rea-agents 6.4.0 → 6.7.0

package/dist/cli/electronCommands.js

@@ -1,7 +1,5 @@
+import { isAbsolute, resolve, sep } from "node:path";
 import { Cli, z } from "incur";
-import { inspectElectronPage, listElectronTargets, } from "../application/javascript/ElectronObservationService.js";
-import { captureElectronScenario } from "../application/javascript/ElectronActiveObservationService.js";
-import { reconcileJavaScriptRuntimeEvidence } from "../application/javascript/JavaScriptRuntimeReconciliationService.js";
 import { logCliCommand } from "../cliLogging.js";
 import { inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/javascript/electronObservation.js";
 import { electronActiveObservationInputSchema } from "../domain/javascript/electronActiveObservation.js";
@@ -9,17 +7,46 @@ import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { createElectronFuseService } from "../composition/electronFuses.js";
 import { parseCliJsonInput, resolveCliJsonPaths } from "../cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "../cliObservationOptions.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 import { withCommandCancellation } from "./commandCancellation.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
 /** Register CLI equivalents of the Electron MCP tools. */
 export const registerElectronCommands = (cli, logger, environment) => {
     registerElectronObservationCommands(cli, logger);
+    registerElectronFuseCommand(cli, logger);
     registerElectronActiveCommand(cli, logger, environment);
     registerJavaScriptApplicationCommand(cli, logger);
     registerJavaScriptRuntimeReconciliationCommand(cli, logger);
 };
+const registerElectronFuseCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectElectronFuses, {
+        description: "Inspect packaged Electron fuse bytes without launching the application",
+        args: z.object({
+            path: z
+                .string()
+                .describe("Local Electron .app, Electron Framework binary, PE executable, or ELF executable"),
+        }),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectElectronFuses, async () => {
+            const service = createElectronFuseService();
+            return finishAnalysisCommand(() => service.inspect({ path: absoluteElectronFusePath(args.path) }, { signal }), service, service.provider.identity.id, "inspect_electron_fuses", signal);
+        })),
+    });
+};
+/** Anchor relative input without changing which file symlink/.. selects. */
+const absoluteElectronFusePath = (path) => {
+    if (path === "")
+        return path;
+    // Win32 resolves dot components before directory links, including drive-relative paths.
+    if (sep === "\\")
+        return resolve(path);
+    if (isAbsolute(path))
+        return path;
+    const base = process.cwd();
+    return `${base}${base.endsWith(sep) ? "" : sep}${path}`;
+};
 const registerElectronActiveCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureElectronScenario, {
         description: "Run one owned Electron scenario with cancellable actions",
@@ -39,9 +66,17 @@ const registerElectronActiveCommand = (cli, logger, environment) => {
             ]));
             if (!parsed.success)
                 return inputError("capture_electron_scenario", parsed.error.issues, input.value);
+            const { captureElectronScenario } = await import("../application/javascript/ElectronActiveObservationService.js");
             const { createElectronScenarioProvider } = await import("../composition/electronScenario.js");
-            const result = await captureElectronScenario(createElectronScenarioProvider(environment), parsed.data, { signal });
-            return result.ok ? result.value : cliError(result.error);
+            const provider = createElectronScenarioProvider(environment);
+            const result = await finishAnalysisCommand(() => captureElectronScenario(provider, parsed.data, { signal }), {
+                close: async () => {
+                    await provider.close?.();
+                },
+            }, provider.identity().id, "capture_electron_scenario", signal);
+            return "code" in result
+                ? { error: "Electron analysis failed", ...result }
+                : result;
         })),
     });
 };
@@ -57,6 +92,7 @@ const registerJavaScriptRuntimeReconciliationCommand = (cli, logger) => {
             const input = await parseCliJsonInput(args.inputJson, "reconcile_javascript_runtime");
             if (!input.ok)
                 return input.error;
+            const { reconcileJavaScriptRuntimeEvidence } = await import("../application/javascript/JavaScriptRuntimeReconciliationService.js");
             const result = reconcileJavaScriptRuntimeEvidence(input.value);
             return result.ok ? result.value : cliError(result.error);
         }),
