spaps 0.7.2 → 0.7.3

package/README.md

@@ -2,185 +2,161 @@
 
 CLI and middleware package for local SPAPS workflows.
 
-## TL;DR
+Examples in this README use placeholder emails and local-only defaults. Replace them with your own values if you wire the middleware into an app.
 
-**The Problem**: Local auth and payment development is slow when every app has to bootstrap a backend, wire environment files, and remember the right health and docs commands.
+## Install
 
-**The Solution**: `spaps` gives you a small CLI for local-server workflows plus exported admin middleware helpers for Node apps that integrate with SPAPS.
-
-### Why Use `spaps`?
-
-| Feature | What It Does |
-| --- | --- |
-| Local server workflow | Start, stop, inspect, and diagnose a local SPAPS server from the CLI |
-| Project bootstrap | Create a starter `.env.local` for SPAPS-aware projects |
-| AI tooling output | Emit the local OpenAI-style tool spec with `spaps tools` |
-| Middleware exports | Reuse admin-permission helpers from the package API |
-
-## Installation
-
-### Run Without Installing
+Run it without installing:
 
 ```bash
 npx spaps help
 ```
 
-### Global Install
+Install globally:
 
 ```bash
 npm install -g spaps
 ```
 
-### Project Dependency
+Add it to a project:
 
 ```bash
 npm install spaps
 ```
 
-## Quick Example
+This package targets `Node.js >=22`.
+
+## When It Fits
+
+| Need | Package gives you |
+| --- | --- |
+| A local SPAPS control surface | `local`, `status`, `doctor`, and `quickstart` commands |
+| Project bootstrap | `spaps init` creates a starter `.env.local` |
+| AI tooling integration | `spaps tools` emits an OpenAI-style tool spec |
+| Lightweight Node middleware | Admin and permission helpers for Express-style apps |
+
+## Quick Start
 
 ```bash
 # Start the local server
 npx spaps local
 
-# Check status
+# Confirm it is healthy
 npx spaps status
 
-# Initialize .env.local in the current project
+# Create a starter .env.local in the current project
 npx spaps init
 
 # Emit the local tool spec as JSON
 npx spaps tools --json
 ```
 
-## CLI Commands
+## CLI Surface
 
-### `spaps local [subcommand]`
+| Command | Purpose | Common flags |
+| --- | --- | --- |
+| `spaps local [stop]` | Start or stop the local server workflow | `--port`, `--detach`, `--fresh`, `--from-backup`, `--open`, `--json` |
+| `spaps status` | Check whether the local server is running | `--port`, `--json` |
+| `spaps quickstart` | Print quick-start instructions | `--port`, `--json` |
+| `spaps init` | Create a starter `.env.local` | `--json` |
+| `spaps create <name>` | Scaffold a SPAPS starter project directory | `--template`, `--dir`, `--force`, `--json` |
+| `spaps docs` | Browse or search bundled docs | `--interactive`, `--search`, `--json` |
+| `spaps tools` | Emit the AI tool spec | `--port`, `--format`, `--json` |
+| `spaps doctor` | Diagnose local environment problems | `--port`, `--stripe`, `--json` |
 
-Start or stop the local SPAPS server.
+Example command usage:
 
 ```bash
-spaps local
-spaps local --port 3400
-spaps local --detach
-spaps local --open
-spaps local stop
-```
-
-Supported flags:
-
-- `--port <port>`
-- `--detach`
-- `--fresh`
-- `--from-backup <path>`
-- `--open`
-- `--json`
-
-### `spaps status`
-
-```bash
-spaps status
-spaps status --port 3400
+spaps local --port 3400 --detach
 spaps status --json
+spaps create my-app --template react
+spaps docs --search secure-messages
+spaps doctor --stripe mock
+spaps local stop
 ```
 
-### `spaps quickstart`
+Still reserved and not finished:
 
