105 lines
5.6 KiB
Markdown
105 lines
5.6 KiB
Markdown
# ADR 0006: Apply common command grammar and recommend shared vocabulary
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
CommandKit owns routing, parsing, and help for standard and registered application
|
|
commands. The selected registry and typed-input model supply a shared source for
|
|
syntax metadata. A concrete grammar makes option placement, operands, repetition, and
|
|
help predictable across the application suite. Shared vocabulary also reduces
|
|
the need to remember different verbs for equivalent operations.
|
|
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes namespace-first
|
|
ownership, typed bindings, explicit presence, and fresh invocation inputs.
|
|
The remaining choices concern option placement, operand handling, repetition,
|
|
and discovery behavior across registered commands.
|
|
|
|
## Decision
|
|
|
|
CommandKit's standard grammar and vocabulary are part of the contract for
|
|
CommandKit-owned commands. Its shared dispatcher and binding APIs implement that
|
|
grammar, so application-owned commands registered through those APIs receive the
|
|
same parsing mechanics. Applications retain ownership of their command names,
|
|
operand meanings, and domain behavior.
|
|
|
|
CommandKit's documentation recommends the same grammar and vocabulary for
|
|
application-owned commands, including commands implemented outside its dispatcher.
|
|
Applications are encouraged to use standard verbs such as `help`, `list`, and
|
|
`show` where their operations have the corresponding purposes described in
|
|
[ADR 0004](0004-standard-inspection-surface.md).
|
|
|
|
CommandKit parses options after the complete registered command path. Within the
|
|
selected command, options and declared operands may be interspersed. Operand counts
|
|
and types come from registration; custom operand domain meaning belongs to the
|
|
handler.
|
|
|
|
Standard options use lowercase names with hyphen-separated words and the `--`
|
|
prefix. Value options accept `--name value` and `--name=value`. Boolean options
|
|
accept their documented presence form and explicit values such as `--name=false`.
|
|
The `--` token ends option parsing; subsequent tokens are operands.
|
|
|
|
Registered metadata identifies each flag as singleton or repeatable. A singleton
|
|
accepts one occurrence per invocation. Repetition across either supported spelling
|
|
is a usage error. A repeatable flag accumulates values in invocation order.
|
|
Presence is recorded independently of defaults and values, preserving supplied
|
|
empty strings, false, and zero under the existing typed-input decision.
|
|
|
|
CommandKit validates paths, flag names, conversions, operand counts, and declared
|
|
input combinations through the shared parser. Those failures use the usage
|
|
classification in [ADR 0005](0005-invocation-outcomes.md). Registered domain value
|
|
parsers and handlers receive values through the typed binding contract.
|
|
|
|
Root help is available through `app`, `app help`, `app --help`, and `app -h`.
|
|
Invoking a command group with no registered execution handler displays group help.
|
|
A runnable command follows its registered handler and operand requirements,
|
|
including when it also has subcommands. CommandKit-owned groups such as `config`
|
|
display help on bare invocation. `app help COMMAND ...` and a resolved command's
|
|
`--help` display the same registered help. Required execution operands are checked
|
|
for execution requests; help uses resolved command and flag
|
|
metadata. Invalid paths and flag names receive usage diagnostics.
|
|
|
|
`app version` and the root-only `app --version` shortcut report application version.
|
|
The version command also accepts explicit component selection under
|
|
[ADR 0004](0004-standard-inspection-surface.md).
|
|
Standard configuration operations have declared flag inputs. PromptKit collection
|
|
and definition commands declare their resource and ID operands. The registry
|
|
generates help, including supported formats and selector applicability, from
|
|
those declarations.
|
|
|
|
The internal Cobra/pflag adapter implements this grammar using registered
|
|
metadata and backend parsing mechanisms. Flag values beginning with `-` follow
|
|
their registered type and supported value syntax. Parser adaptation is centralized
|
|
at that boundary, following [ADR 0002](0002-cobra-backend.md).
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Flags before all operands | Gives argument order a simple positional rule. Operators organize values around that rule when assembling commands. |
|
|
| Common flags before or between command-path components | Supports familiar global-option styles. Routing and help need rules for options across several command levels. |
|
|
| Last singleton occurrence wins | Supports layered argv construction. Repeated assignments become an override mechanism requiring separate presence and precedence interpretation. |
|
|
| Application-selected parser conventions | Supports existing CLI implementations. Operators and shared help need per-application syntax knowledge. |
|
|
|
|
## Consequences
|
|
|
|
Operators learn one option placement and repetition policy for adopting
|
|
commands using CommandKit. Custom handlers retain their operand domain contracts.
|
|
Typed bindings and metadata support consistent parsing and generated help.
|
|
Shared vocabulary guidance encourages consistent names for equivalent
|
|
application-owned operations.
|
|
|
|
The adapter carries the work needed to preserve the grammar across dependency
|
|
updates. Contract evidence must cover repetition, mixed spellings, explicit
|
|
presence, interspersed operands, `--`, help, and fresh state. Backend replacement
|
|
preserves the selected grammar under the release compatibility policy.
|
|
|
|
The CLI reference owns detailed command signatures and examples when implemented.
|
|
This record owns the common rules that apply across those signatures.
|