@sensaiorg/adapter-ios 0.1.0

package/src/transport/simctl-client.ts

@@ -0,0 +1,264 @@
+/**
+ * SimctlClient — wraps xcrun simctl + idb commands for iOS Simulator interaction.
+ *
+ * Uses simctl for: screenshots, app lifecycle, logs, device info
+ * Uses idb for: tap, type, swipe (simctl doesn't support these)
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface SimulatorInfo {
+  udid: string;
+  name: string;
+  runtime: string;
+  state: string;
+  booted: boolean;
+}
+
+export class SimctlClient {
+  private readonly simulatorId: string;
+  private bootedState = false;
+  private idbPath: string | null = null;
+
+  constructor(simulatorId: string) {
+    this.simulatorId = simulatorId;
+  }
+
+  /**
+   * Detect idb binary path asynchronously. Checks common locations.
+   */
+  private async detectIdb(): Promise<void> {
+    const candidates = [
+      process.env.IDB_PATH,
+      process.env.HOME + "/Library/Python/3.9/bin/idb",
+      process.env.HOME + "/Library/Python/3.11/bin/idb",
+      process.env.HOME + "/Library/Python/3.12/bin/idb",
+      "/usr/local/bin/idb",
+      "/opt/homebrew/bin/idb",
+      "idb",  // fallback to PATH
+    ].filter(Boolean) as string[];
+
+    for (const candidate of candidates) {
+      try {
+        await execFileAsync(candidate, ["--help"], {
+          timeout: 5_000,
+        });
+        this.idbPath = candidate;
+        return;
+      } catch {
+        // try next
+      }
+    }
+  }
+
+  /**
+   * Initialize idb detection. Call this before using interaction commands.
+   */
+  async initIdb(): Promise<void> {
+    await this.detectIdb();
+  }
+
+  /**
+   * Execute an idb command. Throws if idb is not available.
+   */
+  private async idb(subcommands: string[], args: string[] = []): Promise<string> {
+    if (!this.idbPath) {
+      throw new Error(
+        "idb (Facebook's iOS Development Bridge) is not installed. " +
+        "Install with: pip3 install fb-idb. " +
+        "Also ensure idb_companion is installed: brew install idb-companion"
+      );
+    }
+    const { stdout } = await execFileAsync(this.idbPath, [
+      ...subcommands,
+      ...args,
+    ], { timeout: 15_000 });
+    return stdout;
+  }
+
+  /**
+   * Execute a simctl command.
+   */
+  async exec(subcommand: string, args: string[] = []): Promise<string> {
+    const { stdout } = await execFileAsync("xcrun", [
+      "simctl",
+      subcommand,
+      this.simulatorId,
+      ...args,
+    ], {
+      timeout: 30_000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    return stdout;
+  }
+
+  /**
+   * Get simulator device info.
+   */
+  async getDeviceInfo(): Promise<SimulatorInfo> {
+    try {
+      const { stdout } = await execFileAsync("xcrun", [
+        "simctl", "list", "devices", "--json",
+      ], { timeout: 10_000 });
+
+      const data = JSON.parse(stdout) as { devices: Record<string, Array<{
+        udid: string; name: string; state: string;
+      }>> };
+
+      // Find our simulator
+      for (const [runtime, devices] of Object.entries(data.devices)) {
+        for (const device of devices) {
+          const isTarget = this.simulatorId === "booted"
+            ? device.state === "Booted"
+            : device.udid === this.simulatorId;
+
+          if (isTarget) {
+            this.bootedState = device.state === "Booted";
+            return {
+              udid: device.udid,
+              name: device.name,
+              runtime,
+              state: device.state,
+              booted: this.bootedState,
+            };
+          }
+        }
+      }
+
+      return {
+        udid: this.simulatorId,
+        name: "Unknown",
+        runtime: "Unknown",
+        state: "Shutdown",
+        booted: false,
+      };
+    } catch {
+      return {
+        udid: this.simulatorId,
+        name: "Not Available",
+        runtime: "Unknown",
+        state: "Not Available",
+        booted: false,
+      };
+    }
+  }
+
+  /**
+   * Take a screenshot and return as base64 PNG.
+   */
+  async screenshot(): Promise<Buffer> {
+    const tmpPath = `/tmp/sensai-ios-${Date.now()}.png`;
+    await this.exec("io", ["screenshot", tmpPath]);
+    const { readFile, unlink } = await import("node:fs/promises");
+    const data = await readFile(tmpPath);
+    await unlink(tmpPath).catch(() => { /* ignore cleanup errors */ });
+    return data;
+  }
+
+  /**
+   * Launch an app by bundle ID.
+   */
+  async launchApp(bundleId: string): Promise<void> {
+    await this.exec("launch", [bundleId]);
+  }
+
+  /**
+   * Terminate an app by bundle ID.
+   */
+  async terminateApp(bundleId: string): Promise<void> {
+    await this.exec("terminate", [bundleId]);
+  }
+
+  /**
+   * Tap at screen coordinates using idb.
+   */
+  async tap(x: number, y: number): Promise<void> {
+    await this.idb(["ui", "tap"], [String(x), String(y)]);
+  }
+
+  /**
+   * Type text into the focused field using idb.
+   */
+  async typeText(text: string): Promise<void> {
+    await this.idb(["ui", "text"], [text]);
+  }
+
+  /**
+   * Swipe from one point to another using idb.
+   */
+  async swipe(startX: number, startY: number, endX: number, endY: number, durationSec = 0.3): Promise<void> {
+    await this.idb(["ui", "swipe"], [
+      String(startX), String(startY), String(endX), String(endY),
+      "--duration", String(durationSec),
+    ]);
+  }
+
+  /**
+   * Describe all accessibility elements on screen using idb.
+   */
+  async describeAll(): Promise<string> {
+    return this.idb(["ui", "describe-all"]);
+  }
+
+  /**
+   * Describe accessibility element at a point using idb.
+   */
+  async describePoint(x: number, y: number): Promise<string> {
+    return this.idb(["ui", "describe-point"], [String(x), String(y)]);
+  }
+
+  /**
+   * Check if idb is available for interaction commands.
+   */
+  hasIdb(): boolean {
+    return this.idbPath !== null;
+  }
+
+  /**
+   * Get recent logs from the simulator.
+   */
+  async getLogs(predicate: string, duration = "30s"): Promise<string> {
+    const { stdout } = await execFileAsync("xcrun", [
+      "simctl", "spawn", this.simulatorId, "log", "show",
+      "--last", duration,
+      "--predicate", predicate,
+    ], { timeout: 30_000, maxBuffer: 10 * 1024 * 1024 });
+    return stdout;
+  }
+
+  /**
+   * Get the resolved UDID (needed for spawn commands when using "booted").
+   */
+  async getResolvedUdid(): Promise<string> {
+    if (this.simulatorId !== "booted") return this.simulatorId;
+    const info = await this.getDeviceInfo();
+    return info.udid;
+  }
+
+  /**
+   * Get crash/exception logs from the last N minutes.
+   */
+  async getCrashLogs(minutes = 5): Promise<string> {
+    const { stdout } = await execFileAsync("xcrun", [
+      "simctl", "spawn", this.simulatorId, "log", "show",
+      "--last", `${minutes}m`,
+      "--predicate",
+      'eventMessage contains "crash" OR eventMessage contains "exception" OR eventMessage contains "fatal" OR eventMessage contains "SIGABRT"',
+    ], { timeout: 30_000, maxBuffer: 10 * 1024 * 1024 });
+    return stdout;
+  }
+
+  /**
+   * Send key input to the simulator via idb.
+   */
+  async keyPress(keycode: number): Promise<void> {
+    await this.idb(["ui", "key"], [String(keycode)]);
+  }
+
+  isBooted(): boolean {
+    return this.bootedState;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "references": [
+    { "path": "../core" }
+  ]
+}