kodelyth-ecc 1.2.0

package/scripts/codex/merge-codex-config.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Merge the non-MCP Codex baseline from `.codex/config.toml` into a target
+ * `config.toml` without overwriting existing user choices.
+ *
+ * Strategy: add-only.
+ * - Missing root keys are inserted before the first TOML table.
+ * - Missing table keys are appended to existing tables.
+ * - Missing tables are appended to the end of the file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let TOML;
+try {
+  TOML = require('@iarna/toml');
+} catch {
+  console.error('[ecc-codex] Missing dependency: @iarna/toml');
+  console.error('[ecc-codex] Run: npm install   (from the ECC repo root)');
+  process.exit(1);
+}
+
+const ROOT_KEYS = ['approval_policy', 'sandbox_mode', 'web_search', 'notify', 'persistent_instructions'];
+const TABLE_PATHS = [
+  'features',
+  'profiles.strict',
+  'profiles.yolo',
+  'agents',
+  'agents.explorer',
+  'agents.reviewer',
+  'agents.docs_researcher',
+];
+const TOML_HEADER_RE = /^[ \t]*(?:\[[^[\]\n][^\]\n]*\]|\[\[[^[\]\n][^\]\n]*\]\])[ \t]*(?:#.*)?$/m;
+
+function log(message) {
+  console.log(`[ecc-codex] ${message}`);
+}
+
+function warn(message) {
+  console.warn(`[ecc-codex] WARNING: ${message}`);
+}
+
+function getNested(obj, pathParts) {
+  let current = obj;
+  for (const part of pathParts) {
+    if (!current || typeof current !== 'object' || !(part in current)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+function setNested(obj, pathParts, value) {
+  let current = obj;
+  for (let i = 0; i < pathParts.length - 1; i += 1) {
+    const part = pathParts[i];
+    if (!current[part] || typeof current[part] !== 'object' || Array.isArray(current[part])) {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+  current[pathParts[pathParts.length - 1]] = value;
+}
+
+function findFirstTableIndex(raw) {
+  const match = TOML_HEADER_RE.exec(raw);
+  return match ? match.index : -1;
+}
+
+function findTableRange(raw, tablePath) {
+  const escaped = tablePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headerPattern = new RegExp(`^[ \\t]*\\[${escaped}\\][ \\t]*(?:#.*)?$`, 'm');
+  const match = headerPattern.exec(raw);
+  if (!match) {
+    return null;
+  }
+
+  const headerEnd = raw.indexOf('\n', match.index);
+  const bodyStart = headerEnd === -1 ? raw.length : headerEnd + 1;
+  const nextHeaderRel = raw.slice(bodyStart).search(TOML_HEADER_RE);
+  const bodyEnd = nextHeaderRel === -1 ? raw.length : bodyStart + nextHeaderRel;
+  return { bodyStart, bodyEnd };
+}
+
+function ensureTrailingNewline(text) {
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function insertBeforeFirstTable(raw, block) {
+  const normalizedBlock = ensureTrailingNewline(block.trimEnd());
+  const firstTableIndex = findFirstTableIndex(raw);
+  if (firstTableIndex === -1) {
+    const prefix = raw.trimEnd();
+    return prefix ? `${prefix}\n${normalizedBlock}` : normalizedBlock;
+  }
+
+  const before = raw.slice(0, firstTableIndex).trimEnd();
+  const after = raw.slice(firstTableIndex).replace(/^\n+/, '');
+  return `${before}\n\n${normalizedBlock}\n${after}`;
+}
+
+function appendBlock(raw, block) {
+  const prefix = raw.trimEnd();
+  const normalizedBlock = block.trimEnd();
+  return prefix ? `${prefix}\n\n${normalizedBlock}\n` : `${normalizedBlock}\n`;
+}
+
+function stringifyValue(value) {
+  return TOML.stringify({ value }).trim().replace(/^value = /, '');
+}
+
+function updateInlineTableKeys(raw, tablePath, missingKeys) {
+  const pathParts = tablePath.split('.');
+  if (pathParts.length < 2) {
+    return null;
+  }
+
+  const parentPath = pathParts.slice(0, -1).join('.');
+  const parentRange = findTableRange(raw, parentPath);
+  if (!parentRange) {
+    return null;
+  }
+
+  const tableKey = pathParts[pathParts.length - 1];
+  const escapedKey = tableKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const body = raw.slice(parentRange.bodyStart, parentRange.bodyEnd);
+  const lines = body.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const inlinePattern = new RegExp(`^(\\s*${escapedKey}\\s*=\\s*\\{)(.*?)(\\}\\s*(?:#.*)?)$`);
+    const match = inlinePattern.exec(lines[index]);
+    if (!match) {
+      continue;
+    }
+
+    const additions = Object.entries(missingKeys)
+      .map(([key, value]) => `${key} = ${stringifyValue(value)}`)
+      .join(', ');
+    const existingEntries = match[2].trim();
+    const nextEntries = existingEntries ? `${existingEntries}, ${additions}` : additions;
+    lines[index] = `${match[1]}${nextEntries}${match[3]}`;
+    return `${raw.slice(0, parentRange.bodyStart)}${lines.join('\n')}${raw.slice(parentRange.bodyEnd)}`;
+  }
+  return null;
+}
+
+function appendImplicitTable(raw, tablePath, missingKeys) {
+  const candidate = appendBlock(raw, stringifyTable(tablePath, missingKeys));
+  try {
+    TOML.parse(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+function appendToTable(raw, tablePath, block, missingKeys = null) {
+  const range = findTableRange(raw, tablePath);
+  if (!range) {
+    if (missingKeys) {
+      const inlineUpdated = updateInlineTableKeys(raw, tablePath, missingKeys);
+      if (inlineUpdated) {
+        return inlineUpdated;
+      }
+
+      const appendedTable = appendImplicitTable(raw, tablePath, missingKeys);
+      if (appendedTable) {
+        return appendedTable;
+      }
+    }
+    warn(`Skipping missing keys for [${tablePath}] because it has no standalone header and could not be safely updated`);
+    return raw;
+  }
+
+  const before = raw.slice(0, range.bodyEnd).trimEnd();
+  const after = raw.slice(range.bodyEnd).replace(/^\n*/, '\n');
+  return `${before}\n${block.trimEnd()}\n${after}`;
+}
+
+function stringifyRootKeys(keys) {
+  return TOML.stringify(keys).trim();
+}
+
+function stringifyTable(tablePath, value) {
+  const scalarOnly = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (entryValue && typeof entryValue === 'object' && !Array.isArray(entryValue)) {
+      continue;
+    }
+    scalarOnly[key] = entryValue;
+  }
+
+  const snippet = {};
+  setNested(snippet, tablePath.split('.'), scalarOnly);
+  return TOML.stringify(snippet).trim();
+}
+
+function stringifyTableKeys(tableValue) {
+  const lines = [];
+  for (const [key, value] of Object.entries(tableValue)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      continue;
+    }
+    lines.push(TOML.stringify({ [key]: value }).trim());
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const configPath = args.find(arg => !arg.startsWith('-'));
+  const dryRun = args.includes('--dry-run');
+
+  if (!configPath) {
+    console.error('Usage: merge-codex-config.js <config.toml> [--dry-run]');
+    process.exit(1);
+  }
+
+  const referencePath = path.join(__dirname, '..', '..', '.codex', 'config.toml');
+  if (!fs.existsSync(referencePath)) {
+    console.error(`[ecc-codex] Reference config not found: ${referencePath}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(configPath)) {
+    console.error(`[ecc-codex] Config file not found: ${configPath}`);
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  const referenceRaw = fs.readFileSync(referencePath, 'utf8');
+
+  let targetConfig;
+  let referenceConfig;
+  try {
+    targetConfig = TOML.parse(raw);
+    referenceConfig = TOML.parse(referenceRaw);
+  } catch (error) {
+    console.error(`[ecc-codex] Failed to parse TOML: ${error.message}`);
+    process.exit(1);
+  }
+
+  const missingRootKeys = {};
+  for (const key of ROOT_KEYS) {
+    if (referenceConfig[key] !== undefined && targetConfig[key] === undefined) {
+      missingRootKeys[key] = referenceConfig[key];
+    }
+  }
+
+  const missingTables = [];
+  const missingTableKeys = [];
+  for (const tablePath of TABLE_PATHS) {
+    const pathParts = tablePath.split('.');
+    const referenceValue = getNested(referenceConfig, pathParts);
+    if (referenceValue === undefined) {
+      continue;
+    }
+
+    const targetValue = getNested(targetConfig, pathParts);
+    if (targetValue === undefined) {
+      missingTables.push(tablePath);
+      continue;
+    }
+
+    const missingKeys = {};
+    for (const [key, value] of Object.entries(referenceValue)) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        continue;
+      }
+      if (targetValue[key] === undefined) {
+        missingKeys[key] = value;
+      }
+    }
+
+    if (Object.keys(missingKeys).length > 0) {
+      missingTableKeys.push({ tablePath, missingKeys });
+    }
+  }
+
+  if (
+    Object.keys(missingRootKeys).length === 0 &&
+    missingTables.length === 0 &&
+    missingTableKeys.length === 0
+  ) {
+    log('All baseline Codex settings already present. Nothing to do.');
+    return;
+  }
+
+  let nextRaw = raw;
+  if (Object.keys(missingRootKeys).length > 0) {
+    log(`  [add-root] ${Object.keys(missingRootKeys).join(', ')}`);
+    nextRaw = insertBeforeFirstTable(nextRaw, stringifyRootKeys(missingRootKeys));
+  }
+
+  for (const { tablePath, missingKeys } of missingTableKeys) {
+    log(`  [add-keys] [${tablePath}] -> ${Object.keys(missingKeys).join(', ')}`);
+    nextRaw = appendToTable(nextRaw, tablePath, stringifyTableKeys(missingKeys), missingKeys);
+  }
+
+  for (const tablePath of missingTables) {
+    log(`  [add-table] [${tablePath}]`);
+    nextRaw = appendBlock(nextRaw, stringifyTable(tablePath, getNested(referenceConfig, tablePath.split('.'))));
+  }
+
+  if (dryRun) {
+    log('Dry run — would write the merged Codex baseline.');
+    return;
+  }
+
+  fs.writeFileSync(configPath, nextRaw, 'utf8');
+  log('Done. Baseline Codex settings merged.');
+}
+
+main();

package/scripts/codex/merge-mcp-config.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Merge ECC-recommended MCP servers into a Codex config.toml.
+ *
+ * Strategy: ADD-ONLY by default.
+ *   - Parse the TOML to detect which mcp_servers.* sections exist.
+ *   - Append raw TOML text for any missing servers (preserves existing file byte-for-byte).
+ *   - Log warnings when an existing server's config differs from the ECC recommendation.
+ *   - With --update-mcp, also replace existing ECC-managed servers.
+ *
+ * Uses the repo's package-manager abstraction (scripts/lib/package-manager.js)
+ * so MCP launcher commands respect the user's configured package manager.
+ *
+ * Usage:
+ *   node merge-mcp-config.js <config.toml> [--dry-run] [--update-mcp]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseDisabledMcpServers } = require('../lib/mcp-config');
+
+let TOML;
+try {
+  TOML = require('@iarna/toml');
+} catch {
+  console.error('[ecc-mcp] Missing dependency: @iarna/toml');
+  console.error('[ecc-mcp] Run: npm install   (from the ECC repo root)');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Package manager detection
+// ---------------------------------------------------------------------------
+
+let pmConfig;
+try {
+  const { getPackageManager } = require(path.join(__dirname, '..', 'lib', 'package-manager.js'));
+  pmConfig = getPackageManager();
+} catch {
+  // Fallback: if package-manager.js isn't available, default to npx
+  pmConfig = { name: 'npm', config: { name: 'npm', execCmd: 'npx' } };
+}
+
+// Yarn 1.x doesn't support `yarn dlx` — fall back to npx for classic Yarn.
+let resolvedExecCmd = pmConfig.config.execCmd;
+if (pmConfig.name === 'yarn' && resolvedExecCmd === 'yarn dlx') {
+  try {
+    const { execFileSync } = require('child_process');
+    const ver = execFileSync('yarn', ['--version'], { encoding: 'utf8', timeout: 5000 }).trim();
+    if (ver.startsWith('1.')) {
+      resolvedExecCmd = 'npx';
+    }
+  } catch {
+    // Can't detect version — keep yarn dlx and let it fail visibly
+  }
+}
+
+const PM_NAME = pmConfig.config.name || pmConfig.name;
+const PM_EXEC = resolvedExecCmd; // e.g. "pnpm dlx", "npx", "bunx", "yarn dlx"
+const PM_EXEC_PARTS = PM_EXEC.split(/\s+/); // ["pnpm", "dlx"] or ["npx"] or ["bunx"]
+
+// ---------------------------------------------------------------------------
+// ECC-recommended MCP servers
+// ---------------------------------------------------------------------------
+
+// GitHub bootstrap uses bash for token forwarding — this is intentionally
+// shell-based regardless of package manager, since Codex runs on macOS/Linux.
+const GH_BOOTSTRAP = `token=$(gh auth token 2>/dev/null || true); if [ -n "$token" ]; then export GITHUB_PERSONAL_ACCESS_TOKEN="$token"; fi; exec ${PM_EXEC} @modelcontextprotocol/server-github`;
+
+/**
+ * Build a server spec with the detected package manager.
+ * Returns { fields, toml } where fields is for drift detection and
+ * toml is the raw text appended to the file.
+ */
+function dlxServer(name, pkg, extraFields, extraToml) {
+  const args = [...PM_EXEC_PARTS.slice(1), pkg];
+  const fields = { command: PM_EXEC_PARTS[0], args, ...extraFields };
+  const argsStr = JSON.stringify(args).replace(/,/g, ', ');
+  let toml = `[mcp_servers.${name}]\ncommand = "${PM_EXEC_PARTS[0]}"\nargs = ${argsStr}`;
+  if (extraToml) toml += '\n' + extraToml;
+  return { fields, toml };
+}
+
+/** Each entry: key = section name under mcp_servers, value = { toml, fields } */
+const DEFAULT_MCP_STARTUP_TIMEOUT_SEC = 30;
+const DEFAULT_MCP_STARTUP_TIMEOUT_TOML = `startup_timeout_sec = ${DEFAULT_MCP_STARTUP_TIMEOUT_SEC}`;
+
+const ECC_SERVERS = {
+  supabase: dlxServer('supabase', '@supabase/mcp-server-supabase@latest', { startup_timeout_sec: 20.0, tool_timeout_sec: 120.0 }, 'startup_timeout_sec = 20.0\ntool_timeout_sec = 120.0'),
+  playwright: dlxServer('playwright', '@playwright/mcp@latest', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
+  context7: dlxServer('context7', '@upstash/context7-mcp@latest', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
+  exa: {
+    fields: { url: 'https://mcp.exa.ai/mcp' },
+    toml: `[mcp_servers.exa]\nurl = "https://mcp.exa.ai/mcp"`
+  },
+  github: {
+    fields: { command: 'bash', args: ['-lc', GH_BOOTSTRAP], startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC },
+    toml: `[mcp_servers.github]\ncommand = "bash"\nargs = ["-lc", ${JSON.stringify(GH_BOOTSTRAP)}]\n${DEFAULT_MCP_STARTUP_TIMEOUT_TOML}`
+  },
+  memory: dlxServer('memory', '@modelcontextprotocol/server-memory', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML),
+  'sequential-thinking': dlxServer('sequential-thinking', '@modelcontextprotocol/server-sequential-thinking', { startup_timeout_sec: DEFAULT_MCP_STARTUP_TIMEOUT_SEC }, DEFAULT_MCP_STARTUP_TIMEOUT_TOML)
+};
+
+// Append --features arg for supabase after dlxServer builds the base
+ECC_SERVERS.supabase.fields.args.push('--features=account,docs,database,debugging,development,functions,storage,branching');
+ECC_SERVERS.supabase.toml = ECC_SERVERS.supabase.toml.replace(/^(args = \[.*)\]$/m, '$1, "--features=account,docs,database,debugging,development,functions,storage,branching"]');
+
+// Legacy section names that should be treated as an existing ECC server.
+// e.g. older configs shipped [mcp_servers.context7-mcp] instead of [mcp_servers.context7].
+const LEGACY_ALIASES = {
+  context7: ['context7-mcp']
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function log(msg) {
+  console.log(`[ecc-mcp] ${msg}`);
+}
+
+function warn(msg) {
+  console.warn(`[ecc-mcp] WARNING: ${msg}`);
+}
+
+/** Shallow-compare two objects (one level deep, arrays by JSON). */
+function configDiffers(existing, recommended) {
+  for (const key of Object.keys(recommended)) {
+    const a = existing[key];
+    const b = recommended[key];
+    if (Array.isArray(b)) {
+      if (JSON.stringify(a) !== JSON.stringify(b)) return true;
+    } else if (a !== b) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Remove a TOML section and its key-value pairs from raw text.
+ * Matches the section header even if followed by inline comments or whitespace
+ * (e.g. `[mcp_servers.github] # comment`).
+ * Returns the text with the section removed.
+ */
+function removeSectionFromText(text, sectionHeader) {
+  const escaped = sectionHeader.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headerPattern = new RegExp(`^${escaped}(\\s*(#.*)?)?$`);
+  const lines = text.split('\n');
+  const result = [];
+  let skipping = false;
+  for (const line of lines) {
+    const trimmed = line.replace(/\r$/, '');
+    if (headerPattern.test(trimmed)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\[/.test(trimmed)) {
+      skipping = false;
+    }
+    if (!skipping) {
+      result.push(line);
+    }
+  }
+  return result.join('\n');
+}
+
+/**
+ * Collect all TOML sub-section headers for a given server name.
+ * @iarna/toml nests subtables, so `[mcp_servers.supabase.env]` appears as
+ * `parsed.mcp_servers.supabase.env` (nested), NOT as a flat dotted key.
+ * Walk the nested object to find sub-objects that represent TOML sub-tables.
+ */
+function findSubSections(serverObj, prefix) {
+  const sections = [];
+  if (!serverObj || typeof serverObj !== 'object') return sections;
+  for (const key of Object.keys(serverObj)) {
+    const val = serverObj[key];
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      const subPath = `${prefix}.${key}`;
+      sections.push(subPath);
+      sections.push(...findSubSections(val, subPath));
+    }
+  }
+  return sections;
+}
+
+/**
+ * Remove a server and all its sub-sections from raw TOML text.
+ * Uses findSubSections to walk the parsed nested object (not flat keys).
+ */
+function removeServerFromText(raw, serverName, existing) {
+  let result = removeSectionFromText(raw, `[mcp_servers.${serverName}]`);
+  const serverObj = existing[serverName];
+  if (serverObj) {
+    for (const sub of findSubSections(serverObj, serverName)) {
+      result = removeSectionFromText(result, `[mcp_servers.${sub}]`);
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  const configPath = args.find(a => !a.startsWith('-'));
+  const dryRun = args.includes('--dry-run');
+  const updateMcp = args.includes('--update-mcp');
+  const disabledServers = new Set(parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS));
+
+  if (!configPath) {
+    console.error('Usage: merge-mcp-config.js <config.toml> [--dry-run] [--update-mcp]');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(configPath)) {
+    console.error(`[ecc-mcp] Config file not found: ${configPath}`);
+    process.exit(1);
+  }
+
+  log(`Package manager: ${PM_NAME} (exec: ${PM_EXEC})`);
+  if (disabledServers.size > 0) {
+    log(`Disabled via ECC_DISABLED_MCPS: ${[...disabledServers].join(', ')}`);
+  }
+
+  let raw = fs.readFileSync(configPath, 'utf8');
+  let parsed;
+  try {
+    parsed = TOML.parse(raw);
+  } catch (err) {
+    console.error(`[ecc-mcp] Failed to parse ${configPath}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const existing = parsed.mcp_servers || {};
+  const toAppend = [];
+  const toRemoveLog = [];
+
+  for (const [name, spec] of Object.entries(ECC_SERVERS)) {
+    const entry = existing[name];
+    const aliases = LEGACY_ALIASES[name] || [];
+    const legacyName = aliases.find(a => existing[a] && typeof existing[a].command === 'string');
+
+    // Prefer canonical entry over legacy alias
+    const hasCanonical = entry && typeof entry.command === 'string';
+    const resolvedEntry = hasCanonical ? entry : legacyName ? existing[legacyName] : null;
+    // For URL-based servers (exa), check for url field instead of command
+    const urlEntry = !resolvedEntry && entry && typeof entry.url === 'string' ? entry : null;
+    const finalEntry = resolvedEntry || urlEntry;
+    const resolvedLabel = hasCanonical ? name : legacyName || name;
+
+    if (disabledServers.has(name)) {
+      if (finalEntry) {
+        toRemoveLog.push(`mcp_servers.${resolvedLabel} (disabled)`);
+        raw = removeServerFromText(raw, resolvedLabel, existing);
+        if (resolvedLabel !== name) {
+          raw = removeServerFromText(raw, name, existing);
+        }
+      }
+      log(`  [skip] mcp_servers.${name} (disabled)`);
+      continue;
+    }
+
+    if (finalEntry) {
+      if (updateMcp) {
+        // --update-mcp: remove existing section (and legacy alias), will re-add below
+        toRemoveLog.push(`mcp_servers.${resolvedLabel}`);
+        raw = removeServerFromText(raw, resolvedLabel, existing);
+        if (resolvedLabel !== name) {
+          raw = removeServerFromText(raw, name, existing);
+        }
+        if (legacyName && hasCanonical) {
+          toRemoveLog.push(`mcp_servers.${legacyName}`);
+          raw = removeServerFromText(raw, legacyName, existing);
+        }
+        toAppend.push(spec.toml);
+      } else {
+        // Add-only mode: skip, but warn about drift
+        if (legacyName && !hasCanonical) {
+          warn(`mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)`);
+        } else if (configDiffers(finalEntry, spec.fields)) {
+          warn(`mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)`);
+        } else {
+          log(`  [ok] mcp_servers.${name}`);
+        }
+      }
+    } else {
+      log(`  [add] mcp_servers.${name}`);
+      toAppend.push(spec.toml);
+    }
+  }
+
+  const hasRemovals = toRemoveLog.length > 0;
+
+  if (toAppend.length === 0 && !hasRemovals) {
+    log('All ECC MCP servers already present. Nothing to do.');
+    return;
+  }
+
+  const appendText = '\n' + toAppend.join('\n\n') + '\n';
+
+  if (dryRun) {
+    if (toRemoveLog.length > 0) {
+      log('Dry run — would remove and re-add:');
+      for (const label of toRemoveLog) log(`  [remove] ${label}`);
+    }
+    log('Dry run — would append:');
+    console.log(appendText);
+    return;
+  }
+
+  // Write: for add-only, append to preserve existing content byte-for-byte.
+  // For --update-mcp, we modified `raw` above, so write the full file + appended sections.
+  if (updateMcp || hasRemovals) {
+    for (const label of toRemoveLog) log(`  [update] ${label}`);
+    const cleaned = raw.replace(/\n+$/, '\n');
+    fs.writeFileSync(configPath, cleaned + (toAppend.length > 0 ? appendText : ''), 'utf8');
+  } else {
+    fs.appendFileSync(configPath, appendText, 'utf8');
+  }
+
+  if (hasRemovals && toAppend.length === 0) {
+    log(`Done. Removed ${toRemoveLog.length} disabled server(s).`);
+    return;
+  }
+
+  log(`Done. ${toAppend.length} server(s) ${updateMcp ? 'updated' : 'added'}.`);
+}
+
+main();