@flrande/browserctl 0.1.0-dev.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 browserctl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-CN.md

@@ -0,0 +1,66 @@
+# browserctl
+
+[English](README.md) | 简体中文
+
+最快路径：通过 relay 扩展直接控制你已打开的 Edge/Chrome。
+
+## 扩展模式最简上手（推荐）
+
+前置条件：
+
+- Node.js 22+
+- npm 或 pnpm
+- PowerShell 7 (`pwsh`)
+- Edge 或 Chrome
+
+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 = "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`。
+
+## 完整文档
+
+- [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

@@ -0,0 +1,66 @@
+# browserctl
+
+English | [简体中文](README-CN.md)
+
+Fastest path: control your current Edge/Chrome through the relay extension.
+
+## Extension Quick Start (Recommended)
+
+Prerequisites:
+
+- Node.js 22+
+- npm or pnpm
+- PowerShell 7 (`pwsh`)
+- Edge or Chrome
+
+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 = "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
+
+- [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/commands/a11y-snapshot.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type A11ySnapshotCommandResult = Record<string, unknown>;
+
+export async function runA11ySnapshotCommand(args: string[]): Promise<A11ySnapshotCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const selector = context.positional[1];
+
+  return await callDaemonTool<A11ySnapshotCommandResult>(
+    "browser.a11y.snapshot",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof selector === "string" && selector.trim().length > 0
+        ? { selector: selector.trim() }
+        : {})
+    })
+  );
+}

package/apps/browserctl/src/commands/act.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ActCommandResult = Record<string, unknown>;
+
+export async function runActCommand(args: string[]): Promise<ActCommandResult> {
+  const context = parseCommandContext(args);
+  const actionType = requirePositionalArg(context, 0, "actionType");
+  const targetId = requirePositionalArg(context, 1, "targetId");
+
+  return await callDaemonTool<ActCommandResult>(
+    "browser.act",
+    buildToolArguments(context, {
+      targetId,
+      action: {
+        type: actionType
+      }
+    })
+  );
+}

package/apps/browserctl/src/commands/common.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  DAEMON_STARTUP_ARGUMENT,
+  buildToolArguments,
+  parseCommandContext
+} from "./common";
+
+const ORIGINAL_AUTH_TOKEN = process.env.BROWSERCTL_AUTH_TOKEN;
+const ORIGINAL_BROWSER = process.env.BROWSERCTL_BROWSER;
+
+afterEach(() => {
+  if (ORIGINAL_AUTH_TOKEN === undefined) {
+    delete process.env.BROWSERCTL_AUTH_TOKEN;
+  } else {
+    process.env.BROWSERCTL_AUTH_TOKEN = ORIGINAL_AUTH_TOKEN;
+  }
+
+  if (ORIGINAL_BROWSER === undefined) {
+    delete process.env.BROWSERCTL_BROWSER;
+    return;
+  }
+
+  process.env.BROWSERCTL_BROWSER = ORIGINAL_BROWSER;
+});
+
+describe("parseCommandContext", () => {
+  it("uses BROWSERCTL_AUTH_TOKEN by default", () => {
+    process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+    const context = parseCommandContext(["target:1"]);
+
+    expect(context.authToken).toBe("env-token");
+    expect(context.positional).toEqual(["target:1"]);
+  });
+
+  it("allows --token to override the environment token", () => {
+    process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+    const context = parseCommandContext(["--token", "cli-token", "target:1"]);
+
+    expect(context.authToken).toBe("cli-token");
+    expect(context.positional).toEqual(["target:1"]);
+  });
+
+  it("throws when --token is missing a value", () => {
+    expect(() => parseCommandContext(["--token"])).toThrow("Missing value for --token.");
+  });
+
+  it("supports --browser edge preset and forwards daemon startup metadata", () => {
+    const context = parseCommandContext(["--browser", "edge", "target:1"]);
+
+    expect(context.daemonStartup).toEqual({
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    });
+    expect(buildToolArguments(context)).toMatchObject({
+      [DAEMON_STARTUP_ARGUMENT]: {
+        managedLocal: {
+          browserName: "chromium",
+          channel: "msedge"
+        }
+      }
+    });
+  });
+
+  it("supports BROWSERCTL_BROWSER env preset", () => {
+    process.env.BROWSERCTL_BROWSER = "edge";
+
+    const context = parseCommandContext(["target:1"]);
+
+    expect(context.daemonStartup).toEqual({
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    });
+  });
+
+  it("throws on unsupported --browser values", () => {
+    expect(() => parseCommandContext(["--browser", "opera"])).toThrow(
+      "Invalid value for --browser: opera. Supported values: chromium, chrome, edge."
+    );
+  });
+});

