@sensaiorg/adapter-ios 0.1.0

package/dist/transport/simctl-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simctl-client.d.ts","sourceRoot":"","sources":["../../src/transport/simctl-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAuB;gBAE1B,WAAW,EAAE,MAAM;IAI/B;;OAEG;YACW,SAAS;IAwBvB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;OAEG;YACW,GAAG;IAejB;;OAEG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAapE;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC;IAgD7C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IASnC;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzG;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAIpC;;OAEG;IACG,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IASnE;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAMxC;;OAEG;IACG,YAAY,CAAC,OAAO,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAUhD;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,QAAQ,IAAI,OAAO;CAGpB"}

package/dist/transport/simctl-client.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimctlClient = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+class SimctlClient {
+    simulatorId;
+    bootedState = false;
+    idbPath = null;
+    constructor(simulatorId) {
+        this.simulatorId = simulatorId;
+    }
+    /**
+     * Detect idb binary path asynchronously. Checks common locations.
+     */
+    async detectIdb() {
+        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);
+        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() {
+        await this.detectIdb();
+    }
+    /**
+     * Execute an idb command. Throws if idb is not available.
+     */
+    async idb(subcommands, args = []) {
+        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, args = []) {
+        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() {
+        try {
+            const { stdout } = await execFileAsync("xcrun", [
+                "simctl", "list", "devices", "--json",
+            ], { timeout: 10_000 });
+            const data = JSON.parse(stdout);
+            // 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() {
+        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(() => { });
+        return data;
+    }
+    /**
+     * Launch an app by bundle ID.
+     */
+    async launchApp(bundleId) {
+        await this.exec("launch", [bundleId]);
+    }
+    /**
+     * Terminate an app by bundle ID.
+     */
+    async terminateApp(bundleId) {
+        await this.exec("terminate", [bundleId]);
+    }
+    /**
+     * Tap at screen coordinates using idb.
+     */
+    async tap(x, y) {
+        await this.idb(["ui", "tap"], [String(x), String(y)]);
+    }
+    /**
+     * Type text into the focused field using idb.
+     */
+    async typeText(text) {
+        await this.idb(["ui", "text"], [text]);
+    }
+    /**
+     * Swipe from one point to another using idb.
+     */
+    async swipe(startX, startY, endX, endY, durationSec = 0.3) {
+        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() {
+        return this.idb(["ui", "describe-all"]);
+    }
+    /**
+     * Describe accessibility element at a point using idb.
+     */
+    async describePoint(x, y) {
+        return this.idb(["ui", "describe-point"], [String(x), String(y)]);
+    }
+    /**
+     * Check if idb is available for interaction commands.
+     */
+    hasIdb() {
+        return this.idbPath !== null;
+    }
+    /**
+     * Get recent logs from the simulator.
+     */
+    async getLogs(predicate, duration = "30s") {
+        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() {
+        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) {
+        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) {
+        await this.idb(["ui", "key"], [String(keycode)]);
+    }
+    isBooted() {
+        return this.bootedState;
+    }
+}
+exports.SimctlClient = SimctlClient;
+//# sourceMappingURL=simctl-client.js.map

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@sensaiorg/adapter-ios",
+  "version": "0.1.0",
+  "description": "SensAI iOS adapter — debug iOS apps via xcrun simctl and Xcode instruments",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@sensaiorg/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @sensai/adapter-ios — iOS platform adapter for SensAI.
+ *
+ * Provides debugging tools via xcrun simctl, Xcode instruments, and
+ * optionally an on-device debug agent for React Native inspection.
+ */
+
+export { IosAdapter } from "./ios-adapter.js";

package/src/ios-adapter.ts

@@ -0,0 +1,104 @@
+/**
+ * IosAdapter — implements IPlatformAdapter for iOS Simulator and devices.
+ *
+ * Uses:
+ * - xcrun simctl: screenshots, app lifecycle, UI hierarchy, status bar
+ * - Xcode instruments: performance profiling
+ * - Safari Web Inspector Protocol: WebView debugging
+ * - IDB (Facebook's iOS Development Bridge): advanced interactions
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {
+  IPlatformAdapter,
+  IUiProvider,
+  ILogProvider,
+  IInteractionProvider,
+  INetworkProvider,
+  IPerformanceProvider,
+  IScreenshotProvider,
+  IAppStateProvider,
+  PlatformCapabilities,
+  ConnectionStatus,
+} from "@sensai/core";
+
+import { SimctlClient } from "./transport/simctl-client.js";
+import { registerIosTools } from "./tools/ios-tools.js";
+
+export interface IosAdapterConfig {
+  /** Specific simulator UDID (default: "booted" = first booted simulator) */
+  simulatorId?: string;
+  /** Bundle ID of the target app */
+  bundleId?: string;
+  /** Path to idb binary (optional, for advanced features) */
+  idbPath?: string;
+}
+
+export class IosAdapter implements IPlatformAdapter {
+  readonly platform = "ios" as const;
+  readonly displayName: string;
+  readonly capabilities: PlatformCapabilities = {
+    uiTree: true,        // via XCUITest accessibility hierarchy
+    logs: true,          // via os_log / simctl spawn log
+    interaction: true,   // via simctl ui / idb
+    network: false,      // Future: mitmproxy integration
+    performance: true,   // via instruments
+    screenshot: true,    // via simctl io screenshot
+    appState: false,     // Future: on-device agent
+    hotReload: true,     // Metro bundler (React Native)
+    evalCode: false,
+  };
+
+  private readonly config: Required<IosAdapterConfig>;
+  private readonly simctl: SimctlClient;
+
+  readonly ui: IUiProvider | null = null;          // TODO: SimctlUiProvider
+  readonly logs: ILogProvider | null = null;        // TODO: OsLogProvider
+  readonly interaction: IInteractionProvider | null = null;  // TODO: SimctlInteractionProvider
+  readonly network: INetworkProvider | null = null;
+  readonly performance: IPerformanceProvider | null = null;  // TODO: InstrumentsProvider
+  readonly screenshot: IScreenshotProvider | null = null;    // TODO: SimctlScreenshotProvider
+  readonly appState: IAppStateProvider | null = null;
+
+  constructor(config: IosAdapterConfig = {}) {
+    this.config = {
+      simulatorId: config.simulatorId ?? "booted",
+      bundleId: config.bundleId ?? process.env.IOS_BUNDLE_ID ?? "com.chronocrew",
+      idbPath: config.idbPath ?? process.env.IDB_PATH ?? "idb",
+    };
+
+    this.displayName = `iOS Simulator (${this.config.simulatorId})`;
+    this.simctl = new SimctlClient(this.config.simulatorId);
+  }
+
+  async initialize(): Promise<ConnectionStatus> {
+    await this.simctl.initIdb();
+    const deviceInfo = await this.simctl.getDeviceInfo();
+
+    return {
+      platform: "ios",
+      device: deviceInfo.name ?? this.config.simulatorId,
+      connected: deviceInfo.booted,
+      capabilities: this.capabilities,
+      details: {
+        udid: deviceInfo.udid,
+        runtime: deviceInfo.runtime,
+        bundleId: this.config.bundleId,
+      },
+    };
+  }
+
+  shutdown(): void {
+    // No persistent connections to clean up for simctl
+  }
+
+  isConnected(): boolean {
+    return this.simctl.isBooted();
+  }
+
+  registerPlatformTools(server: McpServer): void {
+    // Use "ios_" prefix so tools don't clash with Android tool names
+    const prefix = "ios_";
+    registerIosTools(server, this.simctl, this.config.bundleId, prefix);
+  }
+}