kubek 0.4.2__py3-none-any.whl

envx/__main__.py

@@ -0,0 +1,18 @@
+import logging
+
+from envx.cli.main import app
+from envx.console import console
+from envx.style import COLOR_WARNING
+
+logging.basicConfig()
+
+
+def deprecated_entry() -> None:
+    console.print(
+        f"[bold {COLOR_WARNING}]Warning:[/] 'envx' has been deprecated, use 'kenvx' instead."
+    )
+    app()
+
+
+if __name__ == "__main__":
+    app()

envx/cli/main.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import enum
+import json
+import subprocess
+from typing import Annotated
+
+import questionary
+import typer
+
+from envx.console import console, print_error
+from envx.kube import (
+    get_available_deployments,
+    get_available_namespaces,
+    get_available_workflowtemplates,
+    get_deployment_envs,
+    get_workflowtemplate_envs,
+)
+from envx.style import COLOR_MUTED, STYLE
+from envx.utils import export_as_dotenv, resolve_namespace, setup_logging
+
+
+class ResourceKind(str, enum.Enum):
+    DEPLOYMENT = "deployment"
+    WORKFLOWTEMPLATE = "workflowtemplate"
+
+
+class ExportFormat(str, enum.Enum):
+    ENV = "env"
+    JSON = "json"
+
+
+app = typer.Typer()
+
+
+def select_resource_kind() -> ResourceKind:
+    selected = questionary.select(
+        "Select a kind:",
+        choices=[
+            questionary.Choice(
+                title="Deployment",
+                value=ResourceKind.DEPLOYMENT,
+                description="(Kubernetes Deployment)",
+            ),
+            questionary.Choice(
+                title="WorkflowTemplate",
+                value=ResourceKind.WORKFLOWTEMPLATE,
+                description="(Argo WorkflowTemplate)",
+            ),
+        ],
+        use_jk_keys=False,
+        style=STYLE,
+    ).ask()
+    if not selected:
+        raise typer.Exit(code=0)
+    return ResourceKind(selected)
+
+
+@app.callback(invoke_without_command=True)
+def get(
+    kind: Annotated[
+        ResourceKind | None,
+        typer.Option(
+            help="Kind of resource to get parameters for. If not provided, you will be prompted to select one.",
+        ),
+    ] = None,
+    namespace: Annotated[
+        str | None,
+        typer.Option(
+            envvar="KENVX_NAMESPACE",
+            help="Kubernetes namespace. If not provided, you will be prompted to select one.",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            help="Name of the resource. If not provided, you will be prompted to select one.",
+        ),
+    ] = None,
+    output: ExportFormat = ExportFormat.ENV,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose", "-v", count=True, help="Verbose output. Use -vv for debug."
+        ),
+    ] = 0,
+):
+    """
+    Get environment variables for a Kubernetes deployment or Argo WorkflowTemplate.
+    """
+    setup_logging(verbose)
+    if kind is None:
+        kind = select_resource_kind()
+
+    try:
+        with console.status(f"[italic {COLOR_MUTED}]Fetching available namespaces…[/]"):
+            namespaces = get_available_namespaces()
+    except subprocess.CalledProcessError as e:
+        print_error(e, "Failed to fetch available namespaces")
+        raise typer.Exit(code=1) from None
+
+    namespace = resolve_namespace(namespace, available_namespaces=namespaces)
+
+    try:
+        with console.status(
+            f"[italic {COLOR_MUTED}]Fetching available {kind.value}s in {namespace}…[/]"
+        ):
+            if kind == ResourceKind.DEPLOYMENT:
+                resources = get_available_deployments(namespace=namespace)
+            else:
+                resources = get_available_workflowtemplates(namespace=namespace)
+    except subprocess.CalledProcessError as e:
+        print_error(
+            e, f"Failed to fetch available {kind.value}s in namespace '{namespace}'"
+        )
+        raise typer.Exit(code=1) from None
+    if not resources:
+        console.print(f"[red]Error: no {kind.value}s found in namespace '{namespace}'")
+        raise typer.Exit(code=1)
+
+    if not name:
+        name = questionary.select(
+            f"Select a {kind.value}:",
+            choices=resources,
+            use_search_filter=True,
+            use_jk_keys=False,
+            style=STYLE,
+        ).ask()
+        if not name:
+            raise typer.Exit(code=0)
+
+    if name not in resources:
+        console.print(
+            f"[red]Error:[/red] {kind.value} '{name}' not found in namespace '{namespace}'."
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        with console.status(
+            f"[italic {COLOR_MUTED}]Fetching environment variables…[/]"
+        ):
+            if kind == ResourceKind.DEPLOYMENT:
+                vals = get_deployment_envs(namespace=namespace, name=name)
+            else:
+                vals = get_workflowtemplate_envs(namespace=namespace, name=name)
+    except subprocess.CalledProcessError as e:
+        print_error(e, f"Failed to fetch environment variables for '{name}'")
+        raise typer.Exit(code=1) from None
+
+    if output == ExportFormat.JSON:
+        formatted = json.dumps(vals, sort_keys=True)
+    elif output == ExportFormat.ENV:
+        formatted = export_as_dotenv(vals=vals, name=name)
+    print(formatted)
+    raise typer.Exit(code=0)
+
+
+if __name__ == "__main__":
+    app()

envx/console.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+
+from rich.console import Console
+from rich.panel import Panel
+
+from envx.style import COLOR_ERROR
+
+console = Console(stderr=True)
+
+logger = logging.getLogger(__name__)
+
+
+def print_error(e: subprocess.CalledProcessError, msg: str) -> None:
+    logger.debug("kubectl error", exc_info=e, stack_info=True)
+    stderr = (e.stderr or "no output").strip()
+    stdout = (e.stdout or "no output").strip()
+    cmd = " ".join(e.cmd)
+    content = "\n".join(
+        [
+            "[dim]stderr:[/dim]",
+            f"[{COLOR_ERROR}]{stderr}[/]",
+            "",
+            "[dim]stdout:[/dim]",
+            stdout,
+            "",
+            f"[dim]command:[/dim] {cmd}",
+            f"[dim]exit code:[/dim] {e.returncode}",
+        ]
+    )
+    console.print(
+        Panel(
+            content,
+            title=f"[bold {COLOR_ERROR}]{msg}[/]",
+            border_style=COLOR_ERROR,
+            expand=False,
+        )
+    )

envx/kube.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+from collections.abc import Callable
+from functools import lru_cache
+from typing import Any
+
+from envx.utils import decode
+
+logger = logging.getLogger(__name__)
+
+
+def call_subprocess(cmd: list[str]) -> str:
+    logger.debug("%s", " ".join(cmd))
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+def get_available_namespaces() -> list[str]:
+    cmd = ["kubectl", "get", "namespaces", "-o", "json"]
+    result = call_subprocess(cmd)
+    data = json.loads(result)
+    return [el["metadata"]["name"] for el in data["items"]]
+
+
+@lru_cache
+def get_secret(namespace: str, name: str) -> dict[str, Any]:
+    cmd = ["kubectl", "get", "secret", name, "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    secret = json.loads(result)
+    return secret
+
+
+@lru_cache
+def get_configmap(namespace: str, name: str) -> dict[str, Any]:
+    cmd = ["kubectl", "get", "configmap", name, "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    configmap = json.loads(result)
+    return configmap
+
+
+def _clean_key(key: str) -> str:
+    def strip_argo_inputs_param(key: str) -> str:
+        match = re.match(r"^\{\{inputs\.parameters\.(?P<param_name>\w+)\}\}$", key)
+        return match.group("param_name") if match else key
+
+    cleanups: list[Callable[[str], str]] = [
+        strip_argo_inputs_param,
+    ]
+
+    for cleanup in cleanups:
+        key = cleanup(key)
+    return key
+
+
+def get_available_deployments(namespace: str) -> list[str]:
+    cmd = ["kubectl", "get", "deployment", "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    data = json.loads(result)
+    return [el["metadata"]["name"] for el in data["items"]]
+
+
+def get_deployment_envs(namespace: str, name: str) -> dict[str, str]:
+    cmd = ["kubectl", "get", "deployment", name, "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    deployment = json.loads(result)
+    containers = deployment["spec"]["template"]["spec"]["containers"]
+    if len(containers) != 1:
+        raise ValueError(f"Expected 1 container, got {len(containers)}")
+    return extract_envs_from_container(namespace=namespace, container=containers[0])
+
+
+def get_available_workflowtemplates(namespace: str) -> list[str]:
+    cmd = ["kubectl", "get", "workflowtemplate", "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    data = json.loads(result)
+    return [el["metadata"]["name"] for el in data["items"]]
+
+
+def get_workflowtemplate_envs(namespace: str, name: str) -> dict[str, str]:
+    cmd = ["kubectl", "get", "workflowtemplate", name, "-n", namespace, "-o", "json"]
+    result = call_subprocess(cmd)
+    workflow = json.loads(result)
+    envs = {}
+    for template in workflow["spec"]["templates"]:
+        if "container" not in template:
+            continue
+        fallback_keys = {
+            p["name"]: p["default"]
+            for p in template.get("inputs", {}).get("parameters", [])
+            if "default" in p
+        }
+        envs.update(
+            extract_envs_from_container(
+                namespace, template["container"], fallback_keys=fallback_keys
+            )
+        )
+    return envs
+
+
+def extract_envs_from_container(
+    namespace: str,
+    container: dict[str, Any],
+    fallback_keys: dict[str, str] | None = None,
+) -> dict[str, str]:
+    if fallback_keys is None:
+        fallback_keys = {}
+    result = {}
+    if "envFrom" in container:
+        for env_from in container["envFrom"]:
+            if "configMapRef" in env_from:
+                configmap = get_configmap(namespace, env_from["configMapRef"]["name"])
+                result.update(configmap["data"])
+            elif "secretRef" in env_from:
+                secret_name = env_from["secretRef"]["name"]
+                secret = get_secret(namespace, secret_name)
+                encoded = {k: decode(v) for k, v in secret["data"].items()}
+                result.update(encoded)
+            else:
+                raise ValueError(f"Unknown envFrom format: {env_from}")
+
+    if "env" in container:
+        for env in container["env"]:
+            name = env["name"]
+            if "value" in env:
+                value = env["value"]
+                result[name] = value
+            elif "valueFrom" in env:
+                value_from = env["valueFrom"]
+                if "configMapKeyRef" in value_from:
+                    configmap = get_configmap(
+                        namespace, value_from["configMapKeyRef"]["name"]
+                    )
+                    key = value_from["configMapKeyRef"]["key"]
+                    if key not in configmap["data"]:
+                        key = fallback_keys.get(_clean_key(key), key)
+                    if key not in configmap["data"]:
+                        logger.warning(
+                            f"{name} won't be set: key {key} not found in ConfigMap {value_from['configMapKeyRef']['name']}"
+                        )
+                        value = ""
+                    else:
+                        value = configmap["data"][key]
+                    result[name] = value
+                elif "secretKeyRef" in value_from:
+                    secret_name = value_from["secretKeyRef"]["name"]
+                    encoded = get_secret(namespace, secret_name)
+                    key = value_from["secretKeyRef"]["key"]
+                    if key not in encoded["data"]:
+                        key = fallback_keys.get(_clean_key(key), key)
+                    if key not in encoded["data"]:
+                        logger.warning(
+                            f"{name} won't be set: key {key} not found in Secret {secret_name}"
+                        )
+                        value = ""
+                    else:
+                        value = decode(encoded["data"][key])
+                    result[name] = value
+                else:
+                    logger.warning(
+                        f"Unknown valueFrom format: {value_from} for {name} ({env})"
+                    )
+            else:
+                logger.warning(f"Unknown env format: {env}")
+    return result

envx/style.py

@@ -0,0 +1,27 @@
+from questionary import Style
+
+# fmt: off
+COLOR_ACCENT  = "#e5c07b"  # yellow     — draws attention (qmark)
+COLOR_SUCCESS = "#98c379"  # green      — confirmed / selected
+COLOR_ACTIVE  = "#61afef"  # blue       — navigation / pointer
+COLOR_WARNING  = "#d19a66"  # orange     — warnings / cautions
+COLOR_ERROR   = "#e06c75"  # red        — errors / failures
+COLOR_MUTED   = "#5c6370"  # gray       — secondary elements
+COLOR_SUBTLE  = "#4b5263"  # dark gray  — near-invisible hints
+
+# fmt: off
+STYLE = Style(
+    [
+        ("qmark",       f"fg:{COLOR_ACCENT} bold"),
+        ("question",    "bold"),
+        ("answer",      f"fg:{COLOR_SUCCESS} bold"),
+        ("pointer",     f"fg:{COLOR_ACTIVE} bold"),
+        ("highlighted", f"fg:{COLOR_ACTIVE} bold"),
+        ("selected",    f"fg:{COLOR_SUCCESS}"),
+        ("separator",   f"fg:{COLOR_MUTED}"),
+        ("instruction", f"fg:{COLOR_SUBTLE} italic"),
+        ("text",        ""),
+        ("disabled",    f"fg:{COLOR_SUBTLE} italic"),
+    ]
+)
+# fmt: on

envx/utils.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import base64
+import datetime
+import logging
+
+import questionary
+import typer
+
+from envx.console import console
+from envx.style import STYLE
+
+
+def setup_logging(verbose: int) -> None:
+    levels = [logging.WARNING, logging.INFO, logging.DEBUG]
+    level = levels[min(verbose, len(levels) - 1)]
+    logging.getLogger("kenvx").setLevel(level)
+
+
+def decode(val: str) -> str:
+    decoded_bytes = base64.b64decode(val)
+    return decoded_bytes.decode("utf-8")
+
+
+def export_as_dotenv(vals: dict[str, str], name: str | None = None) -> str:
+    sorted_list = sorted(vals.items(), key=lambda x: x[0])
+    res = []
+    if name:
+        now = datetime.datetime.now().isoformat(timespec="seconds")
+        res.append(f"# {name} @ {now}")
+    for key, value in sorted_list:
+        res.append(f"{key}={value}")
+    return "\n".join(res)
+
+
+def resolve_namespace(value: str | None, available_namespaces: list[str]) -> str:
+    if value:
+        if value not in available_namespaces:
+            console.print(f"[red]Error:[/red] namespace '{value}' not found.")
+            raise typer.Exit(code=1)
+        return value
+    selected = questionary.select(
+        "Select a namespace:",
+        choices=available_namespaces,
+        use_search_filter=True,
+        use_jk_keys=False,
+        style=STYLE,
+    ).ask()
+    if not selected:
+        raise typer.Exit(code=0)
+    return selected

kubek/core/__init__.py

@@ -0,0 +1,2 @@
+def foo():
+    print("Hello, World!")

kubek-0.4.2.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: kubek
+Version: 0.4.2
+Summary: kubectl extensions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: kubernetes,kubectl,kubectl plugins,cli,devtools,port forwarding,dotenv
+Author: ohmycoffe
+Author-email: ohmycoffe1@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Dist: psutil (>=7.2.2,<8.0.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Requires-Dist: questionary (>=2.1.1,<3.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: typer (>=0.25.1,<0.26.0)
+Project-URL: Repository, https://github.com/ohmycoffe/kubek
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# kubek
+
+> `kubectl` plugins for friendlier Kubernetes interactions.
+
+**kubek** (**kub**ernetes **e**xtension **k**it) is a collection of CLI tools that plug into `kubectl` and add interactive, developer-friendly shortcuts on top of it.
+
+![CI](https://github.com/ohmycoffe/kubek/actions/workflows/ci.yml/badge.svg?branch=main)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+---
+
+## Plugins
+
+### 🔌 portfwd — Interactive port forwarding
+
+Forwarding ports to Kubernetes services usually means running a separate `kubectl port-forward` command for each service, keeping track of which local port maps to what, and restarting them when they die. **portfwd** (**port** **f**or**w**ar**d**) replaces all of that with a single interactive command — pick your services, and it handles the rest.
+
+- Fuzzy-search namespaces and services interactively
+- Forward multiple services simultaneously in one command
+- Live status table with real-time updates when a process dies
+- Pin preferred local ports per service in a TOML config
+- Fallback to a random free port if the preferred port is taken
+- Inform user which services are currently forwarded and on which ports
+
+![portfwd demo](https://github.com/user-attachments/assets/18e1b913-b1f4-420a-8d76-2a717d604b3e)
+
+→ [Full documentation](kubectl-portfwd/README.md)
+
+---
+
+### 📦 envx — Export env vars from Kubernetes manifests
+
+Getting credentials out of a running deployment usually means digging through `kubectl get deployment -o yaml`, copying values by hand, and reformatting them into a `.env` file. **envx** (**env**ironment e**x**porter) does it in one command — pick any Deployment or Argo WorkflowTemplate you have access to and get its env vars exported instantly.
+
+- Fully interactive (fuzzy-search, arrow key navigation)
+- Output as `.env` or JSON
+- Pipe directly: `kubectl envx ... > .env` to produce a dotenv file
+
+![envx demo](https://github.com/user-attachments/assets/232d778b-77db-4de6-9b79-929a525419d4)
+
+→ [Full documentation](kubectl-envx/README.md)
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- `kubectl` installed and configured with cluster access
+
+### Install
+
+The recommended way to install kubek is with [pipx](https://pipx.pypa.io/), which installs it in an isolated environment and automatically makes the plugin executables available on your PATH:
+
+```bash
+# Latest stable release (recommended)
+pipx install kubek
+
+# Newest development version
+pipx install git+https://github.com/ohmycoffe/kubek.git
+```
+
+If you use pip or another package manager, make sure the installation's `bin/` directory is on your PATH — `kubectl` discovers plugins by scanning PATH for executables prefixed with `kubectl-`.
+
+### Verify
+
+After installing, confirm both plugins are available:
+
+```bash
+kubectl portfwd --help
+kubectl envx --help
+```
+
+See each plugin's README for full usage details.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

kubek-0.4.2.dist-info/RECORD

@@ -0,0 +1,23 @@
+envx/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envx/__main__.py,sha256=zy4aDa0qqhtusydrj3l7q6tbFknmieBUwowwjvJ2vEQ,341
+envx/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envx/cli/main.py,sha256=QyQPQvqo8qkE0BigIB8lEHiBg1vLXj-xtAWB7aAkRLU,4791
+envx/console.py,sha256=wydmFCzm8Ds06PMVlDUghRpHh2sLGM9B_I2tjNBNTCk,987
+envx/kube.py,sha256=k9Tw9EOp9DQXwC878gBDgtLm_c5i8ug0S1_tfX6pDas,6173
+envx/style.py,sha256=HUT5EMqfRm6iCgHI_0tboILmiY0ymnItWFBmCUCsZnM,1019
+envx/utils.py,sha256=ChiptJGd6dHCkvGDE3TUPj-VlR8d20lgBQg2D_3EKJw,1411
+portfwd/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+portfwd/__main__.py,sha256=wIj7vOZPhMebcsUH75upSLO8mwCSpLIZhsGrhczWPsU,110
+portfwd/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+portfwd/cli/main.py,sha256=LZ9anb4AkDJiPZ6E2Yc5f8A0muNdVsICLt4V7Q_a2uY,55
+portfwd/cli/port_forward.py,sha256=noi-qermp-AqeHJSusnVmuop9x13YBf5Zgo4tTR9yG8,12492
+portfwd/config.py,sha256=jDWh5PQgT7QneJ01CQvAqtVusX-7nQ28vlZLOzZKIwc,1573
+portfwd/kube.py,sha256=TQmJNhV8dufSCivumZ2550Ctarixb5fMFZ5ARUdXmak,4993
+portfwd/utils.py,sha256=-xtml3gowadBYEDCXm6OilMM9Sf9gNh_w5DrQGk3jy0,1004
+kubek/core/__init__.py,sha256=tXbbevUzFUeBNiU8nHd6uAu6l9gzSGfU3DM4N8NYovY,38
+kubek/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kubek-0.4.2.dist-info/METADATA,sha256=etlvpYNQitGklOPalwO8Sk9a1xzfA_uSTS9zsGgE5RM,4176
+kubek-0.4.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+kubek-0.4.2.dist-info/entry_points.txt,sha256=sf0FMfRSWIMeOG3ML3QqpcoxwZ29T-tSiOPP997vqjM,123
+kubek-0.4.2.dist-info/licenses/LICENSE,sha256=c7i_EtV17QajV6Vbh1u8MkC6s6SuX-hVCklvc-7PA1I,1066
+kubek-0.4.2.dist-info/RECORD,,

kubek-0.4.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

kubek-0.4.2.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+envx=envx.__main__:deprecated_entry
+kubectl-envx=envx.__main__:app
+kubectl-portfwd=portfwd.__main__:app
+

kubek-0.4.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ohmycoffe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

portfwd/__main__.py

@@ -0,0 +1,8 @@
+import logging
+
+from portfwd.cli.main import app
+
+logging.basicConfig()
+
+if __name__ == "__main__":
+    app()

portfwd/cli/main.py

@@ -0,0 +1 @@
+from portfwd.cli.port_forward import app  # noqa: F401

portfwd/cli/port_forward.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import questionary
+import typer
+from prompt_toolkit.styles import Style
+from questionary.constants import DEFAULT_QUESTION_PREFIX
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+
+from portfwd.config import DEFAULT_CONFIG_PATH, ServiceConfig, load_config
+from portfwd.kube import (
+    KubernetesService,
+    PortForwardProcess,
+    RunningPortForward,
+    find_running_port_forwards,
+    get_available_namespaces,
+    get_current_context,
+    get_services,
+    start_port_forward,
+)
+from portfwd.utils import ensure_port
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer()
+console = Console(stderr=True)
+
+
+QMARK_COLOR = "#61afef"
+ANSWER_COLOR = "#98c379"
+POINTER_COLOR = "#61afef"
+SELECTED_COLOR = "#98c379"
+SEPARATOR_COLOR = "#4b5263"
+INSTRUCTION_COLOR = "#4b5263"
+DISABLED_COLOR = "#4b5263"
+
+STYLE = Style(
+    [
+        ("qmark", f"fg:{QMARK_COLOR} bold"),
+        ("question", "bold"),
+        ("answer", f"fg:{ANSWER_COLOR} bold"),
+        ("pointer", f"fg:{POINTER_COLOR} bold"),
+        ("highlighted", f"fg:{POINTER_COLOR} bold"),
+        ("selected", f"fg:{SELECTED_COLOR}"),
+        ("separator", f"fg:{SEPARATOR_COLOR}"),
+        ("instruction", f"fg:{INSTRUCTION_COLOR} italic"),
+        ("text", ""),
+        ("disabled", f"fg:{DISABLED_COLOR} italic"),
+    ]
+)
+
+
+def ensure_local_ports(
+    services: list[KubernetesService],
+    service_configs: list[ServiceConfig],
+    namespace: str,
+) -> list[tuple[KubernetesService, int]]:
+    """Map each service to its assigned local port using config preferences,
+    falling back to any free port.
+    """
+    preferred = {
+        (entry.name, entry.remote_port): entry.local_port
+        for entry in service_configs
+        if entry.namespace == namespace
+    }
+    result = []
+    for svc in services:
+        preferred_port = preferred.get((svc.name, svc.port))
+        port = ensure_port(preferred_port)
+        if preferred_port and port != preferred_port:
+            logger.warning(
+                "Preferred port %d for %s:%d is not available. Using %d instead.",
+                preferred_port,
+                svc.name,
+                svc.port,
+                port,
+            )
+        result.append((svc, port))
+    return result
+
+
+async def watch_processes(
+    processes: list[PortForwardProcess],
+    statuses: dict[str, str],
+    stop_event: asyncio.Event,
+    on_exit: Callable[[], None] = lambda: None,
+) -> None:
+    """Watch started port-forward processes and update statuses when they exit."""
+
+    async def _watch(process: PortForwardProcess) -> None:
+        await process.process.wait()
+        if not stop_event.is_set():
+            statuses[f"{process.service_name}:{process.remote_port}"] = (
+                f"died (exit {process.process.returncode})"
+            )
+            on_exit()
+
+    async with asyncio.TaskGroup() as tg:
+        for proc in processes:
+            tg.create_task(_watch(proc))
+
+
+def make_table(
+    processes: list[PortForwardProcess],
+    statuses: dict[str, str],
+    namespace: str,
+    context: str | None,
+) -> Table:
+    """Build the Rich status table for the currently running port-forwards."""
+    context_str = f" [dim]({context})[/dim]" if context else ""
+    table = Table(
+        title=f"[bold]Port Forwards[/bold] — [cyan]{namespace}[/cyan]{context_str}",
+        caption="[dim]Press [bold]Ctrl+C[/bold] to stop[/dim]",
+        border_style="bright_black",
+        show_lines=False,
+    )
+    table.add_column("Service", style="bold", no_wrap=True)
+    table.add_column("Remote", style="cyan", justify="right")
+    table.add_column("Local", style="cyan", justify="right")
+    table.add_column("PID", style="dim", justify="right")
+    table.add_column("Status")
+    for fwd in processes:
+        key = f"{fwd.service_name}:{fwd.remote_port}"
+        raw = statuses.get(key, "live")
+        if raw == "live":
+            status = "[green]● live[/green]"
+        elif raw == "stopped":
+            status = "[yellow]■ stopped[/yellow]"
+        else:
+            status = f"[red]✗ {raw}[/red]"
+        table.add_row(
+            fwd.service_name,
+            f":{fwd.remote_port}",
+            f"localhost:{fwd.local_port}",
+            str(fwd.process.pid),
+            status,
+        )
+    return table
+
+
+async def run_port_forwards(
+    namespace: str,
+    services: list[KubernetesService],
+    service_configs: list[ServiceConfig],
+    context: str | None,
+) -> None:
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+    processes: list[PortForwardProcess] = []
+    statuses: dict[str, str] = {}
+
+    for service, port in ensure_local_ports(services, service_configs, namespace):
+        process = await start_port_forward(namespace, service.name, port, service.port)
+        processes.append(process)
+        statuses[f"{service.name}:{service.port}"] = "live"
+
+    if not processes:
+        return
+
+    with Live(
+        renderable=make_table(processes, statuses, namespace, context),
+        console=console,
+        refresh_per_second=1,
+    ) as live:
+
+        def refresh() -> None:
+            live.update(make_table(processes, statuses, namespace, context))
+
+        def cleanup() -> None:
+            stop_event.set()
+            for proc in processes:
+                try:
+                    proc.process.terminate()
+                    statuses[f"{proc.service_name}:{proc.remote_port}"] = "stopped"
+                except ProcessLookupError:
+                    pass
+            refresh()
+
+        loop.add_signal_handler(signal.SIGINT, cleanup)
+        loop.add_signal_handler(signal.SIGTERM, cleanup)
+
+        await watch_processes(
+            processes=processes,
+            statuses=statuses,
+            stop_event=stop_event,
+            on_exit=refresh,
+        )
+
+
+def __get_title(service: KubernetesService) -> str:
+    return f"{service.name}  :{service.port}  {service.protocol}"
+
+
+def __get_key(service: KubernetesService) -> tuple[str, int]:
+    return (service.name, service.port)
+
+
+def build_service_choices(
+    available_services: list[KubernetesService],
+    running_port_forwards: list[RunningPortForward],
+) -> list[questionary.Choice]:
+    """Build the questionary choice list for service selection,
+    marking already-forwarded services as disabled.
+    """
+    ports = {(r.name, r.remote_port): r.local_port for r in running_port_forwards}
+
+    choices: list[questionary.Choice] = []
+
+    inactive = [svc for svc in available_services if __get_key(svc) not in ports]
+    for svc in inactive:
+        title = __get_title(svc)
+        choices.append(questionary.Choice(title=title, value=svc))
+
+    active = [svc for svc in available_services if __get_key(svc) in ports]
+    for svc in active:
+        title = __get_title(svc)
+        disabled = f"already forwarded → localhost:{ports[__get_key(svc)]}"
+        choices.append(questionary.Choice(title=title, value=svc, disabled=disabled))
+
+    return sorted(choices, key=lambda c: str(c.title))
+
+
+def select_services(
+    available_services: list[KubernetesService],
+    running_port_forwards: list[RunningPortForward],
+) -> list[KubernetesService]:
+    """Interactively prompt the user to select services to port-forward."""
+    choices = build_service_choices(available_services, running_port_forwards)
+    selected: list[KubernetesService] = questionary.checkbox(
+        "Select services to forward:",
+        choices=choices,
+        use_search_filter=True,
+        use_jk_keys=False,
+        style=STYLE,
+    ).ask()
+    return selected
+
+
+def select_namespace(default: str | None, available_namespaces: list[str]) -> str:
+    default = default if default in available_namespaces else None
+
+    selected = questionary.select(
+        "Select a namespace:",
+        choices=available_namespaces,
+        use_search_filter=True,
+        use_jk_keys=False,
+        style=STYLE,
+        default=default,
+    ).ask()
+    if not selected:
+        raise typer.Exit(code=0)
+    return selected
+
+
+def __print_error(e: subprocess.CalledProcessError, msg: str) -> None:
+    stderr = (e.stderr or "").strip()
+    logger.error("Command %s failed [%s]: %s", " ".join(e.cmd), e.returncode, stderr)
+    console.print(
+        Panel(
+            f"[red]{stderr or 'no output'}[/red]",
+            title=f"[bold red]{msg}[/bold red]",
+            border_style="red",
+            expand=False,
+        )
+    )
+
+
+def __setup_logging(verbose: int) -> None:
+    logging_verbosity = [logging.WARNING, logging.INFO, logging.DEBUG]
+    level = logging_verbosity[min(verbose, len(logging_verbosity) - 1)]
+    logging.getLogger("kpf").setLevel(level)
+
+
+@app.callback(invoke_without_command=True)
+def port_forward(
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            envvar="KPF_CONFIG",
+            help=f"Path to TOML config file. Defaults to {DEFAULT_CONFIG_PATH}.",
+        ),
+    ] = None,
+    namespace: Annotated[
+        str | None,
+        typer.Option(
+            "--namespace",
+            "-n",
+            help="Kubernetes namespace to use "
+            "(interactively selected if not provided).",
+        ),
+    ] = None,
+    service: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--service",
+            "-s",
+            help="Service to forward. Can be specified multiple times. "
+            "Skips interactive selection.",
+        ),
+    ] = None,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Verbose output. Use -vv for more detail.",
+        ),
+    ] = 0,
+) -> None:
+    """Interactive kubectl port-forward for Kubernetes services."""
+
+    __setup_logging(verbose)
+
+    context = get_current_context()
+    if context:
+        console.print(f"[dim]Context:[/dim] [cyan]{context}[/cyan]")
+
+    cfg = load_config(config)
+
+    try:
+        with console.status("[bold blue]Fetching namespaces…[/bold blue]"):
+            namespaces = get_available_namespaces()
+    except subprocess.CalledProcessError as e:
+        __print_error(e, "Failed to fetch namespaces using kubectl")
+        raise typer.Exit(code=1) from None
+
+    if namespace is None:
+        namespace = select_namespace(
+            default=cfg.default_namespace, available_namespaces=namespaces
+        )
+    elif namespace not in namespaces:
+        console.print(f"[red]Namespace [bold]{namespace}[/bold] not found.[/red]")
+        raise typer.Exit(code=1)
+    else:
+        console.print(
+            f"[bold {QMARK_COLOR}]{DEFAULT_QUESTION_PREFIX}"
+            f"[/bold {QMARK_COLOR}] [bold]Select a namespace:[/bold]"
+            f" [bold {ANSWER_COLOR}]{namespace}[/bold {ANSWER_COLOR}]"
+        )
+
+    try:
+        with console.status(
+            f"[bold blue]Fetching services in [cyan]{namespace}[/cyan]…[/bold blue]"
+        ):
+            available_services = get_services(namespace)
+    except subprocess.CalledProcessError as e:
+        __print_error(
+            e, f"Failed to fetch services in namespace {namespace} using kubectl"
+        )
+        raise typer.Exit(code=1) from None
+
+    if not available_services:
+        console.print(
+            f"[yellow]No services found in namespace [bold]{namespace}[/bold].[/yellow]"
+        )
+        raise typer.Exit(code=0)
+
+    if service:
+        available_services_map = {s.name: s for s in available_services}
+        not_found = {name for name in service if name not in available_services_map}
+        if not_found:
+            console.print(
+                f"[red]Services not found in namespace "
+                f"[bold]{namespace}[/bold]: {', '.join(not_found)}[/red]"
+            )
+            raise typer.Exit(code=1)
+        selected = [available_services_map[name] for name in service]
+    else:
+        running_services = find_running_port_forwards(available_services)
+        selected = select_services(
+            available_services=available_services,
+            running_port_forwards=running_services,
+        )
+        if not selected:
+            console.print("[yellow]No services selected. Exiting.[/yellow]")
+            raise typer.Exit(code=0)
+    asyncio.run(run_port_forwards(namespace, selected, cfg.ports, context))

portfwd/config.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import logging
+import os
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONFIG_PATH = (
+    Path(
+        os.environ.get(
+            "XDG_CONFIG_HOME",
+            Path.home() / ".config",
+        )
+    )
+    / "kpf"
+    / "config.toml"
+)
+
+
+class ServiceConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1)
+    namespace: str = Field(min_length=1)
+    remote_port: int = Field(ge=1, le=65535)
+    local_port: int = Field(ge=1, le=65535)
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    default_namespace: str | None = None
+    ports: list[ServiceConfig] = []
+
+
+def load_config(path: Path | None) -> Config:
+    if path is None:
+        path = DEFAULT_CONFIG_PATH
+
+    default_config = Config()
+
+    if not path.exists():
+        logger.debug("No config file found at %s, using defaults", path)
+        return default_config
+
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    try:
+        config = Config.model_validate(data)
+        logger.info("Loaded config from %s", path)
+        return config
+    except ValidationError as e:
+        logger.warning(
+            "Failed to parse config file at %s. Using defaults instead. "
+            "To fix this, ensure your config file is valid TOML "
+            "and matches the expected schema.",
+            path,
+        )
+        logger.warning("%s", e)
+
+        return default_config

portfwd/kube.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import subprocess
+from dataclasses import dataclass
+
+import psutil
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class KubernetesService:
+    name: str
+    port: int
+    protocol: str
+
+
+@dataclass
+class RunningPortForward:
+    name: str
+    remote_port: int
+    local_port: int
+    pid: int
+
+
+@dataclass
+class PortForwardProcess:
+    process: asyncio.subprocess.Process
+    local_port: int
+    remote_port: int
+    service_name: str
+
+
+def __call_subprocess(cmd: list[str]) -> str:
+    logger.debug(" ".join(cmd))
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+def parse_context(raw: str) -> str:
+    """Extract cluster name from a kubectl context string,
+    stripping EKS ARN prefix if present.
+    """
+    assert raw is not None, "Context string is empty"
+    context = raw.strip()
+    if context.startswith("arn:aws:eks:"):
+        return context.split("/")[-1]
+    return context
+
+
+def parse_namespaces(raw: str) -> list[str]:
+    """Parse namespace names from `kubectl get namespaces -o json` output."""
+    data = json.loads(raw)
+    return [el["metadata"]["name"] for el in data["items"]]
+
+
+def parse_services(raw: str) -> list[KubernetesService]:
+    """Parse services from `kubectl get services -o json` output,
+    skipping the built-in kubernetes service.
+    """
+    data = json.loads(raw)
+    services: list[KubernetesService] = []
+    for svc in data["items"]:
+        name = svc["metadata"]["name"]
+        if name == "kubernetes":
+            continue
+        for port in svc["spec"]["ports"]:
+            services.append(
+                KubernetesService(
+                    name=name,
+                    port=port["port"],
+                    protocol=port["protocol"],
+                )
+            )
+    return sorted(services, key=lambda x: (x.name, x.port))
+
+
+def get_current_context() -> str:
+    """Get the current kubectl context, extracting cluster name from ARN if present."""
+    return parse_context(__call_subprocess(["kubectl", "config", "current-context"]))
+
+
+def get_available_namespaces() -> list[str]:
+    """Get the list of available Kubernetes namespaces using kubectl."""
+    return parse_namespaces(
+        __call_subprocess(["kubectl", "get", "namespaces", "-o", "json"])
+    )
+
+
+def get_services(namespace: str) -> list[KubernetesService]:
+    """Get the list of services with their ports in the specified namespace."""
+    return parse_services(
+        __call_subprocess(["kubectl", "get", "services", "-n", namespace, "-o", "json"])
+    )
+
+
+def find_running_port_forwards(
+    services: list[KubernetesService],
+) -> list[RunningPortForward]:
+    """Find running kubectl port-forward processes that match the given services."""
+    known_ports = {(svc.name, svc.port) for svc in services}
+
+    kubectl_procs = [
+        proc
+        for proc in psutil.process_iter(["pid", "name", "cmdline"])
+        if proc.info["name"] == "kubectl"
+    ]
+
+    running: list[RunningPortForward] = []
+    for proc in kubectl_procs:
+        cmdline = proc.info["cmdline"]
+        svc_match = re.search(
+            r"(?:svc|service)/(?P<name>[a-zA-Z0-9-]+)", " ".join(cmdline)
+        )
+        if not svc_match:
+            continue
+        service_name = svc_match.group("name")
+
+        for arg in cmdline:
+            port_match = re.fullmatch(r"(?:(?P<local>\d+):)?(?P<remote>\d+)", arg)
+            if not port_match:
+                continue
+            remote_port = int(port_match.group("remote"))
+            local_port = (
+                int(port_match.group("local"))
+                if port_match.group("local")
+                else remote_port
+            )
+            if (service_name, remote_port) in known_ports:
+                running.append(
+                    RunningPortForward(
+                        name=service_name,
+                        remote_port=remote_port,
+                        local_port=local_port,
+                        pid=proc.info["pid"],
+                    )
+                )
+
+    return running
+
+
+async def start_port_forward(
+    namespace: str, service: str, local_port: int, remote_port: int
+) -> PortForwardProcess:
+    """Start a kubectl port-forward process for the specified service and port."""
+    cmd = [
+        "kubectl",
+        "port-forward",
+        f"svc/{service}",
+        f"{local_port}:{remote_port}",
+        "-n",
+        namespace,
+    ]
+    logger.debug(" ".join(cmd))
+    process = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=None,
+    )
+    logger.debug(
+        "Started port forward for %s:%d → localhost:%d [PID: %d]",
+        service,
+        remote_port,
+        local_port,
+        process.pid,
+    )
+    return PortForwardProcess(
+        process=process,
+        local_port=local_port,
+        remote_port=remote_port,
+        service_name=service,
+    )

portfwd/utils.py

@@ -0,0 +1,31 @@
+import socket
+
+
+def is_port_free(port: int) -> bool:
+    """Check if a local port is free by trying to bind to it."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("", port))
+            return True
+        except OSError:
+            return False
+
+
+def find_free_port() -> int:
+    """Find a free local port by binding to port 0,
+    which tells the OS to select an available port.
+    """
+    # TOCTOU: the port is freed before kubectl binds it, so another process
+    # could claim it in the window. Unavoidable without passing a pre-bound
+    # socket, which kubectl does not support.
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+def ensure_port(preferred: int | None) -> int:
+    """Return the preferred port if it's free, otherwise find a free port."""
+    if preferred and is_port_free(preferred):
+        return preferred
+    else:
+        return find_free_port()