create-win-project 1.3.0 → 1.4.0

package/src/stacks/compose-files.js

@@ -0,0 +1,241 @@
+import path from 'node:path'
+import { packageVersion } from './shared/javascript-package.js'
+import { stackRegistry } from './available-stacks.js'
+import { collectContributions } from './shared/contributions.js'
+import { buildSharedTestFiles, buildSupabaseWebFiles } from './backends/supabase/create-files.js'
+import { augmentSupabaseNativeFiles } from './backends/supabase/native.js'
+import { addPostgresScripts, buildPostgresFiles } from './backends/postgres/create-files.js'
+import { buildEnvironmentFiles as nextjsEnvironment } from './frontends/nextjs/environment.js'
+import { buildEnvironmentFiles as reactEnvironment } from './frontends/react-vite/environment.js'
+import { buildEnvironmentFiles as nativeEnvironment } from './frontends/react-native/environment.js'
+import { renderEnvironment } from './shared/environment.js'
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`
+}
+
+function html(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+}
+
+function envFiles(answers, stack) {
+  if (stack.frontendKey === 'no-frontend') {
+    return { '.env.example': renderEnvironment(stack.env, answers) }
+  }
+  if (stack.frontendKey === 'react') return reactEnvironment(answers, stack)
+  if (stack.isMobile) return nativeEnvironment(answers, stack)
+  if (stack.frontendKey === 'nextjs') return nextjsEnvironment(answers, stack)
+  return { '.env.example': renderEnvironment(stack.env, answers) }
+}
+
+function projectReadme(answers, stack) {
+  if (stack.frontendKey === 'no-frontend') {
+    return `# ${answers.projectName}\n\n> ${answers.projectDescription}\n\nGenerated backend-only ${stack.backendLabel} application.\n\n## Start\n\n\`\`\`bash\ncp .env.example .env\ncd backend\n./mvnw spring-boot:run  # use mvnw.cmd on Windows\n\`\`\`\n\n## Validate\n\n\`\`\`bash\ncd backend\n./mvnw --batch-mode test\n./mvnw --batch-mode package -DskipTests\n\`\`\`\n`
+  }
+  const root = stack.frontendKey === 'react' ? 'frontend/' : ''
+  const quality = stack.isMobile
+    ? `npm run typecheck\n${answers.testing === 'none' ? '' : 'npm test -- --runInBand\n'}npm run build -- --platform web`
+    : `npm run lint\nnpm run typecheck\nnpm run test --if-present\nnpm run build`
+  const backend = stack.backendKey === 'springboot'
+    ? `\nThe backend lives in \`backend/\`:\n\n\`\`\`bash\ncd backend\nmvn spring-boot:run\n# verify: curl http://localhost:8080/api/health\n\`\`\`\n`
+    : ''
+  return `# ${answers.projectName}\n\n> ${answers.projectDescription}\n\nGenerated with create-win-project. This repository includes a runnable application, tests, CI guidance, and task-routed agent playbooks.\n\n## Start\n\n\`\`\`bash\n${root ? `cd ${root}\n` : ''}cp .env.example .env.local 2>/dev/null || cp .env.example .env\nnpm install\nnpm run dev\n\`\`\`\n${backend}\n## Validate\n\n\`\`\`bash\n${root ? `cd ${root}\n` : ''}${quality}\n\`\`\`\n\nCommit the generated lockfile before enabling CI; CI intentionally uses \`npm ci\`.\n\n## Agent-assisted work\n\n1. Put product goals and boundaries in \`CONTEXT.md\`.\n2. Read \`AGENTS.md\` for commands and authority boundaries.\n3. Use \`RULES.md\` to open only the relevant playbook section.\n4. Treat tests and application behavior as the source of truth when prose drifts.\n\n## Important files\n\n- \`AGENTS.md\`: small always-on operating contract.\n- \`RULES.md\`: concern-to-playbook router.\n- \`CONTEXT.md\`: project-specific intent and decisions.\n- \`docs/\`: architecture, API, setup, and deployment documentation.\n`
+}
+
+function testingPackage(stack, level) {
+  const scripts = { ...stack.scripts, start: stack.frontendKey === 'nextjs' ? 'next start' : undefined }
+  const devDeps = { ...stack.devDeps }
+
+  if (level === 'none') delete scripts.test
+  if (level !== 'none') {
+    if (stack.isMobile) {
+      Object.assign(devDeps, {
+        jest: packageVersion(stack.profile, 'jest', 'react-native'),
+        '@types/jest': packageVersion(stack.profile, '@types/jest', 'react-native'),
+        'jest-expo': packageVersion(stack.profile, 'jest-expo', 'react-native'),
+        '@testing-library/react-native': packageVersion(stack.profile, '@testing-library/react-native', 'react-native'),
+      })
+    } else {
+      Object.assign(devDeps, {
+        vitest: packageVersion(stack.profile, 'vitest', stack.frontendKey),
+        jsdom: packageVersion(stack.profile, 'jsdom', stack.frontendKey),
+        '@testing-library/react': packageVersion(stack.profile, '@testing-library/react', stack.frontendKey),
+        '@testing-library/jest-dom': packageVersion(stack.profile, '@testing-library/jest-dom', stack.frontendKey),
+      })
+    }
+  }
+  if (level === 'full' && !stack.isMobile) {
+    scripts['test:e2e'] = 'playwright test'
+    devDeps['@playwright/test'] = packageVersion(stack.profile, '@playwright/test', stack.frontendKey)
+  }
+
+  scripts.typecheck = 'tsc --noEmit'
+  scripts.format = 'prettier --write .'
+  scripts['format:check'] = 'prettier --check .'
+  if (!stack.isMobile) scripts.lint = 'eslint .'
+  if (stack.architecture === 'large') scripts['check:boundaries'] = 'node scripts/check-boundaries.mjs'
+  if (stack.backendKey === 'supabase') {
+    const workdir = stack.frontendKey === 'react' ? ' --workdir ..' : ''
+    scripts['supabase:start'] = `supabase${workdir} start`
+    scripts['supabase:stop'] = `supabase${workdir} stop`
+    scripts['supabase:status'] = `supabase${workdir} status`
+    scripts['supabase:reset'] = `supabase${workdir} db reset`
+    scripts['supabase:test'] = `supabase${workdir} test db`
+    const typePath = stack.frontendKey === 'react' ? 'src/types/database.types.ts' : stack.isMobile ? 'types/database.types.ts' : 'src/types/database.types.ts'
+    scripts['supabase:types'] = `supabase${workdir} gen types typescript --local > ${typePath}`
+  }
+  const boundaryCheck = stack.architecture === 'large' ? ' && npm run check:boundaries' : ''
+  scripts.check = stack.isMobile
+    ? `npm run format:check && npm run typecheck${level === 'none' ? '' : ' && npm test -- --runInBand'}${boundaryCheck}`
+    : `npm run format:check && npm run lint && npm run typecheck${level === 'none' ? '' : ' && npm test'}${boundaryCheck}`
+  Object.keys(scripts).forEach((key) => scripts[key] === undefined && delete scripts[key])
+  return { scripts, devDeps }
+}
+
+function packageFile(answers, stack) {
+  const { scripts, devDeps } = testingPackage(stack, answers.testing || 'basic')
+  if (stack.backendKey === 'postgres') {
+    addPostgresScripts(scripts)
+  }
+  if (stack.styleId === 'tailwind') {
+    devDeps.tailwindcss = packageVersion(stack.profile, 'tailwindcss', stack.frontendKey)
+    if (stack.frontendKey === 'nextjs') devDeps['@tailwindcss/postcss'] = packageVersion(stack.profile, '@tailwindcss/postcss', 'nextjs')
+    if (stack.frontendKey === 'react') devDeps['@tailwindcss/vite'] = packageVersion(stack.profile, '@tailwindcss/vite', 'react')
+  }
+  const dependencies = { ...stack.deps }
+  if (stack.frontendKey !== 'nextjs') delete dependencies['@supabase/ssr']
+  if (stack.isMobile && stack.authentication === 'supabase') {
+    dependencies['expo-secure-store'] = packageVersion(stack.profile, 'expo-secure-store', 'react-native')
+  }
+  const packageJson = {
+    name: answers.projectName,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    packageManager: `npm@${stack.profile.runtimes.npmMinimum}`,
+    engines: {
+      node: `>=${stack.profile.runtimes.nodeMinimum}`,
+      npm: `>=${stack.profile.runtimes.npmMinimum}`,
+    },
+    main: stack.isMobile ? 'expo-router/entry' : undefined,
+    scripts,
+    dependencies,
+    devDependencies: devDeps,
+  }
+  if (!packageJson.main) delete packageJson.main
+  return json(packageJson)
+}
+
+function boundaryScript(sourceRoot) {
+  return `/* eslint-disable no-undef -- node script runs outside linted frontend bundle */
+import fs from 'node:fs'\nimport path from 'node:path'\n\nconst root = path.resolve(${JSON.stringify(sourceRoot)}, 'features')\nconst violations = []\nif (fs.existsSync(root)) {\n  for (const feature of fs.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)) {\n    const featureRoot = path.join(root, feature)\n    const visit = (directory) => {\n      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {\n        const file = path.join(directory, entry.name)\n        if (entry.isDirectory()) visit(file)\n        else if (/\\.[cm]?[jt]sx?$/.test(entry.name)) {\n          const content = fs.readFileSync(file, 'utf8')\n          for (const match of content.matchAll(/from\\s+['\"]@\\/features\\/([^/'\"]+)(\\/[^'\"]+)?['\"]/g)) {\n            if (match[1] !== feature && match[2]) violations.push(\`${'${file}'} deep-imports feature ${'${match[1]}'}; import its public API instead\`)\n          }\n        }\n      }\n    }\n    visit(featureRoot)\n  }\n}\nif (violations.length) { console.error(violations.join('\\n')); process.exit(1) }\nconsole.log('Feature boundaries are valid.')\n`
+}
+
+function statusFeatureFiles(root, stack) {
+  if (stack.architecture === 'small') return {}
+  const prefix = root ? `${root}/` : ''
+  const files = {
+    [`${prefix}src/features/status/types.ts`]: "export interface StarterStatus { heading: string; profile: 'medium' | 'large' }\n",
+    [`${prefix}src/features/status/services/getStarterStatus.ts`]: `import type { StarterStatus } from '../types'\n\nexport function getStarterStatus(): StarterStatus {\n  return { heading: 'Your starter is running', profile: '${stack.architecture}' }\n}\n`,
+    [`${prefix}src/features/status/components/StarterStatus.tsx`]: "import type { StarterStatus as Status } from '../types'\n\nexport function StarterStatus({ status }: { status: Status }) {\n  return <><h1>{status.heading}</h1><p>Architecture: {status.profile}</p></>\n}\n",
+  }
+  if (stack.backendKey === 'springboot') {
+    const baseUrl = stack.frontendKey === 'nextjs' ? 'process.env.NEXT_PUBLIC_API_URL' : 'import.meta.env.VITE_API_URL'
+    files[`${prefix}src/features/status/api/getBackendStatus.ts`] = `export interface BackendStatus { status: string }\n\nexport async function getBackendStatus(signal?: AbortSignal): Promise<BackendStatus> {\n  const response = await fetch(\`${'${' + baseUrl + '}'}/api/health\`, { signal })\n  if (!response.ok) throw new Error(\`Backend health request failed (${'${response.status}'})\`)\n  return response.json() as Promise<BackendStatus>\n}\n`
+  }
+  if (stack.architecture === 'large') {
+    files[`${prefix}src/features/status/index.ts`] = "export { StarterStatus } from './components/StarterStatus'\nexport { getStarterStatus } from './services/getStarterStatus'\nexport type { StarterStatus as StarterStatusModel } from './types'\n"
+    files[`${prefix}scripts/check-boundaries.mjs`] = boundaryScript(prefix ? 'src' : 'src')
+  }
+  return files
+}
+
+function nativeStatusFeatureFiles(stack) {
+  if (stack.architecture === 'small') return {}
+  const files = {
+    'features/status/types.ts': "export interface StarterStatus { heading: string; profile: 'medium' | 'large' }\n",
+    'features/status/services/getStarterStatus.ts': `import type { StarterStatus } from '../types'\n\nexport function getStarterStatus(): StarterStatus {\n  return { heading: 'Your starter is running', profile: '${stack.architecture}' }\n}\n`,
+    'features/status/components/StarterStatus.tsx': "import { Text } from 'react-native'\nimport type { StarterStatus as Status } from '../types'\n\nexport function StarterStatus({ status }: { status: Status }) {\n  return <><Text accessibilityRole=\"header\">{status.heading}</Text><Text>Architecture: {status.profile}</Text></>\n}\n",
+  }
+  if (stack.backendKey === 'springboot') {
+    files['features/status/api/getBackendStatus.ts'] = "export interface BackendStatus { status: string }\n\nexport async function getBackendStatus(signal?: AbortSignal): Promise<BackendStatus> {\n  const response = await fetch(`${process.env.EXPO_PUBLIC_API_URL}/api/health`, { signal })\n  if (!response.ok) throw new Error(`Backend health request failed (${response.status})`)\n  return response.json() as Promise<BackendStatus>\n}\n"
+  }
+  if (stack.architecture === 'large') {
+    files['features/status/index.ts'] = "export { StarterStatus } from './components/StarterStatus'\nexport { getStarterStatus } from './services/getStarterStatus'\nexport type { StarterStatus as StarterStatusModel } from './types'\n"
+    files['scripts/check-boundaries.mjs'] = boundaryScript('.')
+  }
+  return files
+}
+
+function supabaseWebFiles(isNext, withAuth = false) {
+  return buildSupabaseWebFiles(isNext, withAuth)
+}
+
+const testFiles = buildSharedTestFiles
+
+function prismaFiles() {
+  return buildPostgresFiles()
+}
+
+function augmentViteFiles(files, stack) {
+  const root = 'frontend'
+  if (stack.backendKey === 'supabase') {
+    for (const [name, value] of Object.entries(supabaseWebFiles(false, stack.authentication === 'supabase'))) files[`${root}/${name}`] = value
+    if (stack.authentication === 'supabase') {
+      files[`${root}/src/features/auth/services/auth.ts`] = `import { supabase } from '@/lib/supabase'\n\nexport async function signIn(email: string, password: string) {\n  const { error } = await supabase.auth.signInWithPassword({ email, password })\n  if (error) throw new Error('Unable to sign in with those credentials.')\n}\n\nexport async function signOut() {\n  const { error } = await supabase.auth.signOut()\n  if (error) throw new Error('Unable to sign out.')\n}\n`
+      files[`${root}/src/features/auth/components/AuthPanel.tsx`] = `import { useState, type FormEvent } from 'react'\nimport { signIn } from '../services/auth'\n\nexport function AuthPanel() {\n  const [error, setError] = useState('')\n  const [pending, setPending] = useState(false)\n  async function submit(event: FormEvent<HTMLFormElement>) {\n    event.preventDefault()\n    setPending(true)\n    setError('')\n    const data = new FormData(event.currentTarget)\n    try { await signIn(String(data.get('email') || ''), String(data.get('password') || '')) }\n    catch (reason) { setError(reason instanceof Error ? reason.message : 'Unable to sign in.') }\n    finally { setPending(false) }\n  }\n  return <section aria-labelledby="login-heading"><h2 id="login-heading">Sign in</h2>{error ? <p role="alert">{error}</p> : null}<form onSubmit={submit}><label>Email <input name="email" type="email" autoComplete="email" required /></label><label>Password <input name="password" type="password" autoComplete="current-password" required /></label><button disabled={pending} type="submit">{pending ? 'Signing in…' : 'Sign in'}</button></form></section>\n}\n`
+      files[`${root}/src/App.tsx`] = `import { AuthPanel } from '@/features/auth/components/AuthPanel'\n${files[`${root}/src/App.tsx`].replace('<p>Read <code>AGENTS.md</code> before your first agent-assisted change.</p>', '<p>Read <code>AGENTS.md</code> before your first agent-assisted change.</p><AuthPanel />')}`
+    }
+  }
+  return files
+}
+
+function nativeFiles(answers, stack) {
+  const files = frontendFiles(answers, stack)
+  augmentSupabaseNativeFiles(files, answers, stack)
+  return files
+}
+
+function frontendFiles(answers, stack) {
+  if (stack.frontendKey === 'no-frontend' || stack.frontendKey === 'laravel-ui') return {}
+  const adapter = stackRegistry.require(stack.frontendKey)
+  return Object.fromEntries(collectContributions([adapter], 'files', {
+    answers,
+    stack,
+    shared: { json, packageFile, testFiles, statusFeatureFiles, nativeStatusFeatureFiles, supabaseWebFiles, prismaFiles },
+  }))
+}
+
+function springFiles(answers, vars, stack) {
+  const adapter = stackRegistry.require(stack.backendKey)
+  return Object.fromEntries(collectContributions([adapter], 'files', { answers, stack, vars }))
+}
+
+export function buildRunnableFiles(answers, stack, vars) {
+  let files = stack.isMobile ? nativeFiles(answers, stack) : frontendFiles(answers, stack)
+  if (stack.frontendKey === 'react') files = augmentViteFiles(files, stack)
+  Object.assign(files, envFiles(answers, stack))
+  files['create-win-project.profile.json'] = json({
+    schemaVersion: 3,
+    applicationShape: stack.applicationShape,
+    compatibilityProfile: {
+      id: stack.profile.id,
+      status: stack.profile.status,
+      supportedUntil: stack.profile.supportedUntil,
+    },
+    architectureProfile: stack.architecture,
+    authentication: {
+      intent: stack.authenticationIntent,
+      model: stack.authentication,
+      audience: stack.authAudience,
+    },
+    stack: stack.key,
+    runtimes: stack.profile.runtimes,
+  })
+  files['README.md'] = projectReadme(answers, stack)
+  if (stack.backendKey === 'springboot') {
+    files['README.md'] = files['README.md'].replace('mvn spring-boot:run', './mvnw spring-boot:run  # use mvnw.cmd on Windows')
+  }
+  if (stackRegistry.get(stack.backendKey)) Object.assign(files, springFiles(answers, vars, stack))
+  return files
+}

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

@@ -1,39 +1,32 @@
 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'
 
 /**
  * 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 +43,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 +72,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) {
@@ -135,6 +122,11 @@ 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 === '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) {
@@ -206,6 +198,40 @@ 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 (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.'],
@@ -230,15 +256,27 @@ 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`
   }
   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`)
@@ -344,7 +382,7 @@ async function generateCI(dest, stack, ciDir, answers, vars) {
 // ─── 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 +392,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'],
+  },
+  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,25 @@
+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', plugins: stack.authentication === 'supabase' ? ['expo-router', 'expo-secure-store'] : ['expo-router'], experiments: { typedRoutes: true } } }),
+    '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')
+}

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

@@ -0,0 +1,5 @@
+// Expo runs on the host with a simulator or physical device. The mobile
+// frontend intentionally contributes no container image.
+export function dockerContributions() {
+  return []
+}