kctl-lib 0.4.0__tar.gz

kctl_lib-0.4.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.env

kctl_lib-0.4.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: kctl-lib
+Version: 0.4.0
+Summary: Shared core library for kctl-* CLI tools
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.28.0; extra == 'dev'
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: monitor
+Provides-Extra: testing
+Requires-Dist: pytest>=8.3.0; extra == 'testing'

kctl_lib-0.4.0/README.md

@@ -0,0 +1,46 @@
+# kctl-common
+
+Shared core library for all kctl-* CLI tools. Published to PyPI as `kctl-common`.
+
+## Installation
+
+```bash
+# As a dependency (in pyproject.toml)
+dependencies = ["kctl-common>=0.3.1"]
+
+# For development
+cd packages/kctl-common
+uv sync --all-extras
+```
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `api_client.py` | `APIClient` — sync HTTP base client with retry, auth, error mapping |
+| `async_api_client.py` | `AsyncAPIClient` — async HTTP base client with retry, auth, error mapping |
+| `callbacks.py` | `AppContextBase` dataclass — lazy Output init, subclassed by each CLI |
+| `completions.py` | Shell completion generation + install (zsh/bash/fish) |
+| `config.py` | Profile framework — `~/.config/kodemeio/config.yaml`, service-scoped, env var expansion |
+| `docker.py` | `DockerManager` — Docker Compose wrapper (up/down/ps/logs/restart/exec) |
+| `doctor_base.py` | `DoctorCheck` protocol + `run_doctor()` + built-in checks |
+| `exceptions.py` | 9 exception classes: KctlError hierarchy |
+| `git_ops.py` | Git workflow helpers — branch_status, pr_create, changelog_generate |
+| `history.py` | `HistoryStore` — SQLite at `~/.local/share/kodemeio/{app}/history.db` |
+| `monitor_base.py` | `health_check_url()`, `ssl_check()`, `dns_check()` |
+| `output.py` | `Output` class — pretty (Rich), json, csv, yaml formatting |
+| `plugins.py` | `KctlPlugin` protocol + plugin discovery |
+| `runner.py` | `run()`, `run_quiet()`, `get_git_sha()`, `get_git_branch()` |
+| `self_update.py` | PyPI version check + uv tool upgrade |
+| `skill_generator.py` | `SkillGenerator` — Typer app introspection for SKILL.md generation |
+| `testing.py` | `mock_output()`, `mock_app_context()`, `temp_config()` |
+| `validate.py` | YAML/JSON/env/Dockerfile linting with `Issue` dataclass |
+
+## Development
+
+```bash
+uv run pytest tests/ -v          # 247 tests
+uv run ruff check src/           # Lint
+uv run mypy src/                 # Type check
+uv build                         # Build package
+```

