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

jcli/__init__.py

@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.0.1"

jcli/cli.py

@@ -48,21 +48,14 @@ SPEC_DIR_ENV = "JCLI_SPEC_DIR"
 
 
 def _default_spec_dir() -> Path:
-    """Locate the cliyard YAML spec directory.
+    """Locate the cliyard YAML spec directory (ships inside the package).
 
-    Priority: ``$JCLI_SPEC_DIR`` > package-local ``specs/`` > repo-root
-    ``specs/`` (editable/dev layout).
+    Priority: ``$JCLI_SPEC_DIR`` env var > package-local ``jcli/specs/``.
     """
     env = os.environ.get(SPEC_DIR_ENV)
     if env:
         return Path(env)
-    pkg_specs = Path(__file__).resolve().parent / "specs"
-    if pkg_specs.is_dir():
-        return pkg_specs
-    repo_specs = Path(__file__).resolve().parent.parent / "specs"
-    if repo_specs.is_dir():
-        return repo_specs
-    return pkg_specs
+    return Path(__file__).resolve().parent / "specs"
 
 
 def extract_profile_override(argv: list[str]) -> str | None:
@@ -213,6 +206,9 @@ def _make_format_injector(callback: Callable[..., Any]) -> Callable[..., Any]:
     ``Error:``/``错误:`` markers and re-emits them on stderr with a non-zero
     exit code.
 
+    Commands carrying a ``--follow`` flag (live log tailing) bypass the
+    stdout capture so the plugin can stream output in real time.
+
     Note: ``ctx.exit(1)`` (not ``return 1``) is required — Click >= 8.4
     ignores a plain integer return value from the top-level callback and
     always exits with ``ctx.exit_code`` (default 0).
@@ -231,6 +227,9 @@ def _make_format_injector(callback: Callable[..., Any]) -> Callable[..., Any]:
             if source in (None, ParameterSource.DEFAULT, ParameterSource.DEFAULT_MAP):
                 kwargs["format"] = global_format
 
+        if kwargs.get("follow"):
+            return callback(**kwargs)
+
         buffer = io.StringIO()
         real_stdout = sys.stdout
         sys.stdout = buffer
@@ -498,6 +497,26 @@ def _add_jcli_auth_commands(cli: click.Group) -> None:
     cli.add_command(auth)
 
 
+def _add_tail_short_options(cli: click.Group) -> None:
+    """Give ``build log`` tail-style short flags (``-f``/``-n``).
+
+    cliyard generates long-only options (``--follow``/``--lines``); add the
+    conventional ``tail`` short aliases on the ``build log`` command.
+    """
+    build = cli.commands.get("build")
+    if not isinstance(build, click.Group):
+        return
+    log = build.commands.get("log")
+    if not log:
+        return
+    for p in log.params:
+        if isinstance(p, click.Option):
+            if p.name == "follow" and "-f" not in p.opts:
+                p.opts = ("-f", "--follow")
+            elif p.name == "lines" and "-n" not in p.opts:
+                p.opts = ("-n", "--lines")
+
+
 def _build_cli(spec_dir: Path, server: str | None, profile: str | None) -> click.Group:
     """Create the cliyard CLI and apply the jcli wrapper layer."""
     base_url = resolve_base_url(server, profile)
@@ -509,6 +528,7 @@ def _build_cli(spec_dir: Path, server: str | None, profile: str | None) -> click
     wrap_subcommand_callbacks(cli)
     set_group_help(cli)
     _prune_non_jcli_commands(cli)
+    _add_tail_short_options(cli)
     return cli
 
 

jcli/cli_helpers.py

@@ -1,54 +1,17 @@
-"""Centralized CLI helpers for creating JenkinsClient and OutputFormatter.
+"""Centralized CLI helpers.
 
-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.
+v2 only needs the output-formatter helper (used by the cliyard command
+plugins, e.g. ``jcli/specs/plugins/jcli_commands.py``).  The v1 ``get_client``
+helper was removed together with the legacy hand-written command modules
+(``jcli/plugins/``).
 """
 
 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."""

jcli/skills/jcli/build/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: jcli-build
+version: 1.0.0
+description: |
+  jcli 构建管理 - 管理 Jenkins 构建的触发、查看、停止等操作。
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# jcli-build
+
+管理 Jenkins 构建的触发、查看、停止等操作。
+
+## 前提条件
+
+- Python >= 3.10
+- Jenkins 2.x 或更高版本
+- 已安装 jcli：`pip install -e /data/git-project/jcli`
+
+## 命令参考
+
+```bash
+jcli build list <job>                      # 列出构建历史
+jcli build list <job> --limit 20           # 列出最近 20 次构建
+jcli build get <job> <number>              # 查看构建详情
+jcli build log <job> <number>              # 查看完整控制台日志
+jcli build log <job> <number> -n 50        # 只显示末尾 50 行（tail -n）
+jcli build log <job> <number> -f           # 实时跟随（tail -f）：先打印全部历史，再滚动新增，构建结束自动退出
+jcli build log <job> <number> -f -n 50     # 显示末尾 50 行后实时跟随
+jcli build artifacts <job> <number>        # 查看构建产物
+jcli build trigger <job>                   # 触发构建
+jcli build trigger <job> --params BRANCH=main  # 带参数触发构建
+jcli build trigger <job> --params KEY1=VAL1 --params KEY2=VAL2  # 多个参数
+jcli build rebuild <job> <number>          # 重建（复用上次构建参数）
+jcli build rebuild <job> <number> --set KEY=VAL  # 重建并覆盖参数（可重复）
+jcli build replay <job> <number> <jenkinsfile>  # 回放（使用修改后的 Jenkinsfile）
+jcli build stop <job> <number>             # 停止构建
+jcli build queue                           # 查看构建队列
+```
+
+## 常见用例
+
+### 查看构建失败原因
+
+```bash
+# 1. 查看最近构建
+jcli build list my-job
+
+# 2. 查看失败构建的日志
+jcli build log my-job 42
+```
+
+### 批量触发构建
+
+```bash
+for job in job1 job2 job3; do
+  jcli build trigger $job
+done
+```
+
+### 监控构建状态
+
+```bash
+# 查看队列
+jcli build queue
+
+# 实时查看最新构建状态
+watch -n 5 "jcli build list my-job --limit 1"
+
+# 实时跟随构建日志（-f，构建结束自动退出）
+jcli build log my-job 42 -f
+```
+
+### 带参数触发构建
+
+```bash
+# 单个参数
+jcli build trigger my-job --params BRANCH=develop
+
+# 多个参数
+jcli build trigger my-job --params BRANCH=develop --params DEPLOY=true --params ENV=staging
+```
+
+### 实时查看构建日志（tail 风格）
+
+`jcli build log` 沿用 `tail` 命令的参数语义：
+
+| 命令 | 效果 |
+|------|------|
+| `jcli build log <job> <n>` | 输出完整日志 |
+| `jcli build log <job> <n> -n 50` | 只显示末尾 50 行 |
+| `jcli build log <job> <n> -f` | 实时跟随：先输出全部历史，再滚动显示新日志 |
+| `jcli build log <job> <n> -f -n 50` | 先看末尾 50 行，再实时跟随 |
+
+- `-f` / `--follow`：实时输出，新日志逐行滚动（tail -f）
+- `-n N` / `--lines N`：只显示末尾 N 行，默认全部
+- 跟随模式在**构建结束后自动退出**，也可随时 `Ctrl+C` 中断
+
+```bash
+# 构建失败排查：看末尾日志定位错误
+jcli build log my-job 42 -n 100
+
+# 实时观察正在构建的日志
+jcli build log my-job 42 -f
+
+# 触发构建后直接跟随
+jcli build trigger my-job
+jcli build log my-job 43 -f
+```
+
+### 重建与回放
+
+```bash
+# 重建：复用上次构建的参数
+jcli build rebuild my-job 42
+
+# 重建并覆盖部分参数（--set 可重复）
+jcli build rebuild my-job 42 --set DEPLOY=false
+
+# 回放：使用修改后的 Jenkinsfile 文件重新运行 Pipeline
+jcli build replay my-job 42 Jenkinsfile
+```

jcli/specs/_auth.yaml

@@ -0,0 +1,15 @@
+name: jcli
+version: "1.0.1"
+description: Jenkins CLI tool
+output:
+  default: table
+server:
+  base_url: http://localhost:8090
+auth:
+  steps:
+    - name: basic
+      type: plugin:jenkins_basic
+      config: {}
+    - name: crumb
+      type: plugin:jenkins_crumb
+      config: {}

jcli/{plugins/skills.py → specs/plugins/jcli_commands.py}

@@ -1,4 +1,14 @@
-"""Jcli skills management commands."""
+"""Top-level command plugins for jcli 2.0: skills, completion.
+
+Migrated verbatim from jcli v1:
+
+* ``skills``  — jcli/plugins/skills.py
+* ``completion`` — jcli/cli.py ``add_completion_command``
+
+Each group is registered as a cliyard command plugin
+(``@register_command``), so ``create_cli`` attaches it to the top-level
+Click group.  Command semantics and output formats are unchanged from v1.
+"""
 
 from __future__ import annotations
 
@@ -8,14 +18,20 @@ from typing import Any
 
 import click
 
+from cliyard.plugin import register_command
+
 from jcli.cli_helpers import get_formatter
 
-# ------------------------------------------------------------------
-# Constants
-# ------------------------------------------------------------------
 
-# Bundled skills directory (ships with jcli package)
-BUNDLED_SKILLS_DIR = Path(__file__).parent.parent / "skills" / "jcli"
+# =====================================================================
+# Skills commands (verbatim from jcli/plugins/skills.py)
+# =====================================================================
+
+# Bundled skills directory (ships with jcli package):
+# <repo-root>/jcli/skills/jcli/*  — this plugin lives in <repo-root>/jcli/specs/plugins/
+BUNDLED_SKILLS_DIR = (
+    Path(__file__).resolve().parent.parent.parent.parent / "jcli" / "skills" / "jcli"
+)
 
 # Default install directory for opencode
 DEFAULT_INSTALL_DIR = Path.home() / ".config" / "opencode" / "skills"
@@ -24,11 +40,6 @@ DEFAULT_INSTALL_DIR = Path.home() / ".config" / "opencode" / "skills"
 FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
 
 
-# ------------------------------------------------------------------
-# Helpers
-# ------------------------------------------------------------------
-
-
 def parse_skill_metadata(skill_dir: Path) -> dict[str, Any]:
     """Parse SKILL.md frontmatter to extract metadata.
 
