supcoflow 0.0.0-stage → 0.3.0

package/dist/comandos/proyecto.js

@@ -0,0 +1,213 @@
+// `supcoflow proyecto crear` y `proyecto ver`: el proyecto del repo de esta carpeta (o de `--repo`).
+// `crear` sale de una conexión ya confirmada (`repo conectar`) y deja `.supcoflow/proyecto.json` en la
+// raíz del repo para que la próxima herramienta sepa de qué proyecto se trata sin preguntarle al motor.
+import path from "node:path";
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { repoPedido } from "../repo-local.js";
+import { claveVigente } from "./clave-vigente.js";
+const PLAZO_DE_LECTURA_MS = 15_000;
+const OPERACION = "proyecto_crear";
+// Lo único que se lee de un `.supcoflow/proyecto.json` ajeno es su id, y sólo si tiene esta forma:
+// así lo que salga a la terminal no puede ser otra cosa que un id (Review Focus 11).
+const FORMA_DEL_ID = /^proj_[a-z0-9-]{1,80}$/;
+// Los 422/409 del alta que el plan no listaba (alta-desde-conexion.ts del motor).
+const RECHAZOS_DE_UNA_PERSONA = new Set(["instalacion_no_verificada", "repo_fuera_de_la_instalacion"]);
+const RECHAZOS_TRANSITORIOS = new Set(["slug_ocupado", "repo_ya_conectado"]);
+const fallo = (codigo, error, message, extra = {}) => ({
+    codigo, json: { ok: false, error, message, ...extra }, texto: message,
+});
+const comillas = (s) => `"${s.replace(/["\\]/g, "\\$&")}"`;
+// El archivo va al repo y se commitea (§5.3): por eso lleva sólo lo que identifica al proyecto. Ni la
+// URL de la API (un repo clonado que la trajera mandaría la clave a otro servidor, §5.2) ni nada
+// secreto: cualquiera que lea el repo lo lee.
+function contenidoDelArchivo(p) {
+    return JSON.stringify({ id: p.id, slug: p.slug, repo: p.repo }, null, 2) + "\n";
+}
+function idDelArchivo(crudo) {
+    try {
+        const v = JSON.parse(crudo);
+        if (typeof v !== "object" || v === null)
+            return null;
+        const id = v.id;
+        return typeof id === "string" && FORMA_DEL_ID.test(id) ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Mismo contenido aunque el formato cambie (otra indentación, otro orden): no es «otro proyecto».
+function mismoArchivo(crudo, p) {
+    if (crudo === contenidoDelArchivo(p))
+        return true;
+    try {
+        const v = JSON.parse(crudo);
+        if (typeof v !== "object" || v === null || Array.isArray(v))
+            return false;
+        const o = v;
+        return Object.keys(o).length === 3 && o.id === p.id && o.slug === p.slug && o.repo === p.repo;
+    }
+    catch {
+        return false;
+    }
+}
+function resultadoDelProyecto(p, reusado, raiz, d) {
+    const nuevo = { id: p.id, slug: p.slug, repo: p.repo };
+    const queda = reusado ? `El proyecto ${p.id} ya existía y lo reusé` : `Creé el proyecto ${p.id}`;
+    let archivo = null;
+    if (raiz !== null) {
+        archivo = path.join(raiz, ".supcoflow", "proyecto.json");
+        const actual = d.archivos.leer(archivo);
+        if (actual !== null && !mismoArchivo(actual, p)) {
+            // Un segundo `go` no pisa archivos (§13): el que está puede ser de otro proyecto a propósito, y
+            // pisarlo cambiaría en silencio a qué proyecto apunta el repo. Se sale 4 para que una persona
+            // decida. Su contenido NUNCA se copia a la salida (puede traer cualquier cosa, una clave
+            // incluida, y `emitir` no sanea): sólo el id, si tiene forma de id.
+            const idActual = idDelArchivo(actual);
+            const message = `Ya hay un \`.supcoflow/proyecto.json\` de otro proyecto (${idActual ?? "que no reconozco"}); no lo toqué. `
+                + `${queda} igual (${p.id}): si es el que querés, borrá el archivo y volvé a correr \`supcoflow proyecto crear\`.`;
+            return fallo(SALIDA.haceFaltaUnaPersona, "archivo_distinto", message, { archivo, id_actual: idActual, nuevo, reusado });
+        }
+        if (actual === null) {
+            try {
+                d.archivos.escribir(archivo, contenidoDelArchivo(p));
+            }
+            catch {
+                const message = `${queda} (${p.id}), pero no pude escribir ${archivo}. Volvé a correr \`supcoflow proyecto crear\`.`;
+                return fallo(SALIDA.inesperado, "archivo_no_escrito", message, { archivo, nuevo, reusado });
+            }
+        }
+    }
+    return {
+        codigo: SALIDA.ok,
+        json: { ok: true, proyecto: { id: p.id, slug: p.slug, repo: p.repo, rama: p.rama }, reusado, archivo },
+        texto: `${queda}: ${p.repo}, rama ${p.rama}.${archivo !== null ? ` Lo anoté en ${archivo}.` : ""}`,
+    };
+}
+export async function proyectoCrear(d, flags) {
+    let repo;
+    let raiz;
+    try {
+        ({ repo, raiz } = await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return leida.resultado;
+    const clave = leida.vigente.clave;
+    let existente;
+    let conexion = null;
+    try {
+        existente = await d.buscarProyecto(d.api, clave, repo);
+        if (existente === null)
+            conexion = await d.ultimaConexion(d.api, clave, repo, PLAZO_DE_LECTURA_MS);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    // Un repo con proyecto no vuelve a pasar por la conexión: el proyecto ya está atado a su instalación.
+    if (existente !== null) {
+        // Una clave guardada de un intento anterior (respuesta perdida, `en_curso`) ya no sirve: el proyecto
+        // existe. Si quedara, un alta futura del mismo repo (borrado y vuelto a crear) mandaría una clave
+        // vieja con otro contenido y el motor contestaría 409. Con --dry-run no se toca ni lo local.
+        if (!flags.dryRun)
+            await d.idempotencia.olvidar(OPERACION, repo);
+        if (flags.install !== null || flags.test !== null) {
+            // Sin copiar los valores: son texto del usuario y el aviso sólo dice qué pasó con ellos. Callarlo
+            // haría creer que el proyecto quedó con los comandos pedidos.
+            d.avisar("El proyecto ya existe: ignoré --install/--test. Para cambiar sus comandos hay que configurarlo.");
+        }
+        return resultadoDelProyecto(existente, true, raiz, d);
+    }
+    if (conexion === null || conexion.estado !== "conectado") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "repo_sin_conectar", "Conectá el repo primero: `supcoflow repo conectar`.", {
+            repo, ...(conexion !== null ? { estado: conexion.estado } : {}),
+        });
+    }
+    if (flags.dryRun) {
+        const haria = `POST /api/conexiones/${conexion.id}/proyecto`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, repo, haria }, texto: `Con --dry-run no hago nada; sin él, crearía el proyecto de ${repo} (${haria}).` };
+    }
+    const cuerpo = {};
+    if (flags.install !== null)
+        cuerpo.install_command = flags.install;
+    if (flags.test !== null)
+        cuerpo.test_command = flags.test;
+    const key = await d.idempotencia.claveDe(OPERACION, repo);
+    let alta;
+    try {
+        alta = await d.crearProyecto(d.api, clave, conexion.id, cuerpo, key);
+    }
+    catch (e) {
+        // La clave NO se olvida (Review Focus 4): sin respuesta no se sabe si el motor creó el proyecto, y
+        // el reintento tiene que mandar la misma para recibir el mismo en vez de otro.
+        return resultadoDeFallo(e);
+    }
+    switch (alta.tipo) {
+        case "ok":
+            await d.idempotencia.olvidar(OPERACION, repo);
+            return resultadoDelProyecto(alta.proyecto, alta.reusado, raiz, d);
+        case "comandos_faltantes": {
+            // Otro intento lleva otro contenido (los flags): con la misma clave el motor contestaría 409.
+            await d.idempotencia.olvidar(OPERACION, repo);
+            const install = flags.install ?? "…";
+            const test = flags.test ?? "…";
+            const message = `${alta.message || "Faltan comandos del proyecto."} Pasalos a mano: \`supcoflow proyecto crear --install ${comillas(install)} --test ${comillas(test)}\`.`;
+            return fallo(SALIDA.entradaInvalida, "comandos_faltantes", message, { faltantes: alta.faltantes });
+        }
+        case "no_conectada":
+            await d.idempotencia.olvidar(OPERACION, repo);
+            return fallo(SALIDA.haceFaltaUnaPersona, "repo_sin_conectar", alta.message || "Conectá el repo primero: `supcoflow repo conectar`.", { repo });
+        case "en_curso":
+            // Se conserva: el pedido en curso puede ser el nuestro y el reintento tiene que poder retomarlo.
+            return fallo(SALIDA.inesperado, "en_curso", "Otro pedido con esta clave está en curso; probá en un minuto.");
+        case "clave_reusada":
+            // No debería pasar (la clave es por repo y un reintento manda lo mismo); olvidarla deja reintentar limpio.
+            await d.idempotencia.olvidar(OPERACION, repo);
+            return fallo(SALIDA.inesperado, "clave_reusada", "El motor rechazó la clave de idempotencia guardada; la descarté, probá de nuevo.");
+        case "rechazo": {
+            // La clave se conserva: tras un rechazo el motor ya la soltó, y el próximo intento la reusa sin
+            // chocar. Lo que cambia es el código: no todo rechazo es culpa de lo que se escribió.
+            const message = alta.message || "El motor rechazó el pedido.";
+            if (RECHAZOS_DE_UNA_PERSONA.has(alta.error)) {
+                // Lo arregla alguien con permisos en GitHub (instalar la App, sumarle el repo): reintentar o
+                // cambiar flags no sirve, y un 3 haría que un asistente siguiera probando entradas.
+                return fallo(SALIDA.haceFaltaUnaPersona, alta.error, `${message} Revisá la instalación de la App en GitHub y volvé a conectar con \`supcoflow repo conectar\`.`);
+            }
+            // Dos altas al mismo tiempo, o un proyecto borrado en el medio: el mismo pedido otra vez anda.
+            if (RECHAZOS_TRANSITORIOS.has(alta.error))
+                return fallo(SALIDA.inesperado, alta.error, message);
+            return fallo(SALIDA.entradaInvalida, alta.error, message);
+        }
+    }
+}
+export async function proyectoVer(d, flags) {
+    let repo;
+    try {
+        repo = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).repo;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return leida.resultado;
+    const clave = leida.vigente.clave;
+    try {
+        const encontrado = await d.buscarProyecto(d.api, clave, repo);
+        if (encontrado === null) {
+            return { codigo: SALIDA.ok, json: { ok: true, repo, proyecto: null }, texto: "Este repo todavía no tiene proyecto: `supcoflow proyecto crear`." };
+        }
+        const { proyecto: p, github } = await d.leerProyecto(d.api, clave, encontrado.id);
+        const proyecto = { id: p.id, slug: p.slug, repo: p.repo, rama: p.rama, install_command: p.installCommand, test_command: p.testCommand };
+        return {
+            codigo: SALIDA.ok,
+            json: { ok: true, proyecto, github: { estado: github.estado, verificado_en: github.verificadoEn } },
+            texto: `${p.id} (${p.repo}, rama ${p.rama}): instala con \`${p.installCommand}\`, prueba con \`${p.testCommand}\`. GitHub: ${github.estado ?? "sin verificar"}.`,
+        };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/comandos/quien-soy.js

@@ -0,0 +1,43 @@
+import { FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "../contrato.js";
+import { claveVigente } from "./clave-vigente.js";
+export async function comandoQuienSoy(d) {
+    const origen = d.api.origin;
+    const leida = await claveVigente(d.guardado, origen);
+    if (!leida.ok)
+        return leida.resultado;
+    const vigente = leida.vigente;
+    if (!vigente.completa) {
+        const otro = vigente.fuente === "archivo" ? "el llavero del sistema" : "el archivo de credenciales";
+        d.avisar(`Uso la clave de ${vigente.fuente}, pero no pude leer ${otro}: puede haber guardada otra más nueva.`);
+    }
+    // Leer no cuesta nada y avisa de algo que la persona no vería de otro modo: claves viejas vivas.
+    try {
+        const { claves, completa } = await d.guardado.leerPorRevocar(origen);
+        if (claves.length > 0) {
+            d.avisar(`Hay ${claves.length} clave(s) anterior(es) anotadas para revocar; se reintenta en el próximo login o logout.`);
+        }
+        if (!completa)
+            d.avisar("No pude leer entera la lista de claves por revocar.");
+    }
+    catch {
+        d.avisar("No pude leer entera la lista de claves por revocar.");
+    }
+    let yo;
+    try {
+        yo = await d.quienSoy(d.api, vigente.clave);
+    }
+    catch (e) {
+        // Con la variable definida, «iniciá sesión de nuevo» no arregla nada: la variable sigue
+        // ganándole a la clave nueva. Hay que decir cuál es la que no vale.
+        if (e instanceof FalloDeLaTerminal && e.codigo === SALIDA.faltaLogin && vigente.fuente === "env") {
+            return resultadoDeFallo(new FalloDeLaTerminal(e.codigo, e.error, "La clave de SUPCOFLOW_TOKEN no vale: sacala de tu entorno o reemplazala por una vigente."));
+        }
+        return resultadoDeFallo(e);
+    }
+    const quien = yo.usuario?.login ?? yo.usuario?.email ?? yo.via;
+    return {
+        codigo: SALIDA.ok,
+        json: { ok: true, via: yo.via, equipo: yo.equipo, usuario: yo.usuario, proyecto: yo.proyecto, fuente: vigente.fuente },
+        texto: `${quien} en el equipo ${yo.equipo} (clave en ${vigente.fuente})`,
+    };
+}

package/dist/comandos/repo-conectar.js

@@ -0,0 +1,126 @@
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { repoPedido } from "../repo-local.js";
+import { PLAZO_MINIMO_DE_SONDEO_MS, TRAMO_MAXIMO_MS } from "../sondeo.js";
+import { claveVigente } from "./clave-vigente.js";
+export const INTERVALO_DE_CONEXION_MS = 5_000;
+const PLAZO_MAXIMO_DE_SONDEO_MS = 15_000;
+const PAUSA_ENTRE_TRAMOS_MS = 1_000;
+const fallo = (codigo, error, message, extra = {}) => ({
+    codigo, json: { ok: false, error, message, ...extra }, texto: message,
+});
+const datosDelPedido = (p) => ({ id: p.id, estado: p.estado, url: p.url, vence_en: p.venceEn });
+// El desenlace de un pedido ya leído. El JSON nunca lleva la clave: sólo el pedido y el repo.
+function resultadoDelPedido(repo, p, avisar) {
+    const pedido = datosDelPedido(p);
+    switch (p.estado) {
+        case "conectado":
+            return {
+                codigo: SALIDA.ok,
+                json: { ok: true, estado: "conectado", repo, repo_canonico: p.repoCanonico, pedido },
+                texto: `${p.repoCanonico ?? repo} está conectado.`,
+            };
+        case "repo_fuera_de_alcance": {
+            const message = `La App está instalada pero no alcanza a ${repo}: sumalo en GitHub y volvé a tocar Confirmar (${p.url}).`;
+            return fallo(SALIDA.haceFaltaUnaPersona, "repo_fuera_de_alcance", message, { repo, url: p.url, pedido });
+        }
+        case "vencido":
+            return fallo(SALIDA.haceFaltaUnaPersona, "pedido_vencido", "El pedido venció. Pedí otro con `supcoflow repo conectar --start`.", { repo, pedido });
+        case "pendiente": {
+            // Un motivo anotado no cierra el pedido: la persona puede reintentar desde la misma página.
+            if (p.fallo !== null)
+                avisar(`La última confirmación falló: ${p.fallo}.`);
+            return {
+                codigo: SALIDA.esperandoAUnaPersona,
+                json: { ok: false, esperando: "persona", repo, url: p.url, pedido, ...(p.fallo !== null ? { fallo: p.fallo } : {}) },
+                texto: `Abrí ${p.url}, instalá la App en GitHub si hace falta y tocá Confirmar.`,
+            };
+        }
+    }
+}
+export async function repoConectarStart(d, flags) {
+    let repo;
+    try {
+        repo = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).repo;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    if (flags.dryRun) {
+        return {
+            codigo: SALIDA.ok,
+            json: { ok: true, dry_run: true, repo, haria: "POST /api/conexiones" },
+            texto: `Con --dry-run no hago nada; sin él, pediría conectar ${repo} (POST /api/conexiones).`,
+        };
+    }
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return leida.resultado;
+    let p;
+    try {
+        p = await d.crearConexion(d.api, leida.vigente.clave, repo);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    return resultadoDelPedido(repo, p, d.avisar);
+}
+export async function repoConectarWait(d, flags) {
+    let repo;
+    try {
+        repo = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).repo;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return leida.resultado;
+    const clave = leida.vigente.clave;
+    const limite = d.ahora() + Math.min(d.tramoMs ?? TRAMO_MAXIMO_MS, TRAMO_MAXIMO_MS);
+    let ultimo = null;
+    for (;;) {
+        const plazoMs = Math.min(PLAZO_MAXIMO_DE_SONDEO_MS, limite - d.ahora());
+        if (plazoMs < PLAZO_MINIMO_DE_SONDEO_MS && ultimo !== null)
+            break;
+        let p;
+        try {
+            // Un fallo del motor en medio del tramo sale 1 y no se reintenta en silencio (P13): quien llama
+            // decide si vuelve.
+            p = await d.ultimaConexion(d.api, clave, repo, Math.max(plazoMs, PLAZO_MINIMO_DE_SONDEO_MS));
+        }
+        catch (e) {
+            return resultadoDeFallo(e);
+        }
+        if (p === null) {
+            return fallo(SALIDA.entradaInvalida, "sin_conexion_en_curso", `No hay una conexión en curso para ${repo}: empezá con \`supcoflow repo conectar --start\`.`, { repo });
+        }
+        ultimo = p;
+        if (p.estado !== "pendiente")
+            break;
+        // Dormir sólo si después cabe otro sondeo con plazo útil: dormir de más pasaría del tramo.
+        if (limite - (d.ahora() + INTERVALO_DE_CONEXION_MS) < PLAZO_MINIMO_DE_SONDEO_MS)
+            break;
+        await d.dormir(INTERVALO_DE_CONEXION_MS);
+    }
+    return resultadoDelPedido(repo, ultimo, d.avisar);
+}
+// La conexión de una persona frente a la terminal: los dos pasos encadenados. Con `--json` (o sin TTY)
+// no se espera a nadie aunque haya terminal (§13, Review Focus 9): un asistente con PTY recibiría un
+// comando que se cuelga hasta 30 minutos. Y se decide ANTES de tocar el motor, para no dejar un pedido
+// que nadie va a mirar.
+export async function repoConectarInteractivo(d, flags) {
+    if (!d.esTty || flags.json) {
+        return fallo(SALIDA.entradaInvalida, "hace_falta_tty", "Sin terminal interactiva usá `supcoflow repo conectar --start --json` y después `supcoflow repo conectar --wait --json`.");
+    }
+    const inicio = await repoConectarStart(d, flags);
+    if (inicio.codigo !== SALIDA.esperandoAUnaPersona)
+        return inicio;
+    d.mostrar(`${inicio.texto} Espero acá…`);
+    let r;
+    do {
+        r = await repoConectarWait(d, flags);
+        if (r.codigo === SALIDA.esperandoAUnaPersona)
+            await d.dormir(PAUSA_ENTRE_TRAMOS_MS);
+    } while (r.codigo === SALIDA.esperandoAUnaPersona);
+    return r;
+}

package/dist/contrato.js

@@ -0,0 +1,38 @@
+// El contrato de salida de la terminal (§13). Quien la llama es, muchas veces, un asistente
+// que lee el código de salida y la ÚLTIMA línea de stdout: por eso un resultado es siempre
+// UNA línea de JSON, y un 5 no es un error sino «volvé a llamarme cuando la persona termine».
+export const SALIDA = {
+    ok: 0,
+    inesperado: 1,
+    faltaLogin: 2,
+    entradaInvalida: 3,
+    haceFaltaUnaPersona: 4,
+    esperandoAUnaPersona: 5,
+    topeAlcanzado: 6,
+};
+export class FalloDeLaTerminal extends Error {
+    codigo;
+    error;
+    constructor(codigo, error, message) {
+        super(message);
+        this.codigo = codigo;
+        this.error = error;
+        this.name = "FalloDeLaTerminal";
+    }
+}
+// JSON.stringify escapa los saltos de línea de los valores, así que la salida cabe en una línea.
+export function emitir(r, modoJson, out) {
+    out(modoJson ? JSON.stringify(r.json) + "\n" : r.texto + "\n");
+}
+// Un mensaje de error de afuera (fetch, el sistema) podría traer la clave o el device_code
+// tal cual; la clave se tapa ANTES que los 64 hex porque los contiene.
+export function taparSecretos(s) {
+    return s.replace(/scf_[0-9a-f]{16}_[0-9a-f]{64}/g, "scf_…").replace(/\b[0-9a-f]{64}\b/g, "[device_code]");
+}
+export function resultadoDeFallo(e) {
+    if (e instanceof FalloDeLaTerminal) {
+        return { codigo: e.codigo, json: { ok: false, error: e.error, message: e.message }, texto: e.message };
+    }
+    const message = taparSecretos(e instanceof Error ? e.message : String(e));
+    return { codigo: SALIDA.inesperado, json: { ok: false, error: "inesperado", message }, texto: message };
+}