feat(help): add browser structured help

jackwener · jackwener · commit 9d2113b78231 · 2026-05-08T02:12:43.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+* **help / browser** — `opencli browser --help -f yaml|json` now emits a structured, agent-ready index of all browser leaf commands (including nested `tab`, `get`, and `dialog` commands), their positionals, command options, namespace options, and root global options. Individual browser commands also support structured help, backed by a shared Commander option/argument spec extractor.
+
 ### Bug Fixes
 
 * **help / build** — every positional arg must now declare a non-empty `help` string. The build-manifest step fails closed when a positional has empty / whitespace-only / missing `help`, so `opencli <site> <cmd> --help` always shows callers what each parameter is for. Pre-existing offenders (`twitter followers/following/list-add/list-remove/list-tweets/search/thread`, `reddit search/subreddit/user/user-comments/user-posts`, `douyin stats/update`, `bilibili subtitle`, `jike search`) now have explicit help text — most notably `twitter followers [user]` and `following [user]` now document that omitting the user fetches the currently logged-in account.
diff --git a/src/cli.test.ts b/src/cli.test.ts
@@ -363,6 +363,135 @@ describe('createProgram root help descriptions', () => {
       for (const [key, value] of snapshot) registry.set(key, value);
     }
   });
+
+  it('renders browser namespace structured help from Commander metadata', () => {
+    const argv = process.argv;
+    try {
+      const program = createProgram('', '');
+      const browser = program.commands.find(cmd => cmd.name() === 'browser');
+      expect(browser).toBeTruthy();
+
+      process.argv = ['node', 'opencli', 'browser', '--help', '-f', 'yaml'];
+      const data = yaml.load(browser!.helpInformation()) as any;
+
+      expect(data.namespace).toBe('browser');
+      expect(data.command).toBe('opencli browser');
+      expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+      expect(data.command_count).toBeGreaterThan(20);
+      expect(data.namespace_options).toMatchObject([
+        {
+          name: 'workspace',
+          flags: '--workspace <name>',
+          takes_value: 'required',
+        },
+      ]);
+      expect(data.global_options).toEqual(expect.arrayContaining([
+        expect.objectContaining({
+          name: 'version',
+          flags: '-V, --version',
+        }),
+        expect.objectContaining({
+          name: 'profile',
+          flags: '--profile <name>',
+          takes_value: 'required',
+        }),
+      ]));
+
+      const click = data.commands.find((cmd: any) => cmd.name === 'click');
+      expect(click).toMatchObject({
+        command: 'opencli browser click',
+        usage: 'opencli browser click <target> [options]',
+        positionals: [{ name: 'target', required: true }],
+      });
+      expect(click.command_options.map((option: any) => option.name)).toEqual(['nth', 'tab']);
+
+      const tabList = data.commands.find((cmd: any) => cmd.name === 'tab list');
+      expect(tabList).toMatchObject({
+        command: 'opencli browser tab list',
+        usage: 'opencli browser tab list [options]',
+        command_options: [],
+      });
+
+      const getText = data.commands.find((cmd: any) => cmd.name === 'get text');
+      expect(getText).toMatchObject({
+        command: 'opencli browser get text',
+        positionals: [{ name: 'target', required: true }],
+      });
+      expect(data.structured_help).toMatchObject({
+        formats: ['yaml', 'json'],
+        usage: 'opencli browser --help -f yaml',
+      });
+    } finally {
+      process.argv = argv;
+    }
+  });
+
+  it('renders nested browser parent structured help for a subtree', () => {
+    const argv = process.argv;
+    try {
+      const program = createProgram('', '');
+      const browser = program.commands.find(cmd => cmd.name() === 'browser')!;
+      const tab = browser.commands.find(cmd => cmd.name() === 'tab');
+      expect(tab).toBeTruthy();
+
+      process.argv = ['node', 'opencli', 'browser', 'tab', '--help', '-f', 'yaml'];
+      const data = yaml.load(tab!.helpInformation()) as any;
+
+      expect(data).toMatchObject({
+        namespace: 'browser',
+        group: 'tab',
+        command: 'opencli browser tab',
+        usage: 'opencli browser tab <command> [args] [options]',
+        command_count: 4,
+      });
+      expect(data.commands.map((cmd: any) => cmd.name)).toEqual([
+        'tab close',
+        'tab list',
+        'tab new',
+        'tab select',
+      ]);
+      expect(data.commands.find((cmd: any) => cmd.name === 'tab close')).toMatchObject({
+        command: 'opencli browser tab close',
+        usage: 'opencli browser tab close [targetId] [options]',
+        positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
+      });
+      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['workspace']);
+      expect(data.structured_help).toMatchObject({
+        usage: 'opencli browser tab --help -f yaml',
+      });
+    } finally {
+      process.argv = argv;
+    }
+  });
+
+  it('renders browser command structured help without needing the full namespace dump', () => {
+    const argv = process.argv;
+    try {
+      const program = createProgram('', '');
+      const browser = program.commands.find(cmd => cmd.name() === 'browser')!;
+      const click = browser.commands.find(cmd => cmd.name() === 'click');
+      expect(click).toBeTruthy();
+
+      process.argv = ['node', 'opencli', 'browser', 'click', '--help', '-f', 'yaml'];
+      const data = yaml.load(click!.helpInformation()) as any;
+
+      expect(data).toMatchObject({
+        namespace: 'browser',
+        name: 'click',
+        command: 'opencli browser click',
+        usage: 'opencli browser click <target> [options]',
+        positionals: [{ name: 'target', required: true }],
+        structured_help: {
+          usage: 'opencli browser click --help -f yaml',
+        },
+      });
+      expect(data.command_options.map((option: any) => option.name)).toEqual(['nth', 'tab']);
+      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['workspace']);
+      expect(data.global_options.map((option: any) => option.name)).toContain('profile');
+    } finally {
+      process.argv = argv;
+    }
+  });
 });
 
 describe('resolveBrowserVerifyInvocation', () => {
diff --git a/src/cli.ts b/src/cli.ts
@@ -19,7 +19,7 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { classifyAdapter, formatRootAdapterHelpText, installStructuredHelp, rootHelpData, type RootAdapterGroups } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, rootHelpData, type RootAdapterGroups } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError, type TargetErrorCode } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs, type ResolveOptions, type TargetMatchLevel } from './browser/target-resolver.js';
@@ -628,6 +628,7 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command
     .command('browser')
     .option('--workspace <name>', 'Browser workspace to use (default: browser:default; bound tabs use bound:<name>)')
     .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+  const originalBrowserDescription = browser.description();
 
   /**
    * Resolve a `<target>` (numeric ref or CSS selector) via the unified resolver.
@@ -2781,6 +2782,7 @@ cli({
   }
   const adapterGroups: RootAdapterGroups = { external: externalNames, apps, sites };
   const adapterNameSet = new Set<string>([...externalNames, ...siteNames]);
+  installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
   program.configureHelp({
     visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
   });
diff --git a/src/help.ts b/src/help.ts
@@ -1,11 +1,31 @@
-import { Command } from 'commander';
+import { Command, type Argument as CommanderArgument, type Option as CommanderOption } from 'commander';
 import yaml from 'js-yaml';
 import type { Arg, CliCommand } from './registry.js';
 import { fullName } from './registry.js';
 import { formatCommandExample } from './serialization.js';
 
 export type StructuredHelpFormat = 'yaml' | 'json';
 
+export interface ArgSpec {
+  name: string;
+  required?: true;
+  variadic?: true;
+  help?: string;
+  default?: unknown;
+  choices?: string[];
+}
+
+export interface OptionSpec {
+  name: string;
+  flags: string;
+  help?: string;
+  takes_value?: 'required' | 'optional';
+  required?: true;
+  default?: unknown;
+  choices?: string[];
+  negate?: true;
+}
+
 const COMMON_OPTIONS = [
   {
     flags: '-f, --format <fmt>',
@@ -158,6 +178,182 @@ function compactCommonOption(option: typeof COMMON_OPTIONS[number]): Record<stri
   };
 }
 
+function compactCommanderArgument(arg: CommanderArgument): ArgSpec {
+  return {
+    name: arg.name(),
+    ...(arg.required ? { required: true } : {}),
+    ...(arg.variadic ? { variadic: true } : {}),
+    ...(arg.description ? { help: arg.description } : {}),
+    ...(arg.defaultValue !== undefined ? { default: arg.defaultValue } : {}),
+    ...(arg.argChoices?.length ? { choices: [...arg.argChoices] } : {}),
+  };
+}
+
+function compactCommanderOption(option: CommanderOption): OptionSpec | null {
+  if (option.hidden) return null;
+  return {
+    name: option.attributeName(),
+    flags: option.flags,
+    ...(option.description ? { help: option.description } : {}),
+    ...(option.required ? { takes_value: 'required' as const } : {}),
+    ...(option.optional ? { takes_value: 'optional' as const } : {}),
+    ...(option.mandatory ? { required: true } : {}),
+    ...(option.defaultValue !== undefined ? { default: option.defaultValue } : {}),
+    ...(option.argChoices?.length ? { choices: [...option.argChoices] } : {}),
+    ...(option.negate ? { negate: true } : {}),
+  };
+}
+
+function compactCommanderOptions(options: readonly CommanderOption[]): OptionSpec[] {
+  return options
+    .map(compactCommanderOption)
+    .filter((option): option is OptionSpec => option !== null);
+}
+
+function commanderPath(command: Command): string[] {
+  const parts: string[] = [];
+  let current: Command | null = command;
+  while (current) {
+    const name = current.name();
+    if (name) parts.push(name);
+    current = current.parent;
+  }
+  return parts.reverse();
+}
+
+function commandPathFromRoot(namespaceRoot: Command, command: Command): string[] {
+  const rootPath = commanderPath(namespaceRoot);
+  const commandPath = commanderPath(command);
+  return commandPath.slice(rootPath.length);
+}
+
+function collectLeafCommands(command: Command): Command[] {
+  if (command.commands.length === 0) return [command];
+  return command.commands.flatMap(child => collectLeafCommands(child));
+}
+
+function collectDescendantCommands(command: Command): Command[] {
+  return command.commands.flatMap(child => [child, ...collectDescendantCommands(child)]);
+}
+
+function formatCommanderPositionals(args: readonly CommanderArgument[]): string {
+  return args
+    .map(arg => {
+      const name = `${arg.name()}${arg.variadic ? '...' : ''}`;
+      return arg.required ? `<${name}>` : `[${name}]`;
+    })
+    .join(' ');
+}
+
+function formatCommanderUsage(
+  command: Command,
+  opts: { namespaceRoot?: Command; globalCommand?: Command } = {},
+): string {
+  const path = commanderPath(command).join(' ');
+  const positionalText = formatCommanderPositionals(command.registeredArguments);
+  const hasOptions = compactCommanderOptions(command.options).length > 0
+    || (opts.namespaceRoot ? compactCommanderOptions(opts.namespaceRoot.options).length > 0 : false)
+    || (opts.globalCommand ? compactCommanderOptions(opts.globalCommand.options).length > 0 : false);
+  const optionText = hasOptions ? ' [options]' : '';
+  return `${path}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
+}
+
+function compactCommanderCommand(
+  namespaceRoot: Command,
+  command: Command,
+  opts: { globalCommand?: Command } = {},
+): Record<string, unknown> {
+  const relativePath = commandPathFromRoot(namespaceRoot, command);
+  return {
+    name: relativePath.join(' '),
+    command: commanderPath(command).join(' '),
+    usage: formatCommanderUsage(command, { namespaceRoot, globalCommand: opts.globalCommand }),
+    description: command.description(),
+    ...(command.aliases().length ? { aliases: command.aliases() } : {}),
+    positionals: command.registeredArguments.map(compactCommanderArgument),
+    command_options: compactCommanderOptions(command.options),
+  };
+}
+
+export function commanderNamespaceHelpData(
+  namespaceRoot: Command,
+  opts: { globalCommand?: Command; description?: string } = {},
+): Record<string, unknown> {
+  const leaves = collectLeafCommands(namespaceRoot)
+    .filter(command => command !== namespaceRoot)
+    .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+  return {
+    namespace: namespaceRoot.name(),
+    command: commanderPath(namespaceRoot).join(' '),
+    usage: `${commanderPath(namespaceRoot).join(' ')} <command> [args] [options]`,
+    description: opts.description ?? namespaceRoot.description(),
+    command_count: leaves.length,
+    commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+    namespace_options: compactCommanderOptions(namespaceRoot.options),
+    ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+    structured_help: {
+      formats: ['yaml', 'json'],
+      usage: `${commanderPath(namespaceRoot).join(' ')} --help -f yaml`,
+    },
+  };
+}
+
+export function commanderCommandHelpData(
+  namespaceRoot: Command,
+  command: Command,
+  opts: { globalCommand?: Command } = {},
+): Record<string, unknown> {
+  return {
+    namespace: namespaceRoot.name(),
+    ...compactCommanderCommand(namespaceRoot, command, opts),
+    namespace_options: compactCommanderOptions(namespaceRoot.options),
+    ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+    structured_help: {
+      formats: ['yaml', 'json'],
+      usage: `${commanderPath(command).join(' ')} --help -f yaml`,
+    },
+  };
+}
+
+export function commanderGroupHelpData(
+  namespaceRoot: Command,
+  groupCommand: Command,
+  opts: { globalCommand?: Command } = {},
+): Record<string, unknown> {
+  const leaves = collectLeafCommands(groupCommand)
+    .filter(command => command !== groupCommand)
+    .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+  return {
+    namespace: namespaceRoot.name(),
+    group: commandPathFromRoot(namespaceRoot, groupCommand).join(' '),
+    command: commanderPath(groupCommand).join(' '),
+    usage: `${commanderPath(groupCommand).join(' ')} <command> [args] [options]`,
+    description: groupCommand.description(),
+    command_count: leaves.length,
+    commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+    namespace_options: compactCommanderOptions(namespaceRoot.options),
+    ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+    structured_help: {
+      formats: ['yaml', 'json'],
+      usage: `${commanderPath(groupCommand).join(' ')} --help -f yaml`,
+    },
+  };
+}
+
+export function installCommanderNamespaceStructuredHelp(
+  namespaceRoot: Command,
+  opts: { globalCommand?: Command; description?: string } = {},
+): void {
+  installStructuredHelp(namespaceRoot, () => commanderNamespaceHelpData(namespaceRoot, opts));
+  for (const command of collectDescendantCommands(namespaceRoot)) {
+    if (command.commands.length > 0) {
+      installStructuredHelp(command, () => commanderGroupHelpData(namespaceRoot, command, opts));
+    } else {
+      installStructuredHelp(command, () => commanderCommandHelpData(namespaceRoot, command, opts));
+    }
+  }
+}
+
 function positionals(cmd: CliCommand): Arg[] {
   return cmd.args.filter(arg => arg.positional);
 }
