xonecode 0.5.1 → 0.8.0

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * El log del aparato, acotado a lo que sirve para diagnosticar: excepciones y errores del host.
+ *
+ * POR QUÉ NO ES `adb logcat` A SECAS. Un volcado crudo de este emulador son megabytes de
+ * `WindowManager` y `Transition requested`, con líneas sueltas de 2 KB: metido en el contexto de
+ * un agente cuesta más que todo el turno y entierra justo lo que se busca. Aquí se filtra por el
+ * **PID del host** —así sale TODO lo suyo, incluidas las excepciones de JavaScript del runtime
+ * XOne— y, aparte, los `FATAL`/`AndroidRuntime` de cualquiera, que son los que cuentan cuando la
+ * app se acaba de morir y ya no tiene PID.
+ *
+ * **Nunca sigue el log.** `adb logcat` sin `-d` no termina jamás, y un comando que no termina
+ * cuelga el turno entero. Si quieres aislar lo que pasa a partir de ahora: `--limpiar`, haces lo
+ * que sea, y vuelves a pedirlo.
+ *
+ * USO:
+ *   xone-log-android                      errores y excepciones recientes
+ *   xone-log-android --lineas 400         más cola
+ *   xone-log-android --todo               todo lo del host, no solo errores
+ *   xone-log-android --limpiar            vacía el buffer y sale (para aislar lo siguiente)
+ *   xone-log-android --serie emulator-5554
+ */
+import { execFileSync } from "node:child_process";
+
+const PAQUETE = "com.xone.android.framework";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.error(`xone-log-android — el log del aparato, acotado al host de XOne.
+
+  xone-log-android                 errores y excepciones recientes (por omisión, 200 líneas)
+  xone-log-android --lineas 400    más cola
+  xone-log-android --todo          todo lo del host, no solo errores
+  xone-log-android --limpiar       vacía el buffer y sale, para aislar lo que pase después
+  xone-log-android --serie <id>    con varios aparatos conectados
+
+Filtra por el PID del host, así que trae también las excepciones de JavaScript del runtime.
+Nunca sigue el log: un comando que no termina cuelga el turno.`);
+  process.exit(0);
+}
+
+const opcion = (nombre) => {
+  const i = args.indexOf(`--${nombre}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const serie = opcion("serie");
+const adb = (...partes) =>
+  execFileSync("adb", [...(serie ? ["-s", serie] : []), ...partes], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+if (args.includes("--limpiar")) {
+  adb("logcat", "-c");
+  console.log("buffer del log vaciado. Haz lo que quieras aislar y vuelve a pedir el log.");
+  process.exit(0);
+}
+
+const lineas = Number(opcion("lineas") ?? 200);
+const todo = args.includes("--todo");
+
+/** El PID del host, si está vivo. Sin él no se puede acotar por proceso: se dice y se sigue. */
+let pid;
+try {
+  pid = adb("shell", "pidof", PAQUETE).trim().split(/\s+/)[0];
+} catch {
+  pid = undefined;
+}
+
+const salida = [];
+
+if (pid !== undefined && pid !== "") {
+  const suyo = adb("logcat", "-d", "--pid", pid, "-t", String(lineas));
+  salida.push(`--- ${PAQUETE} (pid ${pid}) ---`);
+  salida.push(todo ? suyo : soloInteresante(suyo));
+} else {
+  salida.push(`--- ${PAQUETE} no está vivo ahora mismo: solo queda lo que dejó escrito ---`);
+}
+
+/**
+ * Las caídas duras van aparte y SIN el PID, a propósito: cuando una app se muere, el proceso
+ * que escribió la excepción ya no existe, así que filtrar por PID se lleva por delante justo la
+ * traza que explica la muerte.
+ */
+const caidas = adb("logcat", "-d", "-t", String(lineas * 4), "AndroidRuntime:E", "DEBUG:F", "*:F", "*:S").trim();
+if (caidas !== "") {
+  salida.push("", "--- caídas duras (cualquier proceso) ---", caidas);
+}
+
+/** Lo que merece la pena leer de un volcado del host: errores, avisos y trazas de excepción. */
+function soloInteresante(texto) {
+  const filas = texto.split("\n").filter((l) => {
+    if (/^\s*$/.test(l)) return false;
+    // El nivel va tras el PID/TID: `09-18 08:21:17.053 815 880 E Tag: mensaje`.
+    if (/\s[EWF]\s/.test(l)) return true;
+    // Y el cuerpo de una traza de Java, que no lleva nivel en cada línea.
+    return /\bat [\w$.]+\(|Caused by:|Exception|Error:/.test(l);
+  });
+  return filas.length === 0 ? "(sin errores ni avisos en esas líneas)" : filas.join("\n");
+}
+
+console.log(salida.join("\n"));

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Dejar el host de Android en un estado conocido: matarlo y volver a levantarlo.
+ *
+ * POR QUÉ EXISTE. El host guarda la última app ejecutada y la reabre al arrancar, así que si
+ * esa app se quedó en un diálogo de error —o simplemente colgada— el canal **no contesta** y
+ * cualquier comando que mandes muere con «no se pudo hablar con el aparato». Desde fuera eso
+ * se lee como «no hay dispositivo», que es el diagnóstico equivocado: el aparato está, el
+ * framework está, y lo que hay es una app atascada delante.
+ *
+ * Es la primera orden que conviene correr al empezar con un aparato, y la que hay que probar
+ * antes de concluir que algo no funciona.
+ *
+ * USO:
+ *   xone-reiniciar-android                        deja el host en su pantalla de inicio
+ *   xone-reiniciar-android --app MiApp            y además lanza esa app
+ *   xone-reiniciar-android --serie emulator-5554  con varios aparatos conectados
+ *
+ * **No despliega nada**: no sube ficheros ni toca el proyecto. Para eso está
+ * `xone-desplegar-android`, que ya hace este reinicio como uno de sus pasos.
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+const PAQUETE = "com.xone.android.framework";
+const ACTIVIDAD = `${PAQUETE}/com.xone.android.hotswap.activities.SetupActivity`;
+const PUERTO = 8443;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.error(`xone-reiniciar-android — mata el host de XOne y lo vuelve a levantar.
+
+  xone-reiniciar-android                        lo deja en su pantalla de inicio
+  xone-reiniciar-android --app MiApp            y además lanza esa app
+  xone-reiniciar-android --serie emulator-5554  con varios aparatos conectados
+
+Úsalo cuando el canal no conteste: el host reabre la última app ejecutada, y si ésa se quedó
+en un error, nada responde aunque el aparato esté perfectamente. No despliega ni sube nada.`);
+  process.exit(0);
+}
+
+const opcion = (nombre) => {
+  const i = args.indexOf(`--${nombre}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const serie = opcion("serie");
+const adb = (...partes) =>
+  execFileSync("adb", [...(serie ? ["-s", serie] : []), ...partes], { encoding: "utf8" });
+
+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.
+adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO}`);
+adb("shell", "am", "force-stop", PAQUETE);
+
+console.log("2/3 levantando el host");
+adb("shell", "am", "start", "-n", ACTIVIDAD);
+
+console.log("3/3 esperando a que el canal CONTESTE");
+/**
+ * Se espera a una respuesta, no a un reloj: el `am start` vuelve cuando Android acepta el
+ * intent, no cuando el servidor escucha. Medido — sin esto, el primer comando de después muere
+ * con «Received network error or non-101 status code».
+ *
+ * Y la pregunta es `getAllElements`: contesta tanto si hay app viva como si no (`App is not
+ * running`), así que sirve de latido sin exigir que haya nada cargado.
+ */
+let vivo = false;
+for (let intento = 1; intento <= 20 && !vivo; intento++) {
+  try {
+    mandar({ command: "getAllElements", format: "xone" });
+    vivo = true;
+  } catch {
+    execFileSync("sleep", ["1"]);
+  }
+}
+if (!vivo) {
+  console.error(`el canal no levantó. Comprueba que ${PAQUETE} está instalado (adb shell pm list packages | grep xone)`);
+  console.error(`y que el puerto es el ${PUERTO}: si estaba ocupado, el framework coge el siguiente libre y lo dice en su pantalla.`);
+  process.exit(1);
+}
+
+const app = opcion("app");
+if (app === undefined) {
+  console.log("host reiniciado y canal listo. Ninguna app cargada.");
+} else {
+  console.log(`lanzando ${app}`);
+  console.log(mandar({ command: "launchApplication", appName: app }));
+  for (let intento = 1; intento <= 10; intento++) {
+    const salida = mandar({ command: "getAllElements", format: "xone" });
+    if (!salida.includes("App is not running")) {
+      console.log(salida);
+      process.exit(0);
+    }
+    execFileSync("sleep", ["2"]);
+  }
+  console.error(`«${app}» no llegó a contestar el árbol de controles: NO está viva.`);
+  console.error("Si nunca se ha subido a este aparato, primero xone-desplegar-android.");
+  process.exit(1);
+}

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: