theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/scripts/lib/utils.js

@@ -1,658 +0,0 @@
-/**
- * Funciones utilitarias multiplataforma para hooks y scripts de Theus
- * Funciona en Windows, macOS y Linux
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-const { execSync, spawnSync } = require('child_process');
-
-// Detección de plataforma
-const isWindows = process.platform === 'win32';
-const isMacOS = process.platform === 'darwin';
-const isLinux = process.platform === 'linux';
-const SESSION_DATA_DIR_NAME = 'session-data';
-const LEGACY_SESSIONS_DIR_NAME = 'sessions';
-const {
-  resolveAgentDataHome,
-} = require('./agent-data-home');
-const WINDOWS_RESERVED_SESSION_IDS = new Set([
-  'CON', 'PRN', 'AUX', 'NUL',
-  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
-  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'
-]);
-
-/**
- * Obtiene el directorio home del usuario (multiplataforma)
- */
-function getHomeDir() {
-  const explicitHome = process.env.HOME || process.env.USERPROFILE;
-  if (explicitHome && explicitHome.trim().length > 0) {
-    return path.resolve(explicitHome);
-  }
-  return os.homedir();
-}
-
-/**
- * Raíz de datos del agente Theus para persistencia de memoria
- * (ver scripts/lib/agent-data-home.js).
- */
-function getAgentDataHome() {
-  return resolveAgentDataHome();
-}
-
-/**
- * Obtiene el directorio de configuración de Theus
- * (alias de getAgentDataHome por compatibilidad).
- */
-function getTheusDir() {
-  return getAgentDataHome();
-}
-
-
-/**
- * Obtiene el directorio de sesiones
- */
-function getSessionsDir() {
-  return path.join(getTheusDir(), SESSION_DATA_DIR_NAME);
-}
-
-/**
- * Obtiene el directorio de sesiones heredado (formato antiguo)
- */
-function getLegacySessionsDir() {
-  return path.join(getTheusDir(), LEGACY_SESSIONS_DIR_NAME);
-}
-
-/**
- * Obtiene todos los directorios de sesiones a explorar, el canónico primero
- */
-function getSessionSearchDirs() {
-  return Array.from(new Set([getSessionsDir(), getLegacySessionsDir()]));
-}
-
-/**
- * Obtiene el directorio de skills aprendidas
- */
-function getLearnedSkillsDir() {
-  return path.join(getTheusDir(), 'skills', 'learned');
-}
-
-/**
- * Obtiene el directorio temporal (multiplataforma)
- */
-function getTempDir() {
-  return os.tmpdir();
-}
-
-/**
- * Garantiza que un directorio exista (lo crea si no)
- * @param {string} dirPath - Ruta del directorio a crear
- * @returns {string} La ruta del directorio
- * @throws {Error} Si el directorio no puede crearse (p. ej., permiso denegado)
- */
-function ensureDir(dirPath) {
-  try {
-    if (!fs.existsSync(dirPath)) {
-      fs.mkdirSync(dirPath, { recursive: true });
-    }
-  } catch (err) {
-    // EEXIST es aceptable (condición de carrera con otro proceso creándolo)
-    if (err.code !== 'EEXIST') {
-      throw new Error(`No se pudo crear el directorio '${dirPath}': ${err.message}`);
-    }
-  }
-  return dirPath;
-}
-
-/**
- * Obtiene la fecha actual en formato YYYY-MM-DD
- */
-function getDateString() {
-  const now = new Date();
-  const year = now.getFullYear();
-  const month = String(now.getMonth() + 1).padStart(2, '0');
-  const day = String(now.getDate()).padStart(2, '0');
-  return `${year}-${month}-${day}`;
-}
-
-/**
- * Obtiene la hora actual en formato HH:MM
- */
-function getTimeString() {
-  const now = new Date();
-  const hours = String(now.getHours()).padStart(2, '0');
-  const minutes = String(now.getMinutes()).padStart(2, '0');
-  return `${hours}:${minutes}`;
-}
-
-/**
- * Obtiene el nombre del repositorio git
- */
-function getGitRepoName() {
-  const result = runCommand('git rev-parse --show-toplevel');
-  if (!result.success) return null;
-  return path.basename(result.output);
-}
-
-/**
- * Obtiene el nombre del proyecto a partir del repo git o del directorio actual
- */
-function getProjectName() {
-  const repoName = getGitRepoName();
-  if (repoName) return repoName;
-  return path.basename(process.cwd()) || null;
-}
-
-/**
- * Sanitiza una cadena para usarla como segmento de nombre de archivo de sesión.
- * Reemplaza los caracteres inválidos por guiones, colapsa repeticiones, elimina
- * guiones al inicio/final y quita los puntos iniciales para que nombres de
- * directorios ocultos como ".theus" se mapeen limpiamente a "theus".
- *
- * Las entradas puramente no ASCII reciben un hash estable de 8 caracteres para
- * que nombres distintos no colapsen al mismo id de sesión de respaldo. Las
- * entradas de escritura mixta conservan su parte ASCII y ganan un sufijo hash
- * corto para desambiguar.
- */
-function sanitizeSessionId(raw) {
-  if (!raw || typeof raw !== 'string') return null;
-
-  const hasNonAscii = Array.from(raw).some(char => char.codePointAt(0) > 0x7f);
-  const normalized = raw.replace(/^\.+/, '');
-  const sanitized = normalized
-    .replace(/[^a-zA-Z0-9_-]/g, '-')
-    .replace(/-{2,}/g, '-')
-    .replace(/^-+|-+$/g, '');
-
-  if (sanitized.length > 0) {
-    const suffix = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 6);
-    if (WINDOWS_RESERVED_SESSION_IDS.has(sanitized.toUpperCase())) {
-      return `${sanitized}-${suffix}`;
-    }
-    if (!hasNonAscii) return sanitized;
-    return `${sanitized}-${suffix}`;
-  }
-
-  const meaningful = normalized.replace(/[\s\p{P}]/gu, '');
-  if (meaningful.length === 0) return null;
-
-  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 8);
-}
-
-/**
- * Obtiene el id corto de sesión a partir del `session_id` que el motor Theus
- * entrega a los hooks por stdin (JSON). No existe una variable de entorno con
- * el id de sesión: el hook debe leer el JSON de stdin y pasar aquí el campo
- * `session_id`.
- *
- * Devuelve los últimos 8 caracteres del id; si no hay id, cae al nombre
- * sanitizado del proyecto y luego al valor de respaldo.
- *
- * @param {string} [fallback='default'] - Valor de respaldo final
- * @param {string} [sessionId] - `session_id` leído del JSON de stdin del hook
- */
-function getSessionIdShort(fallback = 'default', sessionId = '') {
-  if (sessionId && typeof sessionId === 'string' && sessionId.length > 0) {
-    const sanitized = sanitizeSessionId(sessionId.slice(-8));
-    if (sanitized) return sanitized;
-  }
-  return sanitizeSessionId(getProjectName()) || sanitizeSessionId(fallback) || 'default';
-}
-
-/**
- * Obtiene la fecha y hora actuales en formato YYYY-MM-DD HH:MM:SS
- */
-function getDateTimeString() {
-  const now = new Date();
-  const year = now.getFullYear();
-  const month = String(now.getMonth() + 1).padStart(2, '0');
-  const day = String(now.getDate()).padStart(2, '0');
-  const hours = String(now.getHours()).padStart(2, '0');
-  const minutes = String(now.getMinutes()).padStart(2, '0');
-  const seconds = String(now.getSeconds()).padStart(2, '0');
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
-}
-
-/**
- * Busca archivos que coincidan con un patrón en un directorio
- * (alternativa multiplataforma a find)
- * @param {string} dir - Directorio donde buscar
- * @param {string} pattern - Patrón de archivo (p. ej., "*.tmp", "*.md")
- * @param {object} options - Opciones { maxAge: días, recursive: boolean }
- */
-function findFiles(dir, pattern, options = {}) {
-  if (!dir || typeof dir !== 'string') return [];
-  if (!pattern || typeof pattern !== 'string') return [];
-
-  const { maxAge = null, recursive = false } = options;
-  const results = [];
-
-  if (!fs.existsSync(dir)) {
-    return results;
-  }
-
-  // Escapa todos los caracteres especiales de regex y luego convierte los
-  // comodines glob. El orden importa: primero escapar especiales, luego
-  // convertir * y ? a sus equivalentes regex.
-  const regexPattern = pattern
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    .replace(/\*/g, '.*')
-    .replace(/\?/g, '.');
-  const regex = new RegExp(`^${regexPattern}$`);
-
-  function searchDir(currentDir) {
-    try {
-      const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        const fullPath = path.join(currentDir, entry.name);
-
-        if (entry.isFile() && regex.test(entry.name)) {
-          let stats;
-          try {
-            stats = fs.statSync(fullPath);
-          } catch {
-            continue; // Archivo borrado entre readdir y stat
-          }
-
-          if (maxAge !== null) {
-            const ageInDays = (Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24);
-            if (ageInDays <= maxAge) {
-              results.push({ path: fullPath, mtime: stats.mtimeMs });
-            }
-          } else {
-            results.push({ path: fullPath, mtime: stats.mtimeMs });
-          }
-        } else if (entry.isDirectory() && recursive) {
-          searchDir(fullPath);
-        }
-      }
-    } catch (_err) {
-      // Ignorar errores de permisos
-    }
-  }
-
-  searchDir(dir);
-
-  // Ordenar por fecha de modificación (más reciente primero)
-  results.sort((a, b) => b.mtime - a.mtime);
-
-  return results;
-}
-
-/**
- * Lee JSON desde stdin (para la entrada de los hooks)
- * @param {object} options - Opciones
- * @param {number} options.timeoutMs - Timeout en milisegundos (por defecto: 5000).
- *   Evita que los hooks queden colgados indefinidamente si stdin nunca se cierra.
- * @returns {Promise<object>} Objeto JSON parseado, u objeto vacío si stdin está vacío
- */
-async function readStdinJson(options = {}) {
-  const { timeoutMs = 5000, maxSize = 1024 * 1024 } = options;
-
-  return new Promise((resolve) => {
-    let data = '';
-    let settled = false;
-
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true;
-        // Limpia los listeners de stdin para que el event loop pueda salir
-        process.stdin.removeAllListeners('data');
-        process.stdin.removeAllListeners('end');
-        process.stdin.removeAllListeners('error');
-        if (process.stdin.unref) process.stdin.unref();
-        // Resuelve con lo acumulado hasta ahora en lugar de quedar colgado
-        try {
-          resolve(data.trim() ? JSON.parse(data) : {});
-        } catch {
-          resolve({});
-        }
-      }
-    }, timeoutMs);
-
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => {
-      if (data.length < maxSize) {
-        data += chunk;
-      }
-    });
-
-    process.stdin.on('end', () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      try {
-        resolve(data.trim() ? JSON.parse(data) : {});
-      } catch {
-        // Consistente con la ruta de timeout: resuelve con objeto vacío
-        // para que los hooks no fallen con entrada malformada
-        resolve({});
-      }
-    });
-
-    process.stdin.on('error', () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      // Resuelve con objeto vacío para que los hooks no fallen ante errores de stdin
-      resolve({});
-    });
-  });
-}
-
-/**
- * Escribe en stderr (visible para el usuario en la terminal de Theus)
- */
-function log(message) {
-  console.error(message);
-}
-
-/**
- * Escribe en stdout (se devuelve al agente)
- */
-function output(data) {
-  if (typeof data === 'object') {
-    console.log(JSON.stringify(data));
-  } else {
-    console.log(data);
-  }
-}
-
-/**
- * Lee un archivo de texto de forma segura
- */
-function readFile(filePath) {
-  try {
-    return fs.readFileSync(filePath, 'utf8');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Escribe un archivo de texto
- */
-function writeFile(filePath, content) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, content, 'utf8');
-}
-
-/**
- * Agrega contenido al final de un archivo de texto
- */
-function appendFile(filePath, content) {
-  ensureDir(path.dirname(filePath));
-  fs.appendFileSync(filePath, content, 'utf8');
-}
-
-/**
- * Comprueba si un comando existe en el PATH
- * Usa spawnSync para prevenir inyección de comandos
- */
-function commandExists(cmd) {
-  // Valida el nombre del comando: solo alfanuméricos, guion, guion bajo y punto
-  if (!/^[a-zA-Z0-9_.-]+$/.test(cmd)) {
-    return false;
-  }
-
-  try {
-    if (isWindows) {
-      // Usa spawnSync para evitar la interpolación de shell
-      const result = spawnSync('where', [cmd], { stdio: 'pipe' });
-      return result.status === 0;
-    } else {
-      const result = spawnSync('which', [cmd], { stdio: 'pipe' });
-      return result.status === 0;
-    }
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Ejecuta un comando y devuelve su salida
- *
- * NOTA DE SEGURIDAD: esta función ejecuta comandos de shell. Úsala solo con
- * comandos confiables y fijos en el código. Nunca pases entrada controlada
- * por el usuario directamente. Para entrada del usuario, usa spawnSync con
- * arreglos de argumentos.
- *
- * @param {string} cmd - Comando a ejecutar (debe ser confiable/fijo en el código)
- * @param {object} options - Opciones de execSync
- */
-function runCommand(cmd, options = {}) {
-  // Lista de permitidos: solo prefijos de comando conocidos como seguros
-  const allowedPrefixes = ['git ', 'node ', 'npx ', 'which ', 'where '];
-  if (!allowedPrefixes.some(prefix => cmd.startsWith(prefix))) {
-    return { success: false, output: 'runCommand bloqueado: prefijo de comando no reconocido' };
-  }
-
-  // Rechaza metacaracteres de shell. $() y las comillas invertidas se evalúan
-  // dentro de comillas dobles, así que se bloquean $ y ` en cualquier parte
-  // de cmd. Los demás operadores (;|&) son literales dentro de comillas, por
-  // lo que solo se revisan las porciones sin comillas.
-  const unquoted = cmd.replace(/"[^"]*"/g, '').replace(/'[^']*'/g, '');
-  if (/[;|&\n]/.test(unquoted) || /[`$]/.test(cmd)) {
-    return { success: false, output: 'runCommand bloqueado: metacaracteres de shell no permitidos' };
-  }
-
-  try {
-    const result = execSync(cmd, {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      ...options
-    });
-    return { success: true, output: result.trim() };
-  } catch (err) {
-    return { success: false, output: err.stderr || err.message };
-  }
-}
-
-/**
- * Comprueba si el directorio actual es un repositorio git
- */
-function isGitRepo() {
-  return runCommand('git rev-parse --git-dir').success;
-}
-
-/**
- * Obtiene los archivos modificados según git, opcionalmente filtrados por patrones regex
- * @param {string[]} patterns - Arreglo de patrones regex (como cadenas) para filtrar
- *   archivos. Los patrones inválidos se omiten silenciosamente.
- * @returns {string[]} Arreglo de rutas de archivos modificados
- */
-function getGitModifiedFiles(patterns = []) {
-  if (!isGitRepo()) return [];
-
-  const result = runCommand('git diff --name-only HEAD');
-  if (!result.success) return [];
-
-  let files = result.output.split('\n').filter(Boolean);
-
-  if (patterns.length > 0) {
-    // Precompila los patrones, omitiendo los inválidos
-    const compiled = [];
-    for (const pattern of patterns) {
-      if (typeof pattern !== 'string' || pattern.length === 0) continue;
-      try {
-        compiled.push(new RegExp(pattern));
-      } catch {
-        // Omite patrones regex inválidos
-      }
-    }
-    if (compiled.length > 0) {
-      files = files.filter(file => compiled.some(regex => regex.test(file)));
-    }
-  }
-
-  return files;
-}
-
-/**
- * Reemplaza texto en un archivo (alternativa multiplataforma a sed)
- * @param {string} filePath - Ruta del archivo
- * @param {string|RegExp} search - Patrón a buscar. Los patrones tipo cadena
- *   reemplazan SOLO la primera coincidencia; usa un RegExp con la bandera `g`
- *   para reemplazo global.
- * @param {string} replace - Cadena de reemplazo
- * @param {object} options - Opciones
- * @param {boolean} options.all - Si es true y search es una cadena, reemplaza
- *   TODAS las coincidencias (usa String.replaceAll). Se ignora para RegExp.
- * @returns {boolean} true si el archivo se escribió, false si hubo error
- */
-function replaceInFile(filePath, search, replace, options = {}) {
-  const content = readFile(filePath);
-  if (content === null) return false;
-
-  try {
-    let newContent;
-    if (options.all && typeof search === 'string') {
-      newContent = content.replaceAll(search, replace);
-    } else {
-      newContent = content.replace(search, replace);
-    }
-    writeFile(filePath, newContent);
-    return true;
-  } catch (err) {
-    log(`[Utils] replaceInFile falló para ${filePath}: ${err.message}`);
-    return false;
-  }
-}
-
-/**
- * Cuenta las ocurrencias de un patrón en un archivo
- * @param {string} filePath - Ruta del archivo
- * @param {string|RegExp} pattern - Patrón a contar. Las cadenas se tratan como
- *   patrones regex globales. Las instancias RegExp se usan tal cual, pero se
- *   fuerza la bandera global para garantizar un conteo correcto.
- * @returns {number} Número de coincidencias encontradas
- */
-function countInFile(filePath, pattern) {
-  const content = readFile(filePath);
-  if (content === null) return 0;
-
-  let regex;
-  try {
-    if (pattern instanceof RegExp) {
-      // Siempre crea un RegExp nuevo para evitar estado lastIndex compartido;
-      // garantiza la bandera global
-      regex = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g');
-    } else if (typeof pattern === 'string') {
-      regex = new RegExp(pattern, 'g');
-    } else {
-      return 0;
-    }
-  } catch {
-    return 0; // Patrón regex inválido
-  }
-  const matches = content.match(regex);
-  return matches ? matches.length : 0;
-}
-
-/**
- * Elimina todas las secuencias de escape ANSI de una cadena.
- *
- * Maneja:
- * - Secuencias CSI: \x1b[ … <letra>  (colores, movimiento del cursor, borrado, etc.)
- * - Secuencias OSC: \x1b] … BEL/ST    (títulos de ventana, hipervínculos)
- * - Selección de charset: \x1b(B
- * - ESC + una letra: \x1b <letra>  (p. ej. \x1bM para índice inverso)
- *
- * @param {string} str - Cadena de entrada que posiblemente contenga códigos ANSI
- * @returns {string} Cadena limpia sin secuencias de escape
- */
-function stripAnsi(str) {
-  if (typeof str !== 'string') return '';
-  // eslint-disable-next-line no-control-regex
-  return str.replace(/\x1b(?:\[[0-9;?]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|\([A-Z]|[A-Z])/g, '');
-}
-
-/**
- * Busca un patrón en un archivo y devuelve las líneas coincidentes con su número de línea
- */
-function grepFile(filePath, pattern) {
-  const content = readFile(filePath);
-  if (content === null) return [];
-
-  let regex;
-  try {
-    if (pattern instanceof RegExp) {
-      // Siempre crea un RegExp nuevo sin la bandera 'g' para prevenir problemas
-      // de estado con lastIndex al usar .test() en un bucle (la bandera g hace
-      // que .test() sea con estado, alternando acierto/fallo en líneas
-      // coincidentes consecutivas)
-      const flags = pattern.flags.replace('g', '');
-      regex = new RegExp(pattern.source, flags);
-    } else {
-      regex = new RegExp(pattern);
-    }
-  } catch {
-    return []; // Patrón regex inválido
-  }
-  const lines = content.split('\n');
-  const results = [];
-
-  lines.forEach((line, index) => {
-    if (regex.test(line)) {
-      results.push({ lineNumber: index + 1, content: line });
-    }
-  });
-
-  return results;
-}
-
-module.exports = {
-  // Información de plataforma
-  isWindows,
-  isMacOS,
-  isLinux,
-
-  // Directorios
-  getHomeDir,
-  getAgentDataHome,
-  getTheusDir,
-  getSessionsDir,
-  getLegacySessionsDir,
-  getSessionSearchDirs,
-  getLearnedSkillsDir,
-  getTempDir,
-  ensureDir,
-
-  // Fecha/Hora
-  getDateString,
-  getTimeString,
-  getDateTimeString,
-
-  // Sesión/Proyecto
-  sanitizeSessionId,
-  getSessionIdShort,
-  getGitRepoName,
-  getProjectName,
-
-  // Operaciones con archivos
-  findFiles,
-  readFile,
-  writeFile,
-  appendFile,
-  replaceInFile,
-  countInFile,
-  grepFile,
-
-  // Sanitización de cadenas
-  stripAnsi,
-
-  // E/S de hooks
-  readStdinJson,
-  log,
-  output,
-
-  // Sistema
-  commandExists,
-  runCommand,
-  isGitRepo,
-  getGitModifiedFiles
-};