mobile-debug-mcp 0.11.0 → 0.12.0

package/dist/server.js

@@ -126,6 +126,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["appPath"]
             }
         },
+        {
+            name: "build_app",
+            description: "Build a project for Android or iOS and return the built artifact path. Does not install.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+                    projectPath: { type: "string", description: "Path to project directory (contains gradlew or xcodeproj/xcworkspace)" },
+                    variant: { type: "string", description: "Optional build variant (e.g., Debug/Release)" }
+                },
+                required: ["projectPath"]
+            }
+        },
         {
             name: "get_logs",
             description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
@@ -411,6 +424,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
             return wrapResponse(response);
         }
+        if (name === "build_app") {
+            const { platform, projectPath, variant } = args;
+            const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant });
+            return wrapResponse(res);
+        }
         if (name === 'build_and_install') {
             const { platform, projectPath, deviceId, timeout } = args;
             const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout });

package/dist/utils/diagnostics.js

@@ -0,0 +1,25 @@
+export function makeEnvSnapshot(keys) {
+    const snap = {};
+    for (const k of keys)
+        snap[k] = process.env[k];
+    return snap;
+}
+export function wrapExecResult(command, args, res) {
+    return {
+        exitCode: res.status,
+        stdout: res.stdout ? (typeof res.stdout === 'string' ? res.stdout : res.stdout.toString()) : '',
+        stderr: res.stderr ? (typeof res.stderr === 'string' ? res.stderr : res.stderr.toString()) : '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'IDB_PATH', 'JAVA_HOME', 'HOME']),
+        command,
+        args,
+        suggestedFixes: []
+    };
+}
+export class DiagnosticError extends Error {
+    runResult;
+    constructor(message, runResult) {
+        super(message);
+        this.name = 'DiagnosticError';
+        this.runResult = runResult;
+    }
+}

package/docs/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.12.0]
+- Add iOS idb integration: config-driven idb path resolution (MCP_IDB_PATH / MCP config / IDB_PATH), robust idb detection and parsing of `ui describe-all` output.
+- Add reusable helpers: `isIDBInstalled()` and `getIdbCmd()` to centralise idb resolution and diagnostics.
+- Ensure install_app can build binaries (xcodebuild / Gradle) before installing so agents can autonomously build, install and validate fixes.
+- Add idb integration test (UI-tree + tap) and reorganise device-dependent tests under `test/device`.
+- Gate device tests behind RUN_DEVICE_TESTS (device tests won't run in default CI); added `test:device` runner and updated npm scripts.
+- Linting & tooling fixes: ESLint adjustments (ignore generated scripts), ESM entry fix for install-idb.ts, and various lint cleanups.
+- Added `test/device/README.md` with device-test run instructions.
+
+
 ## [0.11.0]
 - Tools refactor - broke functions into 3 distinct class types; interact (for UI manipulation), manage (for build, installing etc) and observe (observing the app whilst running)
 - Add convenience method to build and install

package/eslint.config.js

@@ -11,7 +11,8 @@ export default [
       '.git/',
       '.vscode/',
       'coverage/',
-      '.env'
+      '.env',
+      'scripts/'
     ]
   },
   // Apply rules to JS/TS source
@@ -56,5 +57,25 @@ export default [
       'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
       '@typescript-eslint/no-unused-vars': 'off'
     }
+  },
+  // Apply rules to scripts and tooling (support TS syntax in scripts)
+  {
+    files: ['scripts/**/*.ts', 'scripts/**/*.js'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'unused-imports': unusedImports
+    },
+    rules: {
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
+      '@typescript-eslint/no-unused-vars': 'off'
+    }
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -10,9 +10,12 @@
     "build": "tsc",
     "start": "node ./dist/server.js",
     "prepare": "npm run build",
+    "healthcheck": "tsx ./scripts/check-idb.ts",
+    "install-idb": "tsx ./scripts/install-idb.ts",
     "test:unit": "tsx test/unit/index.ts",
-    "test:integration": "tsx test/integration/index.ts",
-    "test": "npm run test:unit && npm run test:integration",
+    "test:integration": "npm run build && tsx test/device/index.ts",
+    "test:device": "npm run build && tsx test/device/index.ts",
+    "test": "npm run test:unit",
     "lint": "eslint --ext .ts,.js src test --quiet",
     "lint:fix": "eslint --ext .ts,.js src test --fix"
   },
