localargo 0.1.0__py3-none-any.whl

localargo/core/catalog.py

@@ -0,0 +1,284 @@
+"""App catalog schema, loader, and profile overlays for LocalArgo."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+import yaml
+
+
+@dataclass
+class AppSpec:  # pylint: disable=too-many-instance-attributes
+    """Declarative app specification loaded from localargo.yaml."""
+
+    name: str
+    repo: str
+    path: str = "."
+    type: Literal["kustomize", "helm"] = "kustomize"
+    namespace: str = "default"
+    project: str = "default"
+    sync_policy: Literal["manual", "auto"] = "manual"
+    helm_values: list[str] = field(default_factory=list)
+    health_timeout: int = 300
+    # Optional: if provided, deployment will be done via `kubectl apply -f` on these files
+    # instead of using the ArgoCD CLI to create/update applications.
+    manifest_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AppState:
+    """Observed state of an ArgoCD application."""
+
+    name: str
+    namespace: str
+    health: Literal["Healthy", "Progressing", "Degraded", "Unknown"]
+    sync: Literal["Synced", "OutOfSync", "Unknown"]
+    revision: str | None = None
+
+
+class CatalogError(ValueError):
+    """Raised on invalid catalog content."""
+
+
+def load_catalog(path: str = "localargo.yaml", profile: str | None = None) -> list[AppSpec]:
+    """Load app catalog, applying optional profile overlay if present."""
+    base: dict[str, Any] = _safe_load_yaml(path)
+    specs = _parse_apps(base)
+    if profile:
+        overlay_path = f"localargo.{profile}.yaml"
+        if os.path.exists(overlay_path):
+            overlay = _safe_load_yaml(overlay_path)
+            specs = _merge_overlays(specs, overlay)
+    _validate(specs)
+    return specs
+
+
+def _safe_load_yaml(path: str) -> dict[str, Any]:
+    if not os.path.exists(path):
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+        if not isinstance(data, dict):
+            msg = "Top-level YAML must be a mapping"
+            raise CatalogError(msg)
+        return data
+
+
+def _parse_apps(data: dict[str, Any]) -> list[AppSpec]:
+    apps_val = data.get("apps", [])
+    if apps_val is None:
+        return []
+    if not isinstance(apps_val, list):
+        msg = "'apps' must be a list"
+        raise CatalogError(msg)
+    specs: list[AppSpec] = []
+    for idx, raw in enumerate(apps_val):
+        specs.append(_build_spec_from_raw(raw, idx))
+    return specs
+
+
+def _merge_overlays(base_specs: list[AppSpec], overlay: dict[str, Any]) -> list[AppSpec]:
+    overlays = overlay.get("apps", [])
+    if not overlays:
+        return base_specs
+    if not isinstance(overlays, list):
+        msg = "overlay 'apps' must be a list"
+        raise CatalogError(msg)
+    by_name: dict[str, AppSpec] = {s.name: s for s in base_specs}
+    for idx, raw in enumerate(overlays):
+        _apply_overlay_to_map(by_name, raw, idx)
+    return list(by_name.values())
+
+
+def _build_spec_from_raw(raw: Any, idx: int) -> AppSpec:
+    if not isinstance(raw, dict):
+        msg = f"apps[{idx}] must be a mapping"
+        raise CatalogError(msg)
+    name = _require_str(raw, "name", idx)
+    repo = _require_str(raw, "repo", idx)
+    path = str(raw.get("path", "."))
+    app_type = _parse_app_type(raw, idx)
+    namespace = str(raw.get("namespace", "default"))
+    project = str(raw.get("project", "default"))
+    sync_policy = _parse_sync_policy(raw, idx)
+    helm_values = _parse_helm_values(raw, idx)
+    health_timeout = _parse_health_timeout(raw)
+    manifest_files = _parse_manifest_files(raw)
+    return AppSpec(
+        name=name,
+        repo=repo,
+        path=path,
+        type=app_type,
+        namespace=namespace,
+        project=project,
+        sync_policy=sync_policy,
+        helm_values=[str(v) for v in helm_values],
+        health_timeout=health_timeout,
+        manifest_files=manifest_files,
+    )
+
+
+def _parse_app_type(raw: dict[str, Any], idx: int) -> Literal["kustomize", "helm"]:
+    app_type = raw.get("type", "kustomize")
+    if app_type not in ("kustomize", "helm"):
+        msg = f"apps[{idx}].type must be 'kustomize' or 'helm'"
+        raise CatalogError(msg)
+    return cast(Literal["kustomize", "helm"], app_type)
+
+
+def _parse_sync_policy(raw: dict[str, Any], idx: int) -> Literal["manual", "auto"]:
+    policy = raw.get("syncPolicy", "manual")
+    if policy not in ("manual", "auto"):
+        msg = f"apps[{idx}].syncPolicy must be 'manual' or 'auto'"
+        raise CatalogError(msg)
+    return cast(Literal["manual", "auto"], policy)
+
+
+def _parse_helm_values(raw: dict[str, Any], idx: int) -> list[str]:
+    helm_values = raw.get("helmValues", []) or []
+    if not isinstance(helm_values, list) or not all(
+        isinstance(v, str | os.PathLike) for v in helm_values
+    ):
+        msg = f"apps[{idx}].helmValues must be a list of strings"
+        raise CatalogError(msg)
+    return [str(v) for v in helm_values]
+
+
+def _parse_health_timeout(raw: dict[str, Any]) -> int:
+    return int(raw.get("healthTimeout", 300))
+
+
+def _normalize_manifest_files(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list) and all(isinstance(v, str | os.PathLike) for v in value):
+        return [str(v) for v in value]
+    msg = "manifest files must be a list of strings"
+    raise CatalogError(msg)
+
+
+def _parse_manifest_files(raw: dict[str, Any]) -> list[str]:
+    # Support both snake_case and camelCase
+    vals = []
+    if "manifest_files" in raw and raw["manifest_files"] is not None:
+        vals.extend(_normalize_manifest_files(raw["manifest_files"]))
+    if "manifestFiles" in raw and raw["manifestFiles"] is not None:
+        vals.extend(_normalize_manifest_files(raw["manifestFiles"]))
+    return vals
+
+
+def _apply_overlay_to_map(by_name: dict[str, AppSpec], raw: Any, idx: int) -> None:
+    if not isinstance(raw, dict):
+        msg = f"overlay apps[{idx}] must be a mapping"
+        raise CatalogError(msg)
+    name = _require_str(raw, "name", idx)
+    base = by_name.get(name)
+    if not base:
+        merged_list = _parse_apps({"apps": [raw]})
+        if merged_list:
+            by_name[name] = merged_list[0]
+        return
+    _apply_overlay_to_spec(base, raw)
+
+
+def _apply_overlay_to_spec(base: AppSpec, raw: dict[str, Any]) -> None:
+    _overlay_repo(base, raw)
+    _overlay_path(base, raw)
+    _overlay_type(base, raw)
+    _overlay_namespace(base, raw)
+    _overlay_project(base, raw)
+    _overlay_sync_policy(base, raw)
+    _overlay_helm_values(base, raw)
+    _overlay_health_timeout(base, raw)
+    _overlay_manifest_files(base, raw)
+
+
+def _overlay_repo(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "repo" in raw:
+        base.repo = str(raw["repo"])
+
+
+def _overlay_path(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "path" in raw:
+        base.path = str(raw["path"])
+
+
+def _overlay_type(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "type" in raw:
+        if raw["type"] not in ("kustomize", "helm"):
+            msg = "overlay type must be 'kustomize' or 'helm'"
+            raise CatalogError(msg)
+        base.type = cast(Literal["kustomize", "helm"], raw["type"])
+
+
+def _overlay_namespace(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "namespace" in raw:
+        base.namespace = str(raw["namespace"])
+
+
+def _overlay_project(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "project" in raw:
+        base.project = str(raw["project"])
+
+
+def _overlay_sync_policy(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "syncPolicy" in raw:
+        policy = raw["syncPolicy"]
+        if policy not in ("manual", "auto"):
+            msg = "overlay syncPolicy must be 'manual' or 'auto'"
+            raise CatalogError(msg)
+        base.sync_policy = cast(Literal["manual", "auto"], policy)
+
+
+def _overlay_helm_values(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "helmValues" in raw:
+        base.helm_values = _normalize_overlay_helm_values(raw["helmValues"])
+
+
+def _overlay_health_timeout(base: AppSpec, raw: dict[str, Any]) -> None:
+    if "healthTimeout" in raw:
+        base.health_timeout = int(raw["healthTimeout"])
+
+
+def _overlay_manifest_files(base: AppSpec, raw: dict[str, Any]) -> None:
+    # Merge manifest files if present in overlay
+    files = []
+    if "manifest_files" in raw:
+        files.extend(_normalize_manifest_files(raw["manifest_files"]))
+    if "manifestFiles" in raw:
+        files.extend(_normalize_manifest_files(raw["manifestFiles"]))
+    if files:
+        base.manifest_files = files
+
+
+def _normalize_overlay_helm_values(value: Any) -> list[str]:
+    hv = value or []
+    if not isinstance(hv, list):
+        msg = "overlay helmValues must be a list of strings"
+        raise CatalogError(msg)
+    for v in hv:
+        if not isinstance(v, str | os.PathLike):
+            msg = "overlay helmValues must be a list of strings"
+            raise CatalogError(msg)
+    return [str(v) for v in hv]
+
+
+def _validate(specs: list[AppSpec]) -> None:
+    seen: set[str] = set()
+    for s in specs:
+        if not s.name or not s.repo:
+            msg = "Each app requires non-empty 'name' and 'repo'"
+            raise CatalogError(msg)
+        if s.name in seen:
+            msg = f"Duplicate app name: {s.name}"
+            raise CatalogError(msg)
+        seen.add(s.name)
+
+
+def _require_str(raw: dict[str, Any], key: str, idx: int) -> str:
+    if key not in raw or raw[key] is None or str(raw[key]).strip() == "":
+        msg = f"apps[{idx}].{key} is required"
+        raise CatalogError(msg)
+    return str(raw[key])

localargo/core/cluster.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Core cluster management functionality."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from localargo.logging import logger
+from localargo.providers.k3s import K3sProvider
+from localargo.providers.kind import KindProvider
+from localargo.utils.cli import check_cli_availability, run_subprocess
+
+if TYPE_CHECKING:
+    from localargo.providers.base import ClusterProvider
+
+
+class ClusterManager:
+    """High-level cluster management operations."""
+
+    PROVIDERS: ClassVar[dict[str, type[ClusterProvider]]] = {
+        "kind": KindProvider,
+        "k3s": K3sProvider,
+    }
+
+    def __init__(self) -> None:
+        self.providers = {name: cls() for name, cls in self.PROVIDERS.items()}
+
+    def get_available_providers(self) -> list[str]:
+        """Get list of available (installed) providers."""
+        return [name for name, provider in self.providers.items() if provider.is_available()]
+
+    def get_provider(self, name: str) -> ClusterProvider:
+        """Get a provider instance by name."""
+        if name not in self.providers:
+            msg = f"Unknown provider: {name}"
+            raise ValueError(msg)
+        return self.providers[name]
+
+    def create_cluster(
+        self, provider_name: str, cluster_name: str = "localargo", **kwargs: Any
+    ) -> bool:
+        """Create a cluster using the specified provider."""
+        provider = self.get_provider(provider_name)
+        provider.name = cluster_name
+        return provider.create_cluster(**kwargs)
+
+    def delete_cluster(self, provider_name: str, cluster_name: str | None = None) -> bool:
+        """Delete a cluster using the specified provider."""
+        provider = self.get_provider(provider_name)
+        return provider.delete_cluster(cluster_name)
+
+    def get_cluster_status(
+        self, provider_name: str | None = None, cluster_name: str | None = None
+    ) -> dict[str, Any]:
+        """Get cluster status. If provider not specified, check current context."""
+        if provider_name:
+            provider = self.get_provider(provider_name)
+            return provider.get_cluster_status(cluster_name)
+
+        # Try to detect current cluster provider from context
+        try:
+            kubectl_path = check_cli_availability("kubectl")
+            if not kubectl_path:
+                return {}
+            result = run_subprocess(
+                [kubectl_path, "config", "current-context"],
+            )
+            current_context = result.stdout.strip()
+
+            # Try to identify provider from context name
+            for provider in self.providers.values():
+                if current_context.startswith(f"{provider.provider_name}-"):
+                    status = provider.get_cluster_status()
+                    status["detected_from_context"] = True
+                    return status
+        except subprocess.CalledProcessError:
+            return {
+                "provider": "none",
+                "name": "none",
+                "context": "none",
+                "exists": False,
+                "ready": False,
+                "error": "kubectl not available or no current context",
+            }
+
+        # Fallback: generic status - only if try succeeds but no provider found
+        return {
+            "provider": "unknown",
+            "name": "unknown",
+            "context": current_context,
+            "exists": True,
+            "ready": True,
+            "detected_from_context": True,
+        }
+
+    def list_clusters(self) -> list[dict[str, Any]]:
+        """List all clusters across all providers."""
+        clusters = []
+
+        for provider in self.providers.values():
+            if provider.is_available():
+                try:
+                    status = provider.get_cluster_status()
+                    clusters.append(status)
+                except (subprocess.SubprocessError, OSError) as e:
+                    # Skip clusters we can't get status for
+                    logger.warning(
+                        "Failed to get status for cluster from %s: %s",
+                        provider.provider_name,
+                        e,
+                    )
+                    continue
+
+        return clusters
+
+    def switch_context(self, context_name: str) -> bool:
+        """Switch to a different kubectl context."""
+        try:
+            kubectl_path = check_cli_availability("kubectl")
+            if not kubectl_path:
+                return False
+            run_subprocess(
+                [kubectl_path, "config", "use-context", context_name], check=True
+            )  # Show output for debugging
+        except subprocess.CalledProcessError:
+            return False
+
+        return True
+
+    def get_contexts(self) -> list[str]:
+        """Get list of available kubectl contexts."""
+        try:
+            kubectl_path = check_cli_availability("kubectl")
+            if not kubectl_path:
+                return []
+            result = run_subprocess(
+                [kubectl_path, "config", "get-contexts", "-o", "name"],
+            )
+            contexts = result.stdout.strip().split("\n")
+            return [ctx for ctx in contexts if ctx]  # Filter out empty strings
+        except subprocess.CalledProcessError:
+            return []
+
+
+# Global cluster manager instance
+cluster_manager = ClusterManager()

localargo/core/k8s.py

@@ -0,0 +1,140 @@
+"""Kubernetes helpers for app pod discovery, log streaming, and manifest apply."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess as sp
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from localargo.logging import logger
+from localargo.utils.cli import run_subprocess
+from localargo.utils.proc import run_json, run_stream
+
+
+def _kubeconfig_args(kubeconfig: str | None) -> list[str]:
+    if not kubeconfig:
+        return []
+    # Allow both file paths and directories (ignore directories gracefully)
+    path = Path(kubeconfig)
+    if path.exists() and path.is_file():
+        return ["--kubeconfig", str(path)]
+    return ["--kubeconfig", str(path)]
+
+
+def apply_manifests(files: list[str], *, kubeconfig: str | None = None) -> None:
+    """Apply one or more manifest files using kubectl apply -f.
+
+    Args:
+        files (list[str]): List of file paths (YAML files or directories). Each
+            will be passed to kubectl via repeated -f flags.
+        kubeconfig (str | None): Optional kubeconfig file path. When provided,
+            it's passed to kubectl via --kubeconfig.
+    """
+    if not files:
+        return
+    args: list[str] = ["kubectl", *(_kubeconfig_args(kubeconfig)), "apply"]
+    for f in files:
+        args.extend(["-f", f])
+    logger.info("Applying manifests: %s", ", ".join(files))
+    run_subprocess(args)
+
+
+def ensure_namespace(namespace: str) -> None:
+    """Create namespace if it does not exist."""
+    args = ["kubectl", "get", "ns", namespace, "-o", "name"]
+    result = run_subprocess(args, check=False)
+    if result.returncode != 0:
+        run_subprocess(["kubectl", "create", "ns", namespace])
+
+
+def upsert_secret(namespace: str, secret_name: str, data: dict[str, str]) -> None:
+    """Create or update a generic secret with provided key/value pairs.
+
+    Values are passed from environment; empty values are allowed and result in empty strings.
+    """
+    ensure_namespace(namespace)
+    # Try create
+    base = ["kubectl", "-n", namespace, "create", "secret", "generic", secret_name]
+    for k, v in data.items():
+        base.extend(["--from-literal", f"{k}={v}"])
+    create_result = run_subprocess(base, check=False)
+    if create_result.returncode == 0:
+        return
+
+    # Fallback to kubectl create secret generic --dry-run=client -o yaml | kubectl apply -f -
+    kubectl_path = shutil.which("kubectl")
+    if not kubectl_path:
+        msg = "kubectl not found"
+        raise FileNotFoundError(msg)
+    dry = [
+        kubectl_path,
+        "-n",
+        namespace,
+        "create",
+        "secret",
+        "generic",
+        secret_name,
+        "--dry-run=client",
+        "-o",
+        "yaml",
+    ]
+    for k, v in data.items():
+        dry.extend(["--from-literal", f"{k}={v}"])
+    # Pipe into apply using captured output for safer resource handling
+    dry_result = sp.run(dry, check=True, capture_output=True)
+    sp.run([kubectl_path, "apply", "-f", "-"], check=True, input=dry_result.stdout)
+
+
+if TYPE_CHECKING:  # imported only for type checking
+    from collections.abc import Iterator
+
+
+def list_pods_for_app(app: str, namespace: str) -> list[str]:
+    """List pods associated with an app using common label conventions."""
+    obj = run_json(["kubectl", "get", "pods", "-n", namespace, "-o", "json"])
+    items = obj.get("items", []) if isinstance(obj, dict) else []
+    pods: list[str] = []
+    for item in items:
+        matched = _extract_pod_name_if_matches(item, app)
+        if matched:
+            pods.append(matched)
+    return pods
+
+
+def _matches_app(labels: dict[str, Any], app: str) -> bool:
+    values = [
+        labels.get("app.kubernetes.io/instance"),
+        labels.get("app.kubernetes.io/name"),
+        labels.get("app"),
+        labels.get("argo-app"),
+    ]
+    return any(isinstance(v, str) and v == app for v in values)
+
+
+def _extract_pod_name_if_matches(item: Any, app: str) -> str | None:
+    meta = item.get("metadata", {}) if isinstance(item, dict) else {}
+    name = meta.get("name")
+    labels = meta.get("labels", {}) or {}
+    if isinstance(labels, dict) and _matches_app(labels, app) and isinstance(name, str):
+        return name
+    return None
+
+
+def stream_logs(
+    pod: str,
+    namespace: str,
+    *,
+    container: str | None = None,
+    since: str | None = None,
+    follow: bool = True,
+) -> Iterator[str]:
+    """Stream logs from a pod, yielding lines as strings."""
+    args = ["kubectl", "logs", pod, "-n", namespace]
+    if container:
+        args.extend(["-c", container])
+    if since:
+        args.extend(["--since", since])
+    if follow:
+        args.append("-f")
+    return run_stream(args)

localargo/eyecandy/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+
+#
+# SPDX-License-Identifier: MIT
+
+"""Eyecandy UI abstractions for LocalArgo CLI.
+
+This module provides Rich-based UI abstractions for the LocalArgo CLI,
+including table rendering, progress steps, and enhanced CLI styling.
+"""
+
+from localargo.eyecandy.progress_steps import StepLogger
+from localargo.eyecandy.table_renderer import TableRenderer
+
+__all__ = ["TableRenderer", "StepLogger"]