@flxapps/adbax 0.0.0-stage → 0.1.0

package/src/backends/server.js

@@ -0,0 +1,297 @@
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * Host half of the on-device server (server/src). The server is a dex jar run
+ * through app_process as the shell user. It keeps one UiAutomation connection
+ * open and answers on an abstract unix socket that adb forwards to a local TCP
+ * port. Because the connection stays up, it has seen every accessibility event
+ * since it started and knows when the screen went quiet. A read on a settled
+ * screen costs tens of milliseconds instead of a second of forced waiting.
+ *
+ * The jar's MD5 is the version handshake: the host passes it as --token, the
+ * server echoes it, and a server answering with another token is an older
+ * build and gets replaced.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { adbRaw } from '../adb.js';
+import { AdbaxError, cachePath, delay, q, readJson, readText, serialKey, trace, writeJson } from '../util.js';
+
+const SOCKET = 'adbax';
+const PROCESS = 'adbax-server';
+const REMOTE_JAR = '/data/local/tmp/adbax-server.jar';
+const REMOTE_LOG = '/data/local/tmp/adbax-server.log';
+const MIN_SDK = 24;
+export const JAR = fileURLToPath(new URL('../../server/adbax-server.jar', import.meta.url));
+
+let jarMd5;
+function token() {
+  if (!jarMd5) {
+    if (!fs.existsSync(JAR)) throw new ServerUnavailable(`${JAR} is missing; run server/build.sh`);
+    jarMd5 = crypto.createHash('md5').update(fs.readFileSync(JAR)).digest('hex');
+  }
+  return jarMd5;
+}
+
+/** Seconds without a request before the server exits and frees the connection. */
+export const idleSeconds = () => +(process.env.ADBAX_SERVER_IDLE || 600);
+
+/** The server cannot run here; the caller falls back to the shell backend. */
+export class ServerUnavailable extends AdbaxError {
+  constructor(message, { remembered = false } = {}) {
+    super(message);
+    this.remembered = remembered;
+  }
+}
+
+export class ServerBackend {
+  constructor(adb) {
+    this.adb = adb;
+    this.name = 'server';
+    this.port = null;
+    this.ready = false;
+  }
+
+  get markerFile() {
+    return cachePath(`server-${serialKey(this.adb.serial)}.json`);
+  }
+
+  /** The local port adb already forwards to the server socket, or null. */
+  async findPort() {
+    const out = await adbRaw(['forward', '--list'], { soft: true });
+    for (const line of out.split('\n')) {
+      const [serial, local, remote] = line.trim().split(/\s+/);
+      if (serial === this.adb.serial && remote === `localabstract:${SOCKET}`) return +local.replace('tcp:', '');
+    }
+    return null;
+  }
+
+  get portFile() {
+    return cachePath(`port-${serialKey(this.adb.serial)}`);
+  }
+
+  async forward() {
+    const port = (await this.findPort()) || +(await this.adb.run(['forward', 'tcp:0', `localabstract:${SOCKET}`])).trim();
+    fs.writeFileSync(this.portFile, String(port));
+    return port;
+  }
+
+  /** A server answering for this device and this build. */
+  current(res) {
+    return !!res && res.head.token === token() && res.head.serial === this.adb.serial;
+  }
+
+  /**
+   * One request, one connection. Resolves {head, body}, or null when nothing
+   * answered: adb accepts a forwarded connection even with no server behind
+   * it and then closes it straight away.
+   */
+  send(req, timeoutMs = 15_000) {
+    const started = performance.now();
+    return new Promise((resolve) => {
+      const sock = net.connect(this.port, '127.0.0.1');
+      const chunks = [];
+      const timer = setTimeout(() => sock.destroy(), timeoutMs);
+      sock.on('connect', () => sock.write(JSON.stringify(req) + '\n'));
+      sock.on('data', (c) => chunks.push(c));
+      sock.on('error', () => {});
+      sock.on('close', () => {
+        clearTimeout(timer);
+        trace(`server ${req.cmd}`, started);
+        const buf = Buffer.concat(chunks);
+        const nl = buf.indexOf(10);
+        if (nl < 0) return resolve(null);
+        try {
+          resolve({ head: JSON.parse(buf.subarray(0, nl).toString('utf8')), body: buf.subarray(nl + 1) });
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+  }
+
+  /** Makes sure a current server answers, starting one if needed. Returns its ping. */
+  async ensure() {
+    if (this.ready) return;
+    // The last port saves an `adb forward --list`; the serial echo catches a
+    // port that adb has since handed to another device.
+    const cached = +readText(this.portFile);
+    let ping = null;
+    if (cached) {
+      this.port = cached;
+      ping = await this.send({ cmd: 'ping' }, 3000);
+      if (ping && ping.head.serial !== this.adb.serial) ping = null;
+    }
+    if (!ping) {
+      this.port = await this.forward();
+      ping = await this.send({ cmd: 'ping' }, 3000);
+    }
+    if (this.current(ping)) {
+      this.ready = true;
+      this.info = ping.head;
+      fs.rmSync(this.markerFile, { force: true });
+      return ping.head;
+    }
+    if (ping && ping.head.serial === this.adb.serial) await this.send({ cmd: 'quit' }, 3000);
+    const head = await this.start();
+    this.ready = true;
+    this.info = head;
+    return head;
+  }
+
+  async request(req, timeoutMs) {
+    await this.ensure();
+    let res = await this.send(req, timeoutMs);
+    if (!res) {
+      // It exited between requests (idle timeout, killed). Start it once more.
+      this.ready = false;
+      await this.ensure();
+      res = await this.send(req, timeoutMs);
+    }
+    if (!res) throw new AdbaxError(`server gave no answer to ${req.cmd}; see \`adbax server log\``);
+    if (!res.head.ok) throw new AdbaxError(res.head.error);
+    return res;
+  }
+
+  async start({ idle = idleSeconds(), force = false } = {}) {
+    const marker = readJson(this.markerFile);
+    if (!force && marker && marker.token === token() && marker.unsupported) {
+      throw new ServerUnavailable(marker.unsupported, { remembered: true });
+    }
+    const sdk = +(await this.adb.shell('getprop ro.build.version.sdk')).trim();
+    if (sdk < MIN_SDK) this.unsupported(`Android API ${sdk}; the server needs ${MIN_SDK} or newer`);
+
+    const remote = (await this.adb.shell(`md5sum ${REMOTE_JAR} 2>/dev/null`, { soft: true })).split(/\s/)[0];
+    if (remote !== token()) await this.adb.run(['push', JAR, REMOTE_JAR]);
+
+    // A server that no longer answers on our forward may still hold the
+    // accessibility connection, and only one client can have it.
+    await this.kill();
+    await this.adb.shell(`CLASSPATH=${REMOTE_JAR} nohup app_process / --nice-name=${PROCESS} ` +
+      `es.flx.adbax.Main --socket ${SOCKET} --token ${token()} --serial ${q(this.adb.serial)} --idle ${idle} ` +
+      `>${REMOTE_LOG} 2>&1 &`);
+    this.port = await this.forward();
+
+    const deadline = Date.now() + 10_000;
+    for (let i = 0; Date.now() < deadline; i++) {
+      await delay(i < 10 ? 60 : 200);
+      const ping = await this.send({ cmd: 'ping' }, 2000);
+      if (this.current(ping)) {
+        fs.rmSync(this.markerFile, { force: true });
+        return ping.head;
+      }
+      if (i < 4) continue;
+      const log = (await this.adb.shell(`cat ${REMOTE_LOG}`, { soft: true })).trim();
+      const crashed = /Exception|Error/.test(log);
+      // Until the VM applies --nice-name the process is still "app_process",
+      // so only call it dead after a grace period, or on a stack trace.
+      if (crashed || (Date.now() > deadline - 7000 && !(await this.running()))) {
+        if (/already registered/i.test(log)) {
+          throw new ServerUnavailable('another UiAutomation client holds the accessibility connection ' +
+            '(an instrumentation test, uiautomator, Appium, Maestro). Stop it, or pass --no-server.');
+        }
+        const reason = log.split('\n').find((l) => /Exception|Error/.test(l)) || log.split('\n')[0] || 'exited at start';
+        await this.kill();
+        this.unsupported(`server failed to start: ${reason.trim()}`);
+      }
+    }
+    throw new ServerUnavailable('server did not answer within 10 s; see `adbax server log`');
+  }
+
+  unsupported(reason) {
+    writeJson(this.markerFile, { token: token(), unsupported: reason, at: new Date().toISOString() });
+    throw new ServerUnavailable(reason);
+  }
+
+  async pid() {
+    return (await this.adb.shell(`pidof ${PROCESS}`, { soft: true })).trim();
+  }
+
+  /**
+   * Matches the command line rather than the process name, so it also finds a
+   * server still starting up. The brackets keep the pattern from matching the
+   * shell that runs it.
+   */
+  async running() {
+    return (await this.adb.shell(`pgrep -f '[a]dbx-server'`, { soft: true })).trim() !== '';
+  }
+
+  async kill() {
+    await this.adb.shell(`pkill -f '[a]dbx-server'; sleep 0.1`, { soft: true });
+  }
+
+  /** Ping without starting anything. */
+  async status() {
+    this.port = await this.findPort();
+    const pid = await this.pid();
+    if (!this.port) return { running: !!pid, pid, port: null };
+    const ping = await this.send({ cmd: 'ping' }, 3000);
+    return { running: !!ping, pid, port: this.port, ping: ping && ping.head, current: this.current(ping) };
+  }
+
+  async stop() {
+    this.port = await this.findPort();
+    if (this.port) await this.send({ cmd: 'quit' }, 3000);
+    await this.kill();
+    if (this.port) await this.adb.run(['forward', '--remove', `tcp:${this.port}`], { soft: true });
+    fs.rmSync(this.portFile, { force: true });
+    this.ready = false;
+  }
+
+  log() {
+    return this.adb.shell(`cat ${REMOTE_LOG}`, { soft: true });
+  }
+
+  // ---------------------------------------------------------------- backend
+
+  async dump({ settle = 0, idle = 300, timeout = 2000, windows = false } = {}) {
+    const res = await this.request({ cmd: 'dump', settle, idle, timeout, windows }, settle + timeout + 10_000);
+    return { xml: res.body.toString('utf8'), busy: res.head.busy, head: res.head };
+  }
+
+  tap(x, y) {
+    return this.request({ cmd: 'tap', x, y });
+  }
+
+  swipe(x1, y1, x2, y2, ms) {
+    return this.request({ cmd: 'swipe', x1, y1, x2, y2, ms }, ms + 10_000);
+  }
+
+  async key(codes, { long = false } = {}) {
+    for (const code of codes) {
+      await this.request(typeof code === 'number' ? { cmd: 'key', code, long } : { cmd: 'key', name: String(code).toUpperCase(), long });
+    }
+  }
+
+  /** Key events where the virtual keyboard map has the characters, ACTION_SET_TEXT where not. */
+  async type(text) {
+    return { via: (await this.request({ cmd: 'text', text })).head.via };
+  }
+
+  /** Empties the focused field. Returns false when it has none. */
+  async clear() {
+    try {
+      await this.request({ cmd: 'settext', text: '' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async focus() {
+    return (await this.request({ cmd: 'focus' })).head;
+  }
+
+  async activity() {
+    return (await this.request({ cmd: 'activity' })).head.activity || null;
+  }
+
+  async screenshot({ width = 0, grid = 0, format = 'png', quality = 85 } = {}) {
+    const res = await this.request({ cmd: 'screenshot', width, grid, format, quality }, 20_000);
+    return {
+      data: res.body, format: res.head.format, width: res.head.width, height: res.head.height, scaled: true,
+      screenWidth: res.head.screenWidth, screenHeight: res.head.screenHeight,
+    };
+  }
+}

package/src/backends/shell.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * The fallback backend: plain `adb shell` commands. Works on any device, but
+ * every read is a fresh `uiautomator dump`, which starts a VM, connects to the
+ * accessibility service and waits a full second for the screen to go idle, so
+ * about two seconds per read.
+ */
+import { delay, fail, q } from '../util.js';
+
+export class ShellBackend {
+  constructor(adb) {
+    this.adb = adb;
+    this.name = 'shell';
+  }
+
+  async dump({ settle = 0 } = {}) {
+    if (settle) await delay(settle);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const out = await this.adb.run(['exec-out', 'uiautomator', 'dump', '/dev/tty'], { soft: true, timeout: 30_000 });
+      const i = out.indexOf('<hierarchy');
+      if (i > -1 && out.includes('</hierarchy>')) return { xml: out.slice(i), busy: false };
+      // Some builds refuse /dev/tty; go through a file instead. Removed first,
+      // so a dump that fails cannot hand back the previous screen.
+      const f = await this.adb.shell(
+        'rm -f /sdcard/adbax.xml; uiautomator dump /sdcard/adbax.xml >/dev/null && cat /sdcard/adbax.xml', { soft: true });
+      const j = f.indexOf('<hierarchy');
+      if (j > -1) return { xml: f.slice(j), busy: false };
+      await delay(700);
+    }
+    const holder = (await this.adb.shell('pidof adbax-server', { soft: true })).trim();
+    fail('uiautomator dump failed 3x. ' + (holder
+      ? 'The adbax server is holding the accessibility connection; `adbax server stop` first.'
+      : 'The screen may be mid-animation, showing a secure surface, or the app draws no\n' +
+        '       accessibility nodes. Try `adbax screenshot --small`.'));
+  }
+
+  tap(x, y) {
+    return this.adb.shell(`input tap ${x} ${y}`);
+  }
+
+  swipe(x1, y1, x2, y2, ms) {
+    return this.adb.shell(`input swipe ${x1} ${y1} ${x2} ${y2} ${ms}`);
+  }
+
+  key(codes, { long = false } = {}) {
+    return this.adb.shell(`input keyevent ${long ? '--longpress ' : ''}${codes.map(q).join(' ')}`);
+  }
+
+  /** `input text` takes ASCII only on most builds; the caller warns about the rest. */
+  async type(text) {
+    await this.adb.shell(`input text ${q(text.replace(/ /g, '%s'))}`);
+    return { via: 'input' };
+  }
+
+  async clear(existingLength) {
+    await this.adb.shell('input keyevent KEYCODE_MOVE_END');
+    const n = Math.min(200, Math.max(existingLength + 5, 60));
+    await this.adb.shell('input keyevent ' + Array(n).fill('KEYCODE_DEL').join(' '));
+  }
+
+  /** The shell has no cheap way to ask; callers fall back to a dump. */
+  focus() {
+    return null;
+  }
+
+  async screenshot() {
+    return { data: await this.adb.execOut('screencap -p'), format: 'png', scaled: false };
+  }
+}

package/src/cli.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+import { parseArgs } from './args.js';
+import { resolveSerial } from './adb.js';
+import { Device } from './device.js';
+import { AdbaxError } from './util.js';
+import * as apps from './commands/apps.js';
+import * as device from './commands/device.js';
+import * as screen from './commands/screen.js';
+import * as server from './commands/server.js';
+import * as system from './commands/system.js';
+import * as touch from './commands/touch.js';
+
+const COMMANDS = {
+  ...device, ...screen, ...apps, ...system, ...server,
+  ...touch, 'scroll-to': touch.scrollTo, 'hide-keyboard': touch.hideKeyboard,
+  press: touch.longpress, text: touch.type, screencap: screen.screenshot, logcat: system.log, ls: apps.apps,
+};
+delete COMMANDS.scrollTo;
+delete COMMANDS.hideKeyboard;
+
+export const HELP = `adbax - drive an Android device or emulator by its accessibility tree
+
+  DEVICE    devices | use <serial|-> | avds | boot <avd> [--cold --wipe --no-window] | kill [--all]
+  SEE       ui [--all --full --json --raw --windows] | find <text> | inspect <text> | current
+            screenshot [path] [--small --width N --grid [step]]  (a .jpg path saves JPEG)
+  TOUCH     tap <text|n|x,y> | longpress <sel> [--dur ms] | type <text> [--into <sel>] [--clear --set --enter]
+            key <back|home|enter|recents|del|...|KEYCODE_*> [--long] | back | home | recents | hide-keyboard
+            swipe <up|down|left|right|x1,y1,x2,y2> [--dur ms] [--in <sel>]
+            scroll-to <text> [--max 12] [--dir up|down] [--tap]  |  wait <text> [--timeout 15] [--gone]
+  APPS      apps [filter] [--system] | launch <pkg> | start <pkg/.Act> | stop <pkg> | clear <pkg>
+            install <apk> [splits...] | uninstall <pkg> | deeplink <url> [pkg] | perm <grant|revoke> <pkg> <PERM> | perms <pkg>
+  DEBUG     log [pkg] [--lines N --grep re --level E] | crash | clearlog | record [secs] [path]
+  STATE     dark <on|off> | font <scale> | anim <on|off> | rotate <0|90|180|270|auto> | demo <on|off>
+  SERVER    server [status|start|stop|restart|log] [--idle seconds]
+  RAW       shell <cmd> | pull <remote> <local> | push <local> <remote> | version
+
+  Global: -s <serial>, --ui (show the screen after acting), --settle <ms>, --nth N, --first, --re,
+          --shot (x,y are pixels of the last screenshot, not of the screen),
+          --no-server (plain adb shell and uiautomator, as on devices the server cannot run on)
+
+  Selectors match text, content-desc and resource-id; a match that is not itself
+  clickable resolves to its nearest clickable ancestor. An ambiguous selector
+  exits 2 and lists the candidates rather than guessing.
+
+  adbax ui
+  adbax tap "Sign in" --ui
+  adbax type you@example.com --into Email --enter
+  adbax scroll-to "Delete account" --tap
+`;
+
+export async function main(argv) {
+  const { cmd, pos, flags } = parseArgs(argv);
+  if (!cmd || cmd === 'help' || flags.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (cmd === 'version' || flags.version) {
+    const { createRequire } = await import('node:module');
+    process.stdout.write(createRequire(import.meta.url)('../package.json').version + '\n');
+    return 0;
+  }
+  const run = COMMANDS[cmd];
+  if (!run) throw new AdbaxError(`unknown command "${cmd}". Run \`adbax help\`.`);
+
+  let dev = null;
+  const ctx = {
+    pos,
+    flags,
+    out: (s) => process.stdout.write(s + '\n'),
+    async device() {
+      if (!dev) {
+        const serverOff = flags['no-server'] || /^(0|off|false|no)$/i.test(process.env.ADBAX_SERVER || '');
+        dev = new Device(await resolveSerial(flags), { server: !serverOff, settle: flags.settle });
+      }
+      return dev;
+    },
+  };
+  await run(ctx);
+  return 0;
+}

package/src/commands/apps.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+import path from 'node:path';
+import { fail, q } from '../util.js';
+import { maybeUi } from './common.js';
+
+export async function apps(ctx) {
+  const filter = (ctx.pos[0] || '').toLowerCase();
+  const dev = await ctx.device();
+  const out = await dev.adb.shell(`pm list packages ${ctx.flags.system ? '' : '-3'}`, { soft: true });
+  ctx.out(out.split('\n').map((l) => l.replace('package:', '').trim()).filter(Boolean)
+    .filter((p) => !filter || p.toLowerCase().includes(filter)).sort().join('\n'));
+}
+
+/** Starts the launcher activity and waits until it is drawn (`am start -W`). */
+export async function launch(ctx) {
+  const pkg = ctx.pos[0] || fail('usage: adbax launch <package>');
+  const dev = await ctx.device();
+  const comp = (await dev.adb.shell(
+    `cmd package resolve-activity --brief -c android.intent.category.LAUNCHER ${q(pkg)} | tail -n 1`, { soft: true })).trim();
+  if (comp.includes('/')) await dev.adb.shell(`am start -W -n ${q(comp)}`, { soft: true, timeout: 30_000 });
+  else {
+    const out = await dev.adb.shell(`monkey -p ${q(pkg)} -c android.intent.category.LAUNCHER 1 2>&1 || true`, { soft: true });
+    if (/No activities found/i.test(out)) fail(`${pkg} is not installed or has no launcher activity. \`adbax apps\` lists packages.`, 2);
+  }
+  ctx.out(`launched ${pkg} -> ${await dev.where()}`);
+  await maybeUi(ctx);
+}
+
+export async function start(ctx) {
+  const comp = ctx.pos[0] || fail('usage: adbax start <pkg/.Activity>');
+  const dev = await ctx.device();
+  ctx.out((await dev.adb.shell(`am start -W -n ${q(comp)}`)).trim());
+  await maybeUi(ctx);
+}
+
+export async function stop(ctx) {
+  const pkg = ctx.pos[0] || fail('usage: adbax stop <package>');
+  await (await ctx.device()).adb.shell(`am force-stop ${q(pkg)}`);
+  ctx.out('stopped ' + pkg);
+}
+
+export async function clear(ctx) {
+  const pkg = ctx.pos[0] || fail('usage: adbax clear <package>');
+  ctx.out((await (await ctx.device()).adb.shell(`pm clear ${q(pkg)}`)).trim());
+}
+
+/**
+ * -r -g -t: replace, grant runtime permissions, allow test builds. Several
+ * files (a base APK plus splits) go in as one install-multiple.
+ */
+export async function install(ctx) {
+  if (!ctx.pos.length) fail('usage: adbax install <file.apk> [split.apk ...]');
+  const files = ctx.pos.map((f) => path.resolve(f));
+  const dev = await ctx.device();
+  const verb = files.length > 1 ? 'install-multiple' : 'install';
+  ctx.out((await dev.adb.run([verb, '-r', '-g', '-t', ...files], { timeout: 300_000 })).trim());
+}
+
+export async function uninstall(ctx) {
+  const pkg = ctx.pos[0] || fail('usage: adbax uninstall <package>');
+  ctx.out((await (await ctx.device()).adb.run(['uninstall', pkg])).trim());
+}
+
+export async function deeplink(ctx) {
+  const url = ctx.pos[0] || fail('usage: adbax deeplink <url> [package]');
+  const dev = await ctx.device();
+  const pkg = ctx.pos[1] ? ` -p ${q(ctx.pos[1])}` : '';
+  ctx.out((await dev.adb.shell(`am start -W -a android.intent.action.VIEW -d ${q(url)}${pkg}`, { soft: true })).trim());
+  ctx.out('-> ' + await dev.where());
+  await maybeUi(ctx);
+}
+
+export async function perm(ctx) {
+  const [action, pkg, ...perms] = ctx.pos;
+  if (!['grant', 'revoke'].includes(action) || !pkg || !perms.length) {
+    fail('usage: adbax perm <grant|revoke> <package> <PERMISSION...>');
+  }
+  const dev = await ctx.device();
+  for (const p of perms) {
+    const full = p.includes('.') ? p : 'android.permission.' + p.toUpperCase();
+    await dev.adb.shell(`pm ${action} ${q(pkg)} ${q(full)}`, { soft: true });
+    ctx.out(`${action} ${full}`);
+  }
+}
+
+export async function perms(ctx) {
+  const pkg = ctx.pos[0] || fail('usage: adbax perms <package>');
+  const out = await (await ctx.device()).adb.shell(`dumpsys package ${q(pkg)} | sed -n '/runtime permissions:/,/^$/p'`, { soft: true });
+  ctx.out(out.trim() || '(none granted)');
+}

package/src/commands/common.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+import { parseTree, render, rowRecord } from '../tree.js';
+
+/** What resolve() needs from a device. */
+export const selectorSource = (dev) => ({
+  nodes: () => dev.tree(),
+  lastRows: () => dev.lastRows(),
+  where: () => dev.where(),
+});
+
+export const selectorOptions = (flags) => ({ nth: flags.nth, first: !!flags.first, regex: !!flags.re });
+
+/** Prints the screen. The server names the top activity with the dump; the shell asks dumpsys. */
+export async function showUi(ctx, { afterAction = false } = {}) {
+  const { flags } = ctx;
+  const dev = await ctx.device();
+  const dump = await dev.dump({ afterAction, windows: !!flags.windows });
+  if (flags.raw) return ctx.out(dump.xml);
+  const nodes = parseTree(dump.xml);
+  const rows = dev.saveRows(nodes, !!flags.all);
+  if (flags.json) return ctx.out(JSON.stringify(rows.map(rowRecord), null, 2));
+  const [where, size] = await Promise.all([(dump.head && dump.head.activity) || dev.where(), dev.screenSize(dump.xml)]);
+  ctx.out(`# ${where}   ${size.width}x${size.height}   ${rows.length} nodes` +
+    (flags.all ? ' (--all)' : '') + (dump.busy ? '   (still changing: read before it went quiet)' : ''));
+  ctx.out(render(rows, { full: !!flags.full }));
+  if (!flags.all) ctx.out('# tap by text: adbax tap "Label"   or by index: adbax tap 3   (--all shows every node)');
+}
+
+/** `--ui` on an action: show the screen it led to. */
+export async function maybeUi(ctx) {
+  if (ctx.flags.ui) await showUi(ctx, { afterAction: true });
+}
+
+export const KEYS = {
+  back: 4, home: 3, recents: 187, apps: 187, enter: 66, tab: 61, del: 67, delete: 67,
+  esc: 111, escape: 111, up: 19, down: 20, left: 21, right: 22, menu: 82, search: 84,
+  power: 26, volup: 24, voldown: 25, camera: 27, space: 62, dpad_center: 23, ok: 23,
+  wake: 224, sleep: 223, notifications: 83, mute: 164, call: 5, endcall: 6, paste: 279,
+};

package/src/commands/device.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { adbRaw, emulatorBinary, listDevices, pinSerial, pinnedSerial, runEmulatorSync } from '../adb.js';
+import { cachePath, delay, fail } from '../util.js';
+
+export async function devices(ctx) {
+  const list = await listDevices();
+  if (!list.length) return ctx.out('no devices');
+  const pin = pinnedSerial();
+  for (const d of list) ctx.out(`${d.serial === pin ? '*' : ' '} ${d.serial.padEnd(22)} ${d.state.padEnd(10)} ${d.model}`);
+}
+
+export async function use(ctx) {
+  const s = ctx.pos[0];
+  if (!s || s === '-') {
+    pinSerial(null);
+    return ctx.out('device pin cleared');
+  }
+  pinSerial(s);
+  ctx.out('pinned ' + s);
+}
+
+export async function avds(ctx) {
+  ctx.out(runEmulatorSync(['-list-avds']).trim());
+}
+
+/** Boots an AVD, waits for sys.boot_completed, unlocks it and pins it. */
+export async function boot(ctx) {
+  const { flags } = ctx;
+  const avd = ctx.pos[0] || fail('usage: adbax boot <avd> [--cold] [--wipe] [--no-window]   (see `adbax avds`)');
+  const before = new Set((await listDevices()).map((d) => d.serial));
+  const args = ['-avd', avd];
+  if (flags.cold) args.push('-no-snapshot-load');
+  if (flags.wipe) args.push('-wipe-data');
+  if (flags['no-window']) args.push('-no-window', '-no-audio');
+  const logFile = cachePath(`emulator-${avd}.log`);
+  const log = fs.openSync(logFile, 'w');
+  // The launcher execs into the emulator itself, so an exit here is the
+  // emulator giving up: an unknown AVD name, or one that is already running.
+  const child = spawn(emulatorBinary(), args, { detached: true, stdio: ['ignore', log, log] });
+  let exitCode = null;
+  child.on('exit', (code) => { exitCode = code; });
+  child.unref();
+  process.stderr.write('booting ' + avd);
+  let serial = null;
+  for (let i = 0; i < 180; i++) {
+    await delay(2000);
+    if (exitCode) fail(`\nthe emulator exited with status ${exitCode}. Log: ${logFile}`);
+    process.stderr.write('.');
+    if (!serial) serial = ((await listDevices()).find((d) => !before.has(d.serial)) || {}).serial || null;
+    if (!serial) continue;
+    const booted = (await adbRaw(['-s', serial, 'shell', 'getprop', 'sys.boot_completed'], { soft: true })).trim();
+    if (booted === '1') {
+      await adbRaw(['-s', serial, 'shell', 'input', 'keyevent', '82'], { soft: true });
+      pinSerial(serial);
+      process.stderr.write('\n');
+      return ctx.out(`booted ${serial} (pinned)`);
+    }
+  }
+  fail(`\ntimed out after 6 min. Log: ${logFile}`);
+}
+
+export async function kill(ctx) {
+  if (ctx.flags.all) {
+    for (const d of await listDevices()) {
+      if (d.serial.startsWith('emulator-')) await adbRaw(['-s', d.serial, 'emu', 'kill'], { soft: true });
+    }
+  } else {
+    await (await ctx.device()).adb.run(['emu', 'kill'], { soft: true });
+  }
+  ctx.out('sent kill');
+}