py-wlcli 0.8.0__py3-none-any.whl

wl_cli/mcp/k8s.py

@@ -0,0 +1,344 @@
+"""Read-only Kubernetes diagnostics MCP tools over SSH."""
+
+import os
+import subprocess
+
+from .protocol import serve as serve_protocol
+
+SSH_HOST = os.environ.get("K8S_SSH_HOST", "ubuntu-server")
+KUBECONFIG = "/etc/rancher/k3s/k3s.yaml"
+DEFAULT_NS = os.environ.get("K8S_DEFAULT_NS", "")
+SERVER_NAME = "k8s-diagnose"
+
+
+def _resolve_ns(namespace: str) -> str:
+    """Fall back to K8S_DEFAULT_NS when no namespace is supplied."""
+    return namespace or DEFAULT_NS
+
+
+def _kubectl(kubectl_args: list[str], timeout: int = 60) -> str:
+    """Run a read-only kubectl command on the K3s host over SSH."""
+    full_cmd = [
+        "ssh",
+        SSH_HOST,
+        "--",
+        "sudo",
+        f"KUBECONFIG={KUBECONFIG}",
+        "kubectl",
+    ] + kubectl_args
+    display = " ".join(full_cmd)
+    try:
+        result = subprocess.run(
+            full_cmd, capture_output=True, text=True, timeout=timeout
+        )
+        if result.returncode == 0:
+            return result.stdout
+        err = (result.stderr or result.stdout).strip()
+        if result.returncode == 255:
+            return (
+                f"Error: SSH to {SSH_HOST} failed (exit 255): {err}\nCommand: {display}"
+            )
+        return f"Error: kubectl exit {result.returncode}: {err}\nCommand: {display}"
+    except subprocess.TimeoutExpired:
+        return f"Error: command timed out after {timeout}s: {display}"
+    except FileNotFoundError as exc:
+        return f"Error: ssh/kubectl not found ({exc}) — check SSH host '{SSH_HOST}': {display}"
+    except Exception as exc:
+        return f"Error: failed to run command ({exc}): {display}"
+
+
+def k8s_get(
+    resource: str, name: str = "", namespace: str = "", output: str = ""
+) -> str:
+    """List Kubernetes resources with kubectl get."""
+    namespace = _resolve_ns(namespace)
+    args = ["get", resource]
+    if name:
+        args.append(name)
+    if namespace:
+        args += ["-n", namespace]
+    elif not name:
+        args.append("-A")
+    if output:
+        args += ["-o", output]
+    return _kubectl(args)
+
+
+def k8s_describe(resource: str, name: str = "", namespace: str = "") -> str:
+    """Describe a Kubernetes resource."""
+    namespace = _resolve_ns(namespace)
+    args = ["describe", resource]
+    if name:
+        args.append(name)
+    if namespace:
+        args += ["-n", namespace]
+    return _kubectl(args)
+
+
+def k8s_logs(
+    pod: str,
+    namespace: str = "",
+    tail: int = 50,
+    container: str = "",
+    since: str = "",
+    previous: bool = False,
+    all_containers: bool = False,
+    timeout: int = 60,
+) -> str:
+    """Get logs from a pod."""
+    namespace = _resolve_ns(namespace)
+    args = ["logs", pod]
+    if namespace:
+        args += ["-n", namespace]
+    if tail > 0:
+        args += ["--tail", str(tail)]
+    if container:
+        args += ["-c", container]
+    if since:
+        args += ["--since", since]
+    if previous:
+        args += ["--previous"]
+    if all_containers:
+        args += ["--all-containers"]
+    return _kubectl(args, timeout=timeout)
+
+
+def k8s_top(resource_type: str, namespace: str = "") -> str:
+    """Show CPU and memory usage."""
+    namespace = _resolve_ns(namespace)
+    args = ["top", resource_type]
+    if namespace and resource_type == "pod":
+        args += ["-n", namespace]
+    return _kubectl(args)
+
+
+def k8s_cluster_info() -> str:
+    """Show cluster endpoints and services."""
+    return _kubectl(["cluster-info"])
+
+
+def k8s_api_resources() -> str:
+    """List available API resources."""
+    return _kubectl(["api-resources"])
+
+
+def k8s_explain(resource: str) -> str:
+    """Show documentation for a Kubernetes resource."""
+    return _kubectl(["explain", resource])
+
+
+def k8s_version() -> str:
+    """Show client and server Kubernetes versions."""
+    return _kubectl(["version"])
+
+
+def k8s_events(namespace: str = "", field_selector: str = "", output: str = "") -> str:
+    """List Kubernetes events."""
+    namespace = _resolve_ns(namespace)
+    args = ["get", "events"]
+    if namespace:
+        args += ["-n", namespace]
+    else:
+        args.append("-A")
+    if field_selector:
+        args += ["--field-selector", field_selector]
+    if output:
+        args += ["-o", output]
+    return _kubectl(args)
+
+
+_ALLOWED_ROLLOUT = ("status", "history")
+
+
+def k8s_rollout(action: str, resource: str, name: str, namespace: str = "") -> str:
+    """Show rollout status or history for a workload."""
+    if action not in _ALLOWED_ROLLOUT:
+        return f"Error: rollout action must be one of {_ALLOWED_ROLLOUT} (read-only)"
+    namespace = _resolve_ns(namespace)
+    args = ["rollout", action, f"{resource}/{name}"]
+    if namespace:
+        args += ["-n", namespace]
+    return _kubectl(args)
+
+
+TOOLS: dict[str, dict] = {
+    "k8s_get": {
+        "fn": k8s_get,
+        "desc": "Get Kubernetes resources (pods, deployments, services, nodes, events, etc.). Read-only — only `get` is executed. Use when you need a resource list or its current state.",
+        "params": {
+            "resource": {
+                "type": "str",
+                "required": True,
+                "desc": "resource type (e.g. pods, deployments, svc, nodes, events, ingress)",
+            },
+            "name": {
+                "type": "str",
+                "required": False,
+                "desc": "specific resource name",
+            },
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "Kubernetes namespace (all namespaces when omitted)",
+            },
+            "output": {
+                "type": "str",
+                "required": False,
+                "desc": "output format: wide, yaml, json, name",
+            },
+        },
+    },
+    "k8s_describe": {
+        "fn": k8s_describe,
+        "desc": "Describe a Kubernetes resource in detail. Read-only — only `describe` is executed. Use when `get` isn't enough — events, conditions, container status.",
+        "params": {
+            "resource": {
+                "type": "str",
+                "required": True,
+                "desc": "resource type (e.g. pod, deployment, service, node)",
+            },
+            "name": {
+                "type": "str",
+                "required": False,
+                "desc": "specific resource name",
+            },
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "Kubernetes namespace",
+            },
+        },
+    },
+    "k8s_logs": {
+        "fn": k8s_logs,
+        "desc": "Get logs from a pod. Read-only — only `logs` is executed. Use when a pod is misbehaving or you need to inspect its output.",
+        "params": {
+            "pod": {"type": "str", "required": True, "desc": "pod name"},
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "Kubernetes namespace",
+            },
+            "tail": {
+                "type": "int",
+                "required": False,
+                "desc": "last N lines (0 = all)",
+            },
+            "container": {
+                "type": "str",
+                "required": False,
+                "desc": "specific container name within the pod",
+            },
+            "since": {
+                "type": "str",
+                "required": False,
+                "desc": "fetch logs since duration (e.g. 1h, 10m, 30s)",
+            },
+            "previous": {
+                "type": "bool",
+                "required": False,
+                "desc": "fetch logs from the previous (restarted) container",
+            },
+            "all_containers": {
+                "type": "bool",
+                "required": False,
+                "desc": "fetch logs from all containers in the pod",
+            },
+            "timeout": {
+                "type": "int",
+                "required": False,
+                "desc": "SSH/kubectl timeout in seconds",
+            },
+        },
+    },
+    "k8s_top": {
+        "fn": k8s_top,
+        "desc": "Show resource (CPU/memory) usage. Read-only — only `top` is executed. Use to find nodes or pods under pressure.",
+        "params": {
+            "resource_type": {
+                "type": "str",
+                "required": True,
+                "desc": "node or pod",
+            },
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "namespace (only applies to pod)",
+            },
+        },
+    },
+    "k8s_cluster_info": {
+        "fn": k8s_cluster_info,
+        "desc": "Show cluster info (master endpoint, services). Read-only.",
+        "params": {},
+    },
+    "k8s_api_resources": {
+        "fn": k8s_api_resources,
+        "desc": "List available API resources on the cluster. Read-only.",
+        "params": {},
+    },
+    "k8s_explain": {
+        "fn": k8s_explain,
+        "desc": "Get documentation for a Kubernetes resource type. Read-only.",
+        "params": {
+            "resource": {
+                "type": "str",
+                "required": True,
+                "desc": "resource type to explain (e.g. pod, deployment, service)",
+            },
+        },
+    },
+    "k8s_version": {
+        "fn": k8s_version,
+        "desc": "Show Kubernetes version info (client and server). Read-only.",
+        "params": {},
+    },
+    "k8s_events": {
+        "fn": k8s_events,
+        "desc": "List Kubernetes events, optionally filtered by namespace or field-selector (e.g. type=Warning). Read-only — only `get events` is executed. Use when investigating failures.",
+        "params": {
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "Kubernetes namespace (all namespaces when omitted)",
+            },
+            "field_selector": {
+                "type": "str",
+                "required": False,
+                "desc": "field selector, e.g. type=Warning or reason=Failed",
+            },
+            "output": {
+                "type": "str",
+                "required": False,
+                "desc": "output format: wide, yaml, json",
+            },
+        },
+    },
+    "k8s_rollout": {
+        "fn": k8s_rollout,
+        "desc": "Show rollout status or history for a workload (deployment/statefulset/daemonset). Read-only — status/history only.",
+        "params": {
+            "action": {
+                "type": "str",
+                "required": True,
+                "desc": "status or history (read-only; other actions are rejected)",
+            },
+            "resource": {
+                "type": "str",
+                "required": True,
+                "desc": "workload type, e.g. deployment",
+            },
+            "name": {"type": "str", "required": True, "desc": "workload name"},
+            "namespace": {
+                "type": "str",
+                "required": False,
+                "desc": "Kubernetes namespace",
+            },
+        },
+    },
+}
+
+
+def serve() -> None:
+    """Run the Kubernetes diagnostics MCP stdio server."""
+    serve_protocol(TOOLS, SERVER_NAME)

