supcoflow 0.1.0 → 0.5.0

package/dist/entorno.js

@@ -1,13 +1,17 @@
 // Lo único que toca el mundo de verdad: el proceso, el disco, el llavero, la red y el reloj. Todo lo
 // demás recibe estas piezas inyectadas y se prueba con dobles; acá sólo se enchufan.
-import { spawn } from "node:child_process";
-import { chmodSync, closeSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeSync } from "node:fs";
+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 { homedir, hostname } from "node:os";
-import { join } from "node:path";
-import { canjear, pedirCodigo, quienSoy, revocarPropia, urlDeLaApi } from "./api.js";
+import { basename, dirname, join } from "node:path";
+import { buscarProyecto, canjear, configurar, crearConexion, crearProyecto, elegirOrigen, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerGuia, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, publicarGuia, revisarGuia, } from "./api.js";
+import { crearCandados } from "./candado.js";
 import { almacenDeArchivo } from "./guardado/archivo.js";
 import { crearGuardado } from "./guardado/index.js";
 import { almacenDeLlavero } from "./guardado/llavero.js";
+import { crearGuardaDeSecretos } from "./secreto-a-archivo.js";
+import { crearRegistroDeIdempotencia } from "./idempotencia.js";
 import { TRAMO_MAXIMO_MS } from "./sondeo.js";
 // El `.tmp` se crea en exclusiva (`wx`: falla si quedó algo, enlace incluido, en vez de escribir a
 // través de él) y el `fchmod` va aparte porque el modo de `open` pasa por la umask del proceso.
@@ -60,6 +64,121 @@ export const fsReal = {
         }
     },
 };
