mobile-automator 0.26.0 → 0.27.1

package/README.md

@@ -8,13 +8,13 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20CMP-green.svg)](#)
-[![Node](https://img.shields.io/badge/Node-%E2%89%A520-brightgreen.svg)](#)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A522.12-brightgreen.svg)](#)
 
 ---
 
 ## ⏱️ Quick start (5 minutes)
 
-**You need:** Node ≥ 20 · an AI coding agent · a running emulator/simulator or a connected device.
+**You need:** Node ≥ 22.12 · an AI coding agent · a running emulator/simulator or a connected device.
 
 > This quick start uses **Claude Code** as the example agent. For Cursor, swap `--agent claude` → `--agent cursor`. For any other agent, see [Using another agent](#-using-another-agent).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {
@@ -33,7 +33,7 @@
     "test:all": "jest"
   },
   "dependencies": {
-    "@mobilenext/mobile-mcp": "0.0.55",
+    "@mobilenext/mobile-mcp": "1.0.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.20.0",
     "commander": "^12.1.0"
@@ -45,6 +45,6 @@
     "toml": "^3.0.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.12.0"
   }
 }

package/src/cli.js

@@ -8,6 +8,7 @@ const { version: PKG_VERSION } = require('../package.json');
 const { ok, fail, render, exitCodeFor } = require('./output/envelope');
 const { DeviceBridge } = require('./device/bridge');
 const selectionStore = require('./device/selection');
+const { engineHint } = require('./device/engine-hints');
 const { ScenarioValidator } = require('./scenario/validator');
 const { evaluate, MECHANICAL_TYPES } = require('./assertion/evaluator');
 const { ResultStore } = require('./result/store');
@@ -158,6 +159,16 @@ function toEnvelope(err) {
   };
 }
 
+// The hint for any device-kind failure. Precedence: an explicit err.hint wins
+// (our own code attached it knowing the exact cause — a DeviceResolutionError,
+// the daemon-log pointer, a timeout); then engineHint, which recognises engine
+// messages that are useless on their own (the 1.0.5 engine's missing iOS agent
+// and changed Android device ids, #199); then the handler's generic fallback.
+// Every device fail() below goes through here so no handler can miss it.
+function deviceHint(err, fallback) {
+  return (err && err.hint) || engineHint(err && err.message) || fallback;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers — pure-ish: accept injected deps, return { envelope, exitKind }.
 // No process.exit / printing here so they are trivially unit-testable.
@@ -172,7 +183,7 @@ async function handleElements({ deviceBridge }) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected and the app is running.'
+        deviceHint(err, 'Ensure a device or simulator is connected and the app is running.')
       ),
       exitKind: 'device',
     };
@@ -188,7 +199,7 @@ async function handleScreenshot({ deviceBridge }, destPath) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected.'
+        deviceHint(err, 'Ensure a device or simulator is connected.')
       ),
       exitKind: 'device',
     };
@@ -247,7 +258,7 @@ function deviceFail(err) {
     envelope: fail(
       kind,
       err.message || String(err),
-      err.hint || 'Ensure a device or simulator is connected and the app is running.'
+      deviceHint(err, 'Ensure a device or simulator is connected and the app is running.')
     ),
     exitKind: kind,
   };
@@ -279,7 +290,20 @@ function parseCoordinates(raw) {
       error: fail('invalid_input', `coordinates must be numbers, got "${raw}"`, 'Pass --at <x,y>, e.g. --at 100,250.'),
     };
   }
-  return { x: Math.round(x), y: Math.round(y) };
+  // Check AFTER rounding: the device receives the rounded ints, so -0.4 (-> 0)
+  // is a valid on-screen point while -0.6 (-> -1) is not. `+ 0` normalizes -0
+  // to 0 so neither the envelope nor the engine sees a signed zero. Negatives
+  // must be caught here because mobile-mcp 1.0.5 declares coordinates .min(0)
+  // and would reject them device-side, misclassified as a device failure that
+  // triggers the crash probe (#199).
+  const rx = Math.round(x) + 0;
+  const ry = Math.round(y) + 0;
+  if (rx < 0 || ry < 0) {
+    return {
+      error: fail('invalid_input', `coordinates must be non-negative, got "${raw}"`, 'Coordinates must be >= 0 (screen pixels from the top-left), e.g. --at 100,250.'),
+    };
+  }
+  return { x: rx, y: ry };
 }
 
 async function handleTap({ deviceBridge }, raw) {
@@ -1241,7 +1265,7 @@ async function handleDevices({ deviceBridge }) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected and reachable.'
+        deviceHint(err, 'Ensure a device or simulator is connected and reachable.')
       ),
       exitKind: 'device',
     };
