create-win-project 1.3.0 → 2.0.0

package/{lib/generator.js → src/stacks/create-project.js}

@@ -1,39 +1,33 @@
 import fs from 'fs-extra'
 import path from 'path'
-import { randomUUID } from 'node:crypto'
-import { loadCatalog, resolveStack } from './catalog.js'
-import { loadCompatibility } from './compatibility.js'
-import { buildRulesIndex, copySelectedPlaybooks } from './playbooks.js'
-import { buildVars, render, readTemplate } from './template.js'
-import { buildRunnableFiles } from './scaffold.js'
-import { buildLaravelFiles } from './laravel-scaffold.js'
+import { loadCatalog, resolveStack } from '../engine/load-library.js'
+import { loadCompatibility } from '../engine/tested-versions.js'
+import { buildRulesIndex, copySelectedPlaybooks } from '../engine/project-guidance.js'
+import { buildVars, render, readTemplate } from '../engine/render-templates.js'
+import { buildRunnableFiles } from './compose-files.js'
 import {
   contextMd, progressMd, docPlaceholder,
   editorconfig, prettierrc, prTemplate,
-} from './files.js'
-
-function laravelCompose(answers, stack, vars) {
-  const laravelDir = stack.frontendKey === 'laravel-ui' || stack.frontendKey === 'no-frontend' ? '.' : './backend'
-  const frontend = stack.frontendKey === 'react'
-    ? `  frontend:\n    build:\n      context: ./frontend\n      dockerfile: Dockerfile.dev\n    ports:\n      - "5173:5173"\n    volumes:\n      - ./frontend:/app\n      - frontend-node-modules:/app/node_modules\n    environment:\n      VITE_API_URL: http://localhost:8000\n    depends_on:\n      - backend\n\n`
-    : stack.frontendKey === 'nextjs'
-      ? `  frontend:\n    build:\n      context: .\n      dockerfile: Dockerfile.dev\n    ports:\n      - "3000:3000"\n    volumes:\n      - .:/app\n      - /app/backend\n      - frontend-node-modules:/app/node_modules\n    environment:\n      NEXT_PUBLIC_API_URL: http://localhost:8000\n    depends_on:\n      - backend\n\n`
-      : ''
-  const frontendVolume = frontend ? '  frontend-node-modules:\n' : ''
-  return `services:\n${frontend}  backend:\n    build:\n      context: ${laravelDir}\n      dockerfile: Dockerfile.dev\n    ports:\n      - "8000:8000"\n    volumes:\n      - ${laravelDir}:/app\n      - laravel-vendor:/app/vendor\n    environment:\n      APP_ENV: local\n      APP_DEBUG: "true"\n      APP_KEY: \${APP_KEY:-}\n      DB_CONNECTION: pgsql\n      DB_HOST: db\n      DB_PORT: 5432\n      DB_DATABASE: \${POSTGRES_DB}\n      DB_USERNAME: \${POSTGRES_USER}\n      DB_PASSWORD: \${POSTGRES_PASSWORD}\n    depends_on:\n      db:\n        condition: service_healthy\n\n  db:\n    image: ${vars.POSTGRES_IMAGE}\n    ports:\n      - "5432:5432"\n    environment:\n      POSTGRES_DB: \${POSTGRES_DB}\n      POSTGRES_USER: \${POSTGRES_USER}\n      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD}\n    volumes:\n      - postgres-data:/var/lib/postgresql/data\n    healthcheck:\n      test: ["CMD-SHELL", "pg_isready -U \${POSTGRES_USER} -d \${POSTGRES_DB}"]\n      interval: 5s\n      timeout: 5s\n      retries: 10\n\nvolumes:\n${frontendVolume}  laravel-vendor:\n  postgres-data:\n`
-}
+} from '../engine/project-files.js'
+import {
+  projectDestinations,
+  writeFile as write,
+  writeProjectAtomically,
+} from '../engine/write-files.js'
+import { writeRenderedFile as writeTemplate } from '../engine/render-templates.js'
+import { laravelCompose } from './backends/laravel/docker.js'
+import { fastapiCompose } from './backends/fastapi/docker.js'
 
 /**
  * Main entry point — generates the full project
  */
