android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/scripts/device_ui.mjs

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+// device_ui.mjs — HarmonyOS device UI driver facade (CLI; core logic in device_ui_core.mjs).
+//
+// Contract: argument shapes, single-line JSON on stdout, daemon protocol
+// (<work-dir>/.hypium/daemon.json + {"argv":[...]} wire protocol).
+// Run: node <plugin-path>/scripts/device_ui.mjs [--device SN] [--work-dir DIR] <command> [args]
+// Deps: hypium-driver (Node >=20.11.1), resolved lazily by device_ui_core.loadDriverPkg:
+//   scripts/node_modules (after `npm install` in a repo checkout) → global npm root →
+//   auto `npm install -g hypium-driver@<pinned>`. Pure-hdc commands need none of it.
+//
+// Commands (basic): devices launch observe tap input swipe key density serve shutdown
+// Commands (actions): double-tap long-press clear-text drag fling pinch scroll-until gesture rotate;
+//               swipe supports two-point --from/--to; selectors support --regex/--starts/--ends;
+//               observe elements sparsely expose checked/selected/focused/enabled.
+//               clear-text/scroll-until use device-side By addressing (sole component-handle exemption; uniqueness guard kept).
+// Commands (extended, hypium-driver capability surface):
+//   driver-based: wait-idle unlock wake info window record launch-uri app
+//   pure hdc (no driver connection): shell hdc hilog toast file
+// Addressing: tap/input/long-press/double-tap take the native findComponents fast path (unique hit closes device-side,
+//       ~4-30x faster than full-tree dump; 0/multi hits, --desc, or needing bound fall back to host active-layer
+//       disambiguation; ghost filtering unchanged). observe still uses the host full tree.
+// No-console rule: daemon spawns with a hidden console (windowsHide), children inherit; never a cmd popup.
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import * as core from "./device_ui_core.mjs";
+
+core.captureStdout(); // must run before hypium-driver loads: library logs go to stderr, stdout emits JSON only
+
+const SELF = fileURLToPath(import.meta.url);
+const DAEMON_CONNECT_TIMEOUT = 3000;
+const REQUEST_TIMEOUT = 300000;
+const SERVE_READY_TIMEOUT = 15000;
+const IDLE_TIMEOUT = 1800000;
+
+// --------------------------------------------------------------------------
+// Output + lightweight call tracing (<work-dir>/.hypium/calls.jsonl)
+// --------------------------------------------------------------------------
+let T0 = null, CMD = null, LOG_DIR = null;
+function trace(obj, payload) {
+  if (!LOG_DIR) return;
+  try {
+    const rec = { cmd: CMD, elapsed_ms: T0 == null ? null : Math.round(performance.now() - T0),
+      bytes: Buffer.byteLength(payload, "utf8"), chars: payload.length,
+      count: obj.count, ok: obj.ok };
+    const d = path.join(LOG_DIR, ".hypium");
+    fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(path.join(d, "calls.jsonl"), JSON.stringify(rec) + "\n");
+  } catch { /* tracing failure must not affect the main flow */ }
+}
+function emit(obj) {
+  const s = JSON.stringify(obj);
+  core.writeStdoutLine(s);
+  trace(obj, s);
+}
+function fail(reason, extra = {}, code = 1) {
+  emit({ ok: false, error: reason, ...extra });
+  process.exit(code);
+}
+
+// --------------------------------------------------------------------------
+// Argument parsing (hand-written, zero dependencies)
+// Kept independent of _lib/common.mjs parseFlags: this drives per-command flag tables with
+// typed kinds (xy/xyxy/codes/track/rest switches), which the shared flat parser does not model.
+// --------------------------------------------------------------------------
+const SEL_FLAGS = { "--text": "text", "--contains": "contains", "--regex": "regex",
+  "--starts": "starts", "--ends": "ends", "--key": "key", "--desc": "desc", "--type": "type" };
+
+// Per-command flag table: flag -> [target key, kind]  kinds: s=string i=int f=float b=switch xy=two ints xyxy=four ints codes=comma-separated ints
+const CMD_FLAGS = {
+  devices: {},
+  launch: { "--bundle": ["bundle", "s"], "--ability": ["ability", "s"], "--restart": ["restart", "b"] },
+  observe: { "--out": ["out", "s"], "-o": ["out", "s"], "--all": ["all", "b"], "--raw": ["raw", "b"],
+    "--screenshot": ["screenshot", "b"], "--bound": ["bound", "b"], "--limit": ["limit", "i"], ...selFlags() },
+  tap: { ...selFlags(), "--xy": ["xy", "xy"], "--nth": ["nth", "i"] },
+  "double-tap": { ...selFlags(), "--xy": ["xy", "xy"], "--nth": ["nth", "i"] },
+  "long-press": { ...selFlags(), "--xy": ["xy", "xy"], "--nth": ["nth", "i"], "--press-ms": ["pressMs", "i"] },
+  input: { ...selFlags(), "--xy": ["xy", "xy"], "--nth": ["nth", "i"], "--value": ["value", "s"] },
+  swipe: { "--dir": ["dir", "s"], "--distance": ["distance", "i"], "--speed": ["speed", "i"],
+    "--from": ["from", "xy"], "--to": ["to", "xy"] },
+  drag: { "--from": ["from", "xy"], "--to": ["to", "xy"], "--speed": ["speed", "i"] },
+  fling: { "--dir": ["dir", "s"], "--speed": ["speed", "i"] },
+  pinch: { "--mode": ["mode", "s"], "--area": ["area", "xyxy"], "--scale": ["scale", "f"],
+    "--speed": ["speed", "i"], ...selFlags(), "--nth": ["nth", "i"] },
+  "clear-text": { ...selFlags(), "--nth": ["nth", "i"] },
+  "scroll-until": { ...selFlags(), "--nth": ["nth", "i"], "--container-key": ["containerKey", "s"],
+    "--container-type": ["containerType", "s"], "--container-nth": ["containerNth", "i"] },
+  gesture: { "--track": ["tracks", "track"], "--speed": ["speed", "i"], "--sampling-ms": ["samplingMs", "i"] },
+  key: { "--back": ["back", "b"], "--home": ["home", "b"], "--power": ["power", "b"],
+    "--code": ["code", "i"], "--combo": ["combo", "codes"] },
+  rotate: { "--deg": ["deg", "i"] },
+  density: {},
+  // Extended: driver-based
+  "wait-idle": { "--idle-ms": ["idleMs", "i"], "--timeout-ms": ["timeoutMs", "i"] },
+  unlock: {},
+  wake: {},
+  info: {},
+  window: { "--wbundle": ["wbundle", "s"], "--title": ["title", "s"], "--focused": ["focused", "b"],
+    "--op": ["wop", "s"], "--w": ["w", "i"], "--h": ["h", "i"], "--x": ["x", "i"], "--y": ["y", "i"], "--dir": ["dir", "s"] },
+  record: { "--op": ["rop", "s"], "--out": ["out", "s"], "-o": ["out", "s"] },
+  "launch-uri": { "--action": ["uaction", "s"], "--uri": ["uri", "s"], "--extra": ["extra", "s"] },
+  app: { "--op": ["aop", "s"], "--bundle": ["bundle", "s"], "--path": ["path", "s"] },
+  // Extended: pure hdc (no driver connection)
+  shell: { "--cmd": ["cmd", "s"], "--timeout-ms": ["timeoutMs", "i"] },
+  hdc: { "--args": ["args", "rest"] },
+  hilog: { "--grep": ["grep", "s"], "--lines": ["lines", "i"], "--timeout-ms": ["timeoutMs", "i"] },
+  toast: { "--timeout-ms": ["timeoutMs", "i"] },
+  file: { "--op": ["fop", "s"], "--local": ["local", "s"], "--remote": ["remote", "s"] },
+  serve: { "--foreground": ["foreground", "b"] },
+  shutdown: {},
+};
+function selFlags() {
+  const o = {};
+  for (const [f, k] of Object.entries(SEL_FLAGS)) o[f] = [k, "s"];
+  return o;
+}
+const REQUIRED = { launch: ["bundle"], input: ["value"], swipe: [], drag: ["from", "to"],
+  fling: ["dir"], pinch: ["mode"], rotate: ["deg"], shell: ["cmd"] };
+const DIRS = new Set(["up", "down", "left", "right"]);
+
+function parseInt_(v, flag) {
+  const n = Number(v);
+  if (!Number.isInteger(n)) throw new core.DeviceUIError(`${flag} 需要整数,得到: ${v}`);
+  return n;
+}
+export function parseArgv(argv) {
+  const opts = { device: null, workDir: null };
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--device" || t === "-d") opts.device = argv[++i];
+    else if (t === "--work-dir") opts.workDir = argv[++i];
+    else if (t.startsWith("--device=")) opts.device = t.slice(9);
+    else if (t.startsWith("--work-dir=")) opts.workDir = t.slice(11);
+    else break;
+  }
+  const cmd = argv[i++];
+  if (!cmd || !(cmd in CMD_FLAGS)) {
+    throw new core.DeviceUIError(`未知或缺失命令: ${cmd || "(空)"};可用: ${Object.keys(CMD_FLAGS).join(" ")}`);
+  }
+  const table = CMD_FLAGS[cmd];
+  for (; i < argv.length; i++) {
+    let t = argv[i], inline = null;
+    const eq = t.indexOf("=");
+    if (t.startsWith("--") && eq > 0) { inline = t.slice(eq + 1); t = t.slice(0, eq); }
+    const spec = table[t];
+    if (!spec) throw new core.DeviceUIError(`命令 ${cmd} 不认识参数: ${t}`);
+    const [key, kind] = spec;
+    const next = () => { if (inline != null) return inline; const v = argv[++i]; if (v == null) throw new core.DeviceUIError(`${t} 缺值`); return v; };
+    if (kind === "b") opts[key] = true;
+    else if (kind === "s") opts[key] = next();
+    else if (kind === "i") opts[key] = parseInt_(next(), t);
+    else if (kind === "f") { opts[key] = Number(next()); if (!Number.isFinite(opts[key])) throw new core.DeviceUIError(`${t} 需要数值,得到非法值`); }
+    else if (kind === "xy") opts[key] = [parseInt_(next(), t), parseInt_(argv[++i], t)];
+    else if (kind === "xyxy") opts[key] = [parseInt_(next(), t), parseInt_(argv[++i], t), parseInt_(argv[++i], t), parseInt_(argv[++i], t)];
+    else if (kind === "codes") opts[key] = next().split(",").map((c) => parseInt_(c.trim(), t));
+    else if (kind === "rest") { opts[key] = argv.slice(i + 1); i = argv.length; } // consume everything remaining (hdc passthrough)
+    else if (kind === "track") {
+      // each --track is one finger trajectory: "x,y[,ms];x,y[,ms];..."
+      const pts = next().split(";").map((seg) => seg.split(",").map((n) => parseInt_(n.trim(), t)));
+      (opts[key] ||= []).push(pts);
+    }
+  }
+  for (const k of REQUIRED[cmd] || []) {
+    if (opts[k] == null) throw new core.DeviceUIError(`${cmd} 缺少必填参数 --${k === "pressMs" ? "press-ms" : k}`);
+  }
+  if ((cmd === "swipe" && !opts.from) || cmd === "fling") {
+    if (!opts.dir || !DIRS.has(opts.dir)) throw new core.DeviceUIError(`${cmd} 需要 --dir up|down|left|right(或 swipe 用 --from/--to 两点式)`);
+  }
+  if (cmd === "pinch" && !["in", "out"].includes(opts.mode)) throw new core.DeviceUIError("pinch 需要 --mode in|out");
+  if (cmd === "gesture" && !opts.tracks) throw new core.DeviceUIError('gesture 需要 ≥1 个 --track "x,y[,ms];x,y[,ms];…"');
+  return { cmd, opts };
+}
+
+// --------------------------------------------------------------------------
+// daemon(serve/client)
+// --------------------------------------------------------------------------
+const daemonFile = (wd) => path.join(wd || ".", ".hypium", "daemon.json");
+function readDaemon(wd) {
+  try { return JSON.parse(fs.readFileSync(daemonFile(wd), "utf8")); } catch { return null; }
+}
+function removeDaemonFile(wd) {
+  try { fs.rmSync(daemonFile(wd), { force: true }); } catch { /* ignore */ }
+}
+function tryPort(port, timeout) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: "127.0.0.1", port });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout, () => done(false));
+    s.once("connect", () => done(true));
+    s.once("error", () => done(false));
+  });
+}
+async function daemonAlive(opts) {
+  const info = readDaemon(opts.workDir);
+  if (!info) return null;
+  if (opts.device && info.device && info.device !== opts.device) return null;
+  if (await tryPort(info.port, DAEMON_CONNECT_TIMEOUT)) return info;
+  removeDaemonFile(opts.workDir); // unreachable port = daemon dead; remove stale daemon.json
+  return null;
+}
+function requestDaemon(port, payload, timeout) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: "127.0.0.1", port });
+    let buf = "";
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout, () => done(null));
+    s.once("error", () => done(null));
+    s.once("connect", () => s.write(JSON.stringify(payload) + "\n"));
+    s.on("data", (c) => {
+      buf += c.toString("utf8");
+      const i = buf.indexOf("\n");
+      if (i >= 0) { try { done(JSON.parse(buf.slice(0, i))); } catch { done(null); } }
+    });
+    s.once("end", () => { if (buf && !buf.includes("\n")) { try { done(JSON.parse(buf)); } catch { done(null); } } });
+  });
+}
+function forwardArgv(opts) {
+  // rewrite --work-dir to its absolutized value (daemon cwd != caller cwd); everything else as-is
+  const argv = process.argv.slice(2);
+  if (opts.workDir) {
+    for (let i = 0; i < argv.length; i++) {
+      if (argv[i] === "--work-dir" && i + 1 < argv.length) { argv[i + 1] = opts.workDir; break; }
+      if (argv[i].startsWith("--work-dir=")) { argv[i] = "--work-dir=" + opts.workDir; break; }
+    }
+  }
+  return argv;
+}
+async function clientTry(cmd, opts) {
+  if (cmd === "serve") return null;
+  const info = readDaemon(opts.workDir);
+  if (!info) return null;
+  if (opts.device && info.device && info.device !== opts.device) return null;
+  if (!(await tryPort(info.port, DAEMON_CONNECT_TIMEOUT))) {
+    if (cmd !== "shutdown") removeDaemonFile(opts.workDir); // shutdown left for cmdShutdown to clean up and report truthfully
+    return null;
+  }
+  const payload = cmd === "shutdown" ? { shutdown: true } : { argv: forwardArgv(opts) };
+  return requestDaemon(info.port, payload, REQUEST_TIMEOUT);
+}
+
+async function serveLoop(opts) {
+  // resident listener: connect the device once, reuse one driver per command; always disconnect on exit (release device singleton/forwarding)
+  core.selfHealDevice(opts.device);
+  let d;
+  try { d = await core.connectWithReclaim(opts.device, opts.workDir); }
+  catch (e) { fail(e.reason || String(e.message || e), e.extra || {}); }
+  const srv = net.createServer();
+  let idleTimer = null, closing = false;
+  const shutdownSelf = async () => {
+    if (closing) return; closing = true;
+    try { srv.close(); } catch { /* ignore */ }
+    await core.disconnect(d);
+    core.restoreScreenTimeout(opts.device); // undo selfHealDevice's screen-off override
+    removeDaemonFile(opts.workDir);
+    process.exit(0);
+  };
+  const resetIdle = () => { clearTimeout(idleTimer); idleTimer = setTimeout(shutdownSelf, IDLE_TIMEOUT); };
+  process.on("SIGTERM", shutdownSelf);
+  process.on("SIGINT", shutdownSelf);
+  srv.on("connection", (conn) => {
+    resetIdle();
+    let buf = "";
+    conn.setTimeout(REQUEST_TIMEOUT, () => conn.destroy());
+    conn.on("data", async (c) => {
+      buf += c.toString("utf8");
+      const i = buf.indexOf("\n");
+      if (i < 0) return;
+      const line = buf.slice(0, i); buf = "";
+      let result;
+      let wantShutdown = false;
+      try {
+        const req = JSON.parse(line || "{}");
+        if (req.shutdown) { wantShutdown = true; result = { ok: true, shutdown: true }; }
+        else result = await dispatch(d, req.argv || []);
+      } catch (e) {
+        result = { ok: false, error: String(e.message || e).slice(0, 300) };
+      }
+      try { conn.end(JSON.stringify(result) + "\n"); } catch { /* ignore */ }
+      if (wantShutdown) await shutdownSelf();
+    });
+    conn.on("error", () => { /* client disconnects etc., ignore */ });
+  });
+  await new Promise((res) => srv.listen(0, "127.0.0.1", res));
+  const port = srv.address().port;
+  const df = daemonFile(opts.workDir);
+  fs.mkdirSync(path.dirname(df), { recursive: true });
+  fs.writeFileSync(df, JSON.stringify({ port, device: opts.device, pid: process.pid }));
+  emit({ ok: true, action: "serve", port, device: opts.device, daemon_file: df });
+  resetIdle();
+  await new Promise(() => {}); // stay resident: only shutdown/idle/signal may exit; main's exit must not reap us
+}
+
+async function dispatch(d, argv) {
+  // daemon side: parse the forwarded argv -> execute (same action table as one-shot)
+  let parsed;
+  try { parsed = parseArgv(argv); } catch { return { ok: false, error: `daemon 无法解析命令: ${JSON.stringify(argv)}` }; }
+  const { cmd, opts } = parsed;
+  try {
+    if (cmd === "devices") return core.doDevices();
+    if (cmd === "density") {
+      const dd = core.probeDensity(opts.device);
+      return { ok: dd != null, density: dd, ...(dd == null ? { error: "密度探测失败(hidumper 无 Density 行)" } : {}) };
+    }
+    if (cmd in core.HDC_ACTIONS) return core.HDC_ACTIONS[cmd](opts); // pure hdc, no driver needed
+    if (cmd in core.ACTIONS) return await core.runAction(d, cmd, opts);
+    return { ok: false, error: `daemon 不支持命令: ${cmd}` };
+  } catch (e) {
+    if (e instanceof core.DeviceUIError) return { ok: false, error: e.reason, ...e.extra };
+    return { ok: false, error: String(e.message || e).slice(0, 300) };
+  }
+}
+
+async function cmdServe(opts) {
+  if (opts.foreground) return serveLoop(opts);
+  const info = await daemonAlive(opts);
+  if (info) {
+    emit({ ok: true, action: "serve", port: info.port, device: info.device, daemon_file: daemonFile(opts.workDir), reused: true });
+    return;
+  }
+  const raw = readDaemon(opts.workDir);
+  if (raw && opts.device && raw.device && raw.device !== opts.device) {
+    // same work-dir already holds a daemon for another device -> if alive, fail loudly (per-device work-dir contract); if dead, clean up
+    if (raw.port && (await tryPort(raw.port, DAEMON_CONNECT_TIMEOUT))) {
+      fail(`work-dir 已被 device ${raw.device} 的存活 daemon 占用(本次 --device ${opts.device})——每设备用独立 work-dir,或先对原设备 shutdown`,
+        { daemon_file: daemonFile(opts.workDir) });
+    }
+    removeDaemonFile(opts.workDir);
+  }
+  const args = [SELF];
+  if (opts.device) args.push("--device", opts.device);
+  if (opts.workDir) args.push("--work-dir", opts.workDir);
+  args.push("serve", "--foreground");
+  // No cmd popups + survival across calls, both required (measured combo: CREATE_NEW_PROCESS_GROUP|CREATE_NO_WINDOW):
+  //   hidden console — hypium-driver spawns hdc internally without windowsHide; if the daemon has no
+  //     console (DETACHED), every hdc child pops a new cmd window (measured root cause);
+  //   new process group — otherwise group signals kill the daemon when the launcher's process tree is
+  //     reaped (measured: a direct spawn with only windowsHide dies).
+  // node's detached on Windows bundles DETACHED_PROCESS|CREATE_NEW_PROCESS_GROUP, inseparable ->
+  // relay via cmd: cmd gets a hidden console with CREATE_NO_WINDOW, then `start "" /b` gives the daemon
+  // a new process group while sharing that hidden console — both properties hold. POSIX has no such issue; detached suffices.
+  let child;
+  if (os.platform() === "win32") {
+    const q = (s) => `"${s}"`;
+    const line = `start "" /b ${q(process.execPath)} ${args.map(q).join(" ")}`;
+    child = spawn("cmd.exe", ["/d", "/s", "/c", line], {
+      stdio: "ignore", windowsHide: true, windowsVerbatimArguments: true,
+    });
+  } else {
+    child = spawn(process.execPath, args, { stdio: "ignore", detached: true });
+  }
+  child.unref();
+  const deadline = Date.now() + SERVE_READY_TIMEOUT;
+  while (Date.now() < deadline) {
+    const alive = await daemonAlive(opts);
+    if (alive) {
+      emit({ ok: true, action: "serve", port: alive.port, device: alive.device, daemon_file: daemonFile(opts.workDir), detached: true });
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  fail("daemon 未在 15s 内就绪(detached serve 启动失败,检查设备/hypium-driver)", { daemon_file: daemonFile(opts.workDir) });
+}
+
+function killDaemonByPid(pid) {
+  // kill a leftover daemon by the pid in daemon.json; verify cmdline contains device_ui first, to avoid killing a reused pid
+  if (!pid) return;
+  try {
+    if (os.platform() === "win32") {
+      const ps = `$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${Number(pid)}' -ErrorAction SilentlyContinue; if ($p -and $p.CommandLine -match 'device_ui') { Stop-Process -Id $p.ProcessId -Force }`;
+      spawnSync("powershell.exe", ["-NoProfile", "-Command", ps], { timeout: 15000, windowsHide: true });
+    } else {
+      let cmdline = "device_ui";
+      try { cmdline = fs.readFileSync(`/proc/${Number(pid)}/cmdline`, "utf8"); } catch { /* macOS etc.: fall back to killing by pid */ }
+      if (cmdline.includes("device_ui")) process.kill(Number(pid), "SIGTERM");
+    }
+  } catch { /* best-effort */ }
+}
+
+async function cmdShutdown(opts) {
+  // graceful shutdown of a live daemon is handled by clientTry({"shutdown":true}); this runs only when there is no/dead daemon
+  const info = readDaemon(opts.workDir);
+  if (!info) { emit({ ok: true, action: "shutdown", note: "no daemon running" }); return; }
+  killDaemonByPid(info.pid);
+  removeDaemonFile(opts.workDir);
+  emit({ ok: true, action: "shutdown", note: "cleaned stale daemon", killed_pid: info.pid });
+}
+
+// --------------------------------------------------------------------------
+// main
+// --------------------------------------------------------------------------
+async function main() {
+  let parsed;
+  try { parsed = parseArgv(process.argv.slice(2)); }
+  catch (e) { fail(e.reason || String(e.message || e), e.extra || {}, 2); }
+  const { cmd, opts } = parsed;
+  if (opts.workDir) opts.workDir = path.resolve(opts.workDir);
+  T0 = performance.now(); CMD = cmd; LOG_DIR = opts.workDir;
+  core.ensureHdcOnPath();
+
+  if (cmd === "serve") {
+    await cmdServe(opts);
+    return;
+  }
+  const routed = await clientTry(cmd, opts); // route transparently if a daemon is up, else fall back to one-shot
+  if (routed != null) { emit(routed); return; }
+  if (cmd === "shutdown") { await cmdShutdown(opts); return; }
+  if (cmd === "devices") { emit(core.doDevices()); return; }
+  if (cmd === "density") {
+    const dd = core.probeDensity(opts.device);
+    emit({ ok: dd != null, density: dd, ...(dd == null ? { error: "密度探测失败(hidumper 无 Density 行)" } : {}) });
+    return;
+  }
+  if (cmd in core.HDC_ACTIONS) { emit(core.HDC_ACTIONS[cmd](opts)); return; } // pure hdc, no driver connection
+  let d = null, failure = null;
+  try {
+    d = await core.connect(opts.device, opts.workDir);
+    emit(await core.runAction(d, cmd, opts));
+  } catch (e) {
+    // Defer fail(): process.exit inside the catch would skip the finally disconnect and leak the fport/driver session.
+    failure = e instanceof core.DeviceUIError
+      ? [e.reason, e.extra]
+      : [String(e.message || e).slice(0, 300), { tb: String(e.stack || "").slice(-500) }];
+  } finally {
+    if (d) await core.disconnect(d); // clean up per invocation; never accumulate fports at the source
+  }
+  if (failure) fail(failure[0], failure[1]);
+}
+
+main().then(() => process.exit(0)).catch((e) => fail(String(e?.message || e).slice(0, 300)));