Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

22.0 KB
Raw Blame
import { Command, type Argument as CommanderArgument, type Option as CommanderOption } from 'commander';
import yaml from 'js-yaml';
import { OUTPUT_FORMATS } from './output-format.js';
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>',
    name: 'format',
    help: 'Output format: table, plain, json, yaml, md, csv',
    default: 'json',
    choices: OUTPUT_FORMATS,
  },
  {
    flags: '--trace <mode>',
    name: 'trace',
    help: 'Trace capture: off, on, retain-on-failure',
    default: 'off',
    choices: ['off', 'on', 'retain-on-failure'],
  },
  {
    flags: '-v, --verbose',
    name: 'verbose',
    help: 'Debug output',
    default: false,
  },
  {
    flags: '-h, --help',
    name: 'help',
    help: 'display help for command',
  },
] as const;

const BROWSER_COMMON_OPTIONS = [
  {
    flags: '--window <mode>',
    name: 'window',
    help: 'Browser window mode: foreground or background',
    choices: ['foreground', 'background'],
  },
  {
    flags: '--site-session <mode>',
    name: 'site-session',
    help: 'Adapter site session lifecycle: ephemeral or persistent',
    choices: ['ephemeral', 'persistent'],
  },
  {
    flags: '--keep-tab <bool>',
    name: 'keep-tab',
    help: 'Keep the browser tab lease after the command finishes',
    choices: ['true', 'false'],
  },
] as const;

function normalizeStructuredHelpFormat(value: string | undefined): StructuredHelpFormat | undefined {
  const normalized = value?.toLowerCase();
  if (normalized === 'yaml' || normalized === 'yml') return 'yaml';
  if (normalized === 'json') return 'json';
  return undefined;
}

export function getRequestedHelpFormat(argv: readonly string[] = process.argv): StructuredHelpFormat | undefined {
  for (let i = 0; i < argv.length; i++) {
    const token = argv[i];
    if (token === '-f' || token === '--format') {
      return normalizeStructuredHelpFormat(argv[i + 1]);
    }
    if (token.startsWith('--format=')) {
      return normalizeStructuredHelpFormat(token.slice('--format='.length));
    }
    if (token.startsWith('-f') && token.length > 2) {
      return normalizeStructuredHelpFormat(token.slice(2));
    }
  }
  return undefined;
}

export function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string {
  if (format === 'json') return `${JSON.stringify(data, null, 2)}\n`;
  return yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true });
}

export function wrapCommaList(
  items: readonly string[],
  opts: { width?: number; indent?: string } = {},
): string {
  const width = Math.max(opts.width ?? process.stdout.columns ?? 100, 40);
  const indent = opts.indent ?? '  ';
  const sorted = [...items].sort((a, b) => a.localeCompare(b));
  const lines: string[] = [];
  let line = indent;

  sorted.forEach((item, index) => {
    const token = `${item}${index < sorted.length - 1 ? ',' : ''}`;
    const prefix = line === indent ? '' : ' ';
    if (line.length + prefix.length + token.length > width && line.trim()) {
      lines.push(line);
      line = `${indent}${token}`;
    } else {
      line += `${prefix}${token}`;
    }
  });
  if (line.trim()) lines.push(line);
  return lines.join('\n');
}

export interface RootAdapterGroups {
  /** Web-site adapters (bilibili, dianping, ...) */
  sites: readonly string[];
}

function formatGroupSection(label: string, names: readonly string[]): string[] {
  if (names.length === 0) return [];
  return [
    `${label} (${names.length}):`,
    wrapCommaList(names),
    '',
  ];
}

export function formatRootAdapterHelpText(groups: RootAdapterGroups): string {
  const total = groups.sites.length;
  if (total === 0) return '';
  const lines: string[] = [''];
  lines.push(...formatGroupSection('Site adapters', groups.sites));
  lines.push("Run 'opencli list' for full command details, or 'opencli <site> --help' to inspect one site.");
  lines.push("Agent tip: use 'opencli <site> --help -f json' for all command args/options in one structured response.");
  lines.push('');
  return lines.join('\n');
}

function compactArg(arg: Arg): Record<string, unknown> {
  return {
    name: arg.name,
    ...(arg.type && arg.type !== 'string' ? { type: arg.type } : {}),
    ...(arg.positional ? { positional: true } : {}),
    ...(arg.required ? { required: true } : {}),
    ...(arg.valueRequired ? { valueRequired: true } : {}),
    ...(arg.default !== undefined ? { default: arg.default } : {}),
    ...(arg.choices?.length ? { choices: arg.choices } : {}),
    ...(arg.help ? { help: arg.help } : {}),
  };
}

function compactCommonOption(option: typeof COMMON_OPTIONS[number] | typeof BROWSER_COMMON_OPTIONS[number]): Record<string, unknown> {
  return {
    name: option.name,
    flags: option.flags,
    help: option.help,
    ...('default' in option ? { default: option.default } : {}),
    ...('choices' in option ? { choices: option.choices } : {}),
  };
}

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);
}