@@ -72,16 +108,20 @@ const registerElectronTargetList = (cli, logger) => {
         args: z.object({
             endpoint: z.string().describe("Literal-loopback Electron CDP endpoint"),
         }),
-        run: ({ args }) => logCliCommand(logger, "list-electron-targets", async () => {
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, "list-electron-targets", async () => {
             const context = await electronObservationContext();
             const parsed = listElectronTargetsInputSchema.safeParse({
                 cdp_endpoint: args.endpoint,
             });
             if (!parsed.success)
                 return inputError("list_electron_targets");
-            const result = await listElectronTargets(context.provider, parsed.data);
-            return result.ok ? result.value : cliError(result.error);
-        }),
+            const { listElectronTargets } = await import("../application/javascript/ElectronObservationService.js");
+            return await finishAnalysisCommand(() => listElectronTargets(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, "rea-cdp-electron", "list_electron_targets", signal);
+        })),
     });
 };
 const registerElectronPageInspection = (cli, logger) => {
@@ -92,7 +132,7 @@ const registerElectronPageInspection = (cli, logger) => {
             targetId: z.string().describe("Target ID from list-electron-targets"),
         }),
         options: electronPageInspectionOptions,
-        run: ({ args, options }) => logCliCommand(logger, "inspect-electron-page", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "inspect-electron-page", async () => {
             const context = await electronObservationContext();
             const parsed = inspectElectronPageInputSchema.safeParse({
                 cdp_endpoint: args.endpoint,
@@ -102,9 +142,13 @@ const registerElectronPageInspection = (cli, logger) => {
             });
             if (!parsed.success)
                 return inputError("inspect_electron_page");
-            const result = await inspectElectronPage(context.provider, parsed.data);
-            return result.ok ? result.value : cliError(result.error);
-        }),
+            const { inspectElectronPage } = await import("../application/javascript/ElectronObservationService.js");
+            return await finishAnalysisCommand(() => inspectElectronPage(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, "rea-cdp-electron", "inspect_electron_page", signal);
+        })),
     });
 };
 const registerJavaScriptApplicationCommand = (cli, logger) => {
@@ -118,6 +162,25 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
             input_path: args.path,
             format: options.artifactFormat,
             integrity_policy: options.integrityPolicy,
+            ...(options.maxSemanticNodes === undefined
+                ? {}
+                : { max_semantic_nodes: options.maxSemanticNodes }),
+            ...(options.maxSemanticNodesPerFile === undefined
+                ? {}
+                : {
+                    max_semantic_nodes_per_file: options.maxSemanticNodesPerFile,
+                }),
+            ...(options.maxSemanticUnknowns === undefined
+                ? {}
+                : { max_semantic_unknowns: options.maxSemanticUnknowns }),
+            ...(options.maxSemanticUnknownsPerFile === undefined
+                ? {}
+                : {
+                    max_semantic_unknowns_per_file: options.maxSemanticUnknownsPerFile,
+                }),
+            ...(options.sourcePath === undefined
+                ? {}
+                : { source_paths: options.sourcePath }),
             ...(options.maxHeapMb === undefined
                 ? {}
                 : { max_heap_mb: options.maxHeapMb }),

package/dist/cli/evmCommands.js

@@ -1,14 +1,13 @@
 import { z } from "incur";
-import { resolve } from "node:path";
-import { createEvmInterfaceService } from "../composition/evm.js";
-import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { evmInterfaceModule } from "../composition/evm.js";
 import { logCliCommand } from "../cliLogging.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { withCommandCancellation } from "./commandCancellation.js";
+import { absoluteCallerPath } from "../filesystem/callerPath.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
 /** Resolve operator paths and preserve explicit encoding through the shared workflow. */
 export const registerEvmCommands = (cli, logger, environment) => {
-    const service = createEvmInterfaceService(environment);
-    cli.command(CLI_COMMANDS.inspectEvmInterface, {
+    const service = evmInterfaceModule.create(environment);
+    cli.command(evmInterfaceModule.cliCommand, {
         description: "Infer interface candidates from explicit local EVM bytecode",
         args: z.object({
             path: z.string().describe("Local bytecode carrier"),
@@ -16,18 +15,9 @@ export const registerEvmCommands = (cli, logger, environment) => {
                 .enum(["raw", "hex"])
                 .describe("Selected carrier representation"),
         }),
-        run: ({ args }) => withCommandCancellation(async (signal) => {
-            try {
-                return await logCliCommand(logger, CLI_COMMANDS.inspectEvmInterface, async () => {
-                    const result = await service.inspect({ path: resolve(args.path), encoding: args.encoding }, { signal });
-                    return result.ok
-                        ? result.value
-                        : projectAnalysisError(result.error);
-                });
-            }
-            finally {
-                await service.close();
-            }
-        }),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, evmInterfaceModule.cliCommand, () => finishAnalysisCommand(() => service.inspect({
+            path: absoluteCallerPath(args.path),
+            encoding: args.encoding,
+        }, { signal }), service, "evmole-interface", "inspect_evm_interface", signal))),
     });
 };

package/dist/cli/finishAnalysisCommand.js

@@ -0,0 +1,52 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+/** Finish a one-shot CLI operation while retaining primary results through close. */
+export const finishAnalysisCommand = async (run, service, providerId, canonicalOperation, signal, fallbackResource) => {
+    let result;
+    try {
+        result = await run();
+    }
+    catch (cause) {
+        result = {
+            ok: false,
+            error: cause instanceof AnalysisError
+                ? cause
+                : new ProviderAdapterError(providerId, canonicalOperation, { cause }),
+        };
+    }
+    try {
+        // Resource owners may resolve their retained errors during close. This
+        // adapter cannot infer resolution of a producer's earlier cleanup failure.
+        await service.close();
+    }
+    catch (cause) {
+        let cleanup;
+        if (cause instanceof AnalysisError)
+            cleanup = cause;
+        else {
+            const observation = cause instanceof ArtifactReaderFailure
+                ? ArtifactReaderFailure.cleanupObservation(cause, fallbackResource ?? `${canonicalOperation} resources`)
+                : {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    resources: [],
+                };
+            cleanup = new ProviderCleanupError(providerId, observation.resources, { reason: observation.reason }, { cause, operation: canonicalOperation });
+        }
+        if (result.ok)
+            cleanup.retainPartialObservation(result.value);
+        return projectAnalysisError(result.ok
+            ? cleanup
+            : analysisErrorWithCleanupFailure(result.error, cleanup, canonicalOperation));
+    }
+    if (result.ok && signal.aborted)
+        return projectAnalysisError(new AnalysisCancelledError(canonicalOperation, {
+            cause: signal.reason,
+            partialObservation: result.value,
+        }));
+    return result.ok ? result.value : projectAnalysisError(result.error);
+};

package/dist/cli/firmwareCommands.js

@@ -1,83 +1,53 @@
 import { z } from "incur";
-import { resolve } from "node:path";
 import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";
 import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { firmwareInputSchemas } from "../domain/firmware/firmwareAnalysis.js";
+import { localPathStringSchema } from "../domain/localPath.js";
 import { withCommandCancellation } from "./commandCancellation.js";
+import { absoluteCallerPath } from "../filesystem/callerPath.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
 /** One-shot firmware CLI commands backed by the same workflows as MCP. */
 export const registerFirmwareCommands = (cli, logger, environment) => {
     const service = new FirmwareAnalysisService(createFirmwareAnalysisProvider(environment));
-    const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, async () => {
-        try {
-            const result = await service.execute(operation, input, { signal });
-            return result.ok ? result.value : projectAnalysisError(result.error);
-        }
-        finally {
-            await service.close();
-        }
-    }));
-    const path = z.string().describe("Local firmware path; never executed");
+    const extractInput = firmwareInputSchemas.extract_firmware.shape;
+    const range = extractInput.range.unwrap().shape;
+    const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, () => finishAnalysisCommand(() => service.execute(operation, input, { signal }), service, operation === "inspect_firmware_regions" ? "binwalk" : "unblob", operation, signal)));
+    const path = localPathStringSchema.describe("Local firmware path; never executed");
     cli.command(CLI_COMMANDS.inspectFirmwareRegions, {
         description: "Inspect firmware signature candidates without extracting them",
         args: z.object({ path }),
         run: ({ args }) => execute(CLI_COMMANDS.inspectFirmwareRegions, "inspect_firmware_regions", 
         // CLI paths are operator-relative; resolve before shared validation.
-        { path: resolve(args.path) }),
+        { path: absoluteCallerPath(args.path) }),
     });
     cli.command(CLI_COMMANDS.extractFirmware, {
         description: "Extract selected firmware bytes and return verified files and provenance",
         args: z.object({
             path,
-            outputDirectory: z
-                .string()
-                .describe("Absolute absent output directory; parent must exist"),
+            outputDirectory: localPathStringSchema.describe("Absent output directory; parent must exist"),
         }),
         options: z.object({
-            offset: z
-                .number()
-                .int()
-                .nonnegative()
+            offset: range.offset
                 .optional()
                 .describe("Selected byte offset; requires length"),
-            length: z
-                .number()
-                .int()
-                .positive()
+            length: range.length
                 .optional()
                 .describe("Selected byte length; requires offset"),
-            maxDepth: z
-                .number()
-                .int()
-                .optional()
-                .describe("Extraction depth, 1–10; default 3"),
-            maxOutputBytes: z
-                .number()
-                .int()
-                .optional()
-                .describe("Staging byte budget; default 256 MiB, maximum 512 MiB"),
-            maxOutputFiles: z
-                .number()
-                .int()
-                .optional()
-                .describe("Staging entry budget; default 10000"),
+            maxDepth: extractInput.max_depth,
+            maxOutputBytes: extractInput.max_output_bytes,
+            maxOutputFiles: extractInput.max_output_files,
         }),
         run: ({ args, options }) => execute(CLI_COMMANDS.extractFirmware, "extract_firmware", {
-            path: resolve(args.path),
-            output_directory: resolve(args.outputDirectory),
+            path: absoluteCallerPath(args.path),
+            output_directory: absoluteCallerPath(args.outputDirectory),
             ...(options.offset === undefined && options.length === undefined
                 ? {}
                 : { range: { offset: options.offset, length: options.length } }),
-            ...(options.maxDepth === undefined
-                ? {}
-                : { max_depth: options.maxDepth }),
-            ...(options.maxOutputBytes === undefined
-                ? {}
-                : { max_output_bytes: options.maxOutputBytes }),
-            ...(options.maxOutputFiles === undefined
-                ? {}
-                : { max_output_files: options.maxOutputFiles }),
+            max_depth: options.maxDepth,
+            max_output_bytes: options.maxOutputBytes,
+            max_output_files: options.maxOutputFiles,
         }),
     });
 };

