create-win-project 1.3.0 → 2.0.0

package/templates/makefile/fastapi.mk

@@ -0,0 +1,97 @@
+# =============================================================================
+# Makefile — {{PROJECT_NAME}}
+# =============================================================================
+
+# Variables
+COMPOSE      := docker compose
+BACKEND      := $(COMPOSE) exec backend
+DB           := $(COMPOSE) exec db
+WORKDIR      := $(PWD)
+
+# =============================================================================
+# Default
+# =============================================================================
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show all available commands
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# =============================================================================
+# Project Lifecycle
+# =============================================================================
+
+.PHONY: dev up down restart logs logs-back clean
+
+dev: ## Start all containers and follow logs
+	$(COMPOSE) up --build
+
+up: ## Start all containers in background
+	$(COMPOSE) up -d --build
+
+down: ## Stop and remove all containers
+	$(COMPOSE) down
+
+restart: down up ## Stop then start all containers
+
+logs: ## Follow logs from all containers
+	$(COMPOSE) logs -f
+
+logs-back: ## Follow backend logs only
+	$(COMPOSE) logs -f backend
+
+clean: ## Remove containers, volumes, orphans (full reset)
+	$(COMPOSE) down -v --remove-orphans
+
+# =============================================================================
+# Database
+# =============================================================================
+
+.PHONY: migrate db-shell
+
+migrate: ## Run pending Alembic migrations
+	$(BACKEND) uv run alembic upgrade head
+
+db-shell: ## Open psql shell inside DB container
+	$(DB) psql -U $${POSTGRES_USER} -d $${POSTGRES_DB}
+
+# =============================================================================
+# Shells
+# =============================================================================
+
+.PHONY: shell-back
+
+shell-back: ## Open shell inside backend container
+	$(BACKEND) sh
+
+# =============================================================================
+# Quality
+# =============================================================================
+
+.PHONY: lint test test-back
+
+lint: ## Run Ruff check and format check (backend)
+	$(BACKEND) uv run ruff check .
+	$(BACKEND) uv run ruff format --check .
+
+test: test-back ## Run all tests
+
+test-back: ## Run pytest (backend)
+	$(BACKEND) uv run pytest
+
+# =============================================================================
+# Production
+# =============================================================================
+
+.PHONY: build prod-up prod-down
+
+build: ## Build production Docker images
+	$(COMPOSE) -f docker-compose.prod.yml build
+
+prod-up: ## Start production stack
+	$(COMPOSE) -f docker-compose.prod.yml up -d --build
+
+prod-down: ## Stop production stack
+	$(COMPOSE) -f docker-compose.prod.yml down

package/docs/ARCHITECTURE.md

@@ -1,118 +0,0 @@
-# Architecture
-
-`create-win-project` composes a validated project specification into two coordinated outputs:
-
-1. a small executable application that establishes the stack's real conventions;
-2. a task-routed documentation layer for humans and coding agents.
-
-Executable behavior, tests, and framework configuration are the source of truth. Playbooks explain and extend that behavior; they must not contradict it.
-
-## Generation pipeline
-
-```text
-CLI interview
-    ↓
-validated answers
-    ↓
-manifest catalog + compatibility resolver
-    ↓
-resolved stack descriptor
-    ├── runnable framework files
-    ├── optional CI / Docker / Makefile files
-    ├── project context and documentation
-    └── selected playbooks + RULES.md router
-    ↓
-generated-project contract tests
-```
-
-### CLI boundary
-
-`index.js` owns interaction and presentation. It gathers project identity, frontend, optional backend, styling, one Small/Medium/Large architecture profile, login intent, client audience when relevant, testing depth, and optional operational tooling. Medium is shown first and is the default. It does not contain stack dependency tables.
-
-`generateProject()` validates the same answers again because it is also an exported programmatic API. A caller cannot bypass destination-name, Java-package, or testing-profile validation by skipping the CLI.
-
-### Catalog and resolution
-
-`lib/catalog.js` loads co-located `*.manifest.json` files and merges selected capabilities into one stack descriptor. `lib/compatibility.js` validates `compatibility/profiles.json` and resolves every package name to an exact version for the selected profile.
-
-Stack-specific behavior crosses into core orchestration through the contract in `lib/stacks/contract.js`. Every frontend, backend, or data adapter has a stable identity, declares compatible adapters and supported application/authentication/architecture models, and is added to the explicit registry. Registration is deliberate; adapters are never discovered by scanning directories.
-
-Adapters may contribute data in these areas:
-
-- questions in a core-defined prompt slot;
-- authentication models;
-- generated file descriptions;
-- environment declarations;
-- install steps;
-- Docker and CI fragments;
-- verification cases.
-
-Core code owns prompt order, compatibility-profile resolution, atomic writes, process execution, and final composition. An adapter receives a read-only stack context and returns contributions; it cannot write arbitrary paths or install global tools. Adapter definitions do not accept dependency tables or version fields. Exact versions remain exclusively owned by `compatibility/profiles.json`.
-
-Manifests declare:
-
-- identity and compatibility (`id`, `kind`, `appliesTo`);
-- dependency names and scripts (never dependency versions);
-- semantic environment names and which ones are client-visible;
-- supported architecture profiles, conditional playbooks, and optional templates;
-- constraints shown to the agent;
-- concerns and their playbook sections.
-
-Client environment variables are semantic in manifests (`API_URL`) and receive exactly one framework prefix during resolution (`NEXT_PUBLIC_API_URL`, `VITE_API_URL`, or `EXPO_PUBLIC_API_URL`). Public prefixes always mean the value is shipped to the client.
-
-### Runnable scaffold
-
-`lib/scaffold.js` owns the minimum executable vertical slice:
-
-- Next.js: route-oriented Small; familiar feature services/actions/queries and owned repositories or remote API clients in Medium; public feature APIs and enforced boundaries in Large.
-- React + Vite: thin browser features in Small, feature modules in Medium, and public feature APIs plus boundary checks in Large.
-- Expo: screens/data in Small, feature modules in Medium, and boundaries ready for offline sync, background work, and platform adapters in Large.
-- Spring Boot: conventional package-by-feature in Small, explicit API/service/repository ownership in Medium, and a verified Spring Modulith modular monolith in Large.
-
-Authentication is selected during generation. Supabase emits Supabase Auth clients and login examples; website-only Spring uses a secure server-managed session; multi-client Spring emits an OIDC Resource Server and delegates issuance, refresh, and revocation to the identity provider. `Not yet` is fail-closed for Spring and never emits pretend authentication. Existing projects are never told to rerun the generator to add auth.
-
-This module intentionally generates a small working example. Domain-specific features are added after product context is known; the generator does not invent business entities.
-
-### Repository and operational files
-
-`lib/generator.js` coordinates writes and refuses to merge into a non-empty destination. It adds documentation, selected playbooks, CI, Docker, Makefile, environment examples, and repository conventions around the runnable foundation.
-
-The first `npm install` creates the lockfile. Generated CI uses `npm ci`, so the lockfile must be committed before CI is enabled. `create-win-project.profile.json` separately records the compatibility profile, architecture profile, and authentication intent/model/audience; after generation, that project owns its own upgrade lifecycle.
-
-### Compatibility profile lifecycle
-
-Exactly one profile is `current` and one is `previous`. The current profile is the default. A profile owns exact npm, Spring Boot, runtime, and container versions; manifests and scaffold code may only request names or capabilities. Promotion copies the candidate into a new dated profile, marks the former current profile previous, and happens only after the generated-project matrix passes. Major changes also require migration notes. See `DEPENDENCY_MAINTENANCE.md`.
-
-## Documentation model
-
-| File | Responsibility |
-|------|----------------|
-| `AGENTS.md` | Small always-on command, workflow, safety, and definition-of-done contract. |
-| `CONTEXT.md` | Product goals, boundaries, decisions, and project-specific facts. |
-| `RULES.md` | Generated concern-to-playbook section router. |
-| `playbooks/` | Reusable standards, recipes, rationale, and stack guidance. |
-| `docs/` | Documentation for the generated product, not generic framework teaching. |
-
-Manifest section names are checked against Markdown headings. Numbered headings are normalized for matching, and generated contract tests reject unresolved `RULES.md` entries.
-
-## Testing strategy
-
-The generator itself has three verification levels:
-
-1. unit tests for catalog composition and template rendering;
-2. generated-output contract tests for required files, environment naming, playbook routing, profile-specific boundaries, auth metadata/code, testing profiles, and overwrite safety;
-3. a current-and-previous matrix across every supported stack combination, all three architecture profiles, and every applicable authentication model. It installs and runs lint, typecheck, tests, builds, Expo compatibility checks/web export, Spring MVC/security/Modulith tests and Maven packaging, Compose validation, and current-profile container builds.
-
-Canonical Markdown code examples should progressively move into extracted fixtures so examples compile against the versions they teach.
-
-## Extension workflow
-
-When adding a stack or capability:
-
-1. Add its manifest, all five stack facets, and any platform/capability routes.
-2. Add the smallest runnable files needed in `lib/scaffold.js` or a focused scaffold module.
-3. Add every supported architecture/authentication combination to the generated-output matrix.
-4. Run install, lint/typecheck, tests, and production build for the new fixture.
-5. Update this architecture document if ownership or the generation pipeline changed.
-
-Do not advertise a capability solely because a playbook mentions it. A generated capability must have executable configuration and contract coverage.

package/lib/banner.js

@@ -1,45 +0,0 @@
-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/constants.js

@@ -1,3 +0,0 @@
-// 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

@@ -1,45 +0,0 @@
-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')
-}

package/lib/interview.js

@@ -1,77 +0,0 @@
-const BACK = Symbol('back')
-
-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 async function promptWithBack(inquirer, questions, initialAnswers = {}) {
-  const answers = { ...initialAnswers }
-  const history = []
-  let index = 0
-
-  while (index < questions.length) {
-    const source = questions[index]
-    if (!enabled(source, answers)) { index += 1; continue }
-
-    const canGoBack = history.length > 0
-    const question = { ...source, when: undefined }
-    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)`
-    } else 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) && canGoBack) {
-      const choices = await resolved(question.choices, answers)
-      question.choices = [...choices, new inquirer.Separator(), { name: '← Back', value: BACK }]
-    }
-
-    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
-    }
-
-    answers[source.name] = value
-    history.push(index)
-    index += 1
-  }
-
-  return answers
-}
-
-export function configurationDecisionChoices() {
-  return [
-    { name: 'Create project', value: 'create' },
-    { name: '← Back and edit', value: 'back' },
-    { name: 'Cancel', value: 'cancel' },
-  ]
-}

package/lib/laravel-scaffold.js

@@ -1,3 +0,0 @@
-// Compatibility export for programmatic consumers. Laravel generation now
-// lives behind its stack adapter boundary.
-export { buildLaravelFiles } from './stacks/laravel/generate.js'