v0.10.0: Three-Way Semantic Reconciliation, Full Lifecycle Sync, and the Mission-Control TUI

🚀 Highlights

Protostar v0.10.0 transitions the engine from a one-shot scaffolding tool into a complete, continuous project lifecycle manager. Spanning 261 commits and over 160 merged pull requests, this release delivers a mathematically grounded reconciliation architecture, a fully transactional execution pipeline, and a complete terminal user interface overhaul.

Where v0.9.0 established headless AST planning, v0.10.0 solves long-term project maintenance. With the introduction of protostar sync, status, and diff, projects can now continuously pull upstream template improvements, adopt new quality gates, and upgrade dependency configurations without clobbering local modifications. Backed by deterministic three-way reconciliation across TOML, YAML, JSONC, and line-based text merges, an explicit transactional rollback journal, and a keyboard-first Textual TUI, Protostar now protects your workspace across its entire lifespan.

✨ What's New

🔄 Continuous Project Lifecycle: status, diff, and sync

Protostar is no longer run-once. The new lifecycle command suite tracks your configuration against an authoritative state ledger (protostar.lock) and safely reconciles changes across three directions: the upstream template, your local edits, and the last applied baseline.

• Three-Way Semantic Reconciliation: Merges evaluate changes structurally rather than via brittle text patching. Local customizations are preserved while uncontested template updates apply cleanly.
• Format-Specific AST Adapters:
  • TOML (pyproject.toml, zensical.toml): Powered by tomlkit AST patching. Preserves comments, inline tables, and formatting while enforcing canonical section ordering and handling dotted versus nested key normalization.
  • YAML (.pre-commit-config.yaml, GitHub Actions workflows, .readthedocs.yaml, Codecov): Lossless round-tripping via ruamel.yaml that detects document indentation and style, managing keyed sequences (repositories, hooks, workflow jobs, and steps) by identity.
  • JSONC (.github/renovate.json, .vscode/settings.json): Pure-Python standard library byte-range patcher that preserves comments, key ordering, and trailing commas.
  • In-Process Line-Based Text Merge: Custom diff3 engine implementing patience diff with a bounded difflib fallback for unstructured files (justfile, Dockerfile) and marker-framed append regions (AGENTS.md).
• Content-Addressed Conflict Resolution: Conflicts are assigned deterministic SHA-256 identifiers derived from their base, local, and desired contents. Resolve them headlessly via protostar sync --resolve <id>=<local|desired|both> or interactively in the TUI.
• Declarative Retraction: When a tool or option is disabled, Protostar automatically prunes unedited generated files, removes orphaned dependencies via AST manipulation, and cleans up managed configurations without leaving orphaned hooks or broken CI pipelines.

🛡️ Transactional Execution & Automated Rollback

Scaffolding and synchronization failures no longer leave behind partially written files or corrupted virtual environments.

• The Mutation Journal (MutationJournal): Authoritative ledger recording filesystem node states (ABSENT, REGULAR_FILE, DIRECTORY) prior to the first mutation. On runtime errors or Ctrl+C, rollback restores exact original bytes and POSIX file modes in reverse insertion order. Empty directories created during the run are cleanly unlinked.
• Filesystem Boundary (TransactionAwareFS): All workspace writes, directory creations, and file removals route through a unified abstraction enforcing workspace jail validation and upfront journal recording.
• Process Lifecycle Ownership (ProcessRunner): Managed subprocesses run in isolated process groups (start_new_session=True on POSIX, CREATE_NEW_PROCESS_GROUP on Windows). On timeouts or interrupts, processes receive two-stage termination (SIGTERM escalated to SIGKILL) before filesystem rollback begins.
• Pre-Declared Footprints: Predictable subprocess side effects are owned explicitly. git init declares .git/ as an owned tree, and hook managers pre-journal target script bytes before invocation.
• Fatal Dependency Gating: uv add failures halt execution immediately and trigger automatic rollback of declared dependency files (pyproject.toml, uv.lock).

🎛️ The Mission-Control Terminal Interface (TUI)

