99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
# Scriptorium Integration
|
|
|
|
This document describes the external Scriptorium CLI contract used by
|
|
`weatherreporter`.
|
|
|
|
## Purpose
|
|
|
|
`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
|
|
and generate Markdown reports. This page documents the CLI surface the adapter
|
|
uses, not the full Scriptorium product.
|
|
|
|
## Commands Used
|
|
|
|
Render preflight:
|
|
|
|
```bash
|
|
scriptorium render \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--format json
|
|
```
|
|
|
|
Report generation:
|
|
|
|
```bash
|
|
scriptorium run \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--out <artifact_path>
|
|
```
|
|
|
|
`weatherreporter` always passes prompt input as
|
|
`--input data_package=<path>`. The data package is structured YAML created by
|
|
`internal/promptinput`; module snapshots remain separate JSON artifacts for
|
|
inspection and Recent Changes.
|
|
|
|
## Configured Arguments
|
|
|
|
The adapter can prepend configured flags before prompt-specific arguments:
|
|
|
|
- `--config <path>` from `scriptorium.config_path`
|
|
- `--profile <profile>` from `scriptorium.profile`
|
|
|
|
It appends `scriptorium.extra_args` after the built-in arguments. Extra
|
|
arguments are passed directly as argv items.
|
|
|
|
`scriptorium.binary` selects the executable name or path. If unset inside the
|
|
adapter, it falls back to `scriptorium`.
|
|
|
|
## Execution Behavior
|
|
|
|
The adapter runs Scriptorium without shell interpolation. Arguments are passed
|
|
through `exec.CommandContext`.
|
|
|
|
`scriptorium.timeout` limits each subprocess call when configured. Context
|
|
cancellation or timeout returns an execution error.
|
|
|
|
Stdout and stderr are captured separately. Each stream is capped at 1 MiB and
|
|
the result records whether truncation occurred.
|
|
|
|
## Results
|
|
|
|
Render results include:
|
|
|
|
- full argv recorded as `command`
|
|
- stdout
|
|
- stderr
|
|
- exit code
|
|
- truncation flags when applicable
|
|
|
|
Run results include the same fields plus the requested output path.
|
|
|
|
`weatherreporter` persists render preflight JSON when orchestration reaches the
|
|
preflight save point. The final Markdown artifact is written by Scriptorium to
|
|
the `--out` path.
|
|
|
|
## Failure Behavior
|
|
|
|
The adapter validates required request fields before starting Scriptorium:
|
|
|
|
- prompt ID
|
|
- data package path
|
|
- output path for `run`
|
|
|
|
Nonzero exits return both the captured result and an error containing the exit
|
|
code and stderr. A `run` exit code such as `2` is still treated as an error by
|
|
the adapter, even if Scriptorium wrote output to the requested artifact path.
|
|
|
|
Subprocess start failures, context cancellation, and timeouts return errors
|
|
without fabricating a successful result.
|
|
|
|
## Security Notes
|
|
|
|
- The adapter does not invoke a shell.
|
|
- Generated artifacts, rendered prompt context, stdout, and stderr can contain
|
|
operationally sensitive data.
|
|
- API keys should be provided through the Scriptorium environment or
|
|
Scriptorium configuration, not through `weatherreporter` CLI arguments.
|