supcoflow 0.7.0 → 0.8.1

package/dist/comandos/guia.js

@@ -1,10 +1,12 @@
 // src/comandos/guia.ts
-// `guia revisar|publicar|ver|usar` (bloque 5): la guía del producto que vive en el repo del cliente
-// (`.supcoflow/guia.md`). La terminal NO decide qué es una guía buena —eso lo decide el parser del motor—;
-// lee el archivo, manda UN pedido y traduce la respuesta a los códigos de salida del contrato.
+// `guide check|publish|show|use|versions` (bloque 5 y 0.8.0): la guía del producto que vive en el repo del cliente
+// (`.supcoflow/guide.md`; el nombre viejo `guia.md` se lee sólo si `guide.md` no existe). La terminal NO decide qué
+// es una guía buena —eso lo decide el parser del motor—; lee el archivo, manda UN pedido y traduce la respuesta a
+// los códigos de salida del contrato.
 import path from "node:path";
 import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
-import { huellaDeGuia, MAX_BYTES_DE_LA_GUIA, RUTA_DE_LA_GUIA } from "../guia.js";
+import { huellaDeGuia, MAX_BYTES_DE_LA_GUIA, RUTA_DE_LA_GUIA, RUTA_VIEJA_DE_LA_GUIA } from "../guia.js";
+import { NO_LEIDO } from "../lectura.js";
 import { repoPedido } from "../repo-local.js";
 import { desenlace, fallo, rutaDe } from "./configurar.js";
 import { proyectoDelRepo } from "./proyecto-del-repo.js";
@@ -15,56 +17,88 @@ import { proyectoDelRepo } from "./proyecto-del-repo.js";
 const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""));
 const cadena = (v) => (typeof v === "string" ? limpio(v) : "");
 const corto = (commit) => cadena(commit).slice(0, 7);
-const secciones = (n) => (typeof n === "number" ? `${n} ${n === 1 ? "sección" : "secciones"}` : "secciones sin contar");
-const NOMBRE_DEL_ORIGEN = { repo: "la del repo", agente: "la de nuestro agente" };
+const secciones = (n) => (typeof n === "number" ? `${n} ${n === 1 ? "section" : "sections"}` : "sections not counted");
+const NOMBRE_DEL_ORIGEN = { repo: "the repo's", agente: "our agent's" };
+// El valor del flag `--source` para un origen de la API (el de nuestro agente se pide como `agent`).
+const COMO_SE_PIDE = { repo: "repo", agente: "agent" };
+// Los avisos del nombre del archivo; los códigos son los que usa el motor por GitHub (`aviso`).
+const AVISOS_DEL_NOMBRE = {
+    nombre_viejo: `\`${RUTA_VIEJA_DE_LA_GUIA}\` is the old name: rename it to \`guide.md\`.`,
+    nombre_viejo_ignorado: `Both \`${RUTA_DE_LA_GUIA}\` and \`${RUTA_VIEJA_DE_LA_GUIA}\` exist: I use guide.md and ignore guia.md.`,
+};
 // ─── El archivo local ───
 // Se busca en la raíz de ESTE clon, nunca en el cwd: parado en una subcarpeta sigue siendo la guía del repo.
 // Con `--repo` y sin clon de ese repo no hay dónde leerla (publicar lee la rama, pero la huella sale del archivo).
+// Se lee `guide.md`; SÓLO si no existe se lee `guia.md` (si `guide.md` existe y no se puede leer, o no valida, es un
+// error: nunca motivo para leer el viejo). Si están los dos manda `guide.md` y se avisa que el otro se ignora.
 async function leerLaGuia(d, flags) {
     let raiz;
+    let sinClon;
     try {
-        raiz = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+        ({ raiz, sinClon } = await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd }));
     }
     catch (e) {
         return { ok: false, resultado: resultadoDeFallo(e) };
     }
     if (raiz === null) {
-        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `No tengo el clon de ese repo acá, y la guía se lee de ${RUTA_DE_LA_GUIA}: parate en el clon del repo.`) };
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `${sinClon ?? "I don't have that repo's clone here."} The guide is read from ${RUTA_DE_LA_GUIA} in the repo's clone: stand in it.`) };
+    }
+    let ruta = RUTA_DE_LA_GUIA;
+    let aviso = null;
+    let leido = d.leerArchivoChico(path.join(raiz, ruta), MAX_BYTES_DE_LA_GUIA);
+    if ("error" in leido && leido.error === NO_LEIDO.noExiste) {
+        const vieja = d.leerArchivoChico(path.join(raiz, RUTA_VIEJA_DE_LA_GUIA), MAX_BYTES_DE_LA_GUIA);
+        if ("error" in vieja && vieja.error === NO_LEIDO.noExiste) {
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `${RUTA_DE_LA_GUIA} is missing in the repo: write it (one section per screen) and run again.`) };
+        }
+        ruta = RUTA_VIEJA_DE_LA_GUIA;
+        aviso = "nombre_viejo";
+        leido = vieja;
+    }
+    else if (!("error" in leido)) {
+        // Con `guide.md` leído, el viejo sólo se mira para avisar que se ignora (no se lee su contenido).
+        const vieja = d.leerArchivoChico(path.join(raiz, RUTA_VIEJA_DE_LA_GUIA), 1);
+        if (!("error" in vieja) || vieja.error !== NO_LEIDO.noExiste)
+            aviso = "nombre_viejo_ignorado";
     }
