xonecode 0.38.41 → 0.39.2

package/dist/agent/dispositivos/dispositivosEnMaquina.d.ts

@@ -0,0 +1,161 @@
+/**
+ * El PATH de un proceso hijo con carpetas AÑADIDAS al final, con las reglas de la plataforma.
+ *
+ * Dos cosas que en Windows no son como en macOS, y las dos se rompían en silencio: el
+ * separador es `;` y no `:` (que además vive DENTRO de `C:\…`), y la variable suele llamarse
+ * `Path`. Se devuelve con el MISMO nombre con que llegó: en Windows el entorno no distingue
+ * mayúsculas, y un hijo con `PATH` y `Path` a la vez recibiría uno de los dos sin que nadie
+ * diga cuál. Sin ninguno puesto, `PATH`.
+ */
+export declare function pathConCarpetas(entorno: Record<string, string | undefined>, carpetas: readonly string[], plataforma: string): {
+    nombre: string;
+    valor: string;
+};
+/** Componer una ruta con las reglas de la plataforma medida (ver `rutasDe`). */
+export declare function unirRuta(plataforma: string, ...partes: string[]): string;
+import { type AjustesDeDispositivos } from "../../core/settings.js";
+import { type Dispositivo, type NombreDeHerramienta, type InformeDeDispositivos } from "../../core/dispositivos.js";
+export interface Ejecucion {
+    stdout: string;
+    stderr: string;
+}
+export interface DependenciasDeDeteccion {
+    /** `process.platform`. */
+    plataforma?: string;
+    /** `process.env`. */
+    entorno?: Record<string, string | undefined>;
+    /** El home del usuario, para las carpetas de SDK por omisión. */
+    home?: string;
+    existe?: (ruta: string) => boolean;
+    ejecutar?: (binario: string, args: string[], opciones: {
+        timeout: number;
+    }) => Promise<Ejecucion>;
+    /** Lee el fichero que `devicectl` escribió. */
+    leer?: (ruta: string) => Promise<string>;
+    /** Lo borra: SIEMPRE, también si `xcrun` falló a medias y lo dejó escrito. */
+    borrar?: (ruta: string) => Promise<void>;
+    /** Dónde escribir el JSON de `devicectl`. */
+    ficheroTemporal?: () => string;
+    ahora?: () => Date;
+}
+/** Cuánto se espera a cada herramienta antes de darla por colgada. */
+export declare const TOPES_MS: {
+    /** `adb devices` arranca el demonio si hace falta y eso tarda segundos en frío. */
+    readonly adb: 15000;
+    readonly emulator: 10000;
+    readonly xcrun: 20000;
+};
+export declare function localizadorDeAndroid(deps: {
+    plataforma: string;
+    entorno: Record<string, string | undefined>;
+    home: string;
+    existe: (ruta: string) => boolean;
+}): {
+    raicesDeSdk: string[];
+    enPath: (nombre: string) => string | undefined;
+    /** En el PATH y, si no, dentro del SDK bajo `subcarpeta`. */
+    enSdk: (nombre: string, subcarpeta: string) => string | undefined;
+};
+/**
+ * El JDK con el que corre `sdkmanager`, que es un programa Java.
+ *
+ * `JAVA_HOME` si el usuario la puso; si no, por sistema: en macOS el `openjdk@17` de
+ * Homebrew en los dos prefijos —preguntárselo a `brew --prefix` costaría un proceso en cada
+ * medida—; en Windows la ruta FIJA donde cae el paso 2 de la receta,
+ * `%LOCALAPPDATA%\Android\jdk17` (`descargaDeHerramientas.ts` renombra ahí la carpeta
+ * versionada que trae el zip de Adoptium). Lo usan el detector, para decir si los últimos
+ * pasos se pueden lanzar, y el ejecutor, para ponérselo al hijo: una segunda copia habría
+ * divergido con el síntoma peor, que el botón se ofreciera y luego no encontrara el JDK.
+ */
+export declare function jdkDeLaMaquina(entorno: Record<string, string | undefined>, existe: (ruta: string) => boolean, plataforma: string): string | undefined;
+export declare function detectarDispositivos(deps?: DependenciasDeDeteccion, 
+/** Qué destinos se miran. Ausente = todos (`core/settings.ts#seMira`). */
+ajustes?: AjustesDeDispositivos): Promise<InformeDeDispositivos>;
+/** Cuánto se espera al instalador antes de darlo por colgado. */
+export declare const TOPE_DE_INSTALACION_MS = 60000;
+/**
+ * Lanza el instalador de una herramienta, si hay uno para ella en esta plataforma.
+ *
+ * **Un código de salida distinto de cero NO siempre es un fallo aquí**: `xcode-select
+ * --install` sale con error cuando las herramientas YA están instaladas, y eso no es nada
+ * que contar. Lo que se propaga es lo que impide seguir —que no exista el binario, o que se
+ * cuelgue—; del resto se encarga la medida de después, que es la que dice la verdad sobre si
+ * la herramienta está.
+ */
+export declare function instalarHerramientaDeDispositivos(herramienta: NombreDeHerramienta, deps?: Pick<DependenciasDeDeteccion, "plataforma" | "ejecutar">): Promise<void>;
+/**
+ * VERIFICAR la conexión con un dispositivo: hablarle y esperar respuesta.
+ *
+ * Es otra pregunta que la de `detectarDispositivos`, y por eso es otra función. Listar
+ * (`adb devices`, `simctl list`) dice lo que el intermediario CREE: adb contesta «device»
+ * de un teléfono cuyo `adb shell` se ha quedado colgado, y `simctl list` describe carpetas
+ * en disco —medido: `simctl getenv` contesta la ruta de datos de un simulador APAGADO, así
+ * que no vale como comprobación de nada—. Esto ejecuta algo AL OTRO LADO:
+ *
+ * - **Android** (físico o emulador): `adb -s <serial> shell getprop ro.product.model`. Si
+ *   contesta, hay una shell viva dentro y de paso se sabe qué aparato es. Un teléfono sin
+ *   autorizar falla aquí con su propio motivo, que es lo que hay que leer.
+ * - **Simulador iOS**: `xcrun simctl spawn <udid> /usr/bin/uname -r`, medido contra un
+ *   simulador arrancado (contesta) y uno apagado (código 149 y «device is not booted»). Se
+ *   eligió `spawn` justamente porque exige que el simulador esté vivo.
+ * - **iPhone o iPad físico**: `xcrun devicectl device info details --device <id>`, la misma
+ *   herramienta que los lista. **No está medido**: en esta máquina no hay ninguno conectado,
+ *   igual que `parsearDevicectl`, y la forma sale de su documentación.
+ *
+ * **El identificador NO viene del cliente.** Quien llama pasa el `Dispositivo` de la última
+ * medida, que es la única fuente sobre la máquina: un id que llegara del navegador sería una
+ * cadena de fuera dentro de los argumentos de un proceso.
+ *
+ * Nunca lanza: todo vuelve como `{ok, detalle}` de UNA línea. Quien la llama está atendiendo
+ * una petición del navegador, y esto es una respuesta, no una excepción.
+ */
+export interface VerificacionDeDispositivo {
+    ok: boolean;
+    /** Una línea: lo que contestó, o por qué no. Nunca la salida entera. */
+    detalle: string;
+}
+export declare function verificarDispositivo(dispositivo: Dispositivo, deps?: Pick<DependenciasDeDeteccion, "plataforma" | "entorno" | "home" | "existe" | "ejecutar" | "leer" | "borrar" | "ficheroTemporal">): Promise<VerificacionDeDispositivo>;
+/**
+ * Si un dispositivo Android tiene instalado el framework de XOne.
+ *
+ * **Se pregunta por el PAQUETE, no por el servidor.** `getLog` contesta con `deviceInfo` y
+ * `isXOneFramework: true`, y es la confirmación buena… **después** de conectar, cuando ya hay
+ * túnel y la app está viva. Antes de eso no hay a quién preguntar: el servidor vive dentro del
+ * proceso de la app, y sin app no hay proceso. Así que son dos momentos y dos medidas: el
+ * paquete decide si se puede EMPEZAR; `isXOneFramework` confirma, al final, que con quien se
+ * habló era el framework.
+ *
+ * Un solo viaje: `adb -s <serial> shell pm list packages com.xone.android`, que filtra por
+ * subcadena y trae de una vez los dos flavors. Y se busca por nombre EXACTO entre lo que
+ * contestó: el filtro es por subcadena, así que la lista puede traer parecidos, y dar por
+ * instalado algo que solo se le parece es afirmar de más.
+ *
+ * **No se lee `versionName` ni `versionCode`**: eso es de la INSTALACIÓN, que es otra pasada.
+ * Aquí la pregunta es de sí o no.
+ *
+ * **El `paquete` viaja en el resultado y no se guarda en ningún módulo**: es lo que necesita
+ * el reinicio posterior, porque el comando depende del flavor que este aparato tenga
+ * (`am start -n <paquete>/com.xone.android.hotswap.activities.SetupActivity`).
+ *
+ * Como `verificarDispositivo`, nunca lanza: todo vuelve como `{instalado, detalle}` de UNA
+ * línea. Y un dispositivo que no sea Android contesta sin lanzar NADA —no hay `adb` que
+ * preguntarle a un iPhone, y buscarlo sería un proceso gastado para nada.
+ */
+export interface FrameworkEnDispositivo {
+    instalado: boolean;
+    /**
+     * El nombre EXACTO del paquete que se encontró. **Ausente es «no se encontró»**, nunca un
+     * paquete por omisión: quien vaya a reiniciar con esto tiene que poder distinguir «no hay
+     * framework» de «hay este».
+     */
+    paquete?: string;
+    /** Una línea: qué se encontró, o por qué no. Nunca la salida entera. */
+    detalle: string;
+}
+export declare function frameworkEnDispositivo(dispositivo: Dispositivo, deps?: Pick<DependenciasDeDeteccion, "plataforma" | "entorno" | "home" | "existe" | "ejecutar">): Promise<FrameworkEnDispositivo>;
+/**
+ * Una línea sobre por qué falló, sin la salida entera. Un proceso que `execFile` mató por
+ * el timeout llega con `killed: true`; lo demás es la primera línea útil de stderr o del
+ * mensaje, recortada.
+ */
+export declare function describirFallo(error: unknown, topeMs: number): string;

package/dist/agent/dispositivos/geometriaEnDisco.d.ts

@@ -0,0 +1,17 @@
+import type { ImagenRgba } from "../../core/compararCapturas.js";
+/** El nombre del fichero de geometría de una captura. La MISMA regla que `nombreDeGeometria` del script. */
+export declare function nombreDeGeometria(nombreDeCaptura: string): string;
+/** Cuántas geometrías, de las más recientes, se miran al buscar por contenido. */
+export declare const GEOMETRIAS_A_MIRAR = 12;
+/** Cuántos píxeles distintos hay, en fracción; `Infinity` si no tienen el mismo tamaño. Recorre la imagen ENTERA. Pura. */
+export declare function fraccionDistinta(a: ImagenRgba, b: ImagenRgba): number;
+/** ¿Son la MISMA imagen (la misma captura, quizá reconvertida)? Pura. */
+export declare function mismaImagen(a: ImagenRgba, b: ImagenRgba): boolean;
+export interface BusquedaPorContenido {
+    /** La carpeta REAL de artefactos, donde están la captura que se juzga y las originales. */
+    carpetaDeArtefactos: string;
+    decodificar: (bytes: Buffer) => ImagenRgba;
+}
+/** La geometría de otra captura con los mismos píxeles que ésta, o `undefined`. Nunca lanza. */
+export declare function geometriaPorContenido(carpetaDeHotswap: string, nombreDeCaptura: string, busqueda: BusquedaPorContenido): unknown;
+export declare function geometriaDeCaptura(carpetaDeHotswap: string, nombreDeCaptura: string, busqueda?: BusquedaPorContenido): Promise<unknown>;

