supcoflow 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,83 @@
-# 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.
+
+Por ahora trae lo básico: iniciar y cerrar sesión, y ver con qué cuenta estás.
+
+## 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 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.
+
+### 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 quien-soy --json
+supcoflow logout --dry-run         # qué revocaría, sin revocar nada
+```
+
+## 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`). `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`.
+
+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,133 @@
+// Los cuatro pedidos de la terminal al motor. Sin dependencias: `fetch` viene de Node y se inyecta.
+import { FalloDeLaTerminal, SALIDA } 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.1.0); sólo identifica a la terminal
+// en los logs del motor, no decide nada.
+const VERSION = "0.1.0";
+const PLAZO_POR_DEFECTO_MS = 15_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. 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.
+            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);
+}

package/dist/argumentos.js

@@ -0,0 +1,43 @@
+import { parseArgs } from "node:util";
+import { FalloDeLaTerminal, SALIDA } from "./contrato.js";
+// 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" },
+            },
+        });
+    }
+    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\`.`);
+    }
+    if (parsed.positionals.length > 1) {
+        throw new FalloDeLaTerminal(SALIDA.entradaInvalida, "argumentos_de_mas", "Pasaste más de un comando. Probá `supcoflow --help`.");
+    }
+    const v = parsed.values;
+    return {
+        comando: parsed.positionals[0] ?? null,
+        flags: {
+            json: v.json === true,
+            dryRun: v["dry-run"] === true,
+            help: v.help === true,
+            start: v.start === true,
+            wait: v.wait === true,
+        },
+    };
+}

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// El binario `supcoflow`: lee los argumentos, arma el entorno real y despacha. Todo va dentro de un
+// solo try/catch: cualquier cosa que se escape (un archivo de credenciales ilegible, un llavero roto)
+// 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 { ayuda, comandoDescribir, DESCRIPCION } from "./comandos/describir.js";
+import { loginInteractivo, loginStart, loginWait } from "./comandos/login.js";
+import { comandoLogout } from "./comandos/logout.js";
+import { comandoQuienSoy } from "./comandos/quien-soy.js";
+import { emitir, FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "./contrato.js";
+import { entornoReal } from "./entorno.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) {
+    // Si los argumentos no se pueden leer no se sabe qué flags hay: se mira `--json` a mano para que
+    // el error salga en el formato que pidió quien llama.
+    let json = argv.includes("--json");
+    try {
+        const { comando, flags } = leerArgumentos(argv);
+        json = flags.json;
+        if (comando !== null && !COMANDOS.has(comando)) {
+            throw invalida("comando_desconocido", `No conozco el comando «${comando}». Probá \`supcoflow --help\`.`);
+        }
+        if (flags.help || comando === null) {
+            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`.");
+        }
+        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) {
+                throw invalida("dry_run_no_soportado", "`login --wait` no tiene --dry-run: sondear consume el código. Probá `supcoflow login --start --dry-run`.");
+            }
+        }
+        const e = entornoReal();
+        switch (comando) {
+            case "login":
+                if (flags.start)
+                    return { r: await loginStart(e.login, flags), json };
+                if (flags.wait)
+                    return { r: await loginWait(e.login), json };
+                // Sin TTY, `login --dry-run` igual tiene algo que decir: lo que haría el primer paso.
+                if (flags.dryRun)
+                    return { r: await loginStart(e.login, { dryRun: true }), json };
+                return { r: await loginInteractivo({ ...e.login, esTty: e.esTty, mostrar: e.mostrar }, flags), json };
+            case "logout":
+                return {
+                    r: await comandoLogout({
+                        api: e.api, guardado: e.guardado, ahora: e.login.ahora, avisar: e.avisar,
+                        revocarPropia: (a, clave, plazoMs) => revocarPropia(a, clave, fetch, plazoMs),
+                    }, flags),
+                    json,
+                };
+            case "quien-soy":
+                return { r: await comandoQuienSoy({ api: e.api, guardado: e.guardado, quienSoy: e.quienSoy, avisar: e.avisar }), json };
+        }
+        throw new Error(`comando sin despacho: ${comando}`);
+    }
+    catch (e) {
+        return { r: resultadoDeFallo(e), json };
+    }
+}
+// `process.exitCode` y nunca `process.exit()`: éste corta el proceso con stdout a medio escribir
+// cuando la salida va a un pipe, y quien llama leería una línea de JSON partida.
+const { r, json } = await correr(process.argv.slice(2));
+emitir(r, json, (s) => void process.stdout.write(s));
+process.exitCode = r.codigo;

package/dist/comandos/describir.js

@@ -0,0 +1,106 @@
+// `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.1.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],
+        },
+    ],
+    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");
+}