@flrande/browserctl 0.5.0 → 0.6.0

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+declare const JSON_RPC_VERSION = "2.0";
+export declare const RPC_CLIENT_CONFIG_ERROR = -32001;
+export declare const RPC_CLIENT_TRANSPORT_ERROR = -32002;
+export declare const RPC_CLIENT_PROTOCOL_ERROR = -32003;
+export declare const RPC_CLIENT_INTERNAL_ERROR = -32004;
+export type JsonRpcId = number | string | null;
+export type JsonRpcRequest = {
+    jsonrpc: typeof JSON_RPC_VERSION;
+    id: JsonRpcId;
+    method: string;
+    params: unknown;
+};
+export type JsonRpcError = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+export type JsonRpcSuccessResponse = {
+    jsonrpc: typeof JSON_RPC_VERSION;
+    id: JsonRpcId;
+    result: unknown;
+};
+export type JsonRpcErrorResponse = {
+    jsonrpc: typeof JSON_RPC_VERSION;
+    id: JsonRpcId;
+    error: JsonRpcError;
+};
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+export type RpcClientOptions = {
+    pipeName?: string;
+    timeoutMs?: number;
+};
+export declare function callDaemon(request: JsonRpcRequest, options?: RpcClientOptions): Promise<JsonRpcResponse>;
+export {};

package/dist/client.js

