@actiondock/builder 2.0.4

package/README.md

@@ -0,0 +1,74 @@
+# @actiondock/builder
+
+ActionDock 2.0 构建规划、编译器调度与技能导出包。
+
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+`@actiondock/builder` 负责静态分析依赖关系、调度外部 Bun 编译器管线以及将工具和规程打包导出为可分发的 Agent Skill 资产。
+
+---
+
+## 核心组件与能力
+
+### BuildPlanner 依赖闭包计算器
+
+通过纯文本与声明式元数据静态分析依赖关系，无需执行任何用户 TypeScript 业务代码，杜绝模块加载过程中的副作用：
+
+- **清单事实源驱动**：读取 `actiondock.manifest.json` 与 Playbook 的 YAML 头部，精确提取 Actions 与 Playbooks 映射。
+- **递归依赖闭包**：自顶向下递归解析 Action 的 `uses` 声明列表，构建完整的静态调用图。
+- **规程驱动按需剪枝**：支持针对特定 Playbook 进行定向打包，自动计算并仅保留该 Playbook 直接或间接调用的最小 Action 集合，实现 Tree-shaking 瘦身。
+- **静态资产收集**：自动识别并关联清单中声明的外部静态资产文件。
+
+### BunCompiler 外部编译器调度器
+
+封装对外部 Bun 编译器的调度，将 Action Package 编译为目标平台的单文件独立二进制产物：
+
+- **前置参数严密校验**：在发起编译前严格校验入口文件有效性、输出目录权限、字节码编译标志与代码混淆压缩参数。
+- **跨平台目标架构适配**：支持指定跨平台交叉编译目标架构，覆盖 `linux-x64`、`linux-arm64`、`darwin-x64`、`darwin-arm64`、`windows-x64` 等主流平台。
+- **编译器调用与错误归一化**：通过外部进程安全调度 `bun build --compile`，捕获编译器标准错误输出并转换为结构化错误代码。
+- **构建元数据提取**：自动计算产物文件的字节大小、耗时以及 SHA-256 校验和。
+
+### SkillExporter 技能导出器
+
+将原子 Action 与操作规程 Playbook 打包导出为面向主流 AI 智能体生态的标准 Agent Skill 资产：
+
+- **生成 SKILL.md 文档**：提取 Playbook SOP 内容与工具元数据，合成符合智能体规范的操作指南文档与声明头部。
+- **源码模式技能导出**：保留 TypeScript 源码与依赖声明，适合在具备 Node.js 运行环境的智能体容器中直接运行。
+- **独立二进制模式技能导出**：内嵌经过编译的单文件可执行产物，智能体宿主无需安装 Node.js 或 Bun 即可开箱即用。
+- **标准压缩归档**：支持将导出的技能目录无缝归档打包为 `.zip` 或 `.tar.gz` 压缩格式，便于分发上传。
+
+---
+
+## 编程调用示例
+
+```ts
+import { BuildPlanner, BunCompiler, SkillExporter } from "@actiondock/builder";
+
+// 计算依赖规划闭包
+const planner = new BuildPlanner({ projectRoot: "/path/to/project" });
+const plan = planner.createPlan({ playbookId: "review-pr" });
+
+// 调度外部编译器
+const compiler = new BunCompiler();
+const buildResult = await compiler.compile({
+  entrypoint: plan.entrypoint,
+  outfile: "./dist/review-pr-tool",
+  minify: true,
+});
+
+// 导出便携式技能
+const exporter = new SkillExporter({ projectRoot: "/path/to/project" });
+const exportResult = await exporter.export({
+  outputDir: "./dist/skills",
+  playbookId: "review-pr",
+  standalone: true,
+});
+```
+
+---
+
+## 开源协议
+
+本项目采用 Apache-2.0 开源协议。

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@actiondock/builder",
+  "version": "2.0.4",
+  "description": "ActionDock Build Planner, Bun standalone compiler, and Skill exporter",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@actiondock/core": "^2.0.0",
+    "@actiondock/sdk": "^2.0.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "keywords": ["actiondock", "builder", "compiler", "skill", "export"],
+  "author": "team4u",
+  "license": "Apache-2.0"
+}

package/src/archive.ts

