@ceraph/react-native-mcp 0.2.1 → 0.3.1

package/dist/preflight.js

@@ -0,0 +1,847 @@
+import { spawn } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { syncCameraRegistry, relativeRegistryPath, } from "./camera-registry-sync.js";
+function runCommand(cmd, args, timeoutMs = 4000) {
+    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 });
+        });
+    });
+}
+async function safeCheck(name, severity, fn) {
+    try {
+        const result = await fn();
+        return { name, ...result };
+    }
+    catch (err) {
+        return {
+            name,
+            ok: false,
+            severity,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function pollUntil(fn, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    try {
+        if (await fn())
+            return true;
+    }
+    catch {
+    }
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, opts.intervalMs));
+        try {
+            if (await fn())
+                return true;
+        }
+        catch {
+        }
+    }
+    return false;
+}
+async function getLaptopSsid() {
+    const res = await runCommand("networksetup", ["-getairportnetwork", "en0"]);
+    if (res.code !== 0)
+        return null;
+    const match = res.stdout.match(/Current Wi-Fi Network:\s*(.+)$/m);
+    if (!match)
+        return null;
+    const ssid = match[1].trim();
+    if (!ssid || ssid.toLowerCase().includes("not associated"))
+        return null;
+    return ssid;
+}
+async function getLaptopIp() {
+    const res = await runCommand("ipconfig", ["getifaddr", "en0"]);
+    if (res.code !== 0)
+        return null;
+    const ip = res.stdout.trim();
+    return ip.length > 0 ? ip : null;
+}
+const SCAN_DIRECTORIES = ["app", "src", "screens"];
+const SCAN_EXTENSIONS = new Set([".tsx", ".jsx"]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    ".git",
+    ".ceraph",
+    ".rn-mcp-cache",
+    ".expo",
+    ".next",
+    "ios",
+    "android",
+]);
+async function listSourceFiles(projectDir) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                await walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const dot = entry.name.lastIndexOf(".");
+            if (dot < 0)
+                continue;
+            const ext = entry.name.slice(dot).toLowerCase();
+            if (!SCAN_EXTENSIONS.has(ext))
+                continue;
+            let contents;
+            try {
+                contents = await readFile(abs, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const rel = relative(projectDir, abs).split(sep).join("/");
+            out.push({ absPath: abs, relPath: rel, contents });
+        }
+    }
+    for (const sub of SCAN_DIRECTORIES) {
+        await walk(join(projectDir, sub));
+    }
+    return out;
+}
+function findJsxOpeningTags(file, tagName) {
+    const usages = [];
+    const contents = file.contents;
+    const escaped = tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const startPattern = new RegExp(`<${escaped}(?=[\\s/>])`, "g");
+    let startMatch;
+    while ((startMatch = startPattern.exec(contents)) !== null) {
+        const startIdx = startMatch.index;
+        const tagEndIdx = findJsxOpeningTagEnd(contents, startIdx + startMatch[0].length);
+        if (tagEndIdx === -1)
+            continue;
+        const openingTag = contents.slice(startIdx, tagEndIdx + 1);
+        const upto = contents.slice(0, startIdx);
+        const line = (upto.match(/\n/g)?.length ?? 0) + 1;
+        usages.push({ file, line, openingTag });
+    }
+    return usages;
+}
+function findJsxOpeningTagEnd(contents, start) {
+    let braceDepth = 0;
+    let inDouble = false;
+    let inSingle = false;
+    let inBacktick = false;
+    for (let i = start; i < contents.length; i++) {
+        const c = contents[i];
+        if (inDouble) {
+            if (c === '"' && !isEscaped(contents, i))
+                inDouble = false;
+            continue;
+        }
+        if (inSingle) {
+            if (c === "'" && !isEscaped(contents, i))
+                inSingle = false;
+            continue;
+        }
+        if (inBacktick) {
+            if (c === "`" && !isEscaped(contents, i))
+                inBacktick = false;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (c === "`") {
+            inBacktick = true;
+            continue;
+        }
+        if (c === "{") {
+            braceDepth++;
+            continue;
+        }
+        if (c === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (braceDepth === 0 && c === ">") {
+            return i;
+        }
+    }
+    return -1;
+}
+function isEscaped(contents, pos) {
+    let backslashes = 0;
+    let p = pos - 1;
+    while (p >= 0 && contents[p] === "\\") {
+        backslashes++;
+        p--;
+    }
+    return backslashes % 2 === 1;
+}
+function suggestPreflightImageKey(relPath) {
+    const noExt = relPath.replace(/\.(tsx|jsx)$/i, "");
+    const segments = noExt.split(/[\\/]/).filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return "camera";
+    const file = segments[segments.length - 1];
+    const parent = segments.length > 1 ? segments[segments.length - 2] : file;
+    const generic = new Set(["page", "index", "screen", "route", "layout"]);
+    const stem = generic.has(file.toLowerCase()) ? parent : file;
+    const kebab = stem
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return kebab.length > 0 ? kebab : "camera";
+}
+function importsCameraView(contents) {
+    const re = /import\s*\{([^}]*)\}\s*from\s*["']expo-camera["']/g;
+    let match;
+    while ((match = re.exec(contents)) !== null) {
+        const named = match[1]
+            .split(",")
+            .map((s) => s.trim().split(/\s+as\s+/)[0].trim());
+        if (named.includes("CameraView"))
+            return true;
+    }
+    return false;
+}
+function readImageKeyProp(openingTag) {
+    const KEY = "imageKey";
+    let braceDepth = 0;
+    let inDouble = false;
+    let inSingle = false;
+    let inBacktick = false;
+    for (let i = 0; i < openingTag.length; i++) {
+        const c = openingTag[i];
+        if (inDouble) {
+            if (c === '"' && !isEscaped(openingTag, i))
+                inDouble = false;
+            continue;
+        }
+        if (inSingle) {
+            if (c === "'" && !isEscaped(openingTag, i))
+                inSingle = false;
+            continue;
+        }
+        if (inBacktick) {
+            if (c === "`" && !isEscaped(openingTag, i))
+                inBacktick = false;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (c === "`") {
+            inBacktick = true;
+            continue;
+        }
+        if (c === "{") {
+            braceDepth++;
+            continue;
+        }
+        if (c === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (braceDepth !== 0)
+            continue;
+        if (c !== "i")
+            continue;
+        if (openingTag.substring(i, i + KEY.length) !== KEY)
+            continue;
+        const before = i === 0 ? " " : openingTag[i - 1];
+        if (/[A-Za-z0-9_$]/.test(before))
+            continue;
+        const after = openingTag[i + KEY.length] ?? "";
+        if (after !== "=" && !/\s/.test(after))
+            continue;
+        let j = i + KEY.length;
+        while (j < openingTag.length && /\s/.test(openingTag[j]))
+            j++;
+        if (openingTag[j] !== "=") {
+            i = j - 1;
+            continue;
+        }
+        j++;
+        while (j < openingTag.length && /\s/.test(openingTag[j]))
+            j++;
+        const q = openingTag[j];
+        if (q === '"' || q === "'") {
+            let k = j + 1;
+            while (k < openingTag.length &&
+                !(openingTag[k] === q && !isEscaped(openingTag, k))) {
+                k++;
+            }
+            const raw = openingTag.slice(j + 1, k);
+            if (raw.trim().length === 0)
+                return { present: false };
+            return { present: true, value: raw };
+        }
+        if (q === "{") {
+            return { present: true, value: null };
+        }
+        return { present: false };
+    }
+    return { present: false };
+}
+export async function runPreflight(opts) {
+    const { screen, apps, autonomy, bundleId, requiredEnv, expectedNetwork, projectDir = process.cwd(), target: targetResolver, excludeRuntimeChecks = false, } = opts;
+    const targetInfo = !excludeRuntimeChecks && targetResolver
+        ? await targetResolver.resolve().catch(() => null)
+        : null;
+    const isSimulator = targetInfo?.target === "simulator";
+    const registryPromise = syncCameraRegistry(projectDir);
+    const registrySyncCheck = registryPromise.then((res) => {
+        if (res.writtenOrUnchanged === "missing-dir") {
+            return {
+                name: "camera-registry-synced",
+                ok: true,
+                severity: "info",
+                message: "Skipped — no .ceraph/camera-images/ directory. " +
+                    "Drop test images there to enable the camera shim.",
+            };
+        }
+        return {
+            name: "camera-registry-synced",
+            ok: true,
+            severity: "info",
+            message: `Camera image registry ${res.writtenOrUnchanged} ` +
+                `(${res.registered.length} image${res.registered.length === 1 ? "" : "s"}) ` +
+                `at ${relativeRegistryPath(projectDir, res.registryPath)}.`,
+            details: {
+                registered: res.registered.map((r) => r.key),
+                state: res.writtenOrUnchanged,
+            },
+        };
+    }, (err) => ({
+        name: "camera-registry-synced",
+        ok: false,
+        severity: "warning",
+        message: `Camera registry sync failed: ${err instanceof Error ? err.message : String(err)}`,
+    }));
+    const sourceFilesPromise = listSourceFiles(projectDir);
+    const unwrappedCameraCheck = safeCheck("camera-views-unwrapped", "warning", async () => {
+        const files = await sourceFilesPromise;
+        const offenders = [];
+        for (const file of files) {
+            if (!importsCameraView(file.contents))
+                continue;
+            const usages = findJsxOpeningTags(file, "CameraView");
+            for (const usage of usages) {
+                offenders.push(`${usage.file.relPath}:${usage.line}`);
+            }
+        }
+        if (offenders.length === 0) {
+            return {
+                ok: true,
+                severity: "warning",
+                message: "No bare <CameraView> usages from expo-camera found in app/src/screens.",
+            };
+        }
+        return {
+            ok: false,
+            severity: "warning",
+            message: `Found ${offenders.length} <CameraView> usage(s) not wrapped by <CeraphCamera>.`,
+            remediation: "Replace each <CameraView /> with <CeraphCamera imageKey=\"...\" /> " +
+                'from "@ceraph/react-native-mcp/shim". The shim falls through to ' +
+                "expo-camera in production builds.",
+            details: { offenders },
+        };
+    });
+    const setupCheck = safeCheck("camera-imageKey-setup", "info", async () => {
+        const files = await sourceFilesPromise;
+        const uninitializedCameras = [];
+        for (const file of files) {
+            const usages = findJsxOpeningTags(file, "CeraphCamera");
+            for (const usage of usages) {
+                const prop = readImageKeyProp(usage.openingTag);
+                if (!prop.present) {
+                    uninitializedCameras.push({
+                        location: `${usage.file.relPath}:${usage.line}`,
+                        file: usage.file.relPath,
+                        line: usage.line,
+                        suggestedKey: suggestPreflightImageKey(usage.file.relPath),
+                    });
+                }
+            }
+        }
+        if (uninitializedCameras.length === 0) {
+            return {
+                ok: true,
+                severity: "info",
+                message: "All <CeraphCamera> components have an explicit imageKey (or use a runtime sentinel).",
+            };
+        }
+        return {
+            ok: true,
+            severity: "info",
+            message: `${uninitializedCameras.length} <CeraphCamera> component${uninitializedCameras.length === 1 ? "" : "s"} ` +
+                `awaiting imageKey assignment ` +
+                `(${uninitializedCameras.map((c) => c.location).join(", ")}).`,
+            remediation: "Ask the user about each camera screen and use " +
+                "`ceraph_init_replace_camera` to set the imageKey. Three options per camera: " +
+                "(A) imageKey=\"default\" — bundled 1024x1024 black PNG. Right for tests " +
+                "that don't care about image content (most form/upload flows). " +
+                "(B) imageKey=\"<scenario>\" — a specific test image. Drop the file at " +
+                ".ceraph/camera-images/<scenario>.{jpg,png,webp} (use `ceraph_add_camera_image` " +
+                "to write it programmatically) and re-run `rn_sync_camera_registry`. " +
+                "(C) imageKey=\"@runtime\" — multi-image flows where the planner picks the " +
+                "image per-step at runtime; the shim won't lock the camera to any static key.",
+            details: { uninitializedCameras },
+        };
+    });
+    const orphanImageKeyCheck = safeCheck("camera-image-key-orphan", "error", async () => {
+        const [registry, files] = await Promise.all([
+            registryPromise,
+            sourceFilesPromise,
+        ]);
+        const registeredKeys = new Set(registry.registered.map((r) => r.key));
+        const orphans = [];
+        for (const file of files) {
+            const usages = findJsxOpeningTags(file, "CeraphCamera");
+            for (const usage of usages) {
+                const prop = readImageKeyProp(usage.openingTag);
+                if (!prop.present)
+                    continue;
+                if (prop.value === null)
+                    continue;
+                if (prop.value === "default")
+                    continue;
+                if (prop.value.startsWith("@"))
+                    continue;
+                if (!registeredKeys.has(prop.value)) {
+                    orphans.push({
+                        location: `${usage.file.relPath}:${usage.line}`,
+                        key: prop.value,
+                    });
+                }
+            }
+        }
+        if (orphans.length === 0) {
+            return {
+                ok: true,
+                severity: "error",
+                message: "All <CeraphCamera imageKey> values resolve to files in .ceraph/camera-images/.",
+            };
+        }
+        const summary = orphans
+            .map((o) => `${o.location} (imageKey="${o.key}")`)
+            .join("; ");
+        return {
+            ok: false,
+            severity: "error",
+            message: `Found ${orphans.length} orphan imageKey reference(s): ${summary}.`,
+            remediation: "Add the matching image file to .ceraph/camera-images/ " +
+                "(e.g. <key>.jpg) and re-run `rn_sync_camera_registry`, or fix the imageKey prop value.",
+            details: { orphans },
+        };
+    });
+    const targetCheck = excludeRuntimeChecks
+        ? null
+        : targetResolver
+            ? Promise.resolve({
+                name: "target-selected",
+                ok: true,
+                severity: "info",
+                message: targetInfo
+                    ? `Target: ${targetInfo.target} (${targetInfo.reason}). ` +
+                        `WDA base URL: ${targetInfo.baseUrl}` +
+                        (targetInfo.udid ? `; udid ${targetInfo.udid}` : "")
+                    : "Target: unknown (resolver failed). Falling back to device defaults.",
+                details: targetInfo
+                    ? {
+                        target: targetInfo.target,
+                        reason: targetInfo.reason,
+                        baseUrl: targetInfo.baseUrl,
+                        udid: targetInfo.udid,
+                        preferenceEnv: process.env.CERAPH_TARGET ?? null,
+                    }
+                    : undefined,
+            })
+            : null;
+    const wdaRemediationSim = "Simulator WDA needs to be built and launched first. Run " +
+        "`rn_wda_start` (requires the `appium-webdriveragent` optional " +
+        "dep). The first build can take 60-120s and may require an Xcode " +
+        "signing prompt; subsequent starts are fast.";
+    const wdaRemediationDevice = "Ensure WebDriverAgent is running on the device (Xcode → run " +
+        "WDA target on your iPhone). If the iproxy auto-bridge failed " +
+        "above, follow its remediation first.";
+    const wdaReady = targetInfo?.wdaReady ?? true;
+    const wdaLocation = wdaReady
+        ? (targetInfo?.baseUrl ?? "http://localhost:8100")
+        : null;
+    let iproxyBridgeCheck;
+    let wdaCheck;
+    if (excludeRuntimeChecks) {
+        iproxyBridgeCheck = null;
+        wdaCheck = null;
+    }
+    else if (!isSimulator && opts.iproxyManager) {
+        const mgr = opts.iproxyManager;
+        const bridged = (async () => {
+            let reachable = await screen.isAvailable();
+            let bridgeMessage;
+            let bridgeOk = true;
+            let bridgeRemediation;
+            let bridgeDetails;
+            if (reachable) {
+                bridgeMessage =
+                    "WebDriverAgent already reachable — skipped iproxy auto-bridge.";
+            }
+            else {
+                const udid = await apps.getUdid().catch(() => null);
+                if (!udid) {
+                    bridgeOk = false;
+                    bridgeMessage =
+                        "WDA unreachable and no iOS device detected — cannot auto-bridge.";
+                    bridgeRemediation =
+                        "Connect your iPhone via USB-C and trust this Mac, then re-run preflight.";
+                }
+                else {
+                    const startRes = await mgr.start(udid);
+                    if (startRes.ok) {
+                        reachable = await pollUntil(() => screen.isAvailable(), { intervalMs: 250, timeoutMs: 2500 });
+                        bridgeMessage = `iproxy bridge started (pid ${startRes.pid}).`;
+                        bridgeDetails = { pid: startRes.pid, udid };
+                    }
+                    else if (startRes.reason === "already-running") {
+                        reachable = await pollUntil(() => screen.isAvailable(), { intervalMs: 250, timeoutMs: 2500 });
+                        bridgeMessage = "iproxy bridge already running (external).";
+                    }
+                    else if (startRes.reason === "not-installed") {
+                        bridgeOk = false;
+                        bridgeMessage =
+                            "iproxy is not installed — cannot auto-bridge WDA.";
+                        bridgeRemediation =
+                            "Install with `brew install libimobiledevice`, then re-run preflight.";
+                    }
+                    else {
+                        bridgeOk = false;
+                        bridgeMessage =
+                            `iproxy auto-bridge failed to start: ` +
+                                `${startRes.stderr?.[0] ?? "unknown error"}.`;
+                        bridgeRemediation =
+                            "Run `iproxy 8100 8100 -u <udid>` manually to see the full error.";
+                        bridgeDetails = { stderr: startRes.stderr };
+                    }
+                }
+            }
+            const bridge = {
+                name: "iproxy-bridge",
+                ok: bridgeOk,
+                severity: "warning",
+                message: bridgeMessage,
+                remediation: bridgeRemediation,
+                details: bridgeDetails,
+            };
+            const wda = reachable
+                ? {
+                    name: "wda-reachable",
+                    ok: true,
+                    severity: "error",
+                    message: `WebDriverAgent is reachable at ${wdaLocation ?? "http://localhost:8100"}.`,
+                }
+                : {
+                    name: "wda-reachable",
+                    ok: false,
+                    severity: "error",
+                    message: wdaLocation
+                        ? `WebDriverAgent is not reachable at ${wdaLocation}.`
+                        : "WebDriverAgent is not ready (simulator selected, no port captured yet).",
+                    remediation: wdaRemediationDevice,
+                };
+            return { bridge, wda };
+        })().catch((err) => ({
+            bridge: {
+                name: "iproxy-bridge",
+                ok: false,
+                severity: "warning",
+                message: `iproxy auto-bridge threw: ${err instanceof Error ? err.message : String(err)}`,
+            },
+            wda: {
+                name: "wda-reachable",
+                ok: false,
+                severity: "error",
+                message: `WDA reachability probe threw: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        }));
+        iproxyBridgeCheck = bridged.then((r) => r.bridge);
+        wdaCheck = bridged.then((r) => r.wda);
+    }
+    else {
+        iproxyBridgeCheck = Promise.resolve({
+            name: "iproxy-bridge",
+            ok: true,
+            severity: "info",
+            message: isSimulator
+                ? "Skipped — iproxy is not used on the simulator path."
+                : "Skipped — iproxy auto-bridge not enabled for this preflight call.",
+        });
+        wdaCheck = safeCheck("wda-reachable", "error", async () => {
+            const reachable = await screen.isAvailable();
+            if (reachable) {
+                return {
+                    ok: true,
+                    severity: "error",
+                    message: `WebDriverAgent is reachable at ${wdaLocation ?? "http://localhost:8100"}.`,
+                };
+            }
+            return {
+                ok: false,
+                severity: "error",
+                message: wdaLocation
+                    ? `WebDriverAgent is not reachable at ${wdaLocation}.`
+                    : "WebDriverAgent is not ready (simulator selected, no port captured yet).",
+                remediation: isSimulator ? wdaRemediationSim : wdaRemediationDevice,
+            };
+        });
+    }
+    const udidSeverity = isSimulator ? "warning" : "error";
+    const udidCheck = excludeRuntimeChecks
+        ? null
+        : safeCheck("real-device-connected", udidSeverity, async () => {
+            const udid = await apps.getUdid();
+            if (udid) {
+                return {
+                    ok: true,
+                    severity: udidSeverity,
+                    message: `Real iOS device connected (udid ${udid}).`,
+                    details: { udid },
+                };
+            }
+            if (isSimulator) {
+                return {
+                    ok: true,
+                    severity: "info",
+                    message: "No real iOS device detected — target is simulator, so this is fine.",
+                };
+            }
+            return {
+                ok: false,
+                severity: udidSeverity,
+                message: "No iOS target available.",
+                remediation: "v1 ships real-device only. The agent can resolve this by " +
+                    "calling `rn_wait_for_device` — listens on macOS's usbmuxd " +
+                    "daemon for sub-second event-driven detection (no polling, no " +
+                    "timeout) — after telling the user to plug in their iPhone " +
+                    "via USB-C. Or manually: connect the iPhone + trust this Mac " +
+                    "(run `xcrun devicectl list devices` to verify) and re-run " +
+                    "the original tool.",
+            };
+        });
+    const awakeCheck = excludeRuntimeChecks
+        ? null
+        : safeCheck("device-awake", "error", async () => {
+            const res = await autonomy.ensureAwake();
+            if (res.awake) {
+                return {
+                    ok: true,
+                    severity: "error",
+                    message: `Device is awake (lockState: ${res.lockState}).`,
+                    details: { lockState: res.lockState },
+                };
+            }
+            return {
+                ok: false,
+                severity: "error",
+                message: `Device is not awake (lockState: ${res.lockState}).`,
+                remediation: res.remediation ??
+                    "Unlock the device manually and set Auto-Lock to Never.",
+                details: { lockState: res.lockState },
+            };
+        });
+    const autoLockCheck = excludeRuntimeChecks
+        ? null
+        : Promise.resolve({
+            name: "auto-lock-disabled",
+            ok: true,
+            severity: "info",
+            message: "Verify Settings → Display & Brightness → Auto-Lock is set to " +
+                "Never. Otherwise the phone will sleep mid-flow.",
+        });
+    const appInstalledCheck = excludeRuntimeChecks
+        ? null
+        : bundleId
+            ? safeCheck("app-installed", "error", async () => {
+                const res = await apps.listInstalledApps();
+                if (!res.success) {
+                    return {
+                        ok: false,
+                        severity: "error",
+                        message: `Could not list installed apps: ${res.error ?? "unknown error"}`,
+                        remediation: "Ensure your device is connected and Xcode is installed " +
+                            "(`xcrun devicectl list devices`).",
+                    };
+                }
+                const found = res.apps.find((a) => a.bundleId === bundleId);
+                if (found) {
+                    return {
+                        ok: true,
+                        severity: "error",
+                        message: `App ${bundleId} is installed (${found.name}${found.version ? ` v${found.version}` : ""}).`,
+                        details: { bundleId, name: found.name, version: found.version },
+                    };
+                }
+                return {
+                    ok: false,
+                    severity: "error",
+                    message: `App ${bundleId} is not installed on the device.`,
+                    remediation: "Build and install the app: `expo run:ios --device <udid>` " +
+                        "or `npx react-native run-ios --udid <udid>`.",
+                    details: { bundleId, installedCount: res.apps.length },
+                };
+            })
+            : Promise.resolve({
+                name: "app-installed",
+                ok: true,
+                severity: "info",
+                message: "Skipped — no bundleId provided.",
+            });
+    const envCheck = excludeRuntimeChecks
+        ? null
+        : requiredEnv && requiredEnv.length > 0
+            ? safeCheck("required-env-vars", "error", async () => {
+                const missing = requiredEnv.filter((name) => {
+                    const v = process.env[name];
+                    return v === undefined || v === "";
+                });
+                if (missing.length === 0) {
+                    return {
+                        ok: true,
+                        severity: "error",
+                        message: `All ${requiredEnv.length} required env var(s) present.`,
+                        details: { required: requiredEnv },
+                    };
+                }
+                return {
+                    ok: false,
+                    severity: "error",
+                    message: `Missing env var(s): ${missing.join(", ")}.`,
+                    remediation: `Set the missing vars before running: ` +
+                        missing.map((n) => `export ${n}=...`).join("; ") +
+                        " (or add them to .env.local).",
+                    details: { missing, required: requiredEnv },
+                };
+            })
+            : Promise.resolve({
+                name: "required-env-vars",
+                ok: true,
+                severity: "info",
+                message: "Skipped — no required env vars declared.",
+            });
+    const networkCheck = excludeRuntimeChecks
+        ? null
+        : safeCheck("laptop-network", "warning", async () => {
+            const [ssid, ip] = await Promise.all([getLaptopSsid(), getLaptopIp()]);
+            const details = { ssid, ip };
+            if (expectedNetwork && ssid && ssid !== expectedNetwork) {
+                return {
+                    ok: false,
+                    severity: "warning",
+                    message: `Laptop is on WiFi '${ssid}' at ${ip ?? "<no IP>"}. Expected '${expectedNetwork}'.`,
+                    remediation: "Join the same WiFi network as your phone, or update the " +
+                        "expectedNetwork preflight option.",
+                    details,
+                };
+            }
+            return {
+                ok: true,
+                severity: "info",
+                message: `Laptop is on WiFi '${ssid ?? "<unknown>"}' at ${ip ?? "<no IP>"}. ` +
+                    "If you see network timeout errors during the run, verify your " +
+                    "phone is on the same network.",
+                details,
+            };
+        });
+    const interceptorCheck = excludeRuntimeChecks
+        ? null
+        : Promise.resolve({
+            name: "permission-interceptor-ready",
+            ok: true,
+            severity: "info",
+            message: "Permission interceptor middleware is wired. iOS system permission " +
+                "dialogs will be auto-accepted during flows (configurable via " +
+                "rn_permission_auto_accept).",
+        });
+    const checks = await Promise.all([
+        registrySyncCheck,
+        targetCheck,
+        iproxyBridgeCheck,
+        wdaCheck,
+        udidCheck,
+        awakeCheck,
+        autoLockCheck,
+        appInstalledCheck,
+        envCheck,
+        networkCheck,
+        interceptorCheck,
+        unwrappedCameraCheck,
+        setupCheck,
+        orphanImageKeyCheck,
+    ].filter((c) => c !== null));
+    const ok = !checks.some((c) => c.severity === "error" && !c.ok);
+    return { ok, checks };
+}