@saulwade/swl-ses 1.0.0

package/hooks/lib/evolution-tracker.js

@@ -0,0 +1,442 @@
+'use strict';
+
+/**
+ * Evolution Tracker — Rastreo de evoluciones en componentes SWL.
+ *
+ * Cuando un agente, skill, comando o regla es modificado por auto-evolución
+ * (/swl:evolucionar, /swl:autoresearch, /swl:aprender Tipo D), este módulo:
+ *
+ *   1. Marca el archivo con metadata de evolución en su frontmatter
+ *   2. Detecta archivos evolucionados antes de sobreescribirlos en actualización
+ *   3. Decide la estrategia: preservar, merge o sobreescribir
+ *
+ * Aplica a componentes con frontmatter YAML (agentes, skills, comandos).
+ * Las reglas (.md sin frontmatter) se rastrean vía un archivo sidecar .evolved.json.
+ *
+ * @module hooks/lib/evolution-tracker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Campos de evolución que se inyectan en el frontmatter. */
+const EVOLUTION_FIELDS = {
+  evolved:       'evolved',        // boolean: true
+  evolvedFrom:   'evolved-from',   // string: versión base mejorada
+  evolvedAt:     'evolved-at',     // string: fecha ISO
+  evolvedBy:     'evolved-by',     // string: comando que lo evolucionó
+  evolvedRounds: 'evolved-rounds', // number: rondas de autoresearch (si aplica)
+  evolvedScore:  'evolved-score',  // string: "baseline% → final%"
+  evolvedNote:   'evolved-note',   // string: descripción breve del cambio
+};
+
+/** Nombre del archivo sidecar para componentes sin frontmatter (reglas). */
+const SIDECAR_FILENAME = '.evolved.json';
+
+/** Comandos que generan evoluciones. */
+const EVOLUTION_SOURCES = [
+  'evolucionar',
+  'autoresearch',
+  'aprender',
+  'crear-skill',
+  'instintos promote',
+];
+
+// ---------------------------------------------------------------------------
+// Lectura de metadata de evolución
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee la metadata de evolución de un archivo con frontmatter YAML.
+ *
+ * @param {string} filePath - Ruta al archivo (.md con frontmatter).
+ * @returns {{ evolved: boolean, metadata: object }}
+ */
+function readEvolutionMeta(filePath) {
+  const empty = { evolved: false, metadata: {} };
+  if (!fs.existsSync(filePath)) return empty;
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Detectar frontmatter YAML (entre --- y ---)
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch) {
+      // Sin frontmatter — verificar sidecar
+      return _readSidecar(filePath);
+    }
+
+    const frontmatter = fmMatch[1];
+    const evolvedMatch = frontmatter.match(/^evolved:\s*(true|yes)/mi);
+    if (!evolvedMatch) return empty;
+
+    // Extraer todos los campos evolved-*
+    const metadata = {};
+    for (const [key, yamlKey] of Object.entries(EVOLUTION_FIELDS)) {
+      const re = new RegExp(`^${yamlKey}:\\s*["']?(.+?)["']?\\s*$`, 'mi');
+      const m = frontmatter.match(re);
+      if (m) metadata[key] = m[1].trim();
+    }
+
+    return { evolved: true, metadata };
+  } catch (_) {
+    return empty;
+  }
+}
+
+/**
+ * Lee metadata de evolución desde archivo sidecar (.evolved.json).
+ * Para componentes sin frontmatter (reglas).
+ *
+ * @param {string} filePath
+ * @returns {{ evolved: boolean, metadata: object }}
+ */
+function _readSidecar(filePath) {
+  const sidecarPath = path.join(path.dirname(filePath), SIDECAR_FILENAME);
+  const basename = path.basename(filePath);
+
+  try {
+    if (!fs.existsSync(sidecarPath)) return { evolved: false, metadata: {} };
+    const data = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+    const entry = data[basename];
+    if (entry && entry.evolved) {
+      return { evolved: true, metadata: entry };
+    }
+  } catch (_) {}
+
+  return { evolved: false, metadata: {} };
+}
+
+// ---------------------------------------------------------------------------
+// Escritura de metadata de evolución
+// ---------------------------------------------------------------------------
+
+/**
+ * Marca un archivo como evolucionado inyectando campos en su frontmatter.
+ *
+ * @param {string} filePath   - Ruta del archivo a marcar.
+ * @param {object} meta
+ * @param {string} meta.from  - Versión base (ej: "5.1.0").
+ * @param {string} meta.by    - Comando fuente (ej: "autoresearch").
+ * @param {number} [meta.rounds]  - Rondas de autoresearch.
+ * @param {string} [meta.score]   - Score "baseline% → final%".
+ * @param {string} [meta.note]    - Descripción del cambio.
+ * @returns {{ marked: boolean, error?: string }}
+ */
+function markAsEvolved(filePath, meta) {
+  if (!fs.existsSync(filePath)) {
+    return { marked: false, error: 'Archivo no existe' };
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fmMatch = content.match(/^(---\n)([\s\S]*?)(\n---)/);
+
+    if (!fmMatch) {
+      // Sin frontmatter — usar sidecar
+      return _writeSidecar(filePath, meta);
+    }
+
+    const prefix = fmMatch[1];
+    let frontmatter = fmMatch[2];
+    const suffix = fmMatch[3];
+    const rest = content.slice(fmMatch[0].length);
+
+    // Remover campos evolved previos
+    frontmatter = frontmatter
+      .split('\n')
+      .filter(line => !line.match(/^evolved[-\w]*:/))
+      .join('\n');
+
+    // Agregar campos nuevos
+    const date = new Date().toISOString().split('T')[0];
+    const newFields = [
+      `evolved: true`,
+      `evolved-from: "${meta.from}"`,
+      `evolved-at: "${date}"`,
+      `evolved-by: "${meta.by}"`,
+    ];
+    if (meta.rounds) newFields.push(`evolved-rounds: ${meta.rounds}`);
+    if (meta.score) newFields.push(`evolved-score: "${meta.score}"`);
+    if (meta.note) newFields.push(`evolved-note: "${meta.note}"`);
+
+    frontmatter = frontmatter.trimEnd() + '\n' + newFields.join('\n');
+
+    const newContent = prefix + frontmatter + suffix + rest;
+    fs.writeFileSync(filePath, newContent, 'utf8');
+
+    return { marked: true };
+  } catch (err) {
+    return { marked: false, error: err.message };
+  }
+}
+
+/**
+ * Escribe metadata de evolución en archivo sidecar para componentes sin frontmatter.
+ * @private
+ */
+function _writeSidecar(filePath, meta) {
+  const sidecarPath = path.join(path.dirname(filePath), SIDECAR_FILENAME);
+  const basename = path.basename(filePath);
+
+  let data = {};
+  try {
+    if (fs.existsSync(sidecarPath)) {
+      data = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+    }
+  } catch (_) {}
+
+  data[basename] = {
+    evolved: true,
+    evolvedFrom: meta.from,
+    evolvedAt: new Date().toISOString().split('T')[0],
+    evolvedBy: meta.by,
+    ...(meta.rounds && { evolvedRounds: meta.rounds }),
+    ...(meta.score && { evolvedScore: meta.score }),
+    ...(meta.note && { evolvedNote: meta.note }),
+  };
+
+  fs.writeFileSync(sidecarPath, JSON.stringify(data, null, 2), 'utf8');
+  return { marked: true };
+}
+
+// ---------------------------------------------------------------------------
+// Decisión de actualización
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide qué estrategia usar al actualizar un archivo evolucionado.
+ *
+ * @param {string} destino          - Ruta del archivo instalado (puede tener evolved).
+ * @param {string} origen           - Ruta del archivo nuevo del paquete.
+ * @param {string} versionNueva     - Versión del paquete nuevo (ej: "5.2.0").
+ * @returns {{ strategy: 'preserve'|'overwrite'|'conflict', reason: string, metadata?: object }}
+ */
+function decideUpdateStrategy(destino, origen, versionNueva) {
+  const evo = readEvolutionMeta(destino);
+
+  if (!evo.evolved) {
+    return { strategy: 'overwrite', reason: 'No evolucionado — actualización normal' };
+  }
+
+  const evolvedFrom = evo.metadata.evolvedFrom || evo.metadata.evolved_from || '';
+  const evolvedBy = evo.metadata.evolvedBy || evo.metadata.evolved_by || 'auto-evolución';
+
+  // Caso 1: evolved: true y no hay archivo origen disponible → preservar siempre
+  // (no podemos comparar, pero el usuario evolucionó deliberadamente)
+  if (!origen || !fs.existsSync(origen)) {
+    return {
+      strategy: 'preserve',
+      reason: `Evolucionado desde ${evolvedFrom} por ${evolvedBy} — archivo origen no disponible para comparar`,
+      metadata: evo.metadata,
+    };
+  }
+
+  // Caso 2: Si el contenido del origen (sin evolved fields) es igual al destino (sin evolved fields)
+  // → preservar (la versión nueva no cambió el contenido base de este archivo)
+  try {
+    const origenContent  = fs.readFileSync(origen, 'utf8');
+    const destinoContent = fs.readFileSync(destino, 'utf8');
+    const origenSinEvo   = _stripEvolutionFields(origenContent);
+    const destinoSinEvo  = _stripEvolutionFields(destinoContent);
+
+    if (origenSinEvo.trim() === destinoSinEvo.trim()) {
+      return {
+        strategy: 'preserve',
+        reason: 'Contenido base idéntico — solo tiene campos evolved adicionales',
+        metadata: evo.metadata,
+      };
+    }
+  } catch (_) {}
+
+  // Caso 3: La versión base de la evolución es la misma o anterior a la nueva
+  // Y el contenido del destino tiene mutaciones reales → preservar
+  // (las mutaciones del usuario son más valiosas que la actualización base)
+  if (evolvedFrom && evolvedFrom <= versionNueva) {
+    return {
+      strategy: 'preserve',
+      reason: `Evolucionado desde ${evolvedFrom} por ${evolvedBy} — mutaciones locales preservadas sobre v${versionNueva}`,
+      metadata: evo.metadata,
+    };
+  }
+
+  // Caso 4: Versión base diferente + contenido diferente + versión futura (edge case)
+  // → conflicto (requiere revisión manual)
+  return {
+    strategy: 'conflict',
+    reason: `Evolucionado desde ${evolvedFrom} pero la versión nueva (${versionNueva}) tiene cambios significativos. Requiere revisión.`,
+    metadata: evo.metadata,
+  };
+}
+
+/**
+ * Remueve campos de evolución del frontmatter para comparación limpia.
+ * @private
+ */
+function _stripEvolutionFields(content) {
+  return content
+    .split('\n')
+    .filter(line => !line.match(/^evolved[-\w]*:/))
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Merge de evoluciones
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge inteligente de un archivo evolucionado con una versión nueva.
+ *
+ * Estrategia: toma el archivo nuevo como base y re-aplica los campos de
+ * evolución (frontmatter evolved-*). Las mutaciones de contenido se preservan
+ * generando un archivo .evolved-diff.md que Claude puede re-aplicar.
+ *
+ * @param {string} destino      - Ruta del archivo evolucionado (local).
+ * @param {string} origen       - Ruta del archivo nuevo del paquete.
+ * @param {string} versionNueva - Versión del paquete nuevo.
+ * @returns {{ merged: boolean, diffPath?: string, error?: string }}
+ */
+function mergeEvolved(destino, origen, versionNueva) {
+  try {
+    if (!fs.existsSync(destino) || !fs.existsSync(origen)) {
+      return { merged: false, error: 'Archivo destino u origen no existe' };
+    }
+
+    const evo = readEvolutionMeta(destino);
+    if (!evo.evolved) {
+      return { merged: false, error: 'Archivo destino no está evolucionado' };
+    }
+
+    const destinoContent = fs.readFileSync(destino, 'utf8');
+    const origenContent  = fs.readFileSync(origen, 'utf8');
+
+    // Extraer las líneas que son diferentes entre destino (sin evolved fields) y origen
+    const destinoSinEvo = _stripEvolutionFields(destinoContent);
+    const origenLines    = origenContent.split('\n');
+    const destinoLines   = destinoSinEvo.split('\n');
+
+    const diffs = [];
+    const maxLen = Math.max(origenLines.length, destinoLines.length);
+    for (let i = 0; i < maxLen; i++) {
+      const orig = origenLines[i] || '';
+      const dest = destinoLines[i] || '';
+      if (orig.trim() !== dest.trim()) {
+        diffs.push({
+          line: i + 1,
+          origen: orig,
+          destino: dest,
+        });
+      }
+    }
+
+    if (diffs.length === 0) {
+      // Sin diferencias reales — solo re-aplicar campos evolved al nuevo
+      const marked = markAsEvolved(destino, {
+        from: versionNueva,
+        by: evo.metadata.evolvedBy || 'auto-evolución',
+        rounds: evo.metadata.evolvedRounds ? parseInt(evo.metadata.evolvedRounds, 10) : undefined,
+        score: evo.metadata.evolvedScore,
+        note: `Re-aplicado desde v${evo.metadata.evolvedFrom || '?'} tras actualización a v${versionNueva}`,
+      });
+      return { merged: marked.marked };
+    }
+
+    // Guardar diff para revisión/re-aplicación por Claude
+    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
+    const diffContent = [
+      `# Diff de evolución — ${path.basename(destino)}`,
+      ``,
+      `**Archivo evolucionado por**: ${evo.metadata.evolvedBy || 'auto-evolución'}`,
+      `**Versión base original**: ${evo.metadata.evolvedFrom || '?'}`,
+      `**Versión nueva**: ${versionNueva}`,
+      `**Fecha**: ${new Date().toISOString().split('T')[0]}`,
+      ``,
+      `## Mutaciones locales a re-aplicar`,
+      ``,
+      `Estas son las líneas que difieren entre la versión evolucionada y la nueva.`,
+      `Re-aplicar con \`/swl:autoresearch\` o manualmente.`,
+      ``,
+      ...diffs.map(d => [
+        `### Línea ${d.line}`,
+        `- **Nueva (base)**: \`${d.origen}\``,
+        `- **Evolucionada**: \`${d.destino}\``,
+        ``,
+      ]).flat(),
+    ].join('\n');
+
+    fs.writeFileSync(diffPath, diffContent, 'utf8');
+
+    return { merged: true, diffPath, diffsCount: diffs.length };
+  } catch (err) {
+    return { merged: false, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Escaneo de archivos evolucionados
+// ---------------------------------------------------------------------------
+
+/**
+ * Escanea un directorio buscando archivos evolucionados.
+ *
+ * @param {string} dir - Directorio a escanear (agentes/, habilidades/, comandos/, reglas/).
+ * @param {object} [opts={}]
+ * @param {boolean} [opts.recursive=true]
+ * @returns {object[]} Lista de { path, metadata }.
+ */
+function scanEvolved(dir, opts = {}) {
+  const recursive = opts.recursive !== false;
+  const results = [];
+
+  if (!fs.existsSync(dir)) return results;
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory() && recursive) {
+        results.push(...scanEvolved(fullPath, opts));
+      } else if (entry.name.endsWith('.md')) {
+        const evo = readEvolutionMeta(fullPath);
+        if (evo.evolved) {
+          results.push({ path: fullPath, ...evo.metadata });
+        }
+      }
+    }
+  } catch (_) {}
+
+  // También verificar sidecar en el directorio actual
+  const sidecarPath = path.join(dir, SIDECAR_FILENAME);
+  if (fs.existsSync(sidecarPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+      for (const [filename, meta] of Object.entries(data)) {
+        if (meta.evolved) {
+          results.push({ path: path.join(dir, filename), ...meta });
+        }
+      }
+    } catch (_) {}
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  readEvolutionMeta,
+  markAsEvolved,
+  decideUpdateStrategy,
+  mergeEvolved,
+  scanEvolved,
+  EVOLUTION_FIELDS,
+  EVOLUTION_SOURCES,
+  SIDECAR_FILENAME,
+};