browxai 0.7.0

package/dist/cli/doctor.js

@@ -0,0 +1,407 @@
+// `browxai doctor` — environment + connectivity health-check ().
+//
+// Prints a ✓/✗ checklist + one-line fix per failing check (− marks purely
+// informational rows). Exits 0 iff everything passes, 1 otherwise. Writes to
+// stdout (this is a CLI subcommand, not the MCP server — stdout is fine here).
+import { existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveCapabilities, resolveConfirmHooks, DEFAULT_CAPABILITIES, } from "../util/capabilities.js";
+import { resolveConfig } from "../util/config.js";
+import { resolveOriginPolicy, describePolicy } from "../policy/origin.js";
+import { resolveWorkspace } from "../util/workspace.js";
+import { ConfigStore } from "../util/config-store.js";
+import { pluginChecks } from "./doctor-plugins.js";
+import { IMPLEMENTED_ENGINES, AndroidCdpAdapter, defaultAdbRunner, defaultFetcher, pickFreePort, forwardArgs, forwardRemoveArgs, versionUrl, extractWsUrl, resolveEngineSelection, UnknownEngineError, } from "../engine/index.js";
+export async function runDoctor() {
+    const checks = [];
+    // 1. dist/cli.js built?
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const distCli = resolve(__dirname, "../cli.js");
+    if (existsSync(distCli)) {
+        const age = Math.floor((Date.now() - statSync(distCli).mtimeMs) / 86_400_000);
+        checks.push({ name: "build", ok: true, detail: `dist/cli.js exists (${age}d old)` });
+    }
+    else {
+        checks.push({
+            name: "build",
+            ok: false,
+            detail: `dist/cli.js missing at ${distCli}`,
+            fix: "run `pnpm build`",
+        });
+    }
+    // 2. $BROWX_WORKSPACE writable?
+    try {
+        const ws = resolveWorkspace();
+        const probe = ws.sub("doctor-probe");
+        if (existsSync(probe)) {
+            checks.push({ name: "workspace", ok: true, detail: `${ws.root} (writable)` });
+        }
+        else {
+            checks.push({
+                name: "workspace",
+                ok: false,
+                detail: `${ws.root} couldn't create subdir`,
+                fix: "check permissions; set BROWX_WORKSPACE to a writable dir",
+            });
+        }
+    }
+    catch (e) {
+        checks.push({
+            name: "workspace",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "set BROWX_WORKSPACE to an absolute path you own",
+        });
+    }
+    // 3. BROWX_TEST_ATTRIBUTES configured (default or explicit).
+    const config = resolveConfig();
+    const explicit = !!process.env.BROWX_TEST_ATTRIBUTES;
+    checks.push({
+        name: "test-attrs",
+        ok: true,
+        detail: `${config.testAttributes.join(",")}${explicit ? " (BROWX_TEST_ATTRIBUTES set)" : " (default)"}`,
+        fix: explicit
+            ? undefined
+            : "set BROWX_TEST_ATTRIBUTES if your codebase uses non-default conventions (e.g. add `data-type`)",
+    });
+    // 4. BROWX_ATTACH_CDP — if set, can we reach it?
+    const cdpEnv = process.env.BROWX_ATTACH_CDP?.trim();
+    if (cdpEnv) {
+        const reachable = await probeCdp(cdpEnv);
+        checks.push({
+            name: "cdp-attach",
+            ok: reachable.ok,
+            detail: reachable.ok
+                ? `${cdpEnv} reachable — ${reachable.version}`
+                : `${cdpEnv} unreachable (${reachable.error})`,
+            fix: reachable.ok
+                ? undefined
+                : "start a Chrome at this port — `browxai chrome start` or `chrome --remote-debugging-port=9222 …`",
+        });
+    }
+    else {
+        // Not configured. Probe the default port anyway — adopters with a Chrome
+        // already running may want to be told "you could attach to that, you know."
+        const reachable = await probeCdp("http://127.0.0.1:9222");
+        if (reachable.ok) {
+            checks.push({
+                name: "cdp-attach",
+                ok: true,
+                detail: `BROWX_ATTACH_CDP unset, but a Chrome is reachable at 127.0.0.1:9222 (${reachable.version}). Use the \`browxai-attached\` MCP entry to attach.`,
+            });
+        }
+        else {
+            checks.push({
+                name: "cdp-attach",
+                ok: true,
+                detail: "BROWX_ATTACH_CDP unset — managed-mode default. No --cdp Chrome to attach to.",
+            });
+        }
+    }
+    // 5. Capabilities ( security model).
+    let enabledCapabilities = new Set(DEFAULT_CAPABILITIES);
+    try {
+        const c = resolveCapabilities();
+        enabledCapabilities = c.enabled;
+        const explicit = !!process.env.BROWX_CAPABILITIES;
+        const dangerous = [...c.enabled].filter((x) => x === "eval" || x === "byob-attach");
+        const detail = `enabled=[${[...c.enabled].join(", ")}]${explicit ? "" : " (default)"}${dangerous.length ? "  ⚠ dangerous: " + dangerous.join(", ") : ""}`;
+        checks.push({
+            name: "capabilities",
+            ok: true,
+            detail,
+            fix: dangerous.length
+                ? `${dangerous.join(",")} on — page text remains untrusted; review docs/threat-model.md`
+                : explicit
+                    ? undefined
+                    : "see docs/threat-model.md for the full set; default is " +
+                        DEFAULT_CAPABILITIES.join(","),
+        });
+    }
+    catch (e) {
+        checks.push({
+            name: "capabilities",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "fix BROWX_CAPABILITIES (comma-separated, see docs/threat-model.md)",
+        });
+    }
+    // 6. Confirm-required hooks.
+    try {
+        const hooks = resolveConfirmHooks();
+        checks.push({
+            name: "confirm-hooks",
+            ok: true,
+            detail: hooks.size > 0 ? `[${[...hooks].join(", ")}]` : "(none)",
+        });
+    }
+    catch (e) {
+        checks.push({
+            name: "confirm-hooks",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "fix BROWX_CONFIRM_REQUIRED — see docs/threat-model.md",
+        });
+    }
+    // 7. Origin policy.
+    try {
+        const policy = resolveOriginPolicy();
+        const noAllowlist = policy.allowed.length === 0;
+        checks.push({
+            name: "origins",
+            ok: true,
+            detail: describePolicy(policy),
+            fix: noAllowlist
+                ? "no allowlist set — defense-in-depth not engaged. Set BROWX_ALLOWED_ORIGINS for the navigation gate."
+                : undefined,
+        });
+    }
+    catch (e) {
+        checks.push({
+            name: "origins",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "BROWX_ALLOWED_ORIGINS / BROWX_BLOCKED_ORIGINS: comma-separated absolute URLs (https://app.example.com or https://*.example.com)",
+        });
+    }
+    // 8. Chromium installed (managed-mode dependency).
+    try {
+        // Lazy import so this command doesn't pay the playwright-core cost on bare invocation.
+        const { chromium } = await import("playwright-core");
+        const path = chromium.executablePath();
+        if (path && existsSync(path)) {
+            checks.push({ name: "chromium", ok: true, detail: `${path}` });
+        }
+        else {
+            checks.push({
+                name: "chromium",
+                ok: false,
+                detail: "playwright-core has no Chromium binary cached",
+                fix: "run `pnpm install-browser`",
+            });
+        }
+    }
+    catch (e) {
+        checks.push({
+            name: "chromium",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "run `pnpm install` and `pnpm install-browser`",
+        });
+    }
+    // 8a2. Firefox binary (opt-in second engine — `browserType:"firefox"`).
+    // Informational: Firefox is opt-in, so a missing binary never FAILS doctor —
+    // it just tells the operator how to enable the engine. Mirrors the Chromium
+    // check above but against the Firefox build (Playwright's bundled Juggler).
+    try {
+        const { firefox } = await import("playwright-core");
+        const path = firefox.executablePath();
+        if (path && existsSync(path)) {
+            checks.push({ name: "firefox", ok: true, info: true, detail: `${path}` });
+        }
+        else {
+            checks.push({
+                name: "firefox",
+                ok: true,
+                info: true,
+                detail: 'not installed (opt-in second engine — browserType:"firefox")',
+                fix: "run `npx playwright install firefox` to enable the firefox engine",
+            });
+        }
+    }
+    catch (e) {
+        checks.push({
+            name: "firefox",
+            ok: true,
+            info: true,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "run `npx playwright install firefox` to enable the firefox engine",
+        });
+    }
+    // 8a3. WebKit binary (opt-in third engine — `browserType:"webkit"`).
+    // Informational: WebKit is opt-in, so a missing binary never FAILS doctor —
+    // it just tells the operator how to enable the engine. Mirrors the Chromium +
+    // Firefox checks above but against the WebKit build (Playwright's bundled
+    // WebKit — the WebKit-engine correctness lane, NOT Safari).
+    try {
+        const { webkit } = await import("playwright-core");
+        const path = webkit.executablePath();
+        if (path && existsSync(path)) {
+            checks.push({ name: "webkit", ok: true, info: true, detail: `${path}` });
+        }
+        else {
+            checks.push({
+                name: "webkit",
+                ok: true,
+                info: true,
+                detail: 'not installed (opt-in third engine — browserType:"webkit")',
+                fix: "run `npx playwright install webkit` to enable the webkit engine",
+            });
+        }
+    }
+    catch (e) {
+        checks.push({
+            name: "webkit",
+            ok: true,
+            info: true,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "run `npx playwright install webkit` to enable the webkit engine",
+        });
+    }
+    // 8a4. Android availability (opt-in fourth engine — `browserType:"android"`).
+    // The full-fidelity real-profile BYOB lane: real Chrome-on-Android over adb +
+    // CDP. Informational — Android is opt-in + needs a physically
+    // connected device, so a missing adb / no device / closed Chrome NEVER fails
+    // doctor; it just reports how far the chain reaches (adb present → device ready
+    // → Chrome socket reachable). Probes without opening a session: lists devices,
+    // and if one is ready, forwards the socket + probes /json/version, then removes
+    // the forward.
+    checks.push(await androidCheck());
+    // 8b. SELECTED browser engine. Resolves the operator's choice exactly as the
+    // MCP server does: explicit `--engine <kind>` > `BROWX_ENGINE` env > default
+    // chromium (see src/engine/select.ts). Reports which engine the server WOULD
+    // run on, and points at the per-engine availability row above (chromium /
+    // firefox / webkit / android — those checks always run) so the operator can see
+    // the selected engine's readiness in one glance. Chromium + Firefox + WebKit +
+    // Android are wired; the seam lets each engine be an adapter (see src/engine/).
+    // An invalid selection is reported here (and never fails doctor — it's the same
+    // structured "implemented engines: …" message the server prints, surfaced as a
+    // ✗ so the operator sees it). Informational otherwise.
+    let selectedEngine = "chromium";
+    let engineSelectionError;
+    try {
+        selectedEngine = resolveEngineSelection(process.argv.slice(2)) ?? "chromium";
+    }
+    catch (e) {
+        engineSelectionError =
+            e instanceof UnknownEngineError ? e.message : e instanceof Error ? e.message : String(e);
+    }
+    if (engineSelectionError) {
+        checks.push({
+            name: "engine",
+            ok: false,
+            detail: engineSelectionError,
+            fix: `set BROWX_ENGINE (or --engine) to one of: ${IMPLEMENTED_ENGINES.join(", ")}`,
+        });
+    }
+    else {
+        const explicit = !!process.env.BROWX_ENGINE?.trim() ||
+            process.argv.slice(2).some((a) => a === "--engine" || a.startsWith("--engine="));
+        // The availability row matching the selected engine ran above (chromium ✓,
+        // firefox/webkit/android −). Name it so doctor's engine line is self-contained.
+        const readinessRow = selectedEngine === "chromium"
+            ? "see `chromium` row above"
+            : `see \`${selectedEngine}\` row above`;
+        checks.push({
+            name: "engine",
+            ok: true,
+            info: true,
+            detail: `${selectedEngine}${explicit ? "" : " (default)"} — ${readinessRow}; ` +
+                `implemented: ${IMPLEMENTED_ENGINES.join(", ")}`,
+        });
+    }
+    // 9. Plugins — declaration / install drift / lock health / manifest
+    // sanity. Pure inspection of the same files the runtime's resolution
+    // stage reads; doctor NEVER executes a plugin's register module.
+    try {
+        const ws = resolveWorkspace();
+        const store = new ConfigStore(ws.root);
+        checks.push(...pluginChecks({
+            workspaceRoot: ws.root,
+            enabledCapabilities,
+            extraDeclared: store.resolve().plugins,
+        }));
+    }
+    catch (e) {
+        checks.push({
+            name: "plugins",
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+            fix: "inspect <workspace>/plugins.json, plugins-lock.json and plugins/node_modules/ by hand",
+        });
+    }
+    // Print + exit.
+    let allOk = true;
+    process.stdout.write("browxai doctor — environment & connectivity\n\n");
+    for (const c of checks) {
+        if (!c.ok)
+            allOk = false;
+        const glyph = c.info ? "−" : c.ok ? "✓" : "✗";
+        process.stdout.write(`  ${glyph} ${c.name.padEnd(12)} ${c.detail}\n`);
+        if (!c.ok && c.fix)
+            process.stdout.write(`    fix: ${c.fix}\n`);
+    }
+    process.stdout.write(`\n${allOk ? "all checks passed" : "fix the ✗ items above"}\n`);
+    return allOk ? 0 : 1;
+}
+// Android availability — how far the adb + CDP chain reaches, without opening a
+// session. adb present? → a device ready? → the Chrome DevTools socket
+// reachable? Always informational (Android is opt-in + device-gated). The probe
+// forwards the socket to a transient loopback port, GETs /json/version, then
+// removes the forward — no session, no leaked forward.
+async function androidCheck() {
+    const name = "android";
+    const adapter = new AndroidCdpAdapter();
+    let serial;
+    try {
+        serial = await adapter.discoverDevice(process.env.BROWX_ANDROID_SERIAL?.trim() || undefined);
+    }
+    catch (e) {
+        // adb-missing / no-device / ambiguous — report the structured message's first
+        // clause; never fails doctor.
+        const msg = e instanceof Error ? e.message.split(".")[0] : String(e);
+        return {
+            name,
+            ok: true,
+            info: true,
+            detail: `${msg} (opt-in BYOB lane — browserType:"android")`,
+            fix: "connect an Android phone over USB, enable USB debugging, open Chrome",
+        };
+    }
+    // Device ready — try to reach the Chrome socket so the operator knows whether
+    // Chrome is open + web-debugging is on.
+    let localPort = 0;
+    try {
+        localPort = await pickFreePort();
+        await defaultAdbRunner(forwardArgs(localPort, serial));
+        const body = await defaultFetcher(versionUrl(localPort));
+        extractWsUrl(body);
+        const browser = body.Browser ?? "unknown";
+        return {
+            name,
+            ok: true,
+            info: true,
+            detail: `device ${serial} ready, Chrome reachable (${browser}) — browserType:"android" attach-ready`,
+        };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message.split(".")[0] : String(e);
+        return {
+            name,
+            ok: true,
+            info: true,
+            detail: `device ${serial} ready but Chrome socket not reachable: ${msg}`,
+            fix: "open Chrome on the device + enable USB web-debugging (chrome://inspect should list its tabs)",
+        };
+    }
+    finally {
+        if (localPort) {
+            await defaultAdbRunner(forwardRemoveArgs(localPort, serial)).catch(() => undefined);
+        }
+    }
+}
+async function probeCdp(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        const probeUrl = `${url.origin}/json/version`;
+        const res = await fetch(probeUrl, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok)
+            return { ok: false, error: `HTTP ${res.status}` };
+        const body = (await res.json());
+        return { ok: true, version: body.Browser ?? "unknown" };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(args: string[]): Promise<number>;

package/dist/cli/init.js

@@ -0,0 +1,200 @@
+// `browxai init <workspace>` — bootstrap a per-app workspace ().
+//
+// Creates `<workspace>/.browxai/` (the consumer-co-located `BROWX_WORKSPACE`),
+// emits a workspace-scope `.mcp.json` snippet the user can drop into their MCP
+// client, and (if the workspace has a sibling source tree) heuristically sniffs
+// the most-used test attribute convention so the printed `BROWX_TEST_ATTRIBUTES`
+// order is right out of the gate.
+//
+// Stdout is fine — CLI subcommand.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function runInit(args) {
+    const opts = parseArgs(args);
+    if (!opts) {
+        process.stderr.write("usage: browxai init <workspace> [--test-attrs data-testid,data-type,...] [--no-write]\n" +
+            "  <workspace>  per-app dir to host browxai state (e.g. ~/site-docs/<app>)\n" +
+            "  --no-write   print the .mcp.json snippet without creating files\n");
+        return Promise.resolve(2);
+    }
+    const workspace = resolve(opts.workspace);
+    const browxDir = join(workspace, ".browxai");
+    // Sniff test attrs (if not explicit).
+    let testAttrs = opts.testAttrs;
+    let sniffNote = "";
+    if (!testAttrs) {
+        const sniffed = sniffTestAttributes(workspace);
+        testAttrs = sniffed.attrs.join(",");
+        sniffNote = sniffed.note;
+    }
+    // Resolve the browxai dist/cli.js path (this script's repo).
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const distCli = resolve(__dirname, "../cli.js");
+    const mcpJson = {
+        mcpServers: {
+            browxai: {
+                command: "node",
+                args: [distCli],
+                env: {
+                    BROWX_WORKSPACE: browxDir,
+                    BROWX_TEST_ATTRIBUTES: testAttrs,
+                },
+            },
+            "browxai-attached": {
+                command: "node",
+                args: [distCli],
+                env: {
+                    BROWX_WORKSPACE: browxDir,
+                    BROWX_ATTACH_CDP: "http://127.0.0.1:9222",
+                    BROWX_TEST_ATTRIBUTES: testAttrs,
+                },
+            },
+        },
+    };
+    const mcpJsonText = JSON.stringify(mcpJson, null, 2);
+    process.stdout.write(`browxai init — bootstrap workspace at ${workspace}\n\n`);
+    if (!opts.noWrite) {
+        if (!existsSync(browxDir)) {
+            mkdirSync(browxDir, { recursive: true });
+            process.stdout.write(`  ✓ created ${browxDir}\n`);
+        }
+        else {
+            process.stdout.write(`  ✓ ${browxDir} already exists\n`);
+        }
+        const mcpPath = join(workspace, ".mcp.json");
+        if (existsSync(mcpPath)) {
+            process.stdout.write(`  ⚠  ${mcpPath} exists — printing snippet below; merge manually so no existing entries are clobbered\n`);
+        }
+        else {
+            writeFileSync(mcpPath, mcpJsonText + "\n", "utf8");
+            process.stdout.write(`  ✓ wrote ${mcpPath} (workspace-scope MCP config)\n`);
+        }
+    }
+    process.stdout.write(`\ntest-attributes order: ${testAttrs}\n`);
+    if (sniffNote)
+        process.stdout.write(`  ${sniffNote}\n`);
+    process.stdout.write(`\n.mcp.json snippet (workspace-scope; pair with \`claude mcp add-json -s user\` for user-scope):\n\n${mcpJsonText}\n\n`);
+    process.stdout.write(`next steps:\n  1) open Claude Code with cwd=${workspace} so this .mcp.json is picked up\n` +
+        `  2) (BYOB) \`browxai chrome start\` to launch the attachable Chrome\n` +
+        `  3) use the \`browxai\` MCP server for managed mode, \`browxai-attached\` for BYOB\n`);
+    return Promise.resolve(0);
+}
+function parseArgs(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h")
+        return null;
+    const positional = [];
+    let testAttrs;
+    let noWrite = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--test-attrs") {
+            testAttrs = args[++i];
+            continue;
+        }
+        if (a === "--no-write") {
+            noWrite = true;
+            continue;
+        }
+        positional.push(a);
+    }
+    if (positional.length !== 1)
+        return null;
+    return { workspace: positional[0], testAttrs, noWrite };
+}
+/**
+ * Sniff a consumer codebase for which `data-*` attribute is dominant. Looks at
+ * the workspace's parent dir (typical layout: `~/site-docs/<app>/` and
+ * `~/Projects/<app>/`) for `src/` and counts occurrences of each conventional
+ * test attribute in `.ts` / `.tsx` / `.js` / `.jsx` files. Returns the attrs in
+ * descending frequency order (most-used first — `BROWX_TEST_ATTRIBUTES` is
+ * first-match-wins so the dominant convention should lead).
+ *
+ * Best-effort and bounded: walks at most 200 source files.
+ */
+function sniffTestAttributes(workspace) {
+    const KNOWN = ["data-testid", "data-type", "data-test", "data-cy", "data-qa", "data-test-id"];
+    const counts = new Map(KNOWN.map((a) => [a, 0]));
+    const candidates = [
+        workspace, // in case workspace itself is a code repo
+        join(workspace, "../"), // parent: typical sibling layout
+        join(workspace, "src"),
+        join(workspace, "../src"),
+    ].filter((d) => existsSync(d));
+    if (candidates.length === 0) {
+        return { attrs: KNOWN.slice(0, 5), note: "(no sibling code dir found; default order)" };
+    }
+    let scanned = 0;
+    for (const root of candidates) {
+        walk(root, 4, (file) => {
+            if (scanned >= 200)
+                return false;
+            if (!/\.(t|j)sx?$/.test(file))
+                return true;
+            scanned++;
+            try {
+                const text = readFileSync(file, "utf8");
+                for (const a of KNOWN) {
+                    const re = new RegExp(`${a}=`, "g");
+                    const m = text.match(re);
+                    if (m)
+                        counts.set(a, (counts.get(a) ?? 0) + m.length);
+                }
+            }
+            catch {
+                /* unreadable file — skip */
+            }
+            return true;
+        });
+        if (scanned >= 200)
+            break;
+    }
+    const totalHits = [...counts.values()].reduce((a, b) => a + b, 0);
+    if (totalHits === 0) {
+        return {
+            attrs: KNOWN.slice(0, 5),
+            note: "(scanned but found 0 conventional attrs; default order)",
+        };
+    }
+    const sorted = [...counts.entries()]
+        .sort(([a, av], [b, bv]) => bv - av || KNOWN.indexOf(a) - KNOWN.indexOf(b))
+        .filter(([, v]) => v > 0)
+        .map(([k]) => k);
+    // Always keep `data-testid` as a fallback so consumers with mixed conventions don't lose it.
+    if (!sorted.includes("data-testid"))
+        sorted.push("data-testid");
+    const summary = [...counts.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => `${k}×${v}`)
+        .join(", ");
+    return { attrs: sorted, note: `(sniffed ${scanned} source file(s); hits: ${summary})` };
+}
+function walk(dir, maxDepth, visit) {
+    if (maxDepth < 0)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (e === "node_modules" || e === ".git" || e === "dist" || e.startsWith("."))
+            continue;
+        const full = join(dir, e);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walk(full, maxDepth - 1, visit);
+        else if (st.isFile()) {
+            if (!visit(full))
+                return;
+        }
+    }
+}

