mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/interact/waits/ui-wait.js

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

package/dist/manage/android.js

@@ -47,57 +47,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         let apkToInstall = apkPath;
         try {
-            const stat = await fs.stat(apkPath).catch(() => null);
-            if (stat && stat.isDirectory()) {
-                const detectedJavaHome = await detectJavaHome().catch(() => undefined);
-                const env = { ...process.env };
-                if (detectedJavaHome) {
-                    if (env.JAVA_HOME !== detectedJavaHome) {
-                        env.JAVA_HOME = detectedJavaHome;
-                        env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
-                        console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome);
-                    }
-                }
-                try {
-                    delete env.SHELL;
-                }
-                catch { }
-                const gradleArgs = ['assembleDebug'];
-                if (detectedJavaHome) {
-                    gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
-                    gradleArgs.push('--no-daemon');
-                    env.GRADLE_JAVA_HOME = detectedJavaHome;
-                }
-                const wrapperPath = path.join(apkPath, 'gradlew');
-                const useWrapper = existsSync(wrapperPath);
-                const execCmd = useWrapper ? wrapperPath : 'gradle';
-                const spawnOpts = { cwd: apkPath, env };
-                if (useWrapper) {
-                    await fs.chmod(wrapperPath, 0o755).catch(() => { });
-                    // Run wrapper directly to avoid shell splitting of args
-                    spawnOpts.shell = false;
-                }
-                else {
-                    // Execute gradle directly without a shell so paths with spaces are preserved
-                    spawnOpts.shell = false;
-                }
-                const proc = spawn(execCmd, gradleArgs, spawnOpts);
-                let stderr = '';
-                await new Promise((resolve, reject) => {
-                    proc.stderr?.on('data', d => stderr += d.toString());
-                    proc.on('close', code => {
-                        if (code === 0)
-                            resolve();
-                        else
-                            reject(new Error(stderr || `Gradle build failed with code ${code}`));
-                    });
-                    proc.on('error', err => reject(err));
-                });
-                const built = await findApk(apkPath);
-                if (!built)
-                    throw new Error('Could not locate built APK after running Gradle');
-                apkToInstall = built;
-            }
+            apkToInstall = await prepareInstallApk(apkPath);
             try {
                 const res = await spawnAdb(['install', '-r', apkToInstall], deviceId);
                 if (res.code === 0) {
@@ -221,3 +171,57 @@ export class AndroidManage {
         }
     }
 }
+async function prepareInstallApk(apkPath) {
+    const stat = await fs.stat(apkPath).catch(() => null);
+    if (stat && stat.isDirectory()) {
+        const detectedJavaHome = await detectJavaHome().catch(() => undefined);
+        const env = { ...process.env };
+        if (detectedJavaHome) {
+            if (env.JAVA_HOME !== detectedJavaHome) {
+                env.JAVA_HOME = detectedJavaHome;
+                env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
+                console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome);
+            }
+        }
+        try {
+            delete env.SHELL;
+        }
+        catch { }
+        const gradleArgs = ['assembleDebug'];
+        if (detectedJavaHome) {
+            gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
+            gradleArgs.push('--no-daemon');
+            env.GRADLE_JAVA_HOME = detectedJavaHome;
+        }
+        const wrapperPath = path.join(apkPath, 'gradlew');
+        const useWrapper = existsSync(wrapperPath);
+        const execCmd = useWrapper ? wrapperPath : 'gradle';
+        const spawnOpts = { cwd: apkPath, env };
+        if (useWrapper) {
+            await fs.chmod(wrapperPath, 0o755).catch(() => { });
+            // Run wrapper directly to avoid shell splitting of args
+            spawnOpts.shell = false;
+        }
+        else {
+            // Execute gradle directly without a shell so paths with spaces are preserved
+            spawnOpts.shell = false;
+        }
+        const proc = spawn(execCmd, gradleArgs, spawnOpts);
+        let stderr = '';
+        await new Promise((resolve, reject) => {
+            proc.stderr?.on('data', d => stderr += d.toString());
+            proc.on('close', code => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(stderr || `Gradle build failed with code ${code}`));
+            });
+            proc.on('error', err => reject(err));
+        });
+        const built = await findApk(apkPath);
+        if (!built)
+            throw new Error('Could not locate built APK after running Gradle');
+        return built;
+    }
+    return apkPath;
+}

