xonecode 0.5.1 → 0.8.0

package/skills/archify/SKILL.md

@@ -10,6 +10,28 @@ metadata:
 
 # Archify
 
+## Antes de escribir nada: dónde va y qué no funciona ahí
+
+**Esto se lee aquí porque es donde se lee de verdad.** Vivía en el prompt de cuatro
+especialistas —unos 1.400 caracteres que viajaban en CADA llamada de cada uno, hablaran o no de
+diagramas— y antes de eso vivía en `estilo.md`, que un turno real no llegó a abrir: escribió un
+artefacto con `localStorage`, el script se mató entero y el botón del tema quedó muerto. La
+lección no era «repítelo en todos los prompts», era **ponerlo en el fichero que sí se abre**.
+
+- **DÓNDE se guarda**: `/artefactos/<nombre>.html`, nunca en la raíz del proyecto ni dentro de
+  `/skills`. `/artefactos/` es la carpeta de ESTA sesión: no es del proyecto, no pasa por
+  aprobación, no entra en git y no sube a CloudStudio. Un HTML escrito fuera de ella acaba
+  dentro de la app XOne del usuario.
+- **DÓNDE se VE, y qué NO funciona ahí**: la consola lo pinta en un iframe sin
+  `allow-same-origin`. `localStorage`, `sessionStorage` e `indexedDB` **LANZAN**, y se llevan por
+  delante el resto de tu `<script>`: nada de interruptor de tema ni de recordar nada — el tema se
+  resuelve con `matchMedia`, y ya. Y no se llega al origen de la consola, así que **hornea los
+  datos dentro del HTML**.
+- **Apóyate en el código real** antes de dibujar: no inventes nombres, componentes ni flujos.
+- **Para un diagrama, esquema, arquitectura, flujo, secuencia, datos o estados, esta skill basta.**
+  Si ADEMÁS piden un contenedor interactivo alrededor, eso es otra skill: úsala solo si la
+  tienes y después de decidir el diagrama aquí. **No nombres jamás una skill que no tengas.**
+
 Create a diagram: architecture, workflow, sequence, dataflow, or lifecycle.
 
 ## Aquí no hay terminal
@@ -93,8 +115,9 @@ pide explícitamente una de esas capacidades.
 
 Construye el diagrama tú mismo, como SVG o mermaid inline dentro de tu propio HTML
 autocontenido — no hay JSON de Archify que escribir ni motor que lo consuma, así que no lleva
-theme switching, pan/zoom, búsqueda ni export automático salvo que tú los programes. Sigue la
-skill `artifacts-builder`, en concreto `reference/diagramas.md`. La entrega depende de la tool
+theme switching, pan/zoom, búsqueda ni export automático salvo que tú los programes. **Si tienes** la skill
+`artifacts-builder`, su `reference/diagramas.md` te sirve de guía; si no la tienes, sigue aquí y
+no la nombres. La entrega depende de la tool
 que tengas:
 
 - **Con `publish_artifact`**: `publish_artifact(path=..., title=...)`. **Cuando confirme, HAS

package/skills/artifacts-builder/SKILL.md

@@ -5,6 +5,29 @@ description: "Build a self-contained interactive HTML artifact the user can view
 
 # Artifacts Builder
 
