mobile-debug-mcp 0.4.0 → 0.6.0

package/dist/ios/utils.js

@@ -0,0 +1,114 @@
+import { execFile, spawn } from "child_process";
+export const XCRUN = process.env.XCRUN_PATH || "xcrun";
+export const IDB = "idb";
+// Validate bundle ID to prevent any potential injection or invalid characters
+export function validateBundleId(bundleId) {
+    if (!bundleId)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+export function execCommand(args, deviceId = "booted") {
+    return new Promise((resolve, reject) => {
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(XCRUN, args);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        const timeoutMs = args.includes('log') ? 10000 : 5000; // 10s for logs, 5s for others
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+function parseRuntimeName(runtime) {
+    // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
+    try {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1]; // e.g. "iOS-17-0"
+        // Split by hyphen to separate OS from version numbers
+        // e.g. "iOS-17-0" -> ["iOS", "17", "0"]
+        const segments = lastPart.split('-');
+        if (segments.length > 1) {
+            const os = segments[0]; // "iOS"
+            const version = segments.slice(1).join('.'); // "17.0"
+            return `${os} ${version}`;
+        }
+        return lastPart;
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function getIOSDeviceMetadata(deviceId = "booted") {
+    return new Promise((resolve) => {
+        // If deviceId is provided (and not "booted"), we could try to list just that device.
+        // But listing all booted devices is usually fine to find the one we want or just one.
+        // Let's stick to listing all and filtering if needed, or just return basic info if we can't find it.
+        execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            // Default fallback
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                // Find the device
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch (error) {
+                resolve(fallback);
+            }
+        });
+    });
+}

package/dist/ios.js

@@ -1,21 +1,344 @@
-import { exec } from "child_process";
-export function startIOSApp(bundleId) {
+import { execFile, spawn } from "child_process";
+import { promises as fs } from "fs";
+const XCRUN = process.env.XCRUN_PATH || "xcrun";
+const IDB = "idb";
+// Validate bundle ID to prevent any potential injection or invalid characters
+function validateBundleId(bundleId) {
+    if (!bundleId)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
-        exec(`xcrun simctl launch booted ${bundleId}`, (err, stdout, stderr) => {
-            if (err)
-                reject(stderr);
-            else
-                resolve(stdout);
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(XCRUN, args);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        const timeoutMs = args.includes('log') ? 10000 : 5000; // 10s for logs, 5s for others
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
         });
     });
 }
-export function getIOSLogs() {
-    return new Promise((resolve, reject) => {
-        exec(`xcrun simctl spawn booted log show --style syslog --last 1m`, (err, stdout, stderr) => {
-            if (err)
-                reject(stderr);
-            else
-                resolve(stdout);
+function parseRuntimeName(runtime) {
+    // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
+    try {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1];
+        return lastPart.replace(/-/g, ' ').replace('iOS ', 'iOS '); // Keep iOS prefix
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function getIOSDeviceMetadata(deviceId = "booted") {
+    return new Promise((resolve) => {
+        // If deviceId is provided (and not "booted"), we could try to list just that device.
+        // But listing all booted devices is usually fine to find the one we want or just one.
+        // Let's stick to listing all and filtering if needed, or just return basic info if we can't find it.
+        execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            // Default fallback
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                // Find the device
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch (error) {
+                resolve(fallback);
+            }
+        });
+    });
+}
+export async function startIOSApp(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Simulate launch time and appStarted for demonstration
+    return {
+        device,
+        appStarted: !!result.output,
+        launchTimeMs: 1000,
+    };
+}
+export async function terminateIOSApp(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    return {
+        device,
+        appTerminated: true
+    };
+}
+export async function restartIOSApp(bundleId, deviceId = "booted") {
+    // terminateIOSApp already validates bundleId
+    await terminateIOSApp(bundleId, deviceId);
+    const startResult = await startIOSApp(bundleId, deviceId);
+    return {
+        device: startResult.device,
+        appRestarted: startResult.appStarted,
+        launchTimeMs: startResult.launchTimeMs
+    };
+}
+export async function resetIOSAppData(bundleId, deviceId = "booted") {
+    validateBundleId(bundleId);
+    await terminateIOSApp(bundleId, deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Get data container path
+    const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId);
+    const dataPath = containerResult.output.trim();
+    if (!dataPath) {
+        throw new Error(`Could not find data container for ${bundleId}`);
+    }
+    // Clear contents of Library and Documents
+    try {
+        const libraryPath = `${dataPath}/Library`;
+        const documentsPath = `${dataPath}/Documents`;
+        const tmpPath = `${dataPath}/tmp`;
+        await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => { });
+        // Re-create empty directories as they are expected by apps
+        await fs.mkdir(libraryPath, { recursive: true }).catch(() => { });
+        await fs.mkdir(documentsPath, { recursive: true }).catch(() => { });
+        await fs.mkdir(tmpPath, { recursive: true }).catch(() => { });
+        return {
+            device,
+            dataCleared: true
+        };
+    }
+    catch (err) {
+        throw new Error(`Failed to clear data for ${bundleId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function getIOSLogs(appId, deviceId = "booted") {
+    // If appId is provided, use predicate filtering
+    // Note: execFile passes args directly, so we don't need shell escaping for the predicate string itself,
+    // but we do need to construct the predicate correctly for log show.
+    const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m'];
+    if (appId) {
+        validateBundleId(appId);
+        args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`);
+    }
+    const result = await execCommand(args, deviceId);
+    const device = await getIOSDeviceMetadata(deviceId);
+    const logs = result.output ? result.output.split('\n') : [];
+    return {
+        device,
+        logs,
+        logCount: logs.length,
+    };
+}
+export async function captureIOSScreenshot(deviceId = "booted") {
+    const device = await getIOSDeviceMetadata(deviceId);
+    const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`;
+    try {
+        // 1. Capture screenshot to temp file
+        await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
+        // 2. Read file as base64
+        const buffer = await fs.readFile(tmpFile);
+        const base64 = buffer.toString('base64');
+        // 3. Clean up
+        await fs.rm(tmpFile).catch(() => { });
+        return {
+            device,
+            screenshot: base64,
+            // Default resolution since we can't easily parse it without extra libs
+            // Clients will read the real dimensions from the PNG header anyway
+            resolution: { width: 0, height: 0 },
+        };
+    }
+    catch (err) {
+        // Ensure cleanup happens even on error
+        await fs.rm(tmpFile).catch(() => { });
+        throw new Error(`Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function parseIDBFrame(frame) {
+    if (!frame)
+        return [0, 0, 0, 0];
+    const x = Number(frame.x || 0);
+    const y = Number(frame.y || 0);
+    const w = Number(frame.width || frame.w || 0);
+    const h = Number(frame.height || frame.h || 0);
+    return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+}
+function traverseIDBNode(node, elements, parentIndex = -1) {
+    if (!node)
+        return -1;
+    // Prefer standard keys, fallback to alternatives
+    const type = node.AXElementType || node.type || "unknown";
+    const label = node.AXLabel || node.label || null;
+    const value = node.AXValue || null;
+    const frame = node.AXFrame || node.frame;
+    const element = {
+        text: label,
+        contentDescription: value, // iOS uses Value/Label differently than Android but this maps roughly
+        type: type,
+        resourceId: node.AXUniqueId || null,
+        clickable: (node.AXTraits || []).includes("UIAccessibilityTraitButton") || type === "Button",
+        enabled: true, // idb usually returns enabled elements
+        visible: true,
+        bounds: parseIDBFrame(frame),
+    };
+    if (parentIndex !== -1) {
+        element.parentId = parentIndex;
+    }
+    elements.push(element);
+    const currentIndex = elements.length - 1;
+    const childrenIndices = [];
+    if (node.children && Array.isArray(node.children)) {
+        for (const child of node.children) {
+            const childIndex = traverseIDBNode(child, elements, currentIndex);
+            if (childIndex !== -1) {
+                childrenIndices.push(childIndex);
+            }
+        }
+    }
+    if (childrenIndices.length > 0) {
+        elements[currentIndex].children = childrenIndices;
+    }
+    return currentIndex;
+}
+// Check if IDB is installed
+async function isIDBInstalled() {
+    return new Promise((resolve) => {
+        const child = spawn(IDB, ['--version']);
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
+    });
+}
+export async function getIOSUITree(deviceId = "booted") {
+    const device = await getIOSDeviceMetadata(deviceId);
+    // idb is required
+    const idbExists = await isIDBInstalled();
+    if (!idbExists) {
+        return {
+            device,
+            screen: "",
+            resolution: { width: 0, height: 0 },
+            elements: [],
+            error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
+        };
+    }
+    return new Promise((resolve) => {
+        // idb ui describe --udid <uuid> --json
+        // If deviceId is 'booted', try to resolve it to a UDID because idb often needs explicit target
+        const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+        const args = ['ui', 'describe', '--json'];
+        if (targetUdid) {
+            args.push('--udid', targetUdid);
+        }
+        const child = spawn(IDB, args);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => stdout += data.toString());
+        child.stderr.on('data', (data) => stderr += data.toString());
+        child.on('error', (err) => {
+            resolve({
+                device,
+                screen: "",
+                resolution: { width: 0, height: 0 },
+                elements: [],
+                error: `Failed to execute idb: ${err.message}`
+            });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width: 0, height: 0 },
+                    elements: [],
+                    error: `idb failed (code ${code}): ${stderr.trim()}`
+                });
+                return;
+            }
+            try {
+                const json = JSON.parse(stdout);
+                const elements = [];
+                // idb return object usually has 'children' at root or is the root
+                const root = json;
+                traverseIDBNode(root, elements);
+                // Infer resolution from root element if possible (usually the Window/Application frame)
+                let width = 0;
+                let height = 0;
+                if (elements.length > 0) {
+                    const rootBounds = elements[0].bounds;
+                    width = rootBounds[2] - rootBounds[0];
+                    height = rootBounds[3] - rootBounds[1];
+                }
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width, height },
+                    elements
+                });
+            }
+            catch (e) {
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width: 0, height: 0 },
+                    elements: [],
+                    error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
+                });
+            }
         });
     });
 }