@ceraph/react-native-mcp 0.2.2 → 0.3.2

package/dist/utils/atomic-write.d.ts

@@ -0,0 +1 @@
+export declare function writeFileAtomic(path: string, contents: string | Buffer): Promise<void>;

package/dist/utils/atomic-write.js

@@ -0,0 +1,30 @@
+import { chmod, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export async function writeFileAtomic(path, contents) {
+    const dir = dirname(path);
+    const tmp = join(dir, `${path.slice(dir.length + 1)}.tmp.${process.pid}.${Math.random()
+        .toString(36)
+        .slice(2)}`);
+    let existingMode;
+    try {
+        const st = await stat(path);
+        existingMode = st.mode & 0o777;
+    }
+    catch {
+    }
+    try {
+        await writeFile(tmp, contents, "utf-8");
+        if (existingMode !== undefined) {
+            await chmod(tmp, existingMode);
+        }
+        await rename(tmp, path);
+    }
+    catch (err) {
+        try {
+            await unlink(tmp);
+        }
+        catch {
+        }
+        throw err;
+    }
+}

package/dist/wait-for-device.d.ts

@@ -0,0 +1,68 @@
+export interface WaitForDeviceOptions {
+    signal?: AbortSignal;
+    fallbackPollIntervalMs?: number;
+    timeoutMs?: number;
+}
+export interface WaitForDeviceResult {
+    deviceFound: true;
+    udid: string;
+    name?: string;
+    waitedMs: number;
+    source: "usbmuxd" | "polling-fallback";
+}
+export type WaitForDeviceOpts = WaitForDeviceOptions;
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface UsbmuxdSocketLike {
+    write(buf: Buffer): boolean;
+    on(event: "data", cb: (chunk: Buffer) => void): this;
+    on(event: "error", cb: (err: Error) => void): this;
+    on(event: "close", cb: () => void): this;
+    destroy(err?: Error): void;
+}
+export interface WaitForDeviceDeps {
+    runner: (cmd: string, args: string[], timeoutMs?: number) => Promise<CommandResult>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+    openSocket?: () => Promise<UsbmuxdSocketLike>;
+}
+export declare const defaultWaitForDeviceDeps: WaitForDeviceDeps;
+export declare function buildListenRequest(tag?: number): Buffer;
+export interface UsbmuxdMessage {
+    payload: Record<string, unknown>;
+}
+export declare class UsbmuxdFramer {
+    private buf;
+    feed(chunk: Buffer): UsbmuxdMessage[];
+}
+interface DevicectlDevice {
+    identifier?: string;
+    hardwareProperties?: {
+        platform?: string;
+    };
+    connectionProperties?: {
+        tunnelState?: string;
+        transportType?: string;
+    };
+    deviceProperties?: {
+        name?: string;
+    };
+}
+interface DevicectlListPayload {
+    result?: {
+        devices?: DevicectlDevice[];
+    };
+}
+export declare function pickFirstIosDevice(payload: DevicectlListPayload): {
+    udid: string;
+    name: string;
+} | null;
+export declare function extractAttachedDevice(payload: Record<string, unknown>): {
+    udid: string;
+    name?: string;
+} | null;
+export declare function waitForDevice(opts?: WaitForDeviceOptions, deps?: WaitForDeviceDeps): Promise<WaitForDeviceResult>;
+export {};

package/dist/wait-for-device.js

@@ -0,0 +1,368 @@
+import { spawn } from "node:child_process";
+import * as net from "node:net";
+import * as plist from "plist";
+async function defaultRunner(cmd, args, timeoutMs = 15_000) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let child;
+        try {
+            child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (err) {
+            resolve({
+                code: 127,
+                stdout: "",
+                stderr: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+            }
+        }, timeoutMs);
+        child.stdout?.on("data", (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on("data", (d) => {
+            stderr += d.toString();
+        });
+        let settled = false;
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                code: 127,
+                stdout,
+                stderr: stderr + (err.message ?? String(err)),
+            });
+        });
+        child.on("exit", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function defaultOpenSocket() {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection("/var/run/usbmuxd");
+        let settled = false;
+        socket.once("connect", () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.removeListener("error", onError);
+            resolve(socket);
+        });
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+            }
+            reject(err);
+        };
+        socket.once("error", onError);
+    });
+}
+export const defaultWaitForDeviceDeps = {
+    runner: defaultRunner,
+    sleep: defaultSleep,
+    now: () => Date.now(),
+    openSocket: defaultOpenSocket,
+};
+const USBMUXD_VERSION_PLIST = 1;
+const USBMUXD_MESSAGE_PLIST = 8;
+const USBMUXD_HEADER_BYTES = 16;
+export function buildListenRequest(tag = 1) {
+    const payload = plist.build({
+        MessageType: "Listen",
+        ClientVersionString: "ceraph-react-native-mcp",
+        ProgName: "ceraph-react-native-mcp",
+        kLibUSBMuxVersion: 3,
+    });
+    const payloadBuf = Buffer.from(payload, "utf8");
+    const header = Buffer.alloc(USBMUXD_HEADER_BYTES);
+    header.writeUInt32LE(USBMUXD_HEADER_BYTES + payloadBuf.length, 0);
+    header.writeUInt32LE(USBMUXD_VERSION_PLIST, 4);
+    header.writeUInt32LE(USBMUXD_MESSAGE_PLIST, 8);
+    header.writeUInt32LE(tag, 12);
+    return Buffer.concat([header, payloadBuf]);
+}
+export class UsbmuxdFramer {
+    buf = Buffer.alloc(0);
+    feed(chunk) {
+        this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+        const out = [];
+        while (this.buf.length >= USBMUXD_HEADER_BYTES) {
+            const length = this.buf.readUInt32LE(0);
+            if (length < USBMUXD_HEADER_BYTES || length > 1_048_576) {
+                this.buf = Buffer.alloc(0);
+                return out;
+            }
+            if (this.buf.length < length) {
+                return out;
+            }
+            const body = this.buf.subarray(USBMUXD_HEADER_BYTES, length);
+            this.buf = this.buf.subarray(length);
+            const parsed = parsePlistSafe(body);
+            if (parsed)
+                out.push({ payload: parsed });
+        }
+        return out;
+    }
+}
+function parsePlistSafe(body) {
+    try {
+        const text = body.toString("utf8");
+        const parsed = plist.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function pickFirstIosDevice(payload) {
+    const devices = payload.result?.devices ?? [];
+    if (devices.length === 0)
+        return null;
+    const isIos = (d) => (d.hardwareProperties?.platform?.toLowerCase() ?? "").includes("ios");
+    const connected = devices.find((d) => {
+        const tunnel = d.connectionProperties?.tunnelState?.toLowerCase() ?? "";
+        return isIos(d) && tunnel === "connected";
+    });
+    const pick = connected ?? devices.find(isIos);
+    if (!pick?.identifier)
+        return null;
+    return {
+        udid: pick.identifier,
+        name: pick.deviceProperties?.name ?? pick.identifier,
+    };
+}
+async function probeOnce(deps) {
+    const res = await deps.runner("xcrun", ["devicectl", "list", "devices", "--json-output", "-"], 8_000);
+    if (res.code !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(res.stdout);
+        return pickFirstIosDevice(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function extractAttachedDevice(payload) {
+    if (payload.MessageType !== "Attached")
+        return null;
+    const props = payload.Properties;
+    if (!props || typeof props !== "object")
+        return null;
+    const serial = props.SerialNumber;
+    if (typeof serial !== "string" || serial.length === 0)
+        return null;
+    const rawName = props.DeviceName;
+    const name = typeof rawName === "string" && rawName.length > 0 ? rawName : undefined;
+    return { udid: serial, name };
+}
+export async function waitForDevice(opts = {}, deps = defaultWaitForDeviceDeps) {
+    const signal = opts.signal;
+    const now = deps.now ?? (() => Date.now());
+    if (signal?.aborted)
+        throw new Error("aborted");
+    const start = now();
+    const initial = await probeOnce(deps);
+    if (initial) {
+        return {
+            deviceFound: true,
+            udid: initial.udid,
+            name: initial.name,
+            waitedMs: 0,
+            source: "usbmuxd",
+        };
+    }
+    if (signal?.aborted)
+        throw new Error("aborted");
+    const openSocket = deps.openSocket ?? defaultOpenSocket;
+    let socket;
+    try {
+        socket = await openSocket();
+    }
+    catch {
+        process.stderr.write("[ceraph][rn_wait_for_device] usbmuxd socket unavailable; " +
+            "falling back to polling. Install Xcode for sub-second device detection.\n");
+        return pollUntilDevicePresent(opts, deps, start);
+    }
+    return listenForAttached(socket, opts, deps, start);
+}
+function listenForAttached(socket, opts, deps, start) {
+    const signal = opts.signal;
+    const now = deps.now ?? (() => Date.now());
+    return new Promise((resolve, reject) => {
+        const framer = new UsbmuxdFramer();
+        let settled = false;
+        let timer;
+        const finalize = () => {
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+            try {
+                socket.destroy();
+            }
+            catch {
+            }
+        };
+        const settleResolve = (v) => {
+            if (settled)
+                return;
+            finalize();
+            resolve(v);
+        };
+        const settleReject = (e) => {
+            if (settled)
+                return;
+            finalize();
+            reject(e);
+        };
+        const onAbort = () => settleReject(new Error("aborted"));
+        const onError = (_err) => {
+            if (settled)
+                return;
+            finalize();
+            pollUntilDevicePresent(opts, deps, start).then(resolve, reject);
+        };
+        const onClose = () => {
+            if (settled)
+                return;
+            finalize();
+            pollUntilDevicePresent(opts, deps, start).then(resolve, reject);
+        };
+        const onData = (chunk) => {
+            if (settled)
+                return;
+            const messages = framer.feed(chunk);
+            for (const msg of messages) {
+                const device = extractAttachedDevice(msg.payload);
+                if (device) {
+                    settleResolve({
+                        deviceFound: true,
+                        udid: device.udid,
+                        name: device.name,
+                        waitedMs: now() - start,
+                        source: "usbmuxd",
+                    });
+                    return;
+                }
+            }
+        };
+        socket.on("data", onData);
+        socket.on("error", onError);
+        socket.on("close", onClose);
+        if (signal) {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        if (typeof opts.timeoutMs === "number" && opts.timeoutMs > 0) {
+            const remaining = opts.timeoutMs - (now() - start);
+            const deadline = Math.max(remaining, 0);
+            timer = setTimeout(() => {
+                settleReject(new Error(formatTimeoutMessage(opts.timeoutMs)));
+            }, deadline);
+        }
+        try {
+            socket.write(buildListenRequest());
+        }
+        catch (err) {
+            if (settled)
+                return;
+            finalize();
+            pollUntilDevicePresent(opts, deps, start).then(resolve, reject);
+        }
+    });
+}
+function formatTimeoutMessage(timeoutMs) {
+    const minutes = Math.round(timeoutMs / 60_000);
+    const minutesLabel = minutes === 1 ? "1 minute" : `${minutes} minutes`;
+    return (`No device connected after ${minutesLabel}. Connect your iPhone ` +
+        "via USB-C and trust this Mac, then re-run the original tool.");
+}
+async function pollUntilDevicePresent(opts, deps, start) {
+    const pollIntervalMs = opts.fallbackPollIntervalMs ?? 10_000;
+    const signal = opts.signal;
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? (() => Date.now());
+    while (true) {
+        if (signal?.aborted)
+            throw new Error("aborted");
+        if (typeof opts.timeoutMs === "number" && opts.timeoutMs > 0) {
+            const elapsed = now() - start;
+            const remaining = opts.timeoutMs - elapsed;
+            if (remaining <= 0) {
+                throw new Error(formatTimeoutMessage(opts.timeoutMs));
+            }
+            const waitMs = Math.min(pollIntervalMs, remaining);
+            try {
+                await sleep(waitMs, signal);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message === "aborted")
+                    throw err;
+                throw new Error(`wait-for-device sleep failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            try {
+                await sleep(pollIntervalMs, signal);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message === "aborted")
+                    throw err;
+                throw new Error(`wait-for-device sleep failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (signal?.aborted)
+            throw new Error("aborted");
+        const found = await probeOnce(deps);
+        if (found) {
+            return {
+                deviceFound: true,
+                udid: found.udid,
+                name: found.name,
+                waitedMs: now() - start,
+                source: "polling-fallback",
+            };
+        }
+    }
+}

package/dist/wda-manager.d.ts

@@ -0,0 +1,38 @@
+import type { TargetResolver } from "./target.js";
+import { type LaunchFailureReason, type WdaSimulatorSession } from "./wda-simulator.js";
+export interface StartOpts {
+    udid?: string;
+    derivedDataPath?: string;
+    startupTimeoutMs?: number;
+}
+export type StartFailureReason = "no-booted-simulator" | "simulator-not-found" | LaunchFailureReason;
+export type StartResult = {
+    ok: true;
+    port: number;
+    udid: string;
+    reused: boolean;
+    projectPath: string;
+} | {
+    ok: false;
+    reason: StartFailureReason;
+    error: string;
+    output?: string[];
+};
+export declare class WdaManager {
+    private readonly target;
+    private readonly cacheDir;
+    private readonly projectDir;
+    private session;
+    private inflight;
+    private inflightChild;
+    private stopGeneration;
+    private stopping;
+    constructor(target: TargetResolver, cacheDir: string, projectDir: string);
+    getSession(): WdaSimulatorSession | null;
+    start(opts?: StartOpts): Promise<StartResult>;
+    stop(): Promise<{
+        stopped: boolean;
+        udid?: string;
+        port?: number;
+    }>;
+}

package/dist/wda-manager.js

@@ -0,0 +1,186 @@
+import { join } from "node:path";
+import { disableCaffeinate, enableCaffeinate } from "./mac-caffeinate.js";
+import { listBootedSimulators } from "./target.js";
+import { launchSimulatorWda, } from "./wda-simulator.js";
+export class WdaManager {
+    target;
+    cacheDir;
+    projectDir;
+    session = null;
+    inflight = null;
+    inflightChild = null;
+    stopGeneration = 0;
+    stopping = null;
+    constructor(target, cacheDir, projectDir) {
+        this.target = target;
+        this.cacheDir = cacheDir;
+        this.projectDir = projectDir;
+    }
+    getSession() {
+        return this.session;
+    }
+    async start(opts = {}) {
+        if (this.stopping) {
+            await this.stopping.catch(() => undefined);
+        }
+        if (this.session) {
+            const childAlive = this.session.process.exitCode === null;
+            const udidMatches = !opts.udid || opts.udid === this.session.udid;
+            if (childAlive && udidMatches) {
+                return {
+                    ok: true,
+                    port: this.session.port,
+                    udid: this.session.udid,
+                    reused: true,
+                    projectPath: this.session.projectPath,
+                };
+            }
+            if (childAlive && !udidMatches) {
+                await this.stop().catch(() => undefined);
+            }
+            else {
+                this.session = null;
+                this.target.clearSimulatorWdaPort();
+            }
+        }
+        if (this.inflight)
+            return this.inflight;
+        const stopGenerationAtStart = this.stopGeneration;
+        const work = (async () => {
+            const sims = await listBootedSimulators();
+            if (sims.length === 0) {
+                return {
+                    ok: false,
+                    reason: "no-booted-simulator",
+                    error: "No booted iOS simulator found. Boot one first: " +
+                        "`xcrun simctl boot <udid>` or open it via " +
+                        "`open -a Simulator` and pick a device. Then retry " +
+                        "`rn_wda_start`.",
+                };
+            }
+            let picked;
+            if (opts.udid) {
+                const found = sims.find((s) => s.udid === opts.udid);
+                if (!found) {
+                    return {
+                        ok: false,
+                        reason: "simulator-not-found",
+                        error: `Simulator UDID ${opts.udid} is not booted. Booted ` +
+                            `simulators: ${sims.map((s) => `${s.name} (${s.udid})`).join(", ")}.`,
+                    };
+                }
+                picked = found;
+            }
+            else {
+                picked = sims[0];
+            }
+            const launchOpts = {
+                udid: picked.udid,
+                projectDir: this.projectDir,
+                derivedDataPath: opts.derivedDataPath ?? join(this.cacheDir, "wda-derived"),
+                startupTimeoutMs: opts.startupTimeoutMs,
+                onChildSpawned: (child) => {
+                    this.inflightChild = child;
+                },
+            };
+            let result;
+            try {
+                result = await launchSimulatorWda(launchOpts);
+            }
+            finally {
+                this.inflightChild = null;
+            }
+            if (!result.ok) {
+                return {
+                    ok: false,
+                    reason: result.reason,
+                    error: result.error,
+                    output: result.output,
+                };
+            }
+            if (this.stopGeneration !== stopGenerationAtStart) {
+                await result.session.stop().catch(() => undefined);
+                return {
+                    ok: false,
+                    reason: "xcodebuild-exited-early",
+                    error: "`rn_wda_stop` (or MCP shutdown) ran while the simulator " +
+                        "WDA build was in flight. The build was terminated. Re-run " +
+                        "`rn_wda_start` if you still want a simulator session.",
+                };
+            }
+            this.session = result.session;
+            this.target.setSimulatorWdaPort(result.session.port, result.session.udid);
+            const session = result.session;
+            session.process.once("exit", () => {
+                if (this.session === session) {
+                    this.session = null;
+                    this.target.clearSimulatorWdaPort();
+                }
+            });
+            try {
+                enableCaffeinate();
+            }
+            catch {
+            }
+            return {
+                ok: true,
+                port: result.session.port,
+                udid: result.session.udid,
+                reused: false,
+                projectPath: result.session.projectPath,
+            };
+        })();
+        this.inflight = work;
+        try {
+            return await work;
+        }
+        finally {
+            this.inflight = null;
+        }
+    }
+    async stop() {
+        if (this.stopping) {
+            await this.stopping.catch(() => undefined);
+            return { stopped: false };
+        }
+        this.stopGeneration++;
+        let resolveStopping;
+        this.stopping = new Promise((r) => {
+            resolveStopping = r;
+        });
+        try {
+            const inflightChild = this.inflightChild;
+            this.inflightChild = null;
+            if (inflightChild && inflightChild.exitCode === null) {
+                try {
+                    inflightChild.kill("SIGTERM");
+                }
+                catch {
+                }
+            }
+            if (this.inflight) {
+                await this.inflight.catch(() => undefined);
+            }
+            if (!this.session)
+                return { stopped: false };
+            const { udid, port } = this.session;
+            try {
+                await this.session.stop();
+            }
+            finally {
+                this.session = null;
+                this.target.clearSimulatorWdaPort();
+            }
+            return { stopped: true, udid, port };
+        }
+        finally {
+            try {
+                disableCaffeinate();
+            }
+            catch {
+            }
+            resolveStopping();
+            this.stopping = null;
+        }
+    }
+}