sum-cli 3.0.0__py3-none-any.whl

sum/boilerplate/project_name/home/migrations/__init__.py

@@ -0,0 +1,3 @@
+"""
+Migrations package for the home app.
+"""

sum/boilerplate/project_name/home/models.py

@@ -0,0 +1,13 @@
+"""
+HomePage model for this client project.
+
+Re-exports the HomePage from sum_core.pages. The actual implementation is in
+sum_core, which ships to clients via pip install sum-core.
+
+This module exists so the 'home' app is properly registered in INSTALLED_APPS
+and Django's model discovery finds the HomePage model.
+"""
+
+from sum_core.pages.home import HomePage, HomePageHeroCTA
+
+__all__ = ["HomePage", "HomePageHeroCTA"]

sum/boilerplate/project_name/settings/__init__.py

@@ -0,0 +1,5 @@
+"""
+Settings package for multi-environment configuration.
+
+This package allows different settings modules for local and production environments.
+"""

sum/boilerplate/project_name/settings/base.py

@@ -0,0 +1,348 @@
+"""
+Base Django/Wagtail settings shared across all environments.
+
+This file contains settings common to both local development and production.
+Environment-specific settings should be placed in local.py or production.py.
+
+Replace 'project_name' with your actual project name after copying.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from django.core.exceptions import ImproperlyConfigured
+
+# =============================================================================
+# Core Django Settings
+# =============================================================================
+
+BASE_DIR: Path = Path(__file__).resolve().parent.parent.parent
+
+# =============================================================================
+# Theme Configuration
+# =============================================================================
+#
+# Per THEME-ARCHITECTURE-SPECv1, themes are copied into the client project
+# at init-time. Runtime template/static resolution uses theme/active/, NOT
+# sum_core. The .sum/theme.json file is for provenance tracking only.
+#
+
+
+def _get_canonical_theme_root() -> Path | None:
+    """
+    Optional dev override to load templates/static directly from canonical theme.
+
+    Controlled via SUM_CANONICAL_THEME_ROOT. If set, we validate the path and
+    prefer canonical assets ahead of theme/active.
+    """
+
+    canonical_root_env = os.getenv("SUM_CANONICAL_THEME_ROOT")
+    if not canonical_root_env:
+        return None
+
+    canonical_root = Path(canonical_root_env)
+    templates_dir = canonical_root / "templates"
+
+    if not canonical_root.exists():
+        raise ImproperlyConfigured(
+            f"SUM_CANONICAL_THEME_ROOT='{canonical_root_env}' does not exist. "
+            "Expected <root>/templates and optional <root>/static. "
+            "Unset SUM_CANONICAL_THEME_ROOT to disable."
+        )
+
+    if not templates_dir.exists():
+        raise ImproperlyConfigured(
+            f"SUM_CANONICAL_THEME_ROOT='{canonical_root_env}' is missing required "
+            "<root>/templates. Expected layout: <root>/templates and optional "
+            "<root>/static. Unset SUM_CANONICAL_THEME_ROOT to disable."
+        )
+
+    return canonical_root
+
+
+def _get_project_theme_slug() -> str | None:
+    """
+    Read the selected theme slug from .sum/theme.json for logging/debugging.
+
+    This is provenance only - not used for runtime loading.
+
+    Returns:
+        Theme slug if configured, None otherwise
+    """
+    theme_file = BASE_DIR / ".sum" / "theme.json"
+    if not theme_file.exists():
+        return None
+
+    try:
+        with theme_file.open("r", encoding="utf-8") as f:
+            config = json.load(f)
+        theme_value = config.get("theme")
+        return theme_value if isinstance(theme_value, str) else None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _get_theme_template_dirs() -> list[Path]:
+    """
+    Get template directories for the active theme.
+
+    Per THEME-ARCHITECTURE-SPECv1, templates are resolved from:
+    0. SUM_CANONICAL_THEME_ROOT/templates (optional dev override, highest priority)
+    1. theme/active/templates/ (client-owned theme)
+    2. templates/overrides/ (client-specific overrides)
+    3. APP_DIRS (sum_core fallback)
+
+    Returns:
+        List of theme template directory paths (empty if no theme installed)
+    """
+    canonical_theme_root = _get_canonical_theme_root()
+
+    theme_template_dirs: list[Path] = []
+    if canonical_theme_root:
+        theme_template_dirs.append(canonical_theme_root / "templates")
+
+    theme_templates_dir = BASE_DIR / "theme" / "active" / "templates"
+    if theme_templates_dir.exists():
+        theme_template_dirs.append(theme_templates_dir)
+
+    return theme_template_dirs
+
+
+# Theme slug from provenance (for logging/debugging only)
+THEME_SLUG = _get_project_theme_slug()
+
+# SECURITY WARNING: keep the secret key used in production secret!
+# Override this via environment variable in production
+SECRET_KEY: str = os.getenv(
+    "DJANGO_SECRET_KEY", "insecure-dev-only-change-in-production"
+)
+
+# =============================================================================
+# Application Definition
+# =============================================================================
+
+INSTALLED_APPS: list[str] = [
+    # Django core
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    # Wagtail core
+    "wagtail",
+    "wagtail.admin",
+    "wagtail.users",
+    "wagtail.images",
+    "wagtail.documents",
+    "wagtail.snippets",
+    "wagtail.sites",
+    "wagtail.search",
+    "wagtail.contrib.forms",
+    "wagtail.contrib.settings",
+    "wagtail.contrib.redirects",
+    # Wagtail dependencies
+    "modelcluster",
+    "taggit",
+    # SUM Core apps (the reusable platform package)
+    "sum_core",
+    "sum_core.pages",
+    "sum_core.banners",
+    "sum_core.navigation",
+    "sum_core.leads",
+    "sum_core.forms",
+    "sum_core.analytics",
+    "sum_core.seo",
+    "sum_core.seo_engine",
+    # Client home app (update after renaming project_name)
+    "project_name.home",
+]
+
+MIDDLEWARE: list[str] = [
+    "sum_core.ops.middleware.CorrelationIdMiddleware",  # Request correlation
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+    "wagtail.contrib.redirects.middleware.RedirectMiddleware",
+]
+
+ROOT_URLCONF: str = "project_name.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [
+            # Per THEME-ARCHITECTURE-SPECv1, resolution order:
+            # 0. SUM_CANONICAL_THEME_ROOT/templates (optional dev override)
+            # 1. theme/active/templates/ (client-owned theme)
+            # 2. templates/overrides/ (client-specific overrides)
+            # 3. APP_DIRS (sum_core fallback)
+            *_get_theme_template_dirs(),
+            BASE_DIR / "templates" / "overrides",
+        ],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION: str = "project_name.wsgi.application"
+
+# =============================================================================
+# Password Validation
+# =============================================================================
+
+AUTH_PASSWORD_VALIDATORS: list[dict[str, str]] = [
+    {
+        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
+    },
+]
+
+# =============================================================================
+# Internationalization
+# =============================================================================
+
+LANGUAGE_CODE: str = "en-gb"
+TIME_ZONE: str = "Europe/London"
+USE_I18N: bool = True
+USE_TZ: bool = True
+
+# =============================================================================
+# Static & Media Files
+# =============================================================================
+
+
+def _get_theme_static_dirs() -> list[Path]:
+    """
+    Get static directories for the active theme.
+
+    Per THEME-ARCHITECTURE-SPECv1, static files are resolved from:
+    0. SUM_CANONICAL_THEME_ROOT/static/ (optional dev override, highest priority)
+    1. theme/active/static/ (client-owned theme, highest priority)
+    2. static/ (client-specific statics)
+    3. APP_DIRS (sum_core fallback)
+
+    Returns:
+        List of theme static directory paths (empty if no theme installed)
+    """
+    canonical_theme_root = _get_canonical_theme_root()
+
+    static_dirs: list[Path] = []
+    if canonical_theme_root:
+        canonical_static_dir = canonical_theme_root / "static"
+        if canonical_static_dir.exists():
+            static_dirs.append(canonical_static_dir)
+
+    theme_static_dir = BASE_DIR / "theme" / "active" / "static"
+    if theme_static_dir.exists():
+        static_dirs.append(theme_static_dir)
+
+    return static_dirs
+
+
+STATIC_URL: str = "/static/"
+STATICFILES_DIRS: list[Path] = [
+    # Per THEME-ARCHITECTURE-SPECv1, resolution order:
+    # 0. SUM_CANONICAL_THEME_ROOT/static/ (optional dev override)
+    # 1. theme/active/static/ (client-owned theme, highest priority)
+    # 2. static/ (client-specific statics)
+    *_get_theme_static_dirs(),
+    BASE_DIR / "static",
+]
+STATIC_ROOT: Path = Path(os.getenv("DJANGO_STATIC_ROOT", str(BASE_DIR / "staticfiles")))
+
+MEDIA_URL: str = "/media/"
+MEDIA_ROOT: Path = Path(os.getenv("DJANGO_MEDIA_ROOT", str(BASE_DIR / "media")))
+
+DEFAULT_AUTO_FIELD: str = "django.db.models.BigAutoField"
+
+# =============================================================================
+# Wagtail Settings
+# =============================================================================
+
+# TODO: Update this to your site name
+WAGTAIL_SITE_NAME: str = "My Site"
+WAGTAIL_ENABLE_UPDATE_CHECK: str = "lts"
+WAGTAILADMIN_BASE_URL: str = os.getenv("WAGTAILADMIN_BASE_URL", "http://localhost:8001")
+
+# =============================================================================
+# Cache Configuration (used for rate limiting)
+# =============================================================================
+
+CACHES = {
+    "default": {
+        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "LOCATION": "sum-core-cache",
+    }
+}
+
+# =============================================================================
+# File Upload Limits
+# =============================================================================
+
+FILE_UPLOAD_MAX_MEMORY_SIZE: int = 52_428_800  # 50MB
+DATA_UPLOAD_MAX_MEMORY_SIZE: int = 52_428_800  # 50MB
+
+# =============================================================================
+# Django 6.0 Compatibility
+# =============================================================================
+
+# Silence Django 6.0 deprecation warning about URL scheme
+# Default scheme will change from 'http' to 'https' in Django 6.0
+FORMS_URLFIELD_ASSUME_HTTPS: bool = True
+
+# =============================================================================
+# Celery Configuration (defaults for development)
+# =============================================================================
+
+CELERY_BROKER_URL: str = os.getenv("CELERY_BROKER_URL", "memory://")
+CELERY_RESULT_BACKEND: str = os.getenv("CELERY_RESULT_BACKEND", "cache+memory://")
+
+# =============================================================================
+# Email Configuration (defaults for development)
+# =============================================================================
+
+EMAIL_BACKEND: str = os.getenv(
+    "EMAIL_BACKEND", "django.core.mail.backends.console.EmailBackend"
+)
+EMAIL_HOST: str = os.getenv("EMAIL_HOST", "localhost")
+EMAIL_PORT: int = int(os.getenv("EMAIL_PORT", "25"))
+EMAIL_HOST_USER: str = os.getenv("EMAIL_HOST_USER", "")
+EMAIL_HOST_PASSWORD: str = os.getenv("EMAIL_HOST_PASSWORD", "")
+EMAIL_USE_TLS: bool = os.getenv("EMAIL_USE_TLS", "False").lower() == "true"
+EMAIL_USE_SSL: bool = os.getenv("EMAIL_USE_SSL", "False").lower() == "true"
+DEFAULT_FROM_EMAIL: str = os.getenv("DEFAULT_FROM_EMAIL", "noreply@example.com")
+
+# =============================================================================
+# Lead Notification Settings
+# =============================================================================
+
+LEAD_NOTIFICATION_EMAIL: str = os.getenv("LEAD_NOTIFICATION_EMAIL", "")
+
+# =============================================================================
+# Webhook Configuration
+# =============================================================================
+
+ZAPIER_WEBHOOK_URL: str = os.getenv("ZAPIER_WEBHOOK_URL", "")

sum/boilerplate/project_name/settings/local.py

@@ -0,0 +1,78 @@
+"""
+Local development settings.
+
+This file contains settings for local development and staging.
+Requires PostgreSQL - configure via environment variables in .env file.
+"""
+
+from __future__ import annotations
+
+import os
+
+from sum_core.ops.logging import get_logging_config
+from sum_core.ops.sentry import init_sentry
+
+from .base import *  # noqa: F401, F403
+
+# =============================================================================
+# Debug Settings
+# =============================================================================
+
+DEBUG: bool = True
+ALLOWED_HOSTS: list[str] = ["localhost", "127.0.0.1", "[::1]", "testserver"]
+
+# Support additional hosts via environment variable (e.g., for ngrok, custom domains)
+_allowed_hosts_extra = os.getenv("ALLOWED_HOSTS_EXTRA", "")
+if _allowed_hosts_extra:
+    ALLOWED_HOSTS.extend(
+        host.strip() for host in _allowed_hosts_extra.split(",") if host.strip()
+    )
+
+# CSRF trusted origins for local dev with tunnels/custom domains
+CSRF_TRUSTED_ORIGINS: list[str] = [
+    origin.strip()
+    for origin in os.getenv("CSRF_TRUSTED_ORIGINS", "").split(",")
+    if origin.strip()
+]
+
+# =============================================================================
+# Database - PostgreSQL (configured via environment variables)
+# =============================================================================
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": os.environ["DJANGO_DB_NAME"],
+        "USER": os.environ["DJANGO_DB_USER"],
+        "PASSWORD": os.environ["DJANGO_DB_PASSWORD"],
+        "HOST": os.environ.get("DJANGO_DB_HOST", "localhost"),
+        "PORT": os.environ.get("DJANGO_DB_PORT", "5432"),
+    }
+}
+
+# =============================================================================
+# Cache - Local memory cache for development
+# =============================================================================
+
+CACHES = {
+    "default": {
+        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "LOCATION": "client-cache",
+    }
+}
+
+# =============================================================================
+# Celery - Run tasks synchronously for local development
+# =============================================================================
+
+CELERY_TASK_ALWAYS_EAGER: bool = True
+CELERY_TASK_EAGER_PROPAGATES: bool = True
+
+# =============================================================================
+# Observability (sum_core.ops)
+# =============================================================================
+
+LOGGING = get_logging_config(debug=DEBUG)
+
+# Initialize Sentry if SENTRY_DSN is set (no-ops otherwise)
+init_sentry()

sum/boilerplate/project_name/settings/production.py

@@ -0,0 +1,106 @@
+"""
+Production settings.
+
+This file contains settings for production deployments.
+All sensitive values must be provided via environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+
+from sum_core.ops.logging import get_logging_config
+from sum_core.ops.sentry import init_sentry
+
+from .base import *  # noqa: F401, F403
+
+# =============================================================================
+# Security Settings
+# =============================================================================
+
+DEBUG: bool = False
+
+# SECURITY: ALLOWED_HOSTS must be set in production
+ALLOWED_HOSTS: list[str] = [
+    host.strip() for host in os.getenv("ALLOWED_HOSTS", "").split(",") if host.strip()
+]
+
+# SECURITY: Enforce HTTPS
+SECURE_SSL_REDIRECT: bool = os.getenv("SECURE_SSL_REDIRECT", "True").lower() == "true"
+SESSION_COOKIE_SECURE: bool = True
+CSRF_COOKIE_SECURE: bool = True
+SECURE_BROWSER_XSS_FILTER: bool = True
+SECURE_CONTENT_TYPE_NOSNIFF: bool = True
+X_FRAME_OPTIONS: str = "DENY"
+
+# HSTS settings
+SECURE_HSTS_SECONDS: int = 31536000  # 1 year
+SECURE_HSTS_INCLUDE_SUBDOMAINS: bool = True
+SECURE_HSTS_PRELOAD: bool = True
+
+# SECURITY: CSRF trusted origins for reverse proxy deployments
+CSRF_TRUSTED_ORIGINS: list[str] = [
+    origin.strip()
+    for origin in os.getenv("CSRF_TRUSTED_ORIGINS", "").split(",")
+    if origin.strip()
+]
+
+# SECURITY: Trust X-Forwarded-Proto header from reverse proxy (Caddy, nginx, AWS ALB)
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+
+# =============================================================================
+# Database - PostgreSQL for production
+# =============================================================================
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": os.environ["DJANGO_DB_NAME"],
+        "USER": os.environ["DJANGO_DB_USER"],
+        "PASSWORD": os.environ["DJANGO_DB_PASSWORD"],
+        "HOST": os.environ["DJANGO_DB_HOST"],
+        "PORT": os.getenv("DJANGO_DB_PORT", "5432"),
+        "CONN_MAX_AGE": 60,
+        "OPTIONS": {
+            "connect_timeout": 10,
+        },
+    }
+}
+
+# =============================================================================
+# Cache - Redis for production
+# =============================================================================
+
+REDIS_URL: str = os.getenv("REDIS_URL", "redis://localhost:6379/0")
+
+CACHES = {
+    "default": {
+        "BACKEND": "django.core.cache.backends.redis.RedisCache",
+        "LOCATION": REDIS_URL,
+    }
+}
+
+# =============================================================================
+# Celery - Production broker configuration
+# =============================================================================
+
+CELERY_BROKER_URL = os.environ.get("CELERY_BROKER_URL", REDIS_URL)  # noqa: F405
+CELERY_RESULT_BACKEND = os.environ.get("CELERY_RESULT_BACKEND", REDIS_URL)  # noqa: F405
+CELERY_TASK_ALWAYS_EAGER: bool = False
+CELERY_TASK_EAGER_PROPAGATES: bool = False
+
+# =============================================================================
+# Static Files - Production configuration
+# =============================================================================
+
+# In production, static files should be served by a CDN or whitenoise
+# This is a basic setup; extend as needed for your infrastructure
+
+# =============================================================================
+# Observability (sum_core.ops)
+# =============================================================================
+
+LOGGING = get_logging_config(debug=DEBUG)
+
+# Initialize Sentry (required in production if SENTRY_DSN is set)
+init_sentry()

