dsh-plugin-rea 1.0.6 → 2.0.0

package/docs/bundle-design.md

@@ -0,0 +1,186 @@
+# one-plugin bundle — design notes
+
+Goal: a fresh machine installs **one DSH plugin** and gets a working `mcp__rea__*`
+tool surface, without first installing Node, REA, a JDK, or Ghidra by hand.
+
+`main` keeps the original **config-only adapter** (a single MCP row pointing at a
+`rea` the user installed themselves). This branch adds the self-provisioning
+variant next to it. Nothing on `main` changes.
+
+---
+
+## 1. What upstream will and will not do
+
+REA is explicit: it never installs or upgrades unrelated software, and every
+dependency is "caller-supplied" (`SKILL.md`, `install.sh`, and the remediation
+strings in `dist/`). That is a deliberate upstream boundary, not an oversight.
+Consequently **all provisioning must live on our side**, and it must not pretend
+to be REA.
+
+Two upstream rules shape the runtime wiring:
+
+- Only `GHIDRA_INSTALL_DIR` + `JAVA_HOME` (and `REA_IDA_MCP_CONFIG`,
+  `HOPPER_LAUNCHER_PATH`) are ever published by `rea setup`. Every other knob —
+  `REA_ADB_PATH`, `REA_APKTOOL_COMMAND`, `REA_JADX_MCP_JAR`,
+  `REA_BROWSER_EXECUTABLE`, `REA_ILSPY_CMD_PATH` — must be supplied by the
+  launching environment. We supply them per machine from one JSON file.
+- REA hard-requires an **absolute** Node/runtime path in practice: it rejects
+  relative paths for `GHIDRA_INSTALL_DIR` and resolves Windows `java.exe` by
+  walking PATH itself. We therefore never rely on PATH at all.
+
+## 2. Verified facts this design rests on
+
+Measured on Windows 11 x64, REA 6.4.0, Ghidra 12.1.4, Temurin JDK 25.0.4:
+
+| Fact | Evidence |
+| --- | --- |
+| A row can launch REA with **no PATH `rea`** | `node <pkg>/scripts/rea.mjs mcp` answered the MCP `initialize` handshake (`serverInfo.name = rea`, version 6.4.0) and `rea doctor --json` reported 170 tools, `healthy: true` |
+| `!!js` expressions are supported in this profile layer | the existing profile patch already used one; the loader evaluates them |
+| A row-level `env:` block reaches the MCP child | `binary_session` reported `registrationEnvironment` = `GHIDRA_INSTALL_DIR`, `JAVA_HOME` |
+| No fixed home/layout is promised | the disk layout differs per install; nothing may assume one |
+| Windows is an explicit POC boundary upstream | `DoctorDiagnostics`: "the experimental Windows x64 Ghidra P0 boundary" |
+
+## 3. Architecture
+
+Three responsibilities, kept strictly apart:
+
+1. **Shim (runtime, per launch).** A tiny Node script the MCP row points at. It
+   loads the machine-local `bundle.json`, exports the discovered paths into the
+   child environment, and execs REA. It never downloads anything on the normal
+   path and never writes to the plugin directory.
+2. **Setup (provisioning, explicit or first-run).** A Node script that resolves
+   the component manifest, downloads what is missing into a cache, verifies
+   checksums, unpacks, runs the readiness probe, and writes `bundle.json`.
+   Idempotent and re-runnable; `--reuse` adopts pre-existing installs.
+3. **Patch (wiring, published).** `cordis.patch.yml` from this branch, carrying
+   **no machine path**: the row points at `<plugin>/bin/rea-shim.mjs` and the
+   shim is responsible for the rest.
+
+The published plugin therefore stays portable, while the machine-specific truth
+lives in one small JSON file under the DSH home.
+
+```
+<dsh home>/plugins/rea-bundle/
+  bundle.json          # machine-local truth: resolved paths + versions + hashes
+  mirror.json          # which plugin checkout the mirrored files came from
+  cache/               # downloaded archives (resumable, checksum-verified)
+  vendor/              # unpacked payloads (node, jdk, ghidra, apktool, jadx, adb)
+  logs/setup.log
+```
+
+## 4. Why a shim instead of an `!!js` expression
+
+`!!js` can inject values into the row at load time, but it cannot:
+download, verify, unpack, run a readiness probe, or report progress. It also
+couples the published patch to expressions that must parse on every platform.
+A shim is boring, testable, and can report an action's clear remediation text
+through `failOnStartupError: false` without breaking the harness.
+
+## 5. Control flow
+
+```
+dsh starts
+  └─ MCP row: node <bundle root>/bin/rea-shim.mjs   (setup mirrors it there)
+       ├─ bundle.json present & components verify  → exec REA (normal path)
+       ├─ missing, auto-provision allowed         → start setup detached, print
+       │                                            remediation, exit non-zero
+       └─ missing, auto-provision refused         → print exact command, exit
+```
+
+The shim resolves its bundle root from **its own location**, not from `DSH_HOME`:
+the harness strips every `DSH_*` name from an MCP child's environment, so with a
+custom `DSH_HOME` the shim would look in `~/.dsh`, find nothing, and start a second
+provisioning run there.
+
+`setup` stages, each idempotent and individually verifiable:
+
+1. `detect`  — host platform/arch, DSH home, plugin dir, existing installs
+2. `resolve` — manifest entry per component; candidate URLs are ordered
+3. `fetch`   — download to cache with resume + retries; skip if checksum matches
+4. `verify`  — sha256 against the manifest (and vendor checksum file when present)
+5. `unpack`  — platform-native extraction, atomic into `vendor/`
+6. `wire`    — write `bundle.json`, export the environment variables REA reads
+7. `mirror`  — copy the launcher to the path the published patch computes
+8. `probe`   — `rea doctor --json`, then launch the **mirrored** shim exactly as the row would
+9. `report`  — human summary + exit code; every failure names its remediation
+
+Two notes on stages that exist because their absence was a bug:
+
+- **7 (mirror).** The patch points at `<bundle root>/bin/rea-shim.mjs`, and the
+  plugin itself is not guaranteed to live anywhere the patch can compute. Setup
+  therefore copies the launcher (and the setup script it re-invokes) into the
+  bundle root. Without this, provisioning could succeed and the row would still
+  fail — and the "install the plugin first, it provisions itself" path could
+  never start, because the shim that does the provisioning would not exist at
+  the path being launched. The copy list is exactly what a mirrored run reads
+  back, **including `manifest/bundle.manifest.json`**: a mirrored `setup.mjs`
+  resolves its plugin root to the bundle root, so `loadManifest()` reads
+  `<bundle>/manifest/bundle.manifest.json` — a file only this stage can create.
+  It also writes `<bundle>/mirror.json`, naming the checkout the files came
+  from: the bundle outlives any particular checkout location, and without that
+  record a later mirrored run can only copy the bundle onto itself (provisioning
+  the manifest it was mirrored with, forever) and its remediation text would
+  point the operator at a copy that cannot start.
+- **The row's `!!js` scalar is quoted.** A bare scalar containing `? ` and `: `
+  is not one scalar: YAML reads it as an explicit key/value pair, so the loader
+  receives a mapping where an expression belongs — measured against the
+  harness's own dialect, `args[0]` became `{"[object Object]": "..."}` and the
+  row could not launch at all. Any future expression with a ternary needs the
+  quotes; `audit-manifest.mjs` rejects the bare form.
+- **3 (fetch).** Route order is deliberate and environment-dependent: direct
+  first, then the system proxy, and on Windows the .NET route ahead of both
+  because it follows the GitHub release-asset redirect that the Node routes
+  cannot. Neither "always direct" nor "always proxy" is correct — measured on
+  the development machine, the local proxy answers github.com but returns 403
+  for nodejs.org and 404 for dl.google.com, while the reverse also happens.
+
+## 6. What is genuinely impossible on Windows
+
+Declared up front so no release note over-promises. These are **upstream
+host gates**, not configuration gaps:
+
+| Capability | Gate |
+| --- | --- |
+| Hopper provider | macOS only |
+| IDA provider | requires a user-owned IDA + `REA_IDA_MCP_CONFIG`; REA never launches it |
+| firmware `binwalk` / `unblob` | Linux only |
+| Wakaru JS recovery | Linux x64 only |
+| pwntools paths (ELF layout, recorded crash) | Linux x64 only |
+| pwndbg / gdb core context | Linux/macOS |
+| `mitmdump` native capture decode | Linux only (HAR needs no engine) |
+| Apple toolchain (Mach-O, plist, asset catalog, LLDB) | macOS only |
+| process capture (`capture_process_scenario`) | Linux/macOS PTY |
+
+Everything else — native Ghidra analysis, static JS/Electron, .NET, archives,
+Android (JADX/apktool/adb), browser scenarios, EVM, HAR — is reachable on
+Windows and is what this bundle targets to complete.
+
+## 7. Component matrix (Windows x64 first)
+
+| Component | Needed for | Provisioned as |
+| --- | --- | --- |
+| Node runtime | running REA at all | reuse a compatible existing node, else portable `node.exe` |
+| `rea-agents` | the MCP server itself | vendored copy under `vendor/rea-agents` |
+| Temurin JDK 21/25 | Ghidra headless + JADX bridge | portable JDK zip (full JDK, not a JRE) |
+| Ghidra 12.1.x | native analysis | official release zip, extracted |
+| apktool | Android resource decode | `apktool.bat` + jar in one directory |
+| jadx-headless-mcp jar | Android class/method decompile | pinned 0.7.1 jar (REA validates its classes) |
+| Android platform-tools | `adb` device tools | official zip |
+| a Chromium-family browser | browser/CDP scenarios | reuse an installed Edge/Chrome; never downloaded |
+| `ilspycmd` (optional) | .NET decompilation | optional; only wired when present |
+
+Ghidra itself is **not** redistributed inside the plugin package: the release is
+~570 MB, which no npm package can carry. It is fetched from the official release
+and checksum-verified, or adopted from an existing install with `--reuse`.
+
+## 8. Honest limits of this branch
+
+- npm's per-package limits (unpacked/compressed size) rule out shipping the JDK
+  and Ghidra inside the tarball. "One plugin install" therefore means *one
+  install plus an automatic, checksum-verified fetch*, not a 600 MB npm package.
+- First run is network- and time-bound: the full payload is roughly 800 MB
+  (Ghidra 570 MB, JDK 205 MB) plus the REA package. Progress is reported and the
+  download is resumable; a pre-seeded cache makes it offline-capable.
+- Version pins age. `manifest/bundle.manifest.json` carries the pins, and
+  `check-updates.ps1` gains a bundle section so drift is reported rather than
+  discovered later.

