@reticlehq/server 2.11.0 → 2.13.0

package/dist/setup/interrupt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Take the dev server with us when setup is interrupted.
+ *
+ * `setup` starts a dev server the user did not start — detached, in its own process group — and
+ * stops it in a `finally`. A `finally` does not run on SIGINT: the process is terminated. So Ctrl-C
+ * during setup left that server running forever, holding a port nobody could account for, and the
+ * next run's port probe then found a stranger on it.
+ *
+ * It hid behind an earlier bug. `init` used to exit before the dev server was ever started whenever
+ * instrumentation needed a manual step, so the orphan check found nothing and passed for the wrong
+ * reason. Letting the runtime phase run is what exposed this.
+ */
+/** The parts of `process` this needs, so the behaviour is testable without signalling anything. */
+export interface SignalTarget {
+    on(signal: 'SIGINT' | 'SIGTERM', handler: () => void): void;
+    off(signal: 'SIGINT' | 'SIGTERM', handler: () => void): void;
+    exit(code: number): void;
+}
+/**
+ * Run `stop` if this process is interrupted, then leave with the signal's own code.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export declare function stopOnInterrupt(stop: () => void, target: SignalTarget): () => void;

package/dist/setup/interrupt.js

@@ -0,0 +1,40 @@
+/**
+ * Take the dev server with us when setup is interrupted.
+ *
+ * `setup` starts a dev server the user did not start — detached, in its own process group — and
+ * stops it in a `finally`. A `finally` does not run on SIGINT: the process is terminated. So Ctrl-C
+ * during setup left that server running forever, holding a port nobody could account for, and the
+ * next run's port probe then found a stranger on it.
+ *
+ * It hid behind an earlier bug. `init` used to exit before the dev server was ever started whenever
+ * instrumentation needed a manual step, so the orphan check found nothing and passed for the wrong
+ * reason. Letting the runtime phase run is what exposed this.
+ */
+/** 128 + the signal number, which is what a shell reports — so a caller can tell Ctrl-C from a failure. */
+const EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+/**
+ * Run `stop` if this process is interrupted, then leave with the signal's own code.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export function stopOnInterrupt(stop, target) {
+    // Once only. `stop` is not idempotent — it kills a process GROUP — and on a recycled pid a second
+    // kill is somebody else's process.
+    let done = false;
+    const handlers = ['SIGINT', 'SIGTERM'].map((signal) => {
+        const handler = () => {
+            if (!done) {
+                done = true;
+                stop();
+            }
+            target.exit(EXIT_CODE[signal]);
+        };
+        target.on(signal, handler);
+        return { signal, handler };
+    });
+    return () => {
+        for (const { signal, handler } of handlers)
+            target.off(signal, handler);
+    };
+}

package/dist/setup/license-key.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Writing a license key where the CLI will find it, without leaking it.
+ *
+ * The instructions used to ask an agent to do this by hand in three steps: append to `.env`, check
+ * `.gitignore`, confirm. Every one of those is deterministic, and the second is the one that costs
+ * something when skipped — a license key committed to git is a leaked credential, and it stays
+ * leaked after it is deleted.
+ *
+ * The key is never printed, never returned, and never put in a result object. The only thing said
+ * out loud is that a key was written.
+ */
+export interface LicenseIo {
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+    readonly writeFile: (path: string, contents: string) => void;
+}
+export declare const LicenseWrite: {
+    readonly WRITTEN: "written";
+    readonly ALREADY: "already";
+    readonly REPLACED: "replaced";
+};
+export type LicenseWrite = (typeof LicenseWrite)[keyof typeof LicenseWrite];
+export interface LicenseResult {
+    readonly action: LicenseWrite;
+    /** True when `.gitignore` had to be changed so the key cannot be committed. */
+    readonly gitignoreUpdated: boolean;
+    /** Safe to print. Never contains the key. */
+    readonly message: string;
+}
+/** Whether `.gitignore` already covers `.env`, allowing for the forms people actually write. */
+export declare function gitignoreCoversEnv(contents: string): boolean;
+/**
+ * Put the key in `.env`, and make sure `.env` cannot be committed.
+ *
+ * An existing assignment is REPLACED rather than appended to: two `RETICLE_LICENSE_KEY` lines is a
+ * file where the answer depends on which one the parser reads last, and nobody should have to know
+ * which that is.
+ */
+export declare function writeLicenseKey(dir: string, key: string, io: LicenseIo): LicenseResult;

