python-jcli 0.1.0__py3-none-any.whl

jcli/plugins/view.py

@@ -0,0 +1,148 @@
+"""Jenkins View management commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from jcli.cli_helpers import get_client, get_formatter
+from jcli.sdk.view import create_view as sdk_create_view
+from jcli.sdk.view import delete_view as sdk_delete_view
+from jcli.sdk.view import get_view as sdk_get_view
+from jcli.sdk.view import list_views as sdk_list_views
+from jcli.sdk.view import update_view as sdk_update_view
+
+
+def _format_output(ctx: click.Context, data: object) -> str:
+    """Format data according to the user-specified output format."""
+    ctx_obj = ctx.obj or {}
+    fmt = ctx_obj.get("format", "table")
+
+    if fmt == "json":
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+    if fmt == "yaml":
+        import yaml
+
+        return yaml.dump(data, default_flow_style=False, allow_unicode=True)
+
+    # Default: table-like plain text
+    return str(data)
+
+
+# ------------------------------------------------------------------
+# Click command group
+# ------------------------------------------------------------------
+
+
+@click.group("view", help="Manage Jenkins views.")
+def view_group():
+    """View management commands."""
+
+
+@view_group.command("list")
+@click.pass_context
+def view_list(ctx: click.Context) -> None:
+    """List all Jenkins views."""
+    client = get_client(ctx)
+    views = sdk_list_views(client)
+
+    # Build table output
+    ctx_obj = ctx.obj or {}
+    if ctx_obj.get("format", "table") == "table":
+        if not views:
+            click.echo("No views found.")
+            return
+        for v in views:
+            job_count = len(v.get("jobs", []))
+            click.echo(f"  {v['name']} ({job_count} jobs)")
+        return
+
+    click.echo(_format_output(ctx, views))
+
+
+@view_group.command("get")
+@click.argument("view_name", metavar="NAME")
+@click.pass_context
+def view_get(ctx: click.Context, view_name: str) -> None:
+    """Get details for a Jenkins view."""
+    client = get_client(ctx)
+    data = sdk_get_view(client, view_name)
+
+    # Table output: show key fields
+    ctx_obj = ctx.obj or {}
+    if ctx_obj.get("format", "table") == "table":
+        click.echo(f"Name:        {data.get('name', view_name)}")
+        click.echo(f"URL:         {data.get('url', '')}")
+        click.echo(f"Description: {data.get('description', '')}")
+        jobs = data.get("jobs", [])
+        if jobs:
+            click.echo("Jobs:")
+            for j in jobs:
+                click.echo(f"  - {j['name']}  [{j.get('color', 'unknown')}]")
+        return
+
+    click.echo(_format_output(ctx, data))
+
+
+@view_group.command("create")
+@click.argument("view_name", metavar="NAME")
+@click.argument(
+    "config_file",
+    metavar="CONFIG_XML",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.pass_context
+def view_create(ctx: click.Context, view_name: str, config_file: Path) -> None:
+    """Create a new Jenkins view from an XML config file."""
+    xml_data = config_file.read_text(encoding="utf-8")
+
+    client = get_client(ctx)
+    sdk_create_view(client, view_name, xml_data)
+    click.echo(f"View '{view_name}' created successfully.")
+
+
+@view_group.command("update")
+@click.argument("view_name")
+@click.argument("config_file", type=click.Path(exists=True, dir_okay=False))
+@click.pass_context
+def update_view_cmd(ctx, view_name, config_file):
+    """Update a view's configuration from an XML file."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        with open(config_file, "r", encoding="utf-8") as f:
+            config_xml = f.read()
+        sdk_update_view(client, view_name, config_xml)
+        fmt.print_success(f"View '{view_name}' updated.")
+    except Exception as exc:
+        fmt.print_error(str(exc))
+
+
+@view_group.command("delete")
+@click.argument("view_name", metavar="NAME")
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    help="Skip confirmation prompt.",
+)
+@click.pass_context
+def view_delete(ctx: click.Context, view_name: str, yes: bool) -> None:
+    """Delete a Jenkins view."""
+    if not yes:
+        click.confirm(
+            f"Are you sure you want to delete view '{view_name}'?",
+            abort=True,
+        )
+
+    client = get_client(ctx)
+    sdk_delete_view(client, view_name)
+    click.echo(f"View '{view_name}' deleted successfully.")
+
+
+def register(parent_group: click.Group) -> None:
+    """Register the view subgroup under the parent Click group."""
+    parent_group.add_command(view_group)

