python-jcli 0.1.0__py3-none-any.whl

jcli/sdk/job_templates.py

@@ -0,0 +1,128 @@
+"""Job XML template generation for parameterized job creation."""
+
+from __future__ import annotations
+
+
+def generate_freestyle_xml(
+    git_url: str = "",
+    git_branch: str = "main",
+    shell_script: str = "",
+    description: str = "",
+    cron_schedule: str = "",
+) -> str:
+    """Generate XML for a Freestyle project."""
+    triggers_xml = ""
+    if cron_schedule:
+        triggers_xml = f"""
+  <triggers>
+    <hudson.triggers.TimerTrigger>
+      <spec>{cron_schedule}</spec>
+    </hudson.triggers.TimerTrigger>
+  </triggers>"""
+
+    scm_xml = ""
+    if git_url:
+        scm_xml = f"""
+  <scm class="hudson.plugins.git.GitSCM" plugin="git">
+    <configVersion>2</configVersion>
+    <userRemoteConfigs>
+      <hudson.plugins.git.UserRemoteConfig>
+        <url>{git_url}</url>
+      </hudson.plugins.git.UserRemoteConfig>
+    </userRemoteConfigs>
+    <branches>
+      <hudson.plugins.git.BranchSpec>
+        <name>*/{git_branch}</name>
+      </hudson.plugins.git.BranchSpec>
+    </branches>
+    <doGenerateSubmoduleConfigurations>false</doGenerateSubmoduleConfigurations>
+  </scm>"""
+
+    builders_xml = ""
+    if shell_script:
+        builders_xml = f"""
+  <builders>
+    <hudson.tasks.Shell>
+      <command>{_escape_xml(shell_script)}</command>
+      <configuredLocalRules/>
+    </hudson.tasks.Shell>
+  </builders>"""
+
+    return f"""<?xml version='1.1' encoding='UTF-8'?>
+<project>
+  <description>{_escape_xml(description)}</description>
+  <keepDependencies>false</keepDependencies>
+  <properties/>
+{scm_xml}
+  <canRoam>true</canRoam>
+  <disabled>false</disabled>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+{triggers_xml}
+  <concurrentBuild>false</concurrentBuild>
+{builders_xml}
+  <publishers/>
+  <buildWrappers/>
+</project>"""
+
+
+def generate_pipeline_xml(
+    git_url: str = "",
+    git_branch: str = "main",
+    jenkinsfile_path: str = "Jenkinsfile",
+    description: str = "",
+    script: str = "",
+) -> str:
+    """Generate XML for a Pipeline project.
+
+    If ``script`` is provided the definition uses ``CpsFlowDefinition``
+    (inline Pipeline script).  Otherwise when ``git_url`` is given the
+    definition is ``CpsScmFlowDefinition`` (Pipeline script from SCM).
+    """
+    definition_xml: str
+    if script:
+        # Inline script mode (CpsFlowDefinition)
+        definition_xml = f"""
+    <definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition" plugin="workflow-cps">
+      <script>{_escape_xml(script)}</script>
+      <sandbox>true</sandbox>
+    </definition>"""
+    elif git_url:
+        # SCM-based mode (CpsScmFlowDefinition)
+        definition_xml = f"""
+    <definition class="org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition" plugin="workflow-cps">
+      <scm class="hudson.plugins.git.GitSCM" plugin="git">
+        <configVersion>2</configVersion>
+        <userRemoteConfigs>
+          <hudson.plugins.git.UserRemoteConfig>
+            <url>{git_url}</url>
+          </hudson.plugins.git.UserRemoteConfig>
+        </userRemoteConfigs>
+        <branches>
+          <hudson.plugins.git.BranchSpec>
+            <name>*/{git_branch}</name>
+          </hudson.plugins.git.BranchSpec>
+        </branches>
+        <doGenerateSubmoduleConfigurations>false</doGenerateSubmoduleConfigurations>
+      </scm>
+      <scriptPath>{jenkinsfile_path}</scriptPath>
+      <lightweight>true</lightweight>
+    </definition>"""
+    else:
+        # Bare minimum (no SCM, no script)
+        definition_xml = ""
+
+    return f"""<?xml version='1.1' encoding='UTF-8'?>
+<flow-definition plugin="workflow-job">
+  <description>{_escape_xml(description)}</description>
+  <keepDependencies>false</keepDependencies>
+  <properties/>
+{definition_xml}
+  <triggers/>
+  <disabled>false</disabled>
+</flow-definition>"""
+
+
+def _escape_xml(text: str) -> str:
+    """Escape special XML characters."""
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")

