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

@@ -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