create-win-project 1.3.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,118 @@
+# Architecture
+
+`create-win-project` composes a validated project specification into two coordinated outputs:
+
+1. a small executable application that establishes the stack's real conventions;
+2. a task-routed documentation layer for humans and coding agents.
+
+Executable behavior, tests, and framework configuration are the source of truth. Playbooks explain and extend that behavior; they must not contradict it.
+
+## Generation pipeline
+
+```text
+CLI interview
+    ↓
+validated answers
+    ↓
+manifest catalog + compatibility resolver
+    ↓
+resolved stack descriptor
+    ├── runnable framework files
+    ├── optional CI / Docker / Makefile files
+    ├── project context and documentation
+    └── selected playbooks + RULES.md router
+    ↓
+generated-project contract tests
+```
+
+### CLI boundary
+
+`index.js` owns interaction and presentation. It gathers project identity, frontend, optional backend, styling, one Small/Medium/Large architecture profile, login intent, client audience when relevant, testing depth, and optional operational tooling. Medium is shown first and is the default. It does not contain stack dependency tables.
+
+`generateProject()` validates the same answers again because it is also an exported programmatic API. A caller cannot bypass destination-name, Java-package, or testing-profile validation by skipping the CLI.
+
+### Catalog and resolution
+
+`lib/catalog.js` loads co-located `*.manifest.json` files and merges selected capabilities into one stack descriptor. `lib/compatibility.js` validates `compatibility/profiles.json` and resolves every package name to an exact version for the selected profile.
+
+Stack-specific behavior crosses into core orchestration through the contract in `lib/stacks/contract.js`. Every frontend, backend, or data adapter has a stable identity, declares compatible adapters and supported application/authentication/architecture models, and is added to the explicit registry. Registration is deliberate; adapters are never discovered by scanning directories.
+
+Adapters may contribute data in these areas:
+
+- questions in a core-defined prompt slot;
+- authentication models;
+- generated file descriptions;
+- environment declarations;
+- install steps;
+- Docker and CI fragments;
+- verification cases.
+
+Core code owns prompt order, compatibility-profile resolution, atomic writes, process execution, and final composition. An adapter receives a read-only stack context and returns contributions; it cannot write arbitrary paths or install global tools. Adapter definitions do not accept dependency tables or version fields. Exact versions remain exclusively owned by `compatibility/profiles.json`.
+
+Manifests declare:
+
+- identity and compatibility (`id`, `kind`, `appliesTo`);
+- dependency names and scripts (never dependency versions);
+- semantic environment names and which ones are client-visible;
+- supported architecture profiles, conditional playbooks, and optional templates;
+- constraints shown to the agent;
+- concerns and their playbook sections.
+
+Client environment variables are semantic in manifests (`API_URL`) and receive exactly one framework prefix during resolution (`NEXT_PUBLIC_API_URL`, `VITE_API_URL`, or `EXPO_PUBLIC_API_URL`). Public prefixes always mean the value is shipped to the client.
+
+### Runnable scaffold
+
+`lib/scaffold.js` owns the minimum executable vertical slice:
+
+- Next.js: route-oriented Small; familiar feature services/actions/queries and owned repositories or remote API clients in Medium; public feature APIs and enforced boundaries in Large.
+- React + Vite: thin browser features in Small, feature modules in Medium, and public feature APIs plus boundary checks in Large.
+- Expo: screens/data in Small, feature modules in Medium, and boundaries ready for offline sync, background work, and platform adapters in Large.
+- Spring Boot: conventional package-by-feature in Small, explicit API/service/repository ownership in Medium, and a verified Spring Modulith modular monolith in Large.
+
+Authentication is selected during generation. Supabase emits Supabase Auth clients and login examples; website-only Spring uses a secure server-managed session; multi-client Spring emits an OIDC Resource Server and delegates issuance, refresh, and revocation to the identity provider. `Not yet` is fail-closed for Spring and never emits pretend authentication. Existing projects are never told to rerun the generator to add auth.
+
+This module intentionally generates a small working example. Domain-specific features are added after product context is known; the generator does not invent business entities.
+
+### Repository and operational files
+
+`lib/generator.js` coordinates writes and refuses to merge into a non-empty destination. It adds documentation, selected playbooks, CI, Docker, Makefile, environment examples, and repository conventions around the runnable foundation.
+
+The first `npm install` creates the lockfile. Generated CI uses `npm ci`, so the lockfile must be committed before CI is enabled. `create-win-project.profile.json` separately records the compatibility profile, architecture profile, and authentication intent/model/audience; after generation, that project owns its own upgrade lifecycle.
+
+### Compatibility profile lifecycle
+
+Exactly one profile is `current` and one is `previous`. The current profile is the default. A profile owns exact npm, Spring Boot, runtime, and container versions; manifests and scaffold code may only request names or capabilities. Promotion copies the candidate into a new dated profile, marks the former current profile previous, and happens only after the generated-project matrix passes. Major changes also require migration notes. See `DEPENDENCY_MAINTENANCE.md`.
+
+## Documentation model
+
+| File | Responsibility |
+|------|----------------|
+| `AGENTS.md` | Small always-on command, workflow, safety, and definition-of-done contract. |
+| `CONTEXT.md` | Product goals, boundaries, decisions, and project-specific facts. |
+| `RULES.md` | Generated concern-to-playbook section router. |
+| `playbooks/` | Reusable standards, recipes, rationale, and stack guidance. |
+| `docs/` | Documentation for the generated product, not generic framework teaching. |
+
+Manifest section names are checked against Markdown headings. Numbered headings are normalized for matching, and generated contract tests reject unresolved `RULES.md` entries.
+
+## Testing strategy
+
+The generator itself has three verification levels:
+
+1. unit tests for catalog composition and template rendering;
+2. generated-output contract tests for required files, environment naming, playbook routing, profile-specific boundaries, auth metadata/code, testing profiles, and overwrite safety;
+3. a current-and-previous matrix across every supported stack combination, all three architecture profiles, and every applicable authentication model. It installs and runs lint, typecheck, tests, builds, Expo compatibility checks/web export, Spring MVC/security/Modulith tests and Maven packaging, Compose validation, and current-profile container builds.
+
+Canonical Markdown code examples should progressively move into extracted fixtures so examples compile against the versions they teach.
+
+## Extension workflow
+
+When adding a stack or capability:
+
+1. Add its manifest, all five stack facets, and any platform/capability routes.
+2. Add the smallest runnable files needed in `lib/scaffold.js` or a focused scaffold module.
+3. Add every supported architecture/authentication combination to the generated-output matrix.
+4. Run install, lint/typecheck, tests, and production build for the new fixture.
+5. Update this architecture document if ownership or the generation pipeline changed.
+
+Do not advertise a capability solely because a playbook mentions it. A generated capability must have executable configuration and contract coverage.

