browser-pilot-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,1136 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { writeFileSync as writeFileSync3, readFileSync as readFileSync5, existsSync as existsSync6 } from "fs";
+import { resolve as resolvePath } from "path";
+
+// src/session.ts
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { existsSync as existsSync4 } from "fs";
+
+// src/client.ts
+import http from "http";
+import { existsSync, readFileSync } from "fs";
+
+// src/paths.ts
+import { join } from "path";
+import { homedir } from "os";
+var STATE_DIR = join(homedir(), ".browser-pilot");
+var STATE_FILE = join(STATE_DIR, "state.json");
+var SOCKET_PATH = join(STATE_DIR, "daemon.sock");
+var PID_FILE = join(STATE_DIR, "daemon.pid");
+var REFS_FILE = join(STATE_DIR, "refs.json");
+
+// src/client.ts
+function isDaemonRunning() {
+  if (!existsSync(PID_FILE)) return false;
+  const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var DaemonClient = class {
+  request(path, body) {
+    return new Promise((resolve, reject) => {
+      const req = http.request(
+        {
+          socketPath: SOCKET_PATH,
+          path,
+          method: body !== void 0 ? "POST" : "GET",
+          headers: body !== void 0 ? { "Content-Type": "application/json" } : {},
+          timeout: 6e4
+        },
+        (res) => {
+          let data = "";
+          res.on("data", (chunk) => {
+            data += chunk.toString();
+          });
+          res.on("end", () => {
+            try {
+              const parsed = JSON.parse(data);
+              if (parsed.error) reject(new Error(parsed.error));
+              else resolve(parsed.result ?? parsed);
+            } catch {
+              reject(new Error(`Invalid daemon response: ${data}`));
+            }
+          });
+        }
+      );
+      req.on("error", (err) => {
+        reject(new Error(`Cannot reach daemon: ${err.message}. Run 'bp connect' first.`));
+      });
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error("Daemon request timeout"));
+      });
+      if (body !== void 0) req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+  async send(method, params, sessionId) {
+    return this.request("/cdp", { method, params, sessionId });
+  }
+  async health() {
+    try {
+      await this.request("/health");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async healthInfo() {
+    try {
+      return await this.request("/health");
+    } catch {
+      return { ok: false };
+    }
+  }
+  async shutdown() {
+    try {
+      await this.request("/shutdown", {});
+    } catch {
+    }
+  }
+  async dialogs() {
+    const res = await this.request("/dialogs");
+    return res.dialogs ?? [];
+  }
+  async discoveredTargets() {
+    const res = await this.request("/discovered");
+    return res.targets ?? [];
+  }
+  async setAuth(username, password) {
+    await this.request("/auth", { username, password });
+  }
+  async clearAuth() {
+    await this.request("/auth", { username: "", password: "" });
+  }
+  // ── Network methods ──────────────────────────────
+  async enableNetwork(sessionId) {
+    await this.request("/net/enable", { sessionId });
+  }
+  async netRequests(opts) {
+    const p = new URLSearchParams();
+    if (opts?.limit) p.set("limit", String(opts.limit));
+    if (opts?.url) p.set("url", opts.url);
+    if (opts?.method) p.set("method", opts.method);
+    if (opts?.status) p.set("status", opts.status);
+    if (opts?.type) p.set("type", opts.type);
+    if (opts?.after) p.set("after", String(opts.after));
+    const qs = p.toString();
+    return this.request(`/net/requests${qs ? "?" + qs : ""}`);
+  }
+  async netRequestDetail(id) {
+    return this.request(`/net/request/${id}`);
+  }
+  async netBody(id) {
+    return this.request(`/net/body/${id}`);
+  }
+  async netClear() {
+    await this.request("/net/clear", {});
+  }
+  async netAddRule(rule) {
+    return this.request("/net/rules", rule);
+  }
+  async netRules() {
+    return this.request("/net/rules");
+  }
+  async netRemoveRule(id) {
+    await this.request("/net/rules/remove", id !== void 0 ? { id } : { all: true });
+  }
+  close() {
+  }
+};
+
+// src/chrome.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2, platform } from "os";
+function getDataDirs() {
+  const home = homedir2();
+  const os = platform();
+  if (os === "darwin") {
+    const base = join2(home, "Library", "Application Support");
+    return [
+      { name: "Chrome", path: join2(base, "Google", "Chrome") },
+      { name: "Chrome Beta", path: join2(base, "Google", "Chrome Beta") },
+      { name: "Chrome Canary", path: join2(base, "Google", "Chrome Canary") },
+      { name: "Brave", path: join2(base, "BraveSoftware", "Brave-Browser") },
+      { name: "Edge", path: join2(base, "Microsoft Edge") },
+      { name: "Chromium", path: join2(base, "Chromium") }
+    ];
+  }
+  if (os === "linux") {
+    return [
+      { name: "Chrome", path: join2(home, ".config", "google-chrome") },
+      { name: "Chromium", path: join2(home, ".config", "chromium") },
+      { name: "Brave", path: join2(home, ".config", "BraveSoftware", "Brave-Browser") },
+      { name: "Edge", path: join2(home, ".config", "microsoft-edge") }
+    ];
+  }
+  if (os === "win32") {
+    const appData = process.env.LOCALAPPDATA ?? join2(home, "AppData", "Local");
+    return [
+      { name: "Chrome", path: join2(appData, "Google", "Chrome", "User Data") },
+      { name: "Brave", path: join2(appData, "BraveSoftware", "Brave-Browser", "User Data") },
+      { name: "Edge", path: join2(appData, "Microsoft", "Edge", "User Data") }
+    ];
+  }
+  return [];
+}
+function discoverChrome(browserFilter) {
+  for (const { name, path: dataDir } of getDataDirs()) {
+    if (browserFilter && !name.toLowerCase().includes(browserFilter.toLowerCase())) continue;
+    const portFile = join2(dataDir, "DevToolsActivePort");
+    if (!existsSync2(portFile)) continue;
+    try {
+      const lines = readFileSync2(portFile, "utf-8").trim().split("\n");
+      if (lines.length < 2) continue;
+      const port = parseInt(lines[0], 10);
+      const wsPath = lines[1];
+      if (isNaN(port) || !wsPath) continue;
+      return {
+        port,
+        wsPath,
+        wsUrl: `ws://127.0.0.1:${port}${wsPath}`,
+        browser: name,
+        dataDir
+      };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/state.ts
+import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync3, mkdirSync, unlinkSync } from "fs";
+function loadState() {
+  if (!existsSync3(STATE_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync3(STATE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveState(state) {
+  if (!existsSync3(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true, mode: 448 });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), { mode: 384 });
+}
+function clearState() {
+  try {
+    unlinkSync(STATE_FILE);
+  } catch {
+  }
+}
+
+// src/page-scripts.ts
+var GET_CLICK_COORDS = `function() {
+  this.scrollIntoView({block:'center',inline:'center'});
+  const r = this.getBoundingClientRect();
+  return JSON.stringify({x: r.x + r.width/2, y: r.y + r.height/2});
+}`;
+var SET_VALUE = `function(text, clear) {
+  this.focus();
+  const proto = this instanceof HTMLTextAreaElement
+    ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+  const val = clear ? text : this.value + text;
+  if (setter) setter.call(this, val); else this.value = val;
+  this.dispatchEvent(new Event('input',  {bubbles:true}));
+  this.dispatchEvent(new Event('change', {bubbles:true}));
+}`;
+var PAGE_INFO = `JSON.stringify({title:document.title,url:location.href})`;
+var PAGE_DIMENSIONS = `JSON.stringify({
+  width:  Math.max(document.documentElement.scrollWidth,  document.documentElement.clientWidth),
+  height: Math.max(document.documentElement.scrollHeight, document.documentElement.clientHeight)
+})`;
+var INJECT_BORDER = `(() => {
+  if (document.getElementById('__bp_overlay')) return;
+  const d = document.createElement('div');
+  d.id = '__bp_overlay';
+  d.setAttribute('aria-hidden','true');
+  d.setAttribute('role','presentation');
+  Object.assign(d.style, {position:'fixed',inset:'0',zIndex:'2147483647',pointerEvents:'none'});
+  document.documentElement.appendChild(d);
+  try{d.animate([
+    {boxShadow:'inset 0 0 20px rgba(59,130,246,.8),inset 0 0 40px rgba(59,130,246,.4),inset 0 0 80px rgba(59,130,246,.15)'},
+    {boxShadow:'inset 0 0 30px rgba(59,130,246,1),inset 0 0 60px rgba(59,130,246,.5),inset 0 0 100px rgba(59,130,246,.2)'},
+    {boxShadow:'inset 0 0 20px rgba(59,130,246,.8),inset 0 0 40px rgba(59,130,246,.4),inset 0 0 80px rgba(59,130,246,.15)'},
+  ],{duration:2500,iterations:Infinity,easing:'ease-in-out'})}catch(e){}
+})()`;
+function elementRect(selector) {
+  return `JSON.stringify((() => {
+    const el = document.querySelector(${JSON.stringify(selector)});
+    if (!el) return null;
+    const r = el.getBoundingClientRect();
+    return {x:r.x, y:r.y, width:r.width, height:r.height};
+  })())`;
+}
+
+// src/session.ts
+async function startDaemon(wsUrl) {
+  const script = fileURLToPath(new URL("daemon.js", import.meta.url));
+  const child = spawn(process.execPath, [script, wsUrl], { detached: true, stdio: "ignore" });
+  child.unref();
+  const client = new DaemonClient();
+  const deadline = Date.now() + 6e4;
+  while (Date.now() < deadline) {
+    if (await client.health()) return client;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error(`Connection timeout. Make sure to click "Allow" in Chrome's authorization dialog.`);
+}
+async function getDaemon(wsUrl) {
+  if (isDaemonRunning()) {
+    const client = new DaemonClient();
+    const info = await client.healthInfo();
+    if (info.ok) {
+      if (info.wsUrl === wsUrl) return client;
+      await client.shutdown();
+      const deadline = Date.now() + 5e3;
+      while (Date.now() < deadline && existsSync4(SOCKET_PATH)) {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  }
+  return startDaemon(wsUrl);
+}
+async function verifyPilotTargets(client, state) {
+  const { targetInfos } = await client.send("Target.getTargets");
+  const existing = new Set(targetInfos.map((t) => t.targetId));
+  state.pilotTargetIds = state.pilotTargetIds.filter((id) => existing.has(id));
+  if (state.pilotTargetIds.length === 0) return false;
+  if (!state.pilotTargetIds.includes(state.activeTargetId)) {
+    state.activeTargetId = state.pilotTargetIds[0];
+    state.activeSessionId = void 0;
+  }
+  saveState(state);
+  return true;
+}
+async function initSession(transport, sessionId) {
+  await transport.send("Page.enable", {}, sessionId).catch(() => {
+  });
+  await transport.send("Runtime.evaluate", { expression: INJECT_BORDER }, sessionId).catch(() => {
+  });
+}
+async function ensureSession(client, state) {
+  if (state.activeSessionId) {
+    try {
+      await client.send("Runtime.evaluate", { expression: "1" }, state.activeSessionId);
+      return state.activeSessionId;
+    } catch {
+    }
+  }
+  const { sessionId } = await client.send("Target.attachToTarget", {
+    targetId: state.activeTargetId,
+    flatten: true
+  });
+  await initSession(client, sessionId);
+  state.activeSessionId = sessionId;
+  saveState(state);
+  return sessionId;
+}
+async function connectFresh(browserFilter) {
+  const chrome = discoverChrome(browserFilter);
+  if (!chrome) {
+    throw new Error(
+      "Cannot find Chrome DevTools port.\nOpen chrome://inspect/#remote-debugging in Chrome and toggle ON."
+    );
+  }
+  const client = await getDaemon(chrome.wsUrl);
+  const { targetId } = await client.send("Target.createTarget", {
+    url: "about:blank",
+    newWindow: true
+  });
+  const { sessionId } = await client.send("Target.attachToTarget", {
+    targetId,
+    flatten: true
+  });
+  await initSession(client, sessionId);
+  const state = {
+    wsEndpoint: chrome.wsUrl,
+    browser: chrome.browser,
+    pilotTargetIds: [targetId],
+    activeTargetId: targetId,
+    activeSessionId: sessionId
+  };
+  saveState(state);
+  return { client, state };
+}
+async function resumeExisting() {
+  const state = loadState();
+  if (!state) return null;
+  if (!isDaemonRunning()) return null;
+  const client = new DaemonClient();
+  if (!await client.health()) return null;
+  const valid = await verifyPilotTargets(client, state);
+  if (!valid) return null;
+  return { client, state };
+}
+async function resume(browserFilter) {
+  const existing = await resumeExisting();
+  if (existing) return existing;
+  return connectFresh(browserFilter);
+}
+async function withPilot(fn) {
+  const { client, state } = await resume();
+  const sessionId = await ensureSession(client, state);
+  await fn({ transport: client, state, sessionId });
+}
+async function disconnect() {
+  if (isDaemonRunning()) {
+    const client = new DaemonClient();
+    try {
+      await client.shutdown();
+    } catch {
+    }
+  }
+  clearState();
+}
+async function waitForLoad(transport, sessionId, timeout = 3e4) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const { result } = await transport.send("Runtime.evaluate", {
+        expression: "document.readyState"
+      }, sessionId);
+      if (result.value === "complete") {
+        await transport.send("Runtime.evaluate", { expression: INJECT_BORDER }, sessionId).catch(() => {
+        });
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error("Page load timeout");
+}
+
+// src/snapshot.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5 } from "fs";
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "textbox",
+  "searchbox",
+  "combobox",
+  "listbox",
+  "checkbox",
+  "radio",
+  "spinbutton",
+  "slider",
+  "switch",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab"
+]);
+function saveRefs(targetId, entries) {
+  writeFileSync2(REFS_FILE, JSON.stringify({ targetId, entries }), { mode: 384 });
+}
+function loadRefs(expectedTargetId) {
+  if (!existsSync5(REFS_FILE)) return [];
+  try {
+    const stored = JSON.parse(readFileSync4(REFS_FILE, "utf-8"));
+    if (expectedTargetId && stored.targetId !== expectedTargetId) return [];
+    return stored.entries;
+  } catch {
+    return [];
+  }
+}
+async function takeSnapshot(transport, sessionId, targetId, limit = 50) {
+  const { result: info } = await transport.send("Runtime.evaluate", {
+    expression: PAGE_INFO,
+    returnByValue: true
+  }, sessionId);
+  const { title, url } = JSON.parse(info.value);
+  const { nodes } = await transport.send("Accessibility.getFullAXTree", {}, sessionId);
+  const map = /* @__PURE__ */ new Map();
+  for (const n of nodes) map.set(n.nodeId, { ...n, children: [] });
+  let root = null;
+  for (const [, node] of map) {
+    if (node.childIds) {
+      node.children = node.childIds.map((id) => map.get(id)).filter(Boolean);
+    }
+    if (!node.parentId) root = node;
+  }
+  const refs = [];
+  const elements = [];
+  function walk(node) {
+    if (!node) return;
+    if (!node.ignored) {
+      const role = node.role?.value;
+      if (role && INTERACTIVE_ROLES.has(role) && node.backendDOMNodeId !== void 0) {
+        const props = Object.fromEntries(
+          (node.properties || []).map((p) => [p.name, p.value?.value])
+        );
+        const name = node.name?.value || "";
+        const value = node.value?.value;
+        if (!props.disabled && (name || value) && refs.length < limit) {
+          const checked = props.checked === "true" || props.checked === true ? true : void 0;
+          refs.push({ backendNodeId: node.backendDOMNodeId, role, name });
+          elements.push({ ref: refs.length, backendNodeId: node.backendDOMNodeId, role, name, value, checked });
+        }
+      }
+    }
+    for (const child of node.children) walk(child);
+  }
+  if (root) walk(root);
+  saveRefs(targetId, refs);
+  const lines = [`[page] ${title} | ${url}`, ""];
+  if (elements.length === 0) {
+    lines.push("(no interactive elements)");
+  } else {
+    for (const el of elements) {
+      let line = `[${el.ref}] ${el.role} "${el.name}"`;
+      if (el.value !== void 0 && el.value !== "") line += ` value="${el.value}"`;
+      if (el.checked) line += " checked";
+      lines.push(line);
+    }
+  }
+  return { text: lines.join("\n"), data: { title, url, elements } };
+}
+function isRef(target) {
+  return /^\d+$/.test(target);
+}
+async function resolveTarget(transport, sessionId, target, targetId) {
+  if (isRef(target)) {
+    const refs = loadRefs(targetId);
+    const ref = parseInt(target, 10);
+    if (ref < 1 || ref > refs.length) {
+      throw new Error(`Ref [${ref}] not found. Run 'bp snapshot' to refresh.`);
+    }
+    const { object } = await transport.send("DOM.resolveNode", {
+      backendNodeId: refs[ref - 1].backendNodeId
+    }, sessionId);
+    return object.objectId;
+  }
+  const { result } = await transport.send("Runtime.evaluate", {
+    expression: `document.querySelector(${JSON.stringify(target)})`
+  }, sessionId);
+  if (!result.objectId) throw new Error(`Element not found: ${target}`);
+  return result.objectId;
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("bp").description("Control your browser from the command line").version("0.1.0").option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
+Workflow:
+  bp connect                          # one-time setup (click Allow in Chrome)
+  bp open <url>                       # navigate \u2014 returns snapshot with [ref] numbers
+  bp click <ref>                      # interact \u2014 returns updated snapshot
+  bp type <ref> <text>                # input text \u2014 returns updated snapshot
+  bp press <key>                      # keyboard \u2014 returns updated snapshot
+  bp eval <js>                        # run JavaScript (escape hatch for anything)
+
+Refs:
+  open/click/type/press return numbered interactive elements like:
+    [1] link "Home"  [2] textbox "Search"  [3] button "Submit"
+  Use the number in subsequent commands: bp click 1, bp type 2 "hello"
+
+Output:
+  JSON by default when piped (for LLM/script use).
+  Human-readable when run in a terminal (TTY). Force with --human.
+  Actions return: {"ok":true, "title":"...", "url":"...", "elements":[...]}
+  Errors return:  {"ok":false, "error":"...", "hint":"..."}
+
+Edge cases:
+  bp upload <ref> <filepath>                         # file input upload
+  bp auth <user> <pass>                              # HTTP Basic Auth
+  bp frame                                           # list iframes
+  bp frame 1                                         # eval in iframe context
+  bp frame 0                                         # back to top frame
+  Dialogs (alert/confirm) are auto-handled by the daemon.
+
+Eval (replaces scroll, back, forward, extract, etc.):
+  bp eval "history.back()"                           # go back
+  bp eval "history.forward()"                        # go forward
+  bp eval "location.reload()"                        # reload
+  bp eval "window.scrollBy(0, 500)"                  # scroll down
+  bp eval "document.querySelector('h1').textContent"  # extract text
+  bp eval "document.querySelector('div').innerHTML"   # extract HTML
+  bp eval "JSON.stringify(localStorage)"              # read storage
+  echo 'complex js here' | bp eval                   # stdin for complex JS
+`);
+function useJson() {
+  if (program.opts().human) return false;
+  return !process.stdout.isTTY;
+}
+function emit(data, human) {
+  if (useJson()) console.log(JSON.stringify(data));
+  else if (human) console.log(human);
+}
+function fail(error, hint) {
+  if (useJson()) console.log(JSON.stringify({ ok: false, error, ...hint ? { hint } : {} }));
+  else console.error(`\u2717 ${error}${hint ? `
+  hint: ${hint}` : ""}`);
+  process.exit(1);
+}
+function emitSnapshot(result) {
+  if (useJson()) console.log(JSON.stringify({ ok: true, ...result.data }));
+  else console.log(result.text);
+}
+function action(fn) {
+  return (...args) => fn(...args).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("not found") && msg.includes("Ref")) fail(msg, "Run 'bp snapshot' to refresh element refs.");
+    if (msg.includes("Not connected")) fail(msg, "Run 'bp connect' first.");
+    if (msg.includes("Page load timeout")) fail(msg, "Page may still be loading. Retry the command after a moment.");
+    fail(msg);
+  });
+}
+function normalizeUrl(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url)) return url;
+  return `https://${url}`;
+}
+function parseLimit(raw) {
+  const n = parseInt(raw, 10);
+  if (isNaN(n) || n < 1) throw new Error("--limit must be a positive number");
+  return n;
+}
+function readStdin() {
+  if (process.stdin.isTTY) return Promise.resolve("");
+  return new Promise((resolve) => {
+    let d = "";
+    process.stdin.on("data", (c) => {
+      d += c;
+    });
+    process.stdin.on("end", () => resolve(d.trim()));
+  });
+}
+async function snap(t, sid, tid, limit) {
+  await new Promise((r) => setTimeout(r, 300));
+  await waitForLoad(t, sid, 1e4);
+  return takeSnapshot(t, sid, tid, limit);
+}
+async function dispatchClick(t, sid, x, y) {
+  await t.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none" }, sid);
+  await t.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", clickCount: 1 }, sid);
+  await t.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", clickCount: 1 }, sid);
+}
+var KEY_DEFS = {
+  enter: { key: "Enter", code: "Enter", keyCode: 13 },
+  tab: { key: "Tab", code: "Tab", keyCode: 9 },
+  escape: { key: "Escape", code: "Escape", keyCode: 27 },
+  esc: { key: "Escape", code: "Escape", keyCode: 27 },
+  backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
+  delete: { key: "Delete", code: "Delete", keyCode: 46 },
+  space: { key: " ", code: "Space", keyCode: 32 },
+  arrowup: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
+  arrowdown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
+  arrowleft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
+  arrowright: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 },
+  home: { key: "Home", code: "Home", keyCode: 36 },
+  end: { key: "End", code: "End", keyCode: 35 },
+  pageup: { key: "PageUp", code: "PageUp", keyCode: 33 },
+  pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 }
+};
+var MOD_DEFS = {
+  control: { key: "Control", code: "ControlLeft", keyCode: 17, mask: 2 },
+  ctrl: { key: "Control", code: "ControlLeft", keyCode: 17, mask: 2 },
+  shift: { key: "Shift", code: "ShiftLeft", keyCode: 16, mask: 8 },
+  alt: { key: "Alt", code: "AltLeft", keyCode: 18, mask: 1 },
+  meta: { key: "Meta", code: "MetaLeft", keyCode: 91, mask: 4 },
+  cmd: { key: "Meta", code: "MetaLeft", keyCode: 91, mask: 4 },
+  command: { key: "Meta", code: "MetaLeft", keyCode: 91, mask: 4 }
+};
+async function dispatchKey(t, sid, combo) {
+  const parts = combo.split("+");
+  const mainKey = parts.pop();
+  const mods = parts.map((p) => {
+    const m = MOD_DEFS[p.toLowerCase()];
+    if (!m) throw new Error(`Unknown modifier: ${p}`);
+    return m;
+  });
+  const modifierFlags = mods.reduce((n, m) => n | m.mask, 0);
+  const kd = KEY_DEFS[mainKey.toLowerCase()];
+  const key = kd?.key ?? mainKey;
+  const code = kd?.code ?? (mainKey.length === 1 ? `Key${mainKey.toUpperCase()}` : mainKey);
+  const keyCode = kd?.keyCode ?? mainKey.toUpperCase().charCodeAt(0);
+  for (const m of mods) {
+    await t.send("Input.dispatchKeyEvent", { type: "keyDown", key: m.key, code: m.code, windowsVirtualKeyCode: m.keyCode, modifiers: modifierFlags }, sid);
+  }
+  const text = key === "Enter" ? "\r" : kd ? "" : mainKey;
+  await t.send("Input.dispatchKeyEvent", { type: "keyDown", key, code, windowsVirtualKeyCode: keyCode, text, modifiers: modifierFlags }, sid);
+  await t.send("Input.dispatchKeyEvent", { type: "keyUp", key, code, windowsVirtualKeyCode: keyCode, modifiers: modifierFlags }, sid);
+  for (const m of mods.reverse()) {
+    await t.send("Input.dispatchKeyEvent", { type: "keyUp", key: m.key, code: m.code, windowsVirtualKeyCode: m.keyCode }, sid);
+  }
+}
+program.command("connect").description("Connect to Chrome and create pilot window").option("-b, --browser <name>", "browser to connect to").addHelpText("after", "\nExamples:\n  bp connect\n  bp connect --browser brave").action(action(async (opts) => {
+  if (!useJson()) {
+    console.log("Connecting to Chrome...");
+    console.log(`If prompted, click "Allow" in Chrome's authorization dialog.
+`);
+  }
+  const { state } = await connectFresh(opts.browser);
+  emit(
+    { ok: true, browser: state.browser },
+    `\u2713 Connected to ${state.browser}
+\u2713 Pilot window created (daemon running in background)
+
+Ready! Try: bp open https://example.com`
+  );
+}));
+program.command("disconnect").description("Close pilot window and stop daemon").action(action(async () => {
+  const existing = await resumeExisting();
+  if (existing) {
+    for (const id of existing.state.pilotTargetIds) {
+      try {
+        await existing.client.send("Target.closeTarget", { targetId: id });
+      } catch {
+      }
+    }
+  }
+  await disconnect();
+  emit({ ok: true }, "\u2713 Disconnected");
+}));
+program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
+  url = normalizeUrl(url);
+  const limit = parseLimit(opts.limit);
+  await withPilot(async ({ transport, state, sessionId }) => {
+    let sid = sessionId;
+    let tid = state.activeTargetId;
+    if (opts.new) {
+      const { targetId } = await transport.send("Target.createTarget", { url });
+      const r = await transport.send("Target.attachToTarget", { targetId, flatten: true });
+      await initSession(transport, r.sessionId);
+      state.pilotTargetIds.push(targetId);
+      state.activeTargetId = targetId;
+      state.activeSessionId = r.sessionId;
+      state.frameContextId = void 0;
+      saveState(state);
+      sid = r.sessionId;
+      tid = targetId;
+    } else {
+      await transport.send("Page.navigate", { url }, sid);
+      state.frameContextId = void 0;
+      saveState(state);
+    }
+    await waitForLoad(transport, sid);
+    emitSnapshot(await takeSnapshot(transport, sid, tid, limit));
+  });
+}));
+program.command("snapshot").description("Get interactive elements on the page").option("-l, --limit <n>", "max elements to return", "50").addHelpText("after", "\nExamples:\n  bp snapshot\n  bp snapshot --limit 100").action(action(async (opts) => {
+  const limit = parseLimit(opts.limit);
+  await withPilot(async ({ transport, sessionId, state }) => {
+    emitSnapshot(await takeSnapshot(transport, sessionId, state.activeTargetId, limit));
+  });
+}));
+program.command("click <ref>").description("Click element by ref number and return page snapshot").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nRef is a number from the snapshot output.\n\nExamples:\n  bp click 3\n  bp click 3 --limit 10").action(action(async (ref, opts) => {
+  const limit = parseLimit(opts.limit);
+  await withPilot(async ({ transport, sessionId, state }) => {
+    const objectId = await resolveTarget(transport, sessionId, ref, state.activeTargetId);
+    try {
+      const { result } = await transport.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: GET_CLICK_COORDS,
+        returnByValue: true
+      }, sessionId);
+      const { x, y } = JSON.parse(result.value);
+      await dispatchClick(transport, sessionId, x, y);
+    } finally {
+      await transport.send("Runtime.releaseObject", { objectId }, sessionId).catch(() => {
+      });
+    }
+    emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
+  });
+}));
+program.command("type <ref> <text>").description("Type text into element and return page snapshot").option("-c, --clear", "clear field before typing").option("-s, --submit", "press Enter after typing").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", '\nExamples:\n  bp type 2 "hello world"\n  bp type 5 "query" --submit\n  bp type 3 "new value" --clear').action(action(async (ref, text, opts) => {
+  const limit = parseLimit(opts.limit);
+  await withPilot(async ({ transport, sessionId, state }) => {
+    const objectId = await resolveTarget(transport, sessionId, ref, state.activeTargetId);
+    try {
+      await transport.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: SET_VALUE,
+        arguments: [{ value: text }, { value: !!opts.clear }]
+      }, sessionId);
+      if (opts.submit) await dispatchKey(transport, sessionId, "Enter");
+    } finally {
+      await transport.send("Runtime.releaseObject", { objectId }, sessionId).catch(() => {
+      });
+    }
+    emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
+  });
+}));
+program.command("press <key>").description("Press key combo (e.g. Enter, Escape, Control+a) and return snapshot").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nKeys: Enter, Escape, Tab, Space, Backspace, Delete,\n      ArrowUp, ArrowDown, ArrowLeft, ArrowRight,\n      Home, End, PageUp, PageDown\nModifiers: Control (Ctrl), Shift, Alt, Meta (Cmd)\n\nExamples:\n  bp press Enter\n  bp press Escape\n  bp press Control+a\n  bp press Meta+c").action(action(async (key, opts) => {
+  const limit = parseLimit(opts.limit);
+  await withPilot(async ({ transport, sessionId, state }) => {
+    await dispatchKey(transport, sessionId, key);
+    emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
+  });
+}));
+program.command("eval [expression]").description("Execute JavaScript (pass via argument or stdin)").addHelpText("after", `
+This is the escape hatch \u2014 anything JS can do, eval can do.
+
+Examples:
+  bp eval "document.title"
+  bp eval "history.back()"
+  bp eval "window.scrollBy(0, 500)"
+  bp eval "document.querySelector('h1').textContent"
+  echo 'complex js' | bp eval`).action(action(async (expression) => {
+  if (!expression) {
+    expression = await readStdin();
+    if (!expression) throw new Error("No expression. Pass as argument or pipe via stdin.");
+  }
+  await withPilot(async ({ transport, sessionId, state }) => {
+    const evalParams = { expression, returnByValue: true, awaitPromise: true };
+    if (state.frameContextId) evalParams.contextId = state.frameContextId;
+    const { result, exceptionDetails } = await transport.send("Runtime.evaluate", evalParams, sessionId);
+    if (exceptionDetails) {
+      throw new Error(exceptionDetails.exception?.description || exceptionDetails.text || "Evaluation error");
+    }
+    if (useJson()) {
+      console.log(JSON.stringify({ ok: true, value: result.value }));
+    } else if (result.value !== void 0) {
+      console.log(typeof result.value === "object" ? JSON.stringify(result.value, null, 2) : String(result.value));
+    }
+  });
+}));
+program.command("upload <filepath>").description('Upload file (auto-finds <input type="file"> on the page)').option("--nth <n>", "which file input to use if multiple exist", "1").addHelpText("after", "\nAuto-detects file inputs on the page. No ref needed.\n\nExamples:\n  bp upload ./photo.jpg\n  bp upload /tmp/resume.pdf\n  bp upload ./doc.pdf --nth 2    # if multiple file inputs").action(action(async (filepath, opts) => {
+  const absPath = resolvePath(filepath);
+  if (!existsSync6(absPath)) throw new Error(`File not found: ${absPath}`);
+  await withPilot(async ({ transport, sessionId, state }) => {
+    const { result } = await transport.send("Runtime.evaluate", {
+      expression: `JSON.stringify(Array.from(document.querySelectorAll('input[type=file]')).map((el,i) => ({index:i+1, name:el.name||el.id||'unnamed', accept:el.accept||'*'})))`,
+      returnByValue: true
+    }, sessionId);
+    const inputs = JSON.parse(result.value);
+    if (inputs.length === 0) throw new Error('No <input type="file"> found on this page.');
+    const nth = parseInt(opts.nth, 10);
+    if (nth < 1 || nth > inputs.length) {
+      const list = inputs.map((i) => `  ${i.index}. ${i.name} (${i.accept})`).join("\n");
+      throw new Error(`${inputs.length} file input(s) found. Use --nth to choose:
+${list}`);
+    }
+    const { result: elResult } = await transport.send("Runtime.evaluate", {
+      expression: `document.querySelectorAll('input[type=file]')[${nth - 1}]`
+    }, sessionId);
+    try {
+      const { node } = await transport.send("DOM.describeNode", { objectId: elResult.objectId }, sessionId);
+      await transport.send("DOM.setFileInputFiles", {
+        files: [absPath],
+        backendNodeId: node.backendNodeId
+      }, sessionId);
+    } finally {
+      if (elResult.objectId) {
+        await transport.send("Runtime.releaseObject", { objectId: elResult.objectId }, sessionId).catch(() => {
+        });
+      }
+    }
+    emitSnapshot(await snap(transport, sessionId, state.activeTargetId));
+  });
+}));
+program.command("screenshot [filename]").description("Capture screenshot").option("-f, --full", "capture full page").option("--selector <sel>", "capture specific element").addHelpText("after", '\nExamples:\n  bp screenshot\n  bp screenshot page.png\n  bp screenshot --full\n  bp screenshot --selector ".chart"').action(action(async (filename, opts) => {
+  await withPilot(async ({ transport, sessionId }) => {
+    const params = { format: "png" };
+    if (opts.full) {
+      const { result } = await transport.send("Runtime.evaluate", {
+        expression: PAGE_DIMENSIONS,
+        returnByValue: true
+      }, sessionId);
+      const dims = JSON.parse(result.value);
+      params.captureBeyondViewport = true;
+      params.clip = { x: 0, y: 0, ...dims, scale: 1 };
+    }
+    if (opts.selector) {
+      const { result } = await transport.send("Runtime.evaluate", {
+        expression: elementRect(opts.selector),
+        returnByValue: true
+      }, sessionId);
+      const rect = result.value ? JSON.parse(result.value) : null;
+      if (!rect) throw new Error(`Element not found: ${opts.selector}`);
+      params.clip = { ...rect, scale: 1 };
+    }
+    const { data } = await transport.send("Page.captureScreenshot", params, sessionId);
+    const file = filename ?? `screenshot-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, -5)}.png`;
+    writeFileSync3(file, Buffer.from(data, "base64"));
+    emit({ ok: true, file }, `\u2713 Screenshot saved to ${file}`);
+  });
+}));
+program.command("pdf [filename]").description("Save page as PDF").option("--landscape", "landscape orientation").addHelpText("after", "\nExamples:\n  bp pdf\n  bp pdf report.pdf\n  bp pdf report.pdf --landscape").action(action(async (filename, opts) => {
+  await withPilot(async ({ transport, sessionId }) => {
+    const params = {};
+    if (opts.landscape) params.landscape = true;
+    const { data } = await transport.send("Page.printToPDF", params, sessionId);
+    const file = filename ?? `page-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, -5)}.pdf`;
+    writeFileSync3(file, Buffer.from(data, "base64"));
+    emit({ ok: true, file }, `\u2713 PDF saved to ${file}`);
+  });
+}));
+program.command("cookies [domain]").description("View cookies (CDP-only, includes HttpOnly)").addHelpText("after", "\nExamples:\n  bp cookies\n  bp cookies github.com").action(action(async (domain) => {
+  await withPilot(async ({ transport, sessionId }) => {
+    const { result: info } = await transport.send("Runtime.evaluate", {
+      expression: "location.href",
+      returnByValue: true
+    }, sessionId);
+    const urls = domain ? [`https://${domain}`, `http://${domain}`] : [info.value];
+    const { cookies } = await transport.send("Network.getCookies", { urls }, sessionId);
+    if (useJson()) {
+      console.log(JSON.stringify({ ok: true, cookies }));
+    } else if (cookies.length === 0) {
+      console.log("No cookies found.");
+    } else {
+      for (const c of cookies) {
+        const exp = c.expires === -1 ? "Session" : new Date(c.expires * 1e3).toISOString().slice(0, 10);
+        console.log(`${c.name.padEnd(30)} ${c.domain.padEnd(25)} ${exp}`);
+      }
+    }
+  });
+}));
+program.command("frame [target]").description("List frames, or switch to a frame by index (0=top)").addHelpText("after", "\nExamples:\n  bp frame          # list all frames\n  bp frame 1        # switch eval context to frame 1\n  bp frame 0        # switch back to top frame").action(action(async (target) => {
+  await withPilot(async ({ transport, sessionId, state }) => {
+    const { frameTree } = await transport.send("Page.getFrameTree", {}, sessionId);
+    const frames = [];
+    function collect(node) {
+      frames.push({ id: node.frame.id, url: node.frame.url, name: node.frame.name || "" });
+      for (const child of node.childFrames || []) collect(child);
+    }
+    collect(frameTree);
+    if (target === void 0) {
+      const list = frames.map((f, i) => ({ index: i, ...f }));
+      if (useJson()) {
+        console.log(JSON.stringify({ ok: true, frames: list }));
+      } else {
+        for (const [i, f] of frames.entries()) {
+          console.log(`${i === 0 ? "* " : "  "}${i}  ${f.url}  ${f.name}`);
+        }
+      }
+    } else {
+      const idx = parseInt(target, 10);
+      if (isNaN(idx) || idx < 0 || idx >= frames.length) {
+        throw new Error(`Frame index out of range (0-${frames.length - 1})`);
+      }
+      if (idx === 0) {
+        state.frameContextId = void 0;
+      } else {
+        const { executionContextId } = await transport.send("Page.createIsolatedWorld", {
+          frameId: frames[idx].id
+        }, sessionId);
+        state.frameContextId = executionContextId;
+      }
+      saveState(state);
+      emit(
+        { ok: true, frame: idx, url: frames[idx].url },
+        `\u2713 Switched to frame ${idx}: ${frames[idx].url}`
+      );
+    }
+  });
+}));
+program.command("auth [username] [password]").description("Set or clear HTTP Basic Auth credentials").option("--clear", "clear stored credentials").addHelpText("after", "\nSets credentials for HTTP 401 challenges.\nCall before navigating to the auth-protected URL.\n\nExamples:\n  bp auth admin secret123\n  bp open https://staging.example.com\n  bp auth --clear").action(action(async (username, password, opts) => {
+  const existing = await resumeExisting();
+  if (!existing) throw new Error("Not connected");
+  const { client, state } = existing;
+  if (opts.clear || !username) {
+    await client.clearAuth();
+    emit({ ok: true }, "\u2713 Auth credentials cleared");
+    return;
+  }
+  if (!password) throw new Error("Usage: bp auth <username> <password>");
+  await client.setAuth(username, password);
+  emit({ ok: true }, "\u2713 Auth credentials set (scoped to HTTP 401 challenges)");
+}));
+program.command("tabs").description("List pilot tabs (auto-adopts discovered popups)").action(action(async () => {
+  const existing = await resumeExisting();
+  if (!existing) throw new Error("Not connected");
+  const { client, state } = existing;
+  const { targetInfos } = await client.send("Target.getTargets");
+  const discovered = await client.discoveredTargets();
+  const knownIds = new Set(state.pilotTargetIds);
+  const existingIds = new Set(targetInfos.map((t) => t.targetId));
+  let adopted = 0;
+  for (const d of discovered) {
+    if (!knownIds.has(d.targetId) && existingIds.has(d.targetId)) {
+      state.pilotTargetIds.push(d.targetId);
+      knownIds.add(d.targetId);
+      adopted++;
+    }
+  }
+  if (adopted > 0) saveState(state);
+  const tabs = state.pilotTargetIds.map((id, i) => {
+    const t = targetInfos.find((t2) => t2.targetId === id);
+    return t ? { index: i, url: t.url || "about:blank", title: t.title || "", active: id === state.activeTargetId } : null;
+  }).filter(Boolean);
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, tabs }));
+  } else if (tabs.length === 0) {
+    console.log("No pilot tabs open.");
+  } else {
+    for (const t of tabs) console.log(`${t.active ? "*" : " "} ${t.index}  ${t.url}  ${t.title}`);
+  }
+}));
+program.command("tab <index>").description("Switch to tab by index").action(action(async (indexStr) => {
+  const existing = await resumeExisting();
+  if (!existing) throw new Error("Not connected");
+  const { client, state } = existing;
+  const index = parseInt(indexStr, 10);
+  if (index < 0 || index >= state.pilotTargetIds.length) {
+    throw new Error(`Tab index out of range (0-${state.pilotTargetIds.length - 1})`);
+  }
+  state.activeTargetId = state.pilotTargetIds[index];
+  state.activeSessionId = void 0;
+  state.frameContextId = void 0;
+  saveState(state);
+  await client.send("Target.activateTarget", { targetId: state.activeTargetId });
+  emit({ ok: true, index }, `\u2713 Switched to tab ${index}`);
+}));
+program.command("close").description("Close current pilot tab").option("-a, --all", "close all tabs").action(action(async (opts) => {
+  const existing = await resumeExisting();
+  if (!existing) throw new Error("Not connected");
+  const { client, state } = existing;
+  if (opts.all) {
+    for (const id of [...state.pilotTargetIds]) {
+      try {
+        await client.send("Target.closeTarget", { targetId: id });
+      } catch {
+      }
+    }
+    clearState();
+    emit({ ok: true }, "\u2713 All tabs closed");
+  } else {
+    await client.send("Target.closeTarget", { targetId: state.activeTargetId });
+    state.pilotTargetIds = state.pilotTargetIds.filter((id) => id !== state.activeTargetId);
+    if (state.pilotTargetIds.length > 0) {
+      state.activeTargetId = state.pilotTargetIds[0];
+      state.activeSessionId = void 0;
+      state.frameContextId = void 0;
+      saveState(state);
+      emit({ ok: true, remaining: state.pilotTargetIds.length }, "\u2713 Tab closed");
+    } else {
+      clearState();
+      emit({ ok: true }, "\u2713 Last tab closed");
+    }
+  }
+}));
+async function ensureNet() {
+  const existing = await resumeExisting();
+  if (!existing) throw new Error("Not connected");
+  const { client, state } = existing;
+  if (state.activeSessionId) await client.enableNetwork(state.activeSessionId);
+  return { client, state };
+}
+var netCmd = program.command("net").description("Network monitoring and interception").option("-l, --limit <n>", "max requests to show", "20").option("--url <pattern>", "filter by URL wildcard").option("--method <method>", "filter by HTTP method").option("--status <code>", "filter by status (200, 4xx, 5xx)").option("--type <types>", "filter by resource type (xhr,fetch,document)").option("--after <id>", "show requests after this ID").addHelpText("after", `
+Examples:
+  bp net                              # list recent requests
+  bp net --url "*api*" --method POST  # filter
+  bp net show 3                       # full details + body
+  bp net block "*tracking*"           # block URLs
+  bp net mock "*api/data*" --body '{"ok":true}'
+  bp net rules                        # list active rules
+  bp net remove --all                 # clear rules`).action(action(async (opts) => {
+  const { client } = await ensureNet();
+  const { requests, total } = await client.netRequests({
+    limit: opts.limit ? parseInt(opts.limit, 10) : void 0,
+    url: opts.url,
+    method: opts.method,
+    status: opts.status,
+    type: opts.type,
+    after: opts.after ? parseInt(opts.after, 10) : void 0
+  });
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, requests, total }));
+  } else if (requests.length === 0) {
+    console.log("No requests captured.");
+  } else {
+    console.log(` ${"#".padStart(4)}  ${"METHOD".padEnd(7)} ${"STATUS".padEnd(7)} ${"TYPE".padEnd(8)} ${"TIME".padEnd(8)} URL`);
+    for (const r of requests) {
+      const time = r.time ? `${r.time}ms` : r.error ? "FAIL" : "...";
+      const status = r.status ? String(r.status) : r.error ? "ERR" : "...";
+      console.log(` ${String(r.id).padStart(4)}  ${r.method.padEnd(7)} ${status.padEnd(7)} ${(r.type || "").padEnd(8)} ${time.padEnd(8)} ${r.url}`);
+    }
+  }
+}));
+netCmd.command("show <id>").description("Show full request/response details").option("--save <file>", "save response body to file").action(action(async (idStr, opts) => {
+  const { client } = await ensureNet();
+  const id = parseInt(idStr, 10);
+  if (opts.save) {
+    const { body } = await client.netBody(id);
+    writeFileSync3(opts.save, body);
+    emit({ ok: true, file: opts.save }, `Saved to ${opts.save}`);
+    return;
+  }
+  const detail = await client.netRequestDetail(id);
+  let responseBody;
+  try {
+    responseBody = (await client.netBody(id)).body;
+  } catch {
+  }
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, ...detail, responseBody }));
+  } else {
+    console.log(`#${detail.id} ${detail.method} ${detail.url}`);
+    console.log(`Status: ${detail.status ?? "pending"} ${detail.statusText ?? ""}`);
+    if (detail.postData) console.log(`
+Request Body:
+${detail.postData}`);
+    if (responseBody) {
+      console.log(`
+Response (${detail.mimeType}):`);
+      console.log(responseBody.length > 2e3 ? responseBody.slice(0, 2e3) + "\n... (truncated)" : responseBody);
+    }
+  }
+}));
+netCmd.command("block <pattern>").description("Block requests matching URL pattern").action(action(async (pattern) => {
+  const { client } = await ensureNet();
+  const { rule } = await client.netAddRule({ type: "block", pattern });
+  emit({ ok: true, rule }, `Rule #${rule.id}: blocking "${pattern}"`);
+}));
+netCmd.command("mock <pattern>").description("Mock responses for matching URLs").option("--body <json>", "response body").option("--file <path>", "read body from file").option("--status <code>", "HTTP status", "200").action(action(async (pattern, opts) => {
+  const { client } = await ensureNet();
+  let body = opts.body || "";
+  if (opts.file) {
+    const filePath = resolvePath(opts.file);
+    if (!existsSync6(filePath)) throw new Error(`File not found: ${filePath}`);
+    body = readFileSync5(filePath, "utf-8");
+  }
+  const { rule } = await client.netAddRule({
+    type: "mock",
+    pattern,
+    status: parseInt(opts.status, 10),
+    body
+  });
+  emit({ ok: true, rule }, `Rule #${rule.id}: mocking "${pattern}" -> ${opts.status}`);
+}));
+netCmd.command("headers <pattern> <header...>").description("Add/override request headers for matching URLs").action(action(async (pattern, headerStrs) => {
+  const { client } = await ensureNet();
+  const headers = headerStrs.map((h) => {
+    const [name, ...rest] = h.split(":");
+    return { name: name.trim(), value: rest.join(":").trim() };
+  });
+  const { rule } = await client.netAddRule({ type: "headers", pattern, headers });
+  emit({ ok: true, rule }, `Rule #${rule.id}: headers for "${pattern}"`);
+}));
+netCmd.command("rules").description("List active interception rules").action(action(async () => {
+  const { client } = await ensureNet();
+  const { rules } = await client.netRules();
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, rules }));
+  } else if (rules.length === 0) {
+    console.log("No active rules.");
+  } else {
+    for (const r of rules) console.log(`  #${r.id}  ${r.type.toUpperCase()} "${r.pattern}"`);
+  }
+}));
+netCmd.command("remove [ruleId]").description("Remove interception rule(s)").option("-a, --all", "remove all rules").action(action(async (ruleId, opts) => {
+  const { client } = await ensureNet();
+  if (opts.all) {
+    await client.netRemoveRule();
+    emit({ ok: true }, "All rules removed");
+  } else if (ruleId) {
+    await client.netRemoveRule(parseInt(ruleId, 10));
+    emit({ ok: true }, `Rule #${ruleId} removed`);
+  } else throw new Error("Specify a rule ID or use --all");
+}));
+netCmd.command("clear").description("Clear captured request log").action(action(async () => {
+  const { client } = await ensureNet();
+  await client.netClear();
+  emit({ ok: true }, "Request log cleared");
+}));
+program.parse();