mobile-debug-mcp 0.34.0 → 0.35.0

package/dist/system/ios-status.js

@@ -0,0 +1,132 @@
+import { getIdbCmd, getXcrunCmd } from '../utils/ios/utils.js';
+import { probeIdb } from '../utils/cli/idb/idb-helper.js';
+import { probeCommand, makeFailure, makeToolEntry, describeXcrunDiscovery, describeIdbDiscovery } from './probes.js';
+export function buildIOSPlatform(ios, hostSupported, hostOs) {
+    const platformUnsupported = !hostSupported || hostOs === 'linux' || hostOs === 'windows';
+    if (platformUnsupported) {
+        return {
+            status: 'unsupported',
+            tools: {},
+            providers: {},
+            capabilities: {},
+            devices: [],
+            failures: [
+                makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is only supported on macOS.', {
+                    tool: null,
+                    searchedLocations: [],
+                    selectedProvider: null,
+                    rawVersion: null,
+                    remediation: ['Run Mobile Debug MCP on macOS for iOS toolchain discovery.']
+                })
+            ]
+        };
+    }
+    const { xcrunCmd, xcrunProbe, idbProbe, xcrunTool, idbTool, idbCompanionTool, lldbTool } = iosTools(ios, hostSupported, hostOs);
+    const simctlAvailable = !!ios.iosAvailable;
+    const idbAvailable = !!idbProbe.ok;
+    const bootedDevices = ios.iosDevices > 0
+        ? Array.from({ length: ios.iosDevices }, (_, index) => ({
+            id: `ios-simulator-${index + 1}`,
+            state: 'booted'
+        }))
+        : [];
+    const { platformUnavailableFailure, deviceFailure } = iosFailures(platformUnsupported, simctlAvailable, bootedDevices.length, xcrunCmd, xcrunProbe.raw);
+    const selectedInstallProvider = idbAvailable ? 'idb' : simctlAvailable ? 'simctl' : null;
+    const selectedDebugProvider = simctlAvailable ? 'LLDB' : null;
+    const selectedDiscoveryProvider = idbAvailable ? 'idb' : simctlAvailable ? 'simctl' : null;
+    const status = platformUnsupported
+        ? 'unsupported'
+        : !simctlAvailable
+            ? 'unavailable'
+            : !bootedDevices.length
+                ? 'partially_ready'
+                : 'ready';
+    const iosFailure = platformUnsupported
+        ? makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is only supported on macOS.', {
+            tool: null,
+            searchedLocations: [],
+            selectedProvider: null,
+            rawVersion: null,
+            remediation: ['Run Mobile Debug MCP on macOS for iOS toolchain discovery.']
+        })
+        : platformUnavailableFailure ?? deviceFailure ?? null;
+    const failureList = [iosFailure].filter((value) => value !== null);
+    return {
+        status,
+        tools: {
+            xcrun: xcrunTool,
+            idb: idbTool,
+            idb_companion: idbCompanionTool,
+            lldb: lldbTool
+        },
+        providers: {
+            idb: { available: idbAvailable, selected: selectedInstallProvider === 'idb', tool: 'idb' },
+            simctl: { available: simctlAvailable, selected: selectedInstallProvider === 'simctl', tool: 'xcrun' },
+            lldb: { available: simctlAvailable, selected: selectedDebugProvider === 'LLDB', tool: 'xcrun' }
+        },
+        capabilities: iosCapabilities(selectedDiscoveryProvider, selectedInstallProvider, selectedDebugProvider, simctlAvailable, bootedDevices.length, deviceFailure, iosFailure),
+        devices: bootedDevices,
+        failures: failureList
+    };
+}
+function iosTools(ios, hostSupported, hostOs) {
+    const xcrunCmd = getXcrunCmd();
+    const xcrunProbe = ios.iosAvailable ? probeCommand(xcrunCmd, ['--version']) : { ok: false, raw: null, parsedVersion: null };
+    const idbCmd = getIdbCmd();
+    const idbProbe = hostSupported && hostOs === 'macos' ? probeIdb(idbCmd) : { ok: false, raw: null, parsedVersion: null };
+    const idbCompanionProbe = hostSupported && hostOs === 'macos' ? probeCommand('idb_companion', ['--version']) : { ok: false, raw: null, parsedVersion: null };
+    const xcrunTool = makeToolEntry(xcrunCmd, describeXcrunDiscovery(xcrunCmd).discoverySource, xcrunProbe.raw, xcrunProbe.ok ? 'valid' : 'invalid');
+    const idbTool = makeToolEntry(idbCmd, describeIdbDiscovery(idbCmd).discoverySource, idbProbe.raw, idbProbe.ok ? 'valid' : 'invalid');
+    const idbCompanionTool = makeToolEntry('idb_companion', 'PATH', idbCompanionProbe.raw, idbCompanionProbe.ok ? 'valid' : 'invalid');
+    const lldbTool = makeToolEntry('xcrun lldb', 'xcrun', xcrunProbe.raw, xcrunProbe.ok ? 'valid' : 'invalid');
+    return { xcrunCmd, xcrunProbe, idbProbe, xcrunTool, idbTool, idbCompanionTool, lldbTool };
+}
+function iosFailures(platformUnsupported, simctlAvailable, deviceCount, xcrunCmd, rawVersion) {
+    const platformUnavailableFailure = !platformUnsupported && !simctlAvailable
+        ? makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is unavailable on this host.', {
+            tool: 'xcrun',
+            searchedLocations: describeXcrunDiscovery(xcrunCmd).searchedLocations,
+            selectedProvider: null,
+            rawVersion: rawVersion,
+            remediation: ['Install Xcode Command Line Tools and ensure xcrun is on PATH.']
+        })
+        : null;
+    const deviceFailure = simctlAvailable && !deviceCount
+        ? makeFailure('DEVICE_NOT_FOUND', 'ios', 'No iOS simulators are booted.', {
+            tool: 'simctl',
+            searchedLocations: ['xcrun simctl list devices booted --json'],
+            selectedProvider: 'simctl',
+            rawVersion: rawVersion,
+            remediation: ['Boot a simulator in Xcode or via xcrun simctl boot.']
+        })
+        : null;
+    return { platformUnavailableFailure, deviceFailure };
+}
+function iosCapabilities(selectedDiscoveryProvider, selectedInstallProvider, selectedDebugProvider, simctlAvailable, deviceCount, deviceFailure, iosFailure) {
+    const applicationCapability = {
+        availability: !!selectedInstallProvider && deviceCount > 0,
+        selectedProvider: selectedInstallProvider,
+        blockingFailure: selectedInstallProvider && deviceCount > 0 ? null : deviceFailure ?? iosFailure
+    };
+    return {
+        device_discovery: {
+            availability: !!selectedDiscoveryProvider,
+            selectedProvider: selectedDiscoveryProvider,
+            blockingFailure: selectedDiscoveryProvider ? null : iosFailure
+        },
+        install_app: { ...applicationCapability },
+        launch_app: { ...applicationCapability },
+        ui_interaction: { ...applicationCapability },
+        screenshot: { ...applicationCapability },
+        log_capture: {
+            availability: simctlAvailable && deviceCount > 0,
+            selectedProvider: simctlAvailable ? 'simctl' : null,
+            blockingFailure: simctlAvailable && deviceCount > 0 ? null : deviceFailure ?? iosFailure
+        },
+        debug: {
+            availability: !!selectedDebugProvider,
+            selectedProvider: selectedDebugProvider,
+            blockingFailure: selectedDebugProvider ? null : iosFailure
+        }
+    };
+}

