sum-cli 3.0.0__py3-none-any.whl

sum/utils/environment.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+
+class ExecutionMode(str, Enum):
+    MONOREPO = "monorepo"
+    STANDALONE = "standalone"
+
+
+def _normalize_start_path(start_path: Path | None) -> Path:
+    """Return a directory path from a file path or default to the current cwd."""
+    path = start_path or Path.cwd()
+    if path.is_file():
+        return path.parent
+    return path
+
+
+def find_monorepo_root(start_path: Path | None = None) -> Path | None:
+    """Walk upward to find monorepo root (contains core/ and boilerplate/)."""
+    search_path = _normalize_start_path(start_path)
+
+    for parent in [search_path, *search_path.parents]:
+        if (parent / "core").is_dir() and (parent / "boilerplate").is_dir():
+            return parent
+
+    return None
+
+
+def detect_mode(path: Path | None = None) -> ExecutionMode:
+    """Detect execution mode based on directory structure."""
+    if find_monorepo_root(path) is not None:
+        return ExecutionMode.MONOREPO
+    return ExecutionMode.STANDALONE
+
+
+def get_clients_dir(start_path: Path | None = None, *, create: bool = False) -> Path:
+    """Resolve the clients directory for monorepo or standalone mode."""
+    repo_root = find_monorepo_root(start_path)
+    if repo_root is not None:
+        monorepo_clients = repo_root / "clients"
+        if monorepo_clients.is_dir():
+            return monorepo_clients
+
+    search_path = _normalize_start_path(start_path)
+    standalone_clients = search_path / "clients"
+    if standalone_clients.is_dir():
+        return standalone_clients
+
+    if create:
+        standalone_clients.mkdir(parents=True, exist_ok=True)
+        return standalone_clients
+
+    raise FileNotFoundError(
+        "Cannot locate clients directory. Ensure you're running inside the monorepo "
+        "or from a standalone project root that contains a 'clients' folder."
+    )
+
+
+def resolve_project_path(project: str | None, start_path: Path | None = None) -> Path:
+    """Resolve a project path from name or current directory."""
+    if project:
+        clients_dir = get_clients_dir(start_path)
+        project_path = clients_dir / project
+        if project_path.is_dir():
+            return project_path
+        raise FileNotFoundError(f"Project not found: {project}")
+
+    cwd = _normalize_start_path(start_path)
+    if (cwd / "manage.py").exists():
+        return cwd
+
+    raise FileNotFoundError(
+        "Not in a project directory. Either cd into a project or specify project name."
+    )

sum/utils/output.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+class OutputFormatter:
+    """Formatting helpers for CLI output."""
+
+    @staticmethod
+    def progress(
+        step: int, total: int, message: str, status: str = "running", emit: bool = True
+    ) -> str:
+        """Format, print, and return a progress line for a multi-step operation."""
+        line = f"⏳ [{step}/{total}] {status}: {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def success(message: str, emit: bool = True) -> str:
+        """Format, print, and return a success message string."""
+        line = f"✅ {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def error(message: str, emit: bool = True) -> str:
+        """Format, print, and return an error message string."""
+        line = f"❌ {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def info(message: str, emit: bool = True) -> str:
+        """Format, print, and return an informational message string."""
+        line = f"ℹ {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def warning(message: str, emit: bool = True) -> str:
+        """Format, print, and return a warning message string."""
+        line = f"⚠️  {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def header(message: str, emit: bool = True) -> str:
+        """Format, print, and return a header message string."""
+        line = f"🚀 {message}"
+        if emit:
+            print(line)
+        return line
+
+    @staticmethod
+    def summary(project_name: str, data: Mapping[str, str], emit: bool = True) -> str:
+        """Format, print, and return a formatted summary block for a project.
+
+        Password values are intentionally omitted from the output for safety.
+        """
+        lines = [
+            "📋 Summary",
+            "--------------------",
+            f"🏷️  Project: {project_name}",
+        ]
+        for key, value in data.items():
+            if key.lower() == "password":
+                continue
+            lines.append(f"✅ {key}: {value}")
+        lines.append("--------------------")
+        output = "\n".join(lines)
+        if emit:
+            print(output)
+        return output

sum/utils/project.py