package/dist/manage/index.js

@@ -28,15 +28,15 @@ export async function detectProjectPlatform(projectPath) {
                 try {
                     const full = path.join(dir, e);
                     const st = await fs.stat(full).catch(() => null);
-                    if (st && st.isDirectory()) {
-                        const child = await scan(full, depth - 1);
-                        if (child.ios)
-                            res.ios = true;
-                        if (child.android)
-                            res.android = true;
-                        if (res.ios && res.android)
-                            return res;
-                    }
+                    if (!st || !st.isDirectory())
+                        continue;
+                    const child = await scan(full, depth - 1);
+                    if (child.ios)
+                        res.ios = true;
+                    if (child.android)
+                        res.android = true;
+                    if (res.ios && res.android)
+                        return res;
                 }
                 catch { }
             }
@@ -146,10 +146,8 @@ export class ToolsManage {
                     if (apk)
                         return { artifactPath: apk, output: out };
                 }
-                catch (err) {
-                    const stdout = err && err.stdout ? String(err.stdout) : '';
-                    const stderr = err && err.stderr ? String(err.stderr) : '';
-                    throw new Error(`flutter build apk failed: ${stderr || stdout || err.message}`);
+                catch (thrown) {
+                    throw flutterBuildError(thrown, 'apk');
                 }
             }
             if (!platform || platform === 'ios') {
@@ -160,10 +158,8 @@ export class ToolsManage {
                     if (app)
                         return { artifactPath: app, output: out };
                 }
-                catch (err) {
-                    const stdout = err && err.stdout ? String(err.stdout) : '';
-                    const stderr = err && err.stderr ? String(err.stderr) : '';
-                    throw new Error(`flutter build ios failed: ${stderr || stdout || err.message}`);
+                catch (thrown) {
+                    throw flutterBuildError(thrown, 'ios');
                 }
             }
         }
@@ -172,20 +168,7 @@ export class ToolsManage {
             // Preserve error message for diagnostics if needed
             void e;
         }
-        // Fallback: try native subproject builds
-        if (!platform || platform === 'android') {
-            const androidDir = path.join(projectPath, 'android');
-            const android = new AndroidManage();
-            const artifact = await android.build(androidDir, _forceClean ? 'clean && assembleDebug' : 'assembleDebug');
-            return artifact;
-        }
-        if (!platform || platform === 'ios') {
-            const iosDir = path.join(projectPath, 'ios');
-            const ios = new iOSManage();
-            const artifact = await ios.build(iosDir);
-            return artifact;
-        }
-        return { error: 'Unable to build flutter project' };
+        return buildFlutterNative(projectPath, platform, _forceClean);
     }
     static async build_react_native({ projectPath, platform, variant, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
         // silence unused params
@@ -291,50 +274,8 @@ export class ToolsManage {
             pushEvent({ type: 'build', status: 'failed', error: 'Both platform and projectType parameters are required.' });
             return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).' } };
         }
-        // determine platform if not provided by inspecting path or projectType hint
-        let chosenPlatform = platform;
-        try {
-            if (!chosenPlatform) {
-                // If caller provided projectType, respect it as a hard override and map to platform
-                if (projectType) {
-                    if (projectType === 'kmp' || projectType === 'react-native' || projectType === 'flutter') {
-                        chosenPlatform = 'android';
-                        pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing android platform` });
-                    }
-                    else if (projectType === 'native' || projectType === 'ios') {
-                        chosenPlatform = 'ios';
-                        pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing ios platform` });
-                    }
-                    else {
-                        pushEvent({ type: 'build', status: 'failed', error: `Unknown projectType: ${projectType}` });
-                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: `Unknown projectType: ${projectType}` } };
-                    }
-                }
-                else {
-                    // If autodetect is disabled, require explicit platform or projectType
-                    if (process.env.MCP_DISABLE_AUTODETECT === '1') {
-                        pushEvent({ type: 'build', status: 'failed', error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType' });
-                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType (ios|android).' } };
-                    }
-                    const det = await detectProjectPlatform(projectPath);
-                    if (det === 'ios' || det === 'android') {
-                        chosenPlatform = det;
-                    }
-                    else if (det === 'ambiguous') {
-                        pushEvent({ type: 'build', status: 'failed', error: 'Ambiguous project (contains both iOS and Android). Please provide platform: "ios" or "android".' });
-                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Ambiguous project - please provide explicit platform parameter (ios|android).' } };
-                    }
-                    else {
-                        // Unknown project type - do not guess. Request explicit platform.
-                        pushEvent({ type: 'build', status: 'failed', error: 'Unknown project type - unable to autodetect platform. Please provide platform or projectType.' });
-                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Unknown project type - please provide platform or projectType (ios|android).' } };
-                    }
-                }
-            }
-        }
-        catch {
-            // detection failed; avoid guessing a platform
-        }
+        // Explicit platform/projectType were required above; no autodetection occurs.
+        const chosenPlatform = platform;
         pushEvent({ type: 'build', status: 'started', platform: chosenPlatform });
         let buildRes;
         try {
@@ -376,3 +317,25 @@ export class ToolsManage {
         return { devices };
     }
 }