@@ -0,0 +1,248 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { deflateRawSync, gzipSync } from "node:zlib";
+import { basename, dirname, join, relative, sep } from "node:path";
+
+/**
+ * 纯 Node 实现的归档压缩模块。
+ *
+ * zip 与 tar.gz 均在进程内完成打包，不依赖宿主机的 zip / tar 命令行工具
+ * （Windows 与最小化 Linux 环境普遍缺少 zip 命令）。
+ * 压缩能力复用 node:zlib 内置的 deflateRaw（zip 条目）与 gzip（tar.gz 容器）。
+ */
+
+/** 目录内相对路径条目（目录在前、同级按名称排序，保证归档内容顺序稳定） */
+interface ArchiveEntry {
+  /** 相对根目录的 POSIX 风格路径（目录以 / 结尾仅出现在 zip 条目名层面） */
+  relPath: string;
+  /** 是否为目录 */
+  isDir: boolean;
+}
+
+/** 递归收集目录内全部条目 */
+function collectEntries(dir: string, baseDir = dir): ArchiveEntry[] {
+  const entries: ArchiveEntry[] = [];
+  for (const name of readdirSync(dir).sort()) {
+    const fullPath = join(dir, name);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      entries.push({ relPath: relative(baseDir, fullPath).split(sep).join("/"), isDir: true });
+      entries.push(...collectEntries(fullPath, baseDir));
+    } else if (stat.isFile()) {
+      entries.push({ relPath: relative(baseDir, fullPath).split(sep).join("/"), isDir: false });
+    }
+  }
+  return entries;
+}
+
+/* ------------------------------------------------------------------ */
+/* zip 格式写入                                                        */
+/* ------------------------------------------------------------------ */
+
+/** CRC32 查表（IEEE 802.3 多项式） */
+const CRC32_TABLE: Uint32Array = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buf: Buffer): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC32_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Unix 毫秒时间戳转 DOS 时间格式（date/time 各 16 位） */
+function dosDateTime(ms: number): { date: number; time: number } {
+  const d = new Date(ms);
+  const year = Math.max(d.getFullYear(), 1980);
+  const time = (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1);
+  const date = ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate();
+  return { date, time };
+}
+
+/** central directory 记录（写入 EOCD 前聚合） */
+interface ZipCentralRecord {
+  header: Buffer;
+  localOffset: number;
+}
+
+/**
+ * 将目录打包为标准 zip 归档（PKZIP APPNOTE 结构）。
+ *
+ * @param dir 待打包目录（目录名即归档内根文件夹名）
+ * @param outPath 输出 zip 文件路径
+ */
+export function createZipArchive(dir: string, outPath: string): void {
+  const rootName = basename(dir);
+  const entries = collectEntries(dir);
+  const chunks: Buffer[] = [];
+  const centralRecords: ZipCentralRecord[] = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    // 归档内路径带根目录前缀；目录条目名以 / 结尾
+    const name = `${rootName}/${entry.relPath}${entry.isDir ? "/" : ""}`;
+    const nameBuf = Buffer.from(name, "utf8");
+    const stat = statSync(join(dir, entry.relPath));
+    const { date, time } = dosDateTime(stat.mtimeMs);
+    const content = entry.isDir ? Buffer.alloc(0) : readFileSync(join(dir, entry.relPath));
+
+    let method = 0;
+    let payload = content;
+    if (!entry.isDir && content.length > 0) {
+      const deflated = deflateRawSync(content, { level: 9 });
+      if (deflated.length < content.length) {
+        method = 8;
+        payload = deflated;
+      }
+    }
+
+    const crc = crc32(content);
+
+    // Local File Header（30 字节 + 文件名）
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6); // UTF-8 文件名标志
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(payload.length, 18);
+    local.writeUInt32LE(content.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    chunks.push(local, nameBuf, payload);
+
+    // Central Directory Header（46 字节 + 文件名）
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4); // version made by
+    central.writeUInt16LE(20, 6); // version needed
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(payload.length, 20);
+    central.writeUInt32LE(content.length, 24);
+    central.writeUInt16LE(nameBuf.length, 28);
+    central.writeUInt16LE(0, 30); // extra len
+    central.writeUInt16LE(0, 32); // comment len
+    central.writeUInt16LE(0, 34); // disk start
+    central.writeUInt16LE(0, 36); // internal attrs
+    // 外部属性：Unix 权限左移 16 位，目录附加 MS-DOS 目录位
+    const extAttrs = ((entry.isDir ? 0o40755 : 0o100644) << 16) | (entry.isDir ? 0x10 : 0);
+    central.writeUInt32LE(extAttrs >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centralRecords.push({ header: Buffer.concat([central, nameBuf]), localOffset: offset });
+
+    offset += local.length + nameBuf.length + payload.length;
+  }
+
+  const centralDirOffset = offset;
+  let centralDirSize = 0;
+  for (const record of centralRecords) {
+    chunks.push(record.header);
+    centralDirSize += record.header.length;
+  }
+
+  // End of Central Directory Record（22 字节）
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(centralRecords.length, 8);
+  eocd.writeUInt16LE(centralRecords.length, 10);
+  eocd.writeUInt32LE(centralDirSize, 12);
+  eocd.writeUInt32LE(centralDirOffset, 16);
+  eocd.writeUInt16LE(0, 20); // comment len
+  chunks.push(eocd);
+
+  writeFileSync(outPath, Buffer.concat(chunks));
+}
+
+/* ------------------------------------------------------------------ */
+/* tar.gz 格式写入                                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 构造单个条目的 USTAR 头块（512 字节）。
+ * 路径超长时按 USTAR prefix 字段拆分，仍放不下则抛错。
+ */
+function tarHeader(path: string, size: number, mtimeSec: number, isDir: boolean): Buffer {
+  let name = path;
+  let prefix = "";
+  if (Buffer.byteLength(name, "utf8") > 100) {
+    const split = name.lastIndexOf("/");
+    if (split <= 0 || split > 155 || name.length - split - 1 > 100) {
+      throw new Error(`归档路径超出 USTAR 字段容量: ${path}`);
+    }
+    prefix = name.slice(0, split);
+    name = name.slice(split + 1);
+  }
+
+  const buf = Buffer.alloc(512);
+  buf.write(name, 0, 100, "utf8");
+  buf.write(isDir ? "0000755" : "0000644", 100, 8, "ascii"); // mode
+  buf.write("0000000", 108, 8, "ascii"); // uid
+  buf.write("0000000", 116, 8, "ascii"); // gid
+  buf.write(size.toString(8).padStart(11, "0"), 124, 12, "ascii"); // size
+  buf.write(Math.floor(mtimeSec).toString(8).padStart(11, "0"), 136, 12, "ascii"); // mtime
+  buf.fill(" ", 148, 156); // chksum 占位（计算时视为空格）
+  buf.write(isDir ? "5" : "0", 156, 1, "ascii"); // typeflag
+  buf.write("ustar\0", 257, 6, "ascii"); // magic
+  buf.write("00", 263, 2, "ascii"); // version
+  if (prefix) buf.write(prefix, 345, 155, "utf8");
+
+  // 校验和：整块字节的无符号累加和，写作 6 位八进制 + NUL + 空格
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += buf[i];
+  buf.write(sum.toString(8).padStart(6, "0"), 148, 7, "ascii");
+  buf.write("\0", 154, 1, "ascii");
+  buf.write(" ", 155, 1, "ascii");
+  return buf;
+}
+
+/** 将字节数补齐到 512 的整数倍 */
+function pad512(length: number): Buffer {
+  const rem = length % 512;
+  return rem === 0 ? Buffer.alloc(0) : Buffer.alloc(512 - rem);
+}
+
+/**
+ * 将目录打包为标准 tar.gz 归档（USTAR + gzip）。
+ *
+ * @param dir 待打包目录（目录名即归档内根文件夹名）
+ * @param outPath 输出 tar.gz 文件路径
+ */
+export function createTarGzArchive(dir: string, outPath: string): void {
+  const rootName = basename(dir);
+  const entries = collectEntries(dir);
+  const chunks: Buffer[] = [];
+
+  for (const entry of entries) {
+    const path = `${rootName}/${entry.relPath}`;
+    const fullPath = join(dir, entry.relPath);
+    const stat = statSync(fullPath);
+    const content = entry.isDir ? Buffer.alloc(0) : readFileSync(fullPath);
+
+    chunks.push(tarHeader(path, content.length, Math.floor(stat.mtimeMs / 1000), entry.isDir));
+    if (!entry.isDir) {
+      chunks.push(content, pad512(content.length));
+    }
+  }
+
+  // 归档结尾：两个全零块
+  chunks.push(Buffer.alloc(1024));
+
+  writeFileSync(outPath, gzipSync(Buffer.concat(chunks), { level: 9 }));
+}

