@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/harness-source-snapshot.js

@@ -0,0 +1,309 @@
+'use strict';
+
+/**
+ * Captura inmutable y confinada de las fuentes tracked del harness.
+ * Es la única frontera de lectura compartida por Harness IR y PolicyBundle.
+ */
+
+const childProcess = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { normalizarLF, parsearFrontmatter, parsearJSONSeguro } = require('./frontmatter-canonico');
+
+const HOOKS_CONFIG = 'manifiestos/hooks-config.json';
+const MAX_BUFFER_GIT = 16 * 1024 * 1024;
+
+function crearError(codigo, mensaje, extras = {}) {
+  const excepcion = new Error(mensaje);
+  Object.assign(excepcion, { codigo, ...extras });
+  return excepcion;
+}
+
+function sha256(valor) {
+  return crypto.createHash('sha256').update(valor).digest('hex');
+}
+
+function congelarProfundo(valor) {
+  if (!valor || typeof valor !== 'object' || Object.isFrozen(valor)) return valor;
+  Object.values(valor).forEach(congelarProfundo);
+  return Object.freeze(valor);
+}
+
+function ejecutarGit(args, cwd = process.cwd()) {
+  try {
+    return childProcess.execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      maxBuffer: MAX_BUFFER_GIT,
+    });
+  } catch (cause) {
+    throw crearError('GIT_DISCOVERY_FAILED', 'No fue posible consultar Git', { cause });
+  }
+}
+
+function resolverRaizGit() {
+  const declarada = ejecutarGit(['rev-parse', '--show-toplevel']).trim();
+  if (/^[\\/]{2}/u.test(declarada)) {
+    throw crearError('SOURCE_ROOT_UNC_FORBIDDEN', 'La raíz Git no puede ser UNC');
+  }
+  const absoluta = path.resolve(declarada);
+  const stat = fs.lstatSync(absoluta);
+  const real = fs.realpathSync(absoluta);
+  const esAlias = path.relative(absoluta, real) !== '';
+  if (stat.isSymbolicLink() || !stat.isDirectory() || esAlias) {
+    throw crearError('SOURCE_ROOT_LINK_FORBIDDEN', 'La raíz Git debe ser real no enlazada');
+  }
+  return { absoluta, real };
+}
+
+function valorTemporalNs(stat, campoNs, campoMs) {
+  return String(stat[campoNs] === undefined ? stat[campoMs] : stat[campoNs]);
+}
+
+function fingerprint(stat) {
+  return {
+    dev: String(stat.dev),
+    ino: String(stat.ino),
+    size: String(stat.size),
+    mode: String(stat.mode),
+    mtimeNs: valorTemporalNs(stat, 'mtimeNs', 'mtimeMs'),
+    ctimeNs: valorTemporalNs(stat, 'ctimeNs', 'ctimeMs'),
+  };
+}
+
+function fingerprintPath(ruta) {
+  const stat = fs.lstatSync(ruta, { bigint: true });
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw crearError('SOURCE_INDEX_INVALID', 'El path no es un archivo regular');
+  }
+  return fingerprint(stat);
+}
+
+function resolverIndiceGit(root) {
+  const declarada = ejecutarGit(
+    ['rev-parse', '--path-format=absolute', '--git-path', 'index'],
+    root.absoluta
+  ).trim();
+  if (!declarada) throw crearError('SOURCE_INDEX_INVALID', 'Ruta de índice vacía');
+  const absoluta = path.resolve(root.absoluta, declarada);
+  const real = fs.realpathSync(absoluta);
+  if (path.relative(absoluta, real) !== '') {
+    throw crearError('SOURCE_INDEX_INVALID', 'El índice Git está enlazado');
+  }
+  return { absoluta, fingerprint: fingerprintPath(absoluta) };
+}
+
+function revalidarFingerprintIndice(indiceGit) {
+  const actual = fingerprintPath(indiceGit.absoluta);
+  if (JSON.stringify(actual) !== JSON.stringify(indiceGit.fingerprint)) {
+    throw crearError('SOURCE_INDEX_CHANGED', 'La identidad del índice Git cambió');
+  }
+}
+
+function obtenerIndice(root) {
+  const snapshot = ejecutarGit(['ls-files', '--stage', '-z'], root.absoluta);
+  const entradas = snapshot.split('\0').filter(Boolean);
+  const tracked = [];
+  const modes = new Map();
+  for (const entrada of entradas) {
+    const match = entrada.match(/^(\d+) [0-9a-f]+ (\d+)\t([\s\S]+)$/u);
+    if (!match || match[2] !== '0' || modes.has(match[3])) {
+      throw crearError('SOURCE_INDEX_INVALID', 'Entrada de índice Git inválida');
+    }
+    tracked.push(match[3]);
+    modes.set(match[3], match[1]);
+  }
+  return { tracked, modes, snapshot };
+}
+
+function revalidarIndice(root, indice, indiceGit) {
+  const actual = ejecutarGit(['ls-files', '--stage', '-z'], root.absoluta);
+  if (actual !== indice.snapshot) {
+    throw crearError('SOURCE_INDEX_CHANGED', 'El índice Git cambió durante la captura');
+  }
+  revalidarFingerprintIndice(indiceGit);
+}
+
+function validarPathFuente(relativo) {
+  const segmentos = relativo.split('/');
+  const esInvalido = relativo.includes('\\')
+    || path.posix.isAbsolute(relativo)
+    || /^[A-Za-z]:/u.test(relativo)
+    || segmentos.some((segmento) => !segmento || segmento === '.' || segmento === '..');
+  if (esInvalido) throw crearError('SOURCE_PATH_INVALID', `Path fuente inválido: ${relativo}`);
+}
+
+function tipoFuente(relativo) {
+  if (/^agentes\/[^/]+\.md$/u.test(relativo) && !path.posix.basename(relativo).startsWith('_')) {
+    return 'agent';
+  }
+  if (/^comandos\/swl\/[^/]+\.md$/u.test(relativo)) return 'command';
+  if (/^habilidades\/[^/]+\/SKILL\.md$/u.test(relativo)) return 'skill';
+  if (/^reglas\/(?:[^/]+\/)*[^/]+\.md$/u.test(relativo)) return 'rule';
+  return null;
+}
+
+function seleccionarFuentes(indice) {
+  const fuentes = indice.tracked.flatMap((relativo) => {
+    validarPathFuente(relativo);
+    const kind = tipoFuente(relativo);
+    return kind ? [{ path: relativo, kind }] : [];
+  });
+  if (!indice.tracked.includes(HOOKS_CONFIG)) {
+    throw crearError('HOOKS_CONFIG_NOT_TRACKED', `${HOOKS_CONFIG} debe estar tracked`);
+  }
+  return fuentes;
+}
+
+function validarModos(indice, fuentes) {
+  const paths = [...fuentes.map(({ path: relativo }) => relativo), HOOKS_CONFIG];
+  for (const relativo of paths) {
+    if (indice.modes.get(relativo) === '120000') {
+      throw crearError('SOURCE_INDEX_MODE_FORBIDDEN', `Symlink tracked prohibido: ${relativo}`);
+    }
+  }
+}
+
+function estaDentro(base, destino) {
+  const relativo = path.relative(base, destino);
+  return relativo === '' || (!relativo.startsWith(`..${path.sep}`) && !path.isAbsolute(relativo));
+}
+
+function validarSegmentos(root, relativo) {
+  let actual = root.absoluta;
+  for (const segmento of relativo.split('/').slice(0, -1)) {
+    actual = path.join(actual, segmento);
+    const stat = fs.lstatSync(actual);
+    if (stat.isSymbolicLink()) {
+      throw crearError('SOURCE_LINK_FORBIDDEN', `Segmento enlazado prohibido: ${relativo}`);
+    }
+    if (!estaDentro(root.real, fs.realpathSync(actual))) {
+      throw crearError('SOURCE_PATH_ESCAPE', `Segmento fuera de raíz: ${relativo}`);
+    }
+  }
+}
+
+function mismaIdentidad(antes, despues) {
+  return JSON.stringify(fingerprint(antes)) === JSON.stringify(fingerprint(despues));
+}
+
+function abrirDescriptorFuente(absoluta, relativo) {
+  try {
+    return fs.openSync(absoluta, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  } catch (cause) {
+    if (cause.code === 'ELOOP') {
+      throw crearError('SOURCE_LINK_FORBIDDEN', `Fuente enlazada prohibida: ${relativo}`, { cause });
+    }
+    throw crearError('SOURCE_OPEN_FAILED', `No fue posible abrir: ${relativo}`, { cause });
+  }
+}
+
+function leerBytesFuente(descriptor, antes, relativo) {
+  const abierta = fs.fstatSync(descriptor);
+  if (!mismaIdentidad(antes, abierta)) {
+    throw crearError('SOURCE_CHANGED_DURING_READ', `Fuente cambió antes: ${relativo}`);
+  }
+  const bytes = fs.readFileSync(descriptor);
+  if (!mismaIdentidad(abierta, fs.fstatSync(descriptor))) {
+    throw crearError('SOURCE_CHANGED_DURING_READ', `Fuente cambió durante: ${relativo}`);
+  }
+  return bytes;
+}
+
+function leerFuente(root, relativo) {
+  validarPathFuente(relativo);
+  validarSegmentos(root, relativo);
+  const absoluta = path.join(root.absoluta, ...relativo.split('/'));
+  const antes = fs.lstatSync(absoluta);
+  const real = fs.realpathSync(absoluta);
+  if (antes.isSymbolicLink()) {
+    throw crearError('SOURCE_LINK_FORBIDDEN', `Fuente enlazada prohibida: ${relativo}`);
+  }
+  if (!estaDentro(root.real, real)) {
+    throw crearError('SOURCE_PATH_ESCAPE', `Fuente fuera de raíz: ${relativo}`);
+  }
+  const descriptor = abrirDescriptorFuente(absoluta, relativo);
+  let bytes;
+  try {
+    bytes = leerBytesFuente(descriptor, antes, relativo);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  const texto = normalizarLF(bytes.toString('utf8'));
+  return {
+    source: { path: relativo, texto, sha256: sha256(Buffer.from(texto, 'utf8')) },
+    evidencia: { absoluta, real, stat: antes },
+  };
+}
+
+function parsearArchivo(source, descriptor) {
+  if (descriptor.kind === 'rule' && !source.texto.startsWith('---\n')) {
+    return { valor: {}, campos: {}, cuerpo: source.texto };
+  }
+  try {
+    const parsed = parsearFrontmatter(source.texto, { path: descriptor.path });
+    if (descriptor.kind !== 'rule' && parsed.valor === null) {
+      throw crearError('SOURCE_FRONTMATTER_REQUIRED', `Frontmatter requerido: ${descriptor.path}`);
+    }
+    return parsed;
+  } catch (cause) {
+    if (cause.codigo === 'SOURCE_FRONTMATTER_REQUIRED') throw cause;
+    throw crearError('SOURCE_FRONTMATTER_INVALID', 'Frontmatter inválido', {
+      cause,
+      path: descriptor.path,
+    });
+  }
+}
+
+function parsearHooks(source) {
+  try {
+    const resultado = parsearJSONSeguro(source.texto, { path: source.path });
+    return { valor: resultado.valor, propiedades: resultado.propiedades };
+  } catch (cause) {
+    throw crearError('HOOKS_CONFIG_INVALID', 'JSON de hooks inválido', { cause });
+  }
+}
+
+function revalidarFuentes(capturas) {
+  for (const { evidencia, source } of capturas) {
+    const despues = fs.lstatSync(evidencia.absoluta);
+    const realDespues = fs.realpathSync(evidencia.absoluta);
+    if (!mismaIdentidad(evidencia.stat, despues) || evidencia.real !== realDespues) {
+      throw crearError('SOURCE_CHANGED_DURING_READ', `Fuente cambió: ${source.path}`);
+    }
+  }
+}
+
+function digestSnapshot(entries, hooks) {
+  const fuentes = entries.map(({ kind, path: relativo, source }) => ({
+    kind,
+    path: relativo,
+    sha256: source.sha256,
+  }));
+  fuentes.push({ kind: 'hooks-config', path: hooks.source.path, sha256: hooks.source.sha256 });
+  return sha256(JSON.stringify(fuentes));
+}
+
+function capturarHarnessSourceSnapshot() {
+  const root = resolverRaizGit();
+  const indiceGit = resolverIndiceGit(root);
+  const indice = obtenerIndice(root);
+  revalidarFingerprintIndice(indiceGit);
+  const descriptores = seleccionarFuentes(indice);
+  validarModos(indice, descriptores);
+  const capturas = descriptores.map((descriptor) => ({ ...leerFuente(root, descriptor.path), descriptor }));
+  const hooksCaptura = leerFuente(root, HOOKS_CONFIG);
+  const entries = capturas.map(({ descriptor, source }) => ({
+    ...descriptor,
+    source,
+    parsed: parsearArchivo(source, descriptor),
+  }));
+  const hooks = { source: hooksCaptura.source, parsed: parsearHooks(hooksCaptura.source) };
+  revalidarFuentes([...capturas, hooksCaptura]);
+  revalidarIndice(root, indice, indiceGit);
+  return congelarProfundo({ entries, hooks, snapshotDigest: digestSnapshot(entries, hooks) });
+}
+
+module.exports = { capturarHarnessSourceSnapshot };