sum-cli 3.0.0__py3-none-any.whl

sum/setup/scaffold.py

@@ -0,0 +1,500 @@
+# pyright: reportUnknownArgumentType=false, reportUnknownMemberType=false, reportUnusedCallResult=false, reportImplicitStringConcatenation=false
+
+"""Project scaffold and theme setup utilities."""
+
+from __future__ import annotations
+
+import importlib.resources
+import importlib.resources.abc
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import cast
+
+from sum.exceptions import SetupError, ThemeNotFoundError, ThemeValidationError
+from sum.setup.remote_themes import parse_theme_spec, resolve_remote_theme
+from sum.system_config import ConfigurationError, get_system_config
+from sum.utils.environment import find_monorepo_root
+from sum.utils.project import (
+    ProjectNaming,
+    get_packaged_boilerplate,
+    is_boilerplate_dir,
+    safe_rmtree,
+    safe_text_replace_in_file,
+    validate_project_name,
+)
+
+BoilerplateSource = Path | importlib.resources.abc.Traversable
+
+DEFAULT_THEME_SLUG = "theme_a"
+LEGACY_CORE_CSS_REF = "/static/sum_core/css/main.css"
+MIN_COMPILED_CSS_BYTES = 5 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeManifest:
+    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")
+
+
+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 exc:
+        raise ThemeValidationError(
+            f"Invalid JSON in theme manifest: {manifest_path} ({exc})"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise ThemeValidationError(f"Theme manifest must be an object: {manifest_path}")
+
+    manifest_data = cast(dict[str, object], data)
+    manifest = ThemeManifest(
+        slug=str(manifest_data.get("slug", "")).strip(),
+        name=str(manifest_data.get("name", "")).strip(),
+        description=str(manifest_data.get("description", "")).strip(),
+        version=str(manifest_data.get("version", "")).strip(),
+    )
+    try:
+        manifest.validate()
+    except ValueError as exc:
+        raise ThemeValidationError(str(exc)) from exc
+
+    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(theme_slug: str, repo_root: Path | None) -> Path:
+    """Resolve theme directory from slug, optionally with version.
+
+    Resolution order:
+    1. SUM_THEME_PATH environment variable (if set)
+    2. Monorepo themes directory (repo_root/themes/)
+    3. Current working directory (./themes/)
+    4. Remote fetch from sum-themes repository
+
+    Args:
+        theme_slug: Theme slug, optionally with version (e.g., 'theme_a' or 'theme_a@1.0.0').
+        repo_root: Optional path to monorepo root.
+
+    Returns:
+        Path to the resolved theme directory.
+
+    Raises:
+        ThemeNotFoundError: If theme cannot be found locally or remotely.
+    """
+    # Parse theme spec to extract slug and optional version
+    spec = parse_theme_spec(theme_slug)
+    slug = spec.slug
+
+    # If version is specified, skip local lookups and go straight to remote
+    # (local themes don't support versioning)
+    if spec.version is not None:
+        return resolve_remote_theme(theme_slug)
+
+    # Step 1: Check SUM_THEME_PATH environment variable
+    env = os.getenv("SUM_THEME_PATH")
+    if env:
+        path = Path(env).expanduser().resolve()
+        if not path.exists():
+            raise ThemeNotFoundError(f"SUM_THEME_PATH does not exist: {path}")
+        if (path / "theme.json").is_file():
+            return path
+        candidate = path / slug
+        if candidate.is_dir():
+            return candidate
+        raise ThemeNotFoundError(
+            f"Theme '{slug}' not found under SUM_THEME_PATH: {path}"
+        )
+
+    # Step 2: Check monorepo themes directory
+    if repo_root is not None:
+        repo_theme = repo_root / "themes" / slug
+        if repo_theme.is_dir():
+            return repo_theme
+
+    # Step 3: Check current working directory
+    cwd_theme = (Path.cwd() / "themes" / slug).resolve()
+    if cwd_theme.is_dir():
+        return cwd_theme
+
+    # Step 4: Fetch from remote sum-themes repository
+    remote_error: str | None = None
+    try:
+        return resolve_remote_theme(slug)
+    except ThemeNotFoundError as exc:
+        # Preserve the remote error details for the final message
+        remote_error = str(exc)
+
+    locations = [
+        "SUM_THEME_PATH (if set)",
+        f"{repo_root}/themes/ (monorepo)" if repo_root else None,
+        "./themes/ (current directory)",
+        "sum-themes remote repository",
+    ]
+    locations_str = "\n  - ".join(loc for loc in locations if loc)
+    message = f"Theme '{slug}' not found. Looked in:\n  - {locations_str}"
+    if remote_error:
+        message += f"\n\nRemote fetch error: {remote_error}"
+    raise ThemeNotFoundError(message)
+
+
+def _get_theme(theme_slug: str, repo_root: Path | None) -> tuple[ThemeManifest, Path]:
+    theme_dir = _resolve_theme_dir(theme_slug, repo_root)
+    return _read_manifest(theme_dir), theme_dir
+
+
+def _resolve_boilerplate_source(repo_root: Path | None) -> BoilerplateSource:
+    env_override = os.getenv("SUM_BOILERPLATE_PATH")
+    if env_override:
+        path = Path(env_override).expanduser().resolve()
+        if not is_boilerplate_dir(path):
+            message = (
+                "SUM_BOILERPLATE_PATH is set but is not a valid boilerplate dir: "
+                f"{path}"
+            )
+            raise SetupError(message)
+        return path
+
+    if repo_root is not None:
+        repo_boilerplate = repo_root / "boilerplate"
+        if is_boilerplate_dir(repo_boilerplate):
+            return repo_boilerplate
+
+    cwd_boilerplate = (Path.cwd() / "boilerplate").resolve()
+    if is_boilerplate_dir(cwd_boilerplate):
+        return cwd_boilerplate
+
+    packaged = get_packaged_boilerplate()
+    return cast(BoilerplateSource, packaged)
+
+
+def _replace_placeholders(project_root: Path, naming: ProjectNaming) -> None:
+    for dirpath, _, filenames in os.walk(project_root):
+        for filename in filenames:
+            path = Path(dirpath) / filename
+            _ = safe_text_replace_in_file(
+                path,
+                "project_name",
+                naming.python_package,
+            )
+
+
+def _rename_project_package_dir(project_root: Path, naming: ProjectNaming) -> None:
+    src = project_root / "project_name"
+    dst = project_root / naming.python_package
+    if not src.exists():
+        raise SetupError("Boilerplate is malformed: missing 'project_name/' package.")
+    if dst.exists():
+        raise SetupError(
+            f"Refusing to overwrite existing project package directory: {dst}"
+        )
+    src.rename(dst)
+
+
+def _create_env_from_example(project_root: Path) -> None:
+    env_example = project_root / ".env.example"
+    env_file = project_root / ".env"
+    if env_file.exists():
+        return
+    if env_example.exists():
+        shutil.copy2(env_example, env_file)
+
+
+def _theme_contract_errors(theme_root: Path, theme_slug: str) -> list[str]:
+    errors: list[str] = []
+
+    manifest_path = theme_root / "theme.json"
+    if not manifest_path.is_file():
+        errors.append(f"Missing theme manifest: {manifest_path}")
+
+    base_template = theme_root / "templates" / "theme" / "base.html"
+    if not base_template.is_file():
+        errors.append(f"Missing theme base template: {base_template}")
+
+    compiled_css = theme_root / "static" / theme_slug / "css" / "main.css"
+    if not compiled_css.is_file():
+        errors.append(f"Missing compiled CSS: {compiled_css}")
+    else:
+        try:
+            size = compiled_css.stat().st_size
+        except OSError as exc:
+            errors.append(f"Could not stat compiled CSS: {compiled_css} ({exc})")
+        else:
+            if size <= MIN_COMPILED_CSS_BYTES:
+                errors.append(
+                    f"Compiled CSS is unexpectedly small ({size} bytes): {compiled_css}"
+                )
+
+        try:
+            css_text = compiled_css.read_text(encoding="utf-8", errors="ignore")
+        except OSError as exc:
+            errors.append(f"Could not read compiled CSS: {compiled_css} ({exc})")
+        else:
+            if LEGACY_CORE_CSS_REF in css_text:
+                errors.append(
+                    "Compiled CSS references legacy core stylesheet "
+                    f"({LEGACY_CORE_CSS_REF}): {compiled_css}"
+                )
+
+    return errors
+
+
+def _copy_theme_to_active(
+    project_root: Path, theme_source_dir: Path, theme_slug: str
+) -> None:
+    theme_target_dir = project_root / "theme" / "active"
+    theme_parent_dir = theme_target_dir.parent
+    theme_parent_dir.mkdir(parents=True, exist_ok=True)
+
+    if theme_target_dir.exists():
+        raise SetupError(f"Theme target directory already exists: {theme_target_dir}")
+
+    ignore = shutil.ignore_patterns("node_modules")
+    with tempfile.TemporaryDirectory(prefix=f"sum-theme-{theme_slug}-") as tmp_root:
+        tmp_dir = Path(tmp_root) / theme_slug
+        shutil.copytree(theme_source_dir, tmp_dir, dirs_exist_ok=False, ignore=ignore)
+
+        errors = _theme_contract_errors(tmp_dir, theme_slug)
+        if errors:
+            raise SetupError(
+                "Theme copy validation failed:\n  - " + "\n  - ".join(errors)
+            )
+
+        shutil.move(str(tmp_dir), str(theme_target_dir))
+
+
+def _write_theme_config(
+    project_root: Path, theme_slug: str, theme_version: str
+) -> None:
+    sum_dir = project_root / ".sum"
+    sum_dir.mkdir(parents=True, exist_ok=True)
+
+    theme_config = {
+        "theme": theme_slug,
+        "original_version": theme_version,
+        "locked_at": datetime.now(UTC).isoformat(),
+    }
+
+    theme_file = sum_dir / "theme.json"
+    theme_file.write_text(
+        json.dumps(theme_config, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _resolve_seeders_dir(repo_root: Path | None) -> Path | None:
+    """Resolve the seeders package directory.
+
+    Resolution order:
+    1. Monorepo seeders directory (repo_root/seeders/)
+    2. Current working directory (./seeders/)
+
+    Returns None if seeders cannot be found (will skip seeder copy).
+    """
+    if repo_root is not None:
+        repo_seeders = repo_root / "seeders"
+        if repo_seeders.is_dir() and (repo_seeders / "__init__.py").exists():
+            return repo_seeders
+
+    cwd_seeders = (Path.cwd() / "seeders").resolve()
+    if cwd_seeders.is_dir() and (cwd_seeders / "__init__.py").exists():
+        return cwd_seeders
+
+    return None
+
+
+def _resolve_content_profile_dir(profile: str, repo_root: Path | None) -> Path | None:
+    """Resolve the content profile directory.
+
+    Resolution order:
+    1. Monorepo content directory (repo_root/content/<profile>/)
+    2. Current working directory (./content/<profile>/)
+
+    Returns None if profile cannot be found (will skip content copy).
+    """
+    if repo_root is not None:
+        repo_content = repo_root / "content" / profile
+        if repo_content.is_dir():
+            return repo_content
+
+    cwd_content = (Path.cwd() / "content" / profile).resolve()
+    if cwd_content.is_dir():
+        return cwd_content
+
+    return None
+
+
+def _copy_seeders_and_content(
+    project_path: Path,
+    seeders_dir: Path | None,
+    content_profile_dir: Path | None,
+    profile: str,
+) -> None:
+    """Copy seeders package and content profile to scaffolded project."""
+    ignore = shutil.ignore_patterns("__pycache__", "*.pyc")
+
+    if seeders_dir is not None:
+        target_seeders = project_path / "seeders"
+        shutil.copytree(seeders_dir, target_seeders, ignore=ignore)
+
+    if content_profile_dir is not None:
+        # Create content/<profile>/ structure
+        target_content = project_path / "content" / profile
+        target_content.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(content_profile_dir, target_content, ignore=ignore)
+
+
+def _configure_ci_workflows(project_path: Path) -> None:
+    """Keep only the CI workflow directory for the configured git provider.
+
+    Boilerplate contains both .github/workflows/ and .gitea/workflows/.
+    This removes the one that doesn't match the configured git_provider.
+    """
+    github_dir = project_path / ".github"
+    gitea_dir = project_path / ".gitea"
+
+    # Determine provider from config, defaulting to github if config unavailable
+    try:
+        config = get_system_config()
+        provider = config.agency.git_provider
+    except ConfigurationError:
+        # Config not available (e.g., running in test without config)
+        # Default to GitHub workflows
+        provider = "github"
+
+    if provider == "gitea":
+        # Remove GitHub workflows, keep Gitea
+        if github_dir.exists():
+            shutil.rmtree(github_dir)
+    else:
+        # Remove Gitea workflows, keep GitHub (default)
+        if gitea_dir.exists():
+            shutil.rmtree(gitea_dir)
+
+
+def scaffold_project(
+    project_name: str,
+    clients_dir: Path,
+    theme_slug: str = DEFAULT_THEME_SLUG,
+    seed_profile: str = "starter",
+) -> Path:
+    try:
+        naming = validate_project_name(project_name)
+    except ValueError as exc:
+        raise SetupError(str(exc)) from exc
+
+    project_path: Path = clients_dir / naming.slug
+    if project_path.exists():
+        raise SetupError(f"Target directory already exists: {project_path}")
+
+    repo_root = find_monorepo_root(clients_dir)
+
+    try:
+        theme_manifest, theme_source_dir = _get_theme(theme_slug, repo_root)
+    except ThemeNotFoundError as exc:
+        raise SetupError(f"Theme '{theme_slug}' does not exist.") from exc
+    except ThemeValidationError as exc:
+        raise SetupError(f"Theme '{theme_slug}' is invalid: {exc}") from exc
+
+    # Resolve seeders and content profile for the seed command
+    seeders_dir = _resolve_seeders_dir(repo_root)
+    content_profile_dir = _resolve_content_profile_dir(seed_profile, repo_root)
+
+    boilerplate_source = _resolve_boilerplate_source(repo_root)
+
+    try:
+        clients_dir.mkdir(parents=True, exist_ok=True)
+        boilerplate_ignore = shutil.ignore_patterns("__pycache__", "*.pyc")
+        if isinstance(boilerplate_source, Path):
+            if not is_boilerplate_dir(boilerplate_source):
+                raise SetupError(
+                    f"Boilerplate missing or malformed at: {boilerplate_source}"
+                )
+            shutil.copytree(
+                boilerplate_source,
+                project_path,
+                dirs_exist_ok=False,
+                ignore=boilerplate_ignore,
+            )
+        else:
+            with importlib.resources.as_file(boilerplate_source) as bp_path:
+                bp_path = Path(bp_path)
+                if not is_boilerplate_dir(bp_path):
+                    raise SetupError("Packaged boilerplate missing or malformed.")
+                shutil.copytree(
+                    bp_path,
+                    project_path,
+                    dirs_exist_ok=False,
+                    ignore=boilerplate_ignore,
+                )
+    except FileExistsError as exc:
+        raise SetupError(f"Target directory already exists: {project_path}") from exc
+    except SetupError:
+        raise
+    except Exception as exc:
+        raise SetupError(f"Failed to copy boilerplate: {exc}") from exc
+
+    try:
+        _rename_project_package_dir(project_path, naming)
+        _replace_placeholders(project_path, naming)
+        _create_env_from_example(project_path)
+        _configure_ci_workflows(project_path)
+        _copy_theme_to_active(project_path, theme_source_dir, theme_slug)
+        _write_theme_config(project_path, theme_slug, theme_manifest.version)
+        _copy_seeders_and_content(
+            project_path, seeders_dir, content_profile_dir, seed_profile
+        )
+    except Exception as exc:
+        try:
+            safe_rmtree(project_path, tmp_root=None, repo_root=repo_root)
+        except Exception:
+            # Cleanup failures should not mask the original init error.
+            pass
+        raise SetupError(f"Project created but failed to finalize init: {exc}") from exc
+
+    return project_path
+
+
+def validate_project_structure(project_path: Path) -> None:
+    if not project_path.is_dir():
+        raise SetupError(f"Project directory does not exist: {project_path}")
+
+    required_files = [
+        project_path / "manage.py",
+        project_path / "pytest.ini",
+        project_path / ".env",
+        project_path / ".env.example",
+    ]
+    for path in required_files:
+        if not path.exists():
+            raise SetupError(f"Missing required file: {path}")
+
+    theme_dir = project_path / "theme" / "active"
+    if not theme_dir.is_dir():
+        raise SetupError(f"Missing active theme directory: {theme_dir}")
+
+    theme_config = project_path / ".sum" / "theme.json"
+    if not theme_config.is_file():
+        raise SetupError(f"Missing theme config: {theme_config}")

sum/setup/seed.py

@@ -0,0 +1,110 @@
+"""Content seeding for CLI setup."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from sum.exceptions import SeedError
+from sum.utils.django import DjangoCommandExecutor
+
+
+@dataclass
+class SeedResult:
+    """Result of a seed operation."""
+
+    success: bool
+    page_id: int | None = None
+
+
+class ContentSeeder:
+    """Seeds initial Wagtail content."""
+
+    def __init__(self, django_executor: DjangoCommandExecutor) -> None:
+        self.django = django_executor
+
+    def seed_homepage(self, preset: str | None = None) -> SeedResult:
+        """Create initial homepage.
+
+        Args:
+            preset: Optional theme preset to use for seeding.
+
+        Raises:
+            SeedError: If seeding fails.
+
+        Returns:
+            SeedResult with success=True and optional page_id.
+        """
+        cmd = ["seed_homepage"]
+        if preset:
+            cmd.extend(["--preset", preset])
+
+        result = self.django.run_command(cmd, check=False)
+
+        if result.returncode != 0:
+            # Check if it's just "already exists" warning
+            if "already exists" in result.stdout.lower():
+                return SeedResult(success=True)
+            raise SeedError(f"Seeding failed: {result.stderr}")
+
+        return SeedResult(success=True, page_id=self._extract_page_id(result.stdout))
+
+    def seed_profile(self, profile: str) -> SeedResult:
+        """Run the profile-based site seeder.
+
+        Args:
+            profile: The content profile name to seed (e.g. "sage-stone").
+
+        Raises:
+            SeedError: If seeding fails.
+
+        Returns:
+            SeedResult with success=True.
+        """
+        result = self.django.run_command(["seed", profile], check=False)
+
+        if result.returncode != 0:
+            details = result.stderr or result.stdout
+            raise SeedError(f"Seeding failed: {details}")
+
+        return SeedResult(success=True)
+
+    def check_homepage_exists(self) -> bool:
+        """Check if homepage is already created.
+
+        Returns:
+            True if homepage exists, False otherwise.
+
+        Raises:
+            SeedError: If the Django shell command fails.
+        """
+        result = self.django.run_command(
+            [
+                "shell",
+                "-c",
+                (
+                    "from home.models import HomePage; "
+                    "print(HomePage.objects.filter(slug='home').exists())"
+                ),
+            ],
+            check=False,
+        )
+
+        if result.returncode != 0:
+            raise SeedError(
+                f"Failed to check homepage existence: {result.stderr or result.stdout}"
+            )
+
+        return result.stdout.strip().lower() == "true"
+
+    def _extract_page_id(self, output: str) -> int | None:
+        """Extract page ID from command output.
+
+        Args:
+            output: The command output to parse.
+
+        Returns:
+            The extracted page ID or None if not found.
+        """
+        match = re.search(r"ID: (\d+)", output)
+        return int(match.group(1)) if match else None