@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/evidencia-release.js

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