package/manifest/bundle.manifest.json

@@ -0,0 +1,399 @@
+{
+  "$comment": [
+    "Component manifest for the one-plugin bundle. Every entry is fetched from an",
+    "official vendor source and verified before use. Fields:",
+    "  sha256   - REQUIRED for offline integrity. Vendor-published where one exists;",
+    "             otherwise measured once and recorded here, and drift is reported",
+    "             rather than silently accepted. 'unverified' means neither was done",
+    "             yet, and setup then pins the hash it observes on first fetch.",
+    "  size     - expected byte count, used for truncation checks and resume math.",
+    "  license  - license of the upstream project, not a redistribution claim.",
+    "  requires - components whose binaries this one needs to run.",
+    "  binaries - workspace-relative entries inside the unpacked directory that are",
+    "             directly spawnable; the first that exists becomes the component's",
+    "             recorded path so another component can depend on it.",
+    "Nothing here is redistributed inside the npm package; setup downloads it."
+  ],
+  "manifestVersion": 1,
+  "generatedFor": "dsh-plugin-rea one-plugin bundle",
+  "pins": {
+    "reaAgents": "6.4.0",
+    "ghidra": "12.1.4",
+    "jdk": "21",
+    "apktool": "3.0.3",
+    "jadxHeadlessMcp": "0.7.1",
+    "node": "24.21.0",
+    "nodeEngines": "^22.19.0 || ^24.11.0 || >=26.0.0"
+  },
+  "components": {
+    "node": {
+      "description": "Portable Node.js runtime used to execute vendored REA. Only provisioned when no compatible node is already reachable.",
+      "kind": "archive",
+      "license": "MIT (Node.js)",
+      "requires": [],
+      "unpack": { "stripRootComponents": 1, "moveTo": "node" },
+      "binaries": ["bin/node", "node{exe}"],
+      "probe": {
+        "argv": ["{node}", "-v"],
+        "expect": { "regex": "^v(22\\.(1[9]|[2-9][0-9])|24\\.(1[1-9]|[2-9][0-9])|2[6-9]\\.|[3-9][0-9]\\.)" },
+        "why": "REA's engines are ^22.19.0 || ^24.11.0 || >=26.0.0. A loose '^v\\d+' accepted Node 20, which then fails at REA runtime; the reuse path must reject it here."
+      },
+      "sources": {
+        "win32-x64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-win-x64.zip",
+          "format": "zip",
+          "size": 37618919,
+          "sha256": "158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-win-x64.zip)",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "Checksum and unpack verified on this machine: the extracted node.exe runs standalone (v24.21.0), no installer and no registry writes."
+        },
+        "win32-arm64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-win-arm64.zip",
+          "format": "zip",
+          "size": 33679608,
+          "sha256": "8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-win-arm64.zip), size confirmed by HEAD",
+          "sha256VerifiedOn": "2026-10-13"
+        },
+        "darwin-x64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-darwin-x64.tar.gz",
+          "format": "tar.gz",
+          "size": 54203979,
+          "sha256": "1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-darwin-x64.tar.gz)",
+          "sha256VerifiedOn": "2026-10-13"
+        },
+        "darwin-arm64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-darwin-arm64.tar.gz",
+          "format": "tar.gz",
+          "size": 52909993,
+          "sha256": "bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-darwin-arm64.tar.gz)",
+          "sha256VerifiedOn": "2026-10-13"
+        },
+        "linux-x64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-x64.tar.xz",
+          "format": "tar.xz",
+          "size": 31890184,
+          "sha256": "fd8e59d5a511510f6a298afb548f18c7d2b1be404d8b4a27d94fbe49f56cb2d6",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-linux-x64.tar.xz)",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": ".tar.xz is not unpackable by Windows Expand-Archive; bsdtar handles it. A .tar.gz twin exists for every platform if xz support is ever in doubt."
+        },
+        "linux-arm64": {
+          "version": "24.21.0",
+          "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-arm64.tar.xz",
+          "format": "tar.xz",
+          "size": 30859684,
+          "sha256": "6ad1325edbdb5649c379b75a237147a666c95d4f9ae8d340fef2d1575d289ad2",
+          "sha256Source": "https://nodejs.org/dist/v24.21.0/SHASUMS256.txt (line: node-v24.21.0-linux-arm64.tar.xz)",
+          "sha256VerifiedOn": "2026-10-13"
+        }
+      }
+    },
+    "jdk": {
+      "description": "Full JDK (not a JRE) for Ghidra headless and the JADX bridge. REA validates it with 'java --list-modules' and requires jdk.compiler.",
+      "kind": "archive",
+      "license": "GPL-2.0-with-classpath-exception (Eclipse Temurin)",
+      "requires": [],
+      "unpack": { "stripRootComponents": 1, "moveTo": "jdk" },
+      "probe": { "argv": ["{jvm}", "--list-modules"], "expect": { "contains": "jdk.compiler" } },
+      "sources": {
+        "win32-x64": {
+          "version": "21.0.12.1+1",
+          "url": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_x64_windows_hotspot_21.0.12.1_1.zip",
+          "format": "zip",
+          "size": 205073461,
+          "sha256": "f9d6e191ab098c0d416e7d588a24420a8621cd2f4720dab2459b8b7b2d2d8b4e",
+          "sha256Source": "Adoptium API /v3/assets/latest/21/hotspot (binary.package.checksum), cross-checked against the per-asset .zip.sha256.txt sidecar",
+          "sha256VerifiedOn": "2026-10-13",
+          "metaApi": "https://api.adoptium.net/v3/assets/latest/21/hotspot?architecture=x64&image_type=jdk&os=windows&vendor=eclipse",
+          "note": "Unpacked and exercised on this machine: bin/javac.exe and jmods are present, java --list-modules reports jdk.compiler, and REA's Ghidra provider accepted it as a 64-bit full JDK 21+."
+        },
+        "darwin-x64": {
+          "version": "21.0.12.1+1",
+          "url": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_x64_mac_hotspot_21.0.12.1_1.tar.gz",
+          "format": "tar.gz",
+          "size": 194316575,
+          "sha256": "44db0f08196daf19a47f90d13388b0c943b67663cb537f998fe29e836fa842ce",
+          "sha256Source": "Adoptium API (binary.package.checksum)",
+          "sha256VerifiedOn": "2026-10-13",
+          "metaApi": "https://api.adoptium.net/v3/assets/latest/21/hotspot?architecture=x64&image_type=jdk&os=mac&vendor=eclipse"
+        },
+        "darwin-arm64": {
+          "version": "21.0.12.1+1",
+          "url": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_aarch64_mac_hotspot_21.0.12.1_1.tar.gz",
+          "format": "tar.gz",
+          "size": 200073404,
+          "sha256": "3623232f33a9c3baadf304480b2535f9a3cba8a58d42ecbb438ba267315d9998",
+          "sha256Source": "Adoptium API (binary.package.checksum)",
+          "sha256VerifiedOn": "2026-10-13",
+          "metaApi": "https://api.adoptium.net/v3/assets/latest/21/hotspot?architecture=aarch64&image_type=jdk&os=mac&vendor=eclipse"
+        },
+        "linux-x64": {
+          "version": "21.0.12.1+1",
+          "url": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_x64_linux_hotspot_21.0.12.1_1.tar.gz",
+          "format": "tar.gz",
+          "size": 207473347,
+          "sha256": "ce79869e1307ed8ee1e2baa86a412b1eb5b75d10a01006d788a6f968bcfaee94",
+          "sha256Source": "Adoptium API (binary.package.checksum)",
+          "sha256VerifiedOn": "2026-10-13",
+          "metaApi": "https://api.adoptium.net/v3/assets/latest/21/hotspot?architecture=x64&image_type=jdk&os=linux&vendor=eclipse"
+        },
+        "linux-arm64": {
+          "version": "21.0.12.1+1",
+          "url": "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.12.1%2B1/OpenJDK21U-jdk_aarch64_linux_hotspot_21.0.12.1_1.tar.gz",
+          "format": "tar.gz",
+          "size": 205641175,
+          "sha256": "23e37e026f12f3e706f18938ff611db3032d075b09d0879a25d06718c773e223",
+          "sha256Source": "Adoptium API (binary.package.checksum)",
+          "sha256VerifiedOn": "2026-10-13",
+          "metaApi": "https://api.adoptium.net/v3/assets/latest/21/hotspot?architecture=aarch64&image_type=jdk&os=linux&vendor=eclipse"
+        }
+      }
+    },
+    "ghidra": {
+      "description": "Ghidra release, extracted. REA locates support/analyzeHeadless(.bat) and Features/Decompiler/os/<platform>/decompile[.exe] inside it.",
+      "kind": "archive",
+      "license": "Apache-2.0",
+      "requires": ["jdk"],
+      "unpack": { "stripRootComponents": 1, "moveTo": "ghidra" },
+      "probe": { "file": "{ghidra}/Ghidra/application.properties", "expect": { "contains": "application.version=" } },
+      "sources": {
+        "all": {
+          "version": "12.1.4",
+          "url": "https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_12.1.4_build/ghidra_12.1.4_PUBLIC_20260921.zip",
+          "format": "zip",
+          "size": 569649598,
+          "sha256": "ddac49f903da9d5bac833e5cc79395098b9c33cfd3279be5f31bd00387d2d4db",
+          "sha256Source": "GitHub release body of the pinned tag: api.github.com/repos/NationalSecurityAgency/ghidra/releases/tags/Ghidra_12.1.4_build -> .body, line '* SHA-256: `ddac49f9...`'. No checksum asset exists (six candidate names 404). Always read the pinned tag, never releases/latest, because the body changes.",
+          "releaseApi": "https://api.github.com/repos/NationalSecurityAgency/ghidra/releases/tags/Ghidra_12.1.4_build",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "No platform split for the public release: one zip serves Windows/macOS/Linux. Unpacked and sniffed here (support/analyzeHeadless.bat and the win_x86_64 native decompiler are present, and REA reported provider version 12.1.4). Windows traps: a path containing '!' or '^' breaks Ghidra, and macOS native components are not shipped (they must be built with support/gradle/gradlew buildNatives). Ghidra requires JDK 21+; application.java.max is empty at this tag, so a newer JDK is permitted."
+        }
+      }
+    },
+    "apktool": {
+      "description": "Android resource decoding. REA is pointed at the wrapper script, which must sit next to the jar.",
+      "kind": "multi-file",
+      "license": "Apache-2.0",
+      "requires": ["jdk"],
+      "entries": {
+        "all": [
+          {
+            "id": "jar",
+            "version": "3.0.3",
+            "url": "https://github.com/iBotPeaches/Apktool/releases/download/v3.0.3/apktool_3.0.3.jar",
+            "format": "file",
+            "size": 15478013,
+            "sha256": "dbf930b076c6b9be08d57c449cacefc3bdd6b71ebd59b3066fc0e1f5b14f9423",
+            "sha256Source": "Vendor-published in the 3.0.3 release post (apktool.org/blog/apktool-3.0.3/), md5 50d98c920b005d2fcdc18d3d52e3f23b. Independently reproduced here: this is the hash of the 15,478,013-byte apktool_3.0.3.jar.",
+            "sha256VerifiedOn": "2026-10-13",
+            "moveTo": "apktool",
+            "saveAs": "apktool.jar"
+          }
+        ],
+        "byPlatform": {
+          "win32-x64": [
+            {
+              "id": "wrapper",
+              "version": "master",
+              "url": "https://raw.githubusercontent.com/iBotPeaches/Apktool/master/scripts/windows/apktool.bat",
+              "format": "file",
+              "size": 2348,
+              "sha256": "9440ec9d98efdef14136f4cefd79ac200d72baa016b5991d128234a3a3ef3b43",
+              "sha256Source": "measured on 2026-10-13 (raw.githubusercontent.com publishes no checksum for the wrapper); a single 2,348-byte file, so the archive-free case needs no TOFU",
+              "sha256VerifiedOn": "2026-10-13",
+              "notes": [
+                "The wrapper pushd's to its own directory and resolves apktool.jar first, then globs apktool_*.jar, so the renamed jar next to it is found.",
+                "Its final line is `for %%i in (%cmdcmdline%) do if /i \"%%~i\"==\"/c\" pause & exit /b`: measured here it returns exit 0 in 0.2 s, but it appends 'Press any key to continue . . .' to stdout. That trailing text is upstream's, not a provisioning defect; tools that parse apktool's stdout should tolerate it.",
+                "REA is pointed at this .bat (REA_APKTOOL_COMMAND), not at the jar, exactly as the wrapper expects."
+              ],
+              "moveTo": "apktool",
+              "saveAs": "apktool.bat"
+            }
+          ],
+          "darwin-x64": [
+            {
+              "id": "wrapper",
+              "version": "master",
+              "url": "https://raw.githubusercontent.com/iBotPeaches/Apktool/master/scripts/osx/apktool",
+              "format": "file",
+              "size": 2672,
+              "sha256": "d0c86f0475ed73bfffa6ac39faa69de7aa2dd40ff5e7e6540f82002be3a38f0b",
+              "sha256Source": "measured on 2026-10-13 from the osx wrapper (the correct one for macOS; the linux script is a different file)",
+              "sha256VerifiedOn": "2026-10-13",
+              "moveTo": "apktool",
+              "saveAs": "apktool"
+            }
+          ],
+          "darwin-arm64": [
+            {
+              "id": "wrapper",
+              "version": "master",
+              "url": "https://raw.githubusercontent.com/iBotPeaches/Apktool/master/scripts/osx/apktool",
+              "format": "file",
+              "size": 2672,
+              "sha256": "d0c86f0475ed73bfffa6ac39faa69de7aa2dd40ff5e7e6540f82002be3a38f0b",
+              "sha256Source": "measured on 2026-10-13 from the osx wrapper",
+              "sha256VerifiedOn": "2026-10-13",
+              "moveTo": "apktool",
+              "saveAs": "apktool"
+            }
+          ],
+          "linux-x64": [
+            {
+              "id": "wrapper",
+              "version": "master",
+              "url": "https://raw.githubusercontent.com/iBotPeaches/Apktool/master/scripts/linux/apktool",
+              "format": "file",
+              "size": 2648,
+              "sha256": "a851371023c43ca9b9a30218f87f9fd536304283de7b85447183ae811dfd033c",
+              "sha256Source": "measured on 2026-10-13 from the linux wrapper",
+              "sha256VerifiedOn": "2026-10-13",
+              "moveTo": "apktool",
+              "saveAs": "apktool"
+            }
+          ],
+          "linux-arm64": [
+            {
+              "id": "wrapper",
+              "version": "master",
+              "url": "https://raw.githubusercontent.com/iBotPeaches/Apktool/master/scripts/linux/apktool",
+              "format": "file",
+              "size": 2648,
+              "sha256": "a851371023c43ca9b9a30218f87f9fd536304283de7b85447183ae811dfd033c",
+              "sha256Source": "measured on 2026-10-13 from the linux wrapper",
+              "sha256VerifiedOn": "2026-10-13",
+              "moveTo": "apktool",
+              "saveAs": "apktool"
+            }
+          ]
+        }
+      },
+      "probe": { "argv": ["{jvm}", "-jar", "{vendor}/apktool/apktool.jar", "--version"], "expect": { "regex": "\\d+\\.\\d+" } }
+    },
+    "jadxHeadlessMcp": {
+      "description": "REA validates this exact jar's bridge classes; it is not interchangeable with a plain jadx build.",
+      "kind": "file",
+      "license": "Apache-2.0",
+      "requires": ["jdk"],
+      "probe": { "file": "{vendor}/jadx/jadx-headless-mcp-0.7.1-all.jar" },
+      "entries": {
+        "all": [
+          {
+            "id": "jar",
+            "version": "0.7.1",
+            "url": "https://github.com/1013503897/jadx-headless-mcp/releases/download/v0.7.1/jadx-headless-mcp-0.7.1-all.jar",
+            "format": "file",
+            "size": 42619858,
+            "sha256": "6e5eacf500b64292bfb73c49797c1958f6ee44646e43e868039ae7feb573ff75",
+            "sha256Source": "Vendor-published sidecar asset releases/download/v0.7.1/jadx-headless-mcp.sha256 (98 bytes, one line); the value was independently reproduced here by hashing the downloaded 42,619,858-byte jar. 0.7.1 is the newest release and REA requires exactly this bridge build: the project's own build.gradle.kts documents that the fat jar must be shaded with duplicatesStrategy INCLUDE, otherwise only KotlinMetadataPlugin registers and every APK resolves to a single R class. Versions 0.6.0 and earlier predate that fix.",
+            "sha256VerifiedOn": "2026-10-13",
+            "moveTo": "jadx",
+            "saveAs": "jadx-headless-mcp-0.7.1-all.jar"
+          }
+        ]
+      }
+    },
+    "androidPlatformTools": {
+      "description": "adb, for REA's device tools. Optional: without a device these tools simply report no devices.",
+      "kind": "archive",
+      "license": "Android SDK Terms (Google)",
+      "requires": [],
+      "optional": true,
+      "unpack": { "stripRootComponents": 1, "moveTo": "platform-tools" },
+      "probe": { "argv": ["{vendor}/platform-tools/adb{exe}", "version"], "expect": { "contains": "Android Debug Bridge" } },
+      "sources": {
+        "win32-x64": {
+          "version": "latest (37.0.1)",
+          "url": "https://dl.google.com/android/repository/platform-tools-latest-windows.zip",
+          "format": "zip",
+          "size": 8044989,
+          "sha256": "45f4d63113e895ebde0c90f194099a4676b6ac653bd28d54314a9e022bbc1a99",
+          "sha256Source": "Google publishes no checksum for this rolling asset; measured on 2026-10-13 and the archive verified readable (15 entries incl. adb.exe). The archive's own platform-tools/source.properties reports Pkg.Revision=37.0.1, so the real pin is 'platform-tools 37.0.1'. Google's repository2-3.xml carries size+checksum for versioned archives if a vendor hash is ever required.",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "Rolling 'latest' URL pinned by observation; setup re-verifies against this value and reports drift. Android SDK components are not OSI-licensed and Google restricts redistribution, so this is fetched from Google at install time and never re-hosted. Also contains fastboot, sqlite3, mke2fs and the USB API DLLs."
+        },
+        "darwin-x64": {
+          "version": "latest",
+          "url": "https://dl.google.com/android/repository/platform-tools-latest-darwin.zip",
+          "format": "zip",
+          "size": 16110554,
+          "sha256": "ee39ad5967e95c2a07f04dbcbde96b1a0c916ba376096db5d2f498b7727a5d1d",
+          "sha256Source": "Google publishes no checksum for this rolling asset; measured on 2026-10-13 by downloading the archive and hashing it locally (16,110,554 bytes)",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "Rolling 'latest' URL pinned by observation; setup re-verifies against this value and reports drift."
+        },
+        "darwin-arm64": {
+          "version": "latest",
+          "url": "https://dl.google.com/android/repository/platform-tools-latest-darwin.zip",
+          "format": "zip",
+          "size": 16110554,
+          "sha256": "ee39ad5967e95c2a07f04dbcbde96b1a0c916ba376096db5d2f498b7727a5d1d",
+          "sha256Source": "Same darwin archive as x64 (measured 2026-10-13); it serves Intel and Apple silicon.",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "The same darwin archive serves Intel and Apple silicon."
+        },
+        "linux-x64": {
+          "version": "latest",
+          "url": "https://dl.google.com/android/repository/platform-tools-latest-linux.zip",
+          "format": "zip",
+          "size": 9054187,
+          "sha256": "d230f13842f60f782a8645f9c813f8f845bf36089ea7289f28c48f17979313f1",
+          "sha256Source": "Google publishes no checksum for this rolling asset; measured on 2026-10-13 by downloading the archive and hashing it locally (9,054,187 bytes)",
+          "sha256VerifiedOn": "2026-10-13",
+          "note": "The same linux archive serves x86-64 and arm64."
+        },
+        "linux-arm64": {
+          "version": "latest",
+          "url": "https://dl.google.com/android/repository/platform-tools-latest-linux.zip",
+          "format": "zip",
+          "size": 9054187,
+          "sha256": "d230f13842f60f782a8645f9c813f8f845bf36089ea7289f28c48f17979313f1",
+          "sha256Source": "Same linux archive as x64 (measured 2026-10-13).",
+          "sha256VerifiedOn": "2026-10-13"
+        }
+      }
+    },
+    "reaAgents": {
+      "description": "The REA MCP server itself, installed into vendor/node_modules so the bundle owns the runtime copy. The resolved entry point is vendor/node_modules/rea-agents/scripts/rea.mjs.",
+      "kind": "npm",
+      "license": "MIT",
+      "requires": ["node"],
+      "unpack": { "moveTo": "rea-agents" },
+      "probe": {
+        "argv": ["{node}", "{vendor}/node_modules/rea-agents/scripts/rea.mjs", "--version"],
+        "expect": { "regex": "^6\\.4\\.0" }
+      },
+      "sources": {
+        "npm": {
+          "version": "6.4.0",
+          "registry": "https://registry.npmjs.org/rea-agents",
+          "integrity": "npm's own dist.integrity is the authoritative check for this tarball: the registry tarball ships NO node_modules (verified: 1161 entries, 0 under node_modules), so setup resolves the dependency closure with `npm install --ignore-scripts` instead of unpacking a tarball.",
+          "note": "`just unpacking the published tarball cannot work` is a verified fact, not a caution: the CLI would fail with ERR_MODULE_NOT_FOUND on zod."
+        }
+      }
+    }
+  },
+  "notProvisionable": {
+    "$comment": "Upstream host gates. Listed so the setup report can explain an unavailable capability instead of silently omitting it.",
+    "hopper": "macOS only (HOPPER_LAUNCHER_PATH).",
+    "ida": "requires a user-owned IDA plus REA_IDA_MCP_CONFIG; REA never launches IDA.",
+    "firmware": "binwalk/unblob are Linux-only (REA_BINWALK_COMMAND / REA_UNBLOB_COMMAND).",
+    "wakaru": "Linux x64 only (REA_WAKARU_COMMAND).",
+    "pwntools": "Linux x64 only (REA_PWNTOOLS_PYTHON) — ELF layout and recorded-crash tools.",
+    "pwndbg": "Linux/macOS only (gdb + REA_PWNDBG_GDB).",
+    "mitmdump": "Linux only, native mitmproxy captures (REA_MITMDUMP_COMMAND); HAR needs no engine.",
+    "appleToolchain": "macOS only (xcrun, plutil, assetutil, hdiutil, lldb).",
+    "processCapture": "Linux/macOS PTY only.",
+    "ilspycmd": "Optional .NET decompiler (REA_ILSPY_CMD_PATH). Only wired when a runnable ilspycmd already exists; the static managed provider works without it.",
+    "browser": "Reused from the host (REA_BROWSER_EXECUTABLE). Never downloaded by this bundle."
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-rea",
-  "version": "1.0.6",
-  "description": "Registers the upstream REA MCP server into DeepSeek Harness as mcp__rea__* tools — a third-party adapter, analysis is upstream's. · 把上游 REA 的 MCP 服务接入 DeepSeek Harness，提供 mcp__rea__* 工具（第三方适配，分析能力属上游）。",
+  "version": "2.0.0",
+  "description": "One-plugin bundle: provisions Node/REA/JDK/Ghidra for you, then registers the upstream REA MCP server as mcp__rea__* tools. · 一体包：自动准备 Node/REA/JDK/Ghidra，并把上游 REA 的 MCP 服务接入 DeepSeek Harness。",
   "type": "module",
   "license": "MIT",
   "author": "czcdr",
@@ -27,8 +27,16 @@
     "ghidra",
     "binary-analysis"
   ],
+  "bin": {
+    "rea-bundle-setup": "./scripts/setup.mjs",
+    "rea-bundle-status": "./bin/rea-shim.mjs"
+  },
   "files": [
     "cordis.patch.yml",
+    "bin/",
+    "scripts/",
+    "manifest/",
+    "docs/bundle-design.md",
     "README.md",
     "README.zh-CN.md",
     "LICENSE",
@@ -44,6 +52,17 @@
     }
   },
   "scripts": {
-    "check-updates": "powershell -NoProfile -File ./check-updates.ps1"
+    "check-updates": "powershell -NoProfile -File ./check-updates.ps1",
+    "bundle:setup": "node ./scripts/setup.mjs",
+    "bundle:status": "node ./bin/rea-shim.mjs --shim-status",
+    "bundle:dry-run": "node ./scripts/setup.mjs --reuse --dry-run",
+    "bundle:audit": "node ./scripts/audit-manifest.mjs",
+    "bundle:test": "node --test ./scripts/setup.test.mjs"
+  },
+  "engines": {
+    "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
   }
 }