python-jcli 0.1.0__py3-none-any.whl

jcli/sdk/system.py

@@ -0,0 +1,202 @@
+"""Jenkins System SDK functions.
+
+All functions take a :class:`~jcli.sdk.client.JenkinsClient` as the first argument.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from jcli.sdk.client import JenkinsClient
+
+# ------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------
+
+
+def get_system_info(client: "JenkinsClient") -> dict[str, Any]:
+    """Get Jenkins system information.
+
+    Calls ``GET /api/json`` and extracts version from the ``X-Jenkins``
+    response header.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        Dictionary with keys:
+        - ``version``: Jenkins version string (from ``X-Jenkins`` header).
+        - ``num_executors``: Total number of executors.
+        - ``mode``: Executor mode (e.g. ``NORMAL``, ``EXCLUSIVE``).
+        - ``quietingDown``: Whether Jenkins is in quiet-down mode.
+        - ``slaveAgentPort``: Port for JNLP agents.
+        - ``num_nodes``: Total number of connected nodes (from ``computer``).
+        - ``num_jobs``: Total number of jobs.
+        - ``raw``: Full API response data.
+    """
+    resp = client.request("GET", "/api/json")
+    data: dict[str, Any] = resp.json()
+
+    version = resp.headers.get("X-Jenkins", "unknown")
+
+    # Count nodes from computer list if available
+    num_nodes = 0
+    computer = data.get("computer", [])
+    if isinstance(computer, list):
+        num_nodes = len(computer)
+
+    return {
+        "version": version,
+        "num_executors": data.get("numExecutors", 0),
+        "mode": data.get("mode", ""),
+        "quietingDown": data.get("quietingDown", False),
+        "slaveAgentPort": data.get("slaveAgentPort", 0),
+        "num_nodes": num_nodes,
+        "num_jobs": len(data.get("jobs", [])),
+        "raw": data,
+    }
+
+
+def safe_restart(client: "JenkinsClient") -> bool:
+    """Trigger a safe restart of Jenkins.
+
+    Calls ``POST /safeRestart``. Jenkins waits for running builds to
+    complete before restarting.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        ``True`` on success (HTTP 200/302).
+    """
+    resp = client.request("POST", "/safeRestart")
+    return resp.ok
+
+
+def quiet_down(client: "JenkinsClient", reason: str = "") -> bool:
+    """Put Jenkins into quiet-down mode.
+
+    In quiet-down mode, Jenkins stops scheduling new builds. Running
+    builds continue until finished.  Calls ``POST /quietDown``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        reason: Optional reason shown on the quiet-down banner.
+
+    Returns:
+        ``True`` on success (HTTP 200/302).
+    """
+    params: dict[str, str] | None = None
+    if reason:
+        params = {"reason": reason}
+    resp = client.request("POST", "/quietDown", params=params)
+    return resp.ok
+
+
+def cancel_quiet_down(client: "JenkinsClient") -> bool:
+    """Cancel quiet-down mode, allowing Jenkins to resume scheduling builds.
+
+    Calls ``POST /cancelQuietDown``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        ``True`` on success (HTTP 200/302).
+    """
+    resp = client.request("POST", "/cancelQuietDown")
+    return resp.ok
+
+
+def run_script(client: "JenkinsClient", script: str) -> Any:
+    """Execute a Groovy script on the Jenkins server.
+
+    Calls ``POST /scriptText`` with form-encoded script content.
+
+    Args:
+        client: Jenkins API client.
+        script: Groovy script text.
+
+    Returns:
+        Script output as text.
+    """
+    resp = client.post_data("/scriptText", data={"script": script})
+    return resp.text
+
+
+def get_system_load(client: "JenkinsClient") -> dict[str, Any]:
+    """Get current system load statistics.
+
+    Calls ``GET /queue/api/json`` for the build queue and
+    ``GET /computer/api/json`` for executor usage.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        Dictionary with keys:
+        - ``queue_length``: Number of items in the build queue.
+        - ``total_executors``: Total executors across all nodes.
+        - ``busy_executors``: Currently busy executors.
+        - ``idle_executors``: Currently idle executors.
+    """
+    queue_data = client.get_json("/queue/api/json")
+    queue_items = queue_data.get("items", [])
+    queue_length = len(queue_items) if isinstance(queue_items, list) else 0
+
+    computer_data = client.get_json("/computer/api/json")
+    computers = computer_data.get("computer", [])
+    total_executors = 0
+    busy_executors = 0
+    if isinstance(computers, list):
+        for c in computers:
+            total_executors += c.get("numExecutors", 0)
+            busy = c.get("busyExecutors", 0)
+            if busy:
+                busy_executors += busy
+
+    idle_executors = total_executors - busy_executors
+
+    return {
+        "queue_length": queue_length,
+        "total_executors": total_executors,
+        "busy_executors": busy_executors,
+        "idle_executors": idle_executors,
+    }
+
+
+def list_users(client: "JenkinsClient") -> Any:
+    """List all Jenkins users.
+
+    Calls ``GET /asynchPeople/api/json``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        Parsed JSON with users list.
+    """
+    return client.get_json("/asynchPeople/api/json")
+
+
+def generate_token(
+    client: "JenkinsClient",
+    username: str,
+    token_name: str = "jcli-generated",
+) -> Any:
+    """Generate a new API token for a user.
+
+    Calls ``POST /user/{name}/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        username: Jenkins username.
+        token_name: Name/label for the new token.
+
+    Returns:
+        Parsed JSON with token data including the token value.
+    """
+    path = f"/user/{username}/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken"
+    data = {"newTokenName": token_name}
+    return client.post_data(path, data=data).json()

jcli/sdk/view.py

@@ -0,0 +1,94 @@
+"""SDK functions for Jenkins View management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+from jcli.sdk.exceptions import JenkinsAPIError
+
+
+def list_views(client: JenkinsClient) -> list[dict[str, Any]]:
+    """List all views on the Jenkins server.
+
+    Args:
+        client: Authenticated Jenkins client.
+
+    Returns:
+        List of view dicts, each with ``name``, ``url``, and ``jobs`` keys.
+
+    Raises:
+        JenkinsAPIError: If the API request fails.
+    """
+    data = client.get_json("/api/json", tree="views[name,url,jobs[name]]")
+    return data.get("views", [])
+
+
+def get_view(client: JenkinsClient, name: str) -> dict[str, Any]:
+    """Get details for a single Jenkins view.
+
+    Args:
+        client: Authenticated Jenkins client.
+        name: View name.
+
+    Returns:
+        View detail dict.
+
+    Raises:
+        JenkinsAPIError: If the API request fails.
+        JenkinsNotFoundError: If the view doesn't exist.
+    """
+    return client.get_json(f"/view/{name}/api/json")
+
+
+def create_view(
+    client: JenkinsClient,
+    name: str,
+    config_xml: str,
+) -> None:
+    """Create a new Jenkins view.
+
+    Args:
+        client: Authenticated Jenkins client.
+        name: View name to create.
+        config_xml: XML configuration for the view.
+
+    Raises:
+        JenkinsAPIError: If the API request fails (e.g. view already exists).
+    """
+    client.post_xml(f"/createView?name={name}", config_xml)
+
+
+def update_view(
+    client: JenkinsClient,
+    name: str,
+    config_xml: str | bytes,
+) -> Any:
+    """Update a view's configuration.
+
+    Args:
+        client: Jenkins API client.
+        name: View name.
+        config_xml: New XML configuration.
+
+    Returns:
+        Response from Jenkins.
+
+    Raises:
+        JenkinsAPIError: If the API request fails.
+    """
+    return client.post_xml(f"/view/{name}/config.xml", config_xml)
+
+
+def delete_view(client: JenkinsClient, name: str) -> None:
+    """Delete an existing Jenkins view.
+
+    Args:
+        client: Authenticated Jenkins client.
+        name: View name to delete.
+
+    Raises:
+        JenkinsAPIError: If the API request fails.
+        JenkinsNotFoundError: If the view doesn't exist.
+    """
+    client.post_data(f"/view/{name}/doDelete", data="")

