@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/src/core/ui.js

@@ -1,185 +1,185 @@
-// UI primitives for the CLI: colors, icons, spinner, progress bar,
-// interactive select/confirm prompts, and a summary panel.
-//
-// Design rules:
-//   - Respect process.stdout.isTTY: animations only when interactive.
-//     In pipes/CI, fall back to linear status text.
-//   - Respect NO_COLOR (https://no-color.org) and FORCE_COLOR=1.
-//   - Animations write to stderr to keep stdout clean for `--json` mode
-//     (the user can still pipe machine-readable output even with spinners).
-//   - Zero hidden globals — every primitive is a plain function/class.
-
-import pc from 'picocolors';
-
-// PERF-16-05: @inquirer/prompts é optionalDependency. Carregamos lazy dentro
-// de select()/confirm() para que (a) modo MCP server e CI não paguem o custo
-// de boot, e (b) `npm install --omit=optional` produza CLI core funcional
-// (apenas comandos interativos falham com mensagem descritiva).
-let _inquirerModule = null;
-async function loadInquirer() {
-  if (_inquirerModule) return _inquirerModule;
-  try {
-    _inquirerModule = await import('@inquirer/prompts');
-    return _inquirerModule;
-  } catch (err) {
-    throw new Error(
-      'Interactive prompts require @inquirer/prompts. Install with `npm i @inquirer/prompts` or pass --yes / --no-interactive to skip the prompt.'
-    );
-  }
-}
-
-// --- color helpers ---
-
-const NO_COLOR = process.env.NO_COLOR && process.env.NO_COLOR !== '0';
-const FORCE    = process.env.FORCE_COLOR === '1';
-const COLOR_ON = FORCE || (!NO_COLOR && process.stdout.isTTY);
-
-function id(s) { return String(s); }
-export const c = COLOR_ON
-  ? {
-      green: pc.green, red: pc.red, yellow: pc.yellow, cyan: pc.cyan,
-      magenta: pc.magenta, blue: pc.blue, dim: pc.dim, bold: pc.bold,
-      gray: pc.gray, underline: pc.underline,
-    }
-  : {
-      green: id, red: id, yellow: id, cyan: id, magenta: id, blue: id,
-      dim: id, bold: id, gray: id, underline: id,
-    };
-
-export const icons = {
-  check:   '✓',
-  cross:   '✗',
-  warn:    '⚠',
-  dot:     '•',
-  arrow:   '→',
-  spinner: ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
-};
-
-// --- spinner ---
-
-export function spinner({ text = '' } = {}) {
-  const tty = process.stderr.isTTY;
-  let i = 0;
-  let current = text;
-  let timer = null;
-
-  function render() {
-    process.stderr.write(`\r${c.cyan(icons.spinner[i])} ${current}\x1b[K`);
-    i = (i + 1) % icons.spinner.length;
-  }
-
-  if (tty) {
-    timer = setInterval(render, 80);
-    render();
-  } else {
-    process.stderr.write(`${icons.dot} ${current}\n`);
-  }
-
-  function clearLine() {
-    if (tty) process.stderr.write('\r\x1b[K');
-  }
-
-  return {
-    update(t) { current = t; if (!tty) process.stderr.write(`${icons.dot} ${t}\n`); },
-    succeed(t) {
-      if (timer) clearInterval(timer);
-      clearLine();
-      process.stderr.write(`${c.green(icons.check)} ${t ?? current}\n`);
-    },
-    fail(t) {
-      if (timer) clearInterval(timer);
-      clearLine();
-      process.stderr.write(`${c.red(icons.cross)} ${t ?? current}\n`);
-    },
-    stop() {
-      if (timer) clearInterval(timer);
-      clearLine();
-    },
-  };
-}
-
-// --- progress bar ---
-
-export function progress({ total, label = '' } = {}) {
-  const tty = process.stderr.isTTY;
-  const width = 24;
-  let current = 0;
-  let lastLabel = label;
-
-  function render() {
-    const pct = total === 0 ? 100 : Math.min(100, Math.round((current / total) * 100));
-    const filled = Math.round((width * pct) / 100);
-    const bar = '━'.repeat(filled) + c.dim('━'.repeat(width - filled));
-    const line = `${c.cyan(bar)} ${pct.toString().padStart(3)}% ${c.dim(`(${current}/${total})`)} ${lastLabel}`;
-    process.stderr.write(`\r${line}\x1b[K`);
-  }
-
-  function tick({ label } = {}) {
-    current++;
-    if (label !== undefined) lastLabel = label;
-    if (tty) {
-      render();
-    } else if (current === total || current % Math.max(1, Math.floor(total / 10)) === 0) {
-      // Every ~10% in non-TTY mode
-      const pct = total === 0 ? 100 : Math.round((current / total) * 100);
-      process.stderr.write(`  ${pct}% ${lastLabel}\n`);
-    }
-  }
-
-  function finish(text) {
-    if (tty) {
-      process.stderr.write('\r\x1b[K');
-    }
-    if (text) process.stderr.write(`${c.green(icons.check)} ${text}\n`);
-  }
-
-  if (tty) render();
-  return { tick, finish };
-}
-
-// --- interactive prompts ---
-
-export async function select(opts) {
-  if (!process.stdin.isTTY) {
-    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass the value as a flag instead.');
-  }
-  const { select: inqSelect } = await loadInquirer();
-  return inqSelect(opts);
-}
-
-export async function confirm(opts) {
-  if (!process.stdin.isTTY) {
-    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass --yes to skip confirmation.');
-  }
-  const { confirm: inqConfirm } = await loadInquirer();
-  return inqConfirm(opts);
-}
-
-// --- summary panel ---
-
-export function summary({ title, rows = [], total, hint }) {
-  const lines = [];
-  lines.push(`${c.green(icons.check)} ${c.bold(title)}`);
-  lines.push('');
-
-  // Compute label column width
-  const w = Math.max(...rows.map(r => String(r[0]).length), 0);
-  for (const [label, count, status] of rows) {
-    const cnt = count > 0 ? c.green(String(count).padStart(4)) : c.dim(String(count).padStart(4));
-    const tail = status === 'fail' ? c.red(icons.cross) : c.green(icons.check);
-    lines.push(`  ${label.padEnd(w)}  ${cnt}  ${tail}`);
-  }
-
-  if (total !== undefined || hint) {
-    lines.push('');
-    const totalStr = total !== undefined ? `Total: ${c.bold(total)}` : '';
-    const hintStr = hint ? c.dim(`· ${hint}`) : '';
-    lines.push(`  ${totalStr}${totalStr && hintStr ? ' ' : ''}${hintStr}`);
-  }
-
-  return lines.join('\n');
-}
-
-// --- helpers exposed for tests ---
-
-export const _internal = { COLOR_ON };
+// UI primitives for the CLI: colors, icons, spinner, progress bar,
+// interactive select/confirm prompts, and a summary panel.
+//
+// Design rules:
+//   - Respect process.stdout.isTTY: animations only when interactive.
+//     In pipes/CI, fall back to linear status text.
+//   - Respect NO_COLOR (https://no-color.org) and FORCE_COLOR=1.
+//   - Animations write to stderr to keep stdout clean for `--json` mode
+//     (the user can still pipe machine-readable output even with spinners).
+//   - Zero hidden globals — every primitive is a plain function/class.
+
+import pc from 'picocolors';
+
+// PERF-16-05: @inquirer/prompts é optionalDependency. Carregamos lazy dentro
+// de select()/confirm() para que (a) modo MCP server e CI não paguem o custo
+// de boot, e (b) `npm install --omit=optional` produza CLI core funcional
+// (apenas comandos interativos falham com mensagem descritiva).
+let _inquirerModule = null;
+async function loadInquirer() {
+  if (_inquirerModule) return _inquirerModule;
+  try {
+    _inquirerModule = await import('@inquirer/prompts');
+    return _inquirerModule;
+  } catch (err) {
+    throw new Error(
+      'Interactive prompts require @inquirer/prompts. Install with `npm i @inquirer/prompts` or pass --yes / --no-interactive to skip the prompt.'
+    );
+  }
+}
+
+// --- color helpers ---
+
+const NO_COLOR = process.env.NO_COLOR && process.env.NO_COLOR !== '0';
+const FORCE    = process.env.FORCE_COLOR === '1';
+const COLOR_ON = FORCE || (!NO_COLOR && process.stdout.isTTY);
+
+function id(s) { return String(s); }
+export const c = COLOR_ON
+  ? {
+      green: pc.green, red: pc.red, yellow: pc.yellow, cyan: pc.cyan,
+      magenta: pc.magenta, blue: pc.blue, dim: pc.dim, bold: pc.bold,
+      gray: pc.gray, underline: pc.underline,
+    }
+  : {
+      green: id, red: id, yellow: id, cyan: id, magenta: id, blue: id,
+      dim: id, bold: id, gray: id, underline: id,
+    };
+
+export const icons = {
+  check:   '✓',
+  cross:   '✗',
+  warn:    '⚠',
+  dot:     '•',
+  arrow:   '→',
+  spinner: ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
+};
+
+// --- spinner ---
+
+export function spinner({ text = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  let i = 0;
+  let current = text;
+  let timer = null;
+
+  function render() {
+    process.stderr.write(`\r${c.cyan(icons.spinner[i])} ${current}\x1b[K`);
+    i = (i + 1) % icons.spinner.length;
+  }
+
+  if (tty) {
+    timer = setInterval(render, 80);
+    render();
+  } else {
+    process.stderr.write(`${icons.dot} ${current}\n`);
+  }
+
+  function clearLine() {
+    if (tty) process.stderr.write('\r\x1b[K');
+  }
+
+  return {
+    update(t) { current = t; if (!tty) process.stderr.write(`${icons.dot} ${t}\n`); },
+    succeed(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.green(icons.check)} ${t ?? current}\n`);
+    },
+    fail(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.red(icons.cross)} ${t ?? current}\n`);
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      clearLine();
+    },
+  };
+}
+
+// --- progress bar ---
+
+export function progress({ total, label = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  const width = 24;
+  let current = 0;
+  let lastLabel = label;
+
+  function render() {
+    const pct = total === 0 ? 100 : Math.min(100, Math.round((current / total) * 100));
+    const filled = Math.round((width * pct) / 100);
+    const bar = '━'.repeat(filled) + c.dim('━'.repeat(width - filled));
+    const line = `${c.cyan(bar)} ${pct.toString().padStart(3)}% ${c.dim(`(${current}/${total})`)} ${lastLabel}`;
+    process.stderr.write(`\r${line}\x1b[K`);
+  }
+
+  function tick({ label } = {}) {
+    current++;
+    if (label !== undefined) lastLabel = label;
+    if (tty) {
+      render();
+    } else if (current === total || current % Math.max(1, Math.floor(total / 10)) === 0) {
+      // Every ~10% in non-TTY mode
+      const pct = total === 0 ? 100 : Math.round((current / total) * 100);
+      process.stderr.write(`  ${pct}% ${lastLabel}\n`);
+    }
+  }
+
+  function finish(text) {
+    if (tty) {
+      process.stderr.write('\r\x1b[K');
+    }
+    if (text) process.stderr.write(`${c.green(icons.check)} ${text}\n`);
+  }
+
+  if (tty) render();
+  return { tick, finish };
+}
+
+// --- interactive prompts ---
+
+export async function select(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass the value as a flag instead.');
+  }
+  const { select: inqSelect } = await loadInquirer();
+  return inqSelect(opts);
+}
+
+export async function confirm(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass --yes to skip confirmation.');
+  }
+  const { confirm: inqConfirm } = await loadInquirer();
+  return inqConfirm(opts);
+}
+
+// --- summary panel ---
+
+export function summary({ title, rows = [], total, hint }) {
+  const lines = [];
+  lines.push(`${c.green(icons.check)} ${c.bold(title)}`);
+  lines.push('');
+
+  // Compute label column width
+  const w = Math.max(...rows.map(r => String(r[0]).length), 0);
+  for (const [label, count, status] of rows) {
+    const cnt = count > 0 ? c.green(String(count).padStart(4)) : c.dim(String(count).padStart(4));
+    const tail = status === 'fail' ? c.red(icons.cross) : c.green(icons.check);
+    lines.push(`  ${label.padEnd(w)}  ${cnt}  ${tail}`);
+  }
+
+  if (total !== undefined || hint) {
+    lines.push('');
+    const totalStr = total !== undefined ? `Total: ${c.bold(total)}` : '';
+    const hintStr = hint ? c.dim(`· ${hint}`) : '';
+    lines.push(`  ${totalStr}${totalStr && hintStr ? ' ' : ''}${hintStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- helpers exposed for tests ---
+
+export const _internal = { COLOR_ON };

package/src/mcp-server/install.js

@@ -1,149 +1,149 @@
-// Install kit-mcp into an IDE's MCP-server config.
-//
-// Strategies:
-//   merge-mcpServers-json — read JSON, merge `mcpServers[name]`, write back
-//   append-toml-snippet   — print TOML snippet for the user to paste (Codex)
-//
-// We never overwrite blindly: existing entries with the same name are replaced
-// only if --force is passed, otherwise we abort with a clear message.
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import { fileURLToPath } from 'node:url';
-import { getTarget, listTargets } from '../core/registry.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = path.dirname(__filename);
-const REPO_ROOT  = path.resolve(__dirname, '../..');
-
-export async function installMcp(targetId, opts = {}) {
-  const target = getTarget(targetId);
-  if (!target.mcpConfig) {
-    return { ok: false, target: targetId, reason: `${target.label} has no MCP config integration in registry.` };
-  }
-
-  const scope   = opts.scope ?? 'user'; // 'user' | 'project'
-  const name    = opts.name  ?? 'kit';
-  const dryRun  = !!opts.dryRun;
-  const force   = !!opts.force;
-
-  const entry = buildServerEntry(opts);
-  const configPath = resolveConfigPath(target.mcpConfig, scope, opts.projectRoot);
-  if (!configPath) {
-    return { ok: false, target: targetId, reason: `Could not resolve config path for scope=${scope}.` };
-  }
-
-  if (target.mcpConfig.strategy === 'merge-mcpServers-json') {
-    return await mergeJson(configPath, target.mcpConfig.userKey ?? 'mcpServers', name, entry, { dryRun, force, target: targetId });
-  }
-  if (target.mcpConfig.strategy === 'append-toml-snippet') {
-    return await appendToml(configPath, name, entry, { dryRun, force, target: targetId });
-  }
-  return { ok: false, target: targetId, reason: `Unknown strategy: ${target.mcpConfig.strategy}` };
-}
-
-export function listInstallTargets() {
-  return listTargets().filter(t => t.capabilities.mcpConfig);
-}
-
-// --- helpers ---
-
-function buildServerEntry(opts) {
-  // Three modes:
-  //   via=local (default) — point at this clone's bin/mcp.js with the running node
-  //   via=npx             — `npx -y @luanpdd/kit-mcp` (portable, works on any machine after publish)
-  //   via=global          — `kit-mcp` (assumes user has `npm install -g @luanpdd/kit-mcp`)
-  // Override anything with explicit --command / --args.
-  const via = opts.via ?? 'local';
-  let command, args;
-
-  if (via === 'npx') {
-    command = 'npx';
-    args = ['-y', opts.pkg ?? '@luanpdd/kit-mcp'];
-  } else if (via === 'global') {
-    command = 'kit-mcp';
-    args = [];
-  } else {
-    command = process.execPath;
-    args = [path.join(REPO_ROOT, 'bin', 'mcp.js')];
-  }
-
-  return {
-    command: opts.command ?? command,
-    args:    opts.args    ?? args,
-    env:     opts.env     ?? {},
-  };
-}
-
-function resolveConfigPath(cfg, scope, projectRoot) {
-  if (scope === 'user' && cfg.userPath)   return expandHome(cfg.userPath);
-  if (scope === 'project' && cfg.path)    return path.join(path.resolve(projectRoot ?? process.cwd()), cfg.path);
-  if (cfg.userPath) return expandHome(cfg.userPath);
-  if (cfg.path)     return path.join(path.resolve(projectRoot ?? process.cwd()), cfg.path);
-  return null;
-}
-
-function expandHome(p) {
-  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
-  return p;
-}
-
-async function mergeJson(filePath, key, name, entry, { dryRun, force, target }) {
-  let json = {};
-  try {
-    const raw = await fs.readFile(filePath, 'utf8');
-    json = JSON.parse(raw);
-  } catch (e) {
-    if (e.code !== 'ENOENT') {
-      return { ok: false, target, reason: `Failed to parse existing config at ${filePath}: ${e.message}` };
-    }
-  }
-  json[key] ??= {};
-  if (json[key][name] && !force) {
-    return {
-      ok: false, target, configPath: filePath,
-      reason: `An MCP server named "${name}" already exists in ${filePath}. Re-run with --force to replace, or pass --name <other>.`,
-    };
-  }
-  json[key][name] = entry;
-
-  if (dryRun) {
-    return { ok: true, target, configPath: filePath, dryRun: true, preview: json };
-  }
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(json, null, 2) + '\n', 'utf8');
-  return { ok: true, target, configPath: filePath, name, entry };
-}
-
-async function appendToml(filePath, name, entry, { dryRun, target }) {
-  // Codex MCP entries in TOML look like:
-  //   [mcp_servers.kit]
-  //   command = "node"
-  //   args = ["/abs/path/bin/mcp.js"]
-  const toml = [
-    `[mcp_servers.${name}]`,
-    `command = ${JSON.stringify(entry.command)}`,
-    `args = ${JSON.stringify(entry.args)}`,
-    Object.keys(entry.env || {}).length
-      ? `env = { ${Object.entries(entry.env).map(([k, v]) => `${k} = ${JSON.stringify(v)}`).join(', ')} }`
-      : null,
-    '',
-  ].filter(Boolean).join('\n');
-
-  if (dryRun) {
-    return { ok: true, target, configPath: filePath, dryRun: true, snippet: toml };
-  }
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  // Append (Codex tolerates duplicate sections only with [tables.*]; manual review encouraged).
-  let existing = '';
-  try { existing = await fs.readFile(filePath, 'utf8'); } catch {}
-  if (existing.includes(`[mcp_servers.${name}]`)) {
-    return {
-      ok: false, target, configPath: filePath,
-      reason: `[mcp_servers.${name}] already exists in ${filePath}. Edit by hand or pass --name <other>.`,
-    };
-  }
-  await fs.writeFile(filePath, existing + (existing.endsWith('\n') ? '' : '\n') + toml, 'utf8');
-  return { ok: true, target, configPath: filePath, snippet: toml };
-}
+// Install kit-mcp into an IDE's MCP-server config.
+//
+// Strategies:
+//   merge-mcpServers-json — read JSON, merge `mcpServers[name]`, write back
+//   append-toml-snippet   — print TOML snippet for the user to paste (Codex)
+//
+// We never overwrite blindly: existing entries with the same name are replaced
+// only if --force is passed, otherwise we abort with a clear message.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { getTarget, listTargets } from '../core/registry.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+const REPO_ROOT  = path.resolve(__dirname, '../..');
+
+export async function installMcp(targetId, opts = {}) {
+  const target = getTarget(targetId);
+  if (!target.mcpConfig) {
+    return { ok: false, target: targetId, reason: `${target.label} has no MCP config integration in registry.` };
+  }
+
+  const scope   = opts.scope ?? 'user'; // 'user' | 'project'
+  const name    = opts.name  ?? 'kit';
+  const dryRun  = !!opts.dryRun;
+  const force   = !!opts.force;
+
+  const entry = buildServerEntry(opts);
+  const configPath = resolveConfigPath(target.mcpConfig, scope, opts.projectRoot);
+  if (!configPath) {
+    return { ok: false, target: targetId, reason: `Could not resolve config path for scope=${scope}.` };
+  }
+
+  if (target.mcpConfig.strategy === 'merge-mcpServers-json') {
+    return await mergeJson(configPath, target.mcpConfig.userKey ?? 'mcpServers', name, entry, { dryRun, force, target: targetId });
+  }
+  if (target.mcpConfig.strategy === 'append-toml-snippet') {
+    return await appendToml(configPath, name, entry, { dryRun, force, target: targetId });
+  }
+  return { ok: false, target: targetId, reason: `Unknown strategy: ${target.mcpConfig.strategy}` };
+}
+
+export function listInstallTargets() {
+  return listTargets().filter(t => t.capabilities.mcpConfig);
+}
+
+// --- helpers ---
+
+function buildServerEntry(opts) {
+  // Three modes:
+  //   via=local (default) — point at this clone's bin/mcp.js with the running node
+  //   via=npx             — `npx -y @luanpdd/kit-mcp` (portable, works on any machine after publish)
+  //   via=global          — `kit-mcp` (assumes user has `npm install -g @luanpdd/kit-mcp`)
+  // Override anything with explicit --command / --args.
+  const via = opts.via ?? 'local';
+  let command, args;
+
+  if (via === 'npx') {
+    command = 'npx';
+    args = ['-y', opts.pkg ?? '@luanpdd/kit-mcp'];
+  } else if (via === 'global') {
+    command = 'kit-mcp';
+    args = [];
+  } else {
+    command = process.execPath;
+    args = [path.join(REPO_ROOT, 'bin', 'mcp.js')];
+  }
+
+  return {
+    command: opts.command ?? command,
+    args:    opts.args    ?? args,
+    env:     opts.env     ?? {},
+  };
+}
+
+function resolveConfigPath(cfg, scope, projectRoot) {
+  if (scope === 'user' && cfg.userPath)   return expandHome(cfg.userPath);
+  if (scope === 'project' && cfg.path)    return path.join(path.resolve(projectRoot ?? process.cwd()), cfg.path);
+  if (cfg.userPath) return expandHome(cfg.userPath);
+  if (cfg.path)     return path.join(path.resolve(projectRoot ?? process.cwd()), cfg.path);
+  return null;
+}
+
+function expandHome(p) {
+  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+async function mergeJson(filePath, key, name, entry, { dryRun, force, target }) {
+  let json = {};
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    json = JSON.parse(raw);
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { ok: false, target, reason: `Failed to parse existing config at ${filePath}: ${e.message}` };
+    }
+  }
+  json[key] ??= {};
+  if (json[key][name] && !force) {
+    return {
+      ok: false, target, configPath: filePath,
+      reason: `An MCP server named "${name}" already exists in ${filePath}. Re-run with --force to replace, or pass --name <other>.`,
+    };
+  }
+  json[key][name] = entry;
+
+  if (dryRun) {
+    return { ok: true, target, configPath: filePath, dryRun: true, preview: json };
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(json, null, 2) + '\n', 'utf8');
+  return { ok: true, target, configPath: filePath, name, entry };
+}
+
+async function appendToml(filePath, name, entry, { dryRun, target }) {
+  // Codex MCP entries in TOML look like:
+  //   [mcp_servers.kit]
+  //   command = "node"
+  //   args = ["/abs/path/bin/mcp.js"]
+  const toml = [
+    `[mcp_servers.${name}]`,
+    `command = ${JSON.stringify(entry.command)}`,
+    `args = ${JSON.stringify(entry.args)}`,
+    Object.keys(entry.env || {}).length
+      ? `env = { ${Object.entries(entry.env).map(([k, v]) => `${k} = ${JSON.stringify(v)}`).join(', ')} }`
+      : null,
+    '',
+  ].filter(Boolean).join('\n');
+
+  if (dryRun) {
+    return { ok: true, target, configPath: filePath, dryRun: true, snippet: toml };
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  // Append (Codex tolerates duplicate sections only with [tables.*]; manual review encouraged).
+  let existing = '';
+  try { existing = await fs.readFile(filePath, 'utf8'); } catch {}
+  if (existing.includes(`[mcp_servers.${name}]`)) {
+    return {
+      ok: false, target, configPath: filePath,
+      reason: `[mcp_servers.${name}] already exists in ${filePath}. Edit by hand or pass --name <other>.`,
+    };
+  }
+  await fs.writeFile(filePath, existing + (existing.endsWith('\n') ? '' : '\n') + toml, 'utf8');
+  return { ok: true, target, configPath: filePath, snippet: toml };
+}