+async function buildFlutterNative(projectPath, platform, _forceClean) {
+    // Fallback: try native subproject builds
+    if (!platform || platform === 'android') {
+        const androidDir = path.join(projectPath, 'android');
+        const android = new AndroidManage();
+        const artifact = await android.build(androidDir, _forceClean ? 'clean && assembleDebug' : 'assembleDebug');
+        return artifact;
+    }
+    if (!platform || platform === 'ios') {
+        const iosDir = path.join(projectPath, 'ios');
+        const ios = new iOSManage();
+        const artifact = await ios.build(iosDir);
+        return artifact;
+    }
+    return { error: 'Unable to build flutter project' };
+}
+function flutterBuildError(thrown, kind) {
+    const err = thrown;
+    const stdout = err && err.stdout ? String(err.stdout) : '';
+    const stderr = err && err.stderr ? String(err.stderr) : '';
+    return new Error(`flutter build ${kind} failed: ${stderr || stdout || err.message}`);
+}

package/dist/manage/ios/build-types.js

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

package/dist/manage/ios/build.js

@@ -0,0 +1,210 @@
+import { promises as fs } from "fs";
+import { spawn } from "child_process";
+import { getIOSDeviceMetadata, findAppBundle } from "../../utils/ios/utils.js";
+import path from "path";
+import { findProject } from './project-discovery.js';
+import { detectScheme } from './scheme.js';
+export async function buildIOS(projectPath, optsOrVariant) {
+    // Support legacy variant string as second arg
+    const opts = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {});
+    const env = { ...process.env, ...(opts.env || {}) };
+    try {
+        // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
+        const project = await resolveBuildProject(projectPath, opts);
+        if ('error' in project)
+            return project;
+        const { projectRootDir } = project;
+        const command = await prepareBuild(projectPath, opts, env, project);
+        const failure = await executeBuild(command, projectRootDir, env);
+        if (failure)
+            return failure;
+        // Try to locate built .app. First search project tree, then DerivedData if necessary
+        const built = await findAppBundle(projectPath);
+        if (built)
+            return { artifactPath: built };
+        // Fallback: search DerivedData for matching product
+        const dd = path.join(process.env.HOME || '', 'Library', 'Developer', 'Xcode', 'DerivedData');
+        try {
+            const entries = await fs.readdir(dd).catch(() => []);
+            for (const e of entries) {
+                const candidate = path.join(dd, e);
+                const found = await findAppBundle(candidate).catch(() => undefined);
+                if (found)
+                    return { artifactPath: found };
+            }
+        }
+        catch { }
+        return { error: 'Could not find .app after build' };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+async function resolveBuildProject(projectPath, opts) {
+    // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
+    const absProjectPath = path.resolve(projectPath);
+    // If caller supplied explicit workspace/project, prefer those and set projectRootDir accordingly
+    let projectRootDir = absProjectPath;
+    let workspace = opts.workspace;
+    let proj = opts.project;
+    if (workspace) {
+        // normalize workspace path and set root to its parent
+        workspace = path.isAbsolute(workspace) ? workspace : path.join(absProjectPath, workspace);
+        projectRootDir = path.dirname(workspace);
+        workspace = path.basename(workspace);
+    }
+    else if (proj) {
+        proj = path.isAbsolute(proj) ? proj : path.join(absProjectPath, proj);
+        projectRootDir = path.dirname(proj);
+        proj = path.basename(proj);
+    }
+    else {
+        const projectInfo = await findProject(absProjectPath, 4);
+        if (!projectInfo)
+            return { error: 'No Xcode project or workspace found' };
+        projectRootDir = projectInfo.dir || absProjectPath;
+        workspace = projectInfo.workspace;
+        proj = projectInfo.proj;
+    }
+    return { projectRootDir, workspace, proj };
+}
+async function prepareBuild(projectPath, opts, env, project) {
+    const { projectRootDir, workspace, proj } = project;
+    const destinationUDID = await destination(opts, env);
+    // Determine xcode command early so it can be used when detecting schemes
+    const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild';
+    // Determine available schemes by querying xcodebuild -list rather than guessing
+    // Prepare build flags and paths (support incremental builds)
+    let buildArgs;
+    let chosenScheme = opts.scheme || null;
+    // Derived data and result bundle (agent-configurable)
+    const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
+    // Use unique result bundle path by default to avoid collisions
+    const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`);
+    const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4);
+    const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1';
+    // ensure result dirs exist
+    await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => { });
+    await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => { });
+    // remove any pre-existing result bundle path to avoid xcodebuild complaining
+    await fs.rm(resultBundlePath, { recursive: true, force: true }).catch(() => { });
+    if (workspace) {
+        const workspacePath = path.join(projectRootDir, workspace);
+        if (!chosenScheme)
+            chosenScheme = await detectScheme(projectRootDir, xcodeCmd, workspacePath, undefined, projectRootDir);
+        const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '');
+        buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
+    }
+    else {
+        const projectPathFull = path.join(projectRootDir, proj);
+        if (!chosenScheme)
+            chosenScheme = await detectScheme(projectRootDir, xcodeCmd, undefined, projectPathFull, projectRootDir);
+        const scheme = chosenScheme || proj.replace(/\.xcodeproj$/, '');
+        buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
+    }
+    // Insert clean if explicitly requested via env or opts
+    if (forceClean) {
+        const idx = buildArgs.indexOf('build');
+        if (idx >= 0)
+            buildArgs.splice(idx, 0, 'clean');
+    }
+    // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
+    if (destinationUDID) {
+        buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`);
+    }
+    // Add derived data and result bundle for diagnostics and faster incremental builds
+    buildArgs.push('-derivedDataPath', derivedDataPath);
+    buildArgs.push('-resultBundlePath', resultBundlePath);
+    // parallelisation and jobs
+    buildArgs.push('-parallelizeTargets');
+    buildArgs.push('-jobs', String(xcodeJobs));
+    // Prepare results directory for backwards-compatible logs
+    const resultsDir = path.join(projectPath, 'build-results');
+    // Remove any stale results to avoid xcodebuild complaining about existing result bundles
+    await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => { });
+    await fs.mkdir(resultsDir, { recursive: true }).catch(() => { });
+    return { xcodeCmd, buildArgs, resultsDir };
+}
+async function runAttempt(xcodeCmd, buildArgs, projectRootDir, env, timeoutMs) {
+    return new Promise((resolve) => {
+        const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout?.on('data', d => stdout += d.toString());
+        proc.stderr?.on('data', d => stderr += d.toString());
+        let killed = false;
+        const to = setTimeout(() => {
+            killed = true;
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch { }
+        }, timeoutMs);
+        proc.on('close', (code) => {
+            clearTimeout(to);
+            resolve({ code, stdout, stderr, killedByWatchdog: killed });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(to);
+            resolve({ code: null, stdout, stderr: String(err), killedByWatchdog: killed });
+        });
+    });
+}
+async function executeBuild(command, projectRootDir, env) {
+    const { xcodeCmd, buildArgs, resultsDir } = command;
+    const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
+    const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
+    const tries = MAX_RETRIES + 1;
+    let lastStdout = '';
+    let lastStderr = '';
+    let lastErr = null;
+    for (let attempt = 1; attempt <= tries; attempt++) {
+        // Run xcodebuild with a watchdog
+        const res = await runAttempt(xcodeCmd, buildArgs, projectRootDir, env, XCODEBUILD_TIMEOUT);
+        lastStdout = res.stdout;
+        lastStderr = res.stderr;
+        if (res.code === 0) {
+            // success — clear any previous error and stop retrying
+            lastErr = null;
+            break;
+        }
+        // record the failure for reporting
+        lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`);
+        lastErr.code = res.code;
+        lastErr.exitCode = res.code;
+        lastErr.killedByWatchdog = !!res.killedByWatchdog;
+        // write logs for diagnostics (helpful whether killed or not)
+        try {
+            await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => { });
+            await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stderr.log`), res.stderr).catch(() => { });
+        }
+        catch { }
+        // If killed by watchdog and there are remaining attempts, continue to retry
+        if (res.killedByWatchdog && attempt < tries) {
+            continue;
+        }
+        // no more retries or not a watchdog kill — break to report lastErr
+        if (attempt >= tries)
+            break;
+    }
+    if (lastErr) {
+        // Include diagnostics and result bundle path when available; provide structured info useful for agents
+        const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
+        const envSnapshot = { PATH: env.PATH };
+        return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: lastErr.code || null, invokedCommand, cwd: projectRootDir, envSnapshot } };
+    }
+    return null;
+}
+async function destination(opts, env) {
+    // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
+    let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || '';
+    if (!destinationUDID) {
+        try {
+            const meta = await getIOSDeviceMetadata('booted');
+            if (meta && meta.id)
+                destinationUDID = meta.id;
+        }
+        catch { }
+    }
+    return destinationUDID;
+}

