supcoflow 0.0.0-stage → 0.3.0

package/dist/guardado/index.js

@@ -0,0 +1,258 @@
+// Dónde vive la clave de la terminal (§5.2): el llavero del sistema; si no hay, un archivo 0600
+// avisando; `SUPCOFLOW_TOKEN` por encima de los dos; y nunca un destino dentro de un repo de git.
+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";
+// 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ó.
+// Y la clave y el login en curso son cuentas DISTINTAS (Review Focus 7): empezar o abandonar un login
+// escribe sólo `#pendiente` y nunca puede pisar la clave vigente.
+const cuentaDeClave = (origen) => origen;
+const cuentaDePendiente = (origen) => `${origen}#pendiente`;
+const cuentaPorRevocar = (origen) => `${origen}#por_revocar`;
+function esPendiente(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const p = v;
+    return typeof p.deviceCode === "string" && typeof p.userCode === "string" && typeof p.verificationUriComplete === "string"
+        && typeof p.venceEn === "number" && typeof p.intervaloS === "number"
+        && (p.ultimoSondeoEn === null || typeof p.ultimoSondeoEn === "number");
+}
+function listaDeClaves(s) {
+    try {
+        const v = JSON.parse(s);
+        return Array.isArray(v) && v.every((x) => typeof x === "string") ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function crearGuardado(d) {
+    const almacenes = () => (d.llavero ? [d.llavero, d.archivo] : [d.archivo]);
+    // El techo es de la operación ENTERA (Review Focus 10): un vencimiento absoluto calculado al
+    // entrar, que leer, escribir y limpiar se reparten. Si cada llamada tuviera su propio techo, una
+    // operación «de 5 s» podían ser 10 y la reserva del tramo del login no cerraba.
+    function plazo(techoMs = TECHO_DEL_LLAVERO_MS) {
+        const fin = d.ahora() + techoMs;
+        return () => fin - d.ahora();
+    }
+    // El plazo sólo corta al llavero: el archivo es local y no se cuelga, y es el último recurso para
+    // guardar una clave que no tiene otra copia. Un plazo agotado no espera al llavero: es una falla.
+    async function intentar(a, queda, op) {
+        if (a === null)
+            return { estado: "ausente" };
+        const techo = queda();
+        if (a.nombre === "llavero" && techo <= 0)
+            return { estado: "fallo" };
+        try {
+            return { estado: "ok", valor: await op(a, Math.max(techo, 1)) };
+        }
+        catch (e) {
+            return e instanceof LlaveroAusente ? { estado: "ausente" } : { estado: "fallo" };
+        }
+    }
+    // Gana el `escritoEn` más alto, no el almacén (Review Focus 8): si el llavero falla una vez, la
+    // clave nueva cae al archivo; cuando el llavero vuelve, todavía tiene la VIEJA. Preferir el
+    // llavero por ser el llavero devolvería una clave ya reemplazada (y quizás revocada).
+    async function leerCuentaCompleta(cuenta, queda) {
+        let mejor = null;
+        let completa = true;
+        for (const a of almacenes()) {
+            const i = await intentar(a, queda, (x, t) => x.leer(cuenta, t));
+            if (i.estado === "fallo")
+                completa = false;
+            if (i.estado === "ok" && i.valor !== null && (mejor === null || i.valor.escritoEn > mejor.r.escritoEn)) {
+                mejor = { r: i.valor, fuente: a.nombre };
+            }
+        }
+        return { mejor, completa };
+    }
+    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}.`);
+    };
+    // 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
+    // de la escrita (Review Focus 6): con `~/.config` enlazado a un repo de dotfiles, la escrita no
+    // cae en ningún repo y la real sí.
+    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.`);
+        }
+        await d.archivo.escribir(cuenta, r);
+        d.avisar(`No hay llavero del sistema: guardé ${que} en ${d.rutaDelArchivo} con permisos 0600.`);
+    }
+    async function escribirCuenta(cuenta, valor, que, techoMs) {
+        const queda = plazo(techoMs);
+        const r = { valor, escritoEn: d.ahora() };
+        const ll = await intentar(d.llavero, queda, (x, t) => x.escribir(cuenta, r, t));
+        if (ll.estado === "ok") {
+            // Best-effort: si queda algo viejo en el archivo, la regla del `escritoEn` lo deja atrás.
+            await intentar(d.archivo, queda, (x, t) => x.borrar(cuenta, t));
+            return "llavero";
+        }
+        await escribirEnArchivo(cuenta, r, que);
+        // No se limpia el llavero: si acaba de fallar (o vencer su techo) no se lo vuelve a esperar, y
+        // si está ausente no tiene nada. Lo viejo que quede ahí pierde por `escritoEn`.
+        return "archivo";
+    }
+    // Devuelve de qué almacenes PRESENTES no se pudo borrar; un llavero ausente no guarda nada.
+    async function borrarCuenta(cuenta, techoMs) {
+        const queda = plazo(techoMs);
+        const fallidos = [];
+        for (const a of almacenes()) {
+            if ((await intentar(a, queda, (x, t) => x.borrar(cuenta, t))).estado === "fallo")
+                fallidos.push(a.nombre);
+        }
+        return fallidos;
+    }
+    async function leerLista(a, cuenta, queda) {
+        const i = await intentar(a, queda, (x, t) => x.leer(cuenta, t));
+        if (i.estado !== "ok")
+            return i;
+        if (i.valor === null)
+            return { estado: "ok", valor: [] };
+        const lista = listaDeClaves(i.valor.valor);
+        return lista === null ? { estado: "fallo" } : { estado: "ok", valor: lista };
+    }
+    const guardado = {
+        async leerClave(origen) {
+            // Quien exporta la variable decide: se usa sin mirar el origen.
+            const env = d.env.SUPCOFLOW_TOKEN;
+            if (env)
+                return { clave: env, fuente: "env" };
+            return guardado.leerClaveGuardada(origen);
+        },
+        async leerClaveGuardada(origen) {
+            const l = await leerCuenta(cuentaDeClave(origen), plazo());
+            return l === null ? null : { clave: l.r.valor, fuente: l.fuente };
+        },
+        async leerClaveCompleta(origen) {
+            const env = d.env.SUPCOFLOW_TOKEN;
+            if (env)
+                return { valor: { clave: env, fuente: "env" }, completa: true };
+            return guardado.leerClaveGuardadaCompleta(origen);
+        },
+        // Las de arriba tragan un almacén que no contesta como «no hay»; ésta lo dice, porque quien va a
+        // PISAR o BORRAR la clave necesita saber si leyó todo (Review Focus 12 y 14): con A en un llavero
+        // bloqueado, «no hay» deja que un login la reemplace sin revocarla.
+        async leerClaveGuardadaCompleta(origen, techoMs) {
+            const { mejor, completa } = await leerCuentaCompleta(cuentaDeClave(origen), plazo(techoMs));
+            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) };
+        },
+        async borrarClave(origen) {
+            // Un borrado a medias de una clave no se informa como hecho: la que quedó sigue sirviendo.
+            const fallidos = await borrarCuenta(cuentaDeClave(origen));
+            if (fallidos.length > 0)
+                throw errorDeBorrado(fallidos);
+        },
+        // Para cuando la lectura fue incompleta: se borra sólo la copia que se leyó y se revocó. La del
+        // almacén que no contestó puede ser OTRA clave, viva; borrarla a ciegas la olvidaría sin revocar.
+        async borrarClaveDe(origen, almacen) {
+            const a = almacen === "llavero" ? d.llavero : d.archivo;
+            if ((await intentar(a, plazo(), (x, t) => x.borrar(cuentaDeClave(origen), t))).estado === "fallo") {
+                throw errorDeBorrado([almacen]);
+            }
+        },
+        async leerPendiente(origen) {
+            const l = await leerCuenta(cuentaDePendiente(origen), plazo());
+            if (l === null)
+                return null;
+            try {
+                const v = JSON.parse(l.r.valor);
+                return esPendiente(v) ? v : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async guardarPendiente(origen, p, techoMs) {
+            await escribirCuenta(cuentaDePendiente(origen), JSON.stringify(p), "el inicio de sesión en curso", techoMs);
+        },
+        async borrarPendiente(origen, techoMs) {
+            // Nunca lanza: un pendiente viejo es inofensivo (su device_code ya se consumió o vence en
+            // 10 min; el próximo `--start` lo pisa y un `--wait` sobre él recibe `invalid_grant` y lo limpia).
+            try {
+                return (await borrarCuenta(cuentaDePendiente(origen), techoMs)).length === 0;
+            }
+            catch {
+                return false;
+            }
+        },
+        // La lista «por revocar» NO sigue la regla del `escritoEn` (Review Focus 15): es la UNIÓN de los
+        // dos almacenes. Con «gana la más reciente», A anotada en el llavero y B en el archivo mientras
+        // el llavero no respondía daría [B], y A quedaría vigente para siempre sin que nadie la revoque.
+        async leerPorRevocar(origen) {
+            const queda = plazo();
+            const claves = new Set();
+            let completa = true;
+            for (const a of almacenes()) {
+                const l = await leerLista(a, cuentaPorRevocar(origen), queda);
+                if (l.estado === "ok")
+                    l.valor.forEach((c) => claves.add(c));
+                else if (l.estado === "fallo")
+                    completa = false;
+            }
+            return { claves: [...claves], completa };
+        },
+        // Se escribe SÓLO en un almacén, sobre la lista que se acaba de leer de ESE almacén: nunca se
+        // reemplaza la del otro, que puede tener claves que ahora no se pueden leer. Y un almacén que no
+        // se pudo leer no se pisa a ciegas.
+        async anotarPorRevocar(origen, clave, techoMs) {
+            const queda = plazo(techoMs);
+            const cuenta = cuentaPorRevocar(origen);
+            for (const a of almacenes()) {
+                const l = await leerLista(a, cuenta, queda);
+                if (l.estado !== "ok")
+                    continue;
+                if (l.valor.includes(clave))
+                    return;
+                const r = { valor: JSON.stringify([...l.valor, clave]), escritoEn: d.ahora() };
+                if (a.nombre === "archivo") {
+                    try {
+                        await escribirEnArchivo(cuenta, r, "las claves por revocar");
+                        return;
+                    }
+                    catch (e) {
+                        if (e instanceof FalloDeLaTerminal)
+                            throw e;
+                        break;
+                    }
+                }
+                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.");
+        },
+        // 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
+        // próximo reintento la vuelve a revocar, el motor contesta `ya_no_valia` y se quita entonces.
+        async quitarPorRevocar(origen, clave) {
+            const queda = plazo();
+            const cuenta = cuentaPorRevocar(origen);
+            let completo = true;
+            for (const a of almacenes()) {
+                const l = await leerLista(a, cuenta, queda);
+                if (l.estado === "fallo")
+                    completo = false;
+                if (l.estado !== "ok" || !l.valor.includes(clave))
+                    continue;
+                const resto = l.valor.filter((c) => c !== clave);
+                const op = resto.length === 0
+                    ? (x, t) => x.borrar(cuenta, t)
+                    : (x, t) => x.escribir(cuenta, { valor: JSON.stringify(resto), escritoEn: d.ahora() }, t);
+                if ((await intentar(a, queda, op)).estado !== "ok")
+                    completo = false;
+            }
+            return { completo };
+        },
+    };
+    return guardado;
+}

package/dist/guardado/llavero.js

@@ -0,0 +1,110 @@
+// El llavero del sistema: Keychain en macOS (`security`), Secret Service en Linux (`secret-tool`).
+// Sin dependencias: se habla con el binario del sistema, inyectado como `Correr` para los tests.
+import { existsSync } from "node:fs";
+import { esRegistro } from "./archivo.js";
+// Un anillo bloqueado que pide desbloqueo, o un Linux sin D-Bus, deja al binario esperando para
+// siempre: cada llamada tiene techo y vencerlo es una falla, nunca un comando colgado (Review Focus 2).
+export const TECHO_DEL_LLAVERO_MS = 5_000;
+// AUSENTE no es FALLIDO (Review Focus 12): un binario que no existe no guarda nada, así que no hay
+// 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}).`);
+        this.name = "LlaveroAusente";
+    }
+}
+const SERVICIO = "supcoflow";
+// El base64url no tiene espacios: el modo `-i` de `security` parte la línea por espacios, y una
+// clave en JSON los tiene (o podría tenerlos). Con base64url el secreto es un único argumento.
+const codificar = (r) => Buffer.from(JSON.stringify(r)).toString("base64url");
+function decodificar(s) {
+    let v;
+    try {
+        v = JSON.parse(Buffer.from(s.trim(), "base64url").toString("utf8"));
+    }
+    catch {
+        v = undefined;
+    }
+    if (!esRegistro(v))
+        throw new Error("El llavero devolvió algo que no entiendo.");
+    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.");
+    return cuenta;
+}
+// La ruta ABSOLUTA: un `security` del PATH podría ser otro programa (un `node_modules/.bin`, un
+// directorio del repo en el PATH) y recibiría la clave. El secreto va con `-i` por stdin porque en
+// `argv` lo ve cualquiera con `ps` mientras el comando corre; leer y borrar no llevan secreto.
+const MACOS = {
+    bins: ["/usr/bin/security"],
+    escribir: (cuenta, secreto) => ({
+        args: ["-i"],
+        stdin: `add-generic-password -U -s ${SERVICIO} -a ${cuenta} -w ${secreto}\n`,
+    }),
+    leer: (cuenta) => ["find-generic-password", "-s", SERVICIO, "-a", cuenta, "-w"],
+    borrar: (cuenta) => ["delete-generic-password", "-s", SERVICIO, "-a", cuenta],
+    // 44 = errSecItemNotFound.
+    noEncontrado: (codigo) => codigo === 44,
+};
+// `secret-tool store` lee el secreto de stdin cuando no hay terminal: nunca en `argv`.
+//
+// Rutas ABSOLUTAS y no `secret-tool` por el PATH, por la misma razón que `security` arriba: un
+// `node_modules/.bin/secret-tool` plantado recibiría cada clave por stdin.
+const LINUX = {
+    bins: ["/usr/bin/secret-tool", "/bin/secret-tool", "/usr/local/bin/secret-tool"],
+    escribir: (cuenta, secreto) => ({
+        args: ["store", "--label=Supcoflow", "servicio", SERVICIO, "cuenta", cuenta],
+        stdin: secreto,
+    }),
+    leer: (cuenta) => ["lookup", "servicio", SERVICIO, "cuenta", cuenta],
+    borrar: (cuenta) => ["clear", "servicio", SERVICIO, "cuenta", cuenta],
+    // `secret-tool` sale 1 sin salida también sin D-Bus o con el anillo bloqueado: lo único que
+    // distingue «no está» de «no pude mirar» es que, cuando no está, no dice nada por stderr.
+    noEncontrado: (codigo, stdout, stderr) => codigo === 1 && stdout.trim() === "" && stderr.trim() === "",
+};
+export function almacenDeLlavero(plataforma, correr, existe = existsSync) {
+    const c = plataforma === "darwin" ? MACOS : plataforma === "linux" ? LINUX : null;
+    if (c === null)
+        return null;
+    // Ni el stdout, ni el stdin, ni el stderr van al mensaje: pueden llevar el secreto.
+    async function ejecutar(args, stdin, techoMs) {
+        const bin = c.bins.find((b) => existe(b));
+        if (bin === undefined)
+            throw new LlaveroAusente(c.bins[0]);
+        const r = await correr(bin, args, stdin, techoMs);
+        if (r.ausente)
+            throw new LlaveroAusente(bin);
+        if (r.vencido)
+            throw new Error(`El llavero no contestó en ${Math.round(techoMs / 1000)} s.`);
+        return r;
+    }
+    const fallo = (codigo) => new Error(`El llavero falló (código ${codigo}).`);
+    return {
+        nombre: "llavero",
+        async leer(cuenta, techoMs = TECHO_DEL_LLAVERO_MS) {
+            const r = await ejecutar(c.leer(cuentaSegura(cuenta)), null, techoMs);
+            if (c.noEncontrado(r.codigo, r.stdout, r.stderr ?? ""))
+                return null;
+            if (r.codigo !== 0)
+                throw fallo(r.codigo);
+            return decodificar(r.stdout);
+        },
+        async escribir(cuenta, registro, techoMs = TECHO_DEL_LLAVERO_MS) {
+            const { args, stdin } = c.escribir(cuentaSegura(cuenta), codificar(registro));
+            const r = await ejecutar(args, stdin, techoMs);
+            if (r.codigo !== 0)
+                throw fallo(r.codigo);
+        },
+        async borrar(cuenta, techoMs = TECHO_DEL_LLAVERO_MS) {
+            const r = await ejecutar(c.borrar(cuentaSegura(cuenta)), null, techoMs);
+            if (c.noEncontrado(r.codigo, r.stdout, r.stderr ?? ""))
+                return;
+            if (r.codigo !== 0)
+                throw fallo(r.codigo);
+        },
+    };
+}

