xonecode 0.38.44 → 0.39.4

package/dist/core/modoDeEscritura.d.ts

@@ -0,0 +1,155 @@
+/**
+ * # El modo de escritura de una sesión
+ *
+ * Dos modos y nada más: **supervisado**, donde cada escritura para con su diff delante, y
+ * **autónomo**, donde el agente escribe los ficheros del proyecto sin preguntar.
+ *
+ * **Vive en la SESIÓN, no en el disco.** Antes esto era `settings.sinAprobacion`, un ajuste
+ * por RUTA en `settings.json` que se ponía una vez y se quedaba puesto para siempre, en
+ * todas las sesiones y todos los procesos. Se retiró entero: un mando que está dentro de la
+ * caja del chat se lee como «esta conversación», y una bandera global encendida sobre la app
+ * de un cliente que nadie recuerda haber dejado encendida es el peor final posible. Es la
+ * misma decisión que el esfuerzo de razonamiento (`core/esfuerzo.ts`), que también se elige
+ * por sesión, se anota en el índice y vuelve al reabrirla.
+ *
+ * **Con qué modo NACE una sesión sí tiene un valor por defecto (IXCODE-31)**, global y por
+ * proyecto (`modoParaSesionNueva`), y no es volver a `sinAprobacion`: aquello era un ajuste
+ * que GOBERNABA cada escritura de todas las sesiones; esto solo decide la posición inicial
+ * del conmutador de una sesión NUEVA de una persona, que lo ve en la caja del chat desde el
+ * primer momento y lo cambia ahí. Una sesión reabierta conserva el suyo y una tarea de fondo
+ * no lo usa.
+ *
+ * **Lo que el modo gobierna son las escrituras LOCALES, y solo eso.** No toca la subida:
+ * `/sync subir` conserva su plan delante y su aprobación fail-closed por TIPO en los dos
+ * modos, porque subir es llevar el trabajo a la app de otras personas y eso no es lo que
+ * esta palanca decide. Y no toca las guardas de RUTA: `/.env`, `/.git`, `/.xonecode`, las
+ * vistas aplanadas y un artefacto fuera de sitio se siguen denegando igual en autónomo. El
+ * modo quita la PREGUNTA, nunca la BARRERA.
+ *
+ * **Y por eso se levantó la condición de CloudStudio**, que era la que prohibía todo esto en
+ * un proyecto conectado. El argumento medido: escribir no sube; el commit por turno es git,
+ * o sea recuperable; y la subida sigue teniendo su propia aprobación. La incoherencia que lo
+ * hizo insostenible: sobre ese MISMO proyecto conectado, una tarea de fondo ya escribía sin
+ * preguntar y la consola no podía.
+ */
+/** Supervisado: cada escritura con su diff. Autónomo: se aplican solas. */
+export type ModoDeEscritura = "supervisado" | "autonomo";
+/**
+ * Una sesión que no ha dicho nada PREGUNTA.
+ *
+ * Ausente no es «no consta» aquí, y esa es la diferencia con el esfuerzo o el dispositivo:
+ * de esto hay que decidir algo en cada escritura, así que el hueco tiene que resolverse, y
+ * la única dirección segura para resolverlo es la que enseña el diff.
+ */
+export declare const MODO_POR_OMISION: ModoDeEscritura;
+/** De dónde salió el modo de una sesión nueva: lo dice el código, para poder decirlo. */
+export type OrigenDelModo = "proyecto" | "global" | "omision";
+/**
+ * El modo con que NACE una sesión de una persona (IXCODE-31): el del PROYECTO si está puesto
+ * (`.xonecode/config.json#modoDeEscritura`), si no el GLOBAL (`settings.json#modoDeEscritura`,
+ * Ajustes > General), y si no ninguno, la omisión de siempre. Ausente en cada nivel es «no lo
+ * he dicho», y entonces decide el siguiente.
+ */
+export declare function modoParaSesionNueva(valores: {
+    proyecto?: ModoDeEscritura;
+    global?: ModoDeEscritura;
+}): {
+    modo: ModoDeEscritura;
+    origen: OrigenDelModo;
+};
+/**
+ * Cuántas rondas de aprobación admite un turno de la CONSOLA, en los dos modos.
+ *
+ * El `MAX_APPROVAL_ROUNDS` de `vendor/hitl.ts` son cinco y se dimensionaron para un modelo
+ * que insiste tras cada rechazo — «te lo he preguntado cinco veces, para». Medido después,
+ * eso no es lo que corta: lo que corta son trabajos legítimos a la mitad, porque una ronda
+ * no es una insistencia, es una TANDA de escrituras. Ya lo pagaron las tareas de fondo
+ * —`core/tareas.ts#TOPE_DE_RONDAS_DE_TAREA`, con un turno que acabó con cuatro ficheros
+ * escritos, una escritura abandonada y el verificador sin correr— y lo paga igual una
+ * sesión en modo autónomo, que es la misma forma de trabajar con alguien delante.
+ *
+ * **Es el MISMO 20 que la tarea, y sale de la misma medida**, no de una segunda
+ * observación: lo único medido es el turno que se cortó necesitando cinco tandas, y veinte
+ * deja sitio a un encargo bastante mayor. Sigue siendo un número provisional, y lo que lo
+ * hace aceptable es su MODO DE FALLO: al agotarse se DICE, quedan escrituras sin aplicar y
+ * el turno sale con `cortadoPorTope`. Un tope corto que para con un motivo verdadero se
+ * afina luego; lo que no se puede es que al agotarse mienta.
+ *
+ * **Vive aparte del de la tarea aunque hoy valgan lo mismo**: son dos situaciones y no una
+ * —aquí hay alguien que puede rechazar o pulsar parar, allí no hay nadie mirando—, así que
+ * fundirlos ataría dos decisiones que se van a afinar por separado.
+ *
+ * **Subido a 50 junto con el de la tarea**, a petición de la persona: el ciclo de ajustar una pantalla contra su maqueta
+ * gastaba las 20 en un turno (medido en una tarea; el chat en autónomo trabaja igual). Siguen separados.
+ */
+export declare const TOPE_DE_RONDAS_DE_CONSOLA = 50;
+/**
+ * El tope de rondas de `xonecode run --real` que se puede subir por ENTORNO, para medir.
+ *
+ * `run` no tiene a nadie delante, así que su tope es el corto (`MAX_APPROVAL_ROUNDS`, cinco). Medido
+ * sobre una calculadora hecha por los agentes, **las cinco pasadas se cortaron con él**, y siempre en
+ * el mismo punto: justo antes de la última vuelta del bucle de calidad, la que compara la captura
+ * final con la maqueta. El tope era un artefacto de medir con `run`, no del agente: en la consola
+ * son veinte. Con esto una prueba puede pedir el de la consola sin tocar el código.
+ *
+ * **Solo lo lee `run`**, nunca la consola ni las tareas, que ya tienen el suyo. Un valor que no sea un
+ * entero entre 1 y `TOPE_MAXIMO_DE_RONDAS_DE_ENTORNO` no se aplica y `run` lo DICE: el tope existe para
+ * cortar un bucle que nadie puede parar, y un `999999` por un descuido lo dejaría sin freno.
+ */
+export declare const VARIABLE_DEL_TOPE_DE_RONDAS = "XONECODE_TOPE_DE_RONDAS";
+export declare const TOPE_MAXIMO_DE_RONDAS_DE_ENTORNO = 50;
+export declare function topeDeRondasDeEntorno(valor: string | undefined): number | undefined;
+/** ¿Es uno de los dos nombres EXACTOS del modo? Nada de tildes ni sinónimos: eso es `modoDeTexto`. */
+export declare function esModoDeEscritura(candidato: unknown): candidato is ModoDeEscritura;
+/**
+ * Lo que alguien TECLEA, traducido a un modo.
+ *
+ * Acepta las dos parejas de palabras: la nueva —la que se lee en la pastilla y viaja por el
+ * cable— y la vieja de `/aprobacion [humana|automatica]`, que lleva meses en la ayuda y en
+ * los dedos de quien la usa. Un comando que deja de entender lo que siempre entendió es una
+ * regresión aunque el concepto sea el mismo.
+ *
+ * Las tildes se aceptan al ENTRAR y nunca se guardan: el valor que viaja y se persiste es
+ * siempre `autonomo` a secas, que es el que compara `esModoDeEscritura`.
+ *
+ * **Lo que no reconoce es `undefined`, jamás un modo por omisión**: quien llame decide qué
+ * hacer con un «no lo entiendo», y aquí adivinar sería adivinar en la dirección peligrosa la
+ * mitad de las veces.
+ */
+export declare function modoDeTexto(texto: string): ModoDeEscritura | undefined;
+/**
+ * ¿Las escrituras de esta sesión se aplican SIN preguntar, ahora mismo?
+ *
+ * Las dos condiciones son AND y ninguna sobra:
+ *
+ * - **El modo de la sesión es autónomo.** Lo eligió quien está en esta conversación.
+ * - **Hay alguien delante.** Auto-aprobar significa «el humano que está aquí ha decidido no
+ *   pulsar», no «no hace falta humano». Es la única condición que sobrevivió al rediseño, y
+ *   no es celo: `consolaWeb` declara `interactivo` a fuego, así que quien llama pasa la
+ *   misma cuenta que `pedirDecisiones` (`interactivo && !eof()`). Con ella, una pestaña que
+ *   se cierra a mitad de turno devuelve la escritura al camino de aprobación, donde el eof
+ *   la rechaza — y `xonecode run` en CI y las tuberías siguen sin aplicar nada, que es lo
+ *   que hacen hoy y lo que el código de salida 2 del contrato significa.
+ *
+ * Se pregunta en CADA RONDA, nunca se captura al abrir: el modo se cambia con la sesión en
+ * marcha, y un booleano capturado dejaría el cambio sin efecto hasta reabrir — la mitad de
+ * las veces en la dirección peligrosa.
+ */
+export declare function seEscribeSinPreguntar(opciones: {
+    modo: ModoDeEscritura | undefined;
+    interactivo: boolean;
+}): boolean;
+/**
+ * Cuántas preguntas de UN turno se contestan solas en modo autónomo. Un modelo que encadena
+ * preguntas no puede dejar el turno dando vueltas: pasado el tope, la siguiente le llega a la persona.
+ */
+export declare const TOPE_DE_PREGUNTAS_CONTESTADAS_SOLAS = 8;
+/**
+ * La opción que el agente MARCÓ como recomendada, o `undefined`. Solo cuenta lo que el modelo
+ * escribió: sin marca no se elige por él, y la pregunta llega a la persona.
+ *
+ * **El modo autónomo quitaba la pregunta de las ESCRITURAS y no la del agente**, y una sesión
+ * autónoma se paraba igual a pedir «alcance» y «tipografías», cada una con su recomendada.
+ * Contestarla sola es decidir por la persona, así que se DICE en el chat, con la opción elegida.
+ */
+export declare function opcionRecomendada(opciones: readonly string[]): string | undefined;

