Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
25.2 KB
Raw Blame
/**
 * #7619: `--flag=value` on CLI_ONLY commands. The unknown-flag validator
 * accepts the `=` form of every registered flag, but most handlers read only
 * `--flag value` (`args.includes`, `args[args.indexOf(flag) + 1]`), so the
 * value was dropped with no error: `serve --access=read-only` served every
 * write tool, `auth create --scopes=read` minted a full-access token. The
 * CLI entry never lets an `=` token reach a handler that would drop it:
 *  - refuse (invalid_params, exit 2) a switch: a boolean in the command's own
 *    table (curated help, the sync flag table), a `--no-` negation, the
 *    command's COMMAND_SWITCHES, or a name whose shared-op parameter or
 *    curated flag is boolean. Splitting turns the switch on and keeping drops
 *    the value (`--dry-run=true` would write). Without the command's own
 *    table, that cross-command evidence picks the bare-switch message, so
 *    `--yes=n` is never answered with `--yes <value>`;
 *  - without the command's own table, refuse a true/false word or 0/1
 *    (`--apply=false`) naming both readings, so it never suggests
 *    `--apply false` (which turns a switch on) and says a value never turns
 *    a switch off;
 *  - after a bare `--` the handler reads past, refuse an `=` token that is
 *    not a registered flag: the unknown-flag validator stops at `--`;
 *  - keep the token where the handler on this path reads the `=` form
 *    (EQUALS_READERS, keyed by command or `command sub`), empty values
 *    included: that handler owns refusing them;
 *  - on a path that reads no value flag (NO_VALUE_FLAG_PATHS), refuse a
 *    value flag with advice to leave it out;
 *  - elsewhere, refuse an empty value or one that looks like a flag (`-y`, `--x`);
 *  - split `--flag value` when the command's own table declares a value;
 *  - refuse every other `=` form with the separate-token spelling. Splitting
 *    a flag the subcommand never reads would leave its value as a stray
 *    positional, which handlers that take the first numeric or non-flag token
 *    as their target would act on (`forget --purge --reason=3 34` purging
 *    fact 3). Keeping it whole is safe only where every path of the command
 *    reads the `=` form, and evidence from one module does not show that for
 *    its sibling subcommands (`extract links --source-id=x` walked every
 *    source while `extract --stale` validated the same token).
 * `--json=true` becomes `--json` (the agent contract's JSON spelling, read
 * the same way by jsonRequested). Refusals name `--flag=…`, never the value,
 * which may be a credential. A short flag never takes `=` (`-y=n` is refused,
 * never taken as consent); a quoted argument with whitespace that only starts
 * like one (`capture "-n=3 is the answer"`) is text. `agent run` scans only
 * where parseRunFlags reads flags: the leading flag zone (its switches, its value
 * flags with their value, which passes untouched, and flag-shaped `--x=`
 * tokens, so `--tools=bash, read` still refuses) and, when the prompt holds no
 * bare `--`, the trailing switches it hoists, exact or with an `=` value and
 * no whitespace (`--detach=true` there refuses); the prompt between them is
 * text, except that up to its first bare `--` one of its value flags written
 * with `=` (any value) or a switch written with `=` and no whitespace refuses
 * (`agent run --json --tools=read ...` would hand the job every tool), with
 * advice to write it before the prompt or put `--` before the prompt. OWN_EQUALS_PARSERS pass their argv through. On a
 * command with a registry row, unregistered flags keep the token for the
 * validator to name; on a path with none (the hand-parsed search
 * subcommands), every `=` token but `--json=true` refuses with a neutral
 * message that names the subcommand, echoes no value and vouches for no
 * switch. A bare `--` ends the scan only on a path whose handler stops there
 * (END_OF_OPTIONS, keyed by `command sub`): `serve`, `auth`,
 * `frontmatter generate`, `questions` and `agent logs` read flags after it.
 */
