weatherreporter/docs/internal/scriptorium-adapter.md

Scriptorium Adapter Internals

This document describes the implemented scriptorium subprocess adapter.

Purpose

internal/adapters/scriptorium runs scriptorium render to preflight prompt wiring and scriptorium run to generate report artifacts.

Inputs and Outputs

Input:

• prompt ID
• prompt input data package path
• report output path for run
• configured binary, config path, profile, timeout, and extra arguments

Output:

• captured stdout, with truncation tracking
• captured stderr, with truncation tracking
• exit code
• full argv used for inspection

Boundaries

• This adapter owns scriptorium CLI flag construction and subprocess execution.
• It does not choose report types, build prompt input, fetch weather data, or decide workflow order.

Behavior

The render invocation shape is:

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

The run invocation shape is:

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

Configured --config and --profile values are added when present. Arguments are passed directly as argv, not through a shell. Stdout and stderr are captured separately. SaveRenderResult writes the captured result as JSON for inspection.

Failure Behavior

Nonzero render and run exits return both the captured result and an error containing the exit code and stderr. Run exit code 2 is treated as an error but may still produce a report artifact. Command execution respects context cancellation and the configured timeout.

Tests

Inspect:

• internal/adapters/scriptorium/runner_test.go
• internal/app/app_test.go
• internal/cli/root_test.go

Invariants

• scriptorium details stay inside the adapter package.
• The input name for prompt packages is always data_package.
• Render preflight remains orchestration behavior; this adapter only exposes the subprocess operations.