@h-rig/cli 0.0.6-alpha.0

package/dist/src/commands/browser.js

@@ -0,0 +1,890 @@
+// @bun
+// packages/cli/src/commands/browser.ts
+import { mkdirSync, rmSync } from "fs";
+import { resolve } from "path";
+import { spawn } from "child_process";
+import { emitKeypressEvents } from "readline";
+import { pathToFileURL } from "url";
+import * as clack2 from "@clack/prompts";
+import pc2 from "picocolors";
+
+// packages/cli/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
+import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+function takeFlag(args, flag) {
+  const rest = [];
+  let value = false;
+  for (const arg of args) {
+    if (arg === flag) {
+      value = true;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { value, rest };
+}
+function takeOption(args, option) {
+  const rest = [];
+  let value;
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === option) {
+      const next = args[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new CliError(`Missing value for ${option}`);
+      }
+      value = next;
+      index += 1;
+      continue;
+    }
+    if (current !== undefined) {
+      rest.push(current);
+    }
+  }
+  return { value, rest };
+}
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0) {
+    throw new CliError(`Unexpected arguments: ${args.join(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli/src/commands/browser.ts
+import { runCapture as runCapture2 } from "@rig/runtime/control-plane/native/utils";
+
+// packages/cli/src/commands/task-report-bug.ts
+import * as clack from "@clack/prompts";
+import pc from "picocolors";
+import {
+  appendJsonlRecord,
+  readJsonFile,
+  readJsonlFile,
+  writeJsonFile
+} from "@rig/runtime/control-plane/authority-files";
+import { runCapture, unique } from "@rig/runtime/control-plane/native/utils";
+
+// packages/cli/src/commands/_paths.ts
+import { resolveMonorepoRoot } from "@rig/runtime/control-plane/native/utils";
+
+// packages/cli/src/commands/task-report-bug.ts
+async function promptBugText(message, defaultValue, options = {}) {
+  const result = await clack.text({
+    message,
+    defaultValue: defaultValue?.trim() ? defaultValue : undefined,
+    placeholder: options.placeholder,
+    validate: options.required ? (value) => validateRequiredBugPromptValue(value, message) : undefined
+  });
+  return unwrapClackPrompt(result).trim();
+}
+function validateRequiredBugPromptValue(value, label) {
+  return value?.trim() ? undefined : `${label} is required.`;
+}
+async function promptBugConfirm(message, initialValue) {
+  const result = await clack.confirm({
+    message,
+    initialValue
+  });
+  return unwrapClackPrompt(result);
+}
+function unwrapClackPrompt(result) {
+  if (clack.isCancel(result)) {
+    clack.cancel("Bug report cancelled.");
+    throw new CliError2("Bug report cancelled by user.");
+  }
+  return result;
+}
+
+// packages/cli/src/commands/browser.ts
+function shouldColorizeCliOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+}
+function browserHelpText(options = {}) {
+  const c = pc2.createColors(options.color ?? shouldColorizeCliOutput());
+  const title = (value) => c.bold(c.cyan(value));
+  const section = (value) => c.bold(c.blue(value));
+  const command = (value) => c.green(value);
+  const code = (value) => c.yellow(`\`${value}\``);
+  return [
+    title("rig browser - Rig Browser workstation commands"),
+    "",
+    section("Purpose:"),
+    "  Rig Browser is the deterministic browser workstation for browser-heavy agent work.",
+    "  For hp-next it pins the app preset, persistent profile, state directory, and Chrome DevTools MCP port.",
+    "  Use it instead of ad hoc personal browser tabs for auth, routing, chunk-load, console, network, and visual debugging.",
+    "",
+    section("How agents use it inside a run:"),
+    `  Browser-required tasks get a Browser section in ${code("rig task info --task <id>")}.`,
+    `  The runtime writes browser metadata into ${code("runtime-context.json")}, exports ${code("RIG_BROWSER_*")} env vars,`,
+    "  and injects browser helper commands onto PATH. Agents should read this runtime contract instead",
+    "  of guessing app paths, profiles, or ports.",
+    "",
+    section("Recommended agent sequence:"),
+    `  ${command("rig-browser-launch")}`,
+    `  ${command("rig-browser-check")}`,
+    `  ${command("rig-browser-attach-info")}`,
+    `  ${command("npx chrome-devtools-mcp@latest --browser-url=$RIG_BROWSER_ATTACH_URL")}`,
+    "",
+    section("Runtime helper commands:"),
+    `  ${command("rig-browser-launch")}: Launches the task-resolved Rig Browser using the configured`,
+    "    launch command, profile, state dir, preset, and port. Use at the start of browser-required",
+    `    task work. Pass ${code("--dev")} when you need the dev/watch browser command.`,
+    `  ${command("rig-browser-check")}: Validates that the helper-launched browser exposes the expected CDP`,
+    "    endpoint. Use before attaching Chrome DevTools MCP or before blaming app code.",
+    `  ${command("rig-browser-attach-info")}: Prints the effective attach URL, profile, base profile, preset,`,
+    "    and state directory chosen for this runtime. Use this when sharing instructions or attaching",
+    "    MCP, because isolated runtimes may derive a profile/port from the base config.",
+    `  ${command("rig-browser-e2e")}: Runs the browser e2e command through the same workstation contract.`,
+    "    Use after a browser fix to validate the actual app-owned browser surface.",
+    `  ${command("rig-browser-reset-profile")}: Clears the effective browser profile. Use when stale cookies,`,
+    "    localStorage, auth state, or cache are suspected; do not use when the bug depends on persisted auth.",
+    "",
+    section("rig browser command family:"),
+    `  ${command("rig browser --help")}`,
+    `  ${command("rig browser explain")}`,
+    `  ${command("rig browser hp-next dev")}: Starts hp-next Rig Browser in dev/watch mode.`,
+    "    Use while implementing or debugging local frontend changes.",
+    `  ${command("rig browser hp-next start")}: Builds/starts the hp-next browser workstation without watch mode.`,
+    "    Use for stable manual verification or CI-like local checks.",
+    `  ${command("rig browser hp-next check")}: Validates the hp-next CDP endpoint on the configured port.`,
+    "    Use before MCP attach or after relaunching the browser.",
+    `  ${command("rig browser hp-next e2e")}: Runs hp-next browser e2e smoke checks through Rig Browser.`,
+    "    Use before handing off browser/auth/routing fixes.",
+    `  ${command("rig browser hp-next reset")}: Resets the hp-next browser profile.`,
+    "    Use when stale browser state is the suspected cause.",
+    `  ${command("rig browser demo")}: Launches a real guided agent/browser demo.`,
+    "    Use to experience the browser-required agent task workflow end to end.",
+    `  ${command("rig browser cdp-probe")}: Runs an isolated CDP attach/evaluate/layout probe.`,
+    "    Use to distinguish browser-workstation failure from hp-next app failure.",
+    `  ${command("rig browser profile-persistence")}: Verifies that a named profile persists browser state.`,
+    "    Use when debugging login/session persistence.",
+    `  ${command("rig browser profile-lock-check")}: Verifies concurrent launches reject the same profile.`,
+    "    Use when profile ownership or parallel agent collisions are suspected.",
+    `  ${command("rig browser smoke-test")}: Runs the browser package smoke test.`,
+    "    Use for a quick package-level workstation sanity check.",
+    "",
+    section("Repo script mapping:"),
+    `  ${command("rig browser hp-next dev")}: Runs ${code("bun run app:dev:browser:hp-next")}.`,
+    `  ${command("rig browser hp-next start")}: Runs ${code("bun run app:start:browser:hp-next")}.`,
+    `  ${command("rig browser hp-next check")}: Runs ${code("bun run app:check:browser:hp-next")}.`,
+    `  ${command("rig browser hp-next e2e")}: Runs ${code("bun run app:e2e:browser:hp-next")}.`,
+    `  ${command("rig browser hp-next reset")}: Runs ${code("bun run app:reset:browser:hp-next")}.`,
+    `  ${command("rig browser demo")}: Builds the browser, launches Electron, checks CDP, then attaches to the live page.`,
+    `  ${command("rig browser cdp-probe")}: Runs ${code("bun run --filter=@rig/browser cdp-probe")}.`,
+    `  ${command("rig browser profile-persistence")}: Runs ${code("bun run --filter=@rig/browser profile-persistence")}.`,
+    `  ${command("rig browser profile-lock-check")}: Runs ${code("bun run --filter=@rig/browser profile-lock-check")}.`,
+    `  ${command("rig browser smoke-test")}: Runs ${code("bun run --filter=@rig/browser smoke-test")}.`,
+    "",
+    section("hp-next defaults:"),
+    `  Local attach URL: ${code("http://127.0.0.1:9333")}`,
+    `  Local preset/profile: ${code("hp-next-local")}`,
+    `  Local state dir: ${code(".tmp/rig-browser/hp-next")}`,
+    "",
+    section("Chrome DevTools MCP:"),
+    `  ${command("npx chrome-devtools-mcp@latest --browser-url=http://127.0.0.1:9333")}`,
+    "",
+    section("Profiles:"),
+    "  A profile is the browser state bucket: cookies, localStorage, auth session, and cache.",
+    "  Use hp-next-local to preserve local auth, hp-next-shared for shared-dev, or a bug-specific",
+    "  profile such as bug-otp-auth when you need a clean/reproducible auth run.",
+    "",
+    section("First debug targets:"),
+    "  Inspect page URL/title, console errors, failed network requests, auth cookies/localStorage,",
+    "  route state, chunk requests, and responsive layout before changing app code."
+  ].join(`
+`);
+}
+function browserAgentUsageText() {
+  return browserHelpText();
+}
+function browserDemoHelpText(options = {}) {
+  const c = pc2.createColors(options.color ?? shouldColorizeCliOutput());
+  const section = (value) => c.bold(c.blue(value));
+  const command = (value) => c.green(value);
+  const code = (value) => c.yellow(`\`${value}\``);
+  return [
+    c.bold(c.cyan("rig browser demo - real agent/browser walkthrough")),
+    "",
+    section("What it does:"),
+    "  Places you in the agent's seat inside a browser-required task run.",
+    "  It launches a real Rig Browser window, exposes a real CDP endpoint,",
+    "  asks you to type the same simple commands an agent runs, then prints each command output.",
+    "  It attaches over the live Chrome DevTools Protocol endpoint and performs the same inspect/mutate workflow an agent uses.",
+    "",
+    section("Command:"),
+    `  ${command("rig browser demo")} ${code("[--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]")}`,
+    "",
+    section("Commands you will type:"),
+    `  ${command("rig-browser-attach-info")}`,
+    `  ${command("rig-browser-launch")}`,
+    `  ${command("rig-browser-check")}`,
+    `  ${command("npx chrome-devtools-mcp@latest --browser-url=$RIG_BROWSER_ATTACH_URL")}`,
+    "",
+    section("Real steps:"),
+    "  1. Prepare the demo runtime contract and build the browser bundle unless --no-build is passed.",
+    "  2. Ask you to type rig-browser-attach-info, then print the resolved runtime metadata.",
+    "  3. Ask you to type rig-browser-launch, then launch real Electron with RIG_BROWSER_* env vars.",
+    "  4. Ask you to type rig-browser-check, then check /json/version and /json/list on the live CDP endpoint.",
+    "  5. Ask you to type the DevTools MCP attach command, then run the live CDP inspect/update action.",
+    "",
+    section("Default endpoint:"),
+    "  http://127.0.0.1:9336"
+  ].join(`
+`);
+}
+function buildBrowserDemoRuntime(projectRoot, options = {}) {
+  const profile = options.profile || `agent-demo-${process.pid}`;
+  const port = options.port ?? 9336;
+  const stateDir = options.stateDir || `.tmp/rig-browser/${profile}`;
+  const targetUrl = options.targetUrl || buildBrowserDemoTargetUrl();
+  return {
+    attachUrl: `http://127.0.0.1:${port}`,
+    browserDir: resolve(projectRoot, "apps/native-app/apps/browser"),
+    env: {
+      RIG_BROWSER_DEV: "1",
+      RIG_STATE_DIR: stateDir,
+      T3CODE_STATE_DIR: stateDir,
+      RIG_BROWSER_PRESET: "hp-next-local",
+      RIG_BROWSER_PROFILE: profile,
+      RIG_BROWSER_REMOTE_DEBUGGING_PORT: String(port),
+      RIG_BROWSER_TARGET_URL: targetUrl
+    },
+    helperCommands: [
+      "rig-browser-launch",
+      "rig-browser-check",
+      "rig-browser-attach-info",
+      "rig-browser-e2e",
+      "rig-browser-reset-profile"
+    ],
+    port,
+    profile,
+    stateDir,
+    targetUrl
+  };
+}
+function buildBrowserDemoTargetUrl() {
+  const html = [
+    "<!doctype html>",
+    "<html>",
+    "<head>",
+    '<meta charset="utf-8">',
+    "<title>Rig Browser Agent Demo</title>",
+    "<style>",
+    "body{font-family:ui-sans-serif,system-ui;margin:48px;background:#f7efe3;color:#1f2933}",
+    ".card{max-width:760px;border:2px solid #1f2933;border-radius:20px;padding:28px;background:white;box-shadow:8px 8px 0 #1f2933}",
+    "#status{font-weight:700;color:#8a4b0f}",
+    "</style>",
+    "</head>",
+    "<body>",
+    '<main class="card">',
+    "<p>Rig Browser task run</p>",
+    "<h1>You are the agent now</h1>",
+    '<p id="status">Waiting for the agent to attach over CDP.</p>',
+    '<p id="details">The CLI will inspect this real page and then update it.</p>',
+    "</main>",
+    "<script>console.log('rig-browser-demo-page-ready')</script>",
+    "</body>",
+    "</html>"
+  ].join("");
+  return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`;
+}
+function buildBrowserDemoAgentCommands(runtime) {
+  const attachWithEnv = "npx chrome-devtools-mcp@latest --browser-url=$RIG_BROWSER_ATTACH_URL";
+  const attachWithUrl = `npx chrome-devtools-mcp@latest --browser-url=${runtime.attachUrl}`;
+  return {
+    attachInfo: {
+      primary: "rig-browser-attach-info",
+      accepted: ["rig-browser-attach-info"]
+    },
+    launch: {
+      primary: "rig-browser-launch",
+      accepted: ["rig-browser-launch"]
+    },
+    check: {
+      primary: "rig-browser-check",
+      accepted: ["rig-browser-check"]
+    },
+    attach: {
+      primary: attachWithEnv,
+      accepted: [attachWithEnv, attachWithUrl]
+    }
+  };
+}
+function normalizeBrowserDemoCommand(value) {
+  return value.trim().replace(/\s+/g, " ").replace(/--browser-url\s+/g, "--browser-url=").replace(/--browser-url\s*=\s*/g, "--browser-url=");
+}
+function browserDemoCommandMatches(value, command) {
+  const normalized = normalizeBrowserDemoCommand(value);
+  return command.accepted.map(normalizeBrowserDemoCommand).includes(normalized);
+}
+function browserDemoCommandCompletions(line, command) {
+  if (line.trim().length === 0) {
+    return [[command.primary], line];
+  }
+  const normalizedLine = normalizeBrowserDemoCommand(line);
+  const matches = command.accepted.filter((accepted) => normalizeBrowserDemoCommand(accepted).startsWith(normalizedLine));
+  return [matches.length > 0 ? matches : [command.primary], line];
+}
+function formatBrowserDemoCommandOutput(command, output) {
+  const normalizedOutput = output.trim() || "(no output)";
+  return `$ ${command}
+${normalizedOutput}`;
+}
+function printBrowserDemoCommandOutput(command, output) {
+  const c = pc2.createColors(shouldColorizeCliOutput());
+  console.log("");
+  console.log(c.bold("Agent terminal output"));
+  console.log(c.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(formatBrowserDemoCommandOutput(command, output));
+  console.log(c.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log("");
+}
+async function executeBrowser(context, args) {
+  const [command = "help", ...rest] = args;
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(browserHelpText());
+    return { ok: true, group: "browser", command: "help" };
+  }
+  if (command === "explain") {
+    requireNoExtraArgs(rest, "bun run rig browser explain");
+    console.log(browserAgentUsageText());
+    return { ok: true, group: "browser", command: "explain" };
+  }
+  if (command === "demo") {
+    return executeBrowserDemo(context, rest);
+  }
+  if (command === "app" || command === "hp-next") {
+    const appSlug = command === "hp-next" ? "hp-next" : process.env.RIG_BROWSER_APP?.trim() || "";
+    if (!appSlug) {
+      throw new CliError2(`rig browser app: set RIG_BROWSER_APP=<app-slug> to select which project app scripts to invoke.
+` + `Scripts are invoked as 'bun run app:<mode>:browser:<app-slug>'.
+
+${browserHelpText()}`);
+    }
+    const [subcommand = "help", ...appRest] = rest;
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+      console.log(browserHelpText());
+      return { ok: true, group: "browser", command: `${command}-help` };
+    }
+    const modes = ["dev", "start", "check", "e2e", "reset"];
+    if (!modes.includes(subcommand)) {
+      throw new CliError2(`Unknown browser ${command} command: ${subcommand}. Valid modes: ${modes.join(", ")}.
+
+${browserHelpText()}`);
+    }
+    requireNoExtraArgs(appRest, `bun run rig browser ${command} ${subcommand}`);
+    await context.runCommand(["bun", "run", `app:${subcommand}:browser:${appSlug}`]);
+    return { ok: true, group: "browser", command: `${command}-${subcommand}` };
+  }
+  const packageScripts = {
+    "cdp-probe": "cdp-probe",
+    "profile-persistence": "profile-persistence",
+    "profile-lock-check": "profile-lock-check",
+    "smoke-test": "smoke-test"
+  };
+  const packageScript = packageScripts[command];
+  if (packageScript) {
+    requireNoExtraArgs(rest, `bun run rig browser ${command}`);
+    await context.runCommand(["bun", "run", "--filter=@rig/browser", packageScript]);
+    return { ok: true, group: "browser", command };
+  }
+  throw new CliError2(`Unknown browser command: ${command}
+
+${browserHelpText()}`);
+}
+async function executeBrowserDemo(context, args) {
+  const [maybeHelp] = args;
+  if (maybeHelp === "help" || maybeHelp === "--help" || maybeHelp === "-h") {
+    console.log(browserDemoHelpText());
+    return { ok: true, group: "browser", command: "demo-help" };
+  }
+  let pending = args;
+  const portResult = takeOption(pending, "--port");
+  pending = portResult.rest;
+  const profileResult = takeOption(pending, "--profile");
+  pending = profileResult.rest;
+  const stateDirResult = takeOption(pending, "--state-dir");
+  pending = stateDirResult.rest;
+  const targetUrlResult = takeOption(pending, "--target-url");
+  pending = targetUrlResult.rest;
+  const keepOpenFlag = takeFlag(pending, "--keep-open");
+  pending = keepOpenFlag.rest;
+  const noBuildFlag = takeFlag(pending, "--no-build");
+  pending = noBuildFlag.rest;
+  requireNoExtraArgs(pending, "bun run rig browser demo [--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]");
+  if (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new CliError2("rig browser demo requires an interactive TTY in text mode.");
+  }
+  const port = portResult.value ? Number.parseInt(portResult.value, 10) : undefined;
+  if (port !== undefined && (!Number.isFinite(port) || port <= 0)) {
+    throw new CliError2(`Invalid --port value: ${portResult.value}`);
+  }
+  const runtime = buildBrowserDemoRuntime(context.projectRoot, {
+    ...port !== undefined ? { port } : {},
+    ...profileResult.value ? { profile: profileResult.value } : {},
+    ...stateDirResult.value ? { stateDir: stateDirResult.value } : {},
+    ...targetUrlResult.value ? { targetUrl: targetUrlResult.value } : {}
+  });
+  clack2.intro("rig browser demo");
+  clack2.note([
+    "You are now acting as the agent inside a browser-required task run.",
+    "Type each simple command when prompted. The CLI will run the real backing action",
+    "and print the same kind of output an agent would inspect before the next step."
+  ].join(`
+`), "Agent task-run walkthrough");
+  clack2.note(formatBrowserDemoRuntime(runtime), "Runtime contract the agent receives");
+  const agentCommands = buildBrowserDemoAgentCommands(runtime);
+  await promptBrowserDemoAgentCommand("Agent command 1/4: print browser attach info", agentCommands.attachInfo);
+  printBrowserDemoCommandOutput(agentCommands.attachInfo.primary, formatBrowserDemoAttachInfoOutput(runtime));
+  await promptBrowserDemoAgentCommand("Agent command 2/4: launch Rig Browser", agentCommands.launch);
+  if (!noBuildFlag.value) {
+    const spinner2 = clack2.spinner();
+    spinner2.start("Preparing browser bundle for the launch command");
+    try {
+      runBrowserDemoBuild(context.projectRoot);
+      spinner2.stop("Browser bundle built");
+    } catch (error) {
+      spinner2.error("Browser bundle build failed");
+      throw error;
+    }
+  }
+  const child = await launchBrowserDemo(runtime);
+  let keepOpen = keepOpenFlag.value;
+  try {
+    printBrowserDemoCommandOutput(agentCommands.launch.primary, formatBrowserDemoLaunchOutput(runtime, child.pid));
+    await promptBrowserDemoAgentCommand("Agent command 3/4: check live browser endpoint", agentCommands.check);
+    const readySpinner = clack2.spinner();
+    readySpinner.start(`Waiting for live CDP endpoint at ${runtime.attachUrl}`);
+    const { version, pageTarget, targets } = await waitForBrowserDemoReady(runtime, child);
+    readySpinner.stop("Live CDP endpoint is ready");
+    printBrowserDemoCommandOutput(agentCommands.check.primary, formatBrowserDemoCheckOutput(runtime, version, pageTarget, targets));
+    await promptBugText("Look at the launched browser page, then type ready", undefined, { required: true, placeholder: "ready" });
+    await promptBrowserDemoAgentCommand("Agent command 4/4: attach DevTools MCP", agentCommands.attach);
+    clack2.note([
+      "The attach step evaluates JavaScript inside the live browser page.",
+      "It records DOM state before the change, changes #status, #details, and the page background,",
+      "then records DOM state and layout again so the transcript proves what changed."
+    ].join(`
+`), "What mutationEvaluation means");
+    const cdpSpinner = clack2.spinner();
+    cdpSpinner.start("Agent attaching over WebSocket CDP");
+    const cdpResult = await runBrowserDemoCdpAction(pageTarget.webSocketDebuggerUrl);
+    cdpSpinner.stop("Agent CDP action completed");
+    printBrowserDemoCommandOutput(agentCommands.attach.primary, formatBrowserDemoCdpResult(cdpResult));
+    await promptBugConfirm("Did you see the page update after the agent action?", true);
+    if (!keepOpen) {
+      keepOpen = await promptBugConfirm("Keep the demo browser open after this command exits?", false);
+    }
+    clack2.outro(keepOpen ? "Demo complete. Browser left open by request." : "Demo complete. Closing browser.");
+    return {
+      ok: true,
+      group: "browser",
+      command: "demo",
+      details: {
+        attachUrl: runtime.attachUrl,
+        browser: version.Browser,
+        pageTitle: pageTarget.title,
+        profile: runtime.profile,
+        stateDir: runtime.stateDir,
+        cdpResult,
+        keptOpen: keepOpen
+      }
+    };
+  } finally {
+    if (!keepOpen) {
+      await stopBrowserDemo(child);
+    }
+  }
+}
+function formatBrowserDemoRuntime(runtime) {
+  return [
+    `RIG_BROWSER_ATTACH_URL=${runtime.attachUrl}`,
+    `RIG_BROWSER_PROFILE=${runtime.profile}`,
+    `RIG_BROWSER_STATE_DIR=${runtime.stateDir}`,
+    `RIG_BROWSER_REMOTE_DEBUGGING_PORT=${runtime.port}`,
+    `helpers=${runtime.helperCommands.join(", ")}`
+  ].join(`
+`);
+}
+function formatBrowserDemoAttachInfoOutput(runtime) {
+  return [
+    "Rig Browser",
+    "  Preset: hp-next-local",
+    "  Mode: persistent",
+    `  State dir: ${runtime.stateDir}`,
+    "  Default profile: hp-next-local",
+    `  Effective profile: ${runtime.profile}`,
+    `  Effective attach URL: ${runtime.attachUrl}`,
+    "  Launch helper: rig-browser-launch",
+    "  Check helper: rig-browser-check",
+    "  E2E helper: rig-browser-e2e",
+    "  Reset helper: rig-browser-reset-profile"
+  ].join(`
+`);
+}
+function formatBrowserDemoLaunchOutput(runtime, pid) {
+  return [
+    "Rig Browser launch requested.",
+    `  pid: ${pid ?? "(unknown)"}`,
+    `  profile: ${runtime.profile}`,
+    `  stateDir: ${runtime.stateDir}`,
+    `  attachUrl: ${runtime.attachUrl}`
+  ].join(`
+`);
+}
+function formatBrowserDemoCheckOutput(runtime, version, pageTarget, targets) {
+  return JSON.stringify({
+    attachUrl: runtime.attachUrl,
+    pageTarget,
+    targets,
+    version
+  }, null, 2);
+}
+function formatBrowserDemoCdpResult(result) {
+  return JSON.stringify({
+    title: result.title ?? null,
+    mutationExplanation: {
+      command: "Runtime.evaluate",
+      summary: "The agent executes JavaScript inside the live page through CDP, not against a mock.",
+      changes: [
+        "reads the DOM before mutation",
+        "changes #status, #details, and the page background",
+        "returns the browser-side mutation result",
+        "reads the DOM and layout again after mutation"
+      ],
+      payloadGuide: {
+        beforeDomState: "DOM state captured before Runtime.evaluate mutates the page.",
+        mutationEvaluation: "The exact Runtime.evaluate response returned by the browser-side mutation function.",
+        afterDomState: "DOM state captured after mutation to prove the page changed.",
+        consoleEvents: "Runtime.consoleAPICalled events observed during the attach session.",
+        layoutMetrics: "Full Page.getLayoutMetrics response from the live page."
+      }
+    },
+    beforeDomState: result.beforeDomState,
+    mutationEvaluation: result.mutationEvaluation,
+    afterDomState: result.afterDomState,
+    consoleEvents: result.consoleEvents,
+    layoutMetrics: result.layoutMetrics
+  }, null, 2);
+}
+function runBrowserDemoBuild(projectRoot) {
+  const result = runCapture2(["bun", "run", "--filter=@rig/browser", "build"], projectRoot);
+  if (result.exitCode !== 0) {
+    const details = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join(`
+`);
+    throw new CliError2(`Browser demo build failed.${details ? `
+${details}` : ""}`, result.exitCode);
+  }
+}
+async function promptBrowserDemoAgentCommand(message, command) {
+  for (;; ) {
+    const value = await readBrowserDemoAgentCommand(message, command);
+    if (browserDemoCommandMatches(value, command)) {
+      return normalizeBrowserDemoCommand(value);
+    }
+    clack2.log.warn(`Expected one of:
+${command.accepted.map((accepted) => `  ${accepted}`).join(`
+`)}`);
+  }
+}
+async function readBrowserDemoAgentCommand(message, command) {
+  const c = pc2.createColors(shouldColorizeCliOutput());
+  const alternatives = command.accepted.filter((accepted) => normalizeBrowserDemoCommand(accepted) !== normalizeBrowserDemoCommand(command.primary));
+  console.log("");
+  console.log(`${c.cyan("\u25C6")} ${c.bold(message)}`);
+  console.log(`  ${c.dim("Type the command, or press Tab to fill the placeholder:")}`);
+  console.log(`  ${c.dim(command.primary)}`);
+  if (alternatives.length > 0) {
+    console.log(`  ${c.dim("Also accepted:")}`);
+    for (const alternative of alternatives) {
+      console.log(`  ${c.dim(alternative)}`);
+    }
+  }
+  return readBrowserDemoCommandLine(command);
+}
+function readBrowserDemoCommandLine(command) {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = Boolean(stdin.isRaw);
+  let line = "";
+  const render = () => {
+    stdout.write(`\r\x1B[2K> ${line}`);
+  };
+  return new Promise((resolveInput, rejectInput) => {
+    const cleanup = () => {
+      stdin.off("keypress", onKeypress);
+      if (stdin.isTTY) {
+        stdin.setRawMode(wasRaw);
+      }
+    };
+    const completeLine = () => {
+      const [matches] = browserDemoCommandCompletions(line, command);
+      line = matches[0] ?? command.primary;
+      render();
+    };
+    const onKeypress = (characters, key) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        stdout.write(`
+`);
+        rejectInput(new CliError2("Browser demo cancelled."));
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        stdout.write(`
+`);
+        resolveInput(line);
+        return;
+      }
+      if (key.name === "tab") {
+        completeLine();
+        return;
+      }
+      if (key.name === "backspace") {
+        line = line.slice(0, -1);
+        render();
+        return;
+      }
+      if (key.ctrl && key.name === "u") {
+        line = "";
+        render();
+        return;
+      }
+      if (!key.ctrl && !key.meta && characters) {
+        line += characters;
+        render();
+      }
+    };
+    emitKeypressEvents(stdin);
+    stdin.resume();
+    stdin.on("keypress", onKeypress);
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+    render();
+  });
+}
+async function launchBrowserDemo(runtime) {
+  rmSync(resolve(runtime.browserDir, runtime.stateDir), { recursive: true, force: true });
+  mkdirSync(resolve(runtime.browserDir, runtime.stateDir), { recursive: true });
+  const launcherPath = resolve(runtime.browserDir, "scripts/electron-launcher.mjs");
+  const launcher = await import(pathToFileURL(launcherPath).href);
+  const electronPath = await launcher.resolveElectronPath();
+  const env = { ...process.env, ...runtime.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  const child = spawn(electronPath, ["dist-electron/main.js"], {
+    cwd: runtime.browserDir,
+    env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  child.stdout?.on("data", () => {});
+  child.stderr?.on("data", () => {});
+  return child;
+}
+async function waitForBrowserDemoReady(runtime, child) {
+  const version = await waitForBrowserDemo(() => fetchBrowserDemoJson(runtime, "/json/version"), child, "CDP /json/version");
+  const { targets, pageTarget } = await waitForBrowserDemo(async () => {
+    const nextTargets = await fetchBrowserDemoJson(runtime, "/json/list");
+    const nextPageTarget = findBrowserDemoPageTarget(runtime, nextTargets);
+    if (!nextPageTarget) {
+      throw new Error("demo page target is not ready yet");
+    }
+    return { targets: nextTargets, pageTarget: nextPageTarget };
+  }, child, "CDP demo page target");
+  if (!version.Browser) {
+    throw new CliError2("Browser demo reached CDP but /json/version did not include Browser metadata.");
+  }
+  return { version, targets, pageTarget };
+}
+function findBrowserDemoPageTarget(runtime, targets) {
+  const attachableTargets = targets.filter((target) => target.type === "page" && typeof target.webSocketDebuggerUrl === "string");
+  return attachableTargets.find((target) => target.url === runtime.targetUrl && target.title === "Rig Browser Agent Demo") ?? attachableTargets.find((target) => target.title === "Rig Browser Agent Demo") ?? null;
+}
+async function waitForBrowserDemo(check, child, label, timeoutMs = 18000) {
+  const startedAt = Date.now();
+  let lastError = null;
+  for (;; ) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      throw new CliError2(`Rig Browser exited before ${label} became ready.`);
+    }
+    try {
+      return await check();
+    } catch (error) {
+      lastError = error;
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new CliError2(`${label} did not become ready within ${timeoutMs}ms: ${String(lastError)}`);
+      }
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
+    }
+  }
+}
+async function fetchBrowserDemoJson(runtime, path) {
+  const response = await fetch(`${runtime.attachUrl}${path}`);
+  if (!response.ok) {
+    throw new Error(`${path} returned ${response.status}`);
+  }
+  return response.json();
+}
+async function runBrowserDemoCdpAction(wsUrl) {
+  return withBrowserDemoCdpSession(wsUrl, async ({ send, consoleEvents }) => {
+    await send("Runtime.enable");
+    await send("Page.enable");
+    const beforeDomState = await send("Runtime.evaluate", {
+      expression: [
+        "(() => ({",
+        "title: document.title,",
+        "status: document.querySelector('#status')?.textContent ?? null,",
+        "details: document.querySelector('#details')?.textContent ?? null,",
+        "bodyBackground: getComputedStyle(document.body).backgroundColor,",
+        "url: location.href",
+        "}))()"
+      ].join(""),
+      returnByValue: true
+    });
+    if (beforeDomState.exceptionDetails) {
+      throw new Error(`Runtime.evaluate before state failed: ${JSON.stringify(beforeDomState)}`);
+    }
+    const mutationEvaluation = await send("Runtime.evaluate", {
+      expression: [
+        "(() => {",
+        "console.log('rig-browser-demo-agent-action');",
+        "const status = document.querySelector('#status');",
+        "const details = document.querySelector('#details');",
+        "if (status) status.textContent='Agent CDP command executed.';",
+        "if (details) details.textContent='The CLI attached over the live browser debugging endpoint and changed this page.';",
+        "document.body.style.background='#e4f7ea';",
+        "return {",
+        "title: document.title,",
+        "status: status?.textContent ?? null,",
+        "details: details?.textContent ?? null,",
+        "bodyBackground: getComputedStyle(document.body).backgroundColor,",
+        "url: location.href",
+        "};",
+        "})()"
+      ].join(""),
+      returnByValue: true
+    });
+    if (mutationEvaluation.exceptionDetails) {
+      throw new Error(`Runtime.evaluate mutation failed: ${JSON.stringify(mutationEvaluation)}`);
+    }
+    const afterDomState = await send("Runtime.evaluate", {
+      expression: [
+        "(() => ({",
+        "title: document.title,",
+        "status: document.querySelector('#status')?.textContent ?? null,",
+        "details: document.querySelector('#details')?.textContent ?? null,",
+        "bodyBackground: getComputedStyle(document.body).backgroundColor,",
+        "url: location.href",
+        "}))()"
+      ].join(""),
+      returnByValue: true
+    });
+    if (afterDomState.exceptionDetails) {
+      throw new Error(`Runtime.evaluate after state failed: ${JSON.stringify(afterDomState)}`);
+    }
+    const layoutMetrics = await send("Page.getLayoutMetrics");
+    return {
+      afterDomState,
+      beforeDomState,
+      consoleEvents,
+      layoutMetrics,
+      mutationEvaluation,
+      title: afterDomState.result?.value?.title ?? mutationEvaluation.result?.value?.title
+    };
+  });
+}
+async function withBrowserDemoCdpSession(wsUrl, run) {
+  const socket = new WebSocket(wsUrl);
+  const pending = new Map;
+  const consoleEvents = [];
+  let nextId = 1;
+  const send = (method, params = {}) => new Promise((resolveSend, rejectSend) => {
+    const id = nextId;
+    nextId += 1;
+    pending.set(id, {
+      method,
+      reject: rejectSend,
+      resolve: (value) => resolveSend(value),
+      timeout: setTimeout(() => {
+        pending.delete(id);
+        rejectSend(new Error(`${method} timed out waiting for CDP response`));
+      }, 5000)
+    });
+    socket.send(JSON.stringify({ id, method, params }));
+  });
+  socket.addEventListener("message", (event) => {
+    const message = JSON.parse(String(event.data));
+    if (message.id !== undefined) {
+      const request = pending.get(message.id);
+      if (!request)
+        return;
+      pending.delete(message.id);
+      clearTimeout(request.timeout);
+      if (message.error) {
+        request.reject(new Error(`${request.method} failed: ${JSON.stringify(message.error)}`));
+        return;
+      }
+      request.resolve(message.result);
+      return;
+    }
+    if (message.method === "Runtime.consoleAPICalled") {
+      consoleEvents.push(message.params);
+    }
+  });
+  socket.addEventListener("close", () => {
+    for (const request of pending.values()) {
+      clearTimeout(request.timeout);
+      request.reject(new Error(`CDP WebSocket closed before ${request.method} completed`));
+    }
+    pending.clear();
+  }, { once: true });
+  await new Promise((resolveOpen, rejectOpen) => {
+    const timeout = setTimeout(() => rejectOpen(new Error("CDP WebSocket failed to open within 5000ms")), 5000);
+    socket.addEventListener("open", () => resolveOpen(), { once: true });
+    socket.addEventListener("error", () => rejectOpen(new Error("CDP WebSocket failed to open")), { once: true });
+    socket.addEventListener("open", () => clearTimeout(timeout), { once: true });
+    socket.addEventListener("error", () => clearTimeout(timeout), { once: true });
+  });
+  try {
+    return await run({ consoleEvents, send });
+  } finally {
+    socket.close();
+    await new Promise((resolveClose) => {
+      socket.addEventListener("close", resolveClose, { once: true });
+      setTimeout(resolveClose, 500);
+    });
+  }
+}
+async function stopBrowserDemo(child) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+  child.kill("SIGTERM");
+  await Promise.race([
+    new Promise((resolveExit) => child.once("exit", resolveExit)),
+    new Promise((resolveDelay) => setTimeout(resolveDelay, 2000))
+  ]);
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill("SIGKILL");
+  }
+}
+export {
+  normalizeBrowserDemoCommand,
+  formatBrowserDemoCommandOutput,
+  formatBrowserDemoCheckOutput,
+  formatBrowserDemoCdpResult,
+  findBrowserDemoPageTarget,
+  executeBrowserDemo,
+  executeBrowser,
+  buildBrowserDemoRuntime,
+  buildBrowserDemoAgentCommands,
+  browserHelpText,
+  browserDemoCommandMatches,
+  browserDemoCommandCompletions
+};