package/dist/cli/flutterCommands.js

@@ -0,0 +1,53 @@
+import { z } from "incur";
+import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
+import { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
+/** Expose the same explicit Flutter requests through one-shot CLI commands. */
+export const registerFlutterCommands = (cli, logger, provider = createFlutterBuildAnalysisProvider()) => {
+    const specs = [
+        {
+            command: CLI_COMMANDS.identifyFlutterBuild,
+            description: "Identify a Flutter build's Dart snapshot hash and engine facts by pure APK parsing",
+            argumentSchema: z.object({
+                path: z.string().min(1).describe("Local APK file to inspect"),
+            }),
+            operation: "identify_flutter_build",
+            toInput: (arguments_) => arguments_,
+        },
+        {
+            command: CLI_COMMANDS.inspectDartAot,
+            description: "Inspect one ABI's Dart AOT snapshot: sections, headers, and the string pool",
+            argumentSchema: z.object({
+                path: z
+                    .string()
+                    .min(1)
+                    .describe("Local APK carrying a Flutter payload"),
+            }),
+            optionSchema: z.object({
+                abi: z
+                    .string()
+                    .min(2)
+                    .max(16)
+                    .optional()
+                    .describe("ABI under lib/ to inspect; defaults to the preferred one"),
+            }),
+            operation: "inspect_dart_aot",
+            toInput: (arguments_, options) => ({
+                path: arguments_.path,
+                ...(options.abi === undefined ? {} : { abi: options.abi }),
+            }),
+        },
+    ];
+    for (const spec of specs) {
+        cli.command(spec.command, {
+            description: spec.description,
+            ...(spec.optionSchema === undefined
+                ? { args: spec.argumentSchema }
+                : { args: spec.argumentSchema, options: spec.optionSchema }),
+            run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, spec.command, () => finishAnalysisCommand(() => new FlutterBuildAnalysisService(provider).execute(spec.operation, spec.toInput(args, options ?? {}), { signal }), { close: () => provider.close() }, "flutter", spec.operation, signal))),
+        });
+    }
+};

