supcoflow 0.1.0 → 0.5.0

package/README.md

@@ -3,7 +3,8 @@
 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.
 
-Por ahora trae lo básico: iniciar y cerrar sesión, y ver con qué cuenta estás.
+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
 
@@ -22,9 +23,24 @@ npx supcoflow login
 | `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 guia revisar` | Revisa `.supcoflow/guia.md` contra el motor sin publicar nada. |
+| `supcoflow guia publicar` | Sube `.supcoflow/guia.md` directo (con el commit y la rama que declara tu clon, no verificados en GitHub). `--desde-github` verifica contra la rama principal en vez de subir el archivo. |
+| `supcoflow guia ver` | Muestra la guía activa, de dónde viene y si la rama sigue al día. |
+| `supcoflow guia usar --origen repo\|agente` | Elige cuál guía queda activa. |
 | `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.
+`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
 
@@ -36,10 +52,71 @@ supcoflow login
 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 (hace falta una guía: publicá la del repo con `supcoflow guia publicar` o generá y aprobá la de nuestro agente en Brain). |
+| `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. |
+
+## La guía
+
+La guía le cuenta al chat qué hace cada pantalla de tu producto. Vive en el repo, en
+`.supcoflow/guia.md` (en la raíz). El flujo, en este orden:
+
+1. `supcoflow guia revisar`: la revisa contra el motor sin publicar nada (si está mal armada, sale 3 con la línea de cada error).
+2. `supcoflow guia publicar`: sube el archivo directo y queda como guía activa. Manda también el commit y la rama de tu
+   clon (`git rev-parse HEAD`, si hay git y commits; si no, va sin commit): son declarados por la terminal, no
+   verificados en GitHub, y así se muestran. Repetir con el mismo archivo no duplica.
+3. Opcional, `supcoflow guia publicar --desde-github`: no sube el archivo; manda su huella y el motor la compara con la
+   de la rama principal de GitHub (commit verificado). Si todavía no está subida (o la rama tiene otra), sale 5:
+   subí la guía a la rama principal y volvé a correr.
+
+`supcoflow guia ver` muestra la guía activa y si la rama sigue al día (`al_dia` en el JSON);
+`supcoflow guia usar --origen repo|agente` elige cuál queda activa cuando hay una del repo y otra de nuestro agente.
+Todos toman el repo del `origin`, o `--repo owner/repo` (con `revisar` y `publicar`, sin clon local de ese repo sale 3 `falta_guia`: la guía se lee del archivo); `revisar`, `publicar` y `usar` aceptan `--dry-run`; `--desde-github` es sólo de `publicar`.
+
+El formato de `.supcoflow/guia.md`:
+
+```markdown
+# Guía de Mi App            ← opcional; se ignora
+
+## Facturas                 ← una sección por pantalla o función (1 a 60). Nombre: 1–120 caracteres
+Para qué sirve: Ver y pagar las facturas del mes.             ← obligatorio, 1–600
+Qué puede hacer el usuario: Descargar el PDF, pagar con       ← obligatorio, 1–600; puede seguir
+tarjeta y ver el historial.                                       en las líneas de abajo
+Problemas comunes:                                            ← opcional; hasta 10, cada uno 1–300
+- El botón Pagar no responde con tarjetas de débito.
+- El PDF sale en blanco en Safari.
+```
+
+- Las etiquetas se reconocen al principio de la línea, sin distinguir mayúsculas y con o sin tildes
+  («Para que sirve:» vale). Una línea que no es etiqueta continúa el campo anterior (se une con un espacio).
+- Texto antes del primer `## ` que no sea el `# ` del título → error. Una etiqueta repetida en una sección →
+  error. Una línea con `<` o `>` → error. Más de 64 KB → `guia_muy_grande`.
+
 ## El contrato
 
 Pensado para que lo lea un programa, no sólo una persona:
@@ -48,7 +125,8 @@ Pensado para que lo lea un programa, no sólo una persona:
   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`). `login --wait
