Scriptorium Integration

weatherreporter invokes the Scriptorium executable as a subprocess to preflight prompt input and produce report artifacts. This is the limited CLI contract Weatherreporter uses, not general Scriptorium documentation.

Invocation

The configured scriptorium.binary is the executable name or path. When it is empty, the adapter invokes scriptorium. Arguments are passed directly to the process, without a shell.

For every command, arguments occur in this order:

The subcommand.
--config <path> when scriptorium.config_path is set.
--profile <profile> when scriptorium.profile is set.
The command-specific arguments below.
Each configured scriptorium.extra_args item.

The adapter uses these exact command shapes:

scriptorium render [--config <path>] [--profile <profile>] \
  --prompt <prompt_id> --input data_package=<data_package_path> --format json \
  [<extra_arg> ...]

scriptorium run [--config <path>] [--profile <profile>] \
  --prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
  [<extra_arg> ...]

render is the preflight command. run writes either a Markdown report or a raw generated-text artifact to the supplied --out path. The structured generated-text use of run has the same argv as Markdown generation; it does not add --format, --schema, --schema-path, or --json-schema flags. Prompt configuration selected by <prompt_id> controls that output.

Inputs and Outputs

Weatherreporter always supplies exactly one prompt input: --input data_package=<data_package_path>. The path identifies the YAML data package produced by the prompt-input builder. Its schema and the separate JSON module snapshots are internal artifacts, not part of this CLI contract.

The application supplies an already-managed output path to every run call. For direct reports it is the Markdown artifact path. For generated-text reports it is the raw JSON artifact path; subsequent validation and Markdown rendering are owned by generated-text processing.

render has no output-path argument. Its JSON-formatted stdout remains captured output: the adapter records it and does not parse it into a separate CLI result type. Likewise, the adapter records run output metadata without decoding the artifact written at --out.

Execution and Results

scriptorium.timeout, when greater than zero, creates a timeout for each subprocess invocation. Parent-context cancellation and that timeout stop the command through the process context.

Stdout and stderr are captured independently, each up to 1 MiB. Every returned result records the complete argv as command, the captured stdout and stderr, exitCode, and stdoutTruncated and stderrTruncated when a stream was capped. Results from both forms of run also record outputPath, the requested --out value.

The Scriptorium adapter owns process execution and result capture. Application orchestration owns when preflight output, report artifacts, and generated-text artifacts are persisted.

Failure Behavior

Before starting Scriptorium, the adapter requires a prompt ID and data-package path for every command, plus an output path for run. Missing fields fail without executing a subprocess.

A nonzero process exit returns the captured result and an error that includes the exit code and stderr. An output file written before such an exit does not make the request successful. Failures to start the command, context cancellation, and timeout return an error rather than a successful result.

Operational Notes

Extra arguments are argv items; they are not shell-interpreted.
Prompt input, generated artifacts, stdout, and stderr can contain operationally sensitive weather data.
Provide API keys through the Scriptorium environment or its configuration, not through Weatherreporter CLI arguments.

3.9 KiB Raw Blame History