package/dist/setup/license-key.js

@@ -0,0 +1,72 @@
+/**
+ * Writing a license key where the CLI will find it, without leaking it.
+ *
+ * The instructions used to ask an agent to do this by hand in three steps: append to `.env`, check
+ * `.gitignore`, confirm. Every one of those is deterministic, and the second is the one that costs
+ * something when skipped — a license key committed to git is a leaked credential, and it stays
+ * leaked after it is deleted.
+ *
+ * The key is never printed, never returned, and never put in a result object. The only thing said
+ * out loud is that a key was written.
+ */
+const ENV_FILE = '.env';
+const GITIGNORE = '.gitignore';
+const ENV_VAR = 'RETICLE_LICENSE_KEY';
+export const LicenseWrite = {
+    WRITTEN: 'written',
+    ALREADY: 'already',
+    REPLACED: 'replaced',
+};
+const joinPath = (dir, file) => `${dir.replace(/\/$/, '')}/${file}`;
+/** Whether `.gitignore` already covers `.env`, allowing for the forms people actually write. */
+export function gitignoreCoversEnv(contents) {
+    return contents
+        .split('\n')
+        .map((l) => l.trim())
+        .some((l) => ENV_FILE === l || '.env*' === l || '*.env' === l || '/.env' === l);
+}
+/**
+ * Put the key in `.env`, and make sure `.env` cannot be committed.
+ *
+ * An existing assignment is REPLACED rather than appended to: two `RETICLE_LICENSE_KEY` lines is a
+ * file where the answer depends on which one the parser reads last, and nobody should have to know
+ * which that is.
+ */
+export function writeLicenseKey(dir, key, io) {
+    const envPath = joinPath(dir, ENV_FILE);
+    const existing = io.exists(envPath) ? io.readFile(envPath) : '';
+    const lines = '' === existing ? [] : existing.split('\n');
+    const at = lines.findIndex((l) => l.trimStart().startsWith(`${ENV_VAR}=`));
+    const already = -1 !== at && lines[at]?.trim() === `${ENV_VAR}=${key}`;
+    let action = LicenseWrite.WRITTEN;
+    if (already)
+        action = LicenseWrite.ALREADY;
+    else if (-1 !== at) {
+        lines[at] = `${ENV_VAR}=${key}`;
+        action = LicenseWrite.REPLACED;
+    }
+    else {
+        if (0 < lines.length && '' !== lines[lines.length - 1])
+            lines.push('');
+        lines.push(`${ENV_VAR}=${key}`, '');
+    }
+    if (LicenseWrite.ALREADY !== action)
+        io.writeFile(envPath, lines.join('\n'));
+    // The order matters: a key in git is leaked whether or not the file is later removed.
+    const ignorePath = joinPath(dir, GITIGNORE);
+    const ignore = io.exists(ignorePath) ? io.readFile(ignorePath) : '';
+    let gitignoreUpdated = false;
+    if (!gitignoreCoversEnv(ignore)) {
+        const next = '' === ignore ? `${ENV_FILE}\n` : `${ignore.replace(/\n*$/, '\n')}${ENV_FILE}\n`;
+        io.writeFile(ignorePath, next);
+        gitignoreUpdated = true;
+    }
+    const wrote = LicenseWrite.ALREADY === action
+        ? `license key already in ${ENV_FILE}`
+        : `license key written to ${ENV_FILE}`;
+    return {
+        action,
+        gitignoreUpdated,
+        message: gitignoreUpdated ? `${wrote}, and ${ENV_FILE} added to ${GITIGNORE}` : wrote,
+    };
+}

