kctl-common 0.1.0__tar.gz

kctl_common-0.1.0/.gitignore

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

kctl_common-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-common
+Version: 0.1.0
+Summary: Shared core library for kctl-* CLI tools
+Requires-Python: >=3.12
+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: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.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: testing
+Requires-Dist: pytest>=8.3.0; extra == 'testing'

kctl_common-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-common"
+version = "0.1.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",
+]
+
+[project.optional-dependencies]
+testing = ["pytest>=8.3.0"]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.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

kctl_common-0.1.0/src/kctl_common/__init__.py

@@ -0,0 +1,59 @@
+"""kctl-common: 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
+    - testing: Test fixtures (optional dependency)
+"""
+
+__version__ = "0.1.0"
+
+from kctl_common.callbacks import AppContextBase
+from kctl_common.exceptions import (
+    APIError,
+    AppNotFoundError,
+    AuthenticationError,
+    CommandError,
+    ConfigError,
+    ConnectionError,
+    DockerError,
+    KctlError,
+    NotFoundError,
+    ValidationError,
+)
+from kctl_common.output import Output
+
+__all__ = [
+    "APIError",
+    "AppContextBase",
+    "AppNotFoundError",
+    "AuthenticationError",
+    "CommandError",
+    "ConfigError",
+    "ConnectionError",
+    "DockerError",
+    "KctlError",
+    "NotFoundError",
+    "Output",
+    "ValidationError",
+]
+
+
+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_common-0.1.0/src/kctl_common/callbacks.py