package/dist/system/ios.js

@@ -12,14 +12,7 @@ export async function checkIOS() {
             try {
                 const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] });
                 try {
-                    const data = JSON.parse(simOut);
-                    let count = 0;
-                    for (const k in data.devices) {
-                        const arr = data.devices[k];
-                        if (Array.isArray(arr))
-                            count += arr.filter((d) => (d.state || '').toLowerCase() === 'booted').length;
-                    }
-                    iosDevices = count;
+                    iosDevices = countBooted(simOut);
                 }
                 catch {
                     // Some xcrun builds include extra text around the JSON response.
@@ -44,3 +37,13 @@ export async function checkIOS() {
     }
     return { iosAvailable, iosDevices, issues };
 }
+function countBooted(simOut) {
+    const data = JSON.parse(simOut);
+    let count = 0;
+    for (const k in data.devices) {
+        const arr = data.devices[k];
+        if (Array.isArray(arr))
+            count += arr.filter((d) => (d.state || '').toLowerCase() === 'booted').length;
+    }
+    return count;
+}

package/dist/system/model.js

@@ -0,0 +1 @@
+export {};

package/dist/system/probes.js

@@ -0,0 +1,105 @@
+import { spawnSync } from 'child_process';
+import path from 'path';
+export function normalizeHostOs(platform) {
+    switch (platform) {
+        case 'darwin':
+            return 'macos';
+        case 'linux':
+            return 'linux';
+        case 'win32':
+            return 'windows';
+        case 'freebsd':
+        case 'openbsd':
+        case 'netbsd':
+        case 'sunos':
+            return platform;
+        default:
+            return 'unknown';
+    }
+}
+export function isSupportedHost(hostOs) {
+    return hostOs === 'macos' || hostOs === 'linux' || hostOs === 'windows';
+}
+export function firstVersionToken(raw) {
+    if (!raw)
+        return null;
+    const match = String(raw).match(/(\d+(?:\.\d+)+|\d+)/);
+    return match?.[1] ?? null;
+}
+export function probeCommand(command, args, timeoutMs = 2000) {
+    try {
+        const result = spawnSync(command, args, { encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] });
+        const raw = `${result.stdout || ''}${result.stderr || ''}`.trim() || null;
+        return {
+            ok: result.status === 0,
+            raw,
+            parsedVersion: firstVersionToken(raw)
+        };
+    }
+    catch {
+        return { ok: false, raw: null, parsedVersion: null };
+    }
+}
+export function makeFailure(code, platform, message, opts = {}) {
+    return {
+        code,
+        platform,
+        tool: opts.tool ?? null,
+        message,
+        searchedLocations: opts.searchedLocations ?? [],
+        selectedProvider: opts.selectedProvider ?? null,
+        rawVersion: opts.rawVersion ?? null,
+        remediation: opts.remediation ?? []
+    };
+}
+export function makeToolEntry(resolvedPath, discoverySource, rawVersionOutput, validationStatus) {
+    return {
+        resolvedPath,
+        discoverySource,
+        parsedVersion: firstVersionToken(rawVersionOutput),
+        rawVersionOutput,
+        validationStatus
+    };
+}
+export function describeAdbDiscovery(adbCmd) {
+    const searchedLocations = ['ADB_PATH', 'ANDROID_SDK_ROOT/platform-tools/adb', 'ANDROID_HOME/platform-tools/adb', '~/Library/Android/sdk/platform-tools/adb', 'PATH'];
+    if (process.env.ADB_PATH && process.env.ADB_PATH.trim())
+        return { discoverySource: 'ADB_PATH', searchedLocations };
+    if (process.env.ANDROID_SDK_ROOT)
+        return { discoverySource: 'ANDROID_SDK_ROOT', searchedLocations };
+    if (process.env.ANDROID_HOME)
+        return { discoverySource: 'ANDROID_HOME', searchedLocations };
+    if (adbCmd.includes('Library/Android/sdk'))
+        return { discoverySource: 'HOME_SDK', searchedLocations };
+    if (adbCmd === 'adb')
+        return { discoverySource: 'PATH_OR_FALLBACK', searchedLocations };
+    return { discoverySource: 'PATH', searchedLocations };
+}
+export function describeXcrunDiscovery(xcrunCmd) {
+    const searchedLocations = ['XCRUN_PATH', 'PATH'];
+    if (process.env.XCRUN_PATH && process.env.XCRUN_PATH.trim())
+        return { discoverySource: 'XCRUN_PATH', searchedLocations };
+    return { discoverySource: xcrunCmd === 'xcrun' ? 'PATH' : 'PATH', searchedLocations };
+}
+export function describeIdbDiscovery(idbCmd) {
+    const searchedLocations = ['MCP_IDB_PATH', 'IDB_PATH', 'mcp.config.json', '~/.mcp/config.json', 'PATH', '/opt/homebrew/bin/idb', '/usr/local/bin/idb'];
+    if (process.env.MCP_IDB_PATH && process.env.MCP_IDB_PATH.trim())
+        return { discoverySource: 'MCP_IDB_PATH', searchedLocations };
+    if (process.env.IDB_PATH && process.env.IDB_PATH.trim())
+        return { discoverySource: 'IDB_PATH', searchedLocations };
+    return { discoverySource: idbCmd === 'idb' ? 'PATH_OR_FALLBACK' : 'PATH', searchedLocations };
+}
+export function describeJavaDiscovery(javaHome) {
+    const searchedLocations = ['GRADLE_JAVA_HOME', 'JAVA_HOME', 'GRADLE_HOME', 'detectJavaHome'];
+    if (process.env.GRADLE_JAVA_HOME && process.env.GRADLE_JAVA_HOME.trim())
+        return { discoverySource: 'GRADLE_JAVA_HOME', searchedLocations };
+    if (process.env.JAVA_HOME && process.env.JAVA_HOME.trim())
+        return { discoverySource: 'JAVA_HOME', searchedLocations };
+    if (process.env.GRADLE_HOME && process.env.GRADLE_HOME.trim())
+        return { discoverySource: 'GRADLE_HOME', searchedLocations };
+    return { discoverySource: javaHome ? 'detected' : null, searchedLocations };
+}
+export function resolveJavaBinaryPath(javaHome, hostOs) {
+    const javaBinary = hostOs === 'windows' ? 'java.exe' : 'java';
+    return path.join(javaHome, 'bin', javaBinary);
+}

