refactor(cli)!: dispatch commands through REA-owned execution

Run ordinary CLI commands through REA's registry, argv parser and result owner.
Remove Incur, the second admission parse, SDK error middleware, output capture
and redundant command traversal. Preserve explicit redaction, publication
receipts, incremental output, terminal notice eligibility and drain ownership.
Migrate fixtures to real registrations and retain the derived-source notices.

Validation includes unchanged public parity goldens, public and lifecycle
regressions, repaired fixture consumers, real TTY base comparisons, exports
beyond the engine string limit, four schema catalogs and final static/docs
checks. Native provider and optional validator coverage limits are in the PR.

Fixes #11654. Fixes #10583. Refs #11682, #11476 and #10511.

BREAKING CHANGE: Markdown argument diagnostics use REA's literal escaping,
table widths and token counts. Flag-shaped unknown MCP subcommands honor the
selected format. Completion --schema/--version routes use the canonical
REA-owned hook rather than the retired SDK generator. Refresh affected literal
snapshots and regenerate completion hooks with rea completions <shell>.

Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
This commit is contained in:
Ysopwnableandgensokyo-dev authored and GitHub committed 2026-11-16 13:56:34 +00:00
1 parent 552d1c7108
commit 62014b566d
104 files changed
+1484 -2512

No files matched your search

