@dforce2055/dai 0.13.2 → 0.14.0

package/cli/lib/pr-remote.mjs

@@ -0,0 +1,80 @@
+// 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"];
+}
+
+// ── "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/pr.mjs

@@ -2,7 +2,12 @@
 // Parte pura y testeable: rellena el template con los datos del link + git + check.
 // Los efectos (git push, gh/glab create) viven en dai.mjs.
 
-const EMOJI = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+// Más explícito que el label del CLI a propósito: esto queda PUBLICADO en la PR, donde
+// quien lee no tiene el contexto de la corrida que la creó.
+const EMOJI = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US",
+  "sin-respuesta": "⚠️ no verificado (el tracker no respondió)",
+};
 
 // Las secciones que dai se compromete a entregar llenas. Si alguna sale con el molde
 // del template, la PR se publica vacía y el review no tiene qué mirar (era el bug:
@@ -115,12 +120,21 @@ export function composePrBody(template, d) {
   return upsertLinksBlock(b, d);
 }
 
+// Los placeholders se rellenan DENTRO de la sección, no en todo el body: la misma frase
+// ("verificado con `dai check` ✅") aparecía en la prosa que explica el método, así que un
+// replace global le metía el estado de ESTA PR a una oración general y quedaba
+// "verificado con dai check: ✅ al día. Sin esto, el código no sabe…". dai reescribiendo
+// la prosa de otro es justo lo que el bloque de links ya evitaba con sus marcadores.
+// Sin la sección (un template ajeno con otra forma) se cae al body entero: rellenar de más
+// es recuperable, no rellenar deja la PR con `ABC-###` publicado.
 function fillUsHeader(template, d) {
-  let b = template;
-  b = b.replace(/`ABC-###`/g, `\`${d.id}\``);
-  b = b.replace(/@ `vX`/g, `@ \`${d.version}\``);
-  b = b.replace(/`<hash>`/g, `\`${d.ac_hash}\``);
-  return b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+  const fill = (t) => t
+    .replace(/`ABC-###`/g, `\`${d.id}\``)
+    .replace(/@ `vX`/g, `@ \`${d.version}\``)
+    .replace(/`<hash>`/g, `\`${d.ac_hash}\``)
+    .replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+  const sec = sectionBody(template, "🔗 Implementa");
+  return sec == null ? fill(template) : replaceSection(template, "🔗 Implementa", fill(sec).trim());
 }
 
 // PR de una branch exenta (chore/, docs/, release/…): no implementa una US y no se le

package/cli/lib/us-format.mjs

