supcoflow 0.5.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ La terminal de [Supcoflow](https://app.supcoflow.dev): iniciar sesión y manejar
 desde la consola, o desde un asistente de código que corre comandos por vos.
 
 Trae iniciar y cerrar sesión, ver con qué cuenta estás, conectar el repo con la App de GitHub,
-crear su proyecto y configurar el chat.
+crear su proyecto, configurar el chat y ponerlo en la app.
 
 ## Instalar
 
@@ -30,6 +30,8 @@ npx supcoflow login
 | `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 widget` | Lo que hay que pegar en la app para tener el chat (ver «Poner el chat en la app»). |
+| `supcoflow instalacion anotar --skill 0.1.0` | Anota en `.supcoflow/instalacion.json` con qué versiones se instaló el chat. |
 | `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
@@ -117,6 +119,41 @@ Problemas comunes:                                            ← opcional; hast
 - 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`.
 
+## Poner el chat en la app
+
+`supcoflow widget` muestra lo que hay que pegar, armado por el motor con los ids de tu proyecto (no los
+copies a mano: un id mal copiado deja el chat invisible sin ningún error). No escribe archivos de la app:
+
+1. El paquete con su versión exacta (`npm i @supcoflow/chat@… --save-exact`, o lo mismo con tu gestor).
+2. **Next.js (App Router):** un archivo envoltorio en la ruta que sugiere el motor
+   (`app/_supcoflow/chat-de-soporte.tsx`; si la app usa `src/app`, dentro de `src/app`), con el contenido
+   tal cual. Hace falta porque el componente del chat usa hooks de React y no trae `"use client"`, y un
+   `layout.tsx` es de servidor por defecto: importarlo directo ahí no anda. El envoltorio es esa directiva
+   más el componente con los ids.
+3. Usar el envoltorio en el layout que cubre las pantallas donde se traban tus usuarios.
+4. Si la app tiene una política de contenido (CSP) con `connect-src`, agregarle el origen del chat
+   conservando lo que ya tiene (una segunda `connect-src` se ignora).
+
+La línea de `<script>` que también muestra está disponible pero no probada en una app real, y no es
+para Next.js. `supcoflow widget --json` devuelve el objeto del motor tal cual.
+
+Después, `supcoflow instalacion anotar --skill <versión> [--app <carpeta>]` deja en
+`.supcoflow/instalacion.json` (para commitear) con qué versiones quedó: la skill, la terminal, el chat
+declarado e instalado, y la configuración del proyecto. Nunca lleva un secreto ni una fecha; repetirlo
+sin cambios no lo toca, y si el archivo tiene cambios sin commit sale 4 y no lo pisa.
+
+## Con un asistente
+
+Si usás un asistente de código como Claude Code, la skill de Supcoflow hace todo el camino
+por vos: sesión, proyecto, configuración, guía, el chat en la app y el resumen.
+
+```bash
+npx skills add supcoflow/skills
+```
+
+Y en el asistente: `/supcoflow go`. Las decisiones sobre los datos de tus usuarios y qué pasa con cada
+problema te las pregunta siempre; no sube nada a GitHub.
+
 ## El contrato
 
 Pensado para que lo lea un programa, no sólo una persona:
@@ -126,7 +163,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`, `guia revisar`, `guia publicar`, `guia usar`). `login --wait
+  `proyecto crear`, `guia revisar`, `guia publicar`, `guia usar`, `instalacion anotar`). `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.5.0); sólo identifica a la terminal
+// A mano a propósito: tiene que coincidir con package.json (0.6.0); sólo identifica a la terminal
 // en los logs del motor, no decide nada.
-const VERSION = "0.5.0";
+const VERSION = "0.6.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
@@ -312,3 +312,28 @@ export function leerGuia(api, clave, proyectoId, f) {
 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);
 }
+// Se valida campo a campo: lo que se le pasa a la persona (y de ahí a un archivo de su app) no puede
+// ser algo a medias. `contenido` se guarda tal cual, sin tocarlo: los ids ya vienen puestos por el motor.
+function aWidget(v, status) {
+    const n = (typeof v.nextjs === "object" && v.nextjs !== null ? v.nextjs : {});
+    const s = (typeof v.script === "object" && v.script !== null ? v.script : {});
+    const [tenantId, projectId, backendUrl, version, instalar, csp] = [v.tenant_id, v.project_id, v.backend_url, v.version, v.instalar, v.csp].map(texto);
+    const [archivo, contenido, uso] = [n.archivo_sugerido, n.contenido, n.uso].map(texto);
+    const linea = texto(s.linea);
+    if (!tenantId || !projectId || !backendUrl || !version || !instalar || !csp || v.paquete !== "@supcoflow/chat"
+        || (n.estado !== "probando" && n.estado !== "soportado") || !archivo || !contenido || !uso
+        || s.estado !== "disponible_sin_soporte" || !linea)
+        throw inesperada(status);
+    return {
+        tenant_id: tenantId, project_id: projectId, backend_url: backendUrl, paquete: "@supcoflow/chat", version, instalar,
+        nextjs: { estado: n.estado, archivo_sugerido: archivo, contenido, uso },
+        script: { estado: "disponible_sin_soporte", linea },
+        csp,
+    };
+}
+export async function leerWidget(api, clave, proyectoId, f) {
+    const r = await conClave(api, clave, `/api/proyectos/${encodeURIComponent(proyectoId)}/widget`, { method: "GET" }, f);
+    if (r.status !== 200)
+        throw rechazada(r);
+    return aWidget(r.cuerpo, r.status);
+}

package/dist/argumentos.js

@@ -5,11 +5,12 @@ export const COMANDOS_COMPUESTOS = [
     "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",
+    "instalacion anotar",
 ];
 // 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", "origen",
+    "repo", "install", "test", "sitio", "titulo", "saludo", "archivo", "permitir", "modo", "nombre", "guardar-en", "id", "origen", "skill", "app",
 ];
 // strict: un flag mal escrito (`--estart`) no se ignora en silencio: un asistente creería que
 // pidió algo que no pidió.
@@ -40,6 +41,8 @@ export function leerArgumentos(argv) {
                 id: { type: "string" },
                 origen: { type: "string" },
                 "desde-github": { type: "boolean" },
+                skill: { type: "string" },
+                app: { type: "string" },
                 tema: { type: "string", multiple: true },
             },
             tokens: true,
@@ -97,6 +100,8 @@ export function leerArgumentos(argv) {
             id: v.id ?? null,
             origen: v.origen ?? null,
             desdeGithub: v["desde-github"] === true,
+            skill: v.skill ?? null,
+            app: v.app ?? null,
             tema: v.tema ?? [],
         },
     };

package/dist/cli.js

@@ -7,6 +7,7 @@ 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 { instalacionAnotar } from "./comandos/instalacion.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";
@@ -14,6 +15,7 @@ import { comandoLogout } from "./comandos/logout.js";
 import { proyectoCrear, proyectoVer } from "./comandos/proyecto.js";
 import { comandoQuienSoy } from "./comandos/quien-soy.js";
 import { repoConectarInteractivo, repoConectarStart, repoConectarWait } from "./comandos/repo-conectar.js";
+import { widget } from "./comandos/widget.js";
 import { emitir, FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "./contrato.js";
 import { entornoReal } from "./entorno.js";
 import { flagQueNoAplica } from "./flags-por-comando.js";
@@ -38,6 +40,7 @@ async function correr(argv) {
             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, origen: flags.origen !== null, desdeGithub: flags.desdeGithub,
+            skill: flags.skill !== null, app: flags.app !== null,
         };
         const noAplica = flagQueNoAplica(comando, Object.keys(presentes).filter((k) => presentes[k]));
         if (noAplica !== null)
@@ -123,6 +126,10 @@ async function correr(argv) {
                 return { r: await guiaVer(e.guia, flags), json };
             case "guia usar":
                 return { r: await guiaUsar(e.guia, flags), json };
+            case "widget":
+                return { r: await widget(e.widget, flags), json };
+            case "instalacion anotar":
+                return { r: await instalacionAnotar(e.instalacion, 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.5.0";
+const VERSION = "0.6.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -210,6 +210,26 @@ export const DESCRIPCION = {
             ejemplos: ["supcoflow guia usar --origen repo --json"],
             codigos: [0, 1, 2, 3, 4],
         },
+        {
+            nombre: "widget",
+            resumen: "Muestra lo que hay que pegar en la app para tener el chat, armado por el motor con los ids del proyecto: el paquete y su versión exacta, el archivo envoltorio de Next.js (`nextjs.contenido`, tal cual, sin reescribir los ids), cómo usarlo, la línea de CSP y la de <script> (no para Next.js). No escribe archivos. Sale 4 sin_proyecto si el repo no tiene proyecto; 1 respuesta_inesperada si el motor manda algo a medias.",
+            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json: el objeto del motor tal cual"],
+            ejemplos: ["supcoflow widget --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "instalacion anotar",
+            resumen: "Anota en .supcoflow/instalacion.json (la raíz de este clon) con qué versiones se instaló el chat: la skill, esta terminal, el paquete del chat (declarado en el package.json de la app e instalado en node_modules) y la configuración del proyecto; nunca un secreto ni una fecha. Repetir sin cambios no lo toca (sin_cambios: true). Lo reescribe sólo si git ya guarda el anterior: si tiene cambios sin commit (o está borrado sin commit) sale 4 cambios_sin_commit; si existe sin estar versionado (o ignorado), 4 archivo_no_versionado. Otros: 3 falta_skill / skill_invalida / app_fuera_del_repo / app_inexistente / sin_clon; 4 sin_proyecto / acuerdo_ilegible; 1 paquete_ilegible / configuracion_inesperada / archivo_no_escrito.",
+            flags: [
+                "--skill versión: la metadata.version de la skill que instala (semver, obligatorio; sin él sale 3 falta_skill sin pedir nada)",
+                "--app carpeta: la carpeta de la app, relativa a la raíz del repo (por defecto la raíz; fuera del repo sale 3 app_fuera_del_repo)",
+                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 sin_clon: el archivo va en el clon)",
+                "--dry-run: muestra el archivo y la diferencia sin escribir nada",
+                "--json",
+            ],
+            ejemplos: ["supcoflow instalacion anotar --skill 0.1.0 --app web --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/instalacion.js

@@ -0,0 +1,207 @@
+// src/comandos/instalacion.ts
+// `instalacion anotar --skill <versión> [--app <carpeta>] [--dry-run]` (bloque 6): deja en
+// `.supcoflow/instalacion.json` con qué versiones se instaló el chat. Lee la configuración del motor y los
+// `package.json` de la app y del paquete instalado; nunca ejecuta nada del repo (ni `npm ls` ni `node`).
+//
+// La regla de §13 («no pisa archivos ni cambios sin commit») adaptada a un archivo que tiene que poder cambiar
+// (decisión 11): se reescribe sólo si git ya guarda el anterior. El control se hace ANTES de escribir; si la
+// persona edita el archivo entre el control y el `rename`, su cambio se pierde. Esa carrera se acepta: es una
+// persona instalando, y el archivo lo escribe sólo este comando.
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { armarInstalacion, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar } from "../instalacion.js";
+import { repoPedido } from "../repo-local.js";
+import { fallo } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+export function esCarpetaReal(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function rutaRealOEnNada(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+// Los package.json son chicos; uno de más de 1 MB no es el de una app ni el de un paquete.
+const TOPE_DEL_PACKAGE_JSON = 1024 * 1024;
+const TOPE_DEL_ARCHIVO = 64 * 1024;
+const adentro = (raiz, p) => p === raiz || p.startsWith(raiz + path.sep);
+const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""));
+function leerJson(d, p, nombre) {
+    const leido = d.leerArchivoChico(p, TOPE_DEL_PACKAGE_JSON);
+    if ("error" in leido) {
+        if (leido.error === "no existe")
+            return { ok: false, noExiste: true };
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `No leo ${nombre}: ${limpio(leido.error)}.`) };
+    }
+    try {
+        return { ok: true, valor: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(leido.bytes)) };
+    }
+    catch {
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `${nombre} no es JSON válido.`) };
+    }
+}
+// Como lo resuelve Node desde la app (revisión externa, hallazgo 4): el primer `node_modules/@supcoflow/chat`
+// subiendo desde <app> hasta la raíz del repo. En un monorepo npm lo deja en la raíz; pnpm enlaza a
+// `node_modules/.pnpm/…`, adentro del repo. Si la ruta real sale del repo, no se lee: lo que hay afuera no es
+// de esta instalación y la terminal no lee fuera del repo por un enlace que el repo eligió.
+function paqueteInstalado(d, raiz, app, avisos) {
+    for (let dir = app;; dir = path.dirname(dir)) {
+        const candidato = path.join(dir, "node_modules", ...PAQUETE_DEL_CHAT.split("/"), "package.json");
+        const real = d.rutaReal(candidato);
+        if (real !== null) {
+            if (!adentro(raiz, real)) {
+                const aviso = `${path.relative(raiz, candidato)} apunta fuera del repo; no lo leo y anoto el chat instalado como null.`;
+                avisos.push(aviso);
+                d.avisar(aviso);
+                return { ok: true, valor: null };
+            }
+            const j = leerJson(d, real, `el package.json de ${PAQUETE_DEL_CHAT} instalado`);
+            if (j.ok)
+                return j;
+            // Existía hace un instante: si ahora no está, tampoco se anota «no está».
+            return { ok: false, resultado: j.noExiste ? fallo(SALIDA.inesperado, "paquete_ilegible", `No leo el package.json de ${PAQUETE_DEL_CHAT} instalado.`) : j.resultado };
+        }
+        if (dir === raiz || path.dirname(dir) === dir)
+            return { ok: true, valor: null };
+    }
+}
+async function estadoDelArchivo(d, raizGit, existe) {
+    const git = async (args) => {
+        const r = await d.git(args, raizGit);
+        if (r.codigo !== 0)
+            throw new Error(`git ${args[0]} falló; no escribo ${RUTA_DE_LA_INSTALACION} sin saber si tiene cambios.`);
+        return r.stdout;
+    };
+    const lineas = (await git(["status", "--porcelain", "--ignored", "--", RUTA_DE_LA_INSTALACION])).split("\n").filter((l) => l.trim() !== "");
+    if (lineas.some((l) => !l.startsWith("??") && !l.startsWith("!!")))
+        return "cambios_sin_commit";
+    if (lineas.length > 0)
+        return "archivo_no_versionado";
+    const versionado = (await git(["ls-files", "--", RUTA_DE_LA_INSTALACION])).trim() !== "";
+    return versionado || !existe ? "escribir" : "archivo_no_versionado";
+}
+// Un diff de líneas (LCS) para el texto: los dos lados son chicos. El anterior lo escribió quien sea, así que
+// sale limpio de control y de secretos; el JSON nunca lo lleva.
+function diff(antes, despues) {
+    if (antes === null)
+        return ["--- (no había archivo)", "+++ " + RUTA_DE_LA_INSTALACION, ...despues.trimEnd().split("\n").map((l) => "+ " + l)].join("\n");
+    const a = antes.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n").map(limpio);
+    const b = despues.trimEnd().split("\n");
+    const n = a.length, m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const lineas = ["--- " + RUTA_DE_LA_INSTALACION + " (antes)", "+++ " + RUTA_DE_LA_INSTALACION];
+    let i = 0, j = 0;
+    while (i < n || j < m) {
+        if (i < n && j < m && a[i] === b[j])
+            lineas.push("  " + a[i++]), j++;
+        else if (j < m && (i === n || lcs[i][j + 1] >= lcs[i + 1][j]))
+            lineas.push("+ " + b[j++]);
+        else
+            lineas.push("- " + a[i++]);
+    }
+    return lineas.join("\n");
+}
+const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declarado ${x.chat.declarado ?? "—"} / instalado ${x.chat.instalado ?? "—"}`;
+export async function instalacionAnotar(d, flags) {
+    if (flags.skill === null)
+        return fallo(SALIDA.entradaInvalida, "falta_skill", "Falta la versión de la skill: `supcoflow instalacion anotar --skill 0.1.0`.");
+    if (!esSemver(flags.skill))
+        return fallo(SALIDA.entradaInvalida, "skill_invalida", "--skill va con una versión semver (por ejemplo 0.1.0).");
+    // ─── La raíz y la app, antes de cualquier pedido ───
+    let raizGit;
+    try {
+        raizGit = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    if (raizGit === null)
+        return fallo(SALIDA.entradaInvalida, "sin_clon", `No tengo el clon de ese repo acá, y ${RUTA_DE_LA_INSTALACION} va en el clon: parate en el clon del repo.`);
+    const raiz = d.rutaReal(raizGit);
+    if (raiz === null)
+        return fallo(SALIDA.inesperado, "inesperado", "No pude resolver la raíz del repo.");
+    // `realpath` DESPUÉS de resolver: un `--app` que es un enlace hacia afuera tiene que quedar afuera (Review Focus 4).
+    const app = d.rutaReal(path.resolve(raiz, flags.app ?? "."));
+    if (app === null)
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "La carpeta de --app no existe (va relativa a la raíz del repo).");
+    if (!adentro(raiz, app))
+        return fallo(SALIDA.entradaInvalida, "app_fuera_del_repo", "--app tiene que ser una carpeta dentro del repo (relativa a su raíz).");
+    // Un archivo no es una app: sin esto, leer `<archivo>/package.json` daba ENOTDIR y salía `paquete_ilegible`.
+    if (!d.esCarpeta(app))
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "--app tiene que ser una carpeta (la de la app), no un archivo.");
+    // ─── Proyecto → configuración → package.json de la app → paquete instalado → armar ───
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    let configuracion;
+    try {
+        configuracion = await d.leerConfiguracion(d.api, p.clave, p.proyecto.id);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const deLaApp = leerJson(d, path.join(app, "package.json"), "el package.json de la app");
+    if (!deLaApp.ok && !deLaApp.noExiste)
+        return deLaApp.resultado;
+    const avisos = [];
+    const instalado = paqueteInstalado(d, raiz, app, avisos);
+    if (!instalado.ok)
+        return instalado.resultado;
+    let x;
+    try {
+        x = armarInstalacion({ skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const nuevo = serializar(x);
+    // ─── ¿Se puede escribir? ───
+    const archivo = path.join(raiz, RUTA_DE_LA_INSTALACION);
+    // Una `.supcoflow` que es un enlace hacia afuera: ni se lee (el diff mostraría un archivo de afuera) ni se escribe.
+    const carpeta = d.rutaReal(path.dirname(archivo));
+    if (carpeta !== null && !adentro(raiz, carpeta))
+        return fallo(SALIDA.inesperado, "inesperado", `${path.dirname(RUTA_DE_LA_INSTALACION)} no es una carpeta del repo (¿un enlace?); no escribo ahí.`);
+    const actual = d.leerArchivoChico(archivo, TOPE_DEL_ARCHIVO);
+    const existe = !("error" in actual) || actual.error !== "no existe";
+    const json = { ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, ...(avisos.length > 0 ? { avisos } : {}) };
+    if ("bytes" in actual && Buffer.from(actual.bytes).equals(Buffer.from(nuevo, "utf8"))) {
+        return { codigo: SALIDA.ok, json: { ...json, ...(flags.dryRun ? { dry_run: true } : {}), sin_cambios: true }, texto: `${RUTA_DE_LA_INSTALACION} ya dice eso (${resumen(x)}); no lo toqué.` };
+    }
+    let estado;
+    try {
+        estado = await estadoDelArchivo(d, raizGit, existe);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    if (estado === "cambios_sin_commit") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "cambios_sin_commit", `${RUTA_DE_LA_INSTALACION} tiene cambios sin commit (o se borró sin commit); no lo toqué. Commitealos o descartalos y volvé a correr.`);
+    }
+    if (estado === "archivo_no_versionado") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "archivo_no_versionado", `Ya hay un ${RUTA_DE_LA_INSTALACION} que git no guarda (sin commit o ignorado); no lo pisé. Commitealo o borralo y volvé a correr.`);
+    }
+    const antes = "bytes" in actual ? Buffer.from(actual.bytes).toString("utf8") : null;
+    const cambios = existe && antes === null ? `(el archivo anterior no se lee)\n${diff(null, nuevo)}` : diff(antes, nuevo);
+    if (flags.dryRun) {
+        return { codigo: SALIDA.ok, json: { ...json, dry_run: true, sin_cambios: false }, texto: `Con --dry-run no escribo; sin él anotaría (${resumen(x)}):\n${cambios}` };
+    }
+    try {
+        d.escribir(archivo, nuevo);
+    }
+    catch {
+        return fallo(SALIDA.inesperado, "archivo_no_escrito", `No pude escribir ${RUTA_DE_LA_INSTALACION}. Volvé a correr \`supcoflow instalacion anotar\`.`);
+    }
+    return { codigo: SALIDA.ok, json: { ...json, sin_cambios: false }, texto: `Anoté ${RUTA_DE_LA_INSTALACION} (${resumen(x)}); commitealo cuando quieras.\n${cambios}` };
+}