-    const leido = d.leerArchivoChico(path.join(raiz, RUTA_DE_LA_GUIA), MAX_BYTES_DE_LA_GUIA);
     if ("error" in leido) {
-        if (leido.error === "no existe")
-            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `Falta ${RUTA_DE_LA_GUIA} en el repo: escribila (una sección por pantalla) y volvé a correr.`) };
-        if (leido.error === "es demasiado grande")
-            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_muy_grande", `${RUTA_DE_LA_GUIA} pasa los ${MAX_BYTES_DE_LA_GUIA / 1024} KB: acortala.`) };
-        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `No leo ${RUTA_DE_LA_GUIA}: ${limpio(leido.error)}.`) };
+        if (leido.error === NO_LEIDO.demasiadoGrande)
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_muy_grande", `${ruta} is over ${MAX_BYTES_DE_LA_GUIA / 1024} KB: shorten it.`) };
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `I can't read ${ruta}: ${limpio(leido.error)}.`) };
     }
     try {
         // ignoreBOM: el BOM se CONSERVA en el texto; quitarlo es regla de la huella (`huellaDeGuia`), no de la lectura.
         // fatal: un byte inválido no se reemplaza en silencio, porque la huella de GitHub no coincidiría nunca.
-        return { ok: true, raiz, texto: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(leido.bytes) };
+        return { ok: true, raiz, ruta, aviso, texto: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(leido.bytes) };
     }
     catch {
-        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `${RUTA_DE_LA_GUIA} no es UTF-8 válido.`) };
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `${ruta} isn't valid UTF-8.`) };
     }
 }
+// El aviso del nombre viaja en el JSON (`aviso`) y como última línea del texto, en lo que salió bien.
+function conAviso(r, aviso) {
+    // Si el motor ya dijo el suyo (por GitHub lee el repo él mismo, en un SHA), manda ése.
+    if (aviso === null || r.codigo !== SALIDA.ok || "aviso" in r.json)
+        return r;
+    return { ...r, json: { ...r.json, aviso }, texto: `${r.texto}\n${AVISOS_DEL_NOMBRE[aviso]}` };
+}
 // ─── El desenlace propio de la guía, encima del de configurar ───
