theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/scripts/hooks/pre-compact.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Hook PreCompact - Guarda un resumen generado por LLM antes de la compactación del contexto
+ *
+ * Multiplataforma (Windows, macOS, Linux)
+ *
+ * Se ejecuta antes de que Theus compacte el contexto. Genera un resumen LLM
+ * enriquecido de la sesión actual y lo escribe en el archivo .tmp de la sesión
+ * activa, de modo que el siguiente inicio de sesión reciba un resumen de alta
+ * calidad incluso tras una compactación con pérdida.
+ *
+ * Recurre a una entrada simple en el log cuando transcript_path no está
+ * disponible o la llamada al LLM falla.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { getSessionsDir, getDateTimeString, getTimeString, findFiles, ensureDir, appendFile, readFile, writeFile, log } = require('../lib/utils');
+const { generateSessionSummary } = require('../lib/llm-summary');
+
+const SUMMARY_START_MARKER = '<!-- THEUS:SUMMARY:START -->';
+const SUMMARY_END_MARKER = '<!-- THEUS:SUMMARY:END -->';
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const MAX_STDIN = 1024 * 1024;
+let stdinData = '';
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', chunk => {
+  if (stdinData.length < MAX_STDIN) {
+    stdinData += chunk.substring(0, MAX_STDIN - stdinData.length);
+  }
+});
+
+process.stdin.on('end', () => {
+  main().catch(err => {
+    log(`[PreCompact] Error: ${err.message}`);
+    process.exit(0);
+  });
+});
+
+async function main() {
+  let transcriptPath = null;
+  try {
+    const input = JSON.parse(stdinData);
+    if (input && typeof input.transcript_path === 'string' && input.transcript_path.length > 0) {
+      transcriptPath = input.transcript_path;
+    }
+  } catch {
+    // stdin no es JSON o falta — continuar sin transcripción
+  }
+
+  const sessionsDir = getSessionsDir();
+  const compactionLog = path.join(sessionsDir, 'compaction-log.txt');
+
+  ensureDir(sessionsDir);
+
+  const timestamp = getDateTimeString();
+  appendFile(compactionLog, `[${timestamp}] Compactación de contexto activada\n`);
+
+  const sessions = findFiles(sessionsDir, '*-session.tmp');
+  if (sessions.length === 0) {
+    log('[PreCompact] No se encontró un archivo de sesión activa');
+    process.exit(0);
+  }
+
+  const activeSession = sessions[0].path;
+  const timeStr = getTimeString();
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    appendFile(activeSession, `\n---\n**[Compactación ocurrida a las ${timeStr}]** - El contexto fue resumido\n`);
+    log('[PreCompact] Transcripción no disponible; solo se registró el evento de compactación');
+    process.exit(0);
+  }
+
+  // Generar el resumen LLM justo antes de la compactación — el momento más crítico
+  log('[PreCompact] Generando resumen LLM antes de la compactación...');
+  const llmSummary = generateSessionSummary(transcriptPath);
+
+  if (!llmSummary) {
+    appendFile(activeSession, `\n---\n**[Compactación ocurrida a las ${timeStr}]** - El contexto fue resumido\n`);
+    log('[PreCompact] Resumen LLM no disponible; solo se registró el evento de compactación');
+    process.exit(0);
+  }
+
+  const existing = readFile(activeSession);
+  if (existing && existing.includes(SUMMARY_START_MARKER) && existing.includes(SUMMARY_END_MARKER)) {
+    const newBlock = `${SUMMARY_START_MARKER}\n${llmSummary}\n<!-- LLM_SUMMARY:pre-compact:${timeStr} -->\n${SUMMARY_END_MARKER}`;
+    const updated = existing.replace(new RegExp(`${escapeRegExp(SUMMARY_START_MARKER)}[\\s\\S]*?${escapeRegExp(SUMMARY_END_MARKER)}`), () => newBlock);
+    writeFile(activeSession, updated);
+    log('[PreCompact] Resumen LLM escrito en el archivo de sesión antes de la compactación');
+  } else {
+    appendFile(activeSession, `\n---\n**[Compactación a las ${timeStr}]**\n\n${llmSummary}\n`);
+    log('[PreCompact] Resumen LLM añadido al final (no se encontraron marcadores de resumen)');
+  }
+
+  process.exit(0);
+}

