Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(setup): refresh stale local npx bootstrap
morluto90bb1610f564
diff --git a/README.md b/README.mdindex bf39055cc..e285cd1d5 100644--- a/README.md+++ b/README.md@@ -103,6 +103,13 @@ detected agents, then asks which capabilities to set up: agent integrationNothing is preselected. Choosing agent integration opens a second emptychecklist for the specific detected agents that should receive a registration.+If bare `npx` finds a project-local REA package, its dispatcher restarts setup+through `rea-agents@latest` before planning any changes. This prevents an older+local dependency from silently writing stale integration state. An already+published older release cannot contain that dispatcher protection; run+`npx -y rea-agents@latest setup` once to repair registrations created by one.+Intentional rollbacks remain available through an exact package request.+REA keeps the journey inline so its history remains in the terminal. Selectinga capability does not select every detected target or authorize a change.Before anything changes, REA validates existing configuration, prints exactdiff --git a/docs/installation.md b/docs/installation.mdindex 7f559870a..90aeb5232 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -15,6 +15,24 @@ current package-runner invocation. REA still prints its own setup plan and asksfor separate approval before changing agent configuration or installing aproduct-owned component.+When bare `npx` resolves `rea-agents` from the current project's+`node_modules`, the selected dispatcher restarts setup through+`rea-agents@latest` before REA plans or writes configuration. This protects+current and future releases from silently persisting stale integration state.+Code in an already-published older release cannot acquire that check+retroactively; invoke `npx -y rea-agents@latest setup` once to repair any+registration it created.++For an intentional rollback, make the package request explicit:++```bash+npm exec --yes [email protected] -- rea setup+```++Setup continues to pin persistent MCP registrations to the exact version that+performed setup. Running current setup later migrates unversioned or older+managed registrations through the normal reviewed setup transaction.+REA supports Node.js 22.19+ and 24.11+ (including newer releases). It uses the npm already paired with that runtime and never upgrades Node.js, npm, or Homebrew.Running `npm install rea-agents` without `--global` installs the executable onlydiff --git a/package.json b/package.jsonindex 244c549fa..e9c873aec 100644--- a/package.json+++ b/package.json@@ -43,6 +43,7 @@"bridge/hopper_bridge.py","bridge/ghidra/ReaGhidraBridge.java","scripts/rea.mjs",+ "scripts/package-runner-bootstrap.mjs","scripts/hopper-demo-x11.py","scripts/prepack.mjs","scripts/prepare.mjs",diff --git a/scripts/package-runner-bootstrap.d.mts b/scripts/package-runner-bootstrap.d.mtsnew file mode 100644index 000000000..b220b8729--- /dev/null+++ b/scripts/package-runner-bootstrap.d.mts@@ -0,0 +1,19 @@+export interface PackageRunnerSetupInput {+ readonly args: readonly string[];+ readonly environment: Readonly<Record<string, string | undefined>>;+ readonly packageRoot: string;+ readonly packageName: string;+}++export interface PackageRunnerSetupPlan {+ readonly command: "npm";+ readonly args: readonly string[];+}++export function packageRunnerSetupPlan(+ input: PackageRunnerSetupInput,+): PackageRunnerSetupPlan | undefined;++export function runPackageRunnerSetupBootstrap(+ input: PackageRunnerSetupInput,+): Promise<number | undefined>;diff --git a/scripts/package-runner-bootstrap.mjs b/scripts/package-runner-bootstrap.mjsnew file mode 100644index 000000000..fd3034792--- /dev/null+++ b/scripts/package-runner-bootstrap.mjs@@ -0,0 +1,72 @@+import { spawn } from "node:child_process";+import { resolve } from "node:path";++const BOOTSTRAP_MARKER = "REA_PACKAGE_RUNNER_BOOTSTRAPPED";++/**+ * Plan a current-release setup bootstrap when bare npx selected a project-local+ * package. Explicit `npm exec --package=<name>@<version>` rollbacks bypass it.+ */+export function packageRunnerSetupPlan(input) {+ if (input.args[0] !== "setup") return undefined;+ if (input.environment[BOOTSTRAP_MARKER] === "1") return undefined;+ if (input.environment.npm_lifecycle_event !== "npx") return undefined;++ const localPrefix = input.environment.npm_config_local_prefix;+ if (localPrefix === undefined || localPrefix.length === 0) return undefined;+ if (+ !isPackageBelowLocalPrefix(+ input.packageRoot,+ localPrefix,+ input.packageName,+ )+ )+ return undefined;++ const requestedPackage = input.environment.npm_config_package;+ if (+ requestedPackage !== undefined &&+ isExactPackageVersion(requestedPackage, input.packageName)+ )+ return undefined;++ return {+ command: "npm",+ args: [+ "exec",+ "--yes",+ `--package=${input.packageName}@latest`,+ "--",+ "rea",+ ...input.args,+ ],+ };+}++/** Execute a planned package-runner bootstrap and return its exit status. */+export async function runPackageRunnerSetupBootstrap(input) {+ const plan = packageRunnerSetupPlan(input);+ if (plan === undefined) return undefined;++ return await new Promise((resolveExitCode) => {+ const child = spawn(plan.command, plan.args, {+ stdio: "inherit",+ env: { ...input.environment, [BOOTSTRAP_MARKER]: "1" },+ });+ child.once("error", () => resolveExitCode(1));+ child.once("exit", (code) => resolveExitCode(code ?? 1));+ });+}++function isPackageBelowLocalPrefix(packageRoot, localPrefix, packageName) {+ const expectedRoot = resolve(localPrefix, "node_modules", packageName);+ return resolve(packageRoot) === expectedRoot;+}++function isExactPackageVersion(packageSpecifier, packageName) {+ const version = packageSpecifier.slice(`${packageName}@`.length);+ return (+ packageSpecifier.startsWith(`${packageName}@`) &&+ /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(version)+ );+}diff --git a/scripts/rea.mjs b/scripts/rea.mjsindex 8bc02dfe6..8d75c1c55 100755--- a/scripts/rea.mjs+++ b/scripts/rea.mjs@@ -4,6 +4,8 @@ import { access } from "node:fs/promises";import { dirname, resolve } from "node:path";import { fileURLToPath } from "node:url";+import { runPackageRunnerSetupBootstrap } from "./package-runner-bootstrap.mjs";+// Route production MCP before importing Incur. Incur owns registration helpers// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.const args = process.argv.slice(2);@@ -15,13 +17,21 @@ const isMcpMode =args.length === 1 && (args[0] === "--mcp" || args[0] === "mcp");const isMcpDoctorMode = args[0] === "mcp" && args[1] === "doctor";const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const bootstrapExitCode = await runPackageRunnerSetupBootstrap({+ args,+ environment: process.env,+ packageRoot,+ packageName: packageJson.name,+});const runtimeFiles = isMcpMode? ["dist/main.js"]: isMcpDoctorMode? ["dist/main.js", "dist/mcpDoctor.js"]: ["dist/cli.js", "dist/cliOutput.js"];-if (!(await compiledRuntimeExists(runtimeFiles))) {+if (bootstrapExitCode !== undefined) {+ process.exitCode = bootstrapExitCode;+} else if (!(await compiledRuntimeExists(runtimeFiles))) {process.stderr.write(`REA's compiled runtime is missing. Run \`npm ci\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,);diff --git a/tests/dispatcher.test.ts b/tests/dispatcher.test.tsindex 4feeff67c..5afe2869a 100644--- a/tests/dispatcher.test.ts+++ b/tests/dispatcher.test.ts@@ -25,6 +25,10 @@ describe("executable dispatcher", () => {await Promise.all([mkdir(scripts), mkdir(dist)]);await Promise.all([copyFile("scripts/rea.mjs", join(scripts, "rea.mjs")),+ copyFile(+ "scripts/package-runner-bootstrap.mjs",+ join(scripts, "package-runner-bootstrap.mjs"),+ ),writeFile(join(fixtureRoot, "package.json"),JSON.stringify({ type: "module", version: "1.0.0" }),@@ -77,6 +81,10 @@ describe("executable dispatcher", () => {await mkdir(scripts);await Promise.all([copyFile("scripts/rea.mjs", join(scripts, "rea.mjs")),+ copyFile(+ "scripts/package-runner-bootstrap.mjs",+ join(scripts, "package-runner-bootstrap.mjs"),+ ),writeFile(join(fixtureRoot, "package.json"),JSON.stringify({ type: "module", version: "1.0.0" }),diff --git a/tests/packageRunnerBootstrap.test.ts b/tests/packageRunnerBootstrap.test.tsnew file mode 100644index 000000000..6f03fe054--- /dev/null+++ b/tests/packageRunnerBootstrap.test.ts@@ -0,0 +1,153 @@+import { chmod, readFile, writeFile } from "node:fs/promises";+import { delimiter, join } from "node:path";++import { describe, expect, it } from "vitest";++import {+ packageRunnerSetupPlan,+ runPackageRunnerSetupBootstrap,+} from "../scripts/package-runner-bootstrap.mjs";+import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js";++describe("package-runner setup bootstrap", () => {+ it("reruns bare setup through the current release when npm selected a local package", () => {+ expect(+ packageRunnerSetupPlan({+ args: ["setup", "--client", "codex"],+ environment: {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ },+ packageRoot: "/work/project/node_modules/rea-agents",+ packageName: "rea-agents",+ }),+ ).toEqual({+ command: "npm",+ args: [+ "exec",+ "--yes",+ "--package=rea-agents@latest",+ "--",+ "rea",+ "setup",+ "--client",+ "codex",+ ],+ });+ });++ it("leaves explicit rollback and non-local invocations untouched", () => {+ const base = {+ args: ["setup"],+ packageRoot: "/work/project/node_modules/rea-agents",+ packageName: "rea-agents",+ } as const;++ expect(+ packageRunnerSetupPlan({+ ...base,+ environment: {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ npm_config_package: "[email protected]",+ },+ }),+ ).toBeUndefined();+ expect(+ packageRunnerSetupPlan({+ ...base,+ environment: {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ npm_config_package: "rea-agents@^2.4.0",+ },+ }),+ ).toEqual(+ expect.objectContaining({+ args: expect.arrayContaining(["--package=rea-agents@latest"]),+ }),+ );+ expect(+ packageRunnerSetupPlan({+ ...base,+ packageRoot: "/root/.npm/_npx/cache/node_modules/rea-agents",+ environment: {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ },+ }),+ ).toBeUndefined();+ });++ it("does not redirect recursively or affect commands other than setup", () => {+ const environment = {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ REA_PACKAGE_RUNNER_BOOTSTRAPPED: "1",+ };++ expect(+ packageRunnerSetupPlan({+ args: ["setup"],+ environment,+ packageRoot: "/work/project/node_modules/rea-agents",+ packageName: "rea-agents",+ }),+ ).toBeUndefined();+ expect(+ packageRunnerSetupPlan({+ args: ["doctor"],+ environment: {+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ },+ packageRoot: "/work/project/node_modules/rea-agents",+ packageName: "rea-agents",+ }),+ ).toBeUndefined();+ });++ it("forwards setup arguments to npm with a recursion marker", async () => {+ const directory = await createTestTempDirectory("rea-bootstrap-");+ const npm = join(directory, "npm");+ const log = join(directory, "invocation.json");+ await writeFile(+ npm,+ `#!/usr/bin/env node+import { writeFileSync } from "node:fs";+writeFileSync(process.env.REA_BOOTSTRAP_TEST_LOG, JSON.stringify({+ args: process.argv.slice(2),+ marker: process.env.REA_PACKAGE_RUNNER_BOOTSTRAPPED,+}));+`,+ );+ await chmod(npm, 0o755);++ await expect(+ runPackageRunnerSetupBootstrap({+ args: ["setup", "--dry-run"],+ environment: {+ ...process.env,+ PATH: `${directory}${delimiter}${process.env.PATH ?? ""}`,+ REA_BOOTSTRAP_TEST_LOG: log,+ npm_lifecycle_event: "npx",+ npm_config_local_prefix: "/work/project",+ },+ packageRoot: "/work/project/node_modules/rea-agents",+ packageName: "rea-agents",+ }),+ ).resolves.toBe(0);+ await expect(readFile(log, "utf8").then(JSON.parse)).resolves.toEqual({+ args: [+ "exec",+ "--yes",+ "--package=rea-agents@latest",+ "--",+ "rea",+ "setup",+ "--dry-run",+ ],+ marker: "1",+ });+ });+});diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.tsindex b01bc59df..83b881b84 100644--- a/tests/readmeConsistency.test.ts+++ b/tests/readmeConsistency.test.ts@@ -92,5 +92,19 @@ describe("localized README product facts", () => {expect(content).toContain("--install-hopper");expect(content).toContain("docs/installation.md");expect(content).toContain("You do not need both");+ expect(content).toContain(+ "npx -y rea-agents@latest setup` once to repair registrations",+ );+ });++ it("documents stale bootstrap recovery and explicit rollback", async () => {+ const content = await readFile(resolve("docs/installation.md"), "utf8");+ expect(content).toContain("before REA plans or writes configuration");+ expect(content).toContain(+ "npm exec --yes [email protected] -- rea setup",+ );+ expect(content).toContain(+ "pin persistent MCP registrations to the exact version",+ );});});