@saulwade/swl-ses 1.0.0

package/scripts/doctor.js

@@ -0,0 +1,559 @@
+'use strict';
+
+/**
+ * swl-ses doctor
+ * Diagnóstico interactivo de la instalación SWL: permisos, estructura, conflictos.
+ * Ofrece reparar automáticamente los problemas encontrados.
+ * No-interactivo con --force o sin TTY.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { detectarRuntimes, detectarInstalacionesDuales } = require('./lib/detectar-runtime');
+const { cargarEstado, verificarIntegridad } = require('./lib/estado');
+const { verificarHooks, repararHooks, rutaSettings, cargarHooksConfig, desregistrarHooks, esHookSWL, verificarOptimizaciones, registrarOptimizaciones, validarEstructuraSettings } = require('./lib/hooks-settings');
+const {
+  color, icono, encabezado, formatearPaso, formatearAdvertencia, formatearError,
+  lineaSeparadora, spinner, preguntarSiNo, ES_TTY,
+} = require('./lib/ui');
+const { versionRemotaParalela } = require('./lib/npm-version');
+
+const VERSION = require('../package.json').version;
+
+/**
+ * Consulta la versión más reciente publicada en npm (best-effort, no bloquea).
+ * Best-effort: si no hay red o no responde antes del timeout, devuelve null.
+ */
+async function obtenerVersionRemota() {
+  const r = await versionRemotaParalela({ timeoutMs: 10000 });
+  return r.version;
+}
+
+async function doctor(opciones = {}) {
+  const force = opciones.force || !ES_TTY;
+  const cwd = process.cwd();
+
+  let errores = 0;
+  let advertencias = 0;
+  let ok = 0;
+  const reparables = [];
+
+  console.log(encabezado('swl-ses doctor', VERSION));
+
+  // 0. Verificar si hay versión más reciente en npm
+  const versionRemota = await obtenerVersionRemota();
+  if (versionRemota && versionRemota !== VERSION) {
+    console.log(formatearAdvertencia('Versión', `Ejecutando v${VERSION}, pero v${versionRemota} está disponible en npm`));
+    console.log(`    ${color.dim('Para actualizar: npx @saulwade/swl-ses@latest update --force')}`);
+    console.log('');
+    advertencias++;
+  }
+
+  // 1. Verificar Node.js
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (major >= 18) {
+    console.log(formatearPaso('Node.js', `${nodeVersion} (soportado)`));
+    ok++;
+  } else {
+    console.log(formatearError('Node.js', `${nodeVersion} (se requiere >= 18)`));
+    errores++;
+  }
+
+  // 2. Detectar runtimes
+  const runtimes = detectarRuntimes();
+  if (runtimes.length > 0) {
+    console.log(formatearPaso('Runtimes', runtimes.map(r => r.nombre).join(', ')));
+    ok++;
+  } else {
+    console.log(formatearAdvertencia('Runtimes', 'Ningún runtime de IA detectado'));
+    advertencias++;
+  }
+
+  // 3. Verificar .planning/
+  const planningDir = path.join(cwd, '.planning');
+  if (fs.existsSync(planningDir)) {
+    const archivosEsperados = ['PROYECTO.md', 'REQUISITOS.md', 'HOJA-RUTA.md', 'ESTADO.md'];
+    const faltantes = archivosEsperados.filter(
+      f => !fs.existsSync(path.join(planningDir, f))
+    );
+
+    if (faltantes.length === 0) {
+      console.log(formatearPaso('.planning/', 'Estructura completa'));
+      ok++;
+    } else {
+      console.log(formatearAdvertencia('.planning/', `Faltan: ${faltantes.join(', ')}`));
+      advertencias++;
+      reparables.push({
+        descripcion: `Crear ${faltantes.length} archivo(s) faltante(s) en .planning/: ${faltantes.join(', ')}`,
+        reparar: () => {
+          for (const f of faltantes) {
+            const ruta = path.join(planningDir, f);
+            const nombre = path.basename(f, '.md');
+            fs.writeFileSync(ruta, `# ${nombre}\n\n(Generado por swl-ses doctor)\n`, 'utf-8');
+          }
+          return `${faltantes.length} archivo(s) creado(s)`;
+        },
+      });
+    }
+
+    const researchDir = path.join(planningDir, 'research');
+    if (fs.existsSync(researchDir)) {
+      console.log(formatearPaso('.planning/research/', 'Presente'));
+      ok++;
+    } else {
+      console.log(formatearAdvertencia('.planning/research/', 'No encontrado'));
+      advertencias++;
+      reparables.push({
+        descripcion: 'Crear directorio .planning/research/',
+        reparar: () => {
+          fs.mkdirSync(researchDir, { recursive: true });
+          return 'Directorio creado';
+        },
+      });
+    }
+  } else {
+    console.log(formatearAdvertencia('.planning/', 'No inicializado'));
+    advertencias++;
+    reparables.push({
+      descripcion: 'Inicializar .planning/ con estructura base',
+      reparar: () => {
+        fs.mkdirSync(planningDir, { recursive: true });
+        fs.mkdirSync(path.join(planningDir, 'research'), { recursive: true });
+        for (const f of ['PROYECTO.md', 'REQUISITOS.md', 'HOJA-RUTA.md', 'ESTADO.md']) {
+          const nombre = path.basename(f, '.md');
+          fs.writeFileSync(path.join(planningDir, f), `# ${nombre}\n\n(Generado por swl-ses doctor)\n`, 'utf-8');
+        }
+        return '.planning/ creado con estructura completa';
+      },
+    });
+  }
+
+  // 4. Verificar _userland/
+  const userlandDir = path.join(cwd, '_userland');
+  if (fs.existsSync(userlandDir)) {
+    console.log(formatearPaso('_userland/', 'Presente'));
+    ok++;
+
+    const agentesUser = contarArchivos(path.join(userlandDir, 'agentes'), '.md');
+    const habsUser = contarDirectorios(path.join(userlandDir, 'habilidades'));
+
+    if (agentesUser > 0 || habsUser > 0) {
+      console.log(formatearPaso('Componentes usuario', `${agentesUser} agentes, ${habsUser} habilidades`));
+    }
+  } else {
+    console.log(formatearAdvertencia('_userland/', 'No encontrado'));
+    advertencias++;
+    reparables.push({
+      descripcion: 'Crear _userland/ con estructura base',
+      reparar: () => {
+        for (const sub of ['agentes', 'habilidades', 'reglas', 'plugins']) {
+          fs.mkdirSync(path.join(userlandDir, sub), { recursive: true });
+        }
+        return '_userland/ creado con subdirectorios';
+      },
+    });
+  }
+
+  // 5. Verificar estado de instalación por runtime
+  for (const runtime of runtimes) {
+    // Deduplicar: cuando global y local resuelven al mismo path (ej: running desde home dir)
+    const dirsRaw = [runtime.global, path.resolve(runtime.local)];
+    const dirs = [...new Set(dirsRaw)];
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) continue;
+
+      const esGlobal = dir === runtime.global;
+      const estado = cargarEstado(dir);
+      if (estado) {
+        const { integro, problemas } = verificarIntegridad(estado);
+        if (integro) {
+          console.log(formatearPaso(`${runtime.nombre} (${esGlobal ? 'global' : 'proyecto'})`, `Instalación íntegra ${color.dim(`— ${estado.archivosInstalados.length} archivos`)}`));
+          ok++;
+        } else {
+          console.log(formatearAdvertencia(`${runtime.nombre} (${esGlobal ? 'global' : 'proyecto'})`, `${problemas.length} archivos con problemas`));
+          for (const p of problemas.slice(0, 5)) {
+            console.log(`    ${color.dim('-')} ${p.mensaje}`);
+          }
+          advertencias++;
+        }
+
+        // 5b. Verificar hooks
+        if (runtime.soportaHooks) {
+          if (esGlobal) {
+            const settingsPath = rutaSettings(runtime, dir);
+            const settings = require('./lib/hooks-settings').leerSettings(settingsPath);
+            let hooksGlobalesSWL = 0;
+            for (const evento of ['PreToolUse', 'PostToolUse']) {
+              const entradas = (settings.hooks && settings.hooks[evento]) || [];
+              hooksGlobalesSWL += entradas.filter(e => esHookSWL(e)).length;
+            }
+            if (hooksGlobalesSWL > 0) {
+              console.log(formatearAdvertencia(`Hooks ${runtime.nombre} (global)`, `${hooksGlobalesSWL} hooks SWL en settings global — causa ejecución duplicada`));
+              advertencias++;
+              reparables.push({
+                descripcion: `Eliminar ${hooksGlobalesSWL} hooks SWL del scope global de ${runtime.nombre}`,
+                reparar: () => {
+                  const resultado = desregistrarHooks(settingsPath);
+                  return `${resultado.eliminados} hooks removidos del scope global (${resultado.preservados} externos preservados)`;
+                },
+              });
+            }
+          } else {
+            const settingsPath = rutaSettings(runtime, dir);
+            // hooks-config.json es la fuente de verdad para hooks registrables.
+            // Los módulos tipo "hooks" incluyen archivos auxiliares (libs, scripts,
+            // comandos) que NO deben registrarse en settings.json.
+            const hooksConfig = cargarHooksConfig();
+            let hooksInstalados = Object.keys(hooksConfig);
+
+            if (hooksInstalados.length > 0) {
+              const resultado = verificarHooks(settingsPath, hooksInstalados);
+
+              if (resultado.ok) {
+                console.log(formatearPaso(`Hooks ${runtime.nombre}`, `${resultado.registrados.length} hooks registrados`));
+                ok++;
+              } else {
+                if (resultado.faltantes.length > 0) {
+                  console.log(formatearError(`Hooks ${runtime.nombre}`, `${resultado.faltantes.length} hooks NO registrados`));
+                  for (const f of resultado.faltantes) {
+                    console.log(`    ${color.dim('-')} Faltante: ${f}`);
+                  }
+                  errores++;
+                  reparables.push({
+                    descripcion: `Registrar ${resultado.faltantes.length} hooks faltantes en settings.json`,
+                    reparar: async () => {
+                      const instalador = require('./instalador');
+                      await instalador({
+                        target: runtime.id,
+                        profile: estado.perfil,
+                        global: estado.global,
+                        force: true,
+                      });
+                      return `Hooks re-registrados via re-instalación del perfil ${estado.perfil}`;
+                    },
+                  });
+                }
+                if (resultado.incorrectos.length > 0) {
+                  const reparacion = repararHooks(settingsPath);
+                  if (reparacion.reparados > 0) {
+                    console.log(formatearPaso(`Hooks ${runtime.nombre}`, `${reparacion.reparados} hooks reparados automáticamente`));
+                    ok++;
+                  } else {
+                    console.log(formatearAdvertencia(`Hooks ${runtime.nombre}`, `${resultado.incorrectos.length} hooks con problemas`));
+                    advertencias++;
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // 5-dual. Detectar instalaciones en AMBOS scopes (global + proyecto).
+  // Claude Code lee componentes de ambos y los muestra en la UI como entradas
+  // separadas, lo que confunde al usuario aunque técnicamente sea válido.
+  for (const runtime of runtimes) {
+    const dual = detectarInstalacionesDuales(runtime.id);
+    if (!dual.hayConflicto) continue;
+
+    console.log(formatearAdvertencia(
+      `Scope ${runtime.nombre}`,
+      'Instalación duplicada en global Y proyecto — los comandos pueden duplicarse en la UI'
+    ));
+    console.log(`    ${color.dim('Global:')}   ${dual.globalDir}`);
+    console.log(`    ${color.dim('Proyecto:')} ${dual.localDir}`);
+    console.log(`    ${color.dim('Sugerencia: conserva solo el scope que uses y desinstala el otro con:')}`);
+    console.log(`      ${color.dim('swl-ses uninstall --global          # para remover el scope global')}`);
+    console.log(`      ${color.dim('swl-ses uninstall                    # para remover el scope del proyecto')}`);
+    advertencias++;
+  }
+
+  // 5b-2. Verificar conteo de componentes contra perfil esperado
+  for (const runtime of runtimes) {
+    const dir = path.resolve(runtime.local);
+    if (!fs.existsSync(dir)) continue;
+    const estado = cargarEstado(dir);
+    if (!estado || !estado.perfil) continue;
+
+    try {
+      const { resolverPerfil } = require('./lib/manifiestos');
+      const { detectarStack, filtrarReglasPorStack } = require('./lib/detectar-stack');
+      const resolucion = resolverPerfil(estado.perfil, { target: estado.target });
+
+      // Aplicar el mismo filtro de reglas por stack que usa el instalador
+      const stackDetectado = detectarStack(cwd);
+      const filtrado = filtrarReglasPorStack(resolucion.archivos, stackDetectado);
+      resolucion.archivos = filtrado.archivos;
+
+      // Contar esperados por tipo (solo tipos principales)
+      const tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas'];
+      const esperadosPorTipo = {};
+      for (const archivo of resolucion.archivos) {
+        const tipo = archivo.tipo || 'otros';
+        if (tiposPrincipales.includes(tipo)) {
+          esperadosPorTipo[tipo] = (esperadosPorTipo[tipo] || 0) + 1;
+        }
+      }
+
+      // Contar instalados por tipo
+      const instaladosPorTipo = {};
+      for (const archivo of estado.archivosInstalados) {
+        const tipo = archivo.tipo || 'otros';
+        if (tiposPrincipales.includes(tipo)) {
+          instaladosPorTipo[tipo] = (instaladosPorTipo[tipo] || 0) + 1;
+        }
+      }
+
+      // Comparar tipos principales
+      const discrepancias = [];
+      for (const [tipo, esperado] of Object.entries(esperadosPorTipo)) {
+        const instalado = instaladosPorTipo[tipo] || 0;
+        if (instalado < esperado) {
+          discrepancias.push(`${tipo}: ${instalado}/${esperado}`);
+        }
+      }
+
+      const totalEsperado = resolucion.archivos.length;
+      const totalInstalado = estado.archivosInstalados.length;
+      const detalle = Object.entries(esperadosPorTipo)
+        .map(([t, n]) => `${instaladosPorTipo[t] || 0}/${n} ${t}`)
+        .join(', ');
+
+      if (discrepancias.length === 0) {
+        console.log(formatearPaso(`Conteo ${runtime.nombre}`, `${totalInstalado} archivos (${detalle})`));
+        ok++;
+      } else {
+        console.log(formatearAdvertencia(`Conteo ${runtime.nombre}`, `${totalInstalado} archivos — faltan: ${discrepancias.join(', ')}`));
+        advertencias++;
+        reparables.push({
+          descripcion: `Reinstalar perfil ${estado.perfil} para corregir conteos`,
+          reparar: async () => {
+            const instalador = require('./instalador');
+            await instalador({
+              target: estado.target || runtime.id,
+              profile: estado.perfil,
+              global: estado.global,
+              force: true,
+            });
+            return `Reinstalación completada con perfil ${estado.perfil}`;
+          },
+        });
+      }
+    } catch (err) {
+      // Si falla la resolución del perfil, informar pero no bloquear
+      console.log(formatearAdvertencia(`Conteo ${runtime.nombre}`, `No se pudo verificar: ${err.message}`));
+      advertencias++;
+    }
+  }
+
+  // 5c. Verificar optimizaciones de rendimiento en settings.json
+  for (const runtime of runtimes) {
+    const dir = path.resolve(runtime.local);
+    if (!fs.existsSync(dir)) continue;
+    const estado = cargarEstado(dir);
+    if (!estado) continue;
+
+    const settingsPath = rutaSettings(runtime, dir);
+    const optResult = verificarOptimizaciones(settingsPath);
+    if (optResult.ok) {
+      console.log(formatearPaso(`Optimizaciones ${runtime.nombre}`, 'ENABLE_TOOL_SEARCH y showThinkingSummaries activos'));
+      ok++;
+    } else {
+      console.log(formatearAdvertencia(`Optimizaciones ${runtime.nombre}`, `Faltantes: ${optResult.faltantes.join(', ')}`));
+      advertencias++;
+      reparables.push({
+        descripcion: `Aplicar optimizaciones de rendimiento en settings.json: ${optResult.faltantes.join(', ')}`,
+        reparar: () => {
+          const r = registrarOptimizaciones(settingsPath);
+          return `${r.aplicadas} optimización(es) aplicada(s)`;
+        },
+      });
+    }
+  }
+
+  // 5d. Validar estructura de settings.json
+  for (const runtime of runtimes) {
+    const dir = path.resolve(runtime.local);
+    if (!fs.existsSync(dir)) continue;
+    const estado = cargarEstado(dir);
+    if (!estado) continue;
+
+    const settingsPath = rutaSettings(runtime, dir);
+    if (fs.existsSync(settingsPath)) {
+      const structResult = validarEstructuraSettings(settingsPath);
+      if (structResult.ok) {
+        console.log(formatearPaso(`Estructura settings ${runtime.nombre}`, 'Formato válido'));
+        ok++;
+      } else {
+        console.log(formatearError(`Estructura settings ${runtime.nombre}`, `${structResult.problemas.length} problema(s) de formato`));
+        for (const p of structResult.problemas.slice(0, 5)) {
+          console.log(`    ${color.dim('-')} ${p}`);
+        }
+        errores++;
+      }
+    }
+  }
+
+  // 6. Verificar permisos de escritura
+  const dirsPrueba = [cwd, planningDir, userlandDir].filter(d => fs.existsSync(d));
+  for (const dir of dirsPrueba) {
+    try {
+      fs.accessSync(dir, fs.constants.W_OK);
+    } catch {
+      console.log(formatearError('Permisos', `Sin permisos de escritura en: ${dir}`));
+      errores++;
+    }
+  }
+
+  // 7. Verificar .env + .gitignore
+  const envFile = path.join(cwd, '.env');
+  const gitignore = path.join(cwd, '.gitignore');
+  if (fs.existsSync(envFile)) {
+    if (fs.existsSync(gitignore)) {
+      const contenido = fs.readFileSync(gitignore, 'utf-8');
+      if (!contenido.includes('.env')) {
+        console.log(formatearAdvertencia('Seguridad', '.env existe pero no está en .gitignore'));
+        advertencias++;
+        reparables.push({
+          descripcion: 'Agregar .env a .gitignore',
+          reparar: () => {
+            fs.appendFileSync(gitignore, '\n.env\n', 'utf-8');
+            return '.env agregado a .gitignore';
+          },
+        });
+      } else {
+        console.log(formatearPaso('Seguridad', '.env protegido por .gitignore'));
+        ok++;
+      }
+    } else {
+      console.log(formatearError('Seguridad', '.env existe sin .gitignore — riesgo de filtración'));
+      errores++;
+      reparables.push({
+        descripcion: 'Crear .gitignore con .env',
+        reparar: () => {
+          fs.writeFileSync(gitignore, '.env\nnode_modules/\n', 'utf-8');
+          return '.gitignore creado con .env';
+        },
+      });
+    }
+  }
+
+  // 8. Verificar componentes externos
+  for (const runtime of runtimes) {
+    const dirs = [runtime.global, path.resolve(runtime.local)];
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) continue;
+      const estado = cargarEstado(dir);
+      if (estado && estado.componentesExternos && estado.componentesExternos.length > 0) {
+        let extOk = 0;
+        let extFaltantes = 0;
+        for (const ext of estado.componentesExternos) {
+          const tipoDir = ext.tipo === 'skills'
+            ? (runtime.dirHabilidades ? path.join(dir, runtime.dirHabilidades) : null)
+            : (runtime.dirAgentes ? path.join(dir, runtime.dirAgentes) : null);
+          if (!tipoDir) continue;
+
+          const ruta = ext.tipo === 'skills'
+            ? path.join(tipoDir, ext.nombre)
+            : path.join(tipoDir, ext.nombre + '.md');
+
+          if (fs.existsSync(ruta)) {
+            extOk++;
+          } else {
+            extFaltantes++;
+          }
+        }
+        if (extFaltantes > 0) {
+          console.log(formatearAdvertencia(`Externos ${runtime.nombre}`, `${extFaltantes} componentes externos faltantes`));
+          advertencias++;
+        } else if (extOk > 0) {
+          console.log(formatearPaso(`Externos ${runtime.nombre}`, `${extOk} componentes externos íntegros`));
+          ok++;
+        }
+      }
+    }
+  }
+
+  // Reporte final
+  console.log('');
+  console.log(`  ${lineaSeparadora()}`);
+  console.log(`  Resultado: ${color.verde(`${ok} ok`)}, ${color.amarillo(`${advertencias} advertencias`)}, ${color.rojo(`${errores} errores`)}`);
+
+  if (errores === 0 && advertencias === 0) {
+    console.log(`\n  ${color.verde('Sistema SWL en perfecto estado.')}`);
+    console.log('');
+    process.exit(0);
+    return;
+  }
+
+  // Fase 2: Reparación interactiva
+  if (reparables.length > 0) {
+    console.log('');
+    console.log(`  ${color.negrita(`Se encontraron ${reparables.length} problema(s) reparable(s):`)}`);
+    for (let i = 0; i < reparables.length; i++) {
+      console.log(`    ${color.dim(`${i + 1}.`)} ${reparables[i].descripcion}`);
+    }
+    console.log('');
+
+    let proceder = force;
+    if (!proceder) {
+      proceder = await preguntarSiNo('¿Reparar automáticamente?');
+      console.log('');
+    }
+
+    if (proceder) {
+      let reparados = 0;
+      let fallos = 0;
+
+      // NO usar spinner durante reparación: los reparadores pueden invocar
+      // el instalador que tiene prompts interactivos de readline, y el spinner
+      // animando colisiona con el prompt mezclando caracteres en stdout.
+      // Los reparadores imprimen su propio output (install ya es verboso).
+      for (const r of reparables) {
+        try {
+          console.log(`  ${color.cyan('→')} ${r.descripcion}`);
+          // await soporta tanto valores sync como Promises — seguro para reparadores mixtos.
+          const resultado = await r.reparar();
+          reparados++;
+          console.log(formatearPaso('Reparado', resultado));
+        } catch (err) {
+          fallos++;
+          console.log(formatearError('Fallo', `${r.descripcion}: ${err.message}`));
+        }
+      }
+
+      console.log('');
+      if (fallos === 0) {
+        console.log(`  ${color.verde(`${reparados} problema(s) reparado(s). Sistema funcional.`)}`);
+      } else {
+        console.log(`  ${reparados} reparado(s), ${color.rojo(`${fallos} fallo(s)`)}.`);
+      }
+    } else {
+      console.log(`  ${color.dim('Reparación cancelada. Usa --force para reparar sin confirmar.')}`);
+    }
+  } else if (errores > 0) {
+    console.log(`\n  ${color.rojo('Corrige los errores manualmente o ejecuta install de nuevo.')}`);
+  } else {
+    console.log(`\n  ${color.amarillo('Sistema funcional con advertencias menores.')}`);
+  }
+
+  console.log('');
+  process.exit(errores > 0 ? 1 : 0);
+}
+
+function contarArchivos(dir, extension) {
+  if (!fs.existsSync(dir)) return 0;
+  return fs.readdirSync(dir).filter(f => f.endsWith(extension) && !f.startsWith('.')).length;
+}
+
+function contarDirectorios(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.')).length;
+}
+
+module.exports = doctor;