mobile-debug-mcp 0.14.0 → 0.16.0

package/dist/android/interact.js

@@ -1,6 +1,6 @@
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
-import { AndroidObserve } from "./observe.js";
-import { scrollToElementShared } from "../tools/scroll_to_element.js";
+import { AndroidObserve } from "../observe/index.js";
+import { scrollToElementShared } from "../intera../interact/shared/scroll_to_element.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
     async waitForElement(text, timeout, deviceId) {

package/dist/android/observe.js

@@ -4,6 +4,7 @@ import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, get
 import { createWriteStream } from "fs";
 import { promises as fsPromises } from "fs";
 import path from "path";
+import { computeScreenFingerprint } from "../intera../interact/shared/fingerprint.js";
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
@@ -229,6 +230,18 @@ export class AndroidObserve {
             };
         }
     }
+    async getScreenFingerprint(deviceId) {
+        try {
+            const tree = await this.getUITree(deviceId);
+            if (!tree || tree.error)
+                return { fingerprint: null, error: tree.error };
+            const current = await this.getCurrentScreen(deviceId).catch(() => null);
+            return computeScreenFingerprint(tree, current, 'android', 50);
+        }
+        catch (e) {
+            return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
     async startLogStream(packageName, level = 'error', deviceId, sessionId = 'default') {
         try {
             const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '');

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

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSManage } from '../../ios/manage.js';
+import { iOSObserve } from '../../observe/index.js';
+import { iOSManage } from '../../manage/index.js';
 async function main() {
     const appId = process.argv[2] || 'com.apple.springboard';
     const deviceId = 'booted';

package/dist/cli/ios/run-ios-ui-tree-tap.js

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSInteract } from '../../ios/interact.js';
+import { iOSObserve } from '../../observe/index.js';
+import { iOSInteract } from '../../interact/index.js';
 async function main() {
     const deviceId = 'booted';
     const obs = new iOSObserve();

package/dist/interact/android.js

@@ -0,0 +1,91 @@
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js";
+import { AndroidObserve } from "../observe/index.js";
+import { scrollToElementShared } from "../utils/ui/index.js";
+export class AndroidInteract {
+    observe = new AndroidObserve();
+    async waitForElement(text, timeout, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const tree = await this.observe.getUITree(deviceId);
+                if (tree.error) {
+                    return { device: deviceInfo, found: false, error: tree.error };
+                }
+                const element = tree.elements.find(e => e.text === text);
+                if (element) {
+                    return { device: deviceInfo, found: true, element };
+                }
+            }
+            catch (e) {
+                // Ignore errors during polling and retry
+                console.error("Error polling UI tree:", e);
+            }
+            const elapsed = Date.now() - startTime;
+            const remaining = timeout - elapsed;
+            if (remaining <= 0)
+                break;
+            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
+        }
+        return { device: deviceInfo, found: false };
+    }
+    async tap(x, y, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId);
+            return { device: deviceInfo, success: true, x, y };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async swipe(x1, y1, x2, y2, duration, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId);
+            return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async typeText(text, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // Encode spaces as %s to ensure proper input handling by adb shell input text
+            const encodedText = text.replace(/\s/g, '%s');
+            // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+            await execAdb(['shell', 'input', 'text', encodedText], deviceId);
+            return { device: deviceInfo, success: true, text };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async pressBack(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId);
+            return { device: deviceInfo, success: true };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async scrollToElement(selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId) {
+        return await scrollToElementShared({
+            selector,
+            direction,
+            maxScrolls,
+            scrollAmount,
+            deviceId,
+            fetchTree: async () => await this.observe.getUITree(deviceId),
+            swipe: async (x1, y1, x2, y2, duration, devId) => await this.swipe(x1, y1, x2, y2, duration, devId)
+        });
+    }
+}

package/dist/interact/index.js

@@ -0,0 +1,76 @@
+import { AndroidInteract } from './android.js';
+import { iOSInteract } from './ios.js';
+export { AndroidInteract, iOSInteract };
+import { resolveTargetDevice } from '../utils/resolve-device.js';
+import { ToolsObserve } from '../observe/index.js';
+export class ToolsInteract {
+    static async getInteractionService(platform, deviceId) {
+        const effectivePlatform = platform || 'android';
+        const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
+        const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
+        return { interact: interact, resolved, platform: effectivePlatform };
+    }
+    static async waitForElementHandler({ platform, text, timeout, deviceId }) {
+        const effectiveTimeout = timeout ?? 10000;
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.waitForElement(text, effectiveTimeout, resolved.id);
+    }
+    static async tapHandler({ platform, x, y, deviceId }) {
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.tap(x, y, resolved.id);
+    }
+    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id);
+    }
+    static async typeTextHandler({ text, deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidInteract().typeText(text, resolved.id);
+    }
+    static async pressBackHandler({ deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidInteract().pressBack(resolved.id);
+    }
+    static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }) {
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
+    }
+    static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
+        const start = Date.now();
+        let lastFingerprint = null;
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                const fp = res?.fingerprint ?? null;
+                if (fp === null || fp === undefined) {
+                    lastFingerprint = null;
+                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                    continue;
+                }
+                lastFingerprint = fp;
+                if (fp !== previousFingerprint) {
+                    // Stability confirmation
+                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                    try {
+                        const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const confirmFp = confirmRes?.fingerprint ?? null;
+                        if (confirmFp === fp) {
+                            return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start };
+                        }
+                        lastFingerprint = confirmFp;
+                        continue;
+                    }
+                    catch {
+                        // ignore and continue polling
+                        continue;
+                    }
+                }
+            }
+            catch {
+                // ignore transient errors
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
+    }
+}

