@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/ci-reader.js

@@ -1,193 +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);
-}
+'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);
+}

package/scripts/lib/ciclo-autonomo/yaml-instintos.js

@@ -483,6 +483,55 @@ function actualizarCabeceraPerfil(lineas, incremento) {
   });
 }
 
+/**
+ * Plantilla canónica de `perfil-usuario.yaml` para proyectos que instalaron
+ * SWL antes de la Fase 21 (ADR-0041/0042) y nunca tuvieron este archivo.
+ * Debe mantenerse en sync con `agentes/perfilador-usuario-swl.md` y con el
+ * fixture congelado `tests/ciclo-autonomo/fixtures/perfil-usuario.yaml`.
+ */
+function plantillaPerfilUsuario() {
+  const hoy = new Date().toLocaleDateString('sv');
+  return [
+    '# Perfil de Usuario — Modelo persistente entre sesiones',
+    '# Generado y mantenido por agentes/perfilador-usuario-swl.md',
+    '# Alimentado por hooks/actualizar-perfil-usuario.js (acumula señales en .planning/perfil-usuario/dirty.json)',
+    '# NUNCA editar a mano datos con confidence >= 0.9 sin contraevidencia documentada',
+    '# Formato estandarizado v1.0',
+    '',
+    'version: "1.0"',
+    `generado: "${hoy}"`,
+    `actualizado: "${hoy}"`,
+    'total_senales_consolidadas: 0',
+    '',
+    'identidad:',
+    '  rol: null',
+    '  rol_confidence: 0.0',
+    '  rol_fuentes: []',
+    '  anos_experiencia: null',
+    '  zonas_horarias_activas: []',
+    '',
+    'stack_preferido: []',
+    '',
+    'patrones_trabajo: []',
+    '',
+    'correcciones_repetidas: []',
+    '',
+    'decisiones_validadas: []',
+    '',
+    'preferencias_comunicacion:',
+    '  idioma: "es-MX"',
+    '  formalidad: null',
+    '  longitud_respuestas: null',
+    '  detalle_explicaciones: null',
+    '  confirmacion_acciones: null',
+    '',
+    'limites_explicitos:',
+    '  no_guardar: []',
+    '  no_sugerir: []',
+    '',
+  ].join(String.fromCharCode(10));
+}
+
 /**
  * Append mínimo de entradas draft a una sección de `perfil-usuario.yaml` sin
  * reescribir las secciones no tocadas. Actualiza `total_senales_consolidadas`
@@ -506,6 +555,12 @@ function actualizarCabeceraPerfil(lineas, incremento) {
 function agregarSenalesPerfil(rutaYaml, seccion, entradas) {
   if (!Array.isArray(entradas) || entradas.length === 0) return { agregadas: 0 };
 
+  if (!fs.existsSync(rutaYaml)) {
+    const dir = path.dirname(rutaYaml);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    atomicWriteSync(rutaYaml, plantillaPerfilUsuario());
+  }
+
   respaldar(rutaYaml);
   const crudo = fs.readFileSync(rutaYaml, 'utf8');
   const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
@@ -532,4 +587,5 @@ module.exports = {
   escribirInstintos,
   respaldar,
   agregarSenalesPerfil,
+  plantillaPerfilUsuario,
 };

package/scripts/lib/clasificar-directorio.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * clasificar-directorio.js — Clasifica un directorio de trabajo para que el
+ * instalador y `doctor` decidan si deben anclar `.planning/` ahí.
+ *
+ * Bug de origen (2026-07-15): instalador/doctor trataban `process.cwd()` como
+ * proyecto sin distinguir el HOME del usuario (ubicación de una instalación
+ * GLOBAL, NO un proyecto) de un proyecto de desarrollo real. Correr
+ * `install --global` o `doctor` desde el HOME sembraba `~/.planning/`
+ * (backups del install, scaffold de marcadores, telemetría mal dirigida).
+ *
+ * Categorías:
+ *   - 'home'     : cwd === os.homedir(). Ubicación de install global; NUNCA un proyecto.
+ *   - 'proyecto' : proyecto de desarrollo real (.git, stack detectado, o `.planning/`
+ *                  con marcadores de proyecto).
+ *   - 'nuevo'    : directorio vacío o casi vacío (candidato a inicializar un proyecto).
+ *   - 'otro'     : con contenido pero sin señales de proyecto (no scaffoldear a ciegas).
+ *
+ * Uso interno del instalador/doctor (no viaja a destinos): puede requerir otras
+ * libs de `scripts/lib` y `hooks/lib`. Zero-deps npm.
+ *
+ * @module scripts/lib/clasificar-directorio
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { detectarStack } = require('./detectar-stack');
+const { tienePlanningReal } = require('../../hooks/lib/raiz-proyecto');
+
+// Entradas que NO cuentan como "contenido" al decidir si un dir está vacío
+// (metadatos del SO / control de versiones que pueden existir en un dir "nuevo").
+const IGNORAR_AL_MEDIR_VACIO = new Set(['.git', '.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
+/**
+ * ¿El directorio es el HOME del usuario? (comparación canónica por realpath
+ * para tolerar el nombre corto 8.3 de Windows — misma razón que raiz-proyecto).
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esHome(dir) {
+  const canon = (p) => { try { return fs.realpathSync.native(p); } catch (_) { return path.resolve(p); } };
+  return canon(dir) === canon(os.homedir());
+}
+
+/**
+ * ¿El directorio es un proyecto de desarrollo real? Señal: repo git, stack de
+ * lenguaje detectado, o `.planning/` con marcadores de proyecto.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esProyectoDesarrollo(dir) {
+  try {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+  } catch (_) { /* seguir */ }
+  if (tienePlanningReal(dir)) return true;
+  try {
+    if (detectarStack(dir).size > 0) return true;
+  } catch (_) { /* seguir */ }
+  return false;
+}
+
+/**
+ * ¿El directorio está vacío o casi vacío (solo metadatos del SO/git)?
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function estaVacio(dir) {
+  let entradas;
+  try {
+    entradas = fs.readdirSync(dir);
+  } catch (_) {
+    return false; // no legible → no lo tratamos como vacío
+  }
+  return entradas.filter((e) => !IGNORAR_AL_MEDIR_VACIO.has(e)).length === 0;
+}
+
+/**
+ * Clasifica el directorio de trabajo.
+ * @param {string} [cwd] - Directorio (default: process.cwd()).
+ * @returns {'home'|'proyecto'|'nuevo'|'otro'}
+ */
+function clasificarDirectorio(cwd) {
+  const dir = path.resolve(cwd || process.cwd());
+  if (esHome(dir)) return 'home';
+  if (esProyectoDesarrollo(dir)) return 'proyecto';
+  if (estaVacio(dir)) return 'nuevo';
+  return 'otro';
+}
+
+module.exports = { clasificarDirectorio, esHome, esProyectoDesarrollo, estaVacio };