@actiondock/testing 2.0.12 → 2.2.0

package/dist/index.js

@@ -1,486 +1,6 @@
-// packages/testing/src/index.ts
-import { registerTestRuntimeProvider } from "@actiondock/sdk";
-
-// packages/testing/src/runtime.ts
-import {
-  DefaultExecutionService,
-  InMemoryEventSink,
-  RuntimeConfig,
-  RuntimeStateStore
-} from "@actiondock/core";
-import {
-  MemoryLogger
-} from "@actiondock/sdk";
-
-// packages/testing/src/clock.ts
-class FakeClock {
-  currentNow;
-  currentMonotonic;
-  nextTimerId = 1;
-  pendingSleeps = [];
-  constructor(options = {}) {
-    if (options.now !== undefined) {
-      this.currentNow = new Date(options.now).getTime();
-    } else {
-      this.currentNow = Date.now();
-    }
-    this.currentMonotonic = options.startMonotonic ?? 0;
-  }
-  now() {
-    return new Date(this.currentNow);
-  }
-  monotonic() {
-    return this.currentMonotonic;
-  }
-  sleep(ms) {
-    if (ms <= 0) {
-      return Promise.resolve();
-    }
-    return new Promise((resolve, reject) => {
-      const targetMonotonic = this.currentMonotonic + ms;
-      const targetNow = this.currentNow + ms;
-      this.pendingSleeps.push({
-        id: this.nextTimerId++,
-        targetMonotonic,
-        targetNow,
-        resolve,
-        reject
-      });
-      this.pendingSleeps.sort((a, b) => a.targetMonotonic - b.targetMonotonic);
-    });
-  }
-  async advance(ms) {
-    if (ms < 0) {
-      throw new Error("Cannot advance clock by negative time");
-    }
-    if (ms === 0) {
-      await Promise.resolve();
-      return;
-    }
-    const destinationMonotonic = this.currentMonotonic + ms;
-    const destinationNow = this.currentNow + ms;
-    while (this.pendingSleeps.length > 0) {
-      const nextSleep = this.pendingSleeps[0];
-      if (nextSleep.targetMonotonic > destinationMonotonic) {
-        break;
-      }
-      this.pendingSleeps.shift();
-      this.currentMonotonic = nextSleep.targetMonotonic;
-      this.currentNow = nextSleep.targetNow;
-      nextSleep.resolve();
-      await Promise.resolve();
-    }
-    this.currentMonotonic = destinationMonotonic;
-    this.currentNow = destinationNow;
-    await Promise.resolve();
-  }
-  get pendingCount() {
-    return this.pendingSleeps.length;
-  }
-  clear() {
-    const sleeps = this.pendingSleeps;
-    this.pendingSleeps = [];
-    for (const item of sleeps) {
-      item.reject(new Error("FakeClock timer cancelled"));
-    }
-  }
-}
-
-// packages/testing/src/process.ts
-class MockProcessExecutor {
-  mocks = [];
-  calls = [];
-  detachedCalls = [];
-  defaultPid = 10001;
-  register(matcher, handlerOrResult) {
-    this.mocks.push({ matcher, handler: handlerOrResult });
-    return this;
-  }
-  async exec(command, args = [], options = {}) {
-    const startTime = Date.now();
-    this.calls.push({
-      command,
-      args: [...args],
-      options: { ...options },
-      timestamp: startTime
-    });
-    if (options.signal?.aborted) {
-      const res = {
-        ok: false,
-        exitCode: null,
-        signal: "SIGTERM",
-        stdout: "",
-        stderr: "Process was cancelled by AbortSignal",
-        raw: new Uint8Array,
-        timedOut: false,
-        cancelled: true,
-        durationMs: 0,
-        error: {
-          code: "PROCESS_CANCELLED",
-          message: "Process was cancelled by AbortSignal"
-        }
-      };
-      if (options.throwOnError) {
-        throw new Error(res.stderr);
-      }
-      return res;
-    }
-    const matchedMock = this.findMock(command, args, options);
-    let resolved;
-    if (!matchedMock) {
-      resolved = {
-        ok: true,
-        exitCode: 0,
-        stdout: "",
-        stderr: ""
-      };
-    } else if (typeof matchedMock.handler === "function") {
-      resolved = await matchedMock.handler(command, args, options);
-    } else {
-      resolved = matchedMock.handler;
-    }
-    const maybeMock = resolved;
-    if (typeof maybeMock.delayMs === "number" && maybeMock.delayMs > 0) {
-      await this.waitDelay(maybeMock.delayMs, options);
-    }
-    const timedOut = Boolean(resolved.timedOut);
-    const cancelled = Boolean(resolved.cancelled || options.signal?.aborted);
-    const stdout = resolved.stdout ?? "";
-    const stderr = resolved.stderr ?? (timedOut ? "Process timed out" : cancelled ? "Process cancelled" : "");
-    const raw = resolved.raw ?? new TextEncoder().encode(stdout);
-    const exitCode = resolved.exitCode !== undefined ? resolved.exitCode : timedOut || cancelled ? null : resolved.ok === false ? 1 : 0;
-    const ok = resolved.ok !== undefined ? resolved.ok : exitCode === 0 && !timedOut && !cancelled && !resolved.error;
-    const durationMs = resolved.durationMs ?? Date.now() - startTime;
-    let error = resolved.error;
-    if (!error) {
-      if (timedOut) {
-        error = {
-          code: "PROCESS_TIMEOUT",
-          message: `Process exceeded timeout of ${options.timeoutMs ?? durationMs}ms`
-        };
-      } else if (cancelled) {
-        error = {
-          code: "PROCESS_CANCELLED",
-          message: "Process was cancelled by AbortSignal"
-        };
-      } else if (!ok) {
-        error = {
-          code: "PROCESS_FAILED",
-          message: stderr || `Process exited with code ${exitCode}`
-        };
-      }
-    }
-    const finalResult = {
-      ok,
-      exitCode,
-      signal: resolved.signal,
-      stdout,
-      stderr,
-      raw,
-      timedOut,
-      cancelled,
-      durationMs,
-      error
-    };
-    if (!ok && options.throwOnError) {
-      throw new Error(stderr || `Process exited with code ${exitCode}`);
-    }
-    return finalResult;
-  }
-  async spawnDetached(options) {
-    const startTime = Date.now();
-    this.detachedCalls.push({
-      options: { ...options },
-      timestamp: startTime
-    });
-    if (options.signal?.aborted) {
-      return {
-        ok: false,
-        ready: false,
-        durationMs: 0,
-        error: {
-          code: "PROCESS_CANCELLED",
-          message: "Process was cancelled by AbortSignal"
-        }
-      };
-    }
-    if (options.probe) {
-      const fakeResult = {
-        ok: true,
-        exitCode: 0,
-        stdout: "ready",
-        stderr: "",
-        raw: new TextEncoder().encode("ready"),
-        timedOut: false,
-        cancelled: false,
-        durationMs: 0
-      };
-      const isReady = await options.probe(fakeResult);
-      return {
-        ok: isReady,
-        pid: this.defaultPid++,
-        ready: isReady,
-        durationMs: Date.now() - startTime
-      };
-    }
-    return {
-      ok: true,
-      pid: this.defaultPid++,
-      ready: true,
-      durationMs: Date.now() - startTime
-    };
-  }
-  getCalls(command) {
-    if (!command) {
-      return [...this.calls];
-    }
-    return this.calls.filter((c) => c.command === command);
-  }
-  getLastCall() {
-    return this.calls[this.calls.length - 1];
-  }
-  hasCalled(command) {
-    return this.calls.some((c) => c.command === command);
-  }
-  clearHistory() {
-    this.calls = [];
-    this.detachedCalls = [];
-  }
-  reset() {
-    this.mocks = [];
-    this.calls = [];
-    this.detachedCalls = [];
-  }
-  findMock(command, args, options) {
-    const fullCommandLine = [command, ...args].join(" ").trim();
-    for (let i = this.mocks.length - 1;i >= 0; i--) {
-      const mock = this.mocks[i];
-      if (typeof mock.matcher === "string") {
-        if (mock.matcher === command || mock.matcher === fullCommandLine || fullCommandLine.startsWith(mock.matcher)) {
-          return mock;
-        }
-      } else if (mock.matcher instanceof RegExp) {
-        if (mock.matcher.test(fullCommandLine) || mock.matcher.test(command)) {
-          return mock;
-        }
-      } else if (typeof mock.matcher === "function") {
-        if (mock.matcher(command, args, options)) {
-          return mock;
-        }
-      }
-    }
-    return;
-  }
-  async waitDelay(delayMs, options) {
-    return new Promise((resolve) => {
-      let timer;
-      const cleanup = () => {
-        if (timer)
-          clearTimeout(timer);
-      };
-      if (options.signal) {
-        options.signal.addEventListener("abort", () => {
-          cleanup();
-          resolve();
-        }, { once: true });
-      }
-      timer = setTimeout(() => {
-        cleanup();
-        resolve();
-      }, delayMs);
-    });
-  }
-}
-
-// packages/testing/src/storage.ts
-import {
-  SqliteRuntimeStorage
-} from "@actiondock/core";
-
-class MemoryStorage extends SqliteRuntimeStorage {
-  constructor(options = {}) {
-    super({
-      packageId: options.packageId || "test-pkg",
-      dbPath: ":memory:",
-      driver: options.driver,
-      clock: options.clock
-    });
-  }
-}
-
-// packages/testing/src/runtime.ts
-class ActionRuntimeError extends Error {
-  code;
-  details;
-  cause;
-  constructor(error) {
-    super(error.message);
-    this.name = "ActionRuntimeError";
-    this.code = error.code;
-    this.details = error.details;
-    this.cause = error.cause;
-    Object.setPrototypeOf(this, ActionRuntimeError.prototype);
-  }
-}
-
-class TestConfigStore {
-  runtimeConfig;
-  storage;
-  constructor(storage, projectConfig, overrides) {
-    this.storage = storage;
-    this.runtimeConfig = new RuntimeConfig(storage, overrides, projectConfig, undefined);
-  }
-  get(key, defaultValue) {
-    return this.runtimeConfig.get(key, defaultValue);
-  }
-  has(key) {
-    return this.runtimeConfig.has(key);
-  }
-  set(key, value) {
-    this.storage.setConfig(key, value);
-  }
-  delete(key) {
-    return this.storage.deleteConfig(key);
-  }
-  list() {
-    return this.storage.listConfig();
-  }
-}
-
-class TestEventSink extends InMemoryEventSink {
-  allEvents = [];
-  sequenceCounter = 0;
-  nextSequence() {
-    return this.sequenceCounter++;
-  }
-  emit(event) {
-    this.allEvents.push(event);
-    super.emit(event);
-  }
-  getEvents(runId) {
-    if (runId) {
-      return this.allEvents.filter((e) => e.runId === runId);
-    }
-    return [...this.allEvents];
-  }
-  clearAll() {
-    this.allEvents = [];
-    this.sequenceCounter = 0;
-  }
-}
-function createTestRuntime(options = {}) {
-  const packageId = options.packageId || "test-pkg";
-  const clock = options.clock ?? new FakeClock;
-  const process = options.process ?? new MockProcessExecutor;
-  const storage = options.storage ?? new MemoryStorage({
-    packageId,
-    clock
-  });
-  if (options.config) {
-    for (const [key, val] of Object.entries(options.config)) {
-      storage.setConfig(key, val);
-    }
-  }
-  if (options.state) {
-    for (const [key, val] of Object.entries(options.state)) {
-      storage.setState("", key, val);
-    }
-  }
-  const events = new TestEventSink;
-  const memoryLogger = options.logger instanceof MemoryLogger ? options.logger : new MemoryLogger;
-  const actionsMap = new Map;
-  if (options.actions) {
-    if (Array.isArray(options.actions)) {
-      for (const act of options.actions) {
-        actionsMap.set(act.id, act);
-      }
-    } else if (options.actions instanceof Map) {
-      for (const [k, v] of options.actions) {
-        actionsMap.set(k, v);
-      }
-    } else if (typeof options.actions === "object") {
-      for (const [k, v] of Object.entries(options.actions)) {
-        actionsMap.set(k, v);
-      }
-    }
-  }
-  const executionService = new DefaultExecutionService({
-    packageId,
-    storage,
-    projectConfig: options.projectConfig,
-    configOverrides: options.configOverrides,
-    actions: actionsMap,
-    process,
-    clock,
-    logger: memoryLogger,
-    eventSink: events
-  });
-  const testConfig = new TestConfigStore(storage, options.projectConfig, options.configOverrides);
-  const testState = new RuntimeStateStore(storage);
-  const registerAction = (action) => {
-    executionService.registerAction(action);
-  };
-  const getAction = (id) => {
-    return executionService.getAction(id);
-  };
-  const listActions = () => {
-    return executionService.listActions();
-  };
-  const execute = async (action, input = {}, execOptions = {}) => {
-    if (typeof action !== "string") {
-      executionService.registerAction(action);
-    }
-    const actionRef = typeof action === "string" ? action : action.id;
-    const ticket = await executionService.start(actionRef, input, {
-      signal: execOptions.signal,
-      timeoutMs: execOptions.timeoutMs,
-      config: execOptions.configOverrides,
-      parentRunId: execOptions.parentRunId,
-      rootRunId: execOptions.rootRunId,
-      maxCallDepth: execOptions.maxCallDepth,
-      logger: execOptions.logger,
-      progress: execOptions.progress,
-      process: execOptions.process || process
-    });
-    const result = await ticket.result;
-    return result;
-  };
-  const run = async (action, input = {}) => {
-    const result = await execute(action, input);
-    if (!result.ok) {
-      throw new ActionRuntimeError(result.error);
-    }
-    return result.data;
-  };
-  return {
-    config: testConfig,
-    state: testState,
-    clock,
-    process,
-    events,
-    logger: memoryLogger,
-    storage,
-    executionService,
-    runner: executionService.runner,
-    registerAction,
-    getAction,
-    listActions,
-    run,
-    execute
-  };
-}
-
-// packages/testing/src/index.ts
-function registerTestingAsSdkProvider() {
-  registerTestRuntimeProvider(createTestRuntime);
-}
-export {
-  ActionRuntimeError,
-  FakeClock,
-  MemoryStorage,
-  MockProcessExecutor,
-  TestConfigStore,
-  TestEventSink,
-  createTestRuntime,
-  registerTestingAsSdkProvider
-};
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./storage.js";
+export * from "./runtime.js";
+export * from "./platform.js";
+export * from "./cli.js";

