spaps 0.5.0 → 0.5.2

package/src/ai-tool-spec.js

@@ -0,0 +1,298 @@
+/**
+ * AI Tool Spec generator for SPAPS
+ * - Produces OpenAI-style function schemas for common SPAPS actions
+ * - Keeps defaults safe for local development (no API key required)
+ */
+
+const { DEFAULT_PORT } = require('./config');
+const fs = require('fs');
+const path = require('path');
+
+function tryLoadManifest() {
+  const candidates = [
+    path.resolve(process.cwd(), 'docs/manifest.json'),
+    path.resolve(__dirname, '../../../docs/manifest.json')
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const raw = fs.readFileSync(p, 'utf8');
+        return JSON.parse(raw);
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function tryLoadOpenAPI() {
+  const candidates = [
+    path.resolve(process.cwd(), 'docs/api-reference.yaml'),
+    path.resolve(__dirname, '../../../docs/api-reference.yaml')
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const yaml = require('js-yaml');
+        const raw = fs.readFileSync(p, 'utf8');
+        return yaml.load(raw);
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
+  const baseUrl = `http://localhost:${port}`;
+  const spec = {
+    name: 'spaps',
+    version: '0.1.0',
+    description: 'Auth + payments via SPAPS (local by default). Start with: npx spaps local',
+    base_url: baseUrl,
+    auth: {
+      local_mode: true,
+      production: {
+        header: 'X-API-Key',
+        env: 'SPAPS_API_KEY'
+      }
+    },
+    tools: [
+      {
+        name: 'login',
+        description: 'Login with email/password. Local mode accepts any values.',
+        method: 'POST',
+        path: '/api/auth/login',
+        parameters: {
+          type: 'object',
+          required: ['email', 'password'],
+          properties: {
+            email: { type: 'string', description: 'Email address' },
+            password: { type: 'string', description: 'Plain text password' }
+          }
+        }
+      },
+      {
+        name: 'register',
+        description: 'Register a new user with email/password.',
+        method: 'POST',
+        path: '/api/auth/register',
+        parameters: {
+          type: 'object',
+          required: ['email', 'password'],
+          properties: {
+            email: { type: 'string' },
+            password: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'get_current_user',
+        description: 'Get the currently authenticated user. Uses bearer token from previous login.',
+        method: 'GET',
+        path: '/api/auth/user',
+        parameters: {
+          type: 'object',
+          properties: {
+            authorization: { type: 'string', description: 'Bearer <access_token>' }
+          }
+        }
+      },
+      {
+        name: 'create_checkout_session',
+        description: 'Create a Stripe Checkout session. In local mode uses Stripe test or mock based on USE_REAL_STRIPE.',
+        method: 'POST',
+        path: '/api/stripe/checkout-sessions',
+        parameters: {
+          type: 'object',
+          required: ['success_url', 'cancel_url'],
+          properties: {
+            price_id: { type: 'string', description: 'Existing Stripe price ID (preferred)' },
+            product_name: { type: 'string', description: 'Used when price_id not provided' },
+            amount: { type: 'number', description: 'Amount in cents if creating ad-hoc price' },
+            currency: { type: 'string', default: 'usd' },
+            success_url: { type: 'string' },
+            cancel_url: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'list_products',
+        description: 'List products (Stripe-backed or local).',
+        method: 'GET',
+        path: '/api/stripe/products',
+        parameters: {
+          type: 'object',
+          properties: {
+            active: { type: 'boolean' },
+            limit: { type: 'number' }
+          }
+        }
+      },
+      {
+        name: 'request_magic_link',
+        description: 'Send a magic link for passwordless login (local mode simulates delivery).',
+        method: 'POST',
+        path: '/api/auth/magic-link',
+        parameters: {
+          type: 'object',
+          required: ['email'],
+          properties: {
+            email: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'get_wallet_nonce',
+        description: 'Get a nonce to sign for wallet authentication.',
+        method: 'POST',
+        path: '/api/auth/nonce',
+        parameters: {
+          type: 'object',
+          required: ['wallet_address'],
+          properties: {
+            wallet_address: { type: 'string' },
+            chain_type: { type: 'string', enum: ['solana', 'ethereum', 'bitcoin', 'base'] }
+          }
+        }
+      }
+    ]
+  };
+
+  // Default error shapes used for enrichment/merging
+  const defaultErrors = {
+    '400': {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean' },
+        error: { type: 'object', properties: { code: { type: 'string' }, message: { type: 'string' } }, required: ['message'] }
+      },
+      required: ['error']
+    },
+    '401': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['unauthorized'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '403': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['forbidden'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '429': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['rate_limited'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '500': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['server_error'] }, message: { type: 'string' } },
+      required: ['error']
+    }
+  };
+
+  // Attempt to align paths/methods with docs/manifest.json if available
+  try {
+    const manifest = tryLoadManifest();
+    if (manifest && Array.isArray(manifest.endpoints)) {
+      const find = (method, pathStr) => manifest.endpoints.find(e => e.method === method && e.path === pathStr);
+      const patchTool = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const ep = find(method, pathStr);
+        if (t && ep) {
+          t.method = ep.method;
+          t.path = ep.path;
+        }
+      };
+      patchTool('login', 'POST', '/api/auth/login');
+      patchTool('register', 'POST', '/api/auth/register');
+      patchTool('get_current_user', 'GET', '/api/auth/user');
+      patchTool('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      patchTool('list_products', 'GET', '/api/stripe/products');
+      patchTool('request_magic_link', 'POST', '/api/auth/magic-link');
+      patchTool('get_wallet_nonce', 'POST', '/api/auth/nonce');
+    }
+  } catch {
+    // Best-effort alignment only
+  }
+
+  // Attempt to enrich parameter schemas from OpenAPI
+  try {
+    const openapi = tryLoadOpenAPI();
+    if (openapi && openapi.paths) {
+      const findOp = (method, pathStr) => {
+        const ops = openapi.paths[pathStr];
+        if (!ops) return null;
+        return ops[String(method).toLowerCase()] || null;
+      };
+      const setBodySchema = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const op = findOp(method, pathStr);
+        const schema = op?.requestBody?.content?.['application/json']?.schema;
+        if (t && schema) {
+          t.parameters = schema;
+        }
+      };
+      const setResponses = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const op = findOp(method, pathStr);
+        if (t && op && op.responses) {
+          const responses = {};
+          const examples = {};
+          for (const [code, obj] of Object.entries(op.responses)) {
+            const schema = obj?.content?.['application/json']?.schema;
+            if (schema) responses[code] = schema;
+            const content = obj?.content?.['application/json'];
+            if (content?.example !== undefined) {
+              examples[code] = content.example;
+            } else if (content?.examples && typeof content.examples === 'object') {
+              const ex = {};
+              for (const [name, val] of Object.entries(content.examples)) {
+                if (val && typeof val === 'object') {
+                  if ('value' in val) ex[name] = val.value;
+                }
+              }
+              if (Object.keys(ex).length) examples[code] = ex;
+            }
+          }
+          if (Object.keys(responses).length) {
+            // Merge with default errors for completeness
+            const merged = { ...defaultErrors, ...responses };
+            t.responses = merged;
+          }
+          if (Object.keys(examples).length) t.examples = examples;
+        }
+      };
+      setBodySchema('login', 'POST', '/api/auth/login');
+      setBodySchema('register', 'POST', '/api/auth/register');
+      setBodySchema('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      setBodySchema('request_magic_link', 'POST', '/api/auth/magic-link');
+      setBodySchema('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      setResponses('login', 'POST', '/api/auth/login');
+      setResponses('register', 'POST', '/api/auth/register');
+      setResponses('get_current_user', 'GET', '/api/auth/user');
+      setResponses('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      setResponses('list_products', 'GET', '/api/stripe/products');
+      setResponses('request_magic_link', 'POST', '/api/auth/magic-link');
+      setResponses('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      // For GET endpoints with query/headers, leave minimal schema for simplicity
+    }
+  } catch {
+    // Ignore enrichment errors
+  }
+
+  // Add default error shapes if responses missing
+  spec.tools.forEach(t => {
+    if (!t.responses) t.responses = defaultErrors;
+  });
+
+  return spec;
+}
+
+function buildToolSpec({ format = 'openai', port = DEFAULT_PORT } = {}) {
+  switch (format) {
+    case 'openai':
+    default:
+      return buildOpenAIToolSpec({ port });
+  }
+}
+
+module.exports = { buildToolSpec };

package/src/cli-dispatcher.js

@@ -0,0 +1,233 @@
+// CLI dispatcher: builds a Commander program with pluggable handlers
+// Enables dry-run parsing for unit tests without executing side effects.
+
+const { Command } = require('commander');
+const { DEFAULT_PORT } = require('./config');
+
+function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo = null } = {}) {
+  const intents = [];
+  const program = new Command();
+
+  if (dryRun) {
+    program.allowUnknownOption(true);
+    // Tolerate stray operands during unit tests (Commander normally errors)
+    if (typeof program.allowExcessArguments === 'function') {
+      program.allowExcessArguments(true);
+    }
+  }
+
+  program
+    .name('spaps')
+    .description('CLI for Sweet Potato Authentication & Payment Service')
+    .version(version)
+    .option('--json', 'Output in JSON format for machine parsing');
+
+  function makeAction(name, shape) {
+    return async function actionWrapper(...args) {
+      // Commander 11 passes (options, command) for subcommands without args
+      // For commands with args, it passes (arg1, arg2, ..., options, command)
+      const cmd = args[args.length - 1];
+      const options = args[args.length - 2] || {};
+      const parentJson = program.opts().json;
+      const isJson = Boolean(options.json || parentJson);
+
+      const intent = { name, options: { ...shape(options, cmd, isJson) } };
+      intents.push(intent);
+
+      if (dryRun) return intent;
+      const handler = handlers[name];
+      if (typeof handler === 'function') {
+        return await handler(intent, { program, cmd });
+      }
+      return intent;
+    };
+  }
+
+  // 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')
+    .option('-o, --open', 'Open browser automatically', false)
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('local', (opts, cmd, isJson) => {
+        const out = {
+          port: Number(opts.port),
+          open: Boolean(opts.open),
+          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;
+      })
+    );
+  if (dryRun) {
+    cmdLocal.allowUnknownOption(true);
+    if (typeof cmdLocal.allowExcessArguments === 'function') {
+      cmdLocal.allowExcessArguments(true);
+    }
+  }
+
+  // spaps quickstart
+  const cmdQuick = program
+    .command('quickstart')
+    .description('Get quick start instructions (for AI agents)')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('quickstart', (opts, _cmd, isJson) => ({ port: Number(opts.port), json: isJson })));
+  if (dryRun) {
+    cmdQuick.allowUnknownOption(true);
+    if (typeof cmdQuick.allowExcessArguments === 'function') {
+      cmdQuick.allowExcessArguments(true);
+    }
+  }
+
+  // spaps status
+  const cmdStatus = program
+    .command('status')
+    .description('Check if SPAPS server is running')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('status', (opts, _cmd, isJson) => ({ port: Number(opts.port), json: isJson })));
+  if (dryRun) {
+    cmdStatus.allowUnknownOption(true);
+    if (typeof cmdStatus.allowExcessArguments === 'function') {
+      cmdStatus.allowExcessArguments(true);
+    }
+  }
+
+  // spaps init
+  const cmdInit = program
+    .command('init')
+    .description('Initialize SPAPS in current project')
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('init', (_opts, _cmd, isJson) => ({ json: isJson })));
+  if (dryRun) {
+    cmdInit.allowUnknownOption(true);
+    if (typeof cmdInit.allowExcessArguments === 'function') {
+      cmdInit.allowExcessArguments(true);
+    }
+  }
+
+  // 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] })));
+  if (dryRun) {
+    cmdCreate.allowUnknownOption(true);
+    if (typeof cmdCreate.allowExcessArguments === 'function') {
+      cmdCreate.allowExcessArguments(true);
+    }
+  }
+
+  // spaps types
+  const cmdTypes = program
+    .command('types')
+    .description('Generate TypeScript types (coming soon)')
+    .action(makeAction('types', () => ({})));
+  if (dryRun) {
+    cmdTypes.allowUnknownOption(true);
+    if (typeof cmdTypes.allowExcessArguments === 'function') {
+      cmdTypes.allowExcessArguments(true);
+    }
+  }
+
+  // spaps help
+  const cmdHelp = program
+    .command('help')
+    .description('Show help and guides')
+    .option('-i, --interactive', 'Interactive help mode')
+    .option('-q, --quick', 'Quick reference')
+    .action(
+      makeAction('help', (opts) => ({ interactive: Boolean(opts.interactive), quick: Boolean(opts.quick) }))
+    );
+  if (dryRun) {
+    cmdHelp.allowUnknownOption(true);
+    if (typeof cmdHelp.allowExcessArguments === 'function') {
+      cmdHelp.allowExcessArguments(true);
+    }
+  }
+
+  // spaps docs
+  const cmdDocs = program
+    .command('docs')
+    .description('Browse SDK documentation')
+    .option('-i, --interactive', 'Interactive documentation browser')
+    .option('-s, --search <query>', 'Search documentation')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('docs', (opts, _cmd, isJson) => ({ interactive: Boolean(opts.interactive), search: opts.search || null, json: isJson }))
+    );
+  if (dryRun) {
+    cmdDocs.allowUnknownOption(true);
+    if (typeof cmdDocs.allowExcessArguments === 'function') {
+      cmdDocs.allowExcessArguments(true);
+    }
+  }
+
+  // spaps tools
+  const cmdTools = program
+    .command('tools')
+    .description('Output AI tool spec (OpenAI-style)')
+    .option('-p, --port <port>', 'Port to use for base_url', String(DEFAULT_PORT))
+    .option('-f, --format <format>', 'Spec format (openai)', 'openai')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('tools', (opts, _cmd, isJson) => ({ port: Number(opts.port), format: String(opts.format || 'openai'), json: isJson }))
+    );
+  if (dryRun) {
+    cmdTools.allowUnknownOption(true);
+    if (typeof cmdTools.allowExcessArguments === 'function') {
+      cmdTools.allowExcessArguments(true);
+    }
+  }
+
+  // spaps doctor
+  const cmdDoctor = program
+    .command('doctor')
+    .description('Diagnose local environment and config')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('-s, --stripe <mode>', 'Stripe mode: mock|real')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('doctor', (opts, _cmd, isJson) => ({ port: Number(opts.port), stripe: opts.stripe || null, json: isJson }))
+    );
+  if (dryRun) {
+    cmdDoctor.allowUnknownOption(true);
+    if (typeof cmdDoctor.allowExcessArguments === 'function') {
+      cmdDoctor.allowExcessArguments(true);
+    }
+  }
+
+  return { program, getIntents: () => intents };
+}
+
+function buildProgram(config = {}) {
+  return defineProgram(config).program;
+}
+
+function parseArgv(argv, config = {}) {
+  const { program, getIntents } = defineProgram({ ...config, dryRun: true });
+  program.exitOverride(() => { /* swallow exit in dry-run */ });
+  try {
+    program.parse(argv, { from: 'user' });
+  } catch (err) {
+    // Commander throws for help/version; we ignore in parse mode
+  }
+  return getIntents();
+}
+
+module.exports = { buildProgram, parseArgv };

package/src/config.js

@@ -0,0 +1,5 @@
+// Shared configuration for SPAPS CLI
+module.exports = {
+  DEFAULT_PORT: 3300
+};
+

package/src/docs-html.js

@@ -3,7 +3,7 @@
  * Generates comprehensive documentation page
  */
 
-function generateDocsHTML(port = 3300) {
+function generateDocsHTML(port = 3300, notice) {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -277,6 +277,7 @@ function generateDocsHTML(port = 3300) {
       <p class="subtitle">Sweet Potato Authentication & Payment Service</p>
       <span class="status-badge">✅ Local Mode Active - Port ${port}</span>
     </div>
+    ${notice ? `<div class="alert">${notice}</div>` : ''}
     
     <nav class="nav">
       <ul>
@@ -807,4 +808,4 @@ test().catch(console.error);</code></pre>
 </html>`;
 }
 
-module.exports = { generateDocsHTML };
+module.exports = { generateDocsHTML };