package/dist/system/status-summary.js

@@ -0,0 +1,43 @@
+export function buildLegacySummary(androidStatus, iosStatus, gradle) {
+    const androidReady = androidStatus.status === 'ready';
+    const iosReady = iosStatus.status === 'ready';
+    const gradleReady = (gradle.issues || []).length === 0;
+    const overallStatus = (androidReady || iosReady || gradleReady)
+        ? ((androidReady && iosReady && gradleReady) ? 'ready' : 'degraded')
+        : 'blocked';
+    return {
+        overall: overallStatus,
+        android: {
+            ready: androidReady,
+            summary: androidStatus.status === 'ready'
+                ? `${androidStatus.devices.length} Android device(s) connected; log access available`
+                : androidStatus.status === 'partially_ready'
+                    ? 'Android toolchain available but device-dependent capabilities are limited'
+                    : androidStatus.status === 'unsupported'
+                        ? 'Android unsupported on this host'
+                        : 'ADB unavailable',
+            blockers: androidStatus.failures.map((failure) => failure.message)
+        },
+        ios: {
+            ready: iosReady,
+            summary: iosStatus.status === 'ready'
+                ? `${iosStatus.devices.length} iOS simulator(s) booted`
+                : iosStatus.status === 'partially_ready'
+                    ? 'iOS toolchain available but device-dependent capabilities are limited'
+                    : iosStatus.status === 'unsupported'
+                        ? 'iOS unsupported on this host'
+                        : 'xcrun unavailable',
+            blockers: iosStatus.failures.map((failure) => failure.message)
+        },
+        gradle: {
+            ready: gradleReady,
+            summary: !gradle.gradleJavaHome
+                ? 'No explicit Gradle JDK override detected'
+                : gradleReady
+                    ? `Gradle JDK configured at ${gradle.gradleJavaHome}`
+                    : `Gradle JDK override invalid: ${gradle.gradleJavaHome}`,
+            blockers: gradle.issues || [],
+            suggestedFixes: gradle.suggestedFixes || []
+        }
+    };
+}