package/apps/browserctl/src/commands/common.ts

@@ -0,0 +1,191 @@
+export type ManagedLocalBrowserPreset = "chromium" | "chrome" | "edge";
+
+export type DaemonStartupConfig = {
+  managedLocal: {
+    browserName: "chromium";
+    channel?: string;
+  };
+};
+
+export type CommandContext = {
+  sessionId: string;
+  profile?: string;
+  authToken?: string;
+  daemonStartup?: DaemonStartupConfig;
+  positional: string[];
+};
+
+export const DAEMON_STARTUP_ARGUMENT = "__browserctlDaemonStartup";
+
+const DEFAULT_SESSION_ID = "cli:local";
+const SUPPORTED_BROWSER_PRESETS = new Set<ManagedLocalBrowserPreset>([
+  "chromium",
+  "chrome",
+  "edge"
+]);
+
+function resolveAuthToken(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length > 0 ? trimmedValue : undefined;
+}
+
+function requireValue(args: string[], index: number, option: string): string {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+
+  return value;
+}
+
+function parseBrowserPreset(
+  value: string | undefined,
+  optionName: string
+): ManagedLocalBrowserPreset | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalizedValue = value.trim().toLowerCase();
+  if (normalizedValue.length === 0) {
+    return undefined;
+  }
+
+  if (SUPPORTED_BROWSER_PRESETS.has(normalizedValue as ManagedLocalBrowserPreset)) {
+    return normalizedValue as ManagedLocalBrowserPreset;
+  }
+
+  throw new Error(
+    `Invalid value for ${optionName}: ${value}. Supported values: chromium, chrome, edge.`
+  );
+}
+
+function resolveDaemonStartupConfig(
+  browserPreset: ManagedLocalBrowserPreset | undefined
+): DaemonStartupConfig | undefined {
+  if (browserPreset === undefined) {
+    return undefined;
+  }
+
+  if (browserPreset === "edge") {
+    return {
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    };
+  }
+
+  if (browserPreset === "chrome") {
+    return {
+      managedLocal: {
+        browserName: "chromium",
+        channel: "chrome"
+      }
+    };
+  }
+
+  return {
+    managedLocal: {
+      browserName: "chromium"
+    }
+  };
+}
+
+export function parseCommandContext(args: string[]): CommandContext {
+  const positional: string[] = [];
+  let sessionId = DEFAULT_SESSION_ID;
+  let profile: string | undefined;
+  let authToken = resolveAuthToken(process.env.BROWSERCTL_AUTH_TOKEN);
+  let browserPreset = parseBrowserPreset(process.env.BROWSERCTL_BROWSER, "BROWSERCTL_BROWSER");
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+
+    if (token === "--session") {
+      sessionId = requireValue(args, index, "--session");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--profile") {
+      profile = requireValue(args, index, "--profile");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--token") {
+      authToken = resolveAuthToken(requireValue(args, index, "--token"));
+      if (authToken === undefined) {
+        throw new Error("Missing value for --token.");
+      }
+
+      index += 1;
+      continue;
+    }
+
+    if (token === "--browser") {
+      browserPreset = parseBrowserPreset(requireValue(args, index, "--browser"), "--browser");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--") {
+      positional.push(...args.slice(index + 1));
+      break;
+    }
+
+    positional.push(token);
+  }
+
+  return {
+    sessionId,
+    profile,
+    authToken,
+    daemonStartup: resolveDaemonStartupConfig(browserPreset),
+    positional
+  };
+}
+
+export function buildToolArguments(
+  context: CommandContext,
+  args: Record<string, unknown> = {}
+): Record<string, unknown> {
+  const baseArguments: Record<string, unknown> = {
+    sessionId: context.sessionId
+  };
+
+  if (context.profile !== undefined) {
+    baseArguments.profile = context.profile;
+  }
+
+  if (context.authToken !== undefined) {
+    baseArguments.authToken = context.authToken;
+  }
+
+  if (context.daemonStartup !== undefined) {
+    baseArguments[DAEMON_STARTUP_ARGUMENT] = context.daemonStartup;
+  }
+
+  return {
+    ...baseArguments,
+    ...args
+  };
+}
+
+export function requirePositionalArg(
+  context: CommandContext,
+  index: number,
+  name: string
+): string {
+  const value = context.positional[index];
+  if (value === undefined) {
+    throw new Error(`Missing required argument: ${name}.`);
+  }
+
+  return value;
+}

