@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/first-use-checks.js

@@ -0,0 +1,127 @@
+/**
+ * Four checks for the first seconds of `init`, `connect`, `setup` and `verify`: the Node.js version,
+ * a browser to drive, `npx.cmd` on the Windows PATH, and the bridge port.
+ *
+ * Each failed check prints one line: the cause and its one fix. A passed check prints nothing. All
+ * are warnings: the command goes on, so a check that is wrong can never block a path that works.
+ * The paths that cannot go on still refuse later, in their own words (the lease preflight, the
+ * init runtime phase).
+ *
+ * `reticle doctor --fix` would repair the two that a program can repair: install the Chromium, and
+ * move init to a free port. That is a separate change.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, win32 } from 'node:path';
+import { ReticleEnv } from '@reticlehq/core';
+import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { probeChromiumWithFallback } from '../../launch-chromium.js';
+import { compareVersions } from '../version/version-skew.js';
+import { SERVER_NODE_RANGE } from '../version/identity/server-version.js';
+import { ChromiumPathProblem, configuredChromiumRefusal, } from './doctor/browser/chromium-hint.js';
+const WARNING_PREFIX = '⚠ ';
+const NODE_DOWNLOAD_URL = 'https://nodejs.org';
+/** Only a plain floor (`>=20.11`) is read. Any other range is not checked. */
+const NODE_FLOOR = /^>=\s*(\d+(?:\.\d+)*)$/;
+const NPX_WINDOWS = 'npx.cmd';
+const PATH_KEY = 'path';
+const WINDOWS_PATH_SEPARATOR = ';';
+const WINDOWS = 'win32';
+/** The line for a Node.js older than the `engines` floor, or undefined. */
+export function nodeTooOldLine(version, range) {
+    const floor = range === undefined ? undefined : NODE_FLOOR.exec(range.trim())?.[1];
+    if (floor === undefined) {
+        return undefined;
+    }
+    const order = compareVersions(version, floor);
+    if (order === undefined || order >= 0) {
+        return undefined;
+    }
+    return (`Reticle needs Node.js ${floor} or later, and this is Node.js ${version}. ` +
+        `Install the current Node.js LTS from ${NODE_DOWNLOAD_URL}, then run the command again.`);
+}
+/** The line for a machine with no browser Reticle can launch, or undefined. */
+export function chromiumMissingLine(probe) {
+    if (probe.exists || probe.fallback !== undefined) {
+        return undefined;
+    }
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING);
+    }
+    // No playwright at all is a broken install, not a blocked download. `reticle doctor` names it.
+    if (probe.executablePath === undefined) {
+        return undefined;
+    }
+    return ('No Chromium, Chrome or Edge is on this machine, so the first browser session downloads ' +
+        'Chromium (about 150 MiB). If your network blocks that download, install Google Chrome, or set ' +
+        `${ReticleEnv.CHROMIUM_PATH} to a Chromium executable.`);
+}
+/** The line for a Windows PATH with no `npx.cmd` on it, or undefined. */
+export function windowsNpxLine(platform, env, nodeDir, exists) {
+    if (WINDOWS !== platform) {
+        return undefined;
+    }
+    // Windows reads environment names without letter case: `Path` and `PATH` are one variable.
+    const key = Object.keys(env).find((name) => PATH_KEY === name.toLowerCase());
+    const path = key === undefined ? '' : (env[key] ?? '');
+    const onPath = path
+        .split(WINDOWS_PATH_SEPARATOR)
+        .map((dir) => dir.trim().replace(/^"|"$/g, ''))
+        .some((dir) => dir.length > 0 && exists(win32.join(dir, NPX_WINDOWS)));
+    if (onPath) {
+        return undefined;
+    }
+    return (`${NPX_WINDOWS} is not on PATH, so your agent cannot start the Reticle MCP server with npx. ` +
+        `Add ${nodeDir} to PATH, then open a new terminal.`);
+}
+/** Run a probe; a probe that fails gives no line. */
+async function quietly(probe) {
+    try {
+        return await probe();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The warning lines, in a fixed order. Empty when every check passes. */
+export async function firstUseWarnings(facts) {
+    const lines = [
+        nodeTooOldLine(facts.nodeVersion, facts.nodeRange),
+        windowsNpxLine(facts.platform, facts.env, facts.nodeDir, facts.exists),
+    ];
+    const probe = await quietly(facts.chromium);
+    lines.push(probe === undefined ? undefined : chromiumMissingLine(probe));
+    const { port, portPresence, describePort } = facts;
+    if (port !== undefined && portPresence !== undefined && describePort !== undefined) {
+        const presence = await quietly(portPresence);
+        lines.push(PortPresence.FOREIGN === presence ? describePort(presence, port) : undefined);
+    }
+    return lines.flatMap((line) => (line === undefined ? [] : [`${WARNING_PREFIX}${line}`]));
+}
+/** This machine's facts. */
+function thisMachine(port) {
+    return {
+        nodeVersion: process.versions.node,
+        nodeRange: SERVER_NODE_RANGE,
+        platform: process.platform,
+        env: process.env,
+        nodeDir: dirname(process.execPath),
+        exists: existsSync,
+        chromium: () => probeChromiumWithFallback(),
+        ...(port === undefined
+            ? {}
+            : {
+                port,
+                portPresence: () => probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }),
+                describePort: describePortState,
+            }),
+    };
+}
+/** Write the warnings for this machine to stderr. `port` adds the bridge port check. */
+export async function writeFirstUseWarnings(port) {
+    for (const line of await firstUseWarnings(thisMachine(port))) {
+        process.stderr.write(`${line}\n`);
+    }
+}

