rea-agents 6.0.0 → 6.2.0

package/dist/browser/history/CaptureFailures.js

@@ -1,10 +1,11 @@
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
 import { AnalysisError } from "../../domain/analysisErrorBase.js";
-import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
 import { WEB_NETWORK_CAPTURE_LIMITS, } from "../../domain/webNetworkCapture.js";
 import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+import { HAR_CAPTURE_HEAP_LIMITS } from "./CaptureRelease.js";
 const OPERATION = "inspect_web_network_capture";
 /** Preserve the origin and typed cause of a historical capture failure. */
 export const historicalCaptureFailure = (input, cause, phase, options) => {
@@ -30,6 +31,13 @@ export const historicalCaptureFailure = (input, cause, phase, options) => {
             return new AnalysisTimeoutError(OPERATION, WEB_NETWORK_CAPTURE_LIMITS.timeoutMs);
         if (cause.reason === "output-limit")
             return new AnalysisOutputError(OPERATION, cause.message);
+        if (phase === "decoder" &&
+            input.format === "har" &&
+            cause.reason === "process" &&
+            (cause.snapshot?.signal === "SIGABRT" ||
+                (cause.snapshot?.signal === null && cause.snapshot.exitCode === 134)) &&
+            /FATAL ERROR:[^\r\n]*heap out of memory/u.test(cause.snapshot.stderr.text))
+            return captureMemoryFailure(input, "The HAR decoder exhausted its fixed V8 heap", cause);
     }
     if (options?.signal?.aborted)
         return new AnalysisCancelledError(OPERATION);
@@ -99,3 +107,35 @@ export const historicalCaptureFailure = (input, cause, phase, options) => {
         },
     });
 };
+/** Preserve a decoder's observed memory failure and its actual workload limits. */
+export const captureMemoryFailure = (input, reason, cause) => new AnalysisResourceConstraintError(OPERATION, "memory", `${reason}: ${input.capture_path}. No complete capture result is available.`, {
+    boundary: "historical-capture-decoder",
+    capture_path: input.capture_path,
+    format: input.format,
+    maximum_input_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
+    maximum_reply_bytes: WEB_NETWORK_CAPTURE_LIMITS.outputBytes,
+    ...(input.format === "har"
+        ? {
+            old_generation_heap_mib: HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB,
+            semi_space_heap_mib: HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB,
+        }
+        : {}),
+    ...(cause instanceof OwnedCommandFailure
+        ? {
+            observed_exit_code: cause.snapshot?.exitCode ?? null,
+            observed_signal: cause.snapshot?.signal ?? null,
+        }
+        : {}),
+}, {
+    cause,
+    remediationAction: `Use a smaller capture exported by its producer, or another decoder with sufficient capacity for the original capture. Preserve the original for provenance; a subset does not establish complete-capture coverage.${input.format === "har" ? ` REA's HAR old-generation heap is fixed at ${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB} MiB; inherited NODE_OPTIONS cannot raise it.` : ""}`,
+    ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
+        ? {
+            capturedOutput: {
+                stdout: cause.snapshot.stdout.text,
+                stderr: cause.snapshot.stderr.text,
+                truncated: cause.snapshot.diagnosticTruncated ?? false,
+            },
+        }
+        : {}),
+});

package/dist/browser/history/CaptureRelease.js

@@ -4,6 +4,11 @@ export const HAR_CAPTURE_PROVIDER_IDENTITY = {
     name: "REA HAR capture adapter",
     version: "har-schema@2.0.0;jsonc-parser@3.3.1;lossless-json@4.3.1",
 };
