@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/lib/transformadores/codex.js

@@ -1,375 +1,375 @@
-'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;
+'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;