@ceraph/react-native-mcp 0.2.1 → 0.3.1

package/dist/init.js

@@ -1,46 +1,14 @@
 #!/usr/bin/env node
-/**
- * @ceraph/react-native-mcp init
- *
- * Sets up MCP configuration and the runtime error hook for the current project.
- * Detects which MCP clients are in use and writes config for each one.
- */
 import { readFile, writeFile, mkdir, access, chmod } from "node:fs/promises";
 import { join } from "node:path";
+import { runWalkthrough } from "./init/walkthrough.js";
+import { AppLifecycle } from "./app-lifecycle.js";
+import { ScreenManager } from "./screen.js";
+import { DeviceAutonomy } from "./device-autonomy.js";
+import { runPreflight } from "./preflight.js";
+import { HOOK_SCRIPT, FLOW_PROGRESS_HOOK_SCRIPT, ERROR_HOOK_COMMAND, ERROR_HOOK_MATCHER, FLOW_PROGRESS_HOOK_COMMAND, FLOW_PROGRESS_HOOK_MATCHER, } from "./init/claude-hook-constants.js";
+import { writeFileAtomic } from "./utils/atomic-write.js";
 const PROJECT_DIR = process.cwd();
-// ---------------------------------------------------------------------------
-// Hook script content
-// ---------------------------------------------------------------------------
-const HOOK_SCRIPT = `#!/bin/bash
-# rn-error-notify.sh — Injected by @ceraph/react-native-mcp init
-# Reads .rn-errors.json and injects runtime errors into Claude's context.
-
-ERROR_FILE="\$CLAUDE_PROJECT_DIR/mobile/.rn-errors.json"
-
-# Also check project root if mobile/ doesn't exist
-if [ ! -f "\$ERROR_FILE" ]; then
-  ERROR_FILE="\$CLAUDE_PROJECT_DIR/.rn-errors.json"
-fi
-
-if [ ! -f "\$ERROR_FILE" ]; then
-  exit 0
-fi
-
-ERROR_COUNT=\$(jq -r '.errors | length' "\$ERROR_FILE" 2>/dev/null)
-
-if [ "\$ERROR_COUNT" = "0" ] || [ -z "\$ERROR_COUNT" ]; then
-  exit 0
-fi
-
-echo "REACT NATIVE RUNTIME ERROR DETECTED:"
-echo ""
-jq -r '.errors[] | "Error: \\(.message)\\nStack: \\(.stack)\\nTime: \\(.timestamp)\\n---"' "\$ERROR_FILE" 2>/dev/null
-echo ""
-echo "Use rn_get_errors for full details. Fix the error and rebuild."
-`;
-// ---------------------------------------------------------------------------
-// MCP server entry (same for all JSON-based clients)
-// ---------------------------------------------------------------------------
 const MCP_ENTRY = {
     "mobile-mcp": {
         command: "npx",
@@ -51,9 +19,6 @@ const MCP_ENTRY = {
         args: ["-y", "@ceraph/react-native-mcp@latest"],
     },
 };
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
 async function fileExists(path) {
     try {
         await access(path);
@@ -64,27 +29,55 @@ async function fileExists(path) {
     }
 }
 async function readJson(path) {
+    let raw;
     try {
-        const content = await readFile(path, "utf-8");
-        return JSON.parse(content);
+        raw = await readFile(path, "utf-8");
     }
-    catch {
-        return null;
+    catch (err) {
+        const e = err;
+        if (e && e.code === "ENOENT")
+            return { kind: "missing" };
+        throw err;
     }
+    try {
+        return { kind: "ok", value: JSON.parse(raw) };
+    }
+    catch (err) {
+        return { kind: "malformed", raw, error: err };
+    }
+}
+function isPlainObject(v) {
+    return v != null && typeof v === "object" && !Array.isArray(v);
 }
 async function writeJson(path, data) {
     await mkdir(join(path, ".."), { recursive: true });
-    await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    await writeFileAtomic(path, JSON.stringify(data, null, 2) + "\n");
 }
 function log(msg) {
     console.log(`  ${msg}`);
 }
-// ---------------------------------------------------------------------------
-// MCP config writers
-// ---------------------------------------------------------------------------
-async function setupJsonMcp(configPath, label) {
-    const existing = (await readJson(configPath)) ?? {};
-    const servers = (existing.mcpServers ?? {});
+export async function setupJsonMcp(configPath, label) {
+    const readResult = await readJson(configPath);
+    if (readResult.kind === "malformed") {
+        log(`${label}: existing config at ${configPath} is malformed JSON — preserving it. Fix the file manually then re-run init.`);
+        return false;
+    }
+    const baseExisting = readResult.kind === "ok" ? readResult.value : {};
+    if (readResult.kind === "ok" && !isPlainObject(baseExisting)) {
+        log(`${label}: existing config at ${configPath} is not a JSON object (got ${Array.isArray(baseExisting) ? "array" : typeof baseExisting}) — preserving it.`);
+        return false;
+    }
+    const existing = isPlainObject(baseExisting)
+        ? baseExisting
+        : {};
+    const rawServers = existing.mcpServers;
+    if (rawServers !== undefined && !isPlainObject(rawServers)) {
+        log(`${label}: existing mcpServers in ${configPath} is not a JSON object (got ${Array.isArray(rawServers) ? "array" : typeof rawServers}) — preserving the file.`);
+        return false;
+    }
+    const servers = isPlainObject(rawServers)
+        ? rawServers
+        : {};
     if (servers["react-native-mcp"]) {
         log(`${label}: already configured`);
         return false;
@@ -102,7 +95,6 @@ async function setupCodexToml(configPath) {
         content = await readFile(configPath, "utf-8");
     }
     catch {
-        // File doesn't exist, we'll create it
     }
     if (content.includes("react-native-mcp")) {
         log("Codex: already configured");
@@ -118,62 +110,192 @@ command = "npx"
 args = ["-y", "@ceraph/react-native-mcp@latest"]
 `;
     await mkdir(join(configPath, ".."), { recursive: true });
-    await writeFile(configPath, content + tomlBlock, "utf-8");
+    await writeFileAtomic(configPath, content + tomlBlock);
     log("Codex: configured ✓");
     return true;
 }
-// ---------------------------------------------------------------------------
-// Hook setup
-// ---------------------------------------------------------------------------
-async function setupClaudeHook() {
-    // Write the hook script
-    const hooksDir = join(PROJECT_DIR, ".claude", "hooks");
+export async function setupClaudeHook(projectDir = PROJECT_DIR) {
+    const hooksDir = join(projectDir, ".claude", "hooks");
     const hookPath = join(hooksDir, "rn-error-notify.sh");
+    const progressHookPath = join(hooksDir, "rn-flow-progress-notify.sh");
     await mkdir(hooksDir, { recursive: true });
-    await writeFile(hookPath, HOOK_SCRIPT, "utf-8");
+    await writeFileAtomic(hookPath, HOOK_SCRIPT);
     await chmod(hookPath, 0o755);
     log("Hook script: .claude/hooks/rn-error-notify.sh ✓");
-    // Add FileChanged hook to settings.
-    // Check both settings.json and settings.local.json — if either already has
-    // the hook, we treat it as configured. This prevents duplicate hooks (which
-    // would fire twice per .rn-errors.json write) for projects where the hook
-    // was originally written to settings.local.json.
-    const sharedSettingsPath = join(PROJECT_DIR, ".claude", "settings.json");
-    const localSettingsPath = join(PROJECT_DIR, ".claude", "settings.local.json");
-    const isMatcher = (h) => h.matcher === ".rn-errors.json";
-    const fileChangedFrom = (s) => {
-        const hooks = (s?.hooks ?? {});
-        return (hooks.FileChanged ?? []);
+    await writeFileAtomic(progressHookPath, FLOW_PROGRESS_HOOK_SCRIPT);
+    await chmod(progressHookPath, 0o755);
+    log("Hook script: .claude/hooks/rn-flow-progress-notify.sh ✓");
+    const sharedSettingsPath = join(projectDir, ".claude", "settings.json");
+    const localSettingsPath = join(projectDir, ".claude", "settings.local.json");
+    const hasCeraphEntry = (s, matcher, command) => {
+        const settingsObj = isPlainObject(s) ? s : {};
+        const hooksVal = settingsObj.hooks;
+        const hooks = isPlainObject(hooksVal)
+            ? hooksVal
+            : {};
+        const fc = hooks.FileChanged;
+        if (!Array.isArray(fc)) {
+            return fc !== undefined;
+        }
+        return fc.some((entry) => {
+            if (!isPlainObject(entry))
+                return false;
+            if (entry.matcher !== matcher)
+                return false;
+            const inner = entry.hooks;
+            if (!Array.isArray(inner))
+                return false;
+            return inner.some((h) => {
+                if (!isPlainObject(h))
+                    return false;
+                const cmd = h.command;
+                return typeof cmd === "string" && cmd === command;
+            });
+        });
     };
-    const sharedSettings = await readJson(sharedSettingsPath);
-    const localSettings = await readJson(localSettingsPath);
-    if (fileChangedFrom(sharedSettings).some(isMatcher) ||
-        fileChangedFrom(localSettings).some(isMatcher)) {
-        log("Claude Code hook: already configured");
+    const sharedRead = await readJson(sharedSettingsPath);
+    const localRead = await readJson(localSettingsPath);
+    if (sharedRead.kind === "malformed") {
+        log(`Claude Code hook: ${sharedSettingsPath} is malformed JSON — preserving it. Fix the file manually then re-run init.`);
+        return;
+    }
+    if (localRead.kind === "malformed") {
+        log(`Claude Code hook: ${localSettingsPath} is malformed JSON — preserving it. Fix the file manually then re-run init.`);
+        return;
+    }
+    const sharedSettings = sharedRead.kind === "ok" ? sharedRead.value : null;
+    const localSettings = localRead.kind === "ok" ? localRead.value : null;
+    if (sharedSettings !== null && !isPlainObject(sharedSettings)) {
+        log(`Claude Code hook: ${sharedSettingsPath} top-level is not a JSON object — preserving it.`);
+        return;
+    }
+    if (localSettings !== null && !isPlainObject(localSettings)) {
+        log(`Claude Code hook: ${localSettingsPath} top-level is not a JSON object — preserving it.`);
         return;
     }
-    // Write to settings.json (the shared default). settings.local.json is
-    // reserved for per-machine overrides; we don't write there.
     const settings = sharedSettings ?? {};
-    const hooks = (settings.hooks ?? {});
-    const fileChangedHooks = (hooks.FileChanged ?? []);
-    fileChangedHooks.push({
-        matcher: ".rn-errors.json",
-        hooks: [
-            {
-                type: "command",
-                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/rn-error-notify.sh',
-            },
-        ],
-    });
-    hooks.FileChanged = fileChangedHooks;
-    settings.hooks = hooks;
-    await writeJson(sharedSettingsPath, settings);
-    log("Claude Code hook: FileChanged → .rn-errors.json ✓");
+    const hooksVal = settings.hooks;
+    if (hooksVal !== undefined && !isPlainObject(hooksVal)) {
+        log(`Claude Code hook: ${sharedSettingsPath} \`hooks\` is not a JSON object — preserving it.`);
+        return;
+    }
+    const hooks = isPlainObject(hooksVal)
+        ? hooksVal
+        : {};
+    const fcVal = hooks.FileChanged;
+    const fileChangedHooks = Array.isArray(fcVal)
+        ? fcVal
+        : [];
+    let mutated = false;
+    if (!hasCeraphEntry(sharedSettings, ERROR_HOOK_MATCHER, ERROR_HOOK_COMMAND) &&
+        !hasCeraphEntry(localSettings, ERROR_HOOK_MATCHER, ERROR_HOOK_COMMAND)) {
+        fileChangedHooks.push({
+            matcher: ERROR_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: "command",
+                    command: ERROR_HOOK_COMMAND,
+                },
+            ],
+        });
+        mutated = true;
+        log("Claude Code hook: FileChanged → .rn-errors.json ✓");
+    }
+    else {
+        log("Claude Code hook (.rn-errors.json): already configured");
+    }
+    if (!hasCeraphEntry(sharedSettings, FLOW_PROGRESS_HOOK_MATCHER, FLOW_PROGRESS_HOOK_COMMAND) &&
+        !hasCeraphEntry(localSettings, FLOW_PROGRESS_HOOK_MATCHER, FLOW_PROGRESS_HOOK_COMMAND)) {
+        fileChangedHooks.push({
+            matcher: FLOW_PROGRESS_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: "command",
+                    command: FLOW_PROGRESS_HOOK_COMMAND,
+                },
+            ],
+        });
+        mutated = true;
+        log("Claude Code hook: FileChanged → .rn-flow-progress.json ✓");
+    }
+    else {
+        log("Claude Code hook (.rn-flow-progress.json): already configured");
+    }
+    if (mutated) {
+        hooks.FileChanged = fileChangedHooks;
+        settings.hooks = hooks;
+        await writeJson(sharedSettingsPath, settings);
+    }
+}
+const CAMERA_IMAGES_README = `# Ceraph camera test images
+
+Per-screen test images for \`<CeraphCamera />\` from
+\`@ceraph/react-native-mcp/shim\`. The filename (without extension) is
+the imageKey you pass on the JSX tag.
+
+## Three ways to wire a camera
+
+\`<CeraphCamera />\` (no \`imageKey\`) — uninitialized. Falls back to a
+bundled 1024x1024 black PNG that ships with the package, so the screen
+renders. The MCP's \`rn_preflight\` lists these as info findings so an
+AI assistant can prompt you to make a deliberate choice. Pick from:
+
+1. \`<CeraphCamera imageKey="default" />\` — explicit acknowledgment of
+   the black PNG. Right answer for most form / upload / permission
+   flows where the image content doesn't matter.
+2. \`<CeraphCamera imageKey="profile" />\` — a specific test image you
+   provide (this folder). Drop \`profile.jpg\` (or \`.png\` / \`.webp\` /
+   \`.heic\`) here. The agent can write the file for you via
+   \`ceraph_add_camera_image\`.
+3. \`<CeraphCamera imageKey="@runtime" />\` — runtime control. The flow
+   planner picks the image per-step at test time. Use when one camera
+   screen feeds different scenarios across multiple flows.
+
+## Naming
+
+Lowercase + hyphen-separated, descriptive of what the image represents:
+
+- \`profile.jpg\` — face photo for a profile picture screen
+- \`id-card.png\` — government-issued ID for a KYC scan screen
+- \`product-photo.jpg\` — a product image for an upload screen
+
+Supported extensions: \`.jpg\`, \`.jpeg\`, \`.png\`, \`.webp\`, \`.heic\`.
+Extension priority on collision: jpg > jpeg > png > webp > heic.
+
+## Workflow
+
+1. Drop the image into this folder with the right filename.
+2. Reference it on the tag:
+   \`\`\`tsx
+   import { CeraphCamera } from "@ceraph/react-native-mcp/shim";
+   <CeraphCamera imageKey="profile" />
+   \`\`\`
+3. Regenerate the registry: call the MCP tool
+   \`rn_sync_camera_registry\`, or just call \`rn_preflight\` — it
+   syncs the registry automatically.
+4. In \`App.tsx\` or your root layout (once):
+   \`\`\`tsx
+   import { installCeraph } from "@ceraph/react-native-mcp/shim";
+   useEffect(() => { installCeraph(); }, []);
+   \`\`\`
+   \`installCeraph()\` loads the generated registry from
+   \`./.ceraph/camera-images/_registry\` and wires the deep-link
+   handlers the flow planner uses.
+
+Commit these images so flows are reproducible across machines and CI.
+`;
+async function setupCameraImagesDir() {
+    const dir = join(PROJECT_DIR, ".ceraph", "camera-images");
+    await mkdir(dir, { recursive: true });
+    const readmePath = join(dir, "README.md");
+    if (!(await fileExists(readmePath))) {
+        await writeFile(readmePath, CAMERA_IMAGES_README, "utf-8");
+        log("Camera images: .ceraph/camera-images/ + README.md ✓");
+    }
+    else {
+        log("Camera images: .ceraph/camera-images/ already exists");
+    }
 }
