@saulwade/swl-ses 1.0.0

package/hooks/lib/agent-matcher.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * Agent Matcher — Asignacion inteligente de agentes por afinidad de capacidades.
+ *
+ * Dado un texto de tarea (titulo + descripcion), calcula un score de afinidad
+ * contra cada agente disponible usando keyword overlap bidireccional entre
+ * el texto de la tarea y los skills/descripcion del agente.
+ *
+ * Inspirado en el Scheduler capability-match de open-multi-agent.
+ * Adaptado a la estructura de agentes SWL (nombre, descripcion, skillsInvocables).
+ *
+ * Zero-dependencies: solo usa Node.js stdlib.
+ *
+ * @module hooks/lib/agent-matcher
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Stop words en español (excluidas del scoring)
+// ---------------------------------------------------------------------------
+
+const STOP_WORDS = new Set([
+  'para', 'como', 'este', 'esta', 'esto', 'cuando', 'donde', 'todos',
+  'cada', 'entre', 'desde', 'hasta', 'sobre', 'antes', 'despues', 'tiene',
+  'debe', 'puede', 'hacer', 'usar', 'solo', 'todo', 'bien', 'tambien',
+  'invocar', 'agente', 'sistema', 'proyecto', 'codigo', 'archivo',
+  'the', 'and', 'for', 'that', 'this', 'with', 'are', 'from', 'have',
+  'will', 'you', 'can', 'all', 'when', 'then', 'should', 'must',
+]);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae keywords significativas de un texto.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractKeywords(text) {
+  const words = (text || '')
+    .toLowerCase()
+    .replace(/[^a-záéíóúñü0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 3 && !STOP_WORDS.has(w));
+  return [...new Set(words)];
+}
+
+/**
+ * Cuenta cuantas keywords del array aparecen en el texto.
+ * @param {string} text
+ * @param {string[]} keywords
+ * @returns {number}
+ */
+function keywordScore(text, keywords) {
+  const lower = text.toLowerCase();
+  return keywords.reduce((acc, kw) => acc + (lower.includes(kw) ? 1 : 0), 0);
+}
+
+// ---------------------------------------------------------------------------
+// Cache de agentes
+// ---------------------------------------------------------------------------
+
+let _agentCache = null;
+let _agentCacheDir = null;
+
+/**
+ * Carga los agentes del directorio y extrae nombre, descripcion y skills.
+ * @param {string} agentesDir
+ * @returns {Array<{name: string, description: string, skills: string[], keywords: string[]}>}
+ */
+function loadAgents(agentesDir) {
+  if (_agentCache && _agentCacheDir === agentesDir) return _agentCache;
+
+  const agents = [];
+  try {
+    const files = fs.readdirSync(agentesDir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(agentesDir, file), 'utf8');
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch) continue;
+
+        const fm = fmMatch[1];
+        const nameMatch = fm.match(/^name:\s*(.+)$/m);
+        const descMatch = fm.match(/^description:\s*>?\s*\n?([\s\S]*?)(?=\n\w|\n---)/m);
+        const skillsMatch = fm.match(/^skillsInvocables:\s*(.+)$/m);
+
+        const name = nameMatch ? nameMatch[1].trim() : file.replace('.md', '');
+        const description = descMatch ? descMatch[1].replace(/\n\s*/g, ' ').trim() : '';
+        const skills = skillsMatch
+          ? skillsMatch[1].split(',').map(s => s.trim()).filter(Boolean)
+          : [];
+
+        const fullText = `${name} ${description} ${skills.join(' ')}`;
+        agents.push({
+          name,
+          description,
+          skills,
+          keywords: extractKeywords(fullText),
+        });
+      } catch (_) { /* skip malformed */ }
+    }
+  } catch (_) { /* dir not found */ }
+
+  _agentCache = agents;
+  _agentCacheDir = agentesDir;
+  return agents;
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Calcula scores de afinidad entre una tarea y los agentes disponibles.
+ *
+ * @param {string} taskText - Titulo + descripcion de la tarea.
+ * @param {string} [agentesDir] - Directorio de agentes. Default: ./agentes/
+ * @returns {Array<{name: string, score: number, skills: string[]}>} Ordenado por score descendente.
+ */
+function matchAgents(taskText, agentesDir) {
+  const dir = agentesDir || path.join(process.cwd(), 'agentes');
+  const agents = loadAgents(dir);
+  const taskKeywords = extractKeywords(taskText);
+
+  const scored = agents.map(agent => {
+    // Score bidireccional
+    const agentText = `${agent.name} ${agent.description}`;
+    const scoreA = keywordScore(agentText, taskKeywords);
+    const scoreB = keywordScore(taskText, agent.keywords);
+    return {
+      name: agent.name,
+      score: scoreA + scoreB,
+      skills: agent.skills,
+    };
+  });
+
+  return scored
+    .filter(a => a.score > 0)
+    .sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Sugiere el mejor agente para una tarea.
+ *
+ * @param {string} taskText
+ * @param {string} [agentesDir]
+ * @returns {{ name: string, score: number, skills: string[] } | null}
+ */
+function bestMatch(taskText, agentesDir) {
+  const matches = matchAgents(taskText, agentesDir);
+  return matches.length > 0 ? matches[0] : null;
+}
+
+/**
+ * Sugiere los top-N agentes para una tarea.
+ *
+ * @param {string} taskText
+ * @param {number} [n=3]
+ * @param {string} [agentesDir]
+ * @returns {Array<{name: string, score: number}>}
+ */
+function topMatches(taskText, n = 3, agentesDir) {
+  return matchAgents(taskText, agentesDir).slice(0, n);
+}
+
+/**
+ * Limpia el cache de agentes (para recargar despues de cambios).
+ */
+function clearCache() {
+  _agentCache = null;
+  _agentCacheDir = null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  matchAgents,
+  bestMatch,
+  topMatches,
+  clearCache,
+  extractKeywords,
+};

package/hooks/lib/async-hook-registry.js

@@ -0,0 +1,252 @@
+'use strict';
+
+/**
+ * Async Hook Registry — Fire-and-forget con tracking de promesas.
+ *
+ * Inspirado en AsyncHookRegistry de Claude Code:
+ *   - Los hooks marcados async: true corren sin bloquear el turno
+ *   - Cada hook registra una promesa con timeout configurable
+ *   - Los resultados se pueden consultar después (checkResponses)
+ *   - Fallos se registran silenciosamente sin afectar al usuario
+ *
+ * Patrón: registerPending() → proceso corre → checkResponses() recolecta
+ *
+ * Zero-dependencies — solo child_process y path nativos.
+ *
+ * Uso:
+ *   const registry = require('./async-hook-registry');
+ *   registry.registerPending('tracking-costos', '/path/to/hook.js', inputJson);
+ *   // ... más tarde ...
+ *   const results = registry.checkResponses();
+ *
+ * @module hooks/lib/async-hook-registry
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+
+/** Timeout por defecto para hooks async (ms). */
+const DEFAULT_TIMEOUT_MS = 15000; // 15 segundos
+
+/** Máximo de hooks pendientes simultáneos. */
+const MAX_PENDING = 20;
+
+// ---------------------------------------------------------------------------
+// Estado del registry (module-level, in-process)
+// ---------------------------------------------------------------------------
+
+/**
+ * @type {Map<string, {
+ *   hookName: string,
+ *   startedAt: number,
+ *   timeoutMs: number,
+ *   process: ChildProcess|null,
+ *   stdout: string,
+ *   stderr: string,
+ *   exitCode: number|null,
+ *   settled: boolean,
+ *   error: string|null
+ * }>}
+ */
+const pendingHooks = new Map();
+
+/** Contador monótono para IDs únicos. */
+let idCounter = 0;
+
+// ---------------------------------------------------------------------------
+// API Pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra y lanza un hook asíncronamente.
+ *
+ * El hook se ejecuta como proceso hijo. El resultado se recolecta
+ * con checkResponses() sin bloquear.
+ *
+ * @param {string} hookName - Nombre identificador del hook.
+ * @param {string} hookPath - Ruta absoluta al script .js del hook.
+ * @param {string|object} input - Input a pasar por stdin (JSON).
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=15000] - Timeout en ms.
+ * @returns {string} ID del hook registrado, o null si se descartó.
+ */
+function registerPending(hookName, hookPath, input, opts = {}) {
+  // Evitar saturación
+  if (pendingHooks.size >= MAX_PENDING) {
+    evictOldest();
+  }
+
+  const id = `${hookName}-${++idCounter}`;
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const inputStr = typeof input === 'string' ? input : JSON.stringify(input);
+
+  const entry = {
+    hookName,
+    startedAt: Date.now(),
+    timeoutMs,
+    process: null,
+    stdout: '',
+    stderr: '',
+    exitCode: null,
+    settled: false,
+    error: null,
+  };
+
+  pendingHooks.set(id, entry);
+
+  try {
+    const child = spawn(process.execPath, [hookPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, SWL_ASYNC_HOOK: '1' },
+      detached: false,
+    });
+
+    entry.process = child;
+
+    child.stdout.on('data', chunk => { entry.stdout += chunk; });
+    child.stderr.on('data', chunk => { entry.stderr += chunk; });
+
+    child.on('close', code => {
+      entry.exitCode = code;
+      entry.settled = true;
+    });
+
+    child.on('error', err => {
+      entry.error = err.message;
+      entry.settled = true;
+    });
+
+    // Escribir input y cerrar stdin
+    child.stdin.write(inputStr);
+    child.stdin.end();
+
+    // Timeout: matar el proceso si no termina a tiempo
+    setTimeout(() => {
+      if (!entry.settled) {
+        entry.error = `Timeout después de ${timeoutMs}ms`;
+        entry.settled = true;
+        try { child.kill('SIGTERM'); } catch { /* ya murió */ }
+      }
+    }, timeoutMs);
+
+  } catch (err) {
+    entry.error = `Error al lanzar: ${err.message}`;
+    entry.settled = true;
+  }
+
+  return id;
+}
+
+/**
+ * Recolecta resultados de hooks que ya terminaron.
+ *
+ * Retorna y elimina del registry todos los hooks settled.
+ * Los hooks aún pendientes se mantienen para la próxima consulta.
+ *
+ * @returns {Array<{
+ *   id: string,
+ *   hookName: string,
+ *   exitCode: number|null,
+ *   stdout: string,
+ *   stderr: string,
+ *   error: string|null,
+ *   durationMs: number
+ * }>}
+ */
+function checkResponses() {
+  const results = [];
+
+  for (const [id, entry] of pendingHooks) {
+    if (entry.settled) {
+      results.push({
+        id,
+        hookName: entry.hookName,
+        exitCode: entry.exitCode,
+        stdout: entry.stdout.trim(),
+        stderr: entry.stderr.trim(),
+        error: entry.error,
+        durationMs: Date.now() - entry.startedAt,
+      });
+      pendingHooks.delete(id);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Cuenta hooks pendientes (aún no settled).
+ * @returns {number}
+ */
+function pendingCount() {
+  let count = 0;
+  for (const entry of pendingHooks.values()) {
+    if (!entry.settled) count++;
+  }
+  return count;
+}
+
+/**
+ * Verifica si un hook específico tiene entradas pendientes.
+ * @param {string} hookName
+ * @returns {boolean}
+ */
+function hasPending(hookName) {
+  for (const entry of pendingHooks.values()) {
+    if (entry.hookName === hookName && !entry.settled) return true;
+  }
+  return false;
+}
+
+/**
+ * Mata todos los hooks pendientes y limpia el registry.
+ */
+function killAll() {
+  for (const [id, entry] of pendingHooks) {
+    if (!entry.settled && entry.process) {
+      try { entry.process.kill('SIGTERM'); } catch { /* ok */ }
+    }
+    pendingHooks.delete(id);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Elimina la entrada más antigua (settled o no) para hacer espacio.
+ */
+function evictOldest() {
+  let oldestId = null;
+  let oldestTime = Infinity;
+
+  for (const [id, entry] of pendingHooks) {
+    if (entry.startedAt < oldestTime) {
+      oldestTime = entry.startedAt;
+      oldestId = id;
+    }
+  }
+
+  if (oldestId) {
+    const entry = pendingHooks.get(oldestId);
+    if (entry && !entry.settled && entry.process) {
+      try { entry.process.kill('SIGTERM'); } catch { /* ok */ }
+    }
+    pendingHooks.delete(oldestId);
+  }
+}
+
+module.exports = {
+  registerPending,
+  checkResponses,
+  pendingCount,
+  hasPending,
+  killAll,
+  DEFAULT_TIMEOUT_MS,
+  MAX_PENDING,
+};

package/hooks/lib/atomic-write.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Atomic Write — Escritura atómica a disco con rollback opcional.
+ *
+ * Previene archivos corruptos por interrupciones mid-write.
+ * Patrón adoptado de Hermes Agent (_atomic_write_text).
+ *
+ * Estrategia:
+ *   1. Escribe a archivo temporal en el mismo directorio
+ *   2. fs.renameSync() es atómico en el mismo filesystem
+ *   3. Si falla, el archivo original queda intacto
+ *
+ * @module hooks/lib/atomic-write
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+/**
+ * Escribe contenido a un archivo de forma atómica.
+ *
+ * Aplica `opciones.mode` directamente al temporal antes del rename, lo que
+ * elimina la race condition entre la escritura y un chmod posterior —
+ * el archivo destino hereda los permisos desde el momento de creación.
+ *
+ * @param {string} filePath             - Ruta absoluta del archivo destino.
+ * @param {string} content              - Contenido a escribir.
+ * @param {string} [encoding='utf8']    - Encoding del archivo.
+ * @param {object} [opciones={}]        - Opciones adicionales.
+ * @param {number} [opciones.mode]      - Permisos POSIX del archivo (ej: 0o600).
+ *   Ignorado en Windows (no lanza error).
+ * @throws {Error} Si la escritura o el rename fallan.
+ */
+function atomicWriteSync(filePath, content, encoding = 'utf8', opciones = {}) {
+  const dir     = path.dirname(filePath);
+  const suffix  = crypto.randomBytes(4).toString('hex');
+  const tmpName = `.${path.basename(filePath)}.${suffix}.tmp`;
+  const tmpPath = path.join(dir, tmpName);
+
+  // Asegurar que el directorio existe
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Construir opciones de escritura — incluir mode si se proporcionó
+  const writeOpts = { encoding };
+  if (opciones.mode !== undefined && process.platform !== 'win32') {
+    writeOpts.mode = opciones.mode;
+  }
+
+  try {
+    fs.writeFileSync(tmpPath, content, writeOpts);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    // Limpiar temporal si quedó en disco
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw err;
+  }
+}
+
+/**
+ * Escribe JSON a un archivo de forma atómica con validación.
+ *
+ * Soporta `opciones.mode` igual que atomicWriteSync para aplicar permisos
+ * desde la creación del temporal (sin race condition de chmod).
+ *
+ * @param {string} filePath          - Ruta absoluta del archivo destino.
+ * @param {*}      data              - Datos a serializar como JSON.
+ * @param {number} [indent=2]        - Espacios de indentación.
+ * @param {object} [opciones={}]     - Opciones adicionales.
+ * @param {number} [opciones.mode]   - Permisos POSIX del archivo (ej: 0o600).
+ * @throws {Error} Si la serialización, escritura o validación fallan.
+ */
+function atomicWriteJSON(filePath, data, indent = 2, opciones = {}) {
+  const content = JSON.stringify(data, null, indent);
+
+  // Validar que el JSON es parseable antes de escribir
+  try {
+    JSON.parse(content);
+  } catch (err) {
+    throw new Error(`JSON inválido antes de escribir a ${filePath}: ${err.message}`);
+  }
+
+  atomicWriteSync(filePath, content, 'utf8', opciones);
+}
+
+/**
+ * Escribe con validación post-escritura y rollback automático.
+ *
+ * Si validateFn retorna un string (mensaje de error), revierte al contenido
+ * original. Si retorna true, la escritura se confirma.
+ *
+ * @param {string} filePath   - Ruta absoluta del archivo.
+ * @param {string} content    - Contenido a escribir.
+ * @param {function} validateFn - Función (content) => true | string.
+ *   Retorna true si es válido, o un string con el error.
+ * @returns {{ success: boolean, error?: string }}
+ */
+function atomicWriteWithValidation(filePath, content, validateFn) {
+  // Guardar original para rollback
+  let originalContent = null;
+  try {
+    originalContent = fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    // Archivo nuevo — no hay original para rollback
+  }
+
+  // Escribir atómicamente
+  atomicWriteSync(filePath, content);
+
+  // Validar post-escritura
+  if (typeof validateFn === 'function') {
+    const result = validateFn(content);
+    if (result !== true) {
+      // Rollback
+      if (originalContent !== null) {
+        atomicWriteSync(filePath, originalContent);
+      } else {
+        try { fs.unlinkSync(filePath); } catch (_) {}
+      }
+      return { success: false, error: String(result) };
+    }
+  }
+
+  return { success: true };
+}
+
+module.exports = { atomicWriteSync, atomicWriteJSON, atomicWriteWithValidation };