specops 0.2.5 → 0.3.2

package/.opencode/templates/codebase/testing.md

@@ -0,0 +1,480 @@
+# 测试模式模板
+
+`.planning/codebase/TESTING.md` 的模板 - 记录测试框架和模式。
+
+**用途：** 记录测试的编写和运行方式。为添加符合现有模式的测试提供指导。
+
+---
+
+## 文件模板
+
+```markdown
+# 测试模式
+
+**分析日期：** [YYYY-MM-DD]
+
+## 测试框架
+
+**运行器：**
+- [框架：例如 "Jest 29.x"、"Vitest 1.x"]
+- [配置：例如 "项目根目录的 jest.config.js"]
+
+**断言库：**
+- [库：例如 "内置 expect"、"chai"]
+- [匹配器：例如 "toBe, toEqual, toThrow"]
+
+**运行命令：**
+```bash
+[例如 "npm test" 或 "npm run test"]              # 运行所有测试
+[例如 "npm test -- --watch"]                     # 监听模式
+[例如 "npm test -- path/to/file.test.ts"]       # 单个文件
+[例如 "npm run test:coverage"]                   # 覆盖率报告
+```
+
+## 测试文件组织
+
+**位置：**
+- [模式：例如 "*.test.ts 与源文件并列"]
+- [替代方案：例如 "__tests__/ 目录" 或 "独立的 tests/ 目录树"]
+
+**命名：**
+- [单元测试：例如 "module-name.test.ts"]
+- [集成测试：例如 "feature-name.integration.test.ts"]
+- [端到端测试：例如 "user-flow.e2e.test.ts"]
+
+**结构：**
+```
+[展示实际目录模式，例如：
+src/
+  lib/
+    utils.ts
+    utils.test.ts
+  services/
+    user-service.ts
+    user-service.test.ts
+]
+```
+
+## 测试结构
+
+**套件组织：**
+```typescript
+[展示实际使用的模式，例如：
+
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    it('should handle success case', () => {
+      // 准备
+      // 执行
+      // 断言
+    });
+
+    it('should handle error case', () => {
+      // 测试代码
+    });
+  });
+});
+]
+```
+
+**模式：**
+- [初始化：例如 "使用 beforeEach 进行共享初始化，避免 beforeAll"]
+- [清理：例如 "使用 afterEach 清理，恢复 mock"]
+- [结构：例如 "要求使用 arrange/act/assert 模式"]
+
+## Mock
+
+**框架：**
+- [工具：例如 "Jest 内置 mock"、"Vitest vi"、"Sinon"]
+- [导入 mock：例如 "在文件顶部使用 vi.mock()"]
+
+**模式：**
+```typescript
+[展示实际 mock 模式，例如：
+
+// Mock 外部依赖
+vi.mock('./external-service', () => ({
+  fetchData: vi.fn()
+}));
+
+// 在测试中 mock
+const mockFetch = vi.mocked(fetchData);
+mockFetch.mockResolvedValue({ data: 'test' });
+]
+```
+
+**应该 Mock 的：**
+- [例如 "外部 API、文件系统、数据库"]
+- [例如 "时间/日期（使用 vi.useFakeTimers）"]
+- [例如 "网络请求（使用 mock fetch）"]
+
+**不应该 Mock 的：**
+- [例如 "纯函数、工具函数"]
+- [例如 "内部业务逻辑"]
+
+## 测试数据与工厂
+
+**测试数据：**
+```typescript
+[展示创建测试数据的模式，例如：
+
+// 工厂模式
+function createTestUser(overrides?: Partial<User>): User {
+  return {
+    id: 'test-id',
+    name: 'Test User',
+    email: 'test@example.com',
+    ...overrides
+  };
+}
+
+// 固定数据文件
+// tests/fixtures/users.ts
+export const mockUsers = [/* ... */];
+]
+```
+
+**位置：**
+- [例如 "tests/fixtures/ 存放共享固定数据"]
+- [例如 "工厂函数放在测试文件中或 tests/factories/"]
+
+## 覆盖率
+
+**要求：**
+- [目标：例如 "80% 行覆盖率"、"无特定目标"]
+- [执行：例如 "CI 在低于 80% 时阻断"、"覆盖率仅供参考"]
+
+**配置：**
+- [工具：例如 "通过 --coverage 标志使用内置覆盖率"]
+- [排除：例如 "排除 *.test.ts、配置文件"]
+
+**查看覆盖率：**
+```bash
+[例如 "npm run test:coverage"]
+[例如 "open coverage/index.html"]
+```
+
+## 测试类型
+
+**单元测试：**
+- [范围：例如 "隔离测试单个函数/类"]
+- [Mock：例如 "mock 所有外部依赖"]
+- [速度：例如 "每个测试必须在 1 秒内完成"]
+
+**集成测试：**
+- [范围：例如 "一起测试多个模块"]
+- [Mock：例如 "mock 外部服务，使用真实内部模块"]
+- [初始化：例如 "使用测试数据库，填充数据"]
+
+**端到端测试：**
+- [框架：例如 "使用 Playwright 进行端到端测试"]
+- [范围：例如 "测试完整用户流程"]
+- [位置：例如 "e2e/ 目录与单元测试分开"]
+
+## 常见模式
+
+**异步测试：**
+```typescript
+[展示模式，例如：
+
+it('should handle async operation', async () => {
+  const result = await asyncFunction();
+  expect(result).toBe('expected');
+});
+]
+```
+
+**错误测试：**
+```typescript
+[展示模式，例如：
+
+it('should throw on invalid input', () => {
+  expect(() => functionCall()).toThrow('error message');
+});
+
+// 异步错误
+it('should reject on failure', async () => {
+  await expect(asyncCall()).rejects.toThrow('error message');
+});
+]
+```
+
+**快照测试：**
+- [用法：例如 "仅用于 React 组件" 或 "未使用"]
+- [位置：例如 "__snapshots__/ 目录"]
+
+---
+
+*测试分析：[date]*
+*测试模式变更时更新*
+```
+
+<good_examples>
+```markdown
+# 测试模式
+
+**分析日期：** 2025-01-20
+
+## 测试框架
+
+**运行器：**
+- Vitest 1.0.4
+- 配置：项目根目录的 vitest.config.ts
+
+**断言库：**
+- Vitest 内置 expect
+- 匹配器：toBe, toEqual, toThrow, toMatchObject
+
+**运行命令：**
+```bash
+npm test                              # 运行所有测试
+npm test -- --watch                   # 监听模式
+npm test -- path/to/file.test.ts     # 单个文件
+npm run test:coverage                 # 覆盖率报告
+```
+
+## 测试文件组织
+
+**位置：**
+- *.test.ts 与源文件并列
+- 无独立 tests/ 目录
+
+**命名：**
+- unit-name.test.ts 用于所有测试
+- 文件名中不区分单元/集成测试
+
+**结构：**
+```
+src/
+  lib/
+    parser.ts
+    parser.test.ts
+  services/
+    install-service.ts
+    install-service.test.ts
+  bin/
+    install.ts
+    (无测试 - 通过 CLI 进行集成测试)
+```
+
+## 测试结构
+
+**套件组织：**
+```typescript
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    beforeEach(() => {
+      // 重置状态
+    });
+
+    it('should handle valid input', () => {
+      // 准备
+      const input = createTestInput();
+
+      // 执行
+      const result = functionName(input);
+
+      // 断言
+      expect(result).toEqual(expectedOutput);
+    });
+
+    it('should throw on invalid input', () => {
+      expect(() => functionName(null)).toThrow('Invalid input');
+    });
+  });
+});
+```
+
+**模式：**
+- 使用 beforeEach 进行每个测试的初始化，避免 beforeAll
+- 使用 afterEach 恢复 mock：vi.restoreAllMocks()
+- 复杂测试中使用显式的 arrange/act/assert 注释
+- 每个测试聚焦一个断言（但可以有多个 expect）
+
+## Mock
+
+**框架：**
+- Vitest 内置 mock（vi）
+- 通过 vi.mock() 在测试文件顶部进行模块 mock
+
+**模式：**
+```typescript
+import { vi } from 'vitest';
+import { externalFunction } from './external';
+
+// Mock 模块
+vi.mock('./external', () => ({
+  externalFunction: vi.fn()
+}));
+
+describe('test suite', () => {
+  it('mocks function', () => {
+    const mockFn = vi.mocked(externalFunction);
+    mockFn.mockReturnValue('mocked result');
+
+    // 使用 mock 函数的测试代码
+
+    expect(mockFn).toHaveBeenCalledWith('expected arg');
+  });
+});
+```
+
+**应该 Mock 的：**
+- 文件系统操作（fs-extra）
+- 子进程执行（child_process.exec）
+- 外部 API 调用
+- 环境变量（process.env）
+
+**不应该 Mock 的：**
+- 内部纯函数
+- 简单工具函数（字符串处理、数组辅助函数）
+- TypeScript 类型
+
+## 测试数据与工厂
+
+**测试数据：**
+```typescript
+// 测试文件中的工厂函数
+function createTestConfig(overrides?: Partial<Config>): Config {
+  return {
+    targetDir: '/tmp/test',
+    global: false,
+    ...overrides
+  };
+}
+
+// tests/fixtures/ 中的共享固定数据
+// tests/fixtures/sample-command.md
+export const sampleCommand = `---
+description: Test command
+---
+Content here`;
+```
+
+**位置：**
+- 工厂函数：在测试文件中靠近使用处定义
+- 共享固定数据：tests/fixtures/（用于多文件测试数据）
+- Mock 数据：简单时内联在测试中，复杂时使用工厂
+
+## 覆盖率
+
+**要求：**
+- 无强制覆盖率目标
+- 覆盖率仅供参考
+- 聚焦关键路径（解析器、服务逻辑）
+
+**配置：**
+- Vitest 通过 c8 提供覆盖率（内置）
+- 排除：*.test.ts、bin/install.ts、配置文件
+
+**查看覆盖率：**
+```bash
+npm run test:coverage
+open coverage/index.html
+```
+
+## 测试类型
+
+**单元测试：**
+- 隔离测试单个函数
+- Mock 所有外部依赖（fs、child_process）
+- 快速：每个测试 <100ms
+- 示例：parser.test.ts、validator.test.ts
+
+**集成测试：**
+- 一起测试多个模块
+- 仅 mock 外部边界（文件系统、进程）
+- 示例：install-service.test.ts（测试 service + parser）
+
+**端到端测试：**
+- 当前未使用
+- CLI 集成通过手动测试
+
+## 常见模式
+
+**异步测试：**
+```typescript
+it('should handle async operation', async () => {
+  const result = await asyncFunction();
+  expect(result).toBe('expected');
+});
+```
+
+**错误测试：**
+```typescript
+it('should throw on invalid input', () => {
+  expect(() => parse(null)).toThrow('Cannot parse null');
+});
+
+// 异步错误
+it('should reject on file not found', async () => {
+  await expect(readConfig('invalid.txt')).rejects.toThrow('ENOENT');
+});
+```
+
+**文件系统 Mock：**
+```typescript
+import { vi } from 'vitest';
+import * as fs from 'fs-extra';
+
+vi.mock('fs-extra');
+
+it('mocks file system', () => {
+  vi.mocked(fs.readFile).mockResolvedValue('file content');
+  // 测试代码
+});
+```
+
+**快照测试：**
+- 本代码库未使用
+- 优先使用显式断言以提高清晰度
+
+---
+
+*测试分析：2025-01-20*
+*测试模式变更时更新*
+```
+</good_examples>
+
+<guidelines>
+**TESTING.md 中应包含的内容：**
+- 测试框架和运行器配置
+- 测试文件位置和命名模式
+- 测试结构（describe/it、beforeEach 模式）
+- Mock 方法和示例
+- 固定数据/工厂模式
+- 覆盖率要求
+- 运行测试的命令
+- 实际代码中的常见测试模式
+
+**不应包含的内容：**
+- 具体测试用例（参考实际测试文件）
+- 技术选型（那是 STACK.md 的内容）
+- CI/CD 配置（那是部署文档的内容）
+
+**填写此模板时：**
+- 检查 package.json scripts 中的测试命令
+- 查找测试配置文件（jest.config.js、vitest.config.ts）
+- 阅读 3-5 个现有测试文件以识别模式
+- 查找 tests/ 或 test-utils/ 中的测试工具
+- 检查覆盖率配置
+- 记录实际使用的模式，而非理想模式
+
+**在阶段规划中的用途：**
+- 添加新功能时（编写匹配的测试）
+- 重构时（保持测试模式）
+- 修复 bug 时（添加回归测试）
+- 了解验证方法
+- 搭建测试基础设施
+
+**分析方法：**
+- 检查 package.json 中的测试框架和脚本
+- 阅读测试配置文件了解覆盖率、初始化设置
+- 检查测试文件组织方式（并列 vs 独立目录）
+- 审查 5 个测试文件了解模式（mock、结构、断言）
+- 查找测试工具、固定数据、工厂
+- 记录测试类型（单元、集成、端到端）
+- 记录运行测试的命令
+</guidelines>

