@reticlehq/server 2.5.0 → 2.7.0

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/node-io.js

@@ -8,6 +8,7 @@ import { NodePlatform } from '../platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { windowsShellArg } from './windows-quote.js';
 /**
  * `shell: true` ONLY where it earns its keep.
  *
@@ -19,11 +20,16 @@ import { spawnSync } from 'node:child_process';
 function shellOpt() {
     return NodePlatform.WINDOWS === process.platform ? { shell: true } : {};
 }
-/** Under a shell, quote what the shell would otherwise split. Windows only, where shell is required. */
+/**
+ * Under a shell, quote what the shell would otherwise split or interpret. Windows only, where
+ * `shell: true` is required (see shellOpt). The rule itself lives in windows-quote.ts as a pure
+ * function so it can be tested on every platform — keeping it inside this branch is why it was
+ * wrong for as long as it was.
+ */
 function shellSafe(args) {
     if (process.platform !== NodePlatform.WINDOWS)
         return [...args];
-    return args.map((arg) => (/[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg));
+    return args.map(windowsShellArg);
 }
 export function buildNodeIo(cwd) {
     // Project-relative by default; absolute paths (e.g. ~/.cursor/mcp.json) pass through unchanged.

package/dist/init/non-js-project.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** The ecosystem this directory looks like, or undefined when nothing says. */
+export declare function detectNonJsEcosystem(exists: (file: string) => boolean): string | undefined;
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export declare function noPackageJsonMessage(exists: (file: string) => boolean): string;

package/dist/init/non-js-project.js

@@ -0,0 +1,60 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** Marker files that identify an ecosystem, and what to call it. */
+const ECOSYSTEM_MARKERS = [
+    ['requirements.txt', 'Python'],
+    ['pyproject.toml', 'Python'],
+    ['Pipfile', 'Python'],
+    ['setup.py', 'Python'],
+    ['manage.py', 'Python (Django)'],
+    ['Gemfile', 'Ruby'],
+    ['go.mod', 'Go'],
+    ['composer.json', 'PHP'],
+    ['Cargo.toml', 'Rust'],
+    ['pom.xml', 'Java'],
+    ['build.gradle', 'Java'],
+    ['mix.exs', 'Elixir'],
+];
+/** The ecosystem this directory looks like, or undefined when nothing says. */
+export function detectNonJsEcosystem(exists) {
+    for (const [marker, name] of ECOSYSTEM_MARKERS) {
+        if (exists(marker))
+            return name;
+    }
+    return undefined;
+}
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export function noPackageJsonMessage(exists) {
+    const ecosystem = detectNonJsEcosystem(exists);
+    if (ecosystem === undefined) {
+        return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
+            "your app's directory, or from a repo root that contains it.");
+    }
+    return (`This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
+        'directory beneath it. Reticle instruments a page by having its SDK imported into the app’s own ' +
+        'JavaScript build — so a server-rendered app with no JS build has nowhere to load it from, and ' +
+        'there is no directory you could run this from that would change that. ' +
+        'If this project does have a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
+        'its own package.json), run `reticle init` there, or point at it with `--app <dir>`.');
+}

package/dist/init/plan-framework.d.ts

@@ -38,6 +38,15 @@ export declare function nextSteps(input: PlanInput): Step[];
  * bundler never processes for modules. Reported from a real cra-redux-saga app.
  */
 export declare function craSteps(input: PlanInput): Step[];
+/**
+ * Nuxt: one manual step carrying the whole recipe, and no pretence of more.
+ *
+ * There is no Nuxt app in `apps/` and no CI gate for one, so an auto-written plugin would be a
+ * support claim nothing backs — the same reasoning SvelteKit already carries. What this DOES fix is
+ * everything that made the previous fall-through actively wrong: Nuxt was classified as `html`, so
+ * it was handed the React kit and a localhost-guarded snippet that cannot run in a Vue app.
+ */
+export declare function nuxtSteps(input: PlanInput): Step[];
 export declare function svelteKitSteps(input: PlanInput): Step[];
 /**
  * Astro: the config define + build target, and the connect script in ONE layout.

package/dist/init/plan-framework.js

@@ -6,9 +6,9 @@
 import { patchViteConfig, VitePatchKind } from './vite-config.js';
 import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js';
 import { patchAstroConfig, patchAstroLayout } from './astro-patch.js';
-import { CRA_DEV_MODULE_IMPORT, CRA_DEV_MODULE_PATH, CRA_ENV_PATH, TOKEN_VAR, craDevModuleFile, craEnvPatch, craImportPatch, } from './cra.js';
+import { CRA_DEV_MODULE_IMPORT, CRA_DEV_MODULE_PATH, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craEnvPatch, craImportPatch, } from './cra.js';
 import { PatchKind } from './patch-kind.js';
-import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, } from './snippets.js';
+import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, nuxtManual, NUXT_PLUGIN_PATH, } from './snippets.js';
 import { StepStatus } from './plan.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
@@ -46,6 +46,7 @@ function capabilitiesStep(input) {
     const found = testids.length > 0
         ? `${String(testids.length)} data-testid values`
         : 'no data-testid values yet';
+    const nothingToRegister = 0 === testids.length && 0 === stores.length;
     return [
         {
             title: CAPABILITIES_TITLE,
@@ -55,6 +56,28 @@ function capabilitiesStep(input) {
             write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
             dependsOnInstall: true,
         },
+        // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
+        // stores: [] })` registers nothing, so `hasCapabilities` stays false — correctly — and the ✓
+        // above reads as if the feature is on. Reported as exactly that confusion: "hasCapabilities false
+        // on every session while init said ✓ Capabilities + store".
+        //
+        // Beside the write rather than replacing it, for two reasons: only APPLY steps are written
+        // (run.ts), and SKILL.md tells the reader to skip ✓ lines — so a caveat carried on the ✓ is a
+        // caveat nobody reads.
+        ...(nothingToRegister
+            ? [
+                {
+                    title: 'Capabilities are empty until you edit that file',
+                    target: VITE_DEV_MODULE_PATH,
+                    status: StepStatus.NOTICE,
+                    detail: 'the module was written but registers nothing — no data-testid values were found and ' +
+                        'no state library was detected, so `hasCapabilities` stays false and reticle_state ' +
+                        'has nothing to read. Add data-testid to the elements your main flow touches, or ' +
+                        'register a store in that file, and the agent gains what the app BELIEVES rather than ' +
+                        'only what it rendered.',
+                },
+            ]
+            : []),
     ];
 }
 export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE) {
@@ -219,6 +242,14 @@ export function craSteps(input) {
             detail: `set ${TOKEN_VAR} (the only channel CRA inlines) — ${CRA_ENV_PATH} is gitignored, so each teammate must run \`reticle init\` on their own machine`,
             write: { path: CRA_ENV_PATH, content: env },
         });
