clawt 2.9.1 → 2.10.1

package/src/types/status.ts

@@ -0,0 +1,49 @@
+/** 单个 worktree 的详细状态信息 */
+export interface WorktreeDetailedStatus {
+  /** worktree 路径 */
+  path: string;
+  /** 分支名 */
+  branch: string;
+  /** 变更状态: committed(有已提交内容) / uncommitted(有未提交修改) / conflict(存在合并冲突) / clean(无变更) */
+  changeStatus: 'committed' | 'uncommitted' | 'conflict' | 'clean';
+  /** 相对于主分支的新增提交数（领先） */
+  commitsAhead: number;
+  /** 落后于主分支的提交数 */
+  commitsBehind: number;
+  /** 是否存在 validate 快照 */
+  hasSnapshot: boolean;
+  /** 工作区和暂存区的新增行数 */
+  insertions: number;
+  /** 工作区和暂存区的删除行数 */
+  deletions: number;
+}
+
+/** 主 worktree 状态信息 */
+export interface MainWorktreeStatus {
+  /** 当前分支名 */
+  branch: string;
+  /** 工作区是否干净 */
+  isClean: boolean;
+  /** 项目名 */
+  projectName: string;
+}
+
+/** validate 快照信息 */
+export interface SnapshotInfo {
+  /** 分支名 */
+  branch: string;
+  /** 是否对应的 worktree 仍然存在 */
+  worktreeExists: boolean;
+}
+
+/** status 命令的完整输出结构 */
+export interface StatusResult {
+  /** 主 worktree 状态 */
+  main: MainWorktreeStatus;
+  /** 各 worktree 的详细状态 */
+  worktrees: WorktreeDetailedStatus[];
+  /** 未清理的 validate 快照列表 */
+  snapshots: SnapshotInfo[];
+  /** worktree 总数 */
+  totalWorktrees: number;
+}

package/src/utils/git.ts

@@ -263,6 +263,22 @@ export function getCommitCountAhead(branchName: string, cwd?: string): number {
   return parseInt(output, 10) || 0;
 }
 
