@ceraph/react-native-mcp 0.2.0

package/dist/expo-manager.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Manages React Native / Expo child processes (build and Metro dev server).
+ * Auto-detects whether the project uses Expo or bare React Native
+ * and runs the appropriate commands.
+ * Captures stdout/stderr into rolling buffers and parses errors.
+ */
+import { type Warning, type AllErrors } from "./error-parser.js";
+export interface BuildResult {
+    success: boolean;
+    errors: Array<{
+        file: string;
+        line: number;
+        message: string;
+        type: "build" | "link" | "pod";
+    }>;
+    warnings: Warning[];
+    output: string;
+}
+interface RunBuildOptions {
+    clean?: boolean;
+    device?: string;
+}
+interface StartMetroOptions {
+    port?: number;
+    clear?: boolean;
+}
+interface ConsoleOptions {
+    lines?: number;
+    level?: "all" | "error" | "warn" | "log";
+}
+export declare class RNManager {
+    private buildProcess;
+    private metroProcess;
+    private buildKilled;
+    private metroKilled;
+    private buildOutput;
+    private metroOutput;
+    private buildErrors;
+    private runtimeErrors;
+    private buildWarnings;
+    private metroWarnings;
+    private metroParser;
+    private readonly MAX_BUILD_LINES;
+    private readonly MAX_METRO_LINES;
+    private readonly MAX_ERRORS;
+    /** The working directory for commands. */
+    private cwd;
+    /** Path to the error file that triggers the Claude Code hook. */
+    private errorFilePath;
+    constructor(cwd: string);
+    /**
+     * Detect whether this is an Expo or bare React Native project.
+     * Checks for app.json with expo config or expo package in dependencies.
+     */
+    detectProjectType(): Promise<boolean>;
+    /**
+     * Write errors to .rn-errors.json so the Claude Code hook can detect them.
+     * Overwrites the file each time — the hook fires on any write.
+     */
+    private writeErrorFile;
+    /**
+     * Clear the error file (e.g., on successful build or process start).
+     */
+    private clearErrorFile;
+    /**
+     * Append a line to a rolling buffer, evicting oldest entries when full.
+     */
+    private pushLine;
+    /**
+     * Cap an error array at MAX_ERRORS, dropping oldest entries.
+     */
+    private capErrors;
+    /**
+     * Kill a child process gracefully (SIGTERM, then SIGKILL after timeout).
+     *
+     * The promise resolves only when the process actually exits, not when
+     * SIGKILL is sent. Resolving on the SIGKILL timer was a race: callers
+     * (e.g. `runBuild`) would spawn a new build while the old Xcode process
+     * was still releasing DerivedData / build locks, causing cryptic
+     * SIGABRT or "file locked" errors on the new build.
+     *
+     * A hard upper-bound timer (2s after SIGKILL) guards against the
+     * pathological case where a process refuses to die at all, so callers
+     * never hang forever.
+     */
+    private killProcess;
+    /**
+     * Run `npx expo prebuild --clean` synchronously (waits for exit).
+     */
+    private runPrebuildClean;
+    /**
+     * Build and run the app on an iOS device or simulator.
+     * Auto-detects Expo vs bare React Native and uses the appropriate command:
+     *   - Expo: `npx expo run:ios`
+     *   - Bare RN: `npx react-native run-ios`
+     *
+     * Optionally runs `npx expo prebuild --clean` first (Expo only).
+     */
+    runBuild(options?: RunBuildOptions): Promise<BuildResult>;
+    /**
+     * Start the Metro dev server.
+     * Auto-detects Expo vs bare React Native:
+     *   - Expo: `npx expo start --dev-client`
+     *   - Bare RN: `npx react-native start`
+     *
+     * Spawns Metro in the background and continuously captures output.
+     * Returns quickly once Metro shows signs of being ready (or after a timeout).
+     */
+    startMetro(options?: StartMetroOptions): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Return all captured errors from both build and runtime contexts.
+     */
+    getErrors(): AllErrors;
+    /**
+     * Return recent console output from Metro, optionally filtered by level.
+     */
+    getConsole(options?: ConsoleOptions): string[];
+    /**
+     * Stop all managed Expo processes.
+     */
+    stopAll(): Promise<string[]>;
+    /**
+     * Get the raw build output buffer (for diagnostics).
+     */
+    getBuildOutput(): string[];
+    /**
+     * Get the raw metro output buffer (for diagnostics).
+     */
+    getMetroOutput(): string[];
+}
+export {};

package/dist/expo-manager.js

