core-framework 3.0.0__tar.gz → 3.2.0__tar.gz

core_framework-3.2.0/.cursor/rules/constitution.mdc

@@ -0,0 +1,47 @@
+---
+description: Core non-negotiables — behavior, tech stack, layer direction, host scope
+alwaysApply: true
+---
+
+# Constitution
+
+## Behavior
+
+- State assumptions; ask when unclear. Prefer the simplest correct solution.
+- Touch only what the task requires. Match existing style. Remove orphans your edits create.
+- Define verifiable success criteria for non-trivial work.
+- **Inline small single-use helpers** — do not extract a private function used once and only a few lines (identifier quoting, a short SQL fragment, pass-through wrappers). Extract when the logic is **reused**, **~15+ lines / non-obvious branching**, or a scoped rule requires sharing (e.g. normal + `*_strong` repository reads in **`strong-reads.mdc`**). Do not repo-wide refactor unrelated existing helpers.
+
+## Tech stack
+
+- Python 3.14, Pydantic v2, PostgreSQL 18, orjson (not stdlib json).
+- Absolute imports only (`from core_framework....`). Comma-style `except A, B:` is intentional.
+- Prefer newer APIs and **current Python syntax** over older equivalents still legal on 3.14, for example:
+  - `asyncio.TaskGroup` over `asyncio.gather`
+  - PEP 695 type parameters (`def f[T](...)`, `def f[**P, R](...)`) over module-level `TypeVar` / `ParamSpec`
+  - Built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` / `typing.Dict`
+  - `X | Y` over `Optional[X]` / `Union[X, Y]` unless a library API requires the old form
+  - Do **not** add `from __future__ import annotations` — 3.14 deferred annotations are the default (PEP 649)
+
+## Layers
+
+Dependencies point inward: API/worker → application → domain. Never reverse.
+
+- **API/worker** — transport adapters; call application services.
+- **Application** — orchestration shared by API + worker; no FastAPI types.
+- **Domain** — models, repositories (Postgres only), services. No API/worker/application imports except wiring in `dependencies.py`.
+
+Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.agents/skills/fastapi/`).
+
+## Agent skills
+
+- Package skills (for example **fastapi**) are Library Skills-managed symlinks under **`.agents/skills/<name>/`**. Rules and hand-authored skills reference that path, not a copied tree under **`.cursor/skills/`**.
+- **`.cursor/skills/<name>`** may symlink to **`.agents/skills/<name>`** for Cursor; Library Skills repairs **`.agents/skills`** links when packages move. After **`uv sync`** or a dependency upgrade, run **`uvx library-skills --yes`** if symlinks are stale.
+
+## Host applications
+
+Do not edit consuming host repos in the same task as core-framework work unless the user scopes work to a host or asks to sync/upgrade. See the **sync-host-rules** skill.
+
+## Feature implementation
+
+Greenfield features (DB → API → repository → service → **documentation** → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise. A feature is **not done** until documentation is updated.

core_framework-3.2.0/.cursor/rules/error-boundary.mdc

@@ -0,0 +1,56 @@
+---
+description: HTTP error boundaries — application vs domain exceptions, handlers, anti-enumeration
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+  - core_framework/application/**/*.py
+  - core_framework/api/**/router.py
+  - core_framework/api/**/schemas.py
+  - core_framework/domains/**/exceptions.py
+---
+
+# Error boundary
+
+Platform contract: **`docs/platform/client-error-visibility.md`**. Domain imports: **`domain-imports.mdc`**.
+
+## Layers
+
+| Layer | Outward errors | HTTP |
+|-------|----------------|------|
+| **Application** | **`application.shared.exceptions`**, **`InvalidPageTokenError`** | Handlers map type → status + catalog **`detail`** |
+| **API** | Pydantic; **`HTTPException`** for transport-local guards | **422** field errors; router-chosen status + **`detail`** |
+| **Domain typed** | Internal — not imported by API/application | No typed handlers |
+| **Domain `BaseXxxException`** | Handler catch-all only | **500** if leaked |
+
+## Application and domain
+
+- Application **must not** import or raise typed domain exceptions. Signal via **`None`**, empty collections, or **`application.shared.exceptions`**.
+- Typed domain exceptions inherit domain **`BaseXxxException`** → **`BaseDomainException`**. Export **only** **`BaseXxxException`** from domain **`__init__.py`**, not typed subclasses.
+- **`DomainValidationError`** → dedicated **400** handler + **`GENERIC_BAD_REQUEST_DETAIL`**; do not put internal reason in HTTP **`detail`**.
+- Leaked typed domain exception → **`BaseDomainException`** handler → **500** + **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`**.
+
+## Handler registration
+
+- Use **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`** — not raw **`app.add_exception_handler`** elsewhere.
+- Register handlers in **`core_framework/core/exception_handlers/setup.py`** and **`application.py`**: application types (specific before any base), **`InvalidPageTokenError`**, **`DomainValidationError`**, one **`BaseDomainException`** leak handler, then **`Exception`** unmapped.
+- No per-domain handler modules for typed exceptions. Handlers translate only — no business logic or repository calls.
+- Do not log **error** for expected application 4xx; **`DomainValidationError`** at **warning**/**info**.
+
+## Catalog constants
+
+**`GENERIC_BAD_REQUEST_DETAIL`** (400), **`GENERIC_NOT_FOUND_DETAIL`** (404), **`GENERIC_FORBIDDEN_DETAIL`** (403), **`GENERIC_CONFLICT_DETAIL`** (409), ingest 413/415, **`GENERIC_SERVICE_UNAVAILABLE_DETAIL`** (503), **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
+
+## Anti-enumeration (public routes)
+
+- Read-by-id: missing / hidden / withheld → same status + **`GENERIC_NOT_FOUND_DETAIL`** where flow docs align.
+- Idempotent writes on unknown ids → **204** without leaking existence. Empty list pages are OK.
+- Admin/internal routes may differ when documented. Intentional existence-check endpoints are separate product surface.
+
+## Validation order
+
+User-fixable input shape → API schemas (**422**) or router **`HTTPException`**. Use-case outcomes → application exceptions + handlers. Domain backstops → **`DomainValidationError`** → generic **400** (never domain text in **`detail`**).
+
+## Logging
+
+Do not **`logger.error`** at every domain **`raise`**.
+
+Apply to new handlers and touched raise sites unless the task scopes repo-wide migration.

core_framework-3.2.0/.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-review
+description: Review code for quality, architecture compliance, and best practices. Use when the user asks for a code review, audit, or review.
+---
+
+# Code Review
+
+## Output format (required)
+
+**Actionable findings only:**
+
+- Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason).
+- Prioritize by severity with file context and fix direction.
+- **Do not** praise, summarize strengths, or pad with checklist pass narratives.
+- One-line scope is fine. If nothing is wrong, say so in one sentence.
+
+Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-decisions.md`** unless the implementation violates them.
+
+## Workflow
+
+1. Read **`docs/platform/layers-and-boundaries.md`**, **`conventions.md`**, and **`architecture-decisions.md`** for the reviewed scope.
+1. Apply **scoped rules** (`.cursor/rules/*.mdc`) matching files under review — especially **`error-boundary`**, **`domain-imports`**, **`api-layer`**, **`application-layer`**, **`strong-reads`**.
+1. Report findings only — no filler.
+
+## Quick checks
+
+- Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill (`.agents/skills/fastapi/`) + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
+- Read-after-write refetches use **`*_strong`** where applicable.
+- **Python modernity (constitution):** prefer current 3.14 syntax in reviewed code — PEP 695 type params over module-level `TypeVar`/`ParamSpec`; no unnecessary `from __future__ import annotations`; builtins / `X | Y` over legacy `typing` aliases; `asyncio.TaskGroup` over `gather`.
+
+## Parallel drift
+
+Flag sibling modules with the same job but different structure (async layout, cleanup order, error/idempotency contracts) when docs do not explain the difference.

core_framework-3.2.0/.cursor/skills/sync-host-rules/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: sync-host-rules
+description: Sync core-framework rules, skills, and platform docs to consuming host applications. Use when the user asks to sync rules to a host, bump core-framework in a host, upgrade a host dependency, or port shared cursor/docs content.
+---
+
+# Sync Host Rules and Docs
+
+Consuming applications embed **core-framework** as a dependency.
+
+## Default (core-framework work)
+
+When changing **core-framework** code, migrations, tests, or **`docs/`**:
+
+- **Do not** edit host repos in the same task.
+- **Do not** port **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`**, **`.cursor/rules/`**, or **`.cursor/skills/`** to hosts proactively.
+- Mention that host sync is **deferred until the host bumps its core-framework version** (unless the user asked otherwise).
+
+## When host changes are allowed
+
+1. User explicitly scopes work to a host repo.
+1. User explicitly asks to sync or upgrade the core dependency in a host.
+1. You are editing a host repo directly — follow that repo's rules.
+
+## Sync procedure
+
+Diff by **basename** against the host's **`.cursor/`** and applicable **`docs/`** paths. Port shared content and **adapt**:
+
+- globs: **`core_framework/**`** → host source tree where applicable
+- imports: **`core_framework....`** → host package prefix
+- strong reads: **`strong-reads`** → host equivalent rule if present
+
+**Do not overwrite** host-only rules, skills, or product docs.
+
+### Transactional email (when the bumped core ships it)
+
+Remind the host (via upgrade notes / playbook, not code changes here):
+
+1. Put **`register_email_content`** in the **same** shared host bootstrap helper API and worker already call — worker is load-bearing.
+1. Register branded renderers **before** **`EMAIL_ENABLED=true`** (core default deletion copy is generic English).
+1. Do **not** **`enqueue_transactional_email`** for **`account_deletion_scheduled`** unless the host re-implements gated checks — use the core gated task.
+
+### `docs/deployments/guides/` layout
+
+Core walkthroughs live under **`docs/deployments/guides/setup/`** (one-time install) and **`docs/deployments/guides/playbook/`** (ops / incident runbooks) — not a flat **`guides/`** directory.
+
+When syncing **`docs/deployments/`** to a host:
+
+1. **Match the directory layout** — create **`guides/setup/`** and **`guides/playbook/`** on the host; move or rewrite files into those paths. Do **not** leave stale flat **`guides/*.md`** copies beside the new tree.
+1. **Basename alone is not enough** — a host may still have **`guides/ubuntu-server-setup.md`** while core has **`guides/setup/ubuntu-server-setup.md`**. Diff by relative path under **`docs/deployments/`**, then port.
+1. **Renames** — e.g. **`postgres-backup-ops.md`** → **`guides/playbook/postgres-backup-playbook.md`**. Delete the old host path after porting.
+1. **Adapt host paths** in playbooks (Compose project dir, image names, **`app_configs/<host>/`**) — keep Henry-specific notes in host **`deploy-playbook.md`** / **`release-playbook.md`**.
+
+## Docs boundaries
+
+**Core `docs/` must stay host-agnostic** — no references to specific consuming applications.
+
+| Core path                                                         | Host behavior                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`** | Sync on dependency upgrade or explicit sync request           |
+| **`docs/domains/`**, **`docs/library/`**                          | Canonical in core only — do not mirror product trees to hosts |

core_framework-3.2.0/.github/workflows/_deploy.yml

@@ -0,0 +1,238 @@
+name: Reusable Deployment
+
+on:
+  workflow_call:
+    inputs:
+      env_name:
+        type: string
+        required: true
+      dockerhub_username:
+        type: string
+        required: true
+      worker_replicas:
+        type: number
+        required: false
+        default: 1
+    secrets:
+      SECRET_KEY:
+        required: true
+      WRITE_POSTGRES_PASSWORD:
+        required: true
+      READ_POSTGRES_PASSWORD:
+        required: true
+      FIREBASE_CONFIG:
+        required: true
+      IMAGE_SERVER_SSH_PRIVATE_KEY:
+        required: true
+      IMAGE_SERVER_KNOWN_HOSTS:
+        required: true
+      DEPLOY_SERVER_SSH_KEY:
+        required: true
+      DOCKERHUB_TOKEN:
+        required: true
+
+permissions: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.env_name }}
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Render config.toml from template
+        env:
+          ENVIRONMENT: ${{ inputs.env_name }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+          WRITE_POSTGRES_HOST: ${{ vars.WRITE_POSTGRES_HOST }}
+          WRITE_POSTGRES_PORT: ${{ vars.WRITE_POSTGRES_PORT }}
+          WRITE_POSTGRES_USER: ${{ vars.WRITE_POSTGRES_USER }}
+          WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
+          WRITE_POSTGRES_DB: ${{ vars.WRITE_POSTGRES_DB }}
+          READ_POSTGRES_HOST: ${{ vars.READ_POSTGRES_HOST }}
+          READ_POSTGRES_PORT: ${{ vars.READ_POSTGRES_PORT }}
+          READ_POSTGRES_USER: ${{ vars.READ_POSTGRES_USER }}
+          READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
+          READ_POSTGRES_DB: ${{ vars.READ_POSTGRES_DB }}
+          REDIS_HOST: ${{ vars.REDIS_HOST }}
+          REDIS_PORT: ${{ vars.REDIS_PORT }}
+          ALLOWED_HOSTS: ${{ vars.ALLOWED_HOSTS }}
+          APP_TITLE: ${{ vars.APP_TITLE }}
+          APP_DEBUG: ${{ vars.APP_DEBUG }}
+          OPENAPI_URL: ${{ vars.OPENAPI_URL }}
+          AVATAR_HOST_DOMAIN: ${{ vars.AVATAR_HOST_DOMAIN }}
+          AVATAR_DEFAULT_IMAGE: ${{ vars.AVATAR_DEFAULT_IMAGE }}
+          AVATAR_PUBLISH_ROOT: ${{ vars.AVATAR_PUBLISH_ROOT }}
+          BANNER_HOST_DOMAIN: ${{ vars.BANNER_HOST_DOMAIN }}
+          BANNER_DEFAULT_IMAGE: ${{ vars.BANNER_DEFAULT_IMAGE }}
+          BANNER_PUBLISH_ROOT: ${{ vars.BANNER_PUBLISH_ROOT }}
+          ATTACHMENT_HOST_DOMAIN: ${{ vars.ATTACHMENT_HOST_DOMAIN }}
+          ATTACHMENT_DEFAULT_IMAGE: ${{ vars.ATTACHMENT_DEFAULT_IMAGE }}
+          ATTACHMENT_PUBLISH_ROOT: ${{ vars.ATTACHMENT_PUBLISH_ROOT }}
+          IMAGE_SERVER_HOST: ${{ vars.IMAGE_SERVER_HOST }}
+          IMAGE_SERVER_PORT: ${{ vars.IMAGE_SERVER_PORT }}
+          IMAGE_SERVER_USER: ${{ vars.IMAGE_SERVER_USER }}
+          OBSERVABILITY_ENABLED: ${{ vars.OBSERVABILITY_ENABLED }}
+          OBSERVABILITY_OTLP_ENDPOINT: ${{ vars.OBSERVABILITY_OTLP_ENDPOINT }}
+          PROFILING_KEY: ${{ vars.PROFILING_KEY }}
+          PROFILING_ENABLED: ${{ vars.PROFILING_ENABLED }}
+          LOG_LEVEL: ${{ vars.LOG_LEVEL }}
+          CORS_ALLOWED_ORIGINS: ${{ vars.CORS_ALLOWED_ORIGINS }}
+          RETENTION_POST_VIEWS_DAYS: ${{ vars.RETENTION_POST_VIEWS_DAYS }}
+          RETENTION_READ_NOTIFICATIONS_DAYS: ${{ vars.RETENTION_READ_NOTIFICATIONS_DAYS }}
+          ANALYTICS_REFRESH_INTERVAL_SECONDS: ${{ vars.ANALYTICS_REFRESH_INTERVAL_SECONDS }}
+          EMAIL_ENABLED: ${{ vars.EMAIL_ENABLED }}
+          EMAIL_PROVIDER: ${{ vars.EMAIL_PROVIDER }}
+          EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
+          EMAIL_FROM_ADDRESS: ${{ vars.EMAIL_FROM_ADDRESS }}
+          EMAIL_FROM_NAME: ${{ vars.EMAIL_FROM_NAME }}
+        run: |
+          set -euo pipefail
+
+          echo "Rendering config..."
+          envsubst < config.toml.template > config.toml
+          test -s config.toml
+          python3 - <<'PY'
+          import sys
+          import tomllib
+
+          try:
+              with open("config.toml", "rb") as f:
+                  tomllib.load(f)
+          except Exception as e:
+              print("ERROR: config.toml is invalid TOML", file=sys.stderr)
+              print(e, file=sys.stderr)
+              sys.exit(1)
+          PY
+
+      - name: Generate firebase_config.json from secret
+        env:
+          FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating firebase_config.json..."
+          echo "$FIREBASE_CONFIG" > firebase_config.json
+          test -s firebase_config.json
+          python3 - <<'PY'
+          import sys
+          import json
+
+          try:
+              with open("firebase_config.json", "r") as f:
+                  json.load(f)
+          except Exception as e:
+              print("ERROR: firebase_config.json is invalid JSON", file=sys.stderr)
+              print(e, file=sys.stderr)
+              sys.exit(1)
+          PY
+
+      - name: Generate image_server_ssh_key from secret
+        env:
+          IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating image_server_ssh_key..."
+          printf '%s\n' "$IMAGE_SERVER_SSH_PRIVATE_KEY" > image_server_ssh_key
+          test -s image_server_ssh_key
+          chmod 600 image_server_ssh_key
+
+      - name: Generate image_server_known_hosts from secret
+        env:
+          IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}
+        run: |
+          set -euo pipefail
+
+          echo "Generating image_server_known_hosts..."
+          printf '%s\n' "$IMAGE_SERVER_KNOWN_HOSTS" > image_server_known_hosts
+          test -s image_server_known_hosts
+          chmod 644 image_server_known_hosts
+
+      - name: Stage docker-compose.yml for upload
+        run: cp deploy/app/docker-compose.yml ./docker-compose.yml
+
+      - name: Upload rendered config.toml, firebase_config.json and docker-compose.yml
+        uses: appleboy/scp-action@ff85246acaad7bdce478db94a363cd2bf7c90345 # v1.0.0
+        with:
+          host: ${{ vars.DEPLOY_SERVER_HOST }}
+          username: ${{ vars.DEPLOY_SERVER_USER }}
+          key: ${{ secrets.DEPLOY_SERVER_SSH_KEY }}
+          port: ${{ vars.DEPLOY_SERVER_PORT }}
+          source: "config.toml,firebase_config.json,docker-compose.yml,image_server_ssh_key,image_server_known_hosts"
+          target: "/home/${{ vars.DEPLOY_SERVER_USER }}/app_configs/core-framework"
+
+      - name: Deploy to Server via SSH
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+          DOCKERHUB_USERNAME: ${{ inputs.dockerhub_username }}
+          DEPLOY_SERVER_USER: ${{ vars.DEPLOY_SERVER_USER }}
+          WORKER_REPLICAS: ${{ inputs.worker_replicas }}
+        with:
+          host: ${{ vars.DEPLOY_SERVER_HOST }}
+          username: ${{ vars.DEPLOY_SERVER_USER }}
+          key: ${{ secrets.DEPLOY_SERVER_SSH_KEY }}
+          port: ${{ vars.DEPLOY_SERVER_PORT }}
+          envs: DOCKERHUB_TOKEN,DOCKERHUB_USERNAME,DEPLOY_SERVER_USER,WORKER_REPLICAS
+          script: |
+            set -euo pipefail
+
+            echo "Logging in to Docker Hub"
+            printf '%s' "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
+
+            COMPOSE_FILE="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/docker-compose.yml"
+            CONFIG_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/config.toml"
+            FIREBASE_CONFIG_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/firebase_config.json"
+            MEDIA_STAGING_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/media-staging"
+            IMAGE_SERVER_SSH_KEY_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/image_server_ssh_key"
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="/home/$DEPLOY_SERVER_USER/app_configs/core-framework/image_server_known_hosts"
+
+            echo "Pulling latest image"
+            DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
+            CONFIG_PATH="$CONFIG_PATH" \
+            FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
+            MEDIA_STAGING_PATH="$MEDIA_STAGING_PATH" \
+            IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
+            docker compose -f "$COMPOSE_FILE" pull
+
+            echo "Preparing media staging directory and image server SSH key permissions"
+            mkdir -p "$MEDIA_STAGING_PATH"
+            docker run --rm \
+              --user root \
+              -v "$MEDIA_STAGING_PATH:/app/media-staging" \
+              -v "$IMAGE_SERVER_SSH_KEY_PATH:/app/image-server-ssh-key" \
+              -v "$IMAGE_SERVER_KNOWN_HOSTS_PATH:/app/image-server-known-hosts" \
+              --entrypoint "" \
+              "$DOCKERHUB_USERNAME/core-framework:latest" \
+              sh -c 'mkdir -p /app/media-staging && chown -R appuser:appgroup /app/media-staging && chown appuser:appgroup /app/image-server-ssh-key && chmod 600 /app/image-server-ssh-key && chown appuser:appgroup /app/image-server-known-hosts && chmod 644 /app/image-server-known-hosts'
+
+            echo "Running database migrations (cf-alembic iterates core_framework.bundled_alembic.ALEMBIC_DOMAINS in order)"
+            docker run --rm \
+              --network host \
+              -v "$CONFIG_PATH:/app/config.toml:ro" \
+              "$DOCKERHUB_USERNAME/core-framework:latest" \
+              cf-alembic
+
+            echo "Starting services with Docker Compose"
+            DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
+            CONFIG_PATH="$CONFIG_PATH" \
+            FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
+            MEDIA_STAGING_PATH="$MEDIA_STAGING_PATH" \
+            IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
+            IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
+            docker compose -f "$COMPOSE_FILE" up -d \
+              --remove-orphans \
+              --force-recreate \
+              --scale worker="$WORKER_REPLICAS"
+
+            echo "Cleaning up dangling Docker images"
+            docker image prune -f
+
+            echo "Deployment complete"

core_framework-3.2.0/.github/workflows/dev-ci-cd.yaml

@@ -0,0 +1,235 @@
+name: Development CI/CD
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency:
+  group: core-framework-development
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  package-smoke:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.7.9"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Build wheel and verify install
+        run: |
+          set -euo pipefail
+          rm -rf dist
+          uv build
+          python -m venv /tmp/wheel-smoke
+          /tmp/wheel-smoke/bin/pip install --upgrade pip
+          WHL=$(echo dist/*.whl)
+          /tmp/wheel-smoke/bin/pip install "${WHL}"
+          /tmp/wheel-smoke/bin/python -c "
+          import core_framework
+          from core_framework.api.router import router
+          from core_framework.api.dependencies import RequiredUserID, check_not_banned
+          from core_framework.api.schemas import BasePatchRequest
+          from core_framework.application.analytics.registry import register_activity_source
+          from core_framework.application.bootstrap import configure_application_dependencies, configure_core_framework_runtime
+          from core_framework.application.events.event_service import register_event_handler
+          from core_framework.application.events.utm_capture_kinds import register_utm_capture_kind
+          from core_framework.bundled_alembic import bundled_alembic_root
+          from core_framework.core.runtime import CoreRuntime, build_core_runtime
+          from core_framework.core.settings import PostgresSchemasConfig, RetentionConfig, Settings, load_default_settings
+          from core_framework.domains.analytics import ActivitySourcePort
+          from core_framework.main import init_app
+          from core_framework.worker.main import (
+              CORE_FRAMEWORK_QUEUE_NAME,
+              WorkerSettings,
+              build_worker_settings_kwargs,
+              create_worker_settings_for_shared_runtime,
+          )
+          from core_framework.worker.schedules import build_schedules
+          from core_framework.worker.tasks import tasks
+          assert router is not None
+          assert init_app is not None
+          assert Settings is not None
+          assert load_default_settings is not None
+          assert PostgresSchemasConfig is not None
+          assert RetentionConfig is not None
+          assert RequiredUserID is not None
+          assert check_not_banned is not None
+          assert BasePatchRequest is not None
+          assert register_activity_source is not None
+          assert register_event_handler is not None
+          assert register_utm_capture_kind is not None
+          assert configure_application_dependencies is not None
+          assert configure_core_framework_runtime is not None
+          assert CoreRuntime is not None
+          assert build_core_runtime is not None
+          assert ActivitySourcePort is not None
+          assert WorkerSettings is not None
+          assert CORE_FRAMEWORK_QUEUE_NAME
+          assert build_worker_settings_kwargs is not None
+          assert create_worker_settings_for_shared_runtime is not None
+          assert build_schedules is not None
+          assert tasks
+          assert bundled_alembic_root().is_dir()
+          assert (bundled_alembic_root() / 'user' / 'alembic.ini').is_file()
+          "
+          /tmp/wheel-smoke/bin/pip install "${WHL}[testing]"
+          /tmp/wheel-smoke/bin/python -c "
+          from core_framework.testing import TestConfig, create_firebase_user_token
+          from core_framework.testing.media import reconfigure_media_for_testing
+          assert TestConfig is not None
+          assert create_firebase_user_token is not None
+          assert reconfigure_media_for_testing is not None
+          "
+          test -x /tmp/wheel-smoke/bin/cf-alembic
+
+  app-docker:
+    needs: [package-smoke]
+    runs-on: ubuntu-latest
+    environment: development
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Docker Meta
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ vars.DOCKERHUB_USERNAME }}/core-framework
+          flavor: latest=true
+
+      - name: Login to DockerHub
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Build and Push
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: ./deploy/app/dockerfile
+          target: api
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+
+  worker-docker:
+    needs: [package-smoke]
+    runs-on: ubuntu-latest
+    environment: development
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Docker Meta
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ vars.DOCKERHUB_USERNAME }}/core-framework-worker
+          flavor: latest=true
+
+      - name: Login to DockerHub
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Build and Push
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: ./deploy/app/dockerfile
+          target: worker
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+
+  deploy:
+    needs: [app-docker, worker-docker]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/_deploy.yml
+    with:
+      env_name: development
+      dockerhub_username: ${{ vars.DOCKERHUB_USERNAME }}
+    secrets:
+      SECRET_KEY: ${{ secrets.SECRET_KEY }}
+      WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
+      READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
+      FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
+      IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
+      IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}
+      DEPLOY_SERVER_SSH_KEY: ${{ secrets.DEPLOY_SERVER_SSH_KEY }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+  post-deploy-e2e:
+    needs: [deploy]
+    runs-on: ubuntu-latest
+    environment: development
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.7.9"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Post-deploy E2E
+        run: uv run pytest tests/e2e
+        env:
+          E2E_API_BASE_URL: ${{ vars.E2E_API_BASE_URL }}
+          E2E_FIREBASE_API_KEY: ${{ secrets.E2E_FIREBASE_API_KEY }}
+          E2E_USER_EMAIL: ${{ vars.E2E_USER_EMAIL }}
+          E2E_USER_PASSWORD: ${{ secrets.E2E_USER_PASSWORD }}
+          E2E_ADMIN_EMAIL: ${{ vars.E2E_ADMIN_EMAIL }}
+          E2E_ADMIN_PASSWORD: ${{ secrets.E2E_ADMIN_PASSWORD }}
+          E2E_MEDIA_BASE_URL: ${{ vars.E2E_MEDIA_BASE_URL }}
+          E2E_ALLOWED_ORIGIN: ${{ vars.E2E_ALLOWED_ORIGIN }}
+          E2E_WORKER_POLL_TIMEOUT_SEC: ${{ vars.E2E_WORKER_POLL_TIMEOUT_SEC }}