package/dist/agent/dispositivos/hotswap.d.ts

@@ -0,0 +1,194 @@
+/** La URL por omisión: el puerto de fábrica, con el `adb forward` hecho. */
+export declare const DESTINO_POR_OMISION = "wss://127.0.0.1:8443/hotswap";
+/**
+ * Cuánto se espera al saludo antes de dar el canal por muerto.
+ *
+ * No es un plazo para la app: es para el SERVIDOR, que está dentro del proceso host y saluda en
+ * cuanto acepta el socket. Quince segundos es de sobra para un túnel de `adb` en loopback, y
+ * seguir esperando deja el turno parado sin nada que lo explique.
+ */
+export declare const TOPE_DE_SALUDO_MS = 15000;
+/**
+ * Y hasta cuándo se sigue INTENTANDO abrir el canal, contando desde el primer intento.
+ *
+ * **No es lo mismo que `TOPE_DE_SALUDO_MS`, y por eso hay dos.** Aquél mide un socket ABIERTO que
+ * no saluda; éste, un socket que no llega a abrirse — que es lo que se mide tras reiniciar el
+ * framework (ver la cabecera del módulo). Confundirlos deja el lanzamiento muriendo con la línea
+ * de TLS mientras el framework arranca detrás.
+ *
+ * El mismo minuto que la espera de la app: las dos preguntan lo mismo —cuánto tarda el aparato en
+ * llegar— sobre dos momentos distintos, y sesenta segundos son de sobra para una pantalla que
+ * arranca. El tope es del BUCLE y no de cada intento, así que uno que se quede esperando el saludo
+ * puede añadir su `TOPE_DE_SALUDO_MS` por encima.
+ */
+export declare const TOPE_DE_APERTURA_MS = 60000;
+/**
+ * Cada cuánto se vuelve a preguntar: por el canal que aún no abre, y por la app que aún no está
+ * en pie.
+ *
+ * Un solo número para las dos esperas porque son la misma idea —volver a preguntar en vez de
+ * dormir un rato fijo— y porque miden lo mismo: unos segundos de un aparato arrancando.
+ */
+export declare const INTERVALO_DE_SONDEO_MS = 1000;
+/**
+ * Y hasta cuándo, después de lanzarla.
+ *
+ * Se sondea con intervalo en vez de dormir un rato fijo por dos motivos, y son las dos caras
+ * del mismo error: un temporizador fijo o MIENTE por corto —diciendo que no arrancó algo que
+ * estaba arrancando— o hace perder un minuto entero en cada despliegue que va bien. Lo que
+ * decide es la medida, y en cuanto llega se para.
+ */
+export declare const TOPE_DE_ARRANQUE_MS = 60000;
+/**
+ * Cada cuánto se le VUELVE A PEDIR el lanzamiento mientras la lectura diga que la app no está.
+ *
+ * Existe por una medida, y es la que hacía fallar la pestaña entera: **el primer
+ * `launchApplication` que llega con el framework recién reiniciado se acepta con
+ * `{"result":true}` y no arranca nada.** Medido con los MISMOS bytes de ZIP en las dos
+ * direcciones: mandándolo una sola vez, doce lecturas seguidas dicen `App is not running` durante
+ * los 60 s del tope; volviéndolo a pedir cada 5 s, hay árbol a los dos o tres segundos del
+ * segundo o tercer envío. Las cuatro tiradas buenas de esa sesión se pusieron vivas **justo
+ * detrás de un reenvío**, y ninguna se puso viva sin él.
+ *
+ * **Solo se reenvía con la lectura DICIENDO que no está**, y eso no es prudencia: reenviar sobre
+ * una app viva la TUMBA —`MainEntry.finishApp()` → `closeApplication` → `Terminating and
+ * disposing appData`—, medido como un ciclo de viva/muerta cada 5 s. El bucle de abajo solo llega
+ * a esta línea cuando la lectura acaba de decir que no hay app, así que la propiedad se sostiene
+ * por construcción y no por un `if` que alguien pueda quitar.
+ *
+ * Cinco segundos y no uno: es el intervalo con el que se midió, y preguntar más a menudo no
+ * adelanta nada —lo que arranca la app es un envío POSTERIOR, no la prisa—.
+ */
+export declare const INTERVALO_DE_REENVIO_MS = 5000;
+/**
+ * La respuesta del framework, tal cual llegó. Sin interpretar: `result` es suyo y `status` es
+ * donde viene el motivo —y, en `getAllElements`, el árbol entero como JSON—.
+ */
+export interface RespuestaHotswap {
+    /** El `result` del framework. `false` es un NO suyo, no un fallo de transporte. */
+    result?: unknown;
+    /**
+     * El `status`. Es SIEMPRE una cadena, también cuando lleva dentro un JSON: es el
+     * `ResultMessage(string)` documentado, el mismo molde que usan `getCurrentScreen` y `getRows`.
+     */
+    status?: string;
+    [clave: string]: unknown;
+}
+/**
+ * El trozo del socket que este módulo usa, y nada más.
+ *
+ * Es estructural a propósito: así el doble de un test no tiene que parecerse a `ws` en nada que
+ * no se use, y una versión mayor de `ws` que mueva lo demás no toca aquí.
+ */
+export interface SocketHotswap {
+    on: (evento: "message" | "error" | "close", cb: (valor: never) => void) => void;
+    send: (texto: string) => void;
+    close: () => void;
+}
+/** Cómo se abre el socket. Entra por parámetro: `npm test` no abre ninguno. */
+export type AbrirSocketHotswap = (url: string) => SocketHotswap;
+export interface DependenciasDeHotswap {
+    /** El constructor del socket de verdad. Sin él se usa `ws`. */
+    abrirSocket?: AbrirSocketHotswap;
+    /**
+     * La URL del canal. Gana la posicional de `abrirHotswap`; esto existe porque
+     * `lanzarYComprobar` no tiene dónde ponerla —su segundo parámetro son las dependencias— y es
+     * quien conoce el puerto, que no siempre es el 8443 de fábrica.
+     */
+    destino?: string;
+    /** Cada línea, tal cual. Es lo que permite decir «el framework contestó esto» sin adivinar. */
+    alLinea?: (linea: string) => void;
+}
+export interface ClienteHotswap {
+    /**
+     * Manda un comando y espera SU respuesta. Antes espera el saludo: no sale nada por el socket
+     * hasta que el servidor ha hablado.
+     */
+    comando(nombre: string, extra?: Record<string, unknown>): Promise<RespuestaHotswap>;
+    /** Cierra el canal. Idempotente: se llama en un `finally`, y también desde el propio fallo. */
+    cerrar(): void;
+    /**
+     * Espera el saludo del servidor. Se resuelve con el `server_hello`, y falla con UNA línea si el
+     * canal se cerró antes o si no llegó en `TOPE_DE_SALUDO_MS`.
+     *
+     * Es un MÉTODO y no un campo a propósito: `comando` ya espera el saludo por dentro, así que
+     * quien no necesite esperarlo aparte no toca esta promesa — y una promesa que rechaza sin nadie
+     * mirándola tumba el proceso. Quien la pida, que la pida en el acto: es lo que hace
+     * `abrirConReintento`, que la pide antes de soltar el hilo.
+     */
+    esperarSaludo(): Promise<void>;
+    /** Cada línea, tal cual llegue. Se registra al abrir y antes de mandar nada. */
+    alLinea(escucha: (linea: string) => void): void;
+}
+/**
+ * Abre el canal y devuelve el cliente.
+ *
+ * No es `async` a propósito: quien la llama quiere el cliente para poder REGISTRAR su log
+ * antes de que llegue nada, y el saludo —que sí es asíncrono— se espera dentro de `comando`.
+ */
+export declare function abrirHotswap(destino: string, deps?: DependenciasDeHotswap): ClienteHotswap;
+/**
+ * ¿Saluda el servidor del framework? `undefined` si sí; si no, UNA línea con el motivo. Nunca lanza.
+ *
+ * Existe porque **la subida del despliegue va por el servidor del FRAMEWORK**, y antes del reinicio:
+ * medido, con el framework parado (`am force-stop`) Ejecutar moría en «subiendo» con «Client network
+ * socket disconnected before secure TLS…», porque el túnel acepta y no hay nadie detrás. Con
+ * `reintentar` se espera a que arranque (`abrirConReintento`, el MISMO tope que tras el reinicio);
+ * sin él, se pregunta una vez, que es lo que hace falta para decidir si hay que arrancarlo.
+ */
+export declare function esperarAlServidor(destino: string, deps: DependenciasDeHotswap | undefined, { reintentar }: {
+    reintentar: boolean;
+}): Promise<string | undefined>;
+/**
+ * Lanza la app y COMPRUEBA que está viva.
+ *
+ * Las dos partes están separadas a propósito porque son dos hechos distintos: el acuse de
+ * `launchApplication` dice que el framework aceptó el encargo, y el árbol de `getAllElements`
+ * dice que hay una app delante. Medido: lo primero es `true` aunque lo segundo no llegue nunca.
+ *
+ * **La conexión se reintenta** (`abrirConReintento`) porque un socket que no abre no es un
+ * veredicto sobre la app: recién reiniciado el framework, el canal tarda unos segundos en
+ * existir.
+ *
+ * **Y el lanzamiento se VUELVE A PEDIR** mientras la lectura diga que no está
+ * (`INTERVALO_DE_REENVIO_MS`): el primer envío tras un reinicio en frío se acepta y no arranca
+ * nada, así que mandarlo una sola vez y esperar sesenta segundos es esperar a un encargo que el
+ * framework ya tiró. La regla que lo hace seguro es que solo se reenvía detrás de una lectura que
+ * dice «no está»: sobre una app viva, un segundo `launchApplication` la tumba.
+ *
+ * **Nunca lanza**: todo —el saludo que no llega, el socket que revienta, un `Unknown command`—
+ * vuelve como `{viva, motivo}` de una línea. Quien la llama está atendiendo algo que puede
+ * contar en una pantalla, y un fallo del dispositivo no es una excepción del programa.
+ *
+ * Y `cerrar()` va en un `finally`, también en el camino de fallo: un socket vivo contra un
+ * emulador que se queda abierto en cada intento es una fuga que no da ningún síntoma hasta que
+ * se acumula.
+ */
+export declare function lanzarYComprobar(app: string, deps?: DependenciasDeHotswap): Promise<ArranqueDeApp>;
+export interface ArranqueDeApp {
+    viva: boolean;
+    /**
+     * UNA línea: la respuesta literal del framework, sin traducir. **Ausente si está viva** — el
+     * mismo molde que `ResultadoDeTrabajo`: `motivo` es para lo que falló, y una app viva no
+     * falló. Lo que prueba que está viva viaja en `respuesta`, no aquí.
+     */
+    motivo?: string;
+    /** La última respuesta leída, entera. Es la MEDIDA: un `result:true` no lo es. */
+    respuesta?: RespuestaHotswap;
+}
+/**
+ * El veredicto de vida, en UN sitio.
+ *
+ * Vale si el framework no ha dicho que no, si no ha dicho ninguna de las dos frases con las que
+ * dice que todavía no hay app delante, y si lo que trae es de verdad un ÁRBOL.
+ *
+ * Lo del árbol no es un adorno, es la parte que impide el falso positivo: `getAllElements` mete
+ * su payload —el array de descriptores— como JSON dentro de `status`, así que cualquier otra
+ * cosa que llegue por ahí (otro error, una cadena vacía, un objeto suelto) NO es una app viva.
+ * Conformarse con «hay algo en `status`» convertiría un error desconocido en un visto bueno,
+ * que es el diagnóstico falso más caro de todos porque no da ningún síntoma.
+ *
+ * Y un árbol VACÍO sí está vivo: el `[]` lo contesta una pantalla con un diálogo modal delante
+ * —lo de debajo está tapado y no se publica—, que es una app en pie, no una app muerta.
+ */
+export declare function estaViva(respuesta: RespuestaHotswap): boolean;

