Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #2185 — known-flags registry generator for CLI_ONLY commands.
*
* gbrain's CLI_ONLY commands read flags ad hoc (`args.includes('--force')`,
* per-command parseFlags helpers), so there is no parser to make strict. The
* pre-dispatch validator in src/cli/main.ts needs to know each command's legal
* flags; this script derives them from the source instead of a hand-typed
* list that would rot.
*
* How: per CLI_ONLY command (one record in src/cli/command-table.ts), gather
* its dispatch text: the record's module under src/cli/commands/ (the former
* `case 'X':` / plain `if (command === 'X')` body, moved verbatim in refactor
* wave 1) plus every block of the explicit handleCliOnly pipeline in
* src/cli/main.ts (handleCliOnly and its @cliPipelineStage functions, see
* scripts/lib/cli-pipeline.ts) segmented on its dispatch markers — every
* `if (command === 'X' …)` head, plain or compound, and `case 'X':` labels (see
* segmentDispatchBlocks). Collect every `import('…/commands/Y.ts')` in that
* text, then scan the text plus each imported module (plus one level of that
* module's ./relative same-directory imports) for `--flag` string literals. `//` and
* `/* *\/` comments are stripped at EVERY depth before the scan (prose is not
* consumption; see stripComments) — a helper's doc comment must not legalise a
* flag for a command that merely imports one function from it. String
* literals include help text, which deliberately over-includes: accepting a flag the handler
* ignores is the pre-#2185 status quo for that flag, while missing a real
* flag would break working invocations on upgrade.
*
* Output: src/core/cli-flag-registry.generated.ts (committed; freshness is
* pinned by test/cli-flag-validation.test.ts the same way build:llms pins the
* llms bundles). Regenerate: bun run build:flag-registry
* Check: bun scripts/generate-flag-registry.ts --check exits 1 when the
* committed file differs from a fresh render (what regen:all --check runs).
*
* Hand-tuning lane: EXTRA_FLAGS below, for flags that live deeper than the
* one-level scan (add with a comment naming the deep module).
*/
import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
import { dirname, resolve as resolvePath, join, sep } from 'path';
import { fileURLToPath } from 'url';
import { flattenCliPipeline, parseSource, readCommandModule, readTableRecords } from './lib/cli-pipeline.ts';
/** Read source with CRLF normalized to LF: the parser's block-boundary and
* comment-strip regexes are LF-anchored (`\n}\n`, `//[^\n]*`), so Windows
* checkouts (autocrlf=true) would otherwise widen scan windows and inflate
* the last command's flag list. Deterministic on every platform. */
function readSrc(path: string): string {
return readFileSync(path, 'utf-8').replace(/\r\n/g, '\n');
}
const ROOT = resolvePath(dirname(fileURLToPath(import.meta.url)), '..');
/** Flags that live deeper than the one-level module scan. Keep commented. */
const EXTRA_FLAGS: Record<string, string[]> = {
// embed's pace knobs resolve inside src/core/pace-mode.ts (two levels deep).
embed: ['--pace', '--pace-max-concurrency'],
// sync shares the same pace surface via env/config plus CLI passthrough.
sync: ['--pace', '--pace-max-concurrency'],
// Deferred persistence routing reaches runForget in recall.ts two levels deep;
// `forget --purge` hands off from there to src/commands/forget-purge.ts.
forget: ['--reason', '--request-id', '--purge', '--dry-run', '--yes', '--match', '--status', '--vacuum', '--all-subjects'],
// sources add reads the meetings and slack options as bare names in src/commands/sources-lifecycle-args.ts (its valued set).
sources: ['--provider', '--transcript', '--lookback-days', '--sync-interval-min', '--record', '--visibility', '--channels', '--timezone', '--max-requests', '--skip'],
};
/**
* Command modules a command hands its argv to through a nested handler import,
* scanned at module depth so their safety-flag reads count as consumption
* evidence. Their own imports are not walked. Keep commented.
*/
const DELEGATED_MODULES: Record<string, string[]> = {
// `auth local-writer list|register|revoke` passes its argv to
// runPersistenceAdminCli (#5595), and `auth rescope-client|rescope-token` to
// parseRescopeGrantArgs; both parse --dry-run themselves.
auth: ['src/commands/persistence-admin.ts', 'src/core/grants/cli.ts'],
// `forget --purge` (and forget --help) hand the argv to runForgetPurge, which
// parses --dry-run itself; a plain forget refuses --dry-run (recall.ts).
forget: ['src/commands/forget-purge.ts'],
// `upgrade --restart-only --dry-run` is parsed by restartDryRun in
// upgrade-restart.ts, which refuses --dry-run without --restart-only;
// post-upgrade shares upgrade.ts and never takes it. A plain `upgrade --dry-run`
// is the channel preview, parsed by runUpgradeDryRun in upgrade-channel.ts.
upgrade: ['src/commands/upgrade-restart.ts', 'src/commands/upgrade-channel.ts'],
};
/**
* Modules the import scan must SKIP. thin-client-routing.ts is a pure router —
* its flag literals belong to the commands it routes (takes/search/jobs/cache/
* quarantine), and each of those declares its own flags in its own case block;
* scanning the router bleeds takes/quarantine flags into jobs (whose case
* block imports it for the `jobs stats` thin-client route). job-isolation.ts
* builds the INTERNAL `jobs run-child` argv (`--job-id`, `--allow-shell-jobs`):
* those literals are what a worker passes to its child, not flags an importer
* parses — autopilot imports it only to resolve the child CLI, and `jobs`
* declares both flags in its own source. strict-args.ts is the strict-argument
* table for several commands' destructive subcommands (#6114): its literals
* belong to pages, cache, schema, integrity and search, each of which reads
* its own flags in its own source. flag-equals.ts (#7619) names flags as
* arity data for the `=` split; each handler reads its own flags.
* direct-pool-profile.ts reads other commands'
* argv to pick the process's pool profile (`sync --watch`, `serve --access`):
* serve imports it for the read-only check, and its `--watch` made
* `gbrain serve --watch` pass validation. grants/shared-exposure.ts (GST-363)
* names other commands' flags (auth rescope, mcp grant, doctor) in warning
* text that setup, mcp, connect, skillpack and auth print.
*/
const EXCLUDED_MODULES = ['thin-client-routing.ts', 'persistence-delegate.ts', 'job-isolation.ts', 'strict-args.ts', 'direct-pool-profile.ts', 'flag-equals.ts', 'shared-exposure.ts'];
function isExcludedModule(p: string): boolean {
// Basename comparison is path-separator agnostic: on Windows p ends in
// '\\thin-client-routing.ts' so endsWith('/thin-client-routing.ts') is
// false and the skip silently no-ops, inflating every command that
// imports the router with its flags.
return EXCLUDED_MODULES.some(m => p.split(/[\\/]/).pop() === m);
}
/** Universal helper flags every command may see (parsed or short-circuited upstream). */
const UNIVERSAL_FLAGS = ['--help', '--json', '--brain', '--source'];
const FLAG_RE = /--[a-z0-9][a-z0-9-]*/g;
function flagsInText(text: string): Set<string> {
const out = new Set<string>();
for (const m of text.matchAll(FLAG_RE)) {
// Template-literal prefixes (`--bound-${key}` scans as `--bound-`) are
// not real flags — a trailing hyphen would make the validator accept
// every typo sharing the prefix.
if (!m[0].endsWith('-')) out.add(m[0]);
}
return out;
}
/** One level of ./relative imports (static or dynamic) from a module's source.
* TYPE-ONLY imports are skipped: they carry no runtime behavior the command
* can consume, so their doc-comment prose must not register flags (observed:
* `import type { BrainEngine } from engine.ts` handed skillpack 10 phantom
* flags from engine.ts's comments — the 4th prose-bleed incident). */
function relativeImports(src: string, fromDir: string): string[] {
const scanSrc = src.replace(/import\s+type\s+[^;]+;/g, '');
const paths = new Set<string>();
for (const m of scanSrc.matchAll(/from\s+'(\.\.?\/[^']+\.ts)'/g)) paths.add(m[1]);
for (const m of scanSrc.matchAll(/import\('(\.\.?\/[^']+\.ts)'\)/g)) paths.add(m[1]);
return [...paths]
.map(p => resolvePath(fromDir, p))
.filter(p => existsSync(p) && !isExcludedModule(p))
.flatMap(p => [p, ...facadeExpansion(p)]);
}
/**
* Peeled façade files (containment sprint) whose flag-bearing text moved into
* sibling module dirs. Before the peels, that text lived inside the façade
* itself and rode the one-level walk; scanning the façade now pulls its
* modules back in so a peel can never silently shrink a command's flag set.
*/
function facadeExpansion(p: string): string[] {
// Compare in forward-slash space: on Windows p uses '\\' separators and
// would never match the relative-path constants below, silently skipping
// the peeled-module expansion. Same cross-platform drift class as the
// isExcludedModule separator check above.
const rel = (p.startsWith(ROOT) ? p.slice(ROOT.length + 1) : p).replace(/\\/g, '/');
const collect = (dir: string): string[] => {
if (!existsSync(dir)) return [];
const out: string[] = [];
for (const entry of readdirSync(dir).sort()) {
const full = join(dir, entry);
if (statSync(full).isDirectory()) out.push(...collect(full));
else if (entry.endsWith('.ts')) out.push(full);
}
return out;
};
if (rel === 'src/core/operations.ts') return collect(join(ROOT, 'src/core/ops'));
if (rel === 'src/commands/migrate-embeddings.ts') return [join(ROOT, 'src/core/embedding-migration-cli.ts')];
if (rel === 'src/commands/mcp.ts') return [
join(ROOT, 'src/commands/mcp-admin.ts'),
join(ROOT, 'src/commands/mcp-admin-http.ts'),
];
if (rel === 'src/commands/doctor.ts') return collect(join(ROOT, 'src/commands/doctor'));
if (rel === 'src/commands/decide.ts') return collect(join(ROOT, 'src/commands/decide'));
// Refactor wave 1 (W4 serve-http) peeled runServeHttp into flat
// serve-http-<area>.ts modules; their text (e.g. the expired-magic-link
// page's `--url` / `--oauth-request` hint) used to live in serve-http.ts.
if (rel === 'src/commands/serve-http.ts') {
return ['oauth', 'metrics', 'admin-api', 'spa', 'mcp', 'webhooks']
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
.map(m => join(ROOT, `src/commands/serve-http-${m}.ts`))
.filter(p => existsSync(p));
}
// Refactor wave 1 (W3): the MIGRATIONS array moved to one file per migration.
if (rel === 'src/core/migrate.ts') return collect(join(ROOT, 'src/core/schema-migrations'));
if (rel === 'src/commands/skillpack.ts') return collect(join(ROOT, 'src/commands/skillpack'));
// connectors is a peeled command dir (index.ts dispatches to auth/sync/status);
// scan the whole dir at module depth so a safety flag consumed in a subcommand
// module (sync.ts: `=== '--dry-run'`) carries its evidence into depth-zero.
if (rel === 'src/commands/connectors/index.ts') return collect(join(ROOT, 'src/commands/connectors'));
if (rel === 'src/commands/sync.ts') {
// Only the modules PEELED OUT of sync.ts (their text used to live inside
// it). Pre-existing sync-* siblings were always ordinary deps — sweeping
// them in here would widen surfaces that never saw their text.
const peeled = [
'sync-cost-gate.ts',
'sync-git.ts',
'sync-anchor.ts',
'sync-lock.ts',
'sync-reconcile.ts',
'sync-status-report.ts',
];
// Refactor wave 1 moves sync's phases into src/commands/sync/; that dir's
// text is sync.ts's own text, so it joins the surface from its first file.
return [
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
...peeled.map(f => join(ROOT, 'src/core', f)).filter(p => existsSync(p)),
...collect(join(ROOT, 'src/commands/sync')),
];
}
// Refactor wave 1 subcommand tables for jobs/autopilot (cut-line) land in
// same-named command dirs; empty until those peels happen.
if (rel === 'src/commands/jobs.ts') {
// The built-in handler bodies registerBuiltinHandlers used to hold inline
// moved to src/core/minions/handlers/ (W4 jobs). Only those modules: the
// directory's pre-existing handlers (shell, subagent, ...) were always
// ordinary deps, so globbing it would widen jobs' surface.
const peeledHandlers = [
'autopilot-cycle.ts', 'autopilot-global-maintenance.ts', 'backlinks.ts', 'chronicle-extract.ts',
'cycle-phase.ts', 'embed-catch-up.ts', 'embed.ts', 'enrich.ts', 'extract-atoms-drain.ts',
'extract-conversation-facts.ts', 'extract-ner.ts', 'extract-takes-from-pages.ts',
'extract-timeline-from-meetings.ts', 'extract.ts', 'facts-absorb.ts', 'import.ts',
'integrity-auto.ts', 'integrity.ts', 'job-pull.ts', 'lint-fix.ts', 'lint.ts', 'loops-extract.ts',
'orphans.ts', 'purge.ts', 'reindex.ts', 'repair-jsonb.ts', 'sync-retry-failed.ts', 'sync.ts',
'unify-types.ts',
];
return [
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
...peeledHandlers.map(f => join(ROOT, 'src/core/minions/handlers', f)).filter(p => existsSync(p)),
...collect(join(ROOT, 'src/commands/jobs')),
];
}
if (rel === 'src/commands/autopilot.ts') {
// W4 autopilot split runAutopilot's daemon into flat autopilot-*.ts
// siblings (the existing autopilot-fanout/-pause convention). Only the
// modules peeled out of autopilot.ts: pre-existing siblings were always
// ordinary deps, so a glob would widen the surface.
const peeled = ['autopilot-daemon.ts', 'autopilot-dispatch.ts', 'autopilot-probes.ts'];
return [
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
...peeled.map(f => join(ROOT, 'src/commands', f)).filter(p => existsSync(p)),
...collect(join(ROOT, 'src/commands/autopilot')),
];
}
return [];
}
/**
* A block-level `import('./commands/X.ts')` whose destructured bindings are
* ALL SCREAMING_CASE constants borrows a value (a message string), not a
* handler — `const { THIN_CLIENT_REGISTER_MESSAGE } = await import(
* './commands/agent-register.ts')` in the agent-register pre-connect guard.
* Promoting such a module to depth zero scans its one-level deps
* (sources-ops / config / auth / oauth-provider …) as if the command owned
* them: that handed the agent row 38 phantom flags (--confirm-destructive,
* --force, --remove, …). The handler proper (`const { runX } = …`) still
* reaches the module through its own import walk, so no real flag is lost.
*/
export function isValueOnlyImport(block: string, importIndex: number): boolean {
const lineStart = block.lastIndexOf('\n', importIndex) + 1;
const head = block.slice(lineStart, importIndex);
const m = head.match(/const\s*\{([^}]*)\}\s*=\s*await\s*$/);
if (!m) return false;
const bindings = m[1].split(',').map(b => b.trim()).filter(b => b.length > 0);
return bindings.length > 0 && bindings.every(b => /^[A-Z][A-Z0-9_]*$/.test(b));
}
/**
* Segment handleCliOnly's body into per-command text blocks.
*
* handleCliOnly dispatches through TWO styles: an `if (command === 'X')`
* chain (DB-free commands like init/auth/schema) and a switch with
* `case 'X':` labels. Segment on BOTH marker kinds; the text between a
* marker and the next marker belongs to that label. Repeated labels
* (fall-through cases, a command with several `if` branches) union their
* blocks.
*
* The `if` chain has THREE shapes, and every one is a marker for X:
* if (command === 'X') { plain
* if (command === 'X' && args[0] === 'sub') { compound — the sub-owned
* no-DB bypasses (eval
* longmemeval / brainbench /
* …), the `<cmd> --help`
* pre-engine branches, agent
* register
* if (\n command === 'X' &&\n (...) multi-line compound
* Invariant: ownership follows the `command === 'X'` head, never the
* condition's tail. Pre-fix only the plain shape matched, so a compound
* block's text was attributed to the PRECEDING marker: every `eval <sub>`
* bypass landed on `dream`, every `<cmd> --help` bypass on `status`, and the
* eval row lacked --retrieval-only/--by-type/--no-trajectory/--keyword-only —
* the documented `gbrain eval longmemeval` invocation exited 1 as an unknown
* flag. `[ \t]*` (not `\s*`) keeps the marker anchored to its own line; `\(\s*`
* lets the multi-line shape's newline through. A bare `command === 'X'` inside
* a non-`if` expression (the serve `degradable` const) is deliberately NOT a
* marker.
*/
/**
* Strip `//` line comments and `/* … *\/` block comments from a block's
* text, preserving newlines (so line-anchored scans such as isValueOnlyImport
* still see the same line structure) and leaving string / template literals
* intact (a `'https://…'` literal is not a comment). Prose in a comment is not
* evidence a command reads a flag: cli.ts's `reindex --help` comment ("…the
* --multimodal flags the dispatcher parses") handed the PRECEDING marker
* (storage) a phantom --multimodal because the comment sat between the two
* markers. Regex literals are not modelled — `//` inside one would truncate
* that line — which is acceptable for dispatch-block text (none there today).
*/
export function stripComments(src: string): string {
let out = '';
let i = 0;
const n = src.length;
while (i < n) {
const c = src[i];
const next = src[i + 1];
if (c === '/' && next === '/') {
while (i < n && src[i] !== '\n') i++;
continue;
}
if (c === '/' && next === '*') {
const end = src.indexOf('*/', i + 2);
const stop = end < 0 ? n : end + 2;
// Keep the newlines the comment spanned so line structure survives.
out += src.slice(i, stop).replace(/[^\n]/g, '');
i = stop;
continue;
}
if (c === "'" || c === '"' || c === '`') {
const quote = c;
let j = i + 1;
while (j < n && src[j] !== quote) {
if (src[j] === '\\') j++;
else if (quote !== '`' && src[j] === '\n') break; // unterminated: stop at EOL
j++;
}
out += src.slice(i, Math.min(n, j + 1));
i = j + 1;
continue;
}
out += c;
i++;
}
return out;
}
export function segmentDispatchBlocks(fnSrc: string): Map<string, string> {
const markRe = /(?:^[ \t]*if \(\s*command === '([a-z0-9-]+)'|^ case '([a-z0-9-]+)':)/gm;
const marks: Array<{ label: string; start: number }> = [];
let m: RegExpExecArray | null;
while ((m = markRe.exec(fnSrc)) !== null) {
marks.push({ label: (m[1] ?? m[2])!, start: m.index });
}
const blocks = new Map<string, string>();
for (let i = 0; i < marks.length; i++) {
const end = i + 1 < marks.length ? marks[i + 1].start : fnSrc.length;
// Comments are prose, not consumption: strip them before any flag scan.
const body = stripComments(fnSrc.slice(marks[i].start, end));
// Fall-through labels share the following block.
blocks.set(marks[i].label, (blocks.get(marks[i].label) ?? '') + body);
}
return blocks;
}
/** @param root repository root; a fixture tree in tests (test/cli-synthetic-command.test.ts). */
export function buildFlagRegistry(root: string = ROOT): Record<string, string[]> {
return buildFlagArtifacts(root).registry;
}
/**
* A1 render-time routing pin (src/core/fix-routing.ts): the routing flags a
* fix naming each CLI-only command carries. Acceptance alone is not evidence
* (every command accepts `--brain`/`--source` through UNIVERSAL_FLAGS), so:
* - `--brain` when the command opens its brain through the connect terminator
* (phase other than `pre-connect`), or its own code reads the global brain
* option;
* - `--source` when the record declares `routes_source: true` (its source resolves
* through the ambient chain), or the flag it declares instead (`'--source-id'`
* for extract, whose `--source` selects fs|db). The declaration needs consumption
* evidence (the tight-quoted flag literal in the command's own code, the
* SAFETY_FLAGS rule); a declaration without it fails the generator.
*/
export function buildRoutingFlags(root: string = ROOT): Record<string, string[]> {
return buildFlagArtifacts(root).routing;
}
function buildFlagArtifacts(root: string): { registry: Record<string, string[]>; routing: Record<string, string[]> } {
// CLI_ONLY membership: one record per command in the command table
// (src/cli/command-table.ts), read by AST so the generator never executes
// the table.
const records = readTableRecords(root);
const commands = records.map(r => r.name);
// Dispatch text per command, from two sources (refactor wave 1, W4 cli):
// 1. the explicit handleCliOnly pipeline in src/cli/main.ts: handleCliOnly and
// every @cliPipelineStage function it calls, each segmented on its own
// (bounded at the function, so no function's tail bleeds into the next;
// unbounded, the LAST block once absorbed every --flag literal in the
// rest of cli.ts, printHelp included, a ~100-flag junk allowlist);
// 2. each record's module under src/cli/commands/ (the former plain
// `if (command === 'x')` branch or switch case, moved verbatim).
// Import specifiers resolve relative to the file the text came from.
const blocks = new Map<string, Array<{ text: string; dir: string }>>();
const addBlock = (label: string, text: string, dir: string) => blocks.set(label, [...(blocks.get(label) ?? []), { text, dir }]);
const pipeline = flattenCliPipeline(parseSource(root, 'src/cli/main.ts'));
for (const fn of [pipeline.entry, ...pipeline.stages]) {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
for (const [label, text] of segmentDispatchBlocks(fn.getText())) addBlock(label, text, join(root, 'src', 'cli'));
}
for (const record of records) {
const mod = record.loadSpecifier ? readCommandModule(root, record.loadSpecifier) : null;
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- mod.path comes from the repo's own command table literal import specifiers; build-time only
if (mod) addBlock(record.name, stripComments(readSrc(join(root, mod.path))), dirname(join(root, mod.path)));
}
// Safety flags carry destructive-bypass semantics: allowlisting one that
// the handler never reads recreates the #2185 repro (`post-upgrade
// --dry-run` accepted, ignored, migrations run for real). Presence isn't
// enough — upgrade.ts prints a HINT naming another command's --dry-run,
// which is depth-0 text for post-upgrade. These flags are only legal with
// CONSUMPTION evidence in the command's own code: the flag as a TIGHT-QUOTED
// standalone literal (`includes('--dry-run')`, `has('--dry-run')`,
// `=== '--dry-run'`). Prose bleed embeds the flag inside a longer string, so
// it never has quotes on both sides of the bare flag.
const SAFETY_FLAGS = new Set(['--dry-run', '--allow-noncanonical-root']);
// Reindex scope/mode flags can bleed through upgrade's imported modules even
// though upgrade does not forward them. Require direct consumption on the
// affected dispatch surfaces so callers never get silently ignored selectors.
const SCOPING_FLAGS_BY_COMMAND: Record<string, string[]> = {
reindex: ['--type'],
upgrade: ['--type', '--aliases'],
'post-upgrade': ['--type', '--aliases'],
// bundled-skill's skill_not_found hint names setup's refresh command; it parses its own flags strictly.
'bundled-skill': ['--skill-loading', '--skills-index-only', '--install'],
};
const consumes = (text: string, flag: string): boolean =>
new RegExp(`['"\`]${flag}['"\`]`).test(text);
const registry: Record<string, string[]> = {};
const routing: Record<string, string[]> = {};
for (const command of commands) {
const parts = blocks.get(command) ?? [];
const flags = new Set<string>(UNIVERSAL_FLAGS);
const depthZero = new Set<string>();
let depthZeroText = parts.map(p => p.text).join('');
for (const f of flagsInText(depthZeroText)) { flags.add(f); depthZero.add(f); }
// COMMAND modules imported inside the case block (`./commands/*.ts`
// only), plus one level of each module's own ./relative imports. Core
// helpers a dispatch block reaches for directly (`./core/bootstrap/
// uninstall.ts` in the agent-register pre-connect guard, `./core/
// doctor-remote.ts`, `./core/ai/gateway.ts`, …) are NOT command modules:
// scanning them as one handed the agent row ~45 phantom flags from the
// uninstall command's surface (--delete-brain, --confirm-destructive,
// --break-lock, --force, --remove) the moment the compound
// `command === 'agent' && args[0] === 'register'` head became a marker.
// A flag a block consumes through a core helper is already a literal in
// the block's own text (depth zero); the helper's prose adds nothing.
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module name or a path the generator itself discovered under ROOT
const commandsDir = join(root, 'src', 'commands');
const commandModules = parts.flatMap(({ text, dir }) => [...text.matchAll(/import\('(\.\.?\/[^']+\.ts)'\)/g)]
.filter(mm => !isValueOnlyImport(text, mm.index ?? 0))
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- resolves literal relative import specifiers found in this repo's own source; results are filtered to src/commands below
.map(mm => resolvePath(dir, mm[1])))
.filter(p => p.startsWith(commandsDir + sep) && existsSync(p) && !isExcludedModule(p));
for (const modPath of commandModules) {
// A command module that IS a peeled façade counts its module files as
// part of itself: their text scans at module depth and THEIR relative
// imports scan at dep depth — exactly the pre-peel walk.
const surface = [modPath, ...facadeExpansion(modPath)];
for (const sfPath of surface) {
const sfSrc = readSrc(sfPath);
// Comments are prose at every depth, not just in the dispatch block:
// a helper's doc comment ("Used by --fresh + after manual reset" in
// backfill-base.ts) handed reindex-search-vector a --fresh it never
// parses the moment the command imported one function from it.
// Consumed flags are always string literals, so stripping can only
// remove phantoms.
const sfCode = stripComments(sfSrc);
depthZeroText += sfCode;
for (const f of flagsInText(sfCode)) { flags.add(f); depthZero.add(f); }
for (const dep of relativeImports(sfSrc, dirname(sfPath))) {
for (const f of flagsInText(stripComments(readSrc(dep)))) flags.add(f);
}
}
}
for (const rel of DELEGATED_MODULES[command] ?? []) {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- build-time generator over this repository's own source tree; every joined segment is a constant module path from DELEGATED_MODULES
const path = join(root, rel);
if (!existsSync(path)) continue;
const code = stripComments(readSrc(path));
depthZeroText += code;
for (const f of flagsInText(code)) { flags.add(f); depthZero.add(f); }
}
for (const f of EXTRA_FLAGS[command] ?? []) { flags.add(f); depthZero.add(f); }
for (const f of SAFETY_FLAGS) {
if (flags.has(f) && !consumes(depthZeroText, f)) flags.delete(f);
}
for (const f of SCOPING_FLAGS_BY_COMMAND[command] ?? []) {
if (flags.has(f) && !consumes(depthZeroText, f)) flags.delete(f);
}
registry[command] = [...flags].sort();
const record = records.find(r => r.name === command);
if (record?.routesSource && !consumes(depthZeroText, record.routesSource)) {
throw new Error(`generate-flag-registry: ${command} declares routes_source but its code never reads '${record.routesSource}'`);
}
const routed = [
...(record?.phase !== 'pre-connect' || /getCliOptions\(\)\.brain|cliOpts\.brain/.test(depthZeroText) ? ['--brain'] : []),
...(record?.routesSource ? [record.routesSource] : []),
];
if (routed.length) routing[command] = routed;
}
return { registry, routing };
}
export function renderRegistryModule(registry: Record<string, string[]>, routing: Record<string, string[]> = {}): string {
const render = (map: Record<string, string[]>) => Object.keys(map)
.sort()
.map(cmd => ` '${cmd}': [${map[cmd].map(f => `'${f}'`).join(', ')}],`)
.join('\n');
const entries = render(registry);
return `// AUTO-GENERATED by scripts/generate-flag-registry.ts — do not edit by hand.
// Regenerate: bun run build:flag-registry
// Freshness + drift pinned by test/cli-flag-validation.test.ts (#2185).
//
// Merge conflict here? Do not hand-merge it. This file is regenerated on most
// upstream waves, so a branch that also regenerates it conflicts on the whole
// body. Take the base branch's copy wholesale, then re-run the command above —
// the freshness test named above fails loudly if that regeneration was done
// against the wrong base.
//
// Per-command legal flags for CLI_ONLY commands, derived from each command's
// source (case block + imported modules + one level of relative imports +
// scripts/generate-flag-registry.ts EXTRA_FLAGS). Deliberately over-inclusive
// (help-text mentions count): accepting an ignored flag is the pre-#2185
// status quo; missing a real one breaks working invocations.
export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
${entries}
};
// Routing flags a fix naming each CLI-only command carries (A1 render-time pin,
// src/core/fix-routing.ts): '--brain' when the command opens its brain (not a
// pre-connect command, or its code reads the global brain option); '--source'
// (or the declared '--source-id') when the command-table record declares
// routes_source (consumption-checked).
export const CLI_ROUTING_FLAGS: Record<string, readonly string[]> = {
${render(routing)}
};
`;
}
if (import.meta.main) {
const { registry, routing } = buildFlagArtifacts(ROOT);
const outPath = join(ROOT, 'src/core/cli-flag-registry.generated.ts');
const next = renderRegistryModule(registry, routing);
if (process.argv.includes('--check')) {
if ((existsSync(outPath) ? readFileSync(outPath, 'utf8') : '') !== next) {
console.error('src/core/cli-flag-registry.generated.ts is stale: run bun run regen:all');
process.exit(1);
}
process.exit(0);
}
writeFileSync(outPath, next);
const n = Object.keys(registry).length;
const total = Object.values(registry).reduce((a, v) => a + v.length, 0);
console.log(`wrote ${outPath} (${n} commands, ${total} flag entries)`);
}