clawt 3.2.1 → 3.3.0

package/README.md

@@ -203,6 +203,14 @@ clawt status -i       # 交互式面板模式（实时刷新，支持键盘导
 clawt reset
 ```
 
+### `clawt home` — 切换回主工作分支
+
+```bash
+clawt home
+```
+
+如果当前已在主工作分支上，会提示无需切换。
+
 ### `clawt projects` — 跨项目 worktree 概览
 
 ```bash

package/dist/index.js

@@ -473,6 +473,14 @@ var INIT_MESSAGES = {
   INIT_SET_SUCCESS: (key, value) => `\u2713 \u9879\u76EE\u914D\u7F6E ${key} \u5DF2\u8BBE\u7F6E\u4E3A ${value}`
 };
 
+// src/constants/messages/home.ts
+var HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch) => `\u5DF2\u5728\u4E3B\u5DE5\u4F5C\u5206\u652F ${branch} \u4E0A\uFF0C\u65E0\u9700\u5207\u6362`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from, to) => `\u2713 \u5DF2\u4ECE ${from} \u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${to}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -545,7 +553,8 @@ var MESSAGES = {
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
-  ...INIT_MESSAGES
+  ...INIT_MESSAGES,
+  ...HOME_MESSAGES
 };
 
 // src/constants/exitCodes.ts
@@ -5158,6 +5167,25 @@ async function handleInit(options) {
   }
 }
 
+// src/commands/home.ts
+function registerHomeCommand(program2) {
+  program2.command("home").description("\u5207\u6362\u56DE\u4E3B\u5DE5\u4F5C\u5206\u652F").action(async () => {
+    await handleHome();
+  });
+}
+async function handleHome() {
+  validateMainWorktree();
+  requireProjectConfig();
+  const mainBranch = getMainWorkBranch();
+  const currentBranch = getCurrentBranch();
+  if (currentBranch === mainBranch) {
+    printInfo(MESSAGES.HOME_ALREADY_ON_MAIN(mainBranch));
+    return;
+  }
+  await ensureOnMainWorkBranch();
+  printSuccess(MESSAGES.HOME_SWITCH_SUCCESS(currentBranch, mainBranch));
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -5184,6 +5212,7 @@ registerAliasCommand(program);
 registerProjectsCommand(program);
 registerCompletionCommand(program);
 registerInitCommand(program);
+registerHomeCommand(program);
 var config = loadConfig();
 applyAliases(program, config.aliases);
 process.on("uncaughtException", (error) => {

package/dist/postinstall.js

@@ -450,6 +450,14 @@ var INIT_MESSAGES = {
   INIT_SET_SUCCESS: (key, value) => `\u2713 \u9879\u76EE\u914D\u7F6E ${key} \u5DF2\u8BBE\u7F6E\u4E3A ${value}`
 };
 
+// src/constants/messages/home.ts
+var HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch) => `\u5DF2\u5728\u4E3B\u5DE5\u4F5C\u5206\u652F ${branch} \u4E0A\uFF0C\u65E0\u9700\u5207\u6362`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from, to) => `\u2713 \u5DF2\u4ECE ${from} \u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${to}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -502,7 +510,8 @@ var MESSAGES = {
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
-  ...INIT_MESSAGES
+  ...INIT_MESSAGES,
+  ...HOME_MESSAGES
 };
 
 // src/constants/terminal.ts

package/docs/home.md

