sum-cli 3.0.0__py3-none-any.whl

sum/system_config.py

@@ -0,0 +1,330 @@
+"""System configuration for SUM Platform CLI.
+
+Reads agency-specific settings from /etc/sum/config.yml.
+All values MUST be provided in the config file - no defaults.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+from sum.exceptions import SumCliError
+
+# Default config file location
+DEFAULT_CONFIG_PATH = Path("/etc/sum/config.yml")
+
+# Environment variable override for config path (useful for testing/dev)
+CONFIG_PATH_ENV_VAR = "SUM_CONFIG_PATH"
+
+
+class ConfigurationError(SumCliError):
+    """Configuration file is missing or invalid."""
+
+    pass
+
+
+@dataclass
+class AgencyConfig:
+    """Agency identification settings."""
+
+    name: str
+    # Git provider: "github" (default) or "gitea"
+    git_provider: str = "github"
+    # GitHub-specific (required when git_provider=github)
+    github_org: str | None = None
+    # Gitea-specific (required when git_provider=gitea)
+    gitea_url: str | None = None
+    gitea_org: str | None = None
+    gitea_token_env: str = "GITEA_TOKEN"  # env var name containing API token
+
+    def __post_init__(self) -> None:
+        """Validate provider-specific fields."""
+        if self.git_provider not in ("github", "gitea"):
+            raise ConfigurationError(
+                f"Invalid git_provider '{self.git_provider}'. Must be 'github' or 'gitea'."
+            )
+
+        if self.git_provider == "github":
+            if not self.github_org:
+                raise ConfigurationError(
+                    "github_org is required when git_provider is 'github'"
+                )
+        elif self.git_provider == "gitea":
+            if not self.gitea_url:
+                raise ConfigurationError(
+                    "gitea_url is required when git_provider is 'gitea'"
+                )
+            if not self.gitea_org:
+                raise ConfigurationError(
+                    "gitea_org is required when git_provider is 'gitea'"
+                )
+
+    @property
+    def org(self) -> str:
+        """Get the organization name for the configured provider."""
+        if self.git_provider == "gitea":
+            return self.gitea_org or ""
+        return self.github_org or ""
+
+
+@dataclass
+class StagingConfig:
+    """Staging server configuration."""
+
+    server: str
+    domain_pattern: str  # e.g., "{slug}.example.com"
+    base_dir: str
+
+
+@dataclass
+class ProductionConfig:
+    """Production server configuration."""
+
+    server: str
+    ssh_host: str
+    base_dir: str
+
+
+@dataclass
+class TemplatesConfig:
+    """Infrastructure template paths."""
+
+    dir: str
+    systemd: str
+    caddy: str
+
+    @property
+    def systemd_path(self) -> Path:
+        """Full path to systemd template."""
+        return Path(self.dir) / self.systemd
+
+    @property
+    def caddy_path(self) -> Path:
+        """Full path to Caddy template."""
+        return Path(self.dir) / self.caddy
+
+
+@dataclass
+class DefaultsConfig:
+    """Default values for CLI operations."""
+
+    theme: str
+    deploy_user: str
+    seed_profile: str
+    postgres_port: int = 5432  # Default port, can be overridden in config
+
+
+@dataclass
+class SystemConfig:
+    """Complete system configuration.
+
+    Loaded from /etc/sum/config.yml. All values must be provided.
+    """
+
+    agency: AgencyConfig
+    staging: StagingConfig
+    production: ProductionConfig
+    templates: TemplatesConfig
+    defaults: DefaultsConfig
+
+    _config_path: Path | None = None
+
+    @classmethod
+    def load(cls, config_path: Path | str | None = None) -> SystemConfig:
+        """Load configuration from file.
+
+        Args:
+            config_path: Optional explicit path to config file.
+                         If not provided, checks SUM_CONFIG_PATH env var,
+                         then falls back to /etc/sum/config.yml.
+
+        Returns:
+            SystemConfig instance with loaded values.
+
+        Raises:
+            ConfigurationError: If config file is missing or invalid.
+        """
+        # Determine config path
+        if config_path is None:
+            env_path = os.environ.get(CONFIG_PATH_ENV_VAR)
+            if env_path:
+                config_path = Path(env_path)
+            else:
+                config_path = DEFAULT_CONFIG_PATH
+        else:
+            config_path = Path(config_path)
+
+        # Config file is required
+        if not config_path.exists():
+            raise ConfigurationError(
+                f"Configuration file not found: {config_path}\n\n"
+                f"The SUM CLI requires a configuration file.\n"
+                f"Create {config_path} with your agency settings.\n\n"
+                f"See docs/dev/cli/USER_GUIDE.md for the required format."
+            )
+
+        return cls._load_from_file(config_path)
+
+    @classmethod
+    def _load_from_file(cls, config_path: Path) -> SystemConfig:
+        """Load configuration from YAML file."""
+        try:
+            with open(config_path) as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as exc:
+            raise ConfigurationError(
+                f"Invalid YAML in configuration file {config_path}: {exc}"
+            ) from exc
+
+        if not data:
+            raise ConfigurationError(f"Configuration file is empty: {config_path}")
+
+        # Validate required sections
+        required_sections = ["agency", "staging", "production", "templates", "defaults"]
+        missing_sections = [s for s in required_sections if s not in data]
+        if missing_sections:
+            raise ConfigurationError(
+                f"Missing required sections in {config_path}: {', '.join(missing_sections)}"
+            )
+
+        try:
+            return cls(
+                agency=cls._load_section(data["agency"], AgencyConfig, "agency"),
+                staging=cls._load_section(data["staging"], StagingConfig, "staging"),
+                production=cls._load_section(
+                    data["production"], ProductionConfig, "production"
+                ),
+                templates=cls._load_section(
+                    data["templates"], TemplatesConfig, "templates"
+                ),
+                defaults=cls._load_section(
+                    data["defaults"], DefaultsConfig, "defaults"
+                ),
+                _config_path=config_path,
+            )
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(
+                f"Error loading configuration from {config_path}: {exc}"
+            ) from exc
+
+    @staticmethod
+    def _load_section(
+        data: dict[str, Any], config_class: type, section_name: str
+    ) -> Any:
+        """Load a config section, validating all required fields are present."""
+        if not isinstance(data, dict):
+            raise ConfigurationError(
+                f"Section '{section_name}' must be a mapping, got {type(data).__name__}"
+            )
+
+        # For dataclasses without default_factory, check which fields have no default
+        all_fields = []
+        for field_name, field_info in config_class.__dataclass_fields__.items():
+            if field_name.startswith("_"):
+                continue
+            # Field is required if it has no default and no default_factory
+            if (
+                field_info.default is dataclasses.MISSING
+                and field_info.default_factory is dataclasses.MISSING
+            ):
+                all_fields.append(field_name)
+
+        missing_fields = [f for f in all_fields if f not in data]
+        if missing_fields:
+            raise ConfigurationError(
+                f"Missing required fields in '{section_name}': {', '.join(missing_fields)}"
+            )
+
+        # Build kwargs from data
+        kwargs = {}
+        for field_name in config_class.__dataclass_fields__:
+            if field_name.startswith("_"):
+                continue
+            if field_name in data:
+                kwargs[field_name] = data[field_name]
+
+        return config_class(**kwargs)
+
+    def get_site_dir(self, site_slug: str, target: str = "staging") -> Path:
+        """Get the base directory for a site.
+
+        Args:
+            site_slug: The site slug (e.g., 'acme')
+            target: 'staging' or 'prod'
+
+        Returns:
+            Path to site directory
+        """
+        if target == "prod":
+            base = self.production.base_dir
+        else:
+            base = self.staging.base_dir
+        return Path(base) / site_slug
+
+    def get_site_domain(self, site_slug: str, target: str = "staging") -> str:
+        """Get the domain for a site.
+
+        Args:
+            site_slug: The site slug (e.g., 'acme')
+            target: 'staging' or 'prod' (prod requires explicit domain)
+
+        Returns:
+            Domain string
+
+        Raises:
+            ValueError: If target is 'prod' (production requires explicit domain)
+        """
+        if target == "prod":
+            raise ValueError("Production domain must be explicitly specified")
+        return self.staging.domain_pattern.format(slug=site_slug)
+
+    def get_db_name(self, site_slug: str) -> str:
+        """Get the Postgres database name for a site."""
+        return f"sum_{site_slug}"
+
+    def get_db_user(self, site_slug: str) -> str:
+        """Get the Postgres database user for a site."""
+        return f"sum_{site_slug}_user"
+
+    def get_systemd_service_name(self, site_slug: str) -> str:
+        """Get the systemd service name for a site."""
+        return f"sum-{site_slug}-gunicorn"
+
+    def get_caddy_config_name(self, site_slug: str) -> str:
+        """Get the Caddy config file name for a site."""
+        return f"sum-{site_slug}.caddy"
+
+
+# Module-level singleton for convenience
+_system_config: SystemConfig | None = None
+
+
+def get_system_config(reload: bool = False) -> SystemConfig:
+    """Get the system configuration singleton.
+
+    Args:
+        reload: Force reload from file even if already loaded.
+
+    Returns:
+        SystemConfig instance.
+
+    Raises:
+        ConfigurationError: If config file is missing or invalid.
+    """
+    global _system_config
+    if _system_config is None or reload:
+        _system_config = SystemConfig.load()
+    return _system_config
+
+
+def reset_system_config() -> None:
+    """Reset the config singleton (primarily for testing)."""
+    global _system_config
+    _system_config = None

sum/themes_registry.py

@@ -0,0 +1,180 @@
+"""Theme registry and discovery for CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from sum.exceptions import ThemeNotFoundError, ThemeValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeManifest:
+    """Type-safe theme metadata loaded from theme.json."""
+
+    slug: str
+    name: str
+    description: str
+    version: str
+
+    def validate(self) -> None:
+        if not self.slug:
+            raise ValueError("slug cannot be empty")
+        if not self.name:
+            raise ValueError("name cannot be empty")
+        if not self.version:
+            raise ValueError("version cannot be empty")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ThemeManifest:
+        return cls(
+            slug=str(data.get("slug", "")).strip(),
+            name=str(data.get("name", "")).strip(),
+            description=str(data.get("description", "")).strip(),
+            version=str(data.get("version", "")).strip(),
+        )
+
+
+def _read_manifest(theme_dir: Path) -> ThemeManifest:
+    manifest_path = theme_dir / "theme.json"
+    if not manifest_path.is_file():
+        raise ThemeValidationError(f"Missing theme manifest: {manifest_path}")
+
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ThemeValidationError(
+            f"Invalid JSON in theme manifest: {manifest_path} ({e})"
+        ) from e
+
+    if not isinstance(data, dict):
+        raise ThemeValidationError(f"Theme manifest must be an object: {manifest_path}")
+
+    manifest = ThemeManifest.from_dict(data)
+    manifest.validate()
+
+    # Hard validation: directory name must match manifest slug
+    if manifest.slug != theme_dir.name:
+        raise ThemeValidationError(
+            f"Theme slug mismatch: dir='{theme_dir.name}' manifest='{manifest.slug}'"
+        )
+
+    return manifest
+
+
+def _resolve_theme_dir_from_env(slug: str) -> Path | None:
+    """
+    Resolve a theme dir from SUM_THEME_PATH.
+
+    Spec v1 supports setting SUM_THEME_PATH to a single theme directory like:
+      SUM_THEME_PATH=/path/to/themes/theme_a
+
+    For developer ergonomics we also support pointing at a themes root like:
+      SUM_THEME_PATH=/path/to/themes
+    """
+    env = os.getenv("SUM_THEME_PATH")
+    if not env:
+        return None
+
+    p = Path(env).expanduser().resolve()
+    if not p.exists():
+        raise ThemeNotFoundError(f"SUM_THEME_PATH does not exist: {p}")
+
+    # If SUM_THEME_PATH points at a theme root (contains theme.json), use it directly.
+    if (p / "theme.json").is_file():
+        return p
+
+    # Otherwise treat it as a themes root containing subdirectories by slug.
+    candidate = p / slug
+    if candidate.is_dir():
+        return candidate
+
+    raise ThemeNotFoundError(f"Theme '{slug}' not found under SUM_THEME_PATH: {p}")
+
+
+def resolve_theme_dir(slug: str) -> Path:
+    """
+    Resolve a theme directory using Theme Architecture Spec v1 order:
+
+    1) SUM_THEME_PATH (dev override)
+    2) repo-local canonical: ./themes/<slug> (relative to current working dir)
+    3) bundled themes inside CLI package (optional, later)
+    """
+    slug = slug.strip()
+    if not slug:
+        raise ThemeNotFoundError("Theme slug cannot be empty")
+
+    env_dir = _resolve_theme_dir_from_env(slug)
+    if env_dir is not None:
+        return env_dir
+
+    repo_local = (Path.cwd() / "themes" / slug).resolve()
+    if repo_local.is_dir():
+        return repo_local
+
+    # Bundled themes inside CLI package: optional later (not implemented yet).
+    raise ThemeNotFoundError(
+        f"Theme '{slug}' not found. Looked in SUM_THEME_PATH (if set) and "
+        f"{repo_local.parent}"
+    )
+
+
+def get_theme(slug: str) -> ThemeManifest:
+    """Return a validated ThemeManifest for the theme slug."""
+    theme_dir = resolve_theme_dir(slug)
+    try:
+        return _read_manifest(theme_dir)
+    except ThemeValidationError as e:
+        # Keep a stable exception type for callers (CLI/tests).
+        raise ThemeValidationError(str(e)) from e
+
+
+def list_themes() -> list[ThemeManifest]:
+    """
+    List themes from the best available registry in this environment.
+
+    - If SUM_THEME_PATH points to a single theme dir, return that one theme.
+    - If SUM_THEME_PATH points to a themes root, scan that root.
+    - Else scan ./themes (repo-local canonical).
+    """
+    env = os.getenv("SUM_THEME_PATH")
+    if env:
+        p = Path(env).expanduser().resolve()
+        if (p / "theme.json").is_file():
+            return [_read_manifest(p)]
+        if p.is_dir():
+            return discover_themes(p)
+
+    repo_local_root = (Path.cwd() / "themes").resolve()
+    return discover_themes(repo_local_root)
+
+
+def discover_themes(themes_root: Path) -> list[ThemeManifest]:
+    """Discover themes by scanning `<themes_root>/*/theme.json`."""
+    if not themes_root.exists():
+        return []
+
+    manifests: list[ThemeManifest] = []
+    for theme_dir in sorted(p for p in themes_root.iterdir() if p.is_dir()):
+        if theme_dir.name.startswith("__"):
+            continue
+        try:
+            manifests.append(_read_manifest(theme_dir))
+        except ThemeValidationError:
+            # Discovery is tolerant by design: invalid themes are ignored.
+            continue
+    return sorted(manifests, key=lambda t: t.slug)
+
+
+__all__ = [
+    "ThemeManifest",
+    "ThemeNotFoundError",
+    "ThemeValidationError",
+    "discover_themes",
+    "get_theme",
+    "list_themes",
+    "resolve_theme_dir",
+]

