Metadata-Version: 2.4
Name: sanjiu-jenkins-cli
Version: 0.1.0
Summary: A simple Jenkins CI/CD CLI tool for triggering builds, monitoring status, and streaming logs
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# sj-cicd — Jenkins 构建部署命令行工具

简洁的 Jenkins 命令行工具，一条命令管理构建部署。

- 支持任意 Jenkins 实例，Jenkins URL 完全可配置
- 内置 Claude Code / Codex Skill，安装后可直接对话式操作 Jenkins
- 结构化 JSON 输出，对 AI 和脚本都友好

## 安装

### 方式一：pip 安装（推荐）

```bash
pip install sanjiu-jenkins-cli
```

### 方式二：源码安装（一键脚本，自动引导配置 + 注册 AI Skill）

```bash
git clone https://github.com/slicenferqin/sanjiu-jenkins-cli.git
cd sanjiu-jenkins-cli
bash setup.sh
```

安装脚本会自动完成：
1. 检查 Python 版本（需要 3.11+）
2. 安装 CLI 工具
3. 交互式引导配置 Jenkins 认证
4. 检测 Claude Code / Codex，自动注册 Skill

## 配置

首次使用需要两个东西：**Jenkins URL** 和 **API Token**。

### 获取 API Token

1. 打开你的 Jenkins → 右上角用户名 → Configure（或直接访问 `<你的Jenkins>/me/configure`）
2. 找到 **API Token** 部分
3. 点击 **Add new Token** → 取个名字 → 复制生成的 token

### 写入配置（二选一）

**方式一：配置文件（推荐）**

```bash
cat > ~/.jenkins-cli << 'EOF'
JENKINS_URL=https://your-jenkins.example.com
JENKINS_USER=your-username
JENKINS_TOKEN=your-api-token
EOF
chmod 600 ~/.jenkins-cli
```

**方式二：环境变量**

```bash
export JENKINS_URL="https://your-jenkins.example.com"
export JENKINS_USER="your-username"
export JENKINS_TOKEN="your-api-token"
```

### 验证配置

```bash
sj-cicd auth
# ✓ Authentication successful
# {"user": "sanjiu", "fullName": "三酒", ...}
```

## 使用教程

### 命令一览

```
sj-cicd list [FILTER]           列出任务（支持正则过滤）
sj-cicd info <任务名>            查看任务详情和构建参数
sj-cicd build <任务名> K=V ...   触发构建
sj-cicd status <任务名> [构建号]  查看构建状态（默认最近一次）
sj-cicd history <任务名> [-n N]  查看构建历史（默认最近 10 次）
sj-cicd log <任务名> <构建号>     查看构建日志
sj-cicd stop <任务名> <构建号>    停止运行中的构建
sj-cicd auth                    验证认证配置
```

### 场景 1：搜索任务

```bash
# 列出所有任务
sj-cicd list

# 按关键词搜索（支持正则）
sj-cicd list order-center
sj-cicd list "web|frontend"

# 输出示例：
# [
#   {"name": "Dev_InternalControl-order-center", "type": "pipeline", "buildable": true, "status": "blue"},
#   {"name": "Test_InternalControl-order-center", "type": "pipeline", "buildable": true, "status": "blue"},
#   ...
# ]
```

### 场景 2：查看任务参数

```bash
sj-cicd info DEV-WEB-xiaoy-zhibo-wx

# 输出示例：
# {
#   "name": "DEV-WEB-xiaoy-zhibo-wx",
#   "buildable": true,
#   "lastBuild": 10,
#   "parameters": [
#     {"name": "ENV", "type": "ChoiceParameter", "choices": ["test", "dev"], "defaultValue": "test"},
#     {"name": "BranchName", "type": "GitParameter", "choices": ["master", "release", ...], "defaultValue": "master"},
#     {"name": "NpmRegistry", "type": "ChoiceParameter", "choices": ["私有源", "官方源"], "defaultValue": "私有源"}
#   ]
# }
```

