mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/manage/ios.js

@@ -1,256 +1,17 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
+import { buildIOS } from './ios/build.js';
 import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
-import { spawn, spawnSync } from "child_process";
+import { spawn } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js";
 import { iOSObserve } from "../observe/ios.js";
-import path from "path";
 export class iOSManage {
-    async build(projectPath, optsOrVariant) {
-        // Support legacy variant string as second arg
-        const opts = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {});
-        const env = { ...process.env, ...(opts.env || {}) };
-        try {
-            // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
-            async function findProject(root, maxDepth = 4) {
-                try {
-                    const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
-                    for (const e of ents) {
-                        // .xcworkspace and .xcodeproj are directories on disk (bundles), not regular files
-                        if (e.name.endsWith('.xcworkspace'))
-                            return { dir: root, workspace: e.name };
-                        if (e.name.endsWith('.xcodeproj'))
-                            return { dir: root, proj: e.name };
-                    }
-                }
-                catch { }
-                if (maxDepth <= 0)
-                    return null;
-                try {
-                    const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
-                    for (const e of ents) {
-                        if (e.isDirectory()) {
-                            const candidate = await findProject(path.join(root, e.name), maxDepth - 1);
-                            if (candidate)
-                                return candidate;
-                        }
-                    }
-                }
-                catch { }
-                return null;
-            }
-            // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
-            const absProjectPath = path.resolve(projectPath);
-            // If caller supplied explicit workspace/project, prefer those and set projectRootDir accordingly
-            let projectRootDir = absProjectPath;
-            let workspace = opts.workspace;
-            let proj = opts.project;
-            if (workspace) {
-                // normalize workspace path and set root to its parent
-                workspace = path.isAbsolute(workspace) ? workspace : path.join(absProjectPath, workspace);
-                projectRootDir = path.dirname(workspace);
-                workspace = path.basename(workspace);
-            }
-            else if (proj) {
-                proj = path.isAbsolute(proj) ? proj : path.join(absProjectPath, proj);
-                projectRootDir = path.dirname(proj);
-                proj = path.basename(proj);
-            }
-            else {
-                const projectInfo = await findProject(absProjectPath, 4);
-                if (!projectInfo)
-                    return { error: 'No Xcode project or workspace found' };
-                projectRootDir = projectInfo.dir || absProjectPath;
-                workspace = projectInfo.workspace;
-                proj = projectInfo.proj;
-            }
-            // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
-            let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || '';
-            if (!destinationUDID) {
-                try {
-                    const meta = await getIOSDeviceMetadata('booted');
-                    if (meta && meta.id)
-                        destinationUDID = meta.id;
-                }
-                catch { }
-            }
-            // Determine xcode command early so it can be used when detecting schemes
-            const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild';
-            // Determine available schemes by querying xcodebuild -list rather than guessing
-            async function detectScheme(xcodeCmdInner, workspacePath, projectPathFull, cwd) {
-                try {
-                    const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull];
-                    // Run xcodebuild directly to list schemes
-                    const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 });
-                    const out = res.stdout || '';
-                    const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m);
-                    if (schemesMatch) {
-                        const block = schemesMatch[1];
-                        const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean);
-                        if (schemes.length)
-                            return schemes[0];
-                    }
-                }
-                catch { }
-                return null;
-            }
-            // Prepare build flags and paths (support incremental builds)
-            let buildArgs;
-            let chosenScheme = opts.scheme || null;
-            // Derived data and result bundle (agent-configurable)
-            const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
-            // Use unique result bundle path by default to avoid collisions
-            const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`);
-            const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4);
-            const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1';
-            // ensure result dirs exist
-            await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => { });
-            await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => { });
-            // remove any pre-existing result bundle path to avoid xcodebuild complaining
-            await fs.rm(resultBundlePath, { recursive: true, force: true }).catch(() => { });
-            if (workspace) {
-                const workspacePath = path.join(projectRootDir, workspace);
-                if (!chosenScheme)
-                    chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir);
-                const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '');
-                buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
-            }
-            else {
-                const projectPathFull = path.join(projectRootDir, proj);
-                if (!chosenScheme)
-                    chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir);
-                const scheme = chosenScheme || proj.replace(/\.xcodeproj$/, '');
-                buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
-            }
-            // Insert clean if explicitly requested via env or opts
-            if (forceClean) {
-                const idx = buildArgs.indexOf('build');
-                if (idx >= 0)
-                    buildArgs.splice(idx, 0, 'clean');
-            }
-            // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
-            if (destinationUDID) {
-                buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`);
-            }
-            // Add derived data and result bundle for diagnostics and faster incremental builds
-            buildArgs.push('-derivedDataPath', derivedDataPath);
-            buildArgs.push('-resultBundlePath', resultBundlePath);
-            // parallelisation and jobs
-            buildArgs.push('-parallelizeTargets');
-            buildArgs.push('-jobs', String(xcodeJobs));
-            // Prepare results directory for backwards-compatible logs
-            const resultsDir = path.join(projectPath, 'build-results');
-            // Remove any stale results to avoid xcodebuild complaining about existing result bundles
-            await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => { });
-            await fs.mkdir(resultsDir, { recursive: true }).catch(() => { });
-            const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
-            const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
-            const tries = MAX_RETRIES + 1;
-            let lastStdout = '';
-            let lastStderr = '';
-            let lastErr = null;
-            for (let attempt = 1; attempt <= tries; attempt++) {
-                // Run xcodebuild with a watchdog
-                const res = await new Promise((resolve) => {
-                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env });
-                    let stdout = '';
-                    let stderr = '';
-                    proc.stdout?.on('data', d => stdout += d.toString());
-                    proc.stderr?.on('data', d => stderr += d.toString());
-                    let killed = false;
-                    const to = setTimeout(() => {
-                        killed = true;
-                        try {
-                            proc.kill('SIGKILL');
-                        }
-                        catch { }
-                    }, XCODEBUILD_TIMEOUT);
-                    proc.on('close', (code) => {
-                        clearTimeout(to);
-                        resolve({ code, stdout, stderr, killedByWatchdog: killed });
-                    });
-                    proc.on('error', (err) => {
-                        clearTimeout(to);
-                        resolve({ code: null, stdout, stderr: String(err), killedByWatchdog: killed });
-                    });
-                });
-                lastStdout = res.stdout;
-                lastStderr = res.stderr;
-                if (res.code === 0) {
-                    // success — clear any previous error and stop retrying
-                    lastErr = null;
-                    break;
-                }
-                // record the failure for reporting
-                lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`);
-                lastErr.code = res.code;
-                lastErr.exitCode = res.code;
-                lastErr.killedByWatchdog = !!res.killedByWatchdog;
-                // write logs for diagnostics (helpful whether killed or not)
-                try {
-                    await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => { });
-                    await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stderr.log`), res.stderr).catch(() => { });
-                }
-                catch { }
-                // If killed by watchdog and there are remaining attempts, continue to retry
-                if (res.killedByWatchdog && attempt < tries) {
-                    continue;
-                }
-                // no more retries or not a watchdog kill — break to report lastErr
-                if (attempt >= tries)
-                    break;
-            }
-            if (lastErr) {
-                // Include diagnostics and result bundle path when available; provide structured info useful for agents
-                const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
-                const envSnapshot = { PATH: env.PATH };
-                return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: lastErr.code || null, invokedCommand, cwd: projectRootDir, envSnapshot } };
-            }
-            // Try to locate built .app. First search project tree, then DerivedData if necessary
-            const built = await findAppBundle(projectPath);
-            if (built)
-                return { artifactPath: built };
-            // Fallback: search DerivedData for matching product
-            const dd = path.join(process.env.HOME || '', 'Library', 'Developer', 'Xcode', 'DerivedData');
-            try {
-                const entries = await fs.readdir(dd).catch(() => []);
-                for (const e of entries) {
-                    const candidate = path.join(dd, e);
-                    const found = await findAppBundle(candidate).catch(() => undefined);
-                    if (found)
-                        return { artifactPath: found };
-                }
-            }
-            catch { }
-            return { error: 'Could not find .app after build' };
-        }
-        catch (e) {
-            return { error: e instanceof Error ? e.message : String(e) };
-        }
-    }
+    async build(projectPath, optsOrVariant) { return buildIOS(projectPath, optsOrVariant); }
     async installApp(appPath, deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
         try {
-            let toInstall = appPath;
-            const stat = await fs.stat(appPath).catch(() => null);
-            if (stat && stat.isDirectory()) {
-                if (appPath.endsWith('.app')) {
-                    toInstall = appPath;
-                }
-                else {
-                    const found = await findAppBundle(appPath);
-                    if (found) {
-                        toInstall = found;
-                    }
-                    else {
-                        // Reuse the existing build() implementation to avoid duplicating the xcodebuild logic
-                        const buildRes = await this.build(appPath);
-                        if (buildRes.error)
-                            throw new Error(buildRes.error);
-                        toInstall = buildRes.artifactPath;
-                    }
-                }
-            }
+            const toInstall = await this.installBundle(appPath);
             try {
                 const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId);
                 return { device, installed: true, output: res.output };
@@ -266,18 +27,7 @@ export class iOSManage {
                     });
                     if (idbExists) {
                         // attempt idb install via spawn but include diagnostics
-                        await new Promise((resolve, reject) => {
-                            const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', device.id]);
-                            let stderr = '';
-                            proc.stderr.on('data', d => stderr += d.toString());
-                            proc.on('close', code => {
-                                if (code === 0)
-                                    resolve();
-                                else
-                                    reject(new Error(stderr || `idb install failed with code ${code}`));
-                            });
-                            proc.on('error', err => reject(err));
-                        });
+                        await installWithIdb(toInstall, device.id);
                         return { device, installed: true };
                     }
                 }