@@ -108,8 +108,19 @@ export function validateUS(md) {
 // (METODOLOGIA §4). Sube cuando el cambio es material, y eso lo sabe el PO: dai
 // mirando el hash no puede distinguir un criterio nuevo de un typo corregido.
 
+// La US se escribe a mano en un tracker, así que el nombre del campo llega como salga:
+// `spec_version`, `spec version`, `spec-version` y —visto en un Jira real— `specversion`
+// pegado. Con el `[_ ]` obligatorio de antes, `| specversion | v4 |` no matcheaba y el
+// link se estampaba en `v1` sin que nada avisara (issue #46). El separador es opcional.
+export const SPEC_VERSION_RE = /spec[\s_-]*version[^\n]*?\b(v\d+)\b/i;
+
+// El valor que se escribe cuando la US NO declara versión. Un placeholder VISIBLE es
+// mejor que un `v1` que parece correcto: el `v1` se publica en la PR y se estampa en el
+// tracker como si fuera un dato, cuando es una suposición de dai.
+export const PENDING_VERSION = "pendiente";
+
 export const parseSpecVersion = (md) => {
-  const m = String(md || "").match(/spec[_ ]version[^\n]*?\b(v\d+)\b/i);
+  const m = String(md || "").match(SPEC_VERSION_RE);
   return m ? m[1] : null;
 };
 
@@ -123,8 +134,8 @@ export const bumpSpecVersion = (v) => {
 // al final, donde nadie lo ve, ni en una tabla que no existe.
 export function setSpecVersion(md, version) {
   const text = String(md || "");
-  if (/spec[_ ]version[^\n]*?\bv\d+\b/i.test(text)) {
-    return text.replace(/(spec[_ ]version[^\n]*?\b)v\d+\b/i, `$1${version}`);
+  if (SPEC_VERSION_RE.test(text)) {
+    return text.replace(/(spec[\s_-]*version[^\n]*?\b)v\d+\b/i, `$1${version}`);
   }
   const lines = text.split(/\r?\n/);
   const i = lines.findIndex((l) => /^#\s+\S/.test(l));

package/cli/lib/us.mjs

@@ -3,21 +3,34 @@
 
 import { acHash } from "./ac-hash.mjs";
 import { extractTitle } from "./link-us.mjs";
+import { parseSpecVersion } from "./us-format.mjs";
 
 // Parseo puro de una US (markdown o texto) → identidad + hash vivo.
 export function parseUS(raw) {
   const title = extractTitle(raw);
-  const m = raw.match(/spec[_ ]version[^\n]*?\b(v\d+)\b/i);
-  return { title, spec_version: m ? m[1] : null, ac_hash: acHash(raw) };
+  // El regex vive en us-format.mjs: es UNO solo para leer, escribir y bumpear la versión.
+  // Duplicado acá, la variante `specversion` (sin separador) se arreglaba en un lado y
+  // seguía rota en el otro — que es exactamente como nació el issue #46.
+  return { title, spec_version: parseSpecVersion(raw), ac_hash: acHash(raw) };
 }
 
 // Compara el hash estampado (implements.yaml) con el hash vivo de la US.
-export function coverageStatus(stampedHash, liveHash) {
+//
+// `sin-us` y `sin-respuesta` NO son lo mismo, y confundirlos es caro: el primero es una
+// RESPUESTA del tracker (preguntamos y la US no está), el segundo es la AUSENCIA de
+// respuesta (sin red, sin token, 5xx, certificado corporativo). Colapsados en un mismo
+// `null`, dai terminaba AFIRMANDO que no había US cuando lo único cierto era que no había
+// podido preguntar — y eso se publicaba en el cuerpo de una PR, al lado del id de la US.
+export function coverageStatus(stampedHash, liveHash, { unreachable = false } = {}) {
+  if (unreachable) return "sin-respuesta";
   if (liveHash == null) return "sin-us";
   return stampedHash === liveHash ? "al-dia" : "atrasado";
 }
 
-const STATUS_LABEL = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+const STATUS_LABEL = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado",
+  "sin-us": "❓ sin US", "sin-respuesta": "⚠️ no verificado",
+};
 export const statusLabel = (s) => STATUS_LABEL[s] || s;
 
 // Render de la cobertura como markdown (lo que un backend "estampa").
@@ -34,3 +47,25 @@ export function renderCoverage(id, r) {
   if (r.commitUrl) lines.push(`- commit: ${r.commit} → ${r.commitUrl}  (ancla durable)`);
   return lines.join("\n") + "\n";
 }
+
+// `fetch failed` es TODO lo que dice undici cuando no hay red, el host no resuelve, el DNS
+// se cayó o el certificado no valida. Sin contexto es indistinguible de un bug de dai: el
+// dev lee "dai: fetch failed" y no sabe ni qué se estaba consultando. Es el mismo modo de
+// falla que el push por SSH de la 0.13.1 — el dato que resuelve el problema existe, y no
+// llega. Acá se le pone alrededor qué, contra qué, y qué mirar.
+export function explainFetchError(err, { kind, endpoint, id } = {}) {
+  const raw = String(err?.message ?? err ?? "").split("\n")[0] || "error desconocido";
+  const donde = [kind, endpoint].filter(Boolean).join(" · ");
+  const cabeza = `no pude consultar ${id ? `la US ${id}` : "el tracker"}${donde ? ` en ${donde}` : ""}: ${raw}`;
+  if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|certificate|self.signed/i.test(raw)) {
+    return `${cabeza}\n  No llegó a haber respuesta. Revisá la red y el host del backend; si estás detrás de un\n` +
+           `  proxy corporativo, declará la CA con NODE_EXTRA_CA_CERTS (nunca NODE_TLS_REJECT_UNAUTHORIZED=0).\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b40[13]\b|unauthorized|forbidden/i.test(raw)) {
+    return `${cabeza}\n  El tracker rechazó las credenciales: revisá el token del .env.dai (¿venció?) y sus permisos.\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b5\d\d\b/.test(raw)) return `${cabeza}\n  El error es del tracker, no tuyo: probá de nuevo en un rato.`;
+  return cabeza;
+}

package/governance/branch-naming.md

@@ -20,7 +20,21 @@ Ejemplo: `feature/ABC-482-finalizar-compra-sin-duplicado`
 - El **ID nunca se tipea a mano**: sale del argumento de `/link-us ABC-###`. Elimina
   el error de tipeo que rompe el link ([Art. 8](../docs/MANIFIESTO.md#art-8), Art. 9).
 - El **slug** deriva del título de la US: minúsculas, sin acentos ni ñ, espacios → `-`.
-- La **base** de la rama sigue la convención del repo (`main` o `develop`).
+- La **base** de una PR no se recuerda ni se configura una por una: sale del **tipo de
+  rama**, leyendo las dos ramas de vida larga que el repo declara en su `.env.dai`.
+
+  | Tipo de rama | PR contra | Variable |
+  |---|---|---|
+  | `feature/`, `fix/`, el resto | la rama que integra | `DAI_BRANCH_DEV` |
+  | `release/`, `hotfix/` | la rama que despliega a producción | `DAI_BRANCH_PROD` |
+
+  `dai pr` y `dai done` usan ese mapa; `--base` siempre gana. Si `DAI_BRANCH_DEV` no está
+  declarada, dai usa la rama default del remoto y **avisa que la está adivinando**.
+- Apuntarle a `DAI_BRANCH_PROD` pide una **confirmación explícita**: hay que escribir el
+  nombre de la rama, y con `--yes` hace falta `--to-prod`. En repos con ramas de ambiente
+  (`testing` integra, `main` va a producción) esto es lo que evita que una PR quede
+  proponiendo un despliegue que nadie pidió. Sin la variable declarada, dai no marca
+  ninguna rama como producción: no adivina cuál es.
 - Una rama, una US. Si una US toca varios repos, es una rama por repo, **todas con el
   mismo `ABC-###`** — así el índice las agrupa en una fila (federación).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",

package/templates/pull-request.md

@@ -5,19 +5,23 @@
   Lo puede pre-llenar `dai`/una skill a partir del implements.yaml y el diff.
 -->
 
-> **Un PR en dai entrega dos activos, y el review cubre los dos:**
-> 1. **La implementación** — el código que resuelve la US.
-> 2. **El spec trazable** — el `implements.yaml` con el link a la US y el `@version`
->    (`ac_hash`) verificado con `dai check` ✅. Sin esto, el código no sabe *a qué QUÉ*
->    responde, y el CI bloquea el PR (ver `governance/ci-rules.md`).
-
 ## 🔗 Implementa
 
 - **US:** `ABC-###` @ `vX`  ·  ac_hash: `<hash>`  ·  verificado con `dai check` ✅
-- **Link:** este PR está atado a la US vía `implements.yaml`.
 
-> Si este PR no implementa una US (chore/fix sin ticket), borra esta sección y
-> aclara el motivo — no se le exige link.
+<!--
+  Un PR en dai entrega DOS activos, y el review cubre los dos: la implementación (el código
+  que resuelve la US) y el spec trazable (el `implements.yaml` con el link a la US y el
+  `@version`/`ac_hash` verificado). Sin el link, el código no sabe a qué QUÉ responde y el
+  CI bloquea el PR — ver `governance/ci-rules.md`.
+
+  ¿Chore o fix sin ticket? No hay nada que borrar: `dai pr` lo detecta por el nombre de la
+  branch y escribe "Sin US" con el motivo. No se le exige link.
+
+  Esto es un comentario a propósito: es doctrina del método, igual en las 500 PRs del repo.
+  Repetirla a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción.
+-->
 
 ## Descripción