+// 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.
+export const fsDelCandadoReal = {
+    // Se escribe completo en un temporal de la misma carpeta y se PUBLICA con `link`, que falla con EEXIST si
+    // ya hay uno: con `wx` directo, otro proceso podía leer el `.lock` recién creado y todavía vacío, y
+    // informar `candado_abandonado` de un candado vivo. Así el `.lock` nunca se ve sin contenido.
+    crearExclusivo(p, contenido, modo) {
+        const tmp = `${p}.${randomUUID()}.tmp`;
+        try {
+            const fd = openSync(tmp, "wx", modo);
+            try {
+                fchmodSync(fd, modo);
+                writeSync(fd, contenido);
+            }
+            finally {
+                closeSync(fd);
+            }
+            linkSync(tmp, p);
+            return true;
+        }
+        catch (e) {
+            if (e.code === "EEXIST")
+                return false;
+            throw e;
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    },
+    leer(p) {
+        try {
+            const fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                return readFileSync(fd, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch {
+            return null;
+        }
+    },
+    borrar: (p) => rmSync(p, { force: true }),
+    crearDir: (p, modo) => void mkdirSync(p, { recursive: true, mode: modo }),
+};
+// ¿Sigue vivo el dueño de un candado? `kill(pid, 0)` no manda nada: sólo pregunta. `EPERM` es «existe pero
+// es de otro usuario»: vivo. Sólo `ESRCH` (no existe) lo da por muerto.
+export function procesoVivo(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== "ESRCH";
+    }
+}
+// El destino del secreto de `claves crear` (src/secreto-a-archivo.ts): el `fsReal` de siempre más una
+// lectura que no sigue un enlace en el último tramo (`O_NOFOLLOW` → `ELOOP`), no se cuelga en un FIFO y
+// tiene tope. Sólo archivos comunes.
+function leerSinSeguir(p, tope) {
+    let fd;
+    try {
+        fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return { tipo: "ausente" };
+        // macOS y Linux dan `ELOOP` al abrir un enlace con O_NOFOLLOW; algunos BSD, `EMLINK`.
+        return code === "ELOOP" || code === "EMLINK" ? { tipo: "enlace" } : { tipo: "ilegible" };
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return { tipo: "ilegible" };
+        const buf = Buffer.alloc(tope + 1);
+        let n = 0;
+        for (;;) {
+            const leidos = readSync(fd, buf, n, buf.length - n, null);
+            if (leidos === 0)
+                break;
+            n += leidos;
+            if (n > tope)
+                return { tipo: "ilegible" };
+        }
+        return { tipo: "contenido", texto: buf.subarray(0, n).toString("utf8") };
+    }
+    catch {
+        return { tipo: "ilegible" };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// `link` es el idioma del candado (arriba): crea el nombre sólo si no existe y falla con EEXIST si sí, sin
+// ventana entre mirar y escribir. El temporal queda con dos nombres hasta que `guardar` lo borra.
+// Un disco sin enlaces duros (FAT, exFAT, SMB) no da EEXIST sino EPERM, ENOTSUP/EOPNOTSUPP o ENOSYS según
+// el sistema: se informa aparte para no decirle a la persona «¿tenés permiso?» cuando el problema es el disco.
+const SIN_ENLACES = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EXDEV"]);
+function publicarSinPisar(tmp, destino) {
+    try {
+        linkSync(tmp, destino);
+        return "publicado";
+    }
+    catch (e) {
+        const code = e.code ?? "";
+        if (code === "EEXIST")
+            return "existe";
+        if (SIN_ENLACES.has(code))
+            return "sin_enlaces";
+        throw e;
+    }
+}
+export const fsDeSecretosReal = { ...fsReal, leerSinSeguir, publicarSinPisar };
 // Para hablar con `security`/`secret-tool`. stderr se captura sólo como señal (¿dijo algo?: es lo
 // que separa «no encontrado» de «sin D-Bus» en `secret-tool`), recortado, y nunca se muestra ni se
 // registra: podría traer algo del secreto. Al techo el hijo se mata con SIGKILL (un llavero bloqueado no atiende un SIGTERM) y se
@@ -108,6 +227,150 @@ export const correrReal = (bin, args, stdin, techoMs) => new Promise((resolve) =
     hijo.stdin.on("error", () => { });
     hijo.stdin.end(stdin ?? undefined);
 });
+// `git` con entorno mínimo (sólo PATH): ni GIT_DIR ni GIT_CONFIG del shell desvían la lectura, y
+// SUPCOFLOW_TOKEN no le llega. Un git ausente (ENOENT) es «sin git», no un fallo. El plazo es parámetro para no
+// duplicar la función: lo que git imprima nunca sale a la terminal, sólo el código y el stdout.
+const gitConPlazo = (plazoMs) => (args, cwd) => new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: plazoMs, env: { PATH: process.env.PATH ?? "" } }, (e, stdout) => {
+        if (!e)
+            return resolve({ codigo: 0, stdout: String(stdout) });
+        const codigo = e.code;
+        resolve({ codigo: typeof codigo === "number" ? codigo : null, stdout: "" });
+    });
+});
+export const gitReal = gitConPlazo(5_000);
+// El commit y la rama que la terminal DECLARA al subir la guía: 3 segundos (no 5) porque esto es un extra que nunca
+// debe hacer esperar a nadie.
+export const gitRapido = gitConPlazo(3_000);
+// `.supcoflow/proyecto.json` vive DENTRO del repo, y el repo puede ser un clon ajeno: su contenido lo
+// decide quien lo escribió. Por eso ni la carpeta ni el archivo se siguen si son enlaces (uno hacia
+// `~/.ssh/…` haría que la terminal leyera, o escribiera, lo que el repo quiera), y se lee con tope.
+export const TOPE_DEL_ARCHIVO_DEL_REPO = 64 * 1024;
+// Lo que devuelve `leer` cuando hay ALGO ahí que no se lee (un enlace, una carpeta, algo enorme, sin
+// permiso). No es JSON a propósito: `proyecto crear` lo trata como un archivo distinto (sale 4, «no lo
+// toqué») sin que nada de lo que hay ahí llegue a la salida.
+export const ARCHIVO_QUE_NO_SE_LEE = "\u0000(no se lee)";
+// Un archivo que la persona nombra (el logo) con las mismas defensas que los del repo: sin seguir
+// enlaces, sin FIFOs que cuelguen, sólo archivos comunes y con tope (se lee tope + 1 por si crece).
+export function leerArchivoChico(p, tope) {
+    let fd;
+    try {
+        fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (e) {
+        const code = e.code;
+        return { error: code === "ENOENT" ? "no existe" : code === "ELOOP" ? "es un enlace" : "no se pudo abrir" };
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return { error: "no es un archivo común" };
+        const buf = Buffer.alloc(tope + 1);
+        let n = 0;
+        for (;;) {
+            const leidos = readSync(fd, buf, n, buf.length - n, null);
+            if (leidos === 0)
+                break;
+            n += leidos;
+            if (n > tope)
+                return { error: "es demasiado grande" };
+        }
+        return { bytes: new Uint8Array(buf.subarray(0, n)) };
+    }
+    catch {
+        return { error: "no se pudo leer" };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function archivosDelRepo(avisar) {
+    // La carpeta: tiene que ser una carpeta de verdad. Un enlace o un archivo con ese nombre se rechaza;
+    // `null` sólo si no existe.
+    const carpetaPropia = (dir) => {
+        try {
+            const st = lstatSync(dir);
+            return st.isDirectory() && !st.isSymbolicLink() ? "propia" : "ajena";
+        }
+        catch (e) {
+            return e.code === "ENOENT" ? "ausente" : "ajena";
+        }
+    };
+    const noSeLee = (p, porque) => {
+        avisar(`No leo ${p}: ${porque}.`);
+        return ARCHIVO_QUE_NO_SE_LEE;
+    };
+    return {
+        leer(p) {
+            const carpeta = carpetaPropia(dirname(p));
+            if (carpeta === "ausente")
+                return null;
+            if (carpeta === "ajena")
+                return noSeLee(p, `${basename(dirname(p))} no es una carpeta común (¿un enlace?)`);
+            let fd;
+            try {
+                // O_NOFOLLOW: un enlace en el último tramo falla (ELOOP) en vez de abrir su destino.
+                // O_NONBLOCK: abrir un FIFO no se cuelga esperando a quien escriba.
+                fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "ENOENT")
+                    return null;
+                return noSeLee(p, code === "ELOOP" ? "es un enlace" : "no se pudo abrir");
+            }
+            try {
+                const st = fstatSync(fd);
+                if (!st.isFile())
+                    return noSeLee(p, "no es un archivo común");
+                if (st.size > TOPE_DEL_ARCHIVO_DEL_REPO)
+                    return noSeLee(p, "es demasiado grande");
+                // Se lee hasta el tope + 1 y no `st.size`: el archivo puede crecer entre el fstat y la lectura.
+                const buf = Buffer.alloc(TOPE_DEL_ARCHIVO_DEL_REPO + 1);
+                let n = 0;
+                for (;;) {
+                    const leidos = readSync(fd, buf, n, buf.length - n, null);
+                    if (leidos === 0)
+                        break;
+                    n += leidos;
+                    if (n > TOPE_DEL_ARCHIVO_DEL_REPO)
+                        return noSeLee(p, "es demasiado grande");
+                }
+                return buf.subarray(0, n).toString("utf8");
+            }
+            catch {
+                return noSeLee(p, "no se pudo leer");
+            }
+            finally {
+                closeSync(fd);
+            }
+        },
+        // Sólo se llama cuando `leer` dijo que no hay nada. El `.tmp` lleva un nombre al azar y se crea en
+        // exclusiva (`wx` no atraviesa un enlace que alguien dejara con ese nombre), y la carpeta se vuelve
+        // a mirar DESPUÉS del mkdir: `mkdir -p` sobre un enlace a una carpeta no falla, y escribir ahí
+        // sería escribir donde el repo quiera.
+        escribir(p, s) {
+            const dir = dirname(p);
+            mkdirSync(dir, { recursive: true });
+            if (carpetaPropia(dir) !== "propia")
+                throw new Error(`${dir} no es una carpeta común`);
+            const tmp = join(dir, `.${basename(p)}.${randomUUID()}.tmp`);
+            try {
+                const fd = openSync(tmp, "wx", 0o644);
+                try {
+                    writeSync(fd, s);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(tmp, p);
+            }
+            catch (e) {
+                rmSync(tmp, { force: true });
+                throw e;
+            }
+        },
+    };
+}
 const LOCALES = new Set(["localhost", "127.0.0.1", "[::1]"]);
 export function entornoReal(env = process.env) {
     const api = urlDeLaApi(env);
@@ -126,6 +389,29 @@ export function entornoReal(env = process.env) {
     const guardado = crearGuardado({
         env, llavero, archivo: almacenDeArchivo(rutaDelArchivo, fsReal), rutaDelArchivo, fs: fsReal, ahora: Date.now, avisar,
     });
+    // 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");
+    const idempotencia = crearRegistroDeIdempotencia({
+        origen: api.origin,
+        almacen: almacenDeArchivo(rutaDeIdempotencia, fsReal),
+        rutaDelArchivo: rutaDeIdempotencia,
+        fs: fsReal,
+        generar: randomUUID,
+        ahora: Date.now,
+        avisar,
+    });
+    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);
+    const configurarEnElMotor = {
+        api, guardado, git: gitReal, cwd, 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),
+    };
     return {
         env,
         api,
@@ -140,7 +426,7 @@ export function entornoReal(env = process.env) {
             guardado,
             maquina: hostname(),
             ahora: Date.now,
-            dormir: (ms) => new Promise((r) => setTimeout(r, ms)),
+            dormir,
             pedirCodigo: (a, maquina) => pedirCodigo(a, maquina, fetch),
             canjear: (a, deviceCode, plazoMs) => canjear(a, deviceCode, fetch, plazoMs),
             revocarPropia: (a, clave, plazoMs) => revocarPropia(a, clave, fetch, plazoMs),
@@ -148,5 +434,37 @@ export function entornoReal(env = process.env) {
             tramoMs,
         },
         quienSoy: (a, clave) => quienSoy(a, clave, fetch),
+        git: gitReal,
+        cwd,
+        idempotencia,
+        conexion: {
+            api, guardado, git: gitReal, cwd, ahora: Date.now, dormir, avisar, tramoMs,
+            crearConexion: (a, clave, repo) => crearConexion(a, clave, repo, fetch),
+            ultimaConexion: (a, clave, repo, plazoMs) => ultimaConexion(a, clave, repo, fetch, plazoMs),
+        },
+        proyecto: {
+            api, guardado, git: gitReal, cwd, idempotencia, archivos: archivosDelRepo(avisar), avisar,
+            buscarProyecto: (a, clave, repo) => buscarProyecto(a, clave, repo, 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),
+        },
+        configurar: {
+            ...configurarEnElMotor,
+            subirLogo: (a, clave, id, archivo) => subirLogo(a, clave, id, archivo, fetch),
+            leerArchivoChico,
+            leerCatalogo: (a, clave) => leerCatalogo(a, clave, fetch),
+        },
+        guia: {
+            ...configurarEnElMotor,
+            leerArchivoChico, fetch, gitDeclarado: gitRapido,
+            revisar: revisarGuia, publicar: publicarGuia, ver: leerGuia, elegir: elegirOrigen,
+        },
+        claves: {
+            ...configurarEnElMotor,
+            listarClaves: (a, clave, id) => listarClaves(a, clave, id, fetch),
+            esClaveDeConsultaDelProyecto: (a, clave, id) => esClaveDeConsultaDelProyecto(a, clave, id, fetch),
+            idempotencia, candados, secretos,
+        },
     };
 }

package/dist/flags-por-comando.js

@@ -0,0 +1,33 @@
+// 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.
+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",
+];
+export const FLAGS_POR_COMANDO = [
+    { flags: ["start", "wait"], comandos: ["login", "repo conectar"], texto: "--start y --wait son de `supcoflow login` y `supcoflow repo conectar`." },
+    {
+        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO],
+        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver` y los comandos que configuran un proyecto (no de `catalogo`).",
+    },
+    { 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`." },
+];
+/** 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) {
+        if (regla.flags.some((f) => presentes.includes(f)) && !regla.comandos.includes(comando))
+            return regla.texto;
+    }
+    return null;
+}

package/dist/guia.js

@@ -0,0 +1,11 @@
+// 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";
+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
+// editor de Windows pone BOM o \r\n, y si las dos puntas hashearan distinto, `guia_distinta` sería eterno.
+export function huellaDeGuia(texto) {
+    const normalizado = texto.replace(/^/, "").replace(/\r\n?/g, "\n");
+    return createHash("sha256").update(normalizado, "utf8").digest("hex");
+}

package/dist/idempotencia.js

@@ -0,0 +1,88 @@
+// La clave de idempotencia de los pedidos que crean algo en el motor (`proyecto crear`), guardada en
+// `~/.config/supcoflow/idempotencia.json` (Review Focus 4): si la respuesta se pierde en el camino, el
+// 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";
+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.
+    const cuenta = (operacion, alcance) => `${d.origen}#${operacion}#${alcance.toLowerCase()}`;
+    // ─── El modo estricto (`claves crear`; primera revisión externa del 2026-10-16, hallazgo 6) ───
+    // `proyecto crear` puede seguir con una clave sin guardar porque el proyecto tiene clave natural (el
+    // 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.`);
+    return {
+        async claveDe(operacion, alcance, opciones = {}) {
+            const c = cuenta(operacion, alcance);
+            try {
+                const guardada = await d.almacen.leer(c);
+                if (guardada !== null)
+                    return guardada.valor;
+            }
+            catch {
+                if (opciones.estricta)
+                    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.`);
+                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
+            // 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 {
+                if (opciones.estricta)
+                    throw noGuardada();
+                d.avisar(`No pude guardar la clave de idempotencia en ${d.rutaDelArchivo}: un reintento mandará otra.`);
+            }
+            return nueva;
+        },
+        async tiene(operacion, alcance) {
+            // Sólo lo usa el modo estricto: «no sé si hay un intento a medias» no puede leerse como «no hay».
+            try {
+                return (await d.almacen.leer(cuenta(operacion, alcance))) !== null;
+            }
+            catch {
+                throw noGuardada();
+            }
+        },
+        async olvidar(operacion, alcance) {
+            // Best-effort: una clave que queda guardada nunca da un proyecto de más. Tras un 2xx el próximo
+            // `crear` encuentra el proyecto por su repo antes de mandarla; tras un rechazo el motor ya la
+            // soltó; y un 409 `idempotency_key_reusada` la vuelve a olvidar.
+            try {
+                await d.almacen.borrar(cuenta(operacion, alcance));
+            }
+            catch {
+                d.avisar(`No pude borrar la clave de idempotencia de ${d.rutaDelArchivo}.`);
+            }
+        },
+    };
+}

package/dist/repo-local.js

@@ -0,0 +1,68 @@
+// El repo de GitHub de la carpeta donde se corre la terminal, o el que pide `--repo`.
+import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
+// La misma forma que acepta el motor: si la terminal dejara pasar algo que el motor rechaza, el
+// error llegaría como un 400 del servidor en vez de una frase clara acá.
+const FORMA_DEL_REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]{1,100}$/;
+function esRepoValido(s) {
+    if (!FORMA_DEL_REPO.test(s))
+        return false;
+    const nombre = s.split("/")[1];
+    return nombre !== "." && nombre !== "..";
+}
+// El host tiene que ser EXACTAMENTE github.com y va anclado al principio: un origin como
+// `https://evil.com/github.com/o/r` contiene «github.com» en la ruta y no es GitHub. Tampoco se
+// acepta usuario:clave@ delante del host (una URL con token no se interpreta, se descarta).
+// No se sigue `url.<base>.insteadOf` de la config de git: lo que importa es qué repo es, y eso
+// lo vuelve a comprobar el motor contra la instalación de la App; acá sólo se arma el pedido.
+const FORMAS_DE_ORIGIN = [
+    /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+    /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+    /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+];
+export function repoDelOrigin(url) {
+    const limpia = url.trim();
+    for (const forma of FORMAS_DE_ORIGIN) {
+        const m = forma.exec(limpia);
+        if (!m)
+            continue;
+        const repo = `${m[1]}/${m[2]}`;
+        return esRepoValido(repo) ? repo : null;
+    }
+    return null;
+}
+export async function leerRepoLocal(git, cwd) {
+    const top = await git(["rev-parse", "--show-toplevel"], cwd);
+    const raiz = top.codigo === 0 ? top.stdout.trim() : "";
+    if (!raiz)
+        return { repo: null, raiz: null, motivo: "sin_git" };
+    const origin = await git(["remote", "get-url", "origin"], cwd);
+    const url = origin.codigo === 0 ? origin.stdout.trim() : "";
+    if (!url)
+        return { repo: null, raiz, motivo: "sin_origin" };
+    const repo = repoDelOrigin(url);
+    if (!repo)
+        return { repo: null, raiz, motivo: "origin_no_es_github" };
+    return { repo, raiz };
+}
+const MOTIVOS = {
+    sin_git: "esta carpeta no es un repo de git",
+    sin_origin: "el repo no tiene un remoto «origin»",
+    origin_no_es_github: "el «origin» no es un repo de GitHub",
+};
+export async function repoPedido(d) {
+    const local = await leerRepoLocal(d.git, d.cwd);
+    if (d.flagRepo !== null) {
+        if (!esRepoValido(d.flagRepo)) {
+            throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "repo_invalido", "El valor de --repo tiene que ser owner/repo (por ejemplo duenio/mi-app), sin la URL.");
+        }
+        // La raíz sólo se da si el origin local es ESE repo: con otro, lo que se escriba en esta
+        // carpeta (el archivo del proyecto) no le pertenece.
+        const mismo = local.repo !== null && local.repo.toLowerCase() === d.flagRepo.toLowerCase();
+        return { repo: d.flagRepo, raiz: mismo ? local.raiz : null };
+    }
+    if (local.repo === null) {
+        const porque = local.motivo ? MOTIVOS[local.motivo] : "no se pudo leer";
+        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "sin_repo", `No encontré un repo de GitHub acá (${porque}). Pasá --repo owner/repo.`);
+    }
+    return { repo: local.repo, raiz: local.raiz };
+}