package/dist/platform.d.ts

@@ -0,0 +1,48 @@
+import { type EventSink, type FileSystem, type ModuleLoader, type RuntimePlatform, type RuntimeStorage, type StorageFactory } from "@actiondock/core";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+/**
+ * 测试平台构建配置选项。
+ */
+export interface TestPlatformOptions {
+    /** 可选注入的确定性虚拟时钟 */
+    clock?: FakeClock;
+    /** 可选注入的统一存储实例（若指定则所有 Package 存储均回退至该实例） */
+    storage?: RuntimeStorage;
+    /** 可选注入的跨 Package 全局存储实例 */
+    globalStorage?: RuntimeStorage;
+    /** 可选注入的模拟进程执行器 */
+    process?: MockProcessExecutor;
+    /** 可选注入的执行事件接收器 */
+    eventSink?: EventSink;
+    /** 可选注入的文件系统抽象驱动 */
+    files?: FileSystem;
+    /** 可选注入的源码模块加载器 */
+    modules?: ModuleLoader;
+}
+/**
+ * 测试运行时平台接口契约。
+ * 完整实现 RuntimePlatform，并显式暴露测试组件类型。
+ */
+export interface TestPlatform extends RuntimePlatform {
+    readonly name: "test";
+    readonly clock: FakeClock;
+    readonly files: FileSystem;
+    readonly modules: ModuleLoader;
+    readonly process: MockProcessExecutor;
+    readonly storage: StorageFactory;
+    readonly eventSink: EventSink;
+}
+/**
+ * 创建纯内存确定性测试平台实例。
+ * 组装测试核心组件：
+ * - FakeClock 确定性虚拟时钟
+ * - MockProcessExecutor 模拟进程执行器
+ * - MemoryStorage 纯内存数据库存储
+ * - TestEventSink 确定性事件接收器
+ * - DefaultModuleLoader 动态模块加载器
+ * - NodeFileSystem 文件系统
+ *
+ * @param options 测试平台配置选项
+ */
+export declare function createTestPlatform(options?: TestPlatformOptions): TestPlatform;

