4.3 KiB
CommandKit CLI backend implementation
Status: accepted backend; implementation pending.
Date: 2026-10-06.
ADR 0002 owns the Cobra/pflag selection, alternatives, and rationale. ADR 0003 owns the root facade and internal adapter boundary. This roadmap tracks dependency selection, adaptation, and implementation evidence. The CLI plan retains command and grammar proposals; dispatcher work 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
- Select and pin Cobra/pflag versions and record their actual licensing/notices.
- Design the neutral internal definitions required by the public registry and typed-binding API, then implement translation within the adapter boundary.
- Exercise representative standard and application command definitions, including the examples in the dispatcher roadmap, against selected semantics.
- 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. - 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.