package/dist/comandos/widget.js

@@ -0,0 +1,32 @@
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+function textoDe(w) {
+    return [
+        "1. Instalá el paquete (con el gestor de la app, la versión exacta):",
+        `   ${w.instalar}`,
+        "",
+        `2. Creá el archivo ${w.nextjs.archivo_sugerido} con este contenido (Next.js, ${w.nextjs.estado}):`,
+        w.nextjs.contenido.trimEnd(),
+        "",
+        "3. Usalo en el layout que cubre las pantallas donde se traban los usuarios:",
+        `   ${w.nextjs.uso}`,
+        "",
+        "4. Política de contenido (CSP): si la app tiene `connect-src`, agregale este origen conservando lo que ya tiene:",
+        `   ${w.csp}`,
+        "",
+        "Alternativa con <script> (disponible, no probada en una app real):",
+        `   ${w.script.linea}`,
+    ].join("\n");
+}
+export async function widget(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        const w = await d.leerWidget(d.api, p.clave, p.proyecto.id);
+        return { codigo: SALIDA.ok, json: { ok: true, ...w }, texto: textoDe(w) };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/entorno.js

@@ -5,8 +5,10 @@ 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, elegirOrigen, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerGuia, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, publicarGuia, revisarGuia, } from "./api.js";
+import { buscarProyecto, canjear, configurar, leerWidget, 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 { esCarpetaReal, rutaRealOEnNada } from "./comandos/instalacion.js";
+import { DESCRIPCION } from "./comandos/describir.js";
 import { almacenDeArchivo } from "./guardado/archivo.js";
 import { crearGuardado } from "./guardado/index.js";
 import { almacenDeLlavero } from "./guardado/llavero.js";
@@ -466,5 +468,18 @@ export function entornoReal(env = process.env) {
             esClaveDeConsultaDelProyecto: (a, clave, id) => esClaveDeConsultaDelProyecto(a, clave, id, fetch),
             idempotencia, candados, secretos,
         },
+        widget: {
+            api, guardado, git: gitReal, cwd,
+            buscarProyecto: configurarEnElMotor.buscarProyecto,
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch),
+        },
+        // La versión que se anota es la de `describir` (pinzada contra package.json por test): una sola fuente
+        // para lo que la terminal dice de sí misma.
+        instalacion: {
+            ...configurarEnElMotor,
+            leerArchivoChico, rutaReal: rutaRealOEnNada, esCarpeta: esCarpetaReal,
+            escribir: archivosDelRepo(avisar).escribir,
+            terminal: DESCRIPCION.version,
+        },
     };
 }