-function desenlaceDeGuia(r, ok) {
+function desenlaceDeGuia(r, ok, ruta = RUTA_DE_LA_GUIA) {
     const c = r.cuerpo;
     // 2xx, 401, 5xx y cuerpos raros los resuelve el de configurar. Ojo: la terminal no distingue 500
     // connect_no_disponible de 502 github_no_disponible (ambos llegan como falla del servicio): los dos son 1.
     if (r.status < 400 || r.status === 401 || r.status >= 500 || typeof c !== "object" || c === null)
         return desenlace(r, ok);
     const error = typeof c.error === "string" ? c.error : "rechazado";
-    const message = limpio(typeof c.message === "string" ? c.message : `El motor rechazó el pedido (${r.status}).`);
+    const message = limpio(typeof c.message === "string" ? c.message : `The engine rejected the request (${r.status}).`);
     const con = (codigo, extra = {}, texto = message) => ({ codigo, json: { ok: false, error, message: taparSecretos(message), ...extra }, texto });
     switch (error) {
         case "guia_no_subida":
         case "guia_distinta": {
             const rama = cadena(c.rama), commit = cadena(c.commit);
-            const donde = rama !== "" ? ` (rama ${rama}${commit !== "" ? `, commit ${corto(commit)}` : ""})` : "";
-            const que = error === "guia_no_subida" ? "La guía no está en la rama principal del repo" : "La guía de la rama principal es otra, no la de tu archivo";
-            return con(SALIDA.esperandoAUnaPersona, { rama: c.rama ?? null, commit: c.commit ?? null }, `${que}${donde}: subí la guía a la rama principal y volvé a correr.`);
+            const donde = rama !== "" ? ` (branch ${rama}${commit !== "" ? `, commit ${corto(commit)}` : ""})` : "";
+            const que = error === "guia_no_subida" ? "The guide isn't on the repo's main branch" : "The main branch's guide is another one, not your file's";
+            return con(SALIDA.esperandoAUnaPersona, { rama: c.rama ?? null, commit: c.commit ?? null }, `${que}${donde}: push the guide to the main branch and run again.`);
         }
         case "instalacion_ausente":
         case "repo_fuera_de_alcance":
@@ -74,9 +108,9 @@ function desenlaceDeGuia(r, ok) {
             const errores = Array.isArray(c.errores) ? c.errores : [];
             const lineas = errores.map((e) => {
                 const x = (e ?? {});
-                return `línea ${typeof x.linea === "number" ? x.linea : "?"}: ${cadena(x.motivo)}`;
+                return `line ${typeof x.linea === "number" ? x.linea : "?"}: ${cadena(x.motivo)}`;
             });
-            return con(SALIDA.entradaInvalida, { errores: errores.map((e) => { const x = (e ?? {}); return { linea: x.linea ?? null, motivo: taparSecretos(typeof x.motivo === "string" ? x.motivo : "") }; }) }, [`${RUTA_DE_LA_GUIA} está mal armada:`, ...lineas].join("\n"));
+            return con(SALIDA.entradaInvalida, { errores: errores.map((e) => { const x = (e ?? {}); return { linea: x.linea ?? null, motivo: taparSecretos(typeof x.motivo === "string" ? x.motivo : "") }; }) }, [`${ruta} is badly formed:`, ...lineas].join("\n"));
         }
         default:
             return desenlace(r, ok);
@@ -90,13 +124,13 @@ export async function guiaRevisar(d, flags) {
     if (!p.ok)
         return p.resultado;
     if (flags.dryRun) {
-        const haria = `POST ${rutaDe(p.proyecto, "/guia/revisar")} (${new TextEncoder().encode(g.texto).length} bytes)`;
-        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+        const haria = `POST ${rutaDe(p.proyecto, "/guia/revisar")} (${new TextEncoder().encode(g.texto).length} bytes, from ${g.ruta})`;
+        return conAviso({ codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria, ruta: g.ruta }, texto: `With --dry-run I do nothing; without it: ${haria}.` }, g.aviso);
     }
     try {
-        return desenlaceDeGuia(await d.revisar(d.api, p.clave, p.proyecto.id, g.texto, d.fetch), (c) => ({
-            codigo: SALIDA.ok, json: { ok: true, secciones: c.secciones ?? null }, texto: `La guía está bien armada: ${secciones(c.secciones)}.`,
-        }));
+        return conAviso(desenlaceDeGuia(await d.revisar(d.api, p.clave, p.proyecto.id, g.texto, d.fetch), (c) => ({
+            codigo: SALIDA.ok, json: { ok: true, secciones: c.secciones ?? null, ruta: g.ruta }, texto: `The guide is well formed: ${secciones(c.secciones)}.`,
+        }), g.ruta), g.aviso);
     }
     catch (e) {
         return resultadoDeFallo(e);
@@ -130,42 +164,53 @@ export async function guiaPublicar(d, flags) {
     const p = await proyectoDelRepo(d, flags);
     if (!p.ok)
         return p.resultado;
-    const github = flags.desdeGithub === true;
+    const github = flags.fromGithub === true;
     // La vía de GitHub manda la huella del archivo local TAL CUAL (con BOM y \r\n: normalizarla es regla de
     // `huellaDeGuia`). La directa manda el contenido crudo y el motor calcula la huella: la terminal no la necesita.
     const huella = github ? huellaDeGuia(g.texto) : null;
     const decl = github ? {} : await declarado(d, g.raiz);
-    const cuerpo = huella !== null ? { huella } : { contenido: g.texto, ...decl };
-    const cuando = decl.commit ? `commit ${decl.commit.slice(0, 7)}${decl.rama ? ` de ${cadena(decl.rama)}` : ""} declarado` : "sin commit";
+    // La directa manda además la ruta que se leyó de verdad (dato declarado, como el commit y la rama). Por GitHub el
+    // motor resuelve los nombres él mismo, sobre un solo SHA de la rama principal.
+    const cuerpo = huella !== null ? { huella } : { contenido: g.texto, ruta: g.ruta, ...decl };
+    const cuando = decl.commit ? `commit ${decl.commit.slice(0, 7)}${decl.rama ? ` of ${cadena(decl.rama)}` : ""} declared` : "no commit";
     // El JSON del dry-run pasa por la misma limpieza que el texto (control primero, secretos después): la rama la
     // decide quien escribió el clon, y un ESC en ella no debe llegar a la terminal por ninguna de las dos salidas.
     if (flags.dryRun) {
         const haria = huella !== null
-            ? `POST ${rutaDe(p.proyecto, "/guia/publicar")} con la huella ${huella.slice(0, 12)}…`
-            : `POST ${rutaDe(p.proyecto, "/guia/publicar")} con el contenido (${new TextEncoder().encode(g.texto).length} bytes), ${cuando}`;
-        const json = huella !== null ? { ok: true, dry_run: true, huella, haria } : { ok: true, dry_run: true, commit: decl.commit ? cadena(decl.commit) : null, rama: decl.rama ? cadena(decl.rama) : null, haria };
-        return { codigo: SALIDA.ok, json, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+            ? `POST ${rutaDe(p.proyecto, "/guia/publicar")} with the fingerprint ${huella.slice(0, 12)}…`
+            : `POST ${rutaDe(p.proyecto, "/guia/publicar")} with the content (${new TextEncoder().encode(g.texto).length} bytes, from ${g.ruta}), ${cuando}`;
+        const json = huella !== null
+            ? { ok: true, dry_run: true, huella, ruta: g.ruta, haria }
+            : { ok: true, dry_run: true, ruta: g.ruta, commit: decl.commit ? cadena(decl.commit) : null, rama: decl.rama ? cadena(decl.rama) : null, haria };
+        return conAviso({ codigo: SALIDA.ok, json, texto: `With --dry-run I do nothing; without it: ${haria}.` }, g.aviso);
     }
     try {
-        return desenlaceDeGuia(await d.publicar(d.api, p.clave, p.proyecto.id, cuerpo, d.fetch), (c) => {
+        return conAviso(desenlaceDeGuia(await d.publicar(d.api, p.clave, p.proyecto.id, cuerpo, d.fetch), (c) => {
             const guia = (c.guia ?? {});
             const ya = c.ya_publicada === true;
             const rem = c.reemplaza;
-            const reemplaza = !ya && rem && rem.origen === "agente" && typeof rem.version === "number" ? ` (reemplaza a la de nuestro agente v${rem.version})` : "";
+            const reemplaza = !ya && rem && rem.origen === "agente" && typeof rem.version === "number" ? ` (replaces our agent's v${rem.version})` : "";
             const json = { ok: true, guia: c.guia ?? null, ya_publicada: ya, reemplaza: c.reemplaza ?? null };
+            // Una resubida idéntica devuelve la fila vieja con su ruta histórica: se dice, para que nadie crea que el
+            // renombre quedó registrado.
+            const ruta = cadena(guia.ruta);
+            const nota = ya && ruta !== "" && ruta !== g.ruta ? `\nThat version keeps the file name it was first published with (${ruta}).` : "";
             if (github) {
-                const base = `commit ${corto(guia.commit)} de ${cadena(guia.rama)}, ${secciones(guia.secciones)}`;
+                const base = `commit ${corto(guia.commit)} of ${cadena(guia.rama)}, ${secciones(guia.secciones)}`;
                 // Republicar re-activa la guía del repo aunque antes rigiera la de nuestro agente: «sigue siendo» mentiría en ese caso.
-                const texto = ya ? `Ya estaba publicada: ${base}. Quedó como guía activa.` : `Guía publicada: ${base}. Es la guía activa${reemplaza}.`;
-                return { codigo: SALIDA.ok, json, texto };
+                const texto = ya ? `It was already published: ${base}. It stayed as the active guide.${nota}` : `Guide published: ${base}. It's the active guide${reemplaza}.${nota}`;
+                const delMotor = typeof c.aviso === "string" && c.aviso in AVISOS_DEL_NOMBRE ? c.aviso : null;
+                return delMotor === null
+                    ? { codigo: SALIDA.ok, json, texto }
+                    : { codigo: SALIDA.ok, json: { ...json, aviso: delMotor }, texto: `${texto}\n${AVISOS_DEL_NOMBRE[delMotor]}` };
             }
             // El commit se muestra como lo que es: lo que la terminal dijo, no lo que GitHub confirmó.
-            const origen = decl.commit ? `commit ${decl.commit.slice(0, 7)} declarado por la terminal (no verificado en GitHub)` : "sin commit";
+            const origen = decl.commit ? `commit ${decl.commit.slice(0, 7)} declared by the terminal (not verified in GitHub)` : "no commit";
             const texto = ya
-                ? `Ya estaba subida: ${secciones(guia.secciones)}. Quedó como guía activa; ${origen}.`
-                : `Guía subida: ${secciones(guia.secciones)}. Es la guía activa${reemplaza}; ${origen}.`;
+                ? `It was already uploaded: ${secciones(guia.secciones)}. It stayed as the active guide; ${origen}.${nota}`
+                : `Guide uploaded: ${secciones(guia.secciones)}. It's the active guide${reemplaza}; ${origen}.${nota}`;
             return { codigo: SALIDA.ok, json: { ...json, commit_declarado: decl.commit ?? null }, texto };
-        });
+        }, g.ruta), g.aviso);
     }
     catch (e) {
         return resultadoDeFallo(e);
@@ -183,35 +228,39 @@ export async function guiaVer(d, flags) {
             const alDia = rama && typeof rama.al_dia === "boolean" ? rama.al_dia : null;
             const json = { ok: true, guia: guia ?? null, otra: otra ?? null, al_dia: alDia, rama: rama ?? null };
             if (!guia)
-                return { codigo: SALIDA.ok, json, texto: "Este proyecto no tiene guía activa: `supcoflow guia publicar` sube la del repo." };
+                return { codigo: SALIDA.ok, json, texto: "This project has no active guide: `supcoflow guide publish` uploads the repo's." };
             const lineas = [];
             if (guia.origen === "repo") {
-                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.repo} (versión ${guia.version}, ${secciones(guia.secciones)}).`);
+                lineas.push(`Active guide: ${NOMBRE_DEL_ORIGEN.repo} (version ${guia.version}, ${secciones(guia.secciones)}).`);
+                // La ruta es la que se leyó de verdad; por la terminal es declarada (el motor no la verificó), por GitHub no.
+                const ruta = cadena(guia.ruta);
+                if (ruta !== "")
+                    lineas.push(`File: ${ruta}${guia.procedencia === "terminal" ? " (declared by the terminal)" : ""}.`);
                 if (guia.procedencia === "terminal") {
                     // Subida desde la terminal: el motor NO comparó nada contra GitHub a propósito (al_dia null), así que "no pude
                     // comprobar la rama" sería falso. Commit y rama son lo que declaró quien subió; el id crudo de quien publicó
                     // (usr_…) no le dice nada a una persona y la terminal no resuelve nombres: queda sólo en el JSON.
                     const commit = cadena(guia.commit), rama = cadena(guia.rama);
-                    const partes = [cadena(guia.repo), rama !== "" ? `rama ${rama}` : "", commit !== "" ? `commit ${corto(commit)} (declarado)` : "sin commit declarado"].filter((x) => x !== "");
-                    lineas.push(`Procedencia: ${partes.join(", ")}.`);
-                    lineas.push("Subida desde la terminal; el commit es declarado, no verificado en GitHub.");
+                    const partes = [cadena(guia.repo), rama !== "" ? `branch ${rama}` : "", commit !== "" ? `commit ${corto(commit)} (declared)` : "no declared commit"].filter((x) => x !== "");
+                    lineas.push(`Source: ${partes.join(", ")}.`);
+                    lineas.push("Uploaded from the terminal; the commit is declared, not verified in GitHub.");
                 }
                 else {
-                    lineas.push(`Procedencia: ${cadena(guia.repo)}, rama ${cadena(guia.rama)}, commit ${corto(guia.commit)}, publicada por ${cadena(guia.publicada_por)}.`);
+                    lineas.push(`Source: ${cadena(guia.repo)}, branch ${cadena(guia.rama)}, commit ${corto(guia.commit)}, published by ${cadena(guia.publicada_por)}.`);
                     if (alDia === true)
-                        lineas.push("Está al día con la rama.");
+                        lineas.push("It's up to date with the branch.");
                     else if (alDia === false)
-                        lineas.push("En la rama hay otra versión: corré `supcoflow guia publicar`.");
+                        lineas.push("The branch has another version: run `supcoflow guide publish`.");
                     else
-                        lineas.push("No pude comprobar la rama ahora.");
+                        lineas.push("I couldn't check the branch right now.");
                 }
             }
             else {
-                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.agente} (v${guia.version}, ${secciones(guia.secciones)}).`);
-                lineas.push("Procedencia: la escribió nuestro agente y la aprobó una persona.");
+                lineas.push(`Active guide: ${NOMBRE_DEL_ORIGEN.agente} (v${guia.version}, ${secciones(guia.secciones)}).`);
+                lineas.push("Source: our agent wrote it and a person approved it.");
             }
             if (otra && (otra.origen === "repo" || otra.origen === "agente")) {
-                lineas.push(`También hay ${NOMBRE_DEL_ORIGEN[otra.origen]} (v${typeof otra.version === "number" ? otra.version : "?"}): \`supcoflow guia usar --origen ${otra.origen}\` la activa.`);
+                lineas.push(`There's also ${NOMBRE_DEL_ORIGEN[otra.origen]} (v${typeof otra.version === "number" ? otra.version : "?"}): \`supcoflow guide use --source ${COMO_SE_PIDE[otra.origen]}\` activates it.`);
             }
             return { codigo: SALIDA.ok, json, texto: lineas.join("\n") };
         });
@@ -221,24 +270,63 @@ export async function guiaVer(d, flags) {
     }
 }
 export async function guiaUsar(d, flags) {
-    const origen = flags.origen ?? null;
+    const pedido = flags.source ?? null;
+    if (pedido === null)
+        return fallo(SALIDA.entradaInvalida, "falta_origen", "Say which: `supcoflow guide use --source repo` or `--source agent`.");
+    // A la API siempre viaja su valor (`agente`); `agente` también se acepta, por el alias viejo.
+    const origen = pedido === "repo" ? "repo" : pedido === "agent" || pedido === "agente" ? "agente" : null;
     if (origen === null)
-        return fallo(SALIDA.entradaInvalida, "falta_origen", "Decí cuál: `supcoflow guia usar --origen repo` o `--origen agente`.");
-    if (origen !== "repo" && origen !== "agente")
-        return fallo(SALIDA.entradaInvalida, "origen_invalido", "--origen es `repo` o `agente`.");
+        return fallo(SALIDA.entradaInvalida, "origen_invalido", "--source is `repo` or `agent`.");
     const p = await proyectoDelRepo(d, flags);
     if (!p.ok)
         return p.resultado;
     if (flags.dryRun) {
         const haria = `POST ${rutaDe(p.proyecto, "/guia/origen")} {origen: ${origen}}`;
-        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `With --dry-run I do nothing; without it: ${haria}.` };
     }
     try {
         return desenlaceDeGuia(await d.elegir(d.api, p.clave, p.proyecto.id, origen, d.fetch), (c) => ({
-            codigo: SALIDA.ok, json: { ok: true, guia: c.guia ?? null }, texto: `Ahora la guía activa es ${NOMBRE_DEL_ORIGEN[origen]}.`,
+            codigo: SALIDA.ok, json: { ok: true, guia: c.guia ?? null }, texto: `Now the active guide is ${NOMBRE_DEL_ORIGEN[origen]}.`,
         }));
     }
     catch (e) {
         return resultadoDeFallo(e);
     }
 }
+// `guide versions`: la guía que rige ahora (la que lee el chat) y las publicaciones del repo, de la más nueva a la más
+// vieja. Una sola publicación dice «live»: la que es la vigente (el motor lo decide; acá sólo se muestra).
+export async function guiaVersiones(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        return desenlaceDeGuia(await d.versiones(d.api, p.clave, p.proyecto.id, d.fetch), (c) => {
+            const vigente = typeof c.vigente === "object" && c.vigente !== null ? c.vigente : null;
+            const publicaciones = Array.isArray(c.publicaciones) ? c.publicaciones.map((x) => (typeof x === "object" && x !== null ? x : {})) : [];
+            const json = { ok: true, vigente, publicaciones };
+            const lineas = [];
+            if (vigente === null)
+                lineas.push("Active now: no guide.");
+            else if (vigente.origen === "agente")
+                lineas.push(`Active now: ${NOMBRE_DEL_ORIGEN.agente} guide, v${vigente.version} (${secciones(vigente.secciones)}).`);
+            else
+                lineas.push(`Active now: ${NOMBRE_DEL_ORIGEN.repo} guide, version ${vigente.version} (${secciones(vigente.secciones)}).`);
+            lineas.push(publicaciones.length === 0 ? "Published from the repo: none." : "Published from the repo, newest first:");
+            for (const x of publicaciones) {
+                const estado = x.live === true || x.estado === "live" ? "live" : "published";
+                const donde = [
+                    x.procedencia === "terminal" ? "uploaded from the terminal (declared)" : x.procedencia === "github" ? "verified in GitHub" : "",
+                    cadena(x.commit) !== "" ? `commit ${corto(x.commit)}` : "",
+                    cadena(x.ruta),
+                    cadena(x.publicada_por) !== "" ? `by ${cadena(x.publicada_por)}` : "",
+                    cadena(x.publicada_en),
+                ].filter((t) => t !== "");
+                lineas.push(`  v${x.version} ${estado}${donde.length > 0 ? ` · ${donde.join(" · ")}` : ""}`);
+            }
+            return { codigo: SALIDA.ok, json, texto: lineas.join("\n") };
+        });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/comandos/instalacion.js

@@ -1,19 +1,29 @@
 // src/comandos/instalacion.ts
-// `instalacion anotar --skill <versión> [--app <carpeta>] [--dry-run]` (bloque 6): deja en
-// `.supcoflow/instalacion.json` con qué versiones se instaló el chat. Lee la configuración del motor y los
-// `package.json` de la app y del paquete instalado; nunca ejecuta nada del repo (ni `npm ls` ni `node`).
+// `install record --skill <versión> [--app <carpeta>] [--file <ruta>] [--dry-run]` (bloque 6 y 0.8.0): deja en
+// `.supcoflow/instalacion.json` con qué versiones se instaló el chat y, desde la 0.8.0 (v2), en qué archivo quedó
+// (`--file`). Lee la configuración del motor y los `package.json` de la app y del paquete instalado; nunca ejecuta
+// nada del repo (ni `npm ls` ni `node`).
 //
 // La regla de §13 («no pisa archivos ni cambios sin commit») adaptada a un archivo que tiene que poder cambiar
 // (decisión 11): se reescribe sólo si git ya guarda el anterior. El control se hace ANTES de escribir; si la
 // persona edita el archivo entre el control y el `rename`, su cambio se pierde. Esa carrera se acepta: es una
 // persona instalando, y el archivo lo escribe sólo este comando.
-import { realpathSync, statSync } from "node:fs";
+import { lstatSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
-import { armarInstalacion, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar } from "../instalacion.js";
+import { archivoAnotado, armarInstalacion, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar, validarElArchivoDelChat } from "../instalacion.js";
+import { NO_LEIDO } from "../lectura.js";
 import { repoPedido } from "../repo-local.js";
 import { fallo } from "./configurar.js";
 import { proyectoDelRepo } from "./proyecto-del-repo.js";
+export function esEnlaceReal(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 export function esCarpetaReal(p) {
     try {
         return statSync(p).isDirectory();
@@ -38,15 +48,15 @@ const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, "
 function leerJson(d, p, nombre) {
     const leido = d.leerArchivoChico(p, TOPE_DEL_PACKAGE_JSON);
     if ("error" in leido) {
-        if (leido.error === "no existe")
+        if (leido.error === NO_LEIDO.noExiste)
             return { ok: false, noExiste: true };
-        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `No leo ${nombre}: ${limpio(leido.error)}.`) };
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `I can't read ${nombre}: ${limpio(leido.error)}.`) };
     }
     try {
         return { ok: true, valor: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(leido.bytes)) };
     }
     catch {
-        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `${nombre} no es JSON válido.`) };
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `${nombre} isn't valid JSON.`) };
     }
 }
 // Como lo resuelve Node desde la app (revisión externa, hallazgo 4): el primer `node_modules/@supcoflow/chat`
