@oxy.so/doctor 1.3.0 → 1.4.0

package/README.md

@@ -46,3 +46,20 @@ Use Renovate with a shared organisation preset for grouped, reviewable updates.
 Require normal tests and typecheck before merging; never use `latest` ranges or
 mutate dependencies during application startup or CI. Renovate proposes
 changes; Doctor detects drift and duplicate installations.
+
+## Android emulator preflight
+
+`oxy-emulator-preflight --serial emulator-5554` checks that the explicitly
+selected serial occurs exactly once as an online device in `adb devices -l`,
+then asks its emulator console for the AVD name. It prints only the serial on
+success and exits nonzero on invalid input, offline or ambiguous devices, an
+unavailable ADB, or a missing AVD response. It never starts an emulator or runs
+shell, installation, clearing, or uninstallation commands on a device.
+
+The caller must carry the returned serial into every subsequent command, for
+example using `adb -s "$serial" ...`; never rely on ADB's default selection.
+Run the preflight immediately before the operation and fail on errors. This is a
+read-only selection check, not an atomic device lock: devices can disconnect or
+change between commands. It does not prove the AVD is disposable, has no user
+data, or is isolated from production networks. Those are separate prerequisites
+for an isolated mobile test.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/doctor",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Read-only health checks for Oxy ecosystem repositories",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   },
   "type": "module",
   "bin": {
-    "oxy-doctor": "./src/cli.mjs"
+    "oxy-doctor": "./src/cli.mjs",
+    "oxy-emulator-preflight": "./src/emulator-preflight.mjs"
   },
   "exports": {
     ".": "./src/checks.mjs"

package/src/emulator-preflight.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const usage = 'Usage: oxy-emulator-preflight --serial emulator-<port>';
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  console.log(usage);
+  process.exit(0);
+}
+
+function fail(message) {
+  console.error(`Emulator preflight failed: ${message}`);
+  process.exit(1);
+}
+
+if (args.length !== 2 || args[0] !== '--serial' || !/^emulator-\d{4,5}$/.test(args[1] ?? '')) {
+  fail(`an explicit emulator serial is required. ${usage}`);
+}
+const serial = args[1];
+
+function adb(...arguments_) {
+  const result = spawnSync('adb', arguments_, {
+    encoding: 'utf8',
+    timeout: 10_000,
+    maxBuffer: 1_000_000,
+  });
+  if (result.error || result.status !== 0) {
+    fail(`adb ${arguments_[0]} failed or timed out`);
+  }
+  return result.stdout;
+}
+
+const lines = adb('devices', '-l').split(/\r?\n/);
+if (!lines.some((line) => line.trim() === 'List of devices attached')) {
+  fail('unrecognized adb devices output');
+}
+const matches = lines
+  .map((line) => line.trim().split(/\s+/))
+  .filter(([candidate]) => candidate === serial);
+if (matches.length !== 1 || matches[0][1] !== 'device') {
+  fail('the selected emulator must appear exactly once and be online');
+}
+
+// A serial-shaped name alone is not proof that adb is talking to an emulator.
+// The console command is read-only and must return one AVD name followed by OK.
+const reply = adb('-s', serial, 'emu', 'avd', 'name').trim().split(/\r?\n/);
+if (reply.length !== 2 || !/^[A-Za-z0-9_.-]+$/.test(reply[0]) || reply[1] !== 'OK') {
+  fail('the selected device did not identify itself as an Android AVD');
+}
+console.log(serial);