Metadata-Version: 2.4
Name: jenkee
Version: 0.2.1
Summary: Jenkins CLI Helper Tools
Author: Jenkins Studio Team
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: testcontainers>=3.7.1; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.0.0; extra == "release"
Requires-Dist: twine>=4.0.0; extra == "release"

# Jenkins Inspector

Jenkins CLI 工具，提供命令列介面來管理和探索 Jenkins jobs、builds、credentials 等資源。

主要 CLI 命令為 `jenkee`（保留 `jks` 作為相容 alias）。

## 安裝

### 使用 pipx 安裝（推薦）

```bash
pipx install git+https://github.com/qrtt1/jenkins-inspector
```

### 開發模式安裝

如果想要參與開發或修改程式碼：

```bash
# Clone repository
git clone https://github.com/qrtt1/jenkins-inspector
cd jenkins-inspector

# 啟用虛擬環境
source venv/bin/activate

# 以 editable 模式安裝
pip install -e .
```

## 與 AI Agent 的互動

如果你不熟悉 Jenkins Inspector 的使用方式，或想讓 AI agent 協助你完成 Jenkins 相關任務，可以使用 `prompt` 命令：

```bash
jenkee prompt
```

這個命令會輸出專為 AI agent 設計的使用指引，包含：
- Jenkins Inspector 的功能說明
- 各命令的使用方式與情境
- AI agent 操作建議與最佳實踐

你可以將輸出的內容複製給你的 AI assistant（如 ChatGPT、Claude），讓它更了解如何協助你使用 Jenkins Inspector。

### 自訂 AI Agent Prompt

如果需要自訂 prompt 內容（例如：加入團隊特定的工作流程、命名規範等），可以透過以下方式：

**方式 1：使用預設位置**

```bash
# 建立自訂 prompt
cat > ~/.jenkins-inspector/prompt.md << 'EOF'
# 我的使用指引

自訂的 prompt 內容...
EOF
```

**方式 2：使用環境變數指定檔案位置**

```bash
# 設定環境變數
export JENKINS_INSPECTOR_PROMPT_FILE=/path/to/my-prompt.md

# 執行 prompt 命令
jenkee prompt
```

環境變數 `JENKINS_INSPECTOR_PROMPT_FILE` 的優先級高於預設位置。

**暫時忽略自訂 prompt**

如果需要暫時使用預設 prompt 而不刪除自訂檔案：

```bash
# 使用 --ignore-override flag
jenkee prompt --ignore-override
```

詳細說明請參考 [docs/examples/prompt.md](docs/examples/prompt.md)。

## 設定認證

```bash
# 建立設定檔目錄
mkdir -p ~/.jenkins-inspector

# 編輯 .env 檔案
cat > ~/.jenkins-inspector/.env << EOF
JENKINS_URL=http://your-jenkins-server:8080/
JENKINS_USER_ID=your_email@example.com
JENKINS_API_TOKEN=your_api_token
EOF

# 驗證認證
jenkee auth
```

## 可用命令

### 一般命令

| 命令 | 說明 | 範例 |
|------|------|------|
| `help` | 顯示命令說明 | `jenkee help [command]` |
| `prompt` | 顯示 AI agent 使用指引 | `jenkee prompt` |
| `auth` | 驗證 Jenkins 認證 | `jenkee auth` |
| `list-views` | 列出所有 views | `jenkee list-views` |
| `list-jobs` | 列出 view 中的 jobs | `jenkee list-jobs AVENGERS` |
| `get-job` | 取得 job XML 配置 | `jenkee get-job <job-name>` |
| `list-builds` | 列出 job 的 build 歷史 | `jenkee list-builds <job-name>` |
| `console` | 取得 build console 輸出 | `jenkee console <job-name> [build]` |
| `job-status` | 查看 job 狀態與觸發關係 | `jenkee job-status <job-name>` |
| `job-diff` | 比較兩個 job 配置差異 | `jenkee job-diff <job1> <job2>` |
| `list-credentials` | 列出 Jenkins credentials metadata | `jenkee list-credentials [domain]` |
| `describe-credentials` | 查看特定 credential 詳細資訊 | `jenkee describe-credentials <id> [--show-secret]` |
| `add-job-to-view` | 將 jobs 加入到 view | `jenkee add-job-to-view <view> <job> [job ...]` |
| `copy-job` | 複製 job 為新 job | `jenkee copy-job <source> <destination>` |
| `update-job` | 更新 job 配置 | `jenkee update-job <job> < config.xml` |
| `build` | 觸發 job build | `jenkee build <job> [-p key=value] [-s] [-f]` |
| `stop-builds` | 停止執行中的 builds | `jenkee stop-builds <job> [job ...]` |
| `create-job` | 建立新 job | `jenkee create-job <job> < config.xml` |

詳細使用說明請參考 [docs/examples/](docs/examples/) 目錄下的各命令文件。

進階與危險命令請參考 [README.advanced.md](README.advanced.md)。

## 主要功能

### 1. 探索 Jenkins 架構
- 列出所有 views 和 jobs
- 查看 job 配置與狀態
- 追蹤 job 觸發關係

### 2. Build 管理
- 觸發 job builds（支援參數、同步與追蹤模式）
- 停止執行中的 builds
- 查看 build 歷史與 console 輸出

### 3. Job 管理
- 建立、複製、更新 job 配置
- 比較 job 配置差異
- 將 jobs 加入 views

### 4. Credentials 管理
- 列出所有 credentials metadata
- 查看 credentials 類型與相關資訊
- 驗證 credentials 配置

## 文件

- [README.advanced.md](README.advanced.md) - 進階與危險命令
- [CODING_GUIDE.md](CODING_GUIDE.md) - 專案開發指南
- [docs/examples/](docs/examples/) - 各命令使用範例

## 開發指引

如果你是 AI agent 正在開發此專案，請**務必先閱讀 [CODING_GUIDE.md](CODING_GUIDE.md)**。

該文件包含：
- 專案架構原則與設計模式
- 新增 command 的完整流程
- 程式碼格式化規範（Black）
- AI Agent 開發 checklist

遵循 CODING_GUIDE 可確保：
- 程式碼風格一致
- 功能完整實作（包含 help、prompt、example 文件）
- 通過所有整合測試

