@flxapps/adbax 0.0.0-stage → 0.1.0

package/src/select.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+import { kind, label, shortId, tappable } from './tree.js';
+import { fail } from './util.js';
+
+const norm = (s) => (s || '').toLowerCase().trim();
+
+/**
+ * How well a node matches a query: exact before prefix before substring, and
+ * within each, text before content-desc before hint and resource-id.
+ */
+function score(n, q, re) {
+  const fields = [n.text, n.desc, n.hint, shortId(n), n.id];
+  let best = 0;
+  fields.forEach((f, i) => {
+    if (!f) return;
+    const weight = i === 0 ? 0 : i === 1 ? 1 : 4;
+    if (re) { if (re.test(f)) best = Math.max(best, 80 - weight); return; }
+    const nf = norm(f);
+    if (nf === q) best = Math.max(best, 100 - weight);
+    else if (nf.startsWith(q)) best = Math.max(best, 75 - weight);
+    else if (nf.includes(q)) best = Math.max(best, 55 - weight);
+  });
+  return best;
+}
+
+/** The best-scoring nodes for a query; several only when they tie (within 4 points). */
+export function match(nodes, query, { regex = false, preferTappable = false } = {}) {
+  const re = regex ? new RegExp(query, 'i') : null;
+  const q = norm(query);
+  const hits = nodes
+    .filter((n) => n.w > 0 && n.h > 0)
+    .map((n) => ({ n, s: score(n, q, re) }))
+    .filter((h) => h.s > 0);
+  if (!hits.length) return [];
+  // A tap prefers something you can actually tap.
+  if (preferTappable) hits.forEach((h) => { if (tappable(h.n)) h.s += 12; });
+  hits.sort((a, b) => b.s - a.s || a.n.i - b.n.i);
+  const top = hits[0].s;
+  return hits.filter((h) => h.s >= top - 4).map((h) => h.n);
+}
+
+export function tappableAncestor(n) {
+  for (let c = n; c; c = c.parent) if (c.clickable && c.enabled) return c;
+  return n;
+}
+
+/** One line describing a node, for messages. */
+export function describe(n) {
+  const sid = shortId(n);
+  return `${kind(n)} ${JSON.stringify(label(n))}${sid ? ' id=' + sid : ''}`;
+}
+
+/**
+ * Resolves a selector to a point: "540,1200" is taken as is, "3" or "#3" is a
+ * row of the last `adbax ui`, anything else is matched against a fresh tree.
+ *
+ * `ctx` supplies the tree (`nodes()`), the last rows (`lastRows()`) and a line
+ * naming the current screen for error messages (`where()`).
+ */
+export async function resolve(sel, ctx, { forTap = false, nth, first = false, regex = false } = {}) {
+  if (/^-?\d+\s*,\s*-?\d+$/.test(sel)) {
+    const [x, y] = sel.split(',').map((v) => +v.trim());
+    return { x, y, how: 'coords' };
+  }
+  if (/^#?\d+$/.test(sel)) {
+    const idx = +sel.replace('#', '');
+    const rows = ctx.lastRows();
+    if (!rows) fail('no cached dump. Run `adbax ui` first, or select by text.');
+    const r = rows[idx] || fail(`index ${idx} not in the last dump (${rows.length} rows).`);
+    return { x: r.x, y: r.y, how: `[${idx}] ${r.k} ${JSON.stringify(r.label)}` };
+  }
+  const nodes = await ctx.nodes();
+  let hits = match(nodes, sel, { regex, preferTappable: forTap });
+  if (!hits.length) {
+    fail(`no node matching ${JSON.stringify(sel)}.\n       Current screen: ${await ctx.where()}\n` +
+      '       Run `adbax ui` to see what is there.');
+  }
+  if (nth !== undefined) {
+    const k = +nth;
+    if (!hits[k]) fail(`--nth ${k} out of range (${hits.length} matches).`);
+    hits = [hits[k]];
+  }
+  if (hits.length > 1 && !first) {
+    const lines = hits.map((n, k) => `  --nth ${k}  ${describe(n)} @${n.cx},${n.cy}`);
+    fail(`${JSON.stringify(sel)} matches ${hits.length} nodes:\n${lines.join('\n')}\n` +
+      '       Narrow the query, or add --nth N / --first.', 2);
+  }
+  const hit = hits[0];
+  const target = forTap && !tappable(hit) ? tappableAncestor(hit) : hit;
+  const sid = shortId(target);
+  return {
+    x: target.cx, y: target.cy, node: target,
+    how: `${kind(target)} ${JSON.stringify(label(hit))}${sid ? ' id=' + sid : ''}`,
+  };
+}

