base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Simplify ADRs and relax premature constraints

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 02:45:09 +00:00
parent 984d159676
commit 7e453a2df2
9 changed files with 165 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/adr/0009-configuration-scopes.md
View File

@@ -15,13 +15,9 @@ 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 future `feedkit`
family can inspect feeds through its own verbs, independently of whether FeedKit
configuration is also exposed as a configuration scope.
[ADR 0004](0004-standard-inspection-surface.md) defines initial operation purposes.
[ADR 0001](0001-command-dispatch-and-inputs.md) records
installation from declared capabilities.
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
@@ -32,16 +28,17 @@ 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. Scope metadata describes
identity, supported operations, applicable selectors, and dependencies.
CommandKit checks the wiring needed by each declared capability. Additional
operations can be supported as their upstream data becomes available.
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.
Expose scope operations through CommandKit-owned public provider contracts.
Adapters preserve supported upstream values, provenance, and confidentiality.
Exact Go declarations remain API design work under
[ADR 0003](0003-public-facade.md). Separate capability contracts allow new
operations to evolve independently of existing provider implementations.
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.
@@ -50,30 +47,14 @@ availability across the requested selection before acquiring views. An unavailab
operation yields a usage diagnostic identifying the scope and available choices,
so an aggregate result accurately describes the requested coverage.
`show`, `sources`, `explain`, and `diff` default to `app`; `validate` defaults to
`all`. Explicit selection remains available for narrower validation. These
selection defaults operate against the registered inventory and capabilities.
`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. The inventory reports identity, description, supported
operations, and selection defaults entirely from metadata. Discovery is available
independently of file loading.
CommandKit validates scope collisions, operation wiring, selector applicability,
and supported selections. It registers the standard operations supplied by at
least one scope, alongside metadata discovery. Help identifies their applicable
scopes; selection of an unsupported scope-operation pair yields a usage diagnostic.
Declared dependencies are coordinated under
[ADR 0008](0008-inspection-lifecycle.md). An inspection operation acquires its
selected scope and required prerequisites through that provider boundary.
A command family defines its own resources, supported verbs, and data contracts.
The configuration provider contract applies to configuration inspection. FeedKit
resource listing or display, for example, can use separate capabilities with
meanings consistent with shared verbs. A library integration can expose a command
family, configuration scope, or both, according to the provided capabilities.
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
@@ -83,9 +64,9 @@ family, configuration scope, or both, according to the provided capabilities.
| 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. |
| Every operation defaults to `app` | Gives one selection default. Integrated validation becomes an explicit aggregate request. |
| 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. |
| Public upstream result types as the provider API | Simplifies direct wiring. CommandKit acquires those type identities and release dependencies. |
| Require CommandKit-owned provider types throughout | Gives a uniform abstraction boundary, but can duplicate upstream APIs and require unnecessary adapters. |
## Consequences
@@ -94,9 +75,6 @@ inventory make operation availability explicit. Individual capabilities can be
integrated before other upstream inspection APIs exist. Default and ordering
rules remain observable CommandKit behavior.
Scoped operations validate availability before loading. An `all` request can
report unsupported coverage; an explicit supported scope remains available.
The same verb purpose can serve different families with different operation sets.
[Selection inputs](0010-configuration-selection.md) define parsing and propagation;
[native YAML reporting](0007-native-yaml-reports.md) defines combined presentation.
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.