@avasapp/agent-bridge 0.4.1 → 0.5.0

package/dist/cli.js

@@ -2,10 +2,12 @@
 import {
   AgentBridgeCallError,
   RUNTIME_MARKER,
+  assertListening,
   checkName,
   connect,
   connectSession,
   encodeLine,
+  explainConnectError,
   explicitMetro,
   flowScenarios,
   formatDuration,
@@ -14,6 +16,7 @@ import {
   listSessions,
   logLine,
   metroHost,
+  noAppHint,
   openConnection,
   parseDuration,
   parseScenarioFlag,
@@ -26,11 +29,11 @@ import {
   sessionRequest,
   stateDir,
   writePrivate
-} from "./chunk-AJD3XTNT.js";
+} from "./chunk-3QIG7A5W.js";
 
 // src/cli.ts
 import { readFile } from "fs/promises";
-import { resolve } from "path";
+import { resolve as resolve2 } from "path";
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
 
@@ -591,11 +594,11 @@ import { appendFileSync as appendFileSync2, chmodSync, rmSync } from "fs";
 import { createServer } from "net";
 import { createInterface as createInterface3 } from "readline";
 var RELOAD = "app.reload";
-var pause = (ms, signal) => new Promise((resolve2) => {
+var pause = (ms, signal) => new Promise((resolve3) => {
   const done = () => {
     clearTimeout(timer);
     signal.removeEventListener("abort", done);
-    resolve2();
+    resolve3();
   };
   const timer = setTimeout(done, ms);
   signal.addEventListener("abort", done, { once: true });
@@ -619,22 +622,28 @@ async function runSessionDaemon(options) {
   const attemptMs = options.attemptMs ?? 12e3;
   const stopping = new AbortController();
   const cutOff = new AbortController();
-  const reach = (signal) => openConnection({
+  const reach = (signal, pin2) => openConnection({
     metro,
     device: options.device,
+    pin: pin2,
     transport: options.transport,
     ...signal && { signal, timeoutMs: attemptMs }
   });
-  let conn = await reach();
-  const owner = listSessions(dir).find(
-    (s) => s.metro === metro && s.device.deviceId === conn.device.deviceId
-  );
-  if (owner) {
-    conn.close();
+  const claim = (c) => {
+    const owner = listSessions(dir).find(
+      (s) => s.name !== name && s.metro === metro && s.device.deviceId === c.device.deviceId
+    );
+    if (!owner) return;
+    c.close();
     throw new Error(
-      `${conn.device.name} already belongs to session "${owner.name}". Use --session ${owner.name}, or stop it first.`
+      `${c.device.name} already belongs to session "${owner.name}". Use --session ${owner.name}, or stop it first.`
     );
-  }
+  };
+  let conn = await reach().catch(async (error) => {
+    throw await explainConnectError(error, metro, options.device);
+  });
+  claim(conn);
+  const pin = conn.pin;
   const deviceOf = (c) => ({
     name: c.device.name,
     deviceId: c.device.deviceId,
@@ -690,7 +699,8 @@ async function runSessionDaemon(options) {
       const deadline = Date.now() + (patient ? reloadWaitMs : 0);
       for (; ; ) {
         try {
-          const next = await reach(cutOff.signal);
+          const next = await reach(cutOff.signal, pin);
+          claim(next);
           if (patient && knownLoad && next.device.loadId === knownLoad) {
             next.close();
             throw new Error("the old runtime still answers");
@@ -948,11 +958,11 @@ async function runSessionDaemon(options) {
   });
   if (process.platform !== "win32") rmSync(files.socket, { force: true });
   try {
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve3, reject) => {
       server.once("error", reject);
       server.listen(files.socket, () => {
         server.off("error", reject);
-        resolve2();
+        resolve3();
       });
     });
   } catch (error) {
@@ -1039,7 +1049,7 @@ async function start(flags) {
     [...process.execArgv, process.argv[1], ...args],
     { detached: true, stdio: "ignore", windowsHide: true }
   );
-  const state = await new Promise((resolve2, reject) => {
+  const state = await new Promise((resolve3, reject) => {
     const deadline = Date.now() + 3e4;
     let exited = false;
     child.once("exit", () => {
@@ -1050,7 +1060,7 @@ async function start(flags) {
       const failed = existsSync(files.error);
       if (ready && ready.pid === child.pid) {
         clearInterval(tick);
-        resolve2(ready);
+        resolve3(ready);
       } else if (failed || exited || Date.now() > deadline) {
         clearInterval(tick);
         if (!exited) child.kill();
@@ -1172,10 +1182,1151 @@ async function daemonMain(flags) {
   process.exit(0);
 }
 
+// src/init/index.ts
+import { spawn as spawn2 } from "child_process";
+import {
+  appendFileSync as appendFileSync3,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname5, relative as relative4, resolve, sep as sep2 } from "path";
+import { createInterface as createInterface4 } from "readline/promises";
+
+// package.json
+var version = "0.5.0";
+
+// src/init/detect.ts
+import { dirname as dirname3, join as join4, relative } from "path";
+
+// src/init/package-manager.ts
+import { dirname as dirname2, join as join3 } from "path";
+var LOCKFILES = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"]
+];
+var fromName = (value) => {
+  const name = typeof value === "string" ? value.split("@")[0] : void 0;
+  return name === "bun" || name === "pnpm" || name === "yarn" || name === "npm" ? name : void 0;
+};
+function detectPackageManager(dir, root, fs, userAgent = "") {
+  for (const d of [dir, root]) {
+    const pm = fromName(fs.readJson(join3(d, "package.json"))?.packageManager);
+    if (pm) return pm;
+  }
+  for (let d = dir; ; d = dirname2(d)) {
+    for (const [file, pm] of LOCKFILES) if (fs.exists(join3(d, file))) return pm;
+    if (d === root || dirname2(d) === d) break;
+  }
+  return fromName(userAgent.split("/")[0]) ?? "npm";
+}
+function installCommand(pm, spec) {
+  switch (pm) {
+    case "bun":
+      return ["bun", "add", "-d", spec];
+    case "pnpm":
+      return ["pnpm", "add", "-D", spec];
+    case "yarn":
+      return ["yarn", "add", "-D", spec];
+    case "npm":
+      return ["npm", "install", "-D", spec];
+  }
+}
+function binFallback(pm) {
+  switch (pm) {
+    case "bun":
+      return "bunx @avasapp/agent-bridge";
+    case "pnpm":
+      return "pnpm exec agent-bridge";
+    case "yarn":
+      return "yarn agent-bridge";
+    case "npm":
+      return "./node_modules/.bin/agent-bridge";
+  }
+}
+
+// src/init/detect.ts
+var PACKAGE = "@avasapp/agent-bridge";
+var LIBRARIES = {
+  expo: "expo",
+  expoRouter: "expo-router",
+  reactQuery: "@tanstack/react-query",
+  webview: "react-native-webview",
+  zustand: "zustand",
+  mmkv: "react-native-mmkv",
+  ably: "ably",
+  socketIo: "socket.io-client",
+  reactNavigation: "@react-navigation/native",
+  typescript: "typescript"
+};
+var SOURCE_EXTS = ["tsx", "ts", "jsx", "js"];
+var depsOf = (pkg) => ({
+  ...pkg?.peerDependencies,
+  ...pkg?.devDependencies,
+  ...pkg?.dependencies
+});
+var isApp = (dir, fs) => !!fs.readJson(join4(dir, "package.json"))?.dependencies?.["react-native"] || ["app.json", "app.config.js", "app.config.ts", "ios", "android"].some((f) => fs.exists(join4(dir, f)));
+var isWorkspaceRoot = (dir, fs) => !!fs.readJson(join4(dir, "package.json"))?.workspaces || fs.exists(join4(dir, "pnpm-workspace.yaml"));
+function findUp(dir, fs, test) {
+  for (let d = dir; ; d = dirname3(d)) {
+    if (test(d)) return d;
+    if (fs.exists(join4(d, ".git")) || dirname3(d) === d) return void 0;
+  }
+}
+function workspacePatterns(root, fs) {
+  const ws = fs.readJson(join4(root, "package.json"))?.workspaces;
+  const fromPkg = Array.isArray(ws) ? ws : ws?.packages ?? [];
+  const yaml = fs.read(join4(root, "pnpm-workspace.yaml")) ?? "";
+  const block = yaml.match(/^packages:\s*\n((?:[ \t]*(?:-.*|#.*)?\n?)*)/m)?.[1] ?? "";
+  const fromYaml = [...block.matchAll(/^[ \t]*-[ \t]*['"]?([^'"#\n]+?)['"]?[ \t]*$/gm)].map(
+    (m) => m[1]
+  );
+  return [...fromPkg, ...fromYaml].filter(
+    (p) => typeof p === "string" && !p.startsWith("!")
+  );
+}
+function expandWorkspaces(root, patterns, fs) {
+  const found = /* @__PURE__ */ new Set();
+  const walk = (dir, segments, depth) => {
+    if (!segments.length) {
+      if (fs.exists(join4(dir, "package.json"))) found.add(dir);
+      return;
+    }
+    const [head, ...rest] = segments;
+    const children = () => fs.list(dir).filter((e) => e.dir && e.name !== "node_modules" && !e.name.startsWith("."));
+    if (head === "**") {
+      walk(dir, rest, depth);
+      if (depth < 4)
+        for (const c of children()) walk(join4(dir, c.name), segments, depth + 1);
+    } else if (head.includes("*")) {
+      const re = new RegExp(
+        `^${head.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`
+      );
+      for (const c of children())
+        if (re.test(c.name)) walk(join4(dir, c.name), rest, depth);
+    } else {
+      walk(join4(dir, head), rest, depth);
+    }
+  };
+  for (const p of patterns)
+    walk(root, p.replace(/\/+$/, "").split("/").filter((s) => s && s !== "."), 0);
+  return [...found].sort();
+}
+var firstExisting = (dir, fs, candidates) => candidates.find((c) => fs.exists(join4(dir, c)));
+var withExts = (base) => SOURCE_EXTS.map((e) => `${base}.${e}`);
+function detect(dir, fs, env = {}) {
+  const pkg = fs.readJson(join4(dir, "package.json"));
+  if (!pkg) return { error: `No package.json in ${dir}.` };
+  const deps = depsOf(pkg);
+  if (!deps["react-native"]) {
+    if (isWorkspaceRoot(dir, fs)) {
+      const apps = expandWorkspaces(dir, workspacePatterns(dir, fs), fs).filter((d) => isApp(d, fs)).map((d) => relative(dir, d));
+      return {
+        error: apps.length ? `${dir} is a monorepo root. Rerun with --dir pointing at the app: ${apps.map((a) => `--dir ${a}`).join(", ")}` : `${dir} is a monorepo root and no workspace package depends on react-native.`,
+        workspaces: apps
+      };
+    }
+    return {
+      error: `${dir} isn't a React Native app: its package.json has no react-native dependency. Pass --dir <app>.`
+    };
+  }
+  const root = findUp(dir, fs, (d) => isWorkspaceRoot(d, fs)) ?? dir;
+  const repoRoot = findUp(dir, fs, (d) => fs.exists(join4(d, ".git"))) ?? root;
+  const has = Object.fromEntries(
+    Object.entries(LIBRARIES).map(([k, dep]) => [k, !!deps[dep]])
+  );
+  const appJson = fs.readJson(join4(dir, "app.json"));
+  const appName = [appJson?.expo?.name, appJson?.name, pkg.name].find(
+    (n) => typeof n === "string" && !!n
+  ) ?? "app";
+  const tsconfig = firstExisting(dir, fs, ["tsconfig.json"]);
+  const rootFile = firstExisting(
+    dir,
+    fs,
+    has.expoRouter ? [...withExts("app/_layout"), ...withExts("src/app/_layout")] : [...withExts("App"), ...withExts("src/App")]
+  );
+  const agentsFile = [.../* @__PURE__ */ new Set([dir, repoRoot])].flatMap((d) => [join4(d, "AGENTS.md"), join4(d, "CLAUDE.md")]).find((f) => fs.exists(f));
+  let bin;
+  for (let d = dir; ; d = dirname3(d)) {
+    const candidate = join4(d, "node_modules", ".bin", "agent-bridge");
+    if (fs.exists(candidate)) {
+      bin = candidate;
+      break;
+    }
+    if (d === repoRoot || dirname3(d) === d) break;
+  }
+  return {
+    dir,
+    root,
+    repoRoot,
+    appName,
+    pm: detectPackageManager(dir, root, fs, env.userAgent),
+    has,
+    installed: !!deps[PACKAGE],
+    typescript: !!tsconfig || has.typescript,
+    srcDir: fs.exists(join4(dir, "src")),
+    rootFile,
+    tsconfig,
+    oxlint: firstExisting(dir, fs, [".oxlintrc.json"]),
+    eslint: firstExisting(dir, fs, [
+      "eslint.config.js",
+      "eslint.config.mjs",
+      "eslint.config.cjs",
+      "eslint.config.ts"
+    ]),
+    agentsFile,
+    bin
+  };
+}
+
+// src/init/plan.ts
+import { dirname as dirname4, isAbsolute, join as join5, relative as relative2, sep } from "path";
+
+// src/init/jsonc.ts
+function strip(text) {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+    } else if (c === "/" && text[i + 1] === "/") {
+      const end = text.indexOf("\n", i);
+      const j = end === -1 ? text.length : end;
+      out += " ".repeat(j - i);
+      i = j;
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      const j = end === -1 ? text.length : end + 2;
+      out += text.slice(i, j).replace(/[^\n]/g, " ");
+      i = j;
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out.replace(/,(\s*[}\]])/g, " $1");
+}
+function parseJsonc(text) {
+  try {
+    return JSON.parse(strip(text));
+  } catch {
+    return void 0;
+  }
+}
+function addToArray(text, key, value, initial = []) {
+  const json = parseJsonc(text);
+  if (!json || typeof json !== "object" || Array.isArray(json)) return void 0;
+  const current = json[key];
+  const clean = strip(text);
+  const item = JSON.stringify(value);
+  if (Array.isArray(current)) {
+    const matches = [...clean.matchAll(new RegExp(`"${key}"\\s*:\\s*\\[`, "g"))];
+    if (matches.length !== 1) return void 0;
+    const at = matches[0].index + matches[0][0].length;
+    const after = text.slice(at);
+    const multiline = after.match(/^[ \t]*\n([ \t]*)/);
+    if (!current.length) return `${text.slice(0, at)}${item}${after}`;
+    if (multiline) return `${text.slice(0, at)}
+${multiline[1]}${item},${after}`;
+    return `${text.slice(0, at)}${item}, ${after}`;
+  }
+  if (current !== void 0) return void 0;
+  const end = clean.slice(0, clean.lastIndexOf("}")).trimEnd().length;
+  const indent = text.match(/^([ \t]+)"/m)?.[1] ?? "  ";
+  const comma = clean.slice(0, end).endsWith("{") ? "" : ",";
+  const list2 = [...initial, value].map((v) => JSON.stringify(v)).join(", ");
+  return `${text.slice(0, end)}${comma}
+${indent}"${key}": [${list2}]${text.slice(end)}`;
+}
+
+// src/init/render.ts
+import { createHash } from "crypto";
+var DOCS = "https://github.com/avas-app/agent-bridge/blob/main/docs";
+var FLOW_GLOB = "**/*.flow.*";
+var REALTIME = {
+  "socket.io": { fn: "socketIoTools", from: "@avasapp/agent-bridge/socket.io", client: "socket" },
+  ably: { fn: "ablyTools", from: "@avasapp/agent-bridge/ably", client: "ably" }
+};
+var STORES_WHY = "stores often hold tokens: add `redact` for those paths before wiring them";
+var MMKV_WHY = "MMKV often holds tokens and mmkv.get returns values as they are: wire only instances without secrets";
+var REALTIME_WHY = "the adapter must wrap the client where it is created, before the app subscribes";
+var NETWORK_PROMPT = "Wire network tools? In dev builds they patch fetch and XMLHttpRequest so the agent can log and mock requests.";
+var NETWORK_WHY = "networkTools patches fetch and XMLHttpRequest in dev builds so the agent can log and mock requests (net.*); it also enables the offline scenario";
+var storeKey = (name) => {
+  const bare = name.replace(/^use/, "").replace(/Store$/, "") || name;
+  return bare[0].toLowerCase() + bare.slice(1);
+};
+function realtimeLine(todo) {
+  const r = REALTIME[todo.kind];
+  return `export const realtimeDevTools = ${r.fn}(${todo.name ?? r.client})`;
+}
+function realtimeTodoText(todo) {
+  const r = REALTIME[todo.kind];
+  const where = todo.file ? `In ${todo.file}, right after \`${todo.name}\` is created` : `Where your ${todo.kind} client is created`;
+  return `${where}, add \`${realtimeLine(todo)}\` (import { ${r.fn} } from '${r.from}'), then spread realtimeDevTools into tools`;
+}
+function renderBridgeFile(o) {
+  const L = [];
+  const core = ["cdpTransport", ...o.ts ? ["type Scenarios"] : [], "useAgentBridge"];
+  L.push(
+    `// Generated by agent-bridge init ${o.version}. Yours to edit: once changed, init never overwrites it.`,
+    `import { ${core.join(", ")} } from '@avasapp/agent-bridge'`
+  );
+  if (o.expo) L.push(`import { expoTransport } from '@avasapp/agent-bridge/expo'`);
+  if (o.expoRouter) L.push(`import { routerTools } from '@avasapp/agent-bridge/expo-router'`);
+  if (o.network)
+    L.push(`import { networkTools, strictNetwork } from '@avasapp/agent-bridge/network'`);
+  if (o.webview)
+    L.push(`import { webviewTools } from '@avasapp/agent-bridge/react-native-webview'`);
+  if (o.reactQuery) {
+    L.push(
+      `import { queryTools } from '@avasapp/agent-bridge/tanstack-query'`,
+      `import { QueryClientContext } from '@tanstack/react-query'`
+    );
+  }
+  if (o.expoRouter) L.push(`import { router, useNavigationContainerRef } from 'expo-router'`);
+  if (o.reactQuery) L.push(`import { useContext } from 'react'`);
+  if (o.realtimeTools?.length)
+    L.push("", ...o.realtimeTools.map((t) => `import { ${t.name} } from '${t.from}'`));
+  if (o.stores) {
+    const stores = o.stores.length ? o.stores : [{ name: "useAuthStore", from: "../stores/auth" }];
+    L.push(
+      "",
+      "// Zustand stores are left out: they often hold tokens. Add `redact` for those",
+      "// paths, then uncomment these and storeTools below. See",
+      `// ${DOCS}/adapters.md`,
+      `// import { storeTools } from '@avasapp/agent-bridge/zustand'`,
+      ...stores.map((s) => `// import { ${s.name} } from '${s.from}'`)
+    );
+  }
+  if (o.mmkv) {
+    const mmkv = o.mmkv.length ? o.mmkv : [{ name: "storage", from: "../storage" }];
+    L.push(
+      "",
+      "// MMKV is left out: it often holds tokens, and mmkv.get returns values as they",
+      "// are. Wire only instances without secrets: uncomment these and mmkvTools below.",
+      `// See ${DOCS}/adapters.md`,
+      `// import { mmkvTools } from '@avasapp/agent-bridge/react-native-mmkv'`,
+      ...mmkv.map((m) => `// import { ${m.name} } from '${m.from}'`)
+    );
+  }
+  for (const todo of o.realtime) {
+    const r = REALTIME[todo.kind];
+    L.push(
+      "",
+      `// TODO ${todo.kind}: the adapter must wrap the client where it is created,`,
+      `// before the app subscribes (${DOCS}/realtime.md).`,
+      todo.file ? `// In ${todo.file}, right after \`${todo.name}\` is created, add:` : `// Where your ${todo.kind} client is created, add:`,
+      `//   import { ${r.fn} } from '${r.from}'`,
+      `//   ${realtimeLine(todo)}`,
+      `// then import realtimeDevTools here and uncomment it in tools.`
+    );
+  }
+  L.push("");
+  if (o.ts) L.push("const scenarios: Scenarios = {");
+  else L.push(`/** @type {import('@avasapp/agent-bridge').Scenarios} */`, "const scenarios = {");
+  if (o.network) {
+    L.push(
+      "  offline: {",
+      `    description: 'Every request fails like a network failure; Metro still gets through.',`,
+      "    apply: ({ onUndo }) => {",
+      "      onUndo(strictNetwork({ offline: true }))",
+      "    },",
+      "  },"
+    );
+  }
+  L.push(
+    "  // A user signed in locally with every request mocked: the state most flows",
+    `  // start from. See ${DOCS}/scenarios.md`,
+    "  // signedIn: {",
+    `  //   description: 'Signed in locally; no request reaches a server.',`,
+    "  //   apply: async ({ call, onUndo }) => {",
+    `  //     onUndo(strictNetwork())  // and mockApi, both from '@avasapp/agent-bridge/network'`,
+    `  //     onUndo(mockApi(API_URL, { 'GET /me': { json: user } }))`,
+    `  //     await call('store.set', 'auth', { token: 'local', user })`,
+    "  //     return { user }",
+    "  //   },",
+    "  // },",
+    "}",
+    "",
+    "export function AgentBridge() {"
+  );
+  if (o.reactQuery)
+    L.push(
+      "  // Undefined outside a QueryClientProvider: mount this inside one for query.* tools.",
+      "  const queryClient = useContext(QueryClientContext)"
+    );
+  L.push(
+    "  useAgentBridge({",
+    `    name: '${o.appName.replace(/[\\']/g, "\\$&")}',`,
+    `    transports: [${o.expo ? "expoTransport(), " : ""}cdpTransport()],`,
+    "    tools: {"
+  );
+  if (o.reactQuery) L.push("      ...(queryClient ? queryTools(queryClient) : {}),");
+  if (o.expoRouter)
+    L.push("      ...routerTools(router, { navigation: useNavigationContainerRef() }),");
+  if (o.webview)
+    L.push(
+      `      // Each WebView also needs useWebViewTools (${DOCS}/webviews.md).`,
+      "      ...webviewTools(),"
+    );
+  if (o.network) L.push("      ...networkTools(),");
+  for (const t of o.realtimeTools ?? []) L.push(`      ...${t.name},`);
+  if (o.stores) {
+    const stores = o.stores.length ? o.stores : [{ name: "useAuthStore", from: "" }];
+    const map = stores.map((s) => `${storeKey(s.name)}: ${s.name}`).join(", ");
+    const first = storeKey(stores[0].name);
+    L.push(`      // ...storeTools({ ${map} }, { redact: { ${first}: ['token'] } }),`);
+  }
+  if (o.mmkv) {
+    const mmkv = o.mmkv.length ? o.mmkv : [{ name: "storage", from: "" }];
+    L.push(`      // ...mmkvTools({ ${mmkv.map((m) => m.name).join(", ")} }),`);
+  }
+  if (o.realtime.length) L.push("      // ...realtimeDevTools,");
+  if (o.reactNavigation) {
+    const params = o.ts ? "name: string, params?: object" : "name, params";
+    L.push(
+      "      // React Navigation has no adapter. With your container ref",
+      "      // (createNavigationContainerRef from @react-navigation/native), tools like these work:",
+      `      // 'nav.navigate': (${params}) => navigationRef.navigate(name, params),`,
+      `      // 'nav.current': () => navigationRef.getCurrentRoute(),`
+    );
+  }
+  L.push(
+    `      // Your own tools: any function, JSON in and out, e.g. 'cart.clear': () => clearCart(),`,
+    "    },",
+    "    scenarios,",
+    "  })",
+    "  return null",
+    "}",
+    ""
+  );
+  return stamp(L.join("\n"));
+}
+function renderMountSnippet(importPath2) {
+  return `import { AgentBridge } from '${importPath2}'
+{__DEV__ ? <AgentBridge /> : null}`;
+}
+function renderSmokeFlow(o) {
+  return stamp([
+    `// Generated by agent-bridge init ${o.version}. Run it with:`,
+    `//   ${o.bin} run flows/smoke.flow.mjs`,
+    `/** @type {import('@avasapp/agent-bridge/client').FlowModule['default']} */`,
+    "const smoke = async ({ step }) => {",
+    `  await step('snapshot', 'screen.snapshot')`,
+    ...o.expoRouter ? [`  await step('open home', 'router.navigate', '/')`] : [],
+    "  // TODO: wait for text your first screen always shows, for example:",
+    `  // await step('home shown', 'screen.waitFor', 'Welcome')`,
+    `  await step('undo', 'bridge.restore')`,
+    "}",
+    "",
+    "export default smoke",
+    ""
+  ].join("\n"));
+}
+function renderFlowsReadme(bin) {
+  return `Flows for \`${bin} run flows/<name>.flow.mjs\`: plain .mjs files named \`*.flow.mjs\`, kept out of \`app/\` and test globs. See ${DOCS}/cli.md#flows-where-they-go.
+`;
+}
+function agentsLine(appDir, bin) {
+  const where = appDir ? `${appDir}/flows` : "flows";
+  const run = `\`${bin} run flows/smoke.flow.mjs\``;
+  return `- Flows for agent-bridge live in \`${where}/<name>.flow.mjs\` (never under \`app/\`, never \`*.test.*\`); run one ${appDir ? `from \`${appDir}\` with ${run}` : `with ${run}`}.`;
+}
+var HEADER = /^(\/\/ Generated by agent-bridge init \d+\.\d+\.\d+(?:-[\w.]+)?)( \(#([0-9a-f]{12})\))?\./;
+var hash = (body) => createHash("sha256").update(body).digest("hex").slice(0, 12);
+function stamp(content) {
+  const nl = content.indexOf("\n");
+  return content.slice(0, nl).replace(HEADER, `$1 (#${hash(content.slice(nl))}).`) + content.slice(nl);
+}
+function isPristine(text) {
+  const nl = text.indexOf("\n");
+  const recorded = text.slice(0, nl).match(HEADER)?.[3];
+  return !!recorded && recorded === hash(text.slice(nl));
+}
+var NETWORK_LINES = [
+  `import { networkTools } from '@avasapp/agent-bridge/network'`,
+  "...networkTools(),  // in useAgentBridge({ tools })"
+];
+var indentOf = (text) => text.match(/^([ \t]+)"/m)?.[1] ?? "  ";
+function patchJson(text, edit, manual) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return { manual };
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json)) return { manual };
+  if (!edit(json)) return { unchanged: true };
+  return {
+    text: JSON.stringify(json, null, indentOf(text)) + (text.endsWith("\n") ? "\n" : "")
+  };
+}
+function patchPackageScripts(text) {
+  return patchJson(
+    text,
+    (pkg) => {
+      if (pkg.scripts?.flow !== void 0) return false;
+      pkg.scripts = { ...pkg.scripts, flow: "agent-bridge run" };
+      return true;
+    },
+    `Add to package.json scripts: "flow": "agent-bridge run"`
+  );
+}
+var globRe = (glob) => new RegExp(
+  `^${glob.replace(/^\.\//, "").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\0").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, "(?:.*/)?")}$`
+);
+function includesFlows(pattern) {
+  const last = pattern.split("/").pop() ?? "";
+  const glob = last.includes(".") ? pattern : `${pattern.replace(/\/+$/, "")}${last === "*" ? "" : "/**/*"}`;
+  return globRe(glob).test("flows/smoke.flow.mjs");
+}
+function patchTsconfig(text, baseAllowJs) {
+  const manual = `Add "${FLOW_GLOB}" to "exclude" in tsconfig.json`;
+  const json = parseJsonc(text);
+  if (!json || typeof json !== "object") return { manual };
+  if (Array.isArray(json.exclude) && json.exclude.includes(FLOW_GLOB)) return { unchanged: true };
+  const allowJs = json.compilerOptions?.allowJs ?? baseAllowJs ?? true;
+  const include = Array.isArray(json.include) ? json.include : json.files ? [] : ["**/*"];
+  if (!allowJs || !include.some((p) => typeof p === "string" && includesFlows(p)))
+    return { unchanged: true, note: "doesn't include .mjs files" };
+  if (json.extends && !Array.isArray(json.exclude))
+    return {
+      manual: `${manual}, along with what it inherits from ${JSON.stringify(json.extends)}: an "exclude" here replaces the inherited one`
+    };
+  const patched = addToArray(text, "exclude", FLOW_GLOB, ["node_modules"]);
+  return patched ? { text: patched } : { manual };
+}
+function patchOxlint(text) {
+  const ignore = parseJsonc(text)?.ignorePatterns;
+  if (Array.isArray(ignore) && ignore.includes(FLOW_GLOB)) return { unchanged: true };
+  const patched = addToArray(text, "ignorePatterns", FLOW_GLOB);
+  return patched ? { text: patched } : { manual: `Add "${FLOW_GLOB}" to "ignorePatterns" in .oxlintrc.json` };
+}
+var ESLINT_SNIPPET = `{ ignores: ['${FLOW_GLOB}'] },`;
+function patchEslint(text) {
+  if (text.includes(FLOW_GLOB)) return { unchanged: true };
+  const manual = `Add to the start of your ESLint flat config array: ${ESLINT_SNIPPET}`;
+  const re = /^((?:module\.exports\s*=|export\s+default)\s*(?:defineConfig\(\s*)?\[)/gm;
+  const matches = [...text.matchAll(re)];
+  if (matches.length !== 1) return { manual };
+  const at = matches[0].index + matches[0][1].length;
+  return { text: `${text.slice(0, at)}
+  ${ESLINT_SNIPPET}${text.slice(at)}` };
+}
+
+// src/init/plan.ts
+var SKILL_COMMAND = ["npx", "skills", "add", "avas-app/agent-bridge"];
+var SKILL_RUN = ["npx", "--yes", "skills", "add", "avas-app/agent-bridge"];
+var PLUGIN_LINES = [
+  "/plugin marketplace add avas-app/agent-bridge",
+  "/plugin install agent-bridge@agent-bridge"
+];
+var MARKERS = [
+  ["expo", /expoTransport/, "expo"],
+  ["expoRouter", /routerTools/, "expo-router"],
+  ["reactQuery", /queryTools/, "@tanstack/react-query"],
+  ["webview", /webviewTools/, "react-native-webview"],
+  ["zustand", /storeTools/, "zustand"],
+  ["mmkv", /mmkvTools/, "react-native-mmkv"],
+  ["socketIo", /realtimeDevTools|socketIoTools|realtime/i, "socket.io-client"],
+  ["ably", /realtimeDevTools|ablyTools|realtime/i, "ably"]
+];
+var posix = (p) => p.split(sep).join("/");
+function importPath(fromFile, toFile) {
+  const rel = posix(relative2(dirname4(fromFile), toFile)).replace(/\.(tsx?|jsx?|mjs|cjs)$/, "");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function binFor(d) {
+  if (d.bin) {
+    const rel = posix(relative2(d.dir, d.bin));
+    return rel.startsWith(".") ? rel : `./${rel}`;
+  }
+  if (d.pm === "npm" && d.root !== d.dir)
+    return `${posix(relative2(d.dir, d.root))}/node_modules/.bin/agent-bridge`;
+  return binFallback(d.pm);
+}
+function bridgePath(d, out) {
+  if (out) return isAbsolute(out) ? out : join5(d.dir, out);
+  return join5(d.dir, d.srcDir ? "src/dev" : "dev", `agent-bridge.${d.typescript ? "tsx" : "js"}`);
+}
+function nextSteps(bin, o) {
+  const { offline, runFrom } = o;
+  const next = [];
+  if (!o.mounted)
+    next.push({
+      step: o.elsewhere ? "Make sure the root component renders the component that calls useAgentBridge" : "Mount it: paste the snippet above"
+    });
+  next.push(
+    { step: "Reload the app (press r in Metro)" },
+    { step: "Start a session", command: `${bin} session start` },
+    { step: "List the tools", command: `${bin} tools` },
+    { step: "See what's on screen", command: `${bin} call screen.snapshot` }
+  );
+  if (offline)
+    next.push({ step: "Try a scenario", command: `${bin} call scenario.apply '"offline"'` });
+  next.push({ step: "Undo everything and disconnect", command: `${bin} session stop` });
+  const from = runFrom === "." ? "" : `From \`${runFrom}\`: `;
+  return {
+    next,
+    prompt: `This app has agent-bridge. ${from ? `${from}s` : "S"}tart a session with \`${bin} session start\`, see the screen with \`${bin} call screen.snapshot\`, and check changes through the bridge instead of tapping; stop the session when done.`
+  };
+}
+var stripExt = (p) => p.replace(/\.(tsx?|jsx?|mjs|cjs)$/, "").replace(/\/index$/, "");
+function readTsconfig(d, fs) {
+  if (!d.tsconfig) return { aliases: [] };
+  const file = join5(d.dir, d.tsconfig);
+  const json = parseJsonc(fs.read(file) ?? "");
+  if (!json) return { aliases: [] };
+  const findExtended = (from2, ext2) => {
+    const names = ext2.endsWith(".json") ? [ext2] : [ext2, `${ext2}.json`];
+    const roots = ext2.startsWith(".") ? [dirname4(from2)] : ancestors(dirname4(from2), d.repoRoot).map((a) => join5(a, "node_modules"));
+    for (const r of roots) for (const n of names) if (fs.exists(join5(r, n)) && !fs.list(join5(r, n)).length) return join5(r, n);
+    return void 0;
+  };
+  let baseAllowJs;
+  let ext = json.extends;
+  let from = file;
+  for (let depth = 0; typeof ext === "string" && depth < 4; depth++) {
+    const path = findExtended(from, ext);
+    const base = path ? parseJsonc(fs.read(path) ?? "") : void 0;
+    if (!base) break;
+    if (typeof base.compilerOptions?.allowJs === "boolean") {
+      baseAllowJs = base.compilerOptions.allowJs;
+      break;
+    }
+    ext = base.extends;
+    from = path;
+  }
+  const baseDir = join5(d.dir, json.compilerOptions?.baseUrl ?? ".");
+  const paths = json.compilerOptions?.paths ?? {};
+  const aliases = Object.entries(paths).flatMap(
+    ([pattern, targets]) => Array.isArray(targets) && typeof targets[0] === "string" ? [[pattern.replace(/\*$/, ""), join5(baseDir, targets[0].replace(/\*$/, ""))]] : []
+  );
+  return { json, baseAllowJs, aliases };
+}
+function ancestors(dir, stop2) {
+  const out = [];
+  for (let d = dir; ; d = dirname4(d)) {
+    out.push(d);
+    if (d === stop2 || dirname4(d) === d) return out;
+  }
+}
+function importedFiles(file, text, aliases) {
+  const specs = [...text.matchAll(/(?:from\s+|import\s+|require\(\s*)['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  return specs.flatMap((spec) => {
+    if (spec.startsWith(".")) return [stripExt(join5(dirname4(file), spec))];
+    const alias = aliases.find(([prefix]) => prefix && spec.startsWith(prefix));
+    return alias ? [stripExt(join5(alias[1], spec.slice(alias[0].length)))] : [];
+  });
+}
+function plan(d, found, fs, o, cwd) {
+  const rel = (p) => posix(relative2(d.dir, p));
+  const out = bridgePath(d, o.out);
+  if (rel(out).startsWith("..") || isAbsolute(rel(out)))
+    return { error: `--out ${o.out} is outside the app (${d.dir}).` };
+  if (/^(src\/)?app\//.test(rel(out)))
+    return {
+      error: `${rel(out)} is under app/, where expo-router treats every file as a route. Pick another --out.`
+    };
+  const ts = /\.tsx?$/.test(out);
+  const bin = binFor(d);
+  const runFrom = posix(relative2(cwd, d.dir)) || ".";
+  const tsconfig = readTsconfig(d, fs);
+  const actions = [];
+  const files = [];
+  const commented = [];
+  const todos = [];
+  const generate = (path, content) => {
+    const current = fs.read(path);
+    if (current === void 0) {
+      actions.push({ kind: "write", path, content });
+      files.push({ path: rel(path), status: "written" });
+      return "written";
+    }
+    const pristine = isPristine(current);
+    if (!o.force) {
+      files.push({
+        path: rel(path),
+        status: "skipped",
+        note: pristine ? "exists; --force regenerates it" : "exists, edited since init wrote it"
+      });
+      return pristine ? "kept" : "edited";
+    }
+    if (pristine) {
+      const same = current === content;
+      if (!same) actions.push({ kind: "write", path, content });
+      files.push({ path: rel(path), status: same ? "unchanged" : "written" });
+      return "written";
+    }
+    actions.push({ kind: "write", path: `${path}.new`, content });
+    files.push({
+      path: rel(path),
+      status: "skipped",
+      note: `edited since init wrote it, so --force left it; wrote ${rel(path)}.new to compare`
+    });
+    files.push({ path: `${rel(path)}.new`, status: "written" });
+    return "edited";
+  };
+  const imported = (list2) => list2.map((f) => ({ name: f.name, from: importPath(out, join5(d.dir, f.file)) }));
+  const realtimeTools = imported(found.realtimeTools);
+  const realtime = realtimeTools.length ? [] : [
+    ...d.has.socketIo ? found.socketIo.length ? found.socketIo.map((f) => ({ kind: "socket.io", ...f })) : [{ kind: "socket.io" }] : [],
+    ...d.has.ably ? found.ably.length ? found.ably.map((f) => ({ kind: "ably", ...f })) : [{ kind: "ably" }] : []
+  ];
+  const existingText = fs.read(out);
+  const existing = found.bridgeUsers.filter((f) => stripExt(join5(d.dir, f)) !== stripExt(out));
+  const elsewhere = existingText === void 0 && existing.length > 0 && !o.out;
+  let state = "elsewhere";
+  if (elsewhere) {
+    files.push({
+      path: rel(out),
+      status: "skipped",
+      note: `the app already uses the bridge in ${existing.join(", ")}; pass --out to write one anyway`
+    });
+  } else {
+    state = generate(
+      out,
+      renderBridgeFile({
+        version: o.version,
+        appName: d.appName,
+        ts,
+        expo: d.has.expo,
+        expoRouter: d.has.expoRouter,
+        reactQuery: d.has.reactQuery,
+        webview: d.has.webview,
+        network: o.network.enabled,
+        reactNavigation: d.has.reactNavigation && !d.has.expoRouter,
+        stores: d.has.zustand ? imported(found.stores) : void 0,
+        mmkv: d.has.mmkv ? imported(found.mmkv) : void 0,
+        realtime,
+        realtimeTools
+      })
+    );
+  }
+  const wrote = state === "written";
+  const liveText = wrote ? void 0 : elsewhere ? existing.map((f) => fs.read(join5(d.dir, f)) ?? "").join("\n") : existingText;
+  const network = wrote ? o.network.enabled : /networkTools\s*\(/.test(liveText ?? "");
+  const offline = wrote ? o.network.enabled : /\boffline\s*:/.test(liveText ?? "");
+  if (wrote) {
+    if (d.has.zustand)
+      commented.push({
+        adapter: "zustand",
+        items: found.stores.map((s) => `${s.name} (${s.file})`),
+        why: `${STORES_WHY} (${DOCS}/adapters.md)`
+      });
+    if (d.has.mmkv)
+      commented.push({
+        adapter: "react-native-mmkv",
+        items: found.mmkv.map((s) => `${s.name} (${s.file})`),
+        why: `${MMKV_WHY} (${DOCS}/adapters.md)`
+      });
+    if (d.has.reactNavigation && !d.has.expoRouter)
+      commented.push({
+        adapter: "@react-navigation/native",
+        items: ["nav.navigate", "nav.current"],
+        why: "there is no React Navigation adapter; the sample tools need your container ref"
+      });
+    for (const t of realtime) todos.push(`${realtimeTodoText(t)}: ${REALTIME_WHY} (${DOCS}/realtime.md).`);
+  }
+  const missing = !wrote && liveText !== void 0 ? MARKERS.filter(([lib, marker]) => d.has[lib] && !marker.test(liveText)).map(([, , dep]) => dep) : [];
+  const flows = join5(d.dir, "flows");
+  generate(
+    join5(flows, "smoke.flow.mjs"),
+    renderSmokeFlow({ version: o.version, expoRouter: d.has.expoRouter, bin })
+  );
+  const readme = join5(flows, "README.md");
+  if (fs.exists(readme)) files.push({ path: rel(readme), status: "skipped", note: "exists" });
+  else {
+    actions.push({ kind: "write", path: readme, content: renderFlowsReadme(bin) });
+    files.push({ path: rel(readme), status: "written" });
+  }
+  const patch = (path, fn) => {
+    if (!path) return;
+    const abs = join5(d.dir, path);
+    const result = fn(fs.read(abs) ?? "");
+    if ("text" in result) {
+      actions.push({ kind: "patch", path: abs, patch: fn });
+      files.push({ path, status: "patched" });
+    } else if ("manual" in result) {
+      files.push({ path, status: "manual", note: result.manual });
+    } else {
+      files.push({ path, status: "unchanged", ...result.note && { note: result.note } });
+    }
+  };
+  patch("package.json", patchPackageScripts);
+  patch(d.tsconfig, (text) => patchTsconfig(text, tsconfig.baseAllowJs));
+  patch(d.oxlint, patchOxlint);
+  patch(d.eslint, patchEslint);
+  if (d.agentsFile) {
+    const text = fs.read(d.agentsFile) ?? "";
+    const path = posix(relative2(d.dir, d.agentsFile));
+    if (text.includes(".flow.mjs")) files.push({ path, status: "unchanged" });
+    else {
+      const appDir = posix(relative2(dirname4(d.agentsFile), d.dir));
+      actions.push({ kind: "append", path: d.agentsFile, line: agentsLine(appDir, bin) });
+      files.push({ path, status: "appended" });
+    }
+  }
+  const spec = `${PACKAGE}@^${o.version}`;
+  const install = installCommand(d.pm, spec);
+  if (!d.installed && o.install) actions.unshift({ kind: "install", command: install, cwd: d.dir });
+  const skill = o.skillYes ? [...SKILL_RUN, "-y"] : SKILL_RUN;
+  if (o.skill) actions.push({ kind: "skill", command: skill, cwd: d.repoRoot });
+  const rootFile = d.rootFile ? join5(d.dir, d.rootFile) : void 0;
+  const rootImports = rootFile ? importedFiles(rootFile, fs.read(rootFile) ?? "", tsconfig.aliases) : [];
+  const reachedFromRoot = (file) => stripExt(file) === stripExt(rootFile ?? "") || rootImports.includes(stripExt(file));
+  const mounted = elsewhere ? existing.some((f) => reachedFromRoot(join5(d.dir, f))) : rootImports.includes(stripExt(out));
+  const snippet = renderMountSnippet(importPath(rootFile ?? join5(d.dir, "App.tsx"), out));
+  const where = elsewhere ? `The app already uses the bridge in ${existing.join(", ")}; make sure the root component renders it` : d.rootFile ? `Paste the import into ${d.rootFile} and the element into the root component's JSX` : `No root component found (looked for ${d.has.expoRouter ? "app/_layout or src/app/_layout" : "App or src/App"}): paste it into yours, fixing the import path`;
+  const note = `${where}${d.has.reactQuery && !elsewhere ? ", inside QueryClientProvider so query.* tools work" : ""}.`;
+  const regenerable = state === "written" || state === "kept";
+  const ignored = o.network.chosen && !wrote && o.network.enabled !== network ? `${o.network.enabled ? "--network" : "--no-network"} had no effect: ${elsewhere ? existing.join(", ") : rel(out)} already exists${regenerable ? "; add --force to regenerate it" : "; edit it by hand"}.` : void 0;
+  const choice = {
+    enabled: network,
+    open: !network && !(o.network.chosen && wrote),
+    why: NETWORK_WHY,
+    ...regenerable && { flag: network ? "--no-network --force" : "--network --force" },
+    ...!network && { lines: NETWORK_LINES },
+    ...ignored && { note: ignored }
+  };
+  const detected = MARKERS.filter(([lib]) => d.has[lib]).map(([, , dep]) => dep);
+  if (d.has.reactNavigation && !d.has.expoRouter) detected.push("@react-navigation/native");
+  return {
+    actions,
+    report: {
+      ok: true,
+      version: o.version,
+      dryRun: false,
+      app: { dir: d.dir, name: d.appName, packageManager: d.pm, detected },
+      files,
+      install: {
+        status: d.installed ? "present" : "not-run",
+        command: install.join(" ")
+      },
+      skill: { status: "not-run", command: SKILL_COMMAND.join(" "), plugin: PLUGIN_LINES },
+      mount: { file: d.rootFile ?? null, mounted, snippet, note },
+      choices: { network: choice },
+      commented,
+      todos,
+      missing,
+      existing,
+      runFrom,
+      scenarios: offline ? ["offline"] : [],
+      ...nextSteps(bin, { mounted, offline, runFrom, elsewhere })
+    }
+  };
+}
+
+// src/init/scan.ts
+import { join as join6, relative as relative3 } from "path";
+var CODE = /\.(tsx?|jsx?|mjs|cjs)$/;
+var TESTS = /\.(test|spec)\.|(^|\/)__tests__\//;
+var imports = (text, module) => new RegExp(
+  `(from\\s+|require\\(\\s*)['"]${module.replace(/[.]/g, "\\.")}(/[\\w./-]+)?['"]`
+).test(text);
+var TYPED = "(?:\\s*:[^=]+)?";
+var PATTERNS = [
+  ["stores", "zustand", new RegExp(`export\\s+const\\s+(use\\w+)${TYPED}\\s*=\\s*create\\w*\\s*[<(]`, "g")],
+  ["mmkv", "react-native-mmkv", new RegExp(`export\\s+const\\s+(\\w+)${TYPED}\\s*=\\s*(?:new\\s+MMKV|createMMKV)\\s*[<(]`, "g")],
+  ["socketIo", "socket.io-client", new RegExp(`(?:const|let)\\s+(\\w+)${TYPED}\\s*=\\s*io\\s*\\(`, "g")],
+  ["ably", "ably", new RegExp(`(?:const|let)\\s+(\\w+)${TYPED}\\s*=\\s*new\\s+(?:Ably\\.)?Realtime(?:\\.Promise)?\\s*\\(`, "g")],
+  ["realtimeTools", "@avasapp/agent-bridge", /export\s+const\s+(\w+)\s*=\s*(?:socketIoTools|ablyTools)\s*\(/g]
+];
+function scan(dir, fs, { maxFiles = 2e3, maxBytes = 512 * 1024 } = {}) {
+  const files = [];
+  const walk = (d, deep) => {
+    const entries = fs.list(d).sort((a, b) => a.name < b.name ? -1 : 1);
+    for (const e of entries) {
+      if (files.length >= maxFiles) return;
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const path = join6(d, e.name);
+      if (e.dir) {
+        if (deep) walk(path, true);
+      } else if (CODE.test(e.name) && !TESTS.test(relative3(dir, path))) {
+        files.push(path);
+      }
+    }
+  };
+  walk(dir, false);
+  for (const sub of ["src", "app", "lib"]) walk(join6(dir, sub), true);
+  const result = { stores: [], mmkv: [], socketIo: [], ably: [], realtimeTools: [], bridgeUsers: [] };
+  for (const path of files) {
+    const text = fs.read(path);
+    if (!text || text.length > maxBytes) continue;
+    if (/\buseAgentBridge\s*\(|(from\s+|require\(\s*)['"]@avasapp\/agent-bridge['"]/.test(text))
+      result.bridgeUsers.push(relative3(dir, path));
+    for (const [key, module, re] of PATTERNS) {
+      if (!imports(text, module)) continue;
+      for (const m of text.matchAll(re))
+        result[key].push({ name: m[1], file: relative3(dir, path) });
+    }
+  }
+  return result;
+}
+
+// src/init/index.ts
+var INSTALL_TIMEOUT_MS = 5 * 6e4;
+var SKILL_TIMEOUT_MS = 2 * 6e4;
+var posix2 = (p) => p.split(sep2).join("/");
+var nodeFs = {
+  exists: existsSync2,
+  read: (path) => {
+    try {
+      return readFileSync4(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  },
+  readJson: (path) => {
+    try {
+      return JSON.parse(readFileSync4(path, "utf8"));
+    } catch {
+      return void 0;
+    }
+  },
+  list: (dir) => {
+    try {
+      return readdirSync(dir, { withFileTypes: true }).map((e) => ({
+        name: e.name,
+        dir: e.isDirectory()
+      }));
+    } catch {
+      return [];
+    }
+  }
+};
+function nodeIo() {
+  return {
+    fs: nodeFs,
+    write: (path, content) => {
+      mkdirSync2(dirname5(path), { recursive: true });
+      writeFileSync2(path, content);
+    },
+    append: (path, text) => appendFileSync3(path, text),
+    exec: (command, cwd, interactive, timeoutMs) => new Promise((done) => {
+      const [cmd, ...args] = command;
+      const child = spawn2(cmd, args, {
+        cwd,
+        stdio: [interactive ? "inherit" : "ignore", 2, 2],
+        shell: process.platform === "win32"
+      });
+      const timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        done("timeout");
+      }, timeoutMs);
+      child.on("error", () => {
+        clearTimeout(timer);
+        done(127);
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        done(code ?? 1);
+      });
+    }),
+    prompt: async (question) => {
+      const rl = createInterface4({ input: process.stdin, output: process.stderr });
+      try {
+        return await rl.question(question);
+      } finally {
+        rl.close();
+      }
+    },
+    print: (text) => process.stdout.write(`${text}
+`),
+    warn: (text) => process.stderr.write(`${text}
+`),
+    interactive: !!process.stdin.isTTY && !!process.stdout.isTTY && !/^(1|true)$/i.test(process.env.CI ?? ""),
+    cwd: process.cwd(),
+    userAgent: process.env.npm_config_user_agent
+  };
+}
+async function apply(actions, report, io, interactive) {
+  const why = (code, ms) => code === "timeout" ? `timed out after ${ms / 6e4} min` : `exit code ${code}`;
+  for (const a of actions) {
+    switch (a.kind) {
+      case "install": {
+        const code = await io.exec(a.command, a.cwd, false, INSTALL_TIMEOUT_MS);
+        report.install.status = code === 0 ? "installed" : "failed";
+        if (code !== 0) {
+          report.ok = false;
+          report.install.error = why(code, INSTALL_TIMEOUT_MS);
+          io.warn(`Install failed (${a.command.join(" ")}): ${report.install.error}`);
+        }
+        break;
+      }
+      case "skill": {
+        const code = await io.exec(a.command, a.cwd, interactive, SKILL_TIMEOUT_MS);
+        report.skill.status = code === 0 ? "added" : "failed";
+        if (code !== 0) {
+          report.skill.error = why(code, SKILL_TIMEOUT_MS);
+          io.warn(`Adding the skill failed (${report.skill.error}); add it later with ${report.skill.command}`);
+        }
+        break;
+      }
+      case "write":
+        io.write(a.path, a.content);
+        break;
+      case "patch": {
+        const result = a.patch(io.fs.read(a.path) ?? "");
+        if ("text" in result) io.write(a.path, result.text);
+        break;
+      }
+      case "append": {
+        const text = io.fs.read(a.path) ?? "";
+        io.append(a.path, `${text.endsWith("\n") || !text ? "" : "\n"}${a.line}
+`);
+        break;
+      }
+    }
+  }
+}
+var describe = (a, dir) => {
+  const rel = (p) => relative4(dir, p) || ".";
+  switch (a.kind) {
+    case "install":
+      return `install   ${a.command.join(" ")}`;
+    case "skill":
+      return `skill     ${a.command.join(" ")}  (in ${a.cwd})`;
+    case "write":
+      return `write     ${rel(a.path)}`;
+    case "patch":
+      return `patch     ${rel(a.path)}`;
+    case "append":
+      return `append    ${rel(a.path)}: ${a.line}`;
+  }
+};
+function formatReport(r, actions) {
+  const L = [];
+  const detected = r.app.detected.length ? ` (${r.app.detected.join(", ")})` : "";
+  L.push(
+    `agent-bridge init ${r.version}${r.dryRun ? " --dry-run: nothing changed" : ""}`,
+    `App "${r.app.name}"${detected}, ${r.app.packageManager}`,
+    ""
+  );
+  if (r.dryRun) {
+    L.push("Would run:", ...actions.map((a) => `  ${describe(a, r.app.dir)}`), "");
+    for (const a of actions)
+      if (a.kind === "write")
+        L.push(`--- ${relative4(r.app.dir, a.path)}`, a.content.trimEnd(), "");
+  }
+  L.push("Files");
+  for (const f of r.files)
+    L.push(`  ${f.status.padEnd(9)} ${f.path}${f.note ? `: ${f.note}` : ""}`);
+  L.push(
+    "",
+    `Install: ${r.install.status} (${r.install.command})`,
+    `Skill:   ${r.skill.status} (${r.skill.command})`,
+    "         In Claude Code, install it as a plugin instead:",
+    ...r.skill.plugin.map((l) => `           ${l}`)
+  );
+  if (r.existing.length)
+    L.push("", `Already uses the bridge: ${r.existing.join(", ")}`);
+  if (r.missing.length)
+    L.push("", `Detected but not wired in the bridge file: ${r.missing.join(", ")} (see ${DOCS}/adapters.md)`);
+  if (r.commented.length) {
+    L.push("", "Left as comments in the bridge file:");
+    for (const c of r.commented)
+      L.push(`  ${c.adapter}${c.items.length ? `: ${c.items.join(", ")}` : ""}. Why: ${c.why}`);
+  }
+  if (r.todos.length) L.push("", "TODO:", ...r.todos.map((t) => `  ${t}`));
+  const n = r.choices.network;
+  L.push("");
+  if (n.enabled) L.push("Network tools: on (net.*).");
+  else {
+    const how = [n.flag && `rerun with ${n.flag}`, n.lines && "add these lines"].filter(Boolean).join(", or ");
+    L.push(`Network tools: off. ${n.open ? "Open choice: " : ""}${n.why}. To wire them, ${how}:`);
+    L.push(...(n.lines ?? []).map((l) => `  ${l}`));
+  }
+  if (n.note) L.push(n.note);
+  L.push(
+    "",
+    r.mount.mounted ? `Mounted: yes (from ${r.mount.file}).` : `Mounted: no. ${r.mount.note}`
+  );
+  if (!r.mount.mounted && !r.existing.length)
+    L.push(...r.mount.snippet.split("\n").map((l) => `  ${l}`));
+  L.push("", `First run${r.runFrom === "." ? "" : ` (from ${r.runFrom})`}:`);
+  r.next.forEach(
+    (s, i) => L.push(`  ${i + 1}. ${s.step}${s.command ? `
+       ${s.command}` : ""}`)
+  );
+  L.push("", "Prompt for your agent:", `  ${r.prompt}`);
+  return L.join("\n");
+}
+async function runInit(args, io) {
+  const dir = resolve(io.cwd, args.dir ?? ".");
+  const fail = (error) => {
+    if (args.json) io.print(JSON.stringify({ ok: false, ...error }, null, 2));
+    else io.warn(error.error);
+    return 1;
+  };
+  let d = detect(dir, io.fs, { userAgent: io.userAgent });
+  if ("error" in d) return fail(d);
+  const interactive = io.interactive && !args.json && !args.yes;
+  const options = (network2) => ({
+    version,
+    out: args.out === void 0 ? void 0 : resolve(io.cwd, args.out),
+    force: args.force,
+    install: args.install !== false,
+    skill: args.skill !== false,
+    network: network2,
+    skillYes: !interactive
+  });
+  const planFor = (det, network2, install2 = true) => plan(det, scan(dir, io.fs), io.fs, { ...options(network2), install: install2 && args.install !== false }, io.cwd);
+  let network = { enabled: args.network ?? false, chosen: args.network !== void 0 };
+  const first = planFor(d, network);
+  if ("error" in first) return fail(first);
+  if (args.dryRun) {
+    const { actions: actions2, report: report2 } = first;
+    report2.dryRun = true;
+    if (args.json) {
+      const contents = Object.fromEntries(
+        actions2.flatMap((a) => a.kind === "write" ? [[relative4(dir, a.path), a.content]] : [])
+      );
+      io.print(JSON.stringify({ ...report2, contents }, null, 2));
+    } else io.print(formatReport(report2, actions2));
+    return 0;
+  }
+  const bridge = posix2(relative4(dir, bridgePath(d, options(network).out)));
+  const writesBridge = first.report.files.some((f) => f.path === bridge && f.status === "written");
+  if (!network.chosen && interactive && writesBridge) {
+    const answer = await io.prompt(`${NETWORK_PROMPT} [y/N] `);
+    network = { enabled: /^y(es)?$/i.test(answer.trim()), chosen: true };
+  }
+  const install = first.actions.find((a) => a.kind === "install");
+  const installReport = first.report.install;
+  if (install) {
+    await apply([install], first.report, io, interactive);
+    const after = detect(dir, io.fs, { userAgent: io.userAgent });
+    if (!("error" in after)) d = after;
+  }
+  const p = planFor(d, network, false);
+  if ("error" in p) return fail(p);
+  const { actions, report } = p;
+  if (install) {
+    report.install = installReport;
+    report.ok = first.report.ok;
+  }
+  await apply(actions, report, io, interactive);
+  io.print(args.json ? JSON.stringify(report, null, 2) : formatReport(report, actions));
+  return report.ok ? 0 : 1;
+}
+
 // src/cli.ts
 var HELP2 = `agent-bridge: drive a running React Native app from an agent
 
 Usage
+  agent-bridge init                       Set up this app: install, write the dev-only bridge
+                                          file and a smoke flow, print the line to mount it
   agent-bridge devices                    Apps connected to Metro
   agent-bridge tools                      Tools the app exposes
   agent-bridge call <tool> [args]         Call a tool. args: a JSON array, or one JSON value
@@ -1186,7 +2337,7 @@ Usage
   agent-bridge call --batch               Read \`tool args\` lines from stdin (args may be @file); one JSON line per call, one connection
   agent-bridge repl                       Interactive prompt (history, tab completion, .help). With
                                           stdin not a terminal it behaves like call --batch
-  agent-bridge run <flow.mjs|.ts>         Run a flow: export default async ({ step, call }) => {}
+  agent-bridge run <flow.mjs>             Run a flow: export default async ({ step, call }) => {}
                                           export const scenario = 'signedIn' applies it first
                                           and runs bridge.restore after, even on failure
   agent-bridge scenarios                  Scenarios the app defines (scenario.apply applies one)
@@ -1214,6 +2365,17 @@ Options
                          JSON after "=": --scenario 'signedIn={"user":{"name":"Ada"}}'
   --session <name>       Use this session (env AGENT_BRIDGE_SESSION)
   --no-session           Connect directly even if a session is running
+
+init options
+  --dir <path>           The app (default: the current directory)
+  --out <file>           Bridge file path, inside the app (default src/dev/agent-bridge.tsx, or dev/)
+  --dry-run              Print what it would do and the files; change nothing
+  --force                Regenerate files init wrote that are still unedited (edited ones get a .new copy)
+  --no-install           Print the install command instead of running it
+  --no-skill             Don't run \`npx skills add avas-app/agent-bridge\`
+  --network, --no-network  Wire networkTools into a new bridge file (asked in a terminal; off otherwise)
+  --json                 Machine-readable report on stdout; never prompts
+  --yes, -y              Never prompt
 `;
 var failedLogs = (error) => error instanceof AgentBridgeCallError ? error.logs : [];
 async function readStdin() {
@@ -1246,6 +2408,14 @@ async function main() {
       "dry-run": { type: "boolean" },
       session: { type: "string" },
       "no-session": { type: "boolean" },
+      dir: { type: "string" },
+      force: { type: "boolean" },
+      "no-install": { type: "boolean" },
+      "no-skill": { type: "boolean" },
+      network: { type: "boolean" },
+      "no-network": { type: "boolean" },
+      json: { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
       help: { type: "boolean", short: "h" }
     }
   });
@@ -1262,7 +2432,10 @@ async function main() {
   };
   const withBridge = async (fn) => {
     const session = sessionFor(values);
-    if (session) console.error(`Using session "${session.name}"`);
+    if (session)
+      console.error(
+        `Using session "${session.name}" (${session.device.name} on ${session.metro})`
+      );
     const bridge = session ? await connectSession({
       name: session.name,
       timeoutMs: options.timeoutMs
@@ -1282,9 +2455,30 @@ async function main() {
     if (failed) process.exitCode = 1;
   };
   switch (command) {
+    case "init":
+      process.exitCode = await runInit(
+        {
+          dir: values.dir,
+          out: values.out,
+          dryRun: values["dry-run"],
+          force: values.force,
+          install: !values["no-install"],
+          skill: !values["no-skill"],
+          network: values.network ? true : values["no-network"] ? false : void 0,
+          json: values.json,
+          yes: values.yes
+        },
+        nodeIo()
+      );
+      return;
     case "devices": {
       const devices = await listDevices(options);
-      if (!devices.length) console.log("No apps connected.");
+      if (!devices.length) {
+        const metro = metroHost(options.metro);
+        await assertListening(metro);
+        console.log("No apps connected.");
+        console.error(await noAppHint(metro));
+      }
       for (const d of devices) {
         const extra = d.tools !== void 0 ? `  ${d.tools} tools  ${d.deviceId}` : "";
         console.log(`${d.transport.padEnd(5)} ${d.name}${extra}`);
@@ -1345,7 +2539,7 @@ async function main() {
     case "run": {
       const [file] = rest;
       if (!file) throw new Error("Usage: agent-bridge run <flow file>");
-      const flow = await import(pathToFileURL(resolve(file)).href);
+      const flow = await import(pathToFileURL(resolve2(file)).href);
       flowScenarios(flow);
       const extra = (values.scenario ?? []).map(parseScenarioFlag);
       return withBridge(async (bridge) => {