@actiondock/builder 2.0.12 → 2.2.0

package/dist/types.d.ts

@@ -1,4 +1,17 @@
 import type { ActionDockManifest, ProjectConfig } from "@actiondock/core";
+/**
+ * 规划输入侧的项目配置扩展字段。
+ * actiondock.json 实际承载 uses、files、assets 等扩展声明，
+ * ProjectConfig 契约未显式列出的部分在此正式声明，替代类型擦除访问。
+ */
+export interface ProjectConfigWithDeclarations extends ProjectConfig {
+    /** 当前包在清单中声明的顶层 uses 跨包依赖 */
+    uses?: string[];
+    /** 框架导出与分发边界文件列表 */
+    files?: string[];
+    /** 静态资产列表 */
+    assets?: string[];
+}
 /**
  * Action 依赖描述。
  */
@@ -11,6 +24,8 @@ export interface ActionDependency {
     resolvedPath: string;
     /** 静态依赖的下游 Action ID 列表 */
     uses: string[];
+    /** 是否为来自外部依赖包中的 Action */
+    isExternal?: boolean;
     /** Action 功能描述 */
     description?: string;
     /** 入参校验模式 */
@@ -30,8 +45,8 @@ export interface AssetDependency {
     path: string;
     /** 资产绝对物理路径 */
     resolvedPath: string;
-    /** 资产类型：静态资产、规程文档、配置文件或模块源码 */
-    type: "asset" | "playbook" | "config" | "module";
+    /** 资产类型：静态资产、规程文档、配置文件或代码文件模块 */
+    type: "asset" | "playbook" | "config" | "module" | "file";
 }
 /**
  * 外部依赖描述。
@@ -44,6 +59,17 @@ export interface ExternalDependency {
     /** 是否为开发期依赖 */
     isDev?: boolean;
 }
+/**
+ * 锁文件元数据描述。
+ */
+export interface LockfileInfo {
+    /** 锁文件名（如 package-lock.json） */
+    name: string;
+    /** 锁文件物理绝对路径 */
+    path: string;
+    /** 锁文件内容的 SHA-256 校验摘要 */
+    sha256: string;
+}
 /**
  * 构建规划中的依赖集合分类。
  */
@@ -90,16 +116,27 @@ export interface BuildPlan {
     dependencies: BuildPlanDependencies;
     /** 资产路径列表 */
     assets: string[];
+    /** 显式声明的代码文件列表 */
+    files?: string[];
     /** 声明的配置定义字典 */
     configDefs?: Record<string, unknown>;
+    /** 依赖闭包包含的外部已链接包项目根目录列表（去重） */
+    externalProjectRoots?: string[];
+    /** 检测到的锁文件信息 */
+    lockfile?: LockfileInfo;
     /** 规划元数据 */
     metadata: {
         plannedAt: string;
         schemaVersion: number;
         actionCount: number;
         playbookCount: number;
+        lockfileDigest?: string;
     };
 }
+/**
+ * 声明式选择规划产物类型别名。
+ */
+export type SelectionPlan = BuildPlan;
 /**
  * 构建规划器配置选项。
  */
@@ -107,110 +144,200 @@ export interface BuildPlannerOptions {
     /** 项目根目录绝对路径 */
     projectRoot: string;
     /** 显式传入的项目配置（若未提供则从 actiondock.json 读取） */
-    config?: ProjectConfig;
-    /** 显式传入的声明式清单（若未提供则从 actiondock.manifest.json 读取） */
-    manifest?: ActionDockManifest;
+    config?: ProjectConfigWithDeclarations;
+    /** 显式传入的声明式清单（若未提供则从 actiondock.json 读取） */
+    manifest?: ActionDockManifest & {
+        files?: string[];
+    };
     /** 挑选的 Action ID 列表（用于依赖闭包裁剪） */
     actions?: string[];
     /** 挑选的 Playbook ID 列表（用于 Playbook 驱动的依赖闭包裁剪） */
     playbooks?: string[];
+    /** 显式声明包含的代码文件或目录列表 */
+    files?: string[];
+    /** 显式声明包含的资产文件或目录列表 */
+    assets?: string[];
+    /** 指定的锁文件路径（可选） */
+    lockfile?: string;
+    /** 期望的锁文件 SHA-256 摘要（若指定且不一致将报错拒绝） */
+    expectedLockfileDigest?: string;
+    /** 是否跳过本地相对依赖完整性校验（默认 false） */
+    skipDependencyValidation?: boolean;
 }
 /**
- * 支持的 Bun 独立编译目标平台。
+ * 声明式选择规划器配置选项别名。
  */
