supcoflow 0.1.0 → 0.5.0

package/dist/comandos/describir.js

@@ -3,7 +3,7 @@
 // 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";
+const VERSION = "0.5.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -40,17 +40,187 @@ export const DESCRIPCION = {
             ejemplos: ["supcoflow describir --json"],
             codigos: [0],
         },
+        {
+            nombre: "repo conectar",
+            resumen: "Conecta el repo de esta carpeta (o el de --repo) con la App de GitHub: una persona lo confirma en la consola. Sin terminal interactiva, en dos pasos: --start y después --wait.",
+            flags: [
+                "--start: pide la conexión y sale 5 con la URL para confirmarla",
+                "--wait: espera la confirmación hasta 90 s; sale 5 si todavía no llegó (volvé a llamarlo)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué pediría sin pedir nada (--wait sólo lee)",
+                "--json",
+            ],
+            ejemplos: ["supcoflow repo conectar", "supcoflow repo conectar --start --json", "supcoflow repo conectar --wait --json"],
+            codigos: [0, 1, 2, 3, 4, 5],
+        },
+        {
+            nombre: "proyecto crear",
+            resumen: "Crea (o reusa) el proyecto del repo ya conectado y lo anota en .supcoflow/proyecto.json; un archivo distinto nunca se pisa (sale 4).",
+            flags: [
+                "--install \"…\": el comando de instalación, cuando el motor no lo puede deducir",
+                "--test \"…\": el comando de pruebas, ídem",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin escribir el archivo)",
+                "--dry-run: dice qué crearía sin crear nada",
+                "--json",
+            ],
+            ejemplos: ["supcoflow proyecto crear --json", "supcoflow proyecto crear --install \"pnpm i\" --test \"pnpm test\""],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "proyecto ver",
+            resumen: "Muestra el proyecto del repo: rama, comandos y el estado de la App de GitHub; null si todavía no tiene.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow proyecto ver --json"],
+            codigos: [0, 1, 2, 3],
+        },
+        {
+            nombre: "catalogo",
+            resumen: "Lista lo que se puede configurar en el chat (claves y valores admitidos) y el estado del contrato de la App.",
+            flags: ["--json"],
+            ejemplos: ["supcoflow catalogo --json"],
+            codigos: [0, 1, 2, 3],
+        },
+        {
+            nombre: "configuracion",
+            resumen: "Muestra la configuración del proyecto del repo: chat, sitios, marca, política de problemas y acuerdo de datos. El acuerdo frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow configuracion --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat prender",
+            resumen: "Prende el chat de soporte del proyecto. Hace falta una guía vigente (la publicada del repo o la aprobada de nuestro agente); si no, sale 4 (skill_no_aprobada).",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat prender --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat apagar",
+            resumen: "Apaga el chat de soporte del proyecto.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat apagar --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat marca",
+            resumen: "Cambia título, saludo y colores del chat; lo que no nombrás queda como estaba.",
+            flags: [
+                "--titulo \"…\": el título del chat",
+                "--saludo \"…\": el saludo inicial",
+                "--tema clave=valor: un color o ajuste del tema (se repite, uno por clave)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow chat marca --titulo \"Ayuda\" --tema acento=#0a7"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "chat logo",
+            resumen: "Sube el logo del chat (.png, .jpg o .webp, hasta 200 KB).",
+            flags: ["--archivo ruta: la imagen", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow chat logo --archivo logo.png --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "sitios agregar",
+            resumen: "Agrega un sitio desde el que el chat puede cargarse.",
+            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow sitios agregar --sitio https://app.ejemplo.com"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "sitios quitar",
+            resumen: "Quita un sitio de los que pueden cargar el chat.",
+            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow sitios quitar --sitio https://app.ejemplo.com"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "datos fijar",
+            resumen: "Fija el acuerdo de datos: qué datos pasan. Frena lo que se guarda y lo que lee la IA que releva el repo; no cubre lo que ve la IA del chat mientras conversa.",
+            flags: [
+                "--permitir lista: datos que pasan, separados por coma (usuario_id, usuario_rol, pagina_y_navegador, capturas, elementos, email, atributo:nombre) o `nada`",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow datos fijar --permitir usuario_id,atributo:plan"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "politica fijar",
+            resumen: "Fija qué hace el motor con un problema que llega por el chat: relevarlo en el acto (gasta) o guardarlo. Guardar frena sólo lo automático del chat: desde la consola una persona puede pedir el relevamiento, y cuesta.",
+            flags: ["--modo relevar|guardar", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow politica fijar --modo guardar"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves crear",
+            resumen: "Crea una clave de consulta (sólo lee su proyecto) y la guarda en un archivo 0600 fuera de todo repo; el secreto nunca sale por la salida.",
+            flags: [
+                "--nombre ci: para qué es la clave",
+                "--guardar-en ruta: el archivo donde queda (fuera de un repo; si ya tiene otra cosa sale 4 y no lo toca)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
+                "--dry-run: dice qué haría sin hacerlo",
+                "--json",
+            ],
+            ejemplos: ["supcoflow claves crear --nombre ci --guardar-en ~/ci.key --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves listar",
+            resumen: "Lista las claves de consulta activas del proyecto (id, nombre, fecha; nunca el secreto).",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow claves listar --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "claves revocar",
+            resumen: "Revoca una clave de consulta por su id; revocar dos veces deja lo mismo.",
+            flags: ["--id cla_…: la clave (la da `claves listar`)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow claves revocar --id cla_0123456789abcdef --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "guia revisar",
+            resumen: "Revisa .supcoflow/guia.md (la raíz de este clon) contra el motor, sin publicar nada: dice si está bien armada y cuántas secciones tiene. Es el paso antes del commit.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 falta_guia: la guía se lee del archivo)", "--dry-run: dice qué mandaría sin mandarlo", "--json"],
+            ejemplos: ["supcoflow guia revisar --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "guia publicar",
+            resumen: "Sube .supcoflow/guia.md directo: manda el contenido y el commit y la rama que declara este clon (si hay git y commits; si no, sin commit). El motor la revisa y la deja como guía activa; el commit queda como «declarado por la terminal, no verificado en GitHub». Con --desde-github conserva la vía anterior: manda la huella y el motor la compara con la de la rama principal; si todavía no está subida a esa rama (o es otra), sale 5.",
+            flags: ["--desde-github: no sube el archivo; verifica contra la rama principal de GitHub (sale 5 guia_no_subida / guia_distinta si no coincide)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 falta_guia: la guía se lee del archivo)", "--dry-run: dice qué mandaría (o la huella con --desde-github), sin pedir nada", "--json"],
+            ejemplos: ["supcoflow guia publicar --json"],
+            codigos: [0, 1, 2, 3, 4, 5],
+        },
+        {
+            nombre: "guia ver",
+            resumen: "Muestra la guía activa del proyecto, de dónde viene y si la rama principal sigue teniendo esa versión (`al_dia` en el JSON).",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
+            ejemplos: ["supcoflow guia ver --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "guia usar",
+            resumen: "Elige cuál guía queda activa cuando hay dos: la del repo o la de nuestro agente.",
+            flags: ["--origen repo|agente: cuál queda activa (obligatorio)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
+            ejemplos: ["supcoflow guia usar --origen repo --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
     ],
     flags_globales: ["--json: el resultado en una línea de JSON por stdout; los avisos van por stderr", "--help, -h: la ayuda con ejemplos"],
     facultades: [
         {
             nombre: "consultar",
-            incluye: "Identidad y equipo, proyectos, configuración, casos, issues, runs, costos, estado de la instalación",
+            incluye: "Identidad y equipo, proyectos, configuración, casos, issues, runs, costos, estado de la instalación, leer y revisar la guía (guia revisar, guia ver)",
             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",
+            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, elegir la guía activa (guia usar), 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 },

package/dist/comandos/guia.js

@@ -0,0 +1,244 @@
+// src/comandos/guia.ts
+// `guia revisar|publicar|ver|usar` (bloque 5): la guía del producto que vive en el repo del cliente
+// (`.supcoflow/guia.md`). La terminal NO decide qué es una guía buena —eso lo decide el parser del motor—;
+// lee el archivo, manda UN pedido y traduce la respuesta a los códigos de salida del contrato.
+import path from "node:path";
+import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { huellaDeGuia, MAX_BYTES_DE_LA_GUIA, RUTA_DE_LA_GUIA } from "../guia.js";
+import { repoPedido } from "../repo-local.js";
+import { desenlace, fallo, rutaDe } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+// Texto que viene del motor (o del repo, vía el motor) y sale a la terminal de una persona: sin secretos y sin
+// caracteres de control (C0, DEL, C1), que un ESC movería el cursor. Texto y JSON salen del mismo texto ya limpio.
+// Primero se quita el control y recién después se tapan los secretos: al revés, una clave partida por un
+// control (U+0085, por ejemplo) quedaba entera al quitarlo y se imprimía sin tapar.
+const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""));
+const cadena = (v) => (typeof v === "string" ? limpio(v) : "");
+const corto = (commit) => cadena(commit).slice(0, 7);
+const secciones = (n) => (typeof n === "number" ? `${n} ${n === 1 ? "sección" : "secciones"}` : "secciones sin contar");
+const NOMBRE_DEL_ORIGEN = { repo: "la del repo", agente: "la de nuestro agente" };
+// ─── El archivo local ───
+// Se busca en la raíz de ESTE clon, nunca en el cwd: parado en una subcarpeta sigue siendo la guía del repo.
+// Con `--repo` y sin clon de ese repo no hay dónde leerla (publicar lee la rama, pero la huella sale del archivo).
+async function leerLaGuia(d, flags) {
+    let raiz;
+    try {
+        raiz = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+    }
+    catch (e) {
+        return { ok: false, resultado: resultadoDeFallo(e) };
+    }
+    if (raiz === null) {
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `No tengo el clon de ese repo acá, y la guía se lee de ${RUTA_DE_LA_GUIA}: parate en el clon del repo.`) };
+    }
+    const leido = d.leerArchivoChico(path.join(raiz, RUTA_DE_LA_GUIA), MAX_BYTES_DE_LA_GUIA);
+    if ("error" in leido) {
+        if (leido.error === "no existe")
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `Falta ${RUTA_DE_LA_GUIA} en el repo: escribila (una sección por pantalla) y volvé a correr.`) };
+        if (leido.error === "es demasiado grande")
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_muy_grande", `${RUTA_DE_LA_GUIA} pasa los ${MAX_BYTES_DE_LA_GUIA / 1024} KB: acortala.`) };
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `No leo ${RUTA_DE_LA_GUIA}: ${limpio(leido.error)}.`) };
+    }
+    try {
+        // ignoreBOM: el BOM se CONSERVA en el texto; quitarlo es regla de la huella (`huellaDeGuia`), no de la lectura.
+        // fatal: un byte inválido no se reemplaza en silencio, porque la huella de GitHub no coincidiría nunca.
+        return { ok: true, raiz, texto: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(leido.bytes) };
+    }
+    catch {
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `${RUTA_DE_LA_GUIA} no es UTF-8 válido.`) };
+    }
+}
+// ─── El desenlace propio de la guía, encima del de configurar ───
+function desenlaceDeGuia(r, ok) {
+    const c = r.cuerpo;
+    // 2xx, 401, 5xx y cuerpos raros los resuelve el de configurar. Ojo: la terminal no distingue 500
+    // connect_no_disponible de 502 github_no_disponible (ambos llegan como falla del servicio): los dos son 1.
+    if (r.status < 400 || r.status === 401 || r.status >= 500 || typeof c !== "object" || c === null)
+        return desenlace(r, ok);
+    const error = typeof c.error === "string" ? c.error : "rechazado";
+    const message = limpio(typeof c.message === "string" ? c.message : `El motor rechazó el pedido (${r.status}).`);
+    const con = (codigo, extra = {}, texto = message) => ({ codigo, json: { ok: false, error, message: taparSecretos(message), ...extra }, texto });
+    switch (error) {
+        case "guia_no_subida":
+        case "guia_distinta": {
+            const rama = cadena(c.rama), commit = cadena(c.commit);
+            const donde = rama !== "" ? ` (rama ${rama}${commit !== "" ? `, commit ${corto(commit)}` : ""})` : "";
+            const que = error === "guia_no_subida" ? "La guía no está en la rama principal del repo" : "La guía de la rama principal es otra, no la de tu archivo";
+            return con(SALIDA.esperandoAUnaPersona, { rama: c.rama ?? null, commit: c.commit ?? null }, `${que}${donde}: subí la guía a la rama principal y volvé a correr.`);
+        }
+        case "instalacion_ausente":
+        case "repo_fuera_de_alcance":
+        case "sin_guia_del_agente":
+            return con(SALIDA.haceFaltaUnaPersona);
+        case "guia_mal_armada": {
+            const errores = Array.isArray(c.errores) ? c.errores : [];
+            const lineas = errores.map((e) => {
+                const x = (e ?? {});
+                return `línea ${typeof x.linea === "number" ? x.linea : "?"}: ${cadena(x.motivo)}`;
+            });
+            return con(SALIDA.entradaInvalida, { errores: errores.map((e) => { const x = (e ?? {}); return { linea: x.linea ?? null, motivo: taparSecretos(typeof x.motivo === "string" ? x.motivo : "") }; }) }, [`${RUTA_DE_LA_GUIA} está mal armada:`, ...lineas].join("\n"));
+        }
+        default:
+            return desenlace(r, ok);
+    }
+}
+export async function guiaRevisar(d, flags) {
+    const g = await leerLaGuia(d, flags);
+    if (!g.ok)
+        return g.resultado;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    if (flags.dryRun) {
+        const haria = `POST ${rutaDe(p.proyecto, "/guia/revisar")} (${new TextEncoder().encode(g.texto).length} bytes)`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.revisar(d.api, p.clave, p.proyecto.id, g.texto, d.fetch), (c) => ({
+            codigo: SALIDA.ok, json: { ok: true, secciones: c.secciones ?? null }, texto: `La guía está bien armada: ${secciones(c.secciones)}.`,
+        }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+// Commit y rama que la terminal DECLARA: son del clon donde está el archivo, no verificados contra GitHub. Cualquier
+// falla (sin git, sin commits, HEAD suelto, plazo vencido) devuelve vacío: declarar es un extra que nunca bloquea la
+// subida ni pregunta nada, y lo que git imprima no sale a la terminal.
+async function declarado(d, raiz) {
+    const leer = async (args) => {
+        try {
+            const r = await d.gitDeclarado(args, raiz);
+            return r.codigo === 0 ? r.stdout.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const commit = await leer(["rev-parse", "HEAD"]);
+    // Sin un commit de 40 hex no se manda ni la rama: una rama sin commit no dice de dónde salió la guía.
+    if (commit === null || !/^[0-9a-f]{40}$/.test(commit))
+        return {};
+    const rama = await leer(["rev-parse", "--abbrev-ref", "HEAD"]);
+    // «HEAD» a secas es la cabeza suelta: no es una rama.
+    return rama !== null && rama !== "" && rama !== "HEAD" ? { commit, rama } : { commit };
+}
+export async function guiaPublicar(d, flags) {
+    const g = await leerLaGuia(d, flags);
+    if (!g.ok)
+        return g.resultado;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const github = flags.desdeGithub === true;
+    // La vía de GitHub manda la huella del archivo local TAL CUAL (con BOM y \r\n: normalizarla es regla de
+    // `huellaDeGuia`). La directa manda el contenido crudo y el motor calcula la huella: la terminal no la necesita.
+    const huella = github ? huellaDeGuia(g.texto) : null;
+    const decl = github ? {} : await declarado(d, g.raiz);
+    const cuerpo = huella !== null ? { huella } : { contenido: g.texto, ...decl };
+    const cuando = decl.commit ? `commit ${decl.commit.slice(0, 7)}${decl.rama ? ` de ${cadena(decl.rama)}` : ""} declarado` : "sin commit";
+    // El JSON del dry-run pasa por la misma limpieza que el texto (control primero, secretos después): la rama la
+    // decide quien escribió el clon, y un ESC en ella no debe llegar a la terminal por ninguna de las dos salidas.
+    if (flags.dryRun) {
+        const haria = huella !== null
+            ? `POST ${rutaDe(p.proyecto, "/guia/publicar")} con la huella ${huella.slice(0, 12)}…`
+            : `POST ${rutaDe(p.proyecto, "/guia/publicar")} con el contenido (${new TextEncoder().encode(g.texto).length} bytes), ${cuando}`;
+        const json = huella !== null ? { ok: true, dry_run: true, huella, haria } : { ok: true, dry_run: true, commit: decl.commit ? cadena(decl.commit) : null, rama: decl.rama ? cadena(decl.rama) : null, haria };
+        return { codigo: SALIDA.ok, json, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.publicar(d.api, p.clave, p.proyecto.id, cuerpo, d.fetch), (c) => {
+            const guia = (c.guia ?? {});
+            const ya = c.ya_publicada === true;
+            const rem = c.reemplaza;
+            const reemplaza = !ya && rem && rem.origen === "agente" && typeof rem.version === "number" ? ` (reemplaza a la de nuestro agente v${rem.version})` : "";
+            const json = { ok: true, guia: c.guia ?? null, ya_publicada: ya, reemplaza: c.reemplaza ?? null };
+            if (github) {
+                const base = `commit ${corto(guia.commit)} de ${cadena(guia.rama)}, ${secciones(guia.secciones)}`;
+                // Republicar re-activa la guía del repo aunque antes rigiera la de nuestro agente: «sigue siendo» mentiría en ese caso.
+                const texto = ya ? `Ya estaba publicada: ${base}. Quedó como guía activa.` : `Guía publicada: ${base}. Es la guía activa${reemplaza}.`;
+                return { codigo: SALIDA.ok, json, texto };
+            }
+            // El commit se muestra como lo que es: lo que la terminal dijo, no lo que GitHub confirmó.
+            const origen = decl.commit ? `commit ${decl.commit.slice(0, 7)} declarado por la terminal (no verificado en GitHub)` : "sin commit";
+            const texto = ya
+                ? `Ya estaba subida: ${secciones(guia.secciones)}. Quedó como guía activa; ${origen}.`
+                : `Guía subida: ${secciones(guia.secciones)}. Es la guía activa${reemplaza}; ${origen}.`;
+            return { codigo: SALIDA.ok, json: { ...json, commit_declarado: decl.commit ?? null }, texto };
+        });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+export async function guiaVer(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        return desenlaceDeGuia(await d.ver(d.api, p.clave, p.proyecto.id, d.fetch), (c) => {
+            const guia = c.guia;
+            const otra = c.otra;
+            const rama = c.rama;
+            const alDia = rama && typeof rama.al_dia === "boolean" ? rama.al_dia : null;
+            const json = { ok: true, guia: guia ?? null, otra: otra ?? null, al_dia: alDia, rama: rama ?? null };
+            if (!guia)
+                return { codigo: SALIDA.ok, json, texto: "Este proyecto no tiene guía activa: `supcoflow guia publicar` sube la del repo." };
+            const lineas = [];
+            if (guia.origen === "repo") {
+                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.repo} (versión ${guia.version}, ${secciones(guia.secciones)}).`);
+                if (guia.procedencia === "terminal") {
+                    // Subida desde la terminal: el motor NO comparó nada contra GitHub a propósito (al_dia null), así que "no pude
+                    // comprobar la rama" sería falso. Commit y rama son lo que declaró quien subió; el id crudo de quien publicó
+                    // (usr_…) no le dice nada a una persona y la terminal no resuelve nombres: queda sólo en el JSON.
+                    const commit = cadena(guia.commit), rama = cadena(guia.rama);
+                    const partes = [cadena(guia.repo), rama !== "" ? `rama ${rama}` : "", commit !== "" ? `commit ${corto(commit)} (declarado)` : "sin commit declarado"].filter((x) => x !== "");
+                    lineas.push(`Procedencia: ${partes.join(", ")}.`);
+                    lineas.push("Subida desde la terminal; el commit es declarado, no verificado en GitHub.");
+                }
+                else {
+                    lineas.push(`Procedencia: ${cadena(guia.repo)}, rama ${cadena(guia.rama)}, commit ${corto(guia.commit)}, publicada por ${cadena(guia.publicada_por)}.`);
+                    if (alDia === true)
+                        lineas.push("Está al día con la rama.");
+                    else if (alDia === false)
+                        lineas.push("En la rama hay otra versión: corré `supcoflow guia publicar`.");
+                    else
+                        lineas.push("No pude comprobar la rama ahora.");
+                }
+            }
+            else {
+                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.agente} (v${guia.version}, ${secciones(guia.secciones)}).`);
+                lineas.push("Procedencia: la escribió nuestro agente y la aprobó una persona.");
+            }
+            if (otra && (otra.origen === "repo" || otra.origen === "agente")) {
+                lineas.push(`También hay ${NOMBRE_DEL_ORIGEN[otra.origen]} (v${typeof otra.version === "number" ? otra.version : "?"}): \`supcoflow guia usar --origen ${otra.origen}\` la activa.`);
+            }
+            return { codigo: SALIDA.ok, json, texto: lineas.join("\n") };
+        });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+export async function guiaUsar(d, flags) {
+    const origen = flags.origen ?? null;
+    if (origen === null)
+        return fallo(SALIDA.entradaInvalida, "falta_origen", "Decí cuál: `supcoflow guia usar --origen repo` o `--origen agente`.");
+    if (origen !== "repo" && origen !== "agente")
+        return fallo(SALIDA.entradaInvalida, "origen_invalido", "--origen es `repo` o `agente`.");
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    if (flags.dryRun) {
+        const haria = `POST ${rutaDe(p.proyecto, "/guia/origen")} {origen: ${origen}}`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.elegir(d.api, p.clave, p.proyecto.id, origen, d.fetch), (c) => ({
+            codigo: SALIDA.ok, json: { ok: true, guia: c.guia ?? null }, texto: `Ahora la guía activa es ${NOMBRE_DEL_ORIGEN[origen]}.`,
+        }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

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

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