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

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

@@ -14,73 +14,39 @@ 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 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.
| Operation | Default report | Available initial formats |
| --- | --- | --- |
| `help` | Text | Text |
| `version` | Text | Text, YAML |
| `config scopes`, `validate`, `sources`, `explain`, `diff` | Text | Text, YAML |
| `config show` | Native YAML | YAML |
| `promptkit list/show` | Text | Text, YAML |
These format choices govern initial configuration and PromptKit reports and
version reporting. Additional families select formats appropriate to their own
resources through their command contracts. Custom handler formats remain
application-owned. Version format selection preserves the selected subject under
[ADR 0004](0004-standard-inspection-surface.md).
Operations with a format choice use `--format text|yaml`. Format names are
lowercase. YAML-only display uses its native writer directly. Help presents its
registered text form. Format validation follows the usage outcome policy in
[ADR 0005](0005-invocation-outcomes.md).
A single-scope `config show` writes the owning library's complete native redacted
YAML. Its output consists of the inspection document itself. The native writer
preserves effective presence, null and container distinctions, stable mapping
order, and sequence order according to its public contract.
`config show --scope all` emits one native document per registered scope in the
order defined by [ADR 0009](0009-configuration-scopes.md): application first,
PromptKit next when registered, followed by additional scopes in identifier order.
Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all`
selection uses the same labeled document form.
order defined by [ADR 0009](0009-configuration-scopes.md). CommandKit supplies
document separators and scope-label comments around native writer output. Each
scope retains its own value namespace and native rendering; the documents can
be decoded individually.
CommandKit writes the separators and comments around the native writer output.
Comments label scopes for operators; document order follows the registered scope
inventory. That framing offers callers an association between documents and
scopes. Each scope retains its own value namespace and native rendering.
The combined stream is an inspection report whose documents can be decoded
individually.
CommandKit checks operation availability for selected scopes before acquisition.
It acquires their views and completes validation required by those provider
contracts before report output begins. A failure returns its diagnostic outcome
before report writing. After writing begins, a writer failure may leave partial
bytes and returns operational failure under ADR 0005.
Other structured reports use operation-specific YAML schemas and selection
metadata. They contain one document and a trailing newline. Native explanation
snapshots retain their safe YAML text and presence/redaction metadata when
projected into structured reports. The CLI reference owns exact schemas and
field names after implementation.
For `config show`, CommandKit checks operation availability for selected scopes
before acquisition. It acquires all selected views and completes validation
required by those provider contracts before report output begins. A failure
returns its diagnostic outcome before report writing. Other inspection operations
define their own output timing. After writing begins, a writer failure may leave
partial bytes and returns operational failure under
[ADR 0005](0005-invocation-outcomes.md).
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.
Additional families select formats appropriate to their resources. Custom handler
formats remain application-owned. The [CLI roadmap](../roadmap/01-cli-plan.md)
tracks per-operation formats, framing syntax, and report shapes; the implemented
CLI reference will own their exact contracts.
## Alternatives considered
@@ -89,20 +55,18 @@ of serialization format.
| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. |
| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. |
| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. |
| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
| Write `config show` documents as each scope is acquired | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. |
## Consequences
Native display preserves owning-library behavior and keeps rendering focused.
Combined inspection requires multi-document YAML consumption and an ordered scope
contract. The comments label documents, and the ordered inventory supports
identification.
contract.
Loading all scopes before output adds preparation time and allows a failure in
one selected scope to prevent combined output. Explicit single-scope inspection
remains available for a narrower view. Writer failures remain visible through
outcomes and may leave partial output.
Loading all selected scopes before `config show` output adds preparation time and
allows a failure in one scope to prevent combined display. Explicit single-scope
display remains available for a narrower view.
Additional structured schemas are compatibility contracts owned by CommandKit.
Native concatenation can use existing writers; semantic comparison separately