Scriptorium Integration

This document describes the external Scriptorium CLI contract used by weatherreporter.

Purpose

weatherreporter invokes Scriptorium as a subprocess to preflight prompt input and generate Markdown reports. This page documents the CLI surface the adapter uses, not the full Scriptorium product.

Commands Used

Render preflight:

scriptorium render \
  --prompt <prompt_id> \
  --input data_package=<path> \
  --format json

Report generation:

scriptorium run \
  --prompt <prompt_id> \
  --input data_package=<path> \
  --out <artifact_path>

weatherreporter always passes prompt input as --input data_package=<path>. The data package is structured JSON created by internal/promptinput.

Configured Arguments

The adapter can prepend configured flags before prompt-specific arguments:

--config <path> from scriptorium.config_path
--profile <profile> from scriptorium.profile

It appends scriptorium.extra_args after the built-in arguments. Extra arguments are passed directly as argv items.

scriptorium.binary selects the executable name or path. If unset inside the adapter, it falls back to scriptorium.

Execution Behavior

The adapter runs Scriptorium without shell interpolation. Arguments are passed through exec.CommandContext.

scriptorium.timeout limits each subprocess call when configured. Context cancellation or timeout returns an execution error.

Stdout and stderr are captured separately. Each stream is capped at 1 MiB and the result records whether truncation occurred.

Results

Render results include:

full argv recorded as command
stdout
stderr
exit code
truncation flags when applicable

Run results include the same fields plus the requested output path.

weatherreporter persists render preflight JSON when orchestration reaches the preflight save point. The final Markdown artifact is written by Scriptorium to the --out path.

Failure Behavior

The adapter validates required request fields before starting Scriptorium:

prompt ID
data package path
output path for run

Nonzero exits return both the captured result and an error containing the exit code and stderr. A run exit code such as 2 is still treated as an error by the adapter, even if Scriptorium wrote output to the requested artifact path.

Subprocess start failures, context cancellation, and timeouts return errors without fabricating a successful result.

Security Notes

The adapter does not invoke a shell.
Generated artifacts, rendered prompt context, stdout, and stderr can contain operationally sensitive data.
API keys should be provided through the Scriptorium environment or Scriptorium configuration, not through weatherreporter CLI arguments.

2.7 KiB Raw Blame History