create-win-project 1.3.0 → 1.4.0

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' },
+  ]
+}

package/src/cli/questions.js

@@ -0,0 +1,187 @@
+export { configurationDecisionChoices, lastEnabledIndex, promptWithBack, wrapText } from './navigation.js'
+import chalk from 'chalk'
+import {
+  architectureChoicesFor,
+  resolveStack,
+  stylingChoicesFor,
+} from '../engine/load-library.js'
+import {
+  APPLICATION_SHAPES,
+  applicationShapeChoices,
+  backendChoicesForShape,
+  frontendChoicesForShape,
+} from '../engine/project-shapes.js'
+import { laravelUiPromptContribution } from '../stacks/backends/laravel/ui/index.js'
+
+const CONCERN_LABELS = {
+  validation: 'Runtime validation', query: 'Server-state caching', state: 'Shared UI state',
+  env: 'Environment validation', 'url-state': 'URL state', 'safe-action': 'Type-safe server actions',
+  'dark-mode': 'Dark mode', 'http-client': 'HTTP client',
+}
+
+function choice(title, value, { hint, recommended } = {}) {
+  const suffix = [hint ? `(${hint})` : '', recommended ? chalk.green('Recommended') : '']
+    .filter(Boolean).join('  ')
+  return { name: suffix ? `${title}  ${suffix}` : title, short: title, value }
+}
+
+function footerMarker(text) {
+  return { type: 'description-footer', text }
+}
+
+export function exampleForShape(shape) {
+  const description = APPLICATION_SHAPES[shape]?.description
+  const match = description?.match(/Example:\s*(.+?)\.?$/)
+  return match ? match[1] : undefined
+}
+
+function describeExisting(entries, description, hintFor) {
+  return [
+    ...entries.map((entry) => choice(
+      entry.short || entry.name.split('\n')[0].replace(' (Recommended)', ''),
+      entry.value,
+      { hint: hintFor?.(entry.value), recommended: entry.name.includes('(Recommended)') },
+    )),
+    footerMarker(description),
+  ]
+}
+
+function validationError(problem, recovery) {
+  return `${chalk.red(`Error: ${problem}`)} ${chalk.yellow(recovery)}`
+}
+
+export function buildQuestions({ args, catalog }) {
+  return [
+    {
+      type: 'list', name: 'applicationShape', message: 'Application shape',
+      choices: describeExisting(
+        applicationShapeChoices(),
+        'Choose the runtime layout that matches how this application will be deployed.',
+        (shape) => {
+          const example = exampleForShape(shape)
+          return example ? `e.g. ${example}` : undefined
+        },
+      ), default: 'fullstack', when: () => !args.shape,
+    },
+    {
+      type: 'input', name: 'projectName', message: 'Project name', default: 'my-project',
+      validate: (value) => {
+        if (!value.trim()) return validationError('Project name is required.', 'Enter a lowercase name such as my-project.')
+        if (!/^[a-z0-9-]+$/.test(value)) return validationError('The name contains unsupported characters.', 'Use lowercase letters, numbers, and hyphens only.')
+        return true
+      },
+    },
+    { type: 'input', name: 'projectDescription', message: 'One-line description', default: 'A new application' },
+    {
+      type: 'list', name: 'frontend', message: 'Application framework',
+      choices: (answers) => describeExisting(frontendChoicesForShape(args.shape || answers.applicationShape, catalog), 'The primary user-facing application framework.'),
+      when: () => !args.frontend,
+    },
+    {
+      type: 'list', name: 'backend', message: 'Backend or data service',
+      choices: (answers) => describeExisting(backendChoicesForShape(args.shape || answers.applicationShape, answers.frontend, catalog), 'The server or managed data boundary used by this application.'),
+      when: () => !args.backend,
+    },
+    ...laravelUiPromptContribution(args.laravelUi).questions,
+    {
+      type: 'list', name: 'styling', message: 'Styling approach',
+      choices: (answers) => describeExisting(stylingChoicesFor(catalog, answers.frontend), 'The default styling system for generated UI.'),
+      when: (answers) => stylingChoicesFor(catalog, answers.frontend).length > 1,
+    },
+    {
+      type: 'list', name: 'architecture',
+      message: 'Architecture depth',
+      choices: (answers) => {
+        const supported = architectureChoicesFor(catalog, answers.frontend, answers.backend)
+        return [
+          ...[
+            choice('Medium', 'medium', { recommended: true }),
+            choice('Small', 'small'),
+            choice('Large', 'large'),
+          ].filter((choice) => supported.includes(choice.value)),
+          footerMarker('Clear feature boundaries for most long-term applications; fewer layers for prototypes; enforced boundaries for complex domains.'),
+        ]
+      },
+      default: 'medium', when: () => !args.architecture,
+    },
+    {
+      type: 'list', name: 'authentication',
+      message: (answers) => ['supabase', 'springboot', 'laravel'].includes(answers.backend)
+        ? 'User authentication'
+        : `User authentication ${chalk.yellow(`(generation unavailable for ${answers.backend === 'none' ? 'a frontend-only project' : 'a PostgreSQL-only backend'})`)}`,
+      choices: (answers) => {
+        const choices = []
+        if (['supabase', 'springboot', 'laravel'].includes(answers.backend)) {
+          choices.push(choice('Yes', 'yes'))
+        }
+        choices.push(
+          choice('Not yet', 'not-yet', { recommended: true }),
+          choice('No', 'none'),
+          footerMarker('Generate working authentication for this stack, record guidance without pretending login exists, or stay intentionally public.'),
+        )
+        return choices
+      },
+      default: 'not-yet', when: () => !args.authentication,
+    },
+    {
+      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: (answers) => ['springboot', 'laravel'].includes(answers.backend) && answers.frontend !== 'laravel-ui' &&
+        (args.authentication || answers.authentication) === 'yes' && !args.authAudience,
+    },
+    {
+      type: 'list', name: 'testing', message: 'Testing setup?',
+      choices: (answers) => catalog.byId[answers.frontend]?.platform === 'mobile'
+        ? [
+            { name: 'Basic  (Jest + React Native Testing Library)', value: 'basic' },
+            { name: 'None', value: 'none' },
+          ]
+        : [
+            { name: 'Full   (Vitest + React Testing Library + Playwright)', value: 'full' },
+            { name: 'Basic  (Vitest + React Testing Library)', value: 'basic' },
+            { name: 'None', value: 'none' },
+          ],
+      default: (answers) => catalog.byId[answers.frontend]?.platform === 'mobile' ? 'basic' : 'full',
+    },
+    {
+      type: 'confirm', name: 'docker', message: 'Add optional Docker development files', default: false,
+      when: (answers) => Boolean(catalog.byId[answers.backend]?.needsDocker) || catalog.byId[answers.frontend]?.platform !== 'mobile',
+    },
+    {
+      type: 'confirm', name: 'makefile', message: 'Include Makefile?', default: true,
+      when: (answers) => catalog.byId[answers.frontend]?.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: () => !args.install && !args.noInstall,
+    },
+    {
+      type: 'input', name: 'packageName', message: 'Java package name? (e.g. com.yourname)', default: 'com.app',
+      when: (answers) => answers.backend === 'springboot',
+      validate: (value) => {
+        if (!value.trim()) return 'Package name is required'
+        if (!/^[a-z]+(\.[a-z]+)+$/.test(value)) return 'Use format: com.yourname'
+        return true
+      },
+    },
+    {
+      type: 'checkbox', name: 'expectedConcerns',
+      message: 'Planning notes for optional features (advisory only; no libraries or feature code are generated)',
+      choices: (answers) => {
+        const stack = resolveStack({
+          ...answers,
+          styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0],
+        }, catalog)
+        const notes = [...new Set(stack.concerns.filter((concern) => !concern.required).map((concern) => concern.id))]
+          .map((id) => choice(CONCERN_LABELS[id] || id.replaceAll('-', ' '), id))
+        return [...notes, footerMarker('Write selected concerns to CONTEXT.md as planning notes.')]
+      },
+    },
+  ]
+}

