supcoflow 0.0.0-stage → 0.3.0

package/dist/comandos/describir.js

@@ -0,0 +1,248 @@
+// `supcoflow describir --json`: el contrato entero en una línea (§13), para que un asistente sepa
+// qué comandos hay, con qué flags, qué puede la clave y qué quiere decir cada código, sin leer la
+// ayuda pensada para personas. La ayuda se arma desde acá: una sola fuente, así no se desfasan.
+import { SALIDA } from "../contrato.js";
+// A mano a propósito, como en api.ts: tiene que coincidir con package.json (lo pinza un test).
+const VERSION = "0.3.0";
+export const DESCRIPCION = {
+    version: VERSION,
+    comandos: [
+        {
+            nombre: "login",
+            resumen: "Inicia sesión aprobando un código desde la consola. Sin terminal interactiva, en dos pasos: --start y después --wait.",
+            flags: [
+                "--start: pide el código y sale 5 con la URL para aprobarlo",
+                "--wait: espera la aprobación hasta 90 s; sale 5 si todavía no llegó (volvé a llamarlo)",
+                "--dry-run: dice qué haría sin pedir nada (no vale con --wait)",
+                "--json",
+            ],
+            ejemplos: ["supcoflow login", "supcoflow login --start --json", "supcoflow login --wait --json"],
+            codigos: [0, 1, 2, 3, 4, 5],
+        },
+        {
+            nombre: "logout",
+            resumen: "Revoca la clave en uso y la borra de esta máquina; reintenta las que quedaron por revocar.",
+            flags: ["--dry-run: dice qué revocaría sin revocar nada", "--json"],
+            ejemplos: ["supcoflow logout", "supcoflow logout --json"],
+            codigos: [0, 1, 3],
+        },
+        {
+            nombre: "quien-soy",
+            resumen: "Muestra con qué clave anda la terminal, a nombre de quién y en qué equipo.",
+            flags: ["--json"],
+            ejemplos: ["supcoflow quien-soy", "supcoflow quien-soy --json"],
+            codigos: [0, 1, 2, 3],
+        },
+        {
+            nombre: "describir",
+            resumen: "Describe comandos, flags, facultades y códigos de salida, para un asistente.",
+            flags: ["--json"],
+            ejemplos: ["supcoflow describir --json"],
+            codigos: [0],
+        },
+        {
+            nombre: "repo conectar",
+            resumen: "Conecta el repo de esta carpeta (o el de --repo) con la App de GitHub: una persona lo confirma en la consola. Sin terminal interactiva, en dos pasos: --start y después --wait.",
+            flags: [
+                "--start: pide la conexión y sale 5 con la URL para confirmarla",
+                "--wait: espera la confirmación hasta 90 s; sale 5 si todavía no llegó (volvé a llamarlo)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué pediría sin pedir nada (--wait sólo lee)",
+                "--json",
+            ],
+            ejemplos: ["supcoflow repo conectar", "supcoflow repo conectar --start --json", "supcoflow repo conectar --wait --json"],
+            codigos: [0, 1, 2, 3, 4, 5],
+        },
+        {
+            nombre: "proyecto crear",
+            resumen: "Crea (o reusa) el proyecto del repo ya conectado y lo anota en .supcoflow/proyecto.json; un archivo distinto nunca se pisa (sale 4).",
+            flags: [
+                "--install \"…\": el comando de instalación, cuando el motor no lo puede deducir",
+                "--test \"…\": el comando de pruebas, ídem",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin escribir el archivo)",
+                "--dry-run: dice qué crearía sin crear nada",
+                "--json",
+            ],
+            ejemplos: ["supcoflow proyecto crear --json", "supcoflow proyecto crear --install \"pnpm i\" --test \"pnpm test\""],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "proyecto ver",
+            resumen: "Muestra el proyecto del repo: rama, comandos y el estado de la App de GitHub; null si todavía no tiene.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow proyecto ver --json"],
+            codigos: [0, 1, 2, 3],
+        },
+        {
+            nombre: "catalogo",
+            resumen: "Lista lo que se puede configurar en el chat (claves y valores admitidos) y el estado del contrato de la App.",
+            flags: ["--json"],
+            ejemplos: ["supcoflow catalogo --json"],
+            codigos: [0, 1, 2, 3],
+        },
+        {
+            nombre: "configuracion",
+            resumen: "Muestra la configuración del proyecto del repo: chat, sitios, marca, política de problemas y acuerdo de datos. El acuerdo frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow configuracion --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat prender",
+            resumen: "Prende el chat de soporte del proyecto. Sin skill aprobada hace falta una persona (sale 4).",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat prender --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat apagar",
+            resumen: "Apaga el chat de soporte del proyecto.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat apagar --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat marca",
+            resumen: "Cambia título, saludo y colores del chat; lo que no nombrás queda como estaba.",
+            flags: [
+                "--titulo \"…\": el título del chat",
+                "--saludo \"…\": el saludo inicial",
+                "--tema clave=valor: un color o ajuste del tema (se repite, uno por clave)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow chat marca --titulo \"Ayuda\" --tema acento=#0a7"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat logo",
+            resumen: "Sube el logo del chat (.png, .jpg o .webp, hasta 200 KB).",
+            flags: ["--archivo ruta: la imagen", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat logo --archivo logo.png --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "sitios agregar",
+            resumen: "Agrega un sitio desde el que el chat puede cargarse.",
+            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow sitios agregar --sitio https://app.ejemplo.com"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "sitios quitar",
+            resumen: "Quita un sitio de los que pueden cargar el chat.",
+            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow sitios quitar --sitio https://app.ejemplo.com"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "datos fijar",
+            resumen: "Fija el acuerdo de datos: qué datos pasan. Frena lo que se guarda y lo que lee la IA que releva el repo; no cubre lo que ve la IA del chat mientras conversa.",
+            flags: [
+                "--permitir lista: datos que pasan, separados por coma (usuario_id, usuario_rol, pagina_y_navegador, capturas, elementos, email, atributo:nombre) o `nada`",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow datos fijar --permitir usuario_id,atributo:plan"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "politica fijar",
+            resumen: "Fija qué hace el motor con un problema que llega por el chat: relevarlo en el acto (gasta) o guardarlo. Guardar frena sólo lo automático del chat: desde la consola una persona puede pedir el relevamiento, y cuesta.",
+            flags: ["--modo relevar|guardar", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow politica fijar --modo guardar"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves crear",
+            resumen: "Crea una clave de consulta (sólo lee su proyecto) y la guarda en un archivo 0600 fuera de todo repo; el secreto nunca sale por la salida.",
+            flags: [
+                "--nombre ci: para qué es la clave",
+                "--guardar-en ruta: el archivo donde queda (fuera de un repo; si ya tiene otra cosa sale 4 y no lo toca)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow claves crear --nombre ci --guardar-en ~/ci.key --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves listar",
+            resumen: "Lista las claves de consulta activas del proyecto (id, nombre, fecha; nunca el secreto).",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow claves listar --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves revocar",
+            resumen: "Revoca una clave de consulta por su id; revocar dos veces deja lo mismo.",
+            flags: ["--id cla_…: la clave (la da `claves listar`)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow claves revocar --id cla_0123456789abcdef --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+    ],
+    flags_globales: ["--json: el resultado en una línea de JSON por stdout; los avisos van por stderr", "--help, -h: la ayuda con ejemplos"],
+    facultades: [
+        {
+            nombre: "consultar",
+            incluye: "Identidad y equipo, proyectos, configuración, casos, issues, runs, costos, estado de la instalación",
+            con_api_key: true,
+        },
+        {
+            nombre: "configurar",
+            incluye: "Crear/reusar proyecto, conectar o desconectar el repo, configurar y prender el chat, sitios permitidos, acuerdo de datos, política de problemas, publicar la guía, crear y revocar claves de consulta, perfiles de los agentes",
+            con_api_key: true,
+        },
+        { nombre: "probar", incluye: "La prueba hasta el issue (gasta, dentro de los topes)", con_api_key: true },
+        {
+            nombre: "solo_consola",
+            incluye: "Subir el tope de gasto, borrar el proyecto, encender la fábrica, dar o sacar acceso a personas: sólo con sesión en la consola",
+            con_api_key: false,
+        },
+        {
+            nombre: "operador",
+            incluye: "Solicitudes, /maquinaria, cerrar runs, la fábrica de operador: nunca por clave, aunque la persona sea operadora",
+            con_api_key: false,
+        },
+    ],
+    codigos: {
+        [SALIDA.ok]: "ok",
+        [SALIDA.inesperado]: "inesperado",
+        [SALIDA.faltaLogin]: "falta login",
+        [SALIDA.entradaInvalida]: "entrada inválida",
+        [SALIDA.haceFaltaUnaPersona]: "hace falta una persona",
+        [SALIDA.esperandoAUnaPersona]: "esperando a una persona (volvé a llamar)",
+        [SALIDA.topeAlcanzado]: "tope alcanzado",
+    },
+};
+export function comandoDescribir() {
+    return { codigo: SALIDA.ok, json: { ok: true, ...DESCRIPCION }, texto: ayuda(null) };
+}
+function bloque(c) {
+    return [
+        `  ${c.nombre}: ${c.resumen}`,
+        ...c.flags.map((f) => `      ${f}`),
+    ].join("\n");
+}
+export function ayuda(comando) {
+    const elegidos = comando === null ? DESCRIPCION.comandos : DESCRIPCION.comandos.filter((c) => c.nombre === comando);
+    const uso = comando === null ? "supcoflow <comando> [flags]" : `supcoflow ${comando} [flags]`;
+    const codigos = Object.entries(DESCRIPCION.codigos).map(([n, t]) => `  ${n}  ${t}`);
+    return [
+        `Uso: ${uso}`,
+        "",
+        comando === null ? "Comandos:" : "Comando:",
+        ...elegidos.map(bloque),
+        "",
+        "Flags de todos los comandos:",
+        ...DESCRIPCION.flags_globales.map((f) => `  ${f}`),
+        "",
+        "Ejemplos:",
+        ...elegidos.flatMap((c) => c.ejemplos.map((e) => `  ${e}`)),
+        "",
+        "Códigos de salida:",
+        ...codigos,
+    ].join("\n");
+}

package/dist/comandos/login.js

@@ -0,0 +1,254 @@
+import { FalloDeLaTerminal, resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { PLAZO_MINIMO_MS, RESERVA_PARA_CERRAR_MS, sondearUnTramo, TRAMO_MAXIMO_MS } from "../sondeo.js";
+const TECHO_DE_UN_PASO_MS = 5_000;
+const VOLVER_A_EMPEZAR = "Volvé a empezar con `supcoflow login --start`.";
+const fallo = (codigo, error, message, extra = {}) => ({
+    codigo, json: { ok: false, error, message, ...extra }, texto: message,
+});
+// Un error crudo del sistema (fs, el llavero) puede traer cualquier cosa: se tapa antes de mostrarlo.
+const motivo = (e) => e instanceof FalloDeLaTerminal ? e.message : taparSecretos(e instanceof Error ? e.message : String(e));
+// Las claves que un login o logout anterior no pudo revocar (Review Focus 14). Nunca lanza: es
+// limpieza de lo de antes y no puede trabar un login nuevo.
+export async function reintentarPorRevocar(d, limite) {
+    const origen = d.api.origin;
+    const noSe = () => {
+        d.avisar("No pude leer entera la lista de claves por revocar (el llavero no respondió); la reintento la próxima vez.");
+    };
+    let lectura;
+    try {
+        lectura = await d.guardado.leerPorRevocar(origen);
+    }
+    catch {
+        noSe();
+        return { revocadas: 0, quedan: null };
+    }
+    // «Cuántas quedan» sólo es un número si se pudo comprobar entero (Review Focus 15): con un
+    // almacén que no respondió puede haber claves que no se vieron, y decir 0 sería mentir.
+    let sabido = lectura.completa;
+    let revocadas = 0;
+    for (const clave of lectura.claves) {
+        const queda = limite - d.ahora();
+        if (queda < PLAZO_MINIMO_MS)
+            break;
+        try {
+            await d.revocarPropia(d.api, clave, Math.min(TECHO_DE_UN_PASO_MS, queda));
+        }
+        catch {
+            continue; // sigue anotada; el próximo login o logout la reintenta
+        }
+        revocadas++;
+        try {
+            if (!(await d.guardado.quitarPorRevocar(origen, clave)).completo)
+                sabido = false;
+        }
+        catch {
+            sabido = false;
+        }
+    }
+    if (!sabido) {
+        noSe();
+        return { revocadas, quedan: null };
+    }
+    return { revocadas, quedan: lectura.claves.length - revocadas };
+}
+export async function loginStart(d, flags) {
+    const origen = d.api.origin;
+    if (flags.dryRun) {
+        const haria = `pedir un código de dispositivo a ${origen}`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él, iría a ${haria}.` };
+    }
+    await reintentarPorRevocar(d, d.ahora() + 15_000);
+    let c;
+    try {
+        c = await d.pedirCodigo(d.api, d.maquina);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    // Sólo el pendiente, en su propia cuenta: la clave vigente sigue sirviendo hasta que la nueva
+    // quede guardada (Review Focus 7), así un login rechazado o abandonado no deja a nadie sin sesión.
+    const pendiente = {
+        deviceCode: c.deviceCode, userCode: c.userCode, verificationUriComplete: c.verificationUriComplete,
+        venceEn: d.ahora() + c.expiresIn * 1000, intervaloS: c.interval, ultimoSondeoEn: null,
+    };
+    try {
+        await d.guardado.guardarPendiente(origen, pendiente);
+    }
+    catch (e) {
+        return fallo(SALIDA.inesperado, e instanceof FalloDeLaTerminal ? e.error : "no_se_pudo_guardar", `No pude guardar el inicio de sesión en curso: ${motivo(e)}`);
+    }
+    return {
+        codigo: SALIDA.esperandoAUnaPersona,
+        json: {
+            ok: false, esperando: "persona", verification_uri: c.verificationUri,
+            verification_uri_complete: c.verificationUriComplete, user_code: c.userCode, expires_in: c.expiresIn,
+        },
+        texto: `Abrí ${c.verificationUriComplete} y confirmá el código ${c.userCode}. Después corré \`supcoflow login --wait\`.`,
+    };
+}
+export async function loginWait(d) {
+    const origen = d.api.origin;
+    const inicio = d.ahora();
+    const tramo = d.tramoMs ?? TRAMO_MAXIMO_MS;
+    const limite = inicio + tramo;
+    // La proporción sólo pesa con el tramo corto de las pruebas; con 90 s la reserva es la entera.
+    const finDeSondeos = limite - Math.min(RESERVA_PARA_CERRAR_MS, tramo / 3);
+    const techo = () => Math.max(0, Math.min(TECHO_DE_UN_PASO_MS, limite - d.ahora()));
+    const p = await d.guardado.leerPendiente(origen);
+    if (p === null) {
+        return fallo(SALIDA.entradaInvalida, "sin_login_en_curso", "No hay un inicio de sesión en curso: empezá con `supcoflow login --start`.");
+    }
+    // La anterior se lee ANTES de sondear, así no consume la reserva del cierre. Se pide por
+    // `leerClaveCompleta` para saber de paso si SUPCOFLOW_TOKEN está definida (sin costo: la variable
+    // se devuelve sin tocar los almacenes); en ese caso la anterior es la GUARDADA, nunca la del
+    // entorno, que no es de este login y no se revoca acá.
+    const vigente = await d.guardado.leerClaveCompleta(origen);
+    const conVariable = vigente.valor?.fuente === "env";
+    const lectura = conVariable ? await d.guardado.leerClaveGuardadaCompleta(origen) : vigente;
+    // Un llavero que no contestó no es «no había clave» (Review Focus 12 y 14): seguir guardaría la
+    // nueva encima de la anterior sin revocarla, viva y olvidada. Se corta antes de canjear el código
+    // y sin borrar el pendiente, así el mismo `--wait` sirve cuando el llavero vuelva.
+    if (!lectura.completa) {
+        const salida = conVariable
+            ? "desbloqueá el llavero y volvé a llamar `supcoflow login --wait`."
+            : "desbloqueá el llavero y volvé a llamar `supcoflow login --wait` (o, sin login, exportá SUPCOFLOW_TOKEN con una clave vigente).";
+        return fallo(SALIDA.inesperado, "no_pude_leer_la_clave", `No pude leer tu clave guardada (el llavero no respondió), y sin saber cuál es no la puedo reemplazar sin dejarla viva: ${salida}`);
+    }
+    const anterior = lectura.valor;
+    let fin;
+    try {
+        fin = await sondearUnTramo(p, {
+            ahora: d.ahora, dormir: d.dormir, finDeSondeos,
+            canjear: (deviceCode, plazoMs) => d.canjear(d.api, deviceCode, plazoMs),
+            persistir: (q, techoMs) => d.guardado.guardarPendiente(origen, q, techoMs),
+        });
+    }
+    catch (e) {
+        // El progreso de los sondeos anteriores ya quedó guardado: el próximo `--wait` sigue de ahí.
+        return resultadoDeFallo(e);
+    }
+    switch (fin.tipo) {
+        case "sigue":
+            return {
+                codigo: SALIDA.esperandoAUnaPersona,
+                json: { ok: false, esperando: "persona", user_code: fin.pendiente.userCode, verification_uri_complete: fin.pendiente.verificationUriComplete },
+                texto: `Todavía no se confirmó. Abrí ${fin.pendiente.verificationUriComplete} y confirmá el código ${fin.pendiente.userCode}; después volvé a correr \`supcoflow login --wait\`.`,
+            };
+        case "token": {
+            const r = await reemplazarClave(d, { clave: fin.clave, equipo: fin.equipo }, anterior?.clave ?? null, limite);
+            // Va acá y no adentro de `reemplazarClave` porque es acá donde se supo, antes de sondear, sin
+            // gastar reserva: preguntarlo al final costaría otra lectura lenta del guardado.
+            if (conVariable && r.json.guardada_en !== undefined) {
+                d.avisar("SUPCOFLOW_TOKEN está definida y tiene prioridad sobre la clave que acabo de guardar.");
+            }
+            return r;
+        }
+        case "rechazado":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.haceFaltaUnaPersona, "acceso_rechazado", "Rechazaron el acceso desde la consola; tu sesión anterior, si había, sigue igual.");
+        case "vencido":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.faltaLogin, "codigo_vencido", `El código venció. ${VOLVER_A_EMPEZAR}`);
+        case "invalido":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.faltaLogin, "codigo_invalido", `El código ya no vale. ${VOLVER_A_EMPEZAR}`);
+    }
+}
+// El login de una persona frente a la terminal: los mismos dos pasos, encadenados. Sin TTY (o con
+// `--json`) no pide código: nadie iba a ver la URL, y un pedido que nadie aprueba sólo gasta el tope
+// de pedidos por IP del motor. A un asistente le corresponde el camino partido.
+const PAUSA_ENTRE_TRAMOS_MS = 1_000;
+export async function loginInteractivo(d, flags) {
+    if (!d.esTty || flags.json) {
+        return fallo(SALIDA.entradaInvalida, "hace_falta_tty", "Sin terminal interactiva usá `supcoflow login --start --json` y después `supcoflow login --wait --json`.");
+    }
+    const inicio = await loginStart(d, flags);
+    if (inicio.codigo !== SALIDA.esperandoAUnaPersona)
+        return inicio;
+    // El texto de `--start` le dice a la persona que corra `--wait`; acá eso lo hace el comando solo.
+    const { verification_uri_complete: url, user_code: codigo } = inicio.json;
+    d.mostrar(`Abrí ${String(url)} y confirmá el código ${String(codigo)}. Espero acá…`);
+    // Cada tramo termina por su cuenta (≤ 90 s) y el código vence a los pocos minutos, así que el
+    // bucle tiene fin aunque la persona nunca conteste: termina en `codigo_vencido`.
+    let r;
+    do {
+        r = await loginWait(d);
+        // Un `loginWait` que devuelve 5 sin haber sondeado (el intervalo era más largo que la ventana
+        // que quedaba) volvería a girar sin esperar nada: este segundo evita quemar CPU en el vacío.
+        if (r.codigo === SALIDA.esperandoAUnaPersona)
+            await d.dormir(PAUSA_ENTRE_TRAMOS_MS);
+    } while (r.codigo === SALIDA.esperandoAUnaPersona);
+    return r;
+}
+// Por qué este orden (guardar → revocar → anotar → borrar el pendiente), Review Focus 13 y 14:
+// la nueva se guarda primero porque es la única copia; la anterior se revoca recién con la nueva a
+// salvo (si no, un fallo al guardar dejaba a la persona sin ninguna); si no se pudo revocar, se anota
+// para no olvidarla viva; y el borrado del pendiente va último y no lanza, porque ubicado antes era el
+// que podía impedir revocar la anterior, y un pendiente viejo es inofensivo.
+export async function reemplazarClave(d, nueva, anterior, limite) {
+    const origen = d.api.origin;
+    const queda = () => limite - d.ahora();
+    const techo = () => Math.max(0, Math.min(TECHO_DE_UN_PASO_MS, queda()));
+    // 1. Guardar la nueva. Con el techo agotado el guardado salta el llavero y escribe el archivo, que
+    // es local: la clave se guarda igual aunque el tramo esté por vencer.
+    let guardadaEn;
+    try {
+        guardadaEn = (await d.guardado.guardarClave(origen, nueva.clave, techo())).donde;
+    }
+    catch (e) {
+        // Una clave que nadie guardó no puede quedar viva: se revoca, aunque haga falta un plazo mínimo
+        // más allá del tramo, porque nadie más la va a poder revocar.
+        let revocada = true;
+        try {
+            await d.revocarPropia(d.api, nueva.clave, Math.min(TECHO_DE_UN_PASO_MS, Math.max(PLAZO_MINIMO_MS, queda())));
+        }
+        catch {
+            revocada = false;
+        }
+        const despues = revocada
+            ? "La revoqué para que no quede viva; tu sesión anterior, si había, sigue como estaba."
+            : "Tampoco pude revocarla: revocala en la consola, en «Accesos desde la terminal».";
+        return fallo(SALIDA.inesperado, "no_se_pudo_guardar", `No pude guardar la clave nueva (${motivo(e)}). ${despues}`);
+    }
+    // 2. Revocar la anterior, o anotarla.
+    let anteriorRevocada = null;
+    let quedaPorRevocar = false;
+    if (anterior !== null && anterior !== nueva.clave) {
+        anteriorRevocada = false;
+        if (queda() >= PLAZO_MINIMO_MS) {
+            try {
+                await d.revocarPropia(d.api, anterior, Math.min(TECHO_DE_UN_PASO_MS, queda()));
+                anteriorRevocada = true;
+            }
+            catch {
+                // cae a anotarla
+            }
+        }
+        if (!anteriorRevocada) {
+            try {
+                await d.guardado.anotarPorRevocar(origen, anterior, techo());
+                quedaPorRevocar = true;
+                d.avisar("No pude revocar tu clave anterior; quedó anotada y la reintento en el próximo login o logout.");
+            }
+            catch {
+                const message = "No pude revocar ni anotar tu clave anterior: revocala en la consola, en «Accesos desde la terminal».";
+                d.avisar(message);
+                if (queda() >= PLAZO_MINIMO_MS)
+                    await d.guardado.borrarPendiente(origen, techo());
+                // La nueva SÍ quedó guardada y anda: el json lo dice para que nadie vuelva a hacer login.
+                return fallo(SALIDA.inesperado, "clave_anterior_sin_revocar", message, {
+                    equipo: nueva.equipo, guardada_en: guardadaEn, anterior_revocada: false, queda_por_revocar: false,
+                });
+            }
+        }
+    }
+    // 3. Borrar el pendiente; su `false` no cambia nada.
+    if (queda() >= PLAZO_MINIMO_MS)
+        await d.guardado.borrarPendiente(origen, techo());
+    const donde = guardadaEn === "llavero" ? "el llavero del sistema" : "el archivo de credenciales";
+    return {
+        codigo: SALIDA.ok,
+        json: { ok: true, equipo: nueva.equipo, guardada_en: guardadaEn, anterior_revocada: anteriorRevocada, queda_por_revocar: quedaPorRevocar },
+        texto: `Sesión iniciada en el equipo ${nueva.equipo}; la clave quedó en ${donde}.`,
+    };
+}

package/dist/comandos/logout.js

@@ -0,0 +1,96 @@
+// `supcoflow logout`: cierra UNA credencial, la que se está usando, y nunca olvida una clave viva
+// (Review Focus 9 y 14). Borrar sin revocar dejaría la clave sirviendo en el motor y sin nadie que
+// la recuerde: por eso, si el motor no confirma, no se borra nada y el comando sale 1.
+import { FalloDeLaTerminal, SALIDA, taparSecretos } from "../contrato.js";
+import { reintentarPorRevocar } from "./login.js";
+const motivo = (e) => e instanceof FalloDeLaTerminal ? e.message : taparSecretos(e instanceof Error ? e.message : String(e));
+export async function comandoLogout(d, flags) {
+    const origen = d.api.origin;
+    // Sin nada legible y un almacén que no contestó, no se sabe si hay sesión: decir «no había»
+    // dejaría creer que no queda ninguna clave viva (Review Focus 12).
+    const noPudeLeer = (extra = {}) => {
+        const message = "No pude leer la clave guardada (el llavero no respondió); no cerré nada. Probá de nuevo.";
+        return { codigo: SALIDA.inesperado, json: { ok: false, error: "no_pude_leer_la_clave", message, ...extra }, texto: message };
+    };
+    if (flags.dryRun) {
+        const lectura = await d.guardado.leerClaveCompleta(origen);
+        const vigente = lectura.valor;
+        if (vigente === null && !lectura.completa)
+            return noPudeLeer({ dry_run: true });
+        if (vigente === null) {
+            return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, habia_sesion: false }, texto: "No hay sesión iniciada: no haría nada." };
+        }
+        const haria = `revocar la clave de ${vigente.fuente} en ${origen}` + (vigente.fuente !== "env" ? " y borrarla" : "");
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él, iría a ${haria}.` };
+    }
+    // Lo pendiente de antes va primero: un logout es justo cuando la persona espera que no quede
+    // ninguna clave suya viva, y es la última oportunidad que tiene la terminal de revocarlas.
+    const { quedan } = await reintentarPorRevocar(d, d.ahora() + 15_000);
+    // `null` es «no lo pude comprobar» y se dice así: un 0 haría creer que no queda nada vivo.
+    if (quedan === null) {
+        d.avisar("No pude comprobar cuántas claves quedan por revocar; las que haya siguen anotadas y las reintento en el próximo login o logout.");
+    }
+    else if (quedan > 0) {
+        d.avisar(`Quedan ${quedan} clave(s) anterior(es) sin revocar; siguen anotadas y las reintento en el próximo login o logout.`);
+    }
+    const lectura = await d.guardado.leerClaveCompleta(origen);
+    const vigente = lectura.valor;
+    if (vigente === null && !lectura.completa)
+        return noPudeLeer({ quedan_por_revocar: quedan });
+    const conPendientes = (json) => ({ ...json, quedan_por_revocar: quedan, ...(lectura.completa ? {} : { lectura_completa: false }) });
+    if (vigente === null) {
+        await d.guardado.borrarPendiente(origen);
+        return { codigo: SALIDA.ok, json: conPendientes({ ok: true, habia_sesion: false }), texto: "No había sesión iniciada." };
+    }
+    let revocada;
+    try {
+        revocada = (await d.revocarPropia(d.api, vigente.clave)) === "revocada";
+    }
+    catch (e) {
+        const cual = vigente.fuente === "env" ? "la clave de SUPCOFLOW_TOKEN sigue viva" : "la clave sigue guardada";
+        const message = `No pude revocar la clave, así que no cerré la sesión (${motivo(e)}); ${cual}. Probá de nuevo.`;
+        const error = e instanceof FalloDeLaTerminal ? e.error : "inesperado";
+        return { codigo: SALIDA.inesperado, json: conPendientes({ ok: false, error, message }), texto: message };
+    }
+    // La variable no es nuestra: se revoca la clave que trae, pero lo guardado es OTRA credencial,
+    // que sólo se cierra revocándola a ella. Borrarla acá la dejaría viva y olvidada.
+    if (vigente.fuente === "env") {
+        d.avisar("Revoqué la clave de SUPCOFLOW_TOKEN; sacala de tu entorno.");
+        // `undefined` = no se pudo leer: no se afirma que no haya, el json lleva `null` en vez de mentir.
+        let guardada;
+        try {
+            const l = await d.guardado.leerClaveGuardadaCompleta(origen);
+            guardada = l.valor ?? (l.completa ? null : undefined);
+        }
+        catch {
+            guardada = undefined;
+        }
+        if (guardada) {
+            d.avisar(`Sigue guardada otra clave en ${guardada.fuente}; para cerrarla, corré \`supcoflow logout\` sin SUPCOFLOW_TOKEN.`);
+        }
+        return {
+            codigo: SALIDA.ok,
+            json: conPendientes({ ok: true, revocada, fuente: "env", queda_clave_guardada: guardada === undefined ? null : guardada !== null }),
+            texto: "Revoqué la clave de SUPCOFLOW_TOKEN.",
+        };
+    }
+    // Con la lectura incompleta se borra sólo la copia que se leyó y se acaba de revocar: la del
+    // almacén que no contestó puede ser otra clave, viva, y borrarla sin revocarla la olvidaría.
+    if (!lectura.completa) {
+        const otro = vigente.fuente === "archivo" ? "el llavero del sistema" : "el archivo de credenciales";
+        d.avisar(`Cierro la clave de ${vigente.fuente}, pero no pude leer ${otro}: puede quedar otra copia guardada ahí; cuando responda, volvé a correr \`supcoflow logout\`.`);
+    }
+    try {
+        if (lectura.completa)
+            await d.guardado.borrarClave(origen);
+        else
+            await d.guardado.borrarClaveDe(origen, vigente.fuente);
+    }
+    catch (e) {
+        // La clave ya no sirve en el motor, pero quedó escrita: el comando no puede decir que terminó bien.
+        const message = `La clave quedó revocada pero no pude borrarla: ${motivo(e)}`;
+        return { codigo: SALIDA.inesperado, json: conPendientes({ ok: false, error: "no_se_pudo_borrar", message }), texto: message };
+    }
+    await d.guardado.borrarPendiente(origen);
+    return { codigo: SALIDA.ok, json: conPendientes({ ok: true, revocada }), texto: "Sesión cerrada." };
+}

package/dist/comandos/proyecto-del-repo.js

@@ -0,0 +1,26 @@
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { repoPedido } from "../repo-local.js";
+import { claveVigente } from "./clave-vigente.js";
+export async function proyectoDelRepo(d, flags) {
+    let repo;
+    try {
+        repo = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).repo;
+    }
+    catch (e) {
+        return { ok: false, resultado: resultadoDeFallo(e) };
+    }
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return { ok: false, resultado: leida.resultado };
+    try {
+        const proyecto = await d.buscarProyecto(d.api, leida.vigente.clave, repo);
+        if (proyecto === null) {
+            const message = `El repo ${repo} todavía no tiene proyecto. Creá el proyecto: \`supcoflow proyecto crear\`.`;
+            return { ok: false, resultado: { codigo: SALIDA.haceFaltaUnaPersona, json: { ok: false, error: "sin_proyecto", message, repo }, texto: message } };
+        }
+        return { ok: true, clave: leida.vigente.clave, proyecto };
+    }
+    catch (e) {
+        return { ok: false, resultado: resultadoDeFallo(e) };
+    }
+}