@jevitate/cli 0.1.0 → 0.2.0

package/dist/record-api.js

@@ -1,18 +1,15 @@
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdir, writeFile } from "node:fs/promises";
+import { logsDirFor } from "./project-dir.js";
 import { join } from "node:path";
 import { assertAuthorizedExploreTarget, normalizeAllowlist } from "@jevitate/explore";
 import { PlaywrightBrowserPort } from "@jevitate/playwright";
 import { Recorder } from "@jevitate/recorder";
-import { resolveDataDir } from "./data-dir.js";
 export async function runRecording(opts) {
     // Guardrail #1 — authorize BEFORE opening a browser. Throws on refusal.
     const origin = assertAuthorizedExploreTarget(opts.url, opts.allowlist);
     const portFactory = opts.browserPortFactory ?? (() => new PlaywrightBrowserPort());
     const port = portFactory();
-    const profileDir = await mkdtemp(join(tmpdir(), "jevitate-record-"));
     const session = await port.open({
-        profileDir,
         headless: opts.headless ?? false,
         allowedOrigins: [...opts.allowlist],
         baseUrl: origin,
@@ -29,7 +26,7 @@ export async function runRecording(opts) {
         await (opts.waitForStop ?? waitForEnterKey)();
         const recording = await recorder.stop(opts.retro);
         const finalUrl = session.page.url();
-        const outDir = opts.outDir ?? resolveDataDir(["recordings"]);
+        const outDir = opts.outDir ?? logsDirFor();
         await mkdir(outDir, { recursive: true });
         const iso = (opts.nowIso ?? (() => new Date().toISOString()))();
         const recordingPath = join(outDir, `record-${iso.replace(/[:.]/g, "-")}.json`);
@@ -39,7 +36,6 @@ export async function runRecording(opts) {
     }
     finally {
         await session.close();
-        await rm(profileDir, { recursive: true, force: true });
     }
 }
 /**
@@ -54,39 +50,54 @@ export function resolveRecordAllowlist(url, allow) {
     return normalizeAllowlist([url]);
 }
 /**
- * The default stop signal for an interactive `jevitate record` session:
- * resolves the first time the user presses Enter on stdin. Best-effort — if
- * stdin is not a TTY / not readable, it resolves immediately rather than
- * hanging the capture forever.
+ * The default stop signal for an interactive `jevitate record` session: resolves the first time
+ * the user presses Enter on stdin, OR on SIGINT (Ctrl-C, #124) — both end the take the SAME way,
+ * through `recorder.stop()` + the write to disk in `runRecording`'s normal path, so a take is
+ * never silently lost. SIGINT matters most for `--headless` (no visible window to interact with,
+ * so Ctrl-C is the natural way to signal "done"): registering a listener here means Node does NOT
+ * fall back to its default "kill the process" SIGINT behavior — the take is saved first.
+ * Best-effort on stdin — if it is not a TTY / not readable, resolves immediately rather than
+ * hanging the capture forever (SIGINT still works either way).
  */
 export function waitForEnterKey() {
     return new Promise((resolve) => {
+        let settled = false;
         const stdin = process.stdin;
-        if (!stdin || !stdin.readable) {
-            resolve();
-            return;
-        }
+        const onSigint = () => finish();
         const onData = (chunk) => {
-            if (chunk.includes(0x0a) || chunk.includes(0x0d)) {
-                cleanup();
-                resolve();
-            }
+            if (chunk.includes(0x0a) || chunk.includes(0x0d))
+                finish();
         };
-        const cleanup = () => {
-            stdin.off("data", onData);
-            try {
-                stdin.pause();
-            }
-            catch {
-                // stdin may already be closed; nothing to pause.
+        function cleanup() {
+            process.off("SIGINT", onSigint);
+            if (stdin && stdin.readable) {
+                stdin.off("data", onData);
+                try {
+                    stdin.pause();
+                }
+                catch {
+                    // stdin may already be closed; nothing to pause.
+                }
             }
-        };
+        }
+        function finish() {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve();
+        }
+        process.on("SIGINT", onSigint);
+        if (!stdin || !stdin.readable) {
+            finish();
+            return;
+        }
         try {
             stdin.resume();
             stdin.on("data", onData);
         }
         catch {
-            resolve();
+            finish();
         }
     });
 }

package/dist/record-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"record-api.js","sourceRoot":"","sources":["../src/record-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"record-api.js","sourceRoot":"","sources":["../src/record-api.ts"],"names":[],"mappings":"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"}

package/dist/record-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/** Registers `jevitate record` (record-by-demonstration). */
+export declare function registerRecordCommands(program: Command, deps: CliDeps): void;

package/dist/record-cli.js

@@ -0,0 +1,64 @@
+import { UnauthorizedExploreTargetError } from "@jevitate/explore";
+import { ok, fail } from "./envelope.js";
+import { runRecording, resolveRecordAllowlist } from "./record-api.js";
+import { emitJson } from "./cli-shared.js";
+/** Registers `jevitate record` (record-by-demonstration). */
+export function registerRecordCommands(program, deps) {
+    // Additive: `jevitate record` — record-by-demonstration (Ticket #22). Opens a
+    // real browser on an authorized origin, lets the user demonstrate a flow, and
+    // captures it into a schema-valid, replayable Recording written to disk. The
+    // authorized-origin guard is enforced FIRST (fail-closed) inside runRecording,
+    // before any browser is opened; the temp profile dir is always cleaned up.
+    program
+        .command("record")
+        .description("record a demonstrated flow into a Recording (authoring plane)")
+        .option("--url <url>", "start URL to demonstrate from (must be an authorized origin)")
+        .option("--intent <text>", "your framing of the journey (carried to Recording.intent)")
+        .option("--retro <text>", "optional retrospective note (carried to Recording.retro)")
+        .option("--allow <origin>", "authorized origin (repeatable); REPLACES the default allowlist when given (the URL's own origin is used only when --allow is omitted entirely) -- include the URL's own origin explicitly if you still need it", (v, prev) => [...prev, v], [])
+        .option("--headless", "run headless (default: headed — a record session is a live demonstration)", false)
+        .option("--out <dir>", "directory to write the emitted Recording (default: .jevitate/logs/<date> in the project, else ~/.jevitate/logs/<date>)")
+        .option("--json", "emit a JSON envelope")
+        .action(async function () {
+        const o = this.opts();
+        if (!o.url) {
+            emitJson(program, fail("E_RECORD_ARGS", "--url is required"));
+            return;
+        }
+        const allowlist = resolveRecordAllowlist(o.url, o.allow);
+        try {
+            const result = await runRecording({
+                url: o.url,
+                allowlist,
+                intent: o.intent,
+                retro: o.retro,
+                outDir: o.out,
+                headless: o.headless ?? false,
+                browserPortFactory: deps.record?.browserPortFactory,
+                recorderFactory: deps.record?.recorderFactory,
+                waitForStop: deps.record?.waitForStop,
+            });
+            const summary = {
+                recordingPath: result.recordingPath,
+                steps: result.steps,
+                pages: result.pages,
+                finalUrl: result.finalUrl,
+            };
+            if (o.json) {
+                emitJson(program, ok(summary));
+            }
+            else {
+                program.configureOutput().writeOut?.(`${JSON.stringify(summary)}\n`);
+            }
+        }
+        catch (err) {
+            if (err instanceof UnauthorizedExploreTargetError) {
+                emitJson(program, fail("E_UNAUTHORIZED_EXPLORE_TARGET", err.message));
+            }
+            else {
+                emitJson(program, fail("E_RECORD_RUN", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+}
+//# sourceMappingURL=record-cli.js.map

package/dist/record-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-cli.js","sourceRoot":"","sources":["../src/record-cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAgB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEzD,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CAAC,OAAgB,EAAE,IAAa;IACpE,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,2EAA2E;IAC3E,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,+DAA+D,CAAC;SAC5E,MAAM,CAAC,aAAa,EAAE,8DAA8D,CAAC;SACrF,MAAM,CAAC,iBAAiB,EAAE,2DAA2D,CAAC;SACtF,MAAM,CAAC,gBAAgB,EAAE,0DAA0D,CAAC;SACpF,MAAM,CACL,kBAAkB,EAClB,gNAAgN,EAChN,CAAC,CAAC,EAAE,IAAc,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EACnC,EAAc,CACf;SACA,MAAM,CAAC,YAAY,EAAE,2EAA2E,EAAE,KAAK,CAAC;SACxG,MAAM,CAAC,aAAa,EAAE,wHAAwH,CAAC;SAC/I,MAAM,CAAC,QAAQ,EAAE,sBAAsB,CAAC;SACxC,MAAM,CAAC,KAAK;QACX,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAQf,CAAC;QAEL,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YACX,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC,CAAC;YAC9D,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG,sBAAsB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAEzD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;gBAChC,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,SAAS;gBACT,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,MAAM,EAAE,CAAC,CAAC,GAAG;gBACb,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,KAAK;gBAC7B,kBAAkB,EAAE,IAAI,CAAC,MAAM,EAAE,kBAAkB;gBACnD,eAAe,EAAE,IAAI,CAAC,MAAM,EAAE,eAAe;gBAC7C,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW;aACtC,CAAC,CAAC;YACH,MAAM,OAAO,GAAG;gBACd,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC;YACF,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;gBACX,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,8BAA8B,EAAE,CAAC;gBAClD,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,+BAA+B,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACxE,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/recording-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/** Registers `jevitate recording`: `promote|diff|fit|postdoc`. */
+export declare function registerRecordingCommands(program: Command, deps: CliDeps): void;

package/dist/recording-cli.js

@@ -0,0 +1,248 @@
+import { readFile, writeFile } from "node:fs/promises";
+import * as clack from "@clack/prompts";
+import { RecordingSchema, AuthoringTakeSchema, PostdocDecisionsSchema, promoteToVariable, diffTakes, applyPostdoc, flattenBaseFillSteps, fitInteractionPolicy, } from "@jevitate/recording";
+import { ok, fail } from "./envelope.js";
+import { nonNegativeIntArg } from "./cli-args.js";
+import { emitJson } from "./cli-shared.js";
+/** Registers `jevitate recording`: `promote|diff|fit|postdoc`. */
+export function registerRecordingCommands(program, deps) {
+    /**
+     * Reads one "take file" for `recording diff`/`recording postdoc` (#124): a JSON object written
+     * by `jevitate record` — `{ recording, values }` (`AuthoringTakeSchema`). A raw `Recording` — the
+     * kind `explore`/`explore-author-journey`/a usability run emits directly, `{version, site, pages,
+     * ...}` at the TOP level, no `recording`/`values` wrapper — is a common, easy mistake to hand
+     * here; `AuthoringTakeSchema`'s `.strict()` rejects it with an opaque `Unrecognized keys: version,
+     * site, intent, pages` zod dump. Detected BEFORE the schema parse so the caller gets a message
+     * that names the actual problem and how to fix it, not a zod dump.
+     */
+    async function readAuthoringTake(file) {
+        const raw = await readFile(file, "utf8");
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`'${file}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (json !== null && typeof json === "object" && !Array.isArray(json) && "pages" in json && !("recording" in json)) {
+            throw new Error(`'${file}' looks like a Recording (it has a top-level "pages"), not a take file. ` +
+                `'recording diff'/'recording postdoc' need a take file written by 'jevitate record' — shape ` +
+                `{ recording, values } — not a raw Recording from 'explore', 'explore-author-journey', or a ` +
+                `usability run. Wrap it as { "recording": <the Recording>, "values": {} } if you want to ` +
+                `diff/postdoc it anyway.`);
+        }
+        const parsed = AuthoringTakeSchema.parse(json);
+        return { recording: parsed.recording, values: new Map(Object.entries(parsed.values)) };
+    }
+    const recording = program.command("recording").description("inspect and edit recorded takes (promote, edit steps, diff, postdoc)");
+    recording
+        .command("promote <file>")
+        .requiredOption("--page <n>", "page index", nonNegativeIntArg)
+        .requiredOption("--step <n>", "step index within the page", nonNegativeIntArg)
+        .requiredOption("--var <name>", "variable name to bind")
+        .action(async function (file) {
+        const { page, step, var: varName } = this.opts();
+        try {
+            const raw = await readFile(file, "utf8");
+            const rec = RecordingSchema.parse(JSON.parse(raw));
+            const result = promoteToVariable(rec, { page: Number(page), step: Number(step) }, varName);
+            program.configureOutput().writeOut?.(`${JSON.stringify(result, null, 2)}\n`);
+            process.exitCode = 0;
+        }
+        catch (err) {
+            emitJson(program, fail("E_INVALID_RECORDING", String(err)));
+        }
+    });
+    recording
+        .command("diff <takeA> <takeB> [more...]")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (takeA, takeB, more) {
+        const { json } = this.opts();
+        try {
+            const files = [takeA, takeB, ...more];
+            const takes = await Promise.all(files.map(readAuthoringTake));
+            const diffResult = diffTakes(takes);
+            const envelope = ok(diffResult);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                const out = program.configureOutput().writeOut;
+                diffResult.columns.forEach((col, i) => {
+                    const type = col.inferredType ? `, type=${col.inferredType}` : "";
+                    out?.(`column ${i}: ${col.kind} (confidence ${col.confidence.toFixed(2)}${type}) values=${JSON.stringify(col.values)}\n`);
+                });
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            emitJson(program, fail("E_INVALID_TAKE", String(err)));
+        }
+    });
+    recording
+        .command("fit <file>")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (file) {
+        const { json } = this.opts();
+        try {
+            const raw = await readFile(file, "utf8");
+            const rec = RecordingSchema.parse(JSON.parse(raw));
+            const interaction = fitInteractionPolicy(rec);
+            const policy = { version: "1.0.0", interaction };
+            if (json) {
+                emitJson(program, ok(policy));
+            }
+            else {
+                program.configureOutput().writeOut?.(`${JSON.stringify(policy, null, 2)}\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            emitJson(program, fail("E_INVALID_RECORDING", String(err)));
+        }
+    });
+    recording
+        .command("postdoc <take> [more...]")
+        .option("--decisions <file>", "path to a PostdocDecision[] JSON file (non-interactive mode)")
+        .option("--out <file>", "write the resulting Recording to this file instead of stdout")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (take, more) {
+        const { decisions: decisionsFile, out, json } = this.opts();
+        try {
+            const files = [take, ...more];
+            const takes = await Promise.all(files.map(readAuthoringTake));
+            const diff = diffTakes(takes);
+            let decisions;
+            if (decisionsFile !== undefined) {
+                decisions = await loadDecisions(decisionsFile);
+            }
+            else {
+                decisions = await promptForDecisions(takes[0]);
+            }
+            const result = applyPostdoc(takes[0], diff, decisions);
+            if (out !== undefined) {
+                await writeFile(out, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+            }
+            if (json) {
+                emitJson(program, ok(result));
+            }
+            else if (out === undefined) {
+                program.configureOutput().writeOut?.(`${JSON.stringify(result, null, 2)}\n`);
+                process.exitCode = 0;
+            }
+            else {
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof DecisionsParseError) {
+                emitJson(program, fail("E_INVALID_DECISIONS", String(err.cause)));
+            }
+            else {
+                emitJson(program, fail("E_INVALID_TAKE", String(err)));
+            }
+        }
+    });
+}
+/**
+ * Distinguishes a malformed `--decisions <file>` (E_INVALID_DECISIONS) from
+ * every other failure mode of the `postdoc` action (E_INVALID_TAKE) without
+ * making `loadDecisions` itself responsible for emitting the CLI envelope —
+ * matching this file's existing pattern of one try/catch per subcommand
+ * mapping to one error code.
+ */
+class DecisionsParseError extends Error {
+    cause;
+    constructor(cause) {
+        super(String(cause));
+        this.cause = cause;
+    }
+}
+async function loadDecisions(file) {
+    let raw;
+    let parsed;
+    try {
+        raw = await readFile(file, "utf8");
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new DecisionsParseError(err);
+    }
+    const result = PostdocDecisionsSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new DecisionsParseError(result.error);
+    }
+    return result.data;
+}
+/**
+ * Thin `@clack/prompts` adapter: walks `authoring`'s fill/select steps in
+ * order and asks the human how to classify each one. ALL logic (variance
+ * guards, secret-materialization checks, the actual step rewrite) lives in
+ * `applyPostdoc`/`diffTakes` — this function only collects a
+ * `PostdocDecision[]` to hand them.
+ */
+async function promptForDecisions(authoring) {
+    clack.intro("recording postdoc — review captured fill/select steps");
+    const decisions = [];
+    const fillSteps = flattenBaseFillSteps(authoring.recording);
+    for (const { ref } of fillSteps) {
+        const classify = await clack.select({
+            message: `Step ${ref.page}:${ref.step} — how should this value be classified?`,
+            options: [
+                { value: "constant", label: "constant", hint: "fix this value in the artifact" },
+                { value: "variable", label: "variable", hint: "prompt for a value at replay time" },
+                { value: "handback", label: "handback", hint: "hand control to a human at replay time" },
+            ],
+        });
+        if (clack.isCancel(classify)) {
+            clack.cancel("postdoc review cancelled");
+            process.exit(1);
+        }
+        const label = await promptOptionalText("Label for this step? (blank to skip)");
+        const chunk = await promptOptionalText("Chunk name for this step? (blank to skip)");
+        let decision;
+        if (classify === "constant") {
+            const acknowledgeVaried = await clack.confirm({
+                message: "Acknowledge this value varied across takes anyway?",
+                initialValue: false,
+            });
+            if (clack.isCancel(acknowledgeVaried)) {
+                clack.cancel("postdoc review cancelled");
+                process.exit(1);
+            }
+            decision = { step: ref, classify: "constant", ...(acknowledgeVaried ? { acknowledgeVaried: true } : {}) };
+        }
+        else if (classify === "variable") {
+            const name = await clack.text({ message: "Variable name?" });
+            if (clack.isCancel(name)) {
+                clack.cancel("postdoc review cancelled");
+                process.exit(1);
+            }
+            decision = { step: ref, classify: "variable", name };
+        }
+        else {
+            const prompt = await clack.text({ message: "Handback prompt for the human operator?" });
+            if (clack.isCancel(prompt)) {
+                clack.cancel("postdoc review cancelled");
+                process.exit(1);
+            }
+            decision = { step: ref, classify: "handback", prompt };
+        }
+        if (label !== undefined)
+            decision = { ...decision, label };
+        if (chunk !== undefined)
+            decision = { ...decision, chunk };
+        decisions.push(decision);
+    }
+    clack.outro("review complete");
+    return decisions;
+}
+async function promptOptionalText(message) {
+    const value = await clack.text({ message, defaultValue: "" });
+    if (clack.isCancel(value)) {
+        clack.cancel("postdoc review cancelled");
+        process.exit(1);
+    }
+    return value === "" ? undefined : value;
+}
+//# sourceMappingURL=recording-cli.js.map

package/dist/recording-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-cli.js","sourceRoot":"","sources":["../src/recording-cli.ts"],"names":[],"mappings":"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"}

package/dist/regression-api.d.ts

@@ -1,4 +1,53 @@
 import type { Actor } from "@jevitate/screenplay";
+import { type ResolvedJourneyEnvironment } from "./environments.js";
+import { type PersistedFinding } from "./verify-fix-api.js";
+/** #213: `--id <id>` already names a committed regression — refused unless `--force`, checked
+ * BEFORE any reproduce/minimize attempt runs (never a browser-driven overwrite the caller didn't ask for). */
+export declare class RegressionExistsError extends Error {
+    readonly code: "E_REGRESSION_EXISTS";
+    constructor(id: string, dir: string);
+}
+/**
+ * The clear, actionable refusal #81 requires: a Recording with no failure to
+ * reproduce is refused rather than "minimized" into a vacuous artifact that
+ * can only ever pass.
+ */
+export declare class NoFailureToReproduceError extends Error {
+    readonly code: "E_REGRESSION_NO_FAILURE";
+    constructor(message?: string);
+}
+/** `--result` was given but carries no usable oracle at all: no failed `--success` check (of ANY
+ * kind — page/reloadThen/requestMade/responseStatus), no matching declared-invariant defect, and no
+ * APP-caused failed-action step (jevitate's own engine refusals — #92's repeated-side-effect guard,
+ * a budget/fail-closed cutoff, … — are never a valid oracle; #119/#129). */
+export declare class NoOracleInResultError extends Error {
+    readonly code: "E_REGRESSION_NO_ORACLE";
+    constructor(resultPath: string, detail: string);
+}
+/**
+ * #213: `--fingerprint` names one of the mission's OWN findings, but a hard-signal one (http-5xx,
+ * hang, server-log, adversarial-misuse, … — everything but `invariant`, which `captureInvariantRegression`
+ * already handles). Its oracle is the signal itself, never a page/success-check assertion —
+ * `deriveOracle` (transcript/checks only) can never express it, so falling through to it just
+ * produces a generic "no usable oracle" that reads as the `--result` file being unusable, when the
+ * real answer is: this isn't the tool for it. Points at the route that IS: `ledger add` (repro
+ * material for `ledger verify` / `verify-fix`).
+ */
+export declare class RegressionHardSignalOracleError extends Error {
+    readonly code: "E_REGRESSION_HARD_SIGNAL";
+    constructor(resultPath: string, finding: PersistedFinding);
+}
+/** An explicit `--fingerprint` disagrees with the oracle derived from `--result`. */
+export declare class FingerprintMismatchError extends Error {
+    readonly code: "E_REGRESSION_FINGERPRINT_MISMATCH";
+    constructor(given: string, derived: string);
+}
+/** An invariant defect matched by `--fingerprint`, but `verify-fix`'s own replay says it does not
+ * currently reproduce (fixed, or inconclusive) — never fabricated into a regression. */
+export declare class InvariantNotReproducingError extends Error {
+    readonly code: "E_REGRESSION_INVARIANT_NOT_REPRODUCING";
+    constructor(invariantId: string, verdict: string, reason: string);
+}
 export interface RunRegressionCaptureOptions {
     failingRecordingPath: string;
     id: string;
@@ -6,6 +55,25 @@ export interface RunRegressionCaptureOptions {
     attempts?: number;
     bugSummary?: string;
     makeActor: () => Promise<Actor>;
+    /**
+     * Path to a mission result JSON (what `jevitate explore` writes alongside its Recording as
+     * `<recording>.result.json`) — supplies a failure oracle (#81 item 2) when the Recording alone
+     * carries no reproducible failure, because the failing action itself was never captured as a
+     * step (see `@jevitate/explore`'s `RunRecorder`: only successful actions are recorded).
+     */
+    resultPath?: string;
+    /**
+     * An explicit failure fingerprint. Accepts EITHER a `stepSignature` (see `@jevitate/regression`'s
+     * `fingerprintFailure`) alone pinning which structural step in `--from` counts as "the" failure,
+     * OR — combined with `--result` (#119/#129) — the SAME defect/invariant fingerprint every other
+     * command (`verify-fix`, the mission report) uses: when it matches one of the mission's OWN
+     * declared-invariant defects, that invariant is re-checked (via `verify-fix`'s own machinery)
+     * rather than turned into a Recording step. Combined with a page-checkable `--result` oracle, it
+     * cross-checks the derived oracle.
+     */
+    fingerprint?: string;
+    /** #213: overwrite an existing `<id>.recording.json`/`.meta.json` — default: refused (fail closed). */
+    force?: boolean;
 }
 export type RunRegressionCaptureResult = {
     recordingPath: string;
@@ -15,3 +83,36 @@ export type RunRegressionCaptureResult = {
     rate: number;
 };
 export declare function runRegressionCapture(opts: RunRegressionCaptureOptions): Promise<RunRegressionCaptureResult>;
+/** No committed `<id>.recording.json`/`<id>.meta.json` in the regressions directory. */
+export declare class RegressionNotFoundError extends Error {
+    readonly code: "E_REGRESSION_NOT_FOUND";
+    constructor(id: string, dir: string);
+}
+export interface RunRegressionRunOptions {
+    readonly id: string;
+    readonly regressionsDir: string;
+    readonly makeActor: () => Promise<Actor>;
+    /** Fresh-context replays for a declared-invariant oracle (mirrors `verify-fix --replays`). Default 3. */
+    readonly attempts?: number;
+    /**
+     * #247 (`--env`/`--base-url`): replay against this environment — the committed Recording's
+     * same-origin URLs (and an invariant oracle's baseUrl/allowlist) move onto it; a step on an origin
+     * it does not allow is refused before any browser opens. Absent: the recorded site, as before.
+     */
+    readonly environment?: ResolvedJourneyEnvironment;
+}
+export type RegressionRunVerdict = "reproduces" | "fixed" | "inconclusive" | "intermittent";
+export interface RegressionRunReport {
+    readonly id: string;
+    readonly verdict: RegressionRunVerdict;
+    readonly reason: string;
+}
+/**
+ * `regression run <id>` (#129 item 4): replays a committed regression and reports whether it still
+ * REPRODUCES or is now FIXED. Dispatches on `meta.oracle` — absent (the default/original) means the
+ * committed Recording's own trailing `assert` step IS the oracle, replayed by `@jevitate/regression`'s
+ * `replayRegression` (its `expect` failing/holding is the verdict, no different from any other
+ * `RecordingInterpreter` run); a `network`/`invariant` oracle is re-evaluated the SAME way capture
+ * established it (`replayAndCheckNetwork` / `verifyFix`'s invariant re-check) — never duplicated.
+ */
+export declare function runRegressionRun(opts: RunRegressionRunOptions): Promise<RegressionRunReport>;