@actiondock/core 2.0.12 → 2.2.1

package/dist/storage/driver.d.ts

@@ -1,15 +1,9 @@
-import type { SqliteDriver } from "./types";
+import { normalizeSqliteParams } from "./params.js";
+import type { SqliteDriver } from "./types.js";
 export type SqliteDriverFactory = (dbPath: string) => SqliteDriver;
-/**
- * 获取当前注册的全局默认 SQLite 驱动工厂。
- */
-export declare function getSqliteDriverFactory(): SqliteDriverFactory | undefined;
-/**
- * 注册全局默认 SQLite 驱动工厂。
- */
-export declare function setSqliteDriverFactory(factory: SqliteDriverFactory): void;
+export { normalizeSqliteParams };
 /**
  * 创建默认 SQLite 驱动实例。
- * 优先使用外部注册的工厂，其次根据当前运行时环境自动适配。
+ * 基于 Node.js 原生 node:sqlite (DatabaseSync) 驱动实现，严格同步契约。
  */
 export declare function createDefaultSqliteDriver(dbPath: string): SqliteDriver;

package/dist/storage/driver.js

@@ -0,0 +1,59 @@
+import { createRequire } from "node:module";
+import { normalizeSqliteParams } from "./params.js";
+export { normalizeSqliteParams };
+/** ESM 环境下可用的 CommonJS require，用于动态加载 node:sqlite */
+const cjsRequire = createRequire(import.meta.url);
+/**
+ * 创建默认 SQLite 驱动实例。
+ * 基于 Node.js 原生 node:sqlite (DatabaseSync) 驱动实现，严格同步契约。
+ */
+export function createDefaultSqliteDriver(dbPath) {
+    try {
+        const { DatabaseSync } = cjsRequire("node:sqlite");
+        const db = new DatabaseSync(dbPath);
+        return {
+            exec(sql) {
+                db.exec(sql);
+            },
+            prepare(sql) {
+                const stmt = db.prepare(sql);
+                return {
+                    run(...args) {
+                        const params = normalizeSqliteParams(args);
+                        const res = stmt.run(...params);
+                        return { changes: res.changes, lastInsertRowid: res.lastInsertRowid };
+                    },
+                    get(...args) {
+                        const params = normalizeSqliteParams(args);
+                        return stmt.get(...params);
+                    },
+                    all(...args) {
+                        const params = normalizeSqliteParams(args);
+                        return stmt.all(...params);
+                    },
+                };
+            },
+            transaction(fn) {
+                db.exec("BEGIN");
+                try {
+                    const res = fn();
+                    if (res !== null && (typeof res === "object" || typeof res === "function") && typeof res.then === "function") {
+                        throw new Error("Async transactions are not allowed in SQLite");
+                    }
+                    db.exec("COMMIT");
+                    return res;
+                }
+                catch (e) {
+                    db.exec("ROLLBACK");
+                    throw e;
+                }
+            },
+            close() {
+                db.close();
+            },
+        };
+    }
+    catch (err) {
+        throw new Error(`Failed to initialize SQLite driver: ${err?.message || String(err)}`);
+    }
+}

package/dist/storage/index.d.ts

@@ -1,16 +1,18 @@
-import type { RuntimeStorage } from "./types";
-export * from "./driver";
-export * from "./mask";
-export * from "./sqlite";
-export * from "./types";
+import type { RuntimeStorage } from "./types.js";
+export { DataDirLock, type DataDirLockInfo, isProcessAlive, } from "./data-dir-lock.js";
+export * from "./driver.js";
+export * from "./lazy.js";
+export * from "./mask.js";
+export * from "./params.js";
+export * from "./sqlite.js";
+export * from "./types.js";
 /**
  * 解析并计算目标 SQLite 数据库文件的绝对路径。
  *
  * 优先级规则：
- * 1. inMemory: true -> 返回 ":memory:"
- * 2. 显式指定 dataDir -> 返回 `<dataDir>/<packageId>/runtime.db`
- * 3. 显式指定 projectRoot（开发态项目） -> 返回 `<projectRoot>/.actiondock/runtime.db`
- * 4. 默认独立二进制存储路径 -> 返回 `~/.actiondock/data/<packageId>/runtime.db`
+ * - inMemory: true -> 返回 ":memory:"
+ * - 显式指定 dataDir -> 返回 `<dataDir>/<packageId>/runtime.db`
+ * - 默认统一数据存储路径 -> 返回 `~/.actiondock/data/<packageId>/runtime.db`
  *
  * @param packageId 所属 Package ID
  * @param options 路径解析选项
@@ -19,18 +21,35 @@ export declare function resolveDatabasePath(packageId: string, options?: {
     projectRoot?: string;
     dataDir?: string;
     inMemory?: boolean;
+    customHome?: string;
 }): string;
 /**
  * 工厂函数：为指定 Package 创建或连接 RuntimeStorage 实例。
  *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 projectRoot, dataDir, inMemory）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome）
  */
 export declare function createStorage(packageId: string, options?: {
     projectRoot?: string;
     dataDir?: string;
     inMemory?: boolean;
+    customHome?: string;
 }): RuntimeStorage;
