devlens-mcp 0.3.0

package/src/platform/device-manager.ts

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

package/src/platform/device.ts

@@ -0,0 +1,110 @@
+/**
+ * Abstract Device interface — the core abstraction that iOS and Android drivers implement.
+ * Every MCP tool delegates to this interface. Tools never know which platform they're on.
+ */
+
+export interface DeviceInfo {
+  id: string;
+  name: string;
+  platform: "ios" | "android";
+  osVersion: string;
+  screenWidth: number;
+  screenHeight: number;
+  orientation: "portrait" | "landscape";
+  isBooted: boolean;
+}
+
+export interface AppInfo {
+  appId: string;
+  name: string;
+  isRunning: boolean;
+}
+
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface SnapshotNode {
+  /** Element class/type (e.g., "android.widget.TextView", "UILabel") */
+  type: string;
+  /** Text content of the element */
+  text?: string;
+  /** Accessibility label */
+  label?: string;
+  /** Content description / accessibility hint */
+  description?: string;
+  /** Bounding box in screen coordinates */
+  bounds: Bounds;
+  /** Whether the element is interactive (clickable, tappable) */
+  interactive: boolean;
+  /** Whether the element is focused */
+  focused?: boolean;
+  /** Whether the element is enabled */
+  enabled?: boolean;
+  /** Whether the element is visible */
+  visible?: boolean;
+  /** Element value (for inputs, toggles, etc.) */
+  value?: string;
+  /** Resource ID (Android) or accessibility identifier (iOS) */
+  resourceId?: string;
+  /** Child elements */
+  children: SnapshotNode[];
+  /** Platform-specific raw attributes (for debugging) */
+  rawAttributes?: Record<string, string>;
+}
+
+export interface Device {
+  /** Get device information */
+  getInfo(): Promise<DeviceInfo>;
+
+  /** Get the accessibility tree of the current screen */
+  getSnapshot(): Promise<SnapshotNode>;
+
+  /** Take a screenshot, returns PNG buffer */
+  takeScreenshot(): Promise<Buffer>;
+
+  /** Tap at screen coordinates */
+  tap(x: number, y: number): Promise<void>;
+
+  /** Double-tap at screen coordinates */
+  doubleTap(x: number, y: number): Promise<void>;
+
+  /** Long press at screen coordinates */
+  longPress(x: number, y: number, durationMs?: number): Promise<void>;
+
+  /** Type text (assumes an input is already focused) */
+  typeText(text: string): Promise<void>;
+
+  /** Swipe from one point to another */
+  swipe(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    durationMs?: number
+  ): Promise<void>;
+
+  /** Press a hardware/system button */
+  pressButton(button: "home" | "back" | "enter"): Promise<void>;
+
+  /** Set device orientation */
+  setOrientation(orientation: "portrait" | "landscape"): Promise<void>;
+
+  /** Launch an app by its bundle/package ID */
+  launchApp(appId: string): Promise<void>;
+
+  /** Terminate a running app */
+  terminateApp(appId: string): Promise<void>;
+
+  /** Install an app from a file path */
+  installApp(path: string): Promise<void>;
+
+  /** List installed apps */
+  listApps(): Promise<AppInfo[]>;
+
+  /** Open a URL (deep link or web URL) */
+  openUrl(url: string): Promise<void>;
+}

package/src/platform/ios/accessibility.ts

@@ -0,0 +1,189 @@
+import type { SnapshotNode, Bounds } from "../device.js";
+
+/**
+ * Parses iOS accessibility output from `simctl ui` into SnapshotNode tree.
+ *
+ * The simctl accessibility output varies by iOS/Xcode version. This parser
+ * handles the common formats:
+ *
+ * Format 1 (structured):
+ *   Element: UIButton, Label: "Submit", Traits: Button, Frame: {{20, 100}, {340, 44}}
+ *
+ * Format 2 (XML-like from accessibility inspector):
+ *   <AXElement type="UIButton" label="Submit" frame="20 100 340 44" ...>
+ *
+ * When neither format is available, we fall back to a basic tree.
+ */
+export function parseIosAccessibilityOutput(
+  output: string
+): SnapshotNode {
+  // Try XML-like format first
+  if (output.includes("<AX") || output.includes("AXElement")) {
+    return parseAxFormat(output);
+  }
+
+  // Try structured text format
+  if (output.includes("Element:") || output.includes("Label:")) {
+    return parseStructuredFormat(output);
+  }
+
+  // Try simctl describe format (indented tree)
+  return parseDescribeFormat(output);
+}
+
+function parseAxFormat(output: string): SnapshotNode {
+  const root: SnapshotNode = createContainerNode("Screen");
+  const lines = output.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    const typeMatch = trimmed.match(/type[=:]\s*"?(\w+)"?/i);
+    const labelMatch = trimmed.match(/label[=:]\s*"([^"]*)"/i);
+    const frameMatch = trimmed.match(
+      /frame[=:]\s*"?(\d+)\s+(\d+)\s+(\d+)\s+(\d+)"?/i
+    );
+    const traitsMatch = trimmed.match(/traits?[=:]\s*"?([^">\n]+)"?/i);
+
+    if (typeMatch) {
+      const node: SnapshotNode = {
+        type: simplifyIosType(typeMatch[1]),
+        text: labelMatch ? labelMatch[1] : undefined,
+        label: labelMatch ? labelMatch[1] : undefined,
+        description: undefined,
+        bounds: frameMatch
+          ? {
+              x: parseInt(frameMatch[1]),
+              y: parseInt(frameMatch[2]),
+              width: parseInt(frameMatch[3]),
+              height: parseInt(frameMatch[4]),
+            }
+          : { x: 0, y: 0, width: 0, height: 0 },
+        interactive: isInteractiveTrait(traitsMatch?.[1] || ""),
+        children: [],
+      };
+      root.children.push(node);
+    }
+  }
+
+  return root;
+}
+
+function parseStructuredFormat(output: string): SnapshotNode {
+  const root: SnapshotNode = createContainerNode("Screen");
+  const blocks = output.split(/\n(?=Element:)/);
+
+  for (const block of blocks) {
+    const typeMatch = block.match(/Element:\s*(\w+)/);
+    const labelMatch = block.match(/Label:\s*"([^"]*)"/);
+    const frameMatch = block.match(
+      /Frame:\s*\{\{(\d+),\s*(\d+)\},\s*\{(\d+),\s*(\d+)\}\}/
+    );
+    const traitsMatch = block.match(/Traits?:\s*(.+)/);
+
+    if (typeMatch) {
+      const node: SnapshotNode = {
+        type: simplifyIosType(typeMatch[1]),
+        text: labelMatch ? labelMatch[1] : undefined,
+        label: labelMatch ? labelMatch[1] : undefined,
+        description: undefined,
+        bounds: frameMatch
+          ? {
+              x: parseInt(frameMatch[1]),
+              y: parseInt(frameMatch[2]),
+              width: parseInt(frameMatch[3]),
+              height: parseInt(frameMatch[4]),
+            }
+          : { x: 0, y: 0, width: 0, height: 0 },
+        interactive: isInteractiveTrait(traitsMatch?.[1] || ""),
+        children: [],
+      };
+      root.children.push(node);
+    }
+  }
+
+  return root;
+}
+
+function parseDescribeFormat(output: string): SnapshotNode {
+  const root: SnapshotNode = createContainerNode("Screen");
+  const lines = output.split("\n");
+
+  const stack: Array<{ node: SnapshotNode; indent: number }> = [
+    { node: root, indent: -1 },
+  ];
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+
+    // Parse "Type: Label" or just "Type"
+    const parts = trimmed.split(/:\s*/);
+    const type = parts[0] || "View";
+    const label = parts.length > 1 ? parts.slice(1).join(": ") : undefined;
+
+    const node: SnapshotNode = {
+      type: simplifyIosType(type),
+      text: label,
+      label,
+      description: undefined,
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      interactive: isInteractiveType(type),
+      children: [],
+    };
+
+    // Find parent based on indentation
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+
+    stack[stack.length - 1].node.children.push(node);
+    stack.push({ node, indent });
+  }
+
+  return root;
+}
+
+function createContainerNode(name: string): SnapshotNode {
+  return {
+    type: name,
+    bounds: { x: 0, y: 0, width: 0, height: 0 },
+    interactive: false,
+    children: [],
+  };
+}
+
+function simplifyIosType(type: string): string {
+  return type
+    .replace(/^UI/, "")
+    .replace(/^AX/, "")
+    .replace(/^_/, "");
+}
+
+function isInteractiveTrait(traits: string): boolean {
+  const lower = traits.toLowerCase();
+  return (
+    lower.includes("button") ||
+    lower.includes("link") ||
+    lower.includes("textfield") ||
+    lower.includes("searchfield") ||
+    lower.includes("adjustable") ||
+    lower.includes("toggle")
+  );
+}
+
+function isInteractiveType(type: string): boolean {
+  const lower = type.toLowerCase();
+  return (
+    lower.includes("button") ||
+    lower.includes("textfield") ||
+    lower.includes("textview") ||
+    lower.includes("switch") ||
+    lower.includes("slider") ||
+    lower.includes("picker") ||
+    lower.includes("link")
+  );
+}

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

@@ -0,0 +1,116 @@
+import type { Device, DeviceInfo, AppInfo, SnapshotNode } from "../device.js";
+import { Simctl } from "./simctl.js";
+import { parseIosAccessibilityOutput } from "./accessibility.js";
+
+export class IosDevice implements Device {
+  private simctl: Simctl;
+
+  constructor(private deviceId: string) {
+    this.simctl = new Simctl(deviceId);
+  }
+
+  async getInfo(): Promise<DeviceInfo> {
+    const [deviceInfo, screenSize] = await Promise.all([
+      this.simctl.getDeviceInfo(),
+      this.simctl.getScreenSize(),
+    ]);
+
+    return {
+      id: this.deviceId,
+      name: deviceInfo.name,
+      platform: "ios",
+      osVersion: deviceInfo.runtime,
+      screenWidth: screenSize.width,
+      screenHeight: screenSize.height,
+      orientation: "portrait", // Default; would need to query actual orientation
+      isBooted: deviceInfo.state === "Booted",
+    };
+  }
+
+  async getSnapshot(): Promise<SnapshotNode> {
+    const output = await this.simctl.getAccessibilityTree();
+    return parseIosAccessibilityOutput(output);
+  }
+
+  async takeScreenshot(): Promise<Buffer> {
+    return this.simctl.screenshot();
+  }
+
+  async tap(x: number, y: number): Promise<void> {
+    await this.simctl.tap(x, y);
+  }
+
+  async doubleTap(x: number, y: number): Promise<void> {
+    await this.simctl.tap(x, y);
+    await sleep(100);
+    await this.simctl.tap(x, y);
+  }
+
+  async longPress(x: number, y: number, _durationMs = 1000): Promise<void> {
+    // simctl doesn't have a native long-press; we hold via swipe-in-place
+    await this.simctl.swipe(x, y, x, y);
+  }
+
+  async typeText(text: string): Promise<void> {
+    await this.simctl.typeText(text);
+  }
+
+  async swipe(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    _durationMs = 300
+  ): Promise<void> {
+    await this.simctl.swipe(startX, startY, endX, endY);
+  }
+
+  async pressButton(button: "home" | "back" | "enter"): Promise<void> {
+    switch (button) {
+      case "home":
+        await this.simctl.pressKey("home");
+        break;
+      case "back":
+        // iOS doesn't have a hardware back button; swipe from left edge
+        const screenSize = await this.simctl.getScreenSize();
+        await this.simctl.swipe(0, screenSize.height / 2, screenSize.width / 2, screenSize.height / 2);
+        break;
+      case "enter":
+        await this.simctl.pressKey("return");
+        break;
+    }
+  }
+
+  async setOrientation(orientation: "portrait" | "landscape"): Promise<void> {
+    await this.simctl.setOrientation(orientation);
+  }
+
+  async launchApp(appId: string): Promise<void> {
+    await this.simctl.launchApp(appId);
+  }
+
+  async terminateApp(appId: string): Promise<void> {
+    await this.simctl.terminateApp(appId);
+  }
+
+  async installApp(path: string): Promise<void> {
+    await this.simctl.installApp(path);
+  }
+
+  async listApps(): Promise<AppInfo[]> {
+    const apps = await this.simctl.listApps();
+    return apps.map((app) => ({
+      appId: app.bundleId,
+      name: app.name,
+      isRunning: false,
+    }));
+  }
+
+  async openUrl(url: string): Promise<void> {
+    await this.simctl.openUrl(url);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}