Files
reverse-engineering-anything/src/cli/commandRegistry.ts
T
morluto f14e9a1d28 refactor(cli): register every command in an REA-owned command table (#11680)
* refactor(cli): register every command in an REA-owned command table

* fix(cli): flag grouped fields and named selectors in each command's input binding
2026-11-16 11:39:07 +08:00

168 lines
5.7 KiB
TypeScript

import type { z } from "zod";
import type {
ContractCliDescription,
ContractCliDocumentDescription,
} from "./contractCliDescription.js";
import type { CliInstance } from "./types.js";
/** One contract operation a command can run, with the flag of each field it takes. */
export interface CliCommandOperation {
/** The contract name, which is the MCP operation. */
readonly name: string;
/**
* The flag that sets each contract field, or `field.member`, on this
* command, such as `{ entry_point: "--entry-point" }`. Positionals and
* delivery fields have no flag.
*/
readonly flags: Readonly<Record<string, string>>;
}
type Inputs<Schema extends z.ZodObject | undefined> = Schema extends z.ZodObject
? z.output<Schema>
: Record<never, never>;
/** What a command's handler receives. */
export interface CliCommandRunContext<
Args extends z.ZodObject | undefined,
Options extends z.ZodObject | undefined,
> {
readonly args: Inputs<Args>;
readonly options: Inputs<Options>;
/** The caller chose an output format (`--format` or `--json`). */
readonly formatExplicit: boolean;
}
/** A command as its registrar defines it. */
export interface CliCommandDefinition<
Args extends z.ZodObject | undefined = undefined,
Options extends z.ZodObject | undefined = undefined,
> {
readonly description?: string | undefined;
/** Positionals, in argv order. */
readonly args?: Args;
readonly options?: Options;
/** Short alias by option key, such as `{ yes: "y" }`. */
readonly alias?: Readonly<Record<string, string>> | undefined;
/** `agent-only` hides the result on a terminal unless a format is chosen. */
readonly outputPolicy?: "all" | "agent-only" | undefined;
readonly run: (context: CliCommandRunContext<Args, Options>) => unknown;
}
/** How a command was described, for readers that need the full projection. */
export type CliCommandSource =
| { readonly kind: "contract"; readonly description: ContractCliDescription }
| {
readonly kind: "routed";
readonly descriptions: readonly ContractCliDescription[];
}
| {
readonly kind: "document";
readonly description: ContractCliDocumentDescription;
}
| { readonly kind: "host" };
/** One registered command. */
export interface CliCommandEntry {
readonly name: string;
/**
* The definition the dispatcher runs. Shell owners may still replace its
* inputs and handler in place before serving (omittable defaults, result
* output, argument policy), so readers see what is served.
*/
readonly definition: CliCommandDefinition<
z.ZodObject | undefined,
z.ZodObject | undefined
>;
/** Contract operations the command runs, in the order it chooses them. */
readonly operations: readonly CliCommandOperation[];
readonly source: CliCommandSource;
}
const registries = new WeakMap<CliInstance, CliCommandEntry[]>();
/**
* Register one command: record it in REA's command table, in registration
* order, and hand it to the dispatcher. Every command is registered here.
*/
export const registerCliCommand = <
const Args extends z.ZodObject | undefined = undefined,
const Options extends z.ZodObject | undefined = undefined,
>(
cli: CliInstance,
name: string,
definition: CliCommandDefinition<Args, Options>,
registration: {
readonly operations?: readonly CliCommandOperation[];
readonly source?: CliCommandSource;
} = {},
): void => {
const entries = registries.get(cli) ?? [];
if (entries.some((entry) => entry.name === name))
throw new Error(`CLI command ${name} is registered twice`);
// The dispatcher keeps this object, so in-place changes reach both.
(cli.command as (name: string, definition: object) => unknown)(
name,
definition,
);
entries.push({
name,
definition: definition as CliCommandEntry["definition"],
operations: registration.operations ?? [],
source: registration.source ?? { kind: "host" },
});
registries.set(cli, entries);
};
/** Commands registered on this CLI, in registration order. */
export const cliCommands = (cli: CliInstance): readonly CliCommandEntry[] =>
registries.get(cli) ?? [];
const kebabCase = (key: string): string =>
key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
/**
* The operations one contract description runs: its own contract, the
* contract that opens its session target, and the source of its Evidence
* targets, each with the flags this command gives its fields.
*/
export const contractDescriptionOperations = (
description: Pick<ContractCliDescription, "sessionTarget"> & {
readonly inputBinding?: ContractCliDescription["inputBinding"];
readonly contract: { readonly name: string };
readonly evidenceTargets?: ContractCliDescription["evidenceTargets"];
},
): readonly CliCommandOperation[] => {
const { sessionTarget, evidenceTargets } = description;
return [
{
name: description.contract.name,
flags: description.inputBinding?.flags ?? {},
},
...(sessionTarget?.opening === undefined
? []
: [
{
name: sessionTarget.opening,
flags: Object.fromEntries(
sessionTarget.options.map(({ field, key }) => [
field,
`--${kebabCase(key)}`,
]),
),
},
]),
...(evidenceTargets === undefined
? []
: [{ name: evidenceTargets.source, flags: evidenceTargets.sourceFlags }]),
];
};
/** Merge operation lists, keeping the first entry of each operation. */
export const distinctOperations = (
operations: readonly CliCommandOperation[],
): readonly CliCommandOperation[] => {
const seen = new Set<string>();
return operations.filter(({ name }) => !seen.has(name) && seen.add(name));
};