@jpkme/diff-review 0.1.6 → 0.1.10

package/lib/agents.mjs

@@ -0,0 +1,319 @@
+/**
+ * Agentes de código que la CLI puede lanzar con el prompt (`--agent`).
+ *
+ * No hay un registro de agentes en ningún SO: se detectan por nombre en el PATH más algunas rutas fijas
+ * conocidas (p. ej. el Claude Code que trae la app de escritorio en Windows). El prompt viaja por stdin, así
+ * no se toca el portapapeles ni se choca con el límite de largo de la línea de comandos de los shims `.cmd`.
+ */
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+/**
+ * @typedef {{ value: string, label: string, hint?: string }} ModelOption
+ * @typedef {{ model?: string, outputFilename: string }} RunSpec
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   bins: string[],
+ *   extraPaths?: (ctx: DetectContext) => string[],
+ *   models: ModelOption[],
+ *   configuredModel?: (ctx: DetectContext) => { model: string, source: string } | null,
+ *   args: (spec: RunSpec) => string[],
+ * }} AgentDef
+ * @typedef {{ env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string }} DetectContext
+ * @typedef {{ def: AgentDef, path: string }} DetectedAgent
+ */
+
+/** @param {string} file */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Primer `model = "..."` de nivel raíz de un TOML (antes de cualquier `[sección]`). */
+export function topLevelTomlModel(text) {
+  for (const line of String(text).split(/\r?\n/)) {
+    if (/^\s*\[/.test(line)) break;
+    const m = line.match(/^\s*model\s*=\s*["']([^"']+)["']/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/** Versiones tipo `2.1.286` de mayor a menor (las que no parsean, al final). */
+function byVersionDesc(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pb[i] || 0) - (pa[i] || 0);
+    if (d) return Number.isNaN(d) ? 0 : d;
+  }
+  return 0;
+}
+
+/** `<root>/<versión>/<hash>/<exe>` → rutas, de la versión más nueva a la más vieja. */
+function versionedBinaries(root, exe) {
+  /** @type {string[]} */
+  const out = [];
+  let versions;
+  try {
+    versions = readdirSync(root).sort(byVersionDesc);
+  } catch {
+    return out;
+  }
+  for (const version of versions) {
+    let entries;
+    try {
+      entries = readdirSync(join(root, version));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) out.push(join(root, version, entry, exe));
+  }
+  return out;
+}
+
+/** @type {AgentDef[]} */
+export const AGENTS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    bins: ["claude"],
+    extraPaths: ({ env, platform, home }) => {
+      if (platform === "win32") {
+        // La app de escritorio trae su propio Claude Code, fuera del PATH.
+        const appData = env.APPDATA || join(home, "AppData", "Roaming");
+        return versionedBinaries(join(appData, "Claude", "claude-code"), "claude.exe");
+      }
+      const paths = [join(home, ".local", "bin", "claude"), join(home, ".claude", "local", "claude")];
+      if (platform === "darwin") {
+        paths.push(...versionedBinaries(join(home, "Library", "Application Support", "Claude", "claude-code"), "claude"));
+      }
+      return paths;
+    },
+    // Alias estables del CLI: siempre apuntan al último modelo de cada familia.
+    models: [
+      { value: "opus", label: "opus", hint: "el más capaz" },
+      { value: "sonnet", label: "sonnet", hint: "equilibrado" },
+      { value: "haiku", label: "haiku", hint: "el más rápido" },
+    ],
+    configuredModel: ({ env, home }) => {
+      if (env.ANTHROPIC_MODEL) return { model: env.ANTHROPIC_MODEL, source: "ANTHROPIC_MODEL" };
+      const file = join(home, ".claude", "settings.json");
+      const model = readJson(file)?.model;
+      return typeof model === "string" && model ? { model, source: "~/.claude/settings.json" } : null;
+    },
+    args: ({ model, outputFilename }) => [
+      "-p",
+      ...(model ? ["--model", model] : []),
+      // Solo lectura + git + el validate, y escribir únicamente el JSON del review (Edit cubre Write).
+      "--allowedTools",
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash(git:*)",
+      "Bash(npx --yes @jpkme/diff-review validate:*)",
+      `Edit(./${outputFilename})`,
+    ],
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    bins: ["codex"],
+    models: [],
+    configuredModel: ({ home }) => {
+      try {
+        const model = topLevelTomlModel(readFileSync(join(home, ".codex", "config.toml"), "utf8"));
+        return model ? { model, source: "~/.codex/config.toml" } : null;
+      } catch {
+        return null;
+      }
+    },
+    // `-` = prompt por stdin; workspace-write deja escribir el JSON en el repo.
+    args: ({ model }) => ["exec", "--sandbox", "workspace-write", ...(model ? ["-m", model] : []), "-"],
+  },
+  {
+    id: "cursor",
+    label: "Cursor CLI",
+    // No `agent` (el alias nuevo): es un nombre demasiado genérico en el PATH. Tampoco `cursor`, que abre el IDE.
+    bins: ["cursor-agent"],
+    extraPaths: ({ env, platform, home }) =>
+      platform === "win32"
+        ? [join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "cursor-agent", "cursor-agent.cmd")]
+        : [join(home, ".local", "bin", "cursor-agent")],
+    models: [],
+    configuredModel: ({ home }) => {
+      const config = readJson(join(home, ".cursor", "cli-config.json"));
+      const id = config?.selectedModel?.modelId ?? config?.model?.modelId;
+      if (typeof id !== "string" || !id) return null;
+      // "default" es Auto: Cursor elige el modelo.
+      return { model: id === "default" ? "auto" : id, source: "~/.cursor/cli-config.json" };
+    },
+    // Con -p lee el prompt de stdin. Sin --force solo corre lo que esté en la allowlist del usuario
+    // (`~/.cursor/cli-config.json`) y bloquearía el validate; no hay flag para pasar una allowlist.
+    args: ({ model }) => ["-p", "--output-format", "text", "--trust", "--force", ...(model ? ["--model", model] : [])],
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot CLI",
+    bins: ["copilot"],
+    models: [{ value: "auto", label: "auto", hint: "Copilot elige" }],
+    configuredModel: ({ env, home }) => {
+      const dir = env.COPILOT_HOME || join(home, ".copilot");
+      const model = readJson(join(dir, "settings.json"))?.model;
+      const source = env.COPILOT_HOME ? "$COPILOT_HOME/settings.json" : "~/.copilot/settings.json";
+      return typeof model === "string" && model ? { model, source } : null;
+    },
+    // Prompt por stdin (sin -p). Lo que no está permitido se rechaza sin preguntar: git, npx (las reglas de shell
+    // matchean por comando, no por argumentos, así que no se puede acotar al validate) y escribir solo el JSON
+    // del review (leer no pide permiso).
+    args: ({ model, outputFilename }) => [
+      "-s",
+      ...(model ? ["--model", model] : []),
+      "--allow-tool",
+      "shell(git:*)",
+      "--allow-tool",
+      "shell(npx:*)",
+      "--allow-tool",
+      `write(${outputFilename})`,
+    ],
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI",
+    bins: ["gemini"],
+    models: [],
+    configuredModel: ({ home }) => {
+      const model = readJson(join(home, ".gemini", "settings.json"))?.model;
+      const name = typeof model === "string" ? model : model?.name;
+      return typeof name === "string" && name ? { model: name, source: "~/.gemini/settings.json" } : null;
+    },
+    // Sin TTY lee el prompt de stdin; yolo porque no hay quién apruebe los comandos.
+    args: ({ model }) => [...(model ? ["-m", model] : []), "--yolo"],
+  },
+];
+
+/** @param {string} file @param {NodeJS.Platform} platform */
+function isExecutable(file, platform) {
+  try {
+    if (!statSync(file).isFile()) return false;
+    if (platform !== "win32") accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Busca `name` en el PATH (con las extensiones de PATHEXT en Windows). */
+export function findOnPath(name, { env, platform }) {
+  const dirs = String(env.PATH || env.Path || "").split(platform === "win32" ? ";" : delimiter).filter(Boolean);
+  const exts =
+    platform === "win32"
+      ? String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+      : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, name + ext.toLowerCase());
+      if (isExecutable(candidate, platform)) return candidate;
+    }
+  }
+  return null;
+}
+
+/** @param {Partial<DetectContext>} [ctx] */
+function context(ctx = {}) {
+  return { env: ctx.env ?? process.env, platform: ctx.platform ?? process.platform, home: ctx.home ?? homedir() };
+}
+
+/**
+ * Agentes instalados, en el orden de `AGENTS`. Primero el PATH, después las rutas fijas.
+ * @param {Partial<DetectContext>} [ctx]
+ * @returns {DetectedAgent[]}
+ */
+export function detectAgents(ctx) {
+  const c = context(ctx);
+  /** @type {DetectedAgent[]} */
+  const found = [];
+  for (const def of AGENTS) {
+    let path = null;
+    for (const bin of def.bins) {
+      path = findOnPath(bin, c);
+      if (path) break;
+    }
+    if (!path) path = (def.extraPaths?.(c) ?? []).find((p) => existsSync(p) && isExecutable(p, c.platform)) ?? null;
+    if (path) found.push({ def, path });
+  }
+  return found;
+}
+
+/** Valor del select para "no pasar --model" (que el agente use el suyo). */
+export const AGENT_DEFAULT_MODEL = "";
+/** Valor del select para escribir un id de modelo a mano. */
+export const OTHER_MODEL = "__other__";
+
+/**
+ * Opciones del select de modelo: primero el default del agente (marcado como inicial), después los conocidos y
+ * "Otro…". Si el default configurado coincide con uno conocido, no se repite.
+ * @param {AgentDef} def
+ * @param {Partial<DetectContext>} [ctx]
+ * @returns {{ options: ModelOption[], initialValue: string }}
+ */
+export function modelChoices(def, ctx) {
+  const configured = def.configuredModel?.(context(ctx)) ?? null;
+  const first = configured
+    ? { value: AGENT_DEFAULT_MODEL, label: `Por defecto (${configured.model})`, hint: configured.source }
+    : { value: AGENT_DEFAULT_MODEL, label: "Por defecto del agente", hint: "no se pasa --model" };
+  const rest = def.models.filter((m) => m.value !== configured?.model);
+  return {
+    options: [first, ...rest, { value: OTHER_MODEL, label: "Otro…", hint: "escribir el id del modelo" }],
+    initialValue: AGENT_DEFAULT_MODEL,
+  };
+}
+
+/**
+ * Id de modelo que realmente se usó: el elegido, o el configurado del agente si no se pasó `--model`.
+ * @param {AgentDef} def
+ * @param {string} [model]
+ */
+export function resolvedRunModel(def, model) {
+  const chosen = String(model || "").trim();
+  if (chosen) return chosen;
+  try {
+    return def.configuredModel?.(context())?.model || "";
+  } catch {
+    return "";
+  }
+}
+
+/** Comillas para cmd.exe (solo hace falta con los shims .cmd/.bat de npm). */
+function quoteForCmd(arg) {
+  return /^[\w./:@=-]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Lanza el agente en el repo con el prompt por stdin; stdout/stderr van a la terminal.
+ * @param {DetectedAgent} agent
+ * @param {{ cwd: string, prompt: string } & RunSpec} spec
+ * @returns {{ child: import('node:child_process').ChildProcess, exited: Promise<number> }}
+ */
+export function runAgent(agent, { cwd, prompt, model, outputFilename }) {
+  const args = agent.def.args({ model, outputFilename });
+  // Node no lanza .cmd/.bat sin shell (CVE-2024-27980); con shell hay que citar a mano.
+  const viaShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(agent.path);
+  const child = viaShell
+    ? spawn([agent.path, ...args].map(quoteForCmd).join(" "), { cwd, shell: true, stdio: ["pipe", "inherit", "inherit"] })
+    : spawn(agent.path, args, { cwd, stdio: ["pipe", "inherit", "inherit"] });
+  // Si el agente sale antes de leer stdin (p. ej. un modelo inválido), el EPIPE no debe tirar abajo la CLI.
+  child.stdin?.on("error", () => {});
+  child.stdin?.end(prompt);
+  const exited = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve(signal ? 1 : (code ?? 1)));
+  });
+  return { child, exited };
+}

