sum-cli 3.0.0__tar.gz

sum_cli-3.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Mark Ashton
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sum_cli-3.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include sum/boilerplate *
+recursive-exclude sum/boilerplate __pycache__ *.pyc

sum_cli-3.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: sum-cli
+Version: 3.0.0
+Summary: SUM Platform CLI: single control plane for site lifecycle management
+Author: Mark Ashton
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/markashton480/sum-platform
+Project-URL: Repository, https://github.com/markashton480/sum-platform
+Project-URL: Issues, https://github.com/markashton480/sum-platform/issues
+Project-URL: Documentation, https://github.com/markashton480/sum-platform/tree/main/docs/dev/cli.md
+Keywords: sum,cli,django,wagtail
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.7
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: gitea
+Requires-Dist: httpx>=0.27.0; extra == "gitea"
+Dynamic: license-file
+
+# SUM CLI (v3)
+
+[![PyPI](https://img.shields.io/pypi/v/sum-cli.svg)](https://pypi.org/project/sum-cli/)
+
+The SUM CLI is the single control plane for deploying and managing SUM Platform client sites.
+
+## Install
+
+```bash
+pip install sum-cli
+sum-platform --version
+```
+
+### With Gitea Support
+
+If using Gitea instead of GitHub for repository hosting:
+
+```bash
+pip install sum-cli[gitea]
+```
+
+## Quick Usage
+
+```bash
+# Create a new production site (requires sudo)
+sudo sum-platform init acme --theme theme_a
+
+# Create site with custom content profile
+sudo sum-platform init acme --content-path /path/to/profiles/acme
+
+# Update a deployed site
+sum-platform update acme
+
+# Backup a site
+sum-platform backup acme --include-media
+
+# Promote staging to production
+sum-platform promote acme --domain acme.example.com
+
+# List available themes
+sum-platform themes
+
+# Validate a project setup
+sum-platform check acme
+```
+
+## Commands
+
+| Command | Description | Requires Sudo |
+|---------|-------------|---------------|
+| `init` | Create new site at `/srv/sum/<name>/` | Yes |
+| `update` | Pull updates, migrate, restart | No (staging) |
+| `backup` | Database and media backup | No |
+| `promote` | Deploy staging site to production | No |
+| `check` | Validate project setup | No |
+| `themes` | List available themes | No |
+| `run` | Start development server | No |
+
+## Git Provider Support
+
+The CLI supports both GitHub and Gitea for repository hosting. Configure your provider in `/etc/sum/config.yml`:
+
+**GitHub (default):**
+```yaml
+agency:
+  name: "Your Agency"
+  git_provider: "github"
+  github_org: "your-org"
+```
+
+**Gitea:**
+```yaml
+agency:
+  name: "Your Agency"
+  git_provider: "gitea"
+  gitea_url: "https://gitea.example.com"
+  gitea_org: "your-org"
+  gitea_token_env: "GITEA_TOKEN"
+```
+
+For Gitea, set the `GITEA_TOKEN` environment variable with your API token.
+
+## Development Install (monorepo)
+
+```bash
+pip install -e ./cli
+```
+
+## Configuration
+
+System-wide configuration is read from `/etc/sum/config.yml`. See `config.yml.example` for the full schema.
+
+## Documentation
+
+The full User Guide is bundled with the package at `sum/docs/USER_GUIDE.md`.
+
+For monorepo development:
+- [User Guide](../docs/dev/cli/USER_GUIDE.md) - Full command reference
+- [Developer Guide](../docs/dev/cli/DEVELOPER_GUIDE.md) - CLI architecture and contribution guide

sum_cli-3.0.0/README.md

@@ -0,0 +1,99 @@
+# SUM CLI (v3)
+
+[![PyPI](https://img.shields.io/pypi/v/sum-cli.svg)](https://pypi.org/project/sum-cli/)
+
+The SUM CLI is the single control plane for deploying and managing SUM Platform client sites.
+
+## Install
+
+```bash
+pip install sum-cli
+sum-platform --version
+```
+
+### With Gitea Support
+
+If using Gitea instead of GitHub for repository hosting:
+
+```bash
+pip install sum-cli[gitea]
+```
+
+## Quick Usage
+
+```bash
+# Create a new production site (requires sudo)
+sudo sum-platform init acme --theme theme_a
+
+# Create site with custom content profile
+sudo sum-platform init acme --content-path /path/to/profiles/acme
+
+# Update a deployed site
+sum-platform update acme
+
+# Backup a site
+sum-platform backup acme --include-media
+
+# Promote staging to production
+sum-platform promote acme --domain acme.example.com
+
+# List available themes
+sum-platform themes
+
+# Validate a project setup
+sum-platform check acme
+```
+
+## Commands
+
+| Command | Description | Requires Sudo |
+|---------|-------------|---------------|
+| `init` | Create new site at `/srv/sum/<name>/` | Yes |
+| `update` | Pull updates, migrate, restart | No (staging) |
+| `backup` | Database and media backup | No |
+| `promote` | Deploy staging site to production | No |
+| `check` | Validate project setup | No |
+| `themes` | List available themes | No |
+| `run` | Start development server | No |
+
+## Git Provider Support
+
+The CLI supports both GitHub and Gitea for repository hosting. Configure your provider in `/etc/sum/config.yml`:
+
+**GitHub (default):**
+```yaml
+agency:
+  name: "Your Agency"
+  git_provider: "github"
+  github_org: "your-org"
+```
+
+**Gitea:**
+```yaml
+agency:
+  name: "Your Agency"
+  git_provider: "gitea"
+  gitea_url: "https://gitea.example.com"
+  gitea_org: "your-org"
+  gitea_token_env: "GITEA_TOKEN"
+```
+
+For Gitea, set the `GITEA_TOKEN` environment variable with your API token.
+
+## Development Install (monorepo)
+
+```bash
+pip install -e ./cli
+```
+
+## Configuration
+
+System-wide configuration is read from `/etc/sum/config.yml`. See `config.yml.example` for the full schema.
+
+## Documentation
+
+The full User Guide is bundled with the package at `sum/docs/USER_GUIDE.md`.
+
+For monorepo development:
+- [User Guide](../docs/dev/cli/USER_GUIDE.md) - Full command reference
+- [Developer Guide](../docs/dev/cli/DEVELOPER_GUIDE.md) - CLI architecture and contribution guide

sum_cli-3.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sum-cli"
+version = "3.0.0"
+description = "SUM Platform CLI: single control plane for site lifecycle management"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Mark Ashton" }]
+keywords = ["sum", "cli", "django", "wagtail"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Code Generators",
+]
+dependencies = ["click>=8.1.7", "pyyaml>=6.0"]
+
+[project.optional-dependencies]
+gitea = ["httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://github.com/markashton480/sum-platform"
+Repository = "https://github.com/markashton480/sum-platform"
+Issues = "https://github.com/markashton480/sum-platform/issues"
+Documentation = "https://github.com/markashton480/sum-platform/tree/main/docs/dev/cli.md"
+
+[project.scripts]
+sum-platform = "sum.cli:cli"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sum*"]
+
+[tool.setuptools.package-data]
+sum = [
+  "boilerplate/**/*",
+  "boilerplate/.env.example",
+  "boilerplate/.gitignore",
+  "boilerplate/.github/**/*",
+  "boilerplate/.gitea/**/*",
+  "docs/**/*",
+]
+
+[tool.setuptools.exclude-package-data]
+sum = [
+  "boilerplate/**/__pycache__/*",
+  "boilerplate/**/*.pyc",
+]

sum_cli-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sum_cli-3.0.0/sum/__init__.py

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

sum_cli-3.0.0/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_cli-3.0.0/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_cli-3.0.0/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