@saulwade/swl-ses 1.0.0

package/hooks/lib/nudge-tracker.js

@@ -0,0 +1,306 @@
+'use strict';
+
+/**
+ * Nudge Tracker — Ciclo de vida de los nudges del sistema SWL.
+ *
+ * Un "nudge" es un mensaje que un hook emite por stderr sugiriendo una acción
+ * al modelo o al usuario (ej: "invoca perfilador-usuario-swl", "ejecuta
+ * /swl:evolucionar X"). Sin trackear, los nudges ignorados se pierden
+ * silenciosamente — el sistema parece dar sugerencias pero no sabe si alguien
+ * las accionó.
+ *
+ * Este módulo centraliza:
+ *   - emit(kind, target, payload)  → registra nudge en JSONL append-only
+ *   - markAccionado(id)            → marca que fue accionado (llamado por el consumer)
+ *   - escalar(kind, target)        → si >= N nudges del mismo tipo sin accionar,
+ *                                    escribe una alerta persistente
+ *   - resumen()                    → estadísticas por tipo/target
+ *
+ * Zero-deps. Append-only para eventos, atomic-write para alertas.
+ *
+ * @module hooks/lib/nudge-tracker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+
+const DIR_EVOL = path.join(process.cwd(), '.planning', 'evolucion');
+const LOG_PATH = path.join(DIR_EVOL, 'nudges.jsonl');
+const ALERT_PATH = path.join(DIR_EVOL, 'alertas-persistentes.json');
+
+/** Umbral por defecto para escalar a alerta persistente. */
+const DEFAULT_ESCALATION_THRESHOLD = 5;
+
+/** Ventana de "recientes" para decidir escalamiento (ms). */
+const WINDOW_MS = 14 * 24 * 3600 * 1000; // 14 días
+
+// ---------------------------------------------------------------------------
+// Utilidades
+// ---------------------------------------------------------------------------
+
+function ensureDir() {
+  try { fs.mkdirSync(DIR_EVOL, { recursive: true }); } catch { /* ignore */ }
+}
+
+function genId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+function leerLog() {
+  try {
+    return fs.readFileSync(LOG_PATH, 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+/**
+ * Categorías de mutación según intent del cambio propuesto.
+ * Patrón adaptado de evolver GEP (temp/evolver-main/src/gep/mutation.js).
+ *
+ * - repair:   corrige un bug o regresión ya observada (retrospectivo)
+ * - optimize: mejora performance, claridad o cobertura sin corregir bug
+ * - innovate: añade capacidad nueva no cubierta antes (prospectivo)
+ */
+const MUTATION_CATEGORIES = Object.freeze(['repair', 'optimize', 'innovate']);
+
+/**
+ * Nivel de riesgo de aplicar la mutación sugerida.
+ *
+ * - low:    cambio autocontenido, reversible, bajo impacto (ej: doc, comment)
+ * - medium: cambio en 1-2 módulos, reversible con git revert
+ * - high:   cambio estructural, afecta múltiples módulos o interfaces públicas
+ */
+const RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
+
+/**
+ * Emite y registra un nudge.
+ *
+ * @param {object} opts
+ * @param {string} opts.kind                 - Tipo de nudge (ej: 'perfil-usuario', 'auto-evolucion').
+ * @param {string} opts.target               - Sujeto (ej: nombre de agente, skill, componente).
+ * @param {string} opts.message              - Texto sugerido (solo para log; el hook caller emite a stderr).
+ * @param {string} [opts.source]             - Hook o agente que lo emitió.
+ * @param {object} [opts.data]               - Payload adicional.
+ * @param {string} [opts.mutation_category]  - 'repair' | 'optimize' | 'innovate' (ver MUTATION_CATEGORIES).
+ * @param {string} [opts.risk_level]         - 'low' | 'medium' | 'high' (ver RISK_LEVELS).
+ * @returns {{ id: string, ts: string }}
+ */
+function emit(opts) {
+  ensureDir();
+
+  // Validar mutation_category y risk_level si se proveen (silencioso: si vienen
+  // con valor desconocido, se normaliza a undefined en lugar de crashear).
+  const mutationCategory = opts.mutation_category && MUTATION_CATEGORIES.includes(opts.mutation_category)
+    ? opts.mutation_category
+    : undefined;
+  const riskLevel = opts.risk_level && RISK_LEVELS.includes(opts.risk_level)
+    ? opts.risk_level
+    : undefined;
+
+  const entry = {
+    id:        genId(),
+    kind:      String(opts.kind || 'unknown'),
+    target:    String(opts.target || ''),
+    source:    String(opts.source || ''),
+    message:   String(opts.message || ''),
+    data:      opts.data || {},
+    ts:        new Date().toISOString(),
+    accionado: false,
+    accionado_ts: null,
+    accionado_por: null,
+  };
+  if (mutationCategory) entry.mutation_category = mutationCategory;
+  if (riskLevel) entry.risk_level = riskLevel;
+
+  try {
+    fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + '\n', 'utf8');
+  } catch { /* silencioso */ }
+  return { id: entry.id, ts: entry.ts };
+}
+
+/**
+ * Marca un nudge como accionado. El consumer (comando, agente) llama a esto
+ * cuando toma la acción sugerida.
+ *
+ * @param {string} id         - ID retornado por emit().
+ * @param {string} [by]       - Quién lo accionó ('usuario', 'auto', nombre del agente).
+ * @returns {boolean}         - true si se encontró y marcó.
+ */
+function markAccionado(id, by = 'desconocido') {
+  const entries = leerLog();
+  const idx = entries.findIndex(e => e.id === id);
+  if (idx === -1) return false;
+
+  entries[idx].accionado = true;
+  entries[idx].accionado_ts = new Date().toISOString();
+  entries[idx].accionado_por = String(by);
+
+  // Reescribimos el JSONL completo (compromiso vs append-only: el marcado de
+  // accionado es raro comparado con emit, vale la pena para claridad).
+  ensureDir();
+  const lines = entries.map(e => JSON.stringify(e)).join('\n') + '\n';
+  try {
+    fs.writeFileSync(LOG_PATH, lines, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Calcula estadísticas de nudges en la ventana reciente y escala si corresponde.
+ *
+ * Si hay >= threshold nudges del mismo (kind, target) sin accionar en la
+ * ventana, escribe una alerta persistente en alertas-persistentes.json.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.threshold=5]
+ * @returns {{ alertasNuevas: number, totalAlertas: number }}
+ */
+function escalarSiAplica(opts = {}) {
+  const threshold = opts.threshold || DEFAULT_ESCALATION_THRESHOLD;
+  const limite = Date.now() - WINDOW_MS;
+  const entries = leerLog().filter(e => {
+    const t = Date.parse(e.ts);
+    return Number.isFinite(t) && t >= limite && !e.accionado;
+  });
+
+  // Agrupar por (kind, target)
+  const buckets = {};
+  for (const e of entries) {
+    const key = `${e.kind}::${e.target}`;
+    if (!buckets[key]) buckets[key] = [];
+    buckets[key].push(e);
+  }
+
+  // Leer alertas existentes
+  let alertas = {};
+  try {
+    alertas = JSON.parse(fs.readFileSync(ALERT_PATH, 'utf8'));
+  } catch { alertas = {}; }
+
+  let alertasNuevas = 0;
+  for (const [key, lista] of Object.entries(buckets)) {
+    if (lista.length >= threshold) {
+      const [kind, target] = key.split('::');
+      const prevAlerta = alertas[key];
+      if (!prevAlerta || prevAlerta.count < lista.length) {
+        alertas[key] = {
+          kind,
+          target,
+          count: lista.length,
+          primera: lista[0].ts,
+          ultima: lista[lista.length - 1].ts,
+          mensaje: `${lista.length} nudges tipo "${kind}" para "${target}" ignorados en 14 días`,
+          estado: 'activa',
+        };
+        if (!prevAlerta) alertasNuevas++;
+      }
+    }
+  }
+
+  ensureDir();
+  try {
+    atomicWriteJSON(ALERT_PATH, alertas);
+  } catch { /* silencioso */ }
+
+  return {
+    alertasNuevas,
+    totalAlertas: Object.values(alertas).filter(a => a.estado === 'activa').length,
+  };
+}
+
+/**
+ * Resumen de nudges para el comando /swl:evolucion-estado.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.dias=14]
+ * @returns {object} estadísticas agregadas
+ */
+function resumen(opts = {}) {
+  const dias = opts.dias || 14;
+  const limite = Date.now() - dias * 24 * 3600 * 1000;
+  const entries = leerLog().filter(e => {
+    const t = Date.parse(e.ts);
+    return Number.isFinite(t) && t >= limite;
+  });
+
+  const total = entries.length;
+  const accionados = entries.filter(e => e.accionado).length;
+  const pendientes = total - accionados;
+
+  const porKind = {};
+  for (const e of entries) {
+    if (!porKind[e.kind]) porKind[e.kind] = { total: 0, accionados: 0 };
+    porKind[e.kind].total++;
+    if (e.accionado) porKind[e.kind].accionados++;
+  }
+
+  let alertas = {};
+  try {
+    alertas = JSON.parse(fs.readFileSync(ALERT_PATH, 'utf8'));
+  } catch { alertas = {}; }
+  const alertasActivas = Object.values(alertas).filter(a => a.estado === 'activa');
+
+  return {
+    ventanaDias: dias,
+    total,
+    accionados,
+    pendientes,
+    tasaAccion: total > 0 ? Math.round(accionados / total * 100) / 100 : null,
+    porKind,
+    alertasActivas,
+  };
+}
+
+/**
+ * Resuelve una alerta (cuando el tipo de nudge ya se accionó o se descartó).
+ */
+function resolverAlerta(kind, target, razon = 'resuelta') {
+  const key = `${kind}::${target}`;
+  let alertas = {};
+  try {
+    alertas = JSON.parse(fs.readFileSync(ALERT_PATH, 'utf8'));
+  } catch { return false; }
+  if (!alertas[key]) return false;
+  alertas[key].estado = 'resuelta';
+  alertas[key].resuelta_ts = new Date().toISOString();
+  alertas[key].razon = razon;
+  ensureDir();
+  try {
+    atomicWriteJSON(ALERT_PATH, alertas);
+    return true;
+  } catch { return false; }
+}
+
+module.exports = {
+  emit,
+  markAccionado,
+  escalarSiAplica,
+  resumen,
+  resolverAlerta,
+  MUTATION_CATEGORIES,
+  RISK_LEVELS,
+  _paths: { LOG_PATH, ALERT_PATH, DIR_EVOL },
+};

package/hooks/lib/otlp-exporter.js

@@ -0,0 +1,365 @@
+'use strict';
+
+/**
+ * OTLP Exporter — Exportador de trazas compatible con OpenTelemetry.
+ * Zero-deps. Solo módulos nativos de Node.js.
+ *
+ * Almacena trazas en .planning/traces/YYYY-MM-DD.jsonl (append-only).
+ * Exportación opcional a endpoint HTTP/HTTPS vía variable OTLP_ENDPOINT.
+ *
+ * Formato de traza (OTLP-lite):
+ *   { traceId, spanId, nombre, inicio, fin, duracionMs, estado, atributos }
+ *
+ * Desde v2.0.0 expone también la clase OtlpLocalProcessor que implementa
+ * la interfaz TracingProcessor (scripts/lib/tracing-processor-interface.js).
+ * Las funciones sueltas originales (crearSpan, finalizarSpan, etc.) se
+ * mantienen como wrappers delgados para preservar compatibilidad hacia atrás.
+ *
+ * @module hooks/lib/otlp-exporter
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const http   = require('http');
+const https  = require('https');
+
+// Carga la interfaz TracingProcessor con try/catch para robustez:
+// si el archivo no existe (entorno degradado) las funciones sueltas
+// siguen funcionando igual que antes.
+let TracingProcessor;
+try {
+  ({ TracingProcessor } = require('../../scripts/lib/tracing-processor-interface'));
+} catch (_) {
+  // Fallback: clase vacía que no rompe la herencia en OtlpLocalProcessor
+  TracingProcessor = class TracingProcessorFallback {};
+}
+
+const TRACES_DIR = '.planning/traces';
+
+// ---------------------------------------------------------------------------
+// Generadores de IDs
+// ---------------------------------------------------------------------------
+
+/**
+ * Genera un trace ID de 32 caracteres hexadecimales (128 bits).
+ * @returns {string}
+ */
+function generarTraceId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+/**
+ * Genera un span ID de 16 caracteres hexadecimales (64 bits).
+ * @returns {string}
+ */
+function generarSpanId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Persistencia
+// ---------------------------------------------------------------------------
+
+/**
+ * Asegura que el directorio de trazas exista.
+ * @param {string} cwd - Directorio raíz del proyecto.
+ * @returns {string} Ruta absoluta al directorio.
+ */
+function asegurarDirectorio(cwd) {
+  const dir = path.join(cwd, TRACES_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Ruta del archivo JSONL para la fecha actual (YYYY-MM-DD.jsonl).
+ * @param {string} cwd
+ * @returns {string}
+ */
+function rutaHoy(cwd) {
+  const fecha = new Date().toISOString().slice(0, 10);
+  return path.join(asegurarDirectorio(cwd), `${fecha}.jsonl`);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Crea un nuevo span (inicio de una operación a medir).
+ *
+ * @param {string} nombre - Nombre de la operación (ej. "agent:revisor-codigo-swl").
+ * @param {object} [atributos] - Metadatos adicionales clave-valor.
+ * @returns {{ traceId: string, spanId: string, nombre: string, inicio: string, atributos: object }}
+ */
+function crearSpan(nombre, atributos = {}) {
+  return {
+    traceId:   generarTraceId(),
+    spanId:    generarSpanId(),
+    nombre:    String(nombre),
+    inicio:    new Date().toISOString(),
+    atributos: { ...atributos },
+  };
+}
+
+/**
+ * Finaliza un span y lo escribe al archivo JSONL del día.
+ * También envía al endpoint OTLP si OTLP_ENDPOINT está definido.
+ *
+ * @param {string} cwd - Directorio raíz del proyecto.
+ * @param {object} span - Span creado con crearSpan().
+ * @param {object} [atributosExtra] - Atributos adicionales (resultado, error, etc.).
+ * @param {'OK'|'ERROR'} [estado] - Estado de la operación.
+ * @returns {object} Traza completa.
+ */
+function finalizarSpan(cwd, span, atributosExtra = {}, estado = 'OK') {
+  const fin      = new Date().toISOString();
+  const inicioMs = new Date(span.inicio).getTime();
+  const finMs    = new Date(fin).getTime();
+
+  const traza = {
+    traceId:    span.traceId,
+    spanId:     span.spanId,
+    nombre:     span.nombre,
+    inicio:     span.inicio,
+    fin,
+    duracionMs: finMs - inicioMs,
+    estado,
+    atributos:  { ...span.atributos, ...atributosExtra },
+  };
+
+  // Persistir en JSONL (append-only, sin escritura atómica para no bloquear)
+  try {
+    fs.appendFileSync(rutaHoy(cwd), JSON.stringify(traza) + '\n', 'utf8');
+  } catch (_) {
+    // Silencioso — la telemetría no debe interrumpir la sesión
+  }
+
+  exportarAsync(traza);
+  return traza;
+}
+
+/**
+ * Registra una traza completa de forma instantánea (sin inicio/fin separados).
+ * Útil para eventos puntuales donde la duración no importa.
+ *
+ * @param {string} cwd
+ * @param {string} nombre
+ * @param {object} [atributos]
+ * @param {'OK'|'ERROR'} [estado]
+ * @returns {object} Traza registrada.
+ */
+function registrar(cwd, nombre, atributos = {}, estado = 'OK') {
+  const span = crearSpan(nombre, atributos);
+  return finalizarSpan(cwd, span, {}, estado);
+}
+
+/**
+ * Envía la traza a un endpoint HTTP/HTTPS de forma asíncrona (fire-and-forget).
+ * Solo se activa si la variable de entorno OTLP_ENDPOINT está definida.
+ *
+ * @param {object} traza
+ */
+function exportarAsync(traza) {
+  const endpoint = process.env.OTLP_ENDPOINT;
+  if (!endpoint) return;
+
+  try {
+    const body   = JSON.stringify(traza);
+    const url    = new URL(endpoint);
+    const modulo = url.protocol === 'https:' ? https : http;
+    const opts   = {
+      hostname: url.hostname,
+      port:     url.port || (url.protocol === 'https:' ? 443 : 80),
+      path:     url.pathname + (url.search || ''),
+      method:   'POST',
+      headers:  {
+        'Content-Type':   'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    };
+
+    const req = modulo.request(opts);
+    req.on('error', () => {}); // Silencioso
+    req.write(body);
+    req.end();
+  } catch (_) {
+    // Silencioso
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lectura de trazas
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee y parsea las trazas del día actual.
+ *
+ * @param {string} cwd
+ * @returns {object[]} Array de objetos de traza (puede estar vacío).
+ */
+function leerHoy(cwd) {
+  try {
+    return fs.readFileSync(rutaHoy(cwd), 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(l => JSON.parse(l));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Lee y parsea las trazas de una fecha específica.
+ *
+ * @param {string} cwd
+ * @param {string} fecha - Formato YYYY-MM-DD.
+ * @returns {object[]}
+ */
+function leerFecha(cwd, fecha) {
+  try {
+    const filePath = path.join(asegurarDirectorio(cwd), `${fecha}.jsonl`);
+    return fs.readFileSync(filePath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(l => JSON.parse(l));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Genera un resumen de trazas del día: total, por nombre, por estado.
+ *
+ * @param {string} cwd
+ * @returns {{ total: number, porNombre: object, errores: number }}
+ */
+function resumenHoy(cwd) {
+  const trazas    = leerHoy(cwd);
+  const porNombre = {};
+  let errores     = 0;
+
+  for (const t of trazas) {
+    porNombre[t.nombre] = (porNombre[t.nombre] || 0) + 1;
+    if (t.estado === 'ERROR') errores++;
+  }
+
+  return { total: trazas.length, porNombre, errores };
+}
+
+// ---------------------------------------------------------------------------
+// OtlpLocalProcessor — implementación de TracingProcessor
+// ---------------------------------------------------------------------------
+
+/**
+ * Procesador OTLP local que implementa la interfaz TracingProcessor.
+ *
+ * Encapsula la lógica de persistencia JSONL existente bajo el contrato
+ * formal de TracingProcessor, permitiendo su uso con MultiProcessor y
+ * otros exportadores compuestos.
+ *
+ * Compatibilidad hacia atrás: las funciones sueltas del módulo (crearSpan,
+ * finalizarSpan, etc.) siguen funcionando y delegan en esta misma lógica.
+ *
+ * @extends TracingProcessor
+ *
+ * @example
+ * const procesador = new OtlpLocalProcessor('/ruta/proyecto');
+ * procesador.onSpanEnd(span); // persiste en .planning/traces/YYYY-MM-DD.jsonl
+ */
+class OtlpLocalProcessor extends TracingProcessor {
+  /**
+   * @param {string} cwd - Directorio raíz del proyecto.
+   */
+  constructor(cwd) {
+    super();
+    /** @type {string} */
+    this._cwd = String(cwd || process.cwd());
+  }
+
+  /**
+   * Invocado al iniciar una traza. Sin efecto en persistencia local;
+   * el registro ocurre al finalizar spans individuales.
+   *
+   * @param {object} traza
+   */
+  onTraceStart(traza) { // eslint-disable-line no-unused-vars
+    // Sin persistencia en inicio de traza — la traza se reconstruye desde spans
+  }
+
+  /**
+   * Invocado al finalizar una traza. Cierra cualquier buffer asociado.
+   * En el exportador local no hay buffer de traza activo, por lo que
+   * esta operación es un no-op con efecto de flush implícito.
+   *
+   * @param {object} traza
+   */
+  onTraceEnd(traza) { // eslint-disable-line no-unused-vars
+    // No-op: el JSONL es append-only y no requiere cierre de traza
+  }
+
+  /**
+   * Invocado al iniciar un span. Sin persistencia en el exportador local;
+   * los spans incompletos no se registran.
+   *
+   * @param {object} span
+   */
+  onSpanStart(span) { // eslint-disable-line no-unused-vars
+    // Sin persistencia en inicio de span
+  }
+
+  /**
+   * Invocado al finalizar un span. Persiste el span en el archivo JSONL
+   * del día actual y dispara exportación HTTP asíncrona si aplica.
+   *
+   * @param {object} span - Span completo con al menos { traceId, spanId, nombre,
+   *   inicio, fin, duracionMs, estado, atributos }.
+   */
+  onSpanEnd(span) {
+    try {
+      fs.appendFileSync(
+        rutaHoy(this._cwd),
+        JSON.stringify(span) + '\n',
+        'utf8'
+      );
+    } catch (_) {
+      // La telemetría no debe interrumpir la sesión
+    }
+    exportarAsync(span);
+  }
+
+  /**
+   * Cierre limpio del procesador. El JSONL es append-only y no requiere
+   * flush explícito; este método existe para cumplir el contrato de la interfaz.
+   */
+  shutdown() {
+    // No-op: no hay buffers ni conexiones persistentes que cerrar
+  }
+
+  /**
+   * Fuerza el volcado de buffers pendientes. Sin buffers internos en el
+   * exportador local — operación garantizada como no-op seguro.
+   */
+  forceFlush() {
+    // No-op: escrituras son síncronas (appendFileSync)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  // API original — compatibilidad hacia atrás garantizada
+  crearSpan,
+  finalizarSpan,
+  registrar,
+  leerHoy,
+  leerFecha,
+  resumenHoy,
+  // Nueva clase TracingProcessor
+  OtlpLocalProcessor,
+};