package/docs/CONTENT_MODEL.md

@@ -0,0 +1,36 @@
+# Content Model
+
+The project separates always-loaded instructions, task-routed standards, generated product documentation, and executable examples. Each fact should have one owner.
+
+| Content | Owner | Include when |
+|---|---|---|
+| Agent commands, workflow, authority limits, definition of done | `templates/agents/*.md` → generated `AGENTS.md` | Every project; keep short |
+| Product goal, scope, decisions, unknowns | generated `CONTEXT.md` | Every project; project-specific |
+| Concern routing | manifests → generated `RULES.md` | Selected stack/capability only |
+| Reusable engineering policy and rationale | `playbooks/**/*.md` | A task touches that concern |
+| Setup, API, architecture, deployment for this product | generated `docs/` | Every project, then maintained with code |
+| Framework configuration and canonical patterns | `lib/scaffold.js` output plus tests | The capability is selected |
+
+## Authoring rules
+
+1. Put a rule in the narrowest applicable playbook. Do not repeat it in `AGENTS.md`, `README.md`, and stack guides.
+2. Write normative language only for behavior the generator configures or tests. Label uninstalled libraries and alternative architectures as optional.
+3. Route concerns to exact Markdown headings from their manifest. Heading changes and manifest changes belong in the same commit.
+4. Prefer a compact rule, a reason, and one canonical example. Remove tutorial-length alternatives that compete with the default.
+5. Keep secrets, authentication, authorization, validation, accessibility, and failure behavior at explicit trust boundaries.
+6. Product docs describe the generated application. Playbooks teach reusable practices; they must not invent product endpoints or entities.
+7. Code and executable tests win when prose conflicts. Fix the prose in the same change.
+8. Stack guides always use the five-facet contract: `architecture.md`, `structure.md`, `runtime.md`, `security.md`, and `testing.md`.
+9. Universal guidance cannot claim browser, mobile, Spring, or provider-specific behavior. Route it through `platform/`, `stack/`, or `capabilities/`.
+
+## Review checklist
+
+- Does this content have exactly one authoritative home?
+- Is it selected only for stacks where it applies?
+- Does every `RULES.md` section resolve?
+- Are packages/configuration used by examples actually generated, or clearly marked optional?
+- Can a new developer run the documented commands from the stated directory?
+- Do auth examples cover storage, refresh/expiry, CSRF/CORS, authorization, revocation, and failure paths appropriate to that session model?
+- Would moving a long example into a compile-tested fixture reduce drift?
+
+When adding a stack, implement all three profiles, all five facets, a runnable vertical slice for each profile, relevant auth mappings, and matrix entries before advertising support.

