xonecode 0.5.1 → 0.8.0

package/skills/xone-hotswap/scripts/xone-desplegar-android

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+/**
+ * Poner ESTE proyecto en un Android y dejar la app arrancada. La plantilla completa.
+ *
+ * POR QUÉ EXISTE. «Lanza la app» no es un comando del protocolo hotswap: es una cadena de
+ * cinco pasos, y cuatro de ellos no viajan por el canal (el túnel, el ZIP, la subida HTTP y
+ * el reinicio). El canal solo hace el quinto. Esta plantilla es esa cadena, en el orden en el
+ * que se midió que funciona.
+ *
+ * USO (desde la raíz del proyecto, que es el `cwd` de tus comandos):
+ *   xone-desplegar-android
+ *   xone-desplegar-android --captura
+ *   xone-desplegar-android --app MiApp --serie emulator-5554
+ *
+ * EL ORDEN, Y POR QUÉ ES ESE:
+ *  1. **El túnel primero.** Sin `adb forward`, `127.0.0.1:8443` no lleva a ninguna parte: el
+ *     servidor escucha en el localhost del APARATO. No se quita al terminar — hay que
+ *     reaplicarlo tras cada reconexión, así que quitarlo dejaría el siguiente intento hablando
+ *     con nadie.
+ *  2. **El ZIP**, sin `.xonecode` ni `.git`. No es higiene: el `checkpoint.sqlite` de un
+ *     proyecto real pesaba 122 MB él solo, contra 6,7 MB el proyecto entero.
+ *  3. **La subida.** Subir NO aplica: el proceso tiene cargado en memoria lo de antes.
+ *  4. **El reinicio**, que es lo único que aplica lo subido. Y es `SetupActivity`, **nunca**
+ *     `.mainEntry`: medido, `.mainEntry` no levanta el servidor hotswap.
+ *  5. **El lanzamiento**, y LUEGO la comprobación: `{"result":true}` de `launchApplication`
+ *     significa «aceptado», no «arrancó». Lo que dice si está viva es el árbol de controles,
+ *     que tarda unos segundos en contestar algo.
+ *
+ * LA TRAMPA QUE CUESTA UNA SESIÓN: **sin `bd/gestion.db` la app no arranca** y el verificador
+ * estático dice VERDE igual. El `app.xml` declara `<connection connstring="bd/gestion.db"/>` y
+ * esa base se genera FUERA (XOne Studio o `xone-db-tools create-db`). Si la app muere con
+ * «Error opening database», mira eso antes que nada.
+ *
+ * LO QUE NECESITA: `adb` en el PATH, y nada más. El ZIP se construye aquí dentro con `zlib`
+ * —ni binario externo ni dependencias—, así que esto no depende de que haya un `zip` en el
+ * sistema, que en Windows no lo hay.
+ */
+process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+// Y se calla SU aviso, no todos: node grita en cada arranque que la verificación está
+// desactivada, y ese grito acaba en la salida del comando —o sea en el contexto del agente—
+// invitándole a «arreglar» algo que es deliberado y está acotado a este proceso hijo.
+process.removeAllListeners("warning");
+process.on("warning", (aviso) => {
+  if (!String(aviso.message).includes("NODE_TLS_REJECT_UNAUTHORIZED")) console.warn(aviso);
+});
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+import { deflateRawSync } from "node:zlib";
+
+const PAQUETE = "com.xone.android.framework";
+const ACTIVIDAD = `${PAQUETE}/com.xone.android.hotswap.activities.SetupActivity`;
+const PUERTO = 8443;
+
+/**
+ * Un ZIP en memoria, sin `zip` del sistema y sin dependencias.
+ *
+ * Se escribió a mano por dos razones, y ninguna es el gusto por reinventar: **en Windows no
+ * hay `zip`**, así que llamar al binario dejaba esta plantilla sirviendo en dos sistemas de
+ * tres; y una skill instalada en la casa del usuario no tiene `node_modules` donde resolver
+ * una librería. Con `zlib`, que viene con node, no hace falta ninguna de las dos cosas.
+ *
+ * Es el formato mínimo y suficiente: entradas DEFLATE con cabecera local, directorio central y
+ * su cola. Sin ZIP64 —un proyecto XOne no llega a 4 GB ni a 65.535 ficheros— y sin atributos de
+ * Unix, que el framework no mira.
+ */
+const TABLA_CRC = (() => {
+  const tabla = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    tabla[i] = c >>> 0;
+  }
+  return tabla;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = TABLA_CRC[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** Los ficheros del proyecto, en rutas relativas con `/`, saltándose lo que no sube. */
+function ficherosDe(raiz, fuera, dentro = raiz, salida = []) {
+  for (const entrada of readdirSync(dentro, { withFileTypes: true })) {
+    const completa = join(dentro, entrada.name);
+    const rel = relative(raiz, completa).split(sep).join("/");
+    if (fuera.some((f) => rel === f || rel.startsWith(`${f}/`))) continue;
+    // No se sigue un enlace: un symlink a una carpeta de fuera metería el disco entero.
+    if (entrada.isSymbolicLink()) continue;
+    if (entrada.isDirectory()) ficherosDe(raiz, fuera, completa, salida);
+    else if (entrada.isFile()) salida.push(rel);
+  }
+  return salida;
+}
+
+function crearZip(raiz, fuera) {
+  const locales = [];
+  const central = [];
+  let desplazamiento = 0;
+
+  for (const rel of ficherosDe(raiz, fuera)) {
+    const datos = readFileSync(join(raiz, rel));
+    const comprimido = deflateRawSync(datos);
+    const nombre = Buffer.from(rel, "utf8");
+    const suma = crc32(datos);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // versión mínima
+    local.writeUInt16LE(0x0800, 6); // nombres en UTF-8
+    local.writeUInt16LE(8, 8); // deflate
+    local.writeUInt32LE(suma, 14);
+    local.writeUInt32LE(comprimido.length, 18);
+    local.writeUInt32LE(datos.length, 22);
+    local.writeUInt16LE(nombre.length, 26);
+    locales.push(local, nombre, comprimido);
+
+    const entrada = Buffer.alloc(46);
+    entrada.writeUInt32LE(0x02014b50, 0);
+    entrada.writeUInt16LE(20, 4);
+    entrada.writeUInt16LE(20, 6);
+    entrada.writeUInt16LE(0x0800, 8);
+    entrada.writeUInt16LE(8, 10);
+    entrada.writeUInt32LE(suma, 16);
+    entrada.writeUInt32LE(comprimido.length, 20);
+    entrada.writeUInt32LE(datos.length, 24);
+    entrada.writeUInt16LE(nombre.length, 28);
+    entrada.writeUInt32LE(desplazamiento, 42);
+    central.push(entrada, nombre);
+
+    desplazamiento += local.length + nombre.length + comprimido.length;
+  }
+
+  const cuerpoCentral = Buffer.concat(central);
+  const cola = Buffer.alloc(22);
+  const cuantos = central.length / 2;
+  cola.writeUInt32LE(0x06054b50, 0);
+  cola.writeUInt16LE(cuantos, 8);
+  cola.writeUInt16LE(cuantos, 10);
+  cola.writeUInt32LE(cuerpoCentral.length, 12);
+  cola.writeUInt32LE(desplazamiento, 16);
+  return Buffer.concat([...locales, cuerpoCentral, cola]);
+}
+
+const args = process.argv.slice(2);
+const opcion = (nombre) => {
+  const i = args.indexOf(`--${nombre}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+if (args.includes("--help") || args.includes("-h")) {
+  // **Tiene que existir**, y esto no es cortesía: sin `--help` esta orden DESPLEGABA, así que
+  // un agente que la usa para orientarse lanzaba el proceso entero creyendo que preguntaba —
+  // medido, lo repitió 75 veces en un turno. Una opción que no se entiende no puede ejecutar.
+  console.error(`xone-desplegar-android — pone ESTE proyecto en un Android y deja la app arrancada.
+
+  xone-desplegar-android                       nombre de app tomado de app.xml
+  xone-desplegar-android --app MiApp           nombre explícito
+  xone-desplegar-android --serie emulator-5554 con varios aparatos conectados
+
+Hace la cadena entera: túnel adb, ZIP del proyecto (sin .xonecode ni .git), subida, reinicio del
+framework y lanzamiento, y COMPRUEBA que la app esté viva pidiendo su árbol de controles.
+Necesita \`adb\` en el PATH; el ZIP lo construye él mismo.
+
+Si la app no arranca, lo primero que hay que mirar es si existe bd/gestion.db: la genera XOne
+Studio o \`xone-db-tools\`, no esto, y sin ella la app muere aunque el verificador esté en verde.`);
+  process.exit(0);
+}
+
+const serie = opcion("serie");
+const adb = (...partes) =>
+  execFileSync("adb", [...(serie ? ["-s", serie] : []), ...partes], { encoding: "utf8" });
+
+/**
+ * Igual, pero sin dejar hablar al hijo por stderr.
+ *
+ * `execFileSync` hereda stderr por omisión, así que un `pm grant` de un permiso que no es de
+ * ejecución escupe una traza de Java entera. Con 63 permisos declarados eso son decenas de
+ * pantallas de ruido que acaban en el contexto del agente y le hacen creer que algo se rompió.
+ */
+const adbCallado = (...partes) =>
+  execFileSync("adb", [...(serie ? ["-s", serie] : []), ...partes], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/**
+ * Cómo se llama la app, en tres saltos y con el último declarado.
+ *
+ * **El `<app>` de un proyecto XOne real NO lleva `name`** — medido sobre cuatro proyectos del
+ * usuario: lleva `prefix`, `version`, `debug`… y nada más. Leerlo de ahí fue el primer intento y
+ * falla en todos menos en los de juguete. Donde sí está, cuando está, es en `app.ini`
+ * (`name=AppDemo`); y varios proyectos reales ni siquiera tienen `app.ini`.
+ *
+ * Por eso el último salto es **la carpeta**, que es lo que una persona usaría y lo que casa con
+ * cómo guarda el framework lo que sube (`app_<nombre en minúsculas>`). Se DICE cuál se usó, para
+ * que quien mire la salida pueda corregir con `--app` en vez de descubrirlo por el resultado.
+ */
+function nombreDeLaApp() {
+  const dicho = opcion("app");
+  if (dicho !== undefined) return dicho;
+
+  if (existsSync("app.ini")) {
+    const m = /^\s*name\s*=\s*(.+?)\s*$/im.exec(readFileSync("app.ini", "latin1"));
+    if (m !== null && m[1] !== "") {
+      console.log(`    nombre de app.ini: ${m[1]}`);
+      return m[1];
+    }
+  }
+
+  const deLaCarpeta = basename(process.cwd());
+  console.log(`    nombre de la carpeta: ${deLaCarpeta} (usa --app si no es ése)`);
+  return deLaCarpeta;
+}
+
+/**
+ * Concede los permisos de ejecución que el host pide, antes de reiniciarlo.
+ *
+ * **Sin esto la app no arranca y el síntoma engaña.** Medido: tras el reinicio, Android pone
+ * encima su `GrantPermissionsActivity` y la app se queda detrás esperando a que alguien toque
+ * «Permitir». El canal deja de contestar y el mensaje honesto —«no llegó a contestar el árbol»—
+ * manda a mirar la base de datos, que estaba perfectamente. O sea: un diálogo del SISTEMA
+ * disfrazado de app rota.
+ *
+ * Es lo mismo que hace `adb install -g`, y sobre un aparato de PRUEBAS es lo razonable: lo que
+ * se está automatizando es pulsar «Permitir» quince veces. Se conceden solo los que el paquete
+ * DECLARA —se leen del aparato, no de una lista nuestra que caducaría con la siguiente versión
+ * del framework— y los que no son de ejecución fallan uno a uno sin parar nada.
+ */
+function concederPermisos() {
+  let declaradas;
+  try {
+    const volcado = adb("shell", "dumpsys", "package", PAQUETE);
+    const trozo = /requested permissions:([\s\S]*?)(?:install permissions:|runtime permissions:|$)/.exec(volcado);
+    declaradas = (trozo?.[1] ?? "").split("\n").map((l) => l.trim().split(":")[0]).filter((l) => l.startsWith("android.permission."));
+  } catch {
+    console.log("    no se pudo leer qué permisos pide; sigo");
+    return;
+  }
+  let dados = 0;
+  for (const permiso of declaradas) {
+    try {
+      adbCallado("shell", "pm", "grant", PAQUETE, permiso);
+      dados += 1;
+    } catch {
+      // Los que no son de ejecución (`INTERNET`, `FOREGROUND_SERVICE`…) no se conceden así y
+      // fallan uno a uno. No es un error: es que no había nada que conceder.
+    }
+  }
+  console.log(`    ${dados} permiso(s) concedido(s) de ${declaradas.length} declarado(s)`);
+}
+
+/**
+ * La excepción de XOne de ESTE arranque, en las cuatro líneas que importan, o nada.
+ *
+ * Se lee del log y no de la pantalla porque el diálogo enseña el mensaje recortado y sin el
+ * fichero ni la línea; el log trae `Source`, `Cause`, `Line number` y `In include file`, que es
+ * lo que deja ir directo al sitio. Se piden pocas líneas: lo que se busca está al principio del
+ * arranque, y un volcado grande aquí sería ruido en la salida de un comando.
+ */
+function excepcionDeXOne() {
+  let log;
+  try {
+    log = adbCallado("logcat", "-d", "-t", "600");
+  } catch {
+    return undefined;
+  }
+  const filas = log.split("\n");
+  const donde = filas.findIndex((l) => l.includes("XOneJavascriptException"));
+  if (donde < 0) return undefined;
+  // Desde la excepción, lo que viene detrás es su descripción: fuente, causa, línea y fichero.
+  const utiles = filas
+    .slice(donde, donde + 12)
+    .map((l) => l.replace(/^.*?\bSystem\.err:\s?/, "").trim())
+    .filter((l) => l !== "" && !l.startsWith("at "));
+  return utiles.slice(0, 6).join("\n");
+}
+
+const app = nombreDeLaApp();
+
+{
+/**
+ * Sin aparato NO se empieza, y se dice el siguiente paso HECHO.
+ *
+ * Antes el primer `adb forward` moría con «no devices/emulators found», que es cierto y no
+ * dice qué hacer: medido, el modelo se ponía a componer el arranque a mano —y `emulator` no
+ * está en el PATH—. Es la regla de `porQueNo`: cuando sabemos la salida, se escribe, no se
+ * aconseja.
+ */
+function exigirAparato() {
+  let lista = "";
+  try {
+    lista = execFileSync("adb", ["devices"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch (error) {
+    console.error(`no pude hablar con adb: ${error.message.split("\n")[0]}`);
+    process.exit(1);
+  }
+  const hay = lista
+    .split(/\r?\n/)
+    .slice(1)
+    .some((l) => /\sdevice$/.test(l.trim()));
+  if (!hay) {
+    console.error("no hay ningún aparato conectado. Arranca el emulador primero:");
+    console.error("  xone-arrancar-android");
+    process.exit(1);
+  }
+}
+
+  exigirAparato();
+  console.log(`1/5 túnel: ${PUERTO}`);
+  adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO}`);
+
+  console.log("2/5 empaquetando el proyecto (sin .xonecode ni .git)");
+  const cuerpo = crearZip(process.cwd(), [".xonecode", ".git"]);
+  console.log(`    ${(cuerpo.length / 1024).toFixed(0)} KB`);
+
+  console.log(`3/5 subiendo a ${app}`);
+  const url = `https://127.0.0.1:${PUERTO}/file_upload?file=debug_app_update.zip&appName=${encodeURIComponent(app)}`;
+  const respuesta = await fetch(url, {
+    method: "POST",
+    body: cuerpo,
+    headers: { "Content-Type": "application/octet-stream", "Content-Length": String(cuerpo.length) },
+  });
+  if (!respuesta.ok) {
+    console.error(`la subida falló con ${respuesta.status}`);
+    process.exit(1);
+  }
+
+  console.log("4/5 permisos y reinicio del framework");
+  concederPermisos();
+  // El buffer se vacía ANTES de reiniciar para que lo que se lea después sea de ESTE arranque
+  // y no la excepción del intento anterior — que es la forma más fácil de «arreglar» algo y
+  // creerse que sigue roto, o al revés.
+  try {
+    adbCallado("logcat", "-c");
+  } catch {
+    // Si no se puede vaciar, se sigue: el diagnóstico será menos preciso, no falso.
+  }
+  adb("shell", "am", "force-stop", PAQUETE);
+  adb("shell", "am", "start", "-n", ACTIVIDAD);
+
+  console.log("5/5 esperando al canal, lanzando y comprobando que está VIVA");
+  const cliente = join(import.meta.dirname, "xone-hotswap");
+  const mandar = (comando) =>
+    execFileSync("node", [cliente, JSON.stringify(comando)], { encoding: "utf8" }).trim();
+  const esperar = (segundos) => execFileSync("sleep", [String(segundos)]);
+
+  /**
+   * **El canal no está en pie justo después del reinicio**, y esto se descubrió corriéndolo:
+   * el `am start` vuelve en cuanto Android acepta el intent, no cuando el servidor escucha,
+   * así que el primer intento moría con «Received network error or non-101 status code».
+   * Se espera a que CONTESTE, que es la condición de verdad, en vez de dormir un rato fijo.
+   */
+  let listo = false;
+  for (let intento = 1; intento <= 15 && !listo; intento++) {
+    try {
+      mandar({ command: "launchApplication", appName: app });
+      listo = true;
+    } catch {
+      esperar(1);
+    }
+  }
+  if (!listo) {
+    console.error(`el servidor hotswap no levantó tras el reinicio. Comprueba que ${PAQUETE} está instalado`);
+    console.error("y que el puerto es el 8443 (si estaba ocupado, el framework coge el siguiente libre).");
+    process.exit(1);
+  }
+
+  // El árbol es la comprobación: `result:true` solo dice que el encargo se aceptó. Se
+  // reintenta porque la app tarda unos segundos en tener pantalla, y se espera a una
+  // CONDICIÓN y no a un número fijo de segundos.
+  for (let intento = 1; intento <= 10; intento++) {
+    const salida = mandar({ command: "getAllElements", format: "xone" });
+    if (!salida.includes("App is not running")) {
+      console.log(salida);
+      /**
+       * **La captura en la MISMA orden, porque lo que se paga es la ida y vuelta.** Medido: un
+       * «lanza la app y sácame una captura» costaba 17 llamadas al modelo, y cada una reenvía
+       * el historial entero — mientras que lo que devuelve cada comando es pequeño (1,6 KB el
+       * árbol, 108 bytes la captura). O sea que el gasto no es lo que se dice, es cuántas veces
+       * hay que volver a preguntar. Tres órdenes encadenadas por el modelo son tres viajes;
+       * ésta es una.
+       */
+      if (args.includes("--captura")) {
+        try {
+          console.log(mandar({ command: "getScreenshot" }));
+        } catch {
+          console.error("la app arrancó pero la captura falló; el árbol de arriba sí es bueno.");
+        }
+      }
+      // **Estar VIVA no es estar BIEN.** Una app que revienta al cargar la configuración se
+      // queda con su diálogo de error delante, y el canal contesta igual: el árbol llega, la
+      // captura sale, y todo parece haber ido bien. Quien lo cuenta es el log, y no pedirlo
+      // aquí obliga a que alguien se acuerde de hacerlo — que es justo lo que no pasa.
+      const roto = excepcionDeXOne();
+      if (roto !== undefined) {
+        console.error("");
+        console.error("La app ARRANCÓ pero XOne lanzó una excepción al cargar:");
+        console.error(roto);
+        console.error("");
+        console.error("El runtime de XOne es ES5 (Rhino): nada de `let`, `const`, `=>` ni comas");
+        console.error("sobrantes, y una `var` no se puede declarar dos veces en la misma función.");
+        process.exit(1);
+      }
+      process.exit(0);
+    }
+    esperar(2);
+  }
+  console.error("la app no llegó a contestar el árbol de controles: NO está viva.");
+  // **Lo primero, la excepción**, y antes que cualquier consejo: si XOne reventó al cargar, eso
+  // es la respuesta entera y todo lo demás sobra. Aquí hace MÁS falta que en la rama de «está
+  // viva»: una app que no llega a arrancar no tiene pantalla que mirar ni árbol que pedir, así
+  // que sin esto lo único que queda es adivinar.
+  const roto = excepcionDeXOne();
+  if (roto !== undefined) {
+    console.error("");
+    console.error("XOne lanzó una excepción al cargar:");
+    console.error(roto);
+    console.error("");
+    console.error("El motor JS de XOne en Android es Rhino: un error de sintaxis en un fichero");
+    console.error("incluido para la app ENTERA. Mira el `;` al final de cada sentencia, las comas");
+    console.error("sobrantes y las `var` declaradas dos veces en la misma función.");
+    process.exit(1);
+  }
+  // Antes de mandar a mirar la base de datos, se mira QUÉ hay en pantalla: un diálogo del
+  // sistema encima es el falso culpable más caro de este bucle.
+  try {
+    const foco = adb("shell", "dumpsys", "window").split("\n").find((l) => l.includes("mCurrentFocus")) ?? "";
+    if (foco.trim() !== "") console.error(`En pantalla ahora: ${foco.trim()}`);
+    if (foco.includes("permissioncontroller")) {
+      console.error("Hay un diálogo de PERMISOS de Android encima: la app está detrás, esperando.");
+      console.error("Vuelve a intentarlo; si insiste, contéstalo en el aparato.");
+      process.exit(1);
+    }
+  } catch {
+    // Si no se puede preguntar, se sigue con el consejo de siempre.
+  }
+  console.error("Lo primero que hay que mirar es si existe bd/gestion.db (la genera XOne Studio, no esto).");
+  process.exit(1);
+}

package/skills/xone-hotswap/scripts/xone-hotswap

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * El canal de comandos del servidor hotswap, desde la línea de órdenes.
+ *
+ * POR QUÉ EXISTE ESTE FICHERO. Los comandos del servidor hotswap viajan por un **WebSocket**,
+ * y `curl` no habla WebSocket. En Android 5.0.2.2dev el `POST /command` por HTTP contesta
+ * **404** (eso es del flavor `playStoreDeveloper`, no del standalone), así que sin un cliente
+ * no hay forma de mandar `getAllElements` ni `getScreenshot` desde una shell. Esto es ese
+ * cliente, y por eso vive dentro de la skill: la skill dice QUÉ comandos hay, y esto es con
+ * qué se mandan.
+ *
+ * USO
+ *   node "$XONECODE_SKILL_XONE_HOTSWAP/scripts/hotswap.mjs" '{"command":"getAllElements","format":"xone"}'
+ *   node "$XONECODE_SKILL_XONE_HOTSWAP/scripts/hotswap.mjs" '{"command":"launchApplication","appName":"miapp"}' '{"command":"getScreenshot"}'
+ *
+ * Los comandos se mandan EN ORDEN y cada uno espera la respuesta del anterior.
+ *
+ * ANTES DE LLAMARLO (Android): tiene que estar el túnel, o `127.0.0.1:8443` no lleva a
+ * ninguna parte —el servidor escucha en el localhost del APARATO—:
+ *   adb forward tcp:8443 tcp:8443
+ * En iOS no hay túnel: el simulador comparte la pila de red del Mac.
+ *
+ * VARIABLES
+ *   HOTSWAP_URL          el destino. Por omisión `wss://127.0.0.1:8443/hotswap`.
+ *   XONECODE_ARTEFACTOS  dónde dejar lo binario (una captura). Si no está, se dice y no se
+ *                        guarda: escribirlo en el proyecto sería ensuciar la app del usuario.
+ *   HOTSWAP_TOPE_MS      tope de espera de UNA respuesta. Por omisión 40000.
+ *
+ * LO QUE IMPRIME: una línea JSON por respuesta, en stdout. Una respuesta con un binario
+ * dentro NO se imprime: se guarda a fichero y lo que sale es su nombre y su tamaño. Un
+ * `getScreenshot` son ~57.000 caracteres de base64, y volcarlos en la salida de un comando
+ * es meterlos en el contexto para siempre sin que nadie pueda mirarlos.
+ *
+ * TRES COSAS MEDIDAS contra el framework real (Android 5.0.2.2dev, 16-09-2026), que son las
+ * que hacen que esto funcione y un cliente escrito de memoria no:
+ *  - **El WebSocket vive en `/hotswap`**, no en la raíz: `/`, `/ws`, `/websocket` dan 400.
+ *  - **El servidor habla PRIMERO**: al abrir manda `{"command":"server_hello","protocol_version":2}`.
+ *    Se ESPERA ese saludo antes de mandar nada; no se provoca.
+ *  - **La respuesta llega en `status`**, no en un campo `image`, y una captura viene en
+ *    **JPEG** (`/9j/…`), no en PNG.
+ */
+// El certificado del aparato es autofirmado. Esto vale para ESTE proceso hijo y solo para él
+// —no para el harness—, que es justo por lo que el cliente de xonecode no puede hacerlo así.
+process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+// Y se calla SU aviso, no todos: node grita en cada arranque que la verificación está
+// desactivada, y ese grito acaba en la salida del comando —o sea en el contexto del agente—
+// invitándole a «arreglar» algo que es deliberado y está acotado a este proceso hijo.
+process.removeAllListeners("warning");
+process.on("warning", (aviso) => {
+  if (!String(aviso.message).includes("NODE_TLS_REJECT_UNAUTHORIZED")) console.warn(aviso);
+});
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const URL_POR_OMISION = "wss://127.0.0.1:8443/hotswap";
+const TOPE_MS = Number(process.env.HOTSWAP_TOPE_MS ?? 40_000);
+const ARTEFACTOS = process.env.XONECODE_ARTEFACTOS;
+/**
+ * A partir de aquí una respuesta de TEXTO se guarda en vez de imprimirse.
+ *
+ * No decide si algo es binario —eso lo dice `extensionDe` mirando los bytes—, solo si cabe en
+ * la salida de un comando. El árbol de controles de una pantalla llena son varios miles de
+ * caracteres y volcarlos enteros en el contexto del agente cuesta más que la pregunta.
+ */
+const LARGO_PARA_GUARDAR = 2_000;
+
+const pedidos = process.argv.slice(2);
+if (pedidos.length === 0 || pedidos.includes("--help") || pedidos.includes("-h")) {
+  // El prompt del agente promete que `--help` contesta. Una promesa así, sin cumplir, cuesta
+  // un viaje y deja al modelo adivinando argumentos.
+  console.error(`xone-hotswap — manda comandos al servidor hotswap de la app (WebSocket).
+
+  xone-hotswap '{"command":"getAllElements","format":"xone"}'
+  xone-hotswap '{"command":"getScreenshot"}'           la captura va a $XONECODE_ARTEFACTOS
+  xone-hotswap '{"command":"click","name":"MAP_BT"}'   varios comandos, en orden, si pasas varios
+
+Antes, en Android, hace falta el túnel: adb forward tcp:8443 tcp:8443
+Variables: HOTSWAP_URL (${URL_POR_OMISION}), XONECODE_ARTEFACTOS, HOTSWAP_TOPE_MS.
+El catálogo entero de comandos está en el SKILL.md de xone-hotswap.`);
+  process.exit(pedidos.length === 0 ? 1 : 0);
+}
+
+const comandos = [];
+for (const arg of pedidos) {
+  try {
+    comandos.push(JSON.parse(arg));
+  } catch {
+    salir(`no es JSON válido: ${arg.slice(0, 80)}`);
+  }
+}
+
+
+function salir(motivo) {
+  console.error(`hotswap: ${motivo}`);
+  process.exit(1);
+}
+
+/**
+ * Qué es esto, por sus primeros bytes en base64 — nunca por el nombre del comando.
+ *
+ * **`undefined` significa «no es una imagen», y eso NO es «es binario desconocido».** Era el
+ * bug: cualquier campo de más de 2.000 caracteres se daba por base64 y se pasaba por
+ * `Buffer.from(valor, "base64")`. El árbol de `getAllElements` es JSON de TEXTO, así que en
+ * cuanto una pantalla tiene bastantes controles pasaba de ese largo, se «decodificaba»
+ * —descartando `{`, `"`, `:` y los espacios, que no son del alfabeto base64— y lo que quedaba
+ * en el disco eran unos 3/4 de bytes de basura, con nombre `captura-….bin`. Comprobado contra
+ * el aparato: el fichero real empezaba por `9da9 9e30 03ff` y un árbol JSON pasado por ese
+ * mismo `Buffer.from` empieza exactamente igual. O sea que el agente perdía la pantalla justo
+ * cuando la pantalla tenía algo que contar, y encima creía haber guardado una captura.
+ */
+function imagenDe(base64) {
+  if (base64.startsWith("/9j/")) return "jpg";
+  if (base64.startsWith("iVBORw0KGgo")) return "png";
+  if (base64.startsWith("UklGR")) return "webp";
+  return undefined;
+}
+
+/**
+ * Guarda lo binario y lo sustituye por lo que se puede decir de ello.
+ *
+ * Mira TODOS los campos de la respuesta, no solo `status`: el campo donde viene el binario
+ * ha cambiado entre versiones, y un cliente que solo mire uno se calla justo cuando el
+ * servidor cambia de sitio.
+ */
+function sinBinarios(respuesta) {
+  const copia = { ...respuesta };
+  for (const [clave, valor] of Object.entries(copia)) {
+    if (typeof valor !== "string" || valor.length < LARGO_PARA_GUARDAR) continue;
+    const imagen = imagenDe(valor);
+    if (ARTEFACTOS === undefined) {
+      copia[clave] =
+        imagen === undefined
+          ? `<${valor.length} caracteres; sin XONECODE_ARTEFACTOS no hay dónde guardarlos>`
+          : `<imagen ${imagen} de ${valor.length} car.; sin XONECODE_ARTEFACTOS no hay dónde guardarla>`;
+      continue;
+    }
+    /**
+     * Una imagen se DECODIFICA y se llama captura; lo demás es TEXTO y se guarda tal cual,
+     * con su extensión y con un nombre que dice lo que es. Llamar `captura-` a un árbol de
+     * controles no era solo feo: mandaba a quien lo leyera a buscar una foto.
+     */
+    const nombre =
+      imagen === undefined
+        ? `respuesta-${clave}-${Date.now()}.${valor.trimStart().startsWith("[") || valor.trimStart().startsWith("{") ? "json" : "txt"}`
+        : `captura-${Date.now()}.${imagen}`;
+    const bytes = imagen === undefined ? Buffer.from(valor, "utf8") : Buffer.from(valor, "base64");
+    writeFileSync(join(ARTEFACTOS, nombre), bytes);
+    copia[clave] = `<guardado como ${nombre}, ${bytes.length} bytes>`;
+  }
+  return copia;
+}
+
+const ws = new WebSocket(process.env.HOTSWAP_URL ?? URL_POR_OMISION);
+let saludado = false;
+let pendiente;
+let reloj;
+
+const rearmar = () => {
+  clearTimeout(reloj);
+  reloj = setTimeout(() => salir(`sin respuesta en ${TOPE_MS} ms`), TOPE_MS);
+};
+
+function siguiente() {
+  const comando = comandos.shift();
+  if (comando === undefined) {
+    clearTimeout(reloj);
+    ws.close();
+    process.exit(0);
+  }
+  pendiente = comando;
+  rearmar();
+  ws.send(JSON.stringify(comando));
+}
+
+rearmar();
+ws.onerror = (e) => salir(`no se pudo hablar con el aparato: ${e.message ?? e}`);
+ws.onclose = (e) => {
+  if (pendiente !== undefined || comandos.length > 0) {
+    salir(`el canal se cerró antes de terminar (${e.code} ${e.reason || "sin motivo"})`);
+  }
+};
+ws.onmessage = (ev) => {
+  const texto = typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString();
+  let mensaje;
+  try {
+    mensaje = JSON.parse(texto);
+  } catch {
+    console.error(`hotswap: mensaje que no es JSON: ${texto.slice(0, 200)}`);
+    return;
+  }
+  // El servidor saluda primero y ese saludo no es la respuesta de nadie.
+  if (!saludado && mensaje.command === "server_hello") {
+    saludado = true;
+    siguiente();
+    return;
+  }
+  console.log(JSON.stringify({ comando: pendiente?.command, ...sinBinarios(mensaje) }));
+  pendiente = undefined;
+  siguiente();
+};