mobile-debug-mcp 0.12.1 → 0.12.2

package/README.md

@@ -1,4 +1,4 @@
-# Mobile Dev MCP
+# Mobile Dev Tools
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 

package/dist/android/diagnostics.js

@@ -1,24 +1 @@
-import { spawnSync } from 'child_process';
-import { getAdbCmd } from './utils.js';
-import { makeEnvSnapshot } from '../utils/diagnostics.js';
-export function execAdbWithDiagnostics(args, deviceId) {
-    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
-    const timeout = 120000;
-    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
-    const 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 };
-}
+export { execAdbWithDiagnostics } from '../utils/diagnostics.js';

package/dist/android/manage.js

@@ -3,7 +3,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { existsSync } from 'fs';
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js';
-import { execAdbWithDiagnostics } from './diagnostics.js';
+import { execAdbWithDiagnostics } from '../utils/diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 export class AndroidManage {
     async build(projectPath, _variant) {

package/dist/ios/manage.js

@@ -1,5 +1,5 @@
 import { promises as fs } from "fs";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js";
 import path from "path";
 export class iOSManage {
@@ -34,10 +34,12 @@ export class iOSManage {
                 catch { }
                 return null;
             }
-            const projectInfo = await findProject(projectPath, 3);
+            // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
+            const absProjectPath = path.resolve(projectPath);
+            const projectInfo = await findProject(absProjectPath, 3);
             if (!projectInfo)
                 return { error: 'No Xcode project or workspace found' };
-            const projectRootDir = projectInfo.dir || projectPath;
+            const projectRootDir = projectInfo.dir || absProjectPath;
             const workspace = projectInfo.workspace;
             const proj = projectInfo.proj;
             // Determine destination: prefer explicit env var, otherwise use booted simulator UDID
@@ -50,15 +52,38 @@ export class iOSManage {
                 }
                 catch { }
             }
+            // Determine xcode command early so it can be used when detecting schemes
+            const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
+            // Determine available schemes by querying xcodebuild -list rather than guessing
+            async function detectScheme(xcodeCmdInner, workspacePath, projectPathFull, cwd) {
+                try {
+                    const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull];
+                    // Run xcodebuild directly to list schemes
+                    const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 });
+                    const out = res.stdout || '';
+                    const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m);
+                    if (schemesMatch) {
+                        const block = schemesMatch[1];
+                        const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean);
+                        if (schemes.length)
+                            return schemes[0];
+                    }
+                }
+                catch { }
+                return null;
+            }
             let buildArgs;
+            let chosenScheme = null;
             if (workspace) {
                 const workspacePath = path.join(projectRootDir, workspace);
-                const scheme = workspace.replace(/\.xcworkspace$/, '');
+                chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir);
+                const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '');
                 buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
             else {
                 const projectPathFull = path.join(projectRootDir, proj);
-                const scheme = proj.replace(/\.xcodeproj$/, '');
+                chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir);
+                const scheme = chosenScheme || proj.replace(/\.xcodeproj$/, '');
                 buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
             // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
@@ -71,7 +96,6 @@ export class iOSManage {
             await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => { });
             await fs.mkdir(resultsDir, { recursive: true }).catch(() => { });
             // Skip specifying -resultBundlePath to avoid platform-specific collisions; rely on stdout/stderr logs
-            const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
             const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
             const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
             const tries = MAX_RETRIES + 1;
@@ -81,7 +105,7 @@ export class iOSManage {
             for (let attempt = 1; attempt <= tries; attempt++) {
                 // Run xcodebuild with a watchdog
                 const res = await new Promise((resolve) => {
-                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectPath });
+                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir });
                     let stdout = '';
                     let stderr = '';
                     proc.stdout?.on('data', d => stdout += d.toString());
