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

None directly. The adapter returns render and run results; app orchestration and state 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.