Record proposed CLI decisions and clarify CommandKit boundaries
This commit is contained in:
99
docs/adr/0004-standard-inspection-surface.md
Normal file
99
docs/adr/0004-standard-inspection-surface.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# ADR 0004: Define standard inspection operations by family and capability
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
|
||||
## Date
|
||||
|
||||
2026-10-06
|
||||
|
||||
## Context
|
||||
|
||||
CommandKit serves applications with shared configuration and PromptKit inspection
|
||||
needs. A defined operator surface establishes the infrastructure CommandKit
|
||||
provides. Different integrations expose different resources and inspection
|
||||
capabilities, while shared verbs benefit from consistent meanings.
|
||||
|
||||
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes dispatch, registration,
|
||||
capability-based installation, and the boundary of CommandKit policy. The remaining
|
||||
decisions are the operator questions the initial standard answers.
|
||||
|
||||
## Decision
|
||||
|
||||
CommandKit supplies help and version reporting and defines configuration and
|
||||
PromptKit inspection operations. Each family defines its own supported set of
|
||||
operations. Registration installs handlers for the capabilities supplied by the
|
||||
integration and exposes their availability through help and discovery metadata.
|
||||
|
||||
| Standard operation | Responsibility |
|
||||
| --- | --- |
|
||||
| `help` | Describe registered standard and application commands. |
|
||||
| `version` | Report application version by default; report embedded CommandKit version when explicitly selected. |
|
||||
| `config scopes` | List registered configuration scopes and supported operations. |
|
||||
| `config validate` | Validate the selected configuration and its configured definitions. |
|
||||
| `config show` | Display final effective configuration. |
|
||||
| `config sources` | Describe the acquired and synthetic input source inventory. |
|
||||
| `config explain` | Explain effective or historical values and provenance at a selected path. |
|
||||
| `config diff` | Compare effective configuration selections semantically. |
|
||||
|
||||
The optional PromptKit suite supplies `promptkit list prompts`,
|
||||
`promptkit list profiles`, `promptkit show prompt`, and `promptkit show profile`.
|
||||
These operations expose captured definition catalogs, prompt metadata, and
|
||||
backend-completed named execution targets. PromptKit definition capabilities and
|
||||
its configuration scope are registered according to their available provider
|
||||
operations. Either can be integrated independently.
|
||||
|
||||
CommandKit assembles each installed family from its declared capabilities, keeping
|
||||
standard handlers and metadata together. The inventory describes available
|
||||
standard operations; adoption can use the supported subset. Semantic diff depends
|
||||
on safe comparison snapshots for its selected scope. Its availability is
|
||||
independent of display, validation, and other inspection capabilities.
|
||||
|
||||
Shared verbs keep consistent purposes: `list` enumerates resources, `show`
|
||||
displays a selected resource, and `diff` compares supported representations. Each
|
||||
family specializes those purposes for its own resources. For example, a future
|
||||
FeedKit family could supply `list` and `show` as its intended operation set.
|
||||
|
||||
`app version` and root `app --version` report application version. The version
|
||||
command defaults to `--scope app`; `app version --scope commandkit` reports the
|
||||
embedded CommandKit release version. `--format` selects presentation of the same
|
||||
subject. Future component identities can use registered version metadata. Version
|
||||
subjects are independent of configuration scopes and loading providers.
|
||||
|
||||
CommandKit owns vocabulary and observable contracts within its standard families.
|
||||
Custom execution, rendering, serving, sessions, and artifact workflows retain
|
||||
their application-owned meanings. Additional shared operations enter through
|
||||
versioned CommandKit releases under the
|
||||
[release policy](../policy/release.md#versioning-and-compatibility).
|
||||
|
||||
The CLI reference owns exact flags, operands, defaults, and report schemas when
|
||||
implemented. This record owns operation purposes and capability-based availability.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
| Alternative | Analysis |
|
||||
| --- | --- |
|
||||
| Initial operations limited to validation and display | Accelerates first integrations. Source explanation, comparison, and discovery remain repeated application infrastructure. |
|
||||
| Require every operation for every integration | Gives a uniform inventory. One unavailable capability blocks other useful operations and future resource families. |
|
||||
| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. |
|
||||
| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. |
|
||||
| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. |
|
||||
| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. |
|
||||
|
||||
## Consequences
|
||||
|
||||
CommandKit supplies shared handlers with predictable meanings and discovers their
|
||||
availability from registration. Each enabled operation needs its own data
|
||||
contract: comparison needs safe snapshots, catalogs need enumeration, and profile
|
||||
display needs safe execution-target inspection.
|
||||
|
||||
Shared operations retain clear purposes. CommandKit release notes describe changes
|
||||
to its published operations. Coordinated application documentation and caller
|
||||
updates are recommended migration practices.
|
||||
|
||||
Help and discovery describe actual supported capabilities. The
|
||||
[scope model](0009-configuration-scopes.md),
|
||||
[inspection lifecycle](0008-inspection-lifecycle.md), and
|
||||
[comparison policy](0011-semantic-configuration-diff.md) describe the proposed
|
||||
provider and behavioral contracts supporting this surface.
|
||||
Reference in New Issue
Block a user