@debugai/mcp 1.1.0 → 2.1.0

package/dist/cli/clients.js

@@ -0,0 +1,143 @@
+// Where every MCP client keeps its config, and what shape it wants.
+//
+// This registry is the thing that replaces "copy this JSON blob into the
+// right file" in the README. Adding a client = one entry here; the install
+// command, doctor, and `--print` output all read from it.
+//
+// Two config shapes exist in the wild:
+//   mcpServers      { command, args, env? }                    (most clients)
+//   context_servers { source, command: { path, args, env? } }  (Zed)
+//   servers         { type: "stdio", command, args }           (VS Code native)
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+function appDataDir(env) {
+    const home = homedir();
+    if (platform() === 'win32')
+        return env.APPDATA ?? join(home, 'AppData', 'Roaming');
+    if (platform() === 'darwin')
+        return join(home, 'Library', 'Application Support');
+    return env.XDG_CONFIG_HOME ?? join(home, '.config');
+}
+/** VS Code's per-user directory — Cline stores its MCP config under it too. */
+function vscodeUserDir(env) {
+    return join(appDataDir(env), 'Code', 'User');
+}
+export function knownClients(env = process.env) {
+    const home = homedir();
+    const appData = appDataDir(env);
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            shape: 'mcpServers',
+            configPath: join(home, '.claude.json'),
+            probes: [join(home, '.claude'), join(home, '.claude.json')],
+            afterInstall: 'Start a new Claude Code session (or run /mcp to reconnect).',
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            shape: 'mcpServers',
+            configPath: join(appData, 'Claude', 'claude_desktop_config.json'),
+            probes: [join(appData, 'Claude')],
+            afterInstall: 'Quit Claude Desktop completely and reopen it (closing the window is not enough).',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            shape: 'mcpServers',
+            configPath: join(home, '.cursor', 'mcp.json'),
+            probes: [join(home, '.cursor')],
+            afterInstall: 'Cursor picks this up on its own — check Settings, MCP for a green dot.',
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf',
+            shape: 'mcpServers',
+            configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            probes: [join(home, '.codeium', 'windsurf'), join(home, '.codeium')],
+            afterInstall: 'Open Windsurf, Settings, MCP and hit refresh.',
+        },
+        {
+            id: 'zed',
+            label: 'Zed',
+            shape: 'context_servers',
+            configPath: platform() === 'win32'
+                ? join(appData, 'Zed', 'settings.json')
+                : join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'zed', 'settings.json'),
+            probes: [
+                join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'zed'),
+                join(appData, 'Zed'),
+            ],
+            afterInstall: 'Zed reloads settings on save — the server appears in the agent panel.',
+        },
+        {
+            id: 'gemini-cli',
+            label: 'Gemini CLI',
+            shape: 'mcpServers',
+            configPath: join(home, '.gemini', 'settings.json'),
+            probes: [join(home, '.gemini')],
+            afterInstall: 'Restart the Gemini CLI session.',
+        },
+        {
+            id: 'cline',
+            label: 'Cline (VS Code)',
+            shape: 'mcpServers',
+            configPath: join(vscodeUserDir(env), 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'),
+            probes: [join(vscodeUserDir(env), 'globalStorage', 'saoudrizwan.claude-dev')],
+            afterInstall: 'Open the Cline panel, MCP Servers — it reconnects without a VS Code restart.',
+        },
+        {
+            id: 'vscode',
+            label: 'VS Code (native MCP)',
+            shape: 'vscode_servers',
+            configPath: join(vscodeUserDir(env), 'mcp.json'),
+            probes: [vscodeUserDir(env)],
+            optIn: true,
+            note: 'The DebugAI VS Code extension already registers this server (VS Code 1.101+), '
+                + 'plus one-click fix apply and proactive scan. Only install here if you do not want the extension.',
+            afterInstall: 'Run "MCP: List Servers" from the command palette to confirm.',
+        },
+    ];
+}
+export function findClient(id, env = process.env) {
+    return knownClients(env).find((c) => c.id === id.toLowerCase());
+}
+/** A client counts as present when its config file OR its app directory exists. */
+export function isDetected(client) {
+    if (client.configPath && existsSync(client.configPath))
+        return true;
+    return client.probes.some((p) => existsSync(p));
+}
+export function detectedClients(env = process.env) {
+    return knownClients(env).filter(isDetected);
+}
+/**
+ * The server entry itself. `npx -y` is deliberate: it self-updates on each
+ * launch and needs no global install, which is the only variant that works
+ * identically on a laptop, a devcontainer, and CI.
+ *
+ * No `env` block, ever — the key lives in ~/.debugai/config.json (see
+ * config.ts). Client configs get committed to repos; keys should not.
+ */
+export function serverEntry(client) {
+    const command = 'npx';
+    const args = ['-y', '@debugai/mcp'];
+    if (client.shape === 'context_servers') {
+        return { source: 'custom', command: { path: command, args } };
+    }
+    if (client.shape === 'vscode_servers') {
+        return { type: 'stdio', command, args };
+    }
+    return { command, args };
+}
+/** Top-level key in that client's config file where servers are listed. */
+export function serversKey(shape) {
+    if (shape === 'context_servers')
+        return 'context_servers';
+    if (shape === 'vscode_servers')
+        return 'servers';
+    return 'mcpServers';
+}
+export const SERVER_NAME = 'debugai';