@@ -0,0 +1,54 @@
+### 5.20 切换回主工作分支
+
+**命令：**
+
+```bash
+clawt home
+```
+
+**参数：**
+
+无参数。
+
+**功能说明：**
+
+快速切换回项目的主工作分支。当用户在主 worktree 中处于验证分支或其他分支时，可通过 `clawt home` 一键切换回 `clawtMainWorkBranch` 所记录的主工作分支。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **项目级配置校验**：调用 `requireProjectConfig()` 检查项目是否已初始化
+3. **获取分支信息**：
+   - 通过 `getMainWorkBranch()` 获取主工作分支名
+   - 通过 `getCurrentBranch()` 获取当前所在分支名
+4. **判断是否需要切换**：
+   - 当前分支 === 主工作分支 → 输出提示信息，无需切换
+   - 当前分支 !== 主工作分支 → 调用 `ensureOnMainWorkBranch()` 执行切换
+5. **输出结果**
+
+**输出格式：**
+
+```
+# 已在主工作分支上
+ℹ 已在主工作分支 main 上，无需切换
+
+# 切换成功
+✓ 已从 clawt-validate-feat-login 切换到主工作分支 main
+```
+
+**消息常量：**
+
+定义在 `src/constants/messages/home.ts`：
+
+| 常量 | 说明 |
+| --- | --- |
+| `HOME_ALREADY_ON_MAIN(branch)` | 已在主工作分支上，无需切换 |
+| `HOME_SWITCH_SUCCESS(from, to)` | 切换成功提示，显示原分支和目标分支 |
+
+**实现要点：**
+
+- 命令注册函数 `registerHomeCommand` 位于 `src/commands/home.ts`
+- 依赖 `validateMainWorktree`、`requireProjectConfig`、`ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch` 等工具函数
+- `requireProjectConfig()` 为显式调用，因为 home 命令不经过 `ensureOnMainWorkBranch()` 的隐式校验路径（仅在需要切换时才调用 `ensureOnMainWorkBranch()`）
+
+---

package/docs/spec.md

@@ -34,6 +34,7 @@
   - [5.17 自动更新检查](./update-check.md)
   - [5.18 跨项目 Worktree 概览](./projects.md)
   - [5.19 初始化项目级配置](./init.md)
