@flrande/browserctl 0.2.0-dev.12.1 → 0.2.0

package/README-CN.md

@@ -2,50 +2,65 @@
 
 [English](README.md) | 简体中文
 
-面向 coding agent 的扩展优先浏览器控制工具集。
+最快路径：通过 relay 扩展直接控制你已打开的 Edge/Chrome。
 
-## 给 Agent 安装
+## 扩展模式最简上手（推荐）
 
-把下面文本贴给 agent：
+前置条件：
 
-```text
-请抓取并遵循 https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/INSTALL.md 中的说明。
-```
-
-平台快捷入口：
-
-- Codex：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.codex/INSTALL.md`
-- Claude Code：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.claude-plugin/INSTALL.md`
-- Cursor：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.cursor-plugin/INSTALL.md`
-- OpenCode：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.opencode/INSTALL.md`
+- Node.js 22+
+- npm 或 pnpm
+- PowerShell 7 (`pwsh`)
+- Edge 或 Chrome
 
-默认 skill：
-
-- 名称：`browserctl`
-- 路径：`skills/browserctl`
-
-## 浏览器快速开始（扩展默认）
+1. 安装已发布包：
 
 ```powershell
 npm install --global @flrande/browserctl
+# 或：pnpm add --global @flrande/browserctl
+```
 
+2. 用扩展 relay 模式启动 daemon：
+
+```powershell
 $env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
 $env:BROWSERD_CHROME_RELAY_MODE = "extension"
 $env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "browserctl-relay"
-
+$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
 browserctl daemon-stop --json
 browserctl daemon-start --json
+```
+
+3. 加载扩展：
+
+1. 打开 `edge://extensions` 或 `chrome://extensions`。
+2. 开启开发者模式。
+3. 选择“加载已解压的扩展程序”，目录为 `extensions/chrome-relay`。
+4. 在扩展弹窗中设置：
+- `Bridge URL`: `ws://127.0.0.1:9223/bridge`
+- `Token`: `relay-secret`
+5. 点击 `Save`，再点击 `Reconnect`。
+
+4. 连接验证与首个命令：
+
+```powershell
 browserctl status --json --session relay --profile chrome-relay
+browserctl tab-open --json --session relay --profile chrome-relay https://example.com
+```
+
+## 30 秒排查
+
+```powershell
+browserctl daemon-status --json
+Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
 ```
 
+若 `connected` 为 `false`，重新打开扩展弹窗并点击 `Reconnect`。
+
 ## 完整文档
 
-- [Install Guide (English)](INSTALL.md)
-- [安装指南（中文）](INSTALL-CN.md)
-- [User Guide (English)](docs/user-guide.md)
-- [使用指南（中文）](docs/user-guide-cn.md)
-- [CLI Reference (English)](docs/cli-reference.md)
-- [CLI 参考（中文）](docs/cli-reference-cn.md)
-- [Maintainer Onboarding (English)](docs/maintainer-onboarding.md)
-- [维护者上手文档（中文）](docs/maintainer-onboarding-cn.md)
+- [Full User Guide (English)](docs/user-guide.md)
+- [完整使用文档（中文）](docs/user-guide-cn.md)
+- [Chrome Relay Extension README (English)](extensions/chrome-relay/README.md)
+- [Chrome Relay 扩展文档（中文）](extensions/chrome-relay/README-CN.md)
+

package/README.md

@@ -2,50 +2,65 @@
 
 English | [简体中文](README-CN.md)
 
-Extension-first browser control toolkit for coding agents.
+Fastest path: control your current Edge/Chrome through the relay extension.
 
-## Install In Agents
+## Extension Quick Start (Recommended)
 
-Paste this to your agent:
+Prerequisites:
 
-```text
-Fetch and follow instructions from https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/INSTALL.md
-```
-
-Platform shortcuts:
-
-- Codex: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.codex/INSTALL.md`
-- Claude Code: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.claude-plugin/INSTALL.md`
-- Cursor: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.cursor-plugin/INSTALL.md`
-- OpenCode: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.opencode/INSTALL.md`
+- Node.js 22+
+- npm or pnpm
+- PowerShell 7 (`pwsh`)
+- Edge or Chrome
 
-Default skill:
-
-- Name: `browserctl`
-- Path: `skills/browserctl`
-
-## Browser Quick Start (Extension Default)
+1. Install the released package:
 
 ```powershell
 npm install --global @flrande/browserctl
+# or: pnpm add --global @flrande/browserctl
+```
 
