Files
commandkit/docs/roadmap/scriptorium-feature-request.md

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 --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 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.