@dommaker/harness 0.13.0 → 0.13.2

package/src/tools/__tests__/loader.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Tool YAML Loader 测试
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { parseToolYaml, loadToolsFromDir, loadRegistry } from '../loader';
+import { getToolsDir, getRegistryPath } from '../paths';
+
+const DEFINITIONS_DIR = path.resolve(__dirname, '..', 'definitions');
+
+describe('parseToolYaml', () => {
+  it('应该解析 Pattern A (input map) 的 YAML', () => {
+    const yaml = `
+name: file-read
+description: 读取文件内容
+input:
+  path:
+    type: path
+    required: true
+    description: 文件路径
+  encoding:
+    type: string
+    required: false
+    description: 文件编码
+    default: "utf-8"
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'core', 'file', 'read.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.id).toBe('core/file/read');
+    expect(tool.name).toBe('file-read');
+    expect(tool.description).toBe('读取文件内容');
+    expect(tool.category).toBe('core');
+    expect(tool.parameters).toEqual({
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '文件路径' },
+        encoding: { type: 'string', description: '文件编码', default: 'utf-8' },
+      },
+      required: ['path'],
+    });
+  });
+
+  it('应该解析 Pattern B (inputs list) 的 YAML', () => {
+    const yaml = `
+id: deploy/backend
+name: deploy-backend
+description: 后端部署
+category: deploy
+inputs:
+  - name: platform
+    type: string
+    default: "docker"
+    description: 部署平台
+  - name: env
+    type: string
+    required: true
+    description: 环境
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'std', 'deploy', 'deploy-backend.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.id).toBe('deploy/backend');
+    expect(tool.name).toBe('deploy-backend');
+    expect(tool.category).toBe('std');
+    expect(tool.parameters).toEqual({
+      type: 'object',
+      properties: {
+        platform: { type: 'string', description: '部署平台', default: 'docker' },
+        env: { type: 'string', description: '环境' },
+      },
+      required: ['env'],
+    });
+  });
+
+  it('应该解析 Pattern C (inputs map) 的 YAML', () => {
+    const yaml = `
+id: quick/implement
+name: 实现功能
+description: 快速实现功能
+category: quick
+inputs:
+  project_path:
+    type: string
+    description: 项目路径
+    required: true
+  analysis:
+    type: object
+    description: 分析结果
+    required: true
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'std', 'quick', 'implement.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.id).toBe('quick/implement');
+    expect(tool.category).toBe('std');
+    expect(tool.parameters).toEqual({
+      type: 'object',
+      properties: {
+        project_path: { type: 'string', description: '项目路径' },
+        analysis: { type: 'object', description: '分析结果' },
+      },
+      required: ['project_path', 'analysis'],
+    });
+  });
+
+  it('应该从文件路径推导 ID（无显式 id 时）', () => {
+    const yaml = `
+name: git-branch
+description: 创建并切换 Git 分支
+input:
+  branch_name:
+    type: string
+    required: true
+    description: 分支名称
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'core', 'git', 'branch.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.id).toBe('core/git/branch');
+  });
+
+  it('应该正确分类 ext 工具', () => {
+    const yaml = `
+name: browser-automate
+description: 浏览器自动化
+input:
+  url:
+    type: string
+    required: true
+    description: URL
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'ext', 'browser', 'browser-automate.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.category).toBe('ext');
+    expect(tool.id).toBe('ext/browser/browser-automate');
+  });
+
+  it('应该处理空 input 的工具', () => {
+    const yaml = `
+name: no-params
+description: 无参数工具
+`;
+    const filePath = path.join(DEFINITIONS_DIR, 'core', 'test.yml');
+    const tool = parseToolYaml(yaml, filePath, DEFINITIONS_DIR);
+
+    expect(tool.parameters).toEqual({
+      type: 'object',
+      properties: {},
+    });
+    expect((tool.parameters as Record<string, unknown>).required).toBeUndefined();
+  });
+});
+
+describe('loadToolsFromDir', () => {
+  let tools: ReturnType<typeof loadToolsFromDir>;
+
+  beforeAll(() => {
+    tools = loadToolsFromDir(DEFINITIONS_DIR);
+  });
+
+  it('应该加载所有 113 个工具', () => {
+    expect(tools.length).toBe(113);
+  });
+
+  it('应该包含 core、std、ext 三个分类', () => {
+    const categories = new Set(tools.map(t => t.category));
+    expect(categories).toEqual(new Set(['core', 'std', 'ext']));
+  });
+
+  it('应该有 core 工具 (22)', () => {
+    const coreTools = tools.filter(t => t.category === 'core');
+    expect(coreTools.length).toBe(22);
+  });
+
+  it('应该有 std 工具 (87)', () => {
+    const stdTools = tools.filter(t => t.category === 'std');
+    expect(stdTools.length).toBe(87);
+  });
+
+  it('应该有 ext 工具 (4)', () => {
+    const extTools = tools.filter(t => t.category === 'ext');
+    expect(extTools.length).toBe(4);
+  });
+
+  it('每个工具都应该有 id、name、description、category、parameters', () => {
+    for (const tool of tools) {
+      expect(tool.id).toBeTruthy();
+      expect(tool.name).toBeTruthy();
+      expect(typeof tool.description).toBe('string');
+      expect(['core', 'std', 'ext']).toContain(tool.category);
+      expect(tool.parameters).toBeDefined();
+      expect(tool.parameters.type).toBe('object');
+    }
+  });
+
+  it('所有工具 ID 应该唯一', () => {
+    const ids = tools.map(t => t.id);
+    const uniqueIds = new Set(ids);
+    expect(uniqueIds.size).toBe(ids.length);
+  });
+});
+
+describe('loadRegistry', () => {
+  let registry: ReturnType<typeof loadRegistry>;
+
+  beforeAll(() => {
+    const registryPath = path.join(DEFINITIONS_DIR, 'registry.json');
+    registry = loadRegistry(registryPath);
+  });
+
+  it('应该加载 113 个工具条目', () => {
+    expect(registry.length).toBe(113);
+  });
+
+  it('所有条目 type 应该是 tool', () => {
+    for (const entry of registry) {
+      expect(entry.type).toBe('tool');
+    }
+  });
+
+  it('所有路径应该是相对路径', () => {
+    for (const entry of registry) {
+      expect(entry.path).not.toMatch(/^\//);
+      expect(entry.path).toMatch(/\.yml$/);
+    }
+  });
+
+  it('路径应该包含分类前缀 (core/ 或 std/ 或 ext/)', () => {
+    for (const entry of registry) {
+      expect(entry.path).toMatch(/^(core|std|ext)\//);
+    }
+  });
+});
+
+describe('paths', () => {
+  it('getToolsDir 应该返回 definitions 目录的绝对路径', () => {
+    const dir = getToolsDir();
+    expect(path.isAbsolute(dir)).toBe(true);
+    expect(dir).toMatch(/definitions$/);
+    expect(fs.existsSync(dir)).toBe(true);
+  });
+
+  it('getRegistryPath 应该返回 registry.json 的绝对路径', () => {
+    const p = getRegistryPath();
+    expect(path.isAbsolute(p)).toBe(true);
+    expect(p).toMatch(/registry\.json$/);
+    expect(fs.existsSync(p)).toBe(true);
+  });
+});

package/src/tools/__tests__/registry.test.ts

@@ -0,0 +1,157 @@
+/**
+ * ToolRegistry 测试
+ */
+
+import { ToolRegistry } from '../registry';
+import type { ToolDefinition } from '../types';
+
+function makeTool(overrides: Partial<ToolDefinition> = {}): ToolDefinition {
+  return {
+    id: `tool-${Math.random().toString(36).slice(2, 6)}`,
+    name: 'Test Tool',
+    description: 'A test tool',
+    category: 'core',
+    parameters: {},
+    ...overrides,
+  };
+}
+
+describe('ToolRegistry', () => {
+  let registry: ToolRegistry;
+
+  beforeEach(() => {
+    registry = new ToolRegistry();
+  });
+
+  describe('register / get', () => {
+    it('应该注册和获取工具', () => {
+      const tool = makeTool({ id: 'read-file' });
+      registry.register(tool);
+      expect(registry.get('read-file')).toBe(tool);
+    });
+
+    it('应该批量注册', () => {
+      const tools = [makeTool({ id: 'a' }), makeTool({ id: 'b' })];
+      registry.registerAll(tools);
+      expect(registry.size()).toBe(2);
+    });
+
+    it('应该返回 undefined 对于不存在的工具', () => {
+      expect(registry.get('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('getAll / getByCategory', () => {
+    it('应该获取所有工具', () => {
+      registry.register(makeTool({ id: 'a', category: 'core' }));
+      registry.register(makeTool({ id: 'b', category: 'std' }));
+      expect(registry.getAll().length).toBe(2);
+    });
+
+    it('应该按分类过滤', () => {
+      registry.register(makeTool({ id: 'a', category: 'core' }));
+      registry.register(makeTool({ id: 'b', category: 'std' }));
+      registry.register(makeTool({ id: 'c', category: 'core' }));
+
+      const core = registry.getByCategory('core');
+      expect(core.length).toBe(2);
+      expect(core.every(t => t.category === 'core')).toBe(true);
+    });
+  });
+
+  describe('search', () => {
+    it('应该按名称搜索', () => {
+      registry.register(makeTool({ id: 'read-file', name: 'Read File' }));
+      registry.register(makeTool({ id: 'write-file', name: 'Write File' }));
+
+      const results = registry.search('read');
+      expect(results.length).toBe(1);
+      expect(results[0].id).toBe('read-file');
+    });
+
+    it('应该按描述搜索', () => {
+      registry.register(makeTool({ id: 'a', name: 'A', description: 'Reads file contents' }));
+      registry.register(makeTool({ id: 'b', name: 'B', description: 'Writes data' }));
+
+      const results = registry.search('contents');
+      expect(results.length).toBe(1);
+    });
+
+    it('应该按 ID 搜索', () => {
+      registry.register(makeTool({ id: 'git-commit', name: 'Commit' }));
+      const results = registry.search('git');
+      expect(results.length).toBe(1);
+    });
+  });
+
+  describe('execute', () => {
+    it('应该执行工具', async () => {
+      registry.register(makeTool({
+        id: 'echo',
+        handler: async (params) => ({
+          success: true,
+          output: `echo: ${params.text}`,
+        }),
+      }));
+
+      const result = await registry.execute('echo', { text: 'hello' });
+      expect(result.success).toBe(true);
+      expect(result.output).toBe('echo: hello');
+    });
+
+    it('应该处理不存在的工具', async () => {
+      const result = await registry.execute('nonexistent', {});
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('未找到');
+    });
+
+    it('应该处理未注册 handler 的工具', async () => {
+      registry.register(makeTool({ id: 'no-handler' }));
+      const result = await registry.execute('no-handler', {});
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('未注册处理函数');
+    });
+
+    it('应该处理 handler 抛出异常', async () => {
+      registry.register(makeTool({
+        id: 'throw',
+        handler: async () => { throw new Error('boom'); },
+      }));
+
+      const result = await registry.execute('throw', {});
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('boom');
+    });
+  });
+
+  describe('remove / has / size', () => {
+    it('应该移除工具', () => {
+      registry.register(makeTool({ id: 'temp' }));
+      expect(registry.has('temp')).toBe(true);
+      expect(registry.remove('temp')).toBe(true);
+      expect(registry.has('temp')).toBe(false);
+    });
+
+    it('应该返回正确的 size', () => {
+      expect(registry.size()).toBe(0);
+      registry.register(makeTool({ id: 'a' }));
+      expect(registry.size()).toBe(1);
+    });
+  });
+
+  describe('toToolDefinitions', () => {
+    it('应该导出为 LLM tool definitions', () => {
+      registry.register(makeTool({
+        id: 'read',
+        name: 'Read',
+        description: 'Read a file',
+        parameters: { path: { type: 'string' } },
+      }));
+
+      const defs = registry.toToolDefinitions();
+      expect(defs.length).toBe(1);
+      expect(defs[0].name).toBe('read');
+      expect(defs[0].description).toBe('Read a file');
+    });
+  });
+});

package/src/tools/core/__tests__/core.test.ts

@@ -0,0 +1,122 @@
+import { CORE_TOOLS, FILE_TOOLS, GIT_TOOLS, NPM_TOOLS, SHELL_TOOLS } from '../index';
+
+describe('CORE_TOOLS', () => {
+  describe('FILE_TOOLS', () => {
+    it('包含 4 个文件工具', () => {
+      expect(FILE_TOOLS).toHaveLength(4);
+    });
+
+    it('包含 read_file', () => {
+      const tool = FILE_TOOLS.find(t => t.id === 'read_file');
+      expect(tool).toBeDefined();
+      expect(tool!.sandboxLevel).toBe(1);
+      expect(tool!.parameters.required).toContain('path');
+    });
+
+    it('包含 write_file', () => {
+      const tool = FILE_TOOLS.find(t => t.id === 'write_file');
+      expect(tool).toBeDefined();
+      expect(tool!.sandboxLevel).toBe(3);
+      expect(tool!.parameters.required).toContain('path');
+      expect(tool!.parameters.required).toContain('content');
+    });
+
+    it('包含 edit_file', () => {
+      const tool = FILE_TOOLS.find(t => t.id === 'edit_file');
+      expect(tool).toBeDefined();
+      expect(tool!.sandboxLevel).toBe(3);
+    });
+
+    it('包含 list_directory', () => {
+      const tool = FILE_TOOLS.find(t => t.id === 'list_directory');
+      expect(tool).toBeDefined();
+      expect(tool!.sandboxLevel).toBe(1);
+    });
+  });
+
+  describe('GIT_TOOLS', () => {
+    it('包含 4 个 git 工具', () => {
+      expect(GIT_TOOLS).toHaveLength(4);
+    });
+
+    it('git_commit 需要确认', () => {
+      const tool = GIT_TOOLS.find(t => t.id === 'git_commit');
+      expect(tool).toBeDefined();
+      expect(tool!.requiresConfirmation).toBe(true);
+      expect(tool!.sandboxLevel).toBe(3);
+    });
+
+    it('只读 git 工具 sandbox level 1', () => {
+      const status = GIT_TOOLS.find(t => t.id === 'git_status');
+      const diff = GIT_TOOLS.find(t => t.id === 'git_diff');
+      const log = GIT_TOOLS.find(t => t.id === 'git_log');
+      expect(status!.sandboxLevel).toBe(1);
+      expect(diff!.sandboxLevel).toBe(1);
+      expect(log!.sandboxLevel).toBe(1);
+    });
+  });
+
+  describe('NPM_TOOLS', () => {
+    it('包含 3 个 npm 工具', () => {
+      expect(NPM_TOOLS).toHaveLength(3);
+    });
+
+    it('npm_install 有速率限制', () => {
+      const tool = NPM_TOOLS.find(t => t.id === 'npm_install');
+      expect(tool).toBeDefined();
+      expect(tool!.rateLimit).toBe(10);
+    });
+
+    it('npm_test 有 sandbox level 3', () => {
+      const tool = NPM_TOOLS.find(t => t.id === 'npm_test');
+      expect(tool).toBeDefined();
+      expect(tool!.sandboxLevel).toBe(3);
+    });
+  });
+
+  describe('SHELL_TOOLS', () => {
+    it('包含 1 个 shell 工具', () => {
+      expect(SHELL_TOOLS).toHaveLength(1);
+    });
+
+    it('shell_exec 有速率限制', () => {
+      const tool = SHELL_TOOLS[0];
+      expect(tool.id).toBe('shell_exec');
+      expect(tool.rateLimit).toBe(30);
+      expect(tool.sandboxLevel).toBe(3);
+    });
+  });
+
+  describe('CORE_TOOLS 汇总', () => {
+    it('包含所有子工具', () => {
+      expect(CORE_TOOLS).toHaveLength(FILE_TOOLS.length + GIT_TOOLS.length + NPM_TOOLS.length + SHELL_TOOLS.length);
+    });
+
+    it('所有工具都有 category: core', () => {
+      for (const tool of CORE_TOOLS) {
+        expect(tool.category).toBe('core');
+      }
+    });
+
+    it('所有工具都有 id、name、description', () => {
+      for (const tool of CORE_TOOLS) {
+        expect(tool.id).toBeTruthy();
+        expect(tool.name).toBeTruthy();
+        expect(tool.description).toBeTruthy();
+      }
+    });
+
+    it('所有工具都有 parameters', () => {
+      for (const tool of CORE_TOOLS) {
+        expect(tool.parameters).toBeDefined();
+        expect(tool.parameters.type).toBe('object');
+      }
+    });
+
+    it('所有工具都有 sandboxLevel', () => {
+      for (const tool of CORE_TOOLS) {
+        expect([1, 2, 3, 4]).toContain(tool.sandboxLevel);
+      }
+    });
+  });
+});