create-win-project 1.3.0 → 2.0.0

package/src/cli/questions.js

@@ -0,0 +1,188 @@
+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', 'fastapi'].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', 'fastapi'].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', 'fastapi'].includes(answers.backend) && answers.frontend !== 'laravel-ui' &&
+        (args.authentication || answers.authentication) === 'yes' && !args.authAudience,
+    },
+    {
+      type: 'list', name: 'uploads', message: 'User-provided file uploads',
+      choices: [{ name: 'None', value: 'none' }, { name: 'Private object storage', value: 'object-storage' }],
+      default: 'none', when: () => !args.uploads,
+    },
+    {
+      type: 'list', name: 'backgroundJobs', message: 'Background work',
+      choices: [{ name: 'None', value: 'none' }, { name: 'Durable queue', value: 'queue' }],
+      default: 'none', when: (answers) => catalog.byId[answers.frontend]?.platform !== 'mobile' && !args.backgroundJobs,
+    },
+    {
+      type: 'list', name: 'offline', message: 'Offline behavior',
+      choices: [{ name: 'None', value: 'none' }, { name: 'Local cache', value: 'cache' }, { name: 'Synchronization', value: 'sync' }],
+      default: 'none', when: (answers) => catalog.byId[answers.frontend]?.platform === 'mobile' && !args.offline,
+    },
+    {
+      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,158 @@
+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),
+    python: probe('python', ['--version'], run),
+    uv: probe('uv', ['--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 })
+    }
+  }
+  if (stack.backendKey === 'fastapi') {
+    if (!versionAtLeast(versions.python, profile.runtimes.python)) {
+      issues.push({ tool: 'Python', found: versions.python, required: profile.runtimes.python })
+    }
+    if (!versionAtLeast(versions.uv, profile.runtimes.uv)) {
+      issues.push({ tool: 'uv', found: versions.uv, required: profile.runtimes.uv })
+    }
+  }
+  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',
+    )
+  }
+  if (tools.has('Python') || tools.has('uv')) {
+    instructions.push(
+      `Install Python ${profile.runtimes.python} and uv ${profile.runtimes.uv} (https://docs.astral.sh/uv/), or use the generated Docker workflow.`,
+      'Verify: python --version && uv --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'])
+  const pythonVersion = probeDoctor('python')
+  const uvVersion = probeDoctor('uv')
+  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 },
+    { name: 'Python', found: pythonVersion, expected: profile.runtimes.python, required: false },
+    { name: 'uv', found: uvVersion, expected: profile.runtimes.uv, required: false },
+  ]
+}
+
+export function printDoctor(profile, output = console.log, diagnostics = collectDiagnostics(profile)) {
+  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 diagnostics) {
+    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 }
 }
@@ -191,7 +190,8 @@ export function resolveStack(answers, catalog) {
       if (fe.id === 'laravel-ui') authentication = 'laravel-session'
       else authentication = authAudience === 'website' && fe.platform === 'web' ? 'sanctum-spa' : 'laravel-oidc'
     }
-    else throw new Error(`Authentication generation requires Supabase or Spring Boot for ${fe.label}`)
+    else if (be.id === 'fastapi') authentication = 'oidc'
+    else throw new Error(`Authentication generation requires Supabase, Spring Boot, Laravel, or FastAPI for ${fe.label}`)
   }
 
   // ── Collect selected manifests ───────────────────────────────────────────
