rea-agents 0.5.0 → 1.0.0

package/README.md

@@ -120,6 +120,17 @@ rea doctor
 rea analyze /Applications/Notes.app
 ```
 
+Update that global installation in place:
+
+```bash
+rea upgrade
+```
+
+REA checks npm for the latest release and verifies that the running package is
+the global installation it will replace. Source, local, and `npx` copies report
+the manual `npm install --global rea-agents@latest` command instead of updating
+an unrelated global package.
+
 Choose either the no-install commands or the global installation. You do not need both.
 
 ### Requirements
@@ -343,6 +354,7 @@ Or install the `rea` command globally:
 ```bash
 npm install --global rea-agents
 rea --help
+rea upgrade
 rea mcp
 ```
 

package/dist/application/EnhancedTools.js

@@ -1,6 +1,6 @@
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisInputError, AnalysisCancelledError, AnalysisOutputError, } from "../domain/errors.js";
-import { parseDocuments, parseFunctionDossier, parseAddressedPage, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
+import { AnalysisInputError, AnalysisCancelledError, AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js";
+import { addressDistance, parseDocuments, parseFunctionDossier, parseAddressedPage, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, discoverSwiftClasses, } from "../domain/symbolAnalysis.js";
 /**
@@ -89,20 +89,29 @@ export class EnhancedTools {
         return names.ok ? ok(discoverObjcProtocols(names.value)) : names;
     }
     async #batchDecompile(addresses, signal) {
-        if (addresses.length === 0)
-            return ok({ error: "No addresses provided" });
-        const entries = await Promise.all(addresses.map(async (address) => {
+        const items = await Promise.all(addresses.map(async (address) => {
             const result = await this.#call("procedure_pseudo_code", { procedure: address }, signal);
-            return [
-                address,
-                result.ok
-                    ? result.value === null || result.value === ""
-                        ? "No output"
-                        : result.value
-                    : `Error: ${result.error.message}`,
-            ];
+            if (!result.ok)
+                return {
+                    address,
+                    status: "error",
+                    error: projectAnalysisError(result.error),
+                };
+            if (typeof result.value !== "string" || result.value.length === 0)
+                return {
+                    address,
+                    status: "error",
+                    error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
+                };
+            return { address, status: "ok", pseudocode: result.value };
         }));
-        return ok(Object.fromEntries(entries));
+        const succeeded = items.filter(({ status }) => status === "ok").length;
+        return ok({
+            items,
+            total: items.length,
+            succeeded,
+            failed: items.length - succeeded,
+        });
     }
     async #callGraph(input, signal) {
         const relation = input.direction === "forward" ? "callees" : "callers";
@@ -124,7 +133,8 @@ export class EnhancedTools {
             if (!result.ok) {
                 graph[level].push({
                     address: current.address,
-                    error: result.error.message,
+                    status: "error",
+                    error: projectAnalysisError(result.error),
                 });
                 continue;
             }
@@ -132,12 +142,14 @@ export class EnhancedTools {
             if (!related.ok) {
                 graph[level].push({
                     address: current.address,
-                    error: related.error.message,
+                    status: "error",
+                    error: projectAnalysisError(related.error),
                 });
                 continue;
             }
             graph[level].push({
                 address: current.address,
+                status: "ok",
                 calls: [...related.value],
             });
             if (current.depth + 1 < input.depth) {
@@ -158,16 +170,24 @@ export class EnhancedTools {
             : procedures;
     }
     async #findXrefs(name, signal) {
-        const resolved = await this.#call("address_name", { address: name }, signal);
-        if (!resolved.ok)
-            return resolved;
-        const address = resolveAddress(resolved.value);
-        if (address === undefined)
-            return ok({ error: `Could not resolve name: ${name}` });
-        const xrefs = await this.#call("xrefs", { address }, signal);
+        const names = await this.#allAddressed("list_names", signal);
+        if (!names.ok)
+            return names;
+        const resolved = names.value.find((entry) => entry.name === name);
+        if (resolved === undefined)
+            return ok({ status: "unresolved", name, reason: "name_not_found" });
+        const xrefs = await this.#call("xrefs", { address: resolved.address }, signal);
         if (!xrefs.ok)
             return xrefs;
-        return ok(Array.isArray(xrefs.value) ? { xrefs: xrefs.value } : xrefs.value);
+        if (!Array.isArray(xrefs.value) ||
+            xrefs.value.some((xref) => typeof xref !== "string"))
+            return err(new AnalysisOutputError("xrefs", "provider returned an invalid address list"));
+        return ok({
+            status: "resolved",
+            name,
+            address: resolved.address,
+            xrefs: xrefs.value,
+        });
     }
     async #binaryOverview(input, signal) {
         const [segmentsResult, documentsResult, procedures, stringsResult] = await Promise.all([
@@ -346,15 +366,3 @@ export class EnhancedTools {
 const invalidInput = (name, cause) => Promise.resolve(err(new AnalysisInputError(name, {
     cause,
 })));
-const resolveAddress = (value) => {
-    if (typeof value === "string" && value.length > 0)
-        return value;
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    const candidate = value.address ?? value.name;
-    return typeof candidate === "string" && candidate.length > 0
-        ? candidate
-        : undefined;
-};
-const addressDistance = (start, end) => Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));

package/dist/application/Upgrade.js

@@ -0,0 +1,106 @@
+import { execFile, spawn } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+const execFileAsync = promisify(execFile);
+const registryResponseSchema = z.object({ version: z.string().min(1) });
+const UPGRADE_COMMAND = "npm install --global rea-agents@latest";
+/** Check the npm registry and update the same global REA installation. */
+export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), output = "human") => {
+    const latestVersion = await host.latestVersion();
+    if (latestVersion === currentVersion)
+        return {
+            status: "current",
+            currentVersion,
+            latestVersion,
+            installMethod: "npm",
+        };
+    const installation = await host.installation();
+    if (installation === undefined)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: latestVersion ?? null,
+            reason: "unknown-install-method",
+            remediation: `Update manually with: ${UPGRADE_COMMAND}`,
+        };
+    if (!(await host.installLatest(installation, output)))
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: latestVersion ?? null,
+            reason: "install",
+            remediation: `${UPGRADE_COMMAND} failed.`,
+        };
+    return {
+        status: "upgraded",
+        previousVersion: currentVersion,
+        latestVersion: latestVersion ?? null,
+        versionCheck: latestVersion === undefined ? "unavailable" : "available",
+        installMethod: "npm",
+        command: UPGRADE_COMMAND,
+    };
+};
+/** Create the npm registry and subprocess effects for a production upgrade. */
+export const systemUpgradeHost = () => ({
+    latestVersion: async () => {
+        try {
+            const response = await fetch(`https://registry.npmjs.org/${PRODUCT_IDENTITY.packageName}/latest`, { signal: AbortSignal.timeout(10_000) });
+            if (!response.ok)
+                return undefined;
+            const parsed = registryResponseSchema.safeParse(await response.json());
+            return parsed.success ? parsed.data.version : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    installation: () => detectNpmInstallation(fileURLToPath(new URL("../..", import.meta.url)), systemNpmInstallationHost),
+    installLatest: ({ prefix }, output) => runCommand("npm", [
+        "install",
+        "--global",
+        "--prefix",
+        prefix,
+        `${PRODUCT_IDENTITY.packageName}@latest`,
+    ], output),
+});
+const systemNpmInstallationHost = {
+    canonicalPath: realpath,
+    globalRoot: async () => (await execFileAsync("npm", ["root", "--global"])).stdout.trim(),
+    globalPrefix: async () => (await execFileAsync("npm", ["prefix", "--global"])).stdout.trim(),
+};
+/** Identify the npm prefix only when it owns the running package. */
+export const detectNpmInstallation = async (packageRoot, host) => {
+    try {
+        const canonicalPackageRoot = await host.canonicalPath(packageRoot);
+        const npmRoot = await host.globalRoot();
+        const globalPackageRoot = await host.canonicalPath(resolve(npmRoot, PRODUCT_IDENTITY.packageName));
+        if (canonicalPackageRoot === globalPackageRoot) {
+            const prefix = await host.globalPrefix();
+            return prefix.length === 0 ? undefined : { prefix };
+        }
+        return inferUnixGlobalPrefix(canonicalPackageRoot);
+    }
+    catch {
+        return inferUnixGlobalPrefix(packageRoot);
+    }
+};
+const inferUnixGlobalPrefix = (packageRoot) => {
+    const nodeModules = dirname(packageRoot);
+    const library = dirname(nodeModules);
+    if (basename(packageRoot) !== PRODUCT_IDENTITY.packageName ||
+        basename(nodeModules) !== "node_modules" ||
+        basename(library) !== "lib")
+        return undefined;
+    return { prefix: dirname(library) };
+};
+const runCommand = (command, arguments_, output) => new Promise((resolveResult) => {
+    const child = spawn(command, [...arguments_], {
+        stdio: output === "human" ? "inherit" : ["inherit", process.stderr, "inherit"],
+    });
+    child.once("error", () => resolveResult(false));
+    child.once("exit", (code) => resolveResult(code === 0));
+});

