@flrande/browserctl 0.1.0 → 0.2.0-dev.12.1

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

@@ -0,0 +1,398 @@
+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) => {
+    let buffer = "";
+    const timeout = setTimeout(() => {
+      stream.off("data", onData);
+      reject(new Error("Timed out waiting for JSON line response."));
+    }, 1000);
+
+    const onData = (chunk: string | Buffer) => {
+      buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) {
+        return;
+      }
+
+      clearTimeout(timeout);
+      stream.off("data", onData);
+      const line = buffer.slice(0, newlineIndex);
+
+      resolve(JSON.parse(line) as Record<string, unknown>);
+    };
+
+    stream.on("data", onData);
+  });
+}
+
+function sendToolRequest(
+  input: PassThrough,
+  output: PassThrough,
+  request: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  const responsePromise = waitForNextJsonLine(output);
+  input.write(`${JSON.stringify(request)}\n`);
+  return responsePromise;
+}
+
+async function createManagedLegacyRuntime() {
+  const relayPort = await reserveLoopbackPort();
+
+  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}`
+    },
+    input,
+    output,
+    stdioProtocol: "legacy"
+  });
+
+  return {
+    input,
+    output,
+    runtime
+  };
+}
+
+describe("browserd tool matrix", () => {
+  it("returns E_INVALID_ARG for missing required arguments on routed tools", async () => {
+    const { input, output, runtime } = await createManagedLegacyRuntime();
+
+    try {
+      const toolNames = [
+        "browser.profile.use",
+        "browser.tab.focus",
+        "browser.tab.close",
+        "browser.snapshot",
+        "browser.dom.query",
+        "browser.dom.queryAll",
+        "browser.element.screenshot",
+        "browser.a11y.snapshot",
+        "browser.cookie.get",
+        "browser.cookie.set",
+        "browser.cookie.clear",
+        "browser.storage.get",
+        "browser.storage.set",
+        "browser.frame.list",
+        "browser.frame.snapshot",
+        "browser.act",
+        "browser.dialog.arm",
+        "browser.download.trigger",
+        "browser.network.waitFor"
+      ] as const;
+
+      for (const [index, toolName] of toolNames.entries()) {
+        const response = await sendToolRequest(input, output, {
+          id: `request-missing-arg-${index}`,
+          name: toolName,
+          traceId: `trace:missing-arg:${index}`,
+          arguments: {
+            sessionId: "session:missing-arg"
+          }
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.error).toMatchObject({
+          code: "E_INVALID_ARG"
+        });
+      }
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+
+  it("returns E_DRIVER_UNAVAILABLE for structured action tools on managed driver", async () => {
+    const { input, output, runtime } = await createManagedLegacyRuntime();
+
+    try {
+      const openResponse = await sendToolRequest(input, output, {
+        id: "request-unavailable-open",
+        name: "browser.tab.open",
+        traceId: "trace:unavailable:open",
+        arguments: {
+          sessionId: "session:unavailable",
+          url: "https://example.com/unavailable"
+        }
+      });
+      const targetId = (openResponse.data as { targetId: string }).targetId;
+
+      const cases: Array<{ name: string; arguments: Record<string, unknown> }> = [
+        {
+          name: "browser.dom.query",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: "#root"
+          }
+        },
+        {
+          name: "browser.dom.queryAll",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: ".item"
+          }
+        },
+        {
+          name: "browser.element.screenshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: "#hero"
+          }
+        },
+        {
+          name: "browser.a11y.snapshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.cookie.get",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.cookie.set",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            name: "sid",
+            value: "abc"
+          }
+        },
+        {
+          name: "browser.cookie.clear",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.storage.get",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            scope: "local",
+            key: "theme"
+          }
+        },
+        {
+          name: "browser.storage.set",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            scope: "local",
+            key: "theme",
+            value: "dark"
+          }
+        },
+        {
+          name: "browser.frame.list",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.frame.snapshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            frameId: "frame:0"
+          }
+        }
+      ];
+
+      for (const [index, testCase] of cases.entries()) {
+        const response = await sendToolRequest(input, output, {
+          id: `request-driver-unavailable-${index}`,
+          name: testCase.name,
+          traceId: `trace:driver-unavailable:${index}`,
+          arguments: testCase.arguments
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.error).toMatchObject({
+          code: "E_DRIVER_UNAVAILABLE"
+        });
+      }
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+
+  it("routes managed-driver tools including profile.use, act, focus/close, and waitFor timeout", async () => {
+    const { input, output, runtime } = await createManagedLegacyRuntime();
+
+    try {
+      const profileUseResponse = await sendToolRequest(input, output, {
+        id: "request-profile-use",
+        name: "browser.profile.use",
+        traceId: "trace:matrix:profile-use",
+        arguments: {
+          sessionId: "session:profile-use",
+          profile: "managed"
+        }
+      });
+      expect(profileUseResponse.ok).toBe(true);
+      expect(profileUseResponse.data).toEqual({
+        profile: "managed"
+      });
+
+      const openResponse = await sendToolRequest(input, output, {
+        id: "request-flow-open",
+        name: "browser.tab.open",
+        traceId: "trace:matrix:open",
+        arguments: {
+          sessionId: "session:flow",
+          url: "https://example.com/flow"
+        }
+      });
+      const targetId = (openResponse.data as { targetId: string }).targetId;
+
+      const snapshotResponse = await sendToolRequest(input, output, {
+        id: "request-flow-snapshot",
+        name: "browser.snapshot",
+        traceId: "trace:matrix:snapshot",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(snapshotResponse.ok).toBe(true);
+      expect(snapshotResponse.data).toMatchObject({
+        driver: "managed",
+        targetId
+      });
+
+      const focusResponse = await sendToolRequest(input, output, {
+        id: "request-flow-focus",
+        name: "browser.tab.focus",
+        traceId: "trace:matrix:focus",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(focusResponse.ok).toBe(true);
+      expect(focusResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        focused: true
+      });
+
+      const actResponse = await sendToolRequest(input, output, {
+        id: "request-flow-act",
+        name: "browser.act",
+        traceId: "trace:matrix:act",
+        arguments: {
+          sessionId: "session:flow",
+          targetId,
+          action: {
+            type: "click",
+            payload: {
+              selector: "#go"
+            }
+          }
+        }
+      });
+      expect(actResponse.ok).toBe(true);
+      expect(actResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        result: {
+          actionType: "click",
+          targetId,
+          targetKnown: true,
+          ok: true
+        }
+      });
+
+      const dialogResponse = await sendToolRequest(input, output, {
+        id: "request-flow-dialog",
+        name: "browser.dialog.arm",
+        traceId: "trace:matrix:dialog",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(dialogResponse.ok).toBe(true);
+      expect(dialogResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        armed: true
+      });
+
+      const triggerResponse = await sendToolRequest(input, output, {
+        id: "request-flow-trigger",
+        name: "browser.download.trigger",
+        traceId: "trace:matrix:trigger",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(triggerResponse.ok).toBe(true);
+      expect(triggerResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        triggered: true
+      });
+
+      const waitForResponse = await sendToolRequest(input, output, {
+        id: "request-flow-waitfor",
+        name: "browser.network.waitFor",
+        traceId: "trace:matrix:waitfor",
+        arguments: {
+          sessionId: "session:flow",
+          targetId,
+          urlPattern: "/never-match",
+          timeoutMs: 5,
+          pollMs: 1
+        }
+      });
+      expect(waitForResponse.ok).toBe(false);
+      expect(waitForResponse.error).toMatchObject({
+        code: "E_TIMEOUT"
+      });
+
+      const closeResponse = await sendToolRequest(input, output, {
+        id: "request-flow-close",
+        name: "browser.tab.close",
+        traceId: "trace:matrix:close",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(closeResponse.ok).toBe(true);
+      expect(closeResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        closed: true
+      });
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+});

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

@@ -0,0 +1,39 @@
+# BrowserCtl Relay 扩展
+
+[English](README.md) | 简体中文
+
+此扩展用于将 Chromium 系浏览器标签页层连接到本地 BrowserCtl 扩展桥接服务。
+
+## 加载已解压扩展
+
+1. 打开 `chrome://extensions`（Edge 使用 `edge://extensions`）。
+2. 开启**开发者模式**。
+3. 点击**加载已解压的扩展程序**。
+4. 选择目录：`extensions/chrome-relay`。
+
+该扩展使用 `debugger` 权限采集控制台/网络遥测，以供 agent 侧诊断与分析。
+
+## 配置
+
+1. 打开扩展弹窗。
+2. 将 `Bridge URL` 设置为桥接地址。
+3. 将 token 设置为与 `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN` 一致（必填）。
+4. 点击 **Save**，然后点击 **Reconnect**。
+
+默认 Bridge URL：
+
+- `ws://127.0.0.1:9223/bridge`
+- 默认 token（当 daemon 使用默认配置时）：`browserctl-relay`
+
+## 弹窗故障排查
+
+弹窗内置了专门的排查区域：
+
+- **Run Diagnostics**：对比扩展侧连接状态与 relay 侧 `/browserctl/relay/status`。
+- **Copy Report**：复制包含状态快照与建议动作的 JSON 诊断报告。
+- **Guidance list**：给出常见问题的定向建议（URL 不匹配、token 不匹配、relay 不可达、连接陈旧等）。
+
+## 语言切换
+
+使用弹窗语言选择器可切换 **English** 与 **中文**。
+所选语言会保存到扩展本地存储，并在下次打开弹窗时自动应用。