package/dist/interact/ios.js

@@ -0,0 +1,120 @@
+import { spawn } from "child_process";
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
+import { iOSObserve } from "../observe/index.js";
+import { scrollToElementShared } from "../utils/ui/index.js";
+export class iOSInteract {
+    observe = new iOSObserve();
+    async waitForElement(text, timeout, deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const tree = await this.observe.getUITree(deviceId);
+                if (tree.error) {
+                    return { device, found: false, error: tree.error };
+                }
+                const element = tree.elements.find(e => e.text === text);
+                if (element) {
+                    return { device, found: true, element };
+                }
+            }
+            catch (e) {
+                // Ignore errors during polling and retry
+                console.error("Error polling UI tree:", e);
+            }
+            const elapsed = Date.now() - startTime;
+            const remaining = timeout - elapsed;
+            if (remaining <= 0)
+                break;
+            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
+        }
+        return { device, found: false };
+    }
+    async tap(x, y, deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        // Use shared helper to detect idb
+        const idbExists = await isIDBInstalled();
+        if (!idbExists) {
+            return {
+                device,
+                success: false,
+                x,
+                y,
+                error: "iOS tap requires 'idb' (iOS Device Bridge)."
+            };
+        }
+        try {
+            const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+            const args = ['ui', 'tap', x.toString(), y.toString()];
+            if (targetUdid) {
+                args.push('--udid', targetUdid);
+            }
+            await new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args);
+                let stderr = '';
+                proc.stderr.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`idb ui tap failed: ${stderr}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            return { device, success: true, x, y };
+        }
+        catch (e) {
+            return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async swipe(x1, y1, x2, y2, duration, deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        // Use shared helper to detect idb
+        const idbExists = await isIDBInstalled();
+        if (!idbExists) {
+            return {
+                device,
+                success: false,
+                start: [x1, y1],
+                end: [x2, y2],
+                duration,
+                error: "iOS swipe requires 'idb' (iOS Device Bridge)."
+            };
+        }
+        try {
+            const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+            // idb 'ui swipe' does not accept a duration parameter; use coordinates only
+            const args = ['ui', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString()];
+            if (targetUdid) {
+                args.push('--udid', targetUdid);
+            }
+            await new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args);
+                let stderr = '';
+                proc.stderr.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`idb ui swipe failed: ${stderr}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
+        }
+        catch (e) {
+            return { device, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async scrollToElement(selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId = 'booted') {
+        return await scrollToElementShared({
+            selector,
+            direction,
+            maxScrolls,
+            scrollAmount,
+            deviceId,
+            fetchTree: async () => await this.observe.getUITree(deviceId),
+            swipe: async (x1, y1, x2, y2, duration, devId) => await this.swipe(x1, y1, x2, y2, duration, devId)
+        });
+    }
+}

package/dist/interact/shared/fingerprint.js

@@ -0,0 +1 @@
+export { computeScreenFingerprint } from '../../utils/ui/index.js';

package/dist/interact/shared/scroll_to_element.js

@@ -0,0 +1 @@
+export { scrollToElementShared } from '../../utils/ui/index.js';

package/dist/ios/interact.js

@@ -1,7 +1,7 @@
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js";
-import { iOSObserve } from "./observe.js";
-import { scrollToElementShared } from "../tools/scroll_to_element.js";
+import { iOSObserve } from "../observe/index.js";
+import { scrollToElementShared } from "../intera../interact/shared/scroll_to_element.js";
 export class iOSInteract {
     observe = new iOSObserve();
     async waitForElement(text, timeout, deviceId = "booted") {

package/dist/ios/observe.js

@@ -4,6 +4,7 @@ import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcru
 import { createWriteStream, promises as fsPromises } from 'fs';
 import path from 'path';
 import { parseLogLine } from '../android/utils.js';
+import { computeScreenFingerprint } from '../intera../interact/shared/fingerprint.js';
 // --- Helper Functions Specific to Observe ---
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 function parseIDBFrame(frame) {
@@ -237,6 +238,17 @@ export class iOSObserve {
             };
         }
     }
+    async getScreenFingerprint(deviceId = 'booted') {
+        try {
+            const tree = await this.getUITree(deviceId);
+            if (!tree || tree.error)
+                return { fingerprint: null, error: tree && tree.error };
+            return computeScreenFingerprint(tree, null, 'ios', 50);
+        }
+        catch (e) {
+            return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
     // --- Log stream methods ---
     async startLogStream(bundleId, deviceId = 'booted', sessionId = 'default') {
         try {

package/dist/manage/android.js

@@ -0,0 +1,162 @@
+import { promises as fs } from 'fs';
+import { spawn } from 'child_process';
+import path from 'path';
+import { existsSync } from 'fs';
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js';
+import { execAdbWithDiagnostics } from '../utils/diagnostics.js';
+import { detectJavaHome } from '../utils/java.js';
+export class AndroidManage {
+    async build(projectPath, _variant) {
+        void _variant;
+        try {
+            // Always use the shared prepareGradle utility for consistent env/setup
+            const { execCmd, gradleArgs, spawnOpts } = await (await import('../utils/android/utils.js')).prepareGradle(projectPath);
+            await new Promise((resolve, reject) => {
+                const proc = spawn(execCmd, gradleArgs, spawnOpts);
+                let stderr = '';
+                proc.stderr?.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(stderr || `Gradle failed with code ${code}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            const apk = await findApk(projectPath);
+            if (!apk)
+                return { error: 'Could not find APK after build' };
+            return { artifactPath: apk };
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async installApp(apkPath, deviceId) {
+        const metadata = await getAndroidDeviceMetadata('', deviceId);
+        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 = Object.assign({}, 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(() => { });
+                    spawnOpts.shell = false;
+                }
+                else
+                    spawnOpts.shell = true;
+                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;
+            }
+            try {
+                const res = await spawnAdb(['install', '-r', apkToInstall], deviceId);
+                if (res.code === 0) {
+                    return { device: deviceInfo, installed: true, output: res.stdout };
+                }
+            }
+            catch (e) {
+                console.debug('[android-run] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e));
+            }
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            await execAdb(['push', apkToInstall, remotePath], deviceId);
+            const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            try {
+                await execAdb(['shell', 'rm', remotePath], deviceId);
+            }
+            catch { }
+            return { device: deviceInfo, installed: true, output: pmOut };
+        }
+        catch (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);
+        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);
+        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);
+        const startResult = await this.startApp(appId, deviceId);
+        return {
+            device: startResult.device,
+            appRestarted: startResult.appStarted,
+            launchTimeMs: startResult.launchTimeMs
+        };
+    }
+    async resetAppData(appId, deviceId) {
+        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        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 };
+        }
+    }
+}