@dommaker/harness 0.13.0 → 0.13.2

package/src/tools/definitions/std/verification/wait-condition.yml

@@ -0,0 +1,107 @@
+# wait-condition.yml - 条件等待
+# ============================================================================
+# 能力类型: verification（工具型）
+# 来源: Superpowers - condition-based-waiting (Technique)
+# 版本: 2026-03-28 (需手动同步)
+# 执行方式: 纯脚本，轮询检查条件
+# 用途: 等待某个条件满足后再继续执行
+# ============================================================================
+
+name: wait-condition
+stage: verify
+description: 等待条件满足后再继续执行，支持轮询检查
+
+input:
+  condition:
+    type: string
+    required: true
+    description: "等待的条件（如 file exists: /path/to/file）"
+    
+  check_command:
+    type: string
+    required: true
+    description: "检查命令（返回 0 表示条件满足）"
+    
+  timeout_seconds:
+    type: number
+    required: false
+    description: 超时时间（秒）
+    default: 300
+    
+  interval_seconds:
+    type: number
+    required: false
+    description: 检查间隔（秒）
+    default: 5
+    
+  repo_path:
+    type: path
+    required: false
+    description: 项目路径（可选）
+    default: "."
+
+output:
+  satisfied:
+    type: boolean
+    description: 条件是否满足
+    
+  elapsed_seconds:
+    type: number
+    description: 已等待时间（秒）
+    
+  check_count:
+    type: number
+    description: 检查次数
+
+script: |
+  #!/bin/bash
+  set -euo pipefail
+  
+  CONDITION="{{condition}}"
+  CHECK_CMD="{{check_command}}"
+  TIMEOUT="{{timeout_seconds}}"
+  INTERVAL="{{interval_seconds}}"
+  REPO_PATH="{{repo_path}}"
+  
+  cd "$REPO_PATH" 2>/dev/null || true
+  
+  echo "⏳ 等待条件满足"
+  echo "  条件: $CONDITION"
+  echo "  检查命令: $CHECK_CMD"
+  echo "  超时: ${TIMEOUT}s"
+  echo "  间隔: ${INTERVAL}s"
+  echo ""
+  
+  ELAPSED=0
+  CHECK_COUNT=0
+  
+  while [ $ELAPSED -lt $TIMEOUT ]; do
+    CHECK_COUNT=$((CHECK_COUNT + 1))
+    
+    echo "[$CHECK_COUNT] 检查条件... (已等待 ${ELAPSED}s)"
+    
+    if eval "$CHECK_CMD" >/dev/null 2>&1; then
+      echo ""
+      echo "✅ 条件满足！"
+      echo "  已等待: ${ELAPSED}s"
+      echo "  检查次数: $CHECK_COUNT"
+      echo ""
+      echo "SATISFIED=true"
+      echo "ELAPSED=$ELAPSED"
+      echo "CHECK_COUNT=$CHECK_COUNT"
+      exit 0
+    fi
+    
+    sleep $INTERVAL
+    ELAPSED=$((ELAPSED + INTERVAL))
+  done
+  
+  echo ""
+  echo "❌ 条件未满足，已超时"
+  echo "  已等待: ${ELAPSED}s"
+  echo "  检查次数: $CHECK_COUNT"
+  echo ""
+  echo "SATISFIED=false"
+  echo "ELAPSED=$ELAPSED"
+  echo "CHECK_COUNT=$CHECK_COUNT"
+  exit 1

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './registry';
+export * from './core';
+export * from './loader';
+export * from './paths';

package/src/tools/loader.ts

