@zjex/git-workflow 0.2.24 → 0.3.2

package/docs/commands/interactive.md

@@ -0,0 +1,384 @@
+# 交互式菜单
+
+交互式菜单是 Git Workflow 的核心界面，提供了直观、易用的操作方式，特别适合新手快速上手。
+
+## 🎯 启动主菜单
+
+### 基本用法
+
+```bash
+gw
+```
+
+直接运行 `gw` 命令即可启动交互式主菜单。
+
+### 主菜单界面
+
+```
+ ███████╗     ██╗███████╗██╗  ██╗
+ ╚══███╔╝     ██║██╔════╝╚██╗██╔╝
+   ███╔╝      ██║█████╗   ╚███╔╝
+  ███╔╝  ██   ██║██╔══╝   ██╔██╗
+ ███████╗╚█████╔╝███████╗██╔╝ ██╗
+ ╚══════╝ ╚════╝ ╚══════╝╚═╝  ╚═╝
+
+  git-workflow v0.2.24
+
+? 选择操作:
+  [1] ✨ 创建 feature 分支      gw f
+  [2] 🐛 创建 hotfix 分支       gw h
+  [3] 🗑️  删除分支               gw d
+  [4] 📝 提交代码               gw c
+  [5] 🏷️  创建 tag               gw t
+  [6] 🗑️  删除 tag               gw td
+  [7] ✏️  修改 tag               gw tu
+  [8] 📋 列出 tags              gw ts
+  [9] 📦 发布版本               gw r
+  [a] 💾 管理 stash             gw s
+  [b] ⚙️  初始化配置             gw init
+  [0] ❓ 帮助
+  [q] 退出
+```
+
+## 🎨 界面特性
+
+### ASCII Art Logo
+
+主菜单顶部显示精美的 ASCII Art Logo：
+- 使用绿色高亮显示
+- 展示项目品牌标识
+- 包含版本号信息
+
+### 功能分类
+
+菜单项按功能类型进行分组：
+
+#### 分支管理
+- `[1]` **创建 feature 分支** - 日常功能开发
+- `[2]` **创建 hotfix 分支** - 紧急问题修复
+- `[3]` **删除分支** - 清理无用分支
+
+#### 代码管理
+- `[4]` **提交代码** - AI 智能提交或手动提交
+- `[a]` **管理 stash** - 可视化 stash 管理
+
+#### 版本管理
+- `[5]` **创建 tag** - 创建版本标签
+- `[6]` **删除 tag** - 删除版本标签
+- `[7]` **修改 tag** - 修改标签信息
+- `[8]` **列出 tags** - 查看所有标签
+- `[9]` **发布版本** - 更新 package.json 版本
+
+#### 工具管理
+- `[b]` **初始化配置** - 创建配置文件
+- `[0]` **帮助** - 查看帮助信息
+- `[q]` **退出** - 退出程序
+
+### 快捷键设计
+
+每个功能都有对应的快捷键：
+- **数字键** - 主要功能（1-9）
+- **字母键** - 辅助功能（a, b）
+- **特殊键** - 系统功能（0, q）
+
+### 命令提示
+
+每个菜单项都显示对应的命令行快捷方式：
+```
+[1] ✨ 创建 feature 分支      gw f
+```
+- 左侧：快捷键和功能描述
+- 右侧：对应的命令行命令
+
+## ⌨️ 操作方式
+
+### 键盘操作
+
+| 按键       | 功能                     |
+| ---------- | ------------------------ |
+| 数字键 1-9 | 选择对应的主要功能       |
+| 字母键 a-z | 选择对应的辅助功能       |
+| 方向键 ↑↓  | 上下移动选择             |
+| 回车键     | 确认选择                 |
+| q 键       | 退出程序                 |
+| Ctrl+C     | 优雅退出                 |
+
+### 选择方式
+
+#### 直接按键选择（推荐）
+
+```bash
+gw
+# 直接按数字键 1，立即执行创建 feature 分支
+# 直接按字母键 a，立即执行管理 stash
+```
+
+#### 方向键选择
+
+```bash
+gw
+# 使用 ↑↓ 方向键移动光标
+# 按回车键确认选择
+```
+
+### 退出方式
+
+- **q 键** - 正常退出
+- **Ctrl+C** - 强制退出（优雅处理）
+- **选择退出选项** - 通过菜单选择退出
+
+## 🔄 自动更新检查
+
+### 版本检查
+
+主菜单启动时会自动检查更新：
+
+```bash
+gw
+# 检查更新中...
+# 
+# 🎉 发现新版本！
+# 当前版本: v0.2.24
+# 最新版本: v0.2.25
+# 
+# 是否现在更新? (y/N)
+```
+
+### 更新提示
+
+- **非阻塞检查** - 不影响正常使用
+- **智能提醒** - 只在有新版本时提示
+- **可选更新** - 用户可以选择是否更新
+
+## 🎯 使用场景
+
+### 场景一：新手入门
+
+```bash
+# 第一次使用，不熟悉命令
+gw
+
+# 通过菜单了解所有功能
+# 选择需要的操作
+# 跟随交互式引导完成操作
+```
+
+### 场景二：功能探索
+
+```bash
+# 想了解工具的所有功能
+gw
+
+# 浏览完整的功能列表
+# 尝试不同的功能
+# 学习对应的命令行快捷方式
+```
+
+### 场景三：偶尔使用
+
+```bash
+# 不经常使用，忘记了具体命令
+gw
+
+# 通过菜单快速找到需要的功能
+# 无需记忆复杂的命令参数
+```
+
+### 场景四：团队演示
+
+```bash
+# 向团队成员演示工具功能
+gw
+
+# 清晰的界面展示所有功能
+# 直观的操作流程
+# 专业的视觉效果
+```
+
+## 🔧 自定义配置
+
+### 禁用更新检查
+
+如果不希望在交互式模式下检查更新：
+
+```json
+{
+  "checkUpdates": false
+}
+```
+
+### 自定义启动消息
+
+```json
+{
+  "welcomeMessage": "欢迎使用 Git Workflow！"
+}
+```
+
+### 菜单项自定义
+
+```json
+{
+  "menuItems": {
+    "feature": {
+      "enabled": true,
+      "label": "创建功能分支",
+      "shortcut": "f"
+    },
+    "hotfix": {
+      "enabled": true,
+      "label": "创建修复分支",
+      "shortcut": "h"
+    }
+  }
+}
+```
+
+## 🎨 主题和样式
+
+### 颜色方案
+
+主菜单使用统一的颜色方案：
+
+- **绿色** - Logo 和成功信息
+- **黄色** - 版本号和重要提示
+- **蓝色** - 命令和链接
+- **灰色** - 辅助信息
+- **白色** - 主要文本
+
+### 图标系统
+
+每个功能都有对应的 emoji 图标：
+
+- ✨ **feature** - 新功能，闪亮的星星
+- 🐛 **hotfix** - Bug 修复，小虫子
+- 🗑️ **delete** - 删除操作，垃圾桶
+- 📝 **commit** - 提交代码，备忘录
+- 🏷️ **tag** - 版本标签，标签
+- 📦 **release** - 版本发布，包裹
+- 💾 **stash** - 代码暂存，软盘
+- ⚙️ **config** - 配置管理，齿轮
+
+### 响应式布局
+
+主菜单会根据终端宽度自动调整：
+
+- **宽屏** - 显示完整的 Logo 和描述
+- **窄屏** - 简化显示，保持可读性
+- **最小宽度** - 确保基本功能可用
+
+## 🚀 性能优化
+
+### 快速启动
+
+- **延迟加载** - 只在需要时加载功能模块
+- **缓存机制** - 缓存常用信息
+- **异步检查** - 更新检查不阻塞界面
+
+### 内存优化
+
+- **按需加载** - 避免加载不必要的模块
+- **及时清理** - 操作完成后清理资源
+- **轻量依赖** - 使用轻量级的依赖库
+
+## 🔍 调试和故障排除
+
+### 调试模式
+
+启用详细日志：
+
+```bash
+DEBUG=gw:menu gw
+```
+
+### 常见问题
+
+#### 问题一：菜单显示异常
+
+```bash
+# 终端不支持 Unicode 字符
+# 解决方案：使用支持 Unicode 的终端
+```
+
+#### 问题二：颜色显示异常
+
+```bash
+# 终端不支持颜色
+# 解决方案：使用支持 ANSI 颜色的终端
+```
+
+#### 问题三：按键无响应
+
+```bash
+# 终端输入模式问题
+# 解决方案：重新启动终端或使用方向键选择
+```
+
+## 📚 相关功能
+
+### 命令行模式
+
+对于熟练用户，可以直接使用命令行：
+
+```bash
+# 直接执行功能，跳过菜单
+gw f    # 创建 feature 分支
+gw c    # 提交代码
+gw t    # 创建 tag
+```
+
+### 帮助系统
+
+```bash
+# 查看帮助信息
+gw --help
+gw -h
+
+# 或在菜单中选择帮助选项
+gw
+# 选择 [0] 帮助
+```
+
+### 版本信息
+
+```bash
+# 查看版本号
+gw --version
+gw -v
+```
+
+## 💡 使用技巧
+
+### 技巧一：快速操作
+
+```bash
+# 启动后直接按对应数字键
+gw
+1  # 立即创建 feature 分支
+```
+
+### 技巧二：学习命令
+
+```bash
+# 通过菜单学习对应的命令行快捷方式
+# 熟悉后可以直接使用命令行模式
+```
+
+### 技巧三：功能探索
+
+```bash
+# 定期浏览主菜单，发现新功能
+# 尝试不同的操作组合
+```
+
+### 技巧四：团队培训
+
+```bash
+# 使用交互式菜单进行团队培训
+# 直观展示所有功能
+# 降低学习成本
+```
+
+---
+
+交互式菜单是 Git Workflow 的门面，为用户提供了友好、直观的操作界面。无论是新手入门还是功能探索，都能通过主菜单快速找到需要的功能。

