spaps 0.7.2 → 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,223 +1,380 @@
 # spaps
 
-CLI and middleware package for local SPAPS workflows.
+Test SPAPS auth in a new app before you build auth backend infrastructure.
+
+`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**: Local auth and payment development is slow when every app has to bootstrap a backend, wire environment files, and remember the right health and docs commands.
+### 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
 
-**The Solution**: `spaps` gives you a small CLI for local-server workflows plus exported admin middleware helpers for Node apps that integrate with SPAPS.
+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`?
 
-| Feature | What It Does |
+| 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 |
 | --- | --- |
-| Local server workflow | Start, stop, inspect, and diagnose a local SPAPS server from the CLI |
-| Project bootstrap | Create a starter `.env.local` for SPAPS-aware projects |
-| AI tooling output | Emit the local OpenAI-style tool spec with `spaps tools` |
-| Middleware exports | Reuse admin-permission helpers from the package API |
+| `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.
 
-## Installation
+## Install
 
-### Run Without Installing
+Run it without installing:
 
 ```bash
 npx spaps help
 ```
 
-### Global Install
+Install globally:
 
 ```bash
 npm install -g spaps
 ```
 
-### Project Dependency
+Add it to a project:
 
 ```bash
 npm install spaps
 ```
 
-## Quick Example
+## Quick Start
+
+| 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`, `--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 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` |
+
+Example command usage:
 
 ```bash
-# Start the local server
-npx spaps local
+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
+```
 
-# Check status
-npx spaps status
+## CLI Auth
 
-# Initialize .env.local in the current project
-npx spaps init
+`spaps login` uses the active FastAPI device-flow contract:
 
-# Emit the local tool spec as JSON
-npx spaps tools --json
-```
+- 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:
 
-## CLI Commands
+- `--client-id <app-slug>`
+- `SPAPS_CLI_CLIENT_ID`
+- repo-local `spaps.app.json`
+- repo-local `.spaps/app.json`
+- `/health/local-mode` test application metadata
 
-### `spaps local [subcommand]`
+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:
 
-Start or stop the local SPAPS server.
+- `SPAPS_API_KEY`
+- `NEXT_PUBLIC_SPAPS_API_KEY`
+- `VITE_SPAPS_API_KEY`
+- repo-local `.env.local`
+- repo-local `.env`
+
+Examples:
 
 ```bash
-spaps local
-spaps local --port 3400
-spaps local --detach
-spaps local --open
-spaps local stop
+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
 ```
 
-Supported flags:
+Still reserved and not finished:
 
-- `--port <port>`
-- `--detach`
-- `--fresh`
-- `--from-backup <path>`
-- `--open`
-- `--json`
+- `spaps types`
 
-### `spaps status`
+## Create A Starter Project
 
-```bash
-spaps status
-spaps status --port 3400
-spaps status --json
-```
+`spaps create` ships a local-first starter kit rather than a full framework generator. It creates a new directory with:
 
-### `spaps quickstart`
+- `spaps.app.json` for the machine-readable SPAPS app contract
+- `.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
 
-```bash
-spaps quickstart
-spaps quickstart --port 3400
-spaps quickstart --json
-```
+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.
 
-### `spaps init`
+Supported templates:
 
-```bash
-spaps init
-spaps init --json
-```
+- `nextjs`
+- `react`
+- `node`
+- `vanilla`
 
-### `spaps docs`
+Examples:
 
 ```bash
-spaps docs
-spaps docs --interactive
-spaps docs --search secure-messages
-spaps docs --json
+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
 ```
 
-### `spaps tools`
+The generated starter is template-aware:
 
-```bash
-spaps tools
-spaps tools --port 3400
-spaps tools --format openai
-spaps tools --json
-```
+- 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 doctor`
+`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
-spaps doctor
-spaps doctor --port 3400
-spaps doctor --stripe mock
-spaps doctor --json
+npx spaps fixtures apply --base-url http://localhost:5173
+npx spaps fixtures storage-state --persona admin
 ```
 
-### Placeholder Commands
+What `apply` emits:
 
-The CLI currently includes placeholders for:
+- `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
 
-- `spaps create <name>`
-- `spaps types`
+This does not try to import browser password-manager state. It writes deterministic, repo-local test artifacts instead.
 
-Treat them as reserved surfaces rather than stable workflows.
+If you want a human to launch the frontend and click around without a mock backend, include the generated bridge before your app boots:
 
-## Middleware Example
+```html
+<script src="/spaps-dev-auth.js"></script>
+```
 
-The package exports admin middleware and helper utilities from its main module:
+That bridge does three things:
 
-```javascript
-const express = require('express');
-const { requireAdmin, requirePermission } = require('spaps');
+- 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`
 
-const app = express();
+## Middleware Example
 
-app.get('/admin', requireAdmin(), (_req, res) => {
-  res.json({ ok: true });
-});
+The main module exports admin and permission helpers for Express-style apps.
 
-app.post('/admin/products', requirePermission('manage_products'), (_req, res) => {
-  res.json({ created: true });
-});
+```js
+const express = require("express");
+const { requireAdmin, requirePermission } = require("spaps");
+
+const app = express();
+const customAdmins = ["admin@example.com"];
+
+app.get(
+  "/admin",
+  requireAdmin({ customAdmins }),
+  (_req, res) => {
+    res.json({ ok: true });
+  },
+);
+
+app.post(
+  "/admin/products",
+  requirePermission("manage_products", { customAdmins }),
+  (_req, res) => {
+    res.json({ created: true });
+  },
+);
 ```
 
 ## What `spaps init` Writes
 
-`spaps init` creates a `.env.local` with a local API URL starter and leaves existing files alone if they are already present.
+`spaps init` creates a `.env.local` file with a local API URL starter and leaves an existing file alone if one is already present.
 
 ## Troubleshooting
 
 ### Port already in use
 
-Start on a different port:
+Start on another port:
 
 ```bash
 npx spaps local --port 3400
 ```
 
-### Need machine-readable output
+### 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 supported commands such as `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`.
 
-### Local server is not responding
+### The local server is not responding
 
-Check the current status first:
+Check current status first:
 
 ```bash
 npx spaps status
 ```
 
-Then re-run the server with a clean start if needed:
+If needed, restart with a clean boot:
 
 ```bash
 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 README only documents commands and flags that are currently wired in the CLI dispatcher.
-- `create` and `types` are present as placeholders and should not be treated as finished product surfaces.
-- The package is primarily for local workflows, not full production deployment automation.
+- The CLI is aimed at local workflows. It is not a full deployment or hosting tool.
+- `create` does not run `create-next-app`, Vite, or Express generators for you; it scaffolds the SPAPS integration layer.
+- `types` is still a placeholder today.
+- The middleware ships a legacy default admin configuration in code; public-facing apps should pass explicit `customAdmins` instead of relying on that default.
 
 ## FAQ
 
-### Does this package expose the TypeScript SDK?
+### 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 the separate `spaps-sdk` package.
+No. The SDK is published separately as `spaps-sdk`.
 
-### Can I use the CLI without installing globally?
+### Can I use the CLI without a global install?
 
 Yes. Use `npx spaps ...`.
 
-### Does `spaps init` overwrite my existing env file?
+### Does `spaps init` overwrite an existing env file?
 
 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.
-
-### Is the admin middleware available as an import?
-
-Yes. The package exports the admin helpers from its main module and via the `./middleware` export path.
+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.
 
-## About Contributions
+### Is the middleware available from a subpath?
 
-*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.
+Yes. You can import from the main module or `spaps/middleware`.
 
 ## License
 
-UNLICENSED
+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()