kube-query 0.1.0__py3-none-any.whl

kube_query/__init__.py

@@ -0,0 +1,3 @@
+"""kube-query - read-only Kubernetes query CLI for humans and AI agents."""
+
+__version__ = "0.1.0"

kube_query/access.py

@@ -0,0 +1,85 @@
+"""Object-level access: list/get any resource by its ApiResource, read pod logs."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .config import Ctx
+from .discovery import ApiResource
+from .errors import KqApiError, KqError
+from .http import get_json, get_text
+
+
+def resource_path(entry: ApiResource, namespace: str | None = None, name: str | None = None) -> str:
+    if entry.group:
+        base = f"/apis/{quote(entry.api_version, safe='/')}"
+    else:
+        base = f"/api/{entry.version}"
+    if entry.namespaced and namespace:
+        base += f"/namespaces/{quote(namespace, safe='')}"
+    base += f"/{entry.plural}"
+    if name:
+        base += f"/{quote(name, safe='')}"
+    return base
+
+
+def list_objects(
+    ctx: Ctx,
+    entry: ApiResource,
+    *,
+    namespace: str | None = None,
+    label_selector: str | None = None,
+    field_selector: str | None = None,
+) -> list[dict]:
+    """List objects. ``namespace=None`` on a namespaced resource lists all namespaces."""
+    if not entry.namespaced and namespace:
+        namespace = None
+    params = {"labelSelector": label_selector, "fieldSelector": field_selector}
+    data = get_json(ctx.api_client, resource_path(entry, namespace), params)
+    items = data.get("items")
+    if not isinstance(items, list):
+        raise KqError(f"unexpected response while listing {entry.plural}")
+    return items
+
+
+def get_object(ctx: Ctx, entry: ApiResource, name: str, *, namespace: str | None = None) -> dict:
+    if entry.namespaced and not namespace:
+        raise KqError(f"internal: namespace required to fetch a namespaced {entry.kind}")
+    try:
+        return get_json(ctx.api_client, resource_path(entry, namespace, name))
+    except KqApiError as e:
+        if e.status == 404:
+            where = f" in namespace '{namespace}'" if entry.namespaced else ""
+            scope = f" -n {namespace}" if entry.namespaced else ""
+            alt = " (or -A for all namespaces)" if entry.namespaced else ""
+            raise KqError(
+                f"{entry.kind} '{name}' not found{where}.\n"
+                f"  Hint: list candidates with 'kq get {entry.plural}{scope}'{alt}."
+            ) from None
+        raise
+
+
+def pod_logs(
+    ctx: Ctx,
+    namespace: str,
+    pod: str,
+    *,
+    container: str | None = None,
+    tail: int | None = None,
+    previous: bool = False,
+    since_seconds: int | None = None,
+    timestamps: bool = False,
+) -> str:
+    path = f"/api/v1/namespaces/{quote(namespace, safe='')}/pods/{quote(pod, safe='')}/log"
+    params = {
+        "container": container,
+        "tailLines": tail,
+        "previous": "true" if previous else None,
+        "sinceSeconds": since_seconds,
+        "timestamps": "true" if timestamps else None,
+    }
+    return get_text(ctx.api_client, path, params)
+
+
+def server_version(ctx: Ctx) -> dict:
+    return get_json(ctx.api_client, "/version")

kube_query/cleanup.py

@@ -0,0 +1,115 @@
+"""Output compaction: strip agent-irrelevant noise from Kubernetes objects.
+
+Verbosity levels::
+
+    0  (default)  drop managedFields, uid, resourceVersion, generation,
+                  selfLink, noisy annotations, and all empty values
+    1  (-v)       drop managedFields and noisy annotations only
+    2  (-vv)      raw object, nothing is stripped
+"""
+
+from __future__ import annotations
+
+import base64
+
+NOISY_META = ("managedFields", "selfLink", "resourceVersion", "uid", "generation")
+NOISY_ANNOTATIONS = (
+    "kubectl.kubernetes.io/last-applied-configuration",
+    "deployment.kubernetes.io/revision",
+    "deprecated.daemonset.template.generation",
+)
+_EMPTY = ("", {}, [], None)
+
+
+def compact(obj: dict | list, verbose: int = 0) -> dict | list:
+    if verbose >= 2:
+        return obj
+    obj = _strip_noisy(obj)
+    if verbose == 0:
+        obj = _drop_empty(obj)
+    return obj
+
+
+def _strip_noisy(node):
+    if isinstance(node, dict):
+        out = {}
+        for k, v in node.items():
+            if k == "metadata" and isinstance(v, dict):
+                v = {mk: mv for mk, mv in v.items() if mk != "managedFields"}
+                ann = v.get("annotations")
+                if isinstance(ann, dict):
+                    ann = {a: b for a, b in ann.items() if a not in NOISY_ANNOTATIONS}
+                    if ann:
+                        v["annotations"] = ann
+                    else:
+                        v.pop("annotations", None)
+                out[k] = _strip_noisy(v)
+                continue
+            out[k] = _strip_noisy(v)
+        return out
+    if isinstance(node, list):
+        return [_strip_noisy(x) for x in node]
+    return node
+
+
+def _drop_empty(node):
+    if isinstance(node, dict):
+        out = {}
+        for k, v in node.items():
+            if k == "metadata" and isinstance(v, dict):
+                v = {mk: mv for mk, mv in v.items() if mk not in NOISY_META}
+            v = _drop_empty(v)
+            if v in _EMPTY:
+                continue
+            out[k] = v
+        return out
+    if isinstance(node, list):
+        return [_drop_empty(x) for x in node]
+    return node
+
+
+# -- display helpers for ConfigMaps / Secrets ------------------------------
+
+
+def cap_map_values(obj: dict, limit: int = 2000) -> dict:
+    """Cap long string values in data maps (ConfigMap display) in place."""
+    for key in ("data", "stringData", "binaryData"):
+        m = obj.get(key)
+        if not isinstance(m, dict):
+            continue
+        for k, v in list(m.items()):
+            if isinstance(v, str) and len(v) > limit:
+                m[k] = v[:limit] + f" ...[truncated {len(v) - limit} of {len(v)} chars; -v to see full]"
+    return obj
+
+
+def redact_map_values(obj: dict) -> dict:
+    """Hide secret values in place; keys and sizes stay visible."""
+    for key in ("data", "stringData", "binaryData"):
+        m = obj.get(key)
+        if not isinstance(m, dict):
+            continue
+        obj[key] = {k: (f"<{len(v)} chars hidden -- use --reveal>" if isinstance(v, str) else v) for k, v in m.items()}
+    return obj
+
+
+def reveal_map_values(obj: dict) -> dict:
+    """Base64-decode secret data values in place (binary values stay encoded)."""
+    m = obj.get("data")
+    if isinstance(m, dict):
+        out = {}
+        for k, v in m.items():
+            if not isinstance(v, str):
+                out[k] = v
+                continue
+            try:
+                raw = base64.b64decode(v)
+            except Exception:
+                out[k] = v
+                continue
+            try:
+                out[k] = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                out[k] = f"<{len(raw)} bytes binary; base64: {v[:100]}>"
+        obj["data"] = out
+    return obj

kube_query/cli.py

@@ -0,0 +1,81 @@
+"""kq — read-only Kubernetes queries for humans and AI agents."""
+
+from __future__ import annotations
+
+import click
+
+from . import __version__
+from .cli_kit import KqGroup
+from .commands import register
+from .config import Settings
+from .output import FORMATS
+
+EPILOG = """\
+\b
+USAGE PATTERNS
+  kq overview                        cluster snapshot: problems first
+  kq p l [-A|-n NS] [REGEX]          list pods          (d=deploy, n=ns, no=node,
+  kq p NAME / p desc NAME            inspect            sec=secret, cm, svc, ev)
+  kq logs NAME [-c C] [--tail N]     pod logs           kq tree deploy/NAME
+  kq get RESOURCE[/NAME]             any resource incl. CRDs; kq api lists all
+  kq helm ls -A / kq eso -A          helm releases / ExternalSecret status
+
+\b
+OPTIONS
+  -o yaml|json|rich|md|tree          output (default: compact yaml)
+  -n NS | -A | -l SELECTOR | -f RX   scope: namespace / all / labels / name regex
+  -v (system metadata) -vv (raw)     verbosity
+  --ctx NAME / --kubeconfig PATH     cluster selection
+
+\b
+ROLE
+  kq CAPTURES cluster state for diagnosis; fixing belongs to other tools
+  (kubectl apply, gitops, helm). kq only sends GET requests - it can
+  never create, update or delete anything.
+"""
+
+
+@click.group(
+    cls=KqGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(__version__, "--version", prog_name="kube-query")
+@click.option("--ctx", "--context", "context", default=None, help="Kubeconfig context to use.")
+@click.option("--kubeconfig", default=None, type=click.Path(exists=True), help="Path to a kubeconfig file.")
+@click.option("-n", "--ns", "--namespace", "namespace", default=None, help="Default namespace for this invocation.")
+@click.option(
+    "-A", "--all-namespaces", "all_namespaces", is_flag=True, default=False, help="All namespaces (where applicable)."
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_fmt",
+    type=click.Choice(FORMATS),
+    default=None,
+    help="Output format: yaml, json, rich, md, tree. [env: KQ_OUTPUT]",
+)
+@click.option("-v", "--verbose", count=True, help="Verbosity: -v keep system metadata, -vv raw object.")
+@click.pass_context
+def main(ctx, context, kubeconfig, namespace, all_namespaces, output_fmt, verbose):
+    """kq - read-only Kubernetes queries for AI agents and humans.
+
+    Compact yaml by default; rich tables, markdown, json and ownership
+    trees on request. Built-ins, shortnames, CRDs, Helm releases and
+    External Secrets Operator. Start with: kq overview
+    """
+    ctx.obj = Settings(
+        context=context,
+        kubeconfig=kubeconfig,
+        namespace=namespace,
+        output=output_fmt,
+        verbose=verbose,
+        all_namespaces=all_namespaces,
+    )
+
+
+main.epilog = EPILOG
+register(main)
+
+
+if __name__ == "__main__":
+    main()

kube_query/cli_kit.py

@@ -0,0 +1,175 @@
+"""CLI building blocks: alias-hiding groups, resource groups, common options."""
+
+from __future__ import annotations
+
+import click
+
+from .output import FORMATS
+
+
+class KqGroup(click.Group):
+    """A click Group that hides registered aliases from help listings."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._aliases: set[str] = set()
+
+    def add_command(self, cmd, name=None, *, alias: bool = False) -> None:
+        super().add_command(cmd, name)
+        if alias:
+            self._aliases.add(name or cmd.name)
+
+    def list_commands(self, ctx) -> list[str]:
+        return [n for n in self.commands if n not in self._aliases]
+
+
+class ResourceGroup(KqGroup):
+    """A resource group:
+
+    - ``kq pod``           -> runs the default command (ls)
+    - ``kq pod nginx-123`` -> unknown token dispatches to `show` with the name
+    - ``kq pod ls``        -> normal subcommand
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        self.default_command = kwargs.pop("default_command", "ls")
+        super().__init__(*args, **kwargs)
+
+    def get_command(self, ctx, cmd_name):
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None or cmd_name.startswith("-"):
+            return cmd
+        show = super().get_command(ctx, "show")
+        if show is None:
+            return None
+        ctx._implicit_name = cmd_name
+        return show
+
+
+# -- shared option decorators ---------------------------------------------------
+
+
+def output_option(fn):
+    return click.option(
+        "-o",
+        "--output",
+        "output_fmt",
+        type=click.Choice(FORMATS),
+        default=None,
+        help="Output format: yaml (default), json, rich, md, tree. [env: KQ_OUTPUT]",
+    )(fn)
+
+
+def verbose_option(fn):
+    return click.option(
+        "-v",
+        "--verbose",
+        count=True,
+        default=0,
+        help="Verbosity: -v keep system metadata, -vv raw object.",
+    )(fn)
+
+
+def namespace_option(fn):
+    return click.option(
+        "-n",
+        "--ns",
+        "--namespace",
+        "namespace",
+        default=None,
+        help="Namespace (default: current context's namespace).",
+    )(fn)
+
+
+def all_namespaces_option(fn):
+    return click.option(
+        "-A",
+        "--all-namespaces",
+        "all_namespaces",
+        is_flag=True,
+        default=False,
+        help="All namespaces.",
+    )(fn)
+
+
+def selector_options(fn):
+    fn = click.option(
+        "-l",
+        "--selector",
+        "label_selector",
+        default=None,
+        help="Label selector, e.g. app=web,tier=frontend.",
+    )(fn)
+    return click.option(
+        "--field-selector",
+        "field_selector",
+        default=None,
+        help="Field selector, e.g. status.phase=Running.",
+    )(fn)
+
+
+def filter_option(fn):
+    return click.option(
+        "-f",
+        "--filter",
+        "name_filter",
+        default=None,
+        help="Regex filter on object name.",
+    )(fn)
+
+
+def list_options(include_pattern: bool = True):
+    """Options for `ls`-style commands (order matters for help output)."""
+
+    def deco(fn):
+        if include_pattern:
+            fn = click.argument("pattern", required=False)(fn)
+        fn = filter_option(fn)
+        fn = all_namespaces_option(fn)
+        fn = selector_options(fn)
+        fn = namespace_option(fn)
+        fn = verbose_option(fn)
+        return output_option(fn)
+
+    return deco
+
+
+def show_options():
+    """Options for `show`-style commands (NAME may come from group dispatch)."""
+
+    def deco(fn):
+        fn = click.argument("name", required=False)(fn)
+        fn = namespace_option(fn)
+        fn = verbose_option(fn)
+        return output_option(fn)
+
+    return deco
+
+
+def group_options(fn):
+    """Options acceptable directly on a resource group (before the subcommand)."""
+    fn = all_namespaces_option(fn)
+    fn = namespace_option(fn)
+    fn = verbose_option(fn)
+    return output_option(fn)
+
+
+def resolve_show_name(ctx: click.Context, name: str | None) -> str:
+    if name:
+        return name
+    implicit = getattr(getattr(ctx, "parent", None), "_implicit_name", None)
+    if implicit:
+        return implicit
+    raise click.UsageError("Missing NAME.")
+
+
+def merge_group_options(settings, *, namespace=None, output_fmt=None, verbose=0, all_namespaces=False) -> None:
+    """Fold group-level option values into the shared Settings object."""
+    if namespace is not None:
+        settings.namespace = namespace
+    if output_fmt is not None:
+        settings.output = output_fmt
+    if verbose:
+        settings.verbose = max(settings.verbose, verbose)
+    if all_namespaces:
+        settings.all_namespaces = True

kube_query/commands/__init__.py

@@ -0,0 +1,92 @@
+"""Command registry for the kq root group."""
+
+from __future__ import annotations
+
+from .api_resources import api
+from .contexts import make_contexts_group
+from .describe import describe
+from .eso_cmd import eso
+from .events_cmd import ev
+from .get import get
+from .groups import CONFIGMAPS, DEPLOYMENTS, NAMESPACES, NODES, PODS, SECRETS, SERVICES
+from .helm_cmd import make_helm_group
+from .logs import logs
+from .overview import overview
+from .tree_cmd import tree
+from .version import version
+
+
+def register(main) -> None:
+    """Attach all commands and their aliases to the root group."""
+    # triage first
+    main.add_command(overview, "overview")
+    main.add_command(overview, "ov", alias=True)
+    main.add_command(overview, "o", alias=True)
+    main.add_command(overview, "health", alias=True)
+
+    main.add_command(PODS, "pod")
+    main.add_command(PODS, "pods", alias=True)
+    main.add_command(PODS, "p", alias=True)
+    main.add_command(PODS, "po", alias=True)
+
+    main.add_command(NAMESPACES, "ns")
+    main.add_command(NAMESPACES, "namespaces", alias=True)
+    main.add_command(NAMESPACES, "namespace", alias=True)
+    main.add_command(NAMESPACES, "n", alias=True)
+
+    main.add_command(DEPLOYMENTS, "deploy")
+    main.add_command(DEPLOYMENTS, "deployments", alias=True)
+    main.add_command(DEPLOYMENTS, "deployment", alias=True)
+    main.add_command(DEPLOYMENTS, "dep", alias=True)
+    main.add_command(DEPLOYMENTS, "d", alias=True)
+
+    main.add_command(SERVICES, "svc")
+    main.add_command(SERVICES, "services", alias=True)
+    main.add_command(SERVICES, "service", alias=True)
+
+    main.add_command(SECRETS, "secret")
+    main.add_command(SECRETS, "secrets", alias=True)
+    main.add_command(SECRETS, "sec", alias=True)
+
+    main.add_command(CONFIGMAPS, "cm")
+    main.add_command(CONFIGMAPS, "configmaps", alias=True)
+    main.add_command(CONFIGMAPS, "configmap", alias=True)
+
+    main.add_command(NODES, "node")
+    main.add_command(NODES, "nodes", alias=True)
+    main.add_command(NODES, "no", alias=True)
+
+    main.add_command(ev, "ev")
+    main.add_command(ev, "events", alias=True)
+    main.add_command(ev, "event", alias=True)
+    main.add_command(ev, "e", alias=True)
+
+    main.add_command(logs, "logs")
+    main.add_command(logs, "log", alias=True)
+
+    main.add_command(make_helm_group(), "helm")
+    main.add_command(make_helm_group(), "h", alias=True)
+
+    main.add_command(eso, "eso")
+    main.add_command(eso, "externalsecrets", alias=True)
+
+    main.add_command(make_contexts_group(), "ctx")
+    main.add_command(make_contexts_group(), "contexts", alias=True)
+    main.add_command(make_contexts_group(), "context", alias=True)
+    main.add_command(make_contexts_group(), "c", alias=True)
+
+    main.add_command(get, "get")
+    main.add_command(get, "g", alias=True)
+
+    main.add_command(describe, "describe")
+    main.add_command(describe, "desc", alias=True)
+
+    main.add_command(tree, "tree")
+    main.add_command(tree, "t", alias=True)
+
+    main.add_command(api, "api")
+    main.add_command(api, "api-resources", alias=True)
+    main.add_command(api, "ar", alias=True)
+
+    main.add_command(version, "version")
+    main.add_command(version, "ver", alias=True)

kube_query/commands/_impl.py

@@ -0,0 +1,147 @@
+"""Shared command implementations: list / show rendering used by `get` and the sugar groups."""
+
+from __future__ import annotations
+
+import re
+
+from ..access import get_object, list_objects
+from ..cleanup import compact
+from ..config import Settings
+from ..discovery import ApiResource
+from ..errors import KqError
+from ..output import console, emit_data, note, print_object, render_rows
+from ..summarize import columns_for, dig
+
+
+def effective_namespace(settings: Settings, entry: ApiResource, eff, *, name_given: bool) -> str | None:
+    """Namespace for this call (None => all namespaces when listing)."""
+    if not entry.namespaced:
+        return None
+    if name_given:
+        return eff.namespace or settings.client.default_namespace()
+    if eff.all_namespaces:
+        return None
+    return eff.namespace or settings.client.default_namespace()
+
+
+def apply_filter(items: list[dict], patterns: list[str | None]) -> list[dict]:
+    pats = [p for p in patterns if p]
+    if not pats:
+        return items
+    regexes = []
+    for p in pats:
+        try:
+            regexes.append(re.compile(p, re.IGNORECASE))
+        except re.error as e:
+            raise KqError(f"invalid filter regex '{p}': {e}") from None
+    return [it for it in items if all(rx.search(dig(it, "metadata", "name", default="") or "") for rx in regexes)]
+
+
+def sort_items(items: list[dict]) -> list[dict]:
+    return sorted(
+        items,
+        key=lambda o: (dig(o, "metadata", "namespace", default="") or "", dig(o, "metadata", "name", default="") or ""),
+    )
+
+
+def tabulate(entry: ApiResource, items: list[dict], *, include_ns: bool) -> tuple[list[str], list[dict]]:
+    cols = columns_for(entry.kind)
+    if include_ns:
+        cols = [("NAMESPACE", lambda o: dig(o, "metadata", "namespace", default="") or ""), *cols]
+    headers = [h for h, _ in cols]
+    rows = []
+    for it in items:
+        r = {}
+        for h, fn in cols:
+            try:
+                r[h] = fn(it)
+            except Exception:
+                r[h] = ""
+        rows.append(r)
+    return headers, rows
+
+
+def render_list(settings: Settings, entry: ApiResource, items: list[dict], eff, *, namespace: str | None) -> None:
+    """Render a list of objects in the requested format."""
+    if eff.output in ("yaml", "json"):
+        emit_data([compact(it, eff.verbose) for it in items], eff.output)
+        if not items:
+            where = f" in namespace '{namespace}'" if namespace else ""
+            note(f"no {entry.plural} found{where} (0 items)")
+        return
+
+    if eff.output == "tree":
+        from ..tree import forest_for_items, rich_forest
+
+        forest = forest_for_items(settings.client, entry, items)
+        console().print(rich_forest(forest))
+        return
+
+    include_ns = bool(
+        items
+        and any(dig(o, "metadata", "namespace") for o in items)
+        and (namespace is None or len({dig(o, "metadata", "namespace", default="") or "" for o in items}) > 1)
+    )
+    headers, rows = tabulate(entry, items, include_ns=include_ns)
+    where = f" in namespace '{namespace}'" if namespace else " (all namespaces)"
+    subtitle = f"{len(items)} {entry.plural}{where}"
+
+    if not items:
+        console().print(f"[dim]no {entry.plural} found{where}[/dim]")
+        return
+
+    render_rows(headers, rows, eff.output, title=entry.kind, subtitle=subtitle)
+
+
+def render_single(
+    settings: Settings,
+    entry: ApiResource,
+    name: str,
+    eff,
+    *,
+    transform=None,
+) -> None:
+    """Fetch and render one object (`show`-style)."""
+    ns = effective_namespace(settings, entry, eff, name_given=True)
+    obj = get_object(settings.client, entry, name, namespace=ns)
+
+    if eff.output == "tree":
+        from ..tree import build_forest, rich_forest
+
+        console().print(rich_forest(build_forest(settings.client, entry, obj)))
+        return
+
+    data = compact(obj, eff.verbose)
+    if transform is not None:
+        data = transform(data)
+
+    if eff.output in ("yaml", "json"):
+        emit_data(data, eff.output)
+    elif eff.output in ("rich", "md"):
+        title = f"{entry.kind} {name}" + (f" -n {ns}" if ns else "")
+        print_object(data, eff.output, title=title)
+    else:
+        raise KqError(f"format '{eff.output}' is not supported here")
+
+
+def fetch_list(
+    settings: Settings,
+    entry: ApiResource,
+    eff,
+    *,
+    label_selector: str | None = None,
+    field_selector: str | None = None,
+    pattern: str | None = None,
+    name_filter: str | None = None,
+) -> tuple[list[dict], str | None]:
+    """Resolve namespace, list + filter + sort. Returns (items, namespace)."""
+    ns = effective_namespace(settings, entry, eff, name_given=False)
+    items = list_objects(
+        settings.client,
+        entry,
+        namespace=ns,
+        label_selector=label_selector,
+        field_selector=field_selector,
+    )
+    items = sort_items(apply_filter(items, [pattern, name_filter]))
+    return items, ns