Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.1 KB
Raw Blame
/**
 * Subcommand inventories and the help grammar (#6114).
 *
 * Each router command exports its inventory as `SUBCOMMANDS` (re-exported
 * from here, so cli.ts can read them without loading the routers). The
 * router types its dispatch over the inventory, so a subcommand the router
 * handles but the inventory omits fails typecheck, and the help gate
 * (test/cli-help-no-side-effects*.serial.test.ts) runs every listed
 * subcommand's help.
 *
 * Help grammar: `--help` / `-h` anywhere before `--` asks for help, even in
 * a flag-value slot (`--older-than --help`). A bare `help` asks for help only
 * as the first token after a router command (`pages help`) or after one of
 * its subcommands (`pages purge-deleted help`); anywhere else (a free-text
 * query such as `search help`, a flag value) it is an ordinary argument.
 * Help never runs the subcommand: cli.ts prints the router's usage and
 * returns before startup side effects, strict argument checks and engine
 * access.
 */
export const PAGES_SUBCOMMANDS = ['purge-deleted', 'purges', 'unpurge', 'unsearchable', 'ghosts', 'status'] as const;
export const CACHE_SUBCOMMANDS = ['stats', 'clear', 'prune'] as const;
export const INTEGRITY_SUBCOMMANDS = ['check', 'auto', 'review', 'reset-progress'] as const;
export const HOOK_SUBCOMMANDS = ['session-start', 'user-prompt', 'stop', 'session-end', 'compact'] as const;
export const SEARCH_SUBCOMMANDS = ['modes', 'stats', 'tune', 'diagnose'] as const;
export const EDGE_PROPOSALS_SUBCOMMANDS = ['list', 'show', 'accept', 'reject', 'undo', 'date', 'retry'] as const;
export const MEMORY_PROPOSALS_SUBCOMMANDS = ['list', 'show', 'approve', 'deny'] as const;
export const CONFIG_SUBCOMMANDS = ['show', 'get', 'set', 'unset'] as const;
export const QUARANTINE_SUBCOMMANDS = ['list', 'clear', 'scan', 'release', 'drop'] as const;
export const CORE_SUBCOMMANDS = ['list', 'show', 'status', 'add', 'remove', 'diff', 'ack', 'init', 'suggest'] as const;
export const LOOPS_SUBCOMMANDS = ['list', 'show', 'done', 'drop', 'mute', 'unmute'] as const;
export const GUESTS_SUBCOMMANDS = ['init', 'promote', 'grant-owner-clients'] as const;
export const SCHEMA_SUBCOMMANDS = [
  'active', 'list', 'show', 'validate', 'use', 'detect', 'suggest', 'review-candidates', 'init', 'fork', 'edit',
  'diff', 'graph', 'lint', 'explain', 'review-orphans', 'downgrade', 'usage', 'stats', 'cardinality-preview',
  'sync', 'reload', 'add-type', 'remove-type', 'update-type', 'add-alias', 'remove-alias', 'add-prefix',
  'remove-prefix', 'add-link-type', 'remove-link-type', 'set-extractable', 'set-expert-routing', 'scaffold-extractable',
] as const;

export interface RouterInventory {
  subcommands: readonly string[];
  /**
   * The router's first argument is a subcommand, so a bare `help` there asks
   * for help. False for `search`, whose first argument is otherwise a query.
   */
  bareHelpFirst: boolean;
}

/** Every router command with an inventory, keyed by command name. */
export const ROUTERS: Readonly<Record<string, RouterInventory>> = {
  pages: { subcommands: PAGES_SUBCOMMANDS, bareHelpFirst: true },
  cache: { subcommands: CACHE_SUBCOMMANDS, bareHelpFirst: true },
  integrity: { subcommands: INTEGRITY_SUBCOMMANDS, bareHelpFirst: true },
  hook: { subcommands: HOOK_SUBCOMMANDS, bareHelpFirst: true },
  search: { subcommands: SEARCH_SUBCOMMANDS, bareHelpFirst: false },
  'edge-proposals': { subcommands: EDGE_PROPOSALS_SUBCOMMANDS, bareHelpFirst: true },
  'memory-proposals': { subcommands: MEMORY_PROPOSALS_SUBCOMMANDS, bareHelpFirst: true },
  schema: { subcommands: SCHEMA_SUBCOMMANDS, bareHelpFirst: true },
  config: { subcommands: CONFIG_SUBCOMMANDS, bareHelpFirst: true },
  quarantine: { subcommands: QUARANTINE_SUBCOMMANDS, bareHelpFirst: true },
  // #6521: these two were SELF_HELP_WITHOUT_ENGINE entries whose handlers answered help only as the first token,
  // so `core list --help` ran `list` against a null engine and `loops show --help` exited 2 "needs a loop id".
  core: { subcommands: CORE_SUBCOMMANDS, bareHelpFirst: true },
  loops: { subcommands: LOOPS_SUBCOMMANDS, bareHelpFirst: true },
  guests: { subcommands: GUESTS_SUBCOMMANDS, bareHelpFirst: true },
};

/** `--help` / `-h` before any `--` terminator. */
export function helpFlagRequested(args: readonly string[]): boolean {
  for (const a of args) {
    if (a === '--') return false;
    if (a === '--help' || a === '-h') return true;
  }
  return false;
}

/**
 * True when `args` (the tokens after the command) ask for help under the
 * grammar above. `router` is the command's inventory, or undefined for a
 * command without subcommands (only the flags count there).
 */
export function subcommandHelpRequested(args: readonly string[], router?: RouterInventory): boolean {
  if (helpFlagRequested(args)) return true;
  if (!router) return false;
  if (router.bareHelpFirst && args[0] === 'help') return true;
  return router.subcommands.includes(args[0] ?? '') && args[1] === 'help';
}

/** The help decision for `gbrain <command> ...args`, made once in cli.ts before any side effect. */
export function cliHelpRequested(command: string, args: readonly string[]): boolean {
  return subcommandHelpRequested(args, ROUTERS[command]);
}