@flrande/browserctl 0.3.0 → 0.4.0

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

@@ -55,6 +55,33 @@ describe("cli", () => {
     });
   });
 
+  it("parses --help as a global help request", () => {
+    expect(parseArgs(["--help"])).toEqual({
+      command: null,
+      commandArgs: [],
+      json: false,
+      helpTopic: "all"
+    });
+  });
+
+  it("parses -h as a global help request", () => {
+    expect(parseArgs(["-h"])).toEqual({
+      command: null,
+      commandArgs: [],
+      json: false,
+      helpTopic: "all"
+    });
+  });
+
+  it("parses command --help as command help request", () => {
+    expect(parseArgs(["status", "--help"])).toEqual({
+      command: null,
+      commandArgs: [],
+      json: false,
+      helpTopic: "status"
+    });
+  });
+
   it("writes JSON output on successful run", async () => {
     vi.spyOn(statusCommand, "runStatusCommand").mockResolvedValue({
       kind: "browserd",
@@ -86,6 +113,68 @@ describe("cli", () => {
     expect(state.stderr).toContain("Unknown command: unknown");
   });
 
+  it("writes general help output for --help", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["--help"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(state.stdout).toContain("Usage:");
+    expect(state.stdout).toContain("browserctl help [command]");
+  });
+
+  it("writes JSON help output when --json is provided", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["--json", "--help"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(JSON.parse(state.stdout)).toEqual(
+      expect.objectContaining({
+        ok: true,
+        command: "help",
+        data: expect.objectContaining({
+          topic: "all",
+          text: expect.stringContaining("Usage:")
+        })
+      })
+    );
+  });
+
+  it("writes command help output for help <command>", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["help", "status"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(state.stdout).toContain("Usage:");
+    expect(state.stdout).toContain("browserctl status");
+  });
+
+  it("writes command help output for <command> --help", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["tab-open", "--help"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(state.stdout).toContain("Usage:");
+    expect(state.stdout).toContain("browserctl tab-open <url>");
+  });
+
+  it("returns INVALID_ARGS for unknown help topic", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["help", "unknown"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.INVALID_ARGS);
+    expect(state.stdout).toBe("");
+    expect(state.stderr).toContain("Unknown help topic: unknown");
+  });
+
   it("writes non-JSON output when --json is not provided", async () => {
     vi.spyOn(tabsCommand, "runTabsCommand").mockResolvedValue({
       driver: "managed",

package/apps/browserctl/src/main.ts

@@ -74,9 +74,12 @@ export interface ParsedArgs {
   command: CommandName | null;
   commandArgs: string[];
   json: boolean;
+  helpTopic?: HelpTopic;
   error?: string;
 }
 
+export type HelpTopic = "all" | CommandName;
+
 const VALID_COMMANDS: ReadonlySet<CommandName> = new Set([
   "status",
   "tabs",
@@ -111,6 +114,177 @@ const VALID_COMMANDS: ReadonlySet<CommandName> = new Set([
   "daemon-stop"
 ]);
 
+interface CommandHelpEntry {
+  usage: string;
+  description: string;
+}
+
+const COMMAND_HELP: Readonly<Record<CommandName, CommandHelpEntry>> = {
+  status: {
+    usage: "status",
+    description: "Query daemon and active profile readiness."
+  },
+  tabs: {
+    usage: "tabs",
+    description: "List tabs for the current session."
+  },
+  "profile-list": {
+    usage: "profile-list",
+    description: "List available driver profiles."
+  },
+  "profile-use": {
+    usage: "profile-use <driverKey>",
+    description: "Bind session to a driver profile."
+  },
+  "tab-open": {
+    usage: "tab-open <url>",
+    description: "Open a new tab with the given URL."
+  },
+  "tab-focus": {
+    usage: "tab-focus <targetId>",
+    description: "Activate an existing tab target."
+  },
+  "tab-close": {
+    usage: "tab-close <targetId>",
+    description: "Close a tab target."
+  },
+  snapshot: {
+    usage: "snapshot <targetId>",
+    description: "Get structured DOM snapshot for a tab."
+  },
+  screenshot: {
+    usage: "screenshot <targetId>",
+    description: "Capture full-page screenshot for a tab."
+  },
+  "dom-query": {
+    usage: "dom-query <targetId> <selector>",
+    description: "Get first matching element details."
+  },
+  "dom-query-all": {
+    usage: "dom-query-all <targetId> <selector>",
+    description: "List all matching elements."
+  },
+  "element-screenshot": {
+    usage: "element-screenshot <targetId> <selector>",
+    description: "Capture screenshot for one element."
+  },
+  "a11y-snapshot": {
+    usage: "a11y-snapshot <targetId> [selector]",
+    description: "Get accessibility tree snapshot."
+  },
+  "network-wait-for": {
+    usage:
+      "network-wait-for <targetId> <urlPattern> [--method <METHOD>] [--status <CODE>] [--timeout-ms <ms>] [--poll-ms <ms>]",
+    description: "Wait until a matching network response appears."
+  },
+  "cookie-get": {
+    usage: "cookie-get <targetId> [name]",
+    description: "Read cookie(s) from page context."
+  },
+  "cookie-set": {
+    usage: "cookie-set <targetId> <name> <value> [url]",
+    description: "Set one cookie in page context."
+  },
+  "cookie-clear": {
+    usage: "cookie-clear <targetId> [name]",
+    description: "Clear one or all cookies."
+  },
+  "storage-get": {
+    usage: "storage-get <targetId> <local|session> <key>",
+    description: "Read a storage value."
+  },
+  "storage-set": {
+    usage: "storage-set <targetId> <local|session> <key> <value>",
+    description: "Write a storage value."
+  },
+  "frame-list": {
+    usage: "frame-list <targetId>",
+    description: "List frames for a tab."
+  },
+  "frame-snapshot": {
+    usage: "frame-snapshot <targetId> <frameId>",
+    description: "Snapshot one frame subtree."
+  },
+  act: {
+    usage: "act <actionType> <targetId>",
+    description: "Execute high-level action against a tab."
+  },
+  "upload-arm": {
+    usage: "upload-arm <targetId> <file1> [file2 ...]",
+    description: "Prepare file chooser upload paths."
+  },
+  "dialog-arm": {
+    usage: "dialog-arm <targetId>",
+    description: "Prepare next JS dialog interception."
+  },
+  "download-trigger": {
+    usage: "download-trigger <targetId>",
+    description: "Trigger download capture mode."
+  },
+  "download-wait": {
+    usage: "download-wait <targetId> [path]",
+    description: "Wait for next download and persist file."
+  },
+  "console-list": {
+    usage: "console-list <targetId>",
+    description: "List collected console events."
+  },
+  "response-body": {
+    usage: "response-body <targetId> <requestId>",
+    description: "Read response body for a captured request."
+  },
+  "daemon-status": {
+    usage: "daemon-status",
+    description: "Inspect local daemon process status."
+  },
+  "daemon-start": {
+    usage: "daemon-start [--browser <chromium|chrome|edge>]",
+    description: "Start daemon if needed and report runtime."
+  },
+  "daemon-stop": {
+    usage: "daemon-stop",
+    description: "Stop local daemon process."
+  }
+};
+
+const COMMAND_GROUPS: ReadonlyArray<{ title: string; commands: readonly CommandName[] }> = [
+  {
+    title: "Daemon lifecycle",
+    commands: ["daemon-start", "daemon-status", "daemon-stop"]
+  },
+  {
+    title: "Driver/session",
+    commands: ["status", "profile-list", "profile-use", "tabs"]
+  },
+  {
+    title: "Tab/page",
+    commands: ["tab-open", "tab-focus", "tab-close", "snapshot", "screenshot"]
+  },
+  {
+    title: "Structured reads",
+    commands: [
+      "dom-query",
+      "dom-query-all",
+      "element-screenshot",
+      "a11y-snapshot",
+      "network-wait-for",
+      "cookie-get",
+      "cookie-set",
+      "cookie-clear",
+      "storage-get",
+      "storage-set",
+      "frame-list",
+      "frame-snapshot",
+      "console-list",
+      "response-body"
+    ]
+  },
+  {
+    title: "Action/file flow",
+    commands: ["act", "upload-arm", "dialog-arm", "download-trigger", "download-wait"]
+  }
+];
+
 const CHROME_RELAY_FAILURE_GUIDANCE = [
   "chrome-relay 连接失败，请先完成以下检查：",
   "1) 扩展 relay 方案：设置 BROWSERD_CHROME_RELAY_MODE=extension。",
@@ -120,9 +294,89 @@ const CHROME_RELAY_FAILURE_GUIDANCE = [
   "5) 确认 BROWSERD_CHROME_RELAY_URL 指向可访问地址（默认 http://127.0.0.1:9223）。"
 ].join("\n");
 
+function isHelpFlag(value: string): boolean {
+  return value === "--help" || value === "-h";
+}
+
+function formatGeneralHelp(): string {
+  const lines = [
+    "browserctl - BrowserCtl command line client",
+    "",
+    "Usage:",
+    "  browserctl [--json] <command> [command-options] [positionals]",
+    "  browserctl help [command]",
+    "  browserctl <command> --help",
+    "",
+    "Global options:",
+    "  --json         Print success/error envelopes as JSON.",
+    "  --help, -h     Show general help or command help.",
+    "",
+    "Context options (browser commands):",
+    "  --session <id>         Session namespace (default: cli:local).",
+    "  --profile <driverKey>  Driver override.",
+    "  --token <authToken>    Request auth token override.",
+    "  --browser <preset>     Daemon startup browser preset (daemon-start only).",
+    "",
+    "Commands:"
+  ];
+
+  for (const group of COMMAND_GROUPS) {
+    lines.push(`  ${group.title}:`);
+    for (const command of group.commands) {
+      const entry = COMMAND_HELP[command];
+      lines.push(`    ${entry.usage}`);
+      lines.push(`      ${entry.description}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Run \"browserctl help <command>\" for command-specific usage.");
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatCommandHelp(command: CommandName): string {
+  const entry = COMMAND_HELP[command];
+  const lines = [`Command: ${command}`, "", "Usage:", `  browserctl ${entry.usage}`, "", entry.description];
+  const isDaemonCommand = command.startsWith("daemon-");
+
+  if (!isDaemonCommand) {
+    lines.push("");
+    lines.push("Context options:");
+    lines.push("  --session <id>         Session namespace (default: cli:local).");
+    lines.push("  --profile <driverKey>  Driver override.");
+    lines.push("  --token <authToken>    Request auth token override.");
+  } else if (command === "daemon-start") {
+    lines.push("");
+    lines.push("Command options:");
+    lines.push("  --browser <chromium|chrome|edge>  managed-local browser preset.");
+    lines.push("  --token <authToken>               Request auth token override.");
+  } else if (command === "daemon-status") {
+    lines.push("");
+    lines.push("Command options:");
+    lines.push("  --token <authToken>  Request auth token override.");
+  }
+
+  lines.push("");
+  lines.push("Global options:");
+  lines.push("  --json");
+  lines.push("  --help, -h");
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatHelp(topic: HelpTopic): string {
+  if (topic === "all") {
+    return formatGeneralHelp();
+  }
+
+  return formatCommandHelp(topic);
+}
+
 export function parseArgs(argv: string[]): ParsedArgs {
-  const positional = [];
+  const positional: string[] = [];
   let json = false;
+  let helpRequested = false;
 
   for (const value of argv) {
     if (value === "--json") {
@@ -130,11 +384,25 @@ export function parseArgs(argv: string[]): ParsedArgs {
       continue;
     }
 
+    if (isHelpFlag(value)) {
+      helpRequested = true;
+      continue;
+    }
+
     positional.push(value);
   }
 
   const [commandToken, ...commandArgs] = positional;
   if (commandToken === undefined) {
+    if (helpRequested) {
+      return {
+        command: null,
+        commandArgs: [],
+        json,
+        helpTopic: "all"
+      };
+    }
+
     return {
       command: null,
       commandArgs: [],
@@ -143,6 +411,61 @@ export function parseArgs(argv: string[]): ParsedArgs {
     };
   }
 
+  if (commandToken === "help") {
+    if (commandArgs.length === 0) {
+      return {
+        command: null,
+        commandArgs: [],
+        json,
+        helpTopic: "all"
+      };
+    }
+
+    if (commandArgs.length > 1) {
+      return {
+        command: null,
+        commandArgs: [],
+        json,
+        error: "Too many arguments for help."
+      };
+    }
+
+    const topic = commandArgs[0];
+    if (!VALID_COMMANDS.has(topic as CommandName)) {
+      return {
+        command: null,
+        commandArgs: [],
+        json,
+        error: `Unknown help topic: ${topic}`
+      };
+    }
+
+    return {
+      command: null,
+      commandArgs: [],
+      json,
+      helpTopic: topic as CommandName
+    };
+  }
+
+  if (helpRequested) {
+    if (!VALID_COMMANDS.has(commandToken as CommandName)) {
+      return {
+        command: null,
+        commandArgs: [],
+        json,
+        error: `Unknown command: ${commandToken}`
+      };
+    }
+
+    return {
+      command: null,
+      commandArgs: [],
+      json,
+      helpTopic: commandToken as CommandName
+    };
+  }
+
   if (!VALID_COMMANDS.has(commandToken as CommandName)) {
     return {
       command: null,
@@ -327,6 +650,26 @@ export async function runCli(
     return EXIT_CODES.INVALID_ARGS;
   }
 
+  if (parsedArgs.helpTopic !== undefined) {
+    const helpText = formatHelp(parsedArgs.helpTopic);
+    if (parsedArgs.json) {
+      io.stdout.write(
+        `${JSON.stringify({
+          ok: true,
+          command: "help",
+          data: {
+            topic: parsedArgs.helpTopic,
+            text: helpText.trimEnd()
+          }
+        })}\n`
+      );
+    } else {
+      io.stdout.write(helpText);
+    }
+
+    return EXIT_CODES.OK;
+  }
+
   try {
     const data = await executeCommand(parsedArgs.command, parsedArgs.commandArgs);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flrande/browserctl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "bin": {
     "browserctl": "bin/browserctl.cjs",