@@ -112,6 +136,9 @@ export class iOSManage {
                 }
                 // record the failure for reporting
                 lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`);
+                lastErr.code = res.code;
+                lastErr.exitCode = res.code;
+                lastErr.killedByWatchdog = !!res.killedByWatchdog;
                 // write logs for diagnostics (helpful whether killed or not)
                 try {
                     await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => { });
@@ -127,8 +154,10 @@ export class iOSManage {
                     break;
             }
             if (lastErr) {
-                // Include diagnostics and result bundle path when available
-                return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}` };
+                // Include diagnostics and result bundle path when available; provide structured info useful for agents
+                const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
+                const envSnapshot = { PATH: process.env.PATH };
+                return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: lastErr.code || null, invokedCommand, cwd: projectRootDir, envSnapshot } };
             }
             // Try to locate built .app. First search project tree, then DerivedData if necessary
             const built = await findAppBundle(projectPath);

package/dist/tools/interact.js

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidInteract } from '../android/interact.js';
 import { iOSInteract } from '../ios/interact.js';
 export class ToolsInteract {

package/dist/tools/manage.js

@@ -1,6 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { resolveTargetDevice, listDevices } from '../resolve-device.js';
+import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js';
 import { AndroidManage } from '../android/manage.js';
 import { iOSManage } from '../ios/manage.js';
 export class ToolsManage {

package/dist/tools/observe.js

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from '../android/observe.js';
 import { iOSObserve } from '../ios/observe.js';
 export class ToolsObserve {

package/dist/utils/diagnostics.js

@@ -23,3 +23,27 @@ export class DiagnosticError extends Error {
         this.runResult = runResult;
     }
 }
+// Exec ADB with diagnostics — moved from src/android/diagnostics.ts
+import { spawnSync } from 'child_process';
+import { getAdbCmd } from '../android/utils.js';
+export function execAdbWithDiagnostics(args, deviceId) {
+    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
+    const timeout = 120000;
+    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
+    const 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 };
+}

package/dist/utils/resolve-device.js

@@ -0,0 +1,62 @@
+import { listAndroidDevices } from "../android/utils.js";
+import { listIOSDevices } from "../ios/utils.js";
+function parseNumericVersion(v) {
+    if (!v)
+        return 0;
+    const m = v.match(/(\d+)(?:[\.\-](\d+))?/);
+    if (!m)
+        return 0;
+    const major = parseInt(m[1], 10) || 0;
+    const minor = parseInt(m[2] || "0", 10) || 0;
+    return major + minor / 100;
+}
+export async function listDevices(platform, appId) {
+    if (!platform || platform === "android") {
+        const android = await listAndroidDevices(appId);
+        if (platform === "android")
+            return android;
+        const ios = await listIOSDevices(appId);
+        return [...android, ...ios];
+    }
+    return listIOSDevices(appId);
+}
+export async function resolveTargetDevice(opts) {
+    const { platform, appId, prefer, deviceId } = opts;
+    const devices = await listDevices(platform, appId);
+    if (deviceId) {
+        const found = devices.find(d => d.id === deviceId);
+        if (!found)
+            throw new Error(`Device '${deviceId}' not found for platform ${platform}`);
+        return found;
+    }
+    let candidates = devices.slice();
+    if (prefer === "physical")
+        candidates = candidates.filter(d => !d.simulator);
+    if (prefer === "emulator")
+        candidates = candidates.filter(d => d.simulator);
+    if (appId) {
+        const installed = candidates.filter(d => d.appInstalled);
+        if (installed.length > 0)
+            candidates = installed;
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    if (candidates.length > 1) {
+        if (!prefer) {
+            const physical = candidates.filter(d => !d.simulator);
+            if (physical.length === 1)
+                return physical[0];
+            if (physical.length > 1)
+                candidates = physical;
+        }
+        candidates.sort((a, b) => parseNumericVersion(b.osVersion) - parseNumericVersion(a.osVersion));
+        if (candidates.length > 1 && parseNumericVersion(candidates[0].osVersion) > parseNumericVersion(candidates[1].osVersion)) {
+            return candidates[0];
+        }
+        const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }));
+        const err = new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`);
+        err.devices = list;
+        throw err;
+    }
+    throw new Error(`No devices found for platform ${platform}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/android/manage.ts

@@ -3,7 +3,7 @@ import { spawn } from 'child_process'
 import path from 'path'
 import { existsSync } from 'fs'
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js'
-import { execAdbWithDiagnostics } from './diagnostics.js'
+import { execAdbWithDiagnostics } from '../utils/diagnostics.js'
 import { detectJavaHome } from '../utils/java.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 

package/src/ios/manage.ts

@@ -1,11 +1,11 @@
 import { promises as fs } from "fs"
-import { spawn } from "child_process"
+import { spawn, spawnSync } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js"
 import path from "path"
 
 export class iOSManage {
-  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
+  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
     void _variant
     try {
       // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
@@ -34,9 +34,11 @@ export class iOSManage {
         return null
       }
 
-      const projectInfo = await findProject(projectPath, 3)
+      // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
+      const absProjectPath = path.resolve(projectPath)
+      const projectInfo = await findProject(absProjectPath, 3)
       if (!projectInfo) return { error: 'No Xcode project or workspace found' }
-      const projectRootDir = projectInfo.dir || projectPath
+      const projectRootDir = projectInfo.dir || absProjectPath
       const workspace = projectInfo.workspace
       const proj = projectInfo.proj
 
@@ -49,14 +51,37 @@ export class iOSManage {
         } catch {}
       }
 
+      // Determine xcode command early so it can be used when detecting schemes
+      const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild'
+
+      // Determine available schemes by querying xcodebuild -list rather than guessing
+      async function detectScheme(xcodeCmdInner: string, workspacePath?: string, projectPathFull?: string, cwd?: string): Promise<string | null> {
+        try {
+          const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull!]
+          // Run xcodebuild directly to list schemes
+          const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 })
+          const out = res.stdout || ''
+          const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m)
+          if (schemesMatch) {
+            const block = schemesMatch[1]
+            const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean)
+            if (schemes.length) return schemes[0]
+          }
+        } catch {}
+        return null
+      }
+
       let buildArgs: string[]
