spaps 0.7.1 → 0.7.3

package/README.md

@@ -1,438 +1,200 @@
-# 🍠 SPAPS CLI
+# spaps
 
-> Sweet Potato Authentication & Payment Service CLI  
-> Zero‑config local development server with real Stripe integration
+CLI and middleware package for local SPAPS workflows.
 
-## Hey, AI Agent — Read Me First 👋
+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.
 
-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.
+## Install
 
-[![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)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## SDK vs CLI
-
-- CLI (`spaps`): runs the local SPAPS server and tooling for development. No API key required, helpers enabled.
-- SDK (`spaps-sdk`): TypeScript client for your app code. Points at the same base URL and works in local and prod.
-
-Install the SDK in your app to call the API programmatically:
+Run it without installing:
 
 ```bash
-npm install spaps-sdk
-```
-
-Minimal init (works for both local and prod):
-
-```ts
-import { SPAPSClient } from 'spaps-sdk'
-
-export const sdk = new SPAPSClient({
-  apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
-  apiKey: process.env.SPAPS_API_KEY, // not required in local mode
-})
+npx spaps help
 ```
 
-## 🚀 Quick Start
+Install globally:
 
 ```bash
-# Run immediately with npx (recommended)
-npx spaps local
-
-# Or install globally
 npm install -g spaps
-spaps local
 ```
 
-Your local SPAPS server runs at `http://localhost:3301` 🎉
-
-- 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:3301`
-  - `SPAPS_LOCAL_MODE=true` (or auto‑detected on localhost)
-  - API key optional; helpers available (test users, permissive CORS)
-- Prod:
-  - `SPAPS_API_URL=https://api.yourdomain`
-  - `SPAPS_API_KEY=spaps_…` required
-  - Local helpers disabled; CORS and rate limits enforced
-
-Headers policy:
-- Local: may send `x-local-mode: true`; role sim via `X-Test-User: admin` (local‑only)
-- Prod: must send `X-API-Key: $SPAPS_API_KEY`; do NOT use local‑only headers
-
-## ✨ What is SPAPS?
-
-SPAPS provides a **complete authentication and payment backend** for your applications:
-
-- 🔐 **Multi-wallet auth** (Solana, Ethereum, Bitcoin, Base)
-- 📧 **Traditional auth** (email/password, magic links) 
-- 💳 **Real Stripe integration** (products, checkout, webhooks)
-- 🎭 **Test user switching** (`?_user=admin`)
-- 📊 **Admin dashboard** with analytics
-- 🌐 **CORS-ready** for any frontend
-
-Perfect for **rapid prototyping**, **hackathons**, and **local development**.
-
-## 📋 Commands
-
-### `spaps local` - Development Server
-
-Start a full-featured local server with zero configuration:
+Add it to a project:
 
 ```bash
-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
-spaps local --json                  # JSON output (CI-friendly)
+npm install spaps
 ```
 
-Includes:
-- ✅ Auto-authentication (no API keys needed)
-- ✅ Real Stripe test mode integration
-- ✅ Mock payment flows with webhooks
-- ✅ Admin dashboard at `/admin`
-- ✅ API documentation at `/docs`
-- ✅ Test user switching via headers/query params
-
-Flags:
+This package targets `Node.js >=22`.
 
-- `--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
-- `--json`: JSON machine-readable output (ideal for CI)
+## When It Fits
 
-### `spaps init` - Project Setup
+| 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 |
 
-Initialize SPAPS in an existing project:
+## Quick Start
 
 ```bash
-spaps init
-# ✅ Creates .env.local with Stripe test keys
-# ✅ Adds SPAPS client to your package.json
-# ✅ Generates basic integration examples
-```
+# Start the local server
+npx spaps local
 
-### `spaps status` - Health Check
+# Confirm it is healthy
+npx spaps status
 
-Check your local server and Stripe connection:
+# Create a starter .env.local in the current project
+npx spaps init
 
-```bash
-spaps status
-# Shows server status, Stripe connectivity, product sync status
+# Emit the local tool spec as JSON
+npx spaps tools --json
 ```
 
-### Other Commands
-
-- `spaps help` — Quick help; `spaps help --interactive` for guided setup
-- `spaps docs` — SDK docs; `spaps docs --interactive` or `--search "query"`
-- `spaps quickstart` — Minimal SDK usage instructions
-- `spaps tools` — Output AI tool spec (use `--json` to save)
-- `spaps doctor` — Diagnose local environment and config
+## CLI Surface
 
-### JSON Mode (CI)
+| Command | Purpose | Common flags |
+| --- | --- | --- |
+| `spaps local [stop]` | Start or stop the local server workflow | `--port`, `--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 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` |
 
-All commands that support `--json` will print machine-readable output. Example:
+Example command usage:
 
 ```bash
-npx spaps local --port 0 --json | jq '.'
+spaps local --port 3400 --detach
+spaps status --json
+spaps create my-app --template react
+spaps docs --search secure-messages
+spaps doctor --stripe mock
+spaps local stop
 ```
 
-AI tool spec (OpenAI-style):
+Still reserved and not finished:
 
-```bash
-npx spaps tools --json > spaps-tools.json
-```
+- `spaps types`
 
-Run diagnostics:
-
-```bash
-npx spaps doctor --json
+## Create A Starter Project
 
-OpenAPI JSON:
+`spaps create` ships a local-first starter kit rather than a full framework generator. It creates a new directory with:
 
-```bash
-curl http://localhost:3301/openapi.json | jq '.'
-```
-```
+- `spaps.app.json` for the machine-readable SPAPS app contract
+- `.env.local` pointing at local SPAPS
+- `package.json` with `spaps-sdk`
+- a small template-specific integration starter
 
-## 🎯 Key Features
+Supported templates:
 
-### 🔧 **Zero Configuration**
-- No setup required - works out of the box
-- Real Stripe test keys included
-- Automatic CORS for any frontend
+- `nextjs`
+- `react`
+- `node`
+- `vanilla`
 
-### 🎭 Smart Test Users (local‑only)
-Switch between user roles instantly (local server only):
+Example:
 
 ```bash
-# Prefer header (local‑only)
-curl -H "X-Test-User: premium" "http://localhost:3301/api/auth/user"
-
-# Or query param (local‑only convenience)
-curl "http://localhost:3301/api/auth/user?_user=admin"
+npx spaps create my-app --template react
+npx spaps create my-api --template node --dir ./services/my-api
 ```
 
-Available roles: `user`, `admin`, `premium`
-
-### 💳 Real Stripe Integration
-- **Real API calls** to Stripe test mode
-- Create actual checkout sessions
-- Receive real webhooks
-- Sync products to/from Stripe
-- Full webhook testing UI at `/api/stripe/webhooks/test`
-
-### 📊 **Admin Dashboard**
-Visit `/admin` for a complete management interface:
-- Revenue analytics
-- Product management
-- Order tracking
-- Data export/import
-- Real-time webhook monitoring
-
-## 🔌 API Endpoints
-
-| Endpoint | Method | SDK Mapping | Description |
-|----------|--------|-------------|-------------|
-| `/api/auth/login` | POST | `sdk.auth.signInWithPassword` | Email/password authentication |
-| `/api/auth/register` | POST | `sdk.auth.register` | Register new user |
-| `/api/auth/user` | GET | `sdk.auth.getCurrentUser` | Current authenticated user |
-| `/api/auth/wallet-sign-in` | POST | `sdk.auth.signInWithWallet` / `sdk.auth.authenticateWallet` | Wallet signature authentication |
-| `/api/auth/refresh` | POST | `sdk.auth.refreshToken` | Refresh access token |
-| `/api/auth/logout` | POST | `sdk.auth.logout` | Log out |
-| `/api/stripe/products` | GET | `sdk.payments.listProducts` | List Stripe products |
-| `/api/stripe/products/:id` | GET | `sdk.payments.getProduct` | Get product (+prices) |
-| `/api/stripe/prices` | POST | `sdk.payments.createPrice` | Create price (admin) |
-| `/api/stripe/checkout-sessions` | POST | `sdk.payments.createCheckoutSession` | Create checkout session |
-| `/api/stripe/checkout-sessions/:id` | GET | `sdk.payments.getCheckoutSession` | Retrieve checkout session |
-| `/api/stripe/webhooks` | POST | — | Stripe webhook receiver |
-| `/health` | GET | `sdk.healthCheck` | Server health check |
-| `/docs` | GET | — | Interactive API documentation |
-
-## 💡 Usage Examples
-
-### Frontend Integration
-
-```javascript
-// React/Next.js example
-const createCheckout = async () => {
-  const response = await fetch('http://localhost:3301/api/stripe/checkout-sessions', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      price_id: 'price_1234567890',
-      success_url: 'http://localhost:3000/success',
-      cancel_url: 'http://localhost:3000/cancel'
-    })
-  });
-  
-  const { data } = await response.json();
-  window.location.href = data.url; // Redirect to Stripe Checkout
-};
-```
+## Middleware Example
 
-### Test Different User Roles (local‑only)
+The main module exports admin and permission helpers for Express-style apps.
 
-```javascript
-// Test as admin user
-fetch('http://localhost:3301/api/auth/user?_user=admin')
+```js
+const express = require("express");
+const { requireAdmin, requirePermission } = require("spaps");
 
-// Test wallet authentication  
-fetch('http://localhost:3301/api/auth/wallet-sign-in', {
-  method: 'POST',
-  body: JSON.stringify({
-    wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
-    chain_type: 'bitcoin'
-  })
-});
-```
+const app = express();
+const customAdmins = ["admin@example.com"];
 
