clawt 2.10.0 → 2.11.0

package/tests/unit/utils/formatter.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { formatWorktreeStatus, printSuccess, printError, printWarning, printInfo } from '../../../src/utils/formatter.js';
+import { formatWorktreeStatus, printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, isWorktreeIdle, formatDuration } from '../../../src/utils/formatter.js';
 import { createWorktreeStatus } from '../../helpers/fixtures.js';
 
 describe('formatWorktreeStatus', () => {
@@ -38,6 +38,49 @@ describe('formatWorktreeStatus', () => {
   });
 });
 
+describe('isWorktreeIdle', () => {
+  it('全部为零且无未提交修改时返回 true', () => {
+    const status = createWorktreeStatus({ commitCount: 0, insertions: 0, deletions: 0, hasDirtyFiles: false });
+    expect(isWorktreeIdle(status)).toBe(true);
+  });
+
+  it('有提交时返回 false', () => {
+    const status = createWorktreeStatus({ commitCount: 1, insertions: 0, deletions: 0, hasDirtyFiles: false });
+    expect(isWorktreeIdle(status)).toBe(false);
+  });
+
+  it('有 insertions 时返回 false', () => {
+    const status = createWorktreeStatus({ commitCount: 0, insertions: 1, deletions: 0, hasDirtyFiles: false });
+    expect(isWorktreeIdle(status)).toBe(false);
+  });
+
+  it('有 deletions 时返回 false', () => {
+    const status = createWorktreeStatus({ commitCount: 0, insertions: 0, deletions: 1, hasDirtyFiles: false });
+    expect(isWorktreeIdle(status)).toBe(false);
+  });
+
+  it('有未提交修改时返回 false', () => {
+    const status = createWorktreeStatus({ commitCount: 0, insertions: 0, deletions: 0, hasDirtyFiles: true });
+    expect(isWorktreeIdle(status)).toBe(false);
+  });
+});
+
+describe('printSeparator', () => {
+  it('调用 console.log 输出分隔线', () => {
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    printSeparator();
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('printDoubleSeparator', () => {
+  it('调用 console.log 输出粗分隔线', () => {
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    printDoubleSeparator();
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('print 函数', () => {
   it('printSuccess 调用 console.log', () => {
     const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
@@ -67,3 +110,29 @@ describe('print 函数', () => {
     expect(spy.mock.calls[0][0]).toBe('普通消息');
   });
 });
+
+describe('formatDuration', () => {
+  it('小于 60 秒时显示秒数（保留一位小数）', () => {
+    expect(formatDuration(5200)).toBe('5.2s');
+  });
+
+  it('0 毫秒时显示 0.0s', () => {
+    expect(formatDuration(0)).toBe('0.0s');
+  });
+
+  it('59.9 秒时仍显示秒数', () => {
+    expect(formatDuration(59900)).toBe('59.9s');
+  });
+
+  it('大于等于 60 秒时显示分秒格式', () => {
+    expect(formatDuration(83000)).toBe('1m23s');
+  });
+
+  it('整分钟时秒数补零', () => {
+    expect(formatDuration(120000)).toBe('2m00s');
+  });
+
+  it('大数值时正确格式化', () => {
+    expect(formatDuration(3661000)).toBe('61m01s');
+  });
+});

package/tests/unit/utils/git.test.ts

@@ -32,6 +32,8 @@ import {
   gitCommit,
   gitMerge,
   hasMergeConflict,
+  gitPull,
+  gitPush,
   gitResetHard,
   gitCleanForce,
   gitStashPush,
@@ -44,6 +46,7 @@ import {
   gitWorktreePrune,
   hasLocalCommits,
   getCommitCountAhead,
+  getCommitCountBehind,
   getDiffStat,
   gitDiffCachedBinary,
   gitApplyCachedFromStdin,
@@ -530,3 +533,44 @@ describe('gitApplyCachedCheck', () => {
     expect(gitApplyCachedCheck(patch, '/repo')).toBe(false);
   });
 });
+
+describe('gitPull', () => {
+  it('执行 git pull', () => {
+    gitPull('/repo');
+    expect(mockedExecCommand).toHaveBeenCalledWith('git pull', { cwd: '/repo' });
+  });
+
+  it('不传 cwd 时 cwd 为 undefined', () => {
+    gitPull();
+    expect(mockedExecCommand).toHaveBeenCalledWith('git pull', { cwd: undefined });
+  });
+});
+
+describe('gitPush', () => {
+  it('执行 git push', () => {
+    gitPush('/repo');
+    expect(mockedExecCommand).toHaveBeenCalledWith('git push', { cwd: '/repo' });
+  });
+
+  it('不传 cwd 时 cwd 为 undefined', () => {
+    gitPush();
+    expect(mockedExecCommand).toHaveBeenCalledWith('git push', { cwd: undefined });
+  });
+});
+
+describe('getCommitCountBehind', () => {
+  it('返回正确的落后提交数', () => {
+    mockedExecCommand.mockReturnValue('3');
+    expect(getCommitCountBehind('feature')).toBe(3);
+  });
+
+  it('返回 0 当输出无法解析', () => {
+    mockedExecCommand.mockReturnValue('');
+    expect(getCommitCountBehind('feature')).toBe(0);
+  });
+
+  it('命令失败时返回 0', () => {
+    mockedExecCommand.mockImplementation(() => { throw new Error('fail'); });
+    expect(getCommitCountBehind('feature')).toBe(0);
+  });
+});

package/tests/unit/utils/progress.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ProgressRenderer } from '../../../src/utils/progress.js';
+
+describe('ProgressRenderer', () => {
+  let writeSpy: ReturnType<typeof vi.spyOn>;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let originalIsTTY: boolean | undefined;
+
+  beforeEach(() => {
+    writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    originalIsTTY = process.stdout.isTTY;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, writable: true });
+    writeSpy.mockRestore();
+    logSpy.mockRestore();
+  });
+
+  describe('TTY 模式', () => {
+    beforeEach(() => {
+      Object.defineProperty(process.stdout, 'isTTY', { value: true, writable: true });
+    });
+
+    it('start 时隐藏光标并渲染初始面板', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2']);
+      renderer.start();
+      renderer.stop();
+
+      // 应有写入隐藏光标的调用
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('\x1B[?25l');
+      // 应有写入显示光标的调用
+      expect(allOutput).toContain('\x1B[?25h');
+    });
+
+    it('start 后 stop 清除定时器并恢复光标', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      renderer.stop();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('\x1B[?25h');
+    });
+
+    it('stop 幂等，多次调用不报错', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      renderer.stop();
+      renderer.stop();
+      renderer.stop();
+
+      // 只有一次恢复光标
+      const showCursorCount = writeSpy.mock.calls
+        .map((c) => c[0])
+        .filter((s) => typeof s === 'string' && s.includes('\x1B[?25h')).length;
+      expect(showCursorCount).toBe(1);
+    });
+
+    it('渲染面板包含分支名、运行状态和路径', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2']);
+      renderer.start();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('feat-1');
+      expect(allOutput).toContain('feat-2');
+      expect(allOutput).toContain('运行中');
+      expect(allOutput).toContain('/path/feat-1');
+      expect(allOutput).toContain('/path/feat-2');
+
+      renderer.stop();
+    });
+
+    it('markDone 后渲染显示完成状态和路径', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      writeSpy.mockClear();
+
+      renderer.markDone(0, 5000, 0.05);
+      renderer.stop();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('✓');
+      expect(allOutput).toContain('完成');
+      expect(allOutput).toContain('5.0s');
+      expect(allOutput).toContain('$0.05');
+      expect(allOutput).toContain('/path/feat-1');
+    });
+
+    it('markFailed 后渲染显示失败状态和路径', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      writeSpy.mockClear();
+
+      renderer.markFailed(0, 3000);
+      renderer.stop();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('✗');
+      expect(allOutput).toContain('失败');
+      expect(allOutput).toContain('3.0s');
+      expect(allOutput).toContain('/path/feat-1');
+    });
+
+    it('updateActivity 更新后不立即渲染（等待定时器）', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      const callCountBefore = writeSpy.mock.calls.length;
+
+      renderer.updateActivity(0);
+
+      // updateActivity 不应触发额外的 write 调用
+      expect(writeSpy.mock.calls.length).toBe(callCountBefore);
+
+      renderer.stop();
+    });
+
+    it('allRunning=false 时任务初始化为 pending 状态', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2'], false);
+      renderer.start();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('◦');
+      expect(allOutput).toContain('排队中');
+
+      renderer.stop();
+    });
+
+    it('markRunning 将 pending 任务标记为运行中', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2'], false);
+      renderer.start();
+      writeSpy.mockClear();
+
+      renderer.markRunning(0);
+      renderer.stop();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      expect(allOutput).toContain('运行中');
+      // 第二个任务仍为排队中
+      expect(allOutput).toContain('排队中');
+    });
+
+    it('allRunning=false 时面板包含汇总行', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2', 'feat-3'], ['/path/feat-1', '/path/feat-2', '/path/feat-3'], false);
+      renderer.start();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      // 汇总行应包含排队中的计数
+      expect(allOutput).toContain('3/3');
+      expect(allOutput).toContain('排队中');
+
+      renderer.stop();
+    });
+
+    it('汇总行正确反映状态变化', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2', 'feat-3'], ['/path/feat-1', '/path/feat-2', '/path/feat-3'], false);
+      renderer.start();
+      renderer.markRunning(0);
+      renderer.markDone(0, 5000, 0.05);
+      renderer.markRunning(1);
+      writeSpy.mockClear();
+
+      renderer.stop();
+
+      const allOutput = writeSpy.mock.calls.map((c) => c[0]).join('');
+      // 应包含：1/3 完成, 1/3 运行中, 1/3 排队中
+      expect(allOutput).toContain('1/3');
+    });
+  });
+
+  describe('非 TTY 模式', () => {
+    beforeEach(() => {
+      Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+    });
+
+    it('start 时逐行输出启动信息', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2']);
+      renderer.start();
+
+      expect(logSpy).toHaveBeenCalledTimes(2);
+      expect(logSpy.mock.calls[0][0]).toContain('feat-1');
+      expect(logSpy.mock.calls[0][0]).toContain('启动');
+      expect(logSpy.mock.calls[1][0]).toContain('feat-2');
+
+      renderer.stop();
+    });
+
+    it('markDone 时输出完成信息和路径', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      logSpy.mockClear();
+
+      renderer.markDone(0, 5000, 0.05);
+
+      expect(logSpy).toHaveBeenCalledTimes(1);
+      expect(logSpy.mock.calls[0][0]).toContain('✓');
+      expect(logSpy.mock.calls[0][0]).toContain('完成');
+      expect(logSpy.mock.calls[0][0]).toContain('5.0s');
+      expect(logSpy.mock.calls[0][0]).toContain('$0.05');
+      expect(logSpy.mock.calls[0][0]).toContain('/path/feat-1');
+
+      renderer.stop();
+    });
+
+    it('markFailed 时输出失败信息和路径', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      logSpy.mockClear();
+
+      renderer.markFailed(0, 3000);
+
+      expect(logSpy).toHaveBeenCalledTimes(1);
+      expect(logSpy.mock.calls[0][0]).toContain('✗');
+      expect(logSpy.mock.calls[0][0]).toContain('失败');
+      expect(logSpy.mock.calls[0][0]).toContain('3.0s');
+      expect(logSpy.mock.calls[0][0]).toContain('/path/feat-1');
+
+      renderer.stop();
+    });
+
+    it('不使用 ANSI 转义码', () => {
+      const renderer = new ProgressRenderer(['feat-1'], ['/path/feat-1']);
+      renderer.start();
+      renderer.markDone(0, 5000, 0.05);
+      renderer.stop();
+
+      // process.stdout.write 不应被调用（非 TTY 模式用 console.log）
+      expect(writeSpy).not.toHaveBeenCalled();
+    });
+
+    it('allRunning=false 时 start 不输出 pending 任务', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2'], false);
+      renderer.start();
+
+      // pending 任务不应输出启动信息
+      expect(logSpy).not.toHaveBeenCalled();
+
+      renderer.stop();
+    });
+
+    it('markRunning 时输出启动信息', () => {
+      const renderer = new ProgressRenderer(['feat-1', 'feat-2'], ['/path/feat-1', '/path/feat-2'], false);
+      renderer.start();
+
+      renderer.markRunning(0);
+
+      expect(logSpy).toHaveBeenCalledTimes(1);
+      expect(logSpy.mock.calls[0][0]).toContain('feat-1');
+      expect(logSpy.mock.calls[0][0]).toContain('启动');
+
+      renderer.stop();
+    });
+  });
+});