+## Antes de escribir nada: dónde va y qué no funciona ahí
+
+**Esto se lee aquí porque es donde se lee de verdad.** Vivía en el prompt de cuatro
+especialistas —unos 1.400 caracteres que viajaban en CADA llamada de cada uno, hablaran o no de
+diagramas— y antes de eso vivía en `estilo.md`, que un turno real no llegó a abrir: escribió un
+artefacto con `localStorage`, el script se mató entero y el botón del tema quedó muerto. La
+lección no era «repítelo en todos los prompts», era **ponerlo en el fichero que sí se abre**.
+
+- **DÓNDE se guarda**: `/artefactos/<nombre>.html`, nunca en la raíz del proyecto ni dentro de
+  `/skills`. `/artefactos/` es la carpeta de ESTA sesión: no es del proyecto, no pasa por
+  aprobación, no entra en git y no sube a CloudStudio. Un HTML escrito fuera de ella acaba
+  dentro de la app XOne del usuario.
+- **DÓNDE se VE, y qué NO funciona ahí**: la consola lo pinta en un iframe sin
+  `allow-same-origin`. `localStorage`, `sessionStorage` e `indexedDB` **LANZAN**, y se llevan por
+  delante el resto de tu `<script>`: nada de interruptor de tema ni de recordar nada — el tema se
+  resuelve con `matchMedia`, y ya. Y no se llega al origen de la consola, así que **hornea los
+  datos dentro del HTML**.
+- **Apóyate en el código real** antes de dibujar: no inventes nombres, componentes ni flujos.
+- **Esta skill es para dashboards, informes, tablas filtrables y piezas interactivas.** Para un
+  diagrama de arquitectura, flujo o secuencia hay otra: úsala si la tienes, y si no la tienes,
+  dilo en vez de dibujarlo aquí — un diagrama hecho a mano sale peor y cuesta más. **No nombres
+  jamás una skill que no tengas.**
+
 You write ONE self-contained HTML file. No build step, no npm, no `execute` anywhere this
 skill is mounted — nothing here runs a script.
 

package/skills/xone-hotswap/SKILL.md