@@ -289,6 +39,29 @@ export class iOSManage {
             return { device, installed: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
+    async installBundle(appPath) {
+        let toInstall = appPath;
+        const stat = await fs.stat(appPath).catch(() => null);
+        if (stat && stat.isDirectory()) {
+            if (appPath.endsWith('.app')) {
+                toInstall = appPath;
+            }
+            else {
+                const found = await findAppBundle(appPath);
+                if (found) {
+                    toInstall = found;
+                }
+                else {
+                    // Reuse the existing build() implementation to avoid duplicating the xcodebuild logic
+                    const buildRes = await this.build(appPath);
+                    if ('error' in buildRes)
+                        throw new Error(buildRes.error);
+                    toInstall = buildRes.artifactPath;
+                }
+            }
+        }
+        return toInstall;
+    }
     async startApp(bundleId, deviceId = "booted", observe = true) {
         const started = performance.now();
         validateBundleId(bundleId);
@@ -382,3 +155,18 @@ export class iOSManage {
         }
     }
 }
+async function installWithIdb(toInstall, deviceId) {
+    await new Promise((resolve, reject) => {
+        checkDebuggerGuard(true);
+        const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', deviceId]);
+        let stderr = '';
+        proc.stderr.on('data', d => stderr += d.toString());
+        proc.on('close', code => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(stderr || `idb install failed with code ${code}`));
+        });
+        proc.on('error', err => reject(err));
+    });
+}

