From b1c7962f51eb9e81104a291bc1966a90b4e772a3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 02:16:44 +0000 Subject: [PATCH] Make the Scriptorium format accessor proposal optional --- docs/roadmap/scriptorium-feature-request.md | 60 +++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/roadmap/scriptorium-feature-request.md diff --git a/docs/roadmap/scriptorium-feature-request.md b/docs/roadmap/scriptorium-feature-request.md new file mode 100644 index 0000000..53e4c95 --- /dev/null +++ b/docs/roadmap/scriptorium-feature-request.md @@ -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.