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

jcli/specs/plugins/jenkins_methods.py

@@ -0,0 +1,332 @@
+"""Jenkins method plugins: build trigger, replay, node create."""
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Any
+
+from cliyard.plugin import register_method
+
+
+def _job_path(job_name: str) -> str:
+    """Convert job name to Jenkins URL path (folder/sub → /job/folder/job/sub)."""
+    segments = job_name.split("/")
+    return "/job/" + "/job/".join(segments)
+
+
+def _parse_key_values(items: Any) -> dict[str, str]:
+    """Parse a sequence of ``KEY=VALUE`` strings into a dict."""
+    result: dict[str, str] = {}
+    for item in items or ():
+        if "=" in item:
+            k, v = item.split("=", 1)
+            result[k.strip()] = v.strip()
+    return result
+
+
+def _queue_item_from_location(http_client: Any, location: str) -> dict[str, Any] | None:
+    """Follow a Jenkins Location header to the queue-item JSON.
+
+    Handles both absolute URLs (``http://host/queue/item/12/``) and
+    relative paths (``/queue/item/12/``).  Returns ``None`` when the
+    queue item cannot be fetched.
+    """
+    if not location:
+        return None
+    queue_path = urllib.parse.urlparse(location).path
+    if queue_path.startswith(http_client.base_url):
+        queue_path = queue_path[len(http_client.base_url):]
+    if not queue_path.startswith("/"):
+        queue_path = "/" + queue_path
+    try:
+        resp = http_client.request("GET", queue_path.rstrip("/") + "/api/json")
+        return resp.json()
+    except Exception:
+        return None
+
+
+@register_method("jenkins_build_trigger")
+def jenkins_build_trigger(
+    params: dict[str, Any], http_client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Trigger a build with Location header following.
+
+    POST /job/{job}/build or /buildWithParameters, follow Location to queue item.
+
+    Args:
+        params: Body params — ``job_name`` (str), ``params`` (list of
+            ``KEY=VALUE`` strings).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dict with ``status``, ``url`` (queue item URL) and optionally
+        ``queue_item`` (parsed queue-item JSON).
+    """
+    job_name = params.get("job_name", "")
+    build_params = _parse_key_values(params.get("params"))
+
+    path = _job_path(job_name)
+    if build_params:
+        url = f"{path}/buildWithParameters"
+        resp = http_client.request("POST", url, query_params=build_params)
+    else:
+        url = f"{path}/build"
+        resp = http_client.request("POST", url)
+
+    location = resp.headers.get("Location", "")
+    queue_item = _queue_item_from_location(http_client, location)
+    if queue_item is not None:
+        return {"status": "queued", "url": location, "queue_item": queue_item}
+    return {"status": "queued", "url": location}
+
+
+@register_method("jenkins_build_rebuild")
+def jenkins_build_rebuild(
+    params: dict[str, Any], http_client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Rebuild a build: auto-fetch previous build parameters + ``--set`` override.
+
+    Flow: GET previous parameters → merge ``--set`` overrides →
+    POST buildWithParameters or /build.
+
+    Args:
+        params: Body params — ``job_name`` (str), ``build_number`` (int),
+            ``set`` (list of ``KEY=VALUE`` overrides).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dict with ``status``, ``url`` (queue item URL) and ``parameters``
+        (the merged parameter dict actually sent).
+    """
+    job_name = params.get("job_name", "")
+    build_number = params.get("build_number", 0)
+    set_overrides = params.get("set") or ()
+
+    path = _job_path(job_name)
+
+    # Step 1: Fetch previous build parameters
+    build_params: dict[str, str] = {}
+    try:
+        resp = http_client.request(
+            "GET",
+            f"{path}/{build_number}/api/json",
+            query_params={"tree": "actions[parameters[name,value]]"},
+        )
+        for action in resp.json().get("actions", []):
+            for p in action.get("parameters", []):
+                build_params[str(p["name"])] = p["value"]
+    except Exception:
+        pass  # Non-parameterized build
+
+    # Step 2: Apply --set overrides
+    build_params.update(_parse_key_values(set_overrides))
+
+    # Step 3: Trigger build
+    if build_params:
+        resp = http_client.request(
+            "POST", f"{path}/buildWithParameters", query_params=build_params
+        )
+    else:
+        resp = http_client.request("POST", f"{path}/build")
+
+    location = resp.headers.get("Location", "")
+    return {"status": "queued", "url": location, "parameters": build_params}
+
+
+@register_method("jenkins_build_replay")
+def jenkins_build_replay(
+    params: dict[str, Any], http_client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Replay a build with a provided Jenkinsfile via the Jenkins Replay API.
+
+    POST /job/{job}/{build}/replay/run with form data carrying the
+    Jenkinsfile content (``_.mainScript``), a crumb, the ``Submit``
+    button value and the serialized ``json`` form.  On success Jenkins
+    responds with a 302 redirect (new build queued) or 200.
+
+    Args:
+        params: Body params — ``job_name`` (str), ``build_number`` (int),
+            ``jenkinsfile`` (str, file content or path to read).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dict with ``status`` (``replayed``/``failed``), ``job`` and
+        ``build``; on failure also ``code`` and ``detail``.
+    """
+    import os as _os
+
+    job_name = params.get("job_name", "")
+    build_number = params.get("build_number", 0)
+    jenkinsfile = params.get("jenkinsfile", "")
+
+    # ``type: file`` may arrive as a path string (plugin callbacks do not
+    # pre-read file contents) — read it when it points at an existing file.
+    if jenkinsfile and _os.path.isfile(jenkinsfile):
+        with open(jenkinsfile, encoding="utf-8") as _f:
+            jenkinsfile = _f.read()
+
+    path = _job_path(job_name)
+
+    crumb = http_client.default_headers.get("Jenkins-Crumb", "")
+    if not crumb:
+        try:
+            resp = http_client.request("GET", "/crumbIssuer/api/json")
+            crumb = resp.json().get("crumb", "")
+        except Exception:
+            crumb = ""
+
+    # F12-verified Replay form (4 fields; missing ones cause 400/500).
+    form_data = {
+        "_.mainScript": jenkinsfile,
+        "Submit": "运行",
+        "Jenkins-Crumb": crumb,
+        "json": json.dumps(
+            {"mainScript": jenkinsfile, "": "", "Submit": "运行", "Jenkins-Crumb": crumb},
+            ensure_ascii=False,
+        ),
+    }
+    # Form-encoded POST — _session directly (HttpClient.request would JSON-encode).
+    resp = http_client._session.post(
+        f"{http_client.base_url}{path}/{build_number}/replay/run",
+        data=form_data,
+        headers={**http_client.default_headers, "Content-Type": "application/x-www-form-urlencoded"},
+        timeout=getattr(http_client, "timeout", 30),
+        allow_redirects=False,
+    )
+    if resp.status_code in (302, 200):
+        return {"status": "replayed", "job": job_name, "build": build_number}
+    return {"status": "failed", "code": resp.status_code, "detail": resp.text[:300]}
+
+
+@register_method("jenkins_node_create")
+def jenkins_node_create(
+    params: dict[str, Any], http_client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Create a Jenkins agent node via form-encoded POST.
+
+    POST /computer/doCreateItem with form-encoded data (not JSON).
+
+    Args:
+        params: Body params — ``name`` (str), ``num_executors`` (int),
+            ``remote_fs`` (str), ``labels`` (str), ``launch_method`` (str).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dict with ``status`` and ``name``.
+    """
+    name = params.get("name", "")
+    num_executors = params.get("num_executors", 1)
+    remote_fs = params.get("remote_fs", "/tmp")
+    labels = params.get("labels", "")
+    launch_method = params.get("launch_method", "hudson.slaves.JNLPLauncher")
+
+    node_json = json.dumps({
+        "name": name,
+        "nodeDescription": "",
+        "numExecutors": str(num_executors),
+        "remoteFS": remote_fs,
+        "labelString": labels,
+        "mode": "NORMAL",
+        "type": "hudson.slaves.DumbSlave",
+        "retentionStrategy": {"stapler-class": "hudson.slaves.RetentionStrategy$Always"},
+        "nodeProperties": {"stapler-class-bag": "true"},
+        "launcher": {"stapler-class": launch_method},
+    })
+
+    # Form-encoded (not JSON) — use _session directly with merged default
+    # headers so the Authorization / crumb chain still applies.
+    form_data = (
+        f"name={urllib.parse.quote(name)}"
+        f"&type=hudson.slaves.DumbSlave"
+        f"&json={urllib.parse.quote(node_json)}"
+    )
+    http_client._session.post(
+        f"{http_client.base_url}/computer/doCreateItem",
+        params={"name": name, "type": "hudson.slaves.DumbSlave"},
+        data=form_data,
+        headers={**http_client.default_headers, "Content-Type": "application/x-www-form-urlencoded"},
+        timeout=http_client.timeout,
+    )
+    return {"status": "created", "name": name}
+
+
+def _tail_lines(text: str, n: int) -> str:
+    """Return the last *n* lines of *text* (all of it when shorter)."""
+    if n <= 0:
+        return text
+    lines = text.splitlines()
+    if len(lines) <= n:
+        return text
+    return "\n".join(lines[-n:]) + "\n"
+
+
+@register_method("jenkins_build_log")
+def jenkins_build_log(
+    params: dict[str, Any], http_client: Any, config: dict[str, Any]
+) -> dict[str, Any]:
+    """Show a build's console log (``tail`` semantics).
+
+    * no flags — print the whole log once
+    * ``-n N`` — print only the last *N* lines
+    * ``-f`` — follow live; history (all, or the last ``-n N`` lines) is
+      printed first, then newly appended lines stream until the build ends
+
+    Follow polls the full console text and slices locally by byte offset,
+    so it does not rely on Jenkins' ``?start=`` support (some servers and
+    proxies ignore it) — each refresh prints only new lines, no reprints.
+    Output is written directly by this plugin (``_formatted``), so the
+    cliyard/jcli wrappers do not re-format.
+
+    Args:
+        params: Body params — ``job_name`` (str), ``number`` (int),
+            ``follow`` (bool), ``lines`` (int).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        ``{"_formatted": True}`` — output already printed.
+    """
+    import time as _time
+
+    job_name = params.get("job_name", "")
+    number = params.get("number", 0)
+    follow = params.get("follow", False)
+    lines = params.get("lines", 0) or 0
+
+    path = _job_path(job_name)
+    log_url = f"{path}/{number}/consoleText"
+
+    first_text = http_client.request("GET", log_url).text
+
+    if not follow:
+        print(_tail_lines(first_text, lines), end="")
+        return {"_formatted": True}
+
+    print(_tail_lines(first_text, lines), end="", flush=True)
+    offset = len(first_text)
+
+    try:
+        while True:
+            resp = http_client.request("GET", log_url)
+            text = resp.text
+            total = len(text)
+            if total > offset:
+                print(text[offset:], end="", flush=True)
+                offset = total
+
+            build = http_client.request(
+                "GET",
+                f"{path}/{number}/api/json",
+                query_params={"tree": "building"},
+            ).json()
+            if not build.get("building"):
+                break
+            _time.sleep(0.25)
+    except KeyboardInterrupt:
+        pass
+    print()
+    return {"_formatted": True}

jcli/specs/plugins/jenkins_pipeline_validate.py

@@ -0,0 +1,51 @@
+"""Jenkins Pipeline validate plugin: validate Jenkinsfile content."""
+from cliyard.plugin import register_method
+
+
+@register_method("jenkins_pipeline_validate")
+def jenkins_pipeline_validate(params, http_client, config):
+    """Validate a Jenkinsfile against the Jenkins server.
+
+    Sends the Jenkinsfile content to the pipeline-model-converter endpoint
+    and returns the validation result.
+
+    Args:
+        params: Dictionary containing 'jenkinsfile' key with file path.
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Parsed validation result (text or JSON).
+    """
+    jenkinsfile_path = params.get("jenkinsfile") or params.get("body", {}).get("jenkinsfile", "")
+    if not jenkinsfile_path:
+        return {"valid": False, "errors": ["No Jenkinsfile path provided"]}
+
+    try:
+        with open(jenkinsfile_path, "r", encoding="utf-8") as f:
+            jenkinsfile_content = f.read()
+    except Exception as e:
+        return {"valid": False, "errors": [f"Failed to read Jenkinsfile: {e}"]}
+
+    from urllib.parse import urlencode
+    form_data = urlencode({"jenkinsfile": jenkinsfile_content})
+    headers = {"Content-Type": "application/x-www-form-urlencoded"}
+    resp = http_client.request(
+        "POST",
+        "/pipeline-model-converter/validate",
+        data=form_data,
+        headers=headers,
+    )
+    
+    try:
+        return resp.json()
+    except ValueError:
+        text = resp.text.strip()
+        if "Errors encountered" in text:
+            lines = text.split('\n')
+            errors = [line.strip() for line in lines[1:] if line.strip()]
+            return {"valid": False, "errors": errors}
+        elif "successfully validated" in text.lower():
+            return {"valid": True, "message": text}
+        else:
+            return {"valid": None, "raw": text}

jcli/specs/plugins/jenkins_plugin.py

@@ -0,0 +1,77 @@
+"""Jenkins Plugin management plugin: get plugin details and install plugins."""
+from cliyard.plugin import register_method
+
+
+@register_method("jenkins_plugin_get")
+def jenkins_plugin_get(params, http_client, config):
+    """Get details for a single plugin by short name.
+
+    Fetches all plugins and filters locally to find the matching one.
+
+    Args:
+        params: Dictionary containing 'short_name' key.
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Plugin detail dict, or error dict if not found.
+    """
+    short_name = params.get("short_name", "")
+    if not short_name:
+        return {"error": "No plugin name provided"}
+
+    # Fetch all plugins with detailed info
+    resp = http_client.request(
+        "GET",
+        "/pluginManager/api/json",
+        query_params={"tree": "plugins[shortName,version,active,hasUpdate,longName,url,requiredCoreVersion,hasRequireRestart]"}
+    )
+    data = resp.json()
+    plugins = data.get("plugins", [])
+
+    for p in plugins:
+        if p.get("shortName") == short_name:
+            return p
+
+    return {"error": f"Plugin '{short_name}' not found"}
+
+
+@register_method("jenkins_plugin_install")
+def jenkins_plugin_install(params, http_client, config):
+    """Install one or more plugins (optionally with specific versions).
+
+    Args:
+        params: Dictionary containing 'plugins' key with list of plugin specs.
+                Each spec can be 'name' or 'name@version'.
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Success message or error dict.
+    """
+    plugins_list = params.get("plugins", [])
+    if not plugins_list:
+        return {"error": "No plugins specified"}
+
+    lines = ["<jenkins>"]
+    for spec in plugins_list:
+        if "@" in spec:
+            name, version = spec.split("@", 1)
+            lines.append(f'  <install plugin="{name}@{version}" />')
+        else:
+            lines.append(f'  <install plugin="{spec}" />')
+    lines.append("</jenkins>")
+    xml_body = "\n".join(lines)
+
+    headers = {"Content-Type": "application/xml"}
+    resp = http_client.request(
+        "POST",
+        "/pluginManager/installNecessaryPlugins",
+        data=xml_body.encode("utf-8"),
+        headers=headers
+    )
+
+    if resp.status_code == 200:
+        return {"status": "success", "message": "Plugins scheduled for installation"}
+    else:
+        return {"error": f"Install failed with status {resp.status_code}"}

jcli/specs/plugins/jenkins_system.py

@@ -0,0 +1,137 @@
+"""Jenkins System management plugin: info, load, script, token methods."""
+from cliyard.plugin import register_method
+
+
+@register_method("jenkins_system_info")
+def jenkins_system_info(params, http_client, config):
+    """Get Jenkins system information.
+
+    Calls GET /api/json and extracts version from X-Jenkins header.
+    Aggregates executor count, mode, quieting down status, nodes, and jobs.
+
+    Args:
+        params: Dictionary (unused, empty body).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dictionary with version, num_executors, mode, quietingDown,
+        slaveAgentPort, num_nodes, num_jobs.
+    """
+    resp = http_client.request("GET", "/api/json")
+    data = resp.json()
+
+    version = resp.headers.get("X-Jenkins", "unknown")
+
+    # Count nodes from computer list
+    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", [])),
+    }
+
+
+@register_method("jenkins_system_load")
+def jenkins_system_load(params, http_client, config):
+    """Get current system load statistics.
+
+    Aggregates queue length from /queue/api/json and executor usage
+    from /computer/api/json.
+
+    Args:
+        params: Dictionary (unused, empty body).
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Dictionary with queue_length, total_executors, busy_executors,
+        idle_executors.
+    """
+    queue_data = http_client.request("GET", "/queue/api/json").json()
+    queue_items = queue_data.get("items", [])
+    queue_length = len(queue_items) if isinstance(queue_items, list) else 0
+
+    computer_data = http_client.request("GET", "/computer/api/json").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,
+    }
+
+
+@register_method("jenkins_system_script")
+def jenkins_system_script(params, http_client, config):
+    """Execute a Groovy script on the Jenkins server.
+
+    Posts form-encoded script to /scriptText.
+
+    Args:
+        params: Dictionary with 'script' key containing Groovy code.
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Script output as text.
+    """
+    script = params.get("script", "")
+    if not script:
+        return {"error": "No script provided"}
+
+    resp = http_client.request(
+        "POST",
+        "/scriptText",
+        data={"script": script},
+    )
+    return {"output": resp.text}
+
+
+@register_method("jenkins_system_token")
+def jenkins_system_token(params, http_client, config):
+    """Generate a new API token for a user.
+
+    Posts form-encoded newTokenName to
+    /user/{username}/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken
+
+    Args:
+        params: Dictionary with 'username' and 'token_name' keys.
+        http_client: Configured HttpClient instance.
+        config: Plugin configuration (unused).
+
+    Returns:
+        Parsed JSON with token data including the token value.
+    """
+    username = params.get("username", "")
+    token_name = params.get("token_name", "jcli-generated")
+
+    if not username:
+        return {"error": "No username provided"}
+
+    path = f"/user/{username}/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken"
+    resp = http_client.request(
+        "POST",
+        path,
+        data={"newTokenName": token_name},
+    )
+    return resp.json()