@ai-setting/roy-agent-core 1.3.10 → 1.3.14

package/src/env/hook/hook-manager.test.ts

@@ -1,374 +0,0 @@
-import { describe, test, expect, beforeEach } from "bun:test";
-import { HookManager, type Hook, type HookContext } from "./hook-manager";
-import { createHook } from "./types";
-
-// 测试用的上下文类型
-interface TestData {
-  value: number;
-}
-
-// 创建测试 Hook 的辅助函数
-function makeHook(
-  name: string,
-  execute: (ctx: HookContext<TestData>) => void | Promise<void>,
-  priority?: number
-): Hook<TestData> {
-  return createHook({ name, priority }, execute);
-}
-
-describe("HookManager", () => {
-  let manager: HookManager<TestData>;
-
-  beforeEach(() => {
-    manager = new HookManager<TestData>();
-  });
-
-  // ========================================================================
-  // 基础功能测试
-  // ========================================================================
-
-  describe("register", () => {
-    test("should register a hook to a hook point", () => {
-      const hook = makeHook("test-hook", async () => {});
-      
-      manager.register("test.point", hook);
-      
-      expect(manager.count("test.point")).toBe(1);
-    });
-
-    test("should register multiple hooks to the same hook point", () => {
-      const hook1 = makeHook("hook-1", async () => {});
-      const hook2 = makeHook("hook-2", async () => {});
-      
-      manager.register("test.point", hook1);
-      manager.register("test.point", hook2);
-      
-      expect(manager.count("test.point")).toBe(2);
-    });
-
-    test("should register hooks to different hook points", () => {
-      const hook1 = makeHook("hook-1", async () => {});
-      const hook2 = makeHook("hook-2", async () => {});
-      
-      manager.register("point.1", hook1);
-      manager.register("point.2", hook2);
-      
-      expect(manager.count("point.1")).toBe(1);
-      expect(manager.count("point.2")).toBe(1);
-    });
-  });
-
-  describe("registerMany", () => {
-    test("should register multiple hooks at once", () => {
-      const hooks = [
-        makeHook("hook-1", async () => {}),
-        makeHook("hook-2", async () => {}),
-      ];
-      
-      manager.registerMany("test.point", hooks);
-      
-      expect(manager.count("test.point")).toBe(2);
-    });
-
-    test("should register empty array", () => {
-      manager.registerMany("test.point", []);
-      expect(manager.count("test.point")).toBe(0);
-    });
-  });
-
-  describe("unregister", () => {
-    test("should unregister a hook by name", () => {
-      const hook1 = makeHook("hook-1", async () => {});
-      const hook2 = makeHook("hook-2", async () => {});
-      
-      manager.register("test.point", hook1);
-      manager.register("test.point", hook2);
-      
-      const result = manager.unregister("test.point", "hook-1");
-      
-      expect(result).toBe(true);
-      expect(manager.count("test.point")).toBe(1);
-    });
-
-    test("should return false if hook not found", () => {
-      const result = manager.unregister("nonexistent", "hook");
-      expect(result).toBe(false);
-    });
-  });
-
-  describe("unregisterAll", () => {
-    test("should unregister all hooks at a hook point", () => {
-      manager.register("test.point", makeHook("hook-1", async () => {}));
-      manager.register("test.point", makeHook("hook-2", async () => {}));
-      
-      manager.unregisterAll("test.point");
-      
-      expect(manager.count("test.point")).toBe(0);
-    });
-  });
-
-  describe("count", () => {
-    test("should return 0 for non-existent hook point", () => {
-      expect(manager.count("nonexistent")).toBe(0);
-    });
-  });
-
-  describe("clear", () => {
-    test("should clear all hooks", () => {
-      manager.register("point.1", makeHook("hook-1", async () => {}));
-      manager.register("point.2", makeHook("hook-2", async () => {}));
-      
-      manager.clear();
-      
-      expect(manager.count("point.1")).toBe(0);
-      expect(manager.count("point.2")).toBe(0);
-    });
-  });
-
-  describe("getHookPoints", () => {
-    test("should return all registered hook points", () => {
-      manager.register("point.1", makeHook("hook-1", async () => {}));
-      manager.register("point.2", makeHook("hook-2", async () => {}));
-      manager.register("point.3", makeHook("hook-3", async () => {}));
-      
-      const points = manager.getHookPoints();
-      
-      expect(points).toContain("point.1");
-      expect(points).toContain("point.2");
-      expect(points).toContain("point.3");
-    });
-
-    test("should return empty array when no hooks registered", () => {
-      expect(manager.getHookPoints()).toEqual([]);
-    });
-  });
-
-  // ========================================================================
-  // 执行测试
-  // ========================================================================
-
-  describe("execute", () => {
-    test("should execute all hooks at a hook point", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("hook-1", async () => {
-        executionOrder.push("hook-1");
-      }));
-      manager.register("test.point", makeHook("hook-2", async () => {
-        executionOrder.push("hook-2");
-      }));
-      
-      await manager.execute("test.point", { value: 42 }, { meta: "test" });
-      
-      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
-    });
-
-    test("should pass correct context to hooks", async () => {
-      let receivedCtx: HookContext<TestData> | null = null;
-      
-      manager.register("test.point", makeHook("test-hook", async (ctx) => {
-        receivedCtx = ctx;
-      }));
-      
-      const testData = { value: 123 };
-      const testMeta = { source: "unit-test" };
-      
-      await manager.execute("test.point", testData, testMeta);
-      
-      expect(receivedCtx).not.toBeNull();
-      expect(receivedCtx!.data).toEqual(testData);
-      expect(receivedCtx!.metadata).toEqual(testMeta);
-      expect(receivedCtx!.phase).toBe("before");
-      expect(receivedCtx!.hookPoint).toBe("test.point");
-    });
-
-    test("should do nothing for non-existent hook point", async () => {
-      const hook = makeHook("should-not-run", async () => {
-        throw new Error("This hook should not run");
-      });
-      
-      // 不注册，直接执行
-      await manager.execute("nonexistent", { value: 0 });
-      
-      // 没有错误即为通过
-      expect(true).toBe(true);
-    });
-  });
-
-  describe("executeAndCollect", () => {
-    test("should collect return values from hooks", async () => {
-      manager.register("test.point", makeHook("hook-1", async () => "result-1"));
-      manager.register("test.point", makeHook("hook-2", async () => "result-2"));
-      
-      const results = await manager.executeAndCollect<string>("test.point", { value: 0 });
-      
-      expect(results).toEqual(["result-1", "result-2"]);
-    });
-
-    test("should return empty array for non-existent hook point", async () => {
-      const results = await manager.executeAndCollect<string>("nonexistent", { value: 0 });
-      expect(results).toEqual([]);
-    });
-  });
-
-  // ========================================================================
-  // 优先级测试
-  // ========================================================================
-
-  describe("hook priority", () => {
-    test("should execute hooks in priority order (lower priority first)", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("low-priority", async () => {
-        executionOrder.push("low-priority");
-      }, 100));
-      
-      manager.register("test.point", makeHook("high-priority", async () => {
-        executionOrder.push("high-priority");
-      }, 1));
-      
-      manager.register("test.point", makeHook("medium-priority", async () => {
-        executionOrder.push("medium-priority");
-      }, 50));
-      
-      await manager.execute("test.point", { value: 0 });
-      
-      expect(executionOrder).toEqual([
-        "high-priority",
-        "medium-priority",
-        "low-priority"
-      ]);
-    });
-
-    test("should maintain registration order for same priority", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("first", async () => {
-        executionOrder.push("first");
-      }, 0));
-      
-      manager.register("test.point", makeHook("second", async () => {
-        executionOrder.push("second");
-      }, 0));
-      
-      await manager.execute("test.point", { value: 0 });
-      
-      expect(executionOrder).toEqual(["first", "second"]);
-    });
-
-    test("should use default priority 0 when not specified", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("with-priority", async () => {
-        executionOrder.push("with-priority");
-      }, 10));
-      
-      manager.register("test.point", makeHook("no-priority", async () => {
-        executionOrder.push("no-priority");
-      }));
-      
-      await manager.execute("test.point", { value: 0 });
-      
-      expect(executionOrder).toEqual(["no-priority", "with-priority"]);
-    });
-  });
-
-  // ========================================================================
-  // 错误隔离测试
-  // ========================================================================
-
-  describe("error isolation", () => {
-    test("should not throw if a hook throws", async () => {
-      manager.register("test.point", makeHook("failing-hook", async () => {
-        throw new Error("Hook failed");
-      }));
-      
-      manager.register("test.point", makeHook("good-hook", async () => {}));
-      
-      // 应该不抛出错误 - 直接调用而不是用 expect
-      let threw = false;
-      try {
-        await manager.execute("test.point", { value: 0 });
-      } catch {
-        threw = true;
-      }
-      expect(threw).toBe(false);
-    });
-
-    test("should continue executing other hooks if one fails", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("hook-1", async () => {
-        executionOrder.push("hook-1");
-      }));
-      
-      manager.register("test.point", makeHook("failing-hook", async () => {
-        throw new Error("Hook failed");
-      }));
-      
-      manager.register("test.point", makeHook("hook-2", async () => {
-        executionOrder.push("hook-2");
-      }));
-      
-      await manager.execute("test.point", { value: 0 });
-      
-      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
-    });
-
-    test("should handle async hooks throwing", async () => {
-      const executionOrder: string[] = [];
-      
-      manager.register("test.point", makeHook("hook-1", async () => {
-        executionOrder.push("hook-1");
-      }));
-      
-      manager.register("test.point", makeHook("async-failing", async () => {
-        await Promise.resolve();
-        throw new Error("Async hook failed");
-      }));
-      
-      manager.register("test.point", makeHook("hook-2", async () => {
-        executionOrder.push("hook-2");
-      }));
-      
-      await manager.execute("test.point", { value: 0 });
-      
-      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
-    });
-  });
-
-  // ========================================================================
-  // 生命周期测试
-  // ========================================================================
-
-  describe("hook lifecycle", () => {
-    test("should pass component info to hooks", async () => {
-      let receivedCtx: HookContext<TestData> | null = null;
-      const customManager = new HookManager<TestData>({
-        componentName: "TestComponent",
-        componentVersion: "2.0.0"
-      });
-      
-      customManager.register("test.point", makeHook("test-hook", async (ctx) => {
-        receivedCtx = ctx;
-      }));
-      
-      await customManager.execute("test.point", { value: 0 });
-      
-      expect(receivedCtx!.component.name).toBe("TestComponent");
-      expect(receivedCtx!.component.version).toBe("2.0.0");
-    });
-
-    test("should pass correct hookPoint to hooks", async () => {
-      let receivedHookPoint: string | null = null;
-      
-      manager.register("my.hook.point", makeHook("test-hook", async (ctx) => {
-        receivedHookPoint = ctx.hookPoint;
-      }));
-      
-      await manager.execute("my.hook.point", { value: 0 });
-      
-      expect(receivedHookPoint).toBe("my.hook.point");
-    });
-  });
-});

