clawt 1.0.0

package/src/types/claudeCode.ts

@@ -0,0 +1,14 @@
+/** Claude Code CLI 输出的 JSON 结果 */
+export interface ClaudeCodeResult {
+  type: string;
+  subtype: string;
+  is_error: boolean;
+  duration_ms: number;
+  duration_api_ms: number;
+  num_turns: number;
+  result: string;
+  stop_reason: string;
+  session_id: string;
+  total_cost_usd: number;
+  usage: Record<string, unknown>;
+}

package/src/types/command.ts

@@ -0,0 +1,39 @@
+/** create 命令选项 */
+export interface CreateOptions {
+  /** 分支名 */
+  branch: string;
+  /** 创建数量，默认 1 */
+  number: number;
+}
+
+/** run 命令选项 */
+export interface RunOptions {
+  /** 分支名 */
+  branch: string;
+  /** 任务列表（支持多次 --tasks 传入），不传则在 worktree 中打开 Claude Code 交互式界面 */
+  tasks?: string[];
+}
+
+/** validate 命令选项 */
+export interface ValidateOptions {
+  /** 要验证的分支名 */
+  branch: string;
+}
+
+/** merge 命令选项 */
+export interface MergeOptions {
+  /** 要合并的分支名 */
+  branch: string;
+  /** 提交信息（工作区有修改时必填） */
+  message?: string;
+}
+
+/** remove 命令选项 */
+export interface RemoveOptions {
+  /** 移除所有 worktree */
+  all?: boolean;
+  /** 分支名 */
+  branch?: string;
+  /** 指定索引 */
+  index?: number;
+}

package/src/types/config.ts

@@ -0,0 +1,7 @@
+/** clawt 全局配置 */
+export interface ClawtConfig {
+  /** 移除 worktree 时是否自动删除对应本地分支 */
+  autoDeleteBranch: boolean;
+  /** Claude Code CLI 启动指令（不传 --tasks 时在 worktree 中直接打开交互式界面） */
+  claudeCodeCommand: string;
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export type { ClawtConfig } from './config.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions } from './command.js';
+export type { WorktreeInfo } from './worktree.js';
+export type { ClaudeCodeResult } from './claudeCode.js';
+export type { TaskResult, TaskSummary } from './taskResult.js';

package/src/types/taskResult.ts

@@ -0,0 +1,31 @@
+import type { ClaudeCodeResult } from './claudeCode.js';
+
+/** 单个任务的执行结果 */
+export interface TaskResult {
+  /** 任务描述 */
+  task: string;
+  /** 分支名 */
+  branch: string;
+  /** worktree 路径 */
+  worktreePath: string;
+  /** 是否成功 */
+  success: boolean;
+  /** Claude Code 的输出结果 */
+  result: ClaudeCodeResult | null;
+  /** 错误信息（失败时） */
+  error?: string;
+}
+
+/** 所有任务的汇总信息 */
+export interface TaskSummary {
+  /** 总任务数 */
+  total: number;
+  /** 成功数 */
+  succeeded: number;
+  /** 失败数 */
+  failed: number;
+  /** 总耗时（毫秒） */
+  totalDurationMs: number;
+  /** 总花费（美元） */
+  totalCostUsd: number;
+}

package/src/types/worktree.ts

@@ -0,0 +1,7 @@
+/** worktree 信息 */
+export interface WorktreeInfo {
+  /** worktree 路径 */
+  path: string;
+  /** 分支名 */
+  branch: string;
+}

package/src/utils/branch.ts

@@ -0,0 +1,51 @@
+import { INVALID_BRANCH_CHARS, MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import { printWarning } from './formatter.js';
+import { checkBranchExists } from './git.js';
+import { ClawtError } from '../errors/index.js';
+
+/**
+ * 将分支名中的非法字符替换为 '-'，并压缩连续 '-'、去除首尾 '-'
+ * @param {string} branchName - 原始分支名
+ * @returns {string} 清理后的合法分支名
+ */
+export function sanitizeBranchName(branchName: string): string {
+  const sanitized = branchName
+    .replace(INVALID_BRANCH_CHARS, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '');
+
+  if (sanitized !== branchName) {
+    logger.warn(MESSAGES.BRANCH_SANITIZED(branchName, sanitized));
+    printWarning(MESSAGES.BRANCH_SANITIZED(branchName, sanitized));
+  }
+
+  return sanitized;
+}
+
+/**
+ * 根据基础分支名和数量生成分支名数组
+ * n=1 时返回 [branchName]，n>1 时返回 [branchName-1, ..., branchName-n]
+ * @param {string} branchName - 基础分支名
+ * @param {number} count - 数量
+ * @returns {string[]} 分支名数组
+ */
+export function generateBranchNames(branchName: string, count: number): string[] {
+  if (count === 1) {
+    return [branchName];
+  }
+  return Array.from({ length: count }, (_, i) => `${branchName}-${i + 1}`);
+}
+
+/**
+ * 校验所有分支名是否都不存在，有任何一个存在则抛出错误
+ * @param {string[]} branchNames - 分支名数组
+ * @throws {ClawtError} 分支已存在时抛出
+ */
+export function validateBranchesNotExist(branchNames: string[]): void {
+  for (const name of branchNames) {
+    if (checkBranchExists(name)) {
+      throw new ClawtError(MESSAGES.BRANCH_EXISTS(name));
+    }
+  }
+}

package/src/utils/config.ts

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { CONFIG_PATH, CLAWT_HOME, LOGS_DIR, WORKTREES_DIR, DEFAULT_CONFIG } from '../constants/index.js';
+import { ensureDir } from './fs.js';
+import type { ClawtConfig } from '../types/index.js';
+
+/**
+ * 加载全局配置，不存在则返回默认配置
+ * @returns {ClawtConfig} 配置对象
+ */
+export function loadConfig(): ClawtConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return { ...DEFAULT_CONFIG };
+  }
+  const raw = readFileSync(CONFIG_PATH, 'utf-8');
+  return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+}
+
+/**
+ * 获取配置中指定字段的值
+ * @param {keyof ClawtConfig} key - 配置字段名
+ * @returns {ClawtConfig[keyof ClawtConfig]} 配置值
+ */
+export function getConfigValue<K extends keyof ClawtConfig>(key: K): ClawtConfig[K] {
+  const config = loadConfig();
+  return config[key];
+}
+
+/**
+ * 确保 clawt 全局目录结构存在
+ */
+export function ensureClawtDirs(): void {
+  ensureDir(CLAWT_HOME);
+  ensureDir(LOGS_DIR);
+  ensureDir(WORKTREES_DIR);
+}

