@saulwade/swl-ses 1.0.0

package/scripts/lib/preservar-usuario.js

@@ -0,0 +1,586 @@
+'use strict';
+
+/**
+ * Preservar Usuario — Protección de datos de usuario durante instalación/actualización.
+ *
+ * Garantiza que los aprendizajes, instintos, sesiones, cron jobs, y demás datos
+ * generados por el usuario o por la auto-evolución del sistema NO se pierdan
+ * cuando se actualiza la versión de SWL-SES.
+ *
+ * Tres niveles de protección:
+ *   Nivel 1: Archivos protegidos que NUNCA se sobreescriben (ni con --force)
+ *   Nivel 2: Backup automático antes de sobreescribir con --force
+ *   Nivel 3: Merge inteligente para instintos y skills auto-generados
+ *
+ * @module scripts/lib/preservar-usuario
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Nivel 1: Archivos que NUNCA se sobreescriben
+// ---------------------------------------------------------------------------
+
+/**
+ * Rutas relativas (desde la raíz del proyecto) que contienen datos del usuario
+ * y NUNCA deben sobreescribirse durante una actualización, ni siquiera con --force.
+ *
+ * Estos archivos son generados por:
+ *   - /swl:aprender → APRENDIZAJES.md, CLAUDE.md del proyecto
+ *   - hooks de extracción → APRENDIZAJES.md
+ *   - hooks de degradación → instintos/proyecto.yaml
+ *   - /swl:instintos → instintos/proyecto.yaml
+ *   - /swl:evolucionar → skills auto-generados en habilidades/
+ *   - /swl:crear-skill → skills nuevos en habilidades/
+ *   - session-store → .planning/sessions/*.json
+ *   - context-compressor → .planning/COMPACTACION.md
+ *   - cron-store → .planning/cron/
+ *   - gateway → .planning/gateway-sessions.json
+ *   - agent-comms → .planning/comms/
+ */
+const ARCHIVOS_PROTEGIDOS = [
+  // Aprendizajes del proyecto (generados por hooks y /swl:aprender)
+  '.planning/APRENDIZAJES.md',
+
+  // Estado de compresión de contexto
+  '.planning/COMPACTACION.md',
+
+  // Métricas de sesión
+  '.planning/METRICAS.md',
+
+  // Auditoría de gobernanza
+  '.planning/AUDITORIA.md',
+
+  // Registro de plugins
+  '.planning/PLUGINS.md',
+
+  // Sessions del gateway
+  '.planning/gateway-sessions.json',
+];
+
+/**
+ * Directorios completos que NUNCA se sobreescriben.
+ * Todo su contenido está protegido.
+ */
+const DIRECTORIOS_PROTEGIDOS = [
+  // Sesiones de trabajo (generadas por session-store)
+  '.planning/sessions',
+
+  // Comunicaciones entre agentes
+  '.planning/comms',
+
+  // Jobs y logs de cron
+  '.planning/cron',
+
+  // ADRs de arquitectura (escritos por el usuario/arquitecto-swl)
+  '.planning/adrs',
+
+  // Investigación del proyecto
+  '.planning/research',
+
+  // Extensiones del usuario (agentes, skills, plugins)
+  '_userland',
+];
+
+/**
+ * Patrones de archivo que indican datos generados por el usuario o la auto-evolución.
+ * Si un archivo en el destino coincide con estos patrones, no se sobreescribe.
+ */
+const PATRONES_PROTEGIDOS = [
+  // Instintos del proyecto (generados por hooks y /swl:instintos)
+  /^instintos\/proyecto\.yaml$/,
+
+  // CLAUDE.md del proyecto (puede tener reglas Tipo A de /swl:aprender)
+  /^CLAUDE\.md$/,
+];
+
+// ---------------------------------------------------------------------------
+// Nivel 1: API de verificación
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica si una ruta de destino está protegida contra sobreescritura.
+ *
+ * @param {string} rutaRelativa - Ruta relativa desde la raíz del proyecto.
+ * @returns {{ protegido: boolean, razon?: string }}
+ */
+function esProtegido(rutaRelativa) {
+  if (!rutaRelativa || typeof rutaRelativa !== 'string') {
+    return { protegido: false };
+  }
+
+  // Normalizar separadores
+  const normalizada = rutaRelativa.replace(/\\/g, '/');
+
+  // Verificar archivos específicos
+  for (const archivo of ARCHIVOS_PROTEGIDOS) {
+    if (normalizada === archivo || normalizada.endsWith('/' + archivo)) {
+      return {
+        protegido: true,
+        razon: `Archivo protegido: ${archivo} contiene datos del usuario`,
+      };
+    }
+  }
+
+  // Verificar si está dentro de un directorio protegido
+  for (const dir of DIRECTORIOS_PROTEGIDOS) {
+    if (normalizada.startsWith(dir + '/') || normalizada === dir) {
+      return {
+        protegido: true,
+        razon: `Directorio protegido: ${dir}/ contiene datos del usuario`,
+      };
+    }
+  }
+
+  // Verificar patrones
+  for (const patron of PATRONES_PROTEGIDOS) {
+    if (patron.test(normalizada)) {
+      return {
+        protegido: true,
+        razon: `Patrón protegido: ${normalizada} coincide con datos de usuario`,
+      };
+    }
+  }
+
+  return { protegido: false };
+}
+
+/**
+ * Verifica si un archivo destino tiene contenido generado por el usuario
+ * que no existe en el paquete fuente (indica personalización local).
+ *
+ * @param {string} destino    - Ruta absoluta del archivo destino.
+ * @param {string} [origen]   - Ruta absoluta del archivo origen (del paquete).
+ * @returns {boolean} true si el destino tiene modificaciones del usuario.
+ */
+function tieneModificacionesUsuario(destino, origen) {
+  if (!fs.existsSync(destino)) return false;
+  if (!origen || !fs.existsSync(origen)) return true; // Sin origen = todo es del usuario
+
+  try {
+    const contenidoDestino = fs.readFileSync(destino, 'utf8');
+    const contenidoOrigen  = fs.readFileSync(origen, 'utf8');
+    return contenidoDestino !== contenidoOrigen;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Nivel 2: Backup automático
+// ---------------------------------------------------------------------------
+
+/**
+ * Directorio base para backups de actualización.
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {string} version - Versión que se está sobreescribiendo.
+ * @returns {string} Ruta absoluta al directorio de backup.
+ */
+function dirBackup(baseDir, version) {
+  return path.join(baseDir, '.planning', 'backups', `v${version}`);
+}
+
+/**
+ * Crea un backup de un archivo antes de sobreescribirlo.
+ *
+ * @param {string} baseDir       - Raíz del proyecto.
+ * @param {string} rutaAbsoluta  - Ruta absoluta del archivo a respaldar.
+ * @param {string} versionAnterior - Versión del sistema que se está actualizando.
+ * @returns {{ respaldado: boolean, rutaBackup?: string, error?: string }}
+ */
+function crearBackup(baseDir, rutaAbsoluta, versionAnterior) {
+  if (!fs.existsSync(rutaAbsoluta)) {
+    return { respaldado: false, error: 'Archivo no existe' };
+  }
+
+  try {
+    const rutaRelativa = path.relative(baseDir, rutaAbsoluta);
+    const backupDir    = dirBackup(baseDir, versionAnterior);
+    const rutaBackup   = path.join(backupDir, rutaRelativa);
+    const dirPadre     = path.dirname(rutaBackup);
+
+    if (!fs.existsSync(dirPadre)) {
+      fs.mkdirSync(dirPadre, { recursive: true });
+    }
+
+    // Copiar archivo o directorio
+    const stat = fs.statSync(rutaAbsoluta);
+    if (stat.isDirectory()) {
+      _copiarDirectorioRecursivo(rutaAbsoluta, rutaBackup);
+    } else {
+      fs.copyFileSync(rutaAbsoluta, rutaBackup);
+    }
+
+    return { respaldado: true, rutaBackup };
+  } catch (err) {
+    return { respaldado: false, error: err.message };
+  }
+}
+
+/**
+ * Registra un backup en el archivo de estado de instalación.
+ *
+ * @param {object} estado - Objeto de estado de instalación.
+ * @param {object} backup - Info del backup { rutaOriginal, rutaBackup, version }.
+ */
+function registrarBackup(estado, backup) {
+  if (!estado.backups) estado.backups = [];
+  estado.backups.push({
+    ...backup,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Lista backups disponibles.
+ *
+ * @param {string} baseDir
+ * @returns {object[]} Lista de backups { version, fecha, archivos }.
+ */
+function listarBackups(baseDir) {
+  const backupsBase = path.join(baseDir, '.planning', 'backups');
+  if (!fs.existsSync(backupsBase)) return [];
+
+  return fs.readdirSync(backupsBase)
+    .filter(d => d.startsWith('v'))
+    .map(dir => {
+      const fullPath = path.join(backupsBase, dir);
+      const stat = fs.statSync(fullPath);
+      const archivos = _contarArchivosRecursivo(fullPath);
+      return {
+        version: dir.replace(/^v/, ''),
+        fecha: stat.mtime.toISOString(),
+        archivos,
+        ruta: fullPath,
+      };
+    })
+    .sort((a, b) => b.fecha.localeCompare(a.fecha));
+}
+
+/**
+ * Restaura un backup específico.
+ *
+ * @param {string} baseDir
+ * @param {string} version - Versión del backup a restaurar.
+ * @returns {{ restaurado: boolean, archivos: number, error?: string }}
+ */
+function restaurarBackup(baseDir, version) {
+  const backupPath = dirBackup(baseDir, version);
+  if (!fs.existsSync(backupPath)) {
+    return { restaurado: false, archivos: 0, error: `Backup v${version} no encontrado` };
+  }
+
+  try {
+    let archivosRestaurados = 0;
+    _restaurarRecursivo(backupPath, baseDir, () => { archivosRestaurados++; });
+    return { restaurado: true, archivos: archivosRestaurados };
+  } catch (err) {
+    return { restaurado: false, archivos: 0, error: err.message };
+  }
+}
+
+/**
+ * Limpia backups antiguos, conservando solo las últimas N versiones.
+ *
+ * @param {string} baseDir
+ * @param {number} [mantener=3] - Número de versiones recientes a conservar.
+ * @returns {{ eliminados: number, conservados: number, liberadoMB: number }}
+ */
+function limpiarBackups(baseDir, mantener = 3) {
+  const backups = listarBackups(baseDir);
+  if (backups.length <= mantener) {
+    return { eliminados: 0, conservados: backups.length, liberadoMB: 0 };
+  }
+
+  // Los backups ya vienen ordenados por fecha descendente (más reciente primero)
+  const aEliminar = backups.slice(mantener);
+  let bytesLiberados = 0;
+
+  for (const backup of aEliminar) {
+    try {
+      bytesLiberados += _calcularTamanoDirectorio(backup.ruta);
+      fs.rmSync(backup.ruta, { recursive: true, force: true });
+    } catch (_) {}
+  }
+
+  // Si el directorio backups/ quedó vacío, eliminarlo
+  const backupsBase = path.join(baseDir, '.planning', 'backups');
+  try {
+    const remaining = fs.readdirSync(backupsBase);
+    if (remaining.length === 0) {
+      fs.rmdirSync(backupsBase);
+    }
+  } catch (_) {}
+
+  return {
+    eliminados: aEliminar.length,
+    conservados: mantener,
+    liberadoMB: Math.round(bytesLiberados / (1024 * 1024) * 100) / 100,
+  };
+}
+
+/**
+ * Calcula el tamaño total de un directorio recursivamente.
+ * @private
+ */
+function _calcularTamanoDirectorio(dir) {
+  let total = 0;
+  try {
+    const entradas = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entrada of entradas) {
+      const full = path.join(dir, entrada.name);
+      if (entrada.isDirectory()) {
+        total += _calcularTamanoDirectorio(full);
+      } else {
+        total += fs.statSync(full).size;
+      }
+    }
+  } catch (_) {}
+  return total;
+}
+
+// ---------------------------------------------------------------------------
+// Nivel 3: Merge inteligente
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge de instintos: preserva los del usuario, agrega nuevos del sistema.
+ *
+ * Estrategia:
+ *   - Instintos con id que existe en destino: preservar versión del usuario
+ *   - Instintos con id nuevo (solo en origen): agregar al final
+ *   - Instintos en destino que no están en origen: preservar (creados por usuario)
+ *
+ * @param {string} origenPath  - Ruta del archivo de instintos del paquete.
+ * @param {string} destinoPath - Ruta del archivo de instintos del proyecto.
+ * @returns {{ merged: boolean, nuevos: number, preservados: number, error?: string }}
+ */
+function mergeInstintos(origenPath, destinoPath) {
+  if (!fs.existsSync(destinoPath)) {
+    // No hay destino — copiar directamente
+    return { merged: false, nuevos: 0, preservados: 0 };
+  }
+
+  if (!fs.existsSync(origenPath)) {
+    return { merged: true, nuevos: 0, preservados: 0 };
+  }
+
+  try {
+    const contenidoOrigen  = fs.readFileSync(origenPath, 'utf8');
+    const contenidoDestino = fs.readFileSync(destinoPath, 'utf8');
+
+    // Extraer IDs de instintos
+    const idsOrigen  = _extraerIdsInstintos(contenidoOrigen);
+    const idsDestino = _extraerIdsInstintos(contenidoDestino);
+
+    // Instintos nuevos (en origen, no en destino)
+    const idsNuevos = idsOrigen.filter(id => !idsDestino.includes(id));
+
+    if (idsNuevos.length === 0) {
+      return { merged: true, nuevos: 0, preservados: idsDestino.length };
+    }
+
+    // Extraer bloques de instintos nuevos del origen
+    const bloquesNuevos = idsNuevos
+      .map(id => _extraerBloqueInstinto(contenidoOrigen, id))
+      .filter(Boolean);
+
+    // Agregar al final del destino
+    let resultado = contenidoDestino.trimEnd() + '\n\n';
+    resultado += `# Instintos agregados por actualización SWL (${new Date().toISOString().split('T')[0]})\n`;
+    resultado += bloquesNuevos.join('\n');
+
+    fs.writeFileSync(destinoPath, resultado, 'utf8');
+
+    return { merged: true, nuevos: idsNuevos.length, preservados: idsDestino.length };
+  } catch (err) {
+    return { merged: false, nuevos: 0, preservados: 0, error: err.message };
+  }
+}
+
+/**
+ * Detecta si un skill fue generado por auto-evolución o creado por el usuario.
+ *
+ * Revisa el frontmatter del SKILL.md buscando marcadores:
+ *   - `origin: auto-evolucion` → generado por el sistema
+ *   - `origin: usuario` → creado por el usuario
+ *   - Sin campo origin → asume sistema (core)
+ *
+ * @param {string} skillDir - Directorio del skill.
+ * @returns {{ esUsuario: boolean, origin: string }}
+ */
+function detectarOrigenSkill(skillDir) {
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) {
+    return { esUsuario: false, origin: 'desconocido' };
+  }
+
+  try {
+    const contenido = fs.readFileSync(skillPath, 'utf8');
+
+    // Buscar campo origin en frontmatter
+    const matchOrigin = contenido.match(/origin:\s*["']?(\S+)["']?/);
+    if (matchOrigin) {
+      const origin = matchOrigin[1].toLowerCase();
+      return {
+        esUsuario: ['usuario', 'user', 'auto-evolucion', 'autoresearch'].includes(origin),
+        origin,
+      };
+    }
+
+    // Sin origin: verificar si el skill existe en el paquete core
+    // Si no está en el paquete core, probablemente es del usuario
+    return { esUsuario: false, origin: 'core' };
+  } catch (_) {
+    return { esUsuario: false, origin: 'desconocido' };
+  }
+}
+
+/**
+ * Merge de skills: preserva skills del usuario/auto-evolución, actualiza core.
+ *
+ * @param {string} origenDir  - Directorio de skills del paquete.
+ * @param {string} destinoDir - Directorio de skills del proyecto.
+ * @param {object} [opts={}]
+ * @param {boolean} [opts.force=false]
+ * @returns {{ actualizados: number, preservados: number, nuevos: number }}
+ */
+function mergeSkills(origenDir, destinoDir, opts = {}) {
+  if (!fs.existsSync(origenDir) || !fs.existsSync(destinoDir)) {
+    return { actualizados: 0, preservados: 0, nuevos: 0 };
+  }
+
+  let actualizados = 0;
+  let preservados  = 0;
+  let nuevos       = 0;
+
+  const skillsOrigen = fs.readdirSync(origenDir).filter(d => {
+    return fs.statSync(path.join(origenDir, d)).isDirectory();
+  });
+
+  for (const skill of skillsOrigen) {
+    const destinoSkill = path.join(destinoDir, skill);
+
+    if (!fs.existsSync(destinoSkill)) {
+      // Skill nuevo — copiar
+      _copiarDirectorioRecursivo(path.join(origenDir, skill), destinoSkill);
+      nuevos++;
+      continue;
+    }
+
+    // Skill existe — verificar si es del usuario
+    const { esUsuario } = detectarOrigenSkill(destinoSkill);
+    if (esUsuario) {
+      preservados++;
+      continue; // NUNCA sobreescribir skills del usuario
+    }
+
+    // Skill core — actualizar si hay force o si el contenido cambió
+    if (opts.force || tieneModificacionesUsuario(
+      path.join(destinoSkill, 'SKILL.md'),
+      path.join(origenDir, skill, 'SKILL.md'))
+    ) {
+      _copiarDirectorioRecursivo(path.join(origenDir, skill), destinoSkill);
+      actualizados++;
+    }
+  }
+
+  return { actualizados, preservados, nuevos };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+function _extraerIdsInstintos(contenido) {
+  const ids = [];
+  const regex = /- id:\s*(\S+)/g;
+  let match;
+  while ((match = regex.exec(contenido)) !== null) {
+    ids.push(match[1]);
+  }
+  return ids;
+}
+
+function _extraerBloqueInstinto(contenido, id) {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(`- id:\\s*${escapedId}[\\s\\S]*?(?=\\n- id:|$)`, 'm');
+  const match = contenido.match(regex);
+  return match ? match[0].trim() : null;
+}
+
+function _copiarDirectorioRecursivo(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()) {
+      _copiarDirectorioRecursivo(src, dst);
+    } else {
+      fs.copyFileSync(src, dst);
+    }
+  }
+}
+
+function _contarArchivosRecursivo(dir) {
+  let count = 0;
+  try {
+    const entradas = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entrada of entradas) {
+      if (entrada.isDirectory()) {
+        count += _contarArchivosRecursivo(path.join(dir, entrada.name));
+      } else {
+        count++;
+      }
+    }
+  } catch (_) {}
+  return count;
+}
+
+function _restaurarRecursivo(backupDir, baseDir, onFile) {
+  const entradas = fs.readdirSync(backupDir, { withFileTypes: true });
+  for (const entrada of entradas) {
+    const src = path.join(backupDir, entrada.name);
+    const dst = path.join(baseDir, entrada.name);
+
+    if (entrada.isDirectory()) {
+      if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
+      _restaurarRecursivo(src, dst, onFile);
+    } else {
+      fs.copyFileSync(src, dst);
+      if (onFile) onFile();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  // Nivel 1: Protección
+  esProtegido,
+  tieneModificacionesUsuario,
+  ARCHIVOS_PROTEGIDOS,
+  DIRECTORIOS_PROTEGIDOS,
+  PATRONES_PROTEGIDOS,
+
+  // Nivel 2: Backup
+  crearBackup,
+  registrarBackup,
+  listarBackups,
+  restaurarBackup,
+  limpiarBackups,
+  dirBackup,
+
+  // Nivel 3: Merge
+  mergeInstintos,
+  detectarOrigenSkill,
+  mergeSkills,
+};