dsh-plugin-rea 1.0.6 → 2.0.0

package/scripts/setup.test.mjs

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

package/scripts/verify-branch.ps1

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