@saulwade/swl-ses 2.3.0 → 2.3.1

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/migrar-csv-a-array.js

@@ -1,168 +1,168 @@
-#!/usr/bin/env node
-/**
- * Migración 3A — convierte campos CSV a array YAML inline en frontmatter de
- * agentes. Afecta `tools`, `skillsInvocables`, `skillsRestringidos`.
- *
- * Antes:  tools: Read, Write, Edit, Bash
- * Después: tools: [Read, Write, Edit, Bash]
- *
- * Razón: el schema declara `type: array` pero el uso real es CSV string. YAML
- * estándar NO convierte CSV a array — el parser produce una sola string. Esto
- * causó bugs históricos documentados en CLAUDE.md ("regla obligatoria CSV
- * estricto"). Migrar a array inline elimina la ambigüedad.
- *
- * Idempotente: skip si ya es array.
- *
- * Casos especiales detectados en agentes:
- *   - skillsInvocables: <ninguno>      → mantener literal
- *   - skillsRestringidos: ninguno      → convertir a [] (array vacío)
- *   - skillsRestringidos: \n  - x\n    → ya es array YAML multilinea, mantener
- *
- * Uso:
- *   node scripts/migrar-csv-a-array.js [--dry-run]
- *
- * Zero-dependencies. Compatible Windows (CRLF-safe), Node 18+.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
-const DRY_RUN = process.argv.includes('--dry-run');
-
-// Campos que migran de CSV a array
-const CAMPOS_CSV = ['tools', 'skillsInvocables', 'skillsRestringidos'];
-
-// Valores especiales que NO son listas y deben preservarse
-const VALORES_LITERAL = new Set(['ninguno', 'ninguna', '<ninguno>', '<ninguna>', 'none', 'null']);
-
-function parsearValorCSV(valorStr) {
-  // Detectar si ya es array inline `[a, b, c]`
-  if (/^\s*\[/.test(valorStr)) return null;
-
-  // Limpiar
-  const valor = valorStr.trim();
-  if (!valor) return [];
-
-  // Valor especial literal
-  if (VALORES_LITERAL.has(valor.toLowerCase())) return [];
-
-  // CSV split
-  return valor
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-
-function migrarFrontmatter(contenido) {
-  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
-  if (!match) return { contenido, cambios: 0 };
-
-  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
-  const fmCompleto = match[0];
-
-  let nuevoFm = fmCompleto;
-  let cambios = 0;
-
-  for (const campo of CAMPOS_CSV) {
-    // Patrón 2 PRIMERO: array YAML multilínea
-    //   skillsRestringidos:
-    //     - angular-moderno
-    //     - typescript-avanzado
-    // El campo está solo en su línea (sin valor) seguido de líneas con `  - X`
-    const re2 = new RegExp(`^(${campo}):[ \\t]*\\r?\\n((?:[ \\t]+-[ \\t]+[^\\r\\n]+\\r?\\n)+)`, 'm');
-    const m2 = nuevoFm.match(re2);
-    if (m2) {
-      const bloque = m2[2];
-      const items = bloque
-        .split(/\r?\n/)
-        .map((l) => l.trim())
-        .filter((l) => l.startsWith('- '))
-        .map((l) => l.slice(2).trim().replace(/^["']|["']$/g, ''));
-      if (items.length > 0) {
-        const arrayInline = `[${items.join(', ')}]`;
-        const reemplazo = `${campo}: ${arrayInline}${eol}`;
-        nuevoFm = nuevoFm.replace(re2, reemplazo);
-        cambios++;
-      }
-      continue; // procesado, no aplicar regex 1
-    }
-
-    // Patrón 1: campo en una sola línea con valor (CSV o array inline)
-    //   tools: Read, Write
-    //   skillsRestringidos: ninguno
-    //   tools: [Read, Write]   ← skip, ya es array
-    // CRÍTICO: usar [ \\t]* (NO \\s*) para no consumir newlines
-    const re1 = new RegExp(`^(${campo}):[ \\t]*([^\\r\\n]+)$`, 'm');
-    const m1 = nuevoFm.match(re1);
-    if (m1) {
-      const valorStr = m1[2];
-      const items = parsearValorCSV(valorStr);
-      if (items === null) continue; // ya es array, skip
-      const arrayInline = `[${items.join(', ')}]`;
-      const reemplazo = `${campo}: ${arrayInline}`;
-      if (m1[0] !== reemplazo) {
-        nuevoFm = nuevoFm.replace(re1, reemplazo);
-        cambios++;
-      }
-    }
-  }
-
-  if (cambios === 0) return { contenido, cambios: 0 };
-
-  return { contenido: contenido.replace(fmCompleto, nuevoFm), cambios };
-}
-
-function migrarAgente(archivo) {
-  const contenido = fs.readFileSync(archivo, 'utf-8');
-  const { contenido: nuevo, cambios } = migrarFrontmatter(contenido);
-
-  if (cambios === 0) {
-    return { archivo: path.basename(archivo), status: 'sin-cambios' };
-  }
-
-  if (DRY_RUN) {
-    return { archivo: path.basename(archivo), status: 'dry-run', cambios };
-  }
-
-  fs.writeFileSync(archivo, nuevo, 'utf-8');
-  return { archivo: path.basename(archivo), status: 'migrado', cambios };
-}
-
-function main() {
-  console.log(`Migrando CSV → array YAML${DRY_RUN ? ' (dry-run)' : ''}...\n`);
-
-  const archivos = fs
-    .readdirSync(AGENTES_DIR)
-    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
-    .map((f) => path.join(AGENTES_DIR, f));
-
-  const resultados = archivos.map(migrarAgente);
-
-  const stats = {
-    'sin-cambios': 0,
-    migrado: 0,
-    'dry-run': 0,
-    totalCambios: 0,
-  };
-
-  for (const r of resultados) {
-    stats[r.status] = (stats[r.status] || 0) + 1;
-    if (r.cambios) stats.totalCambios += r.cambios;
-  }
-
-  console.log(`Sin cambios: ${stats['sin-cambios']}`);
-  console.log(`Migrados: ${stats.migrado}`);
-  console.log(`Dry-run: ${stats['dry-run']}`);
-  console.log(`Total ediciones: ${stats.totalCambios}`);
-
-  process.exit(0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { parsearValorCSV, migrarFrontmatter };
+#!/usr/bin/env node
+/**
+ * Migración 3A — convierte campos CSV a array YAML inline en frontmatter de
+ * agentes. Afecta `tools`, `skillsInvocables`, `skillsRestringidos`.
+ *
+ * Antes:  tools: Read, Write, Edit, Bash
+ * Después: tools: [Read, Write, Edit, Bash]
+ *
+ * Razón: el schema declara `type: array` pero el uso real es CSV string. YAML
+ * estándar NO convierte CSV a array — el parser produce una sola string. Esto
+ * causó bugs históricos documentados en CLAUDE.md ("regla obligatoria CSV
+ * estricto"). Migrar a array inline elimina la ambigüedad.
+ *
+ * Idempotente: skip si ya es array.
+ *
+ * Casos especiales detectados en agentes:
+ *   - skillsInvocables: <ninguno>      → mantener literal
+ *   - skillsRestringidos: ninguno      → convertir a [] (array vacío)
+ *   - skillsRestringidos: \n  - x\n    → ya es array YAML multilinea, mantener
+ *
+ * Uso:
+ *   node scripts/migrar-csv-a-array.js [--dry-run]
+ *
+ * Zero-dependencies. Compatible Windows (CRLF-safe), Node 18+.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// Campos que migran de CSV a array
+const CAMPOS_CSV = ['tools', 'skillsInvocables', 'skillsRestringidos'];
+
+// Valores especiales que NO son listas y deben preservarse
+const VALORES_LITERAL = new Set(['ninguno', 'ninguna', '<ninguno>', '<ninguna>', 'none', 'null']);
+
+function parsearValorCSV(valorStr) {
+  // Detectar si ya es array inline `[a, b, c]`
+  if (/^\s*\[/.test(valorStr)) return null;
+
+  // Limpiar
+  const valor = valorStr.trim();
+  if (!valor) return [];
+
+  // Valor especial literal
+  if (VALORES_LITERAL.has(valor.toLowerCase())) return [];
+
+  // CSV split
+  return valor
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function migrarFrontmatter(contenido) {
+  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) return { contenido, cambios: 0 };
+
+  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
+  const fmCompleto = match[0];
+
+  let nuevoFm = fmCompleto;
+  let cambios = 0;
+
+  for (const campo of CAMPOS_CSV) {
+    // Patrón 2 PRIMERO: array YAML multilínea
+    //   skillsRestringidos:
+    //     - angular-moderno
+    //     - typescript-avanzado
+    // El campo está solo en su línea (sin valor) seguido de líneas con `  - X`
+    const re2 = new RegExp(`^(${campo}):[ \\t]*\\r?\\n((?:[ \\t]+-[ \\t]+[^\\r\\n]+\\r?\\n)+)`, 'm');
+    const m2 = nuevoFm.match(re2);
+    if (m2) {
+      const bloque = m2[2];
+      const items = bloque
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith('- '))
+        .map((l) => l.slice(2).trim().replace(/^["']|["']$/g, ''));
+      if (items.length > 0) {
+        const arrayInline = `[${items.join(', ')}]`;
+        const reemplazo = `${campo}: ${arrayInline}${eol}`;
+        nuevoFm = nuevoFm.replace(re2, reemplazo);
+        cambios++;
+      }
+      continue; // procesado, no aplicar regex 1
+    }
+
+    // Patrón 1: campo en una sola línea con valor (CSV o array inline)
+    //   tools: Read, Write
+    //   skillsRestringidos: ninguno
+    //   tools: [Read, Write]   ← skip, ya es array
+    // CRÍTICO: usar [ \\t]* (NO \\s*) para no consumir newlines
+    const re1 = new RegExp(`^(${campo}):[ \\t]*([^\\r\\n]+)$`, 'm');
+    const m1 = nuevoFm.match(re1);
+    if (m1) {
+      const valorStr = m1[2];
+      const items = parsearValorCSV(valorStr);
+      if (items === null) continue; // ya es array, skip
+      const arrayInline = `[${items.join(', ')}]`;
+      const reemplazo = `${campo}: ${arrayInline}`;
+      if (m1[0] !== reemplazo) {
+        nuevoFm = nuevoFm.replace(re1, reemplazo);
+        cambios++;
+      }
+    }
+  }
+
+  if (cambios === 0) return { contenido, cambios: 0 };
+
+  return { contenido: contenido.replace(fmCompleto, nuevoFm), cambios };
+}
+
+function migrarAgente(archivo) {
+  const contenido = fs.readFileSync(archivo, 'utf-8');
+  const { contenido: nuevo, cambios } = migrarFrontmatter(contenido);
+
+  if (cambios === 0) {
+    return { archivo: path.basename(archivo), status: 'sin-cambios' };
+  }
+
+  if (DRY_RUN) {
+    return { archivo: path.basename(archivo), status: 'dry-run', cambios };
+  }
+
+  fs.writeFileSync(archivo, nuevo, 'utf-8');
+  return { archivo: path.basename(archivo), status: 'migrado', cambios };
+}
+
+function main() {
+  console.log(`Migrando CSV → array YAML${DRY_RUN ? ' (dry-run)' : ''}...\n`);
+
+  const archivos = fs
+    .readdirSync(AGENTES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+    .map((f) => path.join(AGENTES_DIR, f));
+
+  const resultados = archivos.map(migrarAgente);
+
+  const stats = {
+    'sin-cambios': 0,
+    migrado: 0,
+    'dry-run': 0,
+    totalCambios: 0,
+  };
+
+  for (const r of resultados) {
+    stats[r.status] = (stats[r.status] || 0) + 1;
+    if (r.cambios) stats.totalCambios += r.cambios;
+  }
+
+  console.log(`Sin cambios: ${stats['sin-cambios']}`);
+  console.log(`Migrados: ${stats.migrado}`);
+  console.log(`Dry-run: ${stats['dry-run']}`);
+  console.log(`Total ediciones: ${stats.totalCambios}`);
+
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parsearValorCSV, migrarFrontmatter };