rea-agents 0.5.0 → 1.1.0

package/README.md

@@ -11,14 +11,14 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![68 MCP tools](https://img.shields.io/badge/MCP_tools-68-5c4ee5?style=flat-square)](#68-tools-for-investigation)
-[![Node.js 24](https://img.shields.io/badge/Node.js-24.18.x-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
 [Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
-<code>curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash</code>
+<code>npm install --global rea-agents && rea setup</code>
 
 </div>
 
@@ -81,15 +81,24 @@ REA shows how it reached its conclusions. It does not claim to recover original
 
 ## Quick start
 
-### One-command install — recommended
+### Install the CLI — recommended
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
+npm install --global rea-agents
+rea setup
 ```
 
-The installer supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux. It installs compatible Node.js 24/npm 11 prerequisites, the exact latest `rea-agents-*` release, the official Hopper package, detected client registrations, and the bundled skill, then verifies the result. macOS uses Homebrew; Linux uses the native package manager and may show a system authorization prompt. Pin a reproducible release with `REA_VERSION=0.3.0`; `REA_VERSION` is the only supported installer environment override.
+Installing the CLI does not update Homebrew, Node.js, npm, Hopper, or coding-agent configuration. `rea setup` detects what is already present, prints every proposed change, and asks before applying it.
+
+REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. Registrations are additive, backup-first, and read back after writing. You can safely rerun setup.
+
+An optional curl wrapper installs the same CLI package and starts setup only when a terminal is available:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
+```
 
-REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. It configures detected clients with documented local MCP files; Devin is reported as skipped because its public documentation does not define a local configuration file. You can safely rerun the installer or `rea setup --yes`. If REA's local analysis engine needs one-time activation, installation remains intact and setup reports the exact remaining action rather than claiming full readiness.
+Pass installer options after `bash -s --`, for example `--dry-run`, `--no-setup`, or `--version 1.0.0`. The curl wrapper never installs prerequisites or configures integrations itself. See [Installation and setup](docs/installation.md) for its exact mutation boundary.
 
 ### With a coding agent — recommended
 
@@ -99,36 +108,48 @@ npx skills add morluto/rea
 
 Ask your agent to set up REA. It will check your Mac, explain anything it needs to install, ask for approval, and guide you through system prompts. After setup, restart the agent if it asks you to load the full REA toolset.
 
-Approve installation if needed, complete the one-time activation when prompted, then describe the app or feature you want to understand. REA handles the binary-analysis tools behind the scenes.
+Review the setup plan, approve it if appropriate, complete Hopper's one-time activation when prompted, then describe the app or feature you want to understand.
 
 ### From Terminal — no installation
 
 ```bash
-npx -y rea-agents setup --yes
+npx -y rea-agents setup
 npx -y rea-agents doctor
 npx -y rea-agents analyze /Applications/Notes.app
 ```
 
-If macOS or an installer asks for confirmation, complete the prompt and run the same command again. Restart a configured coding agent so it loads REA.
+Review the setup plan before confirming it. Restart a configured coding agent so it loads REA.
 
 ### From Terminal — install the `rea` command
 
 ```bash
 npm install --global rea-agents
-rea setup --yes
+rea setup
 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
 
 - macOS 12 or newer
 - Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
-- Node.js 24.18.x with npm 11.16.x
+- Node.js 22.19+ or 24.11+ (including newer releases)
+- npm; REA does not require or install a particular npm version
 
-You do not need to choose or install binary-analysis tools yourself. REA setup handles them when needed. Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate desktop application with its own license. REA can install the official macOS or Linux package, but you must approve installation and complete its one-time activation.
+Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate desktop application with its own license. Setup reuses an existing installation. If Hopper is missing, interactive setup proposes the official package and includes it in the confirmation plan. Unattended installation requires `rea setup --yes --install-hopper`.
 
 If something is not working, run:
 
@@ -140,7 +161,9 @@ npx -y rea-agents doctor
 
 ### Linux installation and troubleshooting
 
-On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, setup downloads the matching official Hopper package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman`. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`.
+On macOS, approved setup downloads Hopper's official DMG, verifies it, and installs the app into `~/Applications` without Homebrew or administrator privileges. It opens Hopper once for activation; no manual drag-and-drop is required.
+
+On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, approved setup downloads the matching official Hopper package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman`. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`.
 
 The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
 
@@ -155,7 +178,7 @@ If doctor reports a missing analysis engine even though the file exists, inspect
 ldd /opt/hopper/bin/Hopper | grep 'not found'
 ```
 
-Install the missing distribution packages and rerun `rea setup --yes`. Hopper is a desktop application: real analysis requires an active `DISPLAY` or `WAYLAND_DISPLAY`, plus one-time license activation. The curl installer places the `rea` command in `~/.local/bin` on Linux; add that directory to future shell `PATH` values if it is not already present.
+Install the missing distribution packages and rerun `rea setup`. Hopper is a desktop application: real analysis requires an active `DISPLAY` or `WAYLAND_DISPLAY`, plus one-time license activation. The curl installer places the `rea` command in `~/.local/bin` on Linux; add that directory to future shell `PATH` values if it is not already present.
 
 REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` on macOS and `/opt/hopper/bin/Hopper` on Linux. Explicit configuration always takes precedence.
 
@@ -166,7 +189,7 @@ rea uninstall
 rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state
 ```
 
-Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
+Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
 
 ### CLI or coding agent?
 
@@ -275,7 +298,7 @@ REA is growing into a toolkit for understanding software across static artifacts
 7. **More targets and platforms** — Windows-native providers and ConPTY verification, Linux parity, websites and APIs, mobile artifacts, firmware, document formats, and other software-defined systems.
 8. **Differential reconstruction** — compare artifacts, functions, bundles, protocols, UIs, and process captures; track residual unknowns; verify a reconstruction against observed behavior.
 
-Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow.
+Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow. Once REA has multiple optional toolchains, setup can become capability-selective; the consent rules for that future work are recorded in the [installation roadmap](docs/roadmap.md).
 
 See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the current research matrix and admission gate.
 
@@ -343,6 +366,7 @@ Or install the `rea` command globally:
 ```bash
 npm install --global rea-agents
 rea --help
+rea upgrade
 rea mcp
 ```
 

package/dist/application/Doctor.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
+import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { probeHomebrew } from "./homebrew.js";
 import { linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
 const execFileAsync = promisify(execFile);
@@ -18,9 +19,8 @@ const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
  */
 export const runDoctor = async (target, host = systemDoctorHost()) => {
     const checks = [];
-    const nodeMajor = parseMajor(host.nodeVersion);
-    checks.push(check("node", nodeMajor >= 24, host.nodeVersion, {
-        remediation: "Install Node.js 24.18 or newer.",
+    checks.push(check("node", supportsNodeVersion(host.nodeVersion), host.nodeVersion, {
+        remediation: "Install Node.js 22.19+ or 24.11+.",
         classification: "missing_dependency",
     }));
     const macosVersion = host.platform === "darwin" ? await host.macosVersion() : undefined;
@@ -50,7 +50,7 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             break;
         }
     checks.push(check("hopper", hopperPath !== undefined, hopperPath, {
-        remediation: "Run rea setup --yes to install Hopper, or set HOPPER_LAUNCHER_PATH.",
+        remediation: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
         classification: "missing_analysis_engine",
     }));
     if (target !== undefined)

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/EvidenceBundleFiles.js

@@ -60,8 +60,9 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
     if (bytes > policy.maxBytes)
         return err(new EvidenceFileError("write", "too-large"));
     try {
-        const canonicalParent = await realpath(dirname(resolve(path)));
-        const destination = resolve(canonicalParent, basename(resolve(path)));
+        const requestedPath = resolve(path);
+        const canonicalParent = await realpath(dirname(requestedPath));
+        const destination = resolve(canonicalParent, basename(requestedPath));
         if (!(await isApproved(destination, policy.roots)))
             return err(new EvidenceFileError("write", "outside-root"));
         const existing = await lstat(destination).catch((cause) => {
@@ -80,7 +81,7 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
             mode: 0o600,
             fsync: true,
         });
-        return ok({ path: destination, bytes });
+        return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
         return err(new EvidenceFileError("write", "io", { cause }));

package/dist/application/MacHopper.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { access, mkdir, mkdtemp, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execFileAsync = promisify(execFile);
+const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
+const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
+const MAX_PACKAGE_BYTES = 100_000_000;
+const BUNDLE_IDENTIFIER = "com.cryptic-apps.hopper-web-4";
+/** Download, verify, and install Hopper into the current user's Applications directory. */
+export const installMacHopper = async (host = systemMacHopperInstallHost()) => {
+    let temporary;
+    let mounted = false;
+    try {
+        const metadata = await host.download(RELEASES_URL);
+        if (!metadata.ok)
+            return { status: "failed", reason: "release_metadata" };
+        const parsed = releasesSchema.safeParse(parseJson(metadata.bytes));
+        if (!parsed.success)
+            return { status: "failed", reason: "release_metadata" };
+        const release = parsed.data["OS X"];
+        if (!release.filename.startsWith(DOWNLOAD_PREFIX))
+            return { status: "failed", reason: "release_metadata" };
+        const archive = await host.download(release.filename);
+        if (!archive.ok)
+            return { status: "failed", reason: "download" };
+        if (!integrityMatches(archive.bytes, release))
+            return { status: "failed", reason: "integrity" };
+        const destination = host.destination();
+        if (await host.destinationExists(destination))
+            return { status: "failed", reason: "destination_exists" };
+        temporary = await host.createTemporaryDirectory();
+        const packagePath = join(temporary, "hopper.dmg");
+        const mountPath = join(temporary, "mounted");
+        await host.createMountDirectory(mountPath);
+        await host.writePackage(packagePath, archive.bytes);
+        if (!(await host.mount(packagePath, mountPath)))
+            return { status: "failed", reason: "mount" };
+        mounted = true;
+        const source = await host.appBundle(mountPath);
+        if (source === undefined || !(await host.validBundle(source)))
+            return { status: "failed", reason: "bundle" };
+        const stage = `${destination}.rea-stage`;
+        if (!(await host.installBundle(source, destination, stage)))
+            return { status: "failed", reason: "copy" };
+        const launcherPath = join(destination, "Contents/MacOS/hopper");
+        if (!(await host.launcherReady(launcherPath)))
+            return { status: "failed", reason: "launcher_missing" };
+        await host.openApplication(destination);
+        return { status: "installed", launcherPath };
+    }
+    catch {
+        return { status: "failed", reason: "download" };
+    }
+    finally {
+        if (temporary !== undefined) {
+            const mountPath = join(temporary, "mounted");
+            if (mounted)
+                await host.unmount(mountPath);
+            await host.cleanup(temporary);
+        }
+    }
+};
+const systemMacHopperInstallHost = () => ({
+    async download(url) {
+        const response = await fetch(url, {
+            headers: { accept: "application/json", "user-agent": "rea-installer" },
+            signal: AbortSignal.timeout(120_000),
+        });
+        const length = Number(response.headers.get("content-length") ?? "0");
+        if (length > MAX_PACKAGE_BYTES)
+            return { ok: false, bytes: new Uint8Array() };
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return { ok: response.ok && bytes.byteLength <= MAX_PACKAGE_BYTES, bytes };
+    },
+    createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
+    createMountDirectory: (path) => mkdir(path),
+    writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
+    async mount(packagePath, mountPath) {
+        return commandSucceeds("hdiutil", [
+            "attach",
+            "-readonly",
+            "-nobrowse",
+            "-mountpoint",
+            mountPath,
+            packagePath,
+        ]);
+    },
+    async unmount(mountPath) {
+        await commandSucceeds("hdiutil", ["detach", mountPath, "-force"]);
+    },
+    async appBundle(mountPath) {
+        const entries = await readdir(mountPath, { withFileTypes: true });
+        const app = entries.find((entry) => entry.isDirectory() && /^Hopper.*\.app$/iu.test(entry.name));
+        return app === undefined ? undefined : join(mountPath, app.name);
+    },
+    async validBundle(appPath) {
+        if (!(await commandSucceeds("codesign", [
+            "--verify",
+            "--deep",
+            "--strict",
+            appPath,
+        ])))
+            return false;
+        try {
+            const identifier = (await execFileAsync("/usr/libexec/PlistBuddy", [
+                "-c",
+                "Print :CFBundleIdentifier",
+                join(appPath, "Contents/Info.plist"),
+            ])).stdout.trim();
+            return identifier === BUNDLE_IDENTIFIER;
+        }
+        catch {
+            return false;
+        }
+    },
+    async destinationExists(path) {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async installBundle(source, destination, stage) {
+        try {
+            await mkdir(join(homedir(), "Applications"), { recursive: true });
+            await rm(stage, { recursive: true, force: true });
+            await execFileAsync("ditto", [source, stage]);
+            await rename(stage, destination);
+            return true;
+        }
+        catch {
+            await rm(stage, { recursive: true, force: true });
+            return false;
+        }
+    },
+    async launcherReady(path) {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async openApplication(path) {
+        await execFileAsync("open", [path]);
+    },
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
+    destination: () => join(homedir(), "Applications/Hopper Disassembler.app"),
+});
+const parseJson = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
+const integrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
+    bytes.byteLength <= MAX_PACKAGE_BYTES &&
+    createHash("sha1").update(bytes).digest("hex") === release.file_hash;
+const commandSucceeds = async (command, args) => {
+    try {
+        await execFileAsync(command, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const releaseSchema = z.object({
+    filename: z.string().url(),
+    file_length: z.string().regex(/^\d+$/u),
+    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
+});
+const releasesSchema = z.object({ "OS X": releaseSchema });