spaps 0.7.3 → 0.7.5

package/src/handlers.js

@@ -7,9 +7,27 @@ const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-
 const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
 const { buildToolSpec } = require('./ai-tool-spec');
 const { runDoctor } = require('./doctor');
+const {
+  applyFixtures,
+  exportStorageState,
+  initFixtureKernel,
+  resetFixtures,
+} = require('./fixture-kernel');
 const { createProjectStarter } = require('./project-scaffolder');
+const {
+  loginHandler,
+  logoutHandler,
+  whoamiHandler,
+  tokenHandler,
+} = require('./auth/handlers');
 
 function createHandlers(version, logo) {
+  function invalidArgument(message) {
+    const error = new Error(message);
+    error.code = 'EINVAL';
+    return error;
+  }
+
   return {
     local: async ({ options }) => {
       const isJson = options.json;
@@ -19,7 +37,13 @@ function createHandlers(version, logo) {
       if (options.stop) {
         try {
           const LocalServer = require('./local-server.js');
-          const server = new LocalServer({ json: isJson });
+          const server = new LocalServer({
+            port: options.port,
+            runtimeDir: options.runtimeDir,
+            runtimeSource: options.runtimeSource,
+            dataSource: options.dataSource,
+            json: isJson,
+          });
           server.stop();
           return;
         } catch (error) {
@@ -32,6 +56,9 @@ function createHandlers(version, logo) {
         const LocalServer = require('./local-server.js');
         const server = new LocalServer({
           port: options.port,
+          runtimeDir: options.runtimeDir,
+          runtimeSource: options.runtimeSource,
+          dataSource: options.dataSource,
           json: isJson,
           detach: options.detach,
           fresh: options.fresh,
@@ -48,23 +75,31 @@ function createHandlers(version, logo) {
         }
 
         // Set up shutdown handler
-        process.on('SIGINT', async () => {
+        const shutdown = async () => {
           await server.shutdown();
           process.exit(0);
-        });
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
       } catch (error) {
         handleError(error, { port: options.port, command: 'local' }, { json: isJson });
       }
     },
     quickstart: async ({ options }) => {
-      const instructions = getQuickStartInstructions(options.port);
+      const instructions = await getQuickStartInstructions(options.port);
       if (options.json) {
         console.log(JSON.stringify(instructions, null, 2));
       } else {
         console.log(chalk.yellow('\n🍠 SPAPS Quick Start Instructions\n'));
-        console.log('1. Install SDK: npm install spaps-sdk');
-        console.log('2. Create test file with the code above');
-        console.log('3. Run: node test-spaps.js');
+        const modeSummary = instructions.server.running
+          ? instructions.auth.local_mode
+            ? 'Mode: local mode active'
+            : 'Mode: provisioned application required'
+          : 'Mode: server unreachable';
+        console.log(modeSummary);
+        instructions.summary.forEach((line, index) => {
+          console.log(`${index + 1}. ${line}`);
+        });
         console.log('\nFor JSON output: npx spaps quickstart --json');
       }
     },
@@ -82,6 +117,12 @@ function createHandlers(version, logo) {
           console.log(chalk.green('\n✅ SPAPS server is running!\n'));
           console.log('  URL:', chalk.cyan(status.url));
           console.log('  Docs:', chalk.cyan(status.docs));
+          if (status.local_mode?.known) {
+            console.log(
+              '  Mode:',
+              chalk.cyan(status.local_mode.active ? 'local mode active' : 'application key required')
+            );
+          }
           console.log();
         }
       }
@@ -115,14 +156,15 @@ function createHandlers(version, logo) {
         console.log(chalk.cyan('  3. Start coding!'));
       }
     },
-    create: ({ options }) => {
+    create: async ({ options }) => {
       const isJson = options.json;
 
       try {
-        const result = createProjectStarter({
+        const result = await createProjectStarter({
           name: options.name,
           template: options.template,
           dir: options.dir,
+          port: options.port,
           force: options.force,
           version,
         });
@@ -134,6 +176,7 @@ function createHandlers(version, logo) {
 
         console.log(chalk.green(`\n✨ Created ${result.project_name} (${result.template})`));
         console.log(chalk.cyan(`   ${result.target_dir}`));
+        console.log(chalk.gray(`   provisioning: ${result.provisioning.status}`));
 
         if (result.files_created.length > 0) {
           console.log(chalk.green('\nFiles created:'));
@@ -149,6 +192,13 @@ function createHandlers(version, logo) {
           });
         }
 
+        if (result.warnings.length > 0) {
+          console.log(chalk.yellow('\nWarnings:'));
+          result.warnings.forEach((warning) => {
+            console.log(chalk.gray(`  • ${warning}`));
+          });
+        }
+
         console.log(chalk.green('\nNext steps:'));
         result.next_steps.forEach((step, index) => {
           console.log(chalk.cyan(`  ${index + 1}. ${step}`));
@@ -206,12 +256,22 @@ function createHandlers(version, logo) {
       }
     },
     tools: async ({ options }) => {
-      const spec = buildToolSpec({ format: options.format || 'openai', port: options.port });
+      const spec = await buildToolSpec({
+        format: options.format || 'openai',
+        port: options.port,
+        version,
+      });
       if (options.json) {
         console.log(JSON.stringify(spec, null, 2));
       } else {
         console.log(chalk.yellow('\n🍠 SPAPS AI Tool Spec (OpenAI-style)\n'));
         console.log('Base URL:', spec.base_url);
+        if (spec.auth && typeof spec.auth.local_mode === 'boolean') {
+          console.log(
+            'Auth:',
+            spec.auth.local_mode ? 'local mode active' : 'application key required'
+          );
+        }
         console.log('Tools:');
         spec.tools.forEach((t, i) => {
           console.log(chalk.green(`  ${i + 1}. ${t.name}`), '-', t.description);
@@ -220,9 +280,140 @@ function createHandlers(version, logo) {
         console.log('\nTip: npx spaps tools --json > spaps-tools.json');
       }
     },
+    fixtures: async ({ options }) => {
+      const isJson = options.json;
+
+      try {
+        if (options.format && options.format !== 'playwright') {
+          throw invalidArgument(`Unsupported fixture format "${options.format}". Only "playwright" is currently supported.`);
+        }
+
+        let result;
+        switch (options.subcommand) {
+          case 'init':
+            result = await initFixtureKernel({
+              dir: options.dir,
+              port: options.port,
+              baseUrl: options.baseUrl,
+              version,
+              force: options.force,
+            });
+            break;
+          case 'apply':
+            result = await applyFixtures({
+              dir: options.dir,
+              port: options.port,
+              baseUrl: options.baseUrl,
+              version,
+            });
+            break;
+          case 'reset':
+            result = await resetFixtures({
+              dir: options.dir,
+              port: options.port,
+              baseUrl: options.baseUrl,
+              version,
+            });
+            break;
+          case 'storage-state':
+            if (!options.persona) {
+              throw invalidArgument('The fixtures storage-state command requires --persona.');
+            }
+            result = await exportStorageState({
+              dir: options.dir,
+              port: options.port,
+              baseUrl: options.baseUrl,
+              version,
+              persona: options.persona,
+            });
+            break;
+          default:
+            throw invalidArgument(
+              `Unsupported fixtures subcommand "${options.subcommand}". Use init, apply, reset, or storage-state.`
+            );
+        }
+
+        if (isJson) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log(chalk.green(`\n✨ .spaps fixtures ${result.subcommand} complete`));
+        console.log(chalk.cyan(`   ${result.fixture_dir}`));
+
+        if (Array.isArray(result.files_created) && result.files_created.length > 0) {
+          console.log(chalk.green('\nFiles created:'));
+          result.files_created.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        if (Array.isArray(result.files_overwritten) && result.files_overwritten.length > 0) {
+          console.log(chalk.yellow('\nFiles overwritten:'));
+          result.files_overwritten.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        if (Array.isArray(result.removed) && result.removed.length > 0) {
+          console.log(chalk.yellow('\nRemoved stale artifacts:'));
+          result.removed.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        if (result.generated?.personas?.length) {
+          console.log(chalk.green('\nGenerated personas:'));
+          result.generated.personas.forEach((entry) => {
+            console.log(chalk.gray(`  • ${entry.persona}`));
+            console.log(chalk.gray(`    storageState: ${entry.storage_state_path}`));
+            console.log(chalk.gray(`    headers:      ${entry.headers_path}`));
+          });
+        }
+
+        if (result.generated?.bridge?.script_path) {
+          console.log(chalk.green('\nFrontend bridge:'));
+          console.log(chalk.gray(`  script: ${result.generated.bridge.script_path}`));
+          console.log(chalk.gray(`  include: <script src="${result.generated.bridge.public_url}"></script>`));
+        }
+
+        if (result.storage_state_path) {
+          console.log(chalk.green('\nStorage state:'));
+          console.log(chalk.gray(`  ${result.storage_state_path}`));
+          console.log(chalk.gray(`  headers: ${result.headers_path}`));
+        }
+
+        if (result.bridge?.script_path) {
+          console.log(chalk.green('\nFrontend bridge:'));
+          console.log(chalk.gray(`  script: ${result.bridge.script_path}`));
+          console.log(chalk.gray(`  include: <script src="${result.bridge.public_url}"></script>`));
+        }
+
+        console.log(chalk.green('\nNext steps:'));
+        (result.next_steps || []).forEach((step, index) => {
+          console.log(chalk.cyan(`  ${index + 1}. ${step}`));
+        });
+        console.log();
+      } catch (error) {
+        handleError(
+          error,
+          {
+            command: 'fixtures',
+            subcommand: options.subcommand,
+            dir: options.dir,
+            persona: options.persona,
+          },
+          { json: isJson }
+        );
+      }
+    },
     doctor: async ({ options }) => {
       await runDoctor({ port: options.port || DEFAULT_PORT, stripe: options.stripe || null, json: options.json });
-    }
+    },
+    login: loginHandler,
+    logout: logoutHandler,
+    whoami: whoamiHandler,
+    token: tokenHandler,
   };
 }
 

package/src/help-system.js

@@ -455,6 +455,8 @@ function showQuickHelp() {
   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();
   

package/src/local-runtime.js

@@ -0,0 +1,258 @@
+const axios = require('axios');
+
+const { DEFAULT_PORT } = require('./config');
+
+const REQUEST_TIMEOUT_MS = 1200;
+
+function buildBaseUrl(port = DEFAULT_PORT) {
+  return `http://localhost:${port}`;
+}
+
+function buildDocsUrl(port = DEFAULT_PORT) {
+  return `${buildBaseUrl(port)}/docs`;
+}
+
+function unwrapEnvelope(payload) {
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    payload.success === true &&
+    Object.prototype.hasOwnProperty.call(payload, 'data')
+  ) {
+    return payload.data;
+  }
+
+  return payload;
+}
+
+function extractError(payload, status) {
+  if (payload && typeof payload === 'object') {
+    if (payload.error && typeof payload.error === 'object') {
+      return {
+        code: payload.error.code || `HTTP_${status}`,
+        message: payload.error.message || `Request failed with status ${status}`,
+      };
+    }
+
+    return {
+      code: payload.code || payload.error || `HTTP_${status}`,
+      message: payload.message || payload.detail || `Request failed with status ${status}`,
+    };
+  }
+
+  return {
+    code: `HTTP_${status}`,
+    message: `Request failed with status ${status}`,
+  };
+}
+
+async function requestJson({ method, url, data = null, headers = {}, timeoutMs = REQUEST_TIMEOUT_MS }) {
+  try {
+    const response = await axios({
+      method,
+      url,
+      data,
+      headers,
+      timeout: timeoutMs,
+      validateStatus: () => true,
+    });
+
+    const ok = response.status >= 200 && response.status < 300;
+
+    return {
+      ok,
+      status: response.status,
+      raw: response.data,
+      data: unwrapEnvelope(response.data),
+      error: ok ? null : extractError(response.data, response.status),
+      network_error: false,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: null,
+      raw: null,
+      data: null,
+      error: {
+        code: error.code || 'REQUEST_FAILED',
+        message: error.message || 'Request failed',
+      },
+      network_error: true,
+    };
+  }
+}
+
+async function getServerRuntime({ port = DEFAULT_PORT, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  const url = buildBaseUrl(port);
+  const docs = buildDocsUrl(port);
+
+  const health = await requestJson({
+    method: 'GET',
+    url: `${url}/health`,
+    timeoutMs,
+  });
+
+  if (!health.ok) {
+    return {
+      running: false,
+      port,
+      url,
+      docs,
+      message: health.network_error ? 'Server not running' : 'Health endpoint returned an error',
+      start_command: `npx spaps local --port ${port}`,
+      error: health.error,
+    };
+  }
+
+  const localMode = await requestJson({
+    method: 'GET',
+    url: `${url}/health/local-mode`,
+    timeoutMs,
+  });
+
+  const localModeData = localMode.ok && localMode.data && typeof localMode.data === 'object'
+    ? localMode.data
+    : null;
+
+  return {
+    running: true,
+    port,
+    url,
+    docs,
+    health: health.data || health.raw,
+    local_mode: {
+      known: localMode.ok,
+      active: localModeData ? Boolean(localModeData.local_mode_active) : null,
+      environment: localModeData?.environment || null,
+      spaps_local_mode_env:
+        typeof localModeData?.spaps_local_mode_env === 'boolean'
+          ? localModeData.spaps_local_mode_env
+          : null,
+      test_users: Array.isArray(localModeData?.test_users) ? localModeData.test_users : [],
+      test_application: localModeData?.test_application || null,
+      hints: localModeData?.hints || {},
+      raw: localModeData,
+    },
+  };
+}
+
+function readSelfServicePassword() {
+  return process.env.SELF_SERVICE_PASSWORD || process.env.SELF_SERVICE_ADMIN_PASSWORD || '';
+}
+
+async function provisionStarterApplication({
+  port = DEFAULT_PORT,
+  name,
+  slug,
+  blueprintKey,
+  allowedOrigins = [],
+}) {
+  const runtime = await getServerRuntime({ port });
+
+  if (!runtime.running) {
+    return {
+      status: 'scaffold_only',
+      reason: 'server_unreachable',
+      runtime,
+      warnings: [
+        `Local server was unreachable at ${runtime.url}. Starter files were created without provisioning.`,
+      ],
+    };
+  }
+
+  if (runtime.local_mode.active) {
+    return {
+      status: 'local_mode',
+      reason: null,
+      runtime,
+      application: {
+        id: runtime.local_mode.test_application?.id || null,
+        slug: runtime.local_mode.test_application?.slug || slug,
+      },
+      warnings: [
+        `Local mode is active on ${runtime.url}. Starter files were created without provisioning because API key validation is bypassed.`,
+      ],
+    };
+  }
+
+  const password = readSelfServicePassword();
+  if (!password) {
+    return {
+      status: 'scaffold_only',
+      reason: 'self_service_password_missing',
+      runtime,
+      warnings: [
+        `The server at ${runtime.url} requires a provisioned application key. Set SELF_SERVICE_PASSWORD and re-run this command to provision one automatically.`,
+      ],
+    };
+  }
+
+  const auth = await requestJson({
+    method: 'POST',
+    url: `${runtime.url}/api/self-service/auth`,
+    data: { password },
+  });
+
+  if (!auth.ok || !auth.data?.token) {
+    return {
+      status: 'scaffold_only',
+      reason: 'self_service_auth_failed',
+      runtime,
+      warnings: [
+        `Self-service authentication failed: ${auth.error?.message || 'no token returned'}. Starter files were created without provisioning.`,
+      ],
+      error: auth.error,
+    };
+  }
+
+  const creation = await requestJson({
+    method: 'POST',
+    url: `${runtime.url}/api/self-service/applications`,
+    headers: {
+      Authorization: `Bearer ${auth.data.token}`,
+    },
+    data: {
+      name,
+      slug,
+      blueprint_key: blueprintKey,
+      allowed_origins: allowedOrigins,
+    },
+  });
+
+  if (!creation.ok || !creation.data?.application) {
+    return {
+      status: 'scaffold_only',
+      reason: 'application_provision_failed',
+      runtime,
+      warnings: [
+        `Application provisioning failed: ${creation.error?.message || 'unexpected response'}. Starter files were created without provisioning.`,
+      ],
+      error: creation.error,
+    };
+  }
+
+  return {
+    status: 'provisioned',
+    reason: null,
+    runtime,
+    application: {
+      id: creation.data.application.id,
+      slug: creation.data.application.slug,
+    },
+    keys: {
+      publishable: creation.data.publishable_key || null,
+      secret: creation.data.secret_key || creation.data.api_key || null,
+    },
+    warnings: [],
+  };
+}
+
+module.exports = {
+  buildBaseUrl,
+  buildDocsUrl,
+  getServerRuntime,
+  provisionStarterApplication,
+  readSelfServicePassword,
+  requestJson,
+  unwrapEnvelope,
+};