### 场景 3：触发构建

```bash
# 带参数触发，等待完成
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=test BranchName=master

# 带参数触发，实时流式日志
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=test BranchName=master --follow-log

# 只触发，不等待
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=dev --no-wait
```

`build` 命令的完整流程：
1. 触发构建 → 获取队列 ID
2. 等待构建开始（轮询队列，最长 120 秒）
3. 监控构建状态 / 流式输出日志
4. 报告最终结果（SUCCESS / FAILURE + 耗时）

### 场景 4：查看构建状态

```bash
# 最近一次构建
sj-cicd status DEV-WEB-xiaoy-zhibo-wx

# 指定构建号
sj-cicd status DEV-WEB-xiaoy-zhibo-wx 42

# 输出示例：
# {
#   "job": "DEV-WEB-xiaoy-zhibo-wx",
#   "number": 10,
#   "result": "SUCCESS",
#   "building": false,
#   "duration": "3m21s",
#   "timestamp": "2021-04-14 19:04:04"
# }
```

### 场景 5：构建历史

```bash
# 最近 10 次
sj-cicd history DEV-WEB-xiaoy-zhibo-wx

# 最近 5 次
sj-cicd history DEV-WEB-xiaoy-zhibo-wx -n 5
```

### 场景 6：查看 / 排查日志

```bash
# 查看完整日志
sj-cicd log DEV-WEB-xiaoy-zhibo-wx 10

# 实时流式日志（构建进行中时使用）
sj-cicd log DEV-WEB-xiaoy-zhibo-wx 10 --follow
```

### 场景 7：停止构建

```bash
sj-cicd stop DEV-WEB-xiaoy-zhibo-wx 42
# ✓ Stop request sent for DEV-WEB-xiaoy-zhibo-wx #42
```

### 中文任务名

完全支持中文任务名，自动 URL 编码：

```bash
sj-cicd info "cdn刷新"
sj-cicd build "cdn刷新" Type=File UriList="https://example.com/path"
```

## AI 对话集成（Claude Code / Codex）

安装脚本会自动检测 Claude Code 和 Codex CLI，将 Skill 注册到对应位置。注册后无需记命令，直接用自然语言操作：

| 你说的话 | AI 执行的操作 |
|---------|-------------|
| "部署 DEV-WEB-xiaoy-zhibo-wx 到 test 环境" | `info` → 展示参数 → 确认 → `build --follow-log` |
| "查看 order-center 最近的构建" | `list order-center` → `status` |
| "构建失败了，帮我看下日志" | `history` → 找到失败构建 → `log` → 分析错误 |
| "Jenkins 上有哪些 WEB 项目" | `list WEB` |
| "停止 xxx 的构建" | `status` → 确认运行中 → `stop` |

### 手动安装 Skill

如果通过 pip 安装而非 setup.sh，需要手动复制 Skill：

```bash
# Claude Code
mkdir -p ~/.claude/skills/sj-cicd
curl -o ~/.claude/skills/sj-cicd/SKILL.md \
  https://raw.githubusercontent.com/slicenferqin/sanjiu-jenkins-cli/main/skill/SKILL.md

# Codex CLI
mkdir -p ~/.codex/skills/sj-cicd
curl -o ~/.codex/skills/sj-cicd/SKILL.md \
  https://raw.githubusercontent.com/slicenferqin/sanjiu-jenkins-cli/main/skill/SKILL.md
```

## 项目结构

```
sanjiu-jenkins-cli/
├── setup.sh                    # 一键安装（引导配置 + 自动注册 Skill）
├── pyproject.toml              # 包配置
├── src/jenkins_cli/
│   ├── cli.py                  # CLI 入口（Click）
│   ├── client.py               # Jenkins API 客户端（httpx）
│   └── config.py               # 认证配置管理
├── skill/
│   └── SKILL.md                # AI Skill（Claude Code / Codex）
└── tests/
```

## License

MIT