@@ -59,16 +69,16 @@ function paqueteInstalado(d, raiz, app, avisos) {
         const real = d.rutaReal(candidato);
         if (real !== null) {
             if (!adentro(raiz, real)) {
-                const aviso = `${path.relative(raiz, candidato)} apunta fuera del repo; no lo leo y anoto el chat instalado como null.`;
+                const aviso = `${path.relative(raiz, candidato)} points outside the repo; I don't read it and I record the installed chat as null.`;
                 avisos.push(aviso);
                 d.avisar(aviso);
                 return { ok: true, valor: null };
             }
-            const j = leerJson(d, real, `el package.json de ${PAQUETE_DEL_CHAT} instalado`);
+            const j = leerJson(d, real, `the installed package.json of ${PAQUETE_DEL_CHAT}`);
             if (j.ok)
                 return j;
             // Existía hace un instante: si ahora no está, tampoco se anota «no está».
-            return { ok: false, resultado: j.noExiste ? fallo(SALIDA.inesperado, "paquete_ilegible", `No leo el package.json de ${PAQUETE_DEL_CHAT} instalado.`) : j.resultado };
+            return { ok: false, resultado: j.noExiste ? fallo(SALIDA.inesperado, "paquete_ilegible", `I can't read the installed package.json of ${PAQUETE_DEL_CHAT}.`) : j.resultado };
         }
         if (dir === raiz || path.dirname(dir) === dir)
             return { ok: true, valor: null };
@@ -78,7 +88,7 @@ async function estadoDelArchivo(d, raizGit, existe) {
     const git = async (args) => {
         const r = await d.git(args, raizGit);
         if (r.codigo !== 0)
-            throw new Error(`git ${args[0]} falló; no escribo ${RUTA_DE_LA_INSTALACION} sin saber si tiene cambios.`);
+            throw new Error(`git ${args[0]} failed; I'm not writing ${RUTA_DE_LA_INSTALACION} without knowing whether it has changes.`);
         return r.stdout;
     };
     const lineas = (await git(["status", "--porcelain", "--ignored", "--", RUTA_DE_LA_INSTALACION])).split("\n").filter((l) => l.trim() !== "");
@@ -93,7 +103,7 @@ async function estadoDelArchivo(d, raizGit, existe) {
 // sale limpio de control y de secretos; el JSON nunca lo lleva.
 function diff(antes, despues) {
     if (antes === null)
-        return ["--- (no había archivo)", "+++ " + RUTA_DE_LA_INSTALACION, ...despues.trimEnd().split("\n").map((l) => "+ " + l)].join("\n");
+        return ["--- (there was no file)", "+++ " + RUTA_DE_LA_INSTALACION, ...despues.trimEnd().split("\n").map((l) => "+ " + l)].join("\n");
     const a = antes.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n").map(limpio);
     const b = despues.trimEnd().split("\n");
     const n = a.length, m = b.length;
@@ -101,7 +111,7 @@ function diff(antes, despues) {
     for (let i = n - 1; i >= 0; i--)
         for (let j = m - 1; j >= 0; j--)
             lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
-    const lineas = ["--- " + RUTA_DE_LA_INSTALACION + " (antes)", "+++ " + RUTA_DE_LA_INSTALACION];
+    const lineas = ["--- " + RUTA_DE_LA_INSTALACION + " (before)", "+++ " + RUTA_DE_LA_INSTALACION];
     let i = 0, j = 0;
     while (i < n || j < m) {
         if (i < n && j < m && a[i] === b[j])
@@ -113,34 +123,53 @@ function diff(antes, despues) {
     }
     return lineas.join("\n");
 }
-const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declarado ${x.chat.declarado ?? "—"} / instalado ${x.chat.instalado ?? "—"}`;
+const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declared ${x.chat.declarado ?? "—"} / installed ${x.chat.instalado ?? "—"}${x.archivo !== null ? `, file ${x.archivo}` : ""}`;
 export async function instalacionAnotar(d, flags) {
     if (flags.skill === null)
-        return fallo(SALIDA.entradaInvalida, "falta_skill", "Falta la versión de la skill: `supcoflow instalacion anotar --skill 0.1.0`.");
+        return fallo(SALIDA.entradaInvalida, "falta_skill", "The skill version is missing: `supcoflow install record --skill 0.1.0`.");
     if (!esSemver(flags.skill))
-        return fallo(SALIDA.entradaInvalida, "skill_invalida", "--skill va con una versión semver (por ejemplo 0.1.0).");
+        return fallo(SALIDA.entradaInvalida, "skill_invalida", "--skill goes with a semver version (for example 0.1.0).");
+    // El archivo del chat se mira antes de cualquier pedido: una ruta imposible no gasta una vuelta al motor.
+    let archivoPedido = null;
+    if (flags.file !== undefined && flags.file !== null) {
+        const v = validarElArchivoDelChat(flags.file);
+        if (!v.ok)
+            return fallo(SALIDA.entradaInvalida, "archivo_invalido", v.motivo);
+        archivoPedido = v.ruta;
+    }
     // ─── La raíz y la app, antes de cualquier pedido ───
     let raizGit;
+    let sinClon;
     try {
-        raizGit = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+        ({ raiz: raizGit, sinClon } = await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd }));
     }
     catch (e) {
         return resultadoDeFallo(e);
     }
     if (raizGit === null)
-        return fallo(SALIDA.entradaInvalida, "sin_clon", `No tengo el clon de ese repo acá, y ${RUTA_DE_LA_INSTALACION} va en el clon: parate en el clon del repo.`);
+        return fallo(SALIDA.entradaInvalida, "sin_clon", `${sinClon ?? "I don't have that repo's clone here."} ${RUTA_DE_LA_INSTALACION} goes in the repo's clone: stand in it.`);
     const raiz = d.rutaReal(raizGit);
     if (raiz === null)
-        return fallo(SALIDA.inesperado, "inesperado", "No pude resolver la raíz del repo.");
+        return fallo(SALIDA.inesperado, "inesperado", "I couldn't resolve the repo's root.");
     // `realpath` DESPUÉS de resolver: un `--app` que es un enlace hacia afuera tiene que quedar afuera (Review Focus 4).
     const app = d.rutaReal(path.resolve(raiz, flags.app ?? "."));
     if (app === null)
-        return fallo(SALIDA.entradaInvalida, "app_inexistente", "La carpeta de --app no existe (va relativa a la raíz del repo).");
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "The --app folder doesn't exist (it's relative to the repo root).");
     if (!adentro(raiz, app))
-        return fallo(SALIDA.entradaInvalida, "app_fuera_del_repo", "--app tiene que ser una carpeta dentro del repo (relativa a su raíz).");
+        return fallo(SALIDA.entradaInvalida, "app_fuera_del_repo", "--app has to be a folder inside the repo (relative to its root).");
     // Un archivo no es una app: sin esto, leer `<archivo>/package.json` daba ENOTDIR y salía `paquete_ilegible`.
     if (!d.esCarpeta(app))
-        return fallo(SALIDA.entradaInvalida, "app_inexistente", "--app tiene que ser una carpeta (la de la app), no un archivo.");
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "--app has to be a folder (the app's), not a file.");
+    // `--file`: ni un enlace simbólico ni un camino que pase por uno (saldría del repo sin que se vea). El archivo todavía
+    // puede no existir (con `--dry-run` se anota antes de escribirlo), pero ninguna carpeta del camino puede ser un enlace.
+    if (archivoPedido !== null) {
+        const partes = archivoPedido.split("/");
+        for (let i = 1; i <= partes.length; i++) {
+            if (d.esEnlace(path.join(raiz, ...partes.slice(0, i)))) {
+                return fallo(SALIDA.entradaInvalida, "archivo_invalido", `--file can't be (or go through) a symlink: ${partes.slice(0, i).join("/")} is one.`);
+            }
+        }
+    }
     // ─── Proyecto → configuración → package.json de la app → paquete instalado → armar ───
     const p = await proyectoDelRepo(d, flags);
     if (!p.ok)
@@ -152,32 +181,36 @@ export async function instalacionAnotar(d, flags) {
     catch (e) {
         return resultadoDeFallo(e);
     }
-    const deLaApp = leerJson(d, path.join(app, "package.json"), "el package.json de la app");
+    const deLaApp = leerJson(d, path.join(app, "package.json"), "the app's package.json");
     if (!deLaApp.ok && !deLaApp.noExiste)
         return deLaApp.resultado;
     const avisos = [];
     const instalado = paqueteInstalado(d, raiz, app, avisos);
     if (!instalado.ok)
         return instalado.resultado;
+    // ─── El archivo de ahora: se lee antes de armar, porque `--file` ausente conserva el `archivo` ya anotado ───
+    const archivo = path.join(raiz, RUTA_DE_LA_INSTALACION);
+    // Una `.supcoflow` que es un enlace hacia afuera: ni se lee (el diff mostraría un archivo de afuera) ni se escribe.
+    const carpeta = d.rutaReal(path.dirname(archivo));
+    if (carpeta !== null && !adentro(raiz, carpeta))
+        return fallo(SALIDA.inesperado, "inesperado", `${path.dirname(RUTA_DE_LA_INSTALACION)} isn't a folder of the repo (a symlink?); I'm not writing there.`);
+    const actual = d.leerArchivoChico(archivo, TOPE_DEL_ARCHIVO);
+    const existe = !("error" in actual) || actual.error !== NO_LEIDO.noExiste;
+    const antes = "bytes" in actual ? Buffer.from(actual.bytes).toString("utf8") : null;
+    // Re-correr sin `--file` no borra el archivo que ya se anotó; un v1 (sin `archivo`) da null, sin error.
+    const archivoDelChat = archivoPedido ?? archivoAnotado(antes);
     let x;
     try {
-        x = armarInstalacion({ skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion });
+        x = armarInstalacion({ skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion, archivo: archivoDelChat });
     }
     catch (e) {
         return resultadoDeFallo(e);
     }
     const nuevo = serializar(x);
     // ─── ¿Se puede escribir? ───
-    const archivo = path.join(raiz, RUTA_DE_LA_INSTALACION);
-    // Una `.supcoflow` que es un enlace hacia afuera: ni se lee (el diff mostraría un archivo de afuera) ni se escribe.
-    const carpeta = d.rutaReal(path.dirname(archivo));
-    if (carpeta !== null && !adentro(raiz, carpeta))
-        return fallo(SALIDA.inesperado, "inesperado", `${path.dirname(RUTA_DE_LA_INSTALACION)} no es una carpeta del repo (¿un enlace?); no escribo ahí.`);
-    const actual = d.leerArchivoChico(archivo, TOPE_DEL_ARCHIVO);
-    const existe = !("error" in actual) || actual.error !== "no existe";
-    const json = { ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, ...(avisos.length > 0 ? { avisos } : {}) };
+    const json = { ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, archivo: x.archivo, ...(avisos.length > 0 ? { avisos } : {}) };
     if ("bytes" in actual && Buffer.from(actual.bytes).equals(Buffer.from(nuevo, "utf8"))) {
-        return { codigo: SALIDA.ok, json: { ...json, ...(flags.dryRun ? { dry_run: true } : {}), sin_cambios: true }, texto: `${RUTA_DE_LA_INSTALACION} ya dice eso (${resumen(x)}); no lo toqué.` };
+        return { codigo: SALIDA.ok, json: { ...json, ...(flags.dryRun ? { dry_run: true } : {}), sin_cambios: true }, texto: `${RUTA_DE_LA_INSTALACION} already says that (${resumen(x)}); I didn't touch it.` };
     }
     let estado;
     try {
@@ -187,21 +220,20 @@ export async function instalacionAnotar(d, flags) {
         return resultadoDeFallo(e);
     }
     if (estado === "cambios_sin_commit") {
-        return fallo(SALIDA.haceFaltaUnaPersona, "cambios_sin_commit", `${RUTA_DE_LA_INSTALACION} tiene cambios sin commit (o se borró sin commit); no lo toqué. Commitealos o descartalos y volvé a correr.`);
+        return fallo(SALIDA.haceFaltaUnaPersona, "cambios_sin_commit", `${RUTA_DE_LA_INSTALACION} has uncommitted changes (or was deleted without a commit); I didn't touch it. Commit or discard them and run again.`);
     }
     if (estado === "archivo_no_versionado") {
-        return fallo(SALIDA.haceFaltaUnaPersona, "archivo_no_versionado", `Ya hay un ${RUTA_DE_LA_INSTALACION} que git no guarda (sin commit o ignorado); no lo pisé. Commitealo o borralo y volvé a correr.`);
+        return fallo(SALIDA.haceFaltaUnaPersona, "archivo_no_versionado", `There's already a ${RUTA_DE_LA_INSTALACION} that git doesn't track (uncommitted or ignored); I didn't overwrite it. Commit or delete it and run again.`);
     }
-    const antes = "bytes" in actual ? Buffer.from(actual.bytes).toString("utf8") : null;
-    const cambios = existe && antes === null ? `(el archivo anterior no se lee)\n${diff(null, nuevo)}` : diff(antes, nuevo);
+    const cambios = existe && antes === null ? `(the previous file can't be read)\n${diff(null, nuevo)}` : diff(antes, nuevo);
     if (flags.dryRun) {
-        return { codigo: SALIDA.ok, json: { ...json, dry_run: true, sin_cambios: false }, texto: `Con --dry-run no escribo; sin él anotaría (${resumen(x)}):\n${cambios}` };
+        return { codigo: SALIDA.ok, json: { ...json, dry_run: true, sin_cambios: false }, texto: `With --dry-run I don't write; without it I'd record (${resumen(x)}):\n${cambios}` };
     }
     try {
         d.escribir(archivo, nuevo);
     }
     catch {
-        return fallo(SALIDA.inesperado, "archivo_no_escrito", `No pude escribir ${RUTA_DE_LA_INSTALACION}. Volvé a correr \`supcoflow instalacion anotar\`.`);
+        return fallo(SALIDA.inesperado, "archivo_no_escrito", `I couldn't write ${RUTA_DE_LA_INSTALACION}. Run \`supcoflow install record\` again.`);
     }
-    return { codigo: SALIDA.ok, json: { ...json, sin_cambios: false }, texto: `Anoté ${RUTA_DE_LA_INSTALACION} (${resumen(x)}); commitealo cuando quieras.\n${cambios}` };
+    return { codigo: SALIDA.ok, json: { ...json, sin_cambios: false }, texto: `Recorded ${RUTA_DE_LA_INSTALACION} (${resumen(x)}); commit it whenever you like.\n${cambios}` };
 }