/**
 * Extracts a positional placeholder that should appear immediately after this
 * command's name in user-facing path strings. Reads the leading positional
 * (e.g. `<session>`) from a `.usage()` override; commands without a positional
 * override return `null` so the path stays as-is.
 *
 * Example: `browser` declares `.usage('<session> <command> [options]')`,
 * so `commanderPath(browserClickCmd)` becomes
 * `['opencli', 'browser', '<session>', 'click']`.
 */
export function leadingPositionalFromUsage(command: Command): string | null {
  const usage = (command as Command & { _usage?: string })._usage;
  if (!usage) return null;
  const match = usage.match(/^\s*(<[^>]+>)/);
  return match ? match[1] : 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);
      // If this command declares a leading-positional usage override AND we
      // have already collected a child name below it, the positional must
      // appear between this command and the child (i.e. before the names
      // already collected). parts is in reverse order, so push to the end.
      const positional = leadingPositionalFromUsage(current);
      if (positional && parts.length > 1) {
        // We collected child names first (reverse order). Move them up by one
        // and put the positional at index `parts.length - 2` so reverse()
        // places it between this command and the first child name.
        parts.splice(parts.length - 1, 0, positional);
      }
    }
    current = current.parent;
  }
  return parts.reverse();
}

function commandPathFromRoot(namespaceRoot: Command, command: Command): string[] {
  const rootPath = commanderPath(namespaceRoot);
  const commandPath = commanderPath(command);
  // Strip placeholder positional segments (e.g. `<session>`) from the relative
  // name so agents can still address subcommands by their leaf name. Display
  // paths in `command` / `usage` still include the placeholders.
  return commandPath.slice(rootPath.length).filter(part => !/^<.+>$/.test(part));
}

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(' ')));
  // Respect commander's `.usage()` override (e.g. `<session> <command> [options]`
  // on `browser`); fall back to the generic `<command> [args] [options]` form.
  // Read the private `_usage` field directly because `.usage()` returns the
  // auto-generated form if no override was set.
  const commandPath = commanderPath(namespaceRoot).join(' ');
  const usageOverride = (namespaceRoot as Command & { _usage?: string })._usage;
  const usage = usageOverride
    ? `${commandPath} ${usageOverride}`
    : `${commandPath} <command> [args] [options]`;
  return {
    namespace: namespaceRoot.name(),
    command: commandPath,
    usage,
    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: `${commandPath} --help -f json`,
    },
  };
}

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 json`,
    },
  };
}

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 json`,
    },
  };
}

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);
}

function commandOptions(cmd: CliCommand): Arg[] {
  return cmd.args.filter(arg => !arg.positional);
}

function formatPositionals(args: readonly Arg[]): string {
  return args
    .map(arg => arg.required ? `<${arg.name}>` : `[${arg.name}]`)
    .join(' ');
}

function formatCommandOptionTerm(arg: Arg): string {
  if (arg.required || arg.valueRequired) return `--${arg.name} <value>`;
  return `--${arg.name} [value]`;
}