@@ -278,7 +278,7 @@ export function resolveStack(answers, catalog) {
   // Apply env prefix: clientEnv vars get fe.envPrefix, others stay as-is
   const envPrefix = fe.envPrefix || ''
   if (authentication === 'session') rawEnv.push('SPRING_SECURITY_USER_NAME', 'SPRING_SECURITY_USER_PASSWORD')
-  if (authentication === 'oidc') rawEnv.push('OIDC_ISSUER_URI', 'OIDC_AUDIENCE')
+  if (authentication === 'oidc' && be.id === 'springboot') rawEnv.push('OIDC_ISSUER_URI', 'OIDC_AUDIENCE')
   if (authentication === 'laravel-session') rawEnv.push('SESSION_DOMAIN')
   if (authentication === 'sanctum-spa') rawEnv.push('SESSION_DOMAIN', 'SANCTUM_STATEFUL_DOMAINS', 'CORS_ALLOWED_ORIGINS')
   if (authentication === 'laravel-oidc') rawEnv.push('AUTH0_DOMAIN', 'AUTH0_AUDIENCE')

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

@@ -3,7 +3,7 @@
 // Static helpers only — no stack identity checks. Stack-specific files are
 // now template-driven via templates/ and readTemplate().
 
-export function contextMd(vars, expectedConcerns) {
+export function contextMd(vars, expectedConcerns, capabilities = {}) {
   const concernsBlock = (expectedConcerns && expectedConcerns.length)
     ? expectedConcerns.map((c) => `- ${c}`).join('\n')
     : '- (none selected — all optional concerns remain available)'
@@ -23,6 +23,15 @@ export function contextMd(vars, expectedConcerns) {
 ## Key Decisions
 <!-- Architecture and tech decisions made during the project -->
 
+- Production baseline: generated default; deviations require approval.
+- Uploads: ${capabilities.uploads || 'none'}
+- Background jobs: ${capabilities.backgroundJobs || 'none'}
+- Offline: ${capabilities.offline || 'none'}
+
+## Approved Deviations
+<!-- Record date, approver, rationale, affected files, and recovery path. -->
+- (none)
+
 ## Out of Scope
 <!-- What this project explicitly does NOT do -->
 

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

@@ -32,8 +32,31 @@ 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', rest), 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', rest),
+      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 +185,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/application-shapes.js → src/engine/project-shapes.js}

@@ -29,13 +29,13 @@ const VALID_COMBINATIONS = Object.freeze({
     ['laravel-ui', 'laravel'],
   ],
   separate: [
-    ['nextjs', 'springboot'], ['nextjs', 'laravel'],
-    ['react', 'springboot'], ['react', 'laravel'], ['react', 'supabase'],
+    ['nextjs', 'springboot'], ['nextjs', 'laravel'], ['nextjs', 'fastapi'],
+    ['react', 'springboot'], ['react', 'laravel'], ['react', 'supabase'], ['react', 'fastapi'],
   ],
-  api: [['no-frontend', 'springboot'], ['no-frontend', 'laravel']],
+  api: [['no-frontend', 'springboot'], ['no-frontend', 'laravel'], ['no-frontend', 'fastapi']],
   mobile: [
     ['react-native', 'none'], ['react-native', 'supabase'],
-    ['react-native', 'springboot'], ['react-native', 'laravel'],
+    ['react-native', 'springboot'], ['react-native', 'laravel'], ['react-native', 'fastapi'],
   ],
   frontend: [['react', 'none']],
 })

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
@@ -46,6 +54,8 @@ export function buildVars(answers, stack) {
     SPRING_MODULITH_VERSION: profile.springModulith,
     PHP_VERSION:         profile.runtimes.php,
     COMPOSER_VERSION:    profile.runtimes.composer,
+    PYTHON_VERSION:      profile.runtimes.python,
+    UV_VERSION:          profile.runtimes.uv,
     LARAVEL_VERSION:     profile.composerPackages['laravel/framework'],
     LARAVEL_DIR:         ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '.' : 'backend',
     TESTCONTAINERS_VERSION: profile.packages["testcontainers-junit-jupiter"] || profile.packages["testcontainers-postgresql"] || "1.19.8",
@@ -57,6 +67,7 @@ export function buildVars(answers, stack) {
     NGINX_IMAGE:         `${profile.images.nginx.repository}:${profile.images.nginx.tag}`,
     PHP_IMAGE:           `${profile.images.php.repository}:${profile.images.php.tag}`,
     COMPOSER_IMAGE:      `${profile.images.composer.repository}:${profile.images.composer.tag}`,
+    PYTHON_IMAGE:        `${profile.images.python.repository}:${profile.images.python.tag}`,
     COMPATIBILITY_PROFILE: profile.id,
   }
 }

package/{lib/compatibility.js → src/engine/tested-versions.js}

@@ -20,6 +20,7 @@ export function validateCompatibility(catalog) {
   const statuses = new Map()
   let packageNames
   let composerPackageNames
+  let pythonPackageNames
   for (const [id, profile] of Object.entries(catalog.profiles)) {
     if (!/^\d{4}\.\d{2}$/.test(id)) throw new Error(`Invalid compatibility profile id: ${id}`)
     if (!['current', 'previous'].includes(profile.status)) throw new Error(`Invalid status for profile ${id}`)
@@ -30,10 +31,10 @@ export function validateCompatibility(catalog) {
     statuses.set(profile.status, id)
     if (!EXACT_VERSION.test(profile.springBoot || '')) throw new Error(`Profile ${id} needs an exact Spring Boot version`)
     if (!EXACT_VERSION.test(profile.springModulith || '')) throw new Error(`Profile ${id} needs an exact Spring Modulith version`)
-    for (const key of ['node', 'java', 'maven', 'postgres', 'php', 'composer']) {
+    for (const key of ['node', 'java', 'maven', 'postgres', 'php', 'composer', 'python', 'uv']) {
       if (!profile.runtimes?.[key]) throw new Error(`Profile ${id} is missing runtime ${key}`)
     }
-    for (const key of ['node', 'maven', 'java', 'postgres', 'nginx', 'php', 'composer']) {
+    for (const key of ['node', 'maven', 'java', 'postgres', 'nginx', 'php', 'composer', 'python']) {
       const image = profile.images?.[key]
       if (!image?.repository || !image?.tag || image.tag === 'latest') {
         throw new Error(`Profile ${id} has an invalid ${key} image`)
@@ -57,6 +58,9 @@ export function validateCompatibility(catalog) {
     if (profile.images.composer.repository !== 'composer' || profile.images.composer.tag !== profile.runtimes.composer) {
       throw new Error(`Profile ${id} Composer image must match runtime ${profile.runtimes.composer}`)
     }
+    if (profile.images.python.repository !== 'python' || !profile.images.python.tag.startsWith(`${profile.runtimes.python}-`)) {
+      throw new Error(`Profile ${id} Python image must match runtime ${profile.runtimes.python}`)
+    }
     const names = Object.keys(profile.packages || {}).sort()
     if (!names.length) throw new Error(`Profile ${id} has no package versions`)
     for (const [name, value] of Object.entries(profile.packages)) {
@@ -80,6 +84,15 @@ export function validateCompatibility(catalog) {
       throw new Error(`Profile ${id} does not own the same Composer package set as the current profile`)
     }
     composerPackageNames = composerNames
+    const pythonNames = Object.keys(profile.pythonPackages || {}).sort()
+    if (!pythonNames.length) throw new Error(`Profile ${id} has no Python package versions`)
+    for (const [name, version] of Object.entries(profile.pythonPackages)) {
+      if (!EXACT_VERSION.test(version || '')) throw new Error(`Profile ${id} Python package ${name} must use an exact version`)
+    }
+    if (pythonPackageNames && JSON.stringify(pythonNames) !== JSON.stringify(pythonPackageNames)) {
+      throw new Error(`Profile ${id} does not own the same Python package set as the current profile`)
+    }
+    pythonPackageNames = pythonNames
   }
   if (!statuses.has('current') || !statuses.has('previous')) {
     throw new Error('Exactly one current and one previous compatibility profile are required')
@@ -114,3 +127,9 @@ export function composerPackageVersion(profile, name, owner = name) {
   if (!version) throw new Error(`${owner} requires ${name}, missing from compatibility profile ${profile.id}`)
   return version
 }
+
+export function pythonPackageVersion(profile, name, owner = name) {
+  const version = profile.pythonPackages?.[name]
+  if (!version) throw new Error(`${owner} requires ${name}, missing from compatibility profile ${profile.id}`)
+  return version
+}

package/src/engine/upgrade-report.js

@@ -0,0 +1,20 @@
+import fs from 'fs-extra'
+import path from 'node:path'
+import { loadCompatibility } from './tested-versions.js'
+
+export async function createUpgradeReport(projectPath, compatibilityFile) {
+  const profilePath = path.join(path.resolve(projectPath), 'create-win-project.profile.json')
+  const existing = await fs.readJson(profilePath).catch(() => { throw new Error(`No create-win-project profile found at ${profilePath}`) })
+  const { profile: current } = await loadCompatibility(compatibilityFile)
+  const previousId = existing.compatibilityProfile?.id
+  const differences = []
+  if (existing.schemaVersion !== 2) differences.push({ area: 'migration', current: existing.schemaVersion, supported: 2 })
+  if (previousId !== current.id) differences.push({ area: 'compatibility-profile', current: previousId, supported: current.id })
+  for (const [runtime, version] of Object.entries(current.runtimes)) {
+    if (existing.runtimes?.[runtime] !== version) differences.push({ area: `runtime.${runtime}`, current: existing.runtimes?.[runtime], supported: version })
+  }
+  for (const contract of ['tests', 'continuousIntegration', 'securityRules', 'operationsDocumentation']) {
+    if (existing.productionBaseline?.[contract] !== true) differences.push({ area: `security-contract.${contract}`, current: existing.productionBaseline?.[contract], supported: true })
+  }
+  return { readOnly: true, project: path.resolve(projectPath), stack: existing.stack, profile: previousId, supportedProfile: current.id, differences }
+}