devlens-mcp 0.3.0 → 0.3.2

package/src/platform/android/adb.ts

@@ -1,200 +0,0 @@
-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

@@ -1,116 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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;
-}

package/src/platform/device-manager.ts

@@ -1,229 +0,0 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
-import type { Device, DeviceInfo } from "./device.js";
-import { AndroidDevice } from "./android/android-device.js";
-import { IosDevice } from "./ios/ios-device.js";
-
-const execFileAsync = promisify(execFile);
-
-export interface DiscoveredDevice {
-  id: string;
-  name: string;
-  platform: "ios" | "android";
-  osVersion: string;
-  isBooted: boolean;
-}
-
-/**
- * DeviceManager discovers running iOS Simulators and Android Emulators,
- * and creates Device instances for them.
- */
-export class DeviceManager {
-  private activeDevice: Device | null = null;
-  private activeDeviceId: string | null = null;
-  private activePlatform: "ios" | "android" | null = null;
-
-  async discoverDevices(): Promise<DiscoveredDevice[]> {
-    const devices: DiscoveredDevice[] = [];
-
-    const [androidDevices, iosDevices] = await Promise.allSettled([
-      this.discoverAndroidDevices(),
-      this.discoverIosDevices(),
-    ]);
-
-    if (androidDevices.status === "fulfilled") {
-      devices.push(...androidDevices.value);
-    }
-    if (iosDevices.status === "fulfilled") {
-      devices.push(...iosDevices.value);
-    }
-
-    return devices;
-  }
-
-  async getDevice(deviceId?: string): Promise<Device> {
-    // If we have a cached device and it matches, verify it's still healthy
-    if (
-      this.activeDevice &&
-      this.activeDeviceId &&
-      (!deviceId || deviceId === this.activeDeviceId)
-    ) {
-      const isHealthy = await this.checkDeviceHealth(
-        this.activeDeviceId,
-        this.activePlatform
-      );
-      if (isHealthy) {
-        return this.activeDevice;
-      }
-      // Device is stale — clear cache and rediscover
-      this.activeDevice = null;
-      this.activeDeviceId = null;
-      this.activePlatform = null;
-    }
-
-    const devices = await this.discoverDevices();
-    const bootedDevices = devices.filter((d) => d.isBooted);
-
-    if (bootedDevices.length === 0) {
-      throw new Error(
-        "No running simulators or emulators found. Please start a device first."
-      );
-    }
-
-    let target: DiscoveredDevice;
-    if (deviceId) {
-      const found = bootedDevices.find((d) => d.id === deviceId);
-      if (!found) {
-        throw new Error(
-          `Device "${deviceId}" not found or not running. Available: ${bootedDevices.map((d) => d.id).join(", ")}`
-        );
-      }
-      target = found;
-    } else {
-      target = bootedDevices[0];
-    }
-
-    if (target.platform === "android") {
-      this.activeDevice = new AndroidDevice(target.id);
-    } else {
-      this.activeDevice = new IosDevice(target.id);
-    }
-
-    this.activeDeviceId = target.id;
-    this.activePlatform = target.platform;
-    return this.activeDevice;
-  }
-
-  /**
-   * Quick health check to verify a cached device is still alive.
-   * Returns false if the device is disconnected or no longer booted.
-   */
-  private async checkDeviceHealth(
-    deviceId: string,
-    platform: "ios" | "android" | null
-  ): Promise<boolean> {
-    try {
-      if (platform === "android") {
-        const adbPath = this.getAdbPath();
-        const { stdout } = await execFileAsync(adbPath, ["-s", deviceId, "get-state"], {
-          timeout: 5000,
-        });
-        return stdout.trim() === "device";
-      } else if (platform === "ios") {
-        const { stdout } = await execFileAsync(
-          "xcrun",
-          ["simctl", "list", "devices", "--json"],
-          { timeout: 5000 }
-        );
-        const data = JSON.parse(stdout);
-        for (const deviceList of Object.values(
-          data.devices as Record<string, Array<{ udid: string; state: string }>>
-        )) {
-          const found = deviceList.find((d) => d.udid === deviceId);
-          if (found) return found.state === "Booted";
-        }
-        return false;
-      }
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  private async discoverAndroidDevices(): Promise<DiscoveredDevice[]> {
-    try {
-      const adbPath = this.getAdbPath();
-      const { stdout } = await execFileAsync(adbPath, ["devices", "-l"]);
-      const devices: DiscoveredDevice[] = [];
-
-      for (const line of stdout.split("\n").slice(1)) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed === "") continue;
-
-        const parts = trimmed.split(/\s+/);
-        const id = parts[0];
-        const status = parts[1];
-
-        if (status !== "device") continue;
-
-        // Extract model name from properties
-        const modelMatch = trimmed.match(/model:(\S+)/);
-        const name = modelMatch ? modelMatch[1] : id;
-
-        // Get Android version
-        let osVersion = "unknown";
-        try {
-          const { stdout: versionOut } = await execFileAsync(adbPath, [
-            "-s",
-            id,
-            "shell",
-            "getprop",
-            "ro.build.version.release",
-          ]);
-          osVersion = versionOut.trim();
-        } catch {
-          // Ignore version fetch errors
-        }
-
-        devices.push({
-          id,
-          name,
-          platform: "android",
-          osVersion,
-          isBooted: true,
-        });
-      }
-
-      return devices;
-    } catch {
-      return [];
-    }
-  }
-
-  private async discoverIosDevices(): Promise<DiscoveredDevice[]> {
-    try {
-      const { stdout } = await execFileAsync("xcrun", [
-        "simctl",
-        "list",
-        "devices",
-        "--json",
-      ]);
-      const data = JSON.parse(stdout);
-      const devices: DiscoveredDevice[] = [];
-
-      for (const [runtime, deviceList] of Object.entries(
-        data.devices as Record<string, Array<{ udid: string; name: string; state: string }>>
-      )) {
-        const osVersion = runtime.replace(
-          /^com\.apple\.CoreSimulator\.SimRuntime\./,
-          ""
-        ).replace(/-/g, ".").replace(/^iOS\./, "");
-
-        for (const device of deviceList) {
-          if (device.state === "Booted") {
-            devices.push({
-              id: device.udid,
-              name: device.name,
-              platform: "ios",
-              osVersion,
-              isBooted: true,
-            });
-          }
-        }
-      }
-
-      return devices;
-    } catch {
-      return [];
-    }
-  }
-
-  private getAdbPath(): string {
-    const androidHome =
-      process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
-    if (androidHome) {
-      return `${androidHome}/platform-tools/adb`;
-    }
-    return "adb";
-  }
-}