mobile-debug-mcp 0.34.0 → 0.36.0

package/src/interact/waits/ui-wait-state.ts

@@ -0,0 +1,55 @@
+import { systemClock, type Clock } from '../../runtime/clock.js'
+import type { ActionTargetResolved } from '../../types.js'
+import type { UiSelector } from '../../contracts/selector.js'
+import type { UiTree, ObserveUI } from '../observation.js'
+import type { UiElement } from '../model.js'
+import type { UICondition } from './ui-wait-condition.js'
+import { currentReadinessWait } from '../../observe/readiness.js'
+
+export interface UIWaitInput {
+  selector?: UiSelector; condition?: UICondition; timeout_ms?: number; poll_interval_ms?: number
+  match?: { index?: number }; retry?: { max_attempts?: number; backoff_ms?: number }
+  platform?: 'android' | 'ios'; deviceId?: string; singleObservation?: boolean; singleAttempt?: boolean
+  rejectAmbiguous?: boolean; resolveTapTarget?: boolean
+}
+export interface UIWaitDependencies {
+  clock?: Clock
+  observe: ObserveUI
+  resolve(platform: 'android' | 'ios', deviceId: string | undefined, element: UiElement, index: number): ActionTargetResolved
+}
+export interface UIWaitResult {
+  status: string; error?: { code: string; message?: string }; matched?: number; element?: ActionTargetResolved | null; _tree?: UiTree
+  metrics?: { latency_ms: number; poll_count: number; attempts: number }
+  requested?: { selector: UiSelector; condition: UICondition; match: { index: number } | null }
+  observed?: { matched_count: number; condition_satisfied: boolean; selected_index: number | null; last_matched_element: ActionTargetResolved | null }
+}
+export function createUIWait(input: UIWaitInput, clock: Clock = systemClock) {
+  const tracker = currentReadinessWait(), start = clock.now()
+  const requestedIndex = typeof input.match?.index === 'number' ? input.match.index : null
+  const args = { condition: 'exists' as UICondition, timeout_ms: 60000, poll_interval_ms: 300,
+    retry: { max_attempts: 1, backoff_ms: 0 }, singleObservation: false, singleAttempt: false,
+    rejectAmbiguous: false, resolveTapTarget: false, ...input }
+  // Explicit undefined values have the same defaults as destructured handler parameters.
+  if (args.condition === undefined) args.condition = 'exists'
+  if (args.timeout_ms === undefined) args.timeout_ms = 60000
+  if (args.poll_interval_ms === undefined) args.poll_interval_ms = 300
+  if (args.retry === undefined) args.retry = { max_attempts: 1, backoff_ms: 0 }
+  const requested = { selector: args.selector ?? {}, condition: args.condition, match: requestedIndex === null ? null : { index: requestedIndex } }
+  return { clock, args, requestedIndex, requested, tracker, start, attempts: 0, polls: 0,
+    count: 0, element: null as ActionTargetResolved | null, met: false, stable: 0 }
+}
+export type UIWaitState = ReturnType<typeof createUIWait>
+export function waitObserved(s: UIWaitState, condition = s.met) {
+  return { matched_count: s.count, condition_satisfied: condition, selected_index: s.element?.index ?? null, last_matched_element: s.element }
+}
+export function waitFailure(s: UIWaitState, code: string, message: string, observed = waitObserved(s, false)): UIWaitResult {
+  return { status: 'timeout', error: { code, message }, metrics: { latency_ms: s.clock.now() - s.start, poll_count: s.polls, attempts: s.attempts }, requested: s.requested, observed }
+}
+export function validateUIWait(s: UIWaitState) {
+  const { selector, condition, platform } = s.args
+  const valid = [selector?.text, selector?.resource_id, selector?.accessibility_id].some(value => typeof value === 'string' && value.trim().length > 0)
+  if (!valid) return waitFailure(s, 'INVALID_SELECTOR', 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id')
+  if (!['exists', 'not_exists', 'visible', 'clickable'].includes(condition)) return waitFailure(s, 'INVALID_CONDITION', `Unsupported condition: ${condition}`)
+  if (platform && !['android', 'ios'].includes(platform)) return waitFailure(s, 'PLATFORM_NOT_SUPPORTED', `Unsupported platform: ${platform}`)
+  return null
+}

package/src/interact/waits/ui-wait.ts

@@ -0,0 +1,84 @@
+import { systemClock } from '../../runtime/clock.js'
+import type { UiTree } from '../observation.js'
+import { remainingBudget } from '../../utils/operation-budget.js'
+import { checkDebuggerGuard } from '../../debugger/guard.js'
+import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js'
+import { readinessDelay } from '../../observe/readiness-service.js'
+import { matchingElements, evaluateCondition } from './ui-wait-condition.js'
+import { createUIWait, validateUIWait, waitObserved, waitFailure,
+  type UIWaitInput, type UIWaitDependencies, type UIWaitState, type UIWaitResult } from './ui-wait-state.js'
+
+async function delay(s: UIWaitState, ms: number) {
+  await (s.tracker && s.clock === systemClock ? readinessDelay(ms) : s.clock.sleep(ms))
+}
+function acceptObservation(s: UIWaitState, tree: UiTree, now: number): UIWaitResult | null {
+  const age = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null
+  if (!(s.met && (age === null || age <= 500))) { s.stable = 0; return null }
+  s.stable++
+  if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && s.tracker.summary.state !== 'settled')) return null
+  return { status: 'success', ...(s.args.singleObservation ? { _tree: tree } : {}), matched: s.count,
+    element: s.element, metrics: { latency_ms: now - s.start, poll_count: s.polls, attempts: s.attempts }, requested: s.requested, observed: waitObserved(s, true) }
+}
+function inspectObservation(s: UIWaitState, tree: UiTree, deps: UIWaitDependencies): UIWaitResult | null {
+  const a = s.args, elements = tree && Array.isArray(tree.elements) ? tree.elements : []
+  const matches = matchingElements(elements, a.selector!)
+  if (a.rejectAmbiguous && matches.length > 1 && a.match?.index === undefined) return { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } }
+  const index = typeof a.match?.index === 'number' ? a.match.index : undefined
+  const condition = evaluateCondition(elements, matches, a.condition, index, a.resolveTapTarget)
+  const platform = tree?.device?.platform === 'ios' ? 'ios' : a.platform || 'android'
+  const deviceId = tree?.device?.id || a.deviceId
+  s.count = matches.length; s.met = condition.met
+  s.element = condition.element ? deps.resolve(platform, deviceId, condition.element.el, condition.element.idx) : null
+  return acceptObservation(s, tree, s.clock.now())
+}
+function pollError(s: UIWaitState, error: unknown) {
+  checkDebuggerGuard()
+  if (error instanceof Error && error.message === 'ACTION_TIMEOUT') throw error
+  if (s.tracker && !String(error).includes('READINESS_')) s.tracker.unavailable()
+  if (s.tracker && isDeviceUnavailable(error)) throw error
+  if (!s.tracker) console.warn('waitForUI: poll error (non-fatal):', error instanceof Error ? error.message : String(error))
+}
+async function poll(s: UIWaitState, deps: UIWaitDependencies): Promise<UIWaitResult | null> {
+  remainingBudget(); s.polls++
+  try {
+    const started = s.clock.now(), a = s.args
+    const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId })
+    observeReadinessWait(tree, started)
+    if (a.resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error))) throw new Error('ACTION_TIMEOUT')
+    return inspectObservation(s, tree, deps)
+  } catch (error) { pollError(s, error) }
+  return null
+}
+async function runAttempts(s: UIWaitState, deps: UIWaitDependencies): Promise<UIWaitResult | undefined> {
+  const a = s.args
+  const interval = Math.max(50, Math.min(a.poll_interval_ms || 300, 2000))
+  const maximum = a.retry && a.retry.max_attempts ? Math.max(1, a.retry.max_attempts) : 1
+  const backoff = a.retry && a.retry.backoff_ms ? Math.max(0, a.retry.backoff_ms) : 0
+  while (s.attempts < maximum) {
+    s.attempts++
+    const deadline = s.clock.now() + (a.timeout_ms || 0)
+    while (s.clock.now() <= deadline || (a.singleAttempt && s.polls === 0)) {
+      const result = await poll(s, deps)
+      if (result) return result
+      if (a.singleAttempt) break
+      await delay(s, interval || 50)
+    }
+    if (s.attempts < maximum) { if (backoff > 0) await delay(s, backoff); continue }
+    const note = s.requestedIndex !== null && s.count <= s.requestedIndex
+      ? ` requested match.index=${s.requestedIndex} but observed ${s.count} match(es)` : ` observed ${s.count} match(es)`
+    return waitFailure(s, s.tracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', `Condition ${a.condition} not satisfied within timeout;${note}`, waitObserved(s))
+  }
+}
+export async function waitForUI(input: UIWaitInput, deps: UIWaitDependencies) {
+  const state = createUIWait(input, deps.clock)
+  const invalid = validateUIWait(state)
+  if (invalid) return invalid
+  try { return await runAttempts(state, deps) }
+  catch (error) {
+    checkDebuggerGuard()
+    if (!state.tracker && error instanceof Error && error.message === 'ACTION_TIMEOUT') throw error
+    if (state.tracker && isDeviceUnavailable(error)) throw error
+    return waitFailure(state, state.tracker && String(error).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR',
+      state.tracker ? 'Readiness predicate wait did not complete' : error instanceof Error ? error.message : String(error), waitObserved(state, state.tracker ? state.met : false))
+  }
+}

package/src/manage/android.ts

@@ -41,7 +41,7 @@ export class AndroidManage {
         })
         proc.on('error', err => reject(err))
       })