export function formatCommandListTerm(cmd: CliCommand): string {
  const positionalText = formatPositionals(positionals(cmd));
  const optionText = commandOptions(cmd).length > 0 ? ' [options]' : '';
  return `${cmd.name}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
}

function formatUsage(cmd: CliCommand): string {
  const positionalText = formatPositionals(positionals(cmd));
  return `opencli ${cmd.site} ${cmd.name}${positionalText ? ` ${positionalText}` : ''} [options]`;
}

function compactCommand(cmd: CliCommand): Record<string, unknown> {
  return {
    name: cmd.name,
    command: `opencli ${cmd.site} ${cmd.name}`,
    usage: formatUsage(cmd),
    access: cmd.access,
    description: cmd.description,
    browser: !!cmd.browser,
    ...(cmd.domain ? { domain: cmd.domain } : {}),
    ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
    positionals: positionals(cmd).map(compactArg),
    command_options: commandOptions(cmd).map(compactArg),
    ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
    example: formatCommandExample(cmd),
    ...(cmd.siteSession ? { siteSession: cmd.siteSession } : {}),
    defaultFormat: 'json',
    ...(cmd.columns?.length ? { columns: cmd.columns } : {}),
  };
}

export function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown> {
  const adapterNames = new Set<string>([...groups.sites]);
  const commands = program.commands
    .filter(command => !adapterNames.has(command.name()))
    .map(command => ({
      name: command.name(),
      description: command.description(),
    }));

  const sortLocale = (a: string, b: string) => a.localeCompare(b);
  return {
    name: program.name(),
    description: program.description(),
    commands,
    site_adapters: {
      count: groups.sites.length,
      sites: [...groups.sites].sort(sortLocale),
    },
    next: [
      'opencli <site> --help -f json',
      'opencli list <query>',
      'opencli <site> <command>',
    ],
  };
}

export function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown> {
  const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
    .sort((a, b) => a.name.localeCompare(b.name));
  return {
    site,
    command_count: unique.length,
    commands: unique.map(cmd => compactCommand(cmd)),
    common_options: COMMON_OPTIONS.map(compactCommonOption),
    ...(unique.some(cmd => cmd.browser) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
    next: [
      `opencli ${site} <command> --help -f json`,
      `opencli ${site} <command>`,
    ],
  };
}

export function commandHelpData(cmd: CliCommand): Record<string, unknown> {
  return {
    site: cmd.site,
    ...compactCommand(cmd),
    common_options: COMMON_OPTIONS.map(compactCommonOption),
    ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
    output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
  };
}

function formatRows(rows: readonly [string, string][]): string[] {
  if (rows.length === 0) return [];
  const width = Math.min(Math.max(...rows.map(([left]) => left.length)), 34);
  return rows.map(([left, right]) => `  ${left.padEnd(width + 2)}${right}`);
}

function formatArgHelp(arg: Arg): string {
  const parts: string[] = [];
  if (arg.help) parts.push(arg.help);
  if (arg.default !== undefined) parts.push(`default: ${arg.default}`);
  if (arg.choices?.length) parts.push(`choices: ${arg.choices.join(', ')}`);
  return parts.join('  ');
}

export function formatCommonOptionsHelpText(): string {
  const rows = COMMON_OPTIONS.map(option => {
    const details: string[] = [option.help];
    if ('default' in option) details.push(`default: ${option.default}`);
    if ('choices' in option) details.push(`choices: ${option.choices.join(', ')}`);
    return [option.flags, details.join('  ')] as [string, string];
  });
  return ['Common options:', ...formatRows(rows)].join('\n');
}

export function formatBrowserCommonOptionsHelpText(): string {
  const rows = BROWSER_COMMON_OPTIONS.map(option => {
    const details: string[] = [option.help];
    if ('choices' in option) details.push(`choices: ${option.choices.join(', ')}`);
    return [option.flags, details.join('  ')] as [string, string];
  });
  return ['Browser common options:', ...formatRows(rows)].join('\n');
}

export function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string {
  const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
    .sort((a, b) => a.name.localeCompare(b.name));
  const lines: string[] = [
    `Usage: opencli ${site} <command> [args] [options]`,
    '',
    wrapCommaList(unique.map(cmd => cmd.name), { indent: '' }),
    '',
    'Commands:',
    ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
    '',
    formatCommonOptionsHelpText(),
    ...(unique.some(cmd => cmd.browser) ? ['', formatBrowserCommonOptionsHelpText()] : []),
    '',
    `Agent tip: use 'opencli ${site} --help -f json' to get all command args/options in one structured response.`,
    '',
  ];
  return lines.join('\n');
}

export function formatCommandHelpText(cmd: CliCommand): string {
  const lines: string[] = [
    `Usage: ${formatUsage(cmd)}`,
    '',
    cmd.description,
    '',
  ];

  const positionalRows = positionals(cmd).map(arg => [
    arg.name,
    formatArgHelp(arg),
  ] as [string, string]);
  if (positionalRows.length) {
    lines.push('Arguments:', ...formatRows(positionalRows), '');
  }

  const optionRows = commandOptions(cmd).map(arg => [
    formatCommandOptionTerm(arg),
    formatArgHelp(arg),
  ] as [string, string]);
  if (optionRows.length) {
    lines.push('Command options:', ...formatRows(optionRows), '');
  }

  lines.push(formatCommonOptionsHelpText(), '');
  if (cmd.browser) lines.push(formatBrowserCommonOptionsHelpText(), '');

  const meta: string[] = [];
  meta.push(`Access: ${cmd.access}`);
  meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
  if (cmd.domain) meta.push(`Domain: ${cmd.domain}`);
  meta.push('Default format: json');
  if (cmd.aliases?.length) meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
  lines.push(meta.join(' | '));
  lines.push(`Example: ${formatCommandExample(cmd)}`);
  if (cmd.columns?.length) lines.push(`Output columns: ${cmd.columns.join(', ')}`);
  lines.push("Agent tip: use '--help -f json' for structured args/options.");
  lines.push('');
  return lines.join('\n');
}

export function installStructuredHelp(
  command: Command,
  data: () => unknown,
  textSuffix?: string | (() => string),
): void {
  const original = command.helpInformation.bind(command);
  command.helpInformation = ((contextOptions?: unknown) => {
    const format = getRequestedHelpFormat();
    if (format) return renderStructuredHelp(data(), format);
    const suffix = typeof textSuffix === 'function' ? textSuffix() : textSuffix ?? '';
    return original(contextOptions as never) + suffix;
  }) as Command['helpInformation'];
}

export function formatSiteCommandDescription(cmd: CliCommand): string {
  const access = cmd.access === 'write' ? '[write]' : '[read]';
  return `${access} ${cmd.description}`;
}