spaps 0.7.6 → 0.7.7

package/README.md

@@ -4,6 +4,8 @@ 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.
 
+Run `spaps` with no arguments to get the current operator session, app context, runtime mode, and the next recommended command.
+
 ## TL;DR
 
 ### The problem
@@ -28,6 +30,7 @@ Run SPAPS locally, inspect the current auth mode, then either use local mode dir
 ## No Backend Yet? Start Here
 
 ```bash
+npx spaps
 npx spaps local
 npx spaps quickstart --json | jq '.auth'
 SELF_SERVICE_PASSWORD=your-password npx spaps create demo-app --template react
@@ -74,7 +77,7 @@ Restore order is always: restore base dump first, then let the API container run
 Run it without installing:
 
 ```bash
-npx spaps help
+npx spaps
 ```
 
 Install globally:
@@ -93,49 +96,94 @@ npm install spaps
 
 | 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 |
+| 1 | `npx spaps` | Inspect operator session, detected app context, runtime mode, and the next command |
+| 2 | `npx spaps local` | Start the local SPAPS stack when the runtime is not up yet |
+| 2b | `npx spaps local --data-source prod-cache` | Start the local stack with a cached prod-backed base DB |
+| 3 | `npx spaps connect` | Authenticate the CLI with the active SPAPS server |
+| 4 | `npx spaps verify --json` | Confirm the runtime and auth path end to end |
+| 5 | `npx spaps create my-app --template react` | Scaffold a starter and, when possible, provision a real local app |
+| 6 | `npx spaps tools --json` | Export the current AI tool contract for agents or tests |
+| 7 | `npx spaps fixtures apply` | Materialize repo-local personas into Playwright/browser artifacts |
 
 ## CLI Surface
 
 | Command | Purpose | Common flags |
 | --- | --- | --- |
+| `spaps` / `spaps home` | Show operator session, app context, runtime mode, and the next recommended action | `--port`, `--server-url`, `--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 verify` | Run a compact runtime and auth verification pass | `--port`, `--server-url`, `--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 fixtures <subcommand>` | Manage repo-local `.spaps` auth fixtures | `--dir`, `--port`, `--base-url`, `--persona`, `--seed`, `--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` |
+| `spaps tools` | Emit the AI tool spec (covers auth, stripe, dayrate, email, webhooks, policies, issue-reporting) | `--port`, `--format`, `--json` |
+| `spaps doctor` | Diagnose local environment problems and probe that every domain router is mounted | `--port`, `--stripe`, `--json` |
+| `spaps dayrate config` | Fetch the active dayrate admin config (requires admin JWT) | `--server-url`, `--port`, `--json` |
+| `spaps email <verb>` | Thin email control-plane commands over the existing SPAPS email API | `--server-url`, `--port`, `--json`; run `spaps email --help` for verb-specific flags |
+| `spaps policy list\|create\|delete` | List, create, or delete authorization policies (admin) | `--name`, `--effect`, `--conditions`, `--id`, `--is-active`, `--limit`, `--json` |
+| `spaps webhook list\|register` | List registered webhooks or register a new outbound webhook | `--url`, `--events`, `--json` |
+| `spaps issue-reports list-mine` | List issue reports created by the authenticated caller | `--status`, `--limit`, `--offset`, `--json` |
+
+### Email Commands
+
+Use nested help for the exact flag surface:
+
+```bash
+spaps email --help
+spaps email send --help
+spaps email preview --help
+```
+
+| Verb | Auth | Purpose |
+| --- | --- | --- |
+| `send` | API key | Send a transactional email by template key |
+| `get-template` | API key + JWT | Fetch one template definition |
+| `preview` | API key + JWT | Render a preview with sample or custom context |
+| `logs` | API key + JWT | List email logs for the caller's scope |
+| `list-templates` | API key + JWT + admin | List all templates for the application |
+| `create-template` | API key + JWT + admin | Create a template |
+| `update-template` | API key + JWT + admin | Update a template |
+| `get-override` | API key + JWT | Read the current template override |
+| `set-override` | API key + JWT + admin | Create or update an override |
+| `clear-override` | API key + JWT + admin | Delete an override |
 
 Example command usage:
 
 ```bash
+spaps --json
 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 verify --json
 spaps create my-app --template react
-spaps login --json
+spaps connect --json
 spaps fixtures apply --base-url http://localhost:5173