package/dist/system/unsupported-status.js

@@ -0,0 +1,52 @@
+import { makeFailure } from './probes.js';
+export function buildUnsupportedHostStatus(hostOs) {
+    const failureMessage = `Host operating system '${hostOs}' is not supported.`;
+    const remediation = ['Run Mobile Debug MCP on macOS, Linux, or Windows.'];
+    const failureAndroid = makeFailure('HOST_OS_UNSUPPORTED', 'android', failureMessage, {
+        remediation
+    });
+    const failureIos = makeFailure('HOST_OS_UNSUPPORTED', 'ios', failureMessage, {
+        remediation
+    });
+    return {
+        success: false,
+        status: 'blocked',
+        adbAvailable: false,
+        adbVersion: '',
+        devices: 0,
+        deviceStates: '',
+        logsAvailable: false,
+        envValid: false,
+        issues: [failureMessage],
+        appInstalled: undefined,
+        iosAvailable: false,
+        iosDevices: 0,
+        gradleJavaHome: undefined,
+        gradleValid: false,
+        gradleFilesChecked: [],
+        gradleSuggestedFixes: [],
+        host: { os: hostOs, supported: false },
+        android: {
+            status: 'unsupported',
+            tools: {},
+            providers: {},
+            capabilities: {},
+            devices: [],
+            failures: [failureAndroid]
+        },
+        ios: {
+            status: 'unsupported',
+            tools: {},
+            providers: {},
+            capabilities: {},
+            devices: [],
+            failures: [failureIos]
+        },
+        summary: {
+            overall: 'blocked',
+            android: { ready: false, summary: `Host operating system '${hostOs}' is not supported.`, blockers: [failureMessage] },
+            ios: { ready: false, summary: `Host operating system '${hostOs}' is not supported.`, blockers: [failureMessage] },
+            gradle: { ready: false, summary: 'Gradle status unavailable on unsupported host', blockers: [], suggestedFixes: [] }
+        }
+    };
+}

