mobile-debug-mcp 0.12.1 → 0.12.3

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,31 +51,77 @@ 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
+      }
+
+      // Prepare build flags and paths (support incremental builds)
       let buildArgs: string[]
+      let chosenScheme: string | null = null
+
+      // Derived data and result bundle (agent-configurable)
+      const derivedDataPath = process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
+      const resultBundlePath = path.join(projectRootDir, 'build', 'xcresults', 'ResultBundle.xcresult')
+      const xcodeJobs = parseInt(process.env.MCP_XCODE_JOBS || '', 10) || 4
+      const forceClean = process.env.MCP_FORCE_CLEAN === '1'
+
+      // ensure result dirs exist
+      await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => {})
+      await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => {})
+
       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']
       }
 
+      // Insert clean if explicitly requested via env
+      if (forceClean) {
+        const idx = buildArgs.indexOf('build')
+        if (idx >= 0) buildArgs.splice(idx, 0, 'clean')
+      }
+
       // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
       if (destinationUDID) {
         buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`)
       }
 
-      // Add result bundle path for diagnostics
+      // Add derived data and result bundle for diagnostics and faster incremental builds
+      buildArgs.push('-derivedDataPath', derivedDataPath)
+      buildArgs.push('-resultBundlePath', resultBundlePath)
+      // parallelisation and jobs
+      buildArgs.push('-parallelizeTargets')
+      buildArgs.push('-jobs', String(xcodeJobs))
+
+      // Prepare results directory for backwards-compatible logs
       const resultsDir = path.join(projectPath, 'build-results')
       // Remove any stale results to avoid xcodebuild complaining about existing result bundles
       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
 
@@ -85,7 +133,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 +167,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 +188,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/ios/utils.ts

@@ -246,6 +246,7 @@ export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise
 
 export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
   return new Promise((resolve) => {
+    // Query all devices and separately query booted devices to mark them
     execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
       if (err || !stdout) return resolve([])
       try {
@@ -254,33 +255,49 @@ export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
         const out: DeviceInfo[] = []
         const checks: Promise<void>[] = []
 
-        for (const runtime in devicesMap) {
-          const devices = devicesMap[runtime]
-          if (Array.isArray(devices)) {
-            for (const device of devices) {
-              const info: any = {
-                platform: 'ios',
-                id: device.udid,
-                osVersion: parseRuntimeName(runtime),
-                model: device.name,
-                simulator: true
+        // Get booted devices set
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+          const bootedSet = new Set<string>()
+          if (!err2 && stdout2) {
+            try {
+              const bdata = JSON.parse(stdout2)
+              const bmap = bdata.devices || {}
+              for (const rt in bmap) {
+                const devs = bmap[rt]
+                if (Array.isArray(devs)) for (const d of devs) bootedSet.add(d.udid)
               }
+            } catch {}
+          }
 
-              if (appId) {
-                // check if installed
-                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                  .then(() => { info.appInstalled = true })
-                  .catch(() => { info.appInstalled = false })
-                  .then(() => { out.push(info) })
-                checks.push(p)
-              } else {
-                out.push(info)
+          for (const runtime in devicesMap) {
+            const devices = devicesMap[runtime]
+            if (Array.isArray(devices)) {
+              for (const device of devices) {
+                const info: any = {
+                  platform: 'ios',
+                  id: device.udid,
+                  osVersion: parseRuntimeName(runtime),
+                  model: device.name,
+                  simulator: true,
+                  booted: bootedSet.has(device.udid)
+                }
+
+                if (appId) {
+                  // check if installed
+                  const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                    .then(() => { info.appInstalled = true })
+                    .catch(() => { info.appInstalled = false })
+                    .then(() => { out.push(info) })
+                  checks.push(p)
+                } else {
+                  out.push(info)
+                }
               }
             }
           }
-        }
 
-        Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out))
+          Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out))
+        })
       } catch {
         resolve([])
       }

package/src/server.ts

@@ -139,6 +139,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         type: "object",
         properties: {
           platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from appPath/project files." },
+          projectType: { type: "string", enum: ["native","kmp","react-native","flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
           appPath: { type: "string", description: "Path to APK, .app, .ipa, or project directory" },
           deviceId: { type: "string", description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected." }
         },
@@ -152,12 +153,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         type: "object",
         properties: {
           platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+          projectType: { type: "string", enum: ["native","kmp","react-native","flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
           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.",
@@ -440,8 +443,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 
     if (name === "install_app") {
-        const { platform, appPath, deviceId } = args as any
-        const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId })
+        const { platform, projectType, appPath, deviceId } = args as any
+        const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId, projectType })
         const response: InstallAppResponse = {
           device: res.device,
           installed: res.installed,
@@ -452,14 +455,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       if (name === "build_app") {
-        const { platform, projectPath, variant } = args as any
-        const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant })
+        const { platform, projectType, projectPath, variant } = args as any
+        const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant, projectType })
         return wrapResponse(res)
       }
 
       if (name === 'build_and_install') {
-        const { platform, projectPath, deviceId, timeout } = args as any
-        const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout })
+        const { platform, projectType, projectPath, deviceId, timeout } = args as any
+        const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType })
         // res: { ndjson, result }
         return {
           content: [

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,12 +1,139 @@
 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 { findApk } from '../android/utils.js'
+import { findAppBundle } from '../ios/utils.js'
+import { execSync } from 'child_process'
 import type { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
+export async function detectProjectPlatform(projectPath: string): Promise<'ios'|'android'|'ambiguous'|'unknown'> {
+  try {
+    const stat = await fs.stat(projectPath).catch(() => null)
+    if (stat && stat.isDirectory()) {
+      const files = (await fs.readdir(projectPath).catch(() => [])) as string[]
+      const hasIos = files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))
+      const hasAndroid = files.includes('gradlew') || files.includes('build.gradle') || files.includes('settings.gradle') || (files.includes('app') && (await fs.stat(path.join(projectPath, 'app')).catch(() => null)))
+      if (hasIos && !hasAndroid) return 'ios'
+      if (hasAndroid && !hasIos) return 'android'
+      if (hasIos && hasAndroid) return 'ambiguous'
+      return 'unknown'
+    } else {
+      const ext = path.extname(projectPath).toLowerCase()
+      if (ext === '.apk') return 'android'
+      if (ext === '.ipa' || ext === '.app') return 'ios'
+      return 'unknown'
+    }
+  } catch {
+    return 'unknown'
+  }
+}
+
 export class ToolsManage {
-  static async buildAppHandler({ platform, projectPath, variant }: { platform?: 'android' | 'ios', projectPath: string, variant?: string }) {
+  static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }: { projectPath: string, gradleTask?: string, maxWorkers?: number, gradleCache?: boolean, forceClean?: boolean }) {
+    const android = new AndroidManage()
+    // prepare gradle options via environment hints
+    if (typeof maxWorkers === 'number') process.env.MCP_GRADLE_WORKERS = String(maxWorkers)
+    if (typeof gradleCache === 'boolean') process.env.MCP_GRADLE_CACHE = gradleCache ? '1' : '0'
+    if (forceClean) process.env.MCP_FORCE_CLEAN_ANDROID = '1'
+    const task = gradleTask || 'assembleDebug'
+    const artifact = await (android as any).build(projectPath, task)
+    return artifact
+  }
+
+  static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }: { projectPath: string, workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, buildJobs?: number, forceClean?: boolean }) {
+    const ios = new iOSManage()
+    // silence unused param lints
+    void _workspace; void _project; void _scheme;
+    if (derivedDataPath) process.env.MCP_DERIVED_DATA = derivedDataPath
+    if (typeof buildJobs === 'number') process.env.MCP_BUILD_JOBS = String(buildJobs)
+    if (forceClean) process.env.MCP_FORCE_CLEAN_IOS = '1'
+    if (destinationUDID) process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID
+    const artifact = await (ios as any).build(projectPath)
+    return artifact
+  }
+
+  static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', buildMode?: 'debug'|'release'|'profile', maxWorkers?: number, forceClean?: boolean }) {
+    // Prefer using flutter CLI when available; otherwise delegate to native subproject builders
+    const flutterCmd = process.env.FLUTTER_PATH || 'flutter'
+    // silence unused params
+    void _maxWorkers; void _forceClean;
+    try {
+      // Check flutter presence without streaming output
+      execSync(`${flutterCmd} --version`, { stdio: 'ignore' })
+
+      if (!platform || platform === 'android') {
+        const mode = buildMode || 'debug'
+        try {
+          const out = execSync(`${flutterCmd} build apk --${mode}`, { cwd: projectPath, encoding: 'utf8' })
+          // Try to find built APK
+          const apk = await findApk(path.join(projectPath))
+          if (apk) return { artifactPath: apk, output: out }
+        } catch (err: any) {
+          const stdout = err && err.stdout ? String(err.stdout) : ''
+          const stderr = err && err.stderr ? String(err.stderr) : ''
+          throw new Error(`flutter build apk failed: ${stderr || stdout || err.message}`)
+        }
+      }
+
+      if (!platform || platform === 'ios') {
+        const mode = buildMode || 'debug'
+        try {
+          const out = execSync(`${flutterCmd} build ios --${mode} --no-codesign`, { cwd: projectPath, encoding: 'utf8' })
+          const app = await findAppBundle(path.join(projectPath))
+          if (app) return { artifactPath: app, output: out }
+        } catch (err: any) {
+          const stdout = err && err.stdout ? String(err.stdout) : ''
+          const stderr = err && err.stderr ? String(err.stderr) : ''
+          throw new Error(`flutter build ios failed: ${stderr || stdout || err.message}`)
+        }
+      }
+    } catch (e) {
+      // If flutter CLI not available or command fails, fall back to native subprojects
+      // Preserve error message for diagnostics if needed
+      void e
+    }
+
+    // Fallback: try native subproject builds
+    if (!platform || platform === 'android') {
+      const androidDir = path.join(projectPath, 'android')
+      const android = new AndroidManage()
+      const artifact = await (android as any).build(androidDir, _forceClean ? 'clean && assembleDebug' : 'assembleDebug')
+      return artifact
+    }
+    if (!platform || platform === 'ios') {
+      const iosDir = path.join(projectPath, 'ios')
+      const ios = new iOSManage()
+      const artifact = await (ios as any).build(iosDir)
+      return artifact
+    }
+
+    return { error: 'Unable to build flutter project' }
+  }
+
+  static async build_react_native({ projectPath, platform, variant, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', variant?: string, maxWorkers?: number, forceClean?: boolean }) {
+    // silence unused params
+    void _maxWorkers; void _forceClean;
+    // React Native typically uses native subprojects. Delegate to Android/iOS builders.
+    if (!platform || platform === 'android') {
+      const androidDir = path.join(projectPath, 'android')
+      const android = new AndroidManage()
+      const artifact = await (android as any).build(androidDir, variant || 'assembleDebug')
+      return artifact
+    }
+    if (!platform || platform === 'ios') {
+      const iosDir = path.join(projectPath, 'ios')
+      // Recommend running `pod install` prior to building in CI; not performed automatically here
+      const ios = new iOSManage()
+      const artifact = await (ios as any).build(iosDir)
+      return artifact
+    }
+    return { error: 'Unable to build react-native project' }
+  }
+
+  static async buildAppHandler({ platform, projectPath, variant, projectType: _projectType }: { platform?: 'android' | 'ios', projectPath: string, variant?: string, projectType?: 'native' | 'kmp' | 'react-native' | 'flutter' }) {
+    void _projectType;
     // delegate to platform-specific build implementations
     const chosen = platform || 'android'
     if (chosen === 'android') {
@@ -20,8 +147,19 @@ export class ToolsManage {
     }
   }
 
-  static async installAppHandler({ platform, appPath, deviceId }: { platform?: 'android' | 'ios', appPath: string, deviceId?: string }): Promise<InstallAppResponse> {
-    let chosenPlatform: 'android' | 'ios' | undefined = platform
+  static async installAppHandler({ platform, appPath, deviceId, projectType }: { platform?: 'android' | 'ios', appPath: string, deviceId?: string, projectType?: 'native' | 'kmp' | 'react-native' | 'flutter' }): Promise<InstallAppResponse> {
+    // Use projectType hint to influence platform detection when explicit platform is not provided
+    let chosenPlatform: 'android'|'ios'|undefined = platform
+    if (!chosenPlatform && projectType) {
+      // Heuristic defaults: KMP, React Native and Flutter commonly target Android by default in CI
+      if (projectType === 'kmp' || projectType === 'react-native' || projectType === 'flutter') {
+        chosenPlatform = 'android'
+        console.debug('[manage] projectType hint -> selecting android by default for', projectType)
+      } else if (projectType === 'native' || projectType === 'ios') {
+        chosenPlatform = 'ios'
+        console.debug('[manage] projectType hint -> selecting ios by default for', projectType)
+      }
+    }
 
     try {
       const stat = await fs.stat(appPath).catch(() => null)
@@ -102,30 +240,41 @@ export class ToolsManage {
     }
   }
 
-  static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout }: { platform?: 'android' | 'ios', projectPath: string, deviceId?: string, timeout?: number }) {
+  static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType }: { platform?: 'android' | 'ios', projectPath: string, deviceId?: string, timeout?: number, projectType?: 'native' | 'kmp' | 'react-native' | 'flutter' }) {
     const events: string[] = []
     const pushEvent = (obj: any) => events.push(JSON.stringify(obj))
     const effectiveTimeout = timeout ?? 180000 // reserved for future streaming/timeouts
     void effectiveTimeout
 
-    // determine platform if not provided by inspecting path
+    // determine platform if not provided by inspecting path or projectType hint
     let chosenPlatform = platform
     try {
-      const stat = await fs.stat(projectPath).catch(() => null)
       if (!chosenPlatform) {
-        if (stat && stat.isDirectory()) {
-          const files = (await fs.readdir(projectPath).catch(() => [])) as string[]
-          if (files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))) chosenPlatform = 'ios'
-          else chosenPlatform = 'android'
+        // If autodetect is disabled, require explicit platform or projectType
+        if (process.env.MCP_DISABLE_AUTODETECT === '1') {
+          pushEvent({ type: 'build', status: 'failed', error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType' })
+          return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType (ios|android).' } }
+        }
+        // If caller indicated KMP, prefer android by default (most KMP modul8 setups target Android)
+        if (projectType === 'kmp') {
+          chosenPlatform = 'android'
+          pushEvent({ type: 'build', status: 'info', message: 'projectType=kmp -> selecting android platform by default' })
         } else {
-          const ext = path.extname(projectPath).toLowerCase()
-          if (ext === '.apk') chosenPlatform = 'android'
-          else if (ext === '.ipa' || ext === '.app') chosenPlatform = 'ios'
-          else chosenPlatform = 'android'
+          const det = await detectProjectPlatform(projectPath)
+          if (det === 'ios' || det === 'android') {
+            chosenPlatform = det
+          } else if (det === 'ambiguous') {
+            pushEvent({ type: 'build', status: 'failed', error: 'Ambiguous project (contains both iOS and Android). Please provide platform: "ios" or "android".' })
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Ambiguous project - please provide explicit platform parameter (ios|android).' } }
+          } else {
+            // Unknown project type - do not guess. Request explicit platform.
+            pushEvent({ type: 'build', status: 'failed', error: 'Unknown project type - unable to autodetect platform. Please provide platform or projectType.' })
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Unknown project type - please provide platform or projectType (ios|android).' } }
+          }
         }
       }
     } catch {
-      chosenPlatform = chosenPlatform || 'android'
+      // detection failed; avoid guessing a platform
     }
 
     pushEvent({ type: 'build', status: 'started', platform: chosenPlatform })

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,24 @@ 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
+    // Prefer booted iOS simulators if present
+    if (platform === 'ios') {
+      const booted = candidates.filter((d: any) => !!d.booted)
+      if (booted.length === 1) return booted[0]
+      if (booted.length > 1) return booted[0] // if multiple booted, pick the first
+    }
+
     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/test/device/manage/run-install-kmp.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { ToolsManage } from '../../../dist/tools/manage.js'
+import path from 'path'
+
+async function main() {
+  // Prefer a repo-local sample modul8 project if present, otherwise allow overriding via KMP_PROJECT env var
+  const defaultRelative = path.join(process.cwd(), '..', '..', '..', '..', 'test-fixtures', 'modul8')
+  const project = process.env.KMP_PROJECT || defaultRelative
+  console.log('Running KMP build+install for project', project)
+  // Use projectType=kmp and let handler pick android by default for KMP
+  // Request iOS explicitly for this run to test iOS build path
+  const res = await ToolsManage.buildAndInstallHandler({ platform: 'ios', projectPath: project, projectType: 'kmp', timeout: 600000, deviceId: undefined })
+  console.log(JSON.stringify(res, null, 2))
+  if (res.result && res.result.success) process.exit(0)
+  process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/test/unit/index.ts

@@ -7,5 +7,7 @@ import './manage/install.test.ts'
 import './manage/build.test.ts'
 import './manage/build_and_install.test.ts'
 import './manage/diagnostics.test.ts'
+import './manage/detection.test.ts'
+import './manage/mcp_disable_autodetect.test.ts'
 
 console.log('Unit tests loaded.')