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](../integrations/scriptorium.md) 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.