clawt 1.0.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "clawt",
+  "version": "1.0.0",
+  "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "clawt": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "postinstall": "node dist/postinstall.js"
+  },
+  "keywords": [
+    "claude",
+    "worktree",
+    "git",
+    "cli"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "enquirer": "^2.4.1",
+    "winston": "^3.17.0",
+    "winston-daily-rotate-file": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.ts

@@ -0,0 +1,116 @@
+/**
+ * postinstall 脚本：npm 全局安装后初始化 ~/.clawt/ 目录
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { DEFAULT_CONFIG } from '../src/constants/index.js';
+
+/** clawt 主目录 */
+const CLAWT_HOME = join(homedir(), '.clawt');
+/** 配置文件路径 */
+const CONFIG_PATH = join(CLAWT_HOME, 'config.json');
+/** 日志目录 */
+const LOGS_DIR = join(CLAWT_HOME, 'logs');
+/** worktree 目录 */
+const WORKTREES_DIR = join(CLAWT_HOME, 'worktrees');
+
+/**
+ * 确保目录存在，不存在则递归创建
+ * @param {string} dirPath - 目录路径
+ */
+function ensureDirectory(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * 读取已有的用户配置文件，解析失败时返回 null
+ * @param {string} configPath - 配置文件路径
+ * @returns {Record<string, unknown> | null} 解析后的配置对象，失败返回 null
+ */
+function loadExistingConfig(configPath: string): Record<string, unknown> | null {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 将用户配置与默认配置合并：
+ * - 新版本新增的 key → 使用默认值补充
+ * - 用户已有的 key → 保留用户值不覆盖
+ * - 新版本已移除的 key → 从用户配置中删除
+ * @param {Record<string, unknown>} existing - 用户已有配置
+ * @param {Record<string, unknown>} defaults - 新版本默认配置
+ * @returns {Record<string, unknown>} 合并后的配置对象
+ */
+function mergeConfig(
+  existing: Record<string, unknown>,
+  defaults: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+
+  // 以默认配置的 key 为基准，保留用户已有值，补充新增默认值
+  for (const key of Object.keys(defaults)) {
+    merged[key] = key in existing ? existing[key] : defaults[key];
+  }
+
+  // 默认配置中不存在的 key 不会被带入，即完成了旧配置的清理
+
+  return merged;
+}
+
+/**
+ * 写入配置文件并输出提示
+ * @param {string} configPath - 配置文件路径
+ * @param {Record<string, unknown>} config - 配置对象
+ * @param {string} message - 输出的提示信息
+ */
+function writeConfig(configPath: string, config: Record<string, unknown>, message: string): void {
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+  console.log(message);
+}
+
+/**
+ * 同步配置文件：不存在则创建，已存在则合并
+ * @param {string} configPath - 配置文件路径
+ * @param {Record<string, unknown>} defaultConfig - 默认配置
+ */
+function syncConfig(configPath: string, defaultConfig: Record<string, unknown>): void {
+  const existing = loadExistingConfig(configPath);
+
+  if (!existing) {
+    writeConfig(configPath, defaultConfig, `✓ 已创建默认配置文件: ${configPath}`);
+    return;
+  }
+
+  const merged = mergeConfig(existing, defaultConfig);
+
+  // 仅在配置发生变化时才写入
+  if (JSON.stringify(existing) !== JSON.stringify(merged)) {
+    writeConfig(configPath, merged, `✓ 已更新配置文件: ${configPath}`);
+  }
+}
+
+/**
+ * 初始化 ~/.clawt/ 目录结构和默认配置
+ */
+function init(): void {
+  ensureDirectory(CLAWT_HOME);
+  ensureDirectory(LOGS_DIR);
+  ensureDirectory(WORKTREES_DIR);
+
+  syncConfig(CONFIG_PATH, DEFAULT_CONFIG as unknown as Record<string, unknown>);
+
+  console.log('✓ clawt 初始化完成');
+}
+
+init();

package/src/commands/create.ts

@@ -0,0 +1,49 @@
+import type { Command } from 'commander';
+import { MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import type { CreateOptions } from '../types/index.js';
+import {
+  validateMainWorktree,
+  createWorktrees,
+  printSuccess,
+  printInfo,
+  printSeparator,
+} from '../utils/index.js';
+
+/**
+ * 注册 create 命令：批量创建 worktree 及对应分支
+ * @param {Command} program - Commander 实例
+ */
+export function registerCreateCommand(program: Command): void {
+  program
+    .command('create')
+    .description('批量创建 worktree 及对应分支')
+    .requiredOption('-b, --branch <branchName>', '分支名')
+    .option('-n, --number <count>', '创建数量', '1')
+    .action((options: CreateOptions) => {
+      handleCreate(options);
+    });
+}
+
+/**
+ * 执行 create 命令的核心逻辑
+ * @param {CreateOptions} options - 命令选项
+ */
+function handleCreate(options: CreateOptions): void {
+  validateMainWorktree();
+
+  const count = Number(options.number);
+  logger.info(`create 命令执行，分支: ${options.branch}，数量: ${count}`);
+
+  const worktrees = createWorktrees(options.branch, count);
+
+  printSuccess(MESSAGES.WORKTREE_CREATED(worktrees.length));
+  printInfo('');
+
+  worktrees.forEach((wt, index) => {
+    printInfo(`目录路径${index + 1}：`);
+    printInfo(`  ${wt.path}`);
+    printInfo(`  分支名: ${wt.branch}`);
+    printSeparator();
+  });
+}

package/src/commands/list.ts

@@ -0,0 +1,45 @@
+import type { Command } from 'commander';
+import { MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import {
+  validateMainWorktree,
+  getProjectName,
+  getProjectWorktrees,
+  printInfo,
+} from '../utils/index.js';
+
+/**
+ * 注册 list 命令：列出当前项目所有 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerListCommand(program: Command): void {
+  program
+    .command('list')
+    .description('列出当前项目所有 worktree')
+    .action(() => {
+      handleList();
+    });
+}
+
+/**
+ * 执行 list 命令的核心逻辑
+ */
+function handleList(): void {
+  validateMainWorktree();
+
+  const projectName = getProjectName();
+  const worktrees = getProjectWorktrees();
+
+  logger.info(`list 命令执行，项目: ${projectName}，共 ${worktrees.length} 个 worktree`);
+
+  printInfo(`当前项目: ${projectName}\n`);
+
+  if (worktrees.length === 0) {
+    printInfo(`  ${MESSAGES.NO_WORKTREES}`);
+  } else {
+    for (const wt of worktrees) {
+      printInfo(`  ${wt.path}   [${wt.branch}]`);
+    }
+    printInfo(`\n共 ${worktrees.length} 个 worktree`);
+  }
+}

package/src/commands/merge.ts

@@ -0,0 +1,142 @@
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import type { MergeOptions } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getGitTopLevel,
+  getProjectWorktreeDir,
+  isWorkingDirClean,
+  gitAddAll,
+  gitCommit,
+  gitMerge,
+  hasMergeConflict,
+  gitPull,
+  gitPush,
+  hasLocalCommits,
+  printSuccess,
+  printInfo,
+  getConfigValue,
+  confirmAction,
+  cleanupWorktrees,
+} from '../utils/index.js';
+
+/**
+ * 注册 merge 命令：合并验证过的分支到主 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerMergeCommand(program: Command): void {
+  program
+    .command('merge')
+    .description('合并某个已验证的 worktree 分支到主 worktree')
+    .requiredOption('-b, --branch <branchName>', '要合并的分支名')
+    .option('-m, --message <message>', '提交信息（工作区有修改时必填）')
+    .action(async (options: MergeOptions) => {
+      await handleMerge(options);
+    });
+}
+
+/**
+ * 判断 merge 成功后是否需要清理 worktree 和分支
+ * 如果全局配置了 autoDeleteBranch 则直接返回 true，否则询问用户
+ * @param {string} branchName - 分支名
+ * @returns {Promise<boolean>} 是否清理
+ */
+async function shouldCleanupAfterMerge(branchName: string): Promise<boolean> {
+  const autoDelete = getConfigValue('autoDeleteBranch');
+  if (autoDelete) {
+    printInfo(`已配置自动删除，merge 成功后将自动清理 worktree 和分支: ${branchName}`);
+    return true;
+  }
+  return confirmAction(`merge 成功后是否删除对应的 worktree 和分支 (${branchName})？`);
+}
+
+/**
+ * 清理已合并的 worktree 和对应分支
+ * @param {string} worktreePath - worktree 目录路径
+ * @param {string} branchName - 分支名
+ */
+function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): void {
+  cleanupWorktrees([{ path: worktreePath, branch: branchName }]);
+  printSuccess(MESSAGES.WORKTREE_CLEANED(branchName));
+}
+
+/**
+ * 执行 merge 命令的核心逻辑
+ * @param {MergeOptions} options - 命令选项
+ */
+async function handleMerge(options: MergeOptions): Promise<void> {
+  validateMainWorktree();
+
+  const mainWorktreePath = getGitTopLevel();
+  const projectDir = getProjectWorktreeDir();
+  const targetWorktreePath = join(projectDir, options.branch);
+
+  logger.info(`merge 命令执行，分支: ${options.branch}，提交信息: ${options.message ?? '(未提供)'}`);
+
+  // 检查目标 worktree 是否存在
+  if (!existsSync(targetWorktreePath)) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
+  }
+
+  // 步骤 3：主 worktree 状态检测
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
+  }
+
+  // merge 前确认是否清理 worktree 和分支
+  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
+
+  // 步骤 4：根据目标 worktree 状态决定是否需要提交
+  const targetClean = isWorkingDirClean(targetWorktreePath);
+
+  if (!targetClean) {
+    // 目标 worktree 有未提交修改，必须提供 -m
+    if (!options.message) {
+      throw new ClawtError(MESSAGES.TARGET_WORKTREE_DIRTY_NO_MESSAGE);
+    }
+    gitAddAll(targetWorktreePath);
+    gitCommit(options.message, targetWorktreePath);
+  } else {
+    // 目标 worktree 干净，检查是否有本地提交
+    if (!hasLocalCommits(options.branch, mainWorktreePath)) {
+      throw new ClawtError(MESSAGES.TARGET_WORKTREE_NO_CHANGES);
+    }
+    // 有本地提交，跳过提交步骤，直接合并
+  }
+
+  // 步骤 5：回到主 worktree 进行合并
+  try {
+    gitMerge(options.branch, mainWorktreePath);
+  } catch (error) {
+    // 检查是否有冲突
+    if (hasMergeConflict(mainWorktreePath)) {
+      throw new ClawtError(MESSAGES.MERGE_CONFLICT);
+    }
+    throw error;
+  }
+
+  // 步骤 6：冲突检测（二次确认）
+  if (hasMergeConflict(mainWorktreePath)) {
+    throw new ClawtError(MESSAGES.MERGE_CONFLICT);
+  }
+
+  // 步骤 7：推送
+  gitPull(mainWorktreePath);
+  gitPush(mainWorktreePath);
+
+  // 步骤 8：输出成功提示（根据是否有 message 选择对应模板）
+  if (options.message) {
+    printSuccess(MESSAGES.MERGE_SUCCESS(options.branch, options.message));
+  } else {
+    printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch));
+  }
+
+  // 步骤 9：merge 成功后清理 worktree 和分支
+  if (shouldCleanup) {
+    cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
+  }
+}

