Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Static view of the CLI-only dispatch pipeline (refactor wave 1, W4 cli).
*
* src/cli.ts handleCliOnly is an explicit ordered pipeline: it calls stage
* functions tagged `@cliPipelineStage` and two table steps
* (`dispatchPreConnectCommand`, `dispatchConnectedCommand`) that run the
* command modules named by src/cli/command-table.ts. Two tools read that
* shape as source and must see the same thing:
*
* - test/helpers/cli-dispatch-extract.ts (the W0 dispatch-shape goldens)
* - scripts/generate-flag-registry.ts (per-command legal flags)
*
* `flattenCliPipeline` returns handleCliOnly's statements with every call to a
* tagged stage replaced by that stage's own statements, in order, so a stage
* split never changes what either tool sees. Pure: reads source text only.
*/
import { existsSync, readFileSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import ts from 'typescript';
export const PIPELINE_ENTRY = 'handleCliOnly';
export const PIPELINE_STAGE_TAG = 'cliPipelineStage';
export const PRE_CONNECT_TABLE_STEP = 'dispatchPreConnectCommand';
export const POST_CONNECT_TABLE_STEP = 'dispatchConnectedCommand';
export const COMMAND_TABLE_PATH = 'src/cli/command-table.ts';
export function readSource(root: string, rel: string): string {
// CRLF-normalized so line-anchored scans behave the same on every platform.
return readFileSync(join(root, rel), 'utf8').replace(/\r\n/g, '\n');
}
export function parseSource(root: string, rel: string): ts.SourceFile {
return ts.createSourceFile(rel, readSource(root, rel), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
}
function topLevelFunctions(sf: ts.SourceFile): Map<string, ts.FunctionDeclaration> {
const fns = new Map<string, ts.FunctionDeclaration>();
for (const st of sf.statements) {
if (ts.isFunctionDeclaration(st) && st.name && st.body) fns.set(st.name.text, st);
}
return fns;
}
function isStage(fn: ts.FunctionDeclaration): boolean {
return ts.getJSDocTags(fn).some((t) => t.tagName.text === PIPELINE_STAGE_TAG);
}
/** Names of functions called directly by a statement (not inside nested functions). */
function calledNames(st: ts.Statement): string[] {
const out: string[] = [];
const visit = (n: ts.Node): void => {
if (ts.isFunctionLike(n)) return;
if (ts.isCallExpression(n) && ts.isIdentifier(n.expression)) out.push(n.expression.text);
n.forEachChild(visit);
};
visit(st);
return out;
}
export interface CliPipeline {
sourceFile: ts.SourceFile;
entry: ts.FunctionDeclaration;
/** Stage functions in call order (entry excluded). */
stages: ts.FunctionDeclaration[];
/** Entry statements with each stage call inlined, in dispatch order. */
statements: ts.Statement[];
}
export function flattenCliPipeline(sf: ts.SourceFile): CliPipeline {
const fns = topLevelFunctions(sf);
const entry = fns.get(PIPELINE_ENTRY);
if (!entry) throw new Error(`cli-pipeline: ${PIPELINE_ENTRY} not found in ${sf.fileName}`);
const stages: ts.FunctionDeclaration[] = [];
const flatten = (list: readonly ts.Statement[], depth: number): ts.Statement[] => {
if (depth > 4) throw new Error('cli-pipeline: stage nesting too deep');
const out: ts.Statement[] = [];
for (const st of list) {
const stageName = calledNames(st).find((n) => {
const fn = fns.get(n);
return !!fn && isStage(fn);
});
if (!stageName) {
out.push(st);
continue;
}
const fn = fns.get(stageName)!;
if (stages.includes(fn)) throw new Error(`cli-pipeline: stage ${stageName} is called twice`);
stages.push(fn);
out.push(...flatten(fn.body!.statements, depth + 1));
}
return out;
};
const statements = flatten(entry.body!.statements, 0);
const untagged = [...fns.values()].filter((fn) => isStage(fn) && !stages.includes(fn));
if (untagged.length > 0) {
throw new Error(`cli-pipeline: @${PIPELINE_STAGE_TAG} function(s) not called from ${PIPELINE_ENTRY}: ${untagged.map((f) => f.name!.text).join(', ')}`);
}
return { sourceFile: sf, entry, stages, statements };
}
/** The statement that runs a table step (`if (await dispatchPreConnectCommand(...)) return;`). */
export function isTableStep(st: ts.Statement, step: string): boolean {
return calledNames(st).includes(step);
}
export interface CommandModule {
/** Repo-relative path of the module file. */
path: string;
sourceFile: ts.SourceFile;
/** The exported `run` function the table step calls. */
run: ts.FunctionDeclaration;
}
/** src/cli/commands/<name>.ts for a table record whose load names that module, else null. */
export function readCommandModule(root: string, loadSpecifier: string): CommandModule | null {
const abs = resolve(join(root, dirname(COMMAND_TABLE_PATH)), loadSpecifier);
const rel = relative(root, abs).replace(/\\/g, '/');
if (!rel.startsWith('src/cli/commands/') || !existsSync(abs)) return null;
const sf = parseSource(root, rel);
const run = topLevelFunctions(sf).get('run');
if (!run) throw new Error(`cli-pipeline: ${rel} exports no run()`);
return { path: rel, sourceFile: sf, run };
}
export interface TableRecordShape {
name: string;
/** Literal specifier of `load: () => import('<literal>')`, or null when load is not that shape. */
loadSpecifier: string | null;
/** D3: `help` absent → undefined; `() => import('<literal>')` → the literal; any other shape → null. */
helpSpecifier?: string | null;
/** The record's `phase` string literal (A1 routing pin: pre-connect commands open no brain through the terminator). */
phase?: string;
/** A1: the flag naming the record's target source: `'--source'` for `routes_source: true`, else the declared flag (`'--source-id'`). */
routesSource?: '--source' | '--source-id';
}
/** Every record of CLI_COMMANDS in table order, read by AST (the EO13 literal-load contract). */
export function readTableRecords(root: string): TableRecordShape[] {
const sf = parseSource(root, COMMAND_TABLE_PATH);
let table: ts.ArrayLiteralExpression | undefined;
const visit = (n: ts.Node): void => {
if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === 'CLI_COMMANDS' && n.initializer && ts.isArrayLiteralExpression(n.initializer)) table = n.initializer;
n.forEachChild(visit);
};
visit(sf);
if (!table) throw new Error(`cli-pipeline: CLI_COMMANDS array not found in ${COMMAND_TABLE_PATH}`);
return table.elements.map((el) => {
if (!ts.isObjectLiteralExpression(el)) throw new Error('cli-pipeline: CLI_COMMANDS element is not an object literal');
const prop = (key: string) => el.properties.find((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === key);
const name = prop('name')?.initializer;
if (!name || !ts.isStringLiteral(name)) throw new Error('cli-pipeline: CLI_COMMANDS record without a string-literal name');
const literalImport = (init: ts.Expression | undefined): string | null =>
init && ts.isArrowFunction(init) && init.parameters.length === 0 && ts.isCallExpression(init.body)
&& init.body.expression.kind === ts.SyntaxKind.ImportKeyword && init.body.arguments.length === 1
&& ts.isStringLiteral(init.body.arguments[0]!) ? init.body.arguments[0].text : null;
const help = prop('help');
const phase = prop('phase')?.initializer;
const routes = prop('routes_source')?.initializer;
const routesSource = routes?.kind === ts.SyntaxKind.TrueKeyword ? '--source' as const
: routes && ts.isStringLiteral(routes) && routes.text === '--source-id' ? '--source-id' as const : undefined;
return { name: name.text, loadSpecifier: literalImport(prop('load')?.initializer), ...(help ? { helpSpecifier: literalImport(help.initializer) } : {}),
...(phase && ts.isStringLiteral(phase) ? { phase: phase.text } : {}), ...(routesSource ? { routesSource } : {}) };
});
}