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

View File

@@ -128,16 +128,16 @@ format to compensate for the absence of a native result.
### Output destinations and verbosity
Decision recorded 2026-11-19: use `--output PATH` for the main result's file
destination. Without it, the main result goes to stdout. With it, the selected
representation goes to the file without duplicate stdout output. Use the
spelling `--output`, with no legacy `--out` compatibility alias.
Decision revised 2026-11-19: remove the previously selected `--output` flag.
The main result uses the native invocation reporter and stdout. Callers save it
through shell redirection or a subprocess stdout destination; diagnostics remain
on stderr. Do not retain the old `--out` flag.
`--format` selects the representation independently of the destination:
`--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
report to separate files.
report to separate files by redirecting stdout and supplying `--report`.
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
mode selection, message visibility, rendering, and presentation failures. Do
@@ -145,13 +145,12 @@ not add Scriptorium-specific exceptions to normal command-output suppression.
Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel.
Explicitly requested `--output` and `--report` writes are application-owned file
operations and still occur in quiet mode. Render those files through CommandKit's
writer API; the invocation reporter governs console output. This follows the
upstream distinction between reporting visibility and application effects.
With quiet mode and no requested files, generation still runs while ordinary
result output is suppressed. The [upstream reporting contract][upstream-cli]
owns the shared verbosity rules.
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
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.
### Prepared-request preview
@@ -170,8 +169,7 @@ request construction with generation so previews describe the corresponding
execution request. PromptKit continues to own preparation semantics.
Use the native result stream for preview output; consumers can capture or
redirect stdout to save it. The generation command's `--output` decision does
not itself extend the native inspection commands. File-output convenience does
redirect stdout to save it, as with generation. File-output convenience does
not justify retaining a separate preview command. Update maintained examples
and release migration guidance to use `promptkit show prepared`.
@@ -245,7 +243,7 @@ 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, `--output`, `--report`, server options, and the
configuration/source selection, `--report`, server options, and the
whole-operation deadline separate from framework request controls.
Enable upstream convenience aliases consistently on applicable commands,
@@ -308,10 +306,11 @@ units, separately from the standard per-attempt timeout flag.
### File delivery
Specify ordinary path handling, overwriting, parent-directory behavior,
destination collisions, and delivery ordering for `--output` and `--report`.
Describe partial delivery consistently with native outcome reporting and the
agreed upstream result-availability boundary.
The roadmap and implementation plan specify ordinary report-file handling and
delivery ordering relative to stdout. The caller owns redirected destinations;
Scriptorium does not infer them or check for collisions with the report path.
Partial delivery follows native outcomes and the agreed result-availability
boundary.
### Adoption and verification

View File

@@ -32,7 +32,7 @@ with validation/build toolchain Go 1.27.4. Relevant starting components are
`cmd/scriptorium`, `internal/adapter/cli`, `internal/config`, `internal/format`,
`internal/report`, and the unchanged `internal/adapter/http`.
## Dependency Prerequisite And Selected Integration
## Released Dependencies And Selected Integration
The reviewed public APIs are documented at CommandKit revision
`d330d7637f2e7507eca931a899397222c82bc892` in its
@@ -45,27 +45,16 @@ baseline is:
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` |
There is one approved external prerequisite. CommandKit v0.7.0 has the public
`RenderReport(writer, report, format)` API but does not expose the invocation's
selected format. Its invocation reporter suppresses console writes in quiet
mode. Consequently that release alone cannot implement the agreed formatted
`--output` behavior, including quiet-mode file delivery, through the intended
APIs. The user selected a **released upstream selected-format accessor** as the
solution. Adopt that capability before implementing Stage 6. Its final exported
name and release number are determined upstream, not invented here.
Use the reviewed released combination and verify it in Stage 1. Preserve
ConfigKit v1.2.1 and PromptKit v0.23.3; ckprompt's PromptKit v0.23.2 minimum is
not a reason to downgrade. Raise any demonstrated compatibility problem before
expanding this sprint into another framework upgrade.
Keep ckconfig v0.9.0 and ckprompt v0.10.0 if they compose with the released core
addition; adopt corresponding released integration updates only if needed for
that capability. Preserve ConfigKit v1.2.1 and PromptKit v0.23.3 unless that
necessary released combination requires a separately reviewed change. In
particular, ckprompt's PromptKit v0.23.2 minimum is not a reason to downgrade.
Do not opportunistically expand this sprint into another framework upgrade.
Stage 1 confirms the actual release and API. If unavailable, record the external
dependency and leave the affected work incomplete pending its release. Do not
silently reduce the output contract, parse reporting flags again, use reflection
or private APIs, or commit a local module replacement. The upstream addition is
not an unresolved product choice and is not work to implement in this repository.
No selected-format accessor is required. Main results go through the native
invocation reporter to stdout, with caller-controlled redirection. The separate
`--report` file uses the existing `RenderReport(writer, report, FormatJSON)` API.
The upstream accessor proposal is optional and does not block any stage. Do not
add a second reporting-flag parser or private-API workaround.
## Settled Application Choices
@@ -110,12 +99,12 @@ the existing discovery locations, and source-relative PromptKit resources.
| --- | --- |
| Completed run without `ValidationFailed` | Native success, status 0, subject to delivery. |
| Completed run with `ValidationFailed` | `commandkit.Domain("validation_failed", 4)` with a useful explanation; deliver the returned artifact and native result. |
| Syntax, declaration-input, or destination-combination errors | Native usage, status 2. |
| Syntax or declaration-input errors, including an explicitly empty report path | Native usage, status 2. |
| Configuration load errors | Use `ckconfig.ClassifyConfigurationError` and native diagnostic evidence: usage 2 for classified invalid configuration, otherwise operational 1. |
| Lookup, preparation, generation, capacity, operation-timeout, cancellation, or other operational errors | Operational 1 with safe explanation and preserved typed cause. Request failures are not completed content-validation failures. |
| Native `config diff --check` differences | Native status 3, unchanged. |
| Result or diagnostic presentation failure | Preserve CommandKit's finalization rules: success/usage become operational 1; a nonzero domain status remains nonzero and retains its classification. |
| Explicit file delivery failure | Operational 1 for an otherwise successful run. Preserve an already nonzero domain status 4 while adding the delivery explanation/cause. Attempt remaining requested delivery. |
| Report file delivery failure | Operational 1 for an otherwise successful run. Preserve an already nonzero domain status 4 while adding the delivery explanation/cause. |
Use `errors.Is`/`errors.As`, not error-text matching. Apply cancellation and
typed operation-timeout handling before configuration classification. Do not
@@ -128,40 +117,42 @@ Its reusable text template emits `Artifact.Body` as bytes represented as a strin
with no added newline, header, escaping, or summary. Native JSON/YAML serialization
remains upstream-owned, including byte representation and native metadata.
Without `--output`, submit the report through the invocation reporter. With
`--output PATH`, render through `commandkit.RenderReport` to that file using
the upstream selected-format accessor; do not also submit a console result.
`--report PATH` additionally renders the same native result as JSON, regardless
of main format or destination. Explicit files are application effects and are
written even in quiet mode. No separate report is created when the flag is absent.
Submit the main report through `Invocation.Reporter().Report`. There is no
`--output` or legacy `--out` flag. Callers save stdout using shell redirection or
their subprocess API; Scriptorium keeps diagnostics on stderr. Native quiet
suppresses the main result even when stdout is redirected. Consumers wanting
that result omit `--quiet`.
Use ordinary create/truncate file operations (mode 0644 for newly created files,
subject to umask), preserve normal OS behavior for existing files, and handle
render/write/close errors. Do not create parent directories. Explicit empty
destination values are usage errors; `-` is an ordinary filename. Before
generation, reject output/report paths known to identify the same file using
cleaned absolute path equality and `os.SameFile` for existing destinations.
This is a best-effort collision check, not a filesystem-race guarantee.
`--report PATH` additionally renders the same native result as fixed JSON via
`commandkit.RenderReport`, regardless of the main format or stdout destination.
This application-owned file write still occurs in quiet mode. Omitting the flag
creates no separate report. Use ordinary create/truncate operations (mode 0644
for newly created files, subject to umask), preserve normal OS behavior for
existing files, and handle render/write/close errors. Do not create parent
directories. An explicit empty report path is a usage error; `-` is an ordinary
filename. The caller owns redirected destinations, including keeping the main
output file separate from the report. Do not add stdout-destination discovery
or collision checks in Scriptorium.
Once a result is available, attempt main delivery first, then the separate
report, even if the first attempt fails. Do not precreate or truncate files
before a result exists. No native result means no replacement report or output
file; an existing destination can remain from a previous invocation. Delivery
is nontransactional: written bytes remain after failure. No rollback, atomic
replacement, symlink sandbox, or additional filesystem hardening is requested.
report, even if the first attempt fails. Open the report only after a result
exists; a resultless failure leaves an existing report untouched. This does not
govern a caller's redirection: a shell may create or truncate its destination
before Scriptorium runs. Delivery is nontransactional; written bytes remain
after failure. No rollback, atomic replacement, symlink sandbox, or additional
filesystem hardening is requested.
## Stage 1: Select Released Dependencies And Establish Command Composition
**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition,
`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts.
1. Verify the released selected-format accessor prerequisite above and select
the minimal compatible released module combination. Record the actual
1. Verify the reviewed released module combination above. Record the actual
versions and complete source commits in this plan's implementation status
and attribution entries as appropriate; use released modules, not sibling
checkouts, workspaces, vendoring, or replacements.
2. Add CommandKit, ckconfig, and ckprompt dependencies. Keep the existing Go
minimum and validation toolchain unless the selected addition supplies a
minimum and validation toolchain unless the selected dependencies supply a
concrete contrary requirement; raise such an expansion rather than guessing.
Verify selected PromptKit/ConfigKit versions and tidy the module metadata.
3. Create the CLI composition entry point in `internal/adapter/cli`. Accept a
@@ -358,7 +349,7 @@ helpers in `internal/adapter/cli`, and run integration tests.
7. Build the native result report/text template and submit stdout results
through the invocation reporter. Keep any retained generation summary as a
native Info message, normally hidden at ordinary verbosity. Stage 6 adds
explicit destinations without changing the result shape.
the separate JSON report without changing the result shape.
**Evidence:** real-engine/controlled-provider tests exercise the assembled
positional command, preferred aliases, literal/file precedence, comma-containing
@@ -368,41 +359,41 @@ serialization, completed invalid content/status 4, and resultless operational
failure/status 1. Include a small typed-error mapping table rather than parsing
error prose. Use native config classification for representative load failures.
## Stage 6: Add Explicit Output And Native JSON Report Delivery
## Stage 6: Add Separate Native JSON Report Delivery
**Primary files:** CLI generation-delivery helpers and focused delivery tests.
Requires the released upstream selected-format accessor confirmed in Stage 1.
1. Add `--output` and `--report` as presence-aware application file flags with
path completion. Validate empty values and known destination collisions
before executing the model. Do not create files during validation.
1. Add `--report` as a presence-aware application file flag with path completion.
Reject an explicitly empty path before executing the model. Do not create
files during validation or add a main-output destination flag.
2. Implement the settled delivery rules using the same report as Stage 5.
Main stdout uses `Invocation.Reporter().Report`; main files use
`RenderReport` and the upstream selected format; separate reports use
`RenderReport(..., FormatJSON)`. The default selected format must continue
to use the artifact-only text template. Extensions never select formats.
3. Keep explicit file effects independent of console quiet selection. Do not
Main stdout uses `Invocation.Reporter().Report`; the separate report uses
`RenderReport(..., FormatJSON)`. The invocation reporter owns main format
selection, including automatic artifact-template output. No selected-format
accessor is needed. Extensions never select formats.
3. Keep the report file effect independent of console quiet selection. Do not
temporarily change reporting mode, rerun `App.Execute`, capture stdout and
parse it back, or replace native structured serialization to obtain files.
parse it back, or replace native structured serialization to obtain the report.
Keep file rendering outside reporter render callbacks to avoid reentrancy.
4. Attempt main delivery and then the requested report even when the first
fails, retaining every relevant delivery error. Include useful failure
explanations and preserve the selected nonzero domain outcome. Console
presentation failures remain recorded by CommandKit finalization; explicit
presentation failures remain recorded by CommandKit finalization; report
file errors need their own outcome handling because they bypass its reporter.
5. Remove the CLI observer/report collector wiring and old report-file format.
Leave `internal/report` and HTTP report attachment intact. Only a returned
native run result is eligible for the new CLI report file.
**Evidence:** cover default/text raw bytes, JSON and YAML main files, JSON
separate report equivalence to inline native JSON, no duplicate stdout,
format/extension independence, and quiet with/without requested files. Test
empty paths, same cleaned path, existing same-file aliases, replacement without
parent creation, first-delivery failure followed by report attempt, report
failure after successful main delivery, and an unchanged existing report on a
resultless operational failure. Use temporary files and a small failing-writer
seam for stdout/render failures. Confirm status 4 survives a delivery failure
while its explanation identifies the failure. No exhaustive filesystem matrix.
**Evidence:** cover default/text raw bytes and JSON/YAML through stdout, including
a subprocess whose stdout is redirected to a file. Check separate JSON report
equivalence to inline native JSON and independence from the main format. Quiet
suppresses main output, including redirected stdout, while an explicitly requested
report is still written. Test empty report paths, replacement without parent
creation, stdout failure followed by report attempt, report failure after
successful main delivery, and an unchanged existing report on a resultless
operational failure. Use temporary files and a small failing-writer seam for
stdout/render failures. Confirm status 4 survives a delivery failure while its
explanation identifies the failure. No exhaustive filesystem matrix.
## Stage 7: Wire Process Metadata, Cancellation, And Server Startup
@@ -465,7 +456,7 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
| Owner | Required changes |
| --- | --- |
| `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, run destinations, file semantics, statuses, completion, explicit smoke tests. Link upstream for standard family details. |
| `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, stdout redirection and separate report-file semantics, statuses, completion, explicit smoke tests. Link upstream for standard family details. |
| `docs/config.md` | Removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics. |
| `docs/integrations/subprocess.md` | Artifact-first execution, native reports and result availability, content-bearing metadata reports, stream capture, partial delivery, cancellation, and caller responsibility. Link exact CLI syntax rather than duplicate it. |
| `docs/operations.md` | Updated discovery/preview/execution workflow, explicit smoke-test effects, potentially sensitive reports, file retention, server process lifecycle, unchanged HTTP limits. |
@@ -477,8 +468,9 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
CLI/consumer overview. Cover positional prompt selection; `render` and
`inspect` replacements; file versus literal inputs; repeated mappings without
comma splitting; `--overlay` names; endpoint and timeout spelling/units;
output/report destinations, native formats, and result availability; quiet
behavior; status changes; and content-bearing native inspection/reports.
stdout redirection in place of output-file flags; separate JSON reports,
native formats, and result availability; quiet behavior (omit quiet to capture
main output); status changes; and content-bearing native inspection/reports.
This prepares release migration information without selecting a version,
editing published notes, tagging, pushing, or adding release gates. Eventual
release notes must summarize the breaking change and link the guide under
@@ -516,10 +508,10 @@ current documentation links resolve. Migration examples match the built CLI.
Help/version/scope discovery/static completion work without configuration or
provider availability. Confirm retired commands/flags are absent or rejected
except where a spelling now intentionally has its native meaning (`--input`).
4. Review the output/outcome matrix across stdout, requested files, quiet,
completed validation failure, operational failures, presentation errors,
cancellation, and partial delivery. Verify reports are native values with
no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
4. Review the output/outcome matrix across stdout, caller redirection, report
files, quiet, completed validation failure, operational failures, presentation
errors, cancellation, and partial delivery. Verify reports are native values
with no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
5. Run the repository baseline on the selected toolchain:
```sh
@@ -544,12 +536,10 @@ current documentation links resolve. Migration examples match the built CLI.
7. Record completion and the actual dependency/API selections after successful
verification. Commit the finished implementation units under the agent
policy and report checks, commits, and any remaining work accurately. Do
not mark the migration complete while the approved upstream accessor or
required acceptance behavior is missing.
not mark the migration complete while required acceptance behavior is missing.
There are no unresolved product questions. The selected-format accessor is an
approved external release prerequisite, with its exact API/version to be
confirmed in Stage 1; it does not authorize a local workaround.
There are no unresolved product questions. The optional upstream selected-format
accessor is not a migration dependency or completion gate.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md