create-win-project 1.4.0 → 2.0.0

package/library/tested-versions.json

@@ -15,7 +15,9 @@
         "maven": "3.9.16",
         "postgres": "16",
         "php": "8.5.10",
-        "composer": "2.10.3"
+        "composer": "2.10.3",
+        "python": "3.14.7",
+        "uv": "0.12.10"
       },
       "images": {
         "node": {
@@ -45,8 +47,26 @@
         "composer": {
           "repository": "composer",
           "tag": "2.10.3"
+        },
+        "python": {
+          "repository": "python",
+          "tag": "3.14.7-slim"
         }
       },
+      "pythonPackages": {
+        "alembic": "1.19.2",
+        "asyncpg": "0.31.0",
+        "fastapi": "0.141.1",
+        "httpx": "0.28.1",
+        "mypy": "2.3.1",
+        "pydantic-settings": "2.15.0",
+        "pyjwt": "2.13.0",
+        "pytest": "9.1.1",
+        "pytest-asyncio": "1.4.0",
+        "ruff": "0.16.6",
+        "sqlalchemy": "2.0.52",
+        "uvicorn": "0.52.4"
+      },
       "composerPackages": {
         "auth0/login": "7.22.0",
         "fakerphp/faker": "1.24.1",
@@ -133,7 +153,9 @@
         "maven": "3.9.16",
         "postgres": "16",
         "php": "8.5.10",
-        "composer": "2.10.3"
+        "composer": "2.10.3",
+        "python": "3.13.15",
+        "uv": "0.12.10"
       },
       "images": {
         "node": {
@@ -163,8 +185,26 @@
         "composer": {
           "repository": "composer",
           "tag": "2.10.3"
+        },
+        "python": {
+          "repository": "python",
+          "tag": "3.13.15-slim"
         }
       },
+      "pythonPackages": {
+        "alembic": "1.19.2",
+        "asyncpg": "0.31.0",
+        "fastapi": "0.141.1",
+        "httpx": "0.28.1",
+        "mypy": "2.3.1",
+        "pydantic-settings": "2.15.0",
+        "pyjwt": "2.13.0",
+        "pytest": "9.1.1",
+        "pytest-asyncio": "1.4.0",
+        "ruff": "0.16.6",
+        "sqlalchemy": "2.0.52",
+        "uvicorn": "0.52.4"
+      },
       "composerPackages": {
         "auth0/login": "7.22.0",
         "fakerphp/faker": "1.24.1",

package/library/universal/coding-rules/definition.json

@@ -2,12 +2,12 @@
   "id": "coding-rules",
   "kind": "universal",
   "label": "Coding Rules",
-  "file": "universal/coding-rules.md",
+  "playbooks": ["universal/coding-rules/naming.md", "universal/coding-rules/hygiene.md"],
   "required": true,
   "folders": [],
   "devDeps": ["prettier"],
   "concerns": [
-    { "id": "naming", "required": true, "sections": ["Naming", "Functions", "Imports", "Constants"] },
-    { "id": "no-debug", "required": true, "sections": ["No Debug Code in Commits", "One Thing Per File"] }
+    { "id": "naming", "required": true, "playbook": "universal/coding-rules/naming.md", "sections": ["Naming", "Functions", "Imports", "Constants"] },
+    { "id": "no-debug", "required": true, "playbook": "universal/coding-rules/hygiene.md", "sections": ["No Debug Code in Commits", "One Thing Per File"] }
   ]
 }

package/library/universal/coding-rules/hygiene.md

@@ -0,0 +1,9 @@
+# Code hygiene
+
+## No Debug Code in Commits
+
+Remove temporary logging, breakpoints, fixtures, bypasses, and commented-out implementations. Retain structured operational logging only when it has defined level, fields, privacy handling, and ownership.
+
+## One Thing Per File
+
+A file should have one clear reason to change. Keep tightly coupled helpers beside their owner, but split unrelated components, routes, services, or policies. Do not create one-line files merely to satisfy this rule.

package/library/universal/coding-rules/naming.md

@@ -0,0 +1,17 @@
+# Naming and structure
+
+## Naming
+
+Use names that describe domain intent. Avoid unexplained abbreviations, generic `data`/`utils` modules, and names that repeat their containing folder.
+
+## Functions
+
+Keep functions focused, make side effects visible, validate at boundaries, and return early for invalid states.
+
+## Imports
+
+Group platform, external, and local imports consistently. Respect architecture boundaries and remove unused imports.
+
+## Constants
+
+Name shared constants by meaning, keep feature-local values near their owner, and do not disguise mutable state as a constant.

package/library/universal/git-conventions/branches.md

@@ -0,0 +1,5 @@
+# Git branches
+
+## Branch Structure
+
+Branch from the documented integration branch. Use short prefixes such as `feature/`, `fix/`, `docs/`, `refactor/`, or `chore/`, followed by a specific kebab-case purpose. Keep unrelated work on separate branches.

package/library/universal/git-conventions/commits.md

@@ -0,0 +1,7 @@
+# Git commits
+
+## Commit Convention
+
+Use `type(scope): imperative summary`. Each commit should represent one coherent, testable change and must not include secrets, generated noise, debug code, or unrelated formatting.
+
+Explain motivation and migration impact in the body when the diff alone is insufficient.

package/library/universal/git-conventions/definition.json

@@ -2,10 +2,12 @@
   "id": "git-conventions",
   "kind": "universal",
   "label": "Git Conventions",
-  "file": "universal/git-conventions.md",
+  "playbooks": ["universal/git-conventions/branches.md", "universal/git-conventions/commits.md", "universal/git-conventions/workflow.md"],
   "required": true,
   "folders": [],
   "concerns": [
-    { "id": "git", "required": true, "sections": ["Branch Structure", "Commit Convention", "Daily Workflow"] }
+    { "id": "git-branches", "required": true, "playbook": "universal/git-conventions/branches.md", "sections": ["Branch Structure"] },
+    { "id": "git-commits", "required": true, "playbook": "universal/git-conventions/commits.md", "sections": ["Commit Convention"] },
+    { "id": "git-workflow", "required": true, "playbook": "universal/git-conventions/workflow.md", "sections": ["Daily Workflow"] }
   ]
 }

package/library/universal/git-conventions/workflow.md

@@ -0,0 +1,5 @@
+# Git workflow
+
+## Daily Workflow
+
+Inspect status and upstream changes before editing. Preserve user work, stage deliberately, review the staged diff, and run risk-appropriate checks before committing. Do not push, merge, rewrite shared history, or create releases without authorization.

package/library/universal/typescript/boundaries.md

@@ -0,0 +1,13 @@
+# TypeScript boundaries
+
+## Strict Mode — Always On
+
+Keep `strict` enabled. Model inputs at trust boundaries as `unknown`, validate them, then pass typed values inward. Do not weaken compiler options for one failing file.
+
+## No any
+
+Avoid `any`. Prefer `unknown`, generics, discriminated unions, or a narrow local type. If an external library forces an escape hatch, isolate and document it at the adapter boundary.
+
+## Type vs Interface
+
+Use interfaces for extendable object contracts and types for unions, intersections, mapped types, and aliases. Consistency within a feature matters more than stylistic conversion.

package/library/universal/typescript/definition.json

@@ -2,11 +2,11 @@
   "id": "typescript",
   "kind": "universal",
   "label": "TypeScript",
-  "file": "universal/typescript.md",
+  "playbooks": ["universal/typescript/boundaries.md", "universal/typescript/errors.md", "universal/typescript/patterns.md"],
   "required": true,
   "folders": [],
   "concerns": [
-    { "id": "typescript-strict", "required": true, "sections": ["Strict Mode — Always On", "No any", "Type vs Interface"] },
-    { "id": "validation", "required": false, "when": "Project validates external/runtime input", "sections": ["Zod for Runtime Validation"] }
+    { "id": "typescript-strict", "required": true, "playbook": "universal/typescript/boundaries.md", "sections": ["Strict Mode — Always On", "No any", "Type vs Interface"] },
+    { "id": "validation", "required": false, "when": "Project validates external/runtime input", "playbook": "universal/typescript/patterns.md", "sections": ["Zod for Runtime Validation"] }
   ]
 }