@@ -0,0 +1,561 @@
+/**
+ * Manages React Native / Expo child processes (build and Metro dev server).
+ * Auto-detects whether the project uses Expo or bare React Native
+ * and runs the appropriate commands.
+ * Captures stdout/stderr into rolling buffers and parses errors.
+ */
+import { spawn } from "node:child_process";
+import { writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { parseBuildOutput, parseMetroOutput, MetroErrorParser, classifyLogLevel, } from "./error-parser.js";
+export class RNManager {
+    buildProcess = null;
+    metroProcess = null;
+    buildKilled = false;
+    metroKilled = false;
+    buildOutput = [];
+    metroOutput = [];
+    buildErrors = [];
+    runtimeErrors = [];
+    buildWarnings = [];
+    metroWarnings = [];
+    // Parser state must persist across `onData` chunks so that an error
+    // whose message and stack trace arrive in separate chunks is still
+    // assembled into a single RuntimeError. Resetting on every chunk
+    // (the previous bug) caused the .rn-errors.json hook to fire with
+    // the message but no stack, or to drop multi-line errors entirely.
+    metroParser = new MetroErrorParser();
+    MAX_BUILD_LINES = 1000;
+    MAX_METRO_LINES = 500;
+    MAX_ERRORS = 100;
+    /** The working directory for commands. */
+    cwd;
+    /** Path to the error file that triggers the Claude Code hook. */
+    errorFilePath;
+    constructor(cwd) {
+        this.cwd = cwd;
+        this.errorFilePath = join(cwd, ".rn-errors.json");
+    }
+    /**
+     * Detect whether this is an Expo or bare React Native project.
+     * Checks for app.json with expo config or expo package in dependencies.
+     */
+    async detectProjectType() {
+        try {
+            // Check for app.json with expo key
+            const appJsonPath = join(this.cwd, "app.json");
+            await access(appJsonPath);
+            const appJson = JSON.parse(await (await import("node:fs/promises")).readFile(appJsonPath, "utf-8"));
+            if (appJson.expo) {
+                return true;
+            }
+        }
+        catch {
+            // No app.json or no expo key
+        }
+        try {
+            // Check for expo in package.json dependencies
+            const pkgPath = join(this.cwd, "package.json");
+            const pkg = JSON.parse(await (await import("node:fs/promises")).readFile(pkgPath, "utf-8"));
+            if (pkg.dependencies?.expo) {
+                return true;
+            }
+        }
+        catch {
+            // No package.json
+        }
+        return false;
+    }
+    /**
+     * Write errors to .rn-errors.json so the Claude Code hook can detect them.
+     * Overwrites the file each time — the hook fires on any write.
+     */
+    async writeErrorFile(errors) {
+        try {
+            await writeFile(this.errorFilePath, JSON.stringify({
+                timestamp: new Date().toISOString(),
+                errors: errors.map((e) => ({
+                    message: e.message,
+                    stack: e.stack,
+                    timestamp: e.timestamp,
+                })),
+            }, null, 2), "utf-8");
+        }
+        catch {
+            // Non-critical — don't break the process over a file write
+        }
+    }
+    /**
+     * Clear the error file (e.g., on successful build or process start).
+     */
+    async clearErrorFile() {
+        try {
+            await writeFile(this.errorFilePath, JSON.stringify({ timestamp: new Date().toISOString(), errors: [] }), "utf-8");
+        }
+        catch {
+            // Non-critical
+        }
+    }
+    /**
+     * Append a line to a rolling buffer, evicting oldest entries when full.
+     */
+    pushLine(buffer, line, max) {
+        buffer.push(line);
+        if (buffer.length > max) {
+            buffer.splice(0, buffer.length - max);
+        }
+    }
+    /**
+     * Cap an error array at MAX_ERRORS, dropping oldest entries.
+     */
+    capErrors(arr) {
+        if (arr.length > this.MAX_ERRORS) {
+            arr.splice(0, arr.length - this.MAX_ERRORS);
+        }
+    }
+    /**
+     * Kill a child process gracefully (SIGTERM, then SIGKILL after timeout).
+     *
+     * The promise resolves only when the process actually exits, not when
+     * SIGKILL is sent. Resolving on the SIGKILL timer was a race: callers
+     * (e.g. `runBuild`) would spawn a new build while the old Xcode process
+     * was still releasing DerivedData / build locks, causing cryptic
+     * SIGABRT or "file locked" errors on the new build.
+     *
+     * A hard upper-bound timer (2s after SIGKILL) guards against the
+     * pathological case where a process refuses to die at all, so callers
+     * never hang forever.
+     */
+    async killProcess(proc) {
+        return new Promise((resolve) => {
+            if (!proc.pid || proc.exitCode !== null) {
+                resolve();
+                return;
+            }
+            let hardTimer = null;
+            const softTimer = setTimeout(() => {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    // Process may have already exited between checks.
+                }
+                // Wait for `exit` to fire after SIGKILL, but bound the wait so
+                // callers don't hang on a process that refuses to die.
+                hardTimer = setTimeout(() => {
+                    proc.off("exit", onExit);
+                    resolve();
+                }, 2000);
+            }, 5000);
+            const onExit = () => {
+                clearTimeout(softTimer);
+                if (hardTimer)
+                    clearTimeout(hardTimer);
+                resolve();
+            };
+            proc.once("exit", onExit);
+            try {
+                proc.kill("SIGTERM");
+            }
+            catch {
+                // Process already exited or PID is gone — treat as done. Detach
+                // the exit listener so it doesn't fire stale on a stop/start cycle.
+                proc.off("exit", onExit);
+                clearTimeout(softTimer);
+                resolve();
+                return;
+            }
+            // TOCTOU recovery: if the process exited between the entry guard
+            // and the `once("exit")` registration above, `kill()` returns false
+            // (no throw) and our listener never fires for the already-emitted
+            // exit. Re-check `exitCode` here so we don't wait the full 7s on
+            // the hard timer.
+            if (proc.exitCode !== null) {
+                proc.off("exit", onExit);
+                clearTimeout(softTimer);
+                resolve();
+            }
+        });
+    }
+    /**
+     * Run `npx expo prebuild --clean` synchronously (waits for exit).
+     */
+    runPrebuildClean() {
+        return new Promise((resolve) => {
+            const lines = [];
+            const proc = spawn("npx", ["expo", "prebuild", "--clean"], {
+                cwd: this.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const onData = (data) => {
+                const text = data.toString();
+                for (const line of text.split("\n")) {
+                    if (line.trim())
+                        lines.push(line);
+                }
+            };
+            proc.stdout?.on("data", onData);
+            proc.stderr?.on("data", onData);
+            // Node fires both `error` and `exit` on a failed spawn. Guard so
+            // the second handler doesn't run a stale resolve / output dump.
+            let resolved = false;
+            proc.on("error", (err) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve({
+                    success: false,
+                    output: `Failed to spawn prebuild: ${err.message}`,
+                });
+            });
+            proc.on("exit", (code) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve({
+                    success: code === 0,
+                    output: lines.join("\n"),
+                });
+            });
+        });
+    }
+    /**
+     * Build and run the app on an iOS device or simulator.
+     * Auto-detects Expo vs bare React Native and uses the appropriate command:
+     *   - Expo: `npx expo run:ios`
+     *   - Bare RN: `npx react-native run-ios`
+     *
+     * Optionally runs `npx expo prebuild --clean` first (Expo only).
+     */
+    async runBuild(options = {}) {
+        const isExpo = await this.detectProjectType();
+        // Kill any existing build process
+        if (this.buildProcess) {
+            this.buildKilled = true;
+            await this.killProcess(this.buildProcess);
+            this.buildProcess = null;
+        }
+        // Reset state
+        this.buildKilled = false;
+        this.buildOutput = [];
+        this.buildErrors = [];
+        this.buildWarnings = [];
+        // Run prebuild --clean if requested (Expo only)
+        if (options.clean) {
+            if (!isExpo) {
+                return {
+                    success: false,
+                    errors: [
+                        {
+                            file: "",
+                            line: 0,
+                            message: "prebuild --clean is only available for Expo projects.",
+                            type: "build",
+                        },
+                    ],
+                    warnings: [],
+                    output: "",
+                };
+            }
+            const prebuildResult = await this.runPrebuildClean();
+            if (!prebuildResult.success) {
+                return {
+                    success: false,
+                    errors: [
+                        {
+                            file: "",
+                            line: 0,
+                            message: `prebuild --clean failed:\n${prebuildResult.output}`,
+                            type: "build",
+                        },
+                    ],
+                    warnings: [],
+                    output: prebuildResult.output,
+                };
+            }
+            // Add prebuild output to build output
+            for (const line of prebuildResult.output.split("\n")) {
+                this.pushLine(this.buildOutput, line, this.MAX_BUILD_LINES);
+            }
+        }
+        // Construct the build command based on project type
+        const args = isExpo ? ["expo", "run:ios"] : ["react-native", "run-ios"];
+        if (options.device) {
+            args.push(isExpo ? "--device" : "--udid", options.device);
+        }
+        return new Promise((resolve) => {
+            const proc = spawn("npx", args, {
+                cwd: this.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            this.buildProcess = proc;
+            const onData = (data) => {
+                const text = data.toString();
+                for (const line of text.split("\n")) {
+                    if (line.trim()) {
+                        this.pushLine(this.buildOutput, line, this.MAX_BUILD_LINES);
+                    }
+                }
+            };
+            proc.stdout?.on("data", onData);
+            proc.stderr?.on("data", onData);
+            // Node fires both `error` and `exit` on a spawn failure. Guard so
+            // the `exit` handler doesn't re-parse the (likely empty) output
+            // and overwrite `this.buildErrors` / `this.buildWarnings` after
+            // the caller has already received the failure result.
+            let resolved = false;
+            proc.on("error", (err) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                this.buildProcess = null;
+                resolve({
+                    success: false,
+                    errors: [
+                        {
+                            file: "",
+                            line: 0,
+                            message: `Failed to spawn ${isExpo ? "expo run:ios" : "react-native run-ios"}: ${err.message}`,
+                            type: "build",
+                        },
+                    ],
+                    warnings: [],
+                    output: this.buildOutput.join("\n"),
+                });
+            });
+            proc.on("exit", (code) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                this.buildProcess = null;
+                if (this.buildKilled) {
+                    resolve({
+                        success: false,
+                        errors: [],
+                        warnings: [],
+                        output: "Build was cancelled.",
+                    });
+                    return;
+                }
+                // Parse all captured output
+                const parsed = parseBuildOutput(this.buildOutput);
+                this.buildErrors = parsed.errors;
+                this.buildWarnings = parsed.warnings;
+                this.capErrors(this.buildErrors);
+                const success = code === 0 && !parsed.buildFailed;
+                resolve({
+                    success,
+                    errors: parsed.errors.map((e) => ({
+                        file: e.file,
+                        line: e.line,
+                        message: e.message,
+                        type: e.type,
+                    })),
+                    warnings: parsed.warnings,
+                    output: this.buildOutput.slice(-100).join("\n"), // Last 100 lines
+                });
+            });
+        });
+    }
+    /**
+     * Start the Metro dev server.
+     * Auto-detects Expo vs bare React Native:
+     *   - Expo: `npx expo start --dev-client`
+     *   - Bare RN: `npx react-native start`
+     *
+     * Spawns Metro in the background and continuously captures output.
+     * Returns quickly once Metro shows signs of being ready (or after a timeout).
+     */
+    async startMetro(options = {}) {
+        const isExpo = await this.detectProjectType();
+        // Kill existing Metro process
+        if (this.metroProcess) {
+            this.metroKilled = true;
+            await this.killProcess(this.metroProcess);
+            this.metroProcess = null;
+        }
+        // Reset state
+        this.metroKilled = false;
+        this.metroOutput = [];
+        this.runtimeErrors = [];
+        this.metroWarnings = [];
+        this.metroParser = new MetroErrorParser();
+        const args = isExpo
+            ? ["expo", "start", "--dev-client"]
+            : ["react-native", "start"];
+        if (options.port) {
+            args.push("--port", String(options.port));
+        }
+        if (options.clear) {
+            args.push(isExpo ? "--clear" : "--reset-cache");
+        }
+        await this.clearErrorFile();
+        return new Promise((resolve) => {
+            const proc = spawn("npx", args, {
+                cwd: this.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            this.metroProcess = proc;
+            let resolved = false;
+            const onData = (data) => {
+                const text = data.toString();
+                // Collect lines from this chunk and parse them as a batch.
+                // The parser is stateful, so an error whose message and stack
+                // straddle chunk boundaries is still assembled correctly.
+                const chunkLines = [];
+                for (const line of text.split("\n")) {
+                    if (line.trim()) {
+                        this.pushLine(this.metroOutput, line, this.MAX_METRO_LINES);
+                        chunkLines.push(line);
+                    }
+                }
+                if (chunkLines.length > 0) {
+                    const parsed = this.metroParser.parse(chunkLines);
+                    if (parsed.runtimeErrors.length > 0) {
+                        this.runtimeErrors.push(...parsed.runtimeErrors);
+                        this.capErrors(this.runtimeErrors);
+                        this.writeErrorFile(this.runtimeErrors);
+                    }
+                    if (parsed.warnings.length > 0) {
+                        this.metroWarnings.push(...parsed.warnings);
+                    }
+                }
+                // Detect Metro ready
+                if (!resolved && text.includes("Metro waiting on")) {
+                    resolved = true;
+                    resolve({
+                        success: true,
+                        message: "Metro dev server started successfully.",
+                    });
+                }
+            };
+            proc.stdout?.on("data", onData);
+            proc.stderr?.on("data", onData);
+            proc.on("error", (err) => {
+                this.metroProcess = null;
+                if (!resolved) {
+                    resolved = true;
+                    resolve({
+                        success: false,
+                        message: `Failed to start Metro: ${err.message}`,
+                    });
+                }
+            });
+            proc.on("exit", (code) => {
+                this.metroProcess = null;
+                // Flush any error still being assembled in the streaming parser
+                // so it surfaces in `.rn-errors.json` for the Claude Code hook.
+                const flushed = this.metroParser.flush();
+                if (flushed.runtimeErrors.length > 0) {
+                    this.runtimeErrors.push(...flushed.runtimeErrors);
+                    this.capErrors(this.runtimeErrors);
+                    this.writeErrorFile(this.runtimeErrors);
+                }
+                if (this.metroKilled) {
+                    if (!resolved) {
+                        resolved = true;
+                        resolve({
+                            success: false,
+                            message: "Metro was cancelled.",
+                        });
+                    }
+                    return;
+                }
+                if (!resolved) {
+                    resolved = true;
+                    resolve({
+                        success: false,
+                        message: `Metro exited unexpectedly with code ${code}.`,
+                    });
+                }
+            });
+            // If Metro doesn't show "ready" within 30s, resolve anyway
+            // -- it may still be starting up (pod install, etc.)
+            setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    resolve({
+                        success: true,
+                        message: "Metro process started but has not confirmed readiness yet. " +
+                            "It may still be initializing. Use rn_get_console to check.",
+                    });
+                }
+            }, 30_000);
+        });
+    }
+    /**
+     * Return all captured errors from both build and runtime contexts.
+     */
+    getErrors() {
+        // Only re-parse the buffer when Metro is NOT running. While the
+        // streaming parser holds in-progress state (header received, stack
+        // not yet), an independent re-parse would `flush()` a stackless
+        // copy of that same error and surface it as a duplicate-without-stack.
+        // Once Metro exits, the streaming parser has already been flushed
+        // in the `proc.on("exit")` handler, and re-parsing the buffer is a
+        // safe fallback for anything still missing.
+        const metroParsed = this.metroProcess === null
+            ? parseMetroOutput(this.metroOutput)
+            : { runtimeErrors: [], warnings: [] };
+        return {
+            buildErrors: this.buildErrors.map((e) => ({
+                file: e.file,
+                line: e.line,
+                column: e.column,
+                message: e.message,
+                severity: e.severity,
+                type: e.type,
+            })),
+            runtimeErrors: this.runtimeErrors.length > 0
+                ? this.runtimeErrors
+                : metroParsed.runtimeErrors,
+            warnings: [...this.buildWarnings, ...this.metroWarnings],
+        };
+    }
+    /**
+     * Return recent console output from Metro, optionally filtered by level.
+     */
+    getConsole(options = {}) {
+        const { lines = 50, level = "all" } = options;
+        let output = this.metroOutput;
+        if (level !== "all") {
+            output = output.filter((line) => {
+                const classified = classifyLogLevel(line);
+                return classified === level;
+            });
+        }
+        // Return the last N lines
+        return output.slice(-lines);
+    }
+    /**
+     * Stop all managed Expo processes.
+     */
+    async stopAll() {
+        const stopped = [];
+        if (this.buildProcess) {
+            this.buildKilled = true;
+            await this.killProcess(this.buildProcess);
+            this.buildProcess = null;
+            stopped.push("build");
+        }
+        if (this.metroProcess) {
+            this.metroKilled = true;
+            await this.killProcess(this.metroProcess);
+            this.metroProcess = null;
+            stopped.push("metro");
+        }
+        return stopped;
+    }
+    /**
+     * Get the raw build output buffer (for diagnostics).
+     */
+    getBuildOutput() {
+        return [...this.buildOutput];
+    }
+    /**
+     * Get the raw metro output buffer (for diagnostics).
+     */
+    getMetroOutput() {
+        return [...this.metroOutput];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @ceraph/react-native-mcp — MCP server for React Native / Expo development workflow.
+ *
+ * Auto-detects Expo vs bare React Native projects and uses the appropriate
+ * commands. Provides tools for building, running, error capture, screen
+ * interaction, and prebuild detection.
+ */
+export {};