package/src/utils/formatter.ts

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { MESSAGES } from '../constants/index.js';
+import { createInterface } from 'node:readline';
+
+/**
+ * 输出成功信息
+ * @param {string} message - 消息内容
+ */
+export function printSuccess(message: string): void {
+  console.log(chalk.green(message));
+}
+
+/**
+ * 输出错误信息
+ * @param {string} message - 消息内容
+ */
+export function printError(message: string): void {
+  console.error(chalk.red(`✗ ${message}`));
+}
+
+/**
+ * 输出警告信息
+ * @param {string} message - 消息内容
+ */
+export function printWarning(message: string): void {
+  console.log(chalk.yellow(`⚠ ${message}`));
+}
+
+/**
+ * 输出普通信息
+ * @param {string} message - 消息内容
+ */
+export function printInfo(message: string): void {
+  console.log(message);
+}
+
+/**
+ * 输出分隔线
+ */
+export function printSeparator(): void {
+  console.log(MESSAGES.SEPARATOR);
+}
+
+/**
+ * 输出粗分隔线
+ */
+export function printDoubleSeparator(): void {
+  console.log(MESSAGES.DOUBLE_SEPARATOR);
+}
+
+/**
+ * 简易 yes/no 确认（非交互式场景使用）
+ * @param {string} question - 确认问题
+ * @returns {Promise<boolean>} 用户是否确认
+ */
+export function confirmAction(question: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(`${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}

package/src/utils/fs.ts

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
+
+/**
+ * 确保目录存在，不存在则递归创建
+ * @param {string} dirPath - 目录路径
+ */
+export function ensureDir(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * 如果目录为空则删除
+ * @param {string} dirPath - 目录路径
+ * @returns {boolean} 是否删除了目录
+ */
+export function removeEmptyDir(dirPath: string): boolean {
+  if (!existsSync(dirPath)) {
+    return false;
+  }
+  const entries = readdirSync(dirPath);
+  if (entries.length === 0) {
+    rmdirSync(dirPath);
+    return true;
+  }
+  return false;
+}

package/src/utils/git.ts

@@ -0,0 +1,243 @@
+import { basename } from 'node:path';
+import { execCommand } from './shell.js';
+import { logger } from '../logger/index.js';
+
+/**
+ * 获取 git common dir（用于判断是否为主 worktree）
+ * @param {string} cwd - 工作目录
+ * @returns {string} git common dir 路径
+ */
+export function getGitCommonDir(cwd?: string): string {
+  return execCommand('git rev-parse --git-common-dir', { cwd });
+}
+
+/**
+ * 获取 git 仓库根目录的绝对路径
+ * @param {string} cwd - 工作目录
+ * @returns {string} 仓库根目录路径
+ */
+export function getGitTopLevel(cwd?: string): string {
+  return execCommand('git rev-parse --show-toplevel', { cwd });
+}
+
+/**
+ * 获取项目名（仓库根目录名称）
+ * @param {string} cwd - 工作目录
+ * @returns {string} 项目名
+ */
+export function getProjectName(cwd?: string): string {
+  const topLevel = getGitTopLevel(cwd);
+  return basename(topLevel);
+}
+
+/**
+ * 检查本地分支是否存在
+ * @param {string} branchName - 分支名
+ * @param {string} cwd - 工作目录
+ * @returns {boolean} 分支是否存在
+ */
+export function checkBranchExists(branchName: string, cwd?: string): boolean {
+  try {
+    execCommand(`git show-ref --verify refs/heads/${branchName}`, { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 创建 worktree 并同时创建新分支
+ * @param {string} branchName - 新分支名
+ * @param {string} worktreePath - worktree 目录路径
+ * @param {string} cwd - 工作目录
+ */
+export function createWorktree(branchName: string, worktreePath: string, cwd?: string): void {
+  logger.info(`创建 worktree: ${worktreePath}`);
+  execCommand(`git worktree add -b ${branchName} "${worktreePath}"`, { cwd });
+}
+
+/**
+ * 强制移除 worktree
+ * @param {string} worktreePath - worktree 目录路径
+ * @param {string} cwd - 工作目录
+ */
+export function removeWorktreeByPath(worktreePath: string, cwd?: string): void {
+  logger.info(`移除 worktree: ${worktreePath}`);
+  execCommand(`git worktree remove -f "${worktreePath}"`, { cwd });
+}
+
+/**
+ * 强制删除本地分支
+ * @param {string} branchName - 分支名
+ * @param {string} cwd - 工作目录
+ */
+export function deleteBranch(branchName: string, cwd?: string): void {
+  logger.info(`删除分支: ${branchName}`);
+  execCommand(`git branch -D ${branchName}`, { cwd });
+}
+
+/**
+ * 获取工作区状态（git status --porcelain）
+ * @param {string} cwd - 工作目录
+ * @returns {string} porcelain 格式输出，为空表示干净
+ */
+export function getStatusPorcelain(cwd?: string): string {
+  return execCommand('git status --porcelain', { cwd });
+}
+
+/**
+ * 判断工作区是否干净
+ * @param {string} cwd - 工作目录
+ * @returns {boolean} 是否干净
+ */
+export function isWorkingDirClean(cwd?: string): boolean {
+  return getStatusPorcelain(cwd) === '';
+}
+
+/**
+ * git add 所有文件
+ * @param {string} cwd - 工作目录
+ */
+export function gitAddAll(cwd?: string): void {
+  execCommand('git add .', { cwd });
+}
+
+/**
+ * git commit
+ * @param {string} message - 提交信息
+ * @param {string} cwd - 工作目录
+ */
+export function gitCommit(message: string, cwd?: string): void {
+  execCommand(`git commit -m '${message.replace(/'/g, "'\\''")}'`, { cwd });
+}
+
+/**
+ * git merge
+ * @param {string} branchName - 要合并的分支名
+ * @param {string} cwd - 工作目录
+ */
+export function gitMerge(branchName: string, cwd?: string): void {
+  execCommand(`git merge ${branchName}`, { cwd });
+}
+
+/**
+ * 检查是否有合并冲突
+ * @param {string} cwd - 工作目录
+ * @returns {boolean} 是否有冲突
+ */
+export function hasMergeConflict(cwd?: string): boolean {
+  const status = getStatusPorcelain(cwd);
+  // UU = 双方修改冲突, AA = 双方新增冲突, DD = 双方删除
+  return status.split('\n').some((line) => /^(UU|AA|DD|DU|UD|AU|UA)/.test(line));
+}
+
+/**
+ * git pull
+ * @param {string} cwd - 工作目录
+ */
+export function gitPull(cwd?: string): void {
+  execCommand('git pull', { cwd });
+}
+
+/**
+ * git push
+ * @param {string} cwd - 工作目录
+ */
+export function gitPush(cwd?: string): void {
+  execCommand('git push', { cwd });
+}
+
+/**
+ * git reset --hard HEAD
+ * @param {string} cwd - 工作目录
+ */
+export function gitResetHard(cwd?: string): void {
+  execCommand('git reset --hard HEAD', { cwd });
+}
+
+/**
+ * git clean -fd（删除未跟踪文件）
+ * @param {string} cwd - 工作目录
+ */
+export function gitCleanForce(cwd?: string): void {
+  execCommand('git clean -fd', { cwd });
+}
+
+/**
+ * git stash push -m <message>
+ * @param {string} message - stash 消息
+ * @param {string} cwd - 工作目录
+ */
+export function gitStashPush(message: string, cwd?: string): void {
+  execCommand(`git stash push -m "${message}"`, { cwd });
+}
+
+/**
+ * git stash apply
+ * @param {string} cwd - 工作目录
+ */
+export function gitStashApply(cwd?: string): void {
+  execCommand('git stash apply', { cwd });
+}
+
+/**
+ * git stash pop stash@{index}
+ * @param {number} index - stash 索引
+ * @param {string} cwd - 工作目录
+ */
+export function gitStashPop(index: number = 0, cwd?: string): void {
+  execCommand(`git stash pop stash@{${index}}`, { cwd });
+}
+
+/**
+ * git stash list
+ * @param {string} cwd - 工作目录
+ * @returns {string} stash 列表输出
+ */
+export function gitStashList(cwd?: string): string {
+  try {
+    return execCommand('git stash list', { cwd });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * git restore --staged .
+ * @param {string} cwd - 工作目录
+ */
+export function gitRestoreStaged(cwd?: string): void {
+  execCommand('git restore --staged .', { cwd });
+}
+
+/**
+ * 获取 git worktree list 的输出
+ * @param {string} cwd - 工作目录
+ * @returns {string} worktree 列表
+ */
+export function gitWorktreeList(cwd?: string): string {
+  return execCommand('git worktree list', { cwd });
+}
+
+/**
+ * 执行 git worktree prune
+ * @param {string} cwd - 工作目录
+ */
+export function gitWorktreePrune(cwd?: string): void {
+  execCommand('git worktree prune', { cwd });
+}
+
+/**
+ * 检查目标分支相对于当前分支是否有本地提交
+ * @param {string} branchName - 目标分支名
+ * @param {string} cwd - 工作目录
+ * @returns {boolean} 是否有本地提交
+ */
+export function hasLocalCommits(branchName: string, cwd?: string): boolean {
+  try {
+    const output = execCommand(`git log HEAD..${branchName} --oneline`, { cwd });
+    return output.trim() !== '';
+  } catch {
+    return false;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,35 @@
+export { execCommand, spawnProcess, killAllChildProcesses } from './shell.js';
+export {
+  getGitCommonDir,
+  getGitTopLevel,
+  getProjectName,
+  checkBranchExists,
+  createWorktree,
+  removeWorktreeByPath,
+  deleteBranch,
+  getStatusPorcelain,
+  isWorkingDirClean,
+  gitAddAll,
+  gitCommit,
+  gitMerge,
+  hasMergeConflict,
+  gitPull,
+  gitPush,
+  gitResetHard,
+  gitCleanForce,
+  gitStashPush,
+  gitStashApply,
+  gitStashPop,
+  gitStashList,
+  gitRestoreStaged,
+  gitWorktreeList,
+  gitWorktreePrune,
+  hasLocalCommits,
+} from './git.js';
+export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
+export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
+export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees } from './worktree.js';
+export { loadConfig, getConfigValue, ensureClawtDirs } from './config.js';
+export { printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, confirmAction } from './formatter.js';
+export { ensureDir, removeEmptyDir } from './fs.js';
+export { multilineInput } from './prompt.js';

package/src/utils/prompt.ts

@@ -0,0 +1,18 @@
+import Enquirer from 'enquirer';
+
+/**
+ * 多行交互式输入框
+ * 使用 enquirer 的 Input prompt（multiline 模式）实现
+ * @param {string} message - 提示信息
+ * @returns {Promise<string>} 用户输入的文本内容
+ */
+export async function multilineInput(message: string): Promise<string> {
+  // @ts-expect-error enquirer 类型声明未导出 Input 类，但运行时存在
+  const prompt = new Enquirer.Input({
+    message,
+    multiline: true,
+  });
+
+  const result: string = await prompt.run();
+  return result;
+}

package/src/utils/shell.ts

@@ -0,0 +1,53 @@
+import { execSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
+import { logger } from '../logger/index.js';
+
+/**
+ * 同步执行 shell 命令并返回 stdout
+ * @param {string} command - 要执行的命令
+ * @param {object} options - 可选配置
+ * @param {string} options.cwd - 工作目录
+ * @returns {string} 命令的标准输出（已 trim）
+ * @throws {Error} 命令执行失败时抛出
+ */
+export function execCommand(command: string, options?: { cwd?: string }): string {
+  logger.debug(`执行命令: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ''}`);
+  const result = execSync(command, {
+    cwd: options?.cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.trim();
+}
+
+/**
+ * 以子进程方式异步执行命令
+ * @param {string} command - 要执行的命令
+ * @param {string[]} args - 命令参数
+ * @param {object} options - 可选配置
+ * @param {string} options.cwd - 工作目录
+ * @param {StdioOptions} options.stdio - stdio 配置，默认 ['pipe', 'pipe', 'pipe']
+ * @returns {ChildProcess} 子进程实例
+ */
+export function spawnProcess(
+  command: string,
+  args: string[],
+  options?: { cwd?: string; stdio?: StdioOptions },
+): ChildProcess {
+  logger.debug(`启动子进程: ${command} ${args.join(' ')}${options?.cwd ? ` (cwd: ${options.cwd})` : ''}`);
+  return spawn(command, args, {
+    cwd: options?.cwd,
+    stdio: options?.stdio ?? ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 终止所有正在运行的子进程
+ * @param {ChildProcess[]} children - 子进程列表
+ */
+export function killAllChildProcesses(children: ChildProcess[]): void {
+  for (const child of children) {
+    if (!child.killed) {
+      child.kill('SIGTERM');
+    }
+  }
+}

package/src/utils/validation.ts

@@ -0,0 +1,48 @@
+import { MESSAGES } from '../constants/index.js';
+import { ClawtError } from '../errors/index.js';
+import { execCommand } from './shell.js';
+import { getGitCommonDir } from './git.js';
+
+/**
+ * 校验当前目录是否为主 worktree 的根目录
+ * 条件：git rev-parse --git-common-dir === ".git"
+ * @throws {ClawtError} 不在主 worktree 根目录时抛出
+ */
+export function validateMainWorktree(): void {
+  try {
+    const gitCommonDir = getGitCommonDir();
+    if (gitCommonDir !== '.git') {
+      throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
+    }
+  } catch (error) {
+    if (error instanceof ClawtError) {
+      throw error;
+    }
+    // git 命令执行失败，可能不在 git 仓库中
+    throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
+  }
+}
+
+/**
+ * 校验 Git 是否已安装
+ * @throws {ClawtError} Git 未安装时抛出
+ */
+export function validateGitInstalled(): void {
+  try {
+    execCommand('git --version');
+  } catch {
+    throw new ClawtError(MESSAGES.GIT_NOT_INSTALLED);
+  }
+}
+
+/**
+ * 校验 Claude Code CLI 是否已安装
+ * @throws {ClawtError} Claude Code CLI 未安装时抛出
+ */
+export function validateClaudeCodeInstalled(): void {
+  try {
+    execCommand('claude --version');
+  } catch {
+    throw new ClawtError(MESSAGES.CLAUDE_NOT_INSTALLED);
+  }
+}