mobile-automator 0.29.0 → 0.30.1

package/README.md

@@ -8,6 +8,7 @@ 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)](#)
+[![Host](https://img.shields.io/badge/Host-macOS%20%7C%20Linux-lightgrey.svg)](#)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A522.12-brightgreen.svg)](#)
 
 ---
@@ -24,6 +25,8 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 npm i -g mobile-automator      # exposes `mauto` globally
 ```
 
+> **Supported hosts:** macOS and Linux. Windows is not supported natively (npm refuses the install) — run `mauto` inside WSL2. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#-mauto-refuses-to-run-on-windows).
+
 <details>
 <summary>Or run it without installing / build from source</summary>
 

package/bin/mauto.js

@@ -10,4 +10,5 @@ const { run, emitFatal } = require('../src/cli');
 // exit-on-reject listener.
 process.on('unhandledRejection', emitFatal);
 
-run(process.argv);
+// run() catches everything into emitFatal itself, so the promise never rejects.
+void run(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.29.0",
+  "version": "0.30.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": {
@@ -26,6 +26,7 @@
     "prepublishOnly": "npm test",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "lint": "eslint .",
     "lint:guides": "jest tests/lint",
     "lint:schema-additive": "jest tests/lint/schema-additive.test.js",
     "test:unit": "jest tests/unit",
@@ -39,11 +40,21 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.5",
+    "globals": "^17.13.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "js-yaml": "^4.3.2"
+    "js-yaml": "^4.3.2",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.0"
   },
   "engines": {
     "node": ">=22.12.0"
-  }
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
 }

package/src/cli.js

@@ -7,7 +7,6 @@ const { Command } = require('commander');
 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');
@@ -26,6 +25,7 @@ const guideEmitter = require('./guide/emitter');
 const { ADAPTERS } = require('./init/adapters');
 const { isSemanticAction, ACTION_METHOD, selectResolver } = require('./device/semantic-press');
 const connection = require('./device/connection');
+const { isSupportedHost, unsupportedHostError } = require('./device/host-support');
 const { record } = require('./observe/recorder');
 const { resolveRunId } = require('./observe/settings');
 const { runTracePath } = require('./observe/paths');
@@ -267,6 +267,19 @@ function handleValidate({ validator }, file, opts = {}) {
   return { envelope: env, exitKind: 'invalid_input' };
 }
 
+// The unsupported-host gate (#165), shared by every site that reaches the
+// session layer: connectBridge (all device verbs) and the `session` verbs,
+// which talk to connection.* directly. Null on a supported host; otherwise an
+// `environment` failure (exit 5). Deliberately NOT routed through deviceFail —
+// a `device` kind is exactly the misdiagnosis this exists to prevent: on
+// Windows the session layer's Unix socket, `ps` and process-group kill fail in
+// ways that read as "no device connected".
+function hostGate(platform) {
+  if (isSupportedHost(platform)) return null;
+  const err = unsupportedHostError(platform);
+  return { envelope: fail(err.kind, err.message, err.hint), exitKind: err.kind };
+}
+
 function deviceFail(err) {
   // Respect a typed error's kind (e.g. the daemon's 'timeout') so the envelope
   // and exit code reflect the real failure class; anything else defaults to
@@ -1196,7 +1209,7 @@ async function handleSessionStart(
     projectRoot,
     spawn = require('./device/session-spawn'),
     client = require('./device/session-client'),
-    readHandle = require('./device/resolve-connection').readHandleDevice,
+    readHandle: readHandleDevice = require('./device/resolve-connection').readHandleDevice,
   },
   opts = {}
 ) {
@@ -1219,7 +1232,7 @@ async function handleSessionStart(
     // pinned to A reported already_running:true, device:B while every verb
     // kept driving A. Fail with a hint instead — the agent stays in control
     // and decides whether to `session end` and repin.
-    const pinned = readHandle(projectRoot);
+    const pinned = readHandleDevice(projectRoot);
     if (device !== null && device !== pinned) {
       return {
         envelope: fail(
@@ -1377,7 +1390,7 @@ async function handleDevicesClear({
   store = selectionStore,
   projectRoot,
   isAlive = require('./device/connection').isSessionAlive,
-  readHandle = require('./device/resolve-connection').readHandleDevice,
+  readHandle: readHandleDevice = require('./device/resolve-connection').readHandleDevice,
 } = {}) {
   const previous = store.read(projectRoot);
   store.clear(projectRoot);
@@ -1389,7 +1402,7 @@ async function handleDevicesClear({
   if (!alive) {
     return { envelope: ok({ cleared: previous || null }), exitKind: 'ok' };
   }
-  const pinned = readHandle(projectRoot);
+  const pinned = readHandleDevice(projectRoot);
   return {
     envelope: ok(
       { cleared: previous || null, daemon_still_pinned: pinned },
@@ -1576,6 +1589,8 @@ function buildProgram(deps = {}) {
     emitters = makeEmitters({ projectRoot }),
     // Sink used to emit the rendered envelope + drive the exit code.
     emit = emitters.emit,
+    // Host OS, for the unsupported-host gate (#165). Overridable in tests.
+    platform = process.platform,
   } = deps;
 
   const program = new Command();
@@ -1672,6 +1687,18 @@ function buildProgram(deps = {}) {
     return action(...args);
   };
 
+  // Gate for verbs that reach the device session layer (#165). Runs before
+  // anything is spawned or connected; see hostGate. Emits and returns true when
+  // the host is unsupported, so a caller can bail out.
+  const refuseUnsupportedHost = () => {
+    const refusal = hostGate(platform);
+    if (!refusal) return false;
+    emit(refusal, humanFlag());
+    return true;
+  };
+  const requireSupportedHost = (action) => (...args) =>
+    (refuseUnsupportedHost() ? undefined : action(...args));
+
   // Resolve which device a verb targets: explicit --device wins, else the
   // persisted selection, else null (mobile-mcp auto-selects a single device).
   // Keeping the no-selection fast path returning null preserves zero-config use.
@@ -1687,6 +1714,9 @@ function buildProgram(deps = {}) {
   // (the single connection seam), so this keeps both the envelope boundary and
   // the acquire-seam refactor.
   const connectBridge = async (device, fn) => {
+    // Before the factory: on an unsupported host there is nothing to connect,
+    // and a connect failure would land below as a misleading `device` kind.
+    if (refuseUnsupportedHost()) return;
     let bridge;
     let close;
     try {
@@ -2106,26 +2136,26 @@ function buildProgram(deps = {}) {
     .description('Start the device session daemon (subsequent verbs reuse its connection)')
     .option('--device <id>', 'pin the daemon to a target device id')
     .option('--idle <ms>', 'idle timeout in milliseconds before the daemon self-reaps')
-    .action(withEnvelope(requireWorkspace(async (opts) => {
+    .action(withEnvelope(requireSupportedHost(requireWorkspace(async (opts) => {
       const r = await handleSessionStart({ projectRoot }, { device: opts.device, idle: opts.idle });
       emit(r, humanFlag());
-    })));
+    }))));
 
   session
     .command('status')
     .description('Report whether a device session daemon is running')
-    .action(withEnvelope(async () => {
+    .action(withEnvelope(requireSupportedHost(async () => {
       const r = await handleSessionStatus({ projectRoot });
       emit(r, humanFlag());
-    }));
+    })));
 
   session
     .command('end')
     .description('Stop the device session daemon and remove its socket/pidfile')
-    .action(withEnvelope(async () => {
+    .action(withEnvelope(requireSupportedHost(async () => {
       const r = await handleSessionEnd({ projectRoot });
       emit(r, humanFlag());
-    }));
+    })));
 
   // --- Issue #92: device discovery + persisted selection -------------------
 
@@ -2150,6 +2180,12 @@ function buildProgram(deps = {}) {
   devices
     .command('clear')
     .description('Remove the persisted device selection')
+    // Deliberately OUTSIDE the host gate (#165): its only session-layer probe,
+    // sessionClient.isAlive, is a socket ping — it never runs `ps` or signals a
+    // process, so it answers safely on an unsupported host too. That invariant
+    // is executable, not just prose: the canary in
+    // tests/unit/cli-host-support.test.js ("devices clear stays process-free")
+    // fails if this verb ever starts spawning child processes.
     .action(withEnvelope(async () => {
       const r = await handleDevicesClear({ projectRoot });
       emit(r, humanFlag());
@@ -2288,7 +2324,7 @@ function makeEmitters({ projectRoot = process.cwd() } = {}) {
   // needed). A Date.now() stamped at require time would measure from whenever
   // cli.js was loaded, which is not process start for anything that requires it
   // first (a test harness, bin/mauto.js's own guards).
-  function finish({ text = '', exitKind, ok, errorKind, exitCode = exitCodeFor(exitKind) }) {
+  function finish({ text = '', exitKind, ok: succeeded, errorKind, exitCode = exitCodeFor(exitKind) }) {
     // The flag-resolved id when a command parsed, the environment otherwise: a
     // parse failure reaches no preAction hook and so has no flag, but it is
     // still part of the run and is exactly the class of failure (#146) this
@@ -2318,7 +2354,7 @@ function makeEmitters({ projectRoot = process.cwd() } = {}) {
       // tying this line to a run. sends:false in the event catalog.
       run_id: runId || undefined,
       session_id: resolvedSessionId || undefined,
-      ok,
+      ok: succeeded,
       error_kind: errorKind,
       exit_code: exitCode,
       dur_ms: Math.round(process.uptime() * 1000),

package/src/device/bridge.js

@@ -44,7 +44,7 @@ class DeviceBridge {
   // 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 });
+    return await this._call('mobile_click_on_screen_at_coordinates', { x, y });
   }
 
   // Long-press at absolute screen coordinates. Optional duration (ms) overrides
@@ -52,18 +52,18 @@ class DeviceBridge {
   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);
+    return await 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 });
+    return await 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 });
+    return await this._call('mobile_type_keys', { text, submit: false });
   }
 
   // Swipe in a cardinal direction.
@@ -135,32 +135,32 @@ class DeviceBridge {
 
   // Press a hardware/system button (BACK, HOME, ENTER, ...).
   async pressButton(button) {
-    return this._call('mobile_press_button', { button });
+    return await 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 });
+    return await 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 });
+    return await 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 });
+    return await 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 });
+    return await this._call('mobile_open_url', { url });
   }
 
   // Set the device orientation ('portrait'/'landscape').
   async setOrientation(orientation) {
-    return this._call('mobile_set_orientation', { orientation });
+    return await this._call('mobile_set_orientation', { orientation });
   }
 
   // Crash reports currently readable on the device, as the agnostic crash

package/src/device/host-support.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Which hosts can run the device session, and the error for the ones that
+// cannot (#165). The session daemon binds a Unix domain socket, and the
+// session layer identifies and reaps its daemon with `ps`, process-group kill
+// (`kill(-pid)`) and POSIX signals. None of that exists on Windows, where it
+// used to fail as a confusing `device` error — as if no phone were connected —
+// rather than saying the host itself is unsupported.
+//
+// package.json `os` is the single source of truth: npm refuses the install on
+// any other host, and this guard catches what slips past it (`--force`,
+// `npm link`, a vendored copy). Pure — no I/O; the caller decides how to emit.
+
+const pkg = require('../../package.json');
+
+const SUPPORTED_HOSTS = Object.freeze([...(pkg.os || [])]);
+
+// Human names for the error text — the ONE copy; the docs-agreement lint test
+// (tests/lint/host-support-agreement.test.js) consumes it rather than
+// restating it. Deliberately no fallback: a host added to package.json `os`
+// without a name here is a test failure and a crash at render time, not a raw
+// platform id leaking into the user-facing error.
+const HOST_NAMES = Object.freeze({ darwin: 'macOS', linux: 'Linux' });
+
+const TROUBLESHOOTING_REF = 'see TROUBLESHOOTING.md ("mauto refuses to run on Windows")';
+
+// Per-host guidance. Unknown hosts get the generic pointer instead of a
+// Windows-specific instruction — a freebsd user must not be told about WSL2.
+const HOST_HINTS = Object.freeze({
+  win32: `On Windows, install and run mauto inside WSL2 (a Linux distribution); ${TROUBLESHOOTING_REF}.`,
+});
+
+// For hosts with no specific hint: point at the troubleshooting entry without
+// naming an OS-specific route.
+const GENERIC_HINT = `See TROUBLESHOOTING.md for where mauto runs and how to get there.`;
+
+function isSupportedHost(platform = process.platform) {
+  return SUPPORTED_HOSTS.includes(platform);
+}
+
+function unsupportedHostError(platform = process.platform) {
+  const names = SUPPORTED_HOSTS.map((p) => HOST_NAMES[p]).join(' or ');
+  const err = new Error(
+    `mauto's device session needs a POSIX host (${names}); "${platform}" is not supported`
+  );
+  err.kind = 'environment';
+  err.hint = HOST_HINTS[platform] || GENERIC_HINT;
+  return err;
+}
+
+module.exports = { SUPPORTED_HOSTS, HOST_NAMES, isSupportedHost, unsupportedHostError };

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

@@ -133,8 +133,8 @@ async function createCall({
     throw connectError(err, connectTimeoutMs);
   }
 
-  async function rawCall(toolName, args = {}) {
-    const res = await client.callTool({ name: toolName, arguments: args });
+  async function rawCall(toolName, toolArgs = {}) {
+    const res = await client.callTool({ name: toolName, arguments: toolArgs });
     return parseToolResult(res);
   }
   const { call } = makeCall({ rawCall, device });

package/src/device/resolve-connection.js

@@ -31,8 +31,6 @@ function defaultCreateCall(opts) {
   return require('./mobile-mcp-client').createCall(opts);
 }
 
-const NOOP_CLOSE = () => Promise.resolve();
-
 // Read the live daemon's pinned device from its handle, or null. A null pin
 // means the daemon serves whatever device mobile-mcp selected (matches any
 // request that doesn't pin a specific device).

package/src/device/session-daemon.js

@@ -386,7 +386,13 @@ async function startDaemon({
     clearFlush();
     if (!flush || stopping) return;
     if (!(delayMs > 0) || !Number.isFinite(delayMs)) return;
-    flushTimer = setTimeout(async () => {
+    // tick() never rejects (its flush() is wrapped), so `void` is honest here.
+    flushTimer = setTimeout(() => {
+      void tick();
+    }, delayMs);
+    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+
+    async function tick() {
       if (stopping) return;
       if (inFlight > 0) {
         armFlush(delayMs);
@@ -402,8 +408,7 @@ async function startDaemon({
         // current caller.
       }
       armFlush(next);
-    }, delayMs);
-    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+    }
   }
 
   async function stop(reason = 'explicit') {
@@ -541,7 +546,27 @@ async function startDaemon({
       return true;
     };
 
-    socket.on('data', async (chunk) => {
+    // A plain listener around an async body, never `socket.on('data', async …)`:
+    // the emitter ignores the returned promise, so a throw in the body would be
+    // an unhandled rejection, and bin/mauto-session-daemon.js exits on those.
+    // Found by @typescript-eslint/no-misused-promises (#164).
+    socket.on('data', (chunk) => {
+      handleData(chunk).catch(onHandlerError);
+    });
+
+    // Recorded, then the idle clock re-armed: handleData paused it for the
+    // frame that threw, and nothing else would restart it. The remaining frames
+    // of that chunk are lost; the socket and the daemon both keep serving.
+    function onHandlerError(err) {
+      safeObserve({
+        level: 'error',
+        event: 'daemon.handler_error',
+        message: err && (err.message || String(err)),
+      });
+      armIdle();
+    }
+
+    async function handleData(chunk) {
       const frames = parser.push(chunk);
       for (const f of frames) {
         // Pause the idle clock while we handle a frame so it can never fire
@@ -554,11 +579,20 @@ async function startDaemon({
           continue;
         }
         const req = f.value;
+        // Valid JSON is not yet a request: `null` would throw on `req.type`
+        // below, and a primitive or array is no frame the protocol defines.
+        if (req === null || typeof req !== 'object' || Array.isArray(req)) {
+          await reply({ id: null, ok: false, error: { message: 'malformed frame: not a JSON object' } });
+          armIdle();
+          continue;
+        }
 
         if (req.type === 'shutdown') {
           await reply({ id: req.id, ok: true, result: { stopping: true } });
           // Reply already flushed (awaited) — now tear down.
-          setImmediate(() => stop('shutdown').catch(() => {}));
+          setImmediate(() => {
+            stop('shutdown').catch(() => {});
+          });
           continue;
         }
         if (req.type === 'ping') {
@@ -616,7 +650,7 @@ async function startDaemon({
         await reply({ id: req.id, ok: false, error: { message: `unknown request type: ${req.type}` } });
         armIdle();
       }
-    });
+    }
 
     socket.on('error', () => {
       sockets.delete(socket);

package/src/mcp/server.js

@@ -31,11 +31,14 @@ function buildServer({ projectRoot } = {}) {
     { capabilities: { prompts: {} } }
   );
 
-  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  // Plain functions, not async: both handlers are synchronous, and the SDK
+  // accepts a result or a promise of one. It calls them inside a .then(), so a
+  // throw (an unknown prompt name) still becomes an MCP error reply.
+  server.setRequestHandler(ListPromptsRequestSchema, () => ({
     prompts: handlers.listPrompts(),
   }));
 
-  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  server.setRequestHandler(GetPromptRequestSchema, (request) => {
     return handlers.getPrompt(request.params.name);
   });
 

package/src/memory/entries.js

@@ -12,6 +12,7 @@ const ENTRY_RE = /^-\s+\[(\d{4}-\d{2}-\d{2})\]\[asserted\]\s+(.*)$/;
 
 function sanitizeEntryText(raw) {
   return String(raw == null ? '' : raw)
+    // eslint-disable-next-line no-control-regex -- matching control chars is the point
     .replace(/[\u0000-\u001F\u007F]+/g, ' ') // control chars / newlines / tabs -> space
     .replace(/\s+/g, ' ')
     .trim();

package/src/observe/vocab.js

@@ -46,6 +46,7 @@ const EVENT_NAMES = Object.freeze([
   'daemon.engine_exit',
   'daemon.lock_conflict',
   'daemon.undeliverable',
+  'daemon.handler_error',
   // Emitted by the flush path, which lands in a later slice-5 task; declared
   // now because its event shape is already exercised by unit tests.
   'telemetry.flush',