package/tests/unit/utils/task-file.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { parseTaskFile, loadTaskFile } from '../../../src/utils/task-file.js';
+import { existsSync, readFileSync } from 'node:fs';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}));
+
+vi.mock('../../../src/errors/index.js', () => ({
+  ClawtError: class ClawtError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode = 1) {
+      super(message);
+      this.exitCode = exitCode;
+    }
+  },
+}));
+
+vi.mock('../../../src/constants/index.js', () => ({
+  MESSAGES: {
+    TASK_FILE_NOT_FOUND: (path: string) => `任务文件不存在: ${path}`,
+    TASK_FILE_EMPTY: '任务文件中没有解析到有效任务',
+    TASK_FILE_MISSING_BRANCH: (blockIndex: number) => `第 ${blockIndex} 个任务块缺少分支名`,
+    TASK_FILE_MISSING_TASK: (branch: string) => `分支 ${branch} 缺少任务描述`,
+    TASK_FILE_MISSING_TASK_BY_INDEX: (blockIndex: number) => `第 ${blockIndex} 个任务块缺少任务描述`,
+  },
+}));
+
+const mockedExistsSync = vi.mocked(existsSync);
+const mockedReadFileSync = vi.mocked(readFileSync);
+
+beforeEach(() => {
+  mockedExistsSync.mockReset();
+  mockedReadFileSync.mockReset();
+});
+
+describe('parseTaskFile', () => {
+  it('正常解析多个任务块', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现用户登录功能
+<!-- CLAWT-TASKS:END -->
+
+<!-- CLAWT-TASKS:START -->
+# branch: fix-bug
+修复内存泄漏问题
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].branch).toBe('feat-login');
+    expect(entries[0].task).toBe('实现用户登录功能');
+    expect(entries[1].branch).toBe('fix-bug');
+    expect(entries[1].task).toBe('修复内存泄漏问题');
+  });
+
+  it('支持多行任务描述', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+# branch: feat-dashboard
+开发数据仪表盘页面
+包含图表和实时数据刷新
+支持自定义布局
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBe('feat-dashboard');
+    expect(entries[0].task).toBe('开发数据仪表盘页面\n包含图表和实时数据刷新\n支持自定义布局');
+  });
+
+  it('标签外内容被忽略', () => {
+    const content = `
+这是说明文字，会被忽略
+
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+
+这也是说明文字
+`;
+    const entries = parseTaskFile(content);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBe('feat-login');
+  });
+
+  it('空文件返回空数组', () => {
+    const entries = parseTaskFile('');
+    expect(entries).toHaveLength(0);
+  });
+
+  it('没有任务块时返回空数组', () => {
+    const entries = parseTaskFile('一些普通文本内容');
+    expect(entries).toHaveLength(0);
+  });
+
+  it('缺少分支名时抛出错误', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`;
+    expect(() => parseTaskFile(content)).toThrow('缺少分支名');
+  });
+
+  it('缺少任务描述时抛出错误', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+<!-- CLAWT-TASKS:END -->
+`;
+    expect(() => parseTaskFile(content)).toThrow('缺少任务描述');
+  });
+
+  it('branch 前缀支持不同空格格式', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+#branch:feat-login
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+
+<!-- CLAWT-TASKS:START -->
+# branch:   fix-bug
+修复问题
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].branch).toBe('feat-login');
+    expect(entries[1].branch).toBe('fix-bug');
+  });
+
+  it('branchRequired: false 时缺少分支名不报错，branch 为 undefined', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content, { branchRequired: false });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBeUndefined();
+    expect(entries[0].task).toBe('实现登录功能');
+  });
+
+  it('branchRequired: false 时有分支名仍能正确解析', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content, { branchRequired: false });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBe('feat-login');
+    expect(entries[0].task).toBe('实现登录功能');
+  });
+
+  it('branchRequired: false 时混合有无分支名的块', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+
+<!-- CLAWT-TASKS:START -->
+修复内存泄漏问题
+<!-- CLAWT-TASKS:END -->
+`;
+    const entries = parseTaskFile(content, { branchRequired: false });
+    expect(entries).toHaveLength(2);
+    expect(entries[0].branch).toBe('feat-login');
+    expect(entries[0].task).toBe('实现登录功能');
+    expect(entries[1].branch).toBeUndefined();
+    expect(entries[1].task).toBe('修复内存泄漏问题');
+  });
+
+  it('branchRequired: false 时仍校验任务描述', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+<!-- CLAWT-TASKS:END -->
+`;
+    expect(() => parseTaskFile(content, { branchRequired: false })).toThrow('缺少任务描述');
+  });
+
+  it('不传 options 时默认要求分支名（向后兼容）', () => {
+    const content = `
+<!-- CLAWT-TASKS:START -->
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`;
+    expect(() => parseTaskFile(content)).toThrow('缺少分支名');
+  });
+});
+
+describe('loadTaskFile', () => {
+  it('文件不存在时抛出错误', () => {
+    mockedExistsSync.mockReturnValue(false);
+    expect(() => loadTaskFile('nonexistent.md')).toThrow('任务文件不存在');
+  });
+
+  it('文件无有效任务时抛出错误', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue('普通文本内容');
+    expect(() => loadTaskFile('empty.md')).toThrow('没有解析到有效任务');
+  });
+
+  it('正常加载并解析文件', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue(`
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`);
+    const entries = loadTaskFile('tasks.md');
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBe('feat-login');
+    expect(entries[0].task).toBe('实现登录功能');
+  });
+
+  it('透传 branchRequired: false 选项', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue(`
+<!-- CLAWT-TASKS:START -->
+实现登录功能
+<!-- CLAWT-TASKS:END -->
+`);
+    const entries = loadTaskFile('tasks.md', { branchRequired: false });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].branch).toBeUndefined();
+    expect(entries[0].task).toBe('实现登录功能');
+  });
+});

