@avasapp/agent-bridge 0.5.0 → 0.6.0

package/dist/client/index.cjs

@@ -35,10 +35,26 @@ __export(client_exports, {
   connectSession: () => connectSession,
   listDevices: () => listDevices,
   listSessions: () => listSessions,
-  runFlow: () => runFlow
+  runFlow: () => runFlow,
+  runFlows: () => runFlows
 });
 module.exports = __toCommonJS(client_exports);
 
+// src/client/call-timeout.ts
+var WAITERS = {
+  "screen.waitFor": 2e3,
+  // The page helper adds 5 s to timeoutMs before it gives up.
+  "webview.waitFor": 7e3
+};
+var MAX_MS = 10 * 6e4;
+function callTimeout(base, tool, args) {
+  const margin = WAITERS[tool];
+  const t = args[1]?.timeoutMs;
+  if (margin === void 0 || typeof t !== "number" || !(t > 0) || !Number.isFinite(t))
+    return base;
+  return Math.max(base, Math.min(t + margin, MAX_MS));
+}
+
 // src/client/discover.ts
 var within = (ms, signal) => signal ? AbortSignal.any([AbortSignal.timeout(ms), signal]) : AbortSignal.timeout(ms);
 var DEFAULT_METRO = "localhost:8081";
@@ -272,7 +288,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
     transport: "expo",
     device: info,
     pin: { name: info.name, platform: info.platform },