sum/utils/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from sum.utils.django import DjangoCommandExecutor
+from sum.utils.environment import (
+    ExecutionMode,
+    detect_mode,
+    find_monorepo_root,
+    get_clients_dir,
+)
+from sum.utils.output import OutputFormatter
+from sum.utils.prompts import PromptManager
+from sum.utils.validation import ProjectValidator, ValidationResult, ValidationStatus
+
+__all__ = [
+    "DjangoCommandExecutor",
+    "ExecutionMode",
+    "detect_mode",
+    "find_monorepo_root",
+    "get_clients_dir",
+    "OutputFormatter",
+    "PromptManager",
+    "ProjectValidator",
+    "ValidationResult",
+    "ValidationStatus",
+]

sum/utils/django.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+
+from sum.exceptions import VenvError
+from sum.utils.environment import ExecutionMode, find_monorepo_root
+
+
+class DjangoCommandExecutor:
+    """Executes Django management commands."""
+
+    def __init__(
+        self,
+        project_path: Path,
+        mode: ExecutionMode,
+        python_path: Path | None = None,
+    ) -> None:
+        """Initialize Django command executor.
+
+        Args:
+            project_path: Path to the Django project (where manage.py is).
+            mode: Execution mode (MONOREPO or STANDALONE).
+            python_path: Optional explicit path to Python executable.
+                        If not provided, looks for .venv/bin/python in project_path.
+        """
+        self.project_path = project_path
+        self.mode = mode
+        self._python_path = python_path
+
+    def run_command(
+        self,
+        command: list[str],
+        env: Mapping[str, str] | None = None,
+        check: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        """Run a Django management command.
+
+        Args:
+            command: Command and arguments as a list (e.g., ["migrate", "--noinput"]).
+            env: Optional environment variable overrides.
+            check: Whether to raise on non-zero exit code.
+
+        Returns:
+            Completed process result.
+        """
+        python = self._get_python_executable()
+        full_command = [str(python), "manage.py", *command]
+
+        command_env = os.environ.copy()
+        if env:
+            command_env.update(env)
+
+        if self.mode is ExecutionMode.MONOREPO:
+            core_path = self._get_core_path()
+            existing = command_env.get("PYTHONPATH", "")
+            if existing:
+                command_env["PYTHONPATH"] = f"{existing}{os.pathsep}{core_path}"
+            else:
+                command_env["PYTHONPATH"] = str(core_path)
+
+        return subprocess.run(
+            full_command,
+            cwd=self.project_path,
+            env=command_env,
+            capture_output=True,
+            text=True,
+            check=check,
+        )
+
+    def _get_python_executable(self) -> Path:
+        """Return the Python executable to use."""
+        # Use explicit path if provided
+        if self._python_path is not None:
+            if not self._python_path.exists():
+                raise VenvError(
+                    f"Specified Python executable not found: {self._python_path}"
+                )
+            return self._python_path
+
+        # Fall back to .venv/bin/python in project
+        venv_python = self.project_path / ".venv" / "bin" / "python"
+        if not venv_python.exists():
+            raise VenvError(
+                f"Virtualenv not found at {self.project_path / '.venv'}. "
+                "Run 'sum init --full' or create manually with 'python -m venv .venv'"
+            )
+        return venv_python
+
+    def _get_core_path(self) -> Path:
+        """Get the monorepo core path for PYTHONPATH injection."""
+        repo_root = find_monorepo_root(self.project_path)
+        if repo_root is not None:
+            return repo_root / "core"
+        raise ValueError("Cannot determine core path - not in monorepo")