+35 -82
View File
@@ -1,43 +1,26 @@
import { Cli } from "incur";
import { HOST_PLATFORM } from "../platform/HostPlatform.js";
import type { FridaInstrumentationPort } from "../ports/frida/FridaInstrumentationPort.js";
import { currentClientRegistrationCommand } from "../application/ClientRegistrationIdentity.js";
import {
adaptCliOutputArgumentsForIncur,
parseCliGlobalArguments,
} from "../cliBuiltinArguments.js";
import { parseCliGlobalArguments } from "../cliBuiltinArguments.js";
import type { DirectAnalysis } from "../composition/directAnalysis.js";
import { parseLogLevel } from "../config/processStart.js";
import { parseClientRegistrationCommand } from "../domain/clientRegistrationCommand.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { createLogger } from "../logger.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import {
encodeCliArgumentErrors,
presentCliArgumentErrors,
} from "./argumentErrors.js";
import type {
CliCommandRegistration,
CliRegistrationContext,
} from "./cliCommandRegistration.js";
import {
streamCliCommandResults,
type CliResultOutput,
} from "./cliResultOutput.js";
import type { CliResultOutput } from "./cliResultOutput.js";
import { runCliCommand } from "./runCliCommand.js";
import { completionHelpNote, createCliCompletions } from "./completions.js";
import { excludeDeclaredSensitiveArguments } from "./explicitSensitiveArguments.js";
import {
CLI_CUSTOM_GLOBAL_OPTIONS,
CLI_DESCRIPTION,
CLI_UPDATE_REFUSAL,
serveDiscovery,
} from "./discovery.js";
import { serveDiscovery } from "./discovery.js";
import { reportUnknownMcpSubcommand } from "./mcpBuiltinCommands.js";
import { serveMcpRegistration } from "./mcpRegistration.js";
import { presentOmittableDefaults } from "./omittableDefaults.js";
import { validateCliArguments } from "./strictPositionals.js";
import type { CliInstance } from "./types.js";
import type { CliInstance, CliServeOptions } from "./types.js";
/** A registrar and the module it was loaded from. */
export interface LoadedCliCommandRegistration {
@@ -76,7 +59,7 @@ const registerCommands = (
};
/**
* Build the Incur CLI around the given registrars. Identity, global options,
* Build REA's CLI around the given registrars. Identity, global options,
* argument policy, completions, and registration builtins are the same for
* every set of registrars; they apply to whichever commands were registered.
*/
@@ -98,40 +81,10 @@ export const createCliShell = (options: CliShellOptions): CliInstance => {
"cli",
level?.ok === true ? level.value : "silent",
);
const timedCli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
version: PRODUCT_IDENTITY.packageVersion,
description: CLI_DESCRIPTION,
globals: CLI_CUSTOM_GLOBAL_OPTIONS,
mcp: {
instructions:
"Ask what software, artifact, protocol, or behavior the user wants to understand, then choose the available investigation capabilities that can produce evidence.",
},
sync: false,
update: {
// Incur still supplies ordinary-command notices. Keep its installer
// disabled while REA owns the update refusal and verified update command.
install: () => {
throw new Error(CLI_UPDATE_REFUSAL.message);
},
},
});
timedCli.use(async (context, next) => {
if (!context.globals.timings) return next();
const started = performance.now();
try {
await next();
} finally {
// This interval covers CLI command dispatch, including result delivery.
// It is not a provider-only or analysis-only measurement.
process.stderr.write(
`${JSON.stringify({ rea_timings: { version: 1, command_ms: Math.round(performance.now() - started) } })}\n`,
);
}
});
// Command registrars do not inspect global options; preserve their existing
// type while Incur owns parsing and the middleware owns this added flag.
const cli = timedCli as unknown as CliInstance;
const cli: CliInstance = {
name: PRODUCT_IDENTITY.cliBinary,
serve,
};
registerCommands(
{
@@ -144,25 +97,15 @@ export const createCliShell = (options: CliShellOptions): CliInstance => {
);
presentOmittableDefaults(cli);
// Discovery reads the arguments the dispatcher would, after result output
// has adapted them, so its documents are counted and buffered alike.
const dispatch = cli.serve.bind(cli);
const updateEnvironment = {
variables: environment,
platform: HOST_PLATFORM.platform,
};
cli.serve = (arguments_ = process.argv.slice(2), serveOptions) =>
serveDiscovery(cli, arguments_, serveOptions ?? {}, updateEnvironment) ??
dispatch(arguments_, serveOptions);
if (options.resultOutput !== undefined)
streamCliCommandResults(cli, options.resultOutput);
const serveStrict = validateCliArguments(cli);
presentCliArgumentErrors(cli);
const serveDeclared = excludeDeclaredSensitiveArguments(cli);
encodeCliArgumentErrors(cli);
const serve = cli.serve.bind(cli);
const completions = createCliCompletions(cli, environment);
cli.serve = (arguments_ = process.argv.slice(2), serveOptions) => {
function serve(
arguments_: readonly string[] = process.argv.slice(2),
serveOptions?: CliServeOptions,
): Promise<void> {
if (completions.complete(arguments_, serveOptions ?? {}))
return Promise.resolve();
const global = parseCliGlobalArguments(arguments_);
@@ -175,16 +118,26 @@ export const createCliShell = (options: CliShellOptions): CliInstance => {
serveOptions ?? {},
);
if (registration !== undefined) return registration;
const result = serveStrict(global, serveOptions ?? {}, (selected) =>
serveDeclared(global, selected, (declaredOptions) =>
reportUnknownMcpSubcommand(cli.name, global, declaredOptions)
? Promise.resolve()
: serve(
adaptCliOutputArgumentsForIncur(global.arguments),
declaredOptions,
),
),
);
const result = reportUnknownMcpSubcommand(
cli.name,
global,
serveOptions ?? {},
)
? Promise.resolve()
: (serveDiscovery(
cli,
global.arguments,
serveOptions ?? {},
updateEnvironment,
global,
) ??
runCliCommand(
cli,
global,
serveOptions ?? {},
updateEnvironment,
options.resultOutput,
));
const note = completionHelpNote(global);
if (note === undefined) return result;
return result.then(() => {
@@ -192,6 +145,6 @@ export const createCliShell = (options: CliShellOptions): CliInstance => {
serveOptions?.stdout ?? ((text: string) => process.stdout.write(text));
write(`\n${note}`);
});
};
}
return cli;
};