+/**
+ * 解析全局共享数据库（global.db）文件的绝对路径。
+ *
+ * 单一事实源：core 与各运行时平台适配层（如 runtime-node）
+ * 统一调用本函数计算 global.db 路径，禁止在适配层内重复拼接过
+ * 路径规则，避免双实现漂移。
+ *
+ * 优先级规则：
+ * - 显式指定 dataDir -> 返回 `<dataDir>/global.db`
+ * - 默认路径 -> 返回 `~/.actiondock/global.db`
+ */
+export declare function resolveGlobalDatabasePath(options?: {
+    dataDir?: string;
+    customHome?: string;
+}): string;
 /**
  * 工厂函数：创建或连接 ActionDock 全局共享数据库（~/.actiondock/global.db）。
  * 用于跨 Package 共享的全局配置项存储。
@@ -41,4 +60,5 @@ export declare function createStorage(packageId: string, options?: {
 export declare function createGlobalStorage(customHomeOrOptions?: string | {
     customHome?: string;
     dataDir?: string;
+    inMemory?: boolean;
 }, dataDirArg?: string): RuntimeStorage;

package/dist/storage/index.js

@@ -0,0 +1,98 @@
+import { join, relative, resolve } from "node:path";
+import { assertValidPackageId, getActionDockHome, isPathOutsideBoundary } from "../utils/index.js";
+import { SqliteRuntimeStorage } from "./sqlite.js";
+export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
+export * from "./driver.js";
+export * from "./lazy.js";
+export * from "./mask.js";
+export * from "./params.js";
+export * from "./sqlite.js";
+export * from "./types.js";
+/**
+ * 解析并计算目标 SQLite 数据库文件的绝对路径。
+ *
+ * 优先级规则：
+ * - inMemory: true -> 返回 ":memory:"
+ * - 显式指定 dataDir -> 返回 `<dataDir>/<packageId>/runtime.db`
+ * - 默认统一数据存储路径 -> 返回 `~/.actiondock/data/<packageId>/runtime.db`
+ *
+ * @param packageId 所属 Package ID
+ * @param options 路径解析选项
+ */
+export function resolveDatabasePath(packageId, options = {}) {
+    if (options.inMemory) {
+        return ":memory:";
+    }
+    assertValidPackageId(packageId);
+    // 安全子路径（支持 @scope/pkg 规范，拒绝非法字符与相对回退）
+    const safePkgPath = packageId.startsWith("@") ? packageId.slice(1) : packageId;
+    if (options.dataDir) {
+        const rootDir = resolve(options.dataDir);
+        const dbPath = resolve(rootDir, safePkgPath, "runtime.db");
+        const rel = relative(rootDir, dbPath);
+        if (isPathOutsideBoundary(rel)) {
+            throw new Error(`'database dataDir path' escapes boundary '${rootDir}': ${dbPath}`);
+        }
+        return dbPath;
+    }
+    // 统一数据存储路径: ~/.actiondock/data/<package-id>/runtime.db
+    const rootDir = resolve(join(getActionDockHome(options.customHome), ".actiondock", "data"));
+    const dbPath = resolve(rootDir, safePkgPath, "runtime.db");
+    const rel = relative(rootDir, dbPath);
+    if (isPathOutsideBoundary(rel)) {
+        throw new Error(`'database storage path' escapes boundary '${rootDir}': ${dbPath}`);
+    }
+    return dbPath;
+}
+/**
+ * 工厂函数：为指定 Package 创建或连接 RuntimeStorage 实例。
+ *
+ * @param packageId 目标 Package ID
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome）
+ */
+export function createStorage(packageId, options = {}) {
+    const dbPath = resolveDatabasePath(packageId, options);
+    return new SqliteRuntimeStorage({ dbPath, packageId });
+}
+/**
+ * 解析全局共享数据库（global.db）文件的绝对路径。
+ *
+ * 单一事实源：core 与各运行时平台适配层（如 runtime-node）
+ * 统一调用本函数计算 global.db 路径，禁止在适配层内重复拼接过
+ * 路径规则，避免双实现漂移。
+ *
+ * 优先级规则：
+ * - 显式指定 dataDir -> 返回 `<dataDir>/global.db`
+ * - 默认路径 -> 返回 `~/.actiondock/global.db`
+ */
+export function resolveGlobalDatabasePath(options = {}) {
+    return options.dataDir
+        ? join(options.dataDir, "global.db")
+        : join(getActionDockHome(options.customHome), ".actiondock", "global.db");
+}
+/**
+ * 工厂函数：创建或连接 ActionDock 全局共享数据库（~/.actiondock/global.db）。
+ * 用于跨 Package 共享的全局配置项存储。
+ *
+ * @param customHomeOrOptions 自定义家目录路径或配置对象（可选）
+ * @param dataDirArg 自定义数据存储目录（可选）
+ */
+export function createGlobalStorage(customHomeOrOptions, dataDirArg) {
+    let customHome;
+    let dataDir;
+    let inMemory = false;
+    if (typeof customHomeOrOptions === "object" && customHomeOrOptions !== null) {
+        customHome = customHomeOrOptions.customHome;
+        dataDir = customHomeOrOptions.dataDir;
+        inMemory = Boolean(customHomeOrOptions.inMemory);
+    }
+    else {
+        customHome = customHomeOrOptions;
+        dataDir = dataDirArg;
+    }
+    if (inMemory) {
+        return new SqliteRuntimeStorage({ dbPath: ":memory:", packageId: "__global__" });
+    }
+    const dbPath = resolveGlobalDatabasePath({ dataDir, customHome });
+    return new SqliteRuntimeStorage({ dbPath, packageId: "__global__" });
+}

