mirror of
https://github.com/czcdr/dsh-plugin-rea.git
synced 2026-11-07 10:25:59 -10:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 czcdr
|
3138bd15c3 | ||
|
czcdr
|
83bd2c70fe | ||
|
czcdr
|
84fc9b1611 | ||
|
czcdr
|
9d86f828bf | ||
|
czcdr
|
65a2963029 | ||
|
czcdr
|
419235ad45 | ||
|
czcdr
|
30beb7f622 | ||
|
czcdr
|
9f818e1f05 | ||
|
czcdr
|
0bf5c3eee2 | ||
|
czcdr
|
8f1ea15f2a | ||
|
czcdr
|
422e4f2454 | ||
|
czcdr
|
4a6d2e0a79 | ||
|
czcdr
|
4689a53237 | ||
|
czcdr
|
b10b016a35 | ||
|
czcdr
|
727ead6a14 | ||
|
czcdr
|
f4d8910fcb | ||
|
czcdr
|
818eb082be | ||
|
czcdr
|
7aeb83ce30 |
No files matched your search
@@ -71,7 +71,12 @@ jobs:
|
||||
registry-url: 'https://registry.npmjs.org'
|
||||
|
||||
- name: npm CLI must support OIDC trusted publishing (>= 11.15.0)
|
||||
run: npm install -g npm@latest && npm --version
|
||||
# Pinned to the major that provides trusted publishing. `npm@latest` would
|
||||
# silently follow npm into a future major on release day, which is the one
|
||||
# moment a publishing pipeline should not acquire new behaviour.
|
||||
run: |
|
||||
npm install -g 'npm@^11'
|
||||
npm --version
|
||||
|
||||
- name: Publish to npm via trusted publishing
|
||||
run: npm publish --provenance --access public
|
||||
@@ -67,7 +67,16 @@ jobs:
|
||||
run: |
|
||||
python3 -m pip install --quiet --disable-pip-version-check pyyaml
|
||||
python3 - <<'PY'
|
||||
import glob, sys, yaml
|
||||
import glob, yaml
|
||||
# Every shipped row carries a `!!js` tag whose scalar the DSH loader
|
||||
# evaluates at runtime. safe_load knows nothing about it and rejects the
|
||||
# file this repository exists to ship, so register a scalar passthrough:
|
||||
# indentation, quoting and structure are still validated, which is what
|
||||
# this step is for.
|
||||
yaml.SafeLoader.add_constructor(
|
||||
'tag:yaml.org,2002:js',
|
||||
lambda loader, node: loader.construct_scalar(node),
|
||||
)
|
||||
files = ['cordis.patch.yml', 'docs/marketplace-entry.yml'] + sorted(glob.glob('examples/*.yml')) + sorted(glob.glob('.github/workflows/*.yml'))
|
||||
for f in files:
|
||||
with open(f, encoding='utf-8') as fh:
|
||||
@@ -96,6 +105,12 @@ jobs:
|
||||
run: |
|
||||
python3 - <<'PY'
|
||||
import sys, yaml
|
||||
# The row carries `!!js` scalars, which the harness evaluates at load
|
||||
# time. Register a passthrough so this step can inspect the structure.
|
||||
yaml.SafeLoader.add_constructor(
|
||||
'tag:yaml.org,2002:js',
|
||||
lambda loader, node: loader.construct_scalar(node),
|
||||
)
|
||||
doc = yaml.safe_load(open('cordis.patch.yml', encoding='utf-8'))
|
||||
row = doc[0]['insert'][0]
|
||||
assert row['id'] == 'mcp-rea', row
|
||||
@@ -104,5 +119,47 @@ jobs:
|
||||
assert cfg['serverName'] == 'rea', cfg
|
||||
assert cfg['transport'] == 'stdio', cfg
|
||||
assert 'command' in cfg and 'args' in cfg, cfg
|
||||
# A bare `? a : b` scalar is read as an explicit key/value pair, so the
|
||||
# loader receives a mapping and the row cannot launch. Keep args[0] a
|
||||
# scalar: this is the exact shape that shipped broken once.
|
||||
for i, arg in enumerate(cfg['args']):
|
||||
assert isinstance(arg, str), f'args[{i}] is not a scalar: {arg!r} — quote the !!js scalar'
|
||||
print('row ok:', cfg['command'], cfg['args'])
|
||||
PY
|
||||
|
||||
- name: The harness's own dialect still parses the row
|
||||
run: |
|
||||
# The steps above use pyyaml; this one loads the row through the same
|
||||
# library the harness uses (js-yaml) with its own !!js type, so a shape
|
||||
# that only pyyaml tolerates cannot ship.
|
||||
npm install --no-save --silent --no-audit --no-fund js-yaml@4
|
||||
node - <<'JS'
|
||||
const { readFileSync } = require('node:fs');
|
||||
const yaml = require('js-yaml');
|
||||
const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {
|
||||
kind: 'scalar',
|
||||
resolve: (data) => typeof data === 'string',
|
||||
construct: (data) => ({ __jsExpr: data }),
|
||||
});
|
||||
const doc = yaml.load(readFileSync('cordis.patch.yml', 'utf8'), { schema: yaml.JSON_SCHEMA.extend([JsExpr]) });
|
||||
const cfg = doc[0].insert[0].config;
|
||||
const args = cfg.args;
|
||||
if (typeof cfg.command !== 'object' || typeof cfg.command.__jsExpr !== 'string') throw new Error('command is not an expression node');
|
||||
if (typeof args[0] !== 'object' || typeof args[0].__jsExpr !== 'string') {
|
||||
throw new Error(`args[0] is not an expression node: ${JSON.stringify(args[0])}`);
|
||||
}
|
||||
const path = new Function('process', `return (${args[0].__jsExpr})`)({ env: { USERPROFILE: 'C:\\Users\\probe', HOME: '/home/probe' } });
|
||||
if (!path.endsWith('/.dsh/plugins/rea-bundle/bin/rea-shim.mjs')) throw new Error(`unset DSH_HOME resolves to ${path}`);
|
||||
console.log('dialect ok:', cfg.command.__jsExpr, '->', path);
|
||||
JS
|
||||
|
||||
- name: Unit tests for the pure logic
|
||||
# Probe-token substitution and root stripping broke silently during
|
||||
# development; these tests pin them. They are platform-sensitive by
|
||||
# design, which is exactly why they must run on Linux too.
|
||||
run: npm run bundle:test
|
||||
|
||||
- name: Bundle manifest audit
|
||||
# Checksum coverage, unresolved tokens, duplicate JSON keys, and the
|
||||
# patch-wiring agreement between the row, the shim and setup.mjs.
|
||||
run: npm run bundle:audit
|
||||
+133
@@ -2,6 +2,139 @@
|
||||
|
||||
本插件遵循语义化版本。版本号变化说明「配置组合」这层的变化，与 REA 自身的版本无关。
|
||||
|
||||
## 2.0.1 — 2026-10-15
|
||||
|
||||
**仅文档与版式，无行为变更。**
|
||||
|
||||
- 两份 README 的**语言行正下方**现在先说明「这是哪个版本、1.x 与 2.x 各做什么」——此前版本说明排在
|
||||
首屏那张大截图之后，npm 页面首屏看不到，容易被误判成「README 没改」；对比表与升级章节位置不变。
|
||||
- `docs/bundle-design.md` 的措辞跟上「`main` 已经是一体包线」这一事实（原先写的是「本分支新增、
|
||||
`main` 不变」）。
|
||||
- 为什么纯文档也发一个补丁版：npm 的包页渲染的是**发布进 tarball 的 README**，不重新发布就更新不了首屏。
|
||||
## 2.0.0 — 2026-10-15
|
||||
|
||||
**一体包线的首个正式版**（此前的 `2.0.0-bundle.1` / `2.0.0-bundle.2` 是它的两个预发布）。
|
||||
`main` 现在就是这一条；1.x 的纯配置适配器保留在
|
||||
[`v1` 分支](https://github.com/czcdr/dsh-plugin-rea/tree/v1)，npm 上仍可装 `[email protected]`。
|
||||
|
||||
### 🔴 从 1.x 升级：先跑一次供给，再重启
|
||||
|
||||
1.x 的行指向 PATH 上的 `rea mcp`；2.x 的行指向 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`，
|
||||
而**那个文件只有 `setup.mjs` 会创建**。所以从 1.x 升上来后直接重启会：
|
||||
|
||||
- 让该行以 `MODULE_NOT_FOUND` 退出（harness 本身不受影响 —— `failOnStartupError: false` 是刻意的），
|
||||
于是 `mcp__rea__*` 工具消失，而且**不会得到任何修复提示**：会打提示的 shim 本身还不存在；
|
||||
- 正确做法是在插件目录跑一次 `node scripts/setup.mjs`（或 `scripts\rea-bundle-bootstrap.ps1 -Reuse`），
|
||||
再重启 dsh，工具就回来了。此后每一次「状态缺失」都由 shim 自己发现并在后台补供给。
|
||||
|
||||
（如果你在 profile 的 `cordis.patch.yml` 里按 id 覆盖过 `mcp-rea`（例如钉 `cmd.exe /c rea mcp`），
|
||||
那条覆盖会继续生效，升级不影响你。）
|
||||
|
||||
### 三个致命缺陷（按旧版说明走的用户每一步都会撞上）
|
||||
|
||||
- **MCP 行里的 `!!js` 标量没有加引号。** 裸标量同时含 `? ` 与 `: ` 时，YAML 把它读成**显式键值对**，
|
||||
loader 拿到的是 mapping 而不是表达式节点。用 harness 自己的方言实测（`JSON_SCHEMA` + `app.asar` 里的
|
||||
`!!js` 类型定义），`args[0]` 变成 `{"[object Object]": "..."}` —— 这一行**从来没有可能启动**。
|
||||
现改为双引号标量，内部 JS 字符串用单引号。
|
||||
- **`DSH_HOME` 的兜底少了一层 `.dsh`。** 行回退到裸 home，而 shim、`setup.mjs`、`bootstrap.ps1` 都回退到
|
||||
`<home>/.dsh`。全归档扫描确认 **DSH 从不设置 `DSH_HOME`**（宿主进程内 0 处写入，只在 shell 工具子进程的
|
||||
执行覆盖层注入），所以这是**默认路径**而不是边缘情况：行永远指向供给不会写的位置。
|
||||
- **镜像副本缺 manifest。** 镜像后的 `setup.mjs` 用它自己所在的位置推导 plugin root，于是 `loadManifest()`
|
||||
去读 `<bundle>/manifest/bundle.manifest.json` —— 一个只有镜像步骤才能创建的文件。由 shim 触发的后台供给
|
||||
会以裸 ENOENT 崩溃；`stdio: "ignore"` 让它完全不可见，而它已写下的 lock 又让重试被抑制六小时。
|
||||
|
||||
### 🟡 一并修掉的
|
||||
|
||||
- **shim 改用自身位置定位 bundle。** MCP 子进程的环境会剥掉所有 `DSH_*`（大小写不敏感），所以自定义
|
||||
`DSH_HOME` 时旧 shim 会去 `~/.dsh` 找 `bundle.json`、报"未供给"，然后**在错位置再供给一次 800 MB**。
|
||||
`bundleRoot()` 现在返回 `<shim 所在目录>/..`，与 `DSH_HOME` 是否可见无关。
|
||||
- **新增镜像记录 `mirror.json`。** 真源运行会写下插件 checkout 的位置；镜像副本据此回到真源，插件升级后
|
||||
不会永远用旧 manifest 供给。记录失效（目录被移动/删除）时优雅回退到本地副本。
|
||||
- **空值环境变量。** `REA_BUNDLE_ROOT=""` / `DSH_HOME=""` 原先会把 root 算成 `""` 或相对路径 —— 前者
|
||||
`mkdir ''` 崩在任何日志之前，后者把 bundle 装进 cwd。现在统一 trim 后回退；`--root`/`--cache` 一律
|
||||
`path.resolve`（相对 root 会让 `bundle.json` 记下相对路径，shim 随即误判组件"已消失"并重新供给）。
|
||||
- **`fail()` 的修复命令**不再指向"存在但必然崩溃"的镜像副本；没有可信副本时给出明确指引。
|
||||
- **`check-updates.ps1`** 增加「镜像 manifest 是否就位」检查，指向上面那条升级路径。
|
||||
- **shim 的两份副本各自解析出正确的 bundle root。** 上面那条"用自身位置"只在**镜像副本**上成立：
|
||||
插件 checkout 里的那份是插件而不是 bundle，于是 `npm run bundle:status` 会在已供给的机器上报
|
||||
"未供给"，而裸跑 `node bin/rea-shim.mjs mcp` 会把约 800 MB 下载进**插件目录**。现在用
|
||||
`cordis.patch.yml`（只有 checkout 会带）区分两者：镜像副本用自身位置（MCP 子进程里读不到
|
||||
`DSH_HOME`），checkout 副本按与 setup 相同的规则解析。setup 结尾打印的 `status:` 命令也改为指向
|
||||
镜像副本，这样它对自定义 `--root` 同样成立。
|
||||
- **裸跑 shim 不再启动任何东西。** `package.json` 把这个文件暴露为 `rea-bundle-status` bin，而 npm 的 bin
|
||||
转发只能原样传参、**无法追加 flag**，于是"裸跑一个叫 status 的命令"会掉进启动路径：在已供给的机器上
|
||||
启动 REA，在未供给的机器上**开始约 800 MB 下载** —— 与这个名字承诺的正好相反。现在无参数时打印用法并
|
||||
退出（真实退出码 0），MCP 行不受影响，因为它始终显式传 `mcp`。
|
||||
- **`--dry-run` 在裸机上误报失败并退出 1。** 计划项返回 `{ planned: true }`（没有 `path`），而只有真实
|
||||
`path` 才被计入 `context.resolved`，于是每个依赖前序组件的计划项都被判成"依赖不可用"：在**裸机** —— 恰恰
|
||||
是 README 建议先跑 `--dry-run` 的那台机器 —— 整条链报 4 条 FAIL 且退出码为 1。现在计划项同样满足下游的
|
||||
`requires`。（本机 `--reuse` 会 adopt 成功，所以这个缺陷只在干净机器上可见。）
|
||||
- **`release.yml` 的 npm 自更新**由 `npm@latest` 钉到 `npm@^11`：发布当天不该让流水线获得新行为。
|
||||
- **`check-updates.ps1` 的 engines 判定**：不认识的 pattern（`22.x`、`>=22` 之类）此前返回"不满足"，误导
|
||||
用户去升级一个本来就满足的 Node；现在返回"无法解析"。三条实测：`22.x` → 无法解析、`>=99.0.0` → 不满足、
|
||||
`^24.11.0` → 满足。
|
||||
- **README 的「先装插件也可以」改为诚实描述。** 发布的行指向的镜像 shim **由 setup 创建**，所以在第一次
|
||||
供给之前该行以 `MODULE_NOT_FOUND` 退出 —— 没有任何东西能启动后台供给。首次必须手动跑一次
|
||||
`setup.mjs`，此后才由 shim 自动补供给。
|
||||
|
||||
### 🔴 真机验证（Windows 11 x64，Electron 宿主 0.2.0-rc.2）当场抓到的
|
||||
|
||||
- **bootstrap 的便携 Node 路径必崩。** `$nodeFolder` 被连续剥了两次扩展名：`node-v24.21.0-win-x64.zip`
|
||||
→ `node-v24.21`，而官方 zip 解出来的目录是 `node-v24.21.0-win-x64`。于是在**没有任何 Node 的机器**上
|
||||
—— 也就是这个脚本唯一的读者 —— 它会先成功下载（35 MiB）、校验通过、解压完成，然后抛
|
||||
`the Node zip did not contain node-v24.21`。本机有 Node，永远走不到这段分支，所以单测、审计、WSL 与
|
||||
沙箱端到端全都看不见它；真机复现（清空 PATH 模拟无 Node）一次即中。
|
||||
现在只剥一次，且解压后**接受任何真的带 `node.exe` 的目录**：已经付过下载代价的机器不该因为一次命名
|
||||
漂移而卡住。`-DryRun` 也会去认已经解压好的便携 Node（只认、不下载），这正是下面那条回归检查能
|
||||
**零下载**判定它的原因。
|
||||
|
||||
### 🟡 真机验证顺带修掉的（判据都来自仓库自身）
|
||||
|
||||
- **manifest 的 `optional: true` 被忽略。** `androidPlatformTools` 明写可选（"没有设备时这些工具只是报告
|
||||
没有设备"），而 `setup.mjs` 里 `optional` 出现 **0 次**：dl.google.com 不可达时整轮 exit 1 —— 其余组件
|
||||
都供给好了，却因为 adb 失败。现在可选组件的失败**照实报告**（`optional component(s) unavailable`），但
|
||||
不计入退出码、也不写进 `bundle.json`（shim 因此不会导出 `REA_ADB_PATH`）；被别的组件 `requires` 的组件
|
||||
永不被当作可选，免得"依赖失败却退出 0"。
|
||||
- **`--reuse` 采纳 Node 只看"文件存在"。** manifest 的 `probe.why` 明写"reuse 路径必须在这里拒绝"，但旧代码
|
||||
只做 `fileExists`：PATH 上第一个是 Node 20 的机器会把它记进 `bundle.json`，失败推迟到 REA 启动才以难读的
|
||||
形式出现。现在每个候选（`REA_BUNDLE_NODE` 与**每一个** PATH 命中）都要先过 manifest 的版本闸门；跑不起来
|
||||
的候选（Windows 上 `.cmd`/`.bat` 包装器即 EINVAL）同样拒绝，并把原因打出来。
|
||||
- **README：apktool 在 Windows 上实际不可用**（能力矩阵新增一行）——上游 `execFile` 不加 shell 直接起该命令，
|
||||
而 Windows 不能这样执行 `.bat`/`.cmd`。setup 的 apktool 探针走 `java -jar`（绕过包装器）所以报 `[ok]`，
|
||||
落差只在运行时暴露。
|
||||
- **README：Electron 宿主不能用 `dsh plugin --profile desktop …`**（CLI 硬编码拒绝 `desktop` 这个 profile 名），
|
||||
改为指向应用内插件管理器。
|
||||
|
||||
### 回归防护
|
||||
|
||||
- `audit-manifest.mjs` 新增六项，全部做过反向验证（**故意写坏 6/6 都被抓住**）：`!!js` 裸标量 mapping
|
||||
检测、`DSH_HOME` 三态（未设/空/已设）求值一致性、README 与 patch 表达式不得漂移、镜像清单必须含
|
||||
manifest、镜像清单**不得**携带 `cordis.patch.yml`（它是 shim 区分两份副本的判据，被镜像进去会让镜像
|
||||
副本退回 `DSH_HOME` 规则）、**两份 README 结构平行**（节/子节数量，双语靠手工同步）。另外把
|
||||
「`DSH_HOME`/`USERPROFILE`/`HOME` 全空 → 根路径」这个**已知无害行为**钉成 warn（此前无覆盖）：该情形下
|
||||
该行报 `MODULE_NOT_FOUND`，不写文件、不下载，harness 照常。
|
||||
- `validate.yml`：YAML 步骤注册 `!!js` 标量构造器（原先 `safe_load` 直接拒绝这个仓库要发布的行 ——
|
||||
**CI 一直是红的**）；行契约步骤断言 `args[0]` 是标量、不是 mapping；新增 `bundle:test` 与 `bundle:audit` 两步。
|
||||
- `verify-branch.ps1`：dry-run 断言改为**不带 `--reuse`**（旧写法在本机 adopt 成功时正好掩盖了上面那个
|
||||
裸机缺陷），并新增"不得出现依赖不可用"一条；它现在也检查**自己**的 BOM，因为它是被编辑得最频繁的脚本。
|
||||
- `verify-branch.ps1` 新增第 8 节：**空 PATH + 官方 zip 布局**下，bootstrap 必须认出已解压的便携 Node、
|
||||
且不得计划下载（`-DryRun`，零下载、零副作用）。反向验证：把该脚本 checkout 回 HEAD 版（双重剥离）
|
||||
→ 两条断言立刻变红（`2 CHECK(S) FAILED`／`plan: download and extract ...`）。
|
||||
- 单元测试新增四条**真的去 spawn shim**的用例（镜像布局、checkout 布局、`REA_BUNDLE_ROOT` 覆盖、裸跑只
|
||||
打印用法），并逐条做过反向验证：把 shim 改回"一律用自身位置"时 checkout 那条会红；去掉裸跑守卫时裸跑
|
||||
那条会红（后者自带桩保护，即使回退也只会跑到桩、不会下载）。
|
||||
- 单元测试里的 POSIX 退化断言加平台守卫（`EXE` 为空时 `endsWith("java")` 恒真，在 Linux 上必红；
|
||||
WSL 实测修前 12/13、修后 17/17）。
|
||||
- 单元测试新增四条（共 **21** 条；Windows 21/21、WSL 真 Linux 21/21）：`--reuse` 仍采纳兼容 Node、拒绝
|
||||
manifest 版本闸门不认的候选（用**改了正则的合成 manifest** 判定，跨平台确定，不依赖机器上恰好有什么）、
|
||||
拒绝跑不起来的候选、以及"可选组件失败不致命"。反向验证：把可选记账改回旧行为 → 那条立刻变红；把复用
|
||||
检查改回旧行为 → 另两条立刻变红；两次都确认了源码按字节复原。
|
||||
|
||||
### 升级说明
|
||||
|
||||
已部署过 `2.0.0-bundle.1` 的机器**无法自愈**（旧镜像既缺 manifest 也没有真源记录）：请从**插件目录**
|
||||
重跑一次 `node scripts/setup.mjs`。
|
||||
|
||||
## 1.0.6 — 2026-10-13
|
||||
|
||||
文档结构调整，无行为变更。
|
||||
|
||||
@@ -4,27 +4,37 @@
|
||||
|
||||
**English** · [简体中文](README.zh-CN.md)
|
||||
|
||||
> **Which version is this? 2.x — and `main` is it.** 2.x provisions the runtime itself (Node, the REA CLI, a
|
||||
> JDK, Ghidra) and then wires the row: install the plugin, run `scripts/setup.mjs` once, restart dsh.
|
||||
> **1.x** is the older configuration-only adapter — it expects `rea` on PATH and Ghidra installed by you —
|
||||
> kept on the [`v1` branch](https://github.com/czcdr/dsh-plugin-rea/tree/v1) and on npm as `[email protected]`.
|
||||
> Full comparison: [Two lines: 1.x and 2.x](#two-lines-1x-and-2x) · upgrading: [Upgrading from 1.x](#upgrading-from-1x).
|
||||
|
||||
Brings the upstream **[REA — Reverse Engineer Anything](https://github.com/morluto/rea)** MCP server into
|
||||
**DeepSeek Harness** (dsh), so its tools show up in a session as `mcp__rea__*`.
|
||||
|
||||
|
||||
|
||||
|
||||
## What this is
|
||||
|
||||
A **configuration-only Cordis bundle**. `package.json` declares `dsh.bundle.patch`, and that patch inserts
|
||||
one row of the official MCP client plugin (`@deepseek-ai/dsh-mcp-client`) pointing at the `rea mcp` stdio
|
||||
server already installed on your machine. There is no analysis code here.
|
||||
A **Cordis bundle with a provisioning layer**. `package.json` declares `dsh.bundle.patch`, and that patch
|
||||
inserts one row of the official MCP client plugin (`@deepseek-ai/dsh-mcp-client`). The row launches
|
||||
`bin/rea-shim.mjs` with the running Node executable; the shim reads the machine-local state that
|
||||
`scripts/setup.mjs` wrote and starts the REA CLI it provisioned. There is no analysis code here, and the
|
||||
published patch contains no machine path.
|
||||
|
||||
> **Third-party adapter.** This repository is not part of REA, ships none of REA's code, and is not
|
||||
> maintained by REA's authors. It composes one configuration row.
|
||||
> maintained by REA's authors. It composes one configuration row and fetches upstream's own releases.
|
||||
> Upstream: [github.com/morluto/rea](https://github.com/morluto/rea) (MIT) ·
|
||||
> [docs](https://github.com/morluto/rea#what-you-can-analyze) ·
|
||||
> [中文文档](https://github.com/morluto/rea/blob/main/README_zh.md#可以分析什么) ·
|
||||
> [rea.tools](https://rea.tools/) · npm package `rea-agents`.
|
||||
> REA's own problems go to its tracker; **this plugin's** problems go to
|
||||
> [this repository's issues](https://github.com/czcdr/dsh-plugin-rea/issues).
|
||||
|
||||
**It adds exactly two things:** the tool registration under the `mcp__rea__*` names, and a way to scope the
|
||||
engine environment (`GHIDRA_INSTALL_DIR`, …) to that MCP child process instead of the whole harness.
|
||||
**It adds exactly three things:** the tool registration under the `mcp__rea__*` names, the per-machine
|
||||
engine environment (`GHIDRA_INSTALL_DIR`, `JAVA_HOME`, `REA_ADB_PATH`, `REA_APKTOOL_COMMAND`,
|
||||
`REA_JADX_MCP_JAR`, `REA_BROWSER_EXECUTABLE`, …) scoped to that MCP child instead of the whole harness, and
|
||||
the provisioning that puts those components on disk.
|
||||
|
||||
## What it can and cannot do
|
||||
|
||||
@@ -43,73 +53,120 @@ The analysis is upstream's; this section only restates upstream's own contract s
|
||||
re-implementation, security review, migration reference. To obtain actual source code, use the legitimate
|
||||
route — the upstream repository, vendor authorisation, or the vendor's own SDK.
|
||||
|
||||
## Verified against
|
||||
**What provisioning cannot buy you.** These are upstream host gates, not settings this plugin forgot:
|
||||
|
||||
Author's machine, 2026-10-12/13:
|
||||
|
||||
| Component | Version |
|
||||
| Capability | Gate |
|
||||
|---|---|
|
||||
| REA (`rea-agents`) | **6.4.0** |
|
||||
| DeepSeek Harness | desktop runtime **0.2.0-rc.2**, with its bundled dsh CLI 0.1.7-rc.2 |
|
||||
| `@deepseek-ai/dsh-mcp-client` (row provider) | bundled by the harness; npm latest `0.0.1-rc.1` |
|
||||
| Ghidra | 12.1.4 (REA currently accepts 12.1.x) |
|
||||
| Node.js | 24.21.0 (REA engines: `^22.19.0 \|\| ^24.11.0 \|\| >=26.0.0`) |
|
||||
| Host | Windows 11 x64 |
|
||||
| Hopper provider | macOS only |
|
||||
| IDA provider | needs your own IDA and `REA_IDA_MCP_CONFIG`; REA never launches IDA |
|
||||
| firmware `binwalk` / `unblob` | Linux only |
|
||||
| Wakaru JS recovery, pwntools ELF/recorded-crash paths | Linux x64 only |
|
||||
| pwndbg / gdb core context | Linux, macOS |
|
||||
| native mitmproxy captures | Linux (`REA_MITMDUMP_COMMAND`); HAR needs no engine |
|
||||
| Apple toolchain (Mach-O, plist, asset catalog, LLDB) | macOS only |
|
||||
| `capture_process_scenario` | Linux/macOS PTY |
|
||||
| apktool (Android resource decoding) | available only when `REA_APKTOOL_COMMAND` points at something Node can **execute directly**: upstream `execFile`s that command without a shell, and Windows cannot execute a `.bat`/`.cmd` that way (EINVAL). This bundle wires the official `apktool.bat` as upstream documents, so on Windows the launcher reports no version and the capability stays unavailable; JADX (a jar) is unaffected |
|
||||
|
||||
The shipped row was exercised live: `list_documents` answered through the `cmd.exe` form, and `open_binary`
|
||||
completed with the `ghidra` provider while the engine directory came only from a profile-level override.
|
||||
## Two lines: 1.x and 2.x
|
||||
|
||||
| | **2.x** — this line, `main` | **1.x** — [`v1`](https://github.com/czcdr/dsh-plugin-rea/tree/v1) |
|
||||
|---|---|---|
|
||||
| What it is | the adapter **plus provisioning**: it prepares Node, the REA CLI, a JDK and Ghidra, then wires the row | configuration-only adapter: one MCP row pointing at a `rea` you installed yourself |
|
||||
| What you need first | nothing for the runtime — provisioning fetches what is missing (with `--reuse` it adopts an existing Ghidra/JDK instead) | Node.js on REA's engines, `npm i -g rea-agents`, and Ghidra 12.1.x for native analysis |
|
||||
| First run | run `scripts/setup.mjs` (or the bootstrap) once, then restart dsh | nothing to run |
|
||||
| The row launches | the running Node executable plus `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`, which reads that machine's state | `cmd.exe /c rea mcp` on Windows, `rea mcp` on macOS/Linux |
|
||||
| Machine state | `<DSH_HOME>/plugins/rea-bundle/` — `bundle.json`, `vendor/`, `cache/` | your own REA and Ghidra installs |
|
||||
| Install | `dsh plugin --profile <profile> add dsh-plugin-rea` (npm `latest` ≥ 2.0.0) | `… add [email protected]`, or `github:czcdr/dsh-plugin-rea#v1.0.6` |
|
||||
|
||||
Both lines ship the **same patch shape** — one `insert` row of `@deepseek-ai/dsh-mcp-client` — and offer the
|
||||
same `mcp__rea__*` surface; they differ in who prepares the runtime. Moving from 1.x to 2.x takes two
|
||||
commands: see [Upgrading from 1.x](#upgrading-from-1x).
|
||||
|
||||
## Install
|
||||
|
||||
**Prerequisites**
|
||||
**Nothing to install first.** On a bare Windows x64 machine:
|
||||
|
||||
- Node.js on a version REA accepts (`^22.19.0 || ^24.11.0 || >=26.0.0`).
|
||||
- The REA CLI installed globally: `npm i -g rea-agents`.
|
||||
- For native analysis, Ghidra **12.1.x** (Hopper / IDA are alternatives under their own licences).
|
||||
Static JavaScript/Electron and .NET analysis need no engine at all.
|
||||
```
|
||||
powershell -ExecutionPolicy Bypass -File scripts\rea-bundle-bootstrap.ps1 -Reuse
|
||||
```
|
||||
|
||||
**The plugin**
|
||||
`-Reuse` adopts a Ghidra/JDK you already have; omit it to download both (about 775 MB from the official
|
||||
releases, checksum-verified). Then install the plugin for your profile:
|
||||
|
||||
```
|
||||
dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea
|
||||
# or, from npm:
|
||||
dsh plugin --profile <profile> add dsh-plugin-rea
|
||||
# or pin this release instead of tracking npm latest:
|
||||
dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.0
|
||||
```
|
||||
|
||||
A prebuilt tarball is attached to [Releases](https://github.com/czcdr/dsh-plugin-rea/releases)
|
||||
(version-free asset name, so the link keeps resolving).
|
||||
> **On an Electron host (the DeepSeek Harness desktop app) the profile is owned by the application.**
|
||||
> `dsh plugin --profile desktop …` is refused by the CLI (`profile "desktop" is managed exclusively by
|
||||
> the Electron application`) — install or update through the in-app plugin manager instead. The CLI form
|
||||
> above is for a profile you created yourself with the CLI under another name.
|
||||
|
||||
## Configure — usually nothing
|
||||
If Node is already installed, you can skip the bootstrap and run provisioning directly:
|
||||
|
||||
The shipped row carries **no machine-specific path**:
|
||||
```
|
||||
node scripts/setup.mjs --reuse # or --dry-run to see the plan first
|
||||
```
|
||||
|
||||
- Windows: `command: cmd.exe`, `args: ['/c', 'rea', 'mcp']` — the npm shim is a `.cmd`, so a shell is
|
||||
required.
|
||||
- macOS/Linux: `command: rea`, `args: ['mcp']` — see
|
||||
[`examples/cordis.patch.posix.yml`](examples/cordis.patch.posix.yml).
|
||||
Installing the plugin **first** also works, but it takes two steps. The row resolves to
|
||||
`<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`, and that file is created by setup — so until the first
|
||||
provisioning run the row exits with `MODULE_NOT_FOUND`, and nothing is there to start a background
|
||||
provisioning (the harness itself is unaffected: `failOnStartupError: false` is deliberate). Run
|
||||
`node scripts/setup.mjs` once; from then on the shim is in place, and every later missing state is picked up
|
||||
by the shim itself, which provisions in the background.
|
||||
|
||||
The only optional piece is the analysis engine. REA reads `GHIDRA_INSTALL_DIR` from its environment, so
|
||||
either:
|
||||
## Configure — nothing
|
||||
|
||||
1. set it as an **OS-level environment variable** and (re)start the harness, or
|
||||
2. pin it for the MCP child only — see
|
||||
[`examples/cordis.patch.with-env.yml`](examples/cordis.patch.with-env.yml).
|
||||
|
||||
Either way no literal path is needed: the client hands the parent environment to the child (minus names
|
||||
that look like secrets), and the patch dialect evaluates `!!js` expressions, so
|
||||
`GHIDRA_INSTALL_DIR: !!js process.env.GHIDRA_INSTALL_DIR` also works.
|
||||
|
||||
**Keep machine-specific values out of the plugin.** Override the row from your own profile's
|
||||
`cordis.patch.yml` (id-targeted config override). That file is machine-local and never published:
|
||||
The shipped row carries **no machine path**:
|
||||
|
||||
```yaml
|
||||
- id: mcp-rea
|
||||
config:
|
||||
env:
|
||||
GHIDRA_INSTALL_DIR: '<your Ghidra 12.1.x directory>'
|
||||
- insert:
|
||||
- id: mcp-rea
|
||||
name: '@deepseek-ai/dsh-mcp-client'
|
||||
config:
|
||||
serverName: rea
|
||||
transport: stdio
|
||||
command: !!js process.execPath
|
||||
args:
|
||||
- !!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:
|
||||
ELECTRON_RUN_AS_NODE: '1'
|
||||
failOnStartupError: false
|
||||
```
|
||||
|
||||
Only one row may use `serverName: rea` in a profile.
|
||||
Three details in that row are load-bearing, and all three were bugs first:
|
||||
|
||||
- **The `!!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 (`JSON_SCHEMA` plus the `!!js` type from `app.asar`), the unquoted form made `args[0]` into `{"[object Object]": "..."}` — an object the row cannot launch with. Quoting removes the ambiguity, and the JS string literals inside then use single quotes.
|
||||
- **Forward slashes, never backslashes.** A single-quoted YAML scalar keeps `\` literal, and JavaScript then consumes it: `'\plugins'` is not a path but the BEL control character, `'\rea-bundle'` becomes a carriage return and `'\bin'` a backspace — the path is destroyed silently. Forward slashes work on Windows and on POSIX.
|
||||
- **The `DSH_HOME` fallback is `<home>/.dsh`, not `<home>`.** The shim, `setup.mjs` and `bootstrap.ps1` all resolve an unset `DSH_HOME` to `<home>/.dsh/...`; a fallback that stopped one level higher made the row point at a file provisioning never writes — invisible on any machine where `DSH_HOME` happens to be set.
|
||||
- **No `path`/`require` in a `!!js` expression**: `ctx` is the loader scope, so the DSH_HOME fallback is written as plain concatenation.
|
||||
|
||||
`npm run bundle:audit` enforces the first three: it evaluates this exact expression with `DSH_HOME` unset, empty and set, and rejects a bare scalar that YAML would read as a mapping.
|
||||
|
||||
`ELECTRON_RUN_AS_NODE` only matters if the harness itself runs on Electron; it is harmless for a plain Node host, and stating it explicitly beats relying on it surviving the child-env scrub.
|
||||
|
||||
`command` is the running Node executable and `args[0]` is computed from `DSH_HOME`, so the same patch works
|
||||
on Windows, macOS and Linux without a PATH entry. Everything machine-specific lives in
|
||||
`<DSH_HOME>/plugins/rea-bundle/bundle.json`, written by setup and readable with:
|
||||
|
||||
```
|
||||
node bin/rea-shim.mjs --shim-status # resolved paths, versions, verification state
|
||||
node bin/rea-shim.mjs --shim-print-env # the environment the MCP child will see
|
||||
```
|
||||
|
||||
Both commands answer with the same bundle whether you run them from the plugin directory (the checkout copy)
|
||||
or from `<DSH_HOME>/plugins/rea-bundle` (the mirrored copy): the checkout resolves the location by the same
|
||||
rule setup uses, while the mirror uses its own position — it cannot rely on `DSH_HOME`, which the harness
|
||||
strips from an MCP child's environment.
|
||||
|
||||
Setting `REA_BUNDLE_AUTO_PROVISION=0` disables the first-run background provisioning.
|
||||
|
||||
To pin a different launch command on this machine (for example your own globally installed `rea`), override
|
||||
the row from the profile's own `cordis.patch.yml` — that file is machine-local and never published. Only one
|
||||
row may use `serverName: rea` in a profile.
|
||||
|
||||
## Verify
|
||||
|
||||
@@ -117,30 +174,83 @@ Ask for a `mcp__rea__*` call — `binary_session` reports the engine checks
|
||||
(`configuration` / `installation` / `headless` / `native_decompiler` / `java`), all of which should be
|
||||
`ok: true`. Then `open_binary` a PE, `binary_overview`, and `procedure_pseudo_code`.
|
||||
|
||||
Provisioning itself ends with two probes: `rea doctor --json` (reported, with unmet checks named) and the
|
||||
exact shim launch the MCP row will use.
|
||||
|
||||
## Verified against
|
||||
|
||||
Author's machine, 2026-10-13 / 14:
|
||||
|
||||
| Component | Version |
|
||||
|---|---|
|
||||
| REA (`rea-agents`) | **6.4.0** (170 tools) |
|
||||
| DeepSeek Harness | desktop runtime **0.2.0-rc.2**, with its bundled dsh CLI 0.1.7-rc.2 |
|
||||
| `@deepseek-ai/dsh-mcp-client` (row provider) | bundled by the harness |
|
||||
| Ghidra | 12.1.4 |
|
||||
| JDK | Temurin 21 (provisioned) / Microsoft OpenJDK 25.0.4 (adopted) |
|
||||
| Node.js | 24.21.0 (REA engines: `^22.19.0 \|\| ^24.11.0 \|\| >=26.0.0`) |
|
||||
| Host | Windows 11 x64 (build 26200) |
|
||||
|
||||
Exercised live: a clean `setup.mjs --reuse` run reached `setup complete`; an MCP `initialize` handshake
|
||||
**through the shim with no `rea` on PATH** answered `serverInfo {name: rea, version: 6.4.0}`; and the whole
|
||||
chain ran under the real desktop host — its own Electron binary launched
|
||||
`<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs mcp`, the shim started the **vendored** REA, and a live tool
|
||||
call reported `path_source: environment` for a path only that machine's `bundle.json` knows.
|
||||
|
||||
Not exercised end to end here, and therefore not claimed: the ~775 MB JDK + Ghidra download branch (planned
|
||||
by `--dry-run`, but this machine adopted its existing installs with `--reuse`), and first runs on
|
||||
macOS/Linux.
|
||||
|
||||
## Scope and caveats
|
||||
|
||||
REA exposes 170+ tools at 6.4.0, so every session's tool list grows; the row sets
|
||||
`failOnStartupError: false` so a missing REA never blocks harness startup. Some REA tools launch processes,
|
||||
write files and access the network — DSH's permission policy applies. Analyse only artifacts you are
|
||||
authorized to inspect.
|
||||
- REA exposes 170 tools at 6.4.0, so every session's tool list grows.
|
||||
- Provisioning is honest about checksums: where a vendor publishes one it is pinned and verified; where none
|
||||
exists (jadx-headless-mcp, the apktool wrapper, Android platform-tools, the rolling "latest" URLs) the
|
||||
hash is **measured once and recorded**, and later drift is reported rather than silently accepted.
|
||||
`bundle.json` lists which components are in that state under `unverifiedChecksums`.
|
||||
- Downloads are slow on some networks (measured 0.35–0.54 MiB/s from the GitHub release CDN here, so Ghidra
|
||||
alone takes ~25–45 min). Fetching is resumable: the cache is kept and re-verified, and a killed run
|
||||
continues instead of restarting.
|
||||
- Some REA tools launch processes, write files and access the network — DSH's permission policy applies.
|
||||
Analyse only artifacts you are authorized to inspect.
|
||||
- `scripts/setup.mjs` runs `npm install` for the REA CLI with `--ignore-scripts`: the published tarball
|
||||
carries no `node_modules`, so a dependency closure must be resolved, and package lifecycle scripts are
|
||||
skipped on purpose during provisioning.
|
||||
|
||||
## Updating — two independent things, both manual
|
||||
## Updating — three independent things
|
||||
|
||||
- **This plugin** never updates itself. Installed from a plugin market? Update it **in that market**.
|
||||
Installed from a local `file:` checkout? Overwrite the directory and install it again. Updating REA below
|
||||
does **not** update this plugin, and updating this plugin does not touch REA.
|
||||
- **Upstream REA**: `npm i -g rea-agents@latest`. Its `bin` entry (`scripts/rea.mjs`) is stable across
|
||||
releases, so this needs no change here.
|
||||
- **Ghidra** is version-gated by REA (12.1.x today): update REA first, then check that it accepts a newer
|
||||
Ghidra.
|
||||
- **DeepSeek Harness**: a harness upgrade may change the MCP client's config schema — inspect the row with
|
||||
`Config.listConfigs name=@deepseek-ai/dsh-mcp-client` and adjust the field names.
|
||||
### Upgrading from 1.x
|
||||
|
||||
`check-updates.ps1` (Windows PowerShell) reports the state of all four at once, and
|
||||
`.github/workflows/validate.yml` enforces the bundle's shape — including "the shipped patch must not
|
||||
contain a machine-specific path" — in CI.
|
||||
Install 2.x, then run provisioning **once** before restarting dsh:
|
||||
|
||||
```
|
||||
node scripts/setup.mjs # or: powershell -File scripts\rea-bundle-bootstrap.ps1 -Reuse
|
||||
```
|
||||
|
||||
Why it matters: the 1.x row launched `rea mcp` from PATH, while the 2.x row launches
|
||||
`<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs` — a file only `setup.mjs` creates. Upgrade and restart
|
||||
without provisioning and that row exits with `MODULE_NOT_FOUND`: the harness stays up
|
||||
(`failOnStartupError: false` is deliberate), but the `mcp__rea__*` tools are gone and you get **no
|
||||
remediation message**, because the shim that prints one does not exist yet. After the setup run they are
|
||||
back on the next start.
|
||||
|
||||
- **This plugin** never updates itself. Installed from a market? Update it there. Installed from a `file:`
|
||||
checkout? Overwrite the directory and reinstall.
|
||||
- **Upgrading from `2.0.0-bundle.1`**: that release mirrored the shim and `setup.mjs` but not the manifest,
|
||||
and recorded nothing about the plugin checkout, so a bundle it provisioned cannot repair itself — its
|
||||
background provisioning dies on the missing manifest, invisibly, and its own lock suppresses retries for
|
||||
six hours. Re-run `node scripts/setup.mjs` **from the plugin directory** once; it re-mirrors all three
|
||||
files and writes the record that lets later runs find the checkout. `check-updates.ps1` reports this state.
|
||||
- **Provisioned components**: re-run `node scripts/setup.mjs`; it re-verifies what is on disk and only
|
||||
fetches what is missing or wrong. Pins live in `manifest/bundle.manifest.json`.
|
||||
- **Upstream REA / Ghidra**: update the pins in the manifest, then re-run setup. REA version-gates Ghidra
|
||||
(12.1.x today), so update REA first.
|
||||
|
||||
`check-updates.ps1` (Windows PowerShell) reports the state of all of these at once.
|
||||
|
||||
## License
|
||||
|
||||
MIT (this adapter). REA is MIT and owned by its authors; Ghidra is Apache-2.0 and owned by the NSA. No
|
||||
upstream code is redistributed here.
|
||||
MIT (this adapter). REA is MIT and owned by its authors; Ghidra is Apache-2.0 and owned by the NSA; Temurin
|
||||
is GPLv2+CE; Node.js is MIT; apktool, jadx-headless-mcp and Android platform-tools keep their own licences.
|
||||
**No upstream code or binary is redistributed in this package** — provisioning fetches each component from
|
||||
its official source.
|
||||
+186
-85
@@ -4,136 +4,237 @@
|
||||
|
||||
[English](README.md) · **简体中文**
|
||||
|
||||
> **这是哪个版本？2.x —— 而 `main` 就是它。** 2.x 自己准备运行时（Node、REA CLI、JDK、Ghidra）再把那一行接好：
|
||||
> 装插件 → 跑一次 `scripts/setup.mjs` → 重启 dsh。
|
||||
> **1.x** 是更早的纯配置适配器 —— 它假设 `rea` 在 PATH 上、Ghidra 由你自己装好 —— 保留在
|
||||
> [`v1` 分支](https://github.com/czcdr/dsh-plugin-rea/tree/v1)，npm 上仍是 `[email protected]`。
|
||||
> 完整对比：[两条线：1.x 与 2.x](#两条线1x-与-2x) · 升级：[从 1.x 升级](#从-1x-升级)。
|
||||
|
||||
把上游 **[REA — Reverse Engineer Anything](https://github.com/morluto/rea)** 的 MCP 服务接入
|
||||
**DeepSeek Harness**（dsh），让它的工具在会话里以 `mcp__rea__*` 出现。
|
||||
|
||||
|
||||
|
||||
|
||||
## 这是什么
|
||||
|
||||
一个**纯配置型 Cordis bundle**。`package.json` 声明 `dsh.bundle.patch`，该 patch 插入一行官方 MCP
|
||||
客户端插件（`@deepseek-ai/dsh-mcp-client`）的记录，指向你本机已安装的 `rea mcp`（stdio）服务。
|
||||
本仓库不含任何分析代码。
|
||||
一个**带供给层的 Cordis bundle**。`package.json` 声明 `dsh.bundle.patch`，该 patch 插入一行官方 MCP 客户端
|
||||
插件（`@deepseek-ai/dsh-mcp-client`）。这一行用当前运行的 Node 可执行文件启动 `bin/rea-shim.mjs`，由 shim
|
||||
读取 `scripts/setup.mjs` 写下的本机状态，再拉起它供给的 REA CLI。这里没有任何分析代码，且**发布出去的
|
||||
patch 里不含任何机器路径**。
|
||||
|
||||
> **第三方适配。** 本仓库不是 REA 项目的组成部分，不分发 REA 的任何代码，也不由 REA 作者维护；
|
||||
> 它只组合一行配置。
|
||||
> **第三方适配。** 本仓库不属于 REA，不携带 REA 的任何代码，也不由 REA 作者维护；它只组装一行配置，
|
||||
> 并从上游官方源拉取上游自己的发布物。
|
||||
> 上游：[github.com/morluto/rea](https://github.com/morluto/rea)（MIT）·
|
||||
> [文档](https://github.com/morluto/rea#what-you-can-analyze) ·
|
||||
> [中文文档](https://github.com/morluto/rea/blob/main/README_zh.md#可以分析什么) ·
|
||||
> [rea.tools](https://rea.tools/) · npm 包 `rea-agents`。
|
||||
> REA 自身的问题请提到上游；**本插件**的问题提到
|
||||
> [本仓库 Issues](https://github.com/czcdr/dsh-plugin-rea/issues)。
|
||||
> REA 自身的问题请提给上游；**本插件**的问题提到
|
||||
> [本仓库 issues](https://github.com/czcdr/dsh-plugin-rea/issues)。
|
||||
|
||||
**它只增加两件事**：把工具注册成 `mcp__rea__*`，以及让引擎环境变量（`GHIDRA_INSTALL_DIR` 等）
|
||||
只作用于这个 MCP 子进程，而不是整个 harness。
|
||||
**它只做三件事**：注册 `mcp__rea__*` 这批工具名；把每台机器各自的引擎环境
|
||||
（`GHIDRA_INSTALL_DIR`、`JAVA_HOME`、`REA_ADB_PATH`、`REA_APKTOOL_COMMAND`、`REA_JADX_MCP_JAR`、
|
||||
`REA_BROWSER_EXECUTABLE` 等）限定在那一个 MCP 子进程上、而不是整个 harness；以及把这些组件装到盘上。
|
||||
|
||||
## 能做什么、不能做什么
|
||||
|
||||
分析能力由上游提供；这里只复述上游自己的契约，避免预期错位。
|
||||
分析能力属上游，本节只是复述上游自己的契约，避免预期错位。
|
||||
|
||||
- **无法完整还原源代码。** 上游对原生二进制返回的是**伪代码与汇编**，对 Android APK 返回
|
||||
**反编译的方法**，对 JEB 单元返回**伪代码**，对 JavaScript/Electron 返回**模块及其关系**。
|
||||
上游的工具契约明确写着：伪代码是反编译器输出，**不是原始源码**，且与其他提供方的输出
|
||||
**不保证文本等价**。
|
||||
- 实践中不可恢复的内容：原始标识符命名、类型、注释、宏与模板展开、构建脚本与资源；
|
||||
优化（内联、指令重排）、去符号（strip）、混淆、加壳与 VM 保护只会让可读性更差。
|
||||
- 每条结论都自带**置信度与限制**（`observed` / `derived` / `inferred`，另有 limitations 列表）：
|
||||
请把它们当作证据使用，而不要当作「已还原的源码」。
|
||||
- 适合做：理解行为、定位实现、互操作与兼容实现、安全审计、迁移参考。
|
||||
**要拿到真正的源码，请走正规渠道**——上游代码仓库、厂商授权，或厂商自己的 SDK。
|
||||
- **它无法还原完整源码。** 原生二进制上游给的是*伪代码与汇编*，APK 是*反编译方法*，JEB 单元是*伪代码*，
|
||||
JavaScript/Electron 是*模块及其关系*。上游的工具契约明确写着伪代码"是反编译器输出，不是原始源码，
|
||||
也不与另一 provider 的输出文本等价"。
|
||||
- 实际上拿不回来的：原始标识符名、类型、注释、宏与模板展开、构建脚本与资源。优化（内联、重排）、
|
||||
符号剥离、混淆、加壳、VM 保护只会让输出更差。
|
||||
- 每个结果都带**置信度与限制**（`observed` / `derived` / `inferred`，外加一份明确的 limitations 列表）。
|
||||
请当证据读，别当还原出来的源码。
|
||||
- 适合：理解行为、定位实现、互操作与兼容重写、安全审阅、迁移参考。要拿真正的源码，走正规渠道 ——
|
||||
上游仓库、厂商授权，或厂商自己的 SDK。
|
||||
|
||||
## 实测版本
|
||||
**供给解决不了的部分。** 这些是上游的宿主门槛，不是本插件漏配了什么：
|
||||
|
||||
作者机器，2026-10-12/13：
|
||||
|
||||
| 组件 | 版本 |
|
||||
| 能力 | 门槛 |
|
||||
|---|---|
|
||||
| REA（`rea-agents`） | **6.4.0** |
|
||||
| DeepSeek Harness | 桌面运行时 **0.2.0-rc.2**，自带 dsh CLI 0.1.7-rc.2 |
|
||||
| `@deepseek-ai/dsh-mcp-client`（行提供方） | 由 harness 自带；npm 最新 `0.0.1-rc.1` |
|
||||
| Ghidra | 12.1.4（REA 当前接受 12.1.x） |
|
||||
| Node.js | 24.21.0（REA engines：`^22.19.0 \|\| ^24.11.0 \|\| >=26.0.0`） |
|
||||
| 主机 | Windows 11 x64 |
|
||||
| Hopper provider | 仅 macOS |
|
||||
| IDA provider | 需要你自己的 IDA 与 `REA_IDA_MCP_CONFIG`；REA 从不启动 IDA |
|
||||
| 固件 `binwalk` / `unblob` | 仅 Linux |
|
||||
| Wakaru JS 还原、pwntools 的 ELF/宕机转储路径 | 仅 Linux x64 |
|
||||
| pwndbg / gdb 核心上下文 | 仅 Linux、macOS |
|
||||
| 原生 mitmproxy 抓包 | 仅 Linux（`REA_MITMDUMP_COMMAND`）；HAR 不需要引擎 |
|
||||
| 苹果工具链（Mach-O、plist、资源目录、LLDB） | 仅 macOS |
|
||||
| `capture_process_scenario` | 仅 Linux/macOS 的 PTY |
|
||||
| apktool（Android 资源解码） | 仅当 `REA_APKTOOL_COMMAND` 指向 Node 能**直接执行**的文件时才可用：上游用 `execFile` 不加 shell 直接起这个命令，而 Windows 上 Node 无法直接执行 `.bat`/`.cmd`（EINVAL）。本包按上游文档接的是官方 `apktool.bat`，所以在 Windows 上它拿不到版本、该能力不可用；JADX 走 jar，不受影响 |
|
||||
|
||||
发布用的这一行**实测跑通过**：`list_documents` 在 `cmd.exe` 形式下正常应答，`open_binary` 走
|
||||
`ghidra` 提供方成功，而引擎目录仅来自本机 profile 覆盖。
|
||||
## 两条线：1.x 与 2.x
|
||||
|
||||
| | **2.x** —— 当前这条，`main` | **1.x** —— [`v1`](https://github.com/czcdr/dsh-plugin-rea/tree/v1) |
|
||||
|---|---|---|
|
||||
| 是什么 | 适配器**加供给**：自己准备 Node、REA CLI、JDK、Ghidra，再把那一行接好 | 纯配置适配器：一行 MCP 行，指向你自己装好的 `rea` |
|
||||
| 前置 | 运行时什么都不用装 —— 缺什么它去取（`--reuse` 则复用机器上已有的 Ghidra/JDK） | Node.js（满足 REA engines）、`npm i -g rea-agents`，原生分析还要 Ghidra 12.1.x |
|
||||
| 首次运行 | 先跑一次 `scripts/setup.mjs`（或引导脚本），再重启 dsh | 不用跑任何东西 |
|
||||
| 那一行启动什么 | 当前 Node 可执行文件 + `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`（由 shim 读本机状态） | Windows 上 `cmd.exe /c rea mcp`，macOS/Linux 上 `rea mcp` |
|
||||
| 机器状态 | `<DSH_HOME>/plugins/rea-bundle/` —— `bundle.json`、`vendor/`、`cache/` | 你自己的 REA 与 Ghidra 安装 |
|
||||
| 安装 | `dsh plugin --profile <profile> add dsh-plugin-rea`（npm `latest` ≥ 2.0.0） | `… add [email protected]`，或 `github:czcdr/dsh-plugin-rea#v1.0.6` |
|
||||
|
||||
两条线发布的是**同一种 patch 形态**（一条 `insert` 行，`@deepseek-ai/dsh-mcp-client`），对外也提供同一套
|
||||
`mcp__rea__*` 工具面；区别只在"谁准备运行时"。从 1.x 到 2.x 只要两条命令，见
|
||||
[从 1.x 升级](#从-1x-升级)。
|
||||
|
||||
## 安装
|
||||
|
||||
**前置条件**
|
||||
**前置什么都不用装。** 在干净的 Windows x64 机器上：
|
||||
|
||||
- Node.js 满足 REA 要求（`^22.19.0 || ^24.11.0 || >=26.0.0`）。
|
||||
- 全局安装 REA CLI：`npm i -g rea-agents`。
|
||||
- 原生分析需要 Ghidra **12.1.x**（Hopper / IDA 为替代方案，各自需授权）；
|
||||
静态 JavaScript/Electron 与 .NET 分析不需要引擎。
|
||||
```
|
||||
powershell -ExecutionPolicy Bypass -File scripts\rea-bundle-bootstrap.ps1 -Reuse
|
||||
```
|
||||
|
||||
**安装插件**
|
||||
`-Reuse` 会复用你已有的 Ghidra/JDK；去掉它则从官方发布下载两者（约 775 MB，逐个校验和验证）。然后为你的
|
||||
profile 安装插件：
|
||||
|
||||
```
|
||||
dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea
|
||||
# 或从 npm 安装：
|
||||
dsh plugin --profile <profile> add dsh-plugin-rea
|
||||
# 或钉住这个版本，而不是跟着 npm latest 走：
|
||||
dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.0
|
||||
```
|
||||
|
||||
[Releases](https://github.com/czcdr/dsh-plugin-rea/releases) 附带预构建 tarball（资产名不带版本号，
|
||||
链接不会失效）。
|
||||
> **Electron 宿主（DeepSeek Harness 桌面版）的 profile 由应用独占。** 那种机器上 `dsh plugin --profile desktop …`
|
||||
> 会被 CLI 直接拒绝（`profile "desktop" is managed exclusively by the Electron application`），请改用**应用内的
|
||||
> 插件管理器**安装/更新；上面这条 CLI 只适用于你自己用 CLI 建的非 `desktop` profile。
|
||||
|
||||
## 配置——通常什么都不用改
|
||||
如果机器上已经有 Node，可以跳过引导脚本直接供给：
|
||||
|
||||
发布出去的那一行**不含任何机器相关路径**：
|
||||
```
|
||||
node scripts/setup.mjs --reuse # 或先 --dry-run 看计划
|
||||
```
|
||||
|
||||
- Windows：`command: cmd.exe`、`args: ['/c', 'rea', 'mcp']` —— npm 的 shim 是 `.cmd`，必须经 shell。
|
||||
- macOS/Linux：`command: rea`、`args: ['mcp']` —— 见
|
||||
[`examples/cordis.patch.posix.yml`](examples/cordis.patch.posix.yml)。
|
||||
反过来**先装插件**也可以，但要分两步：发布的行指向 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`，
|
||||
而那个文件**只有 setup 会创建**——所以在第一次供给之前，该行会以 `MODULE_NOT_FOUND` 退出，也就没有
|
||||
任何东西能去启动后台供给（harness 本身不受影响：`failOnStartupError: false` 是刻意的）。先手动跑一次
|
||||
`node scripts/setup.mjs`；此后 shim 就位，之后每一次「状态缺失」都由它自己发现并在后台补供给。
|
||||
|
||||
唯一可选的是分析引擎。REA 从环境读取 `GHIDRA_INSTALL_DIR`，二选一：
|
||||
## 配置 —— 不需要
|
||||
|
||||
1. 设为**系统级环境变量**，然后重启 harness（让 MCP 子进程继承）；
|
||||
2. 只为这个 MCP 子进程指定 —— 见
|
||||
[`examples/cordis.patch.with-env.yml`](examples/cordis.patch.with-env.yml)。
|
||||
|
||||
两种方式都不需要写死路径：客户端会把父进程环境传给子进程（只剔除名字像密钥的变量），
|
||||
而补丁方言支持 `!!js` 表达式，所以 `GHIDRA_INSTALL_DIR: !!js process.env.GHIDRA_INSTALL_DIR`
|
||||
同样可用。
|
||||
|
||||
**机器相关值不要写进插件。** 用你自己的 profile `cordis.patch.yml` **按 id 覆盖**这一行即可；
|
||||
该文件只在你本机、永不随插件发布：
|
||||
发布的那一行**不含任何机器路径**：
|
||||
|
||||
```yaml
|
||||
- id: mcp-rea
|
||||
config:
|
||||
env:
|
||||
GHIDRA_INSTALL_DIR: '<你的 Ghidra 12.1.x 目录>'
|
||||
- insert:
|
||||
- id: mcp-rea
|
||||
name: '@deepseek-ai/dsh-mcp-client'
|
||||
config:
|
||||
serverName: rea
|
||||
transport: stdio
|
||||
command: !!js process.execPath
|
||||
args:
|
||||
- !!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:
|
||||
ELECTRON_RUN_AS_NODE: '1'
|
||||
failOnStartupError: false
|
||||
```
|
||||
|
||||
同一 profile 内 `serverName: rea` 只能有一条记录。
|
||||
这一行里有四个"承重"细节，而且**都先以 bug 的形式出现过**：
|
||||
|
||||
- **`!!js` 标量必须加引号。** 裸标量里同时出现 `? ` 和 `: ` 时，它就不是一个标量了：YAML 会把它读成显式键值对，于是 loader 拿到的是一个 **mapping** 而不是表达式节点。用 harness 自己的方言实测（`JSON_SCHEMA` + `app.asar` 里的 `!!js` 类型），不加引号时 `args[0]` 变成 `{"[object Object]": "..."}` —— 一个行根本无法用来启动的对象。加引号消除歧义，内部的 JS 字符串改用单引号。
|
||||
- **必须用正斜杠，不能用反斜杠。** YAML 单引号标量会保留 `\` 字面量，接着 JavaScript 会把它吃掉：`'\plugins'` 不是路径而是 BEL 控制字符，`'\rea-bundle'` 变成回车、`'\bin'` 变成退格 —— 路径被静默摧毁。正斜杠在 Windows 与 POSIX 上都成立。
|
||||
- **`DSH_HOME` 的兜底是 `<home>/.dsh`，不是 `<home>`。** shim、`setup.mjs`、`bootstrap.ps1` 三者都把未设置的 `DSH_HOME` 解析到 `<home>/.dsh/...`；兜底少这一层，行就会指向供给永远不会写的位置 —— 而在 `DSH_HOME` 恰好被设置的机器上，这个错误完全不可见。
|
||||
- **`!!js` 表达式里没有 `path`/`require`**：`ctx` 是 loader 作用域，所以 DSH_HOME 的兜底写成纯字符串拼接。
|
||||
|
||||
`npm run bundle:audit` 会把前三条钉住：它用「`DSH_HOME` 未设 / 为空 / 已设」三种情形求值这个表达式，并拒绝会被 YAML 读成 mapping 的裸标量。
|
||||
|
||||
`ELECTRON_RUN_AS_NODE` 只在 harness 本身跑在 Electron 上时才有意义；对纯 Node 宿主无害，而显式写出来胜过依赖它恰好能在子进程环境清洗中存活。
|
||||
|
||||
`command` 是当前运行的 Node 可执行文件，`args[0]` 由 `DSH_HOME` 在启动时算出，所以同一份 patch 在
|
||||
Windows、macOS、Linux 上都成立，且不依赖 PATH 上的 `rea`。所有机器相关的真相都放在
|
||||
`<DSH_HOME>/plugins/rea-bundle/bundle.json`，由 setup 写入，可随时查看：
|
||||
|
||||
```
|
||||
node bin/rea-shim.mjs --shim-status # 解析到的路径、版本、校验状态
|
||||
node bin/rea-shim.mjs --shim-print-env # MCP 子进程将看到的环境变量
|
||||
```
|
||||
|
||||
这两个命令在**插件目录**（checkout 副本）或 `<DSH_HOME>/plugins/rea-bundle`（镜像副本）里跑都给出同一
|
||||
答案：checkout 副本按与 setup 相同的规则解析供给位置，镜像副本用自身位置（因为 MCP 子进程的环境里
|
||||
`DSH_*` 会被剥掉，它不能依赖 `DSH_HOME`）。
|
||||
|
||||
设 `REA_BUNDLE_AUTO_PROVISION=0` 可关掉首次运行的后台自动供给。
|
||||
|
||||
想在本机把这一行改成别的启动命令（例如用你自己全局装的 `rea`），从 profile 自己的
|
||||
`cordis.patch.yml` 按 id 覆盖即可 —— 那个文件是机器本地的，永不发布。一个 profile 里只允许一行使用
|
||||
`serverName: rea`。
|
||||
|
||||
## 验证
|
||||
|
||||
调用任一 `mcp__rea__*` 工具：`binary_session` 会给出引擎检查项
|
||||
（configuration / installation / headless / native_decompiler / java），应全部 `ok: true`；
|
||||
随后 `open_binary` 打开一个 PE → `binary_overview` → `procedure_pseudo_code`。
|
||||
随便发一个 `mcp__rea__*` 调用 —— `binary_session` 会报引擎各项检查
|
||||
（`configuration` / `installation` / `headless` / `native_decompiler` / `java`），应当全为 `ok: true`。
|
||||
然后 `open_binary` 一个 PE、`binary_overview`、`procedure_pseudo_code`。
|
||||
|
||||
## 范围与注意
|
||||
供给本身结束时也会跑两道探针：`rea doctor --json`（如实报告，并点名未满足项），以及**与 MCP 行完全相同的
|
||||
shim 启动**。
|
||||
|
||||
REA 在 6.4.0 暴露 170+ 个工具，注入后每个会话的工具列表都会变大；行内设置
|
||||
`failOnStartupError: false`，因此 REA 缺失也不会阻塞 harness 启动。部分 REA 工具会启动进程、
|
||||
写文件、访问网络，按 DSH 的权限策略执行。请仅分析你已获得授权的目标。
|
||||
## 实测环境
|
||||
|
||||
## 更新：两件事，且都要手动
|
||||
作者机器，2026-10-13 / 14：
|
||||
|
||||
- **本插件**不会自动更新。**从插件市场安装的，就在市场里更新**；本地 `file:` 目录方式安装的，
|
||||
覆盖目录后在插件管理器里重装。下面更新 REA **不会**更新本插件，反过来也一样。
|
||||
- **上游 REA**：用 `npm i -g rea-agents@latest` 更新。它的 `bin` 入口（`scripts/rea.mjs`）
|
||||
跨版本稳定，所以本插件无需改动。
|
||||
- **Ghidra**：受 REA 版本门槛限制（当前 12.1.x），先升 REA，再确认它接受新版 Ghidra。
|
||||
- **DeepSeek Harness**：升级可能改变 MCP 客户端配置结构，用
|
||||
`Config.listConfigs name=@deepseek-ai/dsh-mcp-client` 看该行 schema 并调整字段名。
|
||||
| 组件 | 版本 |
|
||||
|---|---|
|
||||
| REA（`rea-agents`） | **6.4.0**（170 个工具） |
|
||||
| DeepSeek Harness | desktop runtime **0.2.0-rc.2**，内含 dsh CLI 0.1.7-rc.2 |
|
||||
| `@deepseek-ai/dsh-mcp-client`（行 provider） | 随 harness 打包 |
|
||||
| Ghidra | 12.1.4 |
|
||||
| JDK | Temurin 21（供给）/ Microsoft OpenJDK 25.0.4（复用） |
|
||||
| Node.js | 24.21.0（REA engines：`^22.19.0 \|\| ^24.11.0 \|\| >=26.0.0`） |
|
||||
| 宿主 | Windows 11 x64（build 26200） |
|
||||
|
||||
`check-updates.ps1`（Windows PowerShell）会把上述四项一次跑完；
|
||||
`.github/workflows/validate.yml` 在 CI 里守住 bundle 的形状（含「发布物不得含机器路径」这一条）。
|
||||
实测跑过：一次干净的 `setup.mjs --reuse` 走到 `setup complete`；一次**不经 PATH 上的 `rea`、完全经由
|
||||
shim** 的 MCP `initialize` 握手返回 `serverInfo {name: rea, version: 6.4.0}`；以及**真实桌面宿主下的完整链路** ——
|
||||
宿主自己的 Electron 二进制启动 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs mcp`，shim 拉起 **bundle 内置**
|
||||
的 REA，随后一次真实工具调用报出 `path_source: environment`，而那个路径只有该机的 `bundle.json` 知道。
|
||||
|
||||
## 许可
|
||||
本机**没有**端到端跑过、因此不做承诺的：约 775 MB 的 JDK + Ghidra 下载分支（`--dry-run` 有计划，本机用
|
||||
`--reuse` 复用了已有安装），以及 macOS/Linux 的首次运行。
|
||||
|
||||
本适配器为 MIT；REA 为 MIT，版权归其作者；Ghidra 为 Apache-2.0，版权归 NSA。
|
||||
本仓库不再分发上游代码。
|
||||
## 边界与注意事项
|
||||
|
||||
- REA 在 6.4.0 有 170 个工具，每个会话的工具列表都会变长。
|
||||
- 校验和对得起良心：厂商发布了的就固定并验证；没发布的（jadx-headless-mcp、apktool 包装脚本、
|
||||
Android platform-tools、滚动的 `latest` 地址）则**实测一次并记录**，之后若漂移是**报告**而不是默默接受。
|
||||
`bundle.json` 的 `unverifiedChecksums` 会列出处于该状态的组件。
|
||||
- 某些网络下很慢（这里实测 GitHub release CDN 只有 0.35–0.54 MiB/s，光 Ghidra 就要 25–45 分钟）。
|
||||
下载是**可续传**的：缓存保留并重新校验，被中断的一轮会继续而不是从头再来。
|
||||
- **代理**：Node 的全局 `fetch` 不读系统代理，而 .NET/PowerShell 会读。在开着 WinINET 代理的机器上，
|
||||
同一个地址 `Invoke-WebRequest` 通、Node 却 `ECONNRESET`/超时。setup 自己解析代理
|
||||
（环境变量优先，Windows 上回退读注册表）并用 CONNECT 隧道，`NO_PROXY` 也照常生效。
|
||||
- REA 的部分工具会启动进程、写文件、访问网络 —— DSH 的权限策略照常适用。只分析你有权检视的样本。
|
||||
- `scripts/setup.mjs` 为 REA CLI 跑的是带 `--ignore-scripts` 的 `npm install`：官方 tarball 不带
|
||||
`node_modules`，必须解析依赖闭包；而供给过程中**刻意跳过包的 lifecycle 脚本**。
|
||||
|
||||
## 更新 —— 三件互相独立的事
|
||||
|
||||
### 从 1.x 升级
|
||||
|
||||
装上 2.x 后，**先跑一次供给**，再重启 dsh：
|
||||
|
||||
```
|
||||
node scripts/setup.mjs # 或：powershell -File scripts\rea-bundle-bootstrap.ps1 -Reuse
|
||||
```
|
||||
|
||||
为什么必须先跑：1.x 的行从 PATH 上启动 `rea mcp`，而 2.x 的行启动
|
||||
`<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs` —— 那个文件**只有 `setup.mjs` 会创建**。升级后直接重启，
|
||||
该行会以 `MODULE_NOT_FOUND` 退出：harness 本身照常（`failOnStartupError: false` 是刻意的），但
|
||||
`mcp__rea__*` 工具会消失，而且**不会有任何修复提示** —— 会打提示的 shim 本身还不存在。跑完 setup 再启动，
|
||||
工具就回来了。
|
||||
|
||||
- **本插件**从不自更新。从市场装的就在市场更新；从 `file:` 检出的就覆盖目录重装。
|
||||
- **从 `2.0.0-bundle.1` 升级**：那一版镜像了 shim 与 `setup.mjs`，却漏了 manifest，也没有留下插件 checkout
|
||||
的记录，所以它供给出来的 bundle **无法自愈** —— 后台供给会因缺 manifest 而崩溃且完全不可见，而它自己写下的
|
||||
lock 又会让重试被抑制六小时。请**从插件目录**重跑一次 `node scripts/setup.mjs`：它会重新镜像三个文件，
|
||||
并写下让后续运行找到真源的记录。`check-updates.ps1` 会报告这个状态。
|
||||
- **供给的组件**：重跑 `node scripts/setup.mjs`，它会重新校验盘上的东西，只补缺失或不对的。
|
||||
版本钉在 `manifest/bundle.manifest.json`。
|
||||
- **上游 REA / Ghidra**：改清单里的钉子再重跑 setup。REA 对 Ghidra 有版本闸门（目前 12.1.x），
|
||||
所以先更新 REA。
|
||||
|
||||
`check-updates.ps1`（Windows PowerShell）会一次性报告以上各项的状态。
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT（本适配器）。REA 是 MIT、归其作者；Ghidra 是 Apache-2.0、归 NSA；Temurin 是 GPLv2+CE；Node.js 是
|
||||
MIT；apktool、jadx-headless-mcp、Android platform-tools 各自保留自己的许可。
|
||||
**本包不再分发任何上游代码或二进制** —— 供给过程是从各组件的官方源逐个拉取。
|
||||
@@ -11,7 +11,13 @@
|
||||
（用 pwsh 7 编辑则无此限制，但保持 BOM 对两者都安全）。
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param([string]$OutDir = (Join-Path $PSScriptRoot '.'))
|
||||
param([string]$OutDir)
|
||||
|
||||
# The documented invocation (`powershell -File .\make-screenshots.ps1`) died right here:
|
||||
# "Cannot bind argument to parameter 'Path' because it is an empty string" — $PSScriptRoot
|
||||
# is not reliably populated while parameter defaults are bound, so this script had never
|
||||
# actually regenerated a screenshot. Resolve the default in the body instead.
|
||||
if (-not $OutDir -or $OutDir.Trim() -eq '') { $OutDir = $PSScriptRoot }
|
||||
|
||||
Add-Type -AssemblyName System.Drawing
|
||||
|
||||
@@ -73,7 +79,7 @@ function Save-Png($bmp, $g, $path) { $g.Dispose(); $bmp.Save($path, [System.Draw
|
||||
# ---------------------------------------------------------------- 图 1：插件做了什么
|
||||
$r = New-Canvas; $bmp = $r[0]; $g = $r[1]
|
||||
Draw-Text $g 'dsh-plugin-rea：把 REA 接入 DeepSeek Harness' $fTitle $ink 60 46
|
||||
Draw-Text $g '第三方适配 · 自身不做逆向分析 · 只插入一条 MCP 客户端记录，并把引擎环境变量限制在该子进程内' $fSub $muted 62 98
|
||||
Draw-Text $g '第三方适配 · 自身不做逆向分析 · 自供给 Node/REA/JDK/Ghidra 后自动接好那一行' $fSub $muted 62 98
|
||||
|
||||
$rowY = 180; $boxH = 158; $boxW = 250
|
||||
Draw-Box $g 60 $rowY $boxW $boxH $([System.Drawing.Color]::White) $line
|
||||
@@ -82,16 +88,16 @@ Draw-Text $g "mcp__rea__* 工具`n（6.4.0 暴露 170+）`n工具随会话注入
|
||||
|
||||
Draw-Box $g 360 $rowY $boxW $boxH $([System.Drawing.Color]::FromArgb(255,239,246,255)) $accent
|
||||
Draw-Text $g '官方 MCP 客户端行' $fBox $accent 380 ($rowY + 18)
|
||||
Draw-Text $g "@deepseek-ai/dsh-mcp-client`nserverName = rea`ntransport = stdio`ncommand = node" $fBody $muted 380 ($rowY + 50)
|
||||
Draw-Text $g "@deepseek-ai/dsh-mcp-client`nserverName = rea / transport = stdio`ncommand = 当前 Node 可执行文件`nargs[0] = <DSH_HOME>/plugins/rea-bundle/`n bin/rea-shim.mjs" $fBody $muted 380 ($rowY + 50)
|
||||
Draw-Text $g '↑ 本插件插入的就是这一行' $fSmall $accent 360 ($rowY + $boxH + 8)
|
||||
|
||||
Draw-Box $g 660 $rowY $boxW $boxH $([System.Drawing.Color]::White) $line
|
||||
Draw-Text $g 'rea mcp（本机进程）' $fBox $ink 680 ($rowY + 18)
|
||||
Draw-Text $g "node …`n \rea-agents\scripts`n \rea.mjs mcp`nenv: GHIDRA_INSTALL_DIR`n JAVA_HOME（仅此处）" $fBody $muted 680 ($rowY + 50)
|
||||
Draw-Text $g 'rea-shim（供给后镜像到此）' $fBox $ink 680 ($rowY + 18)
|
||||
Draw-Text $g "读 bundle.json 里的本机真相`n导出 GHIDRA_INSTALL_DIR /`n JAVA_HOME / REA_*`n再拉起 bundle 内置的 REA" $fBody $muted 680 ($rowY + 50)
|
||||
|
||||
Draw-Box $g 960 $rowY $boxW $boxH $([System.Drawing.Color]::FromArgb(255,240,253,244)) $accent2
|
||||
Draw-Text $g '分析引擎' $fBox $accent2 980 ($rowY + 18)
|
||||
Draw-Text $g "Ghidra 12.1.4（本机已装）`nHopper / IDA（可选，`n各自需授权）`n静态 JS / .NET 无需引擎" $fBody $muted 980 ($rowY + 50)
|
||||
Draw-Text $g '分析引擎（供给或复用）' $fBox $accent2 980 ($rowY + 18)
|
||||
Draw-Text $g "Ghidra 12.1.x / JDK 21：`n缺则下载并校验，`n已有则 --reuse 复用`n静态 JS / .NET 无需引擎" $fBody $muted 980 ($rowY + 50)
|
||||
|
||||
Draw-Arrow $g 310 ($rowY + 40) 358 ($rowY + 40) $muted
|
||||
Draw-Arrow $g 610 ($rowY + 40) 658 ($rowY + 40) $muted
|
||||
@@ -106,7 +112,7 @@ Draw-Line $g 358 446 150 446 $muted
|
||||
Draw-Arrow $g 150 446 150 342 $muted
|
||||
|
||||
Draw-Text $g '上游 REA（MIT）：github.com/morluto/rea 本插件：github.com/czcdr/dsh-plugin-rea' $fSmall $muted 60 620
|
||||
Draw-Text $g '实测 REA 6.4.0 + DSH 桌面运行时 0.2.0-rc.2 + Ghidra 12.1.4 + Node 24.21.0（Windows 11 x64，2026-10-12）' $fSmall $muted 60 646
|
||||
Draw-Text $g '实测 REA 6.4.0 + DSH 桌面运行时 0.2.0-rc.2 + Ghidra 12.1.4 + Node 24.21.0（Windows 11 x64，2026-10-14）' $fSmall $muted 60 646
|
||||
Draw-Text $g 'Ghidra 为 Apache-2.0（NSA）；REA 为 MIT。本仓库不分发上游代码。' $fSmall $muted 60 672
|
||||
Save-Png $bmp $g (Join-Path $OutDir 'screenshot-1.png')
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 67 KiB |
@@ -0,0 +1,356 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* rea-shim — the process the DSH MCP row launches.
|
||||
*
|
||||
* Why this exists: the published `cordis.patch.yml` must carry no machine path,
|
||||
* yet REA needs absolute paths for every dependency. The shim is the seam: it
|
||||
* reads one machine-local JSON file, exports exactly the variables REA reads,
|
||||
* and execs the vendored REA CLI with the arguments the row was given.
|
||||
*
|
||||
* It downloads nothing, writes nothing, and never touches PATH.
|
||||
*
|
||||
* Exit codes: 0 child exited normally * child's own status
|
||||
* 78 EX_CONFIG bundle not provisioned (or unusable) — the row has
|
||||
* `failOnStartupError: false`, so the harness stays up
|
||||
* and the message is the operator's remediation.
|
||||
*/
|
||||
import { spawn } from "node:child_process";
|
||||
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { homedir } from "node:os";
|
||||
import path from "node:path";
|
||||
import process from "node:process";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const EX_CONFIG = 78;
|
||||
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = path.resolve(HERE, "..");
|
||||
|
||||
/** DSH home, by the same rule setup.mjs and the published patch use. */
|
||||
function dshHome() {
|
||||
const fromEnv = process.env.DSH_HOME;
|
||||
if (fromEnv && fromEnv.trim() !== "") return path.resolve(fromEnv);
|
||||
return path.join(homedir(), ".dsh");
|
||||
}
|
||||
|
||||
/**
|
||||
* Where setup writes the machine-local truth.
|
||||
*
|
||||
* Two copies of this file exist and they need different answers, so the copy has
|
||||
* to be identified before the root can be:
|
||||
*
|
||||
* * The **mirrored** copy at `<bundle>/bin/rea-shim.mjs` is what the published
|
||||
* row launches, and its own location is the bundle root. It must not consult
|
||||
* DSH_HOME: the harness strips every `DSH_*` name from an MCP child's
|
||||
* environment (case-insensitively, because Windows is), so a custom DSH_HOME
|
||||
* would send it to `~/.dsh`, where it would report "not provisioned" for a
|
||||
* bundle sitting right next to it — and start a second ~800 MB run there.
|
||||
* * The **checkout** copy (`<plugin>/bin/rea-shim.mjs`) is what a human runs, e.g.
|
||||
* `npm run bundle:status`, from a shell where DSH_HOME *is* visible. Its own
|
||||
* directory is the plugin, not the bundle, so resolving to itself would report
|
||||
* "not provisioned" on a fully provisioned machine — and a bare
|
||||
* `node bin/rea-shim.mjs mcp` would provision ~800 MB into the checkout.
|
||||
*
|
||||
* Only the checkout ships `cordis.patch.yml`, so that file is the discriminator.
|
||||
* REA_BUNDLE_ROOT stays as an explicit override for tests and unusual layouts.
|
||||
*/
|
||||
function bundleRoot() {
|
||||
const override = process.env.REA_BUNDLE_ROOT;
|
||||
if (override && override.trim() !== "") return path.resolve(override);
|
||||
if (!existsSync(path.join(PLUGIN_ROOT, "cordis.patch.yml"))) return PLUGIN_ROOT;
|
||||
return path.join(dshHome(), "plugins", "rea-bundle");
|
||||
}
|
||||
|
||||
/**
|
||||
* A directory can provision only when it holds both files a run reads: the script
|
||||
* and the manifest it loads at startup. A bundle provisioned before the manifest
|
||||
* was mirrored has the script but not the manifest, so recommending that copy
|
||||
* would send the operator straight into an ENOENT.
|
||||
*/
|
||||
function usableSetup(dir) {
|
||||
if (typeof dir !== "string" || dir.trim() === "") return null;
|
||||
const base = path.resolve(dir);
|
||||
const script = path.join(base, "scripts", "setup.mjs");
|
||||
const manifest = path.join(base, "manifest", "bundle.manifest.json");
|
||||
return existsSync(script) && existsSync(manifest) ? script : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Which setup.mjs to run.
|
||||
*
|
||||
* The mirrored copy is a snapshot: after a plugin upgrade it still holds the
|
||||
* previous manifest, so it would provision the previous versions forever. setup
|
||||
* writes <bundle>/mirror.json naming the real checkout; prefer that while it is
|
||||
* usable, and fall back to the local copy — which is also all a first run has.
|
||||
*/
|
||||
function provisioningScript(root) {
|
||||
try {
|
||||
const record = JSON.parse(readFileSync(path.join(root, "mirror.json"), "utf8"));
|
||||
const recorded = usableSetup(record && record.pluginRoot);
|
||||
if (recorded) return recorded;
|
||||
} catch {
|
||||
/* no record, or not readable: the local copy is the only option */
|
||||
}
|
||||
return usableSetup(PLUGIN_ROOT);
|
||||
}
|
||||
|
||||
/**
|
||||
* On first run there is nothing to launch. Provisioning is a long download, so
|
||||
* it is started detached: the harness may kill this row (or the whole session)
|
||||
* long before 800 MB arrive, and the downloader is resumable and idempotent, so
|
||||
* a killed attempt is simply continued on the next start.
|
||||
*
|
||||
* Set REA_BUNDLE_AUTO_PROVISION=0 to require an explicit `setup.mjs` run.
|
||||
* Returns the log path when a run was started, otherwise null.
|
||||
*/
|
||||
function maybeAutoProvision(root) {
|
||||
if (process.env.REA_BUNDLE_AUTO_PROVISION === "0") return null;
|
||||
const setupScript = provisioningScript(root);
|
||||
if (!setupScript) return null;
|
||||
const lock = path.join(root, "setup.lock");
|
||||
const logPath = path.join(root, "logs", "setup.log");
|
||||
if (existsSync(lock)) {
|
||||
// A crashed run must not wedge provisioning forever: honour the lock only
|
||||
// while it is fresh; setup removes it itself when it finishes cleanly.
|
||||
let age = Infinity;
|
||||
try {
|
||||
age = Date.now() - Number(readFileSync(lock, "utf8").trim() || 0);
|
||||
} catch {
|
||||
age = Infinity;
|
||||
}
|
||||
if (Number.isFinite(age) && age < 6 * 60 * 60 * 1000) return logPath;
|
||||
}
|
||||
try {
|
||||
mkdirSync(path.join(root, "logs"), { recursive: true });
|
||||
// Exclusive create: check-then-write is not atomic, so two rows starting at
|
||||
// once could both decide to provision. EEXIST means another run owns it.
|
||||
writeFileSync(lock, String(Date.now()), { flag: "wx" });
|
||||
} catch (error) {
|
||||
if (error?.code === "EEXIST") return logPath;
|
||||
/* a read-only bundle root must never break the harness */
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
const child = spawn(process.execPath, [setupScript, "--root", root], {
|
||||
detached: true,
|
||||
stdio: "ignore",
|
||||
windowsHide: true,
|
||||
});
|
||||
child.unref();
|
||||
return logPath;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function fail(message, detail) {
|
||||
const lines = [
|
||||
"",
|
||||
" dsh-plugin-rea (bundle): REA is not provisioned on this machine.",
|
||||
"",
|
||||
" " + message,
|
||||
];
|
||||
if (detail) lines.push("", " detail: " + detail);
|
||||
// Point at the real checkout when the record allows it: running the mirrored
|
||||
// copy is fine, but it can only ever provision the manifest it was mirrored
|
||||
// with — and a bundle mirrored before the manifest travelled with it has no
|
||||
// usable copy at all, so the honest answer is then "run the plugin's own script".
|
||||
const setupScript = provisioningScript(bundleRoot());
|
||||
lines.push(
|
||||
"",
|
||||
" Finish setup with:",
|
||||
setupScript
|
||||
? " node \"" + setupScript + "\""
|
||||
: " node \"<installed plugin directory>/scripts/setup.mjs\"",
|
||||
);
|
||||
if (!setupScript) {
|
||||
lines.push("", " (Run it from the installed plugin directory: the copy in this bundle has no manifest.)");
|
||||
}
|
||||
lines.push(
|
||||
"",
|
||||
" Then restart DSH (or reload the profile) so the MCP row reconnects.",
|
||||
"",
|
||||
" The harness keeps running: this row declares failOnStartupError: false.",
|
||||
"",
|
||||
);
|
||||
process.stderr.write(lines.join("\n"));
|
||||
return EX_CONFIG;
|
||||
}
|
||||
|
||||
function readBundleConfig(root) {
|
||||
const file = path.join(root, "bundle.json");
|
||||
if (!existsSync(file)) return { ok: false, code: "missing", file };
|
||||
let parsed;
|
||||
try {
|
||||
parsed = JSON.parse(readFileSync(file, "utf8"));
|
||||
} catch (error) {
|
||||
return { ok: false, code: "malformed", file, detail: String(error && error.message) };
|
||||
}
|
||||
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
|
||||
return { ok: false, code: "malformed", file, detail: "bundle.json is not an object" };
|
||||
}
|
||||
return { ok: true, file, config: parsed };
|
||||
}
|
||||
|
||||
/** Resolve the vendored REA entry, or report precisely what is missing. */
|
||||
function resolveRea(config, root) {
|
||||
const paths = config.paths ?? {};
|
||||
const node = paths.node;
|
||||
const reaEntry = paths.reaEntry
|
||||
?? path.join(root, "vendor", "rea-agents", "scripts", "rea.mjs");
|
||||
|
||||
if (typeof node !== "string" || node.trim() === "") {
|
||||
return { ok: false, reason: "bundle.json has no paths.node" };
|
||||
}
|
||||
if (!existsSync(node)) {
|
||||
return { ok: false, reason: `the recorded Node runtime is gone: ${node}` };
|
||||
}
|
||||
if (!existsSync(reaEntry)) {
|
||||
return { ok: false, reason: `the vendored REA CLI is gone: ${reaEntry}` };
|
||||
}
|
||||
return { ok: true, node, reaEntry };
|
||||
}
|
||||
|
||||
/**
|
||||
* Export only what REA actually reads, and only when the bundle recorded it.
|
||||
* An absent variable is better than a wrong one: REA then reports its own
|
||||
* availability with its own remediation text.
|
||||
*/
|
||||
function childEnvironment(config) {
|
||||
const env = { ...process.env };
|
||||
const paths = config.paths ?? {};
|
||||
|
||||
const set = (name, value) => {
|
||||
if (typeof value === "string" && value.trim() !== "") env[name] = value;
|
||||
};
|
||||
|
||||
// Analysis engines.
|
||||
set("GHIDRA_INSTALL_DIR", paths.ghidra);
|
||||
set("JAVA_HOME", paths.jdk);
|
||||
// Optional providers/tools; wired only when the bundle provisioned them.
|
||||
set("REA_ADB_PATH", paths.adb);
|
||||
set("REA_APKTOOL_COMMAND", paths.apktoolCommand);
|
||||
set("REA_JADX_MCP_JAR", paths.jadxJar);
|
||||
set("REA_BROWSER_EXECUTABLE", paths.browser);
|
||||
set("REA_ILSPY_CMD_PATH", paths.ilspycmd);
|
||||
|
||||
// Keep the vendored Node first for any grandchild the bridge may spawn.
|
||||
if (typeof paths.node === "string" && paths.node.trim() !== "") {
|
||||
const nodeDir = path.dirname(paths.node);
|
||||
const current = env.PATH ?? "";
|
||||
const parts = current.split(path.delimiter).filter((part) => part !== "");
|
||||
if (!parts.some((part) => path.resolve(part) === path.resolve(nodeDir))) {
|
||||
env.PATH = [nodeDir, ...parts].join(path.delimiter);
|
||||
}
|
||||
}
|
||||
return env;
|
||||
}
|
||||
|
||||
/**
|
||||
* Usage text, also what a bare invocation prints.
|
||||
*
|
||||
* `package.json` exposes this file as the `rea-bundle-status` bin, and npm's bin
|
||||
* shim can only forward the arguments a user typed — it cannot append a flag. So a
|
||||
* bare `rea-bundle-status`, which is exactly what that name invites, used to fall
|
||||
* through to the launch path: it started REA, and on an unprovisioned machine it
|
||||
* began an ~800 MB download. Reporting usage instead makes the command's behaviour
|
||||
* match its name, and the row is unaffected because it always passes `mcp`.
|
||||
*/
|
||||
function usage() {
|
||||
return [
|
||||
"rea-shim: launches the vendored REA MCP server for a DSH MCP row.",
|
||||
"",
|
||||
" node bin/rea-shim.mjs [rea arguments...] (normal use: 'mcp')",
|
||||
" node bin/rea-shim.mjs --shim-status provisioning status, no launch",
|
||||
" node bin/rea-shim.mjs --shim-print-env the environment it would export",
|
||||
"",
|
||||
` bundle root: ${bundleRoot()}`,
|
||||
` plugin root: ${PLUGIN_ROOT}`,
|
||||
"",
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
function main() {
|
||||
const argv = process.argv.slice(2);
|
||||
|
||||
if (argv.includes("--shim-help") || argv.length === 0) {
|
||||
process.stdout.write(usage());
|
||||
return 0;
|
||||
}
|
||||
|
||||
const root = bundleRoot();
|
||||
const loaded = readBundleConfig(root);
|
||||
|
||||
if (argv.includes("--shim-status")) {
|
||||
const report = {
|
||||
bundleRoot: root,
|
||||
bundleFile: loaded.file,
|
||||
provisioned: loaded.ok,
|
||||
reason: loaded.ok ? undefined : loaded.code,
|
||||
autoProvision: process.env.REA_BUNDLE_AUTO_PROVISION ?? "(default)",
|
||||
};
|
||||
if (loaded.ok) {
|
||||
report.paths = loaded.config.paths ?? {};
|
||||
report.versions = loaded.config.versions ?? {};
|
||||
report.rea = resolveRea(loaded.config, root);
|
||||
}
|
||||
process.stdout.write(JSON.stringify(report, null, 2) + "\n");
|
||||
return loaded.ok ? 0 : EX_CONFIG;
|
||||
}
|
||||
|
||||
if (!loaded.ok) {
|
||||
const message =
|
||||
loaded.code === "missing"
|
||||
? `No bundle state at ${loaded.file}.`
|
||||
: `Bundle state at ${loaded.file} could not be parsed.`;
|
||||
const logPath = loaded.code === "missing" ? maybeAutoProvision(root) : null;
|
||||
if (logPath) {
|
||||
process.stderr.write(
|
||||
`\n dsh-plugin-rea (bundle): first run — provisioning started in the background.\n progress: ${logPath}\n`,
|
||||
);
|
||||
}
|
||||
return fail(message, loaded.detail);
|
||||
}
|
||||
|
||||
const rea = resolveRea(loaded.config, root);
|
||||
if (!rea.ok) return fail(rea.reason);
|
||||
|
||||
const env = childEnvironment(loaded.config);
|
||||
if (argv.includes("--shim-print-env")) {
|
||||
const interesting = Object.fromEntries(
|
||||
Object.entries(env).filter(([key]) =>
|
||||
/^(GHIDRA_INSTALL_DIR|JAVA_HOME|REA_[A-Z0-9_]+|PATH)$/.test(key),
|
||||
),
|
||||
);
|
||||
process.stdout.write(JSON.stringify(interesting, null, 2) + "\n");
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Pass through whatever the row supplied; 'mcp' in the normal case.
|
||||
const childArgs = [rea.reaEntry, ...(argv.length > 0 ? argv : ["mcp"])];
|
||||
const child = spawn(rea.node, childArgs, {
|
||||
env,
|
||||
stdio: "inherit",
|
||||
windowsHide: true,
|
||||
});
|
||||
|
||||
child.on("error", (error) => {
|
||||
process.stderr.write(
|
||||
`rea-shim: could not start ${rea.node}\n ${String(error && error.message)}\n`,
|
||||
);
|
||||
process.exit(EX_CONFIG);
|
||||
});
|
||||
child.on("exit", (code, signal) => {
|
||||
if (signal) {
|
||||
// Re-raising the signal is not portable: process.kill(pid, "SIGTERM")
|
||||
// throws ERR_UNKNOWN_SIGNAL on Windows. Report the conventional 128+n
|
||||
// status instead, which the harness reads the same way.
|
||||
const signals = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
|
||||
process.exit(128 + (signals[signal] ?? 0));
|
||||
}
|
||||
process.exit(code ?? 0);
|
||||
});
|
||||
return null;
|
||||
}
|
||||
|
||||
const status = main();
|
||||
if (typeof status === "number") process.exit(status);
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -216,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 '无需动作：整条链路与上游保持一致' }
|
||||
|
||||
+39
-31
@@ -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
|
||||
@@ -0,0 +1,187 @@
|
||||
# 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` **is** this variant: the self-provisioning one-plugin bundle. The earlier
|
||||
**config-only adapter** (a single MCP row pointing at a `rea` the user installed
|
||||
themselves) is preserved on the [`v1` branch](https://github.com/czcdr/dsh-plugin-rea/tree/v1)
|
||||
and on npm as `[email protected]`; nothing here changes that line.
|
||||
|
||||
---
|
||||
|
||||
## 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` on `main`, 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 approach
|
||||
|
||||
- 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.
|
||||
@@ -10,7 +10,7 @@
|
||||
# - 一个 PR 最多 3 条。
|
||||
#
|
||||
# 若已发布 Release tarball，可取消下面 tarball 行的注释（资产名必须不带版本号）。
|
||||
# 本仓库的 Release 一直附带 dsh-plugin-rea.tgz（当前 v1.0.5），故该行保持启用。
|
||||
# 本仓库的 Release 一直附带 dsh-plugin-rea.tgz（资产名不带版本号，永远指向最新 Release），故该行保持启用。
|
||||
# 注意：脚本里 npm 映射优先于 tarball（installTargetFor：有 npm 名就走 npm），
|
||||
# 所以这行只是 npm 不可用时的兜底，不会改变市场默认的安装方式。
|
||||
|
||||
@@ -18,6 +18,6 @@ url: https://github.com/czcdr/dsh-plugin-rea
|
||||
name: czcdr/dsh-plugin-rea
|
||||
category: tools
|
||||
description:
|
||||
en: 'Third-party adapter that registers the upstream REA (Reverse Engineer Anything) MCP server into DeepSeek Harness as mcp__rea__* tools. REA itself analyses native binaries (Hopper/Ghidra/IDA), JavaScript/Electron apps, .NET assemblies, websites, Android APKs and adb devices, firmware, and process captures.'
|
||||
zh: '第三方适配插件：把上游 REA（逆向一切，github.com/morluto/rea）的 MCP 服务注册进 DeepSeek Harness，提供 mcp__rea__* 工具。逆向分析能力由 REA 提供，覆盖原生二进制（Hopper/Ghidra/IDA）、JavaScript/Electron 应用、.NET 程序集、网站、Android APK 与 adb 设备、固件与进程捕获。'
|
||||
en: 'Third-party adapter that registers the upstream REA (Reverse Engineer Anything) MCP server into DeepSeek Harness as mcp__rea__* tools. 2.x provisions its own runtime (Node, the REA CLI, a JDK, Ghidra) under <DSH_HOME>/plugins/rea-bundle and launches REA through a shim, so a machine with nothing pre-installed works after one setup run; 1.x (branch v1, npm 1.0.6) is configuration-only and expects REA and Ghidra to be installed already. Analysis is upstream''s: native binaries (Hopper/Ghidra/IDA), JavaScript/Electron apps, .NET assemblies, websites, Android APKs and adb devices, firmware, and process captures.'
|
||||
zh: '第三方适配插件：把上游 REA（逆向一切，github.com/morluto/rea）的 MCP 服务接入 DeepSeek Harness，提供 mcp__rea__* 工具。2.x 自带供给：把 Node、REA CLI、JDK、Ghidra 装到 <DSH_HOME>/plugins/rea-bundle 下，再经 shim 启动 REA —— 干净机器跑一次 setup 即可用；1.x（v1 分支 / npm 1.0.6）是纯配置适配器，需要你自己装好 REA 与 Ghidra。逆向分析能力由 REA 提供，覆盖原生二进制（Hopper/Ghidra/IDA）、JavaScript/Electron 应用、.NET 程序集、网站、Android APK 与 adb 设备、固件与进程捕获。'
|
||||
tarball: https://github.com/czcdr/dsh-plugin-rea/releases/latest/download/dsh-plugin-rea.tgz
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
+22
-3
@@ -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.1",
|
||||
"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/"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,445 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* manifest audit — validate the component manifest before it is published.
|
||||
*
|
||||
* JSON.parse cannot see duplicate keys (the last one silently wins), and this
|
||||
* manifest is long enough that a duplicated field is easy to introduce while
|
||||
* editing. So the checks are:
|
||||
*
|
||||
* 1. duplicate object keys inside any single object (parse-level)
|
||||
* 2. every fetch entry has a sha256 that is either 64-hex or the literal
|
||||
* "unverified", never a placeholder or an invented value
|
||||
* 3. every fetch entry declares a size, except formats where the vendor does
|
||||
* not publish one
|
||||
* 4. every platform we claim to support has every entry it needs
|
||||
* 5. the apktool wrapper for a platform is the right script (the osx wrapper
|
||||
* is not the linux one) and jar+wrapper both land in the same directory
|
||||
* 6. every probe token is one the substitution step actually understands
|
||||
* 7. `requires` names refer to real components and cannot form a cycle
|
||||
*
|
||||
* Exit code 0 = clean, 1 = findings. Also usable as `npm run bundle:audit`.
|
||||
*/
|
||||
import { readFileSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
import process from "node:process";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
const MANIFEST = path.join(HERE, "..", "manifest", "bundle.manifest.json");
|
||||
const raw = readFileSync(MANIFEST, "utf8");
|
||||
|
||||
const findings = [];
|
||||
const add = (severity, where, message) => findings.push({ severity, where, message });
|
||||
|
||||
/* -------------------------------------------------- 1. duplicate object keys */
|
||||
|
||||
/** Walk the raw text and report any key that appears twice in one object. */
|
||||
function findDuplicateKeys(text) {
|
||||
const duplicates = [];
|
||||
const stack = [];
|
||||
let i = 0;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (ch === "{") {
|
||||
stack.push(new Set());
|
||||
i += 1;
|
||||
continue;
|
||||
}
|
||||
if (ch === "}") {
|
||||
stack.pop();
|
||||
i += 1;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"') {
|
||||
const start = i;
|
||||
i += 1;
|
||||
while (i < text.length) {
|
||||
if (text[i] === "\\") i += 2;
|
||||
else if (text[i] === '"') break;
|
||||
else i += 1;
|
||||
}
|
||||
const key = text.slice(start + 1, i);
|
||||
i += 1;
|
||||
// A key is followed by ':' after optional whitespace.
|
||||
let j = i;
|
||||
while (j < text.length && /\s/.test(text[j])) j += 1;
|
||||
if (text[j] === ":" && stack.length > 0) {
|
||||
const frame = stack[stack.length - 1];
|
||||
if (frame.has(key)) duplicates.push({ key, index: start });
|
||||
frame.add(key);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
i += 1;
|
||||
}
|
||||
return duplicates;
|
||||
}
|
||||
|
||||
const duplicates = findDuplicateKeys(raw);
|
||||
if (duplicates.length > 0) {
|
||||
const lineOf = (index) => raw.slice(0, index).split("\n").length;
|
||||
for (const duplicate of duplicates) {
|
||||
add("error", `line ${lineOf(duplicate.index)}`, `duplicate object key "${duplicate.key}" — JSON.parse silently keeps only the last one`);
|
||||
}
|
||||
}
|
||||
|
||||
let manifest;
|
||||
try {
|
||||
manifest = JSON.parse(raw);
|
||||
} catch (error) {
|
||||
add("error", "manifest", `not valid JSON: ${String(error.message)}`);
|
||||
}
|
||||
|
||||
if (manifest) {
|
||||
/* ------------------------------------------- 2/3. every fetch entry is sound */
|
||||
|
||||
const HEX64 = /^[0-9a-f]{64}$/;
|
||||
const fetchEntries = [];
|
||||
for (const [componentName, component] of Object.entries(manifest.components ?? {})) {
|
||||
if (component.sources) {
|
||||
for (const [key, source] of Object.entries(component.sources)) {
|
||||
if (key === "npm") continue;
|
||||
fetchEntries.push({ where: `${componentName}.sources.${key}`, entry: source });
|
||||
}
|
||||
}
|
||||
if (component.entries) {
|
||||
for (const [key, list] of Object.entries(component.entries)) {
|
||||
if (key === "byPlatform") {
|
||||
for (const [platform, platformList] of Object.entries(list)) {
|
||||
for (const [index, entry] of platformList.entries()) {
|
||||
fetchEntries.push({ where: `${componentName}.entries.byPlatform.${platform}[${index}]`, entry });
|
||||
}
|
||||
}
|
||||
} else {
|
||||
for (const [index, entry] of list.entries()) {
|
||||
fetchEntries.push({ where: `${componentName}.entries.${key}[${index}]`, entry });
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const { where, entry } of fetchEntries) {
|
||||
const sha = entry.sha256;
|
||||
if (sha === undefined) {
|
||||
add("error", where, "has no sha256 field");
|
||||
} else if (sha !== "unverified" && !HEX64.test(sha)) {
|
||||
add("error", where, `sha256 is neither 64 lowercase hex nor "unverified": ${JSON.stringify(sha)}`);
|
||||
}
|
||||
if (entry.size === undefined && entry.format !== "npm") {
|
||||
add("warn", where, "has no size, so a truncated transfer cannot be detected by length");
|
||||
}
|
||||
if (!entry.url) add("error", where, "has no url");
|
||||
if (entry.url && /localhost|127\.0\.0\.1/.test(entry.url)) add("error", where, "url points at loopback");
|
||||
if (entry.sha256 === "unverified" && !entry.sha256Source) {
|
||||
add("warn", where, "is unverified but does not say why");
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------- 4. platform coverage */
|
||||
|
||||
const DECLARED_PLATFORMS = ["win32-x64", "darwin-x64", "darwin-arm64", "linux-x64", "linux-arm64"];
|
||||
for (const [name, component] of Object.entries(manifest.components ?? {})) {
|
||||
if (!component.sources) continue;
|
||||
// An `all` source is platform-independent and an npm source has no platform
|
||||
// at all; neither is expected to enumerate every platform.
|
||||
if (component.sources.all || component.kind === "npm" || component.sources.npm) continue;
|
||||
for (const platform of DECLARED_PLATFORMS) {
|
||||
if (!component.sources[platform]) {
|
||||
add("error", `${name}.sources`, `no source for declared platform ${platform}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------- 5. apktool wrapper mapping is not crossed */
|
||||
|
||||
const apktool = manifest.components?.apktool;
|
||||
if (apktool?.entries?.byPlatform) {
|
||||
const byPlatform = apktool.entries.byPlatform;
|
||||
const jarDirectory = apktool.entries.all?.[0]?.moveTo;
|
||||
for (const [platform, list] of Object.entries(byPlatform)) {
|
||||
for (const entry of list) {
|
||||
const wantsWindows = platform.startsWith("win32");
|
||||
const wantsOsx = platform.startsWith("darwin");
|
||||
if (wantsWindows && !entry.url.includes("/windows/")) {
|
||||
add("error", `apktool.entries.byPlatform.${platform}`, `expects the windows wrapper but points at ${entry.url}`);
|
||||
}
|
||||
if (wantsOsx && !entry.url.includes("/osx/")) {
|
||||
add("error", `apktool.entries.byPlatform.${platform}`, `macOS must use scripts/osx/apktool, not ${entry.url}`);
|
||||
}
|
||||
if (platform.startsWith("linux") && !entry.url.includes("/linux/")) {
|
||||
add("error", `apktool.entries.byPlatform.${platform}`, `expects the linux wrapper but points at ${entry.url}`);
|
||||
}
|
||||
if (entry.moveTo !== jarDirectory) {
|
||||
add("error", `apktool.entries.byPlatform.${platform}`, `wrapper lands in ${entry.moveTo} but the jar lands in ${jarDirectory}; the wrapper resolves the jar next to itself`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------- 6. probe tokens */
|
||||
|
||||
const KNOWN_TOKENS = ["{root}", "{vendor}", "{vendorDir}", "{node}", "{jdk}", "{jvm}", "{javahome}", "{ghidra}", "{exe}"];
|
||||
const probes = [];
|
||||
for (const [name, component] of Object.entries(manifest.components ?? {})) {
|
||||
if (component.probe?.argv) for (const value of component.probe.argv) probes.push({ where: `${name}.probe`, value });
|
||||
if (component.probe?.file) probes.push({ where: `${name}.probe`, value: component.probe.file });
|
||||
}
|
||||
for (const { where, value } of probes) {
|
||||
for (const token of String(value).match(/\{[a-zA-Z]+\}/g) ?? []) {
|
||||
if (!KNOWN_TOKENS.includes(token)) add("error", where, `unknown probe token ${token} in ${JSON.stringify(value)}`);
|
||||
}
|
||||
}
|
||||
|
||||
/* -------------------------------------------------- 7. requires integrity */
|
||||
|
||||
const names = new Set(Object.keys(manifest.components ?? {}));
|
||||
for (const [name, component] of Object.entries(manifest.components ?? {})) {
|
||||
for (const requirement of component.requires ?? []) {
|
||||
if (!names.has(requirement)) add("error", `${name}.requires`, `unknown component "${requirement}"`);
|
||||
if (requirement === name) add("error", `${name}.requires`, "depends on itself");
|
||||
}
|
||||
}
|
||||
// Cycle check over `requires`.
|
||||
const visiting = new Set();
|
||||
const visited = new Set();
|
||||
const walk = (name, trail) => {
|
||||
if (visited.has(name)) return;
|
||||
if (visiting.has(name)) {
|
||||
add("error", `${name}.requires`, `dependency cycle: ${[...trail, name].join(" -> ")}`);
|
||||
return;
|
||||
}
|
||||
visiting.add(name);
|
||||
for (const requirement of manifest.components[name]?.requires ?? []) {
|
||||
if (names.has(requirement)) walk(requirement, [...trail, name]);
|
||||
}
|
||||
visiting.delete(name);
|
||||
visited.add(name);
|
||||
};
|
||||
for (const name of names) walk(name, []);
|
||||
|
||||
/* ------------------------------------- 8. the published patch's JS escapes */
|
||||
|
||||
// This check exists because of a real bug: the row used
|
||||
// process.env.DSH_HOME + '\plugins\rea-bundle\bin\rea-shim.mjs'
|
||||
// YAML single quotes keep the backslashes literal, and JavaScript then eats
|
||||
// them — '\p' is not a path separator, '\r' is a carriage return and '\b' is a
|
||||
// backspace, so the evaluated path was a string full of control characters
|
||||
// that could never start. Nothing in a manifest audit would notice; evaluating
|
||||
// the expression does.
|
||||
const patchPath = path.join(HERE, "..", "cordis.patch.yml");
|
||||
const patchText = readFileSync(patchPath, "utf8");
|
||||
const controlChar = /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/;
|
||||
|
||||
// Evaluate every JS string literal in the patch the way JavaScript would, so
|
||||
// the escape handling is the real one and not a re-implementation.
|
||||
const literals = [...patchText.matchAll(/'((?:[^'\\]|\\.)*)'/g)].map((match) => match[1]);
|
||||
const evaluated = literals.map((literal) => {
|
||||
try {
|
||||
// eslint-disable-next-line no-new-func
|
||||
return new Function(`return '${literal}'`)();
|
||||
} catch {
|
||||
return literal;
|
||||
}
|
||||
});
|
||||
for (const value of evaluated) {
|
||||
if (controlChar.test(value)) {
|
||||
add(
|
||||
"error",
|
||||
"cordis.patch.yml",
|
||||
`a single-quoted literal evaluates to a string containing control characters (${JSON.stringify(value.slice(0, 60))}) — use forward slashes in JS string literals`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (/\\p|\\r|\\b|\\n|\\t/.test(patchText.replace(/^\s*#.*$/gm, ""))) {
|
||||
add("error", "cordis.patch.yml", "a JS string literal contains a backslash escape (\\p, \\r, \\b, ...); use forward slashes");
|
||||
}
|
||||
if (!/rea-shim\.mjs/.test(patchText)) {
|
||||
add("error", "cordis.patch.yml", "the patch does not reference rea-shim.mjs");
|
||||
}
|
||||
if (!/DSH_HOME/.test(patchText) || !/USERPROFILE|HOME/.test(patchText)) {
|
||||
add("error", "cordis.patch.yml", "no fallback for an unset DSH_HOME was found");
|
||||
}
|
||||
|
||||
/* --------------------------- 9. the row, the shim and setup agree on DSH_HOME */
|
||||
|
||||
// This check exists because of a real bug: the row fell back to the bare home
|
||||
// directory while the shim, setup.mjs and bootstrap.ps1 all fall back to
|
||||
// `<home>/.dsh`. setup therefore mirrored the launcher one level below where
|
||||
// the row looked for it, and the row could never start — but only on a machine
|
||||
// where DSH_HOME happened to be unset, so it stayed invisible. Evaluating the
|
||||
// published expression is the only way to catch it.
|
||||
// A bare `!!js` scalar containing "? " and ": " is not one scalar at all: YAML
|
||||
// reads `? a : b` as an explicit key/value pair, so the loader receives a
|
||||
// mapping instead of an expression node. Reproduced against the harness's own
|
||||
// schema (JSON_SCHEMA + the !!js Type from app.asar): args[0] became
|
||||
// {"[object Object]": "..."} and the row could not start. Quoting the scalar
|
||||
// removes the ambiguity, so this check requires quotes around any expression
|
||||
// that would otherwise be read as a mapping.
|
||||
for (const match of patchText.matchAll(/^[ \t]*-[ \t]*!!js[ \t]+(\S.*)$/gm)) {
|
||||
const scalar = match[1].trim();
|
||||
if (scalar.startsWith('"') || scalar.startsWith("'")) continue;
|
||||
if (/\?\s/.test(scalar) && /:\s/.test(scalar)) {
|
||||
add(
|
||||
"error",
|
||||
"cordis.patch.yml",
|
||||
`a bare !!js scalar contains "? " and ": " (${scalar.slice(0, 48)}...), which YAML reads as a mapping: quote the scalar so the loader receives an expression`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Pull the shim-path expression out of the row — quoted (required for a ternary)
|
||||
// or bare. The trailing YAML quote follows the expression's own closing quote,
|
||||
// so the match takes the rest of the line and strips the outer quoting.
|
||||
const rowMatch = patchText.match(/^[ \t]*-[ \t]*!!js[ \t]+(.+rea-shim\.mjs.*)$/m);
|
||||
let jsExpression = rowMatch ? rowMatch[1].trim() : null;
|
||||
if (jsExpression) {
|
||||
const first = jsExpression[0];
|
||||
const last = jsExpression[jsExpression.length - 1];
|
||||
if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
|
||||
jsExpression = jsExpression.slice(1, -1);
|
||||
}
|
||||
}
|
||||
const shimSuffix = "/.dsh/plugins/rea-bundle/bin/rea-shim.mjs";
|
||||
if (!jsExpression) {
|
||||
add("error", "cordis.patch.yml", "the !!js expression that computes the shim path was not found");
|
||||
} else {
|
||||
const evaluate = (env) => {
|
||||
// eslint-disable-next-line no-new-func
|
||||
return new Function("process", `return ${jsExpression}`)({ env });
|
||||
};
|
||||
for (const [label, env] of [
|
||||
["DSH_HOME unset", { USERPROFILE: "C:\\Users\\probe", HOME: "/home/probe" }],
|
||||
["DSH_HOME empty", { DSH_HOME: " ", USERPROFILE: "C:\\Users\\probe", HOME: "/home/probe" }],
|
||||
["DSH_HOME unset, POSIX only", { HOME: "/home/probe" }],
|
||||
]) {
|
||||
let value;
|
||||
try {
|
||||
value = evaluate(env);
|
||||
} catch (error) {
|
||||
add("error", "cordis.patch.yml", `the !!js expression throws with ${label}: ${error && error.message}`);
|
||||
continue;
|
||||
}
|
||||
if (typeof value !== "string" || !value.endsWith(shimSuffix)) {
|
||||
add(
|
||||
"error",
|
||||
"cordis.patch.yml",
|
||||
`with ${label} the row resolves to ${JSON.stringify(value)}; it must end in ${shimSuffix} — the shim, setup.mjs and bootstrap.ps1 all fall back to <home>/.dsh, so the row would look one level too high for a file provisioning writes`,
|
||||
);
|
||||
}
|
||||
}
|
||||
let withHome;
|
||||
try {
|
||||
withHome = evaluate({ DSH_HOME: "/custom/home" });
|
||||
} catch (error) {
|
||||
withHome = `threw: ${error && error.message}`;
|
||||
}
|
||||
if (withHome !== "/custom/home/plugins/rea-bundle/bin/rea-shim.mjs") {
|
||||
add("error", "cordis.patch.yml", `with DSH_HOME set the row resolves to ${JSON.stringify(withHome)}, expected /custom/home/plugins/rea-bundle/bin/rea-shim.mjs`);
|
||||
}
|
||||
|
||||
// A machine with no DSH_HOME, USERPROFILE and HOME resolves the row to the
|
||||
// filesystem root. That is a known, harmless divergence rather than a bug: the
|
||||
// row reports MODULE_NOT_FOUND, writes and downloads nothing, and the harness
|
||||
// carries on (`failOnStartupError: false`). It cannot be reconciled from inside
|
||||
// a `!!js` expression either — setup.mjs resolves such a machine through
|
||||
// `os.homedir()`, which falls back to the passwd entry on POSIX. Pinned as a
|
||||
// warning so the behaviour stays known instead of being rediscovered as a bug.
|
||||
let rootless;
|
||||
try {
|
||||
rootless = evaluate({});
|
||||
} catch (error) {
|
||||
rootless = `threw: ${error && error.message}`;
|
||||
}
|
||||
if (rootless !== "/.dsh/plugins/rea-bundle/bin/rea-shim.mjs") {
|
||||
add(
|
||||
"warn",
|
||||
"cordis.patch.yml",
|
||||
`with DSH_HOME, USERPROFILE and HOME all absent the row resolves to ${JSON.stringify(rootless)}; the documented behaviour is "/.dsh/plugins/rea-bundle/bin/rea-shim.mjs"`,
|
||||
);
|
||||
}
|
||||
|
||||
// Both READMEs print this row so a reader can copy it, and a documented row
|
||||
// that has drifted from the shipped one is what people actually install.
|
||||
for (const doc of ["README.md", "README.zh-CN.md"]) {
|
||||
const text = readFileSync(path.join(HERE, "..", doc), "utf8");
|
||||
if (!text.includes(jsExpression)) {
|
||||
add("error", doc, "the documented !!js expression differs from cordis.patch.yml, so copied instructions would install the wrong row");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ---------------------------------- 9b. the two READMEs stay parallel */
|
||||
|
||||
// They are maintained by hand, and an edit that lands in only one of them leaves
|
||||
// half the readers with stale instructions — the patch expression above is the
|
||||
// one piece already compared, but sections drift the same way. The prose differs
|
||||
// by language, so the check compares the structure that must stay parallel.
|
||||
const headingCounts = (doc) => {
|
||||
const text = readFileSync(path.join(HERE, "..", doc), "utf8");
|
||||
const count = (marker) => (text.match(new RegExp(`^${marker} `, "gm")) ?? []).length;
|
||||
return { sections: count("##"), subsections: count("###") };
|
||||
};
|
||||
const englishHeadings = headingCounts("README.md");
|
||||
const chineseHeadings = headingCounts("README.zh-CN.md");
|
||||
if (englishHeadings.sections !== chineseHeadings.sections || englishHeadings.subsections !== chineseHeadings.subsections) {
|
||||
add(
|
||||
"error",
|
||||
"README.md",
|
||||
`the two READMEs drifted apart in structure: README.md has ${englishHeadings.sections} sections / ${englishHeadings.subsections} subsections, README.zh-CN.md has ${chineseHeadings.sections} / ${chineseHeadings.subsections}`,
|
||||
);
|
||||
}
|
||||
|
||||
/* ------------------------------------------- 10. the mirror list is complete */
|
||||
|
||||
// Another real bug: mirrorLauncher() copied the shim and setup.mjs but not the
|
||||
// manifest. The mirrored setup.mjs derives its plugin root from its own
|
||||
// location, so loadManifest() then read <bundle>/manifest/bundle.manifest.json
|
||||
// — a file nothing created — and every later run died with a bare ENOENT that
|
||||
// the detached auto-provision swallowed.
|
||||
const setupText = readFileSync(path.join(HERE, "..", "scripts", "setup.mjs"), "utf8");
|
||||
const mirrorBody = setupText.match(/function mirrorLauncher\(context\) \{([\s\S]*?)\n\}/)?.[1] ?? "";
|
||||
if (!mirrorBody) {
|
||||
add("error", "scripts/setup.mjs", "mirrorLauncher() was not found, so the mirror list can no longer be verified");
|
||||
} else {
|
||||
// Only the array literal counts. Scanning the whole function body would also
|
||||
// match the explanatory comment above it, which is exactly how this check
|
||||
// first let a sabotaged mirror list pass.
|
||||
const sourcesBody = mirrorBody.match(/const sources = \[([\s\S]*?)\];/)?.[1];
|
||||
if (sourcesBody === undefined) {
|
||||
add("error", "scripts/setup.mjs", "the mirror list (const sources = [...]) was not found");
|
||||
} else {
|
||||
for (const needed of ["bin/rea-shim.mjs", "scripts/setup.mjs", "manifest/bundle.manifest.json"]) {
|
||||
if (!sourcesBody.includes(`"${needed}"`)) {
|
||||
add("error", "scripts/setup.mjs", `mirrorLauncher() does not mirror ${needed}, which the mirrored copy reads at run time`);
|
||||
}
|
||||
}
|
||||
// The shim tells its two copies apart by `cordis.patch.yml`, which only the
|
||||
// checkout ships: a mirrored copy resolves its bundle from its own location
|
||||
// (an MCP child has no DSH_HOME to consult), a checkout copy resolves the
|
||||
// same root setup writes. Mirroring the discriminator would silently flip a
|
||||
// mirrored copy back to the DSH_HOME rule — wrong wherever DSH_HOME is
|
||||
// custom, and wrong in every MCP child, where it is stripped.
|
||||
if (/cordis\.patch\.yml/.test(sourcesBody)) {
|
||||
add(
|
||||
"error",
|
||||
"scripts/setup.mjs",
|
||||
"the mirror list ships cordis.patch.yml, which bin/rea-shim.mjs uses to tell a checkout from a mirrored copy — a mirrored copy would then resolve its bundle through DSH_HOME, which an MCP child does not have",
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------- summary */
|
||||
|
||||
const pinned = fetchEntries.filter((entry) => entry.entry.sha256 && entry.entry.sha256 !== "unverified").length;
|
||||
const tofu = fetchEntries.length - pinned;
|
||||
console.log(`manifest audit: ${fetchEntries.length} fetch entries — ${pinned} hash-pinned, ${tofu} TOFU`);
|
||||
const errors = findings.filter((finding) => finding.severity === "error");
|
||||
const warnings = findings.filter((finding) => finding.severity === "warn");
|
||||
for (const finding of findings) {
|
||||
console.log(` ${finding.severity === "error" ? "ERROR" : "warn "} ${finding.where}: ${finding.message}`);
|
||||
}
|
||||
console.log(errors.length === 0 ? `clean${warnings.length ? ` (${warnings.length} warning(s))` : ""}` : `${errors.length} error(s), ${warnings.length} warning(s)`);
|
||||
process.exit(errors.length === 0 ? 0 : 1);
|
||||
}
|
||||
@@ -0,0 +1,192 @@
|
||||
# rea-bundle-bootstrap.ps1 — get from "no Node at all" to a provisioned bundle.
|
||||
#
|
||||
# Why this exists: setup.mjs is written in Node, so a machine with no Node
|
||||
# cannot run it. This script uses only PowerShell + Expand-Archive (no
|
||||
# downloads other than the official Node.js zip and then the components), gets a
|
||||
# portable Node, and hands the rest to scripts/setup.mjs.
|
||||
#
|
||||
# powershell -ExecutionPolicy Bypass -File scripts\rea-bundle-bootstrap.ps1
|
||||
#
|
||||
# Options:
|
||||
# -Root <dir> bundle root (default: $env:DSH_HOME\plugins\rea-bundle,
|
||||
# falling back to ~\.dsh\plugins\rea-bundle)
|
||||
# -Reuse adopt an existing Ghidra/JDK instead of downloading them
|
||||
# -DryRun print the plan and stop
|
||||
#
|
||||
# Nothing is installed system-wide and no registry key is touched: the runtime
|
||||
# is unpacked next to the bundle and used from there.
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string]$Root,
|
||||
[switch]$Reuse,
|
||||
[switch]$DryRun
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$ProgressPreference = 'SilentlyContinue'
|
||||
|
||||
function Write-Step([string]$Message) { Write-Host "[bootstrap] $Message" }
|
||||
|
||||
# --- where things go -------------------------------------------------------
|
||||
|
||||
if (-not $Root -or $Root.Trim() -eq '') {
|
||||
$home2 = $env:DSH_HOME
|
||||
if (-not $home2 -or $home2.Trim() -eq '') { $home2 = Join-Path $HOME '.dsh' }
|
||||
$Root = Join-Path $home2 'plugins\rea-bundle'
|
||||
}
|
||||
$Root = [System.IO.Path]::GetFullPath($Root)
|
||||
$stack = Join-Path $Root 'stack'
|
||||
$cache = Join-Path $Root 'cache'
|
||||
$logs = Join-Path $Root 'logs'
|
||||
foreach ($dir in @($Root, $stack, $cache, $logs)) {
|
||||
if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
|
||||
}
|
||||
|
||||
$pluginRoot = Split-Path -Parent $PSScriptRoot
|
||||
$setupScript = Join-Path $pluginRoot 'scripts\setup.mjs'
|
||||
if (-not (Test-Path $setupScript)) { throw "setup.mjs not found next to this script: $setupScript" }
|
||||
|
||||
Write-Step "bundle root : $Root"
|
||||
Write-Step "plugin root : $pluginRoot"
|
||||
Write-Step "platform : $([System.Runtime.InteropServices.RuntimeInformation]::OSDescription)"
|
||||
Write-Step "architecture: $env:PROCESSOR_ARCHITECTURE"
|
||||
|
||||
if ($env:PROCESSOR_ARCHITECTURE -notmatch '64') {
|
||||
throw "This bootstrap supports 64-bit Windows (PROCESSOR_ARCHITECTURE=$env:PROCESSOR_ARCHITECTURE)."
|
||||
}
|
||||
|
||||
# --- Node: reuse if compatible, else fetch the portable zip -----------------
|
||||
#
|
||||
# The version and checksum come from the manifest, which is the single source of
|
||||
# truth the rest of provisioning already reads. Hard-coding a second copy here
|
||||
# meant two numbers that could drift apart silently.
|
||||
|
||||
$manifestPath = Join-Path $pluginRoot 'manifest\bundle.manifest.json'
|
||||
if (-not (Test-Path $manifestPath)) { throw "manifest not found: $manifestPath" }
|
||||
$manifest = Get-Content $manifestPath -Raw -Encoding UTF8 | ConvertFrom-Json
|
||||
|
||||
$hostKey = 'win32-' + $(if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x64' })
|
||||
$nodeSource = $manifest.components.node.sources.$hostKey
|
||||
if (-not $nodeSource) { throw "the manifest has no Node source for $hostKey" }
|
||||
$nodeVersion = $nodeSource.version
|
||||
$nodeSha256 = $nodeSource.sha256
|
||||
$nodeUrl = $nodeSource.url
|
||||
$nodeZipName = [System.IO.Path]::GetFileName(([uri]$nodeUrl).AbsolutePath)
|
||||
# The official archive unpacks to exactly one top-level directory named after the
|
||||
# zip: node-v24.21.0-win-x64.zip -> node-v24.21.0-win-x64. The extension is
|
||||
# therefore stripped EXACTLY ONCE. Stripping twice yielded 'node-v24.21', so the
|
||||
# checks below looked for <stack>\node-v24.21\node.exe and the run threw
|
||||
# "the Node zip did not contain node-v24.21" *after* a successful download,
|
||||
# checksum and extraction — on every machine that had no Node, which is the only
|
||||
# audience this script has. Invisible wherever a Node is already on PATH.
|
||||
$nodeFolder = [System.IO.Path]::GetFileNameWithoutExtension($nodeZipName)
|
||||
if ($nodeSha256 -eq 'unverified') { throw "the manifest pins no checksum for $hostKey; refusing to download unverified bytes" }
|
||||
Write-Step "Node source: $hostKey v$nodeVersion"
|
||||
|
||||
function Test-NodeUsable([string]$Exe) {
|
||||
if (-not $Exe -or -not (Test-Path $Exe)) { return $null }
|
||||
try {
|
||||
$version = (& $Exe -v 2>$null)
|
||||
} catch { return $null }
|
||||
if (-not $version) { return $null }
|
||||
$clean = $version.TrimStart('v').Trim()
|
||||
$parts = $clean.Split('.')
|
||||
if ($parts.Count -lt 2) { return $null }
|
||||
$major = [int]$parts[0]
|
||||
$minor = [int]$parts[1]
|
||||
# REA's engines: ^22.19.0 || ^24.11.0 || >=26.0.0
|
||||
$ok = ($major -eq 22 -and $minor -ge 19) -or ($major -eq 24 -and $minor -ge 11) -or ($major -ge 26)
|
||||
if (-not $ok) { return $null }
|
||||
return [pscustomobject]@{ Path = (Resolve-Path $Exe).Path; Version = $clean }
|
||||
}
|
||||
|
||||
# The directory the zip actually created. The derived name is preferred, but any
|
||||
# directory carrying node.exe is accepted: a naming drift must not strand a machine
|
||||
# that has already downloaded and checksum-verified the bytes.
|
||||
function Get-PortableNodeDir {
|
||||
$exact = Join-Path $stack $nodeFolder
|
||||
if (Test-Path (Join-Path $exact 'node.exe')) { return $exact }
|
||||
$found = Get-ChildItem -Path $stack -Directory -ErrorAction SilentlyContinue |
|
||||
Where-Object { Test-Path (Join-Path $_.FullName 'node.exe') } |
|
||||
Select-Object -First 1
|
||||
if ($found) { return $found.FullName }
|
||||
return $exact
|
||||
}
|
||||
|
||||
function Get-PortableNode([switch]$NoDownload) {
|
||||
$exe = Join-Path (Get-PortableNodeDir) 'node.exe'
|
||||
$found = Test-NodeUsable $exe
|
||||
if ($found) { Write-Step "portable Node present: $($found.Path) (v$($found.Version))"; return $found }
|
||||
# -DryRun still *looks* for the portable copy (that is the only way the plan can
|
||||
# tell the truth about whether a download is needed) but never fetches anything.
|
||||
if ($NoDownload) { return $null }
|
||||
|
||||
$zip = Join-Path $cache $nodeZipName
|
||||
if (Test-Path $zip) {
|
||||
$hash = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()
|
||||
if ($hash -ne $nodeSha256) { Write-Step "cached Node zip failed its checksum; re-downloading"; Remove-Item $zip -Force }
|
||||
}
|
||||
if (-not (Test-Path $zip)) {
|
||||
Write-Step "downloading $nodeZipName (~35 MiB)"
|
||||
$partial = "$zip.part"
|
||||
if (Test-Path $partial) { Remove-Item $partial -Force }
|
||||
# Invoke-WebRequest buffers the whole body before writing, so a slow mirror
|
||||
# looks frozen; say so plainly rather than appearing stuck.
|
||||
Invoke-WebRequest -Uri $nodeUrl -OutFile $partial -UseBasicParsing -TimeoutSec 1800
|
||||
Move-Item -LiteralPath $partial -Destination $zip -Force
|
||||
}
|
||||
$actual = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()
|
||||
if ($actual -ne $nodeSha256) { throw "Node.js zip checksum mismatch.`n expected $nodeSha256`n actual $actual" }
|
||||
Write-Step "checksum ok: $actual"
|
||||
|
||||
Write-Step "extracting into $stack"
|
||||
Expand-Archive -LiteralPath $zip -DestinationPath $stack -Force
|
||||
$unpacked = Get-PortableNodeDir
|
||||
if (-not (Test-Path (Join-Path $unpacked 'node.exe'))) { throw "the Node zip left no node.exe under $stack (expected $nodeFolder)" }
|
||||
$found = Test-NodeUsable (Join-Path $unpacked 'node.exe')
|
||||
if (-not $found) { throw "the extracted node.exe could not be executed" }
|
||||
Write-Step "portable Node ready: $($found.Path) (v$($found.Version))"
|
||||
return $found
|
||||
}
|
||||
|
||||
$node = $null
|
||||
$candidates = @()
|
||||
if ($env:REA_BUNDLE_NODE) { $candidates += $env:REA_BUNDLE_NODE }
|
||||
$onPath = (Get-Command node -ErrorAction SilentlyContinue)
|
||||
if ($onPath) { $candidates += $onPath.Source }
|
||||
foreach ($candidate in $candidates) {
|
||||
$node = Test-NodeUsable $candidate
|
||||
if ($node) { Write-Step "using existing Node: $($node.Path) (v$($node.Version))"; break }
|
||||
}
|
||||
|
||||
# A portable Node already unpacked next to the bundle counts as an existing
|
||||
# install, and asking about it is what makes the -DryRun plan tell the truth.
|
||||
if (-not $node) { $node = Get-PortableNode -NoDownload:$DryRun }
|
||||
|
||||
if ($DryRun) {
|
||||
if ($node) { Write-Step "plan: use Node $($node.Path) (v$($node.Version))" }
|
||||
else { Write-Step "plan: download and extract $nodeZipName into $stack" }
|
||||
Write-Step "plan: node `"$setupScript`" --root `"$Root`"$(if ($Reuse) { ' --reuse' })"
|
||||
Write-Step "dry run complete; nothing was changed."
|
||||
exit 0
|
||||
}
|
||||
|
||||
if (-not $node) { $node = Get-PortableNode }
|
||||
|
||||
# --- hand over to setup.mjs ------------------------------------------------
|
||||
|
||||
$setupArgs = @($setupScript, '--root', $Root)
|
||||
if ($Reuse) { $setupArgs += '--reuse' }
|
||||
|
||||
Write-Step "running setup: node $($setupArgs -join ' ')"
|
||||
& $node.Path @setupArgs
|
||||
$code = $LASTEXITCODE
|
||||
|
||||
if ($code -eq 0) {
|
||||
Write-Step "done. Restart DeepSeek Harness so the mcp-rea row reconnects."
|
||||
} else {
|
||||
Write-Step "setup reported unmet components (exit $code). Re-run after fixing the cause."
|
||||
Write-Step "log: $(Join-Path $logs 'setup.log')"
|
||||
}
|
||||
exit $code
|
||||
+1453
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,418 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Unit tests for the pure logic in scripts/setup.mjs — the parts that broke
|
||||
* during development and would break silently again:
|
||||
*
|
||||
* - probe token substitution (a doubled "\bin\java.exe\bin\java.exe" slipped
|
||||
* through once, and a self-referential token could not resolve at all)
|
||||
* - root-directory stripping (an archive's single top-level folder)
|
||||
* - byte formatting and version comparison
|
||||
*
|
||||
* Runs with `node --test`. No network, no filesystem writes outside a temp dir.
|
||||
*/
|
||||
import assert from "node:assert/strict";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import test from "node:test";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
/* ------------------------------------------------- probe token substitution */
|
||||
|
||||
// Mirror of the substitution in setup.mjs, kept small on purpose: the test's job
|
||||
// is to pin the contract, and the integration run covers the real module.
|
||||
const EXE = process.platform === "win32" ? ".exe" : "";
|
||||
|
||||
function substituteProbe(value, context) {
|
||||
const vendor = context.vendor;
|
||||
let text = String(value);
|
||||
const swap = (token, resolved) => {
|
||||
if (typeof resolved === "string" && resolved !== "") text = text.replaceAll(token, resolved);
|
||||
};
|
||||
const vendorPath = (name) => {
|
||||
const resolved = context.resolved?.[name];
|
||||
if (resolved && typeof resolved.path === "string") return resolved.path;
|
||||
if (name === "node") return process.execPath;
|
||||
if (name === "jdk") return path.join(context.vendor, "jdk");
|
||||
if (name === "ghidra") return path.join(context.vendor, "ghidra");
|
||||
return null;
|
||||
};
|
||||
swap("{vendor}", vendor);
|
||||
swap("{vendorDir}", vendor);
|
||||
swap("{root}", context.root);
|
||||
swap("{node}", vendorPath("node"));
|
||||
swap("{jdk}", vendorPath("jdk"));
|
||||
swap("{ghidra}", vendorPath("ghidra"));
|
||||
const jdk = vendorPath("jdk");
|
||||
if (jdk) {
|
||||
const home = /[\\/]bin[\\/]java(\.exe)?$/i.test(jdk) ? path.dirname(path.dirname(jdk)) : jdk;
|
||||
swap("{jvm}", path.join(home, "bin", `java${EXE}`));
|
||||
swap("{javahome}", home);
|
||||
}
|
||||
// Unconditional, matching setup.mjs: on POSIX EXE is "" and a `!== ""` guard
|
||||
// would leave the literal token in place.
|
||||
text = text.replaceAll("{exe}", EXE);
|
||||
return text.replaceAll("/", path.sep);
|
||||
}
|
||||
|
||||
function contextWith(resolved) {
|
||||
return { vendor: path.join(path.sep, "bundle", "vendor"), root: path.join(path.sep, "bundle"), resolved };
|
||||
}
|
||||
|
||||
test("a jdk recorded as an executable still yields a JAVA_HOME-derived {jvm}", () => {
|
||||
// The real failure: {jdk} resolved to java.exe, so join({jdk}, "bin", "java")
|
||||
// produced "<...>\bin\java.exe\bin\java.exe".
|
||||
const context = contextWith({ jdk: { path: path.join(path.sep, "bundle", "vendor", "jdk", "bin", `java${EXE}`) } });
|
||||
const result = substituteProbe("{jvm}", context);
|
||||
assert.equal(result, path.join(path.sep, "bundle", "vendor", "jdk", "bin", `java${EXE}`));
|
||||
assert.equal(result.includes(`java${EXE}${path.sep}bin`), false, "must not double-append the java path");
|
||||
});
|
||||
|
||||
test("a jdk recorded as a home yields the same {jvm}", () => {
|
||||
const context = contextWith({ jdk: { path: path.join(path.sep, "bundle", "vendor", "jdk") } });
|
||||
const result = substituteProbe("{jvm}", context);
|
||||
assert.equal(result, path.join(path.sep, "bundle", "vendor", "jdk", "bin", `java${EXE}`));
|
||||
});
|
||||
|
||||
test("{jvm} resolves while the jdk itself is being provisioned", () => {
|
||||
// No resolved entry at all: the component's own probe must still work.
|
||||
const context = contextWith({});
|
||||
const result = substituteProbe("{jvm}", context);
|
||||
assert.equal(result, path.join(path.sep, "bundle", "vendor", "jdk", "bin", `java${EXE}`));
|
||||
});
|
||||
|
||||
test("{ghidra} resolves while the ghidra component itself is being provisioned", () => {
|
||||
const context = contextWith({});
|
||||
assert.match(substituteProbe("{ghidra}/Ghidra/application.properties", context), /vendor.*ghidra.*Ghidra/);
|
||||
});
|
||||
|
||||
test("{node} falls back to the running interpreter while node is provisioned", () => {
|
||||
const context = contextWith({});
|
||||
assert.equal(substituteProbe("{node}", context), process.execPath);
|
||||
});
|
||||
|
||||
test("{exe} is expanded for tokens that need it and not for those that carry it", () => {
|
||||
const context = contextWith({
|
||||
jdk: { path: path.join(path.sep, "bundle", "vendor", "jdk") },
|
||||
});
|
||||
const adb = substituteProbe("{vendor}/platform-tools/adb{exe}", context);
|
||||
assert.equal(adb, path.join(path.sep, "bundle", "vendor", "platform-tools", `adb${EXE}`));
|
||||
// On POSIX {exe} is "", and the substitution must still consume the token:
|
||||
// leaving "adb{exe}" behind fails the probe with ENOENT on Linux and macOS.
|
||||
assert.equal(adb.includes("{exe}"), false, "{exe} must be consumed even when it expands to nothing");
|
||||
assert.equal(substituteProbe("{jvm}", context).endsWith(`java${EXE}`), true);
|
||||
// Only meaningful where {exe} expands to something: on POSIX EXE is "", so
|
||||
// `java${EXE}${EXE}` degenerates to "java" and endsWith is true by
|
||||
// construction — an assertion that can only ever fail on Windows.
|
||||
if (EXE) assert.equal(substituteProbe("{jvm}", context).endsWith(`java${EXE}${EXE}`), false);
|
||||
});
|
||||
|
||||
test("an unresolved token stays literal instead of throwing", () => {
|
||||
// A missing component must produce a readable ENOENT for the probe, not an
|
||||
// exception out of path.join.
|
||||
const context = contextWith({});
|
||||
const result = substituteProbe("{ghidra}/x", contextWith({ ghidra: undefined }));
|
||||
assert.equal(result, path.join(path.sep, "bundle", "vendor", "ghidra", "x"));
|
||||
});
|
||||
|
||||
/* ------------------------------------------------------- root dir stripping */
|
||||
|
||||
/** Mirror of the descent rule: one level per declared stripRootComponents. */
|
||||
function pickEffectiveRoot(staging, strip, readdir, isDirectory) {
|
||||
let effective = staging;
|
||||
for (let level = 0; level < strip; level += 1) {
|
||||
const entries = readdir(effective).filter((entry) => !entry.startsWith("."));
|
||||
if (entries.length !== 1 || !isDirectory(path.join(effective, entries[0]))) break;
|
||||
effective = path.join(effective, entries[0]);
|
||||
}
|
||||
return effective;
|
||||
}
|
||||
|
||||
// Fixture keys must be built with path.join: the descent uses it, so a
|
||||
// hand-written "/s" would never match on Windows.
|
||||
const ROOT = path.join(path.sep, "s");
|
||||
const NODE_DIR = path.join(ROOT, "node-v24.21.0-win-x64");
|
||||
const JDK_DIR = path.join(ROOT, "jdk-21.0.12.1+1");
|
||||
|
||||
test("stripRootComponents descends past a single top-level folder", () => {
|
||||
const tree = {
|
||||
[ROOT]: ["node-v24.21.0-win-x64"],
|
||||
[NODE_DIR]: ["node.exe", "npm.cmd"],
|
||||
};
|
||||
const readdir = (dir) => tree[dir] ?? [];
|
||||
const isDirectory = (entry) => Object.prototype.hasOwnProperty.call(tree, entry);
|
||||
assert.equal(pickEffectiveRoot(ROOT, 1, readdir, isDirectory), NODE_DIR);
|
||||
});
|
||||
|
||||
test("stripRootComponents leaves a flat archive alone", () => {
|
||||
const tree = { [ROOT]: ["adb.exe", "AdbWinApi.dll"] };
|
||||
const readdir = (dir) => tree[dir] ?? [];
|
||||
const isDirectory = () => false;
|
||||
assert.equal(pickEffectiveRoot(ROOT, 1, readdir, isDirectory), ROOT);
|
||||
});
|
||||
|
||||
test("stop descending when the single entry is a file, not a directory", () => {
|
||||
// A real archive whose root holds exactly one FILE must not be stripped: the
|
||||
// file itself is the payload. Only single DIRECTORIES are descended into.
|
||||
const tree = { [ROOT]: ["payload.bin"] };
|
||||
const readdir = (dir) => tree[dir] ?? [];
|
||||
const isDirectory = (entry) => Object.prototype.hasOwnProperty.call(tree, entry);
|
||||
assert.equal(pickEffectiveRoot(ROOT, 1, readdir, isDirectory), ROOT);
|
||||
});
|
||||
|
||||
test("a jdk-style archive descends into its single root directory", () => {
|
||||
const tree = {
|
||||
[ROOT]: ["jdk-21.0.12.1+1"],
|
||||
[JDK_DIR]: ["bin", "lib", "jmods", "release"],
|
||||
[path.join(JDK_DIR, "bin")]: ["java.exe", "javac.exe"],
|
||||
};
|
||||
const readdir = (dir) => tree[dir] ?? [];
|
||||
const isDirectory = (entry) => Object.prototype.hasOwnProperty.call(tree, entry);
|
||||
assert.equal(pickEffectiveRoot(ROOT, 1, readdir, isDirectory), JDK_DIR);
|
||||
});
|
||||
|
||||
/* --------------------------------------------------------------- tiny helpers */
|
||||
|
||||
test("dotted version comparison used by the reuse check", () => {
|
||||
const cmp = (a, b) => {
|
||||
const left = a.split(".").map(Number);
|
||||
const right = b.split(".").map(Number);
|
||||
for (let i = 0; i < 3; i += 1) {
|
||||
if ((left[i] ?? 0) !== (right[i] ?? 0)) return (left[i] ?? 0) - (right[i] ?? 0);
|
||||
}
|
||||
return 0;
|
||||
};
|
||||
assert.ok(cmp("24.21.0", "24.11.0") > 0);
|
||||
assert.ok(cmp("22.19.0", "22.19.0") === 0);
|
||||
assert.ok(cmp("21.0.12", "21.0.12.1") < 1);
|
||||
});
|
||||
|
||||
test("byte sizes format without a floating-point surprise", () => {
|
||||
const mib = (bytes) => (bytes / 1048576).toFixed(1);
|
||||
assert.equal(mib(569649598), "543.3");
|
||||
assert.equal(mib(8044989), "7.7");
|
||||
});
|
||||
|
||||
/* ------------------------------------------------------ the shim's two homes */
|
||||
|
||||
// The shim runs from two places and must answer differently in each:
|
||||
// * the mirrored copy the published row launches sits at <bundle>/bin/ and must
|
||||
// use its own location — an MCP child has no DSH_HOME to consult, because the
|
||||
// harness strips every DSH_* name from it;
|
||||
// * the checkout copy a human runs (`npm run bundle:status`) is a plugin, not a
|
||||
// bundle, and must resolve the same root setup.mjs writes.
|
||||
// Both mistakes are silent: the checkout claims "not provisioned" on a machine
|
||||
// that is provisioned, and a bare `node bin/rea-shim.mjs mcp` provisions ~800 MB
|
||||
// into the plugin directory.
|
||||
const SHIM_SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "bin", "rea-shim.mjs");
|
||||
|
||||
function shimBundleRoot(shimFile, env) {
|
||||
const run = spawnSync(process.execPath, [shimFile, "--shim-status"], {
|
||||
encoding: "utf8",
|
||||
env: { ...process.env, REA_BUNDLE_AUTO_PROVISION: "0", ...env },
|
||||
});
|
||||
// --shim-status prints its report even when no bundle exists yet (exit 78).
|
||||
return JSON.parse(run.stdout).bundleRoot;
|
||||
}
|
||||
|
||||
test("a mirrored shim takes its bundle root from its own location, not DSH_HOME", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-shim-mirror-"));
|
||||
try {
|
||||
const mirror = path.join(root, "plugins", "rea-bundle");
|
||||
mkdirSync(path.join(mirror, "bin"), { recursive: true });
|
||||
copyFileSync(SHIM_SOURCE, path.join(mirror, "bin", "rea-shim.mjs"));
|
||||
assert.equal(shimBundleRoot(path.join(mirror, "bin", "rea-shim.mjs"), { DSH_HOME: path.join(root, "elsewhere") }), mirror);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("a checkout shim resolves the bundle root setup.mjs would write", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-shim-checkout-"));
|
||||
try {
|
||||
const checkout = path.join(root, "checkout");
|
||||
mkdirSync(path.join(checkout, "bin"), { recursive: true });
|
||||
copyFileSync(SHIM_SOURCE, path.join(checkout, "bin", "rea-shim.mjs"));
|
||||
// The discriminator: only a plugin checkout ships cordis.patch.yml.
|
||||
writeFileSync(path.join(checkout, "cordis.patch.yml"), "- insert: []\n");
|
||||
const home = path.join(root, "dsh-home");
|
||||
assert.equal(
|
||||
shimBundleRoot(path.join(checkout, "bin", "rea-shim.mjs"), { DSH_HOME: home }),
|
||||
path.join(home, "plugins", "rea-bundle"),
|
||||
);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("REA_BUNDLE_ROOT still overrides both layouts", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-shim-override-"));
|
||||
try {
|
||||
const checkout = path.join(root, "checkout");
|
||||
mkdirSync(path.join(checkout, "bin"), { recursive: true });
|
||||
copyFileSync(SHIM_SOURCE, path.join(checkout, "bin", "rea-shim.mjs"));
|
||||
writeFileSync(path.join(checkout, "cordis.patch.yml"), "- insert: []\n");
|
||||
const forced = path.join(root, "forced");
|
||||
assert.equal(shimBundleRoot(path.join(checkout, "bin", "rea-shim.mjs"), { REA_BUNDLE_ROOT: forced }), forced);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("a bare invocation reports usage instead of starting anything", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-shim-bare-"));
|
||||
try {
|
||||
const checkout = path.join(root, "checkout");
|
||||
mkdirSync(path.join(checkout, "bin"), { recursive: true });
|
||||
copyFileSync(SHIM_SOURCE, path.join(checkout, "bin", "rea-shim.mjs"));
|
||||
writeFileSync(path.join(checkout, "cordis.patch.yml"), "- insert: []\n");
|
||||
// The test guards itself: package.json exposes this file as the
|
||||
// `rea-bundle-status` bin, npm cannot append a flag for it, and a regression
|
||||
// here would start REA — or begin an ~800 MB download on an unprovisioned
|
||||
// machine. So setup is a stub that exits immediately.
|
||||
mkdirSync(path.join(checkout, "scripts"), { recursive: true });
|
||||
mkdirSync(path.join(checkout, "manifest"), { recursive: true });
|
||||
writeFileSync(path.join(checkout, "scripts", "setup.mjs"), "process.exit(0);\n");
|
||||
writeFileSync(path.join(checkout, "manifest", "bundle.manifest.json"), "{}\n");
|
||||
|
||||
const home = path.join(root, "dsh-home");
|
||||
const env = { ...process.env, DSH_HOME: home };
|
||||
// Deliberately left at its default: the point is that a bare run must not reach
|
||||
// the provisioning branch at all, not that provisioning is switched off.
|
||||
delete env.REA_BUNDLE_AUTO_PROVISION;
|
||||
|
||||
const run = spawnSync(process.execPath, [path.join(checkout, "bin", "rea-shim.mjs")], {
|
||||
encoding: "utf8",
|
||||
env,
|
||||
timeout: 60000,
|
||||
});
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
assert.match(run.stdout, /--shim-status/);
|
||||
// A lock would mean a provisioning run was started, which a stray
|
||||
// `rea-bundle-status` must never do.
|
||||
assert.equal(existsSync(path.join(home, "plugins", "rea-bundle", "setup.lock")), false);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
/* ------------------------------------------- reusing a Node must check engines */
|
||||
|
||||
// `manifest.components.node.probe.expect.regex` is the contract, and its `why`
|
||||
// says the reuse path must reject an incompatible runtime *there*. Adoption used
|
||||
// to be `fileExists` only, so a Node 20 on PATH was recorded in bundle.json and
|
||||
// the failure surfaced much later as an unexplained REA start failure.
|
||||
//
|
||||
// The tests below run setup.mjs for real (dry-run, node only, temp root: no
|
||||
// network, no writes outside the temp directory) and keep the fix honest in both
|
||||
// directions — a compatible node must still be adopted, so this cannot pass by
|
||||
// rejecting everything.
|
||||
const SETUP_SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), "setup.mjs");
|
||||
const MANIFEST_SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "manifest", "bundle.manifest.json");
|
||||
|
||||
function runSetupNodeOnly(setupPath, root, env) {
|
||||
return spawnSync(process.execPath, [setupPath, "--reuse", "--dry-run", "--only", "node", "--root", root], {
|
||||
encoding: "utf8",
|
||||
timeout: 120000,
|
||||
env: { ...process.env, ...env },
|
||||
});
|
||||
}
|
||||
|
||||
test("--reuse still adopts a compatible node", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-node-ok-"));
|
||||
try {
|
||||
const run = runSetupNodeOnly(SETUP_SOURCE, root, { REA_BUNDLE_NODE: process.execPath });
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
assert.match(run.stdout, /reusing existing node from REA_BUNDLE_NODE/);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("--reuse rejects a candidate the manifest's node probe rejects", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-node-reject-"));
|
||||
try {
|
||||
// A synthetic plugin tree whose manifest rejects the *running* Node, so the
|
||||
// version branch is exercised deterministically on every platform instead of
|
||||
// depending on which OS built-ins happen to exist.
|
||||
const plugin = path.join(root, "plugin");
|
||||
mkdirSync(path.join(plugin, "scripts"), { recursive: true });
|
||||
mkdirSync(path.join(plugin, "manifest"), { recursive: true });
|
||||
copyFileSync(SETUP_SOURCE, path.join(plugin, "scripts", "setup.mjs"));
|
||||
const manifest = JSON.parse(readFileSync(MANIFEST_SOURCE, "utf8"));
|
||||
manifest.components.node.probe.expect.regex = "^v99\\.";
|
||||
writeFileSync(path.join(plugin, "manifest", "bundle.manifest.json"), JSON.stringify(manifest, null, 2));
|
||||
|
||||
const run = runSetupNodeOnly(path.join(plugin, "scripts", "setup.mjs"), path.join(root, "bundle"), {
|
||||
REA_BUNDLE_NODE: process.execPath,
|
||||
});
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
assert.doesNotMatch(run.stdout, /reusing existing node from REA_BUNDLE_NODE/);
|
||||
assert.match(run.stdout, /not reusing REA_BUNDLE_NODE node/);
|
||||
assert.match(run.stdout, /which REA's engines reject/);
|
||||
// ...and it falls through to provisioning rather than giving up.
|
||||
assert.match(run.stdout, /\[plan\] node —/);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("--reuse rejects a candidate that cannot be run at all", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-node-broken-"));
|
||||
try {
|
||||
// A file that exists but is not an executable: on Windows a .bat/.cmd wrapper
|
||||
// reaches the same rejection (execFile cannot spawn one without a shell), and
|
||||
// such a Node could never have launched REA either.
|
||||
const broken = path.join(root, EXE ? "broken-node.exe" : "broken-node");
|
||||
writeFileSync(broken, "this is not an executable\n");
|
||||
if (!EXE) chmodSync(broken, 0o644);
|
||||
const run = runSetupNodeOnly(SETUP_SOURCE, path.join(root, "bundle"), { REA_BUNDLE_NODE: broken });
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
// Not adopted from the override. (A compatible node later on PATH may still be
|
||||
// adopted — that is the fallback working, not the check being bypassed.)
|
||||
assert.doesNotMatch(run.stdout, /reusing existing node from REA_BUNDLE_NODE/);
|
||||
assert.match(run.stdout, /not reusing REA_BUNDLE_NODE node/);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
/* ------------------------------------ an optional component cannot fail the run */
|
||||
|
||||
// `manifest.components.androidPlatformTools` declares `"optional": true` ("without
|
||||
// a device these tools simply report no devices"), but setup.mjs never read that
|
||||
// field: an unreachable dl.google.com — the only Google-hosted component — failed
|
||||
// the whole run on a machine where everything REA needs had provisioned fine.
|
||||
// --offline reproduces exactly that failure with no network: the archive is simply
|
||||
// not in the cache.
|
||||
test("an unavailable optional component is reported, not fatal", () => {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "rea-optional-"));
|
||||
try {
|
||||
// A stub REA, so the probe/shim stages have something to run: this test is
|
||||
// about the optional accounting, not about REA.
|
||||
const stub = path.join(root, "vendor", "node_modules", "rea-agents", "scripts");
|
||||
mkdirSync(stub, { recursive: true });
|
||||
writeFileSync(
|
||||
path.join(stub, "rea.mjs"),
|
||||
'if (process.argv.includes("--version")) { console.log("6.4.0"); } else { console.log(JSON.stringify({ checks: [], tools: [] })); }\n',
|
||||
);
|
||||
|
||||
const run = spawnSync(process.execPath, [SETUP_SOURCE, "--offline", "--only", "androidPlatformTools", "--root", root], {
|
||||
encoding: "utf8",
|
||||
timeout: 120000,
|
||||
});
|
||||
assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`);
|
||||
assert.match(run.stdout, /optional component\(s\) unavailable/);
|
||||
assert.match(run.stdout, /optional: androidPlatformTools/);
|
||||
assert.doesNotMatch(run.stdout, /setup finished with/);
|
||||
|
||||
// Reported, never invented: no adb path is recorded, and the component is
|
||||
// marked unavailable so the shim exports no REA_ADB_PATH at all.
|
||||
const written = JSON.parse(readFileSync(path.join(root, "bundle.json"), "utf8"));
|
||||
assert.equal(written.paths.adb, null);
|
||||
assert.equal(written.components.androidPlatformTools.unavailable, true);
|
||||
} finally {
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,131 @@
|
||||
# verify-branch.ps1 — one-shot structural verification of the bundle branch.
|
||||
# Read-only: parses, audits and unit-tests; it does not provision anything.
|
||||
# Run from the branch root: powershell -NoProfile -File scripts\verify-branch.ps1
|
||||
|
||||
$ErrorActionPreference = 'Continue'
|
||||
$root = Split-Path -Parent $PSScriptRoot
|
||||
Set-Location $root
|
||||
$fail = 0
|
||||
function Check($name, [bool]$ok, $detail) {
|
||||
if ($ok) { Write-Host (" PASS " + $name) -ForegroundColor Green }
|
||||
else { Write-Host (" FAIL " + $name + " " + $detail) -ForegroundColor Red; $script:fail++ }
|
||||
}
|
||||
|
||||
Write-Host "`n=== 1. JS syntax ===" -ForegroundColor Cyan
|
||||
foreach ($f in @('bin\rea-shim.mjs','scripts\setup.mjs','scripts\audit-manifest.mjs','scripts\setup.test.mjs')) {
|
||||
$out = & node --check $f 2>&1
|
||||
Check $f ($LASTEXITCODE -eq 0) ($out -join ' ')
|
||||
}
|
||||
|
||||
Write-Host "`n=== 2. PowerShell parse + BOM ===" -ForegroundColor Cyan
|
||||
# This script checks itself too: it is edited as often as the others, and an editor
|
||||
# that drops the BOM would otherwise go unnoticed until someone adds CJK text here.
|
||||
foreach ($f in @('check-updates.ps1','assets\make-screenshots.ps1','scripts\rea-bundle-bootstrap.ps1','scripts\verify-branch.ps1')) {
|
||||
$p = Join-Path $root $f
|
||||
$bytes = [System.IO.File]::ReadAllBytes($p)
|
||||
$bom = ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF)
|
||||
$errs = $null
|
||||
[System.Management.Automation.Language.Parser]::ParseFile($p, [ref]$null, [ref]$errs) | Out-Null
|
||||
$count = @($errs).Count
|
||||
Check "$f parses" ($count -eq 0) "$count error(s): $(($errs | Select-Object -First 1).Message)"
|
||||
if ($f -ne 'scripts\rea-bundle-bootstrap.ps1') {
|
||||
# These two carry CJK text, which PowerShell 5.1 misreads without a BOM.
|
||||
Check "$f has UTF-8 BOM" $bom "first bytes: $(($bytes[0..2] | ForEach-Object { $_.ToString('x2') }) -join ' ')"
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "`n=== 3. manifest audit ===" -ForegroundColor Cyan
|
||||
$audit = & node scripts\audit-manifest.mjs 2>&1
|
||||
$audit | ForEach-Object { Write-Host " $_" -ForegroundColor Gray }
|
||||
Check 'audit clean' ($LASTEXITCODE -eq 0) 'see findings above'
|
||||
|
||||
Write-Host "`n=== 4. unit tests ===" -ForegroundColor Cyan
|
||||
$tests = & node --test scripts\setup.test.mjs 2>&1
|
||||
$testExit = $LASTEXITCODE
|
||||
$failing = @($tests | Select-String -Pattern 'not ok' ).Count
|
||||
Check 'node --test' ($testExit -eq 0) "$failing failing"
|
||||
|
||||
Write-Host "`n=== 5. the published patch is machine-path-free and escape-safe ===" -ForegroundColor Cyan
|
||||
$patch = Get-Content (Join-Path $root 'cordis.patch.yml') -Raw
|
||||
Check 'no drive letter in patch' (-not ($patch -match '[A-Za-z]:[\\/]')) 'a machine path leaked into the published patch'
|
||||
Check 'no backslash escape in JS literals' (-not ($patch -replace '(?m)^\s*#.*$','' -match '\\[prbnt]')) 'use forward slashes'
|
||||
Check 'references rea-shim.mjs' ($patch -match 'rea-shim\.mjs') ''
|
||||
Check 'has a DSH_HOME fallback' (($patch -match 'DSH_HOME') -and ($patch -match 'USERPROFILE|HOME')) ''
|
||||
$jsProbe = Join-Path $env:TEMP 'rea-verify-literals.cjs'
|
||||
@'
|
||||
const fs = require("node:fs");
|
||||
const text = fs.readFileSync("cordis.patch.yml", "utf8").replace(/^\s*#.*$/gm, "");
|
||||
const control = /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/;
|
||||
const literals = [...text.matchAll(/'((?:[^'\\]|\\.)*)'/g)].map((m) => {
|
||||
try { return new Function("return '" + m[1] + "'")(); } catch { return m[1]; }
|
||||
});
|
||||
const bad = literals.filter((v) => control.test(v));
|
||||
console.log("literals: " + JSON.stringify(literals));
|
||||
if (bad.length) {
|
||||
console.error("control characters in: " + bad.map((v) => JSON.stringify(v)).join(", "));
|
||||
process.exit(1);
|
||||
}
|
||||
'@ | Set-Content $jsProbe -Encoding utf8
|
||||
& node $jsProbe 2>&1 | ForEach-Object { Write-Host " $_" -ForegroundColor Gray }
|
||||
Check 'evaluated literals contain no control characters' ($LASTEXITCODE -eq 0) 'see above'
|
||||
|
||||
Write-Host "`n=== 6. package payload lists what the bundle needs ===" -ForegroundColor Cyan
|
||||
# -Encoding UTF8 is required: the package description contains CJK text, and
|
||||
# PowerShell 5.1 reads a BOM-less file as ANSI, which breaks ConvertFrom-Json.
|
||||
$pkg = Get-Content (Join-Path $root 'package.json') -Raw -Encoding UTF8 | ConvertFrom-Json
|
||||
foreach ($entry in @('bin/', 'scripts/', 'manifest/', 'cordis.patch.yml')) {
|
||||
Check "files[] includes $entry" (@($pkg.files) -contains $entry) ''
|
||||
}
|
||||
foreach ($script in @('bundle:setup', 'bundle:status', 'bundle:audit', 'bundle:test')) {
|
||||
Check "scripts.$script exists" ($pkg.scripts.PSObject.Properties.Name -contains $script) ''
|
||||
}
|
||||
|
||||
Write-Host "`n=== 7. dry-run still plans the whole chain ===" -ForegroundColor Cyan
|
||||
$env:REA_BUNDLE_ROOT = Join-Path $env:TEMP 'rea-verify-dryrun'
|
||||
# Deliberately WITHOUT --reuse. Adoption of whatever this machine happens to have
|
||||
# installed used to hide a defect that only a bare machine sees: every planned
|
||||
# component returned `{ planned: true }` with no path, so the dependents of each
|
||||
# plan entry were reported as "required component is unavailable" and the command
|
||||
# exited 1 — for the exact reader the README sends to `--dry-run`.
|
||||
$dry = & node scripts\setup.mjs --root $env:REA_BUNDLE_ROOT --dry-run 2>&1
|
||||
$planned = @($dry | Select-String -Pattern '^\[plan\]').Count
|
||||
$unmet = @($dry | Select-String -Pattern 'is unavailable').Count
|
||||
Check 'dry-run exits 0 without --reuse' ($LASTEXITCODE -eq 0) (($dry | Select-Object -Last 3) -join ' ')
|
||||
Check 'dry-run plans every component' ($planned -ge 4) "planned=$planned"
|
||||
Check 'dry-run reports no unavailable dependency' ($unmet -eq 0) "unavailable=$unmet"
|
||||
Remove-Item Env:\REA_BUNDLE_ROOT -ErrorAction SilentlyContinue
|
||||
|
||||
Write-Host "`n=== 8. bootstrap recognises an unpacked portable Node (no download) ===" -ForegroundColor Cyan
|
||||
# A machine with no Node is this script's entire audience, so the portable path is
|
||||
# only ever exercised where it is least observable: it must therefore be tested
|
||||
# here, with an empty PATH and a stack laid out exactly as the official zip lays it
|
||||
# out. The folder name is derived from the manifest by a SINGLE extension strip
|
||||
# (node-v24.21.0-win-x64.zip -> node-v24.21.0-win-x64); a double strip used to make
|
||||
# the bootstrap throw "the Node zip did not contain node-v24.21" after a successful
|
||||
# download, checksum and extraction. -DryRun keeps this check download-free.
|
||||
$bootRoot = Join-Path $env:TEMP 'rea-verify-bootstrap'
|
||||
# -Encoding UTF8: the manifest carries non-ASCII text and PowerShell 5.1 would
|
||||
# otherwise read a BOM-less file as ANSI and fail ConvertFrom-Json.
|
||||
$manifest = Get-Content (Join-Path $root 'manifest\bundle.manifest.json') -Raw -Encoding UTF8 | ConvertFrom-Json
|
||||
$bootLayoutName = [System.IO.Path]::GetFileNameWithoutExtension(
|
||||
[System.IO.Path]::GetFileName(([uri]$manifest.components.node.sources.'win32-x64'.url).AbsolutePath))
|
||||
$bootLayout = Join-Path (Join-Path $bootRoot 'stack') $bootLayoutName
|
||||
New-Item -ItemType Directory -Path $bootLayout -Force | Out-Null
|
||||
$hostNode = (Get-Command node -ErrorAction SilentlyContinue).Source
|
||||
if ($hostNode) {
|
||||
$target = Join-Path $bootLayout 'node.exe'
|
||||
if (Test-Path $target) { Remove-Item $target -Force }
|
||||
try { New-Item -ItemType HardLink -Path $target -Target $hostNode -ErrorAction Stop | Out-Null }
|
||||
catch { Copy-Item $hostNode $target -Force }
|
||||
}
|
||||
$bootOut = & powershell -NoProfile -Command "`$env:PATH='C:\Windows\System32;C:\Windows'; & '$root\scripts\rea-bundle-bootstrap.ps1' -Root '$bootRoot' -Reuse -DryRun" 2>&1
|
||||
Check 'bootstrap finds the portable Node in the official layout' (@($bootOut | Select-String 'portable Node present').Count -ge 1) (($bootOut | Select-Object -Last 2) -join ' ')
|
||||
Check 'bootstrap plans no download when one is present' (@($bootOut | Select-String 'plan: download').Count -eq 0) (@($bootOut | Select-String 'plan:').Line -join ' | ')
|
||||
for ($i = 0; $i -lt 5; $i++) {
|
||||
try { Remove-Item -Recurse -Force $bootRoot -ErrorAction Stop; break } catch { Start-Sleep -Milliseconds 300 }
|
||||
}
|
||||
|
||||
Write-Host ''
|
||||
if ($fail -eq 0) { Write-Host 'ALL CHECKS PASSED' -ForegroundColor Green }
|
||||
else { Write-Host "$fail CHECK(S) FAILED" -ForegroundColor Red }
|
||||
exit $fail
|
||||
Reference in new issue
Block a user