@jevitate/cli 0.1.0 → 0.3.0

package/dist/journey-annotate-api.js

@@ -0,0 +1,269 @@
+import { expectedResultFromDelta } from "@jevitate/explore";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AnnotationDraftMismatchError, AnnotationDraftSchema, FsJourneyStore, applyAnnotationDraft, describeStep, flatJourneySteps, intentCoverage, secretParamValues, } from "@jevitate/journey";
+import { assertNoSecretInPayload, redactText, redactUrl } from "@jevitate/ai-core";
+import { contentHash, clock } from "@jevitate/domain";
+import { BrowseTheWebToken } from "@jevitate/screenplay";
+import { runJourneyProgrammatically, UnknownJourneyError } from "./journey-api.js";
+/**
+ * #246 — `jevitate journey annotate`: replay a Journey, capture redacted before/after page evidence
+ * per step, and ask the generation gateway to DRAFT each step's objective / expected result (and the
+ * Journey's goal / success criteria when missing). The draft goes to a sidecar file and NEVER into
+ * the Journey: `approveJourneyAnnotations` writes it only on an explicit human approval, and only
+ * while the Journey is unchanged since the draft (content hash).
+ */
+/** Visible text kept per page for the model (redacted first, then bounded). */
+const EVIDENCE_TEXT_CHARS = 1500;
+export class AnnotationDraftNotFoundError extends Error {
+    code = "E_JOURNEY_ANNOTATIONS_NOT_FOUND";
+}
+export class InvalidAnnotationDraftError extends Error {
+    code = "E_INVALID_ANNOTATIONS_DRAFT";
+}
+/** The Journey changed after the draft was made — approving would annotate steps it never saw. */
+export class StaleAnnotationDraftError extends Error {
+    code = "E_JOURNEY_ANNOTATIONS_STALE";
+}
+/**
+ * Where a Journey's draft lives: `<journeys>/.drafts/<id>.annotations.json` (`<ns>/<id>` for a shared
+ * Journey). A dot-folder, so `journey list` and namespace discovery never read it as a Journey.
+ */
+export function annotationDraftPath(journeysDir, id) {
+    const parts = id.split("/");
+    return join(journeysDir, ".drafts", ...parts.slice(0, -1), `${parts[parts.length - 1] ?? id}.annotations.json`);
+}
+/** The Journey's content hash — what a draft is bound to. */
+export function journeyContentHash(journey) {
+    return contentHash(journey);
+}
+async function loadJourney(dir, id) {
+    const journey = await new FsJourneyStore(dir).get(id);
+    if (journey === null)
+        throw new UnknownJourneyError(`unknown journey '${id}'`);
+    return journey;
+}
+/** BROWSER CODE — the page's main heading (else its title) and visible text. */
+function readPage() {
+    const h1 = document.querySelector("h1");
+    const heading = (h1?.innerText ?? h1?.textContent ?? "").trim() || (document.title ?? "");
+    return { heading, text: document.body?.innerText ?? "" };
+}
+/** Redacted page evidence (never throws: an unreadable page is empty evidence). */
+async function capture(actor, secrets) {
+    const page = actor.ability(BrowseTheWebToken).session.page;
+    const raw = await page.evaluate(readPage).catch(() => ({ heading: "", text: "" }));
+    const scrub = (s) => redactText(s, secrets);
+    return {
+        url: scrub(redactUrl(page.url())),
+        heading: scrub(raw.heading.replace(/\s+/g, " ").trim()).slice(0, 300),
+        // Redact the WHOLE text before bounding it, so a cut never splits a secret past the redactor.
+        text: scrub(raw.text.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim()).slice(0, EVIDENCE_TEXT_CHARS),
+    };
+}
+/**
+ * Replays the Journey through `runJourneyProgrammatically` (the same session, site policy, fixtures
+ * and fail-closed policy as `journey run`) with an observing interpreter, then drafts. A replay that
+ * stops early still drafts the steps it reached (`replay.outcome: "stopped"`).
+ *
+ * Environments (#247): every browser/session option `journey run` takes rides in `opts` and is
+ * handed to `runJourneyProgrammatically` unchanged — including `environment` (`--env`/`--base-url`,
+ * resolved by `resolveJourneyEnvironment`), so the replay is rebased and allowlisted exactly as a run.
+ */
+export async function annotateJourney(opts) {
+    const journey = await loadJourney(opts.dir, opts.id);
+    const journeyHash = journeyContentHash(journey);
+    const secrets = secretParamValues(journey, opts.params);
+    const flat = flatJourneySteps(journey);
+    const before = new Map();
+    const after = new Map();
+    const observer = {
+        beforeStep: async ({ actor, index }) => {
+            before.set(index, await capture(actor, secrets));
+        },
+        afterStep: async ({ actor, index, outcome }) => {
+            after.set(index, outcome === "done" ? await capture(actor, secrets) : null);
+        },
+    };
+    const { gen, now, ...runOpts } = opts;
+    const run = await runJourneyProgrammatically({ ...runOpts, observer });
+    const reachedSteps = before.size;
+    const replay = run.outcome === "quarantined"
+        ? { outcome: "stopped", reachedSteps, totalSteps: flat.length, reason: redactText(run.reason, secrets).slice(0, 2000) }
+        : { outcome: "completed", reachedSteps, totalSteps: flat.length };
+    const m = journey.metadata;
+    const context = redactText(m.goal ?? [m.name, m.description, journey.recording.intent].filter((s) => s !== undefined && s !== "").join(" — "), secrets);
+    const clean = (s) => {
+        const t = s === null || s === undefined ? "" : redactText(s, secrets).trim();
+        return t === "" ? undefined : t;
+    };
+    let provenance;
+    const steps = [];
+    const stepLines = [];
+    for (const s of flat) {
+        const described = redactText(describeStep(s.recorded.step), secrets);
+        const b = before.get(s.index);
+        const needObjective = (s.recorded.objective ?? "").trim() === "";
+        const needExpected = (s.recorded.expectedResult ?? "").trim() === "";
+        let objective = s.recorded.objective;
+        // #303 (`--action-deltas`): the expected result is drafted by code from what the step changed.
+        const observed = run.actionDeltas?.steps.find((x) => x.step === s.index + 1);
+        const fromDelta = needExpected && observed !== undefined ? clean(expectedResultFromDelta(observed.delta)) : undefined;
+        if (b !== undefined && fromDelta !== undefined && !needObjective) {
+            const a = after.get(s.index) ?? null;
+            steps.push({
+                index: s.index,
+                step: described.slice(0, 1000),
+                expectedResult: fromDelta,
+                evidence: { before: { url: b.url, heading: b.heading }, after: a === null ? null : { url: a.url, heading: a.heading } },
+            });
+        }
+        else if (b !== undefined && (needObjective || needExpected)) {
+            const a = after.get(s.index) ?? null;
+            const input = { journey: context, stepNumber: s.index + 1, totalSteps: flat.length, step: described, before: b, after: a };
+            assertNoSecretInPayload(input, secrets); // fail closed: nothing secret reaches a model
+            const { output, provenance: p } = await gen.generate("journey.step", input);
+            provenance = p;
+            const draftObjective = needObjective ? clean(output.objective) : undefined;
+            const draftExpected = needExpected ? (fromDelta ?? clean(output.expectedResult)) : undefined;
+            objective = draftObjective ?? objective;
+            if (draftObjective !== undefined || draftExpected !== undefined) {
+                steps.push({
+                    index: s.index,
+                    step: described.slice(0, 1000),
+                    ...(draftObjective === undefined ? {} : { objective: draftObjective }),
+                    ...(draftExpected === undefined ? {} : { expectedResult: draftExpected }),
+                    evidence: {
+                        before: { url: b.url, heading: b.heading },
+                        after: a === null ? null : { url: a.url, heading: a.heading },
+                    },
+                });
+            }
+        }
+        stepLines.push(`${s.index + 1}. ${described}${objective === undefined ? "" : ` — ${redactText(objective, secrets)}`}`.slice(0, 1200));
+    }
+    let goal;
+    let successCriteria;
+    const needGoal = (m.goal ?? "").trim() === "";
+    const needCriteria = (m.successCriteria ?? []).length === 0;
+    if (needGoal || needCriteria) {
+        const lastReached = [...before.keys()].sort((x, y) => y - x)[0];
+        const finalPage = lastReached === undefined ? null : (after.get(lastReached) ?? before.get(lastReached) ?? null);
+        const input = {
+            name: redactText(m.name, secrets).slice(0, 500),
+            ...(m.description === undefined ? {} : { description: redactText(m.description, secrets).slice(0, 2000) }),
+            ...(journey.recording.intent === undefined ? {} : { intent: redactText(journey.recording.intent, secrets).slice(0, 2000) }),
+            steps: stepLines.slice(0, 200),
+            finalPage,
+        };
+        assertNoSecretInPayload(input, secrets);
+        const { output, provenance: p } = await gen.generate("journey.goal", input);
+        provenance = p;
+        if (needGoal)
+            goal = clean(output.goal);
+        if (needCriteria) {
+            const criteria = output.successCriteria.map((c) => clean(c)).filter((c) => c !== undefined);
+            if (criteria.length > 0)
+                successCriteria = criteria;
+        }
+    }
+    const draft = AnnotationDraftSchema.parse({
+        kind: "jevitate.journey-annotations.draft",
+        version: 1,
+        journeyId: opts.id,
+        journeyHash,
+        createdAtIso: (now ?? (() => clock.nowIso()))(),
+        provenance: provenance === undefined
+            ? { adapter: "none", model: "none", promptVersion: "none" }
+            : { adapter: provenance.adapter, model: provenance.model, promptVersion: provenance.promptVersion },
+        replay,
+        ...(goal === undefined ? {} : { goal }),
+        ...(successCriteria === undefined ? {} : { successCriteria }),
+        steps,
+    });
+    assertNoSecretInPayload(draft, secrets, "journey annotation draft"); // the last line: never at rest
+    const draftPath = annotationDraftPath(opts.dir, opts.id);
+    await mkdir(dirname(draftPath), { recursive: true, mode: 0o700 });
+    await writeFile(draftPath, `${JSON.stringify(draft, null, 2)}\n`, { mode: 0o600 });
+    return {
+        id: opts.id,
+        draftPath,
+        replay,
+        drafted: {
+            objectives: steps.filter((s) => s.objective !== undefined).length,
+            expectedResults: steps.filter((s) => s.expectedResult !== undefined).length,
+            goal: goal !== undefined,
+            successCriteria: successCriteria?.length ?? 0,
+        },
+        proposed: applyAnnotationDraft(journey, draft).changes,
+        coverage: intentCoverage(journey),
+        ...(run.screenshotPaths === undefined ? {} : { screenshotPaths: run.screenshotPaths }),
+        ...(run.screenshotIndex === undefined ? {} : { screenshotIndex: run.screenshotIndex }),
+        ...(run.screenshotsSkipped === undefined ? {} : { screenshotsSkipped: run.screenshotsSkipped }),
+    };
+}
+/** Reads and validates a Journey's draft (not found / invalid are typed refusals). */
+export async function readAnnotationDraft(dir, id) {
+    const draftPath = annotationDraftPath(dir, id);
+    let raw;
+    try {
+        raw = await readFile(draftPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new AnnotationDraftNotFoundError(`no annotation draft for journey '${id}' (${draftPath}) — run \`jevitate journey annotate ${id}\` first`);
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new InvalidAnnotationDraftError(`${draftPath} is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = AnnotationDraftSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new InvalidAnnotationDraftError(`${draftPath} is not a valid annotation draft: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    }
+    if (result.data.journeyId !== id) {
+        throw new InvalidAnnotationDraftError(`${draftPath} is a draft for journey '${result.data.journeyId}', not '${id}'`);
+    }
+    return { draft: result.data, draftPath };
+}
+/**
+ * The human approval gate (like `journey promote`): applies the reviewed draft to the Journey and
+ * removes the draft. Refuses — writing nothing — when the Journey changed since the draft was made
+ * (its content hash differs) or the draft names steps the Journey does not have.
+ */
+export async function approveJourneyAnnotations(dir, id) {
+    const journey = await loadJourney(dir, id);
+    const { draft, draftPath } = await readAnnotationDraft(dir, id);
+    if (journeyContentHash(journey) !== draft.journeyHash) {
+        throw new StaleAnnotationDraftError(`journey '${id}' changed after this draft was made (${draftPath}) — re-run \`jevitate journey annotate ${id}\` to draft against the current Journey`);
+    }
+    let applied;
+    try {
+        applied = applyAnnotationDraft(journey, draft);
+    }
+    catch (err) {
+        if (err instanceof AnnotationDraftMismatchError)
+            throw new InvalidAnnotationDraftError(err.message);
+        throw err;
+    }
+    if (applied.changes.length > 0)
+        await new FsJourneyStore(dir).put(applied.journey);
+    await rm(draftPath, { force: true });
+    return { id, draftPath, changes: applied.changes, coverage: intentCoverage(applied.journey) };
+}
+/** `journey run`'s informational intent line (#246): how many steps say why. Never fails a run. */
+export async function journeyIntentCoverage(dir, id) {
+    try {
+        const journey = await new FsJourneyStore(dir).get(id);
+        return journey === null ? undefined : intentCoverage(journey);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=journey-annotate-api.js.map

package/dist/journey-annotate-api.js.map

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

package/dist/journey-annotate-cli.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/**
+ * #246 — `jevitate journey annotate <id>`: replay the Journey and DRAFT its intent (each step's
+ * objective / expected result, the goal and success criteria when missing) into a sidecar file;
+ * `--approve` is the human gate that writes a reviewed draft into the Journey (refused when the
+ * Journey changed since the draft). The model never edits a Journey on its own.
+ */
+export declare function registerJourneyAnnotateCommand(journey: Command, program: Command, deps: CliDeps): void;

package/dist/journey-annotate-cli.js

@@ -0,0 +1,181 @@
+import { existsSync } from "node:fs";
+import { ParamValidationError, formatAnnotationChanges } from "@jevitate/journey";
+import { MissingCredentialError, SecretLeakError } from "@jevitate/ai-core";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { ok, fail } from "./envelope.js";
+import { UnknownJourneyError, JourneyRequiresAuthError } from "./journey-api.js";
+import { formatScreenshotsLine, parseScreenshotsArg } from "./run-screenshots.js";
+import { annotateJourney, approveJourneyAnnotations, AnnotationDraftNotFoundError, InvalidAnnotationDraftError, StaleAnnotationDraftError, } from "./journey-annotate-api.js";
+import { withSiteGate } from "./site-gate-cli.js";
+import { buildMissionFixtures, checkSetupRefs, withFixtureFlags } from "./fixture-cli.js";
+import { FixtureSetupError, FixtureSpecError, UnboundSetupRefError } from "./mission-fixtures.js";
+import { withEngine } from "./engine.js";
+import { EXIT_CODES } from "./exit-codes.js";
+import { environmentFromFlags, isEnvironmentError, withEnvironmentFlags } from "./environments.js";
+import { resolveDbPath, resolveJourneysDir, withBrowserLaunchFlags, withScreenshotsFlag, browserOption, withEmulationFlags, emulationFromFlags, collectParam, emitJson, emitUsageLine, environmentSeams, GatewaySelectionError, buildGenerationGateway, } from "./cli-shared.js";
+/**
+ * #246 — `jevitate journey annotate <id>`: replay the Journey and DRAFT its intent (each step's
+ * objective / expected result, the goal and success criteria when missing) into a sidecar file;
+ * `--approve` is the human gate that writes a reviewed draft into the Journey (refused when the
+ * Journey changed since the draft). The model never edits a Journey on its own.
+ */
+export function registerJourneyAnnotateCommand(journey, program, deps) {
+    withScreenshotsFlag(withEnvironmentFlags(withBrowserLaunchFlags(withEmulationFlags(withFixtureFlags(journey.command("annotate <id>"))))))
+        .description("draft each step's objective/expected result (and the goal/success criteria when missing) by replaying the Journey; " +
+        "writes a reviewable draft, never the Journey — `--approve` applies a reviewed draft (human gate)")
+        .option("--dir <path>", "journeys directory (default: the repo's .jevitate/journeys; outside a repo ~/.jevitate/journeys)")
+        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
+        .option("--storage-state <file>", "Playwright storageState JSON to start the replay authenticated; must exist")
+        .option("--real", "draft with the live OpenRouter generation gateway (requires keys)", false)
+        .option("--fake-ai", "draft with the deterministic fake generator (pipeline smoke only)", false)
+        .option("--approve", "apply the reviewed draft to the Journey (shows the diff; refused if the Journey changed since the draft)", false)
+        .option("--action-deltas", "opt-in (#303): record what each replayed step changed and draft its expected result from that delta (by code, redacted) — the model is asked only for what the delta cannot say")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (id) {
+        const ownFixtureFlags = this.opts();
+        const { dir, param, storageState: storageStateFlag, real, fakeAi, approve, json, env: envName, baseUrl, screenshots: screenshotsFlag, actionDeltas, ...emulationFlags } = this.opts();
+        const out = program.configureOutput().writeOut;
+        const journeysDir = resolveJourneysDir(deps, dir);
+        if (approve === true) {
+            if (real === true ||
+                fakeAi === true ||
+                Object.keys(param).length > 0 ||
+                storageStateFlag !== undefined ||
+                envName !== undefined ||
+                baseUrl !== undefined ||
+                screenshotsFlag !== undefined) {
+                emitJson(program, fail("E_JOURNEY_ANNOTATE_ARGS", "--approve applies an existing draft: it replays nothing, so it takes no --real/--fake-ai/--param/--storage-state/--env/--base-url/--screenshots"));
+                return;
+            }
+            try {
+                const result = await approveJourneyAnnotations(journeysDir, id);
+                if (json) {
+                    emitJson(program, ok(result));
+                }
+                else {
+                    out?.(formatAnnotationChanges(result.changes));
+                    out?.(`applied ${result.changes.length} change(s) to journey '${id}' (${result.coverage.withObjective}/${result.coverage.steps} steps now have an objective)\n`);
+                    process.exitCode = EXIT_CODES.ok;
+                }
+            }
+            catch (err) {
+                if (err instanceof UnknownJourneyError)
+                    emitJson(program, fail("E_UNKNOWN_JOURNEY", err.message));
+                else if (err instanceof AnnotationDraftNotFoundError || err instanceof InvalidAnnotationDraftError || err instanceof StaleAnnotationDraftError) {
+                    emitJson(program, fail(err.code, err.message));
+                }
+                else
+                    emitJson(program, fail("E_JOURNEY_ANNOTATE", String(err instanceof Error ? err.message : err)));
+            }
+            return;
+        }
+        // #247: --env/--base-url choose where the replay runs — the same resolver as `journey run`
+        // (unknown env / bad file / secret in environments.json → 64, nothing opened).
+        let environment;
+        try {
+            environment = environmentFromFlags({ ...(envName === undefined ? {} : { env: envName }), ...(baseUrl === undefined ? {} : { baseUrl }) }, environmentSeams(deps));
+        }
+        catch (err) {
+            if (!isEnvironmentError(err))
+                throw err;
+            emitJson(program, fail(err.code, err.message));
+            return;
+        }
+        // The environment's fixtures/hooks apply when the flags name none (hooks still need --allow-shell-hooks).
+        const fixtureFlags = {
+            ...ownFixtureFlags,
+            ...(ownFixtureFlags.before === undefined && environment?.hooks?.before !== undefined ? { before: environment.hooks.before } : {}),
+            ...(ownFixtureFlags.after === undefined && environment?.hooks?.after !== undefined ? { after: environment.hooks.after } : {}),
+        };
+        // --storage-state wins; else the environment's own session (~/.jevitate/targets.json[<origin>]).
+        const storageState = storageStateFlag ?? environment?.storageState;
+        if (storageState !== undefined && !existsSync(storageState)) {
+            emitJson(program, fail("E_JOURNEY_ANNOTATE_ARGS", `storage state not found: ${storageState}`));
+            return;
+        }
+        let emulation;
+        let screenshots;
+        try {
+            emulation = emulationFromFlags(emulationFlags);
+            screenshots = parseScreenshotsArg(screenshotsFlag);
+        }
+        catch (err) {
+            emitJson(program, fail("E_JOURNEY_ANNOTATE_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        let gateway;
+        try {
+            gateway = await buildGenerationGateway(deps, { real: real ?? false, fakeAi: fakeAi ?? false });
+        }
+        catch (err) {
+            if (err instanceof MissingCredentialError || err instanceof GatewaySelectionError)
+                emitJson(program, fail("E_AI_SETUP_REQUIRED", err.message));
+            else
+                emitJson(program, fail("E_JOURNEY_ANNOTATE", String(err instanceof Error ? err.message : err)));
+            return;
+        }
+        try {
+            const result = await withSiteGate(resolveDbPath(deps), (siteGate) => annotateJourney({
+                ...(siteGate === undefined ? {} : { siteGate }),
+                dir: journeysDir,
+                id,
+                params: param,
+                gen: gateway.gen,
+                browserPortFactory: deps.explore?.browserPortFactory,
+                ...browserOption(this.opts()),
+                ...(emulation === undefined ? {} : { emulation }),
+                ...(screenshots === undefined ? {} : { screenshots }),
+                ...(actionDeltas === true ? { actionDeltas: true } : {}),
+                ...(storageState !== undefined ? { storageState } : {}),
+                ...(environment === undefined ? {} : { environment }),
+                fixtures: (site) => {
+                    const fx = buildMissionFixtures(fixtureFlags, {
+                        allowlist: environment === undefined ? [site] : environment.allowedOrigins,
+                        baseUrl: site,
+                        ...(storageState !== undefined ? { storageState } : {}),
+                        ...(environment?.fixtures === undefined ? {} : { targetFixtures: environment.fixtures }),
+                    });
+                    checkSetupRefs({ "--param": Object.values(param) }, fx);
+                    return fx;
+                },
+            }));
+            const data = withEngine({ ...result, usage: gateway.usage.snapshot() });
+            // A replay that stopped early drafted only the steps it reached: the command did not finish its work.
+            const exit = result.replay.outcome === "completed" ? EXIT_CODES.ok : EXIT_CODES.inconclusive;
+            if (json) {
+                emitJson(program, ok(data));
+            }
+            else {
+                const r = result.replay;
+                out?.(`drafted annotations for journey '${id}' (${r.reachedSteps}/${r.totalSteps} steps replayed${r.outcome === "stopped" ? `; stopped: ${r.reason ?? "unknown"}` : ""}): ` +
+                    `${result.drafted.objectives} objective(s), ${result.drafted.expectedResults} expected result(s)` +
+                    `${result.drafted.goal ? ", a goal" : ""}${result.drafted.successCriteria > 0 ? `, ${result.drafted.successCriteria} success criterion(s)` : ""}\n`);
+                out?.(formatAnnotationChanges(result.proposed));
+                out?.(`draft: ${result.draftPath}\nreview or edit it, then apply it: jevitate journey annotate ${id} --approve\n`);
+                if (result.screenshotIndex !== undefined)
+                    out?.(formatScreenshotsLine(result));
+                emitUsageLine(program, data);
+            }
+            process.exitCode = exit;
+        }
+        catch (err) {
+            if (err instanceof SiteGateRefusedError || isEnvironmentError(err))
+                emitJson(program, fail(err.code, err.message));
+            else if (err instanceof UnknownJourneyError)
+                emitJson(program, fail("E_UNKNOWN_JOURNEY", err.message));
+            else if (err instanceof JourneyRequiresAuthError)
+                emitJson(program, fail("E_JOURNEY_REQUIRES_AUTH", err.message));
+            else if (err instanceof ParamValidationError)
+                emitJson(program, fail("E_INVALID_PARAMS", err.message));
+            else if (err instanceof FixtureSpecError || err instanceof UnboundSetupRefError)
+                emitJson(program, fail(err.code, err.message));
+            else if (err instanceof FixtureSetupError)
+                emitJson(program, fail("E_JOURNEY_ANNOTATE", err.message));
+            else if (err instanceof SecretLeakError)
+                emitJson(program, fail("E_JOURNEY_ANNOTATE_SECRET", err.message));
+            else
+                emitJson(program, fail("E_JOURNEY_ANNOTATE", String(err instanceof Error ? err.message : err)));
+        }
+    });
+}
+//# sourceMappingURL=journey-annotate-cli.js.map

package/dist/journey-annotate-cli.js.map

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

package/dist/journey-api.d.ts

@@ -1,5 +1,14 @@
+import { type Journey } from "@jevitate/journey";
 import { type RunPolicy } from "@jevitate/domain";
-import { type JourneyRunResult, type SelfHealer } from "@jevitate/runtime";
+import { type BrowserPort, type BrowserSession, type EmulationSpec } from "@jevitate/playwright";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+import { RecordingInterpreter, type StepObserver } from "@jevitate/interpreter";
+import { type ReplayDeltaSummary } from "@jevitate/explore";
+import { SecretPixelMask } from "./demo-capture.js";
+import { type ScreenshotsResult, type ScreenshotsSpec } from "./run-screenshots.js";
+import { type JourneyRunResult, type SelfHealer, type SiteGateDeps } from "@jevitate/runtime";
+import { type FixtureRecord, type MissionFixtures } from "./mission-fixtures.js";
+import { type ResolvedJourneyEnvironment } from "./environments.js";
 /**
  * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
  * can tell "no such journey" apart from "params didn't match the journey's
@@ -7,6 +16,13 @@ import { type JourneyRunResult, type SelfHealer } from "@jevitate/runtime";
  */
 export declare class UnknownJourneyError extends Error {
 }
+/**
+ * A Journey declares `metadata.requiresAuth: true` (#118) but the run was given no
+ * `storageState` — refused BEFORE any browser launches, with a message that names the
+ * actual problem instead of a confusing `replay-target-not-found` deep into the steps.
+ */
+export declare class JourneyRequiresAuthError extends Error {
+}
 export interface RunJourneyProgrammaticallyOptions {
     /** Directory a `FsJourneyStore` reads Journey JSON files from. */
     dir: string;
@@ -24,7 +40,89 @@ export interface RunJourneyProgrammaticallyOptions {
      * this port (enforced by `JourneyRunner`'s write floor).
      */
     selfHealer?: SelfHealer;
+    /**
+     * Mission fixtures (#140/#144), built for the journey's own site once it is known: set up before
+     * the browser opens (a failure throws `FixtureSetupError` — the journey never runs on unknown
+     * state), `${setup.<name>}` in params bound to its outputs, and restored after the run.
+     */
+    fixtures?: (site: string) => MissionFixtures | undefined;
+    /**
+     * Playwright storageState JSON to seed the session from (CLI/MCP `--storage-state`, #118) —
+     * the deterministic authenticated pre-step a Journey authored behind a login needs to
+     * replay. Contains live session cookies: handed only to the browser, never logged, never
+     * returned in the result, and never sent to a model.
+     */
+    storageState?: string;
+    /** Testing seam — defaults to a real `PlaywrightBrowserPort`. */
+    browserPortFactory?: () => BrowserPort;
+    /** How Chromium is launched (executable/channel/extra args) and shown (#245 demo mode). Default: pinned Chromium, headless. */
+    browser?: BrowserRunOptions;
+    /** Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`). */
+    emulation?: EmulationSpec;
+    /**
+     * The site-policy gate's repositories (`jevitate site policy set`): pacing, throttles, budgets and
+     * quiet hours for the Journey's origin. Absent (no policy database) means no site policy applies.
+     */
+    siteGate?: SiteGateDeps;
+    /** The site-policy account (default `primary`, as `jevitate site policy` uses). */
+    account?: string;
+    /**
+     * #246 seam: the interpreter the run replays with — `journey annotate` passes one carrying a
+     * `StepObserver` (before/after page evidence). Default: a plain `RecordingInterpreter`.
+     */
+    interpreter?: RecordingInterpreter;
+    /**
+     * The environment to run against (#247, `--env`/`--base-url`, from `resolveJourneyEnvironment`):
+     * the Journey's recorded same-origin URLs move onto its `baseUrl` and the run's allowlist is its
+     * `allowedOrigins`; a step on any other origin is refused before any fixture or browser.
+     * Absent: the Journey's recorded site, exactly as before.
+     */
+    environment?: ResolvedJourneyEnvironment;
+    /**
+     * #251 `--screenshots`: one masked screenshot per distinct screen (or per step) + `index.md`;
+     * the paths come back as `screenshotPaths`. Absent: none.
+     */
+    screenshots?: ScreenshotsSpec;
+    /** #251 seam: a per-step observer composed into the default interpreter (annotate, demo). Ignored with `interpreter`. */
+    observer?: StepObserver;
+    /**
+     * #250/#251: the run's pixel mask (default: one over the Journey's secret parameters) — installed
+     * on the session before its first navigation whenever it records video or screenshots.
+     */
+    mask?: SecretPixelMask;
+    /**
+     * #293 journey-anchored exploration: replay in THIS already-open session and leave it open (the
+     * caller's mission continues in the same page, form contents and session). No browser is opened
+     * or closed here; video/screenshots belong to the caller's session.
+     */
+    session?: BrowserSession;
+    /**
+     * #293: replay only the first N top-level steps — the prefix up to an anchor. A `--param` the
+     * Journey does not take is still refused; one only a later step uses is not required (and unused).
+     */
+    stopAfterStep?: number;
+    /**
+     * #303 `--action-deltas` (opt-in): record what each replayed step changed (redacted, code verdict)
+     * and compare it with the delta the Journey's Recording stored — returned as `actionDeltas`.
+     * Observation only: it never changes the replay. Off: nothing is captured.
+     */
+    actionDeltas?: boolean;
 }
+/**
+ * #293: the params a Journey PREFIX runs with — a `--param` the whole Journey does not take is
+ * refused (`ParamValidationError`), one only a later step uses is dropped; the prefix's own required
+ * params are then checked by `validateParams` as usual.
+ */
+export declare function prefixParams(full: Journey, prefix: Journey, params: Record<string, string>): Record<string, string>;
+/**
+ * Promotes a local Journey (#124, mirrors `promoteMissionTarget` in
+ * `mission-api.ts`) so it becomes discoverable via `journey find`/MCP
+ * `find_capabilities` and runnable via `run_journey` — a human-approval gate,
+ * same as `mission target promote`. An unknown id is refused with
+ * `UnknownJourneyError` (never silently created). Returns the persisted,
+ * now-promoted Journey.
+ */
+export declare function promoteJourney(dir: string, id: string): Promise<Journey>;
 /**
  * The one programmatic surface for "run this published Journey by id" —
  * used by BOTH the CLI `journey run` action and external callers. Builds
@@ -34,4 +132,8 @@ export interface RunJourneyProgrammaticallyOptions {
  * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
  * launched, then builds the real Actor + `JourneyRunner` and runs.
  */
-export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions): Promise<JourneyRunResult>;
+export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions): Promise<JourneyRunResult & {
+    fixtures?: FixtureRecord;
+    videoPaths?: string[];
+    actionDeltas?: ReplayDeltaSummary;
+} & Partial<ScreenshotsResult>>;