@saulwade/swl-ses 1.0.0

package/scripts/instalador.js

@@ -0,0 +1,1031 @@
+'use strict';
+
+/**
+ * swl-ses install
+ * Instala componentes SWL en el runtime destino.
+ *
+ * Flujo:
+ * 1. Detectar/validar runtime target
+ * 2. Resolver perfil → módulos → archivos
+ * 3. Detectar _userland/ y hacer merge
+ * 4. Mostrar plan de instalación
+ * 5. Aplicar (copiar archivos, adaptar formato si necesario)
+ * 6. Guardar estado de instalación
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { obtenerRuntime, calcularRutas, resumenDeteccion, detectarInstalacionesDuales } = require('./lib/detectar-runtime');
+const { preguntarSiNo, ES_TTY } = require('./lib/ui');
+const { resolverPerfil, generarPlan } = require('./lib/manifiestos');
+const { crearEstado, registrarArchivo, registrarComponente, guardarEstado, cargarEstado } = require('./lib/estado');
+const { validarRuta, esArchivoSensible, filtrarSecretos } = require('./lib/seguridad');
+const { registrarHooks, registrarOptimizaciones, rutaSettings, cargarHooksConfig } = require('./lib/hooks-settings');
+const { obtenerTransformador } = require('./lib/transformadores');
+const {
+  esProtegido,
+  crearBackup,
+  registrarBackup,
+  limpiarBackups,
+  mergeInstintos,
+  mergeSkills,
+} = require('./lib/preservar-usuario');
+const {
+  decideUpdateStrategy,
+  mergeEvolved,
+  scanEvolved,
+} = require('../hooks/lib/evolution-tracker');
+const { detectarStack, filtrarReglasPorStack } = require('./lib/detectar-stack');
+const { actualizarGitignore, entradasParaRuntime, limpiarTracked, leerManifest, escribirManifest } = require('./lib/gitignore-manifest');
+
+const RAIZ_PKG = path.resolve(__dirname, '..');
+const VERSION = require('../package.json').version;
+
+async function install(opciones) {
+  // Leer manifest .swl-ses si existe — sus valores son defaults que el CLI puede sobreescribir
+  const manifest = leerManifest(process.cwd());
+  if (manifest && !opciones.target && !opciones.profile) {
+    console.log(`[manifest] Usando configuración de .swl-ses: target=${manifest.target}, profile=${manifest.profile}`);
+  }
+
+  const target  = opciones.target  || (manifest && manifest.target)  || 'claude';
+  const perfil  = opciones.profile || (manifest && manifest.profile) || 'core';
+  const esGlobal = opciones.global || false;
+  const dryRun = opciones.dry_run || false;
+  const force = opciones.force || false;
+  const allLangs = opciones.all_langs || false;
+  const syncMode = opciones.sync_mode || (manifest && manifest.syncMode) || 'copy'; // copy | symlink | flat
+  const flatNaming = opciones.flat_naming || syncMode === 'flat'; // Convierte path/to/skill → path__to__skill
+
+  console.log(`swl-ses install v${VERSION}`);
+  console.log(`${'='.repeat(40)}`);
+
+  // 1. Validar runtime
+  let runtime;
+  try {
+    runtime = obtenerRuntime(target);
+  } catch (err) {
+    console.error(err.message);
+    console.log('\n' + resumenDeteccion());
+    process.exit(1);
+  }
+
+  if (runtime.soporte === 'parcial') {
+    console.log(`Nota: Runtime "${target}" (${runtime.nombre}) tiene soporte parcial — solo agentes y reglas.\n`);
+  }
+
+  // 1b. Detectar conflicto dual-scope: instalar en un scope cuando el opuesto
+  // ya tiene SWL instalado causa duplicación visible de comandos en la UI.
+  // Con --force se omite el prompt (asume que el caller sabe lo que hace).
+  // En modo no-TTY solo se muestra advertencia informativa y se continúa.
+  if (!force && !dryRun) {
+    const dual = detectarInstalacionesDuales(target);
+    const tieneOpuesto = esGlobal ? dual.local : dual.global;
+
+    if (tieneOpuesto) {
+      const scopeActual = esGlobal ? 'global' : 'proyecto';
+      const scopeOpuesto = esGlobal ? 'proyecto' : 'global';
+      const dirOpuesto = esGlobal ? dual.localDir : dual.globalDir;
+
+      console.log('');
+      console.log(`  Ya existe una instalación SWL de ${runtime.nombre} en scope ${scopeOpuesto}:`);
+      console.log(`    ${dirOpuesto}`);
+      console.log('');
+      console.log(`  Instalar también en scope ${scopeActual} duplicará comandos/agentes en la UI`);
+      console.log(`  porque ${runtime.nombre} lee componentes de ambos scopes y los muestra como`);
+      console.log(`  entradas separadas.`);
+      console.log('');
+      console.log(`  Recomendación: usa un solo scope.`);
+      console.log('');
+
+      if (ES_TTY) {
+        const proceder = await preguntarSiNo(
+          `¿Continuar e instalar en ambos scopes de todos modos?`,
+          false
+        );
+        console.log('');
+        if (!proceder) {
+          console.log('  Instalación cancelada.');
+          console.log(`  Si solo quieres usar el scope ${scopeOpuesto}, ya está instalado.`);
+          console.log(`  Si quieres cambiar de scope: ejecuta 'swl-ses uninstall${esGlobal ? '' : ' --global'}' primero.`);
+          return;
+        }
+      } else {
+        // No-TTY (CI, pipes): no podemos preguntar, pero avisamos.
+        console.log('  [no-TTY] Procediendo con la instalación — usa --force para suprimir este aviso.');
+        console.log('');
+      }
+    }
+  }
+
+  // 2. Resolver perfil
+  let resolucion;
+  try {
+    resolucion = resolverPerfil(perfil, {
+      target,
+      with: opciones.with,
+      without: opciones.without,
+    });
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  // 2b. Filtrar reglas de lenguaje por stack detectado
+  // El stack se detecta siempre que: hay reglas de lenguaje en el perfil, O
+  // se ejecuta con --force (actualización) para poder limpiar las ya instaladas.
+  const tieneReglasLenguaje = resolucion.archivos.some(
+    a => a.rutaRelativa && a.rutaRelativa.startsWith('reglas/lenguajes/')
+  );
+  const necesitaStack = (tieneReglasLenguaje || force) && !allLangs;
+
+  let stackDetectado = null;
+
+  if (necesitaStack) {
+    stackDetectado = detectarStack(process.cwd());
+  }
+
+  if (tieneReglasLenguaje) {
+    if (allLangs) {
+      console.log('\n[stack] --all-langs activado: se instalan reglas de todos los lenguajes.');
+    } else {
+      if (stackDetectado.size > 0) {
+        console.log(`\n[stack] Lenguajes detectados en el proyecto: ${[...stackDetectado].join(', ')}`);
+      } else {
+        console.log('\n[stack] No se detectaron lenguajes específicos en el proyecto.');
+      }
+
+      const resultado = filtrarReglasPorStack(resolucion.archivos, stackDetectado);
+      if (resultado.excluidos > 0) {
+        resolucion.archivos = resultado.archivos;
+        console.log(
+          `[stack] ${resultado.excluidos} reglas excluidas (lenguajes no presentes: ${resultado.lenguajesExcluidos.join(', ')})`
+        );
+        console.log('[stack] Usa --all-langs para forzar instalación de todos los lenguajes.');
+      } else {
+        console.log('[stack] Todas las reglas de lenguaje coinciden con el proyecto detectado.');
+      }
+    }
+  }
+
+  // 3. Calcular rutas destino
+  const rutas = calcularRutas(target, { global: esGlobal });
+
+  // 3b. En actualización (--force) limpiar reglas de lenguajes que ya no son del stack.
+  // Corre incluso si el perfil actual no incluye reglas-lenguajes, para eliminar
+  // subdirectorios de instalaciones anteriores con perfiles más amplios (e.g. completo).
+  if (force && stackDetectado !== null && rutas.reglas) {
+    const limpiadosStack = limpiarReglasSinStack(rutas.reglas, stackDetectado);
+    if (limpiadosStack.eliminados > 0) {
+      console.log(`\n[stack] Limpieza: ${limpiadosStack.eliminados} regla(s) de lenguaje eliminadas (${limpiadosStack.lenguajes.join(', ')})`);
+    }
+  }
+
+  // 4. Detectar _userland/
+  const userlandAgentes = path.join(process.cwd(), '_userland', 'agentes');
+  const userlandHabilidades = path.join(process.cwd(), '_userland', 'habilidades');
+  let archivosUserland = [];
+
+  if (fs.existsSync(userlandAgentes)) {
+    const agentesUser = fs.readdirSync(userlandAgentes)
+      .filter(f => f.endsWith('.md') && f !== '.gitkeep');
+    for (const a of agentesUser) {
+      archivosUserland.push({
+        origen: path.join(userlandAgentes, a),
+        rutaRelativa: `_userland/agentes/${a}`,
+        tipo: 'agentes',
+        modulo: 'userland',
+        esUserland: true,
+      });
+    }
+  }
+
+  if (fs.existsSync(userlandHabilidades)) {
+    const habsUser = fs.readdirSync(userlandHabilidades)
+      .filter(f => !f.startsWith('.'));
+    for (const h of habsUser) {
+      const skillPath = path.join(userlandHabilidades, h, 'SKILL.md');
+      if (fs.existsSync(skillPath)) {
+        archivosUserland.push({
+          origen: path.join(userlandHabilidades, h),
+          rutaRelativa: `_userland/habilidades/${h}`,
+          tipo: 'habilidades',
+          modulo: 'userland',
+          esUserland: true,
+        });
+      }
+    }
+  }
+
+  // 5. Mostrar plan
+  console.log(generarPlan(resolucion, rutas));
+
+  if (archivosUserland.length > 0) {
+    console.log(`\n[userland] (${archivosUserland.length} componentes del usuario)`);
+    for (const u of archivosUserland) {
+      console.log(`  + ${u.rutaRelativa} (prioridad: usuario > core)`);
+    }
+  }
+
+  if (dryRun) {
+    console.log('\n(modo --dry-run: sin cambios aplicados)');
+    return;
+  }
+
+  // 6. Detectar versión anterior para backup (Nivel 2)
+  let versionAnterior = null;
+  const estadoAnterior = cargarEstado(rutas.base);
+  if (estadoAnterior) {
+    versionAnterior = estadoAnterior.versionSistema;
+    if (versionAnterior && versionAnterior !== VERSION) {
+      console.log(`\n[preservar] Actualizando v${versionAnterior} → v${VERSION}`);
+      console.log(`[preservar] Datos de usuario serán preservados automáticamente.`);
+    }
+  }
+
+  // 6b. Migración LEARNINGS.md → APRENDIZAJES.md (v5.1.3+)
+  const learningsPath     = path.join(process.cwd(), '.planning', 'LEARNINGS.md');
+  const aprendizajesPath  = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');
+  if (fs.existsSync(learningsPath)) {
+    try {
+      const learningsContent = fs.readFileSync(learningsPath, 'utf8').trim();
+      if (learningsContent.length > 0) {
+        // Fusionar contenido en APRENDIZAJES.md
+        let aprendizajesContent = '';
+        if (fs.existsSync(aprendizajesPath)) {
+          aprendizajesContent = fs.readFileSync(aprendizajesPath, 'utf8');
+        }
+        // Solo fusionar si el contenido no está ya duplicado
+        if (!aprendizajesContent.includes(learningsContent.substring(0, 100))) {
+          const header = aprendizajesContent ? '' : '# Registro de aprendizajes\n\n---\n';
+          fs.writeFileSync(aprendizajesPath, aprendizajesContent + '\n\n' + header + learningsContent, 'utf8');
+          console.log('  ⊕ Migración: LEARNINGS.md fusionado en APRENDIZAJES.md');
+        }
+      }
+      // Eliminar el archivo obsoleto
+      fs.unlinkSync(learningsPath);
+      console.log('  ✓ Migración: LEARNINGS.md eliminado (unificado en APRENDIZAJES.md)');
+    } catch (err) {
+      console.log(`  ! Migración LEARNINGS.md: ${err.message}`);
+    }
+  }
+
+  // 6c. Migración de archivos .planning/ renombrados de inglés a español (v5.6.0+)
+  //     Los proyectos que actualizan desde versiones anteriores pueden tener
+  //     archivos con nombres en inglés que los hooks ya no encuentran.
+  const MIGRACIONES_PLANNING = [
+    { viejo: 'STATE.md',        nuevo: 'ESTADO.md' },
+    { viejo: 'COMPACT.md',      nuevo: 'COMPACTACION.md' },
+    { viejo: 'ROADMAP.md',      nuevo: 'HOJA-RUTA.md' },
+    { viejo: 'PROJECT.md',      nuevo: 'PROYECTO.md' },
+    { viejo: 'REQUIREMENTS.md', nuevo: 'REQUISITOS.md' },
+    { viejo: 'GRAPH_REPORT.md', nuevo: 'REPORTE-GRAFO.md' },
+    { viejo: 'METRICS.md',      nuevo: 'METRICAS.md' },
+  ];
+
+  let migracionesAplicadas = 0;
+  for (const m of MIGRACIONES_PLANNING) {
+    const rutaVieja = path.join(process.cwd(), '.planning', m.viejo);
+    const rutaNueva = path.join(process.cwd(), '.planning', m.nuevo);
+
+    if (!fs.existsSync(rutaVieja)) continue;
+
+    try {
+      const contenidoViejo = fs.readFileSync(rutaVieja, 'utf8').trim();
+      if (contenidoViejo.length === 0) {
+        // Archivo vacío: solo eliminar
+        fs.unlinkSync(rutaVieja);
+        console.log(`  ✓ Migración: ${m.viejo} eliminado (vacío)`);
+        migracionesAplicadas++;
+        continue;
+      }
+
+      if (!fs.existsSync(rutaNueva)) {
+        // Caso 1: solo existe el viejo → renombrar
+        fs.renameSync(rutaVieja, rutaNueva);
+        console.log(`  ✓ Migración: ${m.viejo} → ${m.nuevo} (renombrado)`);
+      } else {
+        // Caso 2: ambos existen → fusionar contenido del viejo en el nuevo
+        const contenidoNuevo = fs.readFileSync(rutaNueva, 'utf8');
+        // Solo fusionar si el contenido no está ya duplicado
+        const muestra = contenidoViejo.substring(0, 100);
+        if (!contenidoNuevo.includes(muestra)) {
+          const separador = '\n\n---\n\n<!-- Contenido migrado desde ' + m.viejo + ' -->\n\n';
+          fs.writeFileSync(rutaNueva, contenidoNuevo + separador + contenidoViejo, 'utf8');
+          console.log(`  ⊕ Migración: ${m.viejo} fusionado en ${m.nuevo}`);
+        }
+        // Eliminar el archivo obsoleto
+        fs.unlinkSync(rutaVieja);
+        console.log(`  ✓ Migración: ${m.viejo} eliminado (unificado en ${m.nuevo})`);
+      }
+      migracionesAplicadas++;
+    } catch (err) {
+      console.log(`  ! Migración ${m.viejo}: ${err.message}`);
+    }
+  }
+
+  if (migracionesAplicadas > 0) {
+    console.log(`  [migración] ${migracionesAplicadas} archivo(s) de .planning/ migrado(s) de inglés a español`);
+  }
+
+  // 6d. Filtrar skills por targets declarados en SKILL.md frontmatter (patrón skillshare)
+  //     Si un skill declara targets: [claude, copilot], solo se instala en esos runtimes.
+  //     Si no declara targets, se instala en todos (comportamiento por defecto).
+  let skillsFiltradosPorTarget = 0;
+  resolucion.archivos = resolucion.archivos.filter(archivo => {
+    if (archivo.tipo !== 'habilidades') return true;
+
+    const skillMdPath = path.join(archivo.origen, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) return true;
+
+    try {
+      const contenido = fs.readFileSync(skillMdPath, 'utf8');
+      // Extraer frontmatter targets (formato: targets: [claude, copilot])
+      const targetsMatch = contenido.match(/^targets:\s*\[([^\]]+)\]/m);
+      if (!targetsMatch) return true; // Sin targets declarados → incluir en todos
+
+      const declaredTargets = targetsMatch[1].split(',').map(t => t.trim().replace(/['"]/g, ''));
+      if (declaredTargets.length === 0) return true;
+
+      // Normalizar target actual (claude-code → claude, etc.)
+      const targetNormalizado = target.replace(/-code$/, '');
+      if (declaredTargets.includes(targetNormalizado) || declaredTargets.includes(target)) {
+        return true;
+      }
+
+      skillsFiltradosPorTarget++;
+      return false;
+    } catch {
+      return true; // Error leyendo → incluir por defecto
+    }
+  });
+
+  if (skillsFiltradosPorTarget > 0) {
+    console.log(`\n[targets] ${skillsFiltradosPorTarget} skill(s) excluidos (no declaran target "${target}")`);
+  }
+
+  // 7. Aplicar instalación
+  console.log('\nAplicando instalación...\n');
+
+  const estado = crearEstado({
+    versionSistema: VERSION,
+    target,
+    perfil,
+    rutaBase: rutas.base,
+    global: esGlobal,
+  });
+
+  let instalados = 0;
+  let errores = 0;
+  let colisiones = 0;
+  let protegidos = 0;
+  let respaldados = 0;
+  let evolucionados = 0;
+
+  // Escanear componentes evolucionados antes de instalar
+  if (force && fs.existsSync(rutas.base)) {
+    const evolved = [
+      ...scanEvolved(rutas.agentes || ''),
+      ...scanEvolved(rutas.habilidades || ''),
+      ...scanEvolved(rutas.comandos || ''),
+      ...scanEvolved(rutas.reglas || ''),
+    ];
+    if (evolved.length > 0) {
+      console.log(`[evolución] ${evolved.length} componente(s) evolucionado(s) detectado(s):`);
+      for (const e of evolved) {
+        console.log(`  ★ ${path.basename(e.path)} (por ${e.evolvedBy || 'auto-evolución'}, desde v${e.evolvedFrom || '?'})`);
+      }
+      console.log('');
+    }
+  }
+
+  // Nivel 3: Merge de instintos antes de instalar (si existe proyecto.yaml en destino)
+  const instintosOrigen  = path.join(RAIZ_PKG, 'instintos', 'proyecto.yaml');
+  const instintosDestino = path.join(process.cwd(), 'instintos', 'proyecto.yaml');
+  if (fs.existsSync(instintosDestino) && fs.existsSync(instintosOrigen)) {
+    const mergeResult = mergeInstintos(instintosOrigen, instintosDestino);
+    if (mergeResult.merged) {
+      console.log(`  ⊕ Instintos: ${mergeResult.preservados} preservados, ${mergeResult.nuevos} nuevos agregados`);
+    }
+  }
+
+  // Instalar archivos core
+  for (const archivo of resolucion.archivos) {
+    try {
+      const resultado = instalarArchivo(archivo, rutas, runtime, {
+        force,
+        versionAnterior,
+        versionActual: VERSION,
+        estado,
+        syncMode,
+        flatNaming,
+      });
+      if (resultado.instalado) {
+        registrarArchivo(estado, {
+          origen: archivo.rutaRelativa,
+          destino: resultado.destino,
+          tipo: archivo.tipo,
+        });
+        instalados++;
+      } else if (resultado.colision) {
+        colisiones++;
+      } else if (resultado.protegido) {
+        protegidos++;
+      } else if (resultado.evolucionado) {
+        // Registrar en el estado aunque no se sobrescribió — el archivo
+        // existe en disco (versión evolucionada del usuario) y el doctor
+        // necesita contarlo para la verificación de conteo de componentes.
+        registrarArchivo(estado, {
+          origen: archivo.rutaRelativa,
+          destino: resultado.destino,
+          tipo: archivo.tipo,
+        });
+        evolucionados++;
+      }
+    } catch (err) {
+      console.error(`  ! Error: ${archivo.rutaRelativa}: ${err.message}`);
+      errores++;
+    }
+  }
+
+  // Instalar userland (prioridad sobre core)
+  for (const archivo of archivosUserland) {
+    try {
+      const resultado = instalarArchivo(archivo, rutas, runtime, { force: true });
+      if (resultado.instalado) {
+        registrarArchivo(estado, {
+          origen: archivo.rutaRelativa,
+          destino: resultado.destino,
+          tipo: archivo.tipo,
+        });
+        instalados++;
+        console.log(`  * Userland: ${path.basename(archivo.origen)} (prioridad usuario)`);
+      }
+    } catch (err) {
+      console.error(`  ! Error userland: ${archivo.rutaRelativa}: ${err.message}`);
+      errores++;
+    }
+  }
+
+  // Registrar componentes
+  for (const modulo of resolucion.modulos) {
+    registrarComponente(estado, modulo);
+  }
+
+  // 7. Registrar hooks en settings.json del runtime
+  // Los hooks solo se registran a nivel PROYECTO (no global) para evitar
+  // ejecucion duplicada cuando Claude Code combina hooks de ambos scopes.
+  let hooksRegistrados = 0;
+  let hooksPreservados = 0;
+
+  if (runtime.soportaHooks) {
+    // hooks-config.json es la fuente de verdad para hooks registrables.
+    // No filtrar por tipo de módulo porque hooks como grafo-contexto.js
+    // pueden pertenecer a módulos con tipo distinto a "hooks".
+    const hooksConfig = cargarHooksConfig();
+    const hookFilesInstalados = resolucion.archivos
+      .filter(a => (a.rutaRelativa || a.origen).endsWith('.js') && hooksConfig[path.basename(a.origen)])
+      .map(a => path.basename(a.origen));
+
+    if (hookFilesInstalados.length > 0) {
+      if (esGlobal) {
+        console.log('  ~ Hooks: omitiendo registro en settings global (solo se registran a nivel proyecto)');
+        console.log('    Los hooks se activan al instalar a nivel proyecto con: npx swl-ses@latest install --target claude');
+      } else {
+        const settingsPath = rutaSettings(runtime, rutas.base);
+        try {
+          const resultado = registrarHooks({
+            settingsPath,
+            hooksDir: rutas.hooks,
+            esGlobal: false,
+            hookFiles: hookFilesInstalados,
+          });
+          hooksRegistrados = resultado.registrados;
+          hooksPreservados = resultado.preservados;
+          console.log(`  + Hooks registrados en settings.json (proyecto): ${hooksRegistrados}`);
+          if (hooksPreservados > 0) {
+            console.log(`    (${hooksPreservados} hooks externos preservados)`);
+          }
+
+          // Registrar optimizaciones de rendimiento en settings.json
+          const optResult = registrarOptimizaciones(settingsPath);
+          if (optResult.aplicadas > 0) {
+            console.log(`  + Optimizaciones de rendimiento aplicadas: ${optResult.aplicadas}`);
+          }
+        } catch (err) {
+          console.error(`  ! Error registrando hooks en settings.json: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  // 8. Generar archivo de instrucciones principal (si el target lo requiere)
+  const transformador = obtenerTransformador(target, runtime);
+  if (runtime.archivoPrincipal) {
+    try {
+      // Recopilar contexto para el archivo de instrucciones
+      const agentesInstalados = resolucion.archivos
+        .filter(a => a.tipo === 'agentes')
+        .map(a => {
+          try {
+            return { nombre: path.basename(a.origen, '.md'), contenido: fs.readFileSync(a.origen, 'utf-8') };
+          } catch { return null; }
+        })
+        .filter(Boolean);
+
+      const reglasInstaladas = resolucion.archivos
+        .filter(a => a.tipo === 'reglas')
+        .map(a => {
+          try {
+            return { nombre: path.basename(a.origen, '.md'), contenido: fs.readFileSync(a.origen, 'utf-8') };
+          } catch { return null; }
+        })
+        .filter(Boolean);
+
+      const skillsInstalados = resolucion.archivos
+        .filter(a => a.tipo === 'habilidades')
+        .map(a => {
+          const nombre = path.basename(a.origen);
+          const skillMd = path.join(a.origen, 'SKILL.md');
+          let descripcion = '';
+          try {
+            const contenido = fs.readFileSync(skillMd, 'utf-8');
+            const match = contenido.match(/description:\s*>?\s*\n?\s*(.+)/);
+            if (match) descripcion = match[1].trim();
+          } catch { /* sin descripcion */ }
+          return { nombre, descripcion };
+        });
+
+      const conteos = {
+        agentes: agentesInstalados.length,
+        skills: skillsInstalados.length,
+        reglas: reglasInstaladas.length,
+        comandos: resolucion.archivos.filter(a => a.tipo === 'comandos').length,
+      };
+
+      const instrucciones = transformador.generarArchivoInstrucciones({
+        version: VERSION,
+        perfil,
+        agentes: agentesInstalados,
+        reglas: reglasInstaladas,
+        skills: skillsInstalados,
+        conteos,
+      });
+
+      if (instrucciones) {
+        const dirBase = instrucciones.dirBase
+          ? path.resolve(instrucciones.dirBase)
+          : rutas.base;
+        const rutaInstrucciones = path.join(dirBase, instrucciones.rutaRelativa);
+        const dirInstrucciones = path.dirname(rutaInstrucciones);
+
+        // Opt-out explícito: --no-claudemd para Claude Code
+        // Respeta al usuario que prefiere mantener su CLAUDE.md 100% manual.
+        const esClaudeMd = instrucciones.rutaRelativa === 'CLAUDE.md';
+        if (esClaudeMd && opciones.no_claudemd) {
+          console.log('  = CLAUDE.md no modificado (--no-claudemd)');
+        } else if (instrucciones.merge && instrucciones.merge.tipo === 'marcadores') {
+          // Merge idempotente con marcadores — preserva contenido del usuario.
+          if (!fs.existsSync(dirInstrucciones)) {
+            fs.mkdirSync(dirInstrucciones, { recursive: true });
+          }
+          const { mergeConMarcadores } = require('./lib/append-con-marcadores');
+          const resMerge = mergeConMarcadores(rutaInstrucciones, instrucciones.contenido, {
+            beginTag:    instrucciones.merge.beginTag,
+            endTag:      instrucciones.merge.endTag,
+            beginPrefix: instrucciones.merge.beginPrefix,
+          });
+          const etiqueta = {
+            'creado':       '+ CLAUDE.md creado con bloque SWL',
+            'append':       '+ Bloque SWL agregado al final de CLAUDE.md (contenido del usuario preservado)',
+            'reemplazado':  '* Bloque SWL actualizado en CLAUDE.md (contenido del usuario preservado)',
+            'sin-cambios':  '= CLAUDE.md ya tenía el bloque SWL actualizado',
+            'error':        '! Error al fusionar CLAUDE.md',
+          }[resMerge.accion] || `${resMerge.accion} ${resMerge.archivo}`;
+          console.log(`  ${etiqueta}${resMerge.detalle ? ': ' + resMerge.detalle : ''}`);
+          registrarArchivo(estado, {
+            origen: 'generado-merge',
+            destino: rutaInstrucciones,
+            tipo: 'instrucciones-merge',
+            accion: resMerge.accion,
+          });
+        } else {
+          // Comportamiento clásico: sobrescribir archivo completo (codex/gemini/copilot/opencode)
+          if (!fs.existsSync(dirInstrucciones)) {
+            fs.mkdirSync(dirInstrucciones, { recursive: true });
+          }
+          fs.writeFileSync(rutaInstrucciones, instrucciones.contenido, 'utf-8');
+          console.log(`  + Archivo principal generado: ${instrucciones.rutaRelativa}`);
+          registrarArchivo(estado, {
+            origen: 'generado',
+            destino: rutaInstrucciones,
+            tipo: 'instrucciones',
+          });
+        }
+      }
+    } catch (err) {
+      console.error(`  ! Error generando archivo de instrucciones: ${err.message}`);
+    }
+  }
+
+  // 9. Opt-in interactivo de notificaciones Telegram
+  // Nota: SWL solo registra hooks a nivel proyecto, excepto bajo opt-in explícito
+  // del usuario en este flujo. Ver ADR-0009 y scripts/lib/hooks-settings.js.
+  const noNotificaciones   = opciones.no_notificaciones   || false;
+  const withNotificaciones = opciones.with_notificaciones || null; // 'token,chatId'
+
+  if (!noNotificaciones) {
+    try {
+      const notif = require('./lib/notificaciones-telegram');
+
+      // Modo headless explícito: --with-notificaciones=token,chatId
+      if (withNotificaciones) {
+        const [tokenHl, chatIdHl] = withNotificaciones.split(',');
+        if (tokenHl && chatIdHl) {
+          const resHl = await notif.init({
+            token:    tokenHl.trim(),
+            chatId:   chatIdHl.trim(),
+            esTty:    false,
+            hooksDir: rutas.hooks || null,
+          });
+          if (resHl.resultado === 'completado') {
+            console.log('  + Notificaciones Telegram configuradas (modo headless).');
+          } else {
+            console.log(`  ~ Notificaciones Telegram: ${resHl.resultado} — ${resHl.detalle || ''}`);
+          }
+        } else {
+          console.log('  ! --with-notificaciones: formato esperado token,chatId — omitiendo notificaciones.');
+        }
+      } else if (!ES_TTY) {
+        // No-TTY y sin flags headless → saltar automáticamente
+        console.log('  ~ Notificaciones Telegram: omitido en modo no-interactivo (usar /swl:notificaciones init para activarlo después).');
+      } else {
+        // TTY → flujo interactivo
+        const resInteractivo = await notif.init({
+          esTty:    true,
+          hooksDir: rutas.hooks || null,
+          dryRun:   dryRun,
+        });
+        if (resInteractivo.resultado === 'completado') {
+          console.log('  + Notificaciones Telegram configuradas.');
+        } else if (resInteractivo.resultado === 'omitido') {
+          // Silencioso — ya se imprimió mensaje en init()
+        }
+      }
+    } catch (err) {
+      // No romper la instalación entera por un fallo de notificaciones
+      console.error(`  ! Notificaciones Telegram: error no esperado (instalación continúa): ${err.message}`);
+    }
+  }
+
+  // 10. Guardar estado
+  estado.hooksRegistrados = hooksRegistrados;
+  const rutaEstado = guardarEstado(estado, rutas.base);
+
+  // 9.5. En instalación global: copiar vendors a ~/.claude/scripts/vendor/
+  //      Permite que los scripts funcionen en proyectos que no tienen la copia local
+  if (esGlobal) {
+    const vendorsGlobal = ['claude-usage', 'markitdown'];
+    for (const vendorNombre of vendorsGlobal) {
+      const vendorOrigen = path.join(RAIZ_PKG, 'scripts', 'vendor', vendorNombre);
+      const vendorDestino = path.join(rutas.base, 'scripts', 'vendor', vendorNombre);
+      if (fs.existsSync(vendorOrigen)) {
+        try {
+          copiarDirectorio(vendorOrigen, vendorDestino);
+          console.log(`[vendor] ${vendorNombre} copiado a ${vendorDestino}`);
+        } catch (err) {
+          console.error(`  ! Error copiando ${vendorNombre}: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  // 10. Reporte final
+  console.log('\n' + '='.repeat(40));
+  console.log('Resultado de instalación');
+  console.log('='.repeat(40));
+  console.log(`  Target:     ${target} (${runtime.nombre})`);
+  console.log(`  Perfil:     ${perfil}`);
+  console.log(`  Ubicación:  ${rutas.base}`);
+  console.log(`  Instalados: ${instalados}`);
+  console.log(`  Protegidos: ${protegidos} (datos de usuario preservados)`);
+  console.log(`  Evolucionados: ${evolucionados} (mejorados por auto-evolución, preservados)`);
+  console.log(`  Respaldados: ${estado.backups ? estado.backups.length : 0}`);
+  console.log(`  Colisiones: ${colisiones}`);
+  console.log(`  Errores:    ${errores}`);
+  console.log(`  Estado:     ${rutaEstado}`);
+
+  if (resolucion.warnings.length > 0) {
+    console.log('\nAdvertencias:');
+    for (const w of resolucion.warnings) {
+      console.log(`  ! ${w}`);
+    }
+  }
+
+  // 11. Cleanup automático de backups antiguos (conservar últimas 3 versiones)
+  const cleanup = limpiarBackups(process.cwd(), 3);
+  if (cleanup.eliminados > 0) {
+    console.log(`\n[cleanup] ${cleanup.eliminados} backup(s) antiguo(s) eliminado(s) (${cleanup.liberadoMB} MB liberados, ${cleanup.conservados} conservados)`);
+  }
+
+  // 12. Actualizar manifest y .gitignore (solo para instalaciones locales)
+  if (!esGlobal) {
+    const cwd = process.cwd();
+
+    // Actualiza manifest con target y profile realmente usados
+    escribirManifest(cwd, { target, profile: perfil, version: VERSION });
+
+    // Agrega entradas gitignore específicas del runtime si no son las base (claude)
+    const extrasRuntime = entradasParaRuntime(target);
+    actualizarGitignore(cwd, extrasRuntime);
+    console.log('[manifest] .swl-ses actualizado.');
+    console.log('[gitignore] Sección swl-ses actualizada.');
+
+    // 13. Limpiar archivos swl-ses que estén tracked en git
+    // SWL-SES es tooling (como node_modules), no se commitea.
+    // Si el usuario commiteó archivos antes de tener el .gitignore correcto,
+    // los quitamos del índice para que git deje de trackearlos.
+    const limpieza = limpiarTracked(cwd, extrasRuntime);
+    if (limpieza.eliminados > 0) {
+      console.log(`[git] ${limpieza.eliminados} archivo(s) swl-ses removido(s) del índice de git (los archivos siguen en disco).`);
+    }
+  }
+
+  console.log('\nSiguiente paso:');
+  console.log('  npx swl-ses@latest doctor');
+  console.log('');
+  console.log('  (usar @latest evita el caché stale de npx — ver MANUAL_USO.md)');
+  console.log('');
+
+  if (errores > 0) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Instala un archivo individual en el directorio destino correcto
+ */
+function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
+  // Verificar que el target soporta este tipo de componente
+  if (runtime.tiposSoportados && !runtime.tiposSoportados.includes(archivo.tipo)) {
+    return { instalado: false, razon: `Target "${runtime.id}" no soporta "${archivo.tipo}"` };
+  }
+
+  let dirDestino;
+
+  switch (archivo.tipo) {
+    case 'agentes':
+      dirDestino = rutas.agentes;
+      break;
+    case 'habilidades':
+      dirDestino = rutas.habilidades;
+      break;
+    case 'comandos':
+      dirDestino = rutas.comandos;
+      break;
+    case 'reglas':
+      dirDestino = rutas.reglas;
+      break;
+    case 'hooks':
+      dirDestino = rutas.hooks;
+      break;
+    case 'plantillas':
+      // Las plantillas van a .planning/
+      dirDestino = path.join(process.cwd(), '.planning');
+      break;
+    default:
+      dirDestino = rutas.base;
+  }
+
+  if (!dirDestino) {
+    return { instalado: false, razon: `Target no soporta tipo "${archivo.tipo}"` };
+  }
+
+  // Crear directorio destino si no existe
+  if (!fs.existsSync(dirDestino)) {
+    fs.mkdirSync(dirDestino, { recursive: true });
+  }
+
+  let nombreArchivo = path.basename(archivo.origen);
+
+  // Flat naming: convierte rutas jerárquicas en nombres planos con __
+  // Ejemplo: habilidades/build-errors-python → build-errors-python (sin cambio, ya es plano)
+  // Ejemplo: reglas/lenguajes/java/java-estilo.md → java__java-estilo.md
+  // Patrón adoptado de skillshare (internal/sync/naming.go)
+  if (opciones.flatNaming && archivo.rutaRelativa) {
+    const partes = archivo.rutaRelativa.split('/');
+    if (partes.length > 2) {
+      // Tomar desde el segundo nivel en adelante, unir con __
+      nombreArchivo = partes.slice(1).join('__');
+    }
+  }
+
+  // Reglas de lenguaje: preservar subdirectorio (reglas/lenguajes/LANG/archivo.md → .claude/rules/LANG/archivo.md)
+  // Sin esto todos los archivos colisionarían con el mismo nombre en la raíz.
+  let destino;
+  if (
+    archivo.tipo === 'reglas' &&
+    archivo.rutaRelativa &&
+    archivo.rutaRelativa.startsWith('reglas/lenguajes/')
+  ) {
+    const resto = archivo.rutaRelativa.slice('reglas/lenguajes/'.length);
+    const partes = resto.split('/');
+    if (partes.length >= 2) {
+      const subdirLang = path.join(dirDestino, partes[0]);
+      if (!fs.existsSync(subdirLang)) {
+        fs.mkdirSync(subdirLang, { recursive: true });
+      }
+      destino = path.join(subdirLang, partes[1]);
+    } else {
+      destino = path.join(dirDestino, nombreArchivo);
+    }
+  } else {
+    destino = path.join(dirDestino, nombreArchivo);
+  }
+
+  // Seguridad: validar ruta
+  validarRuta(dirDestino, nombreArchivo);
+
+  // Verificar archivo sensible
+  if (esArchivoSensible(nombreArchivo)) {
+    console.log(`  ! Archivo sensible omitido: ${nombreArchivo}`);
+    return { instalado: false, razon: 'archivo sensible' };
+  }
+
+  // Nivel 1: Verificar si el destino está protegido (datos de usuario)
+  const rutaRelativaProyecto = path.relative(process.cwd(), destino);
+  const proteccion = esProtegido(rutaRelativaProyecto);
+  if (proteccion.protegido && fs.existsSync(destino)) {
+    console.log(`  ~ Protegido: ${nombreArchivo} (${proteccion.razon})`);
+    return { instalado: false, protegido: true };
+  }
+
+  // Evolución: Verificar si el destino fue evolucionado por auto-evolución
+  const esComponenteEvolucionable = ['agentes', 'habilidades', 'comandos', 'reglas'].includes(archivo.tipo);
+  if (esComponenteEvolucionable && fs.existsSync(destino) && opciones.force) {
+    // Resolver ruta absoluta del origen (archivo.origen es relativo al paquete)
+    const origenAbsoluto = path.resolve(RAIZ_PKG, archivo.origen);
+    const strategy = decideUpdateStrategy(destino, origenAbsoluto, opciones.versionActual || '');
+    if (strategy.strategy === 'preserve') {
+      console.log(`  ★ Evolucionado: ${nombreArchivo} — preservado (${strategy.reason})`);
+      return { instalado: false, evolucionado: true, destino };
+    }
+    if (strategy.strategy === 'conflict') {
+      // Crear backup del archivo evolucionado ANTES de sobrescribir
+      if (opciones.versionAnterior) {
+        const backup = crearBackup(process.cwd(), destino, opciones.versionAnterior);
+        if (backup.respaldado) {
+          console.log(`  ⚠ Conflicto: ${nombreArchivo} — evolucionado localmente + cambios en versión nueva`);
+          console.log(`    ↩ Backup evolucionado: ${path.relative(process.cwd(), backup.rutaBackup)}`);
+          if (opciones.estado) {
+            registrarBackup(opciones.estado, {
+              rutaOriginal: destino,
+              rutaBackup: backup.rutaBackup,
+              version: opciones.versionAnterior,
+              evolucionado: true,
+            });
+          }
+        }
+      }
+      // Intentar merge: generar diff de mutaciones para re-aplicación
+      const merge = mergeEvolved(destino, origenAbsoluto, opciones.versionActual || '');
+      if (merge.merged && merge.diffPath) {
+        console.log(`    ⊕ Diff generado: ${path.relative(process.cwd(), merge.diffPath)} (${merge.diffsCount} mutaciones)`);
+        console.log(`    → Ejecutar /swl:autoresearch para re-aplicar mutaciones sobre v${opciones.versionActual}`);
+      } else if (merge.merged) {
+        console.log(`    ⊕ Merge exitoso: campos evolved re-aplicados sin cambios de contenido`);
+        return { instalado: false, evolucionado: true, destino };
+      }
+    }
+  }
+
+  // Verificar colisión
+  if (fs.existsSync(destino) && !opciones.force) {
+    console.log(`  - Colisión: ${nombreArchivo} (usa --force para sobreescribir)`);
+    return { instalado: false, colision: true };
+  }
+
+  // Nivel 2: Backup antes de sobreescribir con --force
+  if (fs.existsSync(destino) && opciones.force && opciones.versionAnterior) {
+    const backup = crearBackup(process.cwd(), destino, opciones.versionAnterior);
+    if (backup.respaldado) {
+      console.log(`  ↩ Backup: ${nombreArchivo} → ${path.relative(process.cwd(), backup.rutaBackup)}`);
+      if (opciones.estado) {
+        registrarBackup(opciones.estado, {
+          rutaOriginal: destino,
+          rutaBackup: backup.rutaBackup,
+          version: opciones.versionAnterior,
+        });
+      }
+    }
+  }
+
+  // Copiar, symlink o flat-copy según syncMode
+  if (fs.existsSync(archivo.origen)) {
+    const stat = fs.statSync(archivo.origen);
+    const modo = opciones.syncMode || 'copy';
+
+    if (modo === 'symlink') {
+      // Symlink mode: crear enlace simbólico en lugar de copiar.
+      // Cambios en la fuente se reflejan instantáneamente en el destino.
+      // Ideal para desarrollo del repo fuente de swl-ses.
+      try {
+        if (fs.existsSync(destino)) {
+          const dStat = fs.lstatSync(destino);
+          if (dStat.isSymbolicLink()) fs.unlinkSync(destino);
+          else if (dStat.isDirectory()) fs.rmSync(destino, { recursive: true });
+          else fs.unlinkSync(destino);
+        }
+        const origenAbsoluto = path.resolve(archivo.origen);
+        fs.symlinkSync(origenAbsoluto, destino, stat.isDirectory() ? 'junction' : 'file');
+        console.log(`  ~ ${path.relative(rutas.base, destino)} (symlink)`);
+        return { instalado: true, destino };
+      } catch (symlinkErr) {
+        // Fallback a copy si symlink falla (permisos, filesystem)
+        console.log(`  ! Symlink falló (${symlinkErr.code || symlinkErr.message}), usando copy`);
+      }
+    }
+
+    // Copy mode (default) o fallback de symlink
+    if (stat.isDirectory()) {
+      copiarDirectorio(archivo.origen, path.join(dirDestino, nombreArchivo));
+    } else {
+      fs.copyFileSync(archivo.origen, destino);
+    }
+    console.log(`  + ${path.relative(rutas.base, destino)}`);
+    return { instalado: true, destino };
+  } else {
+    return { instalado: false, razon: 'origen no existe' };
+  }
+}
+
+/**
+ * Copia un directorio recursivamente
+ */
+function copiarDirectorio(origen, destino) {
+  if (!fs.existsSync(destino)) {
+    fs.mkdirSync(destino, { recursive: true });
+  }
+
+  const entradas = fs.readdirSync(origen, { withFileTypes: true });
+  for (const entrada of entradas) {
+    const src = path.join(origen, entrada.name);
+    const dst = path.join(destino, entrada.name);
+
+    if (entrada.isDirectory()) {
+      copiarDirectorio(src, dst);
+    } else {
+      fs.copyFileSync(src, dst);
+    }
+  }
+}
+
+/**
+ * Elimina subdirectorios de reglas de lenguaje en .claude/rules/ para lenguajes
+ * que NO están en el stack detectado del proyecto.
+ *
+ * Solo borra subdirectorios cuyo nombre coincide con un lenguaje conocido del sistema
+ * (java, go, rust, etc.). Nunca toca archivos en la raíz de .claude/rules/.
+ *
+ * @param {string} dirReglas - Ruta a .claude/rules/ (rutas.reglas)
+ * @param {Set<string>} stackDetectado - Lenguajes detectados por detectarStack()
+ * @returns {{ eliminados: number, lenguajes: string[] }}
+ */
+function limpiarReglasSinStack(dirReglas, stackDetectado) {
+  const { LENGUAJES_CONOCIDOS } = require('./lib/detectar-stack');
+  const lenguajesEliminados = [];
+
+  if (!fs.existsSync(dirReglas)) {
+    return { eliminados: 0, lenguajes: [] };
+  }
+
+  let entradas;
+  try {
+    entradas = fs.readdirSync(dirReglas, { withFileTypes: true });
+  } catch {
+    return { eliminados: 0, lenguajes: [] };
+  }
+
+  for (const entrada of entradas) {
+    if (!entrada.isDirectory()) continue;
+
+    const lang = entrada.name;
+    // Solo actuar sobre subdirectorios que son lenguajes conocidos del sistema
+    if (!LENGUAJES_CONOCIDOS.has(lang)) continue;
+    // Si el lenguaje está en el stack detectado, conservar
+    if (stackDetectado.has(lang)) continue;
+
+    const dirLang = path.join(dirReglas, lang);
+    try {
+      fs.rmSync(dirLang, { recursive: true, force: true });
+      lenguajesEliminados.push(lang);
+    } catch (err) {
+      console.log(`  ! No se pudo eliminar ${dirLang}: ${err.message}`);
+    }
+  }
+
+  return { eliminados: lenguajesEliminados.length, lenguajes: lenguajesEliminados.sort() };
+}
+
+module.exports = install;