devlens-mcp 0.3.0

package/src/metro/network-inspector.ts

@@ -0,0 +1,134 @@
+import type { CdpClient, CdpMessage } from "./cdp-client.js";
+
+/**
+ * Intercepts network requests from the React Native app via CDP's Network domain.
+ * Captures fetch/XHR requests, their responses, and timing information.
+ */
+
+export interface NetworkRequest {
+  id: string;
+  url: string;
+  method: string;
+  status?: number;
+  statusText?: string;
+  type?: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  requestHeaders?: Record<string, string>;
+  responseHeaders?: Record<string, string>;
+  size?: number;
+  error?: string;
+}
+
+export class NetworkInspector {
+  private requests: Map<string, NetworkRequest> = new Map();
+  private maxRequests: number = 200;
+
+  constructor(private cdp: CdpClient) {}
+
+  /** Start intercepting network requests */
+  start(): void {
+    // Enable Network domain
+    this.cdp.send("Network.enable").catch(() => {
+      // Network domain might not be available
+    });
+
+    // Request started
+    this.cdp.on("Network.requestWillBeSent", (msg: CdpMessage) => {
+      const params = msg.params;
+      if (!params) return;
+
+      const request: NetworkRequest = {
+        id: params.requestId,
+        url: params.request?.url || "",
+        method: params.request?.method || "GET",
+        type: params.type,
+        startTime: Date.now(),
+        requestHeaders: params.request?.headers,
+      };
+
+      this.requests.set(params.requestId, request);
+      this.trimRequests();
+    });
+
+    // Response received
+    this.cdp.on("Network.responseReceived", (msg: CdpMessage) => {
+      const params = msg.params;
+      if (!params) return;
+
+      const request = this.requests.get(params.requestId);
+      if (request) {
+        request.status = params.response?.status;
+        request.statusText = params.response?.statusText;
+        request.responseHeaders = params.response?.headers;
+        request.endTime = Date.now();
+        request.duration = request.endTime - request.startTime;
+      }
+    });
+
+    // Loading finished
+    this.cdp.on("Network.loadingFinished", (msg: CdpMessage) => {
+      const params = msg.params;
+      if (!params) return;
+
+      const request = this.requests.get(params.requestId);
+      if (request) {
+        request.size = params.encodedDataLength;
+        if (!request.endTime) {
+          request.endTime = Date.now();
+          request.duration = request.endTime - request.startTime;
+        }
+      }
+    });
+
+    // Loading failed
+    this.cdp.on("Network.loadingFailed", (msg: CdpMessage) => {
+      const params = msg.params;
+      if (!params) return;
+
+      const request = this.requests.get(params.requestId);
+      if (request) {
+        request.error = params.errorText || "Request failed";
+        request.endTime = Date.now();
+        request.duration = request.endTime - request.startTime;
+      }
+    });
+  }
+
+  /** Get all captured network requests, optionally filtered by URL pattern */
+  getRequests(urlPattern?: string): NetworkRequest[] {
+    let requests = Array.from(this.requests.values());
+
+    if (urlPattern) {
+      const pattern = urlPattern.toLowerCase();
+      requests = requests.filter((r) =>
+        r.url.toLowerCase().includes(pattern)
+      );
+    }
+
+    // Sort by start time (newest first)
+    return requests.sort((a, b) => b.startTime - a.startTime);
+  }
+
+  /** Clear all captured requests */
+  clear(): void {
+    this.requests.clear();
+  }
+
+  private trimRequests(): void {
+    if (this.requests.size > this.maxRequests) {
+      // Remove oldest entries
+      const entries = Array.from(this.requests.entries()).sort(
+        (a, b) => a[1].startTime - b[1].startTime
+      );
+      const toRemove = entries.slice(
+        0,
+        entries.length - Math.floor(this.maxRequests * 0.8)
+      );
+      for (const [id] of toRemove) {
+        this.requests.delete(id);
+      }
+    }
+  }
+}

package/src/platform/android/adb.ts