-## 🏗️ Development Workflow
+app.get(
+  "/admin",
+  requireAdmin({ customAdmins }),
+  (_req, res) => {
+    res.json({ ok: true });
+  },
+);
 
-1. **Start SPAPS**: `npx spaps local`
-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
-6. **Export data** when ready for production
+app.post(
+  "/admin/products",
+  requirePermission("manage_products", { customAdmins }),
+  (_req, res) => {
+    res.json({ created: true });
+  },
+);
+```
 
-## 🔒 Environment & Security
+## What `spaps init` Writes
 
-Local mode safety:
-- Only runs on localhost
-- Uses Stripe test keys by default
-- All data stored locally in `.spaps/` directory
-- Responses include local‑mode headers/metadata for visibility
+`spaps init` creates a `.env.local` file with a local API URL starter and leaves an existing file alone if one is already present.
 
-## Curl Examples (Header‑First)
+## Troubleshooting
 
-Authenticated (prod/staging):
+### Port already in use
 
-```bash
-export SPAPS_API_URL=https://api.yourdomain
-export SPAPS_API_KEY=spaps_XXXXXXXXXXXXXXXX
-
-curl -X POST "$SPAPS_API_URL/api/stripe/checkout-sessions" \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: $SPAPS_API_KEY" \
-  -d '{
-    "price_id": "price_1234567890",
-    "success_url": "https://yourapp/success",
-    "cancel_url": "https://yourapp/cancel"
-  }'
-```
-
-Local (no key, role sim via header):
+Start on another port:
 
 ```bash