+- **`--dry-run`** donde se puede simular (`login`, `login --start`, `logout`, `repo conectar --start`,
+  `proyecto crear`, `guia revisar`, `guia publicar`, `guia usar`). `login --wait
   --dry-run` sale 3: sondear consume el código y no hay cómo simularlo.
 
 | Código | Quiere decir |
@@ -70,6 +148,8 @@ Pensado para que lo lea un programa, no sólo una persona:
   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`.

package/dist/api.js

@@ -1,5 +1,5 @@
-// Los cuatro pedidos de la terminal al motor. Sin dependencias: `fetch` viene de Node y se inyecta.
-import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
+// 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.
@@ -21,10 +21,14 @@ export function urlDeLaApi(env) {
         return new URL(u.origin);
     throw invalida();
 }
-// A mano a propósito: tiene que coincidir con package.json (0.1.0); sólo identifica a la terminal
+// A mano a propósito: tiene que coincidir con package.json (0.5.0); sólo identifica a la terminal
 // en los logs del motor, no decide nada.
-const VERSION = "0.1.0";
+const VERSION = "0.5.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).
@@ -37,8 +41,9 @@ async function pedir(api, ruta, init, f, plazoMs) {
             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. Los cuatro endpoints del motor nunca redirigen: una redirección es
-            // anómala y sale como `motor_inalcanzable`, sin Location ni cuerpo en el mensaje.
+            // 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();
@@ -131,3 +136,179 @@ export async function revocarPropia(api, clave, f, plazoMs) {
         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;
+}
+// ---- La guía (bloque 5) ----
+// Devuelven la respuesta entera: qué significa cada 409/422 lo decide el comando (`guia_no_subida` es
+// un código de salida propio; `guia_mal_armada` lleva la lista de errores por línea).
+const rutaDeLaGuia = (proyectoId) => `/api/proyectos/${encodeURIComponent(proyectoId)}/guia`;
+export function revisarGuia(api, clave, proyectoId, contenido, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/revisar`, { method: "POST", headers: JSON_BODY, body: JSON.stringify({ contenido }) }, f);
+}
+export function publicarGuia(api, clave, proyectoId, cuerpo, f) {
+    // La vía de GitHub acuña con Connect y le pregunta a GitHub por la rama: el mismo plazo que las altas (la directa no
+    // llama a GitHub, pero comparte el plazo para no tener dos reglas).
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/publicar`, { method: "POST", headers: JSON_BODY, body: JSON.stringify(cuerpo) }, f, PLAZO_DE_ALTA_MS);
+}
+// Siempre con `comprobar=1`: `guia ver` quiere el `al_dia` de la rama; el motor lo ignora si el origen no es el repo.
+export function leerGuia(api, clave, proyectoId, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}?comprobar=1`, { method: "GET" }, f, PLAZO_DE_ALTA_MS);
+}
+export function elegirOrigen(api, clave, proyectoId, origen, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/origen`, { method: "POST", headers: JSON_BODY, body: JSON.stringify({ origen }) }, f);
+}

package/dist/argumentos.js

@@ -1,5 +1,16 @@
 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",
+    "guia revisar", "guia publicar", "guia ver", "guia usar",
+];
+// 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", "origen",
+];
 // 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) {
@@ -15,7 +26,23 @@ export function leerArgumentos(argv) {
                 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" },
+                origen: { type: "string" },
+                "desde-github": { type: "boolean" },
+                tema: { type: "string", multiple: true },
             },
+            tokens: true,
         });
     }
     catch (e) {
@@ -26,18 +53,51 @@ export function leerArgumentos(argv) {
         }
         throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_invalidos", `${e.message} Probá \`supcoflow --help\`.`);
     }
-    if (parsed.positionals.length > 1) {
-        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_de_mas", "Pasaste más de un comando. 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: parsed.positionals[0] ?? null,
+        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,
+            origen: v.origen ?? null,
+            desdeGithub: v["desde-github"] === true,
+            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 */
+                    }
+                },
+            };
+        },
+    };
+}

