@saulwade/swl-ses 2.0.0 → 2.2.0

package/scripts/cli/notificaciones.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses notificaciones <op>` — gestiona las notificaciones
+ * Telegram y su bot daemon. Reemplaza los inline
+ * `require('./scripts/lib/notificaciones-telegram')` relativos al proyecto
+ * (rotos downstream; ver docs/invocacion-cli-cross-scope.md). Encapsula también
+ * el formato de salida que antes vivía en el comando.
+ *
+ * Ops:
+ *   init                  (requiere TTY)        bot-start
+ *   status                                      bot-stop
+ *   disable [--purge]                           bot-status
+ *   repair                                      bot-restart
+ *                                               bot-enable-autostart
+ *                                               bot-disable-autostart
+ */
+
+const nt = require('../lib/notificaciones-telegram');
+
+function imprimirStatus() {
+  const s = nt.status();
+  const botS = nt.botStatus();
+  const autostartLabel =
+    process.platform === 'win32'
+      ? 'Scheduled Task'
+      : process.platform === 'linux'
+        ? 'systemd --user'
+        : 'LaunchAgent';
+  const mudos = s.proyectosSilenciados.length
+    ? s.proyectosSilenciados.join(', ')
+    : 'ninguno';
+  console.log('');
+  console.log('Notificaciones Telegram — estado actual');
+  console.log('  .env:             ', s.envExiste ? 'existe' : 'no existe');
+  console.log('  token:            ', s.tokenConfigurado ? 'configurado' : 'no configurado');
+  console.log(
+    '  chat_id:          ',
+    s.chatIdConfigurado ? 'configurado (' + s.chatIdParcial + ')' : 'no configurado'
+  );
+  console.log('  proyectos mudos:  ', mudos);
+  console.log('  bot daemon:       ', botS.activo ? 'activo (PID ' + botS.pid + ')' : 'detenido');
+  console.log('  autostart:         usar /swl:notificaciones bot enable-autostart (' + autostartLabel + ')');
+  console.log('');
+}
+
+function imprimirBotStatus() {
+  const r = nt.botStatus();
+  console.log('');
+  console.log('Bot daemon — estado actual');
+  console.log('  activo:', r.activo ? 'sí' : 'no');
+  console.log('  pid:   ', r.pid !== null ? r.pid : 'n/a');
+  console.log('');
+}
+
+function reportarOk(prefijo, r, mensajeDefault) {
+  if (r.ok) {
+    console.log('[' + prefijo + ']', r.mensaje || mensajeDefault);
+  } else {
+    console.error('[' + prefijo + '] Error:', r.error);
+    process.exitCode = 1;
+  }
+}
+
+// Tabla de dispatch de los ops del bot daemon: [prefijo, fn, mensajeDefault].
+const BOT_OPS = {
+  'bot-start': ['bot', () => nt.botStart(), 'Bot iniciado.'],
+  'bot-stop': ['bot', () => nt.botStop(), 'Bot detenido.'],
+  'bot-restart': ['bot', () => nt.botRestart(), 'Bot reiniciado.'],
+  'bot-enable-autostart': ['autostart', () => nt.botEnableAutostart(), 'Autostart habilitado.'],
+  'bot-disable-autostart': ['autostart', () => nt.botDisableAutostart(), 'Autostart deshabilitado.'],
+};
+
+async function notificaciones(opciones = {}) {
+  const op = (opciones._args && opciones._args[0]) || opciones.op || 'status';
+
+  if (BOT_OPS[op]) {
+    const [prefijo, fn, msg] = BOT_OPS[op];
+    reportarOk(prefijo, fn(), msg);
+    return;
+  }
+
+  switch (op) {
+    case 'init': {
+      if (!process.stdin.isTTY) {
+        console.log('Este subcomando requiere entrada interactiva (TTY).');
+        console.log('Ejecuta desde tu terminal:');
+        console.log('  swl-ses notificaciones init');
+        console.log('O usa el instalador:');
+        console.log('  npx -y @saulwade/swl-ses@latest install');
+        return;
+      }
+      const r = await nt.init({ esTty: true });
+      console.log('[resultado]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'status':
+      imprimirStatus();
+      return;
+    case 'disable': {
+      const r = nt.disable({ confirmar: true, conservarEnv: !opciones.purge });
+      console.log('[resultado]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'repair': {
+      const r = await nt.repair();
+      console.log('[repair]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'bot-status':
+      imprimirBotStatus();
+      return;
+    default:
+      console.error('Op desconocida: ' + op);
+      console.error('Ops: init|status|disable|repair|bot-start|bot-stop|bot-status|bot-restart|bot-enable-autostart|bot-disable-autostart');
+      process.exitCode = 1;
+  }
+}
+
+module.exports = notificaciones;

package/scripts/cli/propose-step.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * Wrapper CLI para `swl-ses propose-step` — anexo propositivo del RESUMEN de
+ * fase (ADR-0037). Envuelve hooks/lib/propose-step.js (que lee process.argv).
+ *
+ * Reemplaza el `node hooks/lib/propose-step.js --rango=...` relativo al proyecto
+ * que /swl:ejecutar-fase invocaba — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses propose-step --rango=<base>..HEAD   (opt-out SWL_PROPOSE=0)
+ */
+
+const { main } = require('../../hooks/lib/propose-step.js');
+
+function proposeStep(opciones = {}) {
+  opciones = opciones || {};
+  const args = ['node', 'propose-step'];
+  if (opciones.rango) args.push(`--rango=${opciones.rango}`);
+  const argvOriginal = process.argv;
+  process.argv = args;
+  try {
+    return main(process.argv);
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = proposeStep;

package/scripts/cli/schedule-parse.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses schedule-parse` — parsea una frase en inglés a expresión
+ * cron. Reemplaza el inline `require('./scripts/lib/schedule-parser')` relativo
+ * al proyecto (roto downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses schedule-parse "every morning at 9am"
+ */
+
+const { parseNaturalSchedule } = require('../lib/schedule-parser');
+
+function scheduleParse(opciones = {}) {
+  const frase =
+    (opciones._args && opciones._args.join(' ')) || opciones.texto || '';
+  console.log(JSON.stringify(parseNaturalSchedule(frase), null, 2));
+}
+
+module.exports = scheduleParse;

package/scripts/cli/sugerir-modelo.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses sugerir-modelo` — evalúa la complejidad de una tarea y
+ * sugiere el modelo (opus/sonnet/haiku). Reemplaza el inline
+ * `require('./hooks/lib/model-router.js')` relativo al proyecto (roto downstream;
+ * ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses sugerir-modelo "<descripción de la tarea>"
+ */
+
+const { sugerirModelo } = require('../../hooks/lib/model-router.js');
+
+function sugerirModeloCli(opciones = {}) {
+  const desc =
+    (opciones._args && opciones._args.join(' ')) || opciones.desc || '';
+  console.log(JSON.stringify(sugerirModelo(desc), null, 2));
+}
+
+module.exports = sugerirModeloCli;

package/scripts/cli/verificar-plan.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Subcomando `swl-ses verificar-plan --fase=N` — verificación read-only del lock
+ * de un PLAN (gate G1). Lo usa /swl:ejecutar-fase antes de implementar y
+ * /swl:aprobar-plan Paso 2 para detectar planes ya firmados/mutados/legacy.
+ *
+ * Reemplaza el `node -e "require('./scripts/lib/plan-lock')"` inline que se
+ * rompía downstream (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Exit 0 si ok (firmado o legacy); exit 1 si mutado/sin-firmar/corrupto.
+ *
+ * Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]
+ */
+
+const { verificarPlan } = require('../lib/plan-lock');
+const { resolverPlanPath } = require('../lib/resolver-plan-fase');
+
+function verificarPlanCli(opciones = {}) {
+  opciones = opciones || {};
+  const planPath = resolverPlanPath(opciones);
+  if (!planPath) {
+    console.error('Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]');
+    process.exit(1);
+  }
+  const r = verificarPlan(planPath);
+  console.log(JSON.stringify(r, null, 2));
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = verificarPlanCli;
+
+if (require.main === module) {
+  const { parsearOpciones } = require('../lib/parsear-opciones');
+  verificarPlanCli(parsearOpciones(process.argv.slice(2)));
+}

package/scripts/cli/verificar-trazabilidad.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Wrapper CLI para el subcomando `swl-ses verificar-trazabilidad`.
+ *
+ * Traduce las opciones parseadas del bin a las flags que espera el script
+ * standalone `scripts/verificar-trazabilidad.js` (que lee process.argv y hace
+ * su propio process.exit). Mismo patrón que scripts/cli/audit-claudemd.js.
+ *
+ * Reemplaza el `node scripts/verificar-trazabilidad.js` relativo al proyecto que
+ * /swl:aprobar-plan invocaba — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses verificar-trazabilidad --fase=N [--solo-plan] [--json]
+ */
+
+const { main } = require('../verificar-trazabilidad.js');
+
+function verificarTrazabilidad(opciones = {}) {
+  opciones = opciones || {};
+  const args = [];
+  if (opciones.fase != null && opciones.fase !== true) args.push(`--fase=${opciones.fase}`);
+  if (opciones['solo-plan'] || opciones.solo_plan) args.push('--solo-plan');
+  if (opciones.json) args.push('--json');
+
+  const argvOriginal = process.argv;
+  process.argv = ['node', 'verificar-trazabilidad.js', ...args];
+  try {
+    main();
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = verificarTrazabilidad;

package/scripts/derivar-feature-list.js

@@ -486,4 +486,5 @@ module.exports = {
   enriquecerDesdeFases,
   generarFeatureList,
   normalizarEstado,
+  main,
 };

package/scripts/instalador.js

@@ -101,17 +101,24 @@ async function install(opciones) {
   //   1. opciones.profile  — flag explícito del usuario (también acepta --perfil)
   //   2. manifest.profile  — declarado en .swl-ses del proyecto
   //   3. install-state existente en el destino — preserva el perfil ya instalado
-  //   4. 'core' — default final
+  //   4. 'completo' — default final
   //
   // Antes del fix v1.3.5, `install --force` sin --profile defaulteaba directamente
-  // a 'core' aunque ya existiera una instalación con perfil 'completo'. El usuario
+  // al default aunque ya existiera una instalación con perfil distinto. El usuario
   // perdía silenciosamente componentes y el update subsiguiente reproducía el
   // estado contaminado (los archivos del completo quedaban con contenido viejo).
   //
+  // El default final es 'completo' (cambiado desde 'core'): una instalación sin
+  // --profile entrega el sistema entero (todos los agentes, skills y comandos).
+  // Razón: un `install --target=... --with-mcp --global --force` sin --perfil
+  // parecía una instalación completa pero entregaba el perfil mínimo, dejando al
+  // usuario sin la mayoría de comandos /swl:* (caso reportado 2026-06-12). Para
+  // instalar solo el núcleo, pasar --perfil core explícito.
+  //
   // La detección del install-state aquí es deliberadamente best-effort: si no
-  // existe o no se puede leer, caemos al default 'core'. Solo aplica para
+  // existe o no se puede leer, caemos al default 'completo'. Solo aplica para
   // `install --force` (reinstalación); en una primera instalación no hay state
-  // todavía y core como default sigue siendo razonable.
+  // todavía y el sistema completo es el default razonable.
   let perfilDeState = null;
   if (!opciones.profile && !(manifest && manifest.profile)) {
     try {
@@ -131,7 +138,7 @@ async function install(opciones) {
   const perfil = opciones.profile
               || (manifest && manifest.profile)
               || perfilDeState
-              || 'core';
+              || 'completo';
 
   console.log(`swl-ses install v${VERSION}`);
   console.log(`${'='.repeat(40)}`);
@@ -247,7 +254,7 @@ async function install(opciones) {
   if (allLangs && !tieneReglasLenguaje && !esGlobal) {
     console.log(
       '\n[stack] Aviso: --all-langs ignorado — el perfil actual (' +
-      (resolucion.perfil || 'core') +
+      (resolucion.perfil || 'completo') +
       ') no incluye reglas de lenguajes. ' +
       'Usa --perfil completo o --perfil polyglot para activar las reglas por lenguaje.'
     );
@@ -644,6 +651,45 @@ async function install(opciones) {
     }
   }
 
+  // Copiar fragmentos compartidos (agentes/_*.md) — NO van en modulos.json
+  // (no son agentes routables) pero los agentes que los importan vía
+  // `fragmentos:` los leen al cargarse. El loader los espera en el dir de
+  // agentes del destino. Se copian raw (sin transformar: no tienen frontmatter).
+  // Cierra DT-FRAGMENTOS-DISTRIBUCION (Fase 13).
+  if (
+    runtime.tiposSoportados &&
+    runtime.tiposSoportados.includes('agentes') &&
+    rutas.agentes &&
+    resolucion.archivos.some(a => a.tipo === 'agentes')
+  ) {
+    const fragmentosOrigen = path.join(RAIZ_PKG, 'agentes');
+    try {
+      const fragmentos = fs.existsSync(fragmentosOrigen)
+        ? fs.readdirSync(fragmentosOrigen).filter(f => f.startsWith('_') && f.endsWith('.md'))
+        : [];
+      if (fragmentos.length > 0 && !fs.existsSync(rutas.agentes)) {
+        fs.mkdirSync(rutas.agentes, { recursive: true });
+      }
+      let fragmentosCopiados = 0;
+      for (const frag of fragmentos) {
+        const destino = path.join(rutas.agentes, frag);
+        fs.copyFileSync(path.join(fragmentosOrigen, frag), destino);
+        registrarArchivo(estado, {
+          origen: `agentes/${frag}`,
+          destino,
+          tipo: 'fragmentos', // distinto de 'agentes' → no infla el conteo del doctor
+        });
+        fragmentosCopiados++;
+      }
+      if (fragmentosCopiados > 0) {
+        console.log(`  + Fragmentos compartidos: ${fragmentosCopiados} (agentes/_*.md)`);
+      }
+    } catch (err) {
+      console.error(`  ! Error copiando fragmentos: ${err.message}`);
+      errores++;
+    }
+  }
+
   // Instalar userland (prioridad sobre core)
   for (const archivo of archivosUserland) {
     try {

package/scripts/lib/auditar-invocaciones-comandos.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * auditar-invocaciones-comandos.js
+ *
+ * Gate anti-regresión de la clase de bug "invocación relativa al proyecto en
+ * comandos user-facing" (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Un comando que corre en el proyecto del usuario NUNCA debe invocar scripts SWL
+ * con ruta relativa al proyecto (`node scripts/lib/...`, `node hooks/...`,
+ * `require('./scripts/...')`): esas rutas no existen downstream. Debe usar el
+ * subcomando del CLI (`swl-ses <sub>` / `npx ... <sub>` / `node scripts/cli/<sub>.js`).
+ *
+ * Solo escanea bloques de código (``` ... ```) para no marcar menciones
+ * prohibitivas en prosa. Excluye `scripts/cli/` (forma repo-madre sancionada).
+ *
+ * Función pura + entrypoint CLI con exit 1 si hay violaciones.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Comandos que corren SOLO en el repo madre de swl-ses (el CWD ES el repo, así
+// que `node scripts/...` relativo es correcto). NO son user-facing.
+const SELF_DEV = new Set([
+  'release',
+  'contribuir',
+  'evaluar-skill',
+  'reflect-skills',
+]);
+
+// Patrones de invocación relativa al proyecto que se rompen downstream.
+// Se evalúan SOLO dentro de bloques de código.
+const PATRONES = [
+  { re: /\bnode\s+(?:\.\/)?scripts\/(?!cli\/)/, desc: 'node scripts/ (usa swl-ses <sub>)' },
+  { re: /\bnode\s+(?:\.\/)?hooks\//, desc: 'node hooks/ (usa swl-ses <sub>)' },
+  { re: /require\(\s*['"]\.\.?\/scripts\//, desc: "require('./scripts/ inline" },
+  { re: /require\(\s*['"]\.\.?\/hooks\//, desc: "require('./hooks/ inline" },
+];
+
+/**
+ * @param {string} [comandosDir] default: comandos/swl relativo al repo de este script.
+ * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
+ */
+function auditarInvocacionesComandos(comandosDir) {
+  const dir = comandosDir || path.join(__dirname, '..', '..', 'comandos', 'swl');
+  const violaciones = [];
+  let escaneados = 0;
+
+  let archivos;
+  try {
+    archivos = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
+  } catch {
+    return { ok: true, violaciones, escaneados: 0 };
+  }
+
+  for (const archivo of archivos) {
+    const comando = archivo.replace(/\.md$/, '');
+    if (SELF_DEV.has(comando)) continue;
+    escaneados++;
+
+    const contenido = fs.readFileSync(path.join(dir, archivo), 'utf8');
+    const lineas = contenido.split('\n');
+    let dentroCodigo = false;
+
+    for (let i = 0; i < lineas.length; i++) {
+      const linea = lineas[i];
+      if (/^\s*```/.test(linea)) {
+        dentroCodigo = !dentroCodigo;
+        continue;
+      }
+      if (!dentroCodigo) continue;
+      for (const { re, desc } of PATRONES) {
+        if (re.test(linea)) {
+          violaciones.push({
+            comando,
+            linea: i + 1,
+            texto: linea.trim(),
+            patron: desc,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { ok: violaciones.length === 0, violaciones, escaneados };
+}
+
+module.exports = { auditarInvocacionesComandos, SELF_DEV };
+
+if (require.main === module) {
+  const r = auditarInvocacionesComandos();
+  if (r.ok) {
+    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos user-facing sin rutas relativas al proyecto`);
+    process.exit(0);
+  }
+  console.error(`[FALLA] invocaciones-comandos — ${r.violaciones.length} invocación(es) relativa(s) al proyecto en comandos user-facing:`);
+  for (const v of r.violaciones) {
+    console.error(`  ${v.comando}.md:${v.linea} [${v.patron}] ${v.texto}`);
+  }
+  console.error('\nUsa el patrón cross-scope (docs/invocacion-cli-cross-scope.md): swl-ses <sub> / npx ... <sub> / node scripts/cli/<sub>.js');
+  process.exit(1);
+}

package/scripts/lib/ci-reader.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * ci-reader.js
+ *
+ * Métricas DORA dependientes de CI (GitHub Actions vía `gh run list`):
+ *   - change failure rate: runs fallidos / runs completados en la ventana.
+ *   - MTTR (mean/median time to restore): mediana del tiempo de un run fallido
+ *     hasta el siguiente run exitoso.
+ *
+ * `gh` es OPCIONAL (D-15-01): si no está instalado, no autenticado, o el repo no
+ * tiene remoto GitHub, las funciones devuelven `{disponible:false, razon}` SIN
+ * lanzar. El executor `gh` es inyectable (`opts.ejecutorGh`) para tests sin gh
+ * real. Funciones puras sobre el array de runs. Entrypoint CLI `--json`.
+ * Parte de la Fase 15 (ADR-0039).
+ */
+
+const { execFileSync } = require('node:child_process');
+
+const MS_DIA = 24 * 60 * 60 * 1000;
+const MS_HORA = 60 * 60 * 1000;
+const LIMITE_DEFAULT = 200;
+
+const CONCLUSIONES_FALLO = new Set(['failure', 'timed_out', 'startup_failure']);
+const CONCLUSIONES_EXITO = new Set(['success']);
+
+const GH_MAX_BUFFER = 8 * 1024 * 1024; // 8 MiB
+const GH_TIMEOUT_MS = 8000; // gh puede tardar por red; degrada si excede (H-04)
+
+/** Executor real de gh. Lanza si gh no está disponible/autenticado. */
+function ejecutorGhReal(args) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: GH_MAX_BUFFER,
+    timeout: GH_TIMEOUT_MS,
+  });
+}
+
+/** Categoriza el fallo de gh sin filtrar e.message crudo a logs/persistencia (H-03). */
+function _razonGh(e) {
+  if (e && e.code === 'ENOENT') return 'gh no instalado';
+  if (e && e.killed && e.signal) return 'gh excedió el timeout';
+  return 'gh no disponible o sin acceso al repo';
+}
+
+/**
+ * Obtiene los runs de CI. Degrada sin lanzar.
+ * @returns {{disponible:boolean, runs?:Array, razon?:string}}
+ */
+function obtenerRuns(opts = {}) {
+  const { ejecutorGh = ejecutorGhReal, limite = LIMITE_DEFAULT, rama } = opts;
+  let salida;
+  try {
+    salida = ejecutorGh([
+      'run', 'list',
+      '--json', 'databaseId,conclusion,createdAt,updatedAt,headBranch,workflowName',
+      '--limit', String(limite),
+    ]);
+  } catch (e) {
+    return { disponible: false, razon: _razonGh(e) };
+  }
+  let runs;
+  try {
+    runs = JSON.parse(salida);
+  } catch {
+    return { disponible: false, razon: 'salida de gh no es JSON válido' };
+  }
+  if (!Array.isArray(runs)) return { disponible: false, razon: 'salida de gh inesperada' };
+  if (rama) runs = runs.filter((r) => r && r.headBranch === rama);
+  return { disponible: true, runs };
+}
+
+function _runsEnVentana(runs, ventanaDias, hoy) {
+  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA).getTime();
+  const hasta = hoy.getTime();
+  return runs.filter((r) => {
+    const t = Date.parse(r && r.createdAt);
+    return Number.isFinite(t) && t >= desde && t <= hasta;
+  });
+}
+
+function _mediana(valoresOrdenados) {
+  const n = valoresOrdenados.length;
+  if (n === 0) return null;
+  const mid = Math.floor(n / 2);
+  return n % 2 ? valoresOrdenados[mid] : (valoresOrdenados[mid - 1] + valoresOrdenados[mid]) / 2;
+}
+
+/**
+ * Change failure rate en la ventana.
+ * @returns {{disponible:boolean, cfr?:number, totalRuns?:number, fallidos?:number,
+ *            sinDatos?:boolean, razon?:string}}
+ */
+function changeFailureRate(opts = {}) {
+  const { ventanaDias = 30, hoy = new Date() } = opts;
+  const base = opts.runs ? { disponible: true, runs: opts.runs } : obtenerRuns(opts);
+  if (!base.disponible) return { disponible: false, razon: base.razon };
+
+  const enVentana = _runsEnVentana(base.runs, ventanaDias, hoy);
+  const completados = enVentana.filter(
+    (r) => CONCLUSIONES_EXITO.has(r.conclusion) || CONCLUSIONES_FALLO.has(r.conclusion)
+  );
+  if (completados.length === 0) {
+    return { disponible: true, sinDatos: true, totalRuns: 0, fallidos: 0, cfr: 0 };
+  }
+  const fallidos = completados.filter((r) => CONCLUSIONES_FALLO.has(r.conclusion)).length;
+  return {
+    disponible: true,
+    sinDatos: false,
+    totalRuns: completados.length,
+    fallidos,
+    cfr: fallidos / completados.length,
+  };
+}
+
+/**
+ * MTTR: mediana del tiempo de un run fallido hasta el siguiente run exitoso.
+ * @returns {{disponible:boolean, mttrHoras?:number, recuperaciones?:number,
+ *            sinDatos?:boolean, razon?:string}}
+ */
+function meanTimeToRestore(opts = {}) {
+  const { ventanaDias = 30, hoy = new Date() } = opts;
+  const base = opts.runs ? { disponible: true, runs: opts.runs } : obtenerRuns(opts);
+  if (!base.disponible) return { disponible: false, razon: base.razon };
+
+  const enVentana = _runsEnVentana(base.runs, ventanaDias, hoy)
+    .filter((r) => CONCLUSIONES_EXITO.has(r.conclusion) || CONCLUSIONES_FALLO.has(r.conclusion))
+    .map((r) => ({
+      fallo: CONCLUSIONES_FALLO.has(r.conclusion),
+      detectado: Date.parse(r.updatedAt || r.createdAt),
+    }))
+    .filter((r) => Number.isFinite(r.detectado))
+    .sort((a, b) => a.detectado - b.detectado);
+
+  const recuperaciones = [];
+  for (let i = 0; i < enVentana.length; i++) {
+    if (!enVentana[i].fallo) continue;
+    const exito = enVentana.slice(i + 1).find((r) => !r.fallo);
+    if (exito) {
+      const h = (exito.detectado - enVentana[i].detectado) / MS_HORA;
+      if (h >= 0) recuperaciones.push(h);
+    }
+  }
+  recuperaciones.sort((a, b) => a - b);
+  if (recuperaciones.length === 0) {
+    return { disponible: true, sinDatos: true, recuperaciones: 0, mttrHoras: null };
+  }
+  return {
+    disponible: true,
+    sinDatos: false,
+    recuperaciones: recuperaciones.length,
+    mttrHoras: _mediana(recuperaciones),
+  };
+}
+
+module.exports = {
+  obtenerRuns,
+  changeFailureRate,
+  meanTimeToRestore,
+  ejecutorGhReal,
+  CONCLUSIONES_FALLO,
+  CONCLUSIONES_EXITO,
+};
+
+// Entrypoint CLI: node scripts/lib/ci-reader.js [--json] [--dias=N]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const diasArg = args.find((a) => a.startsWith('--dias='));
+  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
+
+  // Una sola llamada a gh; si no está disponible, no se re-intenta.
+  const base = obtenerRuns({ limite: LIMITE_DEFAULT });
+  let out;
+  if (!base.disponible) {
+    out = { disponible: false, razon: base.razon };
+  } else {
+    const cfr = changeFailureRate({ ventanaDias, runs: base.runs });
+    const mttr = meanTimeToRestore({ ventanaDias, runs: base.runs });
+    out = { ventana_dias: ventanaDias, changeFailureRate: cfr, mttr };
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  } else if (!base.disponible) {
+    process.stdout.write(`CI no disponible: ${base.razon}\n`);
+  } else {
+    process.stdout.write(`Change failure rate: ${out.changeFailureRate.sinDatos ? 'sin datos' : (out.changeFailureRate.cfr * 100).toFixed(1) + '%'}\n`);
+    process.stdout.write(`MTTR: ${out.mttr.sinDatos ? 'sin datos' : out.mttr.mttrHoras.toFixed(1) + 'h'}\n`);
+  }
+  process.exit(0);
+}