@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/astro-patch.js

@@ -0,0 +1,240 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+import { PatchKind } from './patch-kind.js';
+/** Present in a patched config AND in a hand-followed recipe — so both count as already wired. */
+const CONFIG_MARKER = '__RETICLE_TOKEN__';
+/** Present in a patched layout and in the printed recipe's script. */
+const LAYOUT_MARKER = 'reticle.connect';
+/**
+ * The SDK, declared so Vite pre-bundles it BEFORE the first page load.
+ *
+ * The connect script does `await import('@reticlehq/react')`. Undeclared, Vite meets that import
+ * mid-load, pre-bundles it, and the hashed `/node_modules/.vite/deps/@reticlehq_react.js?v=…` URL
+ * the browser already requested stops existing — the import rejects with "Failed to fetch
+ * dynamically imported module", connect() never runs, and the page looks entirely normal. Measured
+ * on astro-nanostores, intermittent on whether the dep cache was warm. The Vite plugin has declared
+ * the SDK for this exact reason since the bug was first found on React; Astro is hand-patched and
+ * never got it.
+ */
+const SDK_INCLUDE_LITERAL = `'@reticlehq/react'`;
+/**
+ * An `include:` the app already declared — ours joins that array instead of adding a second key.
+ * Deliberately not anchored to a newline: `optimizeDeps: { include: ['x'] }` on one line is the
+ * common way to write it, and requiring a line break made the merge miss it and duplicate the key.
+ */
+const EXISTING_INCLUDE = /(\s*include\s*:\s*\[)/;
+const DEFINE_CONFIG = /defineConfig\s*\(\s*\{/;
+/** A `vite:` key whose value is an object LITERAL — the one shape we can merge into safely. */
+const VITE_OBJECT_KEY = /(^\s*vite\s*:\s*\{)/m;
+/** Any `vite:` key at all. One that is not an object literal (a spread, an imported config) is ours to refuse. */
+const ANY_VITE_KEY = /^\s*vite\s*:/m;
+const BODY_CLOSE = '</body>';
+const HELPER = `
+function reticleToken() {
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+  try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+}
+`;
+const HELPER_IMPORTS = `import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+`;
+/**
+ * The keys we add inside `vite:`, each with what it must contain.
+ *
+ * Kept as a list rather than one blob because a config that already sets one of these must be merged
+ * INTO, not duplicated: the real astro-nanostores config has `build: { chunkSizeWarningLimit }`, and
+ * inserting our own `build` beside it gave the object two — where the last one wins, so
+ * `target: 'es2022'` was silently discarded while init reported success. Losing that target is not
+ * cosmetic: Astro's default down-levels the modern SDK bundle and dies on a destructuring transform.
+ */
+const VITE_KEYS = [
+    { key: 'build', inner: `\n      target: 'es2022',` },
+    {
+        key: 'optimizeDeps',
+        inner: `\n      include: [${SDK_INCLUDE_LITERAL}],\n      esbuildOptions: { target: 'es2022' },`,
+    },
+    {
+        key: 'define',
+        inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
+    },
+];
+/** Whole-key form, for a `vite:` block that does not have the key at all. */
+const WHOLE = {
+    build: `\n    build: { target: 'es2022' },`,
+    optimizeDeps: `\n    optimizeDeps: { include: [${SDK_INCLUDE_LITERAL}], esbuildOptions: { target: 'es2022' } },`,
+    define: `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`,
+};
+/**
+ * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
+ *
+ * Returns null when a colliding key is not an object literal (`build: sharedConfig`) — there is no
+ * brace to merge into, and duplicating or replacing it would corrupt someone's build.
+ */
+function mergeIntoViteBlock(source, braceAt) {
+    let out = source;
+    for (const { key, inner } of VITE_KEYS) {
+        // Scoped to the vite block by searching from its opening brace: a `build:` under `markdown:` or
+        // at the top level is somebody else's key and must not be touched.
+        const existing = new RegExp(`(\\n\\s*${key}\\s*:\\s*)([\\{A-Za-z_])`).exec(out.slice(braceAt));
+        if (existing?.index === undefined) {
+            out = `${out.slice(0, braceAt)}${WHOLE[key] ?? ''}${out.slice(braceAt)}`;
+            continue;
+        }
+        // The character after the colon decides: `{` is a literal we can open; anything else is a
+        // reference we must not touch.
+        if (existing[2] !== '{')
+            return null;
+        const at = braceAt + existing.index + existing[0].length; // just past the `{`
+        // An `include:` the app already wrote is an ARRAY, and a second `include:` key in the same
+        // object literal is not a merge — the last one wins and one of the two silently disappears.
+        // That is how `build.target` was lost while init still reported success. Join their array.
+        // Scoped to THIS block's braces: an `include:` under a later key is somebody else's array, and
+        // appending the SDK to it would both miss the target and edit a config we were not asked to.
+        const own = 'optimizeDeps' === key ? EXISTING_INCLUDE.exec(blockAfter(out, at)) : null;
+        if (own?.index === undefined) {
+            out = insertAt(out, at, inner);
+            continue;
+        }
+        // Their array first, then the rest of our keys at the block's start — inserting at the LOWER
+        // offset second keeps the first offset valid.
+        out = insertAt(out, at + own.index + own[0].length, `${SDK_INCLUDE_LITERAL}, `);
+        out = insertAt(out, at, withoutInclude(inner));
+    }
+    return out;
+}
+function insertAt(source, at, text) {
+    return `${source.slice(0, at)}${text}${source.slice(at)}`;
+}
+/**
+ * The text from just inside an opening brace to its match — a brace count, not a parser.
+ *
+ * Enough for the one question asked of it (does THIS object literal already declare `include`), and
+ * honest about its limit: a `{` or `}` inside a string literal in someone's Vite config would fool
+ * it. That only ever shortens or lengthens the window we search for `include:` in, so the worst case
+ * is the same duplicate-key merge we would have done before, never a corrupted file.
+ */
+function blockAfter(source, at) {
+    let depth = 1;
+    for (let i = at; i < source.length; i++) {
+        if ('{' === source[i])
+            depth += 1;
+        else if ('}' === source[i]) {
+            depth -= 1;
+            if (0 === depth)
+                return source.slice(at, i);
+        }
+    }
+    return source.slice(at);
+}
+/** The optimizeDeps inner minus our `include:` line, for when the app already has one to join. */
+function withoutInclude(inner) {
+    return inner.replace(`\n      include: [${SDK_INCLUDE_LITERAL}],`, '');
+}
+/**
+ * The `vite:` block Astro needs. `build.target` is raised because Astro's default down-levels the
+ * modern SDK bundle and dies on a destructuring transform; `__RETICLE_ROOT__` is defined because
+ * without it every source pointer comes back as an absolute path from the machine that ran `init`.
+ */
+const VITE_BLOCK = `  vite: {
+    build: { target: 'es2022' },
+    optimizeDeps: { include: [${SDK_INCLUDE_LITERAL}], esbuildOptions: { target: 'es2022' } },
+    define: {
+      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+      __RETICLE_ROOT__: JSON.stringify(process.cwd()),
+    },
+  },
+`;
+export function patchAstroConfig(source) {
+    if (source.includes(CONFIG_MARKER))
+        return { kind: PatchKind.ALREADY };
+    // A `vite: { ... }` block is an object literal, so our keys can go straight after the brace and
+    // whatever is already in there is untouched. Refusing outright was the only genuine install defect
+    // left in the gate: the config bailed while the LAYOUT patch applied anyway, leaving an app with a
+    // connect snippet, no inlined token and no raised build target — which cannot connect, reported as
+    // one OK step and one warning.
+    const viteObject = VITE_OBJECT_KEY.exec(source);
+    if (viteObject?.index !== undefined) {
+        const at = viteObject.index + viteObject[0].length;
+        const merged = mergeIntoViteBlock(source, at);
+        if (merged !== null) {
+            return {
+                kind: PatchKind.APPLY,
+                code: `${HELPER_IMPORTS}${merged.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+            };
+        }
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets a `vite` key Reticle needs (build / optimizeDeps / define) to something ' +
+                'other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    if (ANY_VITE_KEY.test(source)) {
+        // `vite: sharedConfig` — not an object literal, so there is no brace to merge into and guessing
+        // would corrupt a build config. The recipe is the honest answer here.
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets `vite:` to something other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    const opening = DEFINE_CONFIG.exec(source);
+    if (opening?.index === undefined) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a `defineConfig({ ... })` call to extend",
+        };
+    }
+    const at = opening.index + opening[0].length;
+    const withBlock = `${source.slice(0, at)}\n${VITE_BLOCK}${source.slice(at)}`;
+    return {
+        kind: PatchKind.APPLY,
+        code: `${HELPER_IMPORTS}${withBlock.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+    };
+}
+/** The dev-only connect that goes inside the layout's `<body>`. */
+function astroConnectScript(port, projectId) {
+    const url = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    return `    <script>
+      if (import.meta.env.DEV) {
+        const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+        const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+        const { reticle, install } = await import('@reticlehq/react');
+        install();
+        reticle.connect({${id}${url}
+          ...(token.length > 0 ? { token } : {}),
+          ...(root.length > 0 ? { root } : {}),
+        });
+      }
+    </script>
+`;
+}
+export function patchAstroLayout(source, port, projectId) {
+    if (source.includes(LAYOUT_MARKER))
+        return { kind: PatchKind.ALREADY };
+    const at = source.lastIndexOf(BODY_CLOSE);
+    if (at < 0) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a `</body>` to place the connect script before",
+        };
+    }
+    return {
+        kind: PatchKind.APPLY,
+        code: `${source.slice(0, at)}${astroConnectScript(port, projectId)}${source.slice(at)}`,
+    };
+}

package/dist/init/capabilities.js

@@ -35,7 +35,10 @@ export function scanTestids(sources) {
  */
 const STORE_LIBRARIES = [
     ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
-    ['zustand', "registerStore('app', useStore) // pass the store itself, not () => store.getState()"],
+    [
+        'zustand',
+        "registerStore('app', useStore) // pass the store itself, not () => store.getState()",
+    ],
     ['@reduxjs/toolkit', "registerStore('app', store)"],
     ['redux', "registerStore('app', store)"],
     ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],

package/dist/init/cra.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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`. Side-effect import: the module guards itself on NODE_ENV. */
+export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
+export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
+export declare const CRA_ENV_PATH = ".env.development.local";
+export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * 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): string | null;
+/** The dev-only connect module imported from `src/index.tsx`. */
+export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;

package/dist/init/cra.js

@@ -0,0 +1,106 @@
+/**
+ * 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`. Side-effect import: the module guards itself on NODE_ENV. */
+export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
+export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+export const CRA_ENV_PATH = '.env.development.local';
+export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
+/**
+ * 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 `npx reticle 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 `npx reticle 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) {
+    if ('' === token)
+        return null;
+    const line = `${TOKEN_VAR}=${token}`;
+    if (null === existing || '' === existing.trim())
+        return `${line}\n`;
+    if (existing.includes(line))
+        return null;
+    // Replace rather than append: two assignments of one variable is a silent coin flip on which wins.
+    if (new RegExp(`^${TOKEN_VAR}=`, 'm').test(existing)) {
+        return existing.replace(new RegExp(`^${TOKEN_VAR}=.*$`, 'm'), line);
+    }
+    return `${existing.endsWith('\n') ? existing : `${existing}\n`}${line}\n`;
+}
+/** The dev-only connect module imported from `src/index.tsx`. */
+export function craDevModuleFile(port, projectId) {
+    const fields = [];
+    if (port !== undefined)
+        fields.push(`url: 'ws://127.0.0.1:${String(port)}/reticle'`);
+    if (projectId !== undefined && projectId.length > 0)
+        fields.push(`projectId: '${projectId}'`);
+    const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
+    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(({ reticle, install }) => {
+    install();
+    const token = process.env.${TOKEN_VAR} ?? '';
+    // Loud on purpose: without this the only symptom is the bridge's generic auth failure.
+    if (token.length === 0) console.error(${JSON.stringify(`[reticle] ${CRA_TOKEN_MISSING_NOTE}`)});
+    // Still attempt it — a bridge running without a token pairs fine.
+    reticle.connect({ ${inline}...(token.length > 0 ? { token } : {}) });
+  });
+}
+
+export {};
+`;
+}

package/dist/init/cursor.js

@@ -5,6 +5,7 @@
  * (jsonc/comment) files bail to manual rather than being rewritten.
  */
 import { NPX, MCP_SERVER_NAME, npxServerArgs } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 /** Path of Cursor's global MCP config, relative to the user's home directory. */
 export const CURSOR_MCP_RELPATH = '.cursor/mcp.json';
 /** The directory whose presence signals Cursor is installed for this user. */
@@ -18,18 +19,47 @@ export function cursorServerEntry() {
     return { command: NPX, args: npxServerArgs() };
 }
 function parseConfig(existing) {
-    if (existing === null || existing.trim().length === 0)
+    if (null === existing || 0 === existing.trim().length)
         return { ok: true, config: {} };
     try {
         const parsed = JSON.parse(existing);
-        if (typeof parsed !== 'object' || parsed === null)
-            return { ok: true, config: {} };
+        // Valid JSON that is not a PLAIN OBJECT — `[]`, `3`, `"x"`, `null` — used to fall through to an
+        // empty config, and the file was then rewritten wholesale. Unparseable JSON was already handled
+        // conservatively; this adjacent case destroyed the file instead. Whatever is in there is the
+        // user's, and we do not understand it, so we do not touch it.
+        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed))
+            return { ok: false };
         return { ok: true, config: parsed };
     }
     catch {
         return { ok: false };
     }
 }
+/**
+ * Should this entry be left exactly as it is?
+ *
+ * Two different reasons to leave one alone, and only one of them is "it is correct":
+ *   - it already matches what we would write; or
+ *   - it is not an entry WE wrote. Somebody pointing `reticle` at their own local build is a
+ *     deliberate choice, and silently replacing it with the published npx command would break their
+ *     setup to fix a problem they do not have.
+ *
+ * What IS repaired is a stale entry of our own shape — an old pin, a command that has moved — which
+ * presence-only idempotency reported as "already registered" and never fixed, so an upgrade could
+ * not repair the thing an upgrade exists to repair.
+ */
+function leaveEntryAlone(existing) {
+    if (JSON.stringify(existing) === JSON.stringify(cursorServerEntry()))
+        return true;
+    if (typeof existing !== 'object' || null === existing)
+        return true;
+    const command = existing.command;
+    const args = existing.args;
+    const ours = command === NPX &&
+        Array.isArray(args) &&
+        args.some((arg) => 'string' === typeof arg && arg.includes(RETICLE_NPM_PACKAGE));
+    return !ours;
+}
 export function mergeCursorConfig(existing) {
     const parsed = parseConfig(existing);
     if (!parsed.ok) {
@@ -37,7 +67,12 @@ export function mergeCursorConfig(existing) {
     }
     const config = parsed.config;
     const servers = config.mcpServers ?? {};
-    if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME)) {
+    // Presence alone used to mean "already registered", so a `reticle` entry left by an older release —
+    // a command that no longer exists, or a stale pin — was reported done and never repaired. An
+    // upgrade could not fix a bad entry, which is exactly when it needs to. Only OUR key is replaced;
+    // every other server and top-level key is carried through untouched by the spread below.
+    if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME) &&
+        leaveEntryAlone(servers[MCP_SERVER_NAME])) {
         return { status: CursorMergeStatus.ALREADY, content: existing ?? '' };
     }
     const merged = {

package/dist/init/desktop-doctor.d.ts

@@ -23,7 +23,7 @@ export declare const DesktopFinding: {
     readonly ELECTRON_CAPTURE_MISSING: "electron-capture-missing";
 };
 export type DesktopFinding = (typeof DesktopFinding)[keyof typeof DesktopFinding];
-export interface DesktopDiagnosis {
+interface DesktopDiagnosis {
     code: DesktopFinding;
     /** Which file to look at. */
     file: string;
@@ -33,8 +33,9 @@ export interface DesktopDiagnosis {
     fix: string;
 }
 /** Reads a project-relative path. Undefined means the file does not exist. */
-export type ReadFile = (path: string) => string | undefined;
+type ReadFile = (path: string) => string | undefined;
 /** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
 export declare function isDesktopProject(read: ReadFile): boolean;
 /** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
 export declare function diagnoseDesktop(read: ReadFile, port: number): DesktopDiagnosis[];
+export {};

package/dist/init/desktop-doctor.js

@@ -31,7 +31,7 @@ function parseJson(text) {
         return undefined;
     try {
         const parsed = JSON.parse(text);
-        return typeof parsed === 'object' && parsed !== null
+        return 'object' === typeof parsed && parsed !== null
             ? parsed
             : undefined;
     }
@@ -40,7 +40,7 @@ function parseJson(text) {
     }
 }
 function record(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 /**
  * Does this CSP permit the bridge WebSocket on `port`?
@@ -72,7 +72,7 @@ function diagnoseTauri(read, port) {
     if (conf === undefined)
         return [];
     const security = record(record(conf['app'])['security']);
-    const csp = typeof security['csp'] === 'string' ? security['csp'] : undefined;
+    const csp = 'string' === typeof security['csp'] ? security['csp'] : undefined;
     const findings = [];
     if (!cspAllowsBridge(csp, port)) {
         findings.push({
@@ -193,6 +193,6 @@ export function diagnoseDesktop(read, port) {
     const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
     if (deps['electron'] === undefined)
         return [];
-    const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+    const main = 'string' === typeof pkg['main'] ? pkg['main'] : undefined;
     return main === undefined ? [] : diagnoseElectron(read, main);
 }

package/dist/init/detect.d.ts

@@ -7,6 +7,8 @@ export declare const Framework: {
     readonly VITE: "vite";
     readonly SVELTEKIT: "sveltekit";
     readonly ASTRO: "astro";
+    /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
+    readonly CRA: "cra";
     readonly HTML: "html";
 };
 export type Framework = (typeof Framework)[keyof typeof Framework];
@@ -60,8 +62,13 @@ export interface Detection {
 }
 /** Extract the leading major version from a semver range like "^19.0.0" or "19.1.1". */
 export declare function parseMajor(range: string | undefined): number | undefined;
-/** Marker basenames present inside the project's `node_modules`, if it has one. */
-export declare function packageManagerFromNodeModules(markers: ReadonlySet<string>): PackageManager | undefined;
+/**
+ * Whether an installed tree identifies the manager that built it. Callers use this to decide whether
+ * they still need weaker evidence — see `resolveLockfiles`, which stops inheriting an ancestor
+ * lockfile once the project's own tree can answer the question.
+ */
+export declare function namesAPackageManager(markers: ReadonlySet<string>): boolean;
+export declare function detectPackageManager(lockfiles: ReadonlySet<string>, nodeModulesMarkers: ReadonlySet<string>): PackageManager;
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;

package/dist/init/detect.js

@@ -7,6 +7,8 @@ export const Framework = {
     VITE: 'vite',
     SVELTEKIT: 'sveltekit',
     ASTRO: 'astro',
+    /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
+    CRA: 'cra',
     HTML: 'html',
 };
 export const PackageManager = {
@@ -30,7 +32,12 @@ export const UiLibrary = {
 const NEXT_CONFIGS = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'];
 const VITE_CONFIGS = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts'];
 const SVELTE_CONFIGS = ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'];
-const ASTRO_CONFIGS = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs'];
+const ASTRO_CONFIGS = [
+    'astro.config.mjs',
+    'astro.config.js',
+    'astro.config.ts',
+    'astro.config.cjs',
+];
 function depVersion(pkg, name) {
     return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name];
 }
@@ -42,7 +49,7 @@ export function parseMajor(range) {
     if (range === undefined)
         return undefined;
     const match = range.match(/(\d+)/);
-    if (match === null || match[1] === undefined)
+    if (null === match || match[1] === undefined)
         return undefined;
     const major = parseInt(match[1], 10);
     return isNaN(major) ? undefined : major;
@@ -62,13 +69,21 @@ const NODE_MODULES_MARKERS = [
     ['.package-lock.json', PackageManager.NPM],
 ];
 /** Marker basenames present inside the project's `node_modules`, if it has one. */
-export function packageManagerFromNodeModules(markers) {
+function packageManagerFromNodeModules(markers) {
     for (const [name, pm] of NODE_MODULES_MARKERS)
         if (markers.has(name))
             return pm;
     return undefined;
 }
-function detectPackageManager(lockfiles, nodeModulesMarkers) {
+/**
+ * Whether an installed tree identifies the manager that built it. Callers use this to decide whether
+ * they still need weaker evidence — see `resolveLockfiles`, which stops inheriting an ancestor
+ * lockfile once the project's own tree can answer the question.
+ */
+export function namesAPackageManager(markers) {
+    return packageManagerFromNodeModules(markers) !== undefined;
+}
+export function detectPackageManager(lockfiles, nodeModulesMarkers) {
     if (lockfiles.has('pnpm-lock.yaml'))
         return PackageManager.PNPM;
     if (lockfiles.has('yarn.lock'))
@@ -97,6 +112,10 @@ function detectFramework(input) {
     if (depVersion(pkg, 'vite') !== undefined || hasAnyConfig(configFiles, VITE_CONFIGS)) {
         return Framework.VITE;
     }
+    // Checked after Vite, never before: a project migrating off CRA can carry both, and the Vite path
+    // is the one that works. CRA has no config file at all, so the dependency is the only signal.
+    if (depVersion(pkg, 'react-scripts') !== undefined)
+        return Framework.CRA;
     return Framework.HTML;
 }
 /**
@@ -136,7 +155,7 @@ const INSTALL_ARGS = {
 };
 /** Build a dev-dependency install command for one or more packages (e.g. the kit + its build plugin). */
 export function installCommandParts(pm, pkgs) {
-    const list = typeof pkgs === 'string' ? [pkgs] : pkgs;
+    const list = 'string' === typeof pkgs ? [pkgs] : pkgs;
     return { command: pm, args: [...INSTALL_ARGS[pm], ...list] };
 }
 export function installCommand(pm, pkgs) {