Questionary prompts have been completely purged from the codebase. Protostar now boots a full-screen, high-performance terminal UI built on Textual.

• Mission-Control Visual Design: Styled after modern astrophysics consoles with a dark page background (#0a0a0a), deep navy panels, unbroken hairline rules, and cyan (#22d3ee) focus accents.
• Interactive Recipe Editor (protostar init): A single unified form to configure templates, tiers, tools, Docker, and project metadata with a real-time live preview pane updating planned workspace trees and collision states in background workers.
• Pre-Execution Change Review: Review file changes before disk writes occur. Inspect planned file states (new, modified, conflict, existing, after setup), review unified diffs, inspect planned subprocess commands, and select collision strategies.
• Interactive Conflict Resolver: When running protostar sync in an interactive terminal, conflicting updates launch a side-by-side diff review allowing one-key conflict resolution (k keep mine, u take update, b both).
• Keyboard-First Navigation: Strict keyboard ergonomics where navigation never alters state. Navigate via arrows and tabs, inspect contextual help with ?, view tool capabilities with i, save/continue with Ctrl+S, and apply with a.

📦 Template Evolution: Remote Versioning, Migrations & Dual Tiers

Template management now scales cleanly across organizations, upstream updates, and distinct project maturity levels.

• Remote Ref Tracking & Upgrades (sync --to): Remote templates track repository locators and git refs independently. Upstream releases are listed via Git smart HTTP (git-upload-pack) without subprocess overhead, enabling version pinning and upgrades via protostar sync --to <tag|branch|sha>.
• Declarative Migrations ([[migrations]]): Template authors can define forward migrations in TOML blueprints to rename paths, retire obsolete starter files, and rename variables across version bumps without user intervention.
• Typed Template Options: Blueprints can declare typed switches and choices ([options.<name>]) that conditionally gate files, configurations, and dependencies via declarative requires predicates.
• Dual Tiers (Workbench vs. Production): Built-in templates now support two distinct operational tiers:
  • Workbench: Lean, exploratory setup with minimal friction (Ruff, direnv, Just).
  • Production: Full quality and release engineering gate (strict Mypy, Pytest with branch coverage, Prek/pre-commit hooks, CI/CD matrices, Renovate, Codecov, and release workflows).
• Curated Built-In Catalog: Added lib, a first-class Product-tier template for reusable, typed Python packages (Hatchling backend, py.typed marker, PEP 561 compliance). Niche dsp and embedded templates have been retired to external community templates.
• Template Authoring Linter (protostar check-template): Dedicated validation CLI for template authors with support for GitHub Actions workflow annotations (--output-format github).

🧭 Approachable Onboarding & Developer Ergonomics

• protostar guide: On-demand command that inspects the workspace manifest and renders the exact run, test, lint, format, and documentation commands configured for the active project.
• Non-Fatal Missing Tool Architecture: Missing binaries (direnv, just) no longer abort planning or execution. They are recorded as structured data, skipped gracefully during execution, and presented alongside copyable, platform-specific package manager commands.
• Existing Project Enrollment: protostar init analyzes existing repositories to extract Python version constraints, authors, and existing tool configurations without destructive overwrites.
• Managed Community Health (--community): Scaffolds standardized open-source governance files, including CONTRIBUTING.md (kept in sync with active project tools via managed regions), Contributor Covenant 2.1 CODE_OF_CONDUCT.md, SECURITY.md, and GitHub issue/PR templates.
• Secret Scanning Guard: Template variables are validated against vendored Gitleaks rules prior to interpolation, blocking credentials from being committed to project recipes while providing explicit per-variable overrides (--allow-secret).
• Interactive Configuration Editor (protostar config): Interactive TUI form for editing global user settings, Git identity fallbacks, and default tooling preferences.
• Clean Project Ejection (protostar eject): One-step removal of protostar.lock and [tool.protostar] recipe tables, releasing the workspace as an unmanaged vanilla project.

💥 Breaking Changes

• Ownership State Ledger Renamed: .protostar.lock.toml has been renamed to protostar.lock. In accordance with pre-1.0 clean-break policies, legacy checksum-based lock records from v0.9.0 are unsupported; delete existing locks to regenerate under s...

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.

v0.8.0: Python Singularity, Documentation Overhaul, and Engine Hardening

🚀 Highlights

Protostar 0.8.0 is the largest architectural release to date. The project has been streamlined into a dedicated Python environment scaffolding tool, with a cleaner public API, significantly improved documentation, and a more robust execution engine.

This release removes legacy complexity, strengthens reliability, and lays the foundation for faster iteration going forward.

✨ What's New

🐍 Python-first architecture

Protostar is now exclusively focused on Python project initialization.

This release removes the legacy multi-language scaffolding system and the generate command, allowing the CLI and execution engine to become substantially simpler, faster, and easier to maintain.

Highlights include:

• Removed the generate subsystem entirely
• Eliminated language selection and routing logic
• Simplified the interactive wizard
• Reduced CLI complexity and startup overhead
• Cleaner configuration model with fewer obsolete options

📚 Documentation overhaul

Documentation has been rewritten to reflect Protostar's new direction.

Improvements include:

• Comprehensive README refresh
• Python-focused documentation throughout
• Updated contributor onboarding
• Migration from make to just
• Stable ReadTheDocs links
• Improved branding and deterministic SVG rendering

⚙️ Engine hardening

Several internal improvements make Protostar more reliable and easier to extend.

Highlights include:

• Public package API with exported extension interfaces
• Centralized package version handling
• Expanded automated test coverage
• Restored Codecov quality gates
• Improved Python 3.14 compatibility
• Refactored Homebrew release automation into typed Python

💥 Breaking Changes

This release completes Protostar's transition into a dedicated Python scaffolding tool.

The following have been removed:

• protostar generate
• Language selection (--python, --rust, --node, --cpp, --latex)
• Local .protostar.toml configuration
• Non-Python generators and related documentation

v0.7.0: Zensical Docs, Engine Hardening, and Astro Expansion

Summary

This release introduces a massive architectural shift to Protostar's documentation pipeline, moving deep-dives to a dedicated ReadTheDocs deployment. Under the hood, the core execution engine gets heavily hardened with task-level subprocess timeouts, bulletproof SIGINT handling, and strict tooling boundaries. For the computational crowd, the Astro preset gets a serious "batteries-included" upgrade.

New Official Documentation

Head over to the Official Documentation for:

• Command Reference: Full flags and capabilities for init and generate.
• Domain Presets: Matrices for Scientific, Astrophysics, ML, DSP, and Embedded workflows.
• Configuration & Shell Autocomplete: Setting up global defaults, CLI autocompletion, and advanced AST overrides.
• Architecture Mechanics: Deep dives into the Orchestrator, Executor, and Manifest lifecycle.

Core Engine & CLI Mechanics

• Task-Level Timeouts: Subprocess execution is no longer unbounded. Heavy network operations (like uv or pip dependency resolution) are now capped at a 600s timeout, preventing the orchestrator from hanging indefinitely on dropped connections.
• Context-Aware Status Rendering: The TUI now surfaces intelligent, domain-specific status descriptions during the realization phase (e.g., "Installing pre-commit git hooks") instead of dumping raw subprocess arrays to the terminal.
• Strict Tooling Boundaries: Deprecated the hardcoded Python requirement in favor of dynamic language constraints. The CLI and interactive wizard will now actively intercept and block you from scaffolding mismatched toolchains (like trying to drop Ruff onto a Rust-only workspace).
• SIGINT & TTY Routing: Trapped Ctrl+C to fail silently and exit cleanly with POSIX code 130, stopping the CLI from spilling raw stack traces or the argparse help manual upon cancellation. Additionally, hoisted the --force flag logic above the TTY environment check, allowing headless scripts to overwrite collisions without hanging on interactive prompts.
• AST Merging & Determinism: Squashed a tomlkit bug that stacked triple-newlines during deep-merge overwrites, localized IDE interpreter settings strictly to Python module generation, and forced .gitignore payload sorting to eliminate arbitrary diff churn.

Astrophysics & Scientific Stack

• Expanded Astro Preset (-a): The astrophysics footprint now natively bundles the standard scientific computing matrix (numpy, scipy, pandas, matplotlib) alongside astropy, meaning you no longer need to stack the -s and -a flags.
• Automated Notebook Versioning: Automatically installs and configures nbdime (nbdime config-git --enable) during post-install tasks, permanently resolving the Jupyter JSON diff nightmare for research repositories.

Documentation & Assets

• Zensical & ReadTheDocs Migration: Evicted the bloated deep-dive documentation from the README.md and migrated to a custom zensical (Material derivative) framework on ReadTheDocs. Includes a custom Slate dark-mode UI with proper CSS specificity flattening.
• Automated SVG Fixtures: The CLI help matrices are now generated programmatically via rich.console into deterministic SVGs. This process is fully typed, sandboxed, and enforced in CI—if the CLI arguments change but the docs aren't updated, the build fails.
• VHS Integration & Static Branding: Swapped the computationally expensive animated Lorenz attractor scripts for clean, lightweight static SVGs, and introduced vhs tapes for programmatic TUI screen recording.

Build System & CI

• Justfile Optimization: Replaced the legacy Makefile with a justfile. All execution targets now trigger a silent uv sync --all-extras --dev pre-flight check, guaranteeing sub-millisecond dependency determinism.
• Telemetry Parsing: Extracted the inline YAML benchmark script into scripts/parse_benchmarks.py. Hyperfine results for both headless and interactive paths are now properly routed to the GitHub Pages performance dashboard.
• Dependency Trimming: Removed redundant configurations in pyproject.toml and explicitly excluded internal scripts/assets from the Hatch sdist target to keep the PyPI package lean.

v0.6.0: The Architecture & Execution Hardening Update

Summary

This release focuses on deep architectural decoupling, bulletproofing the execution phase, and ensuring the configuration state remains predictable and firmly tracked. We’ve rebuilt the core orchestration engine to cleanly separate state manifestation from disk I/O, hardened the TOML parsers against edge-case mutations, and shifted our benchmarking to capture true out-of-process cold starts.

🏗️ Core Architecture & DAG Lifecycles

• State vs. Execution Split: The monolithic orchestrator has been decoupled. Orchestrator now acts strictly as a state machine for manifest aggregation, while the new SystemExecutor handles all highly-volatile filesystem I/O and subprocess execution.
• DAG Execution Ordering Fix: Resolved a critical execution ordering bug by introducing a post_install_tasks queue. Virtual environment binaries (like pre-commit and direnv) are now strictly guaranteed to execute after the dependency resolution phase completes.
• Dynamic CLI Routing: Extracted abstraction leaks by pushing iteration logic into the PresetModule and BootstrapModule base classes. Tooling modules and presets now evaluate dynamically, meaning future language additions require zero modifications to the core parser.

🛡️ Configuration & Injection Safety

• Runtime Type Validation: The configuration parser now uses typing.get_type_hints to gracefully reject malformed TOML inputs and fall back to safe defaults, entirely avoiding the import overhead of Pydantic.
• Strict Scope Boundaries: Hard-enforced the partition between global initializations and local workspace generation. The orchestrator now actively strips [env], [presets], and [dev] blocks from local .protostar.toml files to prevent configuration drift.
• Deterministic AST Merges: TOML injections now utilize structural parity guards (e.g., ensuring a Table only merges with a Table), and plain-text injections are protected by MD5 payload hashes to ensure idempotency even if users modify the generated logic.
• O(1) Config Loading: Implemented an in-memory class-level cache to eliminate repeated disk I/O when loading configurations across the CLI lifecycle.

📉 Graceful Degradation & Telemetry

• Partial Success States: If a package manager (uv or pip) encounters a fatal error like a network timeout, the orchestrator no longer crashes. It degrades gracefully, trapping the stderr payload and surfacing a PARTIAL SUCCESS warning, preserving the 99% of the environment that was successfully scaffolded.
• Rich OSC 8 Hyperlinks: The crash reporter UI has been upgraded. Massive URL-encoded GitHub issue payloads are now hidden behind clean, clickable terminal hyperlinks.
• Subprocess Security: $EDITOR environment variables are now safely tokenized using shlex.split(), preventing FileNotFoundError crashes for complex arguments (e.g., export EDITOR="code --wait").

🧪 Benchmarking & Test Infrastructure

• True Cold-Start Benchmarks: Migrated from pytest-benchmark to hyperfine. Latency benchmarking now executes entirely out-of-process to capture true Python boot times and CLI initialization overhead, natively integrated into our CI pipeline to gate regressions.
• 95% Test Coverage: Completely overhauled the test suite to execute true E2E subprocesses within tmp_path sandboxes. XDG base directories are now actively isolated during testing to prevent host-machine configuration leakage.
• Strict Local Enforcement: Expanded Ruff linting rules (RUF, N, RET) and configured a hard fail_under = 90 coverage floor for local execution, ensuring high standards before code ever hits the cloud.

v0.5.0: AST-Aware Configuration, Collision Safety, & Rich CLI Overhaul

Summary

This release fundamentally rebuilds Protostar's state evaluation engine to guarantee safe, idempotent execution—especially critical when scaffolding tooling into existing Python data analysis pipelines or complex project topologies. By migrating to a fully AST-aware TOML pipeline and introducing interactive collision mitigation, v0.5.0 ensures existing scripts and workspace configurations remain uncorrupted. The CLI has also been entirely redesigned with rich, utilizing lazy-evaluation proxies to maintain sub-3ms initialization latency.

🛡️ Non-Destructive Collision Safety

• Interactive TUI Intercept: Before executing Phase 4 disk I/O, the orchestrator evaluates the workspace against module-specific collision_markers. If a conflict is detected, execution pauses to prompt for a MERGE, OVERWRITE, or ABORT strategy.
• Strict Headless Boundaries: In non-interactive environments (such as CI/CD pipelines), Protostar now strictly defaults to ABORT to prevent silent data loss. This safety boundary can be explicitly bypassed using the new -f / --force flag.
• Target File Guards: Addressed silent overwrite vulnerabilities. Pre-existing requirements.txt files are now guarded against pip freeze steamrolling, and IDE settings injection safely aborts if VS Code settings.json contains JSONC (comments) that the standard library cannot parse.

⚙️ AST-Exclusive Configuration Engine

• Semantic TOML Merging: Legacy heuristic string-appending has been replaced with tomlkit. Injected configurations are deeply merged directly into the Abstract Syntax Tree (AST), preserving existing formatting, comments, and non-colliding leaf tables (e.g., updating [tool.ruff] without nuking sibling [tool.mypy] blocks).
• Pre-Execution Validation: The orchestrator now utilizes the C-optimized tomllib to validate the syntax of existing workspace files before mutations begin, preventing environment fragmentation caused by attempting to merge into malformed target files.
• Advanced Global Overrides: The ProtostarConfig engine was rewritten using dynamic dataclasses.fields evaluation to support complex nested overrides. You can now inject raw multi-line TOML payloads ([dev.pyproject]), globally map dev dependencies ([dev]), or completely override specific preset dependencies and directories via ~/.config/protostar/config.toml.

🪐 Domain Presets & Astrophysics Refinements

• Refined Astrophysics & Scientific Scaffolding: To better support observational data pipelines, the --astro preset was tightened to focus on core optical and spectral reduction (photutils, specutils). The --scientific preset traded domain-biased modules for foundational numerical and statistical libraries (scikit-learn).
• New Topology Presets: Added --ml for deep learning workflows (configured to strictly ignore heavy serialized weights and telemetry bloat), --api for REST backends, and --cli for terminal applications.

💄 Rich CLI & Performance Telemetry

• Render-Time Lazy Evaluation: Migrated to rich-argparse to output bordered, highly readable subcommand matrices. To protect the sub-3ms fast-path execution latency, rich components are heavily decoupled using LazyTargetHelp and GenerateEpilogTable proxies, deferring string interpolation and AST evaluation until the exact moment of rendering.
• Automated Benchmarking: Deployed a pytest-benchmark suite to GitHub Pages to track fast-path and TUI execution latency, empirically validating Protostar's sub-50ms performance budget and generating dynamic latency-badge.json endpoints.
• Codecov & Renovate: Integrated Codecov for strict branch coverage tracking (decoupled from the fast local make test execution loop) and configured Renovate with a 2-week age gate for low-noise, batched dependency updates.

v0.3.0: Late-Binding Architecture & Deterministic Inception

Summary

This release represents a significant architectural shift in how Protostar handles dependency pipelines and configuration scaffolding. The primary focus is decoupling the tooling layer through a new late-binding architecture, alongside enforcing strict interpreter determinism for uv environments.

Major Changes

Late-Binding Tooling Architecture & Pre-commit Integration

The core PythonModule has been stripped of its hardcoded linters and formatters to prevent toolchain leakage across environments. Tooling is now managed via a late-binding payload broadcast strategy.

• Discrete Tooling Modules: Ruff, Mypy, Pytest, and MarkdownLint are now independent BootstrapModule subclasses. They evaluate their activation state contextually and drop their specific configuration payloads and cache ignores into the EnvironmentManifest.
• Dynamic Pre-Commit Generation: Introduced the --pre-commit flag. Instead of hardcoding a monolithic YAML file, language and tooling modules blindly push their specific pre-commit hooks to the manifest. The new PreCommitModule acts as a gatekeeper, concatenating the payloads and executing git init and pre-commit install during the serialization phase.
• Token Interpolation: The Orchestrator now features an _append_files() phase that evaluates late-binding tokens. For example, it extracts the requires-python string from pyproject.toml to replace {{PYTHON_VERSION}}, and dynamically maps all project dependencies into {{MYPY_DEPENDENCIES}} to ensure strict static typing coverage inside the pre-commit hook.

Interpreter Determinism & Optimized uv Scaffolding

Environment initialization is now strictly deterministic to prevent reproducible build failures across host machines or containerized pipelines.

• Zero-Boilerplate Init: uv init now runs with --bare and --python-pin, completely preventing the generation of deletable boilerplate like hello.py or default README.md files, while dropping a .python-version pin into the workspace.
• Explicit Versioning: You can now explicitly define the target Python version via the --python-version CLI flag or globally in config.toml.
• Dynamic Docker Context: To prevent container-side interpreter resolution conflicts, the orchestrator now dynamically evaluates the system_tasks queue. If uv init was used, it automatically appends the host-bound .python-version file to the .dockerignore.

direnv Context Boundaries & Manifest Injections

To bypass the friction of manually dropping into subshells or sourcing virtual environments, Protostar now supports automatic shell binding.

• Auto-Scaffolding: The --direnv flag (or global config toggle) auto-generates a .envrc file, dynamically routing between uv sync or python3 -m venv depending on your global configuration.
• Fail Loud: Enforces a strict pre-flight check, hard-aborting the scaffolding process if the direnv binary is missing from your $PATH.
• Generalized File Injections: Hardcoded _write_envrc methods were refactored out in favor of a new file_injections dictionary in the EnvironmentManifest, allowing any module to safely queue string payloads mapped to arbitrary file paths.

---

Minor Changes & Under-the-Hood Fixes

• Dependency Segregation: Added dev_dependencies: set[str] to the manifest. The orchestrator now natively segregates installations using uv add --dev (while retaining a unified fallback for pip install + pip freeze).
• Contextual Subprocess Errors: Upgraded run_quiet() in the system layer to catch and parse specific uv subprocess failures. If uv fails due to restrictive global config rules (e.g., python-downloads = "never"), it now raises a highly contextual RuntimeError instead of an ambiguous non-zero exit code.
• Config Inversions: Added support for toggles like no-ruff to cleanly opt-out of default scaffolding behaviors.
• Testing: Expanded pytest coverage using pytest-mock to verify config merging, CLI flag dispatching, regex extraction, and deterministic side-effect generation without polluting the host disk.

v0.2.0: The Polymorphic Update

Summary

This release transitions the Protostar CLI from a procedural, flat-argument script into a fully decoupled, polymorphic architecture. We’ve enforced a strict "manifest-first, side-effects-last" design philosophy. The execution phase is now entirely declarative, preventing I/O side-effects from mutating the global state before the orchestrator is ready to build.

Less time fighting boilerplate, more time actually running the data analysis pipelines.

🚀 Major Highlights

Core Architecture: O(1) Dispatch & Declarative State

We’ve completely rewritten the internal dependency injection and routing mechanisms.

• Modular Subcommands: argparse namespace saturation is gone. We've moved to a standard git-style subcommand architecture (proto init, proto generate).
• TargetGenerator ABC: Imperative scaffolding functions have been modularized into the generators/ package. The orchestrator now uses an O(1) dynamic dictionary dispatch to evaluate targets rather than rigid if/elif blocks.
• Manifest State Separation: The overloaded ignored_paths attribute in EnvironmentManifest is dead. It’s been split into vcs_ignores (for .gitignore) and workspace_hides (for IDE visualization), stopping version control and IDE settings from clobbering each other.
• Cascading Configs: Added an immutable merge cascade for workspace-specific .protostar.toml overrides. You can now override global presets locally without destroying unmentioned keys.

Domain-Specific Pipeline Presets

We've migrated the rigid --scientific flag out of the cli.py monkey-patch and into a dedicated PresetModule registry, bringing three new specialized environments with it:

• --astro: Built for observational and theoretical pipelines. Drops in astropy and gwpy, and scaffolds data/fits/ structures. It's perfectly tuned for crunching final-year thesis data at UVic without having to reinvent the directory wheel.
• --dsp: Scaffolds audio analysis and signal processing pipelines (librosa, mido, data/raw_audio). Ideal for dissecting frequencies when building out mixing tools for the next DnB or garage set.
• --embedded: Preps host-side hardware telemetry (pyserial, esptool).
• --scientific: Now automatically generates a standard analytical tree (data/, notebooks/, src/) and aggressively .gitignores massive binary formats (*.csv, *.parquet, *.nc).

The Generator Engine (proto generate)

The new generate subcommand handles domain-specific boilerplate independently of the global orchestrator lifecycle, ensuring CLI atomicity.

• Hardware & IoT (circuitpython, pio): PlatformIO targets now infer architecture strings natively. The CircuitPython generator drops a non-blocking time.monotonic() state machine by default. This avoids standard time.sleep() bottlenecks when soldering up sensors or custom event lighting rigs.
• C++ (cmake, cpp-class): The cmake generator statically scans the local directory via Python to write .cpp filenames directly into the add_executable directive, officially bypassing the CMake globbing cache anti-pattern.
• LaTeX (tex): Generates modular .tex templates with dynamically cascading preambles (science macros, biblatex) based on your active preset.

🔧 The Fine Print (QoL, Tooling, & Chores)

• Rich TUI & Help System: Replaced the ugly argparse text wrap with a responsive rich.table.Table TUI. Executing proto help generate now dynamically reads registry docstrings and prints a clean, rounded-box grid that respects terminal width.
• POSIX pip Fallback: Added a python_package_manager config option. If uv isn't available, Protostar falls back to standard POSIX pip, dynamically generating .venv and requirements.txt states.
• Docker Context Optimization: The new --docker flag dynamically merges your manifest's vcs_ignores with standard daemon context bloat to generate an optimized .dockerignore.
• POSIX Short Flags: Added single-character shorthands (-p for --python, -r for --rust) for better terminal ergonomics.
• Global XDG Config: proto config automatically resolves ~/.config/protostar/config.toml and spawns a subprocess to open it in $EDITOR.
• Strict Typing & Linting: Enforced Google-style docstrings across the codebase via ruff's D ruleset and added explicit return types to squash all mypy violations.
• Documentation: Shipped a formal CONTRIBUTING.md enforcing the sandboxed disk I/O testing mandates.