create-thunderous 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan DeWitt
+
+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/bin/index.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { input, confirm, select } from '@inquirer/prompts';
+import stringWidth from 'string-width';
+import chalk from 'chalk';
+import { emojify } from 'node-emoji';
+import { shimConsoleLog } from 'emoji-space-shim';
+
+const shim = shimConsoleLog();
+process.on('exit', () => {
+	shim.restore();
+});
+
+const DEFAULT_NAME = 'Thunderous Project';
+const DEFAULT_PACKAGE_MANAGER = 'pnpm';
+const PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn'];
+const PLACEHOLDER = '{{ APP_NAME }}';
+
+const program = new Command();
+
+program
+	.name('create-thunderous')
+	.description('Scaffold a new Thunderous project')
+	.version('0.0.0')
+	.argument('[project-name]', 'project name, or "." to scaffold in the current directory')
+	.option('--current-dir', 'scaffold in the current directory')
+	.option('-p, --package-manager <name>', `package manager to use (${PACKAGE_MANAGERS.join(', ')})`)
+	.showHelpAfterError('(add --help for additional information)')
+	.configureOutput({
+		outputError: (str, write) => write(`\x1b[31m${str}\x1b[0m`),
+	});
+
+program.parse();
+
+const options = program.opts();
+const rawNameArg = program.args[0];
+
+await main({
+	rawNameArg,
+	currentDir: Boolean(options.currentDir),
+	packageManager: options.packageManager,
+});
+
+async function main({ rawNameArg, currentDir, packageManager }) {
+	const cwd = process.cwd();
+	const currentDirName = path.basename(cwd);
+	const dotMeansCurrentDir = rawNameArg === '.';
+
+	let projectName = dotMeansCurrentDir ? currentDirName : rawNameArg;
+
+	if (!projectName) {
+		projectName = await input({
+			message: 'Project name',
+			default: DEFAULT_NAME,
+		});
+	}
+
+	projectName = projectName.trim() || DEFAULT_NAME;
+
+	const namesMatch = looselyMatches(projectName, currentDirName);
+
+	let targetDir = cwd;
+	let createdFolder = false;
+
+	if (currentDir || dotMeansCurrentDir) {
+		targetDir = cwd;
+	} else if (!namesMatch) {
+		targetDir = path.join(cwd, toKebabCase(projectName));
+		createdFolder = true;
+	}
+
+	ensureTargetIsUsable(targetDir, createdFolder);
+
+	const chosenPackageManager = await choosePackageManager(packageManager);
+
+	const templateDir = path.resolve(getScriptDir(), '../reference-project');
+	if (!fs.existsSync(templateDir)) {
+		fail(`Could not find reference-project at: ${templateDir}`);
+	}
+
+	logStep('Scaffolding project files');
+	copyDirectoryContents(templateDir, targetDir);
+	replacePlaceholderInDirectory(targetDir, PLACEHOLDER, projectName);
+
+	logStep(`Preparing ${chosenPackageManager}`);
+	ensurePackageManagerInstalled(chosenPackageManager);
+
+	logStep(`Installing dependencies with ${chosenPackageManager}`);
+	runInstall(chosenPackageManager, targetDir);
+
+	const shouldInitializeGit = await confirm({
+		message: 'Initialize git repository?',
+		default: true,
+	});
+
+	if (shouldInitializeGit) {
+		logStep('Initializing git repository');
+		runCommand('git', ['init'], { cwd: targetDir });
+		runCommand('git', ['add', '.'], { cwd: targetDir });
+		runCommand('git', ['commit', '-m', 'Initial commit'], { cwd: targetDir });
+	}
+
+	printSuccess(projectName, targetDir, cwd, chosenPackageManager);
+}
+
+async function choosePackageManager(explicitValue) {
+	if (explicitValue) {
+		const normalized = explicitValue.toLowerCase();
+		if (!PACKAGE_MANAGERS.includes(normalized)) {
+			fail(`Unsupported package manager "${explicitValue}". Use one of: ${PACKAGE_MANAGERS.join(', ')}`);
+		}
+		return normalized;
+	}
+
+	return await select({
+		message: 'Which package manager would you like to use?',
+		default: DEFAULT_PACKAGE_MANAGER,
+		choices: [
+			{ name: 'pnpm', value: 'pnpm' },
+			{ name: 'npm', value: 'npm' },
+			{ name: 'yarn', value: 'yarn' },
+		],
+	});
+}
+
+function normalizeForComparison(value) {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.replace(/[_-]+/g, ' ')
+		.replace(/[^\p{L}\p{N}]+/gu, ' ')
+		.toLowerCase()
+		.trim()
+		.replace(/\s+/g, ' ');
+}
+
+function looselyMatches(a, b) {
+	return normalizeForComparison(a) === normalizeForComparison(b);
+}
+
+function toKebabCase(value) {
+	return normalizeForComparison(value).replace(/\s+/g, '-');
+}
+
+function ensureTargetIsUsable(targetDir, createdFolder) {
+	if (!fs.existsSync(targetDir)) {
+		fs.mkdirSync(targetDir, { recursive: true });
+		return;
+	}
+
+	const entries = fs.readdirSync(targetDir);
+	if (entries.length > 0 && createdFolder) {
+		fail(`Target directory already exists and is not empty: ${targetDir}`);
+	}
+}
+
+function copyDirectoryContents(sourceDir, targetDir) {
+	fs.mkdirSync(targetDir, { recursive: true });
+
+	for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+		const sourcePath = path.join(sourceDir, entry.name);
+		const targetPath = path.join(targetDir, entry.name);
+
+		if (entry.isDirectory()) {
+			fs.cpSync(sourcePath, targetPath, { recursive: true });
+		} else {
+			fs.copyFileSync(sourcePath, targetPath);
+		}
+	}
+}
+
+function replacePlaceholderInDirectory(dir, searchValue, replacementValue) {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const fullPath = path.join(dir, entry.name);
+
+		if (entry.isDirectory()) {
+			replacePlaceholderInDirectory(fullPath, searchValue, replacementValue);
+			continue;
+		}
+
+		if (!entry.isFile()) continue;
+		if (looksBinary(fullPath)) continue;
+
+		const original = fs.readFileSync(fullPath, 'utf8');
+		const updated = original.split(searchValue).join(replacementValue);
+
+		if (updated !== original) {
+			fs.writeFileSync(fullPath, updated, 'utf8');
+		}
+	}
+}
+
+function looksBinary(filePath) {
+	const buffer = fs.readFileSync(filePath);
+	const sampleSize = Math.min(buffer.length, 8000);
+
+	for (let i = 0; i < sampleSize; i++) {
+		if (buffer[i] === 0) return true;
+	}
+
+	return false;
+}
+
+function ensurePackageManagerInstalled(packageManager) {
+	if (hasCommand(packageManager)) return;
+
+	if (packageManager === 'npm') {
+		fail('npm is not available on this system. Install Node.js first, since npm is bundled with Node.');
+	}
+
+	if (!hasCommand('corepack')) {
+		if (!hasCommand('npm')) {
+			fail(
+				`${packageManager} is not installed, and Corepack is unavailable. Install Node.js/npm or install ${packageManager} manually.`,
+			);
+		}
+
+		logSubstep('Installing Corepack');
+		runCommand('npm', ['install', '-g', 'corepack@latest']);
+	}
+
+	logSubstep(`Enabling Corepack shim for ${packageManager}`);
+	runCommand('corepack', ['enable', packageManager]);
+
+	logSubstep(`Installing ${packageManager} via Corepack`);
+	runCommand('corepack', ['install', '-g', `${packageManager}@latest`]);
+
+	if (!hasCommand(packageManager)) {
+		fail(`Failed to make ${packageManager} available on PATH.`);
+	}
+}
+
+function runInstall(packageManager, cwd) {
+	if (packageManager === 'npm') {
+		runCommand('npm', ['install'], { cwd });
+		return;
+	}
+
+	if (packageManager === 'pnpm') {
+		runCommand('pnpm', ['install'], { cwd });
+		return;
+	}
+
+	if (packageManager === 'yarn') {
+		runCommand('yarn', ['install'], { cwd });
+		return;
+	}
+
+	fail(`Unsupported package manager: ${packageManager}`);
+}
+
+function hasCommand(command) {
+	const result = spawnSync(command, ['--version'], {
+		stdio: 'ignore',
+		shell: process.platform === 'win32',
+	});
+
+	return result.status === 0;
+}
+
+function runCommand(command, args, options = {}) {
+	const result = spawnSync(command, args, {
+		stdio: 'inherit',
+		cwd: options.cwd,
+		shell: process.platform === 'win32',
+	});
+
+	if (result.error) {
+		fail(`Failed to run "${command} ${args.join(' ')}": ${result.error.message}`);
+	}
+
+	if (result.status !== 0) {
+		fail(`Command failed: ${command} ${args.join(' ')}`);
+	}
+}
+
+function getScriptDir() {
+	return path.dirname(fileURLToPath(import.meta.url));
+}
+
+function stripAnsi(value) {
+	return value.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function visibleWidth(value) {
+	return stringWidth(stripAnsi(value));
+}
+
+function printSuccess(projectName, targetDir, originalCwd, packageManager) {
+	const lines = [
+		`${chalk.blue(emojify(':cloud_with_lightning:'))}  ${chalk.magenta('Thunderous project created successfully!')} ${chalk.blue(emojify(':cloud_with_lightning:'))}`,
+		'',
+		`    ${chalk.bold('Name:')} ${chalk.blue(projectName)}`,
+		`    ${chalk.bold('Package manager:')} ${chalk.blue(packageManager)}`,
+		`    ${chalk.bold('Location:')} ${chalk.underline(chalk.blue(targetDir))}`,
+		'',
+		`    ${chalk.bold(targetDir !== originalCwd ? 'Next steps:' : 'Next step:')}`,
+		...(targetDir !== originalCwd ? [chalk.blue(`      cd ${path.relative(originalCwd, targetDir) || '.'}`)] : []),
+		chalk.blue(`      ${packageManager} dev`),
+	];
+
+	printBox(lines, {
+		borderColor: 'magenta',
+		textColor: 'white',
+		padding: 2,
+		marginBottom: 1,
+	});
+}
+
+function printBox(lines, options = {}) {
+	const { borderColor = '', textColor = '', padding = 0, marginTop = 1, marginBottom = 0 } = options;
+
+	const contentWidth = Math.max(...lines.map((line) => visibleWidth(line)), 0);
+	const innerWidth = contentWidth + padding * 2;
+	const horizontalWidth = innerWidth + 2;
+	const bc = chalk[borderColor];
+	const tc = chalk[textColor];
+
+	const top = bc(`╭${'─'.repeat(horizontalWidth)}──╮`);
+	const bottom = bc(`╰${'─'.repeat(horizontalWidth)}──╯`);
+	const emptyLine = `${bc('│')} ${' '.repeat(innerWidth)}   ${bc('│')}`;
+
+	if (marginTop > 0) {
+		process.stdout.write('\n'.repeat(marginTop));
+	}
+
+	console.log(top);
+	console.log(emptyLine);
+
+	for (const line of lines) {
+		const width = visibleWidth(line);
+		const rightPad = innerWidth - width - padding;
+		const paddedLine = ' '.repeat(padding) + line + ' '.repeat(Math.max(0, rightPad));
+
+		console.log(`${bc('│')} ${tc(paddedLine)}   ${bc('│')}`);
+	}
+
+	console.log(emptyLine);
+	console.log(bottom);
+
+	if (marginBottom > 0) {
+		process.stdout.write('\n'.repeat(marginBottom));
+	}
+}
+
+function logStep(message) {
+	console.log('');
+	console.log(`\x1b[36m▶\x1b[0m ${message}`);
+}
+
+function logSubstep(message) {
+	console.log(`  \x1b[90m•\x1b[0m ${message}`);
+}
+
+function fail(message) {
+	console.error('');
+	console.error(`\x1b[31m✖ ${message}\x1b[0m`);
+	process.exit(1);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "create-thunderous",
+  "version": "0.0.0",
+  "description": "A CLI tool to scaffold a new project using the Thunderous stack.",
+  "main": "index.js",
+  "bin": {
+    "create-thunderous": "./bin/index.js"
+  },
+  "keywords": [
+    "thunderous",
+    "create",
+    "starter",
+    "template"
+  ],
+  "author": "Jonathan DeWitt <jon.dewitt@thunder.solutions>",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "emoji-space-shim": "^0.1.7",
+    "node-emoji": "^2.2.0",
+    "string-width": "^8.2.0"
+  }
+}

