rea-agents 2.4.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -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",
@@ -54,12 +55,16 @@
     "deps:check": "node scripts/check-dependency-install.mjs",
     "metadata:generate": "node scripts/generate-package-metadata.mjs",
     "metadata:check": "node scripts/generate-package-metadata.mjs --check",
+    "mcp-catalog:generate": "npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs",
+    "mcp-catalog:check": "node scripts/generate-mcp-tool-catalog.mjs --check",
     "prebuild": "npm run deps:check && npm run metadata:check",
     "build": "tsc -p tsconfig.build.json",
     "precheck": "npm run deps:check",
     "check": "turbo run typecheck lint format:check knip metadata:check",
     "precheck:fast": "npm run deps:check",
     "check:fast": "turbo run typecheck lint",
+    "precheck:changed": "npm run deps:check",
+    "check:changed": "turbo run typecheck lint && npm run test:changed",
     "precheck:test": "npm run deps:check",
     "check:test": "turbo run typecheck lint format:check knip metadata:check test:run",
     "precheck:pr": "npm run deps:check",
@@ -80,25 +85,35 @@
     "test": "vitest run",
     "test:run": "vitest run",
     "pretest:fast": "npm run build:cached",
-    "test:fast": "vitest run --project parallel",
+    "test:fast": "vitest run --project domain --project services --project adapters --project composition --project boundary --project conformance",
+    "pretest:boundary": "npm run build:cached",
+    "test:boundary": "vitest run --project boundary --project process-global",
+    "pretest:acceptance": "npm run build:cached",
+    "test:acceptance": "vitest run --project acceptance",
+    "pretest:changed": "npm run build:cached",
+    "test:changed": "vitest run --project domain --project services --project adapters --project composition --project boundary --project conformance --project evaluation --changed",
     "pretest:integration": "npm run build:cached",
-    "test:integration": "vitest run --project serial-integration",
+    "test:integration": "vitest run --project boundary --project process-global --project acceptance",
     "pretest:coverage": "npm run build:cached",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
     "test:ci": "npm run test:coverage -- --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
     "pretest:ci:shard": "npm run build:cached",
-    "test:ci:shard": "vitest run --coverage.enabled --coverage.provider=v8 --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=blob",
-    "test:ci:merge": "vitest --merge-reports --coverage.enabled --coverage.provider=v8 --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
+    "test:ci:shard": "npm run test:ci:shard:run",
+    "test:ci:shard:run": "vitest run --coverage.enabled --coverage.provider=v8 --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=blob",
+    "test:ci:merge": "vitest --merge-reports --coverage.enabled --coverage.provider=v8",
     "pretest:verbose": "npm run build:cached",
     "test:verbose": "vitest run --reporter=verbose",
     "pretest:watch": "npm run build:cached",
-    "test:watch": "vitest --project parallel --changed",
+    "test:watch": "vitest --project domain --project services --project adapters --project composition --project boundary --project conformance --project evaluation --changed",
+    "pretest:watch:all": "npm run build:cached",
+    "test:watch:all": "vitest --changed",
     "typecheck": "tsc --noEmit",
     "verify:test-temp-hygiene": "npm run build:cached && node scripts/verify-test-temp-hygiene.mjs",
     "verify:hopper": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper.mjs",
     "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
     "verify:ghidra:windows": "npm run build:cached && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs",
     "verify:browser": "npm run build:cached && node scripts/verify-real-browser.mjs",
+    "verify:inspector": "npm run build:cached && node scripts/verify-real-javascript-runtime-observation.mjs",
     "verify:javascript-runtime": "npm run build:cached && node scripts/verify-local-javascript-runtime.mjs",
     "verify:application-workflows": "npm run build:cached && node scripts/verify-local-application-workflows.mjs",
     "verify:managed": "npm run build:cached && node scripts/verify-managed-conformance.mjs",
@@ -109,6 +124,7 @@
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
     "build:ghidra-windows-fixture": "node scripts/create-ghidra-windows-fixture.mjs",
     "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs",