package/src/cli/system-check.js

@@ -0,0 +1,138 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+function numericVersion(value) {
+  const match = String(value || '').match(/\d+(?:\.\d+){0,2}/)
+  return match ? match[0].split('.').map(Number) : null
+}
+
+export function versionAtLeast(found, required) {
+  const actual = numericVersion(found)
+  const minimum = numericVersion(required)
+  if (!actual || !minimum) return false
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (actual[index] || 0) - (minimum[index] || 0)
+    if (difference !== 0) return difference > 0
+  }
+  return true
+}
+
+function probe(command, args = ['--version'], run = spawnSync) {
+  const result = run(command, args, { encoding: 'utf8', shell: false })
+  if (result.error || result.status !== 0) return null
+  return `${result.stdout || result.stderr || ''}`.trim().split('\n')[0] || null
+}
+
+export function detectSystemVersions({ run = spawnSync, nodeVersion = process.versions.node } = {}) {
+  return {
+    node: nodeVersion,
+    npm: probe(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['--version'], run),
+    php: probe('php', ['--version'], run),
+    composer: probe(process.platform === 'win32' ? 'composer.bat' : 'composer', ['--version'], run),
+  }
+}
+
+export function needsNpmInstallation(stack) {
+  return stack.frontendKey !== 'no-frontend' &&
+    (stack.frontendKey !== 'laravel-ui' || stack.laravelUi === 'inertia-react')
+}
+
+export function installationIssues(stack, profile, versions) {
+  const issues = []
+  if (needsNpmInstallation(stack)) {
+    const minimumNode = profile.runtimes.nodeMinimum
+    const minimumNpm = profile.runtimes.npmMinimum
+    if (!versionAtLeast(versions.node, minimumNode)) {
+      issues.push({ tool: 'Node.js', found: versions.node, required: minimumNode })
+    }
+    if (!versionAtLeast(versions.npm, minimumNpm)) {
+      issues.push({ tool: 'npm', found: versions.npm, required: minimumNpm })
+    }
+  }
+  if (stack.backendKey === 'laravel') {
+    if (!versionAtLeast(versions.php, profile.runtimes.php)) {
+      issues.push({ tool: 'PHP', found: versions.php, required: profile.runtimes.php })
+    }
+    if (!versionAtLeast(versions.composer, profile.runtimes.composer)) {
+      issues.push({ tool: 'Composer', found: versions.composer, required: profile.runtimes.composer })
+    }
+  }
+  return issues
+}
+
+export async function decideInstallation({ requested, issues, interactive, choose }) {
+  if (!requested) return { install: false, reason: 'not-requested' }
+  if (issues.length === 0) return { install: true, reason: 'supported' }
+  if (!interactive) return { install: false, reason: 'runtime-mismatch' }
+
+  while (true) {
+    const decision = await choose()
+    if (decision === 'skip') return { install: false, reason: 'runtime-mismatch' }
+    if (decision === 'cancel') return { install: false, reason: 'cancelled' }
+    if (decision !== 'instructions') throw new Error(`Unknown runtime decision: ${decision}`)
+    return { install: false, reason: 'show-instructions' }
+  }
+}
+
+export function runtimeSetupInstructions(profile, issues = []) {
+  const tools = new Set(issues.map((issue) => issue.tool))
+  const instructions = []
+  if (tools.has('Node.js') || tools.has('npm')) {
+    instructions.push(
+      `Mise: mise use node@${profile.runtimes.node}`,
+      `NVM:  nvm install ${profile.runtimes.node} && nvm use ${profile.runtimes.node}`,
+      'Verify: node --version && npm --version',
+    )
+  }
+  if (tools.has('PHP') || tools.has('Composer')) {
+    instructions.push(
+      `Install PHP ${profile.runtimes.php} and Composer ${profile.runtimes.composer}, or use the generated Docker workflow.`,
+      'Verify: php --version && composer --version',
+    )
+  }
+  return instructions
+}
+
+// ─── Doctor (from lib/doctor.js) ───────────────────────────────────────────
+function isOnPath(command) {
+  const suffixes = process.platform === 'win32' ? ['', '.cmd', '.exe', '.bat'] : ['']
+  return (process.env.PATH || '').split(path.delimiter).some((directory) =>
+    suffixes.some((suffix) => existsSync(path.join(directory, `${command}${suffix}`)))
+  )
+}
+
+function probeDoctor(command, args = ['--version']) {
+  const result = spawnSync(command, args, { encoding: 'utf8', shell: false })
+  const version = `${result.stdout || result.stderr || ''}`.trim().split('\n')[0]
+  if (!version) return isOnPath(command) ? 'available (version unavailable)' : null
+  if (result.status !== 0) return null
+  return version
+}
+
+export function collectDiagnostics(profile) {
+  const nodeVersion = process.versions.node
+  const npmVersion = probeDoctor('npm')
+  const dockerVersion = probeDoctor('docker')
+  const composeVersion = dockerVersion ? probeDoctor('docker', ['compose', 'version']) : null
+  const javaVersion = probeDoctor('java', ['-version'])
+  return [
+    { name: 'Node.js', found: nodeVersion, expected: profile.runtimes.node, required: false },
+    { name: 'npm', found: npmVersion, required: false },
+    { name: 'Docker', found: dockerVersion, required: false },
+    { name: 'Docker Compose', found: composeVersion, required: false },
+    { name: 'Java', found: javaVersion, expected: profile.runtimes.java, required: false },
+  ]
+}
+
+export function printDoctor(profile, output = console.log) {
+  output(`create-win-project doctor (profile ${profile.id})`)
+  output('Use either the Node/npm lane or the Docker/Compose lane; Java is only needed for host-run Spring projects.')
+  for (const item of collectDiagnostics(profile)) {
+    const expectation = item.expected ? ` (tested: ${item.expected})` : ''
+    output(`${item.found ? '✓' : '○'} ${item.name}: ${item.found || 'not found'}${expectation}`)
+  }
+  output('')
+  output('Node lane:   npm ci && npm start')
+  output('Docker lane: docker compose build && docker compose run --rm app')
+}

