mobile-debug-mcp 0.19.0 → 0.19.2

package/dist/server.js

@@ -7,6 +7,10 @@ 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';
+import { getIdbCmd, isIDBInstalled } from './utils/ios/utils.js';
+import { getXcrunCmd } from './utils/ios/utils.js';
+import { execSync } from 'child_process';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -15,6 +19,50 @@ 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));
+        }
+    }
+    // Check idb availability (non-fatal)
+    try {
+        const idbInstalled = await isIDBInstalled();
+        const idbCmd = getIdbCmd();
+        if (idbInstalled)
+            console.debug('[startup] idb available:', idbCmd);
+        else
+            console.debug('[startup] idb not available or failed to run:', idbCmd);
+    }
+    catch (e) {
+        console.warn('[startup] error during idb healthcheck:', e instanceof Error ? e.message : String(e));
+    }
+    // Check xcrun availability (non-fatal)
+    try {
+        const xcrun = getXcrunCmd();
+        try {
+            const out = execSync(`${xcrun} --version`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+            console.debug('[startup] xcrun available:', xcrun, out.split('\n')[0]);
+        }
+        catch (err) {
+            console.warn('[startup] xcrun not available or failed to run:', xcrun, err instanceof Error ? err.message : String(err));
+        }
+    }
+    catch (e) {
+        console.warn('[startup] error during xcrun healthcheck:', e instanceof Error ? e.message : 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/ios/utils.js

@@ -75,12 +75,13 @@ export async function isIDBInstalled() {
         execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] });
         return true;
     }
