v0.9.0: The Agent Interface, Declarative Templates, and Headless Architecture

🚀 Highlights

Protostar v0.9.0 is a massive structural metamorphosis. Built on the foundation of over 100 merged pull requests, this release dismantles the monolithic execution pipeline in favor of a strictly decoupled, headless scaffolding engine.

We have completely purged hardcoded Python preset modules, transitioning to a deterministic, AST-aware TOML templating ecosystem. With the introduction of the new Machine Interface (--json), a zero-latency static hook registry, and a rigorous filesystem security sandbox, Protostar is now built to be driven by both humans and AI coding agents.

✨ What's New

📄 Declarative TOML Templates & Portable Scaffolding

Python-based PresetModule definitions are dead. Protostar now uses 100% valid, JSON Schema-validated .toml blueprints for all environment scaffolding.

• Semantic AST Merging: Replaced brittle string templating with tomlkit-powered AST deep merging. Protostar preserves your existing pyproject.toml comments and formatting while deterministically sorting tables and injecting visual headers.
• The [appends] API: A generalized, extension-aware injection engine that safely injects hash-delimited marker blocks into any file (Python, Rust, HTML, JS) without corrupting syntax.
• Dual-Mode Resolution: The --from flag now accepts remote repository URLs. Protostar natively translates web UI links for GitHub, GitLab, Bitbucket, Codeberg, and Sourcehut, securely extracting .zip and .tar.gz payloads on the fly.
• Global Alias Registry: Register your organization's remote templates in ~/.config/protostar/config.toml under [templates] to invoke them anywhere via --template <alias>.

🤖 The Machine & Agent Interface

Protostar is now fully navigable by automated scripts, CI pipelines, and LLM coding agents.

• Strict stdout Purity: Passing the position-independent --json flag reserves stdout exclusively for machine-readable JSON payloads. All human-readable logging, tracebacks, and spinners are routed to stderr.
• Deterministic Simulation: The new --dry-run flag executes the pure plan() phase, returning a serialized EnvironmentManifest (in JSON mode) or a dashboard summary (in Human mode) detailing exact disk mutations and dependency resolution without touching the disk.
• Schema Exports: The export-schema subcommand dynamically generates the JSON Schema for TOML templates, enabling real-time linting in editors like VS Code.

🧱 The Engine Bulkhead

The engine has been cleaved into two mathematically distinct phases: plan() and execute().

• Headless Planning: The plan() phase is now mathematically pure and side-effect free. It aggregates the EnvironmentManifest domain slices (Dependencies, Filesystem, Tooling, Tasks) without invoking subprocesses or mutating disk state.
• Stateful Execution: The SystemExecutor was dismantled from a 1,400-line monolith into seven highly cohesive, single-responsibility modules (e.g., security.py, toml_ast.py, workflows.py).
• Interactive Decoupling: All UI components (questionary, rich) have been strictly isolated to the CLI presentation layer, preventing the engine from hanging on unexpected interactive prompts in CI.

⚡️ Zero-Latency Static Hook Registry

The slow pre-commit autoupdate network penalty has been eliminated.

• Hook revisions are now resolved via a Fastly-backed asynchronous static JSON registry.
• Hook resolution latency has dropped from several seconds to roughly ~50ms.
• Includes a hardcoded offline fallback dictionary to guarantee zero downtime in air-gapped environments.

🛡️ Security, Error Handling & Resilience

• The Remote Trust Dialog: Executing untrusted external templates containing shell tasks triggers an informed-consent security prompt. External templates registered via your global alias registry bypass this automatically.
• Filesystem Sandbox: Implemented strict Zip/Tar Slip protection during archive extraction and a Path Jail guardrail preventing templates from writing outside the target workspace.
• POSIX-Compliant Telemetry: Domain exceptions (ConfigurationError, NetworkFetchError, etc.) now map directly to standard UNIX exit codes (e.g., EX_CONFIG / 78, EX_TEMPFAIL / 75) and emit deep-linked documentation URLs in the terminal.
• Graceful Interrupts: Hitting Ctrl+C mid-execution now raises a PartialExecutionAbortedError that renders a precise ledger of which files were modified before the interrupt occurred.

🧰 Expanded Tooling Matrix

The scaffolding matrix has been drastically upgraded for modern Python development.

• rumdl Default: Replaced Node-based markdownlint-cli2 with rumdl as the default, hyper-fast Rust-based Markdown linter.
• Docker Multi-Stage: The --docker flag now generates a hardened, multi-stage Dockerfile tailored to the project type (API, Typer CLI, or package) alongside .dockerignore.
• New Integrations: Added native scaffolding modules for commitizen, Astral's ty, Meta's pyrefly, renovate, codecov, and readthedocs.
• Local Toolchain Hooks: Python-based pre-commit hooks (ruff, mypy) now execute locally via uv run repo: local, eliminating redundant virtual environments and version drift.

💥 Breaking Changes

• Python Presets are Dead: The legacy --astro, --api, and --cli preset flags have been removed. Use --template <name> instead.
• Force Flags Split: The ambiguous --force flag has been removed. You must now explicitly declare intent using --force-merge or --force-replace.
• Global Config Updates: The active_presets array is no longer valid in config.toml or protostar.toml.
• Variable Interpolation Syntax: Load-time configuration variables now use the <% VAR %> syntax instead of {{ VAR }} to disambiguate from late-binding execution tokens.
• Python Baseline: The default target Python version has been bumped to 3.13.