package/src/engine/create-project.js

@@ -0,0 +1,10 @@
+import { scaffoldProject } from '../stacks/create-project.js'
+
+/**
+ * Runs the generic project-creation pipeline. Stack-owned contributions are
+ * composed behind the shared stack boundary and are migrated into their
+ * individual adapters in the following phases.
+ */
+export async function generateProject(answers, cliRoot) {
+  return scaffoldProject(answers, cliRoot)
+}

package/src/engine/install-dependencies.js

@@ -0,0 +1,13 @@
+import { spawnSync } from 'node:child_process'
+
+export function runDependencySteps(steps, run = spawnSync) {
+  for (const step of steps) {
+    const result = run(step.command, step.args, {
+      cwd: step.cwd,
+      stdio: 'inherit',
+      shell: false,
+    })
+    if (result.error || result.status !== 0) return { ok: false, failed: step, result }
+  }
+  return { ok: true, failed: null }
+}

package/{lib/catalog.js → src/engine/load-library.js}

@@ -1,7 +1,7 @@
 import fs from 'fs-extra'
 import path from 'path'
-import { loadCompatibility, resolvePackages } from './compatibility.js'
-import { inferApplicationShape, validateApplicationShape } from './application-shapes.js'
+import { loadCompatibility, resolvePackages } from './tested-versions.js'
+import { inferApplicationShape, validateApplicationShape } from './project-shapes.js'
 
 // ─── Loader ───────────────────────────────────────────────────────────────────
 
