spaps 0.2.3 → 0.2.5

package/bin/spaps.js

@@ -12,6 +12,8 @@ const { program } = require('commander');
 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;
 
@@ -86,37 +88,7 @@ program
       });
       
     } catch (error) {
-      if (isJson) {
-        console.log(JSON.stringify({
-          success: false,
-          command: 'local',
-          error: {
-            message: error.message,
-            code: error.code,
-            suggestion: error.code === 'EADDRINUSE' ? 
-              'Try a different port with --port option' : 
-              'Check error message for details'
-          }
-        }));
-      } else {
-        console.error(chalk.red('❌ Failed to start server:'), error.message);
-        
-        if (error.code === 'MODULE_NOT_FOUND') {
-          console.log(chalk.yellow('\n💡 Installing dependencies...'));
-          const { execSync } = require('child_process');
-          try {
-            execSync('npm install express cors', { 
-              cwd: path.join(__dirname, '..'),
-              stdio: 'inherit'
-            });
-            console.log(chalk.green('✅ Dependencies installed! Please run the command again.'));
-          } catch (installError) {
-            console.error(chalk.red('Failed to install dependencies. Please run: npm install express cors'));
-          }
-        }
-      }
-      
-      process.exit(1);
+      handleError(error, { port: options.port, command: 'local' }, { json: isJson });
     }
   });
 
@@ -205,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();
@@ -221,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.3",
+  "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/error-handler.js

