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

@@ -63,8 +63,9 @@ dependencies remain subject to the existing
No selected-format accessor is required for this migration. The native
invocation reporter handles the main result on stdout; the existing writer API
handles the separate report using fixed JSON. The upstream accessor proposal
remains optional API work, independent of Scriptorium's adoption.
handles the separate report with automatic or explicitly selected rendering.
The upstream accessor proposal remains optional API work, independent of
Scriptorium's adoption.
## Target End State
@@ -199,9 +200,9 @@ mapping, not a promise that separate invocations see an immutable snapshot.
### Generation, Reports, And Process Outcomes
Use a CommandKit `Report` whose value is PromptKit's native `RunResult` and whose
text template emits only the resulting artifact content. The template should
emit artifact bytes without presentation decoration. Default/text serves raw
Use a main CommandKit `Report` whose value is PromptKit's native `RunResult` and
whose text template emits only the resulting artifact content. The template
should emit artifact bytes without presentation decoration. Default/text serves raw
artifact consumers; JSON and YAML expose the full native result. The native
structured serialization, including its representation of artifact bytes,
remains upstream-owned. There is no Scriptorium result envelope.
@@ -211,7 +212,14 @@ remains upstream-owned. There is no Scriptorium result envelope.
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
| `--format text` or default | Main result contains only the artifact. |
| `--format json` or `--format yaml` | Main result contains the native result and metadata. |
| `--report PATH` | Additionally write the native result as JSON through CommandKit's renderer, independently of the main format and destination. |
| `--report PATH` | Additionally write the native result through CommandKit's renderer, independently of the main format and destination. Without `--report-format`, use native automatic rendering. |
| `--report-format text\|yaml\|json` | Explicitly select the separate report's native rendering format. |
The separate report contains the same native `RunResult`, without the main
report's artifact-only text template. Omission of `--report-format` leaves the
format unset so CommandKit decides how to render it. Its current automatic
rendering for structured values is YAML; future upstream default changes flow
through. Scriptorium does not set a default report format.
There is no `--output` or legacy `--out` flag. Callers save the main result by
redirecting stdout in a shell or supplying a file as the subprocess stdout
@@ -234,7 +242,7 @@ invocation-error envelope is part of this migration.
Adopt CommandKit's quiet and verbosity semantics, including rendering and
presentation failures. Console results use the invocation reporter; diagnostics
use its diagnostic channel. An explicit `--report` write is an application
effect rendered as JSON through the writer API and still occurs in quiet mode.
effect rendered through the writer API and still occurs in quiet mode.
Quiet does not cancel generation; it suppresses the main result even when
stdout is redirected, while failure explanations remain visible. Move any
retained generation summary into an appropriate native message category.
@@ -296,8 +304,9 @@ documentation and examples describe the shipped interface. In particular:
collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate
reports expose the native result. Main output uses stdout and native quiet
semantics; the optional JSON report file is written independently of quiet,
with useful failure outcomes and nontransactional delivery.
semantics; the optional report file uses native automatic or explicitly
selected rendering, independently of quiet, with useful failure outcomes and
nontransactional delivery.
- Narratio's linked acceptance scenarios are supported, including useful partial
discovery and discovery before generated artifacts exist.
- Native help, aliases, completion, and explicit smoke testing are available.
@@ -309,8 +318,8 @@ documentation and examples describe the shipped interface. In particular:
reflect the cutover. The CLI migration includes positional prompt selection,
command replacements, literal versus file inputs, repeated mappings, overlay
selection, native endpoint/timeout controls, stdout redirection in place of
output-file flags, content-bearing reports, report availability, quiet
behavior, and changed exit statuses.
output-file flags, content-bearing reports, optional report-format selection,
report availability, quiet behavior, and changed exit statuses.
The [implementation plan](implementation.md) owns task sequencing, concrete
adapter mappings, verification steps, and sprint status. There are no unresolved