-```bash
-spaps quickstart
-spaps quickstart --port 3400
-spaps quickstart --json
-```
+- `spaps types`
 
-### `spaps init`
+## Create A Starter Project
 
-```bash
-spaps init
-spaps init --json
-```
+`spaps create` ships a local-first starter kit rather than a full framework generator. It creates a new directory with:
 
-### `spaps docs`
+- `spaps.app.json` for the machine-readable SPAPS app contract
+- `.env.local` pointing at local SPAPS
+- `package.json` with `spaps-sdk`
+- a small template-specific integration starter
 
-```bash
-spaps docs
-spaps docs --interactive
-spaps docs --search secure-messages
-spaps docs --json
-```
+Supported templates:
 
-### `spaps tools`
+- `nextjs`
+- `react`
+- `node`
+- `vanilla`
 
-```bash
-spaps tools
-spaps tools --port 3400
-spaps tools --format openai
-spaps tools --json
-```
-
-### `spaps doctor`
+Example:
 
 ```bash
-spaps doctor
-spaps doctor --port 3400
-spaps doctor --stripe mock
-spaps doctor --json
+npx spaps create my-app --template react
+npx spaps create my-api --template node --dir ./services/my-api
 ```
 
-### Placeholder Commands
-
-The CLI currently includes placeholders for:
-
-- `spaps create <name>`
-- `spaps types`
-
-Treat them as reserved surfaces rather than stable workflows.
-
 ## Middleware Example
 
-The package exports admin middleware and helper utilities from its main module:
+The main module exports admin and permission helpers for Express-style apps.
 
-```javascript
-const express = require('express');
-const { requireAdmin, requirePermission } = require('spaps');
+```js
+const express = require("express");
+const { requireAdmin, requirePermission } = require("spaps");
 
 const app = express();
-
-app.get('/admin', requireAdmin(), (_req, res) => {
-  res.json({ ok: true });
-});
-
-app.post('/admin/products', requirePermission('manage_products'), (_req, res) => {
-  res.json({ created: true });
-});
+const customAdmins = ["admin@example.com"];
+
+app.get(
+  "/admin",
+  requireAdmin({ customAdmins }),
+  (_req, res) => {
+    res.json({ ok: true });
+  },
+);
+
+app.post(
+  "/admin/products",
+  requirePermission("manage_products", { customAdmins }),
+  (_req, res) => {
+    res.json({ created: true });
+  },
+);
 ```
 
 ## What `spaps init` Writes
 
-`spaps init` creates a `.env.local` with a local API URL starter and leaves existing files alone if they are already present.
+`spaps init` creates a `.env.local` file with a local API URL starter and leaves an existing file alone if one is already present.
 
 ## Troubleshooting
 
 ### Port already in use
 
-Start on a different port:
+Start on another port:
 
 ```bash
 npx spaps local --port 3400
 ```
 
-### Need machine-readable output
+### I need machine-readable output
 
-Use `--json` on supported commands such as `local`, `status`, `quickstart`, `init`, `docs`, `tools`, and `doctor`.
+Use `--json` on commands that support it, including `local`, `status`, `quickstart`, `init`, `docs`, `tools`, and `doctor`.
 
-### Local server is not responding
+### The local server is not responding
 
-Check the current status first:
+Check current status first:
 
 ```bash
 npx spaps status
 ```
 
-Then re-run the server with a clean start if needed:
+If needed, restart with a clean boot:
 
 ```bash
 npx spaps local --fresh
@@ -188,21 +164,22 @@ npx spaps local --fresh
 
 ## Limitations
 
-- The README only documents commands and flags that are currently wired in the CLI dispatcher.
-- `create` and `types` are present as placeholders and should not be treated as finished product surfaces.
-- The package is primarily for local workflows, not full production deployment automation.
+- The CLI is aimed at local workflows. It is not a full deployment or hosting tool.
+- `create` does not run `create-next-app`, Vite, or Express generators for you; it scaffolds the SPAPS integration layer.
+- `types` is still a placeholder today.
+- The middleware ships a legacy default admin configuration in code; public-facing apps should pass explicit `customAdmins` instead of relying on that default.
 
 ## FAQ
 
