create-win-project 1.3.0 → 2.0.0

package/src/cli/arguments.js

@@ -0,0 +1,63 @@
+import { APPLICATION_SHAPES } from '../engine/project-shapes.js'
+import { laravelUis } from '../stacks/backends/laravel/ui/index.js'
+
+function option(args, name) {
+  return args.find((argument) => argument.startsWith(`--${name}=`))?.split('=')[1]
+}
+
+export function parseArguments(args) {
+  const upgradeReportIndex = args.indexOf('upgrade-report')
+  const profile = option(args, 'profile')
+  const shape = option(args, 'shape')
+  const frontendValue = option(args, 'frontend')
+  const frontendAliases = { vite: 'react', expo: 'react-native', none: 'no-frontend' }
+  const frontend = frontendAliases[frontendValue] || frontendValue
+  const backend = option(args, 'backend')
+  const architecture = option(args, 'architecture')
+  const authentication = option(args, 'authentication')
+  const authAudience = option(args, 'auth-audience')
+  const laravelUi = option(args, 'laravel-ui')
+  const uploads = option(args, 'uploads')
+  const backgroundJobs = option(args, 'background-jobs')
+  const offline = option(args, 'offline')
+  const install = args.includes('--install')
+  const noInstall = args.includes('--no-install')
+
+  if (shape && !APPLICATION_SHAPES[shape]) {
+    throw new Error('--shape must be fullstack, separate, api, mobile, or frontend')
+  }
+  if (architecture && !['small', 'medium', 'large'].includes(architecture)) {
+    throw new Error('--architecture must be small, medium, or large')
+  }
+  if (authentication && !['yes', 'not-yet', 'none'].includes(authentication)) {
+    throw new Error('--authentication must be yes, not-yet, or none')
+  }
+  if (authAudience && !['website', 'multi-client'].includes(authAudience)) {
+    throw new Error('--auth-audience must be website or multi-client')
+  }
+  if (laravelUi && !laravelUis.some((ui) => ui.id === laravelUi)) {
+    throw new Error('--laravel-ui must be blade, livewire, or inertia-react')
+  }
+  if (uploads && !['none', 'object-storage'].includes(uploads)) throw new Error('--uploads must be none or object-storage')
+  if (backgroundJobs && !['none', 'queue'].includes(backgroundJobs)) throw new Error('--background-jobs must be none or queue')
+  if (offline && !['none', 'cache', 'sync'].includes(offline)) throw new Error('--offline must be none, cache, or sync')
+  if (install && noInstall) throw new Error('Use either --install or --no-install, not both')
+
+  return Object.freeze({
+    profile,
+    shape,
+    frontend,
+    backend,
+    architecture,
+    authentication,
+    authAudience,
+    laravelUi,
+    uploads,
+    backgroundJobs,
+    offline,
+    install,
+    noInstall,
+    doctor: args[0] === 'doctor' || args.includes('--doctor'),
+    upgradeReportPath: upgradeReportIndex >= 0 ? (args[upgradeReportIndex + 1] || '.') : undefined,
+  })
+}

package/src/cli/display.js