@@ -34,6 +34,102 @@ responde. Habla dos protocolos por el mismo puerto: **WebSocket** para los coman
   comando exista. Cuál es cuál, comando a comando: la columna **Canal (iOS)** de la
   [matriz](references/comandos.md#matriz-de-disponibilidad).
 
+## Los scripts que trae esta skill: se llaman por su nombre
+
+Esta carpeta trae siete programas, y **están en el PATH**: se llaman como cualquier otro comando,
+sin ruta. Existen por una razón concreta — los comandos del canal viajan por **WebSocket** y
+`curl` no habla WebSocket, así que sin ellos no hay forma de mandar un `getAllElements` desde una
+shell.
+
+```bash
+# ANTES QUE NADA si `adb devices` no lista ninguno: levanta el emulador y ESPERA a que esté
+# listo de verdad. Ya arrancado, lo dice y no lanza nada, así que se puede llamar sin miedo.
+xone-arrancar-android
+xone-arrancar-android --avd pixel8                # con varios AVDs
+xone-arrancar-android --lista                     # cuáles hay, sin arrancar ninguno
+
+# LO PRIMERO al empezar con un aparato, y lo primero que hay que probar si el canal no contesta:
+# el host reabre la última app ejecutada, y si ésa se quedó en un error, nada responde.
+xone-reiniciar-android
+xone-reiniciar-android --app MiApp
+
+# «lanza la app», «despliégala»: la cadena ENTERA (túnel, ZIP, subida, reinicio, lanzamiento)
+# y termina diciendo si la app está VIVA, con su árbol de controles.
+xone-desplegar-android
+xone-desplegar-android --captura                  # …y deja la captura, en la MISMA orden
+xone-desplegar-android --app MiApp --serie emulator-5554
+
+# Cualquier comando del catálogo de más abajo (varios en orden, si le pasas varios):
+xone-hotswap '{"command":"getAllElements","format":"xone"}'
+xone-hotswap '{"command":"getScreenshot"}'
+xone-hotswap '{"command":"click","name":"MAP_BT_ACEPTAR"}'
+
+# Por qué algo no se pinta o la app se muere: las excepciones del aparato.
+xone-log-android
+xone-log-android --limpiar        # aísla lo que pase a partir de ahora
+
+# RESPALDO de la captura, para cuando el canal no contesta: `adb exec-out screencap` pero
+# guardándola donde toca. Nunca redirijas ese `adb` tú: el `cwd` es la raíz del proyecto.
+xone-captura-android
+xone-captura-android --nombre login.png
+
+# iOS: levantar el host y dejar el canal listo (desplegar en iOS NO está medido).
+xone-arrancar-ios
+```
+
+**El log es donde está el porqué.** Una pantalla en blanco no dice nada; el log dice
+`LayoutException … Cannot find font file Inter-Regular`, con la colección y el control. Medido
+sobre un proyecto real: la app arrancaba, el árbol de controles contestaba, y lo que faltaba era
+una fuente. Ni la captura ni `getAllElements` lo cuentan.
+
+**Encadenar órdenes cuesta más que la orden.** Lo que devuelve cada una es pequeño —1,6 KB el
+árbol de controles, 108 bytes la captura—, pero cada ida y vuelta reenvía la conversación
+entera. Por eso «lanza la app y sácame una captura» es `xone-desplegar-android --captura`, un
+viaje, y no tres órdenes encadenadas. Y `xone-hotswap` acepta varios comandos de golpe, que es
+la misma idea.
+
+Tres cosas de `xone-hotswap` que conviene saber antes de leer su salida:
+
+- **Una captura no se imprime**: se guarda en `$XONECODE_ARTEFACTOS` 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 sin que nadie pueda mirarlos. Para ENSEÑARLA, di su nombre:
+  la interfaz la enseña desde ahí. **No intentes abrirla ni leerla**: es binaria.
+- **La respuesta viene en `status`** —no en un campo `image`— y una captura de Android es
+  **JPEG**, no PNG.
+- Si muere con «no se pudo hablar con el aparato», casi siempre falta el túnel
+  (`adb forward tcp:8443 tcp:8443`) o la app host no está viva.
+
+Y `xone-desplegar-android` **no necesita un `zip` del sistema**: construye el ZIP él mismo con
+`zlib`, así que tampoco depende de que haya uno en Windows.
+
+**No uses las herramientas nativas para lo que contesta el canal**: `uiautomator dump` da la
+jerarquía de vistas de ANDROID y `adb exec-out screencap` una foto cruda; ninguna de las dos
+conoce los controles XOne, que es por lo que suelen preguntarte.
+
+**Pero si el canal no contesta y aun así hace falta una captura, es `xone-captura-android`, no
+un `adb` compuesto a mano.** Medido: redirigir `adb exec-out screencap -p > captura.png` deja el
+fichero en el `cwd`, que es LA RAÍZ DEL PROYECTO del usuario — de ahí se va a la aprobación, a
+git y a CloudStudio. El script hace lo mismo y lo deja en `$XONECODE_ARTEFACTOS`, e imprime solo
+el nombre. Lo que enseña es lo que pinta el SISTEMA, no lo que la app host dice de sí misma: por
+eso sigue siendo el respaldo y no la vía buena.
+
+**Sin aparato no hay nada que probar, y arrancarlo es `xone-arrancar-android`.** Espera a que
+el sistema diga `sys.boot_completed=1` —no solo a que salga en `adb devices`—, porque sobre un
+Android a medio arrancar el despliegue falla de formas que no se leen. Y si ya está arrancado
+lo dice y no lanza nada, así que se puede llamar a la defensiva antes de desplegar.
+
+```bash
+adb devices                    # ¿hay algo?
+xone-arrancar-android          # si no; --avd <nombre> con varios AVDs
+xone-desplegar-android
+```
+
+**No lo compongas a mano.** Un comando que no termina cuelga el turno, y además el binario no
+suele estar donde crees: tus comandos corren con `/bin/sh`, sin el `~/.zshrc` de nadie, y en un
+Mac con Homebrew `emulator` vive en `share/android-commandlinetools/emulator/` aunque `adb` sí
+esté en el PATH. El script recibe la ruta buena del harness (`$XONECODE_EMULATOR`), que la
+resuelve con el mismo localizador que la pestaña Ejecutar.
+
 ## Cómo llegar, según la plataforma
 
 **Android** — por `adb forward`, y entonces la IP es `127.0.0.1` (el localhost del PC, que adb

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

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Levantar un emulador de Android y dejarlo listo para desplegar.
+ *
+ * EXISTE PORQUE FALTABA, y el síntoma fue literal: con el emulador cerrado, el agente no lo
+ * levantaba. Lo que había era prosa en la skill —«mándalo al fondo y espera a una
+ * condición»— y cuatro sitios donde equivocarse: encontrar un binario que NO está en el PATH
+ * (en un Mac con Homebrew `emulator` vive en `share/android-commandlinetools/emulator/`
+ * mientras `adb` sí está, y `ANDROID_HOME` suele estar vacía), elegir el AVD, mandarlo al
+ * fondo sin colgar el turno, y saber cuándo está listo de verdad.
+ *
+ * LAS RUTAS NO SE ADIVINAN, LLEGAN: `$XONECODE_EMULATOR` y `$XONECODE_ADB` las pone el
+ * harness con el MISMO localizador que usa la pestaña Ejecutar
+ * (`core/shellDeAgente.ts#variablesDeAndroid` ← `localizadorDeAndroid`). Dos reglas sobre
+ * dónde vive el SDK son dos reglas que divergen. Si no están, se cae al PATH, que es lo
+ * único honesto que se puede hacer sin ellas.
+ *
+ * DOS COSAS QUE LO SEPARAN DEL BOTÓN DE LA WEB (`agent/dispositivos/arranqueDeEmulador.ts`),
+ * y son deliberadas:
+ *
+ *  - **Espera a `sys.boot_completed`, no solo a que el aparato APAREZCA.** Al botón le basta
+ *    con que `adb devices` lo liste con su nombre de AVD: quien mira la pantalla ya ve el
+ *    resto. Aquí el comando siguiente es `xone-desplegar-android`, y sobre un Android a
+ *    medio arrancar falla de formas que no se leen —un `pm grant` que no responde, un
+ *    `am start` que se traga—. La condición de «listo» es la del sistema, no la nuestra.
+ *  - **Es IDEMPOTENTE.** El modelo lo va a llamar a la defensiva antes de desplegar. Si ya
+ *    hay un emulador vivo con ese AVD se dice y se sale con 0, sin lanzar nada: un segundo
+ *    `emulator -avd pixel8` falla con ruido y manda al modelo a diagnosticar un problema que
+ *    no existe.
+ *
+ * USO:
+ *   xone-arrancar-android                  el único AVD que haya
+ *   xone-arrancar-android --avd pixel8     con varios
+ *   xone-arrancar-android --lista          qué AVDs hay, sin arrancar nada
+ */
+import { execFileSync, spawn } from "node:child_process";
+
+/** Lo que tarda un arranque en frío de un AVD con `google_apis`, con margen. Por debajo del
+ *  tope de reloj de UN comando del harness (600 s), que es quien mataría al script entero. */
+const TOPE_MS = 180_000;
+const ESPERA_S = 2;
+
+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")) {
+  console.error(`xone-arrancar-android — levanta un emulador y espera a que esté ARRANCADO.
+
+  xone-arrancar-android                  el único AVD que haya
+  xone-arrancar-android --avd pixel8     con varios
+  xone-arrancar-android --lista          qué AVDs hay, sin arrancar nada
+
+Si ya hay un emulador vivo con ese AVD, lo dice y no lanza nada. Espera a que el sistema
+diga \`sys.boot_completed=1\`, no solo a que el aparato aparezca en \`adb devices\`: sobre un
+Android a medio arrancar, \`xone-desplegar-android\` falla de formas que no se leen.
+Después: xone-desplegar-android`);
+  process.exit(0);
+}
+
+// El harness los pone; el PATH es el respaldo. Un valor vacío no es «no consta», así que no
+// se acepta como ruta: se cae al nombre pelado igual que si no estuviera.
+const EMULATOR = process.env.XONECODE_EMULATOR || "emulator";
+const ADB = process.env.XONECODE_ADB || "adb";
+
+const adb = (...partes) =>
+  execFileSync(ADB, partes, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/** Los emuladores conectados, con el AVD que dice ser cada uno. */
+function emuladoresVivos() {
+  let salida;
+  try {
+    salida = adb("devices");
+  } catch {
+    // `adb` puede estar levantando su demonio. No es un fallo del arranque, es un sondeo más.
+    return [];
+  }
+  const vivos = [];
+  for (const linea of salida.split(/\r?\n/)) {
+    const l = linea.trim();
+    if (l === "" || /^List of devices/i.test(l) || l.startsWith("*")) continue;
+    const [serie, estado] = l.split(/\s+/);
+    if (!serie || !serie.startsWith("emulator-") || estado !== "device") continue;
+    let avd;
+    try {
+      avd = adb("-s", serie, "emu", "avd", "name")
+        .split(/\r?\n/)
+        .map((x) => x.trim())
+        .find((x) => x !== "" && x !== "OK");
+    } catch {
+      // Ese emulador todavía no contesta a la consola. Se sigue con los demás.
+    }
+    vivos.push({ serie, avd });
+  }
+  return vivos;
+}
+
+/** «Listo» lo dice el SISTEMA, no nosotros. */
+function arrancadoDelTodo(serie) {
+  try {
+    return adb("-s", serie, "shell", "getprop", "sys.boot_completed").trim() === "1";
+  } catch {
+    return false;
+  }
+}
+
+function avdsDisponibles() {
+  try {
+    return execFileSync(EMULATOR, ["-list-avds"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter((l) => l !== "");
+  } catch (error) {
+    console.error(`no pude listar los AVDs con «${EMULATOR}»: ${error.message.split("\n")[0]}`);
+    console.error("Si el SDK está instalado pero no lo encuentro, es que falta ANDROID_HOME o la carpeta emulator/.");
+    process.exit(1);
+  }
+}
+
+if (args.includes("--lista")) {
+  const avds = avdsDisponibles();
+  if (avds.length === 0) console.error("no hay ningún AVD creado. Créalo con `avdmanager` o desde Android Studio.");
+  else console.log(avds.join("\n"));
+  process.exit(0);
+}
+
+/** El AVD: el que se diga, o el único que haya. Mismo contrato que `xone-arrancar-ios`. */
+function elegirAvd() {
+  const dicho = opcion("avd");
+  if (dicho !== undefined) return dicho;
+  const avds = avdsDisponibles();
+  if (avds.length === 0) {
+    console.error("no hay ningún AVD creado. Créalo con `avdmanager` o desde Android Studio.");
+    process.exit(1);
+  }
+  if (avds.length > 1) {
+    console.error(`hay ${avds.length} AVDs; dime cuál con --avd:`);
+    for (const a of avds) console.error(`  ${a}`);
+    process.exit(1);
+  }
+  return avds[0];
+}
+
+const avd = elegirAvd();
+
+// El nombre se convierte en un ARGUMENTO de proceso, así que se cierra por FORMA. Ojo al guion
+// INICIAL: `emulator` tomaría `-foo` por una bandera suya. Es la misma clase que acepta el
+// harness (`core/dispositivos.ts#nombreDeAvdDeConsola`), a propósito.
+if (!/^[A-Za-z0-9._][A-Za-z0-9._-]*$/.test(avd)) {
+  console.error(`«${avd}» no es un nombre de AVD`);
+  process.exit(1);
+}
+
+// IDEMPOTENTE: si ya está, no se lanza nada.
+const yaEstaba = emuladoresVivos().find((e) => e.avd === avd);
+if (yaEstaba !== undefined) {
+  if (arrancadoDelTodo(yaEstaba.serie)) {
+    console.log(`${avd} ya está arrancado (${yaEstaba.serie}). No he lanzado nada.`);
+    console.log("Siguiente: xone-desplegar-android");
+    process.exit(0);
+  }
+  console.log(`${avd} (${yaEstaba.serie}) está arrancando; espero a que termine.`);
+}
+
+if (yaEstaba === undefined) {
+  console.log(`1/2 lanzando ${avd}`);
+  /**
+   * DESPEGADO Y SIN TUBERÍAS. Un emulador no termina nunca: si el script se queda con sus
+   * pipes, no sale, y entonces el que muere por el tope de reloj es el SCRIPT —diez minutos
+   * de turno tirados—. `unref` es lo que deja que este proceso acabe con el nieto vivo.
+   */
+  const hijo = spawn(EMULATOR, ["-avd", avd], { detached: true, stdio: "ignore" });
+  let fallo;
+  hijo.on("error", (e) => {
+    fallo = e.message;
+  });
+  hijo.unref();
+  execFileSync("sleep", [String(ESPERA_S)]);
+  if (fallo !== undefined) {
+    console.error(`no pude lanzar el emulador: ${fallo}`);
+    process.exit(1);
+  }
+}
+
+console.log(`2/2 esperando a que ${avd} termine de arrancar`);
+const t0 = Date.now();
+while (Date.now() - t0 < TOPE_MS) {
+  const mio = emuladoresVivos().find((e) => e.avd === avd);
+  if (mio !== undefined && arrancadoDelTodo(mio.serie)) {
+    console.log(`${avd} arrancado y listo (${mio.serie}), ${Math.round((Date.now() - t0) / 1000)} s`);
+    console.log("Siguiente: xone-desplegar-android");
+    process.exit(0);
+  }
+  execFileSync("sleep", [String(ESPERA_S)]);
+}
+
+// El proceso sigue vivo: se dice lo que se SABE, que es que todavía no está listo.
+console.error(`${avd} no ha terminado de arrancar en ${TOPE_MS / 1000} s; sigue en marcha.`);
+console.error("Vuelve a llamarme dentro de un rato: si ya está, lo digo y no lanzo nada.");
+process.exit(1);

package/skills/xone-hotswap/scripts/xone-arrancar-ios

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Levantar el host de iOS y dejar el canal listo. La plantilla equivalente a la de Android.
+ *
+ * LO QUE CAMBIA RESPECTO A ANDROID, y no es un detalle:
+ *  - **No hay túnel.** El simulador comparte la pila de red del Mac, así que el servidor se
+ *    alcanza en `localhost` directamente. En un iPhone físico se llega por la IP de la LAN que
+ *    enseña la propia app.
+ *  - **No hay `/file_upload`, ni `push_files`, ni `runScript`, ni `runSql`, ni logs.** El host
+ *    de iOS no los tiene. O sea que **esto no despliega el proyecto**: arranca el host y abre
+ *    el canal. Desplegar en iOS no está medido, y fingir un paso que no se ha probado es peor
+ *    que no tenerlo.
+ *  - El host es **`es.xone.studioapp.swift`**, y solo existe en el runtime en modo desarrollo.
+ *
+ * USO:
+ *   node "$XONECODE_SKILL_XONE_HOTSWAP/scripts/ios-arrancar.mjs"
+ *   node "$XONECODE_SKILL_XONE_HOTSWAP/scripts/ios-arrancar.mjs" --udid <UDID> --app MiApp
+ *
+ * Después, los comandos van por el mismo cliente que en Android:
+ *   HOTSWAP_URL=wss://localhost:8443/hotswap node "$XONECODE_SKILL_XONE_HOTSWAP/scripts/hotswap.mjs" '{"command":"getAllElements","format":"xone"}'
+ *
+ * DOS AVISOS SOBRE EL HOST DE iOS que te van a costar una sesión si no los sabes: `MyAllXOne`
+ * crashea al arrancar (GoogleMaps) —para probar filas, el fixture usable es `FontIconsApp`—, y
+ * el host se cae al abrir una lista de menú porque le faltan los `xone_img_*.png`. Si el puerto
+ * deja de responder justo después de abrir un menú, es eso y es un defecto AJENO al hotswap.
+ */
+import { execFileSync } from "node:child_process";
+
+const HOST = "es.xone.studioapp.swift";
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.error(`xone-arrancar-ios — levanta el host de iOS y deja el canal listo.
+
+  xone-arrancar-ios                     usa el único simulador arrancado
+  xone-arrancar-ios --udid <UDID>       con varios arrancados
+  xone-arrancar-ios --app MiApp         además lanza esa app
+
+NO despliega el proyecto: en iOS no hay /file_upload y eso no está medido. Después, los comandos
+van por: HOTSWAP_URL=wss://localhost:8443/hotswap xone-hotswap '{"command":"getAllElements"}'`);
+  process.exit(0);
+}
+
+const args = process.argv.slice(2);
+const opcion = (nombre) => {
+  const i = args.indexOf(`--${nombre}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+/** El simulador arrancado, o el que se diga. Sin ninguno, se dice: no se arranca uno a ciegas. */
+function udid() {
+  const dicho = opcion("udid");
+  if (dicho !== undefined) return dicho;
+  const salida = execFileSync("xcrun", ["simctl", "list", "devices", "booted", "-j"], { encoding: "utf8" });
+  const porRuntime = JSON.parse(salida).devices ?? {};
+  const arrancados = Object.values(porRuntime).flat();
+  if (arrancados.length === 0) {
+    console.error("no hay ningún simulador arrancado. Arranca uno (`xcrun simctl boot <UDID>`) o pásame --udid.");
+    process.exit(1);
+  }
+  if (arrancados.length > 1) {
+    console.error(`hay ${arrancados.length} simuladores arrancados; dime cuál con --udid:`);
+    for (const d of arrancados) console.error(`  ${d.udid}  ${d.name}`);
+    process.exit(1);
+  }
+  return arrancados[0].udid;
+}
+
+const destino = udid();
+console.log(`1/2 arrancando el host en ${destino}`);
+// Arrancar el host es lo que levanta el servidor: sin la app viva, el puerto no responde.
+console.log(execFileSync("xcrun", ["simctl", "launch", destino, HOST], { encoding: "utf8" }).trim());
+
+const app = opcion("app");
+if (app === undefined) {
+  console.log("2/2 host arrancado. El canal es wss://localhost:8443/hotswap");
+} else {
+  console.log(`2/2 lanzando ${app}`);
+  const cliente = new URL("hotswap.mjs", import.meta.url).pathname;
+  console.log(
+    execFileSync("node", [cliente, JSON.stringify({ command: "launchApplication", appName: app })], {
+      encoding: "utf8",
+      env: { ...process.env, HOTSWAP_URL: "wss://localhost:8443/hotswap" },
+    }).trim(),
+  );
+}

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

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Una captura de la pantalla del aparato, POR LA VÍA NATIVA, a la carpeta de artefactos.
+ *
+ * POR QUÉ EXISTE, si el canal ya sabe capturar. `xone-hotswap '{"command":"getScreenshot"}'`
+ * es la vía buena —la pide la app host, así que sale lo que la app pinta— pero necesita el
+ * túnel y la app viva. Cuando eso no está, lo único que queda es `adb exec-out screencap`, y
+ * medido: el modelo la compone él y redirige la salida a un fichero, que en el `cwd` de la
+ * shell es LA RAÍZ DEL PROYECTO. Así apareció un `screenshot_login.png` de 773 KB entre los
+ * `.xne` del cliente, camino de la aprobación, de git y de CloudStudio.
+ *
+ * Un script no es una barrera —una shell alcanza el disco entero y eso no se arregla con
+ * prompts—, pero le quita el motivo: pedir la captura por su nombre cuesta menos que
+ * componer el `adb` y elegir dónde dejarla, y ya cae donde tiene que caer.
+ *
+ * LO QUE NO HACE: no imprime la imagen. Un PNG de pantalla completa son cientos de miles de
+ * caracteres en base64, y meterlos en el contexto es pagarlos sin que nadie pueda mirarlos.
+ * Sale el NOMBRE, que es con lo que la interfaz la enseña.
+ *
+ * USO:
+ *   xone-captura-android                       captura a $XONECODE_ARTEFACTOS
+ *   xone-captura-android --nombre login.png    con nombre propio
+ *   xone-captura-android --serie emulator-5554 con varios aparatos conectados
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.error(`xone-captura-android — captura la pantalla del aparato con \`adb\` y la deja en artefactos.
+
+  xone-captura-android                        captura a $XONECODE_ARTEFACTOS
+  xone-captura-android --nombre login.png     con nombre propio
+  xone-captura-android --serie <id>           con varios aparatos conectados
+
+Es la vía de RESPALDO: si el túnel y la app host están vivos, la buena es
+\`xone-hotswap '{"command":"getScreenshot"}'\`, que captura lo que la app pinta.
+Nunca redirijas \`adb exec-out screencap\` a un fichero: el \`cwd\` es la raíz del
+proyecto del usuario y ahí no se escribe.`);
+  process.exit(0);
+}
+
+const ARTEFACTOS = process.env.XONECODE_ARTEFACTOS;
+if (ARTEFACTOS === undefined) {
+  // Sin sitio donde dejarla no se inventa uno: escribir en el `cwd` es exactamente el fallo
+  // que este script existe para no cometer.
+  console.error("no hay XONECODE_ARTEFACTOS: esta sesión no tiene carpeta de artefactos y la captura no se puede guardar.");
+  process.exit(1);
+}
+
+const opcion = (nombre) => {
+  const i = args.indexOf(`--${nombre}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const serie = opcion("serie");
+
+// `basename` y no la cadena tal cual: el nombre lo elige el modelo, y un `../` aquí escribiría
+// fuera de la carpeta de la sesión. Misma regla que `esRutaDeArtefacto` en el host.
+const pedido = opcion("nombre");
+const nombre = pedido === undefined ? `captura-${Date.now()}.png` : basename(pedido);
+if (nombre === "" || nombre === "." || nombre === "..") {
+  console.error("ese nombre no vale para un fichero.");
+  process.exit(1);
+}
+
+let bytes;
+try {
+  // `exec-out` y no `shell`: `shell` traduce los finales de línea y corrompe el PNG.
+  bytes = execFileSync("adb", [...(serie ? ["-s", serie] : []), "exec-out", "screencap", "-p"], {
+    maxBuffer: 256 * 1024 * 1024,
+  });
+} catch (error) {
+  console.error(`no se pudo capturar con adb: ${error.message}`);
+  process.exit(1);
+}
+
+// Una captura vacía no es una captura: `screencap` puede salir con 0 y no devolver nada si el
+// aparato está bloqueado. Decirlo es mejor que dejar un fichero de 0 bytes con buena pinta.
+if (bytes.length === 0) {
+  console.error("adb devolvió una captura VACÍA: ¿está el aparato despierto y desbloqueado?");
+  process.exit(1);
+}
+
+const destino = join(ARTEFACTOS, nombre);
+try {
+  writeFileSync(destino, bytes);
+} catch (error) {
+  console.error(`no se pudo guardar la captura: ${error.message}`);
+  process.exit(1);
+}
+
+console.log(`captura guardada como ${nombre} (${bytes.length} bytes). Es de la vía nativa: enseña lo que el SISTEMA pinta, no lo que la app host dice.`);