sum/boilerplate/project_name/urls.py

@@ -0,0 +1,33 @@
+"""
+URL routing for this client project.
+
+Includes all sum_core endpoints plus Wagtail page serving.
+Replace 'project_name' with your actual project name after copying.
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.conf.urls.static import static
+from django.contrib import admin
+from django.urls import include, path
+from wagtail import urls as wagtail_urls
+from wagtail.admin import urls as wagtailadmin_urls
+from wagtail.documents import urls as wagtaildocs_urls
+
+urlpatterns = [
+    # Django admin (for FormConfiguration etc.)
+    path("django-admin/", admin.site.urls),
+    # Wagtail admin
+    path("admin/", include(wagtailadmin_urls)),
+    path("documents/", include(wagtaildocs_urls)),
+    # SUM Core endpoints
+    path("forms/", include("sum_core.forms.urls")),  # Form submissions
+    path("", include("sum_core.ops.urls")),  # /health/
+    path("", include("sum_core.seo.urls")),  # sitemap.xml, robots.txt
+    # Wagtail page serving (must be last)
+    path("", include(wagtail_urls)),
+]
+
+if settings.DEBUG:
+    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

sum/boilerplate/project_name/wsgi.py

@@ -0,0 +1,16 @@
+"""
+WSGI application entry point.
+
+Replace 'project_name' with your actual project name after copying.
+For production, ensure DJANGO_SETTINGS_MODULE points to production settings.
+"""
+
+from __future__ import annotations
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project_name.settings.local")
+
+application = get_wsgi_application()

sum/boilerplate/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+DJANGO_SETTINGS_MODULE = project_name.settings.local
+python_files = test_*.py
+python_functions = test_*
+addopts = -v --tb=short

sum/boilerplate/requirements.txt

@@ -0,0 +1,25 @@
+# Client Project Requirements
+#
+# Default: Git tag pinning (recommended for client projects)
+# Replace SUM_CORE_GIT_REF with the actual tag/version, e.g., v0.1.0
+#
+# NOTE: For monorepo development mode, comment out the git install below
+# and uncomment the editable install:
+#   -e ../../core
+
+sum-core @ git+https://github.com/markashton480/sum-core.git@v0.7.2#subdirectory=core
+
+# PostgreSQL driver for production deployments
+psycopg[binary]>=3.2,<4
+
+# Required by Django's Redis cache backend
+redis>=5,<6
+
+# WSGI server (used by typical systemd + Caddy deploy)
+gunicorn>=22,<24
+
+# Required by seeders for YAML content profiles
+pyyaml>=6,<7
+
+# Load environment variables from .env file
+python-dotenv>=1.0,<2

sum/boilerplate/static/client/.gitkeep

@@ -0,0 +1,3 @@
+# Placeholder to preserve client static files directory in Git
+# Place client-specific CSS, JS, and images here.
+# Example: client/css/custom.css, client/images/logo.png

sum/boilerplate/templates/overrides/.gitkeep

@@ -0,0 +1,3 @@
+# Placeholder to preserve template overrides directory in Git
+# Place template overrides here mirroring sum_core template paths.
+# Example: overrides/sum_core/home_page.html

sum/boilerplate/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Test package for this client project.
+"""