@actiondock/core 2.10.0 → 2.12.0

package/dist/project/lockfile.js

@@ -2,6 +2,7 @@ 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";
+import { ActionDockError, LOCKFILE_CORRUPTED, LOCKFILE_INVALID, LOCKFILE_READ_FAILED, UNSUPPORTED_LOCKFILE_VERSION, } from "../errors.js";
 export const LOCKFILE_NAME = "actiondock.lock.json";
 export const LOCKFILE_VERSION = 1;
 /**
@@ -18,23 +19,23 @@ export function loadLockfile(projectRoot) {
         raw = readFileSync(filePath, "utf-8");
     }
     catch (err) {
-        throw new Error(`Failed to read lockfile at ${filePath}: ${err.message}`);
+        throw new ActionDockError(LOCKFILE_READ_FAILED, `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}`);
+        throw new ActionDockError(LOCKFILE_CORRUPTED, `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`);
+        throw new ActionDockError(LOCKFILE_INVALID, `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}`);
+        throw new ActionDockError(UNSUPPORTED_LOCKFILE_VERSION, `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`);
+        throw new ActionDockError(LOCKFILE_INVALID, `Invalid lockfile format in ${filePath}: 'packages' must be an object`);
     }
     // 规范化并注入兼容字段
     for (const [key, item] of Object.entries(parsed.packages)) {

package/dist/project/manifest.js

@@ -1,6 +1,7 @@
 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";
+import { ActionDockError, MANIFEST_CORRUPTED, MANIFEST_INVALID, MANIFEST_READ_FAILED, UNSUPPORTED_MANIFEST_SCHEMA, } from "../errors.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._-]*$/;
@@ -18,21 +19,21 @@ export function loadManifest(projectRoot) {
         raw = readFileSync(filePath, "utf-8");
     }
     catch (err) {
-        throw new Error(`Failed to read manifest at ${filePath}: ${err.message}`);
+        throw new ActionDockError(MANIFEST_READ_FAILED, `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}`);
+        throw new ActionDockError(MANIFEST_CORRUPTED, `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`);
+        throw new ActionDockError(MANIFEST_INVALID, `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`);
+        throw new ActionDockError(UNSUPPORTED_MANIFEST_SCHEMA, `Unsupported manifest schemaVersion in ${filePath}: received '${parsed.schemaVersion}', expected 2`);
     }
     if (!parsed.id) {
         parsed.id = basename(projectRoot);

package/dist/project/transactions.d.ts

@@ -20,43 +20,10 @@ export interface ProjectTransaction {
     }): Promise<void>;
     releaseLock(): void;
 }
-/**
- * 检查当前进程 PID 是否处于活跃运行状态。
- */
-export declare function isPidAlive(pid: number): boolean;
-/**
- * 从工程锁隔离或回滚临时目录名称中解析操作者 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;
-/**
- * 安全清理陈旧接管守卫（reclaim guard）。
- * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
- *
- * @param reclaimPath 目标守卫路径
- * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
- */
-export declare function safeRemoveStaleProjectReclaimGuard(reclaimPath: string, expectedGuardToken: string): void;
-/**
- * 安全回滚当前进程创建的工程修改锁。
- * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
- */
-export declare function safeRollbackProjectLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
-/**
- * 清理过期的工程锁隔离目录（GC 回收机制）。
- * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏，语义由目录锁内核统一承载。
- */
-export declare function cleanStaleProjectQuarantines(parentDir: string, basePrefix: string, maxAgeMs?: number, deadline?: number): void;
 /**
  * 安全释放工程主锁。
- * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
- * 释放后同步触发一轮工程锁隔离目录 GC。
  */
-export declare function safeReleaseProjectLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+export declare function safeReleaseProjectLock(lockPath: string, expectedSessionToken?: string, expectedLockToken?: string): void;
 /**
  * 检查项目修改锁 .actiondock/project.lock 是否存在且持有者 PID 处于存活状态。
  *
@@ -66,9 +33,7 @@ export declare function safeReleaseProjectLock(lockPath: string, expectedSession
 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 锁配置参数
@@ -78,9 +43,9 @@ export declare function acquireProjectLock(projectRoot: string, options?: {
     acquireTimeoutMs?: number;
 }): () => void;
 /**
- * 依据恢复后的锁文件执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
+ * 依据恢复后的锁文件异步执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
  */
