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

Record universal report formats and optional command defaults

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 19:49:36 +00:00
parent 756954f056
commit ffe568b6f0
2 changed files with 173 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -33,7 +33,7 @@ The completed v0.18.0 adoption is not reopened.
| Component | Current baseline | Target |
| --- | --- | --- |
| 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. |
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public report output API with universal format selection, optional command defaults, and text/YAML/JSON targets, 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. |
@@ -162,11 +162,12 @@ cause identity. Native errors and their categories remain upstream-owned.
### Preview and request flags
Expose preview as `promptkit show prepared PROMPT_ID`, with YAML-only output
initially, through an independently available capability alongside existing
suite callbacks. The native adapter calls `Engine.Prepare` and projects its returned
snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing
typed selection, acquisition diagnostics, and invocation reporting patterns.
Expose preview as `promptkit show prepared PROMPT_ID`, defaulting to YAML and
accepting core's universal format choices, through an independently available
capability alongside existing suite callbacks. The native adapter calls
`Engine.Prepare` and projects its returned snapshot; a preliminary
`ValidateRequest` call is unnecessary. Use existing typed selection, acquisition
diagnostics, and invocation reporting patterns.
Exact callback names and signatures follow the selected CLI design.
Preview performs applicable resource I/O and rendering but no model call.
@@ -315,34 +316,52 @@ 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.
Focus the capability on plain text, YAML, and JSON. YAML remains the first
structured encoding target; text and JSON are near-term targets, with delivery
staging to be settled during implementation planning. XML is removed from
current consideration. Markdown is not selected for this adoption. New core
formats must work with existing commands without handler refactoring or
per-command encoder registration. This supersedes both the optional YAML-helper
proposal and earlier YAML-only report restrictions. Keep 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.
Core owns the universal `--format` flag, its available options, help, input
validation, and renderer selection. Commands do not maintain format allowlists;
adding a renderer and format option in core makes it available to existing
commands automatically. An unknown format is a usage error before acquisition
or other command work. Use one format flag rather than separate format flags.
This establishes the declaration and selection mechanism. How available
renderers become supported alternatives for a particular report remains a
separate open discussion below.
Commands may optionally declare a default output format. Resolve the effective
format in this order:
1. The operator's explicit `--format` choice.
2. The command's declared default, if supplied.
3. CommandKit's centrally chosen default.
An unset command default means "CommandKit chooses," not "plain text." Preserve
that distinction in the public API rather than making the unspecified value an
alias for text. Core can deliberately change its default in a future release;
commands with explicit defaults retain their preference. A command default does
not restrict operator choices or prevent automatic adoption of new formats.
`config show` declares YAML as its default. Plain text is recommended as the
initial core default, but that policy is not yet selected.
### 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.
The application or integration decides what content to report, including which
information appears normally and what is added by `--details`. Core does not
select domain facts, add detail when a format changes, or infer a summary.
Retain the agreed `--details` spelling for the standard commands.
Provide one public operation through the invocation Reporter that accepts the
selected report data and an optional plain-text template, without requiring a
handler to switch on the selected format or configure an encoder. Core renders
both concise and detailed report values. `invocation.Reporter().Report(report)`
illustrates the intended operation 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
@@ -371,34 +390,57 @@ 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
### Agreed plain-text rendering
The following topics remain open and must be settled before their corresponding
API contracts are finalized:
Core provides a default plain-text fallback and accepts an optional template
from the application or integration as part of the report handoff. With a
template, core renders the chosen text arrangement; without one, it renders the
selected report data using its standard fallback. YAML and JSON use the same
selected content and shared representation rules, independently of the text
template. Applications do not supply separate YAML/JSON writers.
- **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.
Recommend a readable hierarchical fallback with named fields, nested values,
and list items. A template can arrange the supplied content as a sentence,
table, or another useful presentation. Core owns template execution, shared
formatting helpers, and delivery errors. Go's `text/template` and reusable
templates declared once are implementation candidates; the template API,
helper set, and exact fallback layout still need design.
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.
This resolves the earlier human-oriented presentation discussion (point 4).
Universal core formats resolve point 5; per-command supported-format lists and
per-format application renderers are not the selected mechanism.
### Remaining core reporting decisions
- **Initial defaults and staging.** Confirm the initial central default
(recommend text), which standard commands pin a default versus inherit core
policy, and whether text/YAML/JSON land together or in successive core units.
`config show` explicitly defaults to YAML; the existing selected text/YAML
presentations are starting targets, not format restrictions.
- **Shared representation contract.** Specify field/tag and custom-marshaling
precedence, omission and scalar rules, supported Go report values, and how
unsupported values are reported. Keep adapters explicit and avoid silent
numeric loss. This concerns report data, not arbitrary runtime objects.
- **Text handoff.** Settle the template API and helper functions, whether
templates receive the original Go value or shared representation, fallback
conventions, and template preparation and failure behavior. Prefer a small
reusable mechanism; applications select content and layout, core renders it.
- **Native documents and multiple results.** Define how native safe YAML
snapshots and ordered multi-scope documents enter the shared representation,
and how multiple documents/results appear in JSON and text. Preserve native
YAML meanings and disclosure rules without silently losing data or exempting
commands from universal format support. Keep format translation in core and
domain evidence selection in the integrations.
Exact public signatures, flag integration/collision handling, and replacement
of existing format plumbing are implementation design tasks. The decisions
above do not reopen content selection, universal formats, or default precedence.
## 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. Resolve the core discussions
feedback on actual reports should guide changes. Resolve the core design details
above, then implement the agreed extension points without delaying delivery
for exhaustive layout design or speculative additional renderers.
@@ -421,10 +463,10 @@ 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.
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.
Preserve native-document semantics and the concise diff and validation content
selections. Integrations prepare those values and any text templates; core owns
rendering. Native-document adaptation is part of the shared representation
design, not an integration-owned alternative formatting pipeline.
Separate content projection from format rendering and from invocation delivery.
Use the existing Reporter and outcome lifecycle for delivery and failures.
@@ -436,15 +478,17 @@ incidental formatting detail in tests.
## Work sequence
1. **Confirm remaining implementation choices.** Use the accepted flags and
report formats as the MVP target. Resolve the two remaining core reporting
discussions and specify the public API and shared representation conventions.
report content and default preferences as the MVP target. Resolve the
remaining core representation, text-template, native-document, and initial
default/staging decisions; specify the public API.
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
defaults, universal `--format` selection, format-independent Reporter
operation, writer-based API, and shared representation/encoding machinery.
Deliver YAML encoding, text fallback/templates, and JSON encoding according
to the selected staging. 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
@@ -493,12 +537,19 @@ 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.
- [ ] Remaining representation, text-template, native-document, and initial
default/staging decisions are recorded. Public signatures and shared
representation conventions are documented with implementation.
- [ ] Core owns universal `--format` options, help, validation, and selection.
Added core formats work with existing commands without refactoring or local
allowlists. Unknown selections fail before acquisition, and selected formats
do not leak between invocations.
- [ ] Explicit operator selection overrides a declared command default, which
overrides core policy. An unspecified default remains distinct from text.
`config show` defaults to YAML without restricting other format choices.
- [ ] Plain text uses the supplied template or core's fallback. Core owns
rendering and errors in both cases. The integration chooses concise/detailed
content; changing format does not implicitly change the selected detail level.
- [ ] 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
@@ -519,7 +570,8 @@ Default tests remain offline and independent of real credentials.
operational outcomes, including the no-report case; no model dispatch is
introduced by CommandKit to handle them.
- [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and
faithfully reports native fields in YAML, the only initial output format.
faithfully reports native fields, defaulting to YAML and accepting universal
format choices.
Help identifies the argument as a prompt ID and explains resource I/O and
rendered content disclosure. Its CLI path makes no model call and does not
create/execute retained prepared handles.
@@ -557,9 +609,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
- [ ] Discovery retains its initial text default preference, with universal
format choices, 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
@@ -573,9 +626,10 @@ Default tests remain offline and independent of real credentials.
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
without a snapshot wrapper; absent effective paths and unknown source IDs
produce clear operational failures.
retains native YAML semantics when that format is selected. Focused display
uses one scope and defaults to the native YAML value without a snapshot
wrapper; other formats use the shared representation. Absent effective paths
and unknown source IDs produce clear operational failures.
- [ ] Source-ID selection works on successful and failed acquisitions. Path,
explicitness, severity, and code filters preserve the selected evidence and
source references without masking the acquisition outcome.
@@ -591,10 +645,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, 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.
diagnostic report, with an initial text default preference and universal
format choices. Changing format 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
@@ -640,10 +694,11 @@ 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, 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.
The [shared core API](#shared-core-report-output-prerequisite) targets text,
YAML, and JSON, with automatic availability of newly added core formats.
XML is removed from current consideration; Markdown is not selected for this
adoption. Exact delivery staging for the three target formats remains to be
settled, rather than retaining JSON as an unrelated deferred proposal.
Transient acquisition overrides are included under OD-11.
Output-contract override and appended-message flags are deferred under OD-2
and retained in
@@ -658,10 +713,19 @@ These decisions concern significant choices within the proposed scope. Resolved
items retain their numbers and record the agreed decision. OD numbers are local
to this roadmap, not the retired adoption documents.
The core ownership, text fallback/template, universal-format, and default
precedence decisions are now agreed above. Their remaining design details are
listed under [remaining core reporting decisions](#remaining-core-reporting-decisions).
Outstanding integration choices are provider JSON decoding in OD-2, namespace
applicability in OD-3, empty comparison collections and binding design in OD-9,
and override grammar/acquisition details in OD-11. Exact helper names and report
layouts otherwise remain ordinary implementation choices, not unresolved scope.
### OD-1: Preview command and report presentation
**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML-only output
initially and the complete relevant `PreparedRun` projection. The argument names
**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML as its default
and the complete relevant `PreparedRun` projection. Universal core format
selection supersedes the earlier YAML-only restriction. The argument names
the prompt to prepare, not a saved prepared object. A single native preparation
supplies both validation and preview evidence.
@@ -672,8 +736,9 @@ calling the model."
Document resource I/O and rendered content disclosure directly in help and CLI
guidance. The report is an inspection snapshot, not a saved execution handle or
a guarantee that later execution uses the same snapshot or succeeds. A separate
text presentation may be considered later; it is outside the initial scope.
a guarantee that later execution uses the same snapshot or succeeds. Core's
text fallback supplies text output without requiring a dedicated preview
template; a specialized template is not required for initial delivery.
### OD-2: Request controls and provider-parameter grammar
@@ -847,8 +912,8 @@ missing-path usage error; automatic discovery on a bare invocation is not
selected.
**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
with alternatives through core's universal `--format`, 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.
@@ -888,7 +953,9 @@ presence so missing and null remain distinct. Show redaction and concealed-chang
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.
has an explicit empty difference list. Retain YAML as the default preference;
universal core formats supersede the earlier YAML-only detailed restriction.
The same selected comparison evidence is handed to core in every format.
Keep the projection close to native report values, using the
[shared reporting approach](#initial-report-implementation-approach) rather than
@@ -915,8 +982,8 @@ mode on `config diff`. Retain concise validation by default, including its
ordinary warning and error reporting. Detailed mode reports available native
diagnostic records and source references alongside the validation result. The
purpose is to help a human operator locate and investigate configuration
problems; it does not introduce new validation rules. Selecting YAML alone does
not implicitly enable the additional detail.
problems; it does not introduce new validation rules. Changing the output format
does not implicitly enable the additional detail.
Preserve available evidence when loading fails: `config validate --details`
reports diagnostic findings and relevant source references, and `config sources`
@@ -931,9 +998,10 @@ structured evidence through to reporting. Use current core reporting and outcome
handling; no generic cross-family diagnostics framework is required.
**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;
alternatives through core's universal `--format`. Supply a text template that
begins with scope and outcome, then shows 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
@@ -984,10 +1052,12 @@ does not authorize publication.
Keep reports unfiltered by default. The purpose is to reduce noise for a human
operator investigating a known part of the configuration.
Focused show emits the selected native effective YAML directly, without a
snapshot wrapper containing presence/redaction/YAML fields. Use the existing
explanation capability to obtain the native snapshot. An absent effective path
or unknown source ID produces a clear operational failure. Explicitly present
`config show` explicitly defaults to YAML. In that format, focused show emits
the selected native effective YAML directly, without a snapshot wrapper
containing presence/redaction/YAML fields. Other core formats render the selected
value through the shared representation; YAML is a default, not a restriction.
Use the existing explanation capability to obtain the native snapshot. An absent
effective path or unknown source ID produces a clear operational failure. Explicitly present
null remains a valid value; historical-only paths are not effective values.
Path-selected display initially uses one scope, while whole-document
`--scope all` remains available.