chrome-relay 0.2.5 → 0.3.1

package/dist/cli.js

@@ -154,7 +154,7 @@ async function callTool(name, args) {
 // src/program.ts
 function buildProgram() {
   const program = new Command();
-  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").version(CHROME_RELAY_VERSION).showHelpAfterError().addHelpText(
+  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--group <name>", "target the active tab of a named group window (works at top level too)").enablePositionalOptions().addHelpText(
     "after",
     `
 
@@ -197,7 +197,14 @@ Notes:
     }
   }
   function tabOpt(cmd) {
-    return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v));
+    return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--group <name>", "target the active tab of a named group window (see `chrome-relay group`)");
+  }
+  function baseArgs(opts) {
+    const args = {};
+    if (opts.tab !== void 0) args.tabId = opts.tab;
+    const effectiveGroup = opts.group ?? program.opts().group;
+    if (effectiveGroup) args.groupName = effectiveGroup;
+    return args;
   }
   program.command("tabs").description("List open Chrome windows and tabs.").action(async () => {
     await run("get_windows_and_tabs", {});
@@ -223,7 +230,7 @@ Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate
       process.exit(1);
     }
     const args = { url };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (opts.new) args.newTab = true;
     if (opts.inactive) args.active = false;
     await run("chrome_navigate", args);
@@ -247,7 +254,7 @@ full-tab screenshot when an agent only needs to see one component.
     )
   ).action(async (opts) => {
     const args = {};
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (opts.full) args.fullPage = true;
     if (opts.bbox) args.bbox = opts.bbox;
     if (opts.selector) args.selector = opts.selector;
@@ -276,7 +283,7 @@ full-tab screenshot when an agent only needs to see one component.
     program.command("read").description("Extract page structure and interactive elements.").option("-i, --interactive", "return only interactive elements")
   ).action(async (opts) => {
     const args = {};
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (opts.interactive) args.interactiveOnly = true;
     await run("chrome_read_page", args);
   });
@@ -284,14 +291,14 @@ full-tab screenshot when an agent only needs to see one component.
     program.command("click <selector>").description("Click an element by CSS selector.")
   ).action(async (selector, opts) => {
     const args = { selector };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     await run("chrome_click_element", args);
   });
   tabOpt(
     program.command("fill <selector> <value>").description("Fill an input or textarea.")
   ).action(async (selector, value, opts) => {
     const args = { selector, value };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     await run("chrome_fill_or_select", args);
   });
   tabOpt(
@@ -310,7 +317,7 @@ For typing text into a field, use \`chrome-relay type\` instead.
     )
   ).action(async (keys, opts) => {
     const args = { keys };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     await run("chrome_keyboard", args);
   });
   tabOpt(
@@ -331,7 +338,7 @@ When to pick which:
     )
   ).action(async (text, opts) => {
     const args = { text };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (opts.selector) args.selector = opts.selector;
     await run("chrome_type", args);
   });
@@ -353,7 +360,7 @@ Notes:
     )
   ).action(async (code, opts) => {
     const args = { code };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (typeof opts.timeoutMs === "number") args.timeoutMs = opts.timeoutMs;
     await run("chrome_evaluate", args);
   });
@@ -399,19 +406,172 @@ Notes:
     viewport.command("preset <name>").description("Apply a named device preset (iphone-14, pixel-7, desktop-1440, etc).")
   ).action(async (name, opts) => {
     const args = { action: "preset", name };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     await run("chrome_viewport", args);
   });
   tabOpt(
     viewport.command("clear").description("Drop the viewport override and return the tab to its native size.")
   ).action(async (opts) => {
     const args = { action: "clear" };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     await run("chrome_viewport", args);
   });
   viewport.command("list").description("List available presets.").action(async () => {
     await run("chrome_viewport", { action: "list" });
   });
+  program.command("self-reload").description("Restart the chrome-relay extension's service worker (picks up newly built code).").action(async () => {
+    await run("chrome_self_reload", {});
+  });
+  tabOpt(
+    program.command("ax").description("Extract the accessibility tree \u2014 ~30\xD7 smaller than `read` and more semantic.").option("-i, --interactive-only", "filter to actionable roles (button, link, textbox, ...)").option("--root <role>", "start from the first node matching this role (e.g. 'main')").option("--include-subframes", "walk subframes too (default: top frame only)").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay ax --tab 123
+  chrome-relay ax --tab 123 --interactive-only
+  chrome-relay ax --tab 123 --root main --interactive-only
+
+Notes:
+  Each node carries an "id" \u2014 that's the backendDOMNodeId. Pass it to
+  \`chrome-relay click-ax --node <id>\` to click without a CSS selector.
+`
+    )
+  ).action(async (opts) => {
+    const args = baseArgs(opts);
+    if (opts.interactiveOnly) args.interactiveOnly = true;
+    if (opts.root) args.rootRole = opts.root;
+    if (opts.includeSubframes) args.includeSubframes = true;
+    await run("chrome_ax", args);
+  });
+  tabOpt(
+    program.command("click-ax").description("Click an element by its backendDOMNodeId from a previous `ax` call.").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay click-ax --tab 123 --node 456
+
+Notes:
+  Throws explicitly if the node id is stale (page mutated since you called
+  \`ax\`). Re-run \`ax\` and pass the fresh id.
+`
+    )
+  ).action(async (opts) => {
+    const args = baseArgs(opts);
+    args.node = opts.node;
+    await run("chrome_click_ax", args);
+  });
+  const group = program.command("group").description("Manage named Chrome windows so multiple agents can drive separate windows.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay group create bidsmith-h01 --url https://reddit.com
+  chrome-relay group list
+  chrome-relay --group bidsmith-h01 navigate https://news.ycombinator.com
+  chrome-relay --group bidsmith-h01 screenshot -o evidence.png
+  chrome-relay group close bidsmith-h01
+
+Notes:
+  Hard lifecycle: if you manually close the group's window, the next
+  --group operation fails loudly until you run \`group close\` + \`group create\` again.
+  If you pass both --tab and --group on the same command, --tab wins.
+`
+  );
+  group.command("create <name>").description("Open a new Chrome window and bind it to <name>.").option("--url <url>", "initial URL (default about:blank)").option("--label <label>", "human-readable description shown in popup/list").action(async (name, opts) => {
+    const args = { action: "create", name };
+    if (opts.url) args.url = opts.url;
+    if (opts.label) args.label = opts.label;
+    await run("chrome_group", args);
+  });
+  group.command("list").description("List all known groups + whether their window is still alive.").action(async () => {
+    await run("chrome_group", { action: "list" });
+  });
+  group.command("close <name>").description("Close the group's window (if alive) and remove the binding.").action(async (name) => {
+    await run("chrome_group", { action: "close", name });
+  });
+  const network = program.command("network").description("Capture HTTP request/response metadata. Ring buffer, last 200 per tab.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay network --tab 123                          # last 200 requests
+  chrome-relay network --tab 123 --filter api.example.com  # url substring
+  chrome-relay network --tab 123 --status failed           # only failures
+  chrome-relay network --tab 123 --method POST
+  chrome-relay network --tab 123 --body <requestId>        # lazy body fetch
+  chrome-relay network --tab 123 har > capture.har         # HAR export
+  chrome-relay network --tab 123 --clear
+
+Privacy:
+  Capturing network traffic includes Authorization headers, cookies, and
+  request/response bodies. The capture stays in the extension's memory and
+  is wiped on tab close. Don't run this on a tab whose state you wouldn't
+  share with the agent invoking chrome-relay.
+
+Notes:
+  Bodies are NOT eagerly buffered \u2014 Chrome GCs response bodies ~30s after
+  the request finishes. Use \`--body <id>\` promptly. WebSocket frames and
+  SSE streams are out of scope.
+`
+  );
+  tabOpt(
+    network.command("read", { isDefault: true }).description("List captured network entries.").option("--filter <substr>", "url substring filter").option("--status <bucket>", "ok | redirect | client_error | server_error | failed").option("--method <verb>", "exact method, e.g. POST").option("--limit <n>", "cap response length", (v) => Number(v))
+  ).action(async (opts) => {
+    const args = baseArgs(opts);
+    if (opts.filter) args.filter = opts.filter;
+    if (opts.status) args.status = opts.status;
+    if (opts.method) args.method = opts.method;
+    if (typeof opts.limit === "number") args.limit = opts.limit;
+    await run("chrome_network", args);
+  });
+  tabOpt(
+    network.command("body <requestId>").description("Fetch the response body for one request (lazy; may fail if GC'd).")
+  ).action(async (requestId, opts) => {
+    const args = { ...baseArgs(opts), action: "body", requestId };
+    await run("chrome_network", args);
+  });
+  tabOpt(
+    network.command("har").description("Emit HAR-compatible JSON for the captured entries.").option("--filter <substr>", "url substring filter").option("--status <bucket>", "status bucket filter")
+  ).action(async (opts) => {
+    const args = { ...baseArgs(opts), action: "har" };
+    if (opts.filter) args.filter = opts.filter;
+    if (opts.status) args.status = opts.status;
+    await run("chrome_network", args);
+  });
+  tabOpt(
+    network.command("clear").description("Wipe the network buffer for this tab.")
+  ).action(async (opts) => {
+    const args = { ...baseArgs(opts), action: "clear" };
+    await run("chrome_network", args);
+  });
+  tabOpt(
+    program.command("console").description("Read console.log/warn/error + page exceptions (ring buffer, last 200).").option("--level <levels>", "comma-separated: log,info,warn,error,debug,exception").option("--since <id>", "only return entries with id > since (live-tail-ish)", (v) => Number(v)).option("--limit <n>", "cap response length", (v) => Number(v)).option("--clear", "wipe the buffer (no read)").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay console --tab 123
+  chrome-relay console --tab 123 --level error,exception
+  chrome-relay console --tab 123 --since 50         # entries newer than id 50 (tail-style polling)
+  chrome-relay console --tab 123 --clear
+
+Notes:
+  Ring buffer holds the last 200 entries per tab (or 256 KB, whichever first).
+  Wipes on tab close. First call on a tab subscribes; subsequent calls are
+  instant in-memory reads.
+`
+    )
+  ).action(async (opts) => {
+    const args = {};
+    if (opts.tab !== void 0) args.tabId = opts.tab;
+    if (opts.clear) args.action = "clear";
+    if (opts.level) args.levels = opts.level;
+    if (typeof opts.since === "number") args.since = opts.since;
+    if (typeof opts.limit === "number") args.limit = opts.limit;
+    await run("chrome_console", args);
+  });
   return program;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,7 @@
   "devDependencies": {
     "tsup": "^8.4.0",
     "vitest": "^3.0.0",
-    "@chrome-relay/protocol": "0.2.5"
+    "@chrome-relay/protocol": "0.3.0"
   },
   "scripts": {
     "build": "tsup",