@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/mcp-clients.d.ts

@@ -0,0 +1,81 @@
+export declare const McpClient: {
+    readonly CLAUDE_CODE: "claude-code";
+    readonly CURSOR: "cursor";
+    readonly WINDSURF: "windsurf";
+    readonly OPENCODE: "opencode";
+    readonly CODEX: "codex";
+    readonly GEMINI: "gemini";
+    readonly VSCODE: "vscode";
+};
+export type McpClient = (typeof McpClient)[keyof typeof McpClient];
+/** Where the config lives. `cli` means the client owns registration and we shell out to it. */
+export declare const ConfigScope: {
+    readonly HOME: "home";
+    readonly PROJECT: "project";
+    readonly CLI: "cli";
+};
+export type ConfigScope = (typeof ConfigScope)[keyof typeof ConfigScope];
+/** How the file is written. `toml` is deliberately never auto-merged — see mergeClientConfig. */
+export declare const ConfigFormat: {
+    readonly JSON: "json";
+    readonly TOML: "toml";
+    readonly CLI: "cli";
+};
+export type ConfigFormat = (typeof ConfigFormat)[keyof typeof ConfigFormat];
+export interface ClientSpec {
+    id: McpClient;
+    label: string;
+    scope: ConfigScope;
+    /** Relative to `$HOME` for `home`, to the project root for `project`. Empty for `cli`. */
+    relPath: string;
+    format: ConfigFormat;
+    /** The object key holding the server map — `mcpServers`, `servers`, or `mcp`. */
+    serversKey: string;
+    /** Our entry, in THIS client's shape. */
+    entry: () => unknown;
+    /** Where the shape came from, so the next person can re-check it rather than trust this file. */
+    docs: string;
+}
+export declare const MCP_CLIENTS: readonly ClientSpec[];
+export declare function clientSpec(id: McpClient): ClientSpec;
+export declare const ClientMergeStatus: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type ClientMergeStatus = (typeof ClientMergeStatus)[keyof typeof ClientMergeStatus];
+export interface ClientMergeResult {
+    status: ClientMergeStatus;
+    /** Full file content to write. Byte-identical to `existing` when not `apply`. */
+    content: string;
+}
+/**
+ * Merge our server into this client's config.
+ *
+ * TOML is never auto-merged. Editing TOML without a parser is how a config file gets corrupted, and
+ * a corrupted `~/.codex/config.toml` costs the user every server they had, not just ours. Printing
+ * the exact block is honest; writing a guess is not — so Codex returns MANUAL with a snippet.
+ */
+export declare function mergeClientConfig(spec: ClientSpec, existing: string | null): ClientMergeResult;
+/**
+ * A block the user can paste, for a client we could not write.
+ *
+ * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
+ * file could not be parsed, the snippet is the only actionable thing left to give.
+ */
+export declare function clientSnippet(spec: ClientSpec): string;
+/**
+ * The path whose existence means "this user has this client".
+ *
+ * Detection is deliberately conservative and one-directional: we write into a config a client
+ * ALREADY has, and never create `~/.gemini/` or `~/.codeium/` for somebody who does not use them.
+ * Littering a home directory to register a server nobody asked for is worse than printing a snippet.
+ *
+ * For a `home` client this is the directory above its config; for a `project` client it is the
+ * config file (or its directory) inside the repo, which is unambiguous evidence somebody uses it
+ * here. Same reasoning as Cursor's existing rule, which also accepts a project-level `.cursor/`
+ * because a fresh Cursor profile has not written `~/.cursor` yet.
+ */
+export declare function clientMarkerRelPath(spec: ClientSpec): string;
+/** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
+export declare function fileBackedClients(): readonly ClientSpec[];

package/dist/init/mcp-clients.js

@@ -0,0 +1,248 @@
+/**
+ * Where each agent keeps its MCP config, and how to write ours into it.
+ *
+ * `init` knew two clients: Claude Code (a CLI shell-out) and Cursor (a JSON merge). Everything else
+ * got a printed snippet. That is the blocker under the whole release matrix — a per-client release
+ * artifact for a client `init` cannot wire measures whether somebody pasted JSON correctly, not
+ * whether the product works.
+ *
+ * Every path and shape below was read from the client's own documentation rather than recalled,
+ * because they differ in ways that look like they should not:
+ *
+ *   Cursor / Windsurf / Gemini   `mcpServers: { name: { command, args } }` — one shape, three paths
+ *   VS Code                      `servers:` — a different key entirely
+ *   OpenCode                     `mcp: { name: { type, command: [cmd, ...args] } }` — an ARRAY
+ *   Codex                        TOML
+ *
+ * A single "write mcp.json" assuming the Cursor shape would produce a file three of these ignore:
+ * an install that reports success and registers nothing, which is the exact failure class this
+ * repo's install gate exists to catch.
+ */
+import { NPX, MCP_SERVER_NAME, npxServerArgs } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
+export const McpClient = {
+    CLAUDE_CODE: 'claude-code',
+    CURSOR: 'cursor',
+    WINDSURF: 'windsurf',
+    OPENCODE: 'opencode',
+    CODEX: 'codex',
+    GEMINI: 'gemini',
+    VSCODE: 'vscode',
+};
+/** Where the config lives. `cli` means the client owns registration and we shell out to it. */
+export const ConfigScope = {
+    HOME: 'home',
+    PROJECT: 'project',
+    CLI: 'cli',
+};
+/** How the file is written. `toml` is deliberately never auto-merged — see mergeClientConfig. */
+export const ConfigFormat = {
+    JSON: 'json',
+    TOML: 'toml',
+    CLI: 'cli',
+};
+/** The `{ command, args }` entry Cursor, Windsurf, Gemini and VS Code all take. */
+function commandArgsEntry() {
+    return { command: NPX, args: npxServerArgs() };
+}
+/**
+ * OpenCode's entry. `command` is a single ARRAY containing the executable and its arguments, and
+ * `enabled` is explicit — a server registered but disabled is the quietest possible failure.
+ */
+function openCodeEntry() {
+    return { type: 'local', command: [NPX, ...npxServerArgs()], enabled: true };
+}
+export const MCP_CLIENTS = [
+    {
+        id: McpClient.CLAUDE_CODE,
+        label: 'Claude Code',
+        scope: ConfigScope.CLI,
+        relPath: '',
+        format: ConfigFormat.CLI,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'registered via `claude mcp add -s user` — see init/mcp.ts',
+    },
+    {
+        id: McpClient.CURSOR,
+        label: 'Cursor',
+        scope: ConfigScope.HOME,
+        relPath: '.cursor/mcp.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'https://docs.cursor.com — global ~/.cursor/mcp.json, or ./.cursor/mcp.json per project',
+    },
+    {
+        id: McpClient.WINDSURF,
+        label: 'Windsurf',
+        scope: ConfigScope.HOME,
+        relPath: '.codeium/windsurf/mcp_config.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'Windsurf docs — ~/.codeium/windsurf/mcp_config.json (same shape as Cursor, different path)',
+    },
+    {
+        id: McpClient.GEMINI,
+        label: 'Gemini CLI',
+        scope: ConfigScope.HOME,
+        relPath: '.gemini/settings.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html',
+    },
+    {
+        id: McpClient.VSCODE,
+        label: 'VS Code (Copilot)',
+        scope: ConfigScope.PROJECT,
+        relPath: '.vscode/mcp.json',
+        format: ConfigFormat.JSON,
+        // NOT `mcpServers`. Writing that key here registers nothing and reports success.
+        serversKey: 'servers',
+        entry: commandArgsEntry,
+        docs: 'VS Code MCP docs — .vscode/mcp.json, key is `servers`',
+    },
+    {
+        id: McpClient.OPENCODE,
+        label: 'OpenCode',
+        scope: ConfigScope.PROJECT,
+        relPath: 'opencode.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcp',
+        entry: openCodeEntry,
+        docs: 'https://opencode.ai/docs/config — `mcp` key, type:"local", command is an array',
+    },
+    {
+        id: McpClient.CODEX,
+        label: 'Codex CLI',
+        scope: ConfigScope.HOME,
+        relPath: '.codex/config.toml',
+        format: ConfigFormat.TOML,
+        serversKey: 'mcp_servers',
+        entry: commandArgsEntry,
+        docs: 'https://developers.openai.com/codex/mcp — ~/.codex/config.toml, [mcp_servers.<name>]',
+    },
+];
+export function clientSpec(id) {
+    const found = MCP_CLIENTS.find((spec) => spec.id === id);
+    if (found === undefined)
+        throw new Error(`no MCP client spec for '${id}'`);
+    return found;
+}
+export const ClientMergeStatus = {
+    APPLY: 'apply',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+};
+function parseConfig(existing) {
+    if (null === existing || 0 === existing.trim().length)
+        return { ok: true, config: {} };
+    try {
+        const parsed = JSON.parse(existing);
+        // Valid JSON that is not a PLAIN OBJECT — `[]`, `3`, `"x"`, `null` — must not fall through to an
+        // empty config, because the file then gets rewritten wholesale. Unparseable JSON was always
+        // handled conservatively; this adjacent case destroyed the file instead.
+        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 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 made a
+ *     deliberate choice, and replacing it with the published npx command breaks a setup to fix a
+ *     problem they do not have.
+ *
+ * What IS repaired is a stale entry of our own shape — an old pin, a moved command — 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, spec) {
+    if (JSON.stringify(existing) === JSON.stringify(spec.entry()))
+        return true;
+    if (typeof existing !== 'object' || null === existing)
+        return true;
+    const record = existing;
+    // Both shapes carry the package name somewhere in a string; find it without assuming which field.
+    const tokens = [record.command, record.args].flat().filter((v) => 'string' === typeof v);
+    const ours = tokens.some((t) => t === NPX) && tokens.some((t) => t.includes(RETICLE_NPM_PACKAGE));
+    return !ours;
+}
+/**
+ * Merge our server into this client's config.
+ *
+ * TOML is never auto-merged. Editing TOML without a parser is how a config file gets corrupted, and
+ * a corrupted `~/.codex/config.toml` costs the user every server they had, not just ours. Printing
+ * the exact block is honest; writing a guess is not — so Codex returns MANUAL with a snippet.
+ */
+export function mergeClientConfig(spec, existing) {
+    if (spec.format !== ConfigFormat.JSON) {
+        return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
+    }
+    const parsed = parseConfig(existing);
+    if (!parsed.ok)
+        return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
+    const config = parsed.config;
+    const current = config[spec.serversKey];
+    const servers = 'object' === typeof current && null !== current && !Array.isArray(current)
+        ? current
+        : {};
+    if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME) &&
+        leaveEntryAlone(servers[MCP_SERVER_NAME], spec)) {
+        return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
+    }
+    // Only OUR key is replaced; every other server and top-level key is carried through untouched.
+    const merged = {
+        ...config,
+        [spec.serversKey]: { ...servers, [MCP_SERVER_NAME]: spec.entry() },
+    };
+    return { status: ClientMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
+}
+/**
+ * A block the user can paste, for a client we could not write.
+ *
+ * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
+ * file could not be parsed, the snippet is the only actionable thing left to give.
+ */
+export function clientSnippet(spec) {
+    if (spec.format === ConfigFormat.TOML) {
+        const args = npxServerArgs()
+            .map((a) => `"${a}"`)
+            .join(', ');
+        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "${NPX}"\nargs = [${args}]\n`;
+    }
+    if (spec.format === ConfigFormat.CLI) {
+        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${NPX} ${npxServerArgs().join(' ')}\n`;
+    }
+    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry() } }, null, 2)}\n`;
+}
+/**
+ * The path whose existence means "this user has this client".
+ *
+ * Detection is deliberately conservative and one-directional: we write into a config a client
+ * ALREADY has, and never create `~/.gemini/` or `~/.codeium/` for somebody who does not use them.
+ * Littering a home directory to register a server nobody asked for is worse than printing a snippet.
+ *
+ * For a `home` client this is the directory above its config; for a `project` client it is the
+ * config file (or its directory) inside the repo, which is unambiguous evidence somebody uses it
+ * here. Same reasoning as Cursor's existing rule, which also accepts a project-level `.cursor/`
+ * because a fresh Cursor profile has not written `~/.cursor` yet.
+ */
+export function clientMarkerRelPath(spec) {
+    if (spec.scope === ConfigScope.CLI)
+        return '';
+    const parts = spec.relPath.split('/');
+    return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
+}
+/** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
+export function fileBackedClients() {
+    return MCP_CLIENTS.filter((spec) => spec.scope !== ConfigScope.CLI);
+}

package/dist/init/mcp-registered.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Did `reticle init` actually register the MCP server?
+ *
+ * This was `!failed.has(MCP_TARGET)` — the negation of one narrow failure set — so a step that was
+ * SKIPPED (`--no-mcp`) or left MANUAL (the user has to run a command themselves) reported success,
+ * because neither is a failure. Under `--no-mcp` every run claimed registration.
+ *
+ * It is the onboarding funnel's most important field, and it was wrong in the flattering direction
+ * on exactly the runs least likely to have a working install.
+ */
+import { StepStatus } from './plan.js';
+export declare function wasMcpRegistered(status: StepStatus | undefined): boolean;

package/dist/init/mcp-registered.js

@@ -0,0 +1,14 @@
+/**
+ * Did `reticle init` actually register the MCP server?
+ *
+ * This was `!failed.has(MCP_TARGET)` — the negation of one narrow failure set — so a step that was
+ * SKIPPED (`--no-mcp`) or left MANUAL (the user has to run a command themselves) reported success,
+ * because neither is a failure. Under `--no-mcp` every run claimed registration.
+ *
+ * It is the onboarding funnel's most important field, and it was wrong in the flattering direction
+ * on exactly the runs least likely to have a working install.
+ */
+import { StepStatus } from './plan.js';
+export function wasMcpRegistered(status) {
+    return status === StepStatus.APPLY || status === StepStatus.ALREADY;
+}

package/dist/init/mcp.d.ts

@@ -12,9 +12,34 @@
  * global agent config.
  */
 export declare const MCP_SERVER_NAME = "reticle";
+/**
+ * The registered command is STILL bare `npx` on every platform, deliberately.
+ *
+ * Windows is 66% of Reticle's users (65 of 99 in a day of telemetry) and has NO CI, no fixture, and
+ * nothing in this repo has ever run there. Switching the majority platform to a launch command
+ * nobody can test — where `.cmd` also has its own spawn caveats in some hosts — risks breaking the
+ * users it is meant to help. So the fallback is DOCUMENTED (see mcpManual) rather than defaulted,
+ * until somebody can run it on Windows.
+ */
 export declare const NPX = "npx";
-/** Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
- * the project's `.reticle.json` at runtime, so one global entry works for every project. */
+/**
+ * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
+ * the project's `.reticle.json` at runtime, so one global entry works for every project.
+ *
+ * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
+ * exact version, so on release day the app can be on the new one while npx serves a cached older
+ * build — a real skew, reported from the field. Pinning this entry would remove that window.
+ *
+ * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
+ * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
+ * config. Reticle's biggest measured problem is fixes not reaching people (2.4.0 reached zero users
+ * before its nudge existed), and a permanent pin makes that worse for every install, to close a
+ * window that lasts until the next npx cache miss.
+ *
+ * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
+ * shape is now repaired on re-run rather than reported "already registered" (see cursor.ts).
+ */
 export declare function npxServerArgs(): string[];
 interface ClaudeAddCommand {
     command: string;

package/dist/init/mcp.js

@@ -11,16 +11,41 @@
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
-import { RETICLE_NPM_PACKAGE } from '../server-version.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 export const MCP_SERVER_NAME = 'reticle';
+/**
+ * The registered command is STILL bare `npx` on every platform, deliberately.
+ *
+ * Windows is 66% of Reticle's users (65 of 99 in a day of telemetry) and has NO CI, no fixture, and
+ * nothing in this repo has ever run there. Switching the majority platform to a launch command
+ * nobody can test — where `.cmd` also has its own spawn caveats in some hosts — risks breaking the
+ * users it is meant to help. So the fallback is DOCUMENTED (see mcpManual) rather than defaulted,
+ * until somebody can run it on Windows.
+ */
 export const NPX = 'npx';
 // The `reticle` bin lives in the server package, so `npx <pkg> mcp` runs the bridge without the
 // retired `core` umbrella. Sourced from the single derived identity so it can never drift.
 const RETICLE_PACKAGE = RETICLE_NPM_PACKAGE;
 const MCP_SUBCOMMAND = 'mcp';
 const CLAUDE_CLI = 'claude';
-/** Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
- * the project's `.reticle.json` at runtime, so one global entry works for every project. */
+/**
+ * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
+ * the project's `.reticle.json` at runtime, so one global entry works for every project.
+ *
+ * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
+ * exact version, so on release day the app can be on the new one while npx serves a cached older
+ * build — a real skew, reported from the field. Pinning this entry would remove that window.
+ *
+ * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
+ * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
+ * config. Reticle's biggest measured problem is fixes not reaching people (2.4.0 reached zero users
+ * before its nudge existed), and a permanent pin makes that worse for every install, to close a
+ * window that lasts until the next npx cache miss.
+ *
+ * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
+ * shape is now repaired on re-run rather than reported "already registered" (see cursor.ts).
+ */
 export function npxServerArgs() {
     return [RETICLE_PACKAGE, MCP_SUBCOMMAND];
 }
@@ -36,6 +61,11 @@ export function claudeAddCommand() {
 }
 /** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
 export function claudeExistsProbe() {
+    // NO `-s`: `claude mcp get` takes no options at all, so passing one exits 1 with "unknown option
+    // '-s'" — the probe answered "not registered" on EVERY machine, init then ran `claude mcp add`,
+    // which exits 1 with "already exists", and a re-run reported `[⚠] step failed` plus a manual
+    // command that fails the same way. A false positive from a project-scoped entry costs one skipped
+    // registration; the flag cost every re-run a failed step.
     return { command: CLAUDE_CLI, args: [MCP_SUBCOMMAND, 'get', MCP_SERVER_NAME] };
 }
 /** Probe args for whether the `claude` CLI is installed at all. */
@@ -51,5 +81,11 @@ export function mcpManual() {
 
 Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
 
-  "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }`;
+  "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }
+
+On Windows, if the agent cannot start Reticle because npx is blocked ("running scripts is disabled
+on this system" — a PowerShell execution policy), register it through cmd instead, which that policy
+does not gate:
+
+  "${MCP_SERVER_NAME}": { "command": "cmd", "args": ${JSON.stringify(['/c', NPX, ...serverInvocation().slice(1)])} }`;
 }

package/dist/init/next-patch.d.ts

@@ -6,11 +6,8 @@
  * skipped, and one of them is JSX.
  */
 import { type SourcePatch } from './patch-kind.js';
-export declare const NEXT_CONFIG_IMPORT = "import { withReticle } from '@reticlehq/next';";
-export declare const NEXT_CONFIG_REQUIRE = "const { withReticle } = require('@reticlehq/next');";
-export declare const RETICLE_DEV_IMPORT: string;
 /** Where the generated connect component goes, and how the mount file should import it. */
-export interface ReticleDevLocation {
+interface ReticleDevLocation {
     /** Project-relative path to write. */
     path: string;
     /** What the mount file (`app/layout.*` or `pages/_app.*`) should import. */
@@ -39,3 +36,4 @@ export declare function patchNextConfig(source: string): SourcePatch;
  */
 export declare function patchPagesApp(source: string, importSpecifier?: string): SourcePatch;
 export declare function patchRootLayout(source: string): SourcePatch;
+export {};

package/dist/init/next-patch.js

@@ -7,14 +7,14 @@
  */
 import { PatchKind } from './patch-kind.js';
 const RETICLE_NEXT_PACKAGE = '@reticlehq/next';
-export const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
-export const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
+const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
+const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
 const RETICLE_DEV_COMPONENT = 'ReticleDev';
 const RETICLE_DEV_BASENAME = 'reticle-dev';
 /** Default import specifier: the component sits beside the file importing it (App Router). */
 const RETICLE_DEV_SIBLING = `./${RETICLE_DEV_BASENAME}`;
 const reticleDevImport = (specifier) => `import { ${RETICLE_DEV_COMPONENT} } from '${specifier}';`;
-export const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
+const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
 /**
  * Decide where the connect component lives, from the file that will mount it.
  *
@@ -31,11 +31,11 @@ export const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
 export function reticleDevLocation(mountPath, typescript) {
     const ext = typescript ? '.tsx' : '.jsx';
     const slash = mountPath.lastIndexOf('/');
-    const dir = slash === -1 ? '' : mountPath.slice(0, slash);
+    const dir = -1 === slash ? '' : mountPath.slice(0, slash);
     const isPagesRouter = /(^|\/)pages$/.test(dir);
     if (!isPagesRouter) {
         return {
-            path: `${dir === '' ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
+            path: `${'' === dir ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
             importSpecifier: RETICLE_DEV_SIBLING,
         };
     }
@@ -48,26 +48,116 @@ export function reticleDevLocation(mountPath, typescript) {
 }
 /** The dev-guarded mount. Production strips it — `process.env.NODE_ENV` is inlined at build time. */
 const RETICLE_DEV_MOUNT = `{process.env.NODE_ENV === 'development' ? <${RETICLE_DEV_COMPONENT} /> : null}`;
-/** `export default <expr>;` — the ESM shape every `create-next-app` config uses. */
-const ESM_DEFAULT_EXPORT = /export\s+default\s+([\s\S]+?);?\s*$/;
-/** `module.exports = <expr>;` — the CJS shape older configs use. */
-const CJS_EXPORT = /module\.exports\s*=\s*([\s\S]+?);?\s*$/;
+/**
+ * `export default ` / `module.exports = ` at the START of a line — the head of the assignment, not
+ * the whole statement. Where the exported expression ENDS is decided by `expressionEnd` below.
+ *
+ * These used to be `/…([\s\S]+?);?\s*$/`, which reads as "the expression, lazily". It is not: with
+ * no `m` flag the `$` is end-of-FILE and the trailing `;?\s*` is satisfiable only there, so the
+ * capture always ran to the last non-blank character of the file. Every config whose export was not
+ * the final statement got everything after it swallowed into the wrap. On a config exporting
+ * conditionally that produced an unbalanced paren — a syntax error, so `next dev` exited 1 while
+ * `init` reported the step as ✓ and the only symptom was "dev server never served".
+ */
+const ESM_DEFAULT_HEAD = /^[ \t]*export[ \t]+default[ \t]+/gm;
+const CJS_EXPORT_HEAD = /^[ \t]*module\.exports[ \t]*=[ \t]*/gm;
 /** The opening `<body ...>` tag, whose first child is where the mount goes. */
 const BODY_OPEN_TAG = /<body(\s[^>]*)?>/g;
 const NO_EXPORT_REASON = "couldn't find an `export default` or `module.exports` to wrap";
 const NO_BODY_REASON = "couldn't find a single <body> tag to mount <ReticleDev /> inside";
+/** Bracket pairs that keep an expression open. A `;` at depth 0 is what ends it. */
+const OPENERS = '([{';
+const CLOSERS = ')]}';
+const LINE_COMMENT = '//';
+const BLOCK_COMMENT_OPEN = '/*';
+const BLOCK_COMMENT_CLOSE = '*/';
+const QUOTES = '\'"`';
+/**
+ * Index just past the exported expression that starts at `from` — the `;` that closes it, or end of
+ * file. Tracks bracket depth so a multi-line object or a nested call ends in the right place, and
+ * skips strings and comments so a `;` or a brace inside one cannot end it early.
+ *
+ * Deliberately a scanner and not a parser: `next.config.*` is arbitrary JS and this file's contract
+ * is to recognise the obvious shape or bail. It only has to be right about where ONE expression
+ * stops, and wrong is caught by the caller bailing to manual, never by a half-edit.
+ */
+function expressionEnd(source, from) {
+    let depth = 0;
+    for (let i = from; i < source.length; i++) {
+        const ch = source[i] ?? '';
+        const pair = source.slice(i, i + 2);
+        if (pair === LINE_COMMENT) {
+            const nl = source.indexOf('\n', i);
+            if (-1 === nl)
+                return source.length;
+            i = nl;
+            continue;
+        }
+        if (pair === BLOCK_COMMENT_OPEN) {
+            const close = source.indexOf(BLOCK_COMMENT_CLOSE, i + 2);
+            i = -1 === close ? source.length : close + 1;
+            continue;
+        }
+        if (QUOTES.includes(ch)) {
+            for (i++; i < source.length; i++) {
+                if ('\\' === source[i])
+                    i++;
+                else if (source[i] === ch)
+                    break;
+            }
+            continue;
+        }
+        if (OPENERS.includes(ch))
+            depth++;
+        else if (CLOSERS.includes(ch)) {
+            // A closer at depth 0 belongs to an enclosing block, so the expression ended before it.
+            if (0 === depth)
+                return i;
+            depth--;
+        }
+        else if (';' === ch && 0 === depth)
+            return i;
+    }
+    return source.length;
+}
+/** Every top-level export assignment in the file, in source order. */
+function exportSites(source, head) {
+    const sites = [];
+    for (const match of source.matchAll(head)) {
+        if (match.index === undefined)
+            continue;
+        const start = match.index + match[0].length;
+        sites.push({ start, end: expressionEnd(source, start) });
+    }
+    return sites;
+}
+/**
+ * Wrap every listed expression in `withReticle(...)`, leaving every other byte of the file alone.
+ *
+ * All of them, not just the first: a config can export CONDITIONALLY — Sentry-wrapped in one branch,
+ * plain in the other — and which branch runs is an environment variable's business, not ours.
+ * Wrapping each assignment is correct whichever one executes, and it is what turns that shape from a
+ * manual step (an app that boots and never connects) into a working install.
+ *
+ * Applied back-to-front so each splice leaves the earlier offsets valid.
+ */
+function wrapAll(source, sites) {
+    let out = source;
+    for (const site of [...sites].sort((a, b) => b.start - a.start)) {
+        out = `${out.slice(0, site.start)}withReticle(${out.slice(site.start, site.end)})${out.slice(site.end)}`;
+    }
+    return out;
+}
 export function patchNextConfig(source) {
     if (source.includes(RETICLE_NEXT_PACKAGE))
         return { kind: PatchKind.ALREADY };
-    const esm = ESM_DEFAULT_EXPORT.exec(source);
-    if (esm?.[1] !== undefined) {
-        const wrapped = source.replace(ESM_DEFAULT_EXPORT, `export default withReticle(${esm[1]});\n`);
-        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_IMPORT}\n${wrapped}` };
+    const esm = exportSites(source, ESM_DEFAULT_HEAD);
+    if (esm.length > 0) {
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_IMPORT}\n${wrapAll(source, esm)}` };
     }
-    const cjs = CJS_EXPORT.exec(source);
-    if (cjs?.[1] !== undefined) {
-        const wrapped = source.replace(CJS_EXPORT, `module.exports = withReticle(${cjs[1]});\n`);
-        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_REQUIRE}\n${wrapped}` };
+    const cjs = exportSites(source, CJS_EXPORT_HEAD);
+    if (cjs.length > 0) {
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_REQUIRE}\n${wrapAll(source, cjs)}` };
     }
     return { kind: PatchKind.MANUAL, reason: NO_EXPORT_REASON };
 }
@@ -84,7 +174,7 @@ export function patchPagesApp(source, importSpecifier = RETICLE_DEV_SIBLING) {
     if (source.includes(RETICLE_DEV_COMPONENT))
         return { kind: PatchKind.ALREADY };
     const matches = [...source.matchAll(PAGES_APP_COMPONENT)];
-    const match = matches.length === 1 ? matches[0] : undefined;
+    const match = 1 === matches.length ? matches[0] : undefined;
     if (match?.index === undefined)
         return { kind: PatchKind.MANUAL, reason: NO_PAGES_COMPONENT_REASON };
     const wrapped = `<>${RETICLE_DEV_MOUNT}${match[0]}</>`;
@@ -97,7 +187,7 @@ export function patchRootLayout(source) {
     const tags = [...source.matchAll(BODY_OPEN_TAG)];
     // Exactly one <body> or we cannot tell which one actually renders — and mounting into the wrong
     // one is the same silent no-connect as not mounting at all.
-    const tag = tags.length === 1 ? tags[0] : undefined;
+    const tag = 1 === tags.length ? tags[0] : undefined;
     if (tag?.index === undefined)
         return { kind: PatchKind.MANUAL, reason: NO_BODY_REASON };
     const insertAt = tag.index + tag[0].length;