package/src/commands/remove.ts

@@ -0,0 +1,127 @@
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import type { RemoveOptions } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getProjectName,
+  getProjectWorktreeDir,
+  getProjectWorktrees,
+  removeWorktreeByPath,
+  deleteBranch,
+  getConfigValue,
+  gitWorktreePrune,
+  removeEmptyDir,
+  printInfo,
+  printSuccess,
+  confirmAction,
+} from '../utils/index.js';
+
+/**
+ * 注册 remove 命令：移除 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerRemoveCommand(program: Command): void {
+  program
+    .command('remove')
+    .description('移除 worktree（支持单个/批量/全部）')
+    .option('--all', '移除当前项目下所有 worktree')
+    .option('-b, --branch <branchName>', '指定分支名')
+    .option('-i, --index <index>', '指定索引（配合 -b 使用）')
+    .action(async (options: RemoveOptions) => {
+      await handleRemove(options);
+    });
+}
+
+/**
+ * 根据参数确定要移除的 worktree 列表
+ * @param {RemoveOptions} options - 命令选项
+ * @returns {Array<{path: string, branch: string}>} 待移除的 worktree 列表
+ */
+function resolveWorktreesToRemove(options: RemoveOptions): Array<{ path: string; branch: string }> {
+  const projectDir = getProjectWorktreeDir();
+  const allWorktrees = getProjectWorktrees();
+
+  if (options.all) {
+    return allWorktrees;
+  }
+
+  if (!options.branch) {
+    throw new ClawtError('请指定 --all 或 -b <branchName> 参数');
+  }
+
+  if (options.index !== undefined) {
+    // 单个移除：branchName-<index>
+    const targetName = `${options.branch}-${options.index}`;
+    const targetPath = join(projectDir, targetName);
+    const found = allWorktrees.find((wt) => wt.path === targetPath);
+    if (!found) {
+      throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(targetName));
+    }
+    return [found];
+  }
+
+  // 分支级移除：匹配 branchName 或 branchName-*
+  const matched = allWorktrees.filter(
+    (wt) => wt.branch === options.branch || wt.branch.startsWith(`${options.branch}-`),
+  );
+  if (matched.length === 0) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch!));
+  }
+  return matched;
+}
+
+/**
+ * 执行 remove 命令的核心逻辑
+ * @param {RemoveOptions} options - 命令选项
+ */
+async function handleRemove(options: RemoveOptions): Promise<void> {
+  validateMainWorktree();
+
+  const projectName = getProjectName();
+  logger.info(`remove 命令执行，项目: ${projectName}`);
+
+  const worktreesToRemove = resolveWorktreesToRemove(options);
+
+  if (worktreesToRemove.length === 0) {
+    printInfo(MESSAGES.NO_WORKTREES);
+    return;
+  }
+
+  // 列出即将移除的 worktree
+  printInfo('即将移除以下 worktree 及本地分支：\n');
+  worktreesToRemove.forEach((wt, index) => {
+    printInfo(`  ${index + 1}. ${wt.path}  →  分支: ${wt.branch}`);
+  });
+  printInfo('');
+
+  // 判断是否需要删除分支
+  const autoDelete = getConfigValue('autoDeleteBranch');
+  let shouldDeleteBranch = autoDelete;
+
+  if (!autoDelete) {
+    shouldDeleteBranch = await confirmAction('是否同时删除对应的本地分支？');
+  }
+
+  // 执行移除
+  for (const wt of worktreesToRemove) {
+    try {
+      removeWorktreeByPath(wt.path);
+      if (shouldDeleteBranch) {
+        deleteBranch(wt.branch);
+      }
+      printSuccess(MESSAGES.WORKTREE_REMOVED(wt.path));
+    } catch (error) {
+      logger.error(`移除 worktree 失败: ${wt.path} - ${error}`);
+      throw error;
+    }
+  }
+
+  // 清理 worktree 并清除空目录
+  gitWorktreePrune();
+  const projectDir = getProjectWorktreeDir();
+  removeEmptyDir(projectDir);
+}