mobile-debug-mcp 0.13.0 → 0.15.0

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 };
+        }
+    }
+}

package/dist/manage/index.js

@@ -0,0 +1,364 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js';
+import { AndroidManage } from './android.js';
+import { iOSManage } from './ios.js';
+import { findApk } from '../utils/android/utils.js';
+import { findAppBundle } from '../utils/ios/utils.js';
+import { execSync } from 'child_process';
+export { AndroidManage } from './android.js';
+export { iOSManage } from './ios.js';
+export async function detectProjectPlatform(projectPath) {
+    // Recursively scan up to a limited depth for platform markers to avoid mis-detection
+    async function scan(dir, depth = 3) {
+        const res = { ios: false, android: false };
+        try {
+            const ents = await fs.readdir(dir).catch(() => []);
+            for (const e of ents) {
+                if (e.endsWith('.xcworkspace') || e.endsWith('.xcodeproj'))
+                    res.ios = true;
+                if (e === 'gradlew' || e === 'build.gradle' || e === 'settings.gradle')
+                    res.android = true;
+                if (res.ios && res.android)
+                    return res;
+            }
+            if (depth <= 0)
+                return res;
+            for (const e of ents) {
+                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;
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return res;
+    }
+    try {
+        const stat = await fs.stat(projectPath).catch(() => null);
+        if (stat && stat.isDirectory()) {
+            const { ios: hasIos, android: hasAndroid } = await scan(projectPath, 3);
+            if (hasIos && !hasAndroid)
+                return 'ios';
+            if (hasAndroid && !hasIos)
+                return 'android';
+            if (hasIos && hasAndroid)
+                return 'ambiguous';
+            // no explicit markers found
+            return 'unknown';
+        }
+        else {
+            const ext = path.extname(projectPath).toLowerCase();
+            if (ext === '.apk')
+                return 'android';
+            if (ext === '.ipa' || ext === '.app')
+                return 'ios';
+            return 'unknown';
+        }
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export class ToolsManage {
+    static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }) {
+        const android = new AndroidManage();
+        // prepare gradle options via environment hints
+        if (typeof maxWorkers === 'number')
+            process.env.MCP_GRADLE_WORKERS = String(maxWorkers);
+        if (typeof gradleCache === 'boolean')
+            process.env.MCP_GRADLE_CACHE = gradleCache ? '1' : '0';
+        if (forceClean)
+            process.env.MCP_FORCE_CLEAN_ANDROID = '1';
+        const task = gradleTask || 'assembleDebug';
+        const artifact = await android.build(projectPath, task);
+        return artifact;
+    }
+    static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }) {
+        const ios = new iOSManage();
+        // Use provided options rather than env-only; still set env fallbacks for downstream tools
+        if (derivedDataPath)
+            process.env.MCP_DERIVED_DATA = derivedDataPath;
+        if (typeof buildJobs === 'number')
+            process.env.MCP_BUILD_JOBS = String(buildJobs);
+        if (forceClean)
+            process.env.MCP_FORCE_CLEAN_IOS = '1';
+        if (destinationUDID)
+            process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID;
+        const opts = {};
+        if (_workspace)
+            opts.workspace = _workspace;
+        if (_project)
+            opts.project = _project;
+        if (_scheme)
+            opts.scheme = _scheme;
+        if (destinationUDID)
+            opts.destinationUDID = destinationUDID;
+        if (derivedDataPath)
+            opts.derivedDataPath = derivedDataPath;
+        if (forceClean)
+            opts.forceClean = forceClean;
+        // prefer explicit xcodebuild path from env
+        if (process.env.XCODEBUILD_PATH)
+            opts.xcodeCmd = process.env.XCODEBUILD_PATH;
+        const artifact = await ios.build(projectPath, opts);
+        return artifact;
+    }
+    static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
+        // Prefer using flutter CLI when available; otherwise delegate to native subproject builders
+        const flutterCmd = process.env.FLUTTER_PATH || 'flutter';
+        // silence unused params
+        void _maxWorkers;
+        void _forceClean;
+        try {
+            // Check flutter presence without streaming output
+            execSync(`${flutterCmd} --version`, { stdio: 'ignore' });
+            if (!platform || platform === 'android') {
+                const mode = buildMode || 'debug';
+                try {
+                    const out = execSync(`${flutterCmd} build apk --${mode}`, { cwd: projectPath, encoding: 'utf8' });
+                    // Try to find built APK
+                    const apk = await findApk(path.join(projectPath));
+                    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}`);
+                }
+            }
+            if (!platform || platform === 'ios') {
+                const mode = buildMode || 'debug';
+                try {
+                    const out = execSync(`${flutterCmd} build ios --${mode} --no-codesign`, { cwd: projectPath, encoding: 'utf8' });
+                    const app = await findAppBundle(path.join(projectPath));
+                    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 (e) {
+            // If flutter CLI not available or command fails, fall back to native subprojects
+            // 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' };
+    }
+    static async build_react_native({ projectPath, platform, variant, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
+        // silence unused params
+        void _maxWorkers;
+        void _forceClean;
+        // React Native typically uses native subprojects. Delegate to Android/iOS builders.
+        if (!platform || platform === 'android') {
+            const androidDir = path.join(projectPath, 'android');
+            const android = new AndroidManage();
+            const artifact = await android.build(androidDir, variant || 'assembleDebug');
+            return artifact;
+        }
+        if (!platform || platform === 'ios') {
+            const iosDir = path.join(projectPath, 'ios');
+            // Recommend running `pod install` prior to building in CI; not performed automatically here
+            const ios = new iOSManage();
+            const artifact = await ios.build(iosDir);
+            return artifact;
+        }
+        return { error: 'Unable to build react-native project' };
+    }
+    static async buildAppHandler({ platform, projectPath, variant, projectType: _projectType }) {
+        void _projectType;
+        // delegate to platform-specific build implementations
+        const chosen = platform || 'android';
+        if (chosen === 'android') {
+            const android = new AndroidManage();
+            const artifact = await android.build(projectPath, variant);
+            return artifact;
+        }
+        else {
+            const ios = new iOSManage();
+            const artifact = await ios.build(projectPath, variant);
+            return artifact;
+        }
+    }
+    static async installAppHandler({ platform, appPath, deviceId, projectType }) {
+        // Enforce explicit platform and projectType: both are mandatory to avoid ambiguity
+        if (!platform || !projectType) {
+            throw new Error('Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).');
+        }
+        const chosenPlatform = platform;
+        if (chosenPlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            const androidRun = new AndroidManage();
+            const result = await androidRun.installApp(appPath, resolved.id);
+            return result;
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            const iosRun = new iOSManage();
+            const result = await iosRun.installApp(appPath, resolved.id);
+            return result;
+        }
+    }
+    static async startAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().startApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().startApp(appId, resolved.id);
+        }
+    }
+    static async terminateAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().terminateApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().terminateApp(appId, resolved.id);
+        }
+    }
+    static async restartAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().restartApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().restartApp(appId, resolved.id);
+        }
+    }
+    static async resetAppDataHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().resetAppData(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().resetAppData(appId, resolved.id);
+        }
+    }
+    static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType }) {
+        const events = [];
+        const pushEvent = (obj) => events.push(JSON.stringify(obj));
+        const effectiveTimeout = timeout ?? 180000; // reserved for future streaming/timeouts
+        void effectiveTimeout;
+        // Require explicit platform and projectType to avoid ambiguous autodetection
+        if (!platform || !projectType) {
+            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
+        }
+        pushEvent({ type: 'build', status: 'started', platform: chosenPlatform });
+        let buildRes;
+        try {
+            buildRes = await ToolsManage.buildAppHandler({ platform: chosenPlatform, projectPath });
+            if (buildRes && buildRes.error) {
+                pushEvent({ type: 'build', status: 'failed', error: buildRes.error });
+                return { ndjson: events.join('\n') + '\n', result: { success: false, error: buildRes.error } };
+            }
+            pushEvent({ type: 'build', status: 'finished', artifactPath: buildRes.artifactPath });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            pushEvent({ type: 'build', status: 'failed', error: msg });
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: msg } };
+        }
+        // Install phase
+        const artifact = buildRes.artifactPath || projectPath;
+        pushEvent({ type: 'install', status: 'started', artifactPath: artifact, deviceId });
+        let installRes;
+        try {
+            installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform, appPath: artifact, deviceId, projectType });
+            if (installRes && installRes.installed === true) {
+                pushEvent({ type: 'install', status: 'finished', artifactPath: artifact, device: installRes.device });
+                return { ndjson: events.join('\n') + '\n', result: { success: true, artifactPath: artifact, device: installRes.device, output: installRes.output } };
+            }
+            else {
+                pushEvent({ type: 'install', status: 'failed', error: installRes.error || 'unknown' });
+                return { ndjson: events.join('\n') + '\n', result: { success: false, error: installRes.error || 'install failed' } };
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            pushEvent({ type: 'install', status: 'failed', error: msg });
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: msg } };
+        }
+    }
+    static async listDevicesHandler({ platform, appId }) {
+        const devices = await listDevices(platform, appId);
+        return { devices };
+    }
+}