package/docs/DEPENDENCY_MAINTENANCE.md

@@ -0,0 +1,31 @@
+# Dependency maintenance
+
+`compatibility/profiles.json` is the only owner of versions emitted into generated applications. Stack and concern manifests declare package names and capabilities, never ranges or versions. Direct npm dependencies are generated as exact versions, and consumers commit the lockfile created by their first install.
+
+## Profile policy
+
+- Keep exactly one `current` and one `previous` profile.
+- Use a dated, immutable profile ID (`YYYY.MM`). Do not silently rewrite a released profile used by generated projects.
+- Build a new candidate from the current profile. Promote it only when the complete generated-project workflow passes.
+- Keep a support date and successor link on the previous profile.
+- Require explicit review and migration notes for every major runtime, framework, or package upgrade.
+- Treat Expo, React Native, its React override, and related Expo packages as one atomic set. `CI=1 npx expo install --check` is a release gate.
+
+The two initial profiles intentionally bootstrap from the same known-good set. Future promotions preserve the old current profile unchanged as the meaningful previous fallback.
+
+## Automated proposals
+
+Renovate scans only the current profile and opens weekly grouped proposals for web frameworks, Expo, Prisma, testing, TypeScript/lint, Spring Boot, and runtime/container versions. Security alerts are allowed immediately. A Renovate PR is a proposal, not proof of compatibility: CI must pass before merge.
+
+When a runtime and its container image must move together, update both in the same PR. Catalog validation rejects mismatched Node, Java, Maven, or PostgreSQL ownership and rejects ranges, missing versions, duplicate dependency ownership, and unknown package requests.
+
+## Promotion checklist
+
+1. Create the new dated candidate profile; leave the retained previous profile unchanged.
+2. Review upstream release and migration notes, especially for majors.
+3. Run `npm test` and the compatibility workflow for every stack, architecture profile, and applicable authentication model.
+4. Confirm Expo install and auth-lifecycle checks, browser production builds and Playwright, Spring MVC/security/Modulith tests and Maven packages, Supabase RLS tests, Compose parsing, npm package contents, and container builds.
+5. Mark the candidate `current`, the former current `previous`, and remove profiles older than the supported previous profile.
+6. Summarize breaking changes and required migrations in the PR.
+
+Generated projects do not automatically follow catalog updates. Their profile record explains their starting point; they manage later dependency upgrades independently.