jcli/skills/jcli/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: jcli
+version: 1.0.0
+description: |
+  jcli — Jenkins CLI 工具，通过命令行管理 Jenkins 服务器。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli — Jenkins CLI 工具
+
+通过命令行管理 Jenkins 服务器。支持 Job、构建、节点、插件、凭据、Pipeline、视图、系统管理等全功能操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 输出格式
+
+```bash
+jcli -f table job list    # 彩色表格（默认）
+jcli -f json job list     # JSON 输出
+jcli -f yaml job list     # YAML 输出
+```
+
+## 内置技能
+
+| 技能 | 说明 |
+|------|------|
+| [jcli-config](config/SKILL.md) | 配置管理 - Jenkins 连接配置、多实例管理 |
+| [jcli-job](job/SKILL.md) | Job 管理 - Job 创建、删除、复制、启用/禁用 |
+| [jcli-build](build/SKILL.md) | 构建管理 - 构建触发、查看、停止、队列 |
+| [jcli-node](node/SKILL.md) | 节点管理 - Jenkins Agent 节点管理 |
+| [jcli-plugin](plugin/SKILL.md) | 插件管理 - 插件安装、卸载、查看 |
+| [jcli-credential](credential/SKILL.md) | 凭据管理 - 凭据创建、删除、查看 |
+| [jcli-pipeline](pipeline/SKILL.md) | Pipeline 管理 - 阶段查看、日志获取、验证 |
+| [jcli-view](view/SKILL.md) | 视图管理 - 视图创建、删除、查看 |
+| [jcli-system](system/SKILL.md) | 系统管理 - 系统信息、重启、安静模式 |
+
+## Skills 命令
+
+```bash
+jcli skills list                          # 列出所有可用技能
+jcli skills list --installed              # 列出已安装技能
+jcli skills list --bundled                # 列出内置技能
+jcli skills install <name>                # 安装技能
+jcli skills install <name> --force        # 强制安装（覆盖已有）
+jcli skills uninstall <name>              # 卸载技能
+jcli skills get <name>                    # 查看技能详情
+```
+
+## 调试
+
+```bash
+jcli -d job list                           # 启用调试日志
+```
+
+## Shell 补全
+
+```bash
+jcli completion show bash                  # Bash 补全脚本
+jcli completion show zsh                   # Zsh 补全脚本
+jcli completion show fish                  # Fish 补全脚本
+```
+
+## 项目路径
+
+- 源码: `/data/git-project/jcli`
+- 配置: `~/.jcli/config.yaml`
+- 技能文档: `/data/git-project/jcli/skills/jcli/`

