@wolfstar/create-http-framework 2.1.4-next-20260827143053 → 2.2.0-next-20260831114920

package/README.md

@@ -22,25 +22,30 @@ The CLI will guide you through the following prompts:
 - **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`
+- **Optional features** (multiselect) —
+    - **i18n** — add [`@wolfstar/plugin-i18next`](https://github.com/wolfstar-project/stars-components/tree/main/packages/plugin-i18next)
+    - **Subcommands** — add an example command that uses subcommands
+    - **Testing** — set up Vitest with [`@wolfstar/http-framework-test-utils`](https://github.com/wolfstar-project/stars-components/tree/main/packages/http-framework-test-utils)
 - **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                                        |
+| 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 `@wolfstar/plugin-i18next` scaffolding                   |
+| `--subcommands` / `--no-subcommands` |       | Enable or disable the example subcommand command                           |
+| `--testing` / `--no-testing`         |       | Enable or disable the Vitest + `@wolfstar/http-framework-test-utils` setup |
+| `--install` / `--no-install`         |       | Enable or disable dependency installation                                  |
+| `--help`                             | `-h`  | Print usage and exit                                                       |
 
 ## Non-interactive / AI agent mode
 
@@ -56,14 +61,47 @@ create-http-framework my-discord-bot --no-interactive
 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)
+│   │   ├── ping.ts               # Example ping command
+│   │   └── math.ts               # Example command with subcommands (--subcommands)
+│   ├── lib/
+│   │   ├── setup/
+│   │   │   ├── all.ts            # Aggregates setup imports
+│   │   │   └── logger.ts         # Logger configuration
+│   │   └── types/
+│   │       └── augments.ts       # Module augmentations (TypeScript only)
+│   ├── locales/
+│   │   └── en-US/
+│   │       └── commands/
+│   │           └── ping.json     # Example locale resource (--i18n)
+│   ├── @types/
+│   │   └── i18next.d.ts          # Generated i18next augmentation (--i18n)
+│   └── main.ts                   # Entry point — starts the HTTP server
+├── tests/
+│   └── ping.test.ts              # Example test (--testing)
+├── vitest.config.ts              # Vitest configuration (--testing)
+├── vitest.setup.ts               # Vitest setup file (--testing)
+├── README.md                     # Generated project README
+├── .env                          # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
 ├── .gitignore
 ├── package.json
 └── tsconfig.json
 ```
 
