Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(cli): stream JSON results at the shared command boundary
morluto810107a2ad15
diff --git a/src/cli.ts b/src/cli.tsindex 590887c2a..36dcd1275 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -31,7 +31,10 @@ import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRunimport { registerApplicationCommands } from "./cli/applicationCommands.js";import { presentOmittableDefaults } from "./cli/omittableDefaults.js";import type { CliInstance } from "./cli/types.js";-import type { CliResultOutput } from "./cli/streamedJsonOutput.js";+import {+ streamCliCommandResults,+ type CliResultOutput,+} from "./cli/streamedJsonOutput.js";/*** Build the one-shot Incur CLI without starting Hopper at import time.@@ -64,12 +67,7 @@ export const createCli = (});registerSetupCommands(cli, logger, environment);- registerCoreAnalysisCommands(- cli,- logger,- analysis.runDirectAnalysis,- resultOutput,- );+ registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis);registerUtilityCommands(cli, logger, environment, analysis);registerEvmCommands(cli, logger, environment);registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);@@ -89,9 +87,10 @@ export const createCli = (registerJavaScriptRecoveryCommands(cli, logger, environment);registerAdvancedBrowserCommands(cli, logger);registerBrowserScenarioCommands(cli, logger, environment);- registerElectronCommands(cli, logger, environment, resultOutput);+ registerElectronCommands(cli, logger, environment);registerJavaScriptRuntimeObservationCommands(cli, logger);registerApplicationCommands(cli, logger);presentOmittableDefaults(cli);+ if (resultOutput !== undefined) streamCliCommandResults(cli, resultOutput);return cli;};diff --git a/src/cli/coreAnalysisCommands.ts b/src/cli/coreAnalysisCommands.tsindex f72ab1076..999c1b23e 100644--- a/src/cli/coreAnalysisCommands.ts+++ b/src/cli/coreAnalysisCommands.ts@@ -3,15 +3,13 @@ import type { Logger } from "pino";import { registerCoreBinaryCommands } from "./coreBinaryCommands.js";import { registerCoreNativeCommands } from "./coreNativeCommands.js";import type { CliInstance } from "./types.js";-import type { CliResultOutput } from "./streamedJsonOutput.js";/** Register core binary and native deep-analysis CLI commands. */export const registerCoreAnalysisCommands = (cli: CliInstance,logger: Logger,runDirectAnalysis: DirectAnalysis["runDirectAnalysis"],- resultOutput?: CliResultOutput,): void => {- registerCoreBinaryCommands(cli, logger, runDirectAnalysis, resultOutput);+ registerCoreBinaryCommands(cli, logger, runDirectAnalysis);registerCoreNativeCommands(cli, logger, runDirectAnalysis);};diff --git a/src/cli/coreBinaryCommands.ts b/src/cli/coreBinaryCommands.tsindex 5130b8634..a916a2c5a 100644--- a/src/cli/coreBinaryCommands.ts+++ b/src/cli/coreBinaryCommands.ts@@ -15,7 +15,6 @@ import {import type { CliInstance } from "./types.js";import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";import { withCommandCancellation } from "./commandCancellation.js";-import type { CliResultOutput } from "./streamedJsonOutput.js";import { javascriptApplicationOptions } from "../cliObservationOptions.js";/** Register provider-neutral binary overview and procedure CLI commands. */@@ -23,9 +22,8 @@ export const registerCoreBinaryCommands = (cli: CliInstance,logger: Logger,runDirectAnalysis: DirectAnalysis["runDirectAnalysis"],- resultOutput?: CliResultOutput,): void => {- registerOverviewCommands(cli, logger, runDirectAnalysis, resultOutput);+ registerOverviewCommands(cli, logger, runDirectAnalysis);registerDecompileCommand(cli, logger, runDirectAnalysis);registerFunctionCommand(cli, logger, runDirectAnalysis);registerInstructionsCommand(cli, logger, runDirectAnalysis);@@ -38,7 +36,6 @@ const registerOverviewCommands = (cli: CliInstance,logger: Logger,runDirectAnalysis: DirectAnalysis["runDirectAnalysis"],- resultOutput?: CliResultOutput,): void => {const overviewOptions = z.object({snapshot: z@@ -58,11 +55,7 @@ const registerOverviewCommands = (integrityPolicy: javascriptApplicationOptions.shape.integrityPolicy,}),alias: { integrityPolicy: "integrity-policy" },- run: async ({ args, options, format }) => {- const output =- resultOutput === undefined- ? undefined- : { output: resultOutput, command: CLI_COMMANDS.analyze, format };+ run: async ({ args, options }) => {// Route JavaScript targets exactly like analyze-javascript-application,// including typed cancellation; cancellation wraps logging so its exit// code is not replaced by the logged failure status.@@ -74,7 +67,6 @@ const registerOverviewCommands = (input_path: resolve(args.path),integrity_policy: options.integrityPolicy,},- output,signal,),),diff --git a/src/cli/electronCommands.ts b/src/cli/electronCommands.tsindex 79dcd7cc1..73e59fec5 100644--- a/src/cli/electronCommands.ts+++ b/src/cli/electronCommands.ts@@ -24,7 +24,6 @@ import {javascriptApplicationOptions,} from "../cliObservationOptions.js";import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";-import type { CliResultOutput } from "./streamedJsonOutput.js";import { withCommandCancellation } from "./commandCancellation.js";/** Register CLI equivalents of the Electron MCP tools. */@@ -32,11 +31,10 @@ export const registerElectronCommands = (cli: ReturnType<typeof Cli.create>,logger: Logger,environment: Readonly<Record<string, string | undefined>>,- resultOutput?: CliResultOutput,): void => {registerElectronObservationCommands(cli, logger);registerElectronActiveCommand(cli, logger, environment);- registerJavaScriptApplicationCommand(cli, logger, resultOutput);+ registerJavaScriptApplicationCommand(cli, logger);registerJavaScriptRuntimeReconciliationCommand(cli, logger);};@@ -184,7 +182,6 @@ const registerElectronPageInspection = (const registerJavaScriptApplicationCommand = (cli: ReturnType<typeof Cli.create>,logger: Logger,- resultOutput?: CliResultOutput,): void => {cli.command(CLI_COMMANDS.analyzeJavaScriptApplication, {description:@@ -194,7 +191,7 @@ const registerJavaScriptApplicationCommand = (}),options: javascriptApplicationOptions,alias: { integrityPolicy: "integrity-policy" },- run: ({ args, options, format }) =>+ run: ({ args, options }) =>withCommandCancellation((signal) =>logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () =>runCliJavaScriptApplicationAnalysis(@@ -203,13 +200,6 @@ const registerJavaScriptApplicationCommand = (format: options.artifactFormat,integrity_policy: options.integrityPolicy,},- resultOutput === undefined- ? undefined- : {- output: resultOutput,- command: CLI_COMMANDS.analyzeJavaScriptApplication,- format,- },signal,),),diff --git a/src/cli/javascriptApplicationAnalysis.ts b/src/cli/javascriptApplicationAnalysis.tsindex 150a7a913..26fad1e3e 100644--- a/src/cli/javascriptApplicationAnalysis.ts+++ b/src/cli/javascriptApplicationAnalysis.ts@@ -2,15 +2,12 @@ import { analyzeJavaScriptApplication } from "../application/javascript/JavaScriimport { createProgressReporter } from "../application/ProgressReporter.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import type { JsonValue } from "../domain/jsonValue.js";-import type { CliCommandOutput } from "./streamedJsonOutput.js";/** Execute the shared one-shot CLI boundary for static JavaScript analysis. */export const runCliJavaScriptApplicationAnalysis = async (input: unknown,- output?: CliCommandOutput,signal?: AbortSignal,-): Promise<JsonValue | undefined> => {- const started = performance.now();+): Promise<JsonValue> => {const progress = createProgressReporter(async (update) => {process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);@@ -21,18 +18,7 @@ export const runCliJavaScriptApplicationAnalysis = async (progress,...(signal === undefined ? {} : { signal }),});- const value = result.ok ? result.value : cliError(result.error);- if (- output !== undefined &&- (await output.output.write(value, {- command: output.command,- format: output.format,- duration: `${Math.round(performance.now() - started)}ms`,- }))- )- // Keep failures visible to command logging after the stream has handled stdout.- return result.ok ? undefined : value;- return value;+ return result.ok ? result.value : cliError(result.error);};const cliError = (diff --git a/src/cli/jsonOutput.ts b/src/cli/jsonOutput.tsindex 93df9abd3..b42bd82bd 100644--- a/src/cli/jsonOutput.ts+++ b/src/cli/jsonOutput.ts@@ -10,7 +10,7 @@ export const writeJsonOutput = async (destination: Writable,format: JsonOutputFormat = "json",): Promise<void> => {- for (const part of bufferedJsonParts(documentParts(value, format)))+ for (const part of bufferedJsonParts(jsonOutputParts(value, format)))await writePart(destination, part);};@@ -35,7 +35,8 @@ const writePart = (destination: Writable, part: string): Promise<void> =>}});-function* documentParts(+/** The exact formatted document, including its final newline. */+export function* jsonOutputParts(value: unknown,format: JsonOutputFormat,): Generator<string> {diff --git a/src/cli/streamedJsonOutput.ts b/src/cli/streamedJsonOutput.tsindex 282316d0a..64977c22d 100644--- a/src/cli/streamedJsonOutput.ts+++ b/src/cli/streamedJsonOutput.ts@@ -1,10 +1,16 @@+import { constants } from "node:buffer";import { type Writable } from "node:stream";-import { Filter } from "incur";+import { Cli, Filter } from "incur";import { parseCliOutputArguments } from "../cliOutput.js";-import type { JsonValue } from "../domain/jsonValue.js";-import { writeJsonOutput } from "./jsonOutput.js";+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";+import {+ projectAnalysisError,+ type AnalysisErrorProjection,+} from "../domain/analysisErrorProjection.js";+import { jsonOutputParts, writeJsonOutput } from "./jsonOutput.js";+import type { CliInstance } from "./types.js";/** Result metadata supplied by the command that actually ran. */export interface CliResultOutputMetadata {@@ -17,15 +23,82 @@ export interface CliResultOutputMetadata {export interface CliResultOutput {readonly handled: boolean;readonly failed: boolean;- write(value: JsonValue, metadata: CliResultOutputMetadata): Promise<boolean>;+ readonly error: AnalysisErrorProjection | undefined;+ write(value: unknown, metadata: CliResultOutputMetadata): Promise<boolean>;}-/** Selected command output context, independent of application workflows. */-export interface CliCommandOutput {- readonly output: CliResultOutput;- readonly command: string;- readonly format: string;-}+type CommandMap = NonNullable<ReturnType<typeof Cli.toCommands.get>>;+type CommandDefinition = Extract<+ CommandMap extends Map<string, infer Entry> ? Entry : never,+ { run: unknown }+>;+const registeredCommands: WeakMap<object, CommandMap> = Cli.toCommands;++/** Install formatting once, after registration, for every ordinary CLI result. */+export const streamCliCommandResults = (+ cli: CliInstance,+ output: CliResultOutput,+): void => {+ const commands = registeredCommands.get(cli);+ if (commands !== undefined) wrapCommands(commands, [], output);+};++const wrapCommands = (+ commands: CommandMap,+ parents: readonly string[],+ output: CliResultOutput,+): void => {+ for (const [name, entry] of commands) {+ const path = [...parents, name];+ if ("_group" in entry) {+ wrapCommands(entry.commands, path, output);+ if (entry.root !== undefined)+ wrapCommand(entry.root, path.join(" "), output);+ } else if (!("_alias" in entry) && !("_fetch" in entry))+ wrapCommand(entry, path.join(" "), output);+ }+};++const wrapCommand = (+ command: Pick<CommandDefinition, "run">,+ name: string,+ output: CliResultOutput,+): void => {+ const run = command.run;+ command.run = (context) => {+ const started = performance.now();+ const result: unknown = run(context);+ // Generator results and Incur's sentinel responses retain their own protocol.+ if (+ typeof result === "object" &&+ result !== null &&+ Symbol.asyncIterator in result+ )+ return result;+ return Promise.resolve(result).then(async (value: unknown) => {+ if (+ typeof value === "object" &&+ value !== null &&+ Symbol.for("incur.sentinel") in value+ )+ return value;+ if (+ !(await output.write(value, {+ command: name,+ format: context.format,+ duration: `${Math.round(performance.now() - started)}ms`,+ }))+ )+ return value;+ if (output.error !== undefined)+ return context.error({+ code: output.error.code,+ message: output.error.message,+ });+ return undefined;+ });+ };+};/** Preserve Incur's JSON controls while streaming the complete result. */export const createStreamedCliJsonOutput = (@@ -35,7 +108,6 @@ export const createStreamedCliJsonOutput = (const options = parseCliOutputArguments(arguments_);if (options.parseError ||- options.tokenCount ||options.tokenWindow ||(options.format !== "json" && options.format !== "jsonl"))@@ -43,6 +115,7 @@ export const createStreamedCliJsonOutput = (const format = options.format;let handled = false;let failed = false;+ let error: AnalysisErrorProjection | undefined;return {get handled() {return handled;@@ -50,6 +123,9 @@ export const createStreamedCliJsonOutput = (get failed() {return failed;},+ get error() {+ return error;+ },async write(value, metadata) {if (metadata.format !== format) return false;const filtered: unknown = options.filterOutput@@ -59,6 +135,36 @@ export const createStreamedCliJsonOutput = (command: metadata.command,duration: metadata.duration,};+ if (options.tokenCount) {+ // Incur/tokenx materialize the formatted value. Measure its UTF-16+ // expansion before allowing that allocation, independently of UTF-8 bytes.+ let characters = 0;+ if (+ filtered !== undefined &&+ filtered !== null &&+ typeof filtered !== "function" &&+ typeof filtered !== "symbol"+ )+ for (const part of jsonOutputParts(filtered, format))+ characters += part.length;+ characters = Math.max(0, characters - 1);+ if (characters <= constants.MAX_STRING_LENGTH) return false;+ error = projectAnalysisError(+ new AnalysisResourceConstraintError(+ metadata.command,+ "memory",+ "Token counting requires a formatted string larger than the runtime permits.",+ {+ formatted_characters: characters,+ max_string_characters: constants.MAX_STRING_LENGTH,+ },+ {+ remediationAction:+ "Remove --token-count to stream the complete JSON result, or narrow it with --filter-output.",+ },+ ),+ );+ }const document = options.fullOutput? filtered === undefined? { ok: true, meta }@@ -73,7 +179,15 @@ export const createStreamedCliJsonOutput = (// document from Incur's error formatter.handled = true;try {- await writeJsonOutput(document, destination, format);+ await writeJsonOutput(+ error === undefined+ ? document+ : options.fullOutput+ ? { ok: false, error, meta }+ : error,+ destination,+ format,+ );} catch (cause: unknown) {failed = true;throw cause;diff --git a/tests/acceptance/managedCliOutput.test.ts b/tests/acceptance/managedCliOutput.test.tsnew file mode 100644index 000000000..84cec5222--- /dev/null+++ b/tests/acceptance/managedCliOutput.test.ts@@ -0,0 +1,62 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";++import { expect } from "vitest";++import { buildManagedPeFixture } from "../../src/dotnet/ManagedPe.fixture.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+import { cliTest } from "../support/cli/cliFixture.js";++cliTest(+ "managed CLI preserves evidence, filters, envelopes, and bounded token counts",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-managed-cli-output-");+ const path = join(root, "fixture.dll");+ await writeFile(path, buildManagedPeFixture());+ const argv = ["inspect-managed-members", path, "--json"];+ const result = await cli.run({ arguments: argv });+ expect(result.exitCode).toBe(0);+ expect(result.json).toMatchObject({+ operation: "inspect_managed_members",+ provider: { id: "rea-dotnet-static" },+ subject: { local_path: path },+ normalized_result: {+ methods: [expect.objectContaining({ token: expect.any(String) })],+ },+ });+ const filtered = await cli.run({+ arguments: [...argv, "--filter-output", "operation", "--full-output"],+ });+ expect(filtered.exitCode).toBe(0);+ expect(filtered.json).toMatchObject({+ ok: true,+ data: "inspect_managed_members",+ meta: {+ command: "inspect-managed-members",+ duration: expect.stringMatching(/^\d+ms$/u),+ },+ });+ const count = await cli.run({+ arguments: [...argv, "--filter-output", "operation", "--token-count"],+ });+ expect(count.exitCode).toBe(0);+ expect(count.stdout).toMatch(/^\d+\n$/u);+ const omittedCount = await cli.run({+ arguments: [...argv, "--filter-output", "toString", "--token-count"],+ });+ expect(omittedCount.exitCode).toBe(0);+ expect(omittedCount.stdout).toBe("0\n");+ const jsonl = await cli.run({+ arguments: [+ "inspect-managed-members",+ path,+ "--format",+ "jsonl",+ "--filter-output",+ "operation",+ ],+ });+ expect(jsonl.exitCode).toBe(0);+ expect(jsonl.json).toBe("inspect_managed_members");+ },+);diff --git a/tests/boundary/cli/jsonOutput.test.ts b/tests/boundary/cli/jsonOutput.test.tsindex 7c1ff4ddd..029407388 100644--- a/tests/boundary/cli/jsonOutput.test.ts+++ b/tests/boundary/cli/jsonOutput.test.ts@@ -1,9 +1,17 @@+import { constants } from "node:buffer";+import { createHash } from "node:crypto";import { Writable } from "node:stream";+import { Cli } from "incur";import { describe, expect, it } from "vitest";import { writeJsonOutput } from "../../../src/cli/jsonOutput.js";-import { createStreamedCliJsonOutput } from "../../../src/cli/streamedJsonOutput.js";+import {+ createStreamedCliJsonOutput,+ streamCliCommandResults,+} from "../../../src/cli/streamedJsonOutput.js";+import { registerManagedCommands } from "../../../src/cli/managedCommands.js";+import { silentLogger } from "../../../src/logger.js";const collect = async (value: unknown,@@ -140,7 +148,6 @@ describe("streamed CLI result surface", () => {it.each([[],["--format", "md"],- ["--json", "--token-count"],["--json", "--token-limit", "5"],["--json", "--format", "invalid"],])("delegates unsupported output controls %j", (...arguments_) => {@@ -167,4 +174,104 @@ describe("streamed CLI result surface", () => {expect(output.handled).toBe(true);expect(output.failed).toBe(true);});++ it("streams managed command output past the engine string limit and declines oversized token counting", async () => {+ const leaf = "x".repeat(64 * 1024);+ const count = Math.ceil(constants.MAX_STRING_LENGTH / leaf.length) + 1;+ const value = { methods: Array.from({ length: count }, () => leaf) };+ const expected = createHash("sha256");+ const encodedLeaf = JSON.stringify(leaf);+ const prefix = '{\n "methods": [\n ';+ const separator = ",\n ";+ const suffix = "\n ]\n}\n";+ expected.update(prefix);+ for (let index = 0; index < count; index += 1) {+ if (index > 0) expected.update(separator);+ expected.update(encodedLeaf);+ }+ expected.update(suffix);+ const expectedCharacters =+ prefix.length ++ count * encodedLeaf.length ++ (count - 1) * separator.length ++ suffix.length;+ expect(expectedCharacters).toBeGreaterThan(constants.MAX_STRING_LENGTH);++ const actual = createHash("sha256");+ let bytes = 0;+ const destination = new Writable({+ write(chunk: Buffer, _encoding, callback) {+ bytes += chunk.length;+ actual.update(chunk);+ callback();+ },+ });+ const cli = Cli.create("rea-output-test", { sync: false });+ registerManagedCommands(cli, silentLogger, async (path, operation) => {+ expect(path).toBe("fixture.dll");+ expect(operation).toBe("inspect_managed_members");+ return value;+ });+ const argv = ["inspect-managed-members", "fixture.dll", "--json"];+ const output = createStreamedCliJsonOutput(argv, destination);+ if (output === undefined) throw new Error("Missing JSON output surface");+ streamCliCommandResults(cli, output);+ let exitCode = 0;+ let fallbackBytes = 0;+ await cli.serve(argv, {+ stdout: (text) => {+ if (!output.handled) fallbackBytes += text.length;+ },+ exit: (code) => {+ exitCode = code;+ },+ });+ expect(exitCode).toBe(0);+ expect(fallbackBytes).toBe(0);+ expect(bytes).toBe(expectedCharacters);+ expect(actual.digest("hex")).toBe(expected.digest("hex"));++ const chunks: Buffer[] = [];+ const tokenArgv = [...argv, "--token-count", "--full-output"];+ const tokenOutput = createStreamedCliJsonOutput(+ tokenArgv,+ new Writable({+ write(chunk: Buffer, _encoding, callback) {+ chunks.push(chunk);+ callback();+ },+ }),+ );+ if (tokenOutput === undefined)+ throw new Error("Missing token-count output surface");+ const tokenCli = Cli.create("rea-output-test", { sync: false });+ registerManagedCommands(tokenCli, silentLogger, async () => value);+ streamCliCommandResults(tokenCli, tokenOutput);+ await tokenCli.serve(tokenArgv, {+ stdout: (text) => {+ if (!tokenOutput.handled) fallbackBytes += text.length;+ },+ exit: (code) => {+ exitCode = code;+ },+ });+ expect(exitCode).toBe(1);+ expect(fallbackBytes).toBe(0);+ expect(JSON.parse(Buffer.concat(chunks).toString("utf8"))).toMatchObject({+ ok: false,+ error: {+ code: "resource_constraint",+ remediation: {+ action: expect.stringContaining("Remove --token-count"),+ },+ details: {+ reported_limits: {+ formatted_characters: expectedCharacters - 1,+ max_string_characters: constants.MAX_STRING_LENGTH,+ },+ },+ },+ meta: { command: "inspect-managed-members" },+ });+ }, 60_000);});