Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.0 KB
Raw Blame
/**
 * Shared `gbrain <verb> [--flag ...]` scanner for the doc↔CLI truth checks
 * (test/docs-cli-commands.test.ts, test/remediation-command-resolution.test.ts).
 *
 * One definition of "a live verb", "command position", "code regions of a
 * markdown file" and "does this invocation's argv pass the real flag
 * validator", so both gates agree on the CLI surface by construction.
 *
 * Flags are checked by the production pipeline itself: parseGlobalFlags
 * (strips --brain/--quiet/--progress-*) followed by validateCommandFlags
 * (op commands: op.params + CLI-local flags; CLI_ONLY commands: the generated
 * CLI_FLAG_REGISTRY row). Limitations inherited from that validator: CLI_ONLY
 * flags are per top-level command, not per subcommand, and commands it exempts
 * (`call`, `config`, `jobs submit`, `eval brainbench`) are verb-checked only.
 *
 * Plain helper: no env mutation, no engine, no network.
 */
import { routeCommand } from '../../src/cli/command-route.ts';
import { CLI_ONLY, cliAliases, validateCommandFlags } from '../../src/cli/main.ts';
import { parseGlobalFlags } from '../../src/core/cli-options.ts';
import { migrationCliArgumentError } from '../../src/core/embedding-migration-cli.ts';
import { operations } from '../../src/core/operations.ts';

/** Every verb the dispatcher accepts: CLI_ONLY, non-hidden op names, aliases. */
export function liveCliVerbs(): Set<string> {
  const valid = new Set<string>(CLI_ONLY);
  for (const op of operations) {
    const name = op.cliHints?.name;
    if (name && !op.cliHints?.hidden) valid.add(name);
  }
  for (const alias of cliAliases.keys()) valid.add(alias);
  return valid;
}

