Make the Scriptorium format accessor proposal optional

This commit is contained in:
2026-11-20 02:16:44 +00:00
parent d330d7637f
commit b1c7962f51

View File

@@ -0,0 +1,60 @@
# 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.