clawt 2.20.0 → 3.0.0

package/docs/status.md

@@ -0,0 +1,155 @@
+### 5.14 项目全局状态总览
+
+**命令：**
+
+```bash
+clawt status [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                     |
+| -------- | ---- | ---------------------------------------- |
+| `--json` | 否   | 以 JSON 格式输出完整状态数据              |
+
+**使用场景：**
+
+在管理多个 worktree 时，快速了解项目全局状态：主 worktree 当前分支及干净状态、所有 worktree 的变更情况和与主分支的同步状态、validate 快照摘要。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **收集主 worktree 状态**：
+   - 获取当前分支名（`getCurrentBranch()`）
+   - 检测工作区是否干净（`isWorkingDirClean()`）
+   - 获取项目名（`getProjectName()`）
+3. **收集各 worktree 详细状态**：
+   - 获取项目所有 worktree（`getProjectWorktrees()`）
+   - 对每个 worktree 收集以下信息：
+     - **变更状态**（优先级：合并冲突 > 未提交修改 > 已提交 > 无变更）
+     - **行数差异**（新增/删除行数，通过 `getDiffStat()` 获取）
+     - **提交差异**（相对于主分支的领先提交数 `getCommitCountAhead()` 和落后提交数 `getCommitCountBehind()`）
+     - **快照时间**（validate 快照文件的 mtime，通过 `getSnapshotModifiedTime()` 获取，返回 ISO 8601 时间字符串或 null）
+     - **分支创建时间**（通过 `getBranchCreatedAt()` 从 git reflog 获取分支创建时的时间戳）
+4. **收集 validate 快照摘要**：
+   - 通过 `getProjectSnapshotBranches()` 扫描快照目录下的 `.tree` 文件获取所有存在快照的分支名
+   - 统计快照总数和孤立快照数（对应 worktree 已不存在的快照）
+5. **输出状态信息**：
+   - 指定 `--json` → 以 JSON 格式输出完整状态数据（`JSON.stringify`）
+   - 未指定 → 以文本格式输出
+
+**文本输出格式（默认）：**
+
+输出分为三个区块：主 Worktree、Worktree 列表、Validate 快照摘要。每个 worktree 条目每行展示一种信息。
+
+```
+════════════════════════════════════════
+  项目状态总览: main-project
+════════════════════════════════════════
+
+  ◆ 主 Worktree
+    分支: main
+    状态: ✓ 干净
+
+────────────────────────────────────────
+
+  ◆ Worktree 列表 (2 个)
+
+  ● feature-login   [已提交]
+    +120 -30
+    3 个本地提交
+    与主分支同步
+    创建于 3 天前
+    上次验证: 2 小时前
+
+  ● feature-signup   [未提交修改]
+    +45 -10
+    1 个本地提交
+    落后主分支 2 个提交
+    创建于 1 天前
+    ✗ 未验证
+
+────────────────────────────────────────
+
+  ◆ Validate 快照 (3 个)
+    其中 1 个快照对应的 worktree 已不存在
+
+════════════════════════════════════════
+```
+
+**变更状态标签：**
+
+| 状态        | 标签           | 颜色   | 说明                          |
+| ----------- | -------------- | ------ | ----------------------------- |
+| `committed` | 已提交         | 绿色   | 有已提交内容，工作区干净       |
+| `uncommitted` | 未提交修改   | 黄色   | 有未提交的修改                 |
+| `conflict`  | 合并冲突       | 红色   | 存在合并冲突                   |
+| `clean`     | 无变更         | 灰色   | 工作区干净且无本地提交          |
+
+**差异统计展示规则（每项独立一行）：**
+
+- 行数变更（`+N -N`）：仅在有变更时展示，独立一行
+- 本地提交数（`N 个本地提交`）：仅在有提交时展示，独立一行（黄色）
+- 与主分支同步状态：始终展示，独立一行（落后时显示黄色，同步时显示绿色）
+
+**分支创建时间行：**
+
+- 通过 `getBranchCreatedAt()` 从 git reflog 获取分支创建时间，以 `formatRelativeTime()` 格式化为中文相对时间（如"3 天前"、"2 小时前"、"刚刚"）
+- 展示为灰色文本 `创建于 X前`，无法获取时不展示
+
+**验证状态行：**
+
+- 有快照时：显示绿色 `上次验证: X前`（通过 `getSnapshotModifiedTime()` 获取快照文件 mtime，再用 `formatRelativeTime()` 格式化）
+- 无快照时：显示红色 `✗ 未验证` 警示
+
+**快照区块：**
+
+- 标题显示快照总数
+- 如果存在孤立快照（对应 worktree 已不存在），显示黄色警告 `其中 N 个快照对应的 worktree 已不存在`
+- 无孤立快照时不显示额外信息
+
+**JSON 输出格式（`--json`）：**
+
+```json
+{
+  "main": {
+    "branch": "main",
+    "isClean": true,
+    "projectName": "main-project"
+  },
+  "worktrees": [
+    {
+      "path": "~/.clawt/worktrees/main-project/feature-login",
+      "branch": "feature-login",
+      "changeStatus": "committed",
+      "commitsAhead": 3,
+      "commitsBehind": 0,
+      "snapshotTime": "2025-02-06T12:30:00.000Z",
+      "insertions": 120,
+      "deletions": 30,
+      "createdAt": "2025-02-03T10:00:00.000Z"
+    }
+  ],
+  "snapshots": {
+    "total": 3,
+    "orphaned": 1
+  },
+  "totalWorktrees": 1
+}
+```
+
+**实现要点：**
+
+- 类型定义在 `src/types/status.ts`：`WorktreeDetailedStatus`（`hasSnapshot` 已改为 `snapshotTime: string | null`，新增 `createdAt: string | null`）、`MainWorktreeStatus`、`SnapshotInfo`、`SnapshotSummary`（新增，包含 `total` 和 `orphaned`）、`StatusResult`（`snapshots` 已从 `SnapshotInfo[]` 改为 `SnapshotSummary`）
+- 消息常量在 `MESSAGES.STATUS_*` 系列，新增：
+  - `STATUS_LAST_VALIDATED`：上次验证时间标签（如 `上次验证: 2 小时前`）
+  - `STATUS_NOT_VALIDATED`：未验证红色警示文本（`✗ 未验证`）
+  - `STATUS_CREATED_AT`：分支创建时间标签（如 `创建于 3 天前`）
+  - `STATUS_SNAPSHOT_ORPHANED`：改为接受数量参数的函数（如 `其中 1 个快照对应的 worktree 已不存在`）
+- `getBranchCreatedAt()` 是新增的工具函数（在 `src/utils/git.ts`），通过 `git reflog show <branch> --format=%cI` 获取 reflog 最后一条记录的时间戳（即分支创建时间），返回 ISO 8601 格式字符串或 null
+- `getSnapshotModifiedTime()` 是新增的工具函数（在 `src/utils/validate-snapshot.ts`），通过 `fs.statSync` 获取快照文件的修改时间（mtime），返回 UTC 时区的 ISO 8601 格式字符串（`toISOString()` 格式）或 null
+- `formatRelativeTime()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将 ISO 8601 日期字符串转换为中文相对时间描述（如"3 天前"、"2 小时前"、"刚刚"），无效日期时返回 null
+- `getCommitCountBehind()` 是新增的工具函数（在 `src/utils/git.ts`），通过 `git rev-list --count <branch>..HEAD` 计算落后提交数
+- `getProjectSnapshotBranches()` 是新增的工具函数（在 `src/utils/validate-snapshot.ts`），通过扫描快照目录下的 `.tree` 文件提取分支名列表
+
+---

