89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
|
# CommandKit CLI backend implementation
|
||
|
|
|
||
|
|
Status: accepted backend; implementation pending.
|
||
|
|
|
||
|
|
Date: 2026-10-06.
|
||
|
|
|
||
|
|
[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.
|
||
|
|
|
||
|
|
## 1. Current status
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
## 2. Adapter work
|
||
|
|
|
||
|
|
### Typed inputs and fresh state
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### Presence and repetition
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### Help and command discovery
|
||
|
|
|
||
|
|
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.
|