@jevitate/cli 0.1.0 → 0.2.0

package/dist/result-schema.d.ts

@@ -0,0 +1,22 @@
+import type { ServerLogDefect } from "./log-correlation.js";
+/**
+ * The versioned result schema every explore strategy's result follows (#195 part 5) — defined in
+ * `@jevitate/domain` (zod + TS) and re-exported here as part of the CLI's published surface. See
+ * `mission-result.ts` there for the contract; this module holds the helpers the runners fill the
+ * common fields with, so every strategy fills them the same way.
+ */
+export { MISSION_RESULT_SCHEMA_VERSION, MissionResultSchema, PersistedMissionResultSchema, RESULT_STRATEGIES, RESULT_MISSION_OUTCOMES, ResultDefectSchema, type MissionResult, type MissionResultCore, type PersistedMissionResult, type ResultDefect, type ResultMissionOutcome, type ResultStrategy, } from "@jevitate/domain";
+/** A `server-log` defect a strategy reports but never gates on (usability: every UX finding is advisory). */
+export type AdvisoryServerLogDefect = ServerLogDefect & {
+    readonly advisory: true;
+};
+/**
+ * All of a run's defects in ONE list (#195): the strategy's own (hard-signal / declared-invariant)
+ * defects first, then its `server-log` defects — each fingerprint once. What `defects` holds on every
+ * strategy's result; `serverLogDefects` remains only as a deprecated alias of the server-log subset.
+ */
+export declare function unifiedDefects<D extends {
+    readonly fingerprint: string;
+}>(own: readonly D[] | undefined, serverLog: readonly ServerLogDefect[] | undefined): Array<D | ServerLogDefect>;
+/** A usability run's `server-log` defects, marked advisory: reported in `defects`, never gating its outcome. */
+export declare function advisoryDefects(serverLog: readonly ServerLogDefect[] | undefined): AdvisoryServerLogDefect[];

package/dist/result-schema.js

@@ -0,0 +1,28 @@
+/**
+ * The versioned result schema every explore strategy's result follows (#195 part 5) — defined in
+ * `@jevitate/domain` (zod + TS) and re-exported here as part of the CLI's published surface. See
+ * `mission-result.ts` there for the contract; this module holds the helpers the runners fill the
+ * common fields with, so every strategy fills them the same way.
+ */
+export { MISSION_RESULT_SCHEMA_VERSION, MissionResultSchema, PersistedMissionResultSchema, RESULT_STRATEGIES, RESULT_MISSION_OUTCOMES, ResultDefectSchema, } from "@jevitate/domain";
+/**
+ * All of a run's defects in ONE list (#195): the strategy's own (hard-signal / declared-invariant)
+ * defects first, then its `server-log` defects — each fingerprint once. What `defects` holds on every
+ * strategy's result; `serverLogDefects` remains only as a deprecated alias of the server-log subset.
+ */
+export function unifiedDefects(own, serverLog) {
+    const seen = new Set();
+    const out = [];
+    for (const d of [...(own ?? []), ...(serverLog ?? [])]) {
+        if (seen.has(d.fingerprint))
+            continue;
+        seen.add(d.fingerprint);
+        out.push(d);
+    }
+    return out;
+}
+/** A usability run's `server-log` defects, marked advisory: reported in `defects`, never gating its outcome. */
+export function advisoryDefects(serverLog) {
+    return unifiedDefects([], serverLog).map((d) => ({ ...d, advisory: true }));
+}
+//# sourceMappingURL=result-schema.js.map

package/dist/result-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-schema.js","sourceRoot":"","sources":["../src/result-schema.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GAOnB,MAAM,kBAAkB,CAAC;AAK1B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,GAA6B,EAC7B,SAAiD;IAEjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,eAAe,CAAC,SAAiD;IAC/E,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC"}

package/dist/run-index.d.ts

