@saulwade/swl-ses 1.0.0

package/scripts/lib/hooks-settings.js

@@ -0,0 +1,789 @@
+'use strict';
+
+/**
+ * Gestión de hooks en settings.json del runtime destino.
+ *
+ * Funciones para registrar, desregistrar y verificar hooks SWL
+ * en la configuración del runtime (Claude Code, Gemini CLI, etc.).
+ *
+ * Los hooks SWL se identifican por la presencia de "hooks/" + nombre
+ * del archivo en el campo `command`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ_PKG = path.resolve(__dirname, '..', '..');
+
+/**
+ * Carga la configuración de hooks desde manifiestos/hooks-config.json
+ * @returns {object} Mapa de nombre_archivo → { event, matcher, description, blocking }
+ */
+function cargarHooksConfig() {
+  const configPath = path.join(RAIZ_PKG, 'manifiestos', 'hooks-config.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  return config.hooks;
+}
+
+/**
+ * Lee settings.json del runtime. Si no existe, retorna objeto base.
+ * @param {string} settingsPath - Ruta completa al archivo settings.json
+ * @returns {object}
+ */
+function leerSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Escribe settings.json preservando formato legible.
+ * @param {string} settingsPath
+ * @param {object} settings
+ */
+function escribirSettings(settingsPath, settings) {
+  const dir = path.dirname(settingsPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Determina si un hook entry en settings.json pertenece a SWL.
+ * @param {object} entry - { matcher, hooks: [{ type, command }] }
+ * @returns {boolean}
+ */
+function esHookSWL(entry) {
+  const hooksArr = entry.hooks || [];
+  return hooksArr.some(h => {
+    const cmd = h.command || '';
+    // Los hooks SWL usan el patrón: node hooks/nombre-hook.js
+    return /node\s+.*hooks\/[a-z-]+\.js/.test(cmd);
+  });
+}
+
+/**
+ * Calcula la ruta del settings.json para un runtime.
+ * @param {object} runtime - Configuración del runtime
+ * @param {string} base - Directorio base (.claude, ~/.claude, etc.)
+ * @returns {string} Ruta completa al settings.json
+ */
+function rutaSettings(runtime, base) {
+  const configFile = runtime.hookConfig || 'settings.json';
+  return path.join(base, configFile);
+}
+
+/**
+ * En Windows (o cuando el entorno lo solicita vía SWL_HOOKS_PATH_PREFIX),
+ * agrega ubicaciones típicas de Node al PATH del comando para resolver
+ * `node: command not found` en git-bash/MinGW y similares.
+ *
+ * El prefix es inocuo en Linux/macOS: los paths no existen y se ignoran.
+ * El usuario puede desactivarlo con SWL_HOOKS_PATH_PREFIX=0.
+ */
+function prefijoPathNode() {
+  if (process.env.SWL_HOOKS_PATH_PREFIX === '0') return '';
+  // En Windows siempre; en otros sistemas solo si se pide explícitamente.
+  const aplicar = process.platform === 'win32' || process.env.SWL_HOOKS_PATH_PREFIX === '1';
+  if (!aplicar) return '';
+  // Usamos rutas de estilo MSYS/Git-Bash: funcionan en git-bash y son
+  // ignoradas silenciosamente por `sh` en sistemas donde no existen.
+  return 'PATH="/c/Program Files/nodejs:/c/Program Files (x86)/nodejs:$PATH" ';
+}
+
+/**
+ * Decide si debe usarse el wrapper bash `hooks/_run-hook.sh` en lugar del
+ * inline `node -e`. El wrapper es más robusto contra formatters que
+ * reescriben settings.json, porque el command es corto y no contiene el
+ * prefix PATH que algunos formatters remueven.
+ *
+ * Activar con SWL_HOOKS_USAR_WRAPPER=1 (opt-in por ahora para no romper
+ * instalaciones existentes; se activará por default en v6.0.0).
+ */
+function debeUsarWrapper(hooksDir) {
+  if (process.env.SWL_HOOKS_USAR_WRAPPER === '0') return false;
+  if (process.env.SWL_HOOKS_USAR_WRAPPER !== '1') return false;
+  try {
+    const fs = require('fs');
+    const wrapperPath = path.join(hooksDir, '_run-hook.sh');
+    return fs.existsSync(wrapperPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Genera el comando para ejecutar un hook desde el directorio de trabajo.
+ * @param {string} hookFilename - Nombre del archivo de hook (ej: "escaneo-secretos.js")
+ * @param {string} hooksDir - Directorio donde se instalaron los hooks
+ * @param {boolean} esGlobal - Si es instalación global
+ * @returns {string} Comando ejecutable
+ */
+function generarComando(hookFilename, hooksDir, esGlobal) {
+  // Modo wrapper (opt-in): más resiliente contra formatters
+  if (debeUsarWrapper(hooksDir)) {
+    if (esGlobal) {
+      const wrapper = path.join(hooksDir, '_run-hook.sh').replace(/\\/g, '/');
+      const hookAbs = path.join(hooksDir, hookFilename).replace(/\\/g, '/');
+      return `bash "${wrapper}" "${hookAbs}"`;
+    }
+    return `bash ./hooks/_run-hook.sh ${hookFilename}`;
+  }
+
+  // Modo inline (default, compatible con instalaciones previas)
+  const prefix = prefijoPathNode();
+  if (esGlobal) {
+    const rutaAbsoluta = path.join(hooksDir, hookFilename).replace(/\\/g, '/');
+    return `${prefix}node -e "try{require('${rutaAbsoluta}')}catch(e){if(e.code!=='MODULE_NOT_FOUND')throw e}"`;
+  }
+  return `${prefix}node -e "try{require('./hooks/${hookFilename}')}catch(e){if(e.code!=='MODULE_NOT_FOUND')throw e}"`;
+}
+
+/**
+ * Registra los hooks SWL en settings.json del runtime.
+ * Preserva hooks existentes no-SWL. Reemplaza hooks SWL previos.
+ *
+ * @param {object} opciones
+ * @param {string} opciones.settingsPath - Ruta al settings.json
+ * @param {string} opciones.hooksDir - Directorio donde están los hooks
+ * @param {boolean} opciones.esGlobal - Si es instalación global
+ * @param {string[]} opciones.hookFiles - Lista de archivos de hooks instalados
+ * @returns {{ registrados: number, preservados: number }}
+ */
+function registrarHooks(opciones) {
+  const { settingsPath, hooksDir, esGlobal, hookFiles } = opciones;
+  const hooksConfig = cargarHooksConfig();
+  const settings = leerSettings(settingsPath);
+
+  // Inicializar sección hooks si no existe
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  let registrados = 0;
+  let preservados = 0;
+
+  // Agrupar hooks SWL por evento
+  const hooksPorEvento = {};
+  for (const filename of hookFiles) {
+    const config = hooksConfig[filename];
+    if (!config) continue;
+
+    const evento = config.event;
+    if (!hooksPorEvento[evento]) {
+      hooksPorEvento[evento] = [];
+    }
+
+    hooksPorEvento[evento].push({
+      matcher: config.matcher || '',
+      hooks: [{
+        type: 'command',
+        command: generarComando(filename, hooksDir, esGlobal),
+      }],
+    });
+    registrados++;
+  }
+
+  // Para cada tipo de evento, preservar hooks no-SWL y agregar los SWL
+  const todosEventos = new Set(['PreToolUse', 'PostToolUse']);
+  Object.keys(hooksPorEvento).forEach(e => todosEventos.add(e));
+  for (const evento of todosEventos) {
+    const existentes = settings.hooks[evento] || [];
+    const noSWL = existentes.filter(entry => !esHookSWL(entry));
+    preservados += noSWL.length;
+
+    const swlNuevos = hooksPorEvento[evento] || [];
+
+    // Limpiar entradas con matcher vacío (usar "" para match-all)
+    const swlLimpios = swlNuevos.map(h => {
+      const entry = { matcher: h.matcher || '' };
+      entry.hooks = h.hooks;
+      return entry;
+    });
+
+    const combinados = [...noSWL, ...swlLimpios];
+
+    if (combinados.length > 0) {
+      settings.hooks[evento] = combinados;
+    } else {
+      delete settings.hooks[evento];
+    }
+  }
+
+  // Limpiar sección hooks si quedó vacía
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  escribirSettings(settingsPath, settings);
+
+  return { registrados, preservados };
+}
+
+/**
+ * Desregistra todos los hooks SWL de settings.json.
+ * Preserva hooks no-SWL intactos.
+ *
+ * @param {string} settingsPath - Ruta al settings.json
+ * @returns {{ eliminados: number, preservados: number }}
+ */
+function desregistrarHooks(settingsPath) {
+  const settings = leerSettings(settingsPath);
+
+  if (!settings.hooks) {
+    return { eliminados: 0, preservados: 0 };
+  }
+
+  let eliminados = 0;
+  let preservados = 0;
+
+  // Iterar TODOS los eventos presentes en settings.json (no solo PreToolUse/PostToolUse)
+  for (const evento of Object.keys(settings.hooks)) {
+    const existentes = settings.hooks[evento] || [];
+    if (!Array.isArray(existentes)) continue;
+    const noSWL = [];
+
+    for (const entry of existentes) {
+      if (esHookSWL(entry)) {
+        eliminados++;
+      } else {
+        noSWL.push(entry);
+        preservados++;
+      }
+    }
+
+    if (noSWL.length > 0) {
+      settings.hooks[evento] = noSWL;
+    } else {
+      delete settings.hooks[evento];
+    }
+  }
+
+  // Limpiar sección hooks si quedó vacía
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  escribirSettings(settingsPath, settings);
+
+  return { eliminados, preservados };
+}
+
+/**
+ * Verifica que los hooks SWL estén correctamente registrados en settings.json.
+ *
+ * @param {string} settingsPath - Ruta al settings.json
+ * @param {string[]} hookFiles - Lista de archivos de hooks que deberían estar registrados
+ * @returns {{ ok: boolean, registrados: string[], faltantes: string[], incorrectos: string[] }}
+ */
+function verificarHooks(settingsPath, hookFiles) {
+  const hooksConfig = cargarHooksConfig();
+  const settings = leerSettings(settingsPath);
+
+  const registrados = [];
+  const faltantes = [];
+  const incorrectos = [];
+
+  for (const filename of hookFiles) {
+    const config = hooksConfig[filename];
+    if (!config) {
+      faltantes.push(filename);
+      continue;
+    }
+
+    const evento = config.event;
+    const entradas = (settings.hooks && settings.hooks[evento]) || [];
+
+    // Buscar si existe un hook SWL que referencie este archivo
+    const encontrado = entradas.find(entry => {
+      const hooksArr = entry.hooks || [];
+      return hooksArr.some(h => (h.command || '').includes(filename));
+    });
+
+    if (!encontrado) {
+      faltantes.push(filename);
+      continue;
+    }
+
+    // Verificar matcher correcto
+    const matcherEsperado = config.matcher || '';
+    const matcherActual = encontrado.matcher || '';
+
+    if (matcherEsperado !== matcherActual) {
+      incorrectos.push(`${filename}: matcher esperado="${matcherEsperado || '(ninguno)'}" actual="${matcherActual || '(ninguno)'}"`);
+      continue;
+    }
+
+    // Verificar que todos los hooks tienen type: "command"
+    const hooksSinType = (encontrado.hooks || []).filter(h => h.type !== 'command');
+    if (hooksSinType.length > 0) {
+      incorrectos.push(`${filename}: falta "type": "command" en hook entry (causa Settings Error en Claude Code)`);
+      continue;
+    }
+
+    registrados.push(filename);
+  }
+
+  return {
+    ok: faltantes.length === 0 && incorrectos.length === 0,
+    registrados,
+    faltantes,
+    incorrectos,
+  };
+}
+
+/**
+ * Repara hooks SWL en settings.json que no tienen el campo "type": "command".
+ * Claude Code requiere este campo; sin él, genera "Settings Error: type: Invalid input".
+ *
+ * @param {string} settingsPath - Ruta al settings.json
+ * @returns {{ reparados: number }}
+ */
+function repararHooks(settingsPath) {
+  const settings = leerSettings(settingsPath);
+
+  if (!settings.hooks) {
+    return { reparados: 0 };
+  }
+
+  let reparados = 0;
+
+  // Iterar TODOS los eventos presentes (no solo PreToolUse/PostToolUse)
+  for (const evento of Object.keys(settings.hooks)) {
+    const entradas = settings.hooks[evento] || [];
+    if (!Array.isArray(entradas)) continue;
+
+    for (const entry of entradas) {
+      if (!esHookSWL(entry)) continue;
+
+      const hooksArr = entry.hooks || [];
+      for (const h of hooksArr) {
+        if (h.command && h.type !== 'command') {
+          h.type = 'command';
+          reparados++;
+        }
+      }
+    }
+  }
+
+  if (reparados > 0) {
+    escribirSettings(settingsPath, settings);
+  }
+
+  return { reparados };
+}
+
+/**
+ * Agrega hooks SWL al settings.json GLOBAL (~/.claude/settings.json) sin
+ * remover hooks no-SWL ni duplicar entries SWL que ya existan.
+ *
+ * EXCEPCIÓN DOCUMENTADA (ADR-0009): Esta función es la única excepción a la
+ * regla "SWL solo registra hooks a nivel proyecto". Solo debe invocarse bajo
+ * opt-in explícito del usuario (instalador interactivo o /swl:notificaciones init).
+ *
+ * @param {string} settingsPath - Ruta al settings.json global.
+ * @param {Array<{ evento: string, matcher: string, archivo: string, hooksDir?: string|null }>} hookEntries
+ *   Lista de hooks a agregar. Cada entry describe el evento, matcher, archivo y
+ *   directorio de hooks instalados para construir el comando.
+ * @returns {{ agregados: number, preservados: number, error?: string }}
+ */
+function mergeHooksGlobales(settingsPath, hookEntries) {
+  // Validar que el archivo es JSON parseable antes de modificar
+  let settings;
+  try {
+    settings = leerSettings(settingsPath);
+  } catch (err) {
+    return { agregados: 0, preservados: 0, error: `No se puede leer settings.json: ${err.message}` };
+  }
+
+  // Verificar que el JSON existente (si existe el archivo) es válido
+  if (fs.existsSync(settingsPath)) {
+    try {
+      JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (err) {
+      return {
+        agregados:  0,
+        preservados: 0,
+        error: `settings.json tiene JSON inválido — abortando merge para proteger el archivo. Error: ${err.message}`,
+      };
+    }
+  }
+
+  // Crear backup antes de cualquier modificación
+  const ts     = Date.now();
+  const backup = `${settingsPath}.swl-backup-${ts}`;
+  if (fs.existsSync(settingsPath)) {
+    try {
+      fs.copyFileSync(settingsPath, backup);
+    } catch (err) {
+      return { agregados: 0, preservados: 0, error: `No se pudo crear backup: ${err.message}` };
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  let agregados   = 0;
+  let preservados = 0;
+  let migrados    = 0;
+
+  /**
+   * REM-C helper: detecta si dos comandos corresponden al mismo hook
+   * (mismo nombre de archivo .js) independientemente de si la ruta es
+   * relativa o absoluta.
+   *
+   * Ejemplos que deben coincidir:
+   *   "node hooks/notificacion-telegram.js"
+   *   'node "C:/Users/.../.claude/hooks/notificacion-telegram.js"'
+   *   'node "/home/user/.claude/hooks/notificacion-telegram.js"'
+   *
+   * @param {string} commandA
+   * @param {string} archivoRef - Nombre de archivo simple, ej: "notificacion-telegram.js"
+   * @returns {boolean}
+   */
+  function _mismoArchivo(commandA, archivoRef) {
+    // Extraer solo el nombre de archivo del comando (parte después del último /)
+    const match = commandA.match(/([a-z0-9-]+\.js)["']?\s*$/i);
+    if (!match) return false;
+    return match[1] === path.basename(archivoRef);
+  }
+
+  for (const entry of hookEntries) {
+    const { evento, matcher, archivo, hooksDir } = entry;
+
+    if (!settings.hooks[evento]) {
+      settings.hooks[evento] = [];
+    }
+
+    const existentes = settings.hooks[evento];
+
+    // Contar hooks no-SWL que se preservan
+    const noSWL = existentes.filter(e => !esHookSWL(e));
+    preservados += noSWL.length;
+
+    // REM-B: siempre usar ruta absoluta — si no hay hooksDir es error de configuración
+    // (quien llama debe siempre proporcionar hooksDir con HOOKS_GLOBAL_DIR)
+    const comandoNuevo = hooksDir
+      ? `node "${path.join(hooksDir, archivo).replace(/\\/g, '/')}"`
+      : `node hooks/${archivo}`; // fallback de emergencia — nunca debería usarse
+
+    // REM-C: buscar entry existente con mismo archivo (puede tener ruta relativa/incorrecta)
+    const idxExistente = existentes.findIndex(e =>
+      (e.hooks || []).some(h => h.command && _mismoArchivo(h.command, archivo))
+    );
+
+    if (idxExistente === -1) {
+      // No existe — agregar
+      settings.hooks[evento].push({
+        matcher: matcher || '',
+        hooks:   [{ type: 'command', command: comandoNuevo }],
+      });
+      agregados++;
+    } else {
+      // Existe — verificar si necesita migración de ruta relativa → absoluta
+      const entryExistente = existentes[idxExistente];
+      const commandActual  = (entryExistente.hooks || [])[0]?.command || '';
+      const esRelativo     = /^node\s+hooks\//.test(commandActual.trim());
+      const esIncorrecto   = commandActual !== comandoNuevo;
+
+      if (esRelativo || esIncorrecto) {
+        // REM-C: migrar en lugar de duplicar
+        existentes[idxExistente] = {
+          matcher: matcher || entryExistente.matcher || '',
+          hooks:   [{ type: 'command', command: comandoNuevo }],
+        };
+        migrados++;
+      }
+      // Si ya tiene el comando correcto: no-op (idempotente)
+    }
+  }
+
+  // Serializar y validar antes de escribir
+  let contenidoNuevo;
+  try {
+    contenidoNuevo = JSON.stringify(settings, null, 2) + '\n';
+    JSON.parse(contenidoNuevo); // validación pre-escritura
+  } catch (err) {
+    return {
+      agregados:  0,
+      preservados: 0,
+      error: `JSON inválido al serializar settings — operación abortada: ${err.message}`,
+    };
+  }
+
+  // Escritura atómica
+  try {
+    const atomicWrite = require('../../hooks/lib/atomic-write');
+    atomicWrite.atomicWriteSync(settingsPath, contenidoNuevo);
+  } catch (err) {
+    // Intentar restaurar backup
+    try {
+      if (fs.existsSync(backup)) {
+        fs.copyFileSync(backup, settingsPath);
+      }
+    } catch (_) { /* no se pudo restaurar — dejar backup en su lugar */ }
+    return { agregados: 0, preservados: 0, error: `Error escribiendo settings.json: ${err.message}` };
+  }
+
+  // Validación post-escritura
+  try {
+    const escritoFinal = fs.readFileSync(settingsPath, 'utf8');
+    JSON.parse(escritoFinal);
+  } catch (err) {
+    // Rollback desde backup
+    try {
+      if (fs.existsSync(backup)) {
+        fs.copyFileSync(backup, settingsPath);
+        console.error(`  [notificaciones] Rollback desde backup ${backup} (JSON inválido post-escritura).`);
+      }
+    } catch (_) { /* no se pudo restaurar */ }
+    return {
+      agregados:  0,
+      preservados: 0,
+      error: `Validación post-escritura falló — settings restaurado desde backup: ${err.message}`,
+    };
+  }
+
+  return { agregados, preservados, migrados };
+}
+
+/**
+ * Quita todas las entries SWL del settings.json GLOBAL preservando hooks ajenos.
+ *
+ * EXCEPCIÓN DOCUMENTADA (ADR-0009): Inversa de mergeHooksGlobales.
+ * Solo debe invocarse desde /swl:notificaciones disable.
+ *
+ * @param {string} settingsPath
+ * @returns {{ eliminados: number, preservados: number, error?: string }}
+ */
+function desregistrarHooksGlobales(settingsPath) {
+  if (!fs.existsSync(settingsPath)) {
+    return { eliminados: 0, preservados: 0 };
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (err) {
+    return { eliminados: 0, preservados: 0, error: `JSON inválido en settings.json: ${err.message}` };
+  }
+
+  if (!settings.hooks) {
+    return { eliminados: 0, preservados: 0 };
+  }
+
+  // Backup antes de modificar
+  const backup = `${settingsPath}.swl-backup-${Date.now()}`;
+  try {
+    fs.copyFileSync(settingsPath, backup);
+  } catch (err) {
+    return { eliminados: 0, preservados: 0, error: `No se pudo crear backup: ${err.message}` };
+  }
+
+  let eliminados  = 0;
+  let preservados = 0;
+
+  for (const evento of Object.keys(settings.hooks)) {
+    const existentes = settings.hooks[evento] || [];
+    if (!Array.isArray(existentes)) continue;
+
+    const noSWL = [];
+    for (const entry of existentes) {
+      if (esHookSWL(entry)) {
+        eliminados++;
+      } else {
+        noSWL.push(entry);
+        preservados++;
+      }
+    }
+
+    if (noSWL.length > 0) {
+      settings.hooks[evento] = noSWL;
+    } else {
+      delete settings.hooks[evento];
+    }
+  }
+
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  // Escritura atómica + validación post-escritura
+  try {
+    const contenido = JSON.stringify(settings, null, 2) + '\n';
+    JSON.parse(contenido); // validación pre-escritura
+    const atomicWrite = require('../../hooks/lib/atomic-write');
+    atomicWrite.atomicWriteSync(settingsPath, contenido);
+  } catch (err) {
+    try {
+      if (fs.existsSync(backup)) fs.copyFileSync(backup, settingsPath);
+    } catch (_) { /* no se pudo restaurar */ }
+    return { eliminados: 0, preservados: 0, error: `Error al escribir settings.json: ${err.message}` };
+  }
+
+  return { eliminados, preservados };
+}
+
+/**
+ * Optimizaciones de settings.json recomendadas por SWL.
+ * Basadas en auditoría de 858 sesiones / 18,903 turnos.
+ *
+ * - ENABLE_TOOL_SEARCH: carga schemas de herramientas bajo demanda en vez de
+ *   todos al inicio. Reduce ~20,000 tokens/turno de definiciones no usadas.
+ * - showThinkingSummaries: hace visible cuando Claude reduce profundidad de
+ *   razonamiento, permitiendo detectar regresiones de calidad.
+ *
+ * Estas configuraciones se aplican solo a nivel de PROYECTO (.claude/settings.json),
+ * no a nivel global (~/.claude/settings.json), para no afectar otros proyectos.
+ */
+const OPTIMIZACIONES_SWL = {
+  env: {
+    ENABLE_TOOL_SEARCH: 'true',
+  },
+  preferences: {
+    showThinkingSummaries: true,
+  },
+};
+
+/**
+ * Registra las optimizaciones SWL en settings.json del proyecto.
+ * No sobrescribe valores existentes del usuario — solo agrega los faltantes.
+ *
+ * @param {string} settingsPath - Ruta al settings.json
+ * @returns {{ aplicadas: number, yaExistentes: number }}
+ */
+function registrarOptimizaciones(settingsPath) {
+  const settings = leerSettings(settingsPath);
+  let aplicadas = 0;
+  let yaExistentes = 0;
+
+  for (const [seccion, valores] of Object.entries(OPTIMIZACIONES_SWL)) {
+    if (!settings[seccion]) {
+      settings[seccion] = {};
+    }
+
+    for (const [clave, valor] of Object.entries(valores)) {
+      if (settings[seccion][clave] === undefined) {
+        settings[seccion][clave] = valor;
+        aplicadas++;
+      } else {
+        yaExistentes++;
+      }
+    }
+  }
+
+  if (aplicadas > 0) {
+    escribirSettings(settingsPath, settings);
+  }
+
+  return { aplicadas, yaExistentes };
+}
+
+/**
+ * Valida la estructura del settings.json: secciones esperadas, tipos correctos,
+ * hooks con formato válido. No valida contenido semántico, solo estructura.
+ *
+ * @param {string} settingsPath
+ * @returns {{ ok: boolean, problemas: string[] }}
+ */
+function validarEstructuraSettings(settingsPath) {
+  const settings = leerSettings(settingsPath);
+  const problemas = [];
+
+  // Validar sección hooks
+  if (settings.hooks) {
+    const eventosValidos = new Set([
+      'PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop',
+      'SubagentStart', 'SubagentStop', 'PreCompact', 'PostCompact',
+      'Notification', 'SessionStart', 'TaskCompleted',
+    ]);
+
+    for (const [evento, entradas] of Object.entries(settings.hooks)) {
+      if (!eventosValidos.has(evento)) {
+        problemas.push(`hooks.${evento}: evento no reconocido`);
+      }
+      if (!Array.isArray(entradas)) {
+        problemas.push(`hooks.${evento}: debe ser un array de matchers`);
+        continue;
+      }
+      for (let i = 0; i < entradas.length; i++) {
+        const entrada = entradas[i];
+        if (typeof entrada.matcher !== 'string' && entrada.matcher !== undefined) {
+          problemas.push(`hooks.${evento}[${i}].matcher: debe ser string`);
+        }
+        if (!Array.isArray(entrada.hooks)) {
+          problemas.push(`hooks.${evento}[${i}].hooks: debe ser array de hooks`);
+          continue;
+        }
+        for (let j = 0; j < entrada.hooks.length; j++) {
+          const hook = entrada.hooks[j];
+          const tiposValidos = ['command', 'prompt', 'agent', 'http'];
+          if (!tiposValidos.includes(hook.type)) {
+            problemas.push(`hooks.${evento}[${i}].hooks[${j}].type: "${hook.type}" no es válido (command|prompt|agent|http)`);
+          }
+          if (hook.type === 'command' && !hook.command) {
+            problemas.push(`hooks.${evento}[${i}].hooks[${j}]: hook tipo command sin campo command`);
+          }
+        }
+      }
+    }
+  }
+
+  // Validar sección env
+  if (settings.env && typeof settings.env !== 'object') {
+    problemas.push('env: debe ser un objeto { clave: valor }');
+  }
+
+  // Validar sección preferences
+  if (settings.preferences && typeof settings.preferences !== 'object') {
+    problemas.push('preferences: debe ser un objeto');
+  }
+
+  return { ok: problemas.length === 0, problemas };
+}
+
+/**
+ * Verifica que las optimizaciones SWL estén presentes en settings.json.
+ *
+ * @param {string} settingsPath
+ * @returns {{ ok: boolean, faltantes: string[] }}
+ */
+function verificarOptimizaciones(settingsPath) {
+  const settings = leerSettings(settingsPath);
+  const faltantes = [];
+
+  for (const [seccion, valores] of Object.entries(OPTIMIZACIONES_SWL)) {
+    for (const [clave, valor] of Object.entries(valores)) {
+      if (!settings[seccion] || settings[seccion][clave] === undefined) {
+        faltantes.push(`${seccion}.${clave}`);
+      }
+    }
+  }
+
+  return { ok: faltantes.length === 0, faltantes };
+}
+
+module.exports = {
+  cargarHooksConfig,
+  leerSettings,
+  escribirSettings,
+  rutaSettings,
+  registrarHooks,
+  desregistrarHooks,
+  verificarHooks,
+  repararHooks,
+  esHookSWL,
+  registrarOptimizaciones,
+  verificarOptimizaciones,
+  validarEstructuraSettings,
+  generarComando,
+  OPTIMIZACIONES_SWL,
+  // ADR-0009: excepción opt-in para hooks globales de notificaciones Telegram
+  mergeHooksGlobales,
+  desregistrarHooksGlobales,
+};