mobile-automator 0.29.0 → 0.30.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "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": {
@@ -45,5 +45,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
-  }
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
 }

package/src/cli.js

@@ -26,6 +26,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 +268,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
@@ -1576,6 +1590,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 +1688,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 +1715,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 +2137,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 +2181,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());

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 };