package/dist/platform.js

@@ -0,0 +1,61 @@
+import { DefaultModuleLoader, NodeFileSystem, } from "@actiondock/core";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+import { TestEventSink } from "./runtime.js";
+import { MemoryStorage } from "./storage.js";
+/**
+ * 创建纯内存确定性测试平台实例。
+ * 组装测试核心组件：
+ * - FakeClock 确定性虚拟时钟
+ * - MockProcessExecutor 模拟进程执行器
+ * - MemoryStorage 纯内存数据库存储
+ * - TestEventSink 确定性事件接收器
+ * - DefaultModuleLoader 动态模块加载器
+ * - NodeFileSystem 文件系统
+ *
+ * @param options 测试平台配置选项
+ */
+export function createTestPlatform(options = {}) {
+    const clock = options.clock ?? new FakeClock();
+    const process = options.process ?? new MockProcessExecutor();
+    const eventSink = options.eventSink ?? new TestEventSink();
+    const files = options.files ?? new NodeFileSystem();
+    const modules = options.modules ?? new DefaultModuleLoader();
+    const packageStorages = new Map();
+    let globalStorageInstance = options.globalStorage;
+    const storageFactory = {
+        createStorage(packageId, _opts) {
+            if (options.storage) {
+                return options.storage;
+            }
+            let existing = packageStorages.get(packageId);
+            if (!existing) {
+                existing = new MemoryStorage({
+                    packageId,
+                    clock,
+                });
+                packageStorages.set(packageId, existing);
+            }
+            return existing;
+        },
+        createGlobalStorage(_opts) {
+            if (globalStorageInstance) {
+                return globalStorageInstance;
+            }
+            globalStorageInstance = new MemoryStorage({
+                packageId: "__global__",
+                clock,
+            });
+            return globalStorageInstance;
+        },
+    };
+    return {
+        name: "test",
+        clock,
+        files,
+        modules,
+        process,
+        storage: storageFactory,
+        eventSink,
+    };
+}

