Allow native format selection for separate reports

This commit is contained in:
2026-11-20 03:14:07 +00:00
parent fbe7dd56e3
commit 69d2ba7038
3 changed files with 77 additions and 49 deletions

View File

@@ -52,7 +52,8 @@ expanding this sprint into another framework upgrade.
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.
`--report` file uses the existing `RenderReport(writer, report, format)` API,
with the format unset unless `--report-format` is supplied.
The upstream accessor proposal is optional and does not block any stage. Do not
add a second reporting-flag parser or private-API workaround.
@@ -112,7 +113,7 @@ classify every `ErrInvalidConfig` wrapper as invalid user input without native
evidence. Retain safe explanations for provider failures; causes are inspectable
Go errors, not permission to print credential-bearing provider payloads.
Use one `commandkit.Report` with the actual `*promptkit.RunResult` as `Value`.
Use a main `commandkit.Report` with the actual `*promptkit.RunResult` as `Value`.
Its reusable text template emits `Artifact.Body` as bytes represented as a string,
with no added newline, header, escaping, or summary. Native JSON/YAML serialization
remains upstream-owned, including byte representation and native metadata.
@@ -123,9 +124,16 @@ 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`.
`--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
`--report PATH` additionally renders `commandkit.Report{Value: result}` through
`commandkit.RenderReport`, without the main report's artifact-only text template.
Optional `--report-format text|yaml|json` selects its native format independently
of stdout's `--format`. When omitted, pass the zero `commandkit.Format` value
(`""`) for native automatic rendering. Do not substitute JSON, YAML, or text.
CommandKit currently renders structured values as YAML in automatic and text
modes; future upstream defaults flow through without application policy changes.
Filename extensions do not select the format.
This application-owned file write still occurs in quiet mode. Omitting `--report`
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
@@ -349,7 +357,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
the separate JSON report without changing the result shape.
the separate native report without changing the result shape.
**Evidence:** real-engine/controlled-provider tests exercise the assembled
positional command, preferred aliases, literal/file precedence, comma-containing
@@ -359,18 +367,22 @@ 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 Separate Native JSON Report Delivery
## Stage 6: Add Separate Native Report Delivery
**Primary files:** CLI generation-delivery helpers and focused delivery tests.
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`; 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.
Add optional `--report-format` with typed binding and completion for the native
`text`, `yaml`, and `json` formats; leave its default unset. Reject an explicitly
empty path or invalid format as usage errors before executing the model. Do
not create files during validation or add a main-output destination flag.
2. Main stdout uses Stage 5's report through `Invocation.Reporter().Report`.
Render the separate report through `RenderReport` with
`commandkit.Report{Value: result}`, sharing the native result but no text
template. Pass the empty format when `--report-format` is omitted;
otherwise pass the explicitly selected native format. 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 the report.
@@ -385,12 +397,15 @@ error prose. Use native config classification for representative load failures.
native run result is eligible for the new CLI report file.
**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
a subprocess whose stdout is redirected to a file. Compare omitted and explicit
report formats against native `RenderReport` of the same value without a template;
use an empty format for the omission expectation, not hard-coded YAML. Confirm
the separate report retains the full result and metadata, independently of the
main format and filename extension. Quiet suppresses main output, including
redirected stdout, while an explicitly requested report is still written. Test
empty report paths and invalid formats before model execution, 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.
@@ -456,7 +471,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, stdout redirection and separate report-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, separate report files with optional format selection, 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. |
@@ -468,9 +483,10 @@ 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;
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.
stdout redirection in place of output-file flags; separate native reports,
optional report-format selection and upstream automatic rendering, 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
@@ -509,9 +525,10 @@ current documentation links resolve. Migration examples match the built CLI.
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, 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.
files with automatic/explicit formats, 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