package/docs/commands/release.md

@@ -0,0 +1,300 @@
+# Release 命令
+
+版本发布相关的命令详解。
+
+## 📋 命令概览
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `gw release` | `gw r` | 交互式版本发布 |
+
+## 📦 版本发布
+
+### 基本用法
+
+```bash
+gw release
+gw r
+```
+
+### 发布流程
+
+```bash
+$ gw r
+📦 版本发布
+
+当前版本: 0.2.24
+package.json: /path/to/your/project/package.json
+
+? 选择新版本:
+❯ patch   → 0.2.25
+  minor   → 0.3.0
+  major   → 1.0.0
+  alpha   → 0.2.25-alpha.1
+  beta    → 0.2.25-beta.1
+  rc      → 0.2.25-rc.1
+  自定义...
+
+✔ 版本号已更新: 0.2.24 → 0.2.25
+✔ package.json 已更新
+```
+
+## 🔢 版本类型
+
+### 标准版本
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `patch` | 补丁版本，Bug 修复 | 0.2.24 → 0.2.25 |
+| `minor` | 次版本，新功能 | 0.2.24 → 0.3.0 |
+| `major` | 主版本，破坏性变更 | 0.2.24 → 1.0.0 |
+
+### 预发布版本
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `alpha` | 内部测试版 | 0.2.24 → 0.2.25-alpha.1 |
+| `beta` | 公开测试版 | 0.2.24 → 0.2.25-beta.1 |
+| `rc` | 发布候选版 | 0.2.24 → 0.2.25-rc.1 |
+
+### 自定义版本
+
+```bash
+? 选择新版本: 自定义...
+
+? 输入自定义版本号: 2.0.0-beta.1
+
+✔ 版本号已更新: 0.2.24 → 2.0.0-beta.1
+```
+
+## 📝 package.json 更新
+
+工具会自动更新 `package.json` 中的版本号：
+
+### 更新前
+
+```json
+{
+  "name": "@zjex/git-workflow",
+  "version": "0.2.24",
+  "description": "Git workflow CLI tool"
+}
+```
+
+### 更新后
+
+```json
+{
+  "name": "@zjex/git-workflow",
+  "version": "0.2.25",
+  "description": "Git workflow CLI tool"
+}
+```
+
+## 🔄 预发布版本处理
+
+### 当前为预发布版本
+
+如果当前版本是预发布版本，会提供额外选项：
+
+```bash
+当前版本: 1.0.0-beta.1
+
+? 选择新版本:
+❯ pre     → 1.0.0-beta.2    # 升级预发布版本
+  release → 1.0.0           # 转为正式版本
+  patch   → 1.0.1           # 跳过当前，升级 patch
+  minor   → 1.1.0           # 跳过当前，升级 minor
+  major   → 2.0.0           # 跳过当前，升级 major
+  alpha   → 1.0.1-alpha.1   # 新的 alpha 版本
+  beta    → 1.0.1-beta.1    # 新的 beta 版本
+  rc      → 1.0.1-rc.1      # 新的 rc 版本
+```
+
+## 🎯 使用场景
+
+### 日常开发
+
+```bash
+# 修复 bug 后发布补丁版本
+gw r
+# 选择 patch → 1.0.0 → 1.0.1
+```
+
+### 功能发布
+
+```bash
+# 添加新功能后发布次版本
+gw r
+# 选择 minor → 1.0.0 → 1.1.0
+```
+
+### 重大更新
+
+```bash
+# 破坏性变更后发布主版本
+gw r
+# 选择 major → 1.0.0 → 2.0.0
+```
+
+### 测试版本
+
+```bash
+# 发布内部测试版
+gw r
+# 选择 alpha → 1.0.0 → 1.0.1-alpha.1
+
+# 发布公开测试版
+gw r
+# 选择 beta → 1.0.1-alpha.1 → 1.0.1-beta.1
+
+# 发布候选版本
+gw r
+# 选择 rc → 1.0.1-beta.1 → 1.0.1-rc.1
+
+# 发布正式版本
+gw r
+# 选择 release → 1.0.1-rc.1 → 1.0.1
+```
+
+## 🔗 与其他命令配合
+
+### 完整发布流程
+
+```bash
+# 1. 完成开发并提交
+gw c
+
+# 2. 更新版本号
+gw r
+
+# 3. 创建版本标签
+gw t
+
+# 4. 推送到远程
+git push origin main --tags
+```
+
+### 自动化脚本
+
+可以结合其他工具创建自动化发布脚本：
+
+```bash
+#!/bin/bash
+# release.sh
+
+# 运行测试
+npm test
+
+# 构建项目
+npm run build
+
+# 更新版本
+gw release
+
+# 创建 tag
+gw tag
+
+# 推送更改
+git push origin main --tags
+
+# 发布到 npm
+npm publish
+```
+
+## 📋 版本规范
+
+### 语义化版本
+
+遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 规范：
+
+```
+主版本号.次版本号.修订号[-预发布版本号]
+
+例如：
+1.0.0        - 正式版本
+1.0.1        - 补丁版本
+1.1.0        - 次版本
+2.0.0        - 主版本
+1.0.0-alpha.1 - 预发布版本
+```
+
+### 版本号含义
+
+**主版本号（MAJOR）**：
+- 不兼容的 API 修改
+- 重大架构变更
+- 破坏性变更
+
+**次版本号（MINOR）**：
+- 向下兼容的功能性新增
+- 新特性添加
+- 功能增强
+
+**修订号（PATCH）**：
+- 向下兼容的问题修正
+- Bug 修复
+- 安全补丁
+
+### 预发布版本
+
+**Alpha 版本**：
+- 内部测试版本
+- 功能不完整
+- 可能有严重 bug
+
+**Beta 版本**：
+- 公开测试版本
+- 功能基本完整
+- 可能有小 bug
+
+**RC 版本**：
+- 发布候选版本
+- 功能完整
+- 准备正式发布
+
+## 🚀 最佳实践
+
+### 版本发布策略
+
+1. **开发阶段** - 使用 alpha 版本
+2. **测试阶段** - 使用 beta 版本
+3. **预发布** - 使用 rc 版本
+4. **正式发布** - 使用标准版本
+
+### 版本号管理
+
+1. **保持一致** - 所有相关文件版本号同步
+2. **遵循规范** - 严格按照语义化版本规范
+3. **记录变更** - 维护 CHANGELOG 文件
+4. **标签同步** - 版本发布后创建对应 tag
+
+### 团队协作
+
+1. **统一流程** - 团队使用相同的发布流程
+2. **权限控制** - 限制版本发布权限
+3. **自动化** - 使用 CI/CD 自动化发布
+4. **通知机制** - 版本发布后及时通知团队
+
+### 错误处理
+
+如果版本更新出错：
+
+```bash
+# 手动回滚 package.json
+git checkout HEAD -- package.json
+
+# 或者使用 git reset
+git reset --hard HEAD~1
+```
+
+### 发布检查清单
+
+发布前确认：
+
+- [ ] 所有测试通过
+- [ ] 代码已提交
+- [ ] 文档已更新
+- [ ] CHANGELOG 已更新
+- [ ] 版本号符合规范
+- [ ] 没有未完成的功能