-    
+
       const apk = await findApk(projectPath)
       if (!apk) return { error: 'Could not find APK after build' }
       return { artifactPath: apk }
@@ -56,54 +56,7 @@ export class AndroidManage {
 
     let apkToInstall: string = apkPath
     try {
-        const stat = await fs.stat(apkPath).catch(() => null)
-        if (stat && stat.isDirectory()) {
-          const detectedJavaHome = await detectJavaHome().catch(() => undefined)
-          const env = { ...process.env }
-          if (detectedJavaHome) {
-            if (env.JAVA_HOME !== detectedJavaHome) {
-              env.JAVA_HOME = detectedJavaHome
-            env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
-            console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome)
-          }
-        }
-        try { delete env.SHELL } catch {}
-
-        const gradleArgs = ['assembleDebug']
-        if (detectedJavaHome) {
-          gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
-          gradleArgs.push('--no-daemon')
-          env.GRADLE_JAVA_HOME = detectedJavaHome
-        }
-
-        const wrapperPath = path.join(apkPath, 'gradlew')
-        const useWrapper = existsSync(wrapperPath)
-        const execCmd = useWrapper ? wrapperPath : 'gradle'
-        const spawnOpts: any = { cwd: apkPath, env }
-        if (useWrapper) {
-          await fs.chmod(wrapperPath, 0o755).catch(() => {})
-          // Run wrapper directly to avoid shell splitting of args
-          spawnOpts.shell = false
-        } else {
-          // Execute gradle directly without a shell so paths with spaces are preserved
-          spawnOpts.shell = false
-        }
-
-        const proc = spawn(execCmd, gradleArgs, spawnOpts)
-        let stderr = ''
-        await new Promise<void>((resolve, reject) => {
-          proc.stderr?.on('data', d => stderr += d.toString())
-          proc.on('close', code => {
-            if (code === 0) resolve()
-            else reject(new Error(stderr || `Gradle build failed with code ${code}`))
-          })
-          proc.on('error', err => reject(err))
-        })
-
-        const built = await findApk(apkPath)
-        if (!built) throw new Error('Could not locate built APK after running Gradle')
-        apkToInstall = built
-      }
+      apkToInstall = await prepareInstallApk(apkPath)
 
       try {
         const res = await spawnAdb(['install', '-r', apkToInstall], deviceId)
@@ -138,7 +91,7 @@ export class AndroidManage {
         }
         throw new Error(finalPmRes.stderr || finalPmRes.stdout || 'pm install failed')
       } finally {
-        try { await execAdb(['shell', 'rm', remotePath], deviceId) } catch {}
+        try { await execAdb(['shell', 'rm', remotePath], deviceId) } catch { }
       }
     } catch (e) {
       // gather diagnostics for attempted adb operations
@@ -224,3 +177,56 @@ export class AndroidManage {
     }
   }
 }
