81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
# ADR 0009: Select named configuration scopes with declared inspection capabilities
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
An application can expose its own configuration, PromptKit engine configuration,
|
|
and other independently meaningful configurations through the `config` family.
|
|
A scope identifies the configuration targeted by an operation. Different
|
|
providers may support different inspection operations.
|
|
|
|
Configuration scopes and command families are distinct. A scope targets
|
|
configuration; a family defines operations on its own resources. A library
|
|
integration can expose either or both.
|
|
|
|
## Decision
|
|
|
|
Use stable semantic scope identifiers. The `app` scope describes application
|
|
configuration; an optional `promptkit` scope describes captured engine
|
|
configuration. Registration also accepts additional independently meaningful
|
|
configuration scopes with unique identifiers.
|
|
|
|
Each scope declares its available inspection operations and their providers.
|
|
Capabilities can include validation, native effective YAML, source inventory,
|
|
path explanation, and safe semantic comparison data. CommandKit validates declared
|
|
wiring and registers operations supplied by at least one scope under
|
|
[ADR 0004](0004-standard-inspection-surface.md). Help and scope discovery report
|
|
actual capabilities from metadata, independently of file loading.
|
|
|
|
Define narrow integration contracts, reusing upstream public types where useful
|
|
and introducing CommandKit-owned abstractions where they simplify integration.
|
|
Preserve supported upstream values, provenance, and confidentiality. Select
|
|
provider representations against concrete integration needs; exact Go declarations
|
|
remain API design work under
|
|
[ADR 0003](0003-public-facade.md).
|
|
|
|
`--scope NAME` selects one configuration. `all` denotes all registered scopes for
|
|
`config validate` and `config show`; `sources`, `explain`, and `diff` select one.
|
|
An aggregate selection retains its all-scope meaning. CommandKit checks operation
|
|
availability across the requested selection before acquiring views. An unavailable
|
|
operation yields a usage diagnostic identifying the scope and available choices,
|
|
so an aggregate result accurately describes the requested coverage.
|
|
|
|
`show`, `sources`, `explain`, `diff`, and `validate` default to `app`. Explicit
|
|
`--scope all` requests aggregate validation or display.
|
|
|
|
Scope order is `app` first when registered, `promptkit` next when registered,
|
|
then additional scopes sorted by identifier. `config scopes` and combined YAML
|
|
show use that order. [ADR 0007](0007-native-yaml-reports.md) defines combined
|
|
presentation. Acquisition coordination and selector details remain design work
|
|
tracked in the [CLI roadmap](../roadmap/01-cli-plan.md).
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Require every configuration inspection operation per scope | Gives one capability set. Missing comparison or provenance blocks other useful inspection operations. |
|
|
| A separate command tree for each configuration | Makes the target part of the path. Repeats common operations and help. |
|
|
| One verb set for every library family | Gives a uniform inventory. Resource domains acquire operations with little useful meaning. |
|
|
| Executable names as scope identifiers | Relates scopes to application branding. Shared scripts need application-specific identifiers. |
|
|
| Validation defaults to `all` | Checks every scope implicitly, but adding a scope without validation support can make bare validation unavailable. |
|
|
| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of `all` become less apparent. |
|
|
| Require CommandKit-owned provider types throughout | Gives a uniform abstraction boundary, but can duplicate upstream APIs and require unnecessary adapters. |
|
|
|
|
## Consequences
|
|
|
|
A shared configuration family serves multiple configurations while help and
|
|
inventory make operation availability explicit. Individual capabilities can be
|
|
integrated before other upstream inspection APIs exist. Default and ordering
|
|
rules remain observable CommandKit behavior.
|
|
|
|
An `all` request can report unsupported coverage; default application inspection
|
|
remains independent of other scopes' capabilities. Provider design must balance
|
|
simple wiring against dependency coupling as concrete integrations are developed.
|