wl_cli/mcp/protocol.py

@@ -0,0 +1,159 @@
+"""Minimal JSON-RPC over stdio protocol for wl MCP servers.
+
+The two MCP servers share this implementation. Each server only supplies its
+tool registry and wire name; schema derivation, argument coercion, response
+rendering, and method dispatch live here.
+"""
+
+import json
+import sys
+from collections.abc import Callable
+from typing import Any
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_VERSION = "1.0.0"
+
+Handler = Callable[[dict[str, Any]], str]
+
+_JSON_TYPES = {"str": "string", "int": "integer", "bool": "boolean"}
+
+
+def _coerce(args: dict[str, Any], params: dict[str, Any]) -> dict[str, Any]:
+    """Coerce arguments according to their declared parameter types."""
+    coerced: dict[str, Any] = {}
+    for key, value in args.items():
+        kind = params.get(key, {}).get("type")
+        if kind == "int":
+            coerced[key] = int(value)
+        elif (
+            kind == "bool"
+            and isinstance(value, str)
+            and value.lower()
+            in (
+                "true",
+                "false",
+            )
+        ):
+            coerced[key] = value.lower() == "true"
+        else:
+            coerced[key] = value
+    return coerced
+
+
+def _render(result: Any) -> str:
+    """Render a tool result as text without escaping non-ASCII characters."""
+    if isinstance(result, str):
+        return result
+    return json.dumps(result, indent=2, ensure_ascii=False)
+
+
+def _error(msg_id: Any, code: int, message: str) -> str:
+    """Build a JSON-RPC error response."""
+    return json.dumps(
+        {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}}
+    )
+
+
+def make_handler(tools: dict[str, dict[str, Any]], server_name: str) -> Handler:
+    """Build a protocol handler bound to a tool registry and server name."""
+
+    def _handle(msg: dict[str, Any]) -> str:
+        method = msg.get("method", "")
+        msg_id = msg.get("id")
+
+        if method == "initialize":
+            return json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": {
+                        "protocolVersion": PROTOCOL_VERSION,
+                        "serverInfo": {"name": server_name, "version": SERVER_VERSION},
+                        "capabilities": {"tools": {}},
+                    },
+                }
+            )
+        if method == "notifications/initialized":
+            return ""
+        if method == "shutdown":
+            return json.dumps({"jsonrpc": "2.0", "id": msg_id, "result": None})
+
+        if method == "tools/list":
+            return json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": {
+                        "tools": [
+                            {
+                                "name": name,
+                                "description": spec["desc"],
+                                "inputSchema": {
+                                    "type": "object",
+                                    "properties": {
+                                        key: {
+                                            "type": _JSON_TYPES[decl["type"]],
+                                            "description": decl["desc"],
+                                        }
+                                        for key, decl in spec["params"].items()
+                                    },
+                                    "required": [
+                                        key
+                                        for key, decl in spec["params"].items()
+                                        if decl["required"]
+                                    ],
+                                },
+                            }
+                            for name, spec in tools.items()
+                        ],
+                    },
+                }
+            )
+
+        if method == "tools/call":
+            tool_name = msg["params"]["name"]
+            args = msg["params"].get("arguments", {})
+            if tool_name not in tools:
+                return _error(msg_id, -32601, f"Unknown tool: {tool_name}")
+            try:
+                result = tools[tool_name]["fn"](
+                    **_coerce(args, tools[tool_name]["params"])
+                )
+            except Exception as exc:
+                return _error(msg_id, -32603, str(exc))
+            return json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": msg_id,
+                    "result": {"content": [{"type": "text", "text": _render(result)}]},
+                }
+            )
+
+        return _error(msg_id, -32601, f"Unknown method: {method}")
+
+    return _handle
+
+
+def serve(tools: dict[str, dict[str, Any]], server_name: str) -> None:
+    """Run the JSON-RPC line protocol until stdin reaches EOF.
+
+    Malformed JSON receives a ``-32700`` response and does not terminate the
+    loop, so clients can recover and send the next request.
+    """
+    handle = make_handler(tools, server_name)
+    for raw_line in sys.stdin:
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError:
+            response = _error(None, -32700, "Parse error")
+        else:
+            if not isinstance(message, dict):
+                response = _error(None, -32600, "Invalid request")
+            else:
+                response = handle(message)
+        if response:
+            sys.stdout.write(response + "\n")
+            sys.stdout.flush()