+    "verify:readiness": "npm run build:cached && npm run verify:fixtures && node scripts/verify-reconstruction-readiness.mjs",
     "verify:package": "npm run build:cached && node scripts/verify-package.mjs",
     "verify:package:windows": "npm run build:cached && node scripts/verify-windows-package.mjs",
     "probe:windows-capabilities": "npm run build:cached && node scripts/windows-capabilities.mjs",
@@ -118,9 +134,9 @@
     "evidence:check": "npm run build:cached && node scripts/generate-completion-ledger.mjs --check",
     "docs:api": "typedoc",
     "docs:api:cached": "turbo run docs:api",
-    "docs:generate": "npm run metadata:generate && npm run build:cached && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && npm run docs:api:cached && node scripts/generate-error-schema.mjs",
+    "docs:generate": "npm run metadata:generate && npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && npm run docs:api:cached && node scripts/generate-error-schema.mjs",
     "docs:check": "turbo run docs:check:built",
-    "docs:check:built": "node scripts/generate-package-metadata.mjs --check && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/generate-completion-ledger.mjs --check && node scripts/check-doc-facts.mjs && node scripts/generate-error-schema.mjs --check",
+    "docs:check:built": "node scripts/generate-package-metadata.mjs --check && node scripts/generate-mcp-tool-catalog.mjs --check && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/generate-completion-ledger.mjs --check && node scripts/check-doc-facts.mjs && node scripts/generate-error-schema.mjs --check",
     "docs:error-schema": "npm run build:cached && node scripts/generate-error-schema.mjs",
     "prepack": "node scripts/prepack.mjs",
     "prepare": "node scripts/prepare.mjs"
@@ -139,8 +155,8 @@
     "@electron/asar": "4.2.0",
     "@jridgewell/trace-mapping": "0.3.31",
     "@lydell/node-pty": "1.1.0",
-    "@modelcontextprotocol/server": "2.0.0-beta.4",
-    "@modelcontextprotocol/client": "2.0.0-beta.4",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.8.26",
@@ -152,6 +168,7 @@
     "incur": "0.4.13",
     "isomorphic-git": "1.38.7",
     "pino": "9.14.0",
+    "playwright-core": "1.58.2",
     "plist": "5.0.0",
     "semver": "7.8.5",
     "smol-toml": "^1.7.0",
@@ -172,8 +189,8 @@
     "lint-staged": "16.4.0",
     "oxlint": "1.73.0",
     "prettier": "3.6.2",
-    "typedoc": "0.28.20",
     "turbo": "2.10.5",
+    "typedoc": "0.28.20",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
   }

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

package/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`,
   );

package/skills/reverse-engineer-anything/SKILL.md

@@ -3,8 +3,8 @@ name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or approved runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
   version: "23"
-  tool_count: 98
-  catalog_digest: "aa413204625f3aeb62732d0f732b9b8b24832eea4520214b1e6bd204e599bcd6"
+  tool_count: 114
+  catalog_digest: "e83a177f5eca63bbad17886a61f5a1a376d44afe862c51c56e5d38339f7d41f8"
 ---
 
 # REA
@@ -23,7 +23,8 @@ Choose the first tool from the target the user supplied. Do not call
 - ASAR or extracted JavaScript/Electron tree:
   `analyze_javascript_application`.
 - Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG:
-  `inventory_artifact`.
+  `open_binary` with the supplied local path, then `inspect_artifact` or
+  `inventory_artifact` (both operate on the active target and accept no path).
 - Managed PE/CLI assembly: `inspect_managed_artifact`.
 - User-owned browser page already open: `list_browser_targets`.
 - User-owned Electron runtime already open: `list_electron_targets`.
@@ -34,6 +35,12 @@ If the app is missing, ask which app to inspect. Resolve a human-readable app
 name to one clear installed artifact when possible; ask only when matches are
 ambiguous. Never choose an example app on the user's behalf.
 
+In a target-free session, use `open_binary` to bind any archive/package or
+native target whose analysis tool operates on the active target. Do not call a
+tool hidden from `tools/list`; inspect `binary_session` with
+`detail: "capabilities"` for the exact remediation when a desired capability
+is unavailable.
+
 ## Work summary-first
 
 Start with the default summary projection. Do not repeat an identical tool call.