@reticlehq/server 3.2.0 → 3.4.0

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-host.js

@@ -3,6 +3,9 @@ import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
 import { declaredInstallSource } from '../../../telemetry/install-source.js';
+/** The variable Claude Code sets on every process it spawns, and the value it sets it to. */
+const CLAUDE_CODE_MARKER_ENV = 'CLAUDECODE';
+const CLAUDE_CODE_MARKER_VALUE = '1';
 export function serverInitHost() {
     return {
         span(name, fields, fn) {
@@ -33,5 +36,10 @@ export function serverInitHost() {
         installSource() {
             return declaredInstallSource();
         },
+        // Claude Code marks every process it spawns. If the marker ever changes, init falls back to the
+        // notice it printed before, which is the safe direction.
+        insideClaudeCode() {
+            return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
+        },
     };
 }

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;

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

@@ -7,18 +7,27 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { FEEDBACK_HINT, Framework } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
 import { registerOtherAgents, runSetupCommand } from '../setup-command.js';
 import { bridgeOccupied } from '../bringup/bridge-port.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
 import { relaunchDecision } from '../bringup/relaunch.js';
 import { claudeTranscriptExists, codexSessionFor } from '../terminal/transcripts.js';
 import { probePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
+import { staticPageDevCommand } from '../bringup/static-page-server.js';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
+/**
+ * The shapes whose served HTML carries the SDK marker: Vite injects it into index.html, and a plain
+ * HTML page has the snippet pasted in. Everything else connects from the JS bundle, where a fetch
+ * of the document can never see it. See `htmlCarriesSdk` in run-setup.ts.
+ */
+const HTML_CARRIES_SDK = new Set([Framework.VITE, Framework.HTML]);
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
 function wantsAgents(parsed) {
     return false !== parsed.agents && false !== parsed.mcp;
@@ -77,9 +86,16 @@ export async function continueAfterInit(parsed, result, io, cwd) {
                 process.exit(1);
         });
     }
+    // From here on init left the ask to us, so it is the last thing on every exit below.
+    const ask = (spaced = true) => {
+        if (spaced)
+            io.print('');
+        io.print(FEEDBACK_HINT);
+    };
     const context = result.context;
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why.
+        ask();
         process.exit(1);
     }
     // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
@@ -100,12 +116,16 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }), port);
     if (refusal !== undefined) {
         io.print(refusal);
+        ask();
         process.exit(1);
     }
     return runSetupCommand({
         appDir: context.appDir,
         invokedAt: cwd,
         bridgePort: port,
+        // Read here because this is the layer that already owns the bridge: setup opens a lease over
+        // the daemon's MCP transport for `--no-open`, and that transport is gated on this token.
+        pairingToken: readOrCreatePairingTokenSync(defaultPairingTokenDir()),
         env: collectEnv(parsed.env ?? []),
         openBrowser: false !== parsed.open,
         registerAgents: wantsAgents(parsed),
@@ -118,7 +138,19 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             ? {}
             : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
         pollMs: POLL_MS,
-        ...(undefined === context.devCommand ? {} : { devCommand: context.devCommand }),
+        htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
+        // A plain page with no dev script gets Reticle's own static server, so the page is actually
+        // served and the connect can be proved, instead of stopping at "start the app yourself".
+        ...(() => {
+            const devCommand = context.devCommand ??
+                (undefined === parsed.url
+                    ? staticPageDevCommand({
+                        appDir: context.appDir,
+                        isStaticPage: Framework.HTML === context.framework,
+                    })
+                    : undefined);
+            return undefined === devCommand ? {} : { devCommand };
+        })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
     }, (line) => io.print(line)).then((outcome) => {
         // One object, so an agent reads a result instead of interpreting a report.
@@ -145,9 +177,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
             // a wrong sentence, which is the worse of the two: the exit code is read by CI and the
             // sentence is read by a person deciding whether their app is verified. It is not.
-            io.print(`✓ ${outcome.url ?? 'the app'} is instrumented and connected — but NOT verified.`);
+            // The connect already said "connected, nothing verified yet" and listed what to do next;
+            // repeating it here was the same sentence twice, three lines apart.
             for (const [i, step] of outcome.fallback.entries())
                 io.print(`   ${String(i + 1)}. ${step}`);
+            // Already spaced by the blank line above when nothing was listed.
+            ask(0 < outcome.fallback.length);
             return;
         }
         if (outcome.ok) {
@@ -156,6 +191,7 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             // themselves, and it deserves a line of its own rather than a paragraph that gets skimmed.
             io.print('  Read the FINDINGS above before moving on: a flow can pass with a failed request or a ' +
                 'console error behind it, and that is the app, not the check.');
+            ask();
             return;
         }
         // A run that produced no verdict did not succeed, and the exit code is the one place a caller
@@ -163,6 +199,7 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         io.print('⚠ setup did not finish. To carry on from here:');
         for (const [i, step] of outcome.fallback.entries())
             io.print(`   ${i + 1}. ${step}`);
+        ask();
         process.exit(1);
     });
 }

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

@@ -15,31 +15,42 @@ import type { CandidateSession } from './session-pick.js';
 import type { PageProbe } from './probe/page-probe.js';
 /** The dev server this process started, and the only one it will ever stop. */
 export declare class OwnedDevServer {
+    private readonly logDir;
     private child;
-    private buffer;
-    private lastOutputAt;
+    private log;
+    private cwd;
+    private startedAt;
     private handedOver;
+    constructor(logDir?: string);
+    /**
+     * Start it with its output going to a bounded log, through a supervisor that outlives `init`.
+     *
+     * Not a pipe into THIS process. A pipe's read end belonged to `init`; once it exited nobody held
+     * it, and the server's next write (a compile error, an HMR line, SvelteKit's first warning) was an
+     * EPIPE that killed it: "it connected, then the app went away". And not a bare file either, which
+     * has no ceiling: an upstream echo loop grew one to 2.9 GB in five minutes. The supervisor reads
+     * the server's pipes for as long as they are open and rotates the file past a cap — see
+     * dev-server-log-cap.ts. It is the process group leader, so `pid()` and `stop()` cover both.
+     */
     start(command: string, cwd: string, env: Readonly<Record<string, string>>): void;
+    /** Where the server's output goes, for the line that hands it over. */
+    logPath(): string | undefined;
     /** The process group leader, for a caller that has to clean up what it handed over. */
     pid(): number | undefined;
     output(): string;
     exited(): boolean;
+    /** Since the log last grew, which is since the server last printed anything. */
     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.
+     * Leave the server running and stop holding it. After this, `stop()` does nothing.
      *
-     * 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.
+     * Only `unref` is needed: the output is the supervisor's, so no pipe of ours holds the event loop
+     * (`init` once printed "setup complete" and hung on one). `url` is recorded beside the log, so the
+     * next `init` attaches to this server rather than starting a second one beside it.
      */
-    handOver(): void;
+    handOver(url?: string): void;
     stop(): void;
 }
 /**
@@ -50,9 +61,11 @@ export declare class OwnedDevServer {
  * 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).
+ * is REFUSED — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884). Only
+ * refused: a timeout means the right server is slow, and the caller polls again on the same host.
+ * See `isAddressMiss` for the Next 16 first run that hopping on a timeout broke.
  */
-export declare function probePage(url: string): Promise<PageProbe>;
+export declare function probePage(url: string, timeoutMs?: number): 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. */