@avasapp/agent-bridge 0.4.1 → 0.5.0

package/dist/client/index.cjs

@@ -76,11 +76,11 @@ async function listCdpTargets(metro, signal) {
     );
   return await res.json();
 }
-function pickOne(items, filter, label) {
+function pickOne(items, filter, label2) {
   const matching = filter ? items.filter(
-    (item) => label(item).toLowerCase().includes(filter.toLowerCase())
+    (item) => label2(item).toLowerCase().includes(filter.toLowerCase())
   ) : items;
-  const connected = items.map(label).join("; ") || "none";
+  const connected = items.map(label2).join("; ") || "none";
   if (matching.length === 0) {
     throw new Error(
       filter ? `No app matches "${filter}". Connected: ${connected}` : "No app is connected to Metro."
@@ -91,6 +91,15 @@ function pickOne(items, filter, label) {
       `${matching.length} apps are connected; pick one with --device. Connected: ${connected}`
     );
   }
+  if (matching.length > 1) {
+    const exact = matching.filter(
+      (item) => label2(item).toLowerCase() === filter?.toLowerCase()
+    );
+    if (exact.length === 1) return exact[0];
+    throw new Error(
+      `${matching.length} apps match "${filter}"; narrow --device. Matching: ${matching.map(label2).join("; ")}`
+    );
+  }
   return matching[0];
 }
 
@@ -107,6 +116,7 @@ function toAsciiJson(value) {
 
 // src/client/connection.ts
 var import_ws = __toESM(require("ws"), 1);
+var describePin = (pin) => `${pin.name} (${pin.platform}${pin.target ? `, ${pin.target}` : ""})`;
 var OPEN_SOCKET_MS = 5e3;
 var OpenGaveUp = class extends Error {
 };
@@ -232,7 +242,7 @@ async function listExpoDevices(metro, discoveryMs = 600) {
   ws.close();
   return [...devices.values()];
 }
-async function connectExpo(metro, device, discoveryMs = 600, signal) {
+async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
   const { ws, devices, pending, send, announced } = await openBroadcast(
     metro,
     discoveryMs,
@@ -240,7 +250,13 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   );
   let info;
   try {
-    info = pickOne([...devices.values()], device, deviceLabel);
+    const all = [...devices.values()];
+    const candidates = pin ? all.filter((d) => d.name === pin.name && d.platform === pin.platform) : all;
+    if (pin && !candidates.length)
+      throw new Error(
+        `${describePin(pin)} is not connected; connected: ${all.map(deviceLabel).join("; ") || "none"}`
+      );
+    info = pickOne(candidates, device, deviceLabel);
   } catch (error) {
     ws.close();
     throw error;
@@ -255,6 +271,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   return {
     transport: "expo",
     device: info,
+    pin: { name: info.name, platform: info.platform },
     call(tool, args, timeoutMs) {
       if (superseded)
         return Promise.resolve({
@@ -278,17 +295,219 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   };
 }
 
+// src/client/session/state.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+function projectRoot(from = process.cwd()) {
+  for (let dir = (0, import_node_path.resolve)(from); ; dir = (0, import_node_path.dirname)(dir)) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "package.json"))) return dir;
+    if ((0, import_node_path.dirname)(dir) === dir) return (0, import_node_path.resolve)(from);
+  }
+}
+var uid = () => process.getuid?.() ?? (0, import_node_os.userInfo)().username;
+function privateDir(dir) {
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
+  const stat = (0, import_node_fs.lstatSync)(dir);
+  if (!stat.isDirectory())
+    throw new Error(`${dir} is not a directory; remove it and retry`);
+  if (process.getuid && stat.uid !== process.getuid())
+    throw new Error(`${dir} belongs to another user; refusing to use it`);
+  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
+    (0, import_node_fs.chmodSync)(dir, 448);
+  return dir;
+}
+function stateDir() {
+  return privateDir(
+    process.env.AGENT_BRIDGE_STATE_DIR ?? (process.env.XDG_RUNTIME_DIR ? (0, import_node_path.join)(process.env.XDG_RUNTIME_DIR, "agent-bridge") : (0, import_node_path.join)((0, import_node_os.tmpdir)(), `agent-bridge-${uid()}`))
+  );
+}
+var shortHash = (text) => (0, import_node_crypto.createHash)("sha256").update(text).digest("hex").slice(0, 16);
+function socketPath(name, dir) {
+  if (process.platform === "win32")
+    return `\\\\.\\pipe\\agent-bridge-${shortHash(dir)}-${name}`;
+  const path = (0, import_node_path.join)(dir, `${name}.sock`);
+  if (Buffer.byteLength(path) <= 100) return path;
+  const short = privateDir(`/tmp/agent-bridge-${uid()}`);
+  return (0, import_node_path.join)(short, `${shortHash(path)}.sock`);
+}
+var sessionFiles = (name, dir = stateDir()) => ({
+  state: (0, import_node_path.join)(dir, `${name}.json`),
+  error: (0, import_node_path.join)(dir, `${name}.error`),
+  log: (0, import_node_path.join)(dir, `${name}.log`),
+  socket: socketPath(name, dir)
+});
+function checkName(name) {
+  if (!/^[\w.-]{1,40}$/.test(name))
+    throw new Error(
+      `Session name "${name}" must be 1-40 letters, digits, ".", "_" or "-"`
+    );
+  return name;
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function removeSessionFiles(name, dir = stateDir()) {
+  const files = sessionFiles(name, dir);
+  (0, import_node_fs.rmSync)(files.state, { force: true });
+  if (process.platform !== "win32") (0, import_node_fs.rmSync)(files.socket, { force: true });
+}
+function readState(file) {
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function listSessions(dir = stateDir()) {
+  const live = [];
+  for (const entry of (0, import_node_fs.readdirSync)(dir)) {
+    if (!entry.endsWith(".json")) continue;
+    const state = readState((0, import_node_path.join)(dir, entry));
+    if (!state) continue;
+    if (isAlive(state.pid)) live.push(state);
+    else removeSessionFiles(state.name, dir);
+  }
+  return live.sort((a, b) => a.startedAt - b.startedAt);
+}
+function readSession(name, dir = stateDir()) {
+  return listSessions(dir).find((s) => s.name === name) ?? null;
+}
+function pickSession(filter) {
+  if (filter.name) {
+    const named = readSession(checkName(filter.name));
+    if (!named) throw new Error(`No session named "${filter.name}" is running`);
+    return named;
+  }
+  const device = filter.device?.toLowerCase();
+  const explicit = !!(filter.metro || device || filter.transport && filter.transport !== "auto");
+  const project = projectRoot();
+  const matching = listSessions().filter(
+    (s) => (explicit || s.project === project) && (!filter.metro || s.metro === filter.metro) && (!device || s.device.name.toLowerCase().includes(device) || s.device.deviceId.toLowerCase().includes(device)) && (!filter.transport || filter.transport === "auto" || filter.transport === s.transport)
+  );
+  if (matching.length > 1)
+    throw new Error(
+      `Several sessions match (${matching.map((s) => `${s.name}: ${s.device.name} on ${s.metro}`).join("; ")}); pick one by name (--session, or --name for session stop/status), or narrow with --metro/--device`
+    );
+  return matching[0] ?? null;
+}
+
+// src/client/metro-hint.ts
+var range = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => from + i);
+var probe = {
+  ports: [...range(8081, 8090), ...range(8100, 8199)],
+  eachMs: 300,
+  totalMs: 1e3
+};
+var hostOf = (metro) => {
+  const colon = metro.lastIndexOf(":");
+  return colon > 0 && !metro.endsWith("]") ? metro.slice(0, colon) : metro;
+};
+async function answers(metro, signal) {
+  try {
+    const res = await fetch(`http://${metro}/status`, { signal });
+    return (await res.text()).includes("packager-status:running");
+  } catch {
+    return false;
+  }
+}
+async function appsOn(metro, signal) {
+  try {
+    const res = await fetch(`http://${metro}/json/list`, { signal });
+    const targets = await res.json();
+    const names = targets.map(
+      (t) => `${t.title ?? "?"}${t.deviceName ? ` [${t.deviceName}]` : ""}`
+    );
+    return [...new Set(names)];
+  } catch {
+    return [];
+  }
+}
+async function findMetros(metro) {
+  const host = hostOf(metro);
+  const candidates = new Set(probe.ports.map((port) => `${host}:${port}`));
+  try {
+    for (const s of listSessions()) candidates.add(s.metro);
+  } catch {
+  }
+  candidates.delete(metro);
+  const deadline = AbortSignal.timeout(probe.totalMs);
+  const within2 = () => AbortSignal.any([deadline, AbortSignal.timeout(probe.eachMs)]);
+  const running = (await Promise.all(
+    [...candidates].map(async (m) => await answers(m, within2()) ? m : null)
+  )).filter((m) => m !== null);
+  return Promise.all(
+    running.map(async (m) => ({ metro: m, apps: await appsOn(m, within2()) }))
+  );
+}
+var label = (found) => `${found.metro} (${found.apps.length ? `${found.apps.length === 1 ? "app" : "apps"}: ${found.apps.join(", ")}` : "no app connected"})`;
+var howToSet = (metro) => `Pass --metro ${metro} or set AGENT_BRIDGE_METRO=${metro}.`;
+function elsewhere(found) {
+  const [only] = found;
+  if (found.length === 1 && only)
+    return `Metro is running on ${label(only)}. ${howToSet(only.metro)}`;
+  return `Metro is running on ${found.map(label).join("; ")}. ${howToSet("<host:port>")}`;
+}
+var errorText = (error) => {
+  if (!(error instanceof Error)) return String(error);
+  const code = error.code ?? "";
+  return `${error.message} ${code} ${error.cause ? errorText(error.cause) : ""}`;
+};
+var isRefused = (error) => /ECONNREFUSED|ConnectionRefused/.test(errorText(error));
+var NO_APP = /No app is connected to Metro|No app matches/;
+async function refusedMessage(metro) {
+  const found = await findMetros(metro);
+  if (found.length)
+    return `Nothing is listening on ${metro}. ${elsewhere(found)}`;
+  const host = hostOf(metro);
+  return `Nothing is listening on ${metro}, and no Metro answered on ${host} ports 8081-8090 or 8100-8199. Start Metro, or if it runs elsewhere, pass --metro <host:port> or set AGENT_BRIDGE_METRO=<host:port>.`;
+}
+async function noAppHint(metro, device) {
+  const causes = `Likely: the app isn't open or hasn't reloaded since the bridge was mounted, it uses another Metro${device ? `, or --device "${device}" doesn't match` : ""}.`;
+  const withApps = (await findMetros(metro)).filter((f) => f.apps.length);
+  return withApps.length ? `${causes} ${elsewhere(withApps)}` : causes;
+}
+async function refused(metro) {
+  try {
+    await fetch(`http://${metro}/status`, {
+      signal: AbortSignal.timeout(probe.eachMs)
+    });
+    return false;
+  } catch (error) {
+    return isRefused(error);
+  }
+}
+async function explainConnectError(error, metro, device) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (NO_APP.test(message))
+    return new Error(`${message}
+${await noAppHint(metro, device)}`, {
+      cause: error
+    });
+  if (await refused(metro))
+    return new Error(await refusedMessage(metro), { cause: error });
+  return error;
+}
+
 // src/client/cdp.ts
 var import_ws2 = __toESM(require("ws"), 1);
 var CannotEvaluate = class extends Error {
 };
 var targetLabel = (t) => `${t.title}${t.deviceName ? ` [${t.deviceName}]` : ""}`;
-async function connectCdp(metro, device, signal) {
-  const target = pickOne(
-    await listCdpTargets(metro, signal),
-    device,
-    targetLabel
-  );
+async function connectCdp(metro, device, signal, pin) {
+  const targets = await listCdpTargets(metro, signal);
+  const candidates = pin?.target ? targets.filter((t) => targetLabel(t) === pin.target) : targets;
+  if (pin && !candidates.length)
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targets.map(targetLabel).join("; ") || "none"}`
+    );
+  const target = pickOne(candidates, device, targetLabel);
   const hostUri = await expoHostUri(metro, signal);
   const port = metro.split(":")[1] ?? "8081";
   const origin = hostUri ? `http://${hostUri}` : `http://localhost:${port}`;
@@ -366,27 +585,34 @@ async function connectCdp(metro, device, signal) {
     );
   }
   signal?.removeEventListener("abort", dropOnAbort);
+  if (pin && (info.name !== pin.name || info.platform !== pin.platform)) {
+    ws.terminate();
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targetLabel(target)} runs ${info.name} (${info.platform})`
+    );
+  }
   return {
     transport: "cdp",
+    pin: {
+      name: info.name,
+      platform: info.platform,
+      target: targetLabel(target)
+    },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    async call(tool, args, timeoutMs) {
+    call(tool, args, timeoutMs) {
       const call = { id: newCallId(), tool, args };
       const reply = pending.wait(call.id, tool, timeoutMs);
-      reply.catch(() => {
-      });
-      try {
-        await evaluate(
-          `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
-        );
-      } catch (error) {
-        pending.settle({
+      evaluate(
+        `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
+      ).catch(
+        (error) => pending.settle({
           id: call.id,
           from: info.deviceId,
           ok: false,
           error: String(error),
           ms: 0
-        });
-      }
+        })
+      );
       return reply;
     },
     close: () => ws.close()
@@ -429,7 +655,7 @@ async function openConnection(options = {}) {
     try {
       return await phase(
         options,
-        (signal) => connectExpo(metro, options.device, void 0, signal)
+        (signal) => connectExpo(metro, options.device, void 0, signal, options.pin)
       );
     } catch (error) {
       if (want === "expo" || options.signal?.aborted) throw error;
@@ -439,7 +665,7 @@ async function openConnection(options = {}) {
   try {
     return await phase(
       options,
-      (signal) => connectCdp(metro, options.device, signal)
+      (signal) => connectCdp(metro, options.device, signal, options.pin)
     );
   } catch (error) {
     const expoNote = expoError ? ` (Expo socket: ${String(expoError)})` : "";
@@ -503,7 +729,7 @@ async function runFlow(bridge, flow, options = {}) {
     }
   };
   const call = async (tool, ...args) => (await timed(tool, ...args)).value;
-  const step = async (label, tool, ...given) => {
+  const step = async (label2, tool, ...given) => {
     const args = given.length === 1 && Array.isArray(given[0]) ? given[0] : given;
     const { value, ms, logs, notice } = await bridge.timed(tool, ...args).catch((error) => {
       report(failedLogs(error), failedNotice(error));
@@ -511,7 +737,7 @@ async function runFlow(bridge, flow, options = {}) {
     });
     total += ms;
     print(
-      `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+      `${String(++n).padStart(2, "0")} ${label2.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
     );
     report(logs, notice);
     return value;
@@ -563,109 +789,6 @@ var import_node_readline = require("readline");
 var encodeLine = (message) => `${JSON.stringify(message).replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`)}
 `;
 
-// src/client/session/state.ts
-var import_node_crypto = require("crypto");
-var import_node_fs = require("fs");
-var import_node_os = require("os");
-var import_node_path = require("path");
-function projectRoot(from = process.cwd()) {
-  for (let dir = (0, import_node_path.resolve)(from); ; dir = (0, import_node_path.dirname)(dir)) {
-    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "package.json"))) return dir;
-    if ((0, import_node_path.dirname)(dir) === dir) return (0, import_node_path.resolve)(from);
-  }
-}
-var uid = () => process.getuid?.() ?? (0, import_node_os.userInfo)().username;
-function privateDir(dir) {
-  (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
-  const stat = (0, import_node_fs.lstatSync)(dir);
-  if (!stat.isDirectory())
-    throw new Error(`${dir} is not a directory; remove it and retry`);
-  if (process.getuid && stat.uid !== process.getuid())
-    throw new Error(`${dir} belongs to another user; refusing to use it`);
-  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
-    (0, import_node_fs.chmodSync)(dir, 448);
-  return dir;
-}
-function stateDir() {
-  return privateDir(
-    process.env.AGENT_BRIDGE_STATE_DIR ?? (process.env.XDG_RUNTIME_DIR ? (0, import_node_path.join)(process.env.XDG_RUNTIME_DIR, "agent-bridge") : (0, import_node_path.join)((0, import_node_os.tmpdir)(), `agent-bridge-${uid()}`))
-  );
-}
-var shortHash = (text) => (0, import_node_crypto.createHash)("sha256").update(text).digest("hex").slice(0, 16);
-function socketPath(name, dir) {
-  if (process.platform === "win32")
-    return `\\\\.\\pipe\\agent-bridge-${shortHash(dir)}-${name}`;
-  const path = (0, import_node_path.join)(dir, `${name}.sock`);
-  if (Buffer.byteLength(path) <= 100) return path;
-  const short = privateDir(`/tmp/agent-bridge-${uid()}`);
-  return (0, import_node_path.join)(short, `${shortHash(path)}.sock`);
-}
-var sessionFiles = (name, dir = stateDir()) => ({
-  state: (0, import_node_path.join)(dir, `${name}.json`),
-  error: (0, import_node_path.join)(dir, `${name}.error`),
-  log: (0, import_node_path.join)(dir, `${name}.log`),
-  socket: socketPath(name, dir)
-});
-function checkName(name) {
-  if (!/^[\w.-]{1,40}$/.test(name))
-    throw new Error(
-      `Session name "${name}" must be 1-40 letters, digits, ".", "_" or "-"`
-    );
-  return name;
-}
-function isAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error.code === "EPERM";
-  }
-}
-function removeSessionFiles(name, dir = stateDir()) {
-  const files = sessionFiles(name, dir);
-  (0, import_node_fs.rmSync)(files.state, { force: true });
-  if (process.platform !== "win32") (0, import_node_fs.rmSync)(files.socket, { force: true });
-}
-function readState(file) {
-  try {
-    return JSON.parse((0, import_node_fs.readFileSync)(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function listSessions(dir = stateDir()) {
-  const live = [];
-  for (const entry of (0, import_node_fs.readdirSync)(dir)) {
-    if (!entry.endsWith(".json")) continue;
-    const state = readState((0, import_node_path.join)(dir, entry));
-    if (!state) continue;
-    if (isAlive(state.pid)) live.push(state);
-    else removeSessionFiles(state.name, dir);
-  }
-  return live.sort((a, b) => a.startedAt - b.startedAt);
-}
-function readSession(name, dir = stateDir()) {
-  return listSessions(dir).find((s) => s.name === name) ?? null;
-}
-function pickSession(filter) {
-  if (filter.name) {
-    const named = readSession(checkName(filter.name));
-    if (!named) throw new Error(`No session named "${filter.name}" is running`);
-    return named;
-  }
-  const device = filter.device?.toLowerCase();
-  const explicit = !!(filter.metro || device || filter.transport && filter.transport !== "auto");
-  const project = projectRoot();
-  const matching = listSessions().filter(
-    (s) => (explicit || s.project === project) && (!filter.metro || s.metro === filter.metro) && (!device || s.device.name.toLowerCase().includes(device) || s.device.deviceId.toLowerCase().includes(device)) && (!filter.transport || filter.transport === "auto" || filter.transport === s.transport)
-  );
-  if (matching.length > 1)
-    throw new Error(
-      `Several sessions match (${matching.map((s) => `${s.name}: ${s.device.name} on ${s.metro}`).join("; ")}); pick one by name (--session, or --name for session stop/status), or narrow with --metro/--device`
-    );
-  return matching[0] ?? null;
-}
-
 // src/client/session/client.ts
 function openSessionLink(state) {
   return new Promise((resolve2, reject) => {
@@ -787,7 +910,9 @@ Warning: ${notice}` : ""}`);
 };
 async function connect(options = {}) {
   const timeoutMs = options.timeoutMs ?? 1e4;
-  const conn = await openConnection(options);
+  const conn = await openConnection(options).catch(async (error) => {
+    throw await explainConnectError(error, metroHost(options.metro), options.device);
+  });
   const timed = async (tool, ...args) => {
     const t0 = performance.now();
     const result = await conn.call(tool, args, timeoutMs);

package/dist/client/index.js

@@ -5,7 +5,7 @@ import {
   listDevices,
   listSessions,
   runFlow
-} from "../chunk-AJD3XTNT.js";
+} from "../chunk-3QIG7A5W.js";
 export {
   AgentBridgeCallError,
   connect,