package/dist/cli/register-commands.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/register-commands.js

@@ -0,0 +1,22 @@
+// CLI subcommand registrations (RFC 0004 P4 / D6) — the one place the
+// extensibility subcommands are wired into the registry. Importing this module
+// for its side effect populates `command-registry.ts`'s map; `cli.ts` then
+// dispatches through `commandFor(subcommand)` instead of a `switch`.
+//
+// Adding a subcommand is add-only: write its `runXxx(rest)` handler, then add a
+// single `registerCommand("xxx", runXxx)` line here — no edit to the dispatch in
+// `cli.ts`. Each registration binds the SAME handler the old `case` invoked, so
+// the dispatch is byte-identical.
+import { registerCommand } from "./command-registry.js";
+import { runDoctor } from "./doctor.js";
+import { runChrome } from "./chrome.js";
+import { runInit } from "./init.js";
+import { runServe } from "./serve.js";
+import { runPlugin } from "../plugin/cli.js";
+// `runDoctor` takes no argv (it ignored `rest`); the others consume `rest`.
+// `runPlugin` accepts a `ReadonlyArray<string>`, which `string[]` satisfies.
+registerCommand("doctor", () => runDoctor());
+registerCommand("chrome", (rest) => runChrome(rest));
+registerCommand("init", (rest) => runInit(rest));
+registerCommand("serve", (rest) => runServe(rest));
+registerCommand("plugin", (rest) => runPlugin(rest));

package/dist/cli/serve.d.ts

@@ -0,0 +1,14 @@
+import { type Server } from "node:net";
+interface ServeOptions {
+    readonly socketPath: string;
+    readonly attachCdp?: string;
+    readonly headless?: boolean;
+}
+export declare function runServe(rawArgs: string[]): Promise<number>;
+/** Exposed for tests — programmatic `browxai serve` startup that returns the
+ *  underlying net.Server so a test can `close()` it cleanly. */
+export declare function startServeForTests(opts: ServeOptions): Promise<{
+    server: Server;
+    shutdown: () => Promise<void>;
+}>;
+export {};