@@ -231,27 +242,17 @@ def uninstall_skill(name: str, install_dir: Path | None = None) -> bool:
     return True
 
 
-# ------------------------------------------------------------------
-# Click group
-# ------------------------------------------------------------------
-
-
 @click.group("skills", help="Manage jcli skills (list, install, uninstall).")
 def skills_group() -> None:
     """Skills management commands."""
 
 
-# ------------------------------------------------------------------
-# list
-# ------------------------------------------------------------------
-
-
 @skills_group.command("list")
 @click.option("--installed", "-i", is_flag=True, help="Show only installed skills.")
 @click.option("--bundled", "-b", is_flag=True, help="Show only bundled skills.")
 @click.option("--dir", "install_dir", type=click.Path(exists=False), help="Custom install directory.")
 @click.pass_context
-def list_cmd(ctx: click.Context, installed: bool, bundled: bool, install_dir: str | None) -> None:
+def skills_list_cmd(ctx: click.Context, installed: bool, bundled: bool, install_dir: str | None) -> None:
     """List all available skills."""
     fmt = get_formatter(ctx)
     target_dir = Path(install_dir) if install_dir else DEFAULT_INSTALL_DIR
@@ -297,18 +298,13 @@ def list_cmd(ctx: click.Context, installed: bool, bundled: bool, install_dir: st
     fmt.print_table(headers, rows, title="Jcli Skills")
 
 
-# ------------------------------------------------------------------
-# install
-# ------------------------------------------------------------------
-
-
 @skills_group.command("install")
 @click.argument("name", required=False)
 @click.option("--all", "-a", "install_all", is_flag=True, help="Install all bundled skills.")
 @click.option("--force", "-f", is_flag=True, help="Force install (overwrite existing).")
 @click.option("--dir", "install_dir", type=click.Path(exists=False), help="Custom install directory.")
 @click.pass_context
-def install_cmd(ctx: click.Context, name: str | None, install_all: bool, force: bool, install_dir: str | None) -> None:
+def skills_install_cmd(ctx: click.Context, name: str | None, install_all: bool, force: bool, install_dir: str | None) -> None:
     """Install a skill.
 
     NAME is the skill name to install (from bundled skills).
@@ -354,16 +350,11 @@ def install_cmd(ctx: click.Context, name: str | None, install_all: bool, force:
     fmt.print_success(f"Skill '{name}' installed to {target_dir / name}")
 
 
-# ------------------------------------------------------------------
-# uninstall
-# ------------------------------------------------------------------
-
-
 @skills_group.command("uninstall")
 @click.argument("name")
 @click.option("--dir", "install_dir", type=click.Path(exists=False), help="Custom install directory.")
 @click.pass_context
-def uninstall_cmd(ctx: click.Context, name: str, install_dir: str | None) -> None:
+def skills_uninstall_cmd(ctx: click.Context, name: str, install_dir: str | None) -> None:
     """Uninstall a skill.
 
     NAME is the skill name to uninstall.
@@ -382,17 +373,12 @@ def uninstall_cmd(ctx: click.Context, name: str, install_dir: str | None) -> Non
     fmt.print_success(f"Skill '{name}' uninstalled from {target_dir}")
 
 
-# ------------------------------------------------------------------
-# get
-# ------------------------------------------------------------------
-
-
 @skills_group.command("get")
 @click.argument("name")
 @click.option("--installed", "-i", is_flag=True, help="Get from installed skills.")
 @click.option("--dir", "install_dir", type=click.Path(exists=False), help="Custom install directory.")
 @click.pass_context
-def get_cmd(ctx: click.Context, name: str, installed: bool, install_dir: str | None) -> None:
+def skills_get_cmd(ctx: click.Context, name: str, installed: bool, install_dir: str | None) -> None:
     """Show skill details and SKILL.md content."""
     fmt = get_formatter(ctx)
     target_dir = Path(install_dir) if install_dir else DEFAULT_INSTALL_DIR
@@ -432,11 +418,43 @@ def get_cmd(ctx: click.Context, name: str, installed: bool, install_dir: str | N
     fmt.console.print(content)
 
 
-# ------------------------------------------------------------------
-# Registration
-# ------------------------------------------------------------------
+# =====================================================================
+# Completion command (verbatim from jcli/cli.py add_completion_command)
+# =====================================================================
+
+
+def build_completion_group(cli: click.Group) -> click.Group:
+    """Build the ``completion show`` group attached to *cli*."""
+    from click.shell_completion import BashComplete, FishComplete, ZshComplete
+
+    @click.group()
+    def completion() -> None:
+        """Shell completion support for jcli."""
+
+    @completion.command()
+    @click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+    def show(shell: str) -> None:
+        """Output shell completion script for the specified shell."""
+        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)
+    return completion
+
+
+# =====================================================================
+# cliyard command plugin registration
+# =====================================================================
+
+
+@register_command("skills")
+def _register_skills(cli: click.Group, ctx: Any) -> None:
+    """Attach the skills command group to the top-level CLI."""
+    cli.add_command(skills_group)
 
 
-def register(parent_group: click.Group) -> None:
-    """Register the skills subgroup under the parent Click group."""
-    parent_group.add_command(skills_group)
+@register_command("completion")
+def _register_completion(cli: click.Group, ctx: Any) -> None:
+    """Attach the completion command group to the top-level CLI."""
+    build_completion_group(cli)

jcli/specs/plugins/jenkins_auth.py

@@ -0,0 +1,75 @@
+"""Jenkins auth steps: Basic Auth + Crumb (CSRF)."""
+import base64
+import os
+
+import requests
+
+from cliyard.plugin import register_auth_step
+
+
+def _config_path() -> str:
+    """Resolve the jcli config file path at call time.
+
+    Prefers ``jcli.sdk.config.DEFAULT_CONFIG_FILE`` (so tests can point it
+    elsewhere via monkeypatch) and falls back to ``~/.jcli/config.yaml``
+    when the SDK is not importable.
+    """
+    try:
+        from jcli.sdk.config import DEFAULT_CONFIG_FILE
+
+        return str(DEFAULT_CONFIG_FILE)
+    except Exception:
+        return os.path.expanduser("~/.jcli/config.yaml")
+
+
+def _load_profile():
+    import yaml
+    config_path = _config_path()
+    if not os.path.exists(config_path):
+        raise RuntimeError(f"config not found: {config_path}")
+    with open(config_path, "r", encoding="utf-8") as f:
+        cfg = yaml.safe_load(f) or {}
+    name = os.environ.get("JCLI_PROFILE") or cfg.get("active_profile", "default")
+    profile = dict(cfg.get("profiles", {}).get(name, {}))
+    for env_key, field in (("JCLI_URL", "url"), ("JCLI_USERNAME", "username"), ("JCLI_API_TOKEN", "api_token")):
+        if os.environ.get(env_key):
+            profile[field] = os.environ[env_key]
+    return profile
+
+
+@register_auth_step("jenkins_basic")
+class JenkinsBasicAuth:
+    """Set Basic Auth header from ~/.jcli/config.yaml profile."""
+
+    def execute(self, auth_state, config, http_client):
+        profile = _load_profile()
+        username = profile.get("username", "")
+        token = profile.get("api_token", "")
+        if not username or not token:
+            raise RuntimeError("missing username/api_token in profile")
+        raw = f"{username}:{token}".encode()
+        http_client.default_headers["Authorization"] = "Basic " + base64.b64encode(raw).decode()
+        auth_state["username"] = username
+        return {"username": username}
+
+
+@register_auth_step("jenkins_crumb")
+class JenkinsCrumb:
+    """Fetch Jenkins crumb and inject as header. Tolerate 404 (CSRF disabled)."""
+
+    def execute(self, auth_state, config, http_client):
+        url = f"{http_client.base_url}/crumbIssuer/api/json"
+        try:
+            resp = http_client._session.get(url, headers=http_client.default_headers, timeout=10)
+        except requests.RequestException:
+            return {}
+        if resp.status_code == 404:
+            return {}  # CSRF disabled
+        if resp.status_code != 200:
+            raise RuntimeError(f"crumb fetch failed: {resp.status_code}")
+        data = resp.json()
+        field = data.get("crumbRequestField")
+        value = data.get("crumb")
+        if field and value:
+            http_client.default_headers[field] = value
+        return {"crumb": value}