package/vendor/theus-arsenal/scripts/hooks/pretooluse-visible-output.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Utilidades para construir la salida visible de hooks PreToolUse.
+ *
+ * Normaliza y combina fragmentos de contexto adicional y los envuelve
+ * en el JSON `hookSpecificOutput` que el motor de hooks de Theus
+ * interpreta para inyectar contexto en la conversación.
+ */
+
+function normalizeAdditionalContext(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map(item => String(item || '').trim())
+      .filter(Boolean)
+      .join('\n');
+  }
+
+  return String(value || '').trim();
+}
+
+function combineAdditionalContext(current, next) {
+  const currentText = normalizeAdditionalContext(current);
+  const nextText = normalizeAdditionalContext(next);
+
+  if (!currentText) return nextText;
+  if (!nextText) return currentText;
+
+  return `${currentText}\n${nextText}`;
+}
+
+function buildPreToolUseAdditionalContext(value) {
+  const additionalContext = normalizeAdditionalContext(value);
+  if (!additionalContext) return '';
+
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext,
+    },
+  });
+}
+
+module.exports = {
+  buildPreToolUseAdditionalContext,
+  combineAdditionalContext,
+  normalizeAdditionalContext,
+};

package/vendor/theus-arsenal/scripts/hooks/quality-gate.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Hook de control de calidad (Quality Gate)
+ *
+ * Ejecuta verificaciones ligeras de calidad después de editar archivos.
+ * - Apunta a un solo archivo cuando se provee file_path
+ * - Degrada a no-op cuando el lenguaje o las herramientas no están disponibles
+ *
+ * Para archivos JS/TS con Biome, este hook se omite porque
+ * post-edit-format.js ya ejecuta `biome check --write`.
+ * Este hook sigue cubriendo .json/.md con Biome, y todas las
+ * verificaciones de Prettier / Go / Python.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('../lib/resolve-formatter');
+
+const MAX_STDIN = 1024 * 1024;
+
+/**
+ * Ejecuta un comando de forma síncrona y devuelve el resultado de spawnSync.
+ *
+ * @param {string} command - Ruta o nombre del ejecutable
+ * @param {string[]} args - Argumentos a pasar
+ * @param {string} [cwd] - Directorio de trabajo (por defecto process.cwd())
+ * @returns {import('child_process').SpawnSyncReturns<string>}
+ */
+function exec(command, args, cwd = process.cwd()) {
+  return spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    env: process.env,
+    timeout: 15000
+  });
+}
+
+/**
+ * Escribe un mensaje en stderr como registro.
+ *
+ * @param {string} msg - Mensaje a registrar
+ */
+function log(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+/**
+ * Ejecuta las verificaciones de calidad para un archivo según su extensión.
+ * Omite archivos JS/TS cuando Biome está configurado (los cubre post-edit-format).
+ *
+ * @param {string} filePath - Ruta del archivo editado
+ */
+function maybeRunQualityGate(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return;
+  }
+
+  // Resolver a ruta absoluta para que las comparaciones relativas a projectRoot funcionen
+  filePath = path.resolve(filePath);
+
+  const ext = path.extname(filePath).toLowerCase();
+  const fix = String(process.env.THEUS_QUALITY_GATE_FIX || '').toLowerCase() === 'true';
+  const strict = String(process.env.THEUS_QUALITY_GATE_STRICT || '').toLowerCase() === 'true';
+
+  if (['.ts', '.tsx', '.js', '.jsx', '.json', '.md'].includes(ext)) {
+    const projectRoot = findProjectRoot(path.dirname(filePath));
+    const formatter = detectFormatter(projectRoot);
+
+    if (formatter === 'biome') {
+      // JS/TS ya está cubierto por post-edit-format vía `biome check --write`
+      if (['.ts', '.tsx', '.js', '.jsx'].includes(ext)) {
+        return;
+      }
+
+      // .json / .md — todavía requieren el control de calidad
+      const resolved = resolveFormatterBin(projectRoot, 'biome');
+      if (!resolved) return;
+      const args = [...resolved.prefix, 'check', filePath];
+      if (fix) args.push('--write');
+      const result = exec(resolved.bin, args, projectRoot);
+      if (result.status !== 0 && strict) {
+        log(`[QualityGate] La verificación de Biome falló para ${filePath}`);
+      }
+      return;
+    }
+
+    if (formatter === 'prettier') {
+      const resolved = resolveFormatterBin(projectRoot, 'prettier');
+      if (!resolved) return;
+      const args = [...resolved.prefix, fix ? '--write' : '--check', filePath];
+      const result = exec(resolved.bin, args, projectRoot);
+      if (result.status !== 0 && strict) {
+        log(`[QualityGate] La verificación de Prettier falló para ${filePath}`);
+      }
+      return;
+    }
+
+    // Sin formateador configurado — omitir
+    return;
+  }
+
+  if (ext === '.go') {
+    if (fix) {
+      const r = exec('gofmt', ['-w', filePath]);
+      if (r.status !== 0 && strict) {
+        log(`[QualityGate] gofmt falló para ${filePath}`);
+      }
+    } else if (strict) {
+      const r = exec('gofmt', ['-l', filePath]);
+      if (r.status !== 0) {
+        log(`[QualityGate] gofmt falló para ${filePath}`);
+      } else if (r.stdout && r.stdout.trim()) {
+        log(`[QualityGate] La verificación de gofmt falló para ${filePath}`);
+      }
+    }
+    return;
+  }
+
+  if (ext === '.py') {
+    const args = ['format'];
+    if (!fix) args.push('--check');
+    args.push(filePath);
+    const r = exec('ruff', args);
+    if (r.status !== 0 && strict) {
+      log(`[QualityGate] La verificación de Ruff falló para ${filePath}`);
+    }
+  }
+}
+
+/**
+ * Lógica principal — exportada para que run-with-flags.js pueda invocarla directamente.
+ *
+ * @param {string} rawInput - Cadena JSON cruda recibida por stdin
+ * @returns {string} La entrada original (pass-through)
+ */
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    const filePath = String(input.tool_input?.file_path || '');
+    maybeRunQualityGate(filePath);
+  } catch {
+    // Ignorar errores de parseo.
+  }
+  return rawInput;
+}
+
+// ── Punto de entrada por stdin (compatibilidad hacia atrás) ──────────
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+    }
+  });
+
+  process.stdin.on('end', () => {
+    const result = run(raw);
+    process.stdout.write(result);
+  });
+}
+
+module.exports = { run };

