@saulwade/swl-ses 1.3.3 → 1.3.5

package/scripts/lib/transformadores/claude.js

@@ -1,200 +1,200 @@
-'use strict';
-
-const TransformadorBase = require('./base');
-const { detectarStackDetallado } = require('../detectar-stack-detallado');
-
-class TransformadorClaude extends TransformadorBase {
-  transformarAgente(contenidoMd, metadatos) {
-    // Pass-through: Claude soporta el formato SWL directamente
-    return {
-      contenido: contenidoMd,
-      rutaRelativa: `agents/${metadatos.nombreArchivo}`,
-    };
-  }
-
-  transformarSkill(dirSkill, metadatos) {
-    // Pass-through: copiar directorio completo
-    return {
-      tipo: 'directorio',
-      rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
-    };
-  }
-
-  transformarRegla(contenidoMd, metadatos) {
-    return {
-      contenido: contenidoMd,
-      rutaRelativa: `rules/${metadatos.nombreArchivo}`,
-    };
-  }
-
-  transformarComando(contenidoMd, metadatos) {
-    return {
-      contenido: contenidoMd,
-      rutaRelativa: `commands/swl/${metadatos.nombreArchivo}`,
-    };
-  }
-
-  /**
-   * Genera el bloque SWL para insertar en el CLAUDE.md del proyecto destino.
-   *
-   * A diferencia de los otros transformadores (codex/gemini/copilot/opencode)
-   * que generan el archivo completo de instrucciones desde cero, Claude usa
-   * un CLAUDE.md que el usuario mantiene y que puede tener contenido propio
-   * (reglas del proyecto, convenciones, notas). Por eso:
-   *
-   *   - El contenido devuelto es un BLOQUE (no archivo completo)
-   *   - Se devuelve `merge: { tipo: 'marcadores', ... }` para indicar al
-   *     caller que debe usar `append-con-marcadores` en lugar de writeFileSync
-   *   - Los marcadores `<!-- SWL-BEGIN vX.Y.Z -->` / `<!-- SWL-END -->`
-   *     permiten que la siguiente actualización reemplace solo este bloque
-   *     sin tocar el contenido del usuario
-   *
-   * Aplicación de ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
-   *   - Detecta stack del proyecto destino (lenguaje, framework, ORM,
-   *     package manager, comandos disponibles)
-   *   - Genera secciones canónicas: Stack / Comandos del proyecto / Sistema SWL
-   *   - Documenta jerarquía project / user-level (`~/.claude/CLAUDE.md`)
-   *   - Documenta patrón "ask Claude to save to memory" del video oficial
-   */
-  generarArchivoInstrucciones(contexto) {
-    const fecha = new Date().toISOString().split('T')[0];
-    const stack = contexto.dirProyecto
-      ? this._detectarStackSeguro(contexto.dirProyecto)
-      : null;
-
-    const lineas = [
-      `> Gestionado por swl-ses v${contexto.version} — no editar entre estos marcadores.`,
-      `> Regenerado en ${fecha} con perfil \`${contexto.perfil || 'default'}\`.`,
-      `> Para excluir este bloque en futuras actualizaciones: \`npx swl-ses@latest install --no-claudemd\`.`,
-      '',
-    ];
-
-    // ─── Stack del proyecto detectado (best practice Anthropic #2) ─────────
-    if (stack && stack.detectado) {
-      lineas.push('## Stack del proyecto');
-      lineas.push('');
-      const partes = [];
-      if (stack.lenguajePrincipal) {
-        partes.push(`**Lenguaje**: ${stack.lenguajePrincipal.lenguaje}` +
-          (stack.lenguajePrincipal.runtime ? ` (${stack.lenguajePrincipal.runtime})` : ''));
-      }
-      if (stack.framework) partes.push(`**Framework**: ${stack.framework}`);
-      if (stack.orm) partes.push(`**ORM/BD**: ${stack.orm}`);
-      if (stack.packageManager) partes.push(`**Package manager**: ${stack.packageManager}`);
-      lineas.push('- ' + partes.join('\n- '));
-      lineas.push('');
-    }
-
-    // ─── Comandos del proyecto (best practice Anthropic #3) ────────────────
-    if (stack && stack.comandos && stack.comandos.length > 0) {
-      lineas.push('## Comandos del proyecto');
-      lineas.push('');
-      lineas.push('| Comando | Propósito |');
-      lineas.push('|---------|-----------|');
-      for (const c of stack.comandos) {
-        lineas.push(`| \`${c.comando}\` | ${c.proposito} |`);
-      }
-      lineas.push('');
-    }
-
-    // ─── Sistema SWL (siempre presente) ────────────────────────────────────
-    lineas.push('## Sistema SWL — uso obligatorio');
-    lineas.push('');
-    lineas.push(`Este proyecto usa swl-ses v${contexto.version} (sistema de ingeniería de software auto-evolutivo multi-runtime).`);
-    lineas.push(`Componentes instalados: ${contexto.conteos?.agentes || 0} agentes, ${contexto.conteos?.skills || 0} skills, ${contexto.conteos?.comandos || 0} comandos, ${contexto.conteos?.reglas || 0} reglas.`);
-    lineas.push('');
-
-    lineas.push('### Reglas de máxima prioridad');
-    lineas.push('');
-    lineas.push('1. **Idioma: español de México** — respuestas, código comentado, commits, PRs y docs. Evitar anglicismos innecesarios.');
-    lineas.push('2. **Usar el sistema SWL** — invocar agentes especializados (`orquestador-swl`, `implementador-swl`, `depurador-swl`, etc.) en lugar de hacer trabajo directo. Cargar skills con `Skill("nombre")` antes de implementar. Usar comandos `/swl:*` cuando apliquen.');
-    lineas.push('3. **Investigar antes de editar** — leer el archivo completo y entender el contexto antes de modificar código.');
-    lineas.push('4. **Lectura de documentos Office/Jupyter** — usar `python scripts/vendor/markitdown/cli.py <archivo>` para `.docx`, `.xlsx`, `.pptx`, `.ipynb`. El Read tool no soporta esos formatos.');
-    lineas.push('');
-
-    lineas.push('### Dónde están los componentes');
-    lineas.push('');
-    lineas.push('- Agentes: `.claude/agents/*.md`');
-    lineas.push('- Skills: `.claude/skills/*/SKILL.md` (invocar con `Skill("nombre")`)');
-    lineas.push('- Comandos: `.claude/commands/swl/*.md` (invocar con `/swl:nombre`)');
-    lineas.push('- Reglas: `.claude/rules/*.md` (se cargan automáticamente)');
-    lineas.push('- Hooks: registrados en `.claude/settings.json`');
-    lineas.push('');
-
-    lineas.push('### Flujos recomendados');
-    lineas.push('');
-    lineas.push('- **Feature completa**: `/swl:discutir-fase N` → `/swl:planear-fase N` → `/swl:ejecutar-fase N` → `/swl:verificar`');
-    lineas.push('- **Debugging**: delegar a `depurador-swl` con método científico (reproducir → aislar → hipótesis → fix → verificar)');
-    lineas.push('- **Calidad**: `/swl:revisar` (código) + `revisor-seguridad-swl` antes de merge a main');
-    lineas.push('- **Aprendizaje continuo**: `/swl:aprender` al final de fase, `/swl:evolucionar` ante fallos recurrentes de agentes');
-    lineas.push('');
-
-    lineas.push('### Consulta del sistema');
-    lineas.push('');
-    lineas.push('- `/swl:ayuda` — catálogo completo de comandos');
-    lineas.push('- `/swl:salud` — diagnóstico de integridad (incluye calidad de CLAUDE.md)');
-    lineas.push('- `/swl:metricas` — tokens, costo y modelos usados en la sesión');
-    lineas.push('- `/swl:skill-search <keyword>` — buscar skills relevantes');
-    lineas.push('- `/swl:claudemd audit` — auditar este CLAUDE.md (líneas, bullets gigantes, secciones canónicas)');
-    lineas.push('');
-
-    lineas.push('### Convenciones de versionado y commits');
-    lineas.push('');
-    lineas.push('- Versionado semántico estricto (SemVer)');
-    lineas.push('- Mensajes de commit en español, formato `<tipo>(<scope>): <descripción en imperativo>`');
-    lineas.push('- Commits atómicos (un cambio lógico = un commit)');
-    lineas.push('- Antes de release: `/swl:release` y gate `node scripts/verificar-release.js`');
-    lineas.push('');
-
-    // ─── Jerarquía project / user-level (best practice Anthropic) ─────────
-    lineas.push('### Jerarquía de CLAUDE.md (recomendada)');
-    lineas.push('');
-    lineas.push('- **Project-level** (este archivo, `./CLAUDE.md`) — convenciones del proyecto, compartido vía VCS con el equipo.');
-    lineas.push('- **User-level** (`~/.claude/CLAUDE.md`) — preferencias personales transversales (estilo de comentarios, lenguaje preferido, atajos personales). NO se commitea.');
-    lineas.push('- Las **reglas globales** del usuario en `~/.claude/rules/*.md` se cargan automáticamente para todos los proyectos.');
-    lineas.push('- Si no tienes user-level, créalo con `/swl:claudemd init-user`.');
-    lineas.push('');
-
-    // ─── Patrón "ask Claude to save to memory" del video oficial ──────────
-    lineas.push('### Cómo evolucionar este archivo');
-    lineas.push('');
-    lineas.push('1. **Empieza mínimo**. No adelantes reglas. Agrega solo lo que tengas que corregir más de una vez.');
-    lineas.push('2. **Cuando corrijas a Claude**, pide explícitamente: *"guarda esto en memoria"* o *"agrega esto a CLAUDE.md"*. Esa es la forma natural de que el archivo crezca con valor.');
-    lineas.push('3. **Usa `@filepath`** para referenciar docs sin duplicar contenido (ej. `@docs/api.md`, `@.planning/PROYECTO.md`).');
-    lineas.push('4. **Si crece mucho**, ejecuta `/swl:claudemd refactor` para extraer secciones a archivos `@`-referenciados.');
-    lineas.push('');
-
-    return {
-      contenido: lineas.join('\n'),
-      rutaRelativa: 'CLAUDE.md',
-      dirBase: '.',
-      merge: {
-        tipo: 'marcadores',
-        beginTag: `<!-- SWL-BEGIN v${contexto.version} — bloque gestionado por swl-ses -->`,
-        endTag: '<!-- SWL-END -->',
-        beginPrefix: '<!-- SWL-BEGIN',
-      },
-    };
-  }
-
-  transformarHooks(hooksConfig, opciones) {
-    // Los hooks de Claude se manejan via hooks-settings.js existente
-    return { formato: 'claude-settings', config: hooksConfig };
-  }
-
-  /**
-   * Wrapper defensivo: si la detección de stack falla por cualquier razón
-   * (permisos, archivo corrupto, etc.), se ignora y se genera el bloque
-   * sin secciones de stack. NUNCA romper el installer.
-   */
-  _detectarStackSeguro(dirProyecto) {
-    try {
-      return detectarStackDetallado(dirProyecto);
-    } catch (e) {
-      // Silencioso: stack no detectado, bloque base se genera igualmente
-      return null;
-    }
-  }
-}
-
-module.exports = TransformadorClaude;
+'use strict';
+
+const TransformadorBase = require('./base');
+const { detectarStackDetallado } = require('../detectar-stack-detallado');
+
+class TransformadorClaude extends TransformadorBase {
+  transformarAgente(contenidoMd, metadatos) {
+    // Pass-through: Claude soporta el formato SWL directamente
+    return {
+      contenido: contenidoMd,
+      rutaRelativa: `agents/${metadatos.nombreArchivo}`,
+    };
+  }
+
+  transformarSkill(dirSkill, metadatos) {
+    // Pass-through: copiar directorio completo
+    return {
+      tipo: 'directorio',
+      rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
+    };
+  }
+
+  transformarRegla(contenidoMd, metadatos) {
+    return {
+      contenido: contenidoMd,
+      rutaRelativa: `rules/${metadatos.nombreArchivo}`,
+    };
+  }
+
+  transformarComando(contenidoMd, metadatos) {
+    return {
+      contenido: contenidoMd,
+      rutaRelativa: `commands/swl/${metadatos.nombreArchivo}`,
+    };
+  }
+
+  /**
+   * Genera el bloque SWL para insertar en el CLAUDE.md del proyecto destino.
+   *
+   * A diferencia de los otros transformadores (codex/gemini/copilot/opencode)
+   * que generan el archivo completo de instrucciones desde cero, Claude usa
+   * un CLAUDE.md que el usuario mantiene y que puede tener contenido propio
+   * (reglas del proyecto, convenciones, notas). Por eso:
+   *
+   *   - El contenido devuelto es un BLOQUE (no archivo completo)
+   *   - Se devuelve `merge: { tipo: 'marcadores', ... }` para indicar al
+   *     caller que debe usar `append-con-marcadores` en lugar de writeFileSync
+   *   - Los marcadores `<!-- SWL-BEGIN vX.Y.Z -->` / `<!-- SWL-END -->`
+   *     permiten que la siguiente actualización reemplace solo este bloque
+   *     sin tocar el contenido del usuario
+   *
+   * Aplicación de ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
+   *   - Detecta stack del proyecto destino (lenguaje, framework, ORM,
+   *     package manager, comandos disponibles)
+   *   - Genera secciones canónicas: Stack / Comandos del proyecto / Sistema SWL
+   *   - Documenta jerarquía project / user-level (`~/.claude/CLAUDE.md`)
+   *   - Documenta patrón "ask Claude to save to memory" del video oficial
+   */
+  generarArchivoInstrucciones(contexto) {
+    const fecha = new Date().toISOString().split('T')[0];
+    const stack = contexto.dirProyecto
+      ? this._detectarStackSeguro(contexto.dirProyecto)
+      : null;
+
+    const lineas = [
+      `> Gestionado por swl-ses v${contexto.version} — no editar entre estos marcadores.`,
+      `> Regenerado en ${fecha} con perfil \`${contexto.perfil || 'default'}\`.`,
+      `> Para excluir este bloque en futuras actualizaciones: \`npx swl-ses@latest install --no-claudemd\`.`,
+      '',
+    ];
+
+    // ─── Stack del proyecto detectado (best practice Anthropic #2) ─────────
+    if (stack && stack.detectado) {
+      lineas.push('## Stack del proyecto');
+      lineas.push('');
+      const partes = [];
+      if (stack.lenguajePrincipal) {
+        partes.push(`**Lenguaje**: ${stack.lenguajePrincipal.lenguaje}` +
+          (stack.lenguajePrincipal.runtime ? ` (${stack.lenguajePrincipal.runtime})` : ''));
+      }
+      if (stack.framework) partes.push(`**Framework**: ${stack.framework}`);
+      if (stack.orm) partes.push(`**ORM/BD**: ${stack.orm}`);
+      if (stack.packageManager) partes.push(`**Package manager**: ${stack.packageManager}`);
+      lineas.push('- ' + partes.join('\n- '));
+      lineas.push('');
+    }
+
+    // ─── Comandos del proyecto (best practice Anthropic #3) ────────────────
+    if (stack && stack.comandos && stack.comandos.length > 0) {
+      lineas.push('## Comandos del proyecto');
+      lineas.push('');
+      lineas.push('| Comando | Propósito |');
+      lineas.push('|---------|-----------|');
+      for (const c of stack.comandos) {
+        lineas.push(`| \`${c.comando}\` | ${c.proposito} |`);
+      }
+      lineas.push('');
+    }
+
+    // ─── Sistema SWL (siempre presente) ────────────────────────────────────
+    lineas.push('## Sistema SWL — uso obligatorio');
+    lineas.push('');
+    lineas.push(`Este proyecto usa swl-ses v${contexto.version} (sistema de ingeniería de software auto-evolutivo multi-runtime).`);
+    lineas.push(`Componentes instalados: ${contexto.conteos?.agentes || 0} agentes, ${contexto.conteos?.skills || 0} skills, ${contexto.conteos?.comandos || 0} comandos, ${contexto.conteos?.reglas || 0} reglas.`);
+    lineas.push('');
+
+    lineas.push('### Reglas de máxima prioridad');
+    lineas.push('');
+    lineas.push('1. **Idioma: español de México** — respuestas, código comentado, commits, PRs y docs. Evitar anglicismos innecesarios.');
+    lineas.push('2. **Usar el sistema SWL** — invocar agentes especializados (`orquestador-swl`, `implementador-swl`, `depurador-swl`, etc.) en lugar de hacer trabajo directo. Cargar skills con `Skill("nombre")` antes de implementar. Usar comandos `/swl:*` cuando apliquen.');
+    lineas.push('3. **Investigar antes de editar** — leer el archivo completo y entender el contexto antes de modificar código.');
+    lineas.push('4. **Lectura de documentos Office/Jupyter** — usar `python scripts/vendor/markitdown/cli.py <archivo>` para `.docx`, `.xlsx`, `.pptx`, `.ipynb`. El Read tool no soporta esos formatos.');
+    lineas.push('');
+
+    lineas.push('### Dónde están los componentes');
+    lineas.push('');
+    lineas.push('- Agentes: `.claude/agents/*.md`');
+    lineas.push('- Skills: `.claude/skills/*/SKILL.md` (invocar con `Skill("nombre")`)');
+    lineas.push('- Comandos: `.claude/commands/swl/*.md` (invocar con `/swl:nombre`)');
+    lineas.push('- Reglas: `.claude/rules/*.md` (se cargan automáticamente)');
+    lineas.push('- Hooks: registrados en `.claude/settings.json`');
+    lineas.push('');
+
+    lineas.push('### Flujos recomendados');
+    lineas.push('');
+    lineas.push('- **Feature completa**: `/swl:discutir-fase N` → `/swl:planear-fase N` → `/swl:ejecutar-fase N` → `/swl:verificar`');
+    lineas.push('- **Debugging**: delegar a `depurador-swl` con método científico (reproducir → aislar → hipótesis → fix → verificar)');
+    lineas.push('- **Calidad**: `/swl:revisar` (código) + `revisor-seguridad-swl` antes de merge a main');
+    lineas.push('- **Aprendizaje continuo**: `/swl:aprender` al final de fase, `/swl:evolucionar` ante fallos recurrentes de agentes');
+    lineas.push('');
+
+    lineas.push('### Consulta del sistema');
+    lineas.push('');
+    lineas.push('- `/swl:ayuda` — catálogo completo de comandos');
+    lineas.push('- `/swl:salud` — diagnóstico de integridad (incluye calidad de CLAUDE.md)');
+    lineas.push('- `/swl:metricas` — tokens, costo y modelos usados en la sesión');
+    lineas.push('- `/swl:skill-search <keyword>` — buscar skills relevantes');
+    lineas.push('- `/swl:claudemd audit` — auditar este CLAUDE.md (líneas, bullets gigantes, secciones canónicas)');
+    lineas.push('');
+
+    lineas.push('### Convenciones de versionado y commits');
+    lineas.push('');
+    lineas.push('- Versionado semántico estricto (SemVer)');
+    lineas.push('- Mensajes de commit en español, formato `<tipo>(<scope>): <descripción en imperativo>`');
+    lineas.push('- Commits atómicos (un cambio lógico = un commit)');
+    lineas.push('- Antes de release: `/swl:release` y gate `node scripts/verificar-release.js`');
+    lineas.push('');
+
+    // ─── Jerarquía project / user-level (best practice Anthropic) ─────────
+    lineas.push('### Jerarquía de CLAUDE.md (recomendada)');
+    lineas.push('');
+    lineas.push('- **Project-level** (este archivo, `./CLAUDE.md`) — convenciones del proyecto, compartido vía VCS con el equipo.');
+    lineas.push('- **User-level** (`~/.claude/CLAUDE.md`) — preferencias personales transversales (estilo de comentarios, lenguaje preferido, atajos personales). NO se commitea.');
+    lineas.push('- Las **reglas globales** del usuario en `~/.claude/rules/*.md` se cargan automáticamente para todos los proyectos.');
+    lineas.push('- Si no tienes user-level, créalo con `/swl:claudemd init-user`.');
+    lineas.push('');
+
+    // ─── Patrón "ask Claude to save to memory" del video oficial ──────────
+    lineas.push('### Cómo evolucionar este archivo');
+    lineas.push('');
+    lineas.push('1. **Empieza mínimo**. No adelantes reglas. Agrega solo lo que tengas que corregir más de una vez.');
+    lineas.push('2. **Cuando corrijas a Claude**, pide explícitamente: *"guarda esto en memoria"* o *"agrega esto a CLAUDE.md"*. Esa es la forma natural de que el archivo crezca con valor.');
+    lineas.push('3. **Usa `@filepath`** para referenciar docs sin duplicar contenido (ej. `@docs/api.md`, `@.planning/PROYECTO.md`).');
+    lineas.push('4. **Si crece mucho**, ejecuta `/swl:claudemd refactor` para extraer secciones a archivos `@`-referenciados.');
+    lineas.push('');
+
+    return {
+      contenido: lineas.join('\n'),
+      rutaRelativa: 'CLAUDE.md',
+      dirBase: '.',
+      merge: {
+        tipo: 'marcadores',
+        beginTag: `<!-- SWL-BEGIN v${contexto.version} — bloque gestionado por swl-ses -->`,
+        endTag: '<!-- SWL-END -->',
+        beginPrefix: '<!-- SWL-BEGIN',
+      },
+    };
+  }
+
+  transformarHooks(hooksConfig, opciones) {
+    // Los hooks de Claude se manejan via hooks-settings.js existente
+    return { formato: 'claude-settings', config: hooksConfig };
+  }
+
+  /**
+   * Wrapper defensivo: si la detección de stack falla por cualquier razón
+   * (permisos, archivo corrupto, etc.), se ignora y se genera el bloque
+   * sin secciones de stack. NUNCA romper el installer.
+   */
+  _detectarStackSeguro(dirProyecto) {
+    try {
+      return detectarStackDetallado(dirProyecto);
+    } catch (e) {
+      // Silencioso: stack no detectado, bloque base se genera igualmente
+      return null;
+    }
+  }
+}
+
+module.exports = TransformadorClaude;