clawt 2.10.1 → 2.11.0

package/src/utils/task-file.ts

@@ -0,0 +1,87 @@
+import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import type { TaskFileEntry, ParseTaskFileOptions } from '../types/index.js';
+
+/** 匹配任务块的正则：<!-- CLAWT-TASKS:START --> ... <!-- CLAWT-TASKS:END --> */
+const TASK_BLOCK_REGEX = /<!-- CLAWT-TASKS:START -->([\s\S]*?)<!-- CLAWT-TASKS:END -->/g;
+
+/** 匹配分支名行的正则：# branch: <name> */
+const BRANCH_LINE_REGEX = /^#\s*branch:\s*(.+)$/;
+
+/**
+ * 解析任务文件内容，提取所有任务块
+ * 每个块内 `# branch: <name>` 为分支名，其余行为任务描述
+ * @param {string} content - 文件内容
+ * @param {ParseTaskFileOptions} [options] - 解析选项
+ * @returns {TaskFileEntry[]} 解析出的任务列表
+ */
+export function parseTaskFile(content: string, options?: ParseTaskFileOptions): TaskFileEntry[] {
+  const branchRequired = options?.branchRequired ?? true;
+  const entries: TaskFileEntry[] = [];
+  let match: RegExpExecArray | null;
+  let blockIndex = 0;
+
+  // 重置正则 lastIndex，避免模块级 /g 正则跨调用残留状态
+  TASK_BLOCK_REGEX.lastIndex = 0;
+
+  while ((match = TASK_BLOCK_REGEX.exec(content)) !== null) {
+    blockIndex++;
+    const blockContent = match[1].trim();
+    const lines = blockContent.split('\n');
+
+    let branch: string | undefined;
+    const taskLines: string[] = [];
+
+    for (const line of lines) {
+      const branchMatch = line.trim().match(BRANCH_LINE_REGEX);
+      if (branchMatch) {
+        branch = branchMatch[1].trim();
+      } else {
+        taskLines.push(line);
+      }
+    }
+
+    if (branchRequired && !branch) {
+      throw new ClawtError(MESSAGES.TASK_FILE_MISSING_BRANCH(blockIndex));
+    }
+
+    const task = taskLines.join('\n').trim();
+    if (!task) {
+      throw new ClawtError(
+        branch
+          ? MESSAGES.TASK_FILE_MISSING_TASK(branch)
+          : MESSAGES.TASK_FILE_MISSING_TASK_BY_INDEX(blockIndex),
+      );
+    }
+
+    entries.push({ branch, task });
+  }
+
+  return entries;
+}
+
+/**
+ * 读取并解析任务文件
+ * 支持相对路径（基于 cwd）和绝对路径
+ * @param {string} filePath - 文件路径
+ * @param {ParseTaskFileOptions} [options] - 解析选项
+ * @returns {TaskFileEntry[]} 解析出的任务列表
+ */
+export function loadTaskFile(filePath: string, options?: ParseTaskFileOptions): TaskFileEntry[] {
+  const absolutePath = resolve(filePath);
+
+  if (!existsSync(absolutePath)) {
+    throw new ClawtError(MESSAGES.TASK_FILE_NOT_FOUND(absolutePath));
+  }
+
+  const content = readFileSync(absolutePath, 'utf-8');
+  const entries = parseTaskFile(content, options);
+
+  if (entries.length === 0) {
+    throw new ClawtError(MESSAGES.TASK_FILE_EMPTY);
+  }
+
+  return entries;
+}

package/src/utils/worktree.ts

@@ -49,6 +49,33 @@ export function createWorktrees(branchName: string, count: number): WorktreeInfo
   return results;
 }
 
