61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# Selected Report Format Access: Optional Proposal
|
|
|
|
## Status
|
|
|
|
Consumer proposal from Scriptorium, prepared and revised 2026-11-19.
|
|
**This is no longer a prerequisite for Scriptorium's CommandKit migration.**
|
|
It remains an optional API proposal for independent upstream consideration,
|
|
not an accepted CommandKit contract or required release.
|
|
|
|
The reviewed baseline is CommandKit v0.7.0, with public guidance at revision
|
|
`d330d7637f2e7507eca931a899397222c82bc892`.
|
|
|
|
## Revised Consumer Direction
|
|
|
|
Scriptorium will submit PromptKit's native `RunResult` through the invocation
|
|
reporter. Its text template emits the artifact; JSON and YAML use native
|
|
structured rendering. The main result goes to stdout, and callers save it
|
|
through shell redirection or their subprocess API. Scriptorium will not add
|
|
`--output`; callers wanting the main result omit `--quiet`, including when
|
|
stdout is redirected. Diagnostics remain on stderr.
|
|
|
|
The optional `--report PATH` flag additionally writes the native result as fixed
|
|
JSON using the existing `RenderReport(writer, report, FormatJSON)` API. That
|
|
application-owned effect still occurs in quiet mode when a result exists.
|
|
|
|
This design needs no access to the selected main format outside the invocation
|
|
reporter. It can use the existing public APIs without a second parser, custom
|
|
serializer, or change to quiet semantics. Scriptorium owns only the separate
|
|
report file; callers own main-output redirection and its file lifecycle.
|
|
|
|
## Optional Public Capability
|
|
|
|
The original request proposed a read-only selected-format accessor usable by an
|
|
application handler with `RenderReport(writer, report, format)`. It addressed
|
|
application-owned main files whose format followed `--format` and whose writes
|
|
continued in quiet mode. Scriptorium has removed that requirement.
|
|
|
|
If other consumer needs justify this capability, the proposal is to expose the
|
|
selection already interpreted by CommandKit:
|
|
|
|
- Preserve automatic selection when `--format` is omitted, allowing the report's
|
|
text template or native fallback to determine presentation at rendering time.
|
|
- Preserve explicit text, JSON, and YAML selections and native repeated-flag,
|
|
alias, and argument-placement behavior.
|
|
- Leave reporting mode, destinations, diagnostics, and presentation state
|
|
unchanged when reading the selection.
|
|
|
|
The exported name and design remain upstream choices. Such an accessor would
|
|
add no standard output-file flag, file lifecycle management, or automatic
|
|
tracking of application writer failures. The
|
|
[reporting contract](../cli.md#reporting) and
|
|
[consumer guide](../consumers/guide.md#invocation-reporting) retain ownership of
|
|
native rendering and outcomes.
|
|
|
|
## Adoption Impact
|
|
|
|
Scriptorium no longer has accessor-specific acceptance scenarios or a release
|
|
dependency on this proposal. The earlier `--output` scenarios are superseded by
|
|
stdout reporting and caller-controlled redirection. Neither ckconfig nor
|
|
ckprompt needs a change for this revised delivery model.
|