@actiondock/builder 2.0.12 → 2.2.0

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

package/dist/pack.js

@@ -0,0 +1,339 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { getPackageSlug, loadProjectConfig } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+import { assertNoFileProtocolDeps, assertValidManifestActionIds, normalizePkgExportsAndEngines, readPackageJson, serializePlanManifest, } from "./manifest.js";
+import { collectRelativeFiles } from "./fs-utils.js";
+import { SelectionPlanner } from "./planner.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 async function packProject(options) {
+    const root = resolve(options.projectRoot);
+    const pkgConfig = options.config || loadProjectConfig(root);
+    const plan = SelectionPlanner.plan({
+        projectRoot: root,
+        config: pkgConfig,
+        manifest: options.manifest,
+    });
+    if (plan.actions.length === 0) {
+        throw new BuilderError("No actions resolved for packing");
+    }
+    const pkgSlug = getPackageSlug(plan.packageId);
+    const pkgJsonPath = join(root, "package.json");
+    if (!existsSync(pkgJsonPath)) {
+        throw new BuilderError(`package.json not found in project root: ${root}`);
+    }
+    const sourcePkgJson = readPackageJson(pkgJsonPath);
+    // 校验生产依赖合法性（禁止 file: 本地协议）
+    assertNoFileProtocolDeps(sourcePkgJson.dependencies, "packed packages");
+    // 创建干净临时目录，确保不改写源工程
+    const tempBase = mkdtempSync(join(tmpdir(), "ad-pack-"));
+    const stagingPkgDir = join(tempBase, "package");
+    mkdirSync(stagingPkgDir, { recursive: true });
+    try {
+        await compileTypeScript(root, stagingPkgDir, plan);
+        stageSources(root, stagingPkgDir, plan);
+        writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson);
+        // 收集打包文件相对清单与摘要
+        const relativeFiles = collectRelativeFiles(stagingPkgDir);
+        const manifestSummary = {
+            actionsCount: plan.actions.length,
+            actions: plan.actions.map((a) => a.id),
+            assetsCount: plan.assets.length,
+            filesCount: relativeFiles.length,
+        };
+        const tarballName = `${pkgSlug}-${plan.version}.tgz`;
+        const targetOutDir = resolve(options.outDir || join(root, "dist"));
+        if (options.dryRun) {
+            return {
+                packageId: plan.packageId,
+                packageName: plan.packageName,
+                version: plan.version,
+                tarballName,
+                sizeBytes: 0,
+                sha256: "",
+                files: relativeFiles,
+                manifestSummary,
+            };
+        }
+        mkdirSync(targetOutDir, { recursive: true });
+        const finalTarballPath = join(targetOutDir, tarballName);
+        if (existsSync(finalTarballPath)) {
+            rmSync(finalTarballPath, { force: true });
+        }
+        const generatedTarball = await runNpmPack(stagingPkgDir, tempBase, tarballName);
+        copyFileSync(generatedTarball, finalTarballPath);
+        rmSync(generatedTarball, { force: true });
+        const stat = statSync(finalTarballPath);
+        const fileBuf = readFileSync(finalTarballPath);
+        const sha256 = createHash("sha256").update(fileBuf).digest("hex");
+        return {
+            packageId: plan.packageId,
+            packageName: plan.packageName,
+            version: plan.version,
+            tarballPath: finalTarballPath,
+            tarballName,
+            sizeBytes: stat.size,
+            sha256,
+            files: relativeFiles,
+            manifestSummary,
+        };
+    }
+    finally {
+        if (existsSync(tempBase)) {
+            rmSync(tempBase, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+        }
+    }
+}
+/**
+ * 判断文件路径是否为 TypeScript 源码。
+ */
+function isTypeScriptSource(path) {
+    return path.endsWith(".ts") || path.endsWith(".mts");
+}
+/**
+ * 解析项目本地 TypeScript 编译器（回退到打包工具自身依赖）。
+ */
+async function resolveTypeScriptCompiler(root) {
+    try {
+        const req = createRequire(join(root, "package.json"));
+        const tsPath = req.resolve("typescript");
+        const imported = await import(tsPath);
+        return imported.default || imported;
+    }
+    catch {
+        try {
+            const imported = await import("typescript");
+            return imported.default || imported;
+        }
+        catch {
+            throw new BuilderError(`TypeScript is required to pack TypeScript Action packages, but 'typescript' could not be resolved from ${root}.`);
+        }
+    }
+}
+/**
+ * 在暂存目录内执行 TypeScript 编译，产出 .js 与 .d.ts。
+ * 仅在存在 TypeScript 源码时执行。
+ */
+async function compileTypeScript(root, stagingPkgDir, plan) {
+    const hasTypeScript = plan.actions.some((a) => isTypeScriptSource(a.entry)) ||
+        plan.dependencies.modulesAndAssets.some((m) => (m.type === "module" || m.type === "file") && isTypeScriptSource(m.path));
+    if (!hasTypeScript) {
+        return;
+    }
+    const ts = await resolveTypeScriptCompiler(root);
+    const tsSourceFiles = new Set();
+    for (const act of plan.actions) {
+        if (act.isExternal || act.id.includes("/"))
+            continue;
+        if (isTypeScriptSource(act.entry)) {
+            tsSourceFiles.add(act.resolvedPath);
+        }
+    }
+    for (const mod of plan.dependencies.modulesAndAssets) {
+        if ((mod.type === "module" || mod.type === "file") && isTypeScriptSource(mod.path)) {
+            tsSourceFiles.add(mod.resolvedPath);
+        }
+    }
+    const compilerOptions = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        declaration: true,
+        emitDeclarationOnly: false,
+        rewriteRelativeImportExtensions: true,
+        rootDir: root,
+        outDir: stagingPkgDir,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        allowJs: true,
+    };
+    const tsconfigPath = join(root, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+        try {
+            const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+            if (!configFile.error) {
+                const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, root);
+                Object.assign(compilerOptions, parsedConfig.options, {
+                    outDir: stagingPkgDir,
+                    rootDir: root,
+                    declaration: true,
+                    emitDeclarationOnly: false,
+                    rewriteRelativeImportExtensions: true,
+                    noEmit: false,
+                });
+            }
+        }
+        catch {
+            // 忽略 tsconfig 解析失败，回退到标准 compilerOptions
+        }
+    }
+    const host = ts.createCompilerHost(compilerOptions);
+    const program = ts.createProgram(Array.from(tsSourceFiles), compilerOptions, host);
+    const emitResult = program.emit();
+    const preEmitDiagnostics = ts.getPreEmitDiagnostics(program);
+    const allDiagnostics = [...preEmitDiagnostics, ...emitResult.diagnostics];
+    const errors = allDiagnostics.filter((d) => d.category === ts.DiagnosticCategory.Error);
+    if (errors.length > 0 || emitResult.emitSkipped) {
+        const diagnosticsToFormat = errors.length > 0 ? errors : allDiagnostics;
+        const formatted = ts.formatDiagnosticsWithColorAndContext(diagnosticsToFormat, {
+            getCanonicalFileName: (f) => f,
+            getCurrentDirectory: () => root,
+            getNewLine: () => "\n",
+        });
+        throw new BuilderError(`TypeScript compilation failed during pack:\n${formatted}`);
+    }
+}
+/**
+ * 拷贝声明的非 TypeScript 模块、静态资产、原生 JavaScript 入口、Playbook 与基础文档到暂存目录。
+ */
+function stageSources(root, stagingPkgDir, plan) {
+    // 拷贝声明的非 TypeScript 模块与静态资产
+    for (const dep of plan.dependencies.modulesAndAssets) {
+        if ((dep.type === "asset" || dep.type === "module" || dep.type === "file") &&
+            existsSync(dep.resolvedPath)) {
+            if (isTypeScriptSource(dep.path)) {
+                continue; // 已由 TypeScript 编译生成 .js 与 .d.ts
+            }
+            const destPath = join(stagingPkgDir, dep.path);
+            mkdirSync(dirname(destPath), { recursive: true });
+            copyFileSync(dep.resolvedPath, destPath);
+        }
+    }
+    // 拷贝原生 JavaScript Action 入口（若存在）
+    for (const act of plan.actions) {
+        if (!isTypeScriptSource(act.entry)) {
+            const destPath = join(stagingPkgDir, act.entry);
+            mkdirSync(dirname(destPath), { recursive: true });
+            copyFileSync(act.resolvedPath, destPath);
+        }
+    }
+    // 拷贝 Playbook 规程文件
+    for (const pb of plan.playbooks) {
+        if (existsSync(pb.filePath)) {
+            const destPb = join(stagingPkgDir, relative(root, pb.filePath));
+            mkdirSync(dirname(destPb), { recursive: true });
+            copyFileSync(pb.filePath, destPb);
+        }
+    }
+    // 拷贝 README 等基础文档（若存在）
+    for (const doc of ["README.md", "readme.md", "LICENSE", "license"]) {
+        const srcDoc = join(root, doc);
+        if (existsSync(srcDoc)) {
+            copyFileSync(srcDoc, join(stagingPkgDir, doc));
+        }
+    }
+}
+/**
+ * 计算编译后的 Action 入口相对路径（.ts 转 .js、.mts 转 .mjs）。
+ */
+function compiledEntryFor(action) {
+    if (action.entry.endsWith(".ts")) {
+        return action.entry.slice(0, -3) + ".js";
+    }
+    if (action.entry.endsWith(".mts")) {
+        return action.entry.slice(0, -4) + ".mjs";
+    }
+    return action.entry;
+}
+/**
+ * 生成并写入严格校验后的 actiondock.json 与规范化 package.json。
+ */
+function writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson) {
+    // 构建编译后的 Action 清单字典并严格校验入口扩展名
+    const compiledEntries = new Map();
+    for (const act of plan.actions) {
+        if (act.isExternal || act.id.includes("/"))
+            continue;
+        const destEntry = compiledEntryFor(act);
+        if (!destEntry.endsWith(".js") && !destEntry.endsWith(".mjs")) {
+            throw new BuilderError(`Action '${act.id}' entry '${destEntry}' must point to compiled .js or .mjs`);
+        }
+        if (!existsSync(join(stagingPkgDir, destEntry))) {
+            throw new BuilderError(`Compiled action entry file not found: ${destEntry}`);
+        }
+        compiledEntries.set(act.id, destEntry);
+    }
+    // 严格生成与校验 actiondock.json（严禁包含废弃 actionsDir 或 playbooksDir 字段）
+    const packedConfig = serializePlanManifest(plan, {
+        includeSchema: true,
+        configBeforeActions: true,
+        includePlaybooks: false,
+        actionEntryOverride: (act) => compiledEntries.get(act.id),
+    });
+    if ("actionsDir" in packedConfig || "playbooksDir" in packedConfig) {
+        throw new BuilderError("Packed manifest must not contain deprecated fields 'actionsDir' or 'playbooksDir'.");
+    }
+    if (packedConfig.actions && typeof packedConfig.actions === "object") {
+        assertValidManifestActionIds(packedConfig.actions);
+    }
+    writeFileSync(join(stagingPkgDir, "actiondock.json"), JSON.stringify(packedConfig, null, 2) + "\n", "utf-8");
+    // 规范化 package.json：导出 ./actiondock.json，设定 node 引擎约束与 ESM 类型
+    const normalizedPkg = normalizePkgExportsAndEngines(sourcePkgJson);
+    writeFileSync(join(stagingPkgDir, "package.json"), JSON.stringify(normalizedPkg, null, 2) + "\n", "utf-8");
+}
+/**
+ * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
+ * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
+ * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ */
+async function runNpmPack(stagingPkgDir, packDestination, fallbackName) {
+    const { stdout } = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", packDestination], {
+            cwd: stagingPkgDir,
+            shell: process.platform === "win32",
+        });
+        let stdoutBuf = "";
+        let stderrBuf = "";
+        child.stdout.on("data", (chunk) => (stdoutBuf += chunk));
+        child.stderr.on("data", (chunk) => (stderrBuf += chunk));
+        child.on("error", rejectPromise);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolvePromise({ stdout: stdoutBuf, stderr: stderrBuf });
+            }
+            else {
+                rejectPromise(new BuilderError(`npm pack exited with code ${code}. Output:\n${stdoutBuf}\n${stderrBuf}`));
+            }
+        });
+    });
+    // 优先解析 --json 结构化输出中的压缩包文件名
+    let generatedName;
+    const trimmed = stdout.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            const filename = items[0]?.filename;
+            if (typeof filename === "string" && filename.length > 0) {
+                generatedName = filename;
+            }
+        }
+        catch {
+            // 回退到尾部行解析
+        }
+    }
+    if (!generatedName) {
+        const packLines = trimmed.split("\n");
+        generatedName = packLines.pop()?.trim() || fallbackName;
+    }
+    const generatedTarball = join(packDestination, generatedName);
+    if (!existsSync(generatedTarball)) {
+        throw new BuilderError(`npm pack did not produce expected tarball at ${generatedTarball}. Output:\n${stdout}`);
+    }
+    return generatedTarball;
+}