package/dist/core/motor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Qué motor de agente corre una sesión: `deepagents` (el de siempre) o `trueforge` (el segundo,
+ * `docs/VARIANTE-TRUEFORGE-HARNESS.md`).
+ *
+ * **deepagents es LEGACY** (decisión suya, 30-09-2026): sigue corriendo las sesiones que nacieron con
+ * él y a un `"motor": "deepagents"` de distancia, pero lo nuevo va solo a TrueForge y ahí no se toca
+ * nada. Primer caso: `describe_image` (IXCODE-23) no existe en deepagents, aunque el aviso de adjuntos,
+ * que es común, la nombra.
+ *
+ * **Se elige por CONFIGURACIÓN y no se enseña**: decisión suya —«la conexión que sea por
+ * configuración no visible para el usuario»—. La interfaz es la misma con los dos: el motor solo
+ * cambia quién produce los eventos de dominio que las pieles pintan.
+ *
+ * **Y una sesión conserva el motor con el que nació**: la memoria de una conversación de
+ * deepagents (su checkpoint) no la puede continuar TrueForge ni al revés, así que cambiar la
+ * configuración con sesiones abiertas no puede cambiarles el motor por debajo — las nuevas
+ * toman el de la configuración, y las viejas siguen con el suyo.
+ *
+ * Puro: ni disco ni entorno; quien llama pasa las fuentes.
+ */
+export declare const MOTORES: readonly ["deepagents", "trueforge"];
+export type MotorDeAgente = (typeof MOTORES)[number];
+/**
+ * El de omisión, el que corre sin configurar nada: **TrueForge**, decisión suya (24-09-2026) tras el
+ * banco entre motores, que los dio equivalentes en coste dentro del ruido y a TrueForge sin peor
+ * calidad (`docs/VARIANTE-TRUEFORGE-HARNESS.md`, «El banco entre motores»). deepagents sigue a un
+ * `"motor": "deepagents"` de distancia, y una sesión que nació con él sigue con él: el vestíbulo la
+ * reabre con el suyo, y a una sin motor guardado —de antes de que hubiera dos— le pone deepagents a
+ * mano, sin pasar por aquí.
+ */
+export declare const MOTOR_POR_OMISION: MotorDeAgente;
+export declare function esMotor(valor: unknown): valor is MotorDeAgente;
+/**
+ * El motor de una sesión. Precedencia, del más concreto al menos: el de la SESIÓN (con el que
+ * nació), la variable `XONECODE_MOTOR`, el `config.json` del proyecto, el global y la omisión. Un
+ * valor que no es un motor se salta, que es lo mismo que no haberlo puesto.
+ */
+export declare function resolverMotor(fuentes: {
+    sesion?: unknown;
+    entorno?: unknown;
+    proyecto?: unknown;
+    global?: unknown;
+}): MotorDeAgente;