+- `src/locales/en-US/commands/ping.json` and `src/@types/i18next.d.ts` are only generated when **i18n** is enabled.
+- `src/@types/i18next.d.ts` is produced by `@wolfstar/i18next-type-generator`; the CLI runs it automatically at the end of scaffolding, and it can be re-run any time locale files change (see [`generate:i18n`](#i18n-type-generation) below).
+- `src/commands/math.ts` is only generated when **Subcommands** is enabled.
+- `tests/ping.test.ts`, `vitest.config.ts`, and `vitest.setup.ts` are only generated when **Testing** is enabled.
+
+### i18n type generation
+
+When i18n is enabled, the generated `package.json` includes a `generate:i18n` script that (re)generates `src/@types/i18next.d.ts` from the JSON files under `src/locales/`:
+
+```bash
+pnpm generate:i18n
+```
+
+The CLI runs this script automatically once at the end of scaffolding; re-run it manually whenever you add or edit locale keys so the generated types stay in sync.
+
 ## Requirements
 
 - Node.js `>=20`

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, log, multiselect, 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";
@@ -79,10 +79,15 @@ async function fetchVersion(packageName) {
 async function fetchDependencyVersions(selections) {
 	const names = /* @__PURE__ */ new Set([
 		"@wolfstar/http-framework",
+		"@sapphire/pieces",
 		"discord-api-types",
-		"@discordjs/builders"
+		"@wolfstar/env-utilities",
+		"@wolfstar/logger",
+		"@wolfstar/start-banner",
+		"gradient-string"
 	]);
-	if (selections.i18n) names.add("@wolfstar/http-framework-i18n");
+	if (selections.i18n) names.add("@wolfstar/plugin-i18next").add("@wolfstar/i18next-type-generator");
+	if (selections.testing) names.add("vitest").add("@wolfstar/http-framework-test-utils");
 	if (selections.language === "ts") {
 		names.add("@types/node");
 		switch (selections.buildTool) {
@@ -182,11 +187,11 @@ function json(value) {
 }
 function buildScripts(ctx) {
 	const { packageManager: pm, buildTool } = ctx;
-	const start = "node dist/index.js";
+	const start = "node dist/main.js";
 	let scripts;
 	if (ctx.language === "js") scripts = {
-		start: "node src/index.js",
-		dev: "node --watch src/index.js"
+		start: "node src/main.js",
+		dev: "node --watch src/main.js"
 	};
 	else if (buildTool === "tsdown") scripts = {
 		build: "tsdown",
@@ -220,16 +225,22 @@ function buildScripts(ctx) {
 		scripts["format"] = "prettier --write src";
 		scripts["format:check"] = "prettier --check src";
 	}
+	if (ctx.i18n) scripts["generate:i18n"] = "i18next-type-generator ./src/locales/en-US/ ./src/@types/i18next.d.ts";
+	if (ctx.testing) scripts["test"] = "vitest run";
 	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"])
+		"@sapphire/pieces": caret(v["@sapphire/pieces"]),
+		"discord-api-types": caret(v["discord-api-types"]),
+		"@wolfstar/env-utilities": caret(v["@wolfstar/env-utilities"]),
+		"@wolfstar/logger": caret(v["@wolfstar/logger"]),
+		"@wolfstar/start-banner": caret(v["@wolfstar/start-banner"]),
+		"gradient-string": caret(v["gradient-string"])
 	};
-	if (ctx.i18n) dependencies["@wolfstar/http-framework-i18n"] = caret(v["@wolfstar/http-framework-i18n"]);
+	if (ctx.i18n) dependencies["@wolfstar/plugin-i18next"] = caret(v["@wolfstar/plugin-i18next"]);
 	return sortKeys(dependencies);
 }
 function buildDevDependencies(ctx) {
@@ -258,11 +269,16 @@ function buildDevDependencies(ctx) {
 	} 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"]);
+	if (ctx.i18n) dev["@wolfstar/i18next-type-generator"] = caret(v["@wolfstar/i18next-type-generator"]);
+	if (ctx.testing) {
+		dev["vitest"] = caret(v["vitest"]);
+		dev["@wolfstar/http-framework-test-utils"] = caret(v["@wolfstar/http-framework-test-utils"]);
+	}
 	return sortKeys(dev);
 }
 function packageJson(ctx) {
 	const devDependencies = buildDevDependencies(ctx);
-	const main = ctx.language === "js" ? "src/index.js" : "dist/index.js";
+	const main = ctx.language === "js" ? "src/main.js" : "dist/main.js";
 	return json({
 		name: ctx.name,
 		version: "1.0.0",
@@ -329,7 +345,7 @@ function writeBuildConfig(targetDir, ctx) {
 		"	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.",
+		"	// Emit dist/main.js so the shared `start` script (node dist/main.js) works.",
 		"	outExtensions: () => ({ js: '.js' }),",
 		"	clean: true,",
 		"	sourcemap: true",
@@ -400,6 +416,8 @@ function writeProjectFiles(targetDir, ctx) {
 //#endregion
 //#region src/tools/templateProcessor.ts
 const templateDir = join(fileURLToPath(import.meta.url), "../..", "template");
+const baseDir = join(templateDir, "base");
+const featuresDir = join(templateDir, "features");
 function walkDir(dir) {
 	const entries = readdirSync(dir);
 	const files = [];
@@ -410,20 +428,123 @@ function walkDir(dir) {
 	}
 	return files;
 }
-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;
+/**
+* Resolves which `template/features/*` directories should be layered on top of `template/base/`,
+* in application order. Later entries overwrite earlier ones (and `base/`) on path collisions.
+*/
+function resolveFeatureDirs(ctx) {
+	const dirs = [];
+	if (ctx.i18n) dirs.push("i18n");
+	if (ctx.subcommandsAdvanced) dirs.push(ctx.i18n ? "subcommands-advanced-i18n" : "subcommands-advanced");
+	else if (ctx.subcommands) dirs.push(ctx.i18n ? "subcommands-i18n" : "subcommands");
+	if (ctx.testing) {
+		dirs.push("testing");
+		if (ctx.i18n) dirs.push("testing-i18n");
+	}
+	return dirs;
+}
+/** The output-relative path a source file under a template root resolves to for the given language, or `null` if the file doesn't apply to that language. */
+function toOutputRelative(root, absoluteSource, language) {
+	const relativePath = relative(root, absoluteSource);
+	if (language === "js" && relativePath.endsWith(".ts.hbs")) return null;
+	if (language === "ts" && relativePath.endsWith(".js.hbs")) return null;
+	return relativePath.endsWith(".hbs") ? relativePath.slice(0, -4) : relativePath;
+}
+/** The set of output-relative paths that writing `root` for `language` would produce. */
+function collectOutputPaths(root, language) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const absoluteSource of walkDir(root)) {
+		const outputRelative = toOutputRelative(root, absoluteSource, language);
+		if (outputRelative !== null) paths.add(outputRelative);
+	}
+	return paths;
+}
+function renderSource(absoluteSource, context) {
+	const rawContent = readFileSync(absoluteSource, "utf-8");
+	return absoluteSource.endsWith(".hbs") ? Handlebars.compile(rawContent)(context) : rawContent;
+}
+/**
+* Maps every output-relative path `root` could ever produce — for either language — to the source
+* file(s) that render it. Unlike {@link collectOutputPaths} this ignores `context.language`, so it
+* also surfaces paths left behind by a previous run under the *other* language (e.g. `src/main.ts`
+* after rerunning with `--language js`).
+*/
+function collectCandidateSources(root) {
+	const candidates = /* @__PURE__ */ new Map();
+	for (const absoluteSource of walkDir(root)) {
+		const relativePath = relative(root, absoluteSource);
+		const outputRelative = relativePath.endsWith(".hbs") ? relativePath.slice(0, -4) : relativePath;
+		const sources = candidates.get(outputRelative);
+		if (sources) sources.push(absoluteSource);
+		else candidates.set(outputRelative, [absoluteSource]);
+	}
+	return candidates;
+}
+/**
+* When re-running against a non-empty `outputDir` (`--ignore`), files written by a previous run
+* survive even after the feature that produced them is disabled, or the project's language is
+* switched — `processTemplate` only ever (re)writes the paths the *current* selections produce, it
+* never deletes. Left behind, those files can keep importing packages that `writeProjectFiles` just
+* dropped from `package.json` (e.g. `@wolfstar/plugin-i18next`), breaking install/build.
+*
+* Deletes any known generator output path that isn't produced by `base/` or an active feature this
+* run, but only when the file on disk still matches byte-for-byte what the generator would have
+* written for it — i.e. it wasn't hand-edited since. Hand-edited files are left in place (and their
+* paths returned) so the caller can warn instead of silently discarding user work.
+*/
+function removeStaleGeneratedFiles(outputDir, context) {
+	const keepPaths = collectOutputPaths(baseDir, context.language);
+	for (const feature of resolveFeatureDirs(context)) for (const path of collectOutputPaths(join(featuresDir, feature), context.language)) keepPaths.add(path);
+	const candidates = collectCandidateSources(baseDir);
+	for (const feature of readdirSync(featuresDir)) for (const [path, sources] of collectCandidateSources(join(featuresDir, feature))) {
+		const existing = candidates.get(path);
+		if (existing) existing.push(...sources);
+		else candidates.set(path, sources);
+	}
+	const preserved = [];
+	for (const [path, sources] of candidates) {
+		if (keepPaths.has(path)) continue;
+		const target = join(outputDir, path);
+		if (!existsSync(target)) continue;
+		const actual = readFileSync(target, "utf-8");
+		if (sources.some((source) => renderSource(source, context) === actual)) rmSync(target);
+		else preserved.push(path);
+	}
+	return preserved;
+}
+/**
+* Walks `root` and writes every file into `outputDir`, preserving the relative path.
+*
+* - `*.ts.hbs` / `*.js.hbs` files are skipped unless they match `context.language`.
+* - Other `*.hbs` files (e.g. `.env.hbs`, `.gitignore.hbs`, `README.md.hbs`) are compiled unconditionally.
+* - Non-`.hbs` files (e.g. static locale JSON under a feature's `src/locales/**`) are copied verbatim —
+*   no extension stripped, no Handlebars compilation.
+*/
+function processDir(root, outputDir, context) {
+	for (const absoluteSource of walkDir(root)) {
+		const outputRelative = toOutputRelative(root, absoluteSource, context.language);
+		if (outputRelative === null) continue;
 		const rawContent = readFileSync(absoluteSource, "utf-8");
-		const isHandlebars = relativePath.endsWith(".hbs");
-		const outputRelative = isHandlebars ? relativePath.slice(0, -4) : relativePath;
+		const isHandlebars = absoluteSource.endsWith(".hbs");
 		const outputPath = join(outputDir, outputRelative);
 		const content = isHandlebars ? Handlebars.compile(rawContent)(context) : rawContent;
 		writeFile(outputPath, content);
 	}
 }
+/**
+* Renders `template/base/` into `outputDir`, then layers the feature directories resolved by
+* {@link resolveFeatureDirs} on top, in order — feature files overwrite base files at the same
+* output-relative path (e.g. `features/i18n/src/main.ts.hbs` overwrites `base/src/main.ts.hbs`).
+*
+* @returns Output-relative paths that looked stale (belong to a disabled feature or the other
+* language) but were left in place because they'd been hand-edited since the last run.
+*/
+async function processTemplate(outputDir, context) {
+	const preserved = removeStaleGeneratedFiles(outputDir, context);
+	processDir(baseDir, outputDir, context);
+	for (const feature of resolveFeatureDirs(context)) processDir(join(featuresDir, feature), outputDir, context);
+	return preserved;
+}
 
 //#endregion
 //#region src/index.ts
@@ -447,8 +568,12 @@ Options:
   --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)
+  --i18n / --no-i18n           Toggle @wolfstar/plugin-i18next (default: off)
+  --subcommands / --no-subcommands  Toggle the subcommands example command (default: off)
+  --subcommands-advanced / --no-subcommands-advanced  Toggle the subcommand groups example command (default: off; overrides --subcommands)
+  --testing / --no-testing     Toggle the testing setup (vitest) (default: off)
   --install / --no-install     Toggle dependency installation (default: on)
+  --ignore                     Write into an existing, non-empty directory without clearing it
   --help, -h                   Print this message and exit
 
 `);
@@ -464,7 +589,11 @@ function parseEnum(value, allowed, label) {
 }
 async function main() {
 	const argv = mri(process.argv.slice(2), {
-		boolean: ["overwrite", "help"],
+		boolean: [
+			"overwrite",
+			"ignore",
+			"help"
+		],
 		string: [
 			"package-manager",
 			"language",
@@ -485,6 +614,7 @@ async function main() {
 	}
 	const argProjectName = argv._[0];
 	const flagOverwrite = argv["overwrite"];
+	const flagIgnore = argv["ignore"];
 	const flagInteractive = argv["interactive"];
 	const cliPackageManager = parseEnum(argv["package-manager"], PACKAGE_MANAGERS, "--package-manager");
 	const cliLanguage = parseEnum(argv["language"], LANGUAGES, "--language");
@@ -493,6 +623,9 @@ async function main() {
 	const cliFormat = parseEnum(argv["format"], FORMATTERS, "--format");
 	const cliPort = argv["port"];
 	const cliI18n = argv["i18n"];
+	const cliSubcommands = argv["subcommands"];
+	const cliSubcommandsAdvanced = argv["subcommands-advanced"];
+	const cliTesting = argv["testing"];
 	const cliInstall = argv["install"];
 	const { isAgent, agent } = await determineAgent();
 	const agentMode = isAgent && flagInteractive !== true;
@@ -549,25 +682,32 @@ async function main() {
 	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.`);
+		else if (flagIgnore) {} else if (nonInteractive) {
+			cancel(`"${projectName}" already exists. Use --overwrite to overwrite it, or --ignore to write into it without clearing it first.`);
 			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"
-				}]
+				options: [
+					{
+						value: "overwrite",
+						label: "Overwrite the directory (empties it first)"
+					},
+					{
+						value: "ignore",
+						label: "Write into it without clearing existing files"
+					},
+					{
+						value: "cancel",
+						label: "Cancel"
+					}
+				]
 			});
 			if (isCancel(choice) || choice === "cancel") {
 				cancel("Operation cancelled.");
 				process.exit(0);
 			}
-			emptyDir(targetDir);
+			if (choice === "overwrite") emptyDir(targetDir);
 		}
 	}
 	let port;
@@ -698,17 +838,51 @@ async function main() {
 		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
+	let wantsSubcommands;
+	let wantsSubcommandsAdvanced;
+	let wantsTesting;
+	if (nonInteractive) {
+		wantsI18n = cliI18n ?? false;
+		wantsSubcommands = cliSubcommands ?? false;
+		wantsSubcommandsAdvanced = cliSubcommandsAdvanced ?? false;
+		wantsTesting = cliTesting ?? false;
+	} else {
+		const featuresResult = await multiselect({
+			message: "Which optional features would you like to add?",
+			options: [
+				{
+					value: "i18n",
+					label: "i18n support (@wolfstar/plugin-i18next)"
+				},
+				{
+					value: "subcommands",
+					label: "Subcommands example command"
+				},
+				{
+					value: "subcommands-advanced",
+					label: "Subcommands example command (with groups)"
+				},
+				{
+					value: "testing",
+					label: "Testing setup (vitest)"
+				}
+			],
+			initialValues: [],
+			required: false
 		});
-		if (isCancel(i18nResult)) {
+		if (isCancel(featuresResult)) {
 			cancel("Operation cancelled.");
 			process.exit(0);
 		}
-		wantsI18n = Boolean(i18nResult);
+		const features = new Set(featuresResult);
+		wantsI18n = features.has("i18n");
+		wantsSubcommands = features.has("subcommands");
+		wantsSubcommandsAdvanced = features.has("subcommands-advanced");
+		wantsTesting = features.has("testing");
+	}
+	if (wantsSubcommands && wantsSubcommandsAdvanced) {
+		log.warn("Both --subcommands and --subcommands-advanced were selected; using the advanced example (with groups).");
+		wantsSubcommands = false;
 	}
 	let wantsInstall;
 	if (nonInteractive) wantsInstall = cliInstall;
@@ -727,6 +901,9 @@ async function main() {
 	s.start("Fetching latest dependency versions...");
 	const versions = await fetchDependencyVersions({
 		i18n: wantsI18n,
+		subcommands: wantsSubcommands,
+		subcommandsAdvanced: wantsSubcommandsAdvanced,
+		testing: wantsTesting,
 		language,
 		buildTool,
 		linter,
@@ -734,15 +911,22 @@ async function main() {
 	});
 	s.stop("Versions fetched.");
 	s.start("Generating project files...");
-	processTemplate(targetDir, {
+	const preservedFiles = await processTemplate(targetDir, {
 		name: projectName,
 		port,
-		language
+		language,
+		i18n: wantsI18n,
+		subcommands: wantsSubcommands,
+		subcommandsAdvanced: wantsSubcommandsAdvanced,
+		testing: wantsTesting
 	});
 	writeProjectFiles(targetDir, {
 		name: projectName,
 		port,
 		i18n: wantsI18n,
+		subcommands: wantsSubcommands,
+		subcommandsAdvanced: wantsSubcommandsAdvanced,
+		testing: wantsTesting,
 		packageManager,
 		language,
 		buildTool,
@@ -751,6 +935,19 @@ async function main() {
 		versions
 	});
 	s.stop("Project files generated.");
+	for (const file of preservedFiles) log.warn(`Kept hand-edited "${file}" even though its feature is now disabled — remove it manually if it's no longer needed.`);
+	if (wantsI18n) try {
+		s.start("Generating i18n types...");
+		runCommand("npx", [
+			"--yes",
+			"@wolfstar/i18next-type-generator",
+			"./src/locales/en-US",
+			"./src/@types/i18next.d.ts"
+		], targetDir);
+		s.stop("i18n types generated.");
+	} catch {
+		s.stop("Skipped i18n type generation (run it manually once dependencies are installed).");
+	}
 	if (formatter !== "none") try {
 		s.start("Formatting project files...");
 		if (formatter === "oxfmt") runCommand("npx", [
@@ -776,7 +973,10 @@ async function main() {
 		await installDependencies(packageManager, targetDir);
 		s.stop("Dependencies installed.");
 	}
-	outro(`Done! To get started:\n\n  cd ${projectName}\n${wantsInstall ? "" : `  ${getInstallScript(packageManager)}\n`}  ${getRunScript(packageManager, "dev")}`);
+	const extraNotes = [];
+	if (wantsI18n) extraNotes.push(`  After editing locale files, regenerate i18next types with: ${getRunScript(packageManager, "generate:i18n")}`);
+	if (wantsTesting) extraNotes.push(`  Run the test suite with: ${getRunScript(packageManager, "test")}`);
+	outro(`Done! To get started:\n\n  cd ${projectName}\n${wantsInstall ? "" : `  ${getInstallScript(packageManager)}\n`}  ${getRunScript(packageManager, "dev")}${extraNotes.length ? `\n\n${extraNotes.join("\n")}` : ""}`);
 }
 main().catch((error) => {
 	cancel(error instanceof Error ? error.message : String(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolfstar/create-http-framework",
-  "version": "2.1.4-next-20260827143053",
+  "version": "2.2.0-next-20260831114920",
   "description": "Create a new WolfStar HTTP Framework bot project",
   "keywords": [
     "cli",
@@ -46,13 +46,16 @@
     "@types/handlebars": "^4.1.0",
     "@types/mri": "^1.2.0",
     "@types/node": "22.15.21",
+    "@vitest/coverage-v8": "^4.1.8",
     "tsdown": "^0.22.14",
-    "typescript": "~5.8.3"
+    "typescript": "~5.8.3",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
+    "test": "vitest run",
     "build": "tsdown --config-loader unrun",
     "typecheck": "tsc -p ../../tsconfig.json",
     "lint": "oxlint src --fix"

package/template/{.env.hbs → base/.env.hbs}

@@ -1,4 +1,6 @@
 DISCORD_TOKEN=your_bot_token_here
 DISCORD_PUBLIC_KEY=your_public_key_here
 DISCORD_CLIENT_ID=your_client_id_here
+HTTP_ADDRESS=0.0.0.0
+HTTP_PORT={{port}}
 HTTP_POST_PATH=/

package/template/base/README.md.hbs

@@ -0,0 +1,33 @@
+# {{name}}
+
+A Discord bot built with [`@wolfstar/http-framework`](https://www.npmjs.com/package/@wolfstar/http-framework), an HTTP-interactions framework for Discord bots.
+
+## Setup
+
+1. Install dependencies (skip this if the generator already installed them for you).
+
+2. This project was generated with a `.env` file already in place — it's written with placeholder values directly as `.env` (there is no separate `.env.example`), and `.gitignore` keeps it out of version control. Open `.env` and replace the placeholders with your bot's real `DISCORD_TOKEN`, `DISCORD_PUBLIC_KEY`, and `DISCORD_CLIENT_ID`.
+{{#if i18n}}
+3. This project uses [`@wolfstar/plugin-i18next`](https://www.npmjs.com/package/@wolfstar/plugin-i18next). Locale resources live under `src/locales/`; after editing them, regenerate the typed i18next resources with `npm run generate:i18n`.
+{{/if}}
+
+## Scripts
+
+- `npm run dev` — run the bot in watch mode.
+- `npm run build` — compile the project (TypeScript projects only).
+- `npm start` — run the bot.
+{{#if testing}}
+- `npm test` — run the test suite with vitest.
+{{/if}}
+
+## Commands
+
+- `/ping` — replies with `Pong!`.
+{{#if subcommands}}
+- `/math add` / `/math subtract` — basic arithmetic on two integers.
+{{/if}}
+{{#if subcommandsAdvanced}}
+- `/settings profile get` / `/settings profile set` / `/settings notifications enable` / `/settings notifications disable` — subcommand groups example.
+{{/if}}
+
+The HTTP server listens on `HTTP_ADDRESS`:`HTTP_PORT` from `.env` — `{{port}}` by default.

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

@@ -0,0 +1,18 @@
+import { Command } from '@wolfstar/http-framework';
+import { ApplicationIntegrationType, InteractionContextType, MessageFlags } from 'discord-api-types/v10';
+
+export class PingCommand extends Command {
+	registerApplicationCommands(registry) {
+		registry.registerChatInputCommand((builder) =>
+			builder
+				.setName('ping')
+				.setDescription('Replies with pong!')
+				.setIntegrationTypes(ApplicationIntegrationType.GuildInstall, ApplicationIntegrationType.UserInstall)
+				.setContexts(InteractionContextType.Guild, InteractionContextType.BotDM, InteractionContextType.PrivateChannel)
+		);
+	}
+
+	chatInputRun(interaction) {
+		return interaction.reply({ content: 'Pong!', flags: MessageFlags.Ephemeral });
+	}
+}

package/template/{src → base/src}/commands/ping.ts.hbs

@@ -1,10 +1,12 @@
 import { Command, RegisterCommand } from '@wolfstar/http-framework';
-import { MessageFlags } from 'discord-api-types/v10';
+import { ApplicationIntegrationType, InteractionContextType, MessageFlags } from 'discord-api-types/v10';
 
 @RegisterCommand((builder) =>
 	builder //
 		.setName('ping')
 		.setDescription('Replies with pong!')
+		.setIntegrationTypes(ApplicationIntegrationType.GuildInstall, ApplicationIntegrationType.UserInstall)
+		.setContexts(InteractionContextType.Guild, InteractionContextType.BotDM, InteractionContextType.PrivateChannel)
 )
 export class PingCommand extends Command {
 	public override chatInputRun(interaction: Command.ChatInputInteraction) {

package/template/base/src/lib/setup/all.js.hbs

@@ -0,0 +1,8 @@
+import { setup as envRun } from '@wolfstar/env-utilities';
+/* oxlint-disable import/first -- side-effect setup modules must run after env load preparation */
+import './logger.js';
+
+export function setup() {
+	// From src/lib/setup → .env at the project root
+	envRun(new URL('../../../.env', import.meta.url));
+}

package/template/base/src/lib/setup/all.ts.hbs

@@ -0,0 +1,8 @@
+import { setup as envRun } from '@wolfstar/env-utilities';
+/* oxlint-disable import/first -- side-effect setup modules must run after env load preparation */
+import './logger.js';
+
+export function setup() {
+	// From dist/lib/setup → .env at the project root
+	envRun(new URL('../../../.env', import.meta.url));
+}