@@ -0,0 +1,37 @@
+"""Abstract base context for kctl-* CLI tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_common.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

kctl_common-0.1.0/src/kctl_common/config.py

@@ -0,0 +1,168 @@
+"""Profile management and configuration framework for kctl-* CLIs.
+
+Shared config at ~/.config/kodemeio/config.yaml supports multiple services.
+Each CLI provides its own SERVICE_KEY (e.g., "next", "odoo", "react").
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel
+
+CONFIG_DIR = Path.home() / ".config" / "kodemeio"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+
+_ENV_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class ConfigFile(BaseModel):
+    """Top-level config file model."""
+
+    default_profile: str = "default"
+    profiles: dict[str, dict[str, Any]] = {}
+
+
+def expand_env(value: str) -> str:
+    """Expand ${ENV_VAR} references in a string value."""
+
+    def _replace(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        return os.environ.get(var_name, match.group(0))
+
+    return _ENV_VAR_RE.sub(_replace, value)
+
+
+def is_service_scoped(profile_data: dict[str, Any]) -> bool:
+    """Check if profile data uses service-scoped format (nested dicts)."""
+    return any(isinstance(val, dict) for val in profile_data.values())
+
+
+def load_raw_config() -> dict[str, Any]:
+    """Load raw YAML config from disk."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(CONFIG_FILE) as f:
+            return yaml.safe_load(f) or {}
+    except (yaml.YAMLError, OSError) as e:
+        print(f"WARN: Cannot read {CONFIG_FILE}: {e}", file=sys.stderr)
+        return {}
+
+
+def save_raw_config(data: dict[str, Any]) -> None:
+    """Write raw config dict to YAML file."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def load_config() -> ConfigFile:
+    """Load and validate the config file."""
+    data = load_raw_config()
+    return ConfigFile(
+        default_profile=data.get("default_profile", "default"),
+        profiles=data.get("profiles", {}),
+    )
+
+
+def get_service_config(
+    profile_name: str,
+    service_key: str,
+    valid_fields: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get a service config dict from a profile."""
+    cfg = load_config()
+    profile_data = cfg.profiles.get(profile_name, {})
+    if not profile_data:
+        return {}
+
+    if is_service_scoped(profile_data):
+        svc_data = profile_data.get(service_key, {})
+        if not isinstance(svc_data, dict):
+            return {}
+        raw = dict(svc_data)
+    else:
+        raw = dict(profile_data)
+
+    for k, v in raw.items():
+        if isinstance(v, str):
+            raw[k] = expand_env(v)
+
+    if valid_fields is not None:
+        raw = {k: v for k, v in raw.items() if k in valid_fields}
+
+    return raw
+
+
+def set_service_config(profile_name: str, service_key: str, svc_data: dict[str, Any]) -> None:
+    """Set a service config within a profile."""
+    data = load_raw_config()
+    if "profiles" not in data:
+        data["profiles"] = {}
+    if profile_name not in data["profiles"]:
+        data["profiles"][profile_name] = {}
+
+    profile = data["profiles"][profile_name]
+
+    if not is_service_scoped(profile):
+        old_data = dict(profile)
+        profile.clear()
+        profile[service_key] = old_data
+
+    cleaned = {k: v for k, v in svc_data.items() if v}
+    profile[service_key] = cleaned
+    save_raw_config(data)
+
+
+def get_profile_names() -> list[str]:
+    """Return all profile names."""
+    cfg = load_config()
+    return list(cfg.profiles.keys())
+
+
+def get_all_services_in_profile(profile_name: str) -> dict[str, dict[str, Any]]:
+    """Return all service configs within a profile."""
+    cfg = load_config()
+    profile_data = cfg.profiles.get(profile_name, {})
+    if is_service_scoped(profile_data):
+        return {k: v for k, v in profile_data.items() if isinstance(v, dict)}
+    return {}
+
+
+def get_default_profile() -> str:
+    """Return the default profile name."""
+    cfg = load_config()
+    return cfg.default_profile
+
+
+def set_default_profile(name: str) -> None:
+    """Set the default profile name."""
+    data = load_raw_config()
+    data["default_profile"] = name
+    save_raw_config(data)
+
+
+def remove_profile(name: str) -> None:
+    """Remove a profile by name."""
+    data = load_raw_config()
+    profiles = data.get("profiles", {})
+    profiles.pop(name, None)
+    if data.get("default_profile") == name:
+        data["default_profile"] = next(iter(profiles), "default")
+    save_raw_config(data)
+
+
+def resolve_active_profile_name(profile_name: str | None, env_prefix: str) -> str:
+    """Resolve active profile: explicit > env > default."""
+    if profile_name:
+        return profile_name
+    env_var = f"{env_prefix}_PROFILE"
+    if env := os.environ.get(env_var):
+        return env
+    return get_default_profile()

kctl_common-0.1.0/src/kctl_common/exceptions.py

@@ -0,0 +1,84 @@
+"""Unified exception hierarchy for all kctl-* CLI tools."""
+
+from __future__ import annotations
+
+
+class KctlError(Exception):
+    """Base exception for all kctl errors."""
+
+
+class ConfigError(KctlError):
+    """Configuration-related errors."""
+
+
+class AuthenticationError(KctlError):
+    """Authentication/API key errors."""
+
+
+class NotFoundError(KctlError):
+    """Resource not found."""
+
+    def __init__(self, resource_type: str, identifier: str):
+        self.resource_type = resource_type
+        self.identifier = identifier
+        super().__init__(f"{resource_type} not found: {identifier}")
+
+
+class AppNotFoundError(NotFoundError):
+    """App not found in monorepo."""
+
+    def __init__(self, app_name: str, valid_apps: list[str] | None = None):
+        self.valid_apps = valid_apps or []
+        super().__init__("app", app_name)
+
+    def __str__(self) -> str:
+        hint = f" (valid: {', '.join(self.valid_apps)})" if self.valid_apps else ""
+        return f"App not found: {self.identifier}{hint}"
+
+
+class CommandError(KctlError):
+    """Shell command execution errors."""
+
+    def __init__(self, command: str, returncode: int, stderr: str = ""):
+        self.command = command
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"Command failed (exit {returncode}): {command}\n{stderr}".strip())
+
+
+class APIError(KctlError):
+    """HTTP API errors."""
+
+    def __init__(self, status_code: int = 0, detail: str = ""):
+        self.status_code = status_code
+        self.detail = detail
+        msg = f"API error ({status_code}): {detail}" if status_code else detail
+        super().__init__(msg)
+
+
+class ConnectionError(KctlError):  # noqa: A001
+    """Cannot connect to remote service."""
+
+    def __init__(self, url: str, cause: Exception | None = None):
+        self.url = url
+        self.cause = cause
+        super().__init__(f"Cannot connect to {url}: {cause}")
+
+
+class DockerError(KctlError):
+    """Docker compose/exec execution errors."""
+
+    def __init__(self, command: str, returncode: int, stderr: str = ""):
+        self.command = command
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"Command failed (exit {returncode}): {command}\n{stderr}".strip())
+
+
+class ValidationError(KctlError):
+    """Multi-error validation failures."""
+
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        msg = f"{len(errors)} validation error(s):\n" + "\n".join(f"  - {e}" for e in errors)
+        super().__init__(msg)

kctl_common-0.1.0/src/kctl_common/history.py

@@ -0,0 +1,93 @@
+"""SQLite-based history tracking for kctl-* CLI tools."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Generator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+DATA_BASE_DIR = Path.home() / ".local" / "share" / "kodemeio"
+
+
+class HistoryStore:
+    """SQLite-based history storage for a kctl-* CLI."""
+
+    def __init__(self, app_name: str):
+        self._app_name = app_name
+        self._data_dir = DATA_BASE_DIR / app_name
+        self._db_path = self._data_dir / "history.db"
+        self._schema_initialized = False
+
+    @property
+    def db_path(self) -> Path:
+        return self._db_path
+
+    @contextmanager
+    def _connect(self) -> Generator[sqlite3.Connection, None, None]:
+        """Context manager for safe DB connections."""
+        self._data_dir.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(str(self._db_path))
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    def ensure_schema(self, statements: list[str]) -> None:
+        """Run CREATE TABLE statements once per process."""
+        if self._schema_initialized:
+            return
+        with self._connect() as conn:
+            for stmt in statements:
+                conn.execute(stmt)
+            conn.commit()
+        self._schema_initialized = True
+
+    def record(self, table: str, **kwargs: Any) -> int:
+        """Insert a record into a table. Adds timestamp automatically."""
+        kwargs["timestamp"] = datetime.now(UTC).isoformat()
+        columns = ", ".join(kwargs.keys())
+        placeholders = ", ".join("?" for _ in kwargs)
+        values = list(kwargs.values())
+
+        with self._connect() as conn:
+            cur = conn.execute(f"INSERT INTO {table} ({columns}) VALUES ({placeholders})", values)  # noqa: S608
+            conn.commit()
+            return cur.lastrowid or 0
+
+    def query(
+        self,
+        table: str,
+        limit: int = 20,
+        order_by: str = "timestamp DESC",
+        where: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Query records from a table."""
+        sql = f"SELECT * FROM {table}"  # noqa: S608
+        params: list[Any] = []
+
+        if where:
+            clauses = [f"{k} = ?" for k in where]
+            sql += " WHERE " + " AND ".join(clauses)
+            params.extend(where.values())
+
+        sql += f" ORDER BY {order_by} LIMIT ?"
+        params.append(limit)
+
+        with self._connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+            return [dict(r) for r in rows]
+
+    def clear(self, table: str | None = None) -> None:
+        """Clear records from a table, or all tables if table is None."""
+        with self._connect() as conn:
+            if table:
+                conn.execute(f"DELETE FROM {table}")  # noqa: S608
+            else:
+                tables = conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+                for row in tables:
+                    conn.execute(f"DELETE FROM {row['name']}")  # noqa: S608
+            conn.commit()