Documentation
¶
Overview ¶
Package prescript implements the pre-script output protocol (issue #4718).
fullsend run hands the harness pre-script an output file path via the FULLSEND_PRESCRIPT_OUTPUT environment variable. The script may append key=value lines to that file — most notably "skipped=true" plus an optional "reason=..." — which fullsend run reads back after the script exits. When skipped=true, fullsend run reports a "skipped" status and exits successfully before creating the sandbox.
The protocol is specified normatively in docs/normative/prescript-output/v1; that document, not this comment, is what pre-script authors write against. The summary below is a convenience for readers of this package.
Version skew is the same class of concern as ADR 0062, and is handled asymmetrically — deliberately, because the two directions have different costs:
- Old script, new CLI: the script never writes to the file, which parses to a Result with Skipped false and no outputs — exactly today's behavior.
- New script, old CLI: FULLSEND_PRESCRIPT_OUTPUT is unset, so the script cannot signal a skip and the agent runs anyway (a duplicate run — this direction fails open). Scripts must guard on the variable being unset, the same pattern as the existing GITHUB_OUTPUT guard in the scaffold scripts.
Malformed content is a hard error, not a silent proceed: a typo like "skipped true" silently ignored would let a duplicate agent run start — the exact failure mode the pre-checks exist to prevent. Values that case-insensitively match a reserved key but differ in case (SKIPPED=true) are rejected for the same reason.
Supported syntax (line-based):
skipped=true reason=an open PR already addresses this issue # comments and blank lines are ignored
The format resembles GITHUB_OUTPUT but is not compatible with it: there is no quoting, and the "key<<DELIMITER" heredoc form for multiline values is not supported. Values are single-line and may not contain control characters. Surrounding whitespace around both key and value is not significant. Later assignments to the same key win.
Index ¶
Constants ¶
const EnvVar = "FULLSEND_PRESCRIPT_OUTPUT"
EnvVar is the environment variable through which fullsend run passes the output file path to the pre-script. Scripts must guard on it being unset (older CLI versions do not export it).
Variables ¶
This section is empty.
Functions ¶
func LogLine ¶
LogLine renders the outputs as a single stable, sorted line for the run log, so non-GitHub CIs (and local runs) can still see what the pre-script reported. Returns "" when there is nothing to show, or when an output would break the single-line rendering.
func Prepare ¶
Prepare creates the file the pre-script writes its outputs to, inside dir. Using the run directory rather than the system temp directory keeps the file out of reach of tmp reapers during a long pre-script. The cleanup func removes the file and never fails loudly.
func Relay ¶
Relay surfaces the pre-script outputs to the surrounding CI system so remaining workflow-level gating (if any) can consume them. Today only GitHub Actions is detected; other CIs get the outputs in the run log only (fullsend run logs them on every path). Returns whether a relay target was found.
Callers must invoke Relay on both the skip and proceed paths: the skipped key is always written (normalized to "true"/"false") so consumers can gate on its value, and an absent key means the CLI predates this protocol rather than "not skipped".
Types ¶
type Result ¶
type Result struct {
// Skipped is true when the pre-script wrote skipped=true, requesting
// that fullsend run stop before sandbox creation.
Skipped bool
// Reason is the optional human-readable reason accompanying a skip.
Reason string
// Outputs holds every key=value pair the script wrote, including
// skipped and reason, with later assignments overriding earlier ones.
Outputs map[string]string
}
Result is the parsed pre-script output.
func ParseFile ¶
ParseFile reads a pre-script output file. An empty file yields a Result with Skipped false and no outputs (proceed). Malformed lines, invalid keys, values containing control characters, and skipped values other than "true"/"false" are hard errors.
A missing file is also a hard error: Prepare creates the file before the script runs, so its absence afterwards means something removed it, and treating that as "proceed" is the silent-proceed failure this protocol exists to prevent.