dsh-plugin-rea 1.0.5 → 2.0.0

package/check-updates.ps1

@@ -46,6 +46,10 @@ function Test-NodeEngines([string]$node, [string]$engines) {
   # 之后 $node.Major 为 $null，所有 ^ / ~ 分支都会判假（曾因此把 Node 24 判成不满足）。
   $v = Get-NumericVersion $node
   if (-not $v) { return $null }
+  # 只要有一个 term 的形态不认识，整个判断就只能给"无法解析"：返回 $false 会把
+  # `22.x` / `>=22` 这类合法但未实现的 pattern 误报成"不满足"，让用户去升级一个
+  # 本来就满足的 Node。
+  $recognized = $true
   foreach ($term in ($engines -split '\|\|')) {
     $t = $term.Trim()
     if ($t -match '^\^(\d+\.\d+\.\d+)$') {
@@ -56,8 +60,11 @@ function Test-NodeEngines([string]$node, [string]$engines) {
     } elseif ($t -match '^~(\d+\.\d+\.\d+)$') {
       $base = [version]$Matches[1]
       if ($v.Major -eq $base.Major -and $v.Minor -eq $base.Minor -and $v -ge $base) { return $true }
+    } else {
+      $recognized = $false
     }
   }
+  if (-not $recognized) { return $null }
   return $false
 }
 
@@ -107,8 +114,10 @@ if ($installed -and $latest) {
   } elseif ($vi -and $vl -and $vl -eq $vi -and $installed -ne $latest) {
     Warn "同版本号但通道不同：$installed → $latest（预发布/正式）"
   } else { Ok '已是最新版本' }
-} else {
+} elseif (-not $latest) {
   Warn '未能取到上游最新版本（两个 registry 都查不通？）—— 已跳过版本比对'
+} else {
+  Warn '本地没读到已安装版本（见上面那条）—— 已跳过版本比对'
 }
 
 # ------------------------------------------------------------- Node 运行时
@@ -214,6 +223,67 @@ if (Test-Path $profPatch) {
   }
 }
 
+# ------------------------------------------------- 一体包（bundle 分支）
+# 设计文档承诺了这个分区：一体包把组件版本钉在 manifest 里，供应结果记在
+# bundle.json 里。两者不一致 = 有一次 pin 更新还没重新供给，或盘上的组件被换过。
+Head '一体包供给状态（bundle 分支）'
+$pluginRoot = $PSScriptRoot
+$manifestPath = Join-Path $pluginRoot 'manifest\bundle.manifest.json'
+$bundleRoot = $env:REA_BUNDLE_ROOT
+if (-not $bundleRoot) {
+  $homeDir = $env:DSH_HOME
+  if (-not $homeDir) { $homeDir = Join-Path $HOME '.dsh' }
+  $bundleRoot = Join-Path $homeDir 'plugins\rea-bundle'
+}
+$bundleJson = Join-Path $bundleRoot 'bundle.json'
+
+if (-not (Test-Path $manifestPath)) {
+  Info '未找到 manifest/bundle.manifest.json —— 这不是一体包分支，跳过'
+} else {
+  Info "bundle 根目录: $bundleRoot"
+  try {
+    $manifest = Get-Content $manifestPath -Raw -Encoding UTF8 | ConvertFrom-Json
+    if (Test-Path $bundleJson) {
+      $state = Get-Content $bundleJson -Raw -Encoding UTF8 | ConvertFrom-Json
+      Ok "已供给：$($state.provisionedAt)"
+      $drift = 0
+      foreach ($name in $manifest.pins.PSObject.Properties.Name) {
+        if ($name -eq 'nodeEngines') { continue }
+        $pinned = [string]$manifest.pins.$name
+        $installed = ''
+        if ($state.versions -and ($state.versions.PSObject.Properties.Name -contains $name)) {
+          $installed = [string]$state.versions.$name
+        }
+        if (-not $installed) { continue }
+        # Node 的 pin 是引擎范围，不是版本号；其它组件比前缀即可
+        $same = $installed.Equals($pinned) -or $installed.StartsWith(($pinned -split '\.')[0] + '.')
+        if ($same) { Info "  $name = $installed（pin $pinned）" }
+        else { Warn "$name 盘上为 $installed，manifest 已钉 $pinned —— 重跑 setup 对齐"; $drift++ }
+      }
+      if ($drift -eq 0) { Ok '所有组件与 manifest 的 pin 一致' }
+      if ($state.unverifiedChecksums -and @($state.unverifiedChecksums).Count -gt 0) {
+        Warn ("TOFU（无厂商校验和，取首次实测值）: " + (@($state.unverifiedChecksums) -join ', '))
+      }
+      $mirrored = Join-Path $bundleRoot 'bin\rea-shim.mjs'
+      if (Test-Path $mirrored) { Ok 'MCP 行指向的 shim 已就位' }
+      else { Bad "缺少 MCP 行指向的 shim: $mirrored —— 重跑 setup --reuse" }
+      # 镜像副本的 setup 用它自己所在的位置推 plugin root，所以 manifest 必须
+      # 一起镜像。旧版镜像缺这个文件：auto-provision 会以 ENOENT 崩掉且不可见，
+      # 而且它已写下的 lock 会让重试被抑制 6 小时。
+      $mirroredManifest = Join-Path $bundleRoot 'manifest\bundle.manifest.json'
+      if (Test-Path $mirroredManifest) { Ok '镜像副本的 manifest 已就位' }
+      else { Bad "镜像副本缺少 manifest: $mirroredManifest —— 请从插件目录重跑一次 node scripts/setup.mjs（旧镜像无法自愈）" }
+    } else {
+      Warn "尚未供给：$bundleJson 不存在 —— 运行 node scripts/setup.mjs（或直接装插件，行会自行触发）"
+    }
+    $pins = @()
+    foreach ($name in $manifest.pins.PSObject.Properties.Name) {
+      if ($name -ne 'nodeEngines') { $pins += "$name=$($manifest.pins.$name)" }
+    }
+    Info ('manifest 钉子: ' + ($pins -join ', '))
+  } catch { Warn "bundle 状态解析失败: $($_.Exception.Message)" }
+}
+
 # ------------------------------------------------------------------ 汇总
 Head '结论'
 if ($actions.Count -eq 0) { Ok '无需动作：整条链路与上游保持一致' }