-export SPAPS_API_URL=http://localhost:3301
-
-curl -X GET "$SPAPS_API_URL/api/auth/user" \
-  -H "X-Test-User: admin" \
-  -H "x-local-mode: true"
+npx spaps local --port 3400
 ```
 
-Note: `X-Test-User` and `x-local-mode` are ignored in production.
+### I need machine-readable output
 
- 
+Use `--json` on commands that support it, including `local`, `status`, `quickstart`, `init`, `docs`, `tools`, and `doctor`.
 
-**Stripe Configuration:**
-- Real Stripe test API integration
-- Webhook signature verification
-- Product/price synchronization
-- Customer portal simulation
+### The local server is not responding
 
-## 📦 Installation Options
+Check current status first:
 
 ```bash
-# Use immediately (recommended)
-npx spaps local
+npx spaps status
+```
 
-# Install globally
-npm install -g spaps
+If needed, restart with a clean boot:
 
-# Add to project dependencies
-npm install --save-dev spaps
+```bash
+npx spaps local --fresh
 ```
 
-## 🎓 Next Steps
+## Limitations
 
-- 📖 **Full Documentation**: [sweetpotato.dev](https://sweetpotato.dev)
-- 🔧 **Production Setup**: See deployment guides
-- 💬 **Get Help**: [GitHub Issues](https://github.com/buildooor/sweet-potato/issues)
-- 🚀 **Examples**: Check `/examples` directory
+- 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.
 
-## 🤝 Pair with the SDK
+## FAQ
 
-Use the SDK in your app while running the local server:
+### Does this package include the TypeScript SDK?
 
-```bash
-npm install spaps-sdk
-```
+No. The SDK is published separately as `spaps-sdk`.
 
-```ts
-import { SPAPSClient } from 'spaps-sdk';
+### Can I use the CLI without a global install?
 