package/tests/unit/utils/validate-snapshot.test.ts

@@ -39,6 +39,7 @@ import {
   writeSnapshot,
   removeSnapshot,
   removeProjectSnapshots,
+  getProjectSnapshotBranches,
 } from '../../../src/utils/validate-snapshot.js';
 
 const mockedExistsSync = vi.mocked(existsSync);
@@ -149,3 +150,27 @@ describe('removeProjectSnapshots', () => {
     expect(mockedUnlinkSync).not.toHaveBeenCalled();
   });
 });
+
+describe('getProjectSnapshotBranches', () => {
+  it('返回所有存在快照的分支名', () => {
+    mockedExistsSync.mockReturnValue(true);
+    // @ts-expect-error readdirSync 返回类型简化
+    mockedReaddirSync.mockReturnValue(['feat-a.tree', 'feat-a.head', 'feat-b.tree', 'feat-b.head']);
+    const result = getProjectSnapshotBranches('proj');
+    expect(result).toEqual(['feat-a', 'feat-b']);
+  });
+
+  it('没有 .tree 文件时返回空数组', () => {
+    mockedExistsSync.mockReturnValue(true);
+    // @ts-expect-error readdirSync 返回类型简化
+    mockedReaddirSync.mockReturnValue(['feat-a.head']);
+    const result = getProjectSnapshotBranches('proj');
+    expect(result).toEqual([]);
+  });
+
+  it('项目目录不存在时返回空数组', () => {
+    mockedExistsSync.mockReturnValue(false);
+    const result = getProjectSnapshotBranches('proj');
+    expect(result).toEqual([]);
+  });
+});