supcoflow 0.8.0 → 0.9.0

package/dist/entorno.js

@@ -2,7 +2,7 @@
 // demás recibe estas piezas inyectadas y se prueba con dobles; acá sólo se enchufan.
 import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeSync, } from "node:fs";
+import { accessSync, chmodSync, closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, statSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeSync, } from "node:fs";
 import { NO_LEIDO } from "./lectura.js";
 import { homedir, hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -12,6 +12,8 @@ import { esCarpetaReal, esEnlaceReal, rutaRealOEnNada } from "./comandos/instala
 import { DESCRIPCION } from "./comandos/describir.js";
 import { almacenDeArchivo } from "./guardado/archivo.js";
 import { crearGuardado } from "./guardado/index.js";
+import { almacenProtegido } from "./guardado/protegido.js";
+import { revisarElLugar } from "./guardado/lugar.js";
 import { almacenDeLlavero } from "./guardado/llavero.js";
 import { crearGuardaDeSecretos } from "./secreto-a-archivo.js";
 import { crearRegistroDeIdempotencia } from "./idempotencia.js";
@@ -68,6 +70,29 @@ export const fsReal = {
         }
     },
 };
+// Lo que el prechequeo de la máquina (src/guardado/lugar.ts) ve del disco, sin escribir. `estado` sigue los enlaces (`stat`): un
+// enlace roto es «no existe» para él, y `existe` (que es `lstat`) lo distingue.
+export const fsDelLugarReal = {
+    ...fsReal,
+    estado(p) {
+        try {
+            const st = statSync(p);
+            return { existe: true, tipo: st.isDirectory() ? "carpeta" : st.isFile() ? "archivo" : "otro", propio: typeof process.getuid !== "function" || st.uid === process.getuid() };
+        }
+        catch {
+            return { existe: false };
+        }
+    },
+    puede(p, que) {
+        try {
+            accessSync(p, que === "leer" ? constants.R_OK : constants.W_OK | constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
 // El candado de `claves crear` (src/candado.ts). `wx` es la exclusión: SÓLO `EEXIST` es «ya hay uno»;
 // cualquier otro error (permisos, disco) se relanza y sale `no_disponible`, nunca «ocupado». La lectura no
 // sigue enlaces: un `.lock` que alguien cambió por un enlace no se lee como si fuera el nuestro.
@@ -396,27 +421,31 @@ export function entornoReal(env = process.env) {
     // Al lado de las credenciales y con el mismo almacén (carpeta 0700, archivo 0600, `.tmp` en
     // exclusiva): nunca dentro del repo donde se corre el comando, que la publicaría con un `git add -A`.
     const rutaDeIdempotencia = join(dirname(rutaDelArchivo), "idempotencia.json");
+    // Estos dos registros (y sólo estos) pueden vivir bajo una carpeta personal que es un repo de git: el almacén
+    // protegido comprueba con git, antes de cada escritura y cada borrado, que los deja afuera del repo.
+    const protegido = (ruta) => almacenProtegido(almacenDeArchivo(ruta, fsReal), { ruta, fs: fsReal, git: gitReal });
     const idempotencia = crearRegistroDeIdempotencia({
         origen: api.origin,
-        almacen: almacenDeArchivo(rutaDeIdempotencia, fsReal),
+        almacen: protegido(rutaDeIdempotencia),
         rutaDelArchivo: rutaDeIdempotencia,
-        fs: fsReal,
         generar: randomUUID,
         ahora: Date.now,
         avisar,
     });
-    // El pedido de `probar` (intento + última prueba), con el mismo almacén y la misma regla: fuera de un repo.
+    // El pedido de `probar` (intento + última prueba), con el mismo almacén protegido.
     const rutaDePruebas = join(dirname(rutaDelArchivo), "pruebas.json");
     const pruebas = crearRegistroDePruebas({
-        origen: api.origin, almacen: almacenDeArchivo(rutaDePruebas, fsReal), rutaDelArchivo: rutaDePruebas, fs: fsReal, ahora: Date.now, avisar,
+        origen: api.origin, almacen: protegido(rutaDePruebas), rutaDelArchivo: rutaDePruebas, ahora: Date.now, avisar,
+        revisarElLugar: () => revisarElLugar({ ruta: rutaDePruebas, fs: fsDelLugarReal, git: gitReal }),
     });
     const dormir = (ms) => new Promise((r) => setTimeout(r, ms));
     const cwd = process.cwd();
     // Los candados de `claves crear` viven al lado de las credenciales, nunca en un repo.
     const candados = crearCandados(fsDelCandadoReal, join(dirname(rutaDelArchivo), "candados"), process.pid, procesoVivo);
     const secretos = crearGuardaDeSecretos(fsDeSecretosReal);
+    // `archivos`: `proyectoDelRepo` lee `.supcoflow/proyecto.json` del clon con él (fricción 6).
     const configurarEnElMotor = {
-        api, guardado, git: gitReal, cwd, avisar,
+        api, guardado, git: gitReal, cwd, avisar, archivos: archivosDelRepo(avisar),
         buscarProyecto: (a, clave, repo) => buscarProyecto(a, clave, repo, fetch),
         leerConfiguracion: (a, clave, id) => leerConfiguracion(a, clave, id, fetch),
         configurar: (a, clave, ruta, cuerpo, extra) => configurar(a, clave, ruta, cuerpo, fetch, extra),
@@ -454,6 +483,7 @@ export function entornoReal(env = process.env) {
         proyecto: {
             api, guardado, git: gitReal, cwd, idempotencia, archivos: archivosDelRepo(avisar), avisar,
             buscarProyecto: (a, clave, repo) => buscarProyecto(a, clave, repo, fetch),
+            quienSoy: (a, clave) => quienSoy(a, clave, fetch),
             ultimaConexion: (a, clave, repo, plazoMs) => ultimaConexion(a, clave, repo, fetch, plazoMs),
             crearProyecto: (a, clave, conexionId, cuerpo, key) => crearProyecto(a, clave, conexionId, cuerpo, key, fetch),
             leerProyecto: (a, clave, id) => leerProyecto(a, clave, id, fetch),
@@ -476,9 +506,9 @@ export function entornoReal(env = process.env) {
             idempotencia, candados, secretos,
         },
         widget: {
-            api, guardado, git: gitReal, cwd,
+            api, guardado, git: gitReal, cwd, archivos: archivosDelRepo(avisar),
             buscarProyecto: configurarEnElMotor.buscarProyecto,
-            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch),
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch, avisar),
         },
         // La versión que se anota es la de `describir` (pinzada contra package.json por test): una sola fuente
         // para lo que la terminal dice de sí misma.
@@ -489,9 +519,17 @@ export function entornoReal(env = process.env) {
             terminal: DESCRIPCION.version,
         },
         prueba: {
-            api, guardado, git: gitReal, cwd, avisar, pruebas, generar: randomUUID, ahora: Date.now, dormir, tramoMs,
+            api, guardado, git: gitReal, cwd, avisar, archivos: archivosDelRepo(avisar), pruebas, generar: randomUUID, ahora: Date.now, dormir, tramoMs,
             buscarProyecto: configurarEnElMotor.buscarProyecto,
             leerDiagnostico: (a, clave, id) => leerDiagnostico(a, clave, id, fetch),
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch, avisar),
+            existe: (p) => { try {
+                lstatSync(p);
+                return true;
+            }
+            catch {
+                return false;
+            } },
             pedirPrueba: (a, clave, id, intento) => pedirPrueba(a, clave, id, intento, fetch),
             leerPrueba: (a, clave, id, pruebaId, plazoMs) => leerPrueba(a, clave, id, pruebaId, fetch, plazoMs),
         },

package/dist/flags-por-comando.js

@@ -28,8 +28,12 @@ export const FLAGS_POR_COMANDO = [
         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`." },
+    { flags: ["skill", "app", "shape"], comandos: ["install record"], texto: "--skill, --app and --shape belong to `supcoflow install record`." },
 ];
+/** `--file` se repite sólo en `install record` (la interfaz propia vive en varios archivos); en los demás va una vez. */
+export function archivosDeMas(comando, cuantos) {
+    return cuantos > 1 && comando !== "install record" ? "--file goes once, with a value. Try `supcoflow --help`." : null;
+}
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */
 export function flagQueNoAplica(comando, presentes) {
     for (const regla of FLAGS_POR_COMANDO) {

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/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", `I couldn't save the retry key in ${d.rutaDelArchivo}; without it, a retry would create another key. Check that file (it can't be inside a repo) and try again.`);
+    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);
@@ -34,33 +33,20 @@ export function crearRegistroDeIdempotencia(d) {
             }
             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(`I couldn't resolve the path of ${d.rutaDelArchivo}: I'm going on with an idempotency key that isn't saved.`);
-                return nueva;
-            }
-            if (raiz !== null) {
-                if (opciones.estricta)
-                    throw noGuardada();
-                d.avisar(`I'm not saving the idempotency key inside a git repo (${raiz}): a retry will send a different one.`);
-                return nueva;
-            }
             try {
                 await d.almacen.escribir(c, { valor: nueva, escritoEn: d.ahora() });
             }
-            catch {
+            catch (e) {
                 if (opciones.estricta)
-                    throw noGuardada();
-                d.avisar(`I couldn't save the idempotency key in ${d.rutaDelArchivo}: a retry will send a different one.`);
+                    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(`I couldn't delete the idempotency key from ${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; v2 en la 0.8.0): 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; v3 en la 0.9.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
@@ -7,9 +7,22 @@
 import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
 export const RUTA_DE_LA_INSTALACION = ".supcoflow/instalacion.json";
 export const PAQUETE_DEL_CHAT = "@supcoflow/chat";
+export const FORMAS = ["widget", "interfaz_propia"];
+export const MAX_ARCHIVOS_ANOTADOS = 20;
 // SemVer 2.0 tal cual, con tope de largo: la versión de la skill la escribe un asistente y queda en el repo.
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 export const esSemver = (s) => s.length <= 64 && SEMVER.test(s);
+/** Compara `major.minor.patch` número a número (1.10.0 > 1.9.0); lo que sigue al guion (prerelease) o al `+` no cuenta. */
+export function compararSemver(a, b) {
+    const partes = (v) => v.split(/[-+]/)[0].split(".").map(Number);
+    const [x, y] = [partes(a), partes(b)];
+    for (let i = 0; i < 3; i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
 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);
@@ -71,14 +84,26 @@ function guiaDe(c) {
         return { origen: "agente", version: g.version };
     throw inesperada("a guide");
 }
+// El `contract.json` del paquete instalado (T1 del sdk): sólo se copia su `version`, nunca el resto. Ausente es null (un
+// paquete anterior al contrato); presente sin una versión que se entienda NO es null: diría que no hay contrato.
+function contratoDe(contrato) {
+    if (contrato === null || contrato === undefined)
+        return null;
+    const v = objeto(contrato)?.version;
+    if (typeof v !== "string" || !esSemver(v))
+        throw ilegible(`The contract.json of ${PAQUETE_DEL_CHAT} has no version I understand.`);
+    return v;
+}
 export function armarInstalacion(i) {
     return {
-        version: 2,
+        version: 3,
         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,
+        forma: i.forma ?? null,
+        archivos: [...(i.archivos ?? [])],
+        contrato: contratoDe(i.contrato),
     };
 }
 // ─── El archivo del chat (`install record --file`) ───
@@ -99,25 +124,73 @@ export function validarElArchivoDelChat(crudo) {
         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) {
+const SIN_NADA = { forma: null, archivos: [], contrato: null };
+// Una lista de rutas anotadas: cada una tiene que ser válida Y estar ya normalizada (es como la escribe esta terminal); lo
+// que no, se descarta de a una, sin error. Sin repetidas y con tope.
+function rutasAnotadas(v) {
+    if (!Array.isArray(v))
+        return [];
+    const rutas = [];
+    for (const a of v) {
+        if (typeof a !== "string")
+            continue;
+        const r = validarElArchivoDelChat(a);
+        if (r.ok && r.ruta === a && !rutas.includes(a) && rutas.length < MAX_ARCHIVOS_ANOTADOS)
+            rutas.push(a);
+    }
+    return rutas;
+}
+/**
+ * Lo que un `instalacion.json` ya existente dice de la forma, los archivos y el contrato. v1 y cualquier cosa ilegible o inválida
+ * dan «nada»; una versión que esta terminal no conoce (4 o más) tampoco se adivina. Nunca un error.
+ */
+export function leerInstalacionAnotada(texto) {
     if (texto === null)
-        return null;
+        return { estado: "ausente" };
     let v;
     try {
         v = JSON.parse(texto);
     }
     catch {
-        return null;
+        return { estado: "ilegible" };
     }
-    // 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;
+    const o = objeto(v);
+    if (o === null)
+        return { estado: "ilegible" };
+    // Antes de la 0.9.0 la única forma que existía era el widget: una v1 o una v2 son un widget, con el archivo que la v2 anotó (si lo
+    // anotó; la v1 no tiene archivo aunque el campo aparezca).
+    if (o.version === 1)
+        return { estado: "leida", forma: "widget", archivos: [], contrato: null };
+    if (o.version === 2) {
+        const a = typeof o.archivo === "string" ? validarElArchivoDelChat(o.archivo) : null;
+        return { estado: "leida", forma: "widget", archivos: a !== null && a.ok && a.ruta === o.archivo ? [a.ruta] : [], contrato: null };
+    }
+    if (o.version === 3) {
+        const forma = FORMAS.find((f) => f === o.forma) ?? null;
+        const contrato = typeof o.contrato === "string" && esSemver(o.contrato) ? o.contrato : null;
+        return { estado: "leida", forma, archivos: rutasAnotadas(o.archivos), contrato };
+    }
+    if (typeof o.version === "number" && Number.isInteger(o.version) && o.version > 3)
+        return { estado: "mas_nueva" };
+    return { estado: "leida", ...SIN_NADA };
+}
+export function anotadoEn(texto) {
+    const l = leerInstalacionAnotada(texto);
+    return l.estado === "leida" ? { forma: l.forma, archivos: l.archivos, contrato: l.contrato } : SIN_NADA;
+}
+/** Valida y normaliza la lista de `--file`: cada ruta con `validarElArchivoDelChat`, sin repetidas, con tope. */
+export function validarLosArchivos(crudos) {
+    const rutas = [];
+    for (const crudo of crudos) {
+        const r = validarElArchivoDelChat(crudo);
+        if (!r.ok)
+            return r;
+        if (!rutas.includes(r.ruta))
+            rutas.push(r.ruta);
+    }
+    if (rutas.length > MAX_ARCHIVOS_ANOTADOS)
+        return { ok: false, motivo: `--file goes up to ${MAX_ARCHIVOS_ANOTADOS} times: the files of the chat, not the whole app.` };
+    return { ok: true, rutas };
 }
 // 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) {

package/dist/pruebas-guardadas.js

@@ -14,9 +14,8 @@
 //
 // Estricto en todo, como `claves crear` en el registro de idempotencia: una prueba no tiene clave natural
 // del lado de la terminal, así que mandar sin el intento guardado arriesga una segunda prueba (que gasta).
-import path from "node:path";
 import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
-import { dentroDeUnWorkingTree } from "./guardado/repo.js";
+import { SinProteccionDeGit } from "./guardado/protegido.js";
 function esIntento(v) {
     if (typeof v !== "object" || v === null)
         return false;
@@ -28,7 +27,7 @@ export function crearRegistroDePruebas(d) {
     // Por origen, como la clave y el registro de idempotencia: un motor local (o el proxy de P4) y
     // producción no comparten intentos. Cambiar de origen entre dos comandos es otra clave.
     const cuenta = (proyectoId) => `${d.origen}#prueba#${proyectoId}`;
-    const noGuardada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "prueba_no_guardada", `I couldn't ${que} ${d.rutaDelArchivo}; without that, a retry could ask for another test (and spend twice). Check that file (it can't be inside a repo) and try again.`);
+    const noGuardada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "prueba_no_guardada", `I couldn't ${que} ${d.rutaDelArchivo}; without that, a retry could ask for another test (and spend twice). Check that file and try again.`);
     async function leer(proyectoId) {
         let crudo;
         try {
@@ -58,18 +57,6 @@ export function crearRegistroDePruebas(d) {
         };
     }
     async function escribir(proyectoId, g) {
-        // Misma regla que las credenciales: un destino dentro de un repo se publicaría con un `git add -A`.
-        // No saber dónde cae (un enlace roto) es otro «no se puede guardar».
-        let raiz;
-        try {
-            raiz = dentroDeUnWorkingTree(path.dirname(d.rutaDelArchivo), d.fs);
-        }
-        catch {
-            throw noGuardada("resolve the path of");
-        }
-        if (raiz !== null) {
-            throw new FalloDeLaTerminal(SALIDA.inesperado, "prueba_no_guardada", `I'm not saving the test request inside a git repo (${raiz}); without saving it I won't send it. Point XDG_CONFIG_HOME outside a repo.`);
-        }
         const valor = JSON.stringify({
             intento: g.intento === null
                 ? null
@@ -79,12 +66,37 @@ export function crearRegistroDePruebas(d) {
         try {
             await d.almacen.escribir(cuenta(proyectoId), { valor, escritoEn: d.ahora() });
         }
-        catch {
+        catch (e) {
+            // El almacén protegido no escribe dentro de un repo si git no garantiza que lo deja afuera (fricción 2c):
+            // el mensaje dice qué archivo, qué repo y qué hacer.
+            if (e instanceof SinProteccionDeGit) {
+                throw new FalloDeLaTerminal(SALIDA.inesperado, "prueba_no_guardada", `I'm not saving the test request in ${d.rutaDelArchivo}; without saving it I won't send it. ${e.message}`);
+            }
             throw noGuardada("save to");
         }
     }
+    async function revisar(proyectoId) {
+        const impedimentos = [];
+        try {
+            impedimentos.push(...(await d.revisarElLugar?.() ?? []));
+        }
+        catch {
+            impedimentos.push({ codigo: "no_se_pudo_revisar", detalle: `I couldn't check whether ${d.rutaDelArchivo} can be saved.` });
+        }
+        let intentoPendiente = null;
+        try {
+            const { intento } = await leer(proyectoId);
+            if (intento !== null)
+                intentoPendiente = { techoUsd: intento.techoUsd, politica: intento.politicaEsperada };
+        }
+        catch {
+            impedimentos.push({ codigo: "archivo_ilegible", detalle: `I can't read or understand ${d.rutaDelArchivo}.` });
+        }
+        return { maquina: { ok: impedimentos.length === 0, impedimentos }, intentoPendiente };
+    }
     return {
         leer,
+        revisar,
         async abrir(proyectoId, intento) {
             const antes = await leer(proyectoId);
             await escribir(proyectoId, { intento, ultima: antes.ultima });