Files
reverse-engineering-anything/src/cli/cliShell.ts
T
Ysopwnableandgensokyo-dev 7d502ddb0d refactor(cli)!: own builtin refusals and retire per-command MCP
Own builtin refusal paths and Markdown schemas in REA. Reject retired per-command MCP before loading command registrars, preserve invoked identity, and apply token controls to the complete selected failure document.

BREAKING CHANGE: rea <command> --mcp is removed. Start REA's MCP server with rea mcp or rea --mcp.

Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-16 18:26:02 +08:00

198 lines
7.3 KiB
TypeScript

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 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 { 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 { 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";
/** A registrar and the module it was loaded from. */
export interface LoadedCliCommandRegistration {
readonly registration: CliCommandRegistration;
readonly module: unknown;
}
export interface CliShellOptions {
readonly selectedEnvironment: Readonly<Record<string, string | undefined>>;
/** Registrars to run, in registration order. */
readonly registrations: readonly LoadedCliCommandRegistration[];
/** Required when any registrar declares analysis. */
readonly createAnalysis?: (
environment: Readonly<Record<string, string | undefined>>,
) => DirectAnalysis;
readonly resultOutput?: CliResultOutput | undefined;
readonly fridaInstrumentation?: FridaInstrumentationPort | undefined;
}
/** Run each registrar, creating analysis once for those that declare it. */
const registerCommands = (
context: CliRegistrationContext,
options: CliShellOptions,
): void => {
let analysis: DirectAnalysis | undefined;
for (const { registration, module } of options.registrations) {
if (!registration.analysis) {
registration.register(module, context);
continue;
}
if (options.createAnalysis === undefined)
throw new Error("A CLI registrar needs analysis that was not provided");
analysis ??= options.createAnalysis(context.environment);
registration.register(module, { ...context, analysis });
}
};
/**
* Build the Incur 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.
*/
export const createCliShell = (options: CliShellOptions): CliInstance => {
const environment = snapshotEnvironment(
options.selectedEnvironment,
HOST_PLATFORM.platform,
);
const defaultRegistration = parseClientRegistrationCommand(
currentClientRegistrationCommand({ environment }),
);
// The executable reports an invalid level before every command except doctor.
// Doctor keeps going so its readiness report can name REA_LOG_LEVEL.
const level =
environment.REA_LOG_LEVEL === undefined
? undefined
: parseLogLevel(environment.REA_LOG_LEVEL);
const logger = createLogger(
"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;
registerCommands(
{
cli,
logger,
environment,
fridaInstrumentation: options.fridaInstrumentation,
},
options,
);
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) => {
if (completions.complete(arguments_, serveOptions ?? {}))
return Promise.resolve();
const global = parseCliGlobalArguments(arguments_);
if (completions.writeScript(global, serveOptions ?? {}))
return Promise.resolve();
const registration = serveMcpRegistration(
global,
environment,
defaultRegistration,
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 note = completionHelpNote(global);
if (note === undefined) return result;
return result.then(() => {
const write =
serveOptions?.stdout ?? ((text: string) => process.stdout.write(text));
write(`\n${note}`);
});
};
return cli;
};