@jevitate/cli 0.1.0 → 0.3.0

package/dist/run-screenshots.d.ts

@@ -0,0 +1,123 @@
+import type { Page } from "playwright";
+import { type TranscriptEntry } from "@jevitate/explore";
+import type { StepObserver } from "@jevitate/interpreter";
+import type { BrowserPort } from "@jevitate/playwright";
+import { SecretPixelMask } from "./demo-capture.js";
+/**
+ * #251 — `--screenshots [dir]` / `--screenshots steps`: a screenshot capture mode for any run
+ * (explore strategies, `journey run`/`annotate`/`demo`, `verify-fix`).
+ *
+ *  - `screens` (the default): one screenshot per DISTINCT screen — deduplicated by the page-state
+ *    fingerprint coverage already uses (`coverageStateFingerprint`: the url template plus the
+ *    control table), so a new screen is a new state;
+ *  - `steps`: one per step.
+ *
+ * Every image is the viewport after the step acted, with the demo overlay hidden and every
+ * registered secret masked in pixels ({@link SecretPixelMask}); a capture whose mask cannot be
+ * proven is SKIPPED and its reason recorded (fail closed). An `index.md` contact sheet lists each
+ * image with its step, route and what happened (all text redacted, proven secret-free before it is
+ * written). The paths go in the result as `screenshotPaths` (+ `screenshotIndex`, and
+ * `screenshotsSkipped` when a capture was refused).
+ */
+export type ScreenshotMode = "screens" | "steps";
+export interface ScreenshotsSpec {
+    readonly mode: ScreenshotMode;
+    /** Where the images go; absent ⇒ `<run artifact stem>.screenshots/` beside the run's output. */
+    readonly dir?: string;
+}
+/** An unusable `--screenshots` value: refused before anything runs (exit 64). */
+export declare class ScreenshotsArgError extends Error {
+    readonly code: "E_SCREENSHOTS_ARGS";
+    constructor(message: string);
+}
+/**
+ * `--screenshots` → the spec: bare / `screens` → one per distinct screen; `steps` → one per step;
+ * `screens:<dir>` / `steps:<dir>` → that mode into `<dir>`; any other value is the directory
+ * (screens mode). An empty value is refused.
+ */
+export declare function parseScreenshotsArg(v: string | boolean | undefined, where?: string): ScreenshotsSpec | undefined;
+/** The run's screenshot folder: `spec.dir`, else `<dir of artifact>/<artifact stem>.screenshots`. */
+export declare function screenshotsDirFor(spec: ScreenshotsSpec, artifactPath: string): string;
+export interface ScreenshotEntry {
+    /** 1-based image number. */
+    readonly n: number;
+    /** The step it shows (after that step acted). */
+    readonly step: number;
+    /** The route (path) it was taken on, redacted. */
+    readonly route: string;
+    /** What the step did (redacted). */
+    readonly what: string;
+    readonly path: string;
+}
+export interface ScreenshotSkip {
+    readonly step: number;
+    readonly reason: string;
+}
+/** The additive result fields (schemaVersion 1). */
+export interface ScreenshotsResult {
+    readonly screenshotPaths: string[];
+    readonly screenshotIndex: string;
+    readonly screenshotsSkipped?: ScreenshotSkip[];
+}
+export interface RunScreenshotsOptions {
+    readonly spec: ScreenshotsSpec;
+    /** The resolved folder (see {@link screenshotsDirFor}). */
+    readonly dir: string;
+    /** Every registered secret: masked in pixels, redacted in the index. */
+    readonly secrets: readonly string[];
+    /** The contact sheet's heading (redacted). */
+    readonly title: string;
+    /** A shared mask (e.g. the one a masking port installed); default: a new one over `secrets`. */
+    readonly mask?: SecretPixelMask;
+}
+/** A transcript step as one "what happened" line. */
+export declare function describeTranscriptEntry(e: TranscriptEntry): string;
+export declare class RunScreenshots {
+    #private;
+    readonly mask: SecretPixelMask;
+    constructor(opts: RunScreenshotsOptions);
+    get mode(): ScreenshotMode;
+    /** Captures the page after `step` (queued: captures never overlap). Never throws. */
+    capture(page: Page, at: {
+        readonly step: number;
+        readonly url?: string;
+        readonly what: string;
+    }): Promise<void>;
+    /** TranscriptLog listener hook (explore runners): captures the page after the step just recorded. */
+    noteEntry(page: Page, entry: TranscriptEntry): void;
+    /** Every capture done; writes `index.md`; the result fields. */
+    finish(): Promise<ScreenshotsResult>;
+    /** The Markdown contact sheet (images linked relative to the index). */
+    contactSheet(): string;
+}
+/** A per-step observer for an interpreter-driven replay (journey run/annotate/demo, verify-fix). */
+export declare function screenshotObserver(shots: RunScreenshots, pageOf: (actor: Parameters<NonNullable<StepObserver["afterStep"]>>[0]["actor"]) => Page, whatOf: (index: number) => string): StepObserver;
+/** Runs every observer's hooks in order (an observer never changes the replay). */
+export declare function composeObservers(...observers: ReadonlyArray<StepObserver | undefined>): StepObserver;
+/** The human summary line for a run's screenshots (#251). */
+export declare function formatScreenshotsLine(r: {
+    readonly screenshotPaths?: readonly string[];
+    readonly screenshotIndex?: string;
+    readonly screenshotsSkipped?: readonly ScreenshotSkip[];
+}): string;
+/** One run's capture wiring (#250/#251): the masked port and the (optional) screenshots. */
+export interface RunCapture {
+    readonly mask: SecretPixelMask;
+    /** `factory` whose sessions carry the live pixel mask when the run records video or screenshots. */
+    wrap(factory: () => BrowserPort): () => BrowserPort;
+    /** TranscriptLog hook: a screenshot of `page` after the step (no-op without `--screenshots`). */
+    noteEntry(page: Page, entry: TranscriptEntry): void;
+    /** Awaits every capture, writes the index; the result fields (`{}` without `--screenshots`). */
+    finish(): Promise<Partial<ScreenshotsResult>>;
+}
+/**
+ * The capture wiring an explore runner threads through its session and listener. `artifactPath` is
+ * read on first use (the run's Recording path: screenshots go in `<stem>.screenshots/` beside it).
+ */
+export declare function runCaptureFor(o: {
+    readonly recordsVideo: boolean;
+    readonly screenshots: ScreenshotsSpec | undefined;
+    readonly secrets: readonly string[];
+    readonly artifactPath: () => string;
+    readonly title: string;
+}): RunCapture;

