@saulwade/swl-ses 2.3.1 → 2.4.1

package/schemas/agent-frontmatter.schema.json

@@ -51,6 +51,7 @@
       "oneOf": [
         {
           "enum": [
+            "fable",
             "opus",
             "sonnet",
             "haiku",
@@ -61,13 +62,14 @@
           "pattern": "^claude-(opus|sonnet|haiku|fable)-[0-9]+(-[0-9]+){0,2}$"
         }
       ],
-      "description": "Modelo principal del agente. Se recomienda alias corto (opus/sonnet/haiku), que resuelve al modelo vigente de la familia y se auto-actualiza; 'inherit' para sub-agentes; o nombre completo tipo 'claude-opus-4-8', 'claude-sonnet-5', 'claude-haiku-4-5-20251001'."
+      "description": "Modelo principal del agente. Se recomienda alias corto (fable/opus/sonnet/haiku), que resuelve al modelo vigente de la familia y se auto-actualiza; 'inherit' para sub-agentes; o nombre completo tipo 'claude-fable-5', 'claude-opus-4-8', 'claude-sonnet-5', 'claude-haiku-4-5-20251001'."
     },
     "modeloAlterno": {
       "type": "string",
       "oneOf": [
         {
           "enum": [
+            "fable",
             "opus",
             "sonnet",
             "haiku",

package/scripts/instalador.js

@@ -26,6 +26,7 @@ const { obtenerTransformador } = require('./lib/transformadores');
 const {
   esProtegido,
   crearBackup,
+  rutaBackupSegura,
   registrarBackup,
   limpiarBackups,
   mergeInstintos,
@@ -1245,7 +1246,9 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
           // ALTO (nemesis O6): respaldar el DIRECTORIO COMPLETO (recursos incluidos)
           // antes de sobrescribir — el usuario pudo modificar recursos/ aunque no
           // tocara el SKILL.md. Overwrite controlado en-bloque (no fall-through).
-          const backupDir = path.join(process.cwd(), '.planning', 'backups', `v${versionBackup}`, path.relative(process.cwd(), destino));
+          // rutaBackupSegura contiene el backup dentro del dir versionado incluso
+          // cuando destino está fuera del cwd (install --global — bug 2026-07-03).
+          const backupDir = rutaBackupSegura(process.cwd(), versionBackup, destino);
           let backupOk = false;
           try { copiarDirectorio(destino, backupDir); backupOk = true; } catch (e) { console.log(`  ⚠ Backup de directorio falló (${e.message})`); }
           if (!backupOk) {

package/scripts/lib/expandir-targets.js

@@ -1,71 +1,71 @@
-'use strict';
-
-/**
- * Expansión de --target (CSV) y --all-runtimes para multi-target install.
- *
- * ADR-0019 Sub-fase 2.5.
- *
- * Extraído de bin/swl-ses.js para permitir tests unitarios. NUNCA debe tener
- * side effects fuera de logging — solo manipula la lista de strings.
- *
- * @module scripts/lib/expandir-targets
- */
-
-const { listarRuntimesInstalables, RUNTIMES } = require('./detectar-runtime');
-
-/**
- * Expande las opciones del CLI a un array de target IDs.
- *
- * Reglas:
- *  - `all_runtimes` tiene prioridad sobre `target`. Si ambos vienen, se loggea
- *    aviso (vía `logger.warn`) y se usa `all_runtimes`.
- *  - `target='a,b,c'` → ['a','b','c'].
- *  - `target='claude'` → ['claude'].
- *  - Sin nada → ['claude'] (default histórico, backward-compat).
- *  - Duplicados se deduplican preservando el primer orden.
- *  - Targets desconocidos se omiten con aviso (logger.warn).
- *
- * @param {object} opciones - Objeto con `target` (string|undefined) y `all_runtimes` (bool).
- * @param {object} [logger] - Sustituible para tests. Default console.
- * @returns {{ targets: string[], omitidos: string[], errores: string[] }}
- */
-function expandirTargets(opciones, logger) {
-  const log = logger || console;
-  const omitidos = [];
-  const errores = [];
-
-  let candidatos;
-  if (opciones.all_runtimes) {
-    if (opciones.target && typeof opciones.target === 'string') {
-      log.warn && log.warn('[expandir-targets] --all-runtimes tiene prioridad sobre --target; se ignora --target.');
-    }
-    candidatos = listarRuntimesInstalables();
-  } else if (typeof opciones.target === 'string' && opciones.target.includes(',')) {
-    candidatos = opciones.target.split(',').map(s => s.trim()).filter(Boolean);
-  } else if (typeof opciones.target === 'string' && opciones.target.length > 0) {
-    candidatos = [opciones.target.trim()];
-  } else {
-    candidatos = ['claude']; // backward-compat
-  }
-
-  const visto = new Set();
-  const targets = [];
-  for (const t of candidatos) {
-    if (visto.has(t)) continue;
-    visto.add(t);
-    if (!RUNTIMES[t]) {
-      log.warn && log.warn(`[expandir-targets] Target desconocido omitido: "${t}". Disponibles: ${Object.keys(RUNTIMES).join(', ')}`);
-      omitidos.push(t);
-      continue;
-    }
-    targets.push(t);
-  }
-
-  if (targets.length === 0) {
-    errores.push('Ningún target válido tras expansión.');
-  }
-
-  return { targets, omitidos, errores };
-}
-
-module.exports = { expandirTargets };
+'use strict';
+
+/**
+ * Expansión de --target (CSV) y --all-runtimes para multi-target install.
+ *
+ * ADR-0019 Sub-fase 2.5.
+ *
+ * Extraído de bin/swl-ses.js para permitir tests unitarios. NUNCA debe tener
+ * side effects fuera de logging — solo manipula la lista de strings.
+ *
+ * @module scripts/lib/expandir-targets
+ */
+
+const { listarRuntimesInstalables, RUNTIMES } = require('./detectar-runtime');
+
+/**
+ * Expande las opciones del CLI a un array de target IDs.
+ *
+ * Reglas:
+ *  - `all_runtimes` tiene prioridad sobre `target`. Si ambos vienen, se loggea
+ *    aviso (vía `logger.warn`) y se usa `all_runtimes`.
+ *  - `target='a,b,c'` → ['a','b','c'].
+ *  - `target='claude'` → ['claude'].
+ *  - Sin nada → ['claude'] (default histórico, backward-compat).
+ *  - Duplicados se deduplican preservando el primer orden.
+ *  - Targets desconocidos se omiten con aviso (logger.warn).
+ *
+ * @param {object} opciones - Objeto con `target` (string|undefined) y `all_runtimes` (bool).
+ * @param {object} [logger] - Sustituible para tests. Default console.
+ * @returns {{ targets: string[], omitidos: string[], errores: string[] }}
+ */
+function expandirTargets(opciones, logger) {
+  const log = logger || console;
+  const omitidos = [];
+  const errores = [];
+
+  let candidatos;
+  if (opciones.all_runtimes) {
+    if (opciones.target && typeof opciones.target === 'string') {
+      log.warn && log.warn('[expandir-targets] --all-runtimes tiene prioridad sobre --target; se ignora --target.');
+    }
+    candidatos = listarRuntimesInstalables();
+  } else if (typeof opciones.target === 'string' && opciones.target.includes(',')) {
+    candidatos = opciones.target.split(',').map(s => s.trim()).filter(Boolean);
+  } else if (typeof opciones.target === 'string' && opciones.target.length > 0) {
+    candidatos = [opciones.target.trim()];
+  } else {
+    candidatos = ['claude']; // backward-compat
+  }
+
+  const visto = new Set();
+  const targets = [];
+  for (const t of candidatos) {
+    if (visto.has(t)) continue;
+    visto.add(t);
+    if (!RUNTIMES[t]) {
+      log.warn && log.warn(`[expandir-targets] Target desconocido omitido: "${t}". Disponibles: ${Object.keys(RUNTIMES).join(', ')}`);
+      omitidos.push(t);
+      continue;
+    }
+    targets.push(t);
+  }
+
+  if (targets.length === 0) {
+    errores.push('Ningún target válido tras expansión.');
+  }
+
+  return { targets, omitidos, errores };
+}
+
+module.exports = { expandirTargets };

package/scripts/lib/preservar-usuario.js

@@ -34,7 +34,7 @@ const path = require('path');
  *   - /swl:evolucionar → skills auto-generados en habilidades/
  *   - /swl:crear-skill → skills nuevos en habilidades/
  *   - session-store → .planning/sessions/*.json
- *   - context-compressor → .planning/COMPACTACION.md
+ *   - /swl:compactar → .planning/COMPACTACION.md
  *   - cron-store → .planning/cron/
  *   - gateway → .planning/gateway-sessions.json
  *   - agent-comms → .planning/comms/
@@ -181,6 +181,41 @@ function dirBackup(baseDir, version) {
   return path.join(baseDir, '.planning', 'backups', `v${version}`);
 }
 
+/**
+ * Subruta segura de un archivo DENTRO del directorio de backups.
+ *
+ * Un destino fuera de baseDir (install --global: ~/.claude, ~/.openclaude)
+ * produce un path.relative con segmentos '..' que ESCAPAN del directorio
+ * versionado: `.planning/backups/v2.3.1/../../.claude/...` colapsa a
+ * `.planning/.claude/...` (bug 2026-07-03: 1147 backups globales aterrizaron
+ * fuera del dir de backups y aparecieron como archivos nuevos en el repo).
+ * Se neutralizan '..', '.' y dos puntos de unidad preservando la estructura.
+ *
+ * @param {string} baseDir      - Raíz del proyecto.
+ * @param {string} rutaAbsoluta - Ruta absoluta del archivo a respaldar.
+ * @returns {string} Subruta relativa contenida (sin '..').
+ */
+function subrutaBackupSegura(baseDir, rutaAbsoluta) {
+  return path.relative(baseDir, rutaAbsoluta)
+    .split(/[\\/]/)
+    .filter(s => s && s !== '..' && s !== '.')
+    .map(s => s.replace(/:/g, ''))
+    .join(path.sep);
+}
+
+/**
+ * Ruta completa de backup para un archivo, garantizada dentro del
+ * directorio versionado de backups.
+ *
+ * @param {string} baseDir         - Raíz del proyecto.
+ * @param {string} versionAnterior - Versión que se está sobreescribiendo.
+ * @param {string} rutaAbsoluta    - Ruta absoluta del archivo a respaldar.
+ * @returns {string} Ruta absoluta del backup.
+ */
+function rutaBackupSegura(baseDir, versionAnterior, rutaAbsoluta) {
+  return path.join(dirBackup(baseDir, versionAnterior), subrutaBackupSegura(baseDir, rutaAbsoluta));
+}
+
 /**
  * Crea un backup de un archivo antes de sobreescribirlo.
  *
@@ -195,10 +230,8 @@ function crearBackup(baseDir, rutaAbsoluta, versionAnterior) {
   }
 
   try {
-    const rutaRelativa = path.relative(baseDir, rutaAbsoluta);
-    const backupDir    = dirBackup(baseDir, versionAnterior);
-    const rutaBackup   = path.join(backupDir, rutaRelativa);
-    const dirPadre     = path.dirname(rutaBackup);
+    const rutaBackup = rutaBackupSegura(baseDir, versionAnterior, rutaAbsoluta);
+    const dirPadre   = path.dirname(rutaBackup);
 
     if (!fs.existsSync(dirPadre)) {
       fs.mkdirSync(dirPadre, { recursive: true });
@@ -573,6 +606,7 @@ module.exports = {
 
   // Nivel 2: Backup
   crearBackup,
+  rutaBackupSegura,
   registrarBackup,
   listarBackups,
   restaurarBackup,

package/scripts/lib/toml-merge.js

@@ -1,204 +1,204 @@
-'use strict';
-
-/**
- * Merge mínimo de secciones TOML — zero-deps.
- *
- * Opera sobre el formato concreto de `~/.codex/config.toml` (OpenAI Codex CLI):
- *   [mcp_servers.<name>]
- *   command = "node"
- *   args = ["...", "..."]
- *   [mcp_servers.<name>.env]
- *   KEY = "value"
- *
- * Reglas:
- *  - NUNCA reescribe el archivo entero. Solo agrega o reemplaza la sección
- *    `[mcp_servers.<name>]` indicada (incluyendo sub-tabla `.env`).
- *  - Si el archivo no existe lo crea con permisos 0600.
- *  - Si el archivo tiene comentarios o secciones desconocidas, las preserva.
- *  - Bloque "owned" delimitado por marcadores `# SWL-MCP-BEGIN <name>` /
- *    `# SWL-MCP-END <name>` para permitir actualizaciones idempotentes.
- *
- * NO soporta:
- *  - TOML completo (arrays multilínea complejos, inline tables, etc.)
- *  - Multi-section nested tables fuera de `mcp_servers.*`
- *
- * Si en el futuro Codex publica un comando idempotente `codex mcp add --idempotent`
- * podemos delegarle el trabajo y deprecar este helper.
- *
- * @module scripts/lib/toml-merge
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const { atomicWriteSync } = require('../../hooks/lib/atomic-write');
-
-const BEGIN_PREFIX = '# SWL-MCP-BEGIN';
-const END_PREFIX = '# SWL-MCP-END';
-
-/**
- * Serializa un servidor MCP en bloque TOML.
- *
- * @param {string} name - Nombre del server (identificador en config.toml).
- * @param {{ command: string, args?: string[], env?: Record<string,string> }} cfg
- * @returns {string} Bloque TOML con marcadores.
- */
-function serializarServidor(name, cfg) {
-  if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(name)) {
-    throw new Error(`Nombre de MCP server inválido: "${name}". Solo [a-zA-Z0-9_-].`);
-  }
-  if (!cfg || typeof cfg.command !== 'string' || cfg.command.length === 0) {
-    throw new Error(`MCP server "${name}" requiere "command" string no vacío.`);
-  }
-
-  const lineas = [];
-  lineas.push(`${BEGIN_PREFIX} ${name}`);
-  lineas.push(`[mcp_servers.${name}]`);
-  lineas.push(`command = ${tomlString(cfg.command)}`);
-
-  if (Array.isArray(cfg.args) && cfg.args.length > 0) {
-    const items = cfg.args.map(tomlString).join(', ');
-    lineas.push(`args = [${items}]`);
-  }
-
-  if (cfg.env && typeof cfg.env === 'object' && Object.keys(cfg.env).length > 0) {
-    lineas.push('');
-    lineas.push(`[mcp_servers.${name}.env]`);
-    for (const [k, v] of Object.entries(cfg.env)) {
-      if (typeof v !== 'string') {
-        throw new Error(`MCP server "${name}" env.${k} debe ser string (recibido: ${typeof v}).`);
-      }
-      // Solo claves alfanuméricas/_ en env names — TOML restricción razonable
-      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {
-        throw new Error(`MCP server "${name}" env key inválido: "${k}".`);
-      }
-      lineas.push(`${k} = ${tomlString(v)}`);
-    }
-  }
-
-  lineas.push(`${END_PREFIX} ${name}`);
-  return lineas.join('\n');
-}
-
-/**
- * Escapa un string para TOML usando comillas dobles.
- * No usa basic-string raw para evitar pitfalls con backslashes.
- */
-function tomlString(s) {
-  // TOML basic string: escape backslash, doblequote, control chars.
-  const escapado = String(s)
-    .replace(/\\/g, '\\\\')
-    .replace(/"/g, '\\"')
-    .replace(/\n/g, '\\n')
-    .replace(/\r/g, '\\r')
-    .replace(/\t/g, '\\t');
-  return `"${escapado}"`;
-}
-
-/**
- * Inserta o actualiza un servidor MCP en `config.toml`.
- *
- * Idempotente: si el bloque ya existe con el mismo contenido, no escribe.
- * Si existe con contenido distinto, lo reemplaza dentro de los marcadores.
- * Si no existe, lo agrega al final del archivo precedido de línea en blanco.
- *
- * @param {string} rutaConfig - Path absoluto a config.toml (típicamente ~/.codex/config.toml).
- * @param {string} name - Nombre del MCP server (clave de [mcp_servers.<name>]).
- * @param {{ command: string, args?: string[], env?: Record<string,string> }} cfg
- * @returns {{ accion: 'creado' | 'agregado' | 'actualizado' | 'sin-cambios', ruta: string }}
- */
-function upsertMcpServer(rutaConfig, name, cfg) {
-  const bloqueNuevo = serializarServidor(name, cfg);
-
-  let existente = '';
-  let existia = false;
-  try {
-    existente = fs.readFileSync(rutaConfig, 'utf-8');
-    existia = true;
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-    // Archivo no existe — se crea
-  }
-
-  const beginTag = `${BEGIN_PREFIX} ${name}`;
-  const endTag = `${END_PREFIX} ${name}`;
-
-  if (!existia) {
-    const dir = path.dirname(rutaConfig);
-    fs.mkdirSync(dir, { recursive: true });
-    const contenido = `# config.toml de Codex CLI — gestionado parcialmente por swl-ses\n# Bloques delimitados por SWL-MCP-BEGIN/END son regenerables.\n\n${bloqueNuevo}\n`;
-    atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
-    return { accion: 'creado', ruta: rutaConfig };
-  }
-
-  const idxBegin = existente.indexOf(beginTag);
-  const idxEnd = existente.indexOf(endTag);
-
-  // Caso 1: no existe el bloque → append al final
-  if (idxBegin === -1 || idxEnd === -1) {
-    const separador = existente.endsWith('\n') ? '\n' : '\n\n';
-    const contenido = existente + separador + bloqueNuevo + '\n';
-    atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
-    return { accion: 'agregado', ruta: rutaConfig };
-  }
-
-  // Caso 2: existe — comparar contenido
-  // Calculamos fin REAL incluyendo el endTag completo.
-  const finBloqueExistente = idxEnd + endTag.length;
-  const bloqueExistente = existente.slice(idxBegin, finBloqueExistente);
-
-  if (bloqueExistente === bloqueNuevo) {
-    return { accion: 'sin-cambios', ruta: rutaConfig };
-  }
-
-  const contenido = existente.slice(0, idxBegin) + bloqueNuevo + existente.slice(finBloqueExistente);
-  atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
-  return { accion: 'actualizado', ruta: rutaConfig };
-}
-
-/**
- * Elimina un bloque MCP server por nombre. Idempotente: si no existe, no hace nada.
- *
- * @param {string} rutaConfig
- * @param {string} name
- * @returns {{ accion: 'eliminado' | 'sin-cambios', ruta: string }}
- */
-function removeMcpServer(rutaConfig, name) {
-  let existente = '';
-  try {
-    existente = fs.readFileSync(rutaConfig, 'utf-8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return { accion: 'sin-cambios', ruta: rutaConfig };
-    throw err;
-  }
-
-  const beginTag = `${BEGIN_PREFIX} ${name}`;
-  const endTag = `${END_PREFIX} ${name}`;
-  const idxBegin = existente.indexOf(beginTag);
-  const idxEnd = existente.indexOf(endTag);
-
-  if (idxBegin === -1 || idxEnd === -1) {
-    return { accion: 'sin-cambios', ruta: rutaConfig };
-  }
-
-  // Quitar bloque + posible newline previo y posterior (cosmético)
-  let inicio = idxBegin;
-  let fin = idxEnd + endTag.length;
-  // Comer un \n previo si existe (no comer doble \n para preservar separadores entre secciones)
-  if (inicio > 0 && existente[inicio - 1] === '\n') inicio--;
-  if (fin < existente.length && existente[fin] === '\n') fin++;
-
-  const contenido = existente.slice(0, inicio) + existente.slice(fin);
-  atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
-  return { accion: 'eliminado', ruta: rutaConfig };
-}
-
-module.exports = {
-  upsertMcpServer,
-  removeMcpServer,
-  serializarServidor,
-  // Para tests
-  _tomlString: tomlString,
-  BEGIN_PREFIX,
-  END_PREFIX,
-};
+'use strict';
+
+/**
+ * Merge mínimo de secciones TOML — zero-deps.
+ *
+ * Opera sobre el formato concreto de `~/.codex/config.toml` (OpenAI Codex CLI):
+ *   [mcp_servers.<name>]
+ *   command = "node"
+ *   args = ["...", "..."]
+ *   [mcp_servers.<name>.env]
+ *   KEY = "value"
+ *
+ * Reglas:
+ *  - NUNCA reescribe el archivo entero. Solo agrega o reemplaza la sección
+ *    `[mcp_servers.<name>]` indicada (incluyendo sub-tabla `.env`).
+ *  - Si el archivo no existe lo crea con permisos 0600.
+ *  - Si el archivo tiene comentarios o secciones desconocidas, las preserva.
+ *  - Bloque "owned" delimitado por marcadores `# SWL-MCP-BEGIN <name>` /
+ *    `# SWL-MCP-END <name>` para permitir actualizaciones idempotentes.
+ *
+ * NO soporta:
+ *  - TOML completo (arrays multilínea complejos, inline tables, etc.)
+ *  - Multi-section nested tables fuera de `mcp_servers.*`
+ *
+ * Si en el futuro Codex publica un comando idempotente `codex mcp add --idempotent`
+ * podemos delegarle el trabajo y deprecar este helper.
+ *
+ * @module scripts/lib/toml-merge
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { atomicWriteSync } = require('../../hooks/lib/atomic-write');
+
+const BEGIN_PREFIX = '# SWL-MCP-BEGIN';
+const END_PREFIX = '# SWL-MCP-END';
+
+/**
+ * Serializa un servidor MCP en bloque TOML.
+ *
+ * @param {string} name - Nombre del server (identificador en config.toml).
+ * @param {{ command: string, args?: string[], env?: Record<string,string> }} cfg
+ * @returns {string} Bloque TOML con marcadores.
+ */
+function serializarServidor(name, cfg) {
+  if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new Error(`Nombre de MCP server inválido: "${name}". Solo [a-zA-Z0-9_-].`);
+  }
+  if (!cfg || typeof cfg.command !== 'string' || cfg.command.length === 0) {
+    throw new Error(`MCP server "${name}" requiere "command" string no vacío.`);
+  }
+
+  const lineas = [];
+  lineas.push(`${BEGIN_PREFIX} ${name}`);
+  lineas.push(`[mcp_servers.${name}]`);
+  lineas.push(`command = ${tomlString(cfg.command)}`);
+
+  if (Array.isArray(cfg.args) && cfg.args.length > 0) {
+    const items = cfg.args.map(tomlString).join(', ');
+    lineas.push(`args = [${items}]`);
+  }
+
+  if (cfg.env && typeof cfg.env === 'object' && Object.keys(cfg.env).length > 0) {
+    lineas.push('');
+    lineas.push(`[mcp_servers.${name}.env]`);
+    for (const [k, v] of Object.entries(cfg.env)) {
+      if (typeof v !== 'string') {
+        throw new Error(`MCP server "${name}" env.${k} debe ser string (recibido: ${typeof v}).`);
+      }
+      // Solo claves alfanuméricas/_ en env names — TOML restricción razonable
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {
+        throw new Error(`MCP server "${name}" env key inválido: "${k}".`);
+      }
+      lineas.push(`${k} = ${tomlString(v)}`);
+    }
+  }
+
+  lineas.push(`${END_PREFIX} ${name}`);
+  return lineas.join('\n');
+}
+
+/**
+ * Escapa un string para TOML usando comillas dobles.
+ * No usa basic-string raw para evitar pitfalls con backslashes.
+ */
+function tomlString(s) {
+  // TOML basic string: escape backslash, doblequote, control chars.
+  const escapado = String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+  return `"${escapado}"`;
+}
+
+/**
+ * Inserta o actualiza un servidor MCP en `config.toml`.
+ *
+ * Idempotente: si el bloque ya existe con el mismo contenido, no escribe.
+ * Si existe con contenido distinto, lo reemplaza dentro de los marcadores.
+ * Si no existe, lo agrega al final del archivo precedido de línea en blanco.
+ *
+ * @param {string} rutaConfig - Path absoluto a config.toml (típicamente ~/.codex/config.toml).
+ * @param {string} name - Nombre del MCP server (clave de [mcp_servers.<name>]).
+ * @param {{ command: string, args?: string[], env?: Record<string,string> }} cfg
+ * @returns {{ accion: 'creado' | 'agregado' | 'actualizado' | 'sin-cambios', ruta: string }}
+ */
+function upsertMcpServer(rutaConfig, name, cfg) {
+  const bloqueNuevo = serializarServidor(name, cfg);
+
+  let existente = '';
+  let existia = false;
+  try {
+    existente = fs.readFileSync(rutaConfig, 'utf-8');
+    existia = true;
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    // Archivo no existe — se crea
+  }
+
+  const beginTag = `${BEGIN_PREFIX} ${name}`;
+  const endTag = `${END_PREFIX} ${name}`;
+
+  if (!existia) {
+    const dir = path.dirname(rutaConfig);
+    fs.mkdirSync(dir, { recursive: true });
+    const contenido = `# config.toml de Codex CLI — gestionado parcialmente por swl-ses\n# Bloques delimitados por SWL-MCP-BEGIN/END son regenerables.\n\n${bloqueNuevo}\n`;
+    atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
+    return { accion: 'creado', ruta: rutaConfig };
+  }
+
+  const idxBegin = existente.indexOf(beginTag);
+  const idxEnd = existente.indexOf(endTag);
+
+  // Caso 1: no existe el bloque → append al final
+  if (idxBegin === -1 || idxEnd === -1) {
+    const separador = existente.endsWith('\n') ? '\n' : '\n\n';
+    const contenido = existente + separador + bloqueNuevo + '\n';
+    atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
+    return { accion: 'agregado', ruta: rutaConfig };
+  }
+
+  // Caso 2: existe — comparar contenido
+  // Calculamos fin REAL incluyendo el endTag completo.
+  const finBloqueExistente = idxEnd + endTag.length;
+  const bloqueExistente = existente.slice(idxBegin, finBloqueExistente);
+
+  if (bloqueExistente === bloqueNuevo) {
+    return { accion: 'sin-cambios', ruta: rutaConfig };
+  }
+
+  const contenido = existente.slice(0, idxBegin) + bloqueNuevo + existente.slice(finBloqueExistente);
+  atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
+  return { accion: 'actualizado', ruta: rutaConfig };
+}
+
+/**
+ * Elimina un bloque MCP server por nombre. Idempotente: si no existe, no hace nada.
+ *
+ * @param {string} rutaConfig
+ * @param {string} name
+ * @returns {{ accion: 'eliminado' | 'sin-cambios', ruta: string }}
+ */
+function removeMcpServer(rutaConfig, name) {
+  let existente = '';
+  try {
+    existente = fs.readFileSync(rutaConfig, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { accion: 'sin-cambios', ruta: rutaConfig };
+    throw err;
+  }
+
+  const beginTag = `${BEGIN_PREFIX} ${name}`;
+  const endTag = `${END_PREFIX} ${name}`;
+  const idxBegin = existente.indexOf(beginTag);
+  const idxEnd = existente.indexOf(endTag);
+
+  if (idxBegin === -1 || idxEnd === -1) {
+    return { accion: 'sin-cambios', ruta: rutaConfig };
+  }
+
+  // Quitar bloque + posible newline previo y posterior (cosmético)
+  let inicio = idxBegin;
+  let fin = idxEnd + endTag.length;
+  // Comer un \n previo si existe (no comer doble \n para preservar separadores entre secciones)
+  if (inicio > 0 && existente[inicio - 1] === '\n') inicio--;
+  if (fin < existente.length && existente[fin] === '\n') fin++;
+
+  const contenido = existente.slice(0, inicio) + existente.slice(fin);
+  atomicWriteSync(rutaConfig, contenido, 'utf8', { mode: 0o600 });
+  return { accion: 'eliminado', ruta: rutaConfig };
+}
+
+module.exports = {
+  upsertMcpServer,
+  removeMcpServer,
+  serializarServidor,
+  // Para tests
+  _tomlString: tomlString,
+  BEGIN_PREFIX,
+  END_PREFIX,
+};