package/vendor/theus-arsenal/scripts/hooks/run-with-flags.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * Ejecuta un script de hook solo cuando está habilitado por las banderas
+ * de perfil de hooks de Theus.
+ *
+ * Uso:
+ *   node run-with-flags.js <hookId> <rutaRelativaDelScript> [perfilesCsv]
+ *
+ * Gating por variables de entorno:
+ * - THEUS_HOOK_PROFILE=minimal|standard|strict
+ * - THEUS_DISABLED_HOOKS=ids,de,hooks,separados,por,comas
+ * - THEUS_DRY_RUN=1 para previsualizar sin ejecutar
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isHookEnabled, isDryRun } = require('../lib/hook-flags');
+const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) {
+          truncated = true;
+        }
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function writeStderr(stderr) {
+  if (typeof stderr !== 'string' || stderr.length === 0) {
+    return;
+  }
+
+  process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+}
+
+/**
+ * Escribe stdout por completo y luego termina el proceso. Un `process.exit()`
+ * inmediatamente después de `process.stdout.write()` descarta todo lo que
+ * exceda el búfer de la tubería (~64 KB), lo que cortaba payloads grandes
+ * de pass-through a mitad del JSON y hacía que el motor tratara el hook
+ * como fallido. El callback de write se dispara solo después de que el
+ * fragmento se haya volcado a la tubería.
+ */
+function exitWithStdout(text, exitCode) {
+  if (typeof text !== 'string' || text.length === 0) {
+    process.exit(exitCode);
+  }
+  process.stdout.write(text, () => process.exit(exitCode));
+}
+
+function resolveHookResult(raw, output) {
+  if (typeof output === 'string' || Buffer.isBuffer(output)) {
+    return { stdout: String(output), exitCode: 0 };
+  }
+
+  if (output && typeof output === 'object') {
+    writeStderr(output.stderr);
+    const exitCode = Number.isInteger(output.exitCode) ? output.exitCode : 0;
+
+    if (Object.prototype.hasOwnProperty.call(output, 'additionalContext')) {
+      return { stdout: buildPreToolUseAdditionalContext(output.additionalContext), exitCode };
+    }
+    if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {
+      return { stdout: String(output.stdout ?? ''), exitCode };
+    }
+    return { stdout: exitCode === 0 ? raw : '', exitCode };
+  }
+
+  return { stdout: raw, exitCode: 0 };
+}
+
+function resolveLegacySpawnStdout(raw, result) {
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  if (stdout) {
+    return stdout;
+  }
+
+  if (Number.isInteger(result.status) && result.status === 0) {
+    return raw;
+  }
+
+  return '';
+}
+
+function getPluginRoot() {
+  if (process.env.THEUS_PLUGIN_ROOT && process.env.THEUS_PLUGIN_ROOT.trim()) {
+    return process.env.THEUS_PLUGIN_ROOT;
+  }
+  return path.resolve(__dirname, '..', '..');
+}
+
+// Extrae de forma segura el contexto objetivo desde el JSON de stdin del hook,
+// para la previsualización en modo dry-run.
+
+function extractTargetContext(raw) {
+  const result = { tool: '', filePath: '', command: '' };
+  if (!raw || typeof raw !== 'string') return result;
+
+  try {
+    const payload = JSON.parse(raw);
+    if (payload && typeof payload === 'object') {
+      result.tool = String(payload.tool || '');
+      const input = payload.tool_input;
+      if (input && typeof input === 'object') {
+        result.filePath = String(input.file_path || input.path || '');
+        result.command = String(input.command || '');
+      }
+    }
+  } catch {
+    // Extracción de campos de mejor esfuerzo; ignorar entradas malformadas
+  }
+  return result;
+}
+
+// Construye la línea de previsualización [DryRun] para stderr.
+
+function buildDryRunPreview(hookId, relScriptPath, profilesCsv, raw) {
+  const ctx = extractTargetContext(raw);
+  const parts = [`[DryRun] El hook "${hookId}" ejecutaría: ${relScriptPath}`, `(habilitado=true, perfiles=${profilesCsv || 'default'})`];
+
+  if (ctx.tool) {
+    parts.push(`tool=${ctx.tool}`);
+  }
+  if (ctx.filePath) {
+    parts.push(`target=${ctx.filePath}`);
+  }
+  if (ctx.command) {
+    parts.push(`command=${ctx.command}`);
+  }
+
+  return parts.join(' ') + '\n';
+}
+
+async function main() {
+  const [, , hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+
+  // Payloads sobredimensionados: nunca reenviar la cadena truncada — un
+  // documento JSON cortado a medias es tratado por el motor como un fallo
+  // del hook, bloqueando la llamada a la herramienta. Stdout vacío + exit 0
+  // significa "sin opinión", así que las rutas de pass-through fallan en
+  // abierto. El hook igual se ejecuta y recibe la bandera de truncamiento
+  // (contexto de run() / THEUS_HOOK_INPUT_TRUNCATED), de modo que los hooks
+  // de seguridad como config-protection aún pueden decidir bloquear.
+  const sanitizeEcho = text => (truncated && text === raw ? '' : text);
+  if (truncated) {
+    process.stderr.write(`[Hook] stdin superó ${MAX_STDIN} bytes para ${hookId || 'desconocido'}; se suprime el pass-through (falla en abierto salvo que el hook bloquee)\n`);
+  }
+
+  if (!hookId || !relScriptPath) {
+    exitWithStdout(sanitizeEcho(raw), 0);
+    return;
+  }
+
+  if (!isHookEnabled(hookId, { profiles: profilesCsv })) {
+    exitWithStdout(sanitizeEcho(raw), 0);
+    return;
+  }
+
+  if (isDryRun()) {
+    const preview = buildDryRunPreview(hookId, relScriptPath, profilesCsv, raw);
+    process.stderr.write(preview);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  const pluginRoot = getPluginRoot();
+  const resolvedRoot = path.resolve(pluginRoot);
+  const scriptPath = path.resolve(pluginRoot, relScriptPath);
+
+  // Prevenir path traversal fuera de la raíz del plugin
+  if (!scriptPath.startsWith(resolvedRoot + path.sep)) {
+    process.stderr.write(`[Hook] Path traversal rechazado para ${hookId}: ${scriptPath}\n`);
+    exitWithStdout(sanitizeEcho(raw), 0);
+    return;
+  }
+
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`[Hook] Script no encontrado para ${hookId}: ${scriptPath}\n`);
+    exitWithStdout(sanitizeEcho(raw), 0);
+    return;
+  }
+
+  // Preferir require() directo cuando el hook exporta una función run(rawInput).
+  // Esto elimina un spawn de proceso Node.js (~50-100 ms de ahorro por hook).
+  //
+  // SEGURIDAD: solo hacer require() de hooks que exporten run(). Los hooks
+  // legacy ejecutan efectos secundarios a nivel de módulo (listeners de stdin,
+  // process.exit, llamadas a main()) que interferirían con el proceso padre
+  // o causarían doble ejecución.
+  let hookModule;
+  const src = fs.readFileSync(scriptPath, 'utf8');
+  const hasRunExport = /\bmodule\.exports\b/.test(src) && /\brun\b/.test(src);
+
+  if (hasRunExport) {
+    try {
+      hookModule = require(scriptPath);
+    } catch (requireErr) {
+      process.stderr.write(`[Hook] require() falló para ${hookId}: ${requireErr.message}\n`);
+      // Continuar hacia la ruta legacy con spawnSync
+    }
+  }
+
+  if (hookModule && typeof hookModule.run === 'function') {
+    try {
+      const output = hookModule.run(raw, {
+        hookId,
+        pluginRoot,
+        scriptPath,
+        truncated,
+        maxStdin: MAX_STDIN
+      });
+      const result = resolveHookResult(raw, output);
+      exitWithStdout(sanitizeEcho(result.stdout), result.exitCode);
+    } catch (runErr) {
+      process.stderr.write(`[Hook] Error en run() para ${hookId}: ${runErr.message}\n`);
+      exitWithStdout(sanitizeEcho(raw), 0);
+    }
+    return;
+  }
+
+  // Ruta legacy: lanzar un proceso Node hijo para hooks sin export run()
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: raw,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      THEUS_PLUGIN_ROOT: pluginRoot,
+      THEUS_HOOK_ID: hookId,
+      THEUS_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      THEUS_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN)
+    },
+    cwd: process.cwd(),
+    timeout: 30000
+  });
+
+  const legacyStdout = sanitizeEcho(resolveLegacySpawnStdout(raw, result));
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  if (result.error || result.signal || result.status === null) {
+    const failureDetail = result.error ? result.error.message : result.signal ? `terminado por la señal ${result.signal}` : 'sin código de salida';
+    writeStderr(`[Hook] La ejecución del hook legacy falló para ${hookId}: ${failureDetail}`);
+    exitWithStdout(legacyStdout, 1);
+    return;
+  }
+
+  exitWithStdout(legacyStdout, Number.isInteger(result.status) ? result.status : 0);
+}
+
+main().catch(err => {
+  process.stderr.write(`[Hook] Error de run-with-flags: ${err.message}\n`);
+  process.exit(0);
+});