Allow native format selection for separate reports

This commit is contained in:
2026-11-20 03:14:07 +00:00
parent fbe7dd56e3
commit 69d2ba7038
3 changed files with 77 additions and 49 deletions

View File

@@ -100,18 +100,20 @@ is application work; deciding what constitutes a PromptKit failure is not.
### Native result reporting and separate report files
Decision recorded 2026-11-19: use a CommandKit `Report` containing PromptKit's
Decision revised 2026-11-19: use a main CommandKit `Report` containing PromptKit's
native `RunResult`, with a text template that emits only generated content.
Default/text output serves artifact consumers; standard JSON/YAML formats expose
the native result and its metadata. This composes existing upstream APIs;
ckprompt does not supply a general generation command or prescribe this template.
Include an optional `--report PATH` flag requiring an explicit file destination.
Omitting it creates no separate report file. When requested, save the native
result as JSON through CommandKit's renderer, using the same representation as
inline JSON reporting. The report file's format is JSON independently of the
main result's `--format`; requesting a report does not change the main result's
representation or destination.
Omitting it creates no separate report file. When requested, pass the native
`RunResult` to CommandKit's renderer without an artifact-only text template.
Optional `--report-format text|yaml|json` selects the native rendering format.
When omitted, leave the format unset and let CommandKit choose; its current
structured-value default is YAML, and future upstream changes flow through.
There is no Scriptorium default or filename-based selection. Report rendering
is independent of the main result's `--format`, representation, and destination.
Failure to write a requested report is a delivery failure and must produce a
nonzero outcome and diagnostic.
@@ -136,7 +138,7 @@ on stderr. Do not retain the old `--out` flag.
`--format` selects the stdout representation independently of redirection:
default/text emits the raw artifact, while JSON/YAML emits the native result
with metadata. The filename does not select the format. `--report PATH` remains
an additional native JSON report, so callers can save the raw artifact and its
an additional native result report, so callers can save the raw artifact and its
report to separate files by redirecting stdout and supplying `--report`.
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
@@ -146,8 +148,8 @@ Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel.
An explicit `--report` write remains an application-owned effect in quiet mode,
using the existing writer API with fixed JSON. Quiet suppresses the main result
even when stdout is redirected; callers wanting that result omit quiet. No
using the existing writer API. Quiet suppresses the main result even when stdout
is redirected; callers wanting that result omit quiet. No
selected-format accessor is needed, so the upstream proposal is no longer a
migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
shared verbosity rules.
@@ -243,8 +245,8 @@ families. The CLI migration does not redesign the HTTP API.
Reuse ckprompt's applicable resource, input, and execution flag bindings.
Preserve native parsing, explicit-value presence, repeated mapping semantics,
and PromptKit's interpretation of request values. Keep application-specific
configuration/source selection, `--report`, server options, and the
whole-operation deadline separate from framework request controls.
configuration/source selection, `--report`/`--report-format`, server options,
and the whole-operation deadline separate from framework request controls.
Enable upstream convenience aliases consistently on applicable commands,
including `run`. Prefer their shorter spellings in user-facing documentation,