package/dist/setup/listeners.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which ports a process tree is listening on, parsed from the tools that can answer that.
+ *
+ * Kept separate from the commands that produce the text so the Windows behaviour is testable from
+ * any machine. That is not a stylistic preference: port discovery on Windows returned nothing at
+ * all until this was extracted, so a dev server that prints no parseable URL was undiscoverable
+ * there — and `react-scripts` prints no parseable URL outside a tty, which makes it the majority
+ * platform's most common React setup.
+ */
+/** One LISTENING socket and the process that owns it. */
+export interface Listener {
+    readonly port: number;
+    readonly pid: number;
+}
+/** `lsof -a -p <pids> -iTCP -sTCP:LISTEN -P -n`, NAME column only. */
+export declare function parseLsofPorts(out: string): number[];
+/**
+ * `netstat -ano` on Windows.
+ *
+ * The port is whatever follows the LAST colon: `[::]:3000` has three of them, so splitting on ':'
+ * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
+ */
+export declare function parseNetstatListeners(out: string): Listener[];
+/** One (pid, parent) pair, as `wmic process get ParentProcessId,ProcessId` prints them. */
+export interface ProcessPair {
+    readonly pid: number;
+    readonly ppid: number;
+}
+export declare function parseWmicProcesses(out: string): ProcessPair[];
+/**
+ * `root` and everything descended from it.
+ *
+ * The dev server is almost never the process we spawned: `npm run dev` starts a shell, which starts
+ * node, which binds the port. Matching only the pid we hold finds nothing, and nothing is
+ * indistinguishable from "no server".
+ */
+export declare function descendants(pairs: readonly ProcessPair[], root: number): number[];

package/dist/setup/listeners.js

@@ -0,0 +1,85 @@
+/**
+ * Which ports a process tree is listening on, parsed from the tools that can answer that.
+ *
+ * Kept separate from the commands that produce the text so the Windows behaviour is testable from
+ * any machine. That is not a stylistic preference: port discovery on Windows returned nothing at
+ * all until this was extracted, so a dev server that prints no parseable URL was undiscoverable
+ * there — and `react-scripts` prints no parseable URL outside a tty, which makes it the majority
+ * platform's most common React setup.
+ */
+/** `lsof -a -p <pids> -iTCP -sTCP:LISTEN -P -n`, NAME column only. */
+export function parseLsofPorts(out) {
+    const ports = new Set();
+    for (const m of String(out).matchAll(/:(\d+)\s*$/gm))
+        ports.add(Number(m[1]));
+    return [...ports];
+}
+const NETSTAT_PROTO = 'TCP';
+const NETSTAT_STATE = 'LISTENING';
+const NETSTAT_MIN_COLUMNS = 5;
+/**
+ * `netstat -ano` on Windows.
+ *
+ * The port is whatever follows the LAST colon: `[::]:3000` has three of them, so splitting on ':'
+ * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
+ */
+export function parseNetstatListeners(out) {
+    const rows = [];
+    for (const line of String(out).split(/\r?\n/)) {
+        const f = line.trim().split(/\s+/);
+        if (f.length < NETSTAT_MIN_COLUMNS)
+            continue;
+        if (f[0]?.toUpperCase() !== NETSTAT_PROTO || f[3]?.toUpperCase() !== NETSTAT_STATE)
+            continue;
+        const local = f[1] ?? '';
+        const port = Number(local.slice(local.lastIndexOf(':') + 1));
+        const pid = Number(f[4]);
+        if (Number.isInteger(port) && port > 0 && Number.isInteger(pid))
+            rows.push({ port, pid });
+    }
+    return rows;
+}
+export function parseWmicProcesses(out) {
+    const pairs = [];
+    for (const line of String(out).split(/\r?\n/)) {
+        const f = line.trim().split(/\s+/);
+        if (f.length !== 2)
+            continue;
+        const ppid = Number(f[0]);
+        const pid = Number(f[1]);
+        if (Number.isInteger(pid) && Number.isInteger(ppid))
+            pairs.push({ pid, ppid });
+    }
+    return pairs;
+}
+/**
+ * `root` and everything descended from it.
+ *
+ * The dev server is almost never the process we spawned: `npm run dev` starts a shell, which starts
+ * node, which binds the port. Matching only the pid we hold finds nothing, and nothing is
+ * indistinguishable from "no server".
+ */
+export function descendants(pairs, root) {
+    const byParent = new Map();
+    for (const { pid, ppid } of pairs) {
+        const kids = byParent.get(ppid);
+        if (kids === undefined)
+            byParent.set(ppid, [pid]);
+        else
+            kids.push(pid);
+    }
+    const found = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (next === undefined)
+            continue;
+        for (const child of byParent.get(next) ?? []) {
+            if (found.has(child))
+                continue;
+            found.add(child);
+            queue.push(child);
+        }
+    }
+    return [...found];
+}