package/dist/storage/lazy.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeStorage } from "./types.js";
+/**
+ * 创建延迟初始化的运行时存储代理对象。
+ * 只有在首次调用存储的方法或属性时，才会调用底层工厂函数建立真实连接。
+ *
+ * @param factory 底层存储实例工厂函数
+ */
+export declare function createLazyStorage(factory: () => RuntimeStorage): RuntimeStorage;

package/dist/storage/lazy.js

@@ -0,0 +1,44 @@
+/**
+ * 创建延迟初始化的运行时存储代理对象。
+ * 只有在首次调用存储的方法或属性时，才会调用底层工厂函数建立真实连接。
+ *
+ * @param factory 底层存储实例工厂函数
+ */
+export function createLazyStorage(factory) {
+    let instance;
+    function getInstance() {
+        if (!instance) {
+            instance = factory();
+        }
+        return instance;
+    }
+    return new Proxy({}, {
+        get(_target, prop, receiver) {
+            if (prop === "closed") {
+                return instance ? instance.closed : false;
+            }
+            if (prop === "isOpen") {
+                return instance ? instance.isOpen : false;
+            }
+            if (prop === "close") {
+                return () => {
+                    if (instance) {
+                        instance.close();
+                    }
+                };
+            }
+            if (prop === "__isLazyProxy") {
+                return true;
+            }
+            if (prop === "__getUnderlyingInstance") {
+                return getInstance;
+            }
+            const target = getInstance();
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value === "function") {
+                return value.bind(target);
+            }
+            return value;
+        },
+    });
+}

package/dist/storage/mask.d.ts