package/dist/core/motoresLocales.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Los MOTORES LOCALES —Claude Code, Codex, OpenCode— vistos desde Ajustes: si están, si tienen
+ * sesión iniciada y si contestan. Puro: lo que toca la máquina vive en
+ * `agent/motores/motoresLocales.ts`.
+ *
+ * Existe porque un subagente con `motor: claude-code` corre el producto de la máquina con SU
+ * login, y hasta ahora nada decía si ese login estaba: `disponible()` solo comprobaba que el SDK
+ * se importa, y un motor sin sesión fallaba a mitad de un encargo. La guía que circulaba entre
+ * usuarios —PowerShell como administrador, la REPL, `/login`, «deja la consola abierta»— tenía
+ * dos cosas de más, medidas: el SDK trae su PROPIO binario (no hace falta instalar Claude Code) y
+ * la credencial queda en disco (no hace falta dejar nada abierto).
+ */
+import type { MotorExterno } from "./ports.js";
+/** Los tres, en el orden de las pestañas: Claude Code primero, que es el que más se usa. */
+export declare const MOTORES_LOCALES: readonly MotorExterno[];
+export declare function esMotorLocal(valor: unknown): valor is MotorExterno;
+/**
+ * Por qué ENTORNO se prueba. Un subagente de Claude Code SIN `ejecucion` no recibe `env` y hereda
+ * el del proceso —donde `guardarCredencial` deja a propósito la `ANTHROPIC_API_KEY` de
+ * xonecode—, y uno CON `ejecucion` recibe el de nuestra shell, sin claves. Medido: con la clave
+ * en el entorno, `auth status` contesta `apiKeySource: "ANTHROPIC_API_KEY"` y factura a la clave
+ * aunque haya login. Así que con clave son DOS caminos, y se prueban los dos; sin ella, uno.
+ */
+export type CaminoDePrueba = "unico" | "sin-ejecucion" | "con-ejecucion";
+export interface PruebaDeMotorLocal {
+    camino: CaminoDePrueba;
+    ok: boolean;
+    /** La respuesta recortada, o el motivo del fallo en una línea. Sin rutas ni URL. */
+    detalle: string;
+    ms: number;
+    medido: string;
+}
+export interface LoginDeMotorLocal {
+    fase: "esperando" | "hecho" | "fallo" | "cancelado";
+    /** El binario dijo «Paste code here if prompted»: se puede pegar el código de la web. */
+    pideCodigo?: true;
+    detalle?: string;
+    desde: string;
+}
+/**
+ * La foto de un motor. Cada campo ausente es «no consta», nunca «no»: un `conSesion` que falta
+ * es que no se supo preguntar (OpenCode no tiene una salida de estado que se pueda leer sin
+ * adivinar), y entonces la tarjeta no afirma nada y lo dice la prueba.
+ */
+export interface EstadoDeMotorLocal {
+    motor: MotorExterno;
+    instalado: "ok" | "no-encontrado" | "fallo";
+    version?: string;
+    /** Por qué no está o por qué falló, en una línea. */
+    detalle?: string;
+    conSesion?: boolean;
+    /** La sesión en palabras: «Cuenta de Claude · Team · XOne». El CORREO no cruza nunca. */
+    sesion?: string;
+    /** Claude Code: sin ejecución, el SDK usaría la clave de API de xonecode y no el login. */
+    conClave?: true;
+    pruebas?: PruebaDeMotorLocal[];
+    probando?: true;
+    login?: LoginDeMotorLocal;
+    /** Esta ejecución puede iniciar sesión desde el botón (hoy, solo Claude Code). */
+    admiteLogin?: true;
+    /** Y abrir una consola del sistema con el comando ya escrito, como respaldo. */
+    admiteConsola?: true;
+    /**
+     * Este motor necesita un modelo elegido aquí (hoy, solo OpenCode): sin uno, con nuestra
+     * configuración cerrada elige solo un modelo de su tier gratuito, que no contesta fuera de su
+     * propia consola (medido). Lo usan la prueba y todo subagente sin `modelo:` en su `.md`.
+     */
+    admiteModelo?: true;
+    /** El elegido, `proveedor/modelo`. Ausente es que no hay ninguno. */
+    modelo?: string;
+    medido: string;
+}
+/** Los motores a los que se les elige el modelo en Ajustes. */
+export declare const MOTORES_CON_MODELO: readonly MotorExterno[];
+/**
+ * Un modelo de OpenCode tal como lo lista `opencode models`: `proveedor/modelo`. Es la regla del
+ * SERVIDOR al guardarlo y al leerlo de `settings.json`; lo que no la cumpla no se escribe en la
+ * configuración del hijo, donde un valor raro sería un error de arranque y no un «no vale».
+ */
+export declare function motivoDeModeloDeMotorInaceptable(modelo: string): string | undefined;
+/** Lo que interesa de `claude auth status --json`. */
+export interface SesionDeClaude {
+    iniciada: boolean;
+    /** La clave de una variable de entorno manda sobre el login (medido). */
+    porClave: boolean;
+    metodo?: string;
+    organizacion?: string;
+    plan?: string;
+}
+/**
+ * Lee la salida de `claude auth status --json`. Solo se queda con método, organización, plan y
+ * de dónde sale la clave: **el correo y el id de organización no salen de aquí**, la misma regla
+ * que `nombreDelAsignado` aplica al asignado de Jira. Lo que no es un JSON con `loggedIn`
+ * booleano no es una respuesta, y se devuelve `undefined` en vez de adivinar.
+ */
+export declare function interpretarAuthStatusDeClaude(salida: string): SesionDeClaude | undefined;
+/** La sesión de Claude en una línea, para la tarjeta. */
+export declare function lineaDeSesionDeClaude(s: SesionDeClaude): string;
+/** De `claude --version` («2.1.263 (Claude Code)») o `codex-cli 0.1.0`, el número. */
+export declare function versionDeSalida(salida: string): string | undefined;
+/** Una URL no cruza el cable: la de autorización lleva el `state` y el reto de PKCE. */
+export declare function sinUrls(texto: string): string;
+export declare function urlDeAutorizacion(salida: string): string | undefined;
+/** El binario de Claude pide el código cuando el navegador no pudo volver solo (medido sin TTY). */
+export declare function pideCodigo(salida: string): boolean;
+/** La última línea con algo, sin URL y acotada: es lo que se cuenta de un login que falló. */
+export declare function ultimaLinea(salida: string): string | undefined;
+export declare function recortar(texto: string, tope?: number): string;
+/** Lo que se le pide al motor para probarlo. Corto a propósito: se paga en cada prueba. */
+export declare const TAREA_DE_PRUEBA = "Responde exactamente con la palabra OK y nada m\u00E1s.";
+export declare const INSTRUCCIONES_DE_PRUEBA = "Esto es una prueba de conexi\u00F3n de XOneCode. No uses ninguna herramienta: contesta solo con lo que se te pide.";
+/** Contestó y dijo lo que se le pidió. Que conteste otra cosa también es un fallo que contar. */
+export declare function respuestaDePruebaValida(texto: string): boolean;

