create-win-project 1.3.0

package/lib/application-shapes.js

@@ -0,0 +1,95 @@
+export const APPLICATION_SHAPES = Object.freeze({
+  fullstack: {
+    label: 'Full-stack web application',
+    description: 'One project owns the website and server logic. Example: Next.js or Laravel.',
+  },
+  separate: {
+    label: 'Separate frontend and backend API',
+    description: 'Two applications connected through an API. Example: React/Vite + Spring Boot or Laravel.',
+  },
+  api: {
+    label: 'Backend API only',
+    description: 'An API without a generated website. Example: Spring Boot or Laravel.',
+  },
+  mobile: {
+    label: 'Mobile application',
+    description: 'An Expo app using Supabase or a separate Spring Boot or Laravel API.',
+  },
+  frontend: {
+    label: 'Frontend-only website',
+    description: 'A browser application without a generated server. Example: React with Vite.',
+  },
+})
+
+const VALID_COMBINATIONS = Object.freeze({
+  fullstack: [
+    ['nextjs', 'none'],
+    ['nextjs', 'postgres'],
+    ['nextjs', 'supabase'],
+    ['laravel-ui', 'laravel'],
+  ],
+  separate: [
+    ['nextjs', 'springboot'], ['nextjs', 'laravel'],
+    ['react', 'springboot'], ['react', 'laravel'], ['react', 'supabase'],
+  ],
+  api: [['no-frontend', 'springboot'], ['no-frontend', 'laravel']],
+  mobile: [
+    ['react-native', 'none'], ['react-native', 'supabase'],
+    ['react-native', 'springboot'], ['react-native', 'laravel'],
+  ],
+  frontend: [['react', 'none']],
+})
+
+export function applicationShapeChoices() {
+  return Object.entries(APPLICATION_SHAPES).map(([value, shape], index) => ({
+    name: `${shape.label}${index === 0 ? ' (Recommended)' : ''}\n  ${shape.description}`,
+    short: shape.label,
+    value,
+  }))
+}
+
+export function combinationsForShape(shape) {
+  if (!APPLICATION_SHAPES[shape]) throw new Error(`Unknown application shape: ${shape}`)
+  return VALID_COMBINATIONS[shape].map(([frontend, backend]) => ({ frontend, backend }))
+}
+
+export function inferApplicationShape({ frontend, backend }) {
+  const matches = Object.entries(VALID_COMBINATIONS).filter(([, combinations]) =>
+    combinations.some(([candidateFrontend, candidateBackend]) =>
+      candidateFrontend === frontend && candidateBackend === backend))
+  if (matches.length === 1) return matches[0][0]
+  if (matches.length === 0) {
+    throw new Error(`No application shape supports ${frontend} + ${backend}`)
+  }
+  throw new Error(`Specify --shape because ${frontend} + ${backend} is ambiguous`)
+}
+
+export function validateApplicationShape(shape, frontend, backend) {
+  const combinations = combinationsForShape(shape)
+  if (!combinations.some((entry) => entry.frontend === frontend && entry.backend === backend)) {
+    const allowed = combinations.map((entry) => `${entry.frontend} + ${entry.backend}`).join(', ')
+    throw new Error(`${frontend} + ${backend} is not valid for ${shape}; choose one of: ${allowed}`)
+  }
+  return shape
+}
+
+export function availableCombinationsForShape(shape, catalog) {
+  return combinationsForShape(shape).filter(({ frontend, backend }) =>
+    catalog.byId[frontend] && catalog.byId[backend])
+}
+
+export function frontendChoicesForShape(shape, catalog) {
+  const seen = new Set()
+  return availableCombinationsForShape(shape, catalog).flatMap(({ frontend }) => {
+    if (seen.has(frontend)) return []
+    seen.add(frontend)
+    const manifest = catalog.byId[frontend]
+    return [{ name: manifest.label, value: frontend }]
+  })
+}
+
+export function backendChoicesForShape(shape, frontend, catalog) {
+  return availableCombinationsForShape(shape, catalog)
+    .filter((entry) => entry.frontend === frontend)
+    .map(({ backend }) => ({ name: catalog.byId[backend].label, value: backend }))
+}

package/lib/banner.js

