@saulwade/swl-ses 1.0.0

package/hooks/lib/execution-state.js

@@ -0,0 +1,316 @@
+'use strict';
+
+/**
+ * execution-state.js — Estado de ejecución serializable para planes multi-agente.
+ *
+ * Inspirado en el patrón ExecutionSnapshot de Sim Studio (simstudioai/sim).
+ * Permite pausar y reanudar planes multi-agente con estado preciso,
+ * eliminando la reconstrucción de contexto a partir de texto libre.
+ *
+ * Archivo producido: .planning/execution-state.json
+ *
+ * Estructura del estado:
+ * {
+ *   planId:             string — identificador del plan activo
+ *   fase:               string — nombre de la fase actual
+ *   timestamp:          string — ISO 8601 de la última actualización
+ *   agentesEjecutados:  AgentEntry[]
+ *   agenteActual:       AgentRef | null
+ *   proximoAgente:      AgentRef | null
+ *   contextoCompartido: SharedContext
+ *   metadatos:          { sessionId, cwd }
+ * }
+ *
+ * Uso desde el orquestador o skill ejecutar-fase:
+ *   const es = require('./lib/execution-state');
+ *   es.iniciarAgente(cwd, 'implementador-swl', 'api-endpoints');
+ *   // ... esperar output del agente ...
+ *   es.completarAgente(cwd, 'implementador-swl', 'api-endpoints', { archivos: ['src/api.py'] });
+ *   es.establecerProximo(cwd, 'tdd-qa-swl', 'tests-unitarios');
+ *
+ * @module hooks/lib/execution-state
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('./atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const NOMBRE_ARCHIVO = 'execution-state.json';
+
+// ---------------------------------------------------------------------------
+// Fábrica de estado vacío
+// ---------------------------------------------------------------------------
+
+/**
+ * Crea un estado de ejecución nuevo y vacío.
+ *
+ * @param {string} [planId='plan-sin-nombre'] — Identificador del plan
+ * @param {string} [fase='sin-fase']          — Nombre de la fase
+ * @returns {object}
+ */
+function nuevo(planId = 'plan-sin-nombre', fase = 'sin-fase') {
+  return {
+    planId,
+    fase,
+    timestamp:          new Date().toISOString(),
+    agentesEjecutados:  [],
+    agenteActual:       null,
+    proximoAgente:      null,
+    contextoCompartido: {
+      archivosModificados: [],
+      testsStatus:         'desconocido',
+      decisiones:          [],
+      erroresDetectados:   [],
+    },
+    metadatos: {
+      sessionId: '',
+      cwd:       '',
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// I/O — Lectura y escritura atómica
+// ---------------------------------------------------------------------------
+
+/**
+ * Devuelve la ruta absoluta del archivo de estado para el directorio dado.
+ *
+ * @param {string} cwd — Directorio raíz del proyecto.
+ * @returns {string}
+ */
+function rutaArchivo(cwd) {
+  return path.join(cwd, '.planning', NOMBRE_ARCHIVO);
+}
+
+/**
+ * Lee el estado de ejecución del disco.
+ * Si el archivo no existe o está corrupto, devuelve un estado vacío.
+ *
+ * @param {string} cwd — Directorio raíz del proyecto.
+ * @returns {object}
+ */
+function leer(cwd) {
+  try {
+    const ruta = rutaArchivo(cwd);
+    if (!fs.existsSync(ruta)) return nuevo();
+    const raw = fs.readFileSync(ruta, 'utf8');
+    const parsed = JSON.parse(raw);
+    // Garantizar campos opcionales (compatibilidad con versiones previas del archivo)
+    parsed.agentesEjecutados  = parsed.agentesEjecutados  || [];
+    parsed.contextoCompartido = parsed.contextoCompartido || {
+      archivosModificados: [],
+      testsStatus:         'desconocido',
+      decisiones:          [],
+      erroresDetectados:   [],
+    };
+    parsed.metadatos = parsed.metadatos || { sessionId: '', cwd: '' };
+    return parsed;
+  } catch (_) {
+    return nuevo();
+  }
+}
+
+/**
+ * Persiste el estado en disco de forma atómica.
+ *
+ * @param {string} cwd    — Directorio raíz del proyecto.
+ * @param {object} estado — Estado a persistir.
+ */
+function escribir(cwd, estado) {
+  estado.timestamp = new Date().toISOString();
+  atomicWriteJSON(rutaArchivo(cwd), estado);
+}
+
+// ---------------------------------------------------------------------------
+// Mutaciones — API de alto nivel
+// ---------------------------------------------------------------------------
+
+/**
+ * Marca un agente como actualmente en ejecución (agenteActual).
+ * No bloquea; solo registra el estado para auditoría y resumption.
+ *
+ * @param {string} cwd
+ * @param {string} agente  — Nombre del agente (ej: "implementador-swl")
+ * @param {string} slice   — Nombre del slice que ejecuta (ej: "api-endpoints")
+ * @param {object} [opts]  — { sessionId, cwd: rutaProyecto }
+ */
+function iniciarAgente(cwd, agente, slice, opts = {}) {
+  const estado = leer(cwd);
+  estado.agenteActual = { agente, slice, iniciadoEn: new Date().toISOString() };
+  if (opts.sessionId) estado.metadatos.sessionId = opts.sessionId;
+  if (opts.cwd)       estado.metadatos.cwd       = opts.cwd;
+  escribir(cwd, estado);
+}
+
+/**
+ * Marca el agente actual como completado y lo agrega a agentesEjecutados.
+ * Es idempotente: si el agente/slice ya existe, reemplaza la entrada.
+ *
+ * @param {string} cwd
+ * @param {string} agente         — Nombre del agente
+ * @param {string} slice          — Nombre del slice completado
+ * @param {object} [outputResumen={}] — Resumen libre del output (max ~500 chars)
+ * @param {object} [opts]
+ * @param {number} [opts.duracionMs]  — Duración en ms
+ * @param {number} [opts.tokensEst]   — Tokens estimados consumidos
+ */
+function completarAgente(cwd, agente, slice, outputResumen = {}, opts = {}) {
+  const estado = leer(cwd);
+
+  const entrada = {
+    agente,
+    slice,
+    status:       'done',
+    outputResumen,
+    duracionMs:   opts.duracionMs || 0,
+    tokensEst:    opts.tokensEst  || 0,
+    completadoEn: new Date().toISOString(),
+  };
+
+  // Idempotente: reemplaza si ya existe
+  const idx = estado.agentesEjecutados.findIndex(a => a.agente === agente && a.slice === slice);
+  if (idx >= 0) {
+    estado.agentesEjecutados[idx] = entrada;
+  } else {
+    estado.agentesEjecutados.push(entrada);
+  }
+
+  // Limpiar agenteActual si coincide
+  if (estado.agenteActual?.agente === agente && estado.agenteActual?.slice === slice) {
+    estado.agenteActual = null;
+  }
+
+  escribir(cwd, estado);
+}
+
+/**
+ * Registra el próximo agente a ejecutar en el plan.
+ *
+ * @param {string} cwd
+ * @param {string} agente — Nombre del agente
+ * @param {string} slice  — Nombre del slice
+ */
+function establecerProximo(cwd, agente, slice) {
+  const estado = leer(cwd);
+  estado.proximoAgente = { agente, slice };
+  escribir(cwd, estado);
+}
+
+/**
+ * Actualiza el contexto compartido entre agentes con merge (no reemplaza).
+ * Los arrays se deduplicam automáticamente.
+ *
+ * @param {string} cwd
+ * @param {object} delta — Campos a fusionar en contextoCompartido
+ */
+function actualizarContexto(cwd, delta) {
+  const estado = leer(cwd);
+  const ctx    = estado.contextoCompartido;
+
+  // Arrays — merge con deduplicación
+  if (Array.isArray(delta.archivosModificados)) {
+    const s = new Set(ctx.archivosModificados);
+    for (const f of delta.archivosModificados) s.add(f);
+    ctx.archivosModificados = [...s];
+  }
+  if (Array.isArray(delta.decisiones)) {
+    const s = new Set(ctx.decisiones);
+    for (const d of delta.decisiones) s.add(d);
+    ctx.decisiones = [...s];
+  }
+  if (Array.isArray(delta.erroresDetectados)) {
+    ctx.erroresDetectados = [...(ctx.erroresDetectados || []), ...delta.erroresDetectados];
+  }
+
+  // Escalares directos
+  if (delta.testsStatus !== undefined) ctx.testsStatus = delta.testsStatus;
+
+  // Campos extra (extensible)
+  for (const [k, v] of Object.entries(delta)) {
+    if (!['archivosModificados', 'decisiones', 'erroresDetectados', 'testsStatus'].includes(k)) {
+      ctx[k] = v;
+    }
+  }
+
+  estado.contextoCompartido = ctx;
+  escribir(cwd, estado);
+}
+
+/**
+ * Elimina el archivo de estado (al completar un plan o al iniciar uno nuevo).
+ *
+ * @param {string} cwd
+ */
+function limpiar(cwd) {
+  try {
+    const ruta = rutaArchivo(cwd);
+    if (fs.existsSync(ruta)) fs.unlinkSync(ruta);
+  } catch (_) {}
+}
+
+/**
+ * Genera un resumen textual del estado para incluir en prompts o en continue-here.md.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+function formatearResumen(cwd) {
+  const estado = leer(cwd);
+  const { planId, fase, agentesEjecutados, proximoAgente, agenteActual, contextoCompartido } = estado;
+
+  if (!agentesEjecutados.length && !agenteActual && !proximoAgente) {
+    return '(sin estado de ejecución activo)';
+  }
+
+  const lineas = [
+    `Plan: ${planId} — Fase: ${fase}`,
+    '',
+    'Agentes completados:',
+    ...(agentesEjecutados.length
+      ? agentesEjecutados.map(a => `  ✓ ${a.agente} / ${a.slice}`)
+      : ['  (ninguno)']),
+  ];
+
+  if (agenteActual) {
+    lineas.push(`  ⟳ ${agenteActual.agente} / ${agenteActual.slice} (en progreso)`);
+  }
+  if (proximoAgente) {
+    lineas.push(`  → ${proximoAgente.agente} / ${proximoAgente.slice} (próximo)`);
+  }
+
+  const ctx = contextoCompartido || {};
+  if (ctx.archivosModificados?.length) {
+    lineas.push('', `Archivos modificados: ${ctx.archivosModificados.join(', ')}`);
+  }
+  if (ctx.decisiones?.length) {
+    lineas.push(`Decisiones: ${ctx.decisiones.join(' | ')}`);
+  }
+  if (ctx.testsStatus && ctx.testsStatus !== 'desconocido') {
+    lineas.push(`Tests: ${ctx.testsStatus}`);
+  }
+
+  return lineas.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  nuevo,
+  leer,
+  escribir,
+  iniciarAgente,
+  completarAgente,
+  establecerProximo,
+  actualizarContexto,
+  limpiar,
+  formatearResumen,
+  rutaArchivo,
+};

package/hooks/lib/fingerprint-id.js

@@ -0,0 +1,135 @@
+/**
+ * fingerprint-id.js — Deduplicación de contenido por hash
+ *
+ * Genera IDs deterministas basados en el contenido para detectar duplicados.
+ * Inspirado en el patrón fingerprintId de agentmemory.
+ * Zero dependencias externas — usa crypto nativo de Node.js.
+ *
+ * Uso:
+ *   const { fingerprintId, isDuplicate, generateId } = require('./fingerprint-id');
+ *   const id = fingerprintId('mem', 'contenido a deduplicar');
+ *   // → "mem_a1b2c3d4e5f6g7h8"
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Genera un ID determinista basado en el contenido (content-addressable).
+ * El mismo contenido siempre produce el mismo ID.
+ *
+ * @param {string} prefix - Prefijo para el ID (ej: 'mem', 'obs', 'learn')
+ * @param {string} content - Contenido a hashear
+ * @param {number} [length=16] - Longitud del hash truncado (max 64)
+ * @returns {string} ID en formato "prefix_hash"
+ */
+function fingerprintId(prefix, content, length) {
+  const len = Math.min(Math.max(length || 16, 4), 64);
+  const hash = crypto
+    .createHash('sha256')
+    .update(content, 'utf8')
+    .digest('hex')
+    .slice(0, len);
+  return prefix + '_' + hash;
+}
+
+/**
+ * Genera un ID único temporal (no determinista).
+ * Combina timestamp en base36 + bytes aleatorios.
+ *
+ * @param {string} prefix - Prefijo para el ID
+ * @returns {string} ID en formato "prefix_timestamp36_random"
+ */
+function generateId(prefix) {
+  const ts = Date.now().toString(36);
+  const rand = crypto.randomBytes(6).toString('hex');
+  return prefix + '_' + ts + '_' + rand;
+}
+
+/**
+ * Verifica si un contenido ya existe en un conjunto de fingerprints.
+ *
+ * @param {string} content - Contenido a verificar
+ * @param {Set<string>|Map<string,*>|Object} knownFingerprints - Conjunto de IDs conocidos
+ * @param {string} [prefix='dup'] - Prefijo para generar el fingerprint
+ * @returns {{ duplicate: boolean, id: string }} Resultado con el ID generado
+ */
+function isDuplicate(content, knownFingerprints, prefix) {
+  const id = fingerprintId(prefix || 'dup', content);
+
+  let exists = false;
+  if (knownFingerprints instanceof Set) {
+    exists = knownFingerprints.has(id);
+  } else if (knownFingerprints instanceof Map) {
+    exists = knownFingerprints.has(id);
+  } else if (typeof knownFingerprints === 'object' && knownFingerprints !== null) {
+    exists = Object.prototype.hasOwnProperty.call(knownFingerprints, id);
+  }
+
+  return { duplicate: exists, id };
+}
+
+/**
+ * Calcula similitud Jaccard entre dos textos (tokenizados por palabras).
+ * Útil para detectar contenido casi-duplicado cuando el hash exacto no coincide.
+ *
+ * @param {string} textA - Primer texto
+ * @param {string} textB - Segundo texto
+ * @returns {number} Similitud entre 0.0 y 1.0
+ */
+function jaccardSimilarity(textA, textB) {
+  const tokenize = (text) => new Set(
+    text.toLowerCase().split(/\s+/).filter(Boolean)
+  );
+  const setA = tokenize(textA);
+  const setB = tokenize(textB);
+
+  if (setA.size === 0 && setB.size === 0) return 1.0;
+  if (setA.size === 0 || setB.size === 0) return 0.0;
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection++;
+  }
+
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0.0 : intersection / union;
+}
+
+/**
+ * Detecta si un contenido es casi-duplicado de alguno existente.
+ * Usa similitud Jaccard con umbral configurable (default: 0.7).
+ *
+ * @param {string} content - Contenido nuevo a verificar
+ * @param {string[]} existingContents - Lista de contenidos existentes
+ * @param {number} [threshold=0.7] - Umbral de similitud (0.0-1.0)
+ * @returns {{ nearDuplicate: boolean, bestMatch: number, similarity: number }}
+ */
+function isNearDuplicate(content, existingContents, threshold) {
+  const thr = typeof threshold === 'number' ? threshold : 0.7;
+  let bestMatch = -1;
+  let bestSimilarity = 0;
+
+  for (let i = 0; i < existingContents.length; i++) {
+    const sim = jaccardSimilarity(content, existingContents[i]);
+    if (sim > bestSimilarity) {
+      bestSimilarity = sim;
+      bestMatch = i;
+    }
+  }
+
+  return {
+    nearDuplicate: bestSimilarity >= thr,
+    bestMatch,
+    similarity: Math.round(bestSimilarity * 1000) / 1000
+  };
+}
+
+module.exports = {
+  fingerprintId,
+  generateId,
+  isDuplicate,
+  jaccardSimilarity,
+  isNearDuplicate
+};

package/hooks/lib/gateway-notify.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Gateway Notify — Helper para encolar notificaciones al gateway multi-plataforma.
+ *
+ * Escribe un archivo JSON en .planning/comms/ que el GatewayRunner consume
+ * mediante polling (ver gateway/index.js _pollComms). Zero-deps, escritura
+ * atómica, opt-in por configuración en manifiestos/gateway-config.json.
+ *
+ * Uso:
+ *   const { notificarGateway } = require('./lib/gateway-notify');
+ *   notificarGateway({ tipo: 'session-stop', titulo: 'Sesión terminada', texto: '...' });
+ *
+ * No bloquea ni lanza: si el gateway está deshabilitado o no hay comms dir,
+ * retorna silenciosamente.
+ *
+ * @module hooks/lib/gateway-notify
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { atomicWriteJSON } = require('./atomic-write');
+
+const COMMS_DIR = '.planning/comms';
+const CONFIG_PATH = 'manifiestos/gateway-config.json';
+
+/**
+ * Verifica si el gateway está habilitado en configuración.
+ * @returns {boolean}
+ */
+function gatewayHabilitado() {
+  try {
+    const cfgPath = path.join(process.cwd(), CONFIG_PATH);
+    if (!fs.existsSync(cfgPath)) return false;
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    return cfg && cfg.enabled === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Verifica si un tipo de notificación está habilitado.
+ * Lee el mapa notifications de gateway-config.json.
+ * @param {string} tipo - session-stop, checkpoint, error, release, build-fail
+ * @returns {boolean}
+ */
+function tipoHabilitado(tipo) {
+  try {
+    const cfgPath = path.join(process.cwd(), CONFIG_PATH);
+    if (!fs.existsSync(cfgPath)) return true;
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    const map = cfg.notifications || {};
+    const claves = {
+      'session-stop': 'onSessionComplete',
+      'checkpoint':   'onCheckpoint',
+      'error':        'onError',
+      'release':      'onRelease',
+      'build-fail':   'onBuildFail',
+    };
+    const clave = claves[tipo];
+    if (!clave) return true;
+    return map[clave] !== false;
+  } catch (_) {
+    return true;
+  }
+}
+
+/**
+ * Encola una notificación para el gateway.
+ * No bloquea ni lanza. Retorna true si se encoló, false si fue descartada.
+ *
+ * @param {object} params
+ * @param {string} params.tipo - session-stop, checkpoint, error, release, build-fail, custom
+ * @param {string} [params.titulo] - Título corto.
+ * @param {string} [params.texto] - Texto del mensaje (soporta Markdown).
+ * @param {string} [params.to='all'] - Destino: 'all', 'telegram', 'discord', etc.
+ * @param {object} [params.payload] - Payload adicional para el adaptador.
+ * @returns {boolean}
+ */
+function notificarGateway(params) {
+  try {
+    if (!gatewayHabilitado()) return false;
+    if (!tipoHabilitado(params.tipo)) return false;
+
+    const commsDir = path.join(process.cwd(), COMMS_DIR);
+    if (!fs.existsSync(commsDir)) {
+      fs.mkdirSync(commsDir, { recursive: true });
+    }
+
+    const id = `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const msg = {
+      id,
+      type:   'gateway_notification',
+      from:   'swl-system',
+      to:     params.to || 'all',
+      payload: {
+        tipo:   params.tipo,
+        titulo: params.titulo || '',
+        texto:  params.texto  || '',
+        ...(params.payload || {}),
+      },
+      text: params.texto || '',
+      timestamp: new Date().toISOString(),
+      status: 'pending',
+    };
+
+    const filePath = path.join(commsDir, `${id}.json`);
+    atomicWriteJSON(filePath, msg);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { notificarGateway, gatewayHabilitado, tipoHabilitado };

package/hooks/lib/graph-security.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * graph-security.js — Utilidades de seguridad para el grafo de dependencias SWL.
+ *
+ * Portado desde graphify-3/graphify/security.py (validate_graph_path, sanitize_label).
+ * Zero-dependencies: solo módulos nativos de Node.js.
+ *
+ * API:
+ *   validateGraphPath(filePath, allowedRoot) → resolvedPath (string) | throws Error
+ *   sanitizeLabel(text, maxLen?)            → string
+ *
+ * @module hooks/lib/graph-security
+ */
+
+const path = require('path');
+const fs   = require('fs');
+
+const MAX_LABEL_LEN    = 256;
+const CONTROL_CHAR_RE  = /[\x00-\x1f\x7f]/g;
+
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resuelve `filePath` y verifica que permanezca dentro de `allowedRoot`.
+ * Previene path traversal cuando se leen archivos del grafo desde fuentes externas.
+ *
+ * @param {string} filePath    - Ruta a validar (absoluta o relativa)
+ * @param {string} allowedRoot - Directorio raíz permitido (ej: process.cwd())
+ * @returns {string} Ruta resuelta y validada
+ * @throws {Error} Si la ruta escapa del directorio permitido o no existe
+ */
+function validateGraphPath(filePath, allowedRoot) {
+  const root     = path.resolve(allowedRoot);
+  const resolved = path.resolve(filePath);
+
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    throw new Error(
+      `[graph-security] Ruta "${filePath}" escapa del directorio permitido "${root}". ` +
+      'Solo rutas dentro del proyecto están permitidas.'
+    );
+  }
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`[graph-security] Ruta no encontrada: "${resolved}"`);
+  }
+
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Label sanitisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Elimina caracteres de control y limita longitud del texto.
+ * Seguro para embeber en JSON y texto plano.
+ *
+ * @param {string} text
+ * @param {number} [maxLen=256]
+ * @returns {string}
+ */
+function sanitizeLabel(text, maxLen = MAX_LABEL_LEN) {
+  const clean = String(text).replace(CONTROL_CHAR_RE, '');
+  return clean.length > maxLen ? clean.slice(0, maxLen) : clean;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { validateGraphPath, sanitizeLabel };