Files
reverse-engineering-anything/tests/support/cli/cliFixture.ts
T
morluto 80c60ac68c test(cli): cover terminal stdout behaviour in the CLI parity goldens (#11677)
* test(cli): cover terminal stdout behaviour in the CLI parity goldens

* test(cli): run the terminal command as the owned process and relay its output live
2026-11-16 11:26:56 +08:00

410 lines
13 KiB
TypeScript

import { resolve } from "node:path";
import { tmpdir } from "node:os";
import {
productionMcpDoctorArguments,
splitIncurBuiltinArguments,
} from "../../../src/cliBuiltinArguments.js";
import { DEFAULT_INFO_LOGGING_COMMANDS } from "../../../src/contracts/cliCommandNames.js";
import { parseLogLevel } from "../../../src/config/processStart.js";
import { INLINE_EVIDENCE_MCP_ENVIRONMENT } from "../../../scripts/lib/mcp-verification-environment.mjs";
import {
createTestWorkspace,
removeTestWorkspace,
} from "../workspace/workspaceFixture.js";
import {
processTest,
type ProcessResult,
type TestProcesses,
} from "../process/processFixture.js";
import {
createCliCommandSession,
type CliCommandSession,
} from "./cliCommandSession.js";
import { terminalStdoutInvocation } from "./terminalStdout.js";
/** Caller-controlled values for one compiled REA CLI invocation. */
export interface CliInvocation {
readonly arguments: readonly string[];
readonly cwd?: string;
readonly environment?: NodeJS.ProcessEnv;
readonly input?: string | Uint8Array;
readonly timeoutMs?: number;
/**
* Start a new process even when the file's shared process could serve the
* command. Use it for process-level facts such as startup or exit.
*/
readonly freshProcess?: boolean;
/**
* Put stdout on a pseudo-terminal (POSIX only), as when a user runs `rea`
* in a terminal. Stdin is empty and stderr stays a pipe. Always starts a
* fresh process.
*/
readonly terminal?: boolean;
}
/** Normalized result from the compiled REA CLI. */
export interface CliResult extends ProcessResult {
readonly json: unknown | undefined;
}
/** One compiled stdio MCP tool call. */
export type SharedMcpCall = Awaited<
ReturnType<
typeof import("../../fixtures/localToolsMcp.js").connectLocalToolsMcp
>
>["call"];
/** Compiled REA CLI driver owned by one test. */
export interface TestCli {
/**
* Run one command. `cliTest` drivers use the file's shared process when it
* reports the command exactly as a fresh process would, and start a fresh
* process otherwise. Drivers from `createTestCli` always start one.
*/
run(invocation: CliInvocation): Promise<CliResult>;
/**
* File-scoped stdio MCP caller. Present on `cliTest` drivers and absent for
* drivers created with `createTestCli` alone.
*/
sharedMcpCall?(): Promise<SharedMcpCall>;
}
/** One file-scoped stdio MCP session. */
export interface SharedMcpSession {
call(): Promise<SharedMcpCall>;
}
const sharedMcpSessionClosed = (): Error =>
new Error("Shared MCP session is closed");
/** Keep the handshake as the caller error and retain the cleanup failure beside it. */
const startupFailureWithCleanup = (
startup: unknown,
cleanup: unknown,
): Error => {
const primary =
startup instanceof Error ? startup : new Error(String(startup));
return new Error(primary.message, {
cause: new AggregateError([primary, cleanup], primary.message, {
cause: primary,
}),
});
};
/**
* Start at most one server for the file. Close waits for startup still in
* flight. A connector that sees `isClosed` can skip the server; a server
* registered after close is still cleaned up. A failed cleanup stays owned,
* and the next call does not open another server until that cleanup succeeds.
*/
export const createSharedMcpSession = (
connect: (
registerCleanup: (cleanup: () => Promise<void>) => void,
isClosed: () => boolean,
) => Promise<SharedMcpCall>,
): { session: SharedMcpSession; close(): Promise<void> } => {
let pending: Promise<SharedMcpCall> | undefined;
let closed = false;
let closing: Promise<void> | undefined;
let closeGeneration: symbol | undefined;
let cleanupQueue: Promise<void> = Promise.resolve();
const cleanups: Array<() => Promise<void>> = [];
const drain = (): Promise<void> => {
const run = cleanupQueue
.then(
() => undefined,
() => undefined,
)
.then(async () => {
const failures: unknown[] = [];
const retained: Array<() => Promise<void>> = [];
while (cleanups.length > 0) {
const cleanup = cleanups.pop();
if (cleanup === undefined) break;
try {
await cleanup();
} catch (error) {
failures.push(error);
retained.push(cleanup);
}
}
for (const cleanup of retained.reverse()) cleanups.push(cleanup);
// A reasonless rejection is `undefined` and still owns the cleanup.
if (failures.length > 1) {
throw new AggregateError(
failures,
"Shared MCP session cleanup failed",
);
}
if (failures.length === 1) throw failures[0];
});
cleanupQueue = run;
return run;
};
const registerCleanup = (cleanup: () => Promise<void>): void => {
cleanups.push(cleanup);
};
return {
session: {
call: () => {
if (closed) return Promise.reject(sharedMcpSessionClosed());
pending ??= (async () => {
try {
if (cleanups.length > 0) await drain();
} catch (cleanupError) {
// Close owns cleanup once shutdown has started, so a failed
// handshake cannot clear the startup close is awaiting.
if (!closed) pending = undefined;
throw cleanupError;
}
if (closed) throw sharedMcpSessionClosed();
try {
const opened = await connect(registerCleanup, () => closed);
if (closed) throw sharedMcpSessionClosed();
return opened;
} catch (error) {
if (!closed) {
pending = undefined;
try {
await drain();
} catch (cleanupError) {
throw startupFailureWithCleanup(error, cleanupError);
}
}
throw error;
}
})();
return pending;
},
},
close: () => {
closed = true;
if (closing !== undefined) return closing;
const starting = pending;
const generation = Symbol("shared-mcp-close");
closeGeneration = generation;
const attempt = (async () => {
try {
if (starting !== undefined) {
await starting.catch(() => undefined);
}
await drain();
} catch (error) {
// A failed close stays retryable. Completion is cached only after
// every retained cleanup has succeeded.
if (closeGeneration === generation) {
closing = undefined;
closeGeneration = undefined;
}
throw error;
}
})();
closing = attempt;
return attempt;
},
};
};
const createFileMcpSession = (
compileCache: string,
): { session: SharedMcpSession; close(): Promise<void> } =>
createSharedMcpSession(async (registerCleanup, isClosed) => {
const { connectLocalToolsMcp } =
await import("../../fixtures/localToolsMcp.js");
if (isClosed()) throw sharedMcpSessionClosed();
const mcp = await connectLocalToolsMcp(
{
...INLINE_EVIDENCE_MCP_ENVIRONMENT,
NODE_COMPILE_CACHE: compileCache,
},
registerCleanup,
);
return mcp.call;
});
const parseJson = (stdout: string): unknown | undefined => {
const document = stdout.trim();
if (document.length === 0) return undefined;
try {
return JSON.parse(document) as unknown;
} catch {
return undefined;
}
};
/** Child environment for one compiled CLI process, without the parent environment. */
export const cliProcessEnvironment = (
environment: NodeJS.ProcessEnv | undefined,
compileCache?: string,
): NodeJS.ProcessEnv => ({
PATH: process.env.PATH ?? "",
// Native Windows APIs need the system root and a writable temporary
// directory even when the command's application environment is empty.
...(process.platform === "win32"
? {
SystemRoot: process.env.SystemRoot,
TEMP: tmpdir(),
TMP: tmpdir(),
}
: {}),
...cliCompileCacheEnvironment(environment, compileCache),
});
/** Keep string entries. A shared process cannot round-trip an absent variable as JSON. */
export const definedCliEnvironment = (
environment: NodeJS.ProcessEnv,
): Record<string, string> =>
Object.fromEntries(
Object.entries(environment).flatMap(([key, value]) =>
typeof value === "string" ? [[key, value] as const] : [],
),
);
/** Reuse CLI compilation without overriding caller-selected cache or coverage. */
export const cliCompileCacheEnvironment = (
environment: NodeJS.ProcessEnv | undefined,
compileCache?: string,
): NodeJS.ProcessEnv => ({
...(compileCache === undefined || environment?.NODE_V8_COVERAGE !== undefined
? {}
: { NODE_COMPILE_CACHE: compileCache }),
...environment,
});
/**
* Whether the file's shared process reports this command exactly as a fresh
* `rea` process would. Stdin and deadlines belong to a process; the launcher
* routes MCP and its doctor before the shared one-shot path; Node options
* change the process itself; and enabled logging, whether selected or a
* command default, writes outside the
* per-command output capture.
*/
const sharedProcessCanServe = ({
arguments: arguments_,
environment,
input,
timeoutMs,
freshProcess,
terminal,
}: CliInvocation): boolean =>
freshProcess !== true &&
terminal !== true &&
input === undefined &&
timeoutMs === undefined &&
arguments_[0] !== "mcp" &&
arguments_[0] !== "--mcp" &&
productionMcpDoctorArguments([...arguments_]) === undefined &&
environment?.NODE_OPTIONS === undefined &&
!enablesLogging(environment?.REA_LOG_LEVEL) &&
!logsByDefault(arguments_, environment?.REA_LOG_LEVEL);
/** A command that logs at info by default unless REA_LOG_LEVEL selects otherwise. */
const logsByDefault = (
arguments_: readonly string[],
level: string | undefined,
): boolean =>
level === undefined &&
DEFAULT_INFO_LOGGING_COMMANDS.has(
splitIncurBuiltinArguments([...arguments_]).command[0] ?? "",
);
/** A valid level other than silent; an invalid level is a captured refusal. */
const enablesLogging = (level: string | undefined): boolean => {
if (level === undefined) return false;
const parsed = parseLogLevel(level);
return parsed.ok && parsed.value !== "silent";
};
/** Create a compiled CLI driver backed by the supplied process registry. */
export const createTestCli = (
processes: TestProcesses,
compileCache?: string,
): TestCli => ({
run: async ({
arguments: arguments_,
cwd,
environment,
input,
timeoutMs,
terminal,
}) => {
if (terminal === true && input !== undefined)
throw new Error("A terminal run has an empty stdin.");
const rea = [resolve("scripts/rea.mjs"), ...arguments_];
const { command, arguments: commandArguments } =
terminal === true
? terminalStdoutInvocation(process.execPath, rea)
: { command: process.execPath, arguments: rea };
const result = await processes.run(command, commandArguments, {
cwd: cwd ?? process.cwd(),
env: cliProcessEnvironment(environment, compileCache),
...(input === undefined ? {} : { input }),
...(timeoutMs === undefined ? {} : { timeoutMs }),
});
return { ...result, json: parseJson(result.stdout) };
},
});
/** Vitest API extended with an owned process registry and compiled CLI driver. */
export const cliTest = processTest.extend<{
$test: { cli: TestCli };
$file: { mcpSession: SharedMcpSession; cliCommandSession: CliCommandSession };
$worker: { cliCompileCache: string };
}>({
cliCompileCache: [
// oxlint-disable-next-line no-empty-pattern -- Vitest parses fixture dependencies from object destructuring.
async ({}, use) => {
const workspace = await createTestWorkspace("rea-cli-compile-cache-");
try {
await use(workspace.path("node-compile"));
} finally {
await removeTestWorkspace(workspace.root);
}
},
{ scope: "worker" },
],
mcpSession: [
async ({ cliCompileCache }, use) => {
const opened = createFileMcpSession(cliCompileCache);
try {
await use(opened.session);
} finally {
await opened.close();
}
},
{ scope: "file" },
],
cliCommandSession: [
// oxlint-disable-next-line no-empty-pattern -- Vitest parses fixture dependencies from object destructuring.
async ({}, use) => {
const session = createCliCommandSession();
try {
await use(session);
} finally {
await session.close();
}
},
{ scope: "file" },
],
cli: async (
{ processes, cliCompileCache, mcpSession, cliCommandSession },
use,
) => {
const cli = createTestCli(processes, cliCompileCache);
await use({
run: (invocation) =>
sharedProcessCanServe(invocation)
? cliCommandSession.run({
arguments: invocation.arguments,
cwd: invocation.cwd ?? process.cwd(),
environment: definedCliEnvironment(
cliProcessEnvironment(invocation.environment, cliCompileCache),
),
})
: cli.run(invocation),
sharedMcpCall: () => mcpSession.call(),
});
},
});