@reticlehq/server 3.9.0 → 3.10.0

package/dist/command/cli/status/status-lines.js

@@ -14,6 +14,7 @@
  * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
  * logged, so nothing here may throw.
  */
+import { mcpConnectionHint } from '../answers/mcp-connection-hint.js';
 /** Every row label this block can print. The one spelling; nothing writes a label inline. */
 export const StatusLabel = {
     DAEMON: 'daemon',
@@ -24,6 +25,7 @@ export const StatusLabel = {
     NEXT: 'next',
     SPLIT_BRAIN: 'split brain',
     UPDATE: 'update',
+    LICENSE: 'license',
 };
 const LABELS = Object.values(StatusLabel);
 /** The heading, so a reader can tell which command produced the block. */
@@ -80,6 +82,9 @@ export function statusLines(fields) {
     lines.push(row(StatusLabel.DAEMON, running
         ? `${OK} running${at}${pid === undefined ? '' : ` (pid ${String(pid)})`}`
         : `${NOT_OK} not running${at}`));
+    if (running && port !== undefined) {
+        lines.push(continuation(mcpConnectionHint(port)));
+    }
     // What was actually ON the port, when the pid file said nothing useful. "A stranger holds this"
     // and "nothing is here" were the same output once, and the true sentence was said by nothing a
     // person sees — so the word belongs in the prose, not only in the event.
@@ -156,8 +161,25 @@ export function statusLines(fields) {
             lines.push(row(label, value));
         }
     }
+    const license = licenseText(fields['license']);
+    if (license !== undefined) {
+        lines.push(row(StatusLabel.LICENSE, license));
+    }
     return lines;
 }
+/** License states with no key set. `--json` carries them; the block stays silent. */
+const NO_KEY_LICENSE = new Set(['missing', 'eval']);
+/** The license row, only when a key is set: active, expired or rejected. */
+function licenseText(value) {
+    if ('object' !== typeof value || null === value) {
+        return undefined;
+    }
+    const { status, detail } = value;
+    if ('string' !== typeof status || NO_KEY_LICENSE.has(status)) {
+        return undefined;
+    }
+    return 'string' === typeof detail ? `${status}: ${detail}` : status;
+}
 /** The account row: refused at the last sync, not signed in, or signed in. */
 function accountText(refused, who) {
     if (refused !== undefined) {

package/dist/command/cli/status-fields.d.ts

@@ -32,4 +32,8 @@ export declare function splitBrainFields(port: number, projectId: string | undef
  * transport lives on stdout), so `--json` must not go through it.
  */
 export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
-export declare function handleStatus(port: number, json?: boolean): Promise<void>;
+/**
+ * `license` is what `reticle license` printed. The caller reads it, so this directory does not
+ * reach into the license feature.
+ */
+export declare function handleStatus(port: number, json?: boolean, license?: Record<string, unknown>): Promise<void>;

package/dist/command/cli/status-fields.js

@@ -39,7 +39,7 @@ export function withNextAction(facts) {
  */
 export function splitBrainFields(port, projectId) {
     const home = reticleStateHome();
-    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)), { projectId, home });
     const note = elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
     return note === undefined ? {} : { splitBrain: note };
 }
@@ -70,7 +70,11 @@ function agentStatusFields() {
         ? {}
         : { agents: agentStatuses(rows, connectedAgentClients(reticleStateHome())) };
 }
-export async function handleStatus(port, json = false) {
+/**
+ * `license` is what `reticle license` printed. The caller reads it, so this directory does not
+ * reach into the license feature.
+ */
+export async function handleStatus(port, json = false, license) {
     // A broken session file must not cost the reader the rest of the status.
     const account = await accountStatusFields().catch(() => ({}));
     // At a workspace root that is no app of its own, each app and its link: "not linked" named none.
@@ -80,7 +84,7 @@ export async function handleStatus(port, json = false) {
             workspaceApps: await workspaceAppLinks(process.cwd(), localLinkOf).catch(() => []),
         });
     }
-    const report = (fields) => reportStatus({ ...fields, ...account }, json);
+    const report = (fields) => reportStatus({ ...fields, ...account, ...(license === undefined ? {} : { license }) }, json);
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());

package/dist/command/cli/two-builds/compare-command.d.ts

@@ -0,0 +1,48 @@
+import { type OpenedPage } from '../../../features/compare/behaviour-compare.js';
+import { type CompareUrls } from '../../../features/compare/behaviour-report.js';
+import { type StateIo } from '../../../features/compare/outside/state-sources.js';
+import { type ToolCaller } from '../daemon-link/daemon-client.js';
+/** The pairing token the daemon asks for, or undefined when there is none. */
+export declare function pairingToken(): string | undefined;
+/** One leased tab as the compare driver. Every call goes through `reticle_run` on that tab. */
+export declare function leasedPage(caller: ToolCaller, url: string, sessionId: string): OpenedPage;
+export interface CompareCommandOptions extends CompareUrls {
+    json: boolean;
+    port: number;
+    token?: string;
+    /** The caller's project `.reticle`, where the leased tabs write their runs. */
+    root?: string;
+    /** Injected so a test can use its own transport. */
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    fetchText?: (url: string) => Promise<string | undefined>;
+    /** `--report <file>`: also write the comparison as an HTML page there. */
+    report?: string;
+    /** Injected so a test can capture the report; the default writes the file. */
+    writeReport?: (path: string, html: string) => void;
+    /** The path of the declared state sources file (`--state`). */
+    state?: string;
+}
+export declare const MSG_REPORT_WRITTEN = "Report:";
+export declare const MSG_REPORT_FAILED = "Report not written:";
+/** State sources read on this machine: a shell, `docker exec`, `fetch` and the file system. */
+export declare const hostStateIo: StateIo;
+/** Compare the builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export declare function runCompareCommand(options: CompareCommandOptions): 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 handleCompare(parsed: CompareUrls & {
+    json: boolean;
+    port: number;
+    report?: string;
+    state?: string;
+}, ensureDaemon: (port: number) => Promise<void>, out: {
+    line: (text: string) => void;
+    exit: (code: number) => void;
+}): Promise<void>;

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>;