@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/doctor-repairs.js

@@ -0,0 +1,214 @@
+/**
+ * The safe repairs `reticle doctor --fix` can apply, in the order it applies them.
+ *
+ * Each one changes only Reticle's own state, and each reuses the code that already owns that state:
+ * `removePid` for the pid file, `stopWedgedDaemon` for a stuck daemon, the launch path's pinned
+ * install for Chromium, and `reticle setup mcp` for the agent registrations. The facts each one
+ * reads are injected, so the decision is tested without a home directory or a port.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { claudeAvailableProbe, claudeStaleEntryNote, claudeUserEntryIsFloating, codexAvailableProbe, probeCli, } from '@reticlehq/init';
+import { mcpLauncher } from '../setup/mcp-launcher.js';
+import { isAlive, readPid, removePid } from '../daemon/daemon.js';
+import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { identifyPortHolder } from '../daemon/port-state.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { probeChromiumWithFallback, probeLaunchableChromium } from '../../launch-chromium.js';
+import { setupMcp } from '../setup/setup-mcp.js';
+import { handleSetupMcp } from './setup-mcp-cli.js';
+import { stopWedgedDaemon } from './cli-kill.js';
+import { captureLookup } from './ports/port-holder.js';
+import { bundledPlaywrightVersion, chromiumInstallCommand, } from './doctor/browser/chromium-hint.js';
+import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
+import { launcherLine, registeredEntries } from './doctor/doctor-launcher-line.js';
+const SETUP_MCP_COMMAND = 'reticle setup mcp';
+/** A pid file whose process is gone. `removePid` itself never removes the file of a live process. */
+export function stalePidRepair(deps) {
+    const needed = () => {
+        const pid = deps.readPid();
+        return pid !== null && !deps.isAlive(pid);
+    };
+    return {
+        row: DoctorRow.DAEMON,
+        what: 'pid file of a stopped daemon',
+        step: 'delete the pid file of the stopped daemon in ~/.reticle',
+        needed: () => Promise.resolve(needed()),
+        apply: () => {
+            deps.removePid();
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * A Reticle daemon that holds the port and does not answer. Only a holder whose command line is a
+ * Reticle daemon's qualifies; `stopWedgedDaemon` checks that again, after a grace period, before it
+ * sends a signal. A stranger and the agent's own `reticle mcp` proxy are never stopped.
+ */
+export function wedgedDaemonRepair(port, deps) {
+    return {
+        row: DoctorRow.DAEMON,
+        what: 'a Reticle daemon that does not answer',
+        step: `reticle serve --restart --port ${String(port)}`,
+        needed: async () => PortPresence.FOREIGN === (await deps.presence()) && true === deps.holder()?.reticleDaemon,
+        apply: async () => {
+            await deps.stop();
+        },
+    };
+}
+/**
+ * No browser that a launch can use. Only when Playwright's own build is missing or at the wrong
+ * revision and no installed Chrome or Edge stands in. A RETICLE_CHROMIUM_PATH the user set is never
+ * replaced, and an absent playwright package is not a download this can fix.
+ */
+export function chromiumRepair(deps) {
+    return {
+        row: DoctorRow.CHROMIUM,
+        what: "Playwright's own Chromium",
+        step: chromiumInstallCommand(deps.playwrightVersion),
+        needed: async () => {
+            const probe = await deps.probe();
+            return (!probe.exists &&
+                probe.fallback === undefined &&
+                true !== probe.configured &&
+                probe.executablePath !== undefined);
+        },
+        apply: async () => {
+            await deps.install();
+        },
+    };
+}
+/** Agents found on this machine that do not have Reticle's MCP server registered. */
+export function mcpRepair(deps) {
+    return {
+        row: DoctorRow.MCP,
+        what: 'agent registrations',
+        step: SETUP_MCP_COMMAND,
+        needed: () => Promise.resolve(deps.gaps().length > 0),
+        apply: () => {
+            deps.register();
+            return Promise.resolve();
+        },
+    };
+}
+/** How the launcher row starts its command, as `doctor-launcher-line.ts` writes it. */
+const LAUNCHER_RUN = 'Run: ';
+/**
+ * An agent config starts Reticle from an installed copy that no longer exists. `setup mcp`
+ * replaces Reticle's own entry in the JSON clients. It keeps an existing Claude Code entry, so for
+ * Claude Code the row still fails after the repair, and the step is the row's remove-then-add.
+ */
+export function launcherRepair(deps) {
+    let step = SETUP_MCP_COMMAND;
+    return {
+        row: DoctorRow.LAUNCHER,
+        what: 'a registered launcher that does not exist or has no version',
+        // The step is read after `needed`, which reads the row again.
+        get step() {
+            return step;
+        },
+        needed: () => {
+            const line = deps.line();
+            if (line === undefined) {
+                return Promise.resolve(false);
+            }
+            const at = line.indexOf(LAUNCHER_RUN);
+            step = at < 0 ? SETUP_MCP_COMMAND : line.slice(at + LAUNCHER_RUN.length);
+            return Promise.resolve(true);
+        },
+        apply: () => {
+            deps.register();
+            return Promise.resolve();
+        },
+    };
+}
+/** The launcher row for the agent configs of this machine and folder. */
+export function readLauncherLine(cwd) {
+    const io = {
+        exists: existsSync,
+        homeDir: homedir,
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+    return launcherLine(registeredEntries(io, cwd), existsSync, claudeUserEntryIsFloating(io) ? claudeStaleEntryNote(mcpLauncher()) : undefined);
+}
+/** The `mcp` doctor row. */
+export function mcpRegistrationRow(registration) {
+    const { missing, present } = registration;
+    if (missing.length > 0) {
+        const also = 0 === present.length ? '' : ` (registered with ${present.join(', ')})`;
+        return doctorRow(DoctorRow.MCP, `✗ not registered with ${missing.join(', ')}; run \`${SETUP_MCP_COMMAND}\`${also}`);
+    }
+    if (0 === present.length) {
+        return doctorRow(DoctorRow.MCP, `no agent that this check knows was found; \`${SETUP_MCP_COMMAND}\` names the agents it knows`);
+    }
+    return doctorRow(DoctorRow.MCP, `✓ registered with ${present.join(', ')}`);
+}
+/**
+ * Ask `setupMcp` what it would do, and do none of it. Config writes and registration commands are
+ * recorded, not run; only the two `--version` probes run, because they say whether an agent is here.
+ * No telemetry: this is a check, not a registration.
+ */
+export function readMcpRegistration() {
+    const probes = [claudeAvailableProbe(), codexAvailableProbe()];
+    const isProbe = (command, args) => probes.some((p) => p.command === command && p.args.join(' ') === args.join(' '));
+    const result = setupMcp({
+        exists: (p) => existsSync(p),
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: () => { },
+        homeDir: () => homedir(),
+        print: () => { },
+        runCli: (command, args) => (isProbe(command, args) ? probeCli(command, args) : true),
+        reportStep: () => { },
+    });
+    return { missing: result.registered, present: result.alreadyThere };
+}
+/** The repairs for this machine and port, in the order `--fix` applies them. */
+export function machineRepairs(port, reportStep) {
+    return [
+        stalePidRepair({
+            readPid: () => readPid(port),
+            isAlive,
+            removePid: () => {
+                removePid(port);
+            },
+        }),
+        wedgedDaemonRepair(port, {
+            presence: () => probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }),
+            holder: () => identifyPortHolder(port, captureLookup),
+            stop: () => stopWedgedDaemon(port),
+        }),
+        chromiumRepair({
+            probe: () => probeChromiumWithFallback(),
+            install: () => probeLaunchableChromium(),
+            playwrightVersion: bundledPlaywrightVersion(),
+        }),
+        // Before `mcp`: its `setup mcp` also replaces a stale launcher, and this one says so.
+        launcherRepair({
+            line: () => readLauncherLine(process.cwd()),
+            register: () => {
+                handleSetupMcp(reportStep, false);
+            },
+        }),
+        mcpRepair({
+            gaps: () => readMcpRegistration().missing,
+            register: () => {
+                handleSetupMcp(reportStep, false);
+            },
+        }),
+    ];
+}

package/dist/command/cli/drive/drive-command.js

@@ -8,11 +8,10 @@
  */
 import { start } from '../../../index.js';
 import { log } from '../../../log.js';
-import { probePresence, describePresence } from '../../daemon/binding/port-presence.js';
+import { probePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
-import { readPid } from '../../daemon/daemon.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
-import { captureLookup, findPortHolder } from '../ports/port-holder.js';
+import { describePortState } from '../../daemon/port-state.js';
 import { DriveMode, NO_ATTACHED_APP, attachedApp, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
 /** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
 export function handleDrive(parsed, projectId) {
@@ -34,10 +33,7 @@ async function driveWithHonestConflict(parsed, projectId) {
     const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
     const mode = decideDriveMode(presence);
     if (DriveMode.REFUSE === mode) {
-        const reason = driveForeignHolder(describePresence(presence, parsed.port, {
-            ourPid: readPid(parsed.port),
-            holderPid: findPortHolder(parsed.port, captureLookup)?.pid,
-        }));
+        const reason = driveForeignHolder(describePortState(presence, parsed.port));
         log('reticle_drive_port_conflict', { port: parsed.port, presence, reason });
         process.stderr.write(`${reason}\n`);
         process.exit(1);

package/dist/command/cli/ensure-daemon.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `reticle open` and every other flow that needs a daemon on `port`.
+ *
+ * The retry: a FOREIGN reading seconds after `reticle restart` is usually OUR OWN daemon still
+ * answering its first `/status` — the 1 s `/status` window and the 500 ms TCP window do not
+ * survive a cold Windows start, and the refusal then names a holder it could not identify, while
+ * `reticle status` run moments later shows the daemon fine. The pid file names what `restart`
+ * started; while that process is alive the port is probed once more before refusing. A stranger's
+ * pid is never in the file, so the refusal keeps its teeth for the stranger case it was written
+ * for.
+ *
+ * Probes, the pid file and the spawn are injected so the rule is testable without a socket — the
+ * same shape `probePresence`'s own callers use.
+ */
+import { PortPresence } from '../daemon/binding/port-presence.js';
+export interface EnsureDaemonDeps {
+    /** The classified presence probe. Defaults to the shared TCP + `/status` pair. */
+    probe?: (port: number) => Promise<PortPresence>;
+    readPid?: (port: number) => number | null;
+    isAlive?: (pid: number) => boolean;
+    /** How long to wait before the second probe. */
+    retryDelayMs?: number;
+    spawnDaemon?: (port: number) => Promise<void>;
+    onUsable?: (port: number) => Promise<void> | void;
+}
+export declare function ensureDaemon(port: number, deps?: EnsureDaemonDeps): Promise<void>;

package/dist/command/cli/ensure-daemon.js

@@ -0,0 +1,57 @@
+/**
+ * `reticle open` and every other flow that needs a daemon on `port`.
+ *
+ * The retry: a FOREIGN reading seconds after `reticle restart` is usually OUR OWN daemon still
+ * answering its first `/status` — the 1 s `/status` window and the 500 ms TCP window do not
+ * survive a cold Windows start, and the refusal then names a holder it could not identify, while
+ * `reticle status` run moments later shows the daemon fine. The pid file names what `restart`
+ * started; while that process is alive the port is probed once more before refusing. A stranger's
+ * pid is never in the file, so the refusal keeps its teeth for the stranger case it was written
+ * for.
+ *
+ * Probes, the pid file and the spawn are injected so the rule is testable without a socket — the
+ * same shape `probePresence`'s own callers use.
+ */
+import { PortPresence, probePresence, presenceIsUsable, } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
+import { probeDaemon, waitForDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { isAlive, readPid, spawnDaemon } from '../daemon/daemon.js';
+import { warnOnDaemonSkew } from './launch/cli-launch.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG } from './cli-parse.js';
+/** The probe pair every daemon-touching command shares. */
+const REAL_PROBES = {
+    tcpOpen: (port) => probeDaemon(port),
+    status: (port) => fetchStatus(port),
+};
+export async function ensureDaemon(port, deps = {}) {
+    const probe = deps.probe ?? (() => probePresence(port, REAL_PROBES));
+    const readRecordedPid = deps.readPid ?? readPid;
+    const pidIsAlive = deps.isAlive ?? isAlive;
+    const spawn = deps.spawnDaemon ?? spawnRealDaemon;
+    const onUsable = deps.onUsable ?? warnOnDaemonSkew;
+    const retryDelayMs = deps.retryDelayMs ?? 1_500;
+    let presence = await probe(port);
+    if (PortPresence.FOREIGN === presence) {
+        const recorded = readRecordedPid(port);
+        if (recorded !== null && pidIsAlive(recorded)) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+            presence = await probe(port);
+        }
+    }
+    if (presenceIsUsable(presence)) {
+        return void (await onUsable(port));
+    }
+    if (PortPresence.FREE !== presence) {
+        throw new Error(describePortState(presence, port));
+    }
+    await spawn(port);
+}
+async function spawnRealDaemon(port) {
+    const scriptPath = process.argv[1];
+    if (scriptPath === undefined) {
+        throw new Error('cannot locate the reticle daemon script');
+    }
+    spawnDaemon(process.execPath, scriptPath, [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)], port);
+    await waitForDaemon(port);
+}

package/dist/command/cli/finished-run/grade-command.d.ts

@@ -0,0 +1,23 @@
+import { type StateIo } from '../../../features/compare/outside/state-sources.js';
+import { type GradeArgs } from '../cli-parse-grade.js';
+export declare const GradeExit: {
+    readonly PASS: 0;
+    readonly FAIL: 1;
+    readonly UNVERIFIED: 2;
+};
+/** The most difference lines printed as text. `--json` gives every line. */
+export declare const MAX_TEXT_LINES = 10;
+type Ok = Extract<GradeArgs, {
+    kind: 'ok';
+}>;
+export interface GradeOut {
+    line: (text: string) => void;
+    exit: (code: number) => void;
+}
+export interface GradeIo {
+    state: StateIo;
+    readText: (path: string) => Promise<string>;
+    writeText: (path: string, text: string) => void;
+}
+export declare function handleGrade(args: Ok, out: GradeOut, io?: GradeIo): Promise<void>;
+export {};

package/dist/command/cli/finished-run/grade-command.js

@@ -0,0 +1,180 @@
+/**
+ * `reticle grade`: grade a finished run of an app from snapshots of its stored data.
+ *
+ * - `snapshot` reads the declared state sources (and the page the run ended on) into a file.
+ * - `judge` compares a candidate snapshot with two reference snapshots, and checks the final answer
+ *   against a source read at grade time.
+ * - `tables` writes a state declaration with one source for each table of a database.
+ * - `suggest` removes the sources that change between two runs of the same correct steps.
+ *
+ * It needs no daemon and no browser. The rules are in `@/features/grade/`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { MSG_READ_FAILED, readStateSources, sourceRows, StateDeclarationSchema, } from '../../../features/compare/outside/state-sources.js';
+import { checkAnswer, ExpectSchema } from '../../../features/grade/grade-answer.js';
+import { GradeVerdict, gradeState, SnapshotSchema, urlLine, } from '../../../features/grade/grade-state.js';
+import { quietSources, tableSources } from '../../../features/grade/grade-suggest.js';
+import { GradeStep } from '../cli-parse-grade.js';
+import { hostStateIo } from '../two-builds/compare-command.js';
+export const GradeExit = { PASS: 0, FAIL: 1, UNVERIFIED: 2 };
+const EXIT = {
+    [GradeVerdict.PASS]: GradeExit.PASS,
+    [GradeVerdict.FAIL]: GradeExit.FAIL,
+    [GradeVerdict.UNVERIFIED]: GradeExit.UNVERIFIED,
+};
+/** The most difference lines printed as text. `--json` gives every line. */
+export const MAX_TEXT_LINES = 10;
+const UTF8 = 'utf8';
+const COLUMN = '\t';
+const LINE_BREAK = /\r?\n/;
+const SKIP_SEPARATOR = ',';
+const reasonOf = (error) => error instanceof Error ? error.message : String(error);
+function writeFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+}
+const defaultIo = {
+    state: hostStateIo,
+    readText: (path) => readFile(path, UTF8),
+    writeText: writeFile,
+};
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+async function readSnapshot(io, path) {
+    const parsed = SnapshotSchema.safeParse(JSON.parse(await io.readText(path)));
+    if (!parsed.success) {
+        throw new Error(`${path} is not a grade snapshot: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+/** The sources of a state declaration file, or why they could not be read. */
+async function declarationOf(io, path) {
+    try {
+        const parsed = StateDeclarationSchema.safeParse(JSON.parse(await io.readText(path)));
+        return parsed.success ? parsed.data.sources : { error: parsed.error.message };
+    }
+    catch (error) {
+        return { error: reasonOf(error) };
+    }
+}
+/** At most `MAX_TEXT_LINES` lines, then a line that says how many were left out. */
+function capped(sign, lines) {
+    const shown = lines.slice(0, MAX_TEXT_LINES).map((line) => `  ${sign} ${line}`);
+    const rest = lines.length - shown.length;
+    return rest > 0 ? [...shown, `  ... and ${String(rest)} more (--json lists every line)`] : shown;
+}
+async function snapshot(args, io, out) {
+    const sources = await declarationOf(io, args.state ?? '');
+    if ('error' in sources) {
+        out.line(`Could not read the state sources in ${args.state ?? ''}: ${sources.error}`);
+        out.exit(GradeExit.UNVERIFIED);
+        return;
+    }
+    // No row cap: the grade diff is linear, and a cut row would not name its record.
+    const lines = await readStateSources(sources, io.state, Number.POSITIVE_INFINITY);
+    if (args.url !== undefined) {
+        lines.push(urlLine(args.url));
+    }
+    io.writeText(args.out ?? '', json({ lines }));
+    const failed = lines.filter((line) => line.startsWith(MSG_READ_FAILED));
+    out.line(`Snapshot: ${args.out ?? ''}: ${String(lines.length)} lines`);
+    failed.forEach((line) => out.line(`  ${line}`));
+    out.exit(failed.length > 0 ? GradeExit.UNVERIFIED : GradeExit.PASS);
+}
+async function answerOf(args, io) {
+    if (args.expect === undefined) {
+        return {};
+    }
+    const parsed = ExpectSchema.safeParse(JSON.parse(await io.readText(args.expect)));
+    if (!parsed.success) {
+        return { unread: `${args.expect}: ${parsed.error.message}` };
+    }
+    const spec = parsed.data.answer;
+    let rows;
+    try {
+        rows = await sourceRows(spec.source, io.state);
+    }
+    catch (error) {
+        return { unread: `answer source ${spec.source.label}: ${reasonOf(error)}` };
+    }
+    return { check: checkAnswer(rows, args.answer, spec) };
+}
+async function judge(args, io, out) {
+    const [reference, again, candidate] = await Promise.all([args.reference, args.again, args.candidate].map((p) => readSnapshot(io, p ?? '')));
+    if (reference === undefined || again === undefined || candidate === undefined) {
+        throw new Error('a snapshot is missing');
+    }
+    const state = gradeState(reference, again, candidate);
+    const answer = await answerOf(args, io);
+    const unread = [...state.unread, ...(answer.unread === undefined ? [] : [answer.unread])];
+    let verdict = GradeVerdict.PASS;
+    if (unread.length > 0) {
+        verdict = GradeVerdict.UNVERIFIED;
+    }
+    else if (state.verdict === GradeVerdict.FAIL || false === answer.check?.ok) {
+        verdict = GradeVerdict.FAIL;
+    }
+    const result = {
+        verdict,
+        state: { removed: state.removed, added: state.added, ignored: state.ignored },
+        ...(answer.check === undefined ? {} : { answer: answer.check }),
+        unread,
+    };
+    if (args.json) {
+        out.line(JSON.stringify(result));
+    }
+    else {
+        out.line(verdict.toUpperCase());
+        unread.forEach((line) => out.line(`  unread: ${line}`));
+        if (answer.check !== undefined) {
+            out.line(answer.check.ok
+                ? `  answer: correct (${answer.check.expected})`
+                : `  answer: wrong: ${answer.check.reason ?? ''}`);
+        }
+        out.line(`  state: ${String(state.removed.length + state.added.length)} lines differ, ${String(state.ignored)} ignored as noise`);
+        capped('-', state.removed).forEach(out.line);
+        capped('+', state.added).forEach(out.line);
+    }
+    out.exit(EXIT[verdict]);
+}
+async function tables(args, io, out) {
+    const listed = await io.state.run(args.list ?? '', args.container);
+    const names = listed.split(LINE_BREAK).map((line) => line.split(COLUMN)[0] ?? '');
+    const skip = (args.skip ?? '').split(SKIP_SEPARATOR).filter((prefix) => '' !== prefix);
+    const result = tableSources(names, args.rows ?? '', args.container, skip);
+    io.writeText(args.out ?? '', json({ sources: result.sources }));
+    out.line(`Declaration: ${args.out ?? ''}: ${String(result.sources.length)} sources`);
+    result.skipped.forEach((s) => out.line(`  skipped ${s.label}: ${s.reason}`));
+    out.exit(GradeExit.PASS);
+}
+async function suggest(args, io, out) {
+    const sources = await declarationOf(io, args.state ?? '');
+    if ('error' in sources) {
+        out.line(`Could not read the state sources in ${args.state ?? ''}: ${sources.error}`);
+        out.exit(GradeExit.UNVERIFIED);
+        return;
+    }
+    const reference = await readSnapshot(io, args.reference ?? '');
+    const again = await readSnapshot(io, args.again ?? '');
+    const result = quietSources(sources, reference.lines, again.lines);
+    io.writeText(args.out ?? '', json({ sources: result.sources }));
+    out.line(`Declaration: ${args.out ?? ''}: kept ${String(result.sources.length)} of ${String(sources.length)} sources`);
+    result.dropped.forEach((d) => out.line(`  dropped ${d.label}: ${d.reason}`));
+    out.exit(GradeExit.PASS);
+}
+const STEPS = {
+    [GradeStep.SNAPSHOT]: snapshot,
+    [GradeStep.JUDGE]: judge,
+    [GradeStep.TABLES]: tables,
+    [GradeStep.SUGGEST]: suggest,
+};
+export async function handleGrade(args, out, io = defaultIo) {
+    try {
+        await STEPS[args.step](args, io, out);
+    }
+    catch (error) {
+        out.line(`UNVERIFIED\n  ${reasonOf(error)}`);
+        out.exit(GradeExit.UNVERIFIED);
+    }
+}

package/dist/command/cli/first-use-checks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { PortPresence } from '../daemon/binding/port-presence.js';
+import { type ChromiumProbe } from './doctor/browser/chromium-hint.js';
+/** What the checks read, injected so each one runs against a fake machine in tests. */
+export interface FirstUseFacts {
+    /** `process.versions.node`. */
+    nodeVersion: string;
+    /** The `engines.node` range of this package. */
+    nodeRange: string | undefined;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** The folder of the running `node` executable. */
+    nodeDir: string;
+    exists: (path: string) => boolean;
+    chromium: () => Promise<ChromiumProbe>;
+    /** The bridge port to check. No port: no port check. */
+    port?: number;
+    portPresence?: () => Promise<PortPresence>;
+    describePort?: (presence: PortPresence, port: number) => string;
+}
+/** The line for a Node.js older than the `engines` floor, or undefined. */
+export declare function nodeTooOldLine(version: string, range: string | undefined): string | undefined;
+/** The line for a machine with no browser Reticle can launch, or undefined. */
+export declare function chromiumMissingLine(probe: ChromiumProbe): string | undefined;
+/** The line for a Windows PATH with no `npx.cmd` on it, or undefined. */
+export declare function windowsNpxLine(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, nodeDir: string, exists: (path: string) => boolean): string | undefined;
+/** The warning lines, in a fixed order. Empty when every check passes. */
+export declare function firstUseWarnings(facts: FirstUseFacts): Promise<string[]>;
+/** Write the warnings for this machine to stderr. `port` adds the bridge port check. */
+export declare function writeFirstUseWarnings(port?: number): Promise<void>;