@actiondock/core 2.0.11 → 2.2.0

package/dist/project/types-generator.d.ts

@@ -0,0 +1,33 @@
+import type { ActionDockManifest } from "./types.js";
+export declare const GENERATED_TYPES_REL_PATH: string;
+export declare const GENERATED_TYPES_OUTDATED_CODE = "GENERATED_TYPES_OUTDATED";
+/**
+ * 将 JSON Schema 递归转换为 TypeScript 类型声明字符串。
+ */
+export declare function jsonSchemaToTypeScript(schema: any, indent?: number): string;
+/**
+ * 根据项目清单 Schema 生成类型声明文件内容，头部注入 RFC 8785 Manifest SHA-256 摘要。
+ */
+export declare function generateActionTypes(manifest: ActionDockManifest): {
+    code: string;
+    digest: string;
+};
+/**
+ * 将生成的类型声明写入到项目的 .actiondock/generated/actions.d.ts 文件。
+ */
+export declare function writeActionTypes(projectRoot: string, manifest?: ActionDockManifest | null): {
+    filePath: string;
+    digest: string;
+};
+/**
+ * 只读检查项目中的 .actiondock/generated/actions.d.ts 是否过期。
+ * 若文件不存在，则认为无需校验通过（返回 exists: false, outdated: false）。
+ * 若文件存在但摘要与当前 actiondock.json 不一致，则返回 outdated: true。
+ */
+export declare function checkGeneratedTypes(projectRoot: string, manifest?: ActionDockManifest | null): {
+    exists: boolean;
+    outdated: boolean;
+    expectedDigest?: string;
+    actualDigest?: string;
+    filePath: string;
+};