package/index.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+import inquirer from 'inquirer'
+import chalk from 'chalk'
+import ora from 'ora'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { spawnSync } from 'node:child_process'
+import { generateProject } from './lib/generator.js'
+import { loadCompatibility } from './lib/compatibility.js'
+import { printDoctor } from './lib/doctor.js'
+import { configurationDecisionChoices, promptWithBack } from './lib/interview.js'
+import { projectLocationNotice } from './lib/project-location.js'
+import { w1nBanner } from './lib/banner.js'
+import {
+  loadCatalog, resolveStack,
+  stylingChoicesFor, architectureChoicesFor,
+} from './lib/catalog.js'
+import {
+  APPLICATION_SHAPES,
+  applicationShapeChoices,
+  backendChoicesForShape,
+  frontendChoicesForShape,
+} from './lib/application-shapes.js'
+import { laravelUiPromptContribution, laravelUis } from './lib/stacks/laravel/ui/index.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const cliArgs = process.argv.slice(2)
+const profileArg = cliArgs.find((arg) => arg.startsWith('--profile='))?.split('=')[1]
+const shapeArg = cliArgs.find((arg) => arg.startsWith('--shape='))?.split('=')[1]
+const frontendValue = cliArgs.find((arg) => arg.startsWith('--frontend='))?.split('=')[1]
+const backendArg = cliArgs.find((arg) => arg.startsWith('--backend='))?.split('=')[1]
+const frontendAliases = { vite: 'react', expo: 'react-native', none: 'no-frontend' }
+const frontendArg = frontendAliases[frontendValue] || frontendValue
+const architectureArg = cliArgs.find((arg) => arg.startsWith('--architecture='))?.split('=')[1]
+const authenticationArg = cliArgs.find((arg) => arg.startsWith('--authentication='))?.split('=')[1]
+const authAudienceArg = cliArgs.find((arg) => arg.startsWith('--auth-audience='))?.split('=')[1]
+const laravelUiArg = cliArgs.find((arg) => arg.startsWith('--laravel-ui='))?.split('=')[1]
+if (shapeArg && !APPLICATION_SHAPES[shapeArg]) {
+  throw new Error('--shape must be fullstack, separate, api, mobile, or frontend')
+}
+if (architectureArg && !['small', 'medium', 'large'].includes(architectureArg)) {
+  throw new Error('--architecture must be small, medium, or large')
+}
+if (authenticationArg && !['yes', 'not-yet', 'none'].includes(authenticationArg)) {
+  throw new Error('--authentication must be yes, not-yet, or none')
+}
+if (authAudienceArg && !['website', 'multi-client'].includes(authAudienceArg)) {
+  throw new Error('--auth-audience must be website or multi-client')
+}
+if (laravelUiArg && !laravelUis.some((ui) => ui.id === laravelUiArg)) {
+  throw new Error('--laravel-ui must be blade, livewire, or inertia-react')
+}
+const wantsInstall = cliArgs.includes('--install')
+const skipsInstall = cliArgs.includes('--no-install')
+if (wantsInstall && skipsInstall) throw new Error('Use either --install or --no-install, not both')
+const { profile } = await loadCompatibility(
+  path.join(__dirname, 'compatibility/profiles.json'),
+  profileArg,
+)
+if (cliArgs[0] === 'doctor' || cliArgs.includes('--doctor')) {
+  printDoctor(profile)
+  process.exit(0)
+}
+const catalog = await loadCatalog(path.join(__dirname, 'playbooks'), profile)
+
+// ─── Banner ──────────────────────────────────────────────────────────────────
+
+console.log('')
+console.log(w1nBanner())
+console.log('')
+console.log(chalk.gray('  Production-ready project scaffolding'))
+console.log(chalk.gray(`  Compatibility profile: ${profile.id} (${profile.status})`))
+console.log('')
+
+// ─── Interview ───────────────────────────────────────────────────────────────
+
+const questions = [
+  {
+    type: 'list',
+    name: 'applicationShape',
+    message: 'What kind of application are you building?',
+    choices: applicationShapeChoices(),
+    default: 'fullstack',
+    when: () => !shapeArg,
+  },
+  // ── Always-on ──────────────────────────────────────────────────────────
+  {
+    type: 'input',
+    name: 'projectName',
+    message: 'Project name?',
+    default: 'my-project',
+    validate: (v) => {
+      if (!v.trim()) return 'Project name is required'
+      if (!/^[a-z0-9-]+$/.test(v)) return 'Use lowercase letters, numbers, and hyphens only'
+      return true
+    },
+  },
+  {
+    type: 'input',
+    name: 'projectDescription',
+    message: 'One-line description?',
+    default: 'A new application',
+  },
+
+  // ── Stack selection (catalog-driven) ───────────────────────────────────
+  {
+    type: 'list',
+    name: 'frontend',
+    message: 'Which application framework or frontend?',
+    choices: (a) => frontendChoicesForShape(shapeArg || a.applicationShape, catalog),
+    when: () => !frontendArg,
+  },
+  {
+    type: 'list',
+    name: 'backend',
+    message: 'Which backend or data service?',
+    choices: (a) => backendChoicesForShape(shapeArg || a.applicationShape, a.frontend, catalog),
+    when: () => !backendArg,
+  },
+  ...laravelUiPromptContribution(laravelUiArg).questions,
+
+  // ── Styling: only shown when frontend has >1 option (catalog-driven) ───
+  {
+    type: 'list',
+    name: 'styling',
+    message: 'Styling approach?',
+    choices: (a) => stylingChoicesFor(catalog, a.frontend),
+    when: (a) => stylingChoicesFor(catalog, a.frontend).length > 1,
+  },
+
+  // ── One architecture profile, interpreted natively by every stack ──────
+  {
+    type: 'list',
+    name: 'architecture',
+    message: 'Architecture? (Medium is recommended for most long-term applications)',
+    choices: (a) => {
+      const supported = architectureChoicesFor(catalog, a.frontend, a.backend)
+      return [
+        { name: 'Medium (Recommended) — clear feature, service, and data boundaries', value: 'medium' },
+        { name: 'Small — fewer layers for prototypes and simple applications', value: 'small' },
+        { name: 'Large — enforced boundaries for complex domains and larger teams', value: 'large' },
+      ].filter((choice) => supported.includes(choice.value))
+    },
+    default: 'medium',
+    when: () => !architectureArg,
+  },
+
+  // ── Authentication intent, expressed without protocol jargon ───────────
+  {
+    type: 'list',
+    name: 'authentication',
+    message: 'Does your application need user login?',
+    choices: (a) => {
+      const choices = []
+      if (a.backend === 'supabase' || a.backend === 'springboot' || a.backend === 'laravel') {
+        choices.push({ name: 'Yes — generate authentication appropriate for this stack', value: 'yes' })
+      }
+      choices.push(
+        { name: 'Not yet (Recommended) — add guidance without pretending login exists', value: 'not-yet' },
+        { name: 'No — this application is intentionally public and has no user accounts', value: 'none' },
+      )
+      return choices
+    },
+    default: 'not-yet',
+    when: () => !authenticationArg,
+  },
+  {
+    type: 'list',
+    name: 'authAudience',
+    message: 'Where will users access the application?',
+    choices: [
+      { name: 'Website only — use a secure server-managed browser session', value: 'website' },
+      { name: 'Website and mobile — use a trusted identity provider for every client', value: 'multi-client' },
+    ],
+    default: 'website',
+    when: (a) => ['springboot', 'laravel'].includes(a.backend) && a.frontend !== 'laravel-ui' && (authenticationArg || a.authentication) === 'yes' && !authAudienceArg,
+  },
+
+  // ── Testing ────────────────────────────────────────────────────────────
+  {
+    type: 'list',
+    name: 'testing',
+    message: 'Testing setup?',
+    choices: (a) => {
+      const fe = catalog.byId[a.frontend]
+      if (fe?.platform === 'mobile') {
+        return [
+          { name: 'Basic  (Jest + React Native Testing Library)', value: 'basic' },
+          { name: 'None',                                          value: 'none' },
+        ]
+      }
+      return [
+        { name: 'Full   (Vitest + React Testing Library + Playwright)', value: 'full' },
+        { name: 'Basic  (Vitest + React Testing Library)',               value: 'basic' },
+        { name: 'None',                                                  value: 'none' },
+      ]
+    },
+    default: (a) => {
+      const fe = catalog.byId[a.frontend]
+      return fe?.platform === 'mobile' ? 'basic' : 'full'
+    },
+  },
+
+  // ── DevOps extras ──────────────────────────────────────────────────────
+  {
+    type: 'confirm',
+    name: 'docker',
+    message: 'Include Docker?',
+    default: true,
+    when: (a) => {
+      const fe = catalog.byId[a.frontend]
+      const be = catalog.byId[a.backend]
+      return (be?.needsDocker ?? fe?.needsDocker ?? false)
+    },
+  },
+  {
+    type: 'confirm',
+    name: 'makefile',
+    message: 'Include Makefile?',
+    default: true,
+    when: (a) => {
+      // Makefile is useful for web stacks; less relevant for bare mobile
+      const fe = catalog.byId[a.frontend]
+      return fe?.platform !== 'mobile'
+    },
+  },
+  {
+    type: 'confirm',
+    name: 'githubActions',
+    message: 'Include GitHub Actions CI?',
+    default: true,
+  },
+  {
+    type: 'confirm',
+    name: 'installDependencies',
+    message: 'Install project dependencies and create the lockfile now?',
+    default: true,
+    when: () => !wantsInstall && !skipsInstall,
+  },
+
+  // ── Spring Boot specific ───────────────────────────────────────────────
+  {
+    type: 'input',
+    name: 'packageName',
+    message: 'Java package name? (e.g. com.yourname)',
+    default: 'com.app',
+    when: (a) => a.backend === 'springboot',
+    validate: (v) => {
+      if (!v.trim()) return 'Package name is required'
+      if (!/^[a-z]+(\.[a-z]+)+$/.test(v)) return 'Use format: com.yourname'
+      return true
+    },
+  },
+
+  // ── Optional concerns (filtered to current stack) ──────────────────────
+  {
+    type: 'checkbox',
+    name: 'expectedConcerns',
+    message: 'Expected optional concerns? (advisory only — all stay available)',
+    choices: (a) => {
+      const stack = resolveStack({ ...a, styling: a.styling || catalog.byId[a.frontend]?.stylingOptions?.[0] }, catalog)
+      const opts = new Set()
+      for (const c of stack.concerns) if (!c.required) opts.add(c.id)
+      return [...opts].map((id) => ({ name: id, value: id }))
+    },
+  },
+]
+let answers = {
+  applicationShape: shapeArg,
+  frontend: frontendArg,
+  backend: backendArg,
+}
+let stack
+while (true) {
+answers = await promptWithBack(inquirer, questions, answers)
+answers.compatibilityProfile = profile.id
+answers.applicationShape = shapeArg || answers.applicationShape
+answers.architecture = architectureArg || answers.architecture || 'medium'
+answers.authentication = authenticationArg || answers.authentication || 'not-yet'
+answers.authAudience = authAudienceArg || answers.authAudience || (catalog.byId[answers.frontend]?.platform === 'mobile' ? 'multi-client' : 'website')
+answers.laravelUi = laravelUiArg || answers.laravelUi || (answers.frontend === 'laravel-ui' ? 'blade' : undefined)
+if (wantsInstall) answers.installDependencies = true
+if (skipsInstall) answers.installDependencies = false
+
+// ── Auto-resolve docker for stacks that need it ───────────────────────────────
+if (resolveStack({ ...answers, styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0] || 'tailwind' }, catalog).needsDocker) {
+  answers.docker = answers.docker ?? true
+}
+
+stack = resolveStack({ ...answers, styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0] || 'tailwind' }, catalog)
+
+// ─── Confirm ─────────────────────────────────────────────────────────────────
+
+console.log('')
+console.log(chalk.bold('  Summary'))
+console.log(chalk.gray('  ───────────────────────────'))
+console.log(`  ${chalk.cyan('Name:')}         ${answers.projectName}`)
+console.log(`  ${chalk.cyan('Stack:')}        ${stack.label}`)
+console.log(`  ${chalk.cyan('Shape:')}        ${APPLICATION_SHAPES[stack.applicationShape].label}`)
+console.log(`  ${chalk.cyan('Platform:')}     ${stack.platform}`)
+if (stack.styleId) {
+  console.log(`  ${chalk.cyan('Styling:')}      ${catalog.byId[stack.styleId]?.label || stack.styleId}`)
+}
+if (answers.laravelUi) console.log(`  ${chalk.cyan('Laravel UI:')}   ${answers.laravelUi}`)
+console.log(`  ${chalk.cyan('Architecture:')} ${stack.architecture[0].toUpperCase()}${stack.architecture.slice(1)}`)
+console.log(`  ${chalk.cyan('Authentication:')} ${stack.authentication}`)
+console.log(`  ${chalk.cyan('Testing:')}      ${answers.testing}`)
+if (stack.platform !== 'mobile') {
+  console.log(`  ${chalk.cyan('Docker:')}       ${answers.docker ? 'yes' : 'no'}`)
+  console.log(`  ${chalk.cyan('Makefile:')}     ${answers.makefile ? 'yes' : 'no'}`)
+}
+console.log(`  ${chalk.cyan('CI/CD:')}        ${answers.githubActions ? 'yes' : 'no'}`)
+console.log(`  ${chalk.cyan('Install deps:')} ${answers.installDependencies ? 'yes' : 'no'}`)
+if (answers.packageName) {
+  console.log(`  ${chalk.cyan('Package:')}      ${answers.packageName}`)
+}
+if (stack.constraints.length) {
+  console.log('')
+  console.log(chalk.gray('  Key constraints:'))
+  for (const rule of stack.constraints.slice(0, 3)) {
+    console.log(chalk.gray(`  • ${rule}`))
+  }
+}
+console.log('')
+
+const { decision } = await inquirer.prompt([{
+  type: 'list', name: 'decision', message: 'Ready?', choices: configurationDecisionChoices(),
+}])
+
+if (decision === 'back') {
+  continue
+}
+if (decision === 'cancel') {
+  console.log(chalk.yellow('\n  Cancelled.\n'))
+  process.exit(0)
+}
+break
+}
+
+// ─── Generate ────────────────────────────────────────────────────────────────
+
+console.log('')
+const spinner = ora('Scaffolding project...').start()
+
+try {
+  await generateProject(answers, __dirname)
+  spinner.succeed(chalk.green('Project created!'))
+  const locationNotice = projectLocationNotice({ cwd: process.cwd(), cliRoot: __dirname, projectName: answers.projectName })
+  if (locationNotice) {
+    console.log('')
+    console.log(chalk.yellow.bold('  Project location note'))
+    console.log(chalk.yellow(`  ${locationNotice.message}`))
+    console.log(chalk.gray(`  Created at: ${locationNotice.generatedPath}`))
+    console.log(chalk.gray(`  Suggested destination: ${locationNotice.suggestedPath}`))
+    console.log(chalk.gray(`  Linux/macOS: mv "${locationNotice.generatedPath}" "${locationNotice.suggestedPath}"`))
+    console.log(chalk.gray(`  Windows: cut the generated folder in File Explorer and paste it into your projects folder.`))
+  }
+  if (answers.installDependencies) {
+    const projectRoot = path.join(process.cwd(), answers.projectName)
+    const steps = []
+    if (stack.backendKey === 'laravel') {
+      const laravelRoot = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? projectRoot : path.join(projectRoot, 'backend')
+      steps.push({ command: process.platform === 'win32' ? 'composer.bat' : 'composer', args: ['install'], cwd: laravelRoot, retry: `cd ${path.relative(process.cwd(), laravelRoot)} && composer install` })
+    }
+    const needsNpm = stack.frontendKey !== 'no-frontend' && (stack.frontendKey !== 'laravel-ui' || answers.laravelUi === 'inertia-react')
+    if (needsNpm) {
+      const npmRoot = stack.frontendKey === 'react' ? path.join(projectRoot, 'frontend') : projectRoot
+      steps.push({ command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: ['install'], cwd: npmRoot, retry: `cd ${path.relative(process.cwd(), npmRoot)} && npm install` })
+    }
+    const installSpinner = ora('Installing exact dependencies and creating lockfiles...').start()
+    const failed = steps.find((step) => spawnSync(step.command, step.args, { cwd: step.cwd, stdio: 'inherit', shell: false }).status !== 0)
+    if (failed) {
+      installSpinner.warn(chalk.yellow('Project created, but dependency installation did not finish.'))
+      console.log(chalk.yellow(`  Retry with: ${failed.retry}`))
+    } else {
+      installSpinner.succeed(chalk.green('Dependencies installed and lockfiles created.'))
+    }
+  }
+  console.log('')
+  console.log(chalk.bold(`  Next steps:`))
+  console.log(chalk.gray(`  cd ${answers.projectName}`))
+
+  if (stack.backendKey === 'laravel') {
+    const laravelDir = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '' : 'backend/'
+    console.log(chalk.gray(`  cp ${laravelDir}.env.example ${laravelDir}.env`))
+    if (answers.makefile) {
+      console.log(chalk.gray(`  make setup  # first run only`))
+      console.log(chalk.gray(`  make run    # later runs; never rebuilds`))
+    } else {
+      console.log(chalk.gray(`  docker compose build`))
+      console.log(chalk.gray(`  docker compose up -d`))
+    }
+  } else if (stack.frontendKey === 'react') {
+    if (stack.backendKey === 'springboot') {
+      console.log(chalk.gray(`  cp .env.example .env  # Docker/backend values`))
+    }
+    console.log(chalk.gray(`  cd frontend`))
+    console.log(chalk.gray(`  cp .env.example .env`))
+    if (!answers.installDependencies) console.log(chalk.gray(`  npm install`))
+  } else {
+    console.log(chalk.gray(`  cp .env.example ${stack.isMobile ? '.env' : '.env.local'}`))
+    if (!answers.installDependencies) console.log(chalk.gray(`  npm install`))
+  }
+
+  if (stack.backendKey === 'laravel') {
+    // Laravel commands were printed above because its root differs by application shape.
+  } else if (stack.isMobile) {
+    console.log(chalk.gray(`  npx expo start`))
+  } else if (answers.makefile) {
+    if (stack.frontendKey === 'react') {
+      console.log(chalk.gray(`  cd ..`))
+    }
+    console.log(chalk.gray(`  make dev`))
+  } else if (stack.backendKey === 'supabase') {
+    console.log(chalk.gray(`  npm run supabase:start`))
+    console.log(chalk.gray(`  npm run dev`))
+  } else if (stack.frontendKey === 'react') {
+    console.log(chalk.gray(`  npm run dev`))
+  } else {
+    console.log(chalk.gray(`  docker compose up -d db`))
+    console.log(chalk.gray(`  npm run dev`))
+  }
+
+  console.log('')
+  console.log(chalk.cyan(`  Read RULES.md before starting — it maps every playbook for this stack.`))
+  console.log('')
+} catch (err) {
+  spinner.fail(chalk.red('Failed to generate project'))
+  console.error(err)
+  process.exit(1)
+}