import type { OperationError } from '../core/ops/contract.ts';
import { CLI_FLAG_REGISTRY } from '../core/cli-flag-registry.generated.ts';
import { unknownFlagError, usageError } from './cli-error.ts';
import { loadCuratedHelp } from './help/render.ts';
import { OPERATION_MANIFEST } from '../core/operation-manifest.generated.ts';
import { SYNC_FLAGS } from '../core/sync-flags.ts';
import { parseGlobalFlags, setCliOptions } from '../core/cli-options.ts';

/**
 * Where the handler on a path reads the `=` form itself, keyed by command or
 * `command sub` (the narrowest key every path under it honors): the token is
 * kept as written. Pinned by test/cli-flag-equals.test.ts against every module
 * that reads an `=` form.
 */
export const EQUALS_READERS: Readonly<Record<string, readonly string[]>> = {
  // beliefs.ts:61 sourceArg runs before the sub branch (beliefs.ts:98) for every subcommand.
  beliefs: ['--source'],
  // beliefs.ts:52 beliefsChangesArgs (also the thin-client route, thin-client-routing.ts:85).
  'beliefs changes': ['--since'],
  // beliefs-replay-purges.ts:14 flag() reads --x v and --x=v.
  'beliefs replay-purges': ['--archived-at', '--purge-mirror', '--from-url-env'],
  // core/consent.ts:126 via consentGateOrExit (book-mirror.ts:431, args :440, effects paid); book-mirror reads no --max-* itself.
  'book-mirror': ['--max-usd', '--max-cost'],
  // cli/commands/bundled-skill.ts:51 reads --asset <p> and --asset=<p>, and refuses an empty value itself.
  'bundled-skill': ['--asset'],
  // capture.ts:96 regex; every other = form is refused by capture's own parser (capture.ts:132).
  capture: ['--request-id', '--expected-revision'],
  // check-resolvable.ts:120 parseFlags.
  'check-resolvable': ['--skills-dir'],
  // code-scope.ts:64 parseFlag (code-callees.ts:46-48, code-callers.ts:58-60, code-def.ts:166-172, code-refs.ts:109-115).
  'code-callees': ['--limit', '--source'],
  'code-callers': ['--limit', '--source'],
  'code-def': ['--limit', '--lang', '--source'],
  'code-refs': ['--limit', '--lang', '--source'],
  // compile-context.ts:74 flagValue (parseCompileFlags :88-115).
  'compile-context': ['--target', '--budget', '--include', '--out', '--source'],
  // core/consent.ts:123 parseConsentFlags via enableConsent (decide.ts:348, effects paid); decide reads no --max-* itself.
  'decide enable': ['--max-usd', '--max-cost'],
  // doctor/budget.ts:68 --tier/--budget-ms; cli/commands/doctor.ts:27 --tier (thin client); --scope is split (parseDoctorScope reads both forms, #7624);
  // doctor/registry.ts:332 --only; check-resolvable.ts:120 --skills-dir via doctor.ts:460; core/consent.ts:130 --expect (remediate-consent.ts:133).
  doctor: ['--tier', '--budget-ms', '--only', '--skills-dir', '--expect'],
  // edge-proposals.ts:81 flag() used only by list (:91,:93); other subs take the first numeric token as the id (:86).
  'edge-proposals list': ['--status', '--limit'],
  // memory-proposals.ts flag() reads list's --source/--limit and deny's --reason in both forms.
  'memory-proposals list': ['--source', '--limit'],
  'memory-proposals deny': ['--reason'],
  // embed.ts:841 parsePaceArgs (--pace bare or =mode); core/consent.ts:126 via embed-consent.ts:129 and held-embedding.ts:234.
  embed: ['--pace', '--pace-max-concurrency', '--max-usd', '--max-cost'],
  // eval-conversation-parser.ts:48-53 (main.ts handleCliOnly's eval conversation-parser branch and eval.ts:106 both reach it).
  'eval conversation-parser': ['--fixtures', '--min-recall'],
  // eval/decide-eval-flags.ts:122 extractDecideEvalFlags via eval-retrieval-quality.ts:38.
  'eval retrieval-quality': ['--decide', '--decide-provider', '--decide-calibration', '--decide-threshold', '--decide-force-on', '--decide-dataset'],
  // eval-takes-quality.ts:82 getFlag; union over run (:148-162) / trend (:200-201) / regress (:212-226); replay reads none.
  'eval takes-quality': ['--limit', '--cycles', '--budget-usd', '--slug-prefix', '--models', '--source', '--rubric-version', '--against', '--threshold'],
  // export.ts:18 option() (:95-99).
  export: ['--dir', '--source', '--type', '--slug-prefix', '--repo'],
  // core/consent.ts:126 via requireEmbedBackfillConsent (features.ts:306, --auto-fix paid fixes only).
  features: ['--max-usd', '--max-cost'],
  // recall.ts:1183-1188 runForget (plain) and forget-purge.ts:44 flagValue (:114-123, purge); --match is purge-only, ignored by plain forget in any form.
  forget: ['--request-id', '--source', '--match'],
  // forget-purge.ts:131 flagValue --reason (runForgetPurge, routed on --purge at recall.ts:1170); plain forget reads only the separate token (recall.ts:1181).
  'forget --purge': ['--reason', '--reason-scan-limit'],
  // frontmatter.ts:356 runValidate.
  'frontmatter validate': ['--path'],
  // frontmatter.ts:667 runAudit.
  'frontmatter audit': ['--source'],
  // frontmatter-install-hook.ts:184.
  'frontmatter install-hook': ['--source'],
  // graph-query.ts:56.
  'graph-query': ['--source'],
  // import.ts:377-395 readSourceFlag (+ :237 keyless refusal).
  import: ['--source', '--source-id'],
  // integrity.ts:857 extractFlag via cmdCheck (:306-307); integrity auto is STRICT.
  'integrity check': ['--limit', '--type'],
  // core/consent.ts:126 via jobs/submit.ts:104 requireEmbedBackfillConsent, :128 requireReindexConsent, :294 authorizePaidSubmit (paid); submit's own parseFlag(--max-usd) (:286) reads only the separate `off`.
  'jobs submit': ['--max-usd', '--max-cost'],
  // jobs/shared.ts:121 parseJobIsolationFlag via jobs/supervisor.ts:165.
  'jobs supervisor': ['--job-isolation'],
  // jobs/shared.ts:121 parseJobIsolationFlag via jobs/work.ts:114.
  'jobs work': ['--job-isolation'],
  // jobs/watch.ts parseRefreshMs reads --refresh-ms N and --refresh-ms=N (#7624).
  'jobs watch': ['--refresh-ms'],
  // lint.ts:929 runLint.
  lint: ['--exclude'],
  // migrate-graduation.ts:97 flagValue (parseGraduationArgs :121-151); graduation-only flags, the legacy copier (migrate-engine.ts) never reads them.
  migrate: ['--url-env', '--trigger-bypass', '--drain-timeout', '--batch-size', '--expect'],
  // models.ts parseSkipProviders, doctor mode only, repeated --skip <provider> or --skip=<provider> (#7624).
  'models doctor': ['--skip'],
  // core/bounded-listing-cli.ts:15 parseListingFlags via orphans.ts:353.
  orphans: ['--limit', '--cursor'],
  // pages-purges.ts:12 flagValue (:21) for purges and unpurge.
  'pages purges': ['--source'],
  'pages unpurge': ['--source'],
  // pages-unsearchable.ts:34 flagValue (:42-52).
  'pages unsearchable': ['--state', '--limit', '--source'],
  // pages-ghosts.ts:24.
  'pages ghosts': ['--source'],
  // pages-status.ts:77 parsePagesStatusArgs.
  'pages status': ['--source'],
  // recall.ts:156-201 parseFlags (--entity both, --source-id=, --question=, --budget-policy= with empty-value refusal).
  recall: ['--entity', '--source-id', '--question', '--budget-policy'],
  // reindex.ts:155-163 normalizeReindexArgs at entry (cli/commands/reindex.ts:12); --max-cost via core/consent.ts:126 (reindex-consent.ts:77).
  reindex: ['--type', '--limit', '--repo', '--workers', '--concurrency', '--max-usd', '--max-cost'],
  // core/consent.ts:126 via reindex-code.ts:503 / reindex-code-delegate.ts:51 (paid); the own --max-cost loop (reindex-code.ts:438) reads only the separate token and :521 takes the consent cap.
  'reindex-code': ['--max-usd', '--max-cost'],
  // core/consent.ts:130 --expect via consentGateOrExit (reinit-pglite.ts:109, plan_hash :119); parseArgs (:213) reads no --expect.
  'reinit-pglite': ['--expect'],
  // resolvers.ts:172 extractFlag via cmdList (:66-67).
  'resolvers list': ['--cost', '--backend'],
  // routing-eval.ts:83 parseFlags.
  'routing-eval': ['--skills-dir'],
  // schema.ts:457 parseFlags; only these subs use the parsed source (:208,:499,:542,:562,:872,:1043,:1080,:1103).
  'schema active': ['--source', '--source-id'],
  'schema detect': ['--source', '--source-id'],
  'schema suggest': ['--source', '--source-id'],
  'schema review-candidates': ['--source', '--source-id'],
  'schema review-orphans': ['--source', '--source-id'],
  'schema stats': ['--source', '--source-id'],
  'schema cardinality-preview': ['--source', '--source-id'],
  'schema sync': ['--source', '--source-id'],
  // schema.ts:765 runLintCmd strips both forms through parseFlags before util.parseArgs.
  'schema lint': ['--source', '--source-id'],
  // schema.ts:1138 runReloadCmd; schema.ts:1004 pickPackName for the pack-authoring subs (remove-* are STRICT, add-type is OWN).
  'schema reload': ['--pack'],
  'schema update-type': ['--pack'],
  'schema add-alias': ['--pack'],
  'schema add-prefix': ['--pack'],
  'schema add-link-type': ['--pack'],
  'schema set-extractable': ['--pack'],
  'schema set-expert-routing': ['--pack'],
  'schema scaffold-extractable': ['--pack'],
  // skillify.ts:117 parseScaffoldFlags (:142-160); skillify check reads no = form.
  'skillify scaffold': ['--description', '--triggers', '--writes-to', '--skills-dir'],
  // skillpack.ts:312 cmdStatus, :382 cmdSync, :501 cmdMigrateFence, :547 cmdScrubLegacy, :1210 cmdHarvest, :1281-1287 cmdDiff.
  'skillpack status': ['--workspace'],
  'skillpack sync': ['--workspace'],
  'skillpack migrate-fence': ['--workspace'],
  'skillpack scrub-legacy-fence-rows': ['--workspace'],
  'skillpack harvest': ['--from'],
  'skillpack diff': ['--workspace', '--skills-dir'],
  // skillpack/scaffold.ts:36 lane select + :73 --workspace=; harness lane skillpack/harness.ts:91-158 parseHarnessArgs (:364).
  'skillpack scaffold': ['--workspace', '--harness', '--persona', '--skill', '--dest', '--scope', '--skills'],
  // skillpack/reference.ts:44 harness lane (strict-args.ts:102 makes the non-harness lane STRICT); harness.ts:542; skillpack/update.ts readValue (--update-untouched lane).
  'skillpack reference': ['--harness', '--persona', '--skill', '--dest', '--scope', '--workspace', '--skills'],
  // core/bounded-listing-cli.ts:15 via sources.ts:1213 runStatus (+ :1214 paged regex).
  'sources status': ['--limit', '--cursor'],
  // sources-harden.ts:31 flagVal: runHarden (:83-84), runPull (:150-151). `sources pull --path=` refuses: main.ts takes the database-free route only on the exact token.
  'sources harden': ['--branch', '--pat-file'],
  'sources pull': ['--branch'],
  // status.ts:812 parseDeadlineFlag, :834 parseSectionFlag (runStatus :871-881).
  status: ['--section', '--deadline-ms'],
  // core/bounded-listing-cli.ts:15 via sync/operator.ts:167 holdsListing (+ :173 sized check); the `sync --status` alias (syncOperatorVerb, operator.ts:136) reads as this path.
  'sync status': ['--limit', '--cursor'],
  // trust-claim.ts:65 flagValues (:81, :113).
  'trust claim-sources': ['--source'],
  // core/stable-channel.ts:19 parseChannelArg via upgrade.ts:361.
  upgrade: ['--channel'],
};

