@actiondock/core 2.0.11 → 2.2.0

package/dist/project/digest.js

@@ -0,0 +1,324 @@
+import { createHash } from "node:crypto";
+/**
+ * 解析 JSON 文本并在检测到重复键时抛出错误。
+ * 遵循 RFC 8785 清单校验规范：解析阶段必须率先拦截并拒绝重复键。
+ */
+export function parseJsonWithoutDuplicates(jsonText) {
+    let pos = 0;
+    const len = jsonText.length;
+    function skipWhitespace() {
+        while (pos < len) {
+            const ch = jsonText.charCodeAt(pos);
+            if (ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d) {
+                pos++;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    function parseString() {
+        if (jsonText[pos] !== '"') {
+            throw new SyntaxError(`Expected string at position ${pos}`);
+        }
+        const start = pos;
+        pos++; // 跳过开头的引号
+        let result = "";
+        while (pos < len) {
+            const ch = jsonText[pos];
+            if (ch === '"') {
+                pos++; // 跳过结束的引号
+                return result;
+            }
+            if (ch === "\\") {
+                pos++;
+                if (pos >= len) {
+                    throw new SyntaxError(`Unterminated escape sequence in string at ${pos}`);
+                }
+                const esc = jsonText[pos];
+                if (esc === '"' || esc === "\\" || esc === "/") {
+                    result += esc;
+                    pos++;
+                }
+                else if (esc === "b") {
+                    result += "\b";
+                    pos++;
+                }
+                else if (esc === "f") {
+                    result += "\f";
+                    pos++;
+                }
+                else if (esc === "n") {
+                    result += "\n";
+                    pos++;
+                }
+                else if (esc === "r") {
+                    result += "\r";
+                    pos++;
+                }
+                else if (esc === "t") {
+                    result += "\t";
+                    pos++;
+                }
+                else if (esc === "u") {
+                    pos++;
+                    const hex = jsonText.slice(pos, pos + 4);
+                    if (hex.length < 4 || !/^[0-9a-fA-F]{4}$/.test(hex)) {
+                        throw new SyntaxError(`Invalid unicode escape sequence \\u${hex} at ${pos}`);
+                    }
+                    result += String.fromCharCode(parseInt(hex, 16));
+                    pos += 4;
+                }
+                else {
+                    throw new SyntaxError(`Invalid escape character '\\${esc}' at ${pos}`);
+                }
+            }
+            else {
+                result += ch;
+                pos++;
+            }
+        }
+        throw new SyntaxError(`Unterminated string starting at ${start}`);
+    }
+    function parseNumber() {
+        const start = pos;
+        if (jsonText[pos] === "-") {
+            pos++;
+        }
+        if (pos >= len) {
+            throw new SyntaxError(`Expected digits at position ${pos}`);
+        }
+        if (jsonText[pos] === "0") {
+            pos++;
+        }
+        else if (jsonText[pos] >= "1" && jsonText[pos] <= "9") {
+            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
+                pos++;
+            }
+        }
+        else {
+            throw new SyntaxError(`Invalid number at position ${pos}`);
+        }
+        if (pos < len && jsonText[pos] === ".") {
+            pos++;
+            if (pos >= len || jsonText[pos] < "0" || jsonText[pos] > "9") {
+                throw new SyntaxError(`Expected digit after decimal point at position ${pos}`);
+            }
+            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
+                pos++;
+            }
+        }
+        if (pos < len && (jsonText[pos] === "e" || jsonText[pos] === "E")) {
+            pos++;
+            if (pos < len && (jsonText[pos] === "+" || jsonText[pos] === "-")) {
+                pos++;
+            }
+            if (pos >= len || jsonText[pos] < "0" || jsonText[pos] > "9") {
+                throw new SyntaxError(`Expected digit after exponent at position ${pos}`);
+            }
+            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
+                pos++;
+            }
+        }
+        const numStr = jsonText.slice(start, pos);
+        const num = Number(numStr);
+        if (!Number.isFinite(num)) {
+            throw new SyntaxError(`Number out of range: ${numStr}`);
+        }
+        return num;
+    }
+    function parseObject() {
+        const obj = {};
+        const keys = new Set();
+        pos++; // 跳过 '{'
+        skipWhitespace();
+        if (pos < len && jsonText[pos] === "}") {
+            pos++;
+            return obj;
+        }
+        while (pos < len) {
+            skipWhitespace();
+            if (jsonText[pos] !== '"') {
+                throw new SyntaxError(`Expected string key in object at position ${pos}`);
+            }
+            const key = parseString();
+            if (keys.has(key)) {
+                throw new Error(`Duplicate key '${key}' detected in JSON`);
+            }
+            keys.add(key);
+            skipWhitespace();
+            if (pos >= len || jsonText[pos] !== ":") {
+                throw new SyntaxError(`Expected ':' after key '${key}' at position ${pos}`);
+            }
+            pos++; // 跳过 ':'
+            skipWhitespace();
+            const val = parseValue();
+            obj[key] = val;
+            skipWhitespace();
+            if (pos >= len) {
+                throw new SyntaxError("Unexpected end of JSON in object");
+            }
+            if (jsonText[pos] === ",") {
+                pos++;
+                skipWhitespace();
+            }
+            else if (jsonText[pos] === "}") {
+                pos++;
+                return obj;
+            }
+            else {
+                throw new SyntaxError(`Expected ',' or '}' in object at position ${pos}`);
+            }
+        }
+        throw new SyntaxError("Unterminated object in JSON");
+    }
+    function parseArray() {
+        const arr = [];
+        pos++; // 跳过 '['
+        skipWhitespace();
+        if (pos < len && jsonText[pos] === "]") {
+            pos++;
+            return arr;
+        }
+        while (pos < len) {
+            skipWhitespace();
+            const val = parseValue();
+            arr.push(val);
+            skipWhitespace();
+            if (pos >= len) {
+                throw new SyntaxError("Unexpected end of JSON in array");
+            }
+            if (jsonText[pos] === ",") {
+                pos++;
+                skipWhitespace();
+            }
+            else if (jsonText[pos] === "]") {
+                pos++;
+                return arr;
+            }
+            else {
+                throw new SyntaxError(`Expected ',' or ']' in array at position ${pos}`);
+            }
+        }
+        throw new SyntaxError("Unterminated array in JSON");
+    }
+    function parseValue() {
+        skipWhitespace();
+        if (pos >= len) {
+            throw new SyntaxError("Unexpected end of JSON input");
+        }
+        const ch = jsonText[pos];
+        if (ch === "{")
+            return parseObject();
+        if (ch === "[")
+            return parseArray();
+        if (ch === '"')
+            return parseString();
+        if (ch === "-" || (ch >= "0" && ch <= "9"))
+            return parseNumber();
+        if (jsonText.startsWith("true", pos)) {
+            pos += 4;
+            return true;
+        }
+        if (jsonText.startsWith("false", pos)) {
+            pos += 5;
+            return false;
+        }
+        if (jsonText.startsWith("null", pos)) {
+            pos += 4;
+            return null;
+        }
+        throw new SyntaxError(`Unexpected token '${ch}' at position ${pos}`);
+    }
+    const result = parseValue();
+    skipWhitespace();
+    if (pos < len) {
+        throw new SyntaxError(`Unexpected trailing characters at position ${pos}`);
+    }
+    return result;
+}
+/**
+ * 依据 RFC 8785 规范化 JSON 数据。
+ * 规则：
+ * - 对象属性依据 UTF-16 代码单元进行升序排序；
+ * - 符号与键值之间不包含多余空白字符；
+ * - 浮点数与整数遵循 ECMAScript 规范序列化（负零转为零，拒绝非有限数）；
+ * - 字符串转义严格遵循标准规范；
+ * - 数组保持原有顺序且元素递归规范化。
+ */
+export function canonicalizeJson(value) {
+    if (value === null) {
+        return "null";
+    }
+    const type = typeof value;
+    if (type === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (type === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError("RFC 8785 JSON 规范化拒绝非有限数值 (NaN 或 Infinity)");
+        }
+        if (Object.is(value, -0) || value === 0) {
+            return "0";
+        }
+        return JSON.stringify(value);
+    }
+    if (type === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        const items = value.map((item) => {
+            if (item === undefined || typeof item === "function" || typeof item === "symbol") {
+                return "null";
+            }
+            return canonicalizeJson(item);
+        });
+        return `[${items.join(",")}]`;
+    }
+    if (type === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const entries = [];
+        for (const key of keys) {
+            const val = obj[key];
+            if (val === undefined || typeof val === "function" || typeof val === "symbol") {
+                continue;
+            }
+            entries.push(`${JSON.stringify(key)}:${canonicalizeJson(val)}`);
+        }
+        return `{${entries.join(",")}}`;
+    }
+    return "null";
+}
+/**
+ * 计算任意 JSON 结构或 JSON 字符串的 SHA-256 规范化摘要。
+ * 输出格式为 sha256-<hex>。
+ */
+export function computeDigest(value) {
+    let canonicalText;
+    if (typeof value === "string") {
+        const parsed = parseJsonWithoutDuplicates(value);
+        canonicalText = canonicalizeJson(parsed);
+    }
+    else {
+        canonicalText = canonicalizeJson(value);
+    }
+    const hash = createHash("sha256").update(canonicalText, "utf8").digest("hex");
+    return `sha256-${hash}`;
+}
+/**
+ * 计算 Action 清单对象的唯一确定性 RFC 8785 摘要。
+ * 清单中的等价空格变化与字段顺序不会改变摘要结果。
+ */
+export function computeManifestDigest(manifest) {
+    return computeDigest(manifest);
+}
+/**
+ * 校验给定清单的摘要是否与期望值一致。
+ */
+export function verifyManifestDigest(manifest, expectedDigest) {
+    if (!expectedDigest || typeof expectedDigest !== "string") {
+        return false;
+    }
+    return computeManifestDigest(manifest) === expectedDigest;
+}