package/dist/cli/commands.d.ts

@@ -0,0 +1,7 @@
+export declare function cmdLogin(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdLogout(_argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdStatus(_argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdInstall(argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdUninstall(argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdDoctor(_argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdSetup(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/cli/commands.js

@@ -0,0 +1,360 @@
+// The subcommands. Every one of these exists to delete a step a human used
+// to do by hand:
+//
+//   setup      login + install, the only command the README leads with
+//   login      device link — replaces "copy your key out of the dashboard"
+//   install    writes client configs — replaces "paste this JSON blob"
+//   doctor     one command that answers "why isn't it working"
+//   status     what account/key is active right now
+//   logout     removes the stored key
+//   uninstall  removes the server entry from client configs
+//
+// Each returns a process exit code. Nothing here ever writes to stdout while
+// the MCP transport is live — subcommands exit before a server is created.
+import { statSync } from 'node:fs';
+import { hostname, platform } from 'node:os';
+import { clearStoredKey, configPath, loadFileConfig, maskKey, resolveSettings, writeFileConfig, } from '../config.js';
+import { DeviceLinkError, startDeviceLink, waitForDeviceLink } from '../deviceLink.js';
+import { DEFAULT_API_BASE } from '../constants.js';
+import { detectedClients, findClient, isDetected, knownClients, } from './clients.js';
+import { applyToClient, isInstalled } from './install.js';
+import { FAIL, INFO, OK, WARN, bold, codeBox, dim, heading, openBrowser, say, yellow } from './ui.js';
+// ── shared helpers ───────────────────────────────────────────────────────────
+function flag(argv, name) {
+    return argv.includes(`--${name}`);
+}
+function flagValue(argv, name) {
+    const eq = argv.find((a) => a.startsWith(`--${name}=`));
+    if (eq)
+        return eq.slice(name.length + 3);
+    const idx = argv.indexOf(`--${name}`);
+    if (idx >= 0 && argv[idx + 1] && !argv[idx + 1].startsWith('-'))
+        return argv[idx + 1];
+    return undefined;
+}
+/** Confirms a key actually works against the live API. Null = could not verify. */
+async function verifyKey(apiBase, apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 12_000);
+    try {
+        const res = await fetch(`${apiBase}/user/me`, {
+            headers: { 'x-api-key': apiKey },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        const user = body?.user ?? body ?? {};
+        return {
+            email: user.email,
+            tier: user.tier,
+            usedToday: user.usage_today ?? user.used_today ?? user.daily_usage,
+            dailyLimit: user.daily_limit ?? user.limit,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function clientLabel() {
+    return `${hostname()} (${platform()})`;
+}
+function describeResult(r) {
+    const name = bold(r.client.label);
+    switch (r.action) {
+        case 'wrote':
+        case 'updated':
+            say(`  ${OK()} ${name} — ${r.action === 'wrote' ? 'added to' : 'updated in'} ${dim(r.path ?? '')}`);
+            if (r.backupPath)
+                say(`      ${dim(`backup: ${r.backupPath}`)}`);
+            if (r.warning)
+                say(`      ${WARN()} ${yellow(r.warning)}`);
+            say(`      ${dim(`next: ${r.client.afterInstall}`)}`);
+            break;
+        case 'unchanged':
+            say(`  ${OK()} ${name} — already configured, nothing to change`);
+            break;
+        case 'removed':
+            say(`  ${OK()} ${name} — entry removed from ${dim(r.path ?? '')}`);
+            if (r.backupPath)
+                say(`      ${dim(`backup: ${r.backupPath}`)}`);
+            break;
+        case 'skipped':
+            say(`  ${INFO()} ${name} — skipped${r.warning ? `: ${r.warning}` : ''}`);
+            break;
+        case 'failed':
+            say(`  ${FAIL()} ${name} — ${r.error ?? 'failed'}`);
+            say(`      ${dim(`file: ${r.path ?? '(unknown)'}`)}`);
+            if (r.preview) {
+                say(`      ${dim('merge this in by hand:')}`);
+                r.preview.split('\n').forEach((l) => say(`      ${dim(l)}`));
+            }
+            break;
+    }
+}
+// ── login ────────────────────────────────────────────────────────────────────
+export async function cmdLogin(argv, env = process.env) {
+    const { apiBase } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    const manualKey = flagValue(argv, 'key');
+    // Escape hatch for CI, air-gapped machines, and anyone who would rather
+    // paste. Same storage path, so everything downstream behaves identically.
+    if (manualKey) {
+        if (!manualKey.startsWith('dbg_')) {
+            say(`${FAIL()} That does not look like a DebugAI key. They start with ${bold('dbg_')}.`);
+            return 1;
+        }
+        const path = writeFileConfig({ apiKey: manualKey }, env);
+        const info = await verifyKey(apiBase, manualKey);
+        say(`${OK()} Key stored in ${path}${info?.email ? ` for ${bold(info.email)}` : ''}.`);
+        if (!info)
+            say(`${WARN()} ${yellow('Could not verify it against the API just now. Run "debugai-mcp doctor" later.')}`);
+        return 0;
+    }
+    const existing = loadFileConfig(env, () => { }).apiKey;
+    if (existing && !flag(argv, 'force')) {
+        const info = await verifyKey(apiBase, existing);
+        if (info) {
+            say(`${OK()} Already signed in as ${bold(info.email ?? 'this account')} (${info.tier ?? 'free'} tier).`);
+            say(`  ${dim(`Key ${maskKey(existing)} in ${configPath(env)}. Re-link with "debugai-mcp login --force".`)}`);
+            return 0;
+        }
+        say(`${WARN()} A stored key exists but the API rejected it. Re-linking.`);
+    }
+    let start;
+    try {
+        start = await startDeviceLink({ apiBase, clientLabel: clientLabel() });
+    }
+    catch (err) {
+        const detail = err instanceof DeviceLinkError ? err.message : String(err);
+        say(`${FAIL()} Could not start the sign-in link: ${detail}`);
+        say(`  ${dim('Fallback: grab a key at https://debugai.io/dashboard and run')}`);
+        say(`  ${dim('debugai-mcp login --key dbg_your_key')}`);
+        return 1;
+    }
+    say();
+    say(bold('Sign in to DebugAI'));
+    say(codeBox(start.userCode));
+    say(`  Confirm that code at ${bold(start.verificationUriComplete)}`);
+    const opened = openBrowser(start.verificationUriComplete);
+    say(opened
+        ? dim('  (opening your browser. free account, 10 debugs/day, no card)')
+        : dim('  (open that link on any device. free account, 10 debugs/day, no card)'));
+    say();
+    say(dim(`  Waiting… the code expires in ${Math.round(start.expiresIn / 60)} minutes. Ctrl-C to cancel.`));
+    const result = await waitForDeviceLink(start, { apiBase });
+    if (result.status === 'linked') {
+        const path = writeFileConfig({ apiKey: result.apiKey }, env);
+        say();
+        say(`${OK()} Signed in${result.email ? ` as ${bold(result.email)}` : ''}${result.tier ? ` (${result.tier} tier)` : ''}.`);
+        say(`  ${dim(`Key saved to ${path}. Every MCP client on this machine reads it.`)}`);
+        say();
+        say(`  Next: ${bold('npx -y @debugai/mcp install')} ${dim('(wires up the MCP clients you have)')}`);
+        return 0;
+    }
+    say();
+    if (result.status === 'denied')
+        say(`${FAIL()} Sign-in was declined in the browser.`);
+    else if (result.status === 'expired')
+        say(`${FAIL()} The code expired. Run "debugai-mcp login" again.`);
+    else
+        say(`${FAIL()} Sign-in did not complete.`);
+    return 1;
+}
+// ── logout / status ──────────────────────────────────────────────────────────
+export function cmdLogout(_argv, env = process.env) {
+    const removed = clearStoredKey(env);
+    say(removed
+        ? `${OK()} Stored key removed from ${configPath(env)}.`
+        : `${INFO()} No stored key to remove (${configPath(env)}).`);
+    if ((env.DEBUGAI_API_KEY ?? '').trim()) {
+        say(`${WARN()} ${yellow('DEBUGAI_API_KEY is still set in this environment and takes priority over the file.')}`);
+    }
+    return 0;
+}
+export async function cmdStatus(_argv, env = process.env) {
+    const { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    say(`${bold('DebugAI MCP status')}`);
+    say(`  API base   ${apiBase}`);
+    say(`  Key        ${apiKey ? `${maskKey(apiKey)} (from ${keySource === 'env' ? 'DEBUGAI_API_KEY' : configPath(env)})` : dim('none')}`);
+    if (!apiKey) {
+        say();
+        say(`  Run ${bold('npx -y @debugai/mcp login')} to sign in.`);
+        return 1;
+    }
+    const info = await verifyKey(apiBase, apiKey);
+    if (!info) {
+        say(`  Account    ${FAIL()} key rejected or API unreachable`);
+        return 1;
+    }
+    say(`  Account    ${info.email ?? '(unknown)'} · ${info.tier ?? 'free'} tier`);
+    return 0;
+}
+// ── install / uninstall ──────────────────────────────────────────────────────
+function selectClients(argv, env) {
+    const raw = flagValue(argv, 'client');
+    if (raw) {
+        const ids = raw.split(',').map((s) => s.trim()).filter(Boolean);
+        const clients = [];
+        for (const id of ids) {
+            const found = findClient(id, env);
+            if (found)
+                clients.push(found);
+            else
+                say(`${WARN()} Unknown client "${id}". Run "debugai-mcp install --list" to see the names.`);
+        }
+        return { clients, explicit: true };
+    }
+    if (flag(argv, 'all'))
+        return { clients: knownClients(env).filter((c) => !c.optIn), explicit: false };
+    return { clients: detectedClients(env).filter((c) => !c.optIn), explicit: false };
+}
+function listClients(env) {
+    heading('Known MCP clients');
+    for (const c of knownClients(env)) {
+        const mark = isDetected(c) ? OK() : INFO();
+        const state = isDetected(c) ? (isInstalled(c) ? 'detected · debugai configured' : 'detected') : 'not found';
+        say(`  ${mark} ${bold(c.id.padEnd(15))} ${c.label.padEnd(22)} ${dim(state)}`);
+        say(`      ${dim(c.configPath ?? 'no config path on this OS')}`);
+        if (c.note)
+            say(`      ${dim(c.note)}`);
+    }
+    say();
+    say(dim('  Install one explicitly: debugai-mcp install --client=cursor'));
+}
+export function cmdInstall(argv, env = process.env) {
+    if (flag(argv, 'list')) {
+        listClients(env);
+        return 0;
+    }
+    const dryRun = flag(argv, 'dry-run') || flag(argv, 'print');
+    const remove = flag(argv, 'remove');
+    const { clients, explicit } = selectClients(argv, env);
+    if (!clients.length) {
+        say(`${WARN()} No MCP clients detected on this machine.`);
+        say();
+        listClients(env);
+        return 1;
+    }
+    heading(remove ? 'Removing DebugAI from MCP clients' : 'Installing DebugAI into MCP clients');
+    const results = clients.map((c) => applyToClient(c, { dryRun, remove }));
+    results.forEach(describeResult);
+    if (dryRun) {
+        for (const r of results.filter((x) => x.preview)) {
+            heading(`${r.client.label} — ${r.path}`);
+            say(r.preview.trimEnd());
+        }
+        say();
+        say(dim('  Dry run — nothing was written.'));
+        return 0;
+    }
+    const failed = results.filter((r) => r.action === 'failed').length;
+    const changed = results.filter((r) => r.action === 'wrote' || r.action === 'updated' || r.action === 'removed').length;
+    say();
+    if (!remove) {
+        const { apiKey } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+        if (!apiKey) {
+            say(`${WARN()} ${yellow('No API key stored yet — run')} ${bold('npx -y @debugai/mcp login')} ${yellow('to finish.')}`);
+        }
+        else {
+            say(`${OK()} Key already stored — ${changed ? 'restart the clients above and you are done.' : 'nothing left to do.'}`);
+        }
+        if (!explicit)
+            say(dim('  Missing a client? "debugai-mcp install --list" shows every name.'));
+    }
+    return failed ? 1 : 0;
+}
+export function cmdUninstall(argv, env = process.env) {
+    return cmdInstall([...argv, '--remove', '--all'], env);
+}
+// ── doctor ───────────────────────────────────────────────────────────────────
+export async function cmdDoctor(_argv, env = process.env) {
+    let hardFailures = 0;
+    const fail = (msg, hint) => {
+        hardFailures++;
+        say(`  ${FAIL()} ${msg}`);
+        if (hint)
+            say(`      ${dim(hint)}`);
+    };
+    const pass = (msg, detail) => {
+        say(`  ${OK()} ${msg}`);
+        if (detail)
+            say(`      ${dim(detail)}`);
+    };
+    heading('Runtime');
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major >= 18)
+        pass(`Node ${process.versions.node}`);
+    else
+        fail(`Node ${process.versions.node} is too old`, 'DebugAI MCP needs Node 18 or newer (it uses global fetch).');
+    heading('Account');
+    const { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    if (!apiKey) {
+        fail('No API key found', 'Run: npx -y @debugai/mcp login');
+    }
+    else if (!apiKey.startsWith('dbg_')) {
+        fail(`Key does not look like a DebugAI key (${maskKey(apiKey)})`, 'DebugAI keys start with dbg_.');
+    }
+    else {
+        pass(`Key ${maskKey(apiKey)}`, `source: ${keySource === 'env' ? 'DEBUGAI_API_KEY env var' : configPath(env)}`);
+    }
+    if (keySource === 'file') {
+        try {
+            const mode = statSync(configPath(env)).mode & 0o777;
+            if (platform() !== 'win32' && (mode & 0o077) !== 0) {
+                say(`  ${WARN()} ${yellow(`Config file is readable by other users (mode ${mode.toString(8)})`)}`);
+                say(`      ${dim(`fix: chmod 600 ${configPath(env)}`)}`);
+            }
+        }
+        catch { /* file vanished between calls — the key check above already covered it */ }
+    }
+    heading('API');
+    if (!apiKey) {
+        say(`  ${INFO()} Skipped — no key to test with.`);
+    }
+    else {
+        const info = await verifyKey(apiBase, apiKey);
+        if (info) {
+            pass(`${apiBase} reachable`, `${info.email ?? 'account'} · ${info.tier ?? 'free'} tier`);
+        }
+        else {
+            fail(`Could not authenticate against ${apiBase}`, 'Either the key was rotated (run: debugai-mcp login --force) or the API is unreachable from here.');
+        }
+    }
+    heading('MCP clients');
+    const detected = detectedClients(env);
+    if (!detected.length) {
+        say(`  ${INFO()} None detected. "debugai-mcp install --list" shows every supported client.`);
+    }
+    for (const c of detected) {
+        if (isInstalled(c))
+            pass(`${c.label} — debugai configured`, c.configPath ?? undefined);
+        else
+            say(`  ${WARN()} ${yellow(`${c.label} — installed but DebugAI is not in its config`)}\n      ${dim(`fix: debugai-mcp install --client=${c.id}`)}`);
+    }
+    say();
+    if (hardFailures) {
+        say(`${FAIL()} ${hardFailures} problem${hardFailures === 1 ? '' : 's'} to fix.`);
+        return 1;
+    }
+    say(`${OK()} Everything checks out.`);
+    return 0;
+}
+// ── setup (the headline command) ─────────────────────────────────────────────
+export async function cmdSetup(argv, env = process.env) {
+    const { apiKey } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    if (!apiKey || flag(argv, 'force')) {
+        const code = await cmdLogin(argv, env);
+        if (code !== 0)
+            return code;
+    }
+    else {
+        say(`${OK()} Already signed in — skipping login (use --force to re-link).`);
+    }
+    const installCode = cmdInstall(argv.filter((a) => a !== '--force'), env);
+    if (installCode !== 0)
+        return installCode;
+    return cmdDoctor([], env);
+}

package/dist/cli/install.d.ts

@@ -0,0 +1,21 @@
+import { type McpClient } from './clients.js';
+export type InstallAction = 'wrote' | 'updated' | 'unchanged' | 'removed' | 'skipped' | 'failed';
+export interface InstallResult {
+    client: McpClient;
+    action: InstallAction;
+    path: string | null;
+    backupPath?: string;
+    /** Non-fatal thing the user must know (dropped comments, unsupported OS). */
+    warning?: string;
+    error?: string;
+    /** The exact JSON we would write — used by --dry-run and by failure output. */
+    preview?: string;
+}
+export interface InstallOptions {
+    dryRun?: boolean;
+    /** Remove the debugai entry instead of adding it. */
+    remove?: boolean;
+}
+export declare function applyToClient(client: McpClient, opts?: InstallOptions): InstallResult;
+/** True when the client's config already points at this server. */
+export declare function isInstalled(client: McpClient): boolean;

package/dist/cli/install.js

@@ -0,0 +1,150 @@
+// Writes the DebugAI server into MCP client config files.
+//
+// Rules this code refuses to break, because it is editing files a user's
+// whole editor setup depends on:
+//   - never overwrite the file wholesale — parse, touch only our own key,
+//     write everything else back untouched
+//   - back up before the first modification, always, with the path printed
+//   - write to a temp file in the same directory and rename over the target,
+//     so a crash mid-write cannot leave a truncated config behind
+//   - a file we cannot parse is left ALONE and reported, never "fixed"
+//   - running twice is a no-op ("unchanged"), never a duplicate entry
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseJsonc } from './jsonc.js';
+import { SERVER_NAME, serverEntry, serversKey } from './clients.js';
+function backupPath(path) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${path}.debugai-backup-${stamp}`;
+}
+function writeAtomic(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, contents, 'utf8');
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+function sameEntry(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function applyToClient(client, opts = {}) {
+    const path = client.configPath;
+    if (!path) {
+        return {
+            client,
+            action: 'skipped',
+            path: null,
+            warning: `${client.label} has no known config location on this operating system.`,
+        };
+    }
+    const key = serversKey(client.shape);
+    const desired = serverEntry(client);
+    let root = {};
+    let hadComments = false;
+    const existed = existsSync(path);
+    if (existed) {
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            return { client, action: 'failed', path, error: `could not read: ${err.message}` };
+        }
+        try {
+            const parsed = parseJsonc(raw);
+            hadComments = parsed.hadComments;
+            if (typeof parsed.value !== 'object' || parsed.value === null || Array.isArray(parsed.value)) {
+                throw new Error('top level is not a JSON object');
+            }
+            root = parsed.value;
+        }
+        catch (err) {
+            // Do NOT rewrite a file we failed to understand — that is how people
+            // lose their editor settings. Report it and hand back the snippet.
+            return {
+                client,
+                action: 'failed',
+                path,
+                error: `could not parse (${err.message}) — left untouched`,
+                preview: JSON.stringify({ [key]: { [SERVER_NAME]: desired } }, null, 2),
+            };
+        }
+    }
+    else if (opts.remove) {
+        return { client, action: 'unchanged', path };
+    }
+    const existingServers = root[key];
+    const servers = typeof existingServers === 'object' && existingServers !== null && !Array.isArray(existingServers)
+        ? { ...existingServers }
+        : {};
+    if (opts.remove) {
+        if (!(SERVER_NAME in servers))
+            return { client, action: 'unchanged', path };
+        delete servers[SERVER_NAME];
+    }
+    else {
+        if (sameEntry(servers[SERVER_NAME], desired))
+            return { client, action: 'unchanged', path };
+        servers[SERVER_NAME] = desired;
+    }
+    const nextRoot = { ...root, [key]: servers };
+    const contents = `${JSON.stringify(nextRoot, null, 2)}\n`;
+    const warning = hadComments && !opts.dryRun
+        ? 'this file had comments; JSON does not keep them, so they were dropped (the backup above still has them)'
+        : undefined;
+    if (opts.dryRun) {
+        return {
+            client,
+            action: opts.remove ? 'removed' : existed ? 'updated' : 'wrote',
+            path,
+            preview: contents,
+            warning: hadComments ? 'this file has comments; installing would drop them (a backup is written first)' : undefined,
+        };
+    }
+    let backup;
+    try {
+        if (existed) {
+            backup = backupPath(path);
+            copyFileSync(path, backup);
+        }
+        writeAtomic(path, contents);
+    }
+    catch (err) {
+        return {
+            client,
+            action: 'failed',
+            path,
+            backupPath: backup,
+            error: err.message,
+            preview: JSON.stringify({ [key]: { [SERVER_NAME]: desired } }, null, 2),
+        };
+    }
+    return {
+        client,
+        action: opts.remove ? 'removed' : existed ? 'updated' : 'wrote',
+        path,
+        backupPath: backup,
+        warning,
+    };
+}
+/** True when the client's config already points at this server. */
+export function isInstalled(client) {
+    if (!client.configPath || !existsSync(client.configPath))
+        return false;
+    try {
+        const parsed = parseJsonc(readFileSync(client.configPath, 'utf8'));
+        const servers = parsed.value?.[serversKey(client.shape)];
+        return Boolean(servers && typeof servers === 'object' && SERVER_NAME in servers);
+    }
+    catch {
+        return false;
+    }
+}