package/dist/core/mudanzaDeWorkspace.d.ts

@@ -0,0 +1,112 @@
+/**
+ * El literal que vivía en MEDIO del reparto: `<base>/<entorno>/workspace/<proyecto>`.
+ *
+ * Vive aquí y no en `settings.ts` a propósito: `rutaDeWorkspace` ya no lo compone, y
+ * dejarlo allí sería una constante de producción que solo usa la mudanza. Cuando no quede
+ * nadie con el reparto viejo en disco, este fichero entero se va de una pieza.
+ */
+export declare const CARPETA_DEL_REPARTO_VIEJO = "workspace";
+/** Una copia local que está en el reparto viejo, y adónde va en el de ahora. */
+export interface Mudanza {
+    entorno: string;
+    proyecto: string;
+    desde: string;
+    hacia: string;
+}
+/**
+ * Lo que la parte pura necesita saber del disco, y nada más.
+ *
+ * `listar` devuelve las CARPETAS que cuelgan de una ruta —no los ficheros—: quien la
+ * implementa filtra por tipo de entrada, porque un `.DS_Store` es un nombre de segmento
+ * perfectamente válido y aquí no habría forma de distinguirlo de un proyecto.
+ */
+export interface FotoDelLegado {
+    existe: (ruta: string) => boolean;
+    listar: (ruta: string) => readonly string[];
+}
+/**
+ * Qué copias locales siguen en el reparto viejo y adónde van.
+ *
+ * **Por PROYECTO y no por entorno.** Mover la carpeta `<entorno>/workspace` entera parece
+ * más barato, pero no vale en el caso de quien ya tenía `settings.workspace` configurado:
+ * ahí el destino (`<workspace>/<entorno>`) es el PADRE del origen, y la mudanza de una
+ * pieza sería mover una carpeta encima de sí misma. Proyecto a proyecto funciona en los
+ * dos casos con un solo camino.
+ *
+ * **Un destino que ya existe NUNCA se pisa**, y se cuenta aparte en `chocadas` en vez de
+ * callarse: en esa carpeta hay una historia de git, unas sesiones y un checkpoint, y dos
+ * copias del mismo proyecto sin que nadie lo diga son peor que una mudanza que no se hizo.
+ *
+ * Nada de esto toca el disco: quien llama decide, mueve y lo cuenta.
+ */
+export declare function mudanzasPendientes(opciones: {
+    /** La base con el reparto VIEJO: `settings.workspace` si estaba puesto, o `~/.xonecode`. */
+    legado: string;
+    /** El workspace de ahora: `settings.workspace` si está puesto, o `~/.xonecode/workspace`. */
+    workspace: string;
+    entornos: readonly string[];
+} & FotoDelLegado): {
+    mudanzas: Mudanza[];
+    chocadas: Mudanza[];
+};
+/**
+ * Una ruta absoluta ya grabada en disco, traducida al reparto de ahora — o AUSENTE si esta
+ * mudanza no la toca.
+ *
+ * Existe por el almacén que tiene raíces absolutas escritas: `proyecto.raiz` del índice de
+ * tareas (`~/.xonecode/tareas/indice.json`). Sin reescribirlas, una tarea pendiente abriría
+ * una carpeta que ya no está.
+ *
+ * Fueron DOS: las claves de `settings.sinAprobacion` también eran rutas, y perderlas dejaba
+ * sin aplicar una autorización que el usuario dio por puesta. Ese ajuste se retiró cuando el
+ * modo de escritura pasó a vivir en la SESIÓN (`core/modoDeEscritura.ts`) y con él se fue su
+ * mudanza; esta función sigue siendo general porque el problema no era suyo.
+ *
+ * Se compara por SEGMENTOS y no por prefijo de texto, la misma trampa que `dentroDelWorkspace`:
+ * `…/AppDemoViejo` empieza por `…/AppDemo` y no tiene nada que ver. Y ausente significa «esto
+ * no lo mudé yo», que es distinto de «no cambia»: quien llama necesita saber si tocó la
+ * entrada para decidir si reescribe el fichero.
+ */
+export declare function rutaMudada(ruta: string, mudanzas: readonly Mudanza[]): string | undefined;
+/**
+ * Una ruta traducida a través de VARIAS mudanzas, en el orden en que ocurrieron: cada tanda
+ * es el plan de un cambio de base, y la salida de una es la entrada de la siguiente.
+ *
+ * Existe porque `rutaMudada` coge la PRIMERA coincidencia, que dentro de UN plan es correcto
+ * (sus orígenes no se solapan) y entre varios no: con ir de A a B y volver a A, una lista plana
+ * traducía `A/…` a `B/…` —la ida— aunque la vuelta ya había vaciado `B`, y abrir el proyecto
+ * abría una carpeta que no existe. Encadenadas, `A/…` va a `B/…` y vuelve a `A/…`.
+ */
+export declare function rutaTrasLasMudanzas(ruta: string, tandas: readonly (readonly Mudanza[])[]): string;
+/** Lo que el plan de un cambio de base necesita saber del disco. `listar` son CARPETAS. */
+export interface FotoDeLaBase {
+    existe: (ruta: string) => boolean;
+    listar: (ruta: string) => readonly string[];
+}
+/**
+ * Qué copias hay que MUDAR al cambiar el workspace de `desde` a `hacia`, o por qué no se
+ * puede — antes de tocar nada.
+ *
+ * **Se listan las carpetas REALES** `<desde>/<entorno>/<proyecto>`, no los entornos
+ * registrados: quitar un entorno de Ajustes no borra sus copias, y una mudanza que solo mirara
+ * la lista las dejaría huérfanas en la base vieja. Lo OCULTO no es un proyecto —las lápidas
+ * `.<proyecto>.borrando-…` que un borrado a medias deja (`borrarCopiaDeProyecto`) y las
+ * carpetas temporales de una mudanza cortada—, y se queda fuera.
+ *
+ * Tres noes, y todos antes de copiar un byte:
+ * - **una base cuelga de la otra** (o son la misma): copiar una carpeta dentro de sí misma no
+ *   termina, y al revés la base vieja pasaría a parecer un entorno de la nueva;
+ * - **dentro de la casa de xonecode** (`~/.xonecode`), salvo su `workspace` de omisión: ahí
+ *   viven `tareas/`, `agentes/` y `auth.json`, y un entorno llamado igual se mezclaría con
+ *   ellos;
+ * - **un destino que ya existe**: se NIEGA ENTERO, nunca se pisa. En esa carpeta puede haber
+ *   otra historia de git y otro checkpoint, y mudar la mitad dejaría el workspace partido.
+ */
+export declare function planDeCambioDeBase(opciones: {
+    desde: string;
+    hacia: string;
+    casaXonecode: string;
+} & FotoDeLaBase): {
+    mudanzas: Mudanza[];
+    motivo?: string;
+};

