flavorpack 0.0.4.post3

Flavor Pack packaging system implementing Progressive Secure Package Format (PSPF/2025)

🌶️📦 Flavor Pack: Your Yummy Progressive Secure Polyglot Packaging Toolchain

Flavor Pack (flavorpack) is a cross-language packaging system that creates self-contained, portable executables using the Progressive Secure Package Format (PSPF) 2025 Edition. It enables you to ship Python applications as single binaries that "just work" - no installation, no dependencies, no configuration required.

🎯 Key Features

• Single-File Distribution: Package entire applications into one executable file
• Cross-Language Support: Python orchestrator with Go and Rust launchers
• Secure by Default: Ed25519 signature verification ensures package integrity
• Progressive Extraction: Extract only what's needed, when it's needed
• Smart Caching: Persistent work environment with intelligent validation
• Zero Dependencies: End users need nothing pre-installed

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• UV package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Go 1.21+ and Rust 1.75+ (for building ingredients)

Installation

# Clone the repository
git clone https://github.com/provide-io/flavor.git
cd flavor

# Set up environment and install dependencies
source env.sh

# Build the Go and Rust ingredients
./ingredients/build.sh

Creating Your First Package

# Package a Python application
flavor pack --manifest pyproject.toml --output myapp.psp

# Run the packaged application
./myapp.psp

# Verify package integrity
flavor verify myapp.psp

📦 PSPF Format

The Progressive Secure Package Format is a polyglot file format that works as both an OS executable and a structured package:

[Native Launcher] → Go or Rust executable
[8192-byte Index] → Format metadata and offsets
[Metadata] → Gzipped JSON manifest
[Slot Table] → Slot descriptors
[Slots 0..N] → Application code, runtime, dependencies
[📦🪄] → 8-byte emoji magic footer

📚 Documentation

• User Guide - Getting started and creating packages
• Development Guide - Setting up development environment
• Architecture - Technical details and design
• API Reference - Command and format specifications
• Troubleshooting - Common issues and solutions
• Full Documentation Index - Complete documentation structure

🏗️ Architecture

Flavor Pack consists of three main components:

1. Python Orchestrator (src/flavor/)

   • Manages the build process and dependency resolution
   • Creates manifests and handles Python packaging
   • Provides CLI interface for package operations

2. Native Launchers (ingredients/flavor-{go,rs}/)

   • Extract and execute packages at runtime
   • Perform Ed25519 signature verification
   • Manage workenv caching and lifecycle

3. Native Builders (ingredients/flavor-{go,rs}/)

   • Assemble PSPF packages from manifests
   • Implement the PSPF/2025 binary format
   • Handle slot packing and metadata encoding

🔒 Security

Every PSPF package includes cryptographic integrity verification:

• Ed25519 signatures ensure packages haven't been tampered with
• Public keys are embedded in the package index
• Signature verification happens automatically on every launch
• Optional deterministic builds with --key-seed for reproducibility

🧪 Testing

# Run the test suite
workenv/flavor_*/bin/pytest tests/

# Run with coverage
workenv/flavor_*/bin/pytest --cov=src/flavor --cov-report=term-missing

# Test cross-language compatibility
./test-all-combinations.sh

# Run specific test categories
workenv/flavor_*/bin/pytest -m unit        # Fast unit tests
workenv/flavor_*/bin/pytest -m integration # Integration tests
workenv/flavor_*/bin/pytest -m security    # Security tests

# Test ingredients with Taster
cd helpers/taster
../../workenv/flavor_*/bin/flavor pack --manifest pyproject.toml --output taster.psp
./taster.psp --help

🙏 Acknowledgments

Flavor Pack is built on the shoulders of giants:

• UV for fast Python package management
• The Python, Go, and Rust communities for excellent tooling

---

Built with ❤️ by the provide.io team