package/extensions/chrome-relay/README.md

@@ -1,5 +1,7 @@
 # BrowserCtl Relay Extension
 
+English | [简体中文](README-CN.md)
+
 This extension connects a Chromium-based browser tab layer to the local BrowserCtl extension bridge.
 
 ## Load Unpacked
@@ -21,6 +23,7 @@ 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.1.0",
+  "version": "0.2.0-dev.12.1",
   "private": false,
   "bin": {
     "browserctl": "bin/browserctl.cjs",
@@ -16,7 +16,8 @@
     "packages/protocol/src",
     "packages/transport-mcp-stdio/src",
     "extensions/chrome-relay",
-    "scripts/smoke.ps1",
+    "INSTALL.md",
+    "INSTALL-CN.md",
     "bin",
     "README.md",
     "README-CN.md",
@@ -43,8 +44,9 @@
     "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:all": "pnpm run test:unit && pnpm run test:contract && pnpm run test:e2e",
-    "build": "pnpm publish --dry-run --no-git-checks",
+    "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",
     "typecheck": "pnpm exec tsc --noEmit -p tsconfig.typecheck.json",
     "lint": "node ./scripts/lint.mjs"
   }

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

@@ -1,16 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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/scripts/smoke.ps1

@@ -1,127 +0,0 @@
-$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
-  }
-}