package/cordis.patch.yml

@@ -1,33 +1,31 @@
-# dsh-plugin-rea — REA (Reverse Engineer Anything) as native DSH tools
+# dsh-plugin-rea — one-plugin bundle
 #
-# Configuration-only bundle: no Host/Client entry files. It inserts one row of
-# the official MCP client plugin and points it at the installed `rea mcp`
-# stdio server; the model then sees mcp__rea__<tool>.
+# Registers the REA MCP server as mcp__rea__* and launches it through the
+# bundle's own shim, which reads the machine-local state written by
+# `scripts/setup.mjs` and exports exactly the variables REA reads.
 #
-# ---------------------------------------------------------------------------
-# PORTABLE BY DEFAULT — this file carries no machine-specific path.
+# PORTABLE BY CONSTRUCTION — no machine path appears in this file.
+#   * `command` is the running Node executable (`process.execPath`), so the
+#     launcher needs no PATH entry and no shim resolution by the OS.
+#   * `args[0]` is computed at boot from DSH_HOME, where setup mirrors the shim.
+#   * FORWARD SLASHES ONLY in the JS string literals below. A single-quoted YAML
+#     scalar keeps backslashes literal, and JavaScript then eats them: '\plugins'
+#     is not "\plugins" but the BEL control character, '\rea-bundle' becomes a
+#     carriage return and '\bin' a backspace, so the path is silently destroyed.
+#     Forward slashes are accepted on Windows and are correct on POSIX, so one
+#     expression serves every platform.
+#   * `path`/`require` are not in scope for a `!!js` expression (`ctx` is the
+#     loader scope), hence plain string concatenation.
+#   * No DSH_HOME (undefined/absent/empty) falls back to the SAME rule the shim
+#     and setup.mjs use — `<home>/.dsh` — never to the bare home directory.
+#     Getting this wrong is silent: setup would mirror the shim into
+#     `<home>/.dsh/plugins/rea-bundle/bin/` while the row looked for it one level
+#     up, so the row could never start on a machine that merely happened to have
+#     DSH_HOME unset.
 #
-#   Prerequisite: `rea` must be reachable from the PATH the harness sees.
-#                 (`npm i -g rea-agents` puts it there.)
-#
-#   Windows    : command: cmd.exe   args: ['/c', 'rea', 'mcp']   (as below)
-#   macOS/Linux: command: 'rea'     args: ['mcp']
-#                → see examples/cordis.patch.posix.yml
-#
-#   Analysis engines: REA reads GHIDRA_INSTALL_DIR from its environment.
-#     - Option 1 (recommended): set it as an OS-level environment variable,
-#       then start/restart the harness so the MCP child inherits it.
-#     - Option 2: put an `env:` block in the row —
-#       see examples/cordis.patch.with-env.yml.
-#     Without it, native analysis reports the engine as unavailable while every
-#     other REA capability keeps working. Static JavaScript/Electron and .NET
-#     analysis need no engine at all.
-#
-#   Only ONE row may use serverName: rea in a profile. To adapt this bundle for
-#   your machine without touching the upstream file, override `mcp-rea` from
-#   your profile's own cordis.patch.yml (id-targeted config override) — that
-#   file is never published.
-# ---------------------------------------------------------------------------
+# One row may use serverName: rea in a profile. To pin a different launch
+# command on this machine, override `mcp-rea` from the profile's own
+# cordis.patch.yml (id-targeted config override) — that file is never published.
 
 - insert:
     - id: mcp-rea
@@ -35,9 +33,19 @@
       config:
         serverName: rea
         transport: stdio
-        command: 'cmd.exe'
+        command: !!js process.execPath
         args:
-          - '/c'
-          - 'rea'
-          - 'mcp'
+          # DOUBLE-QUOTED on purpose. A bare scalar containing "? " and ": " is not
+          # one scalar at all: YAML reads `? a : b` as an explicit key/value pair,
+          # so js-yaml hands the loader a mapping instead of an expression node and
+          # args[0] becomes an object the launcher cannot use. Quoting makes the
+          # scalar unambiguous; the JS string literals inside use single quotes so
+          # they cannot collide with the YAML ones.
+          - !!js "(process.env.DSH_HOME && process.env.DSH_HOME.trim() !== '' ? process.env.DSH_HOME : (process.env.USERPROFILE || process.env.HOME || '') + '/.dsh') + '/plugins/rea-bundle/bin/rea-shim.mjs'"
+          - mcp
+        env:
+          # Only meaningful when the harness itself runs on Electron; harmless
+          # for a plain Node host. Explicit is better than relying on this
+          # variable happening to survive the child-env scrub.
+          ELECTRON_RUN_AS_NODE: '1'
         failOnStartupError: false

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.