-const spaps = new SPAPSClient(); // auto-detects local mode
-const { data } = await spaps.login('user@example.com', 'password');
-console.log('User:', data.user);
-```
+Yes. Use `npx spaps ...`.
 
-## 🚀 Production Deployment
-
-Ready to go live? SPAPS supports seamless migration from local to production:
-
-### Local → Production Workflow
-
-1. **Export Local Data**:
-   ```bash
-   # Export your products, orders, and customers
-   curl http://localhost:3301/api/admin/export > spaps-data.json
-   ```
-
-2. **Set Up Production Server**:
-   ```bash
-   # Deploy to your server (DigitalOcean, AWS, etc.)
-   # Example production server: http://104.131.188.214:3000
-   git clone https://github.com/build000r/sweet-potato
-   cd sweet-potato
-   npm install
-   ```
-
-3. **Configure Environment**:
-   ```bash
-   # Set production environment variables
-   SUPABASE_URL=https://your-project.supabase.co
-   SUPABASE_SERVICE_KEY=eyJhb...your-service-key
-   STRIPE_SECRET_KEY=<STRIPE_SECRET_KEY> # Your live Stripe key
-   JWT_SECRET=your-32-char-secure-secret
-   ```
-
-4. **Sync Products to Production Stripe**:
-   ```bash
-   # Import your local products to production Stripe
-   curl -X POST http://104.131.188.214:3000/api/v1/admin/products/sync \
-        -H "Content-Type: application/json" \
-        -d @spaps-data.json
-   ```
-
-5. **Update Frontend Config**:
-   ```javascript
-   // Change from local to production endpoint
-   const SPAPS_URL = 'http://104.131.188.214:3000'; // Your production server
-   ```
-
-### Production Features
-
-The production SPAPS server includes:
-- ✅ **Real Supabase integration** with RLS policies
-- ✅ **Live Stripe webhooks** with signature verification
-- ✅ **Multi-wallet authentication** (Solana, Ethereum, Base, Bitcoin)
-- ✅ **JWT authentication** with refresh tokens
-- ✅ **Rate limiting** and security middleware
-- ✅ **Usage tracking** and analytics
-- ✅ **Multi-tenant support** for multiple client apps
-
-### Health Check
-
-Check if your production server is running:
-```bash
-curl http://104.131.188.214:3000/health
-# Returns: {"status":"healthy","mode":"production"}
-```
+### Does `spaps init` overwrite an existing env file?
 
----
+No. It skips `.env.local` if the file already exists.
 
-## 🔒 New in v0.5.0: Admin Middleware & Permissions!
+### What does `spaps tools` output?
 
-Built-in admin middleware and permission utilities for secure Express.js applications:
+An OpenAI-style tool spec for the local SPAPS surface.
 
-```javascript
-const { requireAdmin, isAdminAccount } = require('spaps');
+### Is the middleware available from a subpath?
 
