create-jst 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JST Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# create-jst
+
+Create a web application from the [JST](https://github.com/jst-stack/jst) template.
+
+```bash
+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.
+
+```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 -- --dry-run
+```
+
+Use `--help` to view non-interactive options. The initializer never overwrites a non-empty directory.
+
+See [Architecture](./ARCHITECTURE.md) for the dependency boundaries and replaceable gateways.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-jst",
+  "version": "0.3.0",
+  "description": "Create a web application from the JST template.",
+  "type": "module",
+  "bin": {
+    "create-jst": "src/cli.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jst-stack/create-jst.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jst-stack/create-jst/issues"
+  },
+  "homepage": "https://github.com/jst-stack/jst#readme",
+  "license": "MIT",
+  "dependencies": {
+    "degit": "^3.10.0"
+  }
+}

package/src/application/eventBus.mjs

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

package/src/application/projectInitializer.mjs

@@ -0,0 +1,28 @@
+export function createProjectInitializer({ events, projectGateway, templateGateway }) {
+	return {
+		async execute(specification) {
+			await projectGateway.assertDestinationIsEmpty(specification.destination)
+
+			events.publish({ type: 'template.download.started', specification })
+			await templateGateway.clone(specification.template, specification.destination)
+
+			events.publish({ type: 'project.configuration.started', specification })
+			await projectGateway.configureTemplate(specification)
+
+			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.install) {
+				events.publish({ type: 'dependencies.installation.started', specification })
+				await projectGateway.installDependencies(specification.destination, specification.packageManager)
+			}
+
+			events.publish({ type: 'project.initialized', specification })
+		},
+	}
+}

package/src/cli.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+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))
+
+export async function run(argv, environment = process, application = createProjectApplication()) {
+	const reporter = createReporter(environment.stdout, environment.env)
+	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`)
+
+		const request = await resolveProjectRequest(command, environment)
+		if (request.dryRun) return reporter.plan(request.specification)
+
+		reporter.start()
+		const unsubscribe = reporter.subscribe(application.events)
+		try {
+			await application.initializer.execute(request.specification)
+		}
+		finally {
+			unsubscribe()
+		}
+	}
+	catch (error) {
+		reporter.error(error instanceof Error ? error.message : String(error))
+		environment.exitCode = 1
+	}
+}

package/src/composition/createProjectApplication.mjs

@@ -0,0 +1,15 @@
+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()
+	const initializer = createProjectInitializer({
+		events,
+		projectGateway: createNodeProjectGateway({ nodeExecutable }),
+		templateGateway: createDegitTemplateGateway(),
+	})
+	return { events, initializer }
+}

package/src/domain/projectSpecification.mjs

