diff --git a/docs/roadmap/03-backend.md b/docs/roadmap/03-backend.md index 3fe6daa..71e311d 100644 --- a/docs/roadmap/03-backend.md +++ b/docs/roadmap/03-backend.md @@ -1,88 +1,53 @@ -# CommandKit CLI backend implementation +# CommandKit backend planning record -Status: accepted backend; implementation pending. +Status: initial Cobra/pflag backend implemented. -Date: 2026-10-06. +Original planning: 2026-10-06. Reconciled: 2026-10-07. -[ADR 0002](../adr/0002-cobra-backend.md) owns the Cobra/pflag selection, alternatives, -and rationale. [ADR 0003](../adr/0003-public-facade.md) owns the root facade and -internal adapter boundary. This roadmap tracks dependency selection, adaptation, -and implementation evidence. The [CLI plan](01-cli-plan.md) retains command and -grammar proposals; [dispatcher work](02-dispatch.md) tracks the public input and -invocation API. +## Authority and current owners -## 1. Current status +[ADR 0002](../adr/0002-cobra-backend.md) records the backend selection and rationale; +[ADR 0003](../adr/0003-public-facade.md) records its isolation behind the public +facade. The [architecture policy](../policy/architecture.md) owns boundaries. -Cobra with pflag is selected as the sole initial backend. No module dependency, -adapter, or executable behavior is implemented. Select versions and attribution -when dependencies are incorporated. There is no initial public backend selection -or plugin facility. +Cobra/pflag dependencies, the internal adapter, routing/parsing, generated help, +and invocation integration are implemented. Selected dependency versions belong +in [go.mod](../../go.mod); license and notice entries belong in +[attribution](../oss/attribution.md). The former dependency-selection and +adapter-construction tasks are complete. -## 2. Adapter work +Current mechanics belong in the [internal overview](../internal/overview.md), +with adapter contracts and implementation in +[internal/cobra](../../internal/cobra/parse.go). The root owns registration, +typed input preparation, invocation coordination, standard handlers, and reports. +The [CLI reference](../cli.md) owns observable syntax and presentation. -### Typed inputs and fresh state +## Completed adaptation and evidence -Translate CommandKit's explicit bindings into backend flag bindings and operand -assignments. Create a fresh backend command tree and fresh input storage for each -invocation from registered definitions. Construction must not load configuration, -resolve credentials, or create execution dependencies. +The initial implementation translated registered metadata through a neutral +bridge, rebuilt backend state for each invocation, and adapted backend routing, +local flags, operands, presence, help, and syntax failures to selected semantics. +The [completed plan](implementation.md) records these stages and their checks. -### Presence and repetition +The earlier discussion of rejecting repeated singletons was superseded by the +accepted last-occurrence rule in [ADR 0006](../adr/0006-command-grammar.md). +Detailed conversion, repetition, and terminator behavior belongs in +[registered command syntax](../cli.md#registered-command-syntax). -Record CLI presence independently of parsed defaults, preserving explicit empty, -false, and zero values. Transfer presence into the typed fields selected by each -command; handlers must not need backend flag lookups. +The delivered integrations expose native ConfigKit/PromptKit reports through the +root, as recorded in the [feature target](initial.md). Backend selection creates +no parallel configuration engine or public backend-specific provider contract. +Completed parsing/help, provider integration, attribution, and evidence tasks +have been retired from this roadmap. -Resolve repetition and grammar choices before enforcing them. The CLI plan's -singleton-repetition rejection is still a proposal. If selected, enforce it -explicitly using registered metadata while preserving ordered accumulation for -repeatable inputs. Exercise interspersed flags, values beginning with `-`, and -`--` against the selected contract; avoid application-maintained flag-name lists. +## Future maintenance and adoption -### Help and command discovery +A later backend replacement remains a maintenance possibility governed by the +accepted public/CLI boundary and [release policy](../policy/release.md). A second +backend or generalized selection framework is outside the initial delivery. -Generate help from one registry's metadata for standard and application commands, -using backend machinery with the selected CommandKit presentation. Keep help and -version usable without configuration or runtime construction. - -Configure automatic backend behavior to match the chosen inventory. Backend -completion support does not itself add a standard completion command. Parent and -family help, unknown-command handling, operands, and leaf help need explicit -contract choices rather than incidental defaults. - -### Diagnostics and outcomes - -Use backend context and stream support. Translate backend-owned syntax failures -into CommandKit diagnostics/outcomes and avoid duplicate emission. Preserve the -selected distinctions among usage errors, valid-invocation failures, and custom -application outcomes. Do not match domain error strings or print usage for every -runtime failure. Return control to the application for process termination. - -### Provider integration and native reports - -Install selected standard families from supplied providers and acquire their data -lazily. Scope dependencies and native YAML rendering remain CommandKit integration -work through ConfigKit/PromptKit public inspection APIs. - -Implement accepted `config show --scope all` using native writers and the YAML -stream contract in the CLI plan. Preserve the initial JSON deferral. A parser -backend creates no need for another configuration loader or public backend-specific -provider types. - -## 3. Delivery sequence and evidence - -1. Select and pin Cobra/pflag versions and record their actual licensing/notices. -2. Design the neutral internal definitions required by the public registry and - typed-binding API, then implement translation within the adapter boundary. -3. Exercise representative standard and application command definitions, including - the examples in the dispatcher roadmap, against selected semantics. -4. Introduce meaningful integration evidence for conflicts, nested routing, help - with invalid configuration, repetition, presence, `--`, fresh state, context - and streams, failed writers, and application outcomes. Adapt defaults as needed - without treating that work as grounds to reopen the accepted selection. -5. Integrate standard handlers and coordinate breaking application adoption under - the CLI delivery plan. Update consumer docs and subprocess adapters. - -The testing policy owns check selection; the architecture policy owns boundaries. -The ADR owns the backend-selection rationale and reviewed primary references. -No second backend or generalized backend framework is a prerequisite. +Application migrations and updates to their documentation/subprocess consumers +remain separate work. They can use the [consumer guide](../consumers/guide.md) +and maintained examples; this record does not claim migration completion. +Other deferred capabilities remain in the +[feature roadmap](initial.md#explicit-deferrals). diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index ef2111c..c203a91 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -90,15 +90,17 @@ Owner: [02-dispatch.md](02-dispatch.md). Owner: [03-backend.md](03-backend.md). -- [ ] Remove claims that the module dependencies, adapter, and invocation behavior +- [x] Remove claims that the module dependencies, adapter, and invocation behavior are unimplemented. Link dependency facts to [go.mod](../../go.mod) and notices to [attribution](../oss/attribution.md). -- [ ] Remove the unresolved singleton-rejection discussion and reconcile it with +- [x] Remove the unresolved singleton-rejection discussion and reconcile it with accepted repetition semantics. -- [ ] Retire completed version-selection, translation, parsing/help, integration, +- [x] Retire completed version-selection, translation, parsing/help, integration, and evidence tasks. Link current behavior to its owners; retain backend replacement and consumer adoption only as future work where applicable. +**Completion:** Recorded the implemented backend, retired completed adaptation tasks, and replaced singleton-rejection proposals with canonical references. + ## D-04: reconcile facade planning Owner: [04-facade.md](04-facade.md).