supcoflow 0.1.0 → 0.3.0

package/dist/comandos/claves.js

@@ -0,0 +1,161 @@
+// `supcoflow claves crear`: una clave de consulta (sólo lee su proyecto) para CI. Dos fases (§6.5): el
+// motor la crea pendiente y devuelve el secreto UNA vez; la terminal lo guarda en el archivo que dijo la
+// persona y recién ahí confirma mandándolo de vuelta (demuestra que lo tiene). El secreto nunca sale por
+// stdout ni stderr: quien llama suele ser un asistente, y su salida queda en su contexto.
+//
+// La semántica entera (candado, mirar el destino antes, el ciclo) está en la tarea C4 del plan del bloque 4
+// y en los comentarios de abajo; cada rama de este archivo es una de esas reglas.
+import path from "node:path";
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { desenlace, dryRun, fallo, rutaDe } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+const OPERACION = "clave_crear";
+const SUFIJO = /^scf_([0-9a-f]{16})_[0-9a-f]{64}$/;
+const ID_DE_CLAVE = /^cla_[0-9a-f]{16}$/;
+export async function clavesCrear(d, flags) {
+    if (flags.guardarEn === null)
+        return fallo(SALIDA.entradaInvalida, "falta_guardar_en", "Decí dónde guardar la clave: `supcoflow claves crear --nombre ci --guardar-en ~/ci.key` (fuera de un repo).");
+    if (flags.nombre === null)
+        return fallo(SALIDA.entradaInvalida, "falta_nombre", "Poné un nombre que diga para qué es: `--nombre ci`.");
+    // Absoluta desde ya: la salida dice dónde quedó sin depender de dónde estaba parado el comando.
+    const destino = path.resolve(d.cwd, flags.guardarEn);
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/claves");
+    // Antes de pedir nada: un destino que no sirve (dentro de un repo) dejaba una fila pendiente de más.
+    const invalido = d.secretos.validarDestino(destino);
+    if (invalido !== null)
+        return fallo(invalido.codigo, "destino_invalido", `${destino}: ${invalido.error}.`);
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} y después …/confirmar`);
+    const alcance = `${p.proyecto.id}#${flags.nombre}`;
+    // El registro de idempotencia pone el alcance en minúsculas (`CI` y `ci` comparten fila): el candado
+    // tiene que coincidir, o dos procesos con la misma clave de reintento corrían a la vez.
+    // 1. El candado: el ciclo entero, de a uno por operación en esta máquina. Comprobar que el archivo
+    // autentica y después escribirlo no es atómico: sin candado, un segundo `claves crear` atrasado pisaba
+    // el secreto vigente con uno que después no confirmaba (segunda revisión externa, hallazgo 1). Dos
+    // máquinas no comparten la clave de idempotencia, así que crean filas distintas y no se pisan.
+    const candado = d.candados.tomar(`${OPERACION}#${alcance.toLowerCase()}`);
+    if (candado.tipo === "ocupado")
+        return fallo(SALIDA.inesperado, "en_curso", "Otro `supcoflow claves crear` igual está corriendo en esta máquina; esperá a que termine.");
+    if (candado.tipo === "abandonado") {
+        return fallo(SALIDA.inesperado, "candado_abandonado", `Quedó el candado de un \`claves crear\` que no terminó: ${candado.ruta}. Si no hay otro corriendo, borralo y volvé a probar.`);
+    }
+    if (candado.tipo === "no_disponible") {
+        return fallo(SALIDA.inesperado, "candado_no_disponible", `No pude crear el candado en ${candado.ruta} (¿permisos?). Revisá esa carpeta y volvé a probar.`);
+    }
+    try {
+        const autentica = async (secreto) => d.esClaveDeConsultaDelProyecto(d.api, secreto, p.proyecto.id);
+        const yaCreada = async (claveId) => {
+            await d.idempotencia.olvidar(OPERACION, alcance);
+            return { codigo: SALIDA.ok, json: { ok: true, clave_id: claveId, archivo: destino, ya_confirmada: true }, texto: `La clave ${claveId} ya estaba creada; está en ${destino}.` };
+        };
+        // 2. Mirar el destino antes de pedir nada. Una clave de consulta de ESTE proyecto que autentica es un
+        // éxito anterior: repetir el comando no crea otra fila (el archivo es la referencia durable; la clave
+        // de idempotencia ya se olvidó). Una que no autentica sólo se retoma si hay un intento a medias
+        // nuestro. Cualquier otra cosa (una clave personal aunque autentique, una de otro proyecto, una
+        // revocada) no se pisa: podría ser una clave vigente de alguien (tercera revisión, hallazgo 2).
+        const hay = d.secretos.leer(destino);
+        if (hay.estado === "clave" && (await autentica(hay.secreto)))
+            return await yaCreada(hay.claveId);
+        if (hay.estado !== "ausente" && !(hay.estado === "clave" && (await d.idempotencia.tiene(OPERACION, alcance)))) {
+            return fallo(SALIDA.haceFaltaUnaPersona, "destino_ocupado", `${destino} ya tiene algo que no es una clave vigente de este proyecto; no lo toco. Borrá el archivo o elegí otro destino con --guardar-en.`);
+        }
+        // 3. El ciclo. Estricta: sin la clave de reintento guardada no se manda nada (Review Focus 15).
+        const key = await d.idempotencia.claveDe(OPERACION, alcance, { estricta: true });
+        for (let vuelta = 0; vuelta < 2; vuelta++) {
+            const r = await d.configurar(d.api, p.clave, ruta, { nombre: flags.nombre }, { idempotencyKey: key });
+            if (r.status === 200 && r.cuerpo.estado === "activa") {
+                // El motor no rota una activa (no devuelve secreto): vale sólo si lo que tenemos es su secreto vigente.
+                const claveId = String(r.cuerpo.clave_id);
+                const ahora = d.secretos.leer(destino);
+                if (ahora.estado === "clave" && ahora.claveId === claveId && (await autentica(ahora.secreto)))
+                    return await yaCreada(claveId);
+                await d.idempotencia.olvidar(OPERACION, alcance);
+                return fallo(SALIDA.haceFaltaUnaPersona, "archivo_desactualizado", `La clave ${claveId} quedó activa, pero ${destino} no tiene su secreto vigente. Revocala con \`supcoflow claves revocar --id ${claveId}\` y creá otra.`);
+            }
+            if (r.status !== 201) {
+                if (r.cuerpo.error === "clave_vencida") {
+                    // La fila vencida no vuelve: el próximo intento tiene que ser otra clave de idempotencia.
+                    await d.idempotencia.olvidar(OPERACION, alcance);
+                    // El archivo conserva el secreto pendiente vencido y un reintento daría 4 destino_ocupado. Borrarlo
+                    // desde acá sería tocar un archivo que quizá no escribió este run; se lo pedimos a la persona.
+                    return fallo(SALIDA.inesperado, "clave_vencida", `La clave pendiente venció sin confirmarse. Borrá ${destino} (guarda el secreto vencido, ya no sirve) y volvé a correr el comando para crear otra.`);
+                }
+                // Misma clave de reintento con otro cuerpo: no se arregla reintentando, y guardada trabaría para siempre.
+                if (r.cuerpo.error === "idempotency_key_reusada")
+                    await d.idempotencia.olvidar(OPERACION, alcance);
+                return desenlace(r, () => { throw new Error("inalcanzable"); });
+            }
+            const claveId = String(r.cuerpo.clave_id);
+            const secreto = typeof r.cuerpo.clave === "string" && SUFIJO.test(r.cuerpo.clave) ? r.cuerpo.clave : null;
+            if (secreto === null)
+                return fallo(SALIDA.inesperado, "respuesta_inesperada", "El motor no devolvió una clave con la forma esperada.");
+            // El id y el secreto tienen que ser de la misma fila: si no, lo que se guarda no es lo que se confirma.
+            if (claveId !== `cla_${SUFIJO.exec(secreto)[1]}`)
+                return fallo(SALIDA.inesperado, "respuesta_inesperada", "El motor devolvió una clave que no corresponde a su id; no la guardé.");
+            const g = d.secretos.guardar(destino, claveId, secreto);
+            // Sin guardarla NO se confirma: una pendiente sin confirmar no autentica y vence sola a los 10 minutos.
+            if (g !== "guardado")
+                return fallo(g.codigo, "no_se_guardo", `No guardé la clave en ${destino}: ${g.error}. No quedó activa.`);
+            const c = await d.configurar(d.api, p.clave, `${ruta}/${encodeURIComponent(claveId)}/confirmar`, { clave: secreto });
+            if (c.status === 200) {
+                await d.idempotencia.olvidar(OPERACION, alcance);
+                return { codigo: SALIDA.ok, json: { ok: true, clave_id: claveId, archivo: destino }, texto: `Creé la clave de consulta ${claveId} y la guardé en ${destino}.` };
+            }
+            // Obsoleta: otro intento con la misma clave de idempotencia le acuñó otro secreto a la misma fila.
+            // Una vuelta más trae el vigente y lo guarda encima (mismo id).
+            if (c.cuerpo.error !== "confirmacion_obsoleta")
+                return desenlace(c, () => { throw new Error("inalcanzable"); });
+        }
+        return fallo(SALIDA.inesperado, "confirmacion_obsoleta", "Otro intento cambió la clave mientras la confirmaba; volvé a correr el comando.");
+    }
+    catch (e) {
+        // Red caída a mitad, o el registro estricto que no pudo guardar: la clave de idempotencia (si llegó a
+        // guardarse) se conserva y el reintento retoma la misma fila.
+        return resultadoDeFallo(e);
+    }
+    finally {
+        candado.soltar();
+    }
+}
+export async function clavesListar(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        // El motor ya manda sólo id, nombre y fecha (nunca el hash); acá se arma la forma pública igual.
+        const claves = (await d.listarClaves(d.api, p.clave, p.proyecto.id)).map((c) => ({ id: c.id, nombre: c.nombre, creada_en: c.creadaEn }));
+        const texto = claves.length === 0
+            ? "No hay claves de consulta activas."
+            : `Claves de consulta activas: ${claves.map((c) => `${c.id} (${c.nombre})`).join(", ")}.`;
+        return { codigo: SALIDA.ok, json: { ok: true, claves }, texto };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+export async function clavesRevocar(d, flags) {
+    if (flags.id === null || !ID_DE_CLAVE.test(flags.id)) {
+        return fallo(SALIDA.entradaInvalida, "id_invalido", "Decí qué clave revocar con su id: `supcoflow claves revocar --id cla_…` (lo da `supcoflow claves listar`).");
+    }
+    const claveId = flags.id;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/claves/revocar");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} {clave_id: ${claveId}}`);
+    try {
+        const r = await d.configurar(d.api, p.clave, ruta, { clave_id: claveId });
+        // Revocar dos veces deja lo mismo que una: para quien lo pide, ya está hecho.
+        if (r.status === 409 && r.cuerpo.error === "ya_revocada") {
+            return { codigo: SALIDA.ok, json: { ok: true, clave_id: claveId, ya_revocada: true }, texto: `La clave ${claveId} ya estaba revocada.` };
+        }
+        return desenlace(r, () => ({ codigo: SALIDA.ok, json: { ok: true, clave_id: claveId }, texto: `Revoqué la clave ${claveId}; deja de autenticar.` }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/comandos/configurar.js

@@ -0,0 +1,187 @@
+// src/comandos/configurar.ts
+// Los comandos que configuran el proyecto del repo (spec de supcoflow go §5.4, §9). Cada uno resuelve el
+// proyecto, manda UN pedido y traduce la respuesta a los códigos de §13. Lo que se valida acá (un --tema
+// sin `=`, un --sitio que falta) se valida para no gastar un pedido; la regla de verdad es la del motor.
+import path from "node:path";
+import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+export const fallo = (codigo, error, message) => ({ codigo, json: { ok: false, error, message }, texto: message });
+const PIDEN_UNA_PERSONA = new Set(["skill_no_aprobada"]);
+const TRANSITORIOS = new Set(["sitios_cambiaron", "idempotency_en_curso"]);
+export function desenlace(r, ok) {
+    if (r.status >= 200 && r.status < 300)
+        return ok(r.cuerpo);
+    // Propio de esta función (hoy `conClave` ya lo filtra antes): sin esto, un 401 o un 5xx caerían en el 3 de
+    // «entrada inválida» y la persona (o el asistente) corregiría una entrada que estaba bien.
+    if (r.status === 401)
+        return fallo(SALIDA.faltaLogin, "clave_invalida", "La clave ya no vale: iniciá sesión de nuevo.");
+    if (r.status >= 500 || typeof r.cuerpo !== "object" || r.cuerpo === null) {
+        return fallo(SALIDA.inesperado, "respuesta_inesperada", `El motor contestó algo que no entiendo (${r.status}); probá de nuevo en un rato.`);
+    }
+    const error = typeof r.cuerpo.error === "string" ? r.cuerpo.error : "rechazado";
+    const message = taparSecretos(typeof r.cuerpo.message === "string" ? r.cuerpo.message : `El motor rechazó el pedido (${r.status}).`);
+    if (PIDEN_UNA_PERSONA.has(error))
+        return fallo(SALIDA.haceFaltaUnaPersona, error, message);
+    if (TRANSITORIOS.has(error))
+        return fallo(SALIDA.inesperado, error, message);
+    return fallo(SALIDA.entradaInvalida, error, message);
+}
+export const rutaDe = (p, resto) => `/api/proyectos/${encodeURIComponent(p.id)}${resto}`;
+export const dryRun = (haria) => ({ codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` });
+export async function comandoConfiguracion(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        const c = await d.leerConfiguracion(d.api, p.clave, p.proyecto.id);
+        const chat = c.chat;
+        const sitiosLista = c.sitios;
+        // El acuerdo de datos frena lo que se guarda y lo que lee la IA que releva el repo; NO alcanza a lo
+        // que ve la IA del propio chat mientras conversa (decisión 1b). Por eso el texto lo dice, y nunca
+        // promete «ninguna IA» ni «toda IA». `acuerdo` puede ser null, un acuerdo o {ilegible: true}.
+        const ac = c.acuerdo;
+        const acuerdo = ac === null || ac === undefined
+            ? "sin fijar (entra todo, como hoy)"
+            : ac.ilegible === true
+                ? "fijado pero ilegible (revisalo en la consola)"
+                : "fijado";
+        const alcance = ac === null || ac === undefined ? "" : " Frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa.";
+        return {
+            codigo: SALIDA.ok,
+            json: { ok: true, proyecto: p.proyecto.id, ...c },
+            texto: [
+                `${p.proyecto.id}: chat ${chat.habilitado ? "prendido" : "apagado"}, ${sitiosLista.length} sitio(s), acuerdo de datos ${acuerdo}.${alcance}`,
+                `Política de problemas: ${textoDePolitica(c.politica)}`,
+                `Marca: ${textoDeMarca(c.marca)}`,
+            ].join("\n"),
+        };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+// La política dicha en palabras llanas (decisión del dueño, 2026-10-16): «guardar» frena sólo lo automático
+// del chat; una persona todavía puede pedir el relevamiento desde la consola, y eso gasta. Un motor viejo que
+// no la manda no se adivina: se dice que no vino.
+function textoDePolitica(v) {
+    const modo = v?.modo;
+    if (modo === "relevar")
+        return "relevar: cada problema se releva y nace el issue (gasta).";
+    if (modo === "guardar")
+        return "guardar: los problemas del chat se guardan sin relevar; desde la consola una persona puede pedir el relevamiento (gasta).";
+    return "el motor no la informó.";
+}
+// Título, saludo y tema los escribe quien configura el chat y llegan tal cual: un ESC en el título movería el
+// cursor o cambiaría colores en la terminal de quien corre `configuracion`. En texto se quitan los caracteres
+// de control (C0, DEL y C1); el JSON los conserva, porque ahí van escapados.
+const limpio = (t) => t.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+// `marca` es null (nunca se fijó: el chat usa la de fábrica) o {titulo, saludo, tema, logo_url}. Del tema se
+// muestran las claves tal cual vinieron: el motor decide cuáles hay, la terminal no las reinterpreta.
+function textoDeMarca(v) {
+    if (v === undefined)
+        return "el motor no la informó.";
+    if (v === null)
+        return "sin fijar (el chat usa la de fábrica).";
+    const m = v;
+    const partes = [];
+    if (typeof m.titulo === "string" && m.titulo !== "")
+        partes.push(`título «${limpio(m.titulo)}»`);
+    if (typeof m.saludo === "string" && m.saludo !== "")
+        partes.push(`saludo «${limpio(m.saludo)}»`);
+    if (typeof m.tema === "object" && m.tema !== null) {
+        const colores = Object.entries(m.tema).filter(([, x]) => typeof x === "string").map(([k, x]) => `${limpio(k)} ${limpio(x)}`);
+        if (colores.length > 0)
+            partes.push(`tema ${colores.join(", ")}`);
+    }
+    partes.push(typeof m.logo_url === "string" && m.logo_url !== "" ? "con logo" : "sin logo");
+    return partes.join(", ") + ".";
+}
+export async function chatPrenderApagar(d, flags, habilitar) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/chat");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} {habilitado: ${habilitar}}`);
+    return desenlace(await d.configurar(d.api, p.clave, ruta, { habilitado: habilitar }), () => ({
+        codigo: SALIDA.ok, json: { ok: true, habilitado: habilitar }, texto: habilitar ? "Chat prendido." : "Chat apagado.",
+    }));
+}
+export async function sitios(d, flags, accion) {
+    if (flags.sitio === null)
+        return fallo(SALIDA.entradaInvalida, "falta_sitio", `Falta el sitio: \`supcoflow sitios ${accion} --sitio https://tu-app.com\`.`);
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/origenes");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} {accion: ${accion}}`);
+    return desenlace(await d.configurar(d.api, p.clave, ruta, { accion, origen: flags.sitio }), (c) => ({
+        codigo: SALIDA.ok, json: { ok: true, sitios: c.origenes }, texto: `Sitios: ${c.origenes.join(", ") || "ninguno"}.`,
+    }));
+}
+export async function chatMarca(d, flags) {
+    const tema = {};
+    for (const t of flags.tema) {
+        const i = t.indexOf("=");
+        if (i <= 0 || i === t.length - 1)
+            return fallo(SALIDA.entradaInvalida, "tema_invalido", `--tema va como clave=valor (por ejemplo acento=#0a7); recibí «${t}».`);
+        const clave = t.slice(0, i);
+        if (clave in tema)
+            return fallo(SALIDA.entradaInvalida, "tema_invalido", `--tema ${clave} va una sola vez.`);
+        tema[clave] = t.slice(i + 1);
+    }
+    if (flags.titulo === null && flags.saludo === null && Object.keys(tema).length === 0) {
+        return fallo(SALIDA.entradaInvalida, "marca_vacia", "Pasá al menos --titulo, --saludo o --tema.");
+    }
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    // ─── Se manda la marca ENTERA, mezclada con la guardada (revisión externa del 2026-10-16, hallazgo 5) ───
+    // La route REEMPLAZA la marca (`escribirMarcaDelChat`: lo omitido queda NULL y el tema `{}`), porque así
+    // la usa el formulario de la consola, que manda todo junto y vacía un campo dejándolo en blanco. Mandar
+    // sólo `--titulo` borraba el saludo y los colores. La terminal lee lo guardado y cambia sólo lo nombrado.
+    // Costo aceptado: dos ediciones a la vez (terminal y consola) pueden pisarse; es una persona configurando.
+    // Borrar un campo desde la terminal no existe en este bloque: se hace en la consola.
+    let actual;
+    try {
+        actual = (await d.leerConfiguracion(d.api, p.clave, p.proyecto.id)).marca;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const cuerpo = {};
+    const titulo = flags.titulo ?? (typeof actual?.titulo === "string" ? actual.titulo : null);
+    const saludo = flags.saludo ?? (typeof actual?.saludo === "string" ? actual.saludo : null);
+    if (titulo !== null)
+        cuerpo.titulo = titulo;
+    if (saludo !== null)
+        cuerpo.saludo = saludo;
+    const temaActual = typeof actual?.tema === "object" && actual.tema !== null ? actual.tema : {};
+    const temaFinal = { ...temaActual, ...tema };
+    if (Object.keys(temaFinal).length > 0)
+        cuerpo.tema = temaFinal;
+    const ruta = rutaDe(p.proyecto, "/chat/marca");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta}`);
+    return desenlace(await d.configurar(d.api, p.clave, ruta, cuerpo), (c) => ({ codigo: SALIDA.ok, json: { ok: true, marca: c.marca }, texto: "Marca guardada." }));
+}
+const MIMES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+// El tope del motor es 200 KB (`MAX_LOGO_BYTES`); acá se corta antes para no mandar de más. El motor decide.
+const TOPE_DEL_LOGO = 200_000;
+export async function chatLogo(d, flags) {
+    if (flags.archivo === null)
+        return fallo(SALIDA.entradaInvalida, "falta_archivo", "Falta el logo: `supcoflow chat logo --archivo logo.png`.");
+    const mime = MIMES[path.extname(flags.archivo).toLowerCase()];
+    if (mime === undefined)
+        return fallo(SALIDA.entradaInvalida, "logo_invalido", "El logo tiene que ser .png, .jpg o .webp.");
+    const leido = d.leerArchivoChico(flags.archivo, TOPE_DEL_LOGO);
+    if ("error" in leido)
+        return fallo(SALIDA.entradaInvalida, "logo_ilegible", `No leo ${flags.archivo}: ${leido.error}.`);
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    if (flags.dryRun)
+        return dryRun(`POST ${rutaDe(p.proyecto, "/chat/logo")} (${leido.bytes.length} bytes)`);
+    return desenlace(await d.subirLogo(d.api, p.clave, p.proyecto.id, { bytes: leido.bytes, mime, nombre: path.basename(flags.archivo) }), (c) => ({ codigo: SALIDA.ok, json: { ok: true, logo_url: c.logo_url }, texto: "Logo subido." }));
+}

package/dist/comandos/datos-y-politica.js

@@ -0,0 +1,112 @@
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { claveVigente } from "./clave-vigente.js";
+import { desenlace } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+const BANDERAS = ["usuario_id", "usuario_rol", "pagina_y_navegador", "capturas", "elementos", "email"];
+// Los límites del contrato (`Permitido.atributos`: ≤ 8, 1–40 caracteres). Se cortan acá para que un
+// --permitir imposible salga 3 sin pedido; el motor sigue siendo quien decide.
+const MAX_ATRIBUTOS = 8;
+const MAX_LARGO_DE_ATRIBUTO = 40;
+const fallo = (codigo, error, message) => ({ codigo, json: { ok: false, error, message }, texto: message });
+const rutaDe = (p, resto) => `/api/proyectos/${encodeURIComponent(p.id)}${resto}`;
+const dryRun = (haria) => ({ codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` });
+export function leerPermitir(crudo) {
+    const partes = crudo.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const p = { usuario_id: false, usuario_rol: false, atributos: [], pagina_y_navegador: false, capturas: false, elementos: false, email: false };
+    if (partes.length === 1 && partes[0] === "nada")
+        return p;
+    if (partes.length === 0 || partes.includes("nada"))
+        return { error: "`nada` va solo; si no, nombrá lo que sí pasa." };
+    const vistos = new Set();
+    for (const x of partes) {
+        if (vistos.has(x))
+            return { error: `«${x}» está repetido.` };
+        vistos.add(x);
+        if (x.startsWith("atributo:")) {
+            // Recortado: « plan» y «plan» son el mismo atributo para quien lo escribe, y el motor lo compara exacto.
+            const nombre = x.slice("atributo:".length).trim();
+            if (nombre.length === 0)
+                return { error: "`atributo:` va con el nombre exacto del atributo, por ejemplo atributo:plan." };
+            if (nombre.length > MAX_LARGO_DE_ATRIBUTO)
+                return { error: `El nombre de un atributo tiene hasta ${MAX_LARGO_DE_ATRIBUTO} caracteres.` };
+            if (p.atributos.length >= MAX_ATRIBUTOS)
+                return { error: `Hasta ${MAX_ATRIBUTOS} atributos.` };
+            p.atributos.push(nombre);
+        }
+        else if (BANDERAS.includes(x)) {
+            p[x] = true;
+        }
+        else {
+            return { error: `No conozco «${x}». Valen: ${BANDERAS.join(", ")}, atributo:<nombre>, o nada.` };
+        }
+    }
+    return p;
+}
+export async function datosFijar(d, flags) {
+    if (flags.permitir === null) {
+        return fallo(SALIDA.entradaInvalida, "falta_permitir", "Falta qué datos pasan: `supcoflow datos fijar --permitir usuario_id,capturas` (o `--permitir nada`).");
+    }
+    const permitido = leerPermitir(flags.permitir);
+    if ("error" in permitido)
+        return fallo(SALIDA.entradaInvalida, "permitir_invalido", permitido.error);
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/acuerdo-de-datos");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} {permitido}`);
+    let r;
+    try {
+        r = await d.configurar(d.api, p.clave, ruta, { permitido });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    // El acuerdo frena lo que se guarda y lo que lee la IA que releva; NO alcanza a lo que ve la IA del
+    // propio chat mientras conversa (decisión 1b): el texto lo dice y no promete «toda» ni «ninguna» IA.
+    return desenlace(r, (c) => {
+        const version = c.acuerdo?.version;
+        return {
+            codigo: SALIDA.ok,
+            json: { ok: true, acuerdo: c.acuerdo, alcance: "guardado_y_relevamiento" },
+            texto: `Acuerdo de datos fijado (versión ${version}). Frena lo que se guarda y lo que lee la IA que releva; no lo que ve la IA del chat mientras conversa.`,
+        };
+    });
+}
+export async function politicaFijar(d, flags) {
+    if (flags.modo !== "relevar" && flags.modo !== "guardar") {
+        return fallo(SALIDA.entradaInvalida, "modo_invalido", "--modo vale `relevar` o `guardar`: `supcoflow politica fijar --modo guardar`.");
+    }
+    const modo = flags.modo;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const ruta = rutaDe(p.proyecto, "/politica");
+    if (flags.dryRun)
+        return dryRun(`POST ${ruta} {modo: ${modo}}`);
+    let r;
+    try {
+        r = await d.configurar(d.api, p.clave, ruta, { modo });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    return desenlace(r, (c) => ({
+        codigo: SALIDA.ok,
+        json: { ok: true, politica: c.politica },
+        texto: `Política de problemas fijada: ${modo}.`,
+    }));
+}
+export async function comandoCatalogo(d) {
+    const leida = await claveVigente(d.guardado, d.api.origin);
+    if (!leida.ok)
+        return leida.resultado;
+    try {
+        const c = await d.leerCatalogo(d.api, leida.vigente.clave);
+        const items = c.supcoflow.map((i) => `${i.clave}: ${i.valores}`);
+        return { codigo: SALIDA.ok, json: { ok: true, ...c }, texto: items.join("\n") };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

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.3.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -40,6 +40,148 @@ 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. Sin skill aprobada hace falta una persona (sale 4).",
+            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],
+        },
     ],
     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: [

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) };
+    }
+}