jcli/skills/jcli/config/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: jcli-config
+version: 1.0.0
+description: |
+  jcli 配置管理 - 管理 Jenkins 连接配置，支持多实例管理。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-config
+
+管理 jcli 的连接配置，支持多 Jenkins 实例。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 初始化配置
+
+```bash
+jcli config init
+```
+
+## 配置文件位置
+
+`~/.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
+# 添加新 profile
+jcli config add dev --url https://jenkins-dev.example.com --username admin
+
+# 修改配置
+jcli config set dev api_token your-token
+jcli config set dev description "Development Jenkins"
+
+# 切换 profile
+jcli config use dev
+
+# 查看配置
+jcli config show
+jcli config list
+```
+
+## 环境变量覆盖
+
+| 变量 | 覆盖字段 |
+|------|---------|
+| `JCLI_URL` | url |
+| `JCLI_USERNAME` | username |
+| `JCLI_API_TOKEN` | api_token |
+| `JCLI_PROFILE` | active_profile |
+
+## 命令参考
+
+```bash
+jcli config init                           # 初始化配置文件
+jcli config show                           # 查看当前配置
+jcli config show --profile dev             # 查看指定 profile
+jcli config list                           # 列出所有 profiles
+jcli config add <name> --url URL           # 添加新 profile
+jcli config set <name> <field> <value>     # 修改配置
+jcli config use <name>                     # 切换 active profile
+jcli config delete <name>                  # 删除 profile
+```