jcli/sdk/node.py

@@ -0,0 +1,139 @@
+"""Jenkins Node (Agent) SDK functions.
+
+All functions take a :class:`~jcli.sdk.client.JenkinsClient` as the first argument.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from jcli.sdk.client import JenkinsClient
+
+# ------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------
+
+
+def list_nodes(client: "JenkinsClient") -> list[dict[str, Any]]:
+    """List all Jenkins nodes (built-in node + agents).
+
+    Calls ``GET /computer/api/json``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+
+    Returns:
+        List of node dictionaries, each containing ``displayName``,
+        ``offline``, ``temporarilyOffline``, and other fields.
+    """
+    data = client.get_json("/computer/api/json")
+    return data.get("computer", [])
+
+
+def get_node(client: "JenkinsClient", name: str) -> dict[str, Any]:
+    """Get details for a specific node.
+
+    Calls ``GET /computer/{name}/api/json``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        name: Node display name (e.g. ``"built-in"``, ``"agent-1"``).
+
+    Returns:
+        Node detail dictionary.
+    """
+    return client.get_json(f"/computer/{quote(name, safe='')}/api/json")
+
+
+def delete_node(client: "JenkinsClient", name: str) -> bool:
+    """Delete a node (agent) from Jenkins.
+
+    Calls ``POST /computer/{name}/doDelete``. The built-in node
+    cannot be deleted.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        name: Node display name to delete.
+
+    Returns:
+        ``True`` on success (HTTP 200/302).
+    """
+    resp = client.request("POST", f"/computer/{quote(name, safe='')}/doDelete")
+    return resp.ok
+
+
+def toggle_offline(
+    client: "JenkinsClient",
+    name: str,
+    msg: str = "",
+) -> bool:
+    """Toggle a node's offline/online state.
+
+    If the node is currently online, this marks it temporarily offline.
+    If already temporarily offline, this brings it back online.
+    Calls ``POST /computer/{name}/toggleOffline``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        name: Node display name.
+        msg: Optional offline message (shown when marking offline).
+
+    Returns:
+        ``True`` on success (HTTP 200/302).
+    """
+    data: dict[str, Any] = {}
+    if msg:
+        data["offlineMessage"] = msg
+    resp = client.post_data(f"/computer/{quote(name, safe='')}/toggleOffline", data=data)
+    return resp.ok
+
+
+def create_node(
+    client: "JenkinsClient",
+    name: str,
+    num_executors: int = 1,
+    remote_fs: str = "/tmp",
+    labels: str = "",
+    launch_method: str = "hudson.slaves.JNLPLauncher",
+) -> Any:
+    """Create a new Jenkins agent node.
+
+    Uses form submission to create a DumbSlave node via
+    ``POST /computer/doCreateItem``.
+
+    Args:
+        client: Authenticated Jenkins API client.
+        name: Node display name.
+        num_executors: Number of executors (default: 1).
+        remote_fs: Remote filesystem root (default: ``/tmp``).
+        labels: Node labels string.
+        launch_method: Stapler launch method class name.
+
+    Returns:
+        ``requests.Response`` from the creation POST.
+    """
+    data = {
+        "name": name,
+        "type": "hudson.slaves.DumbSlave",
+        "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},
+        }),
+    }
+    return client.request(
+        "POST",
+        "/computer/doCreateItem",
+        params={"name": name, "type": "hudson.slaves.DumbSlave"},
+        data=data,
+    )

jcli/sdk/output/__init__.py

@@ -0,0 +1,3 @@
+from .formatter import OutputFormatter
+
+__all__ = ["OutputFormatter"]

jcli/sdk/output/formatter.py

@@ -0,0 +1,131 @@
+import json
+from typing import Any, Dict, List, Optional, Union
+
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+
+class OutputFormatter:
+    """Output formatter supporting table, JSON, and YAML formats using Rich library."""
+
+    def __init__(self, format_type: str = "table"):
+        """Initialize formatter.
+
+        Args:
+            format_type: Output format - "table", "json", or "yaml"
+        """
+        if format_type not in ("table", "json", "yaml"):
+            raise ValueError(f"format_type must be 'table', 'json', or 'yaml', got '{format_type}'")
+        self.format_type = format_type
+        self.console = Console()
+        self.error_console = Console(stderr=True)
+
+    def print_table(
+        self,
+        headers: List[str],
+        rows: List[List[Any]],
+        title: Optional[str] = None,
+    ) -> None:
+        """Print data as a formatted table using Rich.
+
+        Args:
+            headers: Column headers
+            rows: List of row data
+            title: Optional table title
+        """
+        if self.format_type == "json":
+            self.print_json([dict(zip(headers, row)) for row in rows])
+            return
+
+        if self.format_type == "yaml":
+            self.print_yaml([dict(zip(headers, row)) for row in rows])
+            return
+
+        table = Table(
+            title=title,
+            show_header=True,
+            header_style="bold cyan",
+            box=None,
+            show_lines=False,
+            expand=False,
+        )
+
+        # Add columns with auto-width
+        for header in headers:
+            table.add_column(header, no_wrap=False)
+
+        # Add rows with alternating colors
+        for idx, row in enumerate(rows):
+            style = "dim" if idx % 2 == 1 else None
+            table.add_row(*[str(cell) for cell in row], style=style)
+
+        self.console.print(table)
+
+    def print_json(self, data: Union[Dict, List, Any]) -> None:
+        """Print data as formatted JSON.
+
+        When ``self.format_type`` is ``"yaml"``, delegates to
+        :meth:`print_yaml` instead.
+
+        Args:
+            data: Data to format as JSON
+        """
+        if self.format_type == "yaml":
+            self.print_yaml(data)
+            return
+
+        output = json.dumps(data, indent=2, ensure_ascii=False)
+        self.console.print(output)
+
+    def print_yaml(self, data: Union[Dict, List, Any]) -> None:
+        """Print data as formatted YAML.
+
+        Args:
+            data: Data to format as YAML.  If already a string it is
+                printed as-is; otherwise :func:`yaml.dump` is used.
+        """
+        if isinstance(data, str):
+            print(data)
+        else:
+            output = yaml.dump(data, allow_unicode=True, sort_keys=False, default_flow_style=False)
+            print(output, end="")
+
+    def print_error(self, message: str) -> None:
+        """Print error message in red to stderr.
+
+        Args:
+            message: Error message
+        """
+        self.error_console.print(f"[red]Error: {message}[/red]")
+
+    def print_success(self, message: str) -> None:
+        """Print success message in green.
+
+        Args:
+            message: Success message
+        """
+        self.console.print(f"[green]{message}[/green]")
+
+    def print_info(self, message: str) -> None:
+        """Print info message in blue.
+
+        Args:
+            message: Info message
+        """
+        self.console.print(f"[blue]{message}[/blue]")
+
+
+def get_formatter(ctx) -> OutputFormatter:
+    """Create an OutputFormatter from Click context.
+
+    Reads ``ctx.obj["format"]`` (default ``"table"``).
+
+    Args:
+        ctx: Click context with ``ctx.obj`` dict.
+
+    Returns:
+        Configured ``OutputFormatter`` instance.
+    """
+    format_type = ctx.obj.get("format", "table") if ctx.obj else "table"
+    return OutputFormatter(format_type=format_type)

jcli/sdk/pipeline.py

@@ -0,0 +1,121 @@
+"""Jenkins Pipeline SDK functions.
+
+Provides functions for querying Pipeline stages, step logs,
+validating Jenkinsfiles, and checking pending input actions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+
+
+def get_pipeline_stages(
+    client: JenkinsClient,
+    job_name: str,
+    build_number: int | str,
+) -> Any:
+    """Get Pipeline stage information for a specific build.
+
+    Uses the Blue Ocean wfapi describe endpoint to retrieve stage
+    and step topology for declarative or scripted Pipelines.
+
+    Args:
+        client: Configured JenkinsClient instance.
+        job_name: Job (Pipeline) name.
+        build_number: Build number to query.
+
+    Returns:
+        Parsed JSON response containing stages, status, and duration info.
+
+    Raises:
+        JenkinsNotFoundError: If job or build doesn't exist.
+        JenkinsAuthError: If authentication fails.
+        JenkinsAPIError: For other API errors.
+    """
+    path = f"job/{job_name}/{build_number}/wfapi/describe"
+    return client.get_json(path)
+
+
+def get_pipeline_log(
+    client: JenkinsClient,
+    job_name: str,
+    build_number: int | str,
+    node_id: str | int,
+) -> Any:
+    """Get log output for a specific Pipeline step (node).
+
+    Uses the Blue Ocean wfapi log endpoint to retrieve console
+    log text for an individual flow node (stage or parallel branch).
+
+    Args:
+        client: Configured JenkinsClient instance.
+        job_name: Job (Pipeline) name.
+        build_number: Build number to query.
+        node_id: Flow node ID (from stage/step info in describe).
+
+    Returns:
+        Parsed JSON response containing log text and metadata.
+
+    Raises:
+        JenkinsNotFoundError: If job, build, or node doesn't exist.
+        JenkinsAuthError: If authentication fails.
+        JenkinsAPIError: For other API errors.
+    """
+    path = f"job/{job_name}/{build_number}/execution/node/{node_id}/wfapi/log"
+    return client.get_json(path)
+
+
+def validate_jenkinsfile(
+    client: JenkinsClient,
+    content: str,
+) -> Any:
+    """Validate a Jenkinsfile (declarative Pipeline) against the Jenkins server.
+
+    Sends the Jenkinsfile content to the pipeline-model-converter endpoint
+    and returns the validation result.
+
+    Args:
+        client: Configured JenkinsClient instance.
+        content: Jenkinsfile content as a string.
+
+    Returns:
+        Parsed JSON response with validation results (errors, warnings).
+
+    Raises:
+        JenkinsAuthError: If authentication fails.
+        JenkinsConnectionError: If server is unreachable.
+    """
+    resp = client.post_data(
+        "/pipeline-model-converter/validate",
+        data={"jenkinsfile": content},
+    )
+    return resp.json()
+
+
+def get_pending_input(
+    client: JenkinsClient,
+    job_name: str,
+    build_number: int | str,
+) -> Any:
+    """Get pending input actions for a Pipeline build.
+
+    Retrieves input steps that are waiting for user interaction
+    (e.g., approval gate, parameter input).
+
+    Args:
+        client: Configured JenkinsClient instance.
+        job_name: Job (Pipeline) name.
+        build_number: Build number to query.
+
+    Returns:
+        Parsed JSON response containing pending input actions.
+
+    Raises:
+        JenkinsNotFoundError: If job or build doesn't exist.
+        JenkinsAuthError: If authentication fails.
+        JenkinsAPIError: For other API errors.
+    """
+    path = f"job/{job_name}/{build_number}/wfapi/pendingInputActions"
+    return client.get_json(path)