@@ -0,0 +1,271 @@
+/**
+ * SPAPS CLI Error Handler
+ * Provides verbose error messages with exact fix commands
+ */
+
+const chalk = require('chalk');
+
+const ERROR_FIXES = {
+  // Port errors
+  EADDRINUSE: (error, context = {}) => ({
+    title: 'Port Already In Use',
+    description: `Port ${context.port || 3300} is being used by another process`,
+    causes: [
+      'Another SPAPS server is already running',
+      'Another application is using this port',
+      'A previous SPAPS process didn\'t shut down cleanly'
+    ],
+    fixes: [
+      {
+        command: `npx spaps local --port ${(parseInt(context.port || 3300) + 1)}`,
+        description: 'Use a different port'
+      },
+      {
+        command: `lsof -ti:${context.port || 3300} | xargs kill -9`,
+        description: 'Kill the process using this port (macOS/Linux)',
+        platform: ['darwin', 'linux']
+      },
+      {
+        command: `netstat -ano | findstr :${context.port || 3300}`,
+        description: 'Find process using this port (Windows)',
+        platform: ['win32']
+      },
+      {
+        command: 'npx spaps local --port 0',
+        description: 'Let the system choose an available port'
+      }
+    ]
+  }),
+
+  // Module errors
+  MODULE_NOT_FOUND: (error, context = {}) => {
+    const module = error.message.match(/Cannot find module '(.+?)'/)?.[1] || 'unknown';
+    return {
+      title: 'Missing Dependencies',
+      description: `Required module "${module}" is not installed`,
+      causes: [
+        'Dependencies were not installed',
+        'Package installation was interrupted',
+        'Node modules were deleted or corrupted'
+      ],
+      fixes: [
+        {
+          command: 'npm install',
+          description: 'Install all dependencies'
+        },
+        {
+          command: `npm install ${module}`,
+          description: `Install missing module "${module}"`
+        },
+        {
+          command: 'rm -rf node_modules package-lock.json && npm install',
+          description: 'Clean reinstall all dependencies'
+        }
+      ]
+    };
+  },
+
+  // Permission errors
+  EACCES: (error, context = {}) => ({
+    title: 'Permission Denied',
+    description: 'Insufficient permissions to perform this operation',
+    causes: [
+      'Trying to bind to a privileged port (< 1024)',
+      'File system permissions issue',
+      'Node.js doesn\'t have necessary permissions'
+    ],
+    fixes: [
+      {
+        command: 'npx spaps local --port 3000',
+        description: 'Use a non-privileged port (>= 1024)'
+      },
+      {
+        command: `sudo npx spaps ${process.argv.slice(2).join(' ')}`,
+        description: 'Run with elevated permissions (use with caution)',
+        warning: true
+      },
+      {
+        command: 'ls -la ./',
+        description: 'Check file permissions in current directory'
+      }
+    ]
+  }),
+
+  // Network errors
+  ECONNREFUSED: (error, context = {}) => ({
+    title: 'Connection Refused',
+    description: `Cannot connect to ${context.url || 'server'}`,
+    causes: [
+      'Server is not running',
+      'Server is running on a different port',
+      'Firewall is blocking the connection'
+    ],
+    fixes: [
+      {
+        command: 'npx spaps local',
+        description: 'Start the local SPAPS server'
+      },
+      {
+        command: 'curl http://localhost:3300/health',
+        description: 'Check if server is responding'
+      },
+      {
+        command: 'netstat -an | grep LISTEN',
+        description: 'List all listening ports'
+      }
+    ]
+  }),
+
+  // File system errors
+  ENOENT: (error, context = {}) => {
+    const file = error.path || context.file || 'file';
+    return {
+      title: 'File or Directory Not Found',
+      description: `Cannot find "${file}"`,
+      causes: [
+        'File does not exist',
+        'Wrong directory',
+        'File was deleted or moved'
+      ],
+      fixes: [
+        {
+          command: 'pwd',
+          description: 'Check current directory'
+        },
+        {
+          command: 'ls -la',
+          description: 'List files in current directory'
+        },
+        {
+          command: 'npx spaps init',
+          description: 'Initialize SPAPS in this directory'
+        }
+      ]
+    };
+  },
+
+  // Generic errors
+  DEFAULT: (error, context = {}) => ({
+    title: 'Unexpected Error',
+    description: error.message || 'An unexpected error occurred',
+    causes: [
+      'Unknown issue',
+      'Corrupted installation',
+      'System-specific problem'
+    ],
+    fixes: [
+      {
+        command: 'npm cache clean --force && npm install',
+        description: 'Clear npm cache and reinstall'
+      },
+      {
+        command: 'node --version && npm --version',
+        description: 'Check Node.js and npm versions'
+      },
+      {
+        command: 'npx spaps@latest --version',
+        description: 'Check SPAPS version'
+      },
+      {
+        command: 'npm update spaps',
+        description: 'Update SPAPS to latest version'
+      }
+    ]
+  })
+};
+
+function formatError(error, context = {}) {
+  const errorCode = error.code || 'DEFAULT';
+  const errorInfo = ERROR_FIXES[errorCode] 
+    ? ERROR_FIXES[errorCode](error, context)
+    : ERROR_FIXES.DEFAULT(error, context);
+
+  const output = [];
+  
+  // Title
+  output.push(chalk.red.bold(`\n❌ ${errorInfo.title}`));
+  output.push(chalk.white(errorInfo.description));
+  
+  // Possible causes
+  if (errorInfo.causes && errorInfo.causes.length > 0) {
+    output.push(chalk.yellow('\n📋 Possible causes:'));
+    errorInfo.causes.forEach(cause => {
+      output.push(chalk.gray(`   • ${cause}`));
+    });
+  }
+  
+  // Fixes
+  if (errorInfo.fixes && errorInfo.fixes.length > 0) {
+    output.push(chalk.green('\n✨ How to fix:'));
+    errorInfo.fixes.forEach((fix, index) => {
+      // Filter by platform if specified
+      if (fix.platform && !fix.platform.includes(process.platform)) {
+        return;
+      }
+      
+      output.push(chalk.cyan(`\n   ${index + 1}. ${fix.description}`));
+      output.push(chalk.bgBlack.white(`      $ ${fix.command}`));
+      
+      if (fix.warning) {
+        output.push(chalk.yellow(`      ⚠️  Use with caution`));
+      }
+    });
+  }
+  
+  // Additional help
+  output.push(chalk.gray('\n📚 For more help:'));
+  output.push(chalk.gray('   • Documentation: https://sweetpotato.dev/docs'));
+  output.push(chalk.gray('   • GitHub Issues: https://github.com/yourusername/sweet-potato/issues'));
+  output.push(chalk.gray('   • Discord: https://discord.gg/sweetpotato\n'));
+  
+  return output.join('\n');
+}
+
+function formatJsonError(error, context = {}) {
+  const errorCode = error.code || 'DEFAULT';
+  const errorInfo = ERROR_FIXES[errorCode] 
+    ? ERROR_FIXES[errorCode](error, context)
+    : ERROR_FIXES.DEFAULT(error, context);
+
+  return {
+    success: false,
+    error: {
+      code: errorCode,
+      title: errorInfo.title,
+      message: errorInfo.description,
+      causes: errorInfo.causes,
+      fixes: errorInfo.fixes.map(fix => ({
+        command: fix.command,
+        description: fix.description,
+        warning: fix.warning || false
+      })),
+      stack: process.env.DEBUG ? error.stack : undefined
+    },
+    help: {
+      docs: 'https://sweetpotato.dev/docs',
+      issues: 'https://github.com/yourusername/sweet-potato/issues',
+      discord: 'https://discord.gg/sweetpotato'
+    }
+  };
+}
+
+module.exports = {
+  formatError,
+  formatJsonError,
+  handleError: (error, context = {}, options = {}) => {
+    if (options.json) {
+      console.log(JSON.stringify(formatJsonError(error, context), null, 2));
+    } else {
+      console.error(formatError(error, context));
+    }
+    
+    // Exit with appropriate code
+    const exitCode = error.code === 'EADDRINUSE' ? 98 :
+                    error.code === 'EACCES' ? 77 :
+                    error.code === 'ENOENT' ? 66 :
+                    error.code === 'MODULE_NOT_FOUND' ? 127 :
+                    1;
+    
+    process.exit(exitCode);
+  }
+};

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
+};