package/apps/browserctl/src/commands/console-list.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ConsoleListCommandResult = {
+  driver: string;
+  targetId: string;
+  entries: unknown[];
+};
+
+export async function runConsoleListCommand(args: string[]): Promise<ConsoleListCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<ConsoleListCommandResult>(
+    "browser.console.list",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/cookie-clear.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieClearCommandResult = Record<string, unknown>;
+
+export async function runCookieClearCommand(args: string[]): Promise<CookieClearCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = context.positional[1];
+
+  return await callDaemonTool<CookieClearCommandResult>(
+    "browser.cookie.clear",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof name === "string" && name.trim().length > 0 ? { name: name.trim() } : {})
+    })
+  );
+}

package/apps/browserctl/src/commands/cookie-get.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieGetCommandResult = Record<string, unknown>;
+
+export async function runCookieGetCommand(args: string[]): Promise<CookieGetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = context.positional[1];
+
+  return await callDaemonTool<CookieGetCommandResult>(
+    "browser.cookie.get",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof name === "string" && name.trim().length > 0 ? { name: name.trim() } : {})
+    })
+  );
+}

package/apps/browserctl/src/commands/cookie-set.ts

@@ -0,0 +1,22 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieSetCommandResult = Record<string, unknown>;
+
+export async function runCookieSetCommand(args: string[]): Promise<CookieSetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = requirePositionalArg(context, 1, "name");
+  const value = requirePositionalArg(context, 2, "value");
+  const url = context.positional[3];
+
+  return await callDaemonTool<CookieSetCommandResult>(
+    "browser.cookie.set",
+    buildToolArguments(context, {
+      targetId,
+      name,
+      value,
+      ...(typeof url === "string" && url.trim().length > 0 ? { url: url.trim() } : {})
+    })
+  );
+}

package/apps/browserctl/src/commands/dialog-arm.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DialogArmCommandResult = {
+  driver: string;
+  targetId: string;
+  armed: boolean;
+};
+
+export async function runDialogArmCommand(args: string[]): Promise<DialogArmCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<DialogArmCommandResult>(
+    "browser.dialog.arm",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/dom-query-all.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DomQueryAllCommandResult = Record<string, unknown>;
+
+export async function runDomQueryAllCommand(args: string[]): Promise<DomQueryAllCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const selector = requirePositionalArg(context, 1, "selector");
+
+  return await callDaemonTool<DomQueryAllCommandResult>(
+    "browser.dom.queryAll",
+    buildToolArguments(context, {
+      targetId,
+      selector
+    })
+  );
+}

package/apps/browserctl/src/commands/dom-query.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DomQueryCommandResult = Record<string, unknown>;
+
+export async function runDomQueryCommand(args: string[]): Promise<DomQueryCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const selector = requirePositionalArg(context, 1, "selector");
+
+  return await callDaemonTool<DomQueryCommandResult>(
+    "browser.dom.query",
+    buildToolArguments(context, {
+      targetId,
+      selector
+    })
+  );
+}

package/apps/browserctl/src/commands/download-trigger.ts

@@ -0,0 +1,22 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DownloadTriggerCommandResult = {
+  driver: string;
+  targetId: string;
+  triggered: boolean;
+};
+
+export async function runDownloadTriggerCommand(
+  args: string[]
+): Promise<DownloadTriggerCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<DownloadTriggerCommandResult>(
+    "browser.download.trigger",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}