-// ---------------------------------------------------------------------------
-// Gitignore
-// ---------------------------------------------------------------------------
 async function setupGitignore() {
     const gitignorePath = join(PROJECT_DIR, ".gitignore");
     let content = "";
@@ -181,55 +303,93 @@ async function setupGitignore() {
         content = await readFile(gitignorePath, "utf-8");
     }
     catch {
-        // No .gitignore yet
     }
-    const entries = [".rn-errors.json", ".rn-mcp-cache/"];
+    const entries = [".rn-errors.json", ".rn-flow-progress.json", ".rn-mcp-cache/"];
     const missing = entries.filter((e) => !content.includes(e));
     if (missing.length === 0) {
         return;
     }
     const prefix = content === "" || content.endsWith("\n") ? "" : "\n";
     const addition = prefix + missing.join("\n") + "\n";
-    await writeFile(gitignorePath, content + addition, "utf-8");
+    await writeFileAtomic(gitignorePath, content + addition);
     log(`.gitignore: added ${missing.join(", ")} ✓`);
 }
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-async function main() {
-    console.log("\n@ceraph/react-native-mcp init\n");
-    // Detect and configure MCP clients
+export async function setupMcpClients() {
     console.log("MCP configuration:");
-    // Claude Code
     await setupJsonMcp(join(PROJECT_DIR, ".mcp.json"), "Claude Code");
-    // Cursor
     await setupJsonMcp(join(PROJECT_DIR, ".cursor", "mcp.json"), "Cursor");
-    // Codex
     await setupCodexToml(join(PROJECT_DIR, ".codex", "config.toml"));
-    // VS Code / Copilot
     await setupJsonMcp(join(PROJECT_DIR, ".vscode", "mcp.json"), "VS Code");
-    // Windsurf (user-level config)
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
     if (home) {
         const windsurfPath = join(home, ".codeium", "windsurf", "mcp_config.json");
         if (await fileExists(join(home, ".codeium", "windsurf"))) {
             await setupJsonMcp(windsurfPath, "Windsurf");
         }
-        // Antigravity (user-level config)
         const antigravityPath = join(home, ".gemini", "antigravity", "mcp_config.json");
         if (await fileExists(join(home, ".gemini", "antigravity"))) {
             await setupJsonMcp(antigravityPath, "Antigravity");
         }
     }
-    // Claude Code error hook
+}
+function summarisePreflight(checks) {
+    const blockers = checks.filter((c) => c.severity === "error" && !c.ok);
+    const warnings = checks.filter((c) => c.severity === "warning" && !c.ok);
+    if (blockers.length === 0 && warnings.length === 0)
+        return "";
+    const lines = [];
+    for (const c of blockers) {
+        lines.push(`  [BLOCKER] ${c.name}: ${c.message}`);
+        if (c.remediation)
+            lines.push(`            → ${c.remediation}`);
+    }
+    for (const c of warnings) {
+        lines.push(`  [WARN]    ${c.name}: ${c.message}`);
+        if (c.remediation)
+            lines.push(`            → ${c.remediation}`);
+    }
+    return lines.join("\n") + "\n";
+}
+export async function runInit(opts = {}) {
+    console.log("\n@ceraph/react-native-mcp init\n");
+    await setupMcpClients();
     console.log("\nRuntime error hook:");
     await setupClaudeHook();
-    // Gitignore
+    console.log("\nCamera test images:");
+    await setupCameraImagesDir();
     console.log("\nGitignore:");
     await setupGitignore();
-    console.log("\nDone. Runtime errors will be automatically injected into Claude's context.\n");
+    console.log("");
+    await runWalkthrough(PROJECT_DIR, {
+        agentMode: opts.agentMode === true,
+        nonInteractive: opts.agentMode === true ? true : undefined,
+        runPreflight: async () => {
+            const screen = new ScreenManager();
+            const apps = new AppLifecycle(screen);
+            const autonomy = new DeviceAutonomy(screen);
+            const res = await runPreflight({
+                screen,
+                apps,
+                autonomy,
+                projectDir: PROJECT_DIR,
+                excludeRuntimeChecks: true,
+            });
+            const passedCount = res.checks.filter((c) => c.ok).length;
+            return {
+                ok: res.ok,
+                summary: summarisePreflight(res.checks),
+                passedCount,
+                totalCount: res.checks.length,
+            };
+        },
+    });
+}
+const argv1 = process.argv[1] ?? "";
+if (argv1.endsWith("init.js") || argv1.endsWith("init.ts")) {
+    const agentMode = process.env.CERAPH_AGENT_MODE === "1" ||
+        process.argv.includes("--agent");
+    runInit({ agentMode }).catch((err) => {
+        console.error("Init failed:", err);
+        process.exit(1);
+    });
 }
-main().catch((err) => {
-    console.error("Init failed:", err);
-    process.exit(1);
-});

package/dist/iproxy-manager.d.ts

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+export interface IproxyManagerOptions {
+    localPort?: number;
+    devicePort?: number;
+    spawnFn?: typeof spawn;
+    whichFn?: (bin: string) => Promise<string | null>;
+}
+export interface IproxyStartResult {
+    ok: boolean;
+    reason?: "not-installed" | "spawn-failed" | "already-running";
+    pid?: number;
+    stderr?: string[];
+}
+export declare class IproxyManager {
+    private child;
+    private udid;
+    private localPort;
+    private devicePort;
+    private stderrBuffer;
+    private spawnFn;
+    private whichFn;
+    private startInFlight;
+    constructor(opts?: IproxyManagerOptions);
+    isRunning(): boolean;
+    start(udid: string): Promise<IproxyStartResult>;
+    private startInner;
+    stop(): Promise<void>;
+    restart(udid?: string): Promise<IproxyStartResult>;
+    getStderr(): string[];
+    private appendStderr;
+    private detectEarlyExit;
+}