shilo-cli 0.7.0 → 0.9.0

package/src/gitobjects.js

@@ -0,0 +1,532 @@
+'use strict';
+
+/**
+ * Del grafo de Shilo a objetos Git. Parte PURA.
+ *
+ * Etapa 5 del PLAN_MOTOR_SHILO, Parte A (§8.8). Acá no hay red ni `git`: recibe
+ * el grafo ya leído (commits, árboles y bytes de blobs) y devuelve los objetos
+ * Git con sus SHA-1. Escribirlos en un repo es de `shilo export` (Parte B).
+ *
+ * La conversión tiene que ser determinística: el mismo grafo da los mismos
+ * SHA-1 en cualquier máquina y cualquier día (invariante 2 de la etapa). Por eso
+ * nada de acá lee el reloj, el usuario que exporta ni el orden en que llegaron
+ * las filas. Cada trampa de la tabla de §8.8 (A1…A15) está marcada donde se
+ * resuelve, y cada una tiene su test.
+ *
+ * Los SHA-1 no reemplazan a los `oid` (SHA-256) del grafo: son una proyección
+ * (🔴 7 de §8.8, GitHub no acepta repos SHA-256). El puente es `mapa`.
+ */
+
+const { createHash } = require('crypto');
+
+// A3: en el objeto árbol el modo de carpeta va sin el cero. El `040000` del
+// grafo es sólo de presentación.
+const MODO_ARCHIVO = '100644';
+const MODO_CARPETA = '40000';
+
+// A7: quien firma lo que no tiene autor (los commits del backfill) y el commit
+// de las notas. Fija: si cambiara, cambiarían los SHA-1 de todo lo exportado.
+const IDENTIDAD_SHILO = Object.freeze({ name: 'Shilo', email: 'noreply@shilo.city' });
+
+const REF_NOTAS = 'refs/notes/shilo';
+
+// El oid del árbol vacío en el grafo: SHA-256 de la cadena vacía. Es también el
+// del archivo vacío (ver `convertirGrafo`).
+const OID_VACIO = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+
+// Mensaje del commit de notas. Fijo por la misma razón que la identidad.
+const MENSAJE_NOTAS = 'Procedencia de Shilo\n';
+
+// Asunto de un guardado sin mensaje (decidido el 2026-09-28, antes de la primera
+// exportación real). Sin él, el pie `Shilo-Oid: …` queda como título en
+// `git log --oneline`. Fijo: cambiarlo movería el SHA-1 de todos esos commits.
+const ASUNTO_SIN_MENSAJE = 'Punto de guardado';
+
+/**
+ * Error de la conversión. `code` es estable (lo lee `shilo export` para decir
+ * qué hacer) y `path`, cuando hay, es la ruta exacta dentro del proyecto.
+ */
+class ErrorConversion extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'ErrorConversion';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+/**
+ * A1: SHA-1 de un objeto Git. Git no hashea el contenido pelado sino
+ * `"<tipo> <largo>\0" + contenido`, con el largo en bytes.
+ */
+function gitSha1(tipo, cuerpo) {
+  const bytes = aBuffer(cuerpo);
+  return createHash('sha1')
+    .update(`${tipo} ${bytes.length}\0`, 'utf8')
+    .update(bytes)
+    .digest('hex');
+}
+
+/** Blob Git a partir de los bytes crudos. A15: sin normalizar CRLF ni BOM. */
+function gitBlob(contenido) {
+  const cuerpo = aBuffer(contenido);
+  return { tipo: 'blob', cuerpo, sha1: gitSha1('blob', cuerpo) };
+}
+
+/**
+ * A2: el orden de un árbol Git. Por bytes UTF-8, y cada carpeta se compara como
+ * si su nombre terminara en `/`. No es el orden de `canonicalizeTree`, que
+ * compara unidades UTF-16 sin la barra: `a-b` y `a/` (el `-` es 0x2D, la `/` es
+ * 0x2F), o un emoji contra un carácter de U+E000–U+FFFF, salen al revés.
+ *
+ * @param {Array<{name, type}>} entradas - type: 'blob' | 'tree'
+ * @returns {Array} copia ordenada
+ */
+function ordenGit(entradas) {
+  const clave = (e) => Buffer.from(e.type === 'tree' ? `${e.name}/` : e.name, 'utf8');
+  return entradas
+    .map((e) => ({ e, k: clave(e) }))
+    .sort((x, y) => Buffer.compare(x.k, y.k))
+    .map(({ e }) => e);
+}
+
+/**
+ * Árbol Git. A4: es binario — `modo SP nombre NUL` y los 20 bytes crudos del
+ * SHA-1 —, no texto.
+ *
+ * @param {Array<{name, type, sha1}>} entradas
+ */
+function gitTree(entradas) {
+  const vistos = new Set();
+  for (const e of entradas) {
+    validarNombre(e.name);
+    if (vistos.has(e.name)) {
+      throw new ErrorConversion('NOMBRE_REPETIDO', `El nombre «${e.name}» está dos veces en la misma carpeta.`, { name: e.name });
+    }
+    vistos.add(e.name);
+  }
+
+  const partes = [];
+  for (const e of ordenGit(entradas)) {
+    const modo = e.type === 'tree' ? MODO_CARPETA : MODO_ARCHIVO;
+    partes.push(Buffer.from(`${modo} ${e.name}\0`, 'utf8'));
+    partes.push(Buffer.from(e.sha1, 'hex'));
+  }
+
+  const cuerpo = Buffer.concat(partes);
+  return { tipo: 'tree', cuerpo, sha1: gitSha1('tree', cuerpo) };
+}
+
+// Los caracteres que HFS+ ignora al comparar nombres: `.g‌it` es `.git`
+// para macOS, y `git fsck` lo rechaza igual. Es la lista de `is_hfs_dotgit`.
+const IGNORABLES_HFS = /[\u200C-\u200F\u202A-\u202E\u206A-\u206F\uFEFF]/g;
+
+/**
+ * A6: un nombre que Git no admite dentro de un árbol.
+ *
+ * `.git` en cualquier combinación de mayúsculas —y sus variantes de NTFS
+ * (`git~1`, espacios o puntos al final) y de HFS+— es lo que `git fsck` y el
+ * `fsck` de GitHub rebotan. `filenames.js` deja pasar `.git` porque su lista
+ * negra piensa en Windows, no en Git (🔴 2). No se renombra: se corta.
+ */
+function validarNombre(nombre) {
+  if (typeof nombre !== 'string' || nombre === '' || nombre === '.' || nombre === '..' || nombre.includes('/') || nombre.includes('\0')) {
+    throw new ErrorConversion('NOMBRE_INVALIDO', `«${nombre}» no es un nombre válido para Git.`, { name: nombre });
+  }
+
+  const plano = nombre.replace(IGNORABLES_HFS, '').replace(/[. ]+$/, '').toLowerCase();
+  if (plano === '.git' || plano === 'git~1') {
+    throw new ErrorConversion(
+      'NOMBRE_GIT',
+      `«${nombre}» es un nombre reservado por Git y ningún repositorio Git lo acepta.`,
+      { name: nombre }
+    );
+  }
+}
+
+/**
+ * A7 + A8: la línea de firma, `Nombre <correo> segundos +0000`.
+ *
+ * El nombre y el correo se limpian como los limpia Git (`fmt_ident`): fuera
+ * `<`, `>` y saltos de línea, y fuera la «basura» de los bordes (espacios y
+ * `,:;"'\`; el punto no, por nombres como «Jr.»). Así la firma es la misma que
+ * Git escribiría con esos datos.
+ *
+ * La fecha se lee del VALOR, no del texto: PostgREST puede devolver `Z` o
+ * `+00:00`, y con microsegundos. El milisegundo se trunca, y el huso es siempre
+ * `+0000` porque el grafo no guarda el de quien guardó.
+ */
+function firmaGit(identidad, fecha) {
+  const nombre = limpiarIdentidad(identidad && identidad.name);
+  const correo = limpiarIdentidad(identidad && identidad.email);
+  if (!nombre || !correo) {
+    throw new ErrorConversion('IDENTIDAD_INCOMPLETA', 'Falta el nombre o el correo de quien firma.');
+  }
+  return `${nombre} <${correo}> ${segundosUnix(fecha)} +0000`;
+}
+
+// La «basura» de los bordes según `crud()` de Git: control y espacio (<= 32) y
+// estos signos. Por código y no con un rango en el regex, igual que en
+// `filenames.js`: escritos literales, los bytes de control no se ven.
+const BASURA = new Set([',', ':', ';', '<', '>', '"', '\\', '\'']);
+const esBasura = (c) => c.charCodeAt(0) <= 32 || BASURA.has(c);
+
+function limpiarIdentidad(valor) {
+  const s = String(valor || '').replace(/[<>\n]/g, '').replace(/\0/g, '');
+  let i = 0;
+  let j = s.length;
+  while (i < j && esBasura(s[i])) i += 1;
+  while (j > i && esBasura(s[j - 1])) j -= 1;
+  return s.slice(i, j);
+}
+
+function segundosUnix(fecha) {
+  const ms = fecha instanceof Date ? fecha.getTime() : Date.parse(fecha);
+  if (!Number.isFinite(ms)) {
+    throw new ErrorConversion('FECHA_INVALIDA', `«${fecha}» no es una fecha.`);
+  }
+  return Math.floor(ms / 1000);
+}
+
+/**
+ * A11: las pocas líneas legibles que van al pie del mensaje. Entran en el SHA-1,
+ * así que van sólo las cortas y estables; lo voluminoso va en la nota.
+ *
+ * El agente sale del primer nivel o, en un commit de dos padres, de lo que se
+ * propuso (`proposed`): el que aplica una propuesta de un agente la firma, pero
+ * el contenido lo escribió el agente.
+ */
+function trailers(provenance, oid) {
+  const p = provenance || {};
+  const agente = p.agent || (p.proposed && p.proposed.agent) || null;
+  const linea = (clave, valor) => {
+    const texto = String(valor === null || valor === undefined ? '' : valor).replace(/[\r\n]+/g, ' ').trim();
+    return texto ? `${clave}: ${texto}` : null;
+  };
+
+  return [
+    agente && linea('Shilo-Agent', agente.name),
+    agente && linea('Shilo-Model', agente.model),
+    linea('Shilo-Card', p.card),
+    linea('Shilo-Proposal', p.proposal_id),
+    linea('Shilo-Oid', oid)
+  ].filter(Boolean);
+}
+
+/**
+ * A11: la nota con la procedencia completa, como `canonicalJson`. Las notas no
+ * entran en el SHA-1 del commit, así que acá sí va todo (`resolutions`, `kept`).
+ * A14: un `prompt_ref` viaja como oid, nunca el texto del prompt.
+ * Sin procedencia no hay nota.
+ */
+function notaShilo(provenance) {
+  if (!provenance || typeof provenance !== 'object' || Object.keys(provenance).length === 0) return null;
+  return `${canonicalJson(provenance)}\n`;
+}
+
+/**
+ * Commit Git.
+ *
+ * A9: el committer es el autor, con la misma fecha. Si fuera «quien exporta,
+ * ahora», dos exportaciones del mismo grafo darían SHA-1 distintos.
+ * A10: Git exige el `\n` final; los saltos de línea van crudos. Un mensaje
+ * vacío es válido.
+ * A12: los padres en el orden guardado. El primero es `main`.
+ *
+ * @param {Object} c
+ * @param {string} c.tree - SHA-1 del árbol
+ * @param {string[]} [c.parents] - SHA-1 de los padres, en orden
+ * @param {string} c.firma - salida de `firmaGit`
+ * @param {string} [c.message]
+ * @param {string[]} [c.trailers]
+ */
+function gitCommit({ tree, parents = [], firma, message = '', trailers: pie = [] }) {
+  let texto = String(message || '');
+  if (texto && !texto.endsWith('\n')) texto += '\n';
+  if (pie.length > 0) texto += `${texto ? '\n' : ''}${pie.join('\n')}\n`;
+
+  const cabecera = [`tree ${tree}`, ...parents.map((p) => `parent ${p}`), `author ${firma}`, `committer ${firma}`];
+  const cuerpo = Buffer.from(`${cabecera.join('\n')}\n\n${texto}`, 'utf8');
+  return { tipo: 'commit', cuerpo, sha1: gitSha1('commit', cuerpo) };
+}
+
+/**
+ * Convierte el grafo alcanzable desde `heads` en objetos Git.
+ *
+ * A13: se recorre desde las cabezas hacia atrás por los padres; un commit que
+ * perdió la carrera del CAS no es alcanzable y no sale. A5: una carpeta vacía —o
+ * que sólo tiene carpetas vacías— se omite y se lista en `vacias`, sin inventar
+ * un `.gitkeep`.
+ *
+ * El `oid` de cada blob se comprueba contra sus bytes: un blob que no describe
+ * su contenido es un grafo roto, y exportarlo lo esparciría.
+ *
+ * @param {Object} grafo
+ * @param {Object<string, Object>} grafo.commits - oid → fila de `commit_objects`
+ * @param {Object<string, Array<{name, type, oid}>>} grafo.trees - oid → entradas
+ * @param {Object<string, Buffer|string>} grafo.blobs - oid → bytes
+ * @param {Object<string, string>} grafo.heads - nombre de ref → oid de commit
+ * @param {Object<string, {name, email}>} [grafo.identidades] - author_id → identidad congelada
+ * @param {Object} [grafo.mapaPrevio] - el `mapa` de una exportación anterior:
+ *   lo que se vuelve a convertir tiene que dar lo mismo (`SHA1_MOVIDO`), y los
+ *   árboles y blobs que no vinieron se toman de ahí sin bajarlos. Los objetos
+ *   sembrados no están en `objetos`: ya están en el repo.
+ * @returns {{ objetos: Map, mapa: Object, refs: Object, notas: Object, vacias: string[] }}
+ */
+function convertirGrafo({ commits, trees, blobs, heads, identidades = {}, mapaPrevio = {} }) {
+  const objetos = new Map();
+  // Un mapa por tipo, no uno solo: en el grafo el árbol vacío y el archivo vacío
+  // tienen el MISMO oid (los dos son el SHA-256 de la cadena vacía), y en Git
+  // son dos objetos distintos.
+  const mapa = { commits: {}, trees: {}, blobs: {} };
+  const vacias = new Set();
+  const notas = {};
+
+  const guardar = (tipo, oid, objeto) => {
+    objetos.set(objeto.sha1, objeto);
+    // Una exportación incremental no confía en lo viejo: lo recalcula y exige
+    // el mismo SHA-1. Si cambió, es un bug de esta conversión, no algo a pisar.
+    const previo = mapaPrevio[tipo] && mapaPrevio[tipo][oid];
+    if (previo && previo !== objeto.sha1) {
+      throw new ErrorConversion(
+        'SHA1_MOVIDO',
+        `El objeto ${oid.slice(0, 12)} daba ${previo.slice(0, 12)} y ahora da ${objeto.sha1.slice(0, 12)}.`,
+        { oid }
+      );
+    }
+    mapa[tipo][oid] = objeto.sha1;
+    return objeto.sha1;
+  };
+
+  // Incremental: un árbol o un blob que no vino pero ya se exportó se toma del
+  // mapa previo sin bajarlo. El oid es por contenido, así que el mismo oid es
+  // el mismo objeto Git, que ya está en el repo. Los commits no se siembran:
+  // son filas, bajarlos todos es barato, y así cada exportación los recalcula
+  // y los compara contra el mapa (y la ref de notas sale completa).
+  const sembrado = (tipo, oid) => {
+    const previo = mapaPrevio[tipo] && mapaPrevio[tipo][oid];
+    if (previo) mapa[tipo][oid] = previo;
+    return Boolean(previo);
+  };
+
+  const blobSha1 = (oid, ruta) => {
+    if (mapa.blobs[oid]) return mapa.blobs[oid];
+    const bytes = blobs[oid];
+    if (bytes === undefined && sembrado('blobs', oid)) return mapa.blobs[oid];
+    if (bytes === undefined) {
+      throw new ErrorConversion('FALTA_OBJETO', `Falta el contenido de ${ruta}.`, { oid, path: ruta });
+    }
+    const buf = aBuffer(bytes);
+    if (createHash('sha256').update(buf).digest('hex') !== oid) {
+      throw new ErrorConversion('BLOB_CORRUPTO', `El contenido de ${ruta} no coincide con su identidad.`, { oid, path: ruta });
+    }
+    return guardar('blobs', oid, gitBlob(buf));
+  };
+
+  // Cache por oid de árbol: `null` = quedó vacío en Git. El árbol no depende de
+  // su ruta, pero la lista de vacías sí, así que se recuerda por oid qué rutas
+  // relativas quedaron vacías y se reportan con cada ruta donde aparece.
+  const arboles = new Map();
+
+  const convertirArbol = (oid, ruta) => {
+    if (!arboles.has(oid)) {
+      const entradas = trees[oid] || (oid === OID_VACIO ? [] : null);
+      // Sembrado: las carpetas vacías de adentro ya se informaron cuando se
+      // exportó por primera vez; acá no se vuelven a listar.
+      if (!entradas && sembrado('trees', oid)) {
+        arboles.set(oid, { sha1: mapa.trees[oid], vaciasRel: [] });
+        return arboles.get(oid);
+      }
+      if (!entradas) throw new ErrorConversion('FALTA_OBJETO', `Falta la carpeta ${ruta || '/'}.`, { oid, path: ruta });
+
+      const salida = [];
+      const vaciasRel = [];
+      for (const e of entradas) {
+        const hija = ruta ? `${ruta}/${e.name}` : e.name;
+        try {
+          validarNombre(e.name);
+        } catch (err) {
+          err.path = hija;
+          throw err;
+        }
+        if (e.type === 'tree') {
+          const sub = convertirArbol(e.oid, hija);
+          vaciasRel.push(...sub.vaciasRel.map((r) => `${e.name}/${r}`));
+          if (sub.sha1) salida.push({ name: e.name, type: 'tree', sha1: sub.sha1 });
+          else vaciasRel.push(e.name);
+        } else {
+          salida.push({ name: e.name, type: 'blob', sha1: blobSha1(e.oid, hija) });
+        }
+      }
+
+      let sha1 = null;
+      if (salida.length > 0) {
+        try {
+          sha1 = guardar('trees', oid, gitTree(salida));
+        } catch (err) {
+          if (!err.path) err.path = ruta || '/';
+          throw err;
+        }
+      }
+      arboles.set(oid, { sha1, vaciasRel });
+    }
+
+    const hecho = arboles.get(oid);
+    for (const r of hecho.vaciasRel) vacias.add(ruta ? `${ruta}/${r}` : r);
+    return hecho;
+  };
+
+  const raiz = (oid) => {
+    const { sha1 } = convertirArbol(oid, '');
+    // La raíz vacía sí existe en Git: el árbol vacío.
+    return sha1 || guardar('trees', oid, gitTree([]));
+  };
+
+  const convertirCommit = (oid) => {
+    // Recorrido iterativo en post-orden: una historia larga desbordaría la pila
+    // con recursión.
+    const pila = [oid];
+    while (pila.length > 0) {
+      const actual = pila[pila.length - 1];
+      if (mapa.commits[actual]) { pila.pop(); continue; }
+
+      const fila = commits[actual];
+      if (!fila) throw new ErrorConversion('FALTA_OBJETO', `Falta el punto de guardado ${actual.slice(0, 12)}.`, { oid: actual });
+
+      const pendientes = (fila.parents || []).filter((p) => !mapa.commits[p]);
+      if (pendientes.length > 0) {
+        pila.push(...pendientes);
+        continue;
+      }
+      pila.pop();
+
+      const sha1 = guardar('commits', actual, gitCommit({
+        tree: raiz(fila.tree_oid),
+        parents: (fila.parents || []).map((p) => mapa.commits[p]),
+        firma: firmaGit(identidadDe(fila, identidades), fila.created_at),
+        message: String(fila.message || '').trim() === '' ? ASUNTO_SIN_MENSAJE : fila.message,
+        trailers: trailers(fila.provenance, actual)
+      }));
+
+      const nota = notaShilo(fila.provenance);
+      if (nota) notas[sha1] = nota;
+    }
+    return mapa.commits[oid];
+  };
+
+  const refs = {};
+  for (const nombre of Object.keys(heads).sort()) {
+    refs[nombre] = convertirCommit(heads[nombre]);
+  }
+
+  // El mapa que se devuelve es el que hay que guardar: el previo más lo nuevo.
+  // Con una raíz sembrada no se recorre lo de adentro, así que lo convertido
+  // en esta vuelta sólo no alcanza para la próxima.
+  const unido = {};
+  for (const tipo of Object.keys(mapa)) unido[tipo] = { ...(mapaPrevio[tipo] || {}), ...mapa[tipo] };
+
+  return { objetos, mapa: unido, refs, notas, vacias: [...vacias].sort() };
+}
+
+/**
+ * A7: quién firma un commit. Sin autor (backfill) firma Shilo; con autor, su
+ * identidad congelada, que la trae quien llama. Leer `username` en vivo haría
+ * que el mismo grafo diera otro SHA-1 el día que alguien se cambia el nombre.
+ */
+function identidadDe(fila, identidades) {
+  if (!fila.author_id) return IDENTIDAD_SHILO;
+  const identidad = identidades[fila.author_id];
+  if (!identidad) {
+    throw new ErrorConversion('FALTA_IDENTIDAD', `Falta la identidad congelada de ${fila.author_id}.`, { author_id: fila.author_id });
+  }
+  return identidad;
+}
+
+/**
+ * El commit de `refs/notes/shilo`: un árbol con un blob por commit anotado,
+ * nombrado con su SHA-1, y un commit sin padre firmado por Shilo.
+ *
+ * Sin padre y con la fecha del commit anotado más reciente, para que dependa
+ * sólo del grafo: exportar dos veces da la misma ref de notas. El costo es que
+ * una exportación incremental reemplaza la ref en vez de avanzarla.
+ *
+ * @param {Object<string, string>} notas - SHA-1 del commit → texto
+ * @param {string|Date} fecha
+ * @returns {{ objetos: Array, sha1: string } | null}
+ */
+function gitNotas(notas, fecha) {
+  const claves = Object.keys(notas);
+  if (claves.length === 0) return null;
+
+  const blobs = claves.map((sha1) => ({ sha1, blob: gitBlob(notas[sha1]) }));
+  const arbol = gitTree(blobs.map(({ sha1, blob }) => ({ name: sha1, type: 'blob', sha1: blob.sha1 })));
+  const commit = gitCommit({ tree: arbol.sha1, firma: firmaGit(IDENTIDAD_SHILO, fecha), message: MENSAJE_NOTAS });
+
+  return { objetos: [...blobs.map((b) => b.blob), arbol, commit], sha1: commit.sha1 };
+}
+
+/**
+ * JSON con las claves ordenadas en todos los niveles. Copia de `canonicalJson`
+ * de `backend/utils/objectGraph.js` (el CLI no importa del backend); el test de
+ * espejo las compara.
+ */
+function canonicalJson(value) {
+  if (value === undefined || value === null) return '{}';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+function aBuffer(x) {
+  return Buffer.isBuffer(x) ? x : Buffer.from(String(x), 'utf8');
+}
+
+/**
+ * Las entradas de un árbol de Shilo a partir de su texto serializado, tal como
+ * lo devuelve `GET /api/projects/graph?objects=trees` (B1).
+ *
+ * Primero se comprueba que `sha256(texto) === oid`: el export no le cree al
+ * servidor, igual que no le cree a los blobs. Después se parsea con las mismas
+ * reglas que `parseTree` del backend (el test de deriva las compara), y se
+ * exige que cada línea sea una entrada completa: un árbol que parsea "más o
+ * menos" daría un repositorio que parece bien y no lo está.
+ */
+function leerArbolShilo(oid, texto) {
+  if (createHash('sha256').update(texto, 'utf8').digest('hex') !== oid) {
+    throw new ErrorConversion('ARBOL_CORRUPTO', `El árbol ${oid.slice(0, 8)} no coincide con su identidad.`, { oid });
+  }
+  if (texto === '') return [];
+
+  return texto.split('\n').filter((linea) => linea.length > 0).map((linea) => {
+    const [mode, type, hijo, ...resto] = linea.split('\t');
+    const name = resto.join('\t');
+    if ((type !== 'blob' && type !== 'tree') || !/^[0-9a-f]{64}$/.test(hijo || '') || name === '') {
+      throw new ErrorConversion('ARBOL_CORRUPTO', `El árbol ${oid.slice(0, 8)} tiene una entrada ilegible.`, { oid, linea });
+    }
+    return { mode, type, oid: hijo, name };
+  });
+}
+
+module.exports = {
+  leerArbolShilo,
+  gitSha1,
+  gitBlob,
+  gitTree,
+  gitCommit,
+  gitNotas,
+  ordenGit,
+  firmaGit,
+  trailers,
+  notaShilo,
+  validarNombre,
+  convertirGrafo,
+  canonicalJson,
+  ErrorConversion,
+  IDENTIDAD_SHILO,
+  ASUNTO_SIN_MENSAJE,
+  REF_NOTAS,
+  MODO_ARCHIVO,
+  MODO_CARPETA
+};

package/src/projectconfig.js

@@ -0,0 +1,76 @@
+/**
+ * `shilo.config.json` del lado del CLI (EP-S2): **espejo** de
+ * `backend/utils/projectConfig.js`, que es donde está explicado el porqué.
+ * El CLI no puede importar del backend; `backend/utils/__tests__/projectConfig.test.js`
+ * corre los dos sobre las mismas entradas para que no se separen.
+ *
+ * El CLI la lee de la carpeta local: los chequeos (MU-93) se corren antes de
+ * proponer, con lo que hay en disco.
+ */
+
+'use strict';
+
+const CONFIG_PATH = 'shilo.config.json';
+const UNIONES = ['archivo', 'lineas'];
+const MAX_CHEQUEOS = 10;
+const MAX_COMANDO = 500;
+
+/** Los comandos válidos de `chequeos`, anotando en `avisos` lo que se ignora. */
+function parseChequeos(raw, avisos) {
+  if (!Array.isArray(raw)) {
+    avisos.push('"chequeos" debe ser una lista de comandos');
+    return [];
+  }
+  const out = [];
+  for (const cmd of raw) {
+    if (typeof cmd !== 'string' || !cmd.trim() || cmd.length > MAX_COMANDO) {
+      avisos.push('Se ignoró un chequeo que no es un comando de texto');
+    } else if (out.length >= MAX_CHEQUEOS) {
+      avisos.push(`Más de ${MAX_CHEQUEOS} chequeos: se ignoran los demás`);
+      break;
+    } else {
+      out.push(cmd.trim());
+    }
+  }
+  return out;
+}
+
+/** El objeto de `shilo.config.json`, o null con el aviso de por qué no. */
+function parseObject(text, avisos) {
+  let raw;
+  try {
+    const clean = String(text);
+    // Sin BOM: JSON.parse no lo acepta y algunos editores de Windows lo ponen.
+    raw = JSON.parse(clean.charCodeAt(0) === 0xfeff ? clean.slice(1) : clean);
+  } catch (err) {
+    avisos.push(`${CONFIG_PATH} no es JSON válido: se usan los valores por defecto`);
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    avisos.push(`${CONFIG_PATH} debe ser un objeto: se usan los valores por defecto`);
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * @param {string|null|undefined} text - contenido de `shilo.config.json`
+ * @returns {{ union: 'archivo'|'lineas', chequeos: string[], avisos: string[] }}
+ */
+function parseProjectConfig(text) {
+  const config = { union: 'archivo', chequeos: [], avisos: [] };
+  if (text === null || text === undefined || String(text).trim() === '') return config;
+
+  const raw = parseObject(text, config.avisos);
+  if (!raw) return config;
+
+  if (raw.union !== undefined) {
+    if (UNIONES.includes(raw.union)) config.union = raw.union;
+    else config.avisos.push(`"union" debe ser ${UNIONES.join(' o ')}: se usa "archivo"`);
+  }
+  if (raw.chequeos !== undefined) config.chequeos = parseChequeos(raw.chequeos, config.avisos);
+
+  return config;
+}
+
+module.exports = { CONFIG_PATH, UNIONES, MAX_CHEQUEOS, parseProjectConfig };