sum-cli 3.0.0__py3-none-any.whl

sum/setup/remote_themes.py

@@ -0,0 +1,371 @@
+# pyright: reportUnusedCallResult=false
+
+"""Remote theme fetching from sum-themes distribution repository."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from sum.exceptions import SetupError, ThemeNotFoundError
+
+# Default repository URL, can be overridden via environment variable
+DEFAULT_SUM_THEMES_REPO = "https://github.com/markashton480/sum-themes.git"
+CACHE_DIR_NAME = "sum-platform"
+THEMES_CACHE_SUBDIR = "themes"
+
+# Timeout for git network operations (in seconds)
+GIT_NETWORK_TIMEOUT = 120
+
+# Valid theme slug pattern: lowercase letters, numbers, underscores, hyphens
+# Must start with a letter
+THEME_SLUG_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+def _get_themes_repo_url() -> str:
+    """Get the themes repository URL from environment or default."""
+    return os.getenv("SUM_THEMES_REPO", DEFAULT_SUM_THEMES_REPO)
+
+
+def _validate_theme_slug(slug: str) -> None:
+    """Validate that a theme slug contains only safe characters.
+
+    Prevents directory traversal attacks and command injection.
+
+    Args:
+        slug: Theme slug to validate.
+
+    Raises:
+        ThemeNotFoundError: If the slug contains invalid characters.
+    """
+    if not THEME_SLUG_PATTERN.match(slug):
+        raise ThemeNotFoundError(
+            f"Invalid theme slug: {slug!r}. "
+            f"Must match pattern: [a-z][a-z0-9_-]* (lowercase, start with letter)"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeSpec:
+    """Parsed theme specification with slug and optional version."""
+
+    slug: str
+    version: str | None
+
+    def __str__(self) -> str:
+        if self.version:
+            return f"{self.slug}@{self.version}"
+        return self.slug
+
+
+def parse_theme_spec(theme_input: str) -> ThemeSpec:
+    """Parse theme specification like 'theme_a' or 'theme_a@1.0.0'.
+
+    Args:
+        theme_input: Theme slug, optionally with version suffix.
+
+    Returns:
+        ThemeSpec with parsed slug and version.
+
+    Raises:
+        ThemeNotFoundError: If the input is empty or malformed.
+    """
+    theme_input = theme_input.strip()
+    if not theme_input:
+        raise ThemeNotFoundError("Theme slug cannot be empty")
+
+    if "@" in theme_input:
+        parts = theme_input.split("@", 1)
+        slug = parts[0].strip()
+        version = parts[1].strip()
+        if not slug:
+            raise ThemeNotFoundError("Theme slug cannot be empty")
+        if not version:
+            raise ThemeNotFoundError("Version cannot be empty when @ is used")
+        _validate_theme_slug(slug)
+        # Strip leading 'v' if present for consistency
+        if version.startswith("v"):
+            version = version[1:]
+        return ThemeSpec(slug=slug, version=version)
+
+    _validate_theme_slug(theme_input)
+    return ThemeSpec(slug=theme_input, version=None)
+
+
+def get_cache_dir() -> Path:
+    """Get the theme cache directory, creating it if needed.
+
+    Returns:
+        Path to ~/.cache/sum-platform/themes/
+
+    Raises:
+        SetupError: If the cache directory cannot be created.
+    """
+    cache_root = Path.home() / ".cache" / CACHE_DIR_NAME / THEMES_CACHE_SUBDIR
+    try:
+        cache_root.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise SetupError(
+            f"Failed to create theme cache directory '{cache_root}': {exc}. "
+            f"Check filesystem permissions and available disk space."
+        ) from exc
+    return cache_root
+
+
+def get_cached_theme(slug: str, version: str) -> Path | None:
+    """Check if a theme version is already cached.
+
+    Args:
+        slug: Theme slug (e.g., 'theme_a').
+        version: Theme version (e.g., '1.0.0').
+
+    Returns:
+        Path to cached theme if it exists and is valid, None otherwise.
+    """
+    cache_dir = get_cache_dir()
+    theme_path = cache_dir / slug / version
+    if theme_path.is_dir() and (theme_path / "theme.json").is_file():
+        return theme_path
+    return None
+
+
+def _run_git_command(
+    args: list[str],
+    cwd: Path | None = None,
+    check: bool = True,
+    timeout: int | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run a git command and return the result.
+
+    Args:
+        args: Git command arguments (without 'git' prefix).
+        cwd: Working directory for the command.
+        check: Whether to raise on non-zero exit code.
+        timeout: Command timeout in seconds (None for no timeout).
+
+    Returns:
+        Completed process result.
+
+    Raises:
+        subprocess.CalledProcessError: If check=True and command fails.
+        subprocess.TimeoutExpired: If command exceeds timeout.
+    """
+    cmd = ["git"] + args
+    return subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=check,
+        timeout=timeout,
+    )
+
+
+def get_latest_theme_tag(slug: str) -> str | None:
+    """Find the latest version tag for a theme in sum-themes repo.
+
+    Tags are expected in format: {slug}/v{version} (e.g., theme_a/v1.0.0)
+
+    Args:
+        slug: Theme slug to find tags for.
+
+    Returns:
+        Latest version string (without 'v' prefix) or None if no tags found.
+    """
+    repo_url = _get_themes_repo_url()
+    try:
+        result = _run_git_command(
+            ["ls-remote", "--tags", repo_url, f"refs/tags/{slug}/*"],
+            check=True,
+            timeout=GIT_NETWORK_TIMEOUT,
+        )
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        return None
+
+    if not result.stdout.strip():
+        return None
+
+    # Parse tags and find the latest version
+    # Format: <hash>\trefs/tags/{slug}/v{version}
+    tag_pattern = re.compile(rf"refs/tags/{re.escape(slug)}/v([\d.]+)$")
+    versions: list[tuple[int, ...]] = []
+    version_strings: dict[tuple[int, ...], str] = {}
+
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            continue
+        ref = parts[1]
+        match = tag_pattern.search(ref)
+        if match:
+            version_str = match.group(1)
+            try:
+                version_tuple = tuple(int(p) for p in version_str.split("."))
+                versions.append(version_tuple)
+                version_strings[version_tuple] = version_str
+            except ValueError:
+                continue
+
+    if not versions:
+        return None
+
+    # Sort versions and return the latest
+    versions.sort(reverse=True)
+    return version_strings[versions[0]]
+
+
+def fetch_theme_from_repo(slug: str, version: str | None = None) -> Path:
+    """Fetch a theme from the sum-themes distribution repository.
+
+    Uses sparse checkout to fetch only the theme directory.
+    Caches the result in ~/.cache/sum-platform/themes/{slug}/{version}/
+
+    Args:
+        slug: Theme slug (e.g., 'theme_a').
+        version: Optional version string. If None, fetches latest.
+
+    Returns:
+        Path to the fetched (and cached) theme directory.
+
+    Raises:
+        ThemeNotFoundError: If theme or version cannot be found/fetched.
+    """
+    repo_url = _get_themes_repo_url()
+
+    # Resolve version if not provided
+    if version is None:
+        version = get_latest_theme_tag(slug)
+        if version is None:
+            raise ThemeNotFoundError(
+                f"No version tags found for theme '{slug}' in {repo_url}"
+            )
+
+    # Check cache first
+    cached = get_cached_theme(slug, version)
+    if cached is not None:
+        return cached
+
+    # Prepare cache directory
+    cache_dir = get_cache_dir()
+    theme_cache_root = cache_dir / slug
+    try:
+        theme_cache_root.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ThemeNotFoundError(
+            f"Failed to create theme cache directory '{theme_cache_root}': {exc}"
+        ) from exc
+    version_dir = theme_cache_root / version
+
+    # Determine git ref (tag format: {slug}/v{version})
+    git_ref = f"{slug}/v{version}"
+
+    # Use temp directory for clone
+    with tempfile.TemporaryDirectory(prefix=f"sum-theme-{slug}-") as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        clone_path = tmp_path / "repo"
+
+        try:
+            # Initialize sparse checkout with timeout for network operations
+            _run_git_command(
+                [
+                    "clone",
+                    "--filter=blob:none",
+                    "--sparse",
+                    "--depth=1",
+                    "--branch",
+                    git_ref,
+                    repo_url,
+                    str(clone_path),
+                ],
+                check=True,
+                timeout=GIT_NETWORK_TIMEOUT,
+            )
+
+            # Configure sparse checkout for just this theme (local, no timeout needed)
+            _run_git_command(
+                ["sparse-checkout", "set", slug],
+                cwd=clone_path,
+                check=True,
+            )
+
+        except subprocess.TimeoutExpired as exc:
+            raise ThemeNotFoundError(
+                f"Timeout while fetching theme '{slug}' from {repo_url}. "
+                f"Check your network connection."
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            # Check if it's a tag not found error
+            stderr = exc.stderr or ""
+            if (
+                "Could not find remote branch" in stderr
+                or "not found" in stderr.lower()
+            ):
+                raise ThemeNotFoundError(
+                    f"Theme '{slug}' version '{version}' not found in {repo_url}"
+                ) from exc
+            raise ThemeNotFoundError(
+                f"Failed to fetch theme '{slug}': {stderr}"
+            ) from exc
+
+        # Verify theme directory exists in checkout
+        theme_source = clone_path / slug
+        if not theme_source.is_dir():
+            raise ThemeNotFoundError(
+                f"Theme directory '{slug}' not found in repository at ref '{git_ref}'"
+            )
+
+        # Verify theme.json exists
+        if not (theme_source / "theme.json").is_file():
+            raise ThemeNotFoundError(
+                f"Theme '{slug}' at version '{version}' is missing theme.json"
+            )
+
+        # Move to cache with error handling
+        if version_dir.exists():
+            try:
+                shutil.rmtree(version_dir)
+            except OSError as exc:
+                raise ThemeNotFoundError(
+                    f"Failed to remove existing theme cache at '{version_dir}': {exc}"
+                ) from exc
+
+        try:
+            moved_path = Path(shutil.move(str(theme_source), str(version_dir)))
+        except OSError as exc:
+            raise ThemeNotFoundError(
+                f"Failed to move theme to cache at '{version_dir}': {exc}"
+            ) from exc
+
+        # Verify the theme ended up where expected
+        if moved_path.resolve() != version_dir.resolve():
+            raise ThemeNotFoundError(
+                f"Theme cache path mismatch for '{slug}' version '{version}': "
+                f"expected '{version_dir}', got '{moved_path}'"
+            )
+
+    return version_dir
+
+
+def resolve_remote_theme(theme_input: str) -> Path:
+    """Resolve a theme specification to a local path, fetching if needed.
+
+    This is the main entry point for remote theme resolution.
+
+    Args:
+        theme_input: Theme specification (e.g., 'theme_a' or 'theme_a@1.0.0').
+
+    Returns:
+        Path to the theme directory (either cached or freshly fetched).
+
+    Raises:
+        ThemeNotFoundError: If theme cannot be resolved or fetched.
+    """
+    spec = parse_theme_spec(theme_input)
+    return fetch_theme_from_repo(spec.slug, spec.version)