+spaps fixtures apply --seed --persona dayrate-entitled --base-url http://localhost:5173
 spaps fixtures storage-state --persona admin
 spaps docs --search secure-messages
 spaps doctor --stripe mock
 spaps local stop
+spaps dayrate config --json
+spaps email --help
+spaps email send --help
+spaps email send --template-key welcome --to user@example.com --context '{"user_name":"Jane"}' --json
+spaps email preview --template-key welcome
+spaps email logs --owner-id owner-123 --limit 25 --json
+spaps email set-override --template-key welcome --subject-override "New subject" --json
+spaps policy list --json
+spaps policy create --name allow_admin --effect allow --conditions '{"role":"admin"}' --json
+spaps webhook register --url https://example.com/hook --events user.created,user.deleted --json
+spaps issue-reports list-mine --status open --json
 ```
 
 ## CLI Auth
 
-`spaps login` uses the active FastAPI device-flow contract:
+`spaps connect` is an alias for `spaps login`, and both use the active FastAPI device-flow contract:
 
 - device authorization at `/api/cli/device/*`
 - authenticated follow-up calls at `/api/auth/*`
@@ -160,6 +208,7 @@ Authenticated follow-up calls such as `whoami`, `logout`, and token refresh stil
 Examples:
 
 ```bash
+npx spaps connect --client-id my-app
 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
@@ -217,9 +266,12 @@ Then run:
 
 ```bash
 npx spaps fixtures apply --base-url http://localhost:5173
+npx spaps fixtures apply --seed --persona issue-reporter-blocked --base-url http://localhost:5173
 npx spaps fixtures storage-state --persona admin
 ```
 
+Use `--seed` when a persona declares backend seed steps in `.spaps/users.json`. Seeding is opt-in, only runs against a reachable local-mode SPAPS server, and reuses the persona selectors already defined in the fixture kernel instead of adding fixture-only backend routes.
+
 What `apply` emits:
 
 - `browser/<persona>.storage-state.json` for Playwright `storageState`

package/assets/local-runtime/Dockerfile

@@ -14,6 +14,19 @@ RUN apt-get update && \
 
 ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.0
 RUN pip install --no-cache-dir "spaps-server-quickstart==${SPAPS_SERVER_QUICKSTART_VERSION}"
+RUN python - <<'PY'
+from pathlib import Path
+
+from spaps_server_quickstart.domains.auth import schemas
+
+schema_path = Path(schemas.__file__)
+text = schema_path.read_text(encoding="utf-8")
+text = text.replace(
+    "    refresh_token: str\n",
+    "    refresh_token: str | None = None\n",
+)
+schema_path.write_text(text, encoding="utf-8")
+PY
 
 COPY alembic.ini /app/alembic.ini
 COPY alembic/ /app/alembic/

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

@@ -20,7 +20,8 @@ services:
       LOG_LEVEL: DEBUG
       LOG_FORMAT: console
       AUTH_BASE_URL: "${SPAPS_AUTH_BASE_URL:-http://localhost:5173}"
-      CORS_ALLOW_ORIGINS: "${CORS_ALLOW_ORIGINS:-*}"
+      CORS_ALLOW_ORIGINS: "${CORS_ALLOW_ORIGINS:-http://localhost:3000,http://127.0.0.1:3000,http://localhost:3001,http://127.0.0.1:3001,http://localhost:5173,http://127.0.0.1:5173,http://localhost:30000,http://127.0.0.1:30000}"
+      CORS_ALLOW_HEADERS: "${CORS_ALLOW_HEADERS:-Accept,Accept-Language,Authorization,Content-Language,Content-Type,X-API-Key,X-Request-ID,X-SPAPS-Signature,X-SPAPS-Use-Refresh-Cookie,X-Test-User}"
       LEGACY_API_KEY_AUTH_ENABLED: "${LEGACY_API_KEY_AUTH_ENABLED:-true}"
     depends_on:
       spaps-dev-db:

package/assets/local-runtime/manifest.json

@@ -3,6 +3,8 @@
   "portable_runtime": {
     "default_local_mode": true,
     "default_auth_base_url": "http://localhost:5173",
-    "default_self_service_password": "spaps_local_self_service_password"
+    "default_self_service_password": "spaps_local_self_service_password",
+    "default_cors_allow_origins": "http://localhost:3000,http://127.0.0.1:3000,http://localhost:3001,http://127.0.0.1:3001,http://localhost:5173,http://127.0.0.1:5173,http://localhost:30000,http://127.0.0.1:30000",
+    "default_cors_allow_headers": "Accept,Accept-Language,Authorization,Content-Language,Content-Type,X-API-Key,X-Request-ID,X-SPAPS-Signature,X-SPAPS-Use-Refresh-Cookie,X-Test-User"
   }
 }

package/bin/spaps.js

@@ -5,7 +5,6 @@
  */
 
 const chalk = require('chalk');
