Use stdout redirection for main generation output

This commit is contained in:
2026-11-20 02:16:44 +00:00
parent 99b0ebfc03
commit fbe7dd56e3
3 changed files with 120 additions and 127 deletions

View File

@@ -61,12 +61,10 @@ v0.23.2 minimum does not require a downgrade. Supported public APIs and released
dependencies remain subject to the existing
[architecture policy](../policy/architecture.md).
One approved upstream addition is needed: a released selected-format accessor.
CommandKit v0.7.0 provides a writer-level renderer but no public access to the
invocation's selected format. The accessor enables formatted application-owned
output files, including in quiet mode, without duplicating reporting-flag
parsing. The implementation plan tracks adoption of its released API; the
agreed file-output contract remains the target.
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.
## Target End State
@@ -210,17 +208,21 @@ remains upstream-owned. There is no Scriptorium result envelope.
| Selection | Behavior |
| --- | --- |
| No destination flag | Main result goes to stdout using the selected format. |
| `--output PATH` | Main result goes to that file, without duplicate stdout output. |
| 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. |
Filename extensions do not select formats. The separate report includes the
native result's content as well as metadata; it replaces the CLI's old
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
destination. Diagnostics remain on stderr. Callers wanting main output omit
`--quiet`, including when stdout is redirected. Filename extensions do not
select formats. The separate report includes the native result's content as
well as metadata; it replaces the CLI's old
observer-derived metadata projection. A caller wanting an artifact file plus
metadata can select separate output and report paths. The caller manages paths
and retention; there is no automatic reporting directory or report collection.
metadata redirects stdout and selects a separate `--report` path. The caller
manages redirected destinations and retention; there is no automatic reporting
directory or report collection.
Native result reporting is available when PromptKit returns a result.
Operational errors return nonzero status and native failure diagnostics, without
@@ -231,10 +233,10 @@ 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. Explicit `--output` and `--report` writes are
application effects rendered through the writer API and still occur in quiet
mode. Quiet does not cancel generation; without requested files it suppresses
ordinary result output while failure explanations remain visible. Move any
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.
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.
Map typed upstream failures and configuration diagnostics into native outcomes,
@@ -246,11 +248,13 @@ native presentation-failure behavior where applicable, including an already
nonzero domain outcome. Requested file errors must not disappear merely because
they occur outside the invocation reporter.
Use ordinary file operations: replace files without creating parents, reject
output/report destinations known to name the same file before execution,
attempt the main output followed by the report, and attempt the report even if
main delivery fails. This adds no rollback, transactional delivery, or stronger
filesystem protection. Already delivered output may remain after failure.
For `--report`, use ordinary file replacement without creating parents. Attempt
the main output followed by the report, and attempt the report even if main
delivery fails. Open the report only when a native result exists. Redirection
and its file-creation or truncation behavior belong to the caller. Scriptorium
does not manage the main output file or check it against the report path. This
adds no rollback or transactional delivery; written bytes may remain after
failure.
Wire signal cancellation through the invocation context. Keep the application
whole-operation budget separate from the native per-attempt timeout binding.
@@ -264,8 +268,7 @@ Remove `render`, its compatibility aliases, `defaults.render_format`, and
unused prepared-output formatters. Native prepared preview uses its upstream
report, default/text YAML presentation, standard formats, request flags,
diagnostics, and outcomes. It does not call a model. Consumers save preview
output through stdout capture or redirection; generation's `--output` does not
extend the native inspection families.
output through stdout capture or redirection, as they do for generation.
Adopt native inspection reports, including captured prompt messages and rendered
prepared content, without recreating old summary projections. Native schemas
@@ -292,8 +295,9 @@ documentation and examples describe the shipped interface. In particular:
preparation, discovery, and inspection of multiple independently maintained
collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate
reports expose the native result. Requested files remain independent of
console quiet mode, with useful failure outcomes and nontransactional delivery.
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.
- 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.
@@ -304,13 +308,13 @@ documentation and examples describe the shipped interface. In particular:
- Canonical contracts, examples, dependency attribution, and migration guidance
reflect the cutover. The CLI migration includes positional prompt selection,
command replacements, literal versus file inputs, repeated mappings, overlay
selection, native endpoint/timeout controls, content-bearing reports, report
availability, quiet behavior, and changed exit statuses.
selection, native endpoint/timeout controls, stdout redirection in place of
output-file flags, content-bearing reports, 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
product decisions; the approved upstream selected-format accessor remains an
external release prerequisite.
product decisions or selected-format accessor release prerequisite.
The [release policy](../policy/release.md#versioning-and-compatibility) governs
the eventual breaking release version. This migration does not itself select