weatherreporter/docs/internal/scriptorium-adapter.md

Scriptorium Adapter Internals

This document describes the subprocess adapter in internal/adapters/scriptorium.

Purpose

The adapter runs scriptorium render for prompt preflight and scriptorium run for Markdown report generation. It isolates subprocess execution, argv construction, timeout handling, output capture, and exit-code interpretation from app and domain packages.

Inputs And Outputs

Inputs:

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

Outputs:

• argv used for execution
• captured stdout and stderr
• truncation flags for captured output
• exit code
• report output path for run

Boundaries

internal/adapters/scriptorium owns Scriptorium command construction and subprocess execution. It does not choose report types, build prompt input, fetch weather data, decide workflow order, or persist workflow metadata.

The adapter exposes request and result structs for render and run operations. State persistence uses a state-owned preflight artifact shape; app orchestration converts render results before saving.

Config Fields Used

• scriptorium.binary
• scriptorium.config_path
• scriptorium.profile
• scriptorium.timeout
• scriptorium.extra_args

Commands

Render preflight argv starts with:

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

Report generation argv starts with:

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

Configured --config and --profile flags are inserted after the subcommand and before prompt-specific arguments. Extra arguments are appended after the built-in arguments.

Execution Behavior

The adapter runs commands without shell interpolation. The same private execution path is used by render and run after command-specific request validation and argv construction.

When scriptorium.timeout is greater than zero, each subprocess call uses a context with that timeout. Stdout and stderr are captured separately, capped at 1 MiB each, and marked as truncated when the cap is reached.

Failure Behavior

• Missing prompt ID or data package path returns an error before subprocess execution.
• Missing run output path returns an error before subprocess execution.
• Subprocess start errors, context cancellation, and timeouts are wrapped with operation context by the caller-facing method.
• Nonzero render and run exits return the captured result plus an error containing the exit code and stderr.

Tests

Inspect:

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

Invariants

• No shell interpolation is used.
• The Scriptorium input name is data_package.
• Render and run preserve command-specific result structs.
• Scriptorium-specific flags stay inside adapter and config boundaries.