spaps 0.7.3 → 0.7.4

package/assets/local-runtime/alembic/versions/000000000016_issue_reporting_platform.py

@@ -0,0 +1,54 @@
+"""issue reporting platform
+
+Revision ID: 000000000016
+Revises: 000000000015
+Create Date: 2026-03-29
+
+Creates the issue_reports table for shared end-user issue reporting linked to
+the support_telemetry_platform support-case substrate.
+"""
+
+from alembic import op
+
+revision = "000000000016"
+down_revision = "000000000015"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS issue_reports (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            application_id UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+            reporter_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+            reporter_role_hint VARCHAR(64),
+            component_key VARCHAR(255) NOT NULL,
+            component_label VARCHAR(255) NOT NULL,
+            page_url VARCHAR(500) NOT NULL,
+            surface_ref VARCHAR(255),
+            target_metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+            note TEXT NOT NULL,
+            parent_issue_report_id UUID REFERENCES issue_reports(id) ON DELETE SET NULL,
+            support_case_id UUID NOT NULL REFERENCES support_cases(id) ON DELETE RESTRICT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+    """)
+
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_issue_reports_app_reporter_created
+        ON issue_reports (application_id, reporter_user_id, created_at);
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_issue_reports_support_case
+        ON issue_reports (support_case_id);
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_issue_reports_parent
+        ON issue_reports (parent_issue_report_id);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE IF EXISTS issue_reports CASCADE;")

package/assets/local-runtime/alembic/versions/000000000017_issue_reporting_platform_import_tracking.py

@@ -0,0 +1,44 @@
+"""issue reporting platform import tracking
+
+Revision ID: 000000000017
+Revises: 000000000016
+Create Date: 2026-03-29
+
+Adds replay-safe legacy source tracking to issue_reports so first-adopter
+cutovers can import HTMA issue logs without duplicating issue reports.
+"""
+
+from alembic import op
+
+revision = "000000000017"
+down_revision = "000000000016"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        ALTER TABLE issue_reports
+        ADD COLUMN IF NOT EXISTS source_app VARCHAR(64);
+    """)
+    op.execute("""
+        ALTER TABLE issue_reports
+        ADD COLUMN IF NOT EXISTS source_record_id VARCHAR(255);
+    """)
+    op.execute("""
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_issue_reports_source_ref
+        ON issue_reports (application_id, source_app, source_record_id)
+        WHERE source_app IS NOT NULL AND source_record_id IS NOT NULL;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS uq_issue_reports_source_ref;")
+    op.execute("""
+        ALTER TABLE issue_reports
+        DROP COLUMN IF EXISTS source_record_id;
+    """)
+    op.execute("""
+        ALTER TABLE issue_reports
+        DROP COLUMN IF EXISTS source_app;
+    """)

package/assets/local-runtime/alembic/versions/000000000018_authorization_policy_engine.py

@@ -0,0 +1,76 @@
+"""authorization policy engine
+
+Revision ID: 000000000018
+Revises: 000000000017
+Create Date: 2026-03-31
+
+Creates the policies and policy_evaluation_logs tables for the composable
+authorization policy engine.
+"""
+
+from alembic import op
+
+revision = "000000000018"
+down_revision = "000000000017"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS policies (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            application_id UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+            name VARCHAR(255) NOT NULL,
+            description TEXT,
+            effect VARCHAR(10) NOT NULL DEFAULT 'allow',
+            conditions JSONB NOT NULL DEFAULT '{}'::jsonb,
+            priority INTEGER NOT NULL DEFAULT 0,
+            is_active BOOLEAN NOT NULL DEFAULT true,
+            metadata JSONB DEFAULT '{}'::jsonb,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+    """)
+
+    # Unique constraint: one policy name per application
+    op.execute("""
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_policies_app_name
+        ON policies (application_id, name);
+    """)
+
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_policies_app_active
+        ON policies (application_id, is_active)
+        WHERE is_active = true;
+    """)
+
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS policy_evaluation_logs (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            policy_id UUID REFERENCES policies(id) ON DELETE SET NULL,
+            application_id UUID NOT NULL,
+            user_id UUID,
+            policy_name VARCHAR(255) NOT NULL,
+            decision VARCHAR(10) NOT NULL,
+            reasons JSONB NOT NULL DEFAULT '[]'::jsonb,
+            evaluation_ms INTEGER NOT NULL DEFAULT 0,
+            context_snapshot JSONB,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+    """)
+
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_policy_eval_logs_app_created
+        ON policy_evaluation_logs (application_id, created_at DESC);
+    """)
+
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_policy_eval_logs_policy_name
+        ON policy_evaluation_logs (application_id, policy_name);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE IF EXISTS policy_evaluation_logs;")
+    op.execute("DROP TABLE IF EXISTS policies;")

package/assets/local-runtime/alembic.ini

@@ -0,0 +1,47 @@
+# SPAPS Alembic configuration
+# Migrations live at repo root: sweet-potato/alembic/
+# Models are imported from: spaps_server_quickstart.domains
+
+[alembic]
+script_location = %(here)s/alembic
+prepend_sys_path = packages/python-server-quickstart/src
+path_separator = os
+
+# DATABASE_URL is set via env.py from settings
+sqlalchemy.url =
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

package/assets/local-runtime/docker-compose.yml

@@ -0,0 +1,61 @@
+services:
+  spaps-dev-api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        SPAPS_SERVER_QUICKSTART_VERSION: ${SPAPS_SERVER_QUICKSTART_VERSION:-0.5.0}
+    restart: unless-stopped
+    ports:
+      - "${SPAPS_LOCAL_PORT:-3301}:8000"
+    environment:
+      ENV: dev
+      DATABASE_URL: postgresql+asyncpg://postgres:postgres@spaps-dev-db:5432/spaps
+      REDIS_URL: redis://spaps-dev-redis:6379/0
+      SPAPS_LOCAL_MODE: "${SPAPS_LOCAL_MODE:-true}"
+      JWT_SECRET: "${JWT_SECRET:-spaps_local_dev_jwt_secret}"
+      REFRESH_TOKEN_SECRET: "${REFRESH_TOKEN_SECRET:-spaps_local_dev_refresh_secret}"
+      SELF_SERVICE_PASSWORD: "${SELF_SERVICE_PASSWORD:-spaps_local_self_service_password}"
+      ALEMBIC_RUN_ON_START_ROLE: primary
+      LOG_LEVEL: DEBUG
+      LOG_FORMAT: console
+      AUTH_BASE_URL: "${SPAPS_AUTH_BASE_URL:-http://localhost:5173}"
+      CORS_ALLOW_ORIGINS: "${CORS_ALLOW_ORIGINS:-*}"
+      LEGACY_API_KEY_AUTH_ENABLED: "${LEGACY_API_KEY_AUTH_ENABLED:-true}"
+    depends_on:
+      spaps-dev-db:
+        condition: service_healthy
+      spaps-dev-redis:
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "python", "-c", "import httpx; r = httpx.get('http://localhost:8000/health'); r.raise_for_status()"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  spaps-dev-db:
+    image: ankane/pgvector:v0.5.1
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: spaps
+    volumes:
+      - spaps-dev-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  spaps-dev-redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: redis-server --appendonly yes
+    volumes:
+      - spaps-dev-redisdata:/data
+
+volumes:
+  spaps-dev-pgdata:
+  spaps-dev-redisdata:

package/assets/local-runtime/manifest.json

@@ -0,0 +1,8 @@
+{
+  "spaps_server_quickstart_version": "0.5.0",
+  "portable_runtime": {
+    "default_local_mode": true,
+    "default_auth_base_url": "http://localhost:5173",
+    "default_self_service_password": "spaps_local_self_service_password"
+  }
+}

package/assets/local-runtime/scripts/container-entrypoint.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${APP_ROOT:-/app}"
+MIGRATION_RUNNER="${ROOT}/scripts/run-migrations.sh"
+
+if [[ -x "${MIGRATION_RUNNER}" ]]; then
+  "${MIGRATION_RUNNER}"
+else
+  echo "⚠️  ${MIGRATION_RUNNER} not executable; skipping migrations." >&2
+fi
+
+exec "$@"

package/assets/local-runtime/scripts/fetch-prod-db.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fetch SPAPS production database dump via SSH (read-only on production).
+# Output: ${SPAPS_CACHE_ROOT:-~/.cache/spaps}/db/prod.sql.gz
+#
+# Environment variables:
+#   SPAPS_PROD_DB_FRESH=1         Force re-fetch even if a cached dump exists
+#   SPAPS_CACHE_ROOT              Override cache directory
+#   SPAPS_PROD_HOST               Primary SSH host
+#   SPAPS_PROD_HOST_FALLBACK      Fallback SSH host
+#   SPAPS_SSH_BIN                 SSH binary path
+
+PRIMARY_PROD_HOST="${SPAPS_PROD_HOST:-aiops@sweet-potato-prod}"
+FALLBACK_PROD_HOST="${SPAPS_PROD_HOST_FALLBACK:-root@104.131.188.214}"
+PROD_HOST=""
+SSH_BIN="${SPAPS_SSH_BIN:-ssh}"
+CACHE_DIR="${SPAPS_CACHE_ROOT:-${HOME}/.cache/spaps}/db"
+PROD_DUMP="${CACHE_DIR}/prod.sql.gz"
+FRESH="${SPAPS_PROD_DB_FRESH:-0}"
+
+info() {
+  printf '\n%s %s\n' "🔧" "$1"
+}
+
+err() {
+  printf '\n%s %s\n' "❌" "$1" >&2
+}
+
+resolve_prod_host() {
+  local candidate
+  local candidates=("${PRIMARY_PROD_HOST}")
+  if [[ -n "${FALLBACK_PROD_HOST}" && "${FALLBACK_PROD_HOST}" != "${PRIMARY_PROD_HOST}" ]]; then
+    candidates+=("${FALLBACK_PROD_HOST}")
+  fi
+
+  for candidate in "${candidates[@]}"; do
+    info "Testing SSH connection to ${candidate}..."
+    if "${SSH_BIN}" -o ConnectTimeout=5 -o BatchMode=yes "${candidate}" "echo ok" >/dev/null 2>&1; then
+      PROD_HOST="${candidate}"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+if [[ -f "${PROD_DUMP}" ]]; then
+  case "${FRESH}" in
+    1|true|TRUE|yes|YES)
+      info "SPAPS_PROD_DB_FRESH=1 set, fetching fresh dump from production..."
+      ;;
+    *)
+      DUMP_AGE=$(( $(date +%s) - $(stat -f %m "${PROD_DUMP}" 2>/dev/null || stat -c %Y "${PROD_DUMP}" 2>/dev/null) ))
+      DUMP_AGE_HOURS=$(( DUMP_AGE / 3600 ))
+      info "Using cached prod dump (${DUMP_AGE_HOURS}h old): ${PROD_DUMP}"
+      info "Run with SPAPS_PROD_DB_FRESH=1 to fetch fresh data."
+      exit 0
+      ;;
+  esac
+fi
+
+mkdir -p "${CACHE_DIR}"
+
+if ! command -v "${SSH_BIN}" >/dev/null 2>&1; then
+  err "ssh command not found: ${SSH_BIN}"
+  exit 1
+fi
+
+if ! resolve_prod_host; then
+  err "Cannot connect to any configured production host."
+  err "Tried: ${PRIMARY_PROD_HOST} ${FALLBACK_PROD_HOST}"
+  err "Check your SSH key is loaded: ssh-add -l"
+  err "Try manually: ssh ${PRIMARY_PROD_HOST}"
+  exit 1
+fi
+info "Using production SSH host: ${PROD_HOST}"
+
+info "Fetching SPAPS production database dump via SSH (read-only)..."
+info "This may take a minute..."
+
+set +e
+"${SSH_BIN}" "${PROD_HOST}" "docker exec spaps-python-db pg_dump -U spaps spaps" 2>"${PROD_DUMP}.err" | gzip > "${PROD_DUMP}.tmp"
+pipe_status=("${PIPESTATUS[@]}")
+set -e
+ssh_status=${pipe_status[0]:-1}
+gzip_status=${pipe_status[1]:-1}
+
+if [[ $ssh_status -ne 0 || $gzip_status -ne 0 ]]; then
+  err "Failed to dump production database (ssh exit ${ssh_status}, gzip exit ${gzip_status})"
+  if [[ $gzip_status -ne 0 ]]; then
+    err "Local compression/write failed (check disk space and file permissions)."
+  fi
+  if [[ -s "${PROD_DUMP}.err" ]]; then
+    err "Error output:"
+    cat "${PROD_DUMP}.err" >&2
+  fi
+  rm -f "${PROD_DUMP}.tmp" "${PROD_DUMP}.err"
+  exit 1
+fi
+rm -f "${PROD_DUMP}.err"
+
+if [[ ! -s "${PROD_DUMP}.tmp" ]]; then
+  err "Dump file is empty"
+  rm -f "${PROD_DUMP}.tmp"
+  exit 1
+fi
+
+mv "${PROD_DUMP}.tmp" "${PROD_DUMP}"
+
+DUMP_SIZE=$(du -h "${PROD_DUMP}" | cut -f1)
+info "Production dump saved: ${PROD_DUMP} (${DUMP_SIZE})"

package/assets/local-runtime/scripts/run-migrations.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${APP_ROOT:-/app}"
+PYTHON_BIN="${PYTHON_BIN:-python}"
+
+if [[ ! -d "${ROOT}" ]]; then
+  echo "⚠️  Application root ${ROOT} not found; skipping migrations." >&2
+  exit 0
+fi
+
+cd "${ROOT}"
+
+if [[ ! -f "${ROOT}/alembic.ini" ]]; then
+  echo "⚠️  alembic.ini not present in ${ROOT}; skipping migrations." >&2
+  exit 0
+fi
+
+if [[ "${ALEMBIC_SKIP_ON_START:-0}" == "1" ]]; then
+  echo "ℹ️  ALEMBIC_SKIP_ON_START=1; skipping migrations."
+  exit 0
+fi
+
+ROLE="${ALEMBIC_RUN_ON_START_ROLE:-primary}"
+
+if [[ "${ROLE}" == "primary" ]]; then
+  echo "🏃 Applying database migrations..."
+else
+  echo "ℹ️  ALEMBIC_RUN_ON_START_ROLE=${ROLE}; verifying schema without applying upgrades."
+fi
+
+normalize_revisions() {
+  matches="$(printf '%s\n' "$1" | grep -Eo '[0-9a-f]{12,}' | sort -u | paste -sd ',' -)"
+  if [[ -n "${matches}" ]]; then
+    printf '%s' "${matches}"
+  fi
+}
+
+restore_database_url() {
+  if [[ "${ORIGINAL_DATABASE_URL}" != "__unset__" ]]; then
+    export DATABASE_URL="${ORIGINAL_DATABASE_URL}"
+  else
+    unset DATABASE_URL
+  fi
+}
+
+assert_single_head() {
+  local heads_raw heads
+  heads_raw="$("${PYTHON_BIN}" -m alembic heads || true)"
+  heads="$(normalize_revisions "${heads_raw:-}")"
+  if [[ -n "${heads}" && "${heads}" == *","* ]]; then
+    echo "❌ Multiple Alembic heads detected (${heads})." >&2
+    echo "   HINT: Align migration down_revision values or create a merge revision to restore a single head." >&2
+    restore_database_url
+    exit 1
+  fi
+}
+
+# Get sync (non-async) database URL from SPAPS settings
+SYNC_URL="$("${PYTHON_BIN}" - <<'PY'
+from spaps_server_quickstart.spaps_settings import get_spaps_settings
+print(get_spaps_settings().sync_database_url, end="")
+PY
+)"
+
+ORIGINAL_DATABASE_URL="${DATABASE_URL-__unset__}"
+if [[ -n "${SYNC_URL}" ]]; then
+  export DATABASE_URL="${SYNC_URL}"
+fi
+
+assert_single_head
+
+if [[ "${ROLE}" == "primary" ]]; then
+  "${PYTHON_BIN}" -m alembic upgrade head
+else
+  echo "ℹ️  Skipping alembic upgrade (role=${ROLE})."
+fi
+
+current_raw="$("${PYTHON_BIN}" -m alembic current || true)"
+heads_raw="$("${PYTHON_BIN}" -m alembic heads || true)"
+
+current="$(normalize_revisions "${current_raw:-}")"
+heads="$(normalize_revisions "${heads_raw:-}")"
+
+if [[ -n "${heads}" && "${current}" != "${heads}" ]]; then
+  echo "❌ Alembic drift detected (current=${current:-none} expected=${heads:-none})." >&2
+  if [[ "${ROLE}" != "primary" ]]; then
+    echo "   HINT: Ensure the primary migration runner has applied upgrades." >&2
+  fi
+  restore_database_url
+  exit 1
+fi
+
+restore_database_url
+
+echo "✅ Alembic migrations current (${current:-none})."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {
@@ -52,6 +52,7 @@
   "files": [
     "bin",
     "src",
+    "assets",
     "AI_TOOLS.json",
     "client.js",
     "README.md"