@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/lib/transformadores/codex.js

@@ -1,115 +1,375 @@
-'use strict';
-
-const TransformadorBase = require('./base');
-
-class TransformadorCodex extends TransformadorBase {
-  transformarAgente(contenidoMd, metadatos) {
-    // Codex no soporta agentes individuales
-    // Retornar contenido para consolidación
-    return {
-      contenido: contenidoMd,
-      consolidar: true,
-      rutaRelativa: 'AGENTS.md',
-      dirBase: '.',
-    };
-  }
-
-  transformarSkill(dirSkill, metadatos) {
-    // Codex NO soporta skills
-    return null;
-  }
-
-  transformarRegla(contenidoMd, metadatos) {
-    // Consolidar en AGENTS.md
-    return {
-      contenido: contenidoMd,
-      consolidar: true,
-      rutaRelativa: 'AGENTS.md',
-      dirBase: '.',
-    };
-  }
-
-  transformarComando(contenidoMd, metadatos) {
-    // Codex NO soporta comandos
-    return null;
-  }
-
-  generarArchivoInstrucciones(contexto) {
-    const lineas = [];
-    lineas.push('# AGENTS.md — Sistema SWL');
-    lineas.push('');
-    lineas.push(`> Generado por swl-ses v${contexto.version} — ${new Date().toISOString().split('T')[0]}`);
-    lineas.push('> NO editar manualmente. Regenerar con: npx @saulwade/swl-ses@latest install --target codex');
-    lineas.push('');
-    lineas.push(`Sistema: swl-ses v${contexto.version}`);
-    lineas.push(`Perfil: ${contexto.perfil}`);
-    lineas.push('');
-
-    // Tabla de agentes
-    if (contexto.agentes && contexto.agentes.length > 0) {
-      lineas.push('## Agentes disponibles');
-      lineas.push('');
-      lineas.push('| Agente | Descripción |');
-      lineas.push('|--------|-------------|');
-      for (const ag of contexto.agentes) {
-        const { frontmatter } = this.parsearFrontmatter(ag.contenido);
-        const nombre = frontmatter.name || ag.nombre || 'sin-nombre';
-        const desc = frontmatter.description || '';
-        const descCorta = desc.length > 100 ? desc.slice(0, 97) + '...' : desc;
-        lineas.push(`| ${nombre} | ${descCorta} |`);
-      }
-      lineas.push('');
-    }
-
-    // Reglas (solo las core, concatenadas)
-    if (contexto.reglas && contexto.reglas.length > 0) {
-      lineas.push('## Reglas obligatorias');
-      lineas.push('');
-      for (const regla of contexto.reglas) {
-        lineas.push(regla.contenido);
-        lineas.push('');
-        lineas.push('---');
-        lineas.push('');
-      }
-    }
-
-    // Skills (solo resumen)
-    if (contexto.skills && contexto.skills.length > 0) {
-      lineas.push('## Skills disponibles (referencia)');
-      lineas.push('');
-      lineas.push('| Skill | Descripción |');
-      lineas.push('|-------|-------------|');
-      for (const sk of contexto.skills) {
-        lineas.push(`| ${sk.nombre} | ${sk.descripcion || ''} |`);
-      }
-      lineas.push('');
-    }
-
-    let resultado = lineas.join('\n');
-
-    // Limitar a 50KB
-    const MAX_SIZE = 50 * 1024;
-    if (Buffer.byteLength(resultado, 'utf-8') > MAX_SIZE) {
-      // Truncar reglas si excede
-      const aviso = '\n\n> **Nota**: Contenido truncado por límite de tamaño. Instalar con perfil más específico para reducir el tamaño.\n';
-      resultado = resultado.slice(0, MAX_SIZE - 200) + aviso;
-    }
-
-    return {
-      contenido: resultado,
-      rutaRelativa: 'AGENTS.md',
-      dirBase: '.',
-    };
-  }
-
-  transformarHooks(hooksConfig, opciones) {
-    // Codex NO soporta hooks
-    return null;
-  }
-
-  soportaTipo(tipo) {
-    return ['agentes', 'reglas'].includes(tipo);
-  }
-}
-
-module.exports = TransformadorCodex;
+'use strict';
+
+/**
+ * Transformador para OpenAI Codex CLI.
+ *
+ * Codex consume:
+ *  - `AGENTS.md` por proyecto (cwd) Y/O `~/.codex/AGENTS.md` global.
+ *  - `~/.codex/config.toml` para configurar MCP servers, sandbox y profiles.
+ *  - NO carga skills, comandos slash propios (a 2026-05-15, no confirmado en docs oficiales),
+ *    ni hooks como Claude Code los entiende.
+ *
+ * Estrategia v1.5.0 (ADR-0019):
+ *  - `--global` → AGENTS.md va a `~/.codex/AGENTS.md`. Sub-fase 1 ADR-0019 punto 1.
+ *  - `--local` → AGENTS.md va a `<proyecto>/AGENTS.md`. Default.
+ *  - Bloque SWL delimitado por marcadores `<!-- SWL-BEGIN -->` / `<!-- SWL-END -->`
+ *    para preservar contenido pre-existente del usuario en AGENTS.md (parche a la versión previa,
+ *    que sobrescribía el archivo completo destruyendo notas del equipo).
+ *  - `withMcp: true` autoregistra `swl-memory` en `~/.codex/config.toml` bajo
+ *    `[mcp_servers.swl-memory]` mediante `lib/toml-merge.js` zero-deps.
+ *  - Skills y comandos slash: descartados en este target. Documentado en INSTALACION.md §3.5.
+ */
+
+const path = require('path');
+const TransformadorBase = require('./base');
+const { upsertMcpServer } = require('../toml-merge');
+
+class TransformadorCodex extends TransformadorBase {
+  /**
+   * Sub-fase 11 v1.5.0: Codex CLI SÍ acepta agentes individuales en formato
+   * TOML (developers.openai.com/codex/subagents). Path: `~/.codex/agents/<name>.toml`
+   * (global) o `.codex/agents/<name>.toml` (project).
+   *
+   * Campos del TOML:
+   *   - name (required)
+   *   - description (required)
+   *   - developer_instructions (required) — multi-line literal del cuerpo Markdown
+   *   - model (opcional) — heredado del frontmatter SWL si existe
+   *   - sandbox_mode (opcional) — mapeado desde permisosEscritura=false → "read-only"
+   *
+   * El cuerpo del .md SWL completo (después del frontmatter) se inserta como
+   * developer_instructions usando TOML literal multi-line strings `'''...'''`
+   * para preservar el contenido sin escapes complejos.
+   *
+   * AGENTS.md sigue conteniendo tabla referencial (redundante pero útil como
+   * índice rápido). Sub-fase 11 es ADITIVA — no afecta el flujo existente.
+   */
+  transformarAgente(contenidoMd, metadatos) {
+    const { frontmatter, cuerpo } = this.parsearFrontmatter(contenidoMd);
+
+    const name = frontmatter.name || (metadatos.nombreArchivo || '').replace(/\.md$/i, '');
+    if (!name) {
+      // Sin nombre, no podemos generar TOML válido — fallback a AGENTS.md consolidado.
+      return {
+        contenido: contenidoMd,
+        consolidar: true,
+        rutaRelativa: 'AGENTS.md',
+      };
+    }
+
+    const description = String(frontmatter.description || '').replace(/\s+/g, ' ').trim();
+    const developerInstructions = String(cuerpo || '').trim();
+
+    const toml = this._construirTomlAgente({
+      name,
+      description,
+      developer_instructions: developerInstructions,
+      model: frontmatter.model || null,
+      sandbox_mode: (frontmatter.permisosEscritura === false) ? 'read-only' : null,
+    });
+
+    const baseNombre = (metadatos.nombreArchivo || `${name}.md`).replace(/\.md$/i, '');
+    return {
+      contenido: toml,
+      rutaRelativa: `agents/${baseNombre}.toml`,
+    };
+  }
+
+  /**
+   * Serializa un agente Codex a TOML. Helper privado.
+   * Usa literal multi-line strings `'''...'''` para developer_instructions
+   * (no procesa escapes — preserva Markdown crudo). Si el cuerpo contiene
+   * `'''` literal, hace fallback a basic multi-line `"""..."""` con escape.
+   */
+  _construirTomlAgente(campos) {
+    const lineas = [];
+    lineas.push(`# Generado por swl-ses — formato Codex agent TOML (Sub-fase 11 v1.5.0)`);
+    lineas.push(`# Fuente: developers.openai.com/codex/subagents`);
+    lineas.push('');
+    lineas.push(`name = ${this._tomlBasicString(campos.name)}`);
+    lineas.push(`description = ${this._tomlBasicString(campos.description)}`);
+    if (campos.model) lineas.push(`model = ${this._tomlBasicString(campos.model)}`);
+    if (campos.sandbox_mode) lineas.push(`sandbox_mode = ${this._tomlBasicString(campos.sandbox_mode)}`);
+    lineas.push('');
+    lineas.push(`developer_instructions = ${this._tomlMultiline(campos.developer_instructions)}`);
+    return lineas.join('\n') + '\n';
+  }
+
+  _tomlBasicString(s) {
+    const escapado = String(s)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
+      .replace(/\t/g, '\\t');
+    return `"${escapado}"`;
+  }
+
+  _tomlMultiline(s) {
+    const contenido = String(s);
+    if (!contenido.includes("'''")) {
+      // Literal multi-line: preserva contenido sin escapes.
+      return `'''\n${contenido}\n'''`;
+    }
+    // Fallback a basic multi-line con escape de \ y """.
+    const escapado = contenido.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""');
+    return `"""\n${escapado}\n"""`;
+  }
+
+  transformarSkill(dirSkill, metadatos) {
+    // Sub-fase 10 v1.5.0: corrección del path. La doc oficial OpenAI
+    // (developers.openai.com/codex/skills) declara `$HOME/.agents/skills/` y
+    // `.agents/skills/` como ubicaciones válidas — NO `~/.codex/skills/`.
+    // El path `~/.codex/skills/` que apareció en Sub-fase 8 era de una sample
+    // sub-doc del repo (no canónica). Ahora apunta al path correcto vía dirBase.
+    const dirBaseGlobal = path.join(require('os').homedir(), '.agents');
+    return {
+      tipo: 'directorio',
+      rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
+      dirBase: dirBaseGlobal,
+    };
+  }
+
+  transformarRegla(contenidoMd, metadatos) {
+    return {
+      contenido: contenidoMd,
+      consolidar: true,
+      rutaRelativa: 'AGENTS.md',
+    };
+  }
+
+  transformarComando(contenidoMd, metadatos) {
+    // Codex NO soporta comandos slash custom desde filesystem (verificado
+    // 2026-05-15 en developers.openai.com/codex/cli/slash-commands — todos
+    // los /comandos son built-in). En Cursor el equivalente es Skills.
+    return null;
+  }
+
+  /**
+   * Sub-fase 10 v1.5.0: transforma hooks SWL a formato Codex hooks.json.
+   *
+   * Schema Codex (developers.openai.com/codex/hooks):
+   *   {
+   *     "hooks": {
+   *       "PreToolUse": [{ "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "...", "timeout": 30 }] }]
+   *     }
+   *   }
+   *
+   * Eventos válidos (case-sensitive): SessionStart, PreToolUse, PermissionRequest,
+   * PostToolUse, UserPromptSubmit, Stop. `Notification` de Claude se descarta.
+   *
+   * @param {object} hooksConfig - Mapa { hookFile: { events: [...], matcher?, timeout? } }
+   * @param {object} [opciones] - { hookFiles?: string[] filtro, rutaHooksDir?: string base }
+   * @returns {object|null} { formato, destino, config, descartados }
+   */
+  transformarHooks(hooksConfig, opciones) {
+    if (!hooksConfig || typeof hooksConfig !== 'object') return null;
+    const opts = opciones || {};
+    const hookFilesFiltro = Array.isArray(opts.hookFiles) ? new Set(opts.hookFiles) : null;
+    const rutaHooksDir = opts.rutaHooksDir || 'hooks';
+
+    const EVENTOS_VALIDOS = new Set([
+      'SessionStart', 'PreToolUse', 'PermissionRequest',
+      'PostToolUse', 'UserPromptSubmit', 'Stop',
+    ]);
+
+    const grupos = {};
+    const descartados = [];
+
+    for (const [hookFile, def] of Object.entries(hooksConfig)) {
+      if (hookFilesFiltro && !hookFilesFiltro.has(hookFile)) continue;
+      if (!def || !Array.isArray(def.events)) continue;
+
+      for (const event of def.events) {
+        if (!EVENTOS_VALIDOS.has(event)) {
+          descartados.push({ hookFile, event, motivo: 'evento no soportado por Codex' });
+          continue;
+        }
+        if (!grupos[event]) grupos[event] = [];
+        const entry = {
+          hooks: [{
+            type: 'command',
+            command: `node ${rutaHooksDir}/${hookFile}`,
+            ...(def.timeout ? { timeout: def.timeout } : {}),
+          }],
+        };
+        if (def.matcher) entry.matcher = def.matcher;
+        grupos[event].push(entry);
+      }
+    }
+
+    return {
+      formato: 'codex-hooks-json',
+      destino: 'hooks.json',
+      config: { hooks: grupos },
+      descartados,
+    };
+  }
+
+  /**
+   * Genera el bloque AGENTS.md.
+   *
+   * @param {object} contexto
+   * @param {string} contexto.version - Versión del paquete swl-ses
+   * @param {string} contexto.perfil - Perfil instalado (core, completo, etc.)
+   * @param {Array} contexto.agentes - Agentes a consolidar
+   * @param {Array} contexto.reglas - Reglas a consolidar
+   * @param {Array} contexto.skills - Skills (solo para tabla referencial)
+   * @param {boolean} [contexto.esGlobal] - Si true escribe en ~/.codex/, si no en cwd
+   * @param {string} [contexto.dirRuntimeGlobal] - Path absoluto de ~/.codex/ (de RUNTIMES.codex.global)
+   * @param {boolean} [contexto.withMcp] - Si true autoregistra swl-memory en config.toml
+   * @param {string} [contexto.swlBinPath] - Path absoluto al CLI swl-ses (para args del MCP)
+   * @returns {object} Objeto con contenido y metadata de escritura
+   */
+  generarArchivoInstrucciones(contexto) {
+    const lineas = [];
+    const fecha = new Date().toISOString().split('T')[0];
+
+    lineas.push('## Sistema SWL — uso obligatorio (gestionado por swl-ses)');
+    lineas.push('');
+    lineas.push(`> Generado por swl-ses v${contexto.version} — ${fecha}`);
+    lineas.push(`> Perfil: \`${contexto.perfil || 'default'}\`. Scope: \`${contexto.esGlobal ? 'global (~/.codex/)' : 'proyecto'}\`.`);
+    lineas.push('> NO editar el contenido entre los marcadores SWL-BEGIN/END — regenerar con:');
+    lineas.push(`> \`npx @saulwade/swl-ses@latest install --target codex${contexto.esGlobal ? ' --global' : ''} --force\``);
+    lineas.push('');
+
+    // Reglas de máxima prioridad
+    lineas.push('### Reglas de máxima prioridad');
+    lineas.push('');
+    lineas.push('1. **Idioma: español de México** — respuestas, comentarios, commits, docs.');
+    lineas.push('2. **Investigar antes de editar** — leer el archivo completo antes de modificar.');
+    lineas.push('3. **Sistema SWL transversal** — la memoria SWL (aprendizajes, instintos, sesiones) está accesible vía MCP server `swl-memory` si está configurado. Ver sección "Memoria SWL" abajo.');
+    lineas.push('');
+
+    // Tabla de agentes (referencial — Codex no los carga individualmente)
+    if (contexto.agentes && contexto.agentes.length > 0) {
+      lineas.push('### Agentes disponibles (referencia)');
+      lineas.push('');
+      lineas.push(`> Total: ${contexto.agentes.length} agentes. Codex no carga agentes individuales — esta tabla es referencia operativa de qué rol invocar conceptualmente.`);
+      lineas.push('');
+      lineas.push('| Agente | Descripción |');
+      lineas.push('|--------|-------------|');
+      for (const ag of contexto.agentes) {
+        const { frontmatter } = this.parsearFrontmatter(ag.contenido || '');
+        const nombre = frontmatter.name || ag.nombre || 'sin-nombre';
+        const desc = String(frontmatter.description || '').replace(/\|/g, '\\|');
+        const descCorta = desc.length > 100 ? desc.slice(0, 97) + '...' : desc;
+        lineas.push(`| \`${nombre}\` | ${descCorta} |`);
+      }
+      lineas.push('');
+    }
+
+    // Reglas concatenadas
+    if (contexto.reglas && contexto.reglas.length > 0) {
+      lineas.push('### Reglas concatenadas');
+      lineas.push('');
+      for (const regla of contexto.reglas) {
+        lineas.push(regla.contenido);
+        lineas.push('');
+        lineas.push('---');
+        lineas.push('');
+      }
+    }
+
+    // Skills (tabla referencial)
+    if (contexto.skills && contexto.skills.length > 0) {
+      lineas.push('### Skills disponibles (referencia)');
+      lineas.push('');
+      lineas.push(`> Total: ${contexto.skills.length} skills. Codex no carga skills nativamente. Para invocarlos vía MCP, ver sección "Memoria SWL".`);
+      lineas.push('');
+      lineas.push('| Skill | Descripción |');
+      lineas.push('|-------|-------------|');
+      for (const sk of contexto.skills) {
+        const desc = String(sk.descripcion || '').replace(/\|/g, '\\|');
+        const descCorta = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
+        lineas.push(`| \`${sk.nombre}\` | ${descCorta} |`);
+      }
+      lineas.push('');
+    }
+
+    // Memoria SWL — MCP
+    lineas.push('### Memoria SWL (acceso vía MCP)');
+    lineas.push('');
+    if (contexto.withMcp) {
+      lineas.push('El servidor `swl-memory` está autoregistrado en `~/.codex/config.toml`. Codex puede consultar:');
+      lineas.push('');
+      lineas.push('- `swl_memory_search` — búsqueda híbrida sobre aprendizajes + sesiones + instintos.');
+      lineas.push('- `swl_aprendizajes_recientes` — últimos N aprendizajes del proyecto.');
+      lineas.push('- `swl_instintos_activos` — patrones validados con confianza efectiva ≥ umbral.');
+      lineas.push('');
+      lineas.push('Para verificar: `codex mcp list` debe mostrar `swl-memory`.');
+    } else {
+      lineas.push('Para habilitar la memoria SWL accesible desde Codex, reinstalar con `--with-mcp`:');
+      lineas.push('');
+      lineas.push('```bash');
+      lineas.push(`npx @saulwade/swl-ses@latest install --target codex${contexto.esGlobal ? ' --global' : ''} --with-mcp --force`);
+      lineas.push('```');
+    }
+    lineas.push('');
+
+    // Convenciones de commits
+    lineas.push('### Convenciones de commits');
+    lineas.push('');
+    lineas.push('- SemVer estricto.');
+    lineas.push('- Mensajes en español: `<tipo>(<scope>): <descripción imperativa>`.');
+    lineas.push('- Sin `Co-Authored-By` ni referencias a IA (regla global del usuario).');
+    lineas.push('');
+
+    let cuerpo = lineas.join('\n');
+
+    // Limitar tamaño total a 50 KB para no saturar el contexto de Codex
+    const MAX_SIZE = 50 * 1024;
+    if (Buffer.byteLength(cuerpo, 'utf-8') > MAX_SIZE) {
+      const aviso = '\n\n> **Nota**: contenido truncado por límite de 50 KB. Instalar con perfil más específico (no `completo`) para reducir tamaño.\n';
+      cuerpo = cuerpo.slice(0, MAX_SIZE - 200) + aviso;
+    }
+
+    // Resolver dirBase según scope
+    const dirBase = contexto.esGlobal && contexto.dirRuntimeGlobal
+      ? contexto.dirRuntimeGlobal
+      : '.';
+
+    // Si el caller pidió MCP, registrar el server en config.toml ANTES de devolver
+    // la metadata de escritura del AGENTS.md. Side effect — pero idempotente y zero-impact
+    // si la escritura del AGENTS.md falla después.
+    if (contexto.withMcp) {
+      try {
+        const configToml = path.join(contexto.dirRuntimeGlobal, 'config.toml');
+        const swlBin = contexto.swlBinPath || 'swl-mcp-server';
+        upsertMcpServer(configToml, 'swl-memory', {
+          command: 'node',
+          args: [swlBin],
+          env: {
+            SWL_MCP_BASE_DIR: process.cwd(),
+          },
+        });
+      } catch (err) {
+        // No bloquear instalación si el registro del MCP falla — solo loggear
+        // El usuario verá el error y puede registrar manualmente con `codex mcp add`.
+        console.warn(`[codex] No se pudo registrar swl-memory en config.toml: ${err.message}`);
+      }
+    }
+
+    return {
+      contenido: cuerpo,
+      rutaRelativa: 'AGENTS.md',
+      dirBase,
+      // Usar merge con marcadores para preservar contenido del usuario en AGENTS.md
+      merge: {
+        tipo: 'marcadores',
+        beginTag: `<!-- SWL-BEGIN v${contexto.version} — bloque gestionado por swl-ses, no editar -->`,
+        endTag: '<!-- SWL-END -->',
+        beginPrefix: '<!-- SWL-BEGIN',
+      },
+    };
+  }
+
+  soportaTipo(tipo) {
+    // Sub-fase 8 (v1.5.0): Codex ahora soporta habilidades nativamente
+    // (~/.codex/skills/<name>/SKILL.md). Agentes y reglas siguen consolidados
+    // en AGENTS.md por limitación de Codex (no expone agents/ individual).
+    return ['agentes', 'habilidades', 'reglas'].includes(tipo);
+  }
+}
+
+module.exports = TransformadorCodex;