@@ -1,15 +1,15 @@
-import type { ConfigItemDefinition } from "../project/types";
+import type { ConfigItemDefinition } from "../project/types.js";
 /**
  * 检查指定配置项是否为敏感数据（密码、私钥、Token、密钥等）。
  *
  * 判定逻辑：
- * 1. 若 actiondock.json 中显式声明了 `secret: true`，直接判定为敏感。
- * 2. 若未显式声明，使用正则探测包含 PASSWORD/SECRET/TOKEN/KEY/PASS/AUTH/CREDENTIAL/PRIVATE_KEY 的通用敏感命名特征。
+ * 严格依据配置项元数据属性判定：若声明了 `secret: true`，直接判定为敏感数据；否则不视为敏感数据。
+ * 不进行基于正则或键名的自动探测，由开发者显式配置驱动。
  *
- * @param key 配置键名
+ * @param _key 配置键名（保留入参以兼容契约）
  * @param declaredItem 项目中声明的配置元数据（可选）
  */
-export declare function isSecretConfigKey(key: string, declaredItem?: ConfigItemDefinition): boolean;
+export declare function isSecretConfigKey(_key?: string, declaredItem?: ConfigItemDefinition): boolean;
 /**
  * 对敏感数据的值进行掩码脱敏处理（返回 "********"）。
  *
@@ -17,3 +17,10 @@ export declare function isSecretConfigKey(key: string, declaredItem?: ConfigItem
  * @returns 掩码脱敏后的安全展示字符串
  */
 export declare function maskSecretValue(value: unknown): string;
+/**
+ * 对配置定义字典进行脱敏处理：
+ * 针对声明为 secret: true 的项，剥离其 default 默认值，不返回敏感默认值。
+ *
+ * @param config 声明的配置定义字典
+ */
+export declare function sanitizeConfigDefinitions(config?: Record<string, ConfigItemDefinition>): Record<string, ConfigItemDefinition> | undefined;

package/dist/storage/mask.js

@@ -0,0 +1,48 @@
+/**
+ * 检查指定配置项是否为敏感数据（密码、私钥、Token、密钥等）。
+ *
+ * 判定逻辑：
+ * 严格依据配置项元数据属性判定：若声明了 `secret: true`，直接判定为敏感数据；否则不视为敏感数据。
+ * 不进行基于正则或键名的自动探测，由开发者显式配置驱动。
+ *
+ * @param _key 配置键名（保留入参以兼容契约）
+ * @param declaredItem 项目中声明的配置元数据（可选）
+ */
+export function isSecretConfigKey(_key, declaredItem) {
+    return declaredItem?.secret === true;
+}
+/**
+ * 对敏感数据的值进行掩码脱敏处理（返回 "********"）。
+ *
+ * @param value 原始数据值
+ * @returns 掩码脱敏后的安全展示字符串
+ */
+export function maskSecretValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    return "********";
+}
+/**
+ * 对配置定义字典进行脱敏处理：
+ * 针对声明为 secret: true 的项，剥离其 default 默认值，不返回敏感默认值。
+ *
+ * @param config 声明的配置定义字典
+ */
+export function sanitizeConfigDefinitions(config) {
+    if (!config)
+        return config;
+    const result = {};
+    for (const [key, item] of Object.entries(config)) {
+        if (item?.secret === true) {
+            const copy = { ...item };
+            delete copy.default;
+            result[key] = copy;
+        }
+        else {
+            result[key] = item;
+        }
+    }
+    return result;
+}

package/dist/storage/params.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SQLite 绑定参数规范化共享纯函数。
+ *
+ * 单一事实源：主线程驱动（core 默认驱动与 runtime-node 的 NodeSqliteDriver）
+ * 与 WorkerSqliteDriver 的 worker 内联脚本均使用本模块生成的同一份实现。
+ *
+ * 工程说明：worker 内联脚本以字符串形式 eval 执行、无法直接 import 模块，
+ * 因此 worker 侧通过 Function.prototype.toString 将本函数源码序列化注入脚本。
+ * 该函数必须保持完全自包含：仅依赖运行时全局 Buffer 与 Uint8Array，
+ * 不得引用任何模块作用域内的其他标识符，也不得引入会被打包器改写的外部闭包，
+ * 否则序列化注入后将在 worker 作用域内产生未定义引用。
+ */
+export declare function normalizeSqliteParams(args: any[]): any[];

