pysae-cli-tools 0.1.2__tar.gz

pysae_cli_tools-0.1.2/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: pysae-cli-tools
+Version: 0.1.2
+Summary: Reusable utilities for Pysae Python CLIs (k8s pod dispatch, …).
+License: MIT
+Author: Rémi Alvergnat
+Author-email: remi.alvergnat@pysae.com
+Requires-Python: >=3.11,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typer (>=0.25.1,<0.26.0)
+Project-URL: Homepage, https://gitlab.com/pysae/tools/cli-tools
+Project-URL: Repository, https://gitlab.com/pysae/tools/cli-tools
+Description-Content-Type: text/markdown
+
+# pysae-cli-tools
+
+Reusable utilities for Pysae Python CLIs.
+
+[![PyPI](https://img.shields.io/pypi/v/pysae-cli-tools.svg)](https://pypi.org/project/pysae-cli-tools/)
+
+## Installation
+
+```bash
+pip install pysae-cli-tools
+# or
+poetry add pysae-cli-tools
+```
+
+## What's included
+
+### `pysae_cli_tools.k8s` — run any Typer command in an ephemeral pod
+
+The `@k8s_support` decorator injects three flags into a Typer command —
+`--k8s`, `--k8s-environment {dev|prod}`, `--k8s-from-local-sources` — and
+dispatches the call into a freshly-spawned Kubernetes pod when `--k8s` is set.
+
+It is meant for CLIs that need to run inside the same network as their target
+infrastructure (private-link databases, VPC-only APIs, …) without rewriting the
+command for `kubectl run`.
+
+#### Usage with `build_k8s_support` (recommended)
+
+Most projects share the same `K8sConfig` across every decorated command —
+declare it once and reuse the bound decorator everywhere:
+
+```python
+from pathlib import Path
+
+from typer import Typer
+
+from pysae_cli_tools.k8s import K8sConfig, build_k8s_support
+
+K8S_CONFIG = K8sConfig(
+    default_image="<registry>/<project>:latest",
+    project_root=Path(__file__).resolve().parents[1],
+    copy_paths=("my_pkg", "pyproject.toml", "poetry.lock"),
+    install_script=(
+        "apt-get update -qq && pip install poetry && "
+        "poetry config virtualenvs.create false && "
+        "poetry install --only main --no-interaction"
+    ),
+    forwarded_envvars=("MY_API_KEY", "MY_DB_URI"),
+    redacted_options=("--api-key", "--password"),
+)
+
+k8s_support = build_k8s_support(K8S_CONFIG)
+app = Typer()
+
+
+@app.command()
+@k8s_support()
+def my_command() -> None:
+    ...
+
+
+@app.command()
+@k8s_support(pod_name_prefix="my-second-command")  # override per-command
+def my_second_command() -> None:
+    ...
+```
+
+#### Usage with the explicit form
+
+When you want to use a different config per command, pass it directly:
+
+```python
+from pysae_cli_tools.k8s import K8sConfig, k8s_support
+
+@app.command()
+@k8s_support(config=K8S_CONFIG)
+def my_command() -> None:
+    ...
+```
+
+#### What happens at runtime
+
+When `--k8s` is set on the command line, the decorator:
+
+1. Spawns an ephemeral pod using `K8sConfig.default_image` (or the Dockerfile
+   base image when `--k8s-from-local-sources` is also set).
+2. Forwards every envvar listed in `K8sConfig.forwarded_envvars` from your
+   local shell into the pod's `env` block.
+3. Runs `python -m <your.cli.module> <subcommand> <filtered argv>` inside the
+   pod, with values matching `K8sConfig.redacted_options` masked in the
+   `[K8S] Running:` log line.
+4. Streams stdout/stderr back to your terminal and deletes the pod on exit.
+
+See [`pysae_cli_tools/k8s/config.py`](pysae_cli_tools/k8s/config.py) for the
+complete `K8sConfig` reference.
+
+## Development
+
+```bash
+poetry install
+poetry run pre-commit install
+poetry run pytest
+```
+
+CI publishes a new version to PyPI on every push to `main` — see
+[`.gitlab-ci.yml`](.gitlab-ci.yml). The version is computed from
+`git describe` via `pysae_cli_tools.compute_version`.
+

pysae_cli_tools-0.1.2/README.md

@@ -0,0 +1,107 @@
+# pysae-cli-tools
+
+Reusable utilities for Pysae Python CLIs.
+
+[![PyPI](https://img.shields.io/pypi/v/pysae-cli-tools.svg)](https://pypi.org/project/pysae-cli-tools/)
+
+## Installation
+
+```bash
+pip install pysae-cli-tools
+# or
+poetry add pysae-cli-tools
+```
+
+## What's included
+
+### `pysae_cli_tools.k8s` — run any Typer command in an ephemeral pod
+
+The `@k8s_support` decorator injects three flags into a Typer command —
+`--k8s`, `--k8s-environment {dev|prod}`, `--k8s-from-local-sources` — and
+dispatches the call into a freshly-spawned Kubernetes pod when `--k8s` is set.
+
+It is meant for CLIs that need to run inside the same network as their target
+infrastructure (private-link databases, VPC-only APIs, …) without rewriting the
+command for `kubectl run`.
+
+#### Usage with `build_k8s_support` (recommended)
+
+Most projects share the same `K8sConfig` across every decorated command —
+declare it once and reuse the bound decorator everywhere:
+
+```python
+from pathlib import Path
+
+from typer import Typer
+
+from pysae_cli_tools.k8s import K8sConfig, build_k8s_support
+
+K8S_CONFIG = K8sConfig(
+    default_image="<registry>/<project>:latest",
+    project_root=Path(__file__).resolve().parents[1],
+    copy_paths=("my_pkg", "pyproject.toml", "poetry.lock"),
+    install_script=(
+        "apt-get update -qq && pip install poetry && "
+        "poetry config virtualenvs.create false && "
+        "poetry install --only main --no-interaction"
+    ),
+    forwarded_envvars=("MY_API_KEY", "MY_DB_URI"),
+    redacted_options=("--api-key", "--password"),
+)
+
+k8s_support = build_k8s_support(K8S_CONFIG)
+app = Typer()
+
+
+@app.command()
+@k8s_support()
+def my_command() -> None:
+    ...
+
+
+@app.command()
+@k8s_support(pod_name_prefix="my-second-command")  # override per-command
+def my_second_command() -> None:
+    ...
+```
+
+#### Usage with the explicit form
+
+When you want to use a different config per command, pass it directly:
+
+```python
+from pysae_cli_tools.k8s import K8sConfig, k8s_support
+
+@app.command()
+@k8s_support(config=K8S_CONFIG)
+def my_command() -> None:
+    ...
+```
+
+#### What happens at runtime
+
+When `--k8s` is set on the command line, the decorator:
+
+1. Spawns an ephemeral pod using `K8sConfig.default_image` (or the Dockerfile
+   base image when `--k8s-from-local-sources` is also set).
+2. Forwards every envvar listed in `K8sConfig.forwarded_envvars` from your
+   local shell into the pod's `env` block.
+3. Runs `python -m <your.cli.module> <subcommand> <filtered argv>` inside the
+   pod, with values matching `K8sConfig.redacted_options` masked in the
+   `[K8S] Running:` log line.
+4. Streams stdout/stderr back to your terminal and deletes the pod on exit.
+
+See [`pysae_cli_tools/k8s/config.py`](pysae_cli_tools/k8s/config.py) for the
+complete `K8sConfig` reference.
+
+## Development
+
+```bash
+poetry install
+poetry run pre-commit install
+poetry run pytest
+```
+
+CI publishes a new version to PyPI on every push to `main` — see
+[`.gitlab-ci.yml`](.gitlab-ci.yml). The version is computed from
+`git describe` via `pysae_cli_tools.compute_version`.

pysae_cli_tools-0.1.2/pyproject.toml

@@ -0,0 +1,54 @@
+[tool.poetry]
+name = "pysae-cli-tools"
+version = "0.1.2"
+description = "Reusable utilities for Pysae Python CLIs (k8s pod dispatch, …)."
+authors = ["Rémi Alvergnat <remi.alvergnat@pysae.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://gitlab.com/pysae/tools/cli-tools"
+repository = "https://gitlab.com/pysae/tools/cli-tools"
+packages = [{include = "pysae_cli_tools"}]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<4"
+typer = "^0.25.1"
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "^4.6.0"
+pytest = "^9.0.3"
+pytest-mock = "^3.15.1"
+mypy = "^2.1.0"
+ruff = "^0.15.14"
+black = "^26.5.1"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+ignore = [
+    "C901",
+]
+select = [
+    "B",     # flake8-bugbear
+    "C",     # flake8-comprehensions
+    "E",     # pycodestyle errors
+    "F",     # pyflakes
+    "I",     # isort
+    "UP",    # pyupgrade
+    "W",     # pycodestyle warnings
+]
+
+[tool.mypy]
+packages = "pysae_cli_tools,pysae_cli_tools_tests"
+strict = true
+implicit_reexport = true
+ignore_missing_imports = true
+follow_imports = "silent"
+
+[tool.pytest.ini_options]
+testpaths = ["pysae_cli_tools_tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

pysae_cli_tools-0.1.2/pysae_cli_tools/__init__.py

@@ -0,0 +1,76 @@
+"""Pysae shared utilities for Python CLIs."""
+
+import re
+import subprocess
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+
+def compute_version(build: bool = False) -> str:
+    """Compute the current version from git describe.
+
+    Args:
+        build: If True, return a clean version without .dev suffix (for CI publishing).
+               If False (default), append .dev+g<sha> for non-tagged commits.
+
+    Returns:
+        Version string like "0.2.17" (build) or "0.2.17.dev+gabcdef" (dev).
+    """
+    pkg_dir = Path(__file__).resolve().parent
+    cwd = str(pkg_dir)
+
+    try:
+        desc = subprocess.run(
+            ["git", "describe", "--tags", "--long", "--match", "v*"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=cwd,
+        )
+        if desc.returncode == 0 and desc.stdout.strip():
+            m = re.match(r"^v?(\d+\.\d+\.\d+)-(\d+)-g([0-9a-f]+)$", desc.stdout.strip())
+            if m:
+                base, dist, sha = m.group(1), int(m.group(2)), m.group(3)
+                major, minor, patch = base.split(".")
+                if dist == 0:
+                    return base
+                ver = f"{major}.{minor}.{int(patch) + dist}"
+                return ver if build else f"{ver}.dev+g{sha}"
+
+        count = subprocess.run(
+            ["git", "rev-list", "--count", "HEAD"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=cwd,
+        )
+        sha_short = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=cwd,
+        )
+        c = count.stdout.strip() if count.returncode == 0 else "0"
+        s = sha_short.stdout.strip() if sha_short.returncode == 0 else ""
+        ver = f"0.1.{c}"
+        if build or not s:
+            return ver
+        return f"{ver}.dev+g{s}"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return "0.1.0" if build else "0.1.0.dev"
+
+
+try:
+    __version__ = _pkg_version("pysae-cli-tools")
+    if __version__ == "0.1.0":
+        __version__ = compute_version(build=False)
+except PackageNotFoundError:
+    __version__ = compute_version(build=False)

pysae_cli_tools-0.1.2/pysae_cli_tools/k8s/__init__.py

@@ -0,0 +1,5 @@
+from pysae_cli_tools.k8s.config import K8sConfig as K8sConfig
+from pysae_cli_tools.k8s.config import K8sEnvironment as K8sEnvironment
+from pysae_cli_tools.k8s.runner import build_k8s_support as build_k8s_support
+from pysae_cli_tools.k8s.runner import k8s_support as k8s_support
+from pysae_cli_tools.k8s.runner import run_on_k8s as run_on_k8s

pysae_cli_tools-0.1.2/pysae_cli_tools/k8s/config.py

@@ -0,0 +1,83 @@
+"""Configuration object for the ``@k8s_support`` decorator.
+
+Each project consuming :mod:`pysae_cli_tools.k8s` declares a single
+:class:`K8sConfig` describing its image, source layout and secret-
+handling conventions, then either:
+
+- passes it explicitly: ``@k8s_support(config=CONFIG)``, or
+- pre-binds it once with :func:`build_k8s_support` and uses the
+  returned decorator everywhere: ``@k8s_support()``.
+
+The defaults match the Pysae convention (``dev``/``prod`` envs whose
+value doubles as the kubectl context and namespace). Pass a custom
+``StrEnum`` to :attr:`K8sConfig.environments` to model a different
+layout.
+"""
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class K8sEnvironment(enum.StrEnum):
+    """Default Pysae Kubernetes environments. Value == context == namespace."""
+
+    dev = "dev"
+    prod = "prod"
+
+
+@dataclass(frozen=True)
+class K8sConfig:
+    """Project-level configuration for the k8s dispatch decorator."""
+
+    default_image: str
+    """Container image used by default to spawn the ephemeral pod."""
+
+    project_root: Path
+    """Absolute path to the project root. ``copy_paths`` are resolved relative to it."""
+
+    copy_paths: tuple[str, ...] = ()
+    """Paths under ``project_root`` to copy into the pod when
+    ``--k8s-from-local-sources`` is set. Empty disables that mode."""
+
+    install_script: str | None = None
+    """Bash script to run inside the pod after copying sources
+    (``--k8s-from-local-sources`` mode). Typically installs Poetry, the
+    project, and any extra binaries the deployed image already carries.
+    When ``None``, no bootstrap is performed (the base image must be
+    self-contained)."""
+
+    forwarded_envvars: tuple[str, ...] = ()
+    """Envvar names whose value is propagated from the operator's shell
+    into the pod's ``env`` block (treated as sensitive — redacted in logs)."""
+
+    redacted_options: tuple[str, ...] = ()
+    """CLI option names whose value is masked in the ``[K8S] Running:`` log line."""
+
+    environments: type[enum.Enum] = field(default=K8sEnvironment)
+    """Enum of supported environments. Each member's value is used as
+    both the kubectl context and the namespace."""
+
+    default_environment_value: str = "dev"
+    """Default value used for ``--k8s-environment`` when the operator
+    omits the flag. Must match one of ``environments``' values."""
+
+    default_pod_name_prefix: str = "pysae-cli"
+    """Pod name prefix. Override per-command via ``@k8s_support(pod_name_prefix=...)``."""
+
+    dockerfile_path: Path | None = None
+    """Path to the Dockerfile used to extract the base image in
+    ``--k8s-from-local-sources`` mode. Defaults to ``project_root / "Dockerfile"``."""
+
+    workdir: str = "/app"
+    """Working directory inside the pod. Sources are extracted here in
+    ``--k8s-from-local-sources`` mode."""
+
+    @property
+    def resolved_dockerfile(self) -> Path:
+        return self.dockerfile_path or self.project_root / "Dockerfile"
+
+    @property
+    def default_environment(self) -> enum.Enum:
+        """Resolve ``default_environment_value`` against ``environments``."""
+        return self.environments(self.default_environment_value)

pysae_cli_tools-0.1.2/pysae_cli_tools/k8s/runner.py

@@ -0,0 +1,820 @@
+"""Run any Pysae CLI command in an ephemeral Kubernetes pod.
+
+Two entry points:
+
+- :func:`run_on_k8s` to dispatch programmatically.
+- :func:`k8s_support` (or :func:`build_k8s_support` for a config-bound
+  variant) — a decorator on a Typer command that injects
+  ``--k8s`` / ``--k8s-environment`` / ``--k8s-from-local-sources``
+  options into its signature so they show up in ``<cmd> --help``
+  exactly as if they had been declared by hand. When ``--k8s`` is
+  set, the decorator intercepts the run and dispatches to k8s
+  instead of executing the local body.
+
+Every project-specific knob (image, source layout, forwarded envvars,
+redacted options, …) lives in :class:`K8sConfig` — see its docstring
+for the full contract.
+"""
+
+import atexit
+import enum
+import functools
+import inspect
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import tempfile
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any, NoReturn, TypeVar
+
+from typer import Option
+
+from pysae_cli_tools.k8s.config import K8sConfig
+
+_EXCLUDE_PATTERNS = [
+    "__pycache__",
+    "*.pyc",
+    ".git",
+    "node_modules",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "dist",
+    ".venv",
+]
+
+
+def _collect_forwarded_envvars(config: K8sConfig) -> dict[str, str]:
+    """Return ``KEY -> VALUE`` for every forwarded envvar set locally."""
+    return {
+        key: os.environ[key] for key in config.forwarded_envvars if key in os.environ
+    }
+
+
+# ---------- kubectl helpers --------------------------------------------------
+
+
+def _kubectl(
+    *args: str,
+    context: str | None = None,
+    namespace: str | None = None,
+) -> list[str]:
+    """Build a kubectl command, injecting ``--context``/``--namespace`` when set."""
+    cmd = ["kubectl"]
+    if context is not None:
+        cmd.append(f"--context={context}")
+    if namespace is not None:
+        cmd.append(f"--namespace={namespace}")
+    cmd.extend(args)
+    return cmd
+
+
+def _run(
+    cmd: list[str],
+    *,
+    check: bool = True,
+    capture: bool = False,
+    stream: bool = False,
+    inherit_stdin: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess command with consistent defaults.
+
+    ``inherit_stdin=True`` keeps the parent's stdin attached to the
+    child instead of redirecting to ``/dev/null``. Required when the
+    command is ``kubectl exec -i -t …`` — kubectl needs a real stdin
+    to negotiate the TTY allocation; ``DEVNULL`` would trip the
+    ``Unable to use a TTY - input is not a terminal`` error.
+    """
+    if capture:
+        return subprocess.run(  # noqa: S603
+            cmd, check=check, text=True, capture_output=True
+        )
+    if stream:
+        return subprocess.run(  # noqa: S603
+            cmd,
+            check=check,
+            text=True,
+            stdin=None if inherit_stdin else subprocess.DEVNULL,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+    return subprocess.run(  # noqa: S603
+        cmd,
+        check=check,
+        text=True,
+        stdin=None if inherit_stdin else subprocess.DEVNULL,
+    )
+
+
+# ---------- image resolution ------------------------------------------------
+
+
+def _extract_base_image(dockerfile: Path) -> str:
+    """Extract the production base image from the Dockerfile (``FROM <image> AS prod``).
+
+    Falls back to the first ``FROM`` directive when no ``AS prod`` is found —
+    matches the common single-stage layout.
+    """
+    text = dockerfile.read_text()
+    prod_pattern = re.compile(r"^FROM\s+(\S+).*\bAS\s+prod", re.IGNORECASE)
+    for line in text.splitlines():
+        m = prod_pattern.match(line.strip())
+        if m:
+            return m.group(1)
+    first_pattern = re.compile(r"^FROM\s+(\S+)", re.IGNORECASE)
+    for line in text.splitlines():
+        m = first_pattern.match(line.strip())
+        if m:
+            return m.group(1)
+    msg = f"Could not find any 'FROM ...' directive in {dockerfile}"
+    raise RuntimeError(msg)
+
+
+# ---------- pod lifecycle ---------------------------------------------------
+
+
+def _generate_pod_name(prefix: str) -> str:
+    short_id = uuid.uuid4().hex[:8]
+    return f"{prefix}-{short_id}"
+
+
+def _create_pod(
+    pod_name: str,
+    image: str,
+    *,
+    workdir: str,
+    namespace: str | None = None,
+    context: str | None = None,
+) -> None:
+    """Create an ephemeral pod with ``sleep infinity`` and wait for Ready.
+
+    The ``cluster-autoscaler.kubernetes.io/safe-to-evict: "false"`` annotation
+    prevents the autoscaler from evicting the pod mid-run — restarting on a
+    different node would lose any in-flight state (source uploads, dump streams,
+    etc.) and force the operator to rerun from scratch.
+    """
+    overrides: dict[str, object] = {
+        "apiVersion": "v1",
+        "metadata": {
+            "annotations": {
+                "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
+            },
+        },
+        "spec": {
+            "containers": [
+                {
+                    "name": "worker",
+                    "image": image,
+                    "command": ["sleep", "infinity"],
+                    "workingDir": workdir,
+                }
+            ],
+            "restartPolicy": "Never",
+        },
+    }
+
+    _run(
+        _kubectl(
+            "run",
+            pod_name,
+            f"--image={image}",
+            "--restart=Never",
+            f"--overrides={json.dumps(overrides)}",
+            context=context,
+            namespace=namespace,
+        ),
+    )
+    print(f"  Pod {pod_name} created, waiting for Ready...")
+    _run(
+        _kubectl(
+            "wait",
+            f"pod/{pod_name}",
+            "--for=condition=Ready",
+            "--timeout=120s",
+            context=context,
+            namespace=namespace,
+        ),
+    )
+    print(f"  Pod {pod_name} is Ready.")
+
+
+def _copy_to_pod(
+    pod_name: str,
+    paths: list[str],
+    *,
+    project_root: Path,
+    workdir: str,
+    namespace: str | None = None,
+    context: str | None = None,
+) -> None:
+    """Copy local paths into the pod via tar + ``kubectl cp``."""
+    exclude_args: list[str] = []
+    for pat in _EXCLUDE_PATTERNS:
+        exclude_args.extend(["--exclude", pat])
+
+    paths_to_copy = [p for p in paths if (project_root / p).exists()]
+    if not paths_to_copy:
+        return
+
+    with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=True) as tmp:
+        _run(
+            [
+                "tar",
+                "czf",
+                tmp.name,
+                *exclude_args,
+                "-C",
+                str(project_root),
+                *paths_to_copy,
+            ],
+        )
+        _run(
+            _kubectl(
+                "cp",
+                tmp.name,
+                f"{pod_name}:{workdir}/_sources.tar.gz",
+                "-c",
+                "worker",
+                context=context,
+                namespace=namespace,
+            ),
+        )
+
+    _run(
+        _kubectl(
+            "exec",
+            pod_name,
+            "-c",
+            "worker",
+            "--",
+            "tar",
+            "xzf",
+            f"{workdir}/_sources.tar.gz",
+            "-C",
+            workdir,
+            context=context,
+            namespace=namespace,
+        ),
+    )
+    _run(
+        _kubectl(
+            "exec",
+            pod_name,
+            "-c",
+            "worker",
+            "--",
+            "rm",
+            f"{workdir}/_sources.tar.gz",
+            context=context,
+            namespace=namespace,
+        ),
+    )
+
+
+def _install_dependencies(
+    pod_name: str,
+    install_script: str,
+    *,
+    namespace: str | None = None,
+    context: str | None = None,
+) -> None:
+    """Run the project's bootstrap script inside the pod."""
+    print("  Installing dependencies in pod...")
+    _run(
+        _kubectl(
+            "exec",
+            pod_name,
+            "-c",
+            "worker",
+            "--",
+            "bash",
+            "-c",
+            install_script,
+            context=context,
+            namespace=namespace,
+        ),
+        stream=True,
+    )
+    print("  Dependencies installed.")
+
+
+def _exec_command(
+    pod_name: str,
+    command: list[str],
+    *,
+    stream: bool = True,
+    namespace: str | None = None,
+    context: str | None = None,
+    tty: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Execute a command inside the pod (blocking).
+
+    ``tty=True`` allocates a pseudo-TTY in the pod (``kubectl exec -i -t``)
+    so the command sees an interactive terminal — required for live progress
+    bars and color output. Callers must resolve auto-detection upstream; when
+    ``tty=True`` is passed with a non-TTY local stdin, kubectl fails with
+    ``Unable to use a TTY`` (that surface is intentional).
+    """
+    tty_flags = ["-i", "-t"] if tty else []
+    return _run(
+        _kubectl(
+            "exec",
+            pod_name,
+            *tty_flags,
+            "-c",
+            "worker",
+            "--",
+            *command,
+            context=context,
+            namespace=namespace,
+        ),
+        stream=stream,
+        check=False,
+        inherit_stdin=tty,
+    )
+
+
+def _delete_pod(
+    pod_name: str,
+    *,
+    namespace: str | None = None,
+    context: str | None = None,
+) -> None:
+    """Delete the ephemeral pod."""
+    print(f"\n  Cleaning up pod {pod_name}...")
+    _run(
+        _kubectl(
+            "delete",
+            "pod",
+            pod_name,
+            "--grace-period=5",
+            "--wait=false",
+            context=context,
+            namespace=namespace,
+        ),
+        check=False,
+    )
+    print(f"  Pod {pod_name} deleted.")
+
+
+# ---------- remote command + redaction --------------------------------------
+
+
+def _build_remote_command(
+    cli_module: str,
+    cli_subcommand: str | None,
+    args: list[str],
+    workdir: str,
+    env_overrides: dict[str, str] | None = None,
+) -> list[str]:
+    """Build the ``env … python -m <module> [subcommand] <args>`` command.
+
+    ``PYTHONPATH=<workdir>`` makes the copied project package importable
+    in ``--k8s-from-local-sources`` mode (already on ``sys.path`` in the
+    deployed image where the wheel sits in site-packages, but the explicit
+    prefix is inoffensive there).
+    """
+    cmd = [
+        "env",
+        f"PYTHONPATH={workdir}",
+        "PYTHONUNBUFFERED=1",
+    ]
+    if env_overrides:
+        cmd.extend(f"{key}={value}" for key, value in env_overrides.items())
+    cmd.extend(["python", "-m", cli_module])
+    if cli_subcommand is not None:
+        cmd.append(cli_subcommand)
+    cmd.extend(args)
+    return cmd
+
+
+def _redact_command(
+    cmd: list[str],
+    redacted_options: tuple[str, ...],
+    redacted_env_keys: frozenset[str] = frozenset(),
+) -> list[str]:
+    """Redact sensitive values in a printable form of the command.
+
+    Two sources of sensitivity are masked:
+
+    - Values right after a known sensitive option
+      (``--public-api-key X`` → ``--public-api-key ***``)
+      or as ``--public-api-key=X``.
+    - Env-var assignments whose key is in ``redacted_env_keys``
+      (``MONGO_URI=mongodb+srv://...`` → ``MONGO_URI=***``).
+    """
+    redacted: list[str] = []
+    skip_next = False
+    for arg in cmd:
+        if skip_next:
+            redacted.append("***")
+            skip_next = False
+            continue
+        if arg in redacted_options:
+            redacted.append(arg)
+            skip_next = True
+            continue
+        if any(arg.startswith(f"{opt}=") for opt in redacted_options):
+            prefix = arg.split("=", 1)[0]
+            redacted.append(f"{prefix}=***")
+            continue
+        if "=" in arg and arg.split("=", 1)[0] in redacted_env_keys:
+            prefix = arg.split("=", 1)[0]
+            redacted.append(f"{prefix}=***")
+            continue
+        redacted.append(arg)
+    return redacted
+
+
+# ---------- public dispatch -------------------------------------------------
+
+
+def run_on_k8s(
+    cli_args: list[str],
+    *,
+    config: K8sConfig,
+    cli_module: str,
+    cli_subcommand: str | None = None,
+    environment: str,
+    namespace: str | None = None,
+    context: str | None = None,
+    pod_name_prefix: str | None = None,
+    from_local_sources: bool = False,
+    env_overrides: dict[str, str] | None = None,
+    tty: bool | None = None,
+) -> NoReturn:
+    """Run ``python -m <cli_module> [<cli_subcommand>] <cli_args>`` in an ephemeral pod.
+
+    ``cli_args`` are forwarded verbatim (the caller is responsible for
+    removing any k8s-only flags, see :func:`_filter_k8s_argv`).
+
+    ``tty``: ``None`` (default) inherits from the local stdin —
+    interactive shell → TTY allocated in the pod, CI/pipe → not.
+
+    Exits the current process with the remote command's return code —
+    this function never returns.
+    """
+    resolved_tty = tty if tty is not None else sys.stdin.isatty()
+    if from_local_sources:
+        image = _extract_base_image(config.resolved_dockerfile)
+    else:
+        image = config.default_image
+    resolved_pod_prefix = pod_name_prefix or config.default_pod_name_prefix
+    pod_name = _generate_pod_name(resolved_pod_prefix)
+
+    print(f"[K8S] Using image: {image}")
+    if context:
+        print(f"[K8S] Using context: {context}")
+    if namespace:
+        print(f"[K8S] Using namespace: {namespace}")
+    print(f"[K8S] Creating ephemeral pod: {pod_name}")
+
+    def _cleanup() -> None:
+        _delete_pod(pod_name, namespace=namespace, context=context)
+
+    atexit.register(_cleanup)
+
+    def _signal_handler(signum: int, frame: object) -> None:
+        _cleanup()
+        raise SystemExit(130)
+
+    signal.signal(signal.SIGINT, _signal_handler)
+
+    try:
+        _create_pod(
+            pod_name,
+            image,
+            workdir=config.workdir,
+            namespace=namespace,
+            context=context,
+        )
+
+        if from_local_sources:
+            if not config.copy_paths:
+                msg = (
+                    "--k8s-from-local-sources requires K8sConfig.copy_paths to be set."
+                )
+                raise RuntimeError(msg)
+            print("  Copying sources into pod...")
+            _copy_to_pod(
+                pod_name,
+                list(config.copy_paths),
+                project_root=config.project_root,
+                workdir=config.workdir,
+                namespace=namespace,
+                context=context,
+            )
+            print("  Sources copied.")
+            if config.install_script:
+                _install_dependencies(
+                    pod_name,
+                    config.install_script,
+                    namespace=namespace,
+                    context=context,
+                )
+
+        remote_cmd = _build_remote_command(
+            cli_module,
+            cli_subcommand,
+            cli_args,
+            workdir=config.workdir,
+            env_overrides=env_overrides,
+        )
+        redacted_env_keys = frozenset(env_overrides) if env_overrides else frozenset()
+        print(
+            f"[K8S] Running: "
+            f"{' '.join(_redact_command(remote_cmd, config.redacted_options, redacted_env_keys))}"
+        )
+
+        result = _exec_command(
+            pod_name,
+            remote_cmd,
+            namespace=namespace,
+            context=context,
+            tty=resolved_tty,
+        )
+        result_rc = result.returncode
+
+    finally:
+        _delete_pod(pod_name, namespace=namespace, context=context)
+        atexit.unregister(_cleanup)
+
+    raise SystemExit(result_rc)
+
+
+# ---------- @k8s_support decorator ------------------------------------------
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Sentinel used to distinguish "auto-detect the subcommand from the
+# enclosing Typer app at runtime" from the explicit ``None`` ("force
+# no subcommand on the remote call") and from a string ("force this
+# subcommand name").
+_AUTO_SUBCOMMAND: Any = object()
+
+
+def _detect_subcommand_for(wrapper: Callable[..., Any], module_name: str) -> str | None:
+    """Return the Typer subcommand name to forward to the pod.
+
+    Walks every ``typer.Typer`` instance defined in ``module_name`` and
+    locates the registered command whose underlying callback is the
+    ``wrapper`` produced by :func:`k8s_support`. Returns ``None`` for
+    a single-command app (Typer auto-executes it remotely too), the
+    Typer command name otherwise, with a function-name fallback when
+    no enclosing app is found.
+    """
+    import typer
+
+    fallback = wrapper.__name__.replace("_", "-")
+    module = sys.modules.get(module_name)
+    if module is None:
+        return fallback
+    typer_apps = [obj for obj in vars(module).values() if isinstance(obj, typer.Typer)]
+    for app in typer_apps:
+        for cmd in app.registered_commands:
+            if cmd.callback is wrapper:
+                if len(app.registered_commands) == 1:
+                    return None
+                return cmd.name or fallback
+    return fallback
+
+
+def _filter_k8s_argv(argv: list[str]) -> list[str]:
+    """Strip ``--k8s``, ``--k8s-environment <v>``, ``--k8s-from-local-sources`` from ``argv``.
+
+    Also handles the ``--flag=value`` variants. Used to forward the
+    original CLI args to the pod without the k8s-specific options the
+    pod would not understand.
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a in ("--k8s", "--k8s-from-local-sources"):
+            i += 1
+        elif a == "--k8s-environment":
+            i += 2
+        elif (
+            a.startswith("--k8s=")
+            or a.startswith("--k8s-from-local-sources=")
+            or a.startswith("--k8s-environment=")
+        ):
+            i += 1
+        else:
+            out.append(a)
+            i += 1
+    return out
+
+
+def k8s_support(
+    *,
+    config: K8sConfig,
+    cli_module: str | None = None,
+    cli_subcommand: Any = _AUTO_SUBCOMMAND,
+    pod_name_prefix: str | None = None,
+    tty: bool | None = None,
+) -> Callable[[F], F]:
+    """Inject k8s flags into a Typer command and dispatch when ``--k8s`` is set.
+
+    Applied to a function used as a Typer command body, this decorator
+    rewrites the function's signature to append three keyword-only
+    parameters:
+
+    - ``--k8s`` (bool, default False) — run on Kubernetes instead of locally.
+    - ``--k8s-environment`` (one of ``config.environments``) — target env.
+    - ``--k8s-from-local-sources`` (bool, default False) — copy local
+      sources and reinstall deps instead of using the deployed image
+      (slower, useful when developing).
+
+    Typer reads ``__signature__`` to generate ``--help``, so the three
+    flags appear under the command's own help just like manually
+    declared options. At runtime, if ``--k8s`` is set, the rest of
+    ``sys.argv`` (with the k8s flags filtered out) is forwarded to
+    :func:`run_on_k8s` and the original function body is **not**
+    executed locally.
+
+    Pre-binding ``config`` once
+    --------------------------
+    When most commands in a project share the same config, use
+    :func:`build_k8s_support` to obtain a decorator with ``config``
+    already bound — the per-command application becomes
+    ``@k8s_support()`` with no boilerplate.
+
+    Parameters
+    ----------
+    config:
+        Project configuration. Drives image, source layout, secret
+        forwarding, redaction, and the set of supported environments.
+    cli_module:
+        Dotted path of the module to run inside the pod. Defaults to
+        ``f.__module__`` (with the ``__main__`` fallback).
+    cli_subcommand:
+        Typer subcommand name. Auto-detected at runtime from the
+        enclosing Typer app by default.
+    pod_name_prefix:
+        Override ``config.default_pod_name_prefix`` for this command.
+        Helps disambiguate pods in ``kubectl get pods`` when several
+        commands run concurrently.
+    tty:
+        ``None`` (default) inherits from the local stdin. Set
+        ``True`` / ``False`` to force the behaviour.
+    """
+    environments = config.environments
+    default_environment = config.default_environment
+
+    def decorator(f: F) -> F:
+        resolved_module = cli_module if cli_module is not None else f.__module__
+        # ``python -m foo.bar`` runs the module as ``__main__`` so
+        # ``f.__module__`` reads ``"__main__"`` — but the real dotted
+        # path lives in ``sys.modules["__main__"].__spec__.name``,
+        # populated by the runtime before the module body executes.
+        if resolved_module == "__main__":
+            main_mod = sys.modules.get("__main__")
+            spec = getattr(main_mod, "__spec__", None)
+            if spec is not None and spec.name:
+                resolved_module = spec.name
+            else:
+                msg = (
+                    f"@k8s_support cannot auto-detect cli_module for {f.__qualname__} "
+                    "(no __spec__.name on __main__ — script run directly via "
+                    "``python script.py`` rather than ``python -m <module>``). "
+                    "Pass cli_module=<dotted.path> explicitly."
+                )
+                raise RuntimeError(msg)
+        original_sig = inspect.signature(f)
+
+        k8s_param = inspect.Parameter(
+            "k8s",
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            default=False,
+            annotation=Annotated[
+                bool,
+                Option(
+                    "--k8s",
+                    help=(
+                        "Run the command in an ephemeral pod on the Kubernetes cluster instead of locally."
+                    ),
+                ),
+            ],
+        )
+        k8s_env_param = inspect.Parameter(
+            "k8s_environment",
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            default=default_environment,
+            annotation=Annotated[
+                environments,
+                Option(
+                    "--k8s-environment",
+                    case_sensitive=False,
+                    help="Target Kubernetes environment when --k8s is set.",
+                ),
+            ],
+        )
+        k8s_local_param = inspect.Parameter(
+            "k8s_from_local_sources",
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            default=False,
+            annotation=Annotated[
+                bool,
+                Option(
+                    "--k8s-from-local-sources",
+                    help=(
+                        "When --k8s is set, copy local sources and "
+                        "install deps in the pod instead of using the "
+                        "deployed image (slower, useful when developing)."
+                    ),
+                ),
+            ],
+        )
+        new_params = list(original_sig.parameters.values()) + [
+            k8s_param,
+            k8s_env_param,
+            k8s_local_param,
+        ]
+        new_sig = original_sig.replace(parameters=new_params)
+
+        @functools.wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            k8s = kwargs.pop("k8s", False)
+            k8s_environment: enum.Enum = kwargs.pop(
+                "k8s_environment", default_environment
+            )
+            k8s_from_local_sources = kwargs.pop("k8s_from_local_sources", False)
+            if not k8s:
+                return f(*args, **kwargs)
+
+            if cli_subcommand is _AUTO_SUBCOMMAND:
+                resolved_subcommand = _detect_subcommand_for(wrapper, f.__module__)
+            else:
+                resolved_subcommand = cli_subcommand
+
+            env_value: str = k8s_environment.value
+            env_overrides = _collect_forwarded_envvars(config)
+            run_on_k8s(
+                _filter_k8s_argv(sys.argv[1:]),
+                config=config,
+                cli_module=resolved_module,
+                cli_subcommand=resolved_subcommand,
+                environment=env_value,
+                namespace=env_value,
+                context=env_value,
+                pod_name_prefix=pod_name_prefix,
+                from_local_sources=k8s_from_local_sources,
+                env_overrides=env_overrides,
+                tty=tty,
+            )
+
+        wrapper.__signature__ = new_sig  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def build_k8s_support(config: K8sConfig) -> Callable[..., Callable[[F], F]]:
+    """Return a :func:`k8s_support` decorator pre-bound to ``config``.
+
+    Typical setup at the top of a project's ``cli.py``::
+
+        from pysae_cli_tools.k8s import K8sConfig, build_k8s_support
+
+        K8S_CONFIG = K8sConfig(
+            default_image="...:latest",
+            project_root=Path(__file__).resolve().parents[1],
+            copy_paths=("src", "pyproject.toml", "poetry.lock"),
+            forwarded_envvars=("MY_API_KEY",),
+            redacted_options=("--api-key",),
+        )
+
+        k8s_support = build_k8s_support(K8S_CONFIG)
+
+        @app.command()
+        @k8s_support()
+        def my_command(...): ...
+
+        @app.command()
+        @k8s_support(pod_name_prefix="my-command-2")  # override per-command
+        def my_other_command(...): ...
+    """
+
+    def k8s_support_bound(
+        *,
+        cli_module: str | None = None,
+        cli_subcommand: Any = _AUTO_SUBCOMMAND,
+        pod_name_prefix: str | None = None,
+        tty: bool | None = None,
+    ) -> Callable[[F], F]:
+        return k8s_support(
+            config=config,
+            cli_module=cli_module,
+            cli_subcommand=cli_subcommand,
+            pod_name_prefix=pod_name_prefix,
+            tty=tty,
+        )
+
+    return k8s_support_bound