kctl_lib-0.4.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-lib"
+version = "0.4.0"
+description = "Shared core library for kctl-* CLI tools"
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+testing = ["pytest>=8.3.0"]
+monitor = []
+dev = [
+    "pytest>=8.3.0",
+    "pytest-cov>=6.0.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+    "httpx>=0.28.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM", "N"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[dependency-groups]
+dev = [
+    "anyio>=4.13.0",
+    "pytest-anyio>=0.0.0",
+]

kctl_lib-0.4.0/src/kctl_lib/__init__.py

@@ -0,0 +1,80 @@
+"""kctl-lib: shared core library for kctl-* CLI tools.
+
+Public API:
+    - exceptions: KctlError hierarchy
+    - output: Output class (pretty/json/csv/yaml)
+    - config: Profile/config framework
+    - callbacks: AppContextBase
+    - runner: run(), run_quiet(), git helpers
+    - plugins: KctlPlugin protocol + discovery
+    - history: HistoryStore
+    - docker: DockerManager
+    - validate: YAML/JSON/env/Dockerfile linting
+    - git_ops: Branch status, PR, changelog, diff
+    - completions: Shell completion generation
+    - self_update: PyPI version check + upgrade
+    - doctor_base: DoctorCheck protocol + built-in checks
+    - monitor_base: Health check, SSL, DNS monitoring
+    - testing: Test fixtures (optional dependency)
+    - api_client: Base APIClient for httpx-based CLIs
+    - async_api_client: Base AsyncAPIClient for async CLIs
+"""
+
+__version__ = "0.4.0"
+
+from kctl_lib.api_client import APIClient
+from kctl_lib.async_api_client import AsyncAPIClient
+from kctl_lib.callbacks import AppContextBase
+from kctl_lib.docker import DockerManager
+from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+from kctl_lib.exceptions import (
+    APIError,
+    AppNotFoundError,
+    AuthenticationError,
+    CommandError,
+    ConfigError,
+    ConnectionError,
+    DockerError,
+    KctlError,
+    NotFoundError,
+    ValidationError,
+)
+from kctl_lib.output import Output
+from kctl_lib.validate import Issue
+
+__all__ = [
+    "APIClient",
+    "APIError",
+    "AppContextBase",
+    "AppNotFoundError",
+    "AsyncAPIClient",
+    "AuthenticationError",
+    "CheckResult",
+    "CommandError",
+    "ConfigError",
+    "ConnectionError",
+    "DockerError",
+    "DockerManager",
+    "DoctorCheck",
+    "Issue",
+    "KctlError",
+    "NotFoundError",
+    "Output",
+    "ValidationError",
+    "run_doctor",
+]
+
+
+def handle_cli_error(e: KctlError) -> None:
+    """Standardized error handler for CLI _run() entry points.
+
+    Usage in each CLI's cli.py:
+        try:
+            app()
+        except KctlError as e:
+            handle_cli_error(e)
+    """
+    import typer
+
+    typer.echo(f"Error: {e}", err=True)
+    raise typer.Exit(1) from e

kctl_lib-0.4.0/src/kctl_lib/api_client.py

@@ -0,0 +1,214 @@
+"""Base API client with retry, error mapping, and debug logging."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from random import uniform
+from typing import Any, Self
+
+import httpx
+
+from kctl_lib.exceptions import APIError, AuthenticationError, ConfigError
+from kctl_lib.exceptions import ConnectionError as KctlConnectionError
+
+
+class APIClient:
+    """Synchronous base API client for kctl-* CLI tools.
+
+    Subclass and override class attributes to customise per-service::
+
+        class MyClient(APIClient):
+            BASE_URL = "https://api.example.com"
+            AUTH_HEADER = "Authorization"
+            AUTH_PREFIX = "Bearer"
+            API_PREFIX = "/v1"
+    """
+
+    # Subclass overrides
+    AUTH_HEADER: str = "Authorization"
+    AUTH_PREFIX: str = "Bearer"
+    API_PREFIX: str = ""
+    BASE_URL: str = ""
+
+    def __init__(
+        self,
+        base_url: str = "",
+        credential: str = "",
+        timeout: float = 30.0,
+        retry_enabled: bool = False,
+        max_retries: int = 3,
+        retry_base_delay: float = 2.0,
+        retry_max_delay: float = 60.0,
+        **_kwargs: Any,
+    ) -> None:
+        if not credential or not credential.strip():
+            raise ConfigError("API credential is required")
+
+        resolved_url = base_url or self.BASE_URL
+        if not resolved_url:
+            raise ConfigError("base_url is required (pass it or set BASE_URL on the class)")
+
+        # Clean trailing slash
+        resolved_url = resolved_url.rstrip("/")
+
+        # Append API_PREFIX if not already present
+        if self.API_PREFIX and not resolved_url.endswith(self.API_PREFIX.rstrip("/")):
+            resolved_url = resolved_url + self.API_PREFIX
+
+        self._base_url = resolved_url
+        self._credential = credential
+        self._retry_enabled = retry_enabled
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._retry_max_delay = retry_max_delay
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._build_auth_header(),
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Auth
+    # ------------------------------------------------------------------
+
+    def _build_auth_header(self) -> dict[str, str]:
+        """Build the authentication header dict."""
+        if self.AUTH_PREFIX:
+            return {self.AUTH_HEADER: f"{self.AUTH_PREFIX} {self._credential}"}
+        return {self.AUTH_HEADER: self._credential}
+
+    # ------------------------------------------------------------------
+    # Core request
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, endpoint: str, **kwargs: Any) -> httpx.Response:
+        """Send an HTTP request with optional retry logic."""
+        url = endpoint.lstrip("/")
+        attempts = 1 + (self._max_retries if self._retry_enabled else 0)
+
+        last_exc: Exception | None = None
+        last_response: httpx.Response | None = None
+
+        for attempt in range(attempts):
+            try:
+                self._log_debug(f"{method.upper()} {self._base_url}{url}")
+                response = self._client.request(method, url, **kwargs)
+
+                if response.status_code < 400:
+                    return response
+
+                # Auth errors — never retry
+                if response.status_code in (401, 403):
+                    detail = self._map_error(response)
+                    raise AuthenticationError(detail)
+
+                # Server errors — retry if enabled
+                if response.status_code >= 500 and self._retry_enabled and attempt < attempts - 1:
+                    last_response = response
+                    self._sleep_with_jitter(attempt)
+                    continue
+
+                # Client errors or final server error
+                last_response = response
+                break
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                if self._retry_enabled and attempt < attempts - 1:
+                    self._sleep_with_jitter(attempt)
+                    continue
+                raise KctlConnectionError(url=self._base_url, cause=exc) from exc
+
+        # If we broke out of the loop with a response, raise the appropriate error
+        if last_response is not None:
+            detail = self._map_error(last_response)
+            raise APIError(status_code=last_response.status_code, detail=detail)
+
+        # Should not reach here, but handle connection errors after exhausted retries
+        if last_exc is not None:
+            raise KctlConnectionError(url=self._base_url, cause=last_exc) from last_exc
+
+        raise APIError(detail="Unexpected request state")  # pragma: no cover
+
+    # ------------------------------------------------------------------
+    # Response unwrapping
+    # ------------------------------------------------------------------
+
+    def _unwrap_response(self, response: httpx.Response) -> Any:
+        """Parse the response body. Override for envelope unwrapping."""
+        if not response.text.strip():
+            return {}
+        return response.json()
+
+    # ------------------------------------------------------------------
+    # Error helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _map_error(response: httpx.Response) -> str:
+        """Extract a human-readable error detail from the response."""
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                for key in ("detail", "error", "message"):
+                    if key in data:
+                        val = data[key]
+                        return str(val) if not isinstance(val, str) else val
+        except Exception:  # noqa: BLE001
+            pass
+        return response.text[:200] if response.text else f"HTTP {response.status_code}"
+
+    # ------------------------------------------------------------------
+    # Retry helpers
+    # ------------------------------------------------------------------
+
+    def _sleep_with_jitter(self, attempt: int) -> None:
+        """Exponential backoff with full jitter."""
+        ceiling = min(self._retry_base_delay * (2**attempt), self._retry_max_delay)
+        time.sleep(uniform(0, ceiling))  # noqa: S311
+
+    # ------------------------------------------------------------------
+    # Debug logging
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _log_debug(msg: str) -> None:
+        """Print debug info to stderr when KCTL_DEBUG is set."""
+        if os.environ.get("KCTL_DEBUG"):
+            print(f"[DEBUG] {msg}", file=sys.stderr)  # noqa: T201
+
+    # ------------------------------------------------------------------
+    # CRUD convenience methods
+    # ------------------------------------------------------------------
+
+    def get(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(self._request("GET", endpoint, **kwargs))
+
+    def post(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(self._request("POST", endpoint, **kwargs))
+
+    def put(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(self._request("PUT", endpoint, **kwargs))
+
+    def patch(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(self._request("PATCH", endpoint, **kwargs))
+
+    def delete(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(self._request("DELETE", endpoint, **kwargs))
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()

kctl_lib-0.4.0/src/kctl_lib/async_api_client.py

@@ -0,0 +1,214 @@
+"""Base async API client with retry, error mapping, and debug logging."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from random import uniform
+from typing import Any, Self
+
+import httpx
+
+from kctl_lib.exceptions import APIError, AuthenticationError, ConfigError
+from kctl_lib.exceptions import ConnectionError as KctlConnectionError
+
+
+class AsyncAPIClient:
+    """Asynchronous base API client for kctl-* CLI tools.
+
+    Subclass and override class attributes to customise per-service::
+
+        class MyAsyncClient(AsyncAPIClient):
+            BASE_URL = "https://api.example.com"
+            AUTH_HEADER = "Authorization"
+            AUTH_PREFIX = "Bearer"
+            API_PREFIX = "/v1"
+    """
+
+    # Subclass overrides
+    AUTH_HEADER: str = "Authorization"
+    AUTH_PREFIX: str = "Bearer"
+    API_PREFIX: str = ""
+    BASE_URL: str = ""
+
+    def __init__(
+        self,
+        base_url: str = "",
+        credential: str = "",
+        timeout: float = 30.0,
+        retry_enabled: bool = False,
+        max_retries: int = 3,
+        retry_base_delay: float = 2.0,
+        retry_max_delay: float = 60.0,
+        **_kwargs: Any,
+    ) -> None:
+        if not credential or not credential.strip():
+            raise ConfigError("API credential is required")
+
+        resolved_url = base_url or self.BASE_URL
+        if not resolved_url:
+            raise ConfigError("base_url is required (pass it or set BASE_URL on the class)")
+
+        # Clean trailing slash
+        resolved_url = resolved_url.rstrip("/")
+
+        # Append API_PREFIX if not already present
+        if self.API_PREFIX and not resolved_url.endswith(self.API_PREFIX.rstrip("/")):
+            resolved_url = resolved_url + self.API_PREFIX
+
+        self._base_url = resolved_url
+        self._credential = credential
+        self._retry_enabled = retry_enabled
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._retry_max_delay = retry_max_delay
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._build_auth_header(),
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Auth
+    # ------------------------------------------------------------------
+
+    def _build_auth_header(self) -> dict[str, str]:
+        """Build the authentication header dict."""
+        if self.AUTH_PREFIX:
+            return {self.AUTH_HEADER: f"{self.AUTH_PREFIX} {self._credential}"}
+        return {self.AUTH_HEADER: self._credential}
+
+    # ------------------------------------------------------------------
+    # Core request
+    # ------------------------------------------------------------------
+
+    async def _request(self, method: str, endpoint: str, **kwargs: Any) -> httpx.Response:
+        """Send an HTTP request with optional retry logic."""
+        url = endpoint.lstrip("/")
+        attempts = 1 + (self._max_retries if self._retry_enabled else 0)
+
+        last_exc: Exception | None = None
+        last_response: httpx.Response | None = None
+
+        for attempt in range(attempts):
+            try:
+                self._log_debug(f"{method.upper()} {self._base_url}{url}")
+                response = await self._client.request(method, url, **kwargs)
+
+                if response.status_code < 400:
+                    return response
+
+                # Auth errors — never retry
+                if response.status_code in (401, 403):
+                    detail = self._map_error(response)
+                    raise AuthenticationError(detail)
+
+                # Server errors — retry if enabled
+                if response.status_code >= 500 and self._retry_enabled and attempt < attempts - 1:
+                    last_response = response
+                    await self._sleep_with_jitter(attempt)
+                    continue
+
+                # Client errors or final server error
+                last_response = response
+                break
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                if self._retry_enabled and attempt < attempts - 1:
+                    await self._sleep_with_jitter(attempt)
+                    continue
+                raise KctlConnectionError(url=self._base_url, cause=exc) from exc
+
+        # If we broke out of the loop with a response, raise the appropriate error
+        if last_response is not None:
+            detail = self._map_error(last_response)
+            raise APIError(status_code=last_response.status_code, detail=detail)
+
+        # Should not reach here, but handle connection errors after exhausted retries
+        if last_exc is not None:
+            raise KctlConnectionError(url=self._base_url, cause=last_exc) from last_exc
+
+        raise APIError(detail="Unexpected request state")  # pragma: no cover
+
+    # ------------------------------------------------------------------
+    # Response unwrapping
+    # ------------------------------------------------------------------
+
+    def _unwrap_response(self, response: httpx.Response) -> Any:
+        """Parse the response body. Override for envelope unwrapping."""
+        if not response.text.strip():
+            return {}
+        return response.json()
+
+    # ------------------------------------------------------------------
+    # Error helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _map_error(response: httpx.Response) -> str:
+        """Extract a human-readable error detail from the response."""
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                for key in ("detail", "error", "message"):
+                    if key in data:
+                        val = data[key]
+                        return str(val) if not isinstance(val, str) else val
+        except Exception:  # noqa: BLE001
+            pass
+        return response.text[:200] if response.text else f"HTTP {response.status_code}"
+
+    # ------------------------------------------------------------------
+    # Retry helpers
+    # ------------------------------------------------------------------
+
+    async def _sleep_with_jitter(self, attempt: int) -> None:
+        """Exponential backoff with full jitter."""
+        ceiling = min(self._retry_base_delay * (2**attempt), self._retry_max_delay)
+        await asyncio.sleep(uniform(0, ceiling))  # noqa: S311
+
+    # ------------------------------------------------------------------
+    # Debug logging
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _log_debug(msg: str) -> None:
+        """Print debug info to stderr when KCTL_DEBUG is set."""
+        if os.environ.get("KCTL_DEBUG"):
+            print(f"[DEBUG] {msg}", file=sys.stderr)  # noqa: T201
+
+    # ------------------------------------------------------------------
+    # CRUD convenience methods
+    # ------------------------------------------------------------------
+
+    async def get(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(await self._request("GET", endpoint, **kwargs))
+
+    async def post(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(await self._request("POST", endpoint, **kwargs))
+
+    async def put(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(await self._request("PUT", endpoint, **kwargs))
+
+    async def patch(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(await self._request("PATCH", endpoint, **kwargs))
+
+    async def delete(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._unwrap_response(await self._request("DELETE", endpoint, **kwargs))
+
+    # ------------------------------------------------------------------
+    # Async context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()

kctl_lib-0.4.0/src/kctl_lib/callbacks.py

@@ -0,0 +1,37 @@
+"""Abstract base context for kctl-* CLI tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_lib.output import Output
+
+
+@dataclass
+class AppContextBase:
+    """Base application context with lazy Output initialization.
+
+    Subclass in each CLI to add domain-specific properties:
+    - Monorepo CLIs (next, react): project_root, apps, packages, validate_app()
+    - Server CLIs (odoo, api): url_override, api_key_override, client
+    - Claw: root_override, live, docker, gateway, config_mgr
+    """
+
+    json_mode: bool = False
+    quiet: bool = False
+    profile: str | None = None
+    format: str = "pretty"
+    no_header: bool = False
+    _output: Output | None = field(default=None, repr=False)
+
+    @property
+    def output(self) -> Output:
+        """Lazy-initialized output handler."""
+        if self._output is None:
+            self._output = Output(
+                json_mode=self.json_mode,
+                quiet=self.quiet,
+                format=self.format,
+                no_header=self.no_header,
+            )
+        return self._output