package/lib/agents.test.mjs

@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import {
+  AGENT_DEFAULT_MODEL,
+  AGENTS,
+  detectAgents,
+  findOnPath,
+  modelChoices,
+  OTHER_MODEL,
+  topLevelTomlModel,
+} from "./agents.mjs";
+
+const claude = AGENTS.find((a) => a.id === "claude");
+const codex = AGENTS.find((a) => a.id === "codex");
+const cursor = AGENTS.find((a) => a.id === "cursor");
+const copilot = AGENTS.find((a) => a.id === "copilot");
+
+function sandbox() {
+  return mkdtempSync(join(tmpdir(), "diff-review-agents-"));
+}
+
+function touch(file, content = "") {
+  mkdirSync(join(file, ".."), { recursive: true });
+  writeFileSync(file, content, { mode: 0o755 });
+  return file;
+}
+
+describe("findOnPath", () => {
+  it("en Windows prueba las extensiones de PATHEXT (shims .cmd de npm)", () => {
+    const root = sandbox();
+    const bin = join(root, "npm");
+    touch(join(bin, "codex.cmd"));
+    const found = findOnPath("codex", {
+      env: { PATH: `${join(root, "nada")};${bin}`, PATHEXT: ".EXE;.CMD" },
+      platform: "win32",
+    });
+    assert.equal(found, join(bin, "codex.cmd"));
+  });
+
+  it("devuelve null si no está", () => {
+    assert.equal(findOnPath("codex", { env: { PATH: sandbox() }, platform: "linux" }), null);
+  });
+});
+
+describe("detectAgents", () => {
+  it("encuentra el Claude Code de la app de escritorio de Windows, en su versión más nueva", () => {
+    const home = sandbox();
+    const appData = join(home, "AppData", "Roaming");
+    const root = join(appData, "Claude", "claude-code");
+    touch(join(root, "2.1.9", "aaa", "claude.exe"));
+    const newest = touch(join(root, "2.1.286", "bbb", "claude.exe"));
+    const found = detectAgents({ env: { PATH: "", APPDATA: appData }, platform: "win32", home });
+    assert.deepEqual(
+      found.map((a) => [a.def.id, a.path]),
+      [["claude", newest]]
+    );
+  });
+
+  it("el PATH gana sobre las rutas fijas", () => {
+    const home = sandbox();
+    const appData = join(home, "AppData", "Roaming");
+    touch(join(appData, "Claude", "claude-code", "2.1.286", "bbb", "claude.exe"));
+    const onPath = touch(join(home, "bin", "claude.exe"));
+    const found = detectAgents({
+      env: { PATH: join(home, "bin"), PATHEXT: ".EXE", APPDATA: appData },
+      platform: "win32",
+      home,
+    });
+    assert.equal(found[0].path, onPath);
+  });
+
+  it("sin nada instalado devuelve vacío", () => {
+    assert.deepEqual(detectAgents({ env: { PATH: "" }, platform: "linux", home: sandbox() }), []);
+  });
+});
+
+describe("modelChoices", () => {
+  it("sin modelo configurado: 'Por defecto del agente' primero y como inicial, y 'Otro…' al final", () => {
+    const { options, initialValue } = modelChoices(claude, { env: {}, platform: "linux", home: sandbox() });
+    assert.equal(initialValue, AGENT_DEFAULT_MODEL);
+    assert.equal(options[0].value, AGENT_DEFAULT_MODEL);
+    assert.equal(options[0].label, "Por defecto del agente");
+    assert.deepEqual(
+      options.slice(1, -1).map((o) => o.value),
+      ["opus", "sonnet", "haiku"]
+    );
+    assert.equal(options.at(-1).value, OTHER_MODEL);
+  });
+
+  it("muestra el modelo configurado en ~/.claude/settings.json y no lo repite en la lista", () => {
+    const home = sandbox();
+    touch(join(home, ".claude", "settings.json"), JSON.stringify({ model: "sonnet" }));
+    const { options } = modelChoices(claude, { env: {}, platform: "linux", home });
+    assert.equal(options[0].label, "Por defecto (sonnet)");
+    assert.equal(options[0].hint, "~/.claude/settings.json");
+    assert.ok(!options.slice(1).some((o) => o.value === "sonnet"));
+  });
+
+  it("ANTHROPIC_MODEL pisa a settings.json", () => {
+    const { options } = modelChoices(claude, {
+      env: { ANTHROPIC_MODEL: "opus" },
+      platform: "linux",
+      home: sandbox(),
+    });
+    assert.equal(options[0].label, "Por defecto (opus)");
+  });
+
+  it("codex lee el model de nivel raíz de ~/.codex/config.toml", () => {
+    const home = sandbox();
+    touch(join(home, ".codex", "config.toml"), 'model = "gpt-x"\n[profiles.otro]\nmodel = "nope"\n');
+    const { options } = modelChoices(codex, { env: {}, platform: "linux", home });
+    assert.equal(options[0].label, "Por defecto (gpt-x)");
+  });
+});
+
+describe("topLevelTomlModel", () => {
+  it("ignora los model dentro de secciones", () => {
+    assert.equal(topLevelTomlModel('[profiles.a]\nmodel = "x"\n'), null);
+    assert.equal(topLevelTomlModel('approval = "never"\nmodel = \'y\'\n'), "y");
+  });
+});
+
+describe("args", () => {
+  it("claude: -p, --model solo si se eligió uno, y escritura limitada al JSON del review", () => {
+    const args = claude.args({ model: "opus", outputFilename: "diff-rev_a_b.json" });
+    assert.deepEqual(args.slice(0, 3), ["-p", "--model", "opus"]);
+    assert.ok(args.includes("Edit(./diff-rev_a_b.json)"));
+    assert.ok(!claude.args({ outputFilename: "x.json" }).includes("--model"));
+  });
+
+  it("codex: lee el prompt de stdin", () => {
+    assert.equal(codex.args({ outputFilename: "x.json" }).at(-1), "-");
+  });
+});
+
+describe("cursor", () => {
+  it("encuentra cursor-agent.cmd en %LOCALAPPDATA% aunque no esté en el PATH", () => {
+    const home = sandbox();
+    const localAppData = join(home, "AppData", "Local");
+    const shim = touch(join(localAppData, "cursor-agent", "cursor-agent.cmd"));
+    const found = detectAgents({ env: { PATH: "", LOCALAPPDATA: localAppData }, platform: "win32", home });
+    assert.deepEqual(
+      found.map((a) => [a.def.id, a.path]),
+      [["cursor", shim]]
+    );
+  });
+
+  it("no toma el alias genérico `agent` del PATH", () => {
+    const home = sandbox();
+    touch(join(home, "bin", "agent"));
+    assert.deepEqual(detectAgents({ env: { PATH: join(home, "bin") }, platform: "linux", home }), []);
+  });
+
+  it("lee el modelo de ~/.cursor/cli-config.json y muestra Auto como `auto`", () => {
+    const home = sandbox();
+    const file = join(home, ".cursor", "cli-config.json");
+    touch(file, JSON.stringify({ selectedModel: { modelId: "default" } }));
+    assert.equal(modelChoices(cursor, { env: {}, platform: "linux", home }).options[0].label, "Por defecto (auto)");
+    touch(file, JSON.stringify({ selectedModel: { modelId: "gpt-5" } }));
+    assert.equal(modelChoices(cursor, { env: {}, platform: "linux", home }).options[0].label, "Por defecto (gpt-5)");
+  });
+
+  it("args: print mode con --force y --model solo si se eligió uno", () => {
+    const args = cursor.args({ model: "sonnet-4", outputFilename: "x.json" });
+    assert.equal(args[0], "-p");
+    assert.ok(args.includes("--force") && args.includes("--trust"));
+    assert.deepEqual(args.slice(-2), ["--model", "sonnet-4"]);
+    assert.ok(!cursor.args({ outputFilename: "x.json" }).includes("--model"));
+  });
+});
+
+describe("copilot", () => {
+  it("lee el modelo de ~/.copilot/settings.json, o de $COPILOT_HOME", () => {
+    const home = sandbox();
+    touch(join(home, ".copilot", "settings.json"), JSON.stringify({ model: "gpt-5.4" }));
+    assert.equal(modelChoices(copilot, { env: {}, platform: "linux", home }).options[0].label, "Por defecto (gpt-5.4)");
+
+    const custom = sandbox();
+    touch(join(custom, "settings.json"), JSON.stringify({ model: "claude-haiku-4.5" }));
+    const { options } = modelChoices(copilot, { env: { COPILOT_HOME: custom }, platform: "linux", home });
+    assert.equal(options[0].label, "Por defecto (claude-haiku-4.5)");
+    assert.equal(options[0].hint, "$COPILOT_HOME/settings.json");
+  });
+
+  it("args: prompt por stdin (sin -p) y escritura limitada al JSON del review", () => {
+    const args = copilot.args({ model: "auto", outputFilename: "diff-rev_a_b.json" });
+    assert.ok(!args.includes("-p"));
+    assert.deepEqual(args.slice(0, 3), ["-s", "--model", "auto"]);
+    assert.ok(args.includes("write(diff-rev_a_b.json)"));
+    assert.ok(!args.includes("--allow-all-tools"));
+  });
+});