@@ -0,0 +1,216 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { ToolDefinition, ToolCategory } from './types';
+
+// Maps the type strings found in tool YAMLs to JSON Schema types
+const TYPE_MAP: Record<string, string> = {
+  string: 'string',
+  path: 'string',
+  integer: 'integer',
+  number: 'number',
+  boolean: 'boolean',
+  array: 'array',
+  object: 'object',
+};
+
+interface RawToolYaml {
+  id?: string;
+  name?: string;
+  description?: string;
+  category?: string;
+  stage?: string;
+  input?: Record<string, {
+    type?: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    items?: unknown;
+    enum?: unknown[];
+  }>;
+  inputs?: Array<{
+    name: string;
+    type?: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+  }> | Record<string, {
+    type?: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+  }>;
+  output?: unknown;
+  outputs?: unknown;
+  script?: string;
+  prompt?: string;
+  agent?: string;
+  tools?: unknown;
+  execute?: unknown;
+  handler?: string;
+  temperature?: number;
+  timeout?: number;
+}
+
+function buildJsonSchema(params: Record<string, { type?: string; required?: boolean; description?: string; default?: unknown; items?: unknown; enum?: unknown[] }>): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const [key, def] of Object.entries(params)) {
+    const prop: Record<string, unknown> = {};
+    const schemaType = TYPE_MAP[def.type ?? 'string'] ?? 'string';
+    prop.type = schemaType;
+    if (def.description) prop.description = def.description;
+    if (def.default !== undefined) prop.default = def.default;
+    if (def.items) prop.items = def.items;
+    if (def.enum) prop.enum = def.enum;
+    properties[key] = prop;
+    if (def.required) required.push(key);
+  }
+
+  const schema: Record<string, unknown> = {
+    type: 'object',
+    properties,
+  };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+function normalizeInputs(raw: RawToolYaml): Record<string, { type?: string; required?: boolean; description?: string; default?: unknown; items?: unknown; enum?: unknown[] }> {
+  // Pattern A: `input` is a map (core/ext tools)
+  if (raw.input && typeof raw.input === 'object' && !Array.isArray(raw.input)) {
+    return raw.input;
+  }
+
+  // Pattern B: `inputs` is a list (some std tools)
+  if (Array.isArray(raw.inputs)) {
+    const result: Record<string, { type?: string; required?: boolean; description?: string; default?: unknown }> = {};
+    for (const item of raw.inputs) {
+      if (item.name) {
+        result[item.name] = {
+          type: item.type,
+          required: item.required,
+          description: item.description,
+          default: item.default,
+        };
+      }
+    }
+    return result;
+  }
+
+  // Pattern C: `inputs` is a map (some std tools)
+  if (raw.inputs && typeof raw.inputs === 'object' && !Array.isArray(raw.inputs)) {
+    return raw.inputs as Record<string, { type?: string; required?: boolean; description?: string; default?: unknown }>;
+  }
+
+  return {};
+}
+
+function deriveToolId(filePath: string, definitionsDir: string): string {
+  // Convert file path to ID: definitions/std/quick/implement.yml → std/quick/implement
+  const relative = path.relative(definitionsDir, filePath);
+  const withoutExt = relative.replace(/\.yml$/, '').replace(/\.yaml$/, '');
+  return withoutExt;
+}
+
+function detectCategory(filePath: string, definitionsDir: string): ToolCategory {
+  const relative = path.relative(definitionsDir, filePath);
+  const topDir = relative.split(path.sep)[0];
+  if (topDir === 'core') return 'core';
+  if (topDir === 'ext') return 'ext';
+  return 'std';
+}
+
+/**
+ * Parse a single YAML file into a ToolDefinition.
+ */
+export function parseToolYaml(yamlContent: string, filePath: string, definitionsDir: string): ToolDefinition {
+  const raw = yaml.load(yamlContent) as RawToolYaml;
+
+  const id = raw.id || deriveToolId(filePath, definitionsDir);
+  const name = raw.name || id;
+  const description = raw.description || '';
+  const category = detectCategory(filePath, definitionsDir);
+  const params = normalizeInputs(raw);
+  const parameters = buildJsonSchema(params);
+
+  const def: ToolDefinition = {
+    id,
+    name,
+    description,
+    category,
+    parameters,
+  };
+
+  return def;
+}
+
+/**
+ * Scan a directory recursively for .yml/.yaml files and return all file paths.
+ */
+function findYamlFiles(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findYamlFiles(fullPath));
+    } else if (entry.isFile() && (entry.name.endsWith('.yml') || entry.name.endsWith('.yaml'))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Load all tool definitions from the definitions directory (core/, std/, ext/).
+ */
+export function loadToolsFromDir(definitionsDir: string): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+
+  for (const category of ['core', 'std', 'ext'] as ToolCategory[]) {
+    const categoryDir = path.join(definitionsDir, category);
+    const yamlFiles = findYamlFiles(categoryDir);
+
+    for (const filePath of yamlFiles) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const tool = parseToolYaml(content, filePath, definitionsDir);
+        tools.push(tool);
+      } catch (err) {
+        // Skip files that fail to parse
+        console.warn(`[harness] Failed to load tool YAML: ${filePath}`, err);
+      }
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Load the registry.json and fix absolute paths to relative (from definitions dir).
+ * Filters out workflow entries, keeping only tool entries.
+ */
+export function loadRegistry(registryPath: string): Array<{
+  name: string;
+  category: string;
+  type: string;
+  description: string;
+  path: string;
+}> {
+  const content = fs.readFileSync(registryPath, 'utf-8');
+  const registry = JSON.parse(content);
+  const definitionsDir = path.dirname(registryPath);
+
+  if (!Array.isArray(registry.tools)) return [];
+
+  return registry.tools
+    .filter((entry: { type?: string }) => entry.type === 'tool')
+    .map((entry: { name: string; category: string; type: string; description: string; path: string }) => ({
+      ...entry,
+      // Fix absolute paths to relative (from definitions dir); keep already-relative paths as-is
+      path: path.isAbsolute(entry.path) ? path.relative(definitionsDir, entry.path) : entry.path,
+    }));
+}

package/src/tools/paths.ts

@@ -0,0 +1,15 @@
+import * as path from 'path';
+
+/**
+ * Returns the absolute path to the bundled tool definitions directory.
+ */
+export function getToolsDir(): string {
+  return path.join(__dirname, 'definitions');
+}
+
+/**
+ * Returns the absolute path to the tool registry.json.
+ */
+export function getRegistryPath(): string {
+  return path.join(__dirname, 'definitions', 'registry.json');
+}

package/src/tools/registry.ts

@@ -0,0 +1,128 @@
+/**
+ * 工具注册表
+ *
+ * 工具注册/发现/执行
+ */
+
+import type { ToolDefinition, ToolCategory, ToolHandler, ToolResult } from './types';
+
+export class ToolRegistry {
+  private tools: Map<string, ToolDefinition>;
+
+  constructor() {
+    this.tools = new Map();
+  }
+
+  /**
+   * 注册工具
+   */
+  register(tool: ToolDefinition): void {
+    this.tools.set(tool.id, tool);
+  }
+
+  /**
+   * 批量注册
+   */
+  registerAll(tools: ToolDefinition[]): void {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+
+  /**
+   * 获取工具
+   */
+  get(id: string): ToolDefinition | undefined {
+    return this.tools.get(id);
+  }
+
+  /**
+   * 获取所有工具
+   */
+  getAll(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * 按分类获取
+   */
+  getByCategory(category: ToolCategory): ToolDefinition[] {
+    return this.getAll().filter(t => t.category === category);
+  }
+
+  /**
+   * 搜索工具（名称/描述模糊匹配）
+   */
+  search(query: string): ToolDefinition[] {
+    const lower = query.toLowerCase();
+    return this.getAll().filter(t =>
+      t.name.toLowerCase().includes(lower) ||
+      t.description.toLowerCase().includes(lower) ||
+      t.id.toLowerCase().includes(lower),
+    );
+  }
+
+  /**
+   * 执行工具
+   */
+  async execute(id: string, params: Record<string, unknown>): Promise<ToolResult> {
+    const tool = this.tools.get(id);
+    if (!tool) {
+      return {
+        success: false,
+        output: '',
+        error: `工具未找到: ${id}`,
+      };
+    }
+
+    if (!tool.handler) {
+      return {
+        success: false,
+        output: '',
+        error: `工具 ${id} 未注册处理函数`,
+      };
+    }
+
+    try {
+      return await tool.handler(params);
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `工具执行失败: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  /**
+   * 移除工具
+   */
+  remove(id: string): boolean {
+    return this.tools.delete(id);
+  }
+
+  /**
+   * 工具数量
+   */
+  size(): number {
+    return this.tools.size;
+  }
+
+  /**
+   * 检查工具是否存在
+   */
+  has(id: string): boolean {
+    return this.tools.has(id);
+  }
+
+  /**
+   * 导出为 tool definitions（用于 LLM function calling）
+   */
+  toToolDefinitions(): Array<{ name: string; description: string; parameters: Record<string, unknown> }> {
+    return this.getAll().map(t => ({
+      name: t.id,
+      description: t.description,
+      parameters: t.parameters,
+    }));
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,46 @@
+/**
+ * 工具注册表类型定义
+ */
+
+// ── 工具定义 ─────────────────────────────────────────────
+
+export type ToolCategory = 'core' | 'std' | 'ext';
+
+export interface ToolDefinition {
+  /** 工具唯一 ID */
+  id: string;
+  /** 工具名称 */
+  name: string;
+  /** 工具描述 */
+  description: string;
+  /** 工具分类 */
+  category: ToolCategory;
+  /** 参数 schema (JSON Schema) */
+  parameters: Record<string, unknown>;
+  /** 所需 sandbox 级别 */
+  sandboxLevel?: 1 | 2 | 3 | 4;
+  /** 是否需要确认 */
+  requiresConfirmation?: boolean;
+  /** 速率限制（每分钟） */
+  rateLimit?: number;
+  /** 工具处理函数 */
+  handler?: ToolHandler;
+}
+
+export type ToolHandler = (params: Record<string, unknown>) => Promise<ToolResult>;
+
+export interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// ── 注册表配置 ───────────────────────────────────────────
+
+export interface ToolRegistryConfig {
+  /** 自动注册核心工具 */
+  autoRegisterCore?: boolean;
+  /** 工具搜索路径 */
+  searchPaths?: string[];
+}

package/src/types/__tests__/types.test.ts

@@ -0,0 +1,86 @@
+/**
+ * src/types 模块导出覆盖测试
+ */
+
+import { describe, it, expect } from '@jest/globals';
+
+// 从 barrel index.ts 导入，覆盖 re-export 行
+import {
+  ConstraintViolationError,
+  IronLawViolationError,
+} from '..';
+
+// 从 iron-law.ts 导入，覆盖 value re-export
+import { IronLawViolationError as IronLawViolationErrorDirect } from '../iron-law';
+
+describe('types barrel exports', () => {
+  it('ConstraintViolationError 应该可从 index 导入', () => {
+    expect(ConstraintViolationError).toBeDefined();
+    expect(typeof ConstraintViolationError).toBe('function');
+  });
+
+  it('IronLawViolationError 应该可从 index 导入（向后兼容）', () => {
+    expect(IronLawViolationError).toBeDefined();
+    expect(IronLawViolationError.prototype).toBeInstanceOf(ConstraintViolationError);
+  });
+
+  it('IronLawViolationError 应该可从 iron-law.ts 直接导入', () => {
+    expect(IronLawViolationErrorDirect).toBeDefined();
+    expect(IronLawViolationErrorDirect).toBe(ConstraintViolationError);
+  });
+});
+
+describe('ConstraintViolationError', () => {
+  it('应该使用 result.message 作为错误消息', () => {
+    const error = new ConstraintViolationError({
+      id: 'test',
+      level: 'iron_law',
+      satisfied: false,
+      message: '测试违规消息',
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toBe('测试违规消息');
+    expect(error.name).toBe('ConstraintViolationError');
+    expect(error.result.id).toBe('test');
+  });
+
+  it('应该在 message 为空时使用默认消息', () => {
+    const error = new ConstraintViolationError({
+      id: 'test',
+      level: 'iron_law',
+      satisfied: false,
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toBe('Constraint violation');
+  });
+
+  it('应该在 message 为空字符串时使用默认消息', () => {
+    const error = new ConstraintViolationError({
+      id: 'test',
+      level: 'iron_law',
+      satisfied: false,
+      message: '',
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toBe('Constraint violation');
+  });
+});
+
+describe('IronLawViolationError', () => {
+  it('应该继承 ConstraintViolationError', () => {
+    const error = new IronLawViolationError({
+      id: 'test',
+      level: 'iron_law',
+      satisfied: false,
+      message: '铁律违规',
+      checkedAt: new Date(),
+    });
+
+    expect(error).toBeInstanceOf(ConstraintViolationError);
+    expect(error.name).toBe('IronLawViolationError');
+    expect(error.message).toBe('铁律违规');
+  });
+});