mobile-debug-mcp 0.11.0 → 0.12.1

package/README.md

@@ -1,15 +1,15 @@
-# Mobile Debug MCP
+# Mobile Dev MCP
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-> **Note:** iOS support is currently an untested Work In Progress (WIP). Please use with caution and report any issues.
+> **Note:** iOS support is limited currently, Please use with caution and report any issues.
 
 ## Requirements
 
 - Node.js >= 18
-- Android SDK (adb) for Android support
+- [Android SDK](https://developer.android.com/studio) (adb) for Android support
 - Xcode command-line tools for iOS support
-- Optional: idb for enhanced iOS device support
+- [idb](https://github.com/facebook/idb) for iOS device support
 
 ## Configuration example
 
@@ -19,12 +19,16 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
     "mobile-debug": {
       "command": "npx",
       "args": ["--yes","mobile-debug-mcp","server"],
-      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun" }
+      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
     }
   }
 }
 ```
 ## Usage
+
+Example: 
+After a crash tell the agent the following:
+
 I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
 
 ## Docs
@@ -35,3 +39,4 @@ I have a crash on the app, can you diagnose it, fix and validate using the mcp t
 ## License
 
 MIT
+

package/dist/android/diagnostics.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'child_process';
+import { getAdbCmd } from './utils.js';
+import { makeEnvSnapshot } from '../utils/diagnostics.js';
+export function execAdbWithDiagnostics(args, deviceId) {
+    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
+    const timeout = 120000;
+    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'ADB_PATH', 'HOME', 'JAVA_HOME']),
+        command: getAdbCmd(),
+        args: adbArgs,
+        suggestedFixes: []
+    };
+    if (res.status !== 0) {
+        if ((runResult.stderr || '').includes('device not found'))
+            runResult.suggestedFixes.push('Ensure device is connected and adb is authorized (adb devices)');
+        if ((runResult.stderr || '').includes('No such file or directory'))
+            runResult.suggestedFixes.push('Verify ADB_PATH or that adb is installed');
+    }
+    return { runResult };
+}

package/dist/android/manage.js

@@ -3,6 +3,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { existsSync } from 'fs';
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js';
+import { execAdbWithDiagnostics } from './diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 export class AndroidManage {
     async build(projectPath, _variant) {
@@ -34,8 +35,8 @@ export class AndroidManage {
     async installApp(apkPath, deviceId) {
         const metadata = await getAndroidDeviceMetadata('', deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        let apkToInstall = apkPath;
         try {
-            let apkToInstall = apkPath;
             const stat = await fs.stat(apkPath).catch(() => null);
             if (stat && stat.isDirectory()) {
                 const detectedJavaHome = await detectJavaHome().catch(() => undefined);
@@ -104,20 +105,38 @@ export class AndroidManage {
             return { device: deviceInfo, installed: true, output: pmOut };
         }
         catch (e) {
-            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e) };
+            // gather diagnostics for attempted adb operations
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            const installDiag = execAdbWithDiagnostics(['install', '-r', apkToInstall], deviceId);
+            const pushDiag = execAdbWithDiagnostics(['push', apkToInstall, remotePath], deviceId);
+            const pmDiag = execAdbWithDiagnostics(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } };
         }
     }
     async startApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-        return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+        try {
+            await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+        }
+        catch (e) {
+            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 };
+        }
     }
     async terminateApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
-        return { device: deviceInfo, appTerminated: true };
+        try {
+            await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: true };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
     async restartApp(appId, deviceId) {
         await this.terminateApp(appId, deviceId);
@@ -131,7 +150,13 @@ export class AndroidManage {
     async resetAppData(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
-        return { device: deviceInfo, dataCleared: output === 'Success' };
+        try {
+            const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: output === 'Success' };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
 }

package/dist/android/observe.js

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { XMLParser } from "fast-xml-parser";
-import { ADB, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js";
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js";
 import { createWriteStream } from "fs";
 import { promises as fsPromises } from "fs";
 import path from "path";
@@ -67,7 +67,7 @@ export class AndroidObserve {
             };
         }
         catch (e) {
-            const errorMessage = `Failed to get UI tree. ADB Path: '${ADB}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+            const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
             return {
                 device: deviceInfo,
@@ -115,7 +115,7 @@ export class AndroidObserve {
             // Need to construct ADB args manually since spawn handles it
             const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
             // Using spawn for screencap as well to ensure consistent process handling
-            const child = spawn(ADB, args);
+            const child = spawn(getAdbCmd(), args);
             const chunks = [];
             let stderr = '';
             child.stdout.on('data', (chunk) => {
@@ -245,7 +245,7 @@ export class AndroidObserve {
                 activeLogStreams.delete(sessionId);
             }
             const args = ['logcat', `--pid=${pid}`, filter];
-            const proc = spawn(ADB, args);
+            const proc = spawn(getAdbCmd(), args);
             const tmpDir = process.env.TMPDIR || '/tmp';
             const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`);
             const stream = createWriteStream(file, { flags: 'a' });

package/dist/android/utils.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import { detectJavaHome } from '../utils/java.js';
-export const ADB = process.env.ADB_PATH || 'adb';
+export function getAdbCmd() { return process.env.ADB_PATH || 'adb'; }
 /**
  * Prepare Gradle execution options for building an Android project.
  * Returns execCmd (wrapper or gradle), base gradleArgs array, and spawn options including env.
@@ -72,7 +72,7 @@ export function execAdb(args, deviceId, options = {}) {
         // Extract timeout from options if present, otherwise pass options to spawn
         const { timeout: customTimeout, ...spawnOptions } = options;
         // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
-        const child = spawn(ADB, adbArgs, spawnOptions);
+        const child = spawn(getAdbCmd(), adbArgs, spawnOptions);
         let stdout = '';
         let stderr = '';
         if (child.stdout) {
@@ -112,7 +112,7 @@ export function spawnAdb(args, deviceId, options = {}) {
     const adbArgs = getAdbArgs(args, deviceId);
     return new Promise((resolve, reject) => {
         const { timeout: customTimeout, ...spawnOptions } = options;
-        const child = spawn(ADB, adbArgs, spawnOptions);
+        const child = spawn(getAdbCmd(), adbArgs, spawnOptions);
         let stdout = '';
         let stderr = '';
         if (child.stdout)

package/dist/cli/idb/check-idb.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process';
+import { main as installMain } from './install-idb.js';
+import { getIdbCmd, isIDBInstalled } from './idb-helper.js';
+function which(cmd) {
+    try {
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0 && r.stdout)
+            return r.stdout.toString().trim();
+    }
+    catch { }
+    try {
+        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+function print(...args) {
+    console.log(...args);
+}
+async function runInstaller() {
+    try {
+        // prefer invoking the TS script via npx/tsx to ensure environment
+        const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null;
+        if (runner) {
+            const args = runner === 'npx' ? ['tsx', './src/cli/idb/install-idb.ts'] : ['./src/cli/idb/install-idb.ts'];
+            const res = spawnSync(runner, args, { stdio: 'inherit' });
+            return typeof res.status === 'number' ? res.status === 0 : false;
+        }
+        // fallback: attempt to import and run the installer directly (may rely on ts-node/tsx)
+        try {
+            // call the exported main; it returns a promise
+            await installMain();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    catch (e) {
+        console.error('Failed to run installer:', e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+try {
+    print('PATH=', process.env.PATH);
+    const idb = process.env.IDB_PATH || getIdbCmd();
+    print('idb:', idb);
+    if (idb && isIDBInstalled()) {
+        try {
+            print('idb --version:', execSync(`${idb} --version`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+        }
+        catch (e) {
+            print('idb --version: (failed)', e instanceof Error ? e.message : String(e));
+        }
+        const companion = which('idb_companion');
+        print('which idb_companion:', companion);
+        if (companion)
+            try {
+                print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+            }
+            catch (e) {
+                print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e));
+            }
+        process.exit(0);
+    }
+    print('idb not found or not responding');
+    const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true';
+    if (auto) {
+        print('MCP_AUTO_INSTALL_IDB=true, attempting installer...');
+        const ok = await runInstaller();
+        if (ok)
+            process.exit(0);
+        print('Installer failed or did not produce idb');
+        process.exit(2);
+    }
+    print('Set MCP_AUTO_INSTALL_IDB=true to attempt automatic installation (CI-friendly).');
+    process.exit(2);
+}
+catch (e) {
+    console.error('idb healthcheck failed:', e instanceof Error ? e.message : String(e));
+    process.exit(2);
+}

package/dist/cli/idb/idb-helper.js

@@ -0,0 +1,91 @@
+import { execSync, spawnSync } from 'child_process';
+import fs from 'fs';
+export function getConfiguredIdbPath() {
+    if (process.env.MCP_IDB_PATH)
+        return process.env.MCP_IDB_PATH;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    const cfgPaths = [
+        process.env.MCP_CONFIG_PATH || (process.env.HOME ? `${process.env.HOME}/.mcp/config.json` : ''),
+        `${process.cwd()}/mcp.config.json`
+    ];
+    for (const p of cfgPaths) {
+        if (!p)
+            continue;
+        try {
+            if (fs.existsSync(p)) {
+                const raw = fs.readFileSync(p, 'utf8');
+                const json = JSON.parse(raw);
+                if (json) {
+                    if (json.idbPath)
+                        return json.idbPath;
+                    if (json.IDB_PATH)
+                        return json.IDB_PATH;
+                }
+            }
+        }
+        catch { }
+    }
+    return undefined;
+}
+export function commandWhich(cmd) {
+    try {
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0 && r.stdout)
+            return r.stdout.toString().trim();
+    }
+    catch { }
+    try {
+        const p = execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p)
+            return p;
+    }
+    catch { }
+    return null;
+}
+export function getIdbCmd() {
+    const cfg = getConfiguredIdbPath();
+    if (cfg)
+        return cfg;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    // Prefer command -v/which
+    const found = commandWhich('idb');
+    if (found)
+        return found;
+    // Common locations
+    const common = [
+        process.env.HOME ? `${process.env.HOME}/Library/Python/3.9/bin/idb` : '',
+        process.env.HOME ? `${process.env.HOME}/Library/Python/3.10/bin/idb` : '',
+        '/opt/homebrew/bin/idb',
+        '/usr/local/bin/idb'
+    ];
+    for (const c of common) {
+        if (!c)
+            continue;
+        try {
+            execSync(`test -x ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+            return c;
+        }
+        catch { }
+    }
+    return null;
+}
+export function isIDBInstalled() {
+    const cmd = getIdbCmd();
+    if (!cmd)
+        return false;
+    try {
+        // command -v <cmd>
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0)
+            return true;
+    }
+    catch { }
+    try {
+        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+        return true;
+    }
+    catch { }
+    return false;
+}

