spaps 0.7.7 → 0.7.8

package/README.md

@@ -77,9 +77,11 @@ Restore order is always: restore base dump first, then let the API container run
 Run it without installing:
 
 ```bash
-npx spaps
+npx --yes spaps
 ```
 
+For CI, SSH automation, or the first run on a fresh box, prefer `npx --yes spaps ...` so npm does not block on its install confirmation prompt.
+
 Install globally:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {

package/src/auth/env.js

@@ -23,6 +23,10 @@ function isHeadless(env = process.env, platform = process.platform) {
   return isSsh(env) || !hasGui(env, platform);
 }
 
+function hasInteractiveTerminal(stdin = process.stdin, stdout = process.stdout) {
+  return Boolean(stdin && stdin.isTTY && stdout && stdout.isTTY);
+}
+
 function tryOpenBrowser(url, { env = process.env, platform = process.platform } = {}) {
   if (isHeadless(env, platform)) return false;
   try {
@@ -53,5 +57,6 @@ module.exports = {
   isSsh,
   hasGui,
   isHeadless,
+  hasInteractiveTerminal,
   tryOpenBrowser,
 };

package/src/docs-quick.js

@@ -0,0 +1,37 @@
+const chalk = require('chalk');
+
+function showQuickReference() {
+  const output = [
+    '',
+    chalk.yellow('🍠 SPAPS SDK Quick Reference'),
+    '',
+    chalk.green('Installation:'),
+    '  npm install spaps-sdk',
+    '',
+    chalk.green('Basic Setup:'),
+    chalk.gray(`  import { SPAPSClient } from 'spaps-sdk'`),
+    chalk.gray(`  const spaps = new SPAPSClient()`),
+    '',
+    chalk.green('Common Methods:'),
+    '  await spaps.login(email, password)',
+    '  await spaps.register(email, password)',
+    '  await spaps.getUser()',
+    '  await spaps.createCheckoutSession(priceId, successUrl)',
+    '  await spaps.getSubscription()',
+    '  await spaps.getUsageBalance()',
+    '',
+    chalk.green('Helper Methods:'),
+    `  spaps.isAuthenticated()  ${chalk.gray('// Check auth status')}`,
+    `  spaps.isLocalMode()       ${chalk.gray('// Check if local mode')}`,
+    `  spaps.getAccessToken()    ${chalk.gray('// Get current token')}`,
+    '',
+    chalk.blue('📚 Full docs: npx spaps docs --interactive'),
+    '',
+  ].join('\n');
+
+  process.stdout.write(`${output}\n`);
+}
+
+module.exports = {
+  showQuickReference,
+};

package/src/docs-system.js

@@ -5,6 +5,7 @@
 
 const chalk = require('chalk');
 const prompts = require('prompts');
+const { showQuickReference } = require('./docs-quick');
 
 const SDK_DOCS = {
   quickstart: {
@@ -676,37 +677,6 @@ async function showInteractiveDocs() {
   }
 }
 
-function showQuickReference() {
-  console.log(chalk.yellow('\n🍠 SPAPS SDK Quick Reference\n'));
-  
-  console.log(chalk.green('Installation:'));
-  console.log('  npm install spaps-sdk');
-  console.log();
-  
-  console.log(chalk.green('Basic Setup:'));
-  console.log(chalk.gray(`  import { SPAPSClient } from 'spaps-sdk'`));
-  console.log(chalk.gray(`  const spaps = new SPAPSClient()`));
-  console.log();
-  
-  console.log(chalk.green('Common Methods:'));
-  console.log('  await spaps.login(email, password)');
-  console.log('  await spaps.register(email, password)');
-  console.log('  await spaps.getUser()');
-  console.log('  await spaps.createCheckoutSession(priceId, successUrl)');
-  console.log('  await spaps.getSubscription()');
-  console.log('  await spaps.getUsageBalance()');
-  console.log();
-  
-  console.log(chalk.green('Helper Methods:'));
-  console.log('  spaps.isAuthenticated()  ' + chalk.gray('// Check auth status'));
-  console.log('  spaps.isLocalMode()       ' + chalk.gray('// Check if local mode'));
-  console.log('  spaps.getAccessToken()    ' + chalk.gray('// Get current token'));
-  console.log();
-  
-  console.log(chalk.blue('📚 Full docs: npx spaps docs --interactive'));
-  console.log();
-}
-
 function searchDocs(query) {
   const results = [];
   const searchTerm = query.toLowerCase();

package/src/handlers.js

@@ -2,26 +2,30 @@ const chalk = require('chalk');
 const fs = require('fs');
 const { DEFAULT_PORT } = require('./config');
 const { handleError } = require('./error-handler');
-const { showInteractiveHelp, showQuickHelp } = require('./help-system');
-const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-system');
-const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
-const { buildToolSpec } = require('./ai-tool-spec');
-const { runDoctor } = require('./doctor');
-const { buildHomeView, renderHomeView } = require('./home-view');
-const {
-  applyFixtures,
-  exportStorageState,
-  initFixtureKernel,
-  resetFixtures,
-} = require('./fixture-kernel');
-const { createProjectStarter } = require('./project-scaffolder');
-const {
-  loginHandler,
-  logoutHandler,
-  whoamiHandler,
-  tokenHandler,
-} = require('./auth/handlers');
-const { callEndpoint, emit, emitAuthError } = require('./domain-cli');
+const { hasInteractiveTerminal } = require('./auth/env');
+const { showQuickHelp } = require('./help-quick');
+const { showQuickReference } = require('./docs-quick');
+
+function lazy(factory) {
+  let value;
+  return () => {
+    if (value === undefined) {
+      value = factory();
+    }
+    return value;
+  };
+}
+
+const loadHelpSystem = lazy(() => require('./help-system'));
+const loadDocsSystem = lazy(() => require('./docs-system'));
+const loadAiHelper = lazy(() => require('./ai-helper'));
+const loadAiToolSpec = lazy(() => require('./ai-tool-spec'));
+const loadDoctor = lazy(() => require('./doctor'));
+const loadHomeView = lazy(() => require('./home-view'));
+const loadFixtureKernel = lazy(() => require('./fixture-kernel'));
+const loadProjectScaffolder = lazy(() => require('./project-scaffolder'));
+const loadAuthCommandHandlers = lazy(() => require('./auth/handlers'));
+const loadDomainCli = lazy(() => require('./domain-cli'));
 
 function createHandlers(version, logo) {
   function invalidArgument(message) {
@@ -30,7 +34,14 @@ function createHandlers(version, logo) {
     return error;
   }
 
+  function emitInteractiveFallback(message) {
+    console.log(
+      chalk.yellow(`\n⚠️  ${message}. Showing the quick reference instead.\n`)
+    );
+  }
+
   const verifyHandler = async ({ options }) => {
+    const { runQuickTest } = loadAiHelper();
     const result = await runQuickTest({
       port: options.port,
       serverUrl: options.serverUrl,
@@ -65,6 +76,7 @@ function createHandlers(version, logo) {
 
   return {
     home: async ({ options }) => {
+      const { buildHomeView, renderHomeView } = loadHomeView();
       const view = await buildHomeView({
         port: options.port,
         serverUrl: options.serverUrl,
@@ -135,6 +147,7 @@ function createHandlers(version, logo) {
       }
     },
     quickstart: async ({ options }) => {
+      const { getQuickStartInstructions } = loadAiHelper();
       const instructions = await getQuickStartInstructions(options.port);
       if (options.json) {
         console.log(JSON.stringify(instructions, null, 2));
@@ -153,6 +166,7 @@ function createHandlers(version, logo) {
       }
     },
     status: async ({ options }) => {
+      const { getServerStatus } = loadAiHelper();
       const status = await getServerStatus(options.port);
       if (options.json) {
         console.log(JSON.stringify(status));
@@ -204,6 +218,7 @@ function createHandlers(version, logo) {
     },
     create: async ({ options }) => {
       const isJson = options.json;
+      const { createProjectStarter } = loadProjectScaffolder();
 
       try {
         const result = await createProjectStarter({
@@ -269,7 +284,12 @@ function createHandlers(version, logo) {
     },
     help: async ({ options }) => {
       if (options.interactive) {
-        await showInteractiveHelp();
+        if (!hasInteractiveTerminal()) {
+          emitInteractiveFallback('Interactive help requires a TTY');
+          showQuickHelp();
+          return;
+        }
+        await loadHelpSystem().showInteractiveHelp();
       } else if (options.quick) {
         showQuickHelp();
       } else {
@@ -278,7 +298,7 @@ function createHandlers(version, logo) {
     },
     docs: async ({ options }) => {
       if (options.search) {
-        const results = searchDocs(options.search);
+        const results = loadDocsSystem().searchDocs(options.search);
         if (options.json) {
           console.log(JSON.stringify({ results }, null, 2));
         } else {
@@ -296,12 +316,18 @@ function createHandlers(version, logo) {
           console.log(chalk.blue('  to browse full documentation\n'));
         }
       } else if (options.interactive) {
-        await showInteractiveDocs();
+        if (!hasInteractiveTerminal()) {
+          emitInteractiveFallback('Interactive docs require a TTY');
+          showQuickReference();
+          return;
+        }
+        await loadDocsSystem().showInteractiveDocs();
       } else {
         showQuickReference();
       }
     },
     tools: async ({ options }) => {
+      const { buildToolSpec } = loadAiToolSpec();
       const spec = await buildToolSpec({
         format: options.format || 'openai',
         port: options.port,
@@ -328,6 +354,12 @@ function createHandlers(version, logo) {
     },
     fixtures: async ({ options }) => {
       const isJson = options.json;
+      const {
+        applyFixtures,
+        exportStorageState,
+        initFixtureKernel,
+        resetFixtures,
+      } = loadFixtureKernel();
 
       try {
         if (options.format && options.format !== 'playwright') {
@@ -465,13 +497,14 @@ function createHandlers(version, logo) {
       }
     },
     doctor: async ({ options }) => {
+      const { runDoctor } = loadDoctor();
       await runDoctor({ port: options.port || DEFAULT_PORT, stripe: options.stripe || null, json: options.json });
     },
     test: verifyHandler,
-    login: loginHandler,
-    logout: logoutHandler,
-    whoami: whoamiHandler,
-    token: tokenHandler,
+    login: async (...args) => loadAuthCommandHandlers().loginHandler(...args),
+    logout: async (...args) => loadAuthCommandHandlers().logoutHandler(...args),
+    whoami: async (...args) => loadAuthCommandHandlers().whoamiHandler(...args),
+    token: async (...args) => loadAuthCommandHandlers().tokenHandler(...args),
     dayrate: dayrateHandler,
     email: emailHandler,
     policy: policyHandler,
@@ -481,6 +514,7 @@ function createHandlers(version, logo) {
 }
 
 function emitText({ intent, result, isJson, successMessage = null }) {
+  const { emit } = loadDomainCli();
   if (isJson) {
     emit({ intent, result, isJson, successMessage });
     return;
@@ -548,6 +582,7 @@ function assignIfDefined(target, key, value) {
 }
 
 async function dayrateHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   if (sub !== 'config') {
@@ -566,6 +601,7 @@ async function dayrateHandler({ options }) {
 }
 
 async function emailHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
 
@@ -777,6 +813,7 @@ async function emailHandler({ options }) {
 }
 
 async function policyHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   try {
@@ -832,6 +869,7 @@ async function policyHandler({ options }) {
 }
 
 async function webhookHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   try {
@@ -863,6 +901,7 @@ async function webhookHandler({ options }) {
 }
 
 async function issueReportsHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   if (sub !== 'list-mine') {

package/src/help-quick.js

@@ -0,0 +1,42 @@
+const chalk = require('chalk');
+
+function showQuickHelp() {
+  const output = [
+    '',
+    chalk.yellow('🍠 SPAPS Quick Reference'),
+    '',
+    chalk.green('Common Commands:'),
+    `  npx spaps local                  ${chalk.gray('# Start local server')}`,
+    `  npx spaps init                   ${chalk.gray('# Initialize in project')}`,
+    `  npx spaps create <name>          ${chalk.gray('# Scaffold a SPAPS starter project')}`,
+    `  npx spaps fixtures apply         ${chalk.gray('# Generate repo-local auth fixtures')}`,
+    `  npx spaps fixtures storage-state ${chalk.gray('# Export one persona artifact')}`,
+    `  npx spaps types                  ${chalk.gray('# Generate types (v0.4.0)')}`,
+    '',
+    chalk.green('Local Development:'),
+    `  npx spaps local --port 3001      ${chalk.gray('# Custom port')}`,
+    `  npx spaps local --open           ${chalk.gray('# Open browser')}`,
+    `  npx spaps local --json           ${chalk.gray('# JSON output')}`,
+    '',
+    chalk.green('SDK Usage:'),
+    `  npm install spaps-sdk            ${chalk.gray('# Install SDK')}`,
+    '',
+    chalk.gray('  import { SPAPSClient } from "spaps-sdk"'),
+    chalk.gray('  const spaps = new SPAPSClient()'),
+    chalk.gray('  await spaps.login(email, password)'),
+    '',
+    chalk.green('Debugging:'),
+    `  curl http://localhost:3301/health   ${chalk.gray('# Check server')}`,
+    `  npx spaps help --interactive         ${chalk.gray('# Interactive help')}`,
+    '',
+    chalk.blue('📚 Docs: https://sweetpotato.dev'),
+    chalk.blue('💬 Discord: https://discord.gg/sweetpotato'),
+    '',
+  ].join('\n');
+
+  process.stdout.write(`${output}\n`);
+}
+
+module.exports = {
+  showQuickHelp,
+};

package/src/help-system.js

@@ -7,6 +7,7 @@ const chalk = require('chalk');
 const prompts = require('prompts');
 
 const { DEFAULT_PORT } = require('./config');
+const { showQuickHelp } = require('./help-quick');
 
 const HELP_TREE = {
   root: {
@@ -448,42 +449,6 @@ async function showInteractiveHelp() {
   }
 }
 
-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('# Scaffold a SPAPS starter project'));
-  console.log('  npx spaps fixtures apply         ' + chalk.gray('# Generate repo-local auth fixtures'));
-  console.log('  npx spaps fixtures storage-state ' + chalk.gray('# Export one persona artifact'));
-  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:3301/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,