+2. Start daemon in extension relay mode:
+
+```powershell
 $env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
 $env:BROWSERD_CHROME_RELAY_MODE = "extension"
 $env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "browserctl-relay"
-
+$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
 browserctl daemon-stop --json
 browserctl daemon-start --json
+```
+
+3. Load extension:
+
+1. Open `edge://extensions` or `chrome://extensions`.
+2. Enable Developer mode.
+3. Load unpacked extension from `extensions/chrome-relay`.
+4. In extension popup, set:
+- `Bridge URL`: `ws://127.0.0.1:9223/bridge`
+- `Token`: `relay-secret`
+5. Click `Save` then `Reconnect`.
+
+4. Verify and run first command:
+
+```powershell
 browserctl status --json --session relay --profile chrome-relay
+browserctl tab-open --json --session relay --profile chrome-relay https://example.com
+```
+
+## 30-Second Troubleshooting
+
+```powershell
+browserctl daemon-status --json
+Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
 ```
 
+If `connected` is `false`, reopen extension popup and click `Reconnect`.
+
 ## Full Docs
 
-- [Install Guide (English)](INSTALL.md)
-- [安装指南（中文）](INSTALL-CN.md)
-- [User Guide (English)](docs/user-guide.md)
-- [使用指南（中文）](docs/user-guide-cn.md)
-- [CLI Reference (English)](docs/cli-reference.md)
-- [CLI 参考（中文）](docs/cli-reference-cn.md)
-- [Maintainer Onboarding (English)](docs/maintainer-onboarding.md)
-- [维护者上手文档（中文）](docs/maintainer-onboarding-cn.md)
+- [Full User Guide (English)](docs/user-guide.md)
+- [完整使用文档（中文）](docs/user-guide-cn.md)
+- [Chrome Relay Extension README (English)](extensions/chrome-relay/README.md)
+- [Chrome Relay 扩展文档（中文）](extensions/chrome-relay/README-CN.md)
+

package/apps/browserctl/src/e2e.test.ts

@@ -2,10 +2,9 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { stopDaemon } from "./daemon-client";
 import { EXIT_CODES, runCli } from "./main";
-import { reserveLoopbackPort } from "./test-port";
 
+const TEST_DAEMON_PORT = "42491";
 const TEST_SESSION_ID = "session:e2e";