package/dist/agent/dispositivos/instalacionEnMaquina.d.ts

@@ -0,0 +1,156 @@
+import { lanzarReal, TOPE_DE_TRABAJO_MS, TOPE_SIN_SALIDA_MS, type Lanzar, type ProcesoHijo } from "./procesosEnMaquina.js";
+/**
+ * Y esto se REEXPORTA: lo que este módulo exportaba antes de que existiera el ejecutor
+ * compartido lo sigue exportando, pero ahora hay UNA sola copia —el `spawn` con `detached`, los
+ * dos topes y el hijo—, y la comparten la receta y el lanzamiento en el dispositivo
+ * (`procesosEnMaquina.ts`). Un segundo `spawn` allí era un segundo sitio donde el `detached`
+ * podía dejar de estar.
+ */
+export { lanzarReal, TOPE_DE_TRABAJO_MS, TOPE_SIN_SALIDA_MS, type Lanzar, type ProcesoHijo };
+/** Una llamada a un proceso dentro de un paso. Un paso puede ser varias, en orden. */
+interface Invocacion {
+    args: string[];
+    /** Lo que se le escribe por `stdin`; sin TTY, un prompt sin respuesta cuelga el proceso. */
+    teclear: string[];
+    /** Cuántas veces se repite el tecleo. Las licencias del SDK son una pregunta por licencia. */
+    repetir?: number;
+    /**
+     * Un fallo aquí NO corta el paso. Hoy solo las licencias: si ya estaban aceptadas,
+     * `--licenses` puede salir con código distinto de cero y la instalación funciona igual.
+     */
+    opcional?: boolean;
+    /** Lo que se dice en el log antes de lanzarla, si hay algo que declarar. */
+    anuncio?: string;
+}
+/**
+ * Lo que hace falta para lanzar un paso: o un PROCESO (lo que ya había: un binario, con qué
+ * llamadas y qué se le teclea) o una DESCARGA (nueva, para Windows: adb/JDK/cmdline-tools no
+ * tienen un Homebrew equivalente que los instale de un tirón, así que se bajan de una URL
+ * fijada y se descomprimen). Las dos comparten el mismo resultado final
+ * (`"ok"|"fallo"|"cancelada"|"colgada"`), así que `correrPasoDeReceta` las trata como la
+ * MISMA cosa de cara a quien pregunta por el cable.
+ */
+type PasoEjecutable = PasoDeProceso | PasoDeDescarga;
+interface PasoDeProceso {
+    tipo: "proceso";
+    /** El binario, por nombre. Tabla cerrada: del cliente llega un NÚMERO, nunca un comando. */
+    binario: "sdkmanager" | "avdmanager" | "brew";
+    /**
+     * ¿Necesita el SDK de Android y un JDK?
+     *
+     * El paso que los INSTALA no puede exigirlos —era el `if` que dejaba al paso 1 sin poder
+     * existir— así que esto es lo que separa «lánzalo dentro del SDK, con su entorno» de
+     * «búscalo en el PATH y lánzalo a secas».
+     */
+    conSdk: boolean;
+    /** Dentro del SDK, si no está en el PATH. Solo con `conSdk`. */
+    subcarpeta?: string;
+    invocaciones: Invocacion[];
+    /** Variables extra para el hijo, encima de las del entorno. */
+    entornoExtra?: Record<string, string>;
+    /** Qué se enseña como título del trabajo. */
+    titulo: string;
+}
+interface PasoDeDescarga {
+    tipo: "descarga";
+    url: string;
+    /** Dónde cae, relativo a `%LOCALAPPDATA%` — la única raíz que Windows garantiza y que
+     *  `RAICES_DE_SDK_POR_OMISION.win32` ya usa para el SDK. */
+    destinoBajoLocalAppData: string[];
+    /** Ver `descargaDeHerramientas.ts#OpcionesDeDescarga`. */
+    renombrarCarpetaUnicaA?: string;
+    titulo: string;
+}
+/**
+ * Los pasos que xonecode lanza él. Tabla CERRADA y por `receta:plataforma:paso`: lo que
+ * llega del cliente es un número, y un número que no esté aquí no lanza nada.
+ *
+ * **La PLATAFORMA es parte de la clave**, y no un detalle: los pasos 1-3 de Windows
+ * (descargas) y los 1-3 de macOS (Homebrew) son acciones completamente distintas bajo el
+ * MISMO número — sin la plataforma en la clave, la entrada de una pisaría a la otra en este
+ * mapa, o habría que inventar números que no significan nada en la receta que se enseña.
+ *
+ * Tiene que coincidir con lo que `core/dispositivos.ts` marca `ejecutable` — un paso con
+ * botón que no esté aquí es un botón muerto, y uno lanzable sin botón es una capacidad que
+ * nadie puede usar. Lo ata un test que compara las dos listas.
+ */
+export declare const PASOS_EJECUTABLES: Map<string, PasoEjecutable>;
+/**
+ * Los dos topes —el del silencio, 5 min, y el total, 60— viven con el ejecutor
+ * (`procesosEnMaquina.ts`), que es quien los arma: son la misma regla sobre el mismo tipo de
+ * proceso, y aquí se reexportan. **El silencio es el síntoma, no la lentitud**: mientras el
+ * hijo diga algo se le espera lo que haga falta; lo que no es normal es que se calle, y eso es
+ * un prompt esperando a alguien que no está.
+ */
+export interface ResultadoDeTrabajo {
+    estado: "ok" | "fallo" | "cancelada" | "colgada";
+    /** Una línea, nunca la salida entera. Ausente si fue bien. */
+    motivo?: string;
+    ms: number;
+}
+export interface Trabajo {
+    titulo: string;
+    cancelar: () => void;
+    terminado: Promise<ResultadoDeTrabajo>;
+}
+export interface DependenciasDeInstalacion {
+    plataforma?: string;
+    entorno?: Record<string, string | undefined>;
+    home?: string;
+    existe?: (ruta: string) => boolean;
+    lanzar?: Lanzar;
+    /** Cada línea de salida, en cuanto sale. Es lo único que hace usable un paso de 3 GB. */
+    alSalirLinea?: (linea: string) => void;
+    ahora?: () => number;
+    /**
+     * Matar un GRUPO de procesos. Entra por parámetro porque el real es `process.kill(-pid)`,
+     * y un test que lo llamara de verdad mataría el grupo de quien corre `npm test`.
+     */
+    matarGrupo?: (pid: number, senal: string) => void;
+    /** Solo para los pasos `tipo: "descarga"` — ver `descargaDeHerramientas.ts`. `npm test`
+     *  nunca toca la red real: sin esto un test de un paso de Windows la tocaría. */
+    fetch?: typeof fetch;
+    crearCarpeta?: (ruta: string) => void;
+    escribir?: (ruta: string, datos: Uint8Array) => void;
+    /**
+     * Copiar una carpeta entera filtrando por ruta ABSOLUTA de origen (`clonarAvd`). Entra por
+     * parámetro para que un test vea la cancelación sin una carpeta de gigas de por medio.
+     */
+    copiarCarpeta?: (origen: string, destino: string, filtro: (ruta: string) => boolean) => Promise<void>;
+}
+/**
+ * Lanza el paso `numero` de la receta `receta`, y devuelve el trabajo en curso.
+ *
+ * Nunca lanza: todo lo que puede ir mal —el paso no es ejecutable, falta el SDK, el proceso
+ * no arranca— vuelve como un `ResultadoDeTrabajo` con su motivo de UNA línea. Quien lo llama
+ * está atendiendo una petición del navegador y no puede recibir una excepción por algo que
+ * es una respuesta.
+ */
+export declare function correrPasoDeReceta(receta: string, numero: number, deps?: DependenciasDeInstalacion): Trabajo;
+/**
+ * Crear un AVD con nombre, por el mismo corredor que la receta (topes, stdin, SDK). Nunca lanza.
+ *
+ * Con `base` es el modo CONFIGURACIÓN: la imagen y el perfil salen del `config.ini` de la base
+ * (`avdmanager` los pide), y al acabar BIEN se le pone encima ese mismo `config.ini` para que
+ * herede RAM, disco y el resto. El AVD nuevo arranca vacío; vale con la base encendida.
+ */
+export declare function crearAvd(nombre: string, deps?: DependenciasDeInstalacion, opciones?: {
+    base?: string;
+}): Trabajo;
+/**
+ * Eliminar un AVD por su nombre, por el MISMO corredor que crear (topes, SDK, `JAVA_HOME`):
+ * `avdmanager delete avd -n <nombre>` borra la carpeta y el `.ini`, y no toca la imagen del sistema
+ * ni los demás. El nombre acaba en un argumento, así que pasa por la regla de forma de siempre
+ * (sin `..` ni barras). Nunca lanza. Que sea el último, o que esté en marcha, lo decide quien llama
+ * (la última medida): aquí solo se ve el disco.
+ */
+export declare function borrarAvd(nombre: string, deps?: DependenciasDeInstalacion): Trabajo;
+/**
+ * Modo CLON: copia la carpeta del AVD `base` a `nombre` (lo instalado incluido), sin lo que
+ * `seCopiaEnClon` excluye, y SOLO al acabar bien escribe `<nombre>.ini` —un AVD sin `.ini` no
+ * existe para el emulador, así que una copia a medias nunca aparece en la lista—. Un fallo o una
+ * cancelación BORRAN la carpeta a medias. Nunca lanza. `snapshots/` viaja con la identidad reescrita
+ * (`core/copiaDeAvd.ts`): sin ella un clon pierde lo que el original aún no había volcado al disco. La base tiene que estar apagada: lo comprueba
+ * quien llama (la medida de dispositivos), aquí solo se ve el disco.
+ */
+export declare function clonarAvd(base: string, nombre: string, deps?: DependenciasDeInstalacion): Trabajo;