@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/two-builds/compare-command.js

@@ -0,0 +1,314 @@
+/**
+ * `reticle compare <reference-url> <candidate-url> [--base <url>] [--json]`.
+ *
+ * Drives two running builds of one app the same way and reports each difference in what a person
+ * sees, for example main against a pull request preview. The app needs nothing installed: each run
+ * is a tab the daemon leases, and a page with no Reticle SDK gets the daemon's own reader. The rules
+ * are in `@/features/compare/behaviour-compare.ts`; this file connects them to the daemon over its
+ * MCP transport, with the same tool calls an agent makes.
+ */
+import { ActionType, isLocalhostSubdomain, isLoopbackHostname, ReticleTool, SnapshotMode, } from '@reticlehq/core';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { runCompare } from '../../../features/compare/behaviour-compare.js';
+import { compareReportHtml } from '../../../features/compare/compare-report-html.js';
+import { invalidComparison } from '../../../features/compare/behaviour-diff.js';
+import { compareExitCode, compareReportJson, compareReportLines, } from '../../../features/compare/behaviour-report.js';
+import { DriverLostError } from '../../../features/compare/build-readings.js';
+import { StateDeclarationSchema, readStateSources, } from '../../../features/compare/outside/state-sources.js';
+import { consoleLines, networkLines } from '../../../features/compare/outside/effect-lines.js';
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { callerArtifactRoot } from '../../../memory/project/link-directory.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
+import { acquireLease, connectOverSse, endpointFor, payloadOf, refusalText, releaseLease, } from '../daemon-link/daemon-client.js';
+/** How long a navigation may take before the start page counts as not loaded. */
+const NAVIGATE_WAIT_MS = 15_000;
+/** Room for one tool call past its own wait. */
+const CALL_MS = 60_000;
+/** The most network calls and console lines read for one sequence. */
+const EFFECTS_LIMIT = 50;
+/** How long fetching one page or script file may take. */
+const FETCH_MS = 10_000;
+/**
+ * Refusals that mean the driver lost its tab, not that the build did something. A run that sees
+ * one proves nothing about the build.
+ */
+const DRIVER_LOST = /no browser session connected|no connected session|multiple sessions connected|session disconnected|names no session|no such session|session ended/i;
+const MSG_NO_DAEMON = 'could not reach the daemon on port';
+const MSG_LEASE_FAILED = 'could not open a browser on';
+const MSG_STATE_UNREADABLE = 'could not read the state sources in';
+/** How long one state source read may take. */
+const STATE_READ_MS = 60_000;
+/** The most output one state command may give. */
+const STATE_OUTPUT_BYTES = 64 * 1024 * 1024;
+const SHELL = 'sh';
+const SHELL_COMMAND_FLAG = '-c';
+const DOCKER = 'docker';
+const DOCKER_EXEC = 'exec';
+const UTF8 = 'utf8';
+const asText = (value) => 'string' === typeof value ? value : undefined;
+/** The pairing token the daemon asks for, or undefined when there is none. */
+export function pairingToken() {
+    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir());
+    return token === undefined || 0 === token.length ? undefined : token;
+}
+/**
+ * A build on loopback or a `*.localhost` name is a disposable copy, so compare presses its guarded
+ * controls too ("Place order", "Delete"): they are the actions most worth comparing. On any other
+ * host the act guard stays on, so a compare can never delete real data.
+ */
+function isDisposableBuild(url) {
+    try {
+        const { hostname } = new URL(url);
+        return isLoopbackHostname(hostname) || isLocalhostSubdomain(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The act tool's args: a press names its key as `text`, a fill or a select its `value`. */
+function actArgs(action, value, guarded) {
+    if (value === undefined) {
+        return guarded;
+    }
+    return ActionType.PRESS === action ? { text: value, ...guarded } : { value, ...guarded };
+}
+/** One leased tab as the compare driver. Every call goes through `reticle_run` on that tab. */
+export function leasedPage(caller, url, sessionId) {
+    let id = sessionId;
+    const guarded = isDisposableBuild(url) ? { confirmDangerous: true } : {};
+    const run = async (tool, args, timeoutMs = CALL_MS) => {
+        let result;
+        try {
+            result = await caller.call(ReticleTool.RUN, { tool, args: { ...args, sessionId: id } }, timeoutMs);
+        }
+        catch (error) {
+            // Name the call, so a run that lost its driver says where.
+            throw new DriverLostError(`${tool}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const payload = payloadOf(result);
+        const refusal = refusalText(result) ?? asText(payload['error']);
+        if (refusal !== undefined && DRIVER_LOST.test(refusal)) {
+            throw new DriverLostError(`${tool}: ${refusal}`);
+        }
+        return refusal === undefined ? { payload } : { payload, refusal };
+    };
+    const navigate = async (to) => {
+        const { payload, refusal } = await run(ReticleTool.NAVIGATE, { url: to, timeout_ms: NAVIGATE_WAIT_MS }, NAVIGATE_WAIT_MS * 2);
+        id = asText(payload['sessionId']) ?? id;
+        return refusal === undefined && true === payload['ok'] && false !== payload['confirmed'];
+    };
+    /** Faults stay on the tab until cleared, and each fresh sequence must see the real server. */
+    let mocked = false;
+    const mockRequests = async (args) => {
+        const { payload, refusal } = await run(ReticleTool.NETWORK_MOCK, args);
+        return refusal === undefined && true === payload['applied'];
+    };
+    return {
+        async open() {
+            if (mocked) {
+                if (!(await mockRequests({ clear: true }))) {
+                    return false;
+                }
+                mocked = false;
+            }
+            return navigate(url);
+        },
+        mock(rules) {
+            mocked = true;
+            return mockRequests({ mocks: rules });
+        },
+        goto(query) {
+            return navigate(new URL(query, url).href);
+        },
+        async read() {
+            const { payload } = await run(ReticleTool.SNAPSHOT, { mode: SnapshotMode.FULL, ids: true });
+            return asText(payload['tree']) ?? '';
+        },
+        async act(at, action, value) {
+            const { payload, refusal } = await run(ReticleTool.ACT, {
+                ...('string' === typeof at ? { ref: at } : { target: at }),
+                action,
+                args: actArgs(action, value, guarded),
+            });
+            const ok = refusal === undefined && false !== payload['dispatched'];
+            const since = payload['since'];
+            return 'number' === typeof since ? { ok, since } : { ok };
+        },
+        async effects(since) {
+            // A refused read is passed on as `{ error }`, so it becomes a visible line, not an empty list.
+            const read = async (tool, args) => {
+                const { payload, refusal } = await run(tool, { since, ...args, limit: EFFECTS_LIMIT });
+                return refusal === undefined ? payload : { error: refusal };
+            };
+            return [
+                ...networkLines(await read(ReticleTool.NETWORK, { bodies: true })),
+                ...consoleLines(await read(ReticleTool.CONSOLE, {})),
+            ];
+        },
+        async close() {
+            await releaseLease(caller, id);
+        },
+    };
+}
+export const MSG_REPORT_WRITTEN = 'Report:';
+export const MSG_REPORT_FAILED = 'Report not written:';
+function writeReportFile(path, html) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, html);
+}
+const execFileText = promisify(execFile);
+/** State sources read on this machine: a shell, `docker exec`, `fetch` and the file system. */
+export const hostStateIo = {
+    async run(command, container) {
+        const [file, args] = container === undefined
+            ? [SHELL, [SHELL_COMMAND_FLAG, command]]
+            : [DOCKER, [DOCKER_EXEC, container, SHELL, SHELL_COMMAND_FLAG, command]];
+        const { stdout } = await execFileText(file, args, {
+            encoding: UTF8,
+            timeout: STATE_READ_MS,
+            maxBuffer: STATE_OUTPUT_BYTES,
+        });
+        return stdout;
+    },
+    async fetchJson(url) {
+        const response = await fetch(url, { signal: AbortSignal.timeout(STATE_READ_MS) });
+        if (!response.ok) {
+            throw new Error(`HTTP ${String(response.status)}`);
+        }
+        return response.json();
+    },
+    readFile: (path) => readFile(path, UTF8),
+};
+/** The sources in the `--state` file, or why they could not be read. */
+async function loadStateSources(path) {
+    try {
+        const parsed = StateDeclarationSchema.safeParse(JSON.parse(await readFile(path, UTF8)));
+        return parsed.success ? parsed.data.sources : { error: parsed.error.message };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Fetch a page or script file as a browser would. Undefined when it could not be fetched. */
+async function fetchText(url) {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_MS) });
+        return response.ok ? await response.text() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The exit code, and the text or the one JSON line to print. */
+function render(json, urls, result, timings, sink) {
+    const report = compareReportJson(urls, result, timings);
+    // A report that could not be written says so: a line in text mode, a field in the one JSON object.
+    let reportError;
+    if (sink !== undefined) {
+        try {
+            sink.write(sink.path, compareReportHtml(report));
+        }
+        catch (error) {
+            reportError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    if (json) {
+        return {
+            code: compareExitCode(result),
+            lines: [JSON.stringify(reportError === undefined ? report : { ...report, reportError })],
+        };
+    }
+    const lines = compareReportLines(urls, result, timings);
+    if (sink !== undefined) {
+        lines.push(reportError === undefined
+            ? `${MSG_REPORT_WRITTEN} ${sink.path}`
+            : `${MSG_REPORT_FAILED} ${sink.path}: ${reportError}`);
+    }
+    return { code: compareExitCode(result), lines };
+}
+/** Compare the builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export async function runCompareCommand(options) {
+    const urls = {
+        reference: options.reference,
+        candidate: options.candidate,
+        ...(options.base === undefined ? {} : { base: options.base }),
+    };
+    const sink = options.report === undefined
+        ? undefined
+        : { path: options.report, write: options.writeReport ?? writeReportFile };
+    let readState;
+    if (options.state !== undefined) {
+        const loaded = await loadStateSources(options.state);
+        if ('error' in loaded) {
+            const reason = `${MSG_STATE_UNREADABLE} ${options.state}: ${loaded.error}`;
+            return render(options.json, urls, invalidComparison(reason, 0), undefined, sink);
+        }
+        readState = () => readStateSources(loaded, hostStateIo);
+    }
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        caller = await connect(endpointFor(options.port, options.token));
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        const reason = `${MSG_NO_DAEMON} ${String(options.port)}: ${why}`;
+        return render(options.json, urls, invalidComparison(reason, 0), undefined, sink);
+    }
+    const open = async (url) => {
+        const lease = await acquireLease(caller, url, false, options.root);
+        if ('failed' in lease) {
+            throw new Error([`${MSG_LEASE_FAILED} ${url}`, ...lease.failed].join(' '));
+        }
+        return leasedPage(caller, url, lease.leased);
+    };
+    try {
+        const { result, timings } = await runCompare({
+            ...urls,
+            open,
+            sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+            now: options.now ?? Date.now,
+            fetchText: options.fetchText ?? fetchText,
+            ...(readState === undefined ? {} : { readState }),
+        });
+        return render(options.json, urls, result, timings, sink);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return render(options.json, urls, invalidComparison(reason, 0), undefined, sink);
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/**
+ * The command. It needs a daemon, as an agent does: `ensureDaemon` attaches to the one on the port,
+ * or starts one. Nothing here stops a daemon, so an agent's MCP link stays up.
+ */
+export async function handleCompare(parsed, ensureDaemon, out) {
+    const fail = (reason) => {
+        const sink = parsed.report === undefined ? undefined : { path: parsed.report, write: writeReportFile };
+        const result = render(parsed.json, parsed, invalidComparison(reason, 0), undefined, sink);
+        result.lines.forEach(out.line);
+        out.exit(result.code);
+    };
+    try {
+        await ensureDaemon(parsed.port);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+        return;
+    }
+    const token = pairingToken();
+    const root = callerArtifactRoot(process.cwd());
+    const result = await runCompareCommand({
+        ...parsed,
+        ...(token === undefined ? {} : { token }),
+        ...(root === undefined ? {} : { root }),
+    });
+    result.lines.forEach(out.line);
+    out.exit(result.code);
+}

package/dist/command/cli/verify-against.d.ts

@@ -0,0 +1,61 @@
+import { type CompareDriver } from '../../features/compare/compare-run.js';
+import { type FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type ToolCaller } from './daemon-link/daemon-client.js';
+/** How long to wait after each action before the page is read, so a short timer can fire. */
+export declare const AGAINST_WAIT_MS = 300;
+/** The explorer's action budget on the reference. */
+export declare const AGAINST_MAX_ACTIONS = 150;
+/** The tab one run drives. */
+export interface LeasedTab {
+    url: string;
+    sessionId: string;
+    /** Release the lease when the run ends. */
+    closeLease: boolean;
+    confirmDangerous?: boolean;
+}
+/** One leased tab, as the compare driver. Every call goes through `reticle_run` on that tab. */
+export declare function daemonDriver(caller: ToolCaller, tab: LeasedTab): CompareDriver;
+/** The saved flows a run replays, with `--select` applied, and how many steps each has. */
+export declare function flowsToReplay(fs: FileSystemPort, reticleRoot: string, select: readonly string[] | undefined, now: () => number): Promise<{
+    name: string;
+    steps: number;
+}[]>;
+export interface VerifyAgainstOptions {
+    port: number;
+    candidate: string;
+    reference: string;
+    flows: readonly {
+        name: string;
+        steps: number;
+    }[];
+    token?: string;
+    /** The caller's project `.reticle`, where the leased tabs write their runs. */
+    root?: string;
+    confirmDangerous?: boolean;
+    resultsJson?: string;
+    sleep: (ms: number) => Promise<void>;
+    /** Injected so a test can use its own transport. */
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+    write?: (path: string, text: string) => Promise<void>;
+}
+/** Compare the two builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export declare function runVerifyAgainst(options: VerifyAgainstOptions): Promise<{
+    code: number;
+    lines: string[];
+}>;
+/**
+ * The command. It needs a daemon, as an agent does: `ensureDaemon` attaches to the one on the port,
+ * or starts one. Nothing here stops a daemon, so an agent's MCP link stays up.
+ */
+export declare function handleVerifyAgainst(parsed: {
+    url: string;
+    against: string;
+    port: number;
+    select?: string[];
+    resultsJson?: string;
+    confirmDangerous?: boolean;
+}, ensureDaemon: (port: number) => Promise<void>, out: {
+    line: (text: string) => void;
+    fail: (text: string) => void;
+    exit: (code: number) => void;
+}): Promise<void>;

package/dist/command/cli/verify-against.js

@@ -0,0 +1,187 @@
+/**
+ * `reticle verify <candidate-url> --against <reference-url>`: did a change alter what users see?
+ *
+ * It drives both running builds with the same actions (the saved flows, and the explorer on the
+ * reference) and reports each difference in what a person can read and use. The rules are in
+ * `@/features/compare`. This file connects them to the running daemon: each run is a leased tab,
+ * and each read or action is a tool call on that tab, the same calls an agent makes.
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ReticleDir, ReticleTool, SnapshotMode, isConsequenceDrift, selectFlows, } from '@reticlehq/core';
+import { compareBuilds } from '../../features/compare/compare-run.js';
+import { compareExit, compareJson, compareLines } from '../../features/compare/compare-report.js';
+import { FlowStore } from '../../language/flows/flows.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { callerArtifactRoot } from '../../memory/project/link-directory.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
+import { acquireLease, connectOverSse, endpointFor, payloadOf, refusalText, releaseLease, } from './daemon-link/daemon-client.js';
+/** How long a navigation may take before the start page counts as not loaded. */
+const NAVIGATE_WAIT_MS = 15_000;
+/** One replayed flow step: a step can wait for its own consequence, so give it room. */
+const REPLAY_STEP_CALL_MS = 120_000;
+/** How long to wait after each action before the page is read, so a short timer can fire. */
+export const AGAINST_WAIT_MS = 300;
+/** The explorer's action budget on the reference. */
+export const AGAINST_MAX_ACTIONS = 150;
+/** The label of a replayed step that names no anchor. */
+const UNNAMED_STEP = 'step';
+const MSG_LEASE_FAILED = 'could not open a browser on';
+const MSG_NO_DAEMON = 'could not reach the daemon on port';
+const asText = (value) => 'string' === typeof value ? value : undefined;
+/** A step that ran: it passed, or its action ran and only its declared consequence did not hold. */
+function stepDone(step) {
+    if (step === undefined) {
+        return false;
+    }
+    if (true === step['ok']) {
+        return true;
+    }
+    const drift = step['drift'];
+    const reason = asText(drift?.reasonKind);
+    return reason !== undefined && isConsequenceDrift(reason);
+}
+/** One leased tab, as the compare driver. Every call goes through `reticle_run` on that tab. */
+export function daemonDriver(caller, tab) {
+    let sessionId = tab.sessionId;
+    const run = async (tool, args, timeoutMs) => {
+        const result = await caller.call(ReticleTool.RUN, { tool, args: { ...args, sessionId } }, timeoutMs);
+        return { payload: payloadOf(result), refused: refusalText(result) !== undefined };
+    };
+    const snapshot = async (mode) => (await run(ReticleTool.SNAPSHOT, { mode })).payload;
+    return {
+        async reset() {
+            const { payload, refused } = await run(ReticleTool.NAVIGATE, { url: tab.url, timeout_ms: NAVIGATE_WAIT_MS }, NAVIGATE_WAIT_MS * 2);
+            const next = asText(payload['sessionId']);
+            if (next !== undefined) {
+                sessionId = next;
+            }
+            return !refused && true === payload['ok'] && false !== payload['confirmed'];
+        },
+        async look() {
+            const body = await snapshot(SnapshotMode.INTERACTIVE);
+            const route = asText(body['status']?.route);
+            return { tree: asText(body['tree']) ?? '', ...(route === undefined ? {} : { route }) };
+        },
+        async read() {
+            return asText((await snapshot(SnapshotMode.FULL))['tree']) ?? '';
+        },
+        async act(ref, action, value) {
+            const { payload, refused } = await run(ReticleTool.ACT, {
+                ref,
+                action,
+                args: value === undefined ? {} : { value },
+            });
+            return { ok: !refused && false !== payload['dispatched'], events: [] };
+        },
+        async replayStep(flow, index) {
+            const { payload } = await run(ReticleTool.FLOW_REPLAY, {
+                flowName: flow,
+                to: index + 1,
+                ...(0 === index ? {} : { at: index }),
+                ...(true === tab.confirmDangerous ? { confirmDangerous: true } : {}),
+            }, REPLAY_STEP_CALL_MS);
+            const steps = Array.isArray(payload['steps']) ? payload['steps'] : [];
+            const step = steps.map((s) => s).find((s) => index === s['step']);
+            return { done: stepDone(step), label: asText(step?.['anchor']) ?? UNNAMED_STEP };
+        },
+        async close() {
+            if (tab.closeLease) {
+                await releaseLease(caller, sessionId);
+            }
+        },
+    };
+}
+/** The saved flows a run replays, with `--select` applied, and how many steps each has. */
+export async function flowsToReplay(fs, reticleRoot, select, now) {
+    const store = new FlowStore(fs, reticleRoot, { now });
+    const files = [];
+    for (const name of await store.list()) {
+        const loaded = await store.load(name);
+        if (loaded.ok) {
+            files.push(loaded.value);
+        }
+    }
+    const chosen = selectFlows(files, select === undefined ? {} : { labels: [...select] }).run;
+    return chosen.map((flow) => ({ name: flow.name, steps: flow.steps.length }));
+}
+/** Compare the two builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export async function runVerifyAgainst(options) {
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        caller = await connect(endpointFor(options.port, options.token));
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        return { code: 1, lines: [`${MSG_NO_DAEMON} ${String(options.port)}: ${why}`] };
+    }
+    const open = async (url) => {
+        const lease = await acquireLease(caller, url, false, options.root);
+        if ('failed' in lease) {
+            throw new Error([`${MSG_LEASE_FAILED} ${url}`, ...lease.failed].join('\n'));
+        }
+        return daemonDriver(caller, {
+            url,
+            sessionId: lease.leased,
+            closeLease: true,
+            ...(true === options.confirmDangerous ? { confirmDangerous: true } : {}),
+        });
+    };
+    try {
+        const result = await compareBuilds({
+            reference: options.reference,
+            candidate: options.candidate,
+            open,
+            flows: options.flows,
+            maxActions: AGAINST_MAX_ACTIONS,
+            wait: () => options.sleep(AGAINST_WAIT_MS),
+        });
+        const urls = { reference: options.reference, candidate: options.candidate };
+        if (options.resultsJson !== undefined) {
+            const write = options.write ?? ((path, text) => writeFile(path, text, 'utf8'));
+            await write(options.resultsJson, `${JSON.stringify(compareJson(urls, result), null, 2)}\n`);
+        }
+        return { code: compareExit(result), lines: compareLines(urls, result) };
+    }
+    catch (error) {
+        return { code: 1, lines: [error instanceof Error ? error.message : String(error)] };
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/**
+ * The command. It needs a daemon, as an agent does: `ensureDaemon` attaches to the one on the port,
+ * or starts one. Nothing here stops a daemon, so an agent's MCP link stays up.
+ */
+export async function handleVerifyAgainst(parsed, ensureDaemon, out) {
+    try {
+        await ensureDaemon(parsed.port);
+    }
+    catch (error) {
+        out.fail(error instanceof Error ? error.message : String(error));
+        out.exit(1);
+        return;
+    }
+    const cwd = process.cwd();
+    const root = callerArtifactRoot(cwd);
+    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir());
+    // The same `.reticle` the leased tabs replay from, so the list and the replay agree.
+    const flows = await flowsToReplay(createNodeFileSystem(), root ?? join(cwd, ReticleDir.ROOT), parsed.select, Date.now);
+    const result = await runVerifyAgainst({
+        port: parsed.port,
+        candidate: parsed.url,
+        reference: parsed.against,
+        flows,
+        ...(token === undefined || 0 === token.length ? {} : { token }),
+        ...(root === undefined ? {} : { root }),
+        ...(true === parsed.confirmDangerous ? { confirmDangerous: true } : {}),
+        ...(parsed.resultsJson === undefined ? {} : { resultsJson: parsed.resultsJson }),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    for (const line of result.lines) {
+        out.line(line);
+    }
+    out.exit(result.code);
+}

package/dist/command/cli/verify-no-session.d.ts

@@ -0,0 +1,2 @@
+/** Why no session connected. A short timeout also says that the unit is milliseconds. */
+export declare function noSessionMessage(timeoutMs: number): string;

package/dist/command/cli/verify-no-session.js

@@ -0,0 +1,13 @@
+const MSG_NO_SESSION = 'No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
+    '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
+    ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
+/** A `--timeout` under this is likely a count of seconds, so the message names the unit. */
+const SHORT_TIMEOUT_MS = 1000;
+/** Why no session connected. A short timeout also says that the unit is milliseconds. */
+export function noSessionMessage(timeoutMs) {
+    if (timeoutMs >= SHORT_TIMEOUT_MS) {
+        return MSG_NO_SESSION;
+    }
+    return (`${MSG_NO_SESSION}\n  The wait was ${String(timeoutMs)} ms: the timeout is in milliseconds. ` +
+        'Use --timeout 60000 to wait 60 seconds.');
+}

package/dist/command/cli/verify-results.d.ts

@@ -7,7 +7,31 @@
  */
 import { Verified, type ReticleVerificationRun } from '@reticlehq/core';
 type JourneyVerdict = typeof Verified.YES | typeof Verified.NO | typeof Verified.UNKNOWN;
+/**
+ * How many steps passed, failed, or were never judged. `unknown` is a step the replay never
+ * reached or could not decide; it stays in the total, so an undecided step never raises a score.
+ */
+export interface StepCounts {
+    passed: number;
+    failed: number;
+    unknown: number;
+    /**
+     * Verdicts reached AFTER the journey's first failed step (`--sweep` goes on past it). They are not
+     * in `passed` or `failed`, and they count as `unknown` in the score: a step is paid only when every
+     * step before it passed. Absent when no step ran after a failure.
+     */
+    swept?: {
+        passed: number;
+        failed: number;
+    };
+}
+/**
+ * The shape of the `--results-json` file. 1 had only `verdict` and `results`; 2 adds `steps` per
+ * journey and the gated `score`. A consumer checks this before it reads a field that 1 did not have.
+ */
+export declare const RESULTS_SCHEMA_VERSION = 2;
 export interface VerifyResults {
+    schemaVersion: number;
     verdict: JourneyVerdict;
     /** `runId` is the run the journey came from, set only when that run reached the platform. */
     results: {
@@ -15,8 +39,17 @@ export interface VerifyResults {
         verdict: JourneyVerdict;
         reason?: string;
         runId?: string;
+        steps: StepCounts;
     }[];
+    /** All journeys together. `value` is passed / total, absent when there is no step at all. */
+    score: StepCounts & {
+        total: number;
+        value?: number;
+    };
 }
-/** `pushed`: the run reached the platform, so its id resolves there and the results name it. */
-export declare function verifyResults(run: ReticleVerificationRun, pushed?: boolean): VerifyResults;
+/**
+ * `pushed`: the run reached the platform, so its id resolves there and the results name it.
+ * `planned`: each flow file's step count, by journey name (see `stepCounts`).
+ */
+export declare function verifyResults(run: ReticleVerificationRun, pushed?: boolean, planned?: ReadonlyMap<string, number>): VerifyResults;
 export {};