2.9 KiB
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
--formatis 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 and consumer guide 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.