@actiondock/core 2.0.12 → 2.2.1

package/dist/project/lockfile.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { computeManifestDigest, parseJsonWithoutDuplicates } from "./digest.js";
+import { MANIFEST_FILE_NAME } from "./manifest.js";
+export const LOCKFILE_NAME = "actiondock.lock.json";
+export const LOCKFILE_VERSION = 1;
+/**
+ * 从指定工程根目录读取并解析 actiondock.lock.json 锁文件。
+ * 若文件不存在则返回 null。
+ */
+export function loadLockfile(projectRoot) {
+    const filePath = join(projectRoot, LOCKFILE_NAME);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Failed to read lockfile at ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = parseJsonWithoutDuplicates(raw);
+    }
+    catch (err) {
+        throw new Error(`Corrupted or duplicate keys in lockfile at ${filePath}: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid lockfile format in ${filePath}: expected a JSON object`);
+    }
+    if (parsed.lockfileVersion !== LOCKFILE_VERSION) {
+        throw new Error(`Unsupported lockfileVersion in ${filePath}: received '${parsed.lockfileVersion}', expected ${LOCKFILE_VERSION}`);
+    }
+    if (!parsed.packages || typeof parsed.packages !== "object" || Array.isArray(parsed.packages)) {
+        throw new Error(`Invalid lockfile format in ${filePath}: 'packages' must be an object`);
+    }
+    // 规范化并注入兼容字段
+    for (const [key, item] of Object.entries(parsed.packages)) {
+        if (item && typeof item === "object") {
+            const locked = item;
+            const npmPkg = locked.package || locked.npmPackage || key;
+            const resVer = locked.resolved || locked.version || "0.0.0";
+            locked.package = npmPkg;
+            locked.npmPackage = npmPkg;
+            locked.resolved = resVer;
+            locked.version = resVer;
+            locked.packageId = locked.packageId || key;
+            locked.source = locked.source || "npm";
+        }
+    }
+    return parsed;
+}
+/**
+ * 将锁文件保存至工程根目录（actiondock.lock.json）。
+ * 保证各包按键名升序排序，实现确定性输出。
+ */
+export function saveLockfile(projectRoot, lockfile) {
+    const filePath = join(projectRoot, LOCKFILE_NAME);
+    const sortedPackages = {};
+    const sortedKeys = Object.keys(lockfile.packages || {}).sort();
+    for (const key of sortedKeys) {
+        const pkg = lockfile.packages[key];
+        const npmPackage = pkg.package || pkg.npmPackage || key;
+        const resolvedVersion = pkg.resolved || pkg.version || "0.0.0";
+        const sortedDeps = pkg.dependencies
+            ? Object.keys(pkg.dependencies)
+                .sort()
+                .reduce((acc, depKey) => {
+                acc[depKey] = pkg.dependencies[depKey];
+                return acc;
+            }, {})
+            : undefined;
+        const entry = {
+            package: npmPackage,
+            resolved: resolvedVersion,
+            source: pkg.source || "npm",
+            integrity: pkg.integrity,
+            manifestDigest: pkg.manifestDigest,
+            dependencies: sortedDeps,
+            packageId: pkg.packageId || key,
+            npmPackage: npmPackage,
+            version: resolvedVersion,
+        };
+        sortedPackages[key] = entry;
+    }
+    const payload = {
+        lockfileVersion: LOCKFILE_VERSION,
+        packages: sortedPackages,
+    };
+    writeFileSync(filePath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+}
+/**
+ * 校验锁文件结构的合法性及内容完整性。
+ * 当提供 projectRoot 时，逐一比对各包实际 actiondock.json 的 RFC 8785 manifestDigest，
+ * 若摘要不一致，校验失败并提示需要重新解析。
+ */
+export function validateLockfile(lockfile, options) {
+    if (!lockfile || typeof lockfile !== "object" || Array.isArray(lockfile)) {
+        return { valid: false, errors: ["Lockfile must be an object"] };
+    }
+    const lf = lockfile;
+    const errors = [];
+    if (lf.lockfileVersion !== LOCKFILE_VERSION) {
+        errors.push(`Lockfile 'lockfileVersion' must be ${LOCKFILE_VERSION} (received '${lf.lockfileVersion}')`);
+    }
+    if (!lf.packages || typeof lf.packages !== "object" || Array.isArray(lf.packages)) {
+        errors.push("Lockfile 'packages' must be an object");
+        return { valid: false, errors };
+    }
+    for (const [key, item] of Object.entries(lf.packages)) {
+        if (!item || typeof item !== "object") {
+            errors.push(`Package entry '${key}' must be an object`);
+            continue;
+        }
+        const pkgName = item.package || item.npmPackage;
+        if (!pkgName || typeof pkgName !== "string") {
+            errors.push(`Package '${key}' missing required string property 'package'`);
+        }
+        const resolved = item.resolved || item.version;
+        if (!resolved || typeof resolved !== "string") {
+            errors.push(`Package '${key}' missing required string property 'resolved'`);
+        }
+        if (!item.manifestDigest || typeof item.manifestDigest !== "string") {
+            errors.push(`Package '${key}' missing required string property 'manifestDigest'`);
+        }
+        // 检查项目根目录下的实际清单摘要匹配性
+        if (options?.projectRoot && item.manifestDigest) {
+            let manifestPath = null;
+            const rootManifestPath = join(options.projectRoot, MANIFEST_FILE_NAME);
+            // 若为当前工程根包
+            if (existsSync(rootManifestPath)) {
+                try {
+                    const rootRaw = readFileSync(rootManifestPath, "utf-8");
+                    const rootParsed = parseJsonWithoutDuplicates(rootRaw);
+                    if (rootParsed.id === (item.packageId || key)) {
+                        manifestPath = rootManifestPath;
+                    }
+                }
+                catch {
+                    // 忽略解析异常
+                }
+            }
+            // 若为外部依赖包，从 node_modules 探测
+            if (!manifestPath && pkgName) {
+                const candidateNpm = join(options.projectRoot, "node_modules", pkgName, MANIFEST_FILE_NAME);
+                const candidateId = join(options.projectRoot, "node_modules", key, MANIFEST_FILE_NAME);
+                if (existsSync(candidateNpm)) {
+                    manifestPath = candidateNpm;
+                }
+                else if (existsSync(candidateId)) {
+                    manifestPath = candidateId;
+                }
+            }
+            if (manifestPath && existsSync(manifestPath)) {
+                try {
+                    const manifestRaw = readFileSync(manifestPath, "utf-8");
+                    const actualParsed = parseJsonWithoutDuplicates(manifestRaw);
+                    const actualDigest = computeManifestDigest(actualParsed);
+                    if (actualDigest !== item.manifestDigest) {
+                        errors.push(`Manifest digest mismatch for package '${item.packageId || key}': expected '${item.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
+                    }
+                }
+                catch (err) {
+                    errors.push(`Failed to verify manifest digest for package '${item.packageId || key}': ${err.message}`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined,
+    };
+}

package/dist/project/manifest.d.ts

@@ -1,12 +1,14 @@
-import type { ActionDockManifest, ActionManifestEntry, ManifestSyncResult, SyncManifestOptions } from "./types";
-export declare const MANIFEST_FILE_NAME = "actiondock.manifest.json";
+import type { ActionDockManifest } from "./types.js";
+export declare const MANIFEST_FILE_NAME = "actiondock.json";
+export declare const ACTION_ID_REGEX: RegExp;
+export declare const PLAYBOOK_ID_REGEX: RegExp;
 /**
- * 读取并解析项目的声明式清单文件。
+ * 读取并解析项目的声明式清单文件（actiondock.json 为唯一事实源）。
  * 若文件不存在则返回 null。
  */
 export declare function loadManifest(projectRoot: string): ActionDockManifest | null;
 /**
- * 保存声明式清单文件至项目根目录。
+ * 保存声明式清单文件至项目根目录（actiondock.json）。
  */
 export declare function saveManifest(projectRoot: string, manifest: ActionDockManifest): void;
 /**
@@ -18,27 +20,3 @@ export declare function validateManifest(manifest: unknown, options?: {
     valid: boolean;
     errors?: string[];
 };
-/**
- * 为单个 Action 构建清单项。
- */
-export declare function createManifestEntry(options: {
-    entry: string;
-    description?: string;
-    inputSchema?: Record<string, unknown> | boolean;
-    outputSchema?: Record<string, unknown> | boolean;
-    uses?: string[];
-    tags?: string[];
-    annotations?: Record<string, unknown>;
-}): ActionManifestEntry;
-/**
- * 依据动作源码目录中的 Action 定义，增量同步或校验 actiondock.manifest.json 文件。
- *
- * @param projectRoot 项目根目录绝对路径
- * @param options 同步选项（包括 actionsDir、check、prune、autoInstall）
- * @returns 同步变更结果报告
- */
-export declare function syncManifest(projectRoot: string, options?: SyncManifestOptions): Promise<ManifestSyncResult>;
-/**
- * 校验当前 actiondock.manifest.json 是否与动作源码定义保持一致（只读检查）。
- */
-export declare function checkManifestSync(projectRoot: string, options?: Omit<SyncManifestOptions, "check">): Promise<ManifestSyncResult>;

package/dist/project/manifest.js

@@ -0,0 +1,220 @@
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { isPathOutsideBoundary, PACKAGE_ID_REGEX } from "../utils/index.js";
+export const MANIFEST_FILE_NAME = "actiondock.json";
+export const ACTION_ID_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
+export const PLAYBOOK_ID_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * 读取并解析项目的声明式清单文件（actiondock.json 为唯一事实源）。
+ * 若文件不存在则返回 null。
+ */
+export function loadManifest(projectRoot) {
+    const filePath = join(projectRoot, MANIFEST_FILE_NAME);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Failed to read manifest at ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Corrupted JSON in manifest at ${filePath}: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid manifest format in ${filePath}: expected a JSON object`);
+    }
+    if (parsed.schemaVersion !== undefined &&
+        (typeof parsed.schemaVersion !== "number" || parsed.schemaVersion < 1 || parsed.schemaVersion > 2)) {
+        throw new Error(`Unsupported manifest schemaVersion in ${filePath}: received '${parsed.schemaVersion}', expected 2`);
+    }
+    if (!parsed.id) {
+        parsed.id = basename(projectRoot);
+    }
+    return parsed;
+}
+/**
+ * 保存声明式清单文件至项目根目录（actiondock.json）。
+ */
+export function saveManifest(projectRoot, manifest) {
+    const filePath = join(projectRoot, MANIFEST_FILE_NAME);
+    writeFileSync(filePath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+/**
+ * 校验清单数据结构的合法性与安全性。
+ */
+export function validateManifest(manifest, options) {
+    if (!manifest || typeof manifest !== "object") {
+        return { valid: false, errors: ["Manifest must be an object"] };
+    }
+    const m = manifest;
+    const errors = [];
+    if (m.schemaVersion !== undefined &&
+        (typeof m.schemaVersion !== "number" || m.schemaVersion < 1 || m.schemaVersion > 2)) {
+        errors.push(`Manifest 'schemaVersion' must be 1 or 2 (received '${m.schemaVersion}')`);
+    }
+    if (m.id !== undefined) {
+        if (typeof m.id !== "string" || !PACKAGE_ID_REGEX.test(m.id)) {
+            errors.push(`Manifest 'id' is invalid: '${m.id}' (must match ${PACKAGE_ID_REGEX})`);
+        }
+    }
+    if (m.actions !== undefined) {
+        if (!m.actions || typeof m.actions !== "object" || Array.isArray(m.actions)) {
+            errors.push("Manifest 'actions' must be an object");
+        }
+        else {
+            for (const [actionId, item] of Object.entries(m.actions)) {
+                if (!ACTION_ID_REGEX.test(actionId)) {
+                    errors.push(`Invalid action ID '${actionId}' in manifest. Action IDs must match ${ACTION_ID_REGEX}`);
+                }
+                if (!item || typeof item !== "object") {
+                    errors.push(`Action entry '${actionId}' must be an object`);
+                    continue;
+                }
+                if (!item.entry || typeof item.entry !== "string") {
+                    errors.push(`Action '${actionId}' must specify string 'entry'`);
+                }
+                else {
+                    if (isAbsolute(item.entry)) {
+                        errors.push(`Action '${actionId}' entry cannot be an absolute path: ${item.entry}`);
+                    }
+                    else if (item.entry.split("/").some((part) => part === ".." || part === "\\..")) {
+                        errors.push(`Action '${actionId}' entry cannot contain path traversal: ${item.entry}`);
+                    }
+                    else if (options?.projectRoot) {
+                        const resolvedPath = resolve(options.projectRoot, item.entry);
+                        const rel = relative(options.projectRoot, resolvedPath);
+                        if (isPathOutsideBoundary(rel)) {
+                            errors.push(`Action '${actionId}' entry escapes project root: ${item.entry}`);
+                        }
+                        else if (existsSync(resolvedPath)) {
+                            try {
+                                const realEntry = realpathSync(resolvedPath);
+                                const realRoot = realpathSync(options.projectRoot);
+                                const relReal = relative(realRoot, realEntry);
+                                if (isPathOutsideBoundary(relReal)) {
+                                    errors.push(`Action '${actionId}' entry symlink resolves outside project root: ${item.entry}`);
+                                }
+                            }
+                            catch (err) {
+                                errors.push(`Failed to resolve real path for Action '${actionId}': ${err.message}`);
+                            }
+                        }
+                    }
+                }
+                if (item.uses && !Array.isArray(item.uses)) {
+                    errors.push(`Action '${actionId}' property 'uses' must be an array`);
+                }
+                if (item.tags && !Array.isArray(item.tags)) {
+                    errors.push(`Action '${actionId}' property 'tags' must be an array`);
+                }
+            }
+        }
+    }
+    if (m.playbooks !== undefined) {
+        if (!m.playbooks || typeof m.playbooks !== "object" || Array.isArray(m.playbooks)) {
+            errors.push("Manifest 'playbooks' must be an object");
+        }
+        else {
+            for (const [playbookId, item] of Object.entries(m.playbooks)) {
+                if (!PLAYBOOK_ID_REGEX.test(playbookId)) {
+                    errors.push(`Invalid playbook ID '${playbookId}' in manifest. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
+                }
+                if (!item || typeof item !== "object") {
+                    errors.push(`Playbook entry '${playbookId}' must be an object`);
+                    continue;
+                }
+                if (!item.entry || typeof item.entry !== "string") {
+                    errors.push(`Playbook '${playbookId}' must specify string 'entry'`);
+                }
+                else {
+                    if (isAbsolute(item.entry)) {
+                        errors.push(`Playbook '${playbookId}' entry cannot be an absolute path: ${item.entry}`);
+                    }
+                    else if (item.entry.split("/").some((part) => part === ".." || part === "\\..")) {
+                        errors.push(`Playbook '${playbookId}' entry cannot contain path traversal: ${item.entry}`);
+                    }
+                    else if (options?.projectRoot) {
+                        const resolvedPath = resolve(options.projectRoot, item.entry);
+                        const rel = relative(options.projectRoot, resolvedPath);
+                        if (isPathOutsideBoundary(rel)) {
+                            errors.push(`Playbook '${playbookId}' entry escapes project root: ${item.entry}`);
+                        }
+                        else if (existsSync(resolvedPath)) {
+                            try {
+                                const realEntry = realpathSync(resolvedPath);
+                                const realRoot = realpathSync(options.projectRoot);
+                                const relReal = relative(realRoot, realEntry);
+                                if (isPathOutsideBoundary(relReal)) {
+                                    errors.push(`Playbook '${playbookId}' entry symlink resolves outside project root: ${item.entry}`);
+                                }
+                            }
+                            catch (err) {
+                                errors.push(`Failed to resolve real path for Playbook '${playbookId}': ${err.message}`);
+                            }
+                        }
+                    }
+                }
+                if (item.actions && !Array.isArray(item.actions)) {
+                    errors.push(`Playbook '${playbookId}' property 'actions' must be an array`);
+                }
+            }
+        }
+    }
+    if (m.dependencies !== undefined) {
+        if (!m.dependencies || typeof m.dependencies !== "object" || Array.isArray(m.dependencies)) {
+            errors.push("Manifest 'dependencies' must be an object");
+        }
+    }
+    if (m.assets !== undefined) {
+        if (!Array.isArray(m.assets)) {
+            errors.push("Manifest 'assets' must be an array");
+        }
+        else {
+            for (const asset of m.assets) {
+                if (typeof asset !== "string") {
+                    errors.push("Asset entry must be a string");
+                }
+                else if (isAbsolute(asset)) {
+                    errors.push(`Asset path cannot be an absolute path: ${asset}`);
+                }
+                else if (asset.split("/").some((part) => part === ".." || part === "\\..")) {
+                    errors.push(`Asset path cannot contain path traversal: ${asset}`);
+                }
+                else if (options?.projectRoot) {
+                    const resolvedPath = resolve(options.projectRoot, asset);
+                    const rel = relative(options.projectRoot, resolvedPath);
+                    if (isPathOutsideBoundary(rel)) {
+                        errors.push(`Asset path escapes project root: ${asset}`);
+                    }
+                    else if (existsSync(resolvedPath)) {
+                        try {
+                            const realAsset = realpathSync(resolvedPath);
+                            const realRoot = realpathSync(options.projectRoot);
+                            const relReal = relative(realRoot, realAsset);
+                            if (isPathOutsideBoundary(relReal)) {
+                                errors.push(`Asset symlink resolves outside project root: ${asset}`);
+                            }
+                        }
+                        catch (err) {
+                            errors.push(`Failed to resolve real path for asset '${asset}': ${err.message}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (m.files !== undefined && !Array.isArray(m.files)) {
+        errors.push("Manifest 'files' must be an array");
+    }
+    return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined,
+    };
+}

package/dist/project/resolver.d.ts

@@ -0,0 +1,116 @@
+import { type ActionDockLockfile } from "./lockfile.js";
+import type { ActionDockManifest, PlaybookDefinition } from "./types.js";
+/**
+ * 语义化版本元数据结构。
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+}
+/**
+ * 解析基础 SemVer 版本字符串。
+ */
+export declare function parseSemVer(v: string): SemVer | null;
+/**
+ * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
+ * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
+ */
+export declare function areVersionsCompatible(v1: string, v2: string): boolean;
+/**
+ * 版本冲突错误。
+ */
+export declare class ActionPackageVersionConflictError extends Error {
+    readonly code = "ACTION_PACKAGE_VERSION_CONFLICT";
+    readonly packageId: string;
+    readonly conflicts: Array<{
+        requester: string;
+        rangeOrVersion: string;
+    }>;
+    constructor(packageId: string, conflicts: Array<{
+        requester: string;
+        rangeOrVersion: string;
+    }>);
+}
+/**
+ * 未声明依赖调用拦截错误。
+ */
+export declare class UndeclaredActionDependencyError extends Error {
+    readonly code = "UNDECLARED_ACTION_DEPENDENCY";
+    readonly targetRef: string;
+    readonly caller?: string;
+    constructor(targetRef: string, caller?: string, reason?: string);
+}
+/**
+ * 已解析 Action 包信息。
+ */
+export interface ResolvedPackageInfo {
+    packageId: string;
+    npmPackage: string;
+    version: string;
+    packageRoot: string;
+    manifest: ActionDockManifest;
+    manifestDigest: string;
+    isDirect: boolean;
+    isRoot: boolean;
+}
+/**
+ * 完整 Action 包依赖图结构。
+ */
+export interface DependencyGraph {
+    rootPackageId: string;
+    packages: Map<string, ResolvedPackageInfo>;
+    directDependencyIds: Set<string>;
+    transitiveDependencyIds: Set<string>;
+    visiblePlaybooks: Map<string, PlaybookDefinition>;
+    delegatedActions: Set<string>;
+}
+export interface ActionPackageResolverOptions {
+    projectRoot: string;
+    manifest?: ActionDockManifest;
+    lockfile?: ActionDockLockfile;
+    allowDevLinks?: boolean;
+    customHome?: string;
+    packageRoots?: Record<string, string>;
+}
+/**
+ * 依赖解析器 ActionPackageResolver。
+ * 负责从 actiondock.json.dependencies 与 actiondock.lock.json 建立包索引与依赖闭包，
+ * 实施版本冲突检测与调用可见性鉴权。
+ */
+export declare class ActionPackageResolver {
+    readonly projectRoot: string;
+    private options;
+    private resolvedGraph?;
+    constructor(options: ActionPackageResolverOptions);
+    /**
+     * 同步解析依赖图。
+     */
+    resolveSync(): DependencyGraph;
+    /**
+     * 异步解析依赖图。
+     */
+    resolve(): Promise<DependencyGraph>;
+    /**
+     * 判定目标 Action 是否允许作为根调用发起。
+     * 规则：
+     * - 目标属于当前根包；
+     * - 目标属于 actiondock.json 直接依赖；
+     * - 目标属于可见 Playbook 精确委托点名的 Action。
+     */
+    canRootCall(targetPackageId: string, targetActionId: string): boolean;
+    /**
+     * 校验根调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
+     */
+    assertRootCallAllowed(targetPackageId: string, targetActionId: string): void;
+    /**
+     * 判定跨包级联调用是否合法。
+     * 规则：调用者 Action 必须在 actiondock.json 的 uses 中显式声明对目标 Action 的依赖。
+     */
+    canCascadeCall(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): boolean;
+    /**
+     * 校验跨包级联调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
+     */
+    assertCascadeCallAllowed(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): void;
+}