-let testDaemonPort = 0;
 
 function createIoCapture() {
   const state = {
@@ -35,20 +34,17 @@ function parseJsonLine(state: { stdout: string }): Record<string, unknown> {
 }
 
 beforeEach(async () => {
-  testDaemonPort = await reserveLoopbackPort();
-  process.env.BROWSERCTL_DAEMON_PORT = String(testDaemonPort);
+  process.env.BROWSERCTL_DAEMON_PORT = TEST_DAEMON_PORT;
   process.env.BROWSERD_MANAGED_LOCAL_ENABLED = "false";
   process.env.BROWSERD_DEFAULT_DRIVER = "managed";
-  process.env.BROWSERD_CHROME_RELAY_MODE = "cdp";
-  await stopDaemon(testDaemonPort);
+  await stopDaemon(Number.parseInt(TEST_DAEMON_PORT, 10));
 });
 
 afterEach(async () => {
-  await stopDaemon(testDaemonPort);
+  await stopDaemon(Number.parseInt(TEST_DAEMON_PORT, 10));
   delete process.env.BROWSERCTL_DAEMON_PORT;
   delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
   delete process.env.BROWSERD_DEFAULT_DRIVER;
-  delete process.env.BROWSERD_CHROME_RELAY_MODE;
 });
 
 describe("browserctl e2e", () => {
@@ -61,7 +57,7 @@ describe("browserctl e2e", () => {
     expect(startPayload.ok).toBe(true);
     const startData = startPayload.data as Record<string, unknown>;
     expect(startData.running).toBe(true);
-    expect(startData.port).toBe(testDaemonPort);
+    expect(startData.port).toBe(Number.parseInt(TEST_DAEMON_PORT, 10));
 
     const openCapture = createIoCapture();
     const openExitCode = await runCli(

package/apps/browserctl/src/smoke.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+
+import { getSmokeCommand } from "./smoke";
+
+describe("smoke wiring", () => {
+  it("returns a PowerShell command with required flags and default script path", () => {
+    const command = getSmokeCommand();
+
+    expect(command).toContain("pwsh");
+    expect(command).toContain("-NoLogo");
+    expect(command).toContain("-NoProfile");
+    expect(command).toContain("-NonInteractive");
+    expect(command).toContain("-File");
+    expect(command).toContain('".\\scripts\\smoke.ps1"');
+  });
+});

package/apps/browserctl/src/smoke.ts

@@ -0,0 +1,5 @@
+const DEFAULT_SMOKE_SCRIPT_PATH = ".\\scripts\\smoke.ps1";
+
+export function getSmokeCommand(scriptPath: string = DEFAULT_SMOKE_SCRIPT_PATH): string {
+  return `pwsh -NoLogo -NoProfile -NonInteractive -File "${scriptPath}"`;
+}

package/apps/browserd/src/chrome-relay-extension-bridge.test.ts

@@ -1,8 +1,33 @@
+import { createServer } from "node:net";
+
 import { afterEach, describe, expect, it } from "vitest";
 import { WebSocket } from "ws";
 
 import { createChromeRelayExtensionBridge } from "./chrome-relay-extension-bridge";
-import { reserveLoopbackPort } from "./test-port";
+
+async function reservePort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (typeof address !== "object" || address === null) {
+        server.close(() => resolve(0));
+        return;
+      }
+
+      const port = address.port;
+      server.close((closeError) => {
+        if (closeError !== undefined) {
+          reject(closeError);
+          return;
+        }
+
+        resolve(port);
+      });
+    });
+  });
+}
 
 async function waitForCondition(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
   const start = Date.now();
@@ -36,7 +61,7 @@ afterEach(async () => {
 
 describe("createChromeRelayExtensionBridge", () => {
   it("requires token configuration for extension bridge startup", async () => {
-    const port = await reserveLoopbackPort();
+    const port = await reservePort();
 
     expect(() =>
       createChromeRelayExtensionBridge({
@@ -46,7 +71,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("sends requests to extension client and receives responses", async () => {
-    const port = await reserveLoopbackPort();
+    const port = await reservePort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -109,7 +134,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("rejects invoke when extension is not connected", async () => {
-    const port = await reserveLoopbackPort();
+    const port = await reservePort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -123,7 +148,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("enforces token validation for extension websocket connection", async () => {
-    const port = await reserveLoopbackPort();
+    const port = await reservePort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -163,7 +188,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("forwards extension event envelopes to bridge listeners", async () => {
-    const port = await reserveLoopbackPort();
+    const port = await reservePort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",

package/apps/browserd/src/container.ts

@@ -53,11 +53,9 @@ export type BrowserdConfig = {
 
 const DEFAULT_DRIVER_KEY = "managed";
 const MANAGED_LOCAL_DRIVER_KEY = "managed-local";
-const DEFAULT_CONFIG_DRIVER_KEY = "chrome-relay";
 const DEFAULT_MANAGED_LOCAL_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
 const DEFAULT_MANAGED_LOCAL_HEADLESS = true;
-const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "extension";
-const DEFAULT_CHROME_RELAY_EXTENSION_TOKEN = "browserctl-relay";
+const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "cdp";
 const DEFAULT_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS = 5_000;
 const DEFAULT_NETWORK_WAIT_TIMEOUT_MS = 10_000;
 const DEFAULT_NETWORK_WAIT_POLL_MS = 200;
@@ -183,11 +181,7 @@ function parseManagedLocalBrowserName(value: string | undefined): ManagedLocalBr
 
 function parseChromeRelayMode(value: string | undefined): ChromeRelayMode {
   const normalizedValue = value?.trim().toLowerCase();
-  if (normalizedValue === "extension" || normalizedValue === "cdp") {
-    return normalizedValue;
-  }
-
-  return DEFAULT_CHROME_RELAY_MODE;
+  return normalizedValue === "extension" ? "extension" : DEFAULT_CHROME_RELAY_MODE;
 }
 
 export type BrowserdContainer = {
@@ -204,12 +198,16 @@ export function loadBrowserdConfig(
 ): BrowserdConfig {
   const managedLocalEnabled = parseBooleanFlag(env.BROWSERD_MANAGED_LOCAL_ENABLED, true);
   const chromeRelayMode = parseChromeRelayMode(env.BROWSERD_CHROME_RELAY_MODE);
-  const chromeRelayExtensionToken =
-    resolveNonEmptyString(env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN) ??
-    (chromeRelayMode === "extension" ? DEFAULT_CHROME_RELAY_EXTENSION_TOKEN : undefined);
+  const chromeRelayExtensionToken = resolveNonEmptyString(env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN);
+  if (chromeRelayMode === "extension" && chromeRelayExtensionToken === undefined) {
+    throw new Error(
+      "BROWSERD_CHROME_RELAY_EXTENSION_TOKEN is required when BROWSERD_CHROME_RELAY_MODE=extension."
+    );
+  }
 
   const defaultDriver =
-    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ?? DEFAULT_CONFIG_DRIVER_KEY;
+    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ??
+    (managedLocalEnabled ? MANAGED_LOCAL_DRIVER_KEY : DEFAULT_DRIVER_KEY);
 
   return {
     chromeRelayUrl: env.BROWSERD_CHROME_RELAY_URL ?? "http://127.0.0.1:9223",

package/apps/browserd/src/main.test.ts

@@ -1,10 +1,9 @@
-import { beforeEach, describe, expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import { PassThrough } from "node:stream";
 import { createConnection } from "node:net";
 
 import { createContainer, loadBrowserdConfig } from "./container";
 import { bootstrapBrowserd } from "./bootstrap";
-import { reserveLoopbackPort } from "./test-port";
 
 function waitForNextJsonLine(stream: PassThrough): Promise<Record<string, unknown>> {
   return new Promise((resolve, reject) => {
@@ -79,33 +78,11 @@ function sendTcpToolRequest(
   });
 }
 
-let testRelayPort = 0;
-let testTcpPort = 0;
-
-beforeEach(async () => {
-  testRelayPort = await reserveLoopbackPort();
-  testTcpPort = await reserveLoopbackPort();
-  while (testTcpPort === testRelayPort) {
-    testTcpPort = await reserveLoopbackPort();
-  }
-});
-
-function createTestEnv(
-  overrides: Record<string, string | undefined> = {}
-): Record<string, string | undefined> {
-  return {
-    BROWSERD_CHROME_RELAY_URL: `http://127.0.0.1:${testRelayPort}`,
-    ...overrides
-  };
-}
-
 describe("browserd container", () => {
   it("uses secure defaults for new security config fields", () => {
     const config = loadBrowserdConfig({});
 
-    expect(config.defaultDriver).toBe("chrome-relay");
-    expect(config.chromeRelayMode).toBe("extension");
-    expect(config.chromeRelayExtensionToken).toBe("browserctl-relay");
+    expect(config.defaultDriver).toBe("managed-local");
     expect(config.managedLocalEnabled).toBe(true);
     expect(config.uploadRoot).toBeUndefined();
     expect(config.downloadRoot).toBeUndefined();
@@ -114,13 +91,12 @@ describe("browserd container", () => {
   });
 
   it("registers managed-local, managed, chrome-relay, and remote-cdp drivers by default", () => {
-    const c = createContainer(loadBrowserdConfig(createTestEnv()));
+    const c = createContainer();
 
     expect(c.drivers.has("managed-local")).toBe(true);
     expect(c.drivers.has("managed")).toBe(true);
     expect(c.drivers.has("chrome-relay")).toBe(true);
     expect(c.drivers.has("remote-cdp")).toBe(true);
-    c.close();
   });
 
   it("uses env override in loadBrowserdConfig", () => {
@@ -134,7 +110,7 @@ describe("browserd container", () => {
 
     expect(config.remoteCdpUrl).toBe("http://127.0.0.1:9333/devtools/browser/override");
     expect(config.chromeRelayUrl).toBe("http://127.0.0.1:9223");
-    expect(config.defaultDriver).toBe("chrome-relay");
+    expect(config.defaultDriver).toBe("managed-local");
     expect(config.managedLocalEnabled).toBe(true);
     expect(config.uploadRoot).toBe("C:\\safe\\uploads");
     expect(config.downloadRoot).toBe("C:\\safe\\downloads");
@@ -156,42 +132,31 @@ describe("browserd container", () => {
     expect(config.chromeRelayExtensionRequestTimeoutMs).toBe(7000);
   });
 
-  it("respects explicit cdp relay mode override", () => {
-    const config = loadBrowserdConfig({
-      BROWSERD_CHROME_RELAY_MODE: "cdp"
-    });
-
-    expect(config.chromeRelayMode).toBe("cdp");
-  });
-
-  it("uses default extension relay token when extension mode is enabled", () => {
-    const config = loadBrowserdConfig({
-      BROWSERD_CHROME_RELAY_MODE: "extension"
-    });
-
-    expect(config.chromeRelayMode).toBe("extension");
-    expect(config.chromeRelayExtensionToken).toBe("browserctl-relay");
+  it("requires extension relay token when extension mode is enabled", () => {
+    expect(() =>
+      loadBrowserdConfig({
+        BROWSERD_CHROME_RELAY_MODE: "extension"
+      })
+    ).toThrow("BROWSERD_CHROME_RELAY_EXTENSION_TOKEN");
   });
 
-  it("keeps chrome-relay as default when managed-local is explicitly disabled", () => {
+  it("defaults to managed when managed-local is explicitly disabled", () => {
     const config = loadBrowserdConfig({
       BROWSERD_MANAGED_LOCAL_ENABLED: "false"
     });
 
     expect(config.managedLocalEnabled).toBe(false);
-    expect(config.defaultDriver).toBe("chrome-relay");
+    expect(config.defaultDriver).toBe("managed");
   });
 
   it("does not register managed-local driver when explicitly disabled", () => {
     const c = createContainer(
       loadBrowserdConfig({
-        ...createTestEnv(),
         BROWSERD_MANAGED_LOCAL_ENABLED: "false"
       })
     );
 
     expect(c.drivers.has("managed-local")).toBe(false);
-    c.close();
   });
 });
 
@@ -200,7 +165,7 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
 
-    const runtime = bootstrapBrowserd({ env: createTestEnv(), input, output });
+    const runtime = bootstrapBrowserd({ input, output });
 
     expect(runtime.mcpStdioStarted).toBe(true);
     expect(runtime.container.drivers.has("managed")).toBe(true);
@@ -214,13 +179,13 @@ describe("browserd bootstrap", () => {
   });
 
   it("supports tcp transport mode for persistent daemon use", async () => {
-    const port = testTcpPort;
+    const port = 41419;
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_TRANSPORT: "tcp",
         BROWSERD_PORT: String(port),
         BROWSERD_AUTH_TOKEN: "tcp-token"
-      })
+      }
     });
 
     const response = await sendTcpToolRequest(port, {
@@ -250,10 +215,10 @@ describe("browserd bootstrap", () => {
     try {
       expect(() => {
         runtime = bootstrapBrowserd({
-          env: createTestEnv({
+          env: {
             BROWSERD_TRANSPORT: "tcp",
-            BROWSERD_PORT: String(testTcpPort)
-          })
+            BROWSERD_PORT: "41420"
+          }
         });
       }).toThrow("BROWSERD_AUTH_TOKEN");
     } finally {
@@ -264,7 +229,7 @@ describe("browserd bootstrap", () => {
   it("processes line-delimited requests and writes response with id", async () => {
     const input = new PassThrough();
     const output = new PassThrough();
-    const runtime = bootstrapBrowserd({ env: createTestEnv(), input, output, stdioProtocol: "legacy" });
+    const runtime = bootstrapBrowserd({ input, output, stdioProtocol: "legacy" });
 
     const response = await sendToolRequest(input, output, {
       id: "request-1",
@@ -282,7 +247,7 @@ describe("browserd bootstrap", () => {
     expect(response.data).toMatchObject({
       kind: "browserd",
       ready: true,
-      driver: "chrome-relay"
+      driver: "managed-local"
     });
 
     runtime.close();
@@ -294,10 +259,10 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_MANAGED_LOCAL_ENABLED: "true",
         BROWSERD_DEFAULT_DRIVER: "managed-local"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -332,10 +297,10 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed-local",
         BROWSERD_MANAGED_LOCAL_ENABLED: "false"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -366,9 +331,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_AUTH_TOKEN: "secret-token"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -397,9 +362,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_AUTH_TOKEN: "secret-token"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -429,11 +394,11 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed",
         BROWSERD_AUTH_TOKEN: "secret-token",
         BROWSERD_AUTH_SCOPES: "read"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -464,11 +429,11 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed",
         BROWSERD_AUTH_TOKEN: "secret-token",
         BROWSERD_AUTH_SCOPES: "read,act"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -529,10 +494,10 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed",
         BROWSERD_UPLOAD_ROOT: "C:\\allowed\\uploads"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -574,9 +539,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -619,10 +584,10 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed",
         BROWSERD_DOWNLOAD_ROOT: "C:\\allowed\\downloads"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -681,9 +646,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -725,9 +690,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -774,9 +739,9 @@ describe("browserd bootstrap", () => {
     const input = new PassThrough();
     const output = new PassThrough();
     const runtime = bootstrapBrowserd({
-      env: createTestEnv({
+      env: {
         BROWSERD_DEFAULT_DRIVER: "managed"
-      }),
+      },
       input,
       output,
       stdioProtocol: "legacy"
@@ -854,7 +819,7 @@ describe("browserd bootstrap", () => {
   it("preserves id and trace/session metadata when queue-level error handling runs", async () => {
     const input = new PassThrough();
     const output = new PassThrough();
-    const runtime = bootstrapBrowserd({ env: createTestEnv(), input, output, stdioProtocol: "legacy" });
+    const runtime = bootstrapBrowserd({ input, output, stdioProtocol: "legacy" });
 
     const originalWrite = output.write.bind(output);
     let shouldThrow = true;

package/apps/browserd/src/tool-matrix.test.ts

@@ -3,7 +3,6 @@ import { PassThrough } from "node:stream";
 import { describe, expect, it } from "vitest";
 
 import { bootstrapBrowserd } from "./bootstrap";
-import { reserveLoopbackPort } from "./test-port";
 
 function waitForNextJsonLine(stream: PassThrough): Promise<Record<string, unknown>> {
   return new Promise((resolve, reject) => {
@@ -41,15 +40,12 @@ function sendToolRequest(
   return responsePromise;
 }
 
-async function createManagedLegacyRuntime() {
-  const relayPort = await reserveLoopbackPort();
-
+function createManagedLegacyRuntime() {
   const input = new PassThrough();
   const output = new PassThrough();
   const runtime = bootstrapBrowserd({
     env: {
-      BROWSERD_DEFAULT_DRIVER: "managed",
-      BROWSERD_CHROME_RELAY_URL: `http://127.0.0.1:${relayPort}`
+      BROWSERD_DEFAULT_DRIVER: "managed"
     },
     input,
     output,
@@ -65,7 +61,7 @@ async function createManagedLegacyRuntime() {
 
 describe("browserd tool matrix", () => {
   it("returns E_INVALID_ARG for missing required arguments on routed tools", async () => {
-    const { input, output, runtime } = await createManagedLegacyRuntime();
+    const { input, output, runtime } = createManagedLegacyRuntime();
 
     try {
       const toolNames = [
@@ -113,7 +109,7 @@ describe("browserd tool matrix", () => {
   });
 
   it("returns E_DRIVER_UNAVAILABLE for structured action tools on managed driver", async () => {
-    const { input, output, runtime } = await createManagedLegacyRuntime();
+    const { input, output, runtime } = createManagedLegacyRuntime();
 
     try {
       const openResponse = await sendToolRequest(input, output, {
@@ -239,7 +235,7 @@ describe("browserd tool matrix", () => {
   });
 
   it("routes managed-driver tools including profile.use, act, focus/close, and waitFor timeout", async () => {
-    const { input, output, runtime } = await createManagedLegacyRuntime();
+    const { input, output, runtime } = createManagedLegacyRuntime();
 
     try {
       const profileUseResponse = await sendToolRequest(input, output, {

package/extensions/chrome-relay/README-CN.md

@@ -23,7 +23,6 @@
 默认 Bridge URL：
 
 - `ws://127.0.0.1:9223/bridge`
-- 默认 token（当 daemon 使用默认配置时）：`browserctl-relay`
 
 ## 弹窗故障排查
 

package/extensions/chrome-relay/README.md

@@ -23,7 +23,6 @@ This extension uses the `debugger` permission to collect console/network telemet
 Default bridge URL:
 
 - `ws://127.0.0.1:9223/bridge`
-- Default token (if daemon uses defaults): `browserctl-relay`
 
 ## Troubleshooting In Popup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flrande/browserctl",
-  "version": "0.2.0-dev.12.1",
+  "version": "0.2.0",
   "private": false,
   "bin": {
     "browserctl": "bin/browserctl.cjs",
@@ -16,8 +16,7 @@
     "packages/protocol/src",
     "packages/transport-mcp-stdio/src",
     "extensions/chrome-relay",
-    "INSTALL.md",
-    "INSTALL-CN.md",
+    "scripts/smoke.ps1",
     "bin",
     "README.md",
     "README-CN.md",
@@ -44,9 +43,8 @@
     "test:unit": "vitest run --config vitest.config.ts",
     "test:contract": "vitest run --config vitest.contract.config.ts",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:smoke": "vitest run --config vitest.smoke.config.ts",
-    "test:all": "pnpm run test:unit && pnpm run test:contract && pnpm run test:e2e && pnpm run test:smoke",
-    "build": "npm pack --dry-run",
+    "test:all": "pnpm run test:unit && pnpm run test:contract && pnpm run test:e2e",
+    "build": "pnpm publish --dry-run --no-git-checks",
     "typecheck": "pnpm exec tsc --noEmit -p tsconfig.typecheck.json",
     "lint": "node ./scripts/lint.mjs"
   }

package/scripts/smoke.ps1

@@ -0,0 +1,127 @@
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+$scriptDir = Split-Path -Parent $PSCommandPath
+$repoRoot = Resolve-Path -LiteralPath (Join-Path $scriptDir '..')
+$browserdEntry = Join-Path $repoRoot 'apps/browserd/src/main.ts'
+$browserctlEntry = Join-Path $repoRoot 'apps/browserctl/src/main.ts'
+
+$daemonProcess = $null
+$daemonPort = 41337
+$timeoutMs = 10000
+$pollIntervalMs = 250
+$pnpmExecutable = if ($IsWindows) { 'pnpm.cmd' } else { 'pnpm' }
+
+function Invoke-SmokeStatus {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$BrowserctlEntry
+  )
+
+  $previousPort = $env:BROWSERCTL_DAEMON_PORT
+  $env:BROWSERCTL_DAEMON_PORT = "$daemonPort"
+
+  $statusOutput = & pnpm exec tsx $BrowserctlEntry status --json 2>&1
+  $exitCode = $LASTEXITCODE
+  $statusText = [string]::Join([Environment]::NewLine, @($statusOutput))
+
+  if ($null -eq $previousPort) {
+    Remove-Item Env:\BROWSERCTL_DAEMON_PORT -ErrorAction SilentlyContinue
+  } else {
+    $env:BROWSERCTL_DAEMON_PORT = $previousPort
+  }
+
+  if ($exitCode -ne 0) {
+    return @{
+      Ok = $false
+      Reason = "browserctl status exited with code $exitCode. Output: $statusText"
+    }
+  }
+
+  $statusPayload = $null
+  try {
+    $statusPayload = $statusText | ConvertFrom-Json -ErrorAction Stop
+  } catch {
+    return @{
+      Ok = $false
+      Reason = "browserctl status returned invalid JSON. Output: $statusText"
+    }
+  }
+
+  if (-not $statusPayload.ok) {
+    return @{
+      Ok = $false
+      Reason = 'browserctl status returned ok=false.'
+    }
+  }
+
+  $errorProperty = $statusPayload.PSObject.Properties['error']
+  if ($null -ne $errorProperty -and $null -ne $errorProperty.Value) {
+    $errorJson = $errorProperty.Value | ConvertTo-Json -Compress
+    return @{
+      Ok = $false
+      Reason = "browserctl status returned error payload: $errorJson"
+    }
+  }
+
+  return @{
+    Ok = $true
+    Payload = $statusPayload
+  }
+}
+
+try {
+  $previousPort = $env:BROWSERCTL_DAEMON_PORT
+  $env:BROWSERCTL_DAEMON_PORT = "$daemonPort"
+  & pnpm exec tsx $browserctlEntry daemon-stop --json *> $null
+  if ($null -eq $previousPort) {
+    Remove-Item Env:\BROWSERCTL_DAEMON_PORT -ErrorAction SilentlyContinue
+  } else {
+    $env:BROWSERCTL_DAEMON_PORT = $previousPort
+  }
+
+  $daemonEnv = @{
+    BROWSERD_TRANSPORT = 'tcp'
+    BROWSERD_PORT = "$daemonPort"
+  }
+
+  $daemonProcess = Start-Process -FilePath $pnpmExecutable `
+    -ArgumentList @('exec', 'tsx', $browserdEntry) `
+    -WorkingDirectory $repoRoot `
+    -Environment $daemonEnv `
+    -PassThru
+
+  $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+  $lastFailure = 'status probe did not run'
+  $statusResult = $null
+
+  while ($stopwatch.ElapsedMilliseconds -lt $timeoutMs) {
+    $statusResult = Invoke-SmokeStatus -BrowserctlEntry $browserctlEntry
+    if ($statusResult.Ok) {
+      break
+    }
+
+    $lastFailure = [string]$statusResult.Reason
+    Start-Sleep -Milliseconds $pollIntervalMs
+  }
+
+  if ($null -eq $statusResult -or -not $statusResult.Ok) {
+    $elapsedMs = [int]$stopwatch.ElapsedMilliseconds
+    throw "Smoke failed: browserctl status --json was not ready within ${timeoutMs}ms (elapsed ${elapsedMs}ms). Last failure: $lastFailure"
+  }
+
+  Write-Host 'Smoke passed: daemon started and browserctl status --json returned success.'
+} finally {
+  if ($null -ne $daemonProcess -and -not $daemonProcess.HasExited) {
+    Stop-Process -Id $daemonProcess.Id -ErrorAction SilentlyContinue
+  }
+
+  $previousPort = $env:BROWSERCTL_DAEMON_PORT
+  $env:BROWSERCTL_DAEMON_PORT = "$daemonPort"
+  & pnpm exec tsx $browserctlEntry daemon-stop --json *> $null
+  if ($null -eq $previousPort) {
+    Remove-Item Env:\BROWSERCTL_DAEMON_PORT -ErrorAction SilentlyContinue
+  } else {
+    $env:BROWSERCTL_DAEMON_PORT = $previousPort
+  }
+}

package/INSTALL-CN.md

@@ -1,28 +0,0 @@
-# 安装 browserctl Skills
-
-[English](INSTALL.md) | 简体中文
-
-本仓库发布一个默认可安装 skill：
-
-- `skills/browserctl`
-
-## 给 Agent 的主提示词
-
-把下面文本贴给 agent：
-
-```text
-请抓取并遵循 https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/INSTALL.md 中的安装说明。
-```
-
-## 平台安装入口
-
-- Codex：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.codex/INSTALL.md`
-- Claude Code：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.claude-plugin/INSTALL.md`
-- Cursor：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.cursor-plugin/INSTALL.md`
-- OpenCode：`https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.opencode/INSTALL.md`
-
-## 兜底约定
-
-如果平台安装入口不可用，agent 应直接抓取并遵循：
-
-- `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/skills/browserctl/SKILL.md`

package/INSTALL.md

@@ -1,28 +0,0 @@
-# Install browserctl Skills
-
-English | [简体中文](INSTALL-CN.md)
-
-This repository publishes one default installable skill:
-
-- `skills/browserctl`
-
-## Primary Agent Prompt
-
-Paste this to your agent:
-
-```text
-Fetch and follow instructions from https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/INSTALL.md
-```
-
-## Platform Guides
-
-- Codex: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.codex/INSTALL.md`
-- Claude Code: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.claude-plugin/INSTALL.md`
-- Cursor: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.cursor-plugin/INSTALL.md`
-- OpenCode: `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/.opencode/INSTALL.md`
-
-## Fallback Contract
-
-If platform-specific install is unavailable, agents should fetch and follow:
-
-- `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/skills/browserctl/SKILL.md`

package/apps/browserctl/src/smoke.e2e.test.ts

@@ -1,97 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import { stopDaemon } from "./daemon-client";
-import { EXIT_CODES, runCli } from "./main";
-import { reserveLoopbackPort } from "./test-port";
-
-let testDaemonPort = 0;
-let activeRelayPort = 0;
-
-function createIoCapture() {
-  const state = {
-    stdout: "",
-    stderr: ""
-  };
-
-  return {
-    state,
-    io: {
-      stdout: {
-        write(content: string) {
-          state.stdout += content;
-        }
-      },
-      stderr: {
-        write(content: string) {
-          state.stderr += content;
-        }
-      }
-    }
-  };
-}
-
-function parseJsonLine(state: { stdout: string }): Record<string, unknown> {
-  return JSON.parse(state.stdout.trim()) as Record<string, unknown>;
-}
-
-beforeEach(async () => {
-  testDaemonPort = await reserveLoopbackPort();
-  activeRelayPort = await reserveLoopbackPort();
-  while (activeRelayPort === testDaemonPort) {
-    activeRelayPort = await reserveLoopbackPort();
-  }
-
-  process.env.BROWSERCTL_DAEMON_PORT = String(testDaemonPort);
-  process.env.BROWSERD_CHROME_RELAY_URL = `http://127.0.0.1:${activeRelayPort}`;
-  delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
-  delete process.env.BROWSERD_DEFAULT_DRIVER;
-  delete process.env.BROWSERD_CHROME_RELAY_MODE;
-  delete process.env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN;
-  await stopDaemon(testDaemonPort);
-});
-
-afterEach(async () => {
-  await stopDaemon(testDaemonPort);
-  delete process.env.BROWSERCTL_DAEMON_PORT;
-  delete process.env.BROWSERD_CHROME_RELAY_URL;
-  delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
-  delete process.env.BROWSERD_DEFAULT_DRIVER;
-  delete process.env.BROWSERD_CHROME_RELAY_MODE;
-  delete process.env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN;
-});
-
-describe("browserctl smoke e2e", () => {
-  it("starts with extension-first defaults and reports chrome-relay status", async () => {
-    const startCapture = createIoCapture();
-    const startExitCode = await runCli(["daemon-start", "--json"], startCapture.io);
-
-    expect(startExitCode).toBe(EXIT_CODES.OK);
-    const startPayload = parseJsonLine(startCapture.state);
-    expect(startPayload.ok).toBe(true);
-
-    const statusCapture = createIoCapture();
-    const statusExitCode = await runCli(["status", "--json"], statusCapture.io);
-
-    expect(statusExitCode).toBe(EXIT_CODES.OK);
-    const statusPayload = parseJsonLine(statusCapture.state);
-    expect(statusPayload.ok).toBe(true);
-    const statusData = statusPayload.data as Record<string, unknown>;
-    expect(statusData.driver).toBe("chrome-relay");
-    expect(statusData.status).toMatchObject({
-      kind: "chrome-relay",
-      connected: false
-    });
-    const relayStatus = statusData.status as Record<string, unknown>;
-    expect(String(relayStatus.relayUrl ?? "")).toContain(`:${activeRelayPort}`);
-
-    const stopCapture = createIoCapture();
-    const stopExitCode = await runCli(["daemon-stop", "--json"], stopCapture.io);
-    expect(stopExitCode).toBe(EXIT_CODES.OK);
-    const stopPayload = parseJsonLine(stopCapture.state);
-    expect(stopPayload.ok).toBe(true);
-    expect(stopPayload.data).toMatchObject({
-      stopped: true,
-      port: testDaemonPort
-    });
-  }, 20_000);
-});

package/apps/browserctl/src/test-port.ts

@@ -1,26 +0,0 @@
-import { createServer } from "node:net";
-
-export async function reserveLoopbackPort(): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const server = createServer();
-
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (typeof address !== "object" || address === null) {
-        server.close(() => reject(new Error("Failed to reserve loopback port.")));
-        return;
-      }
-
-      const port = address.port;
-      server.close((error) => {
-        if (error !== undefined) {
-          reject(error);
-          return;
-        }
-
-        resolve(port);
-      });
-    });
-  });
-}

package/apps/browserd/src/test-port.ts

@@ -1,26 +0,0 @@
-import { createServer } from "node:net";
-
-export async function reserveLoopbackPort(): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const server = createServer();
-
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (typeof address !== "object" || address === null) {
-        server.close(() => reject(new Error("Failed to reserve loopback port.")));
-        return;
-      }
-
-      const port = address.port;
-      server.close((error) => {
-        if (error !== undefined) {
-          reject(error);
-          return;
-        }
-
-        resolve(port);
-      });
-    });
-  });
-}