-export async function generateProject(answers, cliRoot) {
+export async function scaffoldProject(answers, cliRoot) {
   validateAnswers(answers)
-  const finalDest   = path.join(process.cwd(), answers.projectName)
-  const dest        = path.join(process.cwd(), `.${answers.projectName}.tmp-${randomUUID()}`)
-  const playbooksDir = path.join(cliRoot, 'playbooks')
-  const ciDir        = path.join(cliRoot, 'ci')
+  const { finalDestination, stagingDestination } = await projectDestinations(process.cwd(), answers.projectName)
+  const playbooksDir = path.join(cliRoot, 'library')
+  const ciDir        = path.join(cliRoot, 'templates', 'ci')
   const { profile }  = await loadCompatibility(
-    path.join(cliRoot, 'compatibility/profiles.json'),
+    path.join(cliRoot, 'library/tested-versions.json'),
     answers.compatibilityProfile,
   )
   const catalog      = await loadCatalog(playbooksDir, profile)
@@ -50,15 +44,12 @@ export async function generateProject(answers, cliRoot) {
 
   // 1. Refuse to merge into an existing project. Generation must never silently
   // overwrite user work.
-  if (await fs.pathExists(finalDest)) {
-    throw new Error(`Destination already exists: ${finalDest}`)
-  }
-
-  try {
+  await writeProjectAtomically({
+    finalDestination,
+    stagingDestination,
+    generate: async (dest) => {
     // 2. Staging folder. It is moved into place only after every generation
     // step succeeds, so failures never leave a half-written project.
-    await fs.ensureDir(dest)
-
     // 3. Root documentation and repository files. Directories are created only
     // when a real generated file needs them; empty architecture theatre is not
     // part of the scaffold contract.
@@ -82,11 +73,8 @@ export async function generateProject(answers, cliRoot) {
     // 8. RULES.md
     const rulesContent = await buildRulesIndex(stack, catalog, playbooksDir)
     await write(dest, 'RULES.md', rulesContent)
-    await fs.move(dest, finalDest)
-  } catch (error) {
-    await fs.remove(dest)
-    throw error
-  }
+    },
+  })
 }
 
 function validateAnswers(answers) {
@@ -97,9 +85,18 @@ function validateAnswers(answers) {
   if (typeof answers.projectDescription !== 'string' || !answers.projectDescription.trim()) {
     throw new Error('Project description is required')
   }
-  if (answers.testing && !['none', 'basic', 'full'].includes(answers.testing)) {
+  if (answers.testing && !['basic', 'full'].includes(answers.testing)) {
     throw new Error(`Unknown testing setup: ${answers.testing}`)
   }
+  const uploads = answers.uploads || 'none'
+  const jobs = answers.backgroundJobs || 'none'
+  const offline = answers.offline || 'none'
+  if (!['none', 'object-storage'].includes(uploads)) throw new Error(`Unknown uploads requirement: ${uploads}`)
+  if (!['none', 'queue'].includes(jobs)) throw new Error(`Unknown background-jobs requirement: ${jobs}`)
+  if (!['none', 'cache', 'sync'].includes(offline)) throw new Error(`Unknown offline requirement: ${offline}`)
+  if (offline !== 'none' && answers.frontend !== 'react-native') throw new Error('Offline capabilities are supported only for mobile applications')
+  if (jobs === 'queue' && !['springboot', 'laravel'].includes(answers.backend)) throw new Error('Queues require a Spring Boot or Laravel backend')
+  if (uploads === 'object-storage' && answers.backend === 'none') throw new Error('Object storage uploads require a backend or managed data service')
   if (answers.architecture && !['small', 'medium', 'large'].includes(answers.architecture)) {
     throw new Error(`Unknown architecture profile: ${answers.architecture}`)
   }
@@ -114,11 +111,11 @@ function validateAnswers(answers) {
 // ─── Root files ───────────────────────────────────────────────────────────────
 
 async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
-  await writeTemplate(dest, 'CONTEXT.md',    contextMd(vars, answers.expectedConcerns), vars)
+  await writeTemplate(dest, 'CONTEXT.md', contextMd(vars, answers.expectedConcerns, answers), vars)
   // AGENTS.md — template-driven
   {
     const tpl = await readTemplate(templatesDir, 'agents', stack.agentsTemplate, '.md')
-    if (tpl) await writeTemplate(dest, 'AGENTS.md', tpl, vars)
+    if (tpl) await writeTemplate(dest, 'AGENTS.md', `${tpl}\n## Deviation policy\n\nAgents may recommend alternatives, but must propose the change and receive explicit approval before changing the selected architecture, provider, authentication model, data boundary, production baseline, or major dependency. Record approved deviations and their rationale in \`CONTEXT.md\`.\n`, vars)
     else await write(dest, 'AGENTS.md', `# AGENTS.md\nStack: ${stack.label}\n`)
   }
   await write(dest,         'PROGRESS.md',   progressMd())
@@ -135,6 +132,15 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
   }
   await write(dest,         '.editorconfig', editorconfig())
   await write(dest,         '.prettierrc',   prettierrc())
+  if (stack.backendKey === 'springboot') await write(dest, 'backend/.java-version', `${stack.profile.runtimes.java}\n`)
+  if (stack.backendKey === 'fastapi') {
+    const apiRoot = stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+    await write(dest, `${apiRoot}.python-version`, `${stack.profile.runtimes.python}\n`)
+  }
+  if (stack.backendKey === 'laravel') {
+    const laravelRoot = stack.frontendKey === 'laravel-ui' || stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+    await write(dest, `${laravelRoot}.php-version`, `${stack.profile.runtimes.php}\n`)
+  }
 
   // Makefile — template-driven (web only)
   if (answers.makefile && !stack.isMobile) {
@@ -146,11 +152,13 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
   // Mobile frontends run through Expo, but a separate Laravel backend still
   // needs its backend and PostgreSQL services. laravelCompose intentionally
   // omits a frontend service for React Native.
-  if (answers.docker && (!stack.isMobile || stack.backendKey === 'laravel')) {
+  if (answers.docker && (!stack.isMobile || ['laravel', 'fastapi'].includes(stack.backendKey))) {
     // docker-compose.yml
     let composeTpl = null
     if (stack.backendKey === 'laravel') {
       composeTpl = laravelCompose(answers, stack, vars)
+    } else if (stack.backendKey === 'fastapi') {
+      composeTpl = fastapiCompose(answers, stack, vars)
     } else if (stack.needsPackage) {
       composeTpl = await readTemplate(templatesDir, 'docker/compose', 'springboot', '.yml')
     } else if (stack.backendKey === 'supabase') {
@@ -180,6 +188,22 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
       if (beProd) await writeTemplate(dest, 'backend/Dockerfile', beProd, vars)
     }
 
+    if (stack.backendKey === 'fastapi') {
+      const apiRoot = stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+      const prodTpl = await readTemplate(templatesDir, 'docker/compose-prod', 'fastapi', '.yml')
+      if (prodTpl) {
+        const rendered = stack.frontendKey === 'no-frontend'
+          ? prodTpl.replaceAll('context: ./backend', 'context: .').replaceAll('./backend:/app', '.:/app')
+          : prodTpl
+        await writeTemplate(dest, 'docker-compose.prod.yml', rendered, vars)
+      }
+
+      const beDev = await readTemplate(templatesDir, 'docker/dockerfile', 'fastapi.dev', '.dockerfile')
+      if (beDev) await writeTemplate(dest, `${apiRoot}Dockerfile.dev`, beDev, vars)
+      const beProd = await readTemplate(templatesDir, 'docker/dockerfile', 'fastapi.prod', '.dockerfile')
+      if (beProd) await writeTemplate(dest, `${apiRoot}Dockerfile`, beProd, vars)
+    }
+
     // frontend dockerfiles — vite vs nextjs
     if (stack.frontendKey === 'react') {
       const viteDev = await readTemplate(templatesDir, 'docker/dockerfile', 'vite.dev', '.dockerfile')
@@ -187,7 +211,7 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
       const viteProd = await readTemplate(templatesDir, 'docker/dockerfile', 'vite.prod', '.dockerfile')
       if (viteProd) {
         await writeTemplate(dest, 'frontend/Dockerfile', viteProd, vars)
-        const nginx = `server {\n  listen 80;\n  location / {\n    root /usr/share/nginx/html;\n    index index.html;\n    try_files $uri $uri/ /index.html;\n  }\n}\n`
+        const nginx = `server {\n  listen 8080;\n  server_tokens off;\n  root /usr/share/nginx/html;\n  add_header X-Content-Type-Options nosniff always;\n  add_header Referrer-Policy strict-origin-when-cross-origin always;\n  add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;\n  add_header Content-Security-Policy "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'" always;\n  location /assets/ { try_files $uri =404; add_header Cache-Control "public, max-age=31536000, immutable"; }\n  location /api/ { add_header Cache-Control "no-store" always; try_files $uri =404; }\n  location / { index index.html; try_files $uri $uri/ /index.html; add_header Cache-Control "no-cache"; }\n}\n`
         await write(dest, 'frontend/nginx.conf', nginx)
       }
     } else if (stack.frontendKey === 'nextjs') {
@@ -198,6 +222,45 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
     }
   }
 
+  // Production artifacts are part of the deployable web contract even when
+  // the optional development Docker workflow was not selected.
+  if (!answers.docker && !stack.isMobile) {
+    if (stack.frontendKey === 'nextjs') {
+      const nextProd = await readTemplate(templatesDir, 'docker/dockerfile', 'nextjs.prod', '.dockerfile')
+      if (nextProd) await writeTemplate(dest, 'Dockerfile', nextProd, vars)
+    }
+    if (stack.frontendKey === 'react') {
+      const viteProd = await readTemplate(templatesDir, 'docker/dockerfile', 'vite.prod', '.dockerfile')
+      if (viteProd) {
+        await writeTemplate(dest, 'frontend/Dockerfile', viteProd, vars)
+        await write(dest, 'frontend/nginx.conf', `server {\n  listen 8080;\n  server_tokens off;\n  root /usr/share/nginx/html;\n  add_header X-Content-Type-Options nosniff always;\n  add_header Referrer-Policy strict-origin-when-cross-origin always;\n  add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;\n  add_header Content-Security-Policy "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'" always;\n  location /assets/ { try_files $uri =404; add_header Cache-Control "public, max-age=31536000, immutable"; }\n  location /api/ { add_header Cache-Control "no-store" always; try_files $uri =404; }\n  location / { index index.html; try_files $uri $uri/ /index.html; add_header Cache-Control "no-cache"; }\n}\n`)
+      }
+    }
+    if (stack.backendKey === 'springboot') {
+      const backendProd = await readTemplate(templatesDir, 'docker/dockerfile', 'springboot.prod', '.dockerfile')
+      if (backendProd) await writeTemplate(dest, 'backend/Dockerfile', backendProd, vars)
+      const composeProd = await readTemplate(templatesDir, 'docker/compose-prod', 'springboot', '.yml')
+      if (composeProd) await writeTemplate(dest, 'docker-compose.prod.yml', composeProd, vars)
+    }
+    if (stack.backendKey === 'fastapi') {
+      const apiRoot = stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+      const backendProd = await readTemplate(templatesDir, 'docker/dockerfile', 'fastapi.prod', '.dockerfile')
+      if (backendProd) await writeTemplate(dest, `${apiRoot}Dockerfile`, backendProd, vars)
+      const composeProd = await readTemplate(templatesDir, 'docker/compose-prod', 'fastapi', '.yml')
+      if (composeProd) {
+        const rendered = stack.frontendKey === 'no-frontend'
+          ? composeProd.replaceAll('context: ./backend', 'context: .')
+          : composeProd
+        await writeTemplate(dest, 'docker-compose.prod.yml', rendered, vars)
+      }
+    }
+    if (stack.backendKey === 'laravel') {
+      const laravelRoot = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '' : 'backend/'
+      const laravelProd = await readTemplate(templatesDir, 'docker/dockerfile', 'laravel.prod', '.dockerfile')
+      if (laravelProd) await writeTemplate(dest, `${laravelRoot}Dockerfile`, laravelProd, vars)
+    }
+  }
+
   // PR template
   if (answers.githubActions) {
     await write(dest, '.github/PULL_REQUEST_TEMPLATE.md', prTemplate())
@@ -206,6 +269,45 @@ async function generateRootFiles(dest, answers, vars, stack, templatesDir) {
 
 // ─── Doc placeholders ─────────────────────────────────────────────────────────
 
+function toolchainGuide(answers, stack) {
+  const javascriptRoot = stack.frontendKey === 'react' ? 'frontend/' : ''
+  const hasJavaScript = stack.frontendKey !== 'no-frontend' &&
+    !(stack.frontendKey === 'laravel-ui' && stack.laravelUi !== 'inertia-react')
+  const rows = []
+  if (hasJavaScript) {
+    rows.push(`| Node.js | ${stack.profile.runtimes.nodeMinimum}+ (tested ${stack.profile.runtimes.node}) | JavaScript application | \`${javascriptRoot}.node-version\`, \`${javascriptRoot}package.json\` |`)
+    rows.push(`| npm | ${stack.profile.runtimes.npmMinimum}+ | Local package scripts | \`${javascriptRoot}package.json#packageManager\`, \`${javascriptRoot}.npmrc\` |`)
+  }
+  if (stack.backendKey === 'springboot') {
+    rows.push(`| Java | ${stack.profile.runtimes.java} | Host-run backend | \`backend/.java-version\`, \`backend/pom.xml\` |`)
+    rows.push(`| Maven | ${stack.profile.runtimes.maven} | Optional globally; prefer the generated wrapper | \`backend/mvnw\` or \`backend/mvnw.cmd\` |`)
+  }
+  if (stack.backendKey === 'laravel') {
+    const root = stack.frontendKey === 'laravel-ui' || stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+    rows.push(`| PHP | ${stack.profile.runtimes.php} | Host-run Laravel backend | \`${root}.php-version\` |`)
+    rows.push(`| Composer | ${stack.profile.runtimes.composer} | Host-run Laravel backend | \`${root}composer.json\` |`)
+  }
+  if (stack.backendKey === 'fastapi') {
+    const root = stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+    rows.push(`| Python | ${stack.profile.runtimes.python} | Host-run FastAPI backend | \`${root}.python-version\` |`)
+    rows.push(`| uv | ${stack.profile.runtimes.uv} | Host-run FastAPI backend | \`${root}pyproject.toml\` |`)
+  }
+  if (answers.docker || ['supabase', 'postgres'].includes(stack.backendKey)) {
+    rows.push('| Docker with Compose | Current supported release | Generated containers and local managed services | `docker-compose.yml` when selected |')
+  }
+  return `# Toolchain Requirements\n\nInstall only the tools required by the chosen local workflow. ESLint, Prettier, Prisma, TypeScript, and framework CLIs are project dependencies; run them through npm scripts or \`npx\`, never as global installations.\n\n| Tool | Version | When needed | Version source |\n|---|---|---|---|\n${rows.join('\n')}\n\nDependency retries run inside the generated package directory, so npm reads this project's own \`package.json\`, lockfile, engines, and \`.npmrc\`. Different projects can retain different tested dependency versions without global conflicts.\n\n## Host ports\n\nBefore starting containers, check whether the default ports are already in use (for example, \`ss -ltn\` on Linux). Override conflicts when launching Compose with \`FRONTEND_HOST_PORT\`, \`BACKEND_HOST_PORT\`, or \`POSTGRES_HOST_PORT\`; container ports and service-to-service addresses remain unchanged.\n`
+}
+
+function developmentEnvironmentGuide(answers, stack) {
+  const mobile = stack.isMobile
+    ? '\n## Mobile boundary\n\nRun Expo, the iOS Simulator or Android Emulator, and physical-device tooling on the host. Containers may run a selected backend and database, but they do not replace the local device/emulator workflow.\n'
+    : ''
+  const docker = answers.docker
+    ? `\n## Optional Docker workflow\n\nDocker Engine 27 or newer with Docker Compose v2.30 or newer is recommended. Allocate at least 4 GB of memory and 10 GB of free disk space for images, caches, and databases. Check occupied ports before startup with \`ss -ltn\` (Linux) or your platform's equivalent.\n\n\`\`\`bash\ndocker compose config\ndocker compose build\ndocker compose up -d\n\`\`\`\n\nOverride host collisions with \`FRONTEND_HOST_PORT\`, \`BACKEND_HOST_PORT\`, and \`POSTGRES_HOST_PORT\`. Backend runtimes and databases stay inside containers, reducing the host tools you need.\n`
+    : '\n## Adding Docker later\n\nDocker files were not selected. Re-run the generator for a fresh project with Docker enabled if you want isolated backend runtimes and databases; the normal host workflow remains fully supported.\n'
+  return `# Development Environments\n\n## Default local workflow\n\nRun the generator directly on the host, then use the commands in \`setup.md\`. Docker is optional and is never required to run create-win-project itself. Local files and package-manager metadata remain the source of truth.\n${docker}${mobile}\n## Dev Containers\n\nA generic Dev Container is intentionally not generated: JavaScript, Java, PHP, and mobile stacks need different host/device boundaries. VS Code and Codespaces users can open the generated repository normally and add a stack-specific Dev Container later without changing the supported local or Compose workflows.\n`
+}
+
 async function generateDocs(dest, answers, stack) {
   const docs = [
     ['docs/api/overview.md',              'API Overview',           'Base URL, authentication method, and response format.'],
@@ -221,6 +323,8 @@ async function generateDocs(dest, answers, stack) {
   for (const [filePath, title, description] of docs) {
     await write(dest, filePath, docPlaceholder(title, description))
   }
+  await write(dest, 'docs/guides/deployment.md', `# Production deployment and rollback\n\nBuild immutable images from the committed lockfiles and deploy \`docker-compose.prod.yml\` where generated. Validate required environment variables before starting; secrets belong in the deployment platform, never images or client bundles. Run readiness checks before routing traffic and allow the documented graceful-shutdown window during replacement.\n\n## Database preflight\n\nBack up PostgreSQL with encryption before migrations, check available connections and migration compatibility, then run migrations as a single release task. Application instances use a bounded connection pool; size the total across replicas below the database limit.\n\n## Rollback\n\nRetain the previous image digest and a compatible database restore point. Stop routing to the failed release, restore the prior image, and restore data only when the migration is not backward compatible. Test restores automatically on a separate database and document retention and recovery ownership.\n`)
+  await write(dest, 'docs/guides/operations.md', `# Operations\n\nEvery request crossing an HTTP boundary receives or creates an \`X-Request-ID\` and returns it in responses. Errors use a stable JSON shape: \`{ "error": { "code": "stable_code", "message": "safe message", "requestId": "..." } }\`. Never expose stack traces.\n\nList endpoints use cursor pagination with explicit maximum page sizes. Outbound calls have connection and response timeouts; retry only bounded idempotent operations with jitter. Readiness checks include required downstream dependencies while liveness checks remain process-local.\n\nCORS uses an explicit origin allowlist. Cookie-authenticated browser writes require SameSite cookies plus CSRF validation; bearer-token APIs do not use wildcard origins with credentials. Static fingerprinted assets are immutable, HTML revalidates, and API/auth responses default to \`no-store\`.\n`)
 
   const frontendRoot = stack.frontendKey === 'react' ? 'frontend/' : ''
   const validation = stack.isMobile
@@ -230,15 +334,37 @@ async function generateDocs(dest, answers, stack) {
 
   const setupPath = path.join(dest, 'docs/guides/setup.md')
   let setupGuide = (await fs.readFile(setupPath, 'utf8'))
-    .replace('Node.js 20 or newer', `Node.js ${stack.profile.runtimes.node}`)
+    .replace('Node.js 20 or newer', `Node.js ${stack.profile.runtimes.nodeMinimum} or newer with npm ${stack.profile.runtimes.npmMinimum} or newer (tested on Node.js ${stack.profile.runtimes.node})`)
     .replace('Java 21 and Maven 3.9, or Docker', `Java ${stack.profile.runtimes.java}; Maven ${stack.profile.runtimes.maven} or Docker is used through the generated launcher`)
     .replace('PostgreSQL 16, or Docker', `PostgreSQL ${stack.profile.runtimes.postgres}, or Docker`)
     .replace('mvn spring-boot:run', './mvnw spring-boot:run  # use mvnw.cmd on Windows')
+  if (stack.backendKey === 'springboot' && !answers.docker) {
+    setupGuide = setupGuide.replace('docker compose up -d db', '# Start PostgreSQL on the host, then configure DATABASE_URL')
+  }
   if (stack.backendKey === 'laravel') {
     const laravelDir = stack.frontendKey === 'laravel-ui' || stack.frontendKey === 'no-frontend' ? '' : 'backend/'
-    setupGuide = `# Local Setup Guide\n\n## Docker-first setup\n\nOnly Docker with Compose is required. Make is optional; every Make target has a direct Docker equivalent.\n\n\`\`\`bash\ncp ${laravelDir}.env.example ${laravelDir}.env\ndocker compose build\ndocker compose up -d\ndocker compose exec backend php artisan key:generate\ndocker compose exec backend php artisan migrate\n\`\`\`\n\nLater runs use \`docker compose up -d\`; rebuilding is explicit with \`docker compose build\`. If Make is available, \`make setup\` performs the first-run sequence and \`make run\` starts existing images without rebuilding.\n\n## Validate\n\n\`\`\`bash\ndocker compose exec backend composer check\n\`\`\`\n\nWhen dependencies are installed outside Docker, commit \`composer.lock\`${stack.frontendKey === 'laravel-ui' && stack.laravelUi === 'inertia-react' ? ' and `package-lock.json`' : ''}.\n`
+    const frontendSetup = stack.frontendKey === 'react'
+      ? '\nIn another terminal:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n'
+      : stack.frontendKey === 'nextjs'
+        ? '\nIn another terminal from the repository root:\n\n```bash\nnpm install\nnpm run dev\n```\n'
+        : stack.frontendKey === 'laravel-ui' && stack.laravelUi === 'inertia-react'
+          ? '\nIn another terminal from the repository root:\n\n```bash\nnpm install\nnpm run dev\n```\n'
+          : ''
+    setupGuide = `# Local Setup Guide\n\n## Default local setup\n\nUse PHP ${stack.profile.runtimes.php}, Composer ${stack.profile.runtimes.composer}, and PostgreSQL ${stack.profile.runtimes.postgres}.\n\n\`\`\`bash\ncd ${laravelDir || '.'}\ncomposer install\ncp .env.example .env\nphp artisan key:generate\nphp artisan migrate\nphp artisan serve\n\`\`\`\n${frontendSetup}${answers.docker ? `\n## Optional Docker setup\n\nFrom the repository root:\n\n\`\`\`bash\ndocker compose build\ndocker compose up -d\ndocker compose exec backend php artisan key:generate\ndocker compose exec backend php artisan migrate\n\`\`\`\n\nLater runs use \`docker compose up -d\`; rebuilding remains explicit.\n` : ''}\n## Validate\n\n\`\`\`bash\n${laravelDir ? `cd ${laravelDir}\n` : ''}composer check\n\`\`\`\n\nCommit \`composer.lock\`${stack.frontendKey === 'laravel-ui' && stack.laravelUi === 'inertia-react' ? ' and `package-lock.json`' : ''}.\n`
+  }
+  if (stack.backendKey === 'fastapi') {
+    const apiDir = stack.frontendKey === 'no-frontend' ? '' : 'backend/'
+    const frontendSetup = stack.frontendKey === 'react'
+      ? '\nIn another terminal:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n'
+      : stack.frontendKey === 'nextjs'
+        ? '\nIn another terminal from the repository root:\n\n```bash\nnpm install\nnpm run dev\n```\n'
+        : ''
+    setupGuide = `# Local Setup Guide\n\n## Default local setup\n\nUse Python ${stack.profile.runtimes.python}, uv ${stack.profile.runtimes.uv}, and PostgreSQL ${stack.profile.runtimes.postgres}.\n\n\`\`\`bash\ncd ${apiDir || '.'}\nuv sync\ncp .env.example .env\nalembic upgrade head\nuv run uvicorn app.main:app --reload\n\`\`\`\n${frontendSetup}${answers.docker ? `\n## Optional Docker setup\n\nFrom the repository root:\n\n\`\`\`bash\ndocker compose build\ndocker compose up -d\ndocker compose exec backend uv run alembic upgrade head\n\`\`\`\n\nLater runs use \`docker compose up -d\`; rebuilding remains explicit.\n` : ''}\n## Validate\n\n\`\`\`bash\n${apiDir ? `cd ${apiDir}\n` : ''}uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest\n\`\`\`\n\nCommit the generated \`uv.lock\`; CI uses \`uv sync --frozen\`.\n`
+    setupGuide = setupGuide.replace('\nalembic upgrade head\n', '\nuv run alembic upgrade head\n')
   }
   await fs.writeFile(setupPath, setupGuide, 'utf8')
+  await write(dest, 'docs/guides/toolchain.md', toolchainGuide(answers, stack))
+  await write(dest, 'docs/guides/development-environments.md', developmentEnvironmentGuide(answers, stack))
 
   const envLocation = stack.frontendKey === 'react' ? '`frontend/.env` for client values' : stack.isMobile ? '`.env`' : '`.env.local`'
   await write(dest, 'docs/guides/env-variables.md', `# Environment Variables\n\nCopy the generated example before starting. Client environment location: ${envLocation}.\n\n| Variable | Visibility | Required | Purpose |\n|---|---|---:|---|\n${stack.env.map((name) => `| \`${name}\` | ${name.startsWith(stack.envPrefix) ? 'client/public' : 'server only'} | yes | ${environmentPurpose(name)} |`).join('\n')}\n\nValues with \`${stack.envPrefix}\` are bundled into client code and must never contain secrets. Keep real environment files out of version control.\n`)
@@ -251,7 +377,9 @@ async function generateDocs(dest, answers, stack) {
     ? 'GET http://localhost:8080/api/health'
     : stack.backendKey === 'laravel'
       ? 'GET http://localhost:8000/api/health'
-      : stack.frontendKey === 'nextjs' ? 'GET /api/health' : '(No custom HTTP API is generated for this client-only starter.)'
+      : stack.backendKey === 'fastapi'
+        ? 'GET http://localhost:8000/health'
+        : stack.frontendKey === 'nextjs' ? 'GET /api/health' : '(No custom HTTP API is generated for this client-only starter.)'
   await write(dest, 'docs/api/overview.md', `# API Overview\n\n## Health\n\n\`${health}\`\n\nAuthentication and authorization behavior is documented in \`docs/architecture/auth-flow.md\`. Add endpoints to \`docs/api/endpoints.md\` in the same change that adds their implementation and tests.\n`)
 }
 
@@ -259,7 +387,7 @@ function environmentPurpose(name) {
   if (name.endsWith('SUPABASE_URL')) return 'Supabase project URL.'
   if (name.endsWith('SUPABASE_PUBLISHABLE_KEY')) return 'Public Supabase key; RLS protects data.'
   if (name.endsWith('API_URL')) return 'Base URL of the application API.'
-  if (name === 'DATABASE_URL') return 'Server-side PostgreSQL JDBC connection URL.'
+  if (name === 'DATABASE_URL') return 'Server-side PostgreSQL connection URL.'
   if (name === 'POSTGRES_USER') return 'Local/deployed database user.'
   if (name === 'POSTGRES_PASSWORD') return 'Database credential; replace the development example.'
   if (name === 'POSTGRES_DB') return 'Database name.'
@@ -267,7 +395,10 @@ function environmentPurpose(name) {
   if (name === 'SPRING_SECURITY_USER_NAME') return 'Development-only generated Spring login name; replace with the product identity store.'
   if (name === 'SPRING_SECURITY_USER_PASSWORD') return 'Development-only Spring login credential; never commit a real value.'
   if (name === 'OIDC_ISSUER_URI') return 'Trusted OpenID Connect issuer used to validate access tokens.'
+  if (name === 'OIDC_ISSUER') return 'Trusted OpenID Connect issuer used to validate access tokens.'
   if (name === 'OIDC_AUDIENCE') return 'Required audience for tokens accepted by this API.'
+  if (name === 'OIDC_ALGORITHMS') return 'Allowed signing algorithms for accepted access tokens.'
+  if (name === 'OIDC_JWKS_URL') return 'JWKS endpoint for access-token signature validation; defaults to the issuer well-known location.'
   if (name === 'SESSION_DOMAIN') return 'Exact domain scope for the secure session cookie.'
   if (name === 'SANCTUM_STATEFUL_DOMAINS') return 'Comma-separated first-party browser hosts allowed to use Sanctum session authentication.'
   if (name === 'CORS_ALLOWED_ORIGINS') return 'Exact browser origins allowed to make credentialed API requests.'
@@ -285,11 +416,24 @@ function authDocumentation(stack) {
   if (stack.authentication === 'laravel-session') return `# Authentication Flow\n\nLaravel owns the website session. Login regenerates the session identifier, logout invalidates the session and rotates the CSRF token, and protected routes use server-side authorization. The browser receives an HttpOnly session cookie; there is no browser refresh token. Keep CSRF protection enabled for every cookie-authenticated mutation.\n`
   if (stack.authentication === 'sanctum-spa') return `# Authentication Flow\n\nLaravel Sanctum uses Laravel's secure session cookie for this first-party browser application. The SPA first requests \`/sanctum/csrf-cookie\`, then sends credentialed login and API requests. Sanctum does not give this browser a custom bearer/refresh-token system. Configure exact stateful domains and CORS origins, and enforce resource authorization in Laravel.\n`
   if (stack.authentication === 'laravel-oidc') return `# Authentication Flow\n\nAuth0 owns login, access/refresh-token issuance, rotation, revocation, and recovery. Clients use Authorization Code with PKCE. Laravel uses the pinned Auth0 resource-server adapter to accept access tokens only and validate signature, issuer, audience, and time claims. Refresh tokens never go to this API. Configure \`AUTH0_DOMAIN\` and \`AUTH0_AUDIENCE\`; resource ownership and permission checks remain application responsibilities.\n`
+  if (stack.backendKey === 'fastapi') return `# Authentication Flow\n\nAn external OpenID Connect provider owns login, access/refresh token issuance, rotation, revocation, and recovery. Clients use Authorization Code with PKCE. FastAPI validates bearer access tokens: issuer, audience, algorithm, JWKS signature, expiry, and required claims on every protected request. Refresh tokens never go to the FastAPI resource API. Configure \`OIDC_ISSUER\` and \`OIDC_AUDIENCE\`, then test invalid and authorized tokens.\n`
   return `# Authentication Flow\n\nAn external OpenID Connect provider owns login, access/refresh token issuance, rotation, revocation, and recovery. Clients use Authorization Code with PKCE. Spring is an OAuth2 Resource Server: it accepts bearer access tokens and validates signature, issuer, audience, time, and authorities. Refresh tokens never go to the Spring resource API. Configure \`OIDC_ISSUER_URI\` and \`OIDC_AUDIENCE\`, then test invalid and authorized tokens.\n`
 }
 
 // ─── CI — template-driven ─────────────────────────────────────────────────────
 
+function generatedSecurityWorkflow(stack) {
+  const hasJavaScript = stack.frontendKey !== 'no-frontend' &&
+    !(stack.frontendKey === 'laravel-ui' && stack.laravelUi !== 'inertia-react')
+  const npmDirectory = stack.frontendKey === 'react' ? 'frontend' : '.'
+  const laravelDirectory = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '.' : 'backend'
+  const codeqlLanguages = [hasJavaScript && 'javascript-typescript', stack.backendKey === 'springboot' && 'java-kotlin'].filter(Boolean)
+  const npmAudit = hasJavaScript ? `\n  npm-audit:\n    runs-on: ubuntu-latest\n    defaults:\n      run:\n        working-directory: ${npmDirectory}\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4\n        with:\n          node-version: "${stack.profile.runtimes.node}"\n          cache: npm\n          cache-dependency-path: ${npmDirectory === '.' ? 'package-lock.json' : `${npmDirectory}/package-lock.json`}\n      - run: npm ci\n      - run: npm audit --audit-level=high\n` : ''
+  const composerAudit = stack.backendKey === 'laravel' ? `\n  composer-audit:\n    runs-on: ubuntu-latest\n    defaults:\n      run:\n        working-directory: ${laravelDirectory}\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4\n      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2\n        with:\n          php-version: "${stack.profile.runtimes.php}"\n          coverage: none\n      - run: composer install --no-interaction --prefer-dist\n      - run: composer audit --locked\n` : ''
+  const codeql = codeqlLanguages.length ? `\n  codeql:\n    permissions:\n      contents: read\n      security-events: write\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4\n      - uses: github/codeql-action/init@5ba2889ada762081db2c4f32a729827dce632c7b # v3\n        with:\n          languages: ${codeqlLanguages.join(',')}\n      - uses: github/codeql-action/analyze@5ba2889ada762081db2c4f32a729827dce632c7b # v3\n` : ''
+  return `name: Security\n\non:\n  pull_request:\n    branches: [dev, main]\n  push:\n    branches: [dev, main]\n  schedule:\n    - cron: '31 4 * * 1'\n\npermissions:\n  contents: read\n\njobs:\n  dependency-review:\n    if: github.event_name == 'pull_request'\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4\n      - uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0\n        with:\n          fail-on-severity: high\n\n  secret-scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4\n        with:\n          fetch-depth: 0\n      - uses: trufflesecurity/trufflehog@466da5b0bb161144f6afca9afe5d57975828c410 # v3.90.8\n        with:\n          extra_args: --results=verified,unknown\n${npmAudit}${composerAudit}${codeql}`
+}
+
 async function generateCI(dest, stack, ciDir, answers, vars) {
   // Frontend CI — read from ci/{ciTemplate}.yml
   const feTpl = path.join(ciDir, `${stack.ciTemplate}.yml`)
@@ -339,12 +483,27 @@ async function generateCI(dest, stack, ciDir, answers, vars) {
       await write(dest, `.github/workflows/ci-backend.yml`, render(content, vars))
     }
   }
+  if (stack.backendKey === 'fastapi') {
+    const beTpl = path.join(ciDir, 'fastapi.yml')
+    if (await fs.pathExists(beTpl)) {
+      let content = await fs.readFile(beTpl, 'utf-8')
+      if (stack.frontendKey === 'no-frontend') {
+        content = content.replaceAll('      - backend/**', "      - '**'")
+          .replaceAll('working-directory: backend', 'working-directory: .')
+      }
+      if (answers.testing === 'none') {
+        content = content.replace('      - name: Run tests\n        run: uv run pytest\n', '')
+      }
+      await write(dest, `.github/workflows/ci-backend.yml`, render(content, vars))
+    }
+  }
+  await write(dest, '.github/workflows/security.yml', generatedSecurityWorkflow(stack))
 }
 
 // ─── Runnable application files ─────────────────────────────────────────────────
 
 async function generateRunnableFiles(dest, answers, stack, vars) {
-  const files = { ...buildRunnableFiles(answers, stack, vars), ...buildLaravelFiles(answers, stack, vars) }
+  const files = buildRunnableFiles(answers, stack, vars)
   for (const [filePath, content] of Object.entries(files)) await write(dest, filePath, content)
   if (stack.backendKey === 'springboot') await fs.chmod(path.join(dest, 'backend/mvnw'), 0o755)
   if (stack.backendKey === 'laravel') {
@@ -354,13 +513,3 @@ async function generateRunnableFiles(dest, answers, stack, vars) {
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
-
-async function write(dest, filePath, content) {
-  const fullPath = path.join(dest, filePath)
-  await fs.ensureDir(path.dirname(fullPath))
-  await fs.writeFile(fullPath, content, 'utf-8')
-}
-
-async function writeTemplate(dest, filePath, content, vars) {
-  await write(dest, filePath, render(content, vars))
-}

package/src/stacks/frontends/README.md

@@ -0,0 +1,4 @@
+# Frontend stacks
+
+Frontend implementations move here one focused phase at a time. Until then,
+the compatibility exports keep existing `lib` imports stable.

package/src/stacks/frontends/nextjs/ci.js

@@ -0,0 +1,3 @@
+export function ciContributions() {
+  return [{ template: 'nextjs', path: '.github/workflows/ci-frontend.yml' }]
+}

package/src/stacks/frontends/nextjs/create-files.js

@@ -0,0 +1,46 @@
+/**
+ * Builds the files owned by the Next.js frontend. Shared package, testing,
+ * feature, and backend integration builders are injected by the scaffold
+ * composer so this stack does not depend on unrelated implementations.
+ */
+export function buildNextjsFiles(answers, stack, shared) {
+  const files = {}
+  files['package.json'] = packageFile(answers, stack)
+  files['.node-version'] = `${stack.profile.runtimes.node}\n`
+  files['.npmrc'] = 'engine-strict=true\n'
+  files['tsconfig.json'] = json({
+    compilerOptions: {
+      target: 'ES2017', lib: ['dom', 'dom.iterable', 'esnext'], allowJs: false,
+      skipLibCheck: true, strict: true, noEmit: true, esModuleInterop: true,
+      module: 'esnext', moduleResolution: 'bundler', resolveJsonModule: true,
+      isolatedModules: true, jsx: 'react-jsx', incremental: true,
+      plugins: [{ name: 'next' }], paths: { '@/*': ['./src/*'] },
+    },
+    include: ['next-env.d.ts', '**/*.ts', '**/*.tsx', '.next/types/**/*.ts', '.next/dev/types/**/*.ts'],
+    exclude: ['node_modules'],
+  })
+  files['next-env.d.ts'] = "/// <reference types=\"next\" />\n/// <reference types=\"next/image-types/global\" />\n"
+  files['eslint.config.mjs'] = "import { defineConfig, globalIgnores } from 'eslint/config'\nimport nextVitals from 'eslint-config-next/core-web-vitals'\nimport nextTs from 'eslint-config-next/typescript'\n\nexport default defineConfig([\n  ...nextVitals,\n  ...nextTs,\n  globalIgnores(['.next/**', 'out/**', 'next-env.d.ts']),\n])\n"
+  files['next.config.ts'] = `import type { NextConfig } from 'next'\n\nconst securityHeaders = [\n  { key: 'X-Content-Type-Options', value: 'nosniff' },\n  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },\n  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },\n  { key: 'X-Frame-Options', value: 'DENY' },\n]\n\nconst nextConfig: NextConfig = {\n  reactStrictMode: true,\n  output: 'standalone',\n  async headers() { return [{ source: '/(.*)', headers: securityHeaders }] },\n}\n\nexport default nextConfig\n`
+  files['postcss.config.mjs'] = stack.styleId === 'tailwind'
+    ? "const config = { plugins: { '@tailwindcss/postcss': {} } }\nexport default config\n"
+    : "const config = { plugins: {} }\nexport default config\n"
+  files['src/app/globals.css'] = `${stack.styleId === 'tailwind' ? '@import "tailwindcss";\n\n' : ''}:root { color-scheme: light dark; font-family: system-ui, sans-serif; }\n* { box-sizing: border-box; }\nbody { margin: 0; min-height: 100vh; }\nmain { max-width: 48rem; margin: 0 auto; padding: 4rem 1.5rem; }\na { color: inherit; }\n`
+  files['src/app/layout.tsx'] = `import type { Metadata } from 'next'\nimport type { ReactNode } from 'react'\nimport './globals.css'\n\nexport const metadata: Metadata = { title: ${JSON.stringify(answers.projectName)}, description: ${JSON.stringify(answers.projectDescription)} }\n\nexport default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {\n  return <html lang="en"><body>{children}</body></html>\n}\n`
+  files['src/app/page.tsx'] = stack.architecture === 'small'
+    ? `export default function HomePage() {\n  return (\n    <main>\n      <p>create-win-project</p>\n      <h1>Your starter is running</h1>\n      <p>{${JSON.stringify(answers.projectDescription)}}</p>\n      <p>Read <code>AGENTS.md</code> before your first agent-assisted change.</p>\n    </main>\n  )\n}\n`
+    : `${stack.architecture === 'large'
+      ? "import { getStarterStatus, StarterStatus } from '@/features/status'"
+      : "import { StarterStatus } from '@/features/status/components/StarterStatus'\nimport { getStarterStatus } from '@/features/status/services/getStarterStatus'"}\n\nexport default function HomePage() {\n  const status = getStarterStatus()\n  return <main><p>create-win-project</p><StarterStatus status={status} /><p>{${JSON.stringify(answers.projectDescription)}}</p><p>Read <code>AGENTS.md</code> before your first agent-assisted change.</p></main>\n}\n`
+  files['src/app/api/health/route.ts'] = "export function GET() {\n  return Response.json({ status: 'ok' })\n}\n"
+  files['src/app/page.test.tsx'] = `import { expect, test } from 'vitest'\nimport { render, screen } from '@testing-library/react'\nimport HomePage from './page'\n\ntest('renders the starter heading', () => {\n  render(<HomePage />)\n  expect(screen.getByRole('heading', { name: 'Your starter is running' })).toBeInTheDocument()\n})\n`
+  if ((answers.testing || 'basic') === 'none') delete files['src/app/page.test.tsx']
+  addTestingFiles(files, '', stack, answers.testing || 'basic')
+  Object.assign(files, shared.statusFeatureFiles('', stack))
+  if (stack.backendKey === 'supabase') Object.assign(files, shared.supabaseWebFiles(true, stack.authentication === 'supabase'))
+  if (stack.backendKey === 'postgres') Object.assign(files, shared.prismaFiles())
+  return files
+}
+import { json } from '../../shared/javascript-package.js'
+import { addTestingFiles } from '../../shared/testing-files.js'
+import { packageFile } from './dependencies.js'

package/src/stacks/frontends/nextjs/dependencies.js

@@ -0,0 +1,5 @@
+import { buildJavaScriptPackage } from '../../shared/javascript-package.js'
+
+export function packageFile(answers, stack) {
+  return buildJavaScriptPackage(answers, stack, 'nextjs')
+}

package/src/stacks/frontends/nextjs/docker.js

@@ -0,0 +1,3 @@
+export function dockerContributions() {
+  return [{ template: 'nextjs', developmentPath: 'Dockerfile.dev', productionPath: 'Dockerfile' }]
+}

package/src/stacks/frontends/nextjs/environment.js

@@ -0,0 +1,7 @@
+import { partitionEnvironment, renderEnvironment } from '../../shared/environment.js'
+
+export function buildEnvironmentFiles(answers, stack) {
+  const { publicNames, serverNames } = partitionEnvironment(stack)
+  const names = stack.backendKey === 'supabase' ? stack.env : [...publicNames, ...serverNames]
+  return { '.env.example': renderEnvironment(names, answers) }
+}

package/src/stacks/frontends/nextjs/index.js

@@ -0,0 +1,35 @@
+import { defineStackAdapter } from '../../rules.js'
+import { ciContributions } from './ci.js'
+import { dockerContributions } from './docker.js'
+import { buildNextjsFiles } from './create-files.js'
+
+const verificationCases = Object.freeze([
+  Object.freeze({ backend: 'none', styling: 'tailwind', architecture: 'small', authentication: 'public' }),
+  Object.freeze({ backend: 'postgres', styling: 'tailwind', architecture: 'medium', authentication: 'undecided' }),
+  Object.freeze({ backend: 'supabase', styling: 'tailwind', architecture: 'large', authentication: 'supabase' }),
+  Object.freeze({ backend: 'springboot', styling: 'css-modules', architecture: 'medium', authentication: 'session' }),
+  Object.freeze({ backend: 'laravel', styling: 'tailwind', architecture: 'medium', authentication: 'sanctum-spa' }),
+])
+
+export const nextjsAdapter = defineStackAdapter({
+  id: 'nextjs',
+  kind: 'frontend',
+  label: 'Next.js',
+  compatibleWith: {
+    backend: ['none', 'postgres', 'supabase', 'springboot', 'laravel', 'fastapi'],
+  },
+  capabilities: {
+    applicationShapes: ['fullstack', 'separate'],
+    architectureProfiles: ['small', 'medium', 'large'],
+    authenticationModels: ['public', 'undecided', 'supabase', 'session', 'oidc', 'sanctum-spa', 'laravel-oidc'],
+    runtime: 'node',
+  },
+  contributes: {
+    files: ({ answers, stack, shared }) => Object.entries(buildNextjsFiles(answers, stack, shared)),
+    environment: ({ backend }) => backend.id === 'none' ? [] : ['API_URL'],
+    install: () => [{ cwd: '.', command: 'npm', args: ['install'] }],
+    docker: dockerContributions,
+    ci: ciContributions,
+    verification: () => verificationCases,
+  },
+})

package/src/stacks/frontends/react-native/ci.js

@@ -0,0 +1,3 @@
+export function ciContributions() {
+  return [{ template: 'expo', path: '.github/workflows/ci-frontend.yml' }]
+}

package/src/stacks/frontends/react-native/create-files.js

@@ -0,0 +1,28 @@
+import { json } from '../../shared/javascript-package.js'
+import { addTestingFiles } from '../../shared/testing-files.js'
+import { packageFile } from './dependencies.js'
+
+export function buildReactNativeFiles(answers, stack, shared) {
+  const files = {
+    'package.json': packageFile(answers, stack),
+    '.node-version': `${stack.profile.runtimes.node}\n`,
+    '.npmrc': 'engine-strict=true\n',
+    'app.json': json({ expo: { name: answers.projectName, slug: answers.projectName, version: '1.0.0', orientation: 'portrait', scheme: answers.projectName, userInterfaceStyle: 'automatic', runtimeVersion: { policy: 'appVersion' }, updates: { checkAutomatically: 'ON_LOAD', fallbackToCacheTimeout: 0 }, plugins: stack.authentication === 'supabase' ? ['expo-router', 'expo-secure-store'] : ['expo-router'], experiments: { typedRoutes: true } } }),
+    'eas.json': json({ cli: { version: '>= 16.0.0', appVersionSource: 'remote' }, build: { development: { developmentClient: true, distribution: 'internal', channel: 'development' }, preview: { distribution: 'internal', channel: 'preview' }, production: { autoIncrement: true, channel: 'production' } }, submit: { production: {} } }),
+    'lib/deep-links.ts': `const allowedRoutes = new Set(['/', '/login'])\n\nexport function acceptDeepLink(value: string, scheme = '${answers.projectName}') {\n  try {\n    const url = new URL(value)\n    if (url.protocol !== \`${'${scheme}'}:\`) return false\n    const route = \`/${'${url.host}'}${'${url.pathname}'}\`.replace(/\\/$/, '') || '/'\n    return allowedRoutes.has(route)\n  } catch { return false }\n}\n`,
+    'docs/mobile/production.md': `# Mobile production\n\nEAS development, preview, and production builds use separate channels and environment variables. Keep signing credentials, service-role keys, and privileged operations outside the client. Sessions use platform SecureStore where authentication is enabled. Only allowlisted custom-scheme routes are accepted.\n\nRuntime compatibility follows the app version; publish updates only after testing the matching native runtime. Request the minimum native permissions and keep store privacy disclosures aligned with actual collection. Verify authentication, deep links, notifications, permissions, updates, and offline behavior on physical iOS and Android devices before release.\n`,
+    'tsconfig.json': json({ extends: 'expo/tsconfig.base', compilerOptions: { strict: true, types: ['jest'], paths: { '@/*': ['./*'] } }, include: ['**/*.ts', '**/*.tsx', '.expo/types/**/*.ts', 'expo-env.d.ts'] }),
+    'expo-env.d.ts': "/// <reference types=\"expo/types\" />\n",
+    'app/_layout.tsx': stack.authentication === 'supabase'
+      ? `import { Stack } from 'expo-router'\nimport { useEffect } from 'react'\nimport { bindSupabaseAuthLifecycle } from '@/lib/supabase-lifecycle'\n\nexport default function RootLayout() {\n  useEffect(() => bindSupabaseAuthLifecycle(), [])\n  return <Stack screenOptions={{ headerTitle: '${answers.projectName}' }} />\n}\n`
+      : `import { Stack } from 'expo-router'\n\nexport default function RootLayout() { return <Stack screenOptions={{ headerTitle: '${answers.projectName}' }} /> }\n`,
+    'app/index.tsx': stack.architecture === 'small'
+      ? `import { StyleSheet, Text, View } from 'react-native'\nimport { SafeAreaView } from 'react-native-safe-area-context'\n\nexport default function HomeScreen() {\n  return <SafeAreaView style={styles.safe}><View style={styles.container}><Text>create-win-project</Text><Text accessibilityRole="header">Your starter is running</Text><Text>{${JSON.stringify(answers.projectDescription)}}</Text></View></SafeAreaView>\n}\nconst styles = StyleSheet.create({ safe: { flex: 1 }, container: { flex: 1, justifyContent: 'center', padding: 24, gap: 12 } })\n`
+      : `import { StyleSheet, Text, View } from 'react-native'\nimport { SafeAreaView } from 'react-native-safe-area-context'\n${stack.architecture === 'large'
+        ? "import { getStarterStatus, StarterStatus } from '@/features/status'"
+        : "import { StarterStatus } from '@/features/status/components/StarterStatus'\nimport { getStarterStatus } from '@/features/status/services/getStarterStatus'"}\n\nexport default function HomeScreen() {\n  const status = getStarterStatus()\n  return <SafeAreaView style={styles.safe}><View style={styles.container}><Text>create-win-project</Text><StarterStatus status={status} /><Text>{${JSON.stringify(answers.projectDescription)}}</Text></View></SafeAreaView>\n}\nconst styles = StyleSheet.create({ safe: { flex: 1 }, container: { flex: 1, justifyContent: 'center', padding: 24, gap: 12 } })\n`,
+  }
+  addTestingFiles(files, '', stack, answers.testing || 'basic')
+  Object.assign(files, shared.nativeStatusFeatureFiles(stack))
+  return files
+}

package/src/stacks/frontends/react-native/dependencies.js

@@ -0,0 +1,5 @@
+import { buildJavaScriptPackage } from '../../shared/javascript-package.js'
+
+export function packageFile(answers, stack) {
+  return buildJavaScriptPackage(answers, stack, 'react-native')
+}