@@ -0,0 +1,43 @@
+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 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,
+		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,
+		title: input.title,
+	})
+	validateProjectSpecification(specification)
+	return specification
+}
+
+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(', ')}.`)
+}
+
+export function normalizePackageName(value) {
+	return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'jst-app'
+}
+
+export function toTitle(value) {
+	return value.replace(/^@[^/]+\//, '').split(/[-_.]+/).filter(Boolean).map(word => word[0].toUpperCase() + word.slice(1)).join(' ')
+}

package/src/infrastructure/degitTemplateGateway.mjs

@@ -0,0 +1,9 @@
+import degit from 'degit'
+
+export function createDegitTemplateGateway() {
+	return {
+		clone(source, destination) {
+			return degit(source, { disableCache: true, force: false, verbose: false }).clone(destination)
+		},
+	}
+}

package/src/infrastructure/nodeProjectGateway.mjs

@@ -0,0 +1,82 @@
+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 { 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 }) {
+	return {
+		assertDestinationIsEmpty,
+		configurePackageManager,
+		configureTemplate,
+		initializeGit,
+		installDependencies,
+	}
+
+	async function assertDestinationIsEmpty(destination) {
+		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}`)
+	}
+
+	function configureTemplate(specification) {
+		return run(nodeExecutable, [
+			'scripts/setup-template.mjs',
+			'--yes',
+			'--name', specification.name,
+			'--title', specification.title,
+			'--description', specification.description,
+			'--lang', specification.language,
+			'--color-scheme', specification.colorScheme,
+			'--primary-color', specification.primaryColor,
+			'--demo', specification.demo,
+		], specification.destination)
+	}
+
+	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')
+		const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+		manifest.packageManager = `${packageManager}@${version.trim()}`
+		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)
+	}
+
+	function installDependencies(destination, packageManager) {
+		return run(packageManager, installCommands[packageManager], destination, true)
+	}
+}
+
+function run(command, args, cwd, inheritOutput = false) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, { cwd, stdio: inheritOutput ? 'inherit' : 'pipe' })
+		let stderr = ''
+		child.stderr?.on('data', chunk => {
+			stderr += chunk
+		})
+		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.${stderr ? `\n${stderr.trim()}` : ''}`))
+		})
+	})
+}

package/src/ui/command.mjs

@@ -0,0 +1,130 @@
+import { basename, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { buildProjectSpecification, normalizePackageName, PACKAGE_MANAGERS, toTitle } from '../domain/projectSpecification.mjs'
+
+export function parseCommandLine(args) {
+	return parseArgs({
+		allowPositionals: true,
+		args,
+		options: {
+			'color-scheme': { type: 'string' },
+			'demo': { type: 'string' },
+			'description': { type: 'string' },
+			'dry-run': { type: 'boolean' },
+			'git': { type: 'boolean' },
+			'help': { short: 'h', type: 'boolean' },
+			'lang': { type: 'string' },
+			'name': { type: 'string' },
+			'no-git': { type: 'boolean' },
+			'no-install': { type: 'boolean' },
+			'no-interactive': { type: 'boolean' },
+			'package-manager': { type: 'string' },
+			'primary-color': { type: 'string' },
+			'skip-install': { type: 'boolean' },
+			'template': { type: 'string' },
+			'title': { type: 'string' },
+			'version': { short: 'v', type: 'boolean' },
+			'yes': { short: 'y', type: 'boolean' },
+		},
+		strict: true,
+	})
+}
+
+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.')
+
+	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'])
+
+		return {
+			dryRun: values['dry-run'] ?? false,
+			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.choice('Initialize a Git repository', ['yes', 'no'], initGit ? 'yes' : 'no') === 'yes' : initGit,
+				install: prompt ? await prompt.choice('Install dependencies', ['yes', 'no'], install ? 'yes' : 'no') === 'yes' : install,
+				language: values.lang,
+				name,
+				packageManager,
+				primaryColor: values['primary-color'],
+				template: values.template,
+				title,
+			}),
+		}
+	}
+	finally {
+		prompt?.close()
+	}
+}
+
+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'
+	return 'npm'
+}
+
+export function printHelp(output) {
+	output.write(`Create a web application from the JST template.
+
+Usage:
+  npm create jst@latest [directory] [options]
+
+The interactive wizard only asks about decisions that affect the generated project.
+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
+  --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
+  --no-interactive, -y, --yes    accept defaults without prompts
+  --title <title>                override the derived application title
+  --description <description>    override the derived SEO description
+  --name <name>                  override the derived npm package name
+  --lang <language>              document language (default: en)
+  --color-scheme <scheme>        light, dark, or auto
+  --primary-color <colour>       Mantine primary colour
+  --template <owner/repo[#ref]>  use a compatible template source
+  -v, --version                  show the CLI version
+  -h, --help                     show this help
+`)
+}
+
+async function createPrompt(environment, values) {
+	if (!environment.stdin.isTTY || values.yes || values['no-interactive']) return undefined
+	const { createInterface } = await import('node:readline/promises')
+	const reader = createInterface({ input: environment.stdin, output: environment.stdout })
+	return {
+		async choice(label, choices, fallback) {
+			const rendered = choices.map((choice, index) => `${index + 1}:${choice}`).join('  ')
+			const answer = (await reader.question(`  ${label} (${rendered}) [${fallback}]: `)).trim()
+			if (!answer) return fallback
+			const index = Number.parseInt(answer, 10)
+			return choices[index - 1] ?? answer
+		},
+		close() {
+			reader.close()
+		},
+		async text(label, fallback) {
+			return (await reader.question(`  ${label} [${fallback}]: `)).trim() || fallback
+		},
+	}
+}

package/src/ui/reporter.mjs

@@ -0,0 +1,45 @@
+import { basename } from 'node:path'
+
+const progressMessages = {
+	'dependencies.installation.started': specification => `Installing dependencies with ${specification.packageManager}`,
+	'git.initialization.started': () => 'Initialising Git',
+	'package-manager.configuration.started': specification => `Preparing ${specification.packageManager}`,
+	'project.configuration.started': specification => `Configuring ${specification.title}`,
+	'template.download.started': specification => `Downloading ${specification.template}`,
+}
+
+export function createReporter(output, environment = {}) {
+	const color = Boolean(output.isTTY) && !environment.NO_COLOR
+	const paint = (code, value) => color ? `\u001B[${code}m${value}\u001B[0m` : value
+	const dim = value => paint('2', value)
+
+	return {
+		error(message) {
+			output.write(`\n${paint('31', '✕')} ${message}\n`)
+		},
+		plan(specification) {
+			output.write(`\n${paint('38;5;203', 'JST')} ${dim('plan only — no files will be written')}\n\n`)
+			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() {
+			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)
+				const message = progressMessages[event.type]
+				if (message) output.write(`${dim('  ◌')} ${message(event.specification)}\n`)
+			})
+		},
+		success(specification) {
+			output.write(`\n${paint('38;5;114', 'Ready.')} ${specification.title} is in ${paint('38;5;203', basename(specification.destination))}.\n\n`)
+			output.write(`  ${dim('$')} cd ${basename(specification.destination)}\n`)
+			output.write(`  ${dim('$')} ${specification.packageManager} run dev\n\n`)
+		},
+	}
+}