package/dist/project/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./closure.js";
+export * from "./digest.js";
+export * from "./init.js";
+export * from "./loader.js";
+export * from "./lockfile.js";
+export * from "./manifest.js";
+export * from "./resolver.js";
+export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isPidAlive, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
+export * from "./types.js";
+export * from "./types-generator.js";

package/dist/project/index.js

@@ -0,0 +1,10 @@
+export * from "./closure.js";
+export * from "./digest.js";
+export * from "./init.js";
+export * from "./loader.js";
+export * from "./lockfile.js";
+export * from "./manifest.js";
+export * from "./resolver.js";
+export { SNAPSHOT_TRACKED_FILES, isPidAlive, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
+export * from "./types.js";
+export * from "./types-generator.js";

package/dist/project/init.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 项目初始化脚手架选项。
+ */
+export interface InitOptions {
+    /** 自定义项目 ID（默认使用目录名） */
+    id?: string;
+    /** 自定义项目展示名称（默认由目录名美化生成） */
+    name?: string;
+    /** 自定义项目描述 */
+    description?: string;
+}
+/**
+ * 在目标目录初始化一个完整的 ActionDock 2.0 Action Package 脚手架。
+ * 生成内容包括：
+ * - actiondock.json（项目元数据、Action 与 Playbook 声明的单一事实源）
+ * - package.json（Node.js 标准脚本与依赖声明）
+ * - tsconfig.json（现代 NodeNext 模块规范）
+ * - .gitignore（排除持久化 db、node_modules、dist）
+ * - actions/greet.ts（标准示例 Action 执行 Handler，演示 config、state、log 使用）
+ * - playbooks/greet-user.md（纯 Markdown 标准 SOP Playbook 演示）
+ * - tests/greet.test.ts（基于 node:test 与 @actiondock/testing 的测试用例）
+ *
+ * @param targetDir 目标项目目录
+ * @param options 初始化选项
+ */
+export declare function initProject(targetDir: string, options?: InitOptions): void;

package/dist/project/init.js

@@ -0,0 +1,175 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+/**
+ * 在目标目录初始化一个完整的 ActionDock 2.0 Action Package 脚手架。
+ * 生成内容包括：
+ * - actiondock.json（项目元数据、Action 与 Playbook 声明的单一事实源）
+ * - package.json（Node.js 标准脚本与依赖声明）
+ * - tsconfig.json（现代 NodeNext 模块规范）
+ * - .gitignore（排除持久化 db、node_modules、dist）
+ * - actions/greet.ts（标准示例 Action 执行 Handler，演示 config、state、log 使用）
+ * - playbooks/greet-user.md（纯 Markdown 标准 SOP Playbook 演示）
+ * - tests/greet.test.ts（基于 node:test 与 @actiondock/testing 的测试用例）
+ *
+ * @param targetDir 目标项目目录
+ * @param options 初始化选项
+ */
+export function initProject(targetDir, options = {}) {
+    const root = resolve(targetDir);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    const dirName = basename(root);
+    const id = options.id || dirName;
+    const name = options.name || dirName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    const description = options.description || "ActionDock AI Agent Actions";
+    // 1. actiondock.json（单一事实源）
+    const actiondockJson = {
+        $schema: "https://actiondock.dev/schema/v2.json",
+        schemaVersion: 2,
+        id,
+        name,
+        version: "0.1.0",
+        description,
+        config: {
+            SAMPLE_GREETING: {
+                description: "Default greeting message",
+                default: "Hello",
+            },
+        },
+        actions: {
+            "sample.greet": {
+                entry: "actions/greet.ts",
+                description: "Greeting action demonstrating basic input, config, and state usage",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "Name of the person to greet",
+                        },
+                    },
+                    required: ["name"],
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        message: { type: "string" },
+                        timesGreeted: { type: "number" },
+                    },
+                    required: ["message", "timesGreeted"],
+                },
+                tags: ["sample"],
+                uses: [],
+            },
+        },
+        playbooks: {
+            "greet-user": {
+                entry: "playbooks/greet-user.md",
+                description: "SOP for greeting a new user and verifying system health",
+                actions: ["sample.greet"],
+            },
+        },
+        files: [],
+    };
+    writeFileSync(join(root, "actiondock.json"), JSON.stringify(actiondockJson, null, 2) + "\n");
+    // 2. package.json
+    const packageJson = {
+        name: id,
+        version: "0.1.0",
+        description,
+        type: "module",
+        scripts: {
+            test: "node --import tsx --test tests/*.test.ts",
+        },
+        engines: {
+            node: ">=24.12.0",
+        },
+        dependencies: {
+            "@actiondock/sdk": "^2.2.0",
+        },
+        devDependencies: {
+            "@actiondock/testing": "^2.2.0",
+            "@types/node": "^22.13.0",
+            "tsx": "^4.19.0",
+            "typescript": "^5.7.0",
+        },
+    };
+    writeFileSync(join(root, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
+    // 3. tsconfig.json
+    const tsconfigJson = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            skipLibCheck: true,
+            types: ["node"],
+        },
+    };
+    writeFileSync(join(root, "tsconfig.json"), JSON.stringify(tsconfigJson, null, 2) + "\n");
+    // 4. .gitignore
+    const gitignore = `.actiondock/
+node_modules/
+dist/
+build/
+*.log
+.env
+`;
+    writeFileSync(join(root, ".gitignore"), gitignore);
+    // 5. actions/
+    const actionsDir = join(root, "actions");
+    mkdirSync(actionsDir, { recursive: true });
+    const sampleAction = `import { defineAction } from "@actiondock/sdk";
+
+// 说明：若 Action 需导入包内其他源码目录（如 src/、lib/ 或辅助工具模块），
+// 请务必在 actiondock.json 的 "files" 字段中声明对应目录以确保构建与导出完整。
+export default defineAction(async (input: { name: string }, ctx) => {
+  const greeting = ctx.config.get("SAMPLE_GREETING", "Hello");
+  const count = ((await ctx.state.get<number>("greet_count")) || 0) + 1;
+  await ctx.state.set("greet_count", count);
+
+  ctx.log.info(\`Greeting \${input.name} (times greeted: \${count})\`);
+
+  return {
+    message: \`\${greeting}, \${input.name}!\`,
+    timesGreeted: count,
+  };
+});
+`;
+    writeFileSync(join(actionsDir, "greet.ts"), sampleAction);
+    // 6. playbooks/
+    const playbooksDir = join(root, "playbooks");
+    mkdirSync(playbooksDir, { recursive: true });
+    const samplePlaybook = `# Greeting SOP
+
+- Call \`sample.greet\` with the user's name.
+- Confirm the returned greeting message.
+`;
+    writeFileSync(join(playbooksDir, "greet-user.md"), samplePlaybook);
+    // 7. tests/
+    const testsDir = join(root, "tests");
+    mkdirSync(testsDir, { recursive: true });
+    const sampleTest = `import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestRuntime } from "@actiondock/testing";
+import greetAction from "../actions/greet.js";
+
+describe("greet action", () => {
+  it("should greet user with greeting and increment count", async () => {
+    const runtime = createTestRuntime({
+      config: { SAMPLE_GREETING: "Hi" },
+    });
+
+    const res1 = await runtime.run(greetAction, { name: "Alice" });
+    assert.equal(res1.message, "Hi, Alice!");
+    assert.equal(await runtime.state.get("greet_count"), 1);
+
+    const res2 = await runtime.run(greetAction, { name: "Bob" });
+    assert.equal(res2.message, "Hi, Bob!");
+    assert.equal(await runtime.state.get("greet_count"), 2);
+  });
+});
+`;
+    writeFileSync(join(testsDir, "greet.test.ts"), sampleTest);
+}