jcli/sdk/build.py

@@ -0,0 +1,182 @@
+"""Jenkins Build SDK — trigger, query, stop builds and manage queue."""
+
+from __future__ import annotations
+
+import time
+import urllib.parse
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+from jcli.sdk.exceptions import JenkinsError
+
+
+def _job_path(job_name: str) -> str:
+    """Convert a job name to a Jenkins URL path segment.
+
+    Handles nested jobs (folder/sub-job) by converting each slash-separated
+    segment into ``/job/<segment>``.
+    """
+    segments = job_name.split("/")
+    return "/job/" + "/job/".join(segments)
+
+
+def trigger_build(
+    client: JenkinsClient,
+    job_name: str,
+    params: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Trigger a new build for the given job.
+
+    If *params* is provided the build is triggered with parameters via
+    ``/buildWithParameters``, otherwise a plain ``/build`` is used.
+    Jenkins returns a ``Location`` header pointing to the queued item.
+    This function follows that redirect and parses the queue-item JSON.
+
+    :returns: Queue item info as returned by Jenkins (dict).
+    """
+    path = _job_path(job_name)
+    if params:
+        url = f"{path}/buildWithParameters"
+        resp = client.request("POST", url, params=params, allow_redirects=False)
+    else:
+        url = f"{path}/build"
+        resp = client.request("POST", url, allow_redirects=False)
+
+    # Jenkins responds with 201 Created or 302 Found and a Location header
+    # pointing to the queue item.  Follow that URL to get the queue item JSON.
+    location = resp.headers.get("Location")
+    if location:
+        queue_path = urllib.parse.urlparse(location).path
+        # Strip the base URL prefix — client.get_json accepts an absolute path
+        if queue_path.startswith(client.base_url):
+            queue_path = queue_path[len(client.base_url) :]
+        try:
+            return client.get_json(queue_path + "api/json")
+        except JenkinsError:
+            pass
+
+    # Fallback — return a minimal dict
+    return {"status": "queued", "url": location or ""}
+
+
+def get_build(
+    client: JenkinsClient,
+    job_name: str,
+    number: int,
+) -> dict[str, Any]:
+    """Get details for a specific build.
+
+    :returns: Build details as returned by the Jenkins API.
+    """
+    path = f"{_job_path(job_name)}/{number}"
+    return client.get_json(f"{path}/api/json")
+
+
+def get_builds(
+    client: JenkinsClient,
+    job_name: str,
+    limit: int = 10,
+) -> list[dict[str, Any]]:
+    """List recent builds for a job.
+
+    :param limit: Maximum number of builds to return (applied client-side).
+    :returns: List of build dicts (trimmed to *limit*).
+    """
+    path = _job_path(job_name)
+    tree = f"builds[number,url,result,timestamp,duration,building]{f'{{{0},{limit - 1}}}' if limit > 0 else ''}"
+    data = client.get_json(f"{path}/api/json", tree=tree)
+    builds: list[dict[str, Any]] = data.get("builds", [])
+    return builds[:limit]
+
+
+def get_build_log(
+    client: JenkinsClient,
+    job_name: str,
+    number: int,
+    start: int = 0,
+) -> str:
+    """Retrieve the console log for a build.
+
+    :param start: Byte offset to start reading from (useful for polling).
+    :returns: Console log text.
+    """
+    path = f"{_job_path(job_name)}/{number}/consoleText"
+    resp = client.request("GET", path)
+    text = resp.text
+    if start > 0:
+        return text[start:]
+    return text
+
+
+def stop_build(
+    client: JenkinsClient,
+    job_name: str,
+    number: int,
+) -> dict[str, Any]:
+    """Stop (abort) a running build.
+
+    :returns: Empty dict on success.
+    """
+    path = f"{_job_path(job_name)}/{number}"
+    client.request("POST", f"{path}/stop")
+    return {}
+
+
+def get_queue(client: JenkinsClient) -> list[dict[str, Any]]:
+    """Return all items currently in the Jenkins build queue.
+
+    :returns: List of queue item dicts.
+    """
+    data = client.get_json("/queue/api/json")
+    return data.get("items", [])
+
+
+def cancel_queue_item(
+    client: JenkinsClient,
+    queue_id: int,
+) -> dict[str, Any]:
+    """Cancel a queued item.
+
+    :param queue_id: Numeric queue item ID.
+    :returns: Empty dict on success.
+    """
+    client.request("POST", "/queue/cancelItem", params={"id": queue_id})
+    return {}
+
+
+def get_build_artifacts(
+    client: JenkinsClient,
+    job_name: str,
+    build_number: int | str,
+) -> Any:
+    """Get build artifacts.
+
+    Lists artifacts produced by a build.
+    """
+    path = _job_path(job_name) + f"/{build_number}/api/json"
+    return client.get_json(path, tree="artifacts[fileName,relativePath]")
+
+
+def wait_for_build(
+    client: JenkinsClient,
+    job_name: str,
+    number: int,
+    timeout: int = 600,
+    poll_interval: int = 2,
+) -> dict[str, Any]:
+    """Poll until a build completes or *timeout* is reached.
+
+    :param timeout: Maximum seconds to wait.
+    :param poll_interval: Seconds between status checks.
+    :returns: Final build dict.
+    :raises TimeoutError: if the build does not finish within *timeout*.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        build = get_build(client, job_name, number)
+        if not build.get("building", False):
+            return build
+        time.sleep(poll_interval)
+    raise TimeoutError(
+        f"Build {job_name}#{number} did not complete within {timeout}s"
+    )

jcli/sdk/client.py

@@ -0,0 +1,264 @@
+"""Jenkins API client."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import requests
+
+from jcli.sdk.exceptions import (
+    JenkinsAPIError,
+    JenkinsAuthError,
+    JenkinsConnectionError,
+    JenkinsCrumbError,
+    JenkinsNotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+
+# Retry configuration
+MAX_RETRIES = 1
+RETRYABLE_STATUS_CODES = {503, 504}
+
+
+class JenkinsClient:
+    """Lightweight Jenkins REST API client.
+
+    Supports automatic HTTP Basic Auth, Crumb (CSRF) handling,
+    and maps HTTP errors to typed exceptions.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str = "",
+        token: str = "",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        if username and token:
+            self.session.auth = (username, token)
+
+        # Crumb cache: lazily fetched on first POST
+        self._crumb_header: str | None = None
+        self._crumb_value: str | None = None
+
+    # ------------------------------------------------------------------
+    # URL helpers
+    # ------------------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    # ------------------------------------------------------------------
+    # Crumb (CSRF token) handling
+    # ------------------------------------------------------------------
+
+    def _fetch_crumb(self) -> None:
+        """Fetch Jenkins Crumb from ``/crumbIssuer/api/json``.
+
+        Caches the header name and value for subsequent POST requests.
+        Raises ``JenkinsCrumbError`` if the fetch fails.
+        """
+        url = self._url("/crumbIssuer/api/json")
+        try:
+            resp = self.session.get(url, timeout=10)
+        except requests.RequestException as exc:
+            raise JenkinsCrumbError(
+                f"Failed to connect for crumb: {exc}"
+            ) from exc
+
+        if resp.status_code == 404:
+            # Crumb issuer disabled – nothing to do
+            logger.debug("Crumb issuer not available (404), CSRF protection disabled")
+            return
+
+        if resp.status_code != 200:
+            raise JenkinsCrumbError(
+                f"Crumb fetch failed with status {resp.status_code}"
+            )
+
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise JenkinsCrumbError(
+                "Crumb response is not valid JSON"
+            ) from exc
+
+        self._crumb_header = data.get("crumbRequestField")
+        self._crumb_value = data.get("crumb")
+        if not self._crumb_header or not self._crumb_value:
+            raise JenkinsCrumbError("Crumb response missing header or value")
+
+        logger.debug("Crumb fetched: %s", self._crumb_header)
+
+    def _ensure_crumb(self) -> dict[str, str]:
+        """Return crumb headers, fetching if needed. Empty dict if unavailable."""
+        if self._crumb_header and self._crumb_value:
+            return {self._crumb_header: self._crumb_value}
+
+        self._fetch_crumb()
+
+        if self._crumb_header and self._crumb_value:
+            return {self._crumb_header: self._crumb_value}
+        return {}
+
+    # ------------------------------------------------------------------
+    # Error mapping
+    # ------------------------------------------------------------------
+
+    def _map_error(self, resp: requests.Response) -> None:
+        """Raise a typed exception for error status codes."""
+        status = resp.status_code
+        if status == 401:
+            raise JenkinsAuthError(
+                f"Authentication failed (401) for {resp.url}"
+            )
+        if status == 404:
+            raise JenkinsNotFoundError(
+                f"Resource not found (404) for {resp.url}"
+            )
+        if status >= 400:
+            raise JenkinsAPIError(
+                f"API error {status} for {resp.url}",
+                status_code=status,
+            )
+
+    # ------------------------------------------------------------------
+    # Core request method
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        data: Any = None,
+        json: Any = None,
+        timeout: int = 30,
+        retries: int = MAX_RETRIES,
+        **kwargs: Any,
+    ) -> requests.Response:
+        """Unified HTTP request with error mapping and retry on 503/504.
+
+        :param method: HTTP method (GET, POST, PUT, DELETE, …)
+        :param path: URL path relative to base_url
+        :param retries: Number of retries on 503/504 (default 1)
+        :returns: ``requests.Response``
+        :raises JenkinsAuthError: on 401
+        :raises JenkinsNotFoundError: on 404
+        :raises JenkinsAPIError: on other 4xx
+        :raises JenkinsConnectionError: on connection failures
+        """
+        url = self._url(path)
+        req_headers: dict[str, str] = dict(headers) if headers else {}
+
+        # Add crumb for mutating methods
+        if method.upper() in ("POST", "PUT", "DELETE"):
+            crumb_headers = self._ensure_crumb()
+            req_headers.update(crumb_headers)
+
+        last_exc: Exception | None = None
+        for attempt in range(1 + retries):
+            try:
+                resp = self.session.request(
+                    method,
+                    url,
+                    params=params,
+                    headers=req_headers,
+                    data=data,
+                    json=json,
+                    timeout=timeout,
+                    **kwargs,
+                )
+            except requests.ConnectionError as exc:
+                raise JenkinsConnectionError(
+                    f"Connection failed: {exc}"
+                ) from exc
+            except requests.Timeout as exc:
+                raise JenkinsConnectionError(
+                    f"Request timed out after {timeout}s"
+                ) from exc
+            except requests.RequestException as exc:
+                raise JenkinsConnectionError(
+                    f"Request failed: {exc}"
+                ) from exc
+
+            if resp.status_code in RETRYABLE_STATUS_CODES and attempt < retries:
+                logger.warning(
+                    "Retryable status %d on %s %s (attempt %d/%d)",
+                    resp.status_code,
+                    method,
+                    path,
+                    attempt + 1,
+                    retries,
+                )
+                time.sleep(0.1)
+                continue
+
+            self._map_error(resp)
+            return resp
+
+        # Should not reach here, but safety net
+        return resp  # type: ignore[possibly-undefined]
+
+    # ------------------------------------------------------------------
+    # Convenience methods
+    # ------------------------------------------------------------------
+
+    def get_json(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        tree: str | None = None,
+    ) -> Any:
+        """GET request returning parsed JSON.
+
+        :param path: URL path relative to base_url
+        :param params: Query parameters
+        :param tree: Jenkins tree parameter for field filtering
+        :returns: Parsed JSON (dict or list)
+        """
+        if tree:
+            params = dict(params) if params else {}
+            params["tree"] = tree
+        resp = self.request("GET", path, params=params)
+        return resp.json()
+
+    def post_xml(self, path: str, xml_data: str | bytes) -> requests.Response:
+        """POST with ``application/xml`` content type.
+
+        :param path: URL path relative to base_url
+        :param xml_data: XML payload (str or bytes)
+        :returns: ``requests.Response``
+        """
+        return self.request(
+            "POST",
+            path,
+            data=xml_data.encode("utf-8") if isinstance(xml_data, str) else xml_data,
+            headers={"Content-Type": "application/xml"},
+        )
+
+    def post_data(
+        self,
+        path: str,
+        data: dict[str, Any] | str | bytes,
+        content_type: str = "application/x-www-form-urlencoded",
+    ) -> requests.Response:
+        """POST with arbitrary content type.
+
+        :param path: URL path relative to base_url
+        :param data: Form data (dict), raw string, or bytes
+        :param content_type: Content-Type header (default form-encoded)
+        :returns: ``requests.Response``
+        """
+        return self.request(
+            "POST",
+            path,
+            data=data,
+            headers={"Content-Type": content_type},
+        )