package/library/universal/typescript/errors.md

@@ -0,0 +1,5 @@
+# TypeScript errors
+
+## Typed Errors
+
+Represent expected failures with stable codes or discriminated results. Preserve causes for server logs, return safe messages at external boundaries, and exhaustively handle variants with `never` checks.

package/library/universal/typescript/patterns.md

@@ -0,0 +1,7 @@
+# TypeScript patterns
+
+## Zod for Runtime Validation
+
+Static types do not validate runtime data. Parse environment variables, requests, storage, and third-party responses at entry points. Export the inferred type from the schema instead of maintaining a duplicate interface.
+
+Prefer small pure functions, explicit return types on public APIs, `satisfies` for configuration, and immutable inputs where mutation is not part of the contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-win-project",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "Project scaffolding CLI by Win",
   "main": "index.js",
   "type": "module",
@@ -18,10 +18,7 @@
     "templates",
     "checks",
     "public/logo.svg",
-    "docs/ARCHITECTURE.md",
-    "docs/CONTENT_MODEL.md",
-    "docs/DEPENDENCY_MAINTENANCE.md",
-    "docs/CONTRIBUTING.md",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +27,7 @@
     "doctor": "node index.js doctor",
     "test": "vitest run",
     "validate:content": "node checks/check-library.js",