package/dist/cli/idb/install-idb.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawnSync } from 'child_process';
+import readline from 'readline';
+import { getIdbCmd, isIDBInstalled, commandWhich } from './idb-helper.js';
+const IDB_PKG = 'fb-idb';
+function runCommand(cmd, args) {
+    const res = spawnSync(cmd, args, { stdio: 'inherit' });
+    return typeof res.status === 'number' ? res.status : 1;
+}
+async function confirm(prompt) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${prompt} (y/N): `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase() === 'y');
+        });
+    });
+}
+async function main() {
+    try {
+        const idbFromEnv = process.env.IDB_PATH;
+        const existing = idbFromEnv || getIdbCmd();
+        if (existing && isIDBInstalled()) {
+            console.log('idb already available at:', existing);
+            process.exit(0);
+        }
+        const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true' || process.env.CI === 'true';
+        if (!auto) {
+            const ok = await confirm('idb not found. Attempt to install fb-idb now?');
+            if (!ok) {
+                console.log('Aborting install; set MCP_AUTO_INSTALL_IDB=true to auto-install in CI or non-interactive environments.');
+                process.exit(2);
+            }
+        }
+        else {
+            console.log('Auto-install enabled (MCP_AUTO_INSTALL_IDB=true or CI=true)');
+        }
+        const attempts = [];
+        if (commandWhich('pipx'))
+            attempts.push({ name: 'pipx', cmd: 'pipx', args: ['install', IDB_PKG] });
+        if (commandWhich('pip') || commandWhich('python3'))
+            attempts.push({ name: 'pip', cmd: commandWhich('pip') ? 'pip' : 'python3', args: commandWhich('pip') ? ['install', '--user', IDB_PKG] : ['-m', 'pip', 'install', '--user', IDB_PKG] });
+        // Add brew as a fallback on macOS if present (best-effort)
+        if (process.platform === 'darwin' && commandWhich('brew')) {
+            attempts.push({ name: 'brew', cmd: 'brew', args: ['install', 'idb'] });
+        }
+        if (attempts.length === 0) {
+            console.error('No installer tool (pipx/pip/brew) detected. Please install pipx or pip and re-run.');
+            process.exit(2);
+        }
+        for (const a of attempts) {
+            console.log(`Attempting install with ${a.name}: ${a.cmd} ${a.args.join(' ')}`);
+            try {
+                const code = runCommand(a.cmd, a.args);
+                if (code !== 0) {
+                    console.warn(`${a.name} install exited with code ${code}`);
+                }
+            }
+            catch (e) {
+                console.warn(`${a.name} install failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            const found = commandWhich('idb') || commandWhich('command -v idb');
+            if (found) {
+                console.log('idb installed at:', found);
+                process.exit(0);
+            }
+        }
+        console.error('idb was not installed by any installer tried. Please install fb-idb manually and re-run healthcheck.');
+        process.exit(2);
+    }
+    catch (e) {
+        console.error('Installer failed:', e instanceof Error ? e.message : String(e));
+        process.exit(2);
+    }
+}
+const scriptPath = new URL(import.meta.url).pathname;
+if (scriptPath === process.argv[1]) {
+    main().catch(e => { console.error('Installer failed:', e instanceof Error ? e.message : String(e)); process.exit(2); });
+}
+export { main };

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { getIdbCmd, isIDBInstalled, commandWhich } from '../idb/idb-helper.js';
+async function exists(p) {
+    try {
+        await fs.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findFirst(root, patterns, maxDepth = 4) {
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length) {
+        const { dir, depth } = queue.shift();
+        try {
+            console.error('DEBUG findFirst: reading dir', dir, 'depth', depth);
+            const ents = await fs.promises.readdir(dir, { withFileTypes: true });
+            console.error('DEBUG findFirst: entries', ents.map(e => e.name));
+            for (const e of ents) {
+                const full = path.join(dir, e.name);
+                for (const p of patterns) {
+                    if (e.name.endsWith(p)) {
+                        console.error('DEBUG findFirst: matched', full);
+                        return full;
+                    }
+                }
+                if (e.isDirectory() && depth < maxDepth)
+                    queue.push({ dir: full, depth: depth + 1 });
+            }
+        }
+        catch (err) {
+            console.error('DEBUG findFirst: read failed for', dir, err);
+            // ignore
+        }
+    }
+    return null;
+}
+function startCompanionIfNeeded(companionPath, udid) {
+    if (!companionPath || !udid)
+        return { started: false, error: 'missing companion or udid' };
+    try {
+        const child = spawn(companionPath, ['--udid', udid], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return { started: true };
+    }
+    catch (e) {
+        return { started: false, error: e.message };
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    let projectArg;
+    let udid;
+    let startCompanion = false;
+    let kmpBuild = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--project' && args[i + 1]) {
+            projectArg = args[i + 1];
+            i++;
+        }
+        else if (a === '--udid' && args[i + 1]) {
+            udid = args[i + 1];
+            i++;
+        }
+        else if (a === '--start-companion')
+            startCompanion = true;
+        else if (!projectArg)
+            projectArg = a;
+    }
+    const cwd = process.cwd();
+    const projectRoot = projectArg ? path.resolve(projectArg) : cwd;
+    // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
+    let projectFile = null;
+    try {
+        const stat = await fs.promises.stat(projectRoot);
+        if (stat.isFile() && (projectRoot.endsWith('.xcodeproj') || projectRoot.endsWith('.xcworkspace'))) {
+            projectFile = projectRoot;
+        }
+    }
+    catch {
+        // ignore
+    }
+    // detect project if not a direct file
+    if (!projectFile) {
+        const projectFound = await exists(projectRoot);
+        if (projectFound) {
+            projectFile = await findFirst(projectRoot, ['.xcworkspace', '.xcodeproj'], 2);
+        }
+        else {
+            // attempt to find under cwd
+            projectFile = await findFirst(cwd, ['.xcworkspace', '.xcodeproj'], 3);
+        }
+    }
+    // 2) KMP Shared.framework detection (search for *.framework named Shared.framework)
+    let kmpFramework = null;
+    const projectSearchRoot = projectFile ? (fs.existsSync(projectFile) && fs.lstatSync(projectFile).isDirectory() ? projectFile : path.dirname(projectFile)) : cwd;
+    kmpFramework = await findFirst(projectSearchRoot, ['Shared.framework'], 5);
+    if (!kmpFramework)
+        kmpFramework = await findFirst(cwd, ['Shared.framework'], 6);
+    // 3) idb detection
+    const idbPath = getIdbCmd();
+    const idbAvailable = idbPath ? isIDBInstalled() : false;
+    // 4) idb_companion
+    const companionPath = commandWhich('idb_companion');
+    const companionAvailable = !!companionPath;
+    const suggestions = [];
+    if (!projectFile)
+        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
+    if (!kmpFramework)
+        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
+    if (!idbAvailable)
+        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
+    if (!companionAvailable)
+        suggestions.push('Install idb_companion and ensure it is in PATH');
+    const result = {
+        ok: !!projectFile && !!idbAvailable,
+        project: {
+            root: projectRoot,
+            found: !!projectFile,
+            projectFile: projectFile
+        },
+        kmp: {
+            found: !!kmpFramework,
+            path: kmpFramework,
+            build: kmpBuild
+        },
+        idb: {
+            cmd: idbPath,
+            installed: idbAvailable
+        },
+        idb_companion: {
+            cmd: companionPath,
+            installed: companionAvailable
+        },
+        suggestions
+    };
+    if (startCompanion && udid) {
+        const started = startCompanionIfNeeded(companionPath, udid);
+        result.idb_companion.start = started;
+        if (started.started)
+            result.ok = result.ok && true;
+    }
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 2);
+}
+main().catch(e => {
+    // Report structured error on stdout (avoid noisy stderr in normal runs)
+    console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2));
+    process.exit(2);
+});

package/dist/cli/ios/run-ios-smoke.js

@@ -0,0 +1,28 @@
+import { iOSObserve } from '../../ios/observe.js';
+import { iOSManage } from '../../ios/manage.js';
+async function main() {
+    const appId = process.argv[2] || 'com.apple.springboard';
+    const deviceId = 'booted';
+    const obs = new iOSObserve();
+    const manage = new iOSManage();
+    try {
+        console.log('[1] startApp ->', appId);
+        const start = await manage.startApp(appId, deviceId);
+        console.log('start result:', start);
+        console.log('[2] captureScreenshot');
+        const shot = await obs.captureScreenshot(deviceId);
+        console.log('screenshot OK? size:', shot && shot.screenshot ? shot.screenshot.length : 0);
+        console.log('[3] getLogs');
+        const logs = await obs.getLogs(appId, undefined);
+        console.log('logs count:', logs.logCount);
+        console.log('[4] terminateApp');
+        const term = await manage.terminateApp(appId, deviceId);
+        console.log('terminate:', term);
+        console.log('SMOKE OK');
+    }
+    catch (err) {
+        console.error('SMOKE ERROR:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+main();