dsh-plugin-rea 1.0.6 → 2.0.0

package/bin/rea-shim.mjs

@@ -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);

package/check-updates.ps1

@@ -46,6 +46,10 @@ function Test-NodeEngines([string]$node, [string]$engines) {
   # 之后 $node.Major 为 $null，所有 ^ / ~ 分支都会判假（曾因此把 Node 24 判成不满足）。
   $v = Get-NumericVersion $node
   if (-not $v) { return $null }
+  # 只要有一个 term 的形态不认识，整个判断就只能给"无法解析"：返回 $false 会把
+  # `22.x` / `>=22` 这类合法但未实现的 pattern 误报成"不满足"，让用户去升级一个
+  # 本来就满足的 Node。
+  $recognized = $true
   foreach ($term in ($engines -split '\|\|')) {
     $t = $term.Trim()
     if ($t -match '^\^(\d+\.\d+\.\d+)$') {
@@ -56,8 +60,11 @@ function Test-NodeEngines([string]$node, [string]$engines) {
     } elseif ($t -match '^~(\d+\.\d+\.\d+)$') {
       $base = [version]$Matches[1]
       if ($v.Major -eq $base.Major -and $v.Minor -eq $base.Minor -and $v -ge $base) { return $true }
+    } else {
+      $recognized = $false
     }
   }
+  if (-not $recognized) { return $null }
   return $false
 }
 
@@ -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 '无需动作：整条链路与上游保持一致' }

package/cordis.patch.yml

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