@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,63 +0,0 @@
-/**
- * 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.
- *
- * On loopback, the announced host is tried first and the other loopback families follow when it
- * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
- */
-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

@@ -1,225 +0,0 @@
-/**
- * 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';
-import { loopbackProbeUrls } from './loopback-probe-urls.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.
- *
- * On loopback, the announced host is tried first and the other loopback families follow when it
- * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
- */
-export async function probePage(url) {
-    const candidates = loopbackProbeUrls(url);
-    let sawTlsRefused = false;
-    for (const candidate of candidates) {
-        try {
-            const res = await fetch(candidate, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-            const body = await res.text();
-            const sdkInPage = /@reticlehq|@reticle-connect|reticle-dev/.test(body);
-            // Only stamp reachedUrl when we had to leave the announcement — callers that already have
-            // the working URL should not rewrite it for a no-op.
-            return candidate === url
-                ? { served: true, sdkInPage }
-                : { served: true, sdkInPage, reachedUrl: candidate };
-        }
-        catch (err) {
-            const message = String(err?.cause?.message ??
-                err?.message ??
-                '');
-            if (/certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message)) {
-                sawTlsRefused = true;
-            }
-        }
-    }
-    return { served: false, sdkInPage: false, ...(sawTlsRefused ? { tlsRefused: true } : {}) };
-}
-/** 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

@@ -1,44 +0,0 @@
-/**
- * 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;
-    /**
-     * The URL that actually answered, when the announced host missed and a loopback sibling did not.
-     * Callers that open a browser or wait on a session should prefer this over the announcement (#884).
-     */
-    readonly reachedUrl?: string | 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

@@ -1,49 +0,0 @@
-/**
- * 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.');
-    }
-}

package/dist/setup/remaining-steps.js

@@ -1,31 +0,0 @@
-/**
- * What is left to do by hand, from wherever setup stopped.
- *
- * Naming a cause is not the same as being recoverable. Setup can misbehave, and when it does the
- * caller should not have to re-read the whole procedure and work out for itself which parts already
- * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
- */
-const DOCS_INDEX = 'https://docs.reticle.sh/llms.txt';
-export function remainingSteps(p) {
-    const steps = [];
-    if (!p.initDone) {
-        steps.push('Run `npx @reticlehq/server@latest init` here, and fix every ⚠ it reports.');
-    }
-    if (!p.devServerUp && !p.urlSuppliedByCaller) {
-        steps.push(`Start the dev server yourself: ${p.devCommand ?? 'the dev script in package.json'}, then open the app in a browser.`);
-    }
-    if (!p.sessionConnected) {
-        steps.push('Confirm a session appears with `reticle_sessions`. If the list is empty, read its ' +
-            '`next_action`: the usual cause is a dev server that was already running when the build ' +
-            'config was edited, so restart it and hard-reload' +
-            (undefined === p.url ? '.' : ` ${p.url}.`));
-    }
-    if (!p.flowSaved) {
-        steps.push('Drive one flow and produce a verdict: `reticle_snapshot({mode:"interactive"})` once, ' +
-            '`reticle_act_sequence` for the setup steps, then ONE `reticle_act_and_wait({ref,action,until})`. ' +
-            'Wrap it in `reticle_record` start/stop and `reticle_flow_save`, and check the grade it ' +
-            'returns is `asserted` — anything else only acts, so it passes even when the feature breaks.');
-    }
-    steps.push(`The whole procedure, if you need it: \`curl ${DOCS_INDEX}\`.`);
-    return steps;
-}

package/dist/setup/run-setup.d.ts