package/dist/process.d.ts

@@ -1,5 +1,5 @@
 import type { ProcessExecutor } from "@actiondock/core";
-import type { DetachedProcessOptions, DetachedProcessResult, ProcessExecOptions, ProcessResult, RuntimeError } from "@actiondock/sdk";
+import type { ProcessExecOptions, ProcessResult, RuntimeError } from "@actiondock/sdk";
 /**
  * 模拟命令匹配器。
  */
@@ -49,23 +49,25 @@ export interface ProcessCall {
     timestamp: number;
 }
 /**
- * 已记录的后台守护进程调用历史条目。
+ * 模拟进程执行器构造选项。
  */
-export interface DetachedProcessCall {
-    /** 启动参数选项 */
-    options: DetachedProcessOptions;
-    /** 调用发生时的时间戳 */
-    timestamp: number;
+export interface MockProcessExecutorOptions {
+    /** 未命中任何模拟规则时是否回退到真实子进程执行（默认 false，未命中即抛错） */
+    fallbackToReal?: boolean;
 }
 /**
  * 模拟进程执行器实现。
  * 遵循 ProcessExecutor 接口契约，支持预设命令响应、跟踪调用历史并模拟超时与取消场景。
+ *
+ * 默认不回退真实子进程执行：未命中任何模拟规则时抛出明确错误，避免测试中的拼写失误穿透到真实系统命令。
+ * 如确需真实回退（例如集成本地 CLI），可显式传入 fallbackToReal: true。
  */
 export declare class MockProcessExecutor implements ProcessExecutor {
     private mocks;
     calls: ProcessCall[];
-    detachedCalls: DetachedProcessCall[];
     defaultPid: number;
+    private readonly fallbackToReal;
+    constructor(options?: MockProcessExecutorOptions);
     /**
      * 注册模拟命令匹配与返回结果。
      *
@@ -81,12 +83,7 @@ export declare class MockProcessExecutor implements ProcessExecutor {
      * @param options 执行选项
      */
     exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
-    /**
-     * 启动模拟脱离父进程的后台进程。
-     *
-     * @param options 守护进程启动选项
-     */
-    spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult>;
+    spawn(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
     /**
      * 获取指定命令的历史调用记录。
      *
@@ -111,6 +108,10 @@ export declare class MockProcessExecutor implements ProcessExecutor {
      * 重置所有注册规则与历史记录。
      */
     reset(): void;
+    /**
+     * 渲染已注册匹配器列表，辅助定位拼写失误。
+     */
+    private describeMatchers;
     private findMock;
     private waitDelay;
 }