@@ -0,0 +1,138 @@
+import { connect } from "node:net";
+const JSON_RPC_VERSION = "2.0";
+const DEFAULT_TIMEOUT_MS = 2000;
+export const RPC_CLIENT_CONFIG_ERROR = -32001;
+export const RPC_CLIENT_TRANSPORT_ERROR = -32002;
+export const RPC_CLIENT_PROTOCOL_ERROR = -32003;
+export const RPC_CLIENT_INTERNAL_ERROR = -32004;
+export async function callDaemon(request, options = {}) {
+    const pipeName = options.pipeName ?? process.env.BROWSERCTL_DAEMON_PIPE_NAME;
+    if (!pipeName) {
+        return createErrorResponse(request.id, RPC_CLIENT_CONFIG_ERROR, "Daemon pipe name is not configured. Pass options.pipeName or set BROWSERCTL_DAEMON_PIPE_NAME.");
+    }
+    try {
+        const rawResponse = await sendRequest(request, pipeName, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        return parseAndValidateResponse(rawResponse, request.id);
+    }
+    catch (error) {
+        return createErrorResponse(request.id, RPC_CLIENT_TRANSPORT_ERROR, toErrorMessage(error));
+    }
+}
+function connectToPipe(pipeName) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(pipeName);
+        socket.once("connect", () => resolve(socket));
+        socket.once("error", reject);
+    });
+}
+async function sendRequest(request, pipeName, timeoutMs) {
+    const socket = await connectToPipe(pipeName);
+    try {
+        socket.write(`${JSON.stringify(request)}\n`, "utf8");
+        return readLine(socket, timeoutMs);
+    }
+    finally {
+        socket.end();
+    }
+}
+function parseAndValidateResponse(rawResponse, requestId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawResponse);
+    }
+    catch {
+        return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, "Daemon response was not valid JSON.");
+    }
+    if (!isRecord(parsed) || parsed.jsonrpc !== JSON_RPC_VERSION) {
+        return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, "Daemon response must include jsonrpc: \"2.0\".");
+    }
+    if (!Object.prototype.hasOwnProperty.call(parsed, "id") || !isJsonRpcId(parsed.id)) {
+        return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, "Daemon response id is missing or invalid.");
+    }
+    if (parsed.id !== requestId) {
+        return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, `Daemon response id mismatch. Expected ${String(requestId)}.`);
+    }
+    const hasResult = Object.prototype.hasOwnProperty.call(parsed, "result");
+    const hasError = Object.prototype.hasOwnProperty.call(parsed, "error");
+    if (hasResult === hasError) {
+        return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, "Daemon response must include exactly one of result or error.");
+    }
+    if (hasError) {
+        if (!isJsonRpcError(parsed.error)) {
+            return createErrorResponse(requestId, RPC_CLIENT_PROTOCOL_ERROR, "Daemon error response is invalid.");
+        }
+        return {
+            jsonrpc: JSON_RPC_VERSION,
+            id: parsed.id,
+            error: parsed.error
+        };
+    }
+    return {
+        jsonrpc: JSON_RPC_VERSION,
+        id: parsed.id,
+        result: parsed.result
+    };
+}
+function readLine(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = "";
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            reject(new Error("Timed out waiting for daemon response."));
+        }, timeoutMs);
+        const onData = (chunk) => {
+            buffer += chunk.toString("utf8");
+            const separatorIndex = buffer.indexOf("\n");
+            if (separatorIndex < 0) {
+                return;
+            }
+            cleanup();
+            resolve(buffer.slice(0, separatorIndex));
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error("Socket closed before daemon responded."));
+        };
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            socket.off("data", onData);
+            socket.off("error", onError);
+            socket.off("close", onClose);
+        };
+        socket.on("data", onData);
+        socket.on("error", onError);
+        socket.on("close", onClose);
+    });
+}
+function createErrorResponse(id, code, message) {
+    return {
+        jsonrpc: JSON_RPC_VERSION,
+        id,
+        error: {
+            code,
+            message
+        }
+    };
+}
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return `Unexpected client failure: ${String(error)}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonRpcId(value) {
+    return value === null || typeof value === "number" || typeof value === "string";
+}
+function isJsonRpcError(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return typeof value.code === "number" && typeof value.message === "string";
+}

package/dist/commandRegistry.d.ts

@@ -0,0 +1,16 @@
+export declare const DOMAIN_HELP: {
+    readonly session: readonly ["create", "close"];
+    readonly page: readonly ["navigate", "reload"];
+    readonly dom: readonly ["click", "type"];
+    readonly view: readonly ["snapshot", "dom"];
+    readonly network: readonly ["capture.start", "capture.stop"];
+    readonly runtime: readonly ["console.tail", "eval"];
+    readonly workflow: readonly ["run", "replay"];
+    readonly memory: readonly ["suggest", "explain", "pin", "block"];
+    readonly policy: readonly ["preview", "confirm", "whitelist.add", "whitelist.remove"];
+    readonly artifact: readonly ["list", "read", "delete"];
+};
+export type DomainName = keyof typeof DOMAIN_HELP;
+export declare function isDomainName(value: string): value is DomainName;
+export declare function hasDomainCommand(domain: DomainName, command: string): boolean;
+export declare function listDomains(): DomainName[];

package/dist/commandRegistry.js

@@ -0,0 +1,21 @@
+export const DOMAIN_HELP = {
+    session: ["create", "close"],
+    page: ["navigate", "reload"],
+    dom: ["click", "type"],
+    view: ["snapshot", "dom"],
+    network: ["capture.start", "capture.stop"],
+    runtime: ["console.tail", "eval"],
+    workflow: ["run", "replay"],
+    memory: ["suggest", "explain", "pin", "block"],
+    policy: ["preview", "confirm", "whitelist.add", "whitelist.remove"],
+    artifact: ["list", "read", "delete"]
+};
+export function isDomainName(value) {
+    return Object.prototype.hasOwnProperty.call(DOMAIN_HELP, value);
+}
+export function hasDomainCommand(domain, command) {
+    return DOMAIN_HELP[domain].includes(command);
+}
+export function listDomains() {
+    return Object.keys(DOMAIN_HELP);
+}

package/dist/help.d.ts

@@ -0,0 +1,4 @@
+import { type DomainName } from "./commandRegistry.js";
+export declare function renderTextHelp(): string;
+export declare function renderDomainHelp(domain: DomainName): string;
+export declare function renderJsonHelp(): string;

package/dist/help.js

@@ -0,0 +1,24 @@
+import { DOMAIN_HELP, listDomains } from "./commandRegistry.js";
+export function renderTextHelp() {
+    const lines = ["browserctl command reference", "", "domains:"];
+    for (const domain of listDomains()) {
+        lines.push(`  ${domain}: ${DOMAIN_HELP[domain].join(", ")}`);
+    }
+    lines.push("");
+    lines.push("use `browserctl help <domain>` for more details.");
+    lines.push("use `browserctl --json-help` for machine-readable help.");
+    return lines.join("\n");
+}
+export function renderDomainHelp(domain) {
+    const lines = [`browserctl ${domain}`, "", "commands:"];
+    for (const command of DOMAIN_HELP[domain]) {
+        lines.push(`  ${domain} ${command}`);
+    }
+    return lines.join("\n");
+}
+export function renderJsonHelp() {
+    return JSON.stringify({
+        domains: listDomains(),
+        commands: DOMAIN_HELP
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export { runCli } from "./runCli.js";
+export type { RunCliDependencies } from "./runCli.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { runCli } from "./runCli.js";
+export { runCli } from "./runCli.js";
+async function main() {
+    const output = await runCli(process.argv.slice(2));
+    process.stdout.write(`${output}\n`);
+    if (hasErrorEnvelope(output)) {
+        process.exitCode = 1;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void main();
+}
+function hasErrorEnvelope(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return typeof parsed === "object" && parsed !== null && "error" in parsed;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runCli.d.ts

@@ -0,0 +1,5 @@
+import { type JsonRpcRequest, type JsonRpcResponse, type RpcClientOptions } from "./client.js";
+export type RunCliDependencies = {
+    callDaemon?: (request: JsonRpcRequest, options?: RpcClientOptions) => Promise<JsonRpcResponse>;
+};
+export declare function runCli(args: string[], options?: RpcClientOptions, dependencies?: RunCliDependencies): Promise<string>;

package/dist/runCli.js

@@ -0,0 +1,170 @@
+import { callDaemon, RPC_CLIENT_INTERNAL_ERROR } from "./client.js";
+import { hasDomainCommand, isDomainName } from "./commandRegistry.js";
+import { renderDomainHelp, renderJsonHelp, renderTextHelp } from "./help.js";
+const JSON_RPC_VERSION = "2.0";
+const CLI_REQUEST_ID = 1;
+const JSON_RPC_INVALID_REQUEST = -32600;
+export async function runCli(args, options = {}, dependencies = {}) {
+    if (args[0] === "--help" || (args[0] === "help" && args[1] === undefined)) {
+        return renderTextHelp();
+    }
+    if (args[0] === "--json-help") {
+        return renderJsonHelp();
+    }
+    if (args[0] && isDomainName(args[0]) && (args[1] === "--help" || args[1] === "-h")) {
+        return renderDomainHelp(args[0]);
+    }
+    if (args[0] === "help") {
+        const helpTarget = args[1];
+        if (helpTarget && isDomainName(helpTarget)) {
+            return renderDomainHelp(helpTarget);
+        }
+        return createInvalidRequestError(`Unknown help topic: ${helpTarget ?? "<empty>"}`);
+    }
+    const resolvedCommand = resolveCommand(args);
+    if (resolvedCommand === null) {
+        return createInvalidRequestError("Missing RPC method.");
+    }
+    if ("error" in resolvedCommand) {
+        return createInvalidRequestError(resolvedCommand.error);
+    }
+    const request = {
+        jsonrpc: JSON_RPC_VERSION,
+        id: CLI_REQUEST_ID,
+        method: resolvedCommand.method,
+        params: resolvedCommand.params
+    };
+    const invokeDaemon = dependencies.callDaemon ?? callDaemon;
+    try {
+        const response = await invokeDaemon(request, options);
+        return JSON.stringify(response);
+    }
+    catch (error) {
+        return JSON.stringify({
+            jsonrpc: JSON_RPC_VERSION,
+            id: request.id,
+            error: {
+                code: RPC_CLIENT_INTERNAL_ERROR,
+                message: error instanceof Error ? error.message : String(error)
+            }
+        });
+    }
+}
+function resolveCommand(args) {
+    const first = args[0];
+    if (!first) {
+        return null;
+    }
+    if (first.includes(".")) {
+        const parsed = parseParams(args.slice(1));
+        if ("error" in parsed) {
+            return parsed;
+        }
+        return {
+            method: first,
+            params: parsed.params
+        };
+    }
+    if (!isDomainName(first)) {
+        const parsed = parseParams(args.slice(1));
+        if ("error" in parsed) {
+            return parsed;
+        }
+        return {
+            method: first,
+            params: parsed.params
+        };
+    }
+    const onePartCommand = args[1];
+    const twoPartCommand = args[1] !== undefined && args[2] !== undefined ? `${args[1]}.${args[2]}` : undefined;
+    if (twoPartCommand && hasDomainCommand(first, twoPartCommand)) {
+        const parsed = parseParams(args.slice(3));
+        if ("error" in parsed) {
+            return parsed;
+        }
+        return {
+            method: `${first}.${twoPartCommand}`,
+            params: parsed.params
+        };
+    }
+    if (onePartCommand && hasDomainCommand(first, onePartCommand)) {
+        const parsed = parseParams(args.slice(2));
+        if ("error" in parsed) {
+            return parsed;
+        }
+        return {
+            method: `${first}.${onePartCommand}`,
+            params: parsed.params
+        };
+    }
+    return {
+        error: `Unknown command: ${args.join(" ")}`
+    };
+}
+function parseParams(tokens) {
+    const params = {};
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token.startsWith("--")) {
+            return {
+                error: `Unexpected positional argument: ${token}`
+            };
+        }
+        const key = token.slice(2);
+        if (!key) {
+            return {
+                error: "Argument flag must include a key after --"
+            };
+        }
+        const next = tokens[index + 1];
+        if (next === undefined || next.startsWith("--")) {
+            appendParam(params, key, true);
+            continue;
+        }
+        appendParam(params, key, coerceParamValue(next));
+        index += 1;
+    }
+    return { params };
+}
+function coerceParamValue(input) {
+    if ((input.startsWith("{") && input.endsWith("}")) || (input.startsWith("[") && input.endsWith("]"))) {
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            return input;
+        }
+    }
+    if (input === "true") {
+        return true;
+    }
+    if (input === "false") {
+        return false;
+    }
+    if (/^-?\d+(\.\d+)?$/.test(input)) {
+        return Number(input);
+    }
+    return input;
+}
+function appendParam(params, key, value) {
+    const current = params[key];
+    if (current === undefined) {
+        params[key] = value;
+        return;
+    }
+    if (Array.isArray(current)) {
+        current.push(value);
+        return;
+    }
+    params[key] = [current, value];
+}
+function createInvalidRequestError(message) {
+    return JSON.stringify({
+        jsonrpc: JSON_RPC_VERSION,
+        id: null,
+        error: {
+            code: JSON_RPC_INVALID_REQUEST,
+            message
+        }
+    });
+}

package/package.json

@@ -1,57 +1,32 @@
-{
-  "name": "@flrande/browserctl",
-  "version": "0.5.0",
-  "private": false,
-  "bin": {
-    "browserctl": "bin/browserctl.cjs",
-    "browserd": "bin/browserd.cjs"
-  },
-  "files": [
-    "apps/browserctl/src",
-    "apps/browserd/src",
-    "packages/core/src",
-    "packages/driver-chrome-relay/src",
-    "packages/driver-managed/src",
-    "packages/driver-remote-cdp/src",
-    "packages/protocol/src",
-    "packages/transport-mcp-stdio/src",
-    "extensions/chrome-relay",
-    "INSTALL.md",
-    "INSTALL-CN.md",
-    "bin",
-    "README.md",
-    "README-CN.md",
-    "LICENSE",
-    "!**/*.test.ts",
-    "!**/vitest.config.ts",
-    "!**/node_modules/**",
-    "!**/.vite/**"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.4",
-    "playwright-core": "^1.52.0",
-    "tsx": "^4.21.0",
-    "ws": "^8.19.0",
-    "yaml": "^2.8.1",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.30",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.8"
-  },
-  "scripts": {
-    "test": "pnpm run test:unit",
-    "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:e2e:smoke": "vitest run --config vitest.e2e.smoke.config.ts",
-    "test:e2e:full": "vitest run --config vitest.e2e.full.config.ts",
-    "test:e2e:stress": "vitest run --config vitest.e2e.stress.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",
-    "typecheck": "pnpm exec tsc --noEmit -p tsconfig.typecheck.json",
-    "lint": "node ./scripts/lint.mjs"
-  }
-}
+{
+  "name": "@flrande/browserctl",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "browserctl": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Flrande/browserctl"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc src/index.ts --outDir dist --rootDir src --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --esModuleInterop --skipLibCheck --declaration --pretty false",
+    "test": "vitest run"
+  }
+}

package/INSTALL-CN.md

@@ -1,92 +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`
-
-## 安装后更新
-
-默认推荐使用“仓库同源更新”，保证 skill、扩展和 CLI 版本一致。
-
-PowerShell 7：
-
-```powershell
-$repoPath = Join-Path $env:USERPROFILE ".codex\\browserctl" # 按你的本地克隆路径调整
-
-git -C $repoPath pull --ff-only
-npm install --global "$repoPath"
-
-browserctl daemon-stop --json
-browserctl daemon-start --json
-```
-
-Bash：
-
-```bash
-repoPath="$HOME/.codex/browserctl" # 按你的本地克隆路径调整
-
-git -C "$repoPath" pull --ff-only
-npm install --global "$repoPath"
-
-browserctl daemon-stop --json
-browserctl daemon-start --json
-```
-
-拉取后需要在 `edge://extensions` 或 `chrome://extensions` 里刷新扩展：
-
-1. 打开扩展管理页。
-2. 找到 `BrowserCtl Relay`。
-3. 点击 `Reload`。
-
-验证命令：
-
-PowerShell 7：
-
-```powershell
-browserctl status --json --session relay --profile chrome-relay
-Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
-```
-
-Bash：
-
-```bash
-browserctl status --json --session relay --profile chrome-relay
-curl --fail --max-time 3 "http://127.0.0.1:9223/browserctl/relay/status"
-```
-
-可选兜底（非默认）：仅从 npm 仓库更新 CLI。
-
-PowerShell 7：
-
-```powershell
-npm install --global @flrande/browserctl@latest
-```
-
-Bash：
-
-```bash
-npm install --global @flrande/browserctl@latest
-```
-
-## 兜底约定
-
-如果平台安装入口不可用，agent 应直接抓取并遵循：
-
-- `https://raw.githubusercontent.com/Flrande/browserctl/refs/heads/master/skills/browserctl/SKILL.md`