spaps 0.7.3 → 0.7.5

package/src/ai-helper.js

@@ -1,273 +1,215 @@
-/**
- * SPAPS AI Agent Helper
- * Provides AI-friendly outputs and quick commands
- */
-
-const chalk = require('chalk');
-
 const { DEFAULT_PORT } = require('./config');
+const { getServerRuntime, readSelfServicePassword } = require('./local-runtime');
+
+function buildProvisioningCommand(template, port) {
+  return `SELF_SERVICE_PASSWORD=your-password npx spaps create demo-${template === 'node' ? 'api' : 'app'} --template ${template} --port ${port}`;
+}
 
-function getQuickStartInstructions(port = DEFAULT_PORT) {
+function buildLocalModeInstructions(runtime) {
   return {
     success: true,
+    server: {
+      running: true,
+      url: runtime.url,
+      docs: runtime.docs,
+      local_mode_active: true,
+      environment: runtime.local_mode.environment,
+      spaps_local_mode_env: runtime.local_mode.spaps_local_mode_env,
+    },
+    auth: {
+      local_mode: true,
+      api_key_required: false,
+      mode_source: '/health/local-mode',
+      test_users: runtime.local_mode.test_users,
+      test_application: runtime.local_mode.test_application,
+      hints: runtime.local_mode.hints,
+    },
+    summary: [
+      'Install the SDK with `npm install spaps-sdk`.',
+      `Point the client at ${runtime.url}.`,
+      'Use the local-mode hints from `/health/local-mode` if you need a specific test persona.',
+    ],
     instructions: {
-      step1: {
-        description: "Install SDK",
-        command: "npm install spaps-sdk",
-        verify: "npm list spaps-sdk"
+      install_sdk: {
+        description: 'Install the SDK',
+        command: 'npm install spaps-sdk',
       },
-      step2: {
-        description: "Create test file",
-        filename: "test-spaps.js",
-        content: `const { SweetPotatoSDK } = require('spaps-sdk');
-
-async function test() {
-  const sdk = new SweetPotatoSDK({ apiUrl: 'http://localhost:${port}' });
+      create_client: {
+        description: 'Create a client for local mode',
+        filename: 'test-spaps.js',
+        content: `const { SPAPSClient } = require('spaps-sdk');
 
-  // Test email/password auth (local mode accepts any credentials)
-  const auth = await sdk.auth.signInWithPassword({ email: 'test@example.com', password: 'password' });
-  console.log('✅ Login successful:', auth.user.email);
+const spaps = new SPAPSClient({ apiUrl: '${runtime.url}' });
 
-  // Test authenticated request
-  const user = await sdk.auth.getCurrentUser();
-  console.log('✅ Got user:', user.email);
-
-  return { success: true, user };
+async function main() {
+  const status = await fetch('${runtime.url}/health/local-mode').then((res) => res.json());
+  console.log(status.data);
 }
 
-test().then(console.log).catch(console.error);`
+main().catch(console.error);
+`,
+      },
+      verify_server: {
+        description: 'Confirm local mode status',
+        command: `curl -s ${runtime.url}/health/local-mode | jq '.'`,
       },
-      step3: {
-        description: "Run test",
-        command: "node test-spaps.js",
-        expected_output: {
-          success: true,
-          user: {
-            id: "00000000-0000-0000-0000-000000000002",
-            email: "test@example.com"
-          }
-        }
-      }
     },
-    endpoints: [
-      {
-        method: "POST",
-        path: "/api/auth/login",
-        body: { email: "string", password: "string" },
-        response: { access_token: "string", refresh_token: "string", user: "object" }
+  };
+}
+
+function buildProvisionedModeInstructions(runtime, port) {
+  const hasPassword = Boolean(readSelfServicePassword());
+
+  return {
+    success: true,
+    server: {
+      running: true,
+      url: runtime.url,
+      docs: runtime.docs,
+      local_mode_active: false,
+      environment: runtime.local_mode.environment,
+      spaps_local_mode_env: runtime.local_mode.spaps_local_mode_env,
+    },
+    auth: {
+      local_mode: false,
+      api_key_required: true,
+      mode_source: '/health/local-mode',
+      header: 'X-API-Key',
+      env: 'SPAPS_API_KEY',
+      self_service_password_env: 'SELF_SERVICE_PASSWORD',
+    },
+    summary: [
+      'Install the SDK with `npm install spaps-sdk`.',
+      'Provision a local application before testing authenticated flows.',
+      `Send \`X-API-Key\` when /health/local-mode reports \`local_mode_active: false\`.`,
+    ],
+    instructions: {
+      install_sdk: {
+        description: 'Install the SDK',
+        command: 'npm install spaps-sdk',
       },
-      {
-        method: "POST",
-        path: "/api/auth/register",
-        body: { email: "string", password: "string" },
-        response: { access_token: "string", refresh_token: "string", user: "object" }
+      provision_app: {
+        description: hasPassword
+          ? 'Provision a local browser app'
+          : 'Set SELF_SERVICE_PASSWORD, then provision a local browser app',
+        command: buildProvisioningCommand('react', port),
       },
-      {
-        method: "GET",
-        path: "/api/auth/user",
-        headers: { Authorization: "Bearer TOKEN" },
-        response: { id: "string", email: "string", role: "string" }
+      create_client: {
+        description: 'Create a client that uses a provisioned key',
+        filename: 'test-spaps.js',
+        content: `const { createServerClient } = require('spaps-sdk');
+
+const apiUrl = process.env.SPAPS_API_URL || '${runtime.url}';
+const apiKey = process.env.SPAPS_API_KEY;
+
+if (!apiKey) {
+  throw new Error('Set SPAPS_API_KEY before testing against a non-local-mode server.');
+}
+
+const spaps = createServerClient(apiKey, { apiUrl });
+
+async function main() {
+  const result = await spaps.auth.signInWithPassword({
+    email: 'user@example.com',
+    password: 'correct-horse-battery-staple',
+  });
+  console.log(result.user.id);
+}
+
+main().catch(console.error);
+`,
       },
-      {
-        method: "POST",
-        path: "/api/stripe/checkout-sessions",
-        body: { price_id: "string", success_url: "string", cancel_url: "string" },
-        response: { id: "string", url: "string", status: "string" }
+      verify_server: {
+        description: 'Confirm whether the server is in local mode',
+        command: `curl -s ${runtime.url}/health/local-mode | jq '.'`,
       },
-      {
-        method: "GET",
-        path: "/api/usage/balance",
-        headers: { Authorization: "Bearer TOKEN" },
-        response: { balance: "number", currency: "string" }
-      }
-    ],
-    test_commands: {
-      health_check: `curl http://localhost:${port}/health`,
-      login: `curl -X POST http://localhost:${port}/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@example.com","password":"password"}'`,
-      with_sdk: `node -e "const {SweetPotatoSDK}=require('spaps-sdk');const sdk=new SweetPotatoSDK({apiUrl:'http://localhost:${port}'});sdk.auth.signInWithPassword({email:'test@example.com',password:'password'}).then(r=>console.log(JSON.stringify(r.user))).catch(console.error)"`
-    }
+    },
   };
 }
 
-function getServerStatus(port = DEFAULT_PORT) {
-  const http = require('http');
-  
-  return new Promise((resolve) => {
-    const options = {
-      hostname: 'localhost',
-      port: port,
-      path: '/health',
-      method: 'GET',
-      timeout: 1000
-    };
-    
-    const req = http.request(options, (res) => {
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => {
-        try {
-          const parsed = JSON.parse(data);
-          resolve({
-            running: true,
-            port: port,
-            health: parsed,
-            url: `http://localhost:${port}`,
-            docs: `http://localhost:${port}/docs`
-          });
-        } catch {
-          resolve({ running: true, port: port, error: 'Invalid response' });
-        }
-      });
-    });
-    
-    req.on('error', () => {
-      resolve({
-        running: false,
-        port: port,
-        message: 'Server not running',
-        start_command: `npx spaps local --port ${port}`
-      });
-    });
-    
-    req.on('timeout', () => {
-      req.destroy();
-      resolve({
-        running: false,
-        port: port,
-        message: 'Server timeout',
-        start_command: `npx spaps local --port ${port}`
-      });
-    });
-    
-    req.end();
-  });
-}
+async function getQuickStartInstructions(port = DEFAULT_PORT) {
+  const runtime = await getServerRuntime({ port });
 
-async function runQuickTest(port = 3301) {
-  const results = [];
-  
-  // Check server
-  const status = await getServerStatus(port);
-  results.push({
-    test: 'server_status',
-    success: status.running,
-    details: status
-  });
-  
-  if (!status.running) {
+  if (!runtime.running) {
     return {
       success: false,
-      message: 'Server not running',
-      fix: `npx spaps local --port ${port}`,
-      results
+      server: runtime,
+      summary: [
+        `Start the local server with \`npx spaps local --port ${port}\`.`,
+        'Provision a starter application after the server is healthy.',
+      ],
+      instructions: {
+        start_server: {
+          description: 'Start the local server',
+          command: `npx spaps local --port ${port}`,
+        },
+      },
     };
   }
-  
-  // Try HTTP request
-  try {
-    const http = require('http');
-    const loginResult = await new Promise((resolve, reject) => {
-      const postData = JSON.stringify({
-        email: 'test@example.com',
-        password: 'password'
-      });
-      
-      const options = {
-        hostname: 'localhost',
-        port: port,
-        path: '/api/auth/login',
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Content-Length': Buffer.byteLength(postData)
-        }
-      };
-      
-      const req = http.request(options, (res) => {
-        let data = '';
-        res.on('data', chunk => data += chunk);
-        res.on('end', () => {
-          try {
-            resolve(JSON.parse(data));
-          } catch {
-            reject(new Error('Invalid JSON response'));
-          }
-        });
-      });
-      
-      req.on('error', reject);
-      req.write(postData);
-      req.end();
-    });
-    
-    results.push({
-      test: 'login_endpoint',
-      success: true,
-      response: loginResult
-    });
-  } catch (error) {
-    results.push({
-      test: 'login_endpoint',
+
+  if (runtime.local_mode.active) {
+    return buildLocalModeInstructions(runtime);
+  }
+
+  return buildProvisionedModeInstructions(runtime, port);
+}
+
+async function getServerStatus(port = DEFAULT_PORT) {
+  return getServerRuntime({ port });
+}
+
+async function runQuickTest(port = DEFAULT_PORT) {
+  const runtime = await getServerRuntime({ port });
+  const results = [
+    {
+      test: 'server_status',
+      success: runtime.running,
+      details: runtime,
+    },
+  ];
+
+  if (!runtime.running) {
+    return {
       success: false,
-      error: error.message
-    });
+      summary: '0/1 tests passed',
+      results,
+      next_steps: [`Start the server with: npx spaps local --port ${port}`],
+    };
   }
-  
-  // Check SDK availability
-  try {
-    require.resolve('spaps-sdk');
-    results.push({
-      test: 'sdk_installed',
-      success: true,
-      message: 'spaps-sdk is installed'
-    });
-    
-    // Try SDK login
-    try {
-      const { SPAPSClient } = require('spaps-sdk');
-      const spaps = new SPAPSClient({ apiUrl: `http://localhost:${port}` });
-      const { data } = await spaps.login('test@example.com', 'password');
-      
-      results.push({
-        test: 'sdk_login',
-        success: true,
-        user: data.user
-      });
-    } catch (error) {
-      results.push({
-        test: 'sdk_login',
-        success: false,
-        error: error.message
-      });
-    }
-  } catch {
+
+  results.push({
+    test: 'local_mode_contract',
+    success: runtime.local_mode.known,
+    details: runtime.local_mode,
+    fix: runtime.local_mode.known ? null : `curl -s ${runtime.url}/health/local-mode`,
+  });
+
+  if (!runtime.local_mode.active) {
+    const hasKey = Boolean(process.env.SPAPS_API_KEY);
     results.push({
-      test: 'sdk_installed',
-      success: false,
-      message: 'spaps-sdk not installed',
-      fix: 'npm install spaps-sdk'
+      test: 'api_key_wiring',
+      success: hasKey,
+      message: hasKey
+        ? 'SPAPS_API_KEY is set for non-local-mode testing'
+        : 'SPAPS_API_KEY is required when local mode is disabled',
+      fix: hasKey ? null : buildProvisioningCommand('node', port),
     });
   }
-  
-  const allSuccess = results.every(r => r.success);
-  
+
+  const allSuccess = results.every((result) => result.success);
+
   return {
     success: allSuccess,
-    summary: `${results.filter(r => r.success).length}/${results.length} tests passed`,
+    summary: `${results.filter((result) => result.success).length}/${results.length} tests passed`,
     results,
-    next_steps: allSuccess ? [
-      'Server is running and SDK is working',
-      'You can now use SPAPS in your application',
-      'See docs at http://localhost:' + port + '/docs'
-    ] : [
-      'Fix the failing tests above',
-      'Run: npx spaps test --json to retry'
-    ]
+    next_steps: allSuccess
+      ? [`See docs at ${runtime.docs}`]
+      : ['Fix the failing checks above and re-run: npx spaps test --json'],
   };
 }
 
 module.exports = {
   getQuickStartInstructions,
   getServerStatus,
-  runQuickTest
+  runQuickTest,
 };

package/src/ai-tool-spec.js

@@ -1,12 +1,13 @@
 /**
  * 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)
+ * - Derives auth expectations from the running local server when available
  */
 
 const { DEFAULT_PORT } = require('./config');
 const fs = require('fs');
 const path = require('path');
+const { getServerRuntime } = require('./local-runtime');
 
 function tryLoadManifest() {
   const candidates = [
@@ -41,24 +42,54 @@ function tryLoadOpenAPI() {
   return null;
 }
 
-function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
+function buildAuthSection(runtime) {
+  if (!runtime.running) {
+    return {
+      local_mode: false,
+      mode_source: '/health/local-mode',
+      api_key_required: true,
+      header: 'X-API-Key',
+      env: 'SPAPS_API_KEY',
+      status: 'server_unreachable',
+    };
+  }
+
+  return {
+    local_mode: Boolean(runtime.local_mode.active),
+    mode_source: '/health/local-mode',
+    api_key_required: !runtime.local_mode.active,
+    header: 'X-API-Key',
+    env: 'SPAPS_API_KEY',
+    environment: runtime.local_mode.environment,
+    spaps_local_mode_env: runtime.local_mode.spaps_local_mode_env,
+    ...(runtime.local_mode.active
+      ? {
+          test_users: runtime.local_mode.test_users,
+          test_application: runtime.local_mode.test_application,
+          hints: runtime.local_mode.hints,
+        }
+      : {
+          self_service_password_env: 'SELF_SERVICE_PASSWORD',
+        }),
+  };
+}
+
+async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0' } = {}) {
   const baseUrl = `http://localhost:${port}`;
+  const runtime = await getServerRuntime({ port });
+  const auth = buildAuthSection(runtime);
   const spec = {
     name: 'spaps',
-    version: '0.1.0',
-    description: 'Auth + payments via SPAPS (local by default). Start with: npx spaps local',
+    version,
+    description: 'Auth + payments via SPAPS. Resolve local auth requirements from /health/local-mode.',
     base_url: baseUrl,
-    auth: {
-      local_mode: true,
-      production: {
-        header: 'X-API-Key',
-        env: 'SPAPS_API_KEY'
-      }
-    },
+    auth,
     tools: [
       {
         name: 'login',
-        description: 'Login with email/password. Local mode accepts any values.',
+        description: auth.local_mode
+          ? 'Authenticate a local test user. API key validation is bypassed while local mode is active.'
+          : 'Authenticate a user with email/password for a provisioned application. Send X-API-Key when local mode is disabled.',
         method: 'POST',
         path: '/api/auth/login',
         parameters: {
@@ -72,7 +103,9 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
       },
       {
         name: 'register',
-        description: 'Register a new user with email/password.',
+        description: auth.local_mode
+          ? 'Register a user while local mode is active.'
+          : 'Register a new user with email/password for a provisioned application.',
         method: 'POST',
         path: '/api/auth/register',
         parameters: {
@@ -86,7 +119,7 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
       },
       {
         name: 'get_current_user',
-        description: 'Get the currently authenticated user. Uses bearer token from previous login.',
+        description: 'Get the currently authenticated user. Uses the bearer token from a previous login.',
         method: 'GET',
         path: '/api/auth/user',
         parameters: {
@@ -98,7 +131,7 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
       },
       {
         name: 'create_checkout_session',
-        description: 'Create a Stripe Checkout session. In local mode uses Stripe test or mock based on USE_REAL_STRIPE.',
+        description: 'Create a Stripe Checkout session against the configured SPAPS server.',
         method: 'POST',
         path: '/api/stripe/checkout-sessions',
         parameters: {
@@ -116,7 +149,7 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
       },
       {
         name: 'list_products',
-        description: 'List products (Stripe-backed or local).',
+        description: 'List products exposed by the SPAPS server.',
         method: 'GET',
         path: '/api/stripe/products',
         parameters: {
@@ -129,7 +162,7 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
       },
       {
         name: 'request_magic_link',
-        description: 'Send a magic link for passwordless login (local mode simulates delivery).',
+        description: 'Send a magic link for passwordless login.',
         method: 'POST',
         path: '/api/auth/magic-link',
         parameters: {
@@ -254,7 +287,6 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
             }
           }
           if (Object.keys(responses).length) {
-            // Merge with default errors for completeness
             const merged = { ...defaultErrors, ...responses };
             t.responses = merged;
           }
@@ -287,11 +319,11 @@ function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
   return spec;
 }
 
-function buildToolSpec({ format = 'openai', port = DEFAULT_PORT } = {}) {
+async function buildToolSpec({ format = 'openai', port = DEFAULT_PORT, version = '0.0.0' } = {}) {
   switch (format) {
     case 'openai':
     default:
-      return buildOpenAIToolSpec({ port });
+      return buildOpenAIToolSpec({ port, version });
   }
 }