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 schema v1.
• Questionary Dependency Removed: All interactive CLI prompts have been replaced by the Textual TUI. The prompt_toolkit and questionary dependencies are completely removed.
• Template Variable Bindings Dropped: The --bind VARIABLE=ENVIRONMENT syntax and [tool.protostar.bindings] recipe tables have been removed. Custom variables are non-secret by contract, set via --var NAME=VALUE, and persisted in [tool.protostar.variables].
• Built-In Template Catalog Changes: The dsp and embedded templates have been removed from the core distribution. Use external templates via --from instead.
• Subprocess Isolation: Subprocesses executed by Protostar now execute with sanitized environments. Caller virtual environments (VIRTUAL_ENV, PYTHONHOME) and repository git pointers (GIT_DIR, GIT_WORK_TREE) are stripped to prevent target directory contamination.
• API Version Bump: The JSON machine interface now emits api_version: 2 with updated review and planning schemas.