@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/mcp-server/cache.js

@@ -1,106 +1,106 @@
-'use strict';
-
-/**
- * Cache mtime-based para handlers del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
- *
- * El stub experimental leía disco en cada call (latencia medida ~10ms con
- * APRENDIZAJES.md de 1172 líneas). Para datasets más grandes (>10k líneas) o
- * múltiples clientes concurrentes, el caching reduce sustancialmente la carga.
- *
- * Patrón:
- *   - Key = path absoluto del archivo.
- *   - Value = { mtime, contenido, parsed }.
- *   - Invalidación: si fs.stat().mtime > value.mtime → recargar y reparsear.
- *   - TTL opcional vía `SWL_MCP_CACHE_TTL_MS` (default 60000 ms): aunque mtime no
- *     haya cambiado, recargar tras TTL para defensa contra clock skew o ediciones
- *     que no actualizan mtime (raras pero posibles en filesystems exóticos).
- *
- * Zero-deps. NO usar para escritura — sigue read-only.
- *
- * @module scripts/mcp-server/cache
- */
-
-const fs = require('fs');
-
-const DEFAULT_TTL_MS = 60 * 1000;
-
-/**
- * Crea una instancia de cache mtime-based.
- *
- * @param {object} [opciones]
- * @param {number} [opciones.ttlMs] - TTL en milisegundos. Default 60000.
- * @param {object} [opciones.env] - Para leer SWL_MCP_CACHE_TTL_MS en tests.
- * @returns {{ get: Function, invalidate: Function, stats: Function, _store: Map }}
- */
-function crearCache(opciones = {}) {
-  const env = opciones.env || process.env;
-  const ttlMs = opciones.ttlMs !== undefined
-    ? opciones.ttlMs
-    : (parseInt(env.SWL_MCP_CACHE_TTL_MS, 10) || DEFAULT_TTL_MS);
-
-  const store = new Map();
-  const stats = { hits: 0, misses: 0, invalidations: 0 };
-
-  /**
-   * Obtiene el valor cacheado para `path`. Si el archivo cambió (mtime) o el TTL
-   * expiró, vuelve a leer y parsear con `parser(contenido, path)`.
-   *
-   * @param {string} ruta - Path absoluto del archivo a cachear.
-   * @param {(contenido: string, ruta: string) => any} parser - Función que transforma
-   *   el contenido del archivo en el objeto a cachear. DEBE ser pura.
-   * @returns {{ data: any, hit: boolean } | null} null si el archivo no existe.
-   */
-  function get(ruta, parser) {
-    let stat;
-    try {
-      stat = fs.statSync(ruta);
-    } catch (err) {
-      if (err.code === 'ENOENT') return null;
-      throw err;
-    }
-
-    const mtimeMs = stat.mtimeMs;
-    const ahora = Date.now();
-    const cached = store.get(ruta);
-
-    if (cached && cached.mtimeMs === mtimeMs && (ahora - cached.cargadoEn) < ttlMs) {
-      stats.hits++;
-      return { data: cached.data, hit: true };
-    }
-
-    if (cached) stats.invalidations++;
-    else stats.misses++;
-
-    const contenido = fs.readFileSync(ruta, 'utf-8');
-    const data = parser(contenido, ruta);
-    store.set(ruta, { mtimeMs, cargadoEn: ahora, data });
-    return { data, hit: false };
-  }
-
-  /**
-   * Invalida una entrada o todo el cache.
-   * @param {string} [ruta] - Si se omite, vacía todo.
-   */
-  function invalidate(ruta) {
-    if (ruta === undefined) {
-      const n = store.size;
-      store.clear();
-      stats.invalidations += n;
-      return n;
-    }
-    if (store.delete(ruta)) stats.invalidations++;
-    return 0;
-  }
-
-  return {
-    get,
-    invalidate,
-    stats: () => ({ ...stats, size: store.size, ttlMs }),
-    _store: store, // exposed para tests
-  };
-}
-
-module.exports = {
-  crearCache,
-  DEFAULT_TTL_MS,
-};
+'use strict';
+
+/**
+ * Cache mtime-based para handlers del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * El stub experimental leía disco en cada call (latencia medida ~10ms con
+ * APRENDIZAJES.md de 1172 líneas). Para datasets más grandes (>10k líneas) o
+ * múltiples clientes concurrentes, el caching reduce sustancialmente la carga.
+ *
+ * Patrón:
+ *   - Key = path absoluto del archivo.
+ *   - Value = { mtime, contenido, parsed }.
+ *   - Invalidación: si fs.stat().mtime > value.mtime → recargar y reparsear.
+ *   - TTL opcional vía `SWL_MCP_CACHE_TTL_MS` (default 60000 ms): aunque mtime no
+ *     haya cambiado, recargar tras TTL para defensa contra clock skew o ediciones
+ *     que no actualizan mtime (raras pero posibles en filesystems exóticos).
+ *
+ * Zero-deps. NO usar para escritura — sigue read-only.
+ *
+ * @module scripts/mcp-server/cache
+ */
+
+const fs = require('fs');
+
+const DEFAULT_TTL_MS = 60 * 1000;
+
+/**
+ * Crea una instancia de cache mtime-based.
+ *
+ * @param {object} [opciones]
+ * @param {number} [opciones.ttlMs] - TTL en milisegundos. Default 60000.
+ * @param {object} [opciones.env] - Para leer SWL_MCP_CACHE_TTL_MS en tests.
+ * @returns {{ get: Function, invalidate: Function, stats: Function, _store: Map }}
+ */
+function crearCache(opciones = {}) {
+  const env = opciones.env || process.env;
+  const ttlMs = opciones.ttlMs !== undefined
+    ? opciones.ttlMs
+    : (parseInt(env.SWL_MCP_CACHE_TTL_MS, 10) || DEFAULT_TTL_MS);
+
+  const store = new Map();
+  const stats = { hits: 0, misses: 0, invalidations: 0 };
+
+  /**
+   * Obtiene el valor cacheado para `path`. Si el archivo cambió (mtime) o el TTL
+   * expiró, vuelve a leer y parsear con `parser(contenido, path)`.
+   *
+   * @param {string} ruta - Path absoluto del archivo a cachear.
+   * @param {(contenido: string, ruta: string) => any} parser - Función que transforma
+   *   el contenido del archivo en el objeto a cachear. DEBE ser pura.
+   * @returns {{ data: any, hit: boolean } | null} null si el archivo no existe.
+   */
+  function get(ruta, parser) {
+    let stat;
+    try {
+      stat = fs.statSync(ruta);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+
+    const mtimeMs = stat.mtimeMs;
+    const ahora = Date.now();
+    const cached = store.get(ruta);
+
+    if (cached && cached.mtimeMs === mtimeMs && (ahora - cached.cargadoEn) < ttlMs) {
+      stats.hits++;
+      return { data: cached.data, hit: true };
+    }
+
+    if (cached) stats.invalidations++;
+    else stats.misses++;
+
+    const contenido = fs.readFileSync(ruta, 'utf-8');
+    const data = parser(contenido, ruta);
+    store.set(ruta, { mtimeMs, cargadoEn: ahora, data });
+    return { data, hit: false };
+  }
+
+  /**
+   * Invalida una entrada o todo el cache.
+   * @param {string} [ruta] - Si se omite, vacía todo.
+   */
+  function invalidate(ruta) {
+    if (ruta === undefined) {
+      const n = store.size;
+      store.clear();
+      stats.invalidations += n;
+      return n;
+    }
+    if (store.delete(ruta)) stats.invalidations++;
+    return 0;
+  }
+
+  return {
+    get,
+    invalidate,
+    stats: () => ({ ...stats, size: store.size, ttlMs }),
+    _store: store, // exposed para tests
+  };
+}
+
+module.exports = {
+  crearCache,
+  DEFAULT_TTL_MS,
+};

package/scripts/mcp-server/telemetry.js

@@ -1,78 +1,78 @@
-'use strict';
-
-/**
- * Telemetría opt-in del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
- *
- * Cuando `SWL_MCP_METRICS=1` está activo, cada `tools/call` se registra en
- * `.planning/evolucion/mcp-metrics.jsonl` con:
- *   { ts, tool, durationMs, ok, error?, baseDir }
- *
- * Defaults:
- *   - SWL_MCP_METRICS no set → no se persiste nada (zero-cost).
- *   - Se usa append-only JSONL (alta frecuencia → atomicWriteJSON sería ineficiente).
- *   - Si el filesystem no permite escritura (p.ej. baseDir read-only), el error
- *     se traga silenciosamente — la telemetría NUNCA debe romper el server.
- *
- * Zero-deps.
- *
- * @module scripts/mcp-server/telemetry
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Construye un grabador de telemetría desde el entorno actual.
- *
- * @param {object} [opciones]
- * @param {string} opciones.baseDir - Directorio raíz del proyecto SWL (donde está .planning/).
- * @param {object} [opciones.env] - Sustituible para tests.
- * @returns {{ habilitada: boolean, registrar: Function, ruta: string|null }}
- */
-function construirTelemetria(opciones = {}) {
-  const env = opciones.env || process.env;
-  const habilitada = env.SWL_MCP_METRICS === '1' || env.SWL_MCP_METRICS === 'true';
-  const baseDir = opciones.baseDir;
-
-  if (!habilitada || !baseDir) {
-    return {
-      habilitada: false,
-      registrar: () => {}, // noop
-      ruta: null,
-    };
-  }
-
-  const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
-  const ruta = path.join(dirEvolucion, 'mcp-metrics.jsonl');
-
-  // Asegurar que el directorio existe — si falla, deshabilitamos silenciosamente.
-  let escribible = true;
-  try {
-    fs.mkdirSync(dirEvolucion, { recursive: true });
-  } catch (err) {
-    escribible = false;
-  }
-
-  return {
-    habilitada: escribible,
-    registrar: (evento) => {
-      if (!escribible) return;
-      try {
-        const linea = JSON.stringify({
-          ts: new Date().toISOString(),
-          ...evento,
-        }) + '\n';
-        fs.appendFileSync(ruta, linea, { encoding: 'utf-8' });
-      } catch {
-        // Telemetría nunca debe romper el server — error silencioso.
-        // Tras 5 errores consecutivos podríamos deshabilitar, pero no
-        // implementamos eso hasta que aparezca como problema real.
-      }
-    },
-    ruta,
-  };
-}
-
-module.exports = {
-  construirTelemetria,
-};
+'use strict';
+
+/**
+ * Telemetría opt-in del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * Cuando `SWL_MCP_METRICS=1` está activo, cada `tools/call` se registra en
+ * `.planning/evolucion/mcp-metrics.jsonl` con:
+ *   { ts, tool, durationMs, ok, error?, baseDir }
+ *
+ * Defaults:
+ *   - SWL_MCP_METRICS no set → no se persiste nada (zero-cost).
+ *   - Se usa append-only JSONL (alta frecuencia → atomicWriteJSON sería ineficiente).
+ *   - Si el filesystem no permite escritura (p.ej. baseDir read-only), el error
+ *     se traga silenciosamente — la telemetría NUNCA debe romper el server.
+ *
+ * Zero-deps.
+ *
+ * @module scripts/mcp-server/telemetry
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Construye un grabador de telemetría desde el entorno actual.
+ *
+ * @param {object} [opciones]
+ * @param {string} opciones.baseDir - Directorio raíz del proyecto SWL (donde está .planning/).
+ * @param {object} [opciones.env] - Sustituible para tests.
+ * @returns {{ habilitada: boolean, registrar: Function, ruta: string|null }}
+ */
+function construirTelemetria(opciones = {}) {
+  const env = opciones.env || process.env;
+  const habilitada = env.SWL_MCP_METRICS === '1' || env.SWL_MCP_METRICS === 'true';
+  const baseDir = opciones.baseDir;
+
+  if (!habilitada || !baseDir) {
+    return {
+      habilitada: false,
+      registrar: () => {}, // noop
+      ruta: null,
+    };
+  }
+
+  const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
+  const ruta = path.join(dirEvolucion, 'mcp-metrics.jsonl');
+
+  // Asegurar que el directorio existe — si falla, deshabilitamos silenciosamente.
+  let escribible = true;
+  try {
+    fs.mkdirSync(dirEvolucion, { recursive: true });
+  } catch (err) {
+    escribible = false;
+  }
+
+  return {
+    habilitada: escribible,
+    registrar: (evento) => {
+      if (!escribible) return;
+      try {
+        const linea = JSON.stringify({
+          ts: new Date().toISOString(),
+          ...evento,
+        }) + '\n';
+        fs.appendFileSync(ruta, linea, { encoding: 'utf-8' });
+      } catch {
+        // Telemetría nunca debe romper el server — error silencioso.
+        // Tras 5 errores consecutivos podríamos deshabilitar, pero no
+        // implementamos eso hasta que aparezca como problema real.
+      }
+    },
+    ruta,
+  };
+}
+
+module.exports = {
+  construirTelemetria,
+};