-### Does this package expose the TypeScript SDK?
+### Does this package include the TypeScript SDK?
 
-No. The SDK is the separate `spaps-sdk` package.
+No. The SDK is published separately as `spaps-sdk`.
 
-### Can I use the CLI without installing globally?
+### Can I use the CLI without a global install?
 
 Yes. Use `npx spaps ...`.
 
-### Does `spaps init` overwrite my existing env file?
+### Does `spaps init` overwrite an existing env file?
 
 No. It skips `.env.local` if the file already exists.
 
@@ -210,14 +187,14 @@ No. It skips `.env.local` if the file already exists.
 
 An OpenAI-style tool spec for the local SPAPS surface.
 
-### Is the admin middleware available as an import?
+### Is the middleware available from a subpath?
 
-Yes. The package exports the admin helpers from its main module and via the `./middleware` export path.
+Yes. You can import from the main module or `spaps/middleware`.
 
 ## About Contributions
 
-*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+> *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
 
 ## License
 
-UNLICENSED
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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": {
@@ -13,13 +13,13 @@
     "./middleware": "./src/middleware/admin.js"
   },
   "scripts": {
-    "test": "echo \"No tests yet\""
+    "test": "node --test"
   },
   "keywords": [
     "authentication",
     "payments",
     "stripe",
-    "supabase",
+    "fastapi",
     "local-development",
     "cli",
     "spaps",
@@ -29,7 +29,7 @@
     "ethereum"
   ],
   "author": "buildooor",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/build000r"

package/src/cli-dispatcher.js

@@ -138,8 +138,20 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
   // spaps create <name>
   const cmdCreate = program
     .command('create <name>')