jcli/sdk/plugin.py

@@ -0,0 +1,155 @@
+"""Jenkins Plugin management SDK functions."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+from jcli.sdk.exceptions import JenkinsAPIError, JenkinsNotFoundError
+
+logger = logging.getLogger(__name__)
+
+# Jenkins plugin manager API paths
+PLUGIN_MANAGER_API = "/pluginManager/api/json"
+INSTALL_PLUGINS_PATH = "/pluginManager/installNecessaryPlugins"
+
+# Tree filter for listing plugins (essential fields only)
+PLUGIN_LIST_TREE = "plugins[shortName,version,active,hasUpdate]"
+
+# Tree filter for plugin details (richer fields)
+PLUGIN_DETAIL_TREE = (
+    "plugins[shortName,version,active,hasUpdate,longName,url,"
+    "requiredCoreVersion,hasRequireRestart]"
+)
+
+
+def _build_install_xml(plugins_dict: dict[str, str | None]) -> str:
+    """Build XML body for plugin installation request.
+
+    Args:
+        plugins_dict: Mapping of plugin shortName to optional version.
+            e.g. {"git": "5.0.0", "workflow-aggregator": None}
+
+    Returns:
+        XML string for POST to /pluginManager/installNecessaryPlugins.
+    """
+    lines = ["<jenkins>"]
+    for name, version in plugins_dict.items():
+        if version:
+            lines.append(f'  <install plugin="{name}@{version}" />')
+        else:
+            lines.append(f'  <install plugin="{name}" />')
+    lines.append("</jenkins>")
+    return "\n".join(lines)
+
+
+def list_plugins(client: JenkinsClient) -> list[dict[str, Any]]:
+    """Return a list of installed plugins with summary fields.
+
+    URI: GET /pluginManager/api/json?tree=plugins[shortName,version,active,hasUpdate]
+
+    Returns:
+        List of plugin dicts with keys: shortName, version, active, hasUpdate.
+    """
+    data = client.get_json(
+        PLUGIN_MANAGER_API,
+        tree=PLUGIN_LIST_TREE,
+    )
+    logger.debug("list_plugins returned %d entries", len(data.get("plugins", [])))
+    return data.get("plugins", [])
+
+
+def get_plugin(client: JenkinsClient, short_name: str) -> dict[str, Any] | None:
+    """Return details for a single plugin by shortName.
+
+    Uses the full API response and filters locally to avoid additional round-trips.
+
+    Args:
+        client: Authenticated Jenkins client.
+        short_name: Plugin short name (e.g. "git", "workflow-aggregator").
+
+    Returns:
+        Plugin detail dict, or None if not found.
+
+    Raises:
+        JenkinsNotFoundError: if no plugin matching short_name is found.
+    """
+    data = client.get_json(
+        PLUGIN_MANAGER_API,
+        tree=PLUGIN_DETAIL_TREE,
+    )
+    plugins: list[dict[str, Any]] = data.get("plugins", [])
+
+    for p in plugins:
+        if p.get("shortName") == short_name:
+            return p
+
+    raise JenkinsNotFoundError(
+        f"Plugin '{short_name}' not found on server"
+    )
+
+
+def install_plugins(
+    client: JenkinsClient,
+    plugins_dict: dict[str, str | None],
+) -> None:
+    """Install one or more plugins (optionally with specific versions).
+
+    URI: POST /pluginManager/installNecessaryPlugins
+
+    The server will download and install the requested plugins.
+    Restart may be required afterward.
+
+    Args:
+        client: Authenticated Jenkins client.
+        plugins_dict: Mapping of {plugin_shortName: version_or_None}.
+            If version is None, the latest version is installed.
+
+    Raises:
+        JenkinsAPIError: if the request fails.
+    """
+    if not plugins_dict:
+        logger.warning("install_plugins called with empty dict, nothing to do")
+        return
+
+    xml_body = _build_install_xml(plugins_dict)
+    logger.info("Installing plugins: %s", list(plugins_dict.keys()))
+    logger.debug("Install XML: %s", xml_body)
+
+    client.post_xml(INSTALL_PLUGINS_PATH, xml_body)
+
+
+def check_plugin_updates(client: JenkinsClient) -> Any:
+    """Check for plugin updates.
+
+    Triggers Jenkins to check for available plugin updates.
+
+    Args:
+        client: Jenkins API client.
+
+    Returns:
+        Parsed JSON response with update information.
+    """
+    return client.post_data("/pluginManager/checkUpdates", data={}).json()
+
+
+def uninstall_plugin(client: JenkinsClient, short_name: str) -> None:
+    """Trigger uninstall of a plugin by its short name.
+
+    URI: POST /pluginManager/plugin/{shortName}/doUninstall
+
+    The server schedules the plugin for uninstall. A restart is typically required
+    to complete the removal.
+
+    Args:
+        client: Authenticated Jenkins client.
+        short_name: Plugin short name to uninstall.
+
+    Raises:
+        JenkinsAPIError: if the request fails.
+    """
+    path = f"/pluginManager/plugin/{short_name}/doUninstall"
+    logger.info("Uninstalling plugin: %s", short_name)
+
+    client.request("POST", path)