mobile-automator 0.23.8

package/src/config/coerce.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// Normalizes config values into the types config_schema.json declares.
+//
+// Two entry points, one contract:
+//   coerceValue    — a raw CLI string on the way IN to `config set`.
+//   normalizeConfig — a config object on the way OUT of `manager.load()`,
+//                     healing values written before the schema existed (#136).
+//
+// The comma-splitting rule is what makes the setup guide's long-standing
+// `mauto config set environments <env1,env2,...>` prose correct instead of
+// silently producing a string.
+
+const { declaredTypesAt, LIST_KEY_PATHS } = require('./schema');
+
+function splitList(raw) {
+  return String(raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function tryJson(raw) {
+  try {
+    return { ok: true, value: JSON.parse(raw) };
+  } catch (_) {
+    return { ok: false };
+  }
+}
+
+function coerceValue(dottedKey, rawValue) {
+  // A bare `null` argument always means JSON null, regardless of the key's
+  // declared type. It is `validateAt` — not this function — that decides
+  // whether the key is allowed to hold it: keys declared nullable accept it,
+  // everything else gets a loud invalid_input instead of silently storing the
+  // string "null" (see #136 fix-wave, Important 2).
+  if (String(rawValue).trim() === 'null') return null;
+
+  const types = declaredTypesAt(dottedKey);
+
+  // Undeclared key: preserve the historical lenient behavior exactly.
+  if (types.length === 0) {
+    const parsed = tryJson(rawValue);
+    return parsed.ok ? parsed.value : rawValue;
+  }
+
+  if (types.includes('array')) {
+    const parsed = tryJson(rawValue);
+    if (parsed.ok && Array.isArray(parsed.value)) return parsed.value;
+    return splitList(rawValue);
+  }
+
+  if (types.includes('string')) {
+    // Never let JSON.parse retype a string key (a project literally named
+    // "12345" stays a string).
+    return String(rawValue);
+  }
+
+  const parsed = tryJson(rawValue);
+  return parsed.ok ? parsed.value : rawValue;
+}
+
+function getPath(obj, parts) {
+  let cur = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function setPath(obj, parts, value) {
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] == null || typeof cur[parts[i]] !== 'object') return;
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+// Heals every declared list path that holds a string. Values that are already
+// arrays — or are neither string nor array — are left exactly as found; this
+// repairs the known drift, it does not guess at anything else.
+function normalizeConfig(cfg) {
+  if (cfg == null || typeof cfg !== 'object') return cfg;
+  const out = JSON.parse(JSON.stringify(cfg));
+  for (const listPath of LIST_KEY_PATHS) {
+    const parts = listPath.split('.');
+    const current = getPath(out, parts);
+    if (typeof current === 'string') {
+      setPath(out, parts, splitList(current));
+    }
+  }
+  return out;
+}
+
+module.exports = { coerceValue, normalizeConfig, splitList };

package/src/config/manager.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Workspace config manager for the `mauto` CLI.
+//
+// Reads/writes mobile-automator/config.json under a project root.
+// A config without an explicit `mode` is treated as `platform-aware`.
+
+const fs = require('fs');
+const path = require('path');
+const { normalizeConfig } = require('./coerce');
+
+function configDir(projectRoot) {
+  return path.join(projectRoot, 'mobile-automator');
+}
+
+function configPath(projectRoot) {
+  return path.join(configDir(projectRoot), 'config.json');
+}
+
+// Parsed config object, or null when the file is absent. Values written before
+// the config schema existed are healed on the way out (a comma-joined list key
+// becomes a real array) — see #136. Since set() is load-mutate-write, the next
+// write persists the healed shape.
+function load(projectRoot) {
+  const p = configPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  return normalizeConfig(JSON.parse(fs.readFileSync(p, 'utf8')));
+}
+
+// Default to platform-aware for null/empty/legacy configs.
+function resolveMode(cfg) {
+  return cfg && cfg.mode ? cfg.mode : 'platform-aware';
+}
+
+// Dotted-path lookup. Missing path -> undefined.
+function get(projectRoot, key) {
+  const cfg = load(projectRoot);
+  if (cfg == null) return undefined;
+  return getPath(cfg, key);
+}
+
+// Load-or-{}, set the dotted path, write back preserving every other field as
+// pretty 2-space JSON. Creates mobile-automator/ if needed.
+function set(projectRoot, key, value) {
+  const cfg = load(projectRoot) || {};
+  setPath(cfg, key, value);
+  fs.mkdirSync(configDir(projectRoot), { recursive: true });
+  fs.writeFileSync(configPath(projectRoot), JSON.stringify(cfg, null, 2) + '\n');
+  return cfg;
+}
+
+function getPath(obj, key) {
+  const parts = String(key).split('.');
+  let cur = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function setPath(obj, key, value) {
+  const parts = String(key).split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (cur[part] == null || typeof cur[part] !== 'object') {
+      cur[part] = {};
+    }
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+module.exports = { load, resolveMode, get, set, configPath, configDir };

package/src/config/schema.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Type lookup + per-key validation for the workspace config.
+//
+// config_schema.json is the single source of truth for what shape each config
+// key holds. This module is the only reader of that fact: the coercion layer
+// asks it "what type is this key?" and the CLI asks it "is this value valid?".
+// Nothing else hard-codes a config key's type.
+//
+// Validation is deliberately PER-KEY, not whole-document: a config carrying
+// unrelated pre-existing drift must not block an unrelated `config set`.
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+
+const { formatError } = require('../schemas/format-error');
+
+const CONFIG_SCHEMA_PATH = path.resolve(__dirname, '../schemas/config_schema.json');
+
+const schema = JSON.parse(fs.readFileSync(CONFIG_SCHEMA_PATH, 'utf8'));
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+// Resolve a local `$ref` ("#/definitions/stringList") to a fixpoint: a
+// resolved node may itself be another `$ref` (e.g. a `$ref` to a `$ref`), so
+// one hop is not enough to agree with Ajv, which resolves refs fully. A
+// visited-set cycle guard makes a self-referential or circular `$ref` a no-op
+// (return the last-seen node) instead of an infinite loop.
+function deref(node) {
+  const seen = new Set();
+  let cur = node;
+  while (cur && typeof cur === 'object' && typeof cur.$ref === 'string') {
+    if (seen.has(cur.$ref)) return cur; // circular $ref — bail with what we have
+    seen.add(cur.$ref);
+    const parts = cur.$ref.replace(/^#\//, '').split('/');
+    let target = schema;
+    for (const part of parts) {
+      if (target == null) return cur; // unresolvable pointer — leave as-is
+      target = target[part];
+    }
+    if (!target) return cur;
+    cur = target;
+  }
+  return cur;
+}
+
+// Walk `properties` down a dotted path. Undeclared path -> null.
+function subschemaAt(dottedKey) {
+  const parts = String(dottedKey).split('.');
+  let node = schema;
+  for (const part of parts) {
+    node = deref(node);
+    if (!node || !node.properties || !node.properties[part]) return null;
+    node = node.properties[part];
+  }
+  const resolved = deref(node);
+  return resolved || null;
+}
+
+function declaredTypesAt(dottedKey) {
+  const sub = subschemaAt(dottedKey);
+  if (!sub || sub.type === undefined) return [];
+  return Array.isArray(sub.type) ? [...sub.type] : [sub.type];
+}
+
+// Every array-typed dotted path in the schema, flat and nested. Drives both
+// read-side healing and the structural lint guard.
+function collectListPaths(node, prefix, out) {
+  const resolved = deref(node);
+  if (!resolved || !resolved.properties) return out;
+  for (const [name, child] of Object.entries(resolved.properties)) {
+    const childPath = prefix ? `${prefix}.${name}` : name;
+    const rc = deref(child);
+    if (!rc) continue;
+    if (rc.type === 'array') out.push(childPath);
+    else if (rc.type === 'object' || rc.properties) collectListPaths(rc, childPath, out);
+  }
+  return out;
+}
+
+const LIST_KEY_PATHS = collectListPaths(schema, '', []);
+
+// Compiled per-path validators, built lazily and cached.
+const compiled = new Map();
+
+function validateAt(dottedKey, value) {
+  const sub = subschemaAt(dottedKey);
+  if (!sub) return { valid: true, errors: [] }; // undeclared key -> always allowed
+  if (!compiled.has(dottedKey)) {
+    // `sub` may be an object-typed node (e.g. "app", "knowledge") whose OWN
+    // top-level $ref was resolved by subschemaAt's final deref, but whose
+    // nested properties (e.g. app.ios_bundle_id) still carry an unresolved
+    // local `#/definitions/...` $ref. Compiling `sub` standalone would make
+    // that pointer resolve against `sub`'s own (definitions-less) root and
+    // throw "can't resolve reference". Carrying the root `definitions`
+    // alongside makes every local ref in this schema resolve correctly no
+    // matter how deep the compiled subschema sits.
+    compiled.set(dottedKey, ajv.compile({ ...sub, definitions: schema.definitions }));
+  }
+  const fn = compiled.get(dottedKey);
+  const valid = fn(value);
+  if (valid) return { valid: true, errors: [] };
+  // formatError prefixes a root-level error with "(root)" — meaningful for
+  // the scenario validator, whose messages otherwise carry no subject. Here
+  // the CLI message already names the key ("invalid value for config key
+  // ..."), so a bare "(root)" only duplicates it; strip that one case. A
+  // non-root instancePath (e.g. "/android_package" on an object-typed key
+  // like "app") still adds information the key name alone doesn't, so it is
+  // left as formatError produced it. Fixed here, not in format-error.js,
+  // because the scenario validator's messages depend on that prefix.
+  const errors = (fn.errors || []).map((err) => {
+    const msg = formatError(err);
+    return err.instancePath ? msg : msg.replace(/^\(root\)\s*/, '');
+  });
+  return { valid: false, errors };
+}
+
+module.exports = {
+  CONFIG_SCHEMA_PATH,
+  subschemaAt,
+  declaredTypesAt,
+  LIST_KEY_PATHS,
+  validateAt,
+};

package/src/device/action-catalog.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// Single source of truth binding every scenario-schema action to HOW it is
+// executed. Three things must agree and never drift: the schema's action
+// enums (`step.action` + `preconditions.device_actions`), the `mauto` verb
+// surface (cli.js + DeviceBridge), and the execute guide's mapping table.
+// `tests/lint/action-coverage.test.js` derives its assertions from this map,
+// so an action that loses (or never had) a faithful execution path fails the
+// build instead of silently degrading at replay time.
+//
+// `resolution` declares the execution contract for each action:
+//   'verb'        — a dedicated one-shot `mauto` verb backed by a DeviceBridge
+//                   method that calls a single mobile-mcp primitive.
+//   'semantic'    — invoked via `mauto press <action>`; resolved to per-platform
+//                   mechanics by src/device/semantic-press (see ACTION_METHOD).
+//   'composed'    — no dedicated verb; the agent composes it from existing verbs
+//                   (e.g. poll `mauto elements`, repeat `mauto swipe`). The
+//                   execute guide documents the composition.
+//   'unsupported' — mobile-mcp 0.0.55 exposes no primitive for it. Not
+//                   mechanically executable; the guide must NOT promise a verb,
+//                   and the agent reports it honestly / handles it manually.
+//
+// For 'verb' entries, `args` documents the mobile-mcp argument keys the bridge
+// method must pass — deliberately explicit because the keys are inconsistent
+// across the engine (launch=packageName, uninstall=bundle_id, install=path).
+
+const ACTION_CATALOG = {
+  // --- direct verbs (engine-backed) --------------------------------------
+  tap: {
+    resolution: 'verb', verb: 'tap', bridge: 'tap',
+    primitive: 'mobile_click_on_screen_at_coordinates', args: ['x', 'y'],
+  },
+  long_press: {
+    resolution: 'verb', verb: 'long-press', bridge: 'longPress',
+    primitive: 'mobile_long_press_on_screen_at_coordinates', args: ['x', 'y', 'duration?'],
+  },
+  double_tap: {
+    resolution: 'verb', verb: 'double-tap', bridge: 'doubleTap',
+    primitive: 'mobile_double_tap_on_screen', args: ['x', 'y'],
+  },
+  type: {
+    resolution: 'verb', verb: 'type', bridge: 'type',
+    primitive: 'mobile_type_keys', args: ['text', 'submit'],
+  },
+  swipe: {
+    resolution: 'verb', verb: 'swipe', bridge: 'swipe',
+    primitive: 'mobile_swipe_on_screen', args: ['direction'],
+  },
+  press_button: {
+    resolution: 'verb', verb: 'press', bridge: 'pressButton',
+    primitive: 'mobile_press_button', args: ['button'],
+  },
+  launch_app: {
+    resolution: 'verb', verb: 'launch', bridge: 'launchApp',
+    primitive: 'mobile_launch_app', args: ['packageName'],
+  },
+  install_app: {
+    resolution: 'verb', verb: 'install', bridge: 'installApp',
+    primitive: 'mobile_install_app', args: ['path'],
+  },
+  uninstall_app: {
+    resolution: 'verb', verb: 'uninstall', bridge: 'uninstallApp',
+    primitive: 'mobile_uninstall_app', args: ['bundle_id'],
+  },
+  open_url: {
+    resolution: 'verb', verb: 'open-url', bridge: 'openUrl',
+    primitive: 'mobile_open_url', args: ['url'],
+  },
+  set_orientation: {
+    resolution: 'verb', verb: 'orientation', bridge: 'setOrientation',
+    primitive: 'mobile_set_orientation', args: ['orientation'],
+  },
+
+  // --- semantic (mauto press <action>, platform-resolved) ----------------
+  press_back: { resolution: 'semantic', verb: 'press' },
+  dismiss_keyboard: { resolution: 'semantic', verb: 'press' },
+  grant_permission: { resolution: 'semantic', verb: 'press' },
+  deny_permission: { resolution: 'semantic', verb: 'press' },
+
+  // --- composed (agent builds from existing verbs; no dedicated verb) -----
+  scroll_to_element: { resolution: 'composed' },
+  wait_for_element: { resolution: 'composed' },
+  wait_for_element_gone: { resolution: 'composed' },
+  wait_for_loading_complete: { resolution: 'composed' },
+  capture_value: { resolution: 'composed' },
+
+  // --- unsupported (no mobile-mcp 0.0.55 primitive) ----------------------
+  clear_app_data: { resolution: 'unsupported' },
+  enable_wifi: { resolution: 'unsupported' },
+  disable_wifi: { resolution: 'unsupported' },
+};
+
+const RESOLUTIONS = ['verb', 'semantic', 'composed', 'unsupported'];
+
+function actionsByResolution(resolution) {
+  return Object.keys(ACTION_CATALOG).filter((a) => ACTION_CATALOG[a].resolution === resolution);
+}
+
+module.exports = { ACTION_CATALOG, RESOLUTIONS, actionsByResolution };

package/src/device/bridge.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const { normalize, parseElements } = require('./element-model');
+const { normalizeDevices } = require('./device-model');
+const { resolveSingleDevice } = require('./device-resolver');
+
+// Thin wrapper over an injected mobile-mcp `call(toolName, args)` function.
+// Returns the agnostic element model and exposes only the primitives the CLI needs.
+class DeviceBridge {
+  constructor({ call, device = null }) {
+    if (typeof call !== 'function') {
+      throw new TypeError('DeviceBridge requires a `call` function (toolName, args) => Promise');
+    }
+    this._call = call;
+    this._device = device;
+  }
+
+  // Enumerate connected devices/simulators via mobile-mcp and return the
+  // agnostic device model (id/name/platform/state only). Tolerates both a bare
+  // array and the { devices: [...] } envelope mobile-mcp may return.
+  async listDevices() {
+    const result = await this._call('mobile_list_available_devices', {});
+    return normalizeDevices(result);
+  }
+
+  async listElements() {
+    const result = await this._call('mobile_list_elements_on_screen', {});
+    return normalize(parseElements(result));
+  }
+
+  async screenshot(destPath) {
+    // mobile-mcp's save-screenshot tool names the destination `saveTo` (not
+    // `path`); passing the wrong key makes it a silent no-op that still reports
+    // success. It returns a confirmation string, so we resolve to destPath.
+    const result = await this._call('mobile_save_screenshot', { saveTo: destPath });
+    return (result && result.path) || destPath;
+  }
+
+  // Tap at absolute screen coordinates. The agent derives x,y from listElements
+  // centers, so the bridge stays free of any element targeting logic.
+  async tap({ x, y } = {}) {
+    return this._call('mobile_click_on_screen_at_coordinates', { x, y });
+  }
+
+  // Long-press at absolute screen coordinates. Optional duration (ms) overrides
+  // mobile-mcp's 500ms default; absent it is not sent so the default applies.
+  async longPress({ x, y, duration } = {}) {
+    const args = { x, y };
+    if (duration !== undefined) args.duration = duration;
+    return this._call('mobile_long_press_on_screen_at_coordinates', args);
+  }
+
+  // Double-tap at absolute screen coordinates.
+  async doubleTap({ x, y } = {}) {
+    return this._call('mobile_double_tap_on_screen', { x, y });
+  }
+
+  // Type into the focused element. We never auto-submit; pressing ENTER is a
+  // distinct, explicit action via pressButton.
+  async type(text) {
+    return this._call('mobile_type_keys', { text, submit: false });
+  }
+
+  // Swipe in a cardinal direction. Optional x/y set the start point and
+  // distance the travel — used by the iOS edge-swipe back gesture. Absent keys
+  // are not sent so the cardinal-from-center default is preserved.
+  async swipe({ direction, x, y, distance } = {}) {
+    const args = { direction };
+    if (x !== undefined) args.x = x;
+    if (y !== undefined) args.y = y;
+    if (distance !== undefined) args.distance = distance;
+    return this._call('mobile_swipe_on_screen', args);
+  }
+
+  // Platform ('android'/'ios') of the connected device. Uses the pinned id when
+  // one was provided, else the single auto-resolved device.
+  async getPlatform() {
+    const devices = normalizeDevices(await this._call('mobile_list_available_devices', {}));
+    const id = this._device || resolveSingleDevice(devices); // throws DeviceResolutionError on 0/many
+    const match = devices.find((d) => d.id === id);
+    if (!match || !match.platform) {
+      const err = new Error(`Cannot determine the platform of device "${id}".`);
+      err.hint = 'Ensure the device is listed by `mauto devices`.';
+      throw err;
+    }
+    return String(match.platform).toLowerCase();
+  }
+
+  // Physical screen size in pixels, for geometry-based gestures. mobile-mcp
+  // returns this as the human string "Screen size is <w>x<h> pixels" (not an
+  // object), so we parse the WxH out of it; a structured {width,height} shape is
+  // also accepted in case a future engine returns one. An unreadable size is a
+  // hard error — never silently 0/NaN, which would make geometry gestures no-ops.
+  async getScreenSize() {
+    const r = await this._call('mobile_get_screen_size', {});
+    if (r && typeof r === 'object' && r.width != null && r.height != null) {
+      return { width: Number(r.width), height: Number(r.height) };
+    }
+    const m = /(\d+)\s*x\s*(\d+)/i.exec(String(r));
+    if (!m) {
+      const err = new Error(`Could not read the device screen size from "${r}".`);
+      err.hint = 'Ensure a device or simulator is connected.';
+      throw err;
+    }
+    return { width: Number(m[1]), height: Number(m[2]) };
+  }
+
+  // Press a hardware/system button (BACK, HOME, ENTER, ...).
+  async pressButton(button) {
+    return this._call('mobile_press_button', { button });
+  }
+
+  // Launch an installed app by its package/bundle identifier.
+  async launchApp(packageName) {
+    return this._call('mobile_launch_app', { packageName });
+  }
+
+  // Install an app from a local artifact (apk/ipa) path.
+  async installApp(appPath) {
+    return this._call('mobile_install_app', { path: appPath });
+  }
+
+  // Uninstall an app by its bundle/package identifier.
+  async uninstallApp(appId) {
+    return this._call('mobile_uninstall_app', { bundle_id: appId });
+  }
+
+  // Open a URL (deep link or web) on the device.
+  async openUrl(url) {
+    return this._call('mobile_open_url', { url });
+  }
+
+  // Set the device orientation ('portrait'/'landscape').
+  async setOrientation(orientation) {
+    return this._call('mobile_set_orientation', { orientation });
+  }
+}
+
+module.exports = { DeviceBridge };

package/src/device/connection.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// The single verb-facing seam for talking to a device.
+//
+// acquireConnection() hides the daemon-vs-oneshot decision entirely: callers
+// get back a uniform { bridge, close } and never learn (or care) whether the
+// bridge is daemon-backed or a one-shot spawn. The six-concern decision matrix
+// lives privately in resolve-connection.js; this module is the ONE place the
+// rest of the app reaches for a connection.
+//
+// It also owns the session lifecycle ops (is a daemon alive / spawn one / shut
+// one down) so "should I reuse, spawn, or stop the daemon" has a single owner
+// instead of being re-wired independently by the verb path and the lifecycle
+// handlers.
+
+const { resolveDeviceConnection } = require('./resolve-connection');
+const sessionClient = require('./session-client');
+const sessionSpawn = require('./session-spawn');
+
+// Acquire a device connection, transparently reusing a live daemon when one
+// fits and falling back to a one-shot mobile-mcp spawn otherwise. Returns
+// { bridge, close }; close() releases this verb's hold — a no-op for the shared
+// daemon, a real transport teardown for a one-shot.
+//
+// `resolve` is an internal test seam only; verbs call acquireConnection with
+// just { device, projectRoot }.
+async function acquireConnection({
+  device = null,
+  projectRoot = process.cwd(),
+  resolve = resolveDeviceConnection,
+} = {}) {
+  const { bridge, close } = await resolve({ device, projectRoot });
+  return { bridge, close };
+}
+
+// --- Session lifecycle (one owner for daemon liveness/spawn/shutdown) -------
+
+// Is a device session daemon currently reachable for this workspace?
+function isSessionAlive(projectRoot, { client = sessionClient } = {}) {
+  return client.isAlive(projectRoot);
+}
+
+// Rich status: running + in-flight call count + pinned device. `null`s when not
+// running. The in-flight count exposes the double-execution window.
+function sessionStatus(projectRoot, { client = sessionClient } = {}) {
+  return client.getSessionStatus(projectRoot);
+}
+
+// Spawn a daemon and wait until it answers. Resolves true on success.
+function startSession({ projectRoot, device = null, idleMs, spawn = sessionSpawn } = {}) {
+  return spawn.spawnDaemon({ projectRoot, device, idleMs });
+}
+
+// Ask a live daemon to shut down. Resolves true when one acknowledged.
+function endSession(projectRoot, { client = sessionClient } = {}) {
+  return client.requestShutdown(projectRoot);
+}
+
+module.exports = {
+  acquireConnection,
+  isSessionAlive,
+  sessionStatus,
+  startSession,
+  endSession,
+};

package/src/device/device-model.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// Agnostic device shape for `mauto devices`. We deliberately surface ONLY the
+// four stable keys an agent needs to pick a target — id, name, platform, state
+// — and drop every other raw mobile-mcp field (no resource-id, no OS-specific
+// internals). `os` is mapped onto `platform` so the output reads the same way
+// across the Android/iOS/simulator variants mobile-mcp returns.
+
+function nullable(v) {
+  return v === undefined || v === null || v === '' ? null : v;
+}
+
+function normalizeOne(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const id = nullable(
+    raw.id !== undefined
+      ? raw.id
+      : raw.udid !== undefined
+        ? raw.udid
+        : raw.deviceId !== undefined
+          ? raw.deviceId
+          : raw.serial
+  );
+  if (id == null) return null; // an unidentifiable device is not selectable
+
+  const name = nullable(
+    raw.name !== undefined ? raw.name : raw.deviceName
+  );
+
+  // mobile-mcp reports the OS under `os`; expose it agnostically as `platform`.
+  const platform = nullable(
+    raw.platform !== undefined ? raw.platform : raw.os
+  );
+
+  const state = nullable(raw.state !== undefined ? raw.state : raw.status);
+
+  return { id: String(id), name, platform, state };
+}
+
+function normalizeDevices(raw) {
+  let list;
+  if (Array.isArray(raw)) {
+    list = raw;
+  } else if (raw && Array.isArray(raw.devices)) {
+    list = raw.devices;
+  } else {
+    return [];
+  }
+
+  const out = [];
+  for (const item of list) {
+    const d = normalizeOne(item);
+    if (d) out.push(d);
+  }
+  return out;
+}
+
+module.exports = { normalizeDevices };