mobile-debug-mcp 0.19.0 → 0.19.1

package/dist/server.js

@@ -7,6 +7,7 @@ import { ToolsInteract } from './interact/index.js';
 import { ToolsObserve } from './observe/index.js';
 import { AndroidManage } from './manage/index.js';
 import { iOSManage } from './manage/index.js';
+import { ensureAdbAvailable } from './utils/android/utils.js';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -15,6 +16,24 @@ const server = new Server({
         tools: {}
     }
 });
+// Startup healthchecks (non-fatal) — verify adb availability and log chosen command
+(async () => {
+    try {
+        const adbCheck = ensureAdbAvailable();
+        if (adbCheck.ok)
+            console.debug('[startup] adb available:', adbCheck.adbCmd, adbCheck.version);
+        else
+            console.warn('[startup] adb not available or failed to run:', adbCheck.adbCmd, adbCheck.error);
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            console.warn('[startup] error during adb healthcheck:', e.message);
+        }
+        else {
+            console.warn('[startup] error during adb healthcheck:', String(e));
+        }
+    }
+})();
 function wrapResponse(data) {
     return {
         content: [{

package/dist/utils/android/utils.js

@@ -2,7 +2,60 @@ import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import { detectJavaHome } from '../java.js';
 import { execCmd } from '../exec.js';
-export function getAdbCmd() { return process.env.ADB_PATH || 'adb'; }
+import { spawnSync } from 'child_process';
+function findInPath(cmd) {
+    try {
+        // prefer command -v for POSIX
+        const res = spawnSync('command', ['-v', cmd], { encoding: 'utf8' });
+        if (res.status === 0 && res.stdout)
+            return res.stdout.trim();
+    }
+    catch (e) {
+        console.debug(`[findInPath] command -v ${cmd} failed: ${String(e)}`);
+    }
+    try {
+        const res = spawnSync('which', [cmd], { encoding: 'utf8' });
+        if (res.status === 0 && res.stdout)
+            return res.stdout.trim();
+    }
+    catch (e) {
+        console.debug(`[findInPath] which ${cmd} failed: ${String(e)}`);
+    }
+    return null;
+}
+export function resolveAdbCmd() {
+    // Priority: explicit env ADB_PATH -> ANDROID_SDK_ROOT/platform-tools/adb -> ANDROID_HOME/platform-tools/adb -> ~/Library/Android/sdk/platform-tools/adb -> PATH discovery -> 'adb'
+    if (process.env.ADB_PATH && process.env.ADB_PATH.trim())
+        return process.env.ADB_PATH;
+    const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME;
+    if (sdkRoot) {
+        const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // common macOS user SDK path
+    const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
+    if (existsSync(homeSdk))
+        return homeSdk;
+    const found = findInPath('adb');
+    if (found)
+        return found;
+    return 'adb';
+}
+export function getAdbCmd() { return resolveAdbCmd(); }
+export function ensureAdbAvailable() {
+    const adb = resolveAdbCmd();
+    try {
+        const res = spawnSync(adb, ['--version'], { encoding: 'utf8' });
+        if (res.status === 0) {
+            return { adbCmd: adb, ok: true, version: (res.stdout || res.stderr || '').trim() };
+        }
+        return { adbCmd: adb, ok: false, error: (res.stderr || res.stdout || '').trim() };
+    }
+    catch (err) {
+        return { adbCmd: adb, ok: false, error: String(err) };
+    }
+}
 /**
  * Prepare Gradle execution options for building an Android project.
  * Returns execCmd (wrapper or gradle), base gradleArgs array, and spawn options including env.
@@ -24,26 +77,67 @@ export async function prepareGradle(projectPath) {
     }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
     const env = Object.assign({}, process.env);
+    // Ensure child processes can find Android platform-tools (adb, etc.) by
+    // prepending the platform-tools directory to PATH for spawned processes.
+    const adbPath = resolveAdbCmd();
+    let platformToolsDir = undefined;
+    try {
+        if (adbPath && adbPath !== 'adb' && existsSync(adbPath)) {
+            platformToolsDir = path.dirname(adbPath);
+        }
+    }
+    catch (e) {
+        console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`);
+    }
+    const pathParts = [];
     if (detectedJavaHome) {
         if (env.JAVA_HOME !== detectedJavaHome) {
             env.JAVA_HOME = detectedJavaHome;
-            env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
         }
+        const javaBin = path.join(detectedJavaHome, 'bin');
+        pathParts.push(javaBin);
         gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
         gradleArgs.push('--no-daemon');
         env.GRADLE_JAVA_HOME = detectedJavaHome;
     }
+    if (platformToolsDir) {
+        // Prepend platform-tools so gradle and child tools find adb without modifying global env
+        if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
+            pathParts.push(platformToolsDir);
+        }
+    }
+    else if (process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME) {
+        const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || '';
+        const candidate = path.join(sdkRoot, 'platform-tools');
+        if (existsSync(candidate) && (!env.PATH || !env.PATH.includes(candidate))) {
+            pathParts.push(candidate);
+        }
+    }
+    else {
+        // also try common user sdk location
+        const homeSdkTools = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools');
+        if (existsSync(homeSdkTools) && (!env.PATH || !env.PATH.includes(homeSdkTools))) {
+            pathParts.push(homeSdkTools);
+        }
+    }
+    if (pathParts.length > 0) {
+        env.PATH = `${pathParts.join(path.delimiter)}${path.delimiter}${env.PATH || ''}`;
+    }
     try {
         delete env.SHELL;
     }
-    catch { }
+    catch (e) {
+        console.debug('[prepareGradle] failed to delete SHELL from env:', String(e));
+    }
     const useWrapper = existsSync(gradlewPath);
     const spawnOpts = { cwd: projectPath, env };
     if (useWrapper) {
         try {
             await fsPromises.chmod(gradlewPath, 0o755);
         }
-        catch { }
+        catch (e) {
+            console.debug('[prepareGradle] chmod failed for gradlew:', String(e));
+        }
         spawnOpts.shell = false;
     }
     else {
@@ -117,8 +211,8 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
                     resolvedDeviceId = deviceLines[0];
                 }
             }
-            catch {
-                // ignore and continue without resolvedDeviceId
+            catch (e) {
+                console.debug('[getAndroidDeviceMetadata] error detecting single device: ' + String(e));
             }
         }
         // Run these in parallel to avoid sequential timeouts
@@ -130,7 +224,8 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
         const simulator = simOutput === '1';
         return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator };
     }
-    catch {
+    catch (e) {
+        console.debug('[getAndroidDeviceMetadata] failed to gather metadata: ' + String(e));
         return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false };
     }
 }
@@ -170,19 +265,22 @@ export async function listAndroidDevices(appId) {
                         const pm = await execAdb(['shell', 'pm', 'path', appId], serial);
                         appInstalled = !!(pm && pm.includes('package:'));
                     }
-                    catch {
+                    catch (e) {
+                        console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`);
                         appInstalled = false;
                     }
                 }
                 return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled };
             }
-            catch {
+            catch (e) {
+                console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`);
                 return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false };
             }
         }));
         return infos;
     }
-    catch {
+    catch (e) {
+        console.debug('[listAndroidDevices] failed to list devices: ' + String(e));
         return [];
     }
 }
@@ -207,8 +305,8 @@ export async function getScreenResolution(deviceId) {
             return { width: parseInt(match[1]), height: parseInt(match[2]) };
         }
     }
-    catch {
-        // ignore
+    catch (e) {
+        console.debug('[getScreenResolution] failed to detect screen resolution: ' + String(e));
     }
     return { width: 0, height: 0 };
 }

package/dist/utils/cli/ios/preflight-ios.js

@@ -48,7 +48,7 @@ function startCompanionIfNeeded(companionPath, udid) {
         return { started: true };
     }
     catch (e) {
-        return { started: false, error: e.message };
+        return { started: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
 async function main() {

package/dist/utils/java.js

@@ -1,76 +1,133 @@
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import path from 'path';
+function isJavaVersionAcceptable(output) {
+    if (!output)
+        return false;
+    const s = String(output);
+    // Accept Java 17 or 21 (common supported LTS for Android builds)
+    if (/\b17\b/.test(s) || /17\./.test(s))
+        return true;
+    if (/\b21\b/.test(s) || /21\./.test(s))
+        return true;
+    return false;
+}
+import { spawnSync } from 'child_process';
+function javaVersionOf(javaBin) {
+    try {
+        const res = spawnSync(javaBin, ['-version'], { encoding: 'utf8' });
+        // Java prints version to stderr traditionally
+        const out = (res.stdout || '') + (res.stderr || '');
+        return out || undefined;
+    }
+    catch (e) {
+        console.debug('[javaVersionOf] java -version failed: ' + String(e));
+        return undefined;
+    }
+}
 export async function detectJavaHome() {
     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('[java.detect] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17');
-            }
-            catch {
-                console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK17');
+        // 1) Honor explicit ANDROID_STUDIO_JDK env (highest priority)
+        const envStudio = process.env.ANDROID_STUDIO_JDK || process.env.ANDROID_STUDIO_JBR;
+        if (envStudio && existsSync(path.join(envStudio, 'bin', 'java'))) {
+            const v = javaVersionOf(path.join(envStudio, 'bin', 'java'));
+            if (isJavaVersionAcceptable(v)) {
+                console.debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio);
+                return envStudio;
             }
+            console.debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
-        // macOS explicit path
-        const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home';
-        if (existsSync(explicit))
-            return explicit;
-        // Android Studio JBR candidates
+        // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
         const jbrCandidates = [
             '/Applications/Android Studio.app/Contents/jbr',
+            '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
             '/Applications/Android Studio Preview.app/Contents/jbr',
+            '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
             '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr'
+            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
         ];
         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;
+                const v = javaVersionOf(javaBin);
+                if (isJavaVersionAcceptable(v)) {
+                    console.debug('[java.detect] Found Android Studio JBR at:', p);
+                    return p;
+                }
+            }
+        }
+        // 3) If JAVA_HOME set, validate it (accept 17 or 21)
+        if (process.env.JAVA_HOME) {
+            try {
+                const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java');
+                const v = javaVersionOf(javaBin);
+                if (isJavaVersionAcceptable(v)) {
+                    console.debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME);
+                    return process.env.JAVA_HOME;
                 }
-                catch { }
+                console.debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search');
+            }
+            catch {
+                console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK');
             }
         }
-        // macOS /usr/libexec/java_home
+        // 4) macOS explicit path for JDK 17
+        const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home';
+        if (existsSync(explicit))
+            return explicit;
+        // 5) macOS /usr/libexec/java_home try supported versions
+        try {
+            const out17 = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+            if (out17)
+                return out17;
+        }
+        catch (e) {
+            console.debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e));
+        }
         try {
-            const out = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
-            if (out)
-                return out;
+            const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+            if (out21)
+                return out21;
         }
-        catch { }
-        // macOS common JDK locations
+        catch (e) {
+            console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
+        }
+        // 6) 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')) {
+                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
                     const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
                     return candidate;
                 }
             }
         }
-        catch { }
-        // Linux locations
+        catch (e) {
+            console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+        }
+        // 7) 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'
+            '/usr/lib/jvm/temurin-17-jdk',
+            '/usr/lib/jvm/temurin-21-jdk',
+            '/usr/lib/jvm/java-21-openjdk-amd64'
         ];
         for (const p of linuxCandidates) {
             try {
                 if (existsSync(p))
                     return p;
             }
-            catch { }
+            catch (e) {
+                console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+            }
         }
     }
-    catch { }
+    catch (e) {
+        console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+    }
     return undefined;
 }

package/docs/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.19.1]
+
+- Fixed Android install issues
+
 ## [0.19.0]
 
 - Added `observe_until` interaction tool: waits for UI, log, screen fingerprint or idle conditions with configurable polling and timeout. Returns rich details on match (element info, log line, new fingerprint).

package/package.json

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

package/src/manage/android.ts

@@ -115,7 +115,7 @@ export class AndroidManage {
     try {
       await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
       return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
       return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }
@@ -127,7 +127,7 @@ export class AndroidManage {
     try {
       await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
       return { device: deviceInfo, appTerminated: true }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId)
       return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }
@@ -149,7 +149,7 @@ export class AndroidManage {
     try {
       const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
       return { device: deviceInfo, dataCleared: output === 'Success' }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId)
       return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }

package/src/manage/ios.ts

@@ -302,7 +302,7 @@ export class iOSManage {
       const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appStarted: !!result.output, launchTimeMs: 1000 }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
@@ -315,7 +315,7 @@ export class iOSManage {
       await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
@@ -351,7 +351,7 @@ export class iOSManage {
       } catch (e) {
         throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`)
       }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
       return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
     }

package/src/server.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import type { SchemaOutput } from "@modelcontextprotocol/sdk/server/zod-compat.js"
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema
@@ -19,6 +20,7 @@ import { ToolsInteract } from './interact/index.js'
 import { ToolsObserve } from './observe/index.js'
 import { AndroidManage } from './manage/index.js'
 import { iOSManage } from './manage/index.js'
+import { ensureAdbAvailable } from './utils/android/utils.js'
 
 
 const server = new Server(
@@ -31,7 +33,22 @@ const server = new Server(
       tools: {}
     }
   }
-)
+);
+
+// Startup healthchecks (non-fatal) — verify adb availability and log chosen command
+(async () => {
+  try {
+    const adbCheck = ensureAdbAvailable()
+    if (adbCheck.ok) console.debug('[startup] adb available:', adbCheck.adbCmd, adbCheck.version)
+    else console.warn('[startup] adb not available or failed to run:', adbCheck.adbCmd, adbCheck.error)
+  } catch (e: unknown) {
+    if (e instanceof Error) {
+      console.warn('[startup] error during adb healthcheck:', e.message)
+    } else {
+      console.warn('[startup] error during adb healthcheck:', String(e))
+    }
+  }
+})()
 
 function wrapResponse<T>(data: T) {
   return {
@@ -487,9 +504,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       }
     }
   ]
-}))
+}));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>) => {
   const { name, arguments: args } = request.params
 
   try {

package/src/utils/android/utils.ts

@@ -3,8 +3,51 @@ import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
 import { detectJavaHome } from '../java.js'
 import { execCmd } from '../exec.js'
+import { spawnSync } from 'child_process'
 
-export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
+function findInPath(cmd: string): string | null {
+  try {
+    // prefer command -v for POSIX
+    const res = spawnSync('command', ['-v', cmd], { encoding: 'utf8' })
+    if (res.status === 0 && res.stdout) return res.stdout.trim()
+  } catch (e: unknown) { console.debug(`[findInPath] command -v ${cmd} failed: ${String(e)}`) }
+  try {
+    const res = spawnSync('which', [cmd], { encoding: 'utf8' })
+    if (res.status === 0 && res.stdout) return res.stdout.trim()
+  } catch (e: unknown) { console.debug(`[findInPath] which ${cmd} failed: ${String(e)}`) }
+  return null
+}
+
+export function resolveAdbCmd(): string {
+  // Priority: explicit env ADB_PATH -> ANDROID_SDK_ROOT/platform-tools/adb -> ANDROID_HOME/platform-tools/adb -> ~/Library/Android/sdk/platform-tools/adb -> PATH discovery -> 'adb'
+  if (process.env.ADB_PATH && process.env.ADB_PATH.trim()) return process.env.ADB_PATH
+  const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME
+  if (sdkRoot) {
+    const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
+    if (existsSync(candidate)) return candidate
+  }
+  // common macOS user SDK path
+  const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
+  if (existsSync(homeSdk)) return homeSdk
+  const found = findInPath('adb')
+  if (found) return found
+  return 'adb'
+}
+
+export function getAdbCmd() { return resolveAdbCmd() }
+
+export function ensureAdbAvailable() {
+  const adb = resolveAdbCmd()
+  try {
+    const res = spawnSync(adb, ['--version'], { encoding: 'utf8' })
+    if (res.status === 0) {
+      return { adbCmd: adb, ok: true, version: (res.stdout || res.stderr || '').trim() }
+    }
+    return { adbCmd: adb, ok: false, error: (res.stderr || res.stdout || '').trim() }
+  } catch (err: unknown) {
+    return { adbCmd: adb, ok: false, error: String(err) }
+  }
+}
 
 /**
  * Prepare Gradle execution options for building an Android project.
@@ -31,22 +74,58 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
 
   const detectedJavaHome = await detectJavaHome().catch(() => undefined)
   const env = Object.assign({}, process.env)
+
+  // Ensure child processes can find Android platform-tools (adb, etc.) by
+  // prepending the platform-tools directory to PATH for spawned processes.
+  const adbPath = resolveAdbCmd()
+  let platformToolsDir: string | undefined = undefined
+  try {
+    if (adbPath && adbPath !== 'adb' && existsSync(adbPath)) {
+      platformToolsDir = path.dirname(adbPath)
+    }
+  } catch (e: unknown) { console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`) }
+
+  const pathParts: string[] = []
   if (detectedJavaHome) {
     if (env.JAVA_HOME !== detectedJavaHome) {
       env.JAVA_HOME = detectedJavaHome
-      env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
     }
+    const javaBin = path.join(detectedJavaHome, 'bin')
+    pathParts.push(javaBin)
     gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
     gradleArgs.push('--no-daemon')
     env.GRADLE_JAVA_HOME = detectedJavaHome
   }
 
-  try { delete env.SHELL } catch {}
+  if (platformToolsDir) {
+    // Prepend platform-tools so gradle and child tools find adb without modifying global env
+    if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
+      pathParts.push(platformToolsDir)
+    }
+  } else if (process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME) {
+    const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || ''
+    const candidate = path.join(sdkRoot, 'platform-tools')
+    if (existsSync(candidate) && (!env.PATH || !env.PATH.includes(candidate))) {
+      pathParts.push(candidate)
+    }
+  } else {
+    // also try common user sdk location
+    const homeSdkTools = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools')
+    if (existsSync(homeSdkTools) && (!env.PATH || !env.PATH.includes(homeSdkTools))) {
+      pathParts.push(homeSdkTools)
+    }
+  }
+
+  if (pathParts.length > 0) {
+    env.PATH = `${pathParts.join(path.delimiter)}${path.delimiter}${env.PATH || ''}`
+  }
+
+  try { delete env.SHELL } catch (e: unknown) { console.debug('[prepareGradle] failed to delete SHELL from env:', String(e)) }
 
   const useWrapper = existsSync(gradlewPath)
   const spawnOpts: any = { cwd: projectPath, env }
   if (useWrapper) {
-    try { await fsPromises.chmod(gradlewPath, 0o755) } catch {}
+    try { await fsPromises.chmod(gradlewPath, 0o755) } catch (e: unknown) { console.debug('[prepareGradle] chmod failed for gradlew:', String(e)) }
     spawnOpts.shell = false
   } else {
     spawnOpts.shell = true
@@ -125,8 +204,7 @@ export async function getAndroidDeviceMetadata(appId: string, deviceId?: string)
         if (deviceLines.length === 1) {
           resolvedDeviceId = deviceLines[0];
         }
-      } catch {
-        // ignore and continue without resolvedDeviceId
+      } catch (e: unknown) { console.debug('[getAndroidDeviceMetadata] error detecting single device: ' + String(e))
       }
     }
 
@@ -139,7 +217,8 @@ export async function getAndroidDeviceMetadata(appId: string, deviceId?: string)
     
     const simulator = simOutput === '1'
     return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator }
-  } catch {
+  } catch (e: unknown) {
+    console.debug('[getAndroidDeviceMetadata] failed to gather metadata: ' + String(e))
     return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false }
   }
 }
@@ -180,20 +259,14 @@ export async function listAndroidDevices(appId?: string): Promise<DeviceInfo[]>
           try {
             const pm = await execAdb(['shell', 'pm', 'path', appId], serial)
             appInstalled = !!(pm && pm.includes('package:'))
-          } catch {
-            appInstalled = false
-          }
+          } catch (e: unknown) { console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`); 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 }
-      }
+      } catch (e: unknown) { console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`); return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean } }
     }))
 
     return infos
-  } catch {
-    return []
-  }
+  } catch (e: unknown) { console.debug('[listAndroidDevices] failed to list devices: ' + String(e)); return [] }
 }
 
 // UI helper utilities shared by observe/interact
@@ -219,9 +292,7 @@ export async function getScreenResolution(deviceId?: string): Promise<{ width: n
     if (match) {
       return { width: parseInt(match[1]), height: parseInt(match[2]) };
     }
-  } catch {
-    // ignore
-  }
+  } catch (e: unknown) { console.debug('[getScreenResolution] failed to detect screen resolution: ' + String(e)) }
   return { width: 0, height: 0 };
 }
 

package/src/utils/cli/ios/preflight-ios.ts

@@ -40,8 +40,8 @@ function startCompanionIfNeeded(companionPath: string | null, udid: string | nul
     const child = spawn(companionPath, ['--udid', udid], { detached: true, stdio: 'ignore' })
     child.unref()
     return { started: true }
-  } catch (e:any) {
-    return { started: false, error: e.message }
+  } catch (e: unknown) {
+    return { started: false, error: e instanceof Error ? e.message : String(e) }
   }
 }
 

package/src/utils/java.ts

@@ -2,68 +2,114 @@ import { execSync } from 'child_process'
 import { existsSync } from 'fs'
 import path from 'path'
 
+function isJavaVersionAcceptable(output?: string | null): boolean {
+  if (!output) return false
+  const s = String(output)
+  // Accept Java 17 or 21 (common supported LTS for Android builds)
+  if (/\b17\b/.test(s) || /17\./.test(s)) return true
+  if (/\b21\b/.test(s) || /21\./.test(s)) return true
+  return false
+}
+
+import { spawnSync } from 'child_process'
+function javaVersionOf(javaBin: string): string | undefined {
+  try {
+    const res = spawnSync(javaBin, ['-version'], { encoding: 'utf8' })
+    // Java prints version to stderr traditionally
+    const out = (res.stdout || '') + (res.stderr || '')
+    return out || undefined
+  } catch (e: unknown) { console.debug('[javaVersionOf] java -version failed: ' + String(e)); return undefined }
+}
+
 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('[java.detect] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17')
-      } catch {
-        console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK17')
+    // 1) Honor explicit ANDROID_STUDIO_JDK env (highest priority)
+    const envStudio = process.env.ANDROID_STUDIO_JDK || process.env.ANDROID_STUDIO_JBR
+    if (envStudio && existsSync(path.join(envStudio, 'bin', 'java'))) {
+      const v = javaVersionOf(path.join(envStudio, 'bin', 'java'))
+      if (isJavaVersionAcceptable(v)) {
+        console.debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio)
+        return envStudio
       }
+      console.debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions')
     }
 
-    // macOS explicit path
-    const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home'
-    if (existsSync(explicit)) return explicit
-
-    // Android Studio JBR candidates
+    // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
     const jbrCandidates = [
       '/Applications/Android Studio.app/Contents/jbr',
+      '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
       '/Applications/Android Studio Preview.app/Contents/jbr',
+      '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
       '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-      '/Applications/Android Studio Preview 2023.1.app/Contents/jbr'
+      '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+      '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+      '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
     ]
     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 {}
+        const v = javaVersionOf(javaBin)
+        if (isJavaVersionAcceptable(v)) {
+          console.debug('[java.detect] Found Android Studio JBR at:', p)
+          return p
+        }
       }
     }
 
-    // macOS /usr/libexec/java_home
+    // 3) If JAVA_HOME set, validate it (accept 17 or 21)
+    if (process.env.JAVA_HOME) {
+      try {
+        const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java')
+        const v = javaVersionOf(javaBin)
+        if (isJavaVersionAcceptable(v)) {
+          console.debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME)
+          return process.env.JAVA_HOME
+        }
+        console.debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search')
+      } catch {
+        console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK')
+      }
+    }
+
+    // 4) macOS explicit path for JDK 17
+    const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home'
+    if (existsSync(explicit)) return explicit
+
+    // 5) macOS /usr/libexec/java_home try supported versions
+    try {
+      const out17 = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
+      if (out17) return out17
+    } catch (e: unknown) { console.debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e)) }
     try {
-      const out = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
-      if (out) return out
-    } catch {}
+      const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
+      if (out21) return out21
+    } catch (e: unknown) { console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e)) }
 
-    // macOS common JDK locations
+    // 6) 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')) {
+        if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
           const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`
           return candidate
         }
       }
-    } catch {}
+    } catch (e: unknown) { console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e)) }
 
-    // Linux locations
+    // 7) 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'
+      '/usr/lib/jvm/temurin-17-jdk',
+      '/usr/lib/jvm/temurin-21-jdk',
+      '/usr/lib/jvm/java-21-openjdk-amd64'
     ]
     for (const p of linuxCandidates) {
-      try { if (existsSync(p)) return p } catch {}
+      try { if (existsSync(p)) return p } catch (e: unknown) { console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`) }
     }
-  } catch {}
+  } catch (e: unknown) {
+    console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e))
+  }
   return undefined
 }

package/test/utils/detect_java.test.ts

@@ -0,0 +1,25 @@
+import fs from 'fs'
+import path from 'path'
+import { detectJavaHome } from '../../src/utils/java.js'
+
+async function run() {
+  // Create a temporary fake JDK that reports Java 17
+  const tmp = fs.mkdtempSync('/tmp/fakejdk-')
+  const bin = path.join(tmp, 'bin')
+  fs.mkdirSync(bin)
+  const javaSh = path.join(bin, 'java')
+  fs.writeFileSync(javaSh, '#!/bin/sh\necho "openjdk version \"17.0.2\"" >&2\nexit 0\n')
+  fs.chmodSync(javaSh, 0o755)
+
+  process.env.ANDROID_STUDIO_JDK = tmp
+
+  const detected = await detectJavaHome()
+  console.log('DETECTED:', detected)
+  if (detected !== tmp) {
+    console.error('TEST FAIL: expected', tmp, 'got', detected)
+    process.exit(2)
+  }
+  console.log('TEST PASS')
+}
+
+run().catch(e => { console.error(e); process.exit(1) })