-// Protect admin routes
-app.get('/admin/dashboard', requireAdmin(), (req, res) => {
-  res.json({ message: 'Admin only!' });
-});
+Yes. You can import from the main module or `spaps/middleware`.
 
-// Check admin status
-if (isAdminAccount('buildooor@gmail.com')) {
-  // Grant admin access
-}
-```
+## About Contributions
 
-See [ADMIN_MIDDLEWARE.md](./ADMIN_MIDDLEWARE.md) for complete documentation.
+> *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
 
-**Current Version**: v0.5.0  
-**License**: MIT  
-**Node.js**: >=16.0.0 required
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "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": {
@@ -13,13 +13,13 @@
     "./middleware": "./src/middleware/admin.js"
   },
   "scripts": {
-    "test": "echo \"No tests yet\""
+    "test": "node --test"
   },
   "keywords": [
     "authentication",
     "payments",
     "stripe",
-    "supabase",
+    "fastapi",
     "local-development",
     "cli",
     "spaps",
@@ -29,7 +29,7 @@
     "ethereum"
   ],
   "author": "buildooor",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/build000r"

package/src/cli-dispatcher.js

@@ -138,8 +138,20 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
   // spaps create <name>
   const cmdCreate = program
     .command('create <name>')
-    .description('Create a new project with SPAPS (coming soon)')
-    .action(makeAction('create', (optsOrName, cmd) => ({ name: typeof optsOrName === 'string' ? optsOrName : cmd.args[0] })));
+    .description('Create a starter project directory wired for SPAPS')
+    .option('-t, --template <template>', 'Starter template: nextjs|react|node|vanilla')
+    .option('--dir <dir>', 'Target directory (defaults to ./<name>)')
+    .option('-f, --force', 'Allow writing into a non-empty directory', false)
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('create', (opts, cmd, isJson) => ({
+        name: cmd.args[0],
+        template: opts.template || null,
+        dir: opts.dir || null,
+        force: Boolean(opts.force),
+        json: isJson,
+      }))
+    );
   if (dryRun) {
     cmdCreate.allowUnknownOption(true);
     if (typeof cmdCreate.allowExcessArguments === 'function') {
@@ -236,8 +248,14 @@ function buildProgram(config = {}) {
 function parseArgv(argv, config = {}) {
   const { program, getIntents } = defineProgram({ ...config, dryRun: true });
   program.exitOverride(() => { /* swallow exit in dry-run */ });
+  const normalizedArgv = Array.isArray(argv) &&
+    argv.length >= 2 &&
+    /(^|[\\/])node(\.exe)?$/.test(String(argv[0])) &&
+    /spaps(?:\.js)?$/.test(String(argv[1]))
+    ? argv.slice(2)
+    : argv;
   try {
-    program.parse(argv, { from: 'user' });
+    program.parse(normalizedArgv, { from: 'user' });
   } catch (err) {
     // Commander throws for help/version; we ignore in parse mode
   }

package/src/error-handler.js

@@ -91,6 +91,48 @@ const ERROR_FIXES = {
     ]
   }),
 
+  // Invalid arguments
+  EINVAL: (error, context = {}) => ({
+    title: 'Invalid Command Arguments',
+    description: error.message || 'One or more command arguments are invalid',
+    causes: [
+      'A required flag was omitted',
+      'An unsupported template or option was supplied',
+      'The command arguments do not match the expected shape'
+    ],
+    fixes: [
+      {
+        command: 'npx spaps create my-app --template react',
+        description: 'Run create with an explicit supported template'
+      },
+      {
+        command: 'npx spaps help --interactive',
+        description: 'Browse supported create templates and usage examples'
+      }
+    ]
+  }),
+
+  // Existing file system content
+  EEXIST: (error, context = {}) => ({
+    title: 'Target Directory Already Contains Files',
+    description: error.message || 'The target directory is not empty',
+    causes: [
+      'You pointed create at an existing project directory',
+      'A previous scaffold already wrote files there',
+      'The directory contains unrelated files that should not be overwritten by default'
+    ],
+    fixes: [
+      {
+        command: `npx spaps create ${context.name || 'my-app'} --template ${context.template || 'react'} --dir ${context.dir || './my-app'} --force`,
+        description: 'Overwrite the managed starter files explicitly'
+      },
+      {
+        command: `npx spaps create ${context.name || 'my-app'} --template ${context.template || 'react'} --dir ./another-directory`,
+        description: 'Choose an empty directory for the new starter'
+      }
+    ]
+  }),
+
   // Network errors
   ECONNREFUSED: (error, context = {}) => ({
     title: 'Connection Refused',

package/src/handlers.js

@@ -7,6 +7,7 @@ const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-
 const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
 const { buildToolSpec } = require('./ai-tool-spec');
 const { runDoctor } = require('./doctor');
+const { createProjectStarter } = require('./project-scaffolder');
 
 function createHandlers(version, logo) {
   return {
@@ -114,12 +115,57 @@ function createHandlers(version, logo) {
         console.log(chalk.cyan('  3. Start coding!'));
       }
     },
-    create: () => {
-      console.log(chalk.yellow('🍠 SPAPS'));
-      console.log(chalk.yellow(`🚧 'spaps create' coming in v0.3.0!`));
-      console.log();
-      console.log('For now, check out our examples:');
-      console.log(chalk.cyan('  https://github.com/yourusername/sweet-potato/tree/main/examples'));
+    create: ({ options }) => {
+      const isJson = options.json;
+
+      try {
+        const result = createProjectStarter({
+          name: options.name,
+          template: options.template,
+          dir: options.dir,
+          force: options.force,
+          version,
+        });
+
+        if (isJson) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log(chalk.green(`\n✨ Created ${result.project_name} (${result.template})`));
+        console.log(chalk.cyan(`   ${result.target_dir}`));
+
+        if (result.files_created.length > 0) {
+          console.log(chalk.green('\nFiles created:'));
+          result.files_created.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        if (result.files_overwritten.length > 0) {
+          console.log(chalk.yellow('\nFiles overwritten:'));
+          result.files_overwritten.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        console.log(chalk.green('\nNext steps:'));
+        result.next_steps.forEach((step, index) => {
+          console.log(chalk.cyan(`  ${index + 1}. ${step}`));
+        });
+        console.log();
+      } catch (error) {
+        handleError(
+          error,
+          {
+            command: 'create',
+            name: options.name,
+            template: options.template,
+            dir: options.dir,
+          },
+          { json: isJson }
+        );
+      }
     },
     types: () => {
       console.log(chalk.yellow('🍠 SPAPS'));

package/src/help-system.js

@@ -454,7 +454,7 @@ function showQuickHelp() {
   console.log(chalk.green('Common Commands:'));
   console.log('  npx spaps local                  ' + chalk.gray('# Start local server'));
   console.log('  npx spaps init                   ' + chalk.gray('# Initialize in project'));
-  console.log('  npx spaps create <name>          ' + chalk.gray('# Create new project (v0.3.0)'));
+  console.log('  npx spaps create <name>          ' + chalk.gray('# Scaffold a SPAPS starter project'));
   console.log('  npx spaps types                  ' + chalk.gray('# Generate types (v0.4.0)'));
   console.log();
   

package/src/project-scaffolder.js

@@ -0,0 +1,301 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { DEFAULT_PORT } = require('./config');
+
+const SUPPORTED_TEMPLATES = {
+  nextjs: {
+    label: 'Next.js starter',
+    blueprintKey: 'browser_auth',
+    allowedOrigins: ['http://localhost:3000'],
+    files: ({ apiUrl }) => ({
+      'lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || '${apiUrl}',
+});
+`,
+      'app/providers.tsx': `'use client';
+
+import { PropsWithChildren } from 'react';
+import { spaps } from '../lib/spaps';
+
+export function Providers({ children }: PropsWithChildren) {
+  void spaps;
+  return children;
+}
+`,
+    }),
+  },
+  react: {
+    label: 'React + Vite starter',
+    blueprintKey: 'browser_auth',
+    allowedOrigins: ['http://localhost:5173'],
+    files: ({ apiUrl }) => ({
+      'src/lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: import.meta.env.VITE_SPAPS_API_URL || '${apiUrl}',
+});
+`,
+    }),
+  },
+  node: {
+    label: 'Node.js starter',
+    blueprintKey: 'default',
+    allowedOrigins: [],
+    files: ({ apiUrl }) => ({
+      'src/spaps.js': `const { SPAPSClient } = require('spaps-sdk');
+
+const spaps = new SPAPSClient({
+  apiUrl: process.env.SPAPS_API_URL || '${apiUrl}',
+  apiKey: process.env.SPAPS_API_KEY,
+});
+
+module.exports = { spaps };
+`,
+    }),
+  },
+  vanilla: {
+    label: 'Vanilla JavaScript starter',
+    blueprintKey: 'browser_auth',
+    allowedOrigins: ['http://localhost:8080'],
+    files: ({ apiUrl }) => ({
+      'src/spaps.js': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: '${apiUrl}',
+});
+`,
+    }),
+  },
+};
+
+function createCliError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function slugifyProjectName(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function ensureSupportedTemplate(template) {
+  if (!template) {
+    throw createCliError(
+      'EINVAL',
+      `The --template flag is required. Supported templates: ${Object.keys(SUPPORTED_TEMPLATES).join(', ')}.`
+    );
+  }
+
+  if (!SUPPORTED_TEMPLATES[template]) {
+    throw createCliError(
+      'EINVAL',
+      `Unsupported template "${template}". Supported templates: ${Object.keys(SUPPORTED_TEMPLATES).join(', ')}.`
+    );
+  }
+}
+
+function ensureWritableTarget(targetDir, force) {
+  if (!fs.existsSync(targetDir)) {
+    return;
+  }
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length > 0 && !force) {
+    throw createCliError(
+      'EEXIST',
+      `Target directory "${targetDir}" is not empty. Re-run with --force to overwrite managed files.`
+    );
+  }
+}
+
+function writeManagedFile(targetDir, relativePath, content, bookkeeping) {
+  const fullPath = path.join(targetDir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+
+  if (fs.existsSync(fullPath)) {
+    bookkeeping.files_overwritten.push(relativePath);
+  } else {
+    bookkeeping.files_created.push(relativePath);
+  }
+
+  fs.writeFileSync(fullPath, content);
+}
+
+function buildPackageJson(name, template) {
+  const pkg = {
+    name,
+    private: true,
+    version: '0.0.0',
+    description: `SPAPS ${SUPPORTED_TEMPLATES[template].label.toLowerCase()} for ${name}`,
+    dependencies: {
+      'spaps-sdk': 'latest',
+    },
+  };
+
+  if (template === 'node') {
+    pkg.type = 'commonjs';
+  }
+
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+function buildContract({ name, slug, template, version, apiUrl, docsUrl }) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  const contract = {
+    name,
+    slug,
+    template,
+    created_with: `spaps@${version}`,
+    spaps: {
+      local: {
+        api_url: apiUrl,
+        docs_url: docsUrl,
+      },
+      application: {
+        slug,
+        blueprint_key: templateDef.blueprintKey,
+        allowed_origins: templateDef.allowedOrigins,
+        provisioning_status: 'local_starter_only',
+      },
+    },
+  };
+
+  return `${JSON.stringify(contract, null, 2)}\n`;
+}
+
+function buildEnvFile(template, apiUrl) {
+  const lines = [
+    '# SPAPS local development',
+    `SPAPS_API_URL=${apiUrl}`,
+    '# SPAPS_API_KEY=',
+  ];
+
+  if (template === 'nextjs') {
+    lines.push(`NEXT_PUBLIC_SPAPS_API_URL=${apiUrl}`);
+  }
+
+  if (template === 'react') {
+    lines.push(`VITE_SPAPS_API_URL=${apiUrl}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function buildReadme({ name, template, apiUrl }) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
+
+  return `# ${name}
+
+This directory is a SPAPS ${templateDef.label.toLowerCase()}.
+
+It gives you three things immediately:
+
+- a machine-readable SPAPS app contract in \`spaps.app.json\`
+- local env wiring in \`.env.local\`
+- a small template-specific integration starter you can drop into a real app
+
+This is not a full framework generator. It does not run \`create-next-app\`, Vite, or Express setup for you.
+
+## Next Steps
+
+1. Start SPAPS locally with \`npx spaps local\`
+2. Install dependencies in this project with \`npm install\`
+3. Copy the generated starter files into your real ${templateDef.label.toLowerCase()} or keep extending this directory
+4. Point your app at \`${apiUrl}\`
+
+## Generated Files
+
+- \`spaps.app.json\`: local-first app contract and blueprint hints
+- \`.env.local\`: SPAPS API URL wiring
+- \`package.json\`: minimal dependency declaration for \`spaps-sdk\`
+`;
+}
+
+function createProjectStarter({
+  name,
+  template,
+  dir = null,
+  force = false,
+  version = '0.0.0',
+  port = DEFAULT_PORT,
+}) {
+  if (!name || !String(name).trim()) {
+    throw createCliError('EINVAL', 'Project name is required.');
+  }
+
+  ensureSupportedTemplate(template);
+
+  const normalizedName = String(name).trim();
+  const slug = slugifyProjectName(normalizedName);
+  const targetDir = path.resolve(dir || path.join(process.cwd(), slug));
+  const apiUrl = `http://localhost:${port}`;
+  const docsUrl = `${apiUrl}/docs`;
+  const bookkeeping = {
+    files_created: [],
+    files_overwritten: [],
+  };
+
+  ensureWritableTarget(targetDir, force);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  writeManagedFile(
+    targetDir,
+    'spaps.app.json',
+    buildContract({
+      name: normalizedName,
+      slug,
+      template,
+      version,
+      apiUrl,
+      docsUrl,
+    }),
+    bookkeeping
+  );
+  writeManagedFile(targetDir, '.env.local', buildEnvFile(template, apiUrl), bookkeeping);
+  writeManagedFile(targetDir, 'README.md', buildReadme({ name: normalizedName, template, apiUrl }), bookkeeping);
+  writeManagedFile(targetDir, 'package.json', buildPackageJson(normalizedName, template), bookkeeping);
+  writeManagedFile(
+    targetDir,
+    '.gitignore',
+    'node_modules\n.env\n.env.local\n',
+    bookkeeping
+  );
+
+  const templateFiles = SUPPORTED_TEMPLATES[template].files({
+    name: normalizedName,
+    slug,
+    apiUrl,
+  });
+
+  for (const [relativePath, content] of Object.entries(templateFiles)) {
+    writeManagedFile(targetDir, relativePath, content, bookkeeping);
+  }
+
+  return {
+    success: true,
+    command: 'create',
+    project_name: normalizedName,
+    template,
+    target_dir: targetDir,
+    contract_path: path.join(targetDir, 'spaps.app.json'),
+    files_created: bookkeeping.files_created,
+    files_overwritten: bookkeeping.files_overwritten,
+    next_steps: [
+      `cd ${targetDir}`,
+      'npm install',
+      'npx spaps local',
+    ],
+  };
+}
+
+module.exports = {
+  SUPPORTED_TEMPLATES,
+  createProjectStarter,
+};