spaps 0.2.4 → 0.2.5

package/bin/spaps.js

@@ -13,6 +13,7 @@ const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { handleError } = require('../src/error-handler');
+const { showInteractiveHelp, showQuickHelp } = require('../src/help-system');
 
 const version = require('../package.json').version;
 
@@ -176,6 +177,23 @@ program
     console.log(chalk.yellow(`🚧 'spaps types' coming in v0.4.0!`));
   });
 
+// Help command - Interactive help system
+program
+  .command('help')
+  .description('Show help and guides')
+  .option('-i, --interactive', 'Interactive help mode')
+  .option('-q, --quick', 'Quick reference')
+  .action(async (options) => {
+    if (options.interactive) {
+      await showInteractiveHelp();
+    } else if (options.quick) {
+      showQuickHelp();
+    } else {
+      // Default to quick help
+      showQuickHelp();
+    }
+  });
+
 // Help command enhancement
 program.on('--help', () => {
   console.log();
@@ -192,6 +210,8 @@ program.on('--help', () => {
 if (!process.argv.slice(2).length) {
   console.log(logo);
   program.outputHelp();
+  console.log();
+  console.log(chalk.yellow('💡 Try: npx spaps help --interactive'));
 }
 
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Sweet Potato Authentication & Payment Service CLI - Zero-config local development and project scaffolding",
   "main": "bin/spaps.js",
   "bin": {

package/src/help-system.js

@@ -0,0 +1,487 @@
+/**
+ * SPAPS CLI Interactive Help System
+ * Decision trees and structured guidance for developers
+ */
+
+const chalk = require('chalk');
+const prompts = require('prompts');
+
+const HELP_TREE = {
+  root: {
+    question: 'What would you like to do?',
+    options: [
+      {
+        title: '🚀 Start developing locally',
+        value: 'local-dev',
+        description: 'Run SPAPS on your machine'
+      },
+      {
+        title: '📦 Set up a new project',
+        value: 'new-project',
+        description: 'Create a new app with SPAPS'
+      },
+      {
+        title: '🔧 Add SPAPS to existing project',
+        value: 'existing-project',
+        description: 'Integrate SPAPS into your app'
+      },
+      {
+        title: '🐛 Debug an issue',
+        value: 'debug',
+        description: 'Troubleshoot problems'
+      },
+      {
+        title: '📚 Learn about SPAPS',
+        value: 'learn',
+        description: 'Understand concepts and features'
+      }
+    ]
+  },
+
+  'local-dev': {
+    question: 'How do you want to run SPAPS locally?',
+    options: [
+      {
+        title: 'Quick start (default settings)',
+        value: 'quick-start',
+        command: 'npx spaps local',
+        description: 'Start on port 3300'
+      },
+      {
+        title: 'Custom port',
+        value: 'custom-port',
+        command: 'npx spaps local --port 3001',
+        description: 'Choose your own port'
+      },
+      {
+        title: 'Open browser automatically',
+        value: 'auto-open',
+        command: 'npx spaps local --open',
+        description: 'Opens docs in browser'
+      },
+      {
+        title: 'JSON mode (for CI/CD)',
+        value: 'json-mode',
+        command: 'npx spaps local --json',
+        description: 'Machine-readable output'
+      }
+    ]
+  },
+
+  'new-project': {
+    question: 'What type of project?',
+    options: [
+      {
+        title: 'Next.js App',
+        value: 'nextjs',
+        command: 'npx spaps create my-app --template nextjs',
+        description: 'Full-stack React framework',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'React + Vite',
+        value: 'react',
+        command: 'npx spaps create my-app --template react',
+        description: 'Fast, modern React setup',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'Node.js API',
+        value: 'node',
+        command: 'npx spaps create my-api --template node',
+        description: 'Express.js backend',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'Vanilla JavaScript',
+        value: 'vanilla',
+        command: 'npx spaps create my-app --template vanilla',
+        description: 'No framework, just JS',
+        available: 'v0.3.0'
+      }
+    ]
+  },
+
+  'existing-project': {
+    question: 'What framework are you using?',
+    options: [
+      {
+        title: 'Next.js',
+        value: 'integrate-nextjs',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Add to your app:',
+          '',
+          '// app/providers.tsx',
+          'import { SPAPSClient } from "spaps-sdk"',
+          'const spaps = new SPAPSClient()'
+        ]
+      },
+      {
+        title: 'React',
+        value: 'integrate-react',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Create a context:',
+          '',
+          '// src/contexts/SpapsContext.tsx',
+          'import { SPAPSClient } from "spaps-sdk"',
+          'const spaps = new SPAPSClient()',
+          'export const SpapsContext = React.createContext(spaps)'
+        ]
+      },
+      {
+        title: 'Node.js/Express',
+        value: 'integrate-node',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Add middleware:',
+          '',
+          '// server.js',
+          'const { SPAPSClient } = require("spaps-sdk")',
+          'const spaps = new SPAPSClient()',
+          '',
+          'app.use(async (req, res, next) => {',
+          '  req.spaps = spaps',
+          '  next()',
+          '})'
+        ]
+      },
+      {
+        title: 'Other/Vanilla',
+        value: 'integrate-other',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Import in your code:',
+          '',
+          '// Using ES6 modules',
+          'import { SPAPSClient } from "spaps-sdk"',
+          '',
+          '// Using CommonJS',
+          'const { SPAPSClient } = require("spaps-sdk")',
+          '',
+          '// Using CDN',
+          '<script src="https://unpkg.com/spaps-sdk"></script>'
+        ]
+      }
+    ]
+  },
+
+  'debug': {
+    question: 'What issue are you experiencing?',
+    options: [
+      {
+        title: 'Port already in use',
+        value: 'port-error',
+        solution: {
+          commands: [
+            'npx spaps local --port 3301',
+            'lsof -ti:3300 | 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.'
+        }
+      },
+      {
+        title: 'Module not found',
+        value: 'module-error',
+        solution: {
+          commands: [
+            'npm install',
+            'rm -rf node_modules package-lock.json && npm install',
+            'npm install spaps-sdk'
+          ],
+          explanation: 'Dependencies are missing. Reinstall packages to fix this.'
+        }
+      },
+      {
+        title: 'CORS errors',
+        value: 'cors-error',
+        solution: {
+          commands: [
+            'npx spaps local',
+            'Check your API URL: process.env.SPAPS_API_URL'
+          ],
+          explanation: 'CORS is automatically handled in local mode. Make sure your client is pointing to the local server.'
+        }
+      },
+      {
+        title: 'Authentication failing',
+        value: 'auth-error',
+        solution: {
+          commands: [
+            'curl http://localhost:3300/health',
+            'npx spaps local --port 3300'
+          ],
+          explanation: 'In local mode, authentication is automatic. Make sure the local server is running.'
+        }
+      }
+    ]
+  },
+
+  'learn': {
+    question: 'What would you like to learn about?',
+    options: [
+      {
+        title: 'How SPAPS works',
+        value: 'how-it-works',
+        content: `
+SPAPS (Sweet Potato Authentication & Payment Service) provides:
+
+1. **Authentication**: Email/password, magic links, and wallet-based auth
+2. **Payments**: Stripe subscriptions and wallet-based payments
+3. **Local Development**: Zero-config local mode with auto-auth
+4. **Type Safety**: Full TypeScript support with generated types
+5. **Multi-tenant**: API key-based app isolation
+
+In local mode, everything is mocked so you can develop without:
+- API keys
+- Database setup
+- External services
+- Configuration files
+        `
+      },
+      {
+        title: 'Local vs Production',
+        value: 'environments',
+        content: `
+**Local Mode** (http://localhost:3300):
+- No API key required
+- Auto-authentication
+- Mocked responses
+- CORS disabled
+- Perfect for development
+
+**Production Mode** (https://api.yourapp.com):
+- API key required
+- Real authentication
+- Database persistence
+- Stripe integration
+- Rate limiting
+
+The SDK auto-detects which mode to use based on the URL!
+        `
+      },
+      {
+        title: 'Authentication methods',
+        value: 'auth-methods',
+        content: `
+SPAPS supports multiple authentication methods:
+
+**Traditional Auth**:
+- Email/password login
+- Magic link (passwordless)
+- Social logins (coming soon)
+
+**Wallet Auth**:
+- Solana wallets
+- Ethereum wallets
+- Bitcoin (coming soon)
+- Base chain (coming soon)
+
+**Code Examples**:
+\`\`\`javascript
+// Email/password
+await spaps.login(email, password)
+
+// Wallet
+await spaps.walletSignIn(address, signature, message, 'solana')
+\`\`\`
+        `
+      },
+      {
+        title: 'Payment integration',
+        value: 'payments',
+        content: `
+SPAPS handles two payment types:
+
+**Stripe Subscriptions**:
+- Monthly/annual plans
+- Usage-based billing
+- Customer portal
+- Webhook handling
+
+**Wallet Payments**:
+- Direct crypto payments
+- Usage credits
+- Instant settlement
+- Multi-chain support
+
+**Code Example**:
+\`\`\`javascript
+// Create Stripe checkout
+const session = await spaps.createCheckoutSession(priceId, successUrl)
+
+// Check subscription
+const sub = await spaps.getSubscription()
+\`\`\`
+        `
+      }
+    ]
+  }
+};
+
+async function showInteractiveHelp() {
+  console.log(chalk.yellow('\n🍠 SPAPS Interactive Help\n'));
+  
+  let currentNode = 'root';
+  const history = [];
+  
+  while (true) {
+    const node = HELP_TREE[currentNode];
+    
+    if (!node) {
+      // Leaf node - show result
+      break;
+    }
+    
+    const choices = node.options.map(opt => ({
+      title: opt.title,
+      description: opt.description || '',
+      value: opt.value
+    }));
+    
+    // Add back option if not at root
+    if (currentNode !== 'root') {
+      choices.push({
+        title: chalk.gray('← Back'),
+        value: '__back__'
+      });
+    }
+    
+    choices.push({
+      title: chalk.gray('✕ Exit'),
+      value: '__exit__'
+    });
+    
+    const response = await prompts({
+      type: 'select',
+      name: 'choice',
+      message: node.question,
+      choices: choices
+    });
+    
+    if (!response.choice || response.choice === '__exit__') {
+      console.log(chalk.gray('\nGoodbye! 👋\n'));
+      process.exit(0);
+    }
+    
+    if (response.choice === '__back__') {
+      currentNode = history.pop() || 'root';
+      continue;
+    }
+    
+    // Find the selected option
+    const selected = node.options.find(opt => opt.value === response.choice);
+    
+    if (selected) {
+      // Show immediate result if available
+      if (selected.command) {
+        console.log(chalk.green('\n✨ Run this command:\n'));
+        console.log(chalk.bgBlack.white(`  $ ${selected.command}`));
+        
+        if (selected.available) {
+          console.log(chalk.yellow(`\n  ⚠️  Available in ${selected.available}`));
+        }
+        console.log();
+      }
+      
+      if (selected.steps) {
+        console.log(chalk.green('\n📝 Follow these steps:\n'));
+        selected.steps.forEach((step, i) => {
+          if (step.startsWith('//') || step.startsWith('#')) {
+            console.log(chalk.gray(step));
+          } else if (step === '') {
+            console.log();
+          } else if (step.includes('npm') || step.includes('npx')) {
+            console.log(chalk.bgBlack.white(`  $ ${step}`));
+          } else {
+            console.log(`  ${step}`);
+          }
+        });
+        console.log();
+      }
+      
+      if (selected.solution) {
+        console.log(chalk.green('\n💡 Solution:\n'));
+        console.log(chalk.white(selected.solution.explanation));
+        console.log(chalk.green('\nTry these commands:\n'));
+        selected.solution.commands.forEach(cmd => {
+          console.log(chalk.bgBlack.white(`  $ ${cmd}`));
+        });
+        console.log();
+      }
+      
+      if (selected.content) {
+        console.log(chalk.green('\n📚 Information:\n'));
+        console.log(selected.content);
+      }
+      
+      // Navigate to next level if exists
+      if (HELP_TREE[response.choice]) {
+        history.push(currentNode);
+        currentNode = response.choice;
+      } else {
+        // Ask to continue or exit
+        const cont = await prompts({
+          type: 'confirm',
+          name: 'continue',
+          message: 'Continue exploring help?',
+          initial: true
+        });
+        
+        if (!cont.continue) {
+          console.log(chalk.gray('\nGoodbye! 👋\n'));
+          process.exit(0);
+        }
+        
+        // Go back to previous menu
+        currentNode = history.pop() || 'root';
+      }
+    }
+  }
+}
+
+function showQuickHelp() {
+  console.log(chalk.yellow('\n🍠 SPAPS Quick Reference\n'));
+  
+  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 types                  ' + chalk.gray('# Generate types (v0.4.0)'));
+  console.log();
+  
+  console.log(chalk.green('Local Development:'));
+  console.log('  npx spaps local --port 3001      ' + chalk.gray('# Custom port'));
+  console.log('  npx spaps local --open           ' + chalk.gray('# Open browser'));
+  console.log('  npx spaps local --json           ' + chalk.gray('# JSON output'));
+  console.log();
+  
+  console.log(chalk.green('SDK Usage:'));
+  console.log('  npm install spaps-sdk            ' + chalk.gray('# Install SDK'));
+  console.log();
+  console.log(chalk.gray('  import { SPAPSClient } from "spaps-sdk"'));
+  console.log(chalk.gray('  const spaps = new SPAPSClient()'));
+  console.log(chalk.gray('  await spaps.login(email, password)'));
+  console.log();
+  
+  console.log(chalk.green('Debugging:'));
+  console.log('  curl http://localhost:3300/health   ' + chalk.gray('# Check server'));
+  console.log('  npx spaps help --interactive         ' + chalk.gray('# Interactive help'));
+  console.log();
+  
+  console.log(chalk.blue('📚 Docs: https://sweetpotato.dev'));
+  console.log(chalk.blue('💬 Discord: https://discord.gg/sweetpotato'));
+  console.log();
+}
+
+module.exports = {
+  showInteractiveHelp,
+  showQuickHelp,
+  HELP_TREE
+};