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,
collect 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:

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

Report generation argv starts with:

```text
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.