@actiondock/builder 2.0.12 → 2.2.1

package/dist/dependency-check.js

@@ -0,0 +1,246 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { isPathOutsideBoundary } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+/**
+ * 移除源码中的单行与多行注释，防止注释内的相对路径字符串误触发依赖解析。
+ */
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "");
+}
+/**
+ * 从源码中快速提取以相对路径（./ 或 ../）引入的静态或动态导入说明符。
+ */
+export function extractRelativeSpecifiers(source) {
+    const cleanSource = stripComments(source);
+    const specifiers = new Set();
+    // 1. 无 from 的直接副作用导入：import "./side-effect.js"
+    const sideEffectRegex = /\bimport\s+['"](\.{1,2}(?:\/[^'"]*)?)['"]/g;
+    let match;
+    while ((match = sideEffectRegex.exec(cleanSource)) !== null) {
+        if (match[1]) {
+            specifiers.add(match[1]);
+        }
+    }
+    // 2. 静态 import 与 export 携带 from 语句：import { x } from "./x.js", export * from "./y.js"
+    const fromRegex = /\b(?:import|export)(?:\s+type)?\s+(?:[^;"']*?)\s+from\s+['"](\.{1,2}(?:\/[^'"]*)?)['"]/g;
+    while ((match = fromRegex.exec(cleanSource)) !== null) {
+        if (match[1]) {
+            specifiers.add(match[1]);
+        }
+    }
+    // 3. 动态 import() 与 require()
+    const dynamicRegex = /\b(?:import|require)\s*\(\s*['"](\.{1,2}(?:\/[^'"]*)?)['"]\s*\)/g;
+    while ((match = dynamicRegex.exec(cleanSource)) !== null) {
+        if (match[1]) {
+            specifiers.add(match[1]);
+        }
+    }
+    return Array.from(specifiers);
+}
+/**
+ * 支持的候选扩展名列表。
+ */
+const RESOLUTION_EXTENSIONS = [
+    "",
+    ".ts",
+    ".js",
+    ".mts",
+    ".mjs",
+    ".tsx",
+    ".jsx",
+    ".cjs",
+    ".cts",
+    ".json",
+];
+/**
+ * 将相对模块说明符解析为磁盘上的物理真实文件路径。
+ */
+export function resolveRelativeModule(fromDir, specifier) {
+    const basePath = resolve(fromDir, specifier);
+    // 1. 精确匹配文件
+    if (existsSync(basePath) && statSync(basePath).isFile()) {
+        try {
+            return realpathSync(basePath);
+        }
+        catch {
+            return basePath;
+        }
+    }
+    // 2. ESM TypeScript 映射：导入写了 .js / .mjs / .cjs，但在源码中真实文件为 .ts / .mts / .cts
+    if (specifier.endsWith(".js")) {
+        const tsCandidate = basePath.slice(0, -3) + ".ts";
+        if (existsSync(tsCandidate) && statSync(tsCandidate).isFile()) {
+            try {
+                return realpathSync(tsCandidate);
+            }
+            catch {
+                return tsCandidate;
+            }
+        }
+        const tsxCandidate = basePath.slice(0, -3) + ".tsx";
+        if (existsSync(tsxCandidate) && statSync(tsxCandidate).isFile()) {
+            try {
+                return realpathSync(tsxCandidate);
+            }
+            catch {
+                return tsxCandidate;
+            }
+        }
+    }
+    else if (specifier.endsWith(".mjs")) {
+        const mtsCandidate = basePath.slice(0, -4) + ".mts";
+        if (existsSync(mtsCandidate) && statSync(mtsCandidate).isFile()) {
+            try {
+                return realpathSync(mtsCandidate);
+            }
+            catch {
+                return mtsCandidate;
+            }
+        }
+    }
+    else if (specifier.endsWith(".cjs")) {
+        const ctsCandidate = basePath.slice(0, -4) + ".cts";
+        if (existsSync(ctsCandidate) && statSync(ctsCandidate).isFile()) {
+            try {
+                return realpathSync(ctsCandidate);
+            }
+            catch {
+                return ctsCandidate;
+            }
+        }
+    }
+    // 3. 补充扩展名尝试
+    for (const ext of RESOLUTION_EXTENSIONS) {
+        const cand = basePath + ext;
+        if (existsSync(cand) && statSync(cand).isFile()) {
+            try {
+                return realpathSync(cand);
+            }
+            catch {
+                return cand;
+            }
+        }
+    }
+    // 4. 目录默认 index 尝试
+    for (const ext of RESOLUTION_EXTENSIONS) {
+        if (ext === "")
+            continue;
+        const cand = join(basePath, `index${ext}`);
+        if (existsSync(cand) && statSync(cand).isFile()) {
+            try {
+                return realpathSync(cand);
+            }
+            catch {
+                return cand;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * 断言 Action 源码中引用的本地相对模块已全部纳入导出规划。
+ * 若发现引用了未被 actions 或 files 声明收集的本地文件，直接抛出 BuilderError 终止构建。
+ */
+export function assertRelativeDependenciesIntegrity(projectRoot, plan) {
+    const root = resolve(projectRoot);
+    let realRoot;
+    try {
+        realRoot = existsSync(root) ? realpathSync(root) : root;
+    }
+    catch {
+        realRoot = root;
+    }
+    // 收集已包含在构建规划中的全部文件物理绝对路径
+    const collectedPaths = new Set();
+    for (const act of plan.actions) {
+        if (act.resolvedPath) {
+            try {
+                const real = existsSync(act.resolvedPath)
+                    ? realpathSync(act.resolvedPath)
+                    : resolve(act.resolvedPath);
+                collectedPaths.add(real);
+            }
+            catch {
+                collectedPaths.add(resolve(act.resolvedPath));
+            }
+        }
+    }
+    for (const dep of plan.dependencies.modulesAndAssets) {
+        if (dep.resolvedPath) {
+            try {
+                const real = existsSync(dep.resolvedPath)
+                    ? realpathSync(dep.resolvedPath)
+                    : resolve(dep.resolvedPath);
+                collectedPaths.add(real);
+            }
+            catch {
+                collectedPaths.add(resolve(dep.resolvedPath));
+            }
+        }
+    }
+    // 待校验文件队列（包括全部 Action 及其收集的 TS/JS 模块）
+    const queue = [];
+    for (const act of plan.actions) {
+        if (act.resolvedPath && existsSync(act.resolvedPath)) {
+            try {
+                queue.push({
+                    file: existsSync(act.resolvedPath)
+                        ? realpathSync(act.resolvedPath)
+                        : resolve(act.resolvedPath),
+                    actionId: act.id,
+                });
+            }
+            catch {
+                queue.push({
+                    file: resolve(act.resolvedPath),
+                    actionId: act.id,
+                });
+            }
+        }
+    }
+    const visited = new Set();
+    while (queue.length > 0) {
+        const { file, actionId } = queue.shift();
+        if (visited.has(file))
+            continue;
+        visited.add(file);
+        let content;
+        try {
+            content = readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const specifiers = extractRelativeSpecifiers(content);
+        for (const specifier of specifiers) {
+            const resolvedTarget = resolveRelativeModule(dirname(file), specifier);
+            if (!resolvedTarget) {
+                // 相对路径对应的文件在磁盘上不存在
+                const relFromFile = relative(realRoot, file).replace(/\\/g, "/");
+                throw new BuilderError(`Action '${actionId}' (${relFromFile}) imports relative module '${specifier}', but the file does not exist on disk.`, "FILE_NOT_FOUND");
+            }
+            // 检查目标文件是否越出项目根目录
+            const relToRoot = relative(realRoot, resolvedTarget);
+            if (isPathOutsideBoundary(relToRoot) || resolve(resolvedTarget) === resolve(realRoot, "..")) {
+                throw new BuilderError(`Action '${actionId}' imports relative module '${specifier}', which resolves outside project root: '${resolvedTarget}'. External relative imports outside project root are not allowed in exported Skill packages.`, "EXTERNAL_LOCAL_DEPENDENCY");
+            }
+            // 检查目标文件是否在构建收集集合中
+            if (!collectedPaths.has(resolvedTarget)) {
+                const normalizedRel = relToRoot.replace(/\\/g, "/");
+                const fromRel = relative(realRoot, file).replace(/\\/g, "/");
+                throw new BuilderError(`Action '${actionId}' (${fromRel}) imports relative module '${specifier}' (resolving to '${normalizedRel}'), which is not included in the export plan.\nTo fix this, declare '${normalizedRel}' or its parent directory in the 'files' field of actiondock.json.`, "UNMET_LOCAL_DEPENDENCY");
+            }
+            // 如果引用的目标文件本身也是已收集的 TS/JS 代码文件，且尚未遍历过，加入队列递归检查
+            if ((resolvedTarget.endsWith(".ts") ||
+                resolvedTarget.endsWith(".js") ||
+                resolvedTarget.endsWith(".mts") ||
+                resolvedTarget.endsWith(".mjs") ||
+                resolvedTarget.endsWith(".tsx") ||
+                resolvedTarget.endsWith(".jsx")) &&
+                !visited.has(resolvedTarget)) {
+                queue.push({ file: resolvedTarget, actionId });
+            }
+        }
+    }
+}

package/dist/errors.d.ts

@@ -1,8 +1,9 @@
 /**
- * Builder 模块基础错误类。
+ * 构建模块基础错误类。
  */
 export declare class BuilderError extends Error {
-    constructor(message: string);
+    readonly code?: string;
+    constructor(message: string, code?: string);
 }
 /**
  * 构建规划阶段抛出的错误。
@@ -11,31 +12,3 @@ export declare class PlannerError extends BuilderError {
     readonly code: string;
     constructor(message: string, code?: string);
 }
-/**
- * 编译器参数与目标平台校验错误。
- */
-export declare class CompilerValidationError extends BuilderError {
-    readonly code: string;
-    readonly target?: string;
-    constructor(message: string, options?: {
-        code?: string;
-        target?: string;
-    });
-}
-/**
- * 编译器调用执行失败错误。包含标准化错误码与详情。
- */
-export declare class CompilerError extends BuilderError {
-    readonly code: string;
-    readonly exitCode: number;
-    readonly rawError: string;
-    readonly details: string[];
-    readonly target?: string;
-    constructor(message: string, options: {
-        code: string;
-        exitCode: number;
-        rawError: string;
-        details?: string[];
-        target?: string;
-    });
-}

package/dist/errors.js

@@ -0,0 +1,22 @@
+/**
+ * 构建模块基础错误类。
+ */
+export class BuilderError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "BuilderError";
+        this.code = code;
+    }
+}
+/**
+ * 构建规划阶段抛出的错误。
+ */
+export class PlannerError extends BuilderError {
+    code;
+    constructor(message, code = "PLANNER_ERROR") {
+        super(message, code);
+        this.name = "PlannerError";
+        this.code = code;
+    }
+}

package/dist/exporter.d.ts

@@ -1,9 +1,4 @@
-/**
- * 获取内部 @actiondock/* 依赖的版本号规则。
- * 若为主干预发布版本（包含破折号如 -beta / -rc），直接对齐精确版本；普通正式版采用 ^ 范围约束。
- */
-export declare function getInternalDependencyVersion(version?: string): string;
-import type { BatchSkillExportOptions, BatchSkillExportResult, CompositeSkillExportOptions, CompositeSkillExportResult, SkillExporterOptions, SkillExportResult } from "./types";
+import type { BatchSkillExportOptions, BatchSkillExportResult, CompositeSkillExportOptions, CompositeSkillExportResult, SkillExporterOptions, SkillExportResult } from "./types.js";
 /**
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
@@ -14,22 +9,37 @@ export declare function findExistingSingleSkillMd(projectRoot: string, explicitP
 export declare function findExistingCompositeSkillMd(options: CompositeSkillExportOptions): string | undefined;
 /**
  * Agent Skill 导出器。
- * 负责源码型 Skill 与独立二进制型 Skill 的构建、打包与归档分发。
+ * 负责源码型 Skill 与 Node 目录型 Skill 的构建、打包与分发。
  */
 export declare class SkillExporter {
     /**
      * 导出 Skill 产物包。
+     * 主流程仅做编排，各阶段职责由独立函数承担。
      *
      * @param options 导出配置
      * @returns 导出产物详细描述
      */
     export(options: SkillExporterOptions): Promise<SkillExportResult>;
+    /**
+     * Node 目录型 Skill 导出：复用 Node 目录型构建，并在 Skill 内生成调用该入口的 SKILL.md。
+     */
+    private exportNodeSkill;
+    /**
+     * 源码型 Skill 导出：暂存目录内完成清单、说明书与源码装配后原子替换目标目录。
+     */
+    private exportSourceSkill;
+    /**
+     * 静态辅助调用单个 Skill 导出方法。
+     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
+     */
+    static export(options: SkillExporterOptions): Promise<SkillExportResult>;
     /**
      * 批量导出多个 Skill。
      */
     exportBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult>;
     /**
      * 静态辅助调用批量导出方法。
+     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
      */
     static exportBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult>;
     /**
@@ -38,22 +48,22 @@ export declare class SkillExporter {
     exportComposite(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult>;
     /**
      * 静态辅助调用复合导出方法。
+     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
      */
     static exportComposite(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult>;
-    /**
-     * 静态辅助调用方法。
-     */
-    static export(options: SkillExporterOptions): Promise<SkillExportResult>;
 }
 /**
- * 快捷导出 Skill 产物函数。
+ * 导出单个 Skill 产物的顶层便捷函数。
+ * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
  */
 export declare function exportSkill(options: SkillExporterOptions): Promise<SkillExportResult>;
 /**
- * 快捷批量导出多个 Skill 产物函数。
+ * 批量导出多个 Skill 产物的顶层便捷函数。
+ * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
  */
 export declare function exportSkillBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult>;
 /**
- * 快捷复合模式导出 Skill 产物函数。
+ * 导出复合技能套件的顶层便捷函数。
+ * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
  */
 export declare function exportCompositeSkill(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult>;