@wolfstar/create-http-framework 1.0.1 → 2.1.0

package/README.md

@@ -0,0 +1,69 @@
+# `@wolfstar/create-http-framework`
+
+A CLI scaffolding tool for creating new [WolfStar HTTP Framework](https://github.com/wolfstar-project/stars-components/tree/main/packages/http-framework) bot projects.
+
+## Usage
+
+```bash
+npm create @wolfstar/http-framework@latest my-discord-bot
+# or
+pnpm create @wolfstar/http-framework my-discord-bot
+# or
+yarn create @wolfstar/http-framework my-discord-bot
+# or
+bun create @wolfstar/http-framework my-discord-bot
+```
+
+The CLI will guide you through the following prompts:
+
+- **Project name** — an npm-compatible name for your bot
+- **Package manager** — npm, yarn, pnpm, or bun
+- **Language** — TypeScript or JavaScript
+- **Build tool** — tsdown, TypeScript 6, or the TypeScript 7 release candidate
+- **Linter and formatter** — Oxlint / ESLint and Oxfmt / Prettier
+- **Port** — the port the HTTP server will listen on (default: `3000`)
+- **i18n support** — optionally add `@wolfstar/http-framework-i18n`
+- **Auto-install** — install dependencies immediately after scaffolding
+
+## Options
+
+| Flag                         | Alias | Description                                                 |
+| ---------------------------- | ----- | ----------------------------------------------------------- |
+| `--overwrite`                |       | Overwrite the target directory if it already exists         |
+| `--no-interactive`           |       | Skip all prompts and use defaults / flags                   |
+| `--interactive`              | `-i`  | Force interactive prompts even when an AI agent is detected |
+| `--package-manager <pm>`     |       | Choose npm, yarn, pnpm, or bun                              |
+| `--language <lang>`          |       | Choose TypeScript (`ts`) or JavaScript (`js`)               |
+| `--build <tool>`             |       | Choose `tsc6`, `tsc7`, or `tsdown` for TypeScript           |
+| `--lint <linter>`            |       | Choose `none`, `eslint`, or `oxlint`                        |
+| `--format <formatter>`       |       | Choose `none`, `prettier`, or `oxfmt`                       |
+| `--port <number>`            |       | Set the HTTP port (default: `3000`)                         |
+| `--i18n` / `--no-i18n`       |       | Enable or disable i18n support                              |
+| `--install` / `--no-install` |       | Enable or disable dependency installation                   |
+| `--help`                     | `-h`  | Print usage and exit                                        |
+
+## Non-interactive / AI agent mode
+
+When the CLI detects an AI agent is running it (via [`@vercel/detect-agent`](https://www.npmjs.com/package/@vercel/detect-agent)), it automatically enters non-interactive mode, equivalent to passing `--no-interactive`. A project name argument is required in this mode:
+
+```bash
+create-http-framework my-discord-bot --no-interactive
+```
+
+## Generated project structure
+
+```
+my-discord-bot/
+├── src/
+│   ├── commands/
+│   │   └── ping.ts     # Example ping command
+│   └── index.ts        # Entry point — starts the HTTP server
+├── .env                # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
+├── .gitignore
+├── package.json
+└── tsconfig.json
+```
+
+## Requirements
+
+- Node.js `>=20`

package/dist/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { cancel, confirm, intro, isCancel, outro, spinner, text } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import { determineAgent } from "@vercel/detect-agent";
+import mri from "mri";
 import { dirname, join, relative, resolve } from "node:path";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import spawn from "cross-spawn";
 import { resolveCommand } from "package-manager-detector/commands";
 import { detect } from "package-manager-detector/detect";
 import Handlebars from "handlebars";
@@ -10,64 +12,395 @@ import { fileURLToPath } from "node:url";
 
 //#region src/tools/fileSystem.ts
 function directoryExists(path) {
-	return existsSync(path);
+	return existsSync(path) && statSync(path).isDirectory();
+}
+function isEmpty(path) {
+	try {
+		return readdirSync(path).length === 0;
+	} catch (error) {
+		if (error.code === "ENOENT") return true;
+		throw error;
+	}
+}
+function emptyDir(dir) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) rmSync(join(dir, entry.name), {
+		recursive: true,
+		force: true
+	});
 }
 function writeFile(filePath, content) {
 	mkdirSync(dirname(filePath), { recursive: true });
 	writeFileSync(filePath, content, "utf-8");
 }
 
+//#endregion
+//#region src/tools/options.ts
+const PACKAGE_MANAGERS = [
+	"npm",
+	"yarn",
+	"pnpm",
+	"bun"
+];
+const LANGUAGES = ["ts", "js"];
+const BUILD_TOOLS = [
+	"tsc6",
+	"tsc7",
+	"tsdown"
+];
+const LINTERS = [
+	"none",
+	"eslint",
+	"oxlint"
+];
+const FORMATTERS = [
+	"none",
+	"prettier",
+	"oxfmt"
+];
+/**
+* TypeScript 7.0 (the native compiler) ships under the main `typescript` package on the `rc`
+* dist-tag. We pin it exactly because it is a prerelease (the old separate `@typescript/native-preview`
+* package only has dev builds).
+*/
+const TYPESCRIPT_RC_VERSION = "7.0.1-rc";
+
 //#endregion
 //#region src/tools/npmHelpers.ts
-function fetchVersion(packageName) {
-	try {
-		return execFileSync("npm", [
-			"show",
-			packageName,
-			"version"
-		], {
-			encoding: "utf-8",
-			stdio: "pipe"
-		}).trim();
-	} catch {
-		return "latest";
-	}
-}
-function fetchDependencyVersions() {
-	return {
-		httpFramework: fetchVersion("@wolfstar/http-framework"),
-		httpFrameworkI18n: fetchVersion("@wolfstar/http-framework-i18n"),
-		discordApiTypes: fetchVersion("discord-api-types"),
-		typescript: fetchVersion("typescript"),
-		tsNode: fetchVersion("ts-node"),
-		typesNode: fetchVersion("@types/node"),
-		discordJsBuilders: fetchVersion("@discordjs/builders")
-	};
+async function fetchVersion(packageName) {
+	const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+	if (!response.ok) throw new Error(`Failed to resolve latest version for ${packageName}: ${response.status} ${response.statusText}`);
+	return (await response.json()).version;
+}
+/**
+* Resolves the latest versions of only the packages required by the chosen selections.
+* `ts-node` is intentionally never included. TypeScript 7.0 (tsc7) is pinned to the rc instead
+* of being fetched, because `typescript@latest` resolves to the 6.x line.
+*/
+async function fetchDependencyVersions(selections) {
+	const names = /* @__PURE__ */ new Set([
+		"@wolfstar/http-framework",
+		"discord-api-types",
+		"@discordjs/builders"
+	]);
+	if (selections.i18n) names.add("@wolfstar/http-framework-i18n");
+	if (selections.language === "ts") {
+		names.add("@types/node");
+		switch (selections.buildTool) {
+			case "tsc6":
+				names.add("typescript").add("tsc-watch");
+				break;
+			case "tsc7":
+				names.add("tsc-watch");
+				break;
+			case "tsdown":
+				names.add("tsdown").add("typescript");
+				break;
+		}
+	}
+	if (selections.linter === "eslint") {
+		names.add("eslint");
+		names.add(selections.language === "ts" ? "typescript-eslint" : "@eslint/js");
+	}
+	if (selections.linter === "oxlint") names.add("oxlint");
+	if (selections.formatter === "prettier") names.add("prettier");
+	if (selections.formatter === "oxfmt") names.add("oxfmt");
+	const list = [...names];
+	const resolved = await Promise.all(list.map(fetchVersion));
+	const versions = {};
+	list.forEach((name, index) => {
+		versions[name] = resolved[index];
+	});
+	if (selections.language === "ts" && selections.buildTool === "tsc7") versions["typescript"] = TYPESCRIPT_RC_VERSION;
+	return versions;
 }
 
 //#endregion
 //#region src/tools/packageManager.ts
-async function detectPackageManager(installIn) {
+async function detectPackageManager() {
 	const detected = await detect({ cwd: process.cwd() });
-	const agent = detected?.agent ?? "npm";
-	const name = detected?.name ?? "npm";
-	if (installIn) {
-		const resolved = resolveCommand(agent, "install", []);
-		if (!resolved) throw new Error(`Could not resolve install command for ${agent}`);
-		execFileSync(resolved.command, resolved.args, {
-			cwd: installIn,
-			stdio: process.env["DEBUG"] ? "inherit" : "pipe"
-		});
+	if (detected?.name) return detected.name;
+	const userAgent = process.env["npm_config_user_agent"];
+	if (userAgent) {
+		const name = userAgent.split("/")[0];
+		if ([
+			"npm",
+			"yarn",
+			"pnpm",
+			"bun",
+			"deno"
+		].includes(name)) return name;
 	}
-	return name;
+	return "npm";
+}
+function quoteToken(token) {
+	return /\s/.test(token) ? `"${token}"` : token;
+}
+/**
+* Builds the correct "run a script" command string for the given package manager, e.g.
+* `npm run build` / `pnpm run build`. Extra args are forwarded the way each manager expects
+* (npm inserts the `--` separator automatically), and tokens containing spaces are quoted so
+* nested commands (`--onSuccess "pnpm run start"`) survive being placed in a package.json script.
+*/
+function getRunScript(pm, script, args = []) {
+	const resolved = resolveCommand(pm, "run", [script, ...args]);
+	if (!resolved) throw new Error(`Could not resolve run command for ${pm}`);
+	return [resolved.command, ...resolved.args].map(quoteToken).join(" ");
+}
+/** Returns the install command string for the given package manager, e.g. `pnpm install`. */
+function getInstallScript(pm) {
+	const resolved = resolveCommand(pm, "install", []);
+	if (!resolved) throw new Error(`Could not resolve install command for ${pm}`);
+	return [resolved.command, ...resolved.args].map(quoteToken).join(" ");
+}
+async function installDependencies(pm, dir) {
+	const agent = (await detect({ cwd: process.cwd() }))?.agent ?? pm;
+	const resolved = resolveCommand(agent, "install", []);
+	if (!resolved) throw new Error(`Could not resolve install command for ${agent}`);
+	const result = spawn.sync(resolved.command, resolved.args, {
+		cwd: dir,
+		stdio: process.env["DEBUG"] ? "inherit" : "pipe"
+	});
+	if (result.error) throw result.error;
+	if (result.status !== 0) throw new Error(`Dependency installation failed with exit code ${result.status ?? "unknown"}`);
+}
+/** Runs an arbitrary command in `dir` via cross-spawn (used for the post-scaffold formatter pass). */
+function runCommand(command, args, dir) {
+	const result = spawn.sync(command, args, {
+		cwd: dir,
+		stdio: process.env["DEBUG"] ? "inherit" : "pipe"
+	});
+	if (result.error) throw result.error;
+	if (result.status !== 0) throw new Error(`Command "${command}" failed with exit code ${result.status ?? "unknown"}`);
+}
+
+//#endregion
+//#region src/tools/projectFiles.ts
+const caret = (version) => `^${version}`;
+function sortKeys(record) {
+	return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+function json(value) {
+	return `${JSON.stringify(value, null, "	")}\n`;
+}
+function buildScripts(ctx) {
+	const { packageManager: pm, buildTool } = ctx;
+	const start = "node dist/index.js";
+	let scripts;
+	if (ctx.language === "js") scripts = {
+		start: "node src/index.js",
+		dev: "node --watch src/index.js"
+	};
+	else if (buildTool === "tsdown") scripts = {
+		build: "tsdown",
+		dev: getRunScript(pm, "build", ["--onSuccess", getRunScript(pm, "start")]),
+		watch: getRunScript(pm, "build", ["--watch"]),
+		"watch:start": getRunScript(pm, "build", [
+			"--watch",
+			"--onSuccess",
+			getRunScript(pm, "start")
+		]),
+		start
+	};
+	else scripts = {
+		build: "tsc -b src",
+		dev: `${getRunScript(pm, "build")} && ${getRunScript(pm, "start")}`,
+		watch: "tsc -b src -w",
+		"watch:start": `tsc-watch -b src --onSuccess "${getRunScript(pm, "start")}"`,
+		start
+	};
+	if (ctx.linter === "oxlint") {
+		scripts["lint"] = "oxlint src";
+		scripts["lint:fix"] = "oxlint --fix src";
+	} else if (ctx.linter === "eslint") {
+		scripts["lint"] = "eslint src";
+		scripts["lint:fix"] = "eslint src --fix";
+	}
+	if (ctx.formatter === "oxfmt") {
+		scripts["format"] = "oxfmt --write src";
+		scripts["format:check"] = "oxfmt --check src";
+	} else if (ctx.formatter === "prettier") {
+		scripts["format"] = "prettier --write src";
+		scripts["format:check"] = "prettier --check src";
+	}
+	return scripts;
+}
+function buildDependencies(ctx) {
+	const v = ctx.versions;
+	const dependencies = {
+		"@discordjs/builders": caret(v["@discordjs/builders"]),
+		"@wolfstar/http-framework": caret(v["@wolfstar/http-framework"]),
+		"discord-api-types": caret(v["discord-api-types"])
+	};
+	if (ctx.i18n) dependencies["@wolfstar/http-framework-i18n"] = caret(v["@wolfstar/http-framework-i18n"]);
+	return sortKeys(dependencies);
+}
+function buildDevDependencies(ctx) {
+	const v = ctx.versions;
+	const dev = {};
+	if (ctx.language === "ts") {
+		dev["@types/node"] = caret(v["@types/node"]);
+		switch (ctx.buildTool) {
+			case "tsc6":
+				dev["typescript"] = caret(v["typescript"]);
+				dev["tsc-watch"] = caret(v["tsc-watch"]);
+				break;
+			case "tsc7":
+				dev["typescript"] = v["typescript"];
+				dev["tsc-watch"] = caret(v["tsc-watch"]);
+				break;
+			case "tsdown":
+				dev["tsdown"] = caret(v["tsdown"]);
+				dev["typescript"] = caret(v["typescript"]);
+				break;
+		}
+	}
+	if (ctx.linter === "eslint") {
+		dev["eslint"] = caret(v["eslint"]);
+		if (ctx.language === "ts") dev["typescript-eslint"] = caret(v["typescript-eslint"]);
+		else dev["@eslint/js"] = caret(v["@eslint/js"]);
+	} else if (ctx.linter === "oxlint") dev["oxlint"] = caret(v["oxlint"]);
+	if (ctx.formatter === "prettier") dev["prettier"] = caret(v["prettier"]);
+	else if (ctx.formatter === "oxfmt") dev["oxfmt"] = caret(v["oxfmt"]);
+	return sortKeys(dev);
+}
+function packageJson(ctx) {
+	const devDependencies = buildDevDependencies(ctx);
+	return json({
+		name: ctx.name,
+		version: "1.0.0",
+		description: "A Discord HTTP bot built with `@wolfstar/http-framework`",
+		type: "module",
+		scripts: buildScripts(ctx),
+		dependencies: buildDependencies(ctx),
+		...Object.keys(devDependencies).length > 0 ? { devDependencies } : {},
+		engines: { node: ">=20" }
+	});
+}
+const sharedCompilerOptions = {
+	target: "ES2022",
+	module: "Node16",
+	moduleResolution: "Node16",
+	strict: true,
+	esModuleInterop: true,
+	skipLibCheck: true,
+	declaration: true,
+	declarationMap: true,
+	sourceMap: true,
+	experimentalDecorators: true,
+	emitDecoratorMetadata: true
+};
+/** Writes the tsconfig(s). The tsc branches use a composite build so `tsc -b src` resolves `src/tsconfig.json`. */
+function writeTsconfig(targetDir, ctx) {
+	if (ctx.language === "js") return;
+	if (ctx.buildTool === "tsdown") {
+		writeFile(join(targetDir, "tsconfig.json"), json({
+			compilerOptions: {
+				...sharedCompilerOptions,
+				outDir: "./dist",
+				rootDir: "./src"
+			},
+			include: ["src/**/*.ts"],
+			exclude: ["node_modules", "dist"]
+		}));
+		return;
+	}
+	writeFile(join(targetDir, "tsconfig.json"), json({
+		files: [],
+		references: [{ path: "./src" }]
+	}));
+	writeFile(join(targetDir, "src", "tsconfig.json"), json({
+		compilerOptions: {
+			...sharedCompilerOptions,
+			rootDir: ".",
+			outDir: "../dist",
+			composite: true,
+			tsBuildInfoFile: "../dist/tsconfig.tsbuildinfo"
+		},
+		include: ["**/*.ts"]
+	}));
+}
+function writeBuildConfig(targetDir, ctx) {
+	if (ctx.language === "js" || ctx.buildTool !== "tsdown") return;
+	const content = [
+		"import { defineConfig } from 'tsdown';",
+		"",
+		"export default defineConfig({",
+		"	entry: ['src/**/*.ts'],",
+		"	format: ['esm'],",
+		"	target: 'node20',",
+		"	// Mirror the src/ structure so the framework can load command pieces from dist/commands at runtime.",
+		"	unbundle: true,",
+		"	// Emit dist/index.js so the shared `start` script (node dist/index.js) works.",
+		"	outExtensions: () => ({ js: '.js' }),",
+		"	clean: true,",
+		"	sourcemap: true",
+		"});",
+		""
+	].join("\n");
+	writeFile(join(targetDir, "tsdown.config.ts"), content);
+}
+function writeLinterConfig(targetDir, ctx) {
+	if (ctx.linter === "oxlint") writeFile(join(targetDir, ".oxlintrc.json"), json({
+		$schema: "./node_modules/oxlint/configuration_schema.json",
+		...ctx.language === "ts" ? { plugins: ["typescript"] } : {},
+		categories: {
+			correctness: "error",
+			suspicious: "warn"
+		},
+		ignorePatterns: ["dist/**", "node_modules/**"]
+	}));
+	else if (ctx.linter === "eslint") {
+		const content = ctx.language === "ts" ? [
+			"import tseslint from 'typescript-eslint';",
+			"",
+			"export default tseslint.config(",
+			"	{ ignores: ['dist/**'] },",
+			"	...tseslint.configs.recommended",
+			");",
+			""
+		].join("\n") : [
+			"import js from '@eslint/js';",
+			"",
+			"export default [",
+			"	{ ignores: ['dist/**'] },",
+			"	js.configs.recommended",
+			"];",
+			""
+		].join("\n");
+		writeFile(join(targetDir, "eslint.config.mjs"), content);
+	}
+}
+function writeFormatterConfig(targetDir, ctx) {
+	if (ctx.formatter === "oxfmt") writeFile(join(targetDir, ".oxfmtrc.json"), json({
+		$schema: "./node_modules/oxfmt/configuration_schema.json",
+		useTabs: true,
+		tabWidth: 4,
+		printWidth: 150,
+		singleQuote: true,
+		trailingComma: "none",
+		semi: true,
+		endOfLine: "lf"
+	}));
+	else if (ctx.formatter === "prettier") writeFile(join(targetDir, ".prettierrc.json"), json({
+		useTabs: true,
+		tabWidth: 4,
+		printWidth: 150,
+		singleQuote: true,
+		trailingComma: "none"
+	}));
+}
+/** Generates every config-style file in code so the output is always valid, formatted JSON/TS. */
+function writeProjectFiles(targetDir, ctx) {
+	writeFile(join(targetDir, "package.json"), packageJson(ctx));
+	writeTsconfig(targetDir, ctx);
+	writeBuildConfig(targetDir, ctx);
+	writeLinterConfig(targetDir, ctx);
+	writeFormatterConfig(targetDir, ctx);
 }
 
 //#endregion
 //#region src/tools/templateProcessor.ts
-Handlebars.registerHelper("eq", (a, b) => a === b);
-Handlebars.registerHelper("or", (...args) => args.slice(0, -1).some(Boolean));
-Handlebars.registerHelper("and", (...args) => args.slice(0, -1).every(Boolean));
-const templateDir = join(fileURLToPath(import.meta.url), "../../..", "template");
+const templateDir = join(fileURLToPath(import.meta.url), "../..", "template");
 function walkDir(dir) {
 	const entries = readdirSync(dir);
 	const files = [];
@@ -82,6 +415,8 @@ function processTemplate(outputDir, context) {
 	const allFiles = walkDir(templateDir);
 	for (const absoluteSource of allFiles) {
 		const relativePath = relative(templateDir, absoluteSource);
+		if (context.language === "js" && relativePath.endsWith(".ts.hbs")) continue;
+		if (context.language === "ts" && relativePath.endsWith(".js.hbs")) continue;
 		const rawContent = readFileSync(absoluteSource, "utf-8");
 		const isHandlebars = relativePath.endsWith(".hbs");
 		writeFile(join(outputDir, isHandlebars ? relativePath.slice(0, -4) : relativePath), isHandlebars ? Handlebars.compile(rawContent)(context) : rawContent);
@@ -90,75 +425,352 @@ function processTemplate(outputDir, context) {
 
 //#endregion
 //#region src/index.ts
-const NAME_PATTERN = /^[a-z0-9_-]+$/;
+function isValidPackageName(name) {
+	return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
+}
+function toValidPackageName(name) {
+	return name.trim().toLowerCase().replace(/\s+/g, "-").replace(/^[._]+/, "").replace(/[^a-z0-9-._~]/g, "-");
+}
+function printHelp() {
+	process.stdout.write(`
+Usage: create-http-framework [project-name] [options]
+
+Options:
+  --overwrite                  Overwrite target directory if it already exists
+  --no-interactive             Skip all prompts and use defaults / flags
+  --interactive, -i            Force interactive prompts even when an AI agent is detected
+  --package-manager <pm>       npm | yarn | pnpm | bun (defaults to the detected one)
+  --language <lang>            ts | js (default: ts)
+  --build <tool>               tsc6 | tsc7 | tsdown — TypeScript only (default: tsdown)
+  --lint <linter>              none | eslint | oxlint (default: oxlint)
+  --format <formatter>         none | prettier | oxfmt (default: oxfmt)
+  --port <number>              HTTP port (default: 3000)
+  --i18n / --no-i18n           Toggle @wolfstar/http-framework-i18n (default: off)
+  --install / --no-install     Toggle dependency installation (default: on)
+  --help, -h                   Print this message and exit
+
+`);
+	process.exit(0);
+}
+function parseEnum(value, allowed, label) {
+	if (value === void 0) return void 0;
+	if (!allowed.includes(value)) {
+		cancel(`Invalid ${label} "${value}". Expected one of: ${allowed.join(", ")}.`);
+		process.exit(1);
+	}
+	return value;
+}
 async function main() {
+	const argv = mri(process.argv.slice(2), {
+		boolean: ["overwrite", "help"],
+		string: [
+			"package-manager",
+			"language",
+			"build",
+			"lint",
+			"format",
+			"port"
+		],
+		alias: {
+			h: "help",
+			i: "interactive"
+		},
+		default: { install: true }
+	});
+	if (argv["help"]) {
+		printHelp();
+		return;
+	}
+	const argProjectName = argv._[0];
+	const flagOverwrite = argv["overwrite"];
+	const flagInteractive = argv["interactive"];
+	const cliPackageManager = parseEnum(argv["package-manager"], PACKAGE_MANAGERS, "--package-manager");
+	const cliLanguage = parseEnum(argv["language"], LANGUAGES, "--language");
+	const cliBuild = parseEnum(argv["build"], BUILD_TOOLS, "--build");
+	const cliLint = parseEnum(argv["lint"], LINTERS, "--lint");
+	const cliFormat = parseEnum(argv["format"], FORMATTERS, "--format");
+	const cliPort = argv["port"];
+	const cliI18n = argv["i18n"];
+	const cliInstall = argv["install"];
+	const { isAgent, agent } = await determineAgent();
+	const agentMode = isAgent && flagInteractive !== true;
+	const nonInteractive = flagInteractive === false || agentMode;
 	intro("Welcome to the WolfStar HTTP Framework!");
-	const packageManager = await detectPackageManager();
-	const projectNameArg = process.argv[2];
-	const projectName = await text({
-		message: "What is the name of your project?",
-		placeholder: "my-discord-bot",
-		initialValue: projectNameArg ?? "",
-		validate(value) {
-			if (!value) return "Project name cannot be empty.";
-			if (!NAME_PATTERN.test(value)) return "Use only lowercase letters, numbers, dashes, and underscores.";
-			if (directoryExists(resolve(value))) return `Directory "${value}" already exists.`;
+	if (agentMode && flagInteractive !== false) log.info(`AI agent detected (${agent.name}) — running in non-interactive mode`);
+	const detectedPackageManager = await detectPackageManager();
+	let projectName;
+	if (nonInteractive) {
+		if (!argProjectName) {
+			cancel("A project name argument is required in non-interactive mode.");
+			process.exit(1);
 		}
-	});
-	if (isCancel(projectName)) {
-		cancel("Operation cancelled.");
-		process.exit(0);
-	}
-	const portInput = await text({
-		message: "Which port should the HTTP server listen on?",
-		placeholder: "3000",
-		initialValue: "3000",
-		validate(value) {
-			const n = Number(value);
-			if (!value || Number.isNaN(n) || !Number.isInteger(n) || n < 1 || n > 65535) return "Enter a valid port number (1–65535).";
+		const normalized = isValidPackageName(argProjectName) ? argProjectName : toValidPackageName(argProjectName);
+		if (!normalized || !isValidPackageName(normalized)) {
+			cancel("Provide a valid npm-compatible project name in non-interactive mode.");
+			process.exit(1);
 		}
-	});
-	if (isCancel(portInput)) {
-		cancel("Operation cancelled.");
-		process.exit(0);
+		projectName = normalized;
+	} else {
+		const suggested = argProjectName ? toValidPackageName(argProjectName) : "";
+		const nameResult = await text({
+			message: "What is the name of your project?",
+			placeholder: "my-discord-bot",
+			initialValue: argProjectName && isValidPackageName(argProjectName) ? argProjectName : suggested,
+			validate(value) {
+				if (!value) return "Project name cannot be empty.";
+				if (!isValidPackageName(value)) return "Use lowercase letters, numbers, dashes, dots, or underscores (npm-compatible).";
+			}
+		});
+		if (isCancel(nameResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		projectName = nameResult;
 	}
-	const wantsI18n = await confirm({
-		message: "Would you like to add i18n support? (@wolfstar/http-framework-i18n)",
-		initialValue: false
-	});
-	if (isCancel(wantsI18n)) {
-		cancel("Operation cancelled.");
-		process.exit(0);
+	let packageManager;
+	if (nonInteractive) packageManager = cliPackageManager ?? detectedPackageManager;
+	else {
+		const pmResult = await select({
+			message: "Which package manager would you like to use?",
+			options: PACKAGE_MANAGERS.map((pm) => ({
+				value: pm,
+				label: pm
+			})),
+			initialValue: PACKAGE_MANAGERS.includes(detectedPackageManager) ? detectedPackageManager : "npm"
+		});
+		if (isCancel(pmResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		packageManager = pmResult;
 	}
-	const wantsInstall = await confirm({
-		message: `Would you like to automatically install dependencies with ${packageManager}?`,
-		initialValue: true
-	});
-	if (isCancel(wantsInstall)) {
-		cancel("Operation cancelled.");
-		process.exit(0);
+	const targetDir = resolve(projectName);
+	if (directoryExists(targetDir) && !isEmpty(targetDir)) if (flagOverwrite) emptyDir(targetDir);
+	else if (nonInteractive) {
+		cancel(`"${projectName}" already exists. Use --overwrite to overwrite it.`);
+		process.exit(1);
+	} else {
+		const choice = await select({
+			message: `"${projectName}" already exists. What would you like to do?`,
+			options: [{
+				value: "overwrite",
+				label: "Overwrite the directory"
+			}, {
+				value: "cancel",
+				label: "Cancel"
+			}]
+		});
+		if (isCancel(choice) || choice === "cancel") {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		emptyDir(targetDir);
+	}
+	let port;
+	if (nonInteractive) {
+		port = cliPort === void 0 ? 3e3 : Number(cliPort);
+		if (!Number.isInteger(port) || port < 1 || port > 65535) {
+			cancel("Provide a valid --port between 1 and 65535.");
+			process.exit(1);
+		}
+	} else {
+		const portResult = await text({
+			message: "Which port should the HTTP server listen on?",
+			placeholder: "3000",
+			initialValue: "3000",
+			validate(value) {
+				const n = Number(value);
+				if (!value || Number.isNaN(n) || !Number.isInteger(n) || n < 1 || n > 65535) return "Enter a valid port number (1–65535).";
+			}
+		});
+		if (isCancel(portResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		port = Number(portResult);
+	}
+	let language;
+	if (nonInteractive) language = cliLanguage ?? "ts";
+	else {
+		const languageResult = await select({
+			message: "Which language would you like to use?",
+			options: [{
+				value: "ts",
+				label: "TypeScript"
+			}, {
+				value: "js",
+				label: "JavaScript"
+			}],
+			initialValue: "ts"
+		});
+		if (isCancel(languageResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		language = languageResult;
+	}
+	let buildTool = "tsdown";
+	if (cliBuild !== void 0 && language === "js") log.warn("--build only applies to TypeScript projects and will be ignored.");
+	if (language === "ts") if (nonInteractive) buildTool = cliBuild ?? "tsdown";
+	else {
+		const buildResult = await select({
+			message: "Which build tool would you like to use?",
+			options: [
+				{
+					value: "tsdown",
+					label: "tsdown (bundler)"
+				},
+				{
+					value: "tsc6",
+					label: "TypeScript 6.0 (tsc)"
+				},
+				{
+					value: "tsc7",
+					label: "TypeScript 7.0 rc (tsc)"
+				}
+			],
+			initialValue: "tsdown"
+		});
+		if (isCancel(buildResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		buildTool = buildResult;
+	}
+	let linter;
+	if (nonInteractive) linter = cliLint ?? "oxlint";
+	else {
+		const lintResult = await select({
+			message: "Which linter would you like to use?",
+			options: [
+				{
+					value: "oxlint",
+					label: "oxlint"
+				},
+				{
+					value: "eslint",
+					label: "ESLint"
+				},
+				{
+					value: "none",
+					label: "None"
+				}
+			],
+			initialValue: "oxlint"
+		});
+		if (isCancel(lintResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		linter = lintResult;
+	}
+	let formatter;
+	if (nonInteractive) formatter = cliFormat ?? "oxfmt";
+	else {
+		const formatResult = await select({
+			message: "Which formatter would you like to use?",
+			options: [
+				{
+					value: "oxfmt",
+					label: "oxfmt"
+				},
+				{
+					value: "prettier",
+					label: "Prettier"
+				},
+				{
+					value: "none",
+					label: "None"
+				}
+			],
+			initialValue: "oxfmt"
+		});
+		if (isCancel(formatResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		formatter = formatResult;
+	}
+	let wantsI18n;
+	if (nonInteractive) wantsI18n = cliI18n ?? false;
+	else {
+		const i18nResult = await confirm({
+			message: "Would you like to add i18n support? (@wolfstar/http-framework-i18n)",
+			initialValue: false
+		});
+		if (isCancel(i18nResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		wantsI18n = Boolean(i18nResult);
+	}
+	let wantsInstall;
+	if (nonInteractive) wantsInstall = cliInstall;
+	else {
+		const installResult = await confirm({
+			message: `Would you like to automatically install dependencies with ${packageManager}?`,
+			initialValue: true
+		});
+		if (isCancel(installResult)) {
+			cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		wantsInstall = Boolean(installResult);
 	}
 	const s = spinner();
 	s.start("Fetching latest dependency versions...");
-	const versions = fetchDependencyVersions();
+	const versions = await fetchDependencyVersions({
+		i18n: wantsI18n,
+		language,
+		buildTool,
+		linter,
+		formatter
+	});
 	s.stop("Versions fetched.");
 	s.start("Generating project files...");
-	const outputDir = join(process.cwd(), projectName);
-	processTemplate(outputDir, {
+	processTemplate(targetDir, {
+		name: projectName,
+		port,
+		language
+	});
+	writeProjectFiles(targetDir, {
 		name: projectName,
-		port: Number(portInput),
-		i18n: Boolean(wantsI18n),
+		port,
+		i18n: wantsI18n,
 		packageManager,
-		todaysDate: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+		language,
+		buildTool,
+		linter,
+		formatter,
 		versions
 	});
 	s.stop("Project files generated.");
+	if (formatter !== "none") try {
+		s.start("Formatting project files...");
+		if (formatter === "oxfmt") runCommand("npx", [
+			"--yes",
+			"oxfmt",
+			"--write",
+			"."
+		], targetDir);
+		else runCommand("npx", [
+			"--yes",
+			"prettier",
+			"--write",
+			".",
+			"--log-level",
+			"warn"
+		], targetDir);
+		s.stop("Project files formatted.");
+	} catch {
+		s.stop("Skipped formatting (formatter not available yet — it will run after install).");
+	}
 	if (wantsInstall) {
 		s.start(`Installing dependencies with ${packageManager}...`);
-		await detectPackageManager(outputDir);
+		await installDependencies(packageManager, targetDir);
 		s.stop("Dependencies installed.");
 	}
-	outro(`Done! To get started:\n\n  cd ${projectName}\n${wantsInstall ? "" : `  ${packageManager} install\n`}  ${packageManager} run dev`);
+	outro(`Done! To get started:\n\n  cd ${projectName}\n${wantsInstall ? "" : `  ${getInstallScript(packageManager)}\n`}  ${getRunScript(packageManager, "dev")}`);
 }
 main().catch((error) => {
 	cancel(error instanceof Error ? error.message : String(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolfstar/create-http-framework",
-  "version": "1.0.1",
+  "version": "2.1.0",
   "description": "Create a new WolfStar HTTP Framework bot project",
   "keywords": [
     "cli",
@@ -33,12 +33,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^1.6.0",
+    "@clack/prompts": "^1.7.0",
+    "@vercel/detect-agent": "^1.2.3",
+    "cross-spawn": "^7.0.6",
     "handlebars": "^4.7.9",
-    "package-manager-detector": "^1.6.0"
+    "mri": "^1.2.0",
+    "package-manager-detector": "^1.7.0"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/handlebars": "^4.1.0",
+    "@types/mri": "^1.2.0",
     "@types/node": "22.15.21",
     "tsdown": "^0.22.3",
     "typescript": "~5.8.3"

package/template/.env.hbs

@@ -1 +1,4 @@
-DISCORD_TOKEN=your_bot_token_here DISCORD_PUBLIC_KEY=your_public_key_here DISCORD_CLIENT_ID=your_client_id_here HTTP_POST_PATH=/
+DISCORD_TOKEN=your_bot_token_here
+DISCORD_PUBLIC_KEY=your_public_key_here
+DISCORD_CLIENT_ID=your_client_id_here
+HTTP_POST_PATH=/

package/template/.gitignore.hbs

@@ -1 +1,4 @@
-node_modules/ dist/ .env *.js.map
+node_modules/
+dist/
+.env
+*.js.map

package/template/src/commands/ping.js.hbs

@@ -0,0 +1,12 @@
+import { Command } from '@wolfstar/http-framework';
+import { MessageFlags } from 'discord-api-types/v10';
+
+export class PingCommand extends Command {
+	chatInputRun(interaction) {
+		return interaction.reply({ content: 'Pong!', flags: MessageFlags.Ephemeral });
+	}
+
+	static builder = (builder) => builder
+		.setName('ping')
+		.setDescription('Replies with pong!')
+}

package/template/src/commands/ping.ts.hbs

@@ -1,5 +1,13 @@
-import { Command } from '@wolfstar/http-framework'; import { SlashCommandBuilder } from '@discordjs/builders'; import { MessageFlags } from
-'discord-api-types/v10'; export class PingCommand extends Command { public constructor(context: Command.LoaderContext) { super(context, { name:
-'ping', description: 'Replies with pong!' }); } public override chatInputRun(interaction: Command.ChatInputInteraction) { return interaction.reply({
-content: 'Pong!', flags: MessageFlags.Ephemeral }); } public static readonly builder = new SlashCommandBuilder() .setName('ping')
-.setDescription('Replies with pong!'); }
+import { Command, RegisterCommand } from '@wolfstar/http-framework';
+import { MessageFlags } from 'discord-api-types/v10';
+
+@RegisterCommand((builder) =>
+	builder //
+		.setName('ping')
+		.setDescription('Replies with pong!')
+)
+export class PingCommand extends Command {
+	public override chatInputRun(interaction: Command.ChatInputInteraction) {
+		return interaction.reply({ content: 'Pong!', flags: MessageFlags.Ephemeral });
+	}
+}

package/template/src/index.js.hbs

@@ -0,0 +1,10 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@wolfstar/http-framework';
+
+const client = new Client();
+
+await client.load({ baseUserDirectory: join(dirname(fileURLToPath(import.meta.url)), 'commands') });
+await client.listen({ port: {{port}} });
+
+console.log('Bot is running on port {{port}}');

package/template/src/index.ts.hbs

@@ -1,5 +1,10 @@
-import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { Client } from '@wolfstar/http-framework'; const client =
-new Client(); await client.load({ baseUserDirectory: join(dirname(fileURLToPath(import.meta.url)), 'commands') }); await client.listen({ port:
-{{port}}
-}); console.log('Bot is running on port
-{{port}}');
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@wolfstar/http-framework';
+
+const client = new Client();
+
+await client.load({ baseUserDirectory: join(dirname(fileURLToPath(import.meta.url)), 'commands') });
+await client.listen({ port: {{port}} });
+
+console.log('Bot is running on port {{port}}');

package/template/package.json.hbs

@@ -1,7 +0,0 @@
-{ "name": "{{name}}", "version": "1.0.0", "description": "A Discord HTTP bot built with `@wolfstar/http-framework`", "author": "`@wolfstar`",
-"repository": { "url": "https://github.com/yourusername/your-repo.git" }, "bugs": { "url": "https://github.com/yourusername/your-repo/issues" },
-"homepage": "https://github.com/yourusername/your-repo#readme", "keywords": ["discord", "bot", "http", "wolfstar"], "type": "module", "scripts": {
-"build": "tsc", "dev": "node --watch --loader ts-node/esm src/index.ts", "start": "node dist/index.js" }, "dependencies": { "@discordjs/builders": "^{{versions.discordJsBuilders}}",
-"@wolfstar/http-framework": "^{{versions.httpFramework}}"{{#if i18n}}, "@wolfstar/http-framework-i18n": "^{{versions.httpFrameworkI18n}}"{{/if}},
-"discord-api-types": "^{{versions.discordApiTypes}}" }, "devDependencies": { "@types/node": "^{{versions.typesNode}}", "ts-node": "^{{versions.tsNode}}",
-"typescript": "^{{versions.typescript}}" }, "engines": { "node": ">=20" } }

package/template/tsconfig.json.hbs

@@ -1,3 +0,0 @@
-{ "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "outDir": "./dist", "rootDir": "./src", "strict": true,
-"esModuleInterop": true, "skipLibCheck": true, "declaration": true, "declarationMap": true, "sourceMap": true, "experimentalDecorators": true,
-"emitDecoratorMetadata": true }, "include": ["src/**/*.ts"], "exclude": ["node_modules", "dist"] }