package/dist/project/loader.d.ts

@@ -0,0 +1,99 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import { type ModuleLoader } from "../runtime/module-loader.js";
+import type { ActionDockManifest, PlaybookDefinition, PlaybookManifestEntry, ProjectConfig } from "./types.js";
+/**
+ * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
+ *
+ * @param cwd 起始搜索目录（默认为 process.cwd()）
+ * @returns 项目根目录绝对路径，若未找到则返回 null
+ */
+export declare function findProjectRoot(cwd?: string): string | null;
+/**
+ * 加载并校验指定目录下的 `actiondock.json` 配置文件。
+ *
+ * @param projectRoot 项目根目录绝对路径
+ * @returns 解析后的 ProjectConfig 对象
+ * @throws {Error} 若文件不存在或 JSON 格式错误、缺失必要字段
+ */
+export declare function loadProjectConfig(projectRoot: string): ProjectConfig;
+export declare const ALLOWED_INSTALLERS: Set<string>;
+/**
+ * 探测宿主系统中可用的包管理工具。
+ * 优先级：
+ * - 环境变量 ACTIONDOCK_INSTALLER 显式指定（严格白名单校验：npm, bun）；
+ * - 依据项目根目录下现存的锁文件进行精确匹配（bun.lock/bun.lockb -> bun, package-lock.json/npm-shrinkwrap.json -> npm）；
+ * - 候选回退优先级探测（npm > bun）。
+ */
+export declare function getInstallCommand(projectRoot?: string): string[];
+/**
+ * 读取项目当前缓存的依赖指纹哈希。
+ */
+export declare function readStoredDependencyFingerprint(projectRoot: string): string | null;
+/**
+ * 将最新的依赖指纹哈希写入缓存文件。
+ */
+export declare function saveDependencyFingerprint(projectRoot: string, fingerprint: string): void;
+/**
+ * 计算项目依赖的指纹哈希（基于 package.json 依赖声明及可能存在的锁文件内容）。
+ *
+ * @param projectRoot 项目根目录
+ * @returns 64位十六进制哈希字符串，若 package.json 不存在或解析失败则返回 null
+ */
+export declare function computeDependencyFingerprint(projectRoot: string): string | null;
+/**
+ * 确保项目依赖（node_modules）已正确安装。
+ * 若尚未安装、依赖版本变更（指纹不匹配）或加载失败时，自动触发包管理器执行依赖安装。
+ *
+ * @param projectRoot 项目根目录
+ * @param force 是否强制重新安装
+ * @returns 是否成功执行了安装或更新
+ */
+export declare function ensureProjectDependencies(projectRoot: string, force?: boolean): boolean;
+/**
+ * 发现并检索项目 actions 目录下的所有 Action 源码文件（.ts）。
+ *
+ * @param projectRoot 项目根目录
+ * @param actionsDir actions 子目录名称（默认 "actions"）
+ */
+export declare function discoverActionFiles(projectRoot: string, actionsDir?: string): string[];
+/**
+ * 动态导入并加载项目下的所有 Action 定义对象。
+ * 以 actiondock.json 为唯一事实源读取 Action 的元数据契约（id, description, inputSchema, outputSchema, tags, annotations, uses），
+ * 源码文件仅提供执行 Handler。
+ *
+ * @param projectRoot 项目根目录
+ * @param _actionsDir actions 子目录（向后兼容保留参数）
+ * @param options 模块加载器等选项
+ * @returns Map<ActionId, ActionDefinition> 映射
+ */
+export declare function loadActions(projectRoot: string, _actionsDir?: string, options?: {
+    autoInstall?: boolean;
+    loader?: ModuleLoader;
+}): Promise<Map<string, ActionDefinition>>;
+/**
+ * 发现项目 playbooks 目录下的所有 Playbook Markdown 文档（.md）。
+ */
+export declare function discoverPlaybookFiles(projectRoot: string, playbooksDir?: string): string[];
+/**
+ * 解析单个 Playbook Markdown 文件的内容与元数据。
+ * Playbook 规程正文为纯 Markdown，其元数据（id, description, actions）直接由调用方传入（源自 actiondock.json）。
+ *
+ * @param content 文件 Markdown 文本内容
+ * @param filePath 物理文件路径
+ * @param metadata Playbook 清单元数据
+ * @returns PlaybookDefinition 对象
+ */
+export declare function parsePlaybookContent(content: string, filePath: string, metadata?: Partial<PlaybookManifestEntry> & {
+    id?: string;
+    name?: string;
+}): PlaybookDefinition;
+/**
+ * 加载项目声明的 Playbook SOP 规程文档。
+ * 以 actiondock.json 中的 playbooks 声明作为唯一事实源。
+ *
+ * @param projectRoot 项目根目录
+ * @param _playbooksDir playbooks 子目录（向后兼容保留参数）
+ * @param customManifest 可选的显式清单对象（若未提供则从磁盘加载）
+ * @returns Map<PlaybookId, PlaybookDefinition> 映射
+ */
+export declare function loadPlaybooks(projectRoot: string, _playbooksDir?: string, customManifest?: ActionDockManifest | null): Map<string, PlaybookDefinition>;