diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index f652268..00c97b8 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -36,9 +36,10 @@ The published ckprompt v0.2.0 retains its earlier dependencies; see the ### PromptKit v0.19.0 adoption The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md) owns the proposed adoption, -operator CLI additions for PromptKit and ConfigKit, open decisions, -and completion checklist. Scope is agreed in principle and remains subject to -roadmap review. Implementation has not started. Use released upstream contracts +the agreed shared core report output prerequisite, operator CLI additions for +PromptKit and ConfigKit, open decisions, and completion checklist. Scope is +agreed in principle and remains subject to roadmap review. Implementation has +not started. Use released upstream contracts only; do not inspect or monitor unreleased work in anticipation of adoption. ## Future capability targets @@ -78,8 +79,8 @@ adoption identifiers OD-3 through OD-6; the new roadmap has its own decision num belongs in `ckconfig`, with PromptKit exposing native evidence through its 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. +uses the shared core reporting prerequisite, direct serialization, and thin +projections. 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). @@ -102,10 +103,10 @@ public reusable `ckprompt` collections for standard and application-owned CLI commands, composed through existing core bindings. [Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar) records the agreed canonical naming, scoped convenience aliases, integration -installation collection, and selected text/file input forms; no core extension -is required. Output-contract overrides and appended-message flags are deferred -below. These are CLI features; general-purpose helpers for application-internal -PromptKit use are outside CommandKit's ownership boundary. +installation collection, and selected text/file input forms; those flag and alias +features need no core extension. Output-contract overrides and appended-message +flags are deferred below. These are CLI features; general-purpose helpers for +application-internal PromptKit use are outside CommandKit's ownership boundary. - **Focused backend inspection.** Defer a standard backend detail command until a released PromptKit version provides a suitable public backend @@ -159,6 +160,14 @@ steps. No delivery date or final API is selected here. ### Reporting extensions +The [shared core report output prerequisite](promptkit-v0.19.0.md#shared-core-report-output-prerequisite) +is now part of the working adoption roadmap. It records the agreed command +output declarations, format-independent reporting operation, and centralized +representation rules, initially targeting YAML. Human-oriented/native rendering +and format availability remain open discussions there. Additional renderers such +as JSON, XML, and Markdown remain future work; planning for them does not select +their mappings, command coverage, or delivery dates. + Error-conversion helpers such as `WarnError` remain deferred pending demonstrated value; applications can already use `report.Warn(err.Error())`. Terminal redraw and progress-bar presentation were outside the completed reporting scope and @@ -183,7 +192,8 @@ candidate checks do not become general prohibitions on development workspaces. These capabilities remain outside the delivered scope and require a concrete operator or consumer need and an appropriate ownership/behavior decision: -- JSON reports and output-file management or reloadable export. +- Additional report renderers as described under [reporting extensions](#reporting-extensions), + and output-file management or reloadable export. - Shell completion extensions, including alias discovery described above and dynamic discovery of configured or remote values. - Persistent configuration mutation. Transient CLI overrides are selected under diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index a7a7344..dd0f9df 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -1,4 +1,4 @@ -# PromptKit v0.19.0 adoption and ConfigKit operator CLI +# Shared report output, PromptKit v0.19.0 adoption, and ConfigKit operator CLI Status: proposed roadmap for review. Scope is agreed in principle; implementation has not started. Command spellings, report designs, and API changes below are @@ -10,7 +10,11 @@ will guide later refinements rather than requiring exhaustive layout design now. Adopt released PromptKit v0.19.0 and expose useful operator tasks through standard CommandKit commands, flags, and reports. This roadmap covers CLI -exposure, including ConfigKit v1.1.0 operator features in `ckconfig`. It does not +exposure, including ConfigKit v1.1.0 operator features in `ckconfig`, with a new +public core reporting capability as a prerequisite to the downstream work. +Core standardizes report format selection, representation, rendering, and +delivery for core commands, integrations, and application-owned commands. +Applications and integrations continue to choose report content. This does not turn `ckprompt` into a convenience library for application-internal PromptKit operations. Applications continue to own engine construction, domain inputs, credentials, execution, and their executable lifecycle. @@ -29,9 +33,9 @@ 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 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. | +| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public format-independent report output API, initially targeting YAML, as a prerequisite. Flag collections and scoped aliases still use existing core APIs. | +| `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Adopt the new core reporting API, shared CLI inspection extensions, and an appropriate module release. | +| `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | Adopt the new core reporting API, 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. | | Local workspace | Core and both integrations, Go 1.27.0 | Validate local composition and independent modules separately. | @@ -82,6 +86,10 @@ they do not replace already-delivered explanation or smoke functionality. ## Targeted end state +First establish the [shared core report output capability](#shared-core-report-output-prerequisite). +The integration work below uses that public API instead of adding independent +format-selection and encoding machinery in each module. + The original adoption tasks remain included: 1. Update the dependency, checksums, attribution, and unpublished candidate note. @@ -180,9 +188,9 @@ Use the existing core `CommandSpec[I].Flags`, typed flag constructors, and `Supplied[T]`. A generic collection factory can accept destination accessors and return ordinary `[]commandkit.Flag[I]`. Direct binding is sufficient for ordinary use; existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go) -support deferred application or multiple destinations where needed. No core -change or new core collection abstraction is currently required. Exact exported -names and accessor signatures remain implementation design choices. +support deferred application or multiple destinations where needed. These flag +collections require no core change or new core collection abstraction. Exact +exported names and accessor signatures remain implementation design choices. Keep execution-target overrides and the request-level transient retry field distinct even when one convenient collection includes both. Preserve omission @@ -297,22 +305,109 @@ 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. +## Shared core report output prerequisite + +**Agreed scope:** add a first-class public reporting capability to CommandKit +core before implementing the downstream integration additions. An application +or integration gathers report data and hands it to core; core selects the +default or operator-requested format, renders the report, and delivers it. +Centralize formatting and translation machinery to the greatest practical +extent so commands share output conventions and avoid repeated infrastructure. +Core remains independent of ConfigKit and PromptKit types and domain semantics. + +YAML is the initial structured output target. Design the public entry points +for additional formats, such as JSON, XML, and Markdown, without requiring +handlers to change their reporting call. This selects extensibility now, not +implementation of those additional renderers in this adoption. It supersedes +the earlier suggestion to assess only an optional YAML writer during +implementation. Keep the implementation proportionate; exact public names, +signatures, and internal representation remain design work. + +### Agreed command declarations and format selection + +Declare output behavior once per command, including its default format and +supported alternatives. Core uses that declaration for a standard `--format` +flag, help, input validation, and renderer selection. Omission selects the +declared default; an explicit supported value selects the requested format. +Use one format flag rather than separate `--yaml`, `--json`, or `--xml` flags. +An unsupported selection is a usage error before acquisition or other command +work. Handlers do not repeat this plumbing. + +This establishes the declaration and selection mechanism. How available +renderers become supported alternatives for a particular report remains a +separate open discussion below. + +### Agreed format-independent reporting operation + +Provide one public operation through the invocation Reporter that accepts report +data without requiring a handler to switch on the selected format or configure +an encoder. `invocation.Reporter().Report(report)` illustrates the intended +shape only; it is not a selected signature or an existing API. + +Provide a corresponding writer-based API for rendering outside an invocation. +Both entry points share the rendering implementation. Invocation reporting uses +the existing Reporter lifecycle for visibility, destinations, delivery, and +presentation failures, preserving domain outcomes and causes. This extends the +existing reporting facility rather than creating a second delivery lifecycle. + +### Agreed shared representation rules + +Centralize representation rules as well as encoders. Define how report fields, +field names, omissions, numbers, and custom serialized values become output so +different renderers do not silently give the same report different meanings. +The objective is to prepare a report once and render that representation in +multiple formats, avoiding a separate translation tree per format. + +Use Go report values with small, explicit adaptations where needed. Owned +report values follow shared naming and representation conventions; suitable +upstream values can reuse their established serialization contracts through a +shared adapter. Preserve meaningful distinctions among absent, null, false, +zero, and empty values, and avoid numeric precision loss in intermediate +conversions. Paths, durations, and other values needing a different presentation +can use thin projections. Do not assume JSON tags or custom JSON serialization +automatically have the same meaning to a YAML encoder. + +Exact conventions, serialization-contract selection, and adapter APIs need to be +specified during design. A large public document model or custom reflection +framework is not selected by this decision. + +### Remaining core reporting discussions + +The following topics remain open and must be settled before their corresponding +API contracts are finalized: + +- **Human-oriented presentation (discussion point 4).** Determine how concise + text and richer formats such as Markdown relate to automatic structured + rendering, what shared layout helpers are useful, and where custom or native + renderers fit. Generic tables, field lists, custom-renderer hooks, and a + native-document path are candidates, not accepted API requirements. Preserve + the previously agreed operator reports while deciding their implementation. +- **Format availability (discussion point 5).** Determine how core renderer + availability relates to the formats offered by each command or report, + including whether adding a renderer automatically enables it for suitable + reports or requires explicit adoption. Do not infer that every command must + support every format, or select mandatory per-report opt-in, from the agreed + declaration mechanism alone. XML mapping conventions and cross-format + limitations will need deliberate treatment when those formats are added. + +These discussions do not reopen the agreed declaration mechanism, shared +reporting operation, or centralized representation rules. They also do not +silently expand the YAML-only reports already selected in this roadmap. + ## 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. +feedback on actual reports should guide changes. Resolve the core discussions +above, then implement the agreed extension points without delaying delivery +for exhaustive layout design or speculative additional renderers. 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. +writers in core and both integrations. Consolidate suitable report paths onto +the new core API and share encoder configuration and representation helpers. +Use the capability in core, both integrations, and a maintained application-owned +command example. A separately versioned output module or custom serialization +engine is not needed. Follow module release/dependency ordering under OD-7. Prefer directly encoding suitable native inspection/report values or a thin Go projection with serialization tags. Do not mirror a whole upstream object graph @@ -325,12 +420,13 @@ 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. +not engines, mutable runtime configuration, or request credential storage. +Preserve existing native-document semantics and concise diff and validation +presentations. Their connection to the shared API is part of the open +human-oriented/native-rendering discussion, not a decision to rewrite them as +generic structured dumps. -Separate content projection from YAML encoding and from invocation delivery. +Separate content projection from format rendering 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 @@ -340,23 +436,34 @@ incidental formatting detail in tests. ## Work sequence 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 + report formats as the MVP target. Resolve the two remaining core reporting + discussions and specify the public API and shared representation conventions. + Resolve outstanding acquisition/binding grammar and flag collisions; use + concrete examples to review report details during implementation rather than + reopening accepted scope. +2. **Implement shared core report output.** Deliver the agreed command output + declarations, `--format` selection, format-independent Reporter operation, + writer-based API, and shared representation/encoding machinery, with YAML as + the initial structured target. Exercise the public API with core reporting + and an application-owned command example, and consolidate suitable existing + integration reports onto it. Cover the selected contracts and update their + canonical documentation with the implementation. Complete this prerequisite + before building the downstream additions; use the aligned workspace until + the core release is available under OD-7. +3. **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 candidate note and affected canonical dependency/compatibility guidance. No core Go-minimum increase follows from this adoption. -3. **Implement request inspection and selection.** Add preview, literal-text +4. **Implement request inspection and selection.** Add preview, literal-text input and renamed file-input flags, applicable override flags, provider-parameter input, and namespace selectors. Implement public `ckprompt` execution-flag collections on existing core bindings and reuse them in the standard commands. Generate scoped convenience aliases and provide a collection for installing the commands and routing declarations. Reuse the standard suite's lifecycle and preserve existing application adapter - seams. -4. **Implement shared configuration inspection.** Add discovery and metadata + seams. Render suitable new reports through the shared core API. +5. **Implement shared configuration inspection.** Add discovery and metadata within `config explain`, structured diagnostics via `config validate --details`, detailed diff presentation, and source evidence on failure in `ckconfig`. Retain the six-command suite and wire native PromptKit facets through @@ -364,26 +471,45 @@ incidental formatting detail in tests. 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. Reuse and centralize output helpers under the initial report + reviewable unit. Use the shared core API under the initial report implementation approach. Keep boundary coverage with each change. -5. **Update operator and consumer documentation.** The CLI reference owns +6. **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 the new CLI tasks using local fixtures, without adding application-internal execution helpers. Record intentional compatibility effects in module notes. -6. **Align module dependencies and validate.** Prepare the `ckconfig` release - needed by `ckprompt`, update the latter's dependency/checksums, and complete - the validation below. OD-7 addresses the interim development dependency. +7. **Align module dependencies and validate.** Prepare the core release needed + by both integrations and the `ckconfig` release needed by `ckprompt`. Align + requirements/checksums and complete the validation below. OD-7 addresses + interim workspace development and dependency order. Publication and hosted delivery remain separate actions under the [release procedure](../release.md). ## Validation and completion checklist Select focused boundary tests under the [testing policy](../policy/testing.md). -The checklist concerns adapter/CLI behavior; it does not ask CommandKit to -retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. +The checklist concerns core reporting and adapter/CLI behavior; it does not ask +CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit +resolution algorithms. Default tests remain offline and independent of real credentials. +- [ ] Human-oriented/native rendering and format-availability decisions are + recorded before finalizing their core API contracts. Exact public signatures + and shared representation conventions are documented with implementation. +- [ ] Command output declarations drive defaults, `--format`, help, validation, + and renderer selection. Unsupported selections produce usage failures before + acquisition, and selected formats do not leak between invocations. +- [ ] The invocation and writer-based public APIs share rendering behavior; + handlers submit report data without their own format switches or encoder + setup. Existing quiet-mode, presentation-failure, and domain-outcome behavior + is preserved through the Reporter lifecycle. +- [ ] Representative report values preserve field meanings, selected omission + rules, null/false/zero/empty distinctions, and numeric values. Explicit + upstream serialization adapters honor the selected contract rather than + accidentally applying a different encoder's tag or marshaling rules. +- [ ] Core, both integrations, and a maintained application-owned command + exercise the public reporting capability. Suitable duplicate selection and + encoding code is removed; core has no optional integration dependencies. - [ ] Dependency, checksums, attribution commit links, and candidate notes match the final selected module versions. - [ ] All three compatibility changes and corrected credential wording are @@ -480,8 +606,8 @@ Default tests remain offline and independent of real credentials. 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. + sharing the core representation and rendering machinery. Necessary adapters + preserve native meaning without duplicating a full report tree per format. - [ ] 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. @@ -512,9 +638,13 @@ Focused backend inspection remains in [future work](future.md#promptkit-inspecti until a released upstream API supports it. Do not reconstruct backend selection from configuration to deliver it in this roadmap. General execution, prepared handle lifecycle, sessions, and observer convenience APIs remain application -responsibilities. Persistent configuration editing, new live probes, dynamic completion, -JSON report formats, and unrelated deferred proposals are not added by this -roadmap. Transient acquisition overrides are included under OD-11. +responsibilities. Persistent configuration editing, new live probes, dynamic +completion, and unrelated deferred proposals are not added by this roadmap. +JSON, XML, and Markdown renderers remain future additions; the +[shared core API](#shared-core-report-output-prerequisite) now explicitly plans +for format extensibility. Renderer availability policy remains open, and this +roadmap does not promise those formats for every report. +Transient acquisition overrides are included under OD-11. Output-contract override and appended-message flags are deferred under OD-2 and retained in [future work](future.md#promptkit-inspection-and-selection-extensions). @@ -593,10 +723,10 @@ positional prompt ID retain that argument; this naming decision does not add a r resource-selection, and request-input collections may remain separately composable. Namespace controls remain subject to OD-3. -**Agreed assembly approach:** keep alias generation in `ckprompt`; no core -upgrade is required. Define each flag-to-alias relationship once and generate -existing `FlagAliasFor` routing declarations from the flags selected for each -enabled canonical command. Do not maintain a separate hand-written matrix of +**Agreed assembly approach:** keep alias generation in `ckprompt`; alias +assembly requires no core upgrade. Define each flag-to-alias relationship once +and generate existing `FlagAliasFor` routing declarations from the flags selected +for each enabled canonical command. Do not maintain a separate hand-written matrix of all command/flag combinations. Aliases target the original flag binding rather than introducing duplicate bindings. Both spellings retain core parsing, presence, and occurrence-order behavior. @@ -765,12 +895,12 @@ Keep the projection close to native report values, using the 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, +Keep implementation localized to detail selection and a report projection, 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, additional load, or comparison algorithm is required. A shared YAML -output helper may be used, but detailed comparison needs no domain-specific core +callback, additional load, or comparison algorithm is required. Use the shared +core report output capability; 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. @@ -828,19 +958,23 @@ during implementation and practical testing. ### OD-7: Module release and interim workspace coordination -**Agreed:** complete the planned integration work together rather than splitting -out a dependency-only PromptKit release. With no current consumers, an early -compatibility release has no demonstrated benefit. Prepare a new ckconfig minor -release for the shared API/CLI features, then update the still-unpublished -ckprompt candidate to require that released version. Confirm candidate status -and available versions under the release procedure before choosing versions. +**Agreed:** complete the core reporting prerequisite and planned integration work +together rather than splitting out a dependency-only PromptKit release. With no +current consumers, an early compatibility release has no demonstrated benefit. +Prepare the core release supplying the reporting API, then a new ckconfig minor +release for the shared API/CLI features, and update the still-unpublished +ckprompt candidate. Both integrations must require a core version supplying the +new API, and ckprompt must require the ckconfig version supplying the shared +work. Confirm candidate status and available versions under the release +procedure before choosing versions. Use the ignored aligned workspace during joint development. Workspace success -does not establish independent ckprompt correctness with its old ckconfig -requirement. Before final independent validation, pin the released ckconfig -version supplying the APIs and validate both independent modules and the aligned -workspace. Release ckconfig before ckprompt. Publication remains a separate -action requiring authorization; this decision does not authorize publication. +does not establish independent integration correctness with old core or ckconfig +requirements. Before final independent validation, pin released dependency +versions supplying the APIs and validate all three independent modules and the +aligned workspace. Dependency release order is core, ckconfig, then ckprompt. +Publication remains a separate action requiring authorization; this decision +does not authorize publication. ### OD-8: Focused configuration reports and filtering