kx-cli 0.0.5__tar.gz → 0.0.6__tar.gz

{kx_cli-0.0.5/src/kx_cli.egg-info → kx_cli-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kx-cli
-Version: 0.0.5
+Version: 0.0.6
 Summary: kubectl wrapper with index-based resource selection
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -16,6 +16,7 @@ Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
@@ -63,14 +64,17 @@ Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespac
 
 ```
 $ kx get pods
-X  NAME                          READY  STATUS   RESTARTS  AGE
-1  api-7d9f4b8c6-xkp2q           1/1    Running  0         2d
-2  worker-6c8b5f7d9-mnt4r        1/1    Running  3         5h
-3  postgres-0                    1/1    Running  0         12d
+Pods · default · 3 items
+  X    NAME                      READY    STATUS     RESTARTS    AGE
+  1    api-7d9f4b8c6-xkp2q       1/1      Running    0            2d
+  2    worker-6c8b5f7d9-mnt4r    1/1      Running    3            5h
+  3    postgres-0                1/1      Running    0           12d
 ```
 
 All subsequent commands reference resources by their `X` index from the last `kx get`.
 
+Global flags: `--no-color` disables styled output, `--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
+
 ### Commands
 
 <!-- commands-table-start -->
@@ -89,7 +93,9 @@ All subsequent commands reference resources by their `X` index from the last `kx
 | `kx rollout <action> <index>` | Run a rollout action (status, restart, pause, resume, history, undo) on a Deployment, StatefulSet, or DaemonSet. |
 | `kx scale <index> <replicas>` | Scale an indexed Deployment, StatefulSet, or ReplicaSet to a given replica count. |
 | `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to an indexed resource (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service). |
+| `kx diagnostic <index>` | Run read-only health diagnostics on an indexed Deployment, StatefulSet, DaemonSet, or Pod; alias: kx diag. |
 | `kx namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `kx theme [<name>]` | List available color themes or persist a choice by name or index. |
 | `kx state [<position>] [--all/-a]` | Show current state, jump to a history position, or list all entries with --all. |
 | `kx drop <position>` | Remove a history entry by position (shown in kx state --all). |
 | `kx back` | Navigate to the previous kx get result. |
@@ -128,7 +134,7 @@ kx delete 3
 
 ## State
 
-`kx` maintains a history of up to 10 `kx get` results in `~/.kx_state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
+`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
 
 ```
 $ kx get pods          # saves a new entry, cursor advances
@@ -139,6 +145,29 @@ $ kx state --all       # lists all history entries and the current position
 
 Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
 
+## Configuration
+
+`kx` reads `~/.kx/config.toml`; environment variables override file settings.
+
+| Key | Env var | Default | Description |
+| --- | --- | --- | --- |
+| `max_history` | `KX_MAX_HISTORY` | `10` | Number of `kx get` results kept in history. |
+| `shells` | `KX_SHELLS` (comma-separated) | `["bash", "sh"]` | Shell candidates for `kx exec`. |
+| `no_color` | `KX_NO_COLOR` | `false` | Disable styled output (same as `--no-color`). |
+| `theme` | `KX_THEME` | `"github-dark"` | Color theme for all output. |
+
+Styled output is emitted only when stdout is a terminal — piped or redirected output is plain text, so `kx get pods | grep worker` stays clean. The [`NO_COLOR`](https://no-color.org/) convention is honored as well.
+
+### Themes
+
+```bash
+kx theme        # list available themes (indexed) with a preview of each
+kx theme nord   # persist a theme to ~/.kx/config.toml
+kx theme 3      # same, selecting by index from the kx theme listing
+```
+
+Prefab themes: `github-dark` (default), `dracula`, `nord`, `gruvbox`, `solarized-dark`, `catppuccin-mocha`, `tokyo-night`, `rose-pine`, `mono`, `light` (for light terminal backgrounds), and `plain` (no styling at all).
+
 ## Development
 
 ```bash

{kx_cli-0.0.5 → kx_cli-0.0.6}/README.md

@@ -43,14 +43,17 @@ Fetches resources and assigns index numbers. Any extra flags (e.g. `-n <namespac
 
 ```
 $ kx get pods
-X  NAME                          READY  STATUS   RESTARTS  AGE
-1  api-7d9f4b8c6-xkp2q           1/1    Running  0         2d
-2  worker-6c8b5f7d9-mnt4r        1/1    Running  3         5h
-3  postgres-0                    1/1    Running  0         12d
+Pods · default · 3 items
+  X    NAME                      READY    STATUS     RESTARTS    AGE
+  1    api-7d9f4b8c6-xkp2q       1/1      Running    0            2d
+  2    worker-6c8b5f7d9-mnt4r    1/1      Running    3            5h
+  3    postgres-0                1/1      Running    0           12d
 ```
 
 All subsequent commands reference resources by their `X` index from the last `kx get`.
 
+Global flags: `--no-color` disables styled output, `--version` prints the installed version, and `--help` on any command shows usage, examples, and aliases.
+
 ### Commands
 
 <!-- commands-table-start -->
@@ -69,7 +72,9 @@ All subsequent commands reference resources by their `X` index from the last `kx
 | `kx rollout <action> <index>` | Run a rollout action (status, restart, pause, resume, history, undo) on a Deployment, StatefulSet, or DaemonSet. |
 | `kx scale <index> <replicas>` | Scale an indexed Deployment, StatefulSet, or ReplicaSet to a given replica count. |
 | `kx port-forward <index> <port> [kubectl flags...]` | Forward a local port to an indexed resource (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Service). |
+| `kx diagnostic <index>` | Run read-only health diagnostics on an indexed Deployment, StatefulSet, DaemonSet, or Pod; alias: kx diag. |
 | `kx namespace <index>` | Switch to an indexed namespace; alias: kx ns (run kx get namespaces first). |
+| `kx theme [<name>]` | List available color themes or persist a choice by name or index. |
 | `kx state [<position>] [--all/-a]` | Show current state, jump to a history position, or list all entries with --all. |
 | `kx drop <position>` | Remove a history entry by position (shown in kx state --all). |
 | `kx back` | Navigate to the previous kx get result. |
@@ -108,7 +113,7 @@ kx delete 3
 
 ## State
 
-`kx` maintains a history of up to 10 `kx get` results in `~/.kx_state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
+`kx` maintains a history of up to 10 `kx get` results in `~/.kx/state.json`. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor.
 
 ```
 $ kx get pods          # saves a new entry, cursor advances
@@ -119,6 +124,29 @@ $ kx state --all       # lists all history entries and the current position
 
 Use `kx state <position>` to jump directly to any history entry, and `kx drop <position>` to remove one.
 
+## Configuration
+
+`kx` reads `~/.kx/config.toml`; environment variables override file settings.
+
+| Key | Env var | Default | Description |
+| --- | --- | --- | --- |
+| `max_history` | `KX_MAX_HISTORY` | `10` | Number of `kx get` results kept in history. |
+| `shells` | `KX_SHELLS` (comma-separated) | `["bash", "sh"]` | Shell candidates for `kx exec`. |
+| `no_color` | `KX_NO_COLOR` | `false` | Disable styled output (same as `--no-color`). |
+| `theme` | `KX_THEME` | `"github-dark"` | Color theme for all output. |
+
+Styled output is emitted only when stdout is a terminal — piped or redirected output is plain text, so `kx get pods | grep worker` stays clean. The [`NO_COLOR`](https://no-color.org/) convention is honored as well.
+
+### Themes
+
+```bash
+kx theme        # list available themes (indexed) with a preview of each
+kx theme nord   # persist a theme to ~/.kx/config.toml
+kx theme 3      # same, selecting by index from the kx theme listing
+```
+
+Prefab themes: `github-dark` (default), `dracula`, `nord`, `gruvbox`, `solarized-dark`, `catppuccin-mocha`, `tokyo-night`, `rose-pine`, `mono`, `light` (for light terminal backgrounds), and `plain` (no styling at all).
+
 ## Development
 
 ```bash

{kx_cli-0.0.5 → kx_cli-0.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kx-cli"
-version = "0.0.5"
+version = "0.0.6"
 description = "kubectl wrapper with index-based resource selection"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -21,6 +21,7 @@ dev = [
     "ruff",
     "pre-commit",
     "pytest",
+    "pytest-cov",
 ]
 
 [project.scripts]

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/describe.py

@@ -11,7 +11,8 @@ class DescribeCommand:
         self.state = state
         self.kubectl = kubectl
 
-    def execute(self, index: int, extra_args: list[str] = []) -> None:
+    def execute(self, index: int, extra_args: list[str] | None = None) -> None:
+        extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         self.kubectl.run_interactive(
             ["describe", kind, name, "-n", namespace, *extra_args]

kx_cli-0.0.6/src/kx/commands/diagnostic.py

@@ -0,0 +1,195 @@
+from kx.diagnostics import (
+    ContainerDiagnostic,
+    DiagnosticData,
+    DiagnosticReport,
+    DiagnosticsServiceProtocol,
+    Finding,
+    PodDiagnostic,
+    ReplicaHealth,
+    Severity,
+)
+from kx.kinds import Kind
+from kx.state import StateServiceProtocol
+
+_SUPPORTED_KINDS = {Kind.Deployment, Kind.StatefulSet, Kind.DaemonSet, Kind.Pod}
+_RESTART_WARN_THRESHOLD = 5
+
+_IMAGE_PULL_REASONS = {"ImagePullBackOff", "ErrImagePull", "InvalidImageName"}
+_CONFIG_ERROR_REASONS = {"CreateContainerConfigError", "CreateContainerError"}
+
+
+class DiagnosticCommand:
+    def __init__(
+        self,
+        state: StateServiceProtocol,
+        diagnostics: DiagnosticsServiceProtocol,
+    ):
+        self.state = state
+        self.diagnostics = diagnostics
+
+    def execute(self, index: int) -> DiagnosticReport:
+        name, namespace, kind = self.state.fields(index)
+        if kind not in _SUPPORTED_KINDS:
+            raise ValueError(f"diagnostic is not supported for '{kind}'.")
+        return build_report(self.diagnostics.gather(kind, name, namespace))
+
+
+def build_report(data: DiagnosticData) -> DiagnosticReport:
+    findings: list[Finding] = []
+
+    if data.replicas is not None:
+        findings.extend(_replica_findings(data.replicas))
+    for pod in data.pods:
+        findings.extend(_pod_findings(pod))
+    findings.extend(_event_findings(data.warning_events))
+
+    # Prioritize: highest severity first, stable within a severity.
+    findings.sort(key=lambda f: f.severity, reverse=True)
+    verdict = max((f.severity for f in findings), default=Severity.OK)
+
+    return DiagnosticReport(
+        kind=data.kind,
+        name=data.name,
+        namespace=data.namespace,
+        verdict=verdict,
+        findings=findings,
+        pods=data.pods,
+        warning_events=data.warning_events,
+    )
+
+
+def _replica_findings(replicas: ReplicaHealth) -> list[Finding]:
+    findings: list[Finding] = []
+    gen = replicas.generation
+    observed = replicas.observed_generation
+    if gen is not None and observed is not None and observed < gen:
+        findings.append(
+            Finding(
+                Severity.CRITICAL,
+                f"Rollout stalled: observed generation {observed} behind spec generation {gen}",
+            )
+        )
+    if replicas.ready < replicas.desired:
+        severity = (
+            Severity.CRITICAL
+            if replicas.ready == 0 and replicas.desired > 0
+            else Severity.WARNING
+        )
+        findings.append(
+            Finding(
+                severity,
+                f"Only {replicas.ready}/{replicas.desired} replicas ready",
+            )
+        )
+    if replicas.available < replicas.desired:
+        findings.append(
+            Finding(
+                Severity.WARNING,
+                f"{replicas.available}/{replicas.desired} replicas available",
+            )
+        )
+    if replicas.updated < replicas.desired:
+        findings.append(
+            Finding(
+                Severity.WARNING,
+                f"Rollout in progress: {replicas.updated}/{replicas.desired} replicas updated",
+            )
+        )
+    return findings
+
+
+def _pod_findings(pod: PodDiagnostic) -> list[Finding]:
+    findings: list[Finding] = []
+
+    for container in pod.containers:
+        findings.extend(_container_findings(pod.name, container))
+
+    if pod.phase == "Pending" and not pod.scheduling.schedulable:
+        detail = pod.scheduling.message or pod.scheduling.reason or "unschedulable"
+        findings.append(
+            Finding(Severity.CRITICAL, f"Pod {pod.name} unschedulable: {detail}")
+        )
+    elif pod.phase == "Pending":
+        findings.append(Finding(Severity.WARNING, f"Pod {pod.name} pending"))
+    elif pod.phase == "Failed":
+        findings.append(Finding(Severity.CRITICAL, f"Pod {pod.name} failed"))
+    elif (
+        pod.phase == "Running"
+        and pod.ready_containers < pod.total_containers
+        and not any(c.waiting_reason for c in pod.containers)
+    ):
+        findings.append(
+            Finding(
+                Severity.WARNING,
+                f"Pod {pod.name}: {pod.ready_containers}/{pod.total_containers} containers ready",
+            )
+        )
+    return findings
+
+
+def _container_findings(pod_name: str, container: ContainerDiagnostic) -> list[Finding]:
+    findings: list[Finding] = []
+    reason = container.waiting_reason
+
+    if reason == "CrashLoopBackOff":
+        findings.append(
+            Finding(
+                Severity.CRITICAL,
+                f"CrashLoopBackOff in pod {pod_name} ({container.restart_count} restarts)",
+            )
+        )
+    elif reason in _IMAGE_PULL_REASONS:
+        findings.append(
+            Finding(
+                Severity.CRITICAL,
+                f"Image pull failure ({reason}) in pod {pod_name}",
+            )
+        )
+    elif reason in _CONFIG_ERROR_REASONS:
+        detail = container.waiting_message or reason
+        findings.append(
+            Finding(
+                Severity.CRITICAL,
+                f"Container config error in pod {pod_name}: {detail}",
+            )
+        )
+    elif reason is not None:
+        findings.append(
+            Finding(
+                Severity.WARNING,
+                f"Container {container.name} in pod {pod_name} waiting: {reason}",
+            )
+        )
+
+    if "OOMKilled" in (container.terminated_reason, container.last_terminated_reason):
+        findings.append(Finding(Severity.CRITICAL, f"OOMKilled in pod {pod_name}"))
+    elif container.terminated_reason not in (None, "Completed") and container.exit_code:
+        findings.append(
+            Finding(
+                Severity.CRITICAL,
+                f"Container {container.name} in pod {pod_name} terminated: "
+                f"{container.terminated_reason} (exit {container.exit_code})",
+            )
+        )
+
+    if reason is None and container.restart_count >= _RESTART_WARN_THRESHOLD:
+        findings.append(
+            Finding(
+                Severity.WARNING,
+                f"Container {container.name} in pod {pod_name} "
+                f"restarted {container.restart_count} times",
+            )
+        )
+    return findings
+
+
+def _event_findings(events) -> list[Finding]:
+    # The message is deliberately omitted: the WARNING EVENTS section renders it
+    # in full, so repeating it here only bloats the summary.
+    return [
+        Finding(
+            Severity.WARNING,
+            f"{event.reason} ×{event.count} on {event.kind}/{event.name}",
+        )
+        for event in events
+    ]

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/edit.py

@@ -7,6 +7,7 @@ class EditCommand:
         self.state = state
         self.kubectl = kubectl
 
-    def execute(self, index: int, extra_args: list[str] = []) -> None:
+    def execute(self, index: int, extra_args: list[str] | None = None) -> None:
+        extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         self.kubectl.run_interactive(["edit", kind, name, "-n", namespace, *extra_args])

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/exec.py

@@ -17,8 +17,9 @@ class ExecCommand:
         self.shells = shells
 
     def execute(
-        self, index: int, cmd: list[str] | None, extra_args: list[str] = []
+        self, index: int, cmd: list[str] | None, extra_args: list[str] | None = None
     ) -> None:
+        extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         if kind != Kind.Pod:
             raise ValueError("exec is only supported for pods.")

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/get.py

@@ -28,8 +28,9 @@ class GetCommand:
         self,
         resource: str,
         filter_term: str | None = None,
-        extra_args: list[str] = [],
+        extra_args: list[str] | None = None,
     ) -> str:
+        extra_args = extra_args or []
         output = self.kubectl.run(["get", resource, *extra_args])
         if filter_term:
             output = self.index.filter(output, filter_term)

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/logs.py

@@ -12,7 +12,8 @@ class LogsCommand:
         self.state = state
         self.kubectl = kubectl
 
-    def execute(self, index: int, extra_args: list[str] = []) -> None:
+    def execute(self, index: int, extra_args: list[str] | None = None) -> None:
+        extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         if kind == Kind.Pod:
             self.kubectl.run_interactive(["logs", name, "-n", namespace, *extra_args])

{kx_cli-0.0.5 → kx_cli-0.0.6}/src/kx/commands/port_forward.py

@@ -17,7 +17,10 @@ class PortForwardCommand:
         self.kubectl = kubectl
         self.state = state
 
-    def execute(self, index: int, port: str, extra_args: list[str] = []) -> None:
+    def execute(
+        self, index: int, port: str, extra_args: list[str] | None = None
+    ) -> None:
+        extra_args = extra_args or []
         name, namespace, kind = self.state.fields(index)
         if kind not in _SUPPORTED_KINDS:
             raise ValueError(f"port-forward is not supported for '{kind}'.")

kx_cli-0.0.6/src/kx/commands/theme.py

@@ -0,0 +1,23 @@
+from typing import Callable
+
+from kx.themes import THEMES
+
+
+class ThemeCommand:
+    def __init__(self, save: Callable[[str], None]):
+        self.save = save
+
+    def execute(self, name: str) -> str:
+        if name.isdigit():
+            names = list(THEMES)
+            position = int(name)
+            if not 1 <= position <= len(names):
+                raise ValueError(
+                    f"Theme index {position} is out of range — {len(names)} themes "
+                    f"(run 'kx theme' to list)."
+                )
+            name = names[position - 1]
+        if name not in THEMES:
+            raise ValueError(f"Unknown theme '{name}'. Run 'kx theme' to list themes.")
+        self.save(name)
+        return f"Theme set to '{name}'"

kx_cli-0.0.6/src/kx/config.py

@@ -0,0 +1,82 @@
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from kx.themes import DEFAULT_THEME, THEMES
+
+_CONFIG_FILE = Path.home() / ".kx" / "config.toml"
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    max_history: int = 10
+    shells: tuple[str, ...] = ("bash", "sh")
+    no_color: bool = False
+    theme: str = DEFAULT_THEME
+
+
+def load_config() -> Config:
+    kwargs: dict = {}
+
+    if _CONFIG_FILE.exists():
+        try:
+            with open(_CONFIG_FILE, "rb") as f:
+                data = tomllib.load(f)
+        except tomllib.TOMLDecodeError as e:
+            raise SystemExit(f"kx: error reading {_CONFIG_FILE}: {e}")
+
+        if "max_history" in data:
+            kwargs["max_history"] = data["max_history"]
+        if "shells" in data:
+            kwargs["shells"] = tuple(data["shells"])
+        if "no_color" in data:
+            kwargs["no_color"] = data["no_color"]
+        if "theme" in data:
+            kwargs["theme"] = data["theme"]
+
+    if "KX_MAX_HISTORY" in os.environ:
+        try:
+            kwargs["max_history"] = int(os.environ["KX_MAX_HISTORY"])
+        except ValueError:
+            raise SystemExit("kx: KX_MAX_HISTORY must be an integer")
+
+    if "KX_SHELLS" in os.environ:
+        kwargs["shells"] = tuple(os.environ["KX_SHELLS"].split(","))
+
+    if "KX_NO_COLOR" in os.environ:
+        value = os.environ["KX_NO_COLOR"].lower()
+        kwargs["no_color"] = value in {"1", "true", "yes", "on"}
+
+    if "KX_THEME" in os.environ:
+        kwargs["theme"] = os.environ["KX_THEME"]
+
+    if "theme" in kwargs and kwargs["theme"] not in THEMES:
+        raise SystemExit(
+            f"kx: unknown theme '{kwargs['theme']}' (run kx theme to list themes)"
+        )
+
+    return Config(**kwargs)
+
+
+def save_theme(name: str) -> None:
+    """Persist the theme choice to the config file.
+
+    Rewrites only the `theme = ...` line (or appends one) instead of
+    round-tripping the TOML, so user comments and formatting survive. Safe
+    because the config schema is flat: there are no tables a `theme` key
+    could belong to.
+    """
+    line = f'theme = "{name}"'
+    if _CONFIG_FILE.exists():
+        text = _CONFIG_FILE.read_text()
+        new, count = re.subn(r"(?m)^theme\s*=.*$", line, text, count=1)
+        if count == 0:
+            if text and not text.endswith("\n"):
+                text += "\n"
+            new = text + line + "\n"
+        _CONFIG_FILE.write_text(new)
+    else:
+        _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CONFIG_FILE.write_text(line + "\n")