-export declare function runFrozenInstall(projectRoot: string): void;
+export declare function runFrozenInstall(projectRoot: string): Promise<void>;
 /**
  * 检查项目是否存在未完成提交的悬空事务。
  */
@@ -92,9 +57,6 @@ export declare function hasPendingTransactions(projectRoot: string): boolean;
 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;

package/dist/project/transactions.js

@@ -1,8 +1,9 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { acquireDirectoryLock, checkReclaimGuard, cleanStaleQuarantines, isProcessAlive, parseQuarantineTimestamp as parseQuarantineTimestampCore, readLockWithGracePeriod, safeReleaseLock as coreSafeReleaseLock, safeRemoveStaleReclaimGuard, safeRollbackLock, } from "../storage/lock-core.js";
+import { acquireFileLockSync, isLockHeld, safeReleaseFileLockSync, } from "../storage/file-lock.js";
+import { isProcessAlive } from "../utils/index.js";
 import { ActionDockError, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED } from "../errors.js";
 import { LOCKFILE_NAME } from "./lockfile.js";
 import { MANIFEST_FILE_NAME } from "./manifest.js";
@@ -18,51 +19,11 @@ export const SNAPSHOT_TRACKED_FILES = [
     "yarn.lock",
 ];
 const LOCK_DIR_NAME = "project.lock";
