spaps 0.7.2 → 0.7.4

package/src/project-scaffolder.js

@@ -0,0 +1,441 @@
+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 { createBrowserClient, SPAPSClient } from 'spaps-sdk';
+
+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';
+
+import { PropsWithChildren } from 'react';
+import { spaps } from '../lib/spaps';
+
+export function Providers({ children }: PropsWithChildren) {
+  void spaps;
+  return children;
+}
+`,
+    }),
+  },
+  react: {
+    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 { 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 = apiKey && apiKey.startsWith('spaps_pub_')
+  ? createBrowserClient(apiKey, { apiUrl })
+  : new SPAPSClient({
+      apiUrl,
+      ...(apiKey ? { apiKey } : {}),
+    });
+`,
+    }),
+  },
+  node: {
+    label: 'Node.js starter',
+    blueprintKey: 'default',
+    allowedOrigins: [],
+    publicApiUrlEnv: 'SPAPS_API_URL',
+    publicApiKeyEnv: 'SPAPS_API_KEY',
+    files: ({ apiUrl }) => ({
+      '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 = apiKey
+  ? createServerClient(apiKey, { apiUrl })
+  : new SPAPSClient({ apiUrl });
+
+module.exports = { spaps };
+`,
+    }),
+  },
+  vanilla: {
+    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 { createBrowserClient, SPAPSClient } from 'spaps-sdk';
+
+const apiUrl = window.SPAPS_API_URL || '${apiUrl}';
+const apiKey = window.SPAPS_API_KEY;
+
+export const spaps = apiKey && apiKey.startsWith('spaps_pub_')
+  ? createBrowserClient(apiKey, { apiUrl })
+  : new SPAPSClient({
+      apiUrl,
+      ...(apiKey ? { apiKey } : {}),
+    });
+`,
+    }),
+  },
+};
+
+function createCliError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function slugifyProjectName(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function ensureSupportedTemplate(template) {
+  if (!template) {
+    throw createCliError(
+      'EINVAL',
+      `The --template flag is required. Supported templates: ${Object.keys(SUPPORTED_TEMPLATES).join(', ')}.`
+    );
+  }
+
+  if (!SUPPORTED_TEMPLATES[template]) {
+    throw createCliError(
+      'EINVAL',
+      `Unsupported template "${template}". Supported templates: ${Object.keys(SUPPORTED_TEMPLATES).join(', ')}.`
+    );
+  }
+}
+
+function ensureWritableTarget(targetDir, force) {
+  if (!fs.existsSync(targetDir)) {
+    return;
+  }
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length > 0 && !force) {
+    throw createCliError(
+      'EEXIST',
+      `Target directory "${targetDir}" is not empty. Re-run with --force to overwrite managed files.`
+    );
+  }
+}
+
+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 });
+
+  if (fs.existsSync(fullPath)) {
+    bookkeeping.files_overwritten.push(relativePath);
+  } else {
+    bookkeeping.files_created.push(relativePath);
+  }
+
+  fs.writeFileSync(fullPath, content);
+}
+
+function buildPackageJson(name, template) {
+  const pkg = {
+    name,
+    private: true,
+    version: '0.0.0',
+    description: `SPAPS ${SUPPORTED_TEMPLATES[template].label.toLowerCase()} for ${name}`,
+    dependencies: {
+      'spaps-sdk': 'latest',
+    },
+  };
+
+  if (template === 'node') {
+    pkg.type = 'commonjs';
+  }
+
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+function buildContract({ name, slug, template, version, apiUrl, docsUrl, provisioning }) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  const contract = {
+    name,
+    slug,
+    template,
+    created_with: `spaps@${version}`,
+    spaps: {
+      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: provisioning.status,
+        provisioned_via:
+          provisioning.status === 'provisioned'
+            ? 'self_service'
+            : provisioning.status === 'local_mode'
+              ? 'local_mode'
+              : null,
+      },
+    },
+  };
+
+  return `${JSON.stringify(contract, null, 2)}\n`;
+}
+
+function buildEnvFile(template, apiUrl, provisioning) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  const lines = [
+    '# SPAPS local development',
+    `SPAPS_API_URL=${apiUrl}`,
+  ];
+
+  if (templateDef.publicApiUrlEnv !== 'SPAPS_API_URL') {
+    lines.push(`${templateDef.publicApiUrlEnv}=${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 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}
+
+This directory is a SPAPS ${templateDef.label.toLowerCase()}.
+
+It gives you three things immediately:
+
+- a machine-readable SPAPS app contract in \`spaps.app.json\`
+- local env wiring in \`.env.local\`
+- a small template-specific integration starter you can drop into a real app
+
+This is not a full framework generator. It does not run \`create-next-app\`, Vite, or Express setup for you.
+
+${buildProvisioningNote({ provisioning, targetDir, template })}## Next Steps
+
+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 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 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,
+  force = false,
+  version = '0.0.0',
+  port = DEFAULT_PORT,
+}) {
+  if (!name || !String(name).trim()) {
+    throw createCliError('EINVAL', 'Project name is required.');
+  }
+
+  ensureSupportedTemplate(template);
+
+  const normalizedName = String(name).trim();
+  const slug = slugifyProjectName(normalizedName);
+  const targetDir = path.resolve(dir || path.join(process.cwd(), slug));
+  const apiUrl = `http://localhost:${port}`;
+  const docsUrl = `${apiUrl}/docs`;
+  const bookkeeping = {
+    files_created: [],
+    files_overwritten: [],
+  };
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  prepareWritableTarget(targetDir, force);
+  const provisioning = await provisionStarterApplication({
+    port,
+    name: normalizedName,
+    slug,
+    blueprintKey: templateDef.blueprintKey,
+    allowedOrigins: templateDef.allowedOrigins,
+  });
+
+  writeManagedFile(
+    targetDir,
+    'spaps.app.json',
+    buildContract({
+      name: normalizedName,
+      slug,
+      template,
+      version,
+      apiUrl,
+      docsUrl,
+      provisioning,
+    }),
+    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,
+    '.gitignore',
+    'node_modules\n.env\n.env.local\n',
+    bookkeeping
+  );
+
+  const templateFiles = templateDef.files({
+    name: normalizedName,
+    slug,
+    apiUrl,
+  });
+
+  for (const [relativePath, content] of Object.entries(templateFiles)) {
+    writeManagedFile(targetDir, relativePath, content, bookkeeping);
+  }
+
+  return {
+    success: true,
+    command: 'create',
+    project_name: normalizedName,
+    template,
+    target_dir: targetDir,
+    contract_path: path.join(targetDir, 'spaps.app.json'),
+    files_created: bookkeeping.files_created,
+    files_overwritten: bookkeeping.files_overwritten,
+    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,
+    }),
+  };
+}
+
+module.exports = {
+  SUPPORTED_TEMPLATES,
+  createProjectStarter,
+};