package/dist/manage/ios/project-discovery.js

@@ -0,0 +1,29 @@
+import { promises as fs } from "fs";
+import path from "path";
+export async function findProject(root, maxDepth = 4) {
+    try {
+        const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        for (const e of ents) {
+            // .xcworkspace and .xcodeproj are directories on disk (bundles), not regular files
+            if (e.name.endsWith('.xcworkspace'))
+                return { dir: root, workspace: e.name };
+            if (e.name.endsWith('.xcodeproj'))
+                return { dir: root, proj: e.name };
+        }
+    }
+    catch { }
+    if (maxDepth <= 0)
+        return null;
+    try {
+        const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        for (const e of ents) {
+            if (e.isDirectory()) {
+                const candidate = await findProject(path.join(root, e.name), maxDepth - 1);
+                if (candidate)
+                    return candidate;
+            }
+        }
+    }
+    catch { }
+    return null;
+}

package/dist/manage/ios/scheme.js

@@ -0,0 +1,18 @@
+import { spawnSync } from "child_process";
+export async function detectScheme(projectRootDir, xcodeCmdInner, workspacePath, projectPathFull, cwd) {
+    try {
+        const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull];
+        // Run xcodebuild directly to list schemes
+        const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 });
+        const out = res.stdout || '';
+        const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m);
+        if (schemesMatch) {
+            const block = schemesMatch[1];
+            const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean);
+            if (schemes.length)
+                return schemes[0];
+        }
+    }
+    catch { }
+    return null;
+}