Make the Scriptorium format accessor proposal optional
This commit is contained in:
60
docs/roadmap/scriptorium-feature-request.md
Normal file
60
docs/roadmap/scriptorium-feature-request.md
Normal 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.
|
||||
Reference in New Issue
Block a user