Files
commandkit/docs/adr/0002-cobra-backend.md

79 lines
4.2 KiB
Markdown
Raw Permalink Normal View History

# ADR 0002: Use Cobra and pflag as the initial internal CLI backend
## Status
Accepted.
## Date
2026-10-06
## Context
CommandKit's selected dispatcher model needs nested routing, flags and operands,
generated help, usage diagnostics, and invocation execution. Reimplementing this
generic infrastructure would add work beyond the suite-specific inspection and
consistency behavior that motivates the library.
## Decision
Use Cobra with pflag as the sole initial CLI backend. CommandKit translates its
registrations into backend command trees, flag bindings, and execution callbacks.
Reuse their routing, option parsing, help, context, and stream mechanisms and add
adaptation where selected CommandKit semantics require it.
CommandKit retains its own public registration API, typed inputs, standard
families, and observable contracts. Its public registration and handler APIs
use CommandKit-owned definitions and typed inputs. Cobra commands and pflag
getters stay within CommandKit's internal adapter. Independent consumer framework
use remains application-owned. [ADR 0003](0003-public-facade.md) records the
adapter and root-owned public contracts.
Invocations do not inherit parsed values or presence from previous invocations.
Rebuilding the backend command tree and input storage from registered definitions
is the initial implementation strategy; safe reuse remains an implementation
choice. CommandKit's tree construction uses registered metadata and leaves
acquisition callbacks uninvoked. Application startup and callback effects retain
their own lifecycle.
Implement one concrete backend. There is no initial public backend selector or
pluggable framework. A future replacement can change internal implementation
while preserving the public API and selected behavioral contracts.
## Alternatives considered
| Alternative | Advantages | Reason not selected |
| --- | --- | --- |
| urfave/cli v3 | Destination bindings for flags and named operands, presence queries, and duplicate controls fit the chosen input model closely. | Credible alternative; Cobra's broader adoption is the preferred maintenance tradeoff. |
| pflag alone | Established parsing with a smaller integration surface. | Leaves more routing, help integration, and command infrastructure to implement. |
| Kong | Compact typed-struct and tag-driven declarations. | Its main declaration model differs from the explicit-binding API; adaptation reduces its benefit. |
| Standard `flag` alone | Familiar variable binding and custom value parsing. | First-operand stopping requires adaptation for the intended syntax, with more custom command infrastructure. |
| Expose Cobra as the public API | Less adapter code and the full framework surface. | Couples consumers to backend structures and framework-specific configuration. |
| Interchangeable backends immediately | Future integration flexibility. | Adds abstraction and behavior surfaces without a current requirement. |
## Consequences
The framework supplies established generic CLI machinery. CommandKit still owns
registration conflicts, reserved families, typed bindings and presence, standard
help and diagnostics, provider integration, and selected reports and outcomes.
The adapter must accommodate explicit empty/false/zero values, independent parsed
state, selected repetition and operand rules, and help without configuration.
Backend features do not expand the standard automatically: for example,
completion commands remain deferred unless deliberately selected.
Backend error handling must preserve application outcomes, avoid duplicate
2026-10-06 19:36:02 -05:00
diagnostics, and return control to the application's entry point.
The [architecture policy](../policy/architecture.md) owns normative boundaries.
[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input
model.
Reviewed primary references from the selection:
- [Cobra API](https://pkg.go.dev/github.com/spf13/cobra).
- [Cobra command and help guide](https://github.com/spf13/cobra/blob/main/site/content/user_guide.md).
- [Cobra flag bindings](https://cobra.dev/docs/how-to-guides/working-with-flags/).
- [pflag syntax and extension points](https://github.com/spf13/pflag).
- [urfave/cli v3 API](https://pkg.go.dev/github.com/urfave/cli/v3).