jcli/skills/jcli/credential/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: jcli-credential
+version: 1.0.0
+description: |
+  jcli 凭据管理 - 管理 Jenkins 凭据的创建、删除、查看等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-credential
+
+管理 Jenkins 凭据的创建、删除、查看等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```bash
+jcli credential list                       # 列出凭据
+jcli credential get <id>                   # 查看凭据详情
+jcli credential create <id> -f config.xml  # 从 XML 创建凭据
+jcli credential delete <id>                # 删除凭据
+```
+
+## 常见用例
+
+### 查看凭据
+
+```bash
+# 列出所有凭据
+jcli credential list
+
+# 查看特定凭据详情
+jcli credential get my-credential-id
+```
+
+### 创建凭据
+
+```bash
+# 从 XML 配置文件创建凭据
+jcli credential create my-credential-id -f credential-config.xml
+```

jcli/skills/jcli/job/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: jcli-job
+version: 1.0.0
+description: |
+  jcli Job 管理 - 管理 Jenkins Job 的创建、删除、复制、启用/禁用等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-job
+
+管理 Jenkins Job 的创建、删除、复制、启用/禁用等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```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 copy <from> <to>                  # 复制 Job
+jcli job enable <name>                     # 启用 Job
+jcli job disable <name>                    # 禁用 Job
+jcli job config <name>                     # 查看 Job XML 配置
+```
+
+## 常见用例
+
+### 导出 Job 配置
+
+```bash
+jcli job config my-job > job-config.xml
+```
+
+### 批量导出所有 Job 配置
+
+```bash
+jcli -f json job list | jq -r '.[].name' | while read job; do
+  jcli job config "$job" > "${job}.xml"
+done
+```
+
+### 从 XML 创建 Job
+
+```bash
+jcli job create my-new-job -f job-config.xml
+```

jcli/skills/jcli/node/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jcli-node
+version: 1.0.0
+description: |
+  jcli 节点管理 - 管理 Jenkins Agent 节点的上线、下线、删除等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-node
+
+管理 Jenkins Agent 节点的上线、下线、删除等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```bash
+jcli node list                             # 列出所有节点
+jcli node get <name>                       # 查看节点详情
+jcli node delete <name>                    # 删除节点
+jcli node toggle <name> --message "维护"   # 节点离线
+jcli node toggle <name>                    # 节点上线
+```
+
+## 常见用例
+
+### 节点维护
+
+```bash
+# 节点离线（带维护原因）
+jcli node toggle agent-01 --message "系统升级维护"
+
+# 节点恢复上线
+jcli node toggle agent-01
+```
+
+### 查看节点状态
+
+```bash
+# 查看所有节点状态
+jcli node list
+
+# 查看特定节点详情
+jcli node get agent-01
+```

jcli/skills/jcli/pipeline/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: jcli-pipeline
+version: 1.0.0
+description: |
+  jcli Pipeline 管理 - 管理 Jenkins Pipeline 的阶段查看、日志获取、Jenkinsfile 验证等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-pipeline
+
+管理 Jenkins Pipeline 的阶段查看、日志获取、Jenkinsfile 验证等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```bash
+jcli pipeline stages <job> <build>         # 查看阶段信息
+jcli pipeline log <job> <build> <node-id>  # 查看步骤日志
+jcli pipeline validate -f Jenkinsfile      # 验证 Jenkinsfile
+jcli pipeline pending <job> <build>        # 查看待处理输入
+```
+
+## 常见用例
+
+### 查看 Pipeline 阶段
+
+```bash
+# 查看构建的各个阶段
+jcli pipeline stages my-job 42
+```
+
+### 查看特定阶段日志
+
+```bash
+# 查看特定节点/阶段的日志
+jcli pipeline log my-job 42 15
+```
+
+### 验证 Jenkinsfile
+
+```bash
+# 验证 Jenkinsfile 语法
+jcli pipeline validate -f Jenkinsfile
+```
+
+### 查看待处理输入
+
+```bash
+# 查看 Pipeline 中等待人工确认的步骤
+jcli pipeline pending my-job 42
+```