package/dist/project/types-generator.js

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { computeManifestDigest } from "./digest.js";
+import { loadManifest } from "./manifest.js";
+export const GENERATED_TYPES_REL_PATH = join(".actiondock", "generated", "actions.d.ts");
+export const GENERATED_TYPES_OUTDATED_CODE = "GENERATED_TYPES_OUTDATED";
+/**
+ * 将 JSON Schema 递归转换为 TypeScript 类型声明字符串。
+ */
+export function jsonSchemaToTypeScript(schema, indent = 0) {
+    if (!schema || typeof schema !== "object" || Object.keys(schema).length === 0) {
+        return "unknown";
+    }
+    if (schema.enum && Array.isArray(schema.enum)) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    if (schema.anyOf && Array.isArray(schema.anyOf)) {
+        return `(${schema.anyOf.map((s) => jsonSchemaToTypeScript(s, indent)).join(" | ")})`;
+    }
+    if (schema.oneOf && Array.isArray(schema.oneOf)) {
+        return `(${schema.oneOf.map((s) => jsonSchemaToTypeScript(s, indent)).join(" | ")})`;
+    }
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+        return `(${schema.allOf.map((s) => jsonSchemaToTypeScript(s, indent)).join(" & ")})`;
+    }
+    const type = schema.type;
+    if (type === "string")
+        return "string";
+    if (type === "number" || type === "integer")
+        return "number";
+    if (type === "boolean")
+        return "boolean";
+    if (type === "null")
+        return "null";
+    if (type === "array") {
+        const items = schema.items ? jsonSchemaToTypeScript(schema.items, indent) : "unknown";
+        return `Array<${items}>`;
+    }
+    if (type === "object" || schema.properties) {
+        const props = schema.properties || {};
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const propKeys = Object.keys(props);
+        if (propKeys.length === 0) {
+            return "Record<string, unknown>";
+        }
+        const spaces = " ".repeat(indent + 2);
+        const closeSpaces = " ".repeat(indent);
+        const lines = propKeys.map((k) => {
+            const isReq = required.has(k);
+            const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+            const opt = isReq ? "" : "?";
+            const doc = props[k]?.description
+                ? `${spaces}/** ${props[k].description.replace(/\*\//g, "* /")} */\n`
+                : "";
+            return `${doc}${spaces}${safeKey}${opt}: ${jsonSchemaToTypeScript(props[k], indent + 2)};`;
+        });
+        return `{\n${lines.join("\n")}\n${closeSpaces}}`;
+    }
+    return "unknown";
+}
+/**
+ * 将 Action 标识符转换为合法的 TypeScript 标识符（PascalCase）。
+ */
+function toPascalCase(str) {
+    return str
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
+        .replace(/^[a-z]/, (chr) => chr.toUpperCase())
+        .replace(/[^a-zA-Z0-9]/g, "");
+}
+/**
+ * 根据项目清单 Schema 生成类型声明文件内容，头部注入 RFC 8785 Manifest SHA-256 摘要。
+ */
+export function generateActionTypes(manifest) {
+    const digest = computeManifestDigest(manifest);
+    const actions = manifest.actions || {};
+    const actionEntries = Object.entries(actions);
+    const namespaceBlocks = actionEntries.map(([actionId, item]) => {
+        const name = toPascalCase(actionId);
+        const inType = jsonSchemaToTypeScript(item.inputSchema, 4);
+        const outType = jsonSchemaToTypeScript(item.outputSchema, 4);
+        const descComment = item.description
+            ? `    /**\n     * ${item.description.replace(/\*\//g, "* /")}\n     */\n`
+            : "";
+        return `  export namespace ${name} {\n${descComment}    export type Input = ${inType};\n    export type Output = ${outType};\n  }`;
+    });
+    const mapEntries = actionEntries.map(([actionId]) => {
+        const name = toPascalCase(actionId);
+        return `    "${actionId}": {\n      Input: Actions.${name}.Input;\n      Output: Actions.${name}.Output;\n    };`;
+    });
+    const code = `/**
+ * AUTO-GENERATED BY ACTIONDOCK. DO NOT EDIT DIRECTLY.
+ * @manifest-digest ${digest}
+ */
+
+import type { ActionContext, ActionDefinition } from "@actiondock/sdk";
+
+export namespace Actions {
+${namespaceBlocks.join("\n\n")}
+}
+
+export interface ActionSchemaMap {
+${mapEntries.join("\n")}
+}
+
+export type ActionInput<T extends keyof ActionSchemaMap> = ActionSchemaMap[T]["Input"];
+export type ActionOutput<T extends keyof ActionSchemaMap> = ActionSchemaMap[T]["Output"];
+
+export type TypedActionDefinition<T extends keyof ActionSchemaMap> = ActionDefinition<
+  ActionSchemaMap[T]["Input"],
+  ActionSchemaMap[T]["Output"]
+>;
+`;
+    return { code, digest };
+}
+/**
+ * 将生成的类型声明写入到项目的 .actiondock/generated/actions.d.ts 文件。
+ */
+export function writeActionTypes(projectRoot, manifest) {
+    const targetManifest = manifest || loadManifest(projectRoot);
+    if (!targetManifest) {
+        throw new Error(`actiondock.json not found in ${projectRoot}`);
+    }
+    const { code, digest } = generateActionTypes(targetManifest);
+    const fullPath = join(projectRoot, GENERATED_TYPES_REL_PATH);
+    const dir = dirname(fullPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(fullPath, code, "utf-8");
+    return { filePath: fullPath, digest };
+}
+/**
+ * 只读检查项目中的 .actiondock/generated/actions.d.ts 是否过期。
+ * 若文件不存在，则认为无需校验通过（返回 exists: false, outdated: false）。
+ * 若文件存在但摘要与当前 actiondock.json 不一致，则返回 outdated: true。
+ */
+export function checkGeneratedTypes(projectRoot, manifest) {
+    const fullPath = join(projectRoot, GENERATED_TYPES_REL_PATH);
+    if (!existsSync(fullPath)) {
+        return { exists: false, outdated: false, filePath: fullPath };
+    }
+    const targetManifest = manifest || loadManifest(projectRoot);
+    if (!targetManifest) {
+        return { exists: true, outdated: true, filePath: fullPath };
+    }
+    const expectedDigest = computeManifestDigest(targetManifest);
+    try {
+        const content = readFileSync(fullPath, "utf-8");
+        const match = content.match(/@manifest-digest\s+([^\s*]+)/);
+        const actualDigest = match ? match[1] : undefined;
+        const outdated = actualDigest !== expectedDigest;
+        return {
+            exists: true,
+            outdated,
+            expectedDigest,
+            actualDigest,
+            filePath: fullPath,
+        };
+    }
+    catch {
+        return {
+            exists: true,
+            outdated: true,
+            expectedDigest,
+            filePath: fullPath,
+        };
+    }
+}

package/dist/project/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 配置项的值类型枚举。用于自动类型推断与环境变量自动转换。
+ */
+export type ConfigValueType = "string" | "number" | "boolean" | "object" | "array";
+/**
+ * 在 actiondock.json 中声明的单项配置定义。
+ */
+export interface ConfigItemDefinition {
+    /** 配置项的功能描述，展示在 CLI 配置提示与帮助文档中 */
+    description?: string;
+    /** 默认回退值。若未配置任何自定义值或环境变量，将使用此默认值 */
+    default?: unknown;
+    /** 是否为敏感信息（如 API Key, Password）。若为 true，在日志与 CLI 输出中默认脱敏 */
+    secret?: boolean;
+    /** 期望的目标数据类型，从 process.env 读取字符串时将自动尝试强转为此类型 */
+    type?: ConfigValueType;
+    /** 显式绑定的外部环境变量名（支持单个或优先级数组） */
+    env?: string | string[];
+    /** 是否为必填项 */
+    required?: boolean;
+    /** 是否允许单次调用覆盖 */
+    allowInvocationOverride?: boolean;
+}
+/**
+ * 单个 Action 在 actiondock.json 清单中的声明项。
+ */
+export interface ActionManifestEntry {
+    /** Action 入口文件相对路径（如 "actions/greet.ts"） */
+    entry: string;
+    /** Action 功能描述 */
+    description?: string;
+    /** 输入参数模式规范 */
+    inputSchema?: Record<string, unknown> | boolean;
+    /** 输出结果模式规范 */
+    outputSchema?: Record<string, unknown> | boolean;
+    /** 静态依赖的 Action 列表 */
+    uses?: string[];
+    /** 标签列表 */
+    tags?: string[];
+    /** 协议注解元数据 */
+    annotations?: Record<string, unknown>;
+}
+/**
+ * 单个 Playbook 在 actiondock.json 清单中的声明项。
+ */
+export interface PlaybookManifestEntry {
+    /** Playbook Markdown 入口文件相对路径（如 "playbooks/greet-user.md"） */
+    entry: string;
+    /** Playbook 任务描述 */
+    description?: string;
+    /** 该 Playbook 所依赖/调用的 Action ID 列表 */
+    actions?: string[];
+}
+/**
+ * ActionDock 声明式元数据清单契约（actiondock.json 为唯一事实源）。
+ */
+export interface ActionDockManifest {
+    /** JSON Schema 声明 URL */
+    $schema?: string;
+    /** 清单规范版本号（默认 2） */
+    schemaVersion?: number;
+    /** 项目全局唯一逻辑 ID（例如 "team4u.github-tools"） */
+    id: string;
+    /** 项目展示名称（例如 "GitHub Tools"） */
+    name?: string;
+    /** 项目版本号（如 "1.0.0"） */
+    version?: string;
+    /** 项目描述信息 */
+    description?: string;
+    /** 声明的项目依赖配置项清单 */
+    config?: Record<string, ConfigItemDefinition>;
+    /** 声明的 Actions 集合（唯一事实源） */
+    actions?: Record<string, ActionManifestEntry>;
+    /** 声明的 Playbooks 集合（唯一事实源） */
+    playbooks?: Record<string, PlaybookManifestEntry>;
+    /** 跨包外部依赖映射（逻辑包 ID 到 npm 包名） */
+    dependencies?: Record<string, string>;
+    /** 框架导出与分发边界文件列表 */
+    files?: string[];
+    /** 静态资产列表 */
+    assets?: string[];
+    /** Action 源码存放目录（向后兼容过渡配置） */
+    actionsDir?: string;
+    /** Playbook 规程文档存放目录（向后兼容过渡配置） */
+    playbooksDir?: string;
+}
+/**
+ * ActionDock 项目根配置文件契约（等同于 ActionDockManifest，actiondock.json 为单一事实源）。
+ */
+export type ProjectConfig = ActionDockManifest;
+/**
+ * 解析后的完整 Playbook 定义对象。
+ */
+export interface PlaybookDefinition {
+    /** Playbook 唯一标识符（例如 "review-pr"） */
+    id: string;
+    /** Playbook 显示名称 */
+    name?: string;
+    /** Playbook 任务描述 */
+    description?: string;
+    /** 该 Playbook 所依赖/调用的 Action ID 列表 */
+    actions: string[];
+    /** Markdown 正文内容（纯 Markdown 规程内容） */
+    content: string;
+    /** Playbook 源文件的绝对物理路径 */
+    filePath: string;
+}

package/dist/project/types.js

@@ -0,0 +1 @@
+export {};

package/dist/registry/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./lock.js";
+export * from "./registry.js";
+export * from "./resolve.js";
+export * from "./scan.js";
+export * from "./types.js";

package/dist/registry/index.js

@@ -0,0 +1,5 @@
+export * from "./lock.js";
+export * from "./registry.js";
+export * from "./resolve.js";
+export * from "./scan.js";
+export * from "./types.js";

package/dist/registry/lock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 锁目录创建后超过该时长仍未释放，视为持有进程异常退出的残留锁。
+ */
+export declare const REGISTRY_LOCK_STALE_MS = 10000;
+/**
+ * 获取锁的最长等待时间，必须大于 REGISTRY_LOCK_STALE_MS，
+ * 保证等待方至少有机会观察到残留锁被回收后再判定超时。
+ */
+export declare const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
+/**
+ * 两次获取尝试之间的退避间隔，休眠让出事件循环，避免忙等阻塞。
+ */
+export declare const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
+/**
+ * 异步注册表锁（防止多进程并发读写导致 registry.json 损坏）。
+ *
+ * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录。
+ * 冲突处理：EEXIST 时 stat 检查锁目录年龄，超过 stale 阈值则先原子 rename 到
+ * 隔离名再删除——rename 仅有一个进程能成功，失败方回到等待重试，消除
+ * 「stat 检查后删除再重建」的竞态窗口；未过期的锁通过 sleep 让出事件循环后重试。
+ *
+ * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
+ * @param fn 持锁期间执行的操作（同步或异步）
+ * @returns fn 的返回值
+ * @throws 超过 REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS 仍未获取时抛出描述性错误
+ */
+export declare function withRegistryLock<T>(filePath: string, fn: () => T | Promise<T>): Promise<T>;

package/dist/registry/lock.js

@@ -0,0 +1,93 @@
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+/**
+ * 锁目录创建后超过该时长仍未释放，视为持有进程异常退出的残留锁。
+ */
+export const REGISTRY_LOCK_STALE_MS = 10000;
+/**
+ * 获取锁的最长等待时间，必须大于 REGISTRY_LOCK_STALE_MS，
+ * 保证等待方至少有机会观察到残留锁被回收后再判定超时。
+ */
+export const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
+/**
+ * 两次获取尝试之间的退避间隔，休眠让出事件循环，避免忙等阻塞。
+ */
+export const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * 异步注册表锁（防止多进程并发读写导致 registry.json 损坏）。
+ *
+ * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录。
+ * 冲突处理：EEXIST 时 stat 检查锁目录年龄，超过 stale 阈值则先原子 rename 到
+ * 隔离名再删除——rename 仅有一个进程能成功，失败方回到等待重试，消除
+ * 「stat 检查后删除再重建」的竞态窗口；未过期的锁通过 sleep 让出事件循环后重试。
+ *
+ * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
+ * @param fn 持锁期间执行的操作（同步或异步）
+ * @returns fn 的返回值
+ * @throws 超过 REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS 仍未获取时抛出描述性错误
+ */
+export async function withRegistryLock(filePath, fn) {
+    const lockDir = `${filePath}.lock`;
+    const deadline = Date.now() + REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS;
+    while (true) {
+        try {
+            // 原子获取：目录创建成功即持有锁，无需二次确认
+            await mkdir(lockDir);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                throw err;
+            }
+        }
+        // 锁被占用，检查是否为残留的过期锁
+        let lockAgeMs;
+        try {
+            const info = await stat(lockDir);
+            lockAgeMs = Date.now() - info.mtimeMs;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // 持有者恰好在两次探测之间释放，立即重试获取
+                continue;
+            }
+            throw err;
+        }
+        if (lockAgeMs > REGISTRY_LOCK_STALE_MS) {
+            // 原子抢占：rename 到含进程号与时间戳的隔离名，仅一个进程能成功；
+            // 失败方说明已被其他等待者抢先处理，回到等待重试即可
+            const quarantine = `${lockDir}.stale.${process.pid}.${Date.now()}`;
+            try {
+                await rename(lockDir, quarantine);
+                await rm(quarantine, { recursive: true, force: true });
+                continue;
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    // 其他等待者已抢先回收该残留锁
+                    continue;
+                }
+                // 其他原因的 rename 失败（如瞬时权限问题）不视为致命，退回等待重试
+            }
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`Failed to acquire registry lock '${lockDir}' within ${REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS}ms. ` +
+                `The lock may be held by another ActionDock process; retry after it exits or remove the stale lock directory manually.`);
+        }
+        await sleep(REGISTRY_LOCK_RETRY_DELAY_MS);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await rm(lockDir, { recursive: true, force: true });
+        }
+        catch {
+            // 释放失败可忽略：进程未清理的锁目录会随时间超过 stale 阈值，
+            // 被后续获取方的原子 rename 抢占回收，不会造成永久死锁
+        }
+    }
+}

