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

Cleaned up documentation language

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 19:36:02 -05:00
parent 84234275eb
commit a722bc1505
11 changed files with 40 additions and 696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/adr/0001-command-dispatch-and-inputs.md
View File

@@ -10,11 +10,12 @@ Accepted.
## Context
Audita, Narratio, Notarius, and Scriptorium repeat configuration inspection,
routing, parsing, help, and error handling. Their command vocabulary and syntax
have diverged. CommandKit aims to provide one implementation of standard
inspection, consistent vocabulary and mechanics, and less application
infrastructure. Application migrations are expected to make breaking changes.
Several downstream consumers of the ConfigKit and PromptKit libraries include
duplicated or near-duplicated code relating to configuration inspection,
routing, parsing, help, and error handling. However, their command vocabulary
and syntax have diverged. CommandKit aims to provide a single, unified CLI
implementation that will reduce duplication, provide consistent vocabulary and
grammar, and reduce the amount of code each individual applicaiton must own.
Applications have genuine domain commands, such as Narratio's `session restore`,
that remain outside the standard suite. Merely forwarding standard families from
@@ -35,11 +36,13 @@ syntax diagnostics, and standard-family handlers and outcomes. Applications own
custom command names, domain meaning, validation, effects, artifacts, and
operational outcomes.
Use namespace/resource-first syntax for the standard suite. The `config` family
and an installed `promptkit` family belong to CommandKit. PromptKit definition
inspection uses the single `promptkit` namespace; root `prompt` and `profile`
names remain available to applications. This provides a clear family ownership
boundary without spreading a namespace across root verbs.
Use namespace-first syntax for the standard suite, which provides a clear
family ownership boundary. The initial release of CommandKit will ship with two
bundled standard command families:
(1) The `config` family provides ConfigKit inspection and validation; and
(2) the `promptkit` family provides PromptKit inspection and utilities.
CommandKit integrates ConfigKit and PromptKit through their supported public
semantics.
CommandKit accepts custom commands outside its reserved standard families and
reports registration errors for attempts to replace standard handlers or add
@@ -49,8 +52,7 @@ selectors and typed overrides for standard operations.
CommandKit accepts caller-supplied context, streams, handlers, and inspection
providers and returns invocation outcomes. It leaves process termination to the
caller. Executable startup, signals, runtime construction, schemas, acquisition,
and domain resolution remain application choices. CommandKit integrates ConfigKit
and PromptKit through their supported public semantics.
and domain resolution remain application choices.
### Explicit registry and capability installation
@@ -159,8 +161,8 @@ resources, with standard meanings preserved for operations that are installed.
| Both full dispatch and embeddable family handlers | Serves established external CLI architectures but adds integration surfaces and maintenance. Add embedding only for a concrete need. |
| Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter would need to describe its separate parsing and help contract. |
| Universal application runtime framework | Could absorb startup and operational services, but expands beyond the demonstrated CLI boundary and domain ownership. |
| Verb-first standard paths | Groups actions but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
| Reserve root `prompt` and `profile` | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
| Verb-first standard paths | Groups actions, but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
| Reserve root `prompt` and `profile` for PromptKit | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
### Registration

23
docs/adr/0002-cobra-backend.md
View File

