base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reconcile the implemented backend planning record

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 18:25:40 +00:00
parent 2595a7726d
commit 20b646e005
2 changed files with 45 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/roadmap/03-backend.md
View File

@@ -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).