clawt 3.10.4 → 3.10.6

package/docs/superpowers/plans/2026-06-09-worktree-base-branch.md

@@ -0,0 +1,386 @@
+# Worktree Base Branch Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show each clawt worktree's creation-time base branch in `status`, `status -i`, and `list`.
+
+**Architecture:** Store per-worktree metadata under `~/.clawt/projects/<projectName>/worktrees/<branchName>.json` when worktrees are created. Enrich `WorktreeInfo` with `baseBranch` at the data layer so text, JSON, and interactive renderers share the same source.
+
+**Tech Stack:** TypeScript, Commander, Vitest, Node `fs`/`path`, existing clawt utilities.
+
+---
+
+## File Structure
+
+- Create: `src/utils/worktree-metadata.ts`
+  - Single responsibility: generate metadata paths, save metadata, load metadata, remove metadata.
+- Modify: `src/types/worktree.ts`
+  - Add `baseBranch: string | null` to `WorktreeInfo`.
+  - Add `WorktreeMetadata`.
+- Modify: `src/types/status.ts`
+  - Add `baseBranch: string | null` to `WorktreeDetailedStatus`.
+- Modify: `src/utils/worktree.ts`
+  - Capture current branch during creation, save metadata, read metadata when listing, remove metadata during cleanup.
+- Modify: `src/commands/list.ts`
+  - Include `baseBranch` in text and JSON output.
+- Modify: `src/commands/status.ts`
+  - Carry `baseBranch` into status data and render it in text output.
+- Modify: `src/utils/interactive-panel-render.ts`
+  - Render base branch line in `status -i`.
+- Test: `tests/unit/utils/worktree-metadata.test.ts`
+- Test: `tests/unit/utils/worktree.test.ts`
+- Test: `tests/unit/commands/list.test.ts`
+- Test: `tests/unit/commands/status.test.ts`
+- Test: `tests/unit/utils/interactive-panel.test.ts`
+
+### Task 1: Metadata Utility
+
+**Files:**
+- Create: `src/utils/worktree-metadata.ts`
+- Modify: `src/types/worktree.ts`
+- Test: `tests/unit/utils/worktree-metadata.test.ts`
+
+- [ ] **Step 1: Write failing metadata path and save/load tests**
+
+```ts
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  mkdirSync: vi.fn(),
+  readFileSync: vi.fn(),
+  rmSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}));
+
+vi.mock('../../../src/constants/index.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../../src/constants/index.js')>();
+  return {
+    ...actual,
+    PROJECTS_CONFIG_DIR: '/tmp/clawt-projects',
+  };
+});
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  getWorktreeMetadataPath,
+  loadWorktreeMetadata,
+  saveWorktreeMetadata,
+} from '../../../src/utils/worktree-metadata.js';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('worktree metadata', () => {
+  it('生成项目 worktree 元数据路径', () => {
+    expect(getWorktreeMetadataPath('demo', 'feature')).toBe('/tmp/clawt-projects/demo/worktrees/feature.json');
+  });
+
+  it('保存并读取来源分支元数据', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      branch: 'feature',
+      baseBranch: 'test',
+      createdAt: '2026-06-09T10:30:00.000Z',
+    }));
+
+    saveWorktreeMetadata('demo', {
+      branch: 'feature',
+      baseBranch: 'test',
+      createdAt: '2026-06-09T10:30:00.000Z',
+    });
+
+    expect(writeFileSync).toHaveBeenCalledWith(
+      '/tmp/clawt-projects/demo/worktrees/feature.json',
+      expect.stringContaining('"baseBranch": "test"'),
+      'utf-8',
+    );
+    expect(loadWorktreeMetadata('demo', 'feature')?.baseBranch).toBe('test');
+  });
+
+  it('元数据不存在时返回 null', () => {
+    vi.mocked(existsSync).mockReturnValue(false);
+    expect(loadWorktreeMetadata('demo', 'missing')).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm vitest run tests/unit/utils/worktree-metadata.test.ts`
+Expected: FAIL with module not found for `src/utils/worktree-metadata.js`.
+
+- [ ] **Step 3: Add types and metadata utility**
+
+```ts
+/** worktree 来源分支元数据 */
+export interface WorktreeMetadata {
+  /** worktree 分支名 */
+  branch: string;
+  /** 创建 worktree 时所在的真实当前分支 */
+  baseBranch: string;
+  /** 元数据创建时间 */
+  createdAt: string;
+}
+```
+
+Implement `getWorktreeMetadataPath(projectName, branchName)`, `saveWorktreeMetadata(projectName, metadata)`, `loadWorktreeMetadata(projectName, branchName)`, and `removeWorktreeMetadata(projectName, branchName)` with Chinese JSDoc comments. Use `safeStringify()` for writes and `ensureDir()` for directory creation.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm vitest run tests/unit/utils/worktree-metadata.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/utils/worktree-metadata.ts src/types/worktree.ts tests/unit/utils/worktree-metadata.test.ts
+git commit -m "feat: add worktree metadata storage"
+```
+
+### Task 2: Save And Load Base Branch In Worktree Data
+
+**Files:**
+- Modify: `src/utils/worktree.ts`
+- Modify: `src/utils/index.ts`
+- Test: `tests/unit/utils/worktree.test.ts`
+
+- [ ] **Step 1: Write failing worktree data tests**
+
+Add tests asserting:
+
+```ts
+it('创建 worktree 时记录当前分支为来源分支', () => {
+  mockedGetCurrentBranch.mockReturnValue('test');
+  const result = createWorktrees('feature', 1);
+  expect(result[0].baseBranch).toBe('test');
+  expect(saveWorktreeMetadata).toHaveBeenCalledWith('my-project', {
+    branch: 'feature',
+    baseBranch: 'test',
+    createdAt: expect.any(String),
+  });
+});
+
+it('获取 worktree 时读取来源分支', () => {
+  mockedLoadWorktreeMetadata.mockReturnValue({
+    branch: 'feature',
+    baseBranch: 'test',
+    createdAt: '2026-06-09T10:30:00.000Z',
+  });
+  const result = getProjectWorktrees();
+  expect(result[0].baseBranch).toBe('test');
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm vitest run tests/unit/utils/worktree.test.ts`
+Expected: FAIL because `baseBranch` is not returned and metadata functions are not called.
+
+- [ ] **Step 3: Implement worktree metadata integration**
+
+In `createWorktrees()` and `createWorktreesByBranches()`:
+
+```ts
+const projectName = getProjectName();
+const baseBranch = getCurrentBranch();
+```
+
+After each successful worktree creation, call `saveWorktreeMetadata(projectName, { branch: name, baseBranch, createdAt: new Date().toISOString() })` and return `{ path, branch, baseBranch }`.
+
+In `getProjectWorktrees()`, call `loadWorktreeMetadata(projectName, entry.name)` and return `baseBranch: metadata?.baseBranch ?? null`.
+
+In `cleanupWorktrees()`, call `removeWorktreeMetadata(projectName, wt.branch)` inside the existing per-worktree cleanup `try` block after validate branch deletion.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm vitest run tests/unit/utils/worktree.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/utils/worktree.ts src/utils/index.ts tests/unit/utils/worktree.test.ts
+git commit -m "feat: track worktree base branches"
+```
+
+### Task 3: Show Base Branch In List
+
+**Files:**
+- Modify: `src/commands/list.ts`
+- Test: `tests/unit/commands/list.test.ts`
+
+- [ ] **Step 1: Write failing list output tests**
+
+Add JSON assertion:
+
+```ts
+expect(parsed.worktrees[0].baseBranch).toBe('test');
+```
+
+Add text assertion:
+
+```ts
+expect(mockedPrintInfo).toHaveBeenCalledWith(expect.stringContaining('<- test'));
+```
+
+Add missing metadata assertion:
+
+```ts
+expect(mockedPrintInfo).toHaveBeenCalledWith(expect.stringContaining('未记录'));
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm vitest run tests/unit/commands/list.test.ts`
+Expected: FAIL because `baseBranch` is not printed or serialized.
+
+- [ ] **Step 3: Implement list JSON and text display**
+
+In JSON output include:
+
+```ts
+baseBranch: wt.baseBranch,
+```
+
+In text output build one display helper:
+
+```ts
+/**
+ * 格式化来源分支展示文本
+ * @param {string | null} baseBranch - 来源分支
+ * @returns {string} 来源分支展示文本
+ */
+function formatBaseBranchInline(baseBranch: string | null): string {
+  const fallback = getCurrentLanguage() === 'en' ? 'Not recorded' : '未记录';
+  return `<- ${baseBranch ?? fallback}`;
+}
+```
+
+Use it in the first worktree line after `[${wt.branch}]`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm vitest run tests/unit/commands/list.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/commands/list.ts tests/unit/commands/list.test.ts
+git commit -m "feat: show base branch in list"
+```
+
+### Task 4: Show Base Branch In Status And Interactive Panel
+
+**Files:**
+- Modify: `src/types/status.ts`
+- Modify: `src/commands/status.ts`
+- Modify: `src/utils/interactive-panel-render.ts`
+- Test: `tests/unit/commands/status.test.ts`
+- Test: `tests/unit/utils/interactive-panel.test.ts`
+
+- [ ] **Step 1: Write failing status tests**
+
+Add JSON assertion:
+
+```ts
+expect(parsed.worktrees[0].baseBranch).toBe('test');
+```
+
+Add text assertion:
+
+```ts
+expect(mockedPrintInfo).toHaveBeenCalledWith(expect.stringContaining('来源分支: test'));
+```
+
+Add interactive renderer assertion:
+
+```ts
+const lines = renderWorktreeBlock({
+  path: '/path/feature',
+  branch: 'feature',
+  baseBranch: 'test',
+  changeStatus: 'clean',
+  commitsAhead: 0,
+  commitsBehind: 0,
+  snapshotTime: null,
+  insertions: 0,
+  deletions: 0,
+  createdAt: null,
+}, false);
+expect(lines.join('\n')).toContain('来源分支: test');
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pnpm vitest run tests/unit/commands/status.test.ts tests/unit/utils/interactive-panel.test.ts`
+Expected: FAIL because status detail and renderer do not include `baseBranch`.
+
+- [ ] **Step 3: Carry and render baseBranch**
+
+In `collectWorktreeDetailedStatusAsync()`, add:
+
+```ts
+baseBranch: worktree.baseBranch,
+```
+
+In `printWorktreeItem()`, render:
+
+```ts
+printInfo(`    ${chalk.gray(formatBaseBranchLine(wt.baseBranch))}`);
+```
+
+In `renderWorktreeBlock()`, add the same line near the top after branch status or after diff line. Keep helper logic focused and documented with Chinese JSDoc.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pnpm vitest run tests/unit/commands/status.test.ts tests/unit/utils/interactive-panel.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/types/status.ts src/commands/status.ts src/utils/interactive-panel-render.ts tests/unit/commands/status.test.ts tests/unit/utils/interactive-panel.test.ts
+git commit -m "feat: show base branch in status"
+```
+
+### Task 5: Documentation And Full Verification
+
+**Files:**
+- Modify: `docs/create.md`
+- Modify: `docs/list.md`
+- Modify: `docs/status.md`
+
+- [ ] **Step 1: Update command docs**
+
+Document:
+
+```md
+创建 worktree 时，clawt 会记录创建瞬间所在的真实当前分支为来源分支，并保存到 `~/.clawt/projects/<projectName>/worktrees/<branchName>.json`。
+```
+
+Update `list` and `status` JSON examples to include `"baseBranch": "test"` and explain `null` means not recorded.
+
+- [ ] **Step 2: Run focused tests**
+
+Run: `pnpm vitest run tests/unit/utils/worktree-metadata.test.ts tests/unit/utils/worktree.test.ts tests/unit/commands/list.test.ts tests/unit/commands/status.test.ts tests/unit/utils/interactive-panel.test.ts`
+Expected: PASS.
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `pnpm test`
+Expected: PASS.
+
+- [ ] **Step 4: Run type check or build**
+
+Run: `pnpm build`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/create.md docs/list.md docs/status.md
+git commit -m "docs: document worktree base branch metadata"
+```

package/docs/superpowers/specs/2026-06-01-validate-ignored-files-conflict-design.md

@@ -0,0 +1,76 @@
+# validate 被忽略文件冲突检测 — 设计文档
+
+## 问题
+
+当目标分支跟踪了某些在 `.gitignore` 中的文件（如 AI Agent 用 `git add -f` 强制提交），validate 通过 `git apply` 将这些文件创建到主 worktree 工作目录后，`git clean -fd` 无法清理它们（因为被 `.gitignore` 忽略）。后续 validate 的 patch apply 因文件已存在而失败，且 sync 无法打破这个死循环。
+
+## 修复目标
+
+在 `migrateChangesViaPatch` 中，`git apply` 之前检测被 `.gitignore` 忽略且物理存在于主 worktree 工作目录的文件（"幽灵文件"），若检测到冲突则输出清晰的错误提示和可执行的清理命令，而非当前的误导性信息 "diverged too far from main"。
+
+## 验收标准
+
+1. 检测到幽灵文件时，输出文件列表和 `git clean -fdx <dir>` 清理命令
+2. 未检测到幽灵文件时，行为与当前完全一致（无回归）
+3. 提示信息为双语（中英）
+4. 有单元测试覆盖检测逻辑
+
+## 架构
+
+### 检测流程
+
+```
+migrateChangesViaPatch()
+  ├── gitDiffBinaryAgainstBranch()  → 获取 patch
+  ├── detectIgnoredFilesInPatch()   → 新增：检测幽灵文件
+  │     ├── git diff --name-only HEAD...branch  → 获取 patch 涉及的文件列表
+  │     ├── git check-ignore <files>            → 筛选被忽略的文件
+  │     └── fs.existsSync                       → 筛选物理存在的文件
+  ├── 有冲突 → printWarning + return { success: false }
+  └── 无冲突 → gitApplyFromStdin()  → 正常 apply
+```
+
+### 新增函数
+
+| 函数 | 文件 | 职责 |
+|------|------|------|
+| `gitCheckIgnored(paths, cwd)` | `src/utils/git-core.ts` | 批量检测文件是否被 `.gitignore` 忽略 |
+| `detectIgnoredFilesInPatch(branchName, mainWorktreePath)` | `src/utils/validate-core.ts` | 检测 patch 中的幽灵文件列表 |
+
+### 修改函数
+
+| 函数 | 文件 | 变更 |
+|------|------|------|
+| `migrateChangesViaPatch` | `src/utils/validate-core.ts` | apply 前调用检测函数 |
+
+### 新增消息常量
+
+| 常量 | 文件 | 用途 |
+|------|------|------|
+| `VALIDATE_IGNORED_FILES_CONFLICT` | `src/constants/messages/validate.ts` | 幽灵文件冲突提示（含文件列表和清理命令） |
+
+### 提示格式
+
+```
+⚠ 检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - docs/superpowers/findings/2026-05-30-chat-message-block-findings.md
+  - docs/superpowers/plans/2026-05-30-chat-message-block.md
+  ...（共 18 个文件）
+
+请手动清理后重试：
+  git clean -fdx docs/superpowers/
+```
+
+清理命令按冲突文件的直接父目录去重生成。
+
+## 错误处理
+
+- `git check-ignore` 无匹配时退出码为 1（非错误），需 catch 后返回空数组
+- `git diff --name-only` 失败时不阻断流程，跳过检测继续 apply（降级为当前行为）
+- 检测函数本身的异常不应阻断 validate 流程
+
+## 回归测试要求
+
+- 无幽灵文件时：validate 正常通过（现有测试覆盖）
+- 有幽灵文件时：validate 返回 `{ success: false }` 并输出提示
+- `gitCheckIgnored` 单元测试：空输入、全部忽略、全部不忽略、混合场景

package/docs/superpowers/specs/2026-06-09-worktree-base-branch-design.md

@@ -0,0 +1,169 @@
+# Worktree Base Branch Design
+
+## 背景
+
+当前 `clawt status`、`clawt status -i` 和 `clawt list` 会把同一项目下的 worktree 展示在一起，但不会标明这些 worktree 分支最初基于哪个分支创建。当用户同时从 `master`、`test` 等多个分支创建 worktree 时，容易把基于 `test` 的 worktree 误合并到 `master`，风险较高。
+
+## 目标
+
+- 在 `clawt create` 创建 worktree 时记录创建瞬间的真实当前分支，作为该 worktree 的来源分支。
+- 在 `clawt status`、`clawt status -i`、`clawt list` 中展示来源分支。
+- JSON 输出包含稳定字段，便于脚本消费。
+- 历史 worktree 没有元数据时明确展示未记录，不通过不可靠 git 推断伪造结果。
+
+## 非目标
+
+- 不新增历史回填命令。
+- 不修改 `clawt merge` 的合并目标逻辑。
+- 不改变 `clawt init` 的项目主工作分支配置语义。
+- 不把 worktree 元数据写入 `~/.clawt/projects/<projectName>/config.json`。
+
+## 来源分支语义
+
+来源分支定义为执行 `clawt create` 时，创建 worktree 前主 worktree 当前所在的真实分支。示例：用户当时位于 `test` 分支并创建 `feature-login`，则 `feature-login` 的 `baseBranch` 为 `test`。
+
+该语义优先于项目配置中的 `clawtMainWorkBranch`。如果现有前置检查在创建前切换了分支，则记录切换后的真实当前分支，因为它才是实际执行 `git worktree add -b` 的基准。
+
+## 存储设计
+
+每个 worktree 分支使用一个独立 JSON 文件：
+
+```text
+~/.clawt/projects/<projectName>/worktrees/<branchName>.json
+```
+
+文件内容：
+
+```json
+{
+  "branch": "feature-login",
+  "baseBranch": "test",
+  "createdAt": "2026-06-09T10:30:00.000Z"
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `branch` | `string` | worktree 对应分支名 |
+| `baseBranch` | `string` | 创建 worktree 时所在的真实当前分支 |
+| `createdAt` | `string` | 元数据写入时间，ISO 8601 字符串 |
+
+元数据属于项目级动态数据，应放在 `~/.clawt/projects/<projectName>/worktrees/` 下。项目配置 `config.json` 继续只保存配置项，避免运行元数据污染配置文件。
+
+## 代码结构
+
+新增 `src/utils/worktree-metadata.ts`，职责限定为 worktree 元数据路径、读写、删除：
+
+- `getWorktreeMetadataPath(projectName, branchName)`：生成单个分支元数据路径。
+- `saveWorktreeMetadata(projectName, metadata)`：保存来源分支元数据。
+- `loadWorktreeMetadata(projectName, branchName)`：读取元数据，缺失或解析失败时返回 `null`。
+- `removeWorktreeMetadata(projectName, branchName)`：删除元数据，文件不存在时不报错。
+
+新增类型 `WorktreeMetadata`，包含 `branch`、`baseBranch`、`createdAt`。现有 `WorktreeInfo` 和 `WorktreeDetailedStatus` 增加 `baseBranch: string | null`。
+
+## 数据流
+
+创建流程：
+
+1. `clawt create` 完成前置检查。
+2. `createWorktrees()` 在创建前读取 `getCurrentBranch()`。
+3. 每成功创建一个 worktree 和 validate 分支后，写入对应 metadata 文件。
+4. 命令输出继续展示目录、分支、验证分支；是否在创建输出中展示来源分支由实现保持简洁，可不新增。
+
+读取流程：
+
+1. `getProjectWorktrees()` 扫描 `~/.clawt/worktrees/<projectName>/` 并与 `git worktree list` 交叉验证。
+2. 对每个有效 worktree 读取 `~/.clawt/projects/<projectName>/worktrees/<branch>.json`。
+3. 返回 `WorktreeInfo` 时带上 `baseBranch`，没有元数据时为 `null`。
+4. `status` 的收集层把 `baseBranch` 传入 `WorktreeDetailedStatus`。
+5. `list`、`status` 文本渲染和交互面板只负责展示已有字段。
+
+## 展示规则
+
+`clawt status` 普通文本输出中，每个 worktree 条目增加一行：
+
+```text
+来源分支: test
+```
+
+英文语言环境显示：
+
+```text
+Base branch: test
+```
+
+没有元数据时显示：
+
+```text
+来源分支: 未记录
+```
+
+英文语言环境显示：
+
+```text
+Base branch: Not recorded
+```
+
+`clawt status -i` 交互面板在每个 worktree 块中同样显示来源分支行。
+
+`clawt list` 文本输出在路径与分支行中追加来源分支：
+
+```text
+~/.clawt/worktrees/project/feature-login   [feature-login]   <- test
+```
+
+没有元数据时：
+
+```text
+~/.clawt/worktrees/project/feature-login   [feature-login]   <- 未记录
+```
+
+JSON 输出新增 `baseBranch` 字段：
+
+```json
+{
+  "path": "~/.clawt/worktrees/project/feature-login",
+  "branch": "feature-login",
+  "baseBranch": "test"
+}
+```
+
+历史 worktree 无元数据时：
+
+```json
+{
+  "path": "~/.clawt/worktrees/project/legacy",
+  "branch": "legacy",
+  "baseBranch": null
+}
+```
+
+## 清理规则
+
+`cleanupWorktrees()` 删除 worktree、普通分支和 validate 分支时，同步删除对应 metadata 文件。删除 metadata 失败不阻断主清理流程，只记录日志。
+
+## 错误处理
+
+- 元数据文件不存在：返回 `null`，展示未记录。
+- 元数据 JSON 解析失败：记录 warning，返回 `null`。
+- 保存 metadata 失败：记录错误并抛出，让创建流程暴露问题，因为创建后无法记录来源会削弱防误操作能力。
+- 删除 metadata 失败：记录错误，不影响删除 worktree 的主流程。
+
+## 测试要求
+
+- `createWorktrees()` 和 `createWorktreesByBranches()` 创建成功后写入 `baseBranch`。
+- `getProjectWorktrees()` 能读取已有 `baseBranch`，缺失时返回 `null`。
+- `cleanupWorktrees()` 删除对应 metadata。
+- `clawt list --json` 输出 `baseBranch`。
+- `clawt status --json` 输出 `baseBranch`。
+- `status` 文本输出和 `status -i` 渲染显示来源分支。
+- 元数据解析失败不导致 status/list 崩溃。
+
+## 验收标准
+
+- 新创建的 worktree 在 `status`、`status -i`、`list` 中能看到来源分支。
+- 旧 worktree 没有 metadata 时显示未记录，JSON 为 `null`。
+- 删除 worktree 时对应 metadata 文件被清理。
+- 现有 `status`、`list`、`create` 单元测试通过，新增测试覆盖来源分支功能。