@actiondock/core 2.0.12 → 2.2.0

package/dist/project/resolver.js

@@ -0,0 +1,376 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { listLinkedPackages } from "../registry/registry.js";
+import { computeManifestDigest, parseJsonWithoutDuplicates } from "./digest.js";
+import { loadLockfile } from "./lockfile.js";
+import { loadPlaybooks } from "./loader.js";
+import { loadManifest, MANIFEST_FILE_NAME } from "./manifest.js";
+/**
+ * 解析基础 SemVer 版本字符串。
+ */
+export function parseSemVer(v) {
+    const match = v.trim().replace(/^[v=]/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match)
+        return null;
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4],
+    };
+}
+/**
+ * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
+ * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
+ */
+export function areVersionsCompatible(v1, v2) {
+    if (v1 === v2 || v1 === "*" || v2 === "*" || !v1 || !v2) {
+        return true;
+    }
+    // 处理前缀范围符（如 ^1.0.0, ~1.0.0）
+    const clean1 = v1.trim().replace(/^[\^~=]/, "");
+    const clean2 = v2.trim().replace(/^[\^~=]/, "");
+    const sem1 = parseSemVer(clean1);
+    const sem2 = parseSemVer(clean2);
+    if (!sem1 || !sem2) {
+        // 非标准 SemVer 时按字面匹配
+        return v1 === v2;
+    }
+    // 若存在主版本号不一致，则严格视为不兼容
+    if (sem1.major !== sem2.major) {
+        return false;
+    }
+    // 若带波浪号（~1.2.0），次版本号必须一致
+    if (v1.startsWith("~") || v2.startsWith("~")) {
+        if (sem1.minor !== sem2.minor) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 版本冲突错误。
+ */
+export class ActionPackageVersionConflictError extends Error {
+    code = "ACTION_PACKAGE_VERSION_CONFLICT";
+    packageId;
+    conflicts;
+    constructor(packageId, conflicts) {
+        const details = conflicts.map((c) => `'${c.requester}' 要求 '${c.rangeOrVersion}'`).join(", ");
+        super(`ACTION_PACKAGE_VERSION_CONFLICT: 逻辑包 '${packageId}' 存在不可收敛的版本冲突: ${details}`);
+        this.name = "ActionPackageVersionConflictError";
+        this.packageId = packageId;
+        this.conflicts = conflicts;
+    }
+}
+/**
+ * 未声明依赖调用拦截错误。
+ */
+export class UndeclaredActionDependencyError extends Error {
+    code = "UNDECLARED_ACTION_DEPENDENCY";
+    targetRef;
+    caller;
+    constructor(targetRef, caller, reason) {
+        const msg = caller
+            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' 未在 'uses' 中声明对 '${targetRef}' 的跨包依赖`
+            : `UNDECLARED_ACTION_DEPENDENCY: 根调用 Action '${targetRef}' 被拒绝: 目标包既非 actiondock.json 直接依赖，亦未被可见 Playbook 委托${reason ? ` (${reason})` : ""}`;
+        super(msg);
+        this.name = "UndeclaredActionDependencyError";
+        this.targetRef = targetRef;
+        this.caller = caller;
+    }
+}
+/**
+ * 依赖解析器 ActionPackageResolver。
+ * 负责从 actiondock.json.dependencies 与 actiondock.lock.json 建立包索引与依赖闭包，
+ * 实施版本冲突检测与调用可见性鉴权。
+ */
+export class ActionPackageResolver {
+    projectRoot;
+    options;
+    resolvedGraph;
+    constructor(options) {
+        this.projectRoot = resolve(options.projectRoot);
+        this.options = { ...options, projectRoot: this.projectRoot };
+    }
+    /**
+     * 同步解析依赖图。
+     */
+    resolveSync() {
+        if (this.resolvedGraph) {
+            return this.resolvedGraph;
+        }
+        const rootManifest = this.options.manifest ||
+            loadManifest(this.projectRoot) || {
+            id: basename(this.projectRoot),
+            version: "0.1.0",
+        };
+        const rootPackageId = rootManifest.id;
+        const lockfile = this.options.lockfile ?? loadLockfile(this.projectRoot);
+        const packages = new Map();
+        const directDependencyIds = new Set();
+        const transitiveDependencyIds = new Set();
+        const versionRequirements = new Map();
+        // 记录根包自身
+        const rootDigest = computeManifestDigest(rootManifest);
+        packages.set(rootPackageId, {
+            packageId: rootPackageId,
+            npmPackage: rootPackageId,
+            version: rootManifest.version || "0.1.0",
+            packageRoot: this.projectRoot,
+            manifest: rootManifest,
+            manifestDigest: rootDigest,
+            isDirect: true,
+            isRoot: true,
+        });
+        directDependencyIds.add(rootPackageId);
+        // 探测开发本地软链接覆盖
+        const devLinkMap = new Map();
+        if (this.options.allowDevLinks) {
+            try {
+                const linked = listLinkedPackages(this.options.customHome);
+                for (const entry of linked) {
+                    if (existsSync(entry.path)) {
+                        devLinkMap.set(entry.id, entry.path);
+                    }
+                }
+            }
+            catch {
+                // 忽略扫描外部链接包异常
+            }
+        }
+        function recordRequirement(pkgId, requester, rangeOrVersion) {
+            const existing = versionRequirements.get(pkgId) || [];
+            for (const req of existing) {
+                if (!areVersionsCompatible(req.rangeOrVersion, rangeOrVersion)) {
+                    throw new ActionPackageVersionConflictError(pkgId, [
+                        req,
+                        { requester, rangeOrVersion },
+                    ]);
+                }
+            }
+            existing.push({ requester, rangeOrVersion });
+            versionRequirements.set(pkgId, existing);
+        }
+        // 广度优先遍历解析直接与间接依赖
+        const queue = [];
+        for (const [depId, spec] of Object.entries(rootManifest.dependencies || {})) {
+            directDependencyIds.add(depId);
+            recordRequirement(depId, rootPackageId, spec);
+            queue.push({
+                pkgId: depId,
+                requester: rootPackageId,
+                rangeOrSpec: spec,
+                isDirect: true,
+            });
+        }
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (packages.has(item.pkgId)) {
+                continue;
+            }
+            // 寻址包安装根目录
+            let pkgDir = null;
+            const locked = lockfile?.packages?.[item.pkgId];
+            // 优先级：显式注入路径 -> 开发软链接覆盖 -> 锁文件记录 -> node_modules 探测
+            if (this.options.packageRoots?.[item.pkgId]) {
+                pkgDir = this.options.packageRoots[item.pkgId];
+            }
+            else if (devLinkMap.has(item.pkgId)) {
+                pkgDir = devLinkMap.get(item.pkgId);
+            }
+            else {
+                const candidateNames = [];
+                if (locked?.npmPackage) {
+                    candidateNames.push(locked.npmPackage);
+                }
+                candidateNames.push(item.rangeOrSpec);
+                candidateNames.push(item.pkgId);
+                let cur = this.projectRoot;
+                while (true) {
+                    for (const candName of candidateNames) {
+                        const candPath = join(cur, "node_modules", candName);
+                        if (existsSync(candPath) && existsSync(join(candPath, MANIFEST_FILE_NAME))) {
+                            pkgDir = candPath;
+                            break;
+                        }
+                    }
+                    if (pkgDir)
+                        break;
+                    const parent = dirname(cur);
+                    if (parent === cur)
+                        break;
+                    cur = parent;
+                }
+            }
+            if (!pkgDir || !existsSync(pkgDir)) {
+                throw new Error(`PACKAGE_NOT_FOUND: Package '${item.pkgId}' required by '${item.requester}' is not installed in ${this.projectRoot}. Please run 'ad add ${item.rangeOrSpec}'.`);
+            }
+            const manifestPath = join(pkgDir, MANIFEST_FILE_NAME);
+            if (!existsSync(manifestPath)) {
+                throw new Error(`Action package '${item.pkgId}' at '${pkgDir}' misses required manifest 'actiondock.json'`);
+            }
+            let manifestRaw;
+            try {
+                manifestRaw = readFileSync(manifestPath, "utf-8");
+            }
+            catch (err) {
+                throw new Error(`Failed to read manifest for '${item.pkgId}': ${err.message}`);
+            }
+            const depManifest = parseJsonWithoutDuplicates(manifestRaw);
+            const actualDigest = computeManifestDigest(depManifest);
+            // 锁文件摘要校验
+            if (locked?.manifestDigest && locked.manifestDigest !== actualDigest) {
+                throw new Error(`Manifest digest mismatch for package '${item.pkgId}': expected '${locked.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
+            }
+            const pkgVersion = depManifest.version || locked?.version || "0.1.0";
+            // 校验版本是否满足已知要求
+            const reqs = versionRequirements.get(item.pkgId) || [];
+            for (const req of reqs) {
+                if (!areVersionsCompatible(req.rangeOrVersion, pkgVersion)) {
+                    throw new ActionPackageVersionConflictError(item.pkgId, [
+                        req,
+                        { requester: item.pkgId, rangeOrVersion: pkgVersion },
+                    ]);
+                }
+            }
+            const info = {
+                packageId: item.pkgId,
+                npmPackage: locked?.npmPackage || item.rangeOrSpec,
+                version: pkgVersion,
+                packageRoot: pkgDir,
+                manifest: depManifest,
+                manifestDigest: actualDigest,
+                isDirect: item.isDirect,
+                isRoot: false,
+            };
+            packages.set(item.pkgId, info);
+            if (!item.isDirect) {
+                transitiveDependencyIds.add(item.pkgId);
+            }
+            // 继续搜寻传递依赖
+            for (const [subDepId, subSpec] of Object.entries(depManifest.dependencies || {})) {
+                recordRequirement(subDepId, item.pkgId, subSpec);
+                if (!packages.has(subDepId)) {
+                    queue.push({
+                        pkgId: subDepId,
+                        requester: item.pkgId,
+                        rangeOrSpec: subSpec,
+                        isDirect: false,
+                    });
+                }
+            }
+        }
+        // 收集可见 Playbook 与被委托 Action
+        const visiblePlaybooks = new Map();
+        const delegatedActions = new Set();
+        // 根包 Playbooks
+        try {
+            const rootPbs = loadPlaybooks(this.projectRoot);
+            for (const [id, pb] of rootPbs.entries()) {
+                visiblePlaybooks.set(id, pb);
+                visiblePlaybooks.set(`${rootPackageId}/${id}`, pb);
+            }
+        }
+        catch {
+            // 忽略根包 Playbook 加载异常
+        }
+        // 直接依赖包 Playbooks
+        for (const depId of directDependencyIds) {
+            if (depId === rootPackageId)
+                continue;
+            const depPkg = packages.get(depId);
+            if (depPkg) {
+                try {
+                    const depPbs = loadPlaybooks(depPkg.packageRoot);
+                    for (const [id, pb] of depPbs.entries()) {
+                        visiblePlaybooks.set(`${depId}/${id}`, pb);
+                    }
+                }
+                catch {
+                    // 忽略依赖包 Playbook 加载异常
+                }
+            }
+        }
+        // 可见 Playbook 点名委托的 Action 收集
+        for (const pb of visiblePlaybooks.values()) {
+            if (Array.isArray(pb.actions)) {
+                for (const actRef of pb.actions) {
+                    if (typeof actRef === "string" && actRef.trim()) {
+                        delegatedActions.add(actRef.trim());
+                    }
+                }
+            }
+        }
+        this.resolvedGraph = {
+            rootPackageId,
+            packages,
+            directDependencyIds,
+            transitiveDependencyIds,
+            visiblePlaybooks,
+            delegatedActions,
+        };
+        return this.resolvedGraph;
+    }
+    /**
+     * 异步解析依赖图。
+     */
+    async resolve() {
+        return this.resolveSync();
+    }
+    /**
+     * 判定目标 Action 是否允许作为根调用发起。
+     * 规则：
+     * - 目标属于当前根包；
+     * - 目标属于 actiondock.json 直接依赖；
+     * - 目标属于可见 Playbook 精确委托点名的 Action。
+     */
+    canRootCall(targetPackageId, targetActionId) {
+        const graph = this.resolveSync();
+        if (targetPackageId === graph.rootPackageId) {
+            return true;
+        }
+        if (graph.directDependencyIds.has(targetPackageId)) {
+            return true;
+        }
+        const qualifiedRef = `${targetPackageId}/${targetActionId}`;
+        if (graph.delegatedActions.has(qualifiedRef)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 校验根调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
+     */
+    assertRootCallAllowed(targetPackageId, targetActionId) {
+        if (!this.canRootCall(targetPackageId, targetActionId)) {
+            throw new UndeclaredActionDependencyError(`${targetPackageId}/${targetActionId}`);
+        }
+    }
+    /**
+     * 判定跨包级联调用是否合法。
+     * 规则：调用者 Action 必须在 actiondock.json 的 uses 中显式声明对目标 Action 的依赖。
+     */
+    canCascadeCall(callerPackageId, callerActionId, targetPackageId, targetActionId) {
+        if (callerPackageId === targetPackageId) {
+            return true;
+        }
+        const graph = this.resolveSync();
+        const callerPkg = graph.packages.get(callerPackageId);
+        if (!callerPkg) {
+            return false;
+        }
+        const callerActionEntry = callerPkg.manifest.actions?.[callerActionId];
+        const usesList = callerActionEntry?.uses || [];
+        const targetRef = `${targetPackageId}/${targetActionId}`;
+        return usesList.some((u) => u === targetRef || u === `${targetPackageId}/*` || u === targetPackageId);
+    }
+    /**
+     * 校验跨包级联调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
+     */
+    assertCascadeCallAllowed(callerPackageId, callerActionId, targetPackageId, targetActionId) {
+        if (!this.canCascadeCall(callerPackageId, callerActionId, targetPackageId, targetActionId)) {
+            throw new UndeclaredActionDependencyError(`${targetPackageId}/${targetActionId}`, `${callerPackageId}/${callerActionId}`);
+        }
+    }
+}

package/dist/project/transactions.d.ts

@@ -0,0 +1,103 @@
+export declare const SNAPSHOT_TRACKED_FILES: readonly ["package.json", "actiondock.json", "actiondock.lock.json", "package-lock.json", "npm-shrinkwrap.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock"];
+export interface TransactionFileRecord {
+    name: string;
+    existed: boolean;
+}
+export interface TransactionMetadata {
+    id: string;
+    status: "pending" | "committed" | "rolled_back";
+    createdAt: number;
+    description?: string;
+    files: TransactionFileRecord[];
+}
+export interface ProjectTransaction {
+    id: string;
+    projectRoot: string;
+    description?: string;
+    commit(): Promise<void>;
+    rollback(options?: {
+        frozenInstall?: boolean;
+    }): Promise<void>;
+    releaseLock(): void;
+}
+/**
+ * 检查当前进程 PID 是否处于活跃运行状态。
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * 安全清理陈旧接管守卫（reclaim guard）。
+ * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
+ *
+ * @param reclaimPath 目标守卫路径
+ * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
+ */
+export declare function safeRemoveStaleProjectReclaimGuard(reclaimPath: string, expectedGuardToken: string): void;
+/**
+ * 从工程锁隔离或回滚临时目录名称中解析操作者 PID 与隔离生成时间戳。
+ * 命名规范：*.(quarantine|rollback|release).<pid>.<timestamp>.<uuid> 或 *.orphan.<timestamp>.<uuid>
+ */
+export declare function parseProjectQuarantineTimestamp(entryName: string): {
+    operatorPid?: number;
+    timestamp?: number;
+};
+export declare const parseQuarantineTimestamp: typeof parseProjectQuarantineTimestamp;
+/**
+ * 清理过期的工程锁隔离目录（GC 回收机制）。
+ * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏：
+ * - 共同前置条件：存活年龄必须超过 maxAgeMs（默认 10000ms），未超期前严禁清理（保持宽限期）。
+ * - 活跃隔离目录（quarantine / rollback / release）：若 operatorPid 存活或内部 metadata.json 记录的 pid 与 childPids 存活，跳过不予清理。
+ * - 孤儿脱离目录（orphan）：内部旧 metadata.pid 不再作为续命依据；提取其内部 orphanToken，仅当当前规范主路径（主锁目录与 reclaim 目录）依然持有该凭证时保守跳过；规范路径不存在或已变更凭据时直接安全清理。
+ */
+export declare function cleanStaleProjectQuarantines(parentDir: string, basePrefix: string, maxAgeMs?: number, deadline?: number): void;
+/**
+ * 安全回滚当前进程创建的工程修改锁。
+ * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
+ */
+export declare function safeRollbackProjectLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+/**
+ * 安全释放工程主锁。
+ * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
+ */
+export declare function safeReleaseProjectLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+/**
+ * 检查项目修改锁 .actiondock/project.lock 是否存在且持有者 PID 处于存活状态。
+ *
+ * @param projectRoot 项目根目录
+ * @param excludeSelf 是否排除当前进程本身（默认为 true，即仅当其他活跃进程持锁时判定为锁被占用）
+ */
+export declare function isProjectLockHeld(projectRoot: string, excludeSelf?: boolean): boolean;
+/**
+ * 获取工程修改排他锁（.actiondock/project.lock）。
+ * 引入所有竞争者均遵守的原子 reclaim guard 机制（project.lock.reclaim）。
+ * 采用 mkdirSync 原子排他目录创建、renameSync 元数据写入、宽限期重试检测与基于 sessionToken 的释放函数。
+ * 避免空文件窗口与 truncate。
+ *
+ * @param projectRoot 项目根目录
+ * @param options 锁配置参数
+ */
+export declare function acquireProjectLock(projectRoot: string, options?: {
+    sessionToken?: string;
+    acquireTimeoutMs?: number;
+}): () => void;
+/**
+ * 依据恢复后的锁文件执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
+ */
+export declare function runFrozenInstall(projectRoot: string): void;
+/**
+ * 检查项目是否存在未完成提交的悬空事务。
+ */
+export declare function hasPendingTransactions(projectRoot: string): boolean;
+/**
+ * 启动新的工程修改事务快照。
+ * 捕获 package.json、actiondock.json、actiondock.lock.json 及各包管理器锁文件当前快照。
+ */
+export declare function beginTransaction(projectRoot: string, description?: string): Promise<ProjectTransaction>;
+/**
+ * 依据事务日志恢复所有待恢复的悬空事务快照，并在成功后执行冻结安装。
+ * 进入恢复前通过 acquireProjectLock 原子获取排他锁，持有锁执行恢复，完成后通过释放函数安全释放锁。
+ * 若获取锁失败（已有活跃进程正在执行）则安全退出并返回空数组，杜绝 TOCTOU 竞争。
+ * 若冻结安装失败则抛出 PROJECT_RECOVERY_REQUIRED 并阻止 Host 启动。
+ */
+export declare function recoverPendingTransactions(projectRoot: string, options?: {
+    frozenInstall?: boolean;
+}): Promise<string[]>;