@ceraph/react-native-mcp 0.2.2 → 0.3.1

package/dist/init/ast-camera.d.ts

@@ -0,0 +1,29 @@
+export interface CameraReplacementEdit {
+    filePath: string;
+    relPath: string;
+    line: number;
+    suggestedKey: string;
+    alreadyHasImageKey: boolean;
+}
+export interface ScanCameraViewsResult {
+    edits: CameraReplacementEdit[];
+    filesScanned: number;
+}
+export declare function suggestImageKey(absPath: string): string;
+export declare function scanCameraViews(projectDir: string): Promise<ScanCameraViewsResult>;
+export interface ApplyEditsResult {
+    filesEdited: string[];
+    totalReplacements: number;
+}
+export interface ApplyEditsOptions {
+    omitImageKey?: boolean;
+}
+export declare function applyCameraEdits(projectDir: string, edits: CameraReplacementEdit[], options?: ApplyEditsOptions): Promise<ApplyEditsResult>;
+export interface SetImageKeyResult {
+    applied: boolean;
+    previousValue?: string | null;
+    reason?: string;
+}
+export declare function setImageKeyOnExistingTag(filePath: string, line: number, imageKey: string): Promise<SetImageKeyResult>;
+export declare function snapshotFile(filePath: string): Promise<string | null>;
+export declare function restoreFile(filePath: string, snapshot: string): Promise<void>;

package/dist/init/ast-camera.js