+/**
+ * 获取目标分支落后于当前分支的提交数
+ * 即当前分支有多少提交是目标分支没有的
+ * @param {string} branchName - 目标分支名
+ * @param {string} [cwd] - 工作目录
+ * @returns {number} 落后的提交数
+ */
+export function getCommitCountBehind(branchName: string, cwd?: string): number {
+  try {
+    const output = execCommand(`git rev-list --count ${branchName}..HEAD`, { cwd });
+    return parseInt(output, 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * 解析 git diff --shortstat 输出，提取新增行数和删除行数
  * @param {string} output - shortstat 输出字符串

package/src/utils/index.ts

@@ -27,6 +27,7 @@ export {
   gitWorktreePrune,
   hasLocalCommits,
   getCommitCountAhead,
+  getCommitCountBehind,
   getDiffStat,
   gitDiffCachedBinary,
   gitApplyCachedFromStdin,
@@ -52,6 +53,6 @@ export { printSuccess, printError, printWarning, printInfo, printSeparator, prin
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
-export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';
-export { findExactMatch, findFuzzyMatches, promptSelectBranch, resolveTargetWorktree } from './worktree-matcher.js';
-export type { WorktreeResolveMessages } from './worktree-matcher.js';
+export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';
+export { findExactMatch, findFuzzyMatches, promptSelectBranch, promptMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees } from './worktree-matcher.js';
+export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './worktree-matcher.js';

package/src/utils/validate-snapshot.ts

@@ -98,6 +98,23 @@ export function removeSnapshot(projectName: string, branchName: string): void {
   }
 }
 
+/**
+ * 获取指定项目所有存在 validate 快照的分支名列表
+ * 通过扫描快照目录下的 .tree 文件名提取
+ * @param {string} projectName - 项目名
+ * @returns {string[]} 存在快照的分支名列表
+ */
+export function getProjectSnapshotBranches(projectName: string): string[] {
+  const projectDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
+  if (!existsSync(projectDir)) {
+    return [];
+  }
+  const files = readdirSync(projectDir);
+  return files
+    .filter((f: string) => f.endsWith('.tree'))
+    .map((f: string) => f.replace(/\.tree$/, ''));
+}
+
 /**
  * 删除指定项目的所有 validate 快照
  * @param {string} projectName - 项目名

package/src/utils/worktree-matcher.ts

@@ -38,6 +38,21 @@ export function findFuzzyMatches(worktrees: WorktreeInfo[], keyword: string): Wo
   return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
 }
 
+/**
+ * 多选场景下的分支解析消息文案配置
+ * 与 WorktreeResolveMessages 类似，但用于需要多选的命令（如 remove）
+ */
+export interface WorktreeMultiResolveMessages {
+  /** 无可用 worktree 时的错误消息 */
+  noWorktrees: string;
+  /** 未传分支名时的多选交互提示 */
+  selectBranch: string;
+  /** 模糊匹配到多个结果时的多选交互提示 */
+  multipleMatches: (keyword: string) => string;
+  /** 无匹配结果时的错误消息 */
+  noMatch: (keyword: string, branches: string[]) => string;
+}
+
 /**
  * 通过交互式列表让用户从 worktree 列表中选择一个分支
  * @param {WorktreeInfo[]} worktrees - 可供选择的 worktree 列表
@@ -57,6 +72,83 @@ export async function promptSelectBranch(worktrees: WorktreeInfo[], message: str
   return worktrees.find((wt) => wt.branch === selectedBranch)!;
 }
 
+/**
+ * 通过交互式多选列表让用户从 worktree 列表中选择多个分支
+ * 用户可通过空格键选择/取消，回车键确认
+ * @param {WorktreeInfo[]} worktrees - 可供选择的 worktree 列表
+ * @param {string} message - 选择提示信息
+ * @returns {Promise<WorktreeInfo[]>} 用户选择的 worktree 列表
+ */
+export async function promptMultiSelectBranches(worktrees: WorktreeInfo[], message: string): Promise<WorktreeInfo[]> {
+  // @ts-expect-error enquirer 类型声明未导出 MultiSelect 类，但运行时存在
+  const selectedBranches: string[] = await new Enquirer.MultiSelect({
+    message,
+    choices: worktrees.map((wt) => ({
+      name: wt.branch,
+      message: wt.branch,
+    })),
+    // 使用空心圆/实心圆作为选中指示符
+    symbols: {
+      indicator: { on: '●', off: '○' },
+    },
+  }).run();
+
+  return worktrees.filter((wt) => selectedBranches.includes(wt.branch));
+}
+
+/**
+ * 根据用户输入解析目标 worktree（多选版本）
+ * 匹配策略：精确匹配 → 模糊匹配（唯一直接使用，多个交互多选） → 无匹配报错
+ * 不传分支名时列出所有可用分支供多选
+ * @param {WorktreeInfo[]} worktrees - 可用的 worktree 列表
+ * @param {WorktreeMultiResolveMessages} messages - 命令专属的消息文案
+ * @param {string} [branchName] - 用户输入的分支名（可选）
+ * @returns {Promise<WorktreeInfo[]>} 解析后的目标 worktree 列表
+ * @throws {ClawtError} 无可用 worktree 或无匹配结果时抛出
+ */
+export async function resolveTargetWorktrees(
+  worktrees: WorktreeInfo[],
+  messages: WorktreeMultiResolveMessages,
+  branchName?: string,
+): Promise<WorktreeInfo[]> {
+  // 无可用 worktree，直接报错
+  if (worktrees.length === 0) {
+    throw new ClawtError(messages.noWorktrees);
+  }
+
+  // 未传 -b 参数：列出所有分支供多选
+  if (!branchName) {
+    // 只有一个 worktree 时直接使用，无需选择
+    if (worktrees.length === 1) {
+      return [worktrees[0]];
+    }
+    return promptMultiSelectBranches(worktrees, messages.selectBranch);
+  }
+
+  // 1. 精确匹配优先
+  const exactMatch = findExactMatch(worktrees, branchName);
+  if (exactMatch) {
+    return [exactMatch];
+  }
+
+  // 2. 模糊匹配
+  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
+
+  // 2a. 唯一匹配，直接使用
+  if (fuzzyMatches.length === 1) {
+    return [fuzzyMatches[0]];
+  }
+
+  // 2b. 多个匹配，交互多选
+  if (fuzzyMatches.length > 1) {
+    return promptMultiSelectBranches(fuzzyMatches, messages.multipleMatches(branchName));
+  }
+
+  // 3. 无匹配，抛出错误并列出所有可用分支
+  const allBranches = worktrees.map((wt) => wt.branch);
+  throw new ClawtError(messages.noMatch(branchName, allBranches));
+}
+
 /**
  * 根据用户输入解析目标 worktree
  * 匹配策略：精确匹配 → 模糊匹配（唯一直接使用，多个交互选择） → 无匹配报错

package/tests/unit/commands/config.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+// mock 依赖模块
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('../../../src/utils/index.js', () => ({
+  loadConfig: vi.fn(),
+  writeDefaultConfig: vi.fn(),
+  printInfo: vi.fn(),
+  printSuccess: vi.fn(),
+  printSeparator: vi.fn(),
+  confirmDestructiveAction: vi.fn(),
+}));
+
+vi.mock('../../../src/constants/index.js', () => ({
+  CONFIG_PATH: '/mock/.clawt/config.json',
+  DEFAULT_CONFIG: {
+    claudeCodeCommand: 'claude',
+    autoDeleteBranch: false,
+    autoPullPush: false,
+    confirmDestructiveOps: true,
+  },
+  CONFIG_DESCRIPTIONS: {
+    claudeCodeCommand: 'Claude Code CLI 命令',
+    autoDeleteBranch: '自动删除分支',
+    autoPullPush: '自动 pull/push',
+    confirmDestructiveOps: '破坏性操作确认',
+  },
+  MESSAGES: {
+    CONFIG_RESET_SUCCESS: '配置已恢复为默认值',
+    DESTRUCTIVE_OP_CANCELLED: '已取消操作',
+  },
+}));
+
+import { registerConfigCommand } from '../../../src/commands/config.js';
+import { loadConfig, writeDefaultConfig, printInfo, printSuccess, confirmDestructiveAction } from '../../../src/utils/index.js';
+
+const mockedLoadConfig = vi.mocked(loadConfig);
+const mockedWriteDefaultConfig = vi.mocked(writeDefaultConfig);
+const mockedPrintInfo = vi.mocked(printInfo);
+const mockedPrintSuccess = vi.mocked(printSuccess);
+const mockedConfirmDestructiveAction = vi.mocked(confirmDestructiveAction);
+
+beforeEach(() => {
+  mockedLoadConfig.mockReset();
+  mockedWriteDefaultConfig.mockReset();
+  mockedPrintInfo.mockReset();
+  mockedPrintSuccess.mockReset();
+  mockedConfirmDestructiveAction.mockReset();
+});
+
+describe('registerConfigCommand', () => {
+  it('注册 config 命令和 config reset 子命令', () => {
+    const program = new Command();
+    registerConfigCommand(program);
+    const configCmd = program.commands.find((c) => c.name() === 'config');
+    expect(configCmd).toBeDefined();
+    const resetCmd = configCmd!.commands.find((c) => c.name() === 'reset');
+    expect(resetCmd).toBeDefined();
+  });
+});
+
+describe('handleConfig（通过 action 间接测试）', () => {
+  it('展示配置列表', () => {
+    mockedLoadConfig.mockReturnValue({
+      claudeCodeCommand: 'claude',
+      autoDeleteBranch: false,
+      autoPullPush: false,
+      confirmDestructiveOps: true,
+    });
+
+    const program = new Command();
+    program.exitOverride();
+    registerConfigCommand(program);
+    program.parse(['config'], { from: 'user' });
+
+    expect(mockedLoadConfig).toHaveBeenCalled();
+    // 应输出配置信息
+    expect(mockedPrintInfo).toHaveBeenCalled();
+  });
+});
+
+describe('handleConfigReset（通过 action 间接测试）', () => {
+  it('用户确认后恢复默认配置', async () => {
+    mockedConfirmDestructiveAction.mockResolvedValue(true);
+
+    const program = new Command();
+    program.exitOverride();
+    registerConfigCommand(program);
+    await program.parseAsync(['config', 'reset'], { from: 'user' });
+
+    expect(mockedWriteDefaultConfig).toHaveBeenCalled();
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+
+  it('用户取消操作时不写入', async () => {
+    mockedConfirmDestructiveAction.mockResolvedValue(false);
+
+    const program = new Command();
+    program.exitOverride();
+    registerConfigCommand(program);
+    await program.parseAsync(['config', 'reset'], { from: 'user' });
+
+    expect(mockedWriteDefaultConfig).not.toHaveBeenCalled();
+    expect(mockedPrintInfo).toHaveBeenCalled();
+  });
+});

package/tests/unit/commands/create.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: 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: {
+    INVALID_COUNT: (val: string) => `数量必须为正整数: ${val}`,
+    WORKTREE_CREATED: (count: number) => `✓ 已创建 ${count} 个 worktree`,
+  },
+  EXIT_CODES: { SUCCESS: 0, ERROR: 1, ARGUMENT_ERROR: 2 },
+}));
+
+vi.mock('../../../src/utils/index.js', () => ({
+  validateMainWorktree: vi.fn(),
+  createWorktrees: vi.fn(),
+  printSuccess: vi.fn(),
+  printInfo: vi.fn(),
+  printSeparator: vi.fn(),
+}));
+
+import { registerCreateCommand } from '../../../src/commands/create.js';
+import { validateMainWorktree, createWorktrees, printSuccess } from '../../../src/utils/index.js';
+
+const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedCreateWorktrees = vi.mocked(createWorktrees);
+const mockedPrintSuccess = vi.mocked(printSuccess);
+
+beforeEach(() => {
+  mockedValidateMainWorktree.mockReset();
+  mockedCreateWorktrees.mockReset();
+  mockedPrintSuccess.mockReset();
+});
+
+describe('registerCreateCommand', () => {
+  it('注册 create 命令', () => {
+    const program = new Command();
+    registerCreateCommand(program);
+    const cmd = program.commands.find((c) => c.name() === 'create');
+    expect(cmd).toBeDefined();
+  });
+});
+
+describe('handleCreate', () => {
+  it('成功创建 worktree', () => {
+    mockedCreateWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerCreateCommand(program);
+    program.parse(['create', '-b', 'feature'], { from: 'user' });
+
+    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedCreateWorktrees).toHaveBeenCalledWith('feature', 1);
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+
+  it('支持 -n 指定创建数量', () => {
+    mockedCreateWorktrees.mockReturnValue([
+      { path: '/path/feature-1', branch: 'feature-1' },
+      { path: '/path/feature-2', branch: 'feature-2' },
+    ]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerCreateCommand(program);
+    program.parse(['create', '-b', 'feature', '-n', '2'], { from: 'user' });
+
+    expect(mockedCreateWorktrees).toHaveBeenCalledWith('feature', 2);
+  });
+
+  it('无效数量抛出 ClawtError', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCreateCommand(program);
+
+    expect(() => {
+      program.parse(['create', '-b', 'feature', '-n', 'abc'], { from: 'user' });
+    }).toThrow();
+  });
+
+  it('数量为 0 时抛出 ClawtError', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCreateCommand(program);
+
+    expect(() => {
+      program.parse(['create', '-b', 'feature', '-n', '0'], { from: 'user' });
+    }).toThrow();
+  });
+
+  it('负数数量抛出 ClawtError', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCreateCommand(program);
+
+    expect(() => {
+      program.parse(['create', '-b', 'feature', '-n', '-1'], { from: 'user' });
+    }).toThrow();
+  });
+});

package/tests/unit/commands/list.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('../../../src/constants/index.js', () => ({
+  MESSAGES: {
+    NO_WORKTREES: '(无 worktree)',
+    WORKTREE_STATUS_UNAVAILABLE: '(状态不可用)',
+  },
+}));
+
+vi.mock('../../../src/utils/index.js', () => ({
+  validateMainWorktree: vi.fn(),
+  getProjectName: vi.fn(),
+  getProjectWorktrees: vi.fn(),
+  getWorktreeStatus: vi.fn(),
+  formatWorktreeStatus: vi.fn(),
+  isWorktreeIdle: vi.fn(),
+  printInfo: vi.fn(),
+}));
+
+import { registerListCommand } from '../../../src/commands/list.js';
+import { validateMainWorktree, getProjectName, getProjectWorktrees, getWorktreeStatus, printInfo } from '../../../src/utils/index.js';
+
+const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedGetProjectName = vi.mocked(getProjectName);
+const mockedGetProjectWorktrees = vi.mocked(getProjectWorktrees);
+const mockedGetWorktreeStatus = vi.mocked(getWorktreeStatus);
+const mockedPrintInfo = vi.mocked(printInfo);
+
+beforeEach(() => {
+  mockedValidateMainWorktree.mockReset();
+  mockedGetProjectName.mockReset();
+  mockedGetProjectWorktrees.mockReset();
+  mockedGetWorktreeStatus.mockReset();
+  mockedPrintInfo.mockReset();
+});
+
+describe('registerListCommand', () => {
+  it('注册 list 命令', () => {
+    const program = new Command();
+    registerListCommand(program);
+    const cmd = program.commands.find((c) => c.name() === 'list');
+    expect(cmd).toBeDefined();
+  });
+});
+
+describe('handleList', () => {
+  it('无 worktree 时文本输出', () => {
+    mockedGetProjectName.mockReturnValue('test-project');
+    mockedGetProjectWorktrees.mockReturnValue([]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerListCommand(program);
+    program.parse(['list'], { from: 'user' });
+
+    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedPrintInfo).toHaveBeenCalled();
+  });
+
+  it('有 worktree 时文本输出', () => {
+    mockedGetProjectName.mockReturnValue('test-project');
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetWorktreeStatus.mockReturnValue({
+      commitCount: 3, insertions: 10, deletions: 5, hasDirtyFiles: false,
+    });
+
+    const program = new Command();
+    program.exitOverride();
+    registerListCommand(program);
+    program.parse(['list'], { from: 'user' });
+
+    expect(mockedGetWorktreeStatus).toHaveBeenCalled();
+  });
+
+  it('--json 输出 JSON 格式', () => {
+    mockedGetProjectName.mockReturnValue('test-project');
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const program = new Command();
+    program.exitOverride();
+    registerListCommand(program);
+    program.parse(['list', '--json'], { from: 'user' });
+
+    // 应通过 console.log 输出 JSON
+    const jsonCall = consoleSpy.mock.calls.find((call) => {
+      try { JSON.parse(call[0]); return true; } catch { return false; }
+    });
+    expect(jsonCall).toBeDefined();
+    const parsed = JSON.parse(jsonCall![0]);
+    expect(parsed.project).toBe('test-project');
+    expect(parsed.total).toBe(1);
+  });
+
+  it('worktree 状态不可用时显示提示', () => {
+    mockedGetProjectName.mockReturnValue('test-project');
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetWorktreeStatus.mockReturnValue(null);
+
+    const program = new Command();
+    program.exitOverride();
+    registerListCommand(program);
+    program.parse(['list'], { from: 'user' });
+
+    expect(mockedGetWorktreeStatus).toHaveBeenCalled();
+  });
+});