@actiondock/core 2.19.0 → 2.21.0

package/dist/invocation/types.js

@@ -31,9 +31,12 @@ export function createInvocationContext(options) {
         parentRunId: options.parentRunId,
         caller: options.caller,
         callStack: options.callStack ? [...options.callStack] : [],
+        targetScope: options.targetScope,
         package: pkg,
         signal: options.signal ?? new AbortController().signal,
         timeoutMs: options.timeoutMs,
+        initialTimeoutMs: options.initialTimeoutMs,
+        deadline: options.deadline,
         config: options.config,
         requestId: options.requestId,
         tenantId: options.tenantId,
@@ -63,11 +66,16 @@ export function createInvocationContext(options) {
  * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
  */
 export function createRootInvocationContext(options) {
+    const initialTimeoutMs = options.initialTimeoutMs ?? (typeof options.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : undefined);
+    const deadline = options.deadline ?? (initialTimeoutMs !== undefined ? Date.now() + initialTimeoutMs : undefined);
+    const remainingBudget = deadline !== undefined ? Math.max(0, deadline - Date.now()) : options.timeoutMs;
     const base = createInvocationContext({
         package: options.targetPackage,
         callStack: options.callStack,
         signal: options.signal,
-        timeoutMs: options.timeoutMs,
+        timeoutMs: remainingBudget,
+        initialTimeoutMs,
+        deadline,
         config: options.config,
         requestId: options.requestId,
         hostSessionId: options.hostSessionId,
@@ -89,6 +97,8 @@ export function createRootInvocationContext(options) {
         package: base.package,
         signal: base.signal,
         timeoutMs: base.timeoutMs,
+        initialTimeoutMs: base.initialTimeoutMs,
+        deadline: base.deadline,
         config: base.config,
         requestId: base.requestId,
         hostSessionId: base.hostSessionId,

package/dist/package/index.d.ts

@@ -10,7 +10,7 @@ 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, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
+export type { RuntimePlatform, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, InvocationTargetResolution, InvocationCallerInfo, InvocationTargetResolver, } from "../platform/types.js";
 export { type Clock, SystemClock, } from "../storage/clock.js";
 export type { ModuleLoader } from "../platform/module-loader.js";
 export { InMemoryEventSink, type EventSink, } from "../runtime/events.js";
@@ -19,4 +19,4 @@ export type { ProcessAPI as ProcessExecutor } from "@actiondock/sdk";
 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";
+export type { RuntimeStorage, SqliteDriver, StateEntry, ConfigWriteOptions, ConfigSnapshot, } from "../storage/types.js";

package/dist/package/runtime.js

@@ -5,7 +5,9 @@ import { createNodePlatform } from "../platform/index.js";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { RuntimeConfig } from "../runtime/context.js";
 import { normalizeActionCollection } from "../runtime/action-collection.js";
-import { isSecretConfigKey, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { redactConfigValue, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { redactConfigValueWithProtection } from "../storage/index.js";
+import { assertConcreteConfigKey, assertValidConfigDeclarations, isConfigTemplate, resolveConfigDeclaration, validateConfigValue, } from "../project/config-declarations.js";
 import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
 import { createPackageIdentity } from "../runtime/identity.js";
 import { ACTION_NOT_FOUND, ActionDockError, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, INVOCATION_UNSUPPORTED, NOT_FOUND, SERVICE_CLOSED, } from "../errors.js";
@@ -127,6 +129,9 @@ export class DefaultPackageRuntime {
             };
         }
         this.packageRoot = packageRoot;
+        if (projectConfig.config !== undefined) {
+            assertValidConfigDeclarations(projectConfig.config);
+        }
         this.projectConfig = projectConfig;
         // 兼容未在公开选项契约中显式声明的包实例标识与代系标识内部参数透传
         this.identity = options.identity || createPackageIdentity({
@@ -235,6 +240,7 @@ export class DefaultPackageRuntime {
     }
     /** 构造包存储工厂选项（单一事实源，异步与同步打开路径共用） */
     buildStorageOptions() {
+        const config = this.projectConfig?.config;
         return {
             projectRoot: this.packageRoot,
             dataDir: this.options.dataDir,
@@ -243,6 +249,9 @@ export class DefaultPackageRuntime {
             // 默认持有者语义：App 主路径打开时收割死亡会话遗留非终态运行记录；
             // CLI 查询旁观视图显式置 recoverOrphans: false 跳过收割
             recoverOrphans: this.options.recoverOrphans !== false,
+            // 供旧版本库自动迁移判定敏感性（各字典内具体键优先于模板）；
+            // 仅在库需要迁移时被读取，不引入新的生命周期
+            ...(config && Object.keys(config).length > 0 ? { configDeclarations: [config] } : {}),
         };
     }
     /**
@@ -296,12 +305,15 @@ export class DefaultPackageRuntime {
             this.globalStorageRes = { kind: "own", storage };
             return storage;
         }
+        const config = this.projectConfig?.config;
         const globalOpts = {
             customHome: this.options.customHome,
             dataDir: this.options.dataDir,
             inMemory: this.options.inMemory,
             // 与主存储保持同侧收割语义（全局库 runs 表为空集，收割无实际副作用）
             recoverOrphans: this.options.recoverOrphans !== false,
+            // 独立全局库迁移以当前包声明为并集口径；Host 共享路径由 Host 汇集全部已加载包声明
+            ...(config && Object.keys(config).length > 0 ? { configDeclarations: [config] } : {}),
         };
         const storage = this.platform.storage.createGlobalStorage(globalOpts);
         this.globalStorageRes = { kind: "own", storage };
@@ -679,9 +691,18 @@ export class DefaultPackageRuntime {
     }
     async listConfig() {
         this.assertOpen();
-        const declared = this.projectConfig.config || {};
-        const stored = (await this.prepareStorageAsync()).listConfig();
-        const allKeys = Array.from(new Set([...Object.keys(declared), ...Object.keys(stored)]));
+        const packageStorage = await this.prepareStorageAsync();
+        const globalStorage = await this.ensureGlobalStorage();
+        const declaredKeys = Object.keys(this.projectConfig.config || {}).filter((k) => !isConfigTemplate(k));
+        const packageStoredKeys = Object.keys(packageStorage.listConfig());
+        const globalStoredKeys = Object.keys(globalStorage.listConfig());
+        const overrideKeys = Object.keys(this.options.configOverrides || {});
+        const allKeys = Array.from(new Set([
+            ...declaredKeys,
+            ...packageStoredKeys,
+            ...globalStoredKeys,
+            ...overrideKeys,
+        ])).filter((k) => !isConfigTemplate(k));
         const views = [];
         for (const key of allKeys) {
             const item = await this.getConfig(key);
@@ -693,27 +714,39 @@ export class DefaultPackageRuntime {
     }
     async getConfig(key) {
         this.assertOpen();
-        const itemDef = this.projectConfig.config?.[key];
-        const isSecret = isSecretConfigKey(key, itemDef);
-        // 委托 RuntimeConfig 五层优先级链单一事实源，避免重复实现解析链
-        const resolved = this.ensureRuntimeConfig().describe(key);
-        // overrides 来源对外统一星现为包级覆盖视角
-        const source = resolved.source === "overrides" ? "package" : resolved.source;
-        const configured = resolved.source !== "default";
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
+        // 委托 RuntimeConfig 五层优先级链单一事实源，取值与历史保护声明同链原子解析
+        const resolved = this.ensureRuntimeConfig().describeWithProtection(key);
+        // configured 显式判定：仅真实显式来源（override/package/global/env）为 true，
+        // default 与整链未命中（source null）均为 false，不得依赖与 "default" 的不等比较
+        const configured = resolved.source !== null && resolved.source !== "default";
+        // 当前声明与存储持久化的历史保护声明合并脱敏：删除或弱化声明后仍保持既有保护；
+        // 无历史保护时沿用单声明脱敏原语，保持既有视图行为不变
+        const redacted = resolved.protection !== undefined
+            ? redactConfigValueWithProtection(resolved.value, decl?.item ? [decl.item] : [], resolved.protection)
+            : redactConfigValue(resolved.value, decl?.item);
         return {
             key,
             configured,
-            secret: isSecret,
-            source,
-            value: isSecret ? undefined : resolved.value,
+            secret: redacted.secret,
+            source: resolved.source,
+            value: redacted.value,
+            redactedPaths: redacted.redactedPaths,
         };
     }
     async setConfig(key, value) {
         this.assertOpen();
-        await (await this.prepareStorageAsync()).setConfig(key, value);
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
+        validateConfigValue(key, value, decl?.item);
+        // 传递当前有效声明（具体键优先于模板解析结果），
+        // 由存储统一判定整键加密并合并历史保护，禁止保护弱化
+        await (await this.prepareStorageAsync()).setConfig(key, value, decl?.item ? { declarations: [decl.item] } : undefined);
     }
     async deleteConfig(key) {
         this.assertOpen();
+        assertConcreteConfigKey(key);
         return await (await this.prepareStorageAsync()).deleteConfig(key);
     }
     /**

package/dist/platform/node.d.ts

@@ -4,6 +4,7 @@ import { type ModuleLoader } from "./module-loader.js";
 import { ProcessManager } from "../process/process-manager.js";
 import type { ProcessDriver } from "../process/driver.js";
 import { type SqliteDriver } from "../storage/index.js";
+import type { ConfigKeyProvider } from "../security/config-cipher.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform, StorageFactory } from "./types.js";
 /**
@@ -35,6 +36,11 @@ export interface NodePlatformOptions {
     clock?: Clock;
     /** 自定义存储工厂（默认基于 NodeSqliteDriver 构造） */
     storage?: StorageFactory;
+    /**
+     * 显式注入的配置加密密钥提供器：优先于由有效 customHome/dataDir 派生的默认提供器，
+     * 显式注入时对内存库同样生效（供测试注入固定密钥）。
+     */
+    configKeyProvider?: ConfigKeyProvider;
     /** 可选注入的执行事件接收器 */
     eventSink?: EventSink;
     /** 可选注入的统一日志记录器 */

package/dist/platform/node.js

@@ -7,6 +7,7 @@ import { NodeProcessDriver } from "../process/process-driver.js";
 import { ProcessManager } from "../process/process-manager.js";
 import { NodeSqliteDriver } from "../storage/sqlite-driver.js";
 import { resolveDatabasePath, resolveGlobalDatabasePath, SqliteRuntimeStorage, } from "../storage/index.js";
+import { createConfigKeyProvider } from "../security/config-key.js";
 function ensureDirectoryForDb(dbPath) {
     if (dbPath !== ":memory:") {
         const dir = dirname(dbPath);
@@ -72,43 +73,85 @@ export function createNodePlatform(options = {}) {
         return cachedModules;
     };
     const createDriver = options.driverFactory ?? ((dbPath) => new NodeSqliteDriver(dbPath));
+    // - 配置加密密钥提供器按每次建库时的有效路径派生：密钥必须与数据库共享同一
+    //   dataDir/customHome 域，禁止密钥落真实 home 而数据库在别处（或反向）。
+    //   提供器懒加载：仅构造平台或读取普通配置不创建 keys 目录；
+    //   内存库不注入派生提供器，由存储使用随机内存密钥，即使环境提供密钥也不触真实密钥源；
+    //   显式注入的测试提供器对内存库保留生效。
+    const resolveConfigKeyProvider = (dbPath, effectiveCustomHome, effectiveDataDir) => {
+        if (options.configKeyProvider) {
+            return options.configKeyProvider;
+        }
+        if (dbPath === ":memory:") {
+            return undefined;
+        }
+        return createConfigKeyProvider({
+            customHome: effectiveCustomHome,
+            dataDir: effectiveDataDir,
+        });
+    };
+    // - 自建驱动构造失败时释放句柄：SqliteRuntimeStorage 将注入 driver 视为外部资源，
+    //   构造抛出不会代为关闭，此处回收驱动，避免锁泄漏后原样透传错误
+    const createStorageWithDriverCleanup = (build, dbPath) => {
+        const driver = createDriver(dbPath);
+        try {
+            return build(driver);
+        }
+        catch (err) {
+            try {
+                driver.close();
+            }
+            catch {
+                // 忽略清理阶段副异常，确保原始错误优先透传
+            }
+            throw err;
+        }
+    };
     const storage = options.storage ?? {
         createStorage(packageId, opts) {
+            // 显式 opts 中的 undefined 不得覆盖平台级路径：密钥与数据库必须解析同一有效路径
+            const effectiveCustomHome = opts?.customHome ?? options.customHome;
+            const effectiveDataDir = opts?.dataDir ?? options.dataDir;
             const mergedOpts = {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
+                customHome: effectiveCustomHome,
+                dataDir: effectiveDataDir,
+                inMemory: opts?.inMemory,
+                projectRoot: opts?.projectRoot,
             };
             const dbPath = resolveDatabasePath(packageId, mergedOpts);
             ensureDirectoryForDb(dbPath);
-            return new SqliteRuntimeStorage({
+            const configKeyProvider = resolveConfigKeyProvider(dbPath, effectiveCustomHome, effectiveDataDir);
+            return createStorageWithDriverCleanup((driver) => new SqliteRuntimeStorage({
                 dbPath,
                 packageId,
                 clock,
-                driver: createDriver(dbPath),
+                driver,
                 recoverOrphans: opts?.recoverOrphans === true,
                 retentionPolicy: opts?.retentionPolicy,
                 logger: options.logger,
-            });
+                ...(configKeyProvider ? { configKeyProvider } : {}),
+                ...(opts?.configDeclarations?.length ? { configDeclarations: opts.configDeclarations } : {}),
+            }), dbPath);
         },
         createGlobalStorage(opts) {
-            const mergedOpts = {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
-            };
-            const dbPath = mergedOpts.inMemory
+            const effectiveCustomHome = opts?.customHome ?? options.customHome;
+            const effectiveDataDir = opts?.dataDir ?? options.dataDir;
+            const inMemory = Boolean(opts?.inMemory);
+            const dbPath = inMemory
                 ? ":memory:"
-                : resolveGlobalDatabasePath({ dataDir: mergedOpts.dataDir, customHome: mergedOpts.customHome });
+                : resolveGlobalDatabasePath({ dataDir: effectiveDataDir, customHome: effectiveCustomHome });
             ensureDirectoryForDb(dbPath);
-            return new SqliteRuntimeStorage({
+            const configKeyProvider = resolveConfigKeyProvider(dbPath, effectiveCustomHome, effectiveDataDir);
+            return createStorageWithDriverCleanup((driver) => new SqliteRuntimeStorage({
                 dbPath,
                 packageId: "__global__",
                 clock,
-                driver: createDriver(dbPath),
+                driver,
                 recoverOrphans: opts?.recoverOrphans === true,
                 logger: options.logger,
-            });
+                ...(configKeyProvider ? { configKeyProvider } : {}),
+                ...(opts?.configDeclarations?.length ? { configDeclarations: opts.configDeclarations } : {}),
+            }), dbPath);
         },
     };
     const platform = {

package/dist/platform/types.d.ts

@@ -1,8 +1,10 @@
-import type { ProcessAPI } from "@actiondock/sdk";
+import type { ActionInvokeOptions, ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../storage/clock.js";
 import type { ModuleLoader } from "./module-loader.js";
 import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 import type { EventSink } from "../runtime/events.js";
+import type { PackageRuntime } from "../package/types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
 /**
  * 跨运行时持久化存储工厂配置选项。
  */
@@ -18,6 +20,11 @@ export interface StorageFactoryOptions {
     recoverOrphans?: boolean;
     /** 运行记录保留策略配置 */
     retentionPolicy?: RunsRetentionPolicy;
+    /**
+     * 供旧版本数据库迁移判定的配置声明字典集合（包级存储传当前包声明）。
+     * 仅在库需要迁移时被读取；版本迁移只在首次打开执行。
+     */
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }
 /**
  * 跨运行时全局存储工厂配置选项。
@@ -28,6 +35,11 @@ export interface GlobalStorageFactoryOptions {
     customHome?: string;
     /** 是否以持有者身份打开并收割遗留非终态运行记录（默认 false，旁观语义） */
     recoverOrphans?: boolean;
+    /**
+     * 供旧版本全局库迁移判定的配置声明字典集合（通常为所有已加载包的声明并集）。
+     * 仅在库需要迁移时被读取；版本迁移只在首次打开执行。
+     */
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }
 /**
  * 跨运行时持久化存储工厂契约。
@@ -42,6 +54,48 @@ export interface StorageFactory {
      */
     createGlobalStorage(options?: GlobalStorageFactoryOptions): RuntimeStorage;
 }
+/**
+ * 动作调用目标解析结果。
+ */
+export interface InvocationTargetResolution {
+    /** 目标 PackageRuntime 实例 */
+    readonly runtime: PackageRuntime;
+    /** 可选调用作用域，用于区分调用目标与环路死锁检测身份 */
+    readonly scope?: string;
+    /** 是否强制要求调用方显式声明 uses 依赖 */
+    readonly requiresExplicitUses?: boolean;
+}
+/**
+ * 动作调用发起方元数据信息。
+ */
+export interface InvocationCallerInfo {
+    /** 调用发起方包标识 */
+    readonly packageId: string;
+    /** 调用发起方 Action 动作标识 */
+    readonly actionId?: string;
+}
+/**
+ * 运行时平台调用目标解析器端口契约。
+ * 允许底层运行时平台在 Host 选择执行目标阶段介入目标解析，提供自定义 PackageRuntime。
+ */
+export interface InvocationTargetResolver {
+    /**
+     * 解析指定 Action 引用与调用选项对应的目标 PackageRuntime。
+     *
+     * @param action 规范化 Action 引用元数据
+     * @param options 动作调用选项（包含命名 binding 等）
+     * @param caller 发起调用的调用方元数据
+     * @returns 目标解析结果；返回的 Runtime 由 Host 接管生命周期；未命中返回 undefined 交由默认主链处理
+     */
+    resolve(action: {
+        packageId: string;
+        actionId: string;
+    }, options: ActionInvokeOptions | undefined, caller: InvocationCallerInfo): InvocationTargetResolution | undefined;
+    /**
+     * 清理端口缓存和附属资源，不重复关闭已移交 Host 的 Runtime。
+     */
+    close?(): Promise<void>;
+}
 /**
  * 运行时底层环境核心标准契约。
  * 提供统一的运行时契约，屏蔽宿主平台与测试沙箱环境的实现差异。
@@ -61,4 +115,8 @@ export interface RuntimePlatform {
      * 可选执行事件接收器，宿主可注入，缺省由上层默认构造。
      */
     readonly eventSink?: EventSink;
+    /**
+     * 可选动作调用目标解析器端口，用于宿主环境自定义动作调用路由（例如测试具名 Mock 模拟目标）。
+     */
+    readonly invocationTargets?: InvocationTargetResolver;
 }

package/dist/process/command-executor.d.ts

@@ -0,0 +1,35 @@
+import type { ProcessDriver } from "./driver.js";
+/**
+ * 工程工具命令执行配置选项。
+ */
+export interface ExecuteCommandOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    onOutput?: (stream: "stdout" | "stderr", text: string) => void;
+    driver?: ProcessDriver;
+}
+/**
+ * 工程工具命令执行结果。
+ */
+export interface CommandExecutionResult {
+    status: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}
+/**
+ * 面向工程工具的一次性命令适配执行器。
+ *
+ * 核心设计契约：
+ * - 复用底层 ProcessDriver 平台驱动，严格保持进程组隔离与进程树收敛能力；
+ * - 绝不启用系统 Shell，参数列表原样透传，杜绝命令注入与参数转义漏洞；
+ * - 默认每流上限 512KiB 字节有界捕获，超出上限继续排空或转发并置 truncated 标志；
+ * - 捕获字节独立深拷贝，脱离原始底层缓冲区以防内存滞留与复用篡改；
+ * - 仅当显式指定 onOutput 时流式转发，严格保证跨分块 UTF-8 字符解码完整性；
+ * - 规范化取消、超时与异常收敛：等待 driver.terminate 与 outputClosed 终态后抛出结构化 ProcessError。
+ */
+export declare function executeCommand(executable: string, args: readonly string[], options?: ExecuteCommandOptions): Promise<CommandExecutionResult>;