spaps 0.7.3 → 0.7.4

package/AI_TOOLS.json

@@ -1,19 +1,19 @@
 {
   "name": "spaps",
-  "version": "0.1.0",
-  "description": "Auth + payments via SPAPS (local by default). Start with: npx spaps local",
+  "version": "0.7.4",
+  "description": "Auth + payments via SPAPS. Runtime auth requirements come from /health/local-mode or `npx spaps tools --json`.",
   "base_url": "http://localhost:3301",
   "auth": {
-    "local_mode": true,
-    "production": {
-      "header": "X-API-Key",
-      "env": "SPAPS_API_KEY"
-    }
+    "local_mode": null,
+    "mode_source": "/health/local-mode",
+    "api_key_required_when_local_mode_disabled": true,
+    "header": "X-API-Key",
+    "env": "SPAPS_API_KEY"
   },
   "tools": [
     {
       "name": "login",
-      "description": "Login with email/password. Local mode accepts any values.",
+      "description": "Login with email/password. Send X-API-Key when local mode is disabled.",
       "method": "POST",
       "path": "/api/auth/login",
       "parameters": {
@@ -71,7 +71,7 @@
     },
     {
       "name": "list_products",
-      "description": "List products (Stripe-backed or local).",
+      "description": "List products exposed by the SPAPS server.",
       "method": "GET",
       "path": "/api/stripe/products",
       "parameters": {
@@ -84,7 +84,7 @@
     },
     {
       "name": "request_magic_link",
-      "description": "Send a magic link for passwordless login (simulated locally).",
+      "description": "Send a magic link for passwordless login.",
       "method": "POST",
       "path": "/api/auth/magic-link",
       "parameters": {
@@ -111,4 +111,3 @@
     }
   ]
 }
-

package/README.md

@@ -1,8 +1,73 @@
 # spaps
 
-CLI and middleware package for local SPAPS workflows.
+Test SPAPS auth in a new app before you build auth backend infrastructure.
 
-Examples in this README use placeholder emails and local-only defaults. Replace them with your own values if you wire the middleware into an app.
+`spaps` is the shortest path from "I have a new frontend" to "this app can hit authenticated SPAPS routes locally." It wraps the local SPAPS server, tells you what auth mode the server is actually in, scaffolds starter code, and provisions a real local application when the server requires one.
+
+## TL;DR
+
+### The problem
+
+You want to wire auth into a new app, but you do not want to design and ship your own auth backend first.
+
+### The shortcut
+
+Run SPAPS locally, inspect the current auth mode, then either use local mode directly or provision a real local app with one command. The CLI tells you which mode the server is actually in, so you do not have to guess.
+
+### Why Use `spaps`?
+
+| Need | `spaps` gives you |
+| --- | --- |
+| "Can I test auth in this app today?" | `spaps local`, `status`, and `quickstart` |
+| "Do I need a real app key or not?" | Runtime truth from `/health/local-mode` |
+| "Can you scaffold the wiring for me?" | `spaps create <name> --template ...` |
+| "I want a working local app, not a fake contract" | Self-service provisioning when `SELF_SERVICE_PASSWORD` is available |
+| "If provisioning fails, tell me exactly why" | Explicit `scaffold_only` fallback and warnings |
+| "I want persistent local personas, roles, and entitlements in this repo" | `spaps fixtures ...` and a repo-local `.spaps/` kernel |
+
+## No Backend Yet? Start Here
+
+```bash
+npx spaps local
+npx spaps quickstart --json | jq '.auth'
+SELF_SERVICE_PASSWORD=your-password npx spaps create demo-app --template react
+cd demo-app
+npm install
+```
+
+What happens next depends on the server mode:
+
+| Server state | What `spaps` does | What you do |
+| --- | --- | --- |
+| `local_mode_active: true` | Exposes local-mode hints and test personas | Use the starter against `localhost`; no app key provisioning required |
+| `local_mode_active: false` and `SELF_SERVICE_PASSWORD` is set | Provisions a real local SPAPS app and writes the working key into `.env.local` | Start wiring auth flows in your app immediately |
+| Server unreachable or no self-service password | Scaffolds files only and tells you why provisioning was skipped | Bring the server up or rerun with `SELF_SERVICE_PASSWORD` later |
+
+This package targets `Node.js >=22`.
+
+## Local Runtime Modes
+
+`spaps local` now has two runtime paths:
+
+| Runtime path | When it is used | What it does |
+| --- | --- | --- |
+| `repo` | You are running from the `sweet-potato` checkout | Uses the repo's Docker Compose stack and source-mounted assets |
+| `bundle` | You installed `spaps` from npm elsewhere | Uses bundled Docker assets plus the published `spaps-server-quickstart` package |
+
+The default is `auto`: use repo assets when they exist, otherwise fall back to the bundled runtime. The bundled runtime defaults to `SPAPS_LOCAL_MODE=true`, so RBAC fixtures and test personas work out of the box.
+
+## Local Data Sources
+
+`spaps local` separates runtime selection from base data selection:
+
+| Data source | What it does |
+| --- | --- |
+| `empty` | Boot an empty local DB and let migrations create schema |
+| `prod-cache` | Restore the cached SPAPS production dump before the API starts, then reuse it until the cached dump changes |
+| `prod-fresh` | Force a fresh production dump fetch, restore it, then boot the API |
+| `--from-backup <path>` | Restore a specific `.sql.gz` dump file before boot |
+
+Restore order is always: restore base dump first, then let the API container run migrations to head on top of it.
 
 ## Install
 
@@ -24,42 +89,28 @@ Add it to a project:
 npm install spaps
 ```
 
-This package targets `Node.js >=22`.
-
-## When It Fits
-
-| Need | Package gives you |
-| --- | --- |
-| A local SPAPS control surface | `local`, `status`, `doctor`, and `quickstart` commands |
-| Project bootstrap | `spaps init` creates a starter `.env.local` |
-| AI tooling integration | `spaps tools` emits an OpenAI-style tool spec |
-| Lightweight Node middleware | Admin and permission helpers for Express-style apps |
-
 ## Quick Start
 
-```bash
-# Start the local server
-npx spaps local
-
-# Confirm it is healthy
-npx spaps status
-
-# Create a starter .env.local in the current project
-npx spaps init
-
-# Emit the local tool spec as JSON
-npx spaps tools --json
-```
+| Step | Command | Why |
+| --- | --- |
+| 1 | `npx spaps local` | Start the local SPAPS stack |
+| 1b | `npx spaps local --data-source prod-cache` | Start the local stack with a cached prod-backed base DB |
+| 2 | `npx spaps status --json` | Confirm the server is reachable |
+| 3 | `npx spaps quickstart --json` | See whether local mode is active or a real app key is required |
+| 4 | `npx spaps create my-app --template react` | Scaffold a starter and, when possible, provision a real local app |
+| 5 | `npx spaps tools --json` | Export the current AI tool contract for agents or tests |
+| 6 | `npx spaps fixtures apply` | Materialize repo-local personas into Playwright/browser artifacts |
 
 ## CLI Surface
 
 | Command | Purpose | Common flags |
 | --- | --- | --- |
-| `spaps local [stop]` | Start or stop the local server workflow | `--port`, `--detach`, `--fresh`, `--from-backup`, `--open`, `--json` |
+| `spaps local [stop]` | Start or stop the local server workflow | `--port`, `--runtime-dir`, `--runtime-source`, `--data-source`, `--detach`, `--fresh`, `--from-backup`, `--open`, `--json` |
 | `spaps status` | Check whether the local server is running | `--port`, `--json` |
 | `spaps quickstart` | Print quick-start instructions | `--port`, `--json` |
 | `spaps init` | Create a starter `.env.local` | `--json` |
-| `spaps create <name>` | Scaffold a SPAPS starter project directory | `--template`, `--dir`, `--force`, `--json` |
+| `spaps create <name>` | Scaffold a SPAPS starter project directory and try local provisioning | `--template`, `--dir`, `--port`, `--force`, `--json` |
+| `spaps fixtures <subcommand>` | Manage repo-local `.spaps` auth fixtures | `--dir`, `--port`, `--base-url`, `--persona`, `--format`, `--force`, `--json` |
 | `spaps docs` | Browse or search bundled docs | `--interactive`, `--search`, `--json` |
 | `spaps tools` | Emit the AI tool spec | `--port`, `--format`, `--json` |
 | `spaps doctor` | Diagnose local environment problems | `--port`, `--stripe`, `--json` |
@@ -68,13 +119,52 @@ Example command usage:
 
 ```bash
 spaps local --port 3400 --detach
+spaps local --runtime-source bundle --runtime-dir ./.skillbox/spaps-local
+spaps local --runtime-source repo --data-source prod-cache
+spaps local --runtime-source repo --fresh --data-source prod-fresh
+spaps local --from-backup ~/.cache/spaps/db/prod.sql.gz
 spaps status --json
 spaps create my-app --template react
+spaps login --json
+spaps fixtures apply --base-url http://localhost:5173
+spaps fixtures storage-state --persona admin
 spaps docs --search secure-messages
 spaps doctor --stripe mock
 spaps local stop
 ```
 
+## CLI Auth
+
+`spaps login` uses the active FastAPI device-flow contract:
+
+- device authorization at `/api/cli/device/*`
+- authenticated follow-up calls at `/api/auth/*`
+- standard SPAPS response envelopes
+
+The CLI no longer assumes a built-in `spaps-cli` application slug. Resolve the client id in this order:
+
+- `--client-id <app-slug>`
+- `SPAPS_CLI_CLIENT_ID`
+- repo-local `spaps.app.json`
+- repo-local `.spaps/app.json`
+- `/health/local-mode` test application metadata
+
+Authenticated follow-up calls such as `whoami`, `logout`, and token refresh still need a normal SPAPS app key when the server is not in local mode. The CLI resolves that key from:
+
+- `SPAPS_API_KEY`
+- `NEXT_PUBLIC_SPAPS_API_KEY`
+- `VITE_SPAPS_API_KEY`
+- repo-local `.env.local`
+- repo-local `.env`
+
+Examples:
+
+```bash
+npx spaps login --client-id my-app
+SPAPS_CLI_CLIENT_ID=my-app npx spaps login
+VITE_SPAPS_API_KEY=spaps_pub_demo npx spaps whoami --json
+```
+
 Still reserved and not finished:
 
 - `spaps types`
@@ -84,10 +174,12 @@ Still reserved and not finished:
 `spaps create` ships a local-first starter kit rather than a full framework generator. It creates a new directory with:
 
 - `spaps.app.json` for the machine-readable SPAPS app contract
-- `.env.local` pointing at local SPAPS
+- `.env.local` pointing at local SPAPS and, when available, a working template-appropriate key
 - `package.json` with `spaps-sdk`
 - a small template-specific integration starter
 
+When the local server is reachable and `SELF_SERVICE_PASSWORD` is set, `create` also provisions a real local SPAPS application. When that is not possible, it falls back to scaffold-only mode and tells you why.
+
 Supported templates:
 
 - `nextjs`
@@ -95,13 +187,60 @@ Supported templates:
 - `node`
 - `vanilla`
 
-Example:
+Examples:
 
 ```bash
 npx spaps create my-app --template react
 npx spaps create my-api --template node --dir ./services/my-api
+SELF_SERVICE_PASSWORD=your-password npx spaps create my-app --template react
+```
+
+The generated starter is template-aware:
+
+- browser templates write a publishable key when provisioning succeeds
+- server templates write a server key when provisioning succeeds
+- `spaps.app.json` records provisioning status and application id, but never stores raw keys
+
+## Repo-Local Fixtures
+
+Use `.spaps/` when you want persistent local personas for clicking around, Playwright, or app-level auth tests without inventing ad hoc storage keys in each repo.
+
+`spaps fixtures init` creates:
+
+- `.spaps/app.json` for runtime and browser target settings
+- `.spaps/users.json` for personas and profile data
+- `.spaps/roles.json` for RBAC grants
+- `.spaps/entitlements.json` for entitlement grants
+- `.spaps/browser/` for generated storage-state and header artifacts
+
+Then run:
+
+```bash
+npx spaps fixtures apply --base-url http://localhost:5173
+npx spaps fixtures storage-state --persona admin
 ```
 
+What `apply` emits:
+
+- `browser/<persona>.storage-state.json` for Playwright `storageState`
+- `browser/<persona>.headers.json` for `extraHTTPHeaders`
+- `browser/<persona>.context.json` with merged persona/runtime metadata
+- `public/spaps-dev-auth.js` for frontend-only auth/RBAC dev mode
+
+This does not try to import browser password-manager state. It writes deterministic, repo-local test artifacts instead.
+
+If you want a human to launch the frontend and click around without a mock backend, include the generated bridge before your app boots:
+
+```html
+<script src="/spaps-dev-auth.js"></script>
+```
+
+That bridge does three things:
+
+- seeds SDK-compatible localStorage keys like `sweet_potato_user` and `sweet_potato_access_token`
+- intercepts `/api/auth/user`, `/api/auth/login`, `/api/auth/logout`, `/api/entitlements`, and `/api/entitlements/check`
+- renders a tiny persona switcher so you can flip between `user`, `admin`, and `premium`
+
 ## Middleware Example
 
 The main module exports admin and permission helpers for Express-style apps.
@@ -144,9 +283,19 @@ Start on another port:
 npx spaps local --port 3400
 ```
 
+### I need deterministic portable runtime files
+
+Pin the bundled runtime directory explicitly:
+
+```bash
+npx spaps local --runtime-source bundle --runtime-dir ./.skillbox/spaps-local
+```
+
+This is the recommended path for managed environments such as skillbox.
+
 ### I need machine-readable output
 
-Use `--json` on commands that support it, including `local`, `status`, `quickstart`, `init`, `docs`, `tools`, and `doctor`.
+Use `--json` on commands that support it, including `local`, `status`, `quickstart`, `init`, `fixtures`, `docs`, `tools`, and `doctor`.
 
 ### The local server is not responding
 
@@ -162,6 +311,37 @@ If needed, restart with a clean boot:
 npx spaps local --fresh
 ```
 
+If you want the old "db=fresh from prod" behavior through the portable CLI:
+
+```bash
+npx spaps local --fresh --data-source prod-fresh
+```
+
+If you want to keep a cached prod-backed base DB around for day-to-day work:
+
+```bash
+npx spaps local --data-source prod-cache
+```
+
+### `spaps create` only scaffolded files
+
+That means one of two things:
+
+- the local server was unreachable
+- the server is not in local mode and `SELF_SERVICE_PASSWORD` was missing or invalid
+
+Check the current mode first:
+
+```bash
+npx spaps quickstart --json
+```
+
+If the server requires provisioning, rerun with:
+
+```bash
+SELF_SERVICE_PASSWORD=your-password npx spaps create my-app --template react --force
+```
+
 ## Limitations
 
 - The CLI is aimed at local workflows. It is not a full deployment or hosting tool.
@@ -171,6 +351,10 @@ npx spaps local --fresh
 
 ## FAQ
 
+### What is this package actually for?
+
+Use it when you want to prove auth wiring in a new app before you build backend auth infrastructure yourself.
+
 ### Does this package include the TypeScript SDK?
 
 No. The SDK is published separately as `spaps-sdk`.
@@ -185,16 +369,12 @@ No. It skips `.env.local` if the file already exists.
 
 ### What does `spaps tools` output?
 
-An OpenAI-style tool spec for the local SPAPS surface.
+An OpenAI-style tool spec for the local SPAPS surface. The auth section is derived from `/health/local-mode` when the local server is reachable.
 
 ### Is the middleware available from a subpath?
 
 Yes. You can import from the main module or `spaps/middleware`.
 
-## About Contributions
-
-> *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
-
 ## License
 
 MIT

package/assets/local-runtime/Dockerfile

@@ -0,0 +1,28 @@
+# Portable SPAPS local runtime image.
+# Built from bundled assets shipped inside the npm package.
+
+FROM python:3.12-slim AS base
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libpq-dev \
+        gcc \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.0
+RUN pip install --no-cache-dir "spaps-server-quickstart==${SPAPS_SERVER_QUICKSTART_VERSION}"
+
+COPY alembic.ini /app/alembic.ini
+COPY alembic/ /app/alembic/
+COPY scripts/ /app/scripts/
+
+ENV APP_ROOT=/app
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+ENTRYPOINT ["/app/scripts/container-entrypoint.sh"]
+CMD ["uvicorn", "spaps_server_quickstart.spaps_app:app", "--host", "0.0.0.0", "--port", "8000"]

package/assets/local-runtime/alembic/env.py

@@ -0,0 +1,101 @@
+"""
+Alembic environment for SPAPS.
+
+Imports all domain models from spaps_server_quickstart.domains so that
+``Base.metadata`` contains every table. Alembic uses this metadata for
+autogenerate and schema diffing.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+# Ensure Alembic helper modules are importable, then prefer the active
+# quickstart source tree (for local Docker this should be the live /app/src bind
+# mount, not the packaged fallback copied into the image).
+sys.path.insert(0, os.path.dirname(__file__))
+
+from path_bootstrap import ensure_quickstart_src_path  # noqa: E402
+
+ensure_quickstart_src_path(__file__, sys.path)
+
+from spaps_server_quickstart.domains._db.base import Base  # noqa: E402
+
+# Phase 1+: import domain models here so Base.metadata picks them up
+# from spaps_server_quickstart.domains.users.models import User  # noqa: E402, F401
+# from spaps_server_quickstart.domains.auth.models import ...  # noqa: E402, F401
+from spaps_server_quickstart.domains.approval_authz_prod_hardening.models import GovernanceAuthzAuditEvent  # noqa: E402, F401
+from spaps_server_quickstart.domains.support_telemetry_platform.models import SupportCase, SupportCaseEvent  # noqa: E402, F401
+from spaps_server_quickstart.domains.issue_reporting_platform.models import IssueReport  # noqa: E402, F401
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def get_database_url() -> str:
+    """Resolve the database URL from environment or settings."""
+    url = os.environ.get("DATABASE_URL", "")
+    if url:
+        # Alembic runs synchronously — convert asyncpg to psycopg
+        if "asyncpg" in url:
+            url = url.replace("postgresql+asyncpg", "postgresql+psycopg")
+        return url
+
+    # Fallback: try loading from settings
+    try:
+        from spaps_server_quickstart.spaps_settings import get_spaps_settings
+
+        settings = get_spaps_settings()
+        return settings.sync_database_url
+    except Exception:
+        return "postgresql+psycopg://postgres:postgres@localhost:5432/spaps"
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode (generate SQL without DB connection)."""
+    url = get_database_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations with a live database connection."""
+    alembic_config = config.get_section(config.config_ini_section, {})
+    alembic_config["sqlalchemy.url"] = get_database_url()
+
+    connectable = engine_from_config(
+        alembic_config,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/assets/local-runtime/alembic/path_bootstrap.py

@@ -0,0 +1,71 @@
+"""Helpers for locating the active quickstart source tree for Alembic."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import MutableSequence, Sequence
+
+
+_PACKAGE_DIRNAME = "spaps_server_quickstart"
+
+
+def _dedupe_paths(raw_paths: Sequence[str | Path]) -> list[Path]:
+    """Normalize candidate paths while preserving first-seen order."""
+    seen: set[str] = set()
+    candidates: list[Path] = []
+    for raw_path in raw_paths:
+        if not raw_path:
+            continue
+        path = Path(raw_path).resolve()
+        normalized = str(path)
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        candidates.append(path)
+    return candidates
+
+
+def resolve_quickstart_src_path(
+    alembic_env_path: str | Path,
+    sys_path: Sequence[str],
+) -> str | None:
+    """Return the best source root that contains the quickstart package.
+
+    Preference order:
+    1. Existing `sys.path` entries that already expose the package. This keeps
+       Docker bind mounts like `/app/src` ahead of any packaged fallback.
+    2. Known fallback roots relative to `alembic/env.py`.
+    """
+
+    alembic_dir = Path(alembic_env_path).resolve().parent
+    fallback_paths = [
+        Path("/app/src"),
+        alembic_dir.parent / "packages" / "python-server-quickstart" / "src",
+    ]
+
+    for candidate in _dedupe_paths([*sys_path, *fallback_paths]):
+        if (candidate / _PACKAGE_DIRNAME).exists():
+            return str(candidate)
+
+    return None
+
+
+def ensure_quickstart_src_path(
+    alembic_env_path: str | Path,
+    sys_path: MutableSequence[str],
+) -> str | None:
+    """Move the resolved quickstart source root to the front of sys.path."""
+
+    resolved = resolve_quickstart_src_path(alembic_env_path, list(sys_path))
+    if resolved is None:
+        return None
+
+    resolved_path = Path(resolved).resolve()
+    filtered = [
+        entry
+        for entry in sys_path
+        if not entry or Path(entry).resolve() != resolved_path
+    ]
+    sys_path[:] = filtered
+    sys_path.insert(0, resolved)
+    return resolved