sum-cli 3.0.0__py3-none-any.whl

sum/boilerplate/tests/test_health.py

@@ -0,0 +1,51 @@
+"""
+Integration tests for the /health/ endpoint.
+
+This test verifies that sum_core endpoints are correctly wired into this client project.
+It validates the actual health check contract without mocking core internals.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.urls import reverse
+
+
+@pytest.mark.django_db
+def test_health_endpoint_returns_200_with_json(client) -> None:
+    """
+    Integration test: /health/ returns HTTP 200 with JSON in the healthy baseline.
+
+    This test proves that the client project correctly wires the sum_core ops endpoint
+    and validates the real health check contract (ok/degraded=200, unhealthy=503).
+    """
+    response = client.get(reverse("health_check"))
+
+    # In the baseline/healthy state, expect HTTP 200
+    assert response.status_code == 200
+
+    # Response should be JSON
+    data = response.json()
+    assert isinstance(data, dict), "Health endpoint must return JSON object"
+
+
+@pytest.mark.django_db
+def test_health_endpoint_has_required_keys(client) -> None:
+    """
+    Integration test: /health/ JSON response has required structure.
+
+    Verifies the endpoint returns 'status' and 'checks' keys without asserting
+    exact check ordering or exhaustive payload contents.
+    """
+    response = client.get(reverse("health_check"))
+    data = response.json()
+
+    # Verify required keys are present
+    assert "status" in data, "Response JSON must have 'status' key"
+    assert "checks" in data, "Response JSON must have 'checks' key"
+
+    # Verify status is a valid string (don't hardcode exact value)
+    assert isinstance(data["status"], str), "'status' must be a string"
+
+    # Verify checks is a dict (don't assert specific checks or ordering)
+    assert isinstance(data["checks"], dict), "'checks' must be a dictionary"

sum/cli.py

@@ -0,0 +1,42 @@
+"""Command-line entrypoint wiring for the SUM platform CLI."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+import click
+from sum.commands.backup import backup
+from sum.commands.check import check
+from sum.commands.init import init
+from sum.commands.promote import promote
+from sum.commands.run import run
+from sum.commands.themes import themes
+from sum.commands.update import update
+
+
+def _get_version() -> str:
+    try:
+        return importlib.metadata.version("sum-cli")
+    except importlib.metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+@click.group()
+@click.version_option(
+    version=_get_version(), prog_name="sum-platform", message="%(prog)s %(version)s"
+)
+def cli() -> None:
+    """SUM Platform CLI (v2)."""
+
+
+cli.add_command(backup)
+cli.add_command(check)
+cli.add_command(init)
+cli.add_command(promote)
+cli.add_command(run)
+cli.add_command(themes)
+cli.add_command(update)
+
+
+if __name__ == "__main__":
+    cli()

sum/commands/__init__.py

@@ -0,0 +1,10 @@
+"""CLI command implementations."""
+
+from __future__ import annotations
+
+from sum.commands.check import check
+from sum.commands.init import init
+from sum.commands.run import run
+from sum.commands.themes import themes
+
+__all__ = ["check", "init", "run", "themes"]

sum/commands/backup.py

