Allow native format selection for separate reports
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user