+    "package:check": "node checks/check-package.js",
     "matrix:smoke": "node checks/check-compatibility.js --scope=smoke",
     "matrix:full": "node checks/check-compatibility.js --scope=full",
     "verify:generated": "node checks/check-generated-project.js"
@@ -45,6 +43,6 @@
     "ora": "7.0.1"
   },
   "devDependencies": {
-    "vitest": "2.1.9"
+    "vitest": "5.0.0"
   }
 }

package/src/cli/arguments.js

@@ -6,6 +6,7 @@ function option(args, name) {
 }
 
 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')
@@ -16,6 +17,9 @@ export function parseArguments(args) {
   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')
 
@@ -34,6 +38,9 @@ export function parseArguments(args) {
   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({
@@ -45,8 +52,12 @@ export function parseArguments(args) {
     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/main.js

@@ -26,6 +26,7 @@ import {
   startProjectSpinner,
 } from './display.js'
 import { parseArguments } from './arguments.js'
+import { createUpgradeReport } from '../engine/upgrade-report.js'
 import {
   loadCatalog, resolveStack,
 } from '../engine/load-library.js'
@@ -50,8 +51,16 @@ 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,
@@ -85,6 +94,11 @@ 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
 
@@ -157,6 +171,10 @@ try {
     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

package/src/cli/questions.js

@@ -106,12 +106,12 @@ export function buildQuestions({ args, catalog }) {
     },
     {
       type: 'list', name: 'authentication',
-      message: (answers) => ['supabase', 'springboot', 'laravel'].includes(answers.backend)
+      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'].includes(answers.backend)) {
+        if (['supabase', 'springboot', 'laravel', 'fastapi'].includes(answers.backend)) {
           choices.push(choice('Yes', 'yes'))
         }
         choices.push(
@@ -130,22 +130,23 @@ export function buildQuestions({ args, catalog }) {
         { 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' &&
+      when: (answers) => ['springboot', 'laravel', 'fastapi'].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: '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,

package/src/cli/system-check.js

@@ -30,6 +30,8 @@ export function detectSystemVersions({ run = spawnSync, nodeVersion = process.ve
     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),
   }
 }
 
@@ -58,6 +60,14 @@ export function installationIssues(stack, profile, versions) {
       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
 }
 
@@ -91,6 +101,12 @@ export function runtimeSetupInstructions(profile, issues = []) {
       '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
 }
 
@@ -116,19 +132,23 @@ export function collectDiagnostics(profile) {
   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) {
+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 collectDiagnostics(profile)) {
+  for (const item of diagnostics) {
     const expectation = item.expected ? ` (tested: ${item.expected})` : ''
     output(`${item.found ? '✓' : '○'} ${item.name}: ${item.found || 'not found'}${expectation}`)
   }

package/src/engine/load-library.js

@@ -190,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 ───────────────────────────────────────────
@@ -277,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/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/src/engine/project-guidance.js

@@ -37,7 +37,7 @@ export async function resolvePlaybook(libraryDir, file) {
   const rest = restParts.join('/')
   const name = path.basename(file, '.md')
   const candidates = {
-    universal: [path.join(libraryDir, 'universal', name, path.basename(file))],
+    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: [
@@ -46,6 +46,7 @@ export async function resolvePlaybook(libraryDir, file) {
     ],
     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)),
     ],

package/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/src/engine/render-templates.js

@@ -54,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",
@@ -65,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/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 }
+}