chrome-relay 0.3.3 → 0.5.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { writeFileSync } from "fs";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.3.3" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.0" : "0.0.0-dev";
 
 // src/install/install.ts
 import os from "os";
@@ -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().option("--group <name>", "target the active tab of a named group window (works at top level too)").enablePositionalOptions().addHelpText(
+  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--workspace <name>", "target the active tab in a named workspace window (works at top level too)").option("--group <name>", "target the active tab in a named tab-group (works at top level too)").enablePositionalOptions().addHelpText(
     "after",
     `
 
@@ -197,12 +197,15 @@ Notes:
     }
   }
   function tabOpt(cmd) {
-    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`)");
+    return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--workspace <name>", "target the active tab in a named workspace window (see `chrome-relay workspace`)").option("--group <name>", "target the active tab in a named tab-group (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;
+    const parentOpts = program.opts();
+    const effectiveWorkspace = opts.workspace ?? parentOpts.workspace;
+    const effectiveGroup = opts.group ?? parentOpts.group;
+    if (effectiveWorkspace) args.workspaceName = effectiveWorkspace;
     if (effectiveGroup) args.groupName = effectiveGroup;
     return args;
   }
@@ -468,35 +471,79 @@ Notes:
     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(
+  const workspace = program.command("workspace").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
+  chrome-relay workspace create bidsmith-h01 --url https://reddit.com
+  chrome-relay workspace list
+  chrome-relay --workspace bidsmith-h01 navigate https://news.ycombinator.com
+  chrome-relay --workspace bidsmith-h01 screenshot -o evidence.png
+  chrome-relay workspace 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.
+  Hard lifecycle: if you manually close the workspace's window, the next
+  --workspace operation fails loudly until you run \`workspace close\` +
+  \`workspace create\` again.
+  Precedence on a single command: --tab > --group > --workspace.
 `
   );
-  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) => {
+  workspace.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_workspace", args);
+  });
+  workspace.command("list").description("List all known workspaces + whether their window is still alive.").action(async () => {
+    await run("chrome_workspace", { action: "list" });
+  });
+  workspace.command("close <name>").description("Close the workspace's window (if alive) and remove the binding.").action(async (name) => {
+    await run("chrome_workspace", { action: "close", name });
+  });
+  const group = program.command("group").description("Manage Chrome tab-groups (the colored, collapsible folders inside one window).").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay group create research --tabs 123,456,789 --color cyan
+  chrome-relay group list
+  chrome-relay group add research --tabs 1011
+  chrome-relay group remove --tabs 456
+  chrome-relay --group research navigate https://news.ycombinator.com
+  chrome-relay group close research
+
+Notes:
+  Tab-groups live inside ONE Chrome window. To open in a specific window,
+  pass --workspace W on \`group create\` (we'll route the underlying
+  chrome.tabs.group call there).
+  \`--group X navigate --new\` opens the new tab into the group's window AND
+  drops it inside the group.
+  Auto-pruned when the group's last tab is ungrouped or its window closes.
+  Colors: grey, blue, red, yellow, green, pink, purple, cyan, orange.
+`
+  );
+  group.command("create <name>").description("Group existing tabs into a new tab-group bound to <name>.").requiredOption("--tabs <ids>", "comma-separated tab IDs to group, e.g. 123,456,789").option("--color <color>", "grey | blue | red | yellow | green | pink | purple | cyan | orange").option("--collapsed", "create the group in its collapsed state").action(async (name, opts) => {
+    const args = { action: "create", name };
+    args.tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
+    if (opts.color) args.color = opts.color;
+    if (opts.collapsed) args.collapsed = true;
     await run("chrome_group", args);
   });
