@actiondock/core 2.0.12 → 2.2.1

package/dist/registry/registry.js

@@ -0,0 +1,611 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
+import { getActionDockHome, getPackageSlug } from "../utils/index.js";
+import { withRegistryLock } from "./lock.js";
+import { buildLinkedPackageEntry, discoverProjectConfigs, discoverProjectConfigsAsync, discoverProjects, pathExistsAsync, } from "./scan.js";
+import { probeActionAsync, probeActionSync, probePlaybook, resolveEntityFlow, runFlowAsync, runFlowSync, } from "./resolve.js";
+/**
+ * 空注册表初始结构。
+ */
+function emptyRegistry() {
+    return { version: "2.0.0", packages: {}, workspaces: {} };
+}
+/**
+ * 注册表内容解析与 links 迁移（纯函数，同步与异步加载共享的唯一事实源）。
+ *
+ * @param raw 文件原始文本
+ * @param filePath 注册表文件路径（用于错误信息定位）
+ * @returns 解析后的注册表数据
+ * @throws JSON 非法或顶层非对象时抛出带恢复指引的错误（调用方负责留档原文件）
+ */
+export function parseRegistryContent(raw, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Registry file '${filePath}' is corrupted (invalid JSON: ${err.message}). ` +
+            `The original data has been preserved as '${filePath}.corrupt' and can be restored manually. ` +
+            `Fix or restore the file, or remove it to start with an empty registry.`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`Registry file '${filePath}' is corrupted (top-level value is not an object). ` +
+            `The original data has been preserved as '${filePath}.corrupt' and can be restored manually. ` +
+            `Fix or restore the file, or remove it to start with an empty registry.`);
+    }
+    const packages = parsed.packages || {};
+    const workspaces = parsed.workspaces || {};
+    // 格式兼容与迁移：如果包含 schemaVersion: 1 的 links 但缺少 packages/workspaces
+    if (Array.isArray(parsed.links) && Object.keys(packages).length === 0 && Object.keys(workspaces).length === 0) {
+        for (const link of parsed.links) {
+            if (!link.path || !existsSync(link.path))
+                continue;
+            if (link.type === "workspace") {
+                workspaces[link.path] = {
+                    path: resolve(link.path),
+                    linkedAt: link.linkedAt || new Date().toISOString(),
+                };
+            }
+            else {
+                try {
+                    const config = loadProjectConfig(link.path);
+                    packages[config.id] = buildLinkedPackageEntry(config, resolve(link.path), link.linkedAt || new Date().toISOString());
+                }
+                catch {
+                    // 迁移时项目已损坏或配置非法：跳过该条 link，避免迁移整体失败
+                }
+            }
+        }
+    }
+    return {
+        version: "2.0.0",
+        packages,
+        workspaces,
+    };
+}
+export function getRegistryFilePath(customHome) {
+    const baseDir = getActionDockHome(customHome);
+    return join(baseDir, ".actiondock", "registry.json");
+}
+/**
+ * 同步加载注册表（保留同步签名供 CLI 与诊断路径使用）。
+ *
+ * @throws 注册表文件损坏时抛出带恢复指引的错误，绝不静默返回空表，
+ * 否则下次 save 会用空数据覆盖原文件导致全部链接记录丢失
+ */
+export function loadRegistry(customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    if (!existsSync(filePath)) {
+        return emptyRegistry();
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return emptyRegistry();
+        }
+        throw err;
+    }
+    try {
+        return parseRegistryContent(raw, filePath);
+    }
+    catch (err) {
+        archiveCorruptFile(filePath);
+        throw err;
+    }
+}
+/**
+ * 异步加载注册表（损坏语义与同步版一致：留档后抛错，不静默清空）。
+ */
+export async function loadRegistryAsync(customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return emptyRegistry();
+        }
+        throw err;
+    }
+    try {
+        return parseRegistryContent(raw, filePath);
+    }
+    catch (err) {
+        archiveCorruptFile(filePath);
+        throw err;
+    }
+}
+/**
+ * 将损坏的注册表文件原子留档为 `${filePath}.corrupt`，
+ * 后续 save 的临时文件 rename 不会覆盖留档（文件名不同）。
+ */
+function archiveCorruptFile(filePath) {
+    try {
+        renameSync(filePath, `${filePath}.corrupt`);
+    }
+    catch {
+        // 留档失败（如文件被其他进程先行移动）时仅放弃留档：错误仍会向上抛出，
+        // 不会出现静默清空
+    }
+}
+/**
+ * 由结构化数据构造统一落盘载荷（schemaVersion 1 复合格式，保障双向兼容）。
+ */
+function buildUnifiedPayload(data) {
+    const links = [];
+    if (data.workspaces) {
+        for (const [wsPath, ws] of Object.entries(data.workspaces)) {
+            links.push({
+                type: "workspace",
+                path: resolve(ws.path || wsPath),
+                linkedAt: ws.linkedAt || new Date().toISOString(),
+                depth: 3,
+            });
+        }
+    }
+    if (data.packages) {
+        for (const pkg of Object.values(data.packages)) {
+            if (!pkg.workspaceRoot && pkg.path) {
+                links.push({
+                    type: "package",
+                    path: resolve(pkg.path),
+                    linkedAt: pkg.linkedAt || new Date().toISOString(),
+                });
+            }
+        }
+    }
+    return {
+        version: "2.0.0",
+        schemaVersion: 1,
+        packages: data.packages || {},
+        workspaces: data.workspaces || {},
+        links,
+    };
+}
+let tmpFileSeq = 0;
+/**
+ * 原子写入注册表：临时文件写盘后 rename，持锁执行，避免并发撕裂。
+ */
+export async function saveRegistry(data, customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    ensureRegistryDir(filePath);
+    const unifiedData = buildUnifiedPayload(data);
+    const payload = JSON.stringify(unifiedData, null, 2) + "\n";
+    await withRegistryLock(filePath, async () => {
+        await writeRegistryPayloadLocked(filePath, payload);
+    });
+}
+/**
+ * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用，
+ * 避免与 saveRegistry 的锁重入死等）；调用方必须已持有对应锁。
+ */
+export async function writeRegistryLocked(data, customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    ensureRegistryDir(filePath);
+    const payload = JSON.stringify(buildUnifiedPayload(data), null, 2) + "\n";
+    await writeRegistryPayloadLocked(filePath, payload);
+}
+/**
+ * 原子落盘单次写入：临时文件写盘后 rename；文件名含进程号与自增序号，
+ * 确保同一进程内多次保存也不会冲突。
+ */
+async function writeRegistryPayloadLocked(filePath, payload) {
+    const tempPath = `${filePath}.${process.pid}.${++tmpFileSeq}.tmp`;
+    await writeFile(tempPath, payload, "utf-8");
+    await rename(tempPath, filePath);
+}
+function ensureRegistryDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+export async function linkPackage(targetPath = process.cwd(), customHome, options) {
+    const filePath = getRegistryFilePath(customHome);
+    ensureRegistryDir(filePath);
+    const absPath = resolve(targetPath);
+    const directHasConfig = existsSync(join(absPath, "actiondock.json"));
+    // 如果当前目录直接包含 actiondock.json 且未强制递归，按单包链接
+    if (directHasConfig && !options?.recursive) {
+        const config = loadProjectConfig(absPath);
+        return await withRegistryLock(filePath, async () => {
+            const registry = await loadRegistryAsync(customHome);
+            const entry = buildLinkedPackageEntry(config, absPath, new Date().toISOString());
+            registry.packages[config.id] = entry;
+            await writeRegistryLocked(registry, customHome);
+            return {
+                id: config.id,
+                name: entry.name,
+                version: entry.version,
+                path: absPath,
+                linkedAt: entry.linkedAt,
+                isWorkspace: false,
+                entries: [entry],
+            };
+        });
+    }
+    // 尝试扫描子目录发现多个 ActionDock 子项目（Workspace 模式）；
+    // 门槛以「发现子项目根目录」为准而非「配置可加载」，即使全部子项目配置损坏
+    // 也仍注册 workspace（与旧版行为一致，避免边缘场景下静默落入父级回退分支）
+    const discoveredRoots = discoverProjects(absPath);
+    if (discoveredRoots.length > 0) {
+        return await withRegistryLock(filePath, async () => {
+            const registry = await loadRegistryAsync(customHome);
+            const now = new Date().toISOString();
+            const wsEntry = {
+                path: absPath,
+                linkedAt: now,
+            };
+            registry.workspaces = registry.workspaces || {};
+            registry.workspaces[absPath] = wsEntry;
+            const linkedEntries = [];
+            for (const root of discoveredRoots) {
+                try {
+                    const config = loadProjectConfig(root);
+                    const entry = buildLinkedPackageEntry(config, root, now, absPath);
+                    registry.packages[config.id] = entry;
+                    linkedEntries.push(entry);
+                }
+                catch {
+                    // 子项目配置损坏：跳过该子项目条目，不影响 workspace 注册本身
+                }
+            }
+            await writeRegistryLocked(registry, customHome);
+            const wsName = basename(absPath);
+            return {
+                id: wsName,
+                name: wsName,
+                version: "2.0.0",
+                path: absPath,
+                linkedAt: now,
+                isWorkspace: true,
+                entries: linkedEntries,
+                workspace: wsEntry,
+            };
+        });
+    }
+    // 回退检查：如果在子目录执行（例如在 package 的 actions/ 目录下），查找父级项目根目录
+    const parentRoot = findProjectRoot(absPath);
+    if (parentRoot) {
+        const config = loadProjectConfig(parentRoot);
+        return await withRegistryLock(filePath, async () => {
+            const registry = await loadRegistryAsync(customHome);
+            const entry = buildLinkedPackageEntry(config, parentRoot, new Date().toISOString());
+            registry.packages[config.id] = entry;
+            await writeRegistryLocked(registry, customHome);
+            return {
+                id: config.id,
+                name: entry.name,
+                version: entry.version,
+                path: parentRoot,
+                linkedAt: entry.linkedAt,
+                isWorkspace: false,
+                entries: [entry],
+            };
+        });
+    }
+    throw new Error(`Cannot link: actiondock.json not found in '${absPath}' or its subdirectories`);
+}
+export async function unlinkPackage(identifier = process.cwd(), customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    ensureRegistryDir(filePath);
+    return await withRegistryLock(filePath, async () => {
+        const registry = await loadRegistryAsync(customHome);
+        const absPath = resolve(identifier);
+        // 检查是否匹配 Workspace 绝对路径
+        if (registry.workspaces && registry.workspaces[absPath]) {
+            const removedWs = registry.workspaces[absPath];
+            delete registry.workspaces[absPath];
+            let removedCount = 0;
+            for (const [id, entry] of Object.entries(registry.packages)) {
+                if (entry.workspaceRoot === absPath || entry.path.startsWith(absPath)) {
+                    delete registry.packages[id];
+                    removedCount++;
+                }
+            }
+            await writeRegistryLocked(registry, customHome);
+            return {
+                type: "workspace",
+                id: basename(absPath),
+                path: absPath,
+                packagesCount: removedCount,
+                removedWorkspace: removedWs,
+            };
+        }
+        // 检查是否匹配 Workspace 目录别名
+        if (registry.workspaces) {
+            for (const [wsPath, wsEntry] of Object.entries(registry.workspaces)) {
+                if (basename(wsPath) === identifier) {
+                    delete registry.workspaces[wsPath];
+                    let removedCount = 0;
+                    for (const [id, entry] of Object.entries(registry.packages)) {
+                        if (entry.workspaceRoot === wsPath || entry.path.startsWith(wsPath)) {
+                            delete registry.packages[id];
+                            removedCount++;
+                        }
+                    }
+                    await writeRegistryLocked(registry, customHome);
+                    return {
+                        type: "workspace",
+                        id: basename(wsPath),
+                        path: wsPath,
+                        packagesCount: removedCount,
+                        removedWorkspace: wsEntry,
+                    };
+                }
+            }
+        }
+        // 检查是否直接匹配 Package ID
+        let targetKey;
+        if (registry.packages[identifier]) {
+            targetKey = identifier;
+        }
+        else {
+            // 匹配路径或短 slug
+            for (const [id, entry] of Object.entries(registry.packages)) {
+                if (entry.path === absPath ||
+                    entry.id === identifier ||
+                    getPackageSlug(entry.id) === identifier) {
+                    targetKey = id;
+                    break;
+                }
+            }
+        }
+        if (!targetKey) {
+            return null;
+        }
+        const removed = registry.packages[targetKey];
+        delete registry.packages[targetKey];
+        await writeRegistryLocked(registry, customHome);
+        return {
+            type: "package",
+            id: removed.id,
+            path: removed.path,
+            packagesCount: 1,
+            removedPackage: removed,
+        };
+    });
+}
+export function listLinkedPackages(customHome) {
+    const registry = loadRegistry(customHome);
+    const result = { ...registry.packages };
+    // 动态扫描已挂载的 Workspace 目录，确保新拉取/新建的子包即时感知
+    if (registry.workspaces) {
+        for (const ws of Object.values(registry.workspaces)) {
+            if (!existsSync(ws.path))
+                continue;
+            for (const { root, config } of discoverProjectConfigs(ws.path)) {
+                if (!result[config.id] || result[config.id].workspaceRoot === ws.path) {
+                    result[config.id] = buildLinkedPackageEntry(config, root, ws.linkedAt, ws.path);
+                }
+            }
+        }
+    }
+    return Object.values(result);
+}
+export async function listLinkedPackagesAsync(customHome) {
+    const registry = await loadRegistryAsync(customHome);
+    const result = { ...registry.packages };
+    if (registry.workspaces) {
+        for (const ws of Object.values(registry.workspaces)) {
+            if (!(await pathExistsAsync(ws.path)))
+                continue;
+            for (const { root, config } of await discoverProjectConfigsAsync(ws.path)) {
+                if (!result[config.id] || result[config.id].workspaceRoot === ws.path) {
+                    result[config.id] = buildLinkedPackageEntry(config, root, ws.linkedAt, ws.path);
+                }
+            }
+        }
+    }
+    return Object.values(result);
+}
+export function listLinkedWorkspaces(customHome) {
+    const registry = loadRegistry(customHome);
+    return Object.values(registry.workspaces || {});
+}
+export function resolveActionProjectSync(actionIdentifier, cwd = process.cwd(), customHome) {
+    return runFlowSync(resolveEntityFlow({
+        identifier: actionIdentifier,
+        cwd,
+        entityNoun: "Action",
+        listLinkedPackages: () => listLinkedPackages(customHome),
+        probe: (root, config, id) => probeActionSync(root, config, id),
+        buildResult: (projectRoot, packageId, actionId) => ({ projectRoot, packageId, actionId }),
+    }));
+}
+export async function resolveActionProject(actionIdentifier, cwd = process.cwd(), customHome) {
+    return runFlowAsync(resolveEntityFlow({
+        identifier: actionIdentifier,
+        cwd,
+        entityNoun: "Action",
+        listLinkedPackages: () => listLinkedPackagesAsync(customHome),
+        probe: (root, config, id) => probeActionAsync(root, config, id),
+        buildResult: (projectRoot, packageId, actionId) => ({ projectRoot, packageId, actionId }),
+    }));
+}
+export function resolvePlaybookProject(playbookIdentifier, cwd = process.cwd(), customHome) {
+    return runFlowSync(resolveEntityFlow({
+        identifier: playbookIdentifier,
+        cwd,
+        entityNoun: "Playbook",
+        listLinkedPackages: () => listLinkedPackages(customHome),
+        probe: (root, config, id) => probePlaybook(root, config, id),
+        buildResult: (projectRoot, packageId, playbookId, playbook) => ({
+            projectRoot,
+            packageId,
+            playbookId,
+            playbook,
+        }),
+    }));
+}
+export function resolvePackageRoot(packageIdOrPath, cwd, customHome) {
+    if (!packageIdOrPath) {
+        return findProjectRoot(cwd);
+    }
+    const baseDir = cwd || process.cwd();
+    const resolvedPath = resolve(baseDir, packageIdOrPath);
+    // 检查 packageIdOrPath 是否为磁盘上现存的目录或文件路径
+    if (existsSync(resolvedPath)) {
+        try {
+            const info = statSync(resolvedPath);
+            const targetDir = info.isDirectory() ? resolvedPath : dirname(resolvedPath);
+            if (existsSync(join(targetDir, "actiondock.json"))) {
+                return targetDir;
+            }
+            const parentRoot = findProjectRoot(targetDir);
+            if (parentRoot) {
+                return parentRoot;
+            }
+        }
+        catch {
+            // stat 失败（如并发删除）：忽略并继续走标识符解析路径
+        }
+    }
+    // 显式路径形态但未解析成功的场景：
+    // scoped package 标识符（如 @team/tools）虽含 '/' 但属于包 ID 而非文件路径
+    const isScopedPackage = packageIdOrPath.startsWith("@");
+    const isExplicitPath = !isScopedPackage &&
+        (packageIdOrPath.startsWith(".") ||
+            packageIdOrPath.startsWith("/") ||
+            packageIdOrPath.startsWith("~") ||
+            packageIdOrPath.includes("/") ||
+            packageIdOrPath.includes("\\"));
+    if (isExplicitPath) {
+        // 显式路径不存在或不是 ActionDock 项目时必须失败，禁止静默回退
+        return null;
+    }
+    // 检查当前项目（自 cwd 向上探测）
+    const currentRoot = findProjectRoot(cwd);
+    if (currentRoot) {
+        try {
+            const config = loadProjectConfig(currentRoot);
+            if (config.id === packageIdOrPath || getPackageSlug(config.id) === packageIdOrPath) {
+                return currentRoot;
+            }
+        }
+        catch {
+            // 当前项目配置损坏：忽略，继续注册表匹配
+        }
+    }
+    // 检查注册表中的链接包
+    const linkedList = listLinkedPackages(customHome);
+    const found = linkedList.find((p) => p.id === packageIdOrPath ||
+        getPackageSlug(p.id) === packageIdOrPath ||
+        p.path === resolvedPath);
+    if (found) {
+        return found.path;
+    }
+    return null;
+}
+export function getRegistryStatus(customHome) {
+    const registry = loadRegistry(customHome);
+    const workspaces = [];
+    const packages = [];
+    let staleCount = 0;
+    const seenPackageIds = new Set();
+    // 处理 Workspace：目录存活则动态扫描子项目，缺失则标记 stale
+    if (registry.workspaces) {
+        for (const wsPath of Object.keys(registry.workspaces)) {
+            if (!existsSync(wsPath)) {
+                staleCount++;
+                workspaces.push({
+                    type: "workspace",
+                    id: basename(wsPath),
+                    path: wsPath,
+                    status: "stale",
+                    packagesCount: 0,
+                    children: [],
+                });
+                continue;
+            }
+            const children = [];
+            for (const { root, config } of discoverProjectConfigs(wsPath)) {
+                seenPackageIds.add(config.id);
+                children.push({
+                    id: config.id,
+                    name: config.name || config.id,
+                    version: config.version || "0.0.0",
+                    path: root,
+                    status: "active",
+                });
+            }
+            workspaces.push({
+                type: "workspace",
+                id: basename(wsPath),
+                path: wsPath,
+                status: "active",
+                packagesCount: children.length,
+                children,
+            });
+        }
+    }
+    // 处理独立包（不属于任何存活 Workspace 且未被动态扫描覆盖）
+    for (const [pkgId, pkgEntry] of Object.entries(registry.packages)) {
+        if (pkgEntry.workspaceRoot && registry.workspaces && registry.workspaces[pkgEntry.workspaceRoot]) {
+            continue;
+        }
+        if (seenPackageIds.has(pkgId)) {
+            continue;
+        }
+        const isPkgActive = existsSync(pkgEntry.path);
+        if (!isPkgActive) {
+            staleCount++;
+        }
+        packages.push({
+            type: "package",
+            id: pkgEntry.id,
+            name: pkgEntry.name,
+            version: pkgEntry.version,
+            path: pkgEntry.path,
+            status: isPkgActive ? "active" : "stale",
+        });
+    }
+    const totalPackagesCount = workspaces.reduce((acc, ws) => acc + (ws.children?.length || 0), 0) +
+        packages.filter((p) => p.status === "active").length;
+    return {
+        workspaces,
+        packages,
+        staleCount,
+        totalPackagesCount,
+    };
+}
+export async function pruneRegistry(customHome) {
+    const filePath = getRegistryFilePath(customHome);
+    ensureRegistryDir(filePath);
+    return await withRegistryLock(filePath, async () => {
+        const registry = await loadRegistryAsync(customHome);
+        const prunedWorkspaces = [];
+        const prunedPackages = [];
+        // 清理目录已缺失的 Workspace 链接
+        if (registry.workspaces) {
+            for (const [wsPath, wsEntry] of Object.entries(registry.workspaces)) {
+                if (!existsSync(wsPath)) {
+                    prunedWorkspaces.push(wsEntry);
+                    delete registry.workspaces[wsPath];
+                }
+            }
+        }
+        // 清理路径已缺失的 Package 链接
+        for (const [pkgId, pkgEntry] of Object.entries(registry.packages)) {
+            if (!existsSync(pkgEntry.path)) {
+                prunedPackages.push(pkgEntry);
+                delete registry.packages[pkgId];
+            }
+        }
+        if (prunedWorkspaces.length > 0 || prunedPackages.length > 0) {
+            await writeRegistryLocked(registry, customHome);
+        }
+        return {
+            prunedPackages,
+            prunedWorkspaces,
+        };
+    });
+}
+// 重新导出扫描辅助，保持既有从 registry 模块的导入路径可用
+export { discoverProjects, IGNORED_SCAN_DIRS } from "./scan.js";

package/dist/registry/resolve.d.ts

@@ -0,0 +1,62 @@
+import type { ActionDockManifest, PlaybookDefinition } from "../project/types.js";
+import type { LinkedPackageEntry } from "./types.js";
+/**
+ * 流程步骤的惰性执行体：同步驱动器直接调用，异步驱动器 await，
+ * 执行中抛出的异常由驱动器通过 it.throw 回灌生成器的 try/catch。
+ */
+type FlowThunk = () => any;
+/**
+ * 实体解析探针：命中返回实体值（Action 场景恒为 true），未命中返回 undefined。
+ */
+type EntityProbe<V> = (projectRoot: string, config: ActionDockManifest, entityId: string) => V;
+/**
+ * 由命中结果构造最终解析产物。
+ */
+type EntityResultBuilder<V, R> = (projectRoot: string, packageId: string, entityId: string, value: V) => R;
+interface ResolveEntityFlowOptions<V, R> {
+    /** 实体完整标识符（可能是裸 ID 或 <pkg>/<id>、<pkg>:<id> 形式） */
+    identifier: string;
+    /** 起始工作目录 */
+    cwd: string;
+    /** 实体名词（Action 或 Playbook），仅用于错误文案 */
+    entityNoun: string;
+    /** 获取链接包列表（同步或异步由注入方决定，流程通过 thunk 统一驱动） */
+    listLinkedPackages: () => LinkedPackageEntry[];
+    /** 实体探针 */
+    probe: EntityProbe<V>;
+    /** 解析结果构造器 */
+    buildResult: EntityResultBuilder<V, R>;
+}
+/**
+ * 实体解析唯一流程（生成器表达）：
+ * 当前项目探测 → scoped 标识符拆分 → 注册表精确匹配 → 遍历链接包 →
+ * 单命中返回、多命中报错、零命中报错。
+ *
+ * 仅将可能异步的操作（探针、链接列表获取）以 thunk 形式 yield，
+ * 由 runFlowSync / runFlowAsync 双驱动器分别以同步调用或 await 方式执行。
+ */
+export declare function resolveEntityFlow<V, R>(opts: ResolveEntityFlowOptions<V, R>): Generator<FlowThunk, R, any>;
+/**
+ * 同步驱动器：逐个调用 thunk 并把结果回灌生成器，
+ * thunk 抛出的异常经 it.throw 回灌生成器内部的 try/catch 处理。
+ * 同步流程中误注入异步 thunk 时立即抛错，避免 Promise 被当作命中值静默错判。
+ */
+export declare function runFlowSync<R>(flow: Generator<FlowThunk, R, any>): R;
+/**
+ * 异步驱动器：await 每个 thunk 后回灌结果，拒绝原因经 it.throw 回灌。
+ */
+export declare function runFlowAsync<R>(flow: Generator<FlowThunk, R, any>): Promise<R>;
+/**
+ * Action 探针（同步）：manifest 声明优先，其次探测源码文件是否落盘。
+ */
+export declare function probeActionSync(projectRoot: string, config: ActionDockManifest, actionId: string): true | undefined;
+/**
+ * Action 探针（异步）：manifest 声明优先，其次加载源码模块；
+ * 模块加载失败时回退同步探测，保证与同步路径判定一致。
+ */
+export declare function probeActionAsync(projectRoot: string, config: ActionDockManifest, actionId: string): Promise<true | undefined>;
+/**
+ * Playbook 探针：以 actiondock.json 的 playbooks 声明为唯一事实源，命中返回规程定义。
+ */
+export declare function probePlaybook(projectRoot: string, config: ActionDockManifest, playbookId: string): PlaybookDefinition | undefined;
+export {};