Refresh Scriptorium integration guide
This commit is contained in:
@@ -1,118 +1,91 @@
|
||||
# Scriptorium Integration
|
||||
|
||||
This document describes the external Scriptorium CLI contract used by
|
||||
`weatherreporter`.
|
||||
`weatherreporter` invokes the Scriptorium executable as a subprocess to
|
||||
preflight prompt input and produce report artifacts. This is the limited CLI
|
||||
contract Weatherreporter uses, not general Scriptorium documentation.
|
||||
|
||||
## Purpose
|
||||
## Invocation
|
||||
|
||||
`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
|
||||
and generate report artifacts. This page documents the CLI surface the adapter
|
||||
uses, not the full Scriptorium product.
|
||||
The configured `scriptorium.binary` is the executable name or path. When it is
|
||||
empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
|
||||
process, without a shell.
|
||||
|
||||
## Commands Used
|
||||
For every command, arguments occur in this order:
|
||||
|
||||
Render preflight:
|
||||
1. The subcommand.
|
||||
2. `--config <path>` when `scriptorium.config_path` is set.
|
||||
3. `--profile <profile>` when `scriptorium.profile` is set.
|
||||
4. The command-specific arguments below.
|
||||
5. Each configured `scriptorium.extra_args` item.
|
||||
|
||||
```bash
|
||||
scriptorium render \
|
||||
--prompt <prompt_id> \
|
||||
--input data_package=<path> \
|
||||
--format json
|
||||
The adapter uses these exact command shapes:
|
||||
|
||||
```text
|
||||
scriptorium render [--config <path>] [--profile <profile>] \
|
||||
--prompt <prompt_id> --input data_package=<data_package_path> --format json \
|
||||
[<extra_arg> ...]
|
||||
|
||||
scriptorium run [--config <path>] [--profile <profile>] \
|
||||
--prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
|
||||
[<extra_arg> ...]
|
||||
```
|
||||
|
||||
Report generation:
|
||||
`render` is the preflight command. `run` writes either a Markdown report or a
|
||||
raw generated-text artifact to the supplied `--out` path. The structured
|
||||
generated-text use of `run` has the same argv as Markdown generation; it does
|
||||
not add `--format`, `--schema`, `--schema-path`, or `--json-schema` flags.
|
||||
Prompt configuration selected by `<prompt_id>` controls that output.
|
||||
|
||||
```bash
|
||||
scriptorium run \
|
||||
--prompt <prompt_id> \
|
||||
--input data_package=<path> \
|
||||
--out <artifact_path>
|
||||
```
|
||||
## Inputs and Outputs
|
||||
|
||||
Structured generated-text report generation uses the same command shape:
|
||||
Weatherreporter always supplies exactly one prompt input:
|
||||
`--input data_package=<data_package_path>`. The path identifies the YAML data
|
||||
package produced by the [prompt-input builder](../internal/prompt-input.md).
|
||||
Its schema and the separate JSON module snapshots are internal artifacts, not
|
||||
part of this CLI contract.
|
||||
|
||||
```bash
|
||||
scriptorium run \
|
||||
--prompt <prompt_id> \
|
||||
--input data_package=<path> \
|
||||
--out <generated_text_raw_path>
|
||||
```
|
||||
The application supplies an already-managed output path to every `run` call.
|
||||
For direct reports it is the Markdown artifact path. For generated-text
|
||||
reports it is the raw JSON artifact path; subsequent validation and Markdown
|
||||
rendering are owned by [generated-text processing](../internal/generatedtext.md).
|
||||
|
||||
`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.
|
||||
`render` has no output-path argument. Its JSON-formatted stdout remains
|
||||
captured output: the adapter records it and does not parse it into a separate
|
||||
CLI result type. Likewise, the adapter records `run` output metadata without
|
||||
decoding the artifact written at `--out`.
|
||||
|
||||
For generated-text reports, Scriptorium selects the structured output schema
|
||||
from the prompt configuration associated with the prompt ID. `weatherreporter`
|
||||
does not pass `--format`, schema path, or JSON Schema flags for structured
|
||||
generation.
|
||||
## Execution and Results
|
||||
|
||||
## Configured Arguments
|
||||
`scriptorium.timeout`, when greater than zero, creates a timeout for each
|
||||
subprocess invocation. Parent-context cancellation and that timeout stop the
|
||||
command through the process context.
|
||||
|
||||
The adapter can prepend configured flags before prompt-specific arguments:
|
||||
Stdout and stderr are captured independently, each up to 1 MiB. Every returned
|
||||
result records the complete argv as `command`, the captured `stdout` and
|
||||
`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream
|
||||
was capped. Results from both forms of `run` also record `outputPath`, the
|
||||
requested `--out` value.
|
||||
|
||||
- `--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. Structured
|
||||
generated-text run results use the same captured fields and output-path
|
||||
recording, with the output path pointing at the raw generated-text JSON
|
||||
artifact.
|
||||
|
||||
`weatherreporter` persists render preflight JSON when orchestration reaches the
|
||||
preflight save point. For direct Markdown reports, Scriptorium writes the
|
||||
managed Markdown artifact to the `--out` path. For generated-text-template
|
||||
reports, Scriptorium writes raw JSON to the `--out` path; later
|
||||
weatherreporter workflow steps validate those bytes and render Markdown from an
|
||||
embedded template.
|
||||
The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
|
||||
execution and result capture. [Application orchestration](../internal/app-orchestration.md)
|
||||
owns when preflight output, report artifacts, and generated-text artifacts are
|
||||
persisted.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
The adapter validates required request fields before starting Scriptorium:
|
||||
Before starting Scriptorium, the adapter requires a prompt ID and data-package
|
||||
path for every command, plus an output path for `run`. Missing fields fail
|
||||
without executing a subprocess.
|
||||
|
||||
- prompt ID
|
||||
- data package path
|
||||
- output path for `run` and structured generated-text `run`
|
||||
A nonzero process exit returns the captured result and an error that includes
|
||||
the exit code and stderr. An output file written before such an exit does not
|
||||
make the request successful. Failures to start the command, context
|
||||
cancellation, and timeout return an error rather than a successful result.
|
||||
|
||||
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.
|
||||
## Operational Notes
|
||||
|
||||
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.
|
||||
- Extra arguments are argv items; they are not shell-interpreted.
|
||||
- Prompt input, generated artifacts, stdout, and stderr can contain
|
||||
operationally sensitive weather data.
|
||||
- Provide API keys through the Scriptorium environment or its configuration,
|
||||
not through Weatherreporter CLI arguments.
|
||||
|
||||
Reference in New Issue
Block a user