diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 4009c9d..f652268 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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). diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index fe96819..a7a7344 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -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