xonecode 0.38.44 → 0.39.2

package/dist/cli/consola.d.ts

@@ -0,0 +1,473 @@
+/**
+ * El lazo de la consola interactiva y los comandos de barra.
+ *
+ * La regla que gobierna este fichero: una consola no llama a `input()` ni imprime por su
+ * cuenta. `correrConsola` recibe de dónde leer (`consola.lineas`) y a dónde escribir
+ * (`consola.escribir`) — en producción stdin y el `escribir` con flush; en los tests, una
+ * lista de líneas y un acumulador. Sin esa costura la consola no se puede probar.
+ */
+import type { MotorDeAgente } from "../core/motor.js";
+import { type Piel } from "../core/turno.js";
+import { type FuentesDeEleccion, type Proveedor } from "../core/modelos.js";
+import type { Papel } from "../core/ports.js";
+import type { PendienteDeAprobacion } from "../core/events.js";
+import type { ResultadoDeTurno } from "../core/entrega.js";
+import type { LineaDeDiff } from "../core/diff.js";
+import { type Decision } from "../vendor/hitl.js";
+import type { AccionDeSincronizacion, ConfirmacionDeBajada, PoliticaDeAprobacion } from "../core/cloudstudio.js";
+import type { NarracionDeSincronizacion, ResultadoDeSubida } from "../core/actos.js";
+import { type Escribir } from "./stdio.js";
+import { type IdTema } from "./tema.js";
+import type { DecisionDeConsola, Preguntar, RespuestaConSeleccion } from "./aprobar.js";
+import { type ModoDeEscritura } from "../core/modoDeEscritura.js";
+import { URL_CLOUDSTUDIO_POR_OMISION } from "../agent/cloudstudio/cloudstudioMcp.js";
+import type { CatalogoModelosPort, ModeloDisponible } from "../core/ports.js";
+import { type Esfuerzo } from "../core/esfuerzo.js";
+/**
+ * Una línea del lazo, con su procedencia DICHA cuando hace falta decirla.
+ *
+ * El lazo mira si la línea empieza por «/» para decidir si es un comando. En las pieles de
+ * TERMINAL eso es exactamente lo que se quiere: el teclado es la única puerta que hay y «/»
+ * es la sintaxis que la abre. En la web no — allí **cada acción tiene su botón** (el modelo
+ * en la pastilla, el tema en Apariencia, la sincronización en su pestaña), así que «/» no
+ * abre nada. Y mientras estuvo abriendo comandos, teclear «/» para hablar de una ruta del
+ * proyecto EJECUTABA una orden en vez de mandarla al modelo.
+ *
+ * La distinción no se puede adivinar mirando la cadena, porque por la MISMA cola circulan
+ * las dos cosas: lo que teclea una persona y lo que pide un control de la interfaz
+ * (`consolaWeb.encolar`, que es como el servidor aplica `/modelo …` sin que nadie lo
+ * teclee). Por eso la línea lo dice:
+ *  - `comoComando: false` — la tecleó una persona en una piel sin comandos. Es PROSA, y va
+ *    al modelo tal cual, con su «/» delante.
+ *  - `comoComando: true` — la pidió un control de la interfaz, o es una piel donde el
+ *    teclado manda. La FUNCIÓN se comparte aunque la sintaxis no se exporte.
+ *
+ * Una `string` a secas se lee como siempre —comando si empieza por «/»—, que es lo que
+ * siguen haciendo stdio, la TUI, la consola de una tarea y los dobles de los tests: el
+ * contrato viejo no se mueve y ninguna de esas pieles cambia de comportamiento.
+ */
+export type LineaDeConsola = string | {
+    texto: string;
+    comoComando: boolean;
+    /**
+     * La CLAVE de sustitución: si al encolar esta línea ya hay otra PENDIENTE con la misma
+     * clave, aquélla se retira. Es para los controles que reflejan un ESTADO —el modo de
+     * escritura, el modelo, el esfuerzo—, que se pulsan una vez por cambio de opinión y
+     * solo el último vale.
+     *
+     * Viaja como DATO, nunca se deduce del `texto`: comparar dos cadenas para ver si «son
+     * el mismo comando» sería parsear la sintaxis que el servidor acaba de componer, la
+     * misma trampa que `DecisionDeConsola` y `Acto.clase` ya evitan.
+     *
+     * **Ausente es lo de siempre**, y eso es la mitad de la decisión: dos `/sync subir` son
+     * dos operaciones, y lo que teclea una persona no se coalesce nunca.
+     */
+    sustituye?: string;
+};
+export interface Consola {
+    /** De dónde vienen las líneas del usuario. Agotarlo termina la sesión: es EOF, no cuelgue. */
+    lineas: AsyncIterable<LineaDeConsola>;
+    escribir: Escribir;
+    /** Para las aprobaciones dentro de un turno. */
+    preguntar: Preguntar;
+    interactivo: boolean;
+    /**
+     * ¿Se acabó la entrada? Acompaña a `preguntar`, y existe porque su cadena vacía
+     * significa DOS cosas —el usuario pulsó Enter, o el readline se cerró— y con
+     * `interactivo: true` la primera APRUEBA: sin distinguirlas, un Ctrl-D aprobaba una
+     * escritura de fichero (`cli/aprobar.ts` lo cuenta entero). Ausente = no se sabe; la
+     * TUI y la web no lo necesitan porque sus aprobaciones van por `aprobacionesTui`.
+     */
+    eof?: () => boolean;
+    /**
+     * Lee una clave SIN eco (para `provider`). El eco-off no se puede probar desde
+     * aquí: es la costura de test, y la implementación de producción (raw-mode de
+     * stdin) vive fuera — este fichero solo la usa.
+     */
+    leerSecreto: (pregunta: string) => Promise<string>;
+    /** El catálogo vivo entra por puerto; los tests le dan su doble determinista. */
+    catalogoModelos: CatalogoModelosPort;
+    /** Escritura global inyectada: la consola elige, pero no conoce el disco. */
+    guardarModeloGlobal: (papel: Papel, id: string) => {
+        ruta: string;
+        id: string;
+    };
+    /**
+     * Selector opcional de una piel rica. La consola conserva su flujo de preguntas y
+     * número cuando no existe (stdio y tests que no montan la TUI).
+     */
+    seleccionar?: (selector: SelectorDeConsola) => Promise<string | undefined>;
+    /**
+     * La piel que los turnos usan para pintarse. La consola stdio no la define (se usa
+     * `crearPielStdio`); la TUI la aporta — mismo contrato `Piel`, otro render.
+     */
+    piel?: () => Piel;
+    /**
+     * Las aprobaciones propias (modal TUI). Ausente = `pedirDecisiones` por readline.
+     * Mismo contrato que el puerto `pedirAprobacion` de `abrirSesionReal`.
+     */
+    aprobacionesTui?: (pendientes: PendienteDeAprobacion[], ficheros: Map<string, string>, diffs: Map<string, LineaDeDiff[]>) => Promise<Map<string, Decision>>;
+    /**
+     * Cuántas RONDAS de aprobación admite un turno de esta consola. Ausente = el de siempre
+     * (`MAX_APPROVAL_ROUNDS`).
+     *
+     * Lo pone quien monta la consola porque es quien sabe QUIÉN está detrás: el tope de
+     * cinco se dimensionó para una persona pulsando —«te lo he preguntado cinco veces,
+     * para»—, y en una tarea de fondo una ronda no es una pregunta, es una tanda de
+     * escrituras que se autorizan solas. Lo reenvía `crearEjecutorReal` a `abrirSesionReal`,
+     * que es donde vive el bucle; ver `TOPE_DE_RONDAS_DE_TAREA` (`core/tareas.ts`) para el
+     * valor y el porqué de que no sea infinito.
+     */
+    topeDeAprobaciones?: number;
+    /**
+     * Esta piel tiene el modo de escritura SIEMPRE a la vista. Ausente = no.
+     *
+     * Lo declara quien monta la consola, igual que `topeDeAprobaciones`, y cambia cuánto
+     * EXPLICA `/aprobacion` al ponerlo. En la web hay una pastilla en el compositor y una
+     * nota permanente arriba del chat que ya cuentan los tres detalles —que se avisará con
+     * los nombres, que es de esta conversación y que subir sigue preguntando—, así que
+     * repetirlos en el transcript era la duplicación de siempre: cuatro renglones que dicen
+     * lo que se está leyendo dos centímetros más arriba. En el terminal no hay ni pastilla ni
+     * nota, y esos tres detalles son lo único que los cuenta.
+     *
+     * Va como propiedad del DESTINO y no como una bandera de la línea, por lo mismo que
+     * `Piel.anotarSincronizacion?`: la misma `/aprobacion` tecleada en el terminal DEBE
+     * imprimir la explicación entera, y eso no lo puede decidir quien compone el texto.
+     */
+    modoALaVista?: boolean;
+    /**
+     * El agente puede PROPONER repartir un encargo en tareas de fondo encadenadas (`proponer_tareas`).
+     * Ausente = no. Lo declara solo la consola de una PERSONA en la web, que es la que tiene la cola de
+     * tareas y la tarjeta para encolarlas: la de una tarea de fondo no (encadenaría trabajo sin nadie
+     * delante), ni el terminal, `run` o los evals. Lo lee `crearEjecutorReal` al abrir la sesión.
+     */
+    proponeTareas?: boolean;
+    /**
+     * Es la consola de una TAREA DE FONDO: nadie delante que conteste. Ausente = no. Con ella el agente resuelve sus dudas
+     * solo —su opción recomendada, o la que decida— y cierra con un resumen de lo que hizo (`trabajoSinPersona` en
+     * TrueForge). Lo declara solo `consolaDeTarea.ts`; lo lee `crearEjecutorReal` al abrir la sesión.
+     */
+    tareaDeFondo?: boolean;
+    /**
+     * El estado de sesión ACABA de cambiar (un comando devolvió uno nuevo).
+     *
+     * Existe porque el modelo en vigor vive dentro del lazo: `/modelo` y `/modelos` cambian
+     * `estado.fuentes` en caliente y no tocan disco, así que nadie fuera de `correrConsola`
+     * puede saber cuál está puesto — y una piel que lo enseñe tiene que enterarse cuando
+     * cambia, no derivarlo de una frase del transcript. stdio y la TUI no la implementan: la
+     * TUI ya re-parsea `acuseDeModelo` para su barra lateral, y stdio no pinta estado.
+     */
+    alEstado?: (estado: EstadoDeSesion) => void;
+    /** Cambia la paleta de la piel actual; la TUI además fuerza un repintado completo. */
+    aplicarTema?: (tema: IdTema) => void;
+    /** Persistencia inyectada: el tema es del proyecto, no de la cuenta. */
+    guardarTemaDeProyecto?: (tema: IdTema) => {
+        ruta: string;
+        tema: string;
+    };
+    /** Conexión OAuth + MCP, inyectada desde agent para que esta capa siga sin SDK MCP. */
+    conectarCloudStudio?: (url: string, scopes: readonly string[], informar: (texto: string) => void) => Promise<{
+        url: string;
+        scopes: readonly string[];
+        herramientas: Array<{
+            nombre: string;
+            descripcion: string;
+        }>;
+        proyectos: Array<{
+            id: string;
+            nombre: string;
+        }>;
+    }>;
+    /** El endpoint es configuración de proyecto; los tokens OAuth no. */
+    guardarCloudStudioDeProyecto?: (url: string, scopes: readonly string[]) => {
+        ruta: string;
+        url: string;
+        scopes: string[];
+    };
+    /** El modo es configuración local del proyecto, inyectada desde el adaptador de disco. */
+    guardarModoDeProyecto?: (modo: "offline" | "cloud") => {
+        ruta: string;
+        modo: "offline" | "cloud";
+    };
+    guardarProyectoCloudStudioDeProyecto?: (proyecto: {
+        id: string;
+        nombre: string;
+    }) => {
+        ruta: string;
+        proyecto: {
+            id: string;
+            nombre: string;
+        };
+    };
+    /**
+     * Las ramas del proyecto remoto YA elegido, hermana de `conectarCloudStudio`: esta capa
+     * tampoco conoce MCP para esto. Con una sola rama disponible el alta no pregunta.
+     */
+    ramasDeCloudStudio?: (proyecto: string) => Promise<string[]>;
+    /** La rama ORIGEN es identidad del remoto, no una preferencia: va dentro de `cloudstudio`. */
+    guardarRamaDeProyecto?: (rama: string) => {
+        ruta: string;
+        rama: string;
+    };
+    /** El modelo propio del proyecto, por papel. Nunca lleva claves. */
+    guardarModelosDeProyecto?: (papel: Papel, id: string) => {
+        ruta: string;
+        id: string;
+    };
+    /**
+     * Sincronización con CloudStudio, inyectada desde `agent/`: esta capa no conoce MCP ni
+     * git. Su ausencia (modo guion, tests) es la que hace que `/sync` lo diga sin reventar.
+     *
+     * `politicaDeAprobacion` solo importa para «subir» (`core/cloudstudio.ts` documenta el
+     * hueco): quien construye el adaptador real la reenvía a `agent/cloudstudio/subida.ts#subir`, que
+     * la exige. Esta capa no rellena el hueco por su cuenta — eso es cosa del comando
+     * `/sync` (ver `politicaInteractiva` más abajo), que sí tiene `preguntar`/`escribir`.
+     */
+    sincronizar?: (accion: AccionDeSincronizacion, raiz: string, politicaDeAprobacion?: PoliticaDeAprobacion, 
+    /**
+     * Los avisos DETERMINISTAS de la sincronización, tal cual los emite `agent/`: «el
+     * servidor truncó el listado», «el ZIP falló; bajando fichero a fichero», qué
+     * ficheros no se pudieron bajar, cuántos no subieron, qué configuración de git se
+     * conservó. En este repo los avisos son código y no prompt; sin este cable estaban
+     * escritos y no llegaban a ninguna parte (el `informar` por omisión es `() => {}`).
+     */
+    informar?: (texto: string) => void, 
+    /**
+     * Para «bajar»: quien autoriza VACIAR la copia (`core/cloudstudio.ts#ConfirmacionDeBajada`).
+     * Ausente = no se vacía y se aplica la regla de antes. La rellena el comando `/sync`, que
+     * es quien tiene `preguntar`.
+     */
+    confirmarBajada?: ConfirmacionDeBajada) => Promise<{
+        tipo: "texto";
+        texto: string;
+        subida?: ResultadoDeSubida;
+        bajada?: {
+            bajados: number;
+        };
+    } | {
+        tipo: "arbol-sucio";
+        accion: "bajar" | "subir";
+        pendientes: string[];
+    }>;
+    /**
+     * Una operación de sincronización ENTERA, para la piel que tiene un sitio propio donde
+     * contarla.
+     *
+     * **Es OPCIONAL, y por la misma asimetría que `fase?`, `razonamiento?` y `notificacion?` en
+     * `Piel`**: quien no lo implemente —stdio, la TUI, la consola de una tarea, los dobles de los
+     * tests— sigue recibiendo el recorrido por `escribir`, al vuelo y byte a byte como siempre.
+     * Lo que cambia NO es por dónde pasa la sincronización: `/sync subir` y `/sync bajar` siguen
+     * siendo la MISMA línea encolada, con el mismo plan, la misma guarda de árbol sucio y la
+     * misma aprobación. Lo que cambia es DÓNDE SE CUENTA, y eso es una propiedad del destino, no
+     * de la línea: la misma orden en el terminal DEBE imprimir su recorrido y en el navegador no
+     * tiene por qué ensuciar el hilo.
+     *
+     * El nombre es el de la piel web (`anotar*`), y aquí significa «guárdalo en tu registro»: el
+     * comando acumula las líneas y entrega UNA operación al final, ya con su hora y su acción.
+     * Implementado, `/sync` no escribe ni una línea por `escribir`.
+     */
+    anotarSincronizacion?: (operacion: NarracionDeSincronizacion) => void;
+    /**
+     * Una decisión en la que quien contesta puede quedarse con PARTE del plan: la subida a
+     * CloudStudio en el navegador, donde el plan es un árbol con casillas.
+     *
+     * **OPCIONAL por la misma asimetría que `anotarSincronizacion?`**: stdio, la TUI, la consola
+     * de una tarea y los dobles no la tienen, y `politicaInteractiva` cae entonces en `preguntar`
+     * —todo o nada, byte a byte como siempre—. La implementa `web/servidor/consolaWeb.ts`, y un
+     * test de esa consola REAL comprueba que la selección llega a la política: un método opcional
+     * declarado y nunca implementado no da ningún error que leer.
+     */
+    decidirConSeleccion?: (pregunta: string, decision: DecisionDeConsola) => Promise<RespuestaConSeleccion>;
+}
+/**
+ * Saludo local de la consola. No procede del modelo ni se incorpora al hilo: debe hacer
+ * visible que xonecode está listo sin gastar tokens ni sesgar la primera petición.
+ */
+export declare const MENSAJE_BIENVENIDA = "\u00A1Bienvenido a XOneCode! Puedo analizar, explicar y modificar tu proyecto XOne. Escribe `/` para ver los comandos o cu\u00E9ntame qu\u00E9 necesitas.\n";
+/**
+ * Hay estado que retomar solo cuando existe la memoria del PROYECTO. Una carpeta
+ * `.xonecode` con `config.json` aislado no representa trabajo anterior y debe conservar
+ * el saludo de primera visita.
+ */
+export declare function hayEstadoDeProyecto(raiz: string): boolean;
+/**
+ * Petición interna de reanudación. Es deliberadamente de solo lectura y estrecha para
+ * que abrir una sesión existente no se convierta en otra exploración exhaustiva.
+ */
+export declare const PETICION_REANUDAR_PROYECTO: string;
+export declare const MENSAJE_REANUDANDO = "Analizando el estado guardado del repositorio\u2026\n";
+export { URL_CLOUDSTUDIO_POR_OMISION };
+/**
+ * Primer contacto con una carpeta. En pipes no se crea estado ni se pregunta: el modo
+ * offline histórico permanece exactamente igual. Cloud se persiste SOLO después de
+ * autenticar y descubrir el MCP, de modo que un login cancelado deja la carpeta virgen.
+ */
+export declare function configurarModoInicial(raiz: string, consola: Consola): Promise<void>;
+/** Datos de un selector: UI-neutral, para que `consola.ts` no conozca Ink. */
+export interface SelectorDeConsola {
+    titulo: string;
+    opciones: readonly {
+        id: string;
+        etiqueta: string;
+        detalle?: string;
+    }[];
+    /**
+     * Por qué se está preguntando esto (o por qué se pregunta OTRA VEZ). Existe porque hay
+     * una piel que no pinta el transcript mientras pregunta: durante el alta, la consola web
+     * enseña solo la tarjeta con el selector (`apps/web/src/App.tsx`, rama `enAlta`), así que
+     * un motivo dicho con `escribir` acabaría en un acto de sistema que nadie está mirando —
+     * un fallo mudo justo en el paso que se repite. Las pieles de terminal lo pueden ignorar:
+     * ahí el `escribir` ya está a la vista, encima del selector.
+     */
+    aviso?: string;
+}
+export interface EstadoDeSesion {
+    hilo: string;
+    raiz: string;
+    fuentes: FuentesDeEleccion;
+    /** Overrides vivos de `/modelos`, separados de las banderas con las que arrancó la CLI. */
+    seleccionesDeCatalogo?: Partial<Record<Papel, string>>;
+    /**
+     * Cuánto razona el modelo en esta sesión. Ausente = no se manda el parámetro.
+     *
+     * Va FUERA de `fuentes` a propósito: `FuentesDeEleccion` contesta «qué modelo le toca a
+     * cada papel» y tiene su propia precedencia de seis escalones, mientras que esto es un
+     * ajuste DEL modelo resuelto — no compite con nada ni viene de un fichero. Meterlo ahí
+     * habría obligado a `resolver()` a devolverlo por papel, que es una pregunta que nadie
+     * hace: el esfuerzo es de la sesión, no del papel.
+     *
+     * No se valida aquí contra el modelo: eso lo hace `esfuerzoAplicable` al CONSTRUIR, que
+     * es el único sitio que conoce las dos mitades. Un nivel guardado que el modelo de ahora
+     * no admite se omite en vez de tumbar el turno — y vuelve a valer si se cambia a un
+     * modelo que sí lo acepte, que es justo lo que se quiere al ir probando.
+     */
+    esfuerzo?: Esfuerzo;
+    /** El motor de agente de esta sesión (`core/motor.ts`). Ausente = el de la configuración. */
+    motor?: MotorDeAgente;
+    /**
+     * Quién aprueba las escrituras en esta sesión: supervisado (cada una con su diff) o
+     * autónomo (se aplican solas). Ausente = supervisado, y eso NO es «no consta»: de esto
+     * hay que decidir algo en cada escritura, así que el hueco se resuelve, y la única
+     * dirección segura para resolverlo es la que enseña el diff.
+     *
+     * Vive AQUÍ y no en `settings.json` —donde vivía, indexado por ruta— porque es de la
+     * SESIÓN: el mando está dentro de la caja del chat y se lee como «esta conversación».
+     * `core/modoDeEscritura.ts` tiene el argumento entero, incluido por qué se retiró la
+     * condición que lo prohibía en un proyecto conectado a CloudStudio.
+     *
+     * Va fuera de `fuentes` por lo mismo que el esfuerzo: `FuentesDeEleccion` contesta «qué
+     * modelo le toca a cada papel» y esto no compite con nada ni viene de un fichero.
+     */
+    modo?: ModoDeEscritura;
+}
+/** Lo que hace un comando de barra: escribe y puede cambiar el estado de la sesión. */
+export type ManejadorDeBarra = (args: string[], estado: EstadoDeSesion, consola: Consola) => Promise<{
+    seguir: boolean;
+    estado?: EstadoDeSesion;
+}>;
+/**
+ * Cómo se corre una línea de prosa. El valor por omisión usa el agente guionizado.
+ *
+ * **Devuelve lo que el turno sabe de sí mismo**, y ese retorno es una deuda que se paga
+ * aquí. Devolvía `Promise<void>`, así que `crearEjecutorReal` (`cli/main.ts`) tiraba el
+ * retorno de `sesion.turno` y con él el `cortadoPorTope` que sabe que quedaron escrituras
+ * sin aplicar. Medido con las tareas de fondo: cuatro ficheros escritos, una escritura
+ * abandonada, el verificador sin correr ni una vez, y el kanban diciendo «terminada».
+ *
+ * `void` sigue siendo válido a propósito: la mayoría de los caminos —el guionizado, las
+ * pieles que solo pintan— no tienen nada que informar, y **ausente no es vacío**: quien lo
+ * consume trata «no informó» como «no se sabe» y no como «todo bien»
+ * (`core/entrega.ts#medidaDeEntrega`). Con eso ninguna piel cambia y la tubería sigue
+ * siendo byte-idéntica.
+ */
+export type EjecutorDeTurno = (peticion: string, estado: EstadoDeSesion, consola: Consola) => Promise<ResultadoDeTurno | void>;
+/**
+ * Un turno con `AgenteGuionizado`, igual que el `cmdRun` sin `--real`.
+ *
+ * Es el valor por omisión de `correrConsola`: mantiene el invariante de fase 1 (todo corre
+ * sin API y sin red). El cableado del agente REAL va en otra tarea y se inyecta como
+ * tercer parámetro, mismo patrón que `cmdVerify(ruta, escribir, verificador = ...)`.
+ */
+export declare function ejecutarTurnoGuionizado(peticion: string, _estado: EstadoDeSesion, consola: Consola): Promise<void>;
+/** Filtra por id o nombre sin alterar el orden publicado por el proveedor. */
+export declare function filtrarModelos(modelos: readonly ModeloDisponible[], filtro: string): ModeloDisponible[];
+export type EleccionNumerada = {
+    tipo: "elegido";
+    modelo: ModeloDisponible;
+} | {
+    tipo: "cancelado";
+} | {
+    tipo: "invalido";
+};
+/** Un número visible es uno basado en uno; Enter significa cancelar, no elegir el primero. */
+export declare function elegirPorNumero(modelos: readonly ModeloDisponible[], respuesta: string): EleccionNumerada;
+/** Un papel vacío permite salir del flujo, pero cualquier otro texto debe ser exacto. */
+export declare function elegirPapel(respuesta: string): Papel | undefined;
+/** La global solo tiene efecto inmediato si no hay una fuente de rango superior para ese papel. */
+export declare function fuenteQueEclipsaGlobal(papel: Papel, fuentes: FuentesDeEleccion, seleccionesDeCatalogo?: Partial<Record<Papel, string>>): "bandera" | "entorno" | "proyecto" | undefined;
+/** Exportada: `main.ts` la usa para el contexto de `asistenteDeModelo` (stdio y TUI). */
+export declare function hayCredencial(proveedor: Proveedor, raiz: string): boolean;
+/**
+ * El selector de modelo de un catálogo ya elegido: la parte que `/modelos` y el alta de
+ * proyecto (`configurarModoInicial`) COMPARTEN, para que no haya dos copias del mismo
+ * flujo (rico con `seleccionar`, o numerado por `preguntar` cuando esa costura no existe).
+ * Devuelve el id crudo del catálogo (sin el prefijo `<proveedor>/`) o `undefined` si se
+ * canceló o no había nada entre lo que elegir — los mensajes de cada caso ya se escriben
+ * aquí, así que quien llama no repite el aviso.
+ */
+export declare function seleccionarModelo(proveedor: Proveedor, consola: Consola): Promise<string | undefined>;
+export declare function crearCompleter(escribir: Escribir, ficherosDelProyecto?: () => ReadonlySet<string>): (linea: string) => [string[], string];
+/**
+ * La ÚNICA política de aprobación que existe hoy: rellena el hueco de
+ * `core/cloudstudio.ts#PoliticaDeAprobacion` con un humano que ve el plan y responde.
+ * Vive aquí, en `cli/`, y no en `agent/cloudstudio/subida.ts`: la política es de la piel, el hueco es
+ * del motor.
+ *
+ * **Es MÁS estricta que `cli/aprobar.ts`, a propósito: aquí el Enter a secas no aprueba
+ * ni con TTY.** No es el mismo acto. En `aprobar.ts` se autoriza una escritura con su
+ * diff delante, línea a línea, y el Enter que aprueba lo pulsa alguien que está mirando
+ * el cambio; aquí se PUBLICA en un servidor remoto, lo que hay en pantalla es una lista
+ * de rutas —no el contenido— y es la operación menos reversible del producto. El detalle
+ * que lo hace peligroso no se ve: `APPROVALS_TTY` (`vendor/hitl.ts`) contiene la cadena
+ * VACÍA, así que pasarle `interactive` a `interpretAnswer` convertiría en «sube» toda
+ * respuesta vacía — y `consola.preguntar` devuelve "" también cuando el readline ya está
+ * cerrado (Ctrl-D, un stdin agotado a mitad de turno). Un EOF no puede publicar. Por eso
+ * se llama sin opciones, contra `APPROVALS_NO_TTY`, y el prompt enseña `[s/N]` siempre:
+ * un default visible que no fuera el real sería mentir en el paso que sube.
+ *
+ * **Y el plan viaja CON la pregunta, no solo delante de ella** (`DecisionDeConsola`): la
+ * tarjeta de la consola web enseña la lista y ofrece Aceptar/Cancelar, sin campo donde
+ * teclear, y para eso hay que decirle que la respuesta es sí o no. Adivinarlo del `[s/N]`
+ * sería leer la sintaxis, y el día que ese prompt cambie la tarjeta ofrecería un editor
+ * para una decisión —o dos botones sobre una pregunta abierta— sin un solo error.
+ *
+ * La política AUTÓNOMA (el papel `afilado` decidiendo sin que nadie mire) todavía no
+ * existe — hace falta, además del veredicto del juez, que el código compruebe
+ * condiciones deterministas (verificador en verde, árbol limpio, plan sin pendientes):
+ * ver el comentario de `PoliticaDeAprobacion`.
+ *
+ * **`decir` es el sumidero de la operación**, y entra por parámetro porque el plan NO siempre
+ * se cuenta en el scrollback: una piel con registro propio (`anotarSincronizacion`) guarda la
+ * operación entera y no quiere ni una línea suelta en el hilo. Por omisión es `consola.escribir`,
+ * así que quien no pase nada —los tests, cualquier otro llamador— tiene el comportamiento de
+ * siempre.
+ */
+export declare function politicaInteractiva(consola: Consola, decir?: (texto: string) => void): PoliticaDeAprobacion;
+/**
+ * La confirmación de «Actualizar repo local», con lo que se pierde DELANTE — la misma forma
+ * que `politicaInteractiva`: las líneas que van al registro viajan también en la pregunta,
+ * y la tarjeta las pinta con dos botones. Fail-closed: lo que no sea un sí, no vacía nada.
+ */
+export declare function confirmacionInteractiva(consola: Consola, decir?: (texto: string) => void): ConfirmacionDeBajada;
+export declare const COMANDOS: Record<string, {
+    descripcion: string;
+    manejador: ManejadorDeBarra;
+}>;
+/**
+ * El lazo: una línea, una acción, y a la siguiente.
+ *
+ * Tres cosas NO tumban la sesión: un comando de barra que lanza, un turno que lanza y un
+ * comando desconocido (que jamás se manda al modelo). El hilo vive en el checkpointer, así
+ * que lo que falle en un turno lo pierde ese turno, no la sesión.
+ */
+export declare function correrConsola(consola: Consola, estado: EstadoDeSesion, ejecutarTurno?: EjecutorDeTurno): Promise<number>;

