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 or structured generated-text output. 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
• YAML prompt input data package path
• report output path for run
• raw generated-text output path for structured 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
• raw generated-text output path for structured 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, Markdown run, and structured generated-text run operations. State persistence uses state-owned artifact shapes; app orchestration converts adapter 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>

Structured generated-text argv uses the same scriptorium run form, with the --out value set to the raw generated-text JSON artifact path. The adapter does not add --format, schema path, or JSON Schema flags for structured generation; Scriptorium selects the structured output schema from prompt configuration.

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, Markdown run, and structured 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, Markdown run, and structured 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.
• The file at the data package path is YAML produced by internal/promptinput.
• Render, Markdown run, and structured run preserve command-specific result structs.
• Scriptorium-specific flags stay inside adapter and config boundaries.