@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/mcp-server/handlers.js

@@ -1,206 +1,386 @@
-'use strict';
-
-/**
- * handlers.js — Handlers para los 3 endpoints MCP stub de swl-ses.
- *
- * **EXPERIMENTAL** — no producción. Sin auth, sin rate limiting, sin
- * tests robustos. Ver `scripts/mcp-server/README.md` para limitaciones.
- *
- * Los handlers leen el estado file-based de swl-ses (APRENDIZAJES.md,
- * .planning/sessions/, instintos/proyecto.yaml) y devuelven datos
- * estructurados al cliente MCP. NO escriben — solo lectura.
- *
- * @module scripts/mcp-server/handlers
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const memorySearch       = require('../../hooks/lib/memory-search');
-const scoringInstintos   = require('../lib/scoring-instintos');
-
-// ── handler: swl_memory_search ────────────────────────────────────────────────
-
-/**
- * Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos).
- *
- * @param {object} args - { query: string, limit?: number, tipo?: string }
- * @returns {object} { results: Array, count: number }
- */
-function swlMemorySearch(baseDir, args) {
-  if (!args || typeof args.query !== 'string' || !args.query.trim()) {
-    return { error: 'query (string) requerido', results: [] };
-  }
-
-  const filtros = {};
-  if (typeof args.limit === 'number' && args.limit > 0) filtros.limit = Math.min(args.limit, 50);
-  if (typeof args.tipo === 'string') filtros.tipo = args.tipo;
-
-  const results = memorySearch.search(baseDir, args.query, filtros);
-  return {
-    results: results.map(r => ({
-      id: r.id,
-      tipo: r.tipo,
-      titulo: r.titulo,
-      fecha: r.fecha,
-      relevancia: r.relevancia,
-      combinedScore: r.combinedScore,
-    })),
-    count: results.length,
-  };
-}
-
-// ── handler: swl_aprendizajes_recientes ───────────────────────────────────────
-
-/**
- * Devuelve los N aprendizajes más recientes de APRENDIZAJES.md.
- *
- * @param {object} args - { limit?: number (default 10) }
- * @returns {object} { results, count }
- */
-function swlAprendizajesRecientes(baseDir, args = {}) {
-  const limit = (typeof args.limit === 'number' && args.limit > 0)
-    ? Math.min(args.limit, 50)
-    : 10;
-
-  const ruta = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
-  if (!fs.existsSync(ruta)) {
-    return { error: 'APRENDIZAJES.md no encontrado', results: [] };
-  }
-
-  let contenido;
-  try {
-    contenido = fs.readFileSync(ruta, 'utf8');
-  } catch (err) {
-    return { error: 'Error de lectura: ' + err.message, results: [] };
-  }
-
-  const bloques = contenido.split(/^## /m).filter(b => b.trim().length > 0);
-  // Los más recientes están al FINAL del archivo (append-only por convención)
-  const recientes = bloques.slice(-limit).reverse();
-
-  return {
-    results: recientes.map((b, i) => {
-      const primeraLinea = b.split('\n')[0].trim();
-      const cuerpoTrim = b.split('\n').slice(1).join('\n').trim().slice(0, 500);
-      return {
-        index: bloques.length - i,
-        titulo: primeraLinea,
-        contenido: cuerpoTrim,
-      };
-    }),
-    count: recientes.length,
-    total: bloques.length,
-  };
-}
-
-// ── handler: swl_instintos_activos ────────────────────────────────────────────
-
-/**
- * Devuelve instintos con effective_confidence ≥ umbral.
- *
- * @param {object} args - { minConfidence?: number (default 0.5), limit?: number }
- * @returns {object} { results, count }
- */
-function swlInstintosActivos(baseDir, args = {}) {
-  const minConfidence = (typeof args.minConfidence === 'number')
-    ? args.minConfidence : 0.5;
-  const limit = (typeof args.limit === 'number' && args.limit > 0)
-    ? Math.min(args.limit, 100) : 20;
-
-  const ruta = path.join(baseDir, 'instintos', 'proyecto.yaml');
-  if (!fs.existsSync(ruta)) {
-    return { error: 'instintos/proyecto.yaml no encontrado', results: [] };
-  }
-
-  let contenido;
-  try {
-    contenido = fs.readFileSync(ruta, 'utf8');
-  } catch (err) {
-    return { error: 'Error de lectura: ' + err.message, results: [] };
-  }
-
-  // Parser simple sin dep YAML (mismo patrón que memory-search.js)
-  const instinto_re = /- id:\s*(\S+)[\s\S]*?pattern:\s*"([^"]+)"[\s\S]*?confidence:\s*([\d.]+)[\s\S]*?status:\s*(\w+)/g;
-  const results = [];
-  let match;
-  const ahora = new Date();
-
-  while ((match = instinto_re.exec(contenido)) !== null) {
-    const [, id, pattern, confidenceStr, status] = match;
-    const confidence = parseFloat(confidenceStr);
-    if (status !== 'active') continue;
-
-    // Construir objeto mínimo para scoring
-    const instinto = {
-      id,
-      pattern,
-      confidence,
-      status,
-      // Sin más metadata, effective_confidence ≈ confidence
-    };
-    const effective = scoringInstintos.effectiveConfidence(instinto, ahora);
-    if (effective < minConfidence) continue;
-
-    results.push({
-      id,
-      pattern,
-      confidence,
-      effective_confidence: Math.round(effective * 1000) / 1000,
-      status,
-    });
-  }
-
-  results.sort((a, b) => b.effective_confidence - a.effective_confidence);
-  return {
-    results: results.slice(0, limit),
-    count: Math.min(results.length, limit),
-    total: results.length,
-  };
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-const HANDLERS = {
-  swl_memory_search: {
-    description: 'Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos) con RRF fusion.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: { type: 'string', description: 'Texto libre de búsqueda' },
-        limit: { type: 'number', description: 'Máximo de resultados (default 20, max 50)' },
-        tipo:  { type: 'string', enum: ['aprendizaje', 'sesion', 'instinto'], description: 'Filtrar por tipo' },
-      },
-      required: ['query'],
-    },
-    handler: swlMemorySearch,
-  },
-  swl_aprendizajes_recientes: {
-    description: 'Últimos N aprendizajes de .planning/APRENDIZAJES.md (más recientes primero).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: { type: 'number', description: 'Cuántos retornar (default 10, max 50)' },
-      },
-    },
-    handler: swlAprendizajesRecientes,
-  },
-  swl_instintos_activos: {
-    description: 'Instintos con effective_confidence ≥ umbral. Default 0.5.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        minConfidence: { type: 'number', description: 'Umbral mínimo (default 0.5)' },
-        limit: { type: 'number', description: 'Máximo (default 20, max 100)' },
-      },
-    },
-    handler: swlInstintosActivos,
-  },
-};
-
-module.exports = {
-  HANDLERS,
-  swlMemorySearch,
-  swlAprendizajesRecientes,
-  swlInstintosActivos,
-};
+'use strict';
+
+/**
+ * handlers.js — Handlers para los 3 endpoints MCP del swl-mcp-server.
+ *
+ * v1.0.0 (ADR-0019 Sub-fase 3): integra caching mtime-based desde
+ * `scripts/mcp-server/cache.js`. Sigue siendo solo lectura.
+ *
+ * Los handlers leen el estado file-based de swl-ses (APRENDIZAJES.md,
+ * .planning/sessions/, instintos/proyecto.yaml) y devuelven datos
+ * estructurados al cliente MCP. NO escriben — solo lectura.
+ *
+ * @module scripts/mcp-server/handlers
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch       = require('../../hooks/lib/memory-search');
+const scoringInstintos   = require('../lib/scoring-instintos');
+const { crearCache }     = require('./cache');
+
+// Cache singleton — compartido entre handlers para reducir IO en lecturas repetidas.
+// mtime-based, invalidación automática cuando el archivo cambia. ADR-0019 Sub-fase 3.
+const cache = crearCache();
+
+// ── handler: swl_memory_search ────────────────────────────────────────────────
+
+/**
+ * Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos).
+ *
+ * @param {object} args - { query: string, limit?: number, tipo?: string }
+ * @returns {object} { results: Array, count: number }
+ */
+function swlMemorySearch(baseDir, args) {
+  if (!args || typeof args.query !== 'string' || !args.query.trim()) {
+    return { error: 'query (string) requerido', results: [] };
+  }
+
+  const filtros = {};
+  if (typeof args.limit === 'number' && args.limit > 0) filtros.limit = Math.min(args.limit, 50);
+  if (typeof args.tipo === 'string') filtros.tipo = args.tipo;
+
+  const results = memorySearch.search(baseDir, args.query, filtros);
+  return {
+    results: results.map(r => ({
+      id: r.id,
+      tipo: r.tipo,
+      titulo: r.titulo,
+      fecha: r.fecha,
+      relevancia: r.relevancia,
+      combinedScore: r.combinedScore,
+    })),
+    count: results.length,
+  };
+}
+
+// ── handler: swl_aprendizajes_recientes ───────────────────────────────────────
+
+/**
+ * Devuelve los N aprendizajes más recientes de APRENDIZAJES.md.
+ *
+ * @param {object} args - { limit?: number (default 10) }
+ * @returns {object} { results, count }
+ */
+function swlAprendizajesRecientes(baseDir, args = {}) {
+  const limit = (typeof args.limit === 'number' && args.limit > 0)
+    ? Math.min(args.limit, 50)
+    : 10;
+
+  const ruta = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  let cached;
+  try {
+    cached = cache.get(ruta, (contenido) => {
+      const bloques = contenido.split(/^## /m).filter(b => b.trim().length > 0);
+      return { bloques };
+    });
+  } catch (err) {
+    return { error: 'Error de lectura: ' + err.message, results: [] };
+  }
+  if (!cached) return { error: 'APRENDIZAJES.md no encontrado', results: [] };
+
+  const { bloques } = cached.data;
+  // Los más recientes están al FINAL del archivo (append-only por convención)
+  const recientes = bloques.slice(-limit).reverse();
+
+  return {
+    results: recientes.map((b, i) => {
+      const primeraLinea = b.split('\n')[0].trim();
+      const cuerpoTrim = b.split('\n').slice(1).join('\n').trim().slice(0, 500);
+      return {
+        index: bloques.length - i,
+        titulo: primeraLinea,
+        contenido: cuerpoTrim,
+      };
+    }),
+    count: recientes.length,
+    total: bloques.length,
+  };
+}
+
+// ── handler: swl_instintos_activos ────────────────────────────────────────────
+
+/**
+ * Devuelve instintos con effective_confidence ≥ umbral.
+ *
+ * @param {object} args - { minConfidence?: number (default 0.5), limit?: number }
+ * @returns {object} { results, count }
+ */
+function swlInstintosActivos(baseDir, args = {}) {
+  const minConfidence = (typeof args.minConfidence === 'number')
+    ? args.minConfidence : 0.5;
+  const limit = (typeof args.limit === 'number' && args.limit > 0)
+    ? Math.min(args.limit, 100) : 20;
+
+  const ruta = path.join(baseDir, 'instintos', 'proyecto.yaml');
+  if (!fs.existsSync(ruta)) {
+    return { error: 'instintos/proyecto.yaml no encontrado', results: [] };
+  }
+
+  let contenido;
+  try {
+    contenido = fs.readFileSync(ruta, 'utf8');
+  } catch (err) {
+    return { error: 'Error de lectura: ' + err.message, results: [] };
+  }
+
+  // Parser simple sin dep YAML (mismo patrón que memory-search.js)
+  const instinto_re = /- id:\s*(\S+)[\s\S]*?pattern:\s*"([^"]+)"[\s\S]*?confidence:\s*([\d.]+)[\s\S]*?status:\s*(\w+)/g;
+  const results = [];
+  let match;
+  const ahora = new Date();
+
+  while ((match = instinto_re.exec(contenido)) !== null) {
+    const [, id, pattern, confidenceStr, status] = match;
+    const confidence = parseFloat(confidenceStr);
+    if (status !== 'active') continue;
+
+    // Construir objeto mínimo para scoring
+    const instinto = {
+      id,
+      pattern,
+      confidence,
+      status,
+      // Sin más metadata, effective_confidence ≈ confidence
+    };
+    const effective = scoringInstintos.effectiveConfidence(instinto, ahora);
+    if (effective < minConfidence) continue;
+
+    results.push({
+      id,
+      pattern,
+      confidence,
+      effective_confidence: Math.round(effective * 1000) / 1000,
+      status,
+    });
+  }
+
+  results.sort((a, b) => b.effective_confidence - a.effective_confidence);
+  return {
+    results: results.slice(0, limit),
+    count: Math.min(results.length, limit),
+    total: results.length,
+  };
+}
+
+// ── handler: swl_list_skills ──────────────────────────────────────────────────
+
+/**
+ * Lista los skills disponibles (nombre + descripción del frontmatter).
+ *
+ * Sub-fase 9 (v1.5.0). Útil para clientes MCP que no cargan skills filesystem
+ * nativamente y necesitan descubrir qué skills existen antes de invocarlos
+ * con swl_invoke_skill.
+ *
+ * Resolución del directorio de skills:
+ *   1. Si baseDir tiene `habilidades/`, usar ese (repo SWL como project root).
+ *   2. Si baseDir tiene `.claude/skills/`, usar ese (proyecto consumidor con SWL instalado).
+ *   3. Si baseDir tiene `.cursor/skills/`, usar ese.
+ *   4. Si nada de eso, devolver error.
+ *
+ * @param {string} baseDir
+ * @param {object} args - { dominio?: string, limit?: number }
+ */
+function swlListSkills(baseDir, args = {}) {
+  const dirSkills = resolverDirSkills(baseDir);
+  if (!dirSkills) {
+    return { error: 'No se encontró directorio de skills (habilidades/, .claude/skills/, .cursor/skills/)', results: [] };
+  }
+
+  const limit = (typeof args.limit === 'number' && args.limit > 0)
+    ? Math.min(args.limit, 500) : 200;
+  const dominio = typeof args.dominio === 'string' ? args.dominio.toLowerCase() : null;
+
+  let nombres;
+  try {
+    nombres = fs.readdirSync(dirSkills, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+      .map(d => d.name);
+  } catch (err) {
+    return { error: 'Error leyendo directorio: ' + err.message, results: [] };
+  }
+
+  const results = [];
+  for (const nombre of nombres) {
+    if (dominio && !nombre.toLowerCase().includes(dominio)) continue;
+    const skillMd = path.join(dirSkills, nombre, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) continue;
+    try {
+      const contenido = fs.readFileSync(skillMd, 'utf-8');
+      const descMatch = contenido.match(/description:\s*>?\s*\n?\s*(.+?)(?=\n\w+:|\n---)/s);
+      const descripcion = descMatch ? descMatch[1].replace(/\s+/g, ' ').trim() : '';
+      results.push({
+        nombre,
+        descripcion: descripcion.length > 300 ? descripcion.slice(0, 297) + '...' : descripcion,
+      });
+    } catch { /* skill ilegible — saltar */ }
+    if (results.length >= limit) break;
+  }
+
+  return { results, count: results.length, total: nombres.length, dir: dirSkills };
+}
+
+// ── handler: swl_invoke_skill ─────────────────────────────────────────────────
+
+/**
+ * Devuelve el contenido completo de un SKILL.md por nombre.
+ *
+ * Sub-fase 9 (v1.5.0). Útil para clientes MCP donde el cliente NO carga skills
+ * filesystem nativamente (Codex CLI en `--local`, Gemini CLI, otros) pero quiere
+ * acceder a conocimiento operacional SWL. El cliente recibe el cuerpo completo
+ * del SKILL.md y puede usarlo como contexto en su próxima llamada.
+ *
+ * Limitaciones aceptadas:
+ *  - NO ejecuta scripts del skill — solo devuelve el SKILL.md como texto.
+ *  - Si el skill referencia `recursos/X.md`, el cliente debe pedirlo aparte
+ *    (no implementamos retrieval recursivo en v1.5.0).
+ *  - El cuerpo se trunca a 100 KB para no saturar el contexto del cliente.
+ *
+ * @param {string} baseDir
+ * @param {object} args - { nombre: string }
+ */
+function swlInvokeSkill(baseDir, args) {
+  if (!args || typeof args.nombre !== 'string' || !args.nombre.trim()) {
+    return { error: 'argumento "nombre" (string) requerido' };
+  }
+  // Sanitización: solo nombres en kebab-case (prevenir path traversal).
+  const nombre = args.nombre.trim();
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/i.test(nombre)) {
+    return { error: 'Nombre de skill inválido. Solo [a-zA-Z0-9-], 1-63 caracteres.' };
+  }
+
+  const dirSkills = resolverDirSkills(baseDir);
+  if (!dirSkills) {
+    return { error: 'No se encontró directorio de skills (habilidades/, .claude/skills/, .cursor/skills/)' };
+  }
+
+  const skillMd = path.join(dirSkills, nombre, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) {
+    return { error: `Skill "${nombre}" no encontrado en ${dirSkills}` };
+  }
+
+  let contenido;
+  try {
+    contenido = fs.readFileSync(skillMd, 'utf-8');
+  } catch (err) {
+    return { error: 'Error leyendo SKILL.md: ' + err.message };
+  }
+
+  const MAX = 100 * 1024;
+  let truncado = false;
+  if (Buffer.byteLength(contenido, 'utf-8') > MAX) {
+    contenido = contenido.slice(0, MAX) + '\n\n> NOTA: contenido truncado a 100 KB.';
+    truncado = true;
+  }
+
+  // Listar recursos disponibles (sin leerlos) para que el cliente sepa qué pedir.
+  const recursos = [];
+  const dirRecursos = path.join(dirSkills, nombre, 'recursos');
+  if (fs.existsSync(dirRecursos)) {
+    try {
+      const archivos = fs.readdirSync(dirRecursos)
+        .filter(f => /\.(md|json|yaml|yml|txt)$/i.test(f));
+      recursos.push(...archivos.map(f => `recursos/${f}`));
+    } catch { /* sin recursos */ }
+  }
+
+  return { nombre, contenido, truncado, recursos, fuente: skillMd };
+}
+
+/**
+ * Resuelve el directorio de skills en el orden de precedencia:
+ *   1. baseDir/habilidades/  (repo SWL como project root)
+ *   2. baseDir/.claude/skills/  (proyecto consumidor con SWL instalado en Claude)
+ *   3. baseDir/.cursor/skills/  (proyecto con SWL instalado en Cursor)
+ *
+ * Retorna null si ninguno existe.
+ */
+function resolverDirSkills(baseDir) {
+  const candidatos = [
+    path.join(baseDir, 'habilidades'),
+    path.join(baseDir, '.claude', 'skills'),
+    path.join(baseDir, '.cursor', 'skills'),
+  ];
+  for (const dir of candidatos) {
+    if (fs.existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+const HANDLERS = {
+  swl_memory_search: {
+    description: 'Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos) con RRF fusion.',
+    schemaVersion: '1.0.0',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Texto libre de búsqueda' },
+        limit: { type: 'number', description: 'Máximo de resultados (default 20, max 50)' },
+        tipo:  { type: 'string', enum: ['aprendizaje', 'sesion', 'instinto'], description: 'Filtrar por tipo' },
+      },
+      required: ['query'],
+    },
+    handler: swlMemorySearch,
+  },
+  swl_aprendizajes_recientes: {
+    description: 'Últimos N aprendizajes de .planning/APRENDIZAJES.md (más recientes primero).',
+    schemaVersion: '1.0.0',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Cuántos retornar (default 10, max 50)' },
+      },
+    },
+    handler: swlAprendizajesRecientes,
+  },
+  swl_instintos_activos: {
+    description: 'Instintos con effective_confidence ≥ umbral. Default 0.5.',
+    schemaVersion: '1.0.0',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        minConfidence: { type: 'number', description: 'Umbral mínimo (default 0.5)' },
+        limit: { type: 'number', description: 'Máximo (default 20, max 100)' },
+      },
+    },
+    handler: swlInstintosActivos,
+  },
+  swl_list_skills: {
+    description: 'Lista skills SWL disponibles (nombre + descripción). Útil para descubrir conocimiento operacional antes de invocar swl_invoke_skill.',
+    schemaVersion: '1.0.0',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dominio: { type: 'string', description: 'Filtro substring por nombre (opcional)' },
+        limit:   { type: 'number', description: 'Máximo (default 200, max 500)' },
+      },
+    },
+    handler: swlListSkills,
+  },
+  swl_invoke_skill: {
+    description: 'Devuelve el SKILL.md completo de un skill SWL por nombre. Para clientes MCP que no cargan skills filesystem nativamente — el cliente recibe el cuerpo y lo usa como contexto.',
+    schemaVersion: '1.0.0',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        nombre: { type: 'string', description: 'Nombre del skill (kebab-case, ej. fastapi-experto)' },
+      },
+      required: ['nombre'],
+    },
+    handler: swlInvokeSkill,
+  },
+};
+
+module.exports = {
+  HANDLERS,
+  swlMemorySearch,
+  swlAprendizajesRecientes,
+  swlInstintosActivos,
+  swlListSkills,
+  swlInvokeSkill,
+  // Expuesto para tests — permite invalidar el cache singleton entre runs.
+  _cache: cache,
+};