package/dist/observe/android/context.js

@@ -0,0 +1 @@
+export const activeLogStreams = new Map();

package/dist/observe/android/current-screen.js

@@ -0,0 +1,55 @@
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../../utils/android/utils.js";
+export async function collectGetCurrentScreen(deviceId) {
+    const metadata = await getAndroidDeviceMetadata("", deviceId);
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+    try {
+        const output = await execAdb(['shell', 'dumpsys', 'activity', 'activities'], deviceId, { timeout: 10000 });
+        const lines = output.split('\n');
+        let resumedLine = lines.find(line => /^\s*mResumedActivity:/.test(line));
+        if (!resumedLine) {
+            resumedLine = lines.find(line => /^\s*ResumedActivity:/.test(line));
+        }
+        if (!resumedLine) {
+            return {
+                device: deviceInfo,
+                package: "",
+                activity: "",
+                shortActivity: "",
+                error: "Could not find 'mResumedActivity' in dumpsys output"
+            };
+        }
+        const match = resumedLine.match(/ActivityRecord\{[^ ]*(?:\s+[^ ]+)*\s+([^\/ ]+)\/([^ \{}]+)[^}]*\}/);
+        if (match) {
+            const packageName = match[1];
+            let activityName = match[2];
+            if (activityName.startsWith('.')) {
+                activityName = packageName + activityName;
+            }
+            const shortActivity = activityName.split('.').pop() || activityName;
+            return {
+                device: deviceInfo,
+                package: packageName,
+                activity: activityName,
+                shortActivity: shortActivity
+            };
+        }
+        else {
+            return {
+                device: deviceInfo,
+                package: "",
+                activity: "",
+                shortActivity: "",
+                error: `Found resumed activity line but failed to parse: '${resumedLine.trim()}'`
+            };
+        }
+    }
+    catch (e) {
+        return {
+            device: deviceInfo,
+            package: "",
+            activity: "",
+            shortActivity: "",
+            error: e instanceof Error ? e.message : String(e)
+        };
+    }
+}

package/dist/observe/android/fingerprint.js

