@actiondock/core 2.7.0 → 2.8.0

package/dist/node/module-loader.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 统一源码模块加载器接口。
+ * 解耦 Action 与各类扩展模块的具体加载机制（如 ECMAScript 原生 import、tsx 动态转译加载等）。
+ */
+export interface ModuleLoader {
+    /**
+     * 解析模块标识符为绝对路径或完整 URL。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve?(specifier: string, parentPath?: string): string;
+    /**
+     * 动态加载模块并返回命名空间全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    load<T = any>(specifier: string, parentPath?: string): Promise<T>;
+    /**
+     * 加载模块并解包其默认导出（default 或 action 属性）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    loadDefault?<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}
+/**
+ * 解包模块的默认导出对象，优先获取 default 或 action，自动解开嵌套互操作对象。
+ *
+ * @param moduleExports 待解包的模块导出对象
+ */
+export declare function unwrapDefaultExport<T = any>(moduleExports: any): T;
+/**
+ * 基于 Node.js 原生 ESM 动态 import 的源码模块加载器。
+ * 遵循 Node 原生模块规范：
+ * - 严格要求显式入口扩展名（.ts, .mts, .js, .mjs）
+ * - 彻底拒绝无扩展名自动推断与 CommonJS 目录索引解析
+ * - 完全移除第三方转译运行时依赖
+ */
+export declare class NodeModuleLoader implements ModuleLoader {
+    /**
+     * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
+     *
+     * @param specifier 模块规范说明符或相对/绝对物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve(specifier: string, parentPath?: string): string;
+    /**
+     * 基于 Node 原生 ESM 动态 import 加载模块并返回其全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    load<T = any>(specifier: string, parentPath?: string): Promise<T>;
+    /**
+     * 加载模块并解包其默认导出（default 或 action）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    loadDefault<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}

package/dist/node/module-loader.js

@@ -0,0 +1,112 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ActionDockError, ACTION_LOAD_FAILED } from "../errors.js";
+/**
+ * Node 原生 TypeScript 与 ESM 模块支持的扩展名集合。
+ */
+const ALLOWED_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+/**
+ * 解包模块的默认导出对象，优先获取 default 或 action，自动解开嵌套互操作对象。
+ *
+ * @param moduleExports 待解包的模块导出对象
+ */
+export function unwrapDefaultExport(moduleExports) {
+    if (moduleExports === null || moduleExports === undefined) {
+        return moduleExports;
+    }
+    let target = moduleExports.default !== undefined
+        ? moduleExports.default
+        : moduleExports.action !== undefined
+            ? moduleExports.action
+            : moduleExports;
+    if (target &&
+        typeof target === "object" &&
+        "default" in target &&
+        Object.keys(target).length === 1) {
+        target = target.default;
+    }
+    return target;
+}
+/**
+ * 基于 Node.js 原生 ESM 动态 import 的源码模块加载器。
+ * 遵循 Node 原生模块规范：
+ * - 严格要求显式入口扩展名（.ts, .mts, .js, .mjs）
+ * - 彻底拒绝无扩展名自动推断与 CommonJS 目录索引解析
+ * - 完全移除第三方转译运行时依赖
+ */
+export class NodeModuleLoader {
+    /**
+     * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
+     *
+     * @param specifier 模块规范说明符或相对/绝对物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve(specifier, parentPath) {
+        let target = specifier;
+        if (target.startsWith("file://")) {
+            target = fileURLToPath(target);
+        }
+        let baseDir = process.cwd();
+        if (parentPath) {
+            try {
+                const p = parentPath.startsWith("file://")
+                    ? fileURLToPath(parentPath)
+                    : parentPath;
+                if (existsSync(p)) {
+                    const stat = statSync(p);
+                    baseDir = stat.isDirectory() ? resolve(p) : dirname(resolve(p));
+                }
+                else {
+                    baseDir = dirname(resolve(p));
+                }
+            }
+            catch {
+                baseDir = process.cwd();
+            }
+        }
+        const candidateBasePath = isAbsolute(target) ? target : resolve(baseDir, target);
+        const ext = extname(candidateBasePath);
+        if (!ext) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': missing file extension. Explicit .ts, .mts, .js, or .mjs extension is required.`);
+        }
+        if (!ALLOWED_EXTENSIONS.has(ext)) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': unsupported extension '${ext}'. Only .ts, .mts, .js, and .mjs are supported.`);
+        }
+        if (!existsSync(candidateBasePath)) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': file not found`);
+        }
+        let stat;
+        try {
+            stat = statSync(candidateBasePath);
+        }
+        catch (err) {
+            throw new ActionDockError(ACTION_LOAD_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': ${err.message}`);
+        }
+        if (!stat.isFile()) {
+            throw new ActionDockError(ACTION_LOAD_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': path is not a file`);
+        }
+        return candidateBasePath;
+    }
+    /**
+     * 基于 Node 原生 ESM 动态 import 加载模块并返回其全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    async load(specifier, parentPath) {
+        const resolvedPath = this.resolve(specifier, parentPath);
+        const fileUrl = pathToFileURL(resolvedPath).href;
+        return (await import(fileUrl));
+    }
+    /**
+     * 加载模块并解包其默认导出（default 或 action）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    async loadDefault(specifier, parentPath) {
+        const mod = await this.load(specifier, parentPath);
+        return unwrapDefaultExport(mod);
+    }
+}

package/dist/package/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ActionDock 包级运行时必要门面与契约。
+ *
+ * 遵循 Minimal 暴露准则：仅对外输出 PackageRuntime、PackageRuntimeOptions、
+ * createPackageRuntime 以及包与动作元数据契约（PackageInfo、ActionSpec、ActionSummary、
+ * PlaybookSpec、PlaybookSummary）。
+ * 底层存储驱动、独立分发器与平台大对象统一由核心根入口导出。
+ */
+export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
+export { createNonClosingStorageView } from "./storage-view.js";
+export { findExecutable } from "../utils/index.js";
+export type { PackageRuntime, PackageRuntimeOptions, PackageInfo, ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, } from "./types.js";
+export type { RuntimePlatform, FileSystem, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
+export { type Clock, SystemClock, } from "../runtime/clock.js";
+export type { ModuleLoader } from "../node/module-loader.js";
+export { InMemoryEventSink, type EventSink, } from "../runtime/events.js";
+export { ProcessManager, type ProcessOwner, } from "../process/process-manager.js";
+export type { ProcessExecutor } from "../runtime/process.js";
+export { NodeProcessExecutor } from "../process/process-executor.js";
+export type { ProcessDriver, ProcessDriverCallbacks, ProcessDriverHandle, ProcessHandle, ProcessObserver, } from "../process/driver.js";
+export { createStorage, resolveDatabasePath, } from "../storage/index.js";
+export { SqliteRuntimeStorage } from "../storage/sqlite.js";
+export type { RuntimeStorage, SqliteDriver, StateEntry, } from "../storage/types.js";

package/dist/package/index.js

@@ -0,0 +1,18 @@
+/**
+ * ActionDock 包级运行时必要门面与契约。
+ *
+ * 遵循 Minimal 暴露准则：仅对外输出 PackageRuntime、PackageRuntimeOptions、
+ * createPackageRuntime 以及包与动作元数据契约（PackageInfo、ActionSpec、ActionSummary、
+ * PlaybookSpec、PlaybookSummary）。
+ * 底层存储驱动、独立分发器与平台大对象统一由核心根入口导出。
+ */
+export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
+export { createNonClosingStorageView } from "./storage-view.js";
+export { findExecutable } from "../utils/index.js";
+export { SystemClock, } from "../runtime/clock.js";
+export { InMemoryEventSink, } from "../runtime/events.js";
+export { ProcessManager, } from "../process/process-manager.js";
+export { NodeProcessExecutor } from "../process/process-executor.js";
+// 存储契约与驱动
+export { createStorage, resolveDatabasePath, } from "../storage/index.js";
+export { SqliteRuntimeStorage } from "../storage/sqlite.js";

package/dist/{app/app.d.ts → package/runtime.d.ts}

@@ -1,31 +1,33 @@
-import type { ActionDefinition, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
-import type { CancelResult, ExecuteOptions, ExecutionService, ExecutionTicket } from "../execution/types.js";
-import { type RuntimePlatform } from "../platform/index.js";
+import type { ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionInvoker, CancelResult, ExecutionTicket } from "../execution/types.js";
 import type { ProjectConfig } from "../project/types.js";
-import type { RuntimeStorage } from "../storage/types.js";
-import type { ActionDockApp, ActionDockAppOptions, ActionSpec, ActionSummary, ConfigValueView, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary, StateScopeOptions } from "./types.js";
+import { type PackageIdentity } from "../runtime/identity.js";
+import { type InvocationContext, type RunOptions } from "../invocation/types.js";
+import type { ActionSpec, ActionSummary, ConfigValueView, HostManagedPackageRuntime, ListActionsOptions, ListRunsOptions, PackageInfo, PackageRuntime, PackageRuntimeOptions, PackageRuntimeInternalOptions, PlaybookSpec, PlaybookSummary, StateScopeOptions } from "./types.js";
 /**
- * ActionDock 统一应用默认实现。
+ * ActionDock 统一包运行时默认实现。
  * 封装并管理单个 Action Package 的执行引擎、静态元数据索引、配置与状态存储生命周期。
  */
-export declare class DefaultActionDockApp implements ActionDockApp {
+export declare class DefaultPackageRuntime implements HostManagedPackageRuntime {
+    readonly identity: PackageIdentity;
     readonly packageId: string;
     readonly packageInstanceId: string;
     readonly generationId: string;
     readonly packageRoot?: string;
     readonly projectConfig: ProjectConfig;
-    readonly platform: RuntimePlatform;
-    readonly storage: RuntimeStorage;
-    readonly globalStorage?: RuntimeStorage;
-    readonly executionService: ExecutionService;
-    readonly actionsMap: Map<string, ActionDefinition>;
+    private readonly platform;
+    private readonly storage;
+    private readonly globalStorage?;
+    private readonly executionService;
+    private readonly actionsMap;
     private readonly options;
     private runtimeConfig;
     private isClosed;
+    private injectedGlobalStorage;
     /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
     private staticActionIndex?;
     private staticPlaybookIndex?;
-    constructor(options?: ActionDockAppOptions);
+    constructor(options?: PackageRuntimeInternalOptions);
     /**
      * 静态读取并聚合当前包的 Action 规范索引。
      * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果，
@@ -44,8 +46,10 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     describeAction(id: string): Promise<ActionSpec>;
     listPlaybooks(): Promise<PlaybookSummary[]>;
     describePlaybook(id: string): Promise<PlaybookSpec>;
-    runAction(id: string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
-    startAction(id: string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    private buildRootInvocationContext;
+    runAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
+    startAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
+    startInvocation(actionId: string, input: JsonValue, context: InvocationContext): Promise<ExecutionTicket>;
     getRun(runId: string): Promise<RunRecord | undefined>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
@@ -53,6 +57,8 @@ export declare class DefaultActionDockApp implements ActionDockApp {
         signal?: AbortSignal;
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
+    setActionInvoker(invoker?: ActionInvoker): void;
+    recoverDeadSessionRuns(sessionId?: string): void;
     listConfig(): Promise<ConfigValueView[]>;
     getConfig(key: string): Promise<ConfigValueView>;
     setConfig(key: string, value: JsonValue): Promise<void>;
@@ -60,11 +66,20 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     /**
      * 状态作用域统一解析辅助函数（单一事实源）。
      *
-     * 完成重载消歧与 actionId 冲突校验，返回最终生效的命名空间：
-     * - actionId 存在时拼 接 `${actionId}:${namespace}` 或直接 actionId；
-     * - 无 actionId 时返回显式 namespace 或空字符串（包级扁平状态）。
+     * 完成重载消歧后委托 mergeStateScope 计算最终生效的命名空间：
+     * - (actionId, key, options) 形态：位置 actionId 参与冲突校验；
+     * - (key, options) 扁平形态：首参是状态键，options.actionId 属合法显式指定。
      */
     private resolveStateScope;
+    /**
+     * 合并位置 actionId 与 options.actionId 并计算最终命名空间（单一事实源）。
+     *
+     * - positionalActionId 非 undefined：调用形态携带位置 actionId，
+     *   options.actionId 与其冲突时抛出异常（空串同样参与冲突校验）；
+     * - positionalActionId 为 undefined：无位置 actionId 的扁平调用形态，
+     *   options.actionId 属合法显式指定，直接采纳。
+     */
+    private mergeStateScope;
     getState<T extends JsonValue = JsonValue>(key: string, options?: StateScopeOptions): Promise<T | undefined>;
     getState<T extends JsonValue = JsonValue>(actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
     setState<T extends JsonValue = JsonValue>(key: string, value: T, options?: StateScopeOptions): Promise<void>;
@@ -78,11 +93,17 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     listStateKeys(actionId: string, options?: StateScopeOptions): Promise<string[]>;
     clearState(options?: StateScopeOptions): Promise<number>;
     clearState(actionId: string, options?: StateScopeOptions): Promise<number>;
+    listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    clearRuns(options?: {
+        actionId?: string;
+        status?: string;
+    }): Promise<number>;
+    listStateEntries(options?: any): Promise<import("../storage/types.js").StateEntry[]>;
     close(options?: {
         graceMs?: number;
     }): Promise<void>;
 }
 /**
- * 工厂函数：创建并初始化 ActionDockApp 实例。
+ * 工厂函数：创建并初始化 PackageRuntime 实例。
  */
-export declare function createActionDockApp(options?: ActionDockAppOptions): Promise<ActionDockApp>;
+export declare function createPackageRuntime(options?: PackageRuntimeOptions): Promise<PackageRuntime>;