package/.opencode/templates/context.md

@@ -0,0 +1,221 @@
+# 阶段上下文模板
+
+`.planning/phases/XX-name/{phase_num}-CONTEXT.md` 的模板，捕获阶段的实现决策。
+
+**用途:** 记录下游代理需要的决策。研究者用它了解要调查什么。规划者用它了解哪些选择已锁定、哪些可灵活处理。
+
+**关键原则:** 类别不是预定义的。它们从本阶段实际讨论的内容中涌现。CLI 阶段有 CLI 相关的部分，UI 阶段有 UI 相关的部分。
+
+**下游消费者:**
+- `specops-phase-researcher` — 读取决策以聚焦研究 (如 "卡片布局" → 研究卡片组件模式)
+- `specops-planner` — 读取决策以创建具体任务 (如 "无限滚动" → 任务包含虚拟化)
+
+---
+
+## 文件模板
+
+```markdown
+# 阶段 [X]: [名称] - 上下文
+
+**收集时间:** [日期]
+**状态:** 准备规划
+
+<domain>
+## 阶段边界
+
+[清晰说明本阶段交付什么 — 范围锚点。来自 ROADMAP.md，是固定的。讨论在此边界内澄清实现方式。]
+
+</domain>
+
+<decisions>
+## 实现决策
+
+### [讨论的领域 1]
+- [做出的具体决策]
+- [另一个决策（如适用）]
+
+### [讨论的领域 2]
+- [做出的具体决策]
+
+### [讨论的领域 3]
+- [做出的具体决策]
+
+### Claude 自行决定
+[用户明确说 "你来决定" 的领域 — Claude 在规划/实现时有灵活性]
+
+</decisions>
+
+<specifics>
+## 具体想法
+
+[讨论中的特定参考、示例或 "我想要像 X 那样" 的时刻。产品参考、具体行为、交互模式。]
+
+[如果没有: "无具体要求 — 接受标准方案"]
+
+</specifics>
+
+<deferred>
+## 延后的想法
+
+[讨论中出现但属于其他阶段的想法。记录在此以免丢失，但明确不在本阶段范围内。]
+
+[如果没有: "无 — 讨论保持在阶段范围内"]
+
+</deferred>
+
+---
+
+*阶段: XX-name*
+*上下文收集时间: [日期]*
+```
+
+<good_examples>
+
+**示例 1: 视觉功能 (帖子信息流)**
+
+```markdown
+# 阶段 3: 帖子信息流 - 上下文
+
+**收集时间:** 2025-01-20
+**状态:** 准备规划
+
+<domain>
+## 阶段边界
+
+展示关注用户的帖子，可滚动浏览。用户可以查看帖子和互动数据。创建帖子和互动是独立阶段。
+
+</domain>
+
+<decisions>
+## 实现决策
+
+### 布局风格
+- 卡片式布局，不是时间线或列表
+- 每张卡片显示: 作者头像、名称、时间戳、完整帖子内容、反应数
+- 卡片有微妙阴影、圆角 — 现代感
+
+### 加载行为
+- 无限滚动，不是分页
+- 移动端下拉刷新
+- 顶部新帖指示器 ("3 条新帖") 而非自动插入
+
+### 空状态
+- 友好的插图 + "关注一些人来看帖子吧"
+- 根据兴趣推荐 3-5 个账户关注
+
+### Claude 自行决定
+- 加载骨架屏设计
+- 精确的间距和排版
+- 错误状态处理
+
+</decisions>
+
+<specifics>
+## 具体想法
+
+- "我喜欢 Twitter 显示新帖指示器而不打断滚动位置的方式"
+- 卡片应该像 Linear 的 issue 卡片那样 — 干净，不杂乱
+
+</specifics>
+
+<deferred>
+## 延后的想法
+
+- 帖子评论 — 阶段 5
+- 帖子收藏 — 加入待办
+
+</deferred>
+
+---
+
+*阶段: 03-post-feed*
+*上下文收集时间: 2025-01-20*
+```
+
+**示例 2: CLI 工具 (数据库备份)**
+
+```markdown
+# 阶段 2: 备份命令 - 上下文
+
+**收集时间:** 2025-01-20
+**状态:** 准备规划
+
+<domain>
+## 阶段边界
+
+CLI 命令将数据库备份到本地文件或 S3。支持全量和增量备份。恢复命令是独立阶段。
+
+</domain>
+
+<decisions>
+## 实现决策
+
+### 输出格式
+- JSON 用于程序化使用，表格格式用于人类阅读
+- 默认表格，--json 标志切换 JSON
+- 详细模式 (-v) 显示进度，默认静默
+
+### 标志设计
+- 常用选项用短标志: -o (output), -v (verbose), -f (force)
+- 长标志保持清晰: --incremental, --compress, --encrypt
+- 必需: 数据库连接字符串 (位置参数或 --db)
+
+### 错误恢复
+- 网络失败重试 3 次，然后以清晰消息失败
+- --no-retry 标志快速失败
+- 失败时删除部分备份 (不留损坏文件)
+
+### Claude 自行决定
+- 精确的进度条实现
+- 压缩算法选择
+- 临时文件处理
+
+</decisions>
+
+<specifics>
+## 具体想法
+
+- "我想让它感觉像 pg_dump — 数据库人员熟悉的"
+- 应该能在 CI 管道中工作 (退出码，无交互提示)
+
+</specifics>
+
+<deferred>
+## 延后的想法
+
+- 定时备份 — 独立阶段
+- 备份轮换/保留 — 加入待办
+
+</deferred>
+
+---
+
+*阶段: 02-backup-command*
+*上下文收集时间: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**此模板为下游代理捕获决策。**
+
+输出应回答: "研究者需要调查什么？规划者的哪些选择已锁定？"
+
+**好的内容 (具体决策):**
+- "卡片式布局，不是时间线"
+- "网络失败重试 3 次，然后失败"
+- "按年分组，然后按月"
+- "JSON 用于程序化使用，表格用于人类"
+
+**差的内容 (太模糊):**
+- "应该感觉现代和干净"
+- "好的用户体验"
+- "快速和响应式"
+- "易于使用"
+
+**创建后:**
+- 文件位于阶段目录: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
+- `specops-phase-researcher` 使用决策聚焦调查
+- `specops-planner` 使用决策 + 研究创建可执行任务
+- 下游代理不应需要再次向用户询问已捕获的决策
+</guidelines>