spaps 0.7.2 → 0.7.4

package/src/cli-dispatcher.js

@@ -28,10 +28,11 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
       // For commands with args, it passes (arg1, arg2, ..., options, command)
       const cmd = args[args.length - 1];
       const options = args[args.length - 2] || {};
+      const positionals = args.slice(0, -2);
       const parentJson = program.opts().json;
       const isJson = Boolean(options.json || parentJson);
 
-      const intent = { name, options: { ...shape(options, cmd, isJson) } };
+      const intent = { name, options: { ...shape(options, cmd, isJson, positionals) } };
       intents.push(intent);
 
       if (dryRun) return intent;
@@ -48,34 +49,26 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .command('local [subcommand]')
     .description('Start local SPAPS server via Docker Compose (subcommand: stop)')
     .option('-p, --port <port>', 'Port to check (default: 3301)', String(DEFAULT_PORT))
+    .option('--runtime-dir <path>', 'Portable runtime directory (defaults to ~/.cache/spaps/local-<port>)')
+    .option('--runtime-source <source>', 'Runtime source: auto|repo|bundle', 'auto')
+    .option(
+      '--data-source <source>',
+      'Base data source: empty|prod-cache|prod-fresh (use --from-backup for an explicit dump file)',
+      'empty'
+    )
     .option('-d, --detach', 'Run in background (don\'t tail logs)', false)
     .option('--fresh', 'Fresh start: tear down and rebuild from scratch', false)
     .option('--from-backup <path>', 'Load from Supabase backup file', null)
     .option('-o, --open', 'Open browser automatically', false)
     .option('--json', 'Output in JSON format')
     .action(
-      makeAction('local', (subcommandOrOpts, cmdOrOpts, isJsonOrCmd) => {
-        // Handle both 'local' and 'local stop' cases
-        let subcommand = null;
-        let opts = null;
-        let cmd = null;
-        let isJson = false;
-
-        if (typeof subcommandOrOpts === 'string') {
-          // 'local stop' case
-          subcommand = subcommandOrOpts;
-          opts = cmdOrOpts;
-          cmd = isJsonOrCmd;
-          isJson = Boolean(opts.json || (cmd && cmd.parent && cmd.parent.opts().json));
-        } else {
-          // 'local' case (no subcommand)
-          opts = subcommandOrOpts;
-          cmd = cmdOrOpts;
-          isJson = Boolean(opts.json || (cmd && cmd.parent && cmd.parent.opts().json));
-        }
-
+      makeAction('local', (opts, _cmd, isJson, positionals) => {
+        const subcommand = typeof positionals[0] === 'string' ? positionals[0] : null;
         const out = {
           port: Number(opts.port) || 3301,
+          runtimeDir: opts.runtimeDir || null,
+          runtimeSource: String(opts.runtimeSource || 'auto'),
+          dataSource: String(opts.dataSource || 'empty'),
           open: Boolean(opts.open),
           detach: Boolean(opts.detach),
           fresh: Boolean(opts.fresh),
@@ -138,8 +131,22 @@ 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('-p, --port <port>', 'Local SPAPS port to provision against', String(DEFAULT_PORT))
+    .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,
+        port: Number(opts.port) || DEFAULT_PORT,
+        force: Boolean(opts.force),
+        json: isJson,
+      }))
+    );
   if (dryRun) {
     cmdCreate.allowUnknownOption(true);
     if (typeof cmdCreate.allowExcessArguments === 'function') {
@@ -209,6 +216,38 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     }
   }
 
+  // spaps fixtures
+  const cmdFixtures = program
+    .command('fixtures <subcommand>')
+    .description('Manage repo-local .spaps auth fixtures (init|apply|reset|storage-state)')
+    .option('--dir <dir>', 'Target repo directory (defaults to current working directory)')
+    .option('-p, --port <port>', 'Port to inspect for SPAPS runtime hints', String(DEFAULT_PORT))
+    .option('--base-url <url>', 'Browser app base URL for generated storage-state files')
+    .option('--persona <persona>', 'Persona code to target for storage-state export')
+    .option('-f, --format <format>', 'Artifact format (playwright)', 'playwright')
+    .option('--force', 'Overwrite fixture files during init', false)
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('fixtures', (opts, cmd, isJson) => {
+        return {
+          subcommand: cmd.args[0],
+          dir: opts.dir || null,
+          port: Number(opts.port) || DEFAULT_PORT,
+          baseUrl: opts.baseUrl || null,
+          persona: opts.persona || null,
+          format: String(opts.format || 'playwright'),
+          force: Boolean(opts.force),
+          json: isJson,
+        };
+      })
+    );
+  if (dryRun) {
+    cmdFixtures.allowUnknownOption(true);
+    if (typeof cmdFixtures.allowExcessArguments === 'function') {
+      cmdFixtures.allowExcessArguments(true);
+    }
+  }
+
   // spaps doctor
   const cmdDoctor = program
     .command('doctor')
@@ -226,6 +265,92 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     }
   }
 
