@forinda/kickjs-cli 5.0.2 → 5.1.0

package/dist/typegen-8ZeA1B-X.mjs

@@ -0,0 +1,1532 @@
+/**
+ * @forinda/kickjs-cli v5.1.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { t as __exportAll } from "./rolldown-runtime-BM29JyaJ.mjs";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { globSync } from "glob";
+//#region src/typegen/scanner.ts
+/** Decorators that mark a class as DI-managed */
+const DECORATOR_NAMES = [
+	"Service",
+	"Controller",
+	"Repository",
+	"Injectable",
+	"Component",
+	"Module"
+];
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts"
+];
+const DEFAULT_EXCLUDES = [
+	"node_modules",
+	".kickjs",
+	"dist",
+	"build",
+	".test.",
+	".spec.",
+	".d.ts"
+];
+/**
+* Match a class-level decorator immediately followed by an exported
+* class declaration. Captures decorator name and class name.
+*/
+const DECORATED_CLASS_REGEX = new RegExp(String.raw`@(${DECORATOR_NAMES.join("|")})\s*\([^)]*\)` + String.raw`(?:\s*@[A-Z]\w*(?:\s*\([^)]*\))?)*` + String.raw`\s*export\s+(default\s+)?(?:abstract\s+)?class\s+(\w+)`, "g");
+/**
+* Match an exported class declaration that implements `AppModule`.
+* KickJS modules are not decorated — they implement the `AppModule`
+* interface — so the decorated-class scanner never picks them up. This
+* regex captures them by name so `ModuleToken` can be populated.
+*
+* Tolerates an `extends BaseClass` clause before `implements`, multiple
+* implements clauses (`implements Foo, AppModule`), and `default` exports.
+*/
+const APP_MODULE_CLASS_REGEX = new RegExp(String.raw`export\s+(default\s+)?(?:abstract\s+)?class\s+(\w+)` + String.raw`(?:\s+extends\s+\w+(?:<[^>]*>)?)?` + String.raw`\s+implements\s+[^{]*\bAppModule\b`, "g");
+/**
+* Match a `createToken<T>('name')` call with optional `export const X =`
+* or `const X =` prefix. Tolerates whitespace and the type parameter
+* being absent (`createToken('name')`).
+*/
+const CREATE_TOKEN_REGEX = /(?:export\s+)?const\s+(\w+)\s*(?::\s*[^=]+)?=\s*createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/**
+* Match a bare `createToken<T>('name')` call (no const assignment) so
+* we still pick up dynamically-used tokens.
+*/
+const BARE_CREATE_TOKEN_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/** Match `@Inject('literal')` — only literals; computed args are skipped */
+const INJECT_LITERAL_REGEX = /@Inject\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/**
+* Match the start of a `defineAdapter(...)` or `definePlugin(...)` call,
+* tolerating optional `<TConfig, TExtra>` generics. Captures the helper
+* name. The callsite's first-arg object is parsed forward via
+* `findBalancedClose` so nested objects/parens don't confuse us.
+*/
+const DEFINE_HELPER_START = /\b(defineAdapter|definePlugin)\s*(?:<[^>]*>)?\s*\(/g;
+/**
+* Match a class declaration whose `implements` clause includes `AppAdapter`.
+* Captures the class name. Used to pick up the (rare, post-defineAdapter)
+* legacy class-style adapters so their literal `name = '...'` field can
+* still feed `KickJsPluginRegistry`.
+*/
+const APP_ADAPTER_CLASS_REGEX = new RegExp(String.raw`export\s+(?:default\s+)?(?:abstract\s+)?class\s+(\w+)` + String.raw`(?:\s+extends\s+\w+(?:<[^>]*>)?)?` + String.raw`\s+implements\s+[^{]*\bAppAdapter\b`, "g");
+/** Match a string-literal `name = '...'` field on a class body. */
+const CLASS_NAME_FIELD_REGEX = /\bname\s*(?::\s*[^=]+)?=\s*['"`]([^'"`]+)['"`]/;
+/**
+* Match the start of a `defineAugmentation('Name', ...)` call. Captures
+* the literal name. The optional second-arg object is parsed forward so
+* `description` / `example` can be pulled out.
+*/
+const DEFINE_AUGMENTATION_START = /\bdefineAugmentation\s*\(\s*['"`]([^'"`]+)['"`]\s*(,\s*\{)?/g;
+/**
+* Locate the start of a route decorator: `@Get(`, `@Post(`, etc.
+* Used by `extractRoutesFromSource`; the rest of the route declaration
+* (balanced parens, stacked decorators, method name) is parsed by walking
+* the source forward from this match. The previous all-in-one regex
+* couldn't handle nested parens in stacked decorator args (e.g.
+* `@ApiResponse(201, { schema: z.object({ id: z.string() }) })`) — see
+* forinda/kick-js#108.
+*/
+const ROUTE_DECORATOR_START = new RegExp(String.raw`@(${[
+	"Get",
+	"Post",
+	"Put",
+	"Delete",
+	"Patch"
+].join("|")})\s*\(`, "g");
+/**
+* Find the index of the `)` that balances the `(` at `openPos`.
+* Returns -1 if no matching `)` exists. Counts balanced parens only;
+* does not understand string literals, so a `(` or `)` inside a string
+* inside the args will skew the depth counter (matches the limitation
+* of `extractRouteOptionsArg`).
+*/
+function findBalancedClose(text, openPos) {
+	let depth = 1;
+	for (let i = openPos + 1; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "(") depth++;
+		else if (ch === ")") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Walk forward from the end of a route decorator past any stacked
+* decorators (`@ApiOperation(...)`, `@ApiResponse(...)`, `@Middleware(fn)`,
+* etc.), then past optional `public`/`private`/`protected` and `async`,
+* and capture the method name + opening `(`.
+*
+* Returns the method name and the position immediately after the method's
+* opening `(`, or `null` if the source between the route decorator and
+* the method body doesn't fit the expected shape.
+*/
+function readMethodAfterDecorators(block, startPos) {
+	let pos = startPos;
+	while (pos < block.length) {
+		while (pos < block.length && /\s/.test(block[pos])) pos++;
+		if (block[pos] !== "@") break;
+		const decMatch = block.slice(pos).match(/^@([A-Z]\w*)/);
+		if (!decMatch) break;
+		pos += decMatch[0].length;
+		while (pos < block.length && /\s/.test(block[pos])) pos++;
+		if (block[pos] === "(") {
+			const close = findBalancedClose(block, pos);
+			if (close < 0) return null;
+			pos = close + 1;
+		}
+	}
+	while (pos < block.length && /\s/.test(block[pos])) pos++;
+	for (const mod of [
+		"public",
+		"private",
+		"protected"
+	]) if (block.slice(pos, pos + mod.length) === mod && /\s/.test(block.charAt(pos + mod.length))) {
+		pos += mod.length;
+		while (pos < block.length && /\s/.test(block[pos])) pos++;
+		break;
+	}
+	if (block.slice(pos, pos + 5) === "async" && /\s/.test(block.charAt(pos + 5))) {
+		pos += 5;
+		while (pos < block.length && /\s/.test(block[pos])) pos++;
+	}
+	const methodMatch = block.slice(pos).match(/^([a-zA-Z_]\w*)\s*\(/);
+	if (!methodMatch) return null;
+	return {
+		methodName: methodMatch[1],
+		endPos: pos + methodMatch[0].length
+	};
+}
+/** Extract `:placeholder` segments from an Express route path */
+function extractPathParams(path) {
+	return (path.match(/:([a-zA-Z_]\w*)/g) ?? []).map((m) => m.slice(1));
+}
+/**
+* Extract a bare identifier value from a single field in an object literal
+* embedded in a string. Returns `null` if the field is missing or its value
+* isn't a bare identifier (e.g. an inline object, function call, etc.).
+*
+* Example: `extractObjectFieldIdentifier("'/' , { body: createTaskSchema }", 'body')`
+* returns `'createTaskSchema'`.
+*/
+function extractObjectFieldIdentifier(text, field) {
+	const m = new RegExp(String.raw`\b${field}\s*:\s*([A-Za-z_$][\w$]*)`, "g").exec(text);
+	if (!m) return null;
+	return m[1];
+}
+/**
+* Resolve a bare identifier to its module source by inspecting the file's
+* top-level imports and same-file `const` declarations.
+*
+* - `import { X } from './path'` → returns `'./path'`
+* - `import X from './path'` (default import) → returns `'./path'`
+* - `import * as X from './path'` → returns `'./path'`
+* - `const X = z.object(...)` (same file) → returns `null` (caller emits a self-import)
+*
+* Returns `null` when the identifier cannot be resolved.
+*/
+function resolveImportSource(source, identifier) {
+	const named = new RegExp(String.raw`import\s*(?:type\s+)?\{[^}]*\b${identifier}\b[^}]*\}\s*from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (named) return named[1];
+	const def = new RegExp(String.raw`import\s+(?:type\s+)?${identifier}\s+from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (def) return def[1];
+	const ns = new RegExp(String.raw`import\s*\*\s*as\s+${identifier}\s+from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (ns) return ns[1];
+	if (new RegExp(String.raw`(?:^|\n)\s*(?:export\s+)?const\s+${identifier}\b`).test(source)) return "";
+	return null;
+}
+/**
+* Extract whitelist arrays from an `@ApiQueryParams(...)` decorator
+* within `decoratorBlock`. Handles two forms:
+*
+* - Inline literal: `@ApiQueryParams({ filterable: ['a', 'b'], ... })`
+* - Const reference: `@ApiQueryParams(SOME_CONFIG)` — looks up
+*   `const SOME_CONFIG = { ... }` in the same file (`fullSource`).
+*
+* Returns `null` if no `@ApiQueryParams` is present. Returns
+* `{ filterable: [], sortable: [], searchable: [] }` if the decorator
+* is present but no fields could be statically extracted (opaque
+* imports, column-object configs, function calls, etc.).
+*/
+function extractApiQueryParams(decoratorBlock, fullSource) {
+	const apiMatch = /@ApiQueryParams\s*\(\s*([\s\S]*?)\s*\)\s*$/.exec(decoratorBlock);
+	if (!apiMatch) {
+		const loose = /@ApiQueryParams\s*\(([\s\S]*?)\)/.exec(decoratorBlock);
+		if (!loose) return null;
+		return parseApiQueryParamsArg(loose[1].trim(), fullSource);
+	}
+	return parseApiQueryParamsArg(apiMatch[1].trim(), fullSource);
+}
+function parseApiQueryParamsArg(arg, fullSource) {
+	if (arg.startsWith("{")) return parseInlineConfigLiteral(arg);
+	const idMatch = /^([A-Za-z_]\w*)/.exec(arg);
+	if (idMatch) {
+		const ident = idMatch[1];
+		const constMatch = new RegExp(String.raw`const\s+${ident}\s*(?::\s*[^=]+)?=\s*(\{[\s\S]*?\n\})`, "m").exec(fullSource);
+		if (constMatch) return parseInlineConfigLiteral(constMatch[1]);
+	}
+	return {
+		filterable: [],
+		sortable: [],
+		searchable: []
+	};
+}
+/** Extract a string array literal for one config key from an inline object literal */
+function extractStringArray(literal, key) {
+	const m = new RegExp(String.raw`${key}\s*:\s*\[([\s\S]*?)\]`).exec(literal);
+	if (!m) return [];
+	return Array.from(m[1].matchAll(/['"`]([^'"`]+)['"`]/g)).map((x) => x[1]);
+}
+/** Parse an inline `{ filterable: [...], sortable: [...], searchable: [...] }` literal */
+function parseInlineConfigLiteral(literal) {
+	return {
+		filterable: extractStringArray(literal, "filterable"),
+		sortable: extractStringArray(literal, "sortable"),
+		searchable: extractStringArray(literal, "searchable")
+	};
+}
+/** Recursively walk a directory and yield matching file paths */
+async function walk(dir, opts) {
+	const exts = opts.extensions ?? DEFAULT_EXTENSIONS;
+	const excludes = opts.exclude ?? DEFAULT_EXCLUDES;
+	const out = [];
+	let entries;
+	try {
+		entries = await readdir(dir, {
+			withFileTypes: true,
+			encoding: "utf-8"
+		});
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		const rel = relative(opts.cwd, full);
+		if (excludes.some((ex) => rel.includes(ex))) continue;
+		if (entry.isDirectory()) out.push(...await walk(full, opts));
+		else if (entry.isFile()) {
+			if (exts.some((ext) => entry.name.endsWith(ext))) out.push(full);
+		}
+	}
+	return out;
+}
+/** Compute the forward-slash relative path used in scanner output */
+function toRelative(filePath, cwd) {
+	return relative(cwd, filePath).split(sep).join("/");
+}
+/** Extract decorated classes from a single source file */
+function extractClassesFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	DECORATED_CLASS_REGEX.lastIndex = 0;
+	let match;
+	while ((match = DECORATED_CLASS_REGEX.exec(source)) !== null) {
+		const [, decorator, defaultMarker, className] = match;
+		out.push({
+			className,
+			decorator,
+			filePath,
+			relativePath: relPath,
+			isDefault: Boolean(defaultMarker)
+		});
+	}
+	APP_MODULE_CLASS_REGEX.lastIndex = 0;
+	let modMatch;
+	while ((modMatch = APP_MODULE_CLASS_REGEX.exec(source)) !== null) {
+		const [, defaultMarker, className] = modMatch;
+		if (out.some((c) => c.className === className && c.filePath === filePath)) continue;
+		out.push({
+			className,
+			decorator: "Module",
+			filePath,
+			relativePath: relPath,
+			isDefault: Boolean(defaultMarker)
+		});
+	}
+	return out;
+}
+/** Extract `createToken('name')` definitions from a single source file */
+function extractTokensFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	CREATE_TOKEN_REGEX.lastIndex = 0;
+	let match;
+	while ((match = CREATE_TOKEN_REGEX.exec(source)) !== null) {
+		const [full, variable, name] = match;
+		seen.add(full);
+		out.push({
+			name,
+			variable,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	BARE_CREATE_TOKEN_REGEX.lastIndex = 0;
+	while ((match = BARE_CREATE_TOKEN_REGEX.exec(source)) !== null) {
+		if (seen.has(match[0])) continue;
+		out.push({
+			name: match[1],
+			variable: null,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Extract route handlers from a source file.
+*
+* For each decorated class in `classesInFile`, slices the source from
+* the class declaration to the next class (or EOF) and runs the route
+* decorator regex within that slice. The result is a list of routes
+* tagged with their owning controller.
+*
+* Heuristic note: this assumes classes are not nested. KickJS controllers
+* are top-level by convention so this holds in practice.
+*/
+function extractRoutesFromSource(source, filePath, cwd, classesInFile) {
+	const out = [];
+	if (classesInFile.length === 0) return out;
+	const relPath = toRelative(filePath, cwd);
+	const positions = [];
+	for (const cls of classesInFile) {
+		const m = new RegExp(String.raw`class\s+${cls.className}\b`).exec(source);
+		if (m?.index !== void 0) positions.push({
+			cls,
+			start: m.index
+		});
+	}
+	positions.sort((a, b) => a.start - b.start);
+	for (let i = 0; i < positions.length; i++) {
+		const { cls, start } = positions[i];
+		const end = i + 1 < positions.length ? positions[i + 1].start : source.length;
+		const block = source.slice(start, end);
+		ROUTE_DECORATOR_START.lastIndex = 0;
+		let startMatch;
+		while ((startMatch = ROUTE_DECORATOR_START.exec(block)) !== null) {
+			const verb = startMatch[1];
+			const decoratorStart = startMatch.index;
+			const openParen = ROUTE_DECORATOR_START.lastIndex - 1;
+			const closeParen = findBalancedClose(block, openParen);
+			if (closeParen < 0) continue;
+			const routeArgs = block.slice(openParen + 1, closeParen);
+			const pathLiteralMatch = routeArgs.match(/^\s*['"`]([^'"`]*)['"`]/);
+			const path = pathLiteralMatch && pathLiteralMatch[1].length > 0 ? pathLiteralMatch[1] : "/";
+			const methodInfo = readMethodAfterDecorators(block, closeParen + 1);
+			if (!methodInfo) continue;
+			const { methodName, endPos } = methodInfo;
+			ROUTE_DECORATOR_START.lastIndex = endPos;
+			const apiQp = extractApiQueryParams(block.slice(decoratorStart, endPos), source);
+			const bodyId = extractObjectFieldIdentifier(routeArgs, "body");
+			const queryId = extractObjectFieldIdentifier(routeArgs, "query");
+			const paramsId = extractObjectFieldIdentifier(routeArgs, "params");
+			out.push({
+				controller: cls.className,
+				method: methodName,
+				httpMethod: verb.toUpperCase(),
+				path,
+				pathParams: extractPathParams(path),
+				queryFilterable: apiQp?.filterable ?? null,
+				querySortable: apiQp?.sortable ?? null,
+				querySearchable: apiQp?.searchable ?? null,
+				bodySchema: bodyId ? {
+					identifier: bodyId,
+					source: resolveImportSource(source, bodyId)
+				} : null,
+				querySchema: queryId ? {
+					identifier: queryId,
+					source: resolveImportSource(source, queryId)
+				} : null,
+				paramsSchema: paramsId ? {
+					identifier: paramsId,
+					source: resolveImportSource(source, paramsId)
+				} : null,
+				filePath,
+				relativePath: relPath
+			});
+		}
+	}
+	return out;
+}
+/** Extract `@Inject('literal')` calls from a single source file */
+function extractInjectsFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	INJECT_LITERAL_REGEX.lastIndex = 0;
+	let match;
+	while ((match = INJECT_LITERAL_REGEX.exec(source)) !== null) out.push({
+		name: match[1],
+		filePath,
+		relativePath: relPath
+	});
+	return out;
+}
+/**
+* Extract the bounds of an object literal that begins at `openBracePos`
+* (the index of the `{` character). Returns the index of the matching `}`
+* or -1 if no match is found. Counts balanced braces only — does not
+* understand string literals so a `{` or `}` inside a string inside the
+* object will skew the depth counter (matches `findBalancedClose`).
+*/
+function findBalancedBrace(text, openBracePos) {
+	let depth = 1;
+	for (let i = openBracePos + 1; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Extract plugins/adapters declared via `defineAdapter({ name: '...' })`
+* or `definePlugin({ name: '...' })` calls and via class-style adapters
+* (`class XxxAdapter implements AppAdapter` with a string-literal `name`
+* field).
+*
+* Only the literal `name:` field feeds the result — the symbol on the LHS
+* is irrelevant since `dependsOn` references the runtime name.
+*/
+function extractPluginsAndAdaptersFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	DEFINE_HELPER_START.lastIndex = 0;
+	let helperMatch;
+	while ((helperMatch = DEFINE_HELPER_START.exec(source)) !== null) {
+		const helper = helperMatch[1];
+		const openParen = DEFINE_HELPER_START.lastIndex - 1;
+		const closeParen = findBalancedClose(source, openParen);
+		if (closeParen < 0) continue;
+		const callArgs = source.slice(openParen + 1, closeParen);
+		const nameMatch = /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(callArgs);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `${helper}::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: helper === "definePlugin" ? "plugin" : "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	APP_ADAPTER_CLASS_REGEX.lastIndex = 0;
+	let classMatch;
+	while ((classMatch = APP_ADAPTER_CLASS_REGEX.exec(source)) !== null) {
+		const classStart = classMatch.index;
+		const bracePos = source.indexOf("{", classStart);
+		if (bracePos < 0) continue;
+		const closeBrace = findBalancedBrace(source, bracePos);
+		if (closeBrace < 0) continue;
+		const body = source.slice(bracePos + 1, closeBrace);
+		const nameMatch = CLASS_NAME_FIELD_REGEX.exec(body);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `class::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Extract `defineAugmentation('Name', { description, example })` calls
+* from a source file. The metadata object is optional — when absent both
+* `description` and `example` resolve to `null`.
+*/
+function extractAugmentationsFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	DEFINE_AUGMENTATION_START.lastIndex = 0;
+	let match;
+	while ((match = DEFINE_AUGMENTATION_START.exec(source)) !== null) {
+		const name = match[1];
+		let description = null;
+		let example = null;
+		if (match[2]) {
+			const bracePos = source.indexOf("{", match.index + match[0].length - 1);
+			if (bracePos >= 0) {
+				const closeBrace = findBalancedBrace(source, bracePos);
+				if (closeBrace >= 0) {
+					const body = source.slice(bracePos + 1, closeBrace);
+					description = readStringField(body, "description");
+					example = readStringField(body, "example");
+				}
+			}
+		}
+		out.push({
+			name,
+			description,
+			example,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Pull a string-valued field out of a JS object-literal body, respecting
+* the opening quote so the value isn't truncated at the first foreign
+* quote character. Handles backslash escapes inside the literal.
+*
+* Why a custom parser instead of one regex per delimiter: real-world
+* `defineAugmentation` calls embed all three quote characters at once
+* — backtick template literals carrying TS shapes like
+* `'free' | 'pro'` (single quotes) AND `\`ctx.get(...)\`` (escaped
+* backticks). A character-class regex like `[^'"`]+` truncates on the
+* first foreign quote it sees. This walker scans char-by-char from
+* the matched delimiter and only stops on the matching one.
+*/
+function readStringField(body, field) {
+	const m = new RegExp(`\\b${field}\\s*:\\s*(['"\`])`, "g").exec(body);
+	if (!m) return null;
+	const quote = m[1];
+	const start = m.index + m[0].length;
+	let i = start;
+	let raw = null;
+	while (i < body.length) {
+		const ch = body[i];
+		if (ch === "\\") {
+			i += 2;
+			continue;
+		}
+		if (ch === quote) {
+			raw = body.slice(start, i);
+			break;
+		}
+		i++;
+	}
+	if (raw === null) return null;
+	return raw.replace(/\\(.)/g, (_m, c) => {
+		if (c === "n") return "\n";
+		if (c === "t") return "	";
+		if (c === "r") return "\r";
+		return c;
+	});
+}
+/**
+* Default search order for the env schema file. Newer projects keep
+* the schema under `src/config/` so the framework's "config" concept
+* has a single home; older scaffolds dropped it at `src/env.ts` (kept
+* here for back-compat). The first match wins.
+*/
+const DEFAULT_ENV_FILE_CANDIDATES = [
+	"src/config/index.ts",
+	"src/config/env.ts",
+	"src/config.ts",
+	"src/env.ts"
+];
+/**
+* Look for an env schema file. When `envFile` is the string default
+* (`'src/env.ts'`) or omitted, every entry in `DEFAULT_ENV_FILE_CANDIDATES`
+* is tried in order. When the caller passes an explicit path, only that
+* path is tried (so projects can opt out of the search by setting
+* `kick.config.ts → typegen.envFile`).
+*
+* Returns a `DiscoveredEnv` if the file exists and contains both a
+* `defineEnv(...)` call and a default export — the two markers we
+* need before it's safe to emit `import type schema from '...'` in
+* the generator. Returns `null` for any other state (no candidate
+* found, no defineEnv, no default export) so the generator skips env
+* typing silently.
+*/
+async function detectEnvFile(cwd, envFile) {
+	const candidates = envFile === "src/env.ts" ? DEFAULT_ENV_FILE_CANDIDATES : [envFile];
+	for (const candidate of candidates) {
+		const abs = resolve(cwd, candidate);
+		let source;
+		try {
+			source = await readFile(abs, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!/\bdefineEnv\s*\(/.test(source)) continue;
+		if (!/export\s+default\b/.test(source)) continue;
+		return {
+			filePath: abs,
+			relativePath: toRelative(abs, cwd)
+		};
+	}
+	return null;
+}
+/** Detect duplicate class names across files */
+function findCollisions(classes) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const cls of classes) {
+		const arr = groups.get(cls.className) ?? [];
+		arr.push(cls);
+		groups.set(cls.className, arr);
+	}
+	const collisions = [];
+	for (const [className, group] of groups) if (new Set(group.map((c) => c.filePath)).size > 1) collisions.push({
+		className,
+		classes: group
+	});
+	collisions.sort((a, b) => a.className.localeCompare(b.className));
+	return collisions;
+}
+/**
+* Scan a project for decorated classes, createToken definitions, and
+* `@Inject` literal usages.
+*/
+async function scanProject(opts) {
+	const files = await walk(resolve(opts.root), opts);
+	const classes = [];
+	const routes = [];
+	const tokens = [];
+	const injects = [];
+	const pluginsAndAdapters = [];
+	const augmentations = [];
+	const sources = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		let source;
+		try {
+			source = await readFile(file, "utf-8");
+		} catch {
+			continue;
+		}
+		sources.set(file, source);
+		classes.push(...extractClassesFromSource(source, file, opts.cwd));
+		tokens.push(...extractTokensFromSource(source, file, opts.cwd));
+		injects.push(...extractInjectsFromSource(source, file, opts.cwd));
+		pluginsAndAdapters.push(...extractPluginsAndAdaptersFromSource(source, file, opts.cwd));
+		augmentations.push(...extractAugmentationsFromSource(source, file, opts.cwd));
+	}
+	for (const [file, source] of sources) {
+		const classesInFile = classes.filter((c) => c.filePath === file);
+		routes.push(...extractRoutesFromSource(source, file, opts.cwd, classesInFile));
+	}
+	classes.sort((a, b) => {
+		if (a.className !== b.className) return a.className.localeCompare(b.className);
+		return a.relativePath.localeCompare(b.relativePath);
+	});
+	tokens.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	injects.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	routes.sort((a, b) => a.controller.localeCompare(b.controller) || a.method.localeCompare(b.method));
+	pluginsAndAdapters.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	augmentations.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	return {
+		classes,
+		routes,
+		tokens,
+		injects,
+		collisions: findCollisions(classes),
+		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts"),
+		pluginsAndAdapters,
+		augmentations
+	};
+}
+//#endregion
+//#region src/typegen/asset-types.ts
+/**
+* Walks every `assetMap` entry's source directory + emits a typed
+* `KickAssets` ambient augmentation (assets-plan.md PR 4). Generates
+* `.kickjs/types/assets.d.ts` so adopters get autocomplete on
+* `assets.<namespace>.<key>` and `@Asset('<namespace>/<key>')`.
+*
+* Pure module — no side effects beyond what the caller does with the
+* returned content. Mirrors the shape of `renderPlugins` /
+* `renderRegistry` in the generator so the typegen output stays
+* consistent across surfaces.
+*
+* @module @forinda/kickjs-cli/typegen/asset-types
+*/
+function discoverAssets(assetMap, cwd) {
+	if (!assetMap) return {
+		entries: [],
+		count: 0
+	};
+	const seen = /* @__PURE__ */ new Map();
+	for (const [namespace, entry] of Object.entries(assetMap)) {
+		if (!entry || typeof entry.src !== "string") continue;
+		const srcAbs = resolve(cwd, entry.src);
+		if (!isDir(srcAbs)) continue;
+		const matches = globSync(entry.glob ?? "**/*", {
+			cwd: srcAbs,
+			nodir: true,
+			dot: false,
+			posix: true
+		});
+		matches.sort();
+		for (const rel of matches) {
+			const key = stripExt(rel);
+			const logical = `${namespace}/${key}`;
+			seen.set(logical, {
+				namespace,
+				key
+			});
+		}
+	}
+	return {
+		entries: [...seen.values()],
+		count: seen.size
+	};
+}
+function renderAssetTypes(discovered) {
+	const HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+	if (discovered.entries.length === 0) return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * (No assetMap entries discovered yet — declare with
+   *  \`assetMap: { name: { src: 'src/...' } }\` in kick.config.ts.)
+   */
+  interface KickAssets {}
+}
+
+export {}
+`;
+	const tree = {};
+	for (const entry of discovered.entries) {
+		const path = `${entry.namespace}/${entry.key}`.split("/");
+		let node = tree;
+		for (let i = 0; i < path.length - 1; i++) {
+			const part = path[i];
+			const existing = node[part];
+			if (existing === LEAF) {
+				const promoted = {};
+				node[part] = promoted;
+				node = promoted;
+			} else {
+				if (!existing) node[part] = {};
+				node = node[part];
+			}
+		}
+		const leaf = path[path.length - 1];
+		if (typeof node[leaf] === "object") continue;
+		node[leaf] = LEAF;
+	}
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * Each leaf is a \`() => string\` thunk that returns the resolved
+   * absolute path for the file in the current run mode (dev → src,
+   * prod → dist).
+   */
+  interface KickAssets {
+${renderTree(tree, "    ")}
+  }
+}
+
+export {}
+`;
+}
+const LEAF = Symbol("asset-leaf");
+function renderTree(node, indent) {
+	const keys = Object.keys(node).sort();
+	const lines = [];
+	for (const key of keys) {
+		const child = node[key];
+		const safeKey = isIdentifier(key) ? key : JSON.stringify(key);
+		if (child === LEAF) lines.push(`${indent}${safeKey}: () => string`);
+		else {
+			lines.push(`${indent}${safeKey}: {`);
+			lines.push(renderTree(child, `${indent}  `));
+			lines.push(`${indent}}`);
+		}
+	}
+	return lines.join("\n");
+}
+function isIdentifier(str) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(str);
+}
+function isDir(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function stripExt(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
+}
+//#endregion
+//#region src/typegen/generator.ts
+/**
+* Generates `.d.ts` files inside `.kickjs/types/` from the discovered
+* decorated classes and DI tokens. Pattern modeled on React Router's
+* `.react-router/types/` directory.
+*
+* Outputs:
+* - `.kickjs/types/registry.d.ts` — module augmentation for `KickJsRegistry`
+*    that gives `container.resolve('UserService')` the right return type.
+* - `.kickjs/types/services.d.ts` — string-literal union of all known
+*   service-style tokens for tooling autocomplete.
+* - `.kickjs/types/modules.d.ts` — string-literal union of discovered
+*   module class names.
+* - `.kickjs/types/index.d.ts` — re-exports the above (single import target).
+* - `.kickjs/.gitignore` — gitignores the whole folder so generated files
+*   never get committed.
+*
+* ## Collision behaviour
+*
+* If `findCollisions()` returns any duplicate class names:
+* - **Default (`allowDuplicates: false`)** — `generateTypes` throws a
+*   `TokenCollisionError` with a clear message listing every conflicting
+*   file. The caller (CLI) prints it and exits non-zero. Nothing is
+*   written to disk.
+* - **`allowDuplicates: true`** — colliding classes are auto-namespaced
+*   by their relative file path so the registry keys become e.g.
+*   `'modules/users/UserService'` instead of `'UserService'`. Non-colliding
+*   classes still get bare `'ClassName'` keys (smart default).
+*
+* @module @forinda/kickjs-cli/typegen/generator
+*/
+/** Header written to every generated file */
+const HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+/** Decorators whose classes participate in the DI registry augmentation */
+const REGISTRY_DECORATORS = new Set([
+	"Service",
+	"Repository",
+	"Injectable",
+	"Component"
+]);
+/** Thrown by `generateTypes` when collisions are found and not allowed */
+var TokenCollisionError = class extends Error {
+	collisions;
+	constructor(collisions) {
+		super(formatCollisionMessage(collisions));
+		this.name = "TokenCollisionError";
+		this.collisions = collisions;
+	}
+};
+/** Build a human-readable message describing every collision */
+function formatCollisionMessage(collisions) {
+	const lines = ["kick typegen: token collision detected"];
+	for (const c of collisions) {
+		lines.push("");
+		lines.push(`  ${c.classes.length} classes named '${c.className}':`);
+		for (const cls of c.classes) lines.push(`    - ${cls.relativePath}`);
+	}
+	lines.push("");
+	lines.push("Resolutions:");
+	lines.push("  (a) Rename one of the classes");
+	lines.push("  (b) Use createToken<T>('namespaced/Name') and import the token explicitly — see @forinda/kickjs");
+	lines.push("  (c) Pass --allow-duplicates to namespace the registry keys automatically");
+	lines.push("      (e.g. 'modules/users/UserService' instead of 'UserService')");
+	return lines.join("\n");
+}
+/** Compute the module specifier (without extension) used inside `import('...')` */
+function importSpecifierFor(targetFile, fromFile) {
+	let rel = relative(dirname(fromFile), targetFile).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return rel;
+}
+/**
+* Build the namespaced registry key for a colliding class.
+* Strips the `src/` prefix and the file extension, then appends the
+* class name. Example: `src/modules/users/user.service.ts` + `UserService`
+* → `modules/users/UserService`.
+*/
+function namespacedKeyFor(cls) {
+	const parts = cls.relativePath.replace(/^src\//, "").replace(/\.(ts|tsx|mts|cts)$/i, "").split("/");
+	parts.pop();
+	const ns = parts.join("/");
+	return ns ? `${ns}/${cls.className}` : cls.className;
+}
+/**
+* Render the `KickJsRegistry` module augmentation. Each entry maps a
+* string token to the imported class type.
+*
+* Default-exported classes are imported as `import('...').default`.
+*
+* `collidingNames` lists class names that should be auto-namespaced;
+* everything else gets a bare key.
+*/
+function renderRegistry(classes, outFile, collidingNames) {
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const c of classes) {
+		if (!REGISTRY_DECORATORS.has(c.decorator)) continue;
+		const key = collidingNames.has(c.className) ? namespacedKeyFor(c) : c.className;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const spec = importSpecifierFor(c.filePath, outFile);
+		const ref = c.isDefault ? `import('${spec}').default` : `import('${spec}').${c.className}`;
+		entries.push(`    '${key}': ${ref}`);
+	}
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  interface KickJsRegistry {
+${entries.length ? entries.join("\n") : "    // (no services discovered yet — run `kick g service <name>` to add one)"}
+  }
+}
+
+export {}
+`;
+}
+/** Render a string-literal union type containing the given names */
+function renderUnion(typeName, names, emptyComment) {
+	if (names.length === 0) return `${HEADER}
+// ${emptyComment}
+export type ${typeName} = never
+`;
+	return `${HEADER}
+export type ${typeName} =
+${[...new Set(names)].sort().map((n) => `  | '${n}'`).join("\n")}
+`;
+}
+/** Render the barrel index that re-exports the union types */
+function renderIndex(includeEnv) {
+	return `${HEADER}
+export type { ServiceToken } from './services'
+export type { ModuleToken } from './modules'
+
+// The registry, routes, plugins, assets, and env augmentations are
+// loaded as side-effects — importing this file (or having it on
+// tsconfig include) is enough for \`container.resolve()\`,
+// \`Ctx<KickRoutes.UserController['getUser']>\`,
+// \`dependsOn: ['TenantAdapter']\`, \`assets.mails.welcome()\`, and
+// \`@Value('PORT')\` to resolve.
+import './registry'
+import './routes'
+import './plugins'
+import './augmentations'
+import './assets'
+${includeEnv ? "import './env'\n" : ""}`;
+}
+/**
+* Render the `query` field's TypeScript type for a single route.
+*
+* - When `@ApiQueryParams` is absent (`queryFilterable === null`), emits
+*   `unknown` so the user gets nothing extra.
+* - When the decorator is present, emits an object literal whose keys
+*   are the standard query string keys (`filter`, `sort`, `q`, `page`,
+*   `limit`). `sort` is narrowed to a string-literal union of allowed
+*   field names with optional `-` direction prefix.
+*/
+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 }`;
+}
+/** Render JSDoc lines summarising the @ApiQueryParams whitelist */
+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).
+*
+* Aliases are unique per (alias-counter) so two schemas named
+* `createTaskSchema` from different modules don't collide.
+*/
+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;
+}
+/** Build the `import type { ... } from '...'` lines for hoisted schema imports */
+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 name).
+*
+* - Bare module names (`zod`, `@scope/pkg`) are returned as-is.
+* - Relative paths (`./users.dto`, `../shared/schema`) are resolved
+*   against the controller's file path, then re-relativised against the
+*   directory containing `routes.d.ts`.
+* - Empty string (same-file schema) becomes a relative path from the
+*   `routes.d.ts` directory back to the controller file.
+*/
+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;
+}
+/**
+* Render the `KickEnv` + `NodeJS.ProcessEnv` augmentation file from a
+* detected env schema. Mirrors the routes.ts pattern: emits as a `.ts`
+* file (not `.d.ts`) so the top-level `import type schema from '...'`
+* actually resolves under `moduleResolution: 'bundler'`.
+*
+* Returns `null` when no env file was discovered, so the caller can
+* skip writing the file altogether (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 `${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 {}
+`;
+}
+/**
+* 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 `${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 `${HEADER}${renderSchemaImports(schemaImports)}
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace KickRoutes {
+${interfaces.join("\n")}
+  }
+}
+
+export {}
+`;
+}
+/**
+* Render the `KickJsPluginRegistry` augmentation. Each entry maps the
+* literal `name` field of a plugin/adapter to a marker type (the
+* registry value isn't load-bearing at runtime — `dependsOn` only cares
+* about `keyof`, so any non-`never` type works). We emit `'plugin'` /
+* `'adapter'` strings so DevTools can later read the registry to tell
+* the kinds apart without a second source of truth.
+*
+* When the project has no discoverable plugins/adapters, the augmentation
+* is intentionally empty rather than skipped so the `keyof` constraint
+* resolves to `never` (which is harmless — `dependsOn: []` still works).
+*/
+function renderPlugins(items) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const entries = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)).map((item) => `    '${item.name}': '${item.kind}'`).join("\n");
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every plugin/adapter \`name\` discovered in the project. The
+   * value type is the kind tag (\`'plugin'\` or \`'adapter'\`); the
+   * \`keyof\` of this interface narrows \`dependsOn\` so misspelled deps
+   * become compile errors instead of boot-time \`MissingMountDepError\`.
+   */
+  interface KickJsPluginRegistry {
+${entries ? entries : "    // (no plugins/adapters discovered yet — `defineAdapter`/`definePlugin` calls feed this)"}
+  }
+}
+
+export {}
+`;
+}
+/**
+* Render the augmentation manifest — one block per `defineAugmentation`
+* call discovered in the project. The output is a `.d.ts` file that
+* does nothing at runtime but acts as in-IDE documentation: adopters
+* jumping into it see every interface their plugins offer for
+* augmentation, alongside any `description` / `example` the plugin
+* authors provided.
+*/
+function renderAugmentations(items) {
+	if (items.length === 0) return `${HEADER}
+// No augmentations discovered.
+//
+// Plugins advertise augmentable interfaces via:
+//
+//   import { defineAugmentation } from '@forinda/kickjs'
+//   defineAugmentation('FeatureFlags', {
+//     description: 'Feature flag shape consumed by FlagsPlugin',
+//     example: '{ beta: boolean; rolloutPercentage: number }',
+//   })
+//
+// See \`docs/guide/typegen.md#augmentations\` for the full pattern.
+export {}
+`;
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const blocks = [];
+	for (const item of [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))) {
+		const docLines = [];
+		if (item.description) for (const line of item.description.split("\n")) docLines.push(` * ${line}`);
+		if (item.example) {
+			docLines.push(` * @example`, ` * \`\`\`ts`);
+			for (const line of item.example.split("\n")) docLines.push(` * ${line}`);
+			docLines.push(` * \`\`\``);
+		}
+		docLines.push(` * @see ${item.relativePath}`);
+		blocks.push([
+			"/**",
+			...docLines,
+			" */",
+			`export interface ${item.name}Augmentation {}`
+		].join("\n"));
+	}
+	return `${HEADER}
+// Catalogue of augmentable interfaces in this project. The interfaces
+// below are documentation only — augment the source-of-truth interfaces
+// in your own \`d.ts\` files (the framework declares the actual types).
+
+${blocks.join("\n\n")}
+`;
+}
+/** Write all generated `.d.ts` files to `outDir` */
+async function generateTypes(opts) {
+	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, pluginsAndAdapters = [], augmentations = [], assets = {
+		entries: [],
+		count: 0
+	}, outDir, allowDuplicates = false, schemaValidator = false } = opts;
+	if (collisions.length > 0 && !allowDuplicates) throw new TokenCollisionError(collisions);
+	await mkdir(outDir, { recursive: true });
+	const registryFile = join(outDir, "registry.d.ts");
+	const servicesFile = join(outDir, "services.d.ts");
+	const modulesFile = join(outDir, "modules.d.ts");
+	const routesFile = join(outDir, "routes.ts");
+	const envFile = join(outDir, "env.ts");
+	const pluginsFile = join(outDir, "plugins.d.ts");
+	const augmentationsFile = join(outDir, "augmentations.d.ts");
+	const assetsFile = join(outDir, "assets.d.ts");
+	const indexFile = join(outDir, "index.d.ts");
+	const collidingNames = new Set(collisions.map((c) => c.className));
+	const registryContent = renderRegistry(classes, registryFile, collidingNames);
+	const classTokens = classes.filter((c) => REGISTRY_DECORATORS.has(c.decorator)).map((c) => collidingNames.has(c.className) ? namespacedKeyFor(c) : c.className);
+	const tokenLiterals = tokens.map((t) => t.name);
+	const injectLiterals = injects.map((i) => i.name);
+	const allServices = [
+		...classTokens,
+		...tokenLiterals,
+		...injectLiterals
+	];
+	const modules = classes.filter((c) => c.decorator === "Module").map((c) => c.className);
+	const servicesContent = renderUnion("ServiceToken", allServices, "(no tokens discovered — declare with createToken<T>() or `kick g service <name>`)");
+	const modulesContent = renderUnion("ModuleToken", modules, "(no @Module classes discovered — `kick g module <name>` to add one)");
+	const routesContent = renderRoutes(routes, routesFile, schemaValidator);
+	const envContent = renderEnv(env, envFile);
+	const pluginsContent = renderPlugins(pluginsAndAdapters);
+	const augmentationsContent = renderAugmentations(augmentations);
+	const assetsContent = renderAssetTypes(assets);
+	const indexContent = renderIndex(envContent !== null);
+	await writeFile(registryFile, registryContent, "utf-8");
+	await writeFile(servicesFile, servicesContent, "utf-8");
+	await writeFile(modulesFile, modulesContent, "utf-8");
+	await writeFile(routesFile, routesContent, "utf-8");
+	await writeFile(pluginsFile, pluginsContent, "utf-8");
+	await writeFile(augmentationsFile, augmentationsContent, "utf-8");
+	await writeFile(assetsFile, assetsContent, "utf-8");
+	await writeFile(indexFile, indexContent, "utf-8");
+	const written = [
+		registryFile,
+		servicesFile,
+		modulesFile,
+		routesFile,
+		pluginsFile,
+		augmentationsFile,
+		assetsFile,
+		indexFile
+	];
+	if (envContent) {
+		await writeFile(envFile, envContent, "utf-8");
+		written.push(envFile);
+	}
+	await writeFile(join(dirname(outDir), ".gitignore"), "# Auto-generated by kick typegen\n*\n", "utf-8");
+	const uniquePluginNames = new Set(pluginsAndAdapters.map((p) => p.name)).size;
+	const uniqueAugmentations = new Set(augmentations.map((a) => a.name)).size;
+	return {
+		registryEntries: classTokens.length,
+		serviceTokens: new Set(allServices).size,
+		moduleTokens: modules.length,
+		routeEntries: routes.length,
+		pluginEntries: uniquePluginNames,
+		augmentationEntries: uniqueAugmentations,
+		assetEntries: assets.count,
+		envWritten: envContent !== null,
+		written,
+		resolvedCollisions: collisions.length
+	};
+}
+//#endregion
+//#region src/typegen/token-conventions.ts
+/**
+* Regex for the §22.2 token shape. Breakdown:
+*
+* - `^(kick\/)?` — optional reserved framework prefix.
+* - `([a-z][\w-]*\/[A-Z]\w*)` — `<scope>/<PascalKey>`. Scope is
+*   lowercase, key is PascalCase.
+* - `(\/.+)?` — optional `/suffix` for sub-flavours
+*   (e.g. `mycorp/Cache/redis`).
+* - `(:[a-z][\w-]+(:[a-z][\w-]+)*)?` — optional `:instance` (and
+*   further `:extra` colon-sections) for `.scoped()` shards.
+*/
+const TOKEN_CONVENTION_REGEX = /^(kick\/)?([a-z][\w-]*\/[A-Z]\w*)(\/.+)?(:[a-z][\w-]+(:[a-z][\w-]+)*)?$/;
+const LEGACY_PREFIX = "kickjs.";
+function validateTokenConventions(tokens) {
+	const warnings = [];
+	for (const token of tokens) {
+		const name = token.name;
+		if (name.startsWith(LEGACY_PREFIX)) continue;
+		if (TOKEN_CONVENTION_REGEX.test(name)) continue;
+		warnings.push({
+			token: name,
+			variable: token.variable,
+			filePath: token.relativePath,
+			reason: "does not match `<scope>/<PascalKey>[/<suffix>][:<instance>]`",
+			suggestion: suggestRename(name)
+		});
+	}
+	return warnings;
+}
+function suggestRename(name) {
+	if (/^[A-Z]\w*$/.test(name)) return `'<scope>/${name}' (e.g. 'mycorp/${name}')`;
+	if (name.includes(".")) return `consider '<scope>/PascalKey' instead of dotted form`;
+	const slashLower = /^([a-z][\w-]*)\/([a-z]\w*)$/.exec(name);
+	if (slashLower) {
+		const [, scope, key] = slashLower;
+		return `'${scope}/${key.charAt(0).toUpperCase()}${key.slice(1)}'`;
+	}
+}
+//#endregion
+//#region src/typegen/index.ts
+/**
+* Public entry point for the KickJS typegen module.
+*
+* Used by:
+* - `kick typegen` (one-shot or watch mode)
+* - `kick dev` (auto-runs once before Vite starts; refreshes when files change)
+*
+* @module @forinda/kickjs-cli/typegen
+*/
+var typegen_exports = /* @__PURE__ */ __exportAll({
+	runTypegen: () => runTypegen,
+	watchTypegen: () => watchTypegen
+});
+/** Resolve options to absolute paths */
+function resolveOptions(opts) {
+	const cwd = opts.cwd ?? process.cwd();
+	return {
+		cwd,
+		srcDir: resolve(cwd, opts.srcDir ?? "src"),
+		outDir: resolve(cwd, opts.outDir ?? ".kickjs/types"),
+		silent: opts.silent ?? false,
+		allowDuplicates: opts.allowDuplicates ?? false,
+		schemaValidator: opts.schemaValidator ?? false,
+		envFile: opts.envFile ?? "src/env.ts"
+	};
+}
+/**
+* Run a single typegen pass: scan source files, generate `.d.ts` files.
+*
+* Returns the discovered scan result alongside the generation result so
+* callers (`kick dev`, devtools) can log them or feed them to other tools.
+*
+* Throws `TokenCollisionError` if duplicate class names are found and
+* `allowDuplicates` is false.
+*/
+async function runTypegen(opts = {}) {
+	const { cwd, srcDir, outDir, silent, allowDuplicates, schemaValidator, envFile } = resolveOptions(opts);
+	const start = Date.now();
+	const scan = await scanProject({
+		root: srcDir,
+		cwd,
+		envFile: envFile === false ? void 0 : envFile
+	});
+	const assets = discoverAssets(opts.assetMap, cwd);
+	const result = await generateTypes({
+		classes: scan.classes,
+		routes: scan.routes,
+		tokens: scan.tokens,
+		injects: scan.injects,
+		collisions: scan.collisions,
+		env: envFile === false ? null : scan.env,
+		pluginsAndAdapters: scan.pluginsAndAdapters,
+		augmentations: scan.augmentations,
+		assets,
+		outDir,
+		allowDuplicates,
+		schemaValidator
+	});
+	const tokenWarnings = validateTokenConventions(scan.tokens);
+	const elapsed = Date.now() - start;
+	if (!silent) {
+		const where = outDir.replace(cwd + "/", "");
+		const collisionNote = result.resolvedCollisions > 0 ? `, ${result.resolvedCollisions} collisions namespaced` : "";
+		const envNote = result.envWritten ? ", env typed" : "";
+		const pluginNote = result.pluginEntries > 0 ? `, ${result.pluginEntries} plugins/adapters` : "";
+		const augNote = result.augmentationEntries > 0 ? `, ${result.augmentationEntries} augmentations` : "";
+		const assetNote = result.assetEntries > 0 ? `, ${result.assetEntries} assets` : "";
+		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${pluginNote}${augNote}${assetNote}${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		if (tokenWarnings.length > 0) {
+			console.warn(`  kick typegen: ${tokenWarnings.length} token(s) don't match the §22.2 convention:`);
+			for (const warning of tokenWarnings) {
+				const variableNote = warning.variable ? ` [${warning.variable}]` : "";
+				console.warn(`    '${warning.token}' (${warning.filePath})${variableNote} — ${warning.reason}`);
+				if (warning.suggestion) console.warn(`      → suggestion: ${warning.suggestion}`);
+			}
+		}
+	}
+	return {
+		scan,
+		result,
+		tokenWarnings
+	};
+}
+/**
+* Watch mode for `kick typegen --watch`.
+*
+* Uses Node's built-in `fs.watch` (recursive, available on Linux 22+ and
+* macOS 19+). Falls back gracefully if recursive watch is not supported.
+*
+* Debounces re-runs by 100ms so a bulk file change (e.g. `kick g module`
+* creating 5 files at once) emits one regen, not five.
+*
+* In watch mode collisions are reported but never thrown — the watcher
+* keeps running so the user can fix the rename and the next scan
+* recovers automatically.
+*
+* Returns a `stop()` function that closes the watcher.
+*/
+async function watchTypegen(opts = {}) {
+	const resolved = resolveOptions(opts);
+	const { srcDir, silent, cwd } = resolved;
+	const runOpts = {
+		...resolved,
+		allowDuplicates: true
+	};
+	const [{ runAllPluginTypegens }, { loadKickConfig }] = await Promise.all([import("./run-plugins-BXvMFPhJ.mjs"), import("./config-C_LQNClP.mjs").then((n) => n.n)]);
+	const pluginConfig = await loadKickConfig(cwd);
+	const runPlugins = () => runAllPluginTypegens({
+		cwd,
+		config: pluginConfig,
+		silent: true
+	}).catch(() => {});
+	await safeRun(runOpts, silent);
+	await runPlugins();
+	const { watch } = await import("node:fs");
+	let timer = null;
+	const trigger = (filename) => {
+		if (!filename) return;
+		if (!/\.(ts|tsx|mts|cts)$/.test(filename)) return;
+		if (filename.includes(".kickjs")) return;
+		if (filename.endsWith(".d.ts")) return;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			safeRun(runOpts, silent);
+			runPlugins();
+		}, 100);
+	};
+	let watcher;
+	try {
+		watcher = watch(srcDir, { recursive: true }, (_event, filename) => {
+			trigger(filename);
+		});
+	} catch (err) {
+		if (!silent) console.warn(`  kick typegen: watch mode unavailable (${err?.message ?? err}). Falling back to polling.`);
+		const interval = setInterval(() => {
+			safeRun({
+				...runOpts,
+				silent: true
+			}, true);
+		}, 2e3);
+		return () => clearInterval(interval);
+	}
+	return () => {
+		if (timer) clearTimeout(timer);
+		watcher.close();
+	};
+}
+/** Run typegen swallowing errors so the watcher loop never dies */
+async function safeRun(opts, silent) {
+	try {
+		await runTypegen(opts);
+	} catch (err) {
+		if (silent) return;
+		if (err instanceof TokenCollisionError) console.error("\n" + err.message + "\n");
+		else {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(`  kick typegen failed: ${msg}`);
+		}
+	}
+}
+//#endregion
+export { discoverAssets as a, TokenCollisionError as i, typegen_exports as n, renderAssetTypes as o, watchTypegen as r, runTypegen as t };
+
+//# sourceMappingURL=typegen-8ZeA1B-X.mjs.map