theus-cli 0.2.36 → 0.2.38

package/vendor/theus-arsenal/scripts/lib/session-aliases.js

@@ -0,0 +1,483 @@
+/**
+ * Biblioteca de alias de sesión para Theus
+ * Administra los alias de sesión guardados en `<data home>/session-aliases.json`
+ * (por defecto `~/.theus/arsenal`; THEUS_AGENT_DATA_HOME lo redefine).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  getTheusDir,
+  ensureDir,
+  readFile,
+  log
+} = require('./utils');
+
+// Ruta del archivo de alias
+function getAliasesPath() {
+  return path.join(getTheusDir(), 'session-aliases.json');
+}
+
+// Versión actual del formato de almacenamiento de alias
+const ALIAS_VERSION = '1.0';
+
+/**
+ * Estructura por defecto del archivo de alias
+ */
+function getDefaultAliases() {
+  return {
+    version: ALIAS_VERSION,
+    aliases: {},
+    metadata: {
+      totalCount: 0,
+      lastUpdated: new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * Carga los alias desde el archivo
+ * @returns {object} Objeto de alias
+ */
+function loadAliases() {
+  const aliasesPath = getAliasesPath();
+
+  if (!fs.existsSync(aliasesPath)) {
+    return getDefaultAliases();
+  }
+
+  const content = readFile(aliasesPath);
+  if (!content) {
+    return getDefaultAliases();
+  }
+
+  try {
+    const data = JSON.parse(content);
+
+    // Validar la estructura
+    if (!data.aliases || typeof data.aliases !== 'object') {
+      log('[Aliases] Estructura inválida del archivo de alias, reiniciando');
+      return getDefaultAliases();
+    }
+
+    // Garantizar el campo de versión
+    if (!data.version) {
+      data.version = ALIAS_VERSION;
+    }
+
+    // Garantizar los metadatos
+    if (!data.metadata) {
+      data.metadata = {
+        totalCount: Object.keys(data.aliases).length,
+        lastUpdated: new Date().toISOString()
+      };
+    }
+
+    return data;
+  } catch (err) {
+    log(`[Aliases] Error al parsear el archivo de alias: ${err.message}`);
+    return getDefaultAliases();
+  }
+}
+
+/**
+ * Guarda los alias en el archivo con escritura atómica
+ * @param {object} aliases - Objeto de alias a guardar
+ * @returns {boolean} Estado de éxito
+ */
+function saveAliases(aliases) {
+  const aliasesPath = getAliasesPath();
+  const tempPath = aliasesPath + '.tmp';
+  const backupPath = aliasesPath + '.bak';
+
+  try {
+    // Actualizar los metadatos
+    aliases.metadata = {
+      totalCount: Object.keys(aliases.aliases).length,
+      lastUpdated: new Date().toISOString()
+    };
+
+    const content = JSON.stringify(aliases, null, 2);
+
+    // Garantizar que el directorio exista
+    ensureDir(path.dirname(aliasesPath));
+
+    // Crear un respaldo si el archivo existe
+    if (fs.existsSync(aliasesPath)) {
+      fs.copyFileSync(aliasesPath, backupPath);
+    }
+
+    // Escritura atómica: escribir a un archivo temporal y luego renombrar
+    fs.writeFileSync(tempPath, content, 'utf8');
+
+    // En Windows, rename falla con EEXIST si el destino existe, así que se
+    // elimina primero. En Unix/macOS, rename(2) reemplaza el destino de forma
+    // atómica — se omite la eliminación para evitar una ventana no atómica
+    // innecesaria entre unlink y rename.
+    if (process.platform === 'win32' && fs.existsSync(aliasesPath)) {
+      fs.unlinkSync(aliasesPath);
+    }
+    fs.renameSync(tempPath, aliasesPath);
+
+    // Eliminar el respaldo si todo salió bien
+    if (fs.existsSync(backupPath)) {
+      fs.unlinkSync(backupPath);
+    }
+
+    return true;
+  } catch (err) {
+    log(`[Aliases] Error al guardar los alias: ${err.message}`);
+
+    // Restaurar desde el respaldo si existe
+    if (fs.existsSync(backupPath)) {
+      try {
+        fs.copyFileSync(backupPath, aliasesPath);
+        log('[Aliases] Restaurado desde el respaldo');
+      } catch (restoreErr) {
+        log(`[Aliases] No se pudo restaurar el respaldo: ${restoreErr.message}`);
+      }
+    }
+
+    // Limpiar el archivo temporal (mejor esfuerzo)
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+    } catch {
+      // No crítico: el archivo temporal se sobreescribirá en el próximo guardado
+    }
+
+    return false;
+  }
+}
+
+/**
+ * Resuelve un alias para obtener la ruta de la sesión
+ * @param {string} alias - Nombre del alias a resolver
+ * @returns {object|null} Datos del alias o null si no se encuentra
+ */
+function resolveAlias(alias) {
+  if (!alias) return null;
+
+  // Validar el nombre del alias (alfanumérico, guion, guion bajo)
+  if (!/^[a-zA-Z0-9_-]+$/.test(alias)) {
+    return null;
+  }
+
+  const data = loadAliases();
+  const aliasData = data.aliases[alias];
+
+  if (!aliasData) {
+    return null;
+  }
+
+  return {
+    alias,
+    sessionPath: aliasData.sessionPath,
+    createdAt: aliasData.createdAt,
+    title: aliasData.title || null
+  };
+}
+
+/**
+ * Crea o actualiza un alias para una sesión
+ * @param {string} alias - Nombre del alias (alfanumérico, guion, guion bajo)
+ * @param {string} sessionPath - Ruta del directorio de la sesión
+ * @param {string} title - Título opcional para el alias
+ * @returns {object} Resultado con estado de éxito y mensaje
+ */
+function setAlias(alias, sessionPath, title = null) {
+  // Validar el nombre del alias
+  if (!alias || alias.length === 0) {
+    return { success: false, error: 'El nombre del alias no puede estar vacío' };
+  }
+
+  // Validar la ruta de la sesión
+  if (!sessionPath || typeof sessionPath !== 'string' || sessionPath.trim().length === 0) {
+    return { success: false, error: 'La ruta de la sesión no puede estar vacía' };
+  }
+
+  if (alias.length > 128) {
+    return { success: false, error: 'El nombre del alias no puede exceder 128 caracteres' };
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(alias)) {
+    return { success: false, error: 'El nombre del alias solo puede contener letras, números, guiones y guiones bajos' };
+  }
+
+  // Nombres de alias reservados
+  const reserved = ['list', 'help', 'remove', 'delete', 'create', 'set'];
+  if (reserved.includes(alias.toLowerCase())) {
+    return { success: false, error: `'${alias}' es un nombre de alias reservado` };
+  }
+
+  const data = loadAliases();
+  const existing = data.aliases[alias];
+  const isNew = !existing;
+
+  data.aliases[alias] = {
+    sessionPath,
+    createdAt: existing ? existing.createdAt : new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    title: title || null
+  };
+
+  if (saveAliases(data)) {
+    return {
+      success: true,
+      isNew,
+      alias,
+      sessionPath,
+      title: data.aliases[alias].title
+    };
+  }
+
+  return { success: false, error: 'No se pudo guardar el alias' };
+}
+
+/**
+ * Lista todos los alias
+ * @param {object} options - Objeto de opciones
+ * @param {string} options.search - Filtrar alias por nombre (coincidencia parcial)
+ * @param {number} options.limit - Número máximo de alias a devolver
+ * @returns {Array} Arreglo de objetos de alias
+ */
+function listAliases(options = {}) {
+  const { search = null, limit = null } = options;
+  const data = loadAliases();
+
+  let aliases = Object.entries(data.aliases).map(([name, info]) => ({
+    name,
+    sessionPath: info.sessionPath,
+    createdAt: info.createdAt,
+    updatedAt: info.updatedAt,
+    title: info.title
+  }));
+
+  // Ordenar por fecha de actualización (más reciente primero)
+  aliases.sort((a, b) => (new Date(b.updatedAt || b.createdAt || 0).getTime() || 0) - (new Date(a.updatedAt || a.createdAt || 0).getTime() || 0));
+
+  // Aplicar el filtro de búsqueda
+  if (search) {
+    const searchLower = search.toLowerCase();
+    aliases = aliases.filter(a =>
+      a.name.toLowerCase().includes(searchLower) ||
+      (a.title && a.title.toLowerCase().includes(searchLower))
+    );
+  }
+
+  // Aplicar el límite
+  if (limit && limit > 0) {
+    aliases = aliases.slice(0, limit);
+  }
+
+  return aliases;
+}
+
+/**
+ * Elimina un alias
+ * @param {string} alias - Nombre del alias a eliminar
+ * @returns {object} Resultado con estado de éxito
+ */
+function deleteAlias(alias) {
+  const data = loadAliases();
+
+  if (!data.aliases[alias]) {
+    return { success: false, error: `No se encontró el alias '${alias}'` };
+  }
+
+  const deleted = data.aliases[alias];
+  delete data.aliases[alias];
+
+  if (saveAliases(data)) {
+    return {
+      success: true,
+      alias,
+      deletedSessionPath: deleted.sessionPath
+    };
+  }
+
+  return { success: false, error: 'No se pudo eliminar el alias' };
+}
+
+/**
+ * Renombra un alias
+ * @param {string} oldAlias - Nombre actual del alias
+ * @param {string} newAlias - Nuevo nombre del alias
+ * @returns {object} Resultado con estado de éxito
+ */
+function renameAlias(oldAlias, newAlias) {
+  const data = loadAliases();
+
+  if (!data.aliases[oldAlias]) {
+    return { success: false, error: `No se encontró el alias '${oldAlias}'` };
+  }
+
+  // Validar el nuevo nombre del alias (mismas reglas que setAlias)
+  if (!newAlias || newAlias.length === 0) {
+    return { success: false, error: 'El nuevo nombre del alias no puede estar vacío' };
+  }
+
+  if (newAlias.length > 128) {
+    return { success: false, error: 'El nuevo nombre del alias no puede exceder 128 caracteres' };
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(newAlias)) {
+    return { success: false, error: 'El nuevo nombre del alias solo puede contener letras, números, guiones y guiones bajos' };
+  }
+
+  const reserved = ['list', 'help', 'remove', 'delete', 'create', 'set'];
+  if (reserved.includes(newAlias.toLowerCase())) {
+    return { success: false, error: `'${newAlias}' es un nombre de alias reservado` };
+  }
+
+  if (data.aliases[newAlias]) {
+    return { success: false, error: `El alias '${newAlias}' ya existe` };
+  }
+
+  const aliasData = data.aliases[oldAlias];
+  delete data.aliases[oldAlias];
+
+  aliasData.updatedAt = new Date().toISOString();
+  data.aliases[newAlias] = aliasData;
+
+  if (saveAliases(data)) {
+    return {
+      success: true,
+      oldAlias,
+      newAlias,
+      sessionPath: aliasData.sessionPath
+    };
+  }
+
+  // Restaurar el alias antiguo y quitar el nuevo si falla
+  data.aliases[oldAlias] = aliasData;
+  delete data.aliases[newAlias];
+  // Intentar persistir la reversión
+  saveAliases(data);
+  return { success: false, error: 'No se pudo guardar el alias renombrado — se revirtió al original' };
+}
+
+/**
+ * Obtiene la ruta de la sesión por alias (función de conveniencia)
+ * @param {string} aliasOrId - Nombre del alias o ID de sesión
+ * @returns {string|null} Ruta de la sesión o null si no se encuentra
+ */
+function resolveSessionAlias(aliasOrId) {
+  // Primero intentar resolverlo como alias
+  const resolved = resolveAlias(aliasOrId);
+  if (resolved) {
+    return resolved.sessionPath;
+  }
+
+  // Si no es un alias, devolverlo tal cual (podría ser una ruta de sesión)
+  return aliasOrId;
+}
+
+/**
+ * Actualiza el título de un alias
+ * @param {string} alias - Nombre del alias
+ * @param {string|null} title - Nuevo título (cadena o null para limpiar)
+ * @returns {object} Resultado con estado de éxito
+ */
+function updateAliasTitle(alias, title) {
+  if (title !== null && typeof title !== 'string') {
+    return { success: false, error: 'El título debe ser una cadena o null' };
+  }
+
+  const data = loadAliases();
+
+  if (!data.aliases[alias]) {
+    return { success: false, error: `No se encontró el alias '${alias}'` };
+  }
+
+  data.aliases[alias].title = title || null;
+  data.aliases[alias].updatedAt = new Date().toISOString();
+
+  if (saveAliases(data)) {
+    return {
+      success: true,
+      alias,
+      title
+    };
+  }
+
+  return { success: false, error: 'No se pudo actualizar el título del alias' };
+}
+
+/**
+ * Obtiene todos los alias de una sesión específica
+ * @param {string} sessionPath - Ruta de la sesión para la que buscar alias
+ * @returns {Array} Arreglo de nombres de alias
+ */
+function getAliasesForSession(sessionPath) {
+  const data = loadAliases();
+  const aliases = [];
+
+  for (const [name, info] of Object.entries(data.aliases)) {
+    if (info.sessionPath === sessionPath) {
+      aliases.push({
+        name,
+        createdAt: info.createdAt,
+        title: info.title
+      });
+    }
+  }
+
+  return aliases;
+}
+
+/**
+ * Limpia los alias de sesiones que ya no existen
+ * @param {Function} sessionExists - Función para verificar si una sesión existe
+ * @returns {object} Resultado de la limpieza
+ */
+function cleanupAliases(sessionExists) {
+  if (typeof sessionExists !== 'function') {
+    return { totalChecked: 0, removed: 0, removedAliases: [], error: 'sessionExists debe ser una función' };
+  }
+
+  const data = loadAliases();
+  const removed = [];
+
+  for (const [name, info] of Object.entries(data.aliases)) {
+    if (!sessionExists(info.sessionPath)) {
+      removed.push({ name, sessionPath: info.sessionPath });
+      delete data.aliases[name];
+    }
+  }
+
+  if (removed.length > 0 && !saveAliases(data)) {
+    log('[Aliases] No se pudo guardar tras la limpieza');
+    return {
+      success: false,
+      totalChecked: Object.keys(data.aliases).length + removed.length,
+      removed: removed.length,
+      removedAliases: removed,
+      error: 'No se pudo guardar tras la limpieza'
+    };
+  }
+
+  return {
+    success: true,
+    totalChecked: Object.keys(data.aliases).length + removed.length,
+    removed: removed.length,
+    removedAliases: removed
+  };
+}
+
+module.exports = {
+  getAliasesPath,
+  loadAliases,
+  saveAliases,
+  resolveAlias,
+  setAlias,
+  listAliases,
+  deleteAlias,
+  renameAlias,
+  resolveSessionAlias,
+  updateAliasTitle,
+  getAliasesForSession,
+  cleanupAliases
+};

package/vendor/theus-arsenal/scripts/lib/session-bridge.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * Utilidades compartidas del puente de sesión para los hooks de Theus.
+ *
+ * El archivo puente es un pequeño agregado JSON en /tmp que permite que
+ * la línea de estado, el puente de métricas y el monitor de contexto
+ * compartan estado sin escanear logs JSONL grandes en cada invocación.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX_SESSION_ID_LENGTH = 64;
+
+/**
+ * Sanitiza un ID de sesión para uso seguro en rutas de archivos.
+ * Rechaza el path traversal, elimina caracteres inseguros y limita la longitud.
+ * @param {string} raw
+ * @returns {string|null} ID de sesión seguro o null si es inválido
+ */
+function sanitizeSessionId(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  if (/[/\\]|\.\./.test(raw)) return null;
+  const safe = raw.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, MAX_SESSION_ID_LENGTH);
+  return safe || null;
+}
+
+/**
+ * Obtiene la ruta del archivo puente de una sesión.
+ * @param {string} sessionId - ID de sesión ya sanitizado
+ * @returns {string}
+ */
+function getBridgePath(sessionId) {
+  return path.join(os.tmpdir(), `theus-metrics-${sessionId}.json`);
+}
+
+/**
+ * Lee los datos del puente. Devuelve null ante cualquier error.
+ * @param {string} sessionId - ID de sesión ya sanitizado
+ * @returns {object|null}
+ */
+function readBridge(sessionId) {
+  try {
+    const raw = fs.readFileSync(getBridgePath(sessionId), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Escribe los datos del puente de forma atómica (archivo temporal con sufijo
+ * único y luego rename).
+ *
+ * La ruta temporal incluye `process.pid` más un nonce aleatorio para que los
+ * escritores concurrentes (p. ej. el hook PostToolUse del puente de métricas
+ * y la línea de estado en segundo plano, ambos escribiendo al puente de la
+ * misma sesión) no pisen el archivo temporal del otro a mitad de escritura.
+ * Con un sufijo `.tmp` fijo, dos escritores podrían llamar `writeFileSync`
+ * sobre la misma ruta antes de que cualquiera llegue a `renameSync`,
+ * haciendo que la carga de un escritor sobrescriba silenciosamente la del
+ * otro y que el segundo `renameSync` lance ENOENT cuando el rename consuma
+ * el archivo.
+ *
+ * Es el mismo patrón que usa `writeCostWarningIfChanged` en el hook del
+ * puente de métricas para la caché de avisos de costo; aquí se aplica a la
+ * primitiva del puente de sesión.
+ *
+ * @param {string} sessionId - ID de sesión ya sanitizado
+ * @param {object} data
+ */
+function writeBridgeAtomic(sessionId, data) {
+  const target = getBridgePath(sessionId);
+  const tmp = `${target}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data), 'utf8');
+  try {
+    renameWithRetry(tmp, target);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignorar */ }
+    throw err;
+  }
+}
+
+/**
+ * Reemplaza un archivo vía rename, reintentando brevemente ante errores
+ * transitorios del sistema operativo.
+ *
+ * El `rename(2)` de POSIX es atómico entre origen y destino, así que los
+ * escritores concurrentes renombran sobre el mismo destino sin conflicto.
+ * `MoveFileExW` de Windows es distinto: falla con EPERM/EACCES/EBUSY si el
+ * destino está siendo renombrado por *otro* proceso — una ventana de carrera
+ * corta que se dispara de forma consistente bajo nuestra concurrencia de
+ * PostToolUse + línea de estado.
+ *
+ * Para mantener la portabilidad, reintenta hasta 5 veces con backoff
+ * exponencial (20 ms, 40, 80, 160, 320) ante los códigos transitorios
+ * exclusivos de Windows. Las ejecuciones POSIX aciertan al primer intento y
+ * salen de inmediato. Otros códigos de error (ENOENT, ENOSPC, EROFS, …) se
+ * relanzan sin reintento — no son transitorios.
+ *
+ * La espera usa `Atomics.wait` sobre un SharedArrayBuffer desechable para que
+ * la ruta de reintento no consuma CPU en un bucle activo. Funciona en el hilo
+ * principal en Node ≥ 17 (y en workers en versiones anteriores).
+ *
+ * @param {string} tmp
+ * @param {string} target
+ */
+function renameWithRetry(tmp, target) {
+  const RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+  const MAX_ATTEMPTS = 5;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.renameSync(tmp, target);
+      return;
+    } catch (err) {
+      if (attempt + 1 >= MAX_ATTEMPTS || !RETRY_CODES.has(err.code)) {
+        throw err;
+      }
+      const delayMs = 20 << attempt;
+      try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
+      } catch {
+        // Atomics.wait lanza en el hilo principal en algunos runtimes antiguos;
+        // caer a una espera activa breve para que el reintento aún tenga retardo.
+        const until = Date.now() + delayMs;
+        while (Date.now() < until) { /* girar */ }
+      }
+    }
+  }
+}
+
+/**
+ * Resuelve el ID de sesión a partir del `session_id` que el motor Theus
+ * entrega a los hooks por stdin (campo `session_id` del JSON del evento).
+ * No existe una variable de entorno con el ID de sesión: el llamador debe
+ * leer el JSON de stdin y pasar aquí el valor crudo.
+ * @param {string} rawSessionId - `session_id` leído del stdin del hook
+ * @returns {string|null} ID de sesión sanitizado o null
+ */
+function resolveSessionId(rawSessionId) {
+  return sanitizeSessionId(rawSessionId || '');
+}
+
+module.exports = {
+  sanitizeSessionId,
+  getBridgePath,
+  readBridge,
+  writeBridgeAtomic,
+  renameWithRetry,
+  resolveSessionId,
+  MAX_SESSION_ID_LENGTH
+};