package/dist/flags-por-comando.js

@@ -9,8 +9,8 @@ const DE_CONFIGURAR_CON_REPO = [
 export const FLAGS_POR_COMANDO = [
     { flags: ["start", "wait"], comandos: ["login", "repo conectar"], texto: "--start y --wait son de `supcoflow login` y `supcoflow repo conectar`." },
     {
-        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO],
-        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver` y los comandos que configuran un proyecto (no de `catalogo`).",
+        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO, "widget", "instalacion anotar"],
+        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver`, `widget`, `instalacion anotar` y los comandos que configuran un proyecto (no de `catalogo`).",
     },
     { flags: ["install", "test"], comandos: ["proyecto crear"], texto: "--install y --test son de `supcoflow proyecto crear`." },
     { flags: ["sitio"], comandos: ["sitios agregar", "sitios quitar"], texto: "--sitio es de `supcoflow sitios agregar|quitar`." },
@@ -22,6 +22,7 @@ export const FLAGS_POR_COMANDO = [
     { 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`." },
+    { flags: ["skill", "app"], comandos: ["instalacion anotar"], texto: "--skill y --app son de `supcoflow instalacion anotar`." },
 ];
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */
 export function flagQueNoAplica(comando, presentes) {

package/dist/instalacion.js

@@ -0,0 +1,86 @@
+// `.supcoflow/instalacion.json` (bloque 6, decisión 3): con qué versiones se hizo la instalación, anotado en el
+// repo de quien instala. Supcoflow no lo guarda ni lo ve. Puro: recibe lo ya leído y arma el archivo.
+//
+// El archivo queda en el repo y se commitea: un secreto acá se publica con el primer `push`. Por eso se arma con
+// una LISTA CERRADA de campos, cada uno validado por separado; nunca un `...configuracion` (la configuración del
+// motor trae `fijado_por`, `publicada_por`, huellas y lo que el motor agregue mañana: nada de eso es de este archivo).
+import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
+export const RUTA_DE_LA_INSTALACION = ".supcoflow/instalacion.json";
+export const PAQUETE_DEL_CHAT = "@supcoflow/chat";
+// SemVer 2.0 tal cual, con tope de largo: la versión de la skill la escribe un asistente y queda en el repo.
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const esSemver = (s) => s.length <= 64 && SEMVER.test(s);
+const objeto = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? v : null);
+const entero = (v) => typeof v === "number" && Number.isInteger(v) && v >= 1;
+const ilegible = (message) => new FalloDeLaTerminal(SALIDA.inesperado, "paquete_ilegible", message);
+const inesperada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "configuracion_inesperada", `El motor contestó la configuración con ${que} que no entiendo; no anoto nada a medias. Probá de nuevo en un rato.`);
+// Lo declarado en el `package.json` de la app lo escribió quien escribió el repo: puede ser un rango, un alias o
+// cualquier cosa. Se copia tal cual sólo si es texto imprimible y corto; si no, no se adivina (`paquete_ilegible`).
+// `taparSecretos` igual, por si alguien pegó una clave ahí: el archivo nuevo no la repite.
+function declaradoEn(app) {
+    const a = objeto(app);
+    if (a === null)
+        return null;
+    const v = objeto(a.dependencies)?.[PAQUETE_DEL_CHAT] ?? objeto(a.devDependencies)?.[PAQUETE_DEL_CHAT];
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== "string" || v.length === 0 || v.length > 200 || !/^[\x20-\x7e]+$/.test(v)) {
+        throw ilegible(`La versión de ${PAQUETE_DEL_CHAT} en el package.json de la app no se entiende; no la anoto.`);
+    }
+    return taparSecretos(v);
+}
+// `null` es «no está instalado». Un archivo que existe pero sin versión válida NO es null: diría que no está.
+function instaladoEn(paquete) {
+    if (paquete === null)
+        return null;
+    const v = objeto(paquete)?.version;
+    if (typeof v !== "string" || !esSemver(v))
+        throw ilegible(`El package.json de ${PAQUETE_DEL_CHAT} instalado no trae una versión que entienda.`);
+    return v;
+}
+function acuerdoDe(c) {
+    if (c.acuerdo === null)
+        return null;
+    const a = objeto(c.acuerdo);
+    // Ilegible es un estado conocido del motor (aplica cerrado), no «sin acuerdo»: anotarlo como null mentiría.
+    if (a?.ilegible === true) {
+        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, "acuerdo_ilegible", "El acuerdo de datos está fijado pero no se lee: revisalo en la consola y volvé a correr.");
+    }
+    if (a === null || !entero(a.version))
+        throw inesperada("un acuerdo");
+    return a.version;
+}
+function politicaDe(c) {
+    const modo = objeto(c.politica)?.modo;
+    if (modo !== "relevar" && modo !== "guardar")
+        throw inesperada("una política");
+    return modo;
+}
+function guiaDe(c) {
+    if (c.guia === null)
+        return null;
+    const g = objeto(c.guia);
+    if (g?.origen === "repo") {
+        if (g.procedencia !== "terminal" && g.procedencia !== "github")
+            throw inesperada("una guía");
+        if (g.commit !== null && (typeof g.commit !== "string" || !/^[0-9a-f]{40}$/.test(g.commit)))
+            throw inesperada("una guía");
+        return { origen: "repo", procedencia: g.procedencia, commit: g.commit };
+    }
+    if (g?.origen === "agente" && entero(g.version))
+        return { origen: "agente", version: g.version };
+    throw inesperada("una guía");
+}
+export function armarInstalacion(i) {
+    return {
+        version: 1,
+        skill: i.skill,
+        terminal: i.terminal,
+        chat: { declarado: declaradoEn(i.paqueteDeLaApp), instalado: instaladoEn(i.paqueteInstalado) },
+        configuracion: { acuerdo_version: acuerdoDe(i.configuracion), politica: politicaDe(i.configuracion), guia: guiaDe(i.configuracion) },
+    };
+}
+// El orden de las claves es el de `armarInstalacion`: el mismo estado da los mismos bytes, y eso es `sin_cambios`.
+export function serializar(x) {
+    return JSON.stringify(x, null, 2) + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supcoflow",
-  "version": "0.5.0",
+  "version": "0.6.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" },