spaps 0.7.3 → 0.7.4

package/src/project-scaffolder.js

@@ -2,18 +2,27 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { DEFAULT_PORT } = require('./config');
+const { provisionStarterApplication } = require('./local-runtime');
 
 const SUPPORTED_TEMPLATES = {
   nextjs: {
     label: 'Next.js starter',
     blueprintKey: 'browser_auth',
     allowedOrigins: ['http://localhost:3000'],
+    publicApiUrlEnv: 'NEXT_PUBLIC_SPAPS_API_URL',
+    publicApiKeyEnv: 'NEXT_PUBLIC_SPAPS_API_KEY',
     files: ({ apiUrl }) => ({
-      'lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+      'lib/spaps.ts': `import { createBrowserClient, SPAPSClient } from 'spaps-sdk';
 
-export const spaps = new SPAPSClient({
-  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || '${apiUrl}',
-});
+const apiUrl = process.env.NEXT_PUBLIC_SPAPS_API_URL || '${apiUrl}';
+const apiKey = process.env.NEXT_PUBLIC_SPAPS_API_KEY;
+
+export const spaps = apiKey && apiKey.startsWith('spaps_pub_')
+  ? createBrowserClient(apiKey, { apiUrl })
+  : new SPAPSClient({
+      apiUrl,
+      ...(apiKey ? { apiKey } : {}),
+    });
 `,
       'app/providers.tsx': `'use client';
 
@@ -31,12 +40,20 @@ export function Providers({ children }: PropsWithChildren) {
     label: 'React + Vite starter',
     blueprintKey: 'browser_auth',
     allowedOrigins: ['http://localhost:5173'],
+    publicApiUrlEnv: 'VITE_SPAPS_API_URL',
+    publicApiKeyEnv: 'VITE_SPAPS_API_KEY',
     files: ({ apiUrl }) => ({
-      'src/lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+      'src/lib/spaps.ts': `import { createBrowserClient, SPAPSClient } from 'spaps-sdk';
+
+const apiUrl = import.meta.env.VITE_SPAPS_API_URL || '${apiUrl}';
+const apiKey = import.meta.env.VITE_SPAPS_API_KEY;
 
-export const spaps = new SPAPSClient({
-  apiUrl: import.meta.env.VITE_SPAPS_API_URL || '${apiUrl}',
-});
+export const spaps = apiKey && apiKey.startsWith('spaps_pub_')
+  ? createBrowserClient(apiKey, { apiUrl })
+  : new SPAPSClient({
+      apiUrl,
+      ...(apiKey ? { apiKey } : {}),
+    });
 `,
     }),
   },
@@ -44,13 +61,17 @@ export const spaps = new SPAPSClient({
     label: 'Node.js starter',
     blueprintKey: 'default',
     allowedOrigins: [],
+    publicApiUrlEnv: 'SPAPS_API_URL',
+    publicApiKeyEnv: 'SPAPS_API_KEY',
     files: ({ apiUrl }) => ({
-      'src/spaps.js': `const { SPAPSClient } = require('spaps-sdk');
+      'src/spaps.js': `const { createServerClient, SPAPSClient } = require('spaps-sdk');
+
+const apiUrl = process.env.SPAPS_API_URL || '${apiUrl}';
+const apiKey = process.env.SPAPS_API_KEY;
 
-const spaps = new SPAPSClient({
-  apiUrl: process.env.SPAPS_API_URL || '${apiUrl}',
-  apiKey: process.env.SPAPS_API_KEY,
-});
+const spaps = apiKey
+  ? createServerClient(apiKey, { apiUrl })
+  : new SPAPSClient({ apiUrl });
 
 module.exports = { spaps };
 `,
@@ -60,12 +81,20 @@ module.exports = { spaps };
     label: 'Vanilla JavaScript starter',
     blueprintKey: 'browser_auth',
     allowedOrigins: ['http://localhost:8080'],
+    publicApiUrlEnv: 'SPAPS_API_URL',
+    publicApiKeyEnv: 'SPAPS_API_KEY',
     files: ({ apiUrl }) => ({
-      'src/spaps.js': `import { SPAPSClient } from 'spaps-sdk';
+      'src/spaps.js': `import { createBrowserClient, SPAPSClient } from 'spaps-sdk';
+
+const apiUrl = window.SPAPS_API_URL || '${apiUrl}';
+const apiKey = window.SPAPS_API_KEY;
 
-export const spaps = new SPAPSClient({
-  apiUrl: '${apiUrl}',
-});
+export const spaps = apiKey && apiKey.startsWith('spaps_pub_')
+  ? createBrowserClient(apiKey, { apiUrl })
+  : new SPAPSClient({
+      apiUrl,
+      ...(apiKey ? { apiKey } : {}),
+    });
 `,
     }),
   },
@@ -115,6 +144,12 @@ function ensureWritableTarget(targetDir, force) {
   }
 }
 
+function prepareWritableTarget(targetDir, force) {
+  ensureWritableTarget(targetDir, force);
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.accessSync(targetDir, fs.constants.W_OK);
+}
+
 function writeManagedFile(targetDir, relativePath, content, bookkeeping) {
   const fullPath = path.join(targetDir, relativePath);
   fs.mkdirSync(path.dirname(fullPath), { recursive: true });
@@ -146,7 +181,7 @@ function buildPackageJson(name, template) {
   return `${JSON.stringify(pkg, null, 2)}\n`;
 }
 
-function buildContract({ name, slug, template, version, apiUrl, docsUrl }) {
+function buildContract({ name, slug, template, version, apiUrl, docsUrl, provisioning }) {
   const templateDef = SUPPORTED_TEMPLATES[template];
   const contract = {
     name,
@@ -157,12 +192,20 @@ function buildContract({ name, slug, template, version, apiUrl, docsUrl }) {
       local: {
         api_url: apiUrl,
         docs_url: docsUrl,
+        local_mode_active: provisioning.runtime?.local_mode?.active ?? null,
       },
       application: {
+        id: provisioning.application?.id || null,
         slug,
         blueprint_key: templateDef.blueprintKey,
         allowed_origins: templateDef.allowedOrigins,
-        provisioning_status: 'local_starter_only',
+        provisioning_status: provisioning.status,
+        provisioned_via:
+          provisioning.status === 'provisioned'
+            ? 'self_service'
+            : provisioning.status === 'local_mode'
+              ? 'local_mode'
+              : null,
       },
     },
   };
@@ -170,25 +213,73 @@ function buildContract({ name, slug, template, version, apiUrl, docsUrl }) {
   return `${JSON.stringify(contract, null, 2)}\n`;
 }
 
-function buildEnvFile(template, apiUrl) {
+function buildEnvFile(template, apiUrl, provisioning) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
   const lines = [
     '# SPAPS local development',
     `SPAPS_API_URL=${apiUrl}`,
-    '# SPAPS_API_KEY=',
   ];
 
-  if (template === 'nextjs') {
-    lines.push(`NEXT_PUBLIC_SPAPS_API_URL=${apiUrl}`);
+  if (templateDef.publicApiUrlEnv !== 'SPAPS_API_URL') {
+    lines.push(`${templateDef.publicApiUrlEnv}=${apiUrl}`);
   }
 
-  if (template === 'react') {
-    lines.push(`VITE_SPAPS_API_URL=${apiUrl}`);
+  if (provisioning.status === 'provisioned') {
+    const keyValue = template === 'node' ? provisioning.keys?.secret : provisioning.keys?.publishable;
+    if (keyValue) {
+      lines.push(`${templateDef.publicApiKeyEnv}=${keyValue}`);
+    } else {
+      lines.push(`# ${templateDef.publicApiKeyEnv}=`);
+    }
+  } else {
+    lines.push(`# ${templateDef.publicApiKeyEnv}=`);
+  }
+
+  if (template !== 'node' && templateDef.publicApiKeyEnv !== 'SPAPS_API_KEY') {
+    lines.push('# SPAPS_API_KEY=');
   }
 
   return `${lines.join('\n')}\n`;
 }
 
-function buildReadme({ name, template, apiUrl }) {
+function buildProvisioningNote({ provisioning, targetDir, template }) {
+  if (provisioning.status === 'provisioned') {
+    return [
+      '## Provisioning Status',
+      '',
+      `This starter was provisioned against \`${provisioning.runtime.url}\`. The generated \`.env.local\` includes a working ${template === 'node' ? 'server' : 'browser'} key for this template.`,
+      '',
+    ].join('\n');
+  }
+
+  if (provisioning.status === 'local_mode') {
+    return [
+      '## Provisioning Status',
+      '',
+      `The server at \`${provisioning.runtime.url}\` is currently in local mode, so authenticated flows can run without provisioning while that mode stays enabled.`,
+      '',
+      'Use `npx spaps quickstart --json` if you need the current local-mode hints and test personas.',
+      '',
+    ].join('\n');
+  }
+
+  const rerunCommand = `SELF_SERVICE_PASSWORD=your-password npx spaps create ${path.basename(targetDir)} --template ${template} --dir ${targetDir} --force`;
+
+  return [
+    '## Provisioning Status',
+    '',
+    'This run only scaffolded files. Authenticated flows will not work until you provision a real SPAPS application or enable server local mode.',
+    '',
+    'To provision automatically:',
+    '',
+    '```bash',
+    rerunCommand,
+    '```',
+    '',
+  ].join('\n');
+}
+
+function buildReadme({ name, template, apiUrl, targetDir, provisioning }) {
   const templateDef = SUPPORTED_TEMPLATES[template];
 
   return `# ${name}
@@ -203,22 +294,48 @@ It gives you three things immediately:
 
 This is not a full framework generator. It does not run \`create-next-app\`, Vite, or Express setup for you.
 
-## Next Steps
+${buildProvisioningNote({ provisioning, targetDir, template })}## Next Steps
 
-1. Start SPAPS locally with \`npx spaps local\`
-2. Install dependencies in this project with \`npm install\`
-3. Copy the generated starter files into your real ${templateDef.label.toLowerCase()} or keep extending this directory
-4. Point your app at \`${apiUrl}\`
+1. Install dependencies in this project with \`npm install\`
+2. Copy the generated starter files into your real ${templateDef.label.toLowerCase()} or keep extending this directory
+3. Point your app at \`${apiUrl}\`
 
 ## Generated Files
 
-- \`spaps.app.json\`: local-first app contract and blueprint hints
-- \`.env.local\`: SPAPS API URL wiring
+- \`spaps.app.json\`: local app contract and provisioning metadata
+- \`.env.local\`: SPAPS API URL wiring and, when available, a working key for this template
 - \`package.json\`: minimal dependency declaration for \`spaps-sdk\`
 `;
 }
 
-function createProjectStarter({
+function buildNextSteps({ targetDir, provisioning, port, name, template }) {
+  const steps = [
+    `cd ${targetDir}`,
+    'npm install',
+  ];
+
+  if (provisioning.status === 'provisioned') {
+    steps.push('Review .env.local and start your app');
+    return steps;
+  }
+
+  if (provisioning.status === 'local_mode') {
+    steps.push(`Use the starter against http://localhost:${port} while local mode stays enabled`);
+    return steps;
+  }
+
+  if (provisioning.reason === 'server_unreachable') {
+    steps.push(`npx spaps local --port ${port}`);
+  } else {
+    steps.push(
+      `SELF_SERVICE_PASSWORD=your-password npx spaps create ${name} --template ${template} --dir ${targetDir} --force`
+    );
+  }
+
+  return steps;
+}
+
+async function createProjectStarter({
   name,
   template,
   dir = null,
@@ -241,9 +358,15 @@ function createProjectStarter({
     files_created: [],
     files_overwritten: [],
   };
-
-  ensureWritableTarget(targetDir, force);
-  fs.mkdirSync(targetDir, { recursive: true });
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  prepareWritableTarget(targetDir, force);
+  const provisioning = await provisionStarterApplication({
+    port,
+    name: normalizedName,
+    slug,
+    blueprintKey: templateDef.blueprintKey,
+    allowedOrigins: templateDef.allowedOrigins,
+  });
 
   writeManagedFile(
     targetDir,
@@ -255,11 +378,17 @@ function createProjectStarter({
       version,
       apiUrl,
       docsUrl,
+      provisioning,
     }),
     bookkeeping
   );
-  writeManagedFile(targetDir, '.env.local', buildEnvFile(template, apiUrl), bookkeeping);
-  writeManagedFile(targetDir, 'README.md', buildReadme({ name: normalizedName, template, apiUrl }), bookkeeping);
+  writeManagedFile(targetDir, '.env.local', buildEnvFile(template, apiUrl, provisioning), bookkeeping);
+  writeManagedFile(
+    targetDir,
+    'README.md',
+    buildReadme({ name: normalizedName, template, apiUrl, targetDir, provisioning }),
+    bookkeeping
+  );
   writeManagedFile(targetDir, 'package.json', buildPackageJson(normalizedName, template), bookkeeping);
   writeManagedFile(
     targetDir,
@@ -268,7 +397,7 @@ function createProjectStarter({
     bookkeeping
   );
 
-  const templateFiles = SUPPORTED_TEMPLATES[template].files({
+  const templateFiles = templateDef.files({
     name: normalizedName,
     slug,
     apiUrl,
@@ -287,11 +416,22 @@ function createProjectStarter({
     contract_path: path.join(targetDir, 'spaps.app.json'),
     files_created: bookkeeping.files_created,
     files_overwritten: bookkeeping.files_overwritten,
-    next_steps: [
-      `cd ${targetDir}`,
-      'npm install',
-      'npx spaps local',
-    ],
+    provisioning: {
+      status: provisioning.status,
+      reason: provisioning.reason || null,
+      application_id: provisioning.application?.id || null,
+      application_slug: provisioning.application?.slug || slug,
+      local_mode_active: provisioning.runtime?.local_mode?.active ?? null,
+      server_url: provisioning.runtime?.url || apiUrl,
+    },
+    warnings: provisioning.warnings || [],
+    next_steps: buildNextSteps({
+      targetDir,
+      provisioning,
+      port,
+      name: normalizedName,
+      template,
+    }),
   };
 }