create-harper 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# create-harper <a href="https://npmjs.com/package/create-harper"><img src="https://img.shields.io/npm/v/create-harper" alt="npm package"></a>
+
+## Scaffolding Your First Harper Project
+
+> **Compatibility Note:**
+> Harper requires [Node.js](https://nodejs.org/en/) version 20.19+, 22.12+. However, some templates require a higher Node.js version to work, please upgrade if your package manager warns about it.
+
+With NPM:
+
+```bash
+npm create harper@latest
+```
+
+With Yarn:
+
+```bash
+yarn create harper
+```
+
+With PNPM:
+
+```bash
+pnpm create harper
+```
+
+With Bun:
+
+```bash
+bun create harper
+```
+
+With Deno:
+
+```bash
+deno init --npm harper
+```
+
+Then follow the prompts!
+
+You can also directly specify the project name and the template you want to use via additional command line options. For example, to scaffold a Harper + Vue project, run:
+
+```bash
+# npm 7+, extra double-dash is needed:
+npm create harper@latest my-vue-app -- --template vue
+
+# yarn
+yarn create harper my-vue-app --template vue
+
+# pnpm
+pnpm create harper my-vue-app --template vue
+
+# Bun
+bun create harper my-vue-app --template vue
+
+# Deno
+deno init --npm harper my-vue-app --template vue
+```
+
+Currently supported template presets include:
+
+- `vanilla`
+- `vanilla-ts`
+- `vue`
+- `vue-ts`
+- `react`
+- `react-ts`
+- `react-swc`
+- `react-swc-ts`
+- `preact`
+- `preact-ts`
+- `lit`
+- `lit-ts`
+- `svelte`
+- `svelte-ts`
+- `solid`
+- `solid-ts`
+- `qwik`
+- `qwik-ts`
+
+You can use `.` for the project name to scaffold in the current directory.

package/index.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import * as prompts from '@clack/prompts';
+import { determineAgent } from '@vercel/detect-agent';
+import spawn from 'cross-spawn';
+import mri from 'mri';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultTargetDir } from './lib/constants/defaultTargetDir.js';
+import { FRAMEWORKS } from './lib/constants/frameworks.js';
+import { helpMessage } from './lib/constants/helpMessage.js';
+import { TEMPLATES } from './lib/constants/templates.js';
+import { crawlTemplateDir } from './lib/fs/crawlTemplateDir.js';
+import { emptyDir } from './lib/fs/emptyDir.js';
+import { formatTargetDir } from './lib/fs/formatTargetDir.js';
+import { isEmpty } from './lib/fs/isEmpty.js';
+import { install } from './lib/install.js';
+import { getFullCustomCommand } from './lib/pkg/getFullCustomCommand.js';
+import { getInstallCommand } from './lib/pkg/getInstallCommand.js';
+import { getRunCommand } from './lib/pkg/getRunCommand.js';
+import { isValidPackageName } from './lib/pkg/isValidPackageName.js';
+import { pkgFromUserAgent } from './lib/pkg/pkgFromUserAgent.js';
+import { toValidPackageName } from './lib/pkg/toValidPackageName.js';
+import { start } from './lib/start.js';
+
+const argv = mri(process.argv.slice(2), {
+	boolean: ['help', 'overwrite', 'immediate', 'interactive'],
+	alias: { h: 'help', t: 'template', i: 'immediate' },
+	string: ['template'],
+});
+const cwd = process.cwd();
+
+init().catch((e) => {
+	console.error(e);
+});
+
+async function init() {
+	const argTargetDir = argv._[0]
+		? formatTargetDir(String(argv._[0]))
+		: undefined;
+	const argTemplate = argv.template;
+	const argOverwrite = argv.overwrite;
+	const argImmediate = argv.immediate;
+	const argInteractive = argv.interactive;
+
+	const help = argv.help;
+	if (help) {
+		console.log(helpMessage);
+		return;
+	}
+
+	const interactive = argInteractive ?? process.stdin.isTTY;
+
+	// Detect AI agent environment for better agent experience (AX)
+	const { isAgent } = await determineAgent();
+	if (isAgent && interactive) {
+		console.log(
+			'\nTo create in one go, run: create-harper <DIRECTORY> --no-interactive --template <TEMPLATE>\n',
+		);
+	}
+
+	const pkgInfo = pkgFromUserAgent(process.env.npm_config_user_agent);
+	const cancel = () => prompts.cancel('Operation cancelled');
+
+	// 1. Get project name and target dir
+	let targetDir = argTargetDir;
+	let projectName = targetDir;
+	if (!targetDir) {
+		if (interactive) {
+			projectName = await prompts.text({
+				message: 'Project name:',
+				defaultValue: defaultTargetDir,
+				placeholder: defaultTargetDir,
+				validate: (value) => {
+					return !value || formatTargetDir(value).length > 0
+						? undefined
+						: 'Invalid project name';
+				},
+			});
+			if (prompts.isCancel(projectName)) { return cancel(); }
+			targetDir = formatTargetDir(projectName);
+		} else {
+			targetDir = defaultTargetDir;
+		}
+	}
+
+	// 2. Handle directory if exist and not empty
+	if (fs.existsSync(targetDir) && !isEmpty(targetDir)) {
+		let overwrite = argOverwrite
+			? 'yes'
+			: undefined;
+		if (!overwrite) {
+			if (interactive) {
+				const res = await prompts.select({
+					message: (targetDir === '.'
+						? 'Current directory'
+						: `Target directory "${targetDir}"`)
+						+ ` is not empty. Please choose how to proceed:`,
+					options: [
+						{
+							label: 'Cancel operation',
+							value: 'no',
+						},
+						{
+							label: 'Remove existing files and continue',
+							value: 'yes',
+						},
+						{
+							label: 'Ignore files and continue',
+							value: 'ignore',
+						},
+					],
+				});
+				if (prompts.isCancel(res)) { return cancel(); }
+				overwrite = res;
+			} else {
+				overwrite = 'no';
+			}
+		}
+
+		switch (overwrite) {
+			case 'yes':
+				emptyDir(targetDir);
+				break;
+			case 'no':
+				cancel();
+				return;
+		}
+	}
+
+	// 3. Get package name
+	let packageName = path.basename(path.resolve(targetDir));
+	if (!isValidPackageName(packageName)) {
+		if (interactive) {
+			const packageNameResult = await prompts.text({
+				message: 'Package name:',
+				defaultValue: toValidPackageName(packageName),
+				placeholder: toValidPackageName(packageName),
+				validate(dir) {
+					if (dir && !isValidPackageName(dir)) {
+						return 'Invalid package.json name';
+					}
+				},
+			});
+			if (prompts.isCancel(packageNameResult)) { return cancel(); }
+			packageName = packageNameResult;
+		} else {
+			packageName = toValidPackageName(packageName);
+		}
+	}
+
+	// 4. Choose a framework and variant
+	let template = argTemplate;
+	let hasInvalidArgTemplate = false;
+	if (argTemplate && !TEMPLATES.includes(argTemplate)) {
+		template = undefined;
+		hasInvalidArgTemplate = true;
+	}
+	if (!template) {
+		if (interactive) {
+			const framework = await prompts.select({
+				message: hasInvalidArgTemplate
+					? `"${argTemplate}" isn't a valid template. Please choose from below: `
+					: 'Select a framework:',
+				options: FRAMEWORKS
+					.filter(framework => !framework.hidden)
+					.map((framework) => {
+						const frameworkColor = framework.color;
+						return {
+							label: frameworkColor(framework.display || framework.name),
+							value: framework,
+						};
+					}),
+			});
+			if (prompts.isCancel(framework)) { return cancel(); }
+
+			const variant = framework.variants.length === 1
+				? framework.variants[0].name
+				: await prompts.select({
+					message: 'Select a variant:',
+					options: framework.variants.map((variant) => {
+						const variantColor = variant.color;
+						const command = variant.customCommand
+							? getFullCustomCommand(variant.customCommand, pkgInfo).replace(
+								/ TARGET_DIR$/,
+								'',
+							)
+							: undefined;
+						return {
+							label: variantColor(variant.display || variant.name),
+							value: variant.name,
+							hint: command,
+						};
+					}),
+				});
+			if (prompts.isCancel(variant)) { return cancel(); }
+
+			template = variant;
+		} else {
+			template = 'vanilla-ts';
+		}
+	}
+
+	const pkgManager = pkgInfo ? pkgInfo.name : 'npm';
+
+	const root = path.join(cwd, targetDir);
+
+	const { customCommand } = FRAMEWORKS.flatMap((f) => f.variants).find((v) => v.name === template) ?? {};
+
+	if (customCommand) {
+		const fullCustomCommand = getFullCustomCommand(customCommand, pkgInfo);
+
+		const [command, ...args] = fullCustomCommand.split(' ');
+		// we replace TARGET_DIR here because targetDir may include a space
+		const replacedArgs = args.map((arg) => arg.replace('TARGET_DIR', () => targetDir));
+		const { status } = spawn.sync(command, replacedArgs, {
+			stdio: 'inherit',
+		});
+		process.exit(status ?? 0);
+	}
+
+	// 5. Ask about immediate install and package manager
+	let immediate = argImmediate;
+	if (immediate === undefined) {
+		if (interactive) {
+			const immediateResult = await prompts.confirm({
+				message: `Install with ${pkgManager} and start now?`,
+			});
+			if (prompts.isCancel(immediateResult)) { return cancel(); }
+			immediate = immediateResult;
+		} else {
+			immediate = false;
+		}
+	}
+
+	// Only create a directory for built-in templates, not for customCommand
+	fs.mkdirSync(root, { recursive: true });
+	prompts.log.step(`Scaffolding project in ${root}...`);
+
+	const context = {
+		projectName,
+		packageName,
+	};
+
+	const templateSharedDir = path.resolve(fileURLToPath(import.meta.url), '..', `template-shared`);
+	crawlTemplateDir(root, templateSharedDir, context);
+
+	const templateDir = path.resolve(fileURLToPath(import.meta.url), '..', `template-${template}`);
+	crawlTemplateDir(root, templateDir, context);
+
+	if (immediate) {
+		install(root, pkgManager);
+		start(root, pkgManager);
+	} else {
+		let doneMessage = '';
+		const cdProjectName = path.relative(cwd, root);
+		doneMessage += `Done. Now run:\n`;
+		if (root !== cwd) {
+			doneMessage += `\n  cd ${cdProjectName.includes(' ') ? `"${cdProjectName}"` : cdProjectName}`;
+		}
+		doneMessage += `\n  ${getInstallCommand(pkgManager).join(' ')}`;
+		doneMessage += `\n  ${getRunCommand(pkgManager, 'dev').join(' ')}`;
+		prompts.outro(doneMessage);
+	}
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "create-harper",
+	"version": "0.0.1",
+	"type": "module",
+	"author": {
+		"name": "HarperDB",
+		"email": "support@harperdb.io"
+	},
+	"bin": {
+		"create-harper": "index.js",
+		"cha": "index.js"
+	},
+	"files": [
+		"index.js",
+		"template-*"
+	],
+	"scripts": {
+		"lint": "oxlint .",
+		"lint:fix": "oxlint . --fix",
+		"format": "dprint check",
+		"format:fix": "dprint fmt",
+		"format:staged": "dprint check --staged",
+		"test": "vitest"
+	},
+	"engines": {
+		"node": "^20.19.0 || >=22.12.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/harperfast/create-harper.git"
+	},
+	"bugs": {
+		"url": "https://github.com/harperfast/create-harper/issues"
+	},
+	"homepage": "https://github.com/harperfast",
+	"dependencies": {
+		"@clack/prompts": "^1.0.0-alpha.9",
+		"@vercel/detect-agent": "^1.0.0",
+		"cross-spawn": "^7.0.6",
+		"lodash": "^4.17.21",
+		"mri": "^1.2.0",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"dprint": "^0.51.1",
+		"harperdb": "^4.7.15",
+		"oxlint": "^1.38.0",
+		"vitest": "^4.0.17"
+	}
+}