package/dist/utils/android/commands.js

@@ -0,0 +1,89 @@
+import { existsSync } from 'fs';
+import path from 'path';
+import { execCmd } from '../exec.js';
+import { spawnSync } from 'child_process';
+export 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 -> PATH -> known SDK locations -> fallback to 'adb'
+    if (process.env.ADB_PATH && process.env.ADB_PATH.trim())
+        return process.env.ADB_PATH;
+    const found = findInPath('adb');
+    if (found)
+        return found;
+    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;
+    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) };
+    }
+}
+export function getAdbArgs(args, deviceId) {
+    if (deviceId) {
+        return ['-s', deviceId, ...args];
+    }
+    return args;
+}
+export function getAdbTimeout(args, customTimeout) {
+    if (typeof customTimeout === 'number' && !isNaN(customTimeout))
+        return customTimeout;
+    const envTimeout = parseInt(process.env.MCP_ADB_TIMEOUT || process.env.ADB_TIMEOUT || '', 10);
+    if (!isNaN(envTimeout) && envTimeout > 0)
+        return envTimeout;
+    if (args.includes('logcat'))
+        return 10000;
+    if (args.includes('uiautomator') && args.includes('dump'))
+        return 20000;
+    return 120000;
+}
+export async function execAdb(args, deviceId, options = {}) {
+    const adbArgs = getAdbArgs(args, deviceId);
+    const timeoutMs = getAdbTimeout(args, options.timeout);
+    const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell });
+    if (res.exitCode !== 0)
+        throw new Error(res.stderr || `Command failed with code ${res.exitCode}`);
+    return res.stdout;
+}
+export async function spawnAdb(args, deviceId, options = {}) {
+    const adbArgs = getAdbArgs(args, deviceId);
+    const timeoutMs = getAdbTimeout(args, options.timeout);
+    const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell });
+    return { stdout: res.stdout, stderr: res.stderr, code: res.exitCode };
+}