/** Commands that run another command's handler on the same argv (`repos` is runSources, cli/commands/repos.ts:18): the = rule reads the target's keys. */
export const READER_ALIASES: Readonly<Record<string, string>> = { repos: 'sources' };

/**
 * Commands and subcommands whose handler parses `--flag value` and
 * `--flag=value` itself on every path, refusing `=` on its own switches:
 * cliOnlyFlagArgs in src/cli/main.ts passes their argv through unchanged
 * (pinned by test/cli-flag-equals.test.ts in both directions against every
 * `indexOf('=')` option parser). The sources lifecycle subcommands are not
 * here: on an unmanaged brain they fall back to runSources, which reads only
 * exact tokens.
 */
export const OWN_EQUALS_PARSERS: ReadonlySet<string> = new Set([
  'append', 'auth local-writer', 'eval longmemeval', 'git', 'google attachments', 'migrate embeddings', 'repair', 'retrieval-upgrade', 'schema add-type', 'skillpack remove',
  'sources connect', 'sources inspect', 'sources reconcile', 'sources reset-upstream', 'sources writer',
  'takes add', 'takes remove', 'takes resolve', 'takes supersede', 'takes update',
]);

/**
 * Switches a command reads with `args.includes` whose name takes a value
 * elsewhere, or that no shared switch evidence (curated help, the operation
 * manifest) covers: `agent` has no curated help, so its `--follow` and
 * `--detach` need an entry here. The command's own reading wins.
 */