@@ -15,16 +15,6 @@ generated help, usage diagnostics, and invocation execution. Reimplementing this
generic infrastructure would add work beyond the suite-specific inspection and
consistency behavior that motivates the library.
Cobra and urfave/cli v3 were the finalists. The latter's destination bindings and
duplicate controls offered a close fit for the explicit-input model. The author
strongly preferred Cobra because of its broader adoption. Familiarity and the
availability of contributors who know the framework are useful maintenance
considerations across several related applications.
The selection was based on documentation and API review. Ecosystem adoption is
the selection rationale, not evidence that every backend default is an appropriate
CommandKit contract.
## Decision
Use Cobra with pflag as the sole initial CLI backend. CommandKit translates its
@@ -39,10 +29,6 @@ getters stay within CommandKit's internal adapter. Independent consumer framewor
use remains application-owned. [ADR 0003](0003-public-facade.md) records the
adapter and root-owned public contracts.
Applications retain process lifecycle and domain execution. ConfigKit and
PromptKit retain configuration and inspection semantics. Framework selection
does not transfer those responsibilities to Cobra or CommandKit.
Build fresh backend command/flag state and input storage per invocation. A fresh
command tree constructed from registered definitions is the initial approach.
CommandKit's tree construction uses registered metadata and leaves acquisition
@@ -76,14 +62,7 @@ features do not expand the standard automatically: for example, completion
commands remain deferred unless deliberately selected.
Backend error handling must preserve application outcomes, avoid duplicate
diagnostics, and return control to the application's entry point. Native YAML
inspection and multi-document scope display remain integration work using the
owning libraries. Choosing a framework introduces no JSON report requirement.
Exact dependency versions and attribution are selected when dependencies are
incorporated. Meaningful integration evidence must exercise the real adapter
against selected contracts. A dependency update or replacement can change CLI
behavior even with unchanged Go signatures and is subject to compatibility policy.
diagnostics, and return control to the application's entry point.
The [architecture policy](../policy/architecture.md) owns normative boundaries.
[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input

32
docs/adr/0003-public-facade.md
View File

@@ -10,20 +10,20 @@ Accepted.
## Context
CommandKit needs room to change implementation while consumers retain stable
registration, input, and invocation contracts. Exposing backend assembly or
extension structures would let applications depend on details that maintainers
may later replace.
CommandKit needs room to change its internal implementation details while
consumers retain access to a stable external API. Exposing backend assembly or
extension structures would let applications ossify around implementation
details that maintainers may later decide to replace.
ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types and
delegate through private state and explicit conversion. ConfigKit also translates
upstream YAML parser structures into an independent internal document model.
ReleaseKit has a second facade for a distinct lightweight runtime responsibility;
CommandKit has no corresponding requirement for another public package initially.
ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types
and delegate through private state and explicit conversion. ConfigKit also
translates upstream YAML parser structures into an independent internal document
model.
The Cobra selection is compatible with dependency isolation. Public API
independence needs a genuine contract boundary, and keeping backend structures
out of shared internal representations also makes future replacement easier.
The selection of Cobra as an internal dependency is compatible with this
decision. Public API independence needs a genuine contract boundary, and
keeping backend structures out of shared internal representations also makes
future replacement easier.
## Decision
@@ -46,8 +46,8 @@ values and returned errors must not provide indirect backend-object access.
Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
Public types from integration libraries, such as ConfigKit and PromptKit, may
be selected as deliberate dependencies. Application input types remain application-owned. Go declarations
and GoDoc own exact exported contracts.
be selected as deliberate dependencies. Application input types remain application-owned.
Go declarations and GoDoc own exact exported contracts.
Confine Cobra/pflag types and operations to an internal adapter. Registry logic,
standard handlers, and shared definitions use CommandKit-owned representations.
@@ -61,10 +61,6 @@ backend state per invocation. Introduce narrow internal interfaces where actual
engine/adapter interaction justifies them; exact package names and splits remain
implementation choices.
Use one concrete backend initially. There is no public backend interface, plugin
registry, or requirement for a second implementation. Replacement is a future
maintainer change.
Translate backend-owned syntax failures into CommandKit diagnostics and outcomes.
Preserve useful public identity for application handler errors and cancellation
according to the invocation contract. Explicit conversions must preserve value

4
docs/adr/0004-standard-inspection-surface.md
View File

@@ -10,7 +10,7 @@ Proposed
## Context
CommandKit serves applications with shared configuration and PromptKit inspection
CommandKit serves applications with shared ConfigKit 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.
@@ -21,7 +21,7 @@ decisions are the operator questions the initial standard answers.
## Decision
CommandKit supplies help and version reporting and defines configuration and
CommandKit supplies help and version reporting and defines ConfitKit 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.

12
docs/adr/0007-native-yaml-reports.md
View File

@@ -14,16 +14,15 @@ ConfigKit and PromptKit provide native YAML configuration inspection. Reusing
their writers preserves captured value semantics, ordering, and redaction. YAML
also supports automated consumption of structured reports.
The agreed initial direction is YAML-based structured inspection with JSON
deferred, and separate native documents for `config show --scope all`. The
remaining choices concern report defaults, document framing, and when output
begins relative to configuration loading.
The agreed initial direction is YAML-based structured inspection and separate
native documents for `config show --scope all`. The remaining choices concern
report defaults, document framing, and when output begins relative to
configuration loading.
## Decision
The initial standard uses text for concise operator reports and YAML for
structured consumption. JSON retains deferred status; a future format extension
is evaluated against a concrete consumer need.
structured consumption.
| Operation | Default report | Available initial formats |
| --- | --- | --- |
@@ -78,6 +77,7 @@ Report confidentiality follows the owning libraries' sensitivity classifications
Their safe writers and records supply redacted content. CommandKit preserves
those confidentiality semantics; arbitrary caller content retains the caller's
disclosure policy.
Report delivery uses the supplied streams and the channel policy in ADR 0005.
Configuration path syntax follows ConfigKit's JSON Pointer contract independently
of serialization format.

114
docs/adr/0008-inspection-lifecycle.md
View File

@@ -1,114 +0,0 @@
# ADR 0008: Coordinate inspection through provider-supplied captured views
## Status
Proposed
## Date
2026-10-06
## Context
Operators use inspection to understand effective configuration and definitions.
An owning library's captured view gives values, provenance, and definition
metadata a coherent source. Application callbacks provide acquisition and domain
resolution that CommandKit cannot independently implement or audit.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes lazy registration and
the boundary between library contracts and application guidance. This decision
covers CommandKit's use of loaded views and its invocation-local coordination.
## Decision
### CommandKit behavior
CommandKit invokes the registered provider when an inspection operation needs
its data. Standard handlers consume the provider's captured inspection views
through supported public contracts. Effective display uses final values supplied
by that view; source inventory and explanation use its provenance; definition
operations use its catalogs and resolved targets.
CommandKit coordinates declared dependencies and reuses compatible provider
results within an invocation. It requests each distinct resolved selection once
through that coordination path. Semantic diff requests independently resolved
left and right captures under [ADR 0011](0011-semantic-configuration-diff.md).
Provider-internal loading remains outside this coordination boundary.
`config validate` invokes the registered validation capability for each selected
scope and propagates its result. The PromptKit integration requests its public
configuration-validation operation, whose intended coverage is all configured
definitions. CommandKit uses the upstream operation's documented semantics;
additional upstream capabilities are needed where the public API lacks that
coverage.
CommandKit's inspection handlers acquire views, query them, validate through the
registered capability, and write reports. Model execution, request preparation,
capacity admission, artifact production, and operational preflight are domain
handler responsibilities outside the standard inspection family.
Help, version, and scope discovery use registration metadata independently of
inspection capture. Construction and those metadata operations leave acquisition
callbacks uninvoked.
### Provider contract
An inspection provider supplies views with the semantics required by its declared
operation. For the ConfigKit and PromptKit integrations, CommandKit consumes their
supported public inspection results and native writers. It preserves supplied
presence, resolution, provenance, and confidentiality semantics.
The provider boundary communicates selection identity, declared dependencies,
applicable operations, loading failures, and acquisition diagnostics. Loading and
validation steps are those required to produce the owning API's inspection result.
CommandKit requires the corresponding result contract, while the callback's
internal organization remains application-owned.
Acquisition can read files, environment values, or credentials and can perform
application-selected bootstrap work. CommandKit propagates supplied diagnostics
under [ADR 0005](0005-invocation-outcomes.md) and exposes supplied requirements in
help. Its coordination contract governs its own calls; callbacks retain their own
effects. CommandKit's API offers acquisition and inspection hooks independently
of application runtime construction.
CommandKit integrations adopt upstream capabilities through supported public
APIs. Secret classification and native rendering follow those APIs. New catalog,
comparison, or profile inspection support is an integration dependency for its
respective operation.
### Recommended application practice
Sharing loading and domain-resolution code between inspection and execution is
recommended: equivalent inputs can then produce equivalent effective values and
provenance. Acquisition callbacks are best kept focused on producing those views,
with application work performed by execution handlers.
These recommendations describe useful consumer structure. Applications control
their execution pipeline, callback implementation, credential lifecycle, and
bootstrap policy. CommandKit's decisions govern the hooks it offers and how its
handlers use the results.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Render mutable runtime configuration structs | Gives direct access to application values. Captured provenance, presence, and resolution need additional synchronization. |
| Reparse effective YAML for catalogs and queries | Uses available serialized data. CommandKit assumes upstream schemas and reconstructs definition semantics. |
| Include operational preflight in standard inspection | Adds readiness information. Inspection acquires provider-execution and state-management responsibilities. |
| Prescribe one consumer loading implementation | Encourages equivalent reports and execution. CommandKit has no authority over arbitrary callback or application internals. |
| Promise credential-independent acquisition | Simplifies an operator expectation. Actual upstream and callback loading requirements may require credentials. |
## Consequences
CommandKit reports describe provider-supplied captured state and preserve its
supported semantics. Dependency coordination reduces repeated provider calls
within an invocation. Shared loading is available as integration guidance.
The API needs clear result ownership, callback lifetime, dependency identity,
and diagnostic delivery. Report accuracy depends on the registered provider's
contract. Acquisition requirements and effects remain visible as supplied
integration metadata.
The [scope model](0009-configuration-scopes.md) and
[selection contract](0010-configuration-selection.md) define related target and
input behavior. Application execution remains outside these library decisions.

2
docs/adr/0011-semantic-configuration-diff.md → docs/adr/0008-semantic-configuration-diff.md
View File

@@ -1,4 +1,4 @@
# ADR 0011: Compare semantic snapshots with explicit sensitivity gaps
# ADR 0008: Compare semantic snapshots with explicit sensitivity gaps
## Status

100
docs/adr/0010-configuration-selection.md
View File

@@ -1,100 +0,0 @@
# 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.