@@ -26,8 +29,8 @@
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
     "eslint": "^9.39.4",
     "eslint-plugin-unused-imports": "^4.4.1",
     "tsx": "^4.21.0",

package/scripts/check-idb.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process';
+import { main as installMain } from './install-idb';
+function which(cmd) {
+    try {
+        // Prefer POSIX `command -v` which can resolve shell builtins. Use spawnSync
+        // to avoid shell interpolation and injection risks. Fall back to `which`.
+        const res = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (res && res.status === 0 && res.stdout) return res.stdout.toString().trim();
+        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+function print(...args) {
+    console.log(...args);
+}
+async function runInstaller() {
+    try {
+        // prefer invoking the TS script via npx/tsx to ensure environment
+        const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null;
+        if (runner) {
+            const args = runner === 'npx' ? ['tsx', './scripts/install-idb.ts'] : ['./scripts/install-idb.ts'];
+            const res = spawnSync(runner, args, { stdio: 'inherit' });
+            return typeof res.status === 'number' ? res.status === 0 : false;
+        }
+        // fallback: attempt to import and run the installer directly (may rely on ts-node/tsx)
+        try {
+            // call the exported main; it returns a promise
+            await installMain();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    catch (e) {
+        console.error('Failed to run installer:', e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+(async () => {
+    try {
+        print('PATH=', process.env.PATH);
+        const idb = process.env.IDB_PATH || which('idb');
+        print('which idb:', idb);
+        if (idb) {
+            try {
+                print('idb --version:', execSync('idb --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+            }
+            catch (e) {
+                print('idb --version: (failed)', e instanceof Error ? e.message : String(e));
+            }
+            const companion = which('idb_companion');
+            print('which idb_companion:', companion);
+            if (companion)
+                try {
+                    print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+                }
+                catch (e) {
+                    print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e));
+                }
+            process.exit(0);
+        }
+        print('idb not found');
+        const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true';
+        if (auto) {
+            print('MCP_AUTO_INSTALL_IDB=true, attempting installer...');
+            const ok = await runInstaller();
+            if (ok)
+                process.exit(0);
+            print('Installer failed or did not produce idb');
+            process.exit(2);
+        }
+        print('Set MCP_AUTO_INSTALL_IDB=true to attempt automatic installation (CI-friendly).');
+        process.exit(2);
+    }
+    catch (e) {
+        console.error('idb healthcheck failed:', e instanceof Error ? e.message : String(e));
+        process.exit(2);
+    }
+})();

package/scripts/check-idb.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process'
+import { main as installMain } from './install-idb'
+import { getIdbCmd, isIDBInstalled } from './idb-helper'
+
+function which(cmd: string): string | null {
+  try {
+    const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] })
+    if (r && r.status === 0 && r.stdout) return r.stdout.toString().trim()
+  } catch {}
+  try {
+    return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
+  } catch {
+    return null
+  }
+}
+
+function print(...args: any[]) {
+  console.log(...args)
+}
+
+async function runInstaller() {
+  try {
+    // prefer invoking the TS script via npx/tsx to ensure environment
+    const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null
+    if (runner) {
+      const args = runner === 'npx' ? ['tsx', './scripts/install-idb.ts'] : ['./scripts/install-idb.ts']
+      const res = spawnSync(runner, args, { stdio: 'inherit' as any })
+      return typeof res.status === 'number' ? res.status === 0 : false
+    }
+
+    // fallback: attempt to import and run the installer directly (may rely on ts-node/tsx)
+    try {
+      // call the exported main; it returns a promise
+      await installMain()
+      return true
+    } catch {
+      return false
+    }
+  } catch (e) {
+    console.error('Failed to run installer:', e instanceof Error ? e.message : String(e))
+    return false
+  }
+}
+
+try {
+  print('PATH=', process.env.PATH)
+  const idb = process.env.IDB_PATH || getIdbCmd()
+  print('idb:', idb)
+  if (idb && isIDBInstalled()) {
+    try { print('idb --version:', execSync(`${idb} --version`, { stdio: ['ignore','pipe','ignore'] }).toString().trim()) } catch (e) { print('idb --version: (failed)', e instanceof Error ? e.message : String(e)) }
+    const companion = which('idb_companion')
+    print('which idb_companion:', companion)
+    if (companion) try { print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore','pipe','ignore'] }).toString().trim()) } catch (e) { print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e)) }
+    process.exit(0)
+  }
+
+  print('idb not found or not responding')
+  const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true'
+  if (auto) {
+    print('MCP_AUTO_INSTALL_IDB=true, attempting installer...')
+    const ok = runInstaller()
+    if (ok) process.exit(0)
+    print('Installer failed or did not produce idb')
+    process.exit(2)
+  }
+
+  print('Set MCP_AUTO_INSTALL_IDB=true to attempt automatic installation (CI-friendly).')
+  process.exit(2)
+} catch (e) {
+  console.error('idb healthcheck failed:', e instanceof Error ? e.message : String(e))
+  process.exit(2)
+}

package/scripts/idb-helper.ts

@@ -0,0 +1,76 @@
+import { execSync, spawnSync } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+
+export function getConfiguredIdbPath(): string | undefined {
+  if (process.env.MCP_IDB_PATH) return process.env.MCP_IDB_PATH
+  if (process.env.IDB_PATH) return process.env.IDB_PATH
+  const cfgPaths = [
+    process.env.MCP_CONFIG_PATH || (process.env.HOME ? `${process.env.HOME}/.mcp/config.json` : ''),
+    `${process.cwd()}/mcp.config.json`
+  ]
+  for (const p of cfgPaths) {
+    if (!p) continue
+    try {
+      if (fs.existsSync(p)) {
+        const raw = fs.readFileSync(p, 'utf8')
+        const json = JSON.parse(raw)
+        if (json) {
+          if (json.idbPath) return json.idbPath
+          if (json.IDB_PATH) return json.IDB_PATH
+        }
+      }
+    } catch {}
+  }
+  return undefined
+}
+
+export function commandWhich(cmd: string): string | null {
+  try {
+    const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] })
+    if (r && r.status === 0 && r.stdout) return r.stdout.toString().trim()
+  } catch {}
+  try {
+    const p = execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
+    if (p) return p
+  } catch {}
+  return null
+}
+
+export function getIdbCmd(): string | null {
+  const cfg = getConfiguredIdbPath()
+  if (cfg) return cfg
+  if (process.env.IDB_PATH) return process.env.IDB_PATH
+
+  // Prefer command -v/which
+  const found = commandWhich('idb')
+  if (found) return found
+
+  // Common locations
+  const common = [
+    process.env.HOME ? `${process.env.HOME}/Library/Python/3.9/bin/idb` : '',
+    process.env.HOME ? `${process.env.HOME}/Library/Python/3.10/bin/idb` : '',
+    '/opt/homebrew/bin/idb',
+    '/usr/local/bin/idb'
+  ]
+  for (const c of common) {
+    if (!c) continue
+    try { execSync(`test -x ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] }); return c } catch {}
+  }
+  return null
+}
+
+export function isIDBInstalled(): boolean {
+  const cmd = getIdbCmd()
+  if (!cmd) return false
+  try {
+    // command -v <cmd>
+    const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] })
+    if (r && r.status === 0) return true
+  } catch {}
+  try {
+    execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 })
+    return true
+  } catch {}
+  return false
+}

package/scripts/install-idb.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process';
+import readline from 'readline';
+const IDB_PKG = 'fb-idb';
+function which(cmd) {
+    try {
+        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+function runCommand(cmd, args) {
+    const res = spawnSync(cmd, args, { stdio: 'inherit' });
+    return typeof res.status === 'number' ? res.status : 1;
+}
+async function confirm(prompt) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${prompt} (y/N): `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase() === 'y');
+        });
+    });
+}
+async function main() {
+    try {
+        const idbFromEnv = process.env.IDB_PATH;
+        const existing = idbFromEnv || which('idb') || which('command -v idb');
+        if (existing) {
+            console.log('idb already available at:', existing);
+            process.exit(0);
+        }
+        const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true' || process.env.CI === 'true';
+        if (!auto) {
+            const ok = await confirm('idb not found. Attempt to install fb-idb now?');
+            if (!ok) {
+                console.log('Aborting install; set MCP_AUTO_INSTALL_IDB=true to auto-install in CI or non-interactive environments.');
+                process.exit(2);
+            }
+        }
+        else {
+            console.log('Auto-install enabled (MCP_AUTO_INSTALL_IDB=true or CI=true)');
+        }
+        const attempts = [];
+        if (which('pipx'))
+            attempts.push({ name: 'pipx', cmd: 'pipx', args: ['install', IDB_PKG] });
+        if (which('pip') || which('python3'))
+            attempts.push({ name: 'pip', cmd: which('pip') ? 'pip' : 'python3', args: which('pip') ? ['install', '--user', IDB_PKG] : ['-m', 'pip', 'install', '--user', IDB_PKG] });
+        // Add brew as a fallback on macOS if present (best-effort)
+        if (process.platform === 'darwin' && which('brew')) {
+            attempts.push({ name: 'brew', cmd: 'brew', args: ['install', 'idb'] });
+        }
+        if (attempts.length === 0) {
+            console.error('No installer tool (pipx/pip/brew) detected. Please install pipx or pip and re-run.');
+            process.exit(2);
+        }
+        for (const a of attempts) {
+            console.log(`Attempting install with ${a.name}: ${a.cmd} ${a.args.join(' ')}`);
+            try {
+                const code = runCommand(a.cmd, a.args);
+                if (code !== 0) {
+                    console.warn(`${a.name} install exited with code ${code}`);
+                }
+            }
+            catch (e) {
+                console.warn(`${a.name} install failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            const found = which('idb') || which('command -v idb');
+            if (found) {
+                console.log('idb installed at:', found);
+                process.exit(0);
+            }
+        }
+        console.error('idb was not installed by any installer tried. Please install fb-idb manually and re-run healthcheck.');
+        process.exit(2);
+    }
+    catch (e) {
+        console.error('Installer failed:', e instanceof Error ? e.message : String(e));
+        process.exit(2);
+    }
+}
+if (require.main === module) {
+    main();
+}
+export { main };

package/scripts/install-idb.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process'
+import readline from 'readline'
+import { getIdbCmd, isIDBInstalled, commandWhich } from './idb-helper'
+
+const IDB_PKG = 'fb-idb'
+
+function runCommand(cmd: string, args: string[]): number {
+  const res = spawnSync(cmd, args, { stdio: 'inherit' as any })
+  return typeof res.status === 'number' ? res.status : 1
+}
+
+async function confirm(prompt: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => {
+    rl.question(`${prompt} (y/N): `, (ans) => {
+      rl.close()
+      resolve(ans.trim().toLowerCase() === 'y')
+    })
+  })
+}
+
+async function main() {
+  try {
+    const idbFromEnv = process.env.IDB_PATH
+    const existing = idbFromEnv || getIdbCmd()
+    if (existing && isIDBInstalled()) {
+      console.log('idb already available at:', existing)
+      process.exit(0)
+    }
+
+    const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true' || process.env.CI === 'true'
+
+    if (!auto) {
+      const ok = await confirm('idb not found. Attempt to install fb-idb now?')
+      if (!ok) {
+        console.log('Aborting install; set MCP_AUTO_INSTALL_IDB=true to auto-install in CI or non-interactive environments.')
+        process.exit(2)
+      }
+    } else {
+      console.log('Auto-install enabled (MCP_AUTO_INSTALL_IDB=true or CI=true)')
+    }
+
+    const attempts: { name: string; cmd: string; args: string[] }[] = []
+    if (commandWhich('pipx')) attempts.push({ name: 'pipx', cmd: 'pipx', args: ['install', IDB_PKG] })
+    if (commandWhich('pip') || commandWhich('python3')) attempts.push({ name: 'pip', cmd: commandWhich('pip') ? 'pip' : 'python3', args: commandWhich('pip') ? ['install', '--user', IDB_PKG] : ['-m', 'pip', 'install', '--user', IDB_PKG] })
+
+    // Add brew as a fallback on macOS if present (best-effort)
+    if (process.platform === 'darwin' && commandWhich('brew')) {
+      attempts.push({ name: 'brew', cmd: 'brew', args: ['install', 'idb'] })
+    }
+
+    if (attempts.length === 0) {
+      console.error('No installer tool (pipx/pip/brew) detected. Please install pipx or pip and re-run.')
+      process.exit(2)
+    }
+
+    for (const a of attempts) {
+      console.log(`Attempting install with ${a.name}: ${a.cmd} ${a.args.join(' ')}`)
+      try {
+        const code = runCommand(a.cmd, a.args)
+        if (code !== 0) {
+          console.warn(`${a.name} install exited with code ${code}`)
+        }
+      } catch (e) {
+        console.warn(`${a.name} install failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+
+      const found = which('idb') || which('command -v idb')
+      if (found) {
+        console.log('idb installed at:', found)
+        process.exit(0)
+      }
+    }
+
+    console.error('idb was not installed by any installer tried. Please install fb-idb manually and re-run healthcheck.')
+    process.exit(2)
+  } catch (e) {
+    console.error('Installer failed:', e instanceof Error ? e.message : String(e))
+    process.exit(2)
+  }
+}
+
+const scriptPath = new URL(import.meta.url).pathname;
+if (scriptPath === process.argv[1]) {
+  main().catch(e => { console.error('Installer failed:', e instanceof Error ? e.message : String(e)); process.exit(2); });
+}
+
+export { main }

package/scripts/run-ios-smoke.ts

@@ -0,0 +1,34 @@
+import { iOSObserve } from '../src/ios/observe.js';
+import { iOSManage } from '../src/ios/manage.js';
+
+async function main() {
+  const appId = process.argv[2] || 'com.apple.springboard';
+  const deviceId = 'booted';
+  const obs = new iOSObserve();
+  const manage = new iOSManage();
+
+  try {
+    console.log('[1] startApp ->', appId)
+    const start = await manage.startApp(appId, deviceId);
+    console.log('start result:', start)
+
+    console.log('[2] captureScreenshot')
+    const shot = await obs.captureScreenshot(deviceId);
+    console.log('screenshot OK? size:', shot && shot.screenshot ? shot.screenshot.length : 0)
+
+    console.log('[3] getLogs')
+    const logs = await obs.getLogs(appId, undefined);
+    console.log('logs count:', logs.logCount)
+
+    console.log('[4] terminateApp')
+    const term = await manage.terminateApp(appId, deviceId);
+    console.log('terminate:', term)
+
+    console.log('SMOKE OK')
+  } catch (err) {
+    console.error('SMOKE ERROR:', err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  }
+}
+
+main();

package/scripts/run-ios-ui-tree-tap.ts

@@ -0,0 +1,33 @@
+import { iOSObserve } from '../src/ios/observe.js';
+import { iOSInteract } from '../src/ios/interact.js';
+
+async function main() {
+  const deviceId = 'booted';
+  const obs = new iOSObserve();
+  const interact = new iOSInteract();
+
+  console.log('Fetching UI tree...');
+  const tree = await obs.getUITree(deviceId as any);
+  if (tree.error) {
+    console.error('getUITree error:', tree.error);
+    process.exit(2);
+  }
+  console.log('Elements found:', tree.elements.length);
+  if (!tree.elements || tree.elements.length === 0) {
+    console.error('No elements found; aborting');
+    process.exit(3);
+  }
+
+  const clickable = tree.elements.find(e => e.clickable) || tree.elements[0];
+  console.log('Using element:', clickable.text || '(no text)', 'clickable=', clickable.clickable, 'center=', clickable.center);
+  const [x,y] = clickable.center || [0,0];
+
+  console.log(`Tapping at ${x},${y}...`);
+  const res = await interact.tap(x, y, deviceId as any);
+  console.log('Tap result:', res);
+
+  if (res.success) process.exit(0);
+  else process.exit(4);
+}
+
+main();

package/src/android/diagnostics.ts

@@ -0,0 +1,23 @@
+import { spawnSync } from 'child_process'
+import { getAdbCmd } from './utils.js'
+import { RunResult, makeEnvSnapshot } from '../utils/diagnostics.js'
+
+export function execAdbWithDiagnostics(args: string[], deviceId?: string) {
+  const adbArgs = deviceId ? ['-s', deviceId, ...args] : args
+  const timeout = 120000
+  const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout }) as any
+  const runResult: RunResult = {
+    exitCode: typeof res.status === 'number' ? res.status : null,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    envSnapshot: makeEnvSnapshot(['PATH','ADB_PATH','HOME','JAVA_HOME']),
+    command: getAdbCmd(),
+    args: adbArgs,
+    suggestedFixes: []
+  }
+  if (res.status !== 0) {
+    if ((runResult.stderr || '').includes('device not found')) runResult.suggestedFixes!.push('Ensure device is connected and adb is authorized (adb devices)')
+    if ((runResult.stderr || '').includes('No such file or directory')) runResult.suggestedFixes!.push('Verify ADB_PATH or that adb is installed')
+  }
+  return { runResult }
+}