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 while isolating subprocess details from 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

Outputs:

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

Boundaries

• This adapter owns Scriptorium argv construction and subprocess execution.
• It does not choose report types, build prompt input, fetch weather data, decide workflow order, or persist workflow metadata.

Config Fields Used

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

External Adapters Used

• external scriptorium CLI

See Scriptorium integration for the external CLI contract used by this project.

State Or Manifest Behavior

SaveRenderResult can write render results atomically. The app and state store own managed preflight paths and metadata links.

Skip And Resume Behavior

None. Context cancellation and configured timeout stop subprocess execution.

Failure Behavior

• Missing prompt ID, data package path, or run output path returns an error.
• Subprocess start or context errors are wrapped with operation context.
• Nonzero render and run exits return captured output plus an error containing exit code and stderr.
• Captured stdout and stderr are size-limited and marked when truncated.

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.
• Scriptorium-specific flags stay inside adapter and config boundaries.