@co0ontty/wand 4.72.2 → 4.73.0

package/scripts/stage-render-binaries.js

@@ -0,0 +1,626 @@
+#!/usr/bin/env node
+/**
+ * 把 `render-bin` 子模块里 pin 住的 wand-render 产物 stage 到 `dist/native/<triple>/`，
+ * 供 npm 包内嵌（`dist/` 在 package.json 的 `files` 里）。
+ *
+ * 为什么必须有这一步，而不是运行时去读 `render-bin/`：
+ *   - npm 全局安装的结果里只有 `dist/` + `browser-extension` + 少量 `scripts/`；
+ *     `render-bin` 子模块**不会**出现在安装结果里。包要在发布前就把二进制塞进 dist。
+ *   - 二进制经 npm / git 传输会丢可执行位（legacy 的 node-pty spawn-helper 就栽在这），
+ *     所以 stage 完必须显式 chmod 0755，并留下 `.sha256` sidecar 让下游可校验。
+ *   - 三重校验（sha256 / 可执行且版本一致 / 不是 stub）是硬门槛：曾经有一个只打印
+ *     `(stub)` 的 302KB 假二进制进过分发目录。校验失败一律**报错退出**，绝不「放行让下游发现」。
+ *   - `render-bin` 子模块没初始化时要**警告并跳过**（退出码 0）：没拉子模块的开发机上
+ *     `npm run build` 不该因此失败；`--strict` 才是「必须内嵌」的场景（CI 发布链路）。
+ *
+ * 用法见 `--help`；布局与升级路径见 `docs/render-upgrade-path.md`。
+ */
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+/** 本脚本所在仓库 / npm 包的根目录（脚本随包一起分发）。 */
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** 已发布产物的子模块目录与索引文件名。 */
+export const RENDER_BIN_DIR_NAME = "render-bin";
+export const MANIFEST_FILE_NAME = "manifest.json";
+
+export const BINARY_NAME = "wand-render";
+export const STRUCTURED_BINARY_NAME = "wand-structured-renderd";
+export const VERSION_FILE_NAME = "wand-render.version";
+export const SHA256_FILE_NAME = "wand-render.sha256";
+
+/**
+ * 支持的平台三元组，必须与 `render-bin/manifest.json` 的键和
+ * `src/render-binary.ts` 的 `SUPPORTED_RENDER_TRIPLES` 一致。
+ * `src` 侧与 `scripts` 侧的解析逻辑各自独立（TS 不能直接被构建脚本 import），
+ * 一致性由 `tests/render-staging.test.ts` 的对照用例守住。
+ */
+export const SUPPORTED_TRIPLES = ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+
+const VERSION_PROBE_TIMEOUT_MS = 5_000;
+const ARCH_PROBE_TIMEOUT_MS = 1_000;
+const SEMVER = /\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?/;
+
+/** `uname -m` 的架构别名 → Node 的 process.arch 命名。 */
+const MACHINE_ARCH_ALIASES = {
+  arm64: "arm64",
+  aarch64: "arm64",
+  x86_64: "x64",
+  amd64: "x64",
+  x64: "x64",
+};
+
+/** `uname -m` 输出归一化；认不出返回 null。 */
+export function normalizeMachineArch(machine) {
+  if (typeof machine !== "string") return null;
+  return MACHINE_ARCH_ALIASES[machine.trim().toLowerCase()] ?? null;
+}
+
+/**
+ * 平台三元组；不在支持列表里返回 null（调用方给出明确结论，不静默降级）。
+ *
+ * 用 `uname -m` 而不是 `process.arch`：macOS 上 Node 跑在 Rosetta 里时它报 `x64`，
+ * 机器其实是 arm64；`rosettaTranslated` 是反向兜底（翻译态下 `uname -m` 也报 x86_64）。
+ */
+export function resolvePlatformTriple(platform, arch, unameMachine, rosettaTranslated = false) {
+  let normalizedArch = normalizeMachineArch(unameMachine) ?? arch;
+  if (platform === "darwin" && normalizedArch === "x64" && rosettaTranslated) normalizedArch = "arm64";
+  const triple = `${platform}-${normalizedArch}`;
+  return SUPPORTED_TRIPLES.includes(triple) ? triple : null;
+}
+
+function runUnameMachine() {
+  if (process.platform === "win32") return null;
+  try {
+    const result = spawnSync("uname", ["-m"], {
+      encoding: "utf8",
+      timeout: ARCH_PROBE_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.error || result.status !== 0) return null;
+    return (result.stdout ?? "").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function isRosettaTranslated() {
+  if (process.platform !== "darwin") return false;
+  try {
+    const result = spawnSync("sysctl", ["-n", "sysctl.proc_translated"], {
+      encoding: "utf8",
+      timeout: ARCH_PROBE_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.error || result.status !== 0) return false;
+    return (result.stdout ?? "").trim() === "1";
+  } catch {
+    return false;
+  }
+}
+
+/** 文件 sha256（hex，小写）。产物不到 1 MB，整块读即可。 */
+export function sha256File(filePath) {
+  return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+
+function isFile(candidate) {
+  try {
+    return statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 执行二进制拿版本。
+ *
+ * `isStub` 单独判一次是为了给出可读的报错（stub 通常连语义化版本号都没有，
+ * 只按版本比对会报「版本不一致」，看不出真正原因）。
+ */
+export function probeRenderBinary(binaryPath) {
+  const result = spawnSync(binaryPath, ["--version"], {
+    encoding: "utf8",
+    timeout: VERSION_PROBE_TIMEOUT_MS,
+    // 不接 stdin：万一对方是「不认 --version 就直接当守护进程跑」的旧二进制，
+    // 也不会因为等 TTY 输入而挂满超时窗口。
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+  const ran = !result.error && result.status === 0;
+  return {
+    ran,
+    output,
+    version: ran ? SEMVER.exec(output)?.[0] ?? null : null,
+    isStub: /stub/i.test(output),
+  };
+}
+
+/**
+ * 读 manifest。区分「子模块没初始化」（缺文件 → 可跳过）与「文件坏了」（硬错误）。
+ */
+export function readManifest(manifestPath) {
+  if (!isFile(manifestPath)) return { ok: false, missing: true, error: `${manifestPath} 不存在` };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    return { ok: false, missing: false, error: `${manifestPath} 不是合法 JSON：${error instanceof Error ? error.message : String(error)}` };
+  }
+  const latest = parsed && typeof parsed.latest === "string" ? parsed.latest : null;
+  const entry = latest && parsed.versions && typeof parsed.versions === "object" ? parsed.versions[latest] : null;
+  if (!latest || !entry || typeof entry !== "object") {
+    return { ok: false, missing: false, error: `${manifestPath} 缺少 latest/versions 结构` };
+  }
+  const triples = entry.triples && typeof entry.triples === "object" ? entry.triples : null;
+  if (!triples) {
+    return { ok: false, missing: false, error: `${manifestPath} 的 versions["${latest}"] 缺少 triples` };
+  }
+  return { ok: true, missing: false, data: { latest, entry, triples } };
+}
+
+/** 在临时目录里造一份 0755 的可执行副本再探测（不碰 dist/，也不假设源文件带可执行位）。 */
+function withExecutableCopy(sourcePath, body) {
+  const tempDir = mkdtempSync(path.join(os.tmpdir(), "wand-render-probe-"));
+  try {
+    const tempPath = path.join(tempDir, BINARY_NAME);
+    copyFileSync(sourcePath, tempPath);
+    chmodSync(tempPath, 0o755);
+    return body(tempPath);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 校验单个产物：尺寸、sha256、能否执行、版本是否与 manifest 一致、是否 stub。
+ * @returns {string | null} 通过返回 null，否则返回可直接打印的原因
+ */
+/** 各平台产物应有的容器格式。用于「不能执行」的跨平台产物做格式级校验。 */
+const TRIPLE_CONTAINER_FORMAT = { darwin: "macho", linux: "elf", win32: "pe" };
+
+/**
+ * 读文件头判断容器格式。
+ *
+ * 跨平台校验只能做到这一步：Linux CI 上无法执行 macOS 产物（exec format error），
+ * 反过来也一样。但「这个槽位里放的是不是那一类二进制」可以判断 ——
+ * 文本 stub、放错平台的文件都能在这里被拦下。
+ */
+export function readBinaryContainerFormat(filePath) {
+  const header = Buffer.alloc(4);
+  const handle = openSync(filePath, "r");
+  try {
+    readSync(handle, header, 0, 4, 0);
+  } finally {
+    closeSync(handle);
+  }
+  const magic = header.toString("hex");
+  // Mach-O 64/32 小端与 FAT/Universal，以及大端变体
+  if (magic.startsWith("cffaedfe") || magic.startsWith("cefaedfe") || magic === "cafebabe" || magic === "bebafeca") return "macho";
+  if (magic === "7f454c46") return "elf";
+  if (magic.startsWith("4d5a")) return "pe";
+  if (magic.startsWith("2321")) return "script";
+  return "unknown";
+}
+
+function verifyArtifact({ triple, artifact, sourcePath, expectedVersion, hostTriple, log, protocolVersion = null }) {
+  if (!isFile(sourcePath)) return `${triple}: 产物缺失 ${sourcePath}（manifest 指向的路径不对？）`;
+
+  const actualSize = statSync(sourcePath).size;
+  if (typeof artifact.size === "number" && actualSize !== artifact.size) {
+    return `${triple}: 尺寸与 manifest 不一致（实际 ${actualSize}，manifest ${artifact.size}）`;
+  }
+  const actualSha = sha256File(sourcePath);
+  const expectedSha = typeof artifact.sha256 === "string" ? artifact.sha256.trim().toLowerCase() : "";
+  if (!expectedSha) return `${triple}: manifest 里没有 sha256，拒绝安装未固定哈希的产物`;
+  if (actualSha !== expectedSha) {
+    return `${triple}: sha256 与 manifest 不一致（实际 ${actualSha}，manifest ${expectedSha}）——产物被改过或仓库损坏`;
+  }
+
+  // 本平台产物直接执行校验 —— 这是最强的一档，能真实发现 stub / 版本不符 / 动态库缺失。
+  //
+  // 跨平台产物不能执行（Linux CI 上核对 macOS 产物会得到 exec format error，那是正常现象，
+  // 不是产物坏了）。所以退一步：完整性由 manifest 的 sha256 保证（上面已核对），
+  // 再用容器格式确认「这一槽位里放的是不是那一类二进制」——文本 stub 与放错平台的文件都能拦下。
+  if (triple !== hostTriple) {
+    const container = readBinaryContainerFormat(sourcePath);
+    const expectedContainer = TRIPLE_CONTAINER_FORMAT[triple.split("-")[0]];
+    if (expectedContainer && container !== expectedContainer) {
+      return `${triple}: 产物容器格式不对（期望 ${expectedContainer}，实际 ${container}）——放错平台的文件或是 stub`;
+    }
+    log(`${triple}: 非本平台产物，跳过 --version 执行校验（已核对 sha256 与容器格式 ${container}）`);
+    return null;
+  }
+
+  const probe = withExecutableCopy(sourcePath, probeRenderBinary);
+  if (!probe.ran) {
+    return `${triple}: 无法执行 ${sourcePath} --version（架构不符 / 动态库缺失 / 文件损坏）：${probe.output || "无输出"}`;
+  }
+  if (probe.isStub) return `${triple}: 产物是 stub（--version 输出 ${JSON.stringify(probe.output)}），拒绝进入分发目录`;
+  if (!probe.version) return `${triple}: --version 输出里读不出语义化版本号：${JSON.stringify(probe.output)}`;
+  if (probe.version !== expectedVersion) {
+    return `${triple}: 产物版本 ${probe.version} 与 manifest latest ${expectedVersion} 不一致`;
+  }
+  if (protocolVersion !== null && !probe.output.includes(`(protocol ${protocolVersion})`)) {
+    return `${triple}: structured 产物协议版本与 manifest 不一致`;
+  }
+  return null;
+}
+
+function writeTextAtomically(filePath, content) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    writeFileSync(tempPath, content, { mode: 0o644 });
+    renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      rmSync(tempPath, { force: true });
+    } catch {
+      // 清理失败不该掩盖真正的错误
+    }
+    throw error;
+  }
+}
+
+/**
+ * 把单个 triple 的产物 stage 到 dist。写路径用「临时文件 → chmod → rename」：
+ * 绝不留下半截的 `wand-render`，也绝不就地改写一个可能正在被执行的二进制。
+ * @returns {{ error: string | null, targetPath: string, sha256: string, version: string }}
+ */
+function stageTriple({ triple, artifact, sourcePath, expectedVersion, distDir, write, hostTriple,
+  binaryName = BINARY_NAME, protocolVersion = null }) {
+  const targetPath = path.join(distDir, "native", triple, binaryName);
+  const sha256 = sha256File(sourcePath);
+  if (!write) return { error: null, targetPath, sha256, version: expectedVersion };
+
+  mkdirSync(path.dirname(targetPath), { recursive: true, mode: 0o755 });
+  const tempPath = `${targetPath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    copyFileSync(sourcePath, tempPath);
+    // 可执行位必须在 rename 之前设好：先就位再 chmod 会留下一个短暂的不可执行文件。
+    chmodSync(tempPath, 0o755);
+    // 自检「复制有没有损坏、有没有丢可执行位、是不是同一个文件」。
+    // 本平台可以执行二进制（最强），跨平台只能比对内容哈希 + 容器格式 ——
+    // 在 Linux runner 上执行 macOS 产物必然失败，那是预期现象，不是损坏。
+    const copiedSha = sha256File(tempPath);
+    if (copiedSha !== sha256) {
+      throw new Error(`就位后的副本 sha256 与源不一致（${copiedSha} != ${sha256}）`);
+    }
+    if (triple === hostTriple) {
+      const probe = probeRenderBinary(tempPath);
+      if (!probe.ran || probe.isStub || probe.version !== expectedVersion
+        || (protocolVersion !== null && !probe.output.includes(`(protocol ${protocolVersion})`))) {
+        throw new Error(
+          `就位后的副本自检失败（ran=${probe.ran} stub=${probe.isStub} version=${probe.version}，期望 ${expectedVersion}）：${probe.output || "无输出"}`,
+        );
+      }
+    } else {
+      const container = readBinaryContainerFormat(tempPath);
+      const expectedContainer = TRIPLE_CONTAINER_FORMAT[triple.split("-")[0]];
+      if (expectedContainer && container !== expectedContainer) {
+        throw new Error(`就位后的副本容器格式不对（期望 ${expectedContainer}，实际 ${container}）`);
+      }
+    }
+    renameSync(tempPath, targetPath);
+  } catch (error) {
+    try {
+      rmSync(tempPath, { force: true });
+    } catch {
+      // 同上
+    }
+    return { error: `${triple}: ${error instanceof Error ? error.message : String(error)}`, targetPath, sha256, version: expectedVersion };
+  }
+  writeTextAtomically(path.join(path.dirname(targetPath), `${binaryName}.version`), `${expectedVersion}\n`);
+  writeTextAtomically(path.join(path.dirname(targetPath), `${binaryName}.sha256`), `${sha256}  ${binaryName}\n`);
+  return { error: null, targetPath, sha256, version: expectedVersion };
+}
+
+/**
+ * 核心实现（除了 dist/native 之外不写任何磁盘；不联网、不读 config、不杀进程）。
+ *
+ * @param {{
+ *   check?: boolean, dryRun?: boolean, all?: boolean, strict?: boolean,
+ *   triples?: string[], packageRoot?: string, renderBinDir?: string, distDir?: string,
+ *   platform?: string, arch?: string, unameMachine?: string | null, rosettaTranslated?: boolean,
+ *   logger?: (message: string) => void,
+ * }} [options]
+ * @returns {{
+ *   exitCode: number,
+ *   action: "staged" | "would-stage" | "checked" | "skipped" | "failed",
+ *   version: string | null,
+ *   triples: string[],
+ *   staged: { triple: string, sourcePath: string, targetPath: string, sha256: string, version: string }[],
+ *   warnings: string[],
+ *   messages: string[],
+ * }}
+ */
+export function stageRenderBinaries(options = {}) {
+  const messages = [];
+  const log = (message) => {
+    messages.push(message);
+    (options.logger ?? (() => {}))(message);
+  };
+  const warnings = [];
+  const warn = (message) => {
+    warnings.push(message);
+    log(`warning: ${message}`);
+  };
+
+  const check = options.check === true;
+  const dryRun = options.dryRun === true;
+  const strict = options.strict === true;
+  const all = options.all === true;
+  const requested = (options.triples ?? []).filter((triple) => typeof triple === "string" && triple);
+  const packageRoot = path.resolve(options.packageRoot ?? PACKAGE_ROOT);
+  const renderBinDir = path.resolve(options.renderBinDir ?? path.join(packageRoot, RENDER_BIN_DIR_NAME));
+  const distDir = path.resolve(options.distDir ?? path.join(packageRoot, "dist"));
+  const manifestPath = path.join(renderBinDir, MANIFEST_FILE_NAME);
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const unameMachine = options.unameMachine !== undefined ? options.unameMachine : runUnameMachine();
+  const rosettaTranslated = options.rosettaTranslated ?? isRosettaTranslated();
+  const base = { version: null, triples: [], staged: [], warnings, messages };
+
+  if (all && requested.length > 0) {
+    log("error: --all 与 --triple 不能同时使用");
+    return { ...base, exitCode: EXIT_FAILED, action: "failed" };
+  }
+
+  const manifest = readManifest(manifestPath);
+  if (!manifest.ok) {
+    if (manifest.missing && !strict) {
+      // 没拉子模块的开发机不该因为缺少发布产物而构建失败。
+      warn(`${manifest.error}；跳过内嵌平台二进制（本机构建仍可用，只是包里没有 wand-render）`);
+      log(`需要内嵌产物时：git submodule update --init ${RENDER_BIN_DIR_NAME}`);
+      return { ...base, exitCode: EXIT_OK, action: "skipped" };
+    }
+    log(`error: ${manifest.error}${manifest.missing ? "（--strict 下视为失败）" : ""}`);
+    return { ...base, exitCode: EXIT_FAILED, action: "failed" };
+  }
+
+  const { latest, triples: versionTriples } = manifest.data;
+  const available = Object.keys(versionTriples);
+  log(`${RENDER_BIN_DIR_NAME} v${latest}（协议 ${JSON.stringify(manifest.data.entry.protocolVersion ?? "?")}），可用平台：${available.join(", ") || "无"}`);
+  log(`目标目录：${path.join(distDir, "native")}`);
+
+  // 宿主平台三元组：只有它才允许执行校验（跨平台 exec 必然失败）。
+  const hostTriple = resolvePlatformTriple(platform, arch, unameMachine, rosettaTranslated);
+
+  let selected;
+  if (all) {
+    selected = available.slice().sort();
+  } else if (requested.length > 0) {
+    const unknown = requested.filter((triple) => !available.includes(triple));
+    if (unknown.length > 0) {
+      log(`error: manifest v${latest} 里没有这些平台：${unknown.join(", ")}`);
+      return { ...base, version: latest, exitCode: EXIT_FAILED, action: "failed" };
+    }
+    selected = requested;
+  } else {
+    const triple = resolvePlatformTriple(platform, arch, unameMachine, rosettaTranslated);
+    if (!triple) {
+      warn(`不支持的平台：${platform}-${normalizeMachineArch(unameMachine) ?? arch}（支持 ${SUPPORTED_TRIPLES.join(" / ")}）`);
+      return { ...base, version: latest, exitCode: strict ? EXIT_FAILED : EXIT_OK, action: strict ? "failed" : "skipped" };
+    }
+    if (!available.includes(triple)) {
+      warn(`manifest v${latest} 里没有 ${triple} 的产物（本平台可能未分发）`);
+      return { ...base, version: latest, exitCode: strict ? EXIT_FAILED : EXIT_OK, action: strict ? "failed" : "skipped" };
+    }
+    selected = [triple];
+  }
+
+  const staged = [];
+  const failures = [];
+  for (const triple of selected) {
+    const artifact = versionTriples[triple] ?? {};
+    const sourcePath = path.join(renderBinDir, typeof artifact.path === "string" && artifact.path ? artifact.path : path.join(`v${latest}`, triple, BINARY_NAME));
+    const problem = verifyArtifact({ triple, artifact, sourcePath, expectedVersion: latest, hostTriple, log });
+    if (problem) {
+      failures.push(problem);
+      log(`error: ${problem}`);
+      continue;
+    }
+    const sizeLabel = typeof artifact.size === "number" ? `${artifact.size} bytes` : "size 未知";
+    log(`${triple}: 校验通过（sha256 ${sha256File(sourcePath).slice(0, 12)}…，${sizeLabel}，v${latest}）`);
+
+    const result = stageTriple({ triple, artifact, sourcePath, expectedVersion: latest, distDir, write: !check && !dryRun, hostTriple });
+    if (result.error) {
+      failures.push(result.error);
+      log(`error: ${result.error}`);
+      continue;
+    }
+    staged.push({ triple, sourcePath, targetPath: result.targetPath, sha256: result.sha256, version: result.version });
+    let structuredStage = null;
+    if (artifact.structured !== undefined) {
+      const structured = artifact.structured;
+      if (structured?.protocolVersion !== 2 || typeof structured.sha256 !== "string") {
+        const message = `${triple}: v2 structured artifact metadata is invalid`;
+        failures.push(message);
+        log(`error: ${message}`);
+        continue;
+      }
+      const structuredSource = path.join(renderBinDir, typeof structured.path === "string" && structured.path
+        ? structured.path : path.join(`v${latest}`, triple, STRUCTURED_BINARY_NAME));
+      const structuredProblem = verifyArtifact({ triple, artifact: structured, sourcePath: structuredSource,
+        expectedVersion: latest, hostTriple, log, protocolVersion: 2 });
+      if (structuredProblem) {
+        failures.push(structuredProblem);
+        log(`error: ${structuredProblem}`);
+        continue;
+      }
+      const stagedV2 = stageTriple({ triple, artifact: structured, sourcePath: structuredSource,
+        expectedVersion: latest, distDir, write: !check && !dryRun, hostTriple,
+        binaryName: STRUCTURED_BINARY_NAME, protocolVersion: 2 });
+      if (stagedV2.error) {
+        failures.push(stagedV2.error);
+        log(`error: ${stagedV2.error}`);
+        continue;
+      }
+      structuredStage = { sourcePath: structuredSource, ...stagedV2 };
+      staged.push({ triple, sourcePath: structuredSource, targetPath: stagedV2.targetPath,
+        sha256: stagedV2.sha256, version: stagedV2.version });
+    }
+
+    if (check) {
+      if (!isFile(result.targetPath)) {
+        warn(`${result.targetPath} 尚未 stage（构建时由本脚本写入）`);
+        if (strict) {
+          const message = `${triple}: --check --strict 要求 dist 里已经有产物，但 ${result.targetPath} 不存在`;
+          failures.push(message);
+          log(`error: ${message}`);
+        }
+      } else {
+        const stagedSha = sha256File(result.targetPath);
+        if (stagedSha !== result.sha256) {
+          failures.push(`${triple}: 已 stage 的 ${result.targetPath} sha256 与产物不一致（实际 ${stagedSha}）`);
+          log(`error: ${failures[failures.length - 1]}`);
+        } else {
+          log(`${triple}: 已 stage 的副本一致（${result.targetPath}）`);
+        }
+      }
+      if (structuredStage) {
+        if (!isFile(structuredStage.targetPath)) {
+          warn(`${structuredStage.targetPath} 尚未 stage`);
+          if (strict) failures.push(`${triple}: --check --strict requires the v2 binary`);
+        } else if (sha256File(structuredStage.targetPath) !== structuredStage.sha256) {
+          failures.push(`${triple}: staged v2 sha256 mismatch`);
+        }
+      }
+      continue;
+    }
+    if (dryRun) {
+      log(`${triple}: 将写入 ${result.targetPath}（mode 0755）与 ${VERSION_FILE_NAME} / ${SHA256_FILE_NAME} sidecar`);
+      if (structuredStage) log(`${triple}: 将写入 ${structuredStage.targetPath}（v2 protocol 2）`);
+      continue;
+    }
+    log(`${triple}: 已 stage ${result.targetPath}（mode 0755，v${latest}）`);
+    if (structuredStage) log(`${triple}: 已 stage ${structuredStage.targetPath}（protocol 2）`);
+  }
+
+  if (failures.length > 0) {
+    log(`error: ${failures.length} 个平台校验/就位失败，未写入的产物不会被内嵌`);
+    return { ...base, version: latest, triples: selected, staged, exitCode: EXIT_FAILED, action: "failed" };
+  }
+  const action = check ? "checked" : dryRun ? "would-stage" : "staged";
+  return { ...base, version: latest, triples: selected, staged, exitCode: EXIT_OK, action };
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{
+ *   check: boolean, dryRun: boolean, all: boolean, strict: boolean, help: boolean,
+ *   triples: string[], renderBinDir?: string, distDir?: string, error?: string,
+ * }}
+ */
+export function parseArgs(argv) {
+  const options = { check: false, dryRun: false, all: false, strict: false, help: false, triples: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const [name, inlineValue] = arg.startsWith("--") && arg.includes("=")
+      ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)]
+      : [arg, null];
+    const takeValue = () => {
+      if (inlineValue !== null) return inlineValue;
+      index += 1;
+      return argv[index];
+    };
+    if (name === "--check") options.check = true;
+    else if (name === "--dry-run") options.dryRun = true;
+    else if (name === "--all") options.all = true;
+    else if (name === "--strict") options.strict = true;
+    else if (name === "--help" || name === "-h") options.help = true;
+    else if (name === "--triple") {
+      const value = takeValue();
+      if (!value) return { ...options, error: "--triple 需要一个三元组名（如 darwin-arm64）" };
+      options.triples.push(value);
+    } else if (name === "--render-bin") {
+      const value = takeValue();
+      if (!value) return { ...options, error: "--render-bin 需要一个目录" };
+      options.renderBinDir = value;
+    } else if (name === "--dist") {
+      const value = takeValue();
+      if (!value) return { ...options, error: "--dist 需要一个目录" };
+      options.distDir = value;
+    } else {
+      return { ...options, error: `未知参数 ${arg}` };
+    }
+  }
+  return options;
+}
+
+const USAGE = `用法：node scripts/stage-render-binaries.js [选项]
+
+把 ${RENDER_BIN_DIR_NAME}/manifest.json 里 pin 住的 wand-render 产物 stage 到 dist/native/<triple>/，
+供 npm 包内嵌（dist/ 在 package.json 的 files 里）。
+
+选项：
+  --triple <name>    只 stage 指定三元组（可重复；默认按当前平台，含 Rosetta / uname 判定）
+  --all              stage manifest 列出的所有平台
+  --check            只校验（sha256 / 可执行 / 版本 / stub；并比对已 stage 的副本），不写磁盘
+  --dry-run          只报告将写入什么，不写磁盘（仍做全部校验）
+  --strict           ${RENDER_BIN_DIR_NAME} 子模块未初始化 / 本平台无产物 / --check 时 dist 里没有已 stage 的产物 → 视为失败（CI 发布链路用）
+  --render-bin <dir> 指定 ${RENDER_BIN_DIR_NAME} 目录（默认 <pkg>/${RENDER_BIN_DIR_NAME}）
+  --dist <dir>       指定 dist 目录（默认 <pkg>/dist）
+  -h, --help         显示本帮助
+
+退出码：
+  0  已 stage / 可 stage / --check 校验通过（子模块未初始化时也是 0：警告并跳过）
+  1  校验失败（sha256 不符 / 版本不符 / stub / 无法执行）、参数错误、--strict 下的缺产物
+
+双重校验说明：sha256 是唯一「产物是否被改动」的判据（manifest 是 pin）；--version 自检
+是唯一「这个二进制真能跑、且不是 stub」的判据。两者都不通过就不写进 dist。`;
+
+/**
+ * @param {string[]} argv
+ * @returns {number} 退出码
+ */
+export function main(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(USAGE);
+    return EXIT_OK;
+  }
+  if (options.error) {
+    console.error(`error: ${options.error}`);
+    console.error(USAGE);
+    return EXIT_FAILED;
+  }
+  const result = stageRenderBinaries({
+    check: options.check,
+    dryRun: options.dryRun,
+    all: options.all,
+    strict: options.strict,
+    triples: options.triples,
+    renderBinDir: options.renderBinDir,
+    distDir: options.distDir,
+    logger: (message) => console.log(`[wand-render] ${message}`),
+  });
+  return result.exitCode;
+}
+
+// 只有被直接执行时才跑 main；被 import（测试 / Server 自检）时只暴露函数。
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  process.exitCode = main(process.argv.slice(2));
+}