-    call(tool, args, timeoutMs) {
+    call(tool, args, timeoutMs, extra) {
       if (superseded)
         return Promise.resolve({
           id: "",
@@ -285,7 +301,8 @@ async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
         id: newCallId(),
         tool,
         args,
-        to: info.deviceId
+        to: info.deviceId,
+        ...extra
       };
       const reply = pending.wait(call.id, tool, timeoutMs);
       send("call", call);
@@ -306,6 +323,17 @@ function projectRoot(from = process.cwd()) {
     if ((0, import_node_path.dirname)(dir) === dir) return (0, import_node_path.resolve)(from);
   }
 }
+var isPackage = (dir) => (0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "package.json"));
+function inProject(session, project) {
+  if (!session) return false;
+  if (session === project) return true;
+  if (!session.startsWith(project + import_node_path.sep) || !isPackage(project)) return false;
+  for (let dir = session; dir !== project; dir = (0, import_node_path.dirname)(dir)) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, ".git"))) return false;
+    if (dir !== session && isPackage(dir)) return false;
+  }
+  return true;
+}
 var uid = () => process.getuid?.() ?? (0, import_node_os.userInfo)().username;
 function privateDir(dir) {
   (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
@@ -389,8 +417,10 @@ function pickSession(filter) {
   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)
+    (s) => !filter.skip?.(s) && (explicit || inProject(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 (!explicit && matching.length > 1 && matching.every((s) => s.project !== project))
+    return null;
   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`
@@ -599,8 +629,8 @@ async function connectCdp(metro, device, signal, pin) {
       target: targetLabel(target)
     },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    call(tool, args, timeoutMs) {
-      const call = { id: newCallId(), tool, args };
+    call(tool, args, timeoutMs, extra) {
+      const call = { id: newCallId(), tool, args, ...extra };
       const reply = pending.wait(call.id, tool, timeoutMs);
       evaluate(
         `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
@@ -683,6 +713,40 @@ function logLine(entry) {
 }
 
 // src/client/flow.ts
+function deepMatches(actual, expected) {
+  if (expected instanceof RegExp) return typeof actual === "string" && expected.test(actual);
+  if (Array.isArray(expected))
+    return Array.isArray(actual) && actual.length === expected.length && expected.every((e, i) => deepMatches(actual[i], e));
+  if (expected && typeof expected === "object") {
+    const proto = Object.getPrototypeOf(expected);
+    if (proto !== Object.prototype && proto !== null)
+      throw new Error(
+        `A match can hold plain objects, arrays, values and RegExps, not a ${expected.constructor?.name ?? "class instance"}`
+      );
+    return !!actual && typeof actual === "object" && Object.entries(expected).every(
+      ([k, v]) => deepMatches(actual[k], v)
+    );
+  }
+  return Object.is(actual, expected);
+}
+var MAX_SCREEN_LINES = 40;
+function compactScreen(snapshot) {
+  const elements = snapshot?.elements;
+  if (!Array.isArray(elements)) return [];
+  const lines = elements.slice(0, MAX_SCREEN_LINES).map((raw) => {
+    const e = raw;
+    const parts = [String(e.kind ?? "element")];
+    if (e.testID) parts.push(`#${String(e.testID)}`);
+    for (const key of ["text", "label", "placeholder", "value"])
+      if (typeof e[key] === "string" && e[key]) parts.push(JSON.stringify(e[key]));
+    if (e.disabled) parts.push("disabled");
+    if (e.checked) parts.push(`checked=${String(e.checked)}`);
+    return parts.join(" ");
+  });
+  if (elements.length > MAX_SCREEN_LINES)
+    lines.push(`... ${elements.length - MAX_SCREEN_LINES} more`);
+  return lines;
+}
 function flowScenarios(flow) {
   const declared = [
     ...flow.scenario === void 0 ? [] : [flow.scenario],
@@ -710,6 +774,10 @@ async function runFlow(bridge, flow, options = {}) {
   let errors = 0;
   const t0 = performance.now();
   const notices = [];
+  let lost = false;
+  const noteOutcome = (error) => {
+    lost = error !== void 0 && !(error instanceof AgentBridgeCallError);
+  };
   const report = (logs, notice) => {
     errors += logs.length;
     for (const e of logs) print(`   ${logLine(e)}`);
@@ -721,28 +789,82 @@ async function runFlow(bridge, flow, options = {}) {
   const timed = async (tool, ...args) => {
     try {
       const result = await bridge.timed(tool, ...args);
+      noteOutcome();
       report(result.logs, result.notice);
       return result;
     } catch (error) {
+      noteOutcome(error);
       report(failedLogs(error), failedNotice(error));
       throw error;
     }
   };
   const call = async (tool, ...args) => (await timed(tool, ...args)).value;
-  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));
-      throw error;
-    });
+  const record = (label2, ms) => {
     total += ms;
     print(
       `${String(++n).padStart(2, "0")} ${label2.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
     );
-    report(logs, notice);
-    return value;
+  };
+  const step = async (label2, tool, ...given) => {
+    const args = given.length === 1 && Array.isArray(given[0]) ? given[0] : given;
+    const result = await timed(tool, ...args);
+    record(label2, result.ms);
+    return result.value;
+  };
+  const message = (error) => error instanceof Error ? error.message : String(error);
+  const expectApi = {
+    text: async (target, o) => {
+      await step(`expect text ${JSON.stringify(target)}`, "screen.waitFor", target, o ?? {}).catch(
+        (error) => {
+          throw new Error(`expected ${JSON.stringify(target)} on screen: ${message(error)}`);
+        }
+      );
+    },
+    gone: async (target, o) => {
+      await step(`expect gone ${JSON.stringify(target)}`, "screen.waitFor", target, {
+        ...o,
+        gone: true
+      }).catch((error) => {
+        throw new Error(`expected ${JSON.stringify(target)} to be off screen: ${message(error)}`);
+      });
+    },
+    route: async (pathname, o) => {
+      const label2 = `expect route ${pathname}`;
+      const t02 = performance.now();
+      const deadline = t02 + (o?.timeoutMs ?? 2e3);
+      for (; ; ) {
+        const route = await call("router.current").catch((error) => {
+          record(label2, performance.now() - t02);
+          throw error;
+        });
+        if (route?.pathname === pathname) return record(label2, performance.now() - t02);
+        if (performance.now() >= deadline) {
+          record(label2, performance.now() - t02);
+          throw new Error(`expected route ${pathname}, got ${route?.pathname ?? JSON.stringify(route)}`);
+        }
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    result: async (tool, args, match) => {
+      const value = await step(`expect ${tool}`, tool, args);
+      if (!deepMatches(value, match))
+        throw new Error(
+          `expected ${tool} to match ${JSON.stringify(match)}, got ${JSON.stringify(value)}`
+        );
+    }
+  };
+  const failureState = async () => {
+    const has = (name) => bridge.tools().some((t) => t.name === name);
+    const state = {};
+    if (has("screen.snapshot"))
+      state.screen = await call("screen.snapshot").then(compactScreen).catch(() => void 0);
+    if (has("router.current") && !lost)
+      state.route = await call("router.current").catch(() => void 0);
+    return state;
   };
   const restoreErrors = [];
+  let flowErrors = 0;
+  let unreachable = false;
   const applied = {};
   if (needs.length && !bridge.tools().some((t) => t.name === "scenario.apply"))
     throw new Error(
@@ -757,10 +879,22 @@ async function runFlow(bridge, flow, options = {}) {
       bridge: { ...bridge, timed, call },
       call,
       step,
-      scenarios: applied
+      scenarios: applied,
+      expect: expectApi
     });
+  } catch (error) {
+    const state = lost ? {} : await failureState();
+    if (state.route !== void 0) print(`   route: ${JSON.stringify(state.route)}`);
+    if (state.screen?.length) {
+      print("   on screen:");
+      for (const line of state.screen) print(`     ${line}`);
+    }
+    options.onFailure?.(state);
+    throw error;
   } finally {
-    if (needs.length) {
+    flowErrors = errors;
+    unreachable = lost;
+    if (!lost && !options.keep && (needs.length || bridge.tools().some((t) => t.name === "bridge.restore"))) {
       try {
         const result = await step("restore", "bridge.restore");
         for (const [name, value] of Object.entries(result ?? {})) {
@@ -768,17 +902,70 @@ async function runFlow(bridge, flow, options = {}) {
           if (error !== void 0) restoreErrors.push(`${name}: ${String(error)}`);
         }
       } catch (error) {
+        unreachable = lost;
         restoreErrors.push(
           `bridge.restore: ${error instanceof Error ? error.message : String(error)}`
         );
       }
       for (const e of restoreErrors) print(`   ! restore failed: ${e}`);
     }
+    options.onFinish?.({ steps: n, errors: flowErrors, restoreErrors, notices, unreachable });
   }
   print(
-    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}${notices.length ? ", the app reloaded" : ""}`
+    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${flowErrors ? `, ${flowErrors} error${flowErrors === 1 ? "" : "s"}` : ""}${notices.length ? ", the app reloaded" : ""}`
   );
-  return { steps: n, errors, restoreErrors, notices };
+  return { steps: n, errors: flowErrors, restoreErrors, notices, unreachable };
+}
+async function runFlows(bridge, entries, options = {}) {
+  const print = options.print ?? console.log;
+  const printError = options.single ? options.printError ?? console.error : print;
+  const runs = [];
+  let unreachable = false;
+  for (const entry of entries) {
+    const base = { file: entry.file, name: entry.name, restoreErrors: [], notices: [] };
+    const skip = unreachable ? "skipped: the app stopped answering in an earlier flow" : options.bail && runs.some((r) => r.status === "failed") ? "skipped: an earlier flow failed (--bail)" : void 0;
+    if (skip) {
+      runs.push({ ...base, status: "skipped", ms: 0, steps: 0, errors: 0, error: skip });
+      continue;
+    }
+    if (!options.single) print(`
+${entry.name}`);
+    const t0 = performance.now();
+    let state;
+    let done = { steps: 0, errors: 0, restoreErrors: [], notices: [], unreachable: false };
+    const reasons = [];
+    try {
+      await runFlow(bridge, entry.module, {
+        ...options,
+        onFailure: (s) => {
+          state = s;
+        },
+        onFinish: (r) => {
+          done = r;
+        }
+      });
+    } catch (error) {
+      const why = error instanceof Error ? error.message : String(error);
+      printError(`   FAILED: ${why}`);
+      reasons.push(why);
+    }
+    if (done.restoreErrors.length) reasons.push(`restore failed: ${done.restoreErrors.join("; ")}`);
+    if (options.strict && done.errors)
+      reasons.push(`the app logged ${done.errors} error${done.errors === 1 ? "" : "s"}`);
+    if (done.notices.length)
+      print("   ! the app reloaded: changes made before the reload could not be undone");
+    const { unreachable: gone, ...result } = done;
+    runs.push({
+      ...base,
+      ...result,
+      status: reasons.length ? "failed" : "passed",
+      ms: performance.now() - t0,
+      ...reasons.length && { error: reasons.join("; ") },
+      ...state && { state }
+    });
+    if (gone) unreachable = true;
+  }
+  return runs;
 }
 
 // src/client/session/client.ts
@@ -790,19 +977,26 @@ var encodeLine = (message) => `${JSON.stringify(message).replace(/[\u2028\u2029]
 `;
 
 // src/client/session/client.ts
+var SessionLinkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SessionLinkError";
+  }
+};
 function openSessionLink(state) {
   return new Promise((resolve2, reject) => {
     const socket = (0, import_node_net.createConnection)(state.socket);
     const waiting = /* @__PURE__ */ new Map();
     let seq = 0;
     let open = false;
-    const gone = `Session "${state.name}" closed the connection`;
+    let lastError = "";
+    const gone = () => `Session "${state.name}" closed the connection${lastError && `: ${lastError}`}`;
     socket.once("connect", () => {
       open = true;
       resolve2({
         request: (req) => new Promise((done, fail) => {
           if (socket.destroyed || socket.writableEnded) {
-            fail(new Error(gone));
+            fail(new SessionLinkError(gone()));
             return;
           }
           const id = ++seq;
@@ -813,18 +1007,22 @@ function openSessionLink(state) {
       });
     });
     socket.on("error", (error) => {
+      lastError = error.message;
       if (!open)
         reject(
-          new Error(
+          new SessionLinkError(
             `Session "${state.name}" isn't answering on ${state.socket}: ${error.message}`
           )
         );
     });
     socket.on("close", () => {
-      for (const [id, done] of waiting) done({ id, error: gone });
+      for (const [id, done] of waiting) done({ id, error: gone(), linkLost: true });
       waiting.clear();
     });
-    (0, import_node_readline.createInterface)({ input: socket }).on("line", (line) => {
+    const lines = (0, import_node_readline.createInterface)({ input: socket });
+    lines.on("error", () => {
+    });
+    lines.on("line", (line) => {
       const res = JSON.parse(line);
       waiting.get(res.id)?.(res);
       waiting.delete(res.id);
@@ -838,10 +1036,16 @@ async function connectSession(options = {}) {
     device: options.device,
     transport: options.transport
   });
-  if (!state)
+  if (!state) {
+    const where = [
+      explicitMetro(options.metro) && `on Metro ${explicitMetro(options.metro)}`,
+      options.device && `on a device matching "${options.device}"`,
+      options.transport && options.transport !== "auto" && `using ${options.transport}`
+    ].filter(Boolean);
     throw new Error(
-      "No single session matches. Start one with `agent-bridge session start`, or name it."
+      `No single session matches (looked for sessions ${where.length ? where.join(", ") : `started in ${projectRoot()}, or in an app folder under it`}). Start one with \`agent-bridge session start\`, or name it.`
     );
+  }
   const link = await openSessionLink(state);
   const info = await link.request({ op: "info" });
   if (info.error || !info.device || !info.transport) {
@@ -858,6 +1062,7 @@ async function connectSession(options = {}) {
     });
     if (res.error || !res.result) {
       const why = res.error ?? "No result";
+      if (res.linkLost) throw new SessionLinkError(why);
       throw res.notice ? new AgentBridgeCallError(tool, why, [], res.notice) : new Error(why);
     }
     const result = res.result;
@@ -915,7 +1120,7 @@ async function connect(options = {}) {
   });
   const timed = async (tool, ...args) => {
     const t0 = performance.now();
-    const result = await conn.call(tool, args, timeoutMs);
+    const result = await conn.call(tool, args, callTimeout(timeoutMs, tool, args));
     const ms = performance.now() - t0;
     const logs = result.logs ?? [];
     if (!result.ok) throw new AgentBridgeCallError(tool, result.error, logs);
@@ -956,5 +1161,6 @@ async function listDevices(options = {}) {
   connectSession,
   listDevices,
   listSessions,
-  runFlow
+  runFlow,
+  runFlows
 });

package/dist/client/index.d.ts

@@ -44,9 +44,29 @@ type FlowApi = {
     step: (label: string, tool: string, ...args: unknown[]) => Promise<unknown>;
     /** What each declared scenario's apply returned, by name. */
     scenarios: Record<string, unknown>;
+    expect: FlowExpect;
+};
+/** Checks that throw a readable message; each runs as a timed step. */
+type FlowExpect = {
+    /** Text, label or testID is on screen (waits up to `timeoutMs`, default 5000). */
+    text: (target: string, options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+    /** The target is not on screen (waits for it to leave). */
+    gone: (target: string, options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+    /** `router.current` has this pathname (waits up to `timeoutMs`, default 2000). */
+    route: (pathname: string, options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+    /** A tool's result contains `match`: objects by the keys given, arrays and values exactly. */
+    result: (tool: string, args: unknown[], match: unknown) => Promise<void>;
 };
 /** A flow file: `export default async ({ step, call }) => {}`, plus what it needs. */
 type FlowModule = {
+    /** Shown in the run summary and matched by `--grep`; default: the file name. */
+    name?: string;
     default: (api: FlowApi) => Promise<void>;
     /** Applied before the flow and undone after it, even when it fails. */
     scenario?: FlowScenario;
@@ -60,6 +80,13 @@ type FlowResult = {
     restoreErrors: string[];
     /** "app reloaded; N pending restores lost" warnings seen during the flow. */
     notices: string[];
+    /** The app stopped answering (a timeout or closed connection), so no restore was tried. */
+    unreachable: boolean;
+};
+/** What was on screen when a flow failed. */
+type FailureState = {
+    screen?: string[];
+    route?: unknown;
 };
 type RunFlowOptions = {
     /** Where step lines go. Default: console.log. */
@@ -69,14 +96,50 @@ type RunFlowOptions = {
         name: string;
         options?: unknown;
     }>;
+    /** Leave the app as the flow left it: no closing bridge.restore (for debugging). */
+    keep?: boolean;
+    /** Called with what was on screen when the flow failed. */
+    onFailure?: (state: FailureState) => void;
+    /** Called once the flow and its restore are done, also when it failed. */
+    onFinish?: (result: FlowResult) => void;
 };
 /**
- * Runs a flow module you imported: applies its scenarios, runs it, and when
- * there were any, undoes everything with bridge.restore afterwards, even
+ * Runs a flow module you imported: applies its scenarios, runs it, and
+ * undoes everything with bridge.restore afterwards (unless `keep`), even
  * when it fails. Throws what the flow threw; otherwise returns how it went.
  * It runs only the code you hand it, in this process.
  */
 declare function runFlow(bridge: AgentBridge, flow: FlowModule, options?: RunFlowOptions): Promise<FlowResult>;
+type FlowEntry = {
+    file: string;
+    name: string;
+    module: FlowModule;
+};
+type FlowRun = {
+    file: string;
+    name: string;
+    status: 'passed' | 'failed' | 'skipped';
+    ms: number;
+    steps: number;
+    errors: number;
+    /** Why it failed: what the flow threw, restore failures, or app errors under `strict`. */
+    error?: string;
+    state?: FailureState;
+    restoreErrors: string[];
+    notices: string[];
+};
+type RunFlowsOptions = RunFlowOptions & {
+    /** Stop at the first failure; the rest are reported as skipped. */
+    bail?: boolean;
+    /** Count an error the app logged as a failure. */
+    strict?: boolean;
+    /** One flow, text output: no name header, and the failure goes to `printError`. */
+    single?: boolean;
+    /** Where a failed flow's reason goes when `single`. Default: console.error. */
+    printError?: (line: string) => void;
+};
+/** Runs flows in order on one connection, each followed by a restore (see `keep`), and never throws for a failing flow. */
+declare function runFlows(bridge: AgentBridge, entries: FlowEntry[], options?: RunFlowsOptions): Promise<FlowRun[]>;
 
 /** What a running session writes next to its socket. Readable only by the user. */
 type SessionState = {
@@ -126,7 +189,7 @@ type ConnectOptions = {
     device?: string;
     /** "auto" tries Expo's socket first and falls back to CDP. */
     transport?: 'auto' | TransportName;
-    /** Per-call timeout. Default 10 s. */
+    /** Per-call timeout. Default 10 s; stretched when a call's own `timeoutMs` argument is longer. */
     timeoutMs?: number;
 };
 declare class AgentBridgeCallError extends Error {
@@ -170,4 +233,4 @@ type ListedDevice = {
 /** Apps with the bridge on Expo's socket, plus every React Native page Metro knows. */
 declare function listDevices(options?: Pick<ConnectOptions, 'metro'>): Promise<ListedDevice[]>;
 
-export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type FlowApi, type FlowModule, type FlowResult, type FlowScenario, type ListedDevice, type LogEntry, type RunFlowOptions, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions, runFlow };
+export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type FlowApi, type FlowExpect, type FlowModule, type FlowResult, type FlowRun, type FlowScenario, type ListedDevice, type LogEntry, type RunFlowOptions, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions, runFlow, runFlows };

package/dist/client/index.js

@@ -4,13 +4,15 @@ import {
   connectSession,
   listDevices,
   listSessions,
-  runFlow
-} from "../chunk-3QIG7A5W.js";
+  runFlow,
+  runFlows
+} from "../chunk-Y6QFU5ON.js";
 export {
   AgentBridgeCallError,
   connect,
   connectSession,
   listDevices,
   listSessions,
-  runFlow
+  runFlow,
+  runFlows
 };

package/dist/expo/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Transport } from '../types-BmpykP1P.cjs';
+import { a as Transport } from '../types-qlwdcGjt.cjs';
 
 /**
  * Plain JSON over Expo's dev-tools plugin socket: no string evaluation, emoji