supcoflow 0.7.0 → 0.8.1

package/dist/flags-por-comando.js

@@ -1,30 +1,34 @@
 // Qué comandos aceptan cada flag que no es global. Un flag que no aplica sale 3 en vez de ignorarse:
-// un asistente que pasa `--repo` a `quien-soy` creería que preguntó por ese repo. Vive aparte de
-// `cli.ts` (que corre al importarse) para poder probarse sin lanzar el binario.
+// un asistente que pasa `--repo` a `whoami` creería que preguntó por ese repo. Vive aparte de
+// `cli.ts` (que corre al importarse) para poder probarse sin lanzar el binario. Los nombres de los
+// campos son los de `Flags`; los textos nombran los flags y comandos canónicos.
 const DE_CONFIGURAR_CON_REPO = [
-    "configuracion", "chat prender", "chat apagar", "chat marca", "chat logo", "sitios agregar", "sitios quitar",
-    "datos fijar", "politica fijar", "claves crear", "claves listar", "claves revocar",
-    "guia revisar", "guia publicar", "guia ver", "guia usar",
+    "config", "chat on", "chat off", "chat brand", "chat logo", "sites add", "sites remove",
+    "data set", "policy set", "keys create", "keys list", "keys revoke",
+    "guide check", "guide publish", "guide show", "guide use", "guide versions",
 ];
 export const FLAGS_POR_COMANDO = [
-    { flags: ["start"], comandos: ["login", "repo conectar"], texto: "--start es de `supcoflow login` y `supcoflow repo conectar`." },
-    { flags: ["wait"], comandos: ["login", "repo conectar", "probar"], texto: "--wait es de `supcoflow login`, `supcoflow repo conectar` y `supcoflow probar`." },
+    { flags: ["start"], comandos: ["login", "repo connect"], texto: "--start belongs to `supcoflow login` and `supcoflow repo connect`." },
+    { flags: ["wait"], comandos: ["login", "repo connect", "test"], texto: "--wait belongs to `supcoflow login`, `supcoflow repo connect` and `supcoflow test`." },
     {
-        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO, "widget", "instalacion anotar", "diagnosticar", "probar"],
-        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver`, `widget`, `instalacion anotar`, `diagnosticar`, `probar` y los comandos que configuran un proyecto (no de `catalogo`).",
+        flags: ["repo"], comandos: ["repo connect", "project create", "project show", ...DE_CONFIGURAR_CON_REPO, "widget", "install record", "diagnose", "test"],
+        texto: "--repo belongs to `supcoflow repo connect`, `project create|show`, `widget`, `install record`, `diagnose`, `test` and the commands that configure a project (not to `catalog`).",
     },
-    { flags: ["install", "test"], comandos: ["proyecto crear"], texto: "--install y --test son de `supcoflow proyecto crear`." },
-    { flags: ["sitio"], comandos: ["sitios agregar", "sitios quitar"], texto: "--sitio es de `supcoflow sitios agregar|quitar`." },
-    { flags: ["titulo", "saludo", "tema"], comandos: ["chat marca"], texto: "--titulo, --saludo y --tema son de `supcoflow chat marca`." },
-    { flags: ["archivo"], comandos: ["chat logo"], texto: "--archivo es de `supcoflow chat logo`." },
-    { flags: ["permitir"], comandos: ["datos fijar"], texto: "--permitir es de `supcoflow datos fijar`." },
-    { flags: ["modo"], comandos: ["politica fijar"], texto: "--modo es de `supcoflow politica fijar`." },
-    { flags: ["nombre", "guardarEn"], comandos: ["claves crear"], texto: "--nombre y --guardar-en son de `supcoflow claves crear`." },
-    { flags: ["origen"], comandos: ["guia usar"], texto: "--origen es de `supcoflow guia usar`." },
-    { flags: ["desdeGithub"], comandos: ["guia publicar"], texto: "--desde-github es de `supcoflow guia publicar`." },
-    { flags: ["id"], comandos: ["claves revocar"], texto: "--id es de `supcoflow claves revocar`." },
-    { flags: ["autorizoGasto", "mensaje", "prueba"], comandos: ["probar"], texto: "--autorizo-gasto, --mensaje y --prueba son de `supcoflow probar`." },
-    { flags: ["skill", "app"], comandos: ["instalacion anotar"], texto: "--skill y --app son de `supcoflow instalacion anotar`." },
+    { flags: ["install", "test"], comandos: ["project create"], texto: "--install and --test belong to `supcoflow project create`." },
+    { flags: ["site"], comandos: ["sites add", "sites remove"], texto: "--site belongs to `supcoflow sites add|remove`." },
+    { flags: ["title", "greeting", "theme"], comandos: ["chat brand"], texto: "--title, --greeting and --theme belong to `supcoflow chat brand`." },
+    { flags: ["file"], comandos: ["chat logo", "install record"], texto: "--file belongs to `supcoflow chat logo` and `supcoflow install record`." },
+    { flags: ["allow"], comandos: ["data set"], texto: "--allow belongs to `supcoflow data set`." },
+    { flags: ["mode"], comandos: ["policy set"], texto: "--mode belongs to `supcoflow policy set`." },
+    { flags: ["name", "saveTo"], comandos: ["keys create"], texto: "--name and --save-to belong to `supcoflow keys create`." },
+    { flags: ["source"], comandos: ["guide use"], texto: "--source belongs to `supcoflow guide use`." },
+    { flags: ["fromGithub"], comandos: ["guide publish"], texto: "--from-github belongs to `supcoflow guide publish`." },
+    { flags: ["id"], comandos: ["keys revoke"], texto: "--id belongs to `supcoflow keys revoke`." },
+    {
+        flags: ["authorizeSpend", "ceiling", "expectPolicy", "message", "testId"], comandos: ["test"],
+        texto: "--authorize-spend, --ceiling, --expect-policy, --message and --test-id belong to `supcoflow test`.",
+    },
+    { flags: ["skill", "app"], comandos: ["install record"], texto: "--skill and --app belong to `supcoflow install record`." },
 ];
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */
 export function flagQueNoAplica(comando, presentes) {

package/dist/guardado/archivo.js

@@ -21,7 +21,7 @@ export function almacenDeArchivo(ruta, fs) {
             v = undefined;
         }
         if (typeof v !== "object" || v === null || Array.isArray(v)) {
-            throw new Error(`No entiendo el archivo de credenciales ${ruta}; borralo y volvé a iniciar sesión.`);
+            throw new Error(`I don't understand the credentials file ${ruta}; delete it and log in again.`);
         }
         return v;
     }