@@ -0,0 +1,110 @@
+"""Project naming utilities and boilerplate resource access.
+
+This module provides utilities for validating project names, generating
+Python package names from slugs, and accessing bundled boilerplate templates.
+
+Migrated from sum_cli.util as part of CLI v2 consolidation.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import importlib.resources.abc
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+PROJECT_SLUG_RE: Final[re.Pattern[str]] = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+@dataclass(frozen=True)
+class ProjectNaming:
+    """
+    Naming derived from the user-provided project slug.
+
+    - slug: directory name under clients/
+    - python_package: importable Python identifier (hyphens converted to underscores)
+    """
+
+    slug: str
+    python_package: str
+
+
+def validate_project_name(project_name: str) -> ProjectNaming:
+    """
+    Validate and normalize the project name.
+
+    Allowed: lowercase letters, digits, hyphens; must start with a letter.
+    """
+    name = project_name.strip()
+    if not PROJECT_SLUG_RE.fullmatch(name):
+        raise ValueError(
+            "Invalid project name. Use lowercase letters, digits, and hyphens "
+            "(must start with a letter). Example: acme-kitchens"
+        )
+    python_pkg = name.replace("-", "_")
+    return ProjectNaming(slug=name, python_package=python_pkg)
+
+
+def get_packaged_boilerplate() -> importlib.resources.abc.Traversable:
+    """
+    Return the boilerplate directory bundled with the CLI package as a Traversable.
+
+    Use `importlib.resources.as_file(...)` to materialize this to a real filesystem
+    path when you need to pass it to APIs like shutil.copytree.
+    """
+    root = importlib.resources.files("sum")
+    return root.joinpath("boilerplate")
+
+
+def is_boilerplate_dir(path: Path) -> bool:
+    """
+    Minimal structural validation for a boilerplate directory.
+    """
+    return (
+        path.is_dir()
+        and (path / "manage.py").is_file()
+        and (path / "pytest.ini").is_file()
+        and (path / "project_name").is_dir()
+    )
+
+
+def safe_text_replace_in_file(path: Path, old: str, new: str) -> bool:
+    """
+    Replace text in a file if it looks like UTF-8 text.
+
+    Returns True if the file was modified.
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return False
+
+    if old not in content:
+        return False
+
+    path.write_text(content.replace(old, new), encoding="utf-8")
+    return True
+
+
+def find_repo_root(start: Path) -> Path | None:
+    """Walk upward to find repo root (contains .git directory)."""
+    for directory in [start, *start.parents]:
+        if (directory / ".git").exists():
+            return directory
+    return None
+
+
+def safe_rmtree(path: Path, *, tmp_root: Path | None, repo_root: Path | None) -> None:
+    resolved = path.resolve()
+    if ".git" in resolved.parts:
+        raise RuntimeError(f"Refusing to delete path containing .git: {resolved}")
+    if repo_root and resolved == repo_root.resolve():
+        raise RuntimeError(f"Refusing to delete repo root: {resolved}")
+    if tmp_root and not resolved.is_relative_to(tmp_root.resolve()):
+        raise RuntimeError(
+            "Refusing to delete outside tmp root: " f"{resolved} (tmp_root={tmp_root})"
+        )
+    shutil.rmtree(resolved)

sum/utils/prompts.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PromptManager:
+    """Handle interactive prompts with support for non-interactive modes."""
+
+    no_prompt: bool = False
+    ci: bool = False
+
+    def _should_prompt(self) -> bool:
+        return not (self.no_prompt or self.ci)
+
+    def confirm(self, message: str, default: bool = True) -> bool:
+        """Ask a yes/no question and return the user's choice or the default."""
+        if not self._should_prompt():
+            return default
+
+        suffix = " [Y/n]" if default else " [y/N]"
+        response = input(f"{message}{suffix}: ").strip().lower()
+        if not response:
+            return default
+        return response in {"y", "yes"}
+
+    def text(self, message: str, default: str | None = None) -> str:
+        """Prompt for text input, returning the response or default if provided."""
+        if not self._should_prompt():
+            return default or ""
+
+        suffix = f" [{default}]" if default else ""
+        response = input(f"{message}{suffix}: ").strip()
+        if response:
+            return response
+        return default or ""

