Roadmap: make base-cli a 5/5 professional Python CLI framework

[codeforester]

Goal

Drive base-cli from a promising 0.x lifecycle toolkit to a world-class, broadly adoptable framework for professional Python CLIs.

The product strategy is deliberately not “another parser.” Click remains the parsing/composition layer; base-cli should become the safest, most composable, typed, observable, and operationally complete lifecycle around it.

Success criteria

• Lifecycle cleanup and metadata are correct under success, failure, interruption, and secondary-hook failure.
• Existing Click and Typer applications can adopt the lifecycle incrementally.
• Public extension points are stable, typed, and independent of private implementation types.
• Logging, structured output, plugins, retention, and terminal rendering meet production operational needs.
• Supported Python/OS combinations, installed artifacts, typing, security, and documentation are continuously verified.
• The project publishes clear compatibility/security policies, complete reference applications, and evidence from at least three independent production consumers.

Ordered issue train

P0 — Trustworthy lifecycle and compatibility baseline

• Make lifecycle teardown failure-safe #51 — Make lifecycle teardown failure-safe — merged in fix: make lifecycle teardown failure-safe #73
• Finalize run metadata and normalize every invocation outcome #52 — Finalize run metadata and normalize every invocation outcome — merged in fix: finalize run outcomes and metadata #74
• Unify production and test invocation and restore native Click option syntax #53 — Unify production and test invocation and restore native Click option syntax — merged in fix: unify production and test invocation #75
• Harden sensitive-option redaction and runtime cleanup boundaries #54 — Harden sensitive-option redaction and runtime cleanup boundaries — merged in fix: harden redaction and temp cleanup boundaries #76
• Repair application naming and registration contracts #55 — Repair application naming and registration contracts — merged in fix: repair application registration contracts #77
• Reject missing explicit configuration files #56 — Reject missing explicit configuration files — merged in fix: reject invalid explicit config paths #78

Critical path: #51 → #52 → #53. Security hardening #54 follows #51; #55 and #56 can proceed independently.

P1 — Incremental adoption and typed extensibility

• Attach the lifecycle to existing nested and lazy Click command trees #57 — Attach the lifecycle to existing nested and lazy Click command trees — merged in feat: attach lifecycle to existing Click trees #79
• Make standard lifecycle options independently composable #58 — Make standard lifecycle options independently composable — merged in feat: make lifecycle options independently composable #80
• Publish stable typed runtime, profile, and context extension contracts #59 — Publish stable typed runtime, profile, and context extension contracts — merged in feat: publish stable typed extension contracts (#59) #81
• Provide an optional batteries-included configuration profile #60 — Provide an optional batteries-included configuration profile — merged in feat: add opt-in layered configuration profile (#60) #82
• Publish an official Typer adapter #61 — Publish an official Typer adapter — merged in feat: add optional Typer lifecycle adapter #83

Critical path: #57 depends on #51, #53, and #55. Typed contracts #59 unlock #60 and, with #57/#58, the Typer adapter #61.

P2 — Operational completeness

• Implement atomic run bundles and complete-bundle retention policies #62 — Implement atomic run bundles and complete-bundle retention policies
• Define stable structured-log, JSON output, and JSON error contracts #63 — Define stable structured-log, JSON output, and JSON error contracts — merged in feat: add stable JSON output and logging contracts #84
• Discover extensions through Python entry points #64 — Discover extensions through Python entry points
• Stream delimited output and render terminal-aware tables #65 — Stream delimited output and render terminal-aware tables
• Add opt-in Rich and OpenTelemetry integrations #66 — Add opt-in Rich and OpenTelemetry integrations

Critical path: #52/#54 → #62; #52/#58/#59 → #63 → #65 → #66. Plugin discovery #64 follows #57 and #59.

P3 — Ecosystem trust and adoption

• Establish wheel-first release gates across the supported Python and OS matrix #67 — Establish wheel-first release gates across the supported Python and OS matrix
• Add property, fuzz, concurrency, signal, and performance test suites #68 — Add property, fuzz, concurrency, signal, and performance test suites
• Publish an API stability and deprecation policy #69 — Publish an API stability and deprecation policy
• Publish a security policy and runtime threat model #70 — Publish a security policy and runtime threat model
• Ship complete production-grade reference applications #71 — Ship complete production-grade reference applications
• Validate base-cli with three independent production consumers #72 — Validate base-cli with three independent production consumers

The final adoption proof #72 follows the quality, policy, security, and reference-application work.

Scope coverage

This train covers every item from the 5/5 roadmap: failure-proof lifecycle finalization; terminal metadata; clean error/interrupt handling; redaction and deletion safety; command naming/registration; explicit config validation; production/test parity and native Click syntax; incremental Click and Typer adoption; nested/lazy/plugin commands; composable options; stable typed protocols and generic contexts; an optional standard config profile; atomic run-bundle retention; structured logs and JSON contracts; streaming/terminal output; Rich/OpenTelemetry; full Python/OS and installed-wheel validation; strict quality/security/docs gates; fuzz/concurrency/signal/performance tests; API/security policies; reference applications; and three independent consumers.

Prior work this extends

• Serialize testing.invoke cwd handling and document its process-global contract #11 covered process-CWD serialization, not full production/test invocation parity.
• Prune stale log-retention index entries before enforcing max_log_files #12 fixed stale log-index entries, not complete run-bundle retention.
• Address Claude review findings in base-cli #7, Generalize the remaining base-cli context and configuration API #23, Separate generic command protocol framing from Base record schemas #27, and Remove Base command-prefix normalization from generic command filters #28 delivered earlier correctness and consumer-neutral extraction, not the new lifecycle and public typed extension contracts.
• Define and deliver cross-platform base-cli support for Linux, WSL2, and native Windows #35–Document cross-platform support tiers and release readiness #40 delivered platform paths, privacy/locking behavior, Windows support work, and distribution/WSL documentation. Establish wheel-first release gates across the supported Python and OS matrix #67 extends that foundation into a continuous Python × OS installed-wheel matrix.

Train rules

• Each implementation PR closes one child issue and uses the repository's required issue-backed branch.
• Release-blocking correctness lands before dependent compatibility and adoption work.
• Public API expansion requires contract tests and migration documentation.
• Optional integrations remain optional; the core stays lightweight.