package/dist/cli/fridaCommands.js

@@ -0,0 +1,219 @@
+import { z } from "incur";
+import { FridaInstrumentationService, withRecoveredFridaCleanup, } from "../application/frida/FridaInstrumentationService.js";
+import { FridaInstrumentationManager } from "../frida/FridaInstrumentationManager.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err } from "../domain/result.js";
+import { FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION } from "../contracts/fridaToolContracts.js";
+import { isValidFridaRemoteAddress } from "../contracts/fridaRemoteAddress.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Register Frida discovery and one-shot instrumentation CLI operations. */
+export const registerFridaCommands = (cli, logger, provider = new FridaInstrumentationManager()) => {
+    const service = new FridaInstrumentationService(provider);
+    // CLI calls own a disposable provider; MCP retains its shared provider until
+    // server shutdown. Await cleanup here, including failed startup resources.
+    const withProviderCleanup = async (operation) => {
+        const result = await operation();
+        try {
+            await provider.closeAll();
+        }
+        catch (cause) {
+            const cleanup = new ProviderCleanupError("frida", ["Frida sessions or connections"], result.ok
+                ? { partial_observation: jsonValueSchema.parse(result.value) }
+                : {}, { cause, operation: "frida_cleanup" });
+            return err(result.ok
+                ? cleanup
+                : analysisErrorWithCleanupFailure(result.error, cleanup, "frida_cleanup"));
+        }
+        return result.ok ? result : err(withRecoveredFridaCleanup(result.error));
+    };
+    const remoteOptions = z.object({
+        remoteAddress: z
+            .string()
+            .min(1)
+            .max(2048)
+            .refine(isValidFridaRemoteAddress)
+            .optional()
+            .describe("Remote Frida host address, optionally with a port"),
+        token: z.string().min(1).optional().describe("Remote authentication token"),
+        certificate: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Remote TLS certificate"),
+        origin: z.string().min(1).optional().describe("Remote connection origin"),
+        keepaliveInterval: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe(FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION),
+    });
+    const remoteFrom = (options) => options.remoteAddress === undefined
+        ? undefined
+        : {
+            address: options.remoteAddress,
+            ...(options.token === undefined ? {} : { token: options.token }),
+            ...(options.certificate === undefined
+                ? {}
+                : { certificate: options.certificate }),
+            ...(options.origin === undefined ? {} : { origin: options.origin }),
+            ...(options.keepaliveInterval === undefined
+                ? {}
+                : { keepaliveInterval: options.keepaliveInterval }),
+        };
+    const remoteAddressRequired = (options) => options.remoteAddress !== undefined ||
+        (options.token === undefined &&
+            options.certificate === undefined &&
+            options.origin === undefined &&
+            options.keepaliveInterval === undefined);
+    cli.command(CLI_COMMANDS.listFridaDevices, {
+        description: "List local Frida devices and an optional remote endpoint",
+        args: z.object({}),
+        options: remoteOptions.refine(remoteAddressRequired, "Remote credentials and connection options require remoteAddress"),
+        run: ({ options }) => logCliCommand(logger, CLI_COMMANDS.listFridaDevices, async () => {
+            const result = await withProviderCleanup(() => service.listDevices(remoteFrom(options)));
+            return result.ok
+                ? {
+                    devices: result.value.devices,
+                    cleanup_error: result.value.cleanupError,
+                }
+                : projectAnalysisError(result.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.listFridaProcesses, {
+        description: "List processes visible through a Frida device",
+        args: z.object({}),
+        options: remoteOptions
+            .extend({
+            deviceId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Frida device identifier"),
+        })
+            .refine((options) => options.remoteAddress === undefined || options.deviceId === undefined, "Choose either deviceId or remoteAddress, not both")
+            .refine(remoteAddressRequired, "Remote credentials and connection options require remoteAddress"),
+        run: ({ options }) => logCliCommand(logger, CLI_COMMANDS.listFridaProcesses, async () => {
+            const remote = remoteFrom(options);
+            const result = await withProviderCleanup(() => service.listProcesses(remote === undefined
+                ? { deviceId: options.deviceId ?? "local" }
+                : { remote }));
+            return result.ok
+                ? {
+                    device_id: result.value.deviceId,
+                    processes: result.value.processes,
+                    cleanup_error: result.value.cleanupError,
+                }
+                : projectAnalysisError(result.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.instrumentWithFrida, {
+        description: "Run one Frida script against a selected process and detach",
+        args: z.object({
+            mode: z
+                .enum(["attach", "spawn"])
+                .describe("Attach to a PID or spawn a program"),
+            target: z
+                .string()
+                .min(1)
+                .describe("Process ID for attach or program path for spawn"),
+        }),
+        options: remoteOptions
+            .extend({
+            deviceId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Frida device identifier"),
+            script: z.string().optional().describe("Inline JavaScript to load"),
+            scriptFile: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Path to JavaScript source file"),
+            argument: z
+                .array(z.string())
+                .optional()
+                .describe("Arguments passed to a spawned target"),
+            durationMs: z
+                .number()
+                .int()
+                .min(0)
+                .max(60_000)
+                .default(1_000)
+                .describe("Instrumentation duration in milliseconds"),
+        })
+            .refine((options) => options.remoteAddress === undefined || options.deviceId === undefined, "Choose either deviceId or remoteAddress, not both")
+            .refine(remoteAddressRequired, "Remote credentials and connection options require remoteAddress"),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.instrumentWithFrida, async () => {
+            if (args.mode === "attach" && options.argument !== undefined)
+                return projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.instrumentWithFrida, undefined, [
+                    {
+                        path: ["argument"],
+                        reason: "invalid_value",
+                        message: "--argument is only valid in spawn mode; remove it when attaching to a process.",
+                    },
+                ]));
+            if ((options.script === undefined) ===
+                (options.scriptFile === undefined))
+                return projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.instrumentWithFrida, undefined, [
+                    {
+                        path: ["script"],
+                        reason: "invalid_value",
+                        message: "Provide exactly one of --script or --script-file.",
+                    },
+                ]));
+            const remote = remoteFrom(options);
+            const selected = remote === undefined
+                ? { deviceId: options.deviceId ?? "local" }
+                : { remote };
+            const targetInput = args.mode === "attach"
+                ? /^[1-9][0-9]*$/u.test(args.target) &&
+                    Number.isSafeInteger(Number(args.target)) &&
+                    Number(args.target) > 0
+                    ? {
+                        ...selected,
+                        mode: "attach",
+                        pid: Number(args.target),
+                    }
+                    : undefined
+                : {
+                    ...selected,
+                    mode: "spawn",
+                    program: args.target,
+                    ...(options.argument === undefined
+                        ? {}
+                        : { argv: options.argument }),
+                };
+            if (targetInput === undefined)
+                return projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.instrumentWithFrida, undefined, [
+                    {
+                        path: ["target"],
+                        reason: "invalid_value",
+                        message: "attach mode needs a positive integer process ID.",
+                    },
+                ]));
+            const result = await withProviderCleanup(() => service.instrument({
+                ...targetInput,
+                source: options.scriptFile === undefined
+                    ? { sourceKind: "inline", source: options.script ?? "" }
+                    : { sourceKind: "file", path: options.scriptFile },
+                durationMs: options.durationMs,
+            }, signal));
+            if (!result.ok)
+                return projectAnalysisError(result.error);
+            if (result.value.cleanupError !== null)
+                process.exitCode = 1;
+            return {
+                evidence: result.value.evidence,
+                cleanup_error: result.value.cleanupError,
+            };
+        })),
+    });
+};

package/dist/cli/goCommands.js

@@ -0,0 +1,20 @@
+import { z } from "incur";
+import { createGoBinaryService } from "../composition/go.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
+import { absoluteCallerPath } from "../filesystem/callerPath.js";
+/** Resolve caller paths and inspect static build metadata through the shared workflow. */
+export const registerGoCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectGoBinary, {
+        description: "Inspect embedded Go compiler, modules and build settings without target execution",
+        args: z.object({
+            path: z.string().describe("Local ELF, PE or thin Mach-O image"),
+        }),
+        run: ({ args }) => withCommandCancellation(async (signal) => {
+            const service = createGoBinaryService();
+            return await logCliCommand(logger, CLI_COMMANDS.inspectGoBinary, async () => finishAnalysisCommand(() => service.inspect({ path: absoluteCallerPath(args.path) }, { signal }), service, "go-build-info", "inspect_go_binary", signal));
+        }),
+    });
+};