package/src/compiler.ts

@@ -0,0 +1,303 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { CompilerError, CompilerValidationError } from "./errors";
+import type { BunCompilerOptions, BunCompilerResult } from "./types";
+
+/**
+ * 官方支持的 Bun 独立二进制编译目标列表。
+ */
+const SUPPORTED_TARGETS = new Set<string>([
+  "bun",
+  "host",
+  "bun-linux-x64",
+  "linux-x64",
+  "bun-linux-arm64",
+  "linux-arm64",
+  "bun-darwin-x64",
+  "darwin-x64",
+  "bun-darwin-arm64",
+  "darwin-arm64",
+  "bun-windows-x64",
+  "windows-x64",
+  "bun-linux-x64-baseline",
+  "linux-x64-baseline",
+  "bun-linux-x64-modern",
+  "linux-x64-modern",
+]);
+
+/**
+ * 校验目标架构并规范化。
+ */
+function normalizeAndValidateTarget(target?: string): string {
+  if (!target || target === "host" || target === "bun") {
+    return "bun";
+  }
+
+  const cleanTarget = target.trim();
+  if (!SUPPORTED_TARGETS.has(cleanTarget)) {
+    throw new CompilerValidationError(
+      `Unsupported compilation target: '${target}'. Standalone compilation only supports Bun targets (e.g. linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64).`,
+      { code: "UNSUPPORTED_TARGET", target }
+    );
+  }
+
+  return cleanTarget.startsWith("bun-") ? cleanTarget : `bun-${cleanTarget}`;
+}
+
+/**
+ * 规范化编译器错误输出。
+ */
+function normalizeCompilerError(rawStderr: string, rawStdout: string, exitCode: number, target?: string): CompilerError {
+  const combined = `${rawStderr}\n${rawStdout}`.trim();
+  const lines = combined
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+
+  let code = "COMPILATION_FAILED";
+  if (combined.includes("Unsupported target")) {
+    code = "UNSUPPORTED_TARGET";
+  } else if (
+    combined.includes("Cannot find package") ||
+    combined.includes("Cannot find module") ||
+    combined.includes("Could not resolve")
+  ) {
+    code = "MODULE_NOT_FOUND";
+  } else if (
+    combined.includes("SyntaxError") ||
+    combined.includes("Parse error") ||
+    combined.includes("Expected") ||
+    combined.includes("Unexpected")
+  ) {
+    code = "SYNTAX_ERROR";
+  } else if (combined.includes("EACCES") || combined.includes("Permission denied")) {
+    code = "PERMISSION_DENIED";
+  } else if (combined.includes("ENOSPC") || combined.includes("no space left")) {
+    code = "NO_SPACE";
+  }
+
+  const summaryLine = lines.find((l) => l.startsWith("error:")) || lines[0] || "Bun compilation failed";
+
+  return new CompilerError(
+    `Bun compilation failed with exit code ${exitCode} (${code}): ${summaryLine}`,
+    {
+      code,
+      exitCode,
+      rawError: combined,
+      details: lines,
+      target,
+    }
+  );
+}
+
+/**
+ * Bun 独立二进制编译器。
+ * 封装 bun build --compile 调用，提前校验选项组合，收集构建产物与元数据。
+ */
+export class BunCompiler {
+  /**
+   * 执行独立二进制编译。
+   * 
+   * @param options 编译参数
+   * @returns 编译产物元数据结果
+   */
+  public async compile(options: BunCompilerOptions): Promise<BunCompilerResult> {
+    const startTime = Date.now();
+
+    // 1. 入口点存在性校验
+    if (!options.entrypoint) {
+      throw new CompilerValidationError("Entrypoint must be specified for standalone compilation", {
+        code: "INVALID_ENTRYPOINT",
+      });
+    }
+
+    const resolvedEntry = resolve(options.entrypoint);
+    if (!existsSync(resolvedEntry)) {
+      throw new CompilerValidationError(
+        `Entrypoint file not found: ${options.entrypoint}`,
+        { code: "ENTRYPOINT_NOT_FOUND" }
+      );
+    }
+
+    // 2. 输出路径校验
+    if (!options.outfile) {
+      throw new CompilerValidationError("Outfile path must be specified for standalone compilation", {
+        code: "INVALID_OUTFILE",
+      });
+    }
+
+    const resolvedOutfile = resolve(options.outfile);
+    const outDir = dirname(resolvedOutfile);
+    mkdirSync(outDir, { recursive: true });
+
+    // 3. 目标平台与选项校验
+    const normalizedTarget = normalizeAndValidateTarget(options.target);
+    const isWindowsTarget =
+      normalizedTarget.includes("windows") ||
+      (!options.target && process.platform === "win32");
+
+    // 校验布尔选项
+    if (options.minify !== undefined && typeof options.minify !== "boolean") {
+      throw new CompilerValidationError("Option 'minify' must be a boolean", {
+        code: "INVALID_MINIFY_OPTION",
+      });
+    }
+    if (options.bytecode !== undefined && typeof options.bytecode !== "boolean") {
+      throw new CompilerValidationError("Option 'bytecode' must be a boolean", {
+        code: "INVALID_BYTECODE_OPTION",
+      });
+    }
+
+    // 4. 组装 Bun build 命令参数
+    const args = [
+      "bun",
+      "build",
+      resolvedEntry,
+      "--compile",
+      "--outfile",
+      resolvedOutfile,
+    ];
+
+    const bytecode = options.bytecode !== false;
+    if (bytecode) {
+      args.push("--bytecode");
+    }
+
+    const minify = options.minify !== false;
+    if (minify) {
+      args.push("--minify");
+    }
+
+    if (normalizedTarget !== "bun") {
+      args.push(`--target=${normalizedTarget}`);
+    }
+
+    // 5. 执行外部编译器进程
+    const cwd = options.cwd ? resolve(options.cwd) : dirname(resolvedEntry);
+    const proc = spawnSync(args[0], args.slice(1), {
+      cwd,
+      stdio: "pipe",
+      env: {
+        ...process.env,
+        ...options.env,
+      },
+    });
+
+    if (proc.error) {
+      if ((proc.error as any).code === "ENOENT") {
+        throw new CompilerError(
+          "Bun binary not found in PATH. Standalone compilation requires Bun to be installed (e.g. via 'curl -fsSL https://bun.sh/install | bash' or 'npm install -g bun').",
+          {
+            code: "BUN_NOT_FOUND",
+            exitCode: 1,
+            rawError: proc.error.message,
+            target: options.target,
+          }
+        );
+      }
+      throw new CompilerError(`Failed to spawn Bun compiler: ${proc.error.message}`, {
+        code: "SPAWN_FAILED",
+        exitCode: 1,
+        rawError: proc.error.message,
+        target: options.target,
+      });
+    }
+
+    if (proc.status !== 0) {
+      const rawStderr = proc.stderr?.toString("utf-8") || "";
+      const rawStdout = proc.stdout?.toString("utf-8") || "";
+      throw normalizeCompilerError(rawStderr, rawStdout, proc.status ?? 1, options.target);
+    }
+
+    // 6. 解析生成的可执行二进制物理路径（适配 Windows .exe 后缀特性）
+    let actualExecutablePath = resolvedOutfile;
+    if (!existsSync(actualExecutablePath) && isWindowsTarget) {
+      const withExe = `${resolvedOutfile}.exe`;
+      if (existsSync(withExe)) {
+        actualExecutablePath = withExe;
+      }
+    }
+
+    if (!existsSync(actualExecutablePath)) {
+      throw new CompilerError(
+        `Compiler completed with exit code 0 but output executable not found at ${resolvedOutfile}`,
+        {
+          code: "OUTPUT_NOT_FOUND",
+          exitCode: 0,
+          rawError: "Output executable file not found on disk",
+          target: options.target,
+        }
+      );
+    }
+
+    // 7. 计算二进制大小与校验和
+    const binaryBuffer = readFileSync(actualExecutablePath);
+    const sizeBytes = statSync(actualExecutablePath).size;
+    const sha256 = createHash("sha256").update(binaryBuffer).digest("hex");
+    const durationMs = Date.now() - startTime;
+    const compiledAt = new Date().toISOString();
+
+    // 8. 写入 metadata 产物文件
+    let metadataPath: string | undefined;
+    if (options.emitMetadata !== false) {
+      metadataPath = resolve(outDir, "artifact.json");
+      const bunVersion =
+        (typeof (globalThis as any).Bun !== "undefined" && (globalThis as any).Bun.version) ||
+        (() => {
+          try {
+            const vProc = spawnSync("bun", ["--version"], { stdio: "pipe" });
+            if (vProc.status === 0) {
+              return vProc.stdout.toString().trim();
+            }
+          } catch {}
+          return "unknown";
+        })();
+
+      const metadata = {
+        packageId: options.packageId,
+        version: options.version,
+        target: options.target || "host",
+        executable: basename(actualExecutablePath),
+        sizeBytes,
+        sha256,
+        bunVersion,
+        minify,
+        bytecode,
+        actions: options.actions || [],
+        compiledAt,
+      };
+      writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + "\n", "utf-8");
+    }
+
+    return {
+      packageId: options.packageId,
+      version: options.version,
+      target: options.target || "host",
+      executablePath: actualExecutablePath,
+      sizeBytes,
+      sha256,
+      metadataPath,
+      minify,
+      bytecode,
+      durationMs,
+      compiledAt,
+    };
+  }
+
+  /**
+   * 静态辅助调用方法。
+   */
+  public static async compile(options: BunCompilerOptions): Promise<BunCompilerResult> {
+    const compiler = new BunCompiler();
+    return compiler.compile(options);
+  }
+}
+
+/**
+ * 快捷独立二进制编译函数。
+ */
+export async function compileBinary(options: BunCompilerOptions): Promise<BunCompilerResult> {
+  return BunCompiler.compile(options);
+}