python-jcli 0.1.0__py3-none-any.whl

jcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

jcli/__main__.py

@@ -0,0 +1,3 @@
+from jcli.cli import main
+
+main()

jcli/cli.py

@@ -0,0 +1,79 @@
+"""Jenkins CLI - Command line interface for managing Jenkins."""
+
+import logging
+import sys
+
+import click
+
+from jcli import __version__
+from jcli.plugins import register_commands
+
+logger = logging.getLogger("jcli")
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="jcli")
+@click.option(
+    "-f",
+    "--format",
+    "output_format",
+    default="table",
+    type=click.Choice(["table", "json", "yaml"]),
+    help="Output format.",
+)
+@click.option("-p", "--profile", default=None, help="Configuration profile name.")
+@click.option("-s", "--server", default=None, help="Jenkins server URL.")
+@click.option("-d", "--debug", is_flag=True, default=False, help="Enable debug output.")
+@click.pass_context
+def cli(ctx, output_format, profile, server, debug):
+    """Jenkins CLI - Manage Jenkins from the command line."""
+    ctx.ensure_object(dict)
+    ctx.obj["format"] = output_format
+    ctx.obj["profile"] = profile
+    ctx.obj["server"] = server
+    ctx.obj["debug"] = debug
+
+    # Configure debug logging when --debug / -d is set
+    if debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s %(name)s %(levelname)s %(message)s",
+            stream=sys.stderr,
+        )
+        logger.debug("Debug logging enabled")
+    else:
+        # Ensure WARNING+ level when not in debug mode
+        logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
+
+
+# Register all plugin subcommands
+register_commands(cli)
+
+
+@click.group()
+def completion():
+    """Shell completion support for jcli."""
+    pass
+
+
+@completion.command()
+@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+def show(shell):
+    """Output shell completion script for the specified shell."""
+    from click.shell_completion import BashComplete, ZshComplete, FishComplete
+
+    shell_cls = {"bash": BashComplete, "zsh": ZshComplete, "fish": FishComplete}
+    complete = shell_cls[shell](cli, {}, "jcli", "_JCLI_COMPLETE")
+    click.echo(complete.source(), nl=False)
+
+
+cli.add_command(completion)
+
+
+def main():
+    """CLI entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

jcli/cli_helpers.py

@@ -0,0 +1,58 @@
+"""Centralized CLI helpers for creating JenkinsClient and OutputFormatter.
+
+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.
+"""
+
+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."""
+    obj = ctx.obj or {}
+    fmt = obj.get("format", "table")
+
+    return OutputFormatter(format_type=fmt)

jcli/plugins/__init__.py

@@ -0,0 +1,28 @@
+"""Jenkins CLI plugins - register all subcommands."""
+
+import click
+
+from jcli.plugins.build import register as register_build
+from jcli.plugins.config import register as register_config
+from jcli.plugins.credential import register as register_credential
+from jcli.plugins.job import register as register_job
+from jcli.plugins.node import register as register_node
+from jcli.plugins.pipeline import register as register_pipeline
+from jcli.plugins.plugin import register as register_plugin
+from jcli.plugins.skills import register as register_skills
+from jcli.plugins.system import register as register_system
+from jcli.plugins.view import register as register_view
+
+
+def register_commands(group: click.Group) -> None:
+    """Register all plugin subcommands under the main CLI group."""
+    register_build(group)
+    register_config(group)
+    register_credential(group)
+    register_job(group)
+    register_node(group)
+    register_pipeline(group)
+    register_plugin(group)
+    register_skills(group)
+    register_system(group)
+    register_view(group)

jcli/plugins/build.py