package/dist/setup/node-effects.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The real world, bound to the injected shape `runSetupPhases` expects.
+ *
+ * Everything here is a thin binding to something that already exists — `openInBrowser`,
+ * `fetchStatus`, the driver table — with one exception: the dev server. Nothing else in the package
+ * owns a spawned process, and owning one properly is most of this file.
+ *
+ * The promise this makes about that process: setup leaves it running on success, because an
+ * instrumented app the user can watch IS the deliverable, and stops it on every other ending. A
+ * server nobody started, holding a port nobody can account for, surviving the terminal that spawned
+ * it, is the failure this file exists to avoid — measured, an interrupted run used to leave one
+ * listening indefinitely.
+ */
+import type { CandidateSession } from './session-pick.js';
+import type { PageProbe } from './page-probe.js';
+/** The dev server this process started, and the only one it will ever stop. */
+export declare class OwnedDevServer {
+    private child;
+    private buffer;
+    private lastOutputAt;
+    private handedOver;
+    start(command: string, cwd: string, env: Readonly<Record<string, string>>): void;
+    /** The process group leader, for a caller that has to clean up what it handed over. */
+    pid(): number | undefined;
+    output(): string;
+    exited(): boolean;
+    quietForMs(): number;
+    /** Ports anything in this server's process tree is listening on. */
+    listeningPorts(): number[];
+    /** Hand the running server to the user. After this, `stop()` does nothing. */
+    /**
+     * Leave the server running and stop holding it.
+     *
+     * `unref` on the child is NOT enough: its stdout and stderr are pipes owned by this process, and
+     * an open pipe keeps the event loop alive on its own. So `init` printed "setup complete" and then
+     * hung until something killed it, turning a successful run into a non-zero exit — which is
+     * exactly what the install gate reported, on a run whose every other assertion passed.
+     *
+     * The streams are unref'd rather than destroyed: the server is still writing to them, and
+     * destroying the read end of a live pipe risks an EPIPE in somebody else's dev server.
+     */
+    handOver(): void;
+    stop(): void;
+}
+/**
+ * Fetch the page and say what came back.
+ *
+ * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
+ * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
+ * server that is already running.
+ */
+export declare function probePage(url: string): Promise<PageProbe>;
+/** Sessions the daemon is holding, in the shape the picker reads. */
+export declare function listSessions(port: number): Promise<CandidateSession[]>;
+/** Whether this project has a saved flow, wherever the project keeps one. */
+export declare function flowsSaved(roots: readonly string[]): boolean;
+/** On PATH at all. The separate question of whether it RUNS is asked by chooseDriver. */
+export declare function binaryExists(bin: string): boolean;
+/** Whether a directory looks like a project setup has already wired. */
+export declare function alreadyWired(dir: string): boolean;

