spaps 0.7.3 → 0.7.5

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),
@@ -141,6 +134,7 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .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(
@@ -148,6 +142,7 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
         name: cmd.args[0],
         template: opts.template || null,
         dir: opts.dir || null,
+        port: Number(opts.port) || DEFAULT_PORT,
         force: Boolean(opts.force),
         json: isJson,
       }))
@@ -221,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')
@@ -238,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 };
 }
 

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.')
   }
 `
   },