sum-cli 3.0.0__py3-none-any.whl

sum/__init__.py

@@ -0,0 +1 @@
+"""CLI v2 core package."""

sum/boilerplate/.env.example

@@ -0,0 +1,124 @@
+# =============================================================================
+# SUM Client Environment Configuration
+# =============================================================================
+# Copy this file to .env and set values appropriate for your environment.
+# All variables with defaults shown are optional unless noted otherwise.
+
+# =============================================================================
+# Django Core
+# =============================================================================
+
+# REQUIRED in production: Generate with `python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"`
+DJANGO_SECRET_KEY=change-me-in-production
+
+# REQUIRED in production: Comma-separated list of allowed hostnames
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+# Settings module (default: project_name.settings.local)
+# For production, set to: project_name.settings.production
+# DJANGO_SETTINGS_MODULE=project_name.settings.local
+
+# Wagtail admin base URL (for email links, etc.)
+WAGTAILADMIN_BASE_URL=http://localhost:8001
+
+# =============================================================================
+# Database (PostgreSQL)
+# =============================================================================
+# REQUIRED: PostgreSQL is used for both local development and production.
+# These must be configured before running migrations.
+
+DJANGO_DB_NAME=sum_db
+DJANGO_DB_USER=sum_user
+DJANGO_DB_PASSWORD=sum_password
+DJANGO_DB_HOST=localhost
+DJANGO_DB_PORT=5432
+
+
+# =============================================================================
+# Static/Media Roots (Golden Path VPS)
+# =============================================================================
+# For the VPS golden path, set these to point outside the app checkout so Caddy can serve
+# static/media directly. Example:
+#   DJANGO_STATIC_ROOT=/srv/sum/<site_slug>/static
+#   DJANGO_MEDIA_ROOT=/srv/sum/<site_slug>/media
+#
+# DJANGO_STATIC_ROOT=
+# DJANGO_MEDIA_ROOT=
+
+# Optional: used by infrastructure/scripts/deploy.sh smoke checks
+# SITE_DOMAIN=example.com
+
+# =============================================================================
+# Redis / Cache
+# =============================================================================
+# Used for caching and Celery broker in production.
+# Local development uses in-memory cache by default.
+
+REDIS_URL=redis://localhost:6379/0
+
+# =============================================================================
+# Celery (Async Tasks)
+# =============================================================================
+# Falls back to synchronous execution if not configured.
+
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/0
+
+# =============================================================================
+# Email Configuration (SMTP)
+# =============================================================================
+# Defaults to console backend for development (emails printed to stdout).
+# Configure SMTP for production email delivery.
+#
+# We recommend Resend (https://resend.com) for transactional email.
+# Sign up, verify your domain, and get an API key from the dashboard.
+#
+# Resend SMTP settings:
+EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
+EMAIL_HOST=smtp.resend.com
+EMAIL_PORT=587
+EMAIL_HOST_USER=resend
+EMAIL_HOST_PASSWORD=re_YOUR_API_KEY_HERE
+EMAIL_USE_TLS=True
+EMAIL_USE_SSL=False
+DEFAULT_FROM_EMAIL=noreply@yourdomain.com
+
+# Lead notification recipient - where new lead alerts are sent.
+# This MUST be set for lead notification emails to be delivered.
+LEAD_NOTIFICATION_EMAIL=leads@yourdomain.com
+
+# =============================================================================
+# Zapier Integration (Optional)
+# =============================================================================
+# Configure per-site in Wagtail SiteSettings, or set globally here.
+
+# ZAPIER_WEBHOOK_URL=https://hooks.zapier.com/hooks/catch/...
+
+# =============================================================================
+# Observability
+# =============================================================================
+
+# Sentry error tracking (optional, disabled if not set)
+# SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
+# SENTRY_ENVIRONMENT=development
+# SENTRY_TRACES_SAMPLE_RATE=0.0
+
+# Logging configuration (optional)
+# LOG_LEVEL=INFO
+# LOG_FORMAT=auto  # "auto", "json", or blank for console-friendly
+
+# =============================================================================
+# Build / Version Info (typically set by CI)
+# =============================================================================
+# These are included in /health/ endpoint and Sentry releases.
+
+# GIT_SHA=abc123
+# BUILD_ID=build-123
+# RELEASE=v0.1.0
+
+# =============================================================================
+# Security (Production Only)
+# =============================================================================
+# Set to True to enforce HTTPS redirects (default: True in production.py)
+
+# SECURE_SSL_REDIRECT=True

sum/boilerplate/.gitea/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Install test dependencies
+        run: pip install pytest pytest-django
+
+      - name: Run tests
+        run: pytest

sum/boilerplate/.gitea/workflows/deploy-production.yml