package/dist/run-screenshots.js

@@ -0,0 +1,235 @@
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { assertNoSecretInPayload, redactText, redactUrl } from "@jevitate/ai-core";
+import { coverageStateFingerprint, snapshot } from "@jevitate/explore";
+import { captureStepScreenshot, maskingPort, SecretPixelMask } from "./demo-capture.js";
+import { clock } from "@jevitate/domain";
+/** An unusable `--screenshots` value: refused before anything runs (exit 64). */
+export class ScreenshotsArgError extends Error {
+    code = "E_SCREENSHOTS_ARGS";
+    constructor(message) {
+        super(message);
+        this.name = "ScreenshotsArgError";
+    }
+}
+/**
+ * `--screenshots` → the spec: bare / `screens` → one per distinct screen; `steps` → one per step;
+ * `screens:<dir>` / `steps:<dir>` → that mode into `<dir>`; any other value is the directory
+ * (screens mode). An empty value is refused.
+ */
+export function parseScreenshotsArg(v, where = "--screenshots") {
+    if (v === undefined || v === false)
+        return undefined;
+    if (v === true)
+        return { mode: "screens" };
+    const t = v.trim();
+    if (t === "")
+        throw new ScreenshotsArgError(`${where} needs a mode or a directory: screens, steps, screens:<dir>, steps:<dir> or <dir>`);
+    if (t === "screens" || t === "steps")
+        return { mode: t };
+    const m = /^(screens|steps):(.*)$/.exec(t);
+    if (m !== null) {
+        const dir = (m[2] ?? "").trim();
+        if (dir === "")
+            throw new ScreenshotsArgError(`${where} ${m[1]}: needs a directory after the colon`);
+        return { mode: m[1], dir: resolvePath(dir) };
+    }
+    return { mode: "screens", dir: resolvePath(t) };
+}
+/** The run's screenshot folder: `spec.dir`, else `<dir of artifact>/<artifact stem>.screenshots`. */
+export function screenshotsDirFor(spec, artifactPath) {
+    if (spec.dir !== undefined)
+        return spec.dir;
+    const stem = basename(artifactPath).replace(/\.result\.json$/, "").replace(/\.json$/, "");
+    return join(dirname(artifactPath), `${stem}.screenshots`);
+}
+const FINGERPRINT_MS = 10_000;
+function oneLine(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+function routeOf(url) {
+    try {
+        const u = new URL(url);
+        return u.pathname + (u.search === "" ? "" : u.search);
+    }
+    catch {
+        return url;
+    }
+}
+/** A transcript step as one "what happened" line. */
+export function describeTranscriptEntry(e) {
+    const act = e.op === null ? "no action" : `${e.op}${e.target === null ? "" : ` ${e.target}`}`;
+    return e.actOk ? act : `${act} — failed${e.reason === undefined ? "" : `: ${e.reason}`}`;
+}
+export class RunScreenshots {
+    mask;
+    #opts;
+    #entries = [];
+    #skipped = [];
+    #seen = new Set();
+    #queue = Promise.resolve();
+    #prepared;
+    #maxStep = 0;
+    constructor(opts) {
+        this.#opts = opts;
+        this.mask = opts.mask ?? new SecretPixelMask(opts.secrets);
+    }
+    get mode() {
+        return this.#opts.spec.mode;
+    }
+    /** Registered secrets plus those the app revealed during the run (#298) — what the index must not hold. */
+    #known() {
+        return [...this.#opts.secrets, ...this.mask.revealed()];
+    }
+    #redact(s) {
+        return redactText(s, this.#known());
+    }
+    /** Creates the folder once and clears a previous run's images (never another file). */
+    #prepare() {
+        this.#prepared ??= (async () => {
+            await mkdir(this.#opts.dir, { recursive: true });
+            for (const f of await readdir(this.#opts.dir))
+                if (/^\d+-step-\d+\.png$/.test(f))
+                    await rm(join(this.#opts.dir, f), { force: true });
+        })();
+        return this.#prepared;
+    }
+    /** Captures the page after `step` (queued: captures never overlap). Never throws. */
+    capture(page, at) {
+        const run = async () => {
+            this.#maxStep = Math.max(this.#maxStep, at.step);
+            try {
+                if (page.isClosed())
+                    throw new Error("the page is closed");
+                await this.#prepare();
+                if (this.#opts.spec.mode === "screens") {
+                    const fp = await Promise.race([
+                        snapshot(page).then((s) => coverageStateFingerprint(s)),
+                        new Promise((r) => clock.setTimeout(() => r(null), FINGERPRINT_MS)),
+                    ]).catch(() => null);
+                    // An unreadable state cannot be proven a repeat: it is captured (never silently dropped).
+                    if (fp !== null && this.#seen.has(fp))
+                        return;
+                    await this.#shoot(page, at);
+                    if (fp !== null && this.#entries.some((e) => e.step === at.step))
+                        this.#seen.add(fp);
+                    return;
+                }
+                await this.#shoot(page, at);
+            }
+            catch (err) {
+                this.#skipped.push({ step: at.step, reason: this.#redact(oneLine(err instanceof Error ? err.message : String(err))).slice(0, 300) });
+            }
+        };
+        const next = this.#queue.then(run, run);
+        this.#queue = next;
+        return next;
+    }
+    async #shoot(page, at) {
+        const n = this.#entries.length + 1;
+        const path = join(this.#opts.dir, `${String(n).padStart(2, "0")}-step-${String(at.step).padStart(2, "0")}.png`);
+        await captureStepScreenshot(page, path, { step: at.step }, [this.mask.layer()]);
+        const url = at.url ?? page.url();
+        this.#entries.push({
+            n,
+            step: at.step,
+            route: this.#redact(redactUrl(routeOf(url))),
+            what: this.#redact(oneLine(at.what)).slice(0, 300),
+            path,
+        });
+    }
+    /** TranscriptLog listener hook (explore runners): captures the page after the step just recorded. */
+    noteEntry(page, entry) {
+        void this.capture(page, { step: entry.step, what: describeTranscriptEntry(entry) });
+    }
+    /** Every capture done; writes `index.md`; the result fields. */
+    async finish() {
+        await this.#queue;
+        await this.#prepare();
+        const index = join(this.#opts.dir, "index.md");
+        const md = this.contactSheet();
+        assertNoSecretInPayload(md, this.#known(), "screenshot index"); // the last line: never at rest
+        await writeFile(index, md, "utf8");
+        return {
+            screenshotPaths: this.#entries.map((e) => e.path),
+            screenshotIndex: index,
+            ...(this.#skipped.length === 0 ? {} : { screenshotsSkipped: [...this.#skipped] }),
+        };
+    }
+    /** The Markdown contact sheet (images linked relative to the index). */
+    contactSheet() {
+        const mode = this.#opts.spec.mode === "screens" ? "one per distinct screen" : "one per step";
+        const lines = [
+            `# Screenshots: ${oneLine(this.#redact(this.#opts.title))}`,
+            "",
+            `Mode: ${mode} · ${this.#entries.length} screenshot(s) over ${this.#maxStep} step(s). The demo overlay is hidden; registered secrets, elements the app marks as secret and credential-shaped values are masked in every image.`,
+            "",
+        ];
+        for (const e of this.#entries) {
+            const file = basename(e.path);
+            lines.push(`## ${e.n}. Step ${e.step} · \`${e.route.replace(/`/g, "'")}\``, "", `**What happened:** ${e.what}`, "", `![Step ${e.step}: ${e.route.replace(/[[\]]/g, "")}](${encodeURI(file)})`, "");
+        }
+        if (this.#skipped.length > 0) {
+            lines.push("## Not captured", "", ...this.#skipped.map((s) => `- step ${s.step}: ${s.reason}`), "");
+        }
+        // Re-redacted as a whole: a secret the app revealed after an entry was written is scrubbed too (#298).
+        return `${this.#redact(lines.join("\n")).trimEnd()}\n`;
+    }
+}
+/** A per-step observer for an interpreter-driven replay (journey run/annotate/demo, verify-fix). */
+export function screenshotObserver(shots, pageOf, whatOf) {
+    return {
+        afterStep: async ({ actor, index, outcome }) => {
+            const what = `${whatOf(index)}${outcome === "done" ? "" : outcome === "failed" ? " — failed" : " — waiting for a human"}`;
+            await shots.capture(pageOf(actor), { step: index + 1, what });
+        },
+    };
+}
+/** Runs every observer's hooks in order (an observer never changes the replay). */
+export function composeObservers(...observers) {
+    const list = observers.filter((o) => o !== undefined);
+    const each = async (fn) => {
+        for (const o of list) {
+            try {
+                await fn(o);
+            }
+            catch {
+                // One observer's failure never skips the next (nor changes the replay).
+            }
+        }
+    };
+    return {
+        beforeStep: (ctx) => each((o) => o.beforeStep?.(ctx)),
+        afterStep: (ctx) => each((o) => o.afterStep?.(ctx)),
+    };
+}
+/** The human summary line for a run's screenshots (#251). */
+export function formatScreenshotsLine(r) {
+    if (r.screenshotIndex === undefined)
+        return "";
+    const skipped = r.screenshotsSkipped ?? [];
+    return (`screenshots: ${(r.screenshotPaths ?? []).length} — index ${r.screenshotIndex}` +
+        `${skipped.length === 0 ? "" : ` (${skipped.length} not captured: ${skipped.map((s) => `step ${s.step}: ${s.reason}`).join("; ")})`}\n`);
+}
+/**
+ * The capture wiring an explore runner threads through its session and listener. `artifactPath` is
+ * read on first use (the run's Recording path: screenshots go in `<stem>.screenshots/` beside it).
+ */
+export function runCaptureFor(o) {
+    const mask = new SecretPixelMask(o.secrets);
+    const capturing = o.recordsVideo || o.screenshots !== undefined;
+    let shots;
+    const shotsOf = () => {
+        if (o.screenshots === undefined)
+            return undefined;
+        shots ??= new RunScreenshots({ spec: o.screenshots, dir: screenshotsDirFor(o.screenshots, o.artifactPath()), secrets: o.secrets, title: o.title, mask });
+        return shots;
+    };
+    return {
+        mask,
+        wrap: (factory) => (capturing ? () => maskingPort(factory(), mask) : factory),
+        noteEntry: (page, entry) => shotsOf()?.noteEntry(page, entry),
+        finish: async () => (await shotsOf()?.finish()) ?? {},
+    };
+}
+//# sourceMappingURL=run-screenshots.js.map

package/dist/run-screenshots.js.map

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

package/dist/runtime-env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Numeric `JEVITATE_*` tuning variables are validated ONCE, when the CLI starts, so a typo is a
+ * usage error (exit 64) before any browser opens — never a crash mid-run on the first click, and
+ * never a silent fall back to the default.
+ *
+ * Returns the problems found (empty when every set variable is valid).
+ */
+export declare function runtimeEnvProblems(env?: NodeJS.ProcessEnv): string[];

package/dist/runtime-env.js

@@ -0,0 +1,23 @@
+import { clickTimeoutMs } from "@jevitate/explore";
+import { governanceFromEnv, pageUnresponsiveMsFromEnv } from "@jevitate/playwright";
+/**
+ * Numeric `JEVITATE_*` tuning variables are validated ONCE, when the CLI starts, so a typo is a
+ * usage error (exit 64) before any browser opens — never a crash mid-run on the first click, and
+ * never a silent fall back to the default.
+ *
+ * Returns the problems found (empty when every set variable is valid).
+ */
+export function runtimeEnvProblems(env = process.env) {
+    const problems = [];
+    // #205: JEVITATE_RESOURCE_GOVERNANCE / JEVITATE_MAX_BROWSERS / JEVITATE_MAX_BROWSER_MEMORY_MB.
+    for (const check of [pageUnresponsiveMsFromEnv, clickTimeoutMs, governanceFromEnv]) {
+        try {
+            check(env);
+        }
+        catch (err) {
+            problems.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=runtime-env.js.map

package/dist/runtime-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../src/runtime-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEpF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,+FAA+F;IAC/F,KAAK,MAAM,KAAK,IAAI,CAAC,yBAAyB,EAAE,cAAc,EAAE,iBAAiB,CAAC,EAAE,CAAC;QACnF,IAAI,CAAC;YACH,KAAK,CAAC,GAAG,CAAC,CAAC;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/secret-args.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `--secret` values (#195 part 4): a literal, or `env:VAR` — read from the environment so the value
+ * never sits in the process list or shell history (the same `env:` binding `--secret-field` uses).
+ * Resolved HERE, at the CLI dispatch, before any browser opens; the resolved value is registered as a
+ * run secret exactly like a literal one (redacted from every model call, transcript and artifact).
+ *
+ * Fail closed: an unset/empty variable or a malformed ref is a refusal — never an empty secret, and
+ * never the literal text `env:VAR` standing in for the value. An error names the variable, never a
+ * value (a malformed ref is not echoed: it may be a value pasted in place of the variable name).
+ */
+export declare class SecretArgError extends Error {
+    constructor(message: string);
+}
+/** The warning a literal `--secret` earns (it still works): the value is visible to other processes. */
+export declare const LITERAL_SECRET_WARNING = "warning: a literal --secret is visible in the process list and shell history; pass --secret env:VAR to read it from the environment\n";
+/**
+ * Resolves each `--secret` value: `env:VAR` → `env[VAR]`, anything else → itself. `literals` counts
+ * the values given literally (for the caller's warning). Throws `SecretArgError`.
+ */
+export declare function resolveSecretArgs(values: readonly string[], env: Readonly<Record<string, string | undefined>>, flag: string): {
+    secrets: string[];
+    literals: number;
+};

package/dist/secret-args.js

@@ -0,0 +1,45 @@
+/**
+ * `--secret` values (#195 part 4): a literal, or `env:VAR` — read from the environment so the value
+ * never sits in the process list or shell history (the same `env:` binding `--secret-field` uses).
+ * Resolved HERE, at the CLI dispatch, before any browser opens; the resolved value is registered as a
+ * run secret exactly like a literal one (redacted from every model call, transcript and artifact).
+ *
+ * Fail closed: an unset/empty variable or a malformed ref is a refusal — never an empty secret, and
+ * never the literal text `env:VAR` standing in for the value. An error names the variable, never a
+ * value (a malformed ref is not echoed: it may be a value pasted in place of the variable name).
+ */
+export class SecretArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecretArgError";
+    }
+}
+const ENV_REF = "env:";
+const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The warning a literal `--secret` earns (it still works): the value is visible to other processes. */
+export const LITERAL_SECRET_WARNING = "warning: a literal --secret is visible in the process list and shell history; pass --secret env:VAR to read it from the environment\n";
+/**
+ * Resolves each `--secret` value: `env:VAR` → `env[VAR]`, anything else → itself. `literals` counts
+ * the values given literally (for the caller's warning). Throws `SecretArgError`.
+ */
+export function resolveSecretArgs(values, env, flag) {
+    const secrets = [];
+    let literals = 0;
+    for (const v of values) {
+        if (!v.startsWith(ENV_REF)) {
+            secrets.push(v);
+            literals += 1;
+            continue;
+        }
+        const name = v.slice(ENV_REF.length);
+        if (!VAR_NAME_RE.test(name)) {
+            throw new SecretArgError(`${flag} env:<VAR> expects an environment variable name (letters, digits, _; not starting with a digit)`);
+        }
+        const value = env[name];
+        if (value === undefined || value === "")
+            throw new SecretArgError(`${flag} env:${name}: environment variable ${name} is not set`);
+        secrets.push(value);
+    }
+    return { secrets, literals };
+}
+//# sourceMappingURL=secret-args.js.map

package/dist/secret-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-args.js","sourceRoot":"","sources":["../src/secret-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,GAAG,MAAM,CAAC;AACvB,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,wGAAwG;AACxG,MAAM,CAAC,MAAM,sBAAsB,GACjC,uIAAuI,CAAC;AAE1I;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAyB,EACzB,GAAiD,EACjD,IAAY;IAEZ,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,QAAQ,IAAI,CAAC,CAAC;YACd,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,cAAc,CAAC,GAAG,IAAI,iGAAiG,CAAC,CAAC;QACrI,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,MAAM,IAAI,cAAc,CAAC,GAAG,IAAI,QAAQ,IAAI,0BAA0B,IAAI,aAAa,CAAC,CAAC;QAClI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC"}

package/dist/serve-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/** Registers the long-running servers: `jevitate mcp` and `jevitate ui`. */
+export declare function registerServeCommands(program: Command, deps: CliDeps, buildProgram: (deps: CliDeps) => Command): void;

package/dist/serve-cli.js

@@ -0,0 +1,95 @@
+import { envCredentialStore, OpenRouterGenerationGateway } from "@jevitate/ai-core";
+import { loadLocalCredentials } from "./credentials-file.js";
+import { fail } from "./envelope.js";
+import { startMcpServer } from "./mcp-api.js";
+import { realOpenRouterCall } from "./openrouter-call.js";
+import { startUiServer } from "./ui-api.js";
+import { intArg } from "./cli-args.js";
+import { renderPrintConfig } from "./init-mcp.js";
+import { mcpToolDeps } from "./mcp-cli-bridge.js";
+import { makeInProcessCliRunner } from "./mcp-cli-runner.js";
+import { resolveJourneysDir, resolveInboxDir, emitJson, DEFAULT_EXPLORE_CATALOG, DEFAULT_EXPLORE_CONSTRAINTS, } from "./cli-shared.js";
+/** Registers the long-running servers: `jevitate mcp` and `jevitate ui`. */
+export function registerServeCommands(program, deps, buildProgram) {
+    // Additive: `jevitate mcp` (Ticket #20) — start an MCP stdio server that
+    // exposes ONLY `@jevitate/mcp-facade`'s allowlisted tools (never the raw
+    // browser primitives in FORBIDDEN_TOOLS). This is the subcommand form of the
+    // MCP server (single-bundle deployment — no separate published package).
+    // The server owns stdin/stdout as the MCP protocol channel, so on success it
+    // blocks and writes NOTHING to stdout; only a setup failure (before the
+    // transport connects) emits a JSON envelope.
+    program
+        .command("mcp")
+        .description("start an MCP stdio server exposing only the allowlisted Jevitate tools")
+        .option("--dir <path>", "journeys directory (default: the repo's .jevitate/journeys; outside a repo ~/.jevitate/journeys)")
+        .option("--print-config <harness>", "print the config snippet to register `jevitate mcp` in a harness (claude | cursor | codex | json) and exit — prints only, writes nothing")
+        .action(async function () {
+        const { dir, printConfig } = this.opts();
+        // `--print-config <harness>` is the universal escape hatch: render the
+        // exact registration snippet and exit WITHOUT starting the server (safe:
+        // no writes, no stdio takeover). An unknown harness is a fail envelope.
+        if (printConfig !== undefined) {
+            const harness = printConfig;
+            if (harness !== "claude" && harness !== "cursor" && harness !== "codex" && harness !== "json") {
+                emitJson(program, fail("E_MCP_PRINT_CONFIG", `--print-config must be one of claude | cursor | codex | json (got '${printConfig}')`));
+                return;
+            }
+            program.configureOutput().writeOut?.(`${renderPrintConfig(harness)}\n`);
+            process.exitCode = 0;
+            return;
+        }
+        try {
+            // Credential store + generation gateway for the allowlisted
+            // `ai_generate_text` tool. The gateway is the REAL OpenRouter adapter:
+            // the key is read only inside it (Authorization header only), every
+            // outbound payload passes the never-to-model guard, and the facade's
+            // preflight returns a typed `setup_required` when the key is absent —
+            // so no `--real/--fake` flag is needed for the non-interactive server.
+            const aiStore = envCredentialStore(deps.ai?.env ?? process.env, deps.ai?.localConfig ?? loadLocalCredentials());
+            const generationGateway = deps.ai?.gateway ??
+                new OpenRouterGenerationGateway({
+                    store: aiStore,
+                    catalog: deps.ai?.catalog ?? DEFAULT_EXPLORE_CATALOG,
+                    constraints: deps.ai?.constraints ?? DEFAULT_EXPLORE_CONSTRAINTS,
+                    call: await realOpenRouterCall(),
+                });
+            // #254: the same default stores the CLI's `inbox`/`mission queue`/`mission result` read (mcpToolDeps).
+            // #255: the CLI-mirroring tools run the SAME program in process, over the same journeys dir.
+            const journeysDir = resolveJourneysDir(deps, dir);
+            const runCli = makeInProcessCliRunner(() => buildProgram({ ...deps, journeysDir }));
+            await startMcpServer(mcpToolDeps(deps, { journeysDir, credentialStore: aiStore, generationGateway, runCli }));
+        }
+        catch (err) {
+            emitJson(program, fail("E_MCP_SERVE", String(err instanceof Error ? err.message : err)));
+        }
+    });
+    // Additive: `jevitate ui` (Task 8) — starts the local, loopback-only HTTP
+    // HITL approval dashboard (ui-api.ts's `startUiServer`). Resolves the SAME
+    // inbox dir `jevitate mcp`'s inbox tools serve (resolveInboxDir), so the
+    // two commands agree on where approvals/handbacks/reviews live. On success
+    // it prints the bound URL (carrying the capability token) and stays alive —
+    // the open HTTP server keeps the process running, the same way `mcp`'s open
+    // stdio transport does.
+    program
+        .command("ui")
+        .description("start the local HITL approval dashboard (loopback-only HTTP server)")
+        .option("--port <n>", "explicit port (fails on conflict; default 4180, retries on conflict)", intArg({ min: 0, max: 65535 }))
+        .option("--no-open", "do not open the dashboard URL in the default browser")
+        .option("--inbox-dir <path>", "inbox store directory (default: ~/.jevitate/inbox — same dir `jevitate mcp` serves)")
+        .action(async function () {
+        const o = this.opts();
+        try {
+            const start = deps.ui?.startUiServer ?? startUiServer;
+            const handle = await start({
+                inboxDir: resolveInboxDir(deps, o.inboxDir),
+                open: o.open ?? true,
+                ...(o.port !== undefined ? { port: Number(o.port) } : {}),
+            });
+            program.configureOutput().writeOut?.(`${handle.url}\n`);
+        }
+        catch (err) {
+            emitJson(program, fail("E_UI_SERVE", String(err instanceof Error ? err.message : err)));
+        }
+    });
+}
+//# sourceMappingURL=serve-cli.js.map

package/dist/serve-cli.js.map

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

package/dist/server-log-verify.d.ts

@@ -0,0 +1,36 @@
+import type { Recording } from "@jevitate/recording";
+import { type VerifyFixResult, type VerifySession } from "@jevitate/explore";
+/**
+ * `verify-fix` for a `server-log` defect (#142): NOT a re-check of `@jevitate/explore`'s
+ * `verifyFix` (which looks for a fingerprint among DOM/console/network signals — a server log line
+ * is none of those). Instead, this replays the defect's recorded steps in a fresh browser session
+ * AND re-opens the SAME log sources for the SAME drain window, and asks whether a line matching
+ * the SAME matcher and the SAME normalized message reappears. Kept entirely in the CLI layer (new
+ * file) — `packages/explore/src/verify-fix.ts` is untouched.
+ *
+ * Mirrors `verifyFix`'s own replay discipline (#74): `replays` fresh-context attempts, only ones
+ * that actually reached the defect's step count as evidence, and the pure `verifyReplayVerdict`
+ * rule (fired on every ran attempt ⇒ still-reproduces, none ⇒ fixed, a mix ⇒ intermittent — never
+ * "fixed" off one clean replay).
+ */
+export interface VerifyServerLogParams {
+    readonly recording: Recording;
+    /** Flat index of the last Recording step to replay (the defect's `repro.recordingStepIndex`). */
+    readonly recordingStepIndex: number;
+    readonly fingerprint: string;
+    /** The defect's persisted log sources (raw `--log-source` specs) and matcher (raw `--log-defect`). */
+    readonly sources: readonly string[];
+    readonly matcher: string;
+    readonly normalizedMessage: string;
+    readonly drainMs: number;
+    /** #282: the run's `--log-scope` (raw specs): only lines in scope count, as in the original run. */
+    readonly scope?: readonly string[];
+    readonly allowLogCmd: boolean;
+    /** Opens a FRESH browser session (never the one the defect was found in). */
+    readonly openSession: () => Promise<VerifySession>;
+    readonly settleCeilingMs?: number;
+    readonly targetTimeoutMs?: number;
+    /** Fresh-context replays (#74). Default `DEFAULT_VERIFY_REPLAYS` (mirrors `@jevitate/explore`). */
+    readonly replays?: number;
+}
+export declare function verifyServerLogDefect(params: VerifyServerLogParams): Promise<VerifyFixResult>;