+        // Beside the write, not inside it. A ✓ line is one SKILL.md tells the reader to skip, and this
+        // is the fact that decides whether the install works for anyone but the person running it.
+        steps.push({
+            title: 'Pairing token is per-machine',
+            target: CRA_ENV_PATH,
+            status: StepStatus.NOTICE,
+            detail: CRA_TOKEN_PER_MACHINE_NOTICE,
+        });
     }
     else if ('' === token) {
         // No daemon has ever run here, so there is no token to inline. Omitting the step entirely made
@@ -227,7 +258,10 @@ export function craSteps(input) {
             title: 'Pairing token',
             target: CRA_ENV_PATH,
             status: StepStatus.MANUAL,
-            detail: `no pairing token yet — run \`reticle start\`, then \`reticle init\` again to write ${TOKEN_VAR}`,
+            // `reticle serve`, not `reticle start` — the latter is not a verb this CLI dispatches, and
+            // this message is read by someone whose app boots and never pairs. Handing them a command
+            // that errors is a second dead end on the first.
+            detail: `no pairing token yet — the daemon writes one on first run. Start it with \`reticle serve\` (or let your agent run \`reticle mcp\`), then \`reticle init\` again to write ${TOKEN_VAR}`,
         });
     }
     if (null === entry) {
@@ -257,6 +291,24 @@ export function craSteps(input) {
         });
     return steps;
 }
+/**
+ * Nuxt: one manual step carrying the whole recipe, and no pretence of more.
+ *
+ * There is no Nuxt app in `apps/` and no CI gate for one, so an auto-written plugin would be a
+ * support claim nothing backs — the same reasoning SvelteKit already carries. What this DOES fix is
+ * everything that made the previous fall-through actively wrong: Nuxt was classified as `html`, so
+ * it was handed the React kit and a localhost-guarded snippet that cannot run in a Vue app.
+ */
+export function nuxtSteps(input) {
+    return [
+        {
+            title: 'Connect snippet (Nuxt)',
+            target: NUXT_PLUGIN_PATH,
+            status: StepStatus.MANUAL,
+            detail: nuxtManual(input.options.port, input.options.projectId),
+        },
+    ];
+}
 export function svelteKitSteps(input) {
     const unverified = {
         title: 'SvelteKit is UNVERIFIED',

package/dist/init/plan.d.ts

@@ -4,6 +4,7 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, type Detection } from './detect.js';
+import { type McpClient } from './mcp-clients.js';
 /**
  * Pin the SDK to the CLI's own version.
  *
@@ -14,6 +15,8 @@ import { Framework, type Detection } from './detect.js';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
+/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
+export declare function frameworkPackages(framework: Framework): readonly string[];
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
 /** True when this step is what makes the app dial the daemon. */
@@ -90,6 +93,17 @@ export interface PlanInput {
     cursorConfig: string | null;
     /** Absolute path of ~/.cursor/mcp.json (the write target). */
     cursorConfigPath: string;
+    /**
+     * Every OTHER MCP client detected on this machine, with its config path and current content.
+     *
+     * Claude Code and Cursor keep their own steps — Claude registers through its CLI, and Cursor's
+     * predates this. Everything else is uniform: read the file, merge, write.
+     */
+    detectedClients?: readonly {
+        id: McpClient;
+        configPath: string;
+        existing: string | null;
+    }[] | undefined;
     /** Discovered Vite config: its path + source, or null if none found. */
     viteConfig: {
         path: string;