+  // spaps login
+  const cmdLogin = program
+    .command('login')
+    .description('Authenticate with a SPAPS server (RFC 8628 device flow)')
+    .option('-p, --port <port>', 'Port (default: 3301)', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--client-id <id>', 'Application slug to authorize as')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('login', (opts, _cmd, isJson) => ({
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        clientId: opts.clientId || null,
+        json: isJson,
+      }))
+    );
+  if (dryRun) {
+    cmdLogin.allowUnknownOption(true);
+    if (typeof cmdLogin.allowExcessArguments === 'function') {
+      cmdLogin.allowExcessArguments(true);
+    }
+  }
+
+  // spaps logout
+  const cmdLogout = program
+    .command('logout')
+    .description('Revoke and clear stored SPAPS credentials')
+    .option('-p, --port <port>', 'Port (default: 3301)', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('logout', (opts, _cmd, isJson) => ({
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        json: isJson,
+      }))
+    );
+  if (dryRun) {
+    cmdLogout.allowUnknownOption(true);
+    if (typeof cmdLogout.allowExcessArguments === 'function') {
+      cmdLogout.allowExcessArguments(true);
+    }
+  }
+
+  // spaps whoami
+  const cmdWhoami = program
+    .command('whoami')
+    .description('Show the currently authenticated user')
+    .option('-p, --port <port>', 'Port (default: 3301)', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('whoami', (opts, _cmd, isJson) => ({
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        json: isJson,
+      }))
+    );
+  if (dryRun) {
+    cmdWhoami.allowUnknownOption(true);
+    if (typeof cmdWhoami.allowExcessArguments === 'function') {
+      cmdWhoami.allowExcessArguments(true);
+    }
+  }
+
+  // spaps token (print access token for piping to curl or env vars)
+  const cmdToken = program
+    .command('token')
+    .description('Print the current access token (for piping to tools like curl)')
+    .option('-p, --port <port>', 'Port (default: 3301)', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--json', 'Output JSON with metadata instead of bare token')
+    .action(
+      makeAction('token', (opts, _cmd, isJson) => ({
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        json: isJson,
+      }))
+    );
+  if (dryRun) {
+    cmdToken.allowUnknownOption(true);
+    if (typeof cmdToken.allowExcessArguments === 'function') {
+      cmdToken.allowExcessArguments(true);
+    }
+  }
+
   return { program, getIntents: () => intents };
 }
 
@@ -236,8 +361,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/docs-system.js

@@ -22,13 +22,13 @@ ${chalk.green('Basic Usage:')}
   ${chalk.gray('// CommonJS')}
   const { SweetPotatoSDK } = require('spaps-sdk')
   
-  ${chalk.gray('// Create client (auto-detects local mode)')}
+${chalk.gray('// Create client for local or provisioned SPAPS')}
   const sdk = new SweetPotatoSDK({
     apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
-    apiKey: process.env.SPAPS_API_KEY,  ${chalk.gray('// Not required in local mode')}
+    apiKey: process.env.SPAPS_API_KEY,  ${chalk.gray('// Required unless /health/local-mode says otherwise')}
   })
   
-  ${chalk.gray('// Sign in with email/password (local mode accepts any credentials)')}
+  ${chalk.gray('// Sign in with email/password')}
   const auth = await sdk.auth.signInWithPassword({ email: 'user@example.com', password: 'password' })
   console.log('User:', auth.user)
 `
@@ -108,18 +108,18 @@ ${chalk.green('Environment Variables:')}
 ${chalk.green('Configuration Options:')}
   const sdk = new SweetPotatoSDK({
     apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
-    apiKey: process.env.SPAPS_API_KEY, ${chalk.gray('// Omit in local dev')}
+    apiKey: process.env.SPAPS_API_KEY, ${chalk.gray('// Omit only when /health/local-mode reports local_mode_active: true')}
   })
 
 ${chalk.green('Local Mode Detection:')}
-  ${chalk.gray('// The SDK automatically detects local mode when:')}
+  ${chalk.gray('// Localhost URLs still need the running server to advertise local mode:')}
   - URL contains 'localhost'
   - URL contains '127.0.0.1'
   - No API URL is provided
   
-  ${chalk.gray('// Check if in local mode')}
+  ${chalk.gray('// Verify against the server before assuming no key is required')}
   if (sdk.isLocalMode) {
-    console.log('Running in local mode - no API key needed!')
+    console.log('Check /health/local-mode before skipping API keys.')
   }
 `
   },

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',