export const COMMAND_SWITCHES: Readonly<Record<string, readonly string[]>> = {
  sync: ['--detail'],
  schema: ['--fields'],
  agent: ['--follow', '--detach'],
  dream: ['--unsafe-bypass-dream-guard'],
  embed: ['--stale'],
  'edge-proposals': ['--all-held', '--all-applied'],
};

/** Value flags of a command with no curated help that every path reads as `--flag <value>` (migrate-engine.ts parseArgs, migrate-graduation.ts flagValue and routesToGraduation); their `=` form splits. */
export const COMMAND_VALUES: Readonly<Record<string, readonly string[]>> = {
  migrate: ['--to', '--url'],
};

/**
 * Paths (`command sub`) whose handler reads no value flag, only switches and
 * positionals: an `=` value flag there refuses with advice to drop it, never
 * `--flag <value>`, because the separate value would become the target
 * (edge-proposals.ts takes the first numeric token as the proposal id, so
 * `accept --limit 5 12` acts on proposal 5).
 */
export const NO_VALUE_FLAG_PATHS: ReadonlySet<string> = new Set([
  'edge-proposals show', 'edge-proposals accept', 'edge-proposals reject', 'edge-proposals undo', 'edge-proposals date', 'edge-proposals retry',
]);

/** Paths (`command sub`) whose handler treats a bare `--` as the end of its options; everywhere else the scan continues past it. */
export const END_OF_OPTIONS: ReadonlySet<string> = new Set(['agent run', 'frontmatter validate']);

