@reticlehq/init 2.14.0

package/dist/codex-toml.js

@@ -0,0 +1,144 @@
+/**
+ * Read-only detection of an existing `[mcp_servers.reticle]` table in `~/.codex/config.toml`.
+ *
+ * `init` printed `[⚠] MCP server (Codex CLI) → ~/.codex/config.toml — add this by hand` on machines
+ * whose config ALREADY held a working table with the same command and args, because
+ * `mergeClientConfig` short-circuits every non-JSON format to MANUAL without ever reading the file
+ * (#681, reported independently twice). The setup instructions tell an agent it MUST resolve a `⚠`,
+ * and the install gate's own contract is zero `⚠`, so the warning sent people to hand-edit a global
+ * config for no reason.
+ *
+ * This only ANSWERS a question; it never produces TOML to write. Editing TOML without a parser is
+ * how a config gets corrupted, and a corrupted `~/.codex/config.toml` costs the user every server
+ * they had — so writing stays MANUAL, exactly as before.
+ *
+ * A deliberately narrow scanner rather than a TOML parser, because the question is narrow: which
+ * strings does one named table's `command` and `args` hold? Anything it cannot read confidently —
+ * a multi-line array, an unfamiliar quoting, a shape it has no rule for — yields no tokens and
+ * therefore no detection, which is today's behaviour. The failure mode stays "warn when we should
+ * not have", never "stay quiet when the server is genuinely unregistered".
+ */
+import { MCP_SERVER_NAME } from './mcp.js';
+/** Strip a `#` comment that is not inside a string literal. */
+function withoutComment(line) {
+    let quote;
+    for (let i = 0; i < line.length; i += 1) {
+        const char = line[i];
+        if (undefined !== quote) {
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if ('"' === char || "'" === char) {
+            quote = char;
+            continue;
+        }
+        if ('#' === char)
+            return line.slice(0, i);
+    }
+    return line;
+}
+/** `reticle`, `"reticle"` and `'reticle'` are the same key to TOML. */
+function unquote(key) {
+    const trimmed = key.trim();
+    const first = trimmed[0];
+    if (('"' === first || "'" === first) && trimmed.endsWith(first) && trimmed.length >= 2) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/** Split a dotted TOML key path, respecting quoted segments. */
+function keyPath(raw) {
+    const parts = [];
+    let current = '';
+    let quote;
+    for (const char of raw) {
+        if (undefined !== quote) {
+            current += char;
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if ('"' === char || "'" === char) {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if ('.' === char) {
+            parts.push(unquote(current));
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    parts.push(unquote(current));
+    return parts.map((p) => p.trim()).filter((p) => 0 < p.length);
+}
+/** Every double- or single-quoted string in `value`, in order. */
+function quotedStrings(value) {
+    return [...value.matchAll(/"([^"\\]*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2] ?? '');
+}
+/** The table path our server's entry lives under, e.g. `mcp_servers.reticle`. */
+function ourTablePath(serversKey) {
+    return [serversKey, MCP_SERVER_NAME];
+}
+function samePath(a, b) {
+    return a.length === b.length && a.every((segment, i) => segment === b[i]);
+}
+/**
+ * The `command` and `args` strings the config declares for our server, or `[]` when it declares
+ * none — including when the shape was not one this scanner reads.
+ *
+ * Handles the three forms a Codex config actually takes: the standard table header, a dotted
+ * assignment (`mcp_servers.reticle = { … }`), and a key inside an `[mcp_servers]` table.
+ */
+export function codexServerTokens(existing, serversKey) {
+    if (null === existing)
+        return [];
+    const want = ourTablePath(serversKey);
+    const tokens = [];
+    let table = [];
+    let inOurTable = false;
+    /** Set while a `[ ... ]` value is still open across lines; `true` when that value is ours. */
+    let openArrayIsOurs;
+    for (const rawLine of existing.split(/\r?\n/)) {
+        const line = withoutComment(rawLine).trim();
+        if (0 === line.length)
+            continue;
+        // `args = [` spread over several lines is the shape a formatter produces, and reading only the
+        // first line of it would leave a HALF-read entry that looks like somebody else's registration.
+        if (undefined !== openArrayIsOurs) {
+            if (openArrayIsOurs)
+                tokens.push(...quotedStrings(line));
+            if (line.includes(']'))
+                openArrayIsOurs = undefined;
+            continue;
+        }
+        // A table header ends whatever table we were in, whether or not it is ours.
+        const header = /^\[{1,2}([^\]]+)\]{1,2}$/.exec(line);
+        if (null !== header) {
+            table = keyPath(header[1] ?? '');
+            inOurTable = samePath(table, want);
+            continue;
+        }
+        const assignment = /^([^=]+)=(.*)$/.exec(line);
+        if (null === assignment)
+            continue;
+        const key = keyPath(assignment[1] ?? '');
+        const value = assignment[2] ?? '';
+        // Inside `[mcp_servers.reticle]`, the keys we care about are `command` and `args`.
+        const ours = (inOurTable && 1 === key.length && ('command' === key[0] || 'args' === key[0])) ||
+            // `mcp_servers.reticle = { command = "npx", args = [...] }` at the root, or
+            // `reticle = { … }` inside an `[mcp_servers]` table.
+            samePath([...table, ...key], want);
+        if (ours)
+            tokens.push(...quotedStrings(value));
+        if (value.includes('[') && !value.includes(']'))
+            openArrayIsOurs = ours;
+    }
+    return tokens;
+}
+/** Does this config already declare a Reticle server under our name? */
+export function codexDeclaresOurServer(existing, serversKey) {
+    return 0 < codexServerTokens(existing, serversKey).length;
+}

package/dist/connect-steps.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The step titles `init` emits, and which of them decide whether the app can dial the daemon.
+ *
+ * Lifted out of `plan.ts` when that file reached the size backstop. A cohesive unit on its own
+ * terms: one question, asked of a step title, with one consequence — a manual step in this set makes
+ * `init` exit non-zero instead of reporting a success over an app that can never connect.
+ *
+ * The membership used to be matched against free strings written out a second time here, so
+ * renaming a step in `plan-framework.ts` silently dropped it out of the set and nothing went red.
+ * `StepTitle` is now the one place a title is spelled: both files import it, so a rename is a
+ * compile error and `plan-framework.test.ts` pins that no builder has drifted back to a literal.
+ */
+/** Every fixed title a plan step can carry. The one spelling; nothing writes a title inline. */
+export declare const StepTitle: {
+    readonly VITE_PLUGIN: "Vite plugin";
+    readonly CAPABILITIES: "Capabilities + store";
+    readonly CAPABILITIES_TODO: "AGENT: finish the capabilities file";
+    readonly RETICLE_DEV_COMPONENT: "ReticleDev component";
+    readonly NEXT_CONFIG: "Next config (withReticle)";
+    readonly MOUNT_RETICLE_DEV: "Mount ReticleDev";
+    readonly CONNECT_MODULE: "Reticle connect module";
+    readonly PAIRING_TOKEN: "Pairing token";
+    readonly PAIRING_TOKEN_PER_MACHINE: "Pairing token is per-machine";
+    readonly CONNECT_SNIPPET_CRA: "Connect snippet (CRA)";
+    readonly CONNECT_SNIPPET_NUXT: "Connect snippet (Nuxt)";
+    readonly NUXT_CONFIG: "Nuxt config (token + watcher)";
+    readonly NUXT_RESTART: "Restart the Nuxt dev server";
+    readonly CONNECT_SNIPPET_REACT_ROUTER: "Connect snippet (React Router)";
+    readonly CONNECT_SNIPPET_TANSTACK_START: "Connect snippet (TanStack Start)";
+    readonly ELECTRON_VITE_PLUGIN: "Vite plugin (electron-vite renderer)";
+    readonly ELECTRON_PRELOAD: "Electron preload (IPC shim)";
+    readonly ELECTRON_CAPTURE: "Electron capture (screenshots)";
+    readonly TANSTACK_START_UNVERIFIED: "TanStack Start is UNVERIFIED";
+    readonly SVELTEKIT_UNVERIFIED: "SvelteKit is UNVERIFIED";
+    readonly CLIENT_HOOK: "Reticle client hook";
+    readonly CONNECT_SNIPPET_ASTRO: "Connect snippet (Astro)";
+    readonly ASTRO_CONFIG: "Astro config (token + build target)";
+    readonly ASTRO_ENV_DTS: "Astro env types (Vite defines)";
+    readonly CSP: "Content-Security-Policy";
+    readonly CONNECT_SNIPPET: "Connect snippet";
+};
+export type StepTitle = (typeof StepTitle)[keyof typeof StepTitle];
+/** Exported for the guard test: every title a step builder emits must be one of these. */
+export declare const STEP_TITLES: readonly StepTitle[];
+/**
+ * Titles of the steps WITHOUT which no session ever appears.
+ *
+ * A ⚠ on one of these is not a warning, it is a guaranteed failure: nothing performs the manual step,
+ * so the app will not connect and every Reticle tool will answer "no browser session connected".
+ * Reported from a field sweep, where the ⚠ count and "did it connect" were treated as independent
+ * signals and are not.
+ */
+export declare const CONNECT_STEP_TITLES: ReadonlySet<StepTitle>;
+/** True when this step is what makes the app dial the daemon. */
+export declare function isConnectStep(title: string): boolean;

package/dist/connect-steps.js

@@ -0,0 +1,92 @@
+/**
+ * The step titles `init` emits, and which of them decide whether the app can dial the daemon.
+ *
+ * Lifted out of `plan.ts` when that file reached the size backstop. A cohesive unit on its own
+ * terms: one question, asked of a step title, with one consequence — a manual step in this set makes
+ * `init` exit non-zero instead of reporting a success over an app that can never connect.
+ *
+ * The membership used to be matched against free strings written out a second time here, so
+ * renaming a step in `plan-framework.ts` silently dropped it out of the set and nothing went red.
+ * `StepTitle` is now the one place a title is spelled: both files import it, so a rename is a
+ * compile error and `plan-framework.test.ts` pins that no builder has drifted back to a literal.
+ */
+import { CSP_STEP_TITLE } from './csp-check.js';
+/** Every fixed title a plan step can carry. The one spelling; nothing writes a title inline. */
+export const StepTitle = {
+    VITE_PLUGIN: 'Vite plugin',
+    CAPABILITIES: 'Capabilities + store',
+    CAPABILITIES_TODO: 'AGENT: finish the capabilities file',
+    RETICLE_DEV_COMPONENT: 'ReticleDev component',
+    NEXT_CONFIG: 'Next config (withReticle)',
+    MOUNT_RETICLE_DEV: 'Mount ReticleDev',
+    CONNECT_MODULE: 'Reticle connect module',
+    PAIRING_TOKEN: 'Pairing token',
+    PAIRING_TOKEN_PER_MACHINE: 'Pairing token is per-machine',
+    CONNECT_SNIPPET_CRA: 'Connect snippet (CRA)',
+    CONNECT_SNIPPET_NUXT: 'Connect snippet (Nuxt)',
+    NUXT_CONFIG: 'Nuxt config (token + watcher)',
+    NUXT_RESTART: 'Restart the Nuxt dev server',
+    CONNECT_SNIPPET_REACT_ROUTER: 'Connect snippet (React Router)',
+    CONNECT_SNIPPET_TANSTACK_START: 'Connect snippet (TanStack Start)',
+    ELECTRON_VITE_PLUGIN: 'Vite plugin (electron-vite renderer)',
+    ELECTRON_PRELOAD: 'Electron preload (IPC shim)',
+    ELECTRON_CAPTURE: 'Electron capture (screenshots)',
+    TANSTACK_START_UNVERIFIED: 'TanStack Start is UNVERIFIED',
+    SVELTEKIT_UNVERIFIED: 'SvelteKit is UNVERIFIED',
+    CLIENT_HOOK: 'Reticle client hook',
+    CONNECT_SNIPPET_ASTRO: 'Connect snippet (Astro)',
+    ASTRO_CONFIG: 'Astro config (token + build target)',
+    ASTRO_ENV_DTS: 'Astro env types (Vite defines)',
+    CSP: CSP_STEP_TITLE,
+    CONNECT_SNIPPET: 'Connect snippet',
+};
+/** Exported for the guard test: every title a step builder emits must be one of these. */
+export const STEP_TITLES = Object.values(StepTitle);
+/**
+ * Titles of the steps WITHOUT which no session ever appears.
+ *
+ * A ⚠ on one of these is not a warning, it is a guaranteed failure: nothing performs the manual step,
+ * so the app will not connect and every Reticle tool will answer "no browser session connected".
+ * Reported from a field sweep, where the ⚠ count and "did it connect" were treated as independent
+ * signals and are not.
+ */
+export const CONNECT_STEP_TITLES = new Set([
+    StepTitle.CONNECT_SNIPPET,
+    StepTitle.CONNECT_SNIPPET_CRA,
+    StepTitle.CONNECT_SNIPPET_ASTRO,
+    StepTitle.CONNECT_SNIPPET_NUXT,
+    // The config is the other half of the Nuxt connect, not a nicety: it is the only thing in a Nuxt
+    // app that can inline the pairing token, and the bridge refuses a connect without one even on
+    // localhost. A plugin written beside an unpatched config is a guaranteed non-connection.
+    StepTitle.NUXT_CONFIG,
+    StepTitle.CONNECT_SNIPPET_REACT_ROUTER,
+    StepTitle.CONNECT_SNIPPET_TANSTACK_START,
+    StepTitle.CLIENT_HOOK,
+    StepTitle.CONNECT_MODULE,
+    StepTitle.RETICLE_DEV_COMPONENT,
+    // Writing the component and MOUNTING it are two steps, and only the write was here. A root layout
+    // whose shape `init` does not recognise leaves the component on disk and never rendered: the SDK
+    // is in the project, nothing imports it, and `init` exited 0 over an app that could not connect.
+    StepTitle.MOUNT_RETICLE_DEV,
+    // NOT here, and the reason is worth keeping: `StepTitle.PAIRING_TOKEN`.
+    //
+    // It is a genuine connect step — CRA inlines only REACT_APP_*, so without the token in the env
+    // file the bridge refuses every connection and the app boots, looks correct, and never pairs. But
+    // it goes MANUAL in exactly one situation: no daemon has ever run on this machine, so there is no
+    // token to inline. That is the FIRST CRA install on a fresh machine, i.e. the first-time user —
+    // and making that exit non-zero reports a broken install to the one person least able to tell
+    // that it is not.
+    //
+    // The real fix is for `init` to mint the token rather than only read it, which is what both the
+    // daemon and the Vite plugin already do. `runInit` is synchronous and the existing helpers are
+    // not, and `gate:install` scaffolds no CRA app, so that change would ship with no coverage of the
+    // path it changes. It is worth doing, and worth doing with a scaffold behind it.
+    StepTitle.VITE_PLUGIN,
+    // electron-vite's connect IS the renderer plugin. Without it the SDK never injects, and the
+    // preload/capture steps are not enough to produce a session.
+    StepTitle.ELECTRON_VITE_PLUGIN,
+]);
+/** True when this step is what makes the app dial the daemon. */
+export function isConnectStep(title) {
+    return CONNECT_STEP_TITLES.has(title);
+}

package/dist/cra.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Wiring Reticle into a Create React App project.
+ *
+ * CRA had no automated path: init reported `⚠ Connect snippet → index.html`, a target that cannot
+ * work. CRA's `public/index.html` is a static template the bundler never processes for modules, so a
+ * bare import in it resolves to nothing. `src/index.tsx` is what gets bundled, and that is where the
+ * connect has to arrive.
+ *
+ * The token is the second half of the problem. Every other stack has somewhere to inline it —
+ * Vite defines `__RETICLE_TOKEN__`, the Astro and HTML snippets read the file in Node. `src/index.tsx`
+ * is browser code inside a bundler that inlines exactly one thing: environment variables prefixed
+ * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
+ * mechanism and is gitignored by CRA's own template.
+ */
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
+export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export declare function craDevModulePath(typescript: boolean): string;
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export declare const CRA_DEV_MODULE_PATH: string;
+export declare const CRA_ENV_PATH = ".env.development.local";
+export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export declare const URL_VAR = "REACT_APP_RETICLE_URL";
+/**
+ * What the app itself says when the token is not there.
+ *
+ * The token is a per-machine secret and CRA's own template gitignores the file it lives in, so it
+ * CANNOT travel with the repo — that part is correct and must stay. What was wrong is that it failed
+ * silently: a teammate clones, runs `npm start`, and the app connects with an empty token, so the
+ * only signal is the bridge's generic `authentication failed` in a console nobody had open. Naming
+ * the variable, the gitignored file and the one command that fixes it turns a dead app into a
+ * one-line repair. Every other stack reads the token in Node at dev-server start (the Vite plugin,
+ * withReticle); CRA has no such hook without ejecting, so this message is the fix.
+ */
+export declare const CRA_TOKEN_MISSING_NOTE: string;
+/**
+ * Said as its own NOTICE line, beside the write — not inside it.
+ *
+ * The caveat has always been in the write step's `detail`, and the write step renders `[✓]`. But
+ * `SKILL.md` tells whoever reads the report: *"If every line is `✓`, `·` or `–`, skip to Step 4 and
+ * validate."* So the one fact that makes this install conditional sat in the one place the reading
+ * protocol says to ignore — which is exactly how it was reported to us as "4 OK marks and no
+ * warning". The words were on screen; the reader was following instructions.
+ *
+ * It cannot simply be promoted: `run.ts` only writes steps whose status is APPLY, so demoting the
+ * token step to NOTICE would stop it writing the token and break the install outright.
+ */
+export declare const CRA_TOKEN_PER_MACHINE_NOTICE: string;
+/** Add the import after the last existing one, or null when it is already present. */
+export declare function craImportPatch(source: string): string | null;
+/** Set the token variable, or null when nothing needs to change. */
+export declare function craEnvPatch(existing: string | null, token: string, url?: string): string | null;
+/** Options for the CRA connect module. */
+interface CraDevModuleOptions {
+    /**
+     * When false, emit a `.js`-shaped body (no `export {}`). Default true for callers that predate
+     * the language branch.
+     */
+    typescript?: boolean;
+    /** `data-testid` values scanned from the app's source, declared so the app is verifiable. */
+    testids?: readonly string[];
+}
+/** The dev-only connect module imported from the app entry. */
+export declare function craDevModuleFile(port: number | undefined, projectId?: string, options?: CraDevModuleOptions): string;
+export {};

package/dist/cra.js

@@ -0,0 +1,183 @@
+/**
+ * Wiring Reticle into a Create React App project.
+ *
+ * CRA had no automated path: init reported `⚠ Connect snippet → index.html`, a target that cannot
+ * work. CRA's `public/index.html` is a static template the bundler never processes for modules, so a
+ * bare import in it resolves to nothing. `src/index.tsx` is what gets bundled, and that is where the
+ * connect has to arrive.
+ *
+ * The token is the second half of the problem. Every other stack has somewhere to inline it —
+ * Vite defines `__RETICLE_TOKEN__`, the Astro and HTML snippets read the file in Node. `src/index.tsx`
+ * is browser code inside a bundler that inlines exactly one thing: environment variables prefixed
+ * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
+ * mechanism and is gitignored by CRA's own template.
+ */
+import { bridgeWsUrl } from '@reticlehq/core';
+import { CLI } from './agent-rules.js';
+import { registerCapabilitiesCall } from './snippets.js';
+/** The line added to `src/index.tsx` / `src/index.js`. Side-effect import: the module guards itself on NODE_ENV. */
+export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
+/**
+ * Where the connect module lands — `.ts` only when the app already speaks TypeScript.
+ *
+ * A JavaScript CRA project has no tsconfig and cannot resolve `.ts` (#675). Emitting `.ts` there
+ * makes the first compile after init fail while the plan still reports `[✓]`.
+ */
+export function craDevModulePath(typescript) {
+    return typescript ? 'src/reticle-dev.ts' : 'src/reticle-dev.js';
+}
+/** TypeScript default path — prefer `craDevModulePath` when the project's language is known. */
+export const CRA_DEV_MODULE_PATH = craDevModulePath(true);
+export const CRA_ENV_PATH = '.env.development.local';
+export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export const URL_VAR = 'REACT_APP_RETICLE_URL';
+/**
+ * What the app itself says when the token is not there.
+ *
+ * The token is a per-machine secret and CRA's own template gitignores the file it lives in, so it
+ * CANNOT travel with the repo — that part is correct and must stay. What was wrong is that it failed
+ * silently: a teammate clones, runs `npm start`, and the app connects with an empty token, so the
+ * only signal is the bridge's generic `authentication failed` in a console nobody had open. Naming
+ * the variable, the gitignored file and the one command that fixes it turns a dead app into a
+ * one-line repair. Every other stack reads the token in Node at dev-server start (the Vite plugin,
+ * withReticle); CRA has no such hook without ejecting, so this message is the fix.
+ */
+export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle cannot pair with the daemon. ` +
+    `The pairing token is per-machine and ${CRA_ENV_PATH} is gitignored by CRA's template, ` +
+    `so it does not survive a clone. Run \`${CLI} init\` in this project to write it for this machine.`;
+/**
+ * Said as its own NOTICE line, beside the write — not inside it.
+ *
+ * The caveat has always been in the write step's `detail`, and the write step renders `[✓]`. But
+ * `SKILL.md` tells whoever reads the report: *"If every line is `✓`, `·` or `–`, skip to Step 4 and
+ * validate."* So the one fact that makes this install conditional sat in the one place the reading
+ * protocol says to ignore — which is exactly how it was reported to us as "4 OK marks and no
+ * warning". The words were on screen; the reader was following instructions.
+ *
+ * It cannot simply be promoted: `run.ts` only writes steps whose status is APPLY, so demoting the
+ * token step to NOTICE would stop it writing the token and break the install outright.
+ */
+export const CRA_TOKEN_PER_MACHINE_NOTICE = `${CRA_ENV_PATH} is in CRA's own .gitignore, so the token just written does not travel. ` +
+    'It works on THIS machine and nowhere else: a teammate cloning the repo, CI, or a container ' +
+    'gets an app that boots, never pairs, and reports it only in the browser console. ' +
+    `Each developer runs \`${CLI} init\` once locally.`;
+/** Add the import after the last existing one, or null when it is already present. */
+export function craImportPatch(source) {
+    if (source.includes(CRA_DEV_MODULE_IMPORT))
+        return null;
+    const lines = source.split('\n');
+    // After the LAST import: React's own imports must still run first, and a side-effect import placed
+    // above them would connect before the app exists.
+    let lastImport = -1;
+    for (const [index, line] of lines.entries()) {
+        if (/^\s*import\s/.test(line))
+            lastImport = index;
+    }
+    lines.splice(lastImport + 1, 0, CRA_DEV_MODULE_IMPORT);
+    return lines.join('\n');
+}
+/** Set the token variable, or null when nothing needs to change. */
+export function craEnvPatch(existing, token, url) {
+    if ('' === token)
+        return null;
+    const pairs = [
+        [TOKEN_VAR, token],
+        ...(url !== undefined && url.length > 0 ? [[URL_VAR, url]] : []),
+    ];
+    let next = null === existing || '' === existing.trim() ? '' : existing;
+    for (const [name, value] of pairs) {
+        const line = `${name}=${value}`;
+        if (next.includes(line))
+            continue;
+        // Replace rather than append: two assignments of one variable is a silent coin flip on which
+        // wins, and for the URL that coin decides which daemon the app talks to.
+        if (new RegExp(`^${name}=`, 'm').test(next)) {
+            next = next.replace(new RegExp(`^${name}=.*$`, 'm'), line);
+        }
+        else {
+            next = `${'' === next || next.endsWith('\n') ? next : `${next}\n`}${line}\n`;
+        }
+    }
+    return next === (existing ?? '') ? null : next;
+}
+/** The dev-only connect module imported from the app entry. */
+export function craDevModuleFile(port, projectId, options = {}) {
+    const typescript = false !== options.typescript;
+    const fields = [];
+    // `bridgeWsUrl`, not a hand-written string. This was the only client URL in the product spelling
+    // the host as `127.0.0.1` while every other generator said `localhost` — same endpoint, but a
+    // difference with no reason behind it is the kind that becomes a real one after somebody edits half
+    // of it.
+    if (port !== undefined)
+        fields.push(`url: '${bridgeWsUrl(port)}'`);
+    if (projectId !== undefined && projectId.length > 0)
+        fields.push(`projectId: '${projectId}'`);
+    // Multiline on purpose (#684): a single-line connect + console.error fails CRA boilerplate
+    // Prettier (printWidth 80) and the project's own lint blocks a clean install.
+    const connectFields = [
+        ...fields.map((f) => `      ${f},`),
+        '      ...(url.length > 0 ? { url } : {}),',
+        '      ...(token.length > 0 ? { token } : {}),',
+    ].join('\n');
+    // Split so every emitted line stays under a CRA boilerplate printWidth of 80 (#684). A single
+    // JSON.stringify of the whole note is ~290 characters and fails prettier-as-eslint on install.
+    // Chunks are joined with `+` in the emitted file; together they equal `[reticle] ${CRA_TOKEN_MISSING_NOTE}`.
+    const missingChunks = [
+        `[reticle] ${TOKEN_VAR} is not set, so Reticle `,
+        'cannot pair with the daemon. The pairing token is ',
+        `per-machine and ${CRA_ENV_PATH} is gitignored by `,
+        "CRA's template, so it does not survive a clone. Run ",
+        `\`${CLI} init\` in this project to write it for this `,
+        'machine.',
+    ].map((c) => JSON.stringify(c));
+    // Eight spaces match the indent inside `console.error(` below.
+    const missingExpr = missingChunks.join(' +\n        ');
+    // `export {}` is a TypeScript empty-module marker. A `.js` file with it is fine under Babel, but
+    // the workaround reporters used was to drop it when renaming to `.js` — keep the JS emit clean.
+    const trailer = typescript ? '\nexport {};\n' : '\n';
+    return `// Dev-only: connect Reticle. Imported for its side effect from src/index.tsx.
+//
+// CRA's public/index.html is a static template the bundler never processes for
+// modules, so the connect cannot live there. The pairing token arrives through
+// REACT_APP_RETICLE_TOKEN because REACT_APP_* is the only thing CRA inlines
+// into browser code.
+if (process.env.NODE_ENV === 'development') {
+  void import('@reticlehq/react').then((sdk) => {
+    // On its own line: CRA boilerplate prettier caps lines at 80.
+    const { reticle, install, registerCapabilities } = sdk;
+    install();
+    const token = process.env.${TOKEN_VAR} ?? '';
+    // Written by \`reticle init\` from the daemon that was live when it ran, and
+    // refreshed by re-running it. CRA gives us no hook to resolve this at
+    // dev-server start, so if the daemon moves, re-run \`reticle init\` rather
+    // than editing the url below.
+    const url = process.env.${URL_VAR} ?? '';
+    // Loud on purpose: without this the only symptom is the bridge's generic
+    // auth failure.
+    if (token.length === 0) {
+      console.error(
+        ${missingExpr},
+      );
+    }
+    // Still attempt it — a bridge running without a token pairs fine.
+    reticle.connect({
+${connectFields}
+    });
+    // What the agent can drive without guessing.
+${registerCapabilitiesCall(options.testids ?? [], '    ')}
+  });
+}
+${trailer}`;
+}

package/dist/csp-check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Does this app's Content-Security-Policy let the browser reach the Reticle bridge?
+ *
+ * Two independent field reports, both Next: `init` reported every step successful, the SDK mounted,
+ * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
+ * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
+ * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
+ * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
+ * the worst failure mode this repo has.
+ *
+ * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
+ * without importing their whole app, and the thing worth finding is the policy string a developer
+ * typed — in `next.config.*`, in middleware, or in a `<meta http-equiv>` tag. The scan finds the
+ * string wherever it is written.
+ *
+ * NARROW on purpose: it fires only when a `connect-src` exists AND does not admit the bridge. No
+ * CSP, or one that already covers us, produces nothing. A warning that fires on a working setup
+ * costs precisely what a green check on a broken one costs, and this file exists because of the
+ * second kind.
+ */
+/**
+ * The problem with this app's `connect-src`, or undefined if there is not one.
+ *
+ * `https:` counts as a wildcard here only in the sense that a policy written that loosely will not
+ * be the thing blocking a dev WebSocket; the check stays quiet rather than arguing about it.
+ */
+export declare function cspConnectSrcProblem(text: string, port: number): string | undefined;
+/**
+ * The problem with this app's `script-src`, or undefined if there is not one.
+ *
+ * Reports the remedy that works under `'self'` — serve the connect code as an external module file —
+ * rather than telling anyone to weaken their policy with `'unsafe-inline'`.
+ */
+export declare function cspInlineScriptProblem(text: string, port: number): string | undefined;
+/** Where the external connect module goes, for an app served from a static directory. */
+export declare const EXTERNAL_CONNECT_PATH = "public/reticle-connect.js";
+/** The remedy that works under `script-src 'self'`, as text to copy. */
+export declare function externalScriptRemedy(): string;
+/** The exact addition to paste. Text to copy, not advice to interpret. */
+export declare function devCspAddition(port: number): string;
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export declare const CSP_STEP_TITLE = "Content-Security-Policy";
+/**
+ * The first blocking policy among the sources `init` already has in hand, or undefined.
+ *
+ * At most one finding: a second copy of the same policy in a second file is the same problem, and
+ * two identical notices read as two problems.
+ */
+export declare function cspPlanProblem(sources: readonly (string | null | undefined)[], port: number): string | undefined;