package/dist/command/cli/first-verdict-node.d.ts

@@ -0,0 +1,3 @@
+import { type FirstVerdictPorts } from './first-verdict.js';
+/** Bare `reticle` in an unwired folder. Returns the exit code. `stop` records an onboarding stop. */
+export declare function cmdFirstVerdict(port: number, headed: boolean, stop: FirstVerdictPorts['stop']): Promise<number>;

package/dist/command/cli/first-verdict-node.js

@@ -0,0 +1,189 @@
+/**
+ * The first verdict, wired to this machine: the dev server, the daemon and the Reticle browser.
+ * Every decision is in `first-verdict.ts`; this file only gathers facts and runs effects.
+ */
+import { join } from 'node:path';
+import { EventType, PredicateKind, QueryBy, ReticleTool, SnapshotMode, asRecord, } from '@reticlehq/core';
+import { OnboardingStop } from '@reticlehq/core/telemetry';
+import { RETICLE_VERIFY_DEFAULT_PORT } from '../../index.js';
+import { DEV_SERVER_PORTS } from './ports/resolve/cli-port.js';
+import { WELL_KNOWN_RETICLE_PORTS } from './ports/sibling-ports.js';
+import { probeDevServerStates } from '../../portal/session/dev-server/dev-server-probe.js';
+import { detectDevCommandInProject, } from '../../portal/session/dev-server/dev-command.js';
+import { probePage } from '../setup/node-effects.js';
+import { startDevServerAndWait } from '../setup/start-dev-server.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
+import { acquireLease, connectOverSse, endpointFor, releaseLease, verdictOf, } from './adhoc-verdict.js';
+import { ensureTryDaemon } from './try-command.js';
+import { writeFirstUseWarnings } from './first-use-checks.js';
+import { AppChoice, MSG_NO_APP, chooseApp, linksToOpen, pageFactsOf, runFirstVerdict, } from './first-verdict.js';
+/** How long a dev server this command started gets to serve its first page. */
+const DEV_START_BUDGET_MS = 120_000;
+/** How long a page gets to come back after a navigation, and to go quiet after it. */
+const PAGE_ARRIVAL_MS = 15_000;
+const PAGE_SETTLE_MS = 5_000;
+const CALL_SLACK_MS = 5_000;
+/** The most events read for one page, and the most links read off the start page. */
+const EVENTS_READ = 500;
+const LINKS_READ = 100;
+const HREF = 'href';
+/** The tool-call fields that carry each answer, for `verdictOf`. */
+const NAV_FIELD = 'ok';
+const EVENTS_FIELD = 'events';
+const ELEMENTS_FIELD = 'elements';
+const STATUS_FIELD = 'status';
+/** `reticle_look` answers the find and the page read that the merged surface no longer names alone. */
+const LOOK_FIND = 'find';
+const LOOK_PAGE = 'page';
+/** The bridge, the bench daemon and the verify endpoint. None of them is an app. */
+const RETICLE_PORTS = new Set([
+    ...WELL_KNOWN_RETICLE_PORTS,
+    RETICLE_VERIFY_DEFAULT_PORT,
+]);
+/** Only these events decide the smoke check. */
+const SMOKE_EVENTS = [EventType.NET_REQUEST, EventType.CONSOLE_ERROR, EventType.ERROR_UNCAUGHT];
+/** Start the folder's dev command and wait until it serves a page, or say why it did not. */
+async function startDevServer(command, cwd) {
+    const dir = command.directory === undefined ? cwd : join(cwd, command.directory);
+    process.stdout.write(`Starting your dev server: ${command.command}\n`);
+    const started = await startDevServerAndWait(command.command, dir, DEV_START_BUDGET_MS);
+    return 'failed' in started
+        ? { lines: [started.failed], stop: OnboardingStop.DEV_SERVER_FAILED }
+        : { url: started.url, release: started.stop };
+}
+/** The app in `cwd`, or the one dev server that runs, started when it has to be. */
+async function findApp(cwd) {
+    const devCommand = detectDevCommandInProject(cwd);
+    const pinned = devCommand?.port;
+    const pinnedServing = pinned !== undefined && (await probePage(`http://localhost:${String(pinned)}`)).served;
+    // Only outside an app folder: in one, another server is never the app to check.
+    const running = devCommand === undefined
+        ? (await probeDevServerStates([...DEV_SERVER_PORTS].filter((p) => !RETICLE_PORTS.has(p))))
+            .serving
+        : [];
+    const choice = chooseApp({
+        ...(devCommand === undefined ? {} : { devCommand }),
+        pinnedServing,
+        running,
+    });
+    if (AppChoice.USE === choice.action) {
+        return { url: choice.url };
+    }
+    if (AppChoice.NONE === choice.action) {
+        return choice;
+    }
+    // `chooseApp` starts a server only for a folder with a dev command.
+    return devCommand === undefined
+        ? { lines: MSG_NO_APP, stop: OnboardingStop.NO_WEB_APP }
+        : startDevServer(devCommand, cwd);
+}
+/** One call through `reticle_run`, the route every tool profile has. */
+function run(caller, tool, args, timeoutMs) {
+    return caller.call(ReticleTool.RUN, { tool, args }, timeoutMs);
+}
+/** Wait for the page to go quiet, then read what its document did. */
+async function readPage(caller, sessionId, url, nav) {
+    // A page that never goes quiet is still judged on what it did: the wait only bounds the read.
+    await run(caller, ReticleTool.WAIT_FOR, { predicate: { kind: PredicateKind.SETTLED }, timeout_ms: PAGE_SETTLE_MS, sessionId }, PAGE_SETTLE_MS + CALL_SLACK_MS).catch(() => undefined);
+    const observed = verdictOf(await run(caller, ReticleTool.OBSERVE, {
+        sessionId,
+        since: 0,
+        filters: SMOKE_EVENTS,
+        max_events: EVENTS_READ,
+    }), EVENTS_FIELD);
+    const events = observed?.[EVENTS_FIELD];
+    return pageFactsOf(url, Array.isArray(events) ? events : [], nav);
+}
+/** Go to `url` (or reload), and say whether the page came back and where. */
+async function go(caller, sessionId, url) {
+    const args = url === undefined
+        ? { reload: true, timeout_ms: PAGE_ARRIVAL_MS, sessionId }
+        : { url, timeout_ms: PAGE_ARRIVAL_MS, sessionId };
+    const result = asRecord(verdictOf(await caller.call(ReticleTool.NAVIGATE, args, PAGE_ARRIVAL_MS + CALL_SLACK_MS), NAV_FIELD));
+    const landedOn = result['landedOn'];
+    const next = result['sessionId'];
+    return {
+        arrived: true === result['confirmed'],
+        ...('string' === typeof landedOn ? { landedOn } : {}),
+        sessionId: 'string' === typeof next ? next : sessionId,
+    };
+}
+/** The path of the page on screen, from the page's own status. */
+async function currentPath(caller, sessionId) {
+    const answer = verdictOf(await run(caller, ReticleTool.LOOK, {
+        action: LOOK_PAGE,
+        mode: SnapshotMode.STATUS,
+        sessionId,
+    }).catch(() => undefined), STATUS_FIELD);
+    const route = asRecord(answer?.[STATUS_FIELD])['route'];
+    return 'string' === typeof route ? route : undefined;
+}
+/** The smoke check, through the daemon on `port`, in a Reticle browser with the zero-install reader. */
+async function smokeThroughDaemon(port, url, headed) {
+    const unavailable = await ensureTryDaemon(port);
+    if (unavailable !== undefined) {
+        return { failed: [unavailable] };
+    }
+    const caller = await connectOverSse(endpointFor(port, readOrCreatePairingTokenSync(defaultPairingTokenDir())));
+    try {
+        const opened = await acquireLease(caller, url, headed);
+        if ('failed' in opened) {
+            return opened;
+        }
+        try {
+            // Reload once: the reader then runs from the start of the document, so it sees what the
+            // first load did (a console error during start-up) and not only what came after.
+            const back = await go(caller, opened.leased, undefined);
+            const path = await currentPath(caller, back.sessionId);
+            // The path only: the lease puts its own parameters on the url, and the page is not a link to open.
+            const here = path === undefined ? url : new URL(new URL(path, url).pathname, url).href;
+            const startNav = {
+                arrived: back.arrived,
+                ...(new URL(here).pathname === new URL(url).pathname ? {} : { landedOn: here }),
+            };
+            const start = await readPage(caller, back.sessionId, url, startNav);
+            const found = verdictOf(await run(caller, ReticleTool.LOOK, {
+                action: LOOK_FIND,
+                by: QueryBy.ROLE,
+                value: 'link',
+                attrs: [HREF],
+                limit: LINKS_READ,
+                sessionId: back.sessionId,
+            }), ELEMENTS_FIELD);
+            const elements = Array.isArray(found?.[ELEMENTS_FIELD]) ? found[ELEMENTS_FIELD] : [];
+            const links = elements.flatMap((item) => {
+                const element = asRecord(item);
+                const href = asRecord(element['attrs'])[HREF];
+                const name = element['name'];
+                return 'string' === typeof href
+                    ? [{ name: 'string' === typeof name ? name : '', href }]
+                    : [];
+            });
+            const picked = linksToOpen(here, links);
+            const visited = [];
+            let sessionId = back.sessionId;
+            for (const target of picked.open) {
+                const nav = await go(caller, sessionId, target);
+                sessionId = nav.sessionId;
+                visited.push(await readPage(caller, sessionId, target, nav));
+            }
+            return { start, links: visited, linksFound: picked.found };
+        }
+        finally {
+            await releaseLease(caller, opened.leased);
+        }
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/** Bare `reticle` in an unwired folder. Returns the exit code. `stop` records an onboarding stop. */
+export async function cmdFirstVerdict(port, headed, stop) {
+    await writeFirstUseWarnings();
+    return runFirstVerdict({
+        findApp: () => findApp(process.cwd()),
+        smoke: (url) => smokeThroughDaemon(port, url, headed),
+        out: (line) => process.stdout.write(`${line}\n`),
+        stop,
+    });
+}

package/dist/command/cli/first-verdict.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Bare `reticle` in a folder that Reticle has not wired: the first verdict, with no agent, no
+ * `init` and no model.
+ *
+ * It finds the app (the folder's own dev server, or the one dev server that runs on this computer),
+ * starts the dev server when it does not run, opens the page in a Reticle browser with the
+ * zero-install reader, and runs a smoke check that cannot guess: the page loads, no console error,
+ * no failed request, and each same-origin link opens. Then it prints the verdict and the next step.
+ *
+ * The decisions are here, behind `FirstVerdictPorts`, so each one is a unit test. The browser, the
+ * daemon and the dev server are in `first-verdict-node.ts`.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+import { OnboardingStop } from '@reticlehq/core/telemetry';
+/** Bare `reticle` runs the first verdict only with no arguments, in a folder with no Reticle config. */
+export declare function bareRunsFirstVerdict(argv: readonly string[], wired: boolean): boolean;
+export declare const AppChoice: {
+    /** Check this url. */
+    readonly USE: "use";
+    /** Start the folder's dev command, then check what it serves. */
+    readonly START: "start";
+    /** Nothing to check: say why. */
+    readonly NONE: "none";
+};
+export type AppDecision = {
+    action: typeof AppChoice.USE;
+    url: string;
+} | {
+    action: typeof AppChoice.START;
+} | {
+    action: typeof AppChoice.NONE;
+    lines: string[];
+    stop: OnboardingStop;
+};
+export declare const MSG_NO_APP: string[];
+/**
+ * Which app to check. In an app folder, only that app: a server on another port can be another
+ * app, and a verdict on the wrong app is worse than none. Outside one, the one server that runs.
+ */
+export declare function chooseApp(facts: {
+    /** The folder's dev command, when the folder holds a web app. */
+    devCommand?: {
+        port?: number;
+    };
+    /** The dev command pins a port, and that port serves a page now. */
+    pinnedServing: boolean;
+    /** Dev-server ports that serve a page now, outside Reticle's own. */
+    running: readonly number[];
+}): AppDecision;
+/** What one page did, read from its own document's events. */
+export interface PageFacts {
+    /** The url the check opened. */
+    url: string;
+    /** The page came back with Reticle connected, at the url asked for. */
+    arrived: boolean;
+    /** Where the page went instead, when it went somewhere else. */
+    landedOn?: string;
+    /** The HTTP status of the document, when the browser reported one. */
+    documentStatus?: number;
+    consoleErrors: string[];
+    failedRequests: string[];
+}
+/**
+ * The facts of the page now on screen. Events of an earlier document are left out: the check
+ * reloads each page, and what the old document did is not this page's fault.
+ */
+export declare function pageFactsOf(url: string, events: readonly ReticleEvent[], nav: {
+    arrived: boolean;
+    landedOn?: string;
+}): PageFacts;
+/** The most links one check opens. Each one is a page load. */
+export declare const MAX_LINKS_OPENED = 8;
+/**
+ * The same-origin pages the links on `pageUrl` lead to, once each, without the page itself and
+ * without a link that ends the session. `found` counts them all, so a capped list says so.
+ */
+export declare function linksToOpen(pageUrl: string, links: readonly {
+    name: string;
+    href: string;
+}[], max?: number): {
+    open: string[];
+    found: number;
+};
+/** What the smoke check saw: the start page, and each link it opened. */
+export interface SmokeFacts {
+    start: PageFacts;
+    links: PageFacts[];
+    /** Same-origin links found on the start page. More than `links` when the check opened fewer. */
+    linksFound: number;
+}
+export interface SmokeVerdict {
+    verified: 'yes' | 'no';
+    lines: string[];
+}
+/**
+ * The verdict. "yes" only when the start page loaded with no console error and no failed request,
+ * and every link it opened did the same. A page that sends a visitor to sign in is a verdict too:
+ * the check is "yes" up to there, and it says what it could not reach.
+ */
+export declare function judgeSmoke(facts: SmokeFacts): SmokeVerdict;
+/** The app to check, or why there is none. `release` stops a dev server this run started. */
+export type FoundApp = {
+    url: string;
+    release?: () => void;
+} | {
+    lines: string[];
+    stop: OnboardingStop;
+};
+export interface FirstVerdictPorts {
+    findApp: () => Promise<FoundApp>;
+    /** Open the page with the zero-install reader and collect the facts, or say why it could not. */
+    smoke: (url: string) => Promise<SmokeFacts | {
+        failed: string[];
+    }>;
+    out: (line: string) => void;
+    /** Record one onboarding stop. */
+    stop: (row: {
+        step: string;
+        stop: OnboardingStop;
+    }) => void;
+}
+export declare const MSG_NEXT_STEP: string[];
+/** Find the app, check it, print the verdict. Returns the exit code: 0 only for "verified: yes". */
+export declare function runFirstVerdict(ports: FirstVerdictPorts): Promise<number>;
+/** The `reason` on a stop this command records, so a reader can tell it from an `init` stop. */
+export declare const FIRST_VERDICT_REASON = "first_verdict";