@saulwade/swl-ses 1.0.0

package/bin/swl-telegram-bot.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Daemon long-polling del bot de Telegram para swl-ses.
+ *
+ * SEGURIDAD:
+ *   - Filtro hardcoded por TELEGRAM_CHAT_ID. Todo mensaje de otro chat_id
+ *     recibe "Acceso denegado" y se registra en bot.log.
+ *   - Whitelist git estricta: solo rev-parse, status, log, diff, branch.
+ *   - Sin eval, exec ni shell habilitado. Solo execFileSync con array de argumentos.
+ *   - Sin secretos en logs — token nunca se escribe en bot.log ni en respuestas.
+ *   - Solo escribe en ~/.claude/notifications/ (offset, pid, log).
+ *
+ * Comandos heredados:
+ *   /help /start /proyectos /estado /log /diff /ultimo /resumen
+ *   /silencio /activar /mutes /quien
+ *
+ * Los comandos /inbox /costo /salud se agregan en Slice 007.
+ *
+ * @module bin/swl-telegram-bot
+ */
+
+const https = require('node:https');
+const fs    = require('node:fs');
+const path  = require('node:path');
+const os    = require('node:os');
+
+const { cargarConfig } = require('../hooks/lib/telegram-config');
+const { enviarMensaje } = require('../hooks/lib/telegram-cliente');
+const { despachar } = require('./lib/bot-comandos');
+
+// -----------------------------------------------------------------
+// Configuración de paths de estado del daemon
+// -----------------------------------------------------------------
+const DIR_NOTIFICACIONES = path.join(os.homedir(), '.claude', 'notifications');
+const RUTA_OFFSET = path.join(DIR_NOTIFICACIONES, 'bot.offset');
+const RUTA_PID    = path.join(DIR_NOTIFICACIONES, 'bot.pid');
+const RUTA_LOG    = path.join(DIR_NOTIFICACIONES, 'bot.log');
+
+// -----------------------------------------------------------------
+// Configuración de long-polling
+// -----------------------------------------------------------------
+const TIMEOUT_POLL_S   = 50;   // Timeout del request getUpdates (segundos)
+const TIMEOUT_POLL_MS  = (TIMEOUT_POLL_S + 5) * 1000; // +5s para timeout de red
+const BACKOFF_INICIAL  = 1000; // 1s
+const BACKOFF_MAX_NORMAL = 16_000; // 16s
+const BACKOFF_CIRCUIT  = 60_000;   // 60s — circuit breaker abierto
+const MAX_FALLOS_CIRCUITO = 5;
+
+// -----------------------------------------------------------------
+// Estado del daemon
+// -----------------------------------------------------------------
+let fallosConsecutivos = 0;
+let circuitAbierto = false;
+let corriendo = true;
+
+// -----------------------------------------------------------------
+// Logger sin PII — token nunca se loggea
+// -----------------------------------------------------------------
+
+/**
+ * Asegura que el directorio de notificaciones existe.
+ */
+function _asegurarDir() {
+  if (!fs.existsSync(DIR_NOTIFICACIONES)) {
+    fs.mkdirSync(DIR_NOTIFICACIONES, { recursive: true });
+  }
+}
+
+/**
+ * Escribe una línea al log del bot.
+ *
+ * @param {string} nivel  - Nivel: INFO, WARN, ERROR.
+ * @param {string} mensaje - Mensaje sin secretos.
+ */
+function log(nivel, mensaje) {
+  const linea = `[${new Date().toISOString()}] [${nivel}] ${mensaje}\n`;
+  try {
+    _asegurarDir();
+    fs.appendFileSync(RUTA_LOG, linea, 'utf8');
+  } catch (_) {
+    // Si no se puede escribir el log, ignorar silenciosamente
+  }
+  // También imprimir a stderr para facilitar depuración al arrancar
+  process.stderr.write(linea);
+}
+
+// -----------------------------------------------------------------
+// Gestión de offset persistente
+// -----------------------------------------------------------------
+
+/**
+ * Lee el offset guardado en disco.
+ *
+ * @returns {number} El offset persistido, o 0 si no existe.
+ */
+function leerOffset() {
+  try {
+    if (fs.existsSync(RUTA_OFFSET)) {
+      const val = parseInt(fs.readFileSync(RUTA_OFFSET, 'utf8').trim(), 10);
+      if (!isNaN(val) && val >= 0) return val;
+    }
+  } catch (_) {}
+  return 0;
+}
+
+/**
+ * Guarda el offset en disco.
+ *
+ * @param {number} offset - El offset a persistir.
+ */
+function guardarOffset(offset) {
+  try {
+    _asegurarDir();
+    fs.writeFileSync(RUTA_OFFSET, String(offset), 'utf8');
+  } catch (err) {
+    log('WARN', `No se pudo guardar offset: ${err.message}`);
+  }
+}
+
+// -----------------------------------------------------------------
+// Gestión del PID file
+// -----------------------------------------------------------------
+
+/**
+ * Escribe el PID del proceso actual en el archivo pid.
+ */
+function escribirPid() {
+  try {
+    _asegurarDir();
+    fs.writeFileSync(RUTA_PID, String(process.pid), 'utf8');
+  } catch (err) {
+    log('WARN', `No se pudo escribir PID file: ${err.message}`);
+  }
+}
+
+/**
+ * Elimina el PID file al terminar el daemon.
+ */
+function eliminarPid() {
+  try {
+    if (fs.existsSync(RUTA_PID)) {
+      fs.unlinkSync(RUTA_PID);
+    }
+  } catch (_) {}
+}
+
+// -----------------------------------------------------------------
+// Long-polling: getUpdates
+// -----------------------------------------------------------------
+
+/**
+ * Llama a getUpdates de la API de Telegram.
+ *
+ * @param {string} token  - Token del bot.
+ * @param {number} offset - Offset para evitar procesar updates ya vistos.
+ * @returns {Promise<{ ok: boolean, updates: object[], error?: string }>}
+ */
+function getUpdates(token, offset) {
+  const payload = JSON.stringify({
+    offset,
+    timeout: TIMEOUT_POLL_S,
+    allowed_updates: ['message'],
+  });
+
+  return new Promise((resolve) => {
+    const req = https.request(
+      {
+        method:   'POST',
+        hostname: 'api.telegram.org',
+        path:     `/bot${token}/getUpdates`,
+        headers: {
+          'Content-Type':   'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+        },
+        timeout: TIMEOUT_POLL_MS,
+      },
+      (res) => {
+        let cuerpo = '';
+        res.on('data', (chunk) => { cuerpo += chunk; });
+        res.on('end', () => {
+          try {
+            const datos = JSON.parse(cuerpo);
+            if (datos.ok && Array.isArray(datos.result)) {
+              resolve({ ok: true, updates: datos.result, statusCode: res.statusCode });
+            } else {
+              resolve({ ok: false, updates: [], error: datos.description || 'respuesta no-ok', statusCode: res.statusCode });
+            }
+          } catch (parseErr) {
+            resolve({ ok: false, updates: [], error: `JSON inválido: ${parseErr.message}`, statusCode: res.statusCode });
+          }
+        });
+      }
+    );
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ ok: false, updates: [], error: 'timeout', statusCode: 0 });
+    });
+
+    req.on('error', (err) => {
+      resolve({ ok: false, updates: [], error: err.message, statusCode: 0 });
+    });
+
+    req.write(payload);
+    req.end();
+  });
+}
+
+// -----------------------------------------------------------------
+// Pausa para backoff
+// -----------------------------------------------------------------
+
+/**
+ * Pausa durante `ms` milisegundos.
+ *
+ * @param {number} ms - Milisegundos a esperar.
+ * @returns {Promise<void>}
+ */
+function esperar(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Calcula el backoff exponencial con techo.
+ *
+ * @param {number} fallos - Número de fallos consecutivos.
+ * @returns {number} Milisegundos a esperar.
+ */
+function calcularBackoff(fallos) {
+  if (circuitAbierto) return BACKOFF_CIRCUIT;
+  const delay = BACKOFF_INICIAL * Math.pow(2, fallos - 1);
+  return Math.min(delay, BACKOFF_MAX_NORMAL);
+}
+
+// -----------------------------------------------------------------
+// Procesamiento de un update individual
+// -----------------------------------------------------------------
+
+/**
+ * Procesa un update recibido de getUpdates.
+ *
+ * @param {object} update    - Update de Telegram.
+ * @param {string} token     - Token del bot.
+ * @param {string} ownerChatId - Chat ID autorizado.
+ */
+async function procesarUpdate(update, token, ownerChatId) {
+  const mensaje = update.message;
+  if (!mensaje) return; // Ignorar updates sin message (edited_message, etc.)
+
+  const chatId   = String(mensaje.chat?.id || '');
+  const texto    = String(mensaje.text || '');
+  // Solo loggear los últimos 4 dígitos del chat_id para proteger PII
+  const chatIdOculto = chatId.length > 4 ? `***${chatId.slice(-4)}` : `***${chatId}`;
+
+  if (chatId !== String(ownerChatId)) {
+    log('WARN', `rechazado chat_id: ${chatIdOculto}`);
+    // Responder con acceso denegado
+    try {
+      await enviarMensaje(token, chatId, 'Acceso denegado');
+    } catch (_) {}
+    return;
+  }
+
+  // Extraer solo el nombre del comando para el log (no el texto completo por PII)
+  const primerToken = texto.trim().split(/\s+/)[0] || '';
+  const comandoLog  = primerToken.startsWith('/') ? primerToken.split('@')[0] : '(mensaje)';
+  log('INFO', `comando recibido: ${comandoLog} de chat_id: ${chatIdOculto}`);
+
+  const { respuesta } = despachar(mensaje, ownerChatId);
+
+  if (!respuesta) return; // Mensaje sin comando — ignorar
+
+  try {
+    const resultado = await enviarMensaje(token, chatId, respuesta);
+    if (!resultado.ok) {
+      log('WARN', `fallo al enviar respuesta: ${resultado.error || resultado.statusCode}`);
+    }
+  } catch (err) {
+    log('ERROR', `excepción al enviar respuesta: ${err.message}`);
+  }
+}
+
+// -----------------------------------------------------------------
+// Bucle principal del daemon
+// -----------------------------------------------------------------
+
+/**
+ * Bucle principal de long-polling.
+ *
+ * @param {string} token       - Token del bot.
+ * @param {string} ownerChatId - Chat ID autorizado.
+ */
+async function buclePolling(token, ownerChatId) {
+  let offset = leerOffset();
+  log('INFO', `daemon iniciado — PID ${process.pid} — offset inicial: ${offset}`);
+
+  while (corriendo) {
+    const resultado = await getUpdates(token, offset);
+
+    if (!resultado.ok) {
+      fallosConsecutivos++;
+
+      const esError4xx = resultado.statusCode >= 400 && resultado.statusCode < 500;
+
+      if (esError4xx) {
+        // Errores 4xx: credenciales inválidas u otro error cliente — fatal
+        log('ERROR', `error ${resultado.statusCode} de Telegram (cliente). Posible token inválido. Deteniendo daemon.`);
+        corriendo = false;
+        process.exitCode = 1;
+        break;
+      }
+
+      if (fallosConsecutivos >= MAX_FALLOS_CIRCUITO) {
+        if (!circuitAbierto) {
+          log('WARN', `circuit breaker abierto tras ${fallosConsecutivos} fallos consecutivos. Backoff: ${BACKOFF_CIRCUIT / 1000}s`);
+          circuitAbierto = true;
+        }
+      }
+
+      const backoff = calcularBackoff(fallosConsecutivos);
+      log('WARN', `fallo getUpdates (${fallosConsecutivos}/${MAX_FALLOS_CIRCUITO}): ${resultado.error}. Reintentando en ${backoff}ms`);
+
+      if (corriendo) await esperar(backoff);
+      continue;
+    }
+
+    // Éxito: resetear contadores de fallo
+    if (fallosConsecutivos > 0) {
+      log('INFO', `conexión restaurada tras ${fallosConsecutivos} fallos`);
+      fallosConsecutivos = 0;
+      circuitAbierto = false;
+    }
+
+    // Procesar cada update
+    for (const update of resultado.updates) {
+      if (!corriendo) break;
+      try {
+        await procesarUpdate(update, token, ownerChatId);
+      } catch (err) {
+        log('ERROR', `error inesperado procesando update ${update.update_id}: ${err.message}`);
+      }
+      // Avanzar offset: update_id + 1 para marcar como procesado
+      if (typeof update.update_id === 'number') {
+        offset = update.update_id + 1;
+        guardarOffset(offset);
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------
+// Cleanup en señales de terminación
+// -----------------------------------------------------------------
+
+/**
+ * Handler de shutdown limpio.
+ *
+ * @param {string} señal - Nombre de la señal recibida.
+ */
+function cleanup(señal) {
+  log('INFO', `señal ${señal} recibida — apagando daemon`);
+  corriendo = false;
+  eliminarPid();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => cleanup('SIGTERM'));
+process.on('SIGINT',  () => cleanup('SIGINT'));
+
+process.on('uncaughtException', (err) => {
+  log('ERROR', `uncaughtException: ${err.message}\n${err.stack || ''}`);
+  eliminarPid();
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  log('ERROR', `unhandledRejection: ${msg}`);
+  // No terminar — best-effort
+});
+
+// -----------------------------------------------------------------
+// Punto de entrada
+// -----------------------------------------------------------------
+
+/**
+ * Arranca el daemon de Telegram.
+ * Separado para facilitar tests de importación sin efecto lateral.
+ */
+async function runDaemon() {
+  // Verificar credenciales
+  const { config, valido, errores } = cargarConfig();
+
+  if (!valido) {
+    process.stderr.write(
+      `[ERROR] Faltan credenciales de Telegram: ${errores.join(', ')}\n` +
+      `Configura ~/.claude/notifications/.env con TELEGRAM_BOT_TOKEN y TELEGRAM_CHAT_ID.\n` +
+      `Puedes usar /swl:notificaciones init para configurarlas.\n`
+    );
+    process.exit(1);
+  }
+
+  const token       = config.TELEGRAM_BOT_TOKEN;
+  const ownerChatId = String(config.TELEGRAM_CHAT_ID).trim();
+
+  // Escribir PID file
+  _asegurarDir();
+  escribirPid();
+
+  try {
+    await buclePolling(token, ownerChatId);
+  } finally {
+    eliminarPid();
+  }
+}
+
+// Patrón dual-use: librería importable para tests + CLI ejecutable
+if (require.main === module) {
+  runDaemon().catch((err) => {
+    log('ERROR', `error fatal en daemon: ${err.message}`);
+    eliminarPid();
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  // Exportar funciones puras para tests
+  leerOffset,
+  guardarOffset,
+  getUpdates,
+  procesarUpdate,
+  cleanup,
+  esperar,
+  calcularBackoff,
+  // Para tests de integración
+  runDaemon,
+  RUTA_OFFSET,
+  RUTA_PID,
+  RUTA_LOG,
+};

package/bin/swl-telegram-bot.plist

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.swl.telegram-bot</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{NODE_PATH}}</string>
+    <string>{{BIN_PATH}}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/.claude/notifications/bot.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/.claude/notifications/bot.stderr.log</string>
+</dict>
+</plist>

package/bin/swl-telegram-bot.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=SWL Telegram Bot Daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart={{NODE_PATH}} {{BIN_PATH}}
+Restart=on-failure
+RestartSec=5s
+StandardOutput=append:{{HOME}}/.claude/notifications/bot.stdout.log
+StandardError=append:{{HOME}}/.claude/notifications/bot.stderr.log
+
+[Install]
+WantedBy=default.target

package/comandos/swl/.evolved.json

@@ -0,0 +1,23 @@
+{
+  "release.md": {
+    "evolved": true,
+    "evolvedFrom": "5.4.0",
+    "evolvedAt": "2026-04-11",
+    "evolvedBy": "aprender",
+    "evolvedNote": "mejora de metodología: checklist obligatoria de archivos de versión en paso 6"
+  },
+  "aprender.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-25",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
+  },
+  "verificar.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-26",
+    "evolvedBy": "evolucionar",
+    "evolvedNote": "flag --until-converge para iterar verificar→corregir→re-verificar hasta 0 hallazgos CRÍTICO+ALTO+MAYOR (max-iter=5, --no-prompt CI, detección adversarial ≥5 hallazgos nuevos)"
+  }
+}

package/comandos/swl/actualizar.md

@@ -0,0 +1,174 @@
+---
+name: swl:actualizar
+description: Actualiza el sistema SWL a la última versión disponible. Detecta automáticamente el perfil instalado y re-instala con --force preservando la configuración del usuario. No requiere desinstalar primero.
+allowed_tools: ["Read", "Bash", "Glob"]
+---
+
+# /swl:actualizar — Actualizar sistema SWL
+
+Eres el actualizador del sistema SWL dentro de Claude Code. Tu misión es actualizar los componentes instalados a la última versión disponible sin perder la configuración del usuario ni requerir desinstalación previa.
+
+## Cuándo usar este comando
+
+- Cuando se publicó una nueva versión del sistema SWL y quieres obtener las mejoras
+- Después de que `/swl:salud` reporta que la versión instalada está desactualizada
+- Cuando otro miembro del equipo indica que hay actualización disponible
+- Para re-instalar el mismo perfil después de modificaciones manuales que dejaron el sistema inconsistente
+
+No usar si SWL no está instalado — en ese caso usar `/swl:instalar`.
+
+## Paso 0 — Verificar que SWL está instalado
+
+```bash
+cat .claude/.swl-install-state.json 2>/dev/null
+```
+
+Si NO existe archivo de estado:
+- Informa: "No se encontró una instalación de SWL en este proyecto."
+- Sugiere: "Usa `/swl:instalar` para instalar SWL por primera vez."
+- DETENTE.
+
+Si existe, extrae:
+- `perfil`: el perfil actualmente instalado
+- `versionSistema`: la versión instalada
+- `global`: si fue instalación global
+- `archivosInstalados`: cantidad de archivos
+
+Informa al usuario:
+```
+SWL instalado:
+  Versión:  <versionSistema>
+  Perfil:   <perfil>
+  Archivos: <N>
+  Tipo:     <local|global>
+```
+
+## Paso 1 — Verificar versión disponible
+
+```bash
+npm view @saulwade/swl-ses version 2>/dev/null \
+  || npm view @saul-wade/swl-ses version --registry=https://npm.pkg.github.com 2>/dev/null
+```
+
+Si hay una versión más nueva, informa:
+- "Versión instalada: **X**. Versión disponible: **Y**."
+
+Si ya está en la última versión:
+- "Ya tienes la última versión (**X**). ¿Deseas re-instalar de todos modos?"
+- Si el usuario dice no, DETENTE.
+
+## Paso 1.5 — Descubrimiento de features nuevas
+
+Cuando hay una versión nueva disponible, mostrar qué cambió entre la versión
+instalada y la disponible para que el usuario tome una decisión informada.
+
+```bash
+# Obtener changelog entre versiones (si está disponible localmente o via npm)
+CURRENT="<version_instalada>"
+AVAILABLE="<version_disponible>"
+
+# Opción 1: Si el repo SWL está disponible como referencia
+if [ -f "CHANGELOG.md" ]; then
+  # Extraer entradas del changelog entre las dos versiones
+  sed -n "/## \[$AVAILABLE\]/,/## \[$CURRENT\]/p" CHANGELOG.md | head -50
+fi
+```
+
+Presentar al usuario un resumen categorizado:
+
+```
+=== Novedades entre v<CURRENT> y v<AVAILABLE> ===
+
+📦 Componentes nuevos:
+  - [agentes/skills/hooks/comandos nuevos]
+
+🔧 Mejoras:
+  - [mejoras a componentes existentes]
+
+🐛 Correcciones:
+  - [bugs corregidos]
+
+⚠ Cambios que requieren atención:
+  - [breaking changes o migraciones necesarias]
+  - [reglas nuevas obligatorias]
+  - [hooks nuevos que podrían afectar el flujo]
+
+💡 Guía de migración:
+  - [Si hay cambios breaking, pasos concretos para adaptar el proyecto]
+  - [Si hay hooks nuevos, cómo configurarlos]
+```
+
+Si no se puede obtener el changelog, informar:
+```
+No se pudo obtener el detalle de cambios entre versiones.
+Consulta el CHANGELOG.md del repositorio SWL para ver las novedades.
+```
+
+## Paso 2 — Confirmar actualización
+
+```
+=== Actualización SWL ===
+
+Versión actual:     <version instalada>
+Versión disponible: <version nueva>
+Perfil:             <perfil>
+Tipo:               <local|global>
+
+La actualización:
+  - Sobrescribe agentes, skills, comandos, reglas y hooks
+  - Actualiza hooks en settings.json
+  - Preserva _userland/ (extensiones del usuario)
+  - Preserva .planning/ (estado del proyecto)
+
+¿Proceder?
+```
+
+Espera confirmación del usuario.
+
+## Paso 3 — Ejecutar actualización
+
+```bash
+npx @saulwade/swl-ses@latest install --target claude --profile <PERFIL> [--global] --force
+```
+
+Usa el mismo perfil y ubicación de la instalación original.
+
+## Paso 4 — Ejecutar doctor
+
+```bash
+npx @saulwade/swl-ses@latest doctor
+```
+
+## Paso 5 — Reportar resultado
+
+```
+=== Actualización SWL completada ===
+
+Versión anterior: <X>
+Versión nueva:    <Y>
+Perfil:           <perfil>
+Archivos:         <N> actualizados
+
+Doctor: <resultado>
+```
+
+## Cambio de perfil durante actualización
+
+Si el usuario dice algo como "actualiza y cambia a perfil completo", ejecuta:
+
+```bash
+npx @saulwade/swl-ses@latest install --target claude --profile <NUEVO_PERFIL> [--global] --force
+```
+
+Informa que el cambio de perfil puede agregar componentes nuevos pero no elimina los del perfil anterior. Si quiere una instalación limpia con otro perfil, sugiere:
+1. `npx swl-ses uninstall --target claude`
+2. `/swl:instalar` con el nuevo perfil
+
+## Reglas de comportamiento
+
+- SIEMPRE verifica que SWL está instalado antes de intentar actualizar.
+- SIEMPRE muestra versión actual vs disponible.
+- SIEMPRE confirma antes de ejecutar.
+- NUNCA cambia el perfil sin que el usuario lo pida explícitamente.
+- Preserva `_userland/` y `.planning/` siempre.
+- Si la actualización falla, el sistema queda en el estado anterior (los archivos existentes no se borran antes de copiar los nuevos).