-  group.command("list").description("List all known groups + whether their window is still alive.").action(async () => {
+  group.command("list").description("List all known tab-groups + their window/color/tabCount.").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) => {
+  group.command("close <name>").description("Ungroup the tabs in <name> and remove the binding.").action(async (name) => {
     await run("chrome_group", { action: "close", name });
   });
+  group.command("add <name>").description("Add existing tabs to an existing tab-group.").requiredOption("--tabs <ids>", "comma-separated tab IDs to add").action(async (name, opts) => {
+    const tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
+    await run("chrome_group", { action: "add", name, tabIds });
+  });
+  group.command("remove").description("Ungroup specific tabs (they remain open, just outside any tab-group).").requiredOption("--tabs <ids>", "comma-separated tab IDs to ungroup").action(async (opts) => {
+    const tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
+    await run("chrome_group", { action: "remove", tabIds });
+  });
   function netFilterOpts(cmd) {
     return cmd.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));
   }
@@ -597,6 +644,171 @@ Notes:
     if (typeof opts.limit === "number") args.limit = opts.limit;
     await run("chrome_console", args);
   });
+  tabOpt(
+    program.command("hover [selector]").description("Move the pointer over an element or coordinates. Fires :hover styles.").option("--x <px>", "explicit x coordinate (CSS pixels)", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels)", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay hover --tab 123 'button[title="Install runner"]'
+  chrome-relay hover --tab 123 --x 1327 --y 771
+
+Use before screencast to capture hover-driven micro-states (button glow,
+tooltip appearance, etc.) that a bare click would skip past too quickly.
+`
+    )
+  ).action(async (selector, opts) => {
+    const args = {};
+    Object.assign(args, baseArgs(opts));
+    if (selector) args.selector = selector;
+    if (typeof opts.x === "number" && typeof opts.y === "number") {
+      args.x = opts.x;
+      args.y = opts.y;
+    }
+    await run("chrome_hover", args);
+  });
+  const screencast = program.command("screencast").description("Record a tab via CDP (paint-driven). Requires an active tab.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay screencast start --tab 123 --quality 80 --max-width 900
+  # ... drive the interaction (hover, click, etc.) ...
+  chrome-relay screencast stop --tab 123 --out /tmp/recording
+
+  # The --out path becomes a directory of frame_NNNN.jpg files. If ffmpeg
+  # is on PATH and --gif is also passed, an animated GIF is written next to
+  # the frames at /tmp/recording.gif.
+
+Notes:
+  Frames buffer in the extension service worker. A 10-second capture at
+  default settings (jpeg q=60, ~15fps, full viewport) lands ~2-3 MB.
+  Pass --max-width to downscale and lighten the buffer.
+  Each frame is base64 JPEG; the CLI decodes them when --out is given.
+`
+  );
+  tabOpt(
+    screencast.command("start").description("Begin screencast capture on a tab.").option("--format <fmt>", "jpeg | png (default jpeg)").option("--quality <n>", "jpeg quality 0-100 (default 80)", (v) => Number(v)).option("--max-width <px>", "downscale; aspect preserved", (v) => Number(v)).option("--max-height <px>", "downscale; aspect preserved", (v) => Number(v)).option("--every-nth <n>", "throttle: keep 1 in N frames (default 1)", (v) => Number(v))
+  ).action(async (opts) => {
+    const args = { action: "start" };
+    Object.assign(args, baseArgs(opts));
+    if (opts.format) args.format = opts.format;
+    if (typeof opts.quality === "number") args.quality = opts.quality;
+    if (typeof opts.maxWidth === "number") args.maxWidth = opts.maxWidth;
+    if (typeof opts.maxHeight === "number") args.maxHeight = opts.maxHeight;
+    if (typeof opts.everyNth === "number") args.everyNthFrame = opts.everyNth;
+    await run("chrome_screencast", args);
+  });
+  tabOpt(
+    screencast.command("stop").description("Stop the screencast and emit frames (or write to disk).").option("-o, --out <dir>", "write frames as JPEGs into this directory (created if missing)").option("--gif", "after writing frames, ffmpeg them into <dir>.gif").option("--mp4", "after writing frames, ffmpeg them into <dir>.mp4").option("--fps <n>", "assumed framerate when invoking ffmpeg (default 15)", (v) => Number(v)).option("--no-dedupe", "keep raw frames; default collapses consecutive identical frames via SHA-256")
+  ).action(async (opts) => {
+    const args = { action: "stop" };
+    Object.assign(args, baseArgs(opts));
+    try {
+      const result = await callTool("chrome_screencast", args);
+      if (!opts.out) {
+        const { frames, ...summary } = result;
+        process.stdout.write(JSON.stringify({ ...summary, framesOmitted: frames.length, hint: "pass --out <dir> to save" }, null, 2) + "\n");
+        return;
+      }
+      const { mkdirSync, writeFileSync: writeFileSync2, renameSync, unlinkSync } = await import("fs");
+      const path2 = await import("path");
+      const { createHash } = await import("crypto");
+      mkdirSync(opts.out, { recursive: true });
+      result.frames.forEach((f, i) => {
+        const name = `frame_${String(i + 1).padStart(4, "0")}.jpg`;
+        writeFileSync2(path2.join(opts.out, name), Buffer.from(f.data, "base64"));
+      });
+      process.stdout.write(`Wrote ${result.frames.length} frames to ${opts.out}
+`);
+      const dedupeOn = opts.dedupe !== false;
+      if (dedupeOn && result.frames.length > 1) {
+        const hashes = result.frames.map(
+          (f) => createHash("sha256").update(Buffer.from(f.data, "base64")).digest("hex")
+        );
+        const kept = [];
+        let prev = "";
+        hashes.forEach((h, i) => {
+          if (h !== prev) kept.push(i);
+          prev = h;
+        });
+        const dropped = result.frames.length - kept.length;
+        if (dropped > 0) {
+          for (let i = 0; i < result.frames.length; i++) {
+            const src = path2.join(opts.out, `frame_${String(i + 1).padStart(4, "0")}.jpg`);
+            try {
+              unlinkSync(src);
+            } catch {
+            }
+          }
+          kept.forEach((srcIdx, newIdx) => {
+            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            writeFileSync2(tmp, Buffer.from(result.frames[srcIdx].data, "base64"));
+          });
+          kept.forEach((_, newIdx) => {
+            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            const final = path2.join(opts.out, `frame_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            renameSync(tmp, final);
+          });
+          process.stdout.write(`Deduped: dropped ${dropped} identical frames, ${kept.length} remain.
+`);
+        } else {
+          process.stdout.write(`Deduped: no consecutive duplicates found.
+`);
+        }
+      }
+      if (opts.gif || opts.mp4) {
+        const fps = typeof opts.fps === "number" ? opts.fps : 15;
+        const { spawnSync } = await import("child_process");
+        const which = spawnSync("which", ["ffmpeg"]);
+        if (which.status !== 0) {
+          process.stderr.write("[chrome-relay] ffmpeg not on PATH \u2014 skipping --gif/--mp4.\n");
+          return;
+        }
+        if (opts.gif) {
+          const gifOut = `${opts.out.replace(/\/$/, "")}.gif`;
+          const r = spawnSync("ffmpeg", [
+            "-y",
+            "-framerate",
+            String(fps),
+            "-i",
+            path2.join(opts.out, "frame_%04d.jpg"),
+            "-vf",
+            `fps=${fps},split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse`,
+            "-loop",
+            "0",
+            gifOut
+          ], { stdio: "inherit" });
+          if (r.status === 0) process.stdout.write(`Wrote ${gifOut}
+`);
+        }
+        if (opts.mp4) {
+          const mp4Out = `${opts.out.replace(/\/$/, "")}.mp4`;
+          const r = spawnSync("ffmpeg", [
+            "-y",
+            "-framerate",
+            String(fps),
+            "-i",
+            path2.join(opts.out, "frame_%04d.jpg"),
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-crf",
+            "20",
+            mp4Out
+          ], { stdio: "inherit" });
+          if (r.status === 0) process.stdout.write(`Wrote ${mp4Out}
+`);
+        }
+      }
+    } catch (error) {
+      process.stderr.write(
+        (error instanceof Error ? error.message : String(error)) + "\n"
+      );
+      process.exit(1);
+    }
+  });
   return program;
 }
 

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.3.3" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.0" : "0.0.0-dev";
 export {
   CHROME_RELAY_VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",