@@ -0,0 +1,197 @@
+"""Jenkins Build management commands."""
+
+from __future__ import annotations
+
+import click
+
+from jcli.cli_helpers import get_client, get_formatter
+from jcli.sdk.build import (
+    cancel_queue_item,
+    get_build,
+    get_build_artifacts,
+    get_build_log,
+    get_builds,
+    get_queue,
+    stop_build,
+    trigger_build,
+)
+from jcli.sdk.exceptions import JenkinsError
+
+
+def _parse_params(raw_params: tuple[str, ...]) -> dict[str, str]:
+    """Parse ``KEY=VAL`` strings into a dict."""
+    params: dict[str, str] = {}
+    for item in raw_params:
+        if "=" not in item:
+            raise click.BadParameter(f"Invalid parameter format: {item} (expected KEY=VAL)")
+        key, _, value = item.partition("=")
+        params[key.strip()] = value.strip()
+    return params
+
+
+# ------------------------------------------------------------------
+# Build group
+# ------------------------------------------------------------------
+
+
+@click.group("build", help="Manage Jenkins builds.")
+def build_group():
+    """Build management commands."""
+
+
+@build_group.command("trigger")
+@click.argument("job_name")
+@click.option(
+    "--params", "-p",
+    multiple=True,
+    help="Build parameters as KEY=VAL pairs. Repeatable.",
+)
+@click.pass_context
+def trigger(ctx: click.Context, job_name: str, params: tuple[str, ...]):
+    """Trigger a new build for JOB_NAME.
+
+    Use --params/-p KEY=VAL to pass build parameters (repeat for multiple).
+    """
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        param_dict = _parse_params(params) if params else None
+        result = trigger_build(client, job_name, param_dict)
+        fmt.print_success(f"Build triggered for {job_name}")
+        fmt.print_json(result)
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("list")
+@click.argument("job_name")
+@click.option("--limit", "-n", default=10, type=int, help="Maximum builds to show.")
+@click.pass_context
+def list_builds(ctx: click.Context, job_name: str, limit: int):
+    """List recent builds for JOB_NAME."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        builds = get_builds(client, job_name, limit=limit)
+        if not builds:
+            fmt.print_info(f"No builds found for {job_name}")
+            return
+
+        headers = ["Number", "Result", "Timestamp", "Duration", "Building"]
+        rows = [
+            [
+                b.get("number", ""),
+                str(b.get("result") or "IN PROGRESS"),
+                str(b.get("timestamp", "")),
+                str(b.get("duration", "")),
+                str(b.get("building", False)),
+            ]
+            for b in builds
+        ]
+        fmt.print_table(headers, rows, title=f"Builds for {job_name}")
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("get")
+@click.argument("job_name")
+@click.argument("number", type=int)
+@click.pass_context
+def get_build_cmd(ctx: click.Context, job_name: str, number: int):
+    """Show details for a specific build."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        build = get_build(client, job_name, number)
+        fmt.print_json(build)
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("log")
+@click.argument("job_name")
+@click.argument("number", type=int)
+@click.pass_context
+def log_cmd(ctx: click.Context, job_name: str, number: int):
+    """Show console log for a build."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        log_text = get_build_log(client, job_name, number)
+        fmt.console.print(log_text)
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("stop")
+@click.argument("job_name")
+@click.argument("number", type=int)
+@click.pass_context
+def stop_cmd(ctx: click.Context, job_name: str, number: int):
+    """Stop a running build."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        stop_build(client, job_name, number)
+        fmt.print_success(f"Build {job_name}#{number} stopped")
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("queue")
+@click.pass_context
+def queue_cmd(ctx: click.Context):
+    """Show the current Jenkins build queue."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        items = get_queue(client)
+        if not items:
+            fmt.print_info("Build queue is empty")
+            return
+
+        headers = ["ID", "Task", "Why", "In Queue Since"]
+        rows = [
+            [
+                str(item.get("id", "")),
+                str(item.get("task", {}).get("name", "")),
+                str(item.get("why", "")),
+                str(item.get("inQueueSince", "")),
+            ]
+            for item in items
+        ]
+        fmt.print_table(headers, rows, title="Build Queue")
+    except JenkinsError as exc:
+        fmt.print_error(str(exc))
+        raise SystemExit(1)
+
+
+@build_group.command("artifacts")
+@click.argument("job_name")
+@click.argument("build_number")
+@click.pass_context
+def artifacts_cmd(ctx: click.Context, job_name: str, build_number: str):
+    """List artifacts for a build."""
+    client = get_client(ctx)
+    fmt = get_formatter(ctx)
+    try:
+        data = get_build_artifacts(client, job_name, build_number)
+        artifacts = data.get("artifacts", [])
+        if not artifacts:
+            fmt.print_info("No artifacts found.")
+            return
+        headers = ["File Name", "Relative Path"]
+        rows = [[a["fileName"], a["relativePath"]] for a in artifacts]
+        fmt.print_table(headers, rows, title=f"Artifacts: {job_name} #{build_number}")
+    except Exception as exc:
+        fmt.print_error(str(exc))
+
+
+def register(parent_group: click.Group):
+    """Register the build subgroup under the parent Click group."""
+    parent_group.add_command(build_group)

jcli/plugins/config.py

@@ -0,0 +1,268 @@
+"""Configuration management CLI commands for jcli."""
+
+import click
+
+from jcli.sdk.config import Config, ProfileNotFoundError
+from jcli.sdk.output.formatter import OutputFormatter
+
+
+def _get_config(ctx: click.Context) -> Config:
+    """Get or create Config from Click context."""
+    if "config" not in ctx.obj:
+        ctx.obj["config"] = Config().load()
+    return ctx.obj["config"]
+
+
+def _get_formatter(ctx: click.Context) -> OutputFormatter:
+    """Get or create OutputFormatter from Click context."""
+    if "formatter" not in ctx.obj:
+        fmt = ctx.obj.get("format", "table")
+        ctx.obj["formatter"] = OutputFormatter(fmt)
+    return ctx.obj["formatter"]
+
+
+@click.group()
+def config_group():
+    """Manage jcli configuration."""
+    pass
+
+
+@config_group.command("init")
+@click.option("--force", is_flag=True, help="Overwrite existing config file")
+@click.pass_context
+def config_init(ctx: click.Context, force: bool):
+    """Initialize configuration file with default template."""
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    if cfg.config_path.exists() and not force:
+        fmt.print_error(f"Config file already exists: {cfg.config_path}")
+        fmt.print_info("Use --force to overwrite")
+        return
+
+    # Create fresh config with template
+    cfg = Config()
+    cfg.load()
+    cfg.save()
+
+    fmt.print_success(f"Config file created: {cfg.config_path}")
+    fmt.print_info("Edit it with your Jenkins server details:")
+    fmt.print_info(f"  url: https://jenkins.example.com")
+    fmt.print_info(f"  username: admin")
+    fmt.print_info(f"  api_token: your-api-token-here")
+
+
+@config_group.command("show")
+@click.option("--profile", "-p", help="Show specific profile (default: active)")
+@click.pass_context
+def config_show(ctx: click.Context, profile: str | None):
+    """Show configuration details."""
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    if profile:
+        try:
+            data = cfg.get_profile(profile)
+        except ProfileNotFoundError:
+            fmt.print_error(f"Profile '{profile}' not found")
+            return
+        active_name = cfg.get_active_profile_name()
+        is_active = " (active)" if profile == active_name else ""
+        fmt.print_info(f"Profile: {profile}{is_active}")
+        _show_profile(fmt, data)
+    else:
+        active_name = cfg.get_active_profile_name()
+        fmt.print_info(f"Config file: {cfg.config_path}")
+        fmt.print_info(f"Active profile: {active_name}")
+        fmt.print_info("")
+        try:
+            data = cfg.get_active_profile()
+            _show_profile(fmt, data)
+        except ProfileNotFoundError:
+            fmt.print_error(f"Active profile '{active_name}' not found")
+
+
+def _show_profile(fmt: OutputFormatter, data: dict):
+    """Display profile fields."""
+    fields = [
+        ("url", "URL"),
+        ("username", "Username"),
+        ("api_token", "API Token"),
+        ("description", "Description"),
+    ]
+    for key, label in fields:
+        value = data.get(key, "")
+        # Mask token for display
+        if key == "api_token" and value and len(value) > 8:
+            display = value[:4] + "****" + value[-4:]
+        else:
+            display = value
+        fmt.print_info(f"  {label}: {display}")
+
+
+@config_group.command("list")
+@click.pass_context
+def config_list(ctx: click.Context):
+    """List all configured profiles."""
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    profiles = cfg.list_profiles()
+    active_name = cfg.get_active_profile_name()
+
+    if not profiles:
+        fmt.print_info("No profiles configured. Run 'jcli config init' to create one.")
+        return
+
+    headers = ["Name", "URL", "Username", "Active"]
+    rows = []
+    for name, data in profiles.items():
+        active_mark = "✓" if name == active_name else ""
+        rows.append([
+            name,
+            data.get("url", ""),
+            data.get("username", ""),
+            active_mark,
+        ])
+
+    fmt.print_table(headers, rows, title="Profiles")
+
+
+@config_group.command("set")
+@click.argument("profile")
+@click.argument("field", type=click.Choice(["url", "username", "api_token", "description"]))
+@click.argument("value")
+@click.pass_context
+def config_set(ctx: click.Context, profile: str, field: str, value: str):
+    """Set a configuration field for a profile.
+
+    Examples:
+        jcli config set dev url https://jenkins-dev.example.com
+        jcli config set dev username admin
+        jcli config set dev api_token abc123
+        jcli config set dev description "Development Jenkins"
+    """
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    try:
+        data = cfg.get_profile(profile)
+    except ProfileNotFoundError:
+        fmt.print_error(f"Profile '{profile}' not found")
+        fmt.print_info(f"Create it first with: jcli config add {profile}")
+        return
+
+    # Update the field
+    data[field] = value
+    cfg.add_profile(
+        name=profile,
+        url=data.get("url", ""),
+        username=data.get("username", ""),
+        api_token=data.get("api_token", ""),
+        description=data.get("description", ""),
+    )
+
+    fmt.print_success(f"Updated profile '{profile}': {field} = {value}")
+
+
+@config_group.command("add")
+@click.argument("profile")
+@click.option("--url", "-u", default="", help="Jenkins server URL")
+@click.option("--username", default="", help="Jenkins username")
+@click.option("--api-token", default="", help="Jenkins API token")
+@click.option("--description", "-d", default="", help="Profile description")
+@click.pass_context
+def config_add(
+    ctx: click.Context,
+    profile: str,
+    url: str,
+    username: str,
+    api_token: str,
+    description: str,
+):
+    """Add a new configuration profile.
+
+    Examples:
+        jcli config add dev --url https://jenkins-dev.example.com --username admin
+        jcli config add prod -u https://jenkins-prod.example.com -d "Production"
+    """
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    # Check if profile already exists
+    profiles = cfg.list_profiles()
+    if profile in profiles:
+        fmt.print_error(f"Profile '{profile}' already exists")
+        fmt.print_info(f"Use 'jcli config set {profile} <field> <value>' to update")
+        return
+
+    cfg.add_profile(
+        name=profile,
+        url=url or "https://jenkins.example.com",
+        username=username or "admin",
+        api_token=api_token or "",
+        description=description or f"{profile} Jenkins instance",
+    )
+
+    fmt.print_success(f"Profile '{profile}' added")
+    fmt.print_info("Configure it with:")
+    fmt.print_info(f"  jcli config set {profile} url https://your-jenkins.com")
+    fmt.print_info(f"  jcli config set {profile} api_token your-token")
+
+
+@config_group.command("delete")
+@click.argument("profile")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+def config_delete(ctx: click.Context, profile: str, yes: bool):
+    """Delete a configuration profile.
+
+    Examples:
+        jcli config delete dev
+        jcli config delete old-server --yes
+    """
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    profiles = cfg.list_profiles()
+    if profile not in profiles:
+        fmt.print_error(f"Profile '{profile}' not found")
+        return
+
+    if not yes:
+        if not click.confirm(f"Delete profile '{profile}'?"):
+            fmt.print_info("Cancelled")
+            return
+
+    cfg.remove_profile(profile)
+    fmt.print_success(f"Profile '{profile}' deleted")
+
+
+@config_group.command("use")
+@click.argument("profile")
+@click.pass_context
+def config_use(ctx: click.Context, profile: str):
+    """Switch active profile.
+
+    Examples:
+        jcli config use prod
+        jcli config use dev
+    """
+    cfg = _get_config(ctx)
+    fmt = _get_formatter(ctx)
+
+    try:
+        cfg.set_active_profile(profile)
+    except ProfileNotFoundError:
+        fmt.print_error(f"Profile '{profile}' not found")
+        profiles = cfg.list_profiles()
+        if profiles:
+            fmt.print_info(f"Available profiles: {', '.join(profiles.keys())}")
+        return
+
+    fmt.print_success(f"Active profile set to '{profile}'")
+
+
+def register(group: click.Group) -> None:
+    """Register config commands with the main CLI group."""
+    group.add_command(config_group, "config")