package/dist/core/navegacion.d.ts

@@ -0,0 +1,172 @@
+/**
+ * El índice de navegación XOne: qué hay en el proyecto y qué apunta a qué.
+ *
+ * **Este módulo es PURO**, y esa es la mitad del diseño. Quién lee el disco y quién entiende
+ * el XML es `agent/navegacion/` apoyándose en `xone-linter`; aquí solo vive la forma de las
+ * respuestas y cómo se consultan. Así la regla se prueba sin un proyecto delante, y el día
+ * que la fuente del modelo cambie no cambia nada de esto.
+ *
+ * **Por qué existe.** Medido sobre un proyecto real (AppDemo, 41 `.xne`): contestar «¿qué
+ * colecciones tiene el proyecto?» leyendo ficheros cuesta unos 18.000 tokens —son todos los
+ * `.xne`—, y contestarla desde el modelo cuesta 141. La pregunta cara no es leer un fichero
+ * (un `.xne` son un par de kilobytes): es **no saber cuál de los cuarenta y uno leer**. Eso
+ * es lo que esto contesta, y por eso la primera versión va POR NOMBRE y no por posición.
+ *
+ * **Por qué no por posición todavía.** Un editor pregunta «¿qué hay bajo el cursor?»; un
+ * agente no tiene cursor, tiene nombres. Y saber la posición exacta de un atributo exige
+ * conservar su rango al parsear, que hoy `xone-linter` no hace (su `loc()` devuelve solo el
+ * fichero). Lo caro está justo en la mitad que no hace falta para lo que se ha medido.
+ *
+ * **Las rutas que entran aquí son VIRTUALES** (`/Clientes.xne`), nunca de la máquina. Quien
+ * traduce es el adaptador, y no es higiene: esto viaja al modelo y de ahí al cable.
+ */
+/** Qué clase de cosa es un símbolo. Dos, porque son las dos que el modelo nombra. */
+export type ClaseDeSimbolo = "coleccion" | "campo";
+/** Dónde se declara algo. Sin línea: hoy no la hay, y ausente ≠ «línea 1». */
+export interface Declaracion {
+    nombre: string;
+    clase: ClaseDeSimbolo;
+    /** Ruta VIRTUAL. La real no sale nunca de `agent/`. */
+    fichero: string;
+    /** Solo en un campo: la colección que lo declara. */
+    coleccion?: string;
+    /** El tipo declarado de un campo (`T`, `N`, `D`…). Ausente si el `.xne` no lo dice. */
+    tipo?: string;
+}
+/** Quién apunta a quién, y por qué atributo. El atributo importa: no es lo mismo un
+ *  `mapcol` que un `inherits`, y el que pregunta suele querer justo esa diferencia. */
+export interface Referencia {
+    /** Quién referencia: `Citas.CLIENTE`, o `ConsolaReplica` si es la coll entera. */
+    desde: string;
+    /** El atributo que lo hace: `mapcol`, `mapfld`, `linkedfield`, `contents`, `inherits`. */
+    por: string;
+    /** A qué apunta: `Clientes` o `Clientes.NOMBRE`. */
+    hacia: string;
+    /** Ruta VIRTUAL del fichero que contiene la referencia. */
+    fichero: string;
+}
+/**
+ * El modelo mínimo del que sale el índice.
+ *
+ * Es NUESTRO y no el de `xone-linter` a propósito: el suyo trae el proyecto entero —runtime,
+ * estilos, conexiones, imágenes— y atarnos a su forma haría que un cambio suyo se propagara
+ * hasta aquí. El adaptador se queda con lo que estas consultas necesitan y nada más, que es
+ * además la lista de lo que puede viajar.
+ */
+export interface ModeloDeNavegacion {
+    colecciones: readonly ColeccionDeNavegacion[];
+    app: AppDeNavegacion;
+    /**
+     * Las referencias que salen de un SCRIPT y no de un atributo XML.
+     *
+     * Van aparte porque no son de una colección: una puede vivir en un `.js` suelto. Y existen
+     * porque **así es como navega una app XOne de verdad** — medido sobre un proyecto real: los
+     * botones del menú abren colecciones con
+     * `onclick="javascript:appData.getCollection('Deportes')…"`, no con `mapcol`. Sin ellas, «¿quién
+     * usa Deportes?» contestaba «nadie» teniendo dos botones delante.
+     */
+    referenciasDeScript: readonly Referencia[];
+}
+export interface ColeccionDeNavegacion {
+    nombre: string;
+    /** Ruta VIRTUAL. */
+    fichero: string;
+    campos: readonly {
+        nombre: string;
+        tipo?: string;
+    }[];
+    /** Lo que esta colección apunta hacia fuera, ya resuelto por el adaptador. */
+    referencias: readonly Omit<Referencia, "fichero">[];
+    /**
+     * Los eventos declarados, por nombre. Un `onchange` lleva el campo que lo dispara entre
+     * paréntesis, porque sin él no se sabe a qué reacciona — y eso es justo lo que hace falta
+     * antes de tocarlo.
+     */
+    eventos: readonly string[];
+    /** Los nodos personalizados, por nombre. */
+    nodos: readonly string[];
+    /** Las conexiones propias de la colección, por nombre. */
+    conexiones: readonly string[];
+}
+/** Lo que `app.xml` declara del conjunto. Contesta «¿por dónde arranca esto?». */
+export interface AppDeNavegacion {
+    /** Las colecciones de entrada. Vacío = no consta, que no es «no hay». */
+    entrada: readonly string[];
+    /** Las colecciones de login, si el proyecto tiene. */
+    login: readonly string[];
+    /** Las hojas de estilo declaradas, por URL. */
+    estilos: readonly string[];
+    /** Las conexiones declaradas a nivel de aplicación. */
+    conexiones: readonly string[];
+}
+/** Todo lo que se sabe de UNA colección, para la pregunta «háblame de Clientes». */
+export interface DetalleDeColeccion {
+    nombre: string;
+    fichero: string;
+    campos: readonly Declaracion[];
+    eventos: readonly string[];
+    nodos: readonly string[];
+    conexiones: readonly string[];
+    /** Lo que ELLA apunta hacia fuera. Lo que apunta hacia ella es `referencias`. */
+    apuntaA: readonly Referencia[];
+}
+/**
+ * Lo que no cuadra en el proyecto, cruzando referencias con inventario.
+ *
+ * **Esto NO convierte el índice en un validador**, y la diferencia importa: el linter valida
+ * —tiene reglas, severidades y un informe— y esto solo cruza dos listas que ya tiene. Lo que
+ * contesta es la pregunta de orientación «¿hay algo roto por aquí?», que hoy no se puede hacer
+ * sin saber ya el nombre que falta.
+ */
+export interface ProblemasDelProyecto {
+    /** Referencias a una colección que no existe. */
+    rotas: readonly Referencia[];
+}
+/**
+ * **Por qué NO hay «colecciones huérfanas», y está medido.**
+ *
+ * Se implementó y se tiró. Sobre un proyecto real de 42 colecciones daba 33 huérfanas; con las
+ * referencias de script dentro bajaba a 22 — la mitad del proyecto. Una lista donde el 50 % son
+ * falsos positivos no es un hallazgo, es ruido con autoridad: quien la lea o la ignora o borra
+ * código vivo. El motivo es que en XOne se llega a una colección por caminos que este índice no
+ * modela (menús, `ExecuteNode`, nombres compuestos en tiempo de ejecución), y un aviso al pie no
+ * arregla una señal equivocada. Vuelve el día que se pueda acotar el falso positivo, no antes.
+ */
+/** Lo que el índice sabe contestar. Cuatro preguntas, que son las que se han medido. */
+export interface IndiceDeNavegacion {
+    /** Todas las colecciones, por nombre. La pregunta de los 18.000 tokens. */
+    inventario(): readonly Declaracion[];
+    /** Dónde se declara algo. `Clientes` o `Clientes.NOMBRE`. Varias si está duplicado. */
+    definicion(nombre: string): readonly Declaracion[];
+    /** Quién apunta a ello. Acepta la coll (`Clientes`) o el campo (`Clientes.NOMBRE`). */
+    referencias(nombre: string): readonly Referencia[];
+    /** Los campos de una colección, con su tipo. Vacío si la colección no existe. */
+    campos(coleccion: string): readonly Declaracion[];
+    /** Lo que declara `app.xml`: por dónde arranca, login, estilos y conexiones. */
+    app(): AppDeNavegacion;
+    /** Todo lo de UNA colección. `undefined` si no existe — que no es lo mismo que vacía. */
+    detalle(coleccion: string): DetalleDeColeccion | undefined;
+    /** Lo que no cuadra: referencias a lo que no existe. Y SOLO eso: qué colecciones no usa nadie
+     *  no se mide (ver «Por qué NO hay colecciones huérfanas», más arriba). */
+    problemas(): ProblemasDelProyecto;
+}
+/** Parte `Coll.CAMPO` en sus dos mitades. Sin punto, es una colección a secas. */
+export declare function partirNombre(nombre: string): {
+    coleccion: string;
+    campo?: string;
+};
+/**
+ * Construye el índice. Puro: el modelo entra ya resuelto y traducido.
+ *
+ * **No cachea, y quien lo llama tampoco debería.** Construirlo sobre un proyecto real cuesta
+ * unas decenas de milisegundos —medido— contra los segundos de una llamada al modelo, así
+ * que rehacerlo en cada consulta sale gratis y quita de en medio la pregunta de cuándo
+ * invalidarlo. Un índice viejo que dice que un campo existe cuando el agente acaba de
+ * borrarlo es peor que no tener índice: es una respuesta con autoridad y equivocada.
+ *
+ * **La comparación de nombres NO distingue mayúsculas.** En XOne se escribe `NOMBRE` en la
+ * declaración y `Nombre` en un `mapfld` con la misma intención, y un índice que conteste «no
+ * existe» por la caja manda a buscar un fallo que no está. Lo que se DEVUELVE es siempre el
+ * nombre tal como está declarado, no el que se preguntó.
+ */
+export declare function construirIndice(modelo: ModeloDeNavegacion): IndiceDeNavegacion;