@reticlehq/server 3.3.0 → 3.5.0

package/dist/command/setup/bringup/ensure-daemon.js

@@ -8,51 +8,170 @@
  * dial and setup ends with "the SDK is in the page and never dialled the bridge" — the SDK being
  * blamed for the absence of the thing it was dialling.
  *
- * Idempotent by construction: an alive daemon for this project is adopted, and one belonging to
- * somebody else is refused rather than stolen, which is the same rule `reticle mcp` follows.
+ * Idempotent by construction: a daemon that speaks our wire contract is adopted. One that does NOT
+ * is not usable, however healthy its `/status`: an older Reticle turns away every hello from the page
+ * init just instrumented ("bridge refused the connection: invalid message"), and init used to adopt
+ * it anyway, wait out its budget, and blame the page. So a skewed daemon nobody is using is replaced
+ * (stopped by its LISTENER, never `lsof -ti`, which also kills the agent's MCP proxy), and one with
+ * live sessions is left alone with the exact command to run once they are done.
+ *
+ * A stranger on the port that is not a Reticle daemon at all is refused before this runs; see
+ * `bridge-port.ts`.
  */
 import { log } from '../../../log.js';
-import { spawnDaemon } from '../../daemon/daemon.js';
+import { isAlive, readPid, reticleStateHome, spawnDaemon } from '../../daemon/daemon.js';
+import { readDaemonRegistry } from '../../daemon/daemon-resolve.js';
+import { LOOPBACK_HOST, STATUS_HOLD_MS } from '@reticlehq/core';
 import { probePresence, presenceIsUsable } from '../../daemon/binding/port-presence.js';
-import { waitForDaemon, probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { daemonSpawnArgs } from '../../cli/daemon-start-options.js';
-import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { fetchStatus, summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { runKill } from '../../cli/cli-kill.js';
 export const EnsureDaemon = {
     /** Something usable was already there. */
     ADOPTED: 'adopted',
     STARTED: 'started',
+    /** A daemon on another wire contract, serving nobody, was stopped and ours started in its place. */
+    REPLACED: 'replaced',
+    /** A daemon on another wire contract is serving live sessions, so it was left alone. */
+    SKEWED_IN_USE: 'skewed-in-use',
     /** Could not be started, and the caller has to say so rather than blame the page. */
     UNAVAILABLE: 'unavailable',
 };
-export async function ensureDaemon(port, deps) {
-    if (await deps.usable(port))
-        return EnsureDaemon.ADOPTED;
+/** A string field off the /status body, or undefined on a daemon too old to report it. */
+function statusString(payload, key) {
+    if ('object' !== typeof payload || null === payload)
+        return undefined;
+    const value = Reflect.get(payload, key);
+    return 'string' === typeof value && 0 < value.length ? value : undefined;
+}
+async function spawnAndWait(port, deps) {
     if (undefined === deps.scriptPath)
-        return EnsureDaemon.UNAVAILABLE;
-    if (!deps.spawn(port))
-        return EnsureDaemon.UNAVAILABLE;
+        return false;
+    // A lost spawn race is not a failed start: `init` printed "could not start the Reticle daemon"
+    // over a daemon that bound seconds later. Only a spawn that failed with nobody else starting one
+    // is a reason to stop without waiting.
+    if (!deps.spawn(port) && !deps.starting(port))
+        return false;
     try {
         // Readiness means the port ACCEPTS, not that a child was spawned: a readiness signal that
         // precedes readiness is worse than none, because what waits on it stops waiting too early.
         await deps.waitReady(port);
     }
     catch {
-        return EnsureDaemon.UNAVAILABLE;
+        return false;
+    }
+    return deps.usable(port);
+}
+export async function ensureDaemon(port, deps) {
+    if (await deps.usable(port)) {
+        const status = await deps.status(port);
+        if (!deps.skewed(status))
+            return { state: EnsureDaemon.ADOPTED };
+        const theirs = statusString(status, 'version') ?? 'an older build';
+        const { sessionCount } = summarizeStatus(status);
+        if (0 < sessionCount) {
+            return {
+                state: EnsureDaemon.SKEWED_IN_USE,
+                message: `The Reticle daemon on port ${String(port)} is ${theirs}, which speaks a different wire ` +
+                    `contract than this init, so it will refuse your app — and ` +
+                    `${String(sessionCount)} session(s) are still using it, so init will not stop it. When ` +
+                    `they are done, run \`npx @reticlehq/server kill --port ${String(port)}\` and re-run init.`,
+            };
+        }
+        if (!(await deps.replace(port)))
+            return { state: EnsureDaemon.UNAVAILABLE };
+        return (await spawnAndWait(port, deps))
+            ? {
+                state: EnsureDaemon.REPLACED,
+                message: `replaced the idle Reticle daemon on port ${String(port)} (${theirs}), which speaks a ` +
+                    `different wire contract and would have refused your app, with a current one.`,
+            }
+            : { state: EnsureDaemon.UNAVAILABLE };
+    }
+    return (await spawnAndWait(port, deps))
+        ? { state: EnsureDaemon.STARTED }
+        : { state: EnsureDaemon.UNAVAILABLE };
+}
+/**
+ * Stop this project's daemons on any port but `port`, the one init is about to use. Returns the
+ * ports stopped.
+ *
+ * `init --port <new>` started a daemon on the new port and left the old one serving: the build
+ * plugin found both, dialled the old one, and init — waiting on the new one — exited 1 with
+ * "connected to a DIFFERENT Reticle daemon". A daemon another project's tab is still on is left
+ * alone, because stopping it would take that app down to fix this one. Stopped by its listener
+ * (`runKill` without force), never `lsof -ti`, which also kills the agent's MCP proxy.
+ */
+export async function retireMovedDaemons(projectId, port, deps) {
+    if (undefined === projectId || 0 === projectId.length)
+        return [];
+    const stopped = [];
+    for (const entry of deps.registered()) {
+        if (entry.projectId !== projectId || entry.port === port)
+            continue;
+        const { sessions } = summarizeStatus(await deps.status(entry.port));
+        const shared = sessions.some((s) => undefined !== s.projectId && projectId !== s.projectId);
+        if (shared)
+            continue;
+        if (await deps.stop(entry.port))
+            stopped.push(entry.port);
     }
-    return (await deps.usable(port)) ? EnsureDaemon.STARTED : EnsureDaemon.UNAVAILABLE;
+    return stopped;
+}
+/** The real registry, `/status` and listener-only stop. */
+export function nodeRetireDeps() {
+    return {
+        registered: () => readDaemonRegistry(reticleStateHome()).filter((e) => isAlive(e.pid)),
+        status: (port) => fetchStatus(port),
+        stop: (port) => runKill(port, false),
+    };
+}
+/**
+ * Hold the daemon on `port` until the returned release is called, by renewing a hold on its
+ * `/status` well inside the hold window.
+ *
+ * `init` starts the daemon and can then wait on the app for longer than the idle grace — a cold
+ * desktop build, a slow first compile. None of that counted as activity, and the daemon init had
+ * just started idled out (`reticle_daemon_idle_exit`) while init was still waiting on it.
+ */
+export function holdDaemon(port) {
+    const renew = () => void fetchStatus(port, LOOPBACK_HOST, true);
+    renew();
+    const timer = setInterval(renew, STATUS_HOLD_MS / 3);
+    timer.unref();
+    return () => clearInterval(timer);
 }
-export function nodeEnsureDaemonDeps() {
+export function nodeEnsureDaemonDeps(skewed) {
     return {
+        skewed,
         usable: async (port) => presenceIsUsable(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })),
+        status: (port) => fetchStatus(port),
+        // `reticle kill` without `--force`: it signals only the LISTENER, and only one that answers
+        // /status, so the agent's MCP proxy on the same port survives.
+        replace: (port) => runKill(port, false),
         spawn: (port) => {
             const scriptPath = process.argv[1];
             if (undefined === scriptPath)
                 return false;
             const started = spawnDaemon(process.execPath, scriptPath, daemonSpawnArgs({ port, headless: true, http: false }), port);
-            log('reticle_setup_daemon_started', { port, started });
+            // For a log or a pipe. On a terminal it was a JSON line in the middle of `init`'s output, read
+            // by a person, about a step the next lines already report in words.
+            if (true !== process.stderr.isTTY)
+                log('reticle_setup_daemon_started', { port, started });
             return started;
         },
-        waitReady: (port) => waitForDaemon(port),
+        starting: (port) => {
+            const pid = readPid(port);
+            return null !== pid && isAlive(pid);
+        },
+        // The same wait `reticle restart` does: poll until `/status` answers as a daemon, bounded. A
+        // cold daemon on a fresh HOME outlived the proxy's shorter reconnect budget this used to borrow.
+        waitReady: async (port) => {
+            if (!(await waitForDaemonBind(port)))
+                throw new Error(`no daemon bound :${String(port)}`);
+            return undefined;
+        },
         scriptPath: process.argv[1],
     };
 }

package/dist/command/setup/bringup/static-page-server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The dev server `init` starts for a plain HTML page that has none of its own.
+ *
+ * A directory holding only `index.html` (and a script or two) used to be wired correctly — init
+ * writes the connect snippet into the page — and then stop at "No dev command … start the app
+ * yourself and pass --url". The one thing left between that user and a connected session was a web
+ * server, which is the one thing a page like that never had. So init starts this one, the same way it
+ * starts `npm run dev`, and the rest of setup (wait, open, prove the connect) runs unchanged.
+ *
+ * It is run as its own process (`node static-page-server.js --dir <app>`), not inside init, because it
+ * has to outlive init exactly like any handed-over dev server. It imports nothing but Node, so the
+ * built file runs on its own.
+ *
+ * Loopback only, on both families: a page served to the LAN would publish the pairing token the
+ * snippet carries.
+ */
+export declare const STATIC_PAGE_INDEX = "index.html";
+/** Where the search for a free port starts when none is given — clear of Vite's 5173 run. */
+export declare const STATIC_PAGE_FIRST_PORT = 5500;
+export interface StaticPageServer {
+    readonly url: string;
+    close(): Promise<void>;
+}
+export declare function startStaticPageServer(opts: {
+    root: string;
+    port: number;
+}): Promise<StaticPageServer>;
+/**
+ * The command setup runs for a page with no dev server of its own, or undefined when this is not
+ * that page. Quoted so an app path with a space survives the shell.
+ */
+export declare function staticPageDevCommand(opts: {
+    appDir: string;
+    isStaticPage: boolean;
+}): string | undefined;

package/dist/command/setup/bringup/static-page-server.js

@@ -0,0 +1,151 @@
+/**
+ * The dev server `init` starts for a plain HTML page that has none of its own.
+ *
+ * A directory holding only `index.html` (and a script or two) used to be wired correctly — init
+ * writes the connect snippet into the page — and then stop at "No dev command … start the app
+ * yourself and pass --url". The one thing left between that user and a connected session was a web
+ * server, which is the one thing a page like that never had. So init starts this one, the same way it
+ * starts `npm run dev`, and the rest of setup (wait, open, prove the connect) runs unchanged.
+ *
+ * It is run as its own process (`node static-page-server.js --dir <app>`), not inside init, because it
+ * has to outlive init exactly like any handed-over dev server. It imports nothing but Node, so the
+ * built file runs on its own.
+ *
+ * Loopback only, on both families: a page served to the LAN would publish the pairing token the
+ * snippet carries.
+ */
+import { existsSync, readFile, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+export const STATIC_PAGE_INDEX = 'index.html';
+/** Where the search for a free port starts when none is given — clear of Vite's 5173 run. */
+export const STATIC_PAGE_FIRST_PORT = 5500;
+const PORT_SEARCH_SPAN = 50;
+const DIR_FLAG = '--dir';
+const PORT_FLAG = '--port';
+const LOOPBACK_V4 = '127.0.0.1';
+const LOOPBACK_V6 = '::1';
+const ANNOUNCED_HOST = 'localhost';
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8',
+};
+const FALLBACK_TYPE = 'application/octet-stream';
+/** The file a request names, or null when it is missing or outside `root`. */
+function fileFor(root, rawUrl) {
+    let path;
+    try {
+        path = decodeURIComponent(new URL(rawUrl, 'http://x').pathname);
+    }
+    catch {
+        return null;
+    }
+    const target = resolve(root, `.${path}`);
+    if (target !== root && !target.startsWith(`${root}${sep}`))
+        return null;
+    const file = path.endsWith('/') ? join(target, STATIC_PAGE_INDEX) : target;
+    try {
+        return statSync(file).isFile() ? file : null;
+    }
+    catch {
+        return null;
+    }
+}
+function listen(server, port, host) {
+    return new Promise((ok, fail) => {
+        server.once('error', fail);
+        server.listen(port, host, () => {
+            server.off('error', fail);
+            ok();
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((done) => server.close(() => done()));
+}
+export async function startStaticPageServer(opts) {
+    const root = resolve(opts.root);
+    const handler = (req, res) => {
+        const file = fileFor(root, req.url ?? '/');
+        if (null === file) {
+            res.writeHead(404).end();
+            return;
+        }
+        readFile(file, (err, body) => {
+            if (null !== err) {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, {
+                'content-type': CONTENT_TYPES[extname(file).toLowerCase()] ?? FALLBACK_TYPE,
+                'cache-control': 'no-store',
+            });
+            res.end(body);
+        });
+    };
+    const v4 = createServer(handler);
+    // Port 0 means "any": the v4 bind picks it, and the v6 listener joins the same number.
+    const candidates = 0 === opts.port ? [0] : Array.from({ length: PORT_SEARCH_SPAN }, (_, i) => opts.port + i);
+    let bound;
+    for (const port of candidates) {
+        try {
+            await listen(v4, port, LOOPBACK_V4);
+            bound = v4.address().port;
+            break;
+        }
+        catch {
+            /* taken: try the next one */
+        }
+    }
+    if (undefined === bound) {
+        throw new Error(`no free port in ${String(opts.port)}–${String(opts.port + PORT_SEARCH_SPAN)}`);
+    }
+    // `localhost` resolves to ::1 first on macOS, so the page must answer there too. A machine with
+    // no IPv6 loopback just keeps the v4 listener.
+    const v6 = createServer(handler);
+    const hasV6 = await listen(v6, bound, LOOPBACK_V6).then(() => true, () => false);
+    return {
+        url: `http://${ANNOUNCED_HOST}:${String(bound)}/`,
+        close: async () => {
+            await closeServer(v4);
+            if (hasV6)
+                await closeServer(v6);
+        },
+    };
+}
+/**
+ * The command setup runs for a page with no dev server of its own, or undefined when this is not
+ * that page. Quoted so an app path with a space survives the shell.
+ */
+export function staticPageDevCommand(opts) {
+    if (!opts.isStaticPage || !existsSync(join(opts.appDir, STATIC_PAGE_INDEX)))
+        return undefined;
+    const script = fileURLToPath(import.meta.url).replace(/\.ts$/, '.js');
+    return `"${process.execPath}" "${script}" ${DIR_FLAG} "${opts.appDir}"`;
+}
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return -1 === at ? undefined : argv[at + 1];
+}
+// Run as a script: serve until killed, printing the url the setup wait reads.
+if (undefined !== process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const dir = flag(process.argv, DIR_FLAG) ?? process.cwd();
+    const port = Number(flag(process.argv, PORT_FLAG) ?? STATIC_PAGE_FIRST_PORT);
+    startStaticPageServer({ root: dir, port }).then((server) => process.stdout.write(`serving ${dir}\n  Local: ${server.url}\n`), (err) => {
+        process.stderr.write(`static page server: ${String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/command/setup/desktop-shape.d.ts

@@ -53,6 +53,10 @@ interface ShapePolicy {
     readonly connectBudgetMs: number;
     /** Said out loud, because a desktop run looks stuck if nobody explains the wait. */
     readonly note: string | undefined;
+    /** What the connect wait is waiting on, for the progress lines it prints while it waits. */
+    readonly awaiting: string;
 }
+/** "a Tauri app", "an Electron app": printed when the shape is detected. */
+export declare function describeShape(shape: AppShape): string;
 export declare function policyFor(shape: AppShape): ShapePolicy;
 export {};

package/dist/command/setup/desktop-shape.js

@@ -42,7 +42,21 @@ export function isDesktopOrigin(url) {
 }
 const WEB_CONNECT_MS = 120_000;
 /** A cold `tauri dev` compiles the Rust side before a window exists. */
-const DESKTOP_CONNECT_MS = 10 * 60_000;
+const TAURI_CONNECT_MS = 10 * 60_000;
+/**
+ * Electron has no compile step of that size: its window is a Node process loading a dev server that
+ * is already up. It was given Tauri's ten minutes, so a run whose window was never going to dial in
+ * sat silent for all of them — longer than the daemon it was waiting on stayed alive.
+ */
+const ELECTRON_CONNECT_MS = 3 * 60_000;
+/** "a Tauri app", "an Electron app": printed when the shape is detected. */
+export function describeShape(shape) {
+    if (AppShape.ELECTRON === shape)
+        return 'an Electron app';
+    if (AppShape.TAURI === shape)
+        return 'a Tauri app';
+    return 'a web app';
+}
 export function policyFor(shape) {
     if (AppShape.WEB === shape) {
         return {
@@ -50,12 +64,14 @@ export function policyFor(shape) {
             requireHttpReady: true,
             connectBudgetMs: WEB_CONNECT_MS,
             note: undefined,
+            awaiting: 'the page',
         };
     }
     return {
         openBrowser: false,
         requireHttpReady: false,
-        connectBudgetMs: DESKTOP_CONNECT_MS,
+        connectBudgetMs: AppShape.TAURI === shape ? TAURI_CONNECT_MS : ELECTRON_CONNECT_MS,
+        awaiting: AppShape.TAURI === shape ? 'the Tauri window' : 'the Electron window',
         note: AppShape.TAURI === shape
             ? 'Tauri app: not opening a browser, because its own window is the client. A cold `tauri dev` builds the Rust side first, so the window can take minutes to appear.'
             : 'Electron app: not opening a browser, because its own window is the client. Waiting for the app to launch and dial in.',

package/dist/command/setup/init/init-port.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `RETICLE_PORT`, when it names a port. The one reader of it for the CLI, `init` included.
+ *
+ * `init` took only `--port`, so a shell that exported RETICLE_PORT got a project wired, and a daemon
+ * started, on the default port while every other command it ran dialled the exported one. Fed to
+ * `portForInit` as the explicit port, so the files phase writes it into `.reticle.json` and the
+ * runtime phase binds it: the two halves of `init` cannot disagree.
+ */
+export declare function portFromEnv(env: Readonly<Record<string, string | undefined>>): number | undefined;
+export declare function portForInit(explicit: number | undefined, configured: number | undefined, projectId: string | undefined, deps: {
+    /** The projects the daemon on `port` belongs to or is serving right now. */
+    daemonProjects: (port: number) => Promise<readonly string[]>;
+    daemonPresent: (port: number) => Promise<boolean>;
+    pickPort: (preferred: number) => Promise<number>;
+}): Promise<number | undefined>;

package/dist/command/setup/init/init-port.js

@@ -0,0 +1,44 @@
+/**
+ * The daemon port `reticle init` wires a project to.
+ *
+ * Init used to leave this unset, so every project on a machine was wired to the default port. The
+ * second one to run was connected to the first one's daemon, and the bridge refused its app. When a
+ * daemon for another project already holds the default, the new project gets its own port, and init
+ * records it in `.reticle.json`, where the CLI and the build plugins both read it.
+ *
+ * Undefined means the default.
+ */
+import { RETICLE_DEFAULT_PORT, ReticleEnv } from '@reticlehq/core';
+const MAX_PORT = 65_535;
+/**
+ * `RETICLE_PORT`, when it names a port. The one reader of it for the CLI, `init` included.
+ *
+ * `init` took only `--port`, so a shell that exported RETICLE_PORT got a project wired, and a daemon
+ * started, on the default port while every other command it ran dialled the exported one. Fed to
+ * `portForInit` as the explicit port, so the files phase writes it into `.reticle.json` and the
+ * runtime phase binds it: the two halves of `init` cannot disagree.
+ */
+export function portFromEnv(env) {
+    const raw = env[ReticleEnv.PORT];
+    if (undefined === raw || !/^\d+$/.test(raw))
+        return undefined;
+    const port = Number(raw);
+    return 0 < port && port <= MAX_PORT ? port : undefined;
+}
+export async function portForInit(explicit, configured, projectId, deps) {
+    if (explicit !== undefined)
+        return explicit;
+    if (configured !== undefined)
+        return configured;
+    // Undefined, not the default's number: an explicit default would be written into every generated
+    // config as a `port` nobody chose.
+    if (!(await deps.daemonPresent(RETICLE_DEFAULT_PORT)))
+        return undefined;
+    // The bridge's own rule: it refuses a page only when it has served exactly ONE other project. A
+    // daemon serving nobody, several projects, or ours accepts this one. A project that has never
+    // been through init has no id yet, so a single named holder is somebody else.
+    const holders = await deps.daemonProjects(RETICLE_DEFAULT_PORT);
+    if (1 !== holders.length || holders[0] === projectId)
+        return undefined;
+    return deps.pickPort(RETICLE_DEFAULT_PORT + 1);
+}

package/dist/command/setup/init/init-runtime.d.ts

@@ -5,7 +5,7 @@
  * cli.ts is a dispatcher: a command that grew a second half should not make the file that routes
  * every command harder to read.
  */
-import type { InitResult } from '@reticlehq/init';
+import { type InitResult } from '@reticlehq/init';
 /** Just enough of the parsed command to decide and run. */
 interface InitRuntimeArgs {
     readonly port: number | undefined;