supcoflow 0.3.0 → 0.5.0

package/README.md

@@ -26,6 +26,10 @@ npx supcoflow login
 | `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. Los comandos de
@@ -68,7 +72,7 @@ los que escriben aceptan `--dry-run`.
 |---|---|
 | `supcoflow catalogo` | Qué se puede configurar y con qué valores. |
 | `supcoflow configuracion` | Chat, sitios, marca y acuerdo de datos del proyecto. |
-| `supcoflow chat prender` / `chat apagar` | Prende o apaga el chat (sin skill aprobada, prender sale 4). |
+| `supcoflow chat 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. |
@@ -77,6 +81,42 @@ los que escriben aceptan `--dry-run`.
 | `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:
@@ -86,7 +126,7 @@ Pensado para que lo lea un programa, no sólo una persona:
 - **Sin preguntas sin terminal interactiva** (o con `--json`): si falta un dato, sale 3 diciendo qué
   flag usar. `supcoflow login` sin terminal sale 3 y te indica el camino en dos pasos.
 - **`--dry-run`** donde se puede simular (`login`, `login --start`, `logout`, `repo conectar --start`,
-  `proyecto crear`). `login --wait
+  `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 |

package/dist/api.js

@@ -21,9 +21,9 @@ export function urlDeLaApi(env) {
         return new URL(u.origin);
     throw invalida();
 }
-// A mano a propósito: tiene que coincidir con package.json (0.3.0); sólo identifica a la terminal
+// 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.3.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
@@ -293,3 +293,22 @@ export async function esClaveDeConsultaDelProyecto(api, clave, proyectoId, f) {
         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

@@ -4,11 +4,12 @@ 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",
+    "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ó.
@@ -37,6 +38,8 @@ export function leerArgumentos(argv) {
                 nombre: { type: "string" },
                 "guardar-en": { type: "string" },
                 id: { type: "string" },
+                origen: { type: "string" },
+                "desde-github": { type: "boolean" },
                 tema: { type: "string", multiple: true },
             },
             tokens: true,
@@ -92,6 +95,8 @@ export function leerArgumentos(argv) {
             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/cli.js

@@ -6,6 +6,7 @@ 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";
@@ -36,7 +37,7 @@ async function correr(argv) {
             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,
+            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)
@@ -114,6 +115,14 @@ async function correr(argv) {
                 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/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.3.0";
+const VERSION = "0.5.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -89,7 +89,7 @@ export const DESCRIPCION = {
         },
         {
             nombre: "chat prender",
-            resumen: "Prende el chat de soporte del proyecto. Sin skill aprobada hace falta una persona (sale 4).",
+            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],
@@ -182,17 +182,45 @@ export const DESCRIPCION = {
             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/entorno.js

@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeSync, } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { buscarProyecto, canjear, configurar, crearConexion, crearProyecto, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, } from "./api.js";
+import { buscarProyecto, canjear, configurar, crearConexion, crearProyecto, elegirOrigen, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerGuia, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, publicarGuia, revisarGuia, } from "./api.js";
 import { crearCandados } from "./candado.js";
 import { almacenDeArchivo } from "./guardado/archivo.js";
 import { crearGuardado } from "./guardado/index.js";
@@ -228,15 +228,20 @@ export const correrReal = (bin, args, stdin, techoMs) => new Promise((resolve) =
     hijo.stdin.end(stdin ?? undefined);
 });
 // `git` con entorno mínimo (sólo PATH): ni GIT_DIR ni GIT_CONFIG del shell desvían la lectura, y
-// SUPCOFLOW_TOKEN no le llega. Un git ausente (ENOENT) es «sin git», no un fallo.
-export const gitReal = (args, cwd) => new Promise((resolve) => {
-    execFile("git", args, { cwd, timeout: 5_000, env: { PATH: process.env.PATH ?? "" } }, (e, stdout) => {
+// SUPCOFLOW_TOKEN no le llega. Un git ausente (ENOENT) es «sin git», no un fallo. El plazo es parámetro para no
+// duplicar la función: lo que git imprima nunca sale a la terminal, sólo el código y el stdout.
+const gitConPlazo = (plazoMs) => (args, cwd) => new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: plazoMs, env: { PATH: process.env.PATH ?? "" } }, (e, stdout) => {
         if (!e)
             return resolve({ codigo: 0, stdout: String(stdout) });
         const codigo = e.code;
         resolve({ codigo: typeof codigo === "number" ? codigo : null, stdout: "" });
     });
 });
+export const gitReal = gitConPlazo(5_000);
+// El commit y la rama que la terminal DECLARA al subir la guía: 3 segundos (no 5) porque esto es un extra que nunca
+// debe hacer esperar a nadie.
+export const gitRapido = gitConPlazo(3_000);
 // `.supcoflow/proyecto.json` vive DENTRO del repo, y el repo puede ser un clon ajeno: su contenido lo
 // decide quien lo escribió. Por eso ni la carpeta ni el archivo se siguen si son enlaces (uno hacia
 // `~/.ssh/…` haría que la terminal leyera, o escribiera, lo que el repo quiera), y se lee con tope.
@@ -450,6 +455,11 @@ export function entornoReal(env = process.env) {
             leerArchivoChico,
             leerCatalogo: (a, clave) => leerCatalogo(a, clave, fetch),
         },
+        guia: {
+            ...configurarEnElMotor,
+            leerArchivoChico, fetch, gitDeclarado: gitRapido,
+            revisar: revisarGuia, publicar: publicarGuia, ver: leerGuia, elegir: elegirOrigen,
+        },
         claves: {
             ...configurarEnElMotor,
             listarClaves: (a, clave, id) => listarClaves(a, clave, id, fetch),

package/dist/flags-por-comando.js

@@ -4,6 +4,7 @@
 const DE_CONFIGURAR_CON_REPO = [
     "configuracion", "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",
 ];
 export const FLAGS_POR_COMANDO = [
     { flags: ["start", "wait"], comandos: ["login", "repo conectar"], texto: "--start y --wait son de `supcoflow login` y `supcoflow repo conectar`." },
@@ -18,6 +19,8 @@ export const FLAGS_POR_COMANDO = [
     { flags: ["permitir"], comandos: ["datos fijar"], texto: "--permitir es de `supcoflow datos fijar`." },
     { flags: ["modo"], comandos: ["politica fijar"], texto: "--modo es de `supcoflow politica fijar`." },
     { flags: ["nombre", "guardarEn"], comandos: ["claves crear"], texto: "--nombre y --guardar-en son de `supcoflow claves crear`." },
+    { flags: ["origen"], comandos: ["guia usar"], texto: "--origen es de `supcoflow guia usar`." },
+    { flags: ["desdeGithub"], comandos: ["guia publicar"], texto: "--desde-github es de `supcoflow guia publicar`." },
     { flags: ["id"], comandos: ["claves revocar"], texto: "--id es de `supcoflow claves revocar`." },
 ];
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */

package/dist/guia.js

@@ -0,0 +1,11 @@
+// La guía del producto que vive en el repo del cliente. Sin dependencias: sólo `node:crypto`.
+import { createHash } from "node:crypto";
+export const RUTA_DE_LA_GUIA = ".supcoflow/guia.md";
+export const MAX_BYTES_DE_LA_GUIA = 64 * 1024;
+// La misma regla que el motor (`src/guia/formato.ts`), copiada a propósito y clavada con los vectores
+// de `test/vectores/huella.json` (idénticos en los dos repos). Se normaliza antes de hashear porque un
+// editor de Windows pone BOM o \r\n, y si las dos puntas hashearan distinto, `guia_distinta` sería eterno.
+export function huellaDeGuia(texto) {
+    const normalizado = texto.replace(/^/, "").replace(/\r\n?/g, "\n");
+    return createHash("sha256").update(normalizado, "utf8").digest("hex");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supcoflow",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "La terminal de Supcoflow: iniciar sesión y manejar el chat de soporte desde la consola o un asistente.",
   "type": "module",
   "bin": { "supcoflow": "dist/cli.js" },