@saulwade/swl-ses 2.6.0 → 2.8.0

package/hooks/lib/gateway-notify.js

@@ -1,193 +1,193 @@
-'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 { raizProyecto } = require('./raiz-proyecto');
-const path = require('path');
-const { atomicWriteJSON } = require('./atomic-write');
-
-// Deep links opt-in (ADR-0029). Si el módulo no carga (instalación incompleta),
-// el enriquecimiento se omite silenciosamente — comportamiento default sin
-// cambios respecto a versiones previas.
-let construirDeepLink, formatearEnlace;
-try {
-  ({ construirDeepLink, formatearEnlace } = require('./deep-links'));
-} catch {
-  construirDeepLink = () => null;
-  formatearEnlace   = (_, etiqueta) => etiqueta;
-}
-
-const COMMS_DIR = '.planning/comms';
-const CONFIG_PATH = 'manifiestos/gateway-config.json';
-
-// Memo de la raíz del proyecto POR cwd: una notificación consulta config +
-// comms en la misma invocación — sin memo el walk ascendente de raizProyecto
-// se repetiría 3 veces con su I/O de existsSync. La clave por cwd evita
-// congelar la raíz cuando el proceso cambia de directorio (tests, daemons).
-let _raizCache = null;
-function raizBase() {
-  const cwd = process.cwd();
-  if (!_raizCache || _raizCache.cwd !== cwd) {
-    _raizCache = { cwd, raiz: raizProyecto(cwd) };
-  }
-  return _raizCache.raiz;
-}
-
-/** Receptores reconocidos para formato de deep link. */
-const RECEPTORES = new Set(['telegram', 'discord', 'slack', 'email', 'plain']);
-
-/**
- * Verifica si el gateway está habilitado en configuración.
- * @returns {boolean}
- */
-function gatewayHabilitado() {
-  try {
-    const cfgPath = path.join(raizBase(), 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(raizBase(), 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;
-  }
-}
-
-/**
- * Si el payload incluye `fileRef` + `idePreferido`, retorna el enlace
- * formateado al receptor; en otro caso retorna null. No modifica el payload.
- *
- * Estructura esperada del payload (opt-in, ADR-0029):
- *   payload.fileRef = {
- *     archivo: '/abs/path/al/archivo.js',
- *     linea?: 42,
- *     columna?: 8,
- *     etiqueta?: 'Abrir archivo.js:42',   // default: archivo:linea
- *     proyecto?: 'mi-proyecto',           // requerido solo para JetBrains
- *   }
- *   payload.idePreferido = 'vscode' | 'cursor' | ...
- *
- * @param {object} payload
- * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
- * @returns {string|null}
- * @private
- */
-function _construirEnlaceFileRef(payload, receptor) {
-  if (!payload || !payload.fileRef || !payload.idePreferido) return null;
-  const { archivo, linea, columna, etiqueta, proyecto } = payload.fileRef;
-  if (!archivo) return null;
-
-  const url = construirDeepLink({
-    ide: payload.idePreferido,
-    rutaAbsoluta: archivo,
-    linea,
-    columna,
-    proyecto,
-  });
-
-  const label = etiqueta || (linea ? `${path.basename(archivo)}:${linea}` : path.basename(archivo));
-  const formato = RECEPTORES.has(receptor) ? receptor : 'plain';
-  return formatearEnlace(url, label, formato);
-}
-
-/**
- * Encola una notificación para el gateway.
- * No bloquea ni lanza. Retorna true si se encoló, false si fue descartada.
- *
- * Enriquecimiento opt-in (ADR-0029): si `params.payload.fileRef` +
- * `params.payload.idePreferido` están presentes, el mensaje agrega el campo
- * `enlace` con un deep link formateado al receptor. Sin esos campos, el
- * comportamiento es idéntico al previo (compatibilidad hacia atrás).
- *
- * @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(raizBase(), 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 receptor = params.to || 'all';
-    const payloadBase = {
-      tipo:   params.tipo,
-      titulo: params.titulo || '',
-      texto:  params.texto  || '',
-      ...(params.payload || {}),
-    };
-
-    // Enriquecimiento opt-in con deep link (ADR-0029).
-    const enlace = _construirEnlaceFileRef(payloadBase, receptor);
-    if (enlace) payloadBase.enlace = enlace;
-
-    const msg = {
-      id,
-      type:   'gateway_notification',
-      from:   'swl-system',
-      to:     receptor,
-      payload: payloadBase,
-      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 };
+'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 { raizProyecto } = require('./raiz-proyecto');
+const path = require('path');
+const { atomicWriteJSON } = require('./atomic-write');
+
+// Deep links opt-in (ADR-0029). Si el módulo no carga (instalación incompleta),
+// el enriquecimiento se omite silenciosamente — comportamiento default sin
+// cambios respecto a versiones previas.
+let construirDeepLink, formatearEnlace;
+try {
+  ({ construirDeepLink, formatearEnlace } = require('./deep-links'));
+} catch {
+  construirDeepLink = () => null;
+  formatearEnlace   = (_, etiqueta) => etiqueta;
+}
+
+const COMMS_DIR = '.planning/comms';
+const CONFIG_PATH = 'manifiestos/gateway-config.json';
+
+// Memo de la raíz del proyecto POR cwd: una notificación consulta config +
+// comms en la misma invocación — sin memo el walk ascendente de raizProyecto
+// se repetiría 3 veces con su I/O de existsSync. La clave por cwd evita
+// congelar la raíz cuando el proceso cambia de directorio (tests, daemons).
+let _raizCache = null;
+function raizBase() {
+  const cwd = process.cwd();
+  if (!_raizCache || _raizCache.cwd !== cwd) {
+    _raizCache = { cwd, raiz: raizProyecto(cwd) };
+  }
+  return _raizCache.raiz;
+}
+
+/** Receptores reconocidos para formato de deep link. */
+const RECEPTORES = new Set(['telegram', 'discord', 'slack', 'email', 'plain']);
+
+/**
+ * Verifica si el gateway está habilitado en configuración.
+ * @returns {boolean}
+ */
+function gatewayHabilitado() {
+  try {
+    const cfgPath = path.join(raizBase(), 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(raizBase(), 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;
+  }
+}
+
+/**
+ * Si el payload incluye `fileRef` + `idePreferido`, retorna el enlace
+ * formateado al receptor; en otro caso retorna null. No modifica el payload.
+ *
+ * Estructura esperada del payload (opt-in, ADR-0029):
+ *   payload.fileRef = {
+ *     archivo: '/abs/path/al/archivo.js',
+ *     linea?: 42,
+ *     columna?: 8,
+ *     etiqueta?: 'Abrir archivo.js:42',   // default: archivo:linea
+ *     proyecto?: 'mi-proyecto',           // requerido solo para JetBrains
+ *   }
+ *   payload.idePreferido = 'vscode' | 'cursor' | ...
+ *
+ * @param {object} payload
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string|null}
+ * @private
+ */
+function _construirEnlaceFileRef(payload, receptor) {
+  if (!payload || !payload.fileRef || !payload.idePreferido) return null;
+  const { archivo, linea, columna, etiqueta, proyecto } = payload.fileRef;
+  if (!archivo) return null;
+
+  const url = construirDeepLink({
+    ide: payload.idePreferido,
+    rutaAbsoluta: archivo,
+    linea,
+    columna,
+    proyecto,
+  });
+
+  const label = etiqueta || (linea ? `${path.basename(archivo)}:${linea}` : path.basename(archivo));
+  const formato = RECEPTORES.has(receptor) ? receptor : 'plain';
+  return formatearEnlace(url, label, formato);
+}
+
+/**
+ * Encola una notificación para el gateway.
+ * No bloquea ni lanza. Retorna true si se encoló, false si fue descartada.
+ *
+ * Enriquecimiento opt-in (ADR-0029): si `params.payload.fileRef` +
+ * `params.payload.idePreferido` están presentes, el mensaje agrega el campo
+ * `enlace` con un deep link formateado al receptor. Sin esos campos, el
+ * comportamiento es idéntico al previo (compatibilidad hacia atrás).
+ *
+ * @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(raizBase(), 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 receptor = params.to || 'all';
+    const payloadBase = {
+      tipo:   params.tipo,
+      titulo: params.titulo || '',
+      texto:  params.texto  || '',
+      ...(params.payload || {}),
+    };
+
+    // Enriquecimiento opt-in con deep link (ADR-0029).
+    const enlace = _construirEnlaceFileRef(payloadBase, receptor);
+    if (enlace) payloadBase.enlace = enlace;
+
+    const msg = {
+      id,
+      type:   'gateway_notification',
+      from:   'swl-system',
+      to:     receptor,
+      payload: payloadBase,
+      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/mcp-health.js

@@ -17,7 +17,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./raiz-proyecto');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 const os = require('os');
 

package/hooks/lib/notificacion-formato.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * notificacion-formato.js — Formato del cuerpo de las notificaciones.
+ *
+ * Módulo sin efectos secundarios (solo funciones puras), separado del hook
+ * `notificacion-telegram.js` para poder unit-testearlo sin disparar el `run()`
+ * del hook (que se ejecuta al `require`, porque los hooks se invocan vía el
+ * wrapper `node -e "require('./hooks/X.js')"` — no admiten gate de entrypoint).
+ *
+ * Zero-deps.
+ *
+ * @module hooks/lib/notificacion-formato
+ */
+
+/**
+ * Prepara el último mensaje del asistente para una notificación de Telegram:
+ * limpia el ruido de markdown que Telegram no renderiza (fences de código, filas
+ * de tabla, reglas horizontales) y el markdown inline (negritas, itálicas,
+ * código, enlaces, viñetas), preservando el TEXTO COMPLETO. Solo trunca mensajes
+ * ENORMES que no caben en Telegram (~3500 chars el mensaje completo con el
+ * wrapper), y en ese caso corta en un límite natural (fin de línea u oración),
+ * nunca a media palabra. El default alto evita el corte agresivo previo (400
+ * chars) que dejaba mensajes útiles truncados (feedback 2026-07-15).
+ *
+ * @param {string} texto - Mensaje completo del asistente (markdown).
+ * @param {number} [maxChars=3300] - Largo máximo del cuerpo (deja margen para el
+ *   título/labels dentro del límite de 3500 del cliente Telegram).
+ * @returns {string} Texto limpio (completo salvo mensajes enormes).
+ */
+function resumirParaNotificacion(texto, maxChars = 3300) {
+  if (!texto) return '';
+  const limpias = [];
+  let enFence = false;
+  for (const raw of String(texto).split(/\r?\n/)) {
+    const l = raw.trim();
+    if (/^```/.test(l)) { enFence = !enFence; continue; } // abre/cierra bloque de código
+    if (enFence) continue;                                 // omitir contenido de código
+    if (/^\|.*\|$/.test(l)) continue;                      // omitir filas de tabla
+    if (/^[-=_*]{3,}$/.test(l)) continue;                  // omitir reglas horizontales
+    if (l === '') {
+      if (limpias.length && limpias[limpias.length - 1] !== '') limpias.push('');
+      continue;
+    }
+    const t = l
+      .replace(/^#{1,6}\s+/, '')                 // encabezados
+      .replace(/^>\s?/, '')                      // citas
+      .replace(/^[-*+]\s+/, '• ')                // viñetas → •
+      .replace(/^\d+\.\s+/, '')                  // listas numeradas
+      .replace(/\*\*([^*]+)\*\*/g, '$1')         // negritas
+      .replace(/(^|[^*])\*([^*]+)\*/g, '$1$2')   // itálicas
+      .replace(/`([^`]+)`/g, '$1')               // código inline
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');  // enlaces → texto
+    limpias.push(t);
+  }
+  const resumen = limpias.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+  if (resumen.length <= maxChars) return resumen;
+  // Mensaje enorme: cortar en el último límite natural antes de maxChars.
+  const corte = resumen.slice(0, maxChars - 1);
+  const limite = Math.max(
+    corte.lastIndexOf('\n'),
+    corte.lastIndexOf('. '),
+    corte.lastIndexOf('! '),
+    corte.lastIndexOf('? ')
+  );
+  const base = limite > (maxChars - 1) * 0.6 ? corte.slice(0, limite + 1) : corte;
+  return base.trimEnd() + '…';
+}
+
+/**
+ * Clasifica el `message` de un evento Notification de Claude Code y devuelve
+ * subtítulo + cuerpo EN ESPAÑOL (regla es-MX de brevedad-output). El mensaje
+ * nativo de Claude Code viene en inglés ("Claude needs your permission",
+ * "Claude is waiting for your input"); volcarlo crudo mezclaba idiomas en la
+ * notificación (bug 2026-07-15). Se detecta la categoría por keyword (en/es) y
+ * se emite texto es-MX propio, nunca el `message` inglés.
+ *
+ * @param {string} mensaje - evt.message del evento Notification (puede venir en inglés).
+ * @returns {{subtitulo: string, cuerpo: string}} Ambos en español.
+ */
+function clasificarNotificacion(mensaje) {
+  const m = String(mensaje || '').toLowerCase();
+  if (m.includes('permission') || m.includes('permiso')) {
+    return { subtitulo: 'Permisos pendientes', cuerpo: 'Claude necesita tu permiso para continuar.' };
+  }
+  if (m.includes('idle') || m.includes('waiting') || m.includes('esperando')) {
+    return { subtitulo: 'Esperando respuesta', cuerpo: 'Claude está esperando tu respuesta.' };
+  }
+  return { subtitulo: 'Atención requerida', cuerpo: 'Claude requiere tu atención.' };
+}
+
+module.exports = { resumirParaNotificacion, clasificarNotificacion };

package/hooks/lib/nudge-tracker.js

@@ -22,7 +22,7 @@
  */
 
 const fs   = require('fs');
-const { raizProyecto } = require('./raiz-proyecto');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 
 // Escritura atómica para reescritura completa del JSONL (marcar accionado).

package/hooks/lib/otlp-exporter.js

@@ -19,7 +19,7 @@
  */
 
 const fs     = require('fs');
-const { raizProyecto } = require('./raiz-proyecto');
+const { raizProyecto } = require('./raiz-proyecto');
 const path   = require('path');
 const crypto = require('crypto');
 const http   = require('http');

package/hooks/lib/propose-step.js

@@ -20,7 +20,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./raiz-proyecto');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 const { execFileSync } = require('child_process');