@dforce2055/dai 0.14.0 → 0.15.0

package/cli/lib/help.mjs

@@ -227,6 +227,74 @@ Ejemplo:
   dai pr --base develop --description-file notas.md
 `,
 
+  release: `dai release — el ciclo de versión: qué entra, cortarla, cerrarla, contarla
+
+Uso:
+  dai release plan   [--from <ref>] [--to <rama>] [--json] [--no-network]
+  dai release cut    <X.Y.Z> [--no-branch] [--yes] [--dry-run]
+  dai release done   <X.Y.Z> [--app <n>] [--no-release] [--no-notify] [--yes] [--dry-run]
+  dai release stamp  <X.Y.Z> --env <ambiente> [--app <n>] [--url <u>] [--yes] [--dry-run]
+  dai release status [--no-network]
+  dai release notify --test
+
+El ciclo, con la firma humana en el medio:
+
+  plan  ──▶  cut  ──▶  dai pr  ──▶  [ merge + publicar: lo firma una persona ]
+                                                │
+                                                ▼
+                                            done  ──▶  stamp (opcional)
+
+plan — el MANIFIESTO: qué hay entre el último tag y la rama de integración, qué User
+  Stories entran y en qué estado, qué branches entraron sin US, y qué bump PROPONE.
+  Propone, no decide: dai lee los tipos de commit y la regla del repo mira el
+  comportamiento. Algo que mueve un default es minor aunque todo sea \`fix:\`.
+
+cut — prepara la versión: crea \`release/X.Y.Z\`, sube el número en los archivos que este
+  repo espeja (VERSION, package.json — si no hay ninguno, la versión es el tag), escribe
+  la entrada del CHANGELOG con el material para repartir, y commitea. No habla hacia
+  afuera: ni push, ni tag, ni PR. La prosa del CHANGELOG la escribís vos: dai sabe qué
+  entró, no por qué importa.
+  --no-branch   taguea desde la rama de integración, sin branch de release
+
+done — cierra la versión DESPUÉS del merge, igual que \`dai done\` cierra el trabajo de una
+  branch: tag anotado, release note en el forge,
+  back-merge a la rama de integración y aviso al canal. Es la mitad que se olvida cuando
+  la ceremonia se hace a mano. Cada paso reporta por separado: si falla la release note,
+  el tag YA existe y hay que saberlo.
+  --app <nombre>   con qué nombre aparece la app (default: el del repo)
+  --no-release     no publica la nota en el forge
+  --no-notify      no avisa al canal (DAI_NOTIFY)
+  --keep-branch    conserva la rama release/X.Y.Z (por default la borra: ya está mergeada,
+                   tagueada y con el back-merge hecho, y una que sobrevive a su release
+                   es un fork). git se niega a borrar una sin mergear.
+
+stamp — le avisa a CADA User Story del release en qué versión y ambiente salió. Es el
+  comando que más cuidado necesita: escribe N veces hacia afuera, en tickets de gente
+  distinta, y no se deshace. Por eso muestra el alcance REAL antes —cuántos comentarios,
+  en qué tickets, cuáles se saltean por estar ya estampados— y pide confirmación.
+  Es OPCIONAL: decir que no sale con 0 y no rompe nada, porque la versión ya está hecha.
+  Idempotente por (app, versión, ambiente): redesplegar no llena el ticket de repetidos.
+  --env <ambiente>  obligatorio. El que uses (prod, pre, test, uat-2): dai no tiene catálogo
+  --url <u>         link al release, para que el comentario lleve a algún lado
+
+status — dónde estás en el ciclo: versión declarada vs último tag, cuánto hay sin promover,
+  si falta el back-merge, branches de release abiertas y el canal configurado.
+  Lo que NO contesta es qué versión hay en cada ambiente: eso es un evento, no un archivo
+  del repo, y su registro son los stamps de las US.
+
+notify --test — postea un mensaje de prueba al canal. Un webhook no se puede validar sin
+  postear, y fingir que sí sería justo lo que dai no hace: avisa antes y pide confirmación.
+
+Config del repo (.env.dai):
+  DAI_BRANCH_DEV / DAI_BRANCH_PROD   las dos ramas de vida larga
+  DAI_NOTIFY=discord|slack|webex|telegram|webhook|none  ·  DAI_NOTIFY_WEBHOOK=<endpoint>
+
+Ejemplo:
+  dai release plan
+  dai release cut 1.2.0
+  dai release done 1.2.0
+`,
+
   done: `dai done — cierra la US: vuelve a la base, actualiza y borra la branch local
 
 Uso:
@@ -411,6 +479,14 @@ export function globalUsage() {
     "  stamp [<ID>…] [--all]        estampa la cobertura en el tracker (ADR-0005)\n" +
     "                               sin ID: la US de esta branch; si hay varias, pregunta\n" +
     "  done [--base b] [--force]    cierra la US: vuelve a la base, actualiza y borra la branch local\n" +
+    "  release plan [--from r] [--to b] [--json]   el manifiesto de la próxima versión: qué US entran,\n" +
+    "                               qué entró sin US, y qué bump propone (propone: firmás vos)\n" +
+    "  release cut <X.Y.Z> [--no-branch]   prepara la versión: branch + bump + entrada del CHANGELOG + commit\n" +
+    "  release done <X.Y.Z>       tras el merge: tag + release note + back-merge + aviso al canal\n" +
+    "      [--app n] [--no-release] [--no-notify]\n" +
+    "  release stamp <X.Y.Z> --env <amb>   avisa a cada US en qué versión y ambiente salió\n" +
+    "                               (muestra el alcance y confirma · opcional: decir que no no rompe nada)\n" +
+    "  release status · release notify --test   dónde estás en el ciclo · probar el canal\n" +
     "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
     "  pr (alias mr) [--assignee u] [--base b] [--draft] [--yes]   crea o ACTUALIZA TU PR/MR precargada (muestra + confirma)\n" +
     "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\n" +

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

@@ -53,6 +53,20 @@ export function updatePrCmd(tool, { number, title, body, 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.

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;
+}