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
|
dependencies remain subject to the existing
|
||||||
[architecture policy](../policy/architecture.md).
|
[architecture policy](../policy/architecture.md).
|
||||||
|
|
||||||
One approved upstream addition is needed: a released selected-format accessor.
|
No selected-format accessor is required for this migration. The native
|
||||||
CommandKit v0.7.0 provides a writer-level renderer but no public access to the
|
invocation reporter handles the main result on stdout; the existing writer API
|
||||||
invocation's selected format. The accessor enables formatted application-owned
|
handles the separate report using fixed JSON. The upstream accessor proposal
|
||||||
output files, including in quiet mode, without duplicating reporting-flag
|
remains optional API work, independent of Scriptorium's adoption.
|
||||||
parsing. The implementation plan tracks adoption of its released API; the
|
|
||||||
agreed file-output contract remains the target.
|
|
||||||
|
|
||||||
## Target End State
|
## Target End State
|
||||||
|
|
||||||
@@ -210,17 +208,21 @@ remains upstream-owned. There is no Scriptorium result envelope.
|
|||||||
|
|
||||||
| Selection | Behavior |
|
| Selection | Behavior |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| No destination flag | Main result goes to stdout using the selected format. |
|
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
|
||||||
| `--output PATH` | Main result goes to that file, without duplicate stdout output. |
|
|
||||||
| `--format text` or default | Main result contains only the artifact. |
|
| `--format text` or default | Main result contains only the artifact. |
|
||||||
| `--format json` or `--format yaml` | Main result contains the native result and metadata. |
|
| `--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 as JSON through CommandKit's renderer, independently of the main format and destination. |
|
||||||
|
|
||||||
Filename extensions do not select formats. The separate report includes the
|
There is no `--output` or legacy `--out` flag. Callers save the main result by
|
||||||
native result's content as well as metadata; it replaces the CLI's old
|
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
|
observer-derived metadata projection. A caller wanting an artifact file plus
|
||||||
metadata can select separate output and report paths. The caller manages paths
|
metadata redirects stdout and selects a separate `--report` path. The caller
|
||||||
and retention; there is no automatic reporting directory or report collection.
|
manages redirected destinations and retention; there is no automatic reporting
|
||||||
|
directory or report collection.
|
||||||
|
|
||||||
Native result reporting is available when PromptKit returns a result.
|
Native result reporting is available when PromptKit returns a result.
|
||||||
Operational errors return nonzero status and native failure diagnostics, without
|
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
|
Adopt CommandKit's quiet and verbosity semantics, including rendering and
|
||||||
presentation failures. Console results use the invocation reporter; diagnostics
|
presentation failures. Console results use the invocation reporter; diagnostics
|
||||||
use its diagnostic channel. Explicit `--output` and `--report` writes are
|
use its diagnostic channel. An explicit `--report` write is an application
|
||||||
application effects rendered through the writer API and still occur in quiet
|
effect rendered as JSON through the writer API and still occurs in quiet mode.
|
||||||
mode. Quiet does not cancel generation; without requested files it suppresses
|
Quiet does not cancel generation; it suppresses the main result even when
|
||||||
ordinary result output while failure explanations remain visible. Move any
|
stdout is redirected, while failure explanations remain visible. Move any
|
||||||
retained generation summary into an appropriate native message category.
|
retained generation summary into an appropriate native message category.
|
||||||
|
|
||||||
Map typed upstream failures and configuration diagnostics into native outcomes,
|
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
|
nonzero domain outcome. Requested file errors must not disappear merely because
|
||||||
they occur outside the invocation reporter.
|
they occur outside the invocation reporter.
|
||||||
|
|
||||||
Use ordinary file operations: replace files without creating parents, reject
|
For `--report`, use ordinary file replacement without creating parents. Attempt
|
||||||
output/report destinations known to name the same file before execution,
|
the main output followed by the report, and attempt the report even if main
|
||||||
attempt the main output followed by the report, and attempt the report even if
|
delivery fails. Open the report only when a native result exists. Redirection
|
||||||
main delivery fails. This adds no rollback, transactional delivery, or stronger
|
and its file-creation or truncation behavior belong to the caller. Scriptorium
|
||||||
filesystem protection. Already delivered output may remain after failure.
|
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
|
Wire signal cancellation through the invocation context. Keep the application
|
||||||
whole-operation budget separate from the native per-attempt timeout binding.
|
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
|
unused prepared-output formatters. Native prepared preview uses its upstream
|
||||||
report, default/text YAML presentation, standard formats, request flags,
|
report, default/text YAML presentation, standard formats, request flags,
|
||||||
diagnostics, and outcomes. It does not call a model. Consumers save preview
|
diagnostics, and outcomes. It does not call a model. Consumers save preview
|
||||||
output through stdout capture or redirection; generation's `--output` does not
|
output through stdout capture or redirection, as they do for generation.
|
||||||
extend the native inspection families.
|
|
||||||
|
|
||||||
Adopt native inspection reports, including captured prompt messages and rendered
|
Adopt native inspection reports, including captured prompt messages and rendered
|
||||||
prepared content, without recreating old summary projections. Native schemas
|
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
|
preparation, discovery, and inspection of multiple independently maintained
|
||||||
collections. Their upstream lifecycle differences remain visible.
|
collections. Their upstream lifecycle differences remain visible.
|
||||||
- Generation defaults to the artifact alone; structured output and separate
|
- Generation defaults to the artifact alone; structured output and separate
|
||||||
reports expose the native result. Requested files remain independent of
|
reports expose the native result. Main output uses stdout and native quiet
|
||||||
console quiet mode, with useful failure outcomes and nontransactional delivery.
|
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
|
- Narratio's linked acceptance scenarios are supported, including useful partial
|
||||||
discovery and discovery before generated artifacts exist.
|
discovery and discovery before generated artifacts exist.
|
||||||
- Native help, aliases, completion, and explicit smoke testing are available.
|
- 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
|
- Canonical contracts, examples, dependency attribution, and migration guidance
|
||||||
reflect the cutover. The CLI migration includes positional prompt selection,
|
reflect the cutover. The CLI migration includes positional prompt selection,
|
||||||
command replacements, literal versus file inputs, repeated mappings, overlay
|
command replacements, literal versus file inputs, repeated mappings, overlay
|
||||||
selection, native endpoint/timeout controls, content-bearing reports, report
|
selection, native endpoint/timeout controls, stdout redirection in place of
|
||||||
availability, quiet behavior, and changed exit statuses.
|
output-file flags, content-bearing reports, report availability, quiet
|
||||||
|
behavior, and changed exit statuses.
|
||||||
|
|
||||||
The [implementation plan](implementation.md) owns task sequencing, concrete
|
The [implementation plan](implementation.md) owns task sequencing, concrete
|
||||||
adapter mappings, verification steps, and sprint status. There are no unresolved
|
adapter mappings, verification steps, and sprint status. There are no unresolved
|
||||||
product decisions; the approved upstream selected-format accessor remains an
|
product decisions or selected-format accessor release prerequisite.
|
||||||
external release prerequisite.
|
|
||||||
|
|
||||||
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||||
the eventual breaking release version. This migration does not itself select
|
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
|
### Output destinations and verbosity
|
||||||
|
|
||||||
Decision recorded 2026-11-19: use `--output PATH` for the main result's file
|
Decision revised 2026-11-19: remove the previously selected `--output` flag.
|
||||||
destination. Without it, the main result goes to stdout. With it, the selected
|
The main result uses the native invocation reporter and stdout. Callers save it
|
||||||
representation goes to the file without duplicate stdout output. Use the
|
through shell redirection or a subprocess stdout destination; diagnostics remain
|
||||||
spelling `--output`, with no legacy `--out` compatibility alias.
|
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
|
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
|
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
|
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
|
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
|
||||||
mode selection, message visibility, rendering, and presentation failures. Do
|
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
|
Quiet mode does not cancel generation, and failure explanations remain visible
|
||||||
through the native diagnostic channel.
|
through the native diagnostic channel.
|
||||||
|
|
||||||
Explicitly requested `--output` and `--report` writes are application-owned file
|
An explicit `--report` write remains an application-owned effect in quiet mode,
|
||||||
operations and still occur in quiet mode. Render those files through CommandKit's
|
using the existing writer API with fixed JSON. Quiet suppresses the main result
|
||||||
writer API; the invocation reporter governs console output. This follows the
|
even when stdout is redirected; callers wanting that result omit quiet. No
|
||||||
upstream distinction between reporting visibility and application effects.
|
selected-format accessor is needed, so the upstream proposal is no longer a
|
||||||
With quiet mode and no requested files, generation still runs while ordinary
|
migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
|
||||||
result output is suppressed. The [upstream reporting contract][upstream-cli]
|
shared verbosity rules.
|
||||||
owns the shared verbosity rules.
|
|
||||||
|
|
||||||
### Prepared-request preview
|
### Prepared-request preview
|
||||||
|
|
||||||
@@ -170,8 +169,7 @@ request construction with generation so previews describe the corresponding
|
|||||||
execution request. PromptKit continues to own preparation semantics.
|
execution request. PromptKit continues to own preparation semantics.
|
||||||
|
|
||||||
Use the native result stream for preview output; consumers can capture or
|
Use the native result stream for preview output; consumers can capture or
|
||||||
redirect stdout to save it. The generation command's `--output` decision does
|
redirect stdout to save it, as with generation. File-output convenience does
|
||||||
not itself extend the native inspection commands. File-output convenience does
|
|
||||||
not justify retaining a separate preview command. Update maintained examples
|
not justify retaining a separate preview command. Update maintained examples
|
||||||
and release migration guidance to use `promptkit show prepared`.
|
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.
|
Reuse ckprompt's applicable resource, input, and execution flag bindings.
|
||||||
Preserve native parsing, explicit-value presence, repeated mapping semantics,
|
Preserve native parsing, explicit-value presence, repeated mapping semantics,
|
||||||
and PromptKit's interpretation of request values. Keep application-specific
|
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.
|
whole-operation deadline separate from framework request controls.
|
||||||
|
|
||||||
Enable upstream convenience aliases consistently on applicable commands,
|
Enable upstream convenience aliases consistently on applicable commands,
|
||||||
@@ -308,10 +306,11 @@ units, separately from the standard per-attempt timeout flag.
|
|||||||
|
|
||||||
### File delivery
|
### File delivery
|
||||||
|
|
||||||
Specify ordinary path handling, overwriting, parent-directory behavior,
|
The roadmap and implementation plan specify ordinary report-file handling and
|
||||||
destination collisions, and delivery ordering for `--output` and `--report`.
|
delivery ordering relative to stdout. The caller owns redirected destinations;
|
||||||
Describe partial delivery consistently with native outcome reporting and the
|
Scriptorium does not infer them or check for collisions with the report path.
|
||||||
agreed upstream result-availability boundary.
|
Partial delivery follows native outcomes and the agreed result-availability
|
||||||
|
boundary.
|
||||||
|
|
||||||
### Adoption and verification
|
### 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`,
|
`cmd/scriptorium`, `internal/adapter/cli`, `internal/config`, `internal/format`,
|
||||||
`internal/report`, and the unchanged `internal/adapter/http`.
|
`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
|
The reviewed public APIs are documented at CommandKit revision
|
||||||
`d330d7637f2e7507eca931a899397222c82bc892` in its
|
`d330d7637f2e7507eca931a899397222c82bc892` in its
|
||||||
@@ -45,27 +45,16 @@ baseline is:
|
|||||||
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
|
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
|
||||||
| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` |
|
| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` |
|
||||||
|
|
||||||
There is one approved external prerequisite. CommandKit v0.7.0 has the public
|
Use the reviewed released combination and verify it in Stage 1. Preserve
|
||||||
`RenderReport(writer, report, format)` API but does not expose the invocation's
|
ConfigKit v1.2.1 and PromptKit v0.23.3; ckprompt's PromptKit v0.23.2 minimum is
|
||||||
selected format. Its invocation reporter suppresses console writes in quiet
|
not a reason to downgrade. Raise any demonstrated compatibility problem before
|
||||||
mode. Consequently that release alone cannot implement the agreed formatted
|
expanding this sprint into another framework upgrade.
|
||||||
`--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.
|
|
||||||
|
|
||||||
Keep ckconfig v0.9.0 and ckprompt v0.10.0 if they compose with the released core
|
No selected-format accessor is required. Main results go through the native
|
||||||
addition; adopt corresponding released integration updates only if needed for
|
invocation reporter to stdout, with caller-controlled redirection. The separate
|
||||||
that capability. Preserve ConfigKit v1.2.1 and PromptKit v0.23.3 unless that
|
`--report` file uses the existing `RenderReport(writer, report, FormatJSON)` API.
|
||||||
necessary released combination requires a separately reviewed change. In
|
The upstream accessor proposal is optional and does not block any stage. Do not
|
||||||
particular, ckprompt's PromptKit v0.23.2 minimum is not a reason to downgrade.
|
add a second reporting-flag parser or private-API workaround.
|
||||||
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.
|
|
||||||
|
|
||||||
## Settled Application Choices
|
## 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 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. |
|
| 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. |
|
| 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. |
|
| 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. |
|
| 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. |
|
| 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
|
Use `errors.Is`/`errors.As`, not error-text matching. Apply cancellation and
|
||||||
typed operation-timeout handling before configuration classification. Do not
|
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
|
with no added newline, header, escaping, or summary. Native JSON/YAML serialization
|
||||||
remains upstream-owned, including byte representation and native metadata.
|
remains upstream-owned, including byte representation and native metadata.
|
||||||
|
|
||||||
Without `--output`, submit the report through the invocation reporter. With
|
Submit the main report through `Invocation.Reporter().Report`. There is no
|
||||||
`--output PATH`, render through `commandkit.RenderReport` to that file using
|
`--output` or legacy `--out` flag. Callers save stdout using shell redirection or
|
||||||
the upstream selected-format accessor; do not also submit a console result.
|
their subprocess API; Scriptorium keeps diagnostics on stderr. Native quiet
|
||||||
`--report PATH` additionally renders the same native result as JSON, regardless
|
suppresses the main result even when stdout is redirected. Consumers wanting
|
||||||
of main format or destination. Explicit files are application effects and are
|
that result omit `--quiet`.
|
||||||
written even in quiet mode. No separate report is created when the flag is absent.
|
|
||||||
|
|
||||||
Use ordinary create/truncate file operations (mode 0644 for newly created files,
|
`--report PATH` additionally renders the same native result as fixed JSON via
|
||||||
subject to umask), preserve normal OS behavior for existing files, and handle
|
`commandkit.RenderReport`, regardless of the main format or stdout destination.
|
||||||
render/write/close errors. Do not create parent directories. Explicit empty
|
This application-owned file write still occurs in quiet mode. Omitting the flag
|
||||||
destination values are usage errors; `-` is an ordinary filename. Before
|
creates no separate report. Use ordinary create/truncate operations (mode 0644
|
||||||
generation, reject output/report paths known to identify the same file using
|
for newly created files, subject to umask), preserve normal OS behavior for
|
||||||
cleaned absolute path equality and `os.SameFile` for existing destinations.
|
existing files, and handle render/write/close errors. Do not create parent
|
||||||
This is a best-effort collision check, not a filesystem-race guarantee.
|
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
|
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
|
report, even if the first attempt fails. Open the report only after a result
|
||||||
before a result exists. No native result means no replacement report or output
|
exists; a resultless failure leaves an existing report untouched. This does not
|
||||||
file; an existing destination can remain from a previous invocation. Delivery
|
govern a caller's redirection: a shell may create or truncate its destination
|
||||||
is nontransactional: written bytes remain after failure. No rollback, atomic
|
before Scriptorium runs. Delivery is nontransactional; written bytes remain
|
||||||
replacement, symlink sandbox, or additional filesystem hardening is requested.
|
after failure. No rollback, atomic replacement, symlink sandbox, or additional
|
||||||
|
filesystem hardening is requested.
|
||||||
|
|
||||||
## Stage 1: Select Released Dependencies And Establish Command Composition
|
## Stage 1: Select Released Dependencies And Establish Command Composition
|
||||||
|
|
||||||
**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition,
|
**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition,
|
||||||
`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts.
|
`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts.
|
||||||
|
|
||||||
1. Verify the released selected-format accessor prerequisite above and select
|
1. Verify the reviewed released module combination above. Record the actual
|
||||||
the minimal compatible released module combination. Record the actual
|
|
||||||
versions and complete source commits in this plan's implementation status
|
versions and complete source commits in this plan's implementation status
|
||||||
and attribution entries as appropriate; use released modules, not sibling
|
and attribution entries as appropriate; use released modules, not sibling
|
||||||
checkouts, workspaces, vendoring, or replacements.
|
checkouts, workspaces, vendoring, or replacements.
|
||||||
2. Add CommandKit, ckconfig, and ckprompt dependencies. Keep the existing Go
|
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.
|
concrete contrary requirement; raise such an expansion rather than guessing.
|
||||||
Verify selected PromptKit/ConfigKit versions and tidy the module metadata.
|
Verify selected PromptKit/ConfigKit versions and tidy the module metadata.
|
||||||
3. Create the CLI composition entry point in `internal/adapter/cli`. Accept a
|
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
|
7. Build the native result report/text template and submit stdout results
|
||||||
through the invocation reporter. Keep any retained generation summary as a
|
through the invocation reporter. Keep any retained generation summary as a
|
||||||
native Info message, normally hidden at ordinary verbosity. Stage 6 adds
|
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
|
**Evidence:** real-engine/controlled-provider tests exercise the assembled
|
||||||
positional command, preferred aliases, literal/file precedence, comma-containing
|
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
|
failure/status 1. Include a small typed-error mapping table rather than parsing
|
||||||
error prose. Use native config classification for representative load failures.
|
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.
|
**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
|
1. Add `--report` as a presence-aware application file flag with path completion.
|
||||||
path completion. Validate empty values and known destination collisions
|
Reject an explicitly empty path before executing the model. Do not create
|
||||||
before executing the model. Do not create files during validation.
|
files during validation or add a main-output destination flag.
|
||||||
2. Implement the settled delivery rules using the same report as Stage 5.
|
2. Implement the settled delivery rules using the same report as Stage 5.
|
||||||
Main stdout uses `Invocation.Reporter().Report`; main files use
|
Main stdout uses `Invocation.Reporter().Report`; the separate report uses
|
||||||
`RenderReport` and the upstream selected format; separate reports use
|
`RenderReport(..., FormatJSON)`. The invocation reporter owns main format
|
||||||
`RenderReport(..., FormatJSON)`. The default selected format must continue
|
selection, including automatic artifact-template output. No selected-format
|
||||||
to use the artifact-only text template. Extensions never select formats.
|
accessor is needed. Extensions never select formats.
|
||||||
3. Keep explicit file effects independent of console quiet selection. Do not
|
3. Keep the report file effect independent of console quiet selection. Do not
|
||||||
temporarily change reporting mode, rerun `App.Execute`, capture stdout and
|
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.
|
Keep file rendering outside reporter render callbacks to avoid reentrancy.
|
||||||
4. Attempt main delivery and then the requested report even when the first
|
4. Attempt main delivery and then the requested report even when the first
|
||||||
fails, retaining every relevant delivery error. Include useful failure
|
fails, retaining every relevant delivery error. Include useful failure
|
||||||
explanations and preserve the selected nonzero domain outcome. Console
|
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.
|
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.
|
5. Remove the CLI observer/report collector wiring and old report-file format.
|
||||||
Leave `internal/report` and HTTP report attachment intact. Only a returned
|
Leave `internal/report` and HTTP report attachment intact. Only a returned
|
||||||
native run result is eligible for the new CLI report file.
|
native run result is eligible for the new CLI report file.
|
||||||
|
|
||||||
**Evidence:** cover default/text raw bytes, JSON and YAML main files, JSON
|
**Evidence:** cover default/text raw bytes and JSON/YAML through stdout, including
|
||||||
separate report equivalence to inline native JSON, no duplicate stdout,
|
a subprocess whose stdout is redirected to a file. Check separate JSON report
|
||||||
format/extension independence, and quiet with/without requested files. Test
|
equivalence to inline native JSON and independence from the main format. Quiet
|
||||||
empty paths, same cleaned path, existing same-file aliases, replacement without
|
suppresses main output, including redirected stdout, while an explicitly requested
|
||||||
parent creation, first-delivery failure followed by report attempt, report
|
report is still written. Test empty report paths, replacement without parent
|
||||||
failure after successful main delivery, and an unchanged existing report on a
|
creation, stdout failure followed by report attempt, report failure after
|
||||||
resultless operational failure. Use temporary files and a small failing-writer
|
successful main delivery, and an unchanged existing report on a resultless
|
||||||
seam for stdout/render failures. Confirm status 4 survives a delivery failure
|
operational failure. Use temporary files and a small failing-writer seam for
|
||||||
while its explanation identifies the failure. No exhaustive filesystem matrix.
|
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
|
## 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 |
|
| 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/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/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. |
|
| `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
|
CLI/consumer overview. Cover positional prompt selection; `render` and
|
||||||
`inspect` replacements; file versus literal inputs; repeated mappings without
|
`inspect` replacements; file versus literal inputs; repeated mappings without
|
||||||
comma splitting; `--overlay` names; endpoint and timeout spelling/units;
|
comma splitting; `--overlay` names; endpoint and timeout spelling/units;
|
||||||
output/report destinations, native formats, and result availability; quiet
|
stdout redirection in place of output-file flags; separate JSON reports,
|
||||||
behavior; status changes; and content-bearing native inspection/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,
|
This prepares release migration information without selecting a version,
|
||||||
editing published notes, tagging, pushing, or adding release gates. Eventual
|
editing published notes, tagging, pushing, or adding release gates. Eventual
|
||||||
release notes must summarize the breaking change and link the guide under
|
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
|
Help/version/scope discovery/static completion work without configuration or
|
||||||
provider availability. Confirm retired commands/flags are absent or rejected
|
provider availability. Confirm retired commands/flags are absent or rejected
|
||||||
except where a spelling now intentionally has its native meaning (`--input`).
|
except where a spelling now intentionally has its native meaning (`--input`).
|
||||||
4. Review the output/outcome matrix across stdout, requested files, quiet,
|
4. Review the output/outcome matrix across stdout, caller redirection, report
|
||||||
completed validation failure, operational failures, presentation errors,
|
files, quiet, completed validation failure, operational failures, presentation
|
||||||
cancellation, and partial delivery. Verify reports are native values with
|
errors, cancellation, and partial delivery. Verify reports are native values
|
||||||
no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
|
with no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
|
||||||
5. Run the repository baseline on the selected toolchain:
|
5. Run the repository baseline on the selected toolchain:
|
||||||
|
|
||||||
```sh
|
```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
|
7. Record completion and the actual dependency/API selections after successful
|
||||||
verification. Commit the finished implementation units under the agent
|
verification. Commit the finished implementation units under the agent
|
||||||
policy and report checks, commits, and any remaining work accurately. Do
|
policy and report checks, commits, and any remaining work accurately. Do
|
||||||
not mark the migration complete while the approved upstream accessor or
|
not mark the migration complete while required acceptance behavior is missing.
|
||||||
required acceptance behavior is missing.
|
|
||||||
|
|
||||||
There are no unresolved product questions. The selected-format accessor is an
|
There are no unresolved product questions. The optional upstream selected-format
|
||||||
approved external release prerequisite, with its exact API/version to be
|
accessor is not a migration dependency or completion gate.
|
||||||
confirmed in Stage 1; it does not authorize a local workaround.
|
|
||||||
|
|
||||||
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
|
[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
|
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||||
|
|||||||
Reference in New Issue
Block a user