/** True when `gbrain` sits at command position (not mid-prose). */
export function commandPosition(prefix: string): boolean {
  const p = prefix.trimEnd();
  return p === '' || /[|;&`(={[]$/.test(p) || /\$$/.test(p);
}

/**
 * Marker that exempts one example from the truth check because it documents
 * an older release's CLI. Place it on the line directly above a code fence
 * (covers the whole block) or on/above a line with inline code.
 */
export const HISTORICAL_MARKER = '<!-- gbrain-cli: historical -->';

export interface CodeLine { code: string; line: number; historical: boolean }

/**
 * Fenced-block lines (backslash continuations joined) + inline code spans
 * that START with `gbrain `. Comment and ASCII-diagram lines are skipped.
 */
export function codeRegions(text: string): CodeLine[] {
  const out: CodeLine[] = [];
  const lines = text.split('\n');
  const markedAbove = (i: number) => i > 0 && lines[i - 1]!.includes(HISTORICAL_MARKER);
  let inFence = false;
  let fenceHistorical = false;
  for (let i = 0; i < lines.length; i++) {
    const l = lines[i]!;
    if (/^\s*(```|~~~)/.test(l)) {
      inFence = !inFence;
      fenceHistorical = inFence && markedAbove(i);
      continue;
    }
    if (inFence) {
      const t = l.trim();
      if (/^(#|\/\/|--|\*)/.test(t)) continue;
      if (/[│┌┐└┘├┤─═╔╗╚╝]/.test(l)) continue;
      let code = l;
      const start = i;
      while (/\\\s*$/.test(code) && i + 1 < lines.length && !/^\s*(```|~~~)/.test(lines[i + 1]!)) {
        code = code.replace(/\\\s*$/, ' ') + lines[++i]!.trim();
      }
      out.push({ code, line: start + 1, historical: fenceHistorical });
      continue;
    }
    const historical = l.includes(HISTORICAL_MARKER) || markedAbove(i);
    for (const m of l.matchAll(/`(gbrain [^`]+)`/g)) out.push({ code: m[1]!, line: i + 1, historical });
  }
  return out;
}

export interface Invocation { verb: string; argv: string[] }

/** `gbrain <verb>` invocations at command position, with their argv up to the next shell operator. */
export function gbrainInvocations(code: string): Invocation[] {
  const out: Invocation[] = [];
  for (const m of code.matchAll(/\bgbrain\s+([A-Za-z][\w-]*)/g)) {
    const verb = m[1]!;
    if (!/^[a-z][a-z0-9_-]{2,}$/.test(verb)) continue;
    if (!commandPosition(code.slice(0, m.index))) continue;
    if (verb === 'notice' && code[m.index! - 1] === '[') continue; // `[gbrain notice <code> …]` block prefix, not a command
    out.push({ verb, argv: shellWords(code.slice(m.index! + m[0].length - verb.length)) });
  }
  return out;
}

/**
 * Shell-ish word split of one command: honors quotes, stops at an unquoted
 * pipe/list/redirect/substitution boundary or `#` comment. `[...]` optional
 * groups are unwrapped (their inner `|` is alternation, not a pipe).
 * Placeholder words (`<slug>`, `$VAR`, `{a,b}`, `N`, `CLIENT_ID`) become `1`,
 * a value every typed parser (ids, counts, costs, brain names) accepts.
 */
function shellWords(s: string): string[] {
  const words: string[] = [];
  let cur = '';
  let has = false;
  let depth = 0;
  const flush = () => {
    if (has) words.push(/^[A-Z][A-Z0-9_]*$/.test(cur) ? '1' : cur.replace(/^(--[a-z0-9-]+=)?[<${].*$/i, '$11'));
    cur = '';
    has = false;
  };
  for (let i = 0; i < s.length; i++) {
    const c = s[i]!;
    if (c === "'" || c === '"') {
      const end = s.indexOf(c, i + 1);
      cur += end === -1 ? s.slice(i + 1) : s.slice(i + 1, end);
      has = true;
      if (end === -1) break;
      i = end;
      continue;
    }
    if (c === '[') { depth++; continue; }
    if (c === ']') { depth = Math.max(0, depth - 1); continue; }
    if (/\s/.test(c)) { flush(); continue; }
    if (c === '|' && depth > 0) { flush(); continue; }
    if (/[|;&`)]/.test(c) || (c === '>' && !cur.startsWith('<')) || (c === '#' && !has)) break;
    if (c === '<' && !has && /^<\s/.test(s.slice(i))) break;
    cur += c;
    has = true;
  }
  flush();
  return words.filter((w) => w !== '...' && w !== '…');
}

/**
 * Routes src/cli.ts main() dispatches BEFORE the unknown-flag validator runs:
 * their handlers parse their own flags, so only the verb is checked here.
 */
function dispatchedBeforeValidation(command: string, subArgs: string[]): boolean {
  if (command === 'search') return ['modes', 'stats', 'tune', 'diagnose'].includes(subArgs[0] ?? '');
  if (command === 'sources') return ['inspect', 'connect'].includes(subArgs[0] ?? '')
    || (subArgs[0] === 'demo' && subArgs[1] === 'company-brain');
  return false;
}

/**
 * Run an invocation through the production global-flag parser and the
 * pre-dispatch argument validators, in main()'s order. Returns the reason the
 * real CLI would reject it, or null when it accepts its flags.
 */
export function flagRejection(inv: Invocation): string | null {
  let rest: string[];
  try {
    rest = parseGlobalFlags(inv.argv).rest;
  } catch (e) {
    return (e as Error).message;
  }
  const [typed, ...typedArgs] = rest;
  if (!typed || typedArgs.some((a) => a === '--help' || a === '-h')) return null;
  const { command, subArgs } = routeCommand(typed === 'ask' ? 'query' : typed, typedArgs);
  if (dispatchedBeforeValidation(command, subArgs)) return null;
  const migrationError = migrationCliArgumentError(command, subArgs);
  if (migrationError) return migrationError.message;
  const flag = validateCommandFlags(command, subArgs);
  return flag ? `unknown flag ${flag} for 'gbrain ${typed}'` : null;
}