@@ -0,0 +1,308 @@
+# pyright: reportImplicitStringConcatenation=false, reportUnusedCallResult=false
+
+"""Backup command implementation.
+
+Creates backups of site database and optionally media files.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+from types import ModuleType
+
+from sum.exceptions import SetupError
+from sum.system_config import ConfigurationError, SystemConfig, get_system_config
+from sum.utils.output import OutputFormatter
+
+click_module: ModuleType | None
+try:
+    import click as click_module
+except ImportError:  # pragma: no cover
+    click_module = None
+
+click: ModuleType | None = click_module
+
+
+def _generate_backup_filename(site_slug: str, suffix: str = "sql") -> str:
+    """Generate a timestamped backup filename."""
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    return f"{site_slug}_{timestamp}.{suffix}.gz"
+
+
+def _backup_database(
+    site_slug: str,
+    backup_dir: Path,
+    config: SystemConfig,
+) -> Path:
+    """Create a compressed database backup using pg_dump."""
+    # Fail fast if backup directory is not writable
+    if not os.access(backup_dir, os.W_OK):
+        raise SetupError(f"Backup directory is not writable: {backup_dir}")
+
+    db_name = config.get_db_name(site_slug)
+    backup_filename = _generate_backup_filename(site_slug, "sql")
+    backup_path = backup_dir / backup_filename
+
+    try:
+        # pg_dump | gzip > backup_file
+        with open(backup_path, "wb") as f:
+            pg_dump = subprocess.Popen(
+                ["sudo", "-u", "postgres", "pg_dump", db_name],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            gzip = subprocess.Popen(
+                ["gzip"],
+                stdin=pg_dump.stdout,
+                stdout=f,
+                stderr=subprocess.PIPE,
+            )
+            if pg_dump.stdout:
+                pg_dump.stdout.close()
+
+            gzip.communicate()
+            pg_dump.wait()
+
+            if pg_dump.returncode != 0:
+                stderr = pg_dump.stderr.read() if pg_dump.stderr else b""
+                raise SetupError(f"pg_dump failed: {stderr.decode()}")
+
+            if gzip.returncode != 0:
+                raise SetupError("gzip compression failed")
+
+    except OSError as exc:
+        raise SetupError(f"Failed to create backup: {exc}") from exc
+
+    return backup_path
+
+
+def _backup_media(
+    site_slug: str,
+    site_dir: Path,
+    backup_dir: Path,
+) -> Path:
+    """Create a compressed tarball of the media directory."""
+    media_dir = site_dir / "media"
+    backup_filename = _generate_backup_filename(site_slug, "media.tar")
+    backup_path = backup_dir / backup_filename
+
+    if not media_dir.exists():
+        raise SetupError(f"Media directory not found: {media_dir}")
+
+    try:
+        # tar czf backup_file -C media_dir .
+        with open(backup_path, "wb") as f:
+            tar = subprocess.Popen(
+                ["tar", "czf", "-", "-C", str(media_dir), "."],
+                stdout=f,
+                stderr=subprocess.PIPE,
+            )
+            _, stderr = tar.communicate()
+
+            if tar.returncode != 0:
+                raise SetupError(f"tar failed: {stderr.decode()}")
+
+    except OSError as exc:
+        raise SetupError(f"Failed to create media backup: {exc}") from exc
+
+    return backup_path
+
+
+def _run_remote_backup(
+    site_slug: str,
+    config: SystemConfig,
+    include_media: bool = False,
+) -> list[str]:
+    """Run backup on a remote (production) server via SSH."""
+    ssh_host = config.production.ssh_host
+    site_dir = config.get_site_dir(site_slug, target="prod")
+    backup_dir = site_dir / "backups"
+    db_name = config.get_db_name(site_slug)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+
+    backup_files: list[str] = []
+
+    # Database backup command
+    db_backup = f"{site_slug}_{timestamp}.sql.gz"
+    db_cmd = f"sudo -u postgres pg_dump {db_name} | gzip > {backup_dir}/{db_backup}"
+
+    OutputFormatter.info("Creating database backup...")
+    try:
+        subprocess.run(
+            ["ssh", ssh_host, db_cmd],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        backup_files.append(f"{backup_dir}/{db_backup}")
+    except subprocess.CalledProcessError as exc:
+        raise SetupError(f"Remote database backup failed: {exc.stderr}") from exc
+
+    # Media backup (optional)
+    if include_media:
+        media_backup = f"{site_slug}_{timestamp}.media.tar.gz"
+        media_cmd = f"tar czf {backup_dir}/{media_backup} -C {site_dir}/media ."
+
+        OutputFormatter.info("Creating media backup...")
+        try:
+            subprocess.run(
+                ["ssh", ssh_host, media_cmd],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            backup_files.append(f"{backup_dir}/{media_backup}")
+        except subprocess.CalledProcessError as exc:
+            raise SetupError(f"Remote media backup failed: {exc.stderr}") from exc
+
+    return backup_files
+
+
+def run_backup(
+    site_name: str,
+    *,
+    target: str = "staging",
+    include_media: bool = False,
+) -> int:
+    """Create a backup of site database and optionally media.
+
+    Args:
+        site_name: Name/slug of the site to backup.
+        target: 'staging' or 'prod'.
+        include_media: Also backup the media directory.
+
+    Returns:
+        Exit code (0 for success, non-zero for failure).
+    """
+    try:
+        config = get_system_config()
+    except ConfigurationError as exc:
+        OutputFormatter.error(str(exc))
+        return 1
+
+    site_dir = config.get_site_dir(site_name, target=target)
+
+    # For production, delegate to remote execution
+    if target == "prod":
+        OutputFormatter.header(f"Backing up {site_name} on production")
+        print()
+        try:
+            backup_files = _run_remote_backup(site_name, config, include_media)
+        except SetupError as exc:
+            OutputFormatter.error(str(exc))
+            return 1
+
+        print()
+        OutputFormatter.success("Backup completed:")
+        for path in backup_files:
+            print(f"  - {path}")
+        return 0
+
+    # For staging, run locally
+    backup_dir = site_dir / "backups"
+
+    # Validate site exists
+    if not site_dir.exists():
+        OutputFormatter.error(f"Site not found: {site_dir}")
+        return 1
+
+    # Ensure backup directory exists
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    OutputFormatter.header(f"Backing up {site_name} on staging")
+    print()
+
+    backup_files: list[Path] = []
+
+    try:
+        # Database backup
+        OutputFormatter.info("Creating database backup...")
+        db_backup = _backup_database(site_name, backup_dir, config)
+        backup_files.append(db_backup)
+        OutputFormatter.success(f"Database backup: {db_backup.name}")
+
+        # Media backup (optional)
+        if include_media:
+            OutputFormatter.info("Creating media backup...")
+            media_backup = _backup_media(site_name, site_dir, backup_dir)
+            backup_files.append(media_backup)
+            OutputFormatter.success(f"Media backup: {media_backup.name}")
+
+    except SetupError as exc:
+        OutputFormatter.error(str(exc))
+        return 1
+
+    print()
+    OutputFormatter.success("Backup completed:")
+    for path in backup_files:
+        size_mb = path.stat().st_size / (1024 * 1024)
+        print(f"  - {path} ({size_mb:.1f} MB)")
+
+    return 0
+
+
+def _backup_command(
+    site_name: str,
+    target: str,
+    include_media: bool,
+) -> None:
+    """Create a backup of an existing site."""
+    result = run_backup(
+        site_name,
+        target=target,
+        include_media=include_media,
+    )
+    if result != 0:
+        raise SystemExit(result)
+
+
+def _missing_click(*_args: object, **_kwargs: object) -> None:
+    raise RuntimeError("click is required to use the backup command")
+
+
+if click is None:
+    backup = _missing_click
+else:
+
+    @click.command(name="backup")
+    @click.argument("site_name")
+    @click.option(
+        "--target",
+        type=click.Choice(["staging", "prod"], case_sensitive=False),
+        default="staging",
+        show_default=True,
+        help="Target environment to backup.",
+    )
+    @click.option(
+        "--include-media",
+        is_flag=True,
+        help="Also backup the media directory.",
+    )
+    def _click_backup(
+        site_name: str,
+        target: str,
+        include_media: bool,
+    ) -> None:
+        """Create a backup of site database and media.
+
+        Creates a compressed backup of the PostgreSQL database.
+        Optionally includes the media directory.
+
+        Backups are stored in /srv/sum/<site>/backups/
+
+        \b
+        Examples:
+          sum-platform backup acme
+          sum-platform backup acme --include-media
+          sum-platform backup acme --target prod
+        """
+        _backup_command(
+            site_name,
+            target=target,
+            include_media=include_media,
+        )
+
+    backup = _click_backup

sum/commands/check.py

@@ -0,0 +1,128 @@
+"""Check command for validating SUM project readiness."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+from sum.utils.environment import ExecutionMode, detect_mode, resolve_project_path
+from sum.utils.validation import ProjectValidator, ValidationResult, ValidationStatus
+
+
+def _resolve_project_path(project: str | None) -> Path:
+    return resolve_project_path(project)
+
+
+def _format_status(status: ValidationStatus) -> str:
+    if status is ValidationStatus.OK:
+        return "[OK]"
+    if status is ValidationStatus.SKIP:
+        return "[SKIP]"
+    return "[FAIL]"
+
+
+def _virtualenv_check(validator: ProjectValidator) -> ValidationResult:
+    venv_result = validator.check_venv_exists()
+    if venv_result.failed:
+        return venv_result
+
+    package_result = validator.check_packages_installed()
+    if package_result.failed or package_result.skipped:
+        return package_result
+
+    return ValidationResult.ok(".venv exists with required packages")
+
+
+def run_enhanced_checks(project_path: Path, mode: ExecutionMode) -> None:
+    """Run enhanced validation checks.
+
+    Example:
+        run_enhanced_checks(Path('clients/demo'), ExecutionMode.STANDALONE)
+    """
+    validator = ProjectValidator(project_path, mode)
+
+    checks: list[tuple[str, Callable[[], ValidationResult]]] = [
+        ("Virtualenv", lambda: _virtualenv_check(validator)),
+        ("Credentials", validator.check_env_local),
+        ("Database", validator.check_migrations_applied),
+        ("Homepage", validator.check_homepage_exists),
+        ("Theme compiled CSS", validator.check_theme_compiled_css),
+        ("Theme slug match", validator.check_theme_slug_match),
+        ("Required env vars", validator.check_required_env_vars),
+        ("sum_core import", validator.check_sum_core_import),
+    ]
+
+    has_failures = False
+
+    for name, check_func in checks:
+        result = check_func()
+        status = _format_status(result.status)
+        click.echo(f"{status} {name}: {result.message}")
+        if result.failed and result.remediation:
+            click.echo(f"      → {result.remediation}")
+            has_failures = True
+        elif result.failed:
+            has_failures = True
+
+    if has_failures:
+        click.echo("\n❌ Some checks failed")
+        sys.exit(1)
+
+    click.echo("\n✅ All checks passed")
+
+
+def run_check(project_path: str | Path | None = None) -> int:
+    """V1-compatible check that returns exit code instead of calling sys.exit.
+
+    Note: This runs a reduced check set (6 checks) for backward compatibility.
+    Omits Virtualenv and Database checks which require Django environment setup.
+    For full validation (8 checks), use run_enhanced_checks() instead.
+    """
+    try:
+        path = _resolve_project_path(str(project_path) if project_path else None)
+    except FileNotFoundError:
+        return 1
+    mode = detect_mode(path)
+    validator = ProjectValidator(path, mode)
+
+    checks: list[tuple[str, Callable[[], ValidationResult]]] = [
+        ("Credentials", validator.check_env_local),
+        ("Homepage", validator.check_homepage_exists),
+        ("Theme compiled CSS", validator.check_theme_compiled_css),
+        ("Theme slug match", validator.check_theme_slug_match),
+        ("Required env vars", validator.check_required_env_vars),
+        ("sum_core import", validator.check_sum_core_import),
+    ]
+
+    has_failures = False
+    for name, check_func in checks:
+        result = check_func()
+        status = _format_status(result.status)
+        click.echo(f"{status} {name}: {result.message}")
+        if result.failed and result.remediation:
+            click.echo(f"      → {result.remediation}")
+            has_failures = True
+        elif result.failed:
+            has_failures = True
+
+    if has_failures:
+        click.echo("\n❌ Some checks failed")
+        return 1
+
+    click.echo("\n✅ All checks passed")
+    return 0
+
+
+@click.command()
+@click.argument("project", required=False)
+def check(project: str | None) -> None:
+    """Validate project setup."""
+    try:
+        path = _resolve_project_path(project)
+    except FileNotFoundError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        raise SystemExit(1)
+    mode = detect_mode(path)
+    run_enhanced_checks(path, mode)