@@ -1265,7 +1289,7 @@ async function handleDevicesUse({ deviceBridge, store = selectionStore, projectR
     devices = await deviceBridge.listDevices();
   } catch (err) {
     return {
-      envelope: fail('device', err.message || String(err), err.hint || 'Ensure a device or simulator is connected and reachable.'),
+      envelope: fail('device', err.message || String(err), deviceHint(err, 'Ensure a device or simulator is connected and reachable.')),
       exitKind: 'device',
     };
   }
@@ -1376,7 +1400,7 @@ async function handleCrashList({ deviceBridge, projectRoot }, opts = {}) {
     // "Could not look" is NOT "found none". Reporting ok:true with an empty
     // list here would be this slice's own bug with the sign flipped.
     return {
-      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      envelope: fail(err.kind || 'device', err.message || String(err), deviceHint(err, CRASH_LIST_HINT)),
       exitKind: err.kind || 'device',
     };
   }
@@ -1408,7 +1432,7 @@ async function handleCrashGet({ deviceBridge, fs: fsDep = fs }, id, opts = {}) {
     report = await deviceBridge.getCrash(id);
   } catch (err) {
     return {
-      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      envelope: fail(err.kind || 'device', err.message || String(err), deviceHint(err, CRASH_LIST_HINT)),
       exitKind: err.kind || 'device',
     };
   }

package/src/device/action-catalog.js

@@ -16,7 +16,7 @@
 //   '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
+//   'unsupported' — mobile-mcp 1.0.5 exposes no primitive for it. Not
 //                   mechanically executable; the guide must NOT promise a verb,
 //                   and the agent reports it honestly / handles it manually.
 //
@@ -84,7 +84,7 @@ const ACTION_CATALOG = {
   wait_for_loading_complete: { resolution: 'composed' },
   capture_value: { resolution: 'composed' },
 
-  // --- unsupported (no mobile-mcp 0.0.55 primitive) ----------------------
+  // --- unsupported (no mobile-mcp 1.0.5 primitive) -----------------------
   clear_app_data: { resolution: 'unsupported' },
   enable_wifi: { resolution: 'unsupported' },
   disable_wifi: { resolution: 'unsupported' },

package/src/device/bridge.js

@@ -4,6 +4,7 @@ const { normalize, parseElements } = require('./element-model');
 const { normalizeDevices } = require('./device-model');
 const { normalizeCrashes } = require('./crash-model');
 const { resolveSingleDevice } = require('./device-resolver');
+const { centredSwipe } = require('./swipe-geometry');
 
 // Thin wrapper over an injected mobile-mcp `call(toolName, args)` function.
 // Returns the agnostic element model and exposes only the primitives the CLI needs.
@@ -24,8 +25,11 @@ class DeviceBridge {
     return normalizeDevices(result);
   }
 
+  // format:"json" is required from mobile-mcp 1.0.5, which defaults this tool
+  // to a line-per-element text format parseElements cannot read (#199). 0.0.55
+  // ignores the unknown key (its zod schema is non-strict), so it is safe on both.
   async listElements() {
-    const result = await this._call('mobile_list_elements_on_screen', {});
+    const result = await this._call('mobile_list_elements_on_screen', { format: 'json' });
     return normalize(parseElements(result));
   }
 
@@ -62,10 +66,26 @@ class DeviceBridge {
     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.
+  // Swipe in a cardinal direction.
+  //
+  // Direction-only (x, y and distance all undefined): mauto sends explicit
+  // centre ± 30% geometry from centredSwipe rather than trusting the engine
+  // default, which mobile-mcp 1.x changed from that proportional travel to a
+  // fixed 400px on Android and real iOS (#199; see swipe-geometry.js). This
+  // costs one extra mobile_get_screen_size round trip per direction-only swipe
+  // — acceptable because each verb is one-shot and swipes are not hot-path, so
+  // no caching. getScreenSize throws on a zero/unreadable size, so a 0x0 screen
+  // can never produce a degenerate swipe.
+  //
+  // Any explicit key (e.g. the iOS edge-swipe back's x/y/distance) means the
+  // caller owns the geometry: everything given is passed through as-is and
+  // absent keys are not sent — including partial input such as x,y without
+  // distance, which leaves the travel to the engine exactly as before.
   async swipe({ direction, x, y, distance } = {}) {
+    if (x === undefined && y === undefined && distance === undefined) {
+      const geometry = centredSwipe(await this.getScreenSize(), direction);
+      return this._call('mobile_swipe_on_screen', { direction, ...geometry });
+    }
     const args = { direction };
     if (x !== undefined) args.x = x;
     if (y !== undefined) args.y = y;
@@ -92,18 +112,25 @@ class DeviceBridge {
   // 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.
+  // That includes a READABLE zero: mobile-mcp 1.0.5's mobilecli path returns
+  // {width:0,height:0,scale:1} for an unknown size instead of throwing (#199).
   async getScreenSize() {
     const r = await this._call('mobile_get_screen_size', {});
+    let size = null;
     if (r && typeof r === 'object' && r.width != null && r.height != null) {
-      return { width: Number(r.width), height: Number(r.height) };
+      size = { width: Number(r.width), height: Number(r.height) };
+    } else {
+      const m = /(\d+)\s*x\s*(\d+)/i.exec(String(r));
+      if (m) size = { width: Number(m[1]), height: Number(m[2]) };
     }
-    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}".`);
+    const positive = (n) => Number.isFinite(n) && n > 0;
+    if (!size || !positive(size.width) || !positive(size.height)) {
+      const shown = r && typeof r === 'object' ? JSON.stringify(r) : String(r);
+      const err = new Error(`Could not read the device screen size from "${shown}".`);
       err.hint = 'Ensure a device or simulator is connected.';
       throw err;
     }
-    return { width: Number(m[1]), height: Number(m[2]) };
+    return size;
   }
 
   // Press a hardware/system button (BACK, HOME, ENTER, ...).

package/src/device/device-resolver.js

@@ -11,7 +11,8 @@ class DeviceResolutionError extends Error {
   }
 }
 
-// mobile-mcp 0.0.55 requires a concrete device id on every action/read tool.
+// mobile-mcp 1.0.5 requires a concrete device id on every action/read tool
+// (tests/integration/mobile-mcp-contract.test.js pins this against the engine).
 // When the caller pinned nothing (no --device, no persisted selection), we
 // auto-discover: exactly one active device is used; zero or many is a clear,
 // actionable failure rather than a silent empty result.

package/src/device/element-model.js

@@ -58,25 +58,47 @@ function normalize(rawElements) {
   return out;
 }
 
-// mobile-mcp 0.0.55 returns elements as the string
-// `Found these elements on screen: <JSON array>`. Earlier/other shapes may be
-// a bare array or `{elements:[...]}`. Parse all three into the raw element
-// array. Parse the WHOLE JSON array (never per-element regex) so labels
-// containing brackets/quotes/newlines survive.
+// Short, single-line excerpt of an unparseable payload for the error message:
+// the FIRST non-empty line only, capped, so a multi-kilobyte screen dump never
+// floods the envelope but the reader still sees what shape came back.
+const EXCERPT_MAX = 120;
+function excerptOf(text) {
+  const line = (text.split(/\r?\n/).find((l) => l.trim() !== '') || '').trim();
+  return line.length > EXCERPT_MAX ? `${line.slice(0, EXCERPT_MAX)}…` : line;
+}
+
+// mobile-mcp returns elements as the string
+// `Found these elements on screen: <JSON array>` (0.0.55, and 1.0.5 when called
+// with format:"json"). Earlier/other shapes may be a bare array or
+// `{elements:[...]}`. Parse all three into the raw element array. Parse the
+// WHOLE JSON array (never per-element regex) so labels containing
+// brackets/quotes/newlines survive.
+//
+// A non-empty string we cannot parse THROWS rather than returning []: mobile-mcp
+// 1.0.5 defaults this tool to a line-per-element text format whose header
+// contains `[focused] ... [disabled]`, and a silent [] there reported `ok:true`
+// with an empty screen — the failure probe then blamed the app (#199). An empty
+// or whitespace-only string stays [] because it carries no content to misread:
+// it is not evidence of a format change. null / non-string values stay [] for
+// the same reason.
 function parseElements(raw) {
   if (Array.isArray(raw)) return raw;
   if (raw && Array.isArray(raw.elements)) return raw.elements;
-  if (typeof raw === 'string') {
-    const start = raw.indexOf('[');
-    const end = raw.lastIndexOf(']');
-    if (start !== -1 && end > start) {
-      try {
-        const parsed = JSON.parse(raw.slice(start, end + 1));
-        if (Array.isArray(parsed)) return parsed;
-      } catch (_e) { /* fall through */ }
-    }
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+
+  const start = raw.indexOf('[');
+  const end = raw.lastIndexOf(']');
+  if (start !== -1 && end > start) {
+    try {
+      const parsed = JSON.parse(raw.slice(start, end + 1));
+      if (Array.isArray(parsed)) return parsed;
+    } catch (_e) { /* fall through to the loud failure below */ }
   }
-  return [];
+  const err = new Error(`The element list could not be parsed. Engine returned: "${excerptOf(raw)}"`);
+  err.hint =
+    'The mobile-mcp engine likely changed its element output format (e.g. text instead of JSON). ' +
+    'Check the installed @mobilenext/mobile-mcp version matches the one mobile-automator pins.';
+  throw err;
 }
 
 module.exports = { normalize, parseElements };

package/src/device/engine-hints.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Actionable hints for device-engine failures whose raw message alone does not
+// tell the user what to do. Pure: message in, hint string (or null) out. It
+// never throws — a hint classifier that crashes would turn a device failure
+// into an internal one. Found by the #199 real-device run against mobile-mcp
+// 1.0.5 / mobilecli 1.0.13.
+//
+// mauto only TELLS the user which command to run; it never runs mobilecli
+// itself (the device is driven only through mauto verbs, which wrap
+// mobile-mcp).
+
+const ISSUE_459 = 'https://github.com/mobile-next/mobile-mcp/issues/459';
+
+// The mobilecli that the pinned mobile-mcp actually spawns — resolved from
+// mobile-mcp's own directory, since that is the copy whose agent the device
+// must match. Null when it cannot be resolved; the caller omits `@<version>`.
+function resolveMobilecliVersion() {
+  const mcpDir = path.dirname(require.resolve('@mobilenext/mobile-mcp/package.json'));
+  const pkgPath = require.resolve('mobilecli/package.json', { paths: [mcpDir] });
+  // Read, not require(): a non-literal require specifier is unverifiable to
+  // tests/lint/telemetry-transport-isolation.test.js.
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || null;
+}
+
+function safeVersion(resolver) {
+  try {
+    const v = resolver();
+    return typeof v === 'string' && v ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// B1 (iOS): mobilecli `agent status` exits 1 when the DeviceKit agent is
+// missing and mobile-mcp runs it via execFileSync, so the throw skips its own
+// auto-install (upstream mobile-mcp#459). Every verb fails until the agent is
+// installed once by hand.
+function missingAgentHint(message, resolver) {
+  const version = safeVersion(resolver);
+  const pkg = version ? `mobilecli@${version}` : 'mobilecli';
+  const cmd = `npx -y ${pkg} agent install --device`;
+  const m = /--device\s+(\S+)/.exec(message);
+  const install = m
+    ? `\`${cmd} ${m[1]}\``
+    : `\`${cmd}\` followed by the simulator's id from \`mauto devices\``;
+  return (
+    'The simulator is missing the device agent the engine needs, and the engine cannot install it ' +
+    `itself (upstream bug ${ISSUE_459}). Install it once with ${install} ` +
+    '(needs network, takes a few seconds), then retry.'
+  );
+}
+
+// B2: mobile-mcp 1.0.5's default robot lists Android emulators by AVD name,
+// MOBILEMCP_LEGACY_ROBOT=1 (and 0.0.55) by adb serial, and each rejects the
+// other's id — so a selection persisted before the upgrade fails every verb.
+function deviceNotFoundHint(id) {
+  return (
+    `Device "${id}" is not known to the current engine. Device ids can differ between engines: ` +
+    "mauto 0.27's default engine lists Android emulators by AVD name (e.g. Pixel_9_Pro), while " +
+    'MOBILEMCP_LEGACY_ROBOT=1 uses the adb serial (e.g. emulator-5554). Run `mauto devices`, then ' +
+    '`mauto devices use` with an id from that list (or pass that id to --device).'
+  );
+}
+
+function engineHint(message, { mobilecliVersion = resolveMobilecliVersion } = {}) {
+  try {
+    if (typeof message !== 'string' || !message) return null;
+    if (/Agent is not installed on the device/.test(message)) {
+      return missingAgentHint(message, mobilecliVersion);
+    }
+    const notFound = /Device "([^"]+)" not found/.exec(message);
+    if (notFound) return deviceNotFoundHint(notFound[1]);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { engineHint };

package/src/device/mobile-mcp-client.js

@@ -160,4 +160,6 @@ function parseToolResult(res) {
   return res;
 }
 
-module.exports = { createCall, makeCall, parseToolResult };
+// resolveServerEntry is exported so tests/integration/mobile-mcp-contract.test.js
+// spawns the pinned engine by the exact path production does, not a copy of it.
+module.exports = { createCall, makeCall, parseToolResult, resolveServerEntry };

package/src/device/swipe-geometry.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// Geometry for a direction-only swipe: start at centre + 30% of the axis
+// dimension and travel 60% of it, i.e. centre ± 30% (#199).
+//
+// Why mauto computes this instead of letting the engine choose: mobile-mcp
+// 0.0.55's adb and WDA robots used exactly this proportional travel, but 1.0.5
+// routes every device through mobilecli, whose direction-only swipe is a fixed
+// 400px centred stroke — about a third of the old travel on a phone, so
+// scroll-to-element needs ~3x the swipes. Every robot in both versions reads an
+// explicit {x, y, distance} the same way (start at x,y; move `distance` px in
+// `direction`), so sending it pins identical behaviour on either pin.
+//
+// Kept pure and in its own module (not inside DeviceBridge) so the arithmetic
+// is testable without an engine fake and the bridge stays a thin wrapper.
+// There is deliberately no platform branch: proportional geometry is what makes
+// it platform-agnostic.
+//
+// The integer formulas mirror 0.0.55's AndroidRobot (`Math.floor(n * 0.8)`,
+// `Math.floor(n * 0.2)`, centre `floor(n / 2)`) so the endpoints match its old
+// ones pixel-for-pixel, floating-point rounding included.
+function centredSwipe({ width, height }, direction) {
+  const hi = (n) => Math.floor(n * 0.8);
+  const lo = (n) => Math.floor(n * 0.2);
+  const cx = Math.floor(width / 2);
+  const cy = Math.floor(height / 2);
+  switch (direction) {
+    case 'up': return { x: cx, y: hi(height), distance: hi(height) - lo(height) };
+    case 'down': return { x: cx, y: lo(height), distance: hi(height) - lo(height) };
+    case 'left': return { x: hi(width), y: cy, distance: hi(width) - lo(width) };
+    case 'right': return { x: lo(width), y: cy, distance: hi(width) - lo(width) };
+    default:
+      // The CLI validates directions first; this guards other callers from a
+      // swipe with undefined geometry.
+      throw new Error(`Unknown swipe direction "${direction}".`);
+  }
+}
+
+module.exports = { centredSwipe };

package/src/device/tool-args.js

@@ -1,6 +1,8 @@
 'use strict';
 
-// mobile-mcp 0.0.55 requires `device` on every tool EXCEPT the discovery verb.
+// mobile-mcp 1.0.5 requires `device` on every tool EXCEPT the discovery verb;
+// tests/integration/mobile-mcp-contract.test.js enforces this against the
+// pinned engine's own tool schemas.
 // Centralizing the injection (and its one exception) here keeps every call
 // site correct. Pure + non-mutating so it is trivially testable.
 const NO_DEVICE_TOOLS = new Set(['mobile_list_available_devices']);