@@ -0,0 +1,29 @@
+import { type LayoutDeps } from "./project-dir.js";
+/**
+ * #213: which runs belong to THIS project — so a bare `jevitate report`/`diff` reads the current
+ * project's runs, never every app's `~/.jevitate/logs` (a fresh project merged 167 unrelated runs),
+ * and still finds the runs written to an `--out` dir.
+ *
+ * Mechanism: every persisted result is recorded, best-effort, as one line
+ * `{"project": <key>, "path": <absolute result path>}` in the per-user index `~/.jevitate/run-index.jsonl`
+ * (machine-local, like the logs themselves; never in a repo). The project key is the directory that
+ * holds the project's `.jevitate/`, else the git root of the working directory, else the working
+ * directory itself. A bare report reads: the project's own `.jevitate/logs` (only this project writes
+ * there) plus every indexed result of this project that still exists — wherever it was written.
+ *
+ * `JEVITATE_RUN_INDEX=off` turns recording off (the test suite does, so it never touches the real index).
+ */
+export interface RunIndexDeps extends LayoutDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Test seam: the index file (default `~/.jevitate/run-index.jsonl`). */
+    readonly indexPath?: string;
+}
+export declare function runIndexPath(deps?: RunIndexDeps): string;
+/** The current project's key: the dir holding its `.jevitate/`, else the git root, else the cwd. */
+export declare function projectKey(deps?: LayoutDeps): string;
+/** Records one persisted result for the current project. Never throws: an index is a convenience. */
+export declare function recordRun(resultPath: string, deps?: RunIndexDeps): void;
+/** Every indexed result of the current project that still exists, oldest first, each once. */
+export declare function indexedRunsFor(deps?: RunIndexDeps): string[];
+/** The current project's own dated logs dirs (`<repo>/.jevitate/logs/<date>`) — none outside a project. */
+export declare function projectLogDirs(deps?: LayoutDeps): string[];

package/dist/run-index.js

@@ -0,0 +1,70 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { findGitRoot, findProjectDir, homeDataRoot } from "./project-dir.js";
+export function runIndexPath(deps = {}) {
+    return deps.indexPath ?? join(homeDataRoot(deps), "run-index.jsonl");
+}
+/** The current project's key: the dir holding its `.jevitate/`, else the git root, else the cwd. */
+export function projectKey(deps = {}) {
+    const project = findProjectDir(deps);
+    if (project !== null)
+        return dirname(project);
+    const cwd = resolve((deps.cwd ?? (() => process.cwd()))());
+    return findGitRoot(cwd) ?? cwd;
+}
+/** Records one persisted result for the current project. Never throws: an index is a convenience. */
+export function recordRun(resultPath, deps = {}) {
+    if ((deps.env ?? process.env)["JEVITATE_RUN_INDEX"] === "off")
+        return;
+    try {
+        const path = runIndexPath(deps);
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify({ project: projectKey(deps), path: resolve(resultPath) })}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // best-effort: a run's result is never replaced by an index failure
+    }
+}
+/** Every indexed result of the current project that still exists, oldest first, each once. */
+export function indexedRunsFor(deps = {}) {
+    const path = runIndexPath(deps);
+    if (!existsSync(path))
+        return [];
+    const key = projectKey(deps);
+    const out = new Set();
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e.project === key && typeof e.path === "string" && existsSync(e.path))
+                out.add(e.path);
+        }
+        catch {
+            continue; // a torn line names nothing
+        }
+    }
+    return [...out];
+}
+/** The current project's own dated logs dirs (`<repo>/.jevitate/logs/<date>`) — none outside a project. */
+export function projectLogDirs(deps = {}) {
+    const project = findProjectDir(deps);
+    if (project === null)
+        return [];
+    const root = join(project, "logs");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d))
+        .sort()
+        .reverse()
+        .map((d) => join(root, d));
+}
+//# sourceMappingURL=run-index.js.map

package/dist/run-index.js.map

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

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,229 @@
+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";
+/** 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;
+    }
+    #redact(s) {
+        return redactText(s, this.#opts.secrets);
+    }
+    /** 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) => 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.#opts.secrets, "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 and registered secrets 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}`), "");
+        }
+        return `${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,22 @@
+import { clickTimeoutMs } from "@jevitate/explore";
+import { 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 = [];
+    for (const check of [pageUnresponsiveMsFromEnv, clickTimeoutMs]) {
+        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,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,CAAC,yBAAyB,EAAE,cAAc,CAAC,EAAE,CAAC;QAChE,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"}