long-git-cli/README.md

A CLI tool for Git tag management.

# Long CLI

一个支持 Bitbucket/GitHub/GitLab 的 Git tag/commit 自动化命令行工具，基于 TypeScript，结构高度可扩展。

## 安装

```bash
npm install -g long-git-cli
```

或本地开发：
```bash
npm install
npm run build
npm link
```

## 支持命令

### 自动打 tag
```bash
long tag
```
- 拉取最新 tag，自动递增（格式：`test-v00.00.0000`）
- 检查分支（禁止在 master/main/release 上打 tag）
- 自动推送到远程仓库（Bitbucket/GitHub/GitLab 均支持）
- 友好提示 tag 结果

### 规范化 commit 并 push
```bash
long commit
```
- 自动 git add .
- 打印所有将要提交的文件，需用户确认
- 交互式收集 commit 信息（类型、范围、说明、描述、脚注，参考 Angular/commitizen 规范）
- 生成规范化 commit message
- commit 后再次确认，自动 push
- 支持 Bitbucket/GitHub/GitLab，push 后友好提示

### 快速部署（frontend-msg-admin 专用）
```bash
long deploy
```
- 专门为 `frontend-msg-admin` 项目定制的快速部署工具
- 支持 4 个测试环境：test-01, test-02, test-03, test-04
- 自动创建 tag 并触发构建和部署
- 实时监听构建和部署状态
- 支持在仓库目录内外执行

**使用方式**：

```bash
# 交互式选择环境
long deploy

# 直接指定环境（1-4）
long deploy -e 1
long deploy --env 2

# 测试 Bitbucket 和 Jenkins 连接
long deploy --test
long deploy -t
```

**首次使用**：

1. 运行 `long config` 打开 Web UI 配置界面
2. 配置 Bitbucket API Token 和 Jenkins API Token
3. 配置完成后运行 `long deploy --test` 测试连接
4. 测试通过后即可使用 `long deploy` 命令部署

**硬编码配置**：

- **Bitbucket**: `https://bitbucket.org/vantagefxcrm/frontend-msg-admin`
- **Jenkins**: `https://jenkins.app-alpha.com`
- **环境**: test-01, test-02, test-03, test-04

**执行流程**：

1. 检查 API Token 配置
2. 选择部署环境（1-4）
3. 验证仓库路径
   - 在目标仓库目录：使用本地 Git 创建 tag
   - 不在目标仓库目录：通过 API 创建 tag
4. 监听构建状态（AWS CodeBuild）
5. 触发 Jenkins 部署
6. 监听部署状态
7. 显示部署结果

### 配置管理
```bash
long config
```
- 打开 Web UI 配置界面
- 配置 Bitbucket 和 Jenkins API Token
- 配置项目和环境信息（用于 Web UI）



## 交互流程示例

#### long tag
```
🚀 开始自动打 tag...
📥 拉取最新的远程信息...
📋 当前最新 tag: test-v00.00.0001
🆕 新 tag: test-v00.00.0002
🏷️  创建 tag: test-v00.00.0002
✅ Tag test-v00.00.0002 创建成功
📤 推送 tag 到远程仓库...
✅ Tag 推送成功
🔗 你可以在 Bitbucket 上查看新创建的 tag
💡 提示：在 Bitbucket 中，你可以在 "Tags" 页面查看所有 tag
✅ Tag 创建并推送成功！
```

#### long commit
```
📝 本次将要提交的文件：
  src/commands/commit.ts
请确认以上文件是否全部需要提交？ (Y/n)
请选择提交类型（必选）： feat
影响范围（可选，如模块名，直接回车跳过）：core
简短说明（必填，建议50字以内）：支持交互式 commit
详细描述（可选，直接回车跳过）：
脚注（如 BREAKING CHANGE/关联 issue，可选，直接回车跳过）：

🚩 即将提交以下内容：
提交文件:
  src/commands/commit.ts
提交注释:
feat(core): 支持交互式 commit
请确认是否提交并 push？ (Y/n)
✅ commit 成功！
🚀 push 成功！
🔗 你可以在 Bitbucket 上查看新创建的内容
💡 提示：在 Bitbucket 中，你可以在 "Commits" 页面查看
```

#### long deploy
```
Frontend Msg Admin 部署工具

? 选择部署环境: 1. test-01 (app-test-hy-service/frontend-msg-admin)

部署到: test-01
Jenkins Job: app-test-hy-service/frontend-msg-admin

[1/4] 创建 Tag (本地 Git)
  拉取最新 tag...
  当前最新: test-v00.00.0262
  新 tag: test-v00.00.0263
  推送到 Bitbucket...
  Tag 已创建: test-v00.00.0263

[2/4] 监听构建状态
  获取 commit hash: abc123d
  等待 build status 出现...
  AWS CodeBuild us-east-1 (frontend-msg-admin-ci): INPROGRESS (0分15秒)
  AWS CodeBuild us-east-1 (frontend-msg-admin-ci): SUCCESSFUL (1分45秒)
  构建完成

[3/4] 触发 Jenkins 部署
  触发 Jenkins 部署: app-test-hy-service/frontend-msg-admin
  构建已加入队列: 12345
  等待构建开始...
  构建已开始: #678

[4/4] 监听部署状态
  构建状态: BUILDING (0分10秒)
  构建状态: SUCCESS (0分35秒)

部署成功！

Tag: test-v00.00.0263
Jenkins 构建: #678 - SUCCESS
构建 URL: https://jenkins.example.com/job/app-test-hy-service/job/frontend-msg-admin/678/
```

## 扩展性说明

- 所有 git 操作、tag 处理、交互、常量、类型均已抽取为公共模块
- 新增命令/支持更多平台/自定义交互，只需在 utils/constants/types 里维护
- 代码高度解耦，便于单元测试和团队协作

## 配置文件

配置文件位置：`~/.long-cli/config.json`

该文件存储：
- Bitbucket API Token（加密）
- Jenkins API Token（加密）
- 项目和环境配置（用于 Web UI）

**注意**：
- `long deploy` 命令只使用 API Token 配置，项目和环境配置是硬编码的
- `long config` 打开的 Web UI 可以配置多项目多环境，用于更灵活的部署场景

## 故障排除

### long deploy 提示"未找到配置"

**解决方法**：
1. 运行 `long config` 打开 Web UI
2. 配置 Bitbucket API Token 和 Jenkins API Token
3. 保存配置后重新运行 `long deploy`

### long deploy 提示"Bitbucket 配置不完整"

**解决方法**：
1. 运行 `long config` 打开 Web UI
2. 检查 Bitbucket 配置是否完整（用户名和 API Token）
3. 重新保存配置

### long deploy 提示"未找到 Jenkins (app) 配置"

**解决方法**：
1. 运行 `long config` 打开 Web UI
2. 添加 Jenkins 实例，类型选择 "app"
3. 填写 Jenkins URL、用户名和 API Token
4. 保存配置

### 如何重新配置

如果需要重新配置 API Token：
1. 运行 `long config` 打开 Web UI
2. 在配置界面重新输入新的 Token
3. 保存配置

或者直接删除配置文件：
```bash
rm ~/.long-cli/config.json
```
然后重新运行 `long config` 进行配置。

## 贡献

欢迎提 issue 或 PR，或根据自身需求 fork 扩展！