-/**
- * 检查当前进程 PID 是否处于活跃运行状态。
- */
-export function isPidAlive(pid) {
-    return isProcessAlive(pid);
-}
-/**
- * 从工程锁隔离或回滚临时目录名称中解析操作者 PID 与隔离生成时间戳。
- * 命名规范：*.(quarantine|rollback|release).<pid>.<timestamp>.<uuid> 或 *.orphan.<timestamp>.<uuid>
- */
-export function parseProjectQuarantineTimestamp(entryName) {
-    return parseQuarantineTimestampCore(entryName);
-}
-export const parseQuarantineTimestamp = parseProjectQuarantineTimestamp;
-/**
- * 安全清理陈旧接管守卫（reclaim guard）。
- * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
- *
- * @param reclaimPath 目标守卫路径
- * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
- */
-export function safeRemoveStaleProjectReclaimGuard(reclaimPath, expectedGuardToken) {
-    safeRemoveStaleReclaimGuard(reclaimPath, expectedGuardToken);
-}
-/**
- * 安全回滚当前进程创建的工程修改锁。
- * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
- */
-export function safeRollbackProjectLock(lockPath, expectedSessionToken, expectedLockToken) {
-    safeRollbackLock(lockPath, expectedSessionToken, expectedLockToken);
-}
-/**
- * 清理过期的工程锁隔离目录（GC 回收机制）。
- * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏，语义由目录锁内核统一承载。
- */
-export function cleanStaleProjectQuarantines(parentDir, basePrefix, maxAgeMs = 10000, deadline) {
-    cleanStaleQuarantines(parentDir, basePrefix, maxAgeMs, deadline);
-}
 /**
  * 安全释放工程主锁。
- * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
- * 释放后同步触发一轮工程锁隔离目录 GC。
  */
 export function safeReleaseProjectLock(lockPath, expectedSessionToken, expectedLockToken) {
-    coreSafeReleaseLock(lockPath, expectedSessionToken, expectedLockToken, { gcAfterRelease: true });
+    safeReleaseFileLockSync(lockPath, expectedLockToken, expectedSessionToken);
 }
 /**
  * 检查项目修改锁 .actiondock/project.lock 是否存在且持有者 PID 处于存活状态。
@@ -72,49 +33,16 @@ export function safeReleaseProjectLock(lockPath, expectedSessionToken, expectedL
  */
 export function isProjectLockHeld(projectRoot, excludeSelf = true) {
     const lockPath = join(projectRoot, ".actiondock", LOCK_DIR_NAME);
-    const reclaimPath = `${lockPath}.reclaim`;
-    if (existsSync(reclaimPath)) {
-        const reclaimState = checkReclaimGuard(reclaimPath, 1000);
-        if (reclaimState.active) {
-            if (!excludeSelf || reclaimState.holderPid !== process.pid) {
-                return true;
-            }
-        }
-    }
-    if (!existsSync(lockPath)) {
-        return false;
-    }
-    try {
-        const lockState = readLockWithGracePeriod(lockPath, 3000);
-        if (!lockState.exists) {
-            return false;
-        }
-        if (lockState.inGracePeriod) {
-            return true;
-        }
-        if (lockState.info && typeof lockState.info.pid === "number") {
-            if (excludeSelf && lockState.info.pid === process.pid) {
-                return false;
-            }
-            return isProcessAlive(lockState.info.pid);
-        }
-    }
-    catch {
-        // 忽略读取解析异常
-    }
-    return false;
+    return isLockHeld(lockPath, excludeSelf);
 }
 /**
  * 获取工程修改排他锁（.actiondock/project.lock）。
- * 引入所有竞争者均遵守的原子 reclaim guard 机制（project.lock.reclaim）。
- * 采用 mkdirSync 原子排他目录创建、renameSync 元数据写入、宽限期重试检测与基于 sessionToken 的释放函数。
- * 避免空文件窗口与 truncate。
+ * 基于统一轻量文件锁原语实现，非阻塞且支持原子抢占与崩溃恢复。
  *
  * @param projectRoot 项目根目录
  * @param options 锁配置参数
  */
 export function acquireProjectLock(projectRoot, options = {}) {
-    const timeoutMs = options.acquireTimeoutMs ?? 5000;
     const metaDir = join(projectRoot, ".actiondock");
     if (!existsSync(metaDir)) {
         mkdirSync(metaDir, { recursive: true });
@@ -122,55 +50,84 @@ export function acquireProjectLock(projectRoot, options = {}) {
     const lockPath = join(metaDir, LOCK_DIR_NAME);
     const sessionToken = options.sessionToken || randomUUID();
     const lockToken = randomUUID();
-    const currentPid = process.pid;
     const lockData = {
-        pid: currentPid,
+        pid: process.pid,
         sessionToken,
         lockToken,
         createdAt: Date.now(),
     };
-    const content = JSON.stringify(lockData, null, 2);
-    acquireDirectoryLock({
-        lockPath,
-        parentDir: metaDir,
-        basePrefix: LOCK_DIR_NAME,
-        metadataContent: content,
-        sessionToken,
-        lockToken,
-        acquireTimeoutMs: options.acquireTimeoutMs,
-        createLockError(message) {
-            return new ActionDockError(PROJECT_BUSY, message);
-        },
-        messages: {
-            timeoutWaitingReclaimGuard: (holderPid) => `PROJECT_BUSY: Timeout waiting for active reclaim guard (PID ${holderPid ?? "unknown"}) on project '${projectRoot}' after ${timeoutMs}ms`,
-            timeoutAcquireBlockedByGuard: (holderPid) => `PROJECT_BUSY: Timeout acquiring project lock on '${projectRoot}' due to active reclaim guard (PID ${holderPid}) after ${timeoutMs}ms`,
-            timeoutAcquire: () => `PROJECT_BUSY: Timeout acquiring project lock on '${projectRoot}' after ${timeoutMs}ms`,
-            timeoutGracePeriod: () => `PROJECT_BUSY: Timeout waiting for project lock grace period on '${projectRoot}' after ${timeoutMs}ms`,
-            timeoutGuardContention: () => `PROJECT_BUSY: Timeout contending for project reclaim guard on '${projectRoot}' after ${timeoutMs}ms`,
-            timeoutReclaimStale: () => `PROJECT_BUSY: Timeout reclaiming stale project lock on '${projectRoot}' after ${timeoutMs}ms`,
-            timeoutCreate: () => `PROJECT_BUSY: Timeout creating project lock on '${projectRoot}' after ${timeoutMs}ms`,
+    const handle = acquireFileLockSync(lockPath, {
+        metadata: lockData,
+        createLockError() {
+            return new ActionDockError(PROJECT_BUSY, `PROJECT_BUSY: Project modification lock is held by another process. Another command is running in ${projectRoot}.`);
         },
-        assertStaleHolderReclaimable(info) {
+        assertHolderReclaimable(info) {
             const holderPid = info.pid;
-            if (isProcessAlive(holderPid)) {
+            if (holderPid && isProcessAlive(holderPid)) {
                 throw new ActionDockError(PROJECT_BUSY, `PROJECT_BUSY: Project modification lock is held by PID ${holderPid}. Another command is running in ${projectRoot}.`);
             }
         },
-        onAcquired: () => true,
     });
     let released = false;
     return () => {
         if (released)
             return;
         released = true;
-        safeReleaseProjectLock(lockPath, sessionToken, lockToken);
-        cleanStaleQuarantines(metaDir, LOCK_DIR_NAME);
+        handle.release();
     };
 }
 /**
- * 依据恢复后的锁文件执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
+ * 异步执行子进程并收集退出状态与输出流。
+ *
+ * 异步化取舍说明：
+ * - 避免在事务回滚与恢复链路中执行同步阻塞调用导致事件循环停顿；
+ * - Windows 兼容性保留：npm 在 Windows 上是 .cmd 批处理脚本，启用 shell 以防直接调用抛错；
+ * - 命令与参数由系统内部锁文件逻辑决定，不接受外部未受控入参。
+ */
+function execSubprocessAsync(command, args, options) {
+    return new Promise((resolve, reject) => {
+        try {
+            const proc = spawn(command, args, {
+                cwd: options?.cwd,
+                stdio: "pipe",
+                shell: process.platform === "win32",
+                env: options?.env,
+            });
+            let stdout = "";
+            let stderr = "";
+            if (proc.stdout) {
+                proc.stdout.on("data", (chunk) => {
+                    stdout += chunk.toString();
+                });
+            }
+            if (proc.stderr) {
+                proc.stderr.on("data", (chunk) => {
+                    stderr += chunk.toString();
+                });
+            }
+            let settled = false;
+            proc.on("error", (err) => {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            });
+            proc.on("close", (status) => {
+                if (!settled) {
+                    settled = true;
+                    resolve({ status, stdout, stderr });
+                }
+            });
+        }
+        catch (err) {
+            reject(err);
+        }
+    });
+}
+/**
+ * 依据恢复后的锁文件异步执行禁用安装脚本的冻结安装，使 node_modules 与声明重新一致。
  */
-export function runFrozenInstall(projectRoot) {
+export async function runFrozenInstall(projectRoot) {
     if (process.env.ACTIONDOCK_AUTO_INSTALL === "false") {
         return;
     }
@@ -191,12 +148,7 @@ export function runFrozenInstall(projectRoot) {
         args = ["ci", "--ignore-scripts"];
     }
     try {
-        const check = spawnSync(cmd, ["--version"], {
-            stdio: "pipe",
-            // Windows 兼容：npm 为 .cmd 脚本，无 shell 直接 spawn 必然 ENOENT，
-            // 会误判 npm 缺失而把冻结安装降级为普通 install
-            shell: process.platform === "win32",
-        });
+        const check = await execSubprocessAsync(cmd, ["--version"]);
         if (check.status !== 0) {
             cmd = "npm";
             args = ["install", "--ignore-scripts"];
@@ -206,20 +158,23 @@ export function runFrozenInstall(projectRoot) {
         cmd = "npm";
         args = ["install", "--ignore-scripts"];
     }
-    const proc = spawnSync(cmd, args, {
-        cwd: projectRoot,
-        stdio: "pipe",
-        shell: process.platform === "win32",
-        env: {
-            ...process.env,
-            // 项目级安装禁用 npm 的 allow-scripts 白名单机制，避免用户全局 .npmrc
-            // 的 allow-scripts 约束触发 EALLOWSCRIPTS 导致恢复失败（本安装已带 --ignore-scripts）
-            npm_config_allow_scripts: "",
-            NPM_CONFIG_ALLOW_SCRIPTS: "",
-        },
-    });
+    let proc;
+    try {
+        proc = await execSubprocessAsync(cmd, args, {
+            cwd: projectRoot,
+            env: {
+                ...process.env,
+                npm_config_allow_scripts: "",
+                NPM_CONFIG_ALLOW_SCRIPTS: "",
+            },
+        });
+    }
+    catch (err) {
+        const errorMsg = err?.message || "Unknown error";
+        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
+    }
     if (proc.status !== 0) {
-        const errorMsg = proc.stderr?.toString() || proc.stdout?.toString() || "Unknown error";
+        const errorMsg = proc.stderr || proc.stdout || "Unknown error";
         throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
     }
 }
@@ -291,7 +246,6 @@ export async function beginTransaction(projectRoot, description) {
             meta.status = "committed";
             try {
                 writeFileSync(join(txDir, "transaction.json"), JSON.stringify(meta, null, 2) + "\n", "utf-8");
-                // 成功提交后清理事务目录
                 rmSync(txDir, { recursive: true, force: true });
             }
             finally {
@@ -303,7 +257,6 @@ export async function beginTransaction(projectRoot, description) {
                 return;
             isFinalized = true;
             try {
-                // 逐个恢复快照文件
                 for (const rec of fileRecords) {
                     const targetPath = join(projectRoot, rec.name);
                     const snapPath = join(snapshotDir, rec.name);
@@ -313,15 +266,13 @@ export async function beginTransaction(projectRoot, description) {
                         }
                     }
                     else {
-                        // 原先不存在的文件若在事务中被创建，予以删除
                         if (existsSync(targetPath)) {
                             unlinkSync(targetPath);
                         }
                     }
                 }
-                // 执行冻结安装使 node_modules 与恢复后的声明重新一致
                 if (options?.frozenInstall !== false) {
-                    runFrozenInstall(projectRoot);
+                    await runFrozenInstall(projectRoot);
                 }
                 meta.status = "rolled_back";
                 writeFileSync(join(txDir, "transaction.json"), JSON.stringify(meta, null, 2) + "\n", "utf-8");
@@ -347,9 +298,6 @@ export async function beginTransaction(projectRoot, description) {
 }
 /**
  * 依据事务日志恢复所有待恢复的悬空事务快照，并在成功后执行冻结安装。
- * 进入恢复前通过 acquireProjectLock 原子获取排他锁，持有锁执行恢复，完成后通过释放函数安全释放锁。
- * 若获取锁失败（已有活跃进程正在执行）则安全退出并返回空数组，杜绝 TOCTOU 竞争。
- * 若冻结安装失败则抛出 PROJECT_RECOVERY_REQUIRED 并阻止 Host 启动。
  */
 export async function recoverPendingTransactions(projectRoot, options) {
     const txBaseDir = join(projectRoot, ".actiondock", "transactions");
@@ -362,10 +310,8 @@ export async function recoverPendingTransactions(projectRoot, options) {
     }
     catch (err) {
         if (err?.code === "PROJECT_BUSY") {
-            // 仅当项目锁被其他活跃进程占用时，安全退出并返回空数组
             return [];
         }
-        // 底层系统异常（如 EACCES、ENOSPC、ENOENT 等），向外抛出，严禁静默吞掉
         throw err;
     }
     try {
@@ -385,7 +331,6 @@ export async function recoverPendingTransactions(projectRoot, options) {
             }
             if (meta.status === "pending") {
                 const snapshotDir = join(txDir, "snapshot");
-                // 逐个恢复快照文件
                 for (const rec of meta.files) {
                     const targetPath = join(projectRoot, rec.name);
                     const snapPath = join(snapshotDir, rec.name);
@@ -401,7 +346,7 @@ export async function recoverPendingTransactions(projectRoot, options) {
                     }
                 }
                 if (options?.frozenInstall !== false) {
-                    runFrozenInstall(projectRoot);
+                    await runFrozenInstall(projectRoot);
                 }
                 meta.status = "rolled_back";
                 try {

package/dist/project/types-generator.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { computeManifestDigest } from "./digest.js";
 import { loadManifest } from "./manifest.js";
+import { ActionDockError, MANIFEST_NOT_FOUND } from "../errors.js";
 export const GENERATED_TYPES_REL_PATH = join(".actiondock", "generated", "actions.d.ts");
 export const GENERATED_TYPES_OUTDATED_CODE = "GENERATED_TYPES_OUTDATED";
 /**
@@ -118,7 +119,7 @@ export type TypedActionDefinition<T extends keyof ActionSchemaMap> = ActionDefin
 export function writeActionTypes(projectRoot, manifest) {
     const targetManifest = manifest || loadManifest(projectRoot);
     if (!targetManifest) {
-        throw new Error(`actiondock.json not found in ${projectRoot}`);
+        throw new ActionDockError(MANIFEST_NOT_FOUND, `actiondock.json not found in ${projectRoot}`);
     }
     const { code, digest } = generateActionTypes(targetManifest);
     const fullPath = join(projectRoot, GENERATED_TYPES_REL_PATH);

package/dist/project/types.d.ts

@@ -46,6 +46,8 @@ export interface ActionManifestEntry {
 export interface PlaybookManifestEntry {
     /** Playbook Markdown 入口文件相对路径（如 "playbooks/greet-user.md"） */
     entry: string;
+    /** Playbook 展示名称，缺省回落文件名派生 */
+    name?: string;
     /** Playbook 任务描述 */
     description?: string;
     /** 该 Playbook 所依赖/调用的 Action ID 列表 */

package/dist/registry/index.d.ts

@@ -2,6 +2,5 @@ export * from "./lock.js";
 export type { RegistryLockOptions } from "./lock.js";
 export * from "./registry.js";
 export * from "./scan.js";
-export * from "./store.js";
 export * from "./types.js";
 export { getActionDockHome, getPackageSlug, } from "../utils/index.js";

package/dist/registry/index.js

@@ -1,6 +1,5 @@
 export * from "./lock.js";
 export * from "./registry.js";
 export * from "./scan.js";
-export * from "./store.js";
 export * from "./types.js";
 export { getActionDockHome, getPackageSlug, } from "../utils/index.js";

package/dist/registry/lock.d.ts

@@ -14,8 +14,7 @@ export declare const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
 export declare const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
 /**
  * 持锁期间的心跳续期间隔。持有者定期 touch 锁目录刷新 mtime，
- * 使长耗时持锁操作（如 linkPackage 的深度扫描）不会仅因耗时超过
- * stale 阈值而被等待方误判为残留锁抢占。
+ * 使长耗时持锁操作不会仅因耗时超过 stale 阈值而被等待方误判为残留锁抢占。
  */
 export declare const REGISTRY_LOCK_HEARTBEAT_MS = 3000;
 /**
@@ -29,15 +28,7 @@ export interface RegistryLockOptions {
 }
 /**
  * 异步注册表锁（防止多进程并发读写导致 registry.json 损坏）。
- *
- * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录，
- * 创建成功后立即写入含 pid 与随机 token 的 metadata.json。
- * 冲突处理：EEXIST 时按保守语义判定残留（见 isStaleLock）：mtime 超龄且
- * pid 已死才抢占——抢占仍通过原子 rename 到隔离名实现，rename 仅有一个
- * 进程能成功，失败方回到等待重试，消除「检查后删除再重建」的竞态窗口；
- * 未过期的锁通过 sleep 让出事件循环后重试。
- * 心跳续期：持锁期间以固定间隔 touch 锁目录刷新 mtime，使 linkPackage 等
- * 长耗时持锁操作不会仅因耗时被误判残留；fn 完成后停止心跳并删除锁目录。
+ * 基于统一轻量文件锁原语实现。
  *
  * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
  * @param fn 持锁期间执行的操作（同步或异步）