package/dist/cli.js

@@ -4,6 +4,7 @@ import { runDoctor } from "./application/Doctor.js";
 import { runDirectAnalysis, runProviderAnalysis, runSessionStatus, } from "./application/DirectAnalysis.js";
 import { runSetup } from "./application/Setup.js";
 import { runUninstall } from "./application/Uninstall.js";
+import { runUpgrade, systemUpgradeHost } from "./application/Upgrade.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
 import { createLogger, parseLogLevel } from "./logger.js";
 import { logCliCommand } from "./cliLogging.js";
@@ -82,6 +83,10 @@ const registerCoreCommands = (cli, logger) => {
         alias: { purgeData: "purge-data" },
         run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData)),
     });
+    cli.command("upgrade", {
+        description: "Upgrade a global npm installation to the latest REA release",
+        run: ({ formatExplicit }) => logCliCommand(logger, "upgrade", () => runUpgrade(process.env.REA_PACKAGE_VERSION ?? "0.0.0-development", systemUpgradeHost(), formatExplicit ? "structured" : "human")),
+    });
     cli.command("analyze", {
         description: "Get an overview of an app",
         args: z.object({

package/dist/contracts/toolContracts.js

@@ -146,10 +146,10 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("swift_classes", "Discover legacy-mangled Swift class procedures after exhaustively paging analyzed procedures. Returns at most 100 entries and scans at most 5,000 symbols; use analyze_swift_types for other Swift kinds.", enhancedInputSchemas.swift_classes),
     enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels after exhaustively paging names, optionally filtering by literal substring. Returns at most 100 classes; inspect matching metadata and references next.", enhancedInputSchemas.get_objc_classes),
     enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels after exhaustively paging names. Returns at most 100 entries; use xrefs or analyze_function to connect a protocol to implementations.", enhancedInputSchemas.get_objc_protocols),
-    enhanced("batch_decompile", "Decompile up to 20 explicit procedure symbols or addresses concurrently. Per-item strings may contain errors or no-output markers, so validate each result; use analyze_function for a richer single-function dossier.", enhancedInputSchemas.batch_decompile),
-    enhanced("get_call_graph", "Traverse Hopper's caller or callee relationships from one symbol or address for at most five levels. Nodes preserve per-procedure errors; indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("batch_decompile", "Decompile up to 20 explicit procedure symbols or addresses concurrently. Returns ordered per-item ok/error variants and aggregate counts; use analyze_function for a richer single-function dossier.", enhancedInputSchemas.batch_decompile),
+    enhanced("get_call_graph", "Traverse Hopper's caller or callee relationships from one symbol or address for at most five levels. Every node has an ok/error status and failures use safe typed projections; indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
     enhanced("analyze_swift_types", "Categorize exhaustively paged procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Scans at most 5,000 names and returns at most 50 entries per category.", enhancedInputSchemas.analyze_swift_types),
-    enhanced("find_xrefs_to_name", "Resolve a name through Hopper and return analyzed references to its address. Use when starting from a selector or symbol; resolution failure is returned explicitly and xrefs remain untyped.", enhancedInputSchemas.find_xrefs_to_name),
+    enhanced("find_xrefs_to_name", "Resolve an exact name through Hopper's exhaustively paged name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; xrefs remain untyped.", enhancedInputSchemas.find_xrefs_to_name),
     enhanced("binary_overview", "Use immediately after opening a target to summarize document, exhaustive procedure/string counts, and a bounded segment sample. detail controls segment fields and limit controls only the returned segment sample.", enhancedInputSchemas.binary_overview),
     enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, pseudocode, optional assembly, comments, calls, incoming references, and blocks; unsupported outgoing references and CFG edges carry explicit unavailable metadata.", enhancedInputSchemas.analyze_function),
     enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),

package/dist/contracts/toolOutputSchemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ANALYSIS_ERROR_TAGS } from "../domain/errors.js";
 import { evidenceSchema } from "../domain/evidence.js";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
@@ -149,9 +150,24 @@ const symbolDiscoveryOutput = (property) => resultOf(z.object({
     count: z.number().int().min(0),
     [property]: z.array(addressedEntry),
 }));
-const graphNode = z.union([
-    z.object({ address: z.string(), calls: z.array(z.string()) }),
-    z.object({ address: z.string(), error: z.string() }),
+const analysisErrorProjectionSchema = z
+    .object({
+    tag: z.enum(ANALYSIS_ERROR_TAGS),
+    message: z.string(),
+    details: z.record(z.string(), z.union([z.string(), z.number(), z.null()])),
+})
+    .strict();
+const graphNode = z.discriminatedUnion("status", [
+    z.object({
+        address: z.string(),
+        status: z.literal("ok"),
+        calls: z.array(z.string()),
+    }),
+    z.object({
+        address: z.string(),
+        status: z.literal("error"),
+        error: analysisErrorProjectionSchema,
+    }),
 ]);
 const functionDossierOutput = resultOf(functionDossierSchema);
 /** Exact structured-content schemas for the direct Hopper operations. */
@@ -207,10 +223,23 @@ export const enhancedOutputSchemas = {
     swift_classes: symbolDiscoveryOutput("classes"),
     get_objc_classes: symbolDiscoveryOutput("classes"),
     get_objc_protocols: symbolDiscoveryOutput("protocols"),
-    batch_decompile: resultOf(z.union([
-        z.object({ error: z.literal("No addresses provided") }),
-        z.record(z.string(), z.string()),
-    ])),
+    batch_decompile: resultOf(z.object({
+        items: z.array(z.discriminatedUnion("status", [
+            z.object({
+                address: z.string(),
+                status: z.literal("ok"),
+                pseudocode: z.string().min(1),
+            }),
+            z.object({
+                address: z.string(),
+                status: z.literal("error"),
+                error: analysisErrorProjectionSchema,
+            }),
+        ])),
+        total: z.number().int().min(0),
+        succeeded: z.number().int().min(0),
+        failed: z.number().int().min(0),
+    })),
     get_call_graph: resultOf(z.record(z.string(), z.array(graphNode))),
     analyze_swift_types: resultOf(z.object({
         total: z.number().int().min(0),
@@ -219,9 +248,18 @@ export const enhancedOutputSchemas = {
             items: z.array(addressedEntry),
         })),
     })),
-    find_xrefs_to_name: resultOf(z.union([
-        z.object({ xrefs: addressList }),
-        z.object({ error: z.string() }),
+    find_xrefs_to_name: resultOf(z.discriminatedUnion("status", [
+        z.object({
+            status: z.literal("resolved"),
+            name: z.string(),
+            address: z.string(),
+            xrefs: addressList,
+        }),
+        z.object({
+            status: z.literal("unresolved"),
+            name: z.string(),
+            reason: z.literal("name_not_found"),
+        }),
     ])),
     binary_overview: resultOf(z.object({
         document: z.string(),

package/dist/domain/errors.js

@@ -1,3 +1,29 @@
+/** Stable tags exposed by safe analysis-error projections. */
+export const ANALYSIS_ERROR_TAGS = [
+    "AnalysisProtocolError",
+    "AnalysisInputError",
+    "AnalysisOutputError",
+    "AnalysisCapabilityUnavailableError",
+    "AnalysisCancelledError",
+    "AnalysisTimeoutError",
+    "ProviderSelectionError",
+    "ProviderAdapterError",
+    "ArtifactOperationError",
+    "ProcessCaptureError",
+    "EvidenceIntegrityError",
+    "EvidenceLimitError",
+    "EvidenceFileError",
+    "UnknownRegistryError",
+    "HopperTimeoutError",
+    "HopperCancelledError",
+    "HopperProtocolError",
+    "HopperRemoteError",
+    "HopperProcessError",
+    "HopperStartError",
+    "ConfigurationError",
+    "NoBinaryOpenError",
+    "BinaryTargetError",
+];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
 }

package/dist/domain/hopperValues.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
+/** Return the non-negative byte distance between hexadecimal addresses. */
+export const addressDistance = (start, end) => Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));
 const procedureMapSchema = z.record(z.string(), z.string());
 const addressedNamesSchema = z.array(z.object({ address: z.string(), name: z.string() }));
 const addressedNameMapSchema = z.record(z.string(), z.string());

package/dist/native/NativeMacOSProvider.js

@@ -81,6 +81,8 @@ class NativeMacOSClient {
         this.runner = runner;
     }
     async execute(operation, parameters, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation));
         if (operation === "health")
             return ok(createAnalysisExecution(null, IDENTITY));
         if (!isNativeOperation(operation))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Reverse engineer anything from your terminal or coding agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {