Module script 

The script action (07-03, SCRPT-01) — ign script run, the smallest verb in the CLI: one action over the already-shipped, already-secured scriptExec route (05-01’s template, 05-03’s deploy/secret lifecycle).

The opt-in is STRUCTURAL, not a flag: scriptExec deploys ONLY via ign webdev deploy --with-script-exec, whose deploy persists a 32-byte hex secret in the profile config at 0600 BEFORE upload. script_run resolves that secret FIRST — no stored secret means the route was never deployed, and the verb refuses with the additive script_exec_not_configured (exit 6) naming the deploy flag verbatim. There is NO --yes guard on script run (the research-adopted decision): the deploy flag IS the opt-in, the verb is the route’s entire purpose, and agents need it non-interactive.

Sequence per invocation (two round trips, the 05-04 precondition’s correctness-over-latency precedent):

1. Precondition handshake — the version action WITH the secret header. The 200-BODY envelope is the only success oracle (WebDev ignores status; denials ride 200); a secret_required/secret_mismatch denial surfaces honestly through the existing webdev error family — a mismatch means the route was deployed elsewhere/stale, and the hint already says redeploy or --rotate-secret. No new slug, no version-compare magic (the tags precondition owns that discrimination for its family; scriptExec’s gate IS the secret).
2. Exec — {"action": "exec", "code": <code>} with the secret header. A route error body ({ok:false, error{code,message,traceback?}} at HTTP 200) maps through the same denial seam with the traceback surfaced (the 05-08 pattern) — a route-side Python exception is a black box no more.

Timeout honesty (planner decision): v1.0.0’s route has NO server-side timeout — the client rides the existing per-request class, and a long-running script simply holds the HTTP connection (README documents this).

read_script_input is the PURE three-form input reader (--code STR, --file PATH, --file - stdin — the agent pipe path), unit-tested separately from the async action: usage-class errors lead (exit 2, the 03-03 put convention).

Structs

ScriptRunResult

ign script run result — the route’s exec answer under unit-explicit keys, ALL keys always (the family convention: agents never key-hunt). The secret appears in NONE of them (redaction — the 05-03 canary extended to this surface).

Functions

read_script_input

The three-form input reader (PURE — no async, no gateway): --code STR passes through, --file PATH reads the file, --file - reads stdin (the agent pipe path). Both --code AND --file given → InvalidInput (usage errors lead — the caller runs this BEFORE profile resolution, exit 2, profile null); neither given → InvalidInput; unreadable file/stdin → InvalidInput (the 03-03 put convention: the reason names the source).

script_run

ign script run — resolve the profile’s stored scriptExec secret, prove the route answers it, execute the code.