Use stdout redirection for main generation output
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user