101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
# 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. 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
|
|
- prompt input data package path
|
|
- report output path for `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`
|
|
|
|
## 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 and run operations.
|
|
State persistence uses a state-owned preflight artifact shape; app
|
|
orchestration converts render 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>
|
|
```
|
|
|
|
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 and 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 and 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`.
|
|
- Render and run preserve command-specific result structs.
|
|
- Scriptorium-specific flags stay inside adapter and config boundaries.
|