package/dist/cli/describe.d.ts

@@ -0,0 +1,7 @@
+import { type FuentesDeEleccion } from "../core/modelos.js";
+import { type Escribir } from "./stdio.js";
+/**
+ * Qué hay montado. **Sin red, sin claves y sin el simulador**, a propósito: existe para
+ * ver la deriva, y un diagnóstico que necesita credenciales no se usa cuando hace falta.
+ */
+export declare function cmdDescribe(fuentes: FuentesDeEleccion, escribir?: Escribir, raiz?: string): number;

package/dist/cli/doctor.d.ts

@@ -0,0 +1,8 @@
+import { type Escribir } from "./stdio.js";
+/**
+ * ¿Puede este sitio ser un proyecto XOne, y responde el simulador?
+ *
+ * Sale con código != 0 si falta algo imprescindible: es un diagnóstico, y uno que siempre
+ * dice que sí no sirve de nada en CI.
+ */
+export declare function cmdDoctor(escribir?: Escribir): Promise<number>;

package/dist/cli/fuentesDeDisco.d.ts

@@ -0,0 +1,25 @@
+import { cargar } from "../agent/config/configEnDisco.js";
+import type { FuentesDeEleccion } from "../core/modelos.js";
+/**
+ * Lo que hay que leer del disco ANTES de elegir un modelo: la configuración —del proyecto y
+ * la global— y las credenciales, que se aplican al proceso.
+ *
+ * **Existe porque había DOS puertas y solo una lo hacía.** La consola hidrataba sus fuentes
+ * con `cargar()` y llamaba a `aplicarAuth`; `run --real` recibía únicamente lo que venía por
+ * bandera, así que corría con el modelo POR OMISIÓN aunque hubiera uno configurado —medido:
+ * el `config.json` global decía un modelo y el turno dijo otro, con su origen «(omision)» al
+ * lado— y, peor, sin `aplicarAuth` la clave nunca llegaba a `process.env`: un proveedor con
+ * credencial no se podía alcanzar desde `run` de ninguna forma. Para un comando cuyo trabajo
+ * es MEDIR lo que cuesta un turno, medir otro modelo del que se usa lo deja sin sentido.
+ *
+ * Un solo cuerpo de función y dos llamadores, que es la regla de siempre en este repo: dos
+ * copias de esto son dos sitios donde una de las dos se queda sin la mitad.
+ *
+ * **Lo que viene por bandera se conserva tal cual**: aquí no se decide ninguna precedencia
+ * —de eso va `core/modelos.ts#resolver`, que además recuerda el origen de cada valor—, esto
+ * solo rellena las dos fuentes que viven en disco.
+ */
+export declare function hidratarFuentesDeDisco(raiz: string, fuentes: FuentesDeEleccion): {
+    fuentes: FuentesDeEleccion;
+    cargado: ReturnType<typeof cargar>;
+};