-const fs = require('fs');
 const { buildProgram } = require('../src/cli-dispatcher');
 const { createHandlers } = require('../src/handlers');
 
@@ -18,13 +17,40 @@ ${chalk.yellow('🍠 SPAPS')} - Sweet Potato Authentication & Payment Service
 
 const handlers = createHandlers(version, logo);
 const program = buildProgram({ handlers, dryRun: false, version, logo });
+const argv = process.argv.slice(2);
 
-// Show help if no command provided
-if (!process.argv.slice(2).length) {
-  console.log(logo);
-  program.outputHelp();
-  console.log();
-  console.log(chalk.yellow('💡 Try: npx spaps help --interactive'));
+function shouldRouteToHome(args) {
+  if (!args.length) {
+    return true;
+  }
+
+  const flagsWithValues = new Set(['-p', '--port', '--server-url']);
+  const bareFlags = new Set(['--json']);
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V') {
+      return false;
+    }
+
+    if (bareFlags.has(arg)) {
+      continue;
+    }
+
+    if (flagsWithValues.has(arg)) {
+      index += 1;
+      continue;
+    }
+
+    return false;
+  }
+
+  return true;
 }
 
-program.parse(process.argv);
+if (shouldRouteToHome(argv)) {
+  program.parse([process.argv[0], process.argv[1], 'home', ...argv]);
+} else {
+  program.parse(process.argv);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "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": {
@@ -39,11 +39,10 @@
   },
   "homepage": "https://www.buildooor.com/services",
   "dependencies": {
-    "axios": "^1.12.2",
+    "axios": "^1.15.1",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
-    "js-yaml": "^4.1.0",
-    "ora": "^5.4.1",
+    "js-yaml": "^4.1.1",
     "prompts": "^2.4.2"
   },
   "engines": {

package/src/ai-helper.js

@@ -1,5 +1,35 @@
 const { DEFAULT_PORT } = require('./config');
 const { getServerRuntime, readSelfServicePassword } = require('./local-runtime');
+const { resolveAuthApiKey } = require('./auth/api-key');
+
+function normalizeRuntimeArgs(input = DEFAULT_PORT) {
+  if (typeof input === 'number') {
+    return {
+      port: input,
+      serverUrl: null,
+      cwd: process.cwd(),
+    };
+  }
+
+  if (input && typeof input === 'object') {
+    return {
+      port: Number(input.port) || DEFAULT_PORT,
+      serverUrl: input.serverUrl || resolveEnvServerUrl(),
+      cwd: input.cwd || process.cwd(),
+    };
+  }
+
+  return {
+    port: DEFAULT_PORT,
+    serverUrl: null,
+    cwd: process.cwd(),
+  };
+}
+
+function resolveEnvServerUrl() {
+  const raw = String(process.env.SPAPS_API_URL || '').trim();
+  return raw ? raw : null;
+}
 
 function buildProvisioningCommand(template, port) {
   return `SELF_SERVICE_PASSWORD=your-password npx spaps create demo-${template === 'node' ? 'api' : 'app'} --template ${template} --port ${port}`;
@@ -127,8 +157,9 @@ main().catch(console.error);
   };
 }
 
-async function getQuickStartInstructions(port = DEFAULT_PORT) {
-  const runtime = await getServerRuntime({ port });
+async function getQuickStartInstructions(input = DEFAULT_PORT) {
+  const { port, serverUrl } = normalizeRuntimeArgs(input);
+  const runtime = await getServerRuntime({ port, serverUrl });
 
   if (!runtime.running) {
     return {
@@ -154,12 +185,14 @@ async function getQuickStartInstructions(port = DEFAULT_PORT) {
   return buildProvisionedModeInstructions(runtime, port);
 }
 
-async function getServerStatus(port = DEFAULT_PORT) {
-  return getServerRuntime({ port });
+async function getServerStatus(input = DEFAULT_PORT) {
+  const { port, serverUrl } = normalizeRuntimeArgs(input);
+  return getServerRuntime({ port, serverUrl });
 }
 
-async function runQuickTest(port = DEFAULT_PORT) {
-  const runtime = await getServerRuntime({ port });
+async function runQuickTest(input = DEFAULT_PORT) {
+  const { port, serverUrl, cwd } = normalizeRuntimeArgs(input);
+  const runtime = await getServerRuntime({ port, serverUrl });
   const results = [
     {
       test: 'server_status',
@@ -173,7 +206,7 @@ async function runQuickTest(port = DEFAULT_PORT) {
       success: false,
       summary: '0/1 tests passed',
       results,
-      next_steps: [`Start the server with: npx spaps local --port ${port}`],
+      next_steps: [runtime.start_command || `Check the server at ${runtime.url} and rerun spaps verify.`],
     };
   }
 
@@ -185,12 +218,13 @@ async function runQuickTest(port = DEFAULT_PORT) {
   });
 
   if (!runtime.local_mode.active) {
-    const hasKey = Boolean(process.env.SPAPS_API_KEY);
+    const apiKey = resolveAuthApiKey({ cwd });
+    const hasKey = Boolean(apiKey.apiKey);
     results.push({
       test: 'api_key_wiring',
       success: hasKey,
       message: hasKey
-        ? 'SPAPS_API_KEY is set for non-local-mode testing'
+        ? `API key is configured via ${apiKey.source}`
         : 'SPAPS_API_KEY is required when local mode is disabled',
       fix: hasKey ? null : buildProvisioningCommand('node', port),
     });
@@ -204,7 +238,7 @@ async function runQuickTest(port = DEFAULT_PORT) {
     results,
     next_steps: allSuccess
       ? [`See docs at ${runtime.docs}`]
-      : ['Fix the failing checks above and re-run: npx spaps test --json'],
+      : ['Fix the failing checks above and re-run: spaps verify --json'],
   };
 }
 

package/src/ai-tool-spec.js

@@ -8,6 +8,7 @@ const { DEFAULT_PORT } = require('./config');
 const fs = require('fs');
 const path = require('path');
 const { getServerRuntime } = require('./local-runtime');
+const { buildDomainTools } = require('./domains');
 
 function tryLoadManifest() {
   const candidates = [
@@ -74,7 +75,7 @@ function buildAuthSection(runtime) {
   };
 }
 
-async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0' } = {}) {
+async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', include_non_agent = false } = {}) {
   const baseUrl = `http://localhost:${port}`;
   const runtime = await getServerRuntime({ port });
   const auth = buildAuthSection(runtime);
@@ -190,6 +191,14 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0' } =
     ]
   };
 
+  // Merge domain registry tools (dayrate, email, webhooks, policies, issue_reporting).
+  // Admin routes carry admin_required:true; non-agent routes (e.g. mailgun inbound)
+  // are excluded unless include_non_agent is set.
+  const domainTools = buildDomainTools({ includeNonAgent: include_non_agent });
+  for (const dt of domainTools) {
+    spec.tools.push(dt);
+  }
+
   // Default error shapes used for enrichment/merging
   const defaultErrors = {
     '400': {
@@ -305,7 +314,13 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0' } =
       setResponses('list_products', 'GET', '/api/stripe/products');
       setResponses('request_magic_link', 'POST', '/api/auth/magic-link');
       setResponses('get_wallet_nonce', 'POST', '/api/auth/nonce');
-      // For GET endpoints with query/headers, leave minimal schema for simplicity
+      // Enrich every domain-registry tool opportunistically. Skips silently
+      // if the operation isn\u2019t in the OpenAPI doc.
+      for (const t of spec.tools) {
+        if (!t.domain) continue;
+        setBodySchema(t.name, t.method, t.path);
+        setResponses(t.name, t.method, t.path);
+      }
     }
   } catch {
     // Ignore enrichment errors
@@ -319,11 +334,11 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0' } =
   return spec;
 }
 
-async function buildToolSpec({ format = 'openai', port = DEFAULT_PORT, version = '0.0.0' } = {}) {
+async function buildToolSpec({ format = 'openai', port = DEFAULT_PORT, version = '0.0.0', include_non_agent = false } = {}) {
   switch (format) {
     case 'openai':
     default:
-      return buildOpenAIToolSpec({ port, version });
+      return buildOpenAIToolSpec({ port, version, include_non_agent });
   }
 }