xonecode 0.38.41 → 0.39.2

package/dist/core/conectores.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Los conectores MCP de la consola: servidores REMOTOS con los que se conecta esta máquina.
+ * Puro a propósito —catálogo, formas del cable y reglas—; el disco y la red viven en
+ * `agent/conectores/`.
+ *
+ * **Hay DOS familias y una sola forma de fila.** El CATÁLOGO son las filas que vienen por
+ * código (`CATALOGO_DE_CONECTORES`), y una DEFINICIÓN es una fila que escribió el usuario y
+ * vive en su disco. Las dos se resuelven al mismo `ConectorDeCatalogo`, así que de ahí para
+ * abajo —estado, prueba, autorización, botones— nada sabe de qué familia viene: es lo que
+ * hace que un servidor añadido a mano se comporte como Jira.
+ *
+ * **Llegan a los agentes de TrueForge** por `ConectoresPort` (`agent/motores/trueforge/
+ * toolsDeConectores.ts`): qué conectores (`conectoresParaElAgente`), a quién (`recibeConectores`)
+ * y qué ve el modelo (`esquemaParaElModelo`, `resultadoRecortado`) se decide aquí, puro.
+ */
+import type { Agente } from "./agentes.js";
+export type AutenticacionDeConector = "ninguna" | "oauth" | "api-key";
+/**
+ * El literal, comprobado por VALOR: es lo que llega por el cable, donde puede mentir.
+ *
+ * Se usa dos veces y por eso es una función y no tres `===` repetidos: al validar la
+ * definición que entra, y —su copia DECLARADA, porque la frontera del cliente no deja
+ * importar de aquí— en la guarda del store, que descarta la fila ENTERA en silencio si no
+ * reconoce el literal. Añadir un carril de autenticación y no tocar esa guarda deja la fila
+ * invisible con todo en verde.
+ */
+export declare function esAutenticacionDeConector(valor: unknown): valor is AutenticacionDeConector;
+export interface ConectorDeCatalogo {
+    readonly id: string;
+    readonly nombre: string;
+    readonly url: string;
+    readonly descripcion: string;
+    readonly autenticacion: AutenticacionDeConector;
+    /**
+     * En qué cabecera viaja la clave de un `api-key`, con el valor TAL CUAL. Ausente es
+     * `Authorization: Bearer <clave>`, lo de siempre. Existe por Stitch, medido el 30-09-2026: su
+     * clave va en `X-Goog-Api-Key`, y como `Bearer` contesta 401.
+     */
+    readonly cabeceraDeClave?: string;
+    /**
+     * Una tool de LECTURA, sin argumentos, que `probar` llama después de `listTools`, para los
+     * servidores que listan sus tools a cualquiera. Medido en Stitch: `tools/list` contesta 200 sin
+     * clave y con una clave falsa, así que sin esto «Conectado · 15 tools» saldría con cualquier cosa.
+     */
+    readonly comprobacion?: string;
+    /**
+     * Tools que NO se montan en un agente, aunque el servidor las ofrezca. Medido en Stitch: sus 15
+     * tools son unos 11k tokens en CADA llamada del agente que las recibe, y `create_design_system`
+     * y `update_design_system` son dos tercios (el mismo esquema de 15 KB cada una) — el sistema de
+     * diseño se hace igual con `upload_design_md` + `create_design_system_from_design_md`. Y borrar
+     * un proyecto de la cuenta no es trabajo de un agente.
+     */
+    readonly fueraDelAgente?: readonly string[];
+    /**
+     * Por tool, los campos del resultado (JSON) que el agente NO recibe, a cualquier profundidad.
+     * Medido en Stitch: `list_projects` son 143 KB para 16 proyectos —el `designMd` entero de cada
+     * uno, sus pantallas y miniaturas— y el agente no podía ni contarlos (se desalojaba y acabó
+     * lanzando scripts). Sin esos campos, 4 KB. El detalle sigue a mano con `get_project`.
+     */
+    readonly camposFueraDelResultado?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Medido contra los tres servidores el 24-09-2026: deepwiki contesta `listTools` sin
+ * credenciales; Notion y Atlassian publican `registration_endpoint` y S256, y aceptan un
+ * cliente público con `redirect_uri` en loopback. Stitch (30-09-2026) lleva la clave en su propia
+ * cabecera y se comprueba con una llamada, ver `cabeceraDeClave`. El transporte NO se declara: se prueba
+ * `streamable-http` y, si no, `sse`, como hace TrueForge.
+ */
+export declare const CATALOGO_DE_CONECTORES: readonly ConectorDeCatalogo[];
+export declare function conectorDelCatalogo(id: string): ConectorDeCatalogo | undefined;
+/**
+ * Lo que se puede PEDIR sobre un conector. Es una lista blanca por valor: lo que llega por el
+ * cable elige entre estas seis y nada más, y `crear` no es una más —es la única que no lleva
+ * `id`, porque el id lo DERIVA el servidor del nombre—, así que quien la lea tiene que mirar
+ * la acción ANTES de exigir el id.
+ */
+export type AccionDeConector = "anadir" | "quitar" | "probar" | "autorizar" | "desconectar" | "crear";
+/**
+ * Una fila del catálogo tal como VIAJA: los cuatro campos menos la `url`. Es la lista con la que
+ * el cliente pone nombre y descripción a cada `id` de un `ConectorDelCable`, y por eso tiene que
+ * ser `catálogo ∪ definiciones`: con solo las filas de código, un conector escrito a mano se
+ * quedaría sin nombre en pantalla y el cliente caería a un `?? id` que enseña el slug crudo.
+ *
+ * La `url` no está y no es un olvido: en pantalla no hace falta, y una ruta remota de más es una
+ * que discutir. Lo único que la cruza es la de una definición, y solo en el sentido
+ * cliente→servidor (`DefinicionDeConector`).
+ */
+export interface FilaDeCatalogo {
+    readonly id: string;
+    readonly nombre: string;
+    readonly descripcion: string;
+    readonly autenticacion: AutenticacionDeConector;
+}
+/** Una fila resuelta, recortada a lo que viaja. Una sola función para las dos familias. */
+export declare function filaDeCatalogo(c: ConectorDeCatalogo): FilaDeCatalogo;
+/**
+ * Un conector añadido A MANO: lo que una fila del catálogo tiene por código, esto lo tiene
+ * por disco. Sin `id` — el id se DERIVA del nombre (`idDeConectorPropio`), y un campo que se
+ * deriva no se guarda.
+ *
+ * Su `url` es lo único de esta pieza que cruza el cable en el sentido cliente→servidor, y es
+ * inevitable: la escribió una persona en el formulario. Lo que NO cruza nunca de vuelta es la
+ * `url` de la fila —ni la del catálogo ni la de una definición—, por el mismo motivo que la
+ * del catálogo ya no viaja: en pantalla no hace falta, y una ruta remota de más es una que
+ * discutir.
+ */
+export interface DefinicionDeConector {
+    readonly nombre: string;
+    readonly descripcion: string;
+    readonly url: string;
+    readonly autenticacion: AutenticacionDeConector;
+}
+/**
+ * El prefijo de un conector propio es el MISMO literal que el de un proveedor personalizado
+ * (`modelos.ts#PREFIJO_PERSONALIZADO`), y a propósito: en el producto `custom:` significa una
+ * sola cosa —«esto lo añadiste tú»— y un segundo literal sería un segundo sitio donde
+ * decidirla. Las dos familias NO se cruzan: un id de conector no se le pasa jamás a una
+ * función de proveedor, ni al revés, así que compartir el prefijo no las mezcla.
+ */
+export declare function esConectorPropio(id: string): boolean;
+export declare function slugDeConectorPropio(id: string): string;
+export declare function idDeConectorPropio(slug: string): string;
+/**
+ * El id de un conector escrito a mano, derivado de su NOMBRE. Se deriva y no se guarda —un
+ * campo derivado es un campo que puede contradecir a su fuente—, y sale de aquí y no de quien
+ * llama para que la regla del slug viva en UN sitio: quien valida una definición y quien la
+ * guarda tienen que derivar el MISMO id, o el rechazo por id ocupado hablaría de otro.
+ */
+export declare function idDeConectorDesdeNombre(nombre: string): string;
+/**
+ * Una definición como la fila que representa, para que `resolver` devuelva SIEMPRE lo mismo
+ * y ninguna capa de más abajo tenga que saber de qué familia viene un conector.
+ */
+export declare function conectorDeDefinicion(id: string, def: DefinicionDeConector): ConectorDeCatalogo;
+/**
+ * La definición tal como llega por el cable, o `undefined` si no tiene la forma.
+ *
+ * La FORMA y la SEMÁNTICA van separadas a propósito: aquí solo se comprueba que los cuatro
+ * campos sean cadenas del tipo que dicen ser —el JSON de un cliente puede mentir sobre lo
+ * que el tipo promete—, y lo que tiene que valer cada uno lo decide
+ * `motivoDeDefinicionInaceptable`, que es la regla y tiene sus tests.
+ */
+export declare function definicionDelCable(valor: unknown): DefinicionDeConector | undefined;
+/**
+ * ¿Vale eso como conector nuevo? Devuelve el MOTIVO del rechazo, o `undefined` si pasa.
+ *
+ * `idsOcupados` son los ids ya AÑADIDOS más los que tienen definición, y NO el catálogo. La
+ * diferencia importa y es deliberada: lo que choca es crear DOS VECES el mismo nombre —el
+ * segundo pisaría la definición del primero, y su URL y su clave se quedarían apuntando a otro
+ * servidor—, y una definición huérfana (una que se añadió a mano al fichero, o la que dejó un
+ * `quitar` que falló) también ocupa su sitio por eso mismo. Un conector propio llamado «Jira»
+ * NO choca con la fila del catálogo, que vive en `jira` y no en `custom:jira`: montar tu propio
+ * servidor de Jira es una razón real para darlo de alta a mano, y ahí los dos conviven cada uno
+ * con su fila. El id se deriva con la MISMA regla que un proveedor personalizado
+ * (`modelos.ts`): un segundo slug sería un segundo sitio donde divergir, y el slug acaba siendo
+ * clave de un fichero.
+ */
+export declare function motivoDeDefinicionInaceptable(def: DefinicionDeConector, idsOcupados: readonly string[]): string | undefined;
+/** Lo que dice el DISCO, no una medida: la medida es `PruebaDeConector`. */
+export type EstadoDeConector = "sin-autorizacion" | "falta-autorizar" | "autorizado";
+/**
+ * El segundo parámetro se llama `hayCredencial` y no `hayTokens` porque la pregunta que
+ * contesta es «¿hay con qué autenticarse?»: un OAuth guarda tokens y un `api-key` guarda su
+ * clave, y desde aquí son la misma pregunta. Quien pregunta resuelve la suya —el servicio
+ * mira los dos campos de su fichero de secretos— y le pasa un booleano.
+ */
+export declare function estadoDeConector(conector: ConectorDeCatalogo, hayCredencial: boolean): EstadoDeConector;
+/** Una tool tal como la enseña Ajustes. `soloLectura` ausente = el servidor no lo anota. */
+export interface ToolDeConector {
+    nombre: string;
+    descripcion?: string;
+    soloLectura?: boolean;
+}
+/**
+ * Una tool tal como la recibe un AGENTE: la de Ajustes más su esquema de entrada (JSON Schema,
+ * con sus `$defs`). Es otro tipo y no un campo más de `ToolDeConector` porque aquella viaja por el
+ * cable en cada foto de la prueba, y los esquemas de Stitch pesan decenas de KB.
+ */
+export interface ToolConEsquema extends ToolDeConector {
+    esquema: Record<string, unknown>;
+}
+/** La última vez que se probó: una FOTO con hora. Ausente = no se ha probado. */
+export type PruebaDeConector = {
+    cuando: number;
+    ok: true;
+    tools: ToolDeConector[];
+} | {
+    cuando: number;
+    ok: false;
+    motivo: string;
+};
+/**
+ * Un conector AÑADIDO, en la forma del cable. Nunca lleva tokens, ni clave, ni URL de
+ * autorización.
+ *
+ * **No lleva `nombre` ni `descripcion`**: esos los resuelve el cliente buscando este `id` en
+ * la lista que viaja como `catalogo`, y esa lista es `catálogo ∪ definiciones`. Antes esa
+ * búsqueda NO era total —el `catalogo` solo traía las filas de código, así que un conector
+ * añadido a mano se quedaba sin nombre y el cliente caía a un `?? conector.id`—; con la lista
+ * completa lo es, y por eso no hay aquí una segunda copia de los mismos cuatro campos.
+ */
+export interface ConectorDelCable {
+    id: string;
+    estado: EstadoDeConector;
+    prueba?: PruebaDeConector;
+    /** Hay una autorización abierta en el navegador esperando su callback. */
+    autorizando?: boolean;
+}
+/** 10 min, el mismo plazo que TrueForge da a una autorización pendiente. */
+export declare const TTL_DE_AUTORIZACION_MS: number;
+/** Conectar + listar tools: más que esto es «no responde». */
+export declare const TOPE_DE_CONEXION_MS: number;
+/**
+ * Una llamada de un AGENTE a una tool: generar una pantalla en Stitch tarda minutos (medido: casi
+ * dos), y con el tope de conexión el agente veía un fallo de algo que sí terminaba. El SDK tiene su
+ * PROPIO tope por petición (60 s por omisión), así que este valor se le pasa también a él.
+ */
+export declare const TOPE_DE_LLAMADA_MS: number;
+/** La ruta del callback. PÚBLICA: la redirección llega sin cookie (`SameSite=Strict`). */
+export declare const RUTA_CALLBACK_MCP = "/mcp/oauth/callback";
+export interface Pendiente {
+    id: string;
+    expira: number;
+}
+export type ResultadoDeCallback = {
+    ok: true;
+    id: string;
+    code: string;
+} | {
+    ok: false;
+    motivo: string;
+};
+/**
+ * La autenticación de la ruta pública ES el `state`: aleatorio, de un solo uso y con
+ * plazo. Se CONSUME en cuanto se reconoce, vaya bien o mal, para que no se pueda repetir.
+ *
+ * El `motivo` es siempre una frase NUESTRA: la query la escribe quien redirige, y repetirla
+ * en una página nuestra sería servir contenido ajeno desde el origen de la consola.
+ */
+export declare function interpretarCallback(query: URLSearchParams, pendientes: Map<string, Pendiente>, ahora: number): ResultadoDeCallback;
+/** Un conector tal como lo monta una sesión del agente: con lo que el catálogo le recorta. */
+export interface ConectorParaElAgente {
+    id: string;
+    nombre: string;
+    fueraDelAgente: readonly string[];
+    camposFueraDelResultado: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Qué conectores del proyecto llegan a un AGENTE: los marcados en su `config.json`
+ * (`conectores`), que sigan AÑADIDOS y que esta consola sepa nombrar — y NUNCA el del gestor de
+ * tareas vinculado, aunque esté en la misma lista (vincular lo marca): en Jira y en Notion escribe
+ * el HARNESS, con su tarjeta, nunca el agente. El orden es el de los marcados; un id repetido
+ * sale una vez.
+ */
+export declare function conectoresParaElAgente(entrada: {
+    marcados: readonly string[];
+    gestor?: string | undefined;
+    anadidos: readonly string[];
+    catalogo: readonly FilaDeCatalogo[];
+}): ConectorParaElAgente[];
+/** Lo que admite un nombre de función en los proveedores de modelos: `^[a-zA-Z0-9_-]{1,64}$`. */
+export declare const LARGO_MAXIMO_DE_NOMBRE_DE_TOOL = 64;
+/**
+ * Cómo se llama la tool `tool` del conector `id` DENTRO del agente: `stitch__list_projects`. El
+ * prefijo evita que dos conectores con una tool del mismo nombre se pisen, y dice de dónde viene.
+ * Un `custom:acme` lleva `:`, que un proveedor rechaza como nombre de función: todo lo que no sea
+ * `[a-zA-Z0-9_-]` pasa a `_`. Recortado al máximo; devuelve `undefined` si ni así cabe algo que
+ * identifique a la tool (un prefijo que ya ocupa el máximo).
+ */
+export declare function nombreDeToolDeConector(id: string, tool: string): string | undefined;
+/**
+ * Qué tools de los conectores recibe un ESPECIALISTA: todas, solo quien hace los RECURSOS —su
+ * `escribeEn` cubre `icons/`, de los de serie `designer-xone`—, que es quien diseña; el resto,
+ * ninguna. Regla de DATO, no una lista de nombres. Estrecha a propósito: las tools de un conector
+ * viajan en CADA llamada del agente que las recibe (las de Stitch, miles de tokens). El raíz recibe
+ * solo las de LECTURA, y eso lo decide la sesión: es de solo lectura por permisos.
+ */
+export declare function recibeConectores(a: Pick<Agente, "soloLectura" | "ejecucion" | "escribeEn">): boolean;
+/** Cuántos `$ref` anidados se incrustan antes de cortar: un esquema recursivo no puede colgar esto. */
+export declare const PROFUNDIDAD_MAXIMA_DE_REF = 8;
+/**
+ * El esquema de una tool tal como se le puede dar a CUALQUIER proveedor de modelos. Medido con
+ * Stitch y Gemini: los esquemas de Google llevan claves propias (`x-google-identifier`,
+ * `x-google-enum-descriptions`…) y la API de Gemini RECHAZA la petición entera por una sola —el
+ * turno moría antes de empezar—. Se quitan las claves `x-…` (son anotaciones, no restricciones) y
+ * se INCRUSTA cada `$ref` local (`#/$defs/…`), que no todos los proveedores siguen; `$defs` sale
+ * con ellos. Dentro de `properties` las claves son NOMBRES de campo y no se tocan. Puro: no
+ * modifica lo que recibe.
+ */
+export declare function esquemaParaElModelo(esquema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * El resultado de una tool sin los `campos` que el catálogo le recorta (`camposFueraDelResultado`),
+ * a cualquier profundidad, con una línea al final que dice cuáles faltan —que el agente no los dé
+ * por inexistentes—. Lo que no es JSON, o no trae ninguno, vuelve TAL CUAL.
+ */
+export declare function resultadoRecortado(texto: string, campos: readonly string[]): string;

package/dist/core/config.d.ts

@@ -0,0 +1,148 @@
+/**
+ * La validación PURA de los dos ficheros de configuración: sin tocar disco (eso es cosa
+ * de `agent/config/configEnDisco.ts`) y sin importar nada de langchain — la frontera de `core/`
+ * está probada en `imports.test.ts`.
+ *
+ * Dos ficheros con dos ciclos de vida distintos, como opencode:
+ *
+ *  - `config.json` (proyecto o global): modelos y proveedores. Comiteable. NUNCA claves.
+ *    Una clave aquí no se avisa: se RECHAZA, porque un aviso dejaría el fichero
+ *    funcionando y la clave camino del commit. La alternativa —`~/.xonecode/auth.json`—
+ *    está a un comando de distancia.
+ *  - `auth.json` (solo global): las credenciales. En un proyecto se rechaza entero, y se
+ *    comprueba el modo: un `chmod` de más, un `cp -r` o un backup restaurado dejan el
+ *    fichero legible por otros, y eso hay que cantarlo al leerlo, no al día del incidente.
+ *
+ * Y la regla que sostiene a las dos: un aviso NUNCA contiene el valor rechazado, ni
+ * truncado. Un mensaje de error acaba en logs, capturas e issues; el aviso dice QUÉ
+ * campo, no QUÉ contenía. Por eso estos mensajes no interpolan nunca el valor de entrada.
+ */
+import { type MotorDeAgente } from "./motor.js";
+import { type Proveedor, type ProveedorDeclarado } from "./modelos.js";
+import { type VinculoGuardado } from "./gestorDeTareas.js";
+import type { Papel } from "./ports.js";
+import { type ModoDeEscritura } from "./modoDeEscritura.js";
+import { type DisenoVinculado } from "./disenoVinculado.js";
+/** La configuración: modelos y proveedores. Nunca claves. */
+export interface ConfigDeFichero {
+    /** Cómo se abrió este proyecto. Las credenciales nunca se guardan aquí. */
+    modo?: "offline" | "cloud";
+    modelo?: string;
+    /** El motor de agente de las sesiones NUEVAS (`core/motor.ts`). Ausente = `MOTOR_POR_OMISION`. */
+    motor?: MotorDeAgente;
+    modelos?: Partial<Record<Papel, string>>;
+    /** Tema visual de la consola, persistido solo cuando pertenece al proyecto. */
+    tema?: string;
+    /**
+     * A qué entorno de `~/.xonecode/settings.json` pertenece este proyecto.
+     *
+     * Convive con `cloudstudio.url` y no la sustituye: el `entorno` es la referencia (la que
+     * dice de qué juego de credenciales OAuth se lee, `porEntorno[id]` en
+     * `agent/cloudstudio/cloudstudioMcp.ts`) y la URL es la copia operativa que la sincronización lee
+     * exactamente igual que antes de que los entornos existieran. Quitar la URL habría
+     * obligado a tocar `crearSincronizador` y todo lo que cuelga de él, que es justo lo que
+     * el diseño de la consola web se comprometió a no tocar.
+     */
+    entorno?: string;
+    /** Endpoint MCP de CloudStudio. Las credenciales OAuth viven solo en el almacén global. */
+    cloudstudio?: {
+        url: string;
+        scopes?: string[];
+        /** Identidad no sensible del proyecto remoto elegido. */
+        proyecto?: {
+            id: string;
+            nombre: string;
+        };
+        /** La rama ORIGEN: de la que se baja y contra la que se compara. */
+        rama?: string;
+    };
+    ollama?: {
+        baseUrl?: string;
+    };
+    /**
+     * Endpoints compatibles con OpenAI dados de alta por el usuario. **Solo en el
+     * `config.json` GLOBAL**: en el del proyecto se rechaza, y no es purismo de ámbito.
+     *
+     * La clave de un personalizado se guarda en `auth.json` bajo su slug, así que un
+     * proyecto que pudiera redefinir la `baseUrl` de un slug ya existente mandaría esa clave
+     * al host que él dijera, sin que nadie tocara nada. Un `config.json` de proyecto es un
+     * fichero que puede venir de fuera; el global es del dueño de la máquina.
+     */
+    proveedores?: ProveedorDeclarado[];
+    /** Topes de ventana de contexto fijados a mano, por id «proveedor/modelo». */
+    contextos?: Record<string, number>;
+    /** Ids de conectores MCP (IXCODE-11, `core/conectores.ts`) que este proyecto usa. */
+    conectores?: string[];
+    /** El gestor de tareas vinculado (IXCODE-11): a qué conector, sitio y proyecto remoto. */
+    gestorDeTareas?: VinculoGuardado;
+    /** El proyecto de Stitch vinculado (`core/stitch.ts#DisenoVinculado`): de él se eligen las pantallas de una tarea. */
+    disenoVinculado?: DisenoVinculado;
+    /**
+     * El modo con que NACEN las sesiones nuevas de este proyecto (IXCODE-31). Pisa al global
+     * (`settings.json#modoDeEscritura`); ausente = el global. **Solo en el config.json del
+     * PROYECTO**: el global vive en `settings.json`, y uno aquí se descarta diciéndolo, porque dos
+     * sitios para el mismo valor global son dos valores.
+     */
+    modoDeEscritura?: ModoDeEscritura;
+}
+/** Las credenciales, que viven en OTRO fichero y solo global. */
+export type Auth = Partial<Record<Proveedor, {
+    type?: string;
+    key: string;
+}>>;
+export type Procedencia = "proyecto" | "global";
+export interface Aviso {
+    texto: string;
+    severidad: "aviso" | "grave";
+}
+/**
+ * Formas plausibles de colar una clave dentro de un `config.json`. El intento se rechaza
+ * sea cual sea el valor: lo que delata es el NOMBRE del campo, porque una clave con otro
+ * nombre ya no es reconocible — y estas seis cubren lo que la gente escribe a mano.
+ *
+ * Exportada porque `core/settings.ts` la reutiliza tal cual: dos listas de nombres de
+ * credencial que empiezan iguales y divergen con el tiempo es justo el bug que se midió
+ * («key» —el campo que usa `auth.json`— faltaba en la copia que tenía `settings.ts`).
+ */
+/**
+ * ¿Vale eso como clave de API? Devuelve el MOTIVO del rechazo, o `undefined` si pasa.
+ *
+ * La regla no es nuestra: es la que aplica el harness de DeepSeek en su panel de modelos,
+ * y la razón es que una clave de API acaba siendo el valor de una cabecera HTTP — todo
+ * carácter ASCII imprimible (`\x21`–`\x7E`) cabe ahí y ninguno más. Un espacio, un
+ * tabulador, un salto de línea o una eñe no llegan al proveedor: fallan al construir la
+ * petición, o peor, viajan mutilados y el error que vuelve habla de autorización.
+ *
+ * Las otras dos son de pegado, no de formato, y las dos se han visto de verdad:
+ * - `ANTHROPIC_API_KEY=sk-…`, la línea entera del `.env` copiada de un tirón;
+ * - `"sk-…"`, con las comillas de la línea de la que salió.
+ *
+ * Ninguna de las dos se «arregla» por nuestra cuenta quitando lo que sobra: no se puede
+ * saber si el usuario quería eso, y una clave adivinada que resulta ser válida enseña a
+ * pegar mal. Se rechaza diciendo qué pasa, que es lo que se puede afirmar.
+ *
+ * Lo que NO comprueba es que la clave sirva — eso solo lo sabe el proveedor, y el sitio
+ * donde se pregunta es el catálogo (`cli/wizardInicial.ts`, que lista antes de escribir).
+ * Ésta es la criba de balde: la que evita gastar una llamada para que te digan lo que el
+ * propio campo ya decía.
+ */
+export declare function motivoDeClaveInaceptable(clave: string): string | undefined;
+export declare const CLAVES_DENEGADAS: readonly string[];
+/**
+ * Valida un `config.json` sin tocar disco. Lo que no entiende lo descarta y lo avisa
+ * nombrándolo: un campo mal escrito tiene que producir un mensaje que lo diga, si no el
+ * usuario cree haber configurado algo y no.
+ */
+export declare function validar(bruto: unknown, ruta: string, procedencia: Procedencia): {
+    config: ConfigDeFichero;
+    avisos: Aviso[];
+};
+/**
+ * Valida un `auth.json`. Las credenciales SOLO viven en la ruta global: en un proyecto
+ * se rechaza el fichero entero — no es una regla de formato, es de dónde puede vivir
+ * un secreto. El modo se comprueba al leerlo porque crearlo bien no basta.
+ */
+export declare function validarAuth(bruto: unknown, ruta: string, modo: number, procedencia: Procedencia): {
+    auth: Auth;
+    avisos: Aviso[];
+};

package/dist/core/contextos.d.ts

@@ -0,0 +1,54 @@
+/**
+ * El tope de la ventana de contexto de cada modelo, con toda la honestidad de
+ * la que es capaz una tabla.
+ *
+ * **Lo que NO hay aquí es tan deliberado como lo que hay:**
+ *
+ * - `ollama` no aparece a propósito. Cada modelo local trae el suyo (y a veces
+ *   lo recorta el `num_ctx` del Modelfile), así que cualquier tope sería
+ *   inventado — y un porcentaje calculado sobre un tope inventado no es un
+ *   indicador: es una mentira con forma de cifra.
+ * - Las familias de la tabla se emparejan por PREFIJO (`gpt-4o-mini` calza con
+ *   `gpt-4o`), porque los ids son `familia-variante-fecha`.
+ *
+ * Para lo que la tabla no sabe, está el override de `config.json`
+ * («contextos»: {«proveedor/modelo»: tope}): el usuario sabe más de SU modelo
+ * que esta tabla, y se lo cree.
+ */
+import type { Proveedor } from "./modelos.js";
+/**
+ * El tope de contexto de un modelo, o `undefined` si no se sabe.
+ *
+ * El override se mira ANTES que la tabla y va por id completo
+ * («proveedor/modelo»): un tope fijado a mano describe a ESE modelo, no a la
+ * familia.
+ */
+export declare function topeDeContexto(proveedor: Proveedor, modelo: string, overrides?: Record<string, number>): number | undefined;
+/**
+ * El tope con su ORIGEN, para `/config`: lo que el usuario fijó a mano (proyecto gana
+ * a global, igual que con los modelos), la tabla como último recurso — o nada, que es
+ * una respuesta válida y se distingue del cero.
+ */
+export declare function topeResuelto(proveedor: Proveedor, modelo: string, configs: {
+    proyecto?: Record<string, number>;
+    global?: Record<string, number>;
+}): {
+    tope: number;
+    origen: "proyecto" | "global" | "tabla";
+} | undefined;
+/**
+ * Cuándo se COMPACTA el contexto del raíz en TrueForge, según la ventana del modelo.
+ *
+ * Era un 32.000 fijo heredado de deepagents, puesto por Ollama —sin tope que leer y con la
+ * compresión llegando tarde—. Con DeepSeek, que tiene un millón de ventana, eso es compactar al
+ * 3 %: medido en soporte, cada dos o tres lecturas de fichero, y la compactación de TrueForge
+ * SUSTITUYE el contexto entero, así que el agente releía lo que acababa de leer (13
+ * compactaciones en un turno de 30 min). Ahora: un cuarto de la ventana conocida, nunca menos
+ * del 32.000 de antes (que se queda para lo que no tiene tope, Ollama) y nunca más de 128.000,
+ * porque compactar también limita lo que cuesta cada llamada.
+ */
+export declare const UMBRAL_DE_COMPACTACION_MINIMO = 32000;
+export declare const UMBRAL_DE_COMPACTACION_MAXIMO = 128000;
+export declare const FRACCION_DE_LA_VENTANA_PARA_COMPACTAR = 0.25;
+export declare function umbralDeCompactacion(tope: number | undefined): number;
+export declare function topeDeSalida(proveedor: Proveedor, modelo: string): number | undefined;

package/dist/core/convertirAP.d.ts

@@ -0,0 +1,56 @@
+/**
+ * De las medidas de una MAQUETA (px CSS) a la `p` de XOne, con la cuenta de la skill
+ * (`references/css/de-una-maqueta-a-xone.md`, «medido»): `p = px × resolution-width / ancho_de_la_maqueta`.
+ *
+ * ## Por qué una cuenta en código y no una regla en el prompt
+ *
+ * Medido en una tarea de Maset (rediseño desde una maqueta de Stitch): el agente copió los px de la maqueta TAL CUAL
+ * como `p` —`width="24p"` para un icono de 24 px— y los iconos salieron unas 2,6 veces más pequeños; la regla estaba
+ * en la skill y no la aplicó. Aquí los dos datos que la cuenta necesita NO los pone el modelo: el `resolution-width`
+ * sale del `app.xml` del proyecto y el ancho de la maqueta, de su imagen (o lo dice él, si la imagen no lo deja claro).
+ *
+ * ## Lo que no se adivina
+ *
+ * - Un `app.xml` sin `resolution-width`, o con `-1` (visto en un proyecto real, sin documentar en la skill), no se
+ *   convierte: se dice.
+ * - Una imagen de maqueta puede venir a 1× (Stitch: 390 o 427 de ancho) o a 2×/3× (780): solo un ancho de pantalla
+ *   de móvil en px CSS (`ANCHO_DE_MAQUETA_MINIMO`…`ANCHO_DE_MAQUETA_MAXIMO`) se toma por bueno; otro se dice con sus
+ *   divisiones y se pide.
+ */
+export declare const NOMBRE_CONVERTIR_A_P = "convertir_a_p";
+/** El ancho de una pantalla de móvil en px CSS: fuera de aquí, la imagen va a otra escala (o no es de un móvil). */
+export declare const ANCHO_DE_MAQUETA_MINIMO = 320;
+export declare const ANCHO_DE_MAQUETA_MAXIMO = 480;
+/** Cuántas medidas por llamada: una pantalla entera cabe de sobra. */
+export declare const TOPE_DE_MEDIDAS = 60;
+export interface Resolucion {
+    ancho: number;
+    /** Ausente si el `app.xml` no lo declara (o es -1): la cuenta del ancho no lo necesita. */
+    alto?: number;
+}
+/** El `resolution-width`/`resolution-height` del nodo `<app>` de un `app.xml`, o por qué no se puede usar. */
+export declare function resolucionDeAppXml(texto: string): Resolucion | {
+    motivo: string;
+};
+/** ¿Vale el ancho de esta imagen como ancho de la maqueta en px CSS? Si no, por qué, con sus divisiones a 2× y 3×. */
+export declare function anchoDeMaquetaDeImagen(ancho: number, donde: string): {
+    ancho: number;
+} | {
+    motivo: string;
+};
+/** La cuenta. Redondeada a la `p` entera: XOne no usa decimales en una medida. */
+export declare function pDeMaqueta(px: number, resolucionAncho: number, anchoMaqueta: number): number;
+export interface MedidaDeMaqueta {
+    nombre: string;
+    px: number;
+}
+/** Qué no vale de una lista de medidas, o `undefined`. */
+export declare function motivoDeMedidasInaceptables(medidas: readonly MedidaDeMaqueta[]): string | undefined;
+/** El informe de la tool: la tabla, la cuenta con sus dos datos y de dónde salió cada uno, y lo que NO convierte. */
+export declare function informeDeConversion(opciones: {
+    medidas: readonly MedidaDeMaqueta[];
+    resolucion: Resolucion;
+    anchoMaqueta: number;
+    /** De dónde salió el ancho de la maqueta: «lo indicaste tú» o la ruta de la imagen. */
+    origenDelAncho: string;
+}): string;

package/dist/core/copiaDeAvd.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Las reglas PURAS de «Nuevo emulador a partir de uno existente»: qué se lee de un AVD base y qué
+ * se copia al nuevo. El disco y `avdmanager` viven en `agent/dispositivos/instalacionEnMaquina.ts`.
+ *
+ * Dos modos, y la diferencia es cuánto de la base viaja:
+ *  - CONFIGURACIÓN: `avdmanager` crea un AVD vacío con la imagen y el perfil de la base, y se le
+ *    pone encima el `config.ini` de la base (RAM, disco…). Vale con la base encendida.
+ *  - CLON: se copia la carpeta entera (lo instalado), salvo lo que `seCopiaEnClon` excluye. La base
+ *    tiene que estar apagada: sus discos están bloqueados mientras corre.
+ */
+/** Las líneas `clave=valor` de un `.ini` de AVD. Sin `=` o en blanco se ignoran; el valor va tal cual. */
+export declare function leerIni(texto: string): Map<string, string>;
+/**
+ * El paquete de imagen para `avdmanager -k`, de `image.sysdir.1`:
+ * `system-images/android-35/google_apis/arm64-v8a/` → `system-images;android-35;google_apis;arm64-v8a`.
+ * Sin esa forma no se adivina nada: `undefined`.
+ */
+export declare function paqueteDeImagen(config: ReadonlyMap<string, string>): string | undefined;
+/** El perfil de teléfono (`-d`) de la base: `hw.device.name`, si tiene forma de un nombre de perfil. */
+export declare function perfilDeTelefono(config: ReadonlyMap<string, string>): string | undefined;
+/**
+ * El `<nombre>.ini` del clon: el de la base con `path` y `path.rel` apuntando a la carpeta nueva.
+ * Lo demás (`target`, codificación…) se conserva. Si la base no traía alguna de las dos claves se
+ * AÑADE: un `.ini` sin `path` no lo encuentra nadie.
+ */
+export declare function iniDeClon(iniBase: string, nombre: string, carpetaAvd: string): string;
+/**
+ * ¿Entra en el clon esta ruta, relativa a la carpeta del AVD (separada por `/` o `\`)? Lista NEGRA:
+ * los `.lock` en cualquier nivel (el original los tiene cogidos) y los ficheros de la última
+ * ejecución. `snapshots/` SÍ viaja (medido): al parar, el emulador guarda la memoria en la
+ * instantánea, y lo que aún no se volcó al disco solo vive ahí; sin ella, el clon ve un disco a
+ * medias (un fichero escrito salía con 0 bytes). Hay que reescribirles la identidad
+ * (`hardwareIniDeClon`) o el emulador las rechaza.
+ */
+export declare function seCopiaEnClon(relativa: string): boolean;
+/**
+ * El `hardware.ini` de una instantánea del clon, con la identidad del original cambiada por la del
+ * clon (medido: con solo las rutas el emulador rechaza la instantánea —«cannot load snapshot»—; con
+ * las dos cosas la carga). Formato `clave = valor`, con espacios. Solo se tocan:
+ *  - `avd.name` y `avd.id`, si valen exactamente la base;
+ *  - en cualquier otro valor, los segmentos de ruta `<base>.avd` EXACTOS (entre `/` o `\`, o al
+ *    final), nunca el nombre suelto: la base podría aparecer dentro de otra palabra.
+ */
+export declare function hardwareIniDeClon(texto: string, base: string, nombre: string): string;

package/dist/core/cssBienFormado.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ¿Está bien formada esta hoja de estilos de XOne? Pura y sin llamar a nadie.
+ *
+ * Existe por el otro turno de soporte de APPSalud: el framework no arrancaba con un
+ * `CssParseException … Expected open brace character` y el agente pasó media hora contando
+ * comentarios a mano.
+ *
+ * **Es PRUDENTE a propósito**: solo marca lo que rompe la ESTRUCTURA de una hoja con la gramática que
+ * documenta la skill (`xone-development/references/css/buenas-practicas-y-parser.md` §18), y nada de
+ * lo que XOne pueda aceptar: un validador que avisa de algo que funciona manda a reescribir código
+ * bueno. Lo que comprueba:
+ * - comentarios `/* … *\/` cerrados, y los de línea `// …` (XOne acepta los dos);
+ * - llaves que abren y cierran, sin `}` de más ni bloques sin cerrar al acabar;
+ * - que lo que hay fuera de un bloque acaba en `{` (un selector) o es una at-rule (`@import …;`);
+ * - que cada declaración de un bloque tiene su `:`.
+ *
+ * NO comprueba propiedades, valores ni selectores: un atributo que XOne no conoce se ignora en
+ * silencio, y eso es de `xone_atributos`, no de la forma.
+ */
+import type { ResultadoXml } from "./xmlBienFormado.js";
+export type ResultadoCss = ResultadoXml;
+export declare function comprobarCss(entrada: string): ResultadoCss;

package/dist/core/deps.d.ts

@@ -0,0 +1,28 @@
+import { type McpPort, type ModelosPort, type SkillsPort, type VerifierPort } from "./ports.js";
+/**
+ * Todo lo caro, junto y pasado por argumento.
+ *
+ * La regla dura: esto se PASA al construir, nunca se importa dentro de quien lo usa. Es lo
+ * que hace que el lazo entero se recorra sin API, sin red y sin el simulador.
+ */
+export interface Deps {
+    modelos: ModelosPort;
+    skills: SkillsPort;
+    verifier: VerifierPort;
+    /** Declarado y sin cablear en la v1: el proyecto está en el cwd, no en CloudStudio. */
+    mcp: McpPort;
+}
+/** Todo dobles. La suite corre con esto, y `describe` lo canta entero. */
+export declare function depsOffline(): Deps;
+/**
+ * Qué hay montado, y qué de ello es de pega.
+ *
+ * Pura y sin efectos: no llama a ningún puerto, solo mira qué son. Por eso `xonecode
+ * describe` no necesita ni credenciales ni red.
+ *
+ * El verificador va PRIMERO y como `grave` por un motivo: un verificador de pega dice que
+ * todo está bien, así que es el doble que más daño hace pasando desapercibido.
+ */
+export declare function describir(deps: Deps): string[];
+/** Para el aviso del final del turno: los nombres de los puertos caros que son dobles. */
+export declare function doblesGraves(deps: Deps): string[];