package/dist/guardado/repo.js

@@ -0,0 +1,35 @@
+// ¿Cae este destino dentro de un repo de git? Si la respuesta es sí, la clave no se escribe ahí:
+// un `git add -A` distraído (o un repo de dotfiles que se sube a GitHub) la publicaría (§5.2).
+import path from "node:path";
+// La ruta escrita engaña cuando un tramo es un enlace (`~/.config` armado con `stow` desde un repo
+// de dotfiles): se resuelve el ancestro existente más cercano y se le suman los segmentos que todavía
+// no existen, porque `realpath` de algo que no existe lanza (Review Focus 6).
+export function rutaReal(p, fs) {
+    let actual = path.resolve(p);
+    const faltan = [];
+    while (!fs.existe(actual)) {
+        const padre = path.dirname(actual);
+        if (padre === actual)
+            break;
+        faltan.unshift(path.basename(actual));
+        actual = padre;
+    }
+    return path.join(fs.realpath(actual), ...faltan);
+}
+// Seguido o no: basta que exista `.git`, directorio o archivo (un worktree tiene un archivo `.git`).
+// Se miran las dos rutas porque cualquiera de las dos puede ser la que cae dentro del repo.
+export function dentroDeUnWorkingTree(dir, fs) {
+    const escrita = path.resolve(dir);
+    for (const inicio of new Set([escrita, rutaReal(escrita, fs)])) {
+        let actual = inicio;
+        for (;;) {
+            if (fs.existe(path.join(actual, ".git")))
+                return actual;
+            const padre = path.dirname(actual);
+            if (padre === actual)
+                break;
+            actual = padre;
+        }
+    }
+    return null;
+}

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 };
+}