@@ -0,0 +1,220 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { APPLICATION_SHAPES } from '../engine/project-shapes.js'
+import path from 'node:path'
+
+// ─── Banner (from lib/banner.js) ────────────────────────────────────────────
+const W1N = [
+  ' ██╗    ██╗  ██╗ ███╗  ██╗',
+  ' ██║    ██║ ███║ ████╗ ██║',
+  ' ██║ █╗ ██║ ╚██║ ██╔██╗██║',
+  ' ██║███╗██║  ██║ ██║╚████║',
+  ' ╚███╔███╔╝  ██║ ██║ ╚███║',
+  '  ╚══╝╚══╝   ╚═╝ ╚═╝  ╚══╝',
+]
+const PROJECT = [
+  ' █▀█ █▀█ █▀█   █ █▀▀ █▀▀ ▀█▀',
+  ' █▀▀ █▀█ █ █   █ █▀  █    █ ',
+  ' █   █ █ █▄█ █▄█ █▄▄ █▄▄  █ ',
+]
+function plain() {
+  return [...W1N, '', ...PROJECT].join('\n')
+}
+function colored() {
+  const w1n = W1N.map((l) => chalk.bold.cyan(l)).join('\n')
+  const proj = PROJECT.map((l) => chalk.bold.white(l)).join('\n')
+  return `${w1n}\n${proj}`
+}
+export function w1nBanner() {
+  const noColor = process.env.NO_COLOR !== undefined || process.env.FORCE_COLOR === '0'
+  const isTTY = process.stdout.isTTY
+  const width = process.stdout.columns || 80
+  if (!isTTY || width < 80 || noColor) {
+    if (width < 60) return 'W1N PROJECT'
+    return plain()
+  }
+  return colored()
+}
+export const bannerRaw = plain()
+export const W1N_ART = W1N.join('\n')
+export const PROJECT_ART = PROJECT.join('\n')
+
+// ─── Project location (from src/engine/project-location.js) ─────────────────
+export function isInsideDirectory(candidate, parent) {
+  const relative = path.relative(path.resolve(parent), path.resolve(candidate))
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+export function projectLocationNotice({ cwd, cliRoot, projectName }) {
+  if (!isInsideDirectory(cwd, cliRoot)) return null
+  const generatedPath = path.join(path.resolve(cwd), projectName)
+  const suggestedPath = path.join(path.dirname(path.resolve(cliRoot)), projectName)
+  return {
+    generatedPath,
+    suggestedPath,
+    message: `This project was created inside the create-win-project repository. Move or cut the generated folder to your normal projects folder outside this repository before you start committing application work.`,
+  }
+}
+
+// ─── Display helpers ─────────────────────────────────────────────────────────
+export function printBanner(profile, output = console.log) {
+  output('')
+  output(w1nBanner())
+  output('')
+  output(chalk.gray('  Production-ready project scaffolding'))
+  output(chalk.gray(`  Compatibility profile: ${profile.id} (${profile.status})`))
+  output('')
+}
+
+export function printCancelled({ explainNoFiles = false } = {}, output = console.log) {
+  output(chalk.yellow(explainNoFiles ? '\n  Cancelled. No files were created.\n' : '\n  Cancelled.\n'))
+}
+
+export function startProjectSpinner() {
+  return ora('Scaffolding project...').start()
+}
+
+export function projectSucceeded(spinner) {
+  spinner.succeed(chalk.green('Project created!'))
+}
+
+export function startInstallSpinner() {
+  return ora('Installing exact dependencies and creating lockfiles...').start()
+}
+
+export function installSucceeded(spinner) {
+  spinner.succeed(chalk.green('Dependencies installed and lockfiles created.'))
+}
+
+export function installFailed(spinner) {
+  spinner.warn(chalk.yellow('Project created, but dependency installation did not finish.'))
+}
+
+export function generationFailed(spinner, error, report = console.error) {
+  spinner.fail(chalk.red('Failed to generate project'))
+  report(error)
+  report(chalk.yellow('Review the error above, correct the input or environment, then run create-win-project again.'))
+}
+
+export function printSummary({ answers, stack, catalog }, output = console.log) {
+  output('')
+  output(chalk.cyan.bold('  Review before creating files'))
+  output(chalk.gray('  ───────────────────────────'))
+  output(`  ${chalk.cyan('Name:')}         ${answers.projectName}`)
+  output(`  ${chalk.cyan('Stack:')}        ${stack.label}`)
+  output(`  ${chalk.cyan('Shape:')}        ${APPLICATION_SHAPES[stack.applicationShape].label}`)
+  output(`  ${chalk.cyan('Platform:')}     ${stack.platform}`)
+  if (stack.styleId) output(`  ${chalk.cyan('Styling:')}      ${catalog.byId[stack.styleId]?.label || stack.styleId}`)
+  if (answers.laravelUi) output(`  ${chalk.cyan('Laravel UI:')}   ${answers.laravelUi}`)
+  output(`  ${chalk.cyan('Architecture:')} ${stack.architecture[0].toUpperCase()}${stack.architecture.slice(1)}`)
+  output(`  ${chalk.cyan('Authentication:')} ${stack.authentication}`)
+  output(`  ${chalk.cyan('Testing:')}      ${answers.testing}`)
+  if (stack.platform !== 'mobile') {
+    output(`  ${chalk.cyan('Docker:')}       ${answers.docker ? 'yes' : 'no'}`)
+    output(`  ${chalk.cyan('Makefile:')}     ${answers.makefile ? 'yes' : 'no'}`)
+  }
+  output(`  ${chalk.cyan('CI/CD:')}        ${answers.githubActions ? 'yes' : 'no'}`)
+  output(`  ${chalk.cyan('Install deps:')} ${answers.installDependencies ? 'yes' : 'no'}`)
+  if (answers.packageName) output(`  ${chalk.cyan('Package:')}      ${answers.packageName}`)
+  if (stack.constraints.length) {
+    output('')
+    output(chalk.gray('  Key constraints:'))
+    for (const rule of stack.constraints.slice(0, 3)) output(chalk.gray(`  • ${rule}`))
+  }
+  output('')
+}
+
+export function printRuntimeMismatch(issues, output = console.log) {
+  output(chalk.yellow.bold('\n  Runtime mismatch\n'))
+  for (const issue of issues) {
+    output(chalk.yellow(`  ${issue.tool} ${issue.required} or newer is required.`))
+    output(chalk.gray(`  Current terminal: ${issue.tool} ${issue.found || 'not found'}.`))
+  }
+  output(chalk.gray('\n  Your global tools will not be changed.\n'))
+}
+
+export function printRuntimeInstructions(lines, output = console.log) {
+  output(chalk.cyan.bold('\n  Runtime setup\n'))
+  for (const line of lines) output(chalk.gray(`  ${line}`))
+  output(chalk.gray('\n  Run create-win-project again after switching runtimes.\n'))
+}
+
+export function printRuntimeSkip(issues, output = console.log) {
+  output(chalk.yellow('\n  Dependency installation will be skipped because this terminal does not meet the selected project requirements.'))
+  for (const issue of issues) output(chalk.gray(`  ${issue.tool}: ${issue.found || 'not found'} (requires ${issue.required} or newer)`))
+  output(chalk.gray('  Project files will still be created. Use Mise/NVM, then run the retry command shown below.\n'))
+}
+
+export function printLocationNotice(notice, output = console.log) {
+  if (!notice) return
+  output('')
+  output(chalk.yellow.bold('  Project location note'))
+  output(chalk.yellow(`  ${notice.message}`))
+  output(chalk.gray(`  Created at: ${notice.generatedPath}`))
+  output(chalk.gray(`  Suggested destination: ${notice.suggestedPath}`))
+  output(chalk.gray(`  Linux/macOS: mv "${notice.generatedPath}" "${notice.suggestedPath}"`))
+  output(chalk.gray('  Windows: cut the generated folder in File Explorer and paste it into your projects folder.'))
+}
+
+function detectedLine(versions) {
+  return `  Detected Node.js ${versions.node || 'not found'}, npm ${versions.npm || 'not found'}, PHP ${versions.php || 'not found'}, and Composer ${versions.composer || 'not found'}.`
+}
+
+export function printInstallFailure(versions, retry, output = console.log) {
+  output(chalk.yellow(detectedLine(versions)))
+  output(chalk.yellow(`  Retry with: ${retry}`))
+}
+
+export function printInstallSkipped(versions, steps, output = console.log) {
+  output(chalk.yellow('  Project files were created without installing dependencies.'))
+  output(chalk.gray(detectedLine(versions)))
+  for (const step of steps) output(chalk.gray(`  Retry with: ${step.retry}`))
+}
+
+export function printNextSteps(answers, stack, output = console.log) {
+  output('')
+  output(chalk.bold('  Next steps:'))
+  output(chalk.gray(`  cd ${answers.projectName}`))
+  if (stack.backendKey === 'laravel') {
+    const laravelDir = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '' : 'backend/'
+    output(chalk.gray(`  cp ${laravelDir}.env.example ${laravelDir}.env`))
+    if (answers.makefile) {
+      output(chalk.gray('  make setup  # first run only'))
+      output(chalk.gray('  make run    # later runs; never rebuilds'))
+    } else {
+      output(chalk.gray('  docker compose build'))
+      output(chalk.gray('  docker compose up -d'))
+    }
+  } else if (stack.frontendKey === 'react') {
+    if (stack.backendKey === 'springboot') output(chalk.gray('  cp .env.example .env  # Docker/backend values'))
+    output(chalk.gray('  cd frontend'))
+    output(chalk.gray('  cp .env.example .env'))
+    if (!answers.installDependencies) output(chalk.gray('  npm install'))
+  } else {
+    output(chalk.gray(`  cp .env.example ${stack.isMobile ? '.env' : '.env.local'}`))
+    if (!answers.installDependencies) output(chalk.gray('  npm install'))
+  }
+  if (stack.backendKey !== 'laravel') {
+    if (stack.isMobile) output(chalk.gray('  npx expo start'))
+    else if (answers.makefile) {
+      if (stack.frontendKey === 'react') output(chalk.gray('  cd ..'))
+      output(chalk.gray('  make dev'))
+    } else if (stack.backendKey === 'supabase') {
+      output(chalk.gray('  npm run supabase:start'))
+      output(chalk.gray('  npm run dev'))
+    } else if (stack.frontendKey === 'react') output(chalk.gray('  npm run dev'))
+    else {
+      output(chalk.gray('  docker compose up -d db'))
+      output(chalk.gray('  npm run dev'))
+    }
+  }
+  output('')
+  output(chalk.cyan('  Read RULES.md before starting — it maps every playbook for this stack.'))
+  output('')
+}
+
+export function printSupportPrompt(output = console.log) {
+  output(chalk.gray('  ───────────────────────────'))
+  output(chalk.gray('  Enjoyed this starter? ⭐ Star https://github.com/itsw1n/create-win-project'))
+  output(chalk.gray('  Found a gap or idea? Open an issue: https://github.com/itsw1n/create-win-project/issues/new'))
+  output('')
+}

package/src/cli/main.js

@@ -0,0 +1,203 @@
+import inquirer from 'inquirer'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { generateProject } from '../engine/create-project.js'
+import { runDependencySteps } from '../engine/install-dependencies.js'
+import { loadCompatibility } from '../engine/tested-versions.js'
+import { buildQuestions, configurationDecisionChoices, lastEnabledIndex, promptWithBack } from './questions.js'
+import {
+  printBanner,
+  generationFailed,
+  installFailed,
+  installSucceeded,
+  printInstallFailure,
+  printInstallSkipped,
+  printLocationNotice,
+  printNextSteps,
+  printSupportPrompt,
+  printCancelled,
+  printRuntimeInstructions,
+  printRuntimeMismatch,
+  printRuntimeSkip,
+  printSummary,
+  projectSucceeded,
+  projectLocationNotice,
+  startInstallSpinner,
+  startProjectSpinner,
+} from './display.js'
+import { parseArguments } from './arguments.js'
+import { createUpgradeReport } from '../engine/upgrade-report.js'
+import {
+  loadCatalog, resolveStack,
+} from '../engine/load-library.js'
+import {
+  decideInstallation,
+  detectSystemVersions,
+  installationIssues,
+  runtimeSetupInstructions,
+  printDoctor,
+} from './system-check.js'
+
+const cliDirectory = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(cliDirectory, '../..')
+
+export async function runCli() {
+const args = parseArguments(process.argv.slice(2))
+const profileArg = args.profile
+const shapeArg = args.shape
+const frontendArg = args.frontend
+const backendArg = args.backend
+const architectureArg = args.architecture
+const authenticationArg = args.authentication
+const authAudienceArg = args.authAudience
+const laravelUiArg = args.laravelUi
+const uploadsArg = args.uploads
+const backgroundJobsArg = args.backgroundJobs
+const offlineArg = args.offline
+const wantsInstall = args.install
+const skipsInstall = args.noInstall
+if (args.upgradeReportPath) {
+  const report = await createUpgradeReport(args.upgradeReportPath, path.join(projectRoot, 'library/tested-versions.json'))
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  return
+}
+const { profile } = await loadCompatibility(
+  path.join(projectRoot, 'library/tested-versions.json'),
+  profileArg,
+)
+if (args.doctor) {
+  printDoctor(profile)
+  process.exit(0)
+}
+const catalog = await loadCatalog(path.join(projectRoot, 'library'), profile)
+
+// ─── Banner ──────────────────────────────────────────────────────────────────
+
+printBanner(profile)
+
+// ─── Interview ───────────────────────────────────────────────────────────────
+
+const questions = buildQuestions({ args, catalog })
+let answers = {
+  applicationShape: shapeArg,
+  frontend: frontendArg,
+  backend: backendArg,
+}
+let stack
+let resumeAt = 0
+while (true) {
+answers = await promptWithBack(inquirer, questions, answers, resumeAt)
+resumeAt = 0
+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)
+answers.uploads = uploadsArg || answers.uploads || 'none'
+answers.backgroundJobs = backgroundJobsArg || answers.backgroundJobs || 'none'
+answers.offline = offlineArg || answers.offline || 'none'
+answers.testing = answers.frontend === 'react-native' ? 'basic' : 'full'
+answers.githubActions = true
+if (wantsInstall) answers.installDependencies = true
+if (skipsInstall) answers.installDependencies = false
+
+stack = resolveStack({ ...answers, styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0] || 'tailwind' }, catalog)
+
+// ─── Confirm ─────────────────────────────────────────────────────────────────
+
+printSummary({ answers, stack, catalog })
+
+const { decision } = await inquirer.prompt([{
+  type: 'list', name: 'decision', message: 'Ready?', choices: configurationDecisionChoices(),
+}])
+
+if (decision === 'back') {
+  resumeAt = lastEnabledIndex(questions, answers)
+  continue
+}
+if (decision === 'cancel') {
+  printCancelled()
+  process.exit(0)
+}
+break
+}
+
+const detectedVersions = detectSystemVersions()
+const runtimeIssues = installationIssues(stack, profile, detectedVersions)
+const installationDecision = await decideInstallation({
+  requested: answers.installDependencies,
+  issues: runtimeIssues,
+  interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  choose: async () => {
+    printRuntimeMismatch(runtimeIssues)
+    const { runtimeDecision } = await inquirer.prompt([{
+      type: 'list',
+      name: 'runtimeDecision',
+      message: 'How should create-win-project continue?',
+      choices: [
+        { name: 'Create files and skip dependency installation', value: 'skip' },
+        { name: 'Show runtime setup instructions', value: 'instructions' },
+        { name: 'Cancel', value: 'cancel' },
+      ],
+    }])
+    return runtimeDecision
+  },
+})
+
+if (installationDecision.reason === 'cancelled') {
+  printCancelled({ explainNoFiles: true })
+  process.exit(0)
+}
+if (installationDecision.reason === 'show-instructions') {
+  printRuntimeInstructions(runtimeSetupInstructions(profile, runtimeIssues))
+  process.exit(0)
+}
+if (answers.installDependencies && !installationDecision.install) {
+  printRuntimeSkip(runtimeIssues)
+}
+answers.installDependencies = installationDecision.install
+
+// ─── Generate ────────────────────────────────────────────────────────────────
+
+const spinner = startProjectSpinner()
+
+try {
+  await generateProject(answers, projectRoot)
+  projectSucceeded(spinner)
+  const generatedProjectRoot = path.join(process.cwd(), answers.projectName)
+  const steps = []
+  if (stack.backendKey === 'laravel') {
+    const laravelRoot = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? generatedProjectRoot : path.join(generatedProjectRoot, 'backend')
+    steps.push({ command: process.platform === 'win32' ? 'composer.bat' : 'composer', args: ['install'], cwd: laravelRoot, retry: `cd ${path.relative(process.cwd(), laravelRoot)} && composer install` })
+  }
+  if (stack.backendKey === 'fastapi') {
+    const apiRoot = stack.frontendKey === 'no-frontend' ? generatedProjectRoot : path.join(generatedProjectRoot, 'backend')
+    steps.push({ command: 'uv', args: ['sync'], cwd: apiRoot, retry: `cd ${path.relative(process.cwd(), apiRoot)} && uv sync` })
+  }
+  const needsNpm = stack.frontendKey !== 'no-frontend' && (stack.frontendKey !== 'laravel-ui' || answers.laravelUi === 'inertia-react')
+  if (needsNpm) {
+    const npmRoot = stack.frontendKey === 'react' ? path.join(generatedProjectRoot, 'frontend') : generatedProjectRoot
+    steps.push({ command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: ['install'], cwd: npmRoot, retry: `cd ${path.relative(process.cwd(), npmRoot)} && npm install` })
+  }
+  const locationNotice = projectLocationNotice({ cwd: process.cwd(), cliRoot: projectRoot, projectName: answers.projectName })
+  printLocationNotice(locationNotice)
+  if (answers.installDependencies) {
+    const installSpinner = startInstallSpinner()
+    const { failed } = runDependencySteps(steps)
+    if (failed) {
+      installFailed(installSpinner)
+      printInstallFailure(detectedVersions, failed.retry)
+    } else {
+      installSucceeded(installSpinner)
+    }
+  } else if (installationDecision.reason === 'runtime-mismatch') {
+    printInstallSkipped(detectedVersions, steps)
+  }
+  printNextSteps(answers, stack)
+  if (process.stdout.isTTY) printSupportPrompt()
+} catch (err) {
+  generationFailed(spinner, err)
+  process.exit(1)
+}
+}