+/** Fixed V8 heap settings used by the owned HAR decoder process. */
+export const HAR_CAPTURE_HEAP_LIMITS = {
+    oldGenerationMiB: 192,
+    semiSpaceMiB: 8,
+};
 /** Native executable profile verified with unchanged mitmproxy raw-state decoding. */
 export const MITMPROXY_CAPTURE_PROVIDER_IDENTITY = {
     id: "mitmproxy-native-tnetstring",

package/dist/browser/history/HarCaptureAdapter.js

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
+import { HAR_CAPTURE_PROVIDER_IDENTITY, HAR_CAPTURE_HEAP_LIMITS, } from "./CaptureRelease.js";
 /** HAR's parser/schema packages run in one bounded Node heap, without network or target execution. */
 export class HarCaptureAdapter {
     format = "har";
@@ -8,8 +8,8 @@ export class HarCaptureAdapter {
         return {
             command: process.execPath,
             arguments: [
-                "--max-old-space-size=192",
-                "--max-semi-space-size=8",
+                `--max-old-space-size=${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB}`,
+                `--max-semi-space-size=${HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB}`,
                 "--v8-pool-size=1",
                 "--single-threaded",
                 fileURLToPath(new URL("./HarCaptureProcess.js", import.meta.url)),

package/dist/browser/history/HarJson.js

@@ -43,8 +43,9 @@ export const parseHarJson = (text) => {
             });
         },
         onObjectProperty: (key) => {
-            if (key === "__proto__")
-                throw new CaptureFormatError("unsupported", "HAR object contains a __proto__ member that the current JSON schema boundary cannot preserve.");
+            // Prototype-named members are kept as ordinary own properties: the
+            // members map keys them without prototype setters, and
+            // Object.fromEntries materializes them as own data properties.
             const frame = frames.at(-1);
             if (frame?.kind !== "object")
                 throw new TypeError("JSON visitor emitted a property outside an object.");

package/dist/browser/history/HistoricalCaptureDecoder.js

@@ -1,4 +1,4 @@
-import { historicalCaptureFailure } from "./CaptureFailures.js";
+import { historicalCaptureFailure, captureMemoryFailure, } from "./CaptureFailures.js";
 import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
@@ -117,7 +117,9 @@ export class HistoricalCaptureDecoder {
                             },
                         },
                     ]);
-                if (reply.reason === "decoder" || reply.reason === "resource-limit")
+                if (reply.reason === "resource-limit")
+                    throw captureMemoryFailure(input, reply.message);
+                if (reply.reason === "decoder")
                     throw new ProviderAdapterError(input.format, OPERATION, {
                         diagnostics: {
                             phase: "decoder",

package/dist/browser/history/MitmproxyCaptureAdapter.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
 import { MITMPROXY_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
 const OPERATION = "inspect_web_network_capture";
+const MITMDUMP_REQUIREMENT = "Native capture decoding requires Linux and an absolute REA_MITMDUMP_COMMAND path to caller-supplied mitmdump 12.2.3; HAR needs no external engine.";
 /** Native mitmproxy decoding is offline and uses only an explicitly configured Linux tool. */
 export class MitmproxyCaptureAdapter {
     environment;
@@ -18,12 +19,13 @@ export class MitmproxyCaptureAdapter {
         if (process.platform !== "linux" ||
             command === undefined ||
             !isAbsolute(command))
-            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, "Native capture decoding requires Linux and an absolute REA_MITMDUMP_COMMAND path to caller-supplied mitmdump 12.2.3; HAR needs no external engine.");
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, MITMDUMP_REQUIREMENT, { userMessage: MITMDUMP_REQUIREMENT });
         try {
             await access(command, constants.R_OK | constants.X_OK);
         }
         catch (cause) {
-            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, `Configured mitmdump executable is unavailable: ${command}.`, { cause });
+            const reason = `Configured mitmdump executable is unavailable: ${command}.`;
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, reason, { cause, userMessage: reason });
         }
         return {
             command,

package/dist/catalogIdentity.js

@@ -4,7 +4,6 @@ import { z } from "zod";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
-export { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
 const sortedToolContracts = [...TOOL_CONTRACTS].sort((left, right) => left.name.localeCompare(right.name));
 const createToolCatalog = () => sortedToolContracts.map((contract) => ({
     name: contract.name,

package/dist/cli/analysisSelector.js

@@ -0,0 +1,23 @@
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+/** Preserve a CLI selector supplied positionally or through its named option. */
+export const resolveCliAnalysisSelector = (positional, named, option, operation) => {
+    if (positional !== undefined && named !== undefined && positional !== named)
+        throw new AnalysisInputError(operation, undefined, [
+            {
+                path: [option],
+                reason: "invalid_value",
+                message: `The positional selector and --${option} select different objects; supply one selector.`,
+            },
+        ]);
+    const selected = named ?? positional;
+    if (selected === undefined)
+        throw new AnalysisInputError(operation, undefined, [
+            {
+                path: [option],
+                reason: "missing_argument",
+                message: `Supply a positional selector or --${option}=<value>. Use the named option for values beginning with a dash.`,
+                expected: "string",
+            },
+        ]);
+    return selected;
+};

package/dist/cli/analysisViewCommands.js

@@ -0,0 +1,36 @@
+import { z } from "incur";
+import { inspectAnalysisViewValidated } from "../application/analysisView/AnalysisViewService.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { parseCliJsonInput } from "../cliJsonInput.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
+/** Project selected views of completed analysis Evidence through the CLI. */
+export const registerAnalysisViewCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectAnalysisView, {
+        description: "Project a selected view of completed layout or JavaScript application Evidence JSON",
+        args: z.object({
+            inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.inspectAnalysisView, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.inspectAnalysisView);
+            if (!input.ok)
+                return input.error;
+            const parsed = inspectAnalysisViewInputSchema.safeParse(input.value);
+            if (!parsed.success)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(analysisInputErrorFromIssues(CLI_COMMANDS.inspectAnalysisView, parsed.error.issues, input.value)),
+                };
+            const result = inspectAnalysisViewValidated(parsed.data);
+            return result.ok
+                ? jsonValueSchema.parse(result.value)
+                : {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(result.error),
+                };
+        }),
+    });
+};

package/dist/cli/applicationCommands.js

@@ -9,7 +9,6 @@ import { buildReconstructionObligationLedgerEvidenceValidated } from "../applica
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { androidApplicationProjectionInputSchema } from "../domain/android/androidApplication.js";
@@ -20,7 +19,7 @@ import { traceJavaScriptSemanticsInputSchema } from "../domain/javascript/javasc
 import { compareApplicationVersionsInputSchema } from "../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
 import { compareSourceToBundleInputSchema } from "../domain/javascript/sourceToBundleComparisonSchemas.js";
 import { compareJavaScriptExportShapesInputSchema } from "../domain/javascript/javascriptExportShapeComparisonSchemas.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { reconstructionObligationLedgerInputSchema } from "../domain/reconstructionObligationLedgerSchemas.js";
 /** Register CLI equivalents of provider-neutral application graph workflows. */
 export const registerApplicationCommands = (cli, logger) => {
@@ -133,7 +132,7 @@ const registerJsonCommand = ({ cli, logger, name, description, inputSchema, work
             if (!parsed.success)
                 return {
                     error: "Application workflow failed",
-                    ...projectAnalysisError(new AnalysisInputError(name, undefined, projectInputIssues(parsed.error.issues, input.value))),
+                    ...projectAnalysisError(analysisInputErrorFromIssues(name, parsed.error.issues, input.value)),
                 };
             const result = workflow(parsed.data);
             return result.ok

package/dist/cli/artifactCommands.js

@@ -1,14 +1,13 @@
 import { z } from "incur";
-import { runProviderAnalysis } from "../composition/directAnalysis.js";
 import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
-export const registerArtifactCommands = (cli, logger) => {
-    registerInspectionCommand(cli, logger);
-    registerExtractionCommand(cli, logger);
-    registerInterfaceBuilderCommand(cli, logger);
-    registerAssetCatalogCommand(cli, logger);
-    registerDylibResolutionCommand(cli, logger);
+export const registerArtifactCommands = (cli, logger, runProviderAnalysis) => {
+    registerInspectionCommand(cli, logger, runProviderAnalysis);
+    registerExtractionCommand(cli, logger, runProviderAnalysis);
+    registerInterfaceBuilderCommand(cli, logger, runProviderAnalysis);
+    registerAssetCatalogCommand(cli, logger, runProviderAnalysis);
+    registerDylibResolutionCommand(cli, logger, runProviderAnalysis);
     cli.command(CLI_COMMANDS.inspectKeyedArchive, {
         description: "Inspect a Foundation keyed archive as an object-reference graph",
         args: z.object({
@@ -42,7 +41,7 @@ export const registerArtifactCommands = (cli, logger) => {
         }, logger)),
     });
 };
-const registerDylibResolutionCommand = (cli, logger) => {
+const registerDylibResolutionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.traceDylibResolution, {
         description: "Trace dyld load-path resolution for a Mach-O or every executable in an app bundle",
         args: z.object({
@@ -66,7 +65,7 @@ const registerDylibResolutionCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerAssetCatalogCommand = (cli, logger) => {
+const registerAssetCatalogCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectAssetCatalog, {
         description: "Inspect compiled Apple asset catalog metadata",
         args: z.object({ path: z.string().describe("Apple .app bundle path") }),
@@ -89,7 +88,7 @@ const registerAssetCatalogCommand = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectAssetCatalog, () => runProviderAnalysis(args.path, "inspect_asset_catalog", { offset: options.offset, limit: options.limit }, logger)),
     });
 };
-const registerInterfaceBuilderCommand = (cli, logger) => {
+const registerInterfaceBuilderCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.decodeInterfaceBuilder, {
         description: "Decode compiled storyboard and nib archives from an app bundle",
         args: z.object({
@@ -130,7 +129,7 @@ const registerInterfaceBuilderCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerExtractionCommand = (cli, logger) => {
+const registerExtractionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.extractArtifact, {
         description: "Extract all regular artifact contents safely",
         args: z.object({
@@ -142,7 +141,7 @@ const registerExtractionCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerInspectionCommand = (cli, logger) => {
+const registerInspectionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectArtifact, {
         description: "Inspect one artifact and return all available observations and next probes",
         args: z.object({

package/dist/cli/coreAnalysisCommands.js

@@ -1,7 +1,7 @@
 import { registerCoreBinaryCommands } from "./coreBinaryCommands.js";
 import { registerCoreNativeCommands } from "./coreNativeCommands.js";
 /** Register core binary and native deep-analysis CLI commands. */
-export const registerCoreAnalysisCommands = (cli, logger, resultOutput) => {
-    registerCoreBinaryCommands(cli, logger, resultOutput);
-    registerCoreNativeCommands(cli, logger);
+export const registerCoreAnalysisCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
+    registerCoreBinaryCommands(cli, logger, runDirectAnalysis, resultOutput);
+    registerCoreNativeCommands(cli, logger, runDirectAnalysis);
 };

package/dist/cli/coreBinaryCommands.js

@@ -1,21 +1,23 @@
 import { z } from "incur";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
-import { runDirectAnalysis } from "../composition/directAnalysis.js";
+import { resolveCliAnalysisSelector } from "./analysisSelector.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register provider-neutral binary overview and procedure CLI commands. */
-export const registerCoreBinaryCommands = (cli, logger, resultOutput) => {
-    registerOverviewCommands(cli, logger, resultOutput);
-    registerFunctionCommand(cli, logger);
-    registerInstructionsCommand(cli, logger);
-    registerSearchCommand(cli, logger);
-    registerXrefsCommand(cli, logger);
-    registerTraceCommand(cli, logger);
+export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
+    registerOverviewCommands(cli, logger, runDirectAnalysis, resultOutput);
+    registerDecompileCommand(cli, logger, runDirectAnalysis);
+    registerFunctionCommand(cli, logger, runDirectAnalysis);
+    registerInstructionsCommand(cli, logger, runDirectAnalysis);
+    registerSearchCommand(cli, logger, runDirectAnalysis);
+    registerXrefsCommand(cli, logger, runDirectAnalysis);
+    registerTraceCommand(cli, logger, runDirectAnalysis);
 };
-const registerOverviewCommands = (cli, logger, resultOutput) => {
+const registerOverviewCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
     const overviewOptions = z.object({
         snapshot: z
             .string()
@@ -31,9 +33,17 @@ const registerOverviewCommands = (cli, logger, resultOutput) => {
             path: z.string().describe("App, program, or analysis database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options, format }) => logCliCommand(logger, "analyze", () => runRoutedOverview(args.path, options, logger, resultOutput === undefined
-            ? undefined
-            : { output: resultOutput, command: CLI_COMMANDS.analyze, format })),
+        run: async ({ args, options, format }) => {
+            const output = resultOutput === undefined
+                ? undefined
+                : { output: resultOutput, command: CLI_COMMANDS.analyze, format };
+            // 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.
+            if (await routesToJavaScriptAnalysis(args.path, options))
+                return withCommandCancellation((signal) => logCliCommand(logger, "analyze", () => runCliJavaScriptApplicationAnalysis({ input_path: resolve(args.path) }, output, signal)));
+            return logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"])));
+        },
     });
     cli.command(CLI_COMMANDS.inspect, {
         description: "Inspect an app overview with evidence",
@@ -43,13 +53,24 @@ const registerOverviewCommands = (cli, logger, resultOutput) => {
         options: overviewOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
+};
+const registerDecompileCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.decompile, {
         description: "Read one part of an app as code",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -58,17 +79,16 @@ const registerOverviewCommands = (cli, logger, resultOutput) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", {
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "procedure_pseudo_code"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const runRoutedOverview = async (path, options, logger, output) => {
-    if (options.provider === undefined &&
-        options.snapshot === undefined &&
-        options["target-format"] === undefined &&
-        (await isJavaScriptApplicationPath(path)))
-        return runCliJavaScriptApplicationAnalysis({ input_path: resolve(path) }, output);
-    return runDirectAnalysis(path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]));
-};
+/** Select static JavaScript analysis only when no binary-analysis option applies. */
+const routesToJavaScriptAnalysis = async (path, options) => options.provider === undefined &&
+    options.snapshot === undefined &&
+    options["target-format"] === undefined &&
+    (await isJavaScriptApplicationPath(path));
 const isJavaScriptApplicationPath = async (path) => {
     const lower = path.toLowerCase();
     if (lower.endsWith(".asar"))
@@ -85,14 +105,19 @@ const isJavaScriptApplicationPath = async (path) => {
         return false;
     }
 };
-const registerXrefsCommand = (cli, logger) => {
+const registerXrefsCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.xrefs, {
         description: "List bounded references to an analyzed address",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Hexadecimal address"),
+            address: z.string().min(1).optional().describe("Address or symbol name"),
         }),
         options: z.object({
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Address or symbol name; use --address=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -101,17 +126,24 @@ const registerXrefsCommand = (cli, logger) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", {
+            address: resolveCliAnalysisSelector(args.address, options.address, "address", "xrefs"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerTraceCommand = (cli, logger) => {
+const registerTraceCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.trace, {
         description: "Trace a literal feature through analyzed references",
         args: z.object({
             path: z.string().describe("App or program path"),
-            query: z.string().min(1).describe("Literal feature query"),
+            query: z.string().min(1).optional().describe("Literal feature query"),
         }),
         options: z.object({
+            query: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Complete literal feature query; use --query=<value> for leading dashes"),
             caseSensitive: z
                 .boolean()
                 .default(false)
@@ -128,19 +160,28 @@ const registerTraceCommand = (cli, logger) => {
             caseSensitive: "case-sensitive",
         },
         run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
-            query: args.query,
+            query: resolveCliAnalysisSelector(args.query, options.query, "query", "trace_feature"),
             case_sensitive: options.caseSensitive,
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerFunctionCommand = (cli, logger) => {
+const registerFunctionCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.function, {
         description: "Analyze one complete function with evidence",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure name or address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -149,17 +190,28 @@ const registerFunctionCommand = (cli, logger) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", {
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "analyze_function"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerInstructionsCommand = (cli, logger) => {
+const registerInstructionsCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.instructions, {
         description: "Read every raw instruction without decompiling",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure name or address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -169,18 +221,27 @@ const registerInstructionsCommand = (cli, logger) => {
             provider: providerSelectionOption,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.instructions, () => runDirectAnalysis(args.path, "read_function_instructions", {
-            procedure: args.address,
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "read_function_instructions"),
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerSearchCommand = (cli, logger) => {
+const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.search, {
         description: "Search every analyzed string or procedure name",
         args: z.object({
             path: z.string().describe("App or program path"),
-            pattern: z.string().min(1).describe("Literal text or regex pattern"),
+            pattern: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Literal text or regex pattern"),
         }),
         options: z.object({
+            pattern: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Complete literal text or regex pattern; use --pattern=<value> for leading dashes"),
             kind: z
                 .enum(["strings", "procedures"])
                 .default("strings")
@@ -203,7 +264,9 @@ const registerSearchCommand = (cli, logger) => {
         }),
         alias: { caseSensitive: "case-sensitive" },
         run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
-            pattern: args.pattern,
+            pattern: resolveCliAnalysisSelector(args.pattern, options.pattern, "pattern", options.kind === "strings"
+                ? "search_strings"
+                : "search_procedures"),
             mode: options.mode,
             case_sensitive: options.caseSensitive,
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),

package/dist/cli/coreNativeCommands.js

@@ -1,11 +1,10 @@
 import { z } from "incur";
-import { runDirectAnalysis } from "../composition/directAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 /** Register native load-image, memory, and annotation CLI commands. */
-export const registerCoreNativeCommands = (cli, logger) => {
-    registerAnnotationCommand(cli, logger);
+export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
+    registerAnnotationCommand(cli, logger, runDirectAnalysis);
     cli.command(CLI_COMMANDS.inspectNativeLoadImage, {
         description: "Verify loaded native bytes, source mappings, relocations and entry",
         args: z.object({ path: z.string().describe("Local executable path") }),
@@ -160,11 +159,11 @@ export const registerCoreNativeCommands = (cli, logger) => {
             run: ({ args, options }) => logCliCommand(logger, command, () => runDirectAnalysis(args.path, operation, { address: args.address }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
         });
     }
-    registerNativeApiCommand(cli, logger);
-    registerNativeUiActionCommand(cli, logger);
-    registerNativeDispatchMetadataCommand(cli, logger);
+    registerNativeApiCommand(cli, logger, runDirectAnalysis);
+    registerNativeUiActionCommand(cli, logger, runDirectAnalysis);
+    registerNativeDispatchMetadataCommand(cli, logger, runDirectAnalysis);
 };
-const registerNativeDispatchMetadataCommand = (cli, logger) => {
+const registerNativeDispatchMetadataCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.inspectNativeDispatchMetadata, {
         description: "Inspect typed Objective-C and Swift dispatch metadata",
         args: z.object({
@@ -190,7 +189,7 @@ const registerNativeDispatchMetadataCommand = (cli, logger) => {
         run: async ({ args, options }) => logCliCommand(logger, "inspect-native-dispatch-metadata", () => runDirectAnalysis(args.path, "inspect_native_dispatch_metadata", { max_records: options.maxRecords }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerNativeUiActionCommand = (cli, logger) => {
+const registerNativeUiActionCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.traceNativeUiAction, {
         description: "Trace a compiled UI action selector to its native handler and direct callees",
         args: z.object({
@@ -238,7 +237,7 @@ const registerNativeUiActionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
     });
 };
-const registerNativeApiCommand = (cli, logger) => {
+const registerNativeApiCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.inspectNativeApi, {
         description: "Reconstruct one native function API boundary with evidence",
         args: z.object({
@@ -257,7 +256,7 @@ const registerNativeApiCommand = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerAnnotationCommand = (cli, logger) => {
+const registerAnnotationCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.annotateNativeFunction, {
         description: "Edit function annotations and return refreshed analysis",
         args: z.object({