-    catch {
+    catch (e) {
         try {
             execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
             return true;
         }
-        catch {
+        catch (e2) {
+            console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`);
             return false;
         }
     }

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,14 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.19.2]
+- Added healthcheck improvments
+- Added skills 
+
+## [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.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,68 @@
+# MCP Builder skill
+
+name: mcp-builder
+version: 0.1.0
+summary: Reusable procedures for building, validating and installing Android/iOS apps in this repo. Designed for agents to act autonomously with project-specific guidance.
+
+# Purpose
+Provide concise, actionable procedures and schemas that encode the successful sequences used in mobile-debug-mcp: toolchain detection, build orchestration, install fallbacks, diagnostics collection, and verification (lint/tests). Keep core guidance short; link to references for details.
+
+# Activation conditions
+Activate when an agent needs to:
+- build or install an app from this repository
+- diagnose failing CI/dev machine builds
+- run lint/tests and collect reproducible diagnostics
+
+# Surface area (actions)
+- detect-toolchain
+- build-android
+- install-android
+- build-ios
+- install-ios
+- run-lint
+- run-tests
+- collect-diagnostics
+
+# Core guidance (what agent must do)
+1. Prefer project conventions and existing helpers in src/utils and src/manage.
+2. Use detect-toolchain to decide JAVA_HOME/JBR preference and whether adb/idb/xcrun are available.
+3. For Android builds, call prepareGradle() to prepare child PATH and env, then run ./gradlew (wrapper) if present.
+4. For installs, parse adb output defensively (ignore streamed-install noise) and on failure fall back to push+pm path.
+5. For iOS installs, prefer simctl for simulators; if simctl fails check idb and attempt idb install with diagnostics.
+6. On any error, call collect-diagnostics and attach env snapshot, invoked commands, stdout/stderr, and suggested fixes.
+
+# Inputs & outputs (short schemas)
+- detect-toolchain(input: { platform: 'android'|'ios'|'both', preferJBR?: boolean }) -> { tools: [{name, cmd, ok, version, suggestion}] }
+- build-android(input: { projectPath, variant?, clean?, envOverrides? }) -> { success, artifactPath?, logs?, diagnostics? }
+- install-android(input: { appPath, projectPath?, deviceId?, allowBuild? }) -> { installed:boolean, device, output?, diagnostics? }
+- build-ios/install-ios: mirror Android schema but use scheme/workspace/project and resultBundlePath
+- run-lint/run-tests -> { exitCode, stdout, stderr, artifacts[] }
+- collect-diagnostics(input: { reason, platform? }) -> { artifacts: [{ name, contentBase64?, path? }], envSnapshot }
+
+# Failure handling & suggestions
+- Always return structured diagnostics instead of throwing when possible.
+- Provide a short human-friendly suggestion in diagnostics (e.g., "Install Android Platform Tools or set ADB_PATH").
+- Redact sensitive env values (tokens, credentials) when including envSnapshot.
+
+# Progressive disclosure
+- Keep SKILL.md compact (this file). Place heavy references in skills/mcp-builder/references/*.md and instruct agents to load them only when needed.
+
+# References (implement as separate files)
+- references/toolchain-details.md — exact paths/heuristics used for JBR, JAVA_HOME, ANDROID_SDK locations.
+- references/build-flags.md — gradle/xcodebuild flags used, timeouts, and retry rationale.
+- references/diagnostics-schema.md — JSON schema for runResult and collected artifacts.
+
+# Implementation notes for maintainers
+- Implement a thin adapter in src/skills/mcp-builder/index.ts that maps skill actions to existing functions in src/manage and src/utils.
+- Provide unit tests under test/skills/mcp-builder that mock child_process to validate happy/failure paths.
+- Add env toggles: MCP_PREFERS_JBR, MCP_GRADLE_RETRIES, MCP_XCODEBUILD_RETRIES.
+
+# Example agent flow
+1. call detect-toolchain({platform:'android', preferJBR:true})
+2. if ok -> call build-android({projectPath:'/path', variant:'Debug'})
+3. call install-android({appPath:'/path/to.apk', deviceId:'emulator-5554'})
+4. if install fails -> call collect-diagnostics({reason:'install failure', platform:'android'})
+
+# License
+Same as repository (MIT).
+

package/skills/mcp-builder/references/build-flags.md

@@ -0,0 +1,43 @@
+# Build flags and runtime configuration
+
+Purpose: describe the flags, environment variables and spawn-environment handling that agents should use when orchestrating Android and iOS builds for this repo.
+
+Common env variables
+- MCP_GRADLE_RETRIES (default: 1) — number of retry attempts on watchdog kills for Gradle
+- MCP_GRADLE_TIMEOUT_MS (default: 300000) — gradle watch/duration timeout
+- MCP_XCODEBUILD_RETRIES, MCP_XCODEBUILD_TIMEOUT_MS — similar for xcodebuild
+- MCP_PREFERS_JBR — prefer Android Studio JBR for JAVA_HOME
+- MCP_DERIVED_DATA, MCP_XCODE_RESULTBUNDLE_PATH — override DerivedData/result bundle locations
+
+Android (Gradle)
+- Use the Gradle wrapper if present: `./gradlew assemble<Variant>` (e.g., assembleDebug). Prefer wrapper to ensure consistent Gradle version.
+- Prepare spawn env by prepending javaBin and platform-tools dir to PATH and set GRADLE_JAVA_HOME and `-Dorg.gradle.java.home` when necessary.
+- If wrapper exists, ensure `chmod +x ./gradlew` before spawn.
+- Recommended flags:
+  - `--no-daemon` sometimes helpful in CI, but wrap with existing project conventions.
+  - Set `org.gradle.jvmargs` via env or gradle.properties only if needed.
+- Timeouts & watchdog:
+  - Use a watchdog timeout (MCP_GRADLE_TIMEOUT_MS) and retry (MCP_GRADLE_RETRIES) if killed by watchdog. Record stdout/stderr for each attempt.
+
+iOS (xcodebuild)
+- Use `xcodebuild -workspace <ws> -scheme <scheme> -configuration Debug -sdk iphonesimulator build` for simulator builds.
+- Provide `-derivedDataPath` and `-resultBundlePath` to isolate builds and produce diagnostics. Default result bundle path should be unique per run to avoid collisions.
+- Recommended flags: `-parallelizeTargets -jobs <N>` where N is from MCP_XCODE_JOBS or sensible default (4).
+- When a destination UDID is available, always pass `-destination "platform=iOS Simulator,id=<UDID>"` to avoid ambiguous device selection.
+- Timeouts & retries: respect MCP_XCODEBUILD_TIMEOUT_MS and MCP_XCODEBUILD_RETRIES; capture stdout/stderr and save logs under build-results.
+
+Install-time behavior
+- Android: prefer `adb install -r <apk>` for fast installs. If output contains spurious lines (e.g., "Performing Streamed Install" followed by "Success"), parse to extract final status. On failure try `adb push` to `/data/local/tmp` + `pm install -r <remote>` as a fallback collect push/install diagnostics.
+- iOS: prefer `xcrun simctl install <device> <app>` for simulator. On failure attempt idb install if idb exists: `idb install <ipa|app> --udid <udid>` and record its stdout/stderr.
+
+Diagnostics capture
+- Save stdout/stderr, exitCode and environment snapshot for each command. Persist logs under workspace/build-results or a temp dir provided by the caller.
+- For builds, also capture produced artifact paths to return to caller.
+
+Examples
+- Gradle invocation (pseudo):
+  spawnOpts.env.PATH = `${javaBin}:${platformTools}:${process.env.PATH}`
+  spawn('./gradlew', ['assembleDebug'], { cwd: projectRoot, env: spawnOpts.env })
+
+- xcodebuild invocation (pseudo):
+  xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath /tmp/derived -resultBundlePath /tmp/Result-123.xcresult -parallelizeTargets -jobs 4 build

package/skills/mcp-builder/references/diagnostics-schema.md

@@ -0,0 +1,48 @@
+# Diagnostics schema
+
+This document defines the JSON shapes that mcp-builder actions return when collecting diagnostics. Agents and tooling should rely on these keys.
+
+Top-level diagnostic object
+{
+  "error": "short human-friendly message",
+  "runResult": {
+    "command": "/usr/bin/adb",
+    "args": ["install", "app.apk"],
+    "exitCode": 1,
+    "stdout": "...",
+    "stderr": "...",
+    "startTimeMs": 1650000000000,
+    "endTimeMs": 1650000001000,
+    "envSnapshot": { "PATH": "...", "JAVA_HOME": "REDACTED" }
+  },
+  "artifacts": [ { name, path?, contentBase64?, type? } ],
+  "suggestedFixes": ["Install Android Platform Tools", "Set JAVA_HOME to JDK 17"]
+}
+
+Fields
+- error: short message summarising the failure.
+- runResult: information captured from a single command invocation. Use this for programmatic retries or human debugging.
+  - command, args: the executed command
+  - exitCode: numeric exit code, null for killed/unknown
+  - stdout, stderr: captured text
+  - startTimeMs, endTimeMs: epoch ms for duration
+  - envSnapshot: a restricted set of env variables (PATH, JAVA_HOME, ADB_PATH, IDB_PATH, XCRUN_PATH). Any value matching sensitive patterns (e.g., /token|secret|key|passwd/i) must be redacted to "REDACTED".
+- artifacts: array of captured files. Each artifact: { name: string, path?: string, contentBase64?: string, type?: "log"|"archive"|"image" }
+- suggestedFixes: short actionable suggestions for human/operator.
+
+Notes on size and transmission
+- Prefer storing large artifacts on disk and returning paths rather than inlining large base64 blobs. If transmitting, limit base64 inlined artifacts to a configurable max (e.g., 5MB) and prefer compression/archiving.
+
+Example: adb install failure
+{
+  "error": "adb: device not found",
+  "runResult": {
+    "command": "adb",
+    "args": ["devices"],
+    "exitCode": 0,
+    "stdout": "List of devices attached\n\n",
+    "stderr": "",
+    "envSnapshot": { "PATH": "/usr/local/bin:/usr/bin", "JAVA_HOME": null }
+  },
+  "suggestedFixes": ["Connect an Android device or start an emulator", "Ensure adb is on PATH or set ADB_PATH"]
+}

package/skills/mcp-builder/references/toolchain-details.md

@@ -0,0 +1,62 @@
+# Toolchain details
+
+This reference documents the exact heuristics and commands used by the mcp-builder skill to detect and validate the native toolchain (Android & iOS) on contributor machines.
+
+Key environment variables
+- ADB_PATH: explicit path to adb binary
+- ANDROID_SDK_ROOT / ANDROID_HOME: SDK root; platform-tools/adb under these
+- ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK: explicit Android Studio JBR/JDK path
+- JAVA_HOME: system JDK
+- IDB_PATH / MCP_IDB_PATH: idb path for iOS
+- XCRUN_PATH: explicit xcrun path
+- MCP_PREFERS_JBR: boolean to prefer Android Studio JBR when present
+
+Android Java detection precedence
+1. ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK env vars (preferred when MCP_PREFERS_JBR set)
+2. Known Android Studio JBR locations (macOS):
+   - /Applications/Android Studio.app/Contents/jbr/Contents/Home
+   - /Applications/Android Studio Preview.app/Contents/jbr/Contents/Home
+3. Explicit JAVA_HOME (validate via `java -version`)
+4. macOS `/usr/libexec/java_home -v 17` or `-v 21`
+5. Common Linux JDK locations: `/usr/lib/jvm/*temurin*`, `/usr/lib/jvm/*zulu*`
+
+Validation rules
+- Accept only Java 17 or Java 21 for Gradle builds in this project (both tested/known working).
+- Reject GraalVM / Java 23 that causes Gradle jlink errors. If detected, return suggestion: "Prefer an Apple/Temurin/JBR Java 17 or 21. Set ANDROID_STUDIO_JBR or JAVA_HOME to a supported JDK."
+
+ADB resolution precedence
+1. process.env.ADB_PATH (explicit)
+2. ANDROID_SDK_ROOT or ANDROID_HOME -> platform-tools/adb
+3. Common SDK locations (macOS/Linux): $HOME/Library/Android/sdk/platform-tools, /opt/android-sdk/platform-tools
+4. `command -v adb` / `which adb` on PATH
+5. fallback to `adb` (best-effort)
+
+IDB / XCRUN detection (iOS)
+- IDB: check MCP_IDB_PATH -> IDB_PATH -> common locations (/opt/homebrew/bin/idb, /usr/local/bin/idb, $HOME/Library/Python/*/bin/idb). Validate by running `idb --version` or `idb list-targets --json`.
+- XCRUN: check XCRUN_PATH -> run `xcrun --version`.
+
+How to probe (commands)
+- adb: `adb --version` and `adb devices --print` (or `adb devices -l`) to list.
+- java: `java -XshowSettings:properties -version` or `java -version` parse first line.
+- xcrun: `xcrun --version`
+- idb: `idb --version` or `idb list-targets --json`
+
+Output format
+- Each probe returns { name, cmd, ok, version?, suggestion? } so agents can reason programmatically.
+- Include env snapshot (PATH, JAVA_HOME, ADB_PATH, ANDROID_SDK_ROOT, IDB_PATH, XCRUN_PATH) to aid diagnostics.
+
+Notes & rationale
+- Prefer Android Studio JBR (JBR is bundled & known-good) because developer machines often have mismatched system JDKs (e.g., Graal). Allow override via env for CI.
+- For long-running server processes, prepend java/bin and platform-tools to spawn env PATH when running child builds so external PATH/JAVA_HOME changes don't require a server restart.
+
+Examples
+- Detected result (JSON):
+  {
+    "name": "adb",
+    "cmd": "/Users/xxx/Library/Android/sdk/platform-tools/adb",
+    "ok": true,
+    "version": "Android Debug Bridge version 1.0.41"
+  }
+
+- Java suggestion when incompatible:
+  { "name": "java", "ok": false, "suggestion": "Found GraalVM (Java 23). Use Java 17 or 21: set ANDROID_STUDIO_JBR or JAVA_HOME." }

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,10 @@ 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'
+import { getIdbCmd, isIDBInstalled } from './utils/ios/utils.js'
+import { getXcrunCmd } from './utils/ios/utils.js'
+import { execSync } from 'child_process'
 
 
 const server = new Server(
@@ -31,7 +36,46 @@ 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))
+    }
+  }
+
+  // Check idb availability (non-fatal)
+  try {
+    const idbInstalled = await isIDBInstalled()
+    const idbCmd = getIdbCmd()
+    if (idbInstalled) console.debug('[startup] idb available:', idbCmd)
+    else console.debug('[startup] idb not available or failed to run:', idbCmd)
+  } catch (e: unknown) {
+    console.warn('[startup] error during idb healthcheck:', e instanceof Error ? e.message : String(e))
+  }
+
+  // Check xcrun availability (non-fatal)
+  try {
+    const xcrun = getXcrunCmd()
+    try {
+      const out = execSync(`${xcrun} --version`, { stdio: ['ignore','pipe','ignore'] }).toString().trim()
+      console.debug('[startup] xcrun available:', xcrun, out.split('\n')[0])
+    } catch (err: unknown) {
+      console.warn('[startup] xcrun not available or failed to run:', xcrun, err instanceof Error ? err.message : String(err))
+    }
+  } catch (e: unknown) {
+    console.warn('[startup] error during xcrun healthcheck:', e instanceof Error ? e.message : String(e))
+  }
+
+})()
 
 function wrapResponse<T>(data: T) {
   return {
@@ -487,9 +531,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/ios/utils.ts

@@ -62,11 +62,12 @@ export async function isIDBInstalled(): Promise<boolean> {
   try {
     execSync(`command -v ${cmd}`, { stdio: ['ignore','pipe','ignore'] })
     return true
-  } catch {
+  } catch (e: unknown) {
     try {
       execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','ignore'], timeout: 2000 })
       return true
-    } catch {
+    } catch (e2: unknown) {
+      console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`)
       return false
     }
   }

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) })