+  - [5.20 切换回主工作分支](./home.md)
 - [6. 验证架构规则](#6-验证架构规则)
 - [7. 错误处理规范](#7-错误处理规范)
 - [8. 非功能性需求](#8-非功能性需求)
@@ -292,6 +293,7 @@ async function interactiveConfigEditor<T extends object>(
 | `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
 | `clawt completion`    | 为终端提供 shell 自动补全功能（bash/zsh）              | 5.16     |
 | `clawt projects`      | 展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情 | 5.17     |
+| `clawt home`          | 快速切换回主工作分支                                      | 5.20     |
 
 **全局选项：**
 
@@ -325,6 +327,7 @@ async function interactiveConfigEditor<T extends object>(
 - [5.17 自动更新检查](./update-check.md)
 - [5.18 跨项目 Worktree 概览](./projects.md)
 - [5.19 初始化项目级配置](./init.md)
+- [5.20 切换回主工作分支](./home.md)
 
 ---
 
@@ -333,12 +336,12 @@ async function interactiveConfigEditor<T extends object>(
 以下规则适用于验证分支架构的所有实现工作：
 
 1. **不兼容旧版本**：本次重构不考虑旧版本数据、旧版本创建的 worktree 或旧版本配置的兼容性。所有命令均假定验证分支和项目级配置已按新架构存在。用户需删除旧 worktree 后重新创建。
-2. **项目级配置前置校验**：仅对 create、run、validate、sync、remove、merge、reset 这 7 个核心命令添加检测，执行时必须先检查项目级配置（`~/.clawt/projects/<projectName>/config.json`）是否存在且包含 `clawtMainWorkBranch`。如果不存在，直接报错退出并提示用户先执行 `clawt init`：
+2. **项目级配置前置校验**：仅对 create、run、validate、sync、remove、merge、reset、home 这 8 个核心命令添加检测，执行时必须先检查项目级配置（`~/.clawt/projects/<projectName>/config.json`）是否存在且包含 `clawtMainWorkBranch`。如果不存在，直接报错退出并提示用户先执行 `clawt init`：
    ```
    ✗ 该项目尚未初始化，请先执行 clawt init -b<branchName>设置主工作分支
    ```
    其他命令（list、resume、config、status、alias、projects、completion）不受影响，无需添加该校验。
-   > **实现细节**：`ensureOnMainWorkBranch()` 内部已通过 `getMainWorkBranch()` → `requireProjectConfig()` 完成了项目配置校验，因此调用了 `ensureOnMainWorkBranch` 的命令（create、run、validate、merge）**无需再显式调用 `requireProjectConfig()`**，避免重复校验。sync 和 remove 命令因不依赖主 worktree 的分支状态而不调用 `ensureOnMainWorkBranch`，需自行显式调用 `requireProjectConfig()`。reset 命令同理，也需自行调用 `requireProjectConfig()`。
+   > **实现细节**：`ensureOnMainWorkBranch()` 内部已通过 `getMainWorkBranch()` → `requireProjectConfig()` 完成了项目配置校验，因此调用了 `ensureOnMainWorkBranch` 的命令（create、run、validate、merge）**无需再显式调用 `requireProjectConfig()`**，避免重复校验。sync 和 remove 命令因不依赖主 worktree 的分支状态而不调用 `ensureOnMainWorkBranch`，需自行显式调用 `requireProjectConfig()`。reset 和 home 命令同理，也需自行调用 `requireProjectConfig()`。
 3. **主分支名统一从项目级配置获取**：所有需要获取主分支名的场景（sync 中合并主分支、merge 中计算 merge-base、切回主分支等），统一使用项目级配置中的 `clawtMainWorkBranch`，不再通过 `getCurrentBranch(mainWorktreePath)` 动态获取。因为在新架构下，主 worktree 可能处于验证分支上，`getCurrentBranch` 会返回验证分支名而非真正的主工作分支名。
 4. **测试文件全量更新**：本次重构涉及的所有命令（init、create、run、validate、sync、remove、merge、reset），其对应的测试文件必须同步更新，确保覆盖新增的验证分支逻辑、项目级配置逻辑和变更后的流程。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/home.ts

@@ -0,0 +1,43 @@
+import type { Command } from 'commander';
+import { MESSAGES } from '../constants/index.js';
+import {
+  validateMainWorktree,
+  requireProjectConfig,
+  ensureOnMainWorkBranch,
+  getCurrentBranch,
+  getMainWorkBranch,
+  printSuccess,
+  printInfo,
+} from '../utils/index.js';
+
+/**
+ * 注册 home 命令：快速切换回主工作分支
+ * @param {Command} program - Commander 实例
+ */
+export function registerHomeCommand(program: Command): void {
+  program
+    .command('home')
+    .description('切换回主工作分支')
+    .action(async () => {
+      await handleHome();
+    });
+}
+
+/**
+ * 执行 home 命令：切换回主工作分支
+ */
+async function handleHome(): Promise<void> {
+  validateMainWorktree();
+  requireProjectConfig();
+
+  const mainBranch = getMainWorkBranch();
+  const currentBranch = getCurrentBranch();
+
+  if (currentBranch === mainBranch) {
+    printInfo(MESSAGES.HOME_ALREADY_ON_MAIN(mainBranch));
+    return;
+  }
+
+  await ensureOnMainWorkBranch();
+  printSuccess(MESSAGES.HOME_SWITCH_SUCCESS(currentBranch, mainBranch));
+}

package/src/constants/messages/home.ts

@@ -0,0 +1,7 @@
+/** home 命令专属提示消息 */
+export const HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch: string) => `已在主工作分支 ${branch} 上，无需切换`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from: string, to: string) => `✓ 已从 ${from} 切换到主工作分支 ${to}`,
+} as const;

package/src/constants/messages/index.ts

@@ -14,6 +14,7 @@ import { PROJECTS_MESSAGES } from './projects.js';
 import { COMPLETION_MESSAGES } from './completion.js';
 import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
 import { INIT_MESSAGES } from './init.js';
+import { HOME_MESSAGES } from './home.js';
 import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
@@ -40,4 +41,5 @@ export const MESSAGES = {
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
   ...INIT_MESSAGES,
+  ...HOME_MESSAGES,
 } as const;

package/src/index.ts

@@ -19,6 +19,7 @@ import { registerAliasCommand } from './commands/alias.js';
 import { registerProjectsCommand } from './commands/projects.js';
 import { registerCompletionCommand } from './commands/completion.js';
 import { registerInitCommand } from './commands/init.js';
+import { registerHomeCommand } from './commands/home.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -58,6 +59,7 @@ registerAliasCommand(program);
 registerProjectsCommand(program);
 registerCompletionCommand(program);
 registerInitCommand(program);
+registerHomeCommand(program);
 
 // 加载配置并应用命令别名
 const config = loadConfig();