@actiondock/core 2.0.12 → 2.2.1

package/dist/runtime/context.js

@@ -0,0 +1,242 @@
+import { randomUUID } from "node:crypto";
+import { resolveEnvValue } from "./env.js";
+import { DefaultProcessExecutor } from "./process.js";
+/**
+ * 生产级配置解析器实现。
+ * 严格践行 5 层配置解析优先级链：
+ * 1. CLI 临时参数覆写 (Overrides)
+ * 2. 包级持久化存储 (Package SQLite: ~/.actiondock/data/<package-id>/runtime.db)
+ * 3. 全局共享持久化存储 (Global SQLite: ~/.actiondock/global.db)
+ * 4. 操作系统环境变量 (process.env: 显式绑定 / 包名前缀 / SNAKE_CASE / 类型转换)
+ * 5. 项目默认配置 (actiondock.json 中的 default 字段)
+ * 6. 代码级默认回退值 (fallback)
+ */
+export class RuntimeConfig {
+    overrides;
+    storage;
+    projectConfig;
+    globalStorage;
+    constructor(storage, overrides = {}, projectConfig, globalStorage) {
+        this.storage = storage;
+        this.overrides = new Map(Object.entries(overrides));
+        this.projectConfig = projectConfig;
+        this.globalStorage = globalStorage;
+    }
+    get(key, defaultValue) {
+        // 1. CLI 临时参数覆盖
+        if (this.overrides.has(key)) {
+            return this.overrides.get(key);
+        }
+        // 2. 本地项目 SQLite 存储
+        const stored = this.storage.getConfig(key);
+        if (stored !== undefined) {
+            return stored;
+        }
+        // 3. 全局 SQLite 存储 (~/.actiondock/global.db)
+        if (this.globalStorage) {
+            try {
+                const globalStored = this.globalStorage.getConfig(key);
+                if (globalStored !== undefined) {
+                    return globalStored;
+                }
+            }
+            catch {
+                // 忽略全局存储读取异常
+            }
+        }
+        // 4. 环境变量（支持包名前缀、SNAKE_CASE 转换与类型自动推断）
+        const itemDef = this.projectConfig?.config?.[key];
+        const envResolved = resolveEnvValue(key, itemDef, this.projectConfig?.id);
+        if (envResolved !== undefined) {
+            return envResolved.value;
+        }
+        // 5. 项目声明的默认值 (actiondock.json)
+        if (itemDef?.default !== undefined) {
+            return itemDef.default;
+        }
+        // 6. 调用方传入的代码级回退默认值
+        return defaultValue;
+    }
+    has(key) {
+        if (this.overrides.has(key))
+            return true;
+        if (this.storage.getConfig(key) !== undefined)
+            return true;
+        if (this.globalStorage?.getConfig(key) !== undefined)
+            return true;
+        const itemDef = this.projectConfig?.config?.[key];
+        if (resolveEnvValue(key, itemDef, this.projectConfig?.id) !== undefined)
+            return true;
+        if (itemDef?.default !== undefined)
+            return true;
+        return false;
+    }
+    /**
+     * 结构化解析指定配置项的来源与取值视图。
+     *
+     * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
+     * 避免重复实现解析链导致行为漂移。
+     */
+    describe(key) {
+        // 1. CLI 临时参数覆写
+        if (this.overrides.has(key)) {
+            return { source: "overrides", value: this.overrides.get(key) };
+        }
+        // 2. 包级持久化存储
+        const stored = this.storage.getConfig(key);
+        if (stored !== undefined) {
+            return { source: "package", value: stored };
+        }
+        // 3. 全局持久化存储
+        if (this.globalStorage) {
+            try {
+                const globalStored = this.globalStorage.getConfig(key);
+                if (globalStored !== undefined) {
+                    return { source: "global", value: globalStored };
+                }
+            }
+            catch {
+                // 忽略全局存储读取异常
+            }
+        }
+        // 4. 环境变量
+        const itemDef = this.projectConfig?.config?.[key];
+        const envResolved = resolveEnvValue(key, itemDef, this.projectConfig?.id);
+        if (envResolved !== undefined) {
+            return { source: "env", value: envResolved.value };
+        }
+        // 5. 项目声明的默认值
+        return { source: "default", value: itemDef?.default };
+    }
+}
+/**
+ * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
+ */
+export class RuntimeStateStore {
+    storage;
+    namespace;
+    constructor(storage, namespace = "") {
+        this.storage = storage;
+        this.namespace = namespace;
+    }
+    async get(key) {
+        if (this.namespace) {
+            return this.storage.getState(this.namespace, key);
+        }
+        const val = await this.storage.getState("", key);
+        if (val !== undefined) {
+            return val;
+        }
+        const found = await this.storage.findState(key);
+        return found?.value;
+    }
+    async set(key, value, ttl) {
+        return this.storage.setState(this.namespace, key, value, ttl);
+    }
+    async delete(key) {
+        return this.storage.deleteState(this.namespace, key);
+    }
+    async clear(prefix = "") {
+        return this.storage.clearState({
+            namespace: this.namespace,
+            prefix: prefix || undefined,
+        });
+    }
+    async keys(prefix = "") {
+        return this.storage.listStateKeys(this.namespace, prefix);
+    }
+    scope(namespace) {
+        const nextNs = this.namespace
+            ? `${this.namespace}:${namespace}`
+            : namespace;
+        return new RuntimeStateStore(this.storage, nextNs);
+    }
+}
+/**
+ * 标准 Stderr 日志记录器实现。
+ * 遵循 Unix 哲学：所有诊断与追踪日志输出至 stderr，确保 stdout 纯净保留 JSON 信封。
+ */
+export class StderrLogger {
+    prefix;
+    constructor(prefix = "") {
+        this.prefix = prefix ? `[${prefix}] ` : "";
+    }
+    format(level, message, data) {
+        const time = new Date().toISOString().slice(11, 19);
+        const base = `[${time}] [${level.toUpperCase()}] ${this.prefix}${message}`;
+        if (data !== undefined) {
+            let formattedData;
+            try {
+                formattedData = typeof data === "object" && data !== null ? JSON.stringify(data) : String(data);
+            }
+            catch {
+                try {
+                    formattedData = String(data);
+                }
+                catch {
+                    formattedData = "[Unserializable Data]";
+                }
+            }
+            return `${base} ${formattedData}`;
+        }
+        return base;
+    }
+    debug(message, data) {
+        process.stderr.write(this.format("debug", message, data) + "\n");
+    }
+    info(message, data) {
+        process.stderr.write(this.format("info", message, data) + "\n");
+    }
+    warn(message, data) {
+        process.stderr.write(this.format("warn", message, data) + "\n");
+    }
+    error(message, data) {
+        process.stderr.write(this.format("error", message, data) + "\n");
+    }
+}
+/**
+ * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。
+ *
+ * @param options 上下文构建参数
+ * @returns 组装完毕的 ActionContext 实例
+ */
+export function createActionContext(options) {
+    const config = new RuntimeConfig(options.storage, options.overrides, options.projectConfig, options.globalStorage);
+    const state = new RuntimeStateStore(options.storage);
+    const log = options.logger || new StderrLogger();
+    const signal = options.signal ?? new AbortController().signal;
+    const currentRunId = options.runId || randomUUID();
+    const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
+    const invoke = async (action, input) => {
+        if (typeof action !== "string" &&
+            (!action || typeof action !== "object" || typeof action.run === "function" || !("actionId" in action))) {
+            const err = new Error("INVALID_ACTION_REF: ctx.actions.invoke strictly accepts only ActionRef or string, passing ActionDefinition or function is prohibited");
+            err.code = "INVALID_ACTION_REF";
+            throw err;
+        }
+        if (options.onActionInvoke) {
+            return (await options.onActionInvoke(action, input, currentRunId));
+        }
+        throw new Error("ActionInvoker not configured with an invocation delegate");
+    };
+    const invokerFn = (ref, input) => invoke(ref, input);
+    const invoker = Object.assign(invokerFn, { invoke });
+    const processApi = options.process || new DefaultProcessExecutor();
+    const progressApi = options.progress || {
+        report() { },
+    };
+    return {
+        config,
+        state,
+        actions: invoker,
+        process: processApi,
+        log,
+        progress: progressApi,
+        signal,
+        run: {
+            id: currentRunId,
+            rootId: currentRootRunId,
+            parentId: options.parentRunId,
+        },
+    };
+}