+
+async function prepareInstallApk(apkPath: string): Promise<string> {
+  const stat = await fs.stat(apkPath).catch(() => null)
+  if (stat && stat.isDirectory()) {
+    const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+    const env = { ...process.env }
+    if (detectedJavaHome) {
+      if (env.JAVA_HOME !== detectedJavaHome) {
+        env.JAVA_HOME = detectedJavaHome
+        env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
+        console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome)
+      }
+    }
+    try { delete env.SHELL } catch { }
+
+    const gradleArgs = ['assembleDebug']
+    if (detectedJavaHome) {
+      gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
+      gradleArgs.push('--no-daemon')
+      env.GRADLE_JAVA_HOME = detectedJavaHome
+    }
+
+    const wrapperPath = path.join(apkPath, 'gradlew')
+    const useWrapper = existsSync(wrapperPath)
+    const execCmd = useWrapper ? wrapperPath : 'gradle'
+    const spawnOpts: import('node:child_process').SpawnOptions = { cwd: apkPath, env }
+    if (useWrapper) {
+      await fs.chmod(wrapperPath, 0o755).catch(() => { })
+      // Run wrapper directly to avoid shell splitting of args
+      spawnOpts.shell = false
+    } else {
+      // Execute gradle directly without a shell so paths with spaces are preserved
+      spawnOpts.shell = false
+    }
+
+    const proc = spawn(execCmd, gradleArgs, spawnOpts)
+    let stderr = ''
+    await new Promise<void>((resolve, reject) => {
+      proc.stderr?.on('data', d => stderr += d.toString())
+      proc.on('close', code => {
+        if (code === 0) resolve()
+        else reject(new Error(stderr || `Gradle build failed with code ${code}`))
+      })
+      proc.on('error', err => reject(err))
+    })
+
+    const built = await findApk(apkPath)
+    if (!built) throw new Error('Could not locate built APK after running Gradle')
+    return built
+  }
+
+  return apkPath
+}