package/dist/cli.js

@@ -4,12 +4,19 @@
 // sale como un 1 limpio, en una línea si se pidió --json, sin traza y con los secretos tapados.
 import { revocarPropia } from "./api.js";
 import { leerArgumentos } from "./argumentos.js";
+import { clavesCrear, clavesListar, clavesRevocar } from "./comandos/claves.js";
+import { chatLogo, chatMarca, chatPrenderApagar, comandoConfiguracion, sitios } from "./comandos/configurar.js";
+import { guiaPublicar, guiaRevisar, guiaUsar, guiaVer } from "./comandos/guia.js";
+import { comandoCatalogo, datosFijar, politicaFijar } from "./comandos/datos-y-politica.js";
 import { ayuda, comandoDescribir, DESCRIPCION } from "./comandos/describir.js";
 import { loginInteractivo, loginStart, loginWait } from "./comandos/login.js";
 import { comandoLogout } from "./comandos/logout.js";
+import { proyectoCrear, proyectoVer } from "./comandos/proyecto.js";
 import { comandoQuienSoy } from "./comandos/quien-soy.js";
+import { repoConectarInteractivo, repoConectarStart, repoConectarWait } from "./comandos/repo-conectar.js";
 import { emitir, FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "./contrato.js";
 import { entornoReal } from "./entorno.js";
+import { flagQueNoAplica } from "./flags-por-comando.js";
 const COMANDOS = new Set(DESCRIPCION.comandos.map((c) => c.nombre));
 const invalida = (error, message) => new FalloDeLaTerminal(SALIDA.entradaInvalida, error, message);
 async function correr(argv) {
@@ -26,15 +33,21 @@ async function correr(argv) {
             const texto = ayuda(comando);
             return { r: { codigo: SALIDA.ok, json: { ok: true, ayuda: texto }, texto }, json };
         }
-        if ((flags.start || flags.wait) && comando !== "login") {
-            throw invalida("flag_no_aplica", "--start y --wait son sólo de `supcoflow login`.");
+        const presentes = {
+            start: flags.start, wait: flags.wait, repo: flags.repo !== null, install: flags.install !== null, test: flags.test !== null,
+            sitio: flags.sitio !== null, titulo: flags.titulo !== null, saludo: flags.saludo !== null, tema: flags.tema.length > 0,
+            archivo: flags.archivo !== null, permitir: flags.permitir !== null, modo: flags.modo !== null,
+            nombre: flags.nombre !== null, guardarEn: flags.guardarEn !== null, id: flags.id !== null, origen: flags.origen !== null, desdeGithub: flags.desdeGithub,
+        };
+        const noAplica = flagQueNoAplica(comando, Object.keys(presentes).filter((k) => presentes[k]));
+        if (noAplica !== null)
+            throw invalida("flag_no_aplica", noAplica);
+        if (flags.start && flags.wait) {
+            throw invalida("flags_incompatibles", "--start y --wait van por separado: primero uno y después el otro.");
         }
         if (comando === "describir")
             return { r: comandoDescribir(), json };
         if (comando === "login") {
-            if (flags.start && flags.wait) {
-                throw invalida("flags_incompatibles", "--start y --wait van por separado: primero uno y después el otro.");
-            }
             // ANTES de armar el entorno: no hay cómo simular un canje sin consumirlo, y este error no
             // puede depender de leer nada guardado ni de llamar al motor.
             if (flags.wait && flags.dryRun) {
@@ -62,6 +75,54 @@ async function correr(argv) {
                 };
             case "quien-soy":
                 return { r: await comandoQuienSoy({ api: e.api, guardado: e.guardado, quienSoy: e.quienSoy, avisar: e.avisar }), json };
+            case "repo conectar":
+                if (flags.start)
+                    return { r: await repoConectarStart(e.conexion, flags), json };
+                // `--wait` sólo lee (un GET por tramo): con --dry-run haría lo mismo, así que no se rechaza.
+                if (flags.wait)
+                    return { r: await repoConectarWait(e.conexion, flags), json };
+                // Como `login`: sin TTY, --dry-run igual dice lo que haría el primer paso, sin tocar el motor.
+                if (flags.dryRun)
+                    return { r: await repoConectarStart(e.conexion, { repo: flags.repo, dryRun: true }), json };
+                return { r: await repoConectarInteractivo({ ...e.conexion, esTty: e.esTty, mostrar: e.mostrar }, flags), json };
+            case "proyecto crear":
+                return { r: await proyectoCrear(e.proyecto, flags), json };
+            case "proyecto ver":
+                return { r: await proyectoVer(e.proyecto, flags), json };
+            case "catalogo":
+                return { r: await comandoCatalogo(e.configurar), json };
+            case "configuracion":
+                return { r: await comandoConfiguracion(e.configurar, flags), json };
+            case "chat prender":
+                return { r: await chatPrenderApagar(e.configurar, flags, true), json };
+            case "chat apagar":
+                return { r: await chatPrenderApagar(e.configurar, flags, false), json };
+            case "chat marca":
+                return { r: await chatMarca(e.configurar, flags), json };
+            case "chat logo":
+                return { r: await chatLogo(e.configurar, flags), json };
+            case "sitios agregar":
+                return { r: await sitios(e.configurar, flags, "agregar"), json };
+            case "sitios quitar":
+                return { r: await sitios(e.configurar, flags, "quitar"), json };
+            case "datos fijar":
+                return { r: await datosFijar(e.configurar, flags), json };
+            case "politica fijar":
+                return { r: await politicaFijar(e.configurar, flags), json };
+            case "claves crear":
+                return { r: await clavesCrear(e.claves, flags), json };
+            case "claves listar":
+                return { r: await clavesListar(e.claves, flags), json };
+            case "claves revocar":
+                return { r: await clavesRevocar(e.claves, flags), json };
+            case "guia revisar":
+                return { r: await guiaRevisar(e.guia, flags), json };
+            case "guia publicar":
+                return { r: await guiaPublicar(e.guia, flags), json };
+            case "guia ver":
+                return { r: await guiaVer(e.guia, flags), json };
+            case "guia usar":
+                return { r: await guiaUsar(e.guia, flags), json };
         }
         throw new Error(`comando sin despacho: ${comando}`);
     }

package/dist/comandos/clave-vigente.js

@@ -0,0 +1,18 @@
+// La clave con la que la terminal le habla al motor, leída igual para todo comando que la necesite
+// (`quien-soy`, `repo conectar`, …): un solo lugar decide qué es «sin sesión» y qué es «no pude mirar».
+import { SALIDA } from "../contrato.js";
+export async function claveVigente(guardado, origen) {
+    const lectura = await guardado.leerClaveCompleta(origen);
+    const vigente = lectura.valor;
+    // «Iniciá sesión» con la clave guardada en un llavero que no contestó invita a un login que la
+    // pisaría: no es «sin sesión», es «no pude mirar» (Review Focus 12).
+    if (vigente === null && !lectura.completa) {
+        const message = "No pude leer la clave guardada (el llavero no respondió). Desbloquealo y probá de nuevo.";
+        return { ok: false, resultado: { codigo: SALIDA.inesperado, json: { ok: false, error: "llavero_no_responde", message }, texto: message } };
+    }
+    if (vigente === null) {
+        const message = "Iniciá sesión con `supcoflow login`.";
+        return { ok: false, resultado: { codigo: SALIDA.faltaLogin, json: { ok: false, error: "sin_sesion", message }, texto: message } };
+    }
+    return { ok: true, vigente: { clave: vigente.clave, fuente: vigente.fuente, completa: lectura.completa } };
+}