+      let chosenScheme: string | null = null
       if (workspace) {
         const workspacePath = path.join(projectRootDir, workspace)
-        const scheme = workspace.replace(/\.xcworkspace$/, '')
+        chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir)
+        const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '')
         buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build']
       } else {
         const projectPathFull = path.join(projectRootDir, proj!)
-        const scheme = proj!.replace(/\.xcodeproj$/, '')
+        chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir)
+        const scheme = chosenScheme || proj!.replace(/\.xcodeproj$/, '')
         buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build']
       }
 
@@ -73,7 +98,6 @@ export class iOSManage {
       // Skip specifying -resultBundlePath to avoid platform-specific collisions; rely on stdout/stderr logs
 
 
-      const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild'
       const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
       const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
 
@@ -85,7 +109,7 @@ export class iOSManage {
       for (let attempt = 1; attempt <= tries; attempt++) {
         // Run xcodebuild with a watchdog
         const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
-          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectPath })
+          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir })
           let stdout = ''
           let stderr = ''
 
@@ -119,6 +143,10 @@ export class iOSManage {
 
         // record the failure for reporting
         lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`)
+        // Attach exit code and watchdog info so diagnostics can include them
+        ;(lastErr as any).code = res.code
+        ;(lastErr as any).exitCode = res.code
+        ;(lastErr as any).killedByWatchdog = !!res.killedByWatchdog
 
         // write logs for diagnostics (helpful whether killed or not)
         try {
@@ -136,8 +164,10 @@ export class iOSManage {
       }
 
       if (lastErr) {
-        // Include diagnostics and result bundle path when available
-        return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}` }
+        // Include diagnostics and result bundle path when available; provide structured info useful for agents
+        const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`
+        const envSnapshot = { PATH: process.env.PATH }
+        return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: (lastErr as any).code || null, invokedCommand, cwd: projectRootDir, envSnapshot } }
       }
 
       // Try to locate built .app. First search project tree, then DerivedData if necessary

package/src/tools/interact.ts

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js'
+import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { AndroidInteract } from '../android/interact.js'
 import { iOSInteract } from '../ios/interact.js'
 

package/src/tools/manage.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from 'fs'
 import path from 'path'
-import { resolveTargetDevice, listDevices } from '../resolve-device.js'
+import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js'
 import { AndroidManage } from '../android/manage.js'
 import { iOSManage } from '../ios/manage.js'
 import type { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'

package/src/tools/observe.ts

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js'
+import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { AndroidObserve } from '../android/observe.js'
 import { iOSObserve } from '../ios/observe.js'
 

package/src/utils/diagnostics.ts

@@ -34,3 +34,27 @@ export class DiagnosticError extends Error {
     this.runResult = runResult
   }
 }
+
+// Exec ADB with diagnostics — moved from src/android/diagnostics.ts
+import { spawnSync } from 'child_process'
+import { getAdbCmd } from '../android/utils.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 })
+  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 }
+}

package/src/{resolve-device.ts → utils/resolve-device.ts}

@@ -1,6 +1,6 @@
-import { DeviceInfo } from "./types.js"
-import { listAndroidDevices } from "./android/utils.js"
-import { listIOSDevices } from "./ios/utils.js"
+import { DeviceInfo } from "../types.js"
+import { listAndroidDevices } from "../android/utils.js"
+import { listIOSDevices } from "../ios/utils.js"
 
 export interface ResolveOptions {
   platform: "android" | "ios"
@@ -11,7 +11,6 @@ export interface ResolveOptions {
 
 function parseNumericVersion(v: string): number {
   if (!v) return 0
-  // extract first number groups like 17.0 -> 17.0 or Android 12 -> 12
   const m = v.match(/(\d+)(?:[\.\-](\d+))?/) 
   if (!m) return 0
   const major = parseInt(m[1], 10) || 0
@@ -23,7 +22,6 @@ export async function listDevices(platform?: "android" | "ios", appId?: string):
   if (!platform || platform === "android") {
     const android = await listAndroidDevices(appId)
     if (platform === "android") return android
-    // if no platform specified, merge with ios below
     const ios = await listIOSDevices(appId)
     return [...android, ...ios]
   }
@@ -42,11 +40,9 @@ export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceI
 
   let candidates = devices.slice()
 
-  // Apply prefer filter
   if (prefer === "physical") candidates = candidates.filter(d => !d.simulator)
   if (prefer === "emulator") candidates = candidates.filter(d => d.simulator)
 
-  // If appId provided, prefer devices with appInstalled
   if (appId) {
     const installed = candidates.filter(d => (d as any).appInstalled)
     if (installed.length > 0) candidates = installed
@@ -55,21 +51,17 @@ export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceI
   if (candidates.length === 1) return candidates[0]
 
   if (candidates.length > 1) {
-    // Prefer physical over emulator unless prefer=emulator
     if (!prefer) {
       const physical = candidates.filter(d => !d.simulator)
       if (physical.length === 1) return physical[0]
       if (physical.length > 1) candidates = physical
     }
 
-    // Pick highest OS version
     candidates.sort((a, b) => parseNumericVersion(b.osVersion) - parseNumericVersion(a.osVersion))
-    // If top is unique (numeric differs), return it
     if (candidates.length > 1 && parseNumericVersion(candidates[0].osVersion) > parseNumericVersion(candidates[1].osVersion)) {
       return candidates[0]
     }
 
-    // Ambiguous: throw an error with candidate list so caller (agent) can present choices
     const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: (d as any).appInstalled }))
     const err = new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`)
     ;(err as any).devices = list

package/src/android/diagnostics.ts

@@ -1,23 +0,0 @@
-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 }
-}