@@ -0,0 +1,200 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { retry } from "../../utils/retry.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * ADB command wrapper — handles all communication with Android devices via ADB.
+ */
+export class Adb {
+  private adbPath: string;
+
+  constructor(private deviceId: string) {
+    const androidHome =
+      process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+    this.adbPath = androidHome
+      ? `${androidHome}/platform-tools/adb`
+      : "adb";
+  }
+
+  /** Execute an ADB shell command on the device (with retry for transient failures) */
+  async shell(command: string): Promise<string> {
+    return retry(
+      async () => {
+        const { stdout } = await execFileAsync(
+          this.adbPath,
+          ["-s", this.deviceId, "shell", command],
+          { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
+        );
+        return stdout;
+      },
+      { maxAttempts: 2, delayMs: 500 }
+    );
+  }
+
+  /** Execute an ADB command (non-shell) */
+  async exec(...args: string[]): Promise<string> {
+    const { stdout } = await execFileAsync(
+      this.adbPath,
+      ["-s", this.deviceId, ...args],
+      { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
+    );
+    return stdout;
+  }
+
+  /** Take a screenshot and return the PNG buffer (with retry) */
+  async screenshot(): Promise<Buffer> {
+    return retry(
+      async () => {
+        const { stdout } = await execFileAsync(
+          this.adbPath,
+          ["-s", this.deviceId, "exec-out", "screencap", "-p"],
+          { maxBuffer: 20 * 1024 * 1024, encoding: "buffer", timeout: 15000 }
+        );
+        return stdout as unknown as Buffer;
+      },
+      { maxAttempts: 2, delayMs: 300 }
+    );
+  }
+
+  /** Dump the UI hierarchy XML (with retry) */
+  async dumpUiHierarchy(): Promise<string> {
+    return retry(
+      async () => {
+        const dumpPath = "/sdcard/devlens-ui-dump.xml";
+        await execFileAsync(
+          this.adbPath,
+          ["-s", this.deviceId, "shell", `uiautomator dump ${dumpPath}`],
+          { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
+        );
+        const { stdout: xml } = await execFileAsync(
+          this.adbPath,
+          ["-s", this.deviceId, "shell", `cat ${dumpPath}`],
+          { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
+        );
+        // Clean up
+        execFileAsync(
+          this.adbPath,
+          ["-s", this.deviceId, "shell", `rm ${dumpPath}`]
+        ).catch(() => {});
+        return xml;
+      },
+      { maxAttempts: 2, delayMs: 500 }
+    );
+  }
+
+  /** Tap at screen coordinates */
+  async tap(x: number, y: number): Promise<void> {
+    await this.shell(`input tap ${Math.round(x)} ${Math.round(y)}`);
+  }
+
+  /** Long press at coordinates */
+  async longPress(x: number, y: number, durationMs: number = 1000): Promise<void> {
+    await this.shell(
+      `input swipe ${Math.round(x)} ${Math.round(y)} ${Math.round(x)} ${Math.round(y)} ${durationMs}`
+    );
+  }
+
+  /** Swipe between two points */
+  async swipe(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    durationMs: number = 300
+  ): Promise<void> {
+    await this.shell(
+      `input swipe ${Math.round(startX)} ${Math.round(startY)} ${Math.round(endX)} ${Math.round(endY)} ${durationMs}`
+    );
+  }
+
+  /** Type text using ADB input */
+  async typeText(text: string): Promise<void> {
+    // Escape special characters for ADB shell
+    const escaped = text
+      .replace(/\\/g, "\\\\")
+      .replace(/"/g, '\\"')
+      .replace(/ /g, "%s")
+      .replace(/'/g, "\\'")
+      .replace(/&/g, "\\&")
+      .replace(/</g, "\\<")
+      .replace(/>/g, "\\>")
+      .replace(/\|/g, "\\|")
+      .replace(/;/g, "\\;")
+      .replace(/\(/g, "\\(")
+      .replace(/\)/g, "\\)");
+    await this.shell(`input text "${escaped}"`);
+  }
+
+  /** Press a key event */
+  async keyEvent(keyCode: number): Promise<void> {
+    await this.shell(`input keyevent ${keyCode}`);
+  }
+
+  /** Get device screen size */
+  async getScreenSize(): Promise<{ width: number; height: number }> {
+    const output = await this.shell("wm size");
+    const match = output.match(/(\d+)x(\d+)/);
+    if (!match) throw new Error("Could not determine screen size");
+    return { width: parseInt(match[1]), height: parseInt(match[2]) };
+  }
+
+  /** Get device orientation (0=portrait, 1=landscape, 2=reverse-portrait, 3=reverse-landscape) */
+  async getOrientation(): Promise<number> {
+    const output = await this.shell(
+      "dumpsys input | grep 'SurfaceOrientation'"
+    );
+    const match = output.match(/SurfaceOrientation:\s*(\d)/);
+    return match ? parseInt(match[1]) : 0;
+  }
+
+  /** Get Android version */
+  async getAndroidVersion(): Promise<string> {
+    return (await this.shell("getprop ro.build.version.release")).trim();
+  }
+
+  /** Get device model name */
+  async getDeviceName(): Promise<string> {
+    return (await this.shell("getprop ro.product.model")).trim();
+  }
+
+  /** Launch an app by package name */
+  async launchApp(packageName: string): Promise<void> {
+    await this.shell(
+      `monkey -p ${packageName} -c android.intent.category.LAUNCHER 1`
+    );
+  }
+
+  /** Force stop an app */
+  async terminateApp(packageName: string): Promise<void> {
+    await this.shell(`am force-stop ${packageName}`);
+  }
+
+  /** Install an APK */
+  async installApp(apkPath: string): Promise<void> {
+    await this.exec("install", "-r", apkPath);
+  }
+
+  /** List installed packages */
+  async listPackages(): Promise<string[]> {
+    const output = await this.shell("pm list packages -3");
+    return output
+      .split("\n")
+      .filter((line) => line.startsWith("package:"))
+      .map((line) => line.replace("package:", "").trim());
+  }
+
+  /** Open a URL */
+  async openUrl(url: string): Promise<void> {
+    await this.shell(
+      `am start -a android.intent.action.VIEW -d "${url}"`
+    );
+  }
+
+  /** Set orientation (0=auto, 1=portrait, 2=landscape) */
+  async setRotation(rotation: number): Promise<void> {
+    await this.shell("settings put system accelerometer_rotation 0");
+    await this.shell(`settings put system user_rotation ${rotation}`);
+  }
+}

package/src/platform/android/android-device.ts

@@ -0,0 +1,116 @@
+import type { Device, DeviceInfo, AppInfo, SnapshotNode } from "../device.js";
+import { Adb } from "./adb.js";
+import { parseUiAutomatorXml } from "./ui-automator.js";
+
+// Android key codes
+const KEY_HOME = 3;
+const KEY_BACK = 4;
+const KEY_ENTER = 66;
+
+export class AndroidDevice implements Device {
+  private adb: Adb;
+
+  constructor(deviceId: string) {
+    this.adb = new Adb(deviceId);
+  }
+
+  async getInfo(): Promise<DeviceInfo> {
+    const [screenSize, orientation, version, name] = await Promise.all([
+      this.adb.getScreenSize(),
+      this.adb.getOrientation(),
+      this.adb.getAndroidVersion(),
+      this.adb.getDeviceName(),
+    ]);
+
+    return {
+      id: (this.adb as any).deviceId,
+      name,
+      platform: "android",
+      osVersion: version,
+      screenWidth: screenSize.width,
+      screenHeight: screenSize.height,
+      orientation: orientation === 0 || orientation === 2 ? "portrait" : "landscape",
+      isBooted: true,
+    };
+  }
+
+  async getSnapshot(): Promise<SnapshotNode> {
+    const xml = await this.adb.dumpUiHierarchy();
+    return parseUiAutomatorXml(xml);
+  }
+
+  async takeScreenshot(): Promise<Buffer> {
+    return this.adb.screenshot();
+  }
+
+  async tap(x: number, y: number): Promise<void> {
+    await this.adb.tap(x, y);
+  }
+
+  async doubleTap(x: number, y: number): Promise<void> {
+    await this.adb.tap(x, y);
+    await sleep(100);
+    await this.adb.tap(x, y);
+  }
+
+  async longPress(x: number, y: number, durationMs = 1000): Promise<void> {
+    await this.adb.longPress(x, y, durationMs);
+  }
+
+  async typeText(text: string): Promise<void> {
+    await this.adb.typeText(text);
+  }
+
+  async swipe(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    durationMs = 300
+  ): Promise<void> {
+    await this.adb.swipe(startX, startY, endX, endY, durationMs);
+  }
+
+  async pressButton(button: "home" | "back" | "enter"): Promise<void> {
+    const keyMap: Record<string, number> = {
+      home: KEY_HOME,
+      back: KEY_BACK,
+      enter: KEY_ENTER,
+    };
+    await this.adb.keyEvent(keyMap[button]);
+  }
+
+  async setOrientation(orientation: "portrait" | "landscape"): Promise<void> {
+    const rotation = orientation === "portrait" ? 0 : 1;
+    await this.adb.setRotation(rotation);
+  }
+
+  async launchApp(appId: string): Promise<void> {
+    await this.adb.launchApp(appId);
+  }
+
+  async terminateApp(appId: string): Promise<void> {
+    await this.adb.terminateApp(appId);
+  }
+
+  async installApp(path: string): Promise<void> {
+    await this.adb.installApp(path);
+  }
+
+  async listApps(): Promise<AppInfo[]> {
+    const packages = await this.adb.listPackages();
+    return packages.map((pkg) => ({
+      appId: pkg,
+      name: pkg,
+      isRunning: false, // Would need `ps` to determine
+    }));
+  }
+
+  async openUrl(url: string): Promise<void> {
+    await this.adb.openUrl(url);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/platform/android/ui-automator.ts

@@ -0,0 +1,141 @@
+import { XMLParser } from "fast-xml-parser";
+import type { SnapshotNode, Bounds } from "../device.js";
+
+/**
+ * Parses Android UI Automator XML dump into SnapshotNode tree.
+ *
+ * The XML format from `uiautomator dump` looks like:
+ * <hierarchy rotation="0">
+ *   <node index="0" text="" resource-id="..." class="android.widget.FrameLayout"
+ *         package="com.example" content-desc="" checkable="false" checked="false"
+ *         clickable="false" enabled="true" focusable="false" focused="false"
+ *         scrollable="false" long-clickable="false" password="false" selected="false"
+ *         bounds="[0,0][1080,2340]">
+ *     <node ... />
+ *   </node>
+ * </hierarchy>
+ */
+export function parseUiAutomatorXml(xml: string): SnapshotNode {
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    allowBooleanAttributes: true,
+    isArray: (name) => name === "node",
+  });
+
+  const parsed = parser.parse(xml);
+  const hierarchy = parsed.hierarchy;
+
+  if (!hierarchy || !hierarchy.node) {
+    throw new Error(
+      "Invalid UI Automator dump: no hierarchy or root node found"
+    );
+  }
+
+  const rootNodes: any[] = Array.isArray(hierarchy.node)
+    ? hierarchy.node
+    : [hierarchy.node];
+
+  // Create a virtual root that contains all top-level nodes
+  return {
+    type: "hierarchy",
+    text: undefined,
+    label: undefined,
+    description: undefined,
+    bounds: { x: 0, y: 0, width: 0, height: 0 },
+    interactive: false,
+    children: rootNodes.map(convertNode),
+  };
+}
+
+function convertNode(node: any): SnapshotNode {
+  const bounds = parseBounds(node["@_bounds"] || "[0,0][0,0]");
+  const text = node["@_text"] || undefined;
+  const description = node["@_content-desc"] || undefined;
+  const resourceId = node["@_resource-id"] || undefined;
+  const className = node["@_class"] || "unknown";
+
+  const clickable = node["@_clickable"] === "true";
+  const longClickable = node["@_long-clickable"] === "true";
+  const checkable = node["@_checkable"] === "true";
+  const scrollable = node["@_scrollable"] === "true";
+  const focusable = node["@_focusable"] === "true";
+  const interactive =
+    clickable || longClickable || checkable || scrollable || focusable;
+
+  const children: SnapshotNode[] = [];
+  if (node.node) {
+    const childNodes = Array.isArray(node.node) ? node.node : [node.node];
+    for (const child of childNodes) {
+      children.push(convertNode(child));
+    }
+  }
+
+  return {
+    type: simplifyClassName(className),
+    text: text && text.length > 0 ? text : undefined,
+    label: description && description.length > 0 ? description : undefined,
+    description:
+      description && description.length > 0 ? description : undefined,
+    bounds,
+    interactive,
+    focused: node["@_focused"] === "true",
+    enabled: node["@_enabled"] === "true",
+    visible: bounds.width > 0 && bounds.height > 0,
+    value: getElementValue(node),
+    resourceId: resourceId && resourceId.length > 0 ? resourceId : undefined,
+    children,
+    rawAttributes: extractRawAttributes(node),
+  };
+}
+
+/** Parse Android bounds format "[left,top][right,bottom]" into Bounds */
+function parseBounds(boundsStr: string): Bounds {
+  const match = boundsStr.match(
+    /\[(\d+),(\d+)\]\[(\d+),(\d+)\]/
+  );
+  if (!match) {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+
+  const left = parseInt(match[1]);
+  const top = parseInt(match[2]);
+  const right = parseInt(match[3]);
+  const bottom = parseInt(match[4]);
+
+  return {
+    x: left,
+    y: top,
+    width: right - left,
+    height: bottom - top,
+  };
+}
+
+/** Simplify Android class names for readability */
+function simplifyClassName(className: string): string {
+  // "android.widget.TextView" → "TextView"
+  // "android.view.View" → "View"
+  const parts = className.split(".");
+  return parts[parts.length - 1];
+}
+
+/** Extract element value (for checkboxes, switches, inputs, etc.) */
+function getElementValue(node: any): string | undefined {
+  if (node["@_checked"] === "true") return "checked";
+  if (node["@_checked"] === "false" && node["@_checkable"] === "true")
+    return "unchecked";
+  if (node["@_selected"] === "true") return "selected";
+  if (node["@_password"] === "true") return "•••";
+  return undefined;
+}
+
+/** Extract all raw attributes for debugging */
+function extractRawAttributes(node: any): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const key of Object.keys(node)) {
+    if (key.startsWith("@_")) {
+      attrs[key.replace("@_", "")] = String(node[key]);
+    }
+  }
+  return attrs;
+}