kube-pf 0.1.0__tar.gz

kube_pf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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.

kube_pf-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: kube-pf
+Version: 0.1.0
+Summary: Interactive kubectl port-forward CLI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: kubernetes,kubectl,port-forward,cli,devtools
+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 (>=5.9)
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: questionary (>=2.0)
+Requires-Dist: rich (>=13.0)
+Requires-Dist: typer (>=0.9)
+Project-URL: Homepage, https://github.com/ohmycoffe/kube-pf
+Project-URL: Issues, https://github.com/ohmycoffe/kube-pf/issues
+Project-URL: Repository, https://github.com/ohmycoffe/kube-pf
+Description-Content-Type: text/markdown
+
+# kube-pf
+
+> Interactive `kubectl port-forward` — fuzzy-search namespaces and services,
+> forward multiple ports at once, watch a live status table.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+![demo](docs/assets/demo.gif)
+
+---
+
+## Features
+
+- 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
+
+## Quick start
+
+**Install with [pipx](https://pipx.pypa.io/) (recommended)**
+
+```bash
+pipx install kube-pf
+```
+
+Or install from source:
+
+```bash
+pipx install git+https://github.com/ohmycoffe/kube-pf.git
+```
+
+**Requirements:** Python 3.11+, `kubectl` installed and pointing at a cluster.
+
+## Usage
+
+```bash
+kubepf                                      # interactive: pick namespace → pick services
+kubepf -n my-namespace                      # skip namespace prompt
+kubepf -s auth-service -s cache-api        # skip interactive selection, forward specific services
+kubepf -n my-namespace -s auth-service     # non-interactive: namespace + services fully specified
+kubepf --config ~/.config/kpf/config.toml  # use a config file
+kubepf -v / -vv                             # INFO / DEBUG logging
+kubepf --help                               # full option reference
+```
+
+## Configuration
+
+Default path: `~/.config/kpf/config.toml` (or set `KPF_CONFIG`).
+
+```toml
+default_namespace = "kube-public"
+
+[[ports]]
+name        = "auth-service"
+namespace   = "kube-public"
+remote_port = 80
+local_port  = 50000
+
+[[ports]]
+name        = "user-service"
+namespace   = "kube-public"
+remote_port = 8080
+local_port  = 50001
+```
+
+Option precedence: CLI flag → `KPF_CONFIG` env var → config file → built-in default.
+
+## Development
+
+```bash
+poetry install           # install deps
+poetry run kubepf --help
+poetry run pytest        # run unit tests
+```
+
+**Local test cluster with [kind](https://kind.sigs.k8s.io/):**
+
+```bash
+scripts/run-local-cluster.sh  # creates cluster + applies test manifests
+```
+
+**Regenerate demo GIF** (requires [VHS](https://github.com/charmbracelet/vhs)):
+
+```bash
+vhs docs/tapes/demo.tape     # outputs to docs/assets/demo.gif
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

kube_pf-0.1.0/README.md

@@ -0,0 +1,94 @@
+# kube-pf
+
+> Interactive `kubectl port-forward` — fuzzy-search namespaces and services,
+> forward multiple ports at once, watch a live status table.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+![demo](docs/assets/demo.gif)
+
+---
+
+## Features
+
+- 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
+
+## Quick start
+
+**Install with [pipx](https://pipx.pypa.io/) (recommended)**
+
+```bash
+pipx install kube-pf
+```
+
+Or install from source:
+
+```bash
+pipx install git+https://github.com/ohmycoffe/kube-pf.git
+```
+
+**Requirements:** Python 3.11+, `kubectl` installed and pointing at a cluster.
+
+## Usage
+
+```bash
+kubepf                                      # interactive: pick namespace → pick services
+kubepf -n my-namespace                      # skip namespace prompt
+kubepf -s auth-service -s cache-api        # skip interactive selection, forward specific services
+kubepf -n my-namespace -s auth-service     # non-interactive: namespace + services fully specified
+kubepf --config ~/.config/kpf/config.toml  # use a config file
+kubepf -v / -vv                             # INFO / DEBUG logging
+kubepf --help                               # full option reference
+```
+
+## Configuration
+
+Default path: `~/.config/kpf/config.toml` (or set `KPF_CONFIG`).
+
+```toml
+default_namespace = "kube-public"
+
+[[ports]]
+name        = "auth-service"
+namespace   = "kube-public"
+remote_port = 80
+local_port  = 50000
+
+[[ports]]
+name        = "user-service"
+namespace   = "kube-public"
+remote_port = 8080
+local_port  = 50001
+```
+
+Option precedence: CLI flag → `KPF_CONFIG` env var → config file → built-in default.
+
+## Development
+
+```bash
+poetry install           # install deps
+poetry run kubepf --help
+poetry run pytest        # run unit tests
+```
+
+**Local test cluster with [kind](https://kind.sigs.k8s.io/):**
+
+```bash
+scripts/run-local-cluster.sh  # creates cluster + applies test manifests
+```
+
+**Regenerate demo GIF** (requires [VHS](https://github.com/charmbracelet/vhs)):
+
+```bash
+vhs docs/tapes/demo.tape     # outputs to docs/assets/demo.gif
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kube_pf-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "kube-pf"
+version = "0.1.0"
+description = "Interactive kubectl port-forward CLI"
+readme = "README.md"
+authors = [
+    {name = "ohmycoffe",email = "ohmycoffe1@gmail.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["kubernetes", "kubectl", "port-forward", "cli", "devtools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9",
+    "questionary>=2.0",
+    "psutil>=5.9",
+    "pydantic>=2.0",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ohmycoffe/kube-pf"
+Repository = "https://github.com/ohmycoffe/kube-pf"
+Issues = "https://github.com/ohmycoffe/kube-pf/issues"
+
+[project.scripts]
+kubepf = "kubepf.__main__:app"
+
+[tool.poetry]
+packages = [
+    { from = "src", include = "kubepf" },
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.3,<10.0.0)"
+]

kube_pf-0.1.0/src/kubepf/__main__.py

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

kube_pf-0.1.0/src/kubepf/cli/main.py

@@ -0,0 +1 @@
+from kubepf.cli.port_forward import app

kube_pf-0.1.0/src/kubepf/cli/port_forward.py

@@ -0,0 +1,370 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import subprocess
+from pathlib import Path
+from typing import Annotated, Callable
+
+import questionary
+from questionary.constants import DEFAULT_QUESTION_PREFIX
+import typer
+from prompt_toolkit.styles import Style
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+
+from kubepf.utils import ensure_port
+from kubepf.config import DEFAULT_CONFIG_PATH, ServiceConfig, load_config
+from kubepf.kube import (
+    RunningPortForward,
+    KubernetesService,
+    PortForwardProcess,
+    get_available_namespaces,
+    find_running_port_forwards,
+    get_services,
+    start_port_forward,
+    get_current_context,
+)
+
+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 = []
+
+    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 choices
+
+
+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("kubepf").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)
+
+    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}[/bold {QMARK_COLOR}] [bold]Select a namespace:[/bold] [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)
+
+    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 [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))

kube_pf-0.1.0/src/kubepf/config.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import logging
+import tomllib
+from pathlib import Path
+import os
+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

kube_pf-0.1.0/src/kubepf/kube.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass
+import subprocess
+
+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,
+    )

kube_pf-0.1.0/src/kubepf/utils.py

@@ -0,0 +1,29 @@
+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()