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

Structured generated-text report generation uses the same command shape:

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

weatherreporter always passes prompt input as --input data_package=<path>. The data package is structured YAML created by internal/promptinput; module snapshots remain separate JSON artifacts for inspection and Recent Changes.

For generated-text reports, Scriptorium selects the structured output schema from the prompt configuration associated with the prompt ID. weatherreporter does not pass --format, schema path, or JSON Schema flags for structured generation.

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. Structured generated-text run results use the same captured fields and output-path recording, with the output path pointing at the raw generated-text JSON artifact.

weatherreporter persists render preflight JSON when orchestration reaches the preflight save point. Markdown report artifacts are written by Scriptorium to the --out path. Generated-text raw JSON artifacts are also written by Scriptorium to the --out path; later weatherreporter workflow steps validate and render those bytes.

Failure Behavior

The adapter validates required request fields before starting Scriptorium:

prompt ID
data package path
output path for run and structured generated-text 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.

3.6 KiB Raw Blame History