@forinda/kickjs-cli 5.1.0 → 5.2.1

package/dist/{builtins-caRjFvKz.mjs → builtins-B0dptoXq.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v5.1.0
+ * @forinda/kickjs-cli v5.2.1
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,19 +8,292 @@
  *
  * @license MIT
  */
-import { A as httpMethodColor, C as intro, D as select, E as outro, F as writeFileSafe, M as severityColor, N as fileExists, O as spinner, P as setDryRun, S as confirm, T as multiSelect, _ as pluralize, a as initProject, b as toKebabCase, c as generateKickJsSkills, d as generateService, f as generateGuard, g as resolveRepoType, h as generateModule, j as pc, k as text, l as generateDto, m as generateAdapter, n as tryDispatchPluginGenerator, o as generateAgents, p as generateMiddleware, s as generateClaude, t as listPluginGenerators, u as generateController, v as pluralizePascal, w as log, x as toPascalCase, y as toCamelCase } from "./generator-extension-CYY-RI21.mjs";
-import { a as resolveModuleConfig, i as loadKickConfig, t as PACKAGE_MANAGERS } from "./config-C_LQNClP.mjs";
-import { n as defineCliPlugin } from "./types-BBUo1vXh.mjs";
-import { n as mergeCliPlugins } from "./plugin-D8K5fG-O.mjs";
-import { a as discoverAssets, i as TokenCollisionError, o as renderAssetTypes, r as watchTypegen, t as runTypegen$1 } from "./typegen-8ZeA1B-X.mjs";
-import path, { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { A as httpMethodColor, C as intro, D as select, E as outro, F as writeFileSafe, M as severityColor, N as fileExists, O as spinner, P as setDryRun, S as confirm, T as multiSelect, _ as pluralize, a as initProject, b as toKebabCase, c as generateKickJsSkills, d as generateService, f as generateGuard, g as resolveRepoType, h as generateModule, j as pc, k as text, l as generateDto, m as generateAdapter, n as tryDispatchPluginGenerator, o as generateAgents, p as generateMiddleware, s as generateClaude, t as listPluginGenerators, u as generateController, v as pluralizePascal, w as log, x as toPascalCase, y as toCamelCase } from "./generator-extension-C-HwKvFf.mjs";
+import { a as resolveModuleConfig, i as loadKickConfig, o as resolveTokenScope, t as PACKAGE_MANAGERS } from "./config-CRi3zCxk.mjs";
+import { n as defineCliPlugin } from "./types-CU89yUxU.mjs";
+import { n as mergeCliPlugins } from "./plugin-DfomEcef.mjs";
+import { a as discoverAssets, i as TokenCollisionError, o as renderAssetTypes, r as watchTypegen, s as scanProject, t as runTypegen$1 } from "./typegen-B9S81bOx.mjs";
+import path, { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { execSync, fork, spawn, spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { glob } from "glob";
+import { groupAssetKeys } from "@forinda/kickjs";
 import { arch, platform, release } from "node:os";
 import { generate, migrateDown, migrateLatest, migrateRollback, migrateStatus, migrateUp, renderSchemaSource, resolveDbConfig } from "@forinda/kickjs-db";
+//#region src/commands/add.ts
+/** Registry of KickJS packages and their required peer dependencies */
+const PACKAGE_REGISTRY = {
+	kickjs: {
+		pkg: "@forinda/kickjs",
+		peers: ["express"],
+		description: "Unified framework: DI, decorators, routing, middleware",
+		core: true
+	},
+	vite: {
+		pkg: "@forinda/kickjs-vite",
+		peers: ["vite"],
+		description: "Vite plugin: dev server, HMR, module discovery",
+		dev: true,
+		core: true
+	},
+	cli: {
+		pkg: "@forinda/kickjs-cli",
+		peers: [],
+		description: "CLI tool and code generators",
+		dev: true,
+		core: true
+	},
+	swagger: {
+		pkg: "@forinda/kickjs-swagger",
+		peers: [],
+		description: "OpenAPI spec + Swagger UI + ReDoc"
+	},
+	db: {
+		pkg: "@forinda/kickjs-db",
+		peers: [],
+		description: "kick/db core — schema DSL, migrations, KickDbClient, customType"
+	},
+	"db-pg": {
+		pkg: "@forinda/kickjs-db-pg",
+		peers: ["pg"],
+		description: "kick/db PostgreSQL dialect + adapter (pgDialect, pgAdapter)"
+	},
+	drizzle: {
+		pkg: "@forinda/kickjs-drizzle",
+		peers: ["drizzle-orm"],
+		description: "Drizzle ORM adapter + query builder"
+	},
+	prisma: {
+		pkg: "@forinda/kickjs-prisma",
+		peers: ["@prisma/client"],
+		description: "Prisma adapter + query builder"
+	},
+	ws: {
+		pkg: "@forinda/kickjs-ws",
+		peers: ["socket.io"],
+		description: "WebSocket with @WsController decorators"
+	},
+	devtools: {
+		pkg: "@forinda/kickjs-devtools",
+		peers: [],
+		description: "Development dashboard — routes, DI, metrics, health",
+		dev: true
+	},
+	auth: {
+		pkg: "@forinda/kickjs-auth",
+		peers: ["jsonwebtoken"],
+		description: "Authentication — JWT, API key, and custom strategies"
+	},
+	queue: {
+		pkg: "@forinda/kickjs-queue",
+		peers: [],
+		description: "Queue adapter (BullMQ/RabbitMQ/Kafka)"
+	},
+	"queue:bullmq": {
+		pkg: "@forinda/kickjs-queue",
+		peers: ["bullmq", "ioredis"],
+		description: "Queue with BullMQ + Redis"
+	},
+	"queue:rabbitmq": {
+		pkg: "@forinda/kickjs-queue",
+		peers: ["amqplib"],
+		description: "Queue with RabbitMQ"
+	},
+	"queue:kafka": {
+		pkg: "@forinda/kickjs-queue",
+		peers: ["kafkajs"],
+		description: "Queue with Kafka"
+	},
+	mcp: {
+		pkg: "@forinda/kickjs-mcp",
+		peers: ["@modelcontextprotocol/sdk"],
+		description: "Model Context Protocol server — expose @Controller endpoints as AI tools"
+	},
+	testing: {
+		pkg: "@forinda/kickjs-testing",
+		peers: [],
+		description: "Test utilities and TestModule builder",
+		dev: true
+	}
+};
+/**
+* Walk up from `fromDir` to filesystem root, returning the first
+* directory that contains `name`. Lets monorepo sub-packages pick up
+* lockfiles and `packageManager` fields living at the workspace root.
+*/
+function findUp(name, fromDir = process.cwd()) {
+	let current = fromDir;
+	while (true) {
+		if (existsSync(resolve(current, name))) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+function detectFromLockfile() {
+	if (findUp("pnpm-lock.yaml")) return "pnpm";
+	if (findUp("yarn.lock")) return "yarn";
+	if (findUp("bun.lockb") || findUp("bun.lock")) return "bun";
+	if (findUp("package-lock.json")) return "npm";
+	return null;
+}
+/**
+* Read `packageManager` from the nearest ancestor `package.json` that
+* declares the field (corepack convention: `"pnpm@10.0.0"`). Climbs so
+* monorepo sub-packages inherit the workspace pm even when their own
+* package.json omits the field.
+*/
+function packageManagerFromPackageJson() {
+	let dir = process.cwd();
+	while (dir) {
+		const pkgPath = resolve(dir, "package.json");
+		if (existsSync(pkgPath)) try {
+			const field = JSON.parse(readFileSync(pkgPath, "utf-8")).packageManager;
+			if (typeof field === "string") {
+				const name = field.split("@")[0];
+				if (PACKAGE_MANAGERS.includes(name)) return name;
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Resolve which package manager to use, in priority order:
+* 1. `--pm` CLI flag
+* 2. `packageManager` in kick.config
+* 3. `packageManager` in nearest ancestor package.json (corepack)
+* 4. Nearest ancestor lockfile (pnpm-lock.yaml → yarn.lock → bun.lock → package-lock.json)
+* 5. `'npm'` fallback
+*
+* Returns the chosen pm plus the source for callers that want to log
+* the resolution path.
+*/
+async function resolvePackageManagerWithSource(flagPm) {
+	if (flagPm && PACKAGE_MANAGERS.includes(flagPm)) return {
+		pm: flagPm,
+		source: "flag"
+	};
+	const config = await loadKickConfig(process.cwd());
+	if (config?.packageManager && PACKAGE_MANAGERS.includes(config.packageManager)) return {
+		pm: config.packageManager,
+		source: "config"
+	};
+	const fromPkg = packageManagerFromPackageJson();
+	if (fromPkg) return {
+		pm: fromPkg,
+		source: "package.json"
+	};
+	const fromLock = detectFromLockfile();
+	if (fromLock) return {
+		pm: fromLock,
+		source: "lockfile"
+	};
+	return {
+		pm: "npm",
+		source: "default"
+	};
+}
+/** Convenience wrapper for callers that don't care about the source. */
+async function resolvePackageManager(flagPm) {
+	const { pm } = await resolvePackageManagerWithSource(flagPm);
+	return pm;
+}
+/**
+* Print the package catalog. By default shows just the three core
+* packages every project always has — the optional list churns
+* (packages added, deprecated, removed) and a long enumeration in CLI
+* output / docs goes stale within a release. Pass `all = true` to dump
+* everything; that's what `kick add --list --all` triggers when an
+* adopter genuinely wants the live catalog.
+*/
+function printPackageList(all = false) {
+	const entries = Object.entries(PACKAGE_REGISTRY);
+	const maxName = Math.max(...entries.map(([k]) => k.length));
+	const core = entries.filter(([, info]) => info.core);
+	const optional = entries.filter(([, info]) => !info.core);
+	const formatRow = ([name, info]) => {
+		const padded = name.padEnd(maxName + 2);
+		const peers = info.peers.length ? ` (+ ${info.peers.join(", ")})` : "";
+		return `    ${padded} ${info.description}${peers}`;
+	};
+	console.log("\n  Core packages (always installed by `kick new`):\n");
+	for (const row of core) console.log(formatRow(row));
+	if (all) {
+		console.log("\n  Optional packages (add as needed):\n");
+		for (const row of optional) console.log(formatRow(row));
+	} else {
+		console.log(`\n  Plus ${optional.length} optional packages (auth, swagger, db, queue, …).`);
+		console.log("  Run `kick add --list --all` for the full catalog.");
+	}
+	console.log("\n  Usage: kick add auth drizzle swagger");
+	console.log("         kick add queue:bullmq");
+	console.log();
+}
+function registerListCommand(program) {
+	program.command("list").alias("ls").description("List KickJS packages (core only; pair with --all for the full catalog)").option("--all", "Include the full optional catalog").action((opts) => {
+		printPackageList(Boolean(opts.all));
+	});
+}
+function registerAddCommand(program) {
+	program.command("add [packages...]").description("Add KickJS packages with their required dependencies").option("--pm <manager>", "Package manager override").option("-D, --dev", "Install as dev dependency").option("--list", "List packages (core only by default; pair with --all)").option("--all", "When listing, include the full optional catalog").action(async (packages, opts) => {
+		if (opts.list || packages.length === 0) {
+			printPackageList(Boolean(opts.all));
+			return;
+		}
+		const { pm, source } = await resolvePackageManagerWithSource(opts.pm);
+		console.log(`\n  Using ${pm} (resolved from ${source})`);
+		const forceDevFlag = opts.dev;
+		const prodDeps = /* @__PURE__ */ new Set();
+		const devDeps = /* @__PURE__ */ new Set();
+		const unknown = [];
+		for (const name of packages) {
+			const entry = PACKAGE_REGISTRY[name];
+			if (!entry) {
+				unknown.push(name);
+				continue;
+			}
+			const target = forceDevFlag || entry.dev ? devDeps : prodDeps;
+			target.add(entry.pkg);
+			for (const peer of entry.peers) target.add(peer);
+		}
+		if (unknown.length > 0) {
+			console.log(`\n  Unknown packages: ${unknown.join(", ")}`);
+			console.log("  Run \"kick add --list\" to see available packages.\n");
+			if (prodDeps.size === 0 && devDeps.size === 0) return;
+		}
+		if (prodDeps.size > 0) {
+			const deps = Array.from(prodDeps);
+			const cmd = `${pm} add ${deps.join(" ")}`;
+			console.log(`\n  Installing ${deps.length} dependency(ies):`);
+			for (const dep of deps) console.log(`    + ${dep}`);
+			console.log();
+			try {
+				execSync(cmd, { stdio: "inherit" });
+			} catch {
+				console.log(`\n  Installation failed. Run manually:\n    ${cmd}\n`);
+			}
+		}
+		if (devDeps.size > 0) {
+			const deps = Array.from(devDeps);
+			const cmd = `${pm} add -D ${deps.join(" ")}`;
+			console.log(`\n  Installing ${deps.length} dev dependency(ies):`);
+			for (const dep of deps) console.log(`    + ${dep} (dev)`);
+			console.log();
+			try {
+				execSync(cmd, { stdio: "inherit" });
+			} catch {
+				console.log(`\n  Installation failed. Run manually:\n    ${cmd}\n`);
+			}
+		}
+		console.log("  Done!\n");
+	});
+}
+//#endregion
 //#region src/commands/init.ts
 /** All optional packages available for selection */
 const OPTIONAL_PACKAGES = [
@@ -51,9 +324,11 @@ const OPTIONAL_PACKAGES = [
 	}
 ];
 function registerInitCommand(program) {
-	program.command("new [name]").alias("init").description("Create a new KickJS project (use \".\" for current directory)").option("-d, --directory <dir>", "Target directory (defaults to project name)").option("--pm <manager>", "Package manager: pnpm | npm | yarn | bun").option("--git", "Initialize git repository").option("--no-git", "Skip git initialization").option("--install", "Install dependencies after scaffolding").option("--no-install", "Skip dependency installation").option("-f, --force", "Remove existing files without prompting").option("-t, --template <type>", "Project template: rest | ddd | cqrs | minimal").option("-r, --repo <type>", "Default repository: prisma | drizzle | inmemory | custom").option("--packages <packages>", "Comma-separated packages to include (e.g. auth,swagger,ws,queue)").action(async (name, opts) => {
+	program.command("new [name]").alias("init").description("Create a new KickJS project (use \".\" for current directory)").option("-d, --directory <dir>", "Target directory (defaults to project name)").option("--pm <manager>", "Package manager: pnpm | npm | yarn | bun").option("--git", "Initialize git repository").option("--no-git", "Skip git initialization").option("--install", "Install dependencies after scaffolding").option("--no-install", "Skip dependency installation").option("-f, --force", "Remove existing files without prompting").option("-t, --template <type>", "Project template: rest | ddd | cqrs | minimal").option("-r, --repo <type>", "Default repository: prisma | drizzle | inmemory | custom").option("--packages <packages>", "Comma-separated packages to include (e.g. auth,swagger,ws,queue)").option("-y, --yes", "Pick safe defaults for every prompt (template=minimal, repo=inmemory, no extras, git+install on)").option("--non-interactive", "alias for --yes").action(async (name, opts) => {
 		intro("KickJS — Create a new project");
-		if (!name) name = await text({
+		const yes = Boolean(opts.yes || opts.nonInteractive);
+		if (!name) if (yes) name = "my-api";
+		else name = await text({
 			message: "Project name",
 			placeholder: "my-api",
 			defaultValue: "my-api"
@@ -67,7 +342,11 @@ function registerInitCommand(program) {
 			const entries = readdirSync(directory);
 			if (entries.length > 0) {
 				if (opts.force) log.warn(`Clearing existing files in ${directory}`);
-				else {
+				else if (yes) {
+					log.warn(`Directory "${name}" is not empty. Pass --force to clear it.`);
+					outro("Aborted.");
+					return;
+				} else {
 					log.warn(`Directory "${name}" is not empty:`);
 					const shown = entries.slice(0, 5);
 					for (const entry of shown) log.message(`  - ${entry}`);
@@ -87,7 +366,8 @@ function registerInitCommand(program) {
 			}
 		}
 		let template = opts.template;
-		if (!template) template = await select({
+		if (!template) if (yes) template = "minimal";
+		else template = await select({
 			message: "Project template",
 			options: [
 				{
@@ -113,7 +393,8 @@ function registerInitCommand(program) {
 			]
 		});
 		let packageManager = opts.pm;
-		if (!packageManager) packageManager = await select({
+		if (!packageManager) if (yes) packageManager = await resolvePackageManager(void 0);
+		else packageManager = await select({
 			message: "Package manager",
 			options: [
 				{
@@ -135,7 +416,8 @@ function registerInitCommand(program) {
 			]
 		});
 		let defaultRepo = opts.repo;
-		if (!defaultRepo) {
+		if (!defaultRepo) if (yes) defaultRepo = "inmemory";
+		else {
 			defaultRepo = await select({
 				message: "Default repository/ORM",
 				options: [
@@ -168,19 +450,20 @@ function registerInitCommand(program) {
 			const raw = opts.packages.trim().toLowerCase();
 			if (raw === "" || raw === "none" || raw === "false") selectedPackages = [];
 			else selectedPackages = opts.packages.split(",").map((p) => p.trim()).filter(Boolean);
-		} else selectedPackages = await multiSelect({
+		} else if (yes) selectedPackages = [];
+		else selectedPackages = await multiSelect({
 			message: "Select packages to include",
 			options: [...OPTIONAL_PACKAGES],
 			required: false
 		});
 		let initGit;
-		if (opts.git === void 0) initGit = await confirm({
+		if (opts.git === void 0) initGit = yes ? true : await confirm({
 			message: "Initialize git repository?",
 			initialValue: true
 		});
 		else initGit = opts.git;
 		let installDeps;
-		if (opts.install === void 0) installDeps = await confirm({
+		if (opts.install === void 0) installDeps = yes ? true : await confirm({
 			message: "Install dependencies?",
 			initialValue: true
 		});
@@ -428,7 +711,7 @@ function detectName(outDir, override) {
 		const pkg = JSON.parse(readFileSync(join(outDir, "package.json"), "utf-8"));
 		if (pkg.name) return pkg.name.replace(/^@[^/]+\//, "");
 	} catch {}
-	return outDir.split("/").filter(Boolean).pop() ?? "app";
+	return outDir.split("/").findLast(Boolean) ?? "app";
 }
 function detectPm(outDir, override) {
 	if (override) return override;
@@ -892,7 +1175,7 @@ function parseFields(raw) {
 	});
 }
 async function generateScaffold(options) {
-	const { name, fields, modulesDir, noEntity, noTests, repo = "inmemory" } = options;
+	const { name, fields, modulesDir, noEntity, noTests: _noTests, repo = "inmemory", tokenScope = "app" } = options;
 	const shouldPluralize = options.pluralize !== false;
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -914,7 +1197,7 @@ async function generateScaffold(options) {
 	await write(`application/dtos/${kebab}-response.dto.ts`, genResponseDTO(pascal, fields));
 	const useCases = genUseCases(pascal, kebab, plural, pluralPascal);
 	for (const uc of useCases) await write(`application/use-cases/${uc.file}`, uc.content);
-	await write(`domain/repositories/${kebab}.repository.ts`, genRepositoryInterface(pascal, kebab));
+	await write(`domain/repositories/${kebab}.repository.ts`, genRepositoryInterface(pascal, kebab, tokenScope));
 	await write(`domain/services/${kebab}-domain.service.ts`, genDomainService(pascal, kebab));
 	if (repo === "inmemory") await write(`infrastructure/repositories/in-memory-${kebab}.repository.ts`, genInMemoryRepository(pascal, kebab, fields));
 	if (!noEntity) {
@@ -1195,7 +1478,7 @@ export class ${pascal}Controller {
 }
 `;
 }
-function genRepositoryInterface(pascal, kebab) {
+function genRepositoryInterface(pascal, kebab, tokenScope) {
 	return `import { createToken } from '@forinda/kickjs'
 import type { ${pascal}ResponseDTO } from '../../application/dtos/${kebab}-response.dto'
 import type { Create${pascal}DTO } from '../../application/dtos/create-${kebab}.dto'
@@ -1216,8 +1499,12 @@ export interface I${pascal}Repository {
  * \`container.resolve(${pascal.toUpperCase()}_REPOSITORY)\` and
  * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
  * interface — no manual generic, no \`any\` cast.
+ *
+ * The \`'${tokenScope}/'\` prefix matches the project scope so
+ * \`kick-lint\`'s \`token-reserved-prefix\` rule never fires —
+ * adopters must NOT use the reserved \`'kick/'\` namespace.
  */
-export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('app/${kebab}/repository')
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${tokenScope}/${kebab}/repository')
 `;
 }
 function genDomainService(pascal, kebab) {
@@ -1497,6 +1784,7 @@ async function runModuleGeneration(names, opts, dryRun) {
 	const repo = opts.repo ?? resolveRepoType(mc.repo);
 	const pattern = opts.pattern ?? config?.pattern ?? "ddd";
 	const shouldPluralize = opts.pluralize === false ? false : mc.pluralize ?? true;
+	const tokenScope = resolveTokenScope(config, process.cwd());
 	const allFiles = [];
 	for (const name of names) {
 		const files = await generateModule({
@@ -1510,7 +1798,8 @@ async function runModuleGeneration(names, opts, dryRun) {
 			pattern,
 			dryRun,
 			pluralize: shouldPluralize,
-			prismaClientPath: mc.prismaClientPath
+			prismaClientPath: mc.prismaClientPath,
+			tokenScope
 		});
 		allFiles.push(...files);
 	}
@@ -1673,16 +1962,19 @@ function registerGenerateCommand(program) {
 			console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text:optional published:boolean:optional\n  Optional: append :optional (shell-safe, no quoting needed)\n");
 			process.exit(1);
 		}
-		const mc = resolveModuleConfig(await loadKickConfig(process.cwd()));
+		const config = await loadKickConfig(process.cwd());
+		const mc = resolveModuleConfig(config);
 		const modulesDir = opts.modulesDir ?? mc.dir ?? "src/modules";
 		const fields = parseFields(rawFields);
+		const tokenScope = resolveTokenScope(config, process.cwd());
 		const files = await generateScaffold({
 			name,
 			fields,
 			modulesDir: resolve(modulesDir),
 			noEntity: opts.entity === false,
 			noTests: opts.tests === false,
-			pluralize: opts.pluralize === false ? false : mc.pluralize ?? true
+			pluralize: opts.pluralize === false ? false : mc.pluralize ?? true,
+			tokenScope
 		});
 		console.log(`\n  Scaffolded ${name} with ${fields.length} field(s):`);
 		for (const f of fields) console.log(`    ${f.name}: ${f.type}${f.optional ? " (optional)" : ""}`);
@@ -1771,6 +2063,17 @@ const BANNER_PREFIX = "/* AUTO-GENERATED by kick typegen — do not edit. Plugin
 async function runTypegen(opts) {
 	const typesDirAbs = path.resolve(opts.cwd, TYPES_DIR);
 	await mkdir(typesDirAbs, { recursive: true });
+	const scanCache = /* @__PURE__ */ new Map();
+	const scanFn = opts.scan ?? scanProject;
+	const getScanResult = (scanOpts) => {
+		const key = stableScanKey(scanOpts);
+		let pending = scanCache.get(key);
+		if (!pending) {
+			pending = scanFn(scanOpts);
+			scanCache.set(key, pending);
+		}
+		return pending;
+	};
 	const ctx = {
 		cwd: opts.cwd,
 		config: opts.config,
@@ -1782,6 +2085,7 @@ async function runTypegen(opts) {
 			await mkdir(path.dirname(abs), { recursive: true });
 			await writeFile(abs, contents, "utf8");
 		},
+		getScanResult,
 		log: console
 	};
 	const results = [];
@@ -1794,7 +2098,8 @@ async function runTypegen(opts) {
 			});
 			continue;
 		}
-		const file = path.join(typesDirAbs, `${plugin.id.replace(/\//g, "__")}.d.ts`);
+		const ext = plugin.outExtension ?? ".d.ts";
+		const file = path.join(typesDirAbs, `${plugin.id.replace(/\//g, "__")}${ext}`);
 		const next = `${BANNER_PREFIX}${plugin.id} */\n\n` + out + "\n";
 		let prev = "";
 		if (existsSync(file)) prev = await readFile(file, "utf8");
@@ -1816,6 +2121,24 @@ async function runTypegen(opts) {
 	}
 	return results;
 }
+/**
+* Order-independent cache key for `ScanOptions`. Builds the key from
+* the known fields in a fixed order so semantically equal options
+* always produce the same key regardless of how the caller built the
+* object literal. Arrays (extensions / exclude) are sorted before
+* joining so `['.ts', '.tsx']` and `['.tsx', '.ts']` collide.
+*/
+function stableScanKey(opts) {
+	const extensions = (opts.extensions ?? []).slice().toSorted().join(",");
+	const exclude = (opts.exclude ?? []).slice().toSorted().join(",");
+	return [
+		`root=${opts.root}`,
+		`cwd=${opts.cwd}`,
+		`extensions=${extensions}`,
+		`exclude=${exclude}`,
+		`envFile=${opts.envFile ?? ""}`
+	].join("|");
+}
 //#endregion
 //#region src/typegen/disable-filter.ts
 /**
@@ -1937,18 +2260,15 @@ async function processEntry(namespace, entry, cwd, distAbs) {
 	});
 	mkdirSync(destAbs, { recursive: true });
 	const manifestSlice = {};
-	const keyOwner = /* @__PURE__ */ new Map();
-	for (const relPath of matches.sort()) {
+	const { pairs, collisionGroupsResolved } = groupAssetKeys(namespace, [...matches].toSorted(), { strategy: entry.keys ?? "auto" });
+	for (const { rel: relPath, key } of pairs) {
 		const srcFile = join(srcAbs, relPath);
 		const destFile = join(destAbs, relPath);
 		mkdirSync(dirname(destFile), { recursive: true });
 		cpSync(srcFile, destFile);
-		const logicalKey = `${namespace}/${stripExt(relPath)}`;
-		const previous = keyOwner.get(logicalKey);
-		if (previous) console.warn(`  ⚠ assetMap collision in '${namespace}': '${previous}' and '${relPath}' both flatten to key '${logicalKey}'. Last-alphabetical wins ('${relPath}'). Rename one of them or set assetMap.${namespace}.glob to filter by extension.`);
-		keyOwner.set(logicalKey, relPath);
-		manifestSlice[logicalKey] = toManifestRelative(distAbs, destFile);
+		manifestSlice[key] = toManifestRelative(distAbs, destFile);
 	}
+	if (collisionGroupsResolved > 0) console.log(`  ℹ assetMap.${namespace}: auto-resolved ${collisionGroupsResolved} basename collision(s) by keeping extensions (set 'keys: "strip"' to opt back into legacy last-write-wins behaviour, or 'keys: "with-extension"' to keep all keys verbose).`);
 	return {
 		entrySummary: {
 			namespace,
@@ -1959,11 +2279,6 @@ async function processEntry(namespace, entry, cwd, distAbs) {
 		manifestSlice
 	};
 }
-/** Strip the final extension from a file path (`mails/welcome.ejs` → `mails/welcome`). */
-function stripExt(path) {
-	const ext = extname(path);
-	return ext ? path.slice(0, -ext.length) : path;
-}
 /**
 * Make `destFile` relative to the manifest's directory + force POSIX
 * separators so the manifest is byte-stable across platforms.
@@ -2005,8 +2320,21 @@ function isDirectorySync(path) {
 * This function just creates the Vite server, listens, and handles shutdown.
 * Vite owns the HTTP port — Express runs as post-middleware on Vite's server.
 */
-async function startDevServer(_entry, port) {
+/**
+* Resolve whether the dev server's chokidar should poll instead of
+* relying on `fs.watch` events. CLI flag wins over env var; default
+* is event-based (faster, lower CPU). Polling is the right choice in
+* Docker bind mounts, WSL crossing the WSL/Windows boundary, NFS,
+* and some old Linux kernels where new-file events get dropped.
+*/
+function resolvePolling(flag) {
+	if (typeof flag === "boolean") return flag;
+	const env = process.env.KICKJS_WATCH_POLLING;
+	return env === "1" || env === "true";
+}
+async function startDevServer(_entry, port, opts = {}) {
 	if (port) process.env.PORT = port;
+	const polling = resolvePolling(opts.polling);
 	const cwd = process.cwd();
 	const devConfig = await loadKickConfig(cwd);
 	const schemaValidator = devConfig?.typegen?.schemaValidator ?? "zod";
@@ -2019,7 +2347,8 @@ async function startDevServer(_entry, port) {
 			envFile,
 			srcDir: devConfig?.typegen?.srcDir,
 			outDir: devConfig?.typegen?.outDir,
-			assetMap: devConfig?.assetMap
+			assetMap: devConfig?.assetMap,
+			runPlugins: false
 		});
 	} catch (err) {
 		console.warn(`  kick typegen: skipped (${err?.message ?? err})`);
@@ -2032,7 +2361,13 @@ async function startDevServer(_entry, port) {
 	const { createServer } = await import(pathToFileURL(createRequire(resolve("package.json")).resolve("vite")).href);
 	const server = await createServer({
 		configFile: resolve("vite.config.ts"),
-		server: { port: port ? parseInt(port, 10) : void 0 }
+		server: {
+			port: port ? parseInt(port, 10) : void 0,
+			...polling ? { watch: {
+				usePolling: true,
+				interval: 100
+			} } : {}
+		}
 	});
 	const assetSrcRoots = devConfig?.assetMap ? Object.values(devConfig.assetMap).map((entry) => entry?.src).filter((src) => typeof src === "string" && src.length > 0).map((src) => resolve(cwd, src)) : [];
 	const isAssetFile = (file) => assetSrcRoots.some((root) => file === root || file.startsWith(`${root}/`));
@@ -2053,7 +2388,8 @@ async function startDevServer(_entry, port) {
 				envFile,
 				srcDir: devConfig?.typegen?.srcDir,
 				outDir: devConfig?.typegen?.outDir,
-				assetMap: devConfig?.assetMap
+				assetMap: devConfig?.assetMap,
+				runPlugins: false
 			}).catch(() => {});
 			runAllPluginTypegens({
 				cwd,
@@ -2078,9 +2414,9 @@ async function startDevServer(_entry, port) {
 	process.on("SIGTERM", shutdown);
 }
 function registerRunCommands(program) {
-	program.command("dev").description("Start development server with Vite HMR (zero-downtime reload)").option("-e, --entry <file>", "Entry file", "src/index.ts").option("-p, --port <port>", "Port number").action(async (opts) => {
+	program.command("dev").description("Start development server with Vite HMR (zero-downtime reload)").option("-e, --entry <file>", "Entry file", "src/index.ts").option("-p, --port <port>", "Port number").option("--polling", "Force chokidar to poll for file changes (Docker / WSL / NFS / older kernels)").action(async (opts) => {
 		try {
-			await startDevServer(opts.entry, opts.port);
+			await startDevServer(opts.entry, opts.port, { polling: opts.polling });
 		} catch (err) {
 			if (err.code === "ERR_MODULE_NOT_FOUND" && err.message?.includes("vite")) console.error("\n  Error: vite is not installed.\n  Run: pnpm add -D vite unplugin-swc\n");
 			else console.error("\n  Dev server failed:", err.message ?? err);
@@ -2173,7 +2509,7 @@ function registerInfoCommand(program) {
 }
 //#endregion
 //#region src/commands/inspect.ts
-const { bold, dim, green, red, yellow, cyan, blue } = pc;
+const { bold, dim, green, red, yellow, blue } = pc;
 function formatUptime(seconds) {
 	const d = Math.floor(seconds / 86400);
 	const h = Math.floor(seconds % 86400 / 3600);
@@ -2282,198 +2618,6 @@ function registerInspectCommand(program) {
 	});
 }
 //#endregion
-//#region src/commands/add.ts
-/** Registry of KickJS packages and their required peer dependencies */
-const PACKAGE_REGISTRY = {
-	kickjs: {
-		pkg: "@forinda/kickjs",
-		peers: ["express"],
-		description: "Unified framework: DI, decorators, routing, middleware"
-	},
-	vite: {
-		pkg: "@forinda/kickjs-vite",
-		peers: ["vite"],
-		description: "Vite plugin: dev server, HMR, module discovery",
-		dev: true
-	},
-	config: {
-		pkg: "dotenv",
-		peers: [],
-		description: "Optional .env file loader (kickjs ConfigService now ships in @forinda/kickjs)"
-	},
-	cli: {
-		pkg: "@forinda/kickjs-cli",
-		peers: [],
-		description: "CLI tool and code generators",
-		dev: true
-	},
-	swagger: {
-		pkg: "@forinda/kickjs-swagger",
-		peers: [],
-		description: "OpenAPI spec + Swagger UI + ReDoc"
-	},
-	drizzle: {
-		pkg: "@forinda/kickjs-drizzle",
-		peers: ["drizzle-orm"],
-		description: "Drizzle ORM adapter + query builder"
-	},
-	prisma: {
-		pkg: "@forinda/kickjs-prisma",
-		peers: ["@prisma/client"],
-		description: "Prisma adapter + query builder"
-	},
-	ws: {
-		pkg: "@forinda/kickjs-ws",
-		peers: ["socket.io"],
-		description: "WebSocket with @WsController decorators"
-	},
-	devtools: {
-		pkg: "@forinda/kickjs-devtools",
-		peers: [],
-		description: "Development dashboard — routes, DI, metrics, health",
-		dev: true
-	},
-	auth: {
-		pkg: "@forinda/kickjs-auth",
-		peers: ["jsonwebtoken"],
-		description: "Authentication — JWT, API key, and custom strategies"
-	},
-	queue: {
-		pkg: "@forinda/kickjs-queue",
-		peers: [],
-		description: "Queue adapter (BullMQ/RabbitMQ/Kafka)"
-	},
-	"queue:bullmq": {
-		pkg: "@forinda/kickjs-queue",
-		peers: ["bullmq", "ioredis"],
-		description: "Queue with BullMQ + Redis"
-	},
-	"queue:rabbitmq": {
-		pkg: "@forinda/kickjs-queue",
-		peers: ["amqplib"],
-		description: "Queue with RabbitMQ"
-	},
-	"queue:kafka": {
-		pkg: "@forinda/kickjs-queue",
-		peers: ["kafkajs"],
-		description: "Queue with Kafka"
-	},
-	mcp: {
-		pkg: "@forinda/kickjs-mcp",
-		peers: ["@modelcontextprotocol/sdk"],
-		description: "Model Context Protocol server — expose @Controller endpoints as AI tools"
-	},
-	testing: {
-		pkg: "@forinda/kickjs-testing",
-		peers: [],
-		description: "Test utilities and TestModule builder",
-		dev: true
-	}
-};
-function detectPackageManager() {
-	if (existsSync(resolve("pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(resolve("yarn.lock"))) return "yarn";
-	if (existsSync(resolve("bun.lockb")) || existsSync(resolve("bun.lock"))) return "bun";
-	return "npm";
-}
-/** Read `packageManager` from package.json (corepack convention: "pnpm@10.0.0") */
-function packageManagerFromPackageJson() {
-	try {
-		const field = JSON.parse(readFileSync(resolve("package.json"), "utf-8")).packageManager;
-		if (typeof field !== "string") return null;
-		const name = field.split("@")[0];
-		return PACKAGE_MANAGERS.includes(name) ? name : null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Resolve which package manager to use, in priority order:
-* 1. `--pm` CLI flag
-* 2. `packageManager` in kick.config
-* 3. `packageManager` in package.json (corepack)
-* 4. Lockfile detection
-* 5. `'npm'`
-*/
-async function resolvePackageManager(flagPm) {
-	if (flagPm && PACKAGE_MANAGERS.includes(flagPm)) return flagPm;
-	const config = await loadKickConfig(process.cwd());
-	if (config?.packageManager && PACKAGE_MANAGERS.includes(config.packageManager)) return config.packageManager;
-	const fromPkg = packageManagerFromPackageJson();
-	if (fromPkg) return fromPkg;
-	return detectPackageManager();
-}
-function printPackageList() {
-	console.log("\n  Available KickJS packages:\n");
-	const maxName = Math.max(...Object.keys(PACKAGE_REGISTRY).map((k) => k.length));
-	for (const [name, info] of Object.entries(PACKAGE_REGISTRY)) {
-		const padded = name.padEnd(maxName + 2);
-		const peers = info.peers.length ? ` (+ ${info.peers.join(", ")})` : "";
-		console.log(`    ${padded} ${info.description}${peers}`);
-	}
-	console.log("\n  Usage: kick add auth drizzle swagger");
-	console.log("         kick add queue:bullmq");
-	console.log();
-}
-function registerListCommand(program) {
-	program.command("list").alias("ls").description("List all available KickJS packages").action(() => {
-		printPackageList();
-	});
-}
-function registerAddCommand(program) {
-	program.command("add [packages...]").description("Add KickJS packages with their required dependencies").option("--pm <manager>", "Package manager override").option("-D, --dev", "Install as dev dependency").option("--list", "List all available packages").action(async (packages, opts) => {
-		if (opts.list || packages.length === 0) {
-			printPackageList();
-			return;
-		}
-		const pm = await resolvePackageManager(opts.pm);
-		const forceDevFlag = opts.dev;
-		const prodDeps = /* @__PURE__ */ new Set();
-		const devDeps = /* @__PURE__ */ new Set();
-		const unknown = [];
-		for (const name of packages) {
-			const entry = PACKAGE_REGISTRY[name];
-			if (!entry) {
-				unknown.push(name);
-				continue;
-			}
-			const target = forceDevFlag || entry.dev ? devDeps : prodDeps;
-			target.add(entry.pkg);
-			for (const peer of entry.peers) target.add(peer);
-		}
-		if (unknown.length > 0) {
-			console.log(`\n  Unknown packages: ${unknown.join(", ")}`);
-			console.log("  Run \"kick add --list\" to see available packages.\n");
-			if (prodDeps.size === 0 && devDeps.size === 0) return;
-		}
-		if (prodDeps.size > 0) {
-			const deps = Array.from(prodDeps);
-			const cmd = `${pm} add ${deps.join(" ")}`;
-			console.log(`\n  Installing ${deps.length} dependency(ies):`);
-			for (const dep of deps) console.log(`    + ${dep}`);
-			console.log();
-			try {
-				execSync(cmd, { stdio: "inherit" });
-			} catch {
-				console.log(`\n  Installation failed. Run manually:\n    ${cmd}\n`);
-			}
-		}
-		if (devDeps.size > 0) {
-			const deps = Array.from(devDeps);
-			const cmd = `${pm} add -D ${deps.join(" ")}`;
-			console.log(`\n  Installing ${deps.length} dev dependency(ies):`);
-			for (const dep of deps) console.log(`    + ${dep} (dev)`);
-			console.log();
-			try {
-				execSync(cmd, { stdio: "inherit" });
-			} catch {
-				console.log(`\n  Installation failed. Run manually:\n    ${cmd}\n`);
-			}
-		}
-		console.log("  Done!\n");
-	});
-}
-//#endregion
 //#region src/explain/known-issues.ts
 function includesAll(haystack, needles) {
 	const lower = haystack.toLowerCase();
@@ -3280,8 +3424,8 @@ function registerTypegenCommand(program) {
 		const cwd = process.cwd();
 		const config = await loadKickConfig(cwd);
 		if (opts.list) {
-			const { mergeCliPlugins } = await import("./plugin-D8K5fG-O.mjs").then((n) => n.t);
-			const { builtinCliPlugins } = await import("./builtins-caRjFvKz.mjs");
+			const { mergeCliPlugins } = await import("./plugin-DfomEcef.mjs").then((n) => n.t);
+			const { builtinCliPlugins } = await import("./builtins-B0dptoXq.mjs");
 			const merged = mergeCliPlugins([...builtinCliPlugins, ...config?.plugins ?? []], config?.commands ?? []);
 			const disabled = new Set(config?.typegen?.disable ?? []);
 			if (merged.typegens.length === 0) {
@@ -3307,7 +3451,8 @@ function registerTypegenCommand(program) {
 			allowDuplicates: opts.allowDuplicates,
 			schemaValidator,
 			envFile,
-			assetMap: config?.assetMap
+			assetMap: config?.assetMap,
+			runPlugins: false
 		};
 		try {
 			if (opts.watch) {
@@ -3727,6 +3872,238 @@ const kickAssetsTypegen = () => ({
 	}
 });
 //#endregion
+//#region src/typegen/render/routes.ts
+const ROUTES_HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+/**
+* Render the `KickRoutes` global namespace augmentation. Each interface
+* inside corresponds to a controller class; each property is a single
+* route method on that controller, conforming to `RouteShape`.
+*
+* Fills `params` from URL patterns, `query` from `@ApiQueryParams`, and
+* `body`/`query`/`params` (when schema-validated) from the configured
+* schema validator. `response` is emitted as `unknown`.
+*/
+function renderRoutes(routes, routesOutFile, schemaValidator) {
+	if (routes.length === 0) return `${ROUTES_HEADER}
+// (no routes discovered yet — annotate a controller method with
+//  @Get/@Post/@Put/@Delete/@Patch and re-run \`kick typegen\`)
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace KickRoutes {}
+}
+
+export {}
+`;
+	const byController = /* @__PURE__ */ new Map();
+	for (const r of routes) {
+		const arr = byController.get(r.controller) ?? [];
+		arr.push(r);
+		byController.set(r.controller, arr);
+	}
+	const schemaImports = /* @__PURE__ */ new Map();
+	const renderField = (schema, routeFilePath) => {
+		const alias = planSchemaImport(schema, routeFilePath, routesOutFile, schemaValidator, schemaImports);
+		return alias ? `import('zod').infer<typeof ${alias}>` : null;
+	};
+	const interfaces = [];
+	for (const [controller, methods] of byController) {
+		const lines = [`    interface ${controller} {`];
+		for (const m of methods) {
+			const urlParamsType = m.pathParams.length > 0 ? `{ ${m.pathParams.map((p) => `${p}: string`).join("; ")} }` : "{}";
+			const bodySchemaType = renderField(m.bodySchema, m.filePath);
+			const querySchemaType = renderField(m.querySchema, m.filePath);
+			const paramsType = renderField(m.paramsSchema, m.filePath) ?? urlParamsType;
+			const bodyType = bodySchemaType ?? "unknown";
+			const queryType = querySchemaType ?? renderQueryShape(m);
+			const docLines = renderQueryDocLines(m);
+			lines.push(`      /**`, `       * ${m.httpMethod} ${m.path}`, ...docLines.map((d) => `       * ${d}`), `       */`, `      ${m.method}: {`, `        params: ${paramsType}`, `        body: ${bodyType}`, `        query: ${queryType}`, `        response: unknown`, `      }`);
+		}
+		lines.push("    }");
+		interfaces.push(lines.join("\n"));
+	}
+	return `${ROUTES_HEADER}${renderSchemaImports(schemaImports)}
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace KickRoutes {
+${interfaces.join("\n")}
+  }
+}
+
+export {}
+`;
+}
+function renderQueryShape(m) {
+	if (m.queryFilterable === null) return "unknown";
+	const sortable = m.querySortable ?? [];
+	return `{ filter?: string | string[]; sort?: ${sortable.length > 0 ? sortable.flatMap((f) => [`'${f}'`, `'-${f}'`]).join(" | ") : "string"}; q?: string; page?: string; limit?: string }`;
+}
+function renderQueryDocLines(m) {
+	const lines = [];
+	if (m.queryFilterable && m.queryFilterable.length > 0) lines.push(`Filterable: ${m.queryFilterable.join(", ")}`);
+	if (m.querySortable && m.querySortable.length > 0) lines.push(`Sortable: ${m.querySortable.join(", ")}`);
+	if (m.querySearchable && m.querySearchable.length > 0) lines.push(`Searchable: ${m.querySearchable.join(", ")}`);
+	return lines;
+}
+/**
+* Plan a schema import for hoisting at the top of `routes.ts`. Returns
+* the alias the in-namespace code should use, or `null` if the schema
+* cannot be referenced (no validator configured, or source unresolvable).
+*/
+function planSchemaImport(schema, routeFilePath, routesOutFile, schemaValidator, imports) {
+	if (!schema || schemaValidator !== "zod") return null;
+	if (schema.source === null) return null;
+	const specifier = resolveSchemaImportSpecifier(schema.source, routeFilePath, routesOutFile);
+	if (specifier === "unknown") return null;
+	const key = `${specifier}::${schema.identifier}`;
+	let alias = imports.get(key)?.specifier;
+	if (!alias) {
+		alias = `_S${imports.size}`;
+		imports.set(key, {
+			identifier: schema.identifier,
+			specifier: alias
+		});
+	} else alias = imports.get(key).specifier;
+	return alias;
+}
+function renderSchemaImports(imports) {
+	if (imports.size === 0) return "";
+	const lines = [];
+	for (const [key, value] of imports) {
+		const [path] = key.split("::");
+		lines.push(`import type { ${value.identifier} as ${value.specifier} } from '${path}'`);
+	}
+	return lines.join("\n") + "\n";
+}
+/**
+* Compute the import specifier the generated `routes.d.ts` should use
+* to reach a schema declared either in the controller file (empty
+* string) or imported from elsewhere (relative path or bare module).
+*/
+function resolveSchemaImportSpecifier(source, routeFilePath, routesOutFile) {
+	if (source === null) return "unknown";
+	const routesDir = dirname(routesOutFile);
+	if (source === "") {
+		let rel = relative(routesDir, routeFilePath).split(sep).join("/");
+		rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+		if (!rel.startsWith(".")) rel = "./" + rel;
+		return rel;
+	}
+	if (!source.startsWith(".") && !source.startsWith("/")) return source;
+	let rel = relative(routesDir, resolve(dirname(routeFilePath), source)).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return rel;
+}
+//#endregion
+//#region src/typegen/builtin/routes.ts
+const kickRoutesTypegen = () => ({
+	id: "kick/routes",
+	outExtension: ".ts",
+	inputs: ["src/**/*.controller.ts", "src/**/*.module.ts"],
+	async generate(ctx) {
+		const scan = await ctx.getScanResult({
+			root: resolveSrcDir$1(ctx),
+			cwd: ctx.cwd,
+			envFile: resolveEnvFile$1(ctx)
+		});
+		const schemaValidator = ctx.config?.typegen?.schemaValidator ?? "zod";
+		const outFile = path.resolve(ctx.cwd, ".kickjs/types/kick__routes.ts");
+		return renderRoutes(scan.routes, outFile, schemaValidator);
+	}
+});
+function resolveSrcDir$1(ctx) {
+	return path.resolve(ctx.cwd, ctx.config?.typegen?.srcDir ?? "src");
+}
+function resolveEnvFile$1(ctx) {
+	const cfg = ctx.config?.typegen?.envFile;
+	if (cfg === false) return void 0;
+	return cfg;
+}
+//#endregion
+//#region src/typegen/render/env.ts
+const ENV_HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+/**
+* Render the `KickEnv` + `NodeJS.ProcessEnv` augmentation file from a
+* detected env schema. Returns `null` when no env file was discovered,
+* so the caller can skip emission entirely (rather than emitting an
+* empty augmentation that would shadow `KickEnv` to a useless `{}`).
+*/
+function renderEnv(env, envOutFile) {
+	if (!env) return null;
+	let rel = relative(dirname(envOutFile), env.filePath).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return `${ENV_HEADER}
+// Importing the schema as a type lets us infer its shape without
+// pulling in any runtime code. \`Awaited<>\` strips an accidental
+// Promise wrap on dynamic-imported defaults.
+import type _envSchema from '${rel}'
+
+// Local type alias — interfaces can only \`extend\` an identifier,
+// not an inline import expression, so we resolve the schema's
+// inferred shape into a named type first.
+type _KickEnvShape = import('zod').infer<typeof _envSchema>
+
+declare global {
+  /**
+   * Typed environment registry. Augmented from \`${env.relativePath}\`
+   * so \`@Value('PORT')\`, \`Env<'PORT'>\`, and \`process.env.PORT\` are
+   * all type-safe and autocomplete.
+   */
+  interface KickEnv extends _KickEnvShape {}
+
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace NodeJS {
+    /**
+     * Narrow \`process.env\` so known keys exist as \`string\` (the raw
+     * pre-Zod-coercion form). \`@Value\` and the \`ConfigService\` apply
+     * the schema's transforms internally; access \`process.env\` directly
+     * only when you need the raw string. Unknown keys still resolve to
+     * \`string | undefined\` via the base @types/node declaration.
+     */
+    interface ProcessEnv extends Record<keyof KickEnv, string> {}
+  }
+}
+
+export {}
+`;
+}
+//#endregion
+//#region src/typegen/builtin/env.ts
+const kickEnvTypegen = () => ({
+	id: "kick/env",
+	outExtension: ".ts",
+	inputs: [
+		"src/env.ts",
+		"src/**/env.ts",
+		"src/**/*.env.ts"
+	],
+	async generate(ctx) {
+		const envFile = resolveEnvFile(ctx);
+		if (envFile === false) return null;
+		const scan = await ctx.getScanResult({
+			root: resolveSrcDir(ctx),
+			cwd: ctx.cwd,
+			envFile
+		});
+		if (!scan.env) return null;
+		const outFile = path.resolve(ctx.cwd, ".kickjs/types/kick__env.ts");
+		return renderEnv(scan.env, outFile);
+	}
+});
+function resolveSrcDir(ctx) {
+	return path.resolve(ctx.cwd, ctx.config?.typegen?.srcDir ?? "src");
+}
+function resolveEnvFile(ctx) {
+	return ctx.config?.typegen?.envFile;
+}
+//#endregion
 //#region src/plugin/builtins.ts
 const builtinCliPlugins = [
 	defineCliPlugin({
@@ -3789,9 +4166,17 @@ const builtinCliPlugins = [
 	defineCliPlugin({
 		name: "kick/assets",
 		typegens: [kickAssetsTypegen()]
+	}),
+	defineCliPlugin({
+		name: "kick/routes",
+		typegens: [kickRoutesTypegen()]
+	}),
+	defineCliPlugin({
+		name: "kick/env",
+		typegens: [kickEnvTypegen()]
 	})
 ];
 //#endregion
 export { builtinCliPlugins, applyDisableFilter as n, runAllPluginTypegens as t };
 
-//# sourceMappingURL=builtins-caRjFvKz.mjs.map
+//# sourceMappingURL=builtins-B0dptoXq.mjs.map