@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/limpiar-basura-global.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * limpiar-basura-global.js — Purga de directorios basura de una instalación
+ * global de swl-ses.
+ *
+ * Caso de origen (2026-07-15): un `install --global` crea `~/_userland`. Una
+ * versión previa de `swl-ses doctor` contaba ese `_userland` como marcador de
+ * "proyecto swl" (`esProyectoSwl`), así que correr `doctor` desde el HOME
+ * sembraba `~/.planning/` con marcadores scaffold (`# PROJECT\n\n(Generado por
+ * swl-ses doctor)`). Como el HOME no es un proyecto, ese `.planning/` es basura;
+ * peor, hooks que resolvían la raíz vía raiz-proyecto la capturaban y volcaban
+ * telemetría ahí. El fix de raiz-proyecto (frontera del HOME) corta la captura;
+ * este módulo purga el scaffold ya sembrado en el próximo install global.
+ *
+ * También purga un `~/_userland/` VACÍO: el contenedor de plugins userland que
+ * un install global dejaba en el HOME (subdirs agentes/habilidades/plugins/
+ * reglas con solo `.gitkeep`). El instalador actual no lo crea ahí, así que un
+ * `_userland` vacío en el HOME es scaffold huérfano.
+ *
+ * Conservador por diseño (invariantes de seguridad): SOLO elimina un `.planning/`
+ * cuyos marcadores llevan la huella del scaffold de doctor, y un `_userland/`
+ * SIN archivos reales. Un proyecto real o un `_userland` con plugins del usuario
+ * nunca se tocan.
+ *
+ * Zero-deps.
+ *
+ * @module scripts/lib/limpiar-basura-global
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Huella inequívoca del scaffold vacío que `swl-ses doctor` escribía en cada
+// marcador (`# PROJECT\n\n(Generado por swl-ses doctor)\n`).
+const HUELLA_SCAFFOLD_DOCTOR = '(Generado por swl-ses doctor)';
+const MARCADORES = ['PROYECTO.md', 'REQUISITOS.md', 'HOJA-RUTA.md', 'ESTADO.md'];
+
+// Archivos que NO cuentan como contenido real (placeholders de scaffold).
+const ARCHIVOS_PLACEHOLDER = new Set(['.gitkeep', '.DS_Store', 'Thumbs.db']);
+
+/**
+ * ¿El `.planning/` de `dir` es el scaffold espurio de doctor (no un proyecto
+ * real)? Señal: existe al menos un marcador y TODOS los marcadores presentes
+ * llevan la huella del scaffold. Un proyecto real tiene marcadores con
+ * contenido propio → devuelve false y no se toca.
+ *
+ * @param {string} dir - Directorio que contiene el `.planning/` a evaluar.
+ * @returns {boolean}
+ */
+function esPlanningEspurio(dir) {
+  const planning = path.join(dir, '.planning');
+  let esDir = false;
+  try {
+    esDir = fs.statSync(planning).isDirectory();
+  } catch (_) {
+    return false; // no existe
+  }
+  if (!esDir) return false;
+
+  const presentes = MARCADORES.filter(m => fs.existsSync(path.join(planning, m)));
+  if (presentes.length === 0) return false;
+
+  return presentes.every(m => {
+    try {
+      return fs.readFileSync(path.join(planning, m), 'utf8').includes(HUELLA_SCAFFOLD_DOCTOR);
+    } catch (_) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Cuenta archivos reales (no placeholders de scaffold) bajo `dir`, recursivo.
+ * @param {string} dir
+ * @returns {number}
+ */
+function contarArchivosReales(dir) {
+  let entradas;
+  try {
+    entradas = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return 0;
+  }
+  let n = 0;
+  for (const e of entradas) {
+    if (e.isDirectory()) {
+      n += contarArchivosReales(path.join(dir, e.name));
+    } else if (!ARCHIVOS_PLACEHOLDER.has(e.name)) {
+      n += 1;
+    }
+  }
+  return n;
+}
+
+/**
+ * ¿El `_userland/` de `dir` es un scaffold vacío (sin plugins reales del
+ * usuario)? Señal: existe y no contiene ningún archivo real (solo placeholders
+ * como `.gitkeep`). Un `_userland` con plugins del usuario → false, no se toca.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esUserlandVacio(dir) {
+  const userland = path.join(dir, '_userland');
+  let esDir = false;
+  try {
+    esDir = fs.statSync(userland).isDirectory();
+  } catch (_) {
+    return false; // no existe
+  }
+  if (!esDir) return false;
+  return contarArchivosReales(userland) === 0;
+}
+
+/**
+ * ¿El `.planning/` de `dir` contiene un PROYECTO real? Señal: al menos un
+ * marcador con contenido propio (ni vacío ni la huella del scaffold de doctor).
+ * Es el invariante de seguridad: distingue un proyecto legítimo (que se
+ * preserva) de basura (scaffold, backups del install, telemetría mal dirigida).
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function planningTieneProyectoReal(dir) {
+  const planning = path.join(dir, '.planning');
+  return MARCADORES.some((m) => {
+    try {
+      const contenido = fs.readFileSync(path.join(planning, m), 'utf8');
+      return contenido.trim().length > 0 && !contenido.includes(HUELLA_SCAFFOLD_DOCTOR);
+    } catch (_) {
+      return false;
+    }
+  });
+}
+
+/**
+ * ¿El `.planning/` en el HOME es removible? Existe pero NO es un proyecto real.
+ * Cubre: scaffold de doctor (huella), backups del install (`backups/` sin
+ * marcadores), telemetría mal dirigida de hooks, o dir vacío. El HOME nunca es
+ * un proyecto de trabajo — un `.planning` ahí sin proyecto real es basura.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esPlanningRemovibleEnHome(dir) {
+  const planning = path.join(dir, '.planning');
+  try {
+    if (!fs.statSync(planning).isDirectory()) return false;
+  } catch (_) {
+    return false; // no existe
+  }
+  return !planningTieneProyectoReal(dir);
+}
+
+/**
+ * Elimina los directorios basura de una instalación global en el HOME:
+ *   - `.planning/` sin proyecto real (scaffold de doctor, backups del install,
+ *     telemetría mal dirigida o vacío).
+ *   - `_userland/` vacío (scaffold sin plugins del usuario).
+ * Idempotente: si no hay basura, no hace nada. Conservador: cada objetivo tiene
+ * su invariante de seguridad y NUNCA borra contenido real (proyecto o plugins).
+ * Un fallo de borrado en un objetivo no aborta los demás.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home] - Raíz global a limpiar (default: os.homedir()).
+ * @param {boolean} [opts.dryRun=false] - No borra; solo reporta qué borraría.
+ * @returns {{eliminados: string[], dryRun: boolean}} Paths eliminados (o que se
+ *   eliminarían en dryRun).
+ */
+function limpiarBasuraGlobal(opts = {}) {
+  const home = opts.home || os.homedir();
+  const dryRun = !!opts.dryRun;
+  const eliminados = [];
+
+  const objetivos = [
+    { detectar: () => esPlanningRemovibleEnHome(home), ruta: path.join(home, '.planning') },
+    { detectar: () => esUserlandVacio(home), ruta: path.join(home, '_userland') },
+  ];
+
+  for (const obj of objetivos) {
+    if (!obj.detectar()) continue;
+    if (!dryRun) {
+      try {
+        fs.rmSync(obj.ruta, { recursive: true, force: true });
+      } catch (_) {
+        continue; // no se pudo borrar: no reportar como eliminado, seguir con el resto
+      }
+    }
+    eliminados.push(obj.ruta);
+  }
+
+  return { eliminados, dryRun };
+}
+
+module.exports = {
+  limpiarBasuraGlobal,
+  esPlanningEspurio,
+  esPlanningRemovibleEnHome,
+  planningTieneProyectoReal,
+  esUserlandVacio,
+  HUELLA_SCAFFOLD_DOCTOR,
+};

package/scripts/lib/longmemeval-runner.js

@@ -1,125 +1,125 @@
-'use strict';
-
-/**
- * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
- * `hooks/lib/memory-search` y devuelve métricas.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
- * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
- *
- * El dataset es un JSONL donde cada línea es:
- * {
- *   "question_id":  "q-001",
- *   "question":     "texto libre de la query",
- *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
- *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
- *   "status":       "real" | "placeholder"
- * }
- *
- * @module scripts/lib/longmemeval-runner
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const memorySearch     = require('../../hooks/lib/memory-search');
-const benchmarkMetrics = require('./benchmark-metrics');
-
-// ── parser de dataset ─────────────────────────────────────────────────────────
-
-/**
- * Parsea un archivo JSONL del dataset.
- * @param {string} ruta
- * @returns {object[]}
- */
-function leerDataset(ruta) {
-  if (!fs.existsSync(ruta)) {
-    throw new Error(`Dataset no encontrado: ${ruta}`);
-  }
-  const contenido = fs.readFileSync(ruta, 'utf8');
-  const entries = [];
-  let lineNum = 0;
-  for (const linea of contenido.split('\n')) {
-    lineNum++;
-    if (!linea.trim()) continue;
-    if (linea.trim().startsWith('//')) continue; // comentarios
-    try {
-      entries.push(JSON.parse(linea));
-    } catch (err) {
-      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
-    }
-  }
-  return entries;
-}
-
-// ── ejecución de query individual ─────────────────────────────────────────────
-
-/**
- * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
- *
- * @param {string} baseDir - Raíz del proyecto.
- * @param {object} entry - Una línea del dataset.
- * @param {object} [opts]
- * @param {number} [opts.limit=20] - Top-k a recuperar.
- * @returns {object} Métricas + ids retrieved + entry original.
- */
-function ejecutarEntry(baseDir, entry, opts = {}) {
-  const limit = opts.limit || 20;
-  const inicio = Date.now();
-  const resultados = memorySearch.search(baseDir, entry.question, { limit });
-  const latencyMs = Date.now() - inicio;
-
-  const retrievedIds = resultados.map(r => r.id);
-  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
-  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
-
-  return {
-    question_id: entry.question_id || 'unknown',
-    question: entry.question,
-    category: entry.category || null,
-    status: entry.status || 'unknown',
-    retrievedIds,
-    goldIds,
-    metricas,
-    latencyMs,
-  };
-}
-
-/**
- * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
- *
- * @param {string} baseDir
- * @param {string} datasetPath
- * @param {object} [opts]
- * @returns {{ entries: object[], promedio: object, dataset: object }}
- */
-function ejecutarDataset(baseDir, datasetPath, opts = {}) {
-  const entries = leerDataset(datasetPath);
-  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
-  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
-
-  // Estadísticas del dataset
-  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
-  const realCount = entries.filter(e => e.status === 'real').length;
-  const datasetMeta = {
-    total: entries.length,
-    real: realCount,
-    placeholder: placeholderCount,
-    significativo: realCount >= 30,
-  };
-
-  return {
-    entries: resultados,
-    promedio,
-    dataset: datasetMeta,
-  };
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  leerDataset,
-  ejecutarEntry,
-  ejecutarDataset,
-};
+'use strict';
+
+/**
+ * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
+ * `hooks/lib/memory-search` y devuelve métricas.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
+ * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
+ *
+ * El dataset es un JSONL donde cada línea es:
+ * {
+ *   "question_id":  "q-001",
+ *   "question":     "texto libre de la query",
+ *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
+ *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
+ *   "status":       "real" | "placeholder"
+ * }
+ *
+ * @module scripts/lib/longmemeval-runner
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch     = require('../../hooks/lib/memory-search');
+const benchmarkMetrics = require('./benchmark-metrics');
+
+// ── parser de dataset ─────────────────────────────────────────────────────────
+
+/**
+ * Parsea un archivo JSONL del dataset.
+ * @param {string} ruta
+ * @returns {object[]}
+ */
+function leerDataset(ruta) {
+  if (!fs.existsSync(ruta)) {
+    throw new Error(`Dataset no encontrado: ${ruta}`);
+  }
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const entries = [];
+  let lineNum = 0;
+  for (const linea of contenido.split('\n')) {
+    lineNum++;
+    if (!linea.trim()) continue;
+    if (linea.trim().startsWith('//')) continue; // comentarios
+    try {
+      entries.push(JSON.parse(linea));
+    } catch (err) {
+      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
+    }
+  }
+  return entries;
+}
+
+// ── ejecución de query individual ─────────────────────────────────────────────
+
+/**
+ * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
+ *
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {object} entry - Una línea del dataset.
+ * @param {object} [opts]
+ * @param {number} [opts.limit=20] - Top-k a recuperar.
+ * @returns {object} Métricas + ids retrieved + entry original.
+ */
+function ejecutarEntry(baseDir, entry, opts = {}) {
+  const limit = opts.limit || 20;
+  const inicio = Date.now();
+  const resultados = memorySearch.search(baseDir, entry.question, { limit });
+  const latencyMs = Date.now() - inicio;
+
+  const retrievedIds = resultados.map(r => r.id);
+  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
+  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
+
+  return {
+    question_id: entry.question_id || 'unknown',
+    question: entry.question,
+    category: entry.category || null,
+    status: entry.status || 'unknown',
+    retrievedIds,
+    goldIds,
+    metricas,
+    latencyMs,
+  };
+}
+
+/**
+ * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
+ *
+ * @param {string} baseDir
+ * @param {string} datasetPath
+ * @param {object} [opts]
+ * @returns {{ entries: object[], promedio: object, dataset: object }}
+ */
+function ejecutarDataset(baseDir, datasetPath, opts = {}) {
+  const entries = leerDataset(datasetPath);
+  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
+  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
+
+  // Estadísticas del dataset
+  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
+  const realCount = entries.filter(e => e.status === 'real').length;
+  const datasetMeta = {
+    total: entries.length,
+    real: realCount,
+    placeholder: placeholderCount,
+    significativo: realCount >= 30,
+  };
+
+  return {
+    entries: resultados,
+    promedio,
+    dataset: datasetMeta,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  leerDataset,
+  ejecutarEntry,
+  ejecutarDataset,
+};