+/**
+ * 根据独立分支名列表逐个创建 worktree（不自动编号）
+ * 与 createWorktrees 不同，不使用 generateBranchNames 自动编号
+ * 调用方负责分支名清理（sanitizeBranchName）
+ * @param {string[]} branchNames - 已清理的分支名列表
+ * @returns {WorktreeInfo[]} 创建的 worktree 信息列表
+ */
+export function createWorktreesByBranches(branchNames: string[]): WorktreeInfo[] {
+  // 1. 校验所有分支是否都不存在
+  validateBranchesNotExist(branchNames);
+
+  // 2. 确保项目 worktree 目录存在
+  const projectDir = getProjectWorktreeDir();
+  ensureDir(projectDir);
+
+  // 3. 串行创建 worktree
+  const results: WorktreeInfo[] = [];
+  for (const name of branchNames) {
+    const worktreePath = join(projectDir, name);
+    gitCreateWorktree(name, worktreePath);
+    results.push({ path: worktreePath, branch: name });
+    logger.info(`worktree 创建完成: ${worktreePath} (分支: ${name})`);
+  }
+
+  return results;
+}
+
 /**
  * 获取当前项目在 ~/.clawt/worktrees/<project>/ 下的所有 worktree
  * 通过与 git worktree list 交叉验证确认有效性

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

@@ -25,19 +25,67 @@ vi.mock('../../../src/constants/index.js', () => ({
     INTERRUPT_CONFIRM_CLEANUP: '是否清理已创建的 worktree？',
     INTERRUPT_CLEANED: (count: number) => `已清理 ${count} 个 worktree`,
     INTERRUPT_KEPT: '已保留 worktree',
+    CONCURRENCY_INFO: (concurrency: number, total: number) => `并发限制: ${concurrency}，共 ${total} 个任务`,
+    CONCURRENCY_INVALID: '并发数必须为正整数',
+    FILE_AND_TASKS_CONFLICT: '--file 和 --tasks 不能同时使用',
+    BRANCH_OR_FILE_REQUIRED: '请指定 -b 或 -f',
+    TASK_FILE_LOADED: (count: number, path: string) => `✓ 从 ${path} 加载了 ${count} 个任务`,
+    TASK_FILE_MISSING_TASK_BY_INDEX: (blockIndex: number) => `第 ${blockIndex} 个任务块缺少任务描述`,
   },
 }));
 
-vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
-  validateClaudeCodeInstalled: vi.fn(),
-  createWorktrees: vi.fn(),
-  sanitizeBranchName: vi.fn(),
-  checkBranchExists: vi.fn(),
+/**
+ * mock utils/index.js —— run.ts 的直接依赖
+ * 注意：executeBatchTasks 不在此 mock，由 utils/index.js 的 re-export 指向 task-executor.js 的真实实现
+ */
+vi.mock('../../../src/utils/index.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../../src/utils/index.js')>();
+  return {
+    ...actual,
+    validateMainWorktree: vi.fn(),
+    validateClaudeCodeInstalled: vi.fn(),
+    createWorktrees: vi.fn(),
+    sanitizeBranchName: vi.fn(),
+    checkBranchExists: vi.fn(),
+    getConfigValue: vi.fn().mockReturnValue(0),
+    printSuccess: vi.fn(),
+    printError: vi.fn(),
+    printWarning: vi.fn(),
+    printInfo: vi.fn(),
+    printSeparator: vi.fn(),
+    printDoubleSeparator: vi.fn(),
+    confirmAction: vi.fn(),
+    launchInteractiveClaude: vi.fn(),
+    loadTaskFile: vi.fn(),
+    createWorktreesByBranches: vi.fn(),
+  };
+});
+
+/** task-executor.ts 内部依赖的具体模块 mock */
+vi.mock('../../../src/utils/shell.js', () => ({
   spawnProcess: vi.fn(),
   killAllChildProcesses: vi.fn(),
+  execCommand: vi.fn(),
+  execCommandWithInput: vi.fn(),
+}));
+
+vi.mock('../../../src/utils/worktree.js', () => ({
   cleanupWorktrees: vi.fn(),
-  getConfigValue: vi.fn(),
+  createWorktrees: vi.fn(),
+  getProjectWorktrees: vi.fn(),
+  getProjectWorktreeDir: vi.fn(),
+  getWorktreeStatus: vi.fn(),
+  createWorktreesByBranches: vi.fn(),
+}));
+
+vi.mock('../../../src/utils/config.js', () => ({
+  getConfigValue: vi.fn().mockReturnValue(0),
+  loadConfig: vi.fn(),
+  writeDefaultConfig: vi.fn(),
+  ensureClawtDirs: vi.fn(),
+}));
+
+vi.mock('../../../src/utils/formatter.js', () => ({
   printSuccess: vi.fn(),
   printError: vi.fn(),
   printWarning: vi.fn(),
@@ -45,25 +93,47 @@ vi.mock('../../../src/utils/index.js', () => ({
   printSeparator: vi.fn(),
   printDoubleSeparator: vi.fn(),
   confirmAction: vi.fn(),
-  launchInteractiveClaude: vi.fn(),
+  confirmDestructiveAction: vi.fn(),
+  formatWorktreeStatus: vi.fn(),
+  isWorktreeIdle: vi.fn(),
+  formatDuration: vi.fn(),
+}));
+
+vi.mock('../../../src/utils/progress.js', () => ({
+  ProgressRenderer: class {
+    start = vi.fn();
+    stop = vi.fn();
+    updateActivity = vi.fn();
+    markRunning = vi.fn();
+    markDone = vi.fn();
+    markFailed = vi.fn();
+  },
 }));
 
 import { registerRunCommand } from '../../../src/commands/run.js';
 import {
   createWorktrees,
+  createWorktreesByBranches,
   sanitizeBranchName,
   checkBranchExists,
-  spawnProcess,
   printSuccess,
   launchInteractiveClaude,
+  getConfigValue,
+  loadTaskFile,
 } from '../../../src/utils/index.js';
+import { spawnProcess } from '../../../src/utils/shell.js';
+import { printInfo } from '../../../src/utils/formatter.js';
 
 const mockedCreateWorktrees = vi.mocked(createWorktrees);
+const mockedCreateWorktreesByBranches = vi.mocked(createWorktreesByBranches);
 const mockedSanitizeBranchName = vi.mocked(sanitizeBranchName);
 const mockedCheckBranchExists = vi.mocked(checkBranchExists);
 const mockedSpawnProcess = vi.mocked(spawnProcess);
 const mockedPrintSuccess = vi.mocked(printSuccess);
+const mockedPrintInfo = vi.mocked(printInfo);
 const mockedLaunchInteractiveClaude = vi.mocked(launchInteractiveClaude);
+const mockedGetConfigValue = vi.mocked(getConfigValue);
+const mockedLoadTaskFile = vi.mocked(loadTaskFile);
 
 /**
  * 创建模拟子进程
@@ -78,12 +148,14 @@ function createMockChildProcess(stdout: string, exitCode: number) {
   child.stdout = stdoutStream;
   child.stderr = stderrStream;
   child.pid = 12345;
+  child.exitCode = null;
 
   // 延迟触发 close 事件
   setTimeout(() => {
     stdoutStream.push(stdout);
     stdoutStream.push(null);
     stderrStream.push(null);
+    child.exitCode = exitCode;
     child.emit('close', exitCode);
   }, 10);
 
@@ -92,11 +164,18 @@ function createMockChildProcess(stdout: string, exitCode: number) {
 
 beforeEach(() => {
   mockedCreateWorktrees.mockReset();
+  mockedCreateWorktreesByBranches.mockReset();
   mockedSanitizeBranchName.mockReset();
   mockedCheckBranchExists.mockReset();
   mockedSpawnProcess.mockReset();
   mockedPrintSuccess.mockReset();
+  mockedPrintInfo.mockReset();
   mockedLaunchInteractiveClaude.mockReset();
+  mockedGetConfigValue.mockReset();
+  mockedGetConfigValue.mockReturnValue(0 as any);
+  mockedLoadTaskFile.mockReset();
+  // sanitizeBranchName 默认返回输入值
+  mockedSanitizeBranchName.mockImplementation((name: string) => name);
 });
 
 describe('registerRunCommand', () => {
@@ -160,7 +239,6 @@ describe('handleRun', () => {
 
     expect(mockedCreateWorktrees).toHaveBeenCalledWith('feat', 2);
     expect(mockedSpawnProcess).toHaveBeenCalledTimes(2);
-    expect(mockedPrintSuccess).toHaveBeenCalled();
   });
 
   it('任务执行失败时在通知中报告', async () => {
@@ -192,6 +270,7 @@ describe('handleRun', () => {
     child.stdout = new Readable({ read() {} });
     child.stderr = new Readable({ read() {} });
     child.pid = 12345;
+    child.exitCode = null;
     setTimeout(() => {
       child.emit('error', new Error('spawn error'));
     }, 10);
@@ -204,4 +283,174 @@ describe('handleRun', () => {
 
     expect(mockedSpawnProcess).toHaveBeenCalledTimes(1);
   });
+
+  it('传 --concurrency 限制并发数', async () => {
+    const worktrees = [
+      { path: '/path/feat-1', branch: 'feat-1' },
+      { path: '/path/feat-2', branch: 'feat-2' },
+      { path: '/path/feat-3', branch: 'feat-3' },
+    ];
+    mockedCreateWorktrees.mockReturnValue(worktrees);
+
+    const jsonOutput = JSON.stringify({
+      is_error: false,
+      duration_ms: 5000,
+      total_cost_usd: 0.05,
+    });
+    mockedSpawnProcess
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0));
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+    await program.parseAsync(['run', '-b', 'feat', '--tasks', 'task1', 'task2', 'task3', '-c', '1'], { from: 'user' });
+
+    expect(mockedCreateWorktrees).toHaveBeenCalledWith('feat', 3);
+    // 所有任务都应执行完毕
+    expect(mockedSpawnProcess).toHaveBeenCalledTimes(3);
+    // 应输出并发限制提示
+    expect(mockedPrintInfo).toHaveBeenCalledWith(expect.stringContaining('并发限制'));
+  });
+
+  it('--concurrency 为 0 时不限制并发', async () => {
+    const worktrees = [
+      { path: '/path/feat-1', branch: 'feat-1' },
+      { path: '/path/feat-2', branch: 'feat-2' },
+    ];
+    mockedCreateWorktrees.mockReturnValue(worktrees);
+
+    const jsonOutput = JSON.stringify({
+      is_error: false,
+      duration_ms: 5000,
+      total_cost_usd: 0.05,
+    });
+    mockedSpawnProcess
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0));
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+    await program.parseAsync(['run', '-b', 'feat', '--tasks', 'task1', 'task2', '-c', '0'], { from: 'user' });
+
+    // 不限制并发时不输出并发限制提示
+    expect(mockedPrintInfo).not.toHaveBeenCalledWith(expect.stringContaining('并发限制'));
+    expect(mockedSpawnProcess).toHaveBeenCalledTimes(2);
+  });
+
+  it('未传 -c 时使用全局配置的 maxConcurrency', async () => {
+    mockedGetConfigValue.mockReturnValue(2 as any);
+
+    const worktrees = [
+      { path: '/path/feat-1', branch: 'feat-1' },
+      { path: '/path/feat-2', branch: 'feat-2' },
+      { path: '/path/feat-3', branch: 'feat-3' },
+    ];
+    mockedCreateWorktrees.mockReturnValue(worktrees);
+
+    const jsonOutput = JSON.stringify({
+      is_error: false,
+      duration_ms: 5000,
+      total_cost_usd: 0.05,
+    });
+    mockedSpawnProcess
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0));
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+    await program.parseAsync(['run', '-b', 'feat', '--tasks', 'task1', 'task2', 'task3'], { from: 'user' });
+
+    // 应输出并发限制提示（使用配置值 2）
+    expect(mockedPrintInfo).toHaveBeenCalledWith(expect.stringContaining('并发限制'));
+    expect(mockedSpawnProcess).toHaveBeenCalledTimes(3);
+  });
+
+  it('-f 从文件加载任务并执行（无 -b，使用文件中分支名）', async () => {
+    mockedLoadTaskFile.mockReturnValue([
+      { branch: 'feat-login', task: '实现登录功能' },
+      { branch: 'fix-bug', task: '修复问题' },
+    ]);
+    const worktrees = [
+      { path: '/path/feat-login', branch: 'feat-login' },
+      { path: '/path/fix-bug', branch: 'fix-bug' },
+    ];
+    mockedCreateWorktreesByBranches.mockReturnValue(worktrees);
+
+    const jsonOutput = JSON.stringify({
+      is_error: false,
+      duration_ms: 5000,
+      total_cost_usd: 0.05,
+    });
+    mockedSpawnProcess
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0));
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+    await program.parseAsync(['run', '-f', 'tasks.md'], { from: 'user' });
+
+    expect(mockedLoadTaskFile).toHaveBeenCalledWith('tasks.md', { branchRequired: true });
+    expect(mockedCreateWorktreesByBranches).toHaveBeenCalledWith(['feat-login', 'fix-bug']);
+    expect(mockedSpawnProcess).toHaveBeenCalledTimes(2);
+  });
+
+  it('-f + -b 模式使用 -b 自动编号', async () => {
+    mockedLoadTaskFile.mockReturnValue([
+      { task: '任务1' },
+      { task: '任务2' },
+    ]);
+    const worktrees = [
+      { path: '/path/feat-1', branch: 'feat-1' },
+      { path: '/path/feat-2', branch: 'feat-2' },
+    ];
+    mockedCreateWorktrees.mockReturnValue(worktrees);
+
+    const jsonOutput = JSON.stringify({
+      is_error: false,
+      duration_ms: 5000,
+      total_cost_usd: 0.05,
+    });
+    mockedSpawnProcess
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0))
+      .mockReturnValueOnce(createMockChildProcess(jsonOutput, 0));
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+    await program.parseAsync(['run', '-b', 'feat', '-f', 'tasks.md'], { from: 'user' });
+
+    // 应使用 createWorktrees（带 -b 自动编号），而非 createWorktreesByBranches
+    expect(mockedLoadTaskFile).toHaveBeenCalledWith('tasks.md', { branchRequired: false });
+    expect(mockedCreateWorktrees).toHaveBeenCalledWith('feat', 2);
+    expect(mockedCreateWorktreesByBranches).not.toHaveBeenCalled();
+    expect(mockedSpawnProcess).toHaveBeenCalledTimes(2);
+  });
+
+  it('-f 和 --tasks 互斥时报错', async () => {
+    mockedLoadTaskFile.mockReturnValue([{ branch: 'feat', task: '任务' }]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+
+    await expect(
+      program.parseAsync(['run', '-f', 'tasks.md', '--tasks', 'task1'], { from: 'user' }),
+    ).rejects.toThrow();
+  });
+
+  it('未传 -b 和 -f 时报错', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerRunCommand(program);
+
+    await expect(
+      program.parseAsync(['run', '--tasks', 'task1'], { from: 'user' }),
+    ).rejects.toThrow();
+  });
 });

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

@@ -30,6 +30,7 @@ describe('DEFAULT_CONFIG', () => {
     expect(DEFAULT_CONFIG.claudeCodeCommand).toBe('claude');
     expect(DEFAULT_CONFIG.autoPullPush).toBe(false);
     expect(DEFAULT_CONFIG.confirmDestructiveOps).toBe(true);
+    expect(DEFAULT_CONFIG.maxConcurrency).toBe(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, printSeparator, printDoubleSeparator, isWorktreeIdle } 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', () => {
@@ -110,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');
+  });
+});