package/src/tree.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * The accessibility tree as `uiautomator dump` writes it (the on-device server
+ * writes the same format), parsed into nodes and reduced to the rows worth
+ * showing.
+ */
+
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+function unescape(s) {
+  return s.replace(/&(lt|gt|amp|quot|apos|#\d+|#x[0-9a-f]+);/gi, (m, e) => {
+    if (e[0] !== '#') return ENTITIES[e];
+    return String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : +e.slice(1));
+  });
+}
+
+function attributes(s) {
+  const a = {};
+  const re = /([\w:-]+)="([^"]*)"/g;
+  let m;
+  while ((m = re.exec(s))) a[m[1]] = unescape(m[2]);
+  return a;
+}
+
+/** {width, height, rotation} from the <hierarchy> element, where the server provides it. */
+export function screenInfo(xml) {
+  const m = xml.match(/<hierarchy([^>]*)>/);
+  if (!m) return {};
+  const a = attributes(m[1]);
+  return { width: +a.width || 0, height: +a.height || 0, rotation: +a.rotation || 0 };
+}
+
+export function parseTree(xml) {
+  const nodes = [];
+  const stack = [];
+  const re = /<node((?:\s+[\w:-]+="[^"]*")*)\s*(\/?)>|<\/node>/g;
+  let m;
+  while ((m = re.exec(xml))) {
+    if (m[0] === '</node>') { stack.pop(); continue; }
+    const a = attributes(m[1]);
+    const b = (a.bounds || '').match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/);
+    const n = {
+      i: nodes.length,
+      cls: (a.class || '').split('.').pop(),
+      fullCls: a.class || '',
+      text: (a.text || '').trim(),
+      desc: (a['content-desc'] || '').trim(),
+      hint: (a.hint || '').trim(),
+      id: a['resource-id'] || '',
+      pkg: a.package || '',
+      window: a.window || '',
+      clickable: a.clickable === 'true',
+      longClickable: a['long-clickable'] === 'true',
+      checkable: a.checkable === 'true',
+      checked: a.checked === 'true',
+      selected: a.selected === 'true',
+      scrollable: a.scrollable === 'true',
+      enabled: a.enabled !== 'false',
+      focused: a.focused === 'true',
+      focusable: a.focusable === 'true',
+      password: a.password === 'true',
+      x1: b ? +b[1] : 0, y1: b ? +b[2] : 0, x2: b ? +b[3] : 0, y2: b ? +b[4] : 0,
+      parent: stack.length ? stack[stack.length - 1] : null,
+      kids: [],
+    };
+    n.w = n.x2 - n.x1;
+    n.h = n.y2 - n.y1;
+    n.cx = Math.round((n.x1 + n.x2) / 2);
+    n.cy = Math.round((n.y1 + n.y2) / 2);
+    n.editable = /EditText|AutoComplete|TextInputEditText/.test(n.fullCls) ||
+      (n.focusable && n.clickable && /Edit/.test(n.fullCls));
+    if (n.parent) n.parent.kids.push(n);
+    nodes.push(n);
+    if (!m[2]) stack.push(n);
+  }
+  return nodes;
+}
+
+/**
+ * Up to three labels from a node's descendants, for wrappers that carry none
+ * themselves. Clickable descendants are rows of their own (the star button in
+ * a list row), so their labels only count when nothing else has one.
+ */
+function descendantLabels(n, skipClickable, out = [], depth = 0) {
+  if (depth > 4 || out.length >= 3) return out;
+  for (const k of n.kids) {
+    if (skipClickable && (k.clickable || k.editable)) continue;
+    const t = k.text || k.desc;
+    if (t && !out.includes(t)) out.push(t);
+    descendantLabels(k, skipClickable, out, depth + 1);
+  }
+  return out;
+}
+
+export function label(n) {
+  if (n.text) return n.text;
+  if (n.desc) return n.desc;
+  if (n.hint) return '(hint) ' + n.hint;
+  const own = descendantLabels(n, true);
+  return (own.length ? own : descendantLabels(n, false)).join(' / ');
+}
+
+/** "submit" for "com.example:id/submit" inside com.example; the full id otherwise. */
+export function shortId(n) {
+  if (!n.id) return '';
+  const m = n.id.match(/^([^:]+):id\/(.+)$/);
+  if (!m) return n.id;
+  return m[1] === n.pkg ? m[2] : n.id;
+}
+
+export function kind(n) {
+  if (n.editable) return 'EDIT';
+  if (n.checkable) return n.checked ? 'CHK[x]' : 'CHK[ ]';
+  if (n.clickable || n.longClickable) return 'TAP';
+  if (n.scrollable) return 'SCRL';
+  return 'TXT';
+}
+
+export const actionable = (n) => n.clickable || n.longClickable || n.checkable || n.editable;
+export const tappable = (n) => n.clickable || n.editable || n.checkable;
+
+/**
+ * Reduces the raw tree to the rows worth printing: everything you can act on,
+ * scroll containers, and labelled nodes that no actionable ancestor has
+ * already absorbed. `all` keeps absorbed labels and unlabelled nodes with ids.
+ */
+export function interesting(nodes, all = false) {
+  const absorbed = new Set();
+  const picked = new Set();
+  const rows = [];
+  for (const n of nodes) {
+    if (n.w <= 0 || n.h <= 0 || !actionable(n)) continue;
+    // A clickable wrapper eats the labels of its descendants.
+    const stack = n.kids.slice();
+    while (stack.length) {
+      const k = stack.pop();
+      if (k.clickable || k.editable || k.scrollable) continue;
+      absorbed.add(k.i);
+      stack.push(...k.kids);
+    }
+    rows.push(n);
+    picked.add(n.i);
+  }
+  for (const n of nodes) {
+    if (n.w <= 0 || n.h <= 0 || picked.has(n.i)) continue;
+    if (n.scrollable) { rows.push(n); continue; }
+    if (absorbed.has(n.i) && !all) continue;
+    if (n.text || n.desc) rows.push(n);
+    else if (all && n.id) rows.push(n);
+  }
+  rows.sort((a, b) => a.i - b.i);
+  return rows;
+}
+
+export function renderRow(n, idx, { full = false } = {}) {
+  const parts = [`[${idx}]`, kind(n).padEnd(6)];
+  const l = label(n);
+  parts.push(JSON.stringify(l));
+  const sid = shortId(n);
+  if (sid) parts.push('id=' + sid);
+  if (full) parts.push('cls=' + n.cls);
+  if (n.window && n.window !== 'application') parts.push('win=' + n.window);
+  parts.push(`@${n.cx},${n.cy}`);
+  parts.push(`${n.w}x${n.h}`);
+  if (!n.enabled) parts.push('!disabled');
+  if (n.focused) parts.push('*focused');
+  if (n.selected) parts.push('*selected');
+  if (n.password) parts.push('*password');
+  if (n.scrollable && !n.clickable) parts.push('*scrollable');
+  return '  ' + parts.join('  ');
+}
+
+export function render(rows, opts) {
+  return rows.map((n, idx) => renderRow(n, idx, opts)).join('\n');
+}
+
+/** The compact form `adbax ui --json` prints and `tap <index>` reads back. */
+export function rowRecord(n) {
+  return {
+    i: n.i, k: kind(n), label: label(n), id: shortId(n), fullId: n.id, cls: n.cls,
+    x: n.cx, y: n.cy, w: n.w, h: n.h, enabled: n.enabled, checked: n.checked,
+  };
+}

