create-jst 0.3.1 → 0.4.0

package/README.md

@@ -6,12 +6,24 @@ Create a web application from the [JST](https://github.com/jst-stack/jst) templa
 npm create jst@latest my-app
 ```
 
-The wizard derives application metadata from the project directory, so it only asks about choices that change the generated project: starter demo, package manager, dependency installation, and Git initialization.
+The wizard derives application metadata from the project directory, so it only asks about choices that change generated output: package manager, CSS or SCSS Modules, dependency installation, and Git initialization. Creation happens in a temporary sibling directory; failures and signals clean it up before the final atomic rename.
 
 ```bash
 npm create jst@latest my-app -- --yes
-npm create jst@latest my-app -- --package-manager pnpm --demo keep
+npm create jst@latest my-app -- --package-manager pnpm
 npm create jst@latest my-app -- --dry-run
+npm create jst@latest my-app -- --example showcase
 ```
 
-Use `--help` to view non-interactive options. The initializer never overwrites a non-empty directory.
+Use `--help` to view deterministic flags for automation. The initializer never overwrites a non-empty directory and released versions resolve immutable template/showcase revisions.
+
+## Migrations
+
+Run migrations from a clean Git working tree:
+
+```bash
+npx --package=create-jst jst migrate --from 0.3.0 --to 0.4.0 --dry-run
+npx --package=create-jst jst migrate --from 0.3.0 --to 0.4.0
+```
+
+Migrations reject unsupported paths and customized source shapes before writing. Applied files are restored if the project quality gate fails.

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "create-jst",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Create a web application from the JST template.",
   "type": "module",
+  "packageManager": "npm@11.6.2",
   "bin": {
-    "create-jst": "src/cli.mjs"
+    "create-jst": "src/cli.mjs",
+    "jst": "src/jst.mjs"
   },
   "files": [
     "src"
   ],
   "engines": {
-    "node": ">=24 <25"
+    "node": ">=24.15.0 <25"
   },
   "scripts": {
-    "test": "node --test"
+    "lint": "eslint . --max-warnings 0",
+    "benchmark": "node scripts/run-benchmarks.mjs",
+    "benchmark:update": "node scripts/run-benchmarks.mjs --write-baseline",
+    "test": "node --test test/integration.test.mjs test/migration.test.mjs test/options.test.mjs test/projectInitializer.test.mjs",
+    "test:generated": "node --test test/generatedProject.test.mjs",
+    "check": "npm run lint && npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run check"
   },
   "repository": {
     "type": "git",
@@ -27,5 +35,9 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "degit": "^3.10.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.10.0"
   }
 }

package/src/application/projectInitializer.mjs

@@ -1,28 +1,45 @@
-export function createProjectInitializer({ events, projectGateway, templateGateway }) {
+export function createProjectInitializer({ onProgress = () => undefined, projectGateway, templateGateway }) {
 	return {
 		async execute(specification) {
 			await projectGateway.assertDestinationIsEmpty(specification.destination)
+			const temporaryDestination = await projectGateway.prepareDestination(specification.destination)
+			const temporarySpecification = Object.freeze({ ...specification, destination: temporaryDestination })
 
-			events.publish({ type: 'template.download.started', specification })
-			await templateGateway.clone(specification.template, specification.destination)
+			try {
+			onProgress({ type: 'template.download.started', specification })
+				await templateGateway.clone(specification.template, temporaryDestination)
+				if (specification.example === 'clean') {
+					await projectGateway.validateTemplate(temporarySpecification)
+				}
 
-			events.publish({ type: 'project.configuration.started', specification })
-			await projectGateway.configureTemplate(specification)
+				onProgress({ type: 'project.configuration.started', specification })
+				if (specification.example === 'showcase') {
+					await projectGateway.configureExample(temporarySpecification)
+				}
+				else {
+					await projectGateway.configureTemplate(temporarySpecification)
+				}
 
-			if (specification.packageManager !== 'npm') {
-				events.publish({ type: 'package-manager.configuration.started', specification })
-				await projectGateway.configurePackageManager(specification.destination, specification.packageManager)
-			}
-			if (specification.initGit) {
-				events.publish({ type: 'git.initialization.started', specification })
-				await projectGateway.initializeGit(specification.destination)
+				if (specification.packageManager !== 'npm') {
+					onProgress({ type: 'package-manager.configuration.started', specification })
+					await projectGateway.configurePackageManager(temporaryDestination, specification.packageManager)
+				}
+				if (specification.initGit) {
+					onProgress({ type: 'git.initialization.started', specification })
+					await projectGateway.initializeGit(temporaryDestination)
+				}
+				if (specification.install) {
+					onProgress({ type: 'dependencies.installation.started', specification })
+					await projectGateway.installDependencies(temporaryDestination, specification.packageManager)
+				}
+
+				await projectGateway.commitDestination(temporaryDestination, specification.destination)
+				onProgress({ type: 'project.initialized', specification })
 			}
-			if (specification.install) {
-				events.publish({ type: 'dependencies.installation.started', specification })
-				await projectGateway.installDependencies(specification.destination, specification.packageManager)
+			catch (error) {
+				await projectGateway.cleanupDestination(temporaryDestination)
+				throw error
 			}
-
-			events.publish({ type: 'project.initialized', specification })
 		},
 	}
 }

package/src/application/projectMigrator.mjs

@@ -0,0 +1,16 @@
+export function createProjectMigrator({ gateway }) {
+	return {
+		async execute({ directory, dryRun, from, migrations, to }) {
+			await gateway.assertSafeGitState(directory)
+			const files = await gateway.readMigrationFiles(directory, migrations)
+			for (const migration of migrations) {
+				migration.apply(files)
+			}
+			if (dryRun) {
+				return { changedFiles: [...files.keys()].sort(), from, to }
+			}
+			await gateway.writeTransaction(directory, files, () => gateway.verify(directory))
+			return { changedFiles: [...files.keys()].sort(), from, to }
+		},
+	}
+}

package/src/cli.mjs

@@ -3,34 +3,58 @@
 import process from 'node:process'
 import { realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import packageMetadata from '../package.json' with { type: 'json' }
 import { createProjectApplication } from './composition/createProjectApplication.mjs'
 import { parseCommandLine, printHelp, resolveProjectRequest } from './ui/command.mjs'
 import { createReporter } from './ui/reporter.mjs'
 
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) await run(process.argv.slice(2))
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	await run(process.argv.slice(2))
+}
 
-export async function run(argv, environment = process, application = createProjectApplication()) {
+export async function run(argv, environment = process, injectedApplication) {
 	const reporter = createReporter(environment.stdout, environment.env)
+	const signals = registerCancellation(environment)
 	try {
 		const command = parseCommandLine(argv)
-		if (command.values.help) return printHelp(environment.stdout)
-		if (command.values.version) return environment.stdout.write(`${process.env.npm_package_version ?? '0.3.0'}\n`)
+		if (command.values.help) {
+			return printHelp(environment.stdout)
+		}
+		if (command.values.version) {
+			return environment.stdout.write(`${packageMetadata.version}\n`)
+		}
 
 		const request = await resolveProjectRequest(command, environment)
-		if (request.dryRun) return reporter.plan(request.specification, request)
+		if (request.dryRun) {
+			return reporter.plan(request.specification, request)
+		}
 
 		reporter.start(request)
-		const unsubscribe = reporter.subscribe(application.events)
-		try {
-			await application.initializer.execute(request.specification)
-		}
-		finally {
-			unsubscribe()
-		}
+		const application = injectedApplication ?? createProjectApplication({ onProgress: event => reporter.progress(event), signal: signals.signal })
+		await application.initializer.execute(request.specification)
 	}
 	catch (error) {
-		if (error instanceof Error && error.name === 'PromptCancelledError') return
+		if (error instanceof Error && error.name === 'PromptCancelledError') {
+			return
+		}
 		reporter.error(error instanceof Error ? error.message : String(error))
 		environment.exitCode = 1
 	}
+	finally {
+		signals.dispose()
+	}
+}
+
+function registerCancellation(environment) {
+	const controller = new globalThis.AbortController()
+	const abort = () => controller.abort(new Error('Setup cancelled by signal.'))
+	environment.once?.('SIGINT', abort)
+	environment.once?.('SIGTERM', abort)
+	return {
+		dispose() {
+			environment.off?.('SIGINT', abort)
+			environment.off?.('SIGTERM', abort)
+		},
+		signal: controller.signal,
+	}
 }

package/src/composition/createProjectApplication.mjs

@@ -1,15 +1,13 @@
 import process from 'node:process'
-import { createEventBus } from '../application/eventBus.mjs'
 import { createProjectInitializer } from '../application/projectInitializer.mjs'
 import { createDegitTemplateGateway } from '../infrastructure/degitTemplateGateway.mjs'
 import { createNodeProjectGateway } from '../infrastructure/nodeProjectGateway.mjs'
 
-export function createProjectApplication({ nodeExecutable = process.execPath } = {}) {
-	const events = createEventBus()
+export function createProjectApplication({ nodeExecutable = process.execPath, onProgress, signal } = {}) {
 	const initializer = createProjectInitializer({
-		events,
-		projectGateway: createNodeProjectGateway({ nodeExecutable }),
+		onProgress,
+		projectGateway: createNodeProjectGateway({ nodeExecutable, signal }),
 		templateGateway: createDegitTemplateGateway(),
 	})
-	return { events, initializer }
+	return { initializer }
 }

package/src/domain/migrationCatalog.mjs

@@ -0,0 +1,34 @@
+export const CURRENT_PROJECT_VERSION = '0.4.0'
+
+export const migrations = Object.freeze([
+	Object.freeze({
+		from: '0.3.0',
+		to: CURRENT_PROJECT_VERSION,
+		files: Object.freeze(['eslint.config.js']),
+		apply(files) {
+			const eslintConfig = files.get('eslint.config.js')
+			if (!eslintConfig?.includes("jst.configs['strict']")) {
+				throw new Error("Migration requires eslint.config.js to use jst.configs['strict']; migrate custom ESLint composition manually.")
+			}
+			const withPolicy = eslintConfig.includes("from './jst.config.ts'")
+				? eslintConfig
+				: `import policy from './jst.config.ts'\n${eslintConfig}`
+			files.set('eslint.config.js', withPolicy.replace("jst.configs['strict']", 'jst.createConfig(policy)'))
+			files.set('jst.config.ts', "import { defineConfig } from '@jst-stack/eslint-plugin/policy'\n\nexport default defineConfig({})\n")
+		},
+	}),
+])
+
+export function resolveMigrationPath(from, to = CURRENT_PROJECT_VERSION) {
+	const path = []
+	let version = from
+	while (version !== to) {
+		const migration = migrations.find(candidate => candidate.from === version)
+		if (!migration || path.includes(migration)) {
+			throw new Error(`No supported migration path from ${from} to ${to}.`)
+		}
+		path.push(migration)
+		version = migration.to
+	}
+	return Object.freeze(path)
+}

package/src/domain/projectSpecification.mjs

@@ -1,21 +1,25 @@
 export const COLOR_SCHEMES = ['light', 'dark', 'auto']
 export const PRIMARY_COLORS = ['dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'teal', 'green', 'lime', 'yellow', 'orange']
-export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun']
-export const TEMPLATE_SOURCE = 'jst-stack/jst'
+export const PACKAGE_MANAGERS = ['npm', 'pnpm']
+export const STYLE_LANGUAGES = ['css', 'scss']
+export const EXAMPLES = ['clean', 'showcase']
+export const TEMPLATE_SOURCE = 'jst-stack/jst#v0.4.0'
+export const SHOWCASE_SOURCE = 'jst-stack/jst-showcase#d3625bda10ddb9c39599cc061e3f49cdb6be3922'
 
 export function buildProjectSpecification(input) {
 	const specification = Object.freeze({
 		colorScheme: input.colorScheme ?? 'dark',
-		demo: input.demo ?? 'remove',
 		description: input.description ?? `${input.title} web application.`,
 		destination: input.destination,
+		example: input.example ?? 'clean',
 		initGit: input.initGit ?? true,
 		install: input.install ?? true,
 		language: input.language ?? 'en',
 		name: input.name,
 		packageManager: input.packageManager ?? 'npm',
 		primaryColor: input.primaryColor ?? 'lime',
-		template: input.template ?? TEMPLATE_SOURCE,
+		style: input.style ?? 'css',
+		template: input.template ?? (input.example === 'showcase' ? SHOWCASE_SOURCE : TEMPLATE_SOURCE),
 		title: input.title,
 	})
 	validateProjectSpecification(specification)
@@ -26,12 +30,27 @@ export function validateProjectSpecification(specification) {
 	if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(specification.name) || specification.name.length > 214) {
 		throw new Error(`Invalid npm package name: ${specification.name}`)
 	}
-	if (!specification.destination) throw new Error('Project destination is required.')
-	if (!specification.title?.trim()) throw new Error('Application title is required.')
-	if (!COLOR_SCHEMES.includes(specification.colorScheme)) throw new Error(`Colour scheme must be one of: ${COLOR_SCHEMES.join(', ')}.`)
-	if (!PRIMARY_COLORS.includes(specification.primaryColor)) throw new Error(`Primary colour must be one of: ${PRIMARY_COLORS.join(', ')}.`)
-	if (!['keep', 'remove'].includes(specification.demo)) throw new Error('Demo mode must be either keep or remove.')
-	if (!PACKAGE_MANAGERS.includes(specification.packageManager)) throw new Error(`Package manager must be one of: ${PACKAGE_MANAGERS.join(', ')}.`)
+	if (!specification.destination) {
+		throw new Error('Project destination is required.')
+	}
+	if (!specification.title?.trim()) {
+		throw new Error('Application title is required.')
+	}
+	if (!COLOR_SCHEMES.includes(specification.colorScheme)) {
+		throw new Error(`Colour scheme must be one of: ${COLOR_SCHEMES.join(', ')}.`)
+	}
+	if (!PRIMARY_COLORS.includes(specification.primaryColor)) {
+		throw new Error(`Primary colour must be one of: ${PRIMARY_COLORS.join(', ')}.`)
+	}
+	if (!EXAMPLES.includes(specification.example)) {
+		throw new Error(`Example must be one of: ${EXAMPLES.join(', ')}.`)
+	}
+	if (!PACKAGE_MANAGERS.includes(specification.packageManager)) {
+		throw new Error(`Package manager must be one of: ${PACKAGE_MANAGERS.join(', ')}.`)
+	}
+	if (!STYLE_LANGUAGES.includes(specification.style)) {
+		throw new Error(`Style language must be one of: ${STYLE_LANGUAGES.join(', ')}.`)
+	}
 }
 
 export function normalizePackageName(value) {

package/src/infrastructure/degitTemplateGateway.mjs

@@ -1,8 +1,13 @@
 import degit from 'degit'
+import { cp } from 'node:fs/promises'
+import { isAbsolute, resolve } from 'node:path'
 
 export function createDegitTemplateGateway() {
 	return {
 		clone(source, destination) {
+			if (isAbsolute(source) || source.startsWith('.')) {
+				return cp(resolve(source), destination, { recursive: true })
+			}
 			return degit(source, { disableCache: true, force: false, verbose: false }).clone(destination)
 		},
 	}

package/src/infrastructure/nodeMigrationGateway.mjs

@@ -0,0 +1,68 @@
+import { execFile } from 'node:child_process'
+import { readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+const executeFile = promisify(execFile)
+
+export function createNodeMigrationGateway() {
+	return {
+		async assertSafeGitState(directory) {
+			try {
+				const { stdout } = await executeFile('git', ['status', '--porcelain'], { cwd: directory })
+				if (stdout.trim()) {
+					throw new Error('Migration requires a clean Git working tree.')
+				}
+			}
+			catch (error) {
+				if (error.message === 'Migration requires a clean Git working tree.') {
+					throw error
+				}
+				throw new Error('Migration requires the project to be inside a Git repository.', { cause: error })
+			}
+		},
+		async readMigrationFiles(directory, migrations) {
+			const names = new Set(migrations.flatMap(migration => migration.files))
+			const files = new Map()
+			for (const name of names) {
+				files.set(name, await readFile(join(directory, name), 'utf8'))
+			}
+			return files
+		},
+		async verify(directory) {
+			const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'))
+			const packageManager = manifest.packageManager?.startsWith('pnpm@') ? 'pnpm' : 'npm'
+			return executeFile(packageManager, ['run', 'check'], { cwd: directory })
+		},
+		async writeTransaction(directory, files, verify) {
+			const originals = new Map()
+			for (const name of files.keys()) {
+				try {
+					originals.set(name, await readFile(join(directory, name), 'utf8'))
+				}
+				catch (error) {
+					if (error.code !== 'ENOENT') {
+						throw error
+					}
+				}
+			}
+			try {
+				for (const [name, content] of files) {
+					await writeFile(join(directory, name), content)
+				}
+				await verify()
+			}
+			catch (error) {
+				for (const name of files.keys()) {
+					if (originals.has(name)) {
+						await writeFile(join(directory, name), originals.get(name))
+					}
+					else {
+						await rm(join(directory, name), { force: true })
+					}
+				}
+				throw error
+			}
+		},
+	}
+}

package/src/infrastructure/nodeProjectGateway.mjs

@@ -1,31 +1,50 @@
 import { spawn, execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
-import { lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { lstat, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import process from 'node:process'
 import { promisify } from 'node:util'
 
 const executeFile = promisify(execFile)
 const installCommands = {
-	bun: ['install'],
 	npm: ['install', '--no-audit', '--no-fund'],
 	pnpm: ['install'],
-	yarn: ['install'],
 }
 
-export function createNodeProjectGateway({ nodeExecutable }) {
+export function createNodeProjectGateway({ nodeExecutable, signal }) {
 	return {
 		assertDestinationIsEmpty,
-		configurePackageManager,
+		cleanupDestination,
+		commitDestination,
+		configureExample,
+		configurePackageManager: (destination, packageManager) => configurePackageManager(destination, packageManager, signal),
 		configureTemplate,
 		initializeGit,
 		installDependencies,
+		prepareDestination,
+		validateTemplate,
 	}
 
 	async function assertDestinationIsEmpty(destination) {
-		if (!existsSync(destination)) return
+		if (!existsSync(destination)) {
+			return
+		}
 		const stat = await lstat(destination)
-		if (!stat.isDirectory()) throw new Error(`Destination is not a directory: ${destination}`)
-		if ((await readdir(destination)).length > 0) throw new Error(`Destination is not empty: ${destination}`)
+		if (!stat.isDirectory()) {
+			throw new Error(`Destination is not a directory: ${destination}`)
+		}
+		if ((await readdir(destination)).length > 0) {
+			throw new Error(`Destination is not empty: ${destination}`)
+		}
+	}
+
+	function cleanupDestination(destination) {
+		return rm(destination, { force: true, recursive: true })
+	}
+
+	async function commitDestination(temporaryDestination, destination) {
+		await rm(destination, { force: true, recursive: true })
+		await rename(temporaryDestination, destination)
 	}
 
 	function configureTemplate(specification) {
@@ -38,49 +57,101 @@ export function createNodeProjectGateway({ nodeExecutable }) {
 			'--lang', specification.language,
 			'--color-scheme', specification.colorScheme,
 			'--primary-color', specification.primaryColor,
-			'--demo', specification.demo,
-		], specification.destination)
+			'--style', specification.style,
+		], specification.destination, signal)
 	}
 
-	async function configurePackageManager(destination, packageManager) {
-		let version
-		try {
-			({ stdout: version } = await executeFile(packageManager, ['--version']))
-		}
-		catch {
-			throw new Error(`Could not run ${packageManager}. Install it or choose another package manager.`)
-		}
-		const manifestPath = join(destination, 'package.json')
+	async function configureExample(specification) {
+		const manifestPath = join(specification.destination, 'package.json')
 		const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
-		manifest.packageManager = `${packageManager}@${version.trim()}`
+		manifest.name = specification.name
 		await writeFile(manifestPath, `${JSON.stringify(manifest, null, '\t')}\n`)
-		await rm(join(destination, 'package-lock.json'), { force: true })
 	}
 
 	function initializeGit(destination) {
-		return run('git', ['init', '--initial-branch=main'], destination)
+		return run('git', ['init', '--initial-branch=main'], destination, signal)
 	}
 
 	function installDependencies(destination, packageManager) {
-		return run(packageManager, installCommands[packageManager], destination)
+		return run(packageManager, installCommands[packageManager], destination, signal)
+	}
+
+	async function validateTemplate(specification) {
+		const contract = JSON.parse(await readFile(join(specification.destination, 'jst.template.json'), 'utf8'))
+		if (contract.schemaVersion !== 1) {
+			throw new Error(`Unsupported template contract schema: ${contract.schemaVersion}.`)
+		}
+		const selected = {
+			colorSchemes: specification.colorScheme,
+			primaryColors: specification.primaryColor,
+			styles: specification.style,
+		}
+		for (const [option, value] of Object.entries(selected)) {
+			if (!contract.options?.[option]?.includes(value)) {
+				throw new Error(`Template ${contract.templateVersion} does not support ${option}: ${value}.`)
+			}
+		}
+	}
+}
+
+async function configurePackageManager(destination, packageManager, signal) {
+	const manifestPath = join(destination, 'package.json')
+	const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+	delete manifest.packageManager
+	await writeFile(manifestPath, `${JSON.stringify(manifest, null, '\t')}\n`)
+	await rm(join(destination, 'package-lock.json'), { force: true })
+
+	let version
+	try {
+		({ stdout: version } = await executeFile(packageManager, ['--version'], { cwd: destination, signal }))
+	}
+	catch {
+		throw new Error(`Could not run ${packageManager}. Install it or choose another package manager.`)
+	}
+	const packageManagerEntry = ['packageManager', `${packageManager}@${version.trim()}`]
+	const entries = Object.entries(manifest).flatMap(entry => entry[0] === 'engines' ? [packageManagerEntry, entry] : [entry])
+	if (!manifest.engines) {
+		entries.push(packageManagerEntry)
+	}
+	await writeFile(manifestPath, `${JSON.stringify(Object.fromEntries(entries), null, '\t')}\n`)
+	if (packageManager === 'pnpm') {
+		await writeFile(
+			join(destination, 'pnpm-workspace.yaml'),
+			'minimumReleaseAge: 10080\nminimumReleaseAgeExcludePrune: true\ntrustPolicy: no-downgrade\ntrustPolicyIgnoreAfter: 10080\nshellEmulator: true\n',
+		)
+		await replaceReadmeCommands(destination, 'pnpm')
 	}
 }
 
-function run(command, args, cwd) {
+async function replaceReadmeCommands(destination, packageManager) {
+	const path = join(destination, 'README.md')
+	try {
+		const readme = await readFile(path, 'utf8')
+		await writeFile(path, readme.replaceAll('npm run ', `${packageManager} run `).replaceAll('npm ci', `${packageManager} install --frozen-lockfile`))
+	}
+	catch (error) {
+		if (error?.code !== 'ENOENT') {
+			throw error
+		}
+	}
+}
+
+async function prepareDestination(destination) {
+	const temporaryDestination = join(dirname(destination), `.${basename(destination)}-${process.pid}-${Date.now()}.tmp`)
+	await rm(temporaryDestination, { force: true, recursive: true })
+	return temporaryDestination
+}
+
+function run(command, args, cwd, signal) {
 	return new Promise((resolve, reject) => {
-		const child = spawn(command, args, { cwd, stdio: 'pipe' })
-		let stdout = ''
-		let stderr = ''
-		child.stdout?.on('data', chunk => {
-			stdout += chunk
-		})
-		child.stderr?.on('data', chunk => {
-			stderr += chunk
-		})
+		const child = spawn(command, args, { cwd, signal, stdio: 'inherit' })
 		child.once('error', error => reject(new Error(`Could not run ${command}: ${error.message}`)))
 		child.once('close', code => {
-			if (code === 0) resolve()
-			else reject(new Error(`${command} ${args.join(' ')} failed.${[stdout, stderr].filter(Boolean).join('\n').trim() ? `\n${[stdout, stderr].filter(Boolean).join('\n').trim()}` : ''}`))
+			if (code === 0) {
+				resolve()
+				return
+			}
+			reject(new Error(`${command} ${args.join(' ')} failed with exit code ${code}.`))
 		})
 	})
 }

package/src/jst.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { createProjectMigrator } from './application/projectMigrator.mjs'
+import { resolveMigrationPath } from './domain/migrationCatalog.mjs'
+import { createNodeMigrationGateway } from './infrastructure/nodeMigrationGateway.mjs'
+
+export async function run(argv, environment = process, migrator = createProjectMigrator({ gateway: createNodeMigrationGateway() })) {
+	try {
+		const command = parseCommand(argv)
+		if (command.help) {
+			environment.stdout.write('Usage: jst migrate --from <version> [--to <version>] [--dry-run]\n')
+			return
+		}
+		const migrations = resolveMigrationPath(command.from, command.to)
+		const result = await migrator.execute({ directory: environment.cwd(), dryRun: command.dryRun, from: command.from, migrations, to: command.to ?? migrations.at(-1)?.to ?? command.from })
+		environment.stdout.write(`${command.dryRun ? 'Would migrate' : 'Migrated'} ${result.from} → ${result.to}: ${result.changedFiles.join(', ')}\n`)
+	}
+	catch (error) {
+		environment.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+		environment.exitCode = 1
+	}
+}
+
+function parseCommand(argv) {
+	const { positionals, values } = parseArgs({ args: argv, allowPositionals: true, options: {
+		'dry-run': { type: 'boolean' }, from: { type: 'string' }, to: { type: 'string' }, help: { short: 'h', type: 'boolean' },
+	}, strict: true })
+	const help = Boolean(values.help || positionals[0] !== 'migrate')
+	if (!help && !values.from) {
+		throw new Error('--from is required.')
+	}
+	return { dryRun: values['dry-run'] ?? false, from: values.from, help, to: values.to }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await run(process.argv.slice(2))
+}

package/src/ui/command.mjs

@@ -1,7 +1,7 @@
 import { basename, resolve } from 'node:path'
 import { parseArgs } from 'node:util'
 import * as prompts from '@clack/prompts'
-import { buildProjectSpecification, normalizePackageName, PACKAGE_MANAGERS, toTitle } from '../domain/projectSpecification.mjs'
+import { buildProjectSpecification, EXAMPLES, normalizePackageName, PACKAGE_MANAGERS, STYLE_LANGUAGES, toTitle } from '../domain/projectSpecification.mjs'
 
 export function parseCommandLine(args) {
 	return parseArgs({
@@ -9,9 +9,9 @@ export function parseCommandLine(args) {
 		args,
 		options: {
 			'color-scheme': { type: 'string' },
-			'demo': { type: 'string' },
 			'description': { type: 'string' },
 			'dry-run': { type: 'boolean' },
+			'example': { type: 'string' },
 			'git': { type: 'boolean' },
 			'help': { short: 'h', type: 'boolean' },
 			'lang': { type: 'string' },
@@ -22,6 +22,7 @@ export function parseCommandLine(args) {
 			'package-manager': { type: 'string' },
 			'primary-color': { type: 'string' },
 			'skip-install': { type: 'boolean' },
+			'style': { type: 'string' },
 			'template': { type: 'string' },
 			'title': { type: 'string' },
 			'version': { short: 'v', type: 'boolean' },
@@ -33,22 +34,17 @@ export function parseCommandLine(args) {
 
 export async function resolveProjectRequest(command, environment) {
 	const { positionals, values } = command
-	if (positionals.length > 1) throw new Error('Only one project directory can be provided.')
-	if (values.git && values['no-git']) throw new Error('Use either --git or --no-git, not both.')
-	if (values['no-install'] && values['skip-install']) throw new Error('Use either --no-install or --skip-install, not both.')
+	validateCommand(positionals, values)
 
 	const prompt = await createPrompt(environment, values)
 	try {
-		const directory = positionals[0] ?? await prompt?.text('Project directory', 'my-jst-app') ?? 'my-jst-app'
-		const name = values.name ?? normalizePackageName(basename(resolve(environment.cwd(), directory)))
-		const title = values.title ?? toTitle(name)
-		const detectedPackageManager = detectPackageManager(environment.env)
-		const requestedPackageManager = values['package-manager']
-			?? await prompt?.choice('Package manager', PACKAGE_MANAGERS, detectedPackageManager)
-			?? detectedPackageManager
-		const packageManager = requestedPackageManager === 'auto' ? detectedPackageManager : requestedPackageManager
-		const initGit = values.git ?? !values['no-git']
-		const install = !(values['no-install'] || values['skip-install'])
+		const identity = await resolveProjectIdentity(positionals, values, environment, prompt)
+		const packageManager = await resolvePackageManager(values, environment, prompt)
+		const decisions = await resolveProjectDecisions(values, prompt)
+		const example = values.example ?? 'clean'
+		const style = values.style
+			?? await prompt?.choice('CSS Modules language', STYLE_LANGUAGES, 'css')
+			?? 'css'
 
 		return {
 			dryRun: values['dry-run'] ?? false,
@@ -56,17 +52,18 @@ export async function resolveProjectRequest(command, environment) {
 			terminal: Boolean(environment.stdin.isTTY),
 			specification: buildProjectSpecification({
 				colorScheme: values['color-scheme'],
-				demo: values.demo ?? await prompt?.choice('Start from', ['remove', 'keep'], 'remove') ?? 'remove',
-				description: values.description ?? `${title} web application.`,
-				destination: resolve(environment.cwd(), directory),
-				initGit: prompt ? await prompt.confirm('Initialize a Git repository?', initGit) : initGit,
-				install: prompt ? await prompt.confirm('Install dependencies?', install) : install,
+				description: values.description ?? `${identity.title} web application.`,
+				destination: resolve(environment.cwd(), identity.directory),
+				example,
+				initGit: decisions.initGit,
+				install: decisions.install,
 				language: values.lang,
-				name,
+				name: identity.name,
 				packageManager,
 				primaryColor: values['primary-color'],
+				style,
 				template: values.template,
-				title,
+				title: identity.title,
 			}),
 		}
 	}
@@ -77,9 +74,9 @@ export async function resolveProjectRequest(command, environment) {
 
 export function detectPackageManager(environment = {}) {
 	const userAgent = environment.npm_config_user_agent ?? ''
-	if (userAgent.startsWith('pnpm/')) return 'pnpm'
-	if (userAgent.startsWith('yarn/')) return 'yarn'
-	if (userAgent.startsWith('bun/')) return 'bun'
+	if (userAgent.startsWith('pnpm/')) {
+		return 'pnpm'
+	}
 	return 'npm'
 }
 
@@ -93,11 +90,11 @@ The interactive wizard only asks about decisions that affect the generated proje
 Application title and description are derived from the directory; pass flags only when automation needs overrides.
 
 Options:
-  --demo <keep|remove>           retain or remove the starter demo
-  --package-manager <manager>    auto, npm, pnpm, yarn, or bun
+  --package-manager <manager>    auto, npm, or pnpm
   --no-install                   create the project without installing dependencies
   --git, --no-git                initialize a Git repository (default: enabled)
   --dry-run                      show the resolved plan without writing files
+  --example <name>               clean or showcase (default: clean)
   --no-interactive, -y, --yes    accept defaults without prompts
   --title <title>                override the derived application title
   --description <description>    override the derived SEO description
@@ -105,6 +102,7 @@ Options:
   --lang <language>              document language (default: en)
   --color-scheme <scheme>        light, dark, or auto
   --primary-color <colour>       Mantine primary colour
+  --style <language>             css or scss (default: css)
   --template <owner/repo[#ref]>  use a compatible template source
   -v, --version                  show the CLI version
   -h, --help                     show this help
@@ -112,14 +110,16 @@ Options:
 }
 
 async function createPrompt(environment, values) {
-	if (!environment.stdin.isTTY || values.yes || values['no-interactive']) return undefined
+	if (!environment.stdin.isTTY || values.yes || values['no-interactive']) {
+		return undefined
+	}
 	prompts.intro('create-jst')
 	return {
 		async choice(label, choices, fallback) {
 			return resolvePrompt(await prompts.select({
 				initialValue: fallback,
 				message: label,
-				options: choices.map(value => ({ hint: choiceHint(value), label: choiceLabel(value), value })),
+				options: choices.map(value => ({ hint: choiceHint(value), label: value, value })),
 			}))
 		},
 		close() {
@@ -134,24 +134,66 @@ async function createPrompt(environment, values) {
 	}
 }
 
-function choiceLabel(value) {
-	return {
-		keep: 'Keep the JST demo',
-		remove: 'Start with a clean application',
-	}[value] ?? value
-}
-
 function choiceHint(value) {
 	return {
 		npm: 'default',
-		remove: 'recommended',
 	}[value]
 }
 
 function resolvePrompt(value) {
-	if (!prompts.isCancel(value)) return value
+	if (!prompts.isCancel(value)) {
+		return value
+	}
 	prompts.cancel('Setup cancelled.')
 	const error = new Error('Setup cancelled.')
 	error.name = 'PromptCancelledError'
 	throw error
 }
+
+function validateCommand(positionals, values) {
+	if (positionals.length > 1) {
+		throw new Error('Only one project directory can be provided.')
+	}
+	if (values.git && values['no-git']) {
+		throw new Error('Use either --git or --no-git, not both.')
+	}
+	if (values['no-install'] && values['skip-install']) {
+		throw new Error('Use either --no-install or --skip-install, not both.')
+	}
+	if (values.example && !EXAMPLES.includes(values.example)) {
+		throw new Error(`Example must be one of: ${EXAMPLES.join(', ')}.`)
+	}
+}
+
+async function resolveProjectIdentity(positionals, values, environment, prompt) {
+	const directory = positionals[0]
+		?? await prompt?.text('Project directory', 'my-jst-app')
+		?? 'my-jst-app'
+	const name = values.name
+		?? normalizePackageName(basename(resolve(environment.cwd(), directory)))
+
+	return {
+		directory,
+		name,
+		title: values.title ?? toTitle(name),
+	}
+}
+
+async function resolvePackageManager(values, environment, prompt) {
+	const detected = detectPackageManager(environment.env)
+	const requested = values['package-manager']
+		?? await prompt?.choice('Package manager', PACKAGE_MANAGERS, detected)
+		?? detected
+
+	return requested === 'auto' ? detected : requested
+}
+
+async function resolveProjectDecisions(values, prompt) {
+	const initGit = values.git ?? !values['no-git']
+	const install = !(values['no-install'] || values['skip-install'])
+
+	return {
+		initGit: prompt ? await prompt.confirm('Initialize a Git repository?', initGit) : initGit,
+		install: prompt ? await prompt.confirm('Install dependencies?', install) : install,
+	}
+}

package/src/ui/reporter.mjs

@@ -28,11 +28,12 @@ export function createReporter(output, environment = {}) {
 		plan(specification, request) {
 			usesClack = request.terminal
 			if (usesClack) {
-				if (!request.interactive) prompts.intro('create-jst')
+				if (!request.interactive) {
+					prompts.intro('create-jst')
+				}
 				prompts.note([
 					`Template: ${specification.template}`,
 					`Package manager: ${specification.packageManager}`,
-					`Starter demo: ${specification.demo}`,
 					`Install dependencies: ${specification.install ? 'yes' : 'no'}`,
 					`Initialize Git: ${specification.initGit ? 'yes' : 'no'}`,
 				].join('\n'), specification.destination)
@@ -43,23 +44,27 @@ export function createReporter(output, environment = {}) {
 			output.write(`  destination     ${specification.destination}\n`)
 			output.write(`  template        ${specification.template}\n`)
 			output.write(`  package manager ${specification.packageManager}\n`)
-			output.write(`  starter demo    ${specification.demo}\n`)
 			output.write(`  install         ${specification.install ? 'yes' : 'no'}\n`)
 			output.write(`  git             ${specification.initGit ? 'yes' : 'no'}\n\n`)
 		},
 		start(request) {
 			usesClack = request.terminal
 			if (usesClack) {
-				if (!request.interactive) prompts.intro('create-jst')
+				if (!request.interactive) {
+					prompts.intro('create-jst')
+				}
 				return
 			}
 			output.write(`\n${paint('38;5;203', 'JST')} ${dim('A foundation for replaceable layers')}\n\n`)
 		},
-		subscribe(events) {
-			return events.subscribe(event => {
-				if (event.type === 'project.initialized') return this.success(event.specification)
+		progress(event) {
+				if (event.type === 'project.initialized') {
+					return this.success(event.specification)
+				}
 				const message = progressMessages[event.type]
-				if (!message) return
+				if (!message) {
+					return
+				}
 				if (usesClack) {
 					activeSpinner?.stop()
 					activeSpinner = prompts.spinner()
@@ -67,7 +72,6 @@ export function createReporter(output, environment = {}) {
 					return
 				}
 				output.write(`${dim('  ◌')} ${message(event.specification)}\n`)
-			})
 		},
 		success(specification) {
 			if (usesClack) {

package/src/application/eventBus.mjs

@@ -1,12 +0,0 @@
-export function createEventBus() {
-	const subscribers = new Set()
-	return {
-		publish(event) {
-			for (const subscriber of subscribers) subscriber(event)
-		},
-		subscribe(subscriber) {
-			subscribers.add(subscriber)
-			return () => subscribers.delete(subscriber)
-		},
-	}
-}