Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

refactor(config): take the environment as an input at every configuration read (#554)

morluto53fe7d6d3b36
diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts
index 1025e7fdf..3cf34ab25 100644
--- a/src/application/DirectAnalysis.ts
+++ b/src/application/DirectAnalysis.ts
@@ -195,10 +195,18 @@ const runAnalysis = async (
readonly signal: AbortSignal;
readonly permissionAuthority?: PermissionAuthority;
readonly providerId?: AnalysisProviderSelector;
+ /**
+ * Environment the configuration is read from. Defaults to the process
+ * environment so existing callers are unchanged, but a caller may supply
+ * one — which is what lets the MCP path's injected environment reach this
+ * code, and what makes configuration-driven behaviour testable without
+ * mutating `process.env`.
+ */
+ readonly environment?: Readonly<Record<string, string | undefined>>;
},
): Promise<JsonValue> => {
const { logger, signal, snapshotPath } = options;
- const config = parseConfig(process.env);
+ const config = parseConfig(options.environment ?? process.env);
if (!config.ok) return cliError(config.error);
const authorization = await authorizeAnalysisRun({
config: config.value,
diff --git a/src/application/DirectAnalysisStatus.ts b/src/application/DirectAnalysisStatus.ts
index f3712d9f8..5c36443d6 100644
--- a/src/application/DirectAnalysisStatus.ts
+++ b/src/application/DirectAnalysisStatus.ts
@@ -7,8 +7,9 @@ import { createBinarySession } from "./runtime.js";
const runSessionStatus = async (
logger: Logger = silentLogger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): Promise<JsonValue> => {
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return { error: projectAnalysisError(config.error) };
const session = createBinarySession(config.value, logger);
try {
@@ -24,9 +25,13 @@ const runSessionStatus = async (
};
/** List complete provider identities, capabilities, and availability. */
-export const runProviderStatus = (logger: Logger = silentLogger) =>
- runSessionStatus(logger);
+export const runProviderStatus = (
+ logger: Logger = silentLogger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => runSessionStatus(logger, environment);
/** List complete operation descriptors and availability. */
-export const runCapabilityStatus = (logger: Logger = silentLogger) =>
- runSessionStatus(logger);
+export const runCapabilityStatus = (
+ logger: Logger = silentLogger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => runSessionStatus(logger, environment);
diff --git a/src/application/ProcessCli.ts b/src/application/ProcessCli.ts
index 7a841c204..ca3f2af96 100644
--- a/src/application/ProcessCli.ts
+++ b/src/application/ProcessCli.ts
@@ -32,7 +32,10 @@ export interface ProcessCliErrorOutput {
}
/** Capture one JSON scenario through the same policy and evidence contract as MCP. */
-export const captureProcessScenarioFile = async (path: string) => {
+export const captureProcessScenarioFile = async (
+ path: string,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => {
try {
const input = await readJson(path);
let scenario;
@@ -44,7 +47,7 @@ export const captureProcessScenarioFile = async (path: string) => {
"Process scenario is invalid. Check its required fields and limits, then try again.",
);
}
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return cliAnalysisError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return cliAnalysisError(authority.error);
diff --git a/src/cli.ts b/src/cli.ts
index eedd2c1d2..b9c082095 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -24,12 +24,14 @@ import type { CliInstance } from "./cli/types.js";
* Analysis commands acquire and close their own sessions; bare `mcp` and
* `--mcp` are intercepted by the executable dispatcher before this module loads.
*/
-export const createCli = (): CliInstance => {
+export const createCli = (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): CliInstance => {
const logger = createLogger(
"cli",
- process.env.REA_LOG_LEVEL === undefined
+ environment.REA_LOG_LEVEL === undefined
? "silent"
- : parseLogLevel(process.env.REA_LOG_LEVEL),
+ : parseLogLevel(environment.REA_LOG_LEVEL),
);
const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
version: PRODUCT_IDENTITY.packageVersion,
@@ -52,17 +54,17 @@ export const createCli = (): CliInstance => {
registerSetupCommands(cli, logger);
registerCoreAnalysisCommands(cli, logger);
- registerUtilityCommands(cli, logger);
+ registerUtilityCommands(cli, logger, environment);
registerArtifactCommands(cli, logger);
- registerManagedCommands(cli, logger);
+ registerManagedCommands(cli, logger, environment);
registerEvidenceCommands(cli, logger);
registerProcessCommands(cli, logger);
- registerPolicyCommands(cli, logger);
+ registerPolicyCommands(cli, logger, environment);
registerBrowserCommands(cli, logger);
registerAdvancedBrowserCommands(cli, logger);
- registerBrowserScenarioCommands(cli, logger);
- registerElectronCommands(cli, logger);
- registerJavaScriptRuntimeObservationCommands(cli, logger);
- registerApplicationCommands(cli, logger);
+ registerBrowserScenarioCommands(cli, logger, environment);
+ registerElectronCommands(cli, logger, environment);
+ registerJavaScriptRuntimeObservationCommands(cli, logger, environment);
+ registerApplicationCommands(cli, logger, environment);
return cli;
};
diff --git a/src/cli/managedCommands.ts b/src/cli/managedCommands.ts
index 458fc8a6a..f18e1c79a 100644
--- a/src/cli/managedCommands.ts
+++ b/src/cli/managedCommands.ts
@@ -18,6 +18,7 @@ import { registerProjectManagedApplicationGraph } from "./managedProjectGraphCom
export const registerManagedCommands = (
cli: CliInstance,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
registerInspectManagedArtifact(cli, logger);
registerInspectManagedMembers(cli, logger);
@@ -25,7 +26,7 @@ export const registerManagedCommands = (
registerCompareManagedMembers(cli, logger);
registerImportManagedReconstruction(cli, logger);
registerVerifyManagedNativeBoundaries(cli, logger);
- registerPlanManagedRuntimeCorrelation(cli, logger);
+ registerPlanManagedRuntimeCorrelation(cli, logger, environment);
registerProjectManagedApplicationGraph(cli, logger);
};
@@ -166,6 +167,7 @@ const registerVerifyManagedNativeBoundaries = (
const registerPlanManagedRuntimeCorrelation = (
cli: CliInstance,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.planManagedRuntimeCorrelation, {
description:
@@ -182,7 +184,7 @@ const registerPlanManagedRuntimeCorrelation = (
"plan-managed-runtime-correlation",
);
if (!input.ok) return input.error;
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return projectAnalysisError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return projectAnalysisError(authority.error);
diff --git a/src/cli/utilityCommands.ts b/src/cli/utilityCommands.ts
index 78b6bdc0a..24ded0f82 100644
--- a/src/cli/utilityCommands.ts
+++ b/src/cli/utilityCommands.ts
@@ -19,6 +19,7 @@ import type { CliInstance } from "./types.js";
export const registerUtilityCommands = (
cli: CliInstance,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
registerCapabilityCommands(cli, logger);
registerNativeCommands(cli, logger);
@@ -111,7 +112,7 @@ export const registerUtilityCommands = (
),
});
}
- registerReferenceSourceCommand(cli, logger);
+ registerReferenceSourceCommand(cli, logger, environment);
};
const registerCapabilityCommands = (cli: CliInstance, logger: Logger): void => {
@@ -193,6 +194,7 @@ const registerNativeCommands = (cli: CliInstance, logger: Logger): void => {
const registerReferenceSourceCommand = (
cli: CliInstance,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.importReferenceSource, {
description: "Import a source tree as historical reference only",
@@ -203,7 +205,7 @@ const registerReferenceSourceCommand = (
}),
run: ({ args }) =>
logCliCommand(logger, "import-reference-source", async () => {
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok)
return {
error: "Import failed",
diff --git a/src/cliApplicationCommands.ts b/src/cliApplicationCommands.ts
index a995856de..19658bf0e 100644
--- a/src/cliApplicationCommands.ts
+++ b/src/cliApplicationCommands.ts
@@ -47,6 +47,7 @@ type CliInstance = ReturnType<typeof Cli.create>;
export const registerApplicationCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
registerJsonCommand({
cli,
@@ -106,7 +107,7 @@ export const registerApplicationCommands = (
CLI_COMMANDS.runControlledReplay,
);
if (!input.ok) return input.error;
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return projectAnalysisError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return projectAnalysisError(authority.error);
@@ -167,6 +168,8 @@ const registerObligationLedgerCommand = (
interface AuthorizedJsonCommandOptions {
readonly cli: CliInstance;
readonly logger: Logger;
+ /** Environment the configuration is read from; defaults to the process environment. */
+ readonly environment?: Readonly<Record<string, string | undefined>>;
readonly name: string;
readonly description: string;
readonly workflow: (
@@ -182,6 +185,7 @@ interface AuthorizedJsonCommandOptions {
const registerAuthorizedJsonCommand = ({
cli,
logger,
+ environment = process.env,
name,
description,
workflow,
@@ -195,7 +199,7 @@ const registerAuthorizedJsonCommand = ({
logCliCommand(logger, name, async () => {
const input = await parseCliJsonInput(args.inputJson, name);
if (!input.ok) return input.error;
- const configured = await configuredAuthority();
+ const configured = await configuredAuthority(environment);
if (!configured.ok) return configured.error;
const result = await workflow(
configured.config,
@@ -222,7 +226,9 @@ const registerCoverageCommand = (cli: CliInstance, logger: Logger): void =>
},
});
-const configuredAuthority = async (): Promise<
+const configuredAuthority = async (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<
| {
readonly ok: true;
readonly config: AppConfig;
@@ -233,7 +239,7 @@ const configuredAuthority = async (): Promise<
readonly error: ReturnType<typeof projectAnalysisError>;
}
> => {
- const configured = await loadConfiguredAuthority();
+ const configured = await loadConfiguredAuthority(environment);
return configured.ok
? configured
: { ok: false, error: projectAnalysisError(configured.error) };
@@ -302,7 +308,9 @@ const registerJsonCommand = <Schema extends z.ZodType>({
});
};
-const loadConfiguredAuthority = async (): Promise<
+const loadConfiguredAuthority = async (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<
| {
readonly ok: true;
readonly config: AppConfig;
@@ -310,7 +318,7 @@ const loadConfiguredAuthority = async (): Promise<
}
| { readonly ok: false; readonly error: AnalysisError }
> => {
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return config;
const authority = await loadConfiguredPermissionAuthority(config.value);
return authority.ok
diff --git a/src/cliBrowserScenarioCommands.ts b/src/cliBrowserScenarioCommands.ts
index 881dcfbc4..f09eaa549 100644
--- a/src/cliBrowserScenarioCommands.ts
+++ b/src/cliBrowserScenarioCommands.ts
@@ -19,6 +19,7 @@ const OPERATION = "capture_browser_scenario";
export const registerBrowserScenarioCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.captureBrowserScenario, {
description:
@@ -35,7 +36,7 @@ export const registerBrowserScenarioCommands = (
const scenario = browserScenarioSchema.safeParse(input.value);
if (!scenario.success)
return cliError(new AnalysisInputError(OPERATION));
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return cliError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return cliError(authority.error);
diff --git a/src/cliElectronCommands.ts b/src/cliElectronCommands.ts
index 30f0230dc..75b7e9912 100644
--- a/src/cliElectronCommands.ts
+++ b/src/cliElectronCommands.ts
@@ -35,9 +35,10 @@ import { runCliJavaScriptApplicationAnalysis } from "./cli/javascriptApplication
export const registerElectronCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
registerElectronObservationCommands(cli, logger);
- registerElectronActiveCommand(cli, logger);
+ registerElectronActiveCommand(cli, logger, environment);
registerJavaScriptApplicationCommand(cli, logger);
registerJavaScriptRuntimeReconciliationCommand(cli, logger);
};
@@ -45,6 +46,7 @@ export const registerElectronCommands = (
const registerElectronActiveCommand = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.captureElectronScenario, {
description: "Run one approved, bounded owned Electron scenario",
@@ -66,7 +68,7 @@ const registerElectronActiveCommand = (
input.value,
);
if (!parsed.success) return inputError("capture_electron_scenario");
- const context = await electronContext();
+ const context = await electronContext(environment);
if (!context.ok) return context.error;
const result = await captureElectronScenario(
context.activeProvider,
@@ -201,8 +203,10 @@ const registerJavaScriptApplicationCommand = (
});
};
-const electronContext = async () => {
- const config = parseConfig(process.env);
+const electronContext = async (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => {
+ const config = parseConfig(environment);
if (!config.ok) return { ok: false as const, error: cliError(config.error) };
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok)
@@ -216,8 +220,11 @@ const electronContext = async () => {
};
};
-const electronObservationContext = async (operation: string) => {
- const context = await electronContext();
+const electronObservationContext = async (
+ operation: string,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => {
+ const context = await electronContext(environment);
if (!context.ok) return context;
if (context.observationPolicy.status === "disabled")
return {
diff --git a/src/cliEnvironmentSeam.test.ts b/src/cliEnvironmentSeam.test.ts
new file mode 100644
index 000000000..339830078
--- /dev/null
+++ b/src/cliEnvironmentSeam.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { createCli } from "./cli.js";
+import { createSystemDoctorHost } from "./doctorRuntime.js";
+import { captureProcessScenarioFile } from "./application/ProcessCli.js";
+import { runCapabilityStatus } from "./application/DirectAnalysisStatus.js";
+
+describe("the CLI takes its environment as an input", () => {
+ it("builds from an explicitly supplied environment", () => {
+ expect(createCli({ REA_LOG_LEVEL: "debug" })).toBeDefined();
+ expect(createCli({})).toBeDefined();
+ });
+
+ it("still builds with no environment supplied", () => {
+ // The default keeps production behaviour identical.
+ expect(createCli()).toBeDefined();
+ expect(createSystemDoctorHost()).toBeDefined();
+ });
+
+ it("builds a doctor host from an explicit environment", () => {
+ expect(createSystemDoctorHost({})).toBeDefined();
+ });
+
+ it("drives a process scenario failure from the supplied environment", async () => {
+ await expect(
+ captureProcessScenarioFile("/nonexistent/scenario.json", {}),
+ ).resolves.toBeDefined();
+ });
+
+ it("reports session status from a supplied environment", async () => {
+ // An invalid configuration must surface through the caller's supplied
+ // environment rather than whatever the process happens to carry.
+ const result = await runCapabilityStatus(undefined, {
+ REA_LOG_LEVEL: "not-a-level",
+ });
+ expect(result).toMatchObject({ error: expect.anything() });
+ });
+});
diff --git a/src/cliJavaScriptRuntimeCommands.ts b/src/cliJavaScriptRuntimeCommands.ts
index eea52a93e..2ad5be418 100644
--- a/src/cliJavaScriptRuntimeCommands.ts
+++ b/src/cliJavaScriptRuntimeCommands.ts
@@ -40,6 +40,7 @@ const observeOptionsSchema = z.object({
export const registerJavaScriptRuntimeObservationCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.listJavaScriptRuntimeTargets, {
description: "List Node/Electron V8 Inspector targets",
@@ -81,7 +82,10 @@ export const registerJavaScriptRuntimeObservationCommands = (
options: observeOptionsSchema,
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.observeJavaScriptRuntime, async () => {
- const context = await runtimeContext("observe_javascript_runtime");
+ const context = await runtimeContext(
+ "observe_javascript_runtime",
+ environment,
+ );
if (!context.ok) return context.error;
const parsed = observeJavaScriptRuntimeInputSchema.safeParse({
inspector_endpoint: args.endpoint,
@@ -100,8 +104,11 @@ export const registerJavaScriptRuntimeObservationCommands = (
});
};
-const runtimeContext = async (operation: string) => {
- const config = parseConfig(process.env);
+const runtimeContext = async (
+ operation: string,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+) => {
+ const config = parseConfig(environment);
if (!config.ok) return { ok: false as const, error: cliError(config.error) };
const policy = config.value.v8InspectorObservationPolicy;
if (policy.status === "disabled")
diff --git a/src/cliPolicyCommands.ts b/src/cliPolicyCommands.ts
index 12be3f4b2..ecc8a7fd7 100644
--- a/src/cliPolicyCommands.ts
+++ b/src/cliPolicyCommands.ts
@@ -43,6 +43,7 @@ export const approvePolicyRevocation = async (options: {
export const registerPolicyCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
+ environment: Readonly<Record<string, string | undefined>> = process.env,
): void => {
cli.command(CLI_COMMANDS.policy, {
description: "Inspect, explain, or revoke unified local permission grants",
@@ -89,7 +90,7 @@ export const registerPolicyCommands = (
alias: { environmentNames: "environment-names", yes: "y" },
run: ({ agent, args, formatExplicit, options }) =>
logCliCommand(logger, "policy", async () => {
- const config = parseConfig(process.env);
+ const config = parseConfig(environment);
if (!config.ok) return failure(config.error);
if (args.action === "status") return policyStatus(config.value);
if (args.action === "list") return policyList(config.value);
diff --git a/src/doctorRuntime.ts b/src/doctorRuntime.ts
index 94d60b374..03fa0cd55 100644
--- a/src/doctorRuntime.ts
+++ b/src/doctorRuntime.ts
@@ -10,10 +10,12 @@ import { parseConfig } from "./config.js";
import { SystemJavaScriptReplayHost } from "./replay/SystemJavaScriptReplayHost.js";
/** Compose provider diagnostics at the outer CLI adapter boundary. */
-export const createSystemDoctorHost = (): DoctorHost =>
+export const createSystemDoctorHost = (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): DoctorHost =>
systemDoctorHost({
providerInspections: async () => [await inspectSystemGhidraProvider()],
- javascriptReplayCheck: inspectJavaScriptReplay,
+ javascriptReplayCheck: () => inspectJavaScriptReplay(environment),
linuxDemoRuntimeCheck: inspectLinuxPrivateDisplay,
});
@@ -61,8 +63,10 @@ const inspectLinuxPrivateDisplay = async (): Promise<DoctorCheck> => {
};
};
-const inspectJavaScriptReplay = async (): Promise<DoctorCheck> => {
- const config = parseConfig(process.env);
+const inspectJavaScriptReplay = async (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<DoctorCheck> => {
+ const config = parseConfig(environment);
if (!config.ok)
return {
name: "javascript-replay",