package/src/env/hook/hook-manager.ts

@@ -1,309 +0,0 @@
-/**
- * @fileoverview Hook Manager - 统一管理 Component 的 Hook
- * 
- * 提供：
- * - Hook 注册和管理
- * - 按优先级排序执行
- * - 错误隔离
- * - 动态添加/移除
- * - 干预机制（executeWithIntervention）
- */
-
-import type { Hook, HookContext, HookPhase, HookResult } from "./types";
-
-/**
- * HookManager 配置
- */
-export interface HookManagerOptions {
-  /** 组件名称（用于上下文） */
-  componentName?: string;
-  /** 组件版本（用于上下文） */
-  componentVersion?: string;
-  /** 默认优先级 */
-  defaultPriority?: number;
-}
-
-/**
- * HookManager
- * 
- * 统一管理 Component 的 Hook
- * 
- * @example
- * ```typescript
- * const manager = new HookManager<MyContext>();
- * 
- * // 注册 Hook
- * manager.register("before-action", {
- *   name: "my-hook",
- *   priority: 10,
- *   execute: async (ctx) => { /* ... *\/ }
- * });
- * 
- * // 执行 Hooks
- * await manager.execute("before-action", data);
- * ```
- */
-export class HookManager<T = unknown> {
-  private _hooks: Map<string, Hook<T>[]> = new Map();
-  private componentName: string;
-  private componentVersion: string;
-  private defaultPriority: number;
-
-  constructor(options: HookManagerOptions = {}) {
-    this.componentName = options.componentName ?? "unknown";
-    this.componentVersion = options.componentVersion ?? "0.0.0";
-    this.defaultPriority = options.defaultPriority ?? 0;
-  }
-
-  /**
-   * 注册 Hook 到指定 hook 点
-   */
-  register(hookPoint: string, hook: Hook<T>): void {
-    const hooks = this.getOrCreateHooks(hookPoint);
-    hooks.push(hook);
-  }
-
-  /**
-   * 注册多个 Hook
-   */
-  registerMany(hookPoint: string, hooks: Hook<T>[]): void {
-    const hookList = this.getOrCreateHooks(hookPoint);
-    hookList.push(...hooks);
-  }
-
-  /**
-   * 按名称取消注册 Hook
-   * @returns 是否成功取消注册
-   */
-  unregister(hookPoint: string, name: string): boolean {
-    const hooks = this._hooks.get(hookPoint);
-    if (!hooks) return false;
-
-    const index = hooks.findIndex((h) => h.name === name);
-    if (index === -1) return false;
-
-    hooks.splice(index, 1);
-    return true;
-  }
-
-  /**
-   * 取消注册所有指定 hook 点的 Hook
-   */
-  unregisterAll(hookPoint: string): void {
-    this._hooks.delete(hookPoint);
-  }
-
-  /**
-   * 执行指定 hook 点的所有 Hook
-   */
-  async execute(
-    hookPoint: string,
-    data: T,
-    metadata: Record<string, unknown> = {}
-  ): Promise<void> {
-    const hooks = this._hooks.get(hookPoint);
-    if (!hooks || hooks.length === 0) return;
-
-    const sortedHooks = this.sortHooks(hooks);
-    const ctx = this.createContext(hookPoint, data, metadata, "before");
-
-    for (const hook of sortedHooks) {
-      await this.safeExecute(hook, ctx);
-    }
-  }
-
-  /**
-   * 执行指定 hook 点的所有 Hook 并收集返回值
-   */
-  async executeAndCollect<R>(
-    hookPoint: string,
-    data: T,
-    metadata: Record<string, unknown> = {}
-  ): Promise<R[]> {
-    const hooks = this._hooks.get(hookPoint);
-    if (!hooks || hooks.length === 0) return [];
-
-    const sortedHooks = this.sortHooks(hooks);
-    const ctx = this.createContext(hookPoint, data, metadata, "before");
-    const results: R[] = [];
-
-    for (const hook of sortedHooks) {
-      const result = await this.safeExecuteAndReturn(hook, ctx);
-      if (result !== undefined) {
-        results.push(result as R);
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * 获取指定 hook 点的 Hook 数量
-   */
-  count(hookPoint: string): number {
-    return this._hooks.get(hookPoint)?.length ?? 0;
-  }
-
-  /**
-   * 清空所有 Hook
-   */
-  clear(): void {
-    this._hooks.clear();
-  }
-
-  /**
-   * 获取所有已注册的 hook 点
-   */
-  getHookPoints(): string[] {
-    return Array.from(this._hooks.keys());
-  }
-
-  /**
-   * 检查 hook 点是否有任何 Hook
-   */
-  hasHooks(hookPoint: string): boolean {
-    return this.count(hookPoint) > 0;
-  }
-
-  /**
-   * 设置组件信息
-   */
-  setComponentInfo(name: string, version: string): void {
-    this.componentName = name;
-    this.componentVersion = version;
-  }
-
-  /**
-   * 获取所有注册的 hooks（只读副本）
-   */
-  get hooks(): ReadonlyMap<string, Hook<T>[]> {
-    return this._hooks;
-  }
-
-  // ========================================================================
-  // 干预机制
-  // ========================================================================
-
-  /**
-   * 执行 Hook 并支持干预机制
-   * 
-   * 如果任何一个 Hook 返回 { stop: true }，执行会停止
-   * Hook 可以通过返回 HookResult 来执行干预动作
-   * 
-   * @param hookPoint Hook 点
-   * @param data 数据
-   * @param metadata 元数据
-   * @returns 执行结果
-   */
-  async executeWithIntervention(
-    hookPoint: string,
-    data: T,
-    metadata: Record<string, unknown> = {}
-  ): Promise<HookResult> {
-    const hooks = this._hooks.get(hookPoint);
-    if (!hooks || hooks.length === 0) {
-      return { stopped: false, results: [] };
-    }
-
-    const sortedHooks = this.sortHooks(hooks);
-    const ctx = this.createContext(hookPoint, data, metadata, "before");
-    const results: unknown[] = [];
-    let stopped = false;
-    let action: HookResult["action"];
-
-    for (const hook of sortedHooks) {
-      if (stopped) break;
-
-      const result = await this.safeExecuteAndReturn(hook, ctx);
-      results.push(result);
-
-      // 检查是否需要干预
-      if (result && typeof result === "object" && "stopped" in result) {
-        const hookResult = result as HookResult;
-        if (hookResult.stopped) {
-          stopped = true;
-          action = hookResult.action;
-        }
-      }
-    }
-
-    return { stopped, action, results };
-  }
-
-  // ========================================================================
-  // 私有方法
-  // ========================================================================
-
-  /**
-   * 获取或创建 hook 列表
-   */
-  private getOrCreateHooks(hookPoint: string): Hook<T>[] {
-    let hooks = this._hooks.get(hookPoint);
-    if (!hooks) {
-      hooks = [];
-      this._hooks.set(hookPoint, hooks);
-    }
-    return hooks;
-  }
-
-  /**
-   * 按优先级排序 Hook
-   * 
-   * 优先级相同时保持原顺序（稳定排序）
-   */
-  private sortHooks(hooks: Hook<T>[]): Hook<T>[] {
-    return [...hooks].sort((a, b) => {
-      const priorityA = a.priority ?? this.defaultPriority;
-      const priorityB = b.priority ?? this.defaultPriority;
-      return priorityA - priorityB;
-    });
-  }
-
-  /**
-   * 创建 Hook 上下文
-   */
-  private createContext(
-    hookPoint: string,
-    data: T,
-    metadata: Record<string, unknown>,
-    phase: HookPhase
-  ): HookContext<T> {
-    return {
-      component: {
-        name: this.componentName,
-        version: this.componentVersion,
-      },
-      data,
-      metadata,
-      phase,
-      hookPoint,
-    };
-  }
-
-  /**
-   * 安全执行 Hook（错误隔离）
-   */
-  private async safeExecute(hook: Hook<T>, ctx: HookContext<T>): Promise<void> {
-    try {
-      await hook.execute(ctx);
-    } catch (error) {
-      // 记录错误但不中断执行
-      console.error(`Hook "${hook.name}" failed:`, error);
-    }
-  }
-
-  /**
-   * 安全执行 Hook 并返回结果
-   */
-  private async safeExecuteAndReturn<R>(
-    hook: Hook<T>,
-    ctx: HookContext<T>
-  ): Promise<R | undefined> {
-    try {
-      return await (hook.execute(ctx) as Promise<R>);
-    } catch (error) {
-      console.error(`Hook "${hook.name}" failed:`, error);
-      return undefined;
-    }
-  }
-}