package/src/cli/navigation.js

@@ -0,0 +1,156 @@
+import chalk from 'chalk'
+
+const BACK = Symbol('back')
+
+export function wrapText(text, width = Math.max(28, Math.min(72, (process.stdout.columns || 80) - 8))) {
+  const lines = []
+  for (const word of text.split(/\s+/)) {
+    const last = lines.at(-1)
+    if (!last || `${last} ${word}`.length > width) lines.push(word)
+    else lines[lines.length - 1] = `${last} ${word}`
+  }
+  return lines.join('\n  ')
+}
+
+function enabled(question, answers) {
+  return typeof question.when === 'function' ? question.when(answers) : question.when !== false
+}
+
+async function resolved(value, answers) {
+  return typeof value === 'function' ? value(answers) : value
+}
+
+function clearFrom(questions, answers, index) {
+  for (let cursor = index; cursor < questions.length; cursor += 1) {
+    delete answers[questions[cursor].name]
+  }
+}
+
+/**
+ * Runs Inquirer questions one at a time so users can safely revisit earlier answers.
+ * List/checkbox/confirm prompts expose a visible Back choice; text prompts accept `:back`.
+ */
+export function lastEnabledIndex(questions, answers) {
+  let last = 0
+  questions.forEach((question, index) => {
+    if (enabled(question, answers)) last = index
+  })
+  return last
+}
+
+export async function promptWithBack(inquirer, questions, initialAnswers = {}, startIndex = 0) {
+  const answers = { ...initialAnswers }
+  // Seed history with previously asked prompts so Back navigation,
+  // step numbering, and clearFrom targets mirror a natural pass.
+  // Skipped (when:false) prompts are never seeded, exactly as a pass never pushes them.
+  const history = []
+  for (let seed = 0; seed < startIndex; seed += 1) {
+    if (enabled(questions[seed], answers)) history.push(seed)
+  }
+  let index = startIndex
+  let resumeHintShown = startIndex === 0
+
+  while (index < questions.length) {
+    const source = questions[index]
+    if (!enabled(source, answers)) { index += 1; continue }
+
+    const canGoBack = history.length > 0
+    // askAnswered: inquirer skips questions whose answer already exists in
+    // the passed answers object. We always want to ask (re-entry after
+    // Back-and-edit arrives with complete answers); defaults pre-fill
+    // previous values via question.default below.
+    const question = { ...source, when: undefined, askAnswered: true }
+    const title = await resolved(question.message, answers)
+    const controls = question.type === 'checkbox'
+      ? 'Arrow keys move • Space selects (Space on ← Back first) • Enter continues • Back returns'
+      : question.type === 'input'
+        ? 'Type an answer • Enter continues • :back returns'
+        : 'Arrow keys move • Enter selects • Back returns'
+    question.message = `${chalk.cyan.bold(`Step ${history.length + 1} of ${questions.length} - ${title}`)}\n${chalk.dim(controls)}\n`
+    if (!resumeHintShown) {
+      question.message = `${question.message}${chalk.dim('(editing previous answers — choose ← Back to revisit earlier steps, Enter keeps values and returns)\n')}`
+      resumeHintShown = true
+    }
+    if (answers[source.name] !== undefined && question.default === undefined) {
+      question.default = answers[source.name]
+    }
+    if (question.type === 'input' && canGoBack) {
+      question.message = `${question.message} (type :back to return)`
+    }
+    if (question.type === 'input') {
+      // Let the :back sentinel through validation so promptWithBack can
+      // handle it; inquirer validates before returning the value.
+      const originalValidate = question.validate
+      question.validate = (value, answersState) =>
+        value === ':back' ? true : (originalValidate?.(value, answersState) ?? true)
+    }
+    if (question.type === 'confirm') {
+      const defaultValue = await resolved(question.default, answers)
+      question.type = 'list'
+      question.choices = [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+        ...(canGoBack ? [{ name: '← Back', value: BACK }] : []),
+      ]
+      question.default = defaultValue ? 0 : 1
+    } else if (['list', 'checkbox'].includes(question.type)) {
+      const raw = await resolved(question.choices, answers)
+      const rest = raw.filter((choice) => choice?.type !== 'description-footer')
+      const footers = raw
+        .filter((choice) => choice?.type === 'description-footer')
+        .map((footer) => new inquirer.Separator(chalk.dim(wrapText(footer.text))))
+      question.choices = canGoBack
+        ? [...rest, ...footers, new inquirer.Separator(), { name: '← Back', value: BACK }]
+        : [...rest, ...footers]
+    }
+
+    if (typeof question.default === 'function') question.default = await question.default(answers)
+    const result = await inquirer.prompt([question], answers)
+    const value = result[source.name]
+    const requestedBack = value === BACK || value === ':back' || (Array.isArray(value) && value.includes(BACK))
+    if (requestedBack) {
+      const target = history.pop()
+      if (target === undefined) continue
+      clearFrom(questions, answers, target)
+      index = target
+      continue
+    }
+    if (question.type === 'checkbox' && startIndex > 0 && canGoBack) {
+      // Checkbox Enter only confirms checked items, so a highlighted-but-unchecked
+      // ← Back would silently complete the interview instead of going back.
+      // On re-entry runs, ask explicitly (Enter-selectable). Fresh passes keep
+      // the inline Back + Space hint with no extra prompt.
+      const follow = await inquirer.prompt([{
+        type: 'list',
+        name: '__continue',
+        message: 'Continue with these selections?',
+        choices: [
+          { name: 'Continue', value: 'continue' },
+          { name: '← Back', value: BACK },
+        ],
+      }], answers)
+      if (follow.__continue === BACK) {
+        const target = history.pop()
+        if (target !== undefined) {
+          clearFrom(questions, answers, target)
+          index = target
+          continue
+        }
+      }
+    }
+
+    answers[source.name] = value
+    history.push(index)
+    index += 1
+  }
+
+  return answers
+}
+
+export function configurationDecisionChoices() {
+  return [
+    { name: 'Create project\n  Write the reviewed files and selected configuration.\n', value: 'create' },
+    { name: 'Back and edit\n  Return to the interview without creating files.\n', value: 'back' },
+    { name: 'Cancel\n  Exit without creating files.\n', value: 'cancel' },
+  ]
+}