@saulwade/swl-ses 2.0.0 → 2.1.0

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);
+}

package/scripts/lib/detectar-host-swl.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * detectar-host-swl.js
+ *
+ * Determina si un directorio es el REPO HOST del sistema SWL (donde viven los
+ * componentes: agentes/, habilidades/, comandos/swl/, reglas/, hooks/) o un
+ * PROYECTO CONSUMIDOR que solo usa las convenciones SWL vía `~/.claude/`.
+ *
+ * Motivación: `/swl:status salud` audita los componentes del sistema SWL con un
+ * score ponderado (agentes×0.30 + skills×0.25 + comandos×0.20 + reglas×0.15 +
+ * hooks×0.10). En un proyecto consumidor esos directorios no existen → el score
+ * sería 0/100, señal falsa. Antes esta distinción dependía del juicio del agente
+ * de turno; este módulo la vuelve determinista (regla: salud usa verificaciones
+ * deterministas, no juicio subjetivo).
+ *
+ * Función pura zero-deps. Entrypoint CLI con `--json` para consumo desde el
+ * comando /swl:status salud.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Marca canónica del paquete en plugin.json (acepta forma con y sin scope npm).
+const NOMBRES_HOST = new Set(['swl-ses', '@saulwade/swl-ses']);
+
+// Subcomandos de /swl:status que SÍ aplican a un proyecto consumidor.
+const SUGERENCIAS_CONSUMIDOR = [
+  '/swl:status metricas — tokens/costo de la sesión actual',
+  '/swl:status metricas fases — progreso de fases (si usa .planning/HOJA-RUTA.md)',
+  '/swl:status loops — telemetría de loops iterativos',
+  '/swl:status evolucion — ciclo de auto-evolución (si corre en este proyecto)',
+  '/swl:status dashboard — consumo multi-sesión',
+];
+
+/**
+ * Cuenta archivos de un componente sin recursión profunda innecesaria.
+ * @returns {number}
+ */
+function contarComponente(baseDir, rel, filtro) {
+  const dir = path.join(baseDir, rel);
+  let entradas;
+  try {
+    entradas = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  return entradas.filter((e) => filtro(e)).length;
+}
+
+/**
+ * Cuenta los 5 componentes del sistema SWL en baseDir.
+ * @returns {{agentes:number, habilidades:number, comandos:number, reglas:number, hooks:number}}
+ */
+function contarComponentes(baseDir) {
+  return {
+    // Agentes: agentes/*.md excluyendo fragmentos compartidos (_*.md).
+    agentes: contarComponente(
+      baseDir,
+      'agentes',
+      (e) => e.isFile() && e.name.endsWith('.md') && !e.name.startsWith('_')
+    ),
+    // Skills: habilidades/<nombre>/ (cada subdirectorio es un skill).
+    habilidades: contarComponente(baseDir, 'habilidades', (e) => e.isDirectory()),
+    // Comandos: comandos/swl/*.md.
+    comandos: contarComponente(
+      baseDir,
+      path.join('comandos', 'swl'),
+      (e) => e.isFile() && e.name.endsWith('.md')
+    ),
+    // Reglas: reglas/*.md (base; las por-lenguaje viven en subdirectorios).
+    reglas: contarComponente(
+      baseDir,
+      'reglas',
+      (e) => e.isFile() && e.name.endsWith('.md')
+    ),
+    // Hooks: hooks/*.js.
+    hooks: contarComponente(
+      baseDir,
+      'hooks',
+      (e) => e.isFile() && e.name.endsWith('.js')
+    ),
+  };
+}
+
+/**
+ * Lee el nombre declarado en plugin.json si existe y es legible.
+ * @returns {string|null}
+ */
+function leerNombrePlugin(baseDir) {
+  try {
+    const raw = fs.readFileSync(path.join(baseDir, 'plugin.json'), 'utf-8');
+    const json = JSON.parse(raw);
+    return typeof json.name === 'string' ? json.name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detecta si baseDir es el repo host del sistema SWL.
+ *
+ * Criterio (cualquiera de los dos basta):
+ *   1. plugin.json con name ∈ {swl-ses, @saulwade/swl-ses}.
+ *   2. Presencia de los 3 directorios nucleares de componentes con contenido
+ *      (agentes/, habilidades/, comandos/swl/) — cubre forks renombrados.
+ *
+ * @param {string} [baseDir=process.cwd()]
+ * @returns {{esHost:boolean, razon:string, nombrePlugin:(string|null),
+ *            componentes:object, sugerencias:string[]}}
+ */
+function detectarHostSwl(baseDir = process.cwd()) {
+  const nombrePlugin = leerNombrePlugin(baseDir);
+  const componentes = contarComponentes(baseDir);
+
+  const tienePluginHost = nombrePlugin !== null && NOMBRES_HOST.has(nombrePlugin);
+  const tieneNucleo =
+    componentes.agentes > 0 &&
+    componentes.habilidades > 0 &&
+    componentes.comandos > 0;
+
+  const esHost = tienePluginHost || tieneNucleo;
+
+  let razon;
+  if (tienePluginHost) {
+    razon = `plugin.json declara name="${nombrePlugin}" (repo host del sistema SWL).`;
+  } else if (tieneNucleo) {
+    razon =
+      'Presencia de componentes nucleares (agentes/, habilidades/, comandos/swl/) ' +
+      'sin plugin.json canónico — posible fork del sistema SWL.';
+  } else {
+    razon =
+      'Sin plugin.json del sistema y sin directorios de componentes ' +
+      '(agentes/, habilidades/, comandos/swl/): proyecto consumidor de SWL, ' +
+      'no host. El subcomando `salud` audita componentes que aquí no existen ' +
+      'por diseño — un score 0/100 sería engañoso.';
+  }
+
+  return {
+    esHost,
+    razon,
+    nombrePlugin,
+    componentes,
+    sugerencias: esHost ? [] : SUGERENCIAS_CONSUMIDOR.slice(),
+  };
+}
+
+module.exports = {
+  detectarHostSwl,
+  contarComponentes,
+  NOMBRES_HOST,
+  SUGERENCIAS_CONSUMIDOR,
+};
+
+// Entrypoint CLI: `node scripts/lib/detectar-host-swl.js [--json] [baseDir]`
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const dirArg = args.find((a) => !a.startsWith('--'));
+  const resultado = detectarHostSwl(dirArg || process.cwd());
+
+  if (json) {
+    process.stdout.write(JSON.stringify(resultado, null, 2) + '\n');
+  } else if (resultado.esHost) {
+    process.stdout.write(`[host] ${resultado.razon}\n`);
+  } else {
+    process.stdout.write(`[consumidor] ${resultado.razon}\n`);
+    process.stdout.write('Subcomandos de /swl:status aplicables aquí:\n');
+    for (const s of resultado.sugerencias) {
+      process.stdout.write(`  - ${s}\n`);
+    }
+  }
+  // Exit 0 siempre: es diagnóstico, no gate bloqueante.
+  process.exit(0);
+}

package/scripts/lib/evidencia-release.js

@@ -0,0 +1,322 @@
+'use strict';
+
+/**
+ * evidencia-release.js — Evidencia de procedencia del release (Fase 14, ADR-0038).
+ *
+ * Genera, como paso de `/swl:release`, los artefactos de cadena de suministro:
+ *   1. SBOM CycloneDX del árbol runtime (`npm sbom --sbom-format cyclonedx --omit dev`).
+ *   2. SHA256SUMS del tarball producido por `npm pack`.
+ * Ambos se escriben en `releases/vX.Y.Z/` (evidencia versionada en el repo, fuera
+ * del tarball npm — `package.json#files` es allowlist y no incluye `releases/`).
+ *
+ * Diseño: la parte PURA (nombres, formato, sección markdown, validación semver)
+ * se separa de la parte de SUBPROCESO (npm), inyectable vía `opts.ejecutarNpm`
+ * para tests sin tocar npm real.
+ *
+ * Subproceso npm cross-platform: se invoca `node <npm-cli.js> ...` (no `npm.cmd`)
+ * con execFileSync sin shell — patrón de scripts/lib/npm-version.js (evita la
+ * diferencia .cmd/POSIX y DEP0190 en Node 20+).
+ *
+ * Zero-dependencies. CLI: `node scripts/lib/evidencia-release.js --version X.Y.Z`.
+ *
+ * Origen: Fase 14 — cadena de suministro en release (P4, ADR-0038).
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+// Escritura atómica con fallback defensivo idéntico a plan-lock.js (los archivos
+// de evidencia son write-once por release, pero respetamos la convención del repo).
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(__dirname, '..', '..', 'hooks', 'lib', 'atomic-write.js')));
+} catch (err) {
+  // Solo degradar a writeFileSync si el módulo no existe (destino aplanado).
+  // Otros errores (permisos, disco) deben propagarse, no enmascararse.
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  atomicWriteSync = (p, c, e) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, c, e);
+  };
+}
+
+// Semver estricto (core + prerelease + build), suficiente para validar la versión
+// del release sin dependencias. No valida rangos — solo una versión concreta.
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+// Nombre de tarball seguro: lo que produce `npm pack` (scope-paquete-version.tgz).
+// Rechaza newlines, espacios y control chars que corromperían SHA256SUMS.
+const TARBALL_NOMBRE_RE = /^[A-Za-z0-9._@+-]+\.tgz$/;
+// Cota de tamaño del SBOM antes de JSON.parse (defensa DoS por memoria).
+const MAX_SBOM_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Localiza npm-cli.js de la instalación de Node para invocarlo vía `node`.
+ *
+ * Duplicación DELIBERADA del helper de scripts/lib/npm-version.js (~15 líneas).
+ * NO se importa de allí a propósito: `npm-version.js` NO se distribuye al destino
+ * (no está en ningún módulo de modulos.json), mientras esta lib SÍ viaja en
+ * `comandos-core`. Un `require('./npm-version')` rompería con MODULE_NOT_FOUND en
+ * el destino aplanado. La autocontención es el requisito de distribución, no una
+ * omisión — acoplar las dos libs introduciría fragilidad de runtime
+ * (arquitectura.md § "mantener código similar separado cuando la abstracción
+ * compartida sería vaga"). Si se agrega un candidato de ruta nuevo, replicarlo
+ * en ambas.
+ *
+ * @returns {string|null}
+ */
+function localizarNpmCli() {
+  const dir = path.dirname(process.execPath);
+  const candidatos = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  for (const c of candidatos) {
+    try {
+      if (fs.existsSync(c)) return c;
+    } catch { /* continuar */ }
+  }
+  return null;
+}
+
+/**
+ * Valida que `version` sea semver estricto; lanza si no.
+ * @param {string} version
+ */
+function assertSemver(version) {
+  if (typeof version !== 'string' || !SEMVER_RE.test(version)) {
+    throw new Error(`versión inválida (no es semver): ${JSON.stringify(version)}`);
+  }
+}
+
+/**
+ * Nombres de los artefactos de evidencia para una versión dada.
+ * @param {string} version  semver, ej. "2.0.0"
+ * @returns {{dir: string, sbom: string, sums: string}}
+ */
+function nombreArtefactos(version) {
+  assertSemver(version);
+  return {
+    dir: `releases/v${version}`,
+    sbom: `sbom-v${version}.cdx.json`,
+    sums: 'SHA256SUMS',
+  };
+}
+
+/**
+ * Una línea de SHA256SUMS en formato `sha256sum -c` (hash + DOS espacios + nombre).
+ * @param {string} hash    sha256 hex de 64 chars minúsculas
+ * @param {string} archivo nombre del archivo (tarball)
+ * @returns {string}
+ */
+function formatearSums(hash, archivo) {
+  if (typeof hash !== 'string' || !SHA256_HEX_RE.test(hash)) {
+    throw new Error(`hash inválido (se esperaba sha256 hex de 64 chars): ${JSON.stringify(hash)}`);
+  }
+  if (typeof archivo !== 'string' || !TARBALL_NOMBRE_RE.test(archivo)) {
+    // Evita que un nombre con newlines/espacios corrompa el formato sha256sum -c.
+    throw new Error(`nombre de tarball inválido: ${JSON.stringify(archivo)}`);
+  }
+  return `${hash}  ${archivo}`;
+}
+
+/**
+ * Sección markdown "Integridad y verificación" para insertar en RELEASE-NOTES.
+ * @param {{version: string, hash: string, tarball: string}} datos
+ * @returns {string}
+ */
+function seccionVerificacionNotas({ version, hash, tarball }) {
+  assertSemver(version);
+  if (!SHA256_HEX_RE.test(hash)) {
+    throw new Error(`hash inválido en seccionVerificacionNotas: ${JSON.stringify(hash)}`);
+  }
+  const n = nombreArtefactos(version);
+  return [
+    '## Integridad y verificación',
+    '',
+    'Evidencia de procedencia versionada en `' + n.dir + '/`:',
+    '',
+    '- **SBOM** (CycloneDX): `' + n.sbom + '`',
+    '- **Checksums**: `SHA256SUMS`',
+    '',
+    'SHA256 del tarball publicado:',
+    '',
+    '```',
+    formatearSums(hash, tarball),
+    '```',
+    '',
+    'Verificar la integridad tras descargar el paquete:',
+    '',
+    '```bash',
+    `# Bash`,
+    `npm pack @saulwade/swl-ses@${version}`,
+    `sha256sum -c ${n.dir}/SHA256SUMS`,
+    '```',
+    '',
+    '```powershell',
+    `# PowerShell`,
+    `(Get-FileHash ${tarball} -Algorithm SHA256).Hash.ToLower()`,
+    `# debe coincidir con el hash de arriba`,
+    '```',
+    '',
+    'Detalle completo en `docs/verificacion-consumidor.md`.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Ejecutor npm real (default). Inyectable en tests vía opts.ejecutarNpm.
+ * @returns {{sbom: () => string, pack: (destino: string) => string}}
+ */
+function ejecutorNpmReal() {
+  const npmCli = localizarNpmCli();
+  if (!npmCli) {
+    throw new Error(
+      'no se encontró npm-cli.js de la instalación de Node; ' +
+      'evidencia-release requiere npm para generar SBOM y empacar el tarball'
+    );
+  }
+  const correr = (args, opts = {}) =>
+    execFileSync(process.execPath, [npmCli, ...args], {
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      ...opts,
+    });
+
+  return {
+    sbom() {
+      return correr(['sbom', '--sbom-format', 'cyclonedx', '--omit', 'dev']);
+    },
+    pack(destino) {
+      fs.mkdirSync(destino, { recursive: true });
+      // NO usar `npm pack --json`: los scripts de ciclo de vida (prepack)
+      // escriben a stdout y contaminan el JSON. En su lugar empacamos a un
+      // directorio limpio y leemos el único .tgz resultante — robusto ante
+      // cualquier salida de prepack/postpack.
+      correr(['pack', '--pack-destination', destino]);
+      const tgz = fs.readdirSync(destino).filter((f) => f.endsWith('.tgz'));
+      if (tgz.length === 0) {
+        throw new Error(`npm pack no produjo ningún .tgz en ${destino}`);
+      }
+      if (tgz.length > 1) {
+        // El destino es temporal y exclusivo por invocación (pid+timestamp);
+        // más de un tarball indica un destino reutilizado — usar el más reciente.
+        tgz.sort((a, b) =>
+          fs.statSync(path.join(destino, b)).mtimeMs - fs.statSync(path.join(destino, a)).mtimeMs
+        );
+      }
+      return path.join(destino, tgz[0]);
+    },
+  };
+}
+
+/**
+ * Valida y persiste el SBOM. Rechaza salidas no-CycloneDX o demasiado grandes.
+ * @param {string} dir       directorio releases/vX.Y.Z
+ * @param {string} sbomTexto salida cruda de `npm sbom`
+ * @param {string} nombre    nombre del archivo SBOM
+ * @returns {string} ruta del SBOM escrito
+ */
+function persistirSbom(dir, sbomTexto, nombre) {
+  if (typeof sbomTexto !== 'string' || sbomTexto.length > MAX_SBOM_BYTES) {
+    throw new Error(`SBOM ausente o excede ${MAX_SBOM_BYTES} bytes`);
+  }
+  const sbomObj = JSON.parse(sbomTexto);
+  if (!sbomObj || sbomObj.bomFormat !== 'CycloneDX') {
+    throw new Error(`SBOM no es CycloneDX (bomFormat: ${sbomObj && sbomObj.bomFormat})`);
+  }
+  const sbomPath = path.join(dir, nombre);
+  atomicWriteSync(sbomPath, `${JSON.stringify(sbomObj, null, 2)}\n`, 'utf8');
+  return sbomPath;
+}
+
+/**
+ * Empaca el tarball en un dir temporal, calcula su sha256 y limpia el temporal.
+ * @param {object} npm  ejecutor con pack(destino)
+ * @returns {{hash: string, tarball: string}}
+ */
+function calcularChecksumTarball(npm) {
+  const packTmp = path.join(os.tmpdir(), `swl-pack-${process.pid}-${Date.now()}`);
+  try {
+    const tarballPath = npm.pack(packTmp);
+    const buffer = fs.readFileSync(tarballPath);
+    const hash = crypto.createHash('sha256').update(buffer).digest('hex');
+    return { hash, tarball: path.basename(tarballPath) };
+  } finally {
+    try {
+      fs.rmSync(packTmp, { recursive: true, force: true });
+    } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Genera la evidencia de procedencia para `version` bajo `baseDir`.
+ * Escribe releases/vX.Y.Z/{sbom-vX.Y.Z.cdx.json, SHA256SUMS}.
+ *
+ * @param {string} baseDir  raíz del proyecto donde se escribe releases/
+ * @param {string} version  semver del release
+ * @param {object} [opts]
+ * @param {object} [opts.ejecutarNpm]  ejecutor {sbom(), pack(destino)} inyectable
+ * @returns {{hash: string, tarball: string, dir: string, sbomPath: string, sumsPath: string}}
+ */
+function generarEvidencia(baseDir, version, opts = {}) {
+  assertSemver(version); // valida ANTES de invocar npm
+  const npm = opts.ejecutarNpm || ejecutorNpmReal();
+  const n = nombreArtefactos(version);
+  const dir = path.join(baseDir, n.dir);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const sbomPath = persistirSbom(dir, npm.sbom(), n.sbom);
+  const { hash, tarball } = calcularChecksumTarball(npm);
+  const sumsPath = path.join(dir, n.sums);
+  atomicWriteSync(sumsPath, `${formatearSums(hash, tarball)}\n`, 'utf8');
+
+  return { hash, tarball, dir, sbomPath, sumsPath };
+}
+
+// --- CLI ---------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { version: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--version') {
+      out.version = argv[i + 1];
+      i++;
+    } else if (argv[i].startsWith('--version=')) {
+      out.version = argv[i].slice('--version='.length);
+    }
+  }
+  return out;
+}
+
+if (require.main === module) {
+  const { version } = parseArgs(process.argv.slice(2));
+  if (!version) {
+    console.error('uso: node scripts/lib/evidencia-release.js --version X.Y.Z');
+    process.exit(2);
+  }
+  try {
+    const res = generarEvidencia(process.cwd(), version);
+    console.log(`Evidencia generada en ${path.relative(process.cwd(), res.dir)}/`);
+    console.log(`  SBOM:        ${path.basename(res.sbomPath)}`);
+    console.log(`  SHA256SUMS:  ${res.hash}  ${res.tarball}`);
+  } catch (err) {
+    console.error(`error generando evidencia: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  nombreArtefactos,
+  formatearSums,
+  seccionVerificacionNotas,
+  generarEvidencia,
+  ejecutorNpmReal,
+  localizarNpmCli,
+  SEMVER_RE,
+};