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

Set initial report designs and lightweight YAML implementation guidance

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 19:00:02 +00:00
parent d15926a878
commit b6a8f1f2cc
2 changed files with 142 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/roadmap/future.md
View File

@@ -55,7 +55,8 @@ These accepted plans do not change the currently implemented behavior.
[Roadmap OD-5](promptkit-v0.19.0.md#od-5-detailed-comparison-selection-and-shape)
selects an optional detailed report while retaining the concise default for
human operators. Both presentations reuse the existing native comparison data;
the detailed layout remains to be designed.
the accepted initial layout is recorded there for implementation and later beta
feedback.
### Configuration inspection extensions
@@ -67,14 +68,18 @@ structured diagnostics belong to `config validate`; the suite retains six
subcommands. The roadmap records the agreed explanation modes and help behavior;
[OD-6](promptkit-v0.19.0.md#od-6-failure-evidence-and-structured-diagnostic-delivery)
selects optional validation details, a concise default, and available evidence
on failure. OD-8 selects focused display, source selection, and report filters;
report shapes and exact filter grammar remain open.
on failure. OD-8 selects focused display, source selection, and report filters.
Initial report formats and filter spellings are selected in the roadmap;
remaining layout details will be evaluated through implementation and beta use.
It also includes focused effective display,
source-ID selection, metadata/diagnostic filters, independent comparison
selectors, and assertion mode. The original four shared proposals had ConfigKit
adoption identifiers OD-3 through OD-6; the new roadmap has its own decision numbering. Implementation
belongs in `ckconfig`, with PromptKit exposing native evidence through its
configuration scope. CLI syntax and report contracts remain subject to review.
configuration scope. The
[initial report implementation approach](promptkit-v0.19.0.md#initial-report-implementation-approach)
favors direct Go-to-YAML serialization, thin projections, and shared output
helpers. Further presentation refinements should follow practical feedback.
Transient acquisition overrides are included as an opt-in loader capability in
[roadmap OD-11](promptkit-v0.19.0.md#od-11-transient-configuration-overrides).

169
docs/roadmap/promptkit-v0.19.0.md
View File

@@ -2,7 +2,9 @@
Status: proposed roadmap for review. Scope is agreed in principle; implementation
has not started. Command spellings, report designs, and API changes below are
recommendations except where explicitly recorded as agreed below.
recommendations except where explicitly recorded as agreed below. Accepted
report formats are an initial implementation target; practical beta feedback
will guide later refinements rather than requiring exhaustive layout design now.
## Purpose and ownership
@@ -27,7 +29,7 @@ The completed v0.18.0 adoption is not reopened.
| Component | Current baseline | Target |
| --- | --- | --- |
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change currently identified. |
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change needed for flag collections or scoped aliases; assess a small shared YAML output helper during implementation. |
| `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Shared CLI inspection extensions and a new appropriate module release. |
| `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | PromptKit v0.19.0 and the ckconfig version delivering the shared work. |
| Candidate | [ckprompt v0.3.0](../../integrations/ckprompt/docs/releases/v0.3.0.md), recorded as unpublished | Update the unpublished candidate after checking its status during implementation. |
@@ -112,8 +114,9 @@ The configuration suite retains six subcommands: `scopes`, `validate`, `show`,
structured diagnostics belong within `config validate`. This command placement
is agreed. OD-4 selects `--list` and `--path` as the explanation modes, with
help on a bare invocation. OD-6 selects `config validate --details` for detailed
diagnostics while retaining concise validation by default. Report shapes and
filter spellings remain proposals under OD-4, OD-6, and OD-8. No separate path inventory
diagnostics while retaining concise validation by default. Initial report
presentation and filter spellings are selected under OD-4, OD-6, and OD-8; exact
Go projections can be refined during implementation. No separate path inventory
or diagnostics subcommand is planned.
Transient configuration overrides are included under OD-11 as an opt-in loader
@@ -294,11 +297,52 @@ PromptKit execution override's complete provider-map replacement. Do not reuse
one grammar implementation in a way that erases that distinction. Source-load
errors remain errors even if an override would replace the affected value.
## Initial report implementation approach
Use the accepted OD-4 through OD-6 flags and formats as a practical starting
point. Keep added code, report types, and translations proportionate. Beta
feedback on actual reports should guide changes; do not delay implementation
for speculative layout options or build a report framework in anticipation of
future formats.
The repository already uses `go.yaml.in/yaml/v4` and small Go-value-to-YAML
writers in core and both integrations. Centralize common encoder configuration
and reusable output helpers where practical. A small shared writer accepting an
`io.Writer` and a Go report value is sufficient; exact placement and exported
API, if needed across module boundaries, are implementation choices. Keep any
core helper independent of ConfigKit and PromptKit types. A separately versioned
output module or custom serialization engine is not needed. Account for module
release/dependency ordering under OD-7 if a shared public core helper is added.
Prefer directly encoding suitable native inspection/report values or a thin Go
projection with serialization tags. Do not mirror a whole upstream object graph
just to rename fields or rearrange equivalent data. Reuse small path, snapshot,
location, and duration projections where they are genuinely needed. Types whose
intended representation depends on JSON tags or custom JSON serialization cannot
be assumed to encode identically under YAML; reuse their supported serialization
or provide a small explicit adapter rather than inventing a reflection framework.
Exceptions serve concrete report semantics: preserving absent/null/false/zero
and empty collections, expressing paths and durations readably, projecting safe
snapshot values, and retaining native redaction. Encode report/inspection values,
not engines, mutable runtime configuration, or request credential storage. Reuse
native writers where their output already serves the selected report. Keep the
existing concise diff and validation presentations; the simpler YAML approach
applies to detailed reports and other suitable projections.
Separate content projection from YAML encoding and from invocation delivery.
Use the existing Reporter and outcome lifecycle for delivery and failures.
Share common helpers without forcing text output through a YAML round trip or
forcing semantically different reports into one schema. Validate representative
reports and meaningful adaptation boundaries, rather than freezing every
incidental formatting detail in tests.
## Work sequence
1. **Resolve the significant CLI choices.** Review the open decisions, record
selections here, and identify affected published reports and flag collisions.
Prepare concrete command/flag/report examples for implementation review.
1. **Confirm remaining implementation choices.** Use the accepted flags and
report formats as the MVP target. Resolve outstanding acquisition/binding
grammar and flag collisions; use concrete examples to review report details
during implementation rather than reopening accepted scope.
2. **Adopt v0.19.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then
[module attribution](../../integrations/ckprompt/docs/oss/attribution.md)
against the released notices and source commit. Update the unpublished
@@ -320,7 +364,8 @@ errors remain errors even if an override would replace the affected value.
metadata/diagnostic filters using those evidence capabilities. Extend typed
comparison selection and add the agreed assertion outcome. Implement explicit
override acquisition and comparison-side wiring under OD-11 as a separate
reviewable unit. Keep boundary coverage with each change.
reviewable unit. Reuse and centralize output helpers under the initial report
implementation approach. Keep boundary coverage with each change.
5. **Update operator and consumer documentation.** The CLI reference owns
syntax, report schemas, availability, and outcomes; GoDoc owns callback and
value contracts. Extend maintained simple/composed examples to demonstrate
@@ -386,6 +431,10 @@ Default tests remain offline and independent of real credentials.
- [ ] Bare `config explain` displays help successfully, presenting `--list` and
`--path` as the two alternatives. Selecting both modes is a usage error;
explicitly supplied `--path ""` selects root explanation rather than help.
- [ ] Discovery uses text by default with YAML available, compact path/presence/
explicitness fields, and the selected `--historical`, `--under`, and
`--explicit` behavior. Historical-only paths and unavailable discovery are not
misreported as current implicit values or an empty configuration.
- [ ] Metadata discovery through `config explain` distinguishes effective and
historical paths, retains available history on absent lookup, and projects
native field/change records.
@@ -394,6 +443,8 @@ Default tests remain offline and independent of real credentials.
snapshots and presence/redaction/hidden-change evidence. Cover additions,
deletions, explicit null, empty comparisons, sequence-level changes, and
report-delivery failures without extra configuration loads or comparisons.
Detailed YAML uses one before/after entry per path and an explicit empty list
when there are no differences.
- [ ] Focused display preserves native snapshot content and distinguishes
missing/historical-only paths from explicit null. Whole-document display
retains its current contract. Focused display uses one scope and native YAML
@@ -414,7 +465,10 @@ Default tests remain offline and independent of real credentials.
selected comparison-side behavior, native errors, and returned provenance
preserved. No tests independently re-establish ConfigKit override semantics.
- [ ] Default validation remains concise; `--details` selects the additional
diagnostic report. Selecting YAML alone does not enable detailed mode.
diagnostic report, with text by default and optional YAML. Selecting YAML
alone does not enable detailed mode. Severity/code filters, evidence
availability, no-match presentation, and known duplicate-warning handling
preserve the underlying validation outcome.
- [ ] `config sources` and `config validate --details` report
available evidence with an acquisition error;
the original failure, unavailable-versus-empty evidence, cancellation, and
@@ -425,6 +479,9 @@ Default tests remain offline and independent of real credentials.
- [ ] Maintained consumer examples demonstrate the selected CLI tasks and the
configuration failure workflow with deterministic local evidence, including
collection reuse by an application-owned command.
- [ ] Suitable reports use direct Go-value serialization or thin projections,
sharing YAML and common output helpers where practical. Necessary adapters
preserve native meaning without a generic report translation framework.
- [ ] Canonical documentation, module release notes, and roadmap links agree
with the implemented boundary. Open decisions are resolved or deliberately
superseded before the corresponding behavior is claimed complete.
@@ -659,13 +716,28 @@ the root explanation, not help. This deliberately replaces the current
missing-path usage error; automatic discovery on a bare invocation is not
selected.
**Remaining presentation recommendations:** list effective paths by default,
offer optional historical selection and subtree/explicitness filters, and
include available field metadata in detailed explanation. Use the current
single-scope model. A compact text discovery report with YAML available for
scripts is recommended. Define report fields, historical/filter spellings,
mode-specific option combinations, and unavailable metadata handling before
implementation; these details remain open.
**Agreed initial presentation:** use a compact text discovery report by default,
with YAML available through `--format yaml`, and one scope at a time. List
current effective paths by default; `--historical` adds historical-only paths
rather than selecting only removed paths. Show path, current/historical-only
presence, and available explicitness. Do not equate non-explicit values with
application defaults or historical-only metadata with explicitness false.
Use `--under POINTER` to narrow listing to a subtree and
`--explicit=true|false` to select current explicitness. Omitting explicitness
filtering includes both states and, when requested, historical-only entries;
historical-only entries do not match either current explicitness value. Apply
subtree filtering to parsed paths, not textual prefixes. These filters and
`--historical` belong to listing mode; `--path` continues to select detailed
explanation, including its available metadata and history.
Keep values and change history out of the compact listing. Include useful field
metadata in detailed explanation without repeating existing evidence. If a
provider cannot supply discovery metadata, report that capability as unavailable
rather than presenting an empty configuration; its existing path-specific
explanation remains usable. These are sufficient starting choices for the MVP;
exact field layout and mode-specific error wording can be decided in code and
reviewed with concrete examples.
### OD-5: Detailed comparison selection and shape
@@ -678,17 +750,29 @@ The detailed mode should help an operator compare old and new values,
distinguish absence from explicit null, and understand concealed changes even
when the displayed safe snapshots look equal. Present native paths, left/right
snapshots, presence, redaction, and hidden-change evidence in readable YAML.
Select and organize the information for those tasks rather than dumping every
upstream field. A record sequence within a scope-labeled envelope remains a
presentation recommendation; exact field names and layout remain open.
**Agreed initial layout:** one entry per changed path in a scope-labeled YAML
report, with before/after snapshots rather than expanded versions of the three
summary categories. Display snapshot values as YAML values, preserving explicit
presence so missing and null remain distinct. Show redaction and concealed-change
annotations where relevant; omission of an optional annotation has a defined
meaning and never relies on recognizing a marker-looking string. Prefer ordinary
Go fields and serialization tags to custom omission logic. An empty comparison
has an explicit empty difference list. YAML is the only initial detailed format.
Keep the projection close to native report values, using the
[shared reporting approach](#initial-report-implementation-approach) rather than
extensive translation for cosmetic layout. Exact field names are implementation
choices for the initial release and can evolve with beta feedback.
Keep implementation localized to flag selection and a second report writer,
with focused boundary tests, help, and examples. The existing `Scope.Compare`
contract and both native adapters already return the required difference
records. Reuse that data and existing safe-snapshot decoding; no new comparison
callback, core API, additional load, or comparison algorithm is required.
A side-by-side terminal display is not part of this adoption. Comparison exit
status remains a separate choice under OD-10.
callback, additional load, or comparison algorithm is required. A shared YAML
output helper may be used, but detailed comparison needs no domain-specific core
API. A side-by-side terminal display is not part of this adoption. Comparison
exit status follows OD-10.
### OD-6: Failure evidence and structured diagnostic delivery
@@ -716,19 +800,31 @@ error. Unlike detailed comparison, the existing adapters need to carry additiona
structured evidence through to reporting. Use current core reporting and outcome
handling; no generic cross-family diagnostics framework is required.
**Remaining presentation recommendations:** provide readable structured YAML,
for example `config validate --details --format yaml`, with native codes,
severities, paths, locations, and a source legend where available. Exact report
layout and format support remain to be designed. Support severity/code filters
under OD-8 without changing the underlying validation outcome. Distinguish
unavailable evidence from an available empty set of findings.
**Agreed initial presentation:** detailed validation uses text by default, with
YAML available through `--format yaml`. Begin text output with scope and outcome,
then show readable findings with their available messages, severities, codes,
configuration paths, and source locations. Place useful locations near messages;
YAML may use a source legend shared by multiple findings.
Use repeatable `--severity` and `--code` filters in detailed mode. Multiple values
within a filter match any selected value; different filters narrow results
together. Filtering never changes the validation outcome. Distinguish no native
findings, no findings matching the filters, and unavailable structured evidence.
Keep referenced sources needed to interpret selected findings.
Avoid presenting a finding both in the detailed report and as a duplicate
ordinary warning when the records have a known relationship. Do not deduplicate
by guessing from message text. Preserve unrelated messages and the terminal
failure explanation. Keep this coordination within the integration rather than
introducing a general diagnostics framework.
Structured results use the result stream and ordinary messages use the
diagnostic stream. Resolve warning duplication and partial-result cancellation
presentation before implementation. Preserve report-delivery failures separately
from the original operation failure through existing outcome handling. Retain
current aggregate stopping behavior; detailed output does not promise exhaustive
validation across all scopes.
diagnostic stream. Preserve report-delivery failures separately from the original
operation failure through existing outcome handling. Retain current aggregate
stopping behavior; detailed output does not promise exhaustive validation across
all scopes. Partial-evidence and cancellation presentation should use the same
simple report values and existing reporting lifecycle, with exact layout refined
during implementation and practical testing.
### OD-7: Module release and interim workspace coordination
@@ -767,9 +863,10 @@ needed to interpret the selected findings. Apply subtree filtering to parsed
paths; distinguish unavailable current metadata on historical-only paths from
an effective value that was not explicitly supplied.
**Remaining design:** exact filter names, values, combination rules, and empty
filtered-result presentation. No additional snapshot-wrapper report or aggregate
path-selected display is selected for this adoption.
**Selected filter grammar:** OD-4 records discovery filters and OD-6 records
diagnostic filters. Exact report field layout and remaining edge-case messages
are implementation choices for the MVP. No additional snapshot-wrapper report
or aggregate path-selected display is selected for this adoption.
### OD-9: Independent comparison selector bindings