package/dist/registry/registry.d.ts

@@ -0,0 +1,45 @@
+import type { GlobalRegistryData, LinkedPackageEntry, LinkedWorkspaceEntry, LinkResult, PruneResult, RegistryStatusReport, ResolvedActionProject, ResolvedPlaybookProject, UnlinkResult } from "./types.js";
+/**
+ * 注册表内容解析与 links 迁移（纯函数，同步与异步加载共享的唯一事实源）。
+ *
+ * @param raw 文件原始文本
+ * @param filePath 注册表文件路径（用于错误信息定位）
+ * @returns 解析后的注册表数据
+ * @throws JSON 非法或顶层非对象时抛出带恢复指引的错误（调用方负责留档原文件）
+ */
+export declare function parseRegistryContent(raw: string, filePath: string): GlobalRegistryData;
+export declare function getRegistryFilePath(customHome?: string): string;
+/**
+ * 同步加载注册表（保留同步签名供 CLI 与诊断路径使用）。
+ *
+ * @throws 注册表文件损坏时抛出带恢复指引的错误，绝不静默返回空表，
+ * 否则下次 save 会用空数据覆盖原文件导致全部链接记录丢失
+ */
+export declare function loadRegistry(customHome?: string): GlobalRegistryData;
+/**
+ * 异步加载注册表（损坏语义与同步版一致：留档后抛错，不静默清空）。
+ */
+export declare function loadRegistryAsync(customHome?: string): Promise<GlobalRegistryData>;
+/**
+ * 原子写入注册表：临时文件写盘后 rename，持锁执行，避免并发撕裂。
+ */
+export declare function saveRegistry(data: GlobalRegistryData, customHome?: string): Promise<void>;
+/**
+ * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用，
+ * 避免与 saveRegistry 的锁重入死等）；调用方必须已持有对应锁。
+ */
+export declare function writeRegistryLocked(data: GlobalRegistryData, customHome?: string): Promise<void>;
+export declare function linkPackage(targetPath?: string, customHome?: string, options?: {
+    recursive?: boolean;
+}): Promise<LinkResult>;
+export declare function unlinkPackage(identifier?: string, customHome?: string): Promise<UnlinkResult | null>;
+export declare function listLinkedPackages(customHome?: string): LinkedPackageEntry[];
+export declare function listLinkedPackagesAsync(customHome?: string): Promise<LinkedPackageEntry[]>;
+export declare function listLinkedWorkspaces(customHome?: string): LinkedWorkspaceEntry[];
+export declare function resolveActionProjectSync(actionIdentifier: string, cwd?: string, customHome?: string): ResolvedActionProject;
+export declare function resolveActionProject(actionIdentifier: string, cwd?: string, customHome?: string): Promise<ResolvedActionProject>;
+export declare function resolvePlaybookProject(playbookIdentifier: string, cwd?: string, customHome?: string): ResolvedPlaybookProject;
+export declare function resolvePackageRoot(packageIdOrPath?: string, cwd?: string, customHome?: string): string | null;
+export declare function getRegistryStatus(customHome?: string): RegistryStatusReport;
+export declare function pruneRegistry(customHome?: string): Promise<PruneResult>;
+export { discoverProjects, IGNORED_SCAN_DIRS } from "./scan.js";