rea-agents 1.0.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.
 
-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.
+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
+```
+
+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,23 +108,23 @@ 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
 ```
@@ -137,9 +146,10 @@ Choose either the no-install commands or the global installation. You do not nee
 
 - 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:
 
@@ -151,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:
 
@@ -166,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.
 
@@ -177,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?
 
@@ -286,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.
 

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/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 });

package/dist/application/Setup.js

@@ -1,30 +1,30 @@
 import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
-import { probeHomebrew } from "./homebrew.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
-const execFileAsync = promisify(execFile);
+import { installMacHopper } from "./MacHopper.js";
 const registrationCommand = () => process.env.npm_command === "exec"
     ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
 /**
  * Install prerequisites and configure detected clients idempotently.
- * With `yes` false, mutations requiring consent are reported as `needs_human`;
- * with `yes` true, external installers still fail closed if they require UI.
+ * Discovery always precedes mutation. Interactive confirmation or explicit
+ * unattended options authorize only the actions represented in the result.
  */
-export const runSetup = async (yes, host = systemSetupHost()) => {
-    const actions = [];
+export const runSetup = async (options, host = systemSetupHost(), confirm) => {
+    const appliedActions = [];
+    let plannedActions = [];
     const clients = {};
     const fail = async (remediation) => ({
         status: "needs_human",
-        actions,
+        plannedActions,
+        appliedActions,
         clients,
         doctor: await host.doctor(),
         remediation,
@@ -32,43 +32,85 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
     const unsupported = await hostRemediation(host);
     if (unsupported !== undefined)
         return fail(unsupported);
-    if (host.platform === "darwin" && !(await host.hasHomebrew())) {
-        if (!yes)
-            return fail("Re-run with --yes to install Homebrew.");
-        if (!(await host.installHomebrew()))
-            return fail("Homebrew installation was interrupted; resolve the installer prompt and re-run setup.");
-        actions.push("installed_homebrew");
-    }
     let hopperPath = await host.hopperPath();
-    if (hopperPath === undefined) {
-        if (!yes)
-            return fail("Re-run with --yes to install Hopper.");
-        if (!(await host.installHopper()))
-            return fail("Hopper installation was interrupted; resolve the system prompt and re-run setup.");
-        actions.push("installed_hopper");
-        hopperPath = await host.hopperPath();
+    const detectedClients = await host.detectedClients();
+    plannedActions = [
+        ...(hopperPath === undefined
+            ? [
+                {
+                    kind: "install_hopper",
+                    target: host.platform === "darwin"
+                        ? "~/Applications/Hopper Disassembler.app"
+                        : "system package manager",
+                    detail: "Download the official Hopper package, verify it, install it, and open Hopper for activation.",
+                    external: true,
+                },
+            ]
+            : []),
+        ...detectedClients
+            .filter(({ format }) => format !== "unsupported")
+            .map((client) => ({
+            kind: "configure_client",
+            target: client.configPath,
+            detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
+            external: false,
+        })),
+        {
+            kind: "install_skill",
+            target: "~/.agents/skills/rea-analysis/SKILL.md",
+            detail: "Install or update the bundled REA analysis skill.",
+            external: false,
+        },
+    ];
+    let approved = options.approved;
+    let interactiveApproval = false;
+    if (!approved && confirm !== undefined && !options.structured) {
+        interactiveApproval = await confirm(plannedActions);
+        approved = interactiveApproval;
+    }
+    if (!approved)
+        return {
+            status: confirm === undefined ? "needs_confirmation" : "planned",
+            plannedActions,
+            appliedActions,
+            clients,
+            doctor: await host.doctor(),
+            remediation: "Review the setup plan, then rerun interactively or with --yes.",
+        };
+    if (hopperPath === undefined &&
+        (interactiveApproval || options.installHopper)) {
+        hopperPath = await host.installHopper();
         if (hopperPath === undefined)
-            return fail("Hopper installation completed but its launcher was not found.");
+            return {
+                status: "needs_human",
+                plannedActions,
+                appliedActions,
+                clients,
+                doctor: await host.doctor(),
+                remediation: "Hopper installation failed; install Hopper manually or rerun setup after resolving the reported system error.",
+            };
+        appliedActions.push("installed_hopper");
     }
-    for (const client of await host.detectedClients()) {
+    for (const client of detectedClients) {
         const result = await host.configureClient(client, hopperPath, registrationCommand());
         clients[client.name] = result;
         if (result.status === "failed")
             return fail(`${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`);
         if (result.status === "configured")
-            actions.push(`configured_${client.name}`);
+            appliedActions.push(`configured_${client.name}`);
     }
     const skill = await host.installSkill();
     if (skill === "failed")
         return fail("Agent skill installation or readback failed.");
     if (skill === "installed")
-        actions.push("installed_skill");
+        appliedActions.push("installed_skill");
     const doctor = await host.doctor();
-    const activationRequired = actions.includes("installed_hopper");
+    const activationRequired = appliedActions.includes("installed_hopper");
     const ready = doctor.healthy && !activationRequired;
     return {
         status: ready ? "ready" : "needs_human",
-        actions,
+        plannedActions,
+        appliedActions,
         clients,
         doctor,
         ...(ready
@@ -76,15 +118,17 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
             : {
                 remediation: activationRequired
                     ? "Open Hopper, complete its one-time activation, then rerun rea doctor --json."
-                    : "Run rea doctor and apply each reported remediation.",
+                    : hopperPath === undefined
+                        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
+                        : "Run rea doctor and apply each reported remediation.",
             }),
     };
 };
 const hostRemediation = async (host) => {
     if (host.platform !== "darwin" && host.platform !== "linux")
         return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
-    if (major(host.nodeVersion) < 24)
-        return "Install Node.js 24.18 or newer.";
+    if (!supportsNodeVersion(host.nodeVersion))
+        return "Install Node.js 22.19+ or 24.11+ and rerun setup.";
     if (host.platform === "darwin") {
         const version = await host.macosVersion();
         return version === undefined || major(version) < 12
@@ -95,7 +139,7 @@ const hostRemediation = async (host) => {
         ? undefined
         : "REA supports Hopper on Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.";
 };
-/** Production setup effects for macOS, Homebrew, JSON MCP clients, and the canonical skill directory. */
+/** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 const systemSetupHost = () => {
     const doctorHost = systemDoctorHost();
     return {
@@ -103,15 +147,13 @@ const systemSetupHost = () => {
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
-        hasHomebrew: () => brewSucceeds(["--version"]),
-        installHomebrew: () => commandSucceeds("/bin/bash", [
-            "-c",
-            "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)",
-        ], { ...process.env, NONINTERACTIVE: "1" }),
         hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
-        installHopper: () => process.platform === "linux"
-            ? installLinuxHopper().then(({ status }) => status === "installed")
-            : brewSucceeds(["install", "--cask", "hopper-disassembler"]),
+        installHopper: async () => {
+            const result = process.platform === "linux"
+                ? await installLinuxHopper()
+                : await installMacHopper();
+            return result.status === "installed" ? result.launcherPath : undefined;
+        },
         detectedClients: () => detectClients(homedir()),
         configureClient: (client, hopperPath, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
@@ -351,19 +393,6 @@ export const installCanonicalSkill = async (home) => {
         return "failed";
     }
 };
-const commandSucceeds = async (command, args, env) => {
-    try {
-        await execFileAsync(command, args, env === undefined ? {} : { env });
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const brewSucceeds = async (args) => {
-    const result = await probeHomebrew(async (command) => (await commandSucceeds(command, args)) ? true : undefined);
-    return result === true;
-};
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
 const exists = async (path) => {
     try {

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { Cli, z } from "incur";
 import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
 import { runDoctor } from "./application/Doctor.js";
 import { runDirectAnalysis, runProviderAnalysis, runSessionStatus, } from "./application/DirectAnalysis.js";
 import { runSetup } from "./application/Setup.js";
@@ -60,10 +61,20 @@ const registerCoreCommands = (cli, logger) => {
             yes: z
                 .boolean()
                 .default(false)
-                .describe("Approve prerequisite installation"),
+                .describe("Approve user-owned setup actions without prompting"),
+            installHopper: z
+                .boolean()
+                .default(false)
+                .describe("Also approve Hopper installation with --yes"),
         }),
-        alias: { yes: "y" },
-        run: ({ options }) => logCliCommand(logger, "setup", () => runSetup(options.yes)),
+        alias: { yes: "y", installHopper: "install-hopper" },
+        run: ({ options, formatExplicit }) => logCliCommand(logger, "setup", () => runSetup({
+            approved: options.yes,
+            installHopper: options.installHopper,
+            structured: formatExplicit,
+        }, undefined, options.yes || formatExplicit || process.stdin.isTTY !== true
+            ? undefined
+            : confirmSetup)),
     });
     cli.command("doctor", {
         description: "Check whether REA is ready",
@@ -112,6 +123,24 @@ const registerCoreCommands = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
     });
 };
+const confirmSetup = async (actions) => {
+    process.stdout.write("\nREA setup plan\n");
+    for (const action of actions)
+        process.stdout.write(`  - ${action.detail}\n    ${action.target}${action.external ? " (external software)" : ""}\n`);
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await prompt.question("Continue? [Y/n] "))
+            .trim()
+            .toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        prompt.close();
+    }
+};
 const registerXrefsCommand = (cli, logger) => {
     cli.command("xrefs", {
         description: "List bounded references to an analyzed address",

package/dist/domain/runtimeVersion.js

@@ -0,0 +1,8 @@
+/** Return whether a Node.js version satisfies REA's tested runtime families. */
+export const supportsNodeVersion = (version) => {
+    const [majorText = "", minorText = ""] = version.split(".");
+    const major = Number.parseInt(majorText, 10);
+    const minor = Number.parseInt(minorText, 10);
+    return ((major === 22 && minor >= 19) ||
+        (major >= 24 && (major !== 24 || minor >= 11)));
+};

package/install.sh

@@ -3,196 +3,111 @@ set -euo pipefail
 
 PACKAGE="rea-agents"
 REPOSITORY="morluto/rea"
-NODE_FORMULA="node@24"
-NODE_VERSION="24.18.0"
-temporary_directory=""
-node_destination=""
-node_stage=""
-node_backup=""
-node_version=""
-
-cleanup() {
-  if [[ -n "$temporary_directory" && -d "$temporary_directory" ]]; then
-    rm -rf -- "$temporary_directory"
-  fi
-  if [[ -n "$node_stage" && -e "$node_stage" ]]; then
-    rm -rf -- "$node_stage"
-  fi
-  if [[ -n "$node_backup" && -e "$node_backup" && ! -e "$node_destination" ]]; then
-    mv -- "$node_backup" "$node_destination"
-  fi
-}
-trap cleanup EXIT HUP INT TERM
+version="${REA_VERSION:-}"
+dry_run=false
+start_setup=true
+verbose=false
 
 fail() {
   printf 'REA installation failed: %s\n' "$1" >&2
   exit 1
 }
 
-version_at_least() {
-  local actual="$1" required_major="$2" required_minor="$3"
-  local major minor
-  major="${actual%%.*}"
-  minor="${actual#*.}"
-  minor="${minor%%.*}"
-  [[ "$major" =~ ^[0-9]+$ && "$minor" =~ ^[0-9]+$ ]] || return 1
-  ((major > required_major || (major == required_major && minor >= required_minor)))
+usage() {
+  cat <<'EOF'
+Usage: install.sh [--version VERSION] [--dry-run] [--no-setup] [--no-prompt] [--verbose]
+
+Installs only the REA CLI. Run `rea setup` separately to configure Hopper and coding agents.
+EOF
 }
 
-platform="$(uname -s)"
-if [[ "$platform" == "Darwin" ]]; then
-  macos_version="$(sw_vers -productVersion 2>/dev/null)" || fail "could not determine the macOS version."
-  macos_major="${macos_version%%.*}"
-  [[ "$macos_major" =~ ^[0-9]+$ && "$macos_major" -ge 12 ]] || fail "macOS 12 or newer is required."
-elif [[ "$platform" == "Linux" ]]; then
-  [[ "$(uname -m)" == "x86_64" || "$(uname -m)" == "aarch64" ]] || fail "64-bit x86 or ARM Linux is required."
-  [[ -r /etc/os-release ]] || fail "could not identify the Linux distribution."
-  linux_id="$(sed -n 's/^ID=//p' /etc/os-release | tr -d '"')"
-  linux_version="$(sed -n 's/^VERSION_ID=//p' /etc/os-release | tr -d '"')"
-  case "$linux_id" in
-    ubuntu) [[ "${linux_version%%.*}" -ge 24 ]] || fail "Ubuntu 24.04 or newer is required." ;;
-    fedora) [[ "${linux_version%%.*}" -ge 41 ]] || fail "Fedora 41 or newer is required." ;;
-    arch) ;;
-    *) fail "supported Linux distributions are Ubuntu 24.04+, Fedora 41+, and Arch Linux." ;;
+while (($# > 0)); do
+  case "$1" in
+    --version)
+      (($# >= 2)) || fail "--version requires a value."
+      version="$2"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=true
+      shift
+      ;;
+    --no-setup|--no-prompt)
+      start_setup=false
+      shift
+      ;;
+    --verbose)
+      verbose=true
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *) fail "unknown option: $1" ;;
   esac
-else
-  fail "REA supports macOS and selected 64-bit Linux distributions."
-fi
-command -v curl >/dev/null 2>&1 || fail "curl is required."
-command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1 || fail "shasum or sha256sum is required."
+done
 
-if [[ "$platform" == "Darwin" ]] && ! command -v brew >/dev/null 2>&1; then
-  printf 'Installing Homebrew prerequisite...\n'
-  NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || fail "Homebrew installation did not complete."
-  if [[ -x /opt/homebrew/bin/brew ]]; then
-    PATH="/opt/homebrew/bin:$PATH"
-  elif [[ -x /usr/local/bin/brew ]]; then
-    PATH="/usr/local/bin:$PATH"
-  fi
-fi
-if [[ "$platform" == "Darwin" ]]; then
-  command -v brew >/dev/null 2>&1 || fail "Homebrew is not available after installation."
+if [[ "$verbose" == true ]]; then
+  set -x
 fi
 
-node_compatible=false
-if command -v node >/dev/null 2>&1; then
-  node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
-fi
-if version_at_least "$node_version" 24 18 && [[ "$node_version" =~ ^24\. ]]; then
-  node_compatible=true
-fi
-if [[ "$node_compatible" != true ]]; then
-  if [[ "$platform" == "Darwin" ]]; then
-    brew install "$NODE_FORMULA" || fail "Node.js 24 installation failed."
-    node_prefix="$(brew --prefix "$NODE_FORMULA")" || fail "could not locate Node.js 24."
-    PATH="$node_prefix/bin:$PATH"
-  else
-    machine="$(uname -m)"
-    node_arch="$([[ "$machine" == "x86_64" ]] && printf 'x64' || printf 'arm64')"
-    node_archive="node-v${NODE_VERSION}-linux-${node_arch}.tar.xz"
-    node_base="https://nodejs.org/dist/v${NODE_VERSION}"
-    temporary_directory="$(mktemp -d "${TMPDIR:-/tmp}/rea-install.XXXXXX")" || fail "could not create a temporary directory."
-    curl -fsSL "$node_base/$node_archive" -o "$temporary_directory/$node_archive" || fail "Node.js download failed."
-    curl -fsSL "$node_base/SHASUMS256.txt" -o "$temporary_directory/SHASUMS256.txt" || fail "Node.js checksum download failed."
-    expected_checksum="$(awk -v archive="$node_archive" '$2 == archive { print $1 }' "$temporary_directory/SHASUMS256.txt")"
-    [[ "$expected_checksum" =~ ^[a-f0-9]{64}$ ]] || fail "Node.js checksum metadata was malformed."
-    if command -v shasum >/dev/null 2>&1; then
-      actual_checksum="$(shasum -a 256 "$temporary_directory/$node_archive" | awk '{ print $1 }')"
-    else
-      actual_checksum="$(sha256sum "$temporary_directory/$node_archive" | awk '{ print $1 }')"
-    fi
-    [[ "$actual_checksum" == "$expected_checksum" ]] || fail "Node.js checksum verification failed."
-    node_destination="$HOME/.local/share/rea/node"
-    node_stage="$HOME/.local/share/rea/node.new.$$"
-    node_backup="$HOME/.local/share/rea/node.backup.$$"
-    [[ ! -L "$node_destination" ]] || fail "refusing to replace a symlinked Node.js installation."
-    mkdir -p "$HOME/.local/share/rea"
-    rm -rf -- "$node_stage" "$node_backup"
-    mkdir "$node_stage"
-    tar -xJf "$temporary_directory/$node_archive" --strip-components=1 -C "$node_stage" || fail "Node.js extraction failed."
-    if [[ -e "$node_destination" ]]; then
-      mv -- "$node_destination" "$node_backup"
-    fi
-    if ! mv -- "$node_stage" "$node_destination"; then
-      [[ ! -e "$node_backup" ]] || mv -- "$node_backup" "$node_destination"
-      fail "Node.js installation replacement failed."
-    fi
-    node_stage=""
-    rm -rf -- "$node_backup"
-    node_backup=""
-    PATH="$node_destination/bin:$PATH"
-  fi
-fi
+platform="$(uname -s)"
+[[ "$platform" == "Darwin" || "$platform" == "Linux" ]] || fail "REA supports macOS and selected 64-bit Linux distributions."
+command -v curl >/dev/null 2>&1 || fail "curl is required."
+command -v node >/dev/null 2>&1 || fail "Node.js 22.19+ or 24.11+ is required; install it from https://nodejs.org and retry."
+command -v npm >/dev/null 2>&1 || fail "npm is required; install it with Node.js and retry."
+
 node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
-if ! command -v node >/dev/null 2>&1 || ! version_at_least "$node_version" 24 18 || [[ ! "$node_version" =~ ^24\. ]]; then
-  fail "Node.js 24.18 or newer is not active on PATH."
-fi
-command -v npm >/dev/null 2>&1 || fail "npm is missing from the Node.js installation."
-npm_version="$(npm --version)"
-if [[ ! "$npm_version" =~ ^11\. ]] || ! version_at_least "$npm_version" 11 16; then
-  if [[ "$platform" == "Linux" ]]; then
-    npm install --global --prefix "$HOME/.local" npm@11 || fail "npm 11 installation failed."
-  else
-    npm install --global npm@11 || fail "npm 11 installation failed."
-  fi
-fi
-npm_version="$(npm --version)"
-if [[ ! "$npm_version" =~ ^11\. ]] || ! version_at_least "$npm_version" 11 16; then
-  fail "npm 11.16 or newer is not active on PATH."
+IFS=. read -r node_major node_minor _node_patch <<<"$node_version"
+[[ "$node_major" =~ ^[0-9]+$ && "$node_minor" =~ ^[0-9]+$ ]] || fail "could not determine the active Node.js version."
+if ! ((node_major == 22 && node_minor >= 19 || node_major >= 24)); then
+  fail "Node.js $node_version is unsupported; use Node.js 22.19+ or 24.11+."
 fi
-if [[ -n "$temporary_directory" ]]; then
-  rm -rf -- "$temporary_directory"
-  temporary_directory=""
+if ((node_major == 24 && node_minor < 11)); then
+  fail "Node.js $node_version is unsupported; use Node.js 24.11 or newer."
 fi
 
-if [[ -n "${REA_VERSION:-}" ]]; then
-  version="$REA_VERSION"
-  [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || fail "REA_VERSION must be an exact semantic version."
+if [[ -n "$version" ]]; then
+  [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || fail "version must be an exact semantic version."
 else
-  release_json="$(curl -fsSL -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "could not resolve the latest GitHub release."
+  release_json="$(curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "could not resolve the latest GitHub release."
   tag="$(printf '%s' "$release_json" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const v=JSON.parse(s).tag_name;if(typeof v!=="string")process.exit(1);process.stdout.write(v)})')" || fail "GitHub returned malformed release metadata."
   [[ "$tag" =~ ^rea-agents-([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$ ]] || fail "latest release tag is not a valid rea-agents release."
   version="${BASH_REMATCH[1]}"
 fi
 
-printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
+prefix_args=()
 if [[ "$platform" == "Linux" ]]; then
-  mkdir -p "$HOME/.local/bin"
-  PATH="$HOME/.local/bin:$PATH"
-  npm install --global --prefix "$HOME/.local" "$PACKAGE@$version" || fail "npm package installation failed."
+  prefix_args=(--prefix "$HOME/.local")
+  install_bin="$HOME/.local/bin/rea"
 else
-  npm install --global "$PACKAGE@$version" || fail "npm package installation failed."
+  npm_prefix="$(npm prefix --global)" || fail "could not determine the npm global prefix."
+  install_bin="$npm_prefix/bin/rea"
 fi
-command -v rea >/dev/null 2>&1 || fail "the rea command is not available after installation."
-installed_version="$(rea --version 2>/dev/null | tr -d '[:space:]')" || fail "could not read the installed REA version."
-[[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version."
 
-temporary_directory="$(mktemp -d "${TMPDIR:-/tmp}/rea-install.XXXXXX")" || fail "could not create a temporary directory."
-setup_output="$temporary_directory/setup.json"
-doctor_output="$temporary_directory/doctor.json"
-rea setup --yes --json >"$setup_output" || fail "REA setup command failed."
-rea doctor --json >"$doctor_output" || fail "REA doctor command failed."
-result="$(node - "$setup_output" "$doctor_output" <<'NODE'
-const fs = require("node:fs");
-const [setupPath, doctorPath] = process.argv.slice(2);
-try {
-  const setup = JSON.parse(fs.readFileSync(setupPath, "utf8"));
-  const doctor = JSON.parse(fs.readFileSync(doctorPath, "utf8"));
-  if (!Array.isArray(doctor.checks) || typeof doctor.healthy !== "boolean") process.exit(2);
-  if (setup.status !== "ready" && setup.status !== "needs_human") process.exit(2);
-  const activation = setup.actions.includes("installed_hopper");
-  if (!doctor.healthy && !activation) process.exit(3);
-  process.stdout.write(activation ? "activation" : "ready");
-} catch { process.exit(2); }
-NODE
-)" || fail "setup or doctor reported an unhealthy required component or malformed output."
+printf 'REA install plan\n'
+printf '  Version: %s\n' "$version"
+printf '  Runtime: Node.js %s\n' "$node_version"
+printf '  Command: npm install --global %s@%s\n' "$PACKAGE" "$version"
+printf '  Binary:  %s\n' "$install_bin"
+printf '  Setup:   %s\n' "$([[ "$start_setup" == true ]] && printf 'start when a terminal is available' || printf 'skipped')"
 
-if [[ "$result" == "activation" ]]; then
-  printf 'REA %s is installed and coding agents are configured.\n' "$version"
-  printf 'One user action remains: open Hopper, complete its activation, then run: rea doctor --json\n'
-else
-  printf 'REA %s is installed and ready. Run rea doctor --json at any time.\n' "$version"
+if [[ "$dry_run" == true ]]; then
+  printf 'Dry run complete; no changes made.\n'
+  exit 0
 fi
-if [[ "$platform" == "Linux" ]]; then
-  printf 'Add %s to PATH to run rea from future shells.\n' "$HOME/.local/bin"
+
+printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
+npm install --global "${prefix_args[@]}" "$PACKAGE@$version" || fail "npm package installation failed."
+[[ -x "$install_bin" ]] || fail "the rea command was not installed at $install_bin."
+installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "could not read the installed REA version."
+[[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version."
+
+printf 'REA %s is installed.\n' "$version"
+if [[ "$start_setup" == true && -r /dev/tty && -w /dev/tty && -t 1 ]]; then
+  printf 'Starting REA setup...\n'
+  "$install_bin" setup </dev/tty >/dev/tty
+else
+  printf 'Run %s setup to configure Hopper and coding agents.\n' "$install_bin"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Reverse engineer anything from your terminal or coding agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -33,8 +33,7 @@
     "rea": "scripts/rea.mjs"
   },
   "engines": {
-    "node": ">=24.18.0 <25",
-    "npm": ">=11.16.0 <12"
+    "node": "^22.19.0 || >=24.11.0"
   },
   "packageManager": "npm@11.16.0",
   "files": [
@@ -99,7 +98,7 @@
     "pino": "9.14.0",
     "plist": "5.0.0",
     "smol-toml": "^1.7.0",
-    "write-file-atomic": "8.0.0",
+    "write-file-atomic": "7.0.0",
     "ws": "8.21.0",
     "zod": "4.4.3"
   },