devlens-mcp 0.3.0 → 0.3.1

package/src/platform/device.ts

@@ -1,110 +0,0 @@
-/**
- * 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

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

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

package/src/platform/ios/simctl.ts

@@ -1,244 +0,0 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
-
-const execFileAsync = promisify(execFile);
-
-/**
- * Wrapper around `xcrun simctl` for iOS Simulator interaction.
- */
-export class Simctl {
-  constructor(private deviceId: string) {}
-
-  /** Execute a simctl command */
-  async exec(...args: string[]): Promise<string> {
-    const { stdout } = await execFileAsync(
-      "xcrun",
-      ["simctl", ...args],
-      { maxBuffer: 10 * 1024 * 1024, timeout: 30000 }
-    );
-    return stdout;
-  }
-
-  /** Take a screenshot and return PNG buffer */
-  async screenshot(): Promise<Buffer> {
-    const tmpPath = `/tmp/devlens-screenshot-${Date.now()}.png`;
-    await this.exec("io", this.deviceId, "screenshot", tmpPath);
-
-    const { readFile, unlink } = await import("fs/promises");
-    const buffer = await readFile(tmpPath);
-    unlink(tmpPath).catch(() => {});
-    return buffer;
-  }
-
-  /** Get the accessibility tree using simctl's accessibility audit */
-  async getAccessibilityTree(): Promise<string> {
-    // Use simctl ui to get the accessibility hierarchy
-    try {
-      const output = await this.exec(
-        "ui",
-        this.deviceId,
-        "accessibility",
-      );
-      return output;
-    } catch {
-      // Fallback: use the description command for view hierarchy
-      return this.getViewHierarchyViaXctest();
-    }
-  }
-
-  /**
-   * Fallback: Get view hierarchy by running a small XCTest snippet.
-   * This uses `simctl launch` with a debugger approach, but the simplest
-   * method is to use the accessibility description from the simulator.
-   */
-  private async getViewHierarchyViaXctest(): Promise<string> {
-    // Use the simctl subprocess to query the UI
-    // We'll use `simctl ui <device> describe` to get the UI hierarchy
-    try {
-      const output = await this.exec("ui", this.deviceId, "describe");
-      return output;
-    } catch {
-      throw new Error(
-        "Could not extract accessibility tree from iOS Simulator. " +
-          "Ensure the simulator is booted and has an app running."
-      );
-    }
-  }
-
-  /** Get device info from simctl */
-  async getDeviceInfo(): Promise<{
-    name: string;
-    runtime: string;
-    state: string;
-  }> {
-    const { stdout } = await execFileAsync("xcrun", [
-      "simctl",
-      "list",
-      "devices",
-      "--json",
-    ]);
-    const data = JSON.parse(stdout);
-
-    for (const [runtime, devices] of Object.entries(
-      data.devices as Record<string, Array<{ udid: string; name: string; state: string }>>
-    )) {
-      for (const device of devices) {
-        if (device.udid === this.deviceId) {
-          return {
-            name: device.name,
-            runtime: runtime
-              .replace(/^com\.apple\.CoreSimulator\.SimRuntime\./, "")
-              .replace(/-/g, "."),
-            state: device.state,
-          };
-        }
-      }
-    }
-    throw new Error(`Device ${this.deviceId} not found in simctl list`);
-  }
-
-  /** Get screen size of the simulator */
-  async getScreenSize(): Promise<{ width: number; height: number }> {
-    // Take a tiny screenshot and check its dimensions via sharp
-    const tmpPath = `/tmp/devlens-size-check-${Date.now()}.png`;
-    await this.exec("io", this.deviceId, "screenshot", tmpPath);
-
-    try {
-      const sharp = (await import("sharp")).default;
-      const metadata = await sharp(tmpPath).metadata();
-      const { unlink } = await import("fs/promises");
-      unlink(tmpPath).catch(() => {});
-
-      return {
-        width: metadata.width || 390,
-        height: metadata.height || 844,
-      };
-    } catch {
-      // Fallback defaults (iPhone 14)
-      return { width: 390, height: 844 };
-    }
-  }
-
-  /** Tap at coordinates using simctl */
-  async tap(x: number, y: number): Promise<void> {
-    // simctl doesn't have a direct tap command, so we use the io command
-    // with the AppleScript approach or the simctl interact command
-    try {
-      await this.exec(
-        "io",
-        this.deviceId,
-        "tap",
-        String(Math.round(x)),
-        String(Math.round(y))
-      );
-    } catch {
-      // Fallback: use AppleScript to tap on the simulator
-      await execFileAsync("osascript", [
-        "-e",
-        `tell application "Simulator" to activate`,
-      ]);
-      // Use cliclick or similar for coordinate-based tapping
-      throw new Error(
-        "Direct tap not supported on this simctl version. Consider using a newer Xcode."
-      );
-    }
-  }
-
-  /** Swipe on the simulator */
-  async swipe(
-    startX: number,
-    startY: number,
-    endX: number,
-    endY: number
-  ): Promise<void> {
-    try {
-      await this.exec(
-        "io",
-        this.deviceId,
-        "swipe",
-        String(Math.round(startX)),
-        String(Math.round(startY)),
-        String(Math.round(endX)),
-        String(Math.round(endY))
-      );
-    } catch {
-      throw new Error("Swipe not supported on this simctl version.");
-    }
-  }
-
-  /** Type text using simctl keyboard input */
-  async typeText(text: string): Promise<void> {
-    await this.exec("io", this.deviceId, "keyboard", "type", text);
-  }
-
-  /** Press a key using simctl */
-  async pressKey(key: string): Promise<void> {
-    await this.exec("io", this.deviceId, "keyboard", "key", key);
-  }
-
-  /** Launch an app */
-  async launchApp(bundleId: string): Promise<void> {
-    await this.exec("launch", this.deviceId, bundleId);
-  }
-
-  /** Terminate an app */
-  async terminateApp(bundleId: string): Promise<void> {
-    await this.exec("terminate", this.deviceId, bundleId);
-  }
-
-  /** Install an app (.app bundle or .ipa) */
-  async installApp(path: string): Promise<void> {
-    await this.exec("install", this.deviceId, path);
-  }
-
-  /** List installed apps */
-  async listApps(): Promise<Array<{ bundleId: string; name: string }>> {
-    try {
-      const output = await this.exec(
-        "listapps",
-        this.deviceId,
-      );
-      // Parse the plist/json output
-      const apps: Array<{ bundleId: string; name: string }> = [];
-      const bundleIdMatches = output.matchAll(
-        /"CFBundleIdentifier"\s*=\s*"([^"]+)"/g
-      );
-      const nameMatches = output.matchAll(
-        /"CFBundleDisplayName"\s*=\s*"([^"]+)"/g
-      );
-      const bundleIds = [...bundleIdMatches].map((m) => m[1]);
-      const names = [...nameMatches].map((m) => m[1]);
-
-      for (let i = 0; i < bundleIds.length; i++) {
-        apps.push({
-          bundleId: bundleIds[i],
-          name: names[i] || bundleIds[i],
-        });
-      }
-      return apps;
-    } catch {
-      return [];
-    }
-  }
-
-  /** Open a URL */
-  async openUrl(url: string): Promise<void> {
-    await this.exec("openurl", this.deviceId, url);
-  }
-
-  /** Set device orientation */
-  async setOrientation(orientation: "portrait" | "landscape"): Promise<void> {
-    // simctl doesn't have a direct orientation command
-    // Use the Simulator menu via AppleScript
-    const rotation = orientation === "portrait" ? "0" : "90";
-    try {
-      await execFileAsync("osascript", [
-        "-e",
-        `tell application "System Events" to tell process "Simulator" to ` +
-          `click menu item "Rotate ${orientation === "landscape" ? "Right" : "Left"}" of menu "Device" of menu bar 1`,
-      ]);
-    } catch {
-      // Orientation setting may not be available in all environments
-    }
-  }
-}