package/docs/sync.md

@@ -0,0 +1,114 @@
+### 5.12 将主分支代码同步到目标 Worktree
+
+**命令：**
+
+```bash
+# 指定分支名（支持模糊匹配）
+clawt sync -b <branchName>
+
+# 不指定分支名（列出所有分支供选择）
+clawt sync
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                                     |
+| ---- | ---- | ------------------------------------------------------------------------ |
+| `-b` | 否   | 要同步的分支名（支持模糊匹配，不传则列出所有分支供选择）                   |
+
+**使用场景：**
+
+当目标 worktree 的分支需要使用主分支的最新代码继续工作时，通过 `clawt sync` 将主分支最新代码合并到目标 worktree。在新架构下，sync 不再是为了解决 validate 冲突（因为不会冲突了），而是纯粹的「将主分支最新代码同步到目标 worktree」的操作。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **项目配置校验**：调用 `requireProjectConfig()` 确保项目已初始化（存在 `clawtMainWorkBranch` 配置）
+3. **确保在主工作分支上**：`handleSync` 在执行核心逻辑前，调用 `ensureOnMainWorkBranch()` 确保当前处于主工作分支上。sync 命令需要从主分支发起合并操作，因此必须保证当前分支状态正确。
+4. **解析目标 worktree**：根据 `-b` 参数解析目标 worktree，匹配策略如下：
+   - **未传 `-b` 参数**：
+     - 获取当前项目所有 worktree
+     - 无可用 worktree → 报错退出
+     - 仅 1 个 worktree → 直接使用，无需选择
+     - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
+   - **传了 `-b` 参数**：
+     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+     2. **模糊匹配**（子串匹配，大小写不敏感）：
+        - 唯一匹配 → 直接使用
+        - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
+     3. **无匹配** → 报错退出，并列出所有可用分支名
+5. 调用 `executeSyncForBranch(targetWorktreePath, branch)` 执行核心同步逻辑
+
+#### `executeSyncForBranch` — sync 核心操作函数
+
+`executeSyncForBranch(targetWorktreePath: string, branch: string): Promise<SyncResult>` 是从 `handleSync` 中抽取的核心同步逻辑（async 函数），不包含 worktree 解析交互，供 validate 等命令复用。
+
+**接口定义：**
+
+```typescript
+/** sync 核心操作的执行结果 */
+export interface SyncResult {
+  /** 是否同步成功 */
+  success: boolean;
+  /** 是否存在合并冲突 */
+  hasConflict: boolean;
+}
+```
+
+**执行流程：**
+
+1. **获取主分支名**：通过项目级配置 `clawtMainWorkBranch` 获取主工作分支名（不再通过 `getCurrentBranch` 动态获取，因为在新架构下主 worktree 可能处于验证分支上）
+2. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
+   - 有修改 → 自动执行 `git add . && git commit -m "<AUTO_SAVE_COMMIT_MESSAGE>"` 保存变更（commit message 由常量 `AUTO_SAVE_COMMIT_MESSAGE` 定义，值为 `chore: auto-save before sync`，同时用于 merge 命令的 squash 检测）
+   - 无修改 → 跳过
+3. **在目标 worktree 中合并主分支**：
+   ```bash
+   cd ~/.clawt/worktrees/<project>/<branchName>
+   git merge <mainBranch>
+   ```
+4. **冲突处理**：
+   - **有冲突** → 输出警告，提示用户进入目标 worktree 手动解决：
+     ```
+     合并存在冲突，请进入目标 worktree 手动解决：
+       cd ~/.clawt/worktrees/<project>/<branchName>
+       解决冲突后执行 git add . && git merge --continue
+       clawt validate -b <branch> 验证变更
+     ```
+   - 返回 `{ success: false, hasConflict: true }`
+   - **无冲突** → 继续
+5. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
+6. **重建验证分支**（`rebuildValidateBranch`，async 函数）：sync 将主分支合并到目标 worktree 后，目标分支的代码基点发生变化。为保持验证分支与目标分支基点一致，需要重建验证分支。
+   - 确保在主工作分支上创建验证分支，处理三种情况：
+     - **已在主工作分支上** → 直接重建
+     - **在验证分支上** → 验证分支修改可丢弃，清理工作区后自动切回主工作分支
+     - **在其他普通分支上** → 检查工作区是否干净，干净则直接切回主工作分支；不干净则交互处理（`handleDirtyWorkingDir`：reset / stash / exit）后切回
+   ```bash
+   # 情况 1：已在主工作分支上，无需切换
+
+   # 情况 2：在验证分支上，先清理工作区再切回主分支
+   git reset --hard
+   git clean -fd
+   git checkout <clawtMainWorkBranch>
+
+   # 情况 3：在其他分支上
+   # 如果工作区不干净，交互式处理（reset/stash/exit）
+   # 然后切回主工作分支
+   git checkout <clawtMainWorkBranch>
+
+   # 删除旧验证分支
+   git branch -D clawt-validate-<branchName>
+
+   # 基于当前主分支 HEAD 重新创建验证分支
+   git branch clawt-validate-<branchName>
+   ```
+7. **输出成功提示**，然后执行 `rebuildValidateBranch` 重建验证分支，再输出验证分支重建提示，最后返回 `{ success: true, hasConflict: false }`：
+   ```
+   ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
+     验证分支 clawt-validate-<branchName> 已重建
+   ```
+
+#### validate 中自动 sync 的联动
+
+当 validate 的 patch apply 失败（兜底场景）并触发自动 sync 时，sync 内部会自动重建验证分支，validate 流程结束后用户重新执行 validate 即可。
+
+---

package/docs/update-check.md

@@ -0,0 +1,95 @@
+### 5.17 自动更新检查
+
+CLI 在每次命令执行完毕后，根据配置项 `autoUpdate` 决定是否检查 npm registry 上的最新版本。当发现新版本时，以带边框的提示框在终端输出版本更新信息和升级命令。
+
+#### 触发条件
+
+- 配置项 `autoUpdate` 为 `true`（默认启用）
+- 命令正常执行完毕后触发（在 `program.parseAsync()` 之后）
+
+#### 检查流程
+
+1. 读取缓存文件 `~/.clawt/update-check.json`
+2. 判断缓存是否有效：
+   - 缓存不存在或解析失败 → 视为过期
+   - 缓存中的 `currentVersion` 与本地版本不一致 → 视为过期
+   - 距离上次检查超过 24 小时 → 视为过期
+3. **缓存有效**：直接使用缓存中的 `latestVersion` 与本地版本比较，有新版本则打印提示
+4. **缓存过期**：向 npm registry 发起 HTTPS 请求获取最新版本号（5 秒超时），更新缓存文件后判断并打印提示
+
+#### 缓存文件
+
+**路径：** `~/.clawt/update-check.json`
+
+**结构：**
+
+```json
+{
+  "lastCheck": 1709000000000,
+  "latestVersion": "2.18.0",
+  "currentVersion": "2.17.1"
+}
+```
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `lastCheck` | `number` | 上次检查时间戳（毫秒） |
+| `latestVersion` | `string` | 从 registry 获取的最新版本号 |
+| `currentVersion` | `string` | 检查时的本地版本号 |
+
+#### 版本比较
+
+使用简易 semver 比较（不引入额外依赖），逐级比较 `major.minor.patch`：
+
+- `latest > current` → 提示更新
+- `latest <= current` → 不提示
+
+#### 包管理器检测
+
+更新提示中会显示与用户安装方式匹配的升级命令。检测逻辑依次尝试：
+
+1. `pnpm list -g --depth=0 clawt` → 匹配则提示 `pnpm add -g clawt`
+2. `yarn global list --depth=0` → 输出含 `clawt` 则提示 `yarn global add clawt`
+3. 以上均未匹配 → 默认提示 `npm i -g clawt`
+
+#### 提示框格式
+
+当检测到新版本时，输出带 Unicode 圆角边框的居中提示框：
+
+```
+╭──────────────────────────────────────────────╮
+│                                              │
+│   clawt 有新版本可用: 2.17.1 → 2.18.0       │
+│   执行 npm i -g clawt 进行更新               │
+│                                              │
+╰──────────────────────────────────────────────╯
+```
+
+版本号和命令使用 chalk 着色：当前版本红色、最新版本绿色、更新命令青色。
+
+#### 容错设计
+
+所有异常静默处理，不影响 CLI 正常功能：
+
+- 网络请求失败或超时（5 秒） → 静默忽略
+- registry 返回无效 JSON 或缺少 `version` 字段 → 静默忽略
+- 缓存文件读写失败 → 静默忽略
+- `checkForUpdates()` 入口函数的最外层 `try/catch` 确保任何未预期异常都不会中断 CLI
+
+#### 常量定义
+
+| 常量 | 值 | 位置 |
+| ---- | -- | ---- |
+| `UPDATE_CHECK_INTERVAL_MS` | `86400000`（24 小时） | `src/constants/update.ts` |
+| `NPM_REGISTRY_URL` | `https://registry.npmjs.org/clawt/latest` | `src/constants/update.ts` |
+| `NPM_REGISTRY_TIMEOUT_MS` | `5000` | `src/constants/update.ts` |
+| `PACKAGE_NAME` | `clawt` | `src/constants/update.ts` |
+| `UPDATE_CHECK_PATH` | `~/.clawt/update-check.json` | `src/constants/paths.ts` |
+
+#### 实现说明
+
+- 入口函数：`checkForUpdates()`（在 `src/utils/update-checker.ts`）
+- 消息常量：`UPDATE_MESSAGES`、`UPDATE_COMMANDS`（在 `src/constants/messages/update.ts`）
+- 入口调用点：`src/index.ts` 的 `main()` 异步函数中，`program.parseAsync()` 之后根据 `config.autoUpdate` 条件调用
+
+---