supcoflow 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# supcoflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+La terminal de [Supcoflow](https://app.supcoflow.dev): iniciar sesión y manejar el chat de soporte
+desde la consola, o desde un asistente de código que corre comandos por vos.
+
+Trae iniciar y cerrar sesión, ver con qué cuenta estás, conectar el repo con la App de GitHub,
+crear su proyecto y configurar el chat.
+
+## Instalar
+
+Hace falta Node 24 o más nuevo.
+
+```bash
+npx supcoflow login
+```
+
+## Los comandos
+
+| Comando | Qué hace |
+|---|---|
+| `supcoflow login` | Te muestra un enlace y un código; lo aprobás en la consola y la terminal queda con su clave. |
+| `supcoflow login --start` | El primer paso, solo: pide el código y sale 5 con el enlace para aprobarlo. |
+| `supcoflow login --wait` | El segundo paso: espera la aprobación hasta 90 s. Si todavía no llegó, sale 5: volvé a correrlo. |
+| `supcoflow logout` | Revoca la clave en uso y la borra de esta máquina. |
+| `supcoflow quien-soy` | Con qué clave anda la terminal, a nombre de quién y en qué equipo. |
+| `supcoflow repo conectar` | Conecta el repo de esta carpeta con la App de GitHub: te da un enlace, lo confirmás en la consola. Sin terminal, `--start` y después `--wait`, como `login`. |
+| `supcoflow proyecto crear` | Crea (o reusa) el proyecto del repo ya conectado y lo anota en `.supcoflow/proyecto.json`. Si el motor no deduce los comandos, `--install "…" --test "…"`. |
+| `supcoflow proyecto ver` | El proyecto del repo: rama, comandos y el estado de la App de GitHub. |
+| `supcoflow describir --json` | Todo el contrato (comandos, flags, facultades de la clave, códigos) en una línea de JSON. |
+
+`supcoflow --help` (o `supcoflow <comando> --help`) muestra la ayuda con ejemplos. Los comandos de
+repo y proyecto toman el repo del `origin` de la carpeta; `--repo owner/repo` lo elige a mano.
+
+### De cero a un proyecto
+
+1. `supcoflow login`: aprobás el código en la consola.
+2. `supcoflow repo conectar`: instalás la App en GitHub si hace falta y tocás Confirmar.
+3. `supcoflow proyecto crear`: queda el proyecto y `.supcoflow/proyecto.json` para commitear.
+4. `supcoflow proyecto ver`: para revisar cómo quedó.
+
+### Ejemplos
+
+```bash
+# Una persona frente a la terminal
+supcoflow login
+
+# Un asistente, sin terminal interactiva: dos pasos
+supcoflow login --start --json     # sale 5 con verification_uri_complete y user_code
+supcoflow login --wait --json      # sale 5 mientras la persona no apruebe; 0 cuando aprueba
+
+supcoflow repo conectar --start --json   # sale 5 con la url para confirmar
+supcoflow repo conectar --wait --json    # sale 5 mientras nadie confirme; 0 conectado
+supcoflow proyecto crear --json          # 4 si hay un .supcoflow/proyecto.json distinto (no lo pisa)
+supcoflow proyecto crear --install "pnpm i" --test "pnpm test"
+supcoflow proyecto ver --json
+
+supcoflow quien-soy --json
+supcoflow logout --dry-run         # qué revocaría, sin revocar nada
+```
+
+## Configurar
+
+Con el repo ya conectado y su proyecto creado, se configura el chat sin entrar a la consola (la clave
+tiene que ser de sesión, no de consulta). Todos toman el repo del `origin`, o `--repo owner/repo`, y
+los que escriben aceptan `--dry-run`.
+
+| Comando | Qué hace |
+|---|---|
+| `supcoflow catalogo` | Qué se puede configurar y con qué valores. |
+| `supcoflow configuracion` | Chat, sitios, marca y acuerdo de datos del proyecto. |
+| `supcoflow chat prender` / `chat apagar` | Prende o apaga el chat (sin skill aprobada, prender sale 4). |
+| `supcoflow chat marca --titulo "Ayuda" --tema acento=#0a7` | Título, saludo y colores; lo no nombrado queda igual. |
+| `supcoflow chat logo --archivo logo.png` | Sube el logo (.png, .jpg o .webp, hasta 200 KB). |
+| `supcoflow sitios agregar\|quitar --sitio https://app.ejemplo.com` | Sitios desde los que carga el chat. |
+| `supcoflow datos fijar --permitir usuario_id,atributo:plan` | Acuerdo de datos: frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa. |
+| `supcoflow politica fijar --modo guardar` | Qué hace el motor con un problema que llega por el chat: `relevar` (gasta) o `guardar`. Guardar frena sólo lo automático del chat; una persona puede pedir el relevamiento desde la consola, y cuesta. |
+| `supcoflow claves crear --nombre ci --guardar-en ~/ci.key` | Clave de consulta para CI: el secreto queda sólo en ese archivo (0600, fuera de un repo), nunca en la salida. |
+| `supcoflow claves listar` / `claves revocar --id cla_…` | Ver y revocar claves de consulta. |
+
+## El contrato
+
+Pensado para que lo lea un programa, no sólo una persona:
+
+- **`--json`**: el resultado sale por stdout en **una línea** de JSON; los avisos van por stderr.
+  Los errores también: `{"ok":false,"error":"…","message":"…"}`, con su código de salida.
+- **Sin preguntas sin terminal interactiva** (o con `--json`): si falta un dato, sale 3 diciendo qué
+  flag usar. `supcoflow login` sin terminal sale 3 y te indica el camino en dos pasos.
+- **`--dry-run`** donde se puede simular (`login`, `login --start`, `logout`, `repo conectar --start`,
+  `proyecto crear`). `login --wait
+  --dry-run` sale 3: sondear consume el código y no hay cómo simularlo.
+
+| Código | Quiere decir |
+|---|---|
+| 0 | ok |
+| 1 | inesperado |
+| 2 | falta login |
+| 3 | entrada inválida |
+| 4 | hace falta una persona |
+| 5 | esperando a una persona: volvé a llamar |
+| 6 | tope alcanzado |
+
+## Dónde queda la clave
+
+- En el **llavero del sistema** (Keychain en macOS, Secret Service con `secret-tool` en Linux).
+- Si no hay llavero, en `~/.config/supcoflow/credenciales.json` (o `$XDG_CONFIG_HOME/supcoflow/…`)
+  con permisos `0600`, y la terminal te avisa.
+- **Nunca dentro de un repo de git**: si ese archivo cayera dentro de uno (un `HOME` que es un repo
+  de dotfiles, por ejemplo), no guarda nada y te pide usar el llavero o `SUPCOFLOW_TOKEN`.
+- **`SUPCOFLOW_TOKEN`** tiene prioridad sobre lo guardado: sirve para CI y para la nube.
+- La clave nunca sale en un log ni en una salida `--json`.
+- `proyecto crear` guarda su clave de idempotencia (no es un secreto: sólo evita crear dos veces si se
+  pierde la respuesta) en `idempotencia.json`, al lado de las credenciales y con los mismos permisos.
+
+Cuando iniciás sesión de nuevo, la clave anterior se revoca recién cuando la nueva quedó guardada; si
+no se pudo revocar, queda anotada y se reintenta en el próximo `login` o `logout`.
+
+## La API es fija
+
+La terminal habla siempre con `https://app.supcoflow.dev`. Ningún archivo del repo puede cambiar
+eso, así que clonar un repo ajeno y correr `supcoflow` no manda tu clave a otro servidor. Para
+desarrollo, sólo la variable de entorno `SUPCOFLOW_API_URL` la mueve (`https`, o `http` contra
+`localhost`), y lo guardado queda atado a la API que lo emitió: una clave de un motor local nunca
+viaja a producción.

