@dommaker/harness 1.8.0 → 1.9.0

package/src/hooks/registry.ts

@@ -1,166 +0,0 @@
-/**
- * HookRegistry — hook 注册/注销/查询
- *
- * 纯簿记，无执行逻辑。线程不安全（Node.js 单线程）。
- */
-
-import type { EffectiveHook, HookConfig, HookDefinition, HookPhase } from './types';
-
-/**
- * 注册表闭环双向校验（H5，复制 checker 闭环模式）
- *
- * 声明（HookConfig，consumer 的 per-hook 配置表）↔ 实现（注册的
- * HookDefinition）加载期双向校验，任一不满足即抛错，拒绝静默缺失：
- * - 引用未注册 → 抛错（声明了配置但没有注册实现 = 死配置）
- * - 注册无定义 → 抛错（注册了实现但没有配置声明 = 死代码）
- * - 重复声明 / 重复注册 → 抛错
- *
- * 断言限构建/测试期调用（harness 无内置 hook 定义，加载期闭环由
- * consumer 在其注册点/测试中调用本函数），不进入运行时热路径，
- * 不破坏 --help/--version 懒加载。消灭「hook 定义不注册 = 死代码」
- * 类 prompt 规矩（studio 侧随动）。
- *
- * @throws 任一方向不满足时抛错
- */
-export function assertHookRegistryClosed<C = unknown, R = unknown>(
-  configs: readonly HookConfig[],
-  hooks: readonly HookDefinition<C, R>[]
-): void {
-  const configNames = new Set<string>();
-  for (const config of configs) {
-    if (configNames.has(config.name)) {
-      throw new Error(
-        `[harness] hook 注册表闭环校验失败：hook 配置 "${config.name}" 重复声明。`
-      );
-    }
-    configNames.add(config.name);
-  }
-
-  const hookNames = new Set<string>();
-  for (const hook of hooks) {
-    if (hookNames.has(hook.name)) {
-      throw new Error(
-        `[harness] hook 注册表闭环校验失败：hook "${hook.name}" 重复注册。`
-      );
-    }
-    hookNames.add(hook.name);
-  }
-
-  for (const config of configs) {
-    if (!hookNames.has(config.name)) {
-      throw new Error(
-        `[harness] hook 注册表闭环校验失败：hook 配置 "${config.name}" 引用的实现未注册。` +
-        `请注册同名 HookDefinition，或删除该配置声明。`
-      );
-    }
-  }
-
-  for (const hook of hooks) {
-    if (!configNames.has(hook.name)) {
-      throw new Error(
-        `[harness] hook 注册表闭环校验失败：hook "${hook.name}" 注册了实现但没有对应配置声明。` +
-        `请补齐 HookConfig 声明，或移除该实现。`
-      );
-    }
-  }
-}
-
-export class HookRegistry<C = unknown, R = unknown> {
-  private hooks: Map<string, EffectiveHook<C, R>> = new Map();
-
-  /**
-   * 注册 hook（同名覆盖）
-   *
-   * 有效 `enabled` / `errorStrategy` 由 HookConfig 填充——配置表是这两个
-   * 语义的唯一声明点（#159），定义与配置名称不一致即抛错。
-   */
-  register(hook: HookDefinition<C, R>, config: HookConfig): void {
-    if (hook.name !== config.name) {
-      throw new Error(
-        `[harness] hook 注册失败：定义 "${hook.name}" 与配置 "${config.name}" 名称不一致。`
-      );
-    }
-    this.hooks.set(hook.name, {
-      ...hook,
-      enabled: config.enabled,
-      errorStrategy: config.errorStrategy,
-    });
-  }
-
-  /**
-   * 批量注册（按 name 配对配置；有实现缺配置声明即抛错）
-   */
-  registerAll(hooks: HookDefinition<C, R>[], configs: readonly HookConfig[]): void {
-    const configByName = new Map(configs.map(c => [c.name, c]));
-    for (const hook of hooks) {
-      const config = configByName.get(hook.name);
-      if (!config) {
-        throw new Error(
-          `[harness] hook 注册失败：hook "${hook.name}" 没有对应的 HookConfig 声明。`
-        );
-      }
-      this.register(hook, config);
-    }
-  }
-
-  /**
-   * 注销 hook
-   */
-  unregister(name: string): boolean {
-    return this.hooks.delete(name);
-  }
-
-  /**
-   * 获取单个 hook（含有效 enabled / errorStrategy）
-   */
-  get(name: string): EffectiveHook<C, R> | undefined {
-    return this.hooks.get(name);
-  }
-
-  /**
-   * 获取指定时机、已启用的 hook，按优先级排序
-   */
-  getEnabled(phase: HookPhase): EffectiveHook<C, R>[] {
-    return Array.from(this.hooks.values())
-      .filter(h => h.phase === phase && h.enabled)
-      .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
-  }
-
-  /**
-   * 列出所有 hook 名称
-   */
-  listNames(): string[] {
-    return Array.from(this.hooks.keys());
-  }
-
-  /**
-   * 列出所有 hook（含禁用）
-   */
-  listAll(): EffectiveHook<C, R>[] {
-    return Array.from(this.hooks.values());
-  }
-
-  /**
-   * 启用/禁用 hook
-   */
-  setEnabled(name: string, enabled: boolean): boolean {
-    const hook = this.hooks.get(name);
-    if (!hook) return false;
-    hook.enabled = enabled;
-    return true;
-  }
-
-  /**
-   * 清空所有 hook
-   */
-  clear(): void {
-    this.hooks.clear();
-  }
-
-  /**
-   * Hook 数量
-   */
-  get size(): number {
-    return this.hooks.size;
-  }
-}