package/src/util.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** An error the CLI prints as `adbax: <message>` and exits with `code`. */
+export class AdbaxError extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function fail(message, code = 1) {
+  throw new AdbaxError(message, code);
+}
+
+export const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Quotes one word for the device's /bin/sh. */
+export function q(s) {
+  s = String(s);
+  return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+export const CACHE_DIR = process.env.ADBAX_CACHE ||
+  path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'adbax');
+
+export function cachePath(name) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  return path.join(CACHE_DIR, name);
+}
+
+export function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+export function readText(file) {
+  try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
+}
+
+export function writeJson(file, value) {
+  fs.writeFileSync(file, JSON.stringify(value));
+}
+
+/** A filesystem-safe form of a device serial ("emulator-5554", "192.168.1.5:5555"). */
+export const serialKey = (serial) => serial.replace(/[^\w.-]/g, '_');
+
+const T0 = performance.now();
+/** ADBAX_TRACE=1 prints every adb call and server request with its duration to stderr. */
+export const tracing = !!process.env.ADBAX_TRACE;
+export function trace(what, started) {
+  if (!tracing) return;
+  const now = performance.now();
+  process.stderr.write(`[${(now - T0).toFixed(0).padStart(5)} ms] ${(now - started).toFixed(0).padStart(4)} ms  ${what}\n`);
+}