package/dist/api.js

@@ -0,0 +1,295 @@
+// Los pedidos de la terminal al motor. Sin dependencias: `fetch` viene de Node y se inyecta.
+import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
+// La URL viene FIJA (§5.2): si un archivo del repo pudiera cambiarla, clonar un repo ajeno y correr
+// `supcoflow` mandaría el token a un servidor ajeno. Sólo el entorno del proceso la mueve, y `http`
+// únicamente contra la propia máquina: contra un host remoto la clave viajaría en claro.
+export const API_DE_PRODUCCION = "https://app.supcoflow.dev";
+const LOCALES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export function urlDeLaApi(env) {
+    const crudo = env.SUPCOFLOW_API_URL;
+    if (crudo === undefined || crudo === "")
+        return new URL(API_DE_PRODUCCION);
+    const invalida = () => new FalloDeLaTerminal(SALIDA.entradaInvalida, "api_url_invalida", "SUPCOFLOW_API_URL tiene que ser https, o http contra localhost.");
+    let u;
+    try {
+        u = new URL(crudo);
+    }
+    catch {
+        throw invalida();
+    }
+    if (u.protocol === "https:" || (u.protocol === "http:" && LOCALES.has(u.hostname)))
+        return new URL(u.origin);
+    throw invalida();
+}
+// A mano a propósito: tiene que coincidir con package.json (0.3.0); sólo identifica a la terminal
+// en los logs del motor, no decide nada.
+const VERSION = "0.3.0";
+const PLAZO_POR_DEFECTO_MS = 15_000;
+// Los dos POST que crean algo: detrás, el motor acuña con Vercel Connect y le pregunta a GitHub varias
+// veces (instalación, repos, comandos, rama). Con 15 s una respuesta lenta pero buena se cortaba y
+// sólo quedaba reintentar; el sondeo no los usa, así que su tope por tramo no cambia.
+const PLAZO_DE_ALTA_MS = 30_000;
+// Todo lo que vuelve de afuera se trata como no confiable: nunca se pega el cuerpo crudo en un
+// mensaje (una página HTML no sirve en una línea y podría traer cualquier cosa), y el mensaje del
+// error de red no se reenvía (podría llevar la URL o la clave).
+async function pedir(api, ruta, init, f, plazoMs) {
+    let res;
+    let texto;
+    try {
+        res = await f(new URL(ruta, api), {
+            ...init,
+            headers: { ...init.headers, "user-agent": `supcoflow-cli/${VERSION}` },
+            signal: AbortSignal.timeout(plazoMs ?? PLAZO_POR_DEFECTO_MS),
+            // Un 307/308 reenvía el cuerpo del formulario (con el device_code) adonde diga `Location`, aunque
+            // sea otro origen o http; con el Bearer pasaría lo mismo con la clave. Ninguna ruta del motor que
+            // llama la terminal redirige: una redirección es anómala y sale como `motor_inalcanzable`, sin
+            // Location ni cuerpo en el mensaje.
+            redirect: "error",
+        });
+        texto = await res.text();
+    }
+    catch {
+        throw new FalloDeLaTerminal(SALIDA.inesperado, "motor_inalcanzable", "No pude comunicarme con el motor (red caída o demora).");
+    }
+    let cuerpo;
+    try {
+        cuerpo = JSON.parse(texto);
+    }
+    catch {
+        cuerpo = undefined;
+    }
+    if (typeof cuerpo !== "object" || cuerpo === null || Array.isArray(cuerpo)) {
+        throw new FalloDeLaTerminal(SALIDA.inesperado, "respuesta_inesperada", `El motor respondió ${res.status} sin JSON.`);
+    }
+    return { status: res.status, cuerpo: cuerpo };
+}
+function sinServicio(status) {
+    return new FalloDeLaTerminal(SALIDA.inesperado, "motor_inalcanzable", `El motor respondió ${status}; probá en unos minutos.`);
+}
+function inesperada(status) {
+    return new FalloDeLaTerminal(SALIDA.inesperado, "respuesta_inesperada", `El motor respondió ${status} con algo que no esperaba.`);
+}
+const texto = (v) => (typeof v === "string" ? v : null);
+const CLIENT_ID = "supcoflow-cli";
+const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const FORMULARIO = { "content-type": "application/x-www-form-urlencoded" };
+export async function pedirCodigo(api, maquina, f) {
+    const { status, cuerpo: c } = await pedir(api, "/api/dispositivo/codigo", { method: "POST", headers: FORMULARIO, body: new URLSearchParams({ client_id: CLIENT_ID, maquina }).toString() }, f);
+    if (status === 429 || status === 503) {
+        throw new FalloDeLaTerminal(SALIDA.inesperado, texto(c.error) ?? "demasiados_pedidos", "El motor no acepta más pedidos ahora; probá en unos minutos.");
+    }
+    if (status >= 500)
+        throw sinServicio(status);
+    const [deviceCode, userCode, verificationUri, verificationUriComplete] = [c.device_code, c.user_code, c.verification_uri, c.verification_uri_complete].map(texto);
+    if (status !== 200 || !deviceCode || !userCode || !verificationUri || !verificationUriComplete
+        || typeof c.expires_in !== "number" || typeof c.interval !== "number")
+        throw inesperada(status);
+    return { deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn: c.expires_in, interval: c.interval };
+}
+const ERRORES_DEL_CANJE = {
+    authorization_pending: "pendiente", slow_down: "slow_down", access_denied: "rechazado",
+    expired_token: "vencido", invalid_grant: "invalido",
+};
+// `plazoMs` es el techo de ESTE pedido: el sondeo lo achica cerca del final de su tramo para que
+// un pedido colgado no lo pase de largo.
+export async function canjear(api, deviceCode, f, plazoMs) {
+    const { status, cuerpo: c } = await pedir(api, "/api/dispositivo/token", { method: "POST", headers: FORMULARIO, body: new URLSearchParams({ grant_type: GRANT_TYPE, device_code: deviceCode, client_id: CLIENT_ID }).toString() }, f, plazoMs);
+    if (status >= 500)
+        throw sinServicio(status);
+    if (status === 200) {
+        const clave = texto(c.access_token);
+        const equipo = texto(c.equipo);
+        if (!clave || !equipo)
+            throw inesperada(status);
+        return { tipo: "token", clave, equipo };
+    }
+    const tipo = ERRORES_DEL_CANJE[texto(c.error) ?? ""];
+    if (status === 400 && tipo)
+        return { tipo };
+    throw inesperada(status);
+}
+const bearer = (clave) => ({ authorization: `Bearer ${clave}` });
+export async function quienSoy(api, clave, f) {
+    const { status, cuerpo: c } = await pedir(api, "/api/yo", { method: "GET", headers: bearer(clave) }, f);
+    if (status === 401) {
+        throw new FalloDeLaTerminal(SALIDA.faltaLogin, "clave_invalida", texto(c.message) ?? "La clave ya no vale: iniciá sesión de nuevo.");
+    }
+    if (status >= 500)
+        throw sinServicio(status);
+    const u = c.usuario;
+    if (status !== 200 || !texto(c.via) || !texto(c.equipo))
+        throw inesperada(status);
+    return {
+        via: c.via,
+        equipo: c.equipo,
+        usuario: u ? { id: String(u.id), login: texto(u.login), email: texto(u.email) } : null,
+        proyecto: texto(c.proyecto),
+    };
+}
+export async function revocarPropia(api, clave, f, plazoMs) {
+    const { status } = await pedir(api, "/api/dispositivo/revocar", { method: "POST", headers: bearer(clave) }, f, plazoMs);
+    if (status === 200)
+        return "revocada";
+    if (status === 401)
+        return "ya_no_valia";
+    if (status >= 500)
+        throw sinServicio(status);
+    throw inesperada(status);
+}
+// ---- Conexión del repo y proyecto (bloque 3) ----
+// Una sola puerta para los pedidos con clave: suma el Bearer y traduce lo que significa lo mismo en
+// todos (clave rota, clave sin alcance, repo mal escrito, cuenta sin GitHub). Lo que es propio de
+// cada pedido (404, 409, 422 de comandos) lo decide quien llama. Los `message` del motor son texto de
+// afuera: pasan por taparSecretos antes de salir en una línea de la terminal.
+async function conClave(api, clave, ruta, init, f, plazoMs) {
+    const r = await pedir(api, ruta, { ...init, headers: { ...init.headers, ...bearer(clave) } }, f, plazoMs);
+    const error = texto(r.cuerpo.error) ?? "respuesta_inesperada";
+    const message = (porDefecto) => taparSecretos(texto(r.cuerpo.message) ?? porDefecto);
+    if (r.status === 401) {
+        throw new FalloDeLaTerminal(SALIDA.faltaLogin, "clave_invalida", message("La clave ya no vale: iniciá sesión de nuevo."));
+    }
+    if (r.status === 403 && (error === "requiere_persona" || error === "clave_de_consulta")) {
+        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, error, message("Esto lo tiene que hacer una persona con sesión."));
+    }
+    if (r.status === 422 && error === "cuenta_sin_github") {
+        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, error, message("Tu cuenta no tiene GitHub asociado."));
+    }
+    if (r.status === 400 && error === "repo_invalido") {
+        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, error, message("El repo tiene que ser owner/repo."));
+    }
+    if (r.status >= 500)
+        throw sinServicio(r.status);
+    return r;
+}
+const ESTADOS_DE_PEDIDO = new Set(["pendiente", "conectado", "repo_fuera_de_alcance", "vencido"]);
+function aPedido(v, status) {
+    const c = (typeof v === "object" && v !== null ? v : {});
+    const [id, repo, estado, url, venceEn] = [c.id, c.repo, c.estado, c.url, c.vence_en].map(texto);
+    if (!id || !repo || !estado || !ESTADOS_DE_PEDIDO.has(estado) || !url || !venceEn)
+        throw inesperada(status);
+    return { id, repo, estado: estado, url, venceEn, repoCanonico: texto(c.repo_canonico), fallo: texto(c.fallo) };
+}
+function aProyecto(v, status) {
+    const c = (typeof v === "object" && v !== null ? v : {});
+    const [id, slug, repo, rama, installCommand, testCommand] = [c.id, c.slug, c.repo, c.rama, c.install_command, c.test_command].map(texto);
+    if (!id || !slug || !repo || !rama || installCommand === null || testCommand === null)
+        throw inesperada(status);
+    return { id, slug, repo, rama, installCommand, testCommand };
+}
+// Un fallo propio del pedido que el mapeo común no cubrió (404, 409…): sale como entrada inválida
+// con el motivo del motor, nunca con el cuerpo crudo.
+function rechazada(r) {
+    const error = texto(r.cuerpo.error);
+    if (r.status >= 400 && r.status < 500 && error) {
+        return new FalloDeLaTerminal(SALIDA.entradaInvalida, error, taparSecretos(texto(r.cuerpo.message) ?? `El motor rechazó el pedido (${r.status}).`));
+    }
+    return inesperada(r.status);
+}
+const JSON_BODY = { "content-type": "application/json" };
+export async function crearConexion(api, clave, repo, f) {
+    const r = await conClave(api, clave, "/api/conexiones", { method: "POST", headers: JSON_BODY, body: JSON.stringify({ repo }) }, f, PLAZO_DE_ALTA_MS);
+    if (r.status !== 200 && r.status !== 201)
+        throw rechazada(r);
+    return aPedido(r.cuerpo.pedido, r.status);
+}
+export async function ultimaConexion(api, clave, repo, f, plazoMs) {
+    const r = await conClave(api, clave, `/api/conexiones?${new URLSearchParams({ repo })}`, { method: "GET" }, f, plazoMs);
+    if (r.status !== 200)
+        throw rechazada(r);
+    return r.cuerpo.pedido === null ? null : aPedido(r.cuerpo.pedido, r.status);
+}
+export async function crearProyecto(api, clave, conexionId, cuerpo, idempotencyKey, f) {
+    const r = await conClave(api, clave, `/api/conexiones/${encodeURIComponent(conexionId)}/proyecto`, { method: "POST", headers: { ...JSON_BODY, "idempotency-key": idempotencyKey }, body: JSON.stringify(cuerpo) }, f, PLAZO_DE_ALTA_MS);
+    const error = texto(r.cuerpo.error);
+    const message = taparSecretos(texto(r.cuerpo.message) ?? "");
+    if (r.status === 200 || r.status === 201) {
+        return { tipo: "ok", proyecto: aProyecto(r.cuerpo.proyecto, r.status), reusado: r.status === 200 };
+    }
+    if (r.status === 422 && error === "comandos_faltantes") {
+        const faltantes = Array.isArray(r.cuerpo.faltantes) ? r.cuerpo.faltantes.filter((x) => typeof x === "string") : [];
+        return { tipo: "comandos_faltantes", faltantes, message };
+    }
+    if (r.status === 409 && error === "idempotency_en_curso")
+        return { tipo: "en_curso" };
+    if (r.status === 409 && error === "idempotency_key_reusada")
+        return { tipo: "clave_reusada" };
+    if (r.status === 409 && error === "conexion_no_conectada")
+        return { tipo: "no_conectada", message };
+    if (r.status >= 400 && r.status < 500 && error)
+        return { tipo: "rechazo", error, message };
+    throw inesperada(r.status);
+}
+export async function buscarProyecto(api, clave, repo, f) {
+    const r = await conClave(api, clave, `/api/proyectos?${new URLSearchParams({ repo })}`, { method: "GET" }, f);
+    if (r.status !== 200)
+        throw rechazada(r);
+    return r.cuerpo.proyecto === null ? null : aProyecto(r.cuerpo.proyecto, r.status);
+}
+export async function leerProyecto(api, clave, id, f) {
+    const r = await conClave(api, clave, `/api/proyectos/${encodeURIComponent(id)}`, { method: "GET" }, f);
+    if (r.status !== 200)
+        throw rechazada(r);
+    const g = (typeof r.cuerpo.github === "object" && r.cuerpo.github !== null ? r.cuerpo.github : {});
+    return { proyecto: aProyecto(r.cuerpo.proyecto, r.status), github: { estado: texto(g.estado), verificadoEn: texto(g.verificado_en) } };
+}
+// ---- Configurar (bloque 4) ----
+const objeto = (v, status) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        throw inesperada(status);
+    return v;
+};
+export async function leerCatalogo(api, clave, f) {
+    const r = await conClave(api, clave, "/api/catalogo", { method: "GET" }, f);
+    if (r.status !== 200 || !Array.isArray(r.cuerpo.supcoflow))
+        throw rechazada(r);
+    return r.cuerpo;
+}
+export async function leerConfiguracion(api, clave, proyectoId, f) {
+    const r = await conClave(api, clave, `/api/proyectos/${encodeURIComponent(proyectoId)}/configuracion`, { method: "GET" }, f);
+    if (r.status !== 200)
+        throw rechazada(r);
+    objeto(r.cuerpo.chat, r.status);
+    if (!Array.isArray(r.cuerpo.sitios))
+        throw inesperada(r.status);
+    return r.cuerpo;
+}
+// Las escrituras devuelven la respuesta entera: qué significa un 409 lo decide cada comando (prender sin
+// guía es «hace falta una persona»; la lista que cambió es «probá de nuevo»).
+export async function configurar(api, clave, ruta, cuerpo, f, extra = {}) {
+    const headers = { ...JSON_BODY };
+    if (extra.idempotencyKey !== undefined)
+        headers["idempotency-key"] = extra.idempotencyKey;
+    return conClave(api, clave, ruta, { method: "POST", headers, body: JSON.stringify(cuerpo) }, f);
+}
+export async function subirLogo(api, clave, proyectoId, archivo, f) {
+    const form = new FormData();
+    form.set("logo", new Blob([archivo.bytes], { type: archivo.mime }), archivo.nombre);
+    // Sin content-type a mano: `fetch` pone el multipart con su boundary.
+    return conClave(api, clave, `/api/proyectos/${encodeURIComponent(proyectoId)}/chat/logo`, { method: "POST", body: form }, f);
+}
+export async function listarClaves(api, clave, proyectoId, f) {
+    const r = await conClave(api, clave, `/api/proyectos/${encodeURIComponent(proyectoId)}/claves`, { method: "GET" }, f);
+    if (r.status !== 200 || !Array.isArray(r.cuerpo.claves))
+        throw rechazada(r);
+    return r.cuerpo.claves.map((x) => {
+        const o = objeto(x, r.status);
+        const [id, nombre, creadaEn] = [o.id, o.nombre, o.creada_en].map(texto);
+        if (!id || !nombre || !creadaEn)
+            throw inesperada(r.status);
+        return { id, nombre, creadaEn };
+    });
+}
+// ¿Esta clave es una clave de CONSULTA de este proyecto y autentica? La prueba de posesión de
+// `claves crear`: el motor es el único que sabe cuál generación es la vigente, y de qué alcance. Que lea el
+// proyecto no alcanza: una clave personal también lo lee y puede mucho más (tercera revisión, hallazgo 2).
+// Sin `conClave`: un 401 acá es la respuesta («no»), no «iniciá sesión».
+export async function esClaveDeConsultaDelProyecto(api, clave, proyectoId, f) {
+    const r = await pedir(api, "/api/yo", { method: "GET", headers: bearer(clave) }, f);
+    if (r.status === 401)
+        return false;
+    if (r.status >= 500)
+        throw sinServicio(r.status);
+    if (r.status !== 200)
+        throw inesperada(r.status);
+    return r.cuerpo.via === "clave_de_consulta" && r.cuerpo.proyecto === proyectoId;
+}

package/dist/argumentos.js

@@ -0,0 +1,98 @@
+import { parseArgs } from "node:util";
+import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
+export const COMANDOS_COMPUESTOS = [
+    "repo conectar", "proyecto crear", "proyecto ver",
+    "chat prender", "chat apagar", "chat marca", "chat logo", "sitios agregar", "sitios quitar",
+    "datos fijar", "politica fijar", "claves crear", "claves listar", "claves revocar",
+];
+// Sólo estas primeras palabras admiten una segunda: cualquier otro par sigue siendo «de más».
+const PRIMERAS_PALABRAS = new Set(COMANDOS_COMPUESTOS.map((c) => c.split(" ")[0]));
+const FLAGS_CON_VALOR = [
+    "repo", "install", "test", "sitio", "titulo", "saludo", "archivo", "permitir", "modo", "nombre", "guardar-en", "id",
+];
+// strict: un flag mal escrito (`--estart`) no se ignora en silencio: un asistente creería que
+// pidió algo que no pidió.
+export function leerArgumentos(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                json: { type: "boolean" },
+                "dry-run": { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+                start: { type: "boolean" },
+                wait: { type: "boolean" },
+                repo: { type: "string" },
+                install: { type: "string" },
+                test: { type: "string" },
+                sitio: { type: "string" },
+                titulo: { type: "string" },
+                saludo: { type: "string" },
+                archivo: { type: "string" },
+                permitir: { type: "string" },
+                modo: { type: "string" },
+                nombre: { type: "string" },
+                "guardar-en": { type: "string" },
+                id: { type: "string" },
+                tema: { type: "string", multiple: true },
+            },
+            tokens: true,
+        });
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            const m = /'(--?[^']+)'/.exec(e.message);
+            throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "flag_desconocido", `No conozco el flag ${m ? m[1] : "que pasaste"}. Probá \`supcoflow --help\`.`);
+        }
+        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_invalidos", `${e.message} Probá \`supcoflow --help\`.`);
+    }
+    const pos = parsed.positionals;
+    const deMas = () => new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_de_mas", "Pasaste más de un comando. Probá `supcoflow --help`.");
+    if (pos.length > 2 || (pos.length === 2 && !PRIMERAS_PALABRAS.has(pos[0])))
+        throw deMas();
+    // `parseArgs` se queda con el último valor de un flag repetido: un asistente que repite `--repo`
+    // creería que se usó el primero. Se mira en los tokens y se rechaza.
+    for (const nombre of FLAGS_CON_VALOR) {
+        const toks = (parsed.tokens ?? []).filter((t) => t.kind === "option" && t.name === nombre);
+        if (toks.length > 1 || toks.some((t) => t.kind === "option" && t.value === "")) {
+            throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_invalidos", `--${nombre} va una sola vez y con un valor. Probá \`supcoflow --help\`.`);
+        }
+    }
+    // `--tema` sí se repite (uno por clave), pero ninguno vacío: un `--tema ""` es un error de quien arma
+    // el comando, no «sin tema».
+    if ((parsed.values.tema ?? []).some((t) => t === "")) {
+        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_invalidos", "--tema va con un valor clave=valor. Probá `supcoflow --help`.");
+    }
+    // Un par desconocido (`repo borrar`) queda como la primera palabra sola: el despacho la rechaza
+    // como comando desconocido, con el mismo mensaje que cualquier otra.
+    const compuesto = pos.length === 2 ? `${pos[0]} ${pos[1]}` : null;
+    const comando = compuesto !== null && COMANDOS_COMPUESTOS.includes(compuesto) ? compuesto : (pos[0] ?? null);
+    const v = parsed.values;
+    return {
+        comando,
+        flags: {
+            json: v.json === true,
+            dryRun: v["dry-run"] === true,
+            help: v.help === true,
+            start: v.start === true,
+            wait: v.wait === true,
+            repo: v.repo ?? null,
+            install: v.install ?? null,
+            test: v.test ?? null,
+            sitio: v.sitio ?? null,
+            titulo: v.titulo ?? null,
+            saludo: v.saludo ?? null,
+            archivo: v.archivo ?? null,
+            permitir: v.permitir ?? null,
+            modo: v.modo ?? null,
+            nombre: v.nombre ?? null,
+            guardarEn: v["guardar-en"] ?? null,
+            id: v.id ?? null,
+            tema: v.tema ?? [],
+        },
+    };
+}

package/dist/candado.js

@@ -0,0 +1,57 @@
+// Un candado por operación en ESTA máquina (segunda revisión externa del 2026-10-16, hallazgo 1): comprobar
+// que un archivo autentica y después escribirlo no es atómico, y dos `claves crear` del mismo proyecto y
+// nombre pisaban uno el secreto del otro. Un archivo creado en exclusiva es el candado más simple que
+// funciona entre procesos sin dependencias.
+//
+// ─── No se recupera solo (tercera revisión, hallazgo 1) ─────────────────────────
+//
+// La primera versión borraba un candado «viejo» y tomaba uno nuevo. Leer la fecha y después borrar no es
+// atómico: dos procesos que encontraban el mismo candado viejo entraban los dos, y el primero en soltar
+// borraba el del otro. Ahora un candado de un proceso que ya no existe se informa con su ruta y lo borra una
+// persona, que sabe que no hay nadie corriendo. Y `soltar` sólo borra si el archivo sigue siendo el suyo.
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+export function crearCandados(fs, carpeta, pid, procesoVivo) {
+    return {
+        tomar(nombre) {
+            // El nombre lleva el id del proyecto y el nombre de la clave que eligió la persona: el hash lo vuelve
+            // un nombre de archivo sin barras ni puntos, sea lo que sea.
+            const ruta = path.join(carpeta, `${createHash("sha256").update(nombre).digest("hex")}.lock`);
+            const token = randomUUID();
+            let creado;
+            try {
+                fs.crearDir(carpeta, 0o700);
+                creado = fs.crearExclusivo(ruta, JSON.stringify({ pid, token }), 0o600);
+            }
+            catch {
+                return { tipo: "no_disponible", ruta };
+            }
+            if (!creado) {
+                let duenio = null;
+                try {
+                    const v = JSON.parse(fs.leer(ruta) ?? "null");
+                    duenio = typeof v?.pid === "number" ? v.pid : null;
+                }
+                catch {
+                    duenio = null;
+                }
+                // Un candado que no se entiende tampoco se toca: «abandonado» le pide a una persona que mire.
+                return duenio !== null && procesoVivo(duenio) ? { tipo: "ocupado" } : { tipo: "abandonado", ruta };
+            }
+            return {
+                tipo: "tomado",
+                soltar() {
+                    // Sólo si sigue siendo MÍO: si una persona lo borró y otro tomó uno nuevo, no se toca.
+                    try {
+                        const v = JSON.parse(fs.leer(ruta) ?? "null");
+                        if (v?.token === token)
+                            fs.borrar(ruta);
+                    }
+                    catch {
+                        /* best-effort: si no se pudo, queda abandonado y se informa con su ruta */
+                    }
+                },
+            };
+        },
+    };
+}