package/src/hooks/types.ts

@@ -1,118 +0,0 @@
-/**
- * Hooks 类型定义
- *
- * 通用 hook 管线：注册、排序、错误隔离、采样。
- * 无业务逻辑，consumer 自行定义 hook 名称和语义。
- */
-
-/**
- * Hook 执行时机
- */
-export type HookPhase = 'before' | 'after' | 'around';
-
-/**
- * Hook 错误处理策略（有效集合：'block' | 'warn'）
- *
- * #159 起原 'ignore' 退出有效面：策略的唯一声明点是 HookConfig（必填），
- * 不存在「未声明 strategy」的运行时形态。
- */
-export type HookErrorStrategy = 'block' | 'warn';
-
-/**
- * Hook 配置（G7 归一后形状：consumer 侧的 per-hook 声明表）
- *
- * 声明与实现构成注册表闭环（assertHookRegistryClosed 双向校验）：
- * - 声明（HookConfig）是「定义」侧：引用未注册实现 → 抛错
- * - 注册（HookDefinition）是「实现」侧：注册无对应声明 → 抛错
- *
- * #159 起本表是 `enabled` / `errorStrategy` 的**唯一声明点**：
- * HookDefinition 不再携带这两个字段，有效值在注册环节由本表填充
- * （见 EffectiveHook），声明与实现两处值矛盾在构造上不可能出现。
- *
- * 对应 studio 侧 per-hook 运行时配置（hooks/config.ts 的 DEFAULTS）语义：
- * blocking:true ↔ errorStrategy 'block'（失败阻断管线），
- * blocking:false ↔ errorStrategy 'warn'（记录警告继续）——无损映射见
- * config.ts 的 toErrorStrategy。
- */
-export interface HookConfig {
-  /** Hook 唯一名称（须与注册的 HookDefinition.name 一致） */
-  name: string;
-  /** 是否启用（false 时不进入管线） */
-  enabled: boolean;
-  /** 错误策略：block=失败阻断管线，warn=记录警告继续 */
-  errorStrategy: HookErrorStrategy;
-}
-
-/**
- * Hook 定义
- *
- * Consumer 自行选择 name（如 'beforeAgentExecute'），harness 只提供管线。
- * `enabled` / `errorStrategy` 不在此处声明——唯一声明点是 HookConfig（#159）。
- */
-export interface HookDefinition<C = unknown, R = unknown> {
-  /** Hook 唯一名称（consumer 定义语义） */
-  name: string;
-  /** 执行时机 */
-  phase: HookPhase;
-  /** 优先级（越小越先执行，默认 100） */
-  priority?: number;
-  /** 采样率 0-1（1=100% 执行，0.1=10% 采样） */
-  sampleRate?: number;
-  /** Hook 执行函数 */
-  execute: (context: C) => Promise<HookResult<R>>;
-}
-
-/**
- * 有效 hook = HookDefinition + 注册环节由 HookConfig 填充的有效值
- *
- * 管线与注册表的判定（启用过滤、block/warn 分派）只读本类型，
- * 值来源单一（HookConfig），不存在第二声明点。
- */
-export interface EffectiveHook<C = unknown, R = unknown> extends HookDefinition<C, R> {
-  /** 是否启用（来自 HookConfig.enabled） */
-  enabled: boolean;
-  /** 错误策略（来自 HookConfig.errorStrategy） */
-  errorStrategy: HookErrorStrategy;
-}
-
-/**
- * Hook 执行结果
- */
-export interface HookResult<R = unknown> {
-  /** 是否通过（blocking hook 必须返回 false 才阻断） */
-  passed: boolean;
-  /** 结果数据 */
-  data?: R;
-  /** 错误信息 */
-  error?: string;
-  /** 元数据（consumer 自行定义） */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Hook 执行记录
- */
-export interface HookExecutionRecord {
-  hookName: string;
-  phase: HookPhase;
-  startedAt: number;
-  completedAt: number;
-  durationMs: number;
-  passed: boolean;
-  error?: string;
-  sampled?: boolean;
-}
-
-/**
- * 管线执行结果
- */
-export interface PipelineResult {
-  /** 是否全部通过（blocking hook 任一失败 = false） */
-  passed: boolean;
-  /** 各 hook 执行记录 */
-  records: HookExecutionRecord[];
-  /** 失败的 blocking hook 名称列表 */
-  blockedBy: string[];
-  /** 警告 hook 名称列表 */
-  warnings: string[];
-}