package/src/manage/index.ts

@@ -1,3 +1,4 @@
+import type { IOSBuildOptions } from './ios.js'
 import { promises as fs } from 'fs'
 import path from 'path'
 import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js'
@@ -11,9 +12,9 @@ import type { InstallAppResponse, StartAppResponse, TerminateAppResponse, Restar
 export { AndroidManage } from './android.js';
 export { iOSManage } from './ios.js';
 
-export async function detectProjectPlatform(projectPath: string): Promise<'ios'|'android'|'ambiguous'|'unknown'> {
+export async function detectProjectPlatform(projectPath: string): Promise<'ios' | 'android' | 'ambiguous' | 'unknown'> {
   // Recursively scan up to a limited depth for platform markers to avoid mis-detection
-  async function scan(dir: string, depth = 3): Promise<{ ios: boolean, android: boolean }>{
+  async function scan(dir: string, depth = 3): Promise<{ ios: boolean, android: boolean }> {
     const res = { ios: false, android: false }
     try {
       const ents = await fs.readdir(dir).catch(() => [])
@@ -28,15 +29,14 @@ export async function detectProjectPlatform(projectPath: string): Promise<'ios'|
         try {
           const full = path.join(dir, e)
           const st = await fs.stat(full).catch(() => null)
-          if (st && st.isDirectory()) {
-            const child = await scan(full, depth - 1)
-            if (child.ios) res.ios = true
-            if (child.android) res.android = true
-            if (res.ios && res.android) return res
-          }
-        } catch {}
+          if (!st || !st.isDirectory()) continue
+          const child = await scan(full, depth - 1)
+          if (child.ios) res.ios = true
+          if (child.android) res.android = true
+          if (res.ios && res.android) return res
+        } catch { }
       }
-    } catch {}
+    } catch { }
     return res
   }
 
@@ -78,7 +78,7 @@ export class ToolsManage {
   static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }: { projectPath: string, gradleTask?: string, maxWorkers?: number, gradleCache?: boolean, forceClean?: boolean }) {
     const android = new AndroidManage()
     const task = gradleTask || 'assembleDebug'
-    return await (android as any).build(projectPath, {
+    return await android.build(projectPath, {
       variant: task,
       env: mergeDefinedEnv({
         MCP_GRADLE_TASK: task,
@@ -92,7 +92,7 @@ export class ToolsManage {
   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()
 
-    const opts: any = {}
+    const opts: IOSBuildOptions = {}
     if (_workspace) opts.workspace = _workspace
     if (_project) opts.project = _project
     if (_scheme) opts.scheme = _scheme
@@ -103,7 +103,7 @@ export class ToolsManage {
     // prefer explicit xcodebuild path from env
     if (process.env.XCODEBUILD_PATH) opts.xcodeCmd = process.env.XCODEBUILD_PATH
 
-    return await (ios as any).build(projectPath, {
+    return await ios.build(projectPath, {
       ...opts,
       env: mergeDefinedEnv({
         MCP_DERIVED_DATA: derivedDataPath,
@@ -115,7 +115,7 @@ export class ToolsManage {
     })
   }
 
-  static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', buildMode?: 'debug'|'release'|'profile', maxWorkers?: number, forceClean?: boolean }) {
+  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
@@ -131,10 +131,8 @@ export class ToolsManage {
           // 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}`)
+        } catch (thrown: unknown) {
+          throw flutterBuildError(thrown, 'apk')
         }
       }
 
@@ -144,10 +142,8 @@ export class ToolsManage {
           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 (thrown: unknown) {
+          throw flutterBuildError(thrown, 'ios')
         }
       }
     } catch (e) {
@@ -156,38 +152,24 @@ export class ToolsManage {
       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' }
+    return buildFlutterNative(projectPath, platform, _forceClean)
   }
 
-  static async build_react_native({ projectPath, platform, variant, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', variant?: string, maxWorkers?: number, forceClean?: boolean }) {
+  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')
+      const artifact = await android.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)
+      const artifact = await ios.build(iosDir)
       return artifact
     }
     return { error: 'Unable to build react-native project' }
@@ -199,11 +181,11 @@ export class ToolsManage {
     const chosen = platform || 'android'
     if (chosen === 'android') {
       const android = new AndroidManage()
-      const artifact = await (android as any).build(projectPath, { variant })
+      const artifact = await android.build(projectPath, { variant })
       return artifact
     } else {
       const ios = new iOSManage()
-      const artifact = await (ios as any).build(projectPath, { variant })
+      const artifact = await ios.build(projectPath, { variant })
       return artifact
     }
   }
@@ -214,7 +196,7 @@ export class ToolsManage {
       throw new Error('Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).')
     }
 
-    const chosenPlatform: 'android'|'ios' = platform
+    const chosenPlatform: 'android' | 'ios' = platform
 
     if (chosenPlatform === 'android') {
       const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
@@ -271,7 +253,7 @@ export class ToolsManage {
 
   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 pushEvent = (obj: unknown) => events.push(JSON.stringify(obj))
     const effectiveTimeout = timeout ?? 180000 // reserved for future streaming/timeouts
     void effectiveTimeout
 
@@ -281,56 +263,19 @@ export class ToolsManage {
       return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).' } }
     }
 
-    // determine platform if not provided by inspecting path or projectType hint
-    let chosenPlatform = platform
-    try {
-      if (!chosenPlatform) {
-        // If caller provided projectType, respect it as a hard override and map to platform
-        if (projectType) {
-          if (projectType === 'kmp' || projectType === 'react-native' || projectType === 'flutter') {
-            chosenPlatform = 'android'
-            pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing android platform` })
-          } else if (projectType === 'native' || projectType === 'ios') {
-            chosenPlatform = 'ios'
-            pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing ios platform` })
-          } else {
-            pushEvent({ type: 'build', status: 'failed', error: `Unknown projectType: ${projectType}` })
-            return { ndjson: events.join('\n') + '\n', result: { success: false, error: `Unknown projectType: ${projectType}` } }
-          }
-        } else {
-          // 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).' } }
-          }
-
-          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 {
-      // detection failed; avoid guessing a platform
-    }
+    // Explicit platform/projectType were required above; no autodetection occurs.
+    const chosenPlatform = platform
 
     pushEvent({ type: 'build', status: 'started', platform: chosenPlatform })
 
-    let buildRes: any
+    let buildRes: { artifactPath?: string; error?: string; output?: string; diagnostics?: unknown }
     try {
-      buildRes = await ToolsManage.buildAppHandler({ platform: chosenPlatform as any, projectPath })
-      if (buildRes && (buildRes as any).error) {
-        pushEvent({ type: 'build', status: 'failed', error: (buildRes as any).error })
-        return { ndjson: events.join('\n') + '\n', result: { success: false, error: (buildRes as any).error } }
+      buildRes = await ToolsManage.buildAppHandler({ platform: chosenPlatform, projectPath })
+      if (buildRes && buildRes.error) {
+        pushEvent({ type: 'build', status: 'failed', error: buildRes.error })
+        return { ndjson: events.join('\n') + '\n', result: { success: false, error: buildRes.error } }
       }
-      pushEvent({ type: 'build', status: 'finished', artifactPath: (buildRes as any).artifactPath })
+      pushEvent({ type: 'build', status: 'finished', artifactPath: buildRes.artifactPath })
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
       pushEvent({ type: 'build', status: 'failed', error: msg })
@@ -338,11 +283,11 @@ export class ToolsManage {
     }
 
     // Install phase
-    const artifact = (buildRes as any).artifactPath || projectPath
+    const artifact = buildRes.artifactPath || projectPath
     pushEvent({ type: 'install', status: 'started', artifactPath: artifact, deviceId })
-    let installRes: any
+    let installRes: InstallAppResponse
     try {
-      installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform as any, appPath: artifact, deviceId, projectType })
+      installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform, appPath: artifact, deviceId, projectType })
       if (installRes && installRes.installed === true) {
         pushEvent({ type: 'install', status: 'finished', artifactPath: artifact, device: installRes.device })
         return { ndjson: events.join('\n') + '\n', result: { success: true, artifactPath: artifact, device: installRes.device, output: installRes.output } }
@@ -358,7 +303,32 @@ export class ToolsManage {
   }
 
   static async listDevicesHandler({ platform, appId }: { platform?: 'android' | 'ios', appId?: string }) {
-    const devices = await listDevices(platform as any, appId)
+    const devices = await listDevices(platform, appId)
     return { devices }
   }
 }
+
+async function buildFlutterNative(projectPath: string, platform?: 'android' | 'ios', _forceClean?: boolean) {
+  // Fallback: try native subproject builds
+  if (!platform || platform === 'android') {
+    const androidDir = path.join(projectPath, 'android')
+    const android = new AndroidManage()
+    const artifact = await android.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.build(iosDir)
+    return artifact
+  }
+
+  return { error: 'Unable to build flutter project' }
+}
+
+function flutterBuildError(thrown: unknown, kind: string): Error {
+  const err = thrown as { stdout?: unknown; stderr?: unknown; message?: string }
+  const stdout = err && err.stdout ? String(err.stdout) : ''
+  const stderr = err && err.stderr ? String(err.stderr) : ''
+  return new Error(`flutter build ${kind} failed: ${stderr || stdout || err.message}`)
+}

package/src/manage/ios/build-types.ts

@@ -0,0 +1,14 @@
+export type BuildEnv = Record<string, string | undefined>
+
+export interface IOSBuildOptions {
+  variant?: string
+  workspace?: string
+  project?: string
+  scheme?: string
+  destinationUDID?: string
+  derivedDataPath?: string
+  buildJobs?: number
+  forceClean?: boolean
+  xcodeCmd?: string
+  env?: BuildEnv
+}