/** Switch evidence by name: shared-op boolean parameters (handler-free manifest) and boolean flags in any command's curated help. Loaded only when an `=` token needs it. */
let switches: Promise<ReadonlySet<string>> | undefined;
export function knownSwitches(): Promise<ReadonlySet<string>> {
  return switches ??= (async () => {
    const out = new Set<string>();
    for (const op of OPERATION_MANIFEST) for (const [name, p] of Object.entries(op.params)) if (p.type === 'boolean') out.add(`--${name.replace(/_/g, '-')}`);
    for (const command of Object.keys(CLI_FLAG_REGISTRY)) for (const f of (await loadCuratedHelp(command))?.flags ?? []) if (f.type === 'boolean') out.add(f.name);
    return out;
  })();
}

const EQUALS_TOKEN = /^(--[a-z0-9][a-z0-9-]*|-[A-Za-z])=([\s\S]*)$/;

export async function splitFlagEquals(command: string, args: readonly string[]): Promise<{ args: string[] } | { refusal: OperationError }> {
  if (!args.some(a => /^-[^=\s]*=/.test(a))) return { args: [...args] };
  const legal = CLI_FLAG_REGISTRY[command];
  const keyed = READER_ALIASES[command] ?? command;
  const sub = command === 'sync' && args[0] !== 'unblock' && args[0] !== 'trigger' && args.includes('--status') ? 'status' : command === 'forget' && args.includes('--purge') ? '--purge' : args[0];
  const readers = [...EQUALS_READERS[keyed] ?? [], ...EQUALS_READERS[`${keyed} ${sub}`] ?? []];
  let types: Map<string, string> | undefined;
  const out: string[] = [];
  const where = args[0] && !args[0].startsWith('-') ? `gbrain ${command} ${args[0]}` : `gbrain ${command}`;
  let pastDashDash = false;
  let promptAt = -1;
  let tailAt = args.length;
  const values = new Set<number>();
  if (command === 'agent' && args[0] === 'run') {
    const { RUN_VALUE_FLAGS, BOOLEAN_TAIL_FLAGS } = await import('../commands/agent.ts');
    for (promptAt = 1; promptAt < args.length; promptAt++) {
      const t = args[promptAt]!;
      if (RUN_VALUE_FLAGS.has(t)) values.add(++promptAt);
      else if (!BOOLEAN_TAIL_FLAGS.has(t) && !(t.startsWith('--') && EQUALS_TOKEN.test(t))) break;
    }
    const dashAt = args.indexOf('--', promptAt);
    if (dashAt < 0) while (tailAt > promptAt && BOOLEAN_TAIL_FLAGS.has(args[tailAt - 1]!.split('=')[0]!) && !/\s/.test(args[tailAt - 1]!)) tailAt--;
    const stray = args.slice(promptAt, dashAt < 0 ? tailAt : dashAt).map(t => /^(--[a-z0-9][a-z0-9-]*)=([\s\S]*)$/.exec(t)).find(m => m !== null && (RUN_VALUE_FLAGS.has(m[1]!) || BOOLEAN_TAIL_FLAGS.has(m[1]!) && !/\s/.test(m[2]!)))?.[1];
    if (stray) return { refusal: usageError(`gbrain agent: \`${stray}=…\`: agent run reads its flags before the prompt, so this would be prompt text.`, `Write ${RUN_VALUE_FLAGS.has(stray) ? `${stray} <value>` : stray} before the prompt and ahead of any word agent run does not read (such as --json or --yes), or put -- before the prompt to keep it as text.`) };
  }
  for (let i = 0; i < args.length; i++) {
    const token = args[i]!;
    if (token === '--' && END_OF_OPTIONS.has(`${command} ${args[0]}`)) return { args: [...out, ...args.slice(i)] };
    if (values.has(i)) { out.push(token); continue; }
    if (i === promptAt && promptAt < tailAt) { out.push(...args.slice(i, tailAt)); i = tailAt - 1; continue; }
    pastDashDash ||= token === '--';
    const m = EQUALS_TOKEN.exec(token);
    const flag = m?.[1];
    if (flag !== undefined && !flag.startsWith('--') && !/\s/.test(token)) {
      return { refusal: usageError(`gbrain ${command}: \`${flag}=…\`: a short flag takes no =.`, `Write ${flag} on its own, or ${flag} <value> with the value as the next argument.`) };
    }
    const registered = flag !== undefined && (!legal || legal.includes(flag) || flag.startsWith('--no-') && legal.includes(`--${flag.slice(5)}`));
    const unvalidated = pastDashDash && !registered && /^--[^=\s]+=/.exec(token);
    if (unvalidated) return { refusal: usageError(`gbrain ${command}: \`${unvalidated[0]}…\`: not a flag of this command, and its handler reads flags after --.`, 'Check the spelling: flags are lowercase words joined by hyphens.') };
    if (!m || !registered || readers.includes(flag)) { out.push(token); continue; }
    const value = m[2]!;
    if (flag === '--json' && value === 'true') { out.push(flag); continue; }
    types ??= new Map((await loadCuratedHelp(command))?.flags.map(f => [f.name, f.type]));
    const own = types.get(flag) ?? (command === 'sync' ? (SYNC_FLAGS as Record<string, { arity: string }>)[flag]?.arity : undefined) ?? (COMMAND_VALUES[command]?.includes(flag) ? 'string' : undefined);
    const isSwitch = own !== undefined ? own === 'boolean' : flag.startsWith('--no-') || COMMAND_SWITCHES[command]?.includes(flag) || (await knownSwitches()).has(flag);
    const refusal = !legal
      ? [`${where} reads no = form`, `Check the flag in ${where} --help: write a switch on its own (a value never turns it off), or a value as the next argument.`]
      : isSwitch
      ? [`${flag} is a switch and takes no value`, `Write ${flag} on its own, or leave it out.`]
      : NO_VALUE_FLAG_PATHS.has(`${keyed} ${sub}`)
      ? [`${where} does not read ${flag}`, `Leave ${flag} out: written as ${flag} <value>, the value would be read as a positional argument (such as an id).`]
      : value === '' || /^-[-A-Za-z]/.test(value)
        ? [`the value is empty or looks like a flag`, `Write ${flag} <value> with the value as the next argument.`]
        : own === undefined && /^(true|false|yes|no|y|n|on|off|0|1)$/i.test(value)
          ? [`write ${flag} on its own if it is a switch, or with its value as the next argument`, `If ${flag} is a switch, write it on its own to turn it on, or leave it out to turn it off: a value never turns it off. If it takes a value, put the value in the next argument.`]
          : own === undefined
          ? [`this command takes ${flag} <value> as two arguments`, `Write ${flag} <value>, or ${flag} on its own if it is a switch.`]
          : null;
    if (refusal) return { refusal: usageError(`gbrain ${command}: \`${flag}=…\`: ${refusal[0]}.`, refusal[1]!) };
    out.push(flag, value);
  }
  return { args: out };
}