@@ -12,11 +12,10 @@ export async function loadCatalog(playbooksDir, selectedProfile) {
     for (const e of entries) {
       const full = path.join(dir, e.name)
       if (e.isDirectory()) { await walk(full); continue }
-      if (e.name.endsWith('.manifest.json')) {
+      if (e.name === 'definition.json') {
         const m = await fs.readJson(full)
         m._file = full
-        const defaultPlaybook = path.relative(playbooksDir, full).replace(/\.manifest\.json$/, '.md')
-        m._playbooks = m.playbooks || [m.file || defaultPlaybook]
+        m._playbooks = m.playbooks || (m.file ? [m.file] : [])
         const firstPlaybook = m._playbooks[0]
         m._playbook = typeof firstPlaybook === 'string' ? firstPlaybook : firstPlaybook?.file
         manifests.push(m)
@@ -26,7 +25,7 @@ export async function loadCatalog(playbooksDir, selectedProfile) {
   await walk(playbooksDir)
   validateManifests(manifests)
   const profile = selectedProfile || (await loadCompatibility(
-    path.join(path.dirname(playbooksDir), 'compatibility/profiles.json'),
+    path.join(playbooksDir, 'tested-versions.json'),
   )).profile
   return { ...buildIndex(manifests), profile }
 }

package/{lib/playbooks.js → src/engine/project-guidance.js}

@@ -32,8 +32,30 @@ export function extractSections(content) {
  * Resolve a playbook relative path to an absolute path.
  * Handles nested stack facets and concern playbooks transparently.
  */
-export async function resolvePlaybook(playbooksDir, file) {
-  return path.join(playbooksDir, file)
+export async function resolvePlaybook(libraryDir, file) {
+  const [category, ...restParts] = file.split('/')
+  const rest = restParts.join('/')
+  const name = path.basename(file, '.md')
+  const candidates = {
+    universal: [path.join(libraryDir, 'universal', name, path.basename(file))],
+    platform: [path.join(libraryDir, 'platforms', rest), path.join(libraryDir, 'platforms', name, path.basename(file))],
+    stack: [path.join(libraryDir, 'stacks', rest)],
+    capabilities: [
+      path.join(libraryDir, 'features', rest),
+      path.join(libraryDir, 'development-tools', rest),
+    ],
+    concerns: [path.join(libraryDir, 'optional-features', 'concerns', rest)],
+    styling: [
+      path.join(libraryDir, 'optional-features', 'styling', name, path.basename(file)),
+      path.join(libraryDir, 'optional-features', 'styling', name.replace(/-extensions$/, ''), path.basename(file)),
+    ],
+    devops: [path.join(libraryDir, 'development-tools', 'devops', name, path.basename(file))],
+  }[category] || []
+
+  for (const candidate of candidates) {
+    if (await fs.pathExists(candidate)) return candidate
+  }
+  return candidates[0] || path.join(libraryDir, file)
 }
 
 /**
@@ -162,7 +184,7 @@ export async function buildRulesIndex(stack, catalog, playbooksDir) {
 export async function copySelectedPlaybooks(playbooksDir, dest, stack) {
   const allFiles = collectPlaybookFiles(stack)
   for (const file of allFiles) {
-    const src = path.join(playbooksDir, file)
+    const src = await resolvePlaybook(playbooksDir, file)
     if (await fs.pathExists(src)) {
       const dst = path.join(dest, 'playbooks', file)
       await fs.ensureDir(path.dirname(dst))

package/{lib/template.js → src/engine/render-templates.js}

@@ -2,6 +2,7 @@
 
 import fs from 'fs-extra'
 import path from 'path'
+import { writeFile } from './write-files.js'
 
 export function render(content, vars) {
   return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`)
@@ -14,6 +15,13 @@ export async function readTemplate(templatesDir, category, name, ext = '') {
   return null
 }
 
+export async function writeRenderedFile(destination, filePath, template, vars) {
+  const content = render(template, vars)
+  await writeFile(destination, filePath, content)
+}
+
+export * from './write-files.js'
+
 export function buildVars(answers, stack) {
   const packagePath = (answers.packageName ?? 'com.app').replace(/\./g, '/')
   const profile = stack.profile

package/src/engine/write-files.js

@@ -0,0 +1,34 @@
+import fs from 'fs-extra'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export async function projectDestinations(cwd, projectName) {
+  const finalDestination = path.join(cwd, projectName)
+  if (await fs.pathExists(finalDestination)) {
+    throw new Error(`Destination already exists: ${finalDestination}`)
+  }
+  return {
+    finalDestination,
+    stagingDestination: path.join(cwd, `.${projectName}.tmp-${randomUUID()}`),
+  }
+}
+
+export async function writeProjectAtomically({ finalDestination, stagingDestination, generate }) {
+  try {
+    await fs.ensureDir(stagingDestination)
+    await generate(stagingDestination)
+    await fs.move(stagingDestination, finalDestination, { overwrite: false })
+  } catch (error) {
+    await fs.remove(stagingDestination)
+    throw error
+  }
+}
+
+export async function writeFile(destination, filePath, content) {
+  const fullPath = path.join(destination, filePath)
+  await fs.ensureDir(path.dirname(fullPath))
+  await fs.writeFile(fullPath, content, 'utf8')
+}
+
+// Generated documentation/file-content builders remain compatible during the migration.
+export * from './project-files.js'

package/{lib/stacks/registry.js → src/stacks/available-stacks.js}

@@ -1,4 +1,12 @@
-import { isStackAdapter } from './contract.js'
+import { isStackAdapter } from './rules.js'
+import { nextjsAdapter } from './frontends/nextjs/index.js'
+import { reactViteAdapter } from './frontends/react-vite/index.js'
+import { reactNativeAdapter } from './frontends/react-native/index.js'
+import { springbootAdapter } from './backends/springboot/index.js'
+import { supabaseAdapter } from './backends/supabase/index.js'
+import { postgresAdapter } from './backends/postgres/index.js'
+import { noBackendAdapter } from './backends/none/index.js'
+import { laravelAdapter } from './backends/laravel/index.js'
 
 export function createStackRegistry(initialAdapters = []) {
   const adapters = new Map()
@@ -40,3 +48,17 @@ export function createStackRegistry(initialAdapters = []) {
   return Object.freeze(registry)
 }
 
+// This is the only place stack adapters are assembled. Entries stay explicit
+// so adding a source file never silently changes supported generator behavior.
+export const stackRegistry = createStackRegistry([
+  nextjsAdapter,
+  reactViteAdapter,
+  reactNativeAdapter,
+  springbootAdapter,
+  supabaseAdapter,
+  postgresAdapter,
+  noBackendAdapter,
+  laravelAdapter,
+])
+
+export { stackRegistry as availableStacks }