@actiondock/builder 2.0.11 → 2.2.0

package/dist/fs-utils.d.ts

@@ -0,0 +1,16 @@
+export declare function moveDirAtomic(src: string, dest: string): Promise<void>;
+/**
+ * 递归收集目录内全部文件的相对路径（正斜杠分隔，名称排序）。
+ * 统一排序保证产物文件清单与内容摘要的确定性。
+ */
+export declare function collectRelativeFiles(dir: string, baseDir?: string): string[];
+/**
+ * 获取内部 @actiondock/* 依赖的版本号规则。
+ * 预发布版本采用精确锁定，正式版本采用 ^ 语义范围。
+ */
+export declare function getInternalDependencyVersion(version?: string): string;
+/**
+ * 以新目录原子替换已存在的目标目录（含失败回滚保护）。
+ * promotion 失败后优先 backup -> target 回滚；只有新 target 完整成功后才能删除 backup。
+ */
+export declare function replaceDirAtomic(stagingDir: string, targetDir: string): Promise<void>;

package/dist/fs-utils.js

@@ -0,0 +1,146 @@
+import { cpSync, existsSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { ACTIONDOCK_VERSION } from "@actiondock/core";
+/**
+ * builder 包内共享的文件系统基础设施。
+ * 消除 pack / build / exporter 三个业务模块中成体系的重复实现，
+ * 保证目录扫描排序与原子移动等关键行为存在单一事实源。
+ */
+/**
+ * 跨文件系统/分区的原子移动目录辅助函数。
+ * 优先 rename，遇到瞬时性错误码按指数退避重试，最终回退为递归复制后删除。
+ */
+const TRANSIENT_MOVE_ERROR_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+const MOVE_RETRY_ATTEMPTS = 5;
+export async function moveDirAtomic(src, dest) {
+    let lastErr;
+    for (let attempt = 1; attempt <= MOVE_RETRY_ATTEMPTS; attempt++) {
+        try {
+            renameSync(src, dest);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            if (err?.code === "EXDEV") {
+                // 跨文件系统/分区，立即转入跨设备原子搬迁流程
+                break;
+            }
+            if (!TRANSIENT_MOVE_ERROR_CODES.has(err?.code)) {
+                throw err;
+            }
+            await new Promise((r) => setTimeout(r, 50 * attempt));
+        }
+    }
+    if (lastErr?.code !== "EXDEV") {
+        throw lastErr;
+    }
+    // 跨设备场景：先复制到 dest 同父目录下的临时目录，再同设备 rename 保证 dest 提升的原子性
+    const tempDest = `${dest}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        cpSync(src, tempDest, { recursive: true });
+        for (let attempt = 1; attempt <= MOVE_RETRY_ATTEMPTS; attempt++) {
+            try {
+                renameSync(tempDest, dest);
+                break;
+            }
+            catch (err) {
+                if (attempt === MOVE_RETRY_ATTEMPTS || !TRANSIENT_MOVE_ERROR_CODES.has(err?.code)) {
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, 50 * attempt));
+            }
+        }
+        rmSync(src, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    }
+    catch (err) {
+        if (existsSync(tempDest)) {
+            try {
+                rmSync(tempDest, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+            }
+            catch {
+                // 忽略临时目录清理异常
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * 递归收集目录内全部文件的相对路径（正斜杠分隔，名称排序）。
+ * 统一排序保证产物文件清单与内容摘要的确定性。
+ */
+export function collectRelativeFiles(dir, baseDir = dir) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    const entries = readdirSync(dir).sort();
+    for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            results.push(...collectRelativeFiles(fullPath, baseDir));
+        }
+        else if (stat.isFile()) {
+            results.push(relative(baseDir, fullPath).split(sep).join("/"));
+        }
+    }
+    return results;
+}
+/**
+ * 获取内部 @actiondock/* 依赖的版本号规则。
+ * 预发布版本采用精确锁定，正式版本采用 ^ 语义范围。
+ */
+export function getInternalDependencyVersion(version = ACTIONDOCK_VERSION) {
+    if (version.includes("-")) {
+        return version;
+    }
+    return `^${version}`;
+}
+/**
+ * 以新目录原子替换已存在的目标目录（含失败回滚保护）。
+ * promotion 失败后优先 backup -> target 回滚；只有新 target 完整成功后才能删除 backup。
+ */
+export async function replaceDirAtomic(stagingDir, targetDir) {
+    if (existsSync(targetDir)) {
+        const backupDir = `${targetDir}.old-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        await moveDirAtomic(targetDir, backupDir);
+        try {
+            await moveDirAtomic(stagingDir, targetDir);
+        }
+        catch (promoteErr) {
+            // staging 提升失败：清理可能残留的损坏目标目录，并将 backup 恢复至 targetDir
+            if (existsSync(targetDir)) {
+                try {
+                    rmSync(targetDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+                }
+                catch {
+                    // 忽略清理残余异常
+                }
+            }
+            try {
+                await moveDirAtomic(backupDir, targetDir);
+            }
+            catch (rollbackErr) {
+                throw new Error(`Failed to promote directory to '${targetDir}' (${promoteErr instanceof Error ? promoteErr.message : String(promoteErr)}), and rollback from backup '${backupDir}' also failed: ${rollbackErr?.message || String(rollbackErr)}`);
+            }
+            throw promoteErr;
+        }
+        // 只有新 target 完整成功后才能删除 backup
+        rmSync(backupDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    }
+    else {
+        try {
+            await moveDirAtomic(stagingDir, targetDir);
+        }
+        catch (err) {
+            if (existsSync(targetDir)) {
+                try {
+                    rmSync(targetDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+                }
+                catch {
+                    // 忽略清理残余异常
+                }
+            }
+            throw err;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @actiondock/builder 公共导出面。
+ * 采用显式命名导出替代全量 export *，保证公开 API 边界清晰可控。
+ */
+export { BuilderError, PlannerError } from "./errors.js";
+export { collectRelativeFiles, getInternalDependencyVersion, moveDirAtomic, replaceDirAtomic, } from "./fs-utils.js";
+export { assertNoFileProtocolDeps, assertValidManifestActionIds, serializeManifestAction, serializeManifestPlaybooks, serializePlanManifest, } from "./manifest.js";
+export type { SerializePlanManifestOptions } from "./manifest.js";
+export { createTarGzArchive, createTarGzArchiveAsync, createZipArchive, createZipArchiveAsync, writeToStream, } from "./archive.js";
+export type { TarGzArchiveOptions } from "./archive.js";
+export { BuildPlanner, buildPlan, SelectionPlanner, selectionPlan } from "./planner.js";
+export { assertRelativeDependenciesIntegrity, extractRelativeSpecifiers, resolveRelativeModule, } from "./dependency-check.js";
+export { buildProject } from "./build.js";
+export { packProject } from "./pack.js";
+export { exportCompositeSkill, exportSkill, exportSkillBatch, findExistingCompositeSkillMd, findExistingSingleSkillMd, SkillExporter, } from "./exporter.js";
+export type { ActionDependency, ArchiveFormat, AssetDependency, BatchSkillExportOptions, BatchSkillExportResult, BuildOptions, BuildPlan, BuildPlanDependencies, BuildPlannerOptions, BuildResult, CompositeSkillExportOptions, CompositeSkillExportResult, ExternalDependency, LockfileInfo, PackOptions, PackResult, PlaybookPlanEntry, ProjectConfigWithDeclarations, SelectionPlan, SelectionPlannerOptions, SkillExporterOptions, SkillExportResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @actiondock/builder 公共导出面。
+ * 采用显式命名导出替代全量 export *，保证公开 API 边界清晰可控。
+ */
+// 错误类型
+export { BuilderError, PlannerError } from "./errors.js";
+// 共享基础设施（内部复用的通用能力，随包公开便于下游校验）
+export { collectRelativeFiles, getInternalDependencyVersion, moveDirAtomic, replaceDirAtomic, } from "./fs-utils.js";
+// 清单组装与依赖协议校验
+export { assertNoFileProtocolDeps, assertValidManifestActionIds, serializeManifestAction, serializeManifestPlaybooks, serializePlanManifest, } from "./manifest.js";
+// 归档压缩
+export { createTarGzArchive, createTarGzArchiveAsync, createZipArchive, createZipArchiveAsync, writeToStream, } from "./archive.js";
+// 构建规划
+export { BuildPlanner, buildPlan, SelectionPlanner, selectionPlan } from "./planner.js";
+// 相对依赖完整性校验
+export { assertRelativeDependenciesIntegrity, extractRelativeSpecifiers, resolveRelativeModule, } from "./dependency-check.js";
+// 目录型构建与 npm 打包
+export { buildProject } from "./build.js";
+export { packProject } from "./pack.js";
+// Skill 导出
+export { exportCompositeSkill, exportSkill, exportSkillBatch, findExistingCompositeSkillMd, findExistingSingleSkillMd, SkillExporter, } from "./exporter.js";

package/dist/manifest.d.ts

@@ -0,0 +1,75 @@
+import type { ActionDependency, PlaybookPlanEntry } from "./types.js";
+/**
+ * 校验清单 actions 字典中的所有 Action ID 是否符合规范。
+ * 强制写入端契约自检，杜绝非法 Action ID 落盘。
+ */
+export declare function assertValidManifestActionIds(actions: Record<string, unknown>): void;
+/**
+ * actiondock.json 清单组装与依赖协议校验的单一实现。
+ * pack / build / exporter 三个模块的清单拼装与 file: 协议校验全部收敛至此，
+ * 字段顺序属于产物字节级契约的一部分，严禁调整。
+ */
+/**
+ * 构造单个 Action 的清单声明项（字段顺序为产物契约的一部分）。
+ */
+export declare function serializeManifestAction(action: ActionDependency): Record<string, unknown>;
+/**
+ * 构造 Playbook 集合的清单字典。
+ */
+export declare function serializeManifestPlaybooks(playbooks: PlaybookPlanEntry[], playbooksDir: string): Record<string, unknown>;
+/**
+ * manifest 拼装选项。
+ */
+export interface SerializePlanManifestOptions {
+    /** 是否包含 $schema 声明字段（npm pack 产物包含，目录型产物不包含） */
+    includeSchema?: boolean;
+    /** config 字段是否前置于 actions 之前（npm pack 产物的历史字段顺序） */
+    configBeforeActions?: boolean;
+    /** 附加 actionsDir / playbooksDir 目录字段（源码型 Skill 导出需要） */
+    includeDirs?: {
+        actionsDir?: string;
+        playbooksDir?: string;
+    };
+    /** Action 入口改写映射（npm pack 用于指向编译后的 .js/.mjs 入口） */
+    actionEntryOverride?: (action: ActionDependency) => string;
+    /** 是否省略空 config 键（源码型 Skill 导出保持旧版字节级行为：未声明时省略） */
+    omitEmptyConfig?: boolean;
+    /** 是否输出 playbooks 声明（npm pack 产物历史行为不输出，需显式关闭） */
+    includePlaybooks?: boolean;
+}
+/**
+ * 将 SelectionPlan 组装为 actiondock.json 清单对象。
+ * 标准字段顺序：schemaVersion、id、name、version、description、
+ * actionsDir、playbooksDir、actions、playbooks、config、files、assets。
+ */
+export declare function serializePlanManifest(plan: {
+    packageId: string;
+    packageName: string;
+    version: string;
+    description?: string;
+    actions: ActionDependency[];
+    playbooks: PlaybookPlanEntry[];
+    playbooksDir?: string;
+    files?: string[];
+    assets?: string[];
+    configDefs?: Record<string, unknown>;
+}, options?: SerializePlanManifestOptions): Record<string, unknown>;
+/**
+ * 校验依赖字典中不存在 file: 本地协议声明，违规即抛出 BuilderError。
+ */
+export declare function assertNoFileProtocolDeps(dependencies: Record<string, unknown> | undefined, context: string): void;
+/**
+ * 解析 workspace: 依赖的真实版本号。
+ * @actiondock/* 内部依赖直接采用内部版本规则；显式约束直接剥离前缀；
+ * workspace:* 则在本地 node_modules 与 monorepo packages 目录中搜索目标包版本。
+ */
+export declare function resolveWorkspaceDepVersion(root: string, depName: string, ver: string): string;
+/**
+ * 读取并解析 package.json，解析失败抛出 BuilderError。
+ */
+export declare function readPackageJson(pkgJsonPath: string): Record<string, any>;
+/**
+ * 规范化导出用 package.json：导出 ./actiondock.json，设定 node 引擎约束与 ESM 类型。
+ * 返回新对象，不改动传入源。
+ */
+export declare function normalizePkgExportsAndEngines(pkg: Record<string, any>): Record<string, any>;

package/dist/manifest.js

@@ -0,0 +1,213 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ACTION_ID_REGEX } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+import { getInternalDependencyVersion } from "./fs-utils.js";
+/**
+ * 校验清单 actions 字典中的所有 Action ID 是否符合规范。
+ * 强制写入端契约自检，杜绝非法 Action ID 落盘。
+ */
+export function assertValidManifestActionIds(actions) {
+    for (const actionId of Object.keys(actions)) {
+        if (!ACTION_ID_REGEX.test(actionId)) {
+            throw new BuilderError(`Invalid action ID '${actionId}' in generated manifest. Action IDs must match ${ACTION_ID_REGEX}`, "INVALID_ACTION_ID");
+        }
+    }
+}
+/**
+ * actiondock.json 清单组装与依赖协议校验的单一实现。
+ * pack / build / exporter 三个模块的清单拼装与 file: 协议校验全部收敛至此，
+ * 字段顺序属于产物字节级契约的一部分，严禁调整。
+ */
+/**
+ * 构造单个 Action 的清单声明项（字段顺序为产物契约的一部分）。
+ */
+export function serializeManifestAction(action) {
+    return {
+        entry: action.entry,
+        description: action.description,
+        inputSchema: action.inputSchema,
+        outputSchema: action.outputSchema,
+        uses: action.uses,
+        tags: action.tags,
+        annotations: action.annotations,
+    };
+}
+/**
+ * 构造 Playbook 集合的清单字典。
+ */
+export function serializeManifestPlaybooks(playbooks, playbooksDir) {
+    const manifestPlaybooks = {};
+    for (const pb of playbooks) {
+        const fileName = pb.filePath.replace(/\\/g, "/").split("/").pop();
+        manifestPlaybooks[pb.id] = {
+            entry: `${playbooksDir}/${fileName}`,
+            ...(pb.description ? { description: pb.description } : {}),
+            ...(pb.actions && pb.actions.length > 0 ? { actions: pb.actions } : {}),
+        };
+    }
+    return manifestPlaybooks;
+}
+/**
+ * 将 SelectionPlan 组装为 actiondock.json 清单对象。
+ * 标准字段顺序：schemaVersion、id、name、version、description、
+ * actionsDir、playbooksDir、actions、playbooks、config、files、assets。
+ */
+export function serializePlanManifest(plan, options = {}) {
+    const manifestActions = {};
+    for (const act of plan.actions) {
+        // 仅序列化包自有 Action，跨包依赖不写入包清单
+        if (act.isExternal || act.id.includes("/")) {
+            continue;
+        }
+        const serialized = serializeManifestAction(act);
+        if (options.actionEntryOverride) {
+            serialized.entry = options.actionEntryOverride(act);
+        }
+        manifestActions[act.id] = serialized;
+    }
+    // 写入端契约自检断言：校验所有 Action ID 必须符合规范
+    assertValidManifestActionIds(manifestActions);
+    const manifestPlaybooks = serializeManifestPlaybooks(plan.playbooks, options.includeDirs?.playbooksDir || plan.playbooksDir || "playbooks");
+    const manifest = {};
+    if (options.includeSchema) {
+        manifest.$schema = "https://actiondock.dev/schema/v2.json";
+    }
+    manifest.schemaVersion = 2;
+    manifest.id = plan.packageId;
+    manifest.name = plan.packageName;
+    manifest.version = plan.version;
+    manifest.description = plan.description;
+    if (options.includeDirs?.actionsDir) {
+        manifest.actionsDir = options.includeDirs.actionsDir;
+    }
+    if (options.includeDirs?.playbooksDir) {
+        manifest.playbooksDir = options.includeDirs.playbooksDir;
+    }
+    manifest.actions = manifestActions;
+    if (Object.keys(manifestPlaybooks).length > 0 && options.includePlaybooks !== false) {
+        manifest.playbooks = manifestPlaybooks;
+    }
+    if (plan.configDefs) {
+        manifest.config = plan.configDefs;
+    }
+    else if (!options.omitEmptyConfig) {
+        manifest.config = {};
+    }
+    if (plan.files && plan.files.length > 0) {
+        manifest.files = plan.files;
+    }
+    if (plan.assets && plan.assets.length > 0) {
+        manifest.assets = plan.assets;
+    }
+    if (options.configBeforeActions) {
+        // npm pack 产物的历史字段顺序：config 前置于 actions
+        const ordered = {};
+        for (const [key, value] of Object.entries(manifest)) {
+            if (key === "actions") {
+                ordered.config = manifest.config;
+                ordered.actions = value;
+                continue;
+            }
+            if (key === "config") {
+                continue;
+            }
+            ordered[key] = value;
+        }
+        return ordered;
+    }
+    return manifest;
+}
+/**
+ * 校验依赖字典中不存在 file: 本地协议声明，违规即抛出 BuilderError。
+ */
+export function assertNoFileProtocolDeps(dependencies, context) {
+    if (!dependencies || typeof dependencies !== "object")
+        return;
+    for (const [depName, depVer] of Object.entries(dependencies)) {
+        if (String(depVer).startsWith("file:")) {
+            throw new BuilderError(`Unsupported file: dependency for '${depName}'. Runtime dependencies must not use file: protocol in ${context}.`);
+        }
+    }
+}
+/** 依赖名最后一段（scoped 包名去除命名空间前缀） */
+function lastSegment(name) {
+    return name.split("/").pop();
+}
+/**
+ * 解析 workspace: 依赖的真实版本号。
+ * @actiondock/* 内部依赖直接采用内部版本规则；显式约束直接剥离前缀；
+ * workspace:* 则在本地 node_modules 与 monorepo packages 目录中搜索目标包版本。
+ */
+export function resolveWorkspaceDepVersion(root, depName, ver) {
+    if (depName.startsWith("@actiondock/")) {
+        return getInternalDependencyVersion();
+    }
+    const stripped = ver.replace(/^workspace:/, "").trim();
+    if (stripped && stripped !== "*" && stripped !== "^" && stripped !== "~") {
+        return stripped;
+    }
+    const candidates = [
+        resolve(root, "node_modules", depName, "package.json"),
+        resolve(root, "packages", depName, "package.json"),
+        resolve(root, "packages", lastSegment(depName), "package.json"),
+        resolve(root, "..", depName, "package.json"),
+        resolve(root, "..", lastSegment(depName), "package.json"),
+        resolve(root, "..", "packages", depName, "package.json"),
+        resolve(root, "..", "packages", lastSegment(depName), "package.json"),
+        resolve(root, "..", "..", "packages", depName, "package.json"),
+        resolve(root, "..", "..", "packages", lastSegment(depName), "package.json"),
+    ];
+    for (const cand of candidates) {
+        if (existsSync(cand)) {
+            try {
+                const pkgData = JSON.parse(readFileSync(cand, "utf-8"));
+                if (pkgData.version) {
+                    const prefix = stripped === "~" ? "~" : "^";
+                    return `${prefix}${pkgData.version}`;
+                }
+            }
+            catch {
+                // 忽略单个依赖解析异常
+            }
+        }
+    }
+    throw new BuilderError(`Failed to resolve workspace dependency '${depName}' (${ver}) in '${root}'. Target package version could not be found.`);
+}
+/**
+ * 读取并解析 package.json，解析失败抛出 BuilderError。
+ */
+export function readPackageJson(pkgJsonPath) {
+    try {
+        return JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+    }
+    catch (err) {
+        throw new BuilderError(`Invalid package.json in ${pkgJsonPath}: ${err?.message || String(err)}`);
+    }
+}
+/**
+ * 规范化导出用 package.json：导出 ./actiondock.json，设定 node 引擎约束与 ESM 类型。
+ * 返回新对象，不改动传入源。
+ */
+export function normalizePkgExportsAndEngines(pkg) {
+    const normalized = { ...pkg, type: "module" };
+    let currentExports = {};
+    if (typeof normalized.exports === "object" && normalized.exports !== null) {
+        currentExports = { ...normalized.exports };
+    }
+    else if (typeof normalized.exports === "string") {
+        currentExports["."] = normalized.exports;
+    }
+    currentExports["./actiondock.json"] = "./actiondock.json";
+    normalized.exports = currentExports;
+    const currentEngines = {
+        ...(typeof normalized.engines === "object" && normalized.engines !== null
+            ? normalized.engines
+            : {}),
+    };
+    if (!currentEngines.node) {
+        currentEngines.node = ">=24.12.0";
+    }
+    normalized.engines = currentEngines;
+    return normalized;
+}

package/dist/pack.d.ts

@@ -0,0 +1,13 @@
+import type { PackOptions, PackResult } from "./types.js";
+/**
+ * 对 Action Package 执行打包并生成标准 npm Action 压缩包（.tgz）。
+ *
+ * 职责：
+ * - 调用项目本地 TypeScript 编译（Node 执行），输出声明文件（.d.ts）与纯 JavaScript ESM 产物到临时暂存目录。
+ * - 严格校验导出的 Manifest（入口全部指向编译后的 .js/.mjs，不得包含 actionsDir 或 playbooksDir 等废弃目录字段）。
+ * - 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz），严禁使用正则替换与自建 tar 压缩。
+ *
+ * @param options 打包参数选项
+ * @returns 打包结果元数据
+ */
+export declare function packProject(options: PackOptions): Promise<PackResult>;