@@ -0,0 +1,13 @@
+import { computeScreenFingerprint } from "../../utils/ui/index.js";
+export async function collectGetScreenFingerprint(source, deviceId) {
+    try {
+        const tree = await source.getUITree(deviceId);
+        if (!tree || tree.error)
+            return { fingerprint: null, error: tree.error };
+        const current = await source.getCurrentScreen(deviceId).catch(() => null);
+        return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms };
+    }
+    catch (e) {
+        return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/observe/android/log-stream.js

@@ -0,0 +1,132 @@
+import { spawn } from "child_process";
+import { getAdbCmd, execAdb, parseLogLine } from "../../utils/android/utils.js";
+import { createWriteStream } from "fs";
+import { promises as fsPromises } from "fs";
+import path from "path";
+import { activeLogStreams } from './context.js';
+export async function startLogStream(packageName, level = 'error', deviceId, sessionId = 'default') {
+    try {
+        const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '');
+        const pid = (pidOutput || '').trim();
+        if (!pid)
+            return { success: false, error: 'app_not_running' };
+        const levelMap = { error: '*:E', warn: '*:W', info: '*:I', debug: '*:D' };
+        const filter = levelMap[level] || levelMap['error'];
+        if (activeLogStreams.has(sessionId)) {
+            try {
+                activeLogStreams.get(sessionId).proc.kill();
+            }
+            catch { }
+            activeLogStreams.delete(sessionId);
+        }
+        const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter];
+        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' });
+        proc.stdout.on('data', (chunk) => {
+            const text = chunk.toString();
+            const lines = text.split(/\r?\n/).filter(Boolean);
+            for (const l of lines) {
+                const entry = parseLogLine(l);
+                stream.write(JSON.stringify(entry) + '\n');
+            }
+        });
+        proc.stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            const lines = text.split(/\r?\n/).filter(Boolean);
+            for (const l of lines) {
+                const entry = { timestamp: '', level: 'E', tag: 'adb', message: l };
+                stream.write(JSON.stringify(entry) + '\n');
+            }
+        });
+        proc.on('close', () => {
+            stream.end();
+            if (activeLogStreams.get(sessionId)?.proc === proc)
+                activeLogStreams.delete(sessionId);
+        });
+        activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } });
+        return { success: true, stream_started: true };
+    }
+    catch (e) {
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export async function stopLogStream(sessionId = 'default') {
+    const entry = activeLogStreams.get(sessionId);
+    if (!entry)
+        return { success: true };
+    try {
+        entry.proc.kill();
+    }
+    catch { }
+    activeLogStreams.delete(sessionId);
+    return { success: true };
+}
+export async function collectReadLogStream(sessionId = 'default', limit = 100, since) {
+    const entry = activeLogStreams.get(sessionId);
+    let file;
+    if (entry && entry.file)
+        file = entry.file;
+    else {
+        const tmpDir = process.env.TMPDIR || '/tmp';
+        const candidate = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`);
+        file = candidate;
+    }
+    try {
+        const data = await fsPromises.readFile(file, 'utf8').catch(() => '');
+        if (!data)
+            return { entries: [], crash_summary: { crash_detected: false } };
+        const lines = data.split(/\r?\n/).filter(Boolean);
+        const parsed = lines.map(l => {
+            try {
+                const obj = JSON.parse(l);
+                if (typeof obj._iso === 'undefined') {
+                    let iso = null;
+                    if (obj.timestamp) {
+                        const d = new Date(obj.timestamp);
+                        if (!isNaN(d.getTime()))
+                            iso = d.toISOString();
+                    }
+                    obj._iso = iso;
+                }
+                if (typeof obj.crash === 'undefined') {
+                    const msg = (obj.message || '').toString();
+                    const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/);
+                    if (/FATAL EXCEPTION/i.test(msg) || exMatch) {
+                        obj.crash = true;
+                        if (exMatch)
+                            obj.exception = exMatch[1];
+                    }
+                    else {
+                        obj.crash = false;
+                    }
+                }
+                return obj;
+            }
+            catch {
+                return { message: l, _iso: null, crash: false };
+            }
+        });
+        let filtered = parsed;
+        if (since) {
+            let sinceMs = null;
+            if (/^\d+$/.test(since))
+                sinceMs = Number(since);
+            else {
+                const sDate = new Date(since);
+                if (!isNaN(sDate.getTime()))
+                    sinceMs = sDate.getTime();
+            }
+            if (sinceMs !== null)
+                filtered = parsed.filter(p => p._iso && (new Date(p._iso).getTime() >= sinceMs));
+        }
+        const entries = filtered.slice(-Math.max(0, limit));
+        const crashEntry = entries.find(e => e.crash);
+        const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false };
+        return { entries, crash_summary };
+    }
+    catch {
+        return { entries: [], crash_summary: { crash_detected: false } };
+    }
+}

package/dist/observe/android/logs.js

@@ -0,0 +1,107 @@
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, parseLogLine } from "../../utils/android/utils.js";
+export async function collectGetLogs(filters = {}) {
+    const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters;
+    const metadata = await getAndroidDeviceMetadata(appId || "", deviceId);
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+    try {
+        const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50;
+        const { pidArg, args } = await logcatArguments(filters, effectiveLimit);
+        const stdout = await execAdb(args, deviceId);
+        const allLines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : [];
+        // Parse lines into structured entries
+        const parsed = allLines.map(line => parseAndroidLog(line, pidArg));
+        // Apply client-side filters: contains, since_seconds
+        let filtered = parsed;
+        if (contains)
+            filtered = filtered.filter(e => e.message && e.message.includes(contains));
+        if (since_seconds) {
+            const sinceMs = Date.now() - (since_seconds * 1000);
+            filtered = filtered.filter(e => {
+                if (!e.timestamp)
+                    return false;
+                const t = new Date(e.timestamp).getTime();
+                return t >= sinceMs;
+            });
+        }
+        // If appId provided and no pidArg, try to filter by appId substring in message/tag
+        if (appId && !pidArg) {
+            const matched = filtered.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)));
+            if (matched.length > 0)
+                filtered = matched;
+        }
+        // Ensure ordering oldest -> newest (by timestamp when available)
+        filtered.sort((a, b) => {
+            const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+            const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+            return ta - tb;
+        });
+        const limited = filtered.slice(-Math.max(0, effectiveLimit));
+        const source = pidArg ? 'pid' : (appId ? 'package' : 'broad');
+        const meta = { pidArg, appIdProvided: !!appId, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid };
+        return { device: deviceInfo, logs: limited, logCount: limited.length, source, meta };
+    }
+    catch (e) {
+        console.error("Error fetching logs:", e);
+        return { device: deviceInfo, logs: [], logCount: 0, source: 'broad', meta: { error: e instanceof Error ? e.message : String(e) } };
+    }
+}
+function parseAndroidLog(l, pidArg) {
+    const entry = parseLogLine(l);
+    // normalize level
+    const levelChar = (entry.level || '').toUpperCase();
+    const levelMapChar = { 'V': 'VERBOSE', 'D': 'DEBUG', 'I': 'INFO', 'W': 'WARN', 'E': 'ERROR' };
+    const normLevel = levelMapChar[levelChar] || (entry.level && String(entry.level).toUpperCase()) || 'INFO';
+    const iso = entry._iso || (() => {
+        const d = new Date(entry.timestamp || '');
+        if (!isNaN(d.getTime()))
+            return d.toISOString();
+        return null;
+    })();
+    let pidNum = null;
+    if (entry.pid)
+        pidNum = Number(entry.pid);
+    else if (pidArg)
+        pidNum = Number(pidArg);
+    const pidVal = (pidNum !== null && !isNaN(pidNum)) ? pidNum : null;
+    return { timestamp: iso, level: normLevel, tag: entry.tag || '', pid: pidVal, message: entry.message || '' };
+}
+async function logcatArguments(filters, effectiveLimit) {
+    const { appId, deviceId, pid, tag, level } = filters;
+    // If appId provided, try to get pid to filter at source
+    let pidArg = null;
+    if (appId) {
+        try {
+            const pidOut = await execAdb(['shell', 'pidof', appId], deviceId).catch(() => '');
+            const pidTrim = (pidOut || '').trim();
+            if (pidTrim)
+                pidArg = pidTrim.split('\n')[0];
+        }
+        catch (err) {
+            // Log a warning so failures to detect PID are visible during debugging
+            try {
+                console.warn(`getLogs: pid detection failed for appId=${appId}:`, err instanceof Error ? err.message : String(err));
+            }
+            catch { }
+        }
+    }
+    const args = ['logcat', '-d', '-v', 'threadtime'];
+    // Apply pid filter via --pid if available
+    if (pidArg)
+        args.push(`--pid=${pidArg}`);
+    else if (pid)
+        args.push(`--pid=${pid}`);
+    // Apply tag/level filter if provided
+    if (tag && level) {
+        // Map verbose/debug/info/warn/error to single-letter levels
+        const levelMap = { 'VERBOSE': 'V', 'DEBUG': 'D', 'INFO': 'I', 'WARN': 'W', 'ERROR': 'E' };
+        const L = (levelMap[(level || '').toUpperCase()] || 'V');
+        args.push(`${tag}:${L}`);
+    }
+    else {
+        // Default: show all levels
+        args.push('*:V');
+    }
+    // Use -t to limit lines (apply early)
+    args.push('-t', effectiveLimit.toString());
+    return { pidArg, args };
+}