@jevitate/cli 0.1.0 → 0.3.0

package/dist/mission-fixtures.js

@@ -0,0 +1,862 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { redactText, redactUrl } from "@jevitate/ai-core";
+import { isAuthorizedExploreTarget } from "@jevitate/explore";
+import { authHeaders } from "./fixture-auth.js";
+import { clock } from "@jevitate/domain";
+/**
+ * Mission fixtures (#140 declarative app setup, #144 setup/restore around missions and replays) —
+ * ONE capability: put the app into a known state before a mission, bind what that setup created
+ * (an item id, an invite URL) into the run as `${setup.<name>}`, restore the state afterwards, and
+ * do the same around EVERY replay (hang reproduction, `verify-fix`, regression capture) so a replay
+ * starts from the state the finding was made in, not whatever earlier runs left behind.
+ *
+ * Two step kinds, both operator-declared:
+ *
+ *  - HTTP steps, from a fixtures JSON file (`--fixtures`, or `fixtures` in `~/.jevitate/targets.json`).
+ *    Only to an `--allow`-listed http(s) origin; authenticated like the page is (`fixture-auth.ts`:
+ *    a storageState localStorage bearer, its cookies, or a `--secret-field` binding). A file can
+ *    never declare a command. A step's json/body/headers may use `${secretField.<VAR>}` (#166) —
+ *    the run's `--secret-field` value bound to env `<VAR>`, so a login step can authenticate; it
+ *    is put on the wire only (never in a URL, the step log, the result or the Recording).
+ *  - Shell hooks, from the operator's own CLI flags only (`--before <cmd>` / `--after <cmd>`, and
+ *    only with `--allow-shell-hooks`). Never model-chosen, never read from a file a run wrote. Exit
+ *    codes are recorded; stdout is never persisted (it may carry `{vars, secret}`), stderr only
+ *    redacted and clipped.
+ *
+ * Fail closed: a setup that fails, times out, or leaves a `${setup.x}` reference unresolved ends
+ * the run `inconclusive` (`fixture setup failed: …`, a configuration error) — a mission never runs
+ * on unknown state. Secret outputs join the run's redaction set and may only be used inside the
+ * fixture's own requests, never in text a model sees.
+ */
+export const SETUP_REF = /\$\{setup\.([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * `${secretField.<VAR>}` (#166): a run's `--secret-field` value (bound to env `<VAR>`), allowed only
+ * in a step's `json`/`body`/`headers` — so a login step can authenticate. Substituted into the
+ * outgoing request only: never into a URL, the step log, the result or the Recording.
+ */
+export const SECRET_FIELD_REF = /\$\{secretField\.([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Either reference, matched in ONE pass (a substituted value is never re-expanded). */
+const STEP_REF = /\$\{(setup|secretField)\.([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const OUTPUT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A fixture identity's name (#243) — the same shape as a persona/actor name. */
+const IDENTITY_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+/** Keys that would make a fixtures file run a command: refused anywhere in a step. */
+const COMMAND_KEYS = new Set(["command", "cmd", "shell", "exec", "run", "script", "argv", "spawn", "before", "after"]);
+const STEP_KEYS = new Set(["name", "method", "url", "headers", "json", "body", "auth", "expectStatus", "outputs", "secretOutputs", "timeoutMs"]);
+/** Literal credentials would be persisted with the spec: auth comes from the run's session instead. */
+const CREDENTIAL_HEADERS = new Set(["authorization", "cookie", "proxy-authorization", "x-api-key"]);
+const DEFAULT_STEP_TIMEOUT_MS = 30_000;
+const DEFAULT_HOOK_TIMEOUT_MS = 60_000;
+const MAX_HOOK_STDOUT = 64 * 1024;
+const MAX_LOGGED_OUTPUT = 1_000;
+export class FixtureSpecError extends Error {
+    code = "E_FIXTURE_SPEC";
+    constructor(message) {
+        super(message);
+        this.name = "FixtureSpecError";
+    }
+}
+/** Setup failed: the run must end `inconclusive` (a configuration error) without touching the app. */
+export class FixtureSetupError extends Error {
+    code = "E_FIXTURE_SETUP";
+    constructor(detail) {
+        super(`fixture setup failed: ${detail}`);
+        this.name = "FixtureSetupError";
+    }
+}
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** Every `${setup.x}` name referenced in `text`. */
+export function referencedNames(text) {
+    return [...text.matchAll(SETUP_REF)].map((m) => m[1]);
+}
+/**
+ * Every `--secret-field` env variable a spec needs (#166): the `auth: {from: "secretField"}` names
+ * and every `${secretField.<VAR>}` in a step's json/body/headers.
+ */
+export function secretFieldNames(spec) {
+    const names = new Set();
+    for (const s of [...(spec?.setup ?? []), ...(spec?.restore ?? [])]) {
+        if (s.auth?.from === "secretField")
+            names.add(s.auth.name);
+        for (const text of stringsIn([s.headers ?? {}, s.json ?? null, s.body ?? ""])) {
+            for (const m of text.matchAll(SECRET_FIELD_REF))
+                names.add(m[1]);
+        }
+    }
+    return [...names];
+}
+/** Every fixture identity (#243) a spec's steps authenticate as (`auth.identity`). */
+export function identityNames(spec) {
+    const names = new Set();
+    for (const s of [...(spec?.setup ?? []), ...(spec?.restore ?? [])]) {
+        if (s.auth !== undefined && s.auth.from !== "secretField" && s.auth.identity !== undefined)
+            names.add(s.auth.identity);
+    }
+    return [...names];
+}
+/** A header value that is only references (and at most a scheme word) holds no literal credential. */
+function onlyReferences(value) {
+    if (value.search(STEP_REF) === -1)
+        return false;
+    return /^([A-Za-z-]+)?$/.test(value.replace(STEP_REF, "").trim());
+}
+function stringsIn(v, out = []) {
+    if (typeof v === "string")
+        out.push(v);
+    else if (Array.isArray(v))
+        for (const x of v)
+            stringsIn(x, out);
+    else if (isRecord(v))
+        for (const x of Object.values(v))
+            stringsIn(x, out);
+    return out;
+}
+function findCommandKey(v, path) {
+    if (Array.isArray(v)) {
+        for (const [i, x] of v.entries()) {
+            const hit = findCommandKey(x, `${path}[${i}]`);
+            if (hit !== null)
+                return hit;
+        }
+    }
+    else if (isRecord(v)) {
+        for (const [k, x] of Object.entries(v)) {
+            if (COMMAND_KEYS.has(k.toLowerCase()))
+                return `${path}.${k}`;
+            // `json` is an opaque request body: its keys are the app's, not ours.
+            if (k === "json")
+                continue;
+            const hit = findCommandKey(x, `${path}.${k}`);
+            if (hit !== null)
+                return hit;
+        }
+    }
+    return null;
+}
+function resolveStepUrl(url, baseUrl) {
+    try {
+        return new URL(url, baseUrl);
+    }
+    catch {
+        return null;
+    }
+}
+/** Throws unless `url` (with references substituted) is an http(s) URL on an allowlisted origin. */
+function assertStepUrl(url, bounds, where) {
+    const u = resolveStepUrl(url, bounds.baseUrl);
+    if (u === null || (u.protocol !== "http:" && u.protocol !== "https:")) {
+        throw new FixtureSpecError(`${where}.url must be an http(s) URL (got ${JSON.stringify(redactUrl(url))})`);
+    }
+    if (!isAuthorizedExploreTarget(u.href, bounds.allowlist)) {
+        throw new FixtureSpecError(`${where}.url origin ${u.origin} is not an --allow origin (${[...bounds.allowlist].join(", ")})`);
+    }
+}
+function parseAuth(v, where) {
+    if (!isRecord(v) || typeof v.from !== "string")
+        throw new FixtureSpecError(`${where} must be {from: "localStorage"|"cookies"|"secretField", ...}`);
+    const opt = (k) => {
+        const x = v[k];
+        if (x === undefined)
+            return undefined;
+        if (typeof x !== "string")
+            throw new FixtureSpecError(`${where}.${k} must be a string`);
+        return x;
+    };
+    const allowed = (keys) => {
+        for (const k of Object.keys(v))
+            if (!keys.includes(k))
+                throw new FixtureSpecError(`${where}.${k} is not a known auth key`);
+    };
+    const scheme = opt("scheme");
+    const header = opt("header");
+    const extra = { ...(scheme === undefined ? {} : { scheme }), ...(header === undefined ? {} : { header: header.toLowerCase() }) };
+    // #243: authenticate this step as a NAMED identity (its own storageState), not the mission's session.
+    const identity = opt("identity");
+    if (identity !== undefined && !IDENTITY_NAME.test(identity)) {
+        throw new FixtureSpecError(`${where}.identity must be an identity name (1-64 of [A-Za-z0-9_.-], starting alphanumeric)`);
+    }
+    const as = identity === undefined ? {} : { identity };
+    if (v.from === "cookies") {
+        allowed(["from", "identity"]);
+        return { from: "cookies", ...as };
+    }
+    if (v.from === "localStorage") {
+        allowed(["from", "key", "scheme", "header", "identity"]);
+        const key = opt("key");
+        if (key === undefined || key === "")
+            throw new FixtureSpecError(`${where}.key (the localStorage item) is required`);
+        return { from: "localStorage", key, ...extra, ...as };
+    }
+    if (v.from === "secretField") {
+        allowed(["from", "name", "scheme", "header"]);
+        const name = opt("name");
+        if (name === undefined || name === "")
+            throw new FixtureSpecError(`${where}.name (the --secret-field env variable) is required`);
+        return { from: "secretField", name, ...extra };
+    }
+    throw new FixtureSpecError(`${where}.from must be localStorage, cookies or secretField`);
+}
+function parseStep(v, where, bounds, known, phase) {
+    if (!isRecord(v))
+        throw new FixtureSpecError(`${where} must be an object`);
+    const cmd = findCommandKey(v, where);
+    if (cmd !== null) {
+        throw new FixtureSpecError(`${cmd}: a fixtures file cannot declare a command — shell hooks are the operator's own flags (--before/--after with --allow-shell-hooks)`);
+    }
+    for (const k of Object.keys(v))
+        if (!STEP_KEYS.has(k))
+            throw new FixtureSpecError(`${where}.${k} is not a known step key`);
+    const method = typeof v.method === "string" ? v.method.toUpperCase() : "";
+    if (!METHODS.has(method))
+        throw new FixtureSpecError(`${where}.method must be one of ${[...METHODS].join(", ")}`);
+    if (typeof v.url !== "string" || v.url === "")
+        throw new FixtureSpecError(`${where}.url is required`);
+    // A URL is logged and persisted: a secret never goes there (#166).
+    if (v.url.search(SECRET_FIELD_REF) !== -1) {
+        throw new FixtureSpecError(`${where}.url: \${secretField.*} is allowed only in json, body or headers (a URL is logged)`);
+    }
+    // A reference may fill a path or query value, never choose the origin: check it with placeholders.
+    assertStepUrl(v.url.replace(SETUP_REF, "0"), bounds, where);
+    const u = resolveStepUrl(v.url.replace(SETUP_REF, "0"), bounds.baseUrl);
+    const probe = resolveStepUrl(v.url.replace(SETUP_REF, "x.evil.test"), bounds.baseUrl);
+    if (u === null || probe === null || probe.origin !== u.origin)
+        throw new FixtureSpecError(`${where}.url: a \${setup.*} reference cannot choose the origin`);
+    let headers;
+    if (v.headers !== undefined) {
+        if (!isRecord(v.headers))
+            throw new FixtureSpecError(`${where}.headers must be an object of strings`);
+        headers = {};
+        for (const [k, x] of Object.entries(v.headers)) {
+            if (typeof x !== "string")
+                throw new FixtureSpecError(`${where}.headers.${k} must be a string`);
+            // A credential header may only be references (`Bearer ${setup.token}`, `${secretField.API_KEY}`, #166).
+            if (CREDENTIAL_HEADERS.has(k.toLowerCase()) && !onlyReferences(x)) {
+                throw new FixtureSpecError(`${where}.headers.${k}: no literal credentials in a fixtures file — use "auth" (storage state or --secret-field), \${secretField.<VAR>} or a secret \${setup.<name>}`);
+            }
+            headers[k] = x;
+        }
+    }
+    if (v.json !== undefined && v.body !== undefined)
+        throw new FixtureSpecError(`${where}: give json or body, not both`);
+    if (v.body !== undefined && typeof v.body !== "string")
+        throw new FixtureSpecError(`${where}.body must be a string`);
+    let expectStatus;
+    if (v.expectStatus !== undefined) {
+        if (!Array.isArray(v.expectStatus) || v.expectStatus.length === 0 || !v.expectStatus.every((s) => Number.isInteger(s) && s >= 100 && s <= 599)) {
+            throw new FixtureSpecError(`${where}.expectStatus must be a non-empty array of HTTP status codes`);
+        }
+        expectStatus = v.expectStatus;
+    }
+    if (v.timeoutMs !== undefined && !(Number.isInteger(v.timeoutMs) && v.timeoutMs > 0)) {
+        throw new FixtureSpecError(`${where}.timeoutMs must be a positive integer`);
+    }
+    let outputs;
+    if (v.outputs !== undefined) {
+        if (phase === "restore")
+            throw new FixtureSpecError(`${where}.outputs: only setup steps bind outputs`);
+        if (!isRecord(v.outputs))
+            throw new FixtureSpecError(`${where}.outputs must be an object of name → "$.path" | "header:<name>"`);
+        outputs = {};
+        for (const [name, path] of Object.entries(v.outputs)) {
+            if (!OUTPUT_NAME.test(name))
+                throw new FixtureSpecError(`${where}.outputs.${name}: output names are identifiers`);
+            if (typeof path !== "string" || !(path.startsWith("$") || path.startsWith("header:"))) {
+                throw new FixtureSpecError(`${where}.outputs.${name} must be "$.path" or "header:<name>"`);
+            }
+            if (path.startsWith("$"))
+                parseJsonPath(path, `${where}.outputs.${name}`);
+            outputs[name] = path;
+        }
+    }
+    let secretOutputs;
+    if (v.secretOutputs !== undefined) {
+        if (!Array.isArray(v.secretOutputs) || !v.secretOutputs.every((s) => typeof s === "string" && outputs?.[s] !== undefined)) {
+            throw new FixtureSpecError(`${where}.secretOutputs must name this step's own outputs`);
+        }
+        secretOutputs = v.secretOutputs;
+    }
+    const step = {
+        ...(typeof v.name === "string" ? { name: v.name } : {}),
+        method,
+        url: v.url,
+        ...(headers === undefined ? {} : { headers }),
+        ...(v.json === undefined ? {} : { json: v.json }),
+        ...(v.body === undefined ? {} : { body: v.body }),
+        ...(v.auth === undefined ? {} : { auth: parseAuth(v.auth, `${where}.auth`) }),
+        ...(expectStatus === undefined ? {} : { expectStatus }),
+        ...(outputs === undefined ? {} : { outputs }),
+        ...(secretOutputs === undefined ? {} : { secretOutputs }),
+        ...(v.timeoutMs === undefined ? {} : { timeoutMs: v.timeoutMs }),
+    };
+    if (known !== null) {
+        for (const s of stringsIn([step.url, step.headers ?? {}, step.json ?? null, step.body ?? ""])) {
+            for (const name of referencedNames(s)) {
+                if (!known.has(name))
+                    throw new FixtureSpecError(`${where} references \${setup.${name}}, which no earlier setup step outputs`);
+            }
+        }
+    }
+    return step;
+}
+/**
+ * Validates a fixtures spec (fail closed, before any browser or request). `openRefs` allows
+ * references a `--before` hook may bind at run time (unknown statically; still checked when used).
+ */
+export function parseFixtureSpec(raw, bounds, opts = {}) {
+    if (!isRecord(raw))
+        throw new FixtureSpecError("a fixtures spec must be a JSON object {setup, restore}");
+    const cmd = findCommandKey(Object.fromEntries(Object.entries(raw).filter(([k]) => k !== "setup" && k !== "restore" && k !== "teardown")), "fixtures");
+    if (cmd !== null) {
+        throw new FixtureSpecError(`${cmd}: a fixtures file cannot declare a command — shell hooks are the operator's own flags (--before/--after with --allow-shell-hooks)`);
+    }
+    for (const k of Object.keys(raw)) {
+        if (!["name", "setup", "restore", "teardown", "version"].includes(k))
+            throw new FixtureSpecError(`fixtures.${k} is not a known key`);
+    }
+    if (raw.version !== undefined && raw.version !== 1)
+        throw new FixtureSpecError("fixtures.version must be 1");
+    if (raw.restore !== undefined && raw.teardown !== undefined)
+        throw new FixtureSpecError("give restore or teardown (an alias), not both");
+    const list = (v, where) => {
+        if (v === undefined)
+            return [];
+        if (!Array.isArray(v))
+            throw new FixtureSpecError(`${where} must be an array of steps`);
+        return v;
+    };
+    const known = opts.openRefs === true ? null : new Set();
+    const outputsSeen = new Set();
+    const setup = list(raw.setup, "fixtures.setup").map((s, i) => {
+        const step = parseStep(s, `fixtures.setup[${i}]`, bounds, known, "setup");
+        for (const name of Object.keys(step.outputs ?? {})) {
+            if (outputsSeen.has(name))
+                throw new FixtureSpecError(`fixtures.setup[${i}].outputs.${name} is bound twice`);
+            outputsSeen.add(name);
+            known?.add(name);
+        }
+        return step;
+    });
+    const restoreKey = raw.teardown !== undefined ? "teardown" : "restore";
+    const restore = list(raw[restoreKey], `fixtures.${restoreKey}`).map((s, i) => parseStep(s, `fixtures.${restoreKey}[${i}]`, bounds, known, "restore"));
+    if (setup.length === 0 && restore.length === 0)
+        throw new FixtureSpecError("a fixtures spec needs at least one setup or restore step");
+    // A credential header built from a setup output needs that output to be SECRET: a public output
+    // is persisted with the result, and a credential never is.
+    if (known !== null) {
+        const secret = new Set(setup.flatMap((s) => s.secretOutputs ?? []));
+        for (const [phase, steps] of [["setup", setup], [restoreKey, restore]]) {
+            for (const [i, s] of steps.entries()) {
+                for (const [k, x] of Object.entries(s.headers ?? {})) {
+                    if (!CREDENTIAL_HEADERS.has(k.toLowerCase()))
+                        continue;
+                    for (const name of referencedNames(x)) {
+                        if (!secret.has(name))
+                            throw new FixtureSpecError(`fixtures.${phase}[${i}].headers.${k}: \${setup.${name}} carries a credential — list it in secretOutputs`);
+                    }
+                }
+            }
+        }
+    }
+    return { ...(typeof raw.name === "string" ? { name: raw.name } : {}), setup, restore };
+}
+/** Reads and validates a fixtures JSON file. */
+export function loadFixtureFile(path, bounds, opts = {}) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new FixtureSpecError(`cannot read fixtures file ${path}: ${e instanceof SyntaxError ? "not valid JSON" : e instanceof Error ? e.message : String(e)}`);
+    }
+    return parseFixtureSpec(raw, bounds, opts);
+}
+export function parseJsonPath(path, where = "path") {
+    if (!path.startsWith("$"))
+        throw new FixtureSpecError(`${where}: a JSON path starts with $`);
+    const segs = [];
+    const re = /\.([A-Za-z_$][A-Za-z0-9_$-]*)|\[(\d+)\]|\[\s*"([^"]*)"\s*\]|\[\s*'([^']*)'\s*\]/y;
+    let i = 1;
+    while (i < path.length) {
+        re.lastIndex = i;
+        const m = re.exec(path);
+        if (m === null)
+            throw new FixtureSpecError(`${where}: cannot parse ${JSON.stringify(path)} at offset ${i}`);
+        segs.push(m[1] ?? (m[2] !== undefined ? Number(m[2]) : (m[3] ?? m[4] ?? "")));
+        i = re.lastIndex;
+    }
+    return segs;
+}
+/** The scalar at `path` in `doc`, as a string; `undefined` when absent or not a scalar. */
+export function selectJsonPath(doc, path) {
+    let cur = doc;
+    for (const seg of parseJsonPath(path)) {
+        if (typeof seg === "number")
+            cur = Array.isArray(cur) ? cur[seg] : undefined;
+        else
+            cur = isRecord(cur) ? cur[seg] : undefined;
+    }
+    if (typeof cur === "string")
+        return cur;
+    if (typeof cur === "number" || typeof cur === "boolean")
+        return String(cur);
+    return undefined;
+}
+export class UnboundSetupRefError extends Error {
+    code = "E_FIXTURE_REF";
+    constructor(message) {
+        super(message);
+        this.name = "UnboundSetupRefError";
+    }
+}
+/**
+ * Substitutes every `${setup.x}` in `text`. An unknown name throws (never a hollow run); a SECRET
+ * output throws unless `allowSecret` — goal/URL/success text is model- or artifact-visible.
+ */
+export function substituteSetupRefs(text, b, opts = {}) {
+    return text.replace(SETUP_REF, (_whole, name) => {
+        const v = b.values[name];
+        if (v === undefined)
+            throw new UnboundSetupRefError(`${opts.where ?? "text"} references \${setup.${name}}, which the fixture setup did not output`);
+        if (b.secretNames.has(name) && opts.allowSecret !== true) {
+            throw new UnboundSetupRefError(`${opts.where ?? "text"} references the secret output \${setup.${name}}; secret outputs stay inside the fixture's own requests`);
+        }
+        return v;
+    });
+}
+/**
+ * A step's `json`/`body`/`headers` text with every `${setup.x}` and `${secretField.VAR}` filled in,
+ * in one pass (#166). The result goes on the wire ONLY — never into a log line or an artifact.
+ */
+function substituteStepText(text, b, secretFields, where) {
+    return text.replace(STEP_REF, (_whole, kind, name) => {
+        if (kind === "setup") {
+            const v = b.values[name];
+            if (v === undefined)
+                throw new UnboundSetupRefError(`${where} references \${setup.${name}}, which the fixture setup did not output`);
+            return v;
+        }
+        const v = secretFields[name];
+        if (v === undefined || v === "")
+            throw new UnboundSetupRefError(`${where} references \${secretField.${name}}, but the run has no --secret-field bound to env:${name}`);
+        return v;
+    });
+}
+function substituteDeep(v, sub) {
+    if (typeof v === "string")
+        return sub(v);
+    if (Array.isArray(v))
+        return v.map((x) => substituteDeep(x, sub));
+    if (isRecord(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, substituteDeep(x, sub)]));
+    return v;
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(",")}]`;
+    if (isRecord(v)) {
+        return `{${Object.keys(v)
+            .sort()
+            .filter((k) => v[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(v);
+}
+export function hookHash(cmd) {
+    return sha256(`hook:${cmd}`).slice(0, 16);
+}
+function clip(s, n = MAX_LOGGED_OUTPUT) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+function firstLine(e) {
+    const m = e instanceof Error ? e.message : String(e);
+    return m.split("\n")[0] ?? m;
+}
+function runHook(cmd, timeoutMs, stdin, env) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, { shell: true, detached: true, stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, ...env } });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const killGroup = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        const timer = clock.setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, timeoutMs);
+        child.stdout.on("data", (d) => {
+            if (stdout.length < MAX_HOOK_STDOUT)
+                stdout += d.toString("utf8");
+        });
+        child.stderr.on("data", (d) => {
+            if (stderr.length < MAX_HOOK_STDOUT)
+                stderr += d.toString("utf8");
+        });
+        child.on("error", (e) => {
+            clock.clearTimeout(timer);
+            resolve({ exitCode: null, timedOut, stdout, stderr: `${stderr}${e.message}` });
+        });
+        child.on("close", (code) => {
+            clock.clearTimeout(timer);
+            resolve({ exitCode: code, timedOut, stdout, stderr });
+        });
+        child.stdin.on("error", () => undefined);
+        child.stdin.end(stdin);
+    });
+}
+/**
+ * One mission's fixture lifecycle. `setup()` before the mission, `restore()` after it (every exit
+ * path), and `reset()` (restore the active state, then set up again) before each replay.
+ */
+export class MissionFixtures {
+    #opts;
+    #specHash;
+    #values = {};
+    #secretNames = new Set();
+    #active = false;
+    #cycles = 0;
+    #log = [];
+    constructor(opts) {
+        if (opts.hooks !== undefined && (opts.hooks.before !== undefined || opts.hooks.after !== undefined) && opts.allowShellHooks !== true) {
+            throw new FixtureSpecError("--before/--after run operator shell commands: pass --allow-shell-hooks to opt in");
+        }
+        // #166: every `${secretField.VAR}` must name a binding this run has — refused here, before any
+        // browser or request, like an unknown `${setup.x}`.
+        const bound = opts.auth.secretFields ?? {};
+        for (const [phase, steps] of [["setup", opts.spec?.setup ?? []], ["restore", opts.spec?.restore ?? []]]) {
+            for (const [i, s] of steps.entries()) {
+                for (const text of stringsIn([s.headers ?? {}, s.json ?? null, s.body ?? ""])) {
+                    for (const m of text.matchAll(SECRET_FIELD_REF)) {
+                        const v = bound[m[1]];
+                        if (v === undefined || v === "") {
+                            throw new FixtureSpecError(`fixtures.${phase}[${i}] references \${secretField.${m[1]}}, but the run has no --secret-field bound to env:${m[1]}`);
+                        }
+                    }
+                }
+            }
+        }
+        // #243: every `auth.identity` must be bound to a storageState file — refused here, before any
+        // browser or request (never a silent fall back to the mission's own session).
+        for (const name of identityNames(opts.spec)) {
+            if (opts.auth.identities?.[name] === undefined) {
+                throw new FixtureSpecError(`the fixture authenticates as identity ${name}, which is not bound: pass --fixture-identity ${name}=<storageState> or declare personas.${name}.storageState for this origin in targets.json`);
+            }
+        }
+        this.#opts = opts;
+        this.#specHash = sha256(canonical({ spec: opts.spec ?? null, hooks: this.hookHashes() ?? null })).slice(0, 16);
+    }
+    hookHashes() {
+        const h = this.#opts.hooks;
+        if (h?.before === undefined && h?.after === undefined)
+            return undefined;
+        return { ...(h.before === undefined ? {} : { before: hookHash(h.before) }), ...(h.after === undefined ? {} : { after: hookHash(h.after) }) };
+    }
+    get specHash() {
+        return this.#specHash;
+    }
+    /** The output names the spec declares; `null` when a `--before` hook may bind more at run time. */
+    declaredOutputs() {
+        if (this.#opts.hooks?.before !== undefined)
+            return null;
+        return new Set((this.#opts.spec?.setup ?? []).flatMap((s) => Object.keys(s.outputs ?? {})));
+    }
+    /** The output names the spec declares secret. */
+    declaredSecretOutputs() {
+        return new Set((this.#opts.spec?.setup ?? []).flatMap((s) => s.secretOutputs ?? []));
+    }
+    bindings() {
+        return { values: { ...this.#values }, secretNames: new Set(this.#secretNames) };
+    }
+    /** Non-secret outputs (what a replay's recorded values are rebound to). */
+    publicOutputs() {
+        return Object.fromEntries(Object.entries(this.#values).filter(([k]) => !this.#secretNames.has(k)));
+    }
+    /** Secret output values: the caller adds them to the run's redaction set. */
+    secrets() {
+        return [...this.#secretNames].map((n) => this.#values[n]).filter((v) => v !== undefined && v !== "");
+    }
+    #redact(text) {
+        const bound = Object.values(this.#opts.auth.secretFields ?? {}).filter((v) => v !== "");
+        return redactUrl(redactText(text, [...(this.#opts.secrets ?? []), ...bound, ...this.secrets()]));
+    }
+    identity() {
+        return `fx-${sha256(canonical({ spec: this.#specHash, outputs: this.publicOutputs(), secret: [...this.#secretNames].sort() })).slice(0, 16)}`;
+    }
+    record() {
+        return {
+            identity: this.identity(),
+            specHash: this.#specHash,
+            outputs: this.publicOutputs(),
+            secretOutputs: [...this.#secretNames].sort(),
+            cycles: this.#cycles,
+            log: [...this.#log],
+        };
+    }
+    /** #243: the identities the spec's steps use → their storageState paths (paths only). */
+    identities() {
+        const names = identityNames(this.#opts.spec);
+        if (names.length === 0)
+            return undefined;
+        return Object.fromEntries(names.sort().map((n) => [n, this.#opts.auth.identities?.[n]]));
+    }
+    persisted() {
+        const hooks = this.hookHashes();
+        const identities = this.identities();
+        return {
+            identity: this.identity(),
+            specHash: this.#specHash,
+            ...(this.#opts.spec === undefined ? {} : { spec: this.#opts.spec }),
+            ...(hooks === undefined ? {} : { hooks }),
+            outputs: this.publicOutputs(),
+            secretOutputs: [...this.#secretNames].sort(),
+            ...(identities === undefined ? {} : { identities }),
+        };
+    }
+    /** Sets up the fixture. Throws `FixtureSetupError`; the caller still calls `restore()`. */
+    async setup() {
+        this.#values = {};
+        this.#secretNames = new Set();
+        this.#active = true;
+        this.#cycles += 1;
+        const before = this.#opts.hooks?.before;
+        if (before !== undefined)
+            await this.#runSetupHook(before);
+        for (const [i, step] of (this.#opts.spec?.setup ?? []).entries()) {
+            const failure = await this.#runHttp(step, "setup", i);
+            if (failure !== null)
+                throw new FixtureSetupError(failure);
+        }
+    }
+    /** Restores the state the last `setup()` created. Never throws: every step is logged. */
+    async restore() {
+        if (!this.#active)
+            return;
+        this.#active = false;
+        for (const [i, step] of (this.#opts.spec?.restore ?? []).entries())
+            await this.#runHttp(step, "restore", i);
+        const after = this.#opts.hooks?.after;
+        if (after !== undefined) {
+            const started = clock.now();
+            const r = await runHook(after, this.#opts.hooks?.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS, JSON.stringify({ vars: this.publicOutputs() }), {
+                JEVITATE_FIXTURE_PHASE: "restore",
+            });
+            this.#log.push({
+                phase: "restore",
+                kind: "shell",
+                name: "--after",
+                ok: !r.timedOut && r.exitCode === 0,
+                durationMs: clock.now() - started,
+                exitCode: r.exitCode,
+                ...(r.timedOut ? { detail: "timed out" } : {}),
+                ...(r.stderr === "" ? {} : { stderr: clip(this.#redact(r.stderr)) }),
+            });
+        }
+    }
+    /** Before a replay: restore whatever is active, then set up afresh. Throws `FixtureSetupError`. */
+    async reset() {
+        await this.restore();
+        await this.setup();
+    }
+    async #runSetupHook(cmd) {
+        const started = clock.now();
+        const r = await runHook(cmd, this.#opts.hooks?.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS, "", { JEVITATE_FIXTURE_PHASE: "setup" });
+        let detail;
+        if (r.timedOut)
+            detail = "the --before hook timed out";
+        else if (r.exitCode !== 0)
+            detail = `the --before hook exited ${r.exitCode ?? "abnormally"}`;
+        else
+            detail = this.#bindHookStdout(r.stdout);
+        this.#log.push({
+            phase: "setup",
+            kind: "shell",
+            name: "--before",
+            ok: detail === undefined,
+            durationMs: clock.now() - started,
+            exitCode: r.exitCode,
+            ...(detail === undefined ? {} : { detail }),
+            ...(r.stderr === "" ? {} : { stderr: clip(this.#redact(r.stderr)) }),
+        });
+        if (detail !== undefined)
+            throw new FixtureSetupError(detail);
+    }
+    /** The `--before` stdout contract: empty, or one JSON object `{vars: {name: scalar}, secret?: [name]}`. */
+    #bindHookStdout(stdout) {
+        const text = stdout.trim();
+        if (text === "")
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return "the --before hook printed something other than one JSON object {vars, secret}";
+        }
+        if (!isRecord(parsed) || (parsed.vars !== undefined && !isRecord(parsed.vars)))
+            return "the --before hook's stdout must be {vars: {...}, secret?: [...]}";
+        const secret = Array.isArray(parsed.secret) ? parsed.secret.filter((s) => typeof s === "string") : [];
+        for (const [name, v] of Object.entries((parsed.vars ?? {}))) {
+            if (!OUTPUT_NAME.test(name))
+                return `the --before hook var ${JSON.stringify(name)} is not an identifier`;
+            if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+                return `the --before hook var ${name} is not a scalar`;
+            this.#values[name] = String(v);
+            if (secret.includes(name))
+                this.#secretNames.add(name);
+        }
+        return undefined;
+    }
+    /** Runs one HTTP step; returns the failure detail (redacted), or null. */
+    async #runHttp(step, phase, i) {
+        const started = clock.now();
+        const name = step.name ?? `${phase}[${i}]`;
+        const log = (entry) => {
+            this.#log.push({ phase, kind: "http", name, method: step.method, durationMs: clock.now() - started, ...entry });
+        };
+        let url;
+        let body;
+        let headers;
+        try {
+            const b = this.bindings();
+            url = new URL(substituteSetupRefs(step.url, b, { allowSecret: true, where: name }), this.#opts.baseUrl).href;
+            // Re-check the substituted URL: a bound value never widens the allowlist.
+            assertStepUrl(url, this.#opts, name);
+            const sub = (text) => substituteStepText(text, b, this.#opts.auth.secretFields ?? {}, name);
+            for (const [k, x] of Object.entries(step.headers ?? {})) {
+                // A `--before` hook may bind names at run time: a credential header still takes secret outputs only.
+                const pub = CREDENTIAL_HEADERS.has(k.toLowerCase()) ? referencedNames(x).find((n) => !b.secretNames.has(n)) : undefined;
+                if (pub !== undefined)
+                    throw new UnboundSetupRefError(`${name}: headers.${k} uses \${setup.${pub}}, which is not a secret output`);
+            }
+            headers = { ...substituteDeep(step.headers ?? {}, sub) };
+            if (step.json !== undefined) {
+                body = JSON.stringify(substituteDeep(step.json, sub));
+                headers["content-type"] ??= "application/json";
+            }
+            else if (step.body !== undefined) {
+                body = sub(step.body);
+            }
+            if (step.auth !== undefined)
+                Object.assign(headers, authHeaders(step.auth, url, this.#opts.auth));
+        }
+        catch (e) {
+            const detail = `${name}: ${this.#redact(firstLine(e))}`;
+            log({ ok: false, url: this.#redact(step.url), detail });
+            return detail;
+        }
+        const shownUrl = this.#redact(url);
+        const controller = new AbortController();
+        const timer = clock.setTimeout(() => controller.abort(), step.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS);
+        try {
+            const res = await (this.#opts.fetchImpl ?? fetch)(url, {
+                method: step.method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                // Never follow a redirect: it could leave the allowlist.
+                redirect: "manual",
+                signal: controller.signal,
+            });
+            const accepted = step.expectStatus !== undefined ? step.expectStatus.includes(res.status) : res.status >= 200 && res.status < 300;
+            if (!accepted) {
+                const detail = `${name}: ${step.method} ${shownUrl} answered ${res.status}`;
+                log({ ok: false, url: shownUrl, status: res.status, detail });
+                return detail;
+            }
+            if (step.outputs !== undefined) {
+                const text = await res.text();
+                let doc;
+                const needsJson = Object.values(step.outputs).some((p) => p.startsWith("$"));
+                if (needsJson) {
+                    try {
+                        doc = JSON.parse(text);
+                    }
+                    catch {
+                        const detail = `${name}: the response is not JSON, so its outputs cannot be read`;
+                        log({ ok: false, url: shownUrl, status: res.status, detail });
+                        return detail;
+                    }
+                }
+                for (const [out, path] of Object.entries(step.outputs)) {
+                    const v = path.startsWith("header:") ? (res.headers.get(path.slice("header:".length)) ?? undefined) : selectJsonPath(doc, path);
+                    if (v === undefined || v === "") {
+                        const detail = `${name}: output ${out} (${path}) is missing from the response`;
+                        log({ ok: false, url: shownUrl, status: res.status, detail });
+                        return detail;
+                    }
+                    this.#values[out] = v;
+                    if (step.secretOutputs?.includes(out) === true)
+                        this.#secretNames.add(out);
+                }
+            }
+            else {
+                await res.body?.cancel().catch(() => undefined);
+            }
+            log({ ok: true, url: this.#redact(url), status: res.status });
+            return null;
+        }
+        catch (e) {
+            const detail = `${name}: ${step.method} ${shownUrl} failed: ${controller.signal.aborted ? "timed out" : this.#redact(firstLine(e))}`;
+            log({ ok: false, url: shownUrl, detail });
+            return detail;
+        }
+        finally {
+            clock.clearTimeout(timer);
+        }
+    }
+}
+/**
+ * A replay session re-uses the Recording of the ORIGINAL run, whose navigations carry the values
+ * that run's setup bound (e.g. `/items/<old id>`). After a fresh setup, the same navigation must go
+ * to the NEW value: this rewrites each recorded value to its current one in every `page.goto` of the
+ * replay's own page (non-secret outputs of 4+ characters only — shorter ones are too ambiguous to
+ * rewrite blindly).
+ */
+export function rebindReplayNavigation(page, recorded, current) {
+    const pairs = Object.entries(recorded)
+        .map(([k, from]) => [from, current[k]])
+        .filter((p) => p[1] !== undefined && p[0] !== p[1] && p[0].length >= 4);
+    if (pairs.length === 0)
+        return;
+    const original = page.goto.bind(page);
+    page.goto = ((url, ...rest) => {
+        let next = url;
+        for (const [from, to] of pairs) {
+            next = next.split(from).join(to).split(encodeURIComponent(from)).join(encodeURIComponent(to));
+        }
+        return original(next, ...rest);
+    });
+}
+/** The fixture identity carried on a Recording (non-secret outputs only). */
+export function recordingFixture(r) {
+    return { identity: r.identity, specHash: r.specHash, outputs: { ...r.outputs } };
+}
+/**
+ * Wraps a replay-session opener (hang reproduction, `verify-fix`, regression capture) so EVERY
+ * replay starts from the fixture's state: restore whatever is active, set up afresh (a failure
+ * throws, so the replay is "could not open a session" — inconclusive, never evidence), then rebind
+ * the Recording's values (`recorded`, from the run the Recording came from) to the new outputs.
+ */
+export function fixtureReplayOpener(open, fx, recorded) {
+    return async () => {
+        await fx.reset();
+        const session = await open();
+        rebindReplayNavigation(session.page, recorded, fx.publicOutputs());
+        return session;
+    };
+}
+//# sourceMappingURL=mission-fixtures.js.map