fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/compose.py

@@ -0,0 +1,484 @@
+"""Docker Compose subprocess wrapper.
+
+Wraps ``docker compose`` (v2) as a thin Python layer.  Every function
+shells out rather than using a Docker SDK so the CLI has zero runtime
+dependency on Docker libraries and works on any system that has the
+``docker`` binary.
+
+Environment and profile arguments are built from the
+:class:`~faden_cli.core.settings.FadenConfig` dataclass so callers
+never need to assemble raw CLI flags.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from faden_cli.core.console import console, error
+
+
+# ── GPU detection ─────────────────────────────────────────────────
+
+_gpu_cache: bool | None = None
+
+
+def has_nvidia_gpu() -> bool:
+    """Return True if an NVIDIA GPU is actually usable by Docker.
+
+    Checks two things:
+      1. The Docker daemon has the ``nvidia`` runtime registered.
+      2. ``nvidia-smi`` succeeds on the host, proving real GPU
+         adapters are present (the runtime alone may be installed
+         in WSL/CI without any physical GPU).
+    """
+    global _gpu_cache  # noqa: PLW0603
+    if _gpu_cache is not None:
+        return _gpu_cache
+
+    docker = shutil.which("docker")
+    if not docker:
+        _gpu_cache = False
+        return False
+
+    # 1. Runtime check
+    try:
+        proc = subprocess.run(
+            [docker, "info", "--format", "{{.Runtimes}}"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10,
+        )
+        if "nvidia" not in (proc.stdout or "").lower():
+            _gpu_cache = False
+            return False
+    except Exception:  # noqa: BLE001
+        _gpu_cache = False
+        return False
+
+    # 2. Actual GPU adapter check
+    smi = shutil.which("nvidia-smi")
+    if not smi:
+        _gpu_cache = False
+        return False
+    try:
+        proc = subprocess.run(
+            [smi, "-L"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10,
+        )
+        _gpu_cache = proc.returncode == 0 and "GPU" in (proc.stdout or "")
+    except Exception:  # noqa: BLE001
+        _gpu_cache = False
+    return _gpu_cache
+
+
+# ── Types ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class ComposeService:
+    """Parsed row from ``docker compose ps --format json``."""
+
+    name: str = ""
+    service: str = ""
+    status: str = ""  # running, exited, created, …
+    health: str = ""  # healthy, unhealthy, starting, ""
+    ports: str = ""
+    state: str = ""
+    exit_code: int = 0
+
+
+@dataclass
+class ComposeContext:
+    """Everything needed to run a compose command."""
+
+    compose_files: list[Path] = field(default_factory=list)
+    env_file: Path | None = None
+    project_dir: Path | None = None
+    profiles: list[str] = field(default_factory=list)
+
+    def base_cmd(self) -> list[str]:
+        """Build the ``docker compose`` prefix with all file/profile flags."""
+        docker = shutil.which("docker")
+        if not docker:
+            error("docker not found on PATH")
+            sys.exit(1)
+
+        cmd: list[str] = [docker, "compose"]
+        for f in self.compose_files:
+            cmd.extend(["-f", str(f)])
+        if self.env_file and Path(str(self.env_file)).exists():
+            cmd.extend(["--env-file", str(self.env_file)])
+        if self.project_dir:
+            cmd.extend(["--project-directory", str(self.project_dir)])
+        for p in self.profiles:
+            cmd.extend(["--profile", p])
+        return cmd
+
+
+# ── Constants ─────────────────────────────────────────────────────
+
+# Base images used in the platform base Dockerfile.  Pre-pulling
+# puts them in the local store so subsequent builds hit cache.
+_BASE_IMAGES = [
+    "python:3.13-slim-bookworm",
+    "ghcr.io/astral-sh/uv:0.9.12",
+]
+
+
+# ── Public API ────────────────────────────────────────────────────
+
+
+def pull_base_images() -> None:
+    """Pre-pull shared base images so BuildKit finds them locally."""
+    docker = shutil.which("docker")
+    if not docker:
+        return
+    for image in _BASE_IMAGES:
+        subprocess.run(  # noqa: S603
+            [docker, "pull", image],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+
+def build_base_image(ctx: ComposeContext, *, no_cache: bool = False) -> int:
+    """Build the shared platform base image via compose.
+
+    Uses the ``faden-base`` service (gated behind the ``_build``
+    profile) so the image lands in the same BuildKit context that
+    subsequent service builds use.
+    """
+    base_ctx = ComposeContext(
+        compose_files=ctx.compose_files,
+        env_file=ctx.env_file,
+        project_dir=ctx.project_dir,
+        profiles=["_build"],
+    )
+    return build(base_ctx, services=["faden-base"], no_cache=no_cache)
+
+
+def _run(
+    cmd: list[str],
+    *,
+    capture: bool = False,
+    check: bool = True,
+    stream: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Execute a command, optionally streaming output to the console."""
+    if stream:
+        # Stream stdout/stderr to terminal in real time
+        result = subprocess.run(cmd, check=False)  # noqa: S603
+        if check and result.returncode != 0:
+            error(f"Command failed with exit code {result.returncode}")
+        return subprocess.CompletedProcess(cmd, result.returncode, "", "")
+
+    return subprocess.run(  # noqa: S603
+        cmd,
+        capture_output=capture,
+        text=True,
+        # Decode explicitly as UTF-8 and never raise.  `text=True` alone
+        # decodes with the locale codec, which on a Windows console is
+        # cp1252: docker output containing any byte outside it (0x8d in a
+        # container name or a progress glyph) killed the reader thread, left
+        # `stdout` as None, and surfaced as `'NoneType' has no attribute
+        # 'strip'` in the caller rather than as a decoding problem.
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+
+
+def up(
+    ctx: ComposeContext,
+    *,
+    services: list[str] | None = None,
+    detach: bool = True,
+    build: bool = False,
+    pull: str = "",
+    wait: bool = False,
+    timeout: int = 0,
+    force_recreate: bool = False,
+    no_deps: bool = False,
+) -> int:
+    """Run ``docker compose up``.
+
+    *pull* accepts ``"always"``, ``"missing"``, or ``"never"``.
+    An empty string (default) leaves Docker Compose to decide.
+    *wait* blocks until services are healthy (implies ``-d``).
+    *timeout* sets the max wait time in seconds (requires *wait*).
+    *force_recreate* recreates containers even if config hasn't changed.
+    *no_deps* starts only *services*, not what they depend on.
+    """
+    cmd = ctx.base_cmd() + ["up"]
+    if detach:
+        cmd.append("-d")
+    if no_deps:
+        cmd.append("--no-deps")
+    if build:
+        cmd.append("--build")
+    if pull:
+        cmd.append(f"--pull={pull}")
+    if force_recreate:
+        cmd.append("--force-recreate")
+    if wait:
+        cmd.append("--wait")
+    if timeout > 0:
+        cmd.append(f"--wait-timeout={timeout}")
+    if services:
+        cmd.extend(services)
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def service_names(ctx: ComposeContext) -> list[str]:
+    """The services this compose setup runs (its active profiles included); empty when compose cannot say."""
+    result = _run(ctx.base_cmd() + ["config", "--services"], capture=True)
+    if result.returncode != 0:
+        return []
+    return [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
+
+
+def down(
+    ctx: ComposeContext,
+    *,
+    volumes: bool = False,
+    remove_orphans: bool = False,
+    rmi: str | None = None,
+) -> int:
+    """Run ``docker compose down``.
+
+    Args:
+        rmi: Remove images. ``"all"`` removes all images, ``"local"``
+             removes only images without a custom tag.
+    """
+    cmd = ctx.base_cmd() + ["down"]
+    if volumes:
+        cmd.append("-v")
+    if remove_orphans:
+        cmd.append("--remove-orphans")
+    if rmi:
+        cmd.extend(["--rmi", rmi])
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def restart(ctx: ComposeContext, *, services: list[str] | None = None) -> int:
+    """Run ``docker compose restart`` for the given services."""
+    cmd = ctx.base_cmd() + ["restart"]
+    if services:
+        cmd.extend(services)
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def pull(ctx: ComposeContext, *, services: list[str] | None = None) -> int:
+    """Run ``docker compose pull``."""
+    cmd = ctx.base_cmd() + ["pull"]
+    if services:
+        cmd.extend(services)
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def build(
+    ctx: ComposeContext,
+    *,
+    services: list[str] | None = None,
+    no_cache: bool = False,
+    pull: bool = False,
+) -> int:
+    """Run ``docker compose build``."""
+    cmd = ctx.base_cmd() + ["build"]
+    if no_cache:
+        cmd.append("--no-cache")
+    if pull:
+        cmd.append("--pull")
+    if services:
+        cmd.extend(services)
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def logs(
+    ctx: ComposeContext,
+    *,
+    services: list[str] | None = None,
+    follow: bool = True,
+    tail: int | None = 100,
+    timestamps: bool = False,
+) -> int:
+    """Run ``docker compose logs``."""
+    cmd = ctx.base_cmd() + ["logs"]
+    if follow:
+        cmd.append("-f")
+    if tail is not None:
+        cmd.extend(["--tail", str(tail)])
+    if timestamps:
+        cmd.append("--timestamps")
+    if services:
+        cmd.extend(services)
+    result = _run(cmd, stream=True)
+    return result.returncode
+
+
+def ps(ctx: ComposeContext) -> list[ComposeService]:
+    """Run ``docker compose ps`` and parse the output."""
+    import json as _json
+
+    cmd = ctx.base_cmd() + ["ps", "--format", "json", "-a"]
+    result = _run(cmd, capture=True)
+    if result.returncode != 0:
+        return []
+
+    services: list[ComposeService] = []
+    for line in result.stdout.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = _json.loads(line)
+            svc = ComposeService(
+                name=obj.get("Name", ""),
+                service=obj.get("Service", ""),
+                status=obj.get("State", obj.get("Status", "")),
+                health=obj.get("Health", ""),
+                ports=obj.get("Publishers", obj.get("Ports", "")),
+                state=obj.get("State", ""),
+                exit_code=obj.get("ExitCode", 0),
+            )
+            # Format ports if it's a list of dicts
+            if isinstance(svc.ports, list):
+                port_strs = []
+                for p in svc.ports:
+                    if isinstance(p, dict) and p.get("PublishedPort"):
+                        port_strs.append(f"{p.get('URL', '0.0.0.0')}:{p['PublishedPort']}→{p['TargetPort']}")
+                svc.ports = ", ".join(port_strs) if port_strs else ""
+            services.append(svc)
+        except (ValueError, KeyError):
+            continue
+    return services
+
+
+def foreign_containers(ctx: ComposeContext) -> list[tuple[str, str]]:
+    """Containers holding a name this compose file gives, made by something else.
+
+    Compose cannot replace a container it did not create: ``up`` stops with
+    "The container name ... is already in use". An upgrade met one -- a
+    Prometheus recreated by hand with ``docker run`` -- after building images
+    for a quarter of an hour. Returns ``(name, made by)`` pairs, where *made
+    by* is the other compose project, or ``""`` for a plain ``docker run``.
+    """
+    config = _run(ctx.base_cmd() + ["config", "--format", "json"], capture=True)
+    if config.returncode != 0:
+        return []
+    try:
+        spec = json.loads(config.stdout or "{}")
+    except ValueError:
+        return []
+    project = spec.get("name", "")
+    wanted = {
+        s.get("container_name")
+        for s in (spec.get("services") or {}).values()
+        if isinstance(s, dict) and s.get("container_name")
+    }
+    docker = shutil.which("docker") or "docker"
+    listed = _run(
+        [docker, "ps", "-a", "--format", '{{.Names}}\t{{.Label "com.docker.compose.project"}}'],
+        capture=True,
+    )
+    found = []
+    for line in (listed.stdout or "").splitlines():
+        name, _, owner = line.partition("\t")
+        if name in wanted and owner != project:
+            found.append((name, owner))
+    return sorted(found)
+
+
+def exec_cmd(
+    ctx: ComposeContext,
+    service: str,
+    command: list[str],
+    *,
+    capture: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``docker compose exec`` on a running service."""
+    cmd = ctx.base_cmd() + ["exec", service, *command]
+    return _run(cmd, capture=capture)
+
+
+def run_cmd(
+    ctx: ComposeContext,
+    service: str,
+    command: list[str],
+    *,
+    capture: bool = False,
+    remove: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``docker compose run`` (one-off container)."""
+    cmd = ctx.base_cmd() + ["run"]
+    if remove:
+        cmd.append("--rm")
+    cmd.extend([service, *command])
+    return _run(cmd, capture=capture)
+
+
+def _resolve_compose_path(cfg: "FadenConfig") -> Path:
+    """Resolve the compose file, falling back to shared/."""
+    primary = cfg.compose_path
+    if primary.exists():
+        return primary
+    # Check inside shared relative to install path
+    for name in ("docker-compose.yaml", "docker-compose.yml"):
+        candidate = cfg.install_path / "shared" / name
+        if candidate.exists():
+            return candidate
+    return primary
+
+
+def build_context_from_config(cfg: "FadenConfig", *, gpu: bool | None = None) -> ComposeContext:
+    """Build a ComposeContext from the current config.
+
+    *gpu* controls whether the GPU overlay is included:
+      - ``None`` (default): auto-detect via :func:`has_nvidia_gpu`
+      - ``True``: force-include the GPU overlay
+      - ``False``: never include the GPU overlay
+    """
+    compose_file = _resolve_compose_path(cfg)
+    files = [compose_file]
+
+    use_gpu = has_nvidia_gpu() if gpu is None else gpu
+    if use_gpu:
+        gpu_overlay = compose_file.parent / "docker-compose.gpu.yaml"
+        if gpu_overlay.exists():
+            files.append(gpu_overlay)
+
+    return ComposeContext(
+        compose_files=files,
+        env_file=cfg.env_path if cfg.env_path.exists() else None,
+        project_dir=compose_file.parent,
+        profiles=list(cfg.profiles),
+    )
+
+
+def build_context_from_paths(
+    compose_file: Path,
+    *,
+    env_file: Path | None = None,
+    project_dir: Path | None = None,
+    profiles: list[str] | None = None,
+    dev_overlay: Path | None = None,
+) -> ComposeContext:
+    """Build a ComposeContext from explicit paths."""
+    files = [compose_file]
+    if dev_overlay and dev_overlay.exists():
+        files.append(dev_overlay)
+    return ComposeContext(
+        compose_files=files,
+        env_file=env_file,
+        project_dir=project_dir or compose_file.parent,
+        profiles=profiles or [],
+    )

faden_cli/core/console.py

@@ -0,0 +1,106 @@
+"""Rich console singleton and shared output helpers.
+
+Provides a single ``Console`` instance used by every command so that
+output is consistent (colours, width, Unicode support).  Helper
+functions wrap common patterns: success/warning/error panels, spinners,
+tables, and key-value displays.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.theme import Theme
+
+_THEME = Theme(
+    {
+        "info": "cyan",
+        "success": "bold green",
+        "warning": "bold yellow",
+        "error": "bold red",
+        "heading": "bold magenta",
+        "muted": "dim",
+    },
+)
+
+console = Console(theme=_THEME)
+
+
+# ── Shorthand helpers ─────────────────────────────────────────────
+
+
+def heading(text: str) -> None:
+    """Print a heading-styled line."""
+    console.print(f"\n[heading]{text}[/heading]")
+
+
+def success(text: str) -> None:
+    """Print a success-styled line."""
+    console.print(f"[success]✓[/success] {text}")
+
+
+def warning(text: str) -> None:
+    """Print a warning-styled line."""
+    console.print(f"[warning]⚠[/warning] {text}")
+
+
+def error(text: str) -> None:
+    """Print an error-styled line."""
+    console.print(f"[error]✗[/error] {text}")
+
+
+def info(text: str) -> None:
+    """Print an info-styled line."""
+    console.print(f"[info]ℹ[/info] {text}")
+
+
+def kv_table(title: str, rows: list[tuple[str, str]]) -> None:
+    """Print a two-column key/value table."""
+    table = Table(title=title, show_header=False, border_style="dim")
+    table.add_column("Key", style="bold", min_width=20)
+    table.add_column("Value")
+    for key, value in rows:
+        table.add_row(key, value)
+    console.print(table)
+
+
+def banner(lines: list[str], *, title: str = "fadenstack", border_style: str = "cyan") -> None:
+    """Print a bordered panel with the given lines."""
+    body = "\n".join(lines)
+    console.print(Panel(body, title=f"[bold]{title}[/bold]", border_style=border_style))
+
+
+def service_table(rows: list[dict[str, str]], *, title: str = "Services") -> None:
+    """Print a services status table.
+
+    Each row dict should have keys: name, status, health, ports, uptime.
+    """
+    table = Table(title=title, border_style="dim")
+    table.add_column("Service", style="bold")
+    table.add_column("Status")
+    table.add_column("Health")
+    table.add_column("Ports", style="cyan")
+    table.add_column("Uptime", style="dim")
+
+    status_styles = {
+        "running": "green",
+        "exited": "red",
+        "created": "yellow",
+        "restarting": "yellow",
+        "paused": "yellow",
+        "removing": "red",
+        "dead": "red",
+    }
+
+    for row in rows:
+        status = row.get("status", "unknown")
+        style = status_styles.get(status, "white")
+        table.add_row(
+            row.get("name", ""),
+            f"[{style}]{status}[/{style}]",
+            row.get("health", ""),
+            row.get("ports", ""),
+            row.get("uptime", ""),
+        )
+    console.print(table)