package/lib/check-report.mjs

@@ -159,7 +159,8 @@ export function formatCheckReport(file, command, result) {
     "How to continue:",
     "- Fix every problem above in place. Keep existing meta/intent/groups/blocks/findings; only change what is wrong or missing.",
     '- Every diff path must appear in "blocks" or "skipped" (a skipped glob counts).',
-    "- what/why/fix stay ≤120 chars; intent ≥40 chars; enums exactly as in the schema.",
+    "- meta.agent and meta.model are required (product name and the exact model id you are running).",
+    "- intent ≥40 chars; enums exactly as in the schema.",
     "- Human-readable strings in Spanish.",
     `- Re-run exactly: \`${command}\``,
     "- Stop only when that command prints OK."

package/lib/check-report.test.mjs

@@ -3,6 +3,7 @@ import { test } from "node:test";
 import { checkPayload, formatCheckReport } from "./check-report.mjs";
 
 const valid = () => ({
+  meta: { agent: "Cursor", model: "composer" },
   intent: "Agrega el ABM de depósitos locales end-to-end para dejar de administrarlos por SQL.",
   groups: [{ id: "g1", kind: "feat", title: "CRUD de depósitos", intent: "base de todo" }],
   blocks: [

package/lib/fingerprint.mjs

@@ -0,0 +1,24 @@
+/**
+ * Tips cortos de SHA. Sin APIs de Node: la UI lo importa para armar el nombre del JSON.
+ */
+
+export function shortSha(sha, n = 10) {
+  const hex = String(sha || "")
+    .toLowerCase()
+    .replace(/[^a-f0-9]/g, "");
+  return hex.length >= 7 ? hex.slice(0, n) : "";
+}
+
+export function fingerprint(branchSha, baseSha) {
+  const a = shortSha(branchSha);
+  const b = shortSha(baseSha);
+  if (!a || !b) return null;
+  return `${a}-${b}`;
+}
+
+/** File/URL id: short tip of the reviewed branch + short tip of the base. */
+export function reportId(branchSha, baseSha) {
+  const id = fingerprint(branchSha, baseSha);
+  if (!id) throw new Error("Faltan SHAs de los tips para el id del reporte.");
+  return id;
+}

package/lib/git.mjs

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+export { fingerprint, reportId } from "./fingerprint.mjs";
+
 export function assertGitRepo(repo) {
   const raw = String(repo || "").trim();
   if (!raw) {
@@ -74,25 +76,6 @@ export function branchTips(repo, branch, base) {
   };
 }
 
-export function fingerprint(branchSha, baseSha) {
-  const a = shortSha(branchSha);
-  const b = shortSha(baseSha);
-  if (!a || !b) return null;
-  return `${a}-${b}`;
-}
-
-/** File/URL id: short tip of the reviewed branch + short tip of the base. */
-export function reportId(branchSha, baseSha) {
-  const id = fingerprint(branchSha, baseSha);
-  if (!id) throw new Error("Faltan SHAs de los tips para el id del reporte.");
-  return id;
-}
-
-function shortSha(sha, n = 10) {
-  const hex = String(sha || "").toLowerCase().replace(/[^a-f0-9]/g, "");
-  return hex.length >= 7 ? hex.slice(0, n) : "";
-}
-
 export function commitLog(repo, mergeBase, branch, limit = 25) {
   try {
     return git(repo, [

package/lib/output-name.mjs

@@ -2,7 +2,7 @@
  * Nombre del JSON que escribe el agente.
  * Preferido: tips cortos branch/base. Legacy (con stamp o sin tips) sigue válido al importar.
  */
-import { fingerprint } from "./git.mjs";
+import { fingerprint } from "./fingerprint.mjs";
 
 /** Prefijo del formato actual. */
 export const OUTPUT_PREFIX = "diff-rev";