package/dist/utils/android/gradle.js

@@ -0,0 +1,139 @@
+import { promises as fsPromises, existsSync } from 'fs';
+import path from 'path';
+import { detectJavaHome } from '../java.js';
+import { checkGradle } from '../../system/gradle.js';
+import { resolveAdbCmd } from './commands.js';
+export function mergeEnv(overrides) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(overrides || {})) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    return env;
+}
+export async function prepareGradle(projectPath, envOverrides = {}) {
+    const env = mergeEnv(envOverrides);
+    const gradlewPath = path.join(projectPath, 'gradlew');
+    const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle';
+    const execCmd = existsSync(gradlewPath) ? gradlewPath : gradleCmd;
+    // Start with a default task; callers may append/override via env flags
+    const gradleArgs = [env.MCP_GRADLE_TASK || 'assembleDebug'];
+    // Respect generic MCP_BUILD_JOBS and Android-specific MCP_GRADLE_WORKERS
+    const workers = env.MCP_GRADLE_WORKERS || env.MCP_BUILD_JOBS;
+    if (workers) {
+        gradleArgs.push(`--max-workers=${workers}`);
+    }
+    // Respect gradle cache env: default enabled; set MCP_GRADLE_CACHE=0 to disable
+    if (env.MCP_GRADLE_CACHE === '0') {
+        gradleArgs.push('-Dorg.gradle.caching=false');
+    }
+    const detectedJavaHome = await detectJavaHome().catch(() => undefined);
+    // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+    let gradleCheck;
+    try {
+        gradleCheck = await checkGradle();
+    }
+    catch {
+        gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] };
+    }
+    // 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 = [];
+    configureJava(env, gradleArgs, pathParts, detectedJavaHome, gradleCheck);
+    configurePlatformTools(env, pathParts, platformToolsDir);
+    if (pathParts.length > 0) {
+        env.PATH = `${pathParts.join(path.delimiter)}${path.delimiter}${env.PATH || ''}`;
+    }
+    try {
+        delete env.SHELL;
+    }
+    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 (e) {
+            console.debug('[prepareGradle] chmod failed for gradlew:', String(e));
+        }
+        // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
+        spawnOpts.shell = false;
+    }
+    else {
+        // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+        spawnOpts.shell = false;
+    }
+    return { execCmd, gradleArgs, spawnOpts };
+}
+function configureJava(env, gradleArgs, pathParts, detectedJavaHome, gradleCheck) {
+    // Prefer a detected (validated) Java home from the system/IDE
+    if (detectedJavaHome) {
+        if (env.JAVA_HOME !== detectedJavaHome) {
+            env.JAVA_HOME = detectedJavaHome;
+        }
+        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;
+    }
+    else if (gradleCheck && gradleCheck.gradleJavaHome) {
+        // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+        if (gradleCheck.gradleValid) {
+            const p = gradleCheck.gradleJavaHome;
+            const javaBin = path.join(p, 'bin');
+            if (!env.PATH || !env.PATH.includes(javaBin))
+                pathParts.push(javaBin);
+            gradleArgs.push(`-Dorg.gradle.java.home=${p}`);
+            gradleArgs.push('--no-daemon');
+            env.GRADLE_JAVA_HOME = p;
+        }
+        else {
+            // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+            console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`);
+            try {
+                delete env.GRADLE_JAVA_HOME;
+            }
+            catch { }
+        }
+    }
+}
+function configurePlatformTools(env, pathParts, platformToolsDir) {
+    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);
+        }
+    }
+}