package/reference-project/.prettierrc.json

@@ -0,0 +1,17 @@
+{
+	"useTabs": true,
+	"printWidth": 120,
+	"trailingComma": "all",
+	"quoteProps": "consistent",
+	"singleQuote": true,
+	"endOfLine": "auto",
+	"overrides": [
+		{
+			"files": "*.md",
+			"options": {
+				"tabWidth": 2,
+				"useTabs": false
+			}
+		}
+	]
+}

package/reference-project/README.md

@@ -0,0 +1,7 @@
+# Thunderous Project
+
+This project was generated using `create-thunderous`. By default, it includes a simple structure with examples and comments to help you get started.
+
+For more information, see the [Thunderous documentation](https://thunderous.dev/docs).
+
+> **Note**: The documentation may not be up to date yet, and thus may not include information about the full Thunderous stack. Please refer to the [source code](https://github.com/thunder-solutions/thunderous/tree/trunk) for the latest information.

package/reference-project/eslint.config.mjs

@@ -0,0 +1,16 @@
+import js from '@eslint/js';
+import ts from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig([
+	js.configs.recommended,
+	...ts.configs.recommended,
+	{
+		rules: {
+			'@typescript-eslint/no-explicit-any': 'error',
+		},
+	},
+	{
+		ignores: ['package-lock.json', 'node_modules/', 'dist/', '**/*.tmp.*'],
+	},
+]);

package/reference-project/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "{{ APP_NAME }}",
+	"version": "0.0.0",
+	"description": "A demo to showcase Thunderous server capabilities.",
+	"license": "ISC",
+	"author": "",
+	"type": "module",
+	"main": "index.js",
+	"scripts": {
+		"start": "serve dist",
+		"dev": "thunderous dev",
+		"build": "thunderous build",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"format": "prettier --check .",
+		"format:fix": "prettier --write . --list-different",
+		"typecheck": "tsc --noEmit",
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"devDependencies": {
+		"@eslint/css": "^0.13.0",
+		"@eslint/js": "^9.38.0",
+		"@eslint/json": "^0.13.2",
+		"@total-typescript/ts-reset": "^0.6.1",
+		"@types/express": "^5.0.3",
+		"@types/node": "^24.9.1",
+		"@typescript-eslint/eslint-plugin": "^8.46.2",
+		"eslint": "^9.38.0",
+		"prettier": "^3.6.2",
+		"serve": "^14.2.5",
+		"thunderous-server": "^0.0.0",
+		"tsx": "^4.20.6",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.46.2",
+		"undici-types": "^7.16.0"
+	},
+	"dependencies": {
+		"thunderous": "^2.4.1",
+		"thunderous-csr": "^0.0.0"
+	}
+}