@@ -0,0 +1,98 @@
+name: Deploy Production
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      PRODUCTION_HOST: ${{ secrets.PRODUCTION_HOST }}
+      PRODUCTION_USER: ${{ secrets.PRODUCTION_USER }}
+      PRODUCTION_PATH: ${{ secrets.PRODUCTION_PATH }}
+      PRODUCTION_URL: ${{ secrets.PRODUCTION_URL }}
+
+    steps:
+      - name: Verify required secrets are present
+        run: |
+          set -euo pipefail
+          for var in PRODUCTION_HOST PRODUCTION_USER PRODUCTION_PATH PRODUCTION_URL; do
+            if [ -z "${!var}" ]; then
+              echo "Missing $var" >&2
+              exit 1
+            fi
+          done
+
+      - name: Validate SSH key secret
+        if: ${{ secrets.PRODUCTION_SSH_KEY == '' }}
+        run: |
+          echo "::error::PRODUCTION_SSH_KEY is not set"
+          exit 1
+
+      - name: Set up SSH
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          echo "${{ secrets.PRODUCTION_SSH_KEY }}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -H "$PRODUCTION_HOST" > ~/.ssh/known_hosts
+          if [ ! -s ~/.ssh/known_hosts ]; then
+            echo "ssh-keyscan returned no host keys for $PRODUCTION_HOST" >&2
+            exit 1
+          fi
+          chmod 600 ~/.ssh/known_hosts
+
+      # Rollback: ssh $PRODUCTION_USER@$PRODUCTION_HOST "/srv/sum/bin/deploy.sh --site-slug <site-slug> --ref <previous-tag>"
+      - name: Deploy release tag
+        run: |
+          set -euo pipefail
+          SITE_SLUG=$(basename "$PRODUCTION_PATH")
+          RELEASE_TAG="${{ gitea.event.release.tag_name }}"
+          if [ -z "$RELEASE_TAG" ]; then
+            echo "Release tag not found in event payload" >&2
+            exit 1
+          fi
+          ssh -o BatchMode=yes -o StrictHostKeyChecking=yes \
+            "${PRODUCTION_USER}@${PRODUCTION_HOST}" \
+            "/srv/sum/bin/deploy.sh --site-slug \"$SITE_SLUG\" --ref \"$RELEASE_TAG\""
+
+      - name: Health check (blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${PRODUCTION_URL%/}"
+          for attempt in 1 2 3; do
+            echo "Health check attempt $attempt..."
+            if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+              "$BASE_URL/health/" >/dev/null; then
+              echo "Health check OK"
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "Health check failed, retrying in 10s..."
+              sleep 10
+            fi
+          done
+          echo "::error::Health check failed after 3 attempts"
+          exit 1
+
+      - name: Sitemap check (non-blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${PRODUCTION_URL%/}"
+          if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+            "$BASE_URL/sitemap.xml" >/dev/null; then
+            echo "Sitemap check OK"
+          else
+            echo "::warning::Sitemap check failed (non-blocking)"
+          fi
+
+      - name: Clean up SSH key
+        if: always()
+        run: rm -f ~/.ssh/id_rsa

sum/boilerplate/.gitea/workflows/deploy-staging.yml

@@ -0,0 +1,113 @@
+# Name: deploy-staging.yml
+# Path: boilerplate/.gitea/workflows/deploy-staging.yml
+# Purpose: Deploy to staging on push to main.
+#
+# Required secrets:
+# - STAGING_SSH_KEY: SSH private key for deploy user
+# - STAGING_HOST: staging host/IP
+# - STAGING_USER: SSH username
+# - STAGING_PATH: site root (/srv/sum/<site-slug>)
+# - STAGING_URL: staging URL (reserved for health checks)
+
+name: Deploy Staging
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: deploy-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      STAGING_HOST: ${{ secrets.STAGING_HOST }}
+      STAGING_USER: ${{ secrets.STAGING_USER }}
+      STAGING_PATH: ${{ secrets.STAGING_PATH }}
+      STAGING_URL: ${{ secrets.STAGING_URL }}
+    steps:
+      - name: Validate required secrets
+        run: |
+          set -euo pipefail
+          for name in STAGING_HOST STAGING_USER STAGING_PATH STAGING_URL; do
+            if [ -z "${!name}" ]; then
+              echo "::error::$name is not set"
+              exit 1
+            fi
+          done
+
+      - name: Validate SSH key secret
+        if: ${{ secrets.STAGING_SSH_KEY == '' }}
+        run: |
+          echo "::error::STAGING_SSH_KEY is not set"
+          exit 1
+
+      - name: Set up SSH
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          echo "${{ secrets.STAGING_SSH_KEY }}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -H "$STAGING_HOST" > ~/.ssh/known_hosts
+          if [ ! -s ~/.ssh/known_hosts ]; then
+            echo "::error::ssh-keyscan produced no host keys for $STAGING_HOST"
+            exit 1
+          fi
+          chmod 600 ~/.ssh/known_hosts
+
+      - name: Derive site slug
+        id: slug
+        run: |
+          set -euo pipefail
+          SITE_SLUG=$(basename "$STAGING_PATH")
+          echo "site_slug=$SITE_SLUG" >> "$GITEA_OUTPUT"
+          echo "Derived site slug: $SITE_SLUG"
+
+      # Rollback:
+      # 1) SSH to the server.
+      # 2) /srv/sum/bin/deploy.sh --site-slug <slug> --ref <previous-tag>
+      - name: Deploy to staging
+        env:
+          SITE_SLUG: ${{ steps.slug.outputs.site_slug }}
+        run: |
+          set -euo pipefail
+          ssh -o BatchMode=yes -o StrictHostKeyChecking=yes "${STAGING_USER}@${STAGING_HOST}" \
+            "/srv/sum/bin/deploy.sh --site-slug \"$SITE_SLUG\" --ref \"${{ gitea.sha }}\""
+
+      - name: Health check (blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${STAGING_URL%/}"
+          for attempt in 1 2 3; do
+            echo "Health check attempt $attempt..."
+            if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+              "$BASE_URL/health/" >/dev/null; then
+              echo "Health check OK"
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "Health check failed, retrying in 10s..."
+              sleep 10
+            fi
+          done
+          echo "::error::Health check failed after 3 attempts"
+          exit 1
+
+      - name: Sitemap check (non-blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${STAGING_URL%/}"
+          if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+            "$BASE_URL/sitemap.xml" >/dev/null; then
+            echo "Sitemap check OK"
+          else
+            echo "::warning::Sitemap check failed (non-blocking)"
+          fi
+
+      - name: Clean up SSH key
+        if: always()
+        run: rm -f ~/.ssh/id_rsa

sum/boilerplate/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Install test dependencies
+        run: pip install pytest pytest-django
+
+      - name: Run tests
+        run: pytest

sum/boilerplate/.github/workflows/deploy-production.yml

@@ -0,0 +1,102 @@
+name: Deploy Production
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: production
+    # Requires GitHub environment "production" with Required reviewers enabled.
+    env:
+      PRODUCTION_HOST: ${{ secrets.PRODUCTION_HOST }}
+      PRODUCTION_USER: ${{ secrets.PRODUCTION_USER }}
+      PRODUCTION_PATH: ${{ secrets.PRODUCTION_PATH }}
+      PRODUCTION_URL: ${{ secrets.PRODUCTION_URL }}
+
+    steps:
+      - name: Verify required secrets are present
+        run: |
+          set -euo pipefail
+          for var in PRODUCTION_HOST PRODUCTION_USER PRODUCTION_PATH PRODUCTION_URL; do
+            if [ -z "${!var}" ]; then
+              echo "Missing $var" >&2
+              exit 1
+            fi
+          done
+
+      - name: Validate SSH key secret
+        if: ${{ secrets.PRODUCTION_SSH_KEY == '' }}
+        run: |
+          echo "::error::PRODUCTION_SSH_KEY is not set"
+          exit 1
+
+      - name: Start SSH agent
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.PRODUCTION_SSH_KEY }}
+
+      - name: Add host to known_hosts
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          ssh-keyscan -H "$PRODUCTION_HOST" > ~/.ssh/known_hosts
+          if [ ! -s ~/.ssh/known_hosts ]; then
+            echo "ssh-keyscan returned no host keys for $PRODUCTION_HOST" >&2
+            exit 1
+          fi
+          chmod 600 ~/.ssh/known_hosts
+
+      # Rollback: ssh $PRODUCTION_USER@$PRODUCTION_HOST "/srv/sum/bin/deploy.sh --site-slug <site-slug> --ref <previous-tag>"
+      - name: Deploy release tag
+        run: |
+          set -euo pipefail
+          SITE_SLUG=$(basename "$PRODUCTION_PATH")
+          RELEASE_TAG="${{ github.event.release.tag_name }}"
+          if [ -z "$RELEASE_TAG" ]; then
+            echo "Release tag not found in event payload" >&2
+            exit 1
+          fi
+          ssh -o BatchMode=yes -o StrictHostKeyChecking=yes \
+            "${PRODUCTION_USER}@${PRODUCTION_HOST}" \
+            "/srv/sum/bin/deploy.sh --site-slug \"$SITE_SLUG\" --ref \"$RELEASE_TAG\""
+
+      - name: Health check (blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${PRODUCTION_URL%/}"
+          for attempt in 1 2 3; do
+            echo "Health check attempt $attempt..."
+            if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+              "$BASE_URL/health/" >/dev/null; then
+              echo "Health check OK"
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "Health check failed, retrying in 10s..."
+              sleep 10
+            fi
+          done
+          echo "::error::Health check failed after 3 attempts"
+          exit 1
+
+      - name: Sitemap check (non-blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${PRODUCTION_URL%/}"
+          if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+            "$BASE_URL/sitemap.xml" >/dev/null; then
+            echo "Sitemap check OK"
+          else
+            echo "::warning::Sitemap check failed (non-blocking)"
+          fi

sum/boilerplate/.github/workflows/deploy-staging.yml

@@ -0,0 +1,115 @@
+# Name: deploy-staging.yml
+# Path: boilerplate/.github/workflows/deploy-staging.yml
+# Purpose: Deploy to staging on push to main.
+#
+# Required secrets:
+# - STAGING_SSH_KEY: SSH private key for deploy user
+# - STAGING_HOST: staging host/IP
+# - STAGING_USER: SSH username
+# - STAGING_PATH: site root (/srv/sum/<site-slug>)
+# - STAGING_URL: staging URL (reserved for health checks in BPCI-04)
+
+name: Deploy Staging
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      STAGING_HOST: ${{ secrets.STAGING_HOST }}
+      STAGING_USER: ${{ secrets.STAGING_USER }}
+      STAGING_PATH: ${{ secrets.STAGING_PATH }}
+      STAGING_URL: ${{ secrets.STAGING_URL }}
+    steps:
+      - name: Validate required secrets
+        run: |
+          set -euo pipefail
+          for name in STAGING_HOST STAGING_USER STAGING_PATH STAGING_URL; do
+            if [ -z "${!name}" ]; then
+              echo "::error::$name is not set"
+              exit 1
+            fi
+          done
+
+      - name: Validate SSH key secret
+        if: ${{ secrets.STAGING_SSH_KEY == '' }}
+        run: |
+          echo "::error::STAGING_SSH_KEY is not set"
+          exit 1
+
+      - name: Set up SSH agent
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.STAGING_SSH_KEY }}
+
+      - name: Add staging host to known_hosts
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          ssh-keyscan -H "$STAGING_HOST" > ~/.ssh/known_hosts
+          if [ ! -s ~/.ssh/known_hosts ]; then
+            echo "::error::ssh-keyscan produced no host keys for $STAGING_HOST"
+            exit 1
+          fi
+          chmod 600 ~/.ssh/known_hosts
+
+      - name: Derive site slug
+        id: slug
+        run: |
+          set -euo pipefail
+          SITE_SLUG=$(basename "$STAGING_PATH")
+          echo "site_slug=$SITE_SLUG" >> "$GITHUB_OUTPUT"
+          echo "Derived site slug: $SITE_SLUG"
+
+      # Rollback:
+      # 1) SSH to the server.
+      # 2) /srv/sum/bin/deploy.sh --site-slug <slug> --ref <previous-tag>
+      - name: Deploy to staging
+        env:
+          SITE_SLUG: ${{ steps.slug.outputs.site_slug }}
+        run: |
+          set -euo pipefail
+          ssh -o BatchMode=yes -o StrictHostKeyChecking=yes "${STAGING_USER}@${STAGING_HOST}" \
+            "/srv/sum/bin/deploy.sh --site-slug \"$SITE_SLUG\" --ref \"$GITHUB_SHA\""
+
+      - name: Health check (blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${STAGING_URL%/}"
+          for attempt in 1 2 3; do
+            echo "Health check attempt $attempt..."
+            if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+              "$BASE_URL/health/" >/dev/null; then
+              echo "Health check OK"
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "Health check failed, retrying in 10s..."
+              sleep 10
+            fi
+          done
+          echo "::error::Health check failed after 3 attempts"
+          exit 1
+
+      - name: Sitemap check (non-blocking)
+        run: |
+          set -euo pipefail
+          BASE_URL="${STAGING_URL%/}"
+          if curl --fail --show-error --silent --location --max-redirs 0 --max-time 60 \
+            "$BASE_URL/sitemap.xml" >/dev/null; then
+            echo "Sitemap check OK"
+          else
+            echo "::warning::Sitemap check failed (non-blocking)"
+          fi

sum/boilerplate/.gitignore

@@ -0,0 +1,45 @@
+# Environment files - NEVER commit secrets
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+
+# Static files (collected)
+staticfiles/
+
+# Media uploads
+media/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Build
+dist/
+build/
+*.egg-info/