@saulwade/swl-ses 1.0.0

package/bin/lib/bot-comandos.js

@@ -0,0 +1,1030 @@
+'use strict';
+
+/**
+ * Lógica de comandos del bot de Telegram — módulo testeable.
+ *
+ * Maneja el dispatch de comandos, la generación de respuestas HTML
+ * y la gestión de proyectos silenciados. Las funciones aquí no
+ * hacen llamadas de red — reciben el resultado de getUpdates como
+ * input y retornan el texto a enviar.
+ *
+ * @module bin/lib/bot-comandos
+ */
+
+'use strict';
+
+const fs   = require('node:fs');
+const path = require('node:path');
+
+const { descubrirProyectos, resolverProyecto } = require('./bot-discovery');
+const { obtenerEstado, obtenerLog, obtenerDiff } = require('./bot-git');
+const { agregarMute, eliminarMute } = require('../../hooks/lib/telegram-config');
+
+// Límite de chars antes de truncar respuestas largas
+const LIMITE_RESPUESTA = 3500;
+const SUFIJO_TRUNCADO  = '\n… [truncado]';
+
+/**
+ * Lista de comandos disponibles (whitelist de texto de respuesta para /help).
+ */
+const TEXTO_AYUDA = `<b>Comandos disponibles:</b>
+
+/proyectos — Lista proyectos detectados
+/estado &lt;proyecto&gt; — Rama, estado y último commit
+/log &lt;proyecto&gt; [N] — Últimos N commits (default 5, máx 25)
+/diff &lt;proyecto&gt; — Archivos modificados (staged y no-staged)
+/ultimo &lt;proyecto&gt; — Último mensaje del asistente
+/resumen &lt;proyecto&gt; — Resumen del proyecto
+/inbox &lt;proyecto&gt; — Comandos pendientes en el inbox del proyecto
+/costo [d] — Tokens y USD del día o últimos d días
+/salud &lt;proyecto&gt; — Score y advertencias del sistema (SALUD.md)
+/silencio &lt;proyecto&gt; — Silenciar notificaciones del proyecto
+/activar &lt;proyecto&gt; — Reactivar notificaciones del proyecto
+/mutes — Lista proyectos silenciados
+/quien — Mostrar tu chat_id`;
+
+/**
+ * Trunca texto si supera el límite para respuestas de Telegram.
+ *
+ * @param {string} texto - Texto a truncar.
+ * @returns {string} Texto truncado o el original si cabe.
+ */
+function truncarRespuesta(texto) {
+  const s = String(texto || '');
+  if (s.length <= LIMITE_RESPUESTA) return s;
+  const corte = LIMITE_RESPUESTA - SUFIJO_TRUNCADO.length;
+  return s.slice(0, corte).trimEnd() + SUFIJO_TRUNCADO;
+}
+
+/**
+ * Escapa caracteres HTML para respuestas en parse_mode HTML de Telegram.
+ *
+ * @param {string} texto - Texto a escapar.
+ * @returns {string} Texto escapado.
+ */
+function escaparHtml(texto) {
+  return String(texto || '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Parsea el texto del comando y el argumento de proyecto de un mensaje.
+ *
+ * @param {string} texto - Texto completo del mensaje (ej: "/estado mi-proyecto").
+ * @returns {{ comando: string, argProyecto: string, argExtra: string }}
+ */
+function parsearMensaje(texto) {
+  const partes = (texto || '').trim().split(/\s+/);
+  // El comando puede traer @nombrebot: "/estado@mibot" → limpiar
+  const comandoRaw = (partes[0] || '').toLowerCase().split('@')[0];
+  const argProyecto = partes[1] || '';
+  const argExtra    = partes[2] || '';
+  return { comando: comandoRaw, argProyecto, argExtra };
+}
+
+/**
+ * Resuelve un proyecto y devuelve texto de error si no hay match.
+ *
+ * @param {string} termino - Término de búsqueda.
+ * @returns {{ proyecto: object|null, errorTexto: string|null }}
+ */
+function _resolverOError(termino) {
+  if (!termino) {
+    return { proyecto: null, errorTexto: 'Falta el nombre del proyecto. Uso: /comando &lt;proyecto&gt;' };
+  }
+
+  const { proyecto, candidatos, ambiguo } = resolverProyecto(termino);
+
+  if (ambiguo) {
+    const lista = candidatos.map((p) => `• ${escaparHtml(p.nombre)}`).join('\n');
+    return {
+      proyecto: null,
+      errorTexto: `Varios proyectos coinciden con "<b>${escaparHtml(termino)}</b>":\n${lista}\n\nSé más específico.`,
+    };
+  }
+
+  if (!proyecto) {
+    return {
+      proyecto: null,
+      errorTexto: `Proyecto no encontrado: <b>${escaparHtml(termino)}</b>`,
+    };
+  }
+
+  return { proyecto, errorTexto: null };
+}
+
+// -----------------------------------------------------------------
+// Handlers de cada comando
+// -----------------------------------------------------------------
+
+/**
+ * Maneja /help y /start.
+ *
+ * @returns {string} Texto de respuesta.
+ */
+function cmdHelp() {
+  return TEXTO_AYUDA;
+}
+
+/**
+ * Maneja /proyectos.
+ *
+ * @returns {string} Lista de proyectos en HTML.
+ */
+function cmdProyectos() {
+  const proyectos = descubrirProyectos();
+  if (proyectos.length === 0) {
+    return 'No se encontraron proyectos en <code>~/.claude/projects/</code>.';
+  }
+  const lista = proyectos
+    .map((p) => `• <b>${escaparHtml(p.nombre)}</b>\n  <code>${escaparHtml(p.cwd)}</code>`)
+    .join('\n');
+  return `<b>Proyectos detectados (${proyectos.length}):</b>\n\n${lista}`;
+}
+
+/**
+ * Maneja /estado &lt;proyecto&gt;.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdEstado(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  const { ok, rama, estado, ultimoCommit, error } = obtenerEstado(proyecto.cwd);
+
+  if (!ok) {
+    return `Error al consultar git en <b>${escaparHtml(proyecto.nombre)}</b>:\n<code>${escaparHtml(error)}</code>`;
+  }
+
+  return truncarRespuesta(
+    `<b>${escaparHtml(proyecto.nombre)}</b>\n\n` +
+    `<b>Rama:</b> <code>${escaparHtml(rama)}</code>\n\n` +
+    `<b>Estado:</b>\n<pre>${escaparHtml(estado || '(limpio)')}</pre>\n` +
+    `<b>Último commit:</b>\n<code>${escaparHtml(ultimoCommit || '(sin commits)')}</code>`
+  );
+}
+
+/**
+ * Maneja /log &lt;proyecto&gt; [N].
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @param {string} argN        - Número de commits (opcional).
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdLog(argProyecto, argN) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  const n = parseInt(argN, 10) || 5;
+  const { ok, lineas, error } = obtenerLog(proyecto.cwd, n);
+
+  if (!ok) {
+    return `Error al consultar log en <b>${escaparHtml(proyecto.nombre)}</b>:\n<code>${escaparHtml(error)}</code>`;
+  }
+
+  if (lineas.length === 0) {
+    return `<b>${escaparHtml(proyecto.nombre)}</b>: no hay commits.`;
+  }
+
+  const cuerpo = lineas.map((l) => `• <code>${escaparHtml(l)}</code>`).join('\n');
+  return truncarRespuesta(`<b>Log de ${escaparHtml(proyecto.nombre)}:</b>\n\n${cuerpo}`);
+}
+
+/**
+ * Maneja /diff &lt;proyecto&gt;.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdDiff(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  const { diffNoStaged, diffStaged } = obtenerDiff(proyecto.cwd);
+
+  let cuerpo = `<b>Diff — ${escaparHtml(proyecto.nombre)}</b>\n\n`;
+
+  if (diffNoStaged) {
+    cuerpo += `<b>Sin stage:</b>\n<pre>${escaparHtml(diffNoStaged)}</pre>\n`;
+  } else {
+    cuerpo += '<b>Sin stage:</b> (sin cambios)\n';
+  }
+
+  if (diffStaged) {
+    cuerpo += `<b>Staged:</b>\n<pre>${escaparHtml(diffStaged)}</pre>`;
+  } else {
+    cuerpo += '<b>Staged:</b> (sin cambios)';
+  }
+
+  return truncarRespuesta(cuerpo);
+}
+
+/**
+ * Busca el último mensaje del asistente en el .jsonl más reciente del proyecto.
+ *
+ * @param {string} cwd - Directorio del proyecto.
+ * @returns {string|null} El texto del mensaje o null si no se encuentra.
+ */
+function _ultimoMensajeAsistente(cwd) {
+  // Buscar .jsonl en el directorio de proyectos Claude Code
+  const os   = require('node:os');
+  const dirProyectos = path.join(os.homedir(), '.claude', 'projects');
+
+  let jsonlMasReciente = null;
+  let mtimeMasReciente = 0;
+
+  try {
+    const dirs = fs.readdirSync(dirProyectos);
+    for (const dir of dirs) {
+      const dirCompleto = path.join(dirProyectos, dir);
+      try {
+        if (!fs.statSync(dirCompleto).isDirectory()) continue;
+        const archivos = fs.readdirSync(dirCompleto);
+        for (const archivo of archivos) {
+          if (!archivo.endsWith('.jsonl')) continue;
+          const ruta = path.join(dirCompleto, archivo);
+          try {
+            const stat = fs.statSync(ruta);
+            // Verificar que el jsonl pertenece al proyecto buscado
+            const contenido = fs.readFileSync(ruta, 'utf8');
+            const lineas = contenido.split('\n');
+            for (const linea of lineas) {
+              try {
+                const obj = JSON.parse(linea);
+                if (obj && obj.cwd === cwd && stat.mtimeMs > mtimeMasReciente) {
+                  jsonlMasReciente = ruta;
+                  mtimeMasReciente = stat.mtimeMs;
+                }
+              } catch (_) {}
+            }
+          } catch (_) {}
+        }
+      } catch (_) {}
+    }
+  } catch (_) {
+    return null;
+  }
+
+  if (!jsonlMasReciente) return null;
+
+  try {
+    const lineas = fs.readFileSync(jsonlMasReciente, 'utf8').split('\n').reverse();
+    for (const linea of lineas) {
+      try {
+        const obj = JSON.parse(linea);
+        // Buscar mensajes del asistente en formato de sesión Claude Code
+        if (obj && obj.message && obj.message.role === 'assistant') {
+          const content = obj.message.content;
+          if (typeof content === 'string') return content;
+          if (Array.isArray(content)) {
+            // Concatenar bloques de texto
+            const textos = content
+              .filter((b) => b && b.type === 'text')
+              .map((b) => b.text)
+              .join('\n');
+            if (textos) return textos;
+          }
+        }
+      } catch (_) {}
+    }
+  } catch (_) {}
+
+  return null;
+}
+
+/**
+ * Maneja /ultimo &lt;proyecto&gt;.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdUltimo(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  const msg = _ultimoMensajeAsistente(proyecto.cwd);
+
+  if (!msg) {
+    return `No se encontró ningún mensaje del asistente en <b>${escaparHtml(proyecto.nombre)}</b>.`;
+  }
+
+  return truncarRespuesta(
+    `<b>Último mensaje — ${escaparHtml(proyecto.nombre)}:</b>\n\n${escaparHtml(msg)}`
+  );
+}
+
+/**
+ * Maneja /resumen &lt;proyecto&gt;.
+ *
+ * Busca en orden: .planning/RESUMEN.md, .planning/ESTADO.md, README.md.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdResumen(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  const candidatos = [
+    path.join(proyecto.cwd, '.planning', 'RESUMEN.md'),
+    path.join(proyecto.cwd, '.planning', 'ESTADO.md'),
+    path.join(proyecto.cwd, 'README.md'),
+  ];
+
+  for (const ruta of candidatos) {
+    try {
+      if (fs.existsSync(ruta)) {
+        const contenido = fs.readFileSync(ruta, 'utf8');
+        if (contenido.trim()) {
+          const nombreArchivo = path.basename(ruta);
+          return truncarRespuesta(
+            `<b>Resumen de ${escaparHtml(proyecto.nombre)} (${nombreArchivo}):</b>\n\n${escaparHtml(contenido)}`
+          );
+        }
+      }
+    } catch (_) {
+      // Siguiente candidato
+    }
+  }
+
+  return `No se encontró resumen en <b>${escaparHtml(proyecto.nombre)}</b>.\n` +
+    `Archivos buscados: .planning/RESUMEN.md, .planning/ESTADO.md, README.md`;
+}
+
+/**
+ * Maneja /silencio &lt;proyecto&gt;.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta.
+ */
+function cmdSilencio(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  agregarMute(proyecto.nombre);
+  return `Proyecto <b>${escaparHtml(proyecto.nombre)}</b> silenciado. Las notificaciones no se enviarán hasta ejecutar /activar.`;
+}
+
+/**
+ * Maneja /activar &lt;proyecto&gt;.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta.
+ */
+function cmdActivar(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  eliminarMute(proyecto.nombre);
+  return `Proyecto <b>${escaparHtml(proyecto.nombre)}</b> activado. Volveras a recibir notificaciones.`;
+}
+
+/**
+ * Maneja /mutes.
+ *
+ * @returns {string} Lista de proyectos silenciados.
+ */
+function cmdMutes() {
+  // Leer directamente desde el módulo de config
+  const telegramConfig = require('../../hooks/lib/telegram-config');
+  const os  = require('node:os');
+  const rutaMuted = path.join(os.homedir(), '.claude', 'notifications', 'muted.json');
+
+  let muted = [];
+  try {
+    if (fs.existsSync(rutaMuted)) {
+      const contenido = fs.readFileSync(rutaMuted, 'utf8');
+      const datos = JSON.parse(contenido);
+      muted = Array.isArray(datos) ? datos : [];
+    }
+  } catch (_) {
+    muted = [];
+  }
+
+  if (muted.length === 0) {
+    return 'No hay proyectos silenciados.';
+  }
+
+  const lista = muted.map((p) => `• ${escaparHtml(String(p))}`).join('\n');
+  return `<b>Proyectos silenciados (${muted.length}):</b>\n\n${lista}`;
+}
+
+/**
+ * Valida que el path de un proyecto resuelto no escapa del directorio de proyectos.
+ *
+ * Previene path traversal: el cwd del proyecto DEBE pertenecer a un proyecto
+ * conocido, y el subpath derivado DEBE comenzar con ese cwd.
+ *
+ * @param {string} cwdProyecto - cwd real del proyecto (desde descubrirProyectos).
+ * @param {string} subpath     - Subpath a validar dentro del proyecto.
+ * @returns {boolean} true si es seguro, false si hay traversal.
+ */
+function _esCaminoSeguro(cwdProyecto, subpath) {
+  try {
+    const base     = path.resolve(cwdProyecto);
+    const objetivo = path.resolve(subpath);
+    return objetivo.startsWith(base + path.sep) || objetivo === base;
+  } catch (_) {
+    return false;
+  }
+}
+
+// Directorio de proyectos Claude Code (mismo que bot-discovery)
+const DIR_PROYECTOS_CC = path.join(require('node:os').homedir(), '.claude', 'projects');
+
+/**
+ * Valida que el cwd de un proyecto conocido no fue manipulado para escapar
+ * del directorio de proyectos Claude Code.
+ *
+ * @param {string} cwd - cwd a verificar.
+ * @returns {boolean} true si es seguro.
+ */
+function _cwdEsSeguro(cwd) {
+  // El cwd debe ser un path real, sin intentar salir con ".."
+  // Comprobamos que al resolverlo no introduzca segmentos ".."
+  try {
+    const resuelto = path.resolve(cwd);
+    if (cwd.includes('..') || resuelto !== path.normalize(resuelto)) {
+      return false;
+    }
+
+    // REM-5: blacklist de paths sensibles del sistema.
+    // Un proyecto Claude Code nunca debería tener cwd en estas rutas.
+    const homeDir = require('os').homedir();
+    const _pathsSensibles = [
+      path.join(homeDir, '.claude'),
+      path.join(homeDir, '.ssh'),
+      path.join(homeDir, '.aws'),
+      path.join(homeDir, '.gnupg'),
+      '/etc',
+      '/etc/shadow',
+      '/etc/passwd',
+      'C:\\Windows',
+      'C:\\Windows\\System32',
+    ];
+
+    const resueltoNorm = resuelto.toLowerCase();
+    for (const sensible of _pathsSensibles) {
+      const sensibleNorm = sensible.toLowerCase();
+      if (resueltoNorm === sensibleNorm || resueltoNorm.startsWith(sensibleNorm + path.sep)) {
+        return false;
+      }
+    }
+
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// -----------------------------------------------------------------
+// Lazy require de better-sqlite3 (dependencia opt-in)
+// -----------------------------------------------------------------
+
+let _dbModulo;
+
+/**
+ * Carga better-sqlite3 de forma lazy. Devuelve el constructor o null si
+ * no está instalado.
+ *
+ * @returns {Function|null} Constructor de better-sqlite3 o null.
+ */
+function _cargarDb() {
+  if (_dbModulo === undefined) {
+    try {
+      // La carga se hace con require() dinámico para permitir que el módulo
+      // funcione incluso cuando better-sqlite3 no está instalado (opt-in).
+      // eslint-disable-next-line global-require
+      _dbModulo = require('better-sqlite3');
+    } catch (_) {
+      _dbModulo = null;
+    }
+  }
+  return _dbModulo;
+}
+
+// -----------------------------------------------------------------
+// Handler /inbox
+// -----------------------------------------------------------------
+
+/**
+ * Maneja /inbox &lt;proyecto&gt;.
+ *
+ * Lee <proyecto>/.planning/inbox/cmd-*.json, agrupa pendientes y procesados,
+ * devuelve top 10 pendientes con preview de 120 chars del campo `comando`
+ * o `mensaje`.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdInbox(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  if (!_cwdEsSeguro(proyecto.cwd)) {
+    console.error(`[bot] cmdInbox: path traversal rechazado para cwd="${proyecto.cwd}"`);
+    return 'path traversal rechazado';
+  }
+
+  const dirInbox = path.join(proyecto.cwd, '.planning', 'inbox');
+
+  try {
+    if (!fs.existsSync(dirInbox)) {
+      return `<b>${escaparHtml(proyecto.nombre)}</b> no tiene inbox todavía.`;
+    }
+
+    let entradas;
+    try {
+      entradas = fs.readdirSync(dirInbox);
+    } catch (_) {
+      return `Error al leer inbox de <b>${escaparHtml(proyecto.nombre)}</b>.`;
+    }
+
+    // Filtrar archivos cmd-*.json
+    const archivosCmds = entradas.filter(
+      (e) => e.startsWith('cmd-') && e.endsWith('.json')
+    );
+
+    if (archivosCmds.length === 0) {
+      return `<b>${escaparHtml(proyecto.nombre)}</b> sin comandos pendientes.`;
+    }
+
+    // Separar pendientes (sin .processed.json) y procesados
+    const pendientes  = archivosCmds.filter((a) => !a.endsWith('.processed.json'));
+    const procesados  = archivosCmds.filter((a) => a.endsWith('.processed.json'));
+
+    if (pendientes.length === 0) {
+      return (
+        `<b>${escaparHtml(proyecto.nombre)}</b> sin comandos pendientes.\n` +
+        `(${procesados.length} procesados)`
+      );
+    }
+
+    // Top 10 pendientes, ordenados por nombre (que incluye timestamp)
+    const top10 = pendientes.sort().slice(0, 10);
+
+    const lineas = top10.map((archivo) => {
+      const ruta = path.join(dirInbox, archivo);
+      let preview = archivo;
+      try {
+        // Validar path: debe estar dentro del dirInbox
+        const rutaResuelta = path.resolve(ruta);
+        const baseResuelta = path.resolve(dirInbox);
+        if (!rutaResuelta.startsWith(baseResuelta + path.sep) && rutaResuelta !== baseResuelta) {
+          return `• <code>${escaparHtml(archivo)}</code> (path inválido)`;
+        }
+
+        const contenido = fs.readFileSync(ruta, 'utf8');
+        const obj = JSON.parse(contenido);
+        // Intentar campo `comando` o `mensaje`
+        const texto = String(obj.comando || obj.mensaje || JSON.stringify(obj) || '');
+        // Preview de 120 chars
+        preview = texto.length > 120 ? texto.slice(0, 120) + '…' : texto;
+      } catch (_) {
+        preview = '(sin parsear)';
+      }
+      return `• <code>${escaparHtml(archivo)}</code>\n  ${escaparHtml(preview)}`;
+    });
+
+    const encabezado =
+      `<b>Inbox de ${escaparHtml(proyecto.nombre)}:</b> ` +
+      `${pendientes.length} pendiente(s), ${procesados.length} procesado(s)`;
+
+    return truncarRespuesta(encabezado + '\n\n' + lineas.join('\n\n'));
+
+  } catch (err) {
+    console.error(`[bot] cmdInbox error: ${err && err.message}`);
+    return `Error al consultar inbox de <b>${escaparHtml(proyecto.nombre)}</b>.`;
+  }
+}
+
+// -----------------------------------------------------------------
+// Handler /costo
+// -----------------------------------------------------------------
+
+/**
+ * Maneja /costo [d].
+ *
+ * Lee ~/.claude/usage.db (SQLite con better-sqlite3) y devuelve tokens y USD
+ * del día actual o de los últimos d días.
+ *
+ * Nota: requiere `better-sqlite3` instalado manualmente en `bin/`:
+ *   cd bin && npm install --save better-sqlite3
+ * Si no está instalado, devuelve mensaje explicativo sin crashear.
+ *
+ * @param {string} argDias - Número de días (opcional, default 1).
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdCosto(argDias) {
+  const BetterSqlite3 = _cargarDb();
+  if (!BetterSqlite3) {
+    return (
+      'instalación incompleta: falta better-sqlite3\n' +
+      '<code>npm install --save better-sqlite3</code> en <code>bin/</code>'
+    );
+  }
+
+  const os = require('node:os');
+  const rutaDb = path.join(os.homedir(), '.claude', 'usage.db');
+
+  if (!fs.existsSync(rutaDb)) {
+    return 'no hay datos de uso registrados todavía.';
+  }
+
+  // Clamp silencioso: máximo 90 días
+  const diasRaw = parseInt(argDias, 10);
+  const dias    = isNaN(diasRaw) || diasRaw < 1 ? 1 : Math.min(diasRaw, 90);
+
+  let db;
+  try {
+    db = new BetterSqlite3(rutaDb, { readonly: true });
+
+    // Inspeccionar schema: obtener columnas de la tabla usage
+    const infoTabla = db.prepare("PRAGMA table_info('usage')").all();
+    const columnas  = new Set(infoTabla.map((c) => c.name));
+
+    if (columnas.size === 0) {
+      db.close();
+      return 'La base de datos usage.db no tiene la tabla <code>usage</code>.';
+    }
+
+    // Construir SELECT dinámico solo con columnas existentes
+    // (el schema puede variar entre versiones de Claude Code)
+    const colInput        = columnas.has('input_tokens')         ? 'input_tokens'         : null;
+    const colOutput       = columnas.has('output_tokens')        ? 'output_tokens'        : null;
+    const colCacheCreate  = columnas.has('cache_creation_tokens') ? 'cache_creation_tokens' : null;
+    const colCacheRead    = columnas.has('cache_read_tokens')    ? 'cache_read_tokens'    : null;
+    const colCost         = columnas.has('cost_usd')             ? 'cost_usd'             : null;
+    const colModel        = columnas.has('model')                ? 'model'                : null;
+    const colTimestamp    = columnas.has('timestamp')            ? 'timestamp'            : null;
+
+    if (!colTimestamp) {
+      db.close();
+      return 'La tabla <code>usage</code> no tiene columna <code>timestamp</code> — schema inesperado.';
+    }
+
+    // Calcular límite de tiempo: hace N días en unix epoch (segundos o milisegundos)
+    // Claude Code guarda el timestamp como ISO 8601 o epoch entero — probar ambos
+    const ahora      = Date.now();
+    const limiteMs   = ahora - dias * 24 * 60 * 60 * 1000;
+    const limiteSeg  = Math.floor(limiteMs / 1000);
+
+    // Probar formato del timestamp con la primera fila
+    const primeraFila = db.prepare(`SELECT ${colTimestamp} AS ts FROM usage LIMIT 1`).get();
+    if (!primeraFila) {
+      db.close();
+      return `Sin registros de uso en los últimos ${dias} día(s).`;
+    }
+
+    const tsVal = primeraFila.ts;
+    // REM-4: usar bind parameters de SQLite en lugar de interpolación de valores numéricos.
+    // Aunque los valores son internos (Date.now(), no input de usuario), bind params
+    // es la práctica correcta para prevenir inyección si el código evolucionara.
+    let whereClause;
+    let bindParam;
+    if (typeof tsVal === 'number' && tsVal > 1_000_000_000_000) {
+      // Epoch en milisegundos
+      whereClause = `WHERE ${colTimestamp} >= ?`;
+      bindParam   = limiteMs;
+    } else if (typeof tsVal === 'number') {
+      // Epoch en segundos
+      whereClause = `WHERE ${colTimestamp} >= ?`;
+      bindParam   = limiteSeg;
+    } else {
+      // ISO 8601 string — usar comparación de string (funciona para fechas ISO)
+      const fechaIso = new Date(limiteMs).toISOString().slice(0, 10);
+      whereClause = `WHERE ${colTimestamp} >= ?`;
+      bindParam   = fechaIso;
+    }
+
+    // Query agregada con bind parameters (sin interpolación de valores)
+    const partesSel = [];
+    if (colInput)       partesSel.push(`SUM(${colInput})       AS total_input`);
+    if (colOutput)      partesSel.push(`SUM(${colOutput})      AS total_output`);
+    if (colCacheCreate) partesSel.push(`SUM(${colCacheCreate}) AS total_cache_create`);
+    if (colCacheRead)   partesSel.push(`SUM(${colCacheRead})   AS total_cache_read`);
+    if (colCost)        partesSel.push(`SUM(${colCost})        AS total_costo`);
+    partesSel.push('COUNT(*) AS total_llamadas');
+
+    const queryTotal = db.prepare(`SELECT ${partesSel.join(', ')} FROM usage ${whereClause}`);
+    const totales    = queryTotal.get(bindParam);
+
+    if (!totales || totales.total_llamadas === 0) {
+      db.close();
+      return `Sin registros de uso en los últimos ${dias} día(s).`;
+    }
+
+    // Breakdown por modelo si hay más de uno
+    let breakdownHtml = '';
+    if (colModel) {
+      const partesMod = [];
+      if (colInput)  partesMod.push(`SUM(${colInput}) AS tot_in`);
+      if (colOutput) partesMod.push(`SUM(${colOutput}) AS tot_out`);
+      if (colCost)   partesMod.push(`SUM(${colCost}) AS tot_costo`);
+      partesMod.push(`${colModel} AS modelo`, 'COUNT(*) AS llamadas');
+
+      const queryMod = db.prepare(
+        `SELECT ${partesMod.join(', ')} FROM usage ${whereClause} GROUP BY ${colModel} ORDER BY tot_costo DESC`
+      );
+      const filasMod = queryMod.all(bindParam);
+
+      if (filasMod.length > 1) {
+        const lineasMod = filasMod.map((f) => {
+          const costoMod = colCost ? ` · $${Number(f.tot_costo || 0).toFixed(4)}` : '';
+          const inOut    = (colInput && colOutput)
+            ? ` (${_fmtTokens(f.tot_in)}/${_fmtTokens(f.tot_out)})`
+            : '';
+          return `  • <code>${escaparHtml(String(f.modelo || '?'))}</code>${inOut}${costoMod} · ${f.llamadas} llamadas`;
+        });
+        breakdownHtml = '\n\n<b>Por modelo:</b>\n' + lineasMod.join('\n');
+      }
+    }
+
+    db.close();
+
+    // Construir respuesta — no incluye USD en log (solo en respuesta a Telegram)
+    const titulo = dias === 1
+      ? '<b>Uso de hoy:</b>'
+      : `<b>Uso de los últimos ${dias} días:</b>`;
+
+    const lineas = [];
+    if (colInput)       lineas.push(`Tokens entrada:       ${_fmtTokens(totales.total_input)}`);
+    if (colOutput)      lineas.push(`Tokens salida:        ${_fmtTokens(totales.total_output)}`);
+    if (colCacheCreate) lineas.push(`Cache creación:       ${_fmtTokens(totales.total_cache_create)}`);
+    if (colCacheRead)   lineas.push(`Cache lectura:        ${_fmtTokens(totales.total_cache_read)}`);
+    if (colCost)        lineas.push(`Costo total USD:      $${Number(totales.total_costo || 0).toFixed(4)}`);
+    lineas.push(`Llamadas:             ${totales.total_llamadas}`);
+
+    return truncarRespuesta(
+      titulo + '\n\n<pre>' + lineas.join('\n') + '</pre>' + breakdownHtml
+    );
+
+  } catch (err) {
+    if (db) { try { db.close(); } catch (_) {} }
+    console.error(`[bot] cmdCosto error: ${err && err.message}`);
+    return `Error al leer datos de uso: <code>${escaparHtml(String(err && err.message || err))}</code>`;
+  }
+}
+
+/**
+ * Formatea un número de tokens con separadores de miles.
+ *
+ * @param {number|null|undefined} n - Número de tokens.
+ * @returns {string} Número formateado.
+ */
+function _fmtTokens(n) {
+  const num = Number(n) || 0;
+  return num.toLocaleString('es-MX');
+}
+
+// -----------------------------------------------------------------
+// Handler /salud
+// -----------------------------------------------------------------
+
+/**
+ * Maneja /salud &lt;proyecto&gt;.
+ *
+ * Busca SALUD.md en <p>/ o <p>/.planning/ y extrae el score y las
+ * primeras 3 advertencias encontradas.
+ *
+ * @param {string} argProyecto - Término de búsqueda del proyecto.
+ * @returns {string} Texto de respuesta HTML.
+ */
+function cmdSalud(argProyecto) {
+  const { proyecto, errorTexto } = _resolverOError(argProyecto);
+  if (errorTexto) return errorTexto;
+
+  if (!_cwdEsSeguro(proyecto.cwd)) {
+    console.error(`[bot] cmdSalud: path traversal rechazado para cwd="${proyecto.cwd}"`);
+    return 'path traversal rechazado';
+  }
+
+  const candidatos = [
+    path.join(proyecto.cwd, 'SALUD.md'),
+    path.join(proyecto.cwd, '.planning', 'SALUD.md'),
+  ];
+
+  for (const ruta of candidatos) {
+    // Validar que el path candidato no escapa del cwd del proyecto
+    if (!_esCaminoSeguro(proyecto.cwd, ruta)) {
+      console.error(`[bot] cmdSalud: path traversal rechazado: "${ruta}"`);
+      continue;
+    }
+
+    try {
+      if (!fs.existsSync(ruta)) continue;
+      const contenido = fs.readFileSync(ruta, 'utf8');
+      if (!contenido.trim()) continue;
+
+      return truncarRespuesta(_parsearSalud(proyecto.nombre, contenido));
+    } catch (_) {
+      // Siguiente candidato
+    }
+  }
+
+  return `<b>${escaparHtml(proyecto.nombre)}</b> no tiene SALUD.md (correr /swl:salud)`;
+}
+
+/**
+ * Parsea el contenido de un SALUD.md y devuelve HTML con score y advertencias.
+ *
+ * @param {string} nombreProyecto - Nombre del proyecto para el encabezado.
+ * @param {string} contenido      - Contenido completo del SALUD.md.
+ * @returns {string} HTML con score y top 3 advertencias.
+ */
+function _parsearSalud(nombreProyecto, contenido) {
+  // Extraer score — patrones conocidos:
+  //   "Score Global: 100% — ..."
+  //   "Score: 95/100"
+  //   "## Score Global: 100%"
+  const reScore = /score\s*(?:global)?[:\s]+(\d+(?:\.\d+)?)\s*(?:%|\/\s*100)/i;
+  const matchScore = contenido.match(reScore);
+  const scoreTexto = matchScore ? matchScore[0].trim() : null;
+
+  // Extraer advertencias: líneas que contengan palabras clave de problema
+  // (buscamos en filas de tabla, listas o líneas con palabras indicativas)
+  const lineas = contenido.split('\n');
+  const advertencias = [];
+
+  for (const linea of lineas) {
+    const l = linea.trim();
+    if (!l) continue;
+
+    // Buscar filas de tabla con problemas (columna Problemas > 0)
+    // Formato: | Componente | Score | Estado | Problemas |
+    // o líneas con estados de advertencia/error
+    if (
+      /\|\s*\d+\s*\|/.test(l) &&                      // tiene número en tabla
+      /[1-9]\d*/.test(l) &&                            // hay al menos un dígito no-cero
+      !/\|\s*0\s*\|/.test(l.replace(/(\d+%)/, ''))    // no es solo ceros
+    ) {
+      const columnas = l.split('|').map((c) => c.trim()).filter(Boolean);
+      // La última columna suele ser el count de problemas
+      const ultimo = columnas[columnas.length - 1];
+      if (ultimo && /^[1-9]\d*$/.test(ultimo)) {
+        advertencias.push(l.replace(/\|/g, ' ').replace(/\s+/g, ' ').trim());
+        if (advertencias.length >= 3) break;
+      }
+    }
+
+    // Líneas de sección "Problemas críticos" o "Advertencias"
+    if (advertencias.length < 3 && /(?:problem|advertencia|error|crítico|warning)/i.test(l)) {
+      // Solo incluir si parece contenido real (no solo el encabezado de sección)
+      if (l.length > 10 && !l.startsWith('#')) {
+        advertencias.push(l);
+        if (advertencias.length >= 3) break;
+      }
+    }
+  }
+
+  const encabezado = `<b>Salud de ${escaparHtml(nombreProyecto)}</b>`;
+  const scoreHtml  = scoreTexto
+    ? `\n<b>Score:</b> ${escaparHtml(scoreTexto)}`
+    : '\n<i>(score no encontrado)</i>';
+
+  let advertenciasHtml = '';
+  if (advertencias.length > 0) {
+    const lista = advertencias
+      .slice(0, 3)
+      .map((a) => `• ${escaparHtml(a)}`)
+      .join('\n');
+    advertenciasHtml = '\n\n<b>Advertencias (top 3):</b>\n' + lista;
+  } else {
+    advertenciasHtml = '\n\n<i>Sin advertencias detectadas.</i>';
+  }
+
+  return encabezado + scoreHtml + advertenciasHtml;
+}
+
+/**
+ * Maneja /quien.
+ *
+ * @param {string|number} chatId - ID del chat del remitente.
+ * @returns {string} Texto con el chat_id.
+ */
+function cmdQuien(chatId) {
+  return `Tu chat_id es: <code>${escaparHtml(String(chatId))}</code>`;
+}
+
+/**
+ * Despacha un mensaje de Telegram al handler correspondiente.
+ *
+ * @param {object} mensaje   - Objeto mensaje de Telegram.
+ * @param {string} ownerChatId - Chat ID autorizado (como string).
+ * @returns {{ respuesta: string, rechazado: boolean }}
+ */
+function despachar(mensaje, ownerChatId) {
+  const chatId     = String(mensaje?.chat?.id || '');
+  const texto      = String(mensaje?.text || '').trim();
+  const ownerStr   = String(ownerChatId || '');
+
+  // Filtro de acceso
+  if (chatId !== ownerStr) {
+    return { respuesta: 'Acceso denegado', rechazado: true };
+  }
+
+  if (!texto.startsWith('/')) {
+    // Mensaje sin comando: ignorar silenciosamente
+    return { respuesta: '', rechazado: false };
+  }
+
+  const { comando, argProyecto, argExtra } = parsearMensaje(texto);
+
+  let respuesta = '';
+
+  switch (comando) {
+    case '/start':
+    case '/help':
+      respuesta = cmdHelp();
+      break;
+
+    case '/proyectos':
+      respuesta = cmdProyectos();
+      break;
+
+    case '/estado':
+      respuesta = cmdEstado(argProyecto);
+      break;
+
+    case '/log':
+      respuesta = cmdLog(argProyecto, argExtra);
+      break;
+
+    case '/diff':
+      respuesta = cmdDiff(argProyecto);
+      break;
+
+    case '/ultimo':
+      respuesta = cmdUltimo(argProyecto);
+      break;
+
+    case '/resumen':
+      respuesta = cmdResumen(argProyecto);
+      break;
+
+    case '/inbox':
+      respuesta = cmdInbox(argProyecto);
+      break;
+
+    case '/costo':
+      // argProyecto realmente es el número de días cuando se usa /costo [d]
+      respuesta = cmdCosto(argProyecto);
+      break;
+
+    case '/salud':
+      respuesta = cmdSalud(argProyecto);
+      break;
+
+    case '/silencio':
+      respuesta = cmdSilencio(argProyecto);
+      break;
+
+    case '/activar':
+      respuesta = cmdActivar(argProyecto);
+      break;
+
+    case '/mutes':
+      respuesta = cmdMutes();
+      break;
+
+    case '/quien':
+      respuesta = cmdQuien(chatId);
+      break;
+
+    default:
+      respuesta = `Comando no reconocido: <code>${escaparHtml(comando)}</code>\n\nEscribe /help para ver los comandos disponibles.`;
+  }
+
+  return { respuesta, rechazado: false };
+}
+
+module.exports = {
+  despachar,
+  parsearMensaje,
+  truncarRespuesta,
+  escaparHtml,
+  cmdHelp,
+  cmdProyectos,
+  cmdEstado,
+  cmdLog,
+  cmdDiff,
+  cmdUltimo,
+  cmdResumen,
+  cmdInbox,
+  cmdCosto,
+  cmdSalud,
+  cmdSilencio,
+  cmdActivar,
+  cmdMutes,
+  cmdQuien,
+  LIMITE_RESPUESTA,
+  // Exportar para tests
+  _parsearSalud,
+  _esCaminoSeguro,
+  _cwdEsSeguro,
+  _cargarDb,
+};