wl_cli/platform.py

@@ -0,0 +1,139 @@
+"""Platform reporting seam for ``wl`` (issue #226 / wlcc #321).
+
+**Scope (#226):** this module provides the shared computation of the platform
+matrix fields and the payload shape agreed in wlcc #321. Wiring it into the
+CLI is deliberately out of scope: ``wl env check`` is delivered by #221 and
+will be the first consumer. No command in this repository calls
+``platform_payload()`` yet.
+
+The distribution is a pure-Python wheel (``py3-none-any``): every Python
+3.11+ platform can install and run ``wl`` without a Rust toolchain. The native
+extension is optional and diagnostic only, so it never decides ``supported``.
+"""
+
+from __future__ import annotations
+
+import glob
+import sysconfig
+from platform import libc_ver, machine, python_version, system
+
+MIN_PYTHON: tuple[int, int] = (3, 11)
+
+#: ``platform.system()`` -> report prefix. Windows is shortened to ``win`` so
+#: the identifiers read like the wheel tags users see (``win-amd64``).
+_OS_PREFIXES = {"darwin": "darwin", "linux": "linux", "windows": "win"}
+
+#: musl's dynamic loader; ``platform.libc_ver()`` does not recognise musl on
+#: real musl systems, so the loader on disk is the fallback probe.
+_MUSL_LOADER_GLOB = "/lib/ld-musl-*.so.1"
+
+
+def _os_name() -> str:
+    """Return the report's OS component (``darwin``/``linux``/``win``)."""
+    raw = system().lower()
+    return _OS_PREFIXES.get(raw, raw)
+
+
+def _arch_name() -> str:
+    """Return the CPU architecture as reported by ``platform.machine()``.
+
+    Normalising here would lose information: ``uname -m`` already yields the
+    names users expect per OS (``arm64`` on macOS, ``aarch64`` on Linux,
+    ``AMD64``/``ARM64`` on Windows).
+    """
+    return machine().lower() or "unknown"
+
+
+def _host_gnu_type() -> str:
+    """Return the interpreter's build triple (``HOST_GNU_TYPE``), lower-cased.
+
+    CPython builds for glibc report triples ending in ``-gnu`` and musl builds
+    end in ``-musl``; this is the reliable in-process musl signal.
+    """
+    value = sysconfig.get_config_var("HOST_GNU_TYPE")
+    return str(value).lower() if value else ""
+
+
+def _musl_loader_present() -> bool:
+    """Return whether a musl dynamic loader exists on disk."""
+    return bool(glob.glob(_MUSL_LOADER_GLOB))
+
+
+def _libc_name() -> str:
+    """Return the Linux userland's libc: ``glibc``, ``musl`` or ``unknown``.
+
+    ``platform.libc_ver()`` only reliably recognises glibc; on real musl
+    systems it returns ``("", "")`` (or a generic ``libc``), which is why the
+    build triple and the loader on disk are probed first.
+    """
+    host_type = _host_gnu_type()
+    if "musl" in host_type:
+        return "musl"
+    if "gnu" in host_type:
+        return "glibc"
+    if _musl_loader_present():
+        return "musl"
+    lib, _version = libc_ver()
+    lib = lib.lower()
+    if lib in {"glibc", "musl"}:
+        return lib
+    return "unknown"
+
+
+def _platform_identifier() -> str:
+    """Build ``darwin-arm64`` / ``linux-x86_64-glibc`` / ``win-amd64``."""
+    os_name = _os_name()
+    arch = _arch_name()
+    if os_name == "linux":
+        return f"linux-{arch}-{_libc_name()}"
+    return f"{os_name}-{arch}"
+
+
+def _python_supported(version: str) -> bool:
+    """Return whether *version* meets the pure-Python requirement (3.11+)."""
+    parts = version.split(".")
+    try:
+        major, minor = int(parts[0]), int(parts[1])
+    except (IndexError, ValueError):
+        return False
+    return (major, minor) >= MIN_PYTHON
+
+
+def _native_extension_present() -> bool:
+    """Import the optional extension flag lazily to avoid import cycles."""
+    from .lib.rust_utils import HAS_RUST_EXTENSION
+
+    return bool(HAS_RUST_EXTENSION)
+
+
+def platform_payload() -> dict[str, str | bool | None]:
+    """Return the platform matrix fields defined by wlcc #321.
+
+    This is the seam #221's ``wl env check`` will serialise; it is not
+    consumed by any CLI command in this ticket.
+
+    Returns:
+        ``platform``: ``os-arch[-libc]`` identifier (e.g. ``linux-x86_64-glibc``).
+        ``python``: ``X.Y.Z`` interpreter version.
+        ``native_extension``: whether the optional Rust extension imported;
+        diagnostic only, it never gates support.
+        ``supported``: true for Python >= 3.11 (the pure-Python path).
+        ``reason``: ``None`` when supported, else a readable explanation.
+    """
+    version = python_version()
+    supported = _python_supported(version)
+    reason = (
+        None
+        if supported
+        else (
+            f"Python {version} is not supported: wl requires Python 3.11 or "
+            "newer (pure-Python wheel; no native extension is required)."
+        )
+    )
+    return {
+        "platform": _platform_identifier(),
+        "python": version,
+        "native_extension": _native_extension_present(),
+        "supported": supported,
+        "reason": reason,
+    }

wl_cli/quality/__init__.py

@@ -0,0 +1,18 @@
+"""Quality domain (issue #220).
+
+The quality domain's **existing implementation** lives in
+:mod:`wl_cli.commands` (``test`` / ``format`` / ``lint`` / ``init`` /
+``git-flow`` and the other command modules) with its Rust acceleration in
+:mod:`wl_cli.lib`. This ticket deliberately does **not** relocate those
+modules: the move is out of scope, and the user-visible ``wl`` surface must
+not change while it happens. This package only names the domain so later
+splits have an anchor.
+
+Dependency direction: this package (like ``wl_cli.commands`` and
+``wl_cli.lib``) may not import ``wl_cli.cc`` or ``wl_cli.mcp`` — enforced by
+``tests/test_domain_import_direction.py``.
+"""
+
+DOMAIN = "quality"
+
+__all__ = ["DOMAIN"]

wl_cli/utils/__init__.py

@@ -0,0 +1,7 @@
+"""
+Utils module for WL Commands.
+"""
+
+from .lazy_import import lazy_import, lazy_imports
+
+__all__ = ["project_root", "platform_adapter", "lazy_import", "lazy_imports"]