py-wlcli 0.8.0__py3-none-any.whl

wl_cli/env_status.py

@@ -0,0 +1,157 @@
+"""Shared payload builder for the ``wl env check`` probe (issue #221).
+
+``wl env check`` (the ``wl_cli.env`` domain) and the deprecated
+``wl self capabilities`` alias (``wl_cli.commands``) must answer with the same
+five-state envelope. The quality domain may not import the env domain (#220),
+so the builder lives here in the shared layer and both commands call it.
+
+The probe reports **the wl that is running**: its version, its interpreter and
+the shared platform matrix from :func:`wl_cli.platform.platform_payload`
+(wlcc #321). It does not look up another ``wl`` on ``PATH`` and it writes
+nothing. The probe runs with a throwaway temporary directory as its CWD, so a
+future probe cannot create or rewrite ``.wl/`` in the caller's directory; the
+startup self-sync is independently skipped by the dispatcher for read-only
+commands (#220).
+
+Envelope contract: ``status`` is ``ok`` for a supported interpreter,
+``unverifiable`` when the platform matrix rejects it (unreachable for an
+installed wl -- the wheel requires Python 3.11+), and ``error`` only when the
+payload itself cannot be built. The envelope's ``reason`` is the platform
+reason when unsupported; the matrix's own ``reason`` is always carried as
+``platform_reason``, so the two keys never collide.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+import tempfile
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from . import __version__
+from .capabilities import CAPABILITY_SINCE, capability_names, capability_since
+from .envelope import OK_STATUSES, dump, exit_code
+from .platform import platform_payload
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+#: Stable tool name in the envelope's ``tool`` key (the alias reuses it: both
+#: commands answer the same question, so consumers key off one name).
+TOOL = "env check"
+
+#: Minimum release the repair hint and ``wl env repair`` install. Derived from
+#: the shared capability registry -- ``env.check`` first ships in the release
+#: the repair should install -- so the floor is not a second version literal
+#: that can drift from the registry (#227). ``VERSION`` itself is bumped by the
+#: release process, not by this change.
+INSTALL_FLOOR = CAPABILITY_SINCE["env.check"]
+
+#: The repair command as argv -- executed literally, with no shell (so the
+#: ``>=`` spec can never be reinterpreted as a redirection) and no ``--force``
+#: (uv treats an identical install as a no-op, which is what makes repair
+#: idempotent).
+INSTALL_ARGV: tuple[str, ...] = (
+    "uv",
+    "tool",
+    "install",
+    "--python",
+    "3.12",
+    f"py-wlcli>={INSTALL_FLOOR}",
+)
+
+#: Human-readable form derived from the argv, so the printed command and the
+#: executed argv cannot drift apart (wlcc #266: printed == executed).
+INSTALL_COMMAND = shlex.join(INSTALL_ARGV)
+
+
+@contextmanager
+def _isolated_cwd() -> Generator[None, None, None]:
+    """Run the read-only probe with a throwaway directory as the CWD.
+
+    ``wl env check`` must not create or rewrite ``.wl/`` in the caller's
+    directory. Running the probe in a temporary CWD keeps that guarantee even
+    if a future probe grows a relative write; the previous CWD is restored on
+    every exit path.
+    """
+    previous = os.getcwd()
+    with tempfile.TemporaryDirectory(prefix="wl-env-check-") as tmp:
+        os.chdir(tmp)
+        try:
+            yield
+        finally:
+            os.chdir(previous)
+
+
+def executable_path() -> str:
+    """Return the interpreter running this wl (diagnostic; #221 ruling 2).
+
+    ``sys.executable`` is empty for some embedded interpreters, so fall back to
+    the invocation path. Resolve before any CWD change so a relative
+    ``sys.argv[0]`` keeps its original meaning.
+    """
+    candidate = sys.executable or (sys.argv[0] if sys.argv else "")
+    return os.path.abspath(candidate) if candidate else "unknown"
+
+
+def install_fields() -> dict[str, str]:
+    """Return the ``install`` payload: the actual command and its floor."""
+    return {"command": INSTALL_COMMAND, "floor": INSTALL_FLOOR}
+
+
+def build_payload() -> tuple[str, str | None, dict[str, Any]]:
+    """Build the ``wl env check`` fields.
+
+    Returns:
+        ``(status, reason, fields)``. ``status`` is ``ok`` when the running
+        interpreter is supported, ``unverifiable`` when the shared platform
+        matrix says otherwise, and ``error`` only when the payload cannot be
+        built at all. ``reason`` carries the readable platform reason when the
+        status is not ``ok``; ``fields`` is the envelope payload.
+    """
+    executable = executable_path()
+    try:
+        with _isolated_cwd():
+            platform_payload_fields = platform_payload()
+        # Consume the shared payload read-only: pop ``reason`` from a copy, so a
+        # future platform_payload that caches and returns one dict cannot lose
+        # the key on the next build (#227).
+        platform_fields = dict(platform_payload_fields)
+        raw_reason = platform_fields.pop("reason")
+        platform_reason = raw_reason if isinstance(raw_reason, str) else None
+        fields: dict[str, Any] = {
+            "version": __version__,
+            "executable": executable,
+            **platform_fields,
+            "platform_reason": platform_reason,
+            "capabilities": capability_names(),
+            "capability_since": capability_since(),
+            "install": install_fields(),
+        }
+    except Exception as exc:  # noqa: BLE001 - the envelope is the error report
+        return (
+            "error",
+            f"could not probe the environment: {exc}",
+            {
+                "version": __version__,
+                "executable": executable,
+                "install": install_fields(),
+            },
+        )
+
+    if fields["supported"] is True:
+        return "ok", None, fields
+    return "unverifiable", platform_reason or "unsupported platform", fields
+
+
+def emit_check() -> int:
+    """Write the ``env check`` envelope to stdout and return its exit code.
+
+    Both ``wl env check --json`` and the deprecated ``wl self capabilities
+    --json`` alias call this, so the two commands cannot answer differently.
+    """
+    status, reason, fields = build_payload()
+    dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **fields)
+    return exit_code(status)

wl_cli/envelope.py

@@ -0,0 +1,91 @@
+"""Shared five-state JSON envelope for the domain commands (issue #220).
+
+Every ``wl`` domain command that answers a machine-readable question
+(``wl env check``, ``wl cc repair``, ...) reports through this one envelope,
+so consumers learn the contract once instead of per tool. The line on stdout
+is exactly:
+
+    {"tool": "<tool>", "ok": <bool>, "status": "<one of five>", "reason": null, ...payload}
+
+The five states and their exit codes are defined **only** here:
+
+    ok            probe holds, nothing pending                        -> rc 0
+    dangling      probe holds, dangling entries remain (not fixed)    -> rc 0
+    repaired      probe holds, changes were written                   -> rc 0
+    unverifiable  probe does not hold, but reported explicitly        -> rc 1
+    error         the tool itself failed (bad JSON, write, args)      -> rc 1
+
+``ok`` is the boolean reduction of ``status`` (``ok == status in OK_STATUSES``);
+the conclusion lives in the JSON, never in the exit code alone. stdout is
+always exactly one JSON line; diagnostics go to stderr.
+
+Mirrors ``scripts/probe_json.py`` in the wlcc repo (the contract oracle)
+exactly: ``exit_code`` maps every status outside :data:`OK_STATUSES` — known
+or unknown — to rc 1, while :func:`dump` rejects unknown statuses so an
+unknown state can never be emitted.
+"""
+
+import json
+import sys
+from typing import Any
+
+STATUSES = ("ok", "dangling", "repaired", "unverifiable", "error")
+OK_STATUSES = ("ok", "dangling", "repaired")
+
+EXIT_ESTABLISHED = 0
+EXIT_NOT_ESTABLISHED = 1
+
+
+def exit_code(status: str) -> int:
+    """Map a five-state status to an exit code.
+
+    Args:
+        status: One of :data:`STATUSES`.
+
+    Returns:
+        ``0`` when the probe is established (``ok``/``dangling``/``repaired``),
+        ``1`` otherwise — including unknown statuses, matching the wlcc oracle.
+        Emitting an unknown status is still impossible because :func:`dump`
+        rejects it.
+    """
+    return EXIT_ESTABLISHED if status in OK_STATUSES else EXIT_NOT_ESTABLISHED
+
+
+def dump(
+    status: str,
+    ok: bool,
+    *,
+    tool: str,
+    reason: str | None = None,
+    **fields: Any,
+) -> None:
+    """Write one envelope line to stdout as machine-readable JSON.
+
+    ``tool``, ``ok``, ``status`` and ``reason`` are the four fixed top-level
+    keys (in that order); ``fields`` carries the tool-specific payload after
+    them. ``ok`` must agree with ``status`` — disagreement raises immediately
+    rather than emitting two contradictory conclusions.
+
+    Args:
+        status: One of :data:`STATUSES`.
+        ok: Boolean reduction of ``status`` (``status in OK_STATUSES``).
+        tool: Stable tool name reported in the envelope.
+        reason: Human-readable explanation, or ``None``.
+        **fields: Tool-specific payload appended after the fixed keys.
+
+    Raises:
+        ValueError: If ``status`` is unknown or ``ok`` contradicts it.
+    """
+    if status not in STATUSES:
+        raise ValueError(f"未知 status: {status!r}（应 ∈ {', '.join(STATUSES)}）")
+    if ok != (status in OK_STATUSES):
+        raise ValueError(f"ok={ok!r} 与 status={status!r} 不自洽")
+
+    payload: dict[str, Any] = {
+        "tool": tool,
+        "ok": ok,
+        "status": status,
+        "reason": reason,
+    }
+    payload.update(fields)
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")

wl_cli/exceptions.py

@@ -0,0 +1,85 @@
+"""
+Custom exceptions for WL Commands.
+"""
+
+
+class ErrorCode:
+    """Standard error codes."""
+
+    SUCCESS = 0
+    COMMAND_NOT_FOUND = 1
+    COMMAND_EXECUTION_FAILED = 2
+    INVALID_ARGUMENT = 3
+    MISSING_DEPENDENCY = 4
+    MAKE_NOT_FOUND = 5
+    UV_NOT_FOUND = 6
+
+
+class CommandError(Exception):
+    """Base exception for command failures."""
+
+    def __init__(
+        self, message: str, error_code: int = ErrorCode.COMMAND_EXECUTION_FAILED
+    ) -> None:
+        """
+        Initialize command error.
+
+        Args:
+            message (str): Error message.
+            error_code (int): Error code.
+        """
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class MakeNotFoundError(CommandError):
+    """Raised when 'make' command is not found."""
+
+    def __init__(self, message: str = "Make command not found") -> None:
+        super().__init__(message, ErrorCode.MAKE_NOT_FOUND)
+
+
+class UVNotFoundError(CommandError):
+    """Raised when 'uv' command is not found."""
+
+    def __init__(self, message: str = "UV command not found") -> None:
+        super().__init__(message, ErrorCode.UV_NOT_FOUND)
+
+
+class ConfigError(CommandError):
+    """Raised when configuration errors occur."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, ErrorCode.INVALID_ARGUMENT)
+
+
+class FileOperationError(CommandError):
+    """Raised when file operation errors occur."""
+
+    def __init__(self, message: str, path: str | None = None) -> None:
+        super().__init__(message, ErrorCode.COMMAND_EXECUTION_FAILED)
+        self.path = path
+
+
+class GitError(CommandError):
+    """Raised when Git operation errors occur."""
+
+    def __init__(self, message: str, command: str | None = None) -> None:
+        super().__init__(message, ErrorCode.COMMAND_EXECUTION_FAILED)
+        self.command = command
+
+
+class NetworkError(CommandError):
+    """Raised when network operation errors occur."""
+
+    def __init__(self, message: str, url: str | None = None) -> None:
+        super().__init__(message, ErrorCode.COMMAND_EXECUTION_FAILED)
+        self.url = url
+
+
+class ValidationError(CommandError):
+    """Raised when validation errors occur."""
+
+    def __init__(self, message: str, field: str | None = None) -> None:
+        super().__init__(message, ErrorCode.INVALID_ARGUMENT)
+        self.field = field

wl_cli/lib/__init__.py

@@ -0,0 +1,3 @@
+from .rust_utils import HAS_RUST_EXTENSION, sum_as_string
+
+__all__ = ["sum_as_string", "HAS_RUST_EXTENSION"]

wl_cli/lib/rust_utils.py

@@ -0,0 +1,35 @@
+# 尝试导入 Rust 扩展，如果失败则使用 Python 实现
+import os
+import sys
+from typing import cast
+
+try:
+    # 使用当前文件所在目录动态构建 Rust 扩展路径
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, current_dir)
+
+    # 导入 Rust 扩展
+    from wl_cli_native import sum_as_string as rust_sum_as_string
+
+    HAS_RUST_EXTENSION = True
+except ImportError:
+    HAS_RUST_EXTENSION = False
+
+
+def sum_as_string(a: int, b: int) -> str:
+    """
+    计算两个整数的和并返回字符串表示。
+    优先使用 Rust 扩展实现，不可用时回落至 Python 实现。
+
+    Args:
+        a: 第一个整数
+        b: 第二个整数
+
+    Returns:
+        两个整数和的字符串表示
+    """
+    if HAS_RUST_EXTENSION:
+        return cast("str", rust_sum_as_string(a, b))
+    else:
+        # Python 实现作为回落
+        return str(a + b)

wl_cli/mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Model Context Protocol server domain."""
+
+from .capabilities import CAPABILITIES
+from .cli import mcp_group
+
+__all__ = ["CAPABILITIES", "mcp_group"]

wl_cli/mcp/capabilities.py

@@ -0,0 +1,19 @@
+"""MCP capabilities owned by this domain (issue #224).
+
+Since #221 the shared registry :mod:`wl_cli.capabilities` is the single source
+of truth for every capability name. This module keeps the domain-local view
+that #224 introduced -- ``mcp.*`` entries only, derived from the shared
+mapping -- so domain code and tests keep importing the same ``CAPABILITIES``
+dict without keeping a second copy of the data.
+"""
+
+from __future__ import annotations
+
+from ..capabilities import CAPABILITY_SINCE
+
+#: Capability name -> the first wl release that provides it (domain subset).
+CAPABILITIES: dict[str, str] = {
+    name: since for name, since in CAPABILITY_SINCE.items() if name.startswith("mcp.")
+}
+
+__all__ = ["CAPABILITIES"]

wl_cli/mcp/cli.py

@@ -0,0 +1,22 @@
+"""Click commands for the ``mcp`` domain."""
+
+import click
+
+
+@click.group(
+    name="mcp",
+    help="Model Context Protocol server commands.",
+)
+def mcp_group() -> None:
+    """MCP domain entry point."""
+
+
+@mcp_group.command("serve")
+@click.argument("server", type=click.Choice(("gitlab", "k8s")))
+def serve_command(server: str) -> None:
+    """Serve a registered MCP server over stdin/stdout."""
+    if server == "gitlab":
+        from .gitlab import serve
+    else:
+        from .k8s import serve
+    serve()