-    .description('Create a new project with SPAPS (coming soon)')
-    .action(makeAction('create', (optsOrName, cmd) => ({ name: typeof optsOrName === 'string' ? optsOrName : cmd.args[0] })));
+    .description('Create a starter project directory wired for SPAPS')
+    .option('-t, --template <template>', 'Starter template: nextjs|react|node|vanilla')
+    .option('--dir <dir>', 'Target directory (defaults to ./<name>)')
+    .option('-f, --force', 'Allow writing into a non-empty directory', false)
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('create', (opts, cmd, isJson) => ({
+        name: cmd.args[0],
+        template: opts.template || null,
+        dir: opts.dir || null,
+        force: Boolean(opts.force),
+        json: isJson,
+      }))
+    );
   if (dryRun) {
     cmdCreate.allowUnknownOption(true);
     if (typeof cmdCreate.allowExcessArguments === 'function') {
@@ -236,8 +248,14 @@ function buildProgram(config = {}) {
 function parseArgv(argv, config = {}) {
   const { program, getIntents } = defineProgram({ ...config, dryRun: true });
   program.exitOverride(() => { /* swallow exit in dry-run */ });
+  const normalizedArgv = Array.isArray(argv) &&
+    argv.length >= 2 &&
+    /(^|[\\/])node(\.exe)?$/.test(String(argv[0])) &&
+    /spaps(?:\.js)?$/.test(String(argv[1]))
+    ? argv.slice(2)
+    : argv;
   try {
-    program.parse(argv, { from: 'user' });
+    program.parse(normalizedArgv, { from: 'user' });
   } catch (err) {
     // Commander throws for help/version; we ignore in parse mode
   }

package/src/error-handler.js

@@ -91,6 +91,48 @@ const ERROR_FIXES = {
     ]
   }),
 
+  // Invalid arguments
+  EINVAL: (error, context = {}) => ({
+    title: 'Invalid Command Arguments',
+    description: error.message || 'One or more command arguments are invalid',
+    causes: [
+      'A required flag was omitted',
+      'An unsupported template or option was supplied',
+      'The command arguments do not match the expected shape'
+    ],
+    fixes: [
+      {
+        command: 'npx spaps create my-app --template react',
+        description: 'Run create with an explicit supported template'
+      },
+      {
+        command: 'npx spaps help --interactive',
+        description: 'Browse supported create templates and usage examples'
+      }
+    ]
+  }),
+
+  // Existing file system content
+  EEXIST: (error, context = {}) => ({
+    title: 'Target Directory Already Contains Files',
+    description: error.message || 'The target directory is not empty',
+    causes: [
+      'You pointed create at an existing project directory',
+      'A previous scaffold already wrote files there',
+      'The directory contains unrelated files that should not be overwritten by default'
+    ],
+    fixes: [
+      {
+        command: `npx spaps create ${context.name || 'my-app'} --template ${context.template || 'react'} --dir ${context.dir || './my-app'} --force`,
+        description: 'Overwrite the managed starter files explicitly'
+      },
+      {
+        command: `npx spaps create ${context.name || 'my-app'} --template ${context.template || 'react'} --dir ./another-directory`,
+        description: 'Choose an empty directory for the new starter'
+      }
+    ]
+  }),
+
   // Network errors
   ECONNREFUSED: (error, context = {}) => ({
     title: 'Connection Refused',

package/src/handlers.js

@@ -7,6 +7,7 @@ const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-
 const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
 const { buildToolSpec } = require('./ai-tool-spec');
 const { runDoctor } = require('./doctor');
+const { createProjectStarter } = require('./project-scaffolder');
 
 function createHandlers(version, logo) {
   return {
@@ -114,12 +115,57 @@ function createHandlers(version, logo) {
         console.log(chalk.cyan('  3. Start coding!'));
       }
     },
-    create: () => {
-      console.log(chalk.yellow('🍠 SPAPS'));
-      console.log(chalk.yellow(`🚧 'spaps create' coming in v0.3.0!`));
-      console.log();
-      console.log('For now, check out our examples:');
-      console.log(chalk.cyan('  https://github.com/yourusername/sweet-potato/tree/main/examples'));
+    create: ({ options }) => {
+      const isJson = options.json;
+
+      try {
+        const result = createProjectStarter({
+          name: options.name,
+          template: options.template,
+          dir: options.dir,
+          force: options.force,
+          version,
+        });
+
+        if (isJson) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log(chalk.green(`\n✨ Created ${result.project_name} (${result.template})`));
+        console.log(chalk.cyan(`   ${result.target_dir}`));
+
+        if (result.files_created.length > 0) {
+          console.log(chalk.green('\nFiles created:'));
+          result.files_created.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        if (result.files_overwritten.length > 0) {
+          console.log(chalk.yellow('\nFiles overwritten:'));
+          result.files_overwritten.forEach((file) => {
+            console.log(chalk.gray(`  • ${file}`));
+          });
+        }
+
+        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: 'create',
+            name: options.name,
+            template: options.template,
+            dir: options.dir,
+          },
+          { json: isJson }
+        );
+      }
     },
     types: () => {
       console.log(chalk.yellow('🍠 SPAPS'));

package/src/help-system.js

@@ -454,7 +454,7 @@ function showQuickHelp() {
   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('# Create new project (v0.3.0)'));
+  console.log('  npx spaps create <name>          ' + chalk.gray('# Scaffold a SPAPS starter project'));
   console.log('  npx spaps types                  ' + chalk.gray('# Generate types (v0.4.0)'));
   console.log();
   

package/src/project-scaffolder.js

@@ -0,0 +1,301 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { DEFAULT_PORT } = require('./config');
+
+const SUPPORTED_TEMPLATES = {
+  nextjs: {
+    label: 'Next.js starter',
+    blueprintKey: 'browser_auth',
+    allowedOrigins: ['http://localhost:3000'],
+    files: ({ apiUrl }) => ({
+      'lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || '${apiUrl}',
+});
+`,
+      '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'],
+    files: ({ apiUrl }) => ({
+      'src/lib/spaps.ts': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: import.meta.env.VITE_SPAPS_API_URL || '${apiUrl}',
+});
+`,
+    }),
+  },
+  node: {
+    label: 'Node.js starter',
+    blueprintKey: 'default',
+    allowedOrigins: [],
+    files: ({ apiUrl }) => ({
+      'src/spaps.js': `const { SPAPSClient } = require('spaps-sdk');
+
+const spaps = new SPAPSClient({
+  apiUrl: process.env.SPAPS_API_URL || '${apiUrl}',
+  apiKey: process.env.SPAPS_API_KEY,
+});
+
+module.exports = { spaps };
+`,
+    }),
+  },
+  vanilla: {
+    label: 'Vanilla JavaScript starter',
+    blueprintKey: 'browser_auth',
+    allowedOrigins: ['http://localhost:8080'],
+    files: ({ apiUrl }) => ({
+      'src/spaps.js': `import { SPAPSClient } from 'spaps-sdk';
+
+export const spaps = new SPAPSClient({
+  apiUrl: '${apiUrl}',
+});
+`,
+    }),
+  },
+};
+
+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 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 }) {
+  const templateDef = SUPPORTED_TEMPLATES[template];
+  const contract = {
+    name,
+    slug,
+    template,
+    created_with: `spaps@${version}`,
+    spaps: {
+      local: {
+        api_url: apiUrl,
+        docs_url: docsUrl,
+      },
+      application: {
+        slug,
+        blueprint_key: templateDef.blueprintKey,
+        allowed_origins: templateDef.allowedOrigins,
+        provisioning_status: 'local_starter_only',
+      },
+    },
+  };
+
+  return `${JSON.stringify(contract, null, 2)}\n`;
+}
+
+function buildEnvFile(template, apiUrl) {
+  const lines = [
+    '# SPAPS local development',
+    `SPAPS_API_URL=${apiUrl}`,
+    '# SPAPS_API_KEY=',
+  ];
+
+  if (template === 'nextjs') {
+    lines.push(`NEXT_PUBLIC_SPAPS_API_URL=${apiUrl}`);
+  }
+
+  if (template === 'react') {
+    lines.push(`VITE_SPAPS_API_URL=${apiUrl}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function buildReadme({ name, template, apiUrl }) {
+  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.
+
+## 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}\`
+
+## Generated Files
+
+- \`spaps.app.json\`: local-first app contract and blueprint hints
+- \`.env.local\`: SPAPS API URL wiring
+- \`package.json\`: minimal dependency declaration for \`spaps-sdk\`
+`;
+}
+
+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: [],
+  };
+
+  ensureWritableTarget(targetDir, force);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  writeManagedFile(
+    targetDir,
+    'spaps.app.json',
+    buildContract({
+      name: normalizedName,
+      slug,
+      template,
+      version,
+      apiUrl,
+      docsUrl,
+    }),
+    bookkeeping
+  );
+  writeManagedFile(targetDir, '.env.local', buildEnvFile(template, apiUrl), bookkeeping);
+  writeManagedFile(targetDir, 'README.md', buildReadme({ name: normalizedName, template, apiUrl }), bookkeeping);
+  writeManagedFile(targetDir, 'package.json', buildPackageJson(normalizedName, template), bookkeeping);
+  writeManagedFile(
+    targetDir,
+    '.gitignore',
+    'node_modules\n.env\n.env.local\n',
+    bookkeeping
+  );
+
+  const templateFiles = SUPPORTED_TEMPLATES[template].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,
+    next_steps: [
+      `cd ${targetDir}`,
+      'npm install',
+      'npx spaps local',
+    ],
+  };
+}
+
+module.exports = {
+  SUPPORTED_TEMPLATES,
+  createProjectStarter,
+};