package/dist/runtime/env.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigItemDefinition, ConfigValueType } from "../project/types";
+import type { ConfigItemDefinition, ConfigValueType } from "../project/types.js";
 /**
  * 从环境变量成功解析后的结构体。
  */
@@ -7,6 +7,8 @@ export interface ResolvedEnv {
     value: unknown;
     /** 命中的具体环境变量键名 */
     envKey: string;
+    /** 命中的具体环境变量键名（别名） */
+    matchedKey: string;
     /** 数据来源标识 */
     source: "env";
 }

package/dist/runtime/env.js

@@ -0,0 +1,159 @@
+import { getPackageSlug } from "../utils/index.js";
+/**
+ * 将任意命名格式的字符串转换为标准的大写蛇形命名（UPPER_SNAKE_CASE）。
+ * 兼容处理 camelCase、kebab-case、点号分隔、斜杠以及 @ 作用域符号。
+ *
+ * @param str 输入字符串，如 "apiKey"、"@team4u/github-tools"
+ * @returns 转换后的字符串，如 "API_KEY"、"TEAM4U_GITHUB_TOOLS"
+ */
+export function toSnakeUpperCase(str) {
+    return str
+        .replace(/^@/, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[-.\s/@]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toUpperCase();
+}
+/**
+ * 当未显式声明类型时，根据默认值的值类型智能推断目标配置类型。
+ *
+ * @param defaultVal 默认值
+ * @returns 推断出的 ConfigValueType 或 undefined
+ */
+export function inferTypeFromDefault(defaultVal) {
+    if (defaultVal === undefined || defaultVal === null)
+        return undefined;
+    if (typeof defaultVal === "boolean")
+        return "boolean";
+    if (typeof defaultVal === "number")
+        return "number";
+    if (Array.isArray(defaultVal))
+        return "array";
+    if (typeof defaultVal === "object")
+        return "object";
+    if (typeof defaultVal === "string")
+        return "string";
+    return undefined;
+}
+/**
+ * 将从 process.env 获取的原始字符串安全转换为目标类型。
+ *
+ * 支持类型：
+ * - boolean: "true"/"1"/"yes"/"on" -> true; "false"/"0"/"no"/"off" -> false
+ * - number: 自动转换为数字，非数字时回退为原始字符串
+ * - object / array: 自动尝试 JSON.parse 反序列化
+ * - 自动探测: 当 targetType 未指定时，自动识别布尔值及 JSON 对象/数组
+ *
+ * @param rawValue process.env 中的原始字符串
+ * @param targetType 期望转换的目标类型
+ */
+export function coerceEnvValue(rawValue, targetType) {
+    if (targetType === "boolean") {
+        const lower = rawValue.trim().toLowerCase();
+        if (["true", "1", "yes", "on"].includes(lower))
+            return true;
+        if (["false", "0", "no", "off"].includes(lower))
+            return false;
+        return Boolean(rawValue);
+    }
+    if (targetType === "number") {
+        const trimmed = rawValue.trim();
+        const num = Number(trimmed);
+        return isNaN(num) ? rawValue : num;
+    }
+    if (targetType === "object" || targetType === "array") {
+        try {
+            return JSON.parse(rawValue);
+        }
+        catch {
+            return rawValue;
+        }
+    }
+    if (targetType === "string") {
+        return rawValue;
+    }
+    // 智能自动探测
+    const trimmed = rawValue.trim();
+    const lower = trimmed.toLowerCase();
+    if (lower === "true")
+        return true;
+    if (lower === "false")
+        return false;
+    if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            // 保持为字符串
+        }
+    }
+    return rawValue;
+}
+/**
+ * 从操作系统环境变量 (process.env) 中解析配置值。
+ * 严格遵循多层回退候选链：
+ * 1. actiondock.json 中声明的显式环境变量绑定 (itemDef.env)
+ * 2. 带包名前缀的变量: `ACTIONDOCK_<PACKAGE>_<KEY>` 以及 `<PACKAGE>_<KEY>`
+ * 3. 标准大写蛇形变量: `<KEY>` (SNAKE_CASE)
+ * 4. 原始键名原样匹配
+ *
+ * @param key 配置键名
+ * @param itemDef 配置项元数据定义
+ * @param packageId 所属包 ID
+ * @returns 命中的 ResolvedEnv 对象或 undefined
+ */
+export function resolveEnvValue(key, itemDef, packageId) {
+    if (typeof process === "undefined" || !process.env) {
+        return undefined;
+    }
+    const candidateKeys = new Set();
+    // 1. actiondock.json 中显式声明的 env 变量名
+    if (itemDef?.env) {
+        if (Array.isArray(itemDef.env)) {
+            for (const e of itemDef.env) {
+                if (typeof e === "string" && e.trim()) {
+                    candidateKeys.add(e.trim());
+                }
+            }
+        }
+        else if (typeof itemDef.env === "string" && itemDef.env.trim()) {
+            candidateKeys.add(itemDef.env.trim());
+        }
+    }
+    // 2. 包名前缀的环境变量 (例如 ACTIONDOCK_GITHUB_TOOLS_API_KEY / GITHUB_TOOLS__API_KEY)
+    const snakeKey = toSnakeUpperCase(key);
+    if (packageId) {
+        const cleanPkg = toSnakeUpperCase(packageId);
+        candidateKeys.add(`ACTIONDOCK_${cleanPkg}_${snakeKey}`);
+        candidateKeys.add(`ACTIONDOCK_${cleanPkg}__${snakeKey}`);
+        candidateKeys.add(`${cleanPkg}_${snakeKey}`);
+        candidateKeys.add(`${cleanPkg}__${snakeKey}`);
+        const slug = toSnakeUpperCase(getPackageSlug(packageId));
+        if (slug && slug !== cleanPkg) {
+            candidateKeys.add(`ACTIONDOCK_${slug}_${snakeKey}`);
+            candidateKeys.add(`ACTIONDOCK_${slug}__${snakeKey}`);
+            candidateKeys.add(`${slug}_${snakeKey}`);
+            candidateKeys.add(`${slug}__${snakeKey}`);
+        }
+    }
+    // 3. 标准大写蛇形变量名 (例如 API_KEY)
+    candidateKeys.add(snakeKey);
+    // 4. 原始键名 (例如 apiKey)
+    candidateKeys.add(key);
+    // 按优先级顺序依次检索环境变量
+    const effectiveType = itemDef?.type || inferTypeFromDefault(itemDef?.default);
+    for (const envKey of candidateKeys) {
+        const rawVal = process.env[envKey];
+        if (rawVal !== undefined) {
+            const coerced = coerceEnvValue(rawVal, effectiveType);
+            return {
+                value: coerced,
+                envKey,
+                matchedKey: envKey,
+                source: "env",
+            };
+        }
+    }
+    return undefined;
+}

package/dist/runtime/events.d.ts

@@ -1,11 +1,14 @@
 import type { ExecutionEvent } from "@actiondock/sdk";
+export interface EventSinkSubscribeOptions {
+    after?: number | string;
+    signal?: AbortSignal;
+    maxQueueSize?: number;
+}
 export interface EventSink {
     emit(event: ExecutionEvent): void;
-    subscribe(runId: string, options?: {
-        after?: number;
-        signal?: AbortSignal;
-    }): AsyncIterable<ExecutionEvent>;
+    subscribe(runId: string, options?: EventSinkSubscribeOptions): AsyncIterable<ExecutionEvent>;
     clear(runId: string): void;
+    close?(): void;
 }
 export interface InMemoryEventSinkOptions {
     /** 单个运行最大缓冲事件数（默认 1024） */
@@ -14,14 +17,18 @@ export interface InMemoryEventSinkOptions {
     maxBytesPerRun?: number;
     /** 全局最大缓存运行数（默认 500） */
     maxRuns?: number;
+    /** 慢订阅者事件队列背压有界上限（默认 1024） */
+    maxSubscriberQueueSize?: number;
 }
 /**
  * 进程内有界事件缓冲区实现。
  * 遵循设计规范：
- * 1. 单运行双配额保护：上限 1024 条事件或 1MiB 字节数，优先淘汰日志与进度，保护终态。
- * 2. 全局有界回收：限制最大运行数（默认 500），溢出时优先淘汰已完成运行。
- * 3. 原子订阅衔接：先注册实时队列再回放历史快照，去重并杜绝并发丢事件窗口。
- * 4. 严格生命周期清理：迭代退出或中断时彻底注销监听器与 AbortSignal 事件。
+ * - 单运行双配额保护：上限 1024 条事件或 1MiB 字节数，优先淘汰日志与进度，保护终态。
+ * - 全局有界回收：限制最大运行数（默认 500），溢出时优先淘汰已完成运行。
+ * - 原子订阅衔接：先注册实时队列再回放历史快照，去重并杜绝并发丢事件窗口。
+ * - 严格生命周期清理：迭代退出或中断时彻底注销监听器与 AbortSignal 事件。
+ * - 慢订阅者背压保护：队列超出上限时推送终止事件并切断通道，主运行不受阻。
+ * - 游标断点续传：支持全局持久化 eventId 与序列号，过期游标返回 EVENT_CURSOR_EXPIRED。
  */
 export declare class InMemoryEventSink implements EventSink {
     private runs;
@@ -29,15 +36,38 @@ export declare class InMemoryEventSink implements EventSink {
     private wakeups;
     private evictions;
     private evictedRuns;
+    private globalEventSeq;
     private maxEventsPerRun;
     private maxBytesPerRun;
     private maxRuns;
+    private maxSubscriberQueueSize;
     constructor(options?: InMemoryEventSinkOptions);
     emit(event: ExecutionEvent): void;
-    subscribe(runId: string, options?: {
-        after?: number;
-        signal?: AbortSignal;
-    }): AsyncIterable<ExecutionEvent>;
+    subscribe(runId: string, options?: EventSinkSubscribeOptions): AsyncIterable<ExecutionEvent>;
+    /**
+     * 断言请求游标仍处于保留窗口内（过期则抛出 EVENT_CURSOR_EXPIRED 错误）。
+     */
+    private assertCursorRetained;
+    /**
+     * 记录已交付事件并推进游标（已交付序号与最后确认游标）。
+     */
+    private trackDeliveredEvent;
+    /**
+     * 终止谓词：finish 事件或背压终止事件交付后订阅应立即结束。
+     */
+    private isTerminalDelivery;
+    /**
+     * 从实时队列取出下一条应交付的事件（跳过已交付序号），并同步推进游标。
+     */
+    private takeNextDeliverable;
+    /**
+     * 挂起等待下一条实时事件、通道终止或运行淘汰唤醒（严格注销监听避免泄漏）。
+     */
+    private waitForNextEvent;
+    /**
+     * 手动修剪已终态运行中早于指定序列号的历史事件（用于模拟过期清理）。
+     */
+    pruneEvents(runId: string, upToSequence: number): void;
     clear(runId: string): void;
     /**
      * 获取指定运行的事件统计信息（调试与测试用）。
@@ -56,6 +86,8 @@ export declare class InMemoryEventSink implements EventSink {
      * 优先淘汰已终态运行；若无终态运行则淘汰最旧活动运行，严格保证 runs.size <= maxRuns。
      */
     private evictOldestRun;
+    /**
+     * 关闭事件接收器并唤醒所有活跃订阅者退出。
+     */
+    close(): void;
 }
-export declare function getDefaultEventSink(): EventSink;
-export declare function setDefaultEventSink(sink: EventSink): void;