xonecode 0.6.0 → 0.8.0

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.`);

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

@@ -278,6 +278,34 @@ function excepcionDeXOne() {
 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}`);
 

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

@@ -56,8 +56,14 @@ 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í se da por binario y no se imprime. */
-const LARGO_DE_BINARIO = 2_000;
+/**
+ * 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")) {
@@ -90,12 +96,24 @@ function salir(motivo) {
   process.exit(1);
 }
 
-/** Extensión por los primeros bytes en base64, sin adivinar por el nombre del comando. */
-function extensionDe(base64) {
+/**
+ * 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 "bin";
+  return undefined;
 }
 
 /**
@@ -108,13 +126,25 @@ function extensionDe(base64) {
 function sinBinarios(respuesta) {
   const copia = { ...respuesta };
   for (const [clave, valor] of Object.entries(copia)) {
-    if (typeof valor !== "string" || valor.length < LARGO_DE_BINARIO) continue;
+    if (typeof valor !== "string" || valor.length < LARGO_PARA_GUARDAR) continue;
+    const imagen = imagenDe(valor);
     if (ARTEFACTOS === undefined) {
-      copia[clave] = `<${valor.length} car. de binario; sin XONECODE_ARTEFACTOS no hay dónde guardarlo>`;
+      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;
     }
-    const nombre = `captura-${Date.now()}.${extensionDe(valor)}`;
-    const bytes = Buffer.from(valor, "base64");
+    /**
+     * 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>`;
   }

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

@@ -51,6 +51,34 @@ const cliente = join(import.meta.dirname, "xone-hotswap");
 const mandar = (comando) =>
   execFileSync("node", [cliente, JSON.stringify(comando)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
 
+/**
+ * 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/3 túnel y parada de ${PAQUETE}`);
 // El túnel PRIMERO y sin quitarlo después: hay que reaplicarlo tras cada reconexión del cable,
 // así que quitarlo dejaría al siguiente hablando con nadie.

package/skills/xone-plan-builder/SKILL.md

@@ -22,17 +22,33 @@ xone-review             →  valida con xone-simulator
 
 ## Estructura de archivos
 
+Todo vive en **la carpeta del plan**, `/planes/<nombre>/`, NUNCA en la raíz del proyecto: un plan
+no es parte de la app del cliente, y lo que se escribe en la raíz entra en el commit del turno y
+sube a CloudStudio. Escribe tu `TASKS.md` **en la misma carpeta de la que leíste el `PLAN.md`**,
+no en otra: quien desarrolle va a buscarlo ahí. Y el nombre es **EXACTO** — nada de
+`tareas.md` ni variantes: dos ficheros con las mismas tareas son dos fuentes de verdad, y la
+que nadie marca se queda vieja.
+
 ```
-<raíz del proyecto>/
+/planes/favoritos/
 ├── PLAN.md                 ← entrada (producido por xone-spec-builder)
-├── TASKS.md                 ← salida (esta skill)
+├── TASKS.md                ← salida (esta skill)
 ├── CONTEXT.md              ← glosario (ya existe del spec-builder)
-├── docs/
-│   └── adr/
+└── adr/
 ```
 
 Si no existe `PLAN.md`, **detente y pide al usuario que ejecute `xone-spec-builder` primero**. No se puede descomponer lo que no está especificado.
 
+## El `TASKS.md` se ACTUALIZA, no se archiva
+
+`**Estado:**` es `pendiente`, `en curso` o `hecha`, y lo mantiene **quien ejecuta la tarea**, en
+este mismo fichero y en esta misma carpeta. Las casillas de los criterios se marcan `- [x]`
+cuando ese criterio está comprobado, no cuando se escribió el código que debería cumplirlo.
+
+Ésa es la razón de que el plan viva en `/planes/` y no entre los artefactos: no es un documento
+que se entrega una vez, es el estado compartido entre quien planifica y quien desarrolla, a lo
+largo de varios turnos y varias sesiones.
+
 ## Precondiciones
 
 Antes de descomponer, valida el `PLAN.md`:
@@ -133,6 +149,7 @@ Ver [TASKS-FORMAT.md](references/TASKS-FORMAT.md) para la plantilla completa. Re
 ## Tareas
 
 ### 01 — {Título}
+**Estado:** pendiente
 **Qué entrega:** {comportamiento end-to-end, perspectiva del usuario — no lista de capas}
 **Bloqueada por:** Ninguna — puede empezar ya
 **Notas:** {si hay algo que el spec dejó pendiente que afecta a esta tarea}
@@ -141,6 +158,7 @@ Ver [TASKS-FORMAT.md](references/TASKS-FORMAT.md) para la plantilla completa. Re
 - [ ] Criterio de aceptación 2
 
 ### 02 — {Título}
+**Estado:** pendiente
 **Qué entrega:** …
 **Bloqueada por:** 01
 …

package/skills/xone-spec-builder/SKILL.md

@@ -24,22 +24,52 @@ El spec builder es el primer paso de cualquier trabajo XOne. Lo que sigue:
 
 ## Estructura de archivos
 
-La entrevista escribe en el **directorio de trabajo** del usuario — la raíz del proyecto XOne (existente o por crear). Crea los archivos **lazy**, solo cuando hay algo que escribir:
+La entrevista escribe en **`/planes/<nombre>/`**, NUNCA en la raíz del proyecto. Un plan no es
+parte de la app: la raíz es el proyecto XOne del cliente, y lo que se escribe ahí pasa por
+aprobación, entra en el commit de cada turno y **sube a CloudStudio**. `/planes/` no: no entra en
+git, no se sincroniza, y **sobrevive a la sesión** — se planifica un día y se implementa otro.
+
+**Elige tú el `<nombre>`**, y es una carpeta por plan porque puede haber varios a la vez:
+minúsculas, dígitos y guiones sencillos (`favoritos`, `sync-offline`), corto y por lo que el
+desarrollo ES. Mira antes `/planes/` por si ya existe uno del mismo tema: si lo hay, AMPLÍALO en
+vez de abrir otro. Crea los archivos **lazy**, solo cuando hay algo que escribir.
+
+**Los nombres son EXACTOS**: `PLAN.md`, `CONTEXT.md` y la carpeta `adr/`. No crees
+traducciones ni variantes (`spec.md`, `glosario.md`, `plan.md`): quien lea el plan después
+busca esos nombres, y dos ficheros con lo mismo dentro son dos fuentes de verdad — la que
+nadie actualiza se queda vieja sin que nadie lo note.
 
 ```
-<raíz del proyecto>/
+/planes/favoritos/
 ├── PLAN.md                 ← el plan del desarrollo (entregable)
 ├── CONTEXT.md              ← glosario del dominio (términos canónicos, evitar)
-├── docs/
-│   └── adr/
-│       ├── 0001-sqlite-local-vs-replica.md
-│       └── 0002-login-con-oauth2-o-contra-db.md
+└── adr/
+    ├── 0001-sqlite-local-vs-replica.md
+    └── 0002-login-con-oauth2-o-contra-db.md
 ```
 
-Si no existe `PLAN.md`, créalo cuando la entrevista empiece a cristalizar decisiones. Si no existe `CONTEXT.md`, créalo cuando se resuelva el primer término de dominio. Si no existe `docs/adr/`, créalo cuando se tome la primera decisión digna de ADR.
+Si no existe `PLAN.md`, créalo cuando la entrevista empiece a cristalizar decisiones. Si no existe `CONTEXT.md`, créalo cuando se resuelva el primer término de dominio. Si no existe `adr/` dentro de la carpeta del plan, créalo cuando se tome la primera decisión digna de ADR.
 
 > **`PLAN.md` es el entregable.** `CONTEXT.md` y los ADRs lo acompañan y alimentan, pero lo que el usuario se lleva es el plan.
 
+## Si no hay nadie a quien entrevistar
+
+Puede que corras **dentro de un subagente**, y entonces no tienes interlocutor: una delegación es
+de un solo disparo y no hay forma de devolverle una pregunta a nadie a mitad de trabajo. Se nota
+en que nadie contesta a la primera ronda.
+
+Cuando eso pase, **no te inventes las respuestas**, que es justo lo que esta skill se prohíbe.
+Haz esto:
+
+1. Escribe el `PLAN.md` con lo que SÍ puedes resolver leyendo el proyecto.
+2. Pon las decisiones que no puedes tomar en **§Pendientes**, cada una con las opciones y con
+   qué cambia según la respuesta. Una pregunta sin consecuencia no merece bloquear nada.
+3. **Dilo en tu respuesta final**, nombrando las pendientes que bloquean. Quien lea eso sí puede
+   preguntárselo a la persona y volver a encargártelo con las respuestas dentro.
+
+Un plan con tres huecos declarados vale; uno con tres huecos rellenados a ojo es peor que no
+tenerlo, porque nadie sabe cuáles eran.
+
 ## Antes de entrevistar: triage de complejidad
 
 No toda petición necesita una entrevista de 8 rounds. Antes de empezar, clasifica la **complejidad** del desarrollo y ajusta el nivel de especificación: