mobile-debug-mcp 0.7.0 → 0.9.0

package/src/android/utils.ts

@@ -1,7 +1,75 @@
-import { spawn } from "child_process"
+import { spawn, execSync } from 'child_process'
 import { DeviceInfo } from "../types.js"
+import { existsSync, createWriteStream, promises as fsPromises } from 'fs'
+import path from 'path'
 
-export const ADB = process.env.ADB_PATH || "adb"
+export const ADB = process.env.ADB_PATH || 'adb'
+
+export async function detectJavaHome(): Promise<string | undefined> {
+  try {
+    // If JAVA_HOME is set, validate it's Java 17
+    if (process.env.JAVA_HOME) {
+      try {
+        const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java')
+        const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString()
+        if (/\b17\b/.test(v) || /17\./.test(v)) return process.env.JAVA_HOME
+        console.debug('[android] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17')
+      } catch (e) {
+        console.debug('[android] Failed to validate existing JAVA_HOME, searching for JDK17')
+      }
+    }
+
+    // macOS explicit path
+    const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home'
+    if (existsSync(explicit)) return explicit
+
+    // Android Studio JBR candidates
+    const jbrCandidates = [
+      '/Applications/Android Studio.app/Contents/jbr',
+      '/Applications/Android Studio Preview.app/Contents/jbr',
+      '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
+      '/Applications/Android Studio Preview 2023.1.app/Contents/jbr'
+    ]
+    for (const p of jbrCandidates) {
+      const javaBin = path.join(p, 'bin', 'java')
+      if (existsSync(javaBin)) {
+        try {
+          const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString()
+          if (/\b17\b/.test(v) || /17\./.test(v)) return p
+        } catch {}
+      }
+    }
+
+    // macOS /usr/libexec/java_home
+    try {
+      const out = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
+      if (out) return out
+    } catch {}
+
+    // macOS common JDK locations
+    try {
+      const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean)
+      for (const h of homes) {
+        if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17')) {
+          const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`
+          return candidate
+        }
+      }
+    } catch {}
+
+    // Linux locations
+    const linuxCandidates = [
+      '/usr/lib/jvm/java-17-openjdk-amd64',
+      '/usr/lib/jvm/java-17-openjdk',
+      '/usr/lib/jvm/zulu17',
+      '/usr/lib/jvm/temurin-17-jdk'
+    ]
+    for (const p of linuxCandidates) {
+      try { if (existsSync(p)) return p } catch {}
+    }
+  } catch (e) {}
+  return undefined
+}
 
 // Helper to construct ADB args with optional device ID
 function getAdbArgs(args: string[], deviceId?: string): string[] {
@@ -35,12 +103,21 @@ export function execAdb(args: string[], deviceId?: string, options: any = {}): P
       })
     }
 
-    let timeoutMs = customTimeout || 2000;
-    if (!customTimeout) {
-      if (args.includes('logcat')) {
+    let timeoutMs: number;
+    if (typeof customTimeout === 'number' && !isNaN(customTimeout)) {
+      timeoutMs = customTimeout;
+    } else {
+      const envTimeout = parseInt(process.env.MCP_ADB_TIMEOUT || process.env.ADB_TIMEOUT || '', 10);
+      if (!isNaN(envTimeout) && envTimeout > 0) {
+        timeoutMs = envTimeout;
+      } else {
+        if (args.includes('logcat')) {
           timeoutMs = 10000;
-      } else if (args.includes('uiautomator') && args.includes('dump')) {
+        } else if (args.includes('uiautomator') && args.includes('dump')) {
           timeoutMs = 20000; // UI dump can be slow
+        } else {
+          timeoutMs = 120000; // default 2 minutes for installs and slow commands
+        }
       }
     }
 
@@ -79,16 +156,324 @@ export function getDeviceInfo(deviceId: string, metadata: Partial<DeviceInfo> =
 
 export async function getAndroidDeviceMetadata(appId: string, deviceId?: string): Promise<DeviceInfo> {
   try {
+    // If no deviceId provided, try to auto-detect a single connected device
+    let resolvedDeviceId = deviceId;
+    if (!resolvedDeviceId) {
+      try {
+        const devicesOutput = await execAdb(['devices']);
+        // Parse lines like: "<serial>\tdevice"
+        const lines = devicesOutput.split('\n').map(l => l.trim()).filter(Boolean);
+        const deviceLines = lines.slice(1) // skip header
+          .map(l => l.split('\t'))
+          .filter(parts => parts.length >= 2 && parts[1] === 'device')
+          .map(parts => parts[0]);
+        if (deviceLines.length === 1) {
+          resolvedDeviceId = deviceLines[0];
+        }
+      } catch (e) {
+        // ignore and continue without resolvedDeviceId
+      }
+    }
+
     // Run these in parallel to avoid sequential timeouts
     const [osVersion, model, simOutput] = await Promise.all([
-      execAdb(['shell', 'getprop', 'ro.build.version.release'], deviceId).catch(() => ''),
-      execAdb(['shell', 'getprop', 'ro.product.model'], deviceId).catch(() => ''),
-      execAdb(['shell', 'getprop', 'ro.kernel.qemu'], deviceId).catch(() => '0')
+      execAdb(['shell', 'getprop', 'ro.build.version.release'], resolvedDeviceId).catch(() => ''),
+      execAdb(['shell', 'getprop', 'ro.product.model'], resolvedDeviceId).catch(() => ''),
+      execAdb(['shell', 'getprop', 'ro.kernel.qemu'], resolvedDeviceId).catch(() => '0')
     ])
     
     const simulator = simOutput === '1'
-    return { platform: 'android', id: deviceId || 'default', osVersion, model, simulator }
+    return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator }
   } catch (e) {
     return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false }
   }
 }
+
+export async function listAndroidDevices(appId?: string): Promise<DeviceInfo[]> {
+  try {
+    const devicesOutput = await execAdb(['devices', '-l'])
+    const lines = devicesOutput.split('\n').map(l => l.trim()).filter(Boolean)
+    // Skip header if present (some adb versions include 'List of devices attached')
+    const deviceLines = lines.filter(l => !l.startsWith('List of devices')).map(l => l)
+    const serials = deviceLines.map(line => line.split(/\s+/)[0]).filter(Boolean)
+
+    const infos = await Promise.all(serials.map(async (serial) => {
+      try {
+        const [osVersion, model, simOutput] = await Promise.all([
+          execAdb(['shell', 'getprop', 'ro.build.version.release'], serial).catch(() => ''),
+          execAdb(['shell', 'getprop', 'ro.product.model'], serial).catch(() => ''),
+          execAdb(['shell', 'getprop', 'ro.kernel.qemu'], serial).catch(() => '0')
+        ])
+        const simulator = simOutput === '1'
+        let appInstalled = false
+        if (appId) {
+          try {
+            const pm = await execAdb(['shell', 'pm', 'path', appId], serial)
+            appInstalled = !!(pm && pm.includes('package:'))
+          } catch {
+            appInstalled = false
+          }
+        }
+        return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled } as DeviceInfo & { appInstalled?: boolean }
+      } catch {
+        return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean }
+      }
+    }))
+
+    return infos
+  } catch (e) {
+    return []
+  }
+}
+
+// Log stream management (one stream per session)
+
+const activeLogStreams: Map<string, { proc: { kill: () => void } | ReturnType<typeof import('child_process').spawn>, file: string }> = new Map()
+
+// Test helper to register a pre-existing NDJSON file as the active stream for a session (used by unit tests)
+export function _setActiveLogStream(sessionId: string, file: string) {
+  activeLogStreams.set(sessionId, { proc: { kill: () => {} }, file })
+}
+
+export function _clearActiveLogStream(sessionId: string) {
+  activeLogStreams.delete(sessionId)
+}
+
+// Robust log line parser supporting multiple logcat formats
+export function parseLogLine(line: string) {
+  // Collapse internal newlines so multiline stack traces are parseable as a single entry
+  const rawLine = line
+  const normalizedLine = rawLine.replace(/\r?\n/g, ' ')
+  const entry: any = { timestamp: '', level: '', tag: '', message: rawLine, _iso: null, crash: false }
+
+  const nowYear = new Date().getFullYear()
+
+  const tryIso = (ts: string) => {
+    if (!ts) return null
+    // If it's already ISO
+    if (/^\d{4}-\d{2}-\d{2}T/.test(ts)) return ts
+    // If format MM-DD HH:MM:SS(.sss)
+    const m = ts.match(/^(\d{2})-(\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/)
+    if (m) {
+      const month = m[1]
+      const day = m[2]
+      const time = m[3]
+      const candidate = `${nowYear}-${month}-${day}T${time}`
+      const d = new Date(candidate)
+      if (!isNaN(d.getTime())) return d.toISOString()
+    }
+    // If format YYYY-MM-DD HH:MM:SS(.sss)
+    const m2 = ts.match(/^(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/)
+    if (m2) {
+      const candidate = `${m2[1]}T${m2[2]}`
+      const d = new Date(candidate)
+      if (!isNaN(d.getTime())) return d.toISOString()
+    }
+    return null
+  }
+
+  // Patterns to try (ordered)
+  const patterns: Array<{re: RegExp, groups: string[]}> = [
+    // MM-DD HH:MM:SS.mmm PID TID LEVEL/Tag: msg
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts','pid','tid','level','tag','msg'] },
+    // MM-DD HH:MM:SS.mmm PID TID LEVEL Tag: msg  (space between level and tag)
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts','pid','tid','level','tag','msg'] },
+    // YYYY-MM-DD full date with PID TID LEVEL/Tag
+    { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts','pid','tid','level','tag','msg'] },
+    // YYYY-MM-DD with space separation
+    { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts','pid','tid','level','tag','msg'] },
+    // MM-DD PID LEVEL/Tag: msg
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts','pid','level','tag','msg'] },
+    // MM-DD PID LEVEL Tag: msg (space)
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts','pid','level','tag','msg'] },
+    // Short form LEVEL/Tag: msg
+    { re: /^([VDIWE])\/([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level','tag','msg'] },
+    // Short form LEVEL Tag: msg
+    { re: /^([VDIWE])\s+([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level','tag','msg'] },
+  ]
+
+  for (const p of patterns) {
+    const m = normalizedLine.match(p.re)
+    if (m) {
+      const g = p.groups
+      const vals: any = {}
+      for (let i=0;i<g.length;i++) vals[g[i]] = m[i+1]
+      const ts = vals.ts
+      if (ts) {
+        const iso = tryIso(ts)
+        if (iso) {
+          entry.timestamp = ts
+          entry._iso = iso
+        } else {
+          entry.timestamp = ts
+        }
+      }
+      if (vals.level) entry.level = vals.level
+      if (vals.tag) entry.tag = vals.tag.trim()
+      entry.message = vals.msg || entry.message
+      // Crash heuristics
+      const msg = (entry.message || '').toString()
+      const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg)
+      if (crash) {
+        entry.crash = true
+        const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+        if (exMatch) entry.exception = exMatch[1]
+      }
+      return entry
+    }
+  }
+
+  // No pattern matched: attempt to extract level/tag like '... E/Tag: msg'
+  const alt = normalizedLine.match(/([VDIWE])\/([^:]+):\s*(.*)$/)
+  if (alt) {
+    entry.level = alt[1]
+    entry.tag = alt[2].trim()
+    entry.message = alt[3]
+    const msg = entry.message
+    const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg)
+    if (crash) {
+      entry.crash = true
+      const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+      if (exMatch) entry.exception = exMatch[1]
+    }
+  }
+
+  return entry
+}
+
+export async function startAndroidLogStream(packageName: string, level: 'error' | 'warn' | 'info' | 'debug' = 'error', deviceId?: string, sessionId: string = 'default'): Promise<{ success: boolean; stream_started?: boolean; error?: string }> {
+  try {
+    // Determine PID
+    const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '')
+    const pid = (pidOutput || '').trim()
+    if (!pid) {
+      return { success: false, error: 'app_not_running' }
+    }
+
+    // Map level to logcat filter
+    const levelMap: Record<string, string> = { error: '*:E', warn: '*:W', info: '*:I', debug: '*:D' }
+    const filter = levelMap[level] || levelMap['error']
+
+    // Prevent multiple streams per session
+    if (activeLogStreams.has(sessionId)) {
+      // stop existing
+      try { activeLogStreams.get(sessionId)!.proc.kill() } catch(e) {}
+      activeLogStreams.delete(sessionId)
+    }
+
+    // Start logcat process
+    const args = ['logcat', `--pid=${pid}`, filter]
+    const proc = spawn(ADB, args)
+
+    // Prepare output file
+    const tmpDir = process.env.TMPDIR || '/tmp'
+    const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`)
+    const stream = createWriteStream(file, { flags: 'a' })
+
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString()
+      const lines = text.split(/\r?\n/).filter(Boolean)
+      for (const l of lines) {
+        const entry = parseLogLine(l)
+        stream.write(JSON.stringify(entry) + '\n')
+      }
+    })
+
+    proc.stderr.on('data', (chunk) => {
+      // write stderr lines as message with level 'E'
+      const text = chunk.toString()
+      const lines = text.split(/\r?\n/).filter(Boolean)
+      for (const l of lines) {
+        const entry = { timestamp: '', level: 'E', tag: 'adb', message: l }
+        stream.write(JSON.stringify(entry) + '\n')
+      }
+    })
+
+    proc.on('close', (code) => {
+      stream.end()
+      activeLogStreams.delete(sessionId)
+    })
+
+    activeLogStreams.set(sessionId, { proc, file })
+
+    return { success: true, stream_started: true }
+  } catch (err) {
+    return { success: false, error: 'log_stream_start_failed' }
+  }
+}
+
+export async function stopAndroidLogStream(sessionId: string = 'default'): Promise<{ success: boolean }> {
+  const entry = activeLogStreams.get(sessionId)
+  if (!entry) return { success: true }
+  try {
+    entry.proc.kill()
+  } catch (e) {}
+  activeLogStreams.delete(sessionId)
+  return { success: true }
+}
+
+export async function readLogStreamLines(sessionId: string = 'default', limit: number = 100, since?: string): Promise<{ entries: any[], crash_summary?: { crash_detected: boolean, exception?: string, sample?: string } }> {
+  const entry = activeLogStreams.get(sessionId)
+  if (!entry) return { entries: [] }
+  try {
+    const data = await fsPromises.readFile(entry.file, 'utf8').catch(() => '')
+    if (!data) return { entries: [], crash_summary: { crash_detected: false } }
+    const lines = data.split(/\r?\n/).filter(Boolean)
+
+    // Parse NDJSON lines into objects. Prefer fields written by parseLogLine. For backward compatibility, if _iso or crash are missing, enrich minimally here (avoid duplicating full parse logic).
+    const parsed = lines.map(l => {
+      try {
+        const obj: any = JSON.parse(l)
+        // Ensure _iso: if missing, try to derive using Date()
+        if (typeof obj._iso === 'undefined') {
+          let iso: string | null = null
+          if (obj.timestamp) {
+            const d = new Date(obj.timestamp)
+            if (!isNaN(d.getTime())) iso = d.toISOString()
+          }
+          obj._iso = iso
+        }
+        // Ensure crash flag: if missing, run minimal heuristic
+        if (typeof obj.crash === 'undefined') {
+          const msg = (obj.message || '').toString()
+          const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+          if (/FATAL EXCEPTION/i.test(msg) || exMatch) {
+            obj.crash = true
+            if (exMatch) obj.exception = exMatch[1]
+          } else {
+            obj.crash = false
+          }
+        }
+        return obj
+      } catch {
+        return { message: l, _iso: null, crash: false }
+      }
+    })
+
+    // Filter by since if provided (accept ISO or epoch ms)
+    let filtered = parsed
+    if (since) {
+      let sinceMs: number | null = null
+      // If numeric string
+      if (/^\d+$/.test(since)) sinceMs = Number(since)
+      else {
+        const sDate = new Date(since)
+        if (!isNaN(sDate.getTime())) sinceMs = sDate.getTime()
+      }
+      if (sinceMs !== null) {
+        filtered = parsed.filter(p => p._iso && (new Date(p._iso).getTime() >= sinceMs))
+      }
+    }
+
+    // Return the last `limit` entries (most recent)
+    const entries = filtered.slice(-Math.max(0, limit))
+
+    // Crash summary
+    const crashEntry = entries.find(e => e.crash)
+    const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false }
+
+    return { entries, crash_summary }
+  } catch (e) {
+    return { entries: [], crash_summary: { crash_detected: false } }
+  }
+}

package/src/ios/interact.ts

@@ -3,6 +3,8 @@ import { spawn } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, WaitForElementResponse, TapResponse } from "../types.js"
 import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB } from "./utils.js"
 import { iOSObserve } from "./observe.js"
+import path from "path"
+import { existsSync } from "fs"
 
 export class iOSInteract {
   private observe = new iOSObserve();
@@ -81,6 +83,106 @@ export class iOSInteract {
     }
   }
 
+  async installApp(appPath: string, deviceId: string = "booted"): Promise<import("../types.js").InstallAppResponse> {
+    const device = await getIOSDeviceMetadata(deviceId)
+
+    // Helper to find .app bundles under a directory
+    async function findAppBundle(dir: string): Promise<string | undefined> {
+      const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => [])
+      for (const e of entries) {
+        const full = path.join(dir, e.name)
+        if (e.isDirectory()) {
+          if (full.endsWith('.app')) return full
+          const found = await findAppBundle(full)
+          if (found) return found
+        }
+      }
+      return undefined
+    }
+
+    try {
+      let toInstall = appPath
+
+      const stat = await fs.stat(appPath).catch(() => null)
+      if (stat && stat.isDirectory()) {
+        // If directory already contains a .app, use it
+        const found = await findAppBundle(appPath)
+        if (found) {
+          toInstall = found
+        } else {
+          // Attempt to locate an Xcode project and build for simulator
+          const files = await fs.readdir(appPath).catch(() => [])
+          // Prefer workspace when present (CocoaPods / multi-project setups)
+          const workspace = files.find(f => f.endsWith('.xcworkspace'))
+          const proj = files.find(f => f.endsWith('.xcodeproj'))
+          if (!workspace && !proj) throw new Error('No .app bundle, .xcworkspace or .xcodeproj found in directory')
+
+          let buildArgs: string[]
+          let scheme: string
+          if (workspace) {
+            const workspacePath = path.join(appPath, workspace)
+            scheme = workspace.replace(/\.xcworkspace$/, '')
+            buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build', '-quiet']
+          } else {
+            const projectPath = path.join(appPath, proj!)
+            scheme = proj!.replace(/\.xcodeproj$/, '')
+            buildArgs = ['-project', projectPath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build', '-quiet']
+          }
+
+          await new Promise<void>((resolve, reject) => {
+            const proc = spawn('xcodebuild', buildArgs, { cwd: appPath })
+            let stderr = ''
+            proc.stderr?.on('data', d => stderr += d.toString())
+            proc.on('close', code => {
+              if (code === 0) resolve()
+              else reject(new Error(stderr || `xcodebuild failed with code ${code}`))
+            })
+            proc.on('error', err => reject(err))
+          })
+
+          const built = await findAppBundle(appPath)
+          if (!built) throw new Error('Could not locate built .app after xcodebuild')
+          toInstall = built
+        }
+      }
+
+      // Try simulator install first
+      try {
+        const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId)
+        return { device, installed: true, output: res.output }
+      } catch (e) {
+        // If simctl fails and idb is available, try idb install for physical devices
+        try {
+          const child = spawn(IDB, ['--version'])
+          const idbExists = await new Promise<boolean>((resolve) => {
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+          });
+          if (idbExists) {
+            // Use idb to install (works for physical devices and simulators)
+            await new Promise<void>((resolve, reject) => {
+              const proc = spawn(IDB, ['install', toInstall, '--udid', device.id]);
+              let stderr = '';
+              proc.stderr.on('data', d => stderr += d.toString());
+              proc.on('close', code => {
+                if (code === 0) resolve();
+                else reject(new Error(stderr || `idb install failed with code ${code}`));
+              });
+              proc.on('error', err => reject(err));
+            });
+            return { device, installed: true }
+          }
+        } catch (inner) {
+          // fallthrough
+        }
+
+        return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
+      }
+    } catch (e) {
+      return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
   async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
     validateBundleId(bundleId)
     const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)