/** CLI_ONLY lane: token scan against the generated legal set. */
export function findUnknownFlag(args: string[], legal: ReadonlySet<string>): string | null {
  for (const a of args) {
    if (a === '--') break;
    const m = /^--([a-z0-9][a-z0-9-]*)(?:=[\s\S]*)?$/i.exec(a);
    if (!m) continue;
    // Casing typo = unknown flag: every handler in the repo is
    // case-sensitive-lowercase, so `--MIGRATE-ONLY` passing validation would
    // just be silently ignored downstream — the exact class this validator
    // exists to kill.
    if (/[A-Z]/.test(m[1])) return `--${m[1]}`;
    const name = `--${m[1]}`;
    if (legal.has(name)) continue;
    // --no-<flag> negation of a known flag is legal.
    if (name.startsWith('--no-') && legal.has(`--${name.slice(5)}`)) continue;
    return name;
  }
  return null;
}

/** auth.ts's direct `bun run` entry, in main's order: global flags stripped and applied, the `=` rule (`command sub` own `=` parsers pass through; auth has no whole-command own parser, strict spec or exempt path), and main's unknown-flag check with its envelope (legacy keys included). */
export async function directEntryArgs(command: string, raw: string[]): Promise<{ args: string[] } | { refusal: OperationError; legacy?: Record<string, string> }> {
  const { cliOpts, rest } = parseGlobalFlags(raw);
  setCliOptions(cliOpts);
  const split = OWN_EQUALS_PARSERS.has(`${command} ${rest[0]}`) ? { args: rest } : await splitFlagEquals(command, rest);
  if ('refusal' in split) return split;
  const unknown = findUnknownFlag(split.args, new Set(CLI_FLAG_REGISTRY[command]));
  if (!unknown) return split;
  const message = `unknown flag ${unknown} for 'gbrain ${command}'`;
  const known = (await loadCuratedHelp(command))?.flags.map(f => f.name) ?? CLI_FLAG_REGISTRY[command] ?? [];
  return { refusal: unknownFlagError(command, unknown, message, known), legacy: { status: 'error', reason: 'invalid_flag', message } };
}