@actiondock/builder 2.5.1 → 2.6.0

package/dist/index.d.ts

@@ -8,9 +8,10 @@ export { assertNoFileProtocolDeps, assertValidManifestActionIds, serializeManife
 export type { SerializePlanManifestOptions } from "./manifest.js";
 export { createTarGzArchive, createTarGzArchiveAsync, createZipArchive, createZipArchiveAsync, dosDateTime, writeToStream, } from "./archive.js";
 export type { TarGzArchiveOptions } from "./archive.js";
-export { BuildPlanner, buildPlan, SelectionPlanner, selectionPlan } from "./planner.js";
+export { SelectionPlanner } 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";
+export { exportCompositeSkill, exportSkill, exportSkillBatch, SkillExporter, } from "./exporter.js";
+export { findExistingCompositeSkillMd, findExistingSingleSkillMd, } from "./skill-md.js";
+export type { ActionDependency, ArchiveFormat, AssetDependency, BatchSkillExportOptions, BatchSkillExportResult, BuildOptions, BuildPlan, BuildPlanDependencies, BuildResult, CompositeSkillExportOptions, CompositeSkillExportResult, ExternalDependency, LockfileInfo, PackOptions, PackResult, PlaybookPlanEntry, ProjectConfigWithDeclarations, SelectionPlan, SelectionPlannerOptions, SkillExporterOptions, SkillExportResult, } from "./types.js";

package/dist/index.js

@@ -11,11 +11,13 @@ export { assertNoFileProtocolDeps, assertValidManifestActionIds, serializeManife
 // 归档压缩
 export { createTarGzArchive, createTarGzArchiveAsync, createZipArchive, createZipArchiveAsync, dosDateTime, writeToStream, } from "./archive.js";
 // 构建规划
-export { BuildPlanner, buildPlan, SelectionPlanner, selectionPlan } from "./planner.js";
+export { SelectionPlanner } 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";
+// 入口函数与导出器门面位于 ./exporter；SKILL.md 发现能力单一事实源位于 ./skill-md
+export { exportCompositeSkill, exportSkill, exportSkillBatch, SkillExporter, } from "./exporter.js";
+export { findExistingCompositeSkillMd, findExistingSingleSkillMd, } from "./skill-md.js";

package/dist/pack.js

@@ -345,9 +345,23 @@ async function runNpmPack(stagingPkgDir, packDestination, fallbackName) {
     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) {
+            let items;
+            if (Array.isArray(parsed)) {
+                items = parsed;
+            }
+            else if (typeof parsed === "object" && parsed !== null) {
+                // npm >= 11 的 pack --json 输出为按包名索引的对象，取全部包含 filename 的条目
+                items = Object.values(parsed).filter((entry) => typeof entry === "object" && entry !== null && "filename" in entry);
+            }
+            else {
+                items = [];
+            }
+            // 多包输出时取最后一个 filename（npm 按依赖顺序逐包输出，末尾为当前项目产物）
+            const filenames = items
+                .map((item) => item.filename)
+                .filter((name) => typeof name === "string" && name.length > 0);
+            const filename = filenames[filenames.length - 1];
+            if (filename !== undefined) {
                 generatedName = filename;
             }
         }

package/dist/planner.d.ts

@@ -49,20 +49,3 @@ export declare class SelectionPlanner {
      */
     static plan(options: SelectionPlannerOptions): SelectionPlan;
 }
-/**
- * 构建规划器标准导出。
- * @deprecated SelectionPlanner 的历史别名，请直接使用 SelectionPlanner，将在两个版本后移除。
- */
-export declare const BuildPlanner: typeof SelectionPlanner;
-/** @deprecated SelectionPlanner 类型的历史别名，请直接使用 SelectionPlanner 类型。 */
-export type BuildPlanner = SelectionPlanner;
-/**
- * 快捷选择规划函数。
- * @deprecated 便捷快捷函数，请直接使用 SelectionPlanner.plan，将在两个版本后移除。
- */
-export declare function selectionPlan(options: SelectionPlannerOptions): SelectionPlan;
-/**
- * 快捷构建规划函数标准导出。
- * @deprecated selectionPlan 的历史别名，请改用 SelectionPlanner.plan，将在两个版本后移除。
- */
-export declare const buildPlan: typeof selectionPlan;

package/dist/planner.js

@@ -670,20 +670,3 @@ export class SelectionPlanner {
         return planner.plan(options);
     }
 }
-/**
- * 构建规划器标准导出。
- * @deprecated SelectionPlanner 的历史别名，请直接使用 SelectionPlanner，将在两个版本后移除。
- */
-export const BuildPlanner = SelectionPlanner;
-/**
- * 快捷选择规划函数。
- * @deprecated 便捷快捷函数，请直接使用 SelectionPlanner.plan，将在两个版本后移除。
- */
-export function selectionPlan(options) {
-    return SelectionPlanner.plan(options);
-}
-/**
- * 快捷构建规划函数标准导出。
- * @deprecated selectionPlan 的历史别名，请改用 SelectionPlanner.plan，将在两个版本后移除。
- */
-export const buildPlan = selectionPlan;

package/dist/skill-md.d.ts

@@ -0,0 +1,47 @@
+import { type CompositeCustomDeclaration, type PlaybookDefinition, type ProjectConfig, type SkillActionItem } from "@actiondock/core";
+import type { CompositeSkillExportOptions, SelectionPlan } from "./types.js";
+/**
+ * SKILL.md 发现、复用与模板视图适配层。
+ *
+ * 职责单一聚焦：定位项目中已有的 SKILL.md（单包与复合套件两种检索策略）、
+ * 解析自定义说明书声明，并将规划产物适配为模板生成所需视图。
+ */
+/** 供模板生成使用的 SkillActionItem 兼容视图 */
+type PlanActionView = SkillActionItem;
+/**
+ * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
+ */
+export declare function toSkillActionItems(actions: SelectionPlan["actions"]): PlanActionView[];
+/**
+ * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
+ */
+export declare function toPlaybookDefinitions(playbooks: SelectionPlan["playbooks"]): PlaybookDefinition[];
+/**
+ * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
+ */
+export declare function findExistingSingleSkillMd(projectRoot: string, explicitPath?: string, pkgSlug?: string): string | undefined;
+/**
+ * 检索复合套件工作区中已存在的 SKILL.md 文件。
+ */
+export declare function findExistingCompositeSkillMd(options: CompositeSkillExportOptions): string | undefined;
+/**
+ * 解析复合技能自定义说明书：显式 customMdPath 优先（缺失即报错），
+ * 否则按 `SKILL.custom.md` 约定名在工作区根目录与当前目录自动发现。
+ */
+export declare function resolveCustomSkillDeclaration(options: CompositeSkillExportOptions): (CompositeCustomDeclaration & {
+    file: string;
+}) | undefined;
+/**
+ * 复制或生成 SKILL.md 到目标目录。
+ * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
+ */
+export declare function writeSkillMd(root: string, destDir: string, plan: SelectionPlan, options: {
+    skipSkillMd?: boolean;
+    skillMdPath?: string;
+    pkgSlug: string;
+}, generate: () => string): string | undefined;
+/**
+ * 构造模板生成所需的 ProjectConfig 视图。
+ */
+export declare function buildConfigForTemplates(plan: SelectionPlan, actionsDir: string, playbooksDir: string): ProjectConfig;
+export {};

package/dist/skill-md.js

@@ -0,0 +1,166 @@
+import { copyFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { COMPOSITE_CUSTOM_DECLARATION_FILE, parseCustomSkillDeclaration, getPackageSlug, } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+/**
+ * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
+ */
+export function toSkillActionItems(actions) {
+    return actions;
+}
+/**
+ * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
+ */
+export function toPlaybookDefinitions(playbooks) {
+    return playbooks;
+}
+/**
+ * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
+ */
+export function findExistingSingleSkillMd(projectRoot, explicitPath, pkgSlug) {
+    if (explicitPath && existsSync(explicitPath)) {
+        try {
+            if (statSync(explicitPath).isFile())
+                return resolve(explicitPath);
+        }
+        catch {
+            // 忽略文件属性读取异常
+        }
+    }
+    const candidates = [
+        join(projectRoot, "SKILL.md"),
+        join(projectRoot, "skill.md"),
+        join(projectRoot, "skills", "SKILL.md"),
+        join(projectRoot, "skills", "skill.md"),
+    ];
+    if (pkgSlug) {
+        candidates.push(join(projectRoot, "skills", pkgSlug, "SKILL.md"), join(projectRoot, "skills", pkgSlug, "skill.md"));
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            try {
+                if (statSync(candidate).isFile())
+                    return resolve(candidate);
+            }
+            catch {
+                // 忽略文件属性读取异常
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * 检索复合套件工作区中已存在的 SKILL.md 文件。
+ */
+export function findExistingCompositeSkillMd(options) {
+    if (options.skillMdPath && existsSync(options.skillMdPath)) {
+        try {
+            if (statSync(options.skillMdPath).isFile())
+                return resolve(options.skillMdPath);
+        }
+        catch {
+            // 忽略文件属性读取异常
+        }
+    }
+    const bundleSlug = getPackageSlug(options.bundleName);
+    const searchDirs = new Set();
+    if (options.workspaceRoot && existsSync(options.workspaceRoot)) {
+        searchDirs.add(resolve(options.workspaceRoot));
+    }
+    searchDirs.add(process.cwd());
+    for (const root of options.projectRoots) {
+        const absRoot = resolve(root);
+        // 仅搜索父目录（工作区根）一级；祖父目录搜索可能命中毫不相关的全局 SKILL.md 并复制进产物
+        searchDirs.add(dirname(absRoot));
+    }
+    const candidateRelativePaths = [
+        join("skills", options.bundleName, "SKILL.md"),
+        join("skills", bundleSlug, "SKILL.md"),
+        join("skills", "SKILL.md"),
+        "SKILL.md",
+        join("skills", options.bundleName, "skill.md"),
+        join("skills", bundleSlug, "skill.md"),
+        join("skills", "skill.md"),
+        "skill.md",
+    ];
+    for (const dir of searchDirs) {
+        for (const rel of candidateRelativePaths) {
+            const fullPath = join(dir, rel);
+            if (existsSync(fullPath)) {
+                try {
+                    if (statSync(fullPath).isFile())
+                        return fullPath;
+                }
+                catch {
+                    // 忽略文件属性读取异常
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * 解析复合技能自定义说明书：显式 customMdPath 优先（缺失即报错），
+ * 否则按 `SKILL.custom.md` 约定名在工作区根目录与当前目录自动发现。
+ */
+export function resolveCustomSkillDeclaration(options) {
+    let filePath;
+    if (options.customMdPath) {
+        if (!existsSync(options.customMdPath)) {
+            throw new BuilderError(`Custom skill declaration file not found: '${options.customMdPath}'`);
+        }
+        filePath = resolve(options.customMdPath);
+    }
+    else {
+        const searchDirs = [options.workspaceRoot, process.cwd()].filter(Boolean);
+        for (const dir of searchDirs) {
+            const candidate = join(resolve(dir), COMPOSITE_CUSTOM_DECLARATION_FILE);
+            if (existsSync(candidate)) {
+                filePath = candidate;
+                break;
+            }
+        }
+    }
+    if (!filePath) {
+        return undefined;
+    }
+    return {
+        file: filePath,
+        ...parseCustomSkillDeclaration(readFileSync(filePath, "utf-8")),
+    };
+}
+/**
+ * 复制或生成 SKILL.md 到目标目录。
+ * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
+ */
+export function writeSkillMd(root, destDir, plan, options, generate) {
+    const existingSkill = options.skipSkillMd
+        ? undefined
+        : findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug);
+    if (existingSkill) {
+        const destSkillMd = join(destDir, "SKILL.md");
+        if (resolve(existingSkill) !== resolve(destSkillMd)) {
+            copyFileSync(existingSkill, destSkillMd);
+        }
+        return existingSkill;
+    }
+    if (!options.skipSkillMd) {
+        writeFileSync(join(destDir, "SKILL.md"), generate(), "utf-8");
+    }
+    return undefined;
+}
+/**
+ * 构造模板生成所需的 ProjectConfig 视图。
+ */
+export function buildConfigForTemplates(plan, actionsDir, playbooksDir) {
+    return {
+        id: plan.packageId,
+        name: plan.packageName,
+        version: plan.version,
+        description: plan.description,
+        actionsDir,
+        playbooksDir,
+        // 声明性配置字典在规划侧为宽松结构，模板仅透传展示
+        config: plan.configDefs,
+    };
+}

package/dist/types.d.ts

@@ -138,9 +138,9 @@ export interface BuildPlan {
  */
 export type SelectionPlan = BuildPlan;
 /**
- * 构建规划器配置选项。
+ * 声明式选择规划器配置选项。
  */
-export interface BuildPlannerOptions {
+export interface SelectionPlannerOptions {
     /** 项目根目录绝对路径 */
     projectRoot: string;
     /** 显式传入的项目配置（若未提供则从 actiondock.json 读取） */
@@ -164,10 +164,6 @@ export interface BuildPlannerOptions {
     /** 是否跳过本地相对依赖完整性校验（默认 false） */
     skipDependencyValidation?: boolean;
 }
-/**
- * 声明式选择规划器配置选项别名。
- */
-export type SelectionPlannerOptions = BuildPlannerOptions;
 /**
  * 归档压缩格式。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "ActionDock Build Planner, distribution packaging, and Skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,9 +29,9 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.5.1",
-    "@actiondock/runtime-node": "^2.5.1",
-    "@actiondock/sdk": "^2.5.1"
+    "@actiondock/core": "^2.6.0",
+    "@actiondock/runtime-node": "^2.6.0",
+    "@actiondock/sdk": "^2.6.0"
   },
   "keywords": [
     "actiondock",