package/dist/storage/params.js

@@ -0,0 +1,32 @@
+/**
+ * SQLite 绑定参数规范化共享纯函数。
+ *
+ * 单一事实源：主线程驱动（core 默认驱动与 runtime-node 的 NodeSqliteDriver）
+ * 与 WorkerSqliteDriver 的 worker 内联脚本均使用本模块生成的同一份实现。
+ *
+ * 工程说明：worker 内联脚本以字符串形式 eval 执行、无法直接 import 模块，
+ * 因此 worker 侧通过 Function.prototype.toString 将本函数源码序列化注入脚本。
+ * 该函数必须保持完全自包含：仅依赖运行时全局 Buffer 与 Uint8Array，
+ * 不得引用任何模块作用域内的其他标识符，也不得引入会被打包器改写的外部闭包，
+ * 否则序列化注入后将在 worker 作用域内产生未定义引用。
+ */
+export function normalizeSqliteParams(args) {
+    if (!args || args.length === 0) {
+        return [];
+    }
+    if (args.length === 1 && Array.isArray(args[0])) {
+        return args[0].map((v) => (v === undefined ? null : v));
+    }
+    if (args.length === 1 &&
+        typeof args[0] === "object" &&
+        args[0] !== null &&
+        !Buffer.isBuffer(args[0]) &&
+        !(args[0] instanceof Uint8Array)) {
+        const cleaned = {};
+        for (const entry of Object.entries(args[0])) {
+            cleaned[entry[0]] = entry[1] === undefined ? null : entry[1];
+        }
+        return [cleaned];
+    }
+    return args.map((v) => (v === undefined ? null : v));
+}

package/dist/storage/sqlite.d.ts

@@ -1,9 +1,9 @@
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, type RuntimeError, type RunRecord } from "@actiondock/sdk";
-import type { RuntimeStorage, StateEntry, StorageOptions, TerminalRunStatus } from "./types";
+import { type IdempotencyCheckResult, type IdempotencyRecord, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 /**
  * 统一 SQLite 运行时存储实现。
- * 通过 SqliteDriver 抽象驱动，解耦底层具体运行时引擎（Node.js / Bun）。
+ * 通过 SqliteDriver 抽象驱动，解耦底层具体运行时引擎。
  */
 export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private driver;
@@ -11,17 +11,28 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private clock;
     private isClosed;
     private statementCache;
+    private dbPath;
     get isOpen(): boolean;
     get closed(): boolean;
     constructor(options: StorageOptions);
     /**
-     * 初始化数据库结构并执行无损版本升级。
+     * 初始化数据库结构并执行严格版本校验。
+     *
+     * 规则：
+     * - 空数据目录首次初始化在单个事务中完成完整 Schema 构建。
+     * - 若创建事务失败则拒绝启动且不留下残缺表。
+     * - 打开旧版本或不兼容版本的数据库时，在写事务前直接抛出 UNSUPPORTED_STORAGE_SCHEMA 异常并拒绝启动。
      */
     private init;
     /**
-     * 重启恢复：将未正常结算的 running 状态自动收敛为 interrupted
+     * 重启恢复：将未正常结算的非终态（running/pending）记录自动收敛为 interrupted。
+     * 若指定了当前新 Host 会话标识，将收敛不属于该会话（包括旧会话或空会话）的死亡任务。
      */
-    recoverRunningRuns(): number;
+    recoverRunningRuns(currentHostSessionId?: string): number;
+    /**
+     * 收敛死亡会话遗留的非终态运行任务。
+     */
+    recoverDeadSessionRuns(currentHostSessionId?: string): number;
     /**
      * 获取或复用预编译 SQL 语句缓存。
      */
@@ -61,6 +72,8 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
         actionId?: string;
         status?: string;
     }): number;
+    checkAndRecordIdempotency(record: IdempotencyRecord): IdempotencyCheckResult;
+    getIdempotencyRecord(ownerId: string, actionRef: string, requestId: string): IdempotencyRecord | undefined;
     private mapRunRecord;
-    close(): void;
+    close(): Promise<void>;
 }