-export type CompileTarget = "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";
+export type SelectionPlannerOptions = BuildPlannerOptions;
 /**
- * Bun 独立编译器参数选项。
+ * 归档压缩格式。
  */
-export interface BunCompilerOptions {
-    /** 编译入口文件绝对路径 */
-    entrypoint: string;
-    /** 目标二进制文件输出路径 */
-    outfile: string;
-    /** 编译目标平台架构（默认 host） */
-    target?: CompileTarget | string;
-    /** 是否开启代码压缩混淆（默认 true） */
-    minify?: boolean;
-    /** 是否启用字节码预编译（默认 true） */
-    bytecode?: boolean;
-    /** 构建工作目录（默认入口文件所在根目录） */
-    cwd?: string;
-    /** 自定义环境变量 */
-    env?: Record<string, string>;
-    /** 所属 Package ID（写入元数据用） */
-    packageId?: string;
-    /** 所属版本号（写入元数据用） */
-    version?: string;
-    /** 包含的 Action ID 列表（写入元数据用） */
+export type ArchiveFormat = "zip" | "tar.gz";
+/**
+ * 基于 Node.js 的目录型交付产物生成选项。
+ */
+export interface BuildOptions {
+    /** 目标项目根目录绝对路径 */
+    projectRoot: string;
+    /** 产物输出目录路径（默认输出至 dist 目录） */
+    outDir?: string;
+    /** 输出路径别名 */
+    outfile?: string;
+    /** 挑选参与构建的 Action ID 清单 */
     actions?: string[];
-    /** 是否生成 artifact.json 元数据文件（默认 true） */
-    emitMetadata?: boolean;
+    /** 挑选参与构建的 Playbook ID 清单 */
+    playbooks?: string[];
+    /** 是否生成标准 zip 压缩归档交付产物 */
+    archive?: boolean;
+    /** 是否在干净暂存目录中物化锁定的生产依赖 */
+    vendorDeps?: boolean;
+    /** 是否允许执行依赖安装生命周期脚本（默认 false） */
+    allowInstallScripts?: boolean;
+    /** 是否强制要求构建可复现（默认 false） */
+    requireReproducible?: boolean;
+    /** 显式传入的项目配置（可选） */
+    config?: ProjectConfig;
+    /** 显式传入的声明式清单（可选） */
+    manifest?: ActionDockManifest;
+    /** 是否跳过本地相对依赖完整性校验（默认 false） */
+    skipDependencyValidation?: boolean;
+    /**
+     * 已移除的单文件二进制输出目标平台参数。
+     * 若传入将抛出 UNSUPPORTED_BUILD_MODE 错误。
+     */
+    target?: string;
+    /**
+     * 已移除的字节码预编译参数。
+     * 若传入将抛出 UNSUPPORTED_BUILD_MODE 错误。
+     */
+    bytecode?: boolean;
+    /**
+     * 代码混淆选项（历史遗留占位字段，目录型构建不再读取）。
+     */
+    minify?: boolean;
 }
 /**
- * Bun 独立编译器输出结果。
+ * 目录型构建产物结果描述。
  */
-export interface BunCompilerResult {
+export interface BuildResult {
     /** 所属 Package ID */
-    packageId?: string;
-    /** 版本号 */
-    version?: string;
-    /** 编译目标架构 */
-    target: string;
-    /** 独立二进制文件绝对路径 */
+    packageId: string;
+    /** 打包的项目版本号 */
+    version: string;
+    /** 构建产物输出目录路径 */
+    outputDir: string;
+    /** 生成的 zip 压缩归档文件路径（若指定 archive 选项） */
+    archivePath?: string;
+    /** 生成的 Node.js 启动入口绝对路径 */
+    entrypointPath: string;
+    /**
+     * 启动入口可执行文件绝对路径（entrypointPath 的等价别名）。
+     * @deprecated 历史兼容别名，请改用 entrypointPath，将在后续版本移除。
+     */
     executablePath: string;
-    /** 独立二进制文件字节大小 */
-    sizeBytes: number;
-    /** 独立二进制文件的 SHA-256 校验和 */
+    /** 生成的元数据文件路径 */
+    metadataPath: string;
+    /** 打包内置的 Action ID 列表 */
+    actions: string[];
+    /** 打包内置的 Playbook ID 列表 */
+    playbooks: string[];
+    /** 是否物化了依赖 */
+    vendorDeps: boolean;
+    /** 是否具备可复现性 */
+    reproducible: boolean;
+    /** 产物 SHA-256 校验摘要 */
     sha256: string;
-    /** 生成的元数据文件绝对路径（若生成） */
-    metadataPath?: string;
-    /** 编译是否开启混淆 */
-    minify: boolean;
-    /** 编译是否启用字节码 */
-    bytecode: boolean;
-    /** 编译耗时（毫秒） */
-    durationMs: number;
-    /** 编译完成时间戳 */
-    compiledAt: string;
 }
 /**
- * 归档压缩格式。
+ * npm Action 包打包选项。
  */
-export type ArchiveFormat = "zip" | "tar.gz";
+export interface PackOptions {
+    /** 目标项目根目录绝对路径 */
+    projectRoot: string;
+    /** 输出目录路径（默认当前工作目录或 dist 目录） */
+    outDir?: string;
+    /** 是否仅做预检与清单生成，不生成最终 tgz 压缩包 */
+    dryRun?: boolean;
+    /** 显式传入的清单（可选） */
+    manifest?: ActionDockManifest;
+    /** 显式传入的项目配置（可选） */
+    config?: ProjectConfig;
+}
+/**
+ * npm Action 包打包结果。
+ */
+export interface PackResult {
+    /** 所属 Package ID */
+    packageId: string;
+    /** 项目展示名称 */
+    packageName: string;
+    /** 版本号 */
+    version: string;
+    /** 生成的 tgz 压缩包文件路径（dryRun 时未生成则为空） */
+    tarballPath?: string;
+    /** 生成的 tgz 压缩包文件名 */
+    tarballName: string;
+    /** 压缩包字节大小 */
+    sizeBytes: number;
+    /** 压缩包内容的 SHA-256 校验摘要 */
+    sha256: string;
+    /** 打包包含的文件相对路径清单 */
+    files: string[];
+    /** 清单摘要信息 */
+    manifestSummary: {
+        actionsCount: number;
+        actions: string[];
+        assetsCount: number;
+        filesCount: number;
+    };
+}
 /**
  * Skill 导出选项。
  */
 export interface SkillExporterOptions {
     /** 源码项目根目录绝对路径 */
     projectRoot: string;
-    /** 导出模式：source 源码模式 或 standalone 独立二进制模式（默认 source） */
-    mode?: "source" | "standalone";
-    /** 是否开启独立二进制模式（简写选项） */
-    standalone?: boolean;
-    /** 二进制编译目标架构（仅在独立二进制模式生效，默认 host） */
-    target?: CompileTarget | string;
+    /** 导出模式：source 源码型 Skill 或 node 目录型 Skill（默认 source） */
+    mode?: "source" | "node";
     /** 导出产物目标目录（默认输出至 dist 目录） */
     outDir?: string;
     /** 是否执行归档压缩，亦可直接指定归档格式 */
     archive?: boolean | ArchiveFormat;
     /** 归档压缩格式（zip 或 tar.gz） */
     archiveFormat?: ArchiveFormat;
-    /** 挑选的 Playbook 列表（用于 Playbook 驱动的依赖闭包裁剪） */
+    /** 挑选的 Playbook 列表 */
     playbooks?: string[];
-    /** 挑选的 Action 列表（用于 Action 驱动的依赖闭包裁剪） */
+    /** 挑选的 Action 列表 */
     actions?: string[];
-    /** 独立二进制模式下是否开启代码混淆（默认 true） */
-    minify?: boolean;
-    /** 独立二进制模式下是否编译为字节码（默认 true） */
-    bytecode?: boolean;
     /** 预置的项目配置（可选） */
     config?: ProjectConfig;
     /** 预置的声明式清单（可选） */
     manifest?: ActionDockManifest;
-    /** 是否跳过生成 SKILL.md（多包聚合时避免子包重复生成，对外保持唯一定义） */
+    /** 是否跳过生成 SKILL.md */
     skipSkillMd?: boolean;
-    /** 显式指定的已有 SKILL.md 文件路径（若提供或存在则直接使用，不再动态生成） */
+    /** 显式指定的已有 SKILL.md 文件路径 */
     skillMdPath?: string;
+    /** 是否物化锁定依赖（供 node 模式或 source 模式使用） */
+    vendorDeps?: boolean;
+    /** 是否允许生命周期脚本 */
+    allowInstallScripts?: boolean;
+    /** 是否要求可复现 */
+    requireReproducible?: boolean;
+    /** 是否跳过本地相对依赖完整性校验（默认 false） */
+    skipDependencyValidation?: boolean;
+    /** 内部标识：是否作为复合套件子包导出（避免闭包再次触发嵌套 mini-workspace） */
+    _isSubpackage?: boolean;
+    /** 自定义复合技能说明书文件路径 */
+    customMdPath?: string;
+    /** 所属 Workspace 根目录（可选） */
+    workspaceRoot?: string;
+    /**
+     * 已废弃的独立单文件编译选项。
+     * 若传入将抛出替代方案提示或错误。
+     */
+    standalone?: boolean;
+    target?: string;
+    bytecode?: boolean;
+    minify?: boolean;
 }
 /**
  * Skill 导出完成结果。
@@ -220,10 +347,8 @@ export interface SkillExportResult {
     packageId: string;
     /** 项目版本号 */
     version: string;
-    /** 导出模式 */
-    mode: "source" | "standalone";
-    /** 目标平台架构 */
-    target: string;
+    /** 导出模式：source 源码型或 node 目录型 */
+    mode: "source" | "node";
     /** 生成的 Skill 目录绝对路径 */
     skillDir: string;
     /** 生成的归档文件绝对路径（若开启压缩） */
@@ -277,10 +402,14 @@ export interface CompositeSkillExportOptions {
     archive?: boolean | ArchiveFormat;
     /** 归档压缩格式（zip 或 tar.gz） */
     archiveFormat?: ArchiveFormat;
-    /** 工作区根目录（用于检索工作区现有的 SKILL.md 等资产，默认基于 cwd 与项目目录推导） */
+    /** 工作区根目录 */
     workspaceRoot?: string;
-    /** 显式指定的已有 SKILL.md 文件路径（若存在则直接使用，不再动态生成） */
+    /** 显式指定的已有 SKILL.md 文件路径 */
     skillMdPath?: string;
+    /** 显式指定的自定义说明书（SKILL.custom.md）路径；缺省时自动发现工作区/当前目录下的同名文件 */
+    customMdPath?: string;
+    /** 仅生成复合 SKILL.md（始终重新生成，忽略已有 SKILL.md，不拷贝子包产物） */
+    skillMdOnly?: boolean;
 }
 /**
  * 复合 Skill 套件导出结果。
@@ -308,4 +437,6 @@ export interface CompositeSkillExportResult {
     files: string[];
     /** 若复用了已有的 SKILL.md 文件，返回该文件的绝对路径 */
     usedExistingSkillMd?: string;
+    /** skillMdOnly 模式下实际写出的 SKILL.md 文件绝对路径 */
+    skillMdFile?: string;
 }

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.0.12",
-  "description": "ActionDock Build Planner, Bun standalone compiler, and Skill exporter",
+  "version": "2.2.0",
+  "description": "ActionDock Build Planner, distribution packaging, and Skill exporter",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,21 +18,20 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=24.12.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "bun run ../../scripts/build.ts",
-    "test": "bun test"
+    "build": "node ../../scripts/build.ts",
+    "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.0.12",
-    "@actiondock/sdk": "^2.0.12",
-    "typescript": "^5.7.0",
-    "yaml": "^2.7.0"
+    "@actiondock/core": "^2.2.0",
+    "@actiondock/runtime-node": "^2.2.0",
+    "@actiondock/sdk": "^2.2.0"
   },
   "keywords": [
     "actiondock",

package/dist/compiler.d.ts

@@ -1,22 +0,0 @@
-import type { BunCompilerOptions, BunCompilerResult } from "./types";
-/**
- * Bun 独立二进制编译器。
- * 封装 bun build --compile 调用，提前校验选项组合，收集构建产物与元数据。
- */
-export declare class BunCompiler {
-    /**
-     * 执行独立二进制编译。
-     *
-     * @param options 编译参数
-     * @returns 编译产物元数据结果
-     */
-    compile(options: BunCompilerOptions): Promise<BunCompilerResult>;
-    /**
-     * 静态辅助调用方法。
-     */
-    static compile(options: BunCompilerOptions): Promise<BunCompilerResult>;
-}
-/**
- * 快捷独立二进制编译函数。
- */
-export declare function compileBinary(options: BunCompilerOptions): Promise<BunCompilerResult>;