@@ -44,7 +44,7 @@ export function almacenDeArchivo(ruta, fs) {
                 return null;
             const r = t[cuenta];
             if (!esRegistro(r))
-                throw new Error(`No entiendo el archivo de credenciales ${ruta}; borralo y volvé a iniciar sesión.`);
+                throw new Error(`I don't understand the credentials file ${ruta}; delete it and log in again.`);
             return { valor: r.valor, escritoEn: r.escritoEn };
         },
         async escribir(cuenta, r) {

package/dist/guardado/index.js

@@ -4,6 +4,10 @@ import path from "node:path";
 import { FalloDeLaTerminal, SALIDA } from "../contrato.js";
 import { LlaveroAusente, TECHO_DEL_LLAVERO_MS } from "./llavero.js";
 import { dentroDeUnWorkingTree } from "./repo.js";
+// Cómo se nombra cada fuente en un texto para la persona; el valor `fuente` del JSON sigue siendo el de arriba.
+export const NOMBRE_DE_LA_FUENTE = {
+    llavero: "the system keychain", archivo: "the credentials file", env: "SUPCOFLOW_TOKEN",
+};
 // La cuenta ES el origen de la API que emitió lo guardado (Review Focus 3): una clave acuñada por
 // un motor en `localhost` queda en otra cuenta que la de producción, y la terminal apuntada a
 // producción simplemente no la encuentra (sale 2) en vez de mandarla a un servidor que no la emitió.
@@ -71,8 +75,8 @@ export function crearGuardado(d) {
     }
     const leerCuenta = async (cuenta, queda) => (await leerCuentaCompleta(cuenta, queda)).mejor;
     const errorDeBorrado = (fallidos) => {
-        const donde = fallidos.map((n) => (n === "llavero" ? "del llavero del sistema" : `de ${d.rutaDelArchivo}`)).join(" ni ");
-        return new FalloDeLaTerminal(SALIDA.inesperado, "no_se_pudo_borrar", `No pude borrar la clave guardada ${donde}.`);
+        const donde = fallidos.map((n) => (n === "llavero" ? NOMBRE_DE_LA_FUENTE.llavero : d.rutaDelArchivo)).join(" or from ");
+        return new FalloDeLaTerminal(SALIDA.inesperado, "no_se_pudo_borrar", `I couldn't delete the saved key from ${donde}.`);
     };
     // El chequeo del repo va ANTES de escribir (Review Focus 1): una vez escrita, la clave ya está a
     // un `git add -A` de publicarse, y borrarla después no deshace un commit. Mira la ruta REAL además
@@ -81,10 +85,10 @@ export function crearGuardado(d) {
     async function escribirEnArchivo(cuenta, r, que) {
         const raiz = dentroDeUnWorkingTree(path.dirname(d.rutaDelArchivo), d.fs);
         if (raiz !== null) {
-            throw new FalloDeLaTerminal(SALIDA.inesperado, "destino_dentro_de_un_repo", `No guardo ${que} dentro de un repo de git (${raiz}). Usá el llavero del sistema o exportá SUPCOFLOW_TOKEN.`);
+            throw new FalloDeLaTerminal(SALIDA.inesperado, "destino_dentro_de_un_repo", `I won't save ${que} inside a git repo (${raiz}). Use the system keychain or export SUPCOFLOW_TOKEN.`);
         }
         await d.archivo.escribir(cuenta, r);
-        d.avisar(`No hay llavero del sistema: guardé ${que} en ${d.rutaDelArchivo} con permisos 0600.`);
+        d.avisar(`There is no system keychain: I saved ${que} in ${d.rutaDelArchivo} with 0600 permissions.`);
     }
     async function escribirCuenta(cuenta, valor, que, techoMs) {
         const queda = plazo(techoMs);
@@ -145,7 +149,7 @@ export function crearGuardado(d) {
             return { valor: mejor === null ? null : { clave: mejor.r.valor, fuente: mejor.fuente }, completa };
         },
         async guardarClave(origen, clave, techoMs) {
-            return { donde: await escribirCuenta(cuentaDeClave(origen), clave, "la clave", techoMs) };
+            return { donde: await escribirCuenta(cuentaDeClave(origen), clave, "the key", techoMs) };
         },
         async borrarClave(origen) {
             // Un borrado a medias de una clave no se informa como hecho: la que quedó sigue sirviendo.
@@ -174,7 +178,7 @@ export function crearGuardado(d) {
             }
         },
         async guardarPendiente(origen, p, techoMs) {
-            await escribirCuenta(cuentaDePendiente(origen), JSON.stringify(p), "el inicio de sesión en curso", techoMs);
+            await escribirCuenta(cuentaDePendiente(origen), JSON.stringify(p), "the login in progress", techoMs);
         },
         async borrarPendiente(origen, techoMs) {
             // Nunca lanza: un pendiente viejo es inofensivo (su device_code ya se consumió o vence en
@@ -217,7 +221,7 @@ export function crearGuardado(d) {
                 const r = { valor: JSON.stringify([...l.valor, clave]), escritoEn: d.ahora() };
                 if (a.nombre === "archivo") {
                     try {
-                        await escribirEnArchivo(cuenta, r, "las claves por revocar");
+                        await escribirEnArchivo(cuenta, r, "the keys to revoke");
                         return;
                     }
                     catch (e) {
@@ -229,7 +233,7 @@ export function crearGuardado(d) {
                 if ((await intentar(a, queda, (x, t) => x.escribir(cuenta, r, t))).estado === "ok")
                     return;
             }
-            throw new FalloDeLaTerminal(SALIDA.inesperado, "no_se_pudo_anotar", "No pude anotar la clave anterior como «por revocar» ni en el llavero ni en el archivo.");
+            throw new FalloDeLaTerminal(SALIDA.inesperado, "no_se_pudo_anotar", "I couldn't note down the previous key as \"to revoke\" in either the keychain or the file.");
         },
         // Quitar sólo achica la lista, así que no pasa por el control del repo: no agrega ningún secreto.
         // Un almacén presente que falla deja `completo = false`: la clave puede seguir anotada ahí, el

package/dist/guardado/llavero.js

@@ -9,7 +9,7 @@ export const TECHO_DEL_LLAVERO_MS = 5_000;
 // nada que borrar en él; uno que está y falla puede tener datos adentro.
 export class LlaveroAusente extends Error {
     constructor(bin) {
-        super(`No hay llavero del sistema (falta ${bin}).`);
+        super(`There is no system keychain (${bin} is missing).`);
         this.name = "LlaveroAusente";
     }
 }
@@ -26,14 +26,14 @@ function decodificar(s) {
         v = undefined;
     }
     if (!esRegistro(v))
-        throw new Error("El llavero devolvió algo que no entiendo.");
+        throw new Error("The keychain returned something I don't understand.");
     return { valor: v.valor, escritoEn: v.escritoEn };
 }
 // La cuenta viaja en una línea de `security -i`, que también parte por espacios y entiende comillas:
 // una cuenta con algo de eso se leería distinta de lo que se escribió. Un origen nunca lo tiene.
 function cuentaSegura(cuenta) {
     if (!/^[A-Za-z0-9:/.\[\]#_-]+$/.test(cuenta))
-        throw new Error("Cuenta del llavero inválida.");
+        throw new Error("Invalid keychain account.");
     return cuenta;
 }
 // La ruta ABSOLUTA: un `security` del PATH podría ser otro programa (un `node_modules/.bin`, un
@@ -79,10 +79,10 @@ export function almacenDeLlavero(plataforma, correr, existe = existsSync) {
         if (r.ausente)
             throw new LlaveroAusente(bin);
         if (r.vencido)
-            throw new Error(`El llavero no contestó en ${Math.round(techoMs / 1000)} s.`);
+            throw new Error(`The keychain did not respond within ${Math.round(techoMs / 1000)} s.`);
         return r;
     }
-    const fallo = (codigo) => new Error(`El llavero falló (código ${codigo}).`);
+    const fallo = (codigo) => new Error(`The keychain failed (code ${codigo}).`);
     return {
         nombre: "llavero",
         async leer(cuenta, techoMs = TECHO_DEL_LLAVERO_MS) {

package/dist/guardado/lugar.js

@@ -0,0 +1,63 @@
+// El prechequeo SIN ESCRITURAS de lo que guardar un registro necesita (1A.1, fricción 3): se llama antes del OK de gasto
+// para que la persona sepa ya si esta máquina va a poder guardar el pedido de la prueba, y no después. Mira lo mismo que
+// `persistir` (src/guardado/archivo.ts) va a pedirle al disco, y lo de git de la fricción 2c.
+//
+// Qué promete y qué no: «no se detectaron impedimentos» no es «se va a poder escribir». Un disco que se llena después, o
+// un cambio al mismo tiempo, no se pueden garantizar sin escribir. El guardado estricto, justo antes del POST, se queda.
+import path from "node:path";
+import { mirarProteccionDeGit, rutaReal } from "./repo.js";
+export async function revisarElLugar(d) {
+    const impedimentos = [];
+    const dir = path.dirname(d.ruta);
+    const nombre = path.basename(d.ruta);
+    const tmp = d.ruta + ".tmp";
+    let real;
+    try {
+        real = rutaReal(path.resolve(dir), d.fs);
+    }
+    catch {
+        // Un enlace roto en el camino: no se sabe dónde se escribiría, y `persistir` fallaría.
+        return [{ codigo: "ruta_irresoluble", detalle: `I can't tell where ${dir} really is (a broken symlink?).` }];
+    }
+    const carpeta = d.fs.estado(real);
+    if (carpeta.existe) {
+        if (carpeta.tipo !== "carpeta") {
+            impedimentos.push({ codigo: "carpeta_no_es_carpeta", detalle: `${dir} exists but isn't a folder.` });
+        }
+        else {
+            if (!carpeta.propio)
+                impedimentos.push({ codigo: "carpeta_ajena", detalle: `${dir} isn't yours, so I can't set its permissions to 0700.` });
+            if (!d.fs.puede(real, "escribir"))
+                impedimentos.push({ codigo: "carpeta_sin_permiso", detalle: `I can't write in ${dir}.` });
+        }
+    }
+    else {
+        // Todavía no existe: el ancestro más cercano que existe tiene que ser una carpeta donde se pueda crear.
+        let ancestro = path.dirname(real);
+        while (!d.fs.estado(ancestro).existe && path.dirname(ancestro) !== ancestro)
+            ancestro = path.dirname(ancestro);
+        const a = d.fs.estado(ancestro);
+        if (!a.existe || a.tipo !== "carpeta" || !d.fs.puede(ancestro, "escribir")) {
+            impedimentos.push({ codigo: "padre_sin_permiso", detalle: `${dir} doesn't exist and I can't create it: ${ancestro} isn't a folder I can write in.` });
+        }
+    }
+    const archivo = d.fs.estado(path.join(real, nombre));
+    if (archivo.existe) {
+        if (archivo.tipo !== "archivo")
+            impedimentos.push({ codigo: "archivo_no_comun", detalle: `${d.ruta} isn't a regular file.` });
+        else if (!d.fs.puede(path.join(real, nombre), "leer"))
+            impedimentos.push({ codigo: "archivo_ilegible", detalle: `I can't read ${d.ruta}.` });
+    }
+    else if (d.fs.existe(path.join(real, nombre))) {
+        impedimentos.push({ codigo: "archivo_no_comun", detalle: `${d.ruta} is a broken symlink.` });
+    }
+    // El `.tmp` se borra antes de escribir (`borrarSiExiste`, sin recursión): si es una carpeta, no se puede.
+    const temporal = d.fs.estado(path.join(real, nombre + ".tmp"));
+    if (temporal.existe && temporal.tipo === "carpeta") {
+        impedimentos.push({ codigo: "tmp_es_carpeta", detalle: `${tmp} is a folder: I remove that name before saving, and I can't remove a folder.` });
+    }
+    const git = await mirarProteccionDeGit({ dir, archivos: [nombre, nombre + ".tmp"], fs: d.fs, git: d.git });
+    if (!git.protegido)
+        impedimentos.push(git.impedimento);
+    return impedimentos;
+}

package/dist/guardado/protegido.js

@@ -0,0 +1,38 @@
+// El almacén de archivo de los dos registros de la terminal que PUEDEN vivir bajo una carpeta personal que es un repo
+// (`pruebas.json` e `idempotencia.json`; 1A.1, fricción 2c). Es un envoltorio fino: cada `escribir` y cada `borrar`
+// pasan por `asegurarProteccionDeGit` ANTES de tocar el disco, porque borrar una entrada reescribe el archivo entero
+// por su `.tmp`. Las credenciales no lo usan: dentro de un repo se siguen negando.
+import path from "node:path";
+import { asegurarProteccionDeGit } from "./repo.js";
+/** Git no garantiza que este archivo quede fuera del repo: no se escribió (ni se borró) nada. */
+export class SinProteccionDeGit extends Error {
+    impedimento;
+    constructor(impedimento) {
+        super(impedimento.detalle);
+        this.impedimento = impedimento;
+    }
+}
+export function almacenProtegido(base, d) {
+    const dir = path.dirname(d.ruta);
+    const archivos = [path.basename(d.ruta), path.basename(d.ruta) + ".tmp"];
+    async function proteger() {
+        const p = await asegurarProteccionDeGit({ dir, archivos, fs: d.fs, git: d.git });
+        if (!p.protegido)
+            throw new SinProteccionDeGit(p.impedimento);
+    }
+    return {
+        nombre: base.nombre,
+        leer: (cuenta, techoMs) => base.leer(cuenta, techoMs),
+        async escribir(cuenta, r, techoMs) {
+            await proteger();
+            await base.escribir(cuenta, r, techoMs);
+        },
+        async borrar(cuenta, techoMs) {
+            // Si no hay nada que borrar, `borrar` no reescribe nada: no hay nada que proteger.
+            if ((await base.leer(cuenta, techoMs)) === null)
+                return;
+            await proteger();
+            await base.borrar(cuenta, techoMs);
+        },
+    };
+}

package/dist/guardado/repo.js

@@ -33,3 +33,101 @@ export function dentroDeUnWorkingTree(dir, fs) {
     }
     return null;
 }
+const CONTENIDO_DEL_GITIGNORE = "# Written by supcoflow: nothing in this folder belongs in git.\n*\n";
+// La raíz del repo (si hay) de cada una de las dos rutas: la escrita y la real. Un tramo enlazado (`stow`)
+// puede hacer que sean dos repos distintos, y cualquiera de los dos publicaría el archivo.
+function raicesQueContienen(dir, fs) {
+    const escrita = path.resolve(dir);
+    const rutas = new Set([escrita, rutaReal(escrita, fs)]);
+    const raices = new Map();
+    for (const ruta of rutas) {
+        let actual = ruta;
+        for (;;) {
+            if (fs.existe(path.join(actual, ".git"))) {
+                raices.set(actual, [...(raices.get(actual) ?? []), ruta]);
+                break;
+            }
+            const padre = path.dirname(actual);
+            if (padre === actual)
+                break;
+            actual = padre;
+        }
+    }
+    return raices;
+}
+const sinProteger = (codigo, detalle) => ({ protegido: false, impedimento: { codigo, detalle } });
+function queHacer(raiz, archivo) {
+    const rel = path.relative(raiz, archivo);
+    return `Take it out of the repo with \`git -C ${raiz} rm --cached -- ${rel}\` or have git ignore it; I won't touch your repo myself.`;
+}
+async function mirar(d, conGitignore) {
+    let raices;
+    try {
+        raices = raicesQueContienen(d.dir, d.fs);
+    }
+    catch {
+        return sinProteger("ruta_irresoluble", `I can't tell where ${d.dir} really is (a broken symlink?).`);
+    }
+    for (const [raiz, carpetas] of raices) {
+        for (const carpeta of carpetas) {
+            const hayGitignore = conGitignore(carpeta);
+            for (const nombre of d.archivos) {
+                const archivo = path.join(carpeta, nombre);
+                if (hayGitignore) {
+                    // 0 = ignorado y no seguido; 1 = no lo es (o está seguido o agregado). Cualquier otra cosa (git ausente,
+                    // `fatal`, tiempo) es «no sé», y no saber no es «protegido».
+                    const r = await d.git(["check-ignore", "-q", "--", archivo], raiz);
+                    if (r.codigo === 1) {
+                        return sinProteger("git_no_lo_ignora", `Git doesn't ignore ${archivo} in the repo ${raiz} (it is tracked or staged, or a .gitignore doesn't cover it). ${queHacer(raiz, archivo)}`);
+                    }
+                    if (r.codigo !== 0)
+                        return sinProteger("git_no_contesta", `I couldn't ask git whether it ignores ${archivo} in the repo ${raiz}.`);
+                }
+                else {
+                    // Sin `.gitignore` todavía: se crearía uno con `*`, que ignora todo lo que no esté seguido ni en el índice.
+                    const r = await d.git(["ls-files", "--", archivo], raiz);
+                    if (r.codigo !== 0)
+                        return sinProteger("git_no_contesta", `I couldn't ask git whether it tracks ${archivo} in the repo ${raiz}.`);
+                    if (r.stdout.trim() !== "") {
+                        return sinProteger("git_lo_sigue", `Git tracks ${archivo} in the repo ${raiz}. ${queHacer(raiz, archivo)}`);
+                    }
+                }
+            }
+        }
+    }
+    return { protegido: true };
+}
+/** Sin escribir nada: lo mismo que `asegurarProteccionDeGit` va a comprobar, para avisar antes. */
+export function mirarProteccionDeGit(d) {
+    return mirar(d, (carpeta) => d.fs.existe(path.join(carpeta, ".gitignore")));
+}
+/**
+ * Antes de CADA escritura o borrado de un registro. Si la carpeta cae en un repo y no tiene `.gitignore`, crea
+ * uno con `*` (en exclusiva: si aparece otro al mismo tiempo no se pisa; y nunca se edita uno que ya estaba),
+ * y después le pregunta a git por cada archivo y su `.tmp`. Falla cerrada.
+ */
+export async function asegurarProteccionDeGit(d) {
+    let raices;
+    try {
+        raices = raicesQueContienen(d.dir, d.fs);
+    }
+    catch {
+        return sinProteger("ruta_irresoluble", `I can't tell where ${d.dir} really is (a broken symlink?).`);
+    }
+    if (raices.size === 0)
+        return { protegido: true };
+    const gitignore = path.join(path.resolve(d.dir), ".gitignore");
+    if (!d.fs.existe(gitignore)) {
+        try {
+            d.fs.crearDir(path.resolve(d.dir), 0o700);
+            d.fs.escribirExclusivo(gitignore, CONTENIDO_DEL_GITIGNORE, 0o600);
+        }
+        catch (e) {
+            // `EEXIST`: otro proceso lo creó entre medio; sirve igual, y no se toca.
+            if (e.code !== "EEXIST") {
+                return sinProteger("no_se_pudo_crear_gitignore", `I couldn't create ${gitignore} to keep this folder out of git.`);
+            }
+        }
+    }
+    return mirar(d, () => true);
+}

package/dist/guia.js

@@ -1,6 +1,8 @@
 // La guía del producto que vive en el repo del cliente. Sin dependencias: sólo `node:crypto`.
 import { createHash } from "node:crypto";
-export const RUTA_DE_LA_GUIA = ".supcoflow/guia.md";
+// El nombre canónico desde la 0.8.0; `guia.md` es el viejo y se sigue leyendo SÓLO si `guide.md` no existe.
+export const RUTA_DE_LA_GUIA = ".supcoflow/guide.md";
+export const RUTA_VIEJA_DE_LA_GUIA = ".supcoflow/guia.md";
 export const MAX_BYTES_DE_LA_GUIA = 64 * 1024;
 // La misma regla que el motor (`src/guia/formato.ts`), copiada a propósito y clavada con los vectores
 // de `test/vectores/huella.json` (idénticos en los dos repos). Se normaliza antes de hashear porque un

package/dist/idempotencia.js

@@ -3,9 +3,8 @@
 // reintento tiene que mandar la MISMA clave para que el motor devuelva lo que ya hizo en vez de
 // hacerlo dos veces. Por eso se escribe ANTES de devolverla, y sólo se olvida cuando el motor ya dio
 // un desenlace que no hace falta repetir.
-import path from "node:path";
 import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
-import { dentroDeUnWorkingTree } from "./guardado/repo.js";
+import { SinProteccionDeGit } from "./guardado/protegido.js";
 export function crearRegistroDeIdempotencia(d) {
     // Por origen, como la clave (un motor local y producción no comparten claves), y el alcance en
     // minúsculas: `D/r` y `d/r` son el mismo repo para GitHub y para el motor.
@@ -15,7 +14,7 @@ export function crearRegistroDeIdempotencia(d) {
     // repo) y el motor lo reusa. Una clave de consulta no tiene clave natural: sin la de idempotencia
     // guardada, el reintento tras una respuesta perdida crea OTRA fila. Mejor no mandar nada y decir qué
     // arreglar. Por eso, en estricto, cada «aviso y sigo» de abajo lanza.
-    const noGuardada = () => new FalloDeLaTerminal(SALIDA.inesperado, "idempotencia_no_guardada", `No pude guardar la clave de reintento en ${d.rutaDelArchivo}; sin ella, un reintento crearía otra clave. Revisá ese archivo (no puede estar dentro de un repo) y probá de nuevo.`);
+    const noGuardada = (causa) => new FalloDeLaTerminal(SALIDA.inesperado, "idempotencia_no_guardada", `I couldn't save the retry key in ${d.rutaDelArchivo}; without it, a retry would create another key. Check that file and try again.${causa instanceof SinProteccionDeGit ? ` ${causa.message}` : ""}`);
     return {
         async claveDe(operacion, alcance, opciones = {}) {
             const c = cuenta(operacion, alcance);
@@ -29,38 +28,25 @@ export function crearRegistroDeIdempotencia(d) {
                     throw noGuardada();
                 // Un archivo que no se entiende no se reescribe (perdería otras claves); se sigue sin guardar.
                 const nueva = d.generar();
-                d.avisar(`No pude leer ${d.rutaDelArchivo}: sigo con una clave de idempotencia sin guardar.`);
+                d.avisar(`I couldn't read ${d.rutaDelArchivo}: I'm going on with an idempotency key that isn't saved.`);
                 return nueva;
             }
             const nueva = d.generar();
             // Perder la clave no duplica nada: el motor reusa el proyecto por su repo. Por eso un destino
-            // dentro de un repo (misma regla que las credenciales: un `git add -A` la publicaría) o un disco
+            // dentro de un repo que git no garantiza que ignore (el almacén protegido, fricción 2c) o un disco
             // que falla avisan y siguen, en vez de frenar el comando.
-            // `realpath` lanza con un tramo que es un enlace roto (`~/.config/supcoflow` apuntando a un repo
-            // de dotfiles que ya no está): no saber dónde cae el destino es otro «no se puede guardar».
-            let raiz;
-            try {
-                raiz = dentroDeUnWorkingTree(path.dirname(d.rutaDelArchivo), d.fs);
-            }
-            catch {
-                if (opciones.estricta)
-                    throw noGuardada();
-                d.avisar(`No pude resolver la ruta de ${d.rutaDelArchivo}: sigo con una clave de idempotencia sin guardar.`);
-                return nueva;
-            }
-            if (raiz !== null) {
-                if (opciones.estricta)
-                    throw noGuardada();
-                d.avisar(`No guardo la clave de idempotencia dentro de un repo de git (${raiz}): un reintento mandará otra.`);
-                return nueva;
-            }
             try {
                 await d.almacen.escribir(c, { valor: nueva, escritoEn: d.ahora() });
             }
-            catch {
+            catch (e) {
                 if (opciones.estricta)
-                    throw noGuardada();
-                d.avisar(`No pude guardar la clave de idempotencia en ${d.rutaDelArchivo}: un reintento mandará otra.`);
+                    throw noGuardada(e);
+                if (e instanceof SinProteccionDeGit) {
+                    d.avisar(`I'm not saving the idempotency key in ${d.rutaDelArchivo}: a retry will send a different one. ${e.message}`);
+                }
+                else {
+                    d.avisar(`I couldn't save the idempotency key in ${d.rutaDelArchivo}: a retry will send a different one.`);
+                }
             }
             return nueva;
         },
@@ -80,8 +66,10 @@ export function crearRegistroDeIdempotencia(d) {
             try {
                 await d.almacen.borrar(cuenta(operacion, alcance));
             }
-            catch {
-                d.avisar(`No pude borrar la clave de idempotencia de ${d.rutaDelArchivo}.`);
+            catch (e) {
+                d.avisar(e instanceof SinProteccionDeGit
+                    ? `I didn't delete the idempotency key from ${d.rutaDelArchivo}, so as not to rewrite a file git doesn't ignore. ${e.message}`
+                    : `I couldn't delete the idempotency key from ${d.rutaDelArchivo}.`);
             }
         },
     };

package/dist/instalacion.js

@@ -1,4 +1,4 @@
-// `.supcoflow/instalacion.json` (bloque 6, decisión 3): con qué versiones se hizo la instalación, anotado en el
+// `.supcoflow/instalacion.json` (bloque 6, decisión 3; v2 en la 0.8.0): con qué versiones se hizo la instalación, anotado en el
 // repo de quien instala. Supcoflow no lo guarda ni lo ve. Puro: recibe lo ya leído y arma el archivo.
 //
 // El archivo queda en el repo y se commitea: un secreto acá se publica con el primer `push`. Por eso se arma con
@@ -13,7 +13,7 @@ export const esSemver = (s) => s.length <= 64 && SEMVER.test(s);
 const objeto = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? v : null);
 const entero = (v) => typeof v === "number" && Number.isInteger(v) && v >= 1;
 const ilegible = (message) => new FalloDeLaTerminal(SALIDA.inesperado, "paquete_ilegible", message);
-const inesperada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "configuracion_inesperada", `El motor contestó la configuración con ${que} que no entiendo; no anoto nada a medias. Probá de nuevo en un rato.`);
+const inesperada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "configuracion_inesperada", `The engine answered the configuration with ${que} I don't understand; I'm not recording anything halfway. Try again in a while.`);
 // Lo declarado en el `package.json` de la app lo escribió quien escribió el repo: puede ser un rango, un alias o
 // cualquier cosa. Se copia tal cual sólo si es texto imprimible y corto; si no, no se adivina (`paquete_ilegible`).
 // `taparSecretos` igual, por si alguien pegó una clave ahí: el archivo nuevo no la repite.
@@ -25,7 +25,7 @@ function declaradoEn(app) {
     if (v === undefined || v === null)
         return null;
     if (typeof v !== "string" || v.length === 0 || v.length > 200 || !/^[\x20-\x7e]+$/.test(v)) {
-        throw ilegible(`La versión de ${PAQUETE_DEL_CHAT} en el package.json de la app no se entiende; no la anoto.`);
+        throw ilegible(`The version of ${PAQUETE_DEL_CHAT} in the app's package.json isn't understandable; I'm not recording it.`);
     }
     return taparSecretos(v);
 }
@@ -35,7 +35,7 @@ function instaladoEn(paquete) {
         return null;
     const v = objeto(paquete)?.version;
     if (typeof v !== "string" || !esSemver(v))
-        throw ilegible(`El package.json de ${PAQUETE_DEL_CHAT} instalado no trae una versión que entienda.`);
+        throw ilegible(`The installed package.json of ${PAQUETE_DEL_CHAT} has no version I understand.`);
     return v;
 }
 function acuerdoDe(c) {
@@ -44,16 +44,16 @@ function acuerdoDe(c) {
     const a = objeto(c.acuerdo);
     // Ilegible es un estado conocido del motor (aplica cerrado), no «sin acuerdo»: anotarlo como null mentiría.
     if (a?.ilegible === true) {
-        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, "acuerdo_ilegible", "El acuerdo de datos está fijado pero no se lee: revisalo en la consola y volvé a correr.");
+        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, "acuerdo_ilegible", "The data agreement is set but can't be read: check it in the console and run again.");
     }
     if (a === null || !entero(a.version))
-        throw inesperada("un acuerdo");
+        throw inesperada("an agreement");
     return a.version;
 }
 function politicaDe(c) {
     const modo = objeto(c.politica)?.modo;
     if (modo !== "relevar" && modo !== "guardar")
-        throw inesperada("una política");
+        throw inesperada("a policy");
     return modo;
 }
 function guiaDe(c) {
@@ -62,24 +62,63 @@ function guiaDe(c) {
     const g = objeto(c.guia);
     if (g?.origen === "repo") {
         if (g.procedencia !== "terminal" && g.procedencia !== "github")
-            throw inesperada("una guía");
+            throw inesperada("a guide");
         if (g.commit !== null && (typeof g.commit !== "string" || !/^[0-9a-f]{40}$/.test(g.commit)))
-            throw inesperada("una guía");
+            throw inesperada("a guide");
         return { origen: "repo", procedencia: g.procedencia, commit: g.commit };
     }
     if (g?.origen === "agente" && entero(g.version))
         return { origen: "agente", version: g.version };
-    throw inesperada("una guía");
+    throw inesperada("a guide");
 }
 export function armarInstalacion(i) {
     return {
-        version: 1,
+        version: 2,
         skill: i.skill,
         terminal: i.terminal,
         chat: { declarado: declaradoEn(i.paqueteDeLaApp), instalado: instaladoEn(i.paqueteInstalado) },
         configuracion: { acuerdo_version: acuerdoDe(i.configuracion), politica: politicaDe(i.configuracion), guia: guiaDe(i.configuracion) },
+        archivo: i.archivo ?? null,
     };
 }
+// ─── El archivo del chat (`install record --file`) ───
+const MAX_LARGO_DEL_ARCHIVO = 300;
+// Pura: una ruta RELATIVA a la raíz del repo, sin `..`, sin ruta absoluta. Se devuelve normalizada (separador `/`, sin
+// `./` ni barras de más), que es como queda anotada. Que no sea un enlace simbólico lo mira el comando, con el disco.
+export function validarElArchivoDelChat(crudo) {
+    if (crudo.length === 0 || crudo.length > MAX_LARGO_DEL_ARCHIVO || /[\u0000-\u001f\u007f]/.test(crudo)) {
+        return { ok: false, motivo: `--file goes with a path of up to ${MAX_LARGO_DEL_ARCHIVO} printable characters.` };
+    }
+    if (crudo.startsWith("/") || crudo.startsWith("\\") || /^[A-Za-z]:/.test(crudo)) {
+        return { ok: false, motivo: "--file is a path relative to the repo root, not an absolute one." };
+    }
+    const partes = crudo.split(/[\\/]/).filter((x) => x !== "" && x !== ".");
+    if (partes.includes(".."))
+        return { ok: false, motivo: "--file can't go out of the repo: no `..` in the path." };
+    if (partes.length === 0)
+        return { ok: false, motivo: "--file is the chat file, not a folder: say its path." };
+    return { ok: true, ruta: partes.join("/") };
+}
+/** El `archivo` anotado en un `instalacion.json` ya existente: v1 y cualquier cosa ilegible o inválida dan null (nunca un error). */
+export function archivoAnotado(texto) {
+    if (texto === null)
+        return null;
+    let v;
+    try {
+        v = JSON.parse(texto);
+    }
+    catch {
+        return null;
+    }
+    // AD9: un v1 se reconoce por `version: 1` (lo escribe la terminal 0.7.0) y no tiene archivo, aunque el campo aparezca.
+    if (objeto(v)?.version === 1)
+        return null;
+    const a = objeto(v)?.archivo;
+    if (typeof a !== "string")
+        return null;
+    const r = validarElArchivoDelChat(a);
+    return r.ok && r.ruta === a ? a : null;
+}
 // El orden de las claves es el de `armarInstalacion`: el mismo estado da los mismos bytes, y eso es `sin_cambios`.
 export function serializar(x) {
     return JSON.stringify(x, null, 2) + "\n";

package/dist/lectura.js

@@ -0,0 +1,10 @@
+// Por qué `leerArchivoChico` no pudo leer un archivo. Son frases sueltas que van después de «I can't read X:», y
+// los comandos comparan contra estas constantes (nunca contra el texto a mano).
+export const NO_LEIDO = {
+    noExiste: "it doesn't exist",
+    esUnEnlace: "it's a symlink",
+    noSePudoAbrir: "it couldn't be opened",
+    noEsComun: "it isn't a regular file",
+    demasiadoGrande: "it's too large",
+    noSePudoLeer: "it couldn't be read",
+};