@@ -0,0 +1,45 @@
+import chalk from 'chalk'
+
+const W1N = [
+  ' ██╗    ██╗  ██╗ ███╗  ██╗',
+  ' ██║    ██║ ███║ ████╗ ██║',
+  ' ██║ █╗ ██║ ╚██║ ██╔██╗██║',
+  ' ██║███╗██║  ██║ ██║╚████║',
+  ' ╚███╔███╔╝  ██║ ██║ ╚███║',
+  '  ╚══╝╚══╝   ╚═╝ ╚═╝  ╚══╝',
+]
+
+const PROJECT = [
+  ' █▀█ █▀█ █▀█   █ █▀▀ █▀▀ ▀█▀',
+  ' █▀▀ █▀█ █ █   █ █▀  █    █ ',
+  ' █   █ █ █▄█ █▄█ █▄▄ █▄▄  █ ',
+]
+
+function plain() {
+  return [...W1N, '', ...PROJECT].join('\n')
+}
+
+function colored() {
+  const w1n = W1N.map((l) => chalk.bold.cyan(l)).join('\n')
+  const proj = PROJECT.map((l) => chalk.bold.white(l)).join('\n')
+  return `${w1n}\n${proj}`
+}
+
+export function w1nBanner() {
+  const noColor = process.env.NO_COLOR !== undefined || process.env.FORCE_COLOR === '0'
+  const isTTY = process.stdout.isTTY
+  const width = process.stdout.columns || 80
+
+  // Fallback for narrow terminals or non-TTY (CI/logs): plain single-line wordmark
+  if (!isTTY || width < 80 || noColor) {
+    // Keep stacked plain for README consistency, but without colors
+    if (width < 60) return 'W1N PROJECT'
+    return plain()
+  }
+
+  return colored()
+}
+
+export const bannerRaw = plain()
+export const W1N_ART = W1N.join('\n')
+export const PROJECT_ART = PROJECT.join('\n')

package/lib/catalog.js

@@ -0,0 +1,343 @@
+import fs from 'fs-extra'
+import path from 'path'
+import { loadCompatibility, resolvePackages } from './compatibility.js'
+import { inferApplicationShape, validateApplicationShape } from './application-shapes.js'
+
+// ─── Loader ───────────────────────────────────────────────────────────────────
+
+export async function loadCatalog(playbooksDir, selectedProfile) {
+  const manifests = []
+  const walk = async (dir) => {
+    const entries = await fs.readdir(dir, { withFileTypes: true })
+    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')) {
+        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]
+        const firstPlaybook = m._playbooks[0]
+        m._playbook = typeof firstPlaybook === 'string' ? firstPlaybook : firstPlaybook?.file
+        manifests.push(m)
+      }
+    }
+  }
+  await walk(playbooksDir)
+  validateManifests(manifests)
+  const profile = selectedProfile || (await loadCompatibility(
+    path.join(path.dirname(playbooksDir), 'compatibility/profiles.json'),
+  )).profile
+  return { ...buildIndex(manifests), profile }
+}
+
+export function validateManifests(manifests) {
+  const ids = new Set()
+  const validKinds = new Set(['frontend', 'backend', 'database', 'migration', 'styling', 'devops', 'platform', 'universal'])
+  for (const manifest of manifests) {
+    if (!manifest.id || typeof manifest.id !== 'string') throw new Error('Every manifest needs a string id')
+    if (ids.has(manifest.id)) throw new Error(`Duplicate manifest id: ${manifest.id}`)
+    ids.add(manifest.id)
+    if (!validKinds.has(manifest.kind)) throw new Error(`Invalid manifest kind for ${manifest.id}: ${manifest.kind}`)
+    if (!manifest.label || typeof manifest.label !== 'string') throw new Error(`Manifest ${manifest.id} needs a label`)
+    if (['frontend', 'backend'].includes(manifest.kind)) {
+      const profiles = manifest.architectureProfiles
+      if (!Array.isArray(profiles) || profiles.length !== 3 ||
+          !['small', 'medium', 'large'].every((profile) => profiles.includes(profile))) {
+        throw new Error(`Manifest ${manifest.id} must support small, medium, and large architecture profiles`)
+      }
+    }
+    if (manifest.playbooks && (!Array.isArray(manifest.playbooks) || manifest.playbooks.some((entry) =>
+      typeof entry !== 'string' && !(entry && typeof entry.file === 'string')))) {
+      throw new Error(`Manifest ${manifest.id}.playbooks must contain paths or conditional file entries`)
+    }
+    for (const field of ['deps', 'devDeps']) {
+      if (manifest[field] && (!Array.isArray(manifest[field]) || manifest[field].some((name) => typeof name !== 'string'))) {
+        throw new Error(`Manifest ${manifest.id}.${field} must be an array of package names`)
+      }
+    }
+    const env = new Set(manifest.env || [])
+    for (const name of manifest.clientEnv || []) {
+      if (!env.has(name)) throw new Error(`Manifest ${manifest.id} client env ${name} is missing from env`)
+    }
+    for (const concern of manifest.concerns || []) {
+      if (!concern.id || typeof concern.required !== 'boolean') {
+        throw new Error(`Manifest ${manifest.id} has an invalid concern`)
+      }
+      if (!concern.required && !concern.when) {
+        throw new Error(`Optional concern ${manifest.id}/${concern.id} needs a when condition`)
+      }
+    }
+  }
+}
+
+function buildIndex(manifests) {
+  const byId = {}
+  const byKind = {}
+  for (const m of manifests) {
+    byId[m.id] = m
+    ;(byKind[m.kind] ||= []).push(m)
+  }
+  return {
+    manifests, byId, byKind,
+    universal:  byKind['universal']  || [],
+    frontends:  byKind['frontend']   || [],
+    backends:   byKind['backend']    || [],
+  }
+}
+
+// ─── Interview helpers ────────────────────────────────────────────────────────
+
+function displayLabel(label, language) {
+  if (!language) return label
+  if (label.includes('(') && label.endsWith(')')) {
+    return label.replace(/\)$/, `, ${language})`)
+  }
+  return `${label} (${language})`
+}
+
+export function frontendChoices(catalog) {
+  return catalog.frontends.map((f) => ({
+    name: displayLabel(f.label, f.language),
+    value: f.id,
+  }))
+}
+
+export function backendChoicesFor(catalog, feId) {
+  const fe = catalog.byId[feId]
+  const allowed = fe?.appliesTo?.backend || []
+  return allowed.map((b) => {
+    const m = catalog.byId[b]
+    const label = m ? m.label : b
+    return { name: displayLabel(label, m?.language), value: b }
+  })
+}
+
+/** Returns styling choices for a frontend, or [] if only one option (auto-select). */
+export function stylingChoicesFor(catalog, feId) {
+  const fe = catalog.byId[feId]
+  const opts = fe?.stylingOptions || []
+  if (opts.length <= 1) return []
+  return opts.map((id) => {
+    const m = catalog.byId[id]
+    return { name: m ? m.label : id, value: id }
+  })
+}
+
+/** Returns true if the selected frontend supports architecture depth choice. */
+export function architectureChoicesFor(catalog, feId, beId) {
+  const frontend = catalog.byId[feId]
+  const backend = catalog.byId[beId]
+  if (!frontend || !backend) return []
+  const supported = new Set(frontend.architectureProfiles || [])
+  return (backend.architectureProfiles || []).filter((profile) => supported.has(profile))
+}
+
+function matchesWhen(when, context) {
+  if (!when) return true
+  return Object.entries(when).every(([key, expected]) => {
+    const values = Array.isArray(expected) ? expected : [expected]
+    return values.includes(context[key])
+  })
+}
+
+// ─── Stack resolver ───────────────────────────────────────────────────────────
+
+export function resolveStack(answers, catalog) {
+  const fe = catalog.byId[answers.frontend]
+  const be = catalog.byId[answers.backend]
+  if (!fe) throw new Error(`Unknown frontend: ${answers.frontend}`)
+  if (!be) throw new Error(`Unknown backend: ${answers.backend}`)
+
+  const allowed = fe.appliesTo?.backend || []
+  if (!allowed.includes(be.id)) {
+    throw new Error(`${fe.label} cannot pair with ${be.label}`)
+  }
+  const applicationShape = answers.applicationShape || answers.shape || inferApplicationShape({
+    frontend: fe.id,
+    backend: be.id,
+  })
+  validateApplicationShape(applicationShape, fe.id, be.id)
+
+  // ── Auto-resolve styling ─────────────────────────────────────────────────
+  // If only one option, auto-select it. Otherwise use the user's answer.
+  const stylingOpts = fe.stylingOptions || []
+  const styleId = stylingOpts.length === 0
+    ? null
+    : stylingOpts.length === 1
+    ? stylingOpts[0]
+    : (answers.styling || stylingOpts[0] || 'tailwind')
+
+  // ── Architecture ─────────────────────────────────────────────────────────
+  const supportedArchitectures = architectureChoicesFor(catalog, fe.id, be.id)
+  const architecture = answers.architecture || 'medium'
+  if (!supportedArchitectures.includes(architecture)) {
+    throw new Error(`${architecture} architecture is not supported by ${fe.label} + ${be.label}`)
+  }
+
+  const authenticationIntent = answers.authentication || 'not-yet'
+  if (!['yes', 'not-yet', 'none'].includes(authenticationIntent)) {
+    throw new Error(`Unknown authentication choice: ${authenticationIntent}`)
+  }
+  const authAudience = answers.authAudience || (fe.platform === 'mobile' ? 'multi-client' : 'website')
+  if (!['website', 'multi-client'].includes(authAudience)) {
+    throw new Error(`Unknown authentication audience: ${authAudience}`)
+  }
+  let authentication = authenticationIntent === 'none' ? 'public' : 'undecided'
+  if (authenticationIntent === 'yes') {
+    if (be.id === 'supabase') authentication = 'supabase'
+    else if (be.id === 'springboot') authentication = authAudience === 'multi-client' ? 'oidc' : 'session'
+    else if (be.id === 'laravel') {
+      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}`)
+  }
+
+  // ── Collect selected manifests ───────────────────────────────────────────
+  const selected = []
+  const include = (m) => { if (m && !selected.find((s) => s.id === m.id)) selected.push(m) }
+
+  for (const m of catalog.universal) include(m)
+  for (const m of (catalog.byKind['platform'] || [])) {
+    if ((m.appliesTo?.platform || []).includes(fe.platform || 'web')) include(m)
+  }
+  include(fe)
+  include(be)
+
+  // database + migration manifests that apply to the chosen backend
+  for (const m of (catalog.byKind['database'] || [])) {
+    if ((m.appliesTo?.backend || []).includes(be.id)) include(m)
+  }
+  for (const m of (catalog.byKind['migration'] || [])) {
+    if ((m.appliesTo?.backend || []).includes(be.id)) include(m)
+  }
+
+  // Styling manifests contribute their own folders, dependencies, and concerns.
+  const styleManifest = catalog.byId[styleId]
+  if (styleManifest) include(styleManifest)
+
+  // devops extras
+  if (answers.docker)        include(catalog.byId['docker'])
+  if (answers.makefile)      include(catalog.byId['makefile'])
+  if (answers.githubActions) {
+    include(catalog.byId['github-actions'])
+    include(catalog.byId['pr-template'])
+  }
+
+  // ── Merge manifest fields ────────────────────────────────────────────────
+  const selectionContext = {
+    frontend: fe.id,
+    backend: be.id,
+    platform: fe.platform || 'web',
+    architecture,
+    applicationShape,
+    authentication,
+    authenticationIntent,
+    testing: answers.testing || 'basic',
+    laravelUi: answers.laravelUi,
+  }
+  const playbooks = [...new Set(selected.flatMap((manifest) =>
+    (manifest._playbooks || []).filter((entry) =>
+      typeof entry === 'string' || matchesWhen(entry.appliesWhen, selectionContext)
+    ).map((entry) => typeof entry === 'string' ? entry : entry.file)
+  ).filter(Boolean))]
+  let   folders     = []
+  const deps        = {}
+  const devDeps     = {}
+  const dependencyKinds = new Map()
+  const rawEnv      = []   // env var names without prefix
+  const clientEnv   = new Set() // which vars get the fe prefix
+  const constraints = []
+  const concerns    = []
+
+  for (const m of selected) {
+    folders = folders.concat(m.folders || [])
+    folders = folders.concat(m.foldersByArchitecture?.[architecture] || [])
+    for (const [field, target, kind] of [['deps', deps, 'dependency'], ['devDeps', devDeps, 'devDependency']]) {
+      const resolved = resolvePackages(m[field] || [], catalog.profile, `${m.id}.${field}`)
+      for (const [name, version] of Object.entries(resolved)) {
+        const existingKind = dependencyKinds.get(name)
+        if (existingKind && existingKind !== kind) {
+          throw new Error(`${name} is declared as both a dependency and devDependency`)
+        }
+        dependencyKinds.set(name, kind)
+        target[name] = version
+      }
+    }
+    if (m.env)         rawEnv.push(...m.env)
+    if (m.clientEnv)   m.clientEnv.forEach((v) => clientEnv.add(v))
+    if (m.constraints) constraints.push(...m.constraints)
+    if (m.concerns) {
+      for (const c of m.concerns) {
+        if (matchesWhen(c.appliesWhen, selectionContext)) concerns.push({ ...c, _playbook: m._playbook })
+      }
+    }
+  }
+
+  // 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 === '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')
+  const env = [...new Set(rawEnv)].map((v) =>
+    clientEnv.has(v) ? `${envPrefix}${v}` : v
+  )
+
+  // Resolve folder template tokens
+  const packagePath = (answers.packageName || 'com.app').replace(/\./g, '/')
+  const resolvedFolders = [...new Set(folders)].map((f) =>
+    f.replace(/\{\{PACKAGE_PATH\}\}/g, packagePath)
+  )
+
+  // ── Capability flags (read from manifest, not hardcoded) ─────────────────
+  return {
+    // Identity
+    key:           `${fe.id}-${be.id}`,
+    frontendKey:   fe.id,
+    backendKey:    be.id,
+    label:         `${fe.label} + ${be.label}`,
+    frontendLabel: fe.label,
+    backendLabel:  be.label,
+
+    // Capabilities from manifest — no hardcoded isSomething checks
+    platform:      fe.platform || 'web',          // 'web' | 'mobile' | 'api'
+    ciTemplate:    fe.ciTemplate || 'generic',
+    scripts:       fe.scripts || {},
+    frontendDir:   fe.frontendDir ?? '',
+    frontendPort:  String(fe.port ?? ''),
+    backendPort:   be.port ? String(be.port) : '',
+    envPrefix:     fe.envPrefix || '',
+    needsDocker:   be.needsDocker ?? fe.needsDocker ?? false,
+    profile:       catalog.profile,
+    architecture,
+    applicationShape,
+    supportedArchitectures,
+    authenticationIntent,
+    authentication,
+    authAudience,
+    laravelUi: answers.laravelUi,
+    styleId,
+
+    // Template fields (per fix-template-identity spec)
+    makefileTemplate:  fe.platform === 'mobile' ? null : (be.makefileTemplate || fe.makefileTemplate || null),
+    dockerTemplate:    fe.dockerTemplate || null,
+    agentsTemplate:    fe.agentsTemplate || null,
+    gitignoreTemplate: fe.gitignoreTemplate || null,
+
+    // Merged output
+    playbooks: resolvedFolders.length ? playbooks : playbooks,
+    folders:   resolvedFolders,
+    constraints,
+    concerns,
+    deps,
+    devDeps,
+    env,
+
+    // Convenience flags — derived, not hardcoded per stack
+    isMobile:      (fe.platform === 'mobile'),
+    needsPackage:  (be.id === 'springboot'),
+  }
+}

package/lib/compatibility.js

@@ -0,0 +1,116 @@
+import fs from 'fs-extra'
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+export async function loadCompatibility(file, requestedProfile) {
+  const catalog = await fs.readJson(file)
+  validateCompatibility(catalog)
+  const profileId = requestedProfile || catalog.defaultProfile
+  const profile = catalog.profiles[profileId]
+  if (!profile) throw new Error(`Unknown compatibility profile: ${profileId}`)
+  return { catalog, profile: { id: profileId, ...profile } }
+}
+
+export function validateCompatibility(catalog) {
+  if (catalog?.schemaVersion !== 1) throw new Error('Unsupported compatibility catalog schema')
+  if (!catalog.profiles || typeof catalog.profiles !== 'object') throw new Error('Compatibility profiles are required')
+  if (!catalog.profiles[catalog.defaultProfile]) throw new Error('Default compatibility profile does not exist')
+
+  const statuses = new Map()
+  let packageNames
+  let composerPackageNames
+  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}`)
+    if (!ISO_DATE.test(profile.supportedUntil || '') || Number.isNaN(Date.parse(`${profile.supportedUntil}T00:00:00Z`))) {
+      throw new Error(`Profile ${id} needs a valid supportedUntil date`)
+    }
+    if (statuses.has(profile.status)) throw new Error(`Duplicate ${profile.status} compatibility profile`)
+    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']) {
+      if (!profile.runtimes?.[key]) throw new Error(`Profile ${id} is missing runtime ${key}`)
+    }
+    for (const key of ['node', 'maven', 'java', 'postgres', 'nginx', 'php', 'composer']) {
+      const image = profile.images?.[key]
+      if (!image?.repository || !image?.tag || image.tag === 'latest') {
+        throw new Error(`Profile ${id} has an invalid ${key} image`)
+      }
+    }
+    if (profile.images.node.repository !== 'node' || !profile.images.node.tag.startsWith(`${profile.runtimes.node}-`)) {
+      throw new Error(`Profile ${id} Node image must match runtime ${profile.runtimes.node}`)
+    }
+    if (profile.images.maven.repository !== 'maven' || !profile.images.maven.tag.startsWith(`${profile.runtimes.maven}-`)) {
+      throw new Error(`Profile ${id} Maven image must match runtime ${profile.runtimes.maven}`)
+    }
+    if (profile.images.java.repository !== 'eclipse-temurin' || !profile.images.java.tag.startsWith(`${profile.runtimes.java}-`)) {
+      throw new Error(`Profile ${id} Java image must match runtime ${profile.runtimes.java}`)
+    }
+    if (profile.images.postgres.repository !== 'postgres' || !profile.images.postgres.tag.startsWith(`${profile.runtimes.postgres}-`)) {
+      throw new Error(`Profile ${id} PostgreSQL image must match runtime ${profile.runtimes.postgres}`)
+    }
+    if (profile.images.php.repository !== 'php' || !profile.images.php.tag.startsWith(`${profile.runtimes.php}-`)) {
+      throw new Error(`Profile ${id} PHP image must match runtime ${profile.runtimes.php}`)
+    }
+    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}`)
+    }
+    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)) {
+      const versions = typeof value === 'string'
+        ? [value]
+        : [value?.default, ...Object.values(value?.overrides || {})]
+      if (!versions.length || versions.some((version) => !EXACT_VERSION.test(version || ''))) {
+        throw new Error(`Profile ${id} package ${name} must use exact versions`)
+      }
+    }
+    if (packageNames && JSON.stringify(names) !== JSON.stringify(packageNames)) {
+      throw new Error(`Profile ${id} does not own the same package set as the current profile`)
+    }
+    packageNames = names
+    const composerNames = Object.keys(profile.composerPackages || {}).sort()
+    if (!composerNames.length) throw new Error(`Profile ${id} has no Composer package versions`)
+    for (const [name, version] of Object.entries(profile.composerPackages)) {
+      if (!EXACT_VERSION.test(version || '')) throw new Error(`Profile ${id} Composer package ${name} must use an exact version`)
+    }
+    if (composerPackageNames && JSON.stringify(composerNames) !== JSON.stringify(composerPackageNames)) {
+      throw new Error(`Profile ${id} does not own the same Composer package set as the current profile`)
+    }
+    composerPackageNames = composerNames
+  }
+  if (!statuses.has('current') || !statuses.has('previous')) {
+    throw new Error('Exactly one current and one previous compatibility profile are required')
+  }
+  if (statuses.get('current') !== catalog.defaultProfile) {
+    throw new Error('The default compatibility profile must have current status')
+  }
+  const previousId = statuses.get('previous')
+  if (catalog.profiles[previousId].supersededBy !== catalog.defaultProfile) {
+    throw new Error(`Previous profile ${previousId} must point to current profile ${catalog.defaultProfile}`)
+  }
+}
+
+export function resolvePackages(names, profile, owner) {
+  if (!Array.isArray(names)) throw new Error(`${owner} packages must be an array of package names`)
+  return Object.fromEntries(names.map((name) => {
+    const manifestId = owner.split('.')[0]
+    return [name, packageVersion(profile, name, manifestId, owner)]
+  }))
+}
+
+export function packageVersion(profile, name, capability, owner = capability) {
+  const value = profile.packages[name]
+  if (!value) throw new Error(`${owner} requires ${name}, missing from compatibility profile ${profile.id}`)
+  const version = typeof value === 'string' ? value : (value.overrides?.[capability] || value.default)
+  if (!version) throw new Error(`${owner} has no compatible version for ${name} in profile ${profile.id}`)
+  return version
+}
+
+export function composerPackageVersion(profile, name, owner = name) {
+  const version = profile.composerPackages?.[name]
+  if (!version) throw new Error(`${owner} requires ${name}, missing from compatibility profile ${profile.id}`)
+  return version
+}

package/lib/constants.js

@@ -0,0 +1,3 @@
+// Deprecated: stack composition now lives in playbooks/*.manifest.json + lib/catalog.js.
+// Kept as an empty module so any stray import does not break resolution.
+export {}

package/lib/doctor.js

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+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 probe(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 = probe('npm')
+  const dockerVersion = probe('docker')
+  const composeVersion = dockerVersion ? probe('docker', ['compose', 'version']) : null
+  const javaVersion = probe('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')
+}