101 lines
5.3 KiB
Markdown
101 lines
5.3 KiB
Markdown
# ADR 0010: Parse and propagate standardized inspection selection inputs
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
Configuration inspection needs explicit selection inputs and domain context, such
|
|
as Narratio's campaign selectors. Shared flag meanings and presence tracking make
|
|
those inputs understandable. Source discovery, acquisition, and resolution are
|
|
implemented by application integration callbacks.
|
|
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes typed bindings and the
|
|
standard-family extension boundary and limits policy to CommandKit's contracts
|
|
and behavior.
|
|
|
|
## Decision
|
|
|
|
CommandKit parses registered selection inputs, preserves explicit values and
|
|
presence, and passes them to the selected inspection provider. It offers reusable
|
|
bindings so custom execution handlers can receive equivalent selection inputs.
|
|
Provider capture follows [ADR 0008](0008-inspection-lifecycle.md).
|
|
|
|
For integrations based on application configuration, `--config PATH` selects the
|
|
application root, including when targeting its PromptKit engine. CommandKit passes
|
|
that selection and applicable context to the registered provider. `--scope NAME`
|
|
selects the inspected configuration under [ADR 0009](0009-configuration-scopes.md).
|
|
|
|
An explicit empty root path receives a usage error. An explicit relative CLI path
|
|
is interpreted against the invocation working directory. When the selector is
|
|
omitted, CommandKit delegates discovery to the registered acquisition callback.
|
|
It preserves explicit selection and returns source-loading failures from that
|
|
callback as operational failures. CommandKit adds no discovery retry after a
|
|
failed explicit selection. File-relative resource resolution belongs to the
|
|
owning upstream API or provider.
|
|
|
|
The ConfigKit overlay integration uses `--overlay NAME`. Omission, an empty name,
|
|
and the exact name `default` select the base according to ConfigKit semantics;
|
|
other values select a named overlay. This selector describes configuration
|
|
composition. PromptKit execution-profile selection has its own resource identity.
|
|
|
|
Selector registration describes applicable operations and scopes. CommandKit
|
|
exposes supported selectors and validates their applicability before loading.
|
|
Root selection applies to providers using the application root; ConfigKit
|
|
overlay selection applies to providers supporting that composition model.
|
|
Other integrations can declare their own source selectors through the same
|
|
extension mechanism, keeping shared names consistent where applicable.
|
|
|
|
The binding API accepts typed configuration overrides and domain context selectors
|
|
with help, conversion, applicability, and domain-mapping metadata. Parsing
|
|
preserves explicitly supplied empty, false, and zero values, as well as the
|
|
registered type semantics of nullable inputs. Registration detects collisions
|
|
with standard flags. Parsing validates declared combinations and reports usage
|
|
errors under [ADR 0005](0005-invocation-outcomes.md).
|
|
|
|
CommandKit propagates supplied discovery descriptions, environment requirements,
|
|
and defaults-only behavior into help. The provider implements those conventions.
|
|
The API passes typed override and context values to integration callbacks; field
|
|
mapping and recorded domain resolution are outside CommandKit's implementation.
|
|
PromptKit definition operations use the applicable selectors registered for their
|
|
provider and target the engine's definition-inspection capabilities.
|
|
|
|
### Recommended application practice
|
|
|
|
Sharing discovery, acquisition, and domain-resolution code between inspection and
|
|
execution helps equivalent inputs produce equivalent effective values. Reusing
|
|
these bindings and using ConfigKit's recorded override and resolution mechanisms
|
|
helps preserve provenance. Describing discovery and callback effects in help
|
|
helps operators understand acquisition requirements.
|
|
|
|
These are consumer recommendations. Execution loading, source policies, and
|
|
internal application structure remain application choices. CommandKit's decision
|
|
covers parsing, validation of declared inputs, metadata, and callback propagation.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Require an explicit root for every operation | Gives visible selection. Limits discovered, defaults-only, and independently sourced configurations. |
|
|
| Define a universal filesystem discovery policy | Gives identical locations. Deployment and packaging become library policy. |
|
|
| Require one loading function for every consumer | Encourages inspection/execution parity. Prescribes application internals outside CommandKit's authority. |
|
|
| Offer only root, overlay, and scope selectors | Keeps declarations small. Domain context and additional source models need another entry path. |
|
|
| Generic `--set path=value` overrides | Supports arbitrary edits. Requires another value language, conversion contract, and discovery model. |
|
|
|
|
## Consequences
|
|
|
|
CommandKit supplies consistent input mechanics and extension points. Provider
|
|
metadata determines selector relevance, allowing future source models to fit
|
|
without implementing ConfigKit-specific composition. Callbacks receive enough
|
|
selection information to produce useful captured inspection results.
|
|
|
|
Shared loading is recommended integration guidance. CommandKit can preserve and
|
|
propagate inputs; parity with actual application execution depends on consumer
|
|
implementation. Exact selectors and field mappings belong to their implemented
|
|
command contracts.
|