@dforce2055/dai 0.13.3 → 0.15.0

package/cli/lib/notify.mjs

@@ -0,0 +1,205 @@
+// dai · aviso de release a un canal de equipo (opcional, opt-in, default apagado).
+//
+// Tercer adaptador del CLI, con la misma anatomía que los dos que ya existen: una variable
+// que elige el backend (DAI_NOTIFY, como DAI_PM) y las variables propias de ese backend.
+//
+// El mensaje es UNO SOLO para todos los canales: con ESTRUCTURA (qué salió, quién, cuándo,
+// qué trae, dónde mirar) pero SIN FORMATO. Esa distinción es la que hace que esto sea una
+// tabla y no un módulo de render:
+//
+//   · la estructura son saltos de línea y viñetas, y se ve igual en los cinco canales,
+//   · el formato son cuatro dialectos incompatibles (Discord **negrita** sin links con
+//     nombre, Slack *negrita* con <url|texto>, Webex markdown completo, Telegram con su
+//     parse_mode y el escapeo de MarkdownV2 que devuelve 400 por un punto suelto),
+//   · una URL pelada se vuelve clickeable sola en los cuatro,
+//   · y lo único que queda distinto entre proveedores es EN QUÉ CAMPO del JSON va el string.
+//
+// Las viñetas se cortan en MAX_BULLETS, así que el mensaje no se acerca al límite de
+// ningún canal (el más chico es Discord, 2000) y no hay nada que recortar a mano.
+//
+// El detalle del release vive en el ticket (dai release stamp) y en el release note. El
+// canal avisa y linkea: un chat no es un registro, a los dos días nadie lo encuentra.
+//
+// Lo que esto NO es: un framework de notificaciones. dai avisa eventos de release con su
+// manifiesto. Mandar mensajes arbitrarios a un canal no es dai.
+
+import { daiFetch } from "./http.mjs";
+
+// El envelope de cada canal. Esto es el adaptador entero.
+const CANALES = {
+  discord:  (msg) => ({ content: msg }),
+  slack:    (msg) => ({ text: msg }),
+  webex:    (msg) => ({ markdown: msg }),
+  telegram: (msg, cfg) => ({ chat_id: cfg.chatId, text: msg }),
+  // Genérico: los campos estructurados MÁS el texto ya armado. Una integración propia usa
+  // los campos; cualquier endpoint estilo Slack (Mattermost, Rocket.Chat, un webhook de
+  // Teams) levanta el `text` sin configurar nada. No cuesta una línea más soportar los dos.
+  webhook:  (msg, cfg, ev) => ({ ...eventFields(ev), text: msg }),
+};
+
+export const CANALES_VALIDOS = Object.keys(CANALES);
+
+// ── Config ───────────────────────────────────────────────────────────────────
+// Devuelve null cuando el repo no declaró canal: no avisar es el default, y un default
+// que habla hacia afuera sería una sorpresa desagradable.
+export function notifyConfig(env = {}) {
+  const channel = String(env.DAI_NOTIFY ?? "").trim().toLowerCase();
+  if (channel === "" || channel === "none") return null;
+  if (!CANALES[channel]) {
+    throw new Error(
+      `DAI_NOTIFY='${channel}' no es un canal que dai conozca (${CANALES_VALIDOS.join(" | ")} | none).\n` +
+      `  Para un destino propio —Teams, Mattermost, un sistema interno— usá 'webhook':\n` +
+      `  manda los campos del release en JSON y tu endpoint hace lo que quiera con ellos.`,
+    );
+  }
+  const endpoint = String(env.DAI_NOTIFY_WEBHOOK ?? "").trim();
+  if (!endpoint) {
+    throw new Error(
+      `DAI_NOTIFY=${channel} pero falta DAI_NOTIFY_WEBHOOK en el .env.dai (el endpoint del canal).\n` +
+      `  Ese endpoint ES la credencial: quien lo tiene, postea. Nunca lo commitees.`,
+    );
+  }
+  const chatId = String(env.DAI_NOTIFY_CHAT_ID ?? "").trim();
+  // Telegram es el raro de los cuatro: no tiene webhooks de entrada. Es token de bot +
+  // chat_id, y el token vale para el bot entero, no para un canal — por eso hace falta
+  // decir a qué chat. Si falta, el POST sale igual y la API contesta un 400 que no lo explica.
+  if (channel === "telegram" && !chatId) {
+    throw new Error(
+      "DAI_NOTIFY=telegram necesita además DAI_NOTIFY_CHAT_ID (a qué chat postear).\n" +
+      "  Telegram no usa webhooks de entrada: el endpoint es el bot y el chat_id el destino.",
+    );
+  }
+  return { channel, endpoint, chatId: chatId || null };
+}
+
+// Qué se le muestra al usuario como destino. NUNCA la URL entera: el endpoint es la
+// credencial, y un webhook filtrado en una captura de pantalla es un canal comprometido.
+export function describeTarget(cfg) {
+  if (!cfg) return "sin canal (DAI_NOTIFY no declarado)";
+  let host = "(endpoint ilegible)";
+  try { host = new URL(cfg.endpoint).host; } catch { /* URL rara: no la mostramos igual */ }
+  return `${cfg.channel} · ${host}${cfg.chatId ? ` · chat ${cfg.chatId}` : ""}`;
+}
+
+// ── El mensaje ───────────────────────────────────────────────────────────────
+// Un evento de release: qué app, qué versión, a dónde fue, y qué US lleva adentro.
+//   event: "released"  → se publicó la versión (dai release done)
+//   event: "deployed"  → esa versión llegó a un ambiente (dai release stamp --env X)
+//   event: "test"      → prueba de canal (dai release notify --test)
+function eventFields(ev = {}) {
+  return {
+    event: `release.${ev.event || "released"}`,
+    app: ev.app ?? null,
+    version: ev.version ?? null,
+    environment: ev.environment ?? null,
+    url: ev.url ?? null,
+    stories: (Array.isArray(ev.stories) ? ev.stories : []).map((s) => (typeof s === "string" ? { id: s, title: null } : { id: s.id, title: s.title ?? null })),
+  };
+}
+
+// El texto, uno solo para todos los canales. Con ESTRUCTURA (qué salió, quién, cuándo,
+// qué trae, dónde mirar) pero SIN FORMATO: ni negritas ni links con nombre.
+//
+// La diferencia no es estética, es de costo. La estructura son saltos de línea y viñetas,
+// que se ven igual en los cinco canales. El formato son cuatro dialectos incompatibles:
+// Discord usa **negrita** y no soporta links con nombre; Slack usa *negrita* de un
+// asterisco y <url|texto>; Webex quiere markdown completo; Telegram exige parse_mode y
+// escapar media docena de caracteres o devuelve 400. Una URL pelada, en cambio, se vuelve
+// clickeable sola en los cuatro.
+//
+//   🎉 Nuevo release · backend v1.2.0
+//   Autor: Ada Lovelace · Fecha: 09/09/2026 08:12 · Ambiente: PRODUCCIÓN
+//
+//   Cambios principales:
+//    • ACME-482  Checkout sin duplicado
+//    • ACME-491  Alta de póliza sin duplicar cliente
+//
+//   Ver release: https://…/releases/v1.2.0
+//
+// Las viñetas salen de las US del manifiesto, no de los subjects de los commits: lo que
+// el equipo quiere leer es qué valor salió, no qué archivos se tocaron. Es la misma
+// diferencia entre el QUÉ y el CÓMO que sostiene todo el método.
+const MAX_BULLETS = 8;
+
+const dosDigitos = (n) => String(n).padStart(2, "0");
+export function formatFecha(d = new Date()) {
+  return `${dosDigitos(d.getDate())}/${dosDigitos(d.getMonth() + 1)}/${d.getFullYear()} ` +
+         `${dosDigitos(d.getHours())}:${dosDigitos(d.getMinutes())}`;
+}
+
+export function renderNotice(ev = {}) {
+  if (ev.event === "test") {
+    return "✅ Prueba de canal · dai\nSi ves esto, el canal está bien configurado.";
+  }
+  const app = ev.app ? `${ev.app} ` : "";
+  const version = ev.version ? `v${String(ev.version).replace(/^v/, "")}` : "(sin versión)";
+  const L = [];
+  L.push(ev.environment
+    ? `🚀 Release desplegada · ${app}${version} → ${String(ev.environment).toUpperCase()}`
+    : `🎉 Nuevo release · ${app}${version}`);
+
+  // Segunda línea: quién y cuándo. Sale de git y del reloj — nada que configurar.
+  const meta = [];
+  if (ev.author) meta.push(`Autor: ${ev.author}`);
+  meta.push(`Fecha: ${ev.date || formatFecha()}`);
+  L.push(meta.join(" · "));
+
+  const stories = Array.isArray(ev.stories) ? ev.stories : [];
+  if (stories.length) {
+    L.push("");
+    L.push("Cambios principales:");
+    for (const s of stories.slice(0, MAX_BULLETS)) {
+      const id = typeof s === "string" ? s : s.id;
+      const title = typeof s === "string" ? null : s.title;
+      L.push(` • ${id}${title ? `  ${title}` : ""}`);
+    }
+    if (stories.length > MAX_BULLETS) L.push(` • …y ${stories.length - MAX_BULLETS} más`);
+  }
+  if (ev.url) { L.push(""); L.push(`Ver release: ${ev.url}`); }
+  return L.join("\n");
+}
+
+// El cuerpo que se le manda al canal.
+export function payloadFor(cfg, ev) {
+  const envelope = CANALES[cfg.channel];
+  if (!envelope) throw new Error(`canal desconocido: ${cfg.channel}`);
+  return envelope(renderNotice(ev), cfg, ev);
+}
+
+// ── Efecto de red ────────────────────────────────────────────────────────────
+// Un aviso que no sale NO puede voltear una release: para cuando esto corre, el tag ya
+// existe y las US ya están estampadas. Por eso devuelve el error en vez de tirarlo —
+// quien llama lo reporta como advertencia y sigue.
+export async function sendNotice(cfg, ev) {
+  try {
+    const res = await daiFetch(cfg.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payloadFor(cfg, ev)),
+    });
+    if (!res.ok) {
+      const body = (await res.text().catch(() => "")).slice(0, 300);
+      return { ok: false, status: res.status, error: explainNotifyError(cfg, res.status, body) };
+    }
+    return { ok: true, status: res.status, error: null };
+  } catch (e) {
+    // El mensaje de daiFetch ya explica el caso de TLS corporativo; acá solo se le pone
+    // alrededor qué se estaba haciendo, sin filtrar el endpoint.
+    return { ok: false, status: null, error: `no pude avisar a ${describeTarget(cfg)}: ${String(e.message).split("\n")[0]}` };
+  }
+}
+
+export function explainNotifyError(cfg, status, body = "") {
+  const donde = describeTarget(cfg);
+  if (status === 401 || status === 403) {
+    return `${donde} rechazó el aviso (${status}): el endpoint existe pero no autoriza.\n` +
+           "  Revisá DAI_NOTIFY_WEBHOOK en el .env.dai — puede estar revocado o ser de otro espacio.";
+  }
+  if (status === 404) {
+    return `${donde} no existe (404). El webhook fue borrado, o la URL está mal copiada.`;
+  }
+  if (status === 429) {
+    return `${donde} te frenó por rate limit (429). El aviso no salió; el release sí está hecho.`;
+  }
+  return `${donde} respondió ${status}.${body ? `\n  ${body}` : ""}`;
+}