@@ -1,103 +0,0 @@
-/**
- * The half of setup that happens after the files are written.
- *
- * `init` wires a project; this gets the app running with the SDK inside it, proves a session
- * connected, and drives one flow to a verdict. Measured against an agent doing the same steps by
- * hand from SKILL.md across five real applications: 176 model turns, $9.92, forty minutes, and a
- * verdict in two runs out of five — three ended by asking a human to restart their client, having
- * shown them nothing.
- *
- * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
- * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
- * and a real browser to find out what happens when neither works.
- */
-import { type CandidateSession } from './session-pick.js';
-import { type PageProbe } from './page-probe.js';
-import { AppShape } from './desktop-shape.js';
-export declare const SetupPhase: {
-    readonly DEV_SERVER: "dev-server";
-    readonly CONNECT: "connect";
-    readonly DRIVE: "drive";
-    readonly DONE: "done";
-};
-export type SetupPhase = (typeof SetupPhase)[keyof typeof SetupPhase];
-export interface SetupOutcome {
-    /** True only when a flow was driven AND saved. Writing files is not an install. */
-    readonly ok: boolean;
-    readonly reachedPhase: SetupPhase;
-    readonly url?: string | undefined;
-    readonly sessionId?: string | undefined;
-    /** The drive's own report, kept verbatim and never trusted as a pass on its own. */
-    readonly verdict?: string | undefined;
-    readonly flowSaved: boolean;
-    /** What the caller should do next, when this did not finish. */
-    readonly fallback: string[];
-    readonly notes: string[];
-}
-/** Everything the sequence needs from the world, so none of it is reached for directly. */
-export interface SetupEffects {
-    /** Start the dev server. Resolves once started; the caller owns stopping it. */
-    readonly startDevServer: (command: string, cwd: string) => Promise<void>;
-    /**
-     * A live server this project already announced, if any. Setup attaches to it rather than
-     * starting a second one on the next port.
-     */
-    readonly existingAppUrl?: () => Promise<string | undefined>;
-    /** Everything the dev server has printed so far. */
-    readonly devServerOutput: () => string;
-    readonly devServerExited: () => boolean;
-    /** Milliseconds since it last printed anything. */
-    readonly devServerQuietForMs: () => number;
-    /** Ports our own process group is listening on. */
-    readonly observedPorts: () => number[];
-    /** Fetch the url and report what came back. */
-    readonly probePage: (url: string) => Promise<PageProbe>;
-    readonly openBrowser: (url: string) => Promise<void>;
-    readonly listSessions: () => Promise<CandidateSession[]>;
-    /** Drive one flow. Returns the agent's report, or null when nobody could. */
-    readonly drive: (url: string, session: CandidateSession) => Promise<string | null>;
-    /**
-     * Whether this machine has an agent CLI at all.
-     *
-     * Separate from `drive` returning null, because those are different facts and only one of them is
-     * a failure. A drive that RAN and proved nothing is a result worth a non-zero exit. A drive that
-     * could not run is the absence of a tool on the machine, and reporting the install as failed for
-     * it told CI runners — where no agent CLI is ever installed — that a perfectly good install had
-     * not worked.
-     */
-    readonly driverAvailable: () => boolean;
-    readonly flowsSaved: () => boolean;
-    readonly now: () => number;
-    readonly sleep: (ms: number) => Promise<void>;
-    readonly note: (line: string) => void;
-}
-export interface SetupInput {
-    readonly appDir: string;
-    readonly devCommand?: string | undefined;
-    /** The app is already served here, so nothing is started. */
-    readonly suppliedUrl?: string | undefined;
-    /**
-     * The caller's own budget for the connect wait, when they named one.
-     *
-     * Absent, the shape's policy decides — a desktop shell genuinely needs longer than a browser tab.
-     * Present, it WINS, including when it is shorter: the deadline used to be
-     * `max(phaseTimeoutMs, policy)`, so `--timeout 3` could only ever lengthen the wait. A timeout the
-     * tool ignores is a lie, and it left every hostile-environment check killed by its own harness
-     * before setup could say what was wrong.
-     */
-    readonly connectBudgetMs?: number | undefined;
-    readonly openBrowser: boolean;
-    readonly drive: boolean;
-    /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
-    readonly shape: AppShape;
-    readonly phaseTimeoutMs: number;
-    readonly pollMs: number;
-}
-/**
- * Run the phases. Stops at the first one that cannot continue, and always says what is left.
- *
- * A phase that fails is not an error to throw: the caller is usually an agent, and a thrown
- * exception loses the four things it needs — how far this got, the url, the session, and what to do
- * about it.
- */
-export declare function runSetupPhases(input: SetupInput, fx: SetupEffects): Promise<SetupOutcome>;