python-jcli 0.1.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

jcli/cli_helpers.py

@@ -1,54 +1,17 @@
-"""Centralized CLI helpers for creating JenkinsClient and OutputFormatter.
+"""Centralized CLI helpers.
 
-All plugin modules should import ``get_client`` and ``get_formatter`` from here
-instead of implementing their own versions.  This ensures consistent behaviour
-for ``--profile``, ``--server``, and ``--format`` across every subcommand.
+v2 only needs the output-formatter helper (used by the cliyard command
+plugins, e.g. ``jcli/specs/plugins/jcli_commands.py``).  The v1 ``get_client``
+helper was removed together with the legacy hand-written command modules
+(``jcli/plugins/``).
 """
 
 from __future__ import annotations
 
-import logging
-
 import click
 
-from jcli.sdk.client import JenkinsClient
-from jcli.sdk.config import Config
 from jcli.sdk.output import OutputFormatter
 
-logger = logging.getLogger(__name__)
-
-
-def get_client(ctx: click.Context) -> JenkinsClient:
-    """Return a cached ``JenkinsClient`` from the Click context.
-
-    Resolution order:
-    1. Re-use ``ctx.obj["client"]`` if already present (tests / caching).
-    2. Load the config profile selected by ``--profile`` / ``$JCLI_PROFILE``.
-    3. Override the profile URL with ``--server`` when provided.
-    """
-    obj = ctx.obj or {}
-
-    # Allow pre-created client (used by tests and internal callers)
-    if "client" in obj:
-        return obj["client"]
-
-    config = Config()
-    config.load()
-
-    profile_name = obj.get("profile") or config.get_active_profile_name()
-    profile = config.get_profile(profile_name)
-
-    url = obj.get("server") or profile["url"]
-    username = profile["username"]
-    token = profile["api_token"]
-
-    client = JenkinsClient(base_url=url, username=username, token=token)
-    logger.debug("Created JenkinsClient for %s (profile=%s)", url, profile_name)
-
-    # Cache for subsequent calls within the same invocation
-    obj["client"] = client
-    return client
-
 
 def get_formatter(ctx: click.Context) -> OutputFormatter:
     """Return an ``OutputFormatter`` matching the ``--format`` flag."""

jcli/skills/jcli/SKILL.md

@@ -30,7 +30,7 @@ jcli -f yaml job list     # YAML 输出
 
 | 技能 | 说明 |
 |------|------|
-| [jcli-config](config/SKILL.md) | 配置管理 - Jenkins 连接配置、多实例管理 |
+| [jcli-auth](auth/SKILL.md) | 认证配置管理 - Jenkins 连接 profile 添加、切换、查看、删除 |
 | [jcli-job](job/SKILL.md) | Job 管理 - Job 创建、删除、复制、启用/禁用 |
 | [jcli-build](build/SKILL.md) | 构建管理 - 构建触发、查看、停止、队列 |
 | [jcli-node](node/SKILL.md) | 节点管理 - Jenkins Agent 节点管理 |
@@ -40,6 +40,19 @@ jcli -f yaml job list     # YAML 输出
 | [jcli-view](view/SKILL.md) | 视图管理 - 视图创建、删除、查看 |
 | [jcli-system](system/SKILL.md) | 系统管理 - 系统信息、重启、安静模式 |
 
+## 认证配置（auth）
+
+```bash
+jcli auth add -n <name> -u <user> -p <token> -e <url>   # 添加配置（token 即 Jenkins API Token）
+jcli auth status                                        # 查看所有配置（token 掩码）
+jcli auth use <name>                                    # 切换 active profile
+jcli auth set <name> <field> <value>                    # 修改字段（url/username/api_token/description）
+jcli auth show [name]                                   # 查看单个配置详情
+jcli auth rm <name>                                     # 删除配置
+```
+
+详细用法见 [jcli-auth](auth/SKILL.md)。
+
 ## Skills 命令
 
 ```bash
@@ -70,4 +83,4 @@ jcli completion show fish                  # Fish 补全脚本
 
 - 源码: `/data/git-project/jcli`
 - 配置: `~/.jcli/config.yaml`
-- 技能文档: `/data/git-project/jcli/skills/jcli/`
+- 技能文档: `/data/git-project/jcli/jcli/skills/jcli/`

jcli/skills/jcli/auth/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: jcli-auth
+version: 1.0.0
+description: |
+  jcli 认证配置管理 - 管理 Jenkins 连接 profile 的添加、切换、查看、删除等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-auth
+
+管理 jcli 的认证配置 profile，支持多 Jenkins 实例。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 配置文件位置
+
+`~/.jcli/config.yaml`
+
+## 配置结构
+
+```yaml
+active_profile: default
+profiles:
+  default:
+    url: https://jenkins.example.com
+    username: admin
+    api_token: your-api-token-here
+    description: Default Jenkins instance
+```
+
+## 命令参考
+
+```bash
+jcli auth add -n <name> -u <user> -p <token> -e <url>   # 添加（或更新）配置
+jcli auth add -n <name> ... --default                   # 添加并设为 active profile
+jcli auth status                                        # 列出所有配置（token 掩码）
+jcli auth use <name>                                    # 切换 active profile
+jcli auth set <name> <field> <value>                    # 修改字段（url/username/api_token/description）
+jcli auth show [name]                                   # 查看单个配置详情（默认 active）
+jcli auth rm <name>                                     # 删除配置
+jcli auth rm --all                                      # 删除所有配置（重置为模板）
+```
+
+## 常见用例
+
+### 添加新 profile
+
+```bash
+jcli auth add -n dev -u admin -p your-api-token -e https://jenkins-dev.example.com
+```
+
+### 修改配置
+
+```bash
+jcli auth set dev api_token your-token
+jcli auth set dev description "Development Jenkins"
+```
+
+### 切换 profile
+
+```bash
+jcli auth use dev
+```
+
+### 查看配置
+
+```bash
+jcli auth status
+jcli auth show
+jcli auth show dev
+```
+
+## 环境变量覆盖
+
+| 变量 | 覆盖字段 |
+|------|---------|
+| `JCLI_URL` | url |
+| `JCLI_USERNAME` | username |
+| `JCLI_API_TOKEN` | api_token |
+| `JCLI_PROFILE` | active_profile |

jcli/skills/jcli/build/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: jcli-build
+version: 1.0.0
+description: |
+  jcli 构建管理 - 管理 Jenkins 构建的触发、查看、停止等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-build
+
+管理 Jenkins 构建的触发、查看、停止等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```bash
+jcli build list <job>                      # 列出构建历史
+jcli build list <job> --limit 20           # 列出最近 20 次构建
+jcli build get <job> <number>              # 查看构建详情
+jcli build log <job> <number>              # 查看完整控制台日志
+jcli build log <job> <number> -n 50        # 只显示末尾 50 行（tail -n）
+jcli build log <job> <number> -f           # 实时跟随（tail -f）：先打印全部历史，再滚动新增，构建结束自动退出
+jcli build log <job> <number> -f -n 50     # 显示末尾 50 行后实时跟随
+jcli build artifacts <job> <number>        # 查看构建产物
+jcli build trigger <job>                   # 触发构建
+jcli build trigger <job> --params BRANCH=main  # 带参数触发构建
+jcli build trigger <job> --params KEY1=VAL1 --params KEY2=VAL2  # 多个参数
+jcli build rebuild <job> <number>          # 重建（复用上次构建参数）
+jcli build rebuild <job> <number> --set KEY=VAL  # 重建并覆盖参数（可重复）
+jcli build replay <job> <number> <jenkinsfile>  # 回放（使用修改后的 Jenkinsfile）
+jcli build stop <job> <number>             # 停止构建
+jcli build queue                           # 查看构建队列
+```
+
+## 常见用例
+
+### 查看构建失败原因
+
+```bash
+# 1. 查看最近构建
+jcli build list my-job
+
+# 2. 查看失败构建的日志
+jcli build log my-job 42
+```
+
+### 批量触发构建
+
+```bash
+for job in job1 job2 job3; do
+  jcli build trigger $job
+done
+```
+
+### 监控构建状态
+
+```bash
+# 查看队列
+jcli build queue
+
+# 实时查看最新构建状态
+watch -n 5 "jcli build list my-job --limit 1"
+
+# 实时跟随构建日志（-f，构建结束自动退出）
+jcli build log my-job 42 -f
+```
+
+### 带参数触发构建
+
+```bash
+# 单个参数
+jcli build trigger my-job --params BRANCH=develop
+
+# 多个参数
+jcli build trigger my-job --params BRANCH=develop --params DEPLOY=true --params ENV=staging
+```
+
+### 实时查看构建日志（tail 风格）
+
+`jcli build log` 沿用 `tail` 命令的参数语义：
+
+| 命令 | 效果 |
+|------|------|
+| `jcli build log <job> <n>` | 输出完整日志 |
+| `jcli build log <job> <n> -n 50` | 只显示末尾 50 行 |
+| `jcli build log <job> <n> -f` | 实时跟随：先输出全部历史，再滚动显示新日志 |
+| `jcli build log <job> <n> -f -n 50` | 先看末尾 50 行，再实时跟随 |
+
+- `-f` / `--follow`：实时输出，新日志逐行滚动（tail -f）
+- `-n N` / `--lines N`：只显示末尾 N 行，默认全部
+- 跟随模式在**构建结束后自动退出**，也可随时 `Ctrl+C` 中断
+
+```bash
+# 构建失败排查：看末尾日志定位错误
+jcli build log my-job 42 -n 100
+
+# 实时观察正在构建的日志
+jcli build log my-job 42 -f
+
+# 触发构建后直接跟随
+jcli build trigger my-job
+jcli build log my-job 43 -f
+```
+
+### 重建与回放
+
+```bash
+# 重建：复用上次构建的参数
+jcli build rebuild my-job 42
+
+# 重建并覆盖部分参数（--set 可重复）
+jcli build rebuild my-job 42 --set DEPLOY=false
+
+# 回放：使用修改后的 Jenkinsfile 文件重新运行 Pipeline
+jcli build replay my-job 42 Jenkinsfile
+```

jcli/skills/jcli/credential/SKILL.md

@@ -21,10 +21,12 @@ allowed-tools:
 ## 命令参考
 
 ```bash
-jcli credential list                       # 列出凭据
-jcli credential get <id>                   # 查看凭据详情
-jcli credential create <id> -f config.xml  # 从 XML 创建凭据
-jcli credential delete <id>                # 删除凭据
+jcli credential list [store] [domain]     # 列出凭据（默认 store=system, domain=_）
+jcli credential list --depth 2            # 递归列出凭据
+jcli credential get <id> [store]          # 查看凭据详情
+jcli credential create <config.xml> [store] [domain]  # 从 XML 文件创建凭据
+jcli credential update <config.xml> <id> [store]      # 更新凭据
+jcli credential delete <id> [store] [domain]          # 删除凭据
 ```
 
 ## 常见用例
@@ -43,5 +45,12 @@ jcli credential get my-credential-id
 
 ```bash
 # 从 XML 配置文件创建凭据
-jcli credential create my-credential-id -f credential-config.xml
+jcli credential create credential-config.xml
+```
+
+### 更新凭据
+
+```bash
+# 从 XML 文件更新已有凭据
+jcli credential update credential-config.xml my-credential-id
 ```

jcli/skills/jcli/job/SKILL.md

@@ -23,13 +23,16 @@ allowed-tools:
 ```bash
 jcli job list                              # 列出所有 Job
 jcli job get <name>                        # 查看 Job 详情
-jcli job create <name> -f config.xml       # 从 XML 创建 Job
-jcli job delete <name>                     # 删除 Job（需确认）
-jcli job delete <name> --yes               # 删除 Job（跳过确认）
+jcli job create <name> --config-file config.xml  # 从 XML 创建 Job
+jcli job delete <name>                     # 删除 Job
 jcli job copy <from> <to>                  # 复制 Job
+jcli job rename <old> <new>                # 重命名 Job
 jcli job enable <name>                     # 启用 Job
 jcli job disable <name>                    # 禁用 Job
 jcli job config <name>                     # 查看 Job XML 配置
+jcli job update <config.xml> <name>        # 用 XML 更新 Job 配置
+jcli job create-folder <name>              # 创建文件夹
+jcli job delete-folder <name>              # 删除文件夹（含内容）
 ```
 
 ## 常见用例
@@ -51,5 +54,18 @@ done
 ### 从 XML 创建 Job
 
 ```bash
-jcli job create my-new-job -f job-config.xml
+jcli job create my-new-job --config-file job-config.xml
+```
+
+### 参数化创建 Job
+
+```bash
+# 从 git 仓库创建 freestyle 构建
+jcli job create my-freestyle --job-type freestyle --git-url git@github.com:org/repo.git --git-branch main
+
+# 创建 Pipeline 构建（使用仓库根目录的 Jenkinsfile）
+jcli job create my-pipeline --job-type pipeline --git-url git@github.com:org/repo.git --script "pipeline { agent any; stages { stage('Build') { steps { echo 'hi' } } } }"
+
+# 定时构建
+jcli job create my-scheduled --job-type freestyle --git-url git@github.com:org/repo.git --cron "H/15 * * * *"
 ```

jcli/skills/jcli/node/SKILL.md

@@ -23,8 +23,10 @@ allowed-tools:
 ```bash
 jcli node list                             # 列出所有节点
 jcli node get <name>                       # 查看节点详情
+jcli node create <name>                    # 创建节点（JNLP 启动器）
+jcli node create <name> --num-executors 2 --remote-fs /data/jenkins --labels linux  # 指定参数创建
 jcli node delete <name>                    # 删除节点
-jcli node toggle <name> --message "维护"   # 节点离线
+jcli node toggle <name> --offline-message "维护"  # 节点离线（带原因）
 jcli node toggle <name>                    # 节点上线
 ```
 
@@ -34,7 +36,7 @@ jcli node toggle <name>                    # 节点上线
 
 ```bash
 # 节点离线（带维护原因）
-jcli node toggle agent-01 --message "系统升级维护"
+jcli node toggle agent-01 --offline-message "系统升级维护"
 
 # 节点恢复上线
 jcli node toggle agent-01

jcli/skills/jcli/pipeline/SKILL.md

@@ -23,7 +23,7 @@ allowed-tools:
 ```bash
 jcli pipeline stages <job> <build>         # 查看阶段信息
 jcli pipeline log <job> <build> <node-id>  # 查看步骤日志
-jcli pipeline validate -f Jenkinsfile      # 验证 Jenkinsfile
+jcli pipeline validate <Jenkinsfile>       # 验证 Jenkinsfile（位置参数，文件路径）
 jcli pipeline pending <job> <build>        # 查看待处理输入
 ```
 
@@ -46,8 +46,8 @@ jcli pipeline log my-job 42 15
 ### 验证 Jenkinsfile
 
 ```bash
-# 验证 Jenkinsfile 语法
-jcli pipeline validate -f Jenkinsfile
+# 验证 Jenkinsfile 语法（传入文件路径）
+jcli pipeline validate Jenkinsfile
 ```
 
 ### 查看待处理输入

jcli/skills/jcli/plugin/SKILL.md

@@ -25,7 +25,10 @@ jcli plugin list                           # 列出已安装插件
 jcli plugin get <name>                     # 查看插件详情
 jcli plugin install <name>                 # 安装插件
 jcli plugin install git@4.15.0             # 安装指定版本
+jcli plugin install <name1> <name2>        # 一次安装多个插件
 jcli plugin uninstall <name>               # 卸载插件
+jcli plugin restart <name>                 # 重启插件
+jcli plugin check-updates                  # 检查插件更新
 ```
 
 ## 常见用例

jcli/skills/jcli/system/SKILL.md

@@ -27,7 +27,10 @@ jcli system restart                        # 安全重启 Jenkins
 jcli system quiet-down                     # 进入安静模式
 jcli system quiet-down --reason "维护"     # 带原因的安静模式
 jcli system cancel-quiet-down              # 取消安静模式
-jcli system script "println('hello')"      # 执行 Groovy 脚本
+jcli system script <script>                # 执行 Groovy 脚本（位置参数）
+jcli system users                          # 列出所有 Jenkins 用户
+jcli system token <username>               # 为用户生成 API token
+jcli system token <username> --token-name <name>  # 指定 token 名称
 ```
 
 ## 常见用例
@@ -62,9 +65,19 @@ jcli system restart
 ### 执行 Groovy 脚本
 
 ```bash
-# 执行简单的 Groovy 脚本
+# 执行简单的 Groovy 脚本（SCRIPT 为位置参数）
 jcli system script "println('Hello from jcli')"
 
 # 获取所有节点信息
 jcli system script "Jenkins.instance.computers.each { println it.name }"
 ```
+
+### 用户与 Token
+
+```bash
+# 列出所有用户
+jcli system users
+
+# 为指定用户生成 API token
+jcli system token admin
+```

jcli/skills/jcli/view/SKILL.md

@@ -23,7 +23,8 @@ allowed-tools:
 ```bash
 jcli view list                             # 列出所有视图
 jcli view get <name>                       # 查看视图详情
-jcli view create <name> -f config.xml      # 从 XML 创建视图
+jcli view create <config.xml> <name>       # 从 XML 文件创建视图（XML 在前，名称在后）
+jcli view update <config.xml> <name>       # 用 XML 更新视图配置
 jcli view delete <name>                    # 删除视图
 ```
 
@@ -42,6 +43,6 @@ jcli view get my-view
 ### 创建视图
 
 ```bash
-# 从 XML 配置文件创建视图
-jcli view create my-view -f view-config.xml
+# 从 XML 配置文件创建视图（XML 文件路径在前，视图名在后）
+jcli view create view-config.xml my-view
 ```

jcli/specs/_auth.yaml

@@ -0,0 +1,15 @@
+name: jcli
+version: "1.0.1"
+description: Jenkins CLI tool
+output:
+  default: table
+server:
+  base_url: http://localhost:8090
+auth:
+  steps:
+    - name: basic
+      type: plugin:jenkins_basic
+      config: {}
+    - name: crumb
+      type: plugin:jenkins_crumb
+      config: {}