package/cli/lib/pm-adapter.mjs

@@ -9,6 +9,8 @@
 // Interfaz (fetchUS/stamp pueden ser sync o async — el CLI siempre await-ea):
 //   fetchUS(id)          → { id, title, spec_version, ac_hash, url, raw } | null
 //   stamp(id, record)    → destino donde quedó la cobertura
+//   comment(id, markdown)→ comentario libre en la US    (lo usa `dai release stamp`)
+//   listComments(id)     → [texto]  para reconocer los comentarios que dai ya puso
 //   createUS({...})      → { id, url }            (opcional: `dai publish`)
 //   updateUS(id, {...})  → { id, url }            (opcional: `dai update-us`)
 //   kind                 → nombre del backend
@@ -57,6 +59,20 @@ function mdAdapter(env) {
       const raw = readFileSync(p, "utf8");
       return { id, ...parseUS(raw), raw };
     },
+    // Sin tracker, un "comentario" es una línea más en el registro de despliegues de esa US.
+    // Se APÉNDEA (no se pisa): el archivo es la bitácora, y una bitácora que se sobrescribe
+    // no es una bitácora.
+    comment(id, markdown) {
+      const p = join(dir, `${id}.deploys.md`);
+      mkdirSync(dirname(p), { recursive: true });
+      const previo = existsSync(p) ? readFileSync(p, "utf8") : `# Despliegues de ${id}\n`;
+      writeFileSync(p, `${previo.replace(/\s*$/, "")}\n\n${markdown}\n`);
+      return p;
+    },
+    listComments(id) {
+      const p = join(dir, `${id}.deploys.md`);
+      return existsSync(p) ? [readFileSync(p, "utf8")] : [];
+    },
     stamp(id, record) {
       const p = join(dir, `${id}.coverage.md`);
       mkdirSync(dirname(p), { recursive: true });

package/cli/lib/pm-clickup.mjs

@@ -35,6 +35,23 @@ export function clickupAdapter(env) {
       // `url` es la canónica (/t/<team_id>/<id>): la sabe ClickUp, no la deducimos.
       return { id, ...parseUS(raw), url: j.url || null, raw };
     },
+    // Comentario libre (lo usa `dai release stamp`). ClickUp toma texto directamente.
+    async comment(id, markdown) {
+      const res = await fetch(clickupCommentUrl(id), {
+        method: "POST", headers: clickupAuthHeaders(env),
+        body: JSON.stringify({ comment_text: markdown }),
+      });
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      return `task ${id} (comentario)`;
+    },
+    // Los comentarios como texto, para reconocer los que dai ya puso por su marca.
+    async listComments(id) {
+      const res = await fetch(clickupCommentUrl(id), { headers: clickupAuthHeaders(env) });
+      if (res.status === 404) return [];
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return (j.comments || []).map((c) => c.comment_text || c.text_content || "");
+    },
     async stamp(id, record) {
       const res = await fetch(clickupCommentUrl(id), {
         method: "POST", headers: clickupAuthHeaders(env),

package/cli/lib/pm-jira.mjs

@@ -147,6 +147,26 @@ export function jiraAdapter(env) {
       const raw = jiraIssueToText(await res.json());
       return { id, ...parseUS(raw), url: `${trim(base)}/browse/${id}`, raw };
     },
+    // Comentario libre en markdown (lo usa `dai release stamp`). Jira Cloud pide ADF, así
+    // que se convierte con el mismo parser que ya usa la descripción de la US.
+    async comment(id, markdown) {
+      const res = await daiFetch(jiraCommentUrl(base, id), {
+        method: "POST", headers: jiraAuthHeaders(env),
+        body: JSON.stringify({ body: markdownToAdf(markdown) }),
+      });
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      return `${trim(base)}/browse/${id}`;
+    },
+    // Los comentarios como texto plano, para que dai reconozca los suyos por la marca y no
+    // vuelva a estampar lo mismo. Los más nuevos primero: la marca que buscamos, si está,
+    // es reciente. 100 alcanza de sobra y evita paginar un ticket con años de historia.
+    async listComments(id) {
+      const res = await daiFetch(`${jiraCommentUrl(base, id)}?maxResults=100&orderBy=-created`, { headers: jiraAuthHeaders(env) });
+      if (res.status === 404) return [];
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return (j.comments || []).map((c) => (typeof c.body === "string" ? c.body : adfToMarkdown(c.body)));
+    },
     async stamp(id, record) {
       const res = await daiFetch(jiraCommentUrl(base, id), {
         method: "POST", headers: jiraAuthHeaders(env),

package/cli/lib/pr-remote.mjs

@@ -0,0 +1,94 @@
+// dai · la PR/MR que YA existe para esta branch: cómo buscarla, cómo actualizarla (issue #46).
+//
+// El bug: con una MR ya abierta, `dai pr` pusheaba la branch (el diff quedaba al día) y
+// después `glab mr create` fallaba porque la MR existía. El body NO se actualizaba y lo
+// único que se veía era el comando crudo del forge, sin un error legible. Resultado: una
+// MR con el diff correcto y una descripción que MIENTE sobre lo que contiene — el peor de
+// los dos mundos, porque parece que salió bien.
+//
+// Acá está la parte pura y testeable: armar los comandos del forge y leer lo que devuelven.
+// Los efectos (execFileSync) viven en dai.mjs.
+
+// ── Buscar la PR/MR abierta de una branch ────────────────────────────────────
+export function listPrCmd(tool, branch) {
+  if (tool === "gh") {
+    return ["pr", "list", "--head", branch, "--state", "open", "--limit", "5",
+            "--json", "number,url,title,baseRefName"];
+  }
+  return ["mr", "list", "--source-branch", branch, "--per-page", "5", "--output", "json"];
+}
+
+// Normaliza la respuesta de gh/glab a la MISMA forma: { number, url, title, base }.
+// Devuelve null si no hay ninguna abierta. Tira si el JSON no parsea — quien llama decide
+// si eso es fatal (no lo es: se sigue por el camino de crear, que también sabe fallar bien).
+export function parsePrList(tool, stdout) {
+  const raw = String(stdout ?? "").trim();
+  if (!raw) return null;
+  const arr = JSON.parse(raw);
+  const list = Array.isArray(arr) ? arr : Array.isArray(arr?.items) ? arr.items : [];
+  for (const it of list) {
+    // glab devuelve TODAS las MR de la branch si no se filtra por estado: las cerradas y
+    // mergeadas no cuentan — reabrir una MR mergeada no es lo que pidió nadie.
+    const state = String(it.state ?? "opened").toLowerCase();
+    if (!["open", "opened"].includes(state)) continue;
+    const number = it.number ?? it.iid ?? null;
+    if (number == null) continue;
+    return {
+      number: Number(number),
+      url: it.url ?? it.web_url ?? null,
+      title: it.title ?? null,
+      base: it.baseRefName ?? it.target_branch ?? null,
+    };
+  }
+  return null;
+}
+
+// ── Actualizar el body/título de una PR/MR existente ─────────────────────────
+// gh lee el body de un archivo; glab lo toma como string (igual que en `mr create`, que
+// ya funciona así). Por eso la firma pide los dos y cada uno usa el que le sirve.
+export function updatePrCmd(tool, { number, title, body, bodyFile }) {
+  if (tool === "gh") {
+    return ["pr", "edit", String(number), "--title", title, "--body-file", bodyFile];
+  }
+  return ["mr", "update", String(number), "--title", title, "--description", body, "--yes"];
+}
+
+// Plan B para actualizar, cuando el comando de alto nivel falla por algo que no tiene que
+// ver con la edición. Pasa de verdad: `gh pr edit` consulta GraphQL y arrastra campos
+// deprecados del servidor —hoy, `projectCards` de Projects (classic)— así que devuelve un
+// error sobre proyectos cuando lo único que querías era cambiar el body. La API REST no
+// pasa por ahí, y `gh api` usa la misma autenticación: no hace falta un token nuevo.
+//
+// Devuelve null si no sabemos hacer el plan B para esa herramienta (glab actualiza por REST
+// de entrada, así que no lo necesita).
+export function updatePrApiCmd(tool, { number, title, bodyFile, projectPath }) {
+  if (tool !== "gh" || !projectPath) return null;
+  return ["api", "--method", "PATCH", `repos/${projectPath}/pulls/${number}`,
+          "-F", `body=@${bodyFile}`, "-f", `title=${title}`];
+}
+
+// ── "ya existe una PR para esta branch" ──────────────────────────────────────
+// El forge lo dice de formas distintas y en inglés. Se reconoce para poder pasar al camino
+// de actualizar en vez de morir con el comando crudo en pantalla.
+const ALREADY = [
+  /already exists/i,
+  /a merge request already exists/i,
+  /existing (?:pull request|merge request)/i,
+  /pull request for branch .* already exists/i,
+  /open merge request already exists/i,
+];
+export function isAlreadyExistsError(msg) {
+  const s = String(msg ?? "");
+  return ALREADY.some((re) => re.test(s));
+}
+
+// Lo que se le muestra al dev cuando dai detecta la PR existente: qué va a pasar con ella.
+export function describeUpdate(pr, { base, tool }) {
+  const lines = [`ya hay una PR/MR abierta para esta branch: #${pr.number}${pr.url ? ` — ${pr.url}` : ""}`];
+  if (pr.base && base && pr.base !== base) {
+    lines.push(`ojo: apunta a '${pr.base}' y vos pediste '${base}'. dai NO cambia la base de una PR abierta: ` +
+               `si querés otra base, cerrala y creá una nueva.`);
+  }
+  lines.push(`dai va a ACTUALIZAR su título y su descripción con ${tool} (el diff ya lo actualiza el push).`);
+  return lines;
+}

package/cli/lib/release-files.mjs

@@ -0,0 +1,119 @@
+// dai · los archivos que toca cortar una versión: dónde vive el número y qué se escribe
+// en el CHANGELOG. Parte pura; los efectos (escribir, commitear, taguear) viven en dai.mjs.
+//
+// Premisa que vale para todo el módulo: **el tag es la fuente de verdad de la versión; los
+// archivos son espejos opcionales.** Un repo Node tiene package.json, dai tiene además un
+// VERSION, y un repo .NET o un frontend corporativo puede no tener ninguno de los dos y
+// versionar igual. Por eso dai actualiza los espejos que RECONOCE, dice cuáles tocó, y no
+// se planta si no encuentra ninguno.
+
+// ── El número, en los archivos que lo espejan ────────────────────────────────
+
+// package.json: se cambia SOLO la línea de la versión.
+//
+// Reserializar el JSON (`JSON.stringify(pkg, null, 2)`) parece más limpio y es peor: te
+// reformatea los objetos compactos (`"repository": { ... }` en una línea) a multi-línea y
+// ensucia el diff de la release con ruido que nadie pidió. El diff de un `chore(release)`
+// tiene que ser tres líneas.
+export function bumpPackageJson(text, version) {
+  const re = /("version"\s*:\s*")([^"]*)(")/;
+  const m = String(text ?? "").match(re);
+  if (!m) return { text, changed: false, from: null };
+  if (m[2] === version) return { text, changed: false, from: m[2] };
+  return { text: text.replace(re, `$1${version}$3`), changed: true, from: m[2] };
+}
+
+// VERSION: el archivo entero es el número. Sin salto final, como lo escribe dai.
+export function bumpVersionFile(text, version) {
+  const from = String(text ?? "").trim().split("\n")[0] || null;
+  if (from === version) return { text, changed: false, from };
+  return { text: version, changed: true, from };
+}
+
+// ── CHANGELOG ────────────────────────────────────────────────────────────────
+// Keep a Changelog. dai escribe el ANDAMIO y el material; la prosa la escribe una persona
+// (o la skill), y esa división no es pereza: dai sabe QUÉ entró, no POR QUÉ importa. Un
+// changelog autogenerado desde los commits es una lista que nadie lee — el de este repo se
+// lee justamente porque cada entrada cuenta qué estaba mal.
+//
+// El material va en un comentario HTML: se ve al editar y desaparece al renderizar, así
+// que si alguien no lo reparte, el archivo publicado no queda con andamio a la vista.
+export const CHANGELOG_MARK = "<!-- dai:manifiesto";
+
+export function changelogEntry({ version, date, manifest = {}, secciones = ["Agregado", "Cambiado", "Corregido", "Interno"] }) {
+  const L = [`## [${version}] — ${date}`, ""];
+  L.push(`${CHANGELOG_MARK} · el material de esta versión. Repartilo abajo y contá el porqué:`);
+  L.push(`     dai sabe qué entró; por qué importa lo sabés vos.`);
+  for (const s of manifest.stories || []) {
+    L.push(`     ${s.id}${s.title ? `  ${s.title}` : ""}${s.status === "atrasado" ? "   ⚠️ ATRASADA" : ""}`);
+  }
+  for (const b of manifest.chores || []) L.push(`     (sin US) ${b}`);
+  for (const b of manifest.orphans || []) L.push(`     (sin US, sin prefijo exento) ${b}`);
+  if (!(manifest.stories || []).length && !(manifest.chores || []).length && !(manifest.orphans || []).length) {
+    L.push(`     (el manifiesto no encontró US ni branches en el rango)`);
+  }
+  L.push(`-->`);
+  L.push("");
+  for (const s of secciones) { L.push(`### ${s}`); L.push(""); }
+  return L.join("\n");
+}
+
+// ¿La entrada quedó con el andamio sin repartir? Mismo espíritu que `bodyGaps` en `dai pr`:
+// publicar el molde es peor que no publicar nada, porque parece que alguien lo escribió.
+// Acá es un AVISO, no un bloqueo: cortar la versión no debe frenarse por la redacción.
+export function changelogGaps(entry) {
+  const gaps = [];
+  const cuerpo = String(entry ?? "").replace(/<!--[\s\S]*?-->/g, "");
+  if (String(entry ?? "").includes(CHANGELOG_MARK)) gaps.push("el manifiesto de dai sigue sin repartir");
+  const conTexto = cuerpo.split("\n").some((l) => /^\s*[-*]\s+\S/.test(l));
+  if (!conTexto) gaps.push("no hay ni un ítem en las secciones");
+  return gaps;
+}
+
+// Inserta la entrada arriba de la primera que ya exista, y agrega el link al pie.
+// Idempotente en lo que importa: si la versión YA está, no la duplica.
+export function insertChangelogEntry(text, entry, { version, repoUrl } = {}) {
+  const s = String(text ?? "");
+  if (version && new RegExp(`^## \\[${version.replace(/\./g, "\\.")}\\]`, "m").test(s)) {
+    return { text: s, changed: false, reason: `el CHANGELOG ya tiene una entrada para ${version}` };
+  }
+  const i = s.search(/^## \[/m);
+  let out = i === -1
+    ? `${s.replace(/\s*$/, "")}\n\n${entry}\n`
+    : `${s.slice(0, i)}${entry}\n${s.slice(i)}`;
+  if (version && repoUrl) {
+    const link = `[${version}]: ${repoUrl.replace(/\/+$/, "")}/releases/tag/v${version}`;
+    if (!out.includes(link)) {
+      // Junto a los otros links del pie si los hay; si no, al final.
+      const j = out.search(/^\[\d+\.\d+\.\d+\]: /m);
+      out = j === -1 ? `${out.replace(/\s*$/, "")}\n\n${link}\n` : `${out.slice(0, j)}${link}\n${out.slice(j)}`;
+    }
+  }
+  return { text: out, changed: true, reason: null };
+}
+
+// El cuerpo de una versión, para reusarlo como release note del forge.
+export function changelogSection(text, version) {
+  const s = String(text ?? "");
+  const re = new RegExp(`^## \\[${String(version).replace(/\./g, "\\.")}\\][^\\n]*\\n`, "m");
+  const m = s.match(re);
+  if (!m) return null;
+  const ini = m.index + m[0].length;
+  const resto = s.slice(ini);
+  const j = resto.search(/^## \[/m);
+  return (j === -1 ? resto : resto.slice(0, j)).replace(/<!--[\s\S]*?-->/g, "").trim() || null;
+}
+
+// ── Nombres ──────────────────────────────────────────────────────────────────
+export const releaseBranch = (version) => `release/${version}`;
+export const tagName = (version) => `v${String(version).replace(/^v/, "")}`;
+
+// Normaliza y valida lo que tipeó quien corta la versión. Un tag mal escrito se arrastra a
+// npm, al CHANGELOG y a todos los avisos, y renombrarlo después no existe.
+export function normalizeVersion(input) {
+  const v = String(input ?? "").trim().replace(/^v/i, "");
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-+]+)?$/.test(v)) {
+    throw new Error(`'${input}' no es una versión semver (X.Y.Z, opcionalmente -rc.1).`);
+  }
+  return v;
+}