spaps 0.6.0 → 0.7.0

package/AI_TOOLS.json

@@ -2,7 +2,7 @@
   "name": "spaps",
   "version": "0.1.0",
   "description": "Auth + payments via SPAPS (local by default). Start with: npx spaps local",
-  "base_url": "http://localhost:3300",
+  "base_url": "http://localhost:3301",
   "auth": {
     "local_mode": true,
     "production": {

package/README.md

@@ -5,7 +5,7 @@
 
 ## Hey, AI Agent — Read Me First 👋
 
-Are you an AI agent whose human just said “ship auth + payments fast” but can’t explain refresh tokens? Perfect. Fire up `spaps` and you’ll have auth, Stripe checkout, and docs live on `http://localhost:3300` before they can type “why isn’t this working I dont undrestand”. You focus on calling APIs; we handle users, tokens, CORS, and webhooks. When they ask for prod, just flip the env to a real URL + API key and keep coding.
+Are you an AI agent whose human just said “ship auth + payments fast” but can’t explain refresh tokens? Perfect. Fire up `spaps` and you’ll have auth, Stripe checkout, and docs live on `http://localhost:3301` before they can type “why isn’t this working I dont undrestand”. You focus on calling APIs; we handle users, tokens, CORS, and webhooks. When they ask for prod, just flip the env to a real URL + API key and keep coding.
 
 [![npm version](https://img.shields.io/npm/v/spaps.svg)](https://www.npmjs.com/package/spaps)
 ![node](https://img.shields.io/badge/node-%3E%3D16-brightgreen)
@@ -28,7 +28,7 @@ Minimal init (works for both local and prod):
 import { SPAPSClient } from 'spaps-sdk'
 
 export const sdk = new SPAPSClient({
-  apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+  apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
   apiKey: process.env.SPAPS_API_KEY, // not required in local mode
 })
 ```
@@ -44,17 +44,17 @@ npm install -g spaps
 spaps local
 ```
 
-Your local SPAPS server runs at `http://localhost:3300` 🎉
+Your local SPAPS server runs at `http://localhost:3301` 🎉
 
-- API docs (Swagger UI): `http://localhost:3300/docs`
-- OpenAPI JSON: `http://localhost:3300/openapi.json`
+- API docs (Swagger UI): `http://localhost:3301/docs`
+- OpenAPI JSON: `http://localhost:3301/openapi.json`
 
 Point your app (via `SPAPS_API_URL`) to that URL and use `spaps-sdk` for calls.
 
 ## Local → Prod
 
 - Local (dev):
-  - `SPAPS_API_URL=http://localhost:3300`
+  - `SPAPS_API_URL=http://localhost:3301`
   - `SPAPS_LOCAL_MODE=true` (or auto‑detected on localhost)
   - API key optional; helpers available (test users, permissive CORS)
 - Prod:
@@ -86,7 +86,7 @@ Perfect for **rapid prototyping**, **hackathons**, and **local development**.
 Start a full-featured local server with zero configuration:
 
 ```bash
-spaps local                         # Default: http://localhost:3300
+spaps local                         # Default: http://localhost:3301
 spaps local --port 3000             # Custom port
 spaps local --stripe mock|real      # Choose Stripe mode (default: mock)
 spaps local --seed demo             # Seed demo products/customers/orders
@@ -103,7 +103,7 @@ Includes:
 
 Flags:
 
-- `--port <number>`: Set a custom port (default: 3300)
+- `--port <number>`: Set a custom port (default: 3301)
 - `--stripe <mode>`: Stripe mode `mock` (offline, default) or `real` (test API)
 - `--seed <preset>`: Seed local data; supported: `demo`
 - `--open`: Open docs in your browser after start
@@ -159,7 +159,7 @@ npx spaps doctor --json
 OpenAPI JSON:
 
 ```bash
-curl http://localhost:3300/openapi.json | jq '.'
+curl http://localhost:3301/openapi.json | jq '.'
 ```
 ```
 
@@ -175,10 +175,10 @@ Switch between user roles instantly (local server only):
 
 ```bash
 # Prefer header (local‑only)
-curl -H "X-Test-User: premium" "http://localhost:3300/api/auth/user"
+curl -H "X-Test-User: premium" "http://localhost:3301/api/auth/user"
 
 # Or query param (local‑only convenience)
-curl "http://localhost:3300/api/auth/user?_user=admin"
+curl "http://localhost:3301/api/auth/user?_user=admin"
 ```
 
 Available roles: `user`, `admin`, `premium`
@@ -224,7 +224,7 @@ Visit `/admin` for a complete management interface:
 ```javascript
 // React/Next.js example
 const createCheckout = async () => {
-  const response = await fetch('http://localhost:3300/api/stripe/checkout-sessions', {
+  const response = await fetch('http://localhost:3301/api/stripe/checkout-sessions', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
@@ -243,10 +243,10 @@ const createCheckout = async () => {
 
 ```javascript
 // Test as admin user
-fetch('http://localhost:3300/api/auth/user?_user=admin')
+fetch('http://localhost:3301/api/auth/user?_user=admin')
 
 // Test wallet authentication  
-fetch('http://localhost:3300/api/auth/wallet-sign-in', {
+fetch('http://localhost:3301/api/auth/wallet-sign-in', {
   method: 'POST',
   body: JSON.stringify({
     wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
@@ -258,7 +258,7 @@ fetch('http://localhost:3300/api/auth/wallet-sign-in', {
 ## 🏗️ Development Workflow
 
 1. **Start SPAPS**: `npx spaps local`
-2. **Build your frontend** against `http://localhost:3300`
+2. **Build your frontend** against `http://localhost:3301`
 3. **Test payments** using Stripe's test cards
 4. **Monitor webhooks** at `/api/stripe/webhooks/test`
 5. **Manage data** via `/admin` dashboard
@@ -293,7 +293,7 @@ curl -X POST "$SPAPS_API_URL/api/stripe/checkout-sessions" \
 Local (no key, role sim via header):
 
 ```bash
-export SPAPS_API_URL=http://localhost:3300
+export SPAPS_API_URL=http://localhost:3301
 
 curl -X GET "$SPAPS_API_URL/api/auth/user" \
   -H "X-Test-User: admin" \
@@ -355,7 +355,7 @@ Ready to go live? SPAPS supports seamless migration from local to production:
 1. **Export Local Data**:
    ```bash
    # Export your products, orders, and customers
-   curl http://localhost:3300/api/admin/export > spaps-data.json
+   curl http://localhost:3301/api/admin/export > spaps-data.json
    ```
 
 2. **Set Up Production Server**:

package/client.js

@@ -21,7 +21,7 @@ try {
   
   class SPAPSClient {
     constructor(config = {}) {
-      const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || 'http://localhost:3300';
+      const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || 'http://localhost:3301';
       this.isLocalMode = apiUrl.includes('localhost') || apiUrl.includes('127.0.0.1');
       
       this.client = axios.create({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spaps",
-  "version": "0.6.0",
-  "description": "Sweet Potato Authentication & Payment Service CLI - Zero-config local development with built-in admin middleware and permission utilities",
+  "version": "0.7.0",
+  "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": {
     "spaps": "./bin/spaps.js"
@@ -42,14 +42,9 @@
     "axios": "^1.12.2",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
-    "cors": "^2.8.5",
-    "express": "^4.18.2",
     "js-yaml": "^4.1.0",
-    "swagger-ui-dist": "^5.17.14",
     "ora": "^5.4.1",
-    "prompts": "^2.4.2",
-    "stripe": "^18.5.0",
-    "uuid": "^8.3.2"
+    "prompts": "^2.4.2"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/ai-helper.js

@@ -143,7 +143,7 @@ function getServerStatus(port = DEFAULT_PORT) {
   });
 }
 
-async function runQuickTest(port = 3300) {
+async function runQuickTest(port = 3301) {
   const results = [];
   
   // Check server

package/src/cli-dispatcher.js

@@ -45,31 +45,45 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
 
   // spaps local
   const cmdLocal = program
-    .command('local')
-    .description('Start local SPAPS server (no API keys required!)')
-    .option('-p, --port <port>', 'Port to run on', String(DEFAULT_PORT))
-    .option('-s, --stripe <mode>', 'Stripe mode: mock|real', 'mock')
-    .option('--seed <preset>', 'Seed local data: demo', 'none')
+    .command('local [subcommand]')
+    .description('Start local SPAPS server via Docker Compose (subcommand: stop)')
+    .option('-p, --port <port>', 'Port to check (default: 3301)', String(DEFAULT_PORT))
+    .option('-d, --detach', 'Run in background (don\'t tail logs)', false)
+    .option('--fresh', 'Fresh start: tear down and rebuild from scratch', false)
+    .option('--from-backup <path>', 'Load from Supabase backup file', null)
     .option('-o, --open', 'Open browser automatically', false)
     .option('--json', 'Output in JSON format')
     .action(
-      makeAction('local', (opts, cmd, isJson) => {
+      makeAction('local', (subcommandOrOpts, cmdOrOpts, isJsonOrCmd) => {
+        // Handle both 'local' and 'local stop' cases
+        let subcommand = null;
+        let opts = null;
+        let cmd = null;
+        let isJson = false;
+
+        if (typeof subcommandOrOpts === 'string') {
+          // 'local stop' case
+          subcommand = subcommandOrOpts;
+          opts = cmdOrOpts;
+          cmd = isJsonOrCmd;
+          isJson = Boolean(opts.json || (cmd && cmd.parent && cmd.parent.opts().json));
+        } else {
+          // 'local' case (no subcommand)
+          opts = subcommandOrOpts;
+          cmd = cmdOrOpts;
+          isJson = Boolean(opts.json || (cmd && cmd.parent && cmd.parent.opts().json));
+        }
+
         const out = {
-          port: Number(opts.port),
+          port: Number(opts.port) || 3301,
           open: Boolean(opts.open),
+          detach: Boolean(opts.detach),
+          fresh: Boolean(opts.fresh),
+          fromBackup: opts.fromBackup || null,
+          stop: subcommand === 'stop',
           json: isJson,
         };
-        // Include optional flags only if explicitly provided by user
-        try {
-          const srcStripe = typeof cmd.getOptionValueSource === 'function' ? cmd.getOptionValueSource('stripe') : null;
-          const srcSeed = typeof cmd.getOptionValueSource === 'function' ? cmd.getOptionValueSource('seed') : null;
-          if (srcStripe === 'cli') out.stripe = String(opts.stripe || '').toLowerCase();
-          if (srcSeed === 'cli') out.seed = String(opts.seed || '').toLowerCase();
-        } catch (_) {
-          // Commander versions without getOptionValueSource; fall back to only including when present
-          if (typeof opts.stripe !== 'undefined') out.stripe = String(opts.stripe).toLowerCase();
-          if (typeof opts.seed !== 'undefined') out.seed = String(opts.seed).toLowerCase();
-        }
+
         return out;
       })
     );

package/src/config.js

@@ -1,5 +1,5 @@
 // Shared configuration for SPAPS CLI
 module.exports = {
-  DEFAULT_PORT: 3300
+  DEFAULT_PORT: 3301 // Docker Compose dev API external port
 };
 

package/src/docs-html.js

@@ -3,7 +3,7 @@
  * Generates comprehensive documentation page
  */
 
-function generateDocsHTML(port = 3300, notice) {
+function generateDocsHTML(port = 3301, notice) {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>

package/src/docs-system.js

@@ -24,7 +24,7 @@ ${chalk.green('Basic Usage:')}
   
   ${chalk.gray('// Create client (auto-detects local mode)')}
   const sdk = new SweetPotatoSDK({
-    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
     apiKey: process.env.SPAPS_API_KEY,  ${chalk.gray('// Not required in local mode')}
   })
   
@@ -98,16 +98,16 @@ ${chalk.green('Usage Tracking:')}
     content: `
 ${chalk.green('Environment Variables:')}
   ${chalk.gray('# .env or .env.local')}
-  SPAPS_API_URL=http://localhost:3300
+  SPAPS_API_URL=http://localhost:3301
   SPAPS_API_KEY=spaps_live_abc123...
   
   ${chalk.gray('# Next.js (use NEXT_PUBLIC_ prefix)')}
-  NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3300
+  NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3301
   NEXT_PUBLIC_SPAPS_API_KEY=spaps_live_abc123...
 
 ${chalk.green('Configuration Options:')}
   const sdk = new SweetPotatoSDK({
-    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
     apiKey: process.env.SPAPS_API_KEY, ${chalk.gray('// Omit in local dev')}
   })
 
@@ -132,7 +132,7 @@ ${chalk.green('React Context Setup:')}
   import { createContext, useContext } from 'react'
   import { SweetPotatoSDK } from 'spaps-sdk'
   
-  const sdk = new SweetPotatoSDK({ apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3300' })
+  const sdk = new SweetPotatoSDK({ apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301' })
   const SpapsContext = createContext(sdk)
   
   export function SpapsProvider({ children }) {
@@ -447,7 +447,7 @@ ${chalk.green('Interface Examples:')}
 ${chalk.green('Type-Safe Usage:')}
   ${chalk.gray('// Typed client')}
   const spaps: SPAPSClient = new SPAPSClient({
-    apiUrl: 'http://localhost:3300'
+    apiUrl: 'http://localhost:3301'
   })
   
   ${chalk.gray('// Typed responses')}
@@ -486,7 +486,7 @@ ${chalk.green('Unit Testing with Jest:')}
     
     beforeEach(() => {
       spaps = new SPAPSClient({
-        apiUrl: 'http://localhost:3300'
+        apiUrl: 'http://localhost:3301'
       })
     })
     
@@ -600,7 +600,7 @@ ${chalk.green('Health Endpoints:')}
   GET    /health/local-mode         ${chalk.gray('Local mode status')}
 
 ${chalk.green('Local Mode Features:')}
-  ${chalk.gray('In local mode (http://localhost:3300):')}
+  ${chalk.gray('In local mode (http://localhost:3301):')}
   • No API key required
   • Auto-authentication enabled
   • CORS disabled for all origins

package/src/doctor.js

@@ -59,7 +59,7 @@ function checkEnvFile() {
     check: 'env_file',
     success: exists && hasApiUrl,
     details: { path: envPath, exists, hasApiUrl },
-    fix: exists ? (hasApiUrl ? null : 'Add SPAPS_API_URL to .env.local (http://localhost:3300)') : 'Run: npx spaps init'
+    fix: exists ? (hasApiUrl ? null : 'Add SPAPS_API_URL to .env.local (http://localhost:3301)') : 'Run: npx spaps init'
   };
 }
 
@@ -105,7 +105,7 @@ function checkEnvTest() {
       check: 'env_test',
       success: false,
       details: { path: envPath, exists: false },
-      fix: 'Create .env.test with SPAPS_API_URL=http://localhost:3300 (no real network keys)'
+      fix: 'Create .env.test with SPAPS_API_URL=http://localhost:3301 (no real network keys)'
     };
   }
   try {
@@ -190,8 +190,8 @@ async function runDoctor({ port = DEFAULT_PORT, stripe = null, json = false } =
     results.push({
       check: 'spaps_port_vs_next',
       success: false,
-      details: { spaps_port: port, suggestion: 'Use 3300 for SPAPS to avoid Next.js conflicts' },
-      fix: 'Run: npx spaps local --port 3300'
+      details: { spaps_port: port, suggestion: 'Use 3301 for SPAPS to avoid Next.js conflicts' },
+      fix: 'Run: npx spaps local --port 3301'
     });
   } else {
     results.push({ check: 'spaps_port_vs_next', success: true, details: { spaps_port: port }, fix: null });

package/src/error-handler.js

@@ -9,7 +9,7 @@ const ERROR_FIXES = {
   // Port errors
   EADDRINUSE: (error, context = {}) => ({
     title: 'Port Already In Use',
-    description: `Port ${context.port || 3300} is being used by another process`,
+    description: `Port ${context.port || 3301} is being used by another process`,
     causes: [
       'Another SPAPS server is already running',
       'Another application is using this port',
@@ -17,16 +17,16 @@ const ERROR_FIXES = {
     ],
     fixes: [
       {
-        command: `npx spaps local --port ${(parseInt(context.port || 3300) + 1)}`,
+        command: `npx spaps local --port ${(parseInt(context.port || 3301) + 1)}`,
         description: 'Use a different port'
       },
       {
-        command: `lsof -ti:${context.port || 3300} | xargs kill -9`,
+        command: `lsof -ti:${context.port || 3301} | xargs kill -9`,
         description: 'Kill the process using this port (macOS/Linux)',
         platform: ['darwin', 'linux']
       },
       {
-        command: `netstat -ano | findstr :${context.port || 3300}`,
+        command: `netstat -ano | findstr :${context.port || 3301}`,
         description: 'Find process using this port (Windows)',
         platform: ['win32']
       },
@@ -106,7 +106,7 @@ const ERROR_FIXES = {
         description: 'Start the local SPAPS server'
       },
       {
-        command: 'curl http://localhost:3300/health',
+        command: 'curl http://localhost:3301/health',
         description: 'Check if server is responding'
       },
       {
@@ -268,4 +268,4 @@ module.exports = {
     
     process.exit(exitCode);
   }
-};
+};

package/src/handlers.js

@@ -13,33 +13,42 @@ function createHandlers(version, logo) {
     local: async ({ options }) => {
       const isJson = options.json;
       if (!isJson) console.log(logo);
+
+      // Handle stop subcommand
+      if (options.stop) {
+        try {
+          const LocalServer = require('./local-server.js');
+          const server = new LocalServer({ json: isJson });
+          server.stop();
+          return;
+        } catch (error) {
+          handleError(error, { command: 'local stop' }, { json: isJson });
+        }
+      }
+
+      // Handle start
       try {
         const LocalServer = require('./local-server.js');
-        const server = new LocalServer({ port: options.port, json: isJson, stripeMode: options.stripe, seedMode: options.seed });
-        if (isJson) {
-          await server.start();
-          console.log(JSON.stringify({
-            success: true,
-            command: 'local',
-            server: {
-              url: `http://localhost:${options.port}`,
-              docs: `http://localhost:${options.port}/docs`,
-              mode: 'local-development',
-              port: Number(options.port),
-              features: { autoAuth: true, corsEnabled: true, testUsers: ['user', 'admin', 'premium'], apiKeyRequired: false, stripeMode: options.stripe, seeded: options.seed }
-            }
-          }));
-        } else {
-          await server.start();
-          if (options.open) {
-            const { exec } = require('child_process');
-            const url = `http://localhost:${options.port}/docs`;
-            const start = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-            exec(`${start} ${url}`);
-          }
+        const server = new LocalServer({
+          port: options.port,
+          json: isJson,
+          detach: options.detach,
+          fresh: options.fresh,
+          fromBackup: options.fromBackup
+        });
+
+        await server.start();
+
+        if (options.open && !isJson) {
+          const { exec } = require('child_process');
+          const url = `http://localhost:${options.port}/docs`;
+          const start = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          exec(`${start} ${url}`);
         }
-        process.on('SIGINT', () => {
-          if (!isJson) console.log(chalk.yellow('\n👋 Shutting down SPAPS local server...'));
+
+        // Set up shutdown handler
+        process.on('SIGINT', async () => {
+          await server.shutdown();
           process.exit(0);
         });
       } catch (error) {

package/src/help-system.js

@@ -182,10 +182,10 @@ const HELP_TREE = {
         solution: {
           commands: [
             'npx spaps local --port 3301',
-            'lsof -ti:3300 | xargs kill -9',
+            'lsof -ti:3301 | xargs kill -9',
             'npx spaps local --port 0'
           ],
-          explanation: 'Another process is using port 3300. Either use a different port or kill the existing process.'
+          explanation: 'Another process is using port 3301. Either use a different port or kill the existing process.'
         }
       },
       {
@@ -216,8 +216,8 @@ const HELP_TREE = {
         value: 'auth-error',
         solution: {
           commands: [
-            'curl http://localhost:3300/health',
-            'npx spaps local --port 3300'
+            'curl http://localhost:3301/health',
+            'npx spaps local --port 3301'
           ],
           explanation: 'In local mode, authentication is automatic. Make sure the local server is running.'
         }
@@ -251,7 +251,7 @@ In local mode, everything is mocked so you can develop without:
         title: 'Local vs Production',
         value: 'environments',
         content: `
-**Local Mode** (http://localhost:3300):
+**Local Mode** (http://localhost:3301):
 - No API key required
 - Auto-authentication
 - Mocked responses
@@ -473,7 +473,7 @@ function showQuickHelp() {
   console.log();
   
   console.log(chalk.green('Debugging:'));
-  console.log('  curl http://localhost:3300/health   ' + chalk.gray('# Check server'));
+  console.log('  curl http://localhost:3301/health   ' + chalk.gray('# Check server'));
   console.log('  npx spaps help --interactive         ' + chalk.gray('# Interactive help'));
   console.log();