package/dist/setup/node-effects.js

@@ -0,0 +1,210 @@
+/**
+ * The real world, bound to the injected shape `runSetupPhases` expects.
+ *
+ * Everything here is a thin binding to something that already exists — `openInBrowser`,
+ * `fetchStatus`, the driver table — with one exception: the dev server. Nothing else in the package
+ * owns a spawned process, and owning one properly is most of this file.
+ *
+ * The promise this makes about that process: setup leaves it running on success, because an
+ * instrumented app the user can watch IS the deliverable, and stops it on every other ending. A
+ * server nobody started, holding a port nobody can account for, surviving the terminal that spawned
+ * it, is the failure this file exists to avoid — measured, an interrupted run used to leave one
+ * listening indefinitely.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { Socket } from 'node:net';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fetchStatus } from '../cli/cli-launch.js';
+import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './listeners.js';
+const WINDOWS = 'win32' === process.platform;
+/** A page fetch that is slow is a page fetch that failed, for our purposes. */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Stop an inherited stdio pipe from holding the event loop open.
+ *
+ * A child's piped stdout is a Socket at runtime and a Readable in the types, which has no `unref`.
+ * Narrowing through Socket keeps that honest rather than asserting it.
+ */
+function releasePipe(stream) {
+    if (stream instanceof Socket)
+        stream.unref();
+}
+/** The dev server this process started, and the only one it will ever stop. */
+export class OwnedDevServer {
+    child;
+    buffer = '';
+    lastOutputAt = Date.now();
+    handedOver = false;
+    start(command, cwd, env) {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            // Its own process group, so stopping it stops what it started rather than only the wrapper.
+            detached: !WINDOWS,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...env },
+        });
+        const collect = (chunk) => {
+            this.buffer += String(chunk);
+            this.lastOutputAt = Date.now();
+        };
+        child.stdout?.on('data', collect);
+        child.stderr?.on('data', collect);
+        this.child = child;
+    }
+    /** The process group leader, for a caller that has to clean up what it handed over. */
+    pid() {
+        return this.child?.pid;
+    }
+    output() {
+        return this.buffer;
+    }
+    exited() {
+        return undefined !== this.child && null !== this.child.exitCode;
+    }
+    quietForMs() {
+        return Date.now() - this.lastOutputAt;
+    }
+    /** Ports anything in this server's process tree is listening on. */
+    listeningPorts() {
+        const pid = this.child?.pid;
+        if (undefined === pid)
+            return [];
+        if (WINDOWS) {
+            const tree = new Set(descendants(windowsProcessPairs(), pid));
+            return [
+                ...new Set(parseNetstatListeners(run('netstat', ['-ano']))
+                    .filter((r) => tree.has(r.pid))
+                    .map((r) => r.port)),
+            ];
+        }
+        const pids = run('sh', ['-c', `ps -o pid= -g ${pid} 2>/dev/null | tr -d ' '`])
+            .split('\n')
+            .filter(Boolean);
+        if (0 === pids.length)
+            return [];
+        return parseLsofPorts(run('sh', [
+            '-c',
+            `lsof -a -p ${pids.join(',')} -iTCP -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR>1{print $9}'`,
+        ]));
+    }
+    /** Hand the running server to the user. After this, `stop()` does nothing. */
+    /**
+     * Leave the server running and stop holding it.
+     *
+     * `unref` on the child is NOT enough: its stdout and stderr are pipes owned by this process, and
+     * an open pipe keeps the event loop alive on its own. So `init` printed "setup complete" and then
+     * hung until something killed it, turning a successful run into a non-zero exit — which is
+     * exactly what the install gate reported, on a run whose every other assertion passed.
+     *
+     * The streams are unref'd rather than destroyed: the server is still writing to them, and
+     * destroying the read end of a live pipe risks an EPIPE in somebody else's dev server.
+     */
+    handOver() {
+        this.handedOver = true;
+        const child = this.child;
+        releasePipe(child?.stdout);
+        releasePipe(child?.stderr);
+        child?.unref();
+    }
+    stop() {
+        const child = this.child;
+        if (this.handedOver || undefined === child?.pid)
+            return;
+        if (WINDOWS)
+            run('taskkill', ['/PID', String(child.pid), '/T', '/F']);
+        else {
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                try {
+                    child.kill();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+        this.child = undefined;
+    }
+}
+function run(file, args) {
+    const r = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+    return r.stdout ?? '';
+}
+/**
+ * Every (pid, ppid) pair on a Windows machine — from `wmic` if it is there, PowerShell if not.
+ *
+ * `wmic` was the only source, and Microsoft has been removing it: deprecated since 21H1 and absent
+ * from current Windows images. When it is missing `run` returns '' — the honest answer for a tool
+ * that does not exist, and a catastrophic one here, because an empty process list means an empty
+ * process TREE, which means no observed ports, which means the dev server's url is never found.
+ * `init` then waits out the full quiet window and reports "the dev server stopped producing output
+ * without ever serving a page" about a Vite server that was serving perfectly the whole time.
+ *
+ * The fallback prints the same two-integers-per-line shape, so `parseWmicProcesses` reads either
+ * without knowing which produced it. Tried in this order because `wmic` is an order of magnitude
+ * faster to start than PowerShell, and on a machine that still has it nothing needs to change.
+ */
+const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ParentProcessId) $($_.ProcessId)" }';
+function windowsProcessPairs() {
+    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'ParentProcessId,ProcessId']));
+    if (0 < fromWmic.length)
+        return fromWmic;
+    return parseWmicProcesses(run('powershell', ['-NoProfile', '-NonInteractive', '-Command', POWERSHELL_PAIRS]));
+}
+/**
+ * Fetch the page and say what came back.
+ *
+ * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
+ * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
+ * server that is already running.
+ */
+export async function probePage(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        const body = await res.text();
+        return { served: true, sdkInPage: /@reticlehq|@reticle-connect|reticle-dev/.test(body) };
+    }
+    catch (err) {
+        const message = String(err?.cause?.message ??
+            err?.message ??
+            '');
+        const tlsRefused = /certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message);
+        return { served: false, sdkInPage: false, tlsRefused };
+    }
+}
+/** Sessions the daemon is holding, in the shape the picker reads. */
+export async function listSessions(port) {
+    try {
+        const payload = await fetchStatus(port);
+        const sessions = payload.sessions;
+        return Array.isArray(sessions) ? sessions : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether this project has a saved flow, wherever the project keeps one. */
+export function flowsSaved(roots) {
+    for (const root of roots) {
+        try {
+            if (0 < readdirSync(join(root, '.reticle', 'flows')).length)
+                return true;
+        }
+        catch {
+            /* no flows kept there */
+        }
+    }
+    return false;
+}
+/** On PATH at all. The separate question of whether it RUNS is asked by chooseDriver. */
+export function binaryExists(bin) {
+    return 0 === spawnSync(WINDOWS ? 'where' : 'which', [bin], { stdio: 'ignore' }).status;
+}
+/** Whether a directory looks like a project setup has already wired. */
+export function alreadyWired(dir) {
+    return existsSync(join(dir, '.reticle.json'));
+}

package/dist/setup/page-probe.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The one thing the daemon cannot know: what the page actually contains.
+ *
+ * `diagnoseNoSession` in session/no-session-diagnosis.ts already tells the four daemon-side cases
+ * apart — a session that came and went, something listening that never dialled, a wired project on
+ * the wrong port, nothing listening at all — and its sentence is the one to lead with. None of that
+ * requires fetching anything, which is also its limit: the daemon never sees the HTML.
+ *
+ * So this adds only the page-side fact and nothing else. Whether the SDK is IN what the server
+ * returned splits the most common failure of all — a dev server still serving the bundle it built
+ * before the build config was edited — from a connect that ran and returned early.
+ */
+/** What a single fetch of the app's url established. */
+export interface PageProbe {
+    /** The server answered at all. */
+    readonly served: boolean;
+    /** The SDK appears in what it answered with. */
+    readonly sdkInPage: boolean;
+    /**
+     * The server ANSWERED and its certificate was refused. A self-signed dev cert is an ordinary
+     * local setup, so treating this as "nothing is listening" tells someone to start a server that is
+     * already running.
+     */
+    readonly tlsRefused?: boolean | undefined;
+}
+export declare const PageFinding: {
+    readonly NOT_SERVED: "not-served";
+    readonly TLS_REFUSED: "tls-refused";
+    readonly SDK_MISSING: "sdk-missing";
+    readonly SDK_PRESENT: "sdk-present";
+};
+export type PageFinding = (typeof PageFinding)[keyof typeof PageFinding];
+/** Pure, so the mapping is testable without a server or a browser. */
+export declare function readPage(probe: PageProbe): PageFinding;
+/**
+ * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
+ * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ */
+export declare function describePage(finding: PageFinding, url: string): string;

package/dist/setup/page-probe.js

@@ -0,0 +1,49 @@
+/**
+ * The one thing the daemon cannot know: what the page actually contains.
+ *
+ * `diagnoseNoSession` in session/no-session-diagnosis.ts already tells the four daemon-side cases
+ * apart — a session that came and went, something listening that never dialled, a wired project on
+ * the wrong port, nothing listening at all — and its sentence is the one to lead with. None of that
+ * requires fetching anything, which is also its limit: the daemon never sees the HTML.
+ *
+ * So this adds only the page-side fact and nothing else. Whether the SDK is IN what the server
+ * returned splits the most common failure of all — a dev server still serving the bundle it built
+ * before the build config was edited — from a connect that ran and returned early.
+ */
+export const PageFinding = {
+    NOT_SERVED: 'not-served',
+    TLS_REFUSED: 'tls-refused',
+    SDK_MISSING: 'sdk-missing',
+    SDK_PRESENT: 'sdk-present',
+};
+/** Pure, so the mapping is testable without a server or a browser. */
+export function readPage(probe) {
+    if (true === probe.tlsRefused)
+        return PageFinding.TLS_REFUSED;
+    if (!probe.served)
+        return PageFinding.NOT_SERVED;
+    return probe.sdkInPage ? PageFinding.SDK_PRESENT : PageFinding.SDK_MISSING;
+}
+/**
+ * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
+ * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ */
+export function describePage(finding, url) {
+    switch (finding) {
+        case PageFinding.NOT_SERVED:
+            // Leads with the cause. The break-matrix asserts this phrasing because it is what a reader
+            // greps for after a timeout, and "nothing answered" reads as an observation about the check
+            // rather than a statement about the machine.
+            return `nothing is serving ${url} — the dev server is not up, so the SDK was never given the chance to load.`;
+        case PageFinding.TLS_REFUSED:
+            return (`${url} answered over HTTPS with a certificate this process will not accept, so setup could ` +
+                'not read the page. The app itself may be perfectly fine; re-run with ' +
+                'NODE_TLS_REJECT_UNAUTHORIZED=0 if you trust this dev certificate, or use the http origin.');
+        case PageFinding.SDK_MISSING:
+            return (`${url} is served, and the SDK is NOT in the page. That is almost always a dev server still ` +
+                'serving the bundle it built before the build config was edited: restart it and hard-reload.');
+        case PageFinding.SDK_PRESENT:
+            return (`The SDK IS in the page at ${url} and never dialled the bridge, so it loaded and returned ` +
+                'early: a localhost guard, a production-only check, or a bridge port that differs on the two sides.');
+    }
+}