sum/utils/validation.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import cast
+
+from sum.setup.venv import VenvManager
+from sum.utils.django import DjangoCommandExecutor
+from sum.utils.environment import ExecutionMode, find_monorepo_root
+
+
+class ValidationStatus(str, Enum):
+    OK = "ok"
+    FAIL = "fail"
+    SKIP = "skip"
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    status: ValidationStatus
+    message: str
+    remediation: str | None = None
+
+    @property
+    def passed(self) -> bool:
+        return self.status is ValidationStatus.OK
+
+    @property
+    def failed(self) -> bool:
+        return self.status is ValidationStatus.FAIL
+
+    @property
+    def skipped(self) -> bool:
+        return self.status is ValidationStatus.SKIP
+
+    @classmethod
+    def ok(cls, message: str) -> ValidationResult:
+        return cls(ValidationStatus.OK, message)
+
+    @classmethod
+    def fail(cls, message: str, remediation: str | None = None) -> ValidationResult:
+        return cls(ValidationStatus.FAIL, message, remediation)
+
+    @classmethod
+    def skip(cls, message: str) -> ValidationResult:
+        return cls(ValidationStatus.SKIP, message)
+
+
+MIN_COMPILED_CSS_BYTES = 5 * 1024
+ENV_KEY_RE = re.compile(r"^([A-Z][A-Z0-9_]*)=(.*)$")
+
+
+def _parse_env_assignments(path: Path) -> dict[str, str]:
+    data: dict[str, str] = {}
+    if not path.exists():
+        return data
+
+    for raw in path.read_text(encoding="utf-8", errors="ignore").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = ENV_KEY_RE.match(line)
+        if not match:
+            continue
+        key, value = match.group(1), match.group(2)
+        data[key] = value
+    return data
+
+
+def _read_json_file(path: Path) -> tuple[dict[str, object] | None, str]:
+    if not path.exists():
+        return None, f"Missing file: {path}"
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), ""
+    except Exception as exc:  # pragma: no cover - best effort parsing
+        return None, f"Invalid JSON in {path}: {exc}"
+
+
+class ProjectValidator:
+    """Validates project setup state."""
+
+    def __init__(self, project_path: Path, mode: ExecutionMode) -> None:
+        self.project_path = project_path
+        self.mode = mode
+        self.venv_manager = VenvManager()
+
+    def check_venv_exists(self) -> ValidationResult:
+        """Check if virtualenv exists."""
+        venv_path = self.project_path / ".venv"
+        if venv_path.is_dir():
+            return ValidationResult.ok(".venv exists")
+        return ValidationResult.fail(
+            ".venv not found",
+            "Run 'sum init --full' or 'python -m venv .venv'",
+        )
+
+    def check_packages_installed(self) -> ValidationResult:
+        """Check if key packages are installed in venv."""
+        if not self.venv_manager.exists(self.project_path):
+            return ValidationResult.skip("Virtualenv missing; skipping package checks")
+
+        python = self.venv_manager.get_python_executable(self.project_path)
+        for package in ("django", "wagtail"):
+            result = subprocess.run(
+                [str(python), "-c", f"import {package}"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                return ValidationResult.fail(
+                    f"Package '{package}' not installed",
+                    "Run 'pip install -r requirements.txt'",
+                )
+
+        return ValidationResult.ok("Required packages installed")
+
+    def check_env_local(self) -> ValidationResult:
+        """Check if .env.local exists."""
+        env_local = self.project_path / ".env.local"
+        if env_local.is_file():
+            return ValidationResult.ok(".env.local found")
+        return ValidationResult.skip("No .env.local found (superuser not created)")
+
+    def check_migrations_applied(self) -> ValidationResult:
+        """Check if migrations are up to date."""
+        if not self.venv_manager.exists(self.project_path):
+            return ValidationResult.skip("Virtualenv missing; skipping migration check")
+        try:
+            executor = DjangoCommandExecutor(self.project_path, self.mode)
+            result = executor.run_command(["migrate", "--check"], check=False)
+        except Exception as exc:
+            return ValidationResult.fail(f"Migration check failed: {exc}")
+
+        if result.returncode == 0:
+            return ValidationResult.ok("Migrations up to date")
+        return ValidationResult.fail(
+            "Pending migrations",
+            "Run 'python manage.py migrate'",
+        )
+
+    def check_homepage_exists(self) -> ValidationResult:
+        """Check if homepage is set as site root."""
+        if not self.venv_manager.exists(self.project_path):
+            return ValidationResult.skip("Virtualenv missing; skipping homepage check")
+        try:
+            executor = DjangoCommandExecutor(self.project_path, self.mode)
+            script = "\n".join(
+                [
+                    "from wagtail.models import Site",
+                    "site = Site.objects.get(is_default_site=True)",
+                    "print(site.root_page.slug)",
+                ]
+            )
+            result = executor.run_command(["shell", "-c", script], check=False)
+        except Exception as exc:
+            return ValidationResult.fail(f"Homepage check failed: {exc}")
+
+        if result.returncode == 0 and result.stdout.strip() == "home":
+            return ValidationResult.ok("Homepage set as site root")
+        return ValidationResult.fail(
+            "Homepage not configured",
+            "Run 'python manage.py seed_homepage'",
+        )
+
+    def check_required_env_vars(self) -> ValidationResult:
+        """Check required env vars from .env.example are set."""
+        env_example_path = self.project_path / ".env.example"
+        required_env: dict[str, str] = _parse_env_assignments(env_example_path)
+        if not env_example_path.exists():
+            return ValidationResult.fail("Missing .env.example")
+
+        env: dict[str, str] = _parse_env_assignments(self.project_path / ".env")
+        missing: list[str] = []
+        for key in sorted(required_env.keys()):
+            if key in env:
+                continue
+            if key in os.environ and os.environ[key].strip():
+                continue
+            missing.append(str(key))
+
+        if required_env and missing:
+            missing_list: list[str] = list(missing)
+            return ValidationResult.fail(
+                "Missing required env vars",
+                "Missing: " + ", ".join(missing_list),
+            )
+        return ValidationResult.ok("Required env vars present")
+
+    def _resolve_theme_slugs(self) -> tuple[str | None, str | None, str | None]:
+        provenance_path = self.project_path / ".sum" / "theme.json"
+        provenance, provenance_err = _read_json_file(provenance_path)
+        expected_slug: str | None = None
+        if provenance is not None:
+            theme_value = provenance.get("theme")
+            if isinstance(theme_value, str) and theme_value.strip():
+                expected_slug = theme_value.strip()
+
+        theme_root = self.project_path / "theme" / "active"
+        if not theme_root.is_dir():
+            return (
+                expected_slug,
+                None,
+                f"Missing {theme_root} (expected active theme install)",
+            )
+
+        manifest_path = theme_root / "theme.json"
+        manifest, manifest_err = _read_json_file(manifest_path)
+        manifest_slug: str | None = None
+        if manifest is None:
+            return expected_slug, None, manifest_err
+
+        slug_value = manifest.get("slug")
+        if isinstance(slug_value, str) and slug_value.strip():
+            manifest_slug = slug_value.strip()
+        else:
+            return (
+                expected_slug,
+                None,
+                "Missing `slug` field in theme/active/theme.json",
+            )
+
+        if provenance is None:
+            return expected_slug, manifest_slug, provenance_err
+
+        return expected_slug, manifest_slug, None
+
+    def check_theme_slug_match(self) -> ValidationResult:
+        expected_slug, manifest_slug, error = self._resolve_theme_slugs()
+        if error:
+            return ValidationResult.fail(error)
+
+        if expected_slug and manifest_slug and expected_slug != manifest_slug:
+            return ValidationResult.fail(
+                f".sum says '{expected_slug}' but theme/active says '{manifest_slug}'"
+            )
+        if manifest_slug:
+            return ValidationResult.ok(manifest_slug)
+        return ValidationResult.fail(
+            "Could not determine theme slug (check .sum/theme.json and theme/active/theme.json)"
+        )
+
+    def check_theme_compiled_css(self) -> ValidationResult:
+        expected_slug, manifest_slug, error = self._resolve_theme_slugs()
+        if error and manifest_slug is None:
+            return ValidationResult.fail(error)
+
+        css_slug = expected_slug or manifest_slug
+        if not css_slug:
+            return ValidationResult.fail(
+                "Could not determine theme slug for static path (check .sum/theme.json and theme/active/theme.json)"
+            )
+
+        compiled_css = (
+            self.project_path
+            / "theme"
+            / "active"
+            / "static"
+            / css_slug
+            / "css"
+            / "main.css"
+        )
+        if not compiled_css.is_file():
+            return ValidationResult.fail(f"Missing {compiled_css}")
+
+        try:
+            size = compiled_css.stat().st_size
+        except OSError as exc:
+            return ValidationResult.fail(f"Could not stat {compiled_css}: {exc}")
+
+        if size <= MIN_COMPILED_CSS_BYTES:
+            return ValidationResult.fail(
+                f"File too small ({size} bytes): {compiled_css}"
+            )
+
+        return ValidationResult.ok(str(compiled_css))
+
+    def check_sum_core_import(self) -> ValidationResult:
+        monorepo_root = find_monorepo_root(self.project_path)
+        core_path_added = False
+        core_dir: Path | None = None
+        if self.mode is ExecutionMode.MONOREPO and monorepo_root is not None:
+            core_dir = monorepo_root / "core"
+            core_str = str(core_dir)
+            if core_str not in sys.path:
+                sys.path.insert(0, core_str)
+                core_path_added = True
+
+        try:
+            module = importlib.import_module("sum_core")
+            _ = module.__name__
+            if self.mode is ExecutionMode.MONOREPO and monorepo_root is not None:
+                return ValidationResult.ok("monorepo mode")
+            return ValidationResult.ok("sum_core importable")
+        except ImportError:
+            if self.mode is ExecutionMode.MONOREPO and monorepo_root is not None:
+                return ValidationResult.fail(
+                    "Failed in monorepo mode - check core/ directory structure"
+                )
+            return ValidationResult.fail(
+                "Install requirements first: pip install -r requirements.txt"
+            )
+        except Exception as exc:
+            return ValidationResult.fail(f"Failed to import sum_core: {exc}")
+        finally:
+            if core_path_added and core_dir is not None:
+                sys.path.remove(str(cast(Path, core_dir)))