134 lines
8.9 KiB
Markdown
134 lines
8.9 KiB
Markdown
# CommandKit CLI planning record
|
|
|
|
Status: initial CLI planning complete; remaining proposals deferred.
|
|
|
|
Original review: 2026-10-06. Reconciled: 2026-10-07.
|
|
|
|
## Purpose and current owners
|
|
|
|
This document preserves the initial command-suite review and identifies remaining
|
|
future work. Its completed implementation tasks and obsolete contract drafts
|
|
have been retired. The [initial feature target](initial.md) and
|
|
[completed implementation plan](implementation.md) record delivery scope and
|
|
execution history.
|
|
|
|
The [CLI reference](../cli.md) owns implemented commands, syntax, formats, and
|
|
outcomes. Go declarations and GoDoc own exact exported APIs; the
|
|
[consumer guide](../consumers/guide.md) explains integration. Accepted ADRs own
|
|
architectural rationale, and the [architecture policy](../policy/architecture.md)
|
|
owns responsibility boundaries. This planning record does not define a second
|
|
current command contract.
|
|
|
|
## Completed initial scope
|
|
|
|
| Planning area | Delivered boundary and current reference |
|
|
| --- | --- |
|
|
| Discovery and identity | Generated [help](../cli.md#help) and [version reporting](../cli.md#version). |
|
|
| Configuration inspection | [Scope discovery](../cli.md#configuration-scopes), validation, native display including aggregate display, sources, and path explanation. |
|
|
| PromptKit integration | Engine configuration scope and optional [named prompt/profile inspection](../cli.md#promptkit-definition-inspection), registered independently. |
|
|
| Common command infrastructure | Instance registry, typed inputs, presence, routing, and outcomes; see the [consumer guide](../consumers/guide.md) and [internal overview](../internal/overview.md). |
|
|
|
|
CommandKit owns its standard families. Applications retain custom commands,
|
|
source selection, schema/domain work, acquisition callbacks, and executable
|
|
lifecycle. Migration of existing applications remains separate work; the
|
|
maintained [simple](../../examples/simple/README.md) and
|
|
[composed](../../examples/composed/README.md) consumers demonstrate library usage.
|
|
|
|
## Superseded proposal choices
|
|
|
|
The following entries are historical reconciliation notes. They summarize why
|
|
older drafts no longer describe the selected implementation; use the linked
|
|
owner for the complete current contract.
|
|
|
|
| Earlier proposal, now superseded | Selected result and owner |
|
|
| --- | --- |
|
|
| Bare validation defaults to every scope | Configuration operations default to `app`; aggregate validation/display is explicit. See [configuration scopes](../cli.md#configuration-scopes). |
|
|
| Reject repeated singleton flags | Last occurrence supplies the value; every supplied occurrence is converted. See [registered syntax](../cli.md#registered-command-syntax). |
|
|
| Prompt inspection uses `--prompt-version` | It uses `--version`. See [definition inspection](../cli.md#promptkit-definition-inspection). |
|
|
| Rich profile reports await an upstream provider-parameter redaction API | Current public inspection supplies effective `ExtraParams`, included without additional redaction requirements. See [profile reports](../cli.md#promptkit-definition-inspection). |
|
|
| Fix application root/overlay interpretation in CommandKit, reject empty config values, and derive PromptKit selection from one prescribed root | Values and presence are passed to application callbacks, which interpret them. See [scope integration](../consumers/guide.md#a-configuration-scope) and [selection declarations](../../config.go). |
|
|
| Validation failure always emits no success report | Completed scope records can precede a later failure. See [validation](../cli.md#validate-configuration). |
|
|
| Native display has no format flag | `config show --format yaml` is accepted. See [effective display](../cli.md#show-effective-configuration) for syntax and framing. |
|
|
| Scope inventory includes description/default fields; sources use a prescribed table | The selected report shapes are defined in [scope discovery](../cli.md#configuration-scopes) and [source inventory](../cli.md#list-configuration-sources). |
|
|
| Root `app --version` is a standard entry point | The delivered entry point is `app version`; text can include revision and YAML has explicit identity fields. See [version reporting](../cli.md#version). |
|
|
| Blank definition IDs are usage failures | Missing operands are usage failures; explicitly blank values reach owning inspection and produce operational results. See [definition inspection](../cli.md#promptkit-definition-inspection). |
|
|
| CommandKit automatically coordinates shared loads and dependencies | Applications compose acquisition and may use invocation-local caches. See [consumer integration](../consumers/guide.md) and the composed example. |
|
|
|
|
The selected namespace/resource-first grammar, capability-based family assembly,
|
|
application-focused default version, native aggregate YAML, and initial JSON
|
|
deferral remain reflected in the accepted ADRs and delivered target. The earlier
|
|
alternatives are review history, not unresolved implementation choices.
|
|
|
|
## Deferred work and remaining proposals
|
|
|
|
### `config diff`
|
|
|
|
Semantic comparison is deferred pending supported upstream safe snapshot APIs.
|
|
[ADR 0008](../adr/0008-semantic-configuration-diff.md) owns its accepted comparison
|
|
and sensitivity-gap decisions. The [deferred capability target](initial.md#deferred-capability-targets)
|
|
records dependencies.
|
|
|
|
Exact comparison selection syntax and report layout remain future design work.
|
|
The original proposal considered separate right-side root/overlay selection,
|
|
shared versus independent domain context, and an optional assertion mode. None
|
|
of those flags or modes is installed or promised by the initial implementation.
|
|
CommandKit should use owning public APIs rather than compare rendered YAML or
|
|
implement another configuration engine.
|
|
|
|
### PromptKit catalogs
|
|
|
|
Prompt/profile listing is deferred pending public catalog APIs. Catalog resource
|
|
names and enumeration/report details can be specified when supported APIs exist;
|
|
CommandKit does not enumerate by reparsing PromptKit configuration YAML. See the
|
|
[deferred capability target](initial.md#deferred-capability-targets).
|
|
|
|
### Other proposals outside the initial delivery
|
|
|
|
Configuration mutation, reloadable export, credential diagnostics, live provider
|
|
probes, shell completion, exhaustive field-origin inventories, generic value
|
|
assignment, additional component identity registration, and domain artifact
|
|
catalogs remain outside the initial scope. Their inclusion requires a concrete
|
|
operator purpose and an appropriate ownership/behavior decision. JSON remains
|
|
deferred without a commitment to add it.
|
|
|
|
Execution, rendering, serving, and session operations remain application-owned.
|
|
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md),
|
|
not a reserved implementation contract for every consumer.
|
|
|
|
Application migrations should replace divergent standard paths and update
|
|
subprocess consumers and documentation for intentional breaking changes. The
|
|
original review considered Scriptorium/Notarius followed by Audita/Narratio;
|
|
that ordering is historical evidence, not a completed migration or mandatory
|
|
adoption sequence. Future capabilities can be adopted independently.
|
|
|
|
## Historical review evidence
|
|
|
|
The initial review on 2026-10-06 compared Audita's `print-effective`, Notarius's
|
|
`effective`, and Narratio/Scriptorium's `show`; inconsistent scope/source reports;
|
|
repeated dispatch/loading/report plumbing; and differing help, syntax, and status
|
|
conventions. Those differences informed the shared standard, rather than imposing
|
|
compatibility requirements. Narratio's subprocess interpretation of application
|
|
statuses also demonstrated the need to coordinate consumer adoption.
|
|
|
|
Evidence sources, relative to this roadmap in the sibling workspace checkouts:
|
|
|
|
- [Audita CLI contract](../../../audita/docs/cli.md) and
|
|
[configuration parsing](../../../audita/internal/cli/config_input.go).
|
|
- [Narratio CLI contract](../../../narratio/docs/cli.md),
|
|
[configuration inspection](../../../narratio/internal/app/config_commands.go),
|
|
and [comparison](../../../narratio/internal/app/config_diff.go).
|
|
- [Notarius CLI contract](../../../notarius/docs/cli.md) and
|
|
[configuration commands](../../../notarius/internal/cli/configkit_commands.go).
|
|
- [Scriptorium CLI contract](../../../scriptorium/docs/cli.md),
|
|
[application inspection](../../../scriptorium/internal/adapter/cli/config.go),
|
|
and [framework inspection](../../../scriptorium/internal/adapter/cli/framework_config.go).
|
|
- [ConfigKit inspection API](../../../ConfigKit/inspection.go),
|
|
[source records](../../../ConfigKit/records.go), and
|
|
[configuration contract](../../../ConfigKit/docs/config.md).
|
|
- [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go)
|
|
and [consumer guide](../../../promptkit/docs/consumers/pkg-promptkit.md).
|
|
|
|
These links identify sibling-checkout evidence from that review. They are not
|
|
build dependencies, permanent implementation references, or claims about the
|
|
applications' present adoption status. Current contracts are owned in CommandKit.
|