@@ -0,0 +1,267 @@
+import { readFile, writeFile, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { IndentationText, Project, SyntaxKind, Node, } from "ts-morph";
+const SCAN_ROOTS = ["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",
+]);
+const SHIM_IMPORT_MODULE = "@ceraph/react-native-mcp/shim";
+const SHIM_IMPORT_NAME = "CeraphCamera";
+export function suggestImageKey(absPath) {
+    const file = basename(absPath).replace(/\.(tsx|jsx)$/i, "");
+    const parent = basename(dirname(absPath));
+    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";
+}
+async function listCandidateFiles(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;
+            out.push(abs);
+        }
+    }
+    for (const sub of SCAN_ROOTS) {
+        await walk(join(projectDir, sub));
+    }
+    for (const candidate of ["App.tsx", "App.jsx"]) {
+        out.push(join(projectDir, candidate));
+    }
+    return out;
+}
+function buildProject(filePaths) {
+    const project = new Project({
+        useInMemoryFileSystem: false,
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+        skipLoadingLibFiles: true,
+        compilerOptions: { allowJs: true, jsx: 1 },
+        manipulationSettings: { indentationText: IndentationText.TwoSpaces },
+    });
+    for (const path of filePaths) {
+        try {
+            project.addSourceFileAtPath(path);
+        }
+        catch {
+        }
+    }
+    return project;
+}
+function listOpeningElements(source, name) {
+    const out = [];
+    source.forEachDescendant((node) => {
+        if (Node.isJsxOpeningElement(node) || Node.isJsxSelfClosingElement(node)) {
+            const tag = node.getTagNameNode();
+            if (tag.getText() === name) {
+                out.push(node);
+            }
+        }
+    });
+    return out;
+}
+function hasImageKeyAttribute(node) {
+    const attrs = node.getAttributes();
+    for (const attr of attrs) {
+        if (Node.isJsxAttribute(attr)) {
+            const nameNode = attr.getNameNode();
+            if (nameNode.getText() === "imageKey")
+                return true;
+        }
+    }
+    return false;
+}
+export async function scanCameraViews(projectDir) {
+    const candidates = await listCandidateFiles(projectDir);
+    const project = buildProject(candidates);
+    const edits = [];
+    for (const source of project.getSourceFiles()) {
+        const tags = listOpeningElements(source, "CameraView");
+        if (tags.length === 0)
+            continue;
+        for (const tag of tags) {
+            const start = tag.getStart();
+            const lineCol = source.getLineAndColumnAtPos(start);
+            edits.push({
+                filePath: source.getFilePath(),
+                relPath: relative(projectDir, source.getFilePath())
+                    .split(sep)
+                    .join("/"),
+                line: lineCol.line,
+                suggestedKey: suggestImageKey(source.getFilePath()),
+                alreadyHasImageKey: hasImageKeyAttribute(tag),
+            });
+        }
+    }
+    edits.sort((a, b) => a.relPath === b.relPath ? a.line - b.line : a.relPath < b.relPath ? -1 : 1);
+    return { edits, filesScanned: project.getSourceFiles().length };
+}
+export async function applyCameraEdits(projectDir, edits, options = {}) {
+    const byFile = new Map();
+    for (const edit of edits) {
+        const list = byFile.get(edit.filePath) ?? [];
+        list.push(edit);
+        byFile.set(edit.filePath, list);
+    }
+    const project = buildProject(Array.from(byFile.keys()));
+    const filesEdited = [];
+    let totalReplacements = 0;
+    for (const [filePath, fileEdits] of byFile) {
+        const source = project.getSourceFile(filePath);
+        if (!source)
+            continue;
+        let replacementsThisFile = 0;
+        for (const edit of fileEdits) {
+            const tags = listOpeningElements(source, "CameraView");
+            const target = tags.find((t) => {
+                const pos = source.getLineAndColumnAtPos(t.getStart());
+                return pos.line === edit.line;
+            });
+            if (!target)
+                continue;
+            target.getTagNameNode().replaceWithText("CeraphCamera");
+            if (Node.isJsxOpeningElement(target)) {
+                const parent = target.getParentIfKind(SyntaxKind.JsxElement);
+                if (parent) {
+                    const closing = parent.getClosingElement();
+                    closing.getTagNameNode().replaceWithText("CeraphCamera");
+                }
+            }
+            if (!edit.alreadyHasImageKey && !options.omitImageKey) {
+                target.addAttribute({
+                    name: "imageKey",
+                    initializer: `"${edit.suggestedKey}"`,
+                });
+            }
+            replacementsThisFile++;
+            totalReplacements++;
+        }
+        const existingShimImport = source.getImportDeclaration(SHIM_IMPORT_MODULE);
+        if (existingShimImport) {
+            const named = existingShimImport.getNamedImports();
+            if (!named.some((n) => n.getName() === SHIM_IMPORT_NAME)) {
+                existingShimImport.addNamedImport(SHIM_IMPORT_NAME);
+            }
+        }
+        else {
+            source.addImportDeclaration({
+                moduleSpecifier: SHIM_IMPORT_MODULE,
+                namedImports: [SHIM_IMPORT_NAME],
+            });
+        }
+        const expoCameraImport = source.getImportDeclaration("expo-camera");
+        if (expoCameraImport) {
+            const remainingTags = listOpeningElements(source, "CameraView");
+            if (remainingTags.length === 0) {
+                const named = expoCameraImport.getNamedImports();
+                const cameraViewSpec = named.find((n) => n.getName() === "CameraView");
+                if (cameraViewSpec) {
+                    cameraViewSpec.remove();
+                    const remaining = expoCameraImport.getNamedImports();
+                    const hasDefault = expoCameraImport.getDefaultImport() != null;
+                    if (remaining.length === 0 && !hasDefault) {
+                        expoCameraImport.remove();
+                    }
+                }
+            }
+        }
+        if (replacementsThisFile > 0) {
+            const updated = source.getFullText();
+            await writeFile(filePath, updated, "utf-8");
+            filesEdited.push(filePath);
+        }
+    }
+    return { filesEdited, totalReplacements };
+}
+export async function setImageKeyOnExistingTag(filePath, line, imageKey) {
+    const project = buildProject([filePath]);
+    const source = project.getSourceFile(filePath);
+    if (!source) {
+        return { applied: false, reason: `File not found: ${filePath}` };
+    }
+    const tags = listOpeningElements(source, "CeraphCamera");
+    const target = tags.find((t) => {
+        const pos = source.getLineAndColumnAtPos(t.getStart());
+        return pos.line === line;
+    });
+    if (!target) {
+        return {
+            applied: false,
+            reason: `No <CeraphCamera> at ${filePath}:${line}`,
+        };
+    }
+    let previousValue = null;
+    let existingFound = false;
+    for (const attr of target.getAttributes()) {
+        if (Node.isJsxAttribute(attr)) {
+            const nameNode = attr.getNameNode();
+            if (nameNode.getText() === "imageKey") {
+                existingFound = true;
+                const init = attr.getInitializer();
+                if (init && Node.isStringLiteral(init)) {
+                    previousValue = init.getLiteralText();
+                }
+                attr.setInitializer(`"${imageKey}"`);
+                break;
+            }
+        }
+    }
+    if (!existingFound) {
+        target.addAttribute({
+            name: "imageKey",
+            initializer: `"${imageKey}"`,
+        });
+    }
+    if (previousValue === imageKey) {
+        return { applied: false, previousValue, reason: "imageKey unchanged" };
+    }
+    await writeFile(filePath, source.getFullText(), "utf-8");
+    return { applied: true, previousValue };
+}
+export async function snapshotFile(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function restoreFile(filePath, snapshot) {
+    await writeFile(filePath, snapshot, "utf-8");
+}

package/dist/init/ast-layout.d.ts

@@ -0,0 +1,15 @@
+export type RootComponentTarget = {
+    kind: "expo-router";
+    filePath: string;
+} | {
+    kind: "bare-rn";
+    filePath: string;
+};
+export declare function detectRootComponent(projectDir: string): Promise<RootComponentTarget | null>;
+export interface InjectInstallCeraphResult {
+    applied: boolean;
+    reason?: string;
+}
+export declare function injectInstallCeraph(target: RootComponentTarget): Promise<InjectInstallCeraphResult>;
+export declare function snapshotLayout(target: RootComponentTarget): Promise<string | null>;
+export declare function restoreLayout(target: RootComponentTarget, snapshot: string): Promise<void>;

package/dist/init/ast-layout.js

@@ -0,0 +1,167 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { IndentationText, Project, Node, } from "ts-morph";
+const SHIM_MODULE = "@ceraph/react-native-mcp/shim";
+const INSTALL_CALL = "installCeraph";
+async function fileExists(path) {
+    try {
+        await readFile(path, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function detectRootComponent(projectDir) {
+    const expo = join(projectDir, "app", "_layout.tsx");
+    if (await fileExists(expo)) {
+        return { kind: "expo-router", filePath: expo };
+    }
+    const expoJsx = join(projectDir, "app", "_layout.jsx");
+    if (await fileExists(expoJsx)) {
+        return { kind: "expo-router", filePath: expoJsx };
+    }
+    for (const name of ["App.tsx", "App.jsx"]) {
+        const p = join(projectDir, name);
+        if (await fileExists(p)) {
+            return { kind: "bare-rn", filePath: p };
+        }
+    }
+    return null;
+}
+function findDefaultExportFunction(source) {
+    for (const fn of source.getFunctions()) {
+        if (fn.isDefaultExport())
+            return fn;
+    }
+    const exportAssignment = source
+        .getStatements()
+        .find((s) => Node.isExportAssignment(s));
+    if (exportAssignment && Node.isExportAssignment(exportAssignment)) {
+        const expr = exportAssignment.getExpression();
+        if (Node.isIdentifier(expr)) {
+            const symbol = expr.getSymbol();
+            if (symbol) {
+                const decl = symbol.getDeclarations()[0];
+                if (decl && Node.isVariableDeclaration(decl)) {
+                    const init = decl.getInitializer();
+                    if (init && Node.isArrowFunction(init))
+                        return init;
+                    if (init && Node.isFunctionExpression(init))
+                        return init;
+                }
+            }
+        }
+        if (Node.isArrowFunction(expr))
+            return expr;
+        if (Node.isFunctionExpression(expr))
+            return expr;
+    }
+    return null;
+}
+function ensureUseEffectImport(source) {
+    const reactImport = source.getImportDeclaration("react");
+    if (!reactImport) {
+        source.addImportDeclaration({
+            moduleSpecifier: "react",
+            namedImports: ["useEffect"],
+        });
+        return;
+    }
+    const named = reactImport.getNamedImports();
+    if (!named.some((n) => n.getName() === "useEffect")) {
+        reactImport.addNamedImport("useEffect");
+    }
+}
+function ensureShimImport(source) {
+    const existing = source.getImportDeclaration(SHIM_MODULE);
+    if (!existing) {
+        source.addImportDeclaration({
+            moduleSpecifier: SHIM_MODULE,
+            namedImports: [INSTALL_CALL],
+        });
+        return;
+    }
+    const named = existing.getNamedImports();
+    if (!named.some((n) => n.getName() === INSTALL_CALL)) {
+        existing.addNamedImport(INSTALL_CALL);
+    }
+}
+function bodyAlreadyHasInstallCeraph(fn) {
+    const body = fn.getBody();
+    if (!body)
+        return false;
+    if (!Node.isBlock(body))
+        return false;
+    const text = body.getText();
+    return text.includes(`${INSTALL_CALL}(`);
+}
+function insertInstallCeraphHook(fn) {
+    if (bodyAlreadyHasInstallCeraph(fn))
+        return false;
+    if (Node.isArrowFunction(fn)) {
+        const body = fn.getBody();
+        if (!Node.isBlock(body)) {
+            const expressionText = body.getText();
+            body.replaceWithText(`{ return ${expressionText}; }`);
+        }
+    }
+    const block = fn.getBody();
+    if (!block || !Node.isBlock(block))
+        return false;
+    block.insertStatements(0, "useEffect(() => { installCeraph(); }, []);");
+    return true;
+}
+export async function injectInstallCeraph(target) {
+    const project = new Project({
+        useInMemoryFileSystem: false,
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+        skipLoadingLibFiles: true,
+        compilerOptions: { allowJs: true, jsx: 1 },
+        manipulationSettings: { indentationText: IndentationText.TwoSpaces },
+    });
+    const source = project.addSourceFileAtPath(target.filePath);
+    const fn = findDefaultExportFunction(source);
+    if (!fn) {
+        return {
+            applied: false,
+            reason: "Could not locate the default-exported function component. " +
+                `Manually add the following near the top of your root component in ${target.filePath}:\n` +
+                `  import { installCeraph } from "${SHIM_MODULE}";\n` +
+                `  useEffect(() => { installCeraph(); }, []);`,
+        };
+    }
+    if (bodyAlreadyHasInstallCeraph(fn)) {
+        ensureShimImport(source);
+        ensureUseEffectImport(source);
+        const updated = source.getFullText();
+        await writeFile(target.filePath, updated, "utf-8");
+        return { applied: true, reason: "Already wired — imports checked." };
+    }
+    ensureShimImport(source);
+    ensureUseEffectImport(source);
+    const inserted = insertInstallCeraphHook(fn);
+    if (!inserted) {
+        return {
+            applied: false,
+            reason: "Default export is not a block-bodied function. " +
+                "Manually add `useEffect(() => { installCeraph(); }, [])` at the top " +
+                "of the component body.",
+        };
+    }
+    const updated = source.getFullText();
+    await writeFile(target.filePath, updated, "utf-8");
+    return { applied: true };
+}
+export async function snapshotLayout(target) {
+    try {
+        return await readFile(target.filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function restoreLayout(target, snapshot) {
+    await writeFile(target.filePath, snapshot, "utf-8");
+}

package/dist/init/claude-hook-constants.d.ts

@@ -0,0 +1,9 @@
+export declare const HOOK_SCRIPT = "#!/bin/bash\n# rn-error-notify.sh \u2014 Injected by @ceraph/react-native-mcp init\n# Reads .rn-errors.json and injects runtime errors into Claude's context.\n\nERROR_FILE=\"$CLAUDE_PROJECT_DIR/mobile/.rn-errors.json\"\n\n# Also check project root if mobile/ doesn't exist\nif [ ! -f \"$ERROR_FILE\" ]; then\n  ERROR_FILE=\"$CLAUDE_PROJECT_DIR/.rn-errors.json\"\nfi\n\nif [ ! -f \"$ERROR_FILE\" ]; then\n  exit 0\nfi\n\nERROR_COUNT=$(jq -r '.errors | length' \"$ERROR_FILE\" 2>/dev/null)\n\nif [ \"$ERROR_COUNT\" = \"0\" ] || [ -z \"$ERROR_COUNT\" ]; then\n  exit 0\nfi\n\necho \"REACT NATIVE RUNTIME ERROR DETECTED:\"\necho \"\"\njq -r '.errors[] | \"Error: \\(.message)\\nStack: \\(.stack)\\nTime: \\(.timestamp)\\n---\"' \"$ERROR_FILE\" 2>/dev/null\necho \"\"\necho \"Use rn_get_errors for full details. Fix the error and rebuild.\"\n";
+export declare const FLOW_PROGRESS_HOOK_SCRIPT = "#!/bin/bash\n# rn-flow-progress-notify.sh \u2014 Injected by @ceraph/react-native-mcp init\n# Reads .rn-flow-progress.json and injects a one-line heartbeat into\n# Claude's context. HEARTBEAT ONLY \u2014 no step-level failure details.\n\nENTRY_FILE=\"$CLAUDE_PROJECT_DIR/mobile/.rn-flow-progress.json\"\nif [ ! -f \"$ENTRY_FILE\" ]; then\n  ENTRY_FILE=\"$CLAUDE_PROJECT_DIR/.rn-flow-progress.json\"\nfi\nif [ ! -f \"$ENTRY_FILE\" ]; then\n  exit 0\nfi\n\n# If jq isn't installed, exit quietly \u2014 the heartbeat is best-effort.\nif ! command -v jq >/dev/null 2>&1; then\n  exit 0\nfi\n\nENTRY=$(jq -r '.entry' \"$ENTRY_FILE\" 2>/dev/null)\nif [ \"$ENTRY\" = \"null\" ] || [ -z \"$ENTRY\" ]; then\n  exit 0\nfi\n\n# jq '// \"\"' (works in jq 1.4+; \"// empty\" needed 1.5+ and would have\n# silently aborted older shells) makes jq emit an empty string for\n# missing fields rather than the literal \"null\". Defaults below keep\n# set -e shells happy in the arithmetic + awk expansions even when\n# the entry is partial (transient state if the file is read\n# mid-write).\nFLOW=$(jq -r '.entry.flow // \"\"' \"$ENTRY_FILE\" 2>/dev/null)\nINDEX=$(jq -r '.entry.index // \"\"' \"$ENTRY_FILE\" 2>/dev/null)\nTOTAL=$(jq -r '.entry.total // \"\"' \"$ENTRY_FILE\" 2>/dev/null)\nSUCCESS=$(jq -r '.entry.success // \"\"' \"$ENTRY_FILE\" 2>/dev/null)\nDURATION=$(jq -r '.entry.durationMs // \"\"' \"$ENTRY_FILE\" 2>/dev/null)\n\nINDEX=${INDEX:-0}\nTOTAL=${TOTAL:-0}\nDURATION=${DURATION:-0}\nFLOW=${FLOW:-unknown}\n\nDISPLAY_INDEX=$((INDEX + 1))\nif [ \"$SUCCESS\" = \"true\" ]; then\n  STATUS=\"passed\"\nelse\n  STATUS=\"failed\"\nfi\n\necho \"Flow $DISPLAY_INDEX/$TOTAL \u2014 $FLOW: $STATUS in $(awk \"BEGIN {printf \\\"%.1f\\\", $DURATION/1000}\")s\"\necho \"(Wait for the end-of-run summary before making any code changes \u2014 the flows in this run reference your pre-edit code.)\"\n";
+export declare const ERROR_HOOK_REL_PATH: readonly [".claude", "hooks", "rn-error-notify.sh"];
+export declare const FLOW_PROGRESS_HOOK_REL_PATH: readonly [".claude", "hooks", "rn-flow-progress-notify.sh"];
+export declare const ERROR_HOOK_MATCHER = ".rn-errors.json";
+export declare const FLOW_PROGRESS_HOOK_MATCHER = ".rn-flow-progress.json";
+export declare const ERROR_HOOK_COMMAND = "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/rn-error-notify.sh";
+export declare const FLOW_PROGRESS_HOOK_COMMAND = "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/rn-flow-progress-notify.sh";
+export declare const CLAUDE_SETTINGS_REL_PATHS: readonly [readonly [".claude", "settings.json"], readonly [".claude", "settings.local.json"]];

package/dist/init/claude-hook-constants.js

@@ -0,0 +1,91 @@
+export 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."
+`;
+export const FLOW_PROGRESS_HOOK_SCRIPT = `#!/bin/bash
+# rn-flow-progress-notify.sh — Injected by @ceraph/react-native-mcp init
+# Reads .rn-flow-progress.json and injects a one-line heartbeat into
+# Claude's context. HEARTBEAT ONLY — no step-level failure details.
+
+ENTRY_FILE="\$CLAUDE_PROJECT_DIR/mobile/.rn-flow-progress.json"
+if [ ! -f "\$ENTRY_FILE" ]; then
+  ENTRY_FILE="\$CLAUDE_PROJECT_DIR/.rn-flow-progress.json"
+fi
+if [ ! -f "\$ENTRY_FILE" ]; then
+  exit 0
+fi
+
+# If jq isn't installed, exit quietly — the heartbeat is best-effort.
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+ENTRY=\$(jq -r '.entry' "\$ENTRY_FILE" 2>/dev/null)
+if [ "\$ENTRY" = "null" ] || [ -z "\$ENTRY" ]; then
+  exit 0
+fi
+
+# jq '// ""' (works in jq 1.4+; "// empty" needed 1.5+ and would have
+# silently aborted older shells) makes jq emit an empty string for
+# missing fields rather than the literal "null". Defaults below keep
+# set -e shells happy in the arithmetic + awk expansions even when
+# the entry is partial (transient state if the file is read
+# mid-write).
+FLOW=\$(jq -r '.entry.flow // ""' "\$ENTRY_FILE" 2>/dev/null)
+INDEX=\$(jq -r '.entry.index // ""' "\$ENTRY_FILE" 2>/dev/null)
+TOTAL=\$(jq -r '.entry.total // ""' "\$ENTRY_FILE" 2>/dev/null)
+SUCCESS=\$(jq -r '.entry.success // ""' "\$ENTRY_FILE" 2>/dev/null)
+DURATION=\$(jq -r '.entry.durationMs // ""' "\$ENTRY_FILE" 2>/dev/null)
+
+INDEX=\${INDEX:-0}
+TOTAL=\${TOTAL:-0}
+DURATION=\${DURATION:-0}
+FLOW=\${FLOW:-unknown}
+
+DISPLAY_INDEX=\$((INDEX + 1))
+if [ "\$SUCCESS" = "true" ]; then
+  STATUS="passed"
+else
+  STATUS="failed"
+fi
+
+echo "Flow \$DISPLAY_INDEX/\$TOTAL — \$FLOW: \$STATUS in \$(awk "BEGIN {printf \\"%.1f\\", \$DURATION/1000}")s"
+echo "(Wait for the end-of-run summary before making any code changes — the flows in this run reference your pre-edit code.)"
+`;
+export const ERROR_HOOK_REL_PATH = [".claude", "hooks", "rn-error-notify.sh"];
+export const FLOW_PROGRESS_HOOK_REL_PATH = [
+    ".claude",
+    "hooks",
+    "rn-flow-progress-notify.sh",
+];
+export const ERROR_HOOK_MATCHER = ".rn-errors.json";
+export const FLOW_PROGRESS_HOOK_MATCHER = ".rn-flow-progress.json";
+export const ERROR_HOOK_COMMAND = '"$CLAUDE_PROJECT_DIR"/.claude/hooks/rn-error-notify.sh';
+export const FLOW_PROGRESS_HOOK_COMMAND = '"$CLAUDE_PROJECT_DIR"/.claude/hooks/rn-flow-progress-notify.sh';
+export const CLAUDE_SETTINGS_REL_PATHS = [
+    [".claude", "settings.json"],
+    [".claude", "settings.local.json"],
+];

package/dist/init/lan-ip.d.ts

@@ -0,0 +1,11 @@
+import { type NetworkInterfaceInfo } from "node:os";
+export interface LanIpCandidate {
+    interfaceName: string;
+    address: string;
+    kind: "wifi" | "usb-ethernet" | "other";
+}
+export interface DetectMacLanIpDeps {
+    networkInterfaces?: () => Record<string, NetworkInterfaceInfo[] | undefined>;
+}
+export declare function detectMacLanIpCandidates(deps?: DetectMacLanIpDeps): LanIpCandidate[];
+export declare function detectMacLanIp(deps?: DetectMacLanIpDeps): LanIpCandidate | null;

package/dist/init/lan-ip.js

@@ -0,0 +1,51 @@
+import { networkInterfaces } from "node:os";
+const WIFI_INTERFACE_NAMES = new Set(["en0"]);
+const USB_ETHERNET_INTERFACE_NAMES = new Set(["en5", "en6"]);
+function classifyCandidate(ifName, info) {
+    if (info.family !== "IPv4")
+        return null;
+    if (info.internal)
+        return null;
+    if (info.address.startsWith("127."))
+        return null;
+    if (info.address.startsWith("169.254."))
+        return null;
+    let kind;
+    if (WIFI_INTERFACE_NAMES.has(ifName))
+        kind = "wifi";
+    else if (USB_ETHERNET_INTERFACE_NAMES.has(ifName))
+        kind = "usb-ethernet";
+    else
+        return null;
+    return { interfaceName: ifName, address: info.address, kind };
+}
+export function detectMacLanIpCandidates(deps = {}) {
+    const reader = deps.networkInterfaces ?? networkInterfaces;
+    const ifs = reader();
+    const seen = new Set();
+    const wifi = [];
+    const usb = [];
+    const names = Object.keys(ifs).sort();
+    for (const name of names) {
+        const infos = ifs[name];
+        if (!infos)
+            continue;
+        for (const info of infos) {
+            const candidate = classifyCandidate(name, info);
+            if (!candidate)
+                continue;
+            if (seen.has(candidate.address))
+                continue;
+            seen.add(candidate.address);
+            if (candidate.kind === "wifi")
+                wifi.push(candidate);
+            else
+                usb.push(candidate);
+        }
+    }
+    return [...wifi, ...usb];
+}
+export function detectMacLanIp(deps = {}) {
+    const candidates = detectMacLanIpCandidates(deps);
+    return candidates[0] ?? null;
+}

package/dist/init/monorepo.d.ts

@@ -0,0 +1,13 @@
+export interface MonorepoCandidate {
+    absPath: string;
+    relPath: string;
+    signals: ReadonlyArray<"expo" | "react-native" | "app.json">;
+}
+export interface MonorepoDetectionResult {
+    kind: "none" | "single" | "multi";
+    matches: MonorepoCandidate[];
+    rootIsRnApp: boolean;
+    isMonorepo: boolean;
+}
+export declare function readWorkspaceGlobs(projectDir: string): Promise<string[] | null>;
+export declare function detectMonorepoSubpackages(projectDir: string): Promise<MonorepoDetectionResult>;