@forinda/kickjs-cli 2.1.0 → 2.2.1

package/dist/typegen-UejiKdXA.mjs

@@ -0,0 +1,886 @@
+/**
+ * @forinda/kickjs-cli v2.2.1
+ *
+ * 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 { dirname, join, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+//#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 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 a route decorator immediately followed by a method declaration.
+* Captures the HTTP verb, path literal (or empty), and method name.
+*
+* Tolerates:
+* - Optional second arg to the route decorator (`@Get('/path', { ... })`)
+* - Stacked decorators between the route and the method (`@Get('/') @Use(...)`)
+* - Path-less decorators (`@Get()` → defaults to `/`)
+* - `async` modifier on the method
+*
+* Run within a class body slice (see extractRoutesFromSource) so the
+* captured method name is unambiguously a method on that class.
+*/
+const ROUTE_METHOD_REGEX = new RegExp(String.raw`@(${[
+	"Get",
+	"Post",
+	"Put",
+	"Delete",
+	"Patch"
+].join("|")})\s*\(` + String.raw`(?:\s*['"\`]([^'"\`]*)['"\`])?[^)]*\)` + String.raw`(?:\s*@[A-Z]\w*(?:\s*\([^)]*\))?)*` + String.raw`\s*(?:public\s+|private\s+|protected\s+)?(?:async\s+)?` + String.raw`([a-zA-Z_]\w*)\s*\(`, "g");
+/** Extract `:placeholder` segments from an Express route path */
+function extractPathParams(path) {
+	return (path.match(/:([a-zA-Z_]\w*)/g) ?? []).map((m) => m.slice(1));
+}
+/**
+* Given the matched text of a route decorator + method declaration, return
+* the substring inside the route decorator's argument list (between the
+* outermost `(` and `)`). Returns `null` if no parens are found.
+*
+* Example input:
+*   `@Post('/', { body: createTaskSchema, name: 'CreateTask' }) async create(`
+* Returns:
+*   `'/', { body: createTaskSchema, name: 'CreateTask' }`
+*/
+function extractRouteOptionsArg(matchedText) {
+	const open = matchedText.indexOf("(");
+	if (open < 0) return null;
+	let depth = 1;
+	for (let i = open + 1; i < matchedText.length; i++) {
+		const ch = matchedText[i];
+		if (ch === "(") depth++;
+		else if (ch === ")") {
+			depth--;
+			if (depth === 0) return matchedText.slice(open + 1, i);
+		}
+	}
+	return null;
+}
+/**
+* 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)
+		});
+	}
+	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_METHOD_REGEX.lastIndex = 0;
+		let match;
+		while ((match = ROUTE_METHOD_REGEX.exec(block)) !== null) {
+			const [matchedText, verb, pathLiteral, methodName] = match;
+			const path = pathLiteral && pathLiteral.length > 0 ? pathLiteral : "/";
+			const apiQp = extractApiQueryParams(matchedText, source);
+			const routeArgs = extractRouteOptionsArg(matchedText);
+			const bodyId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "body") : null;
+			const queryId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "query") : null;
+			const paramsId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "params") : null;
+			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;
+}
+/**
+* Look for an env schema file at `<cwd>/<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 (file missing, no defineEnv, no
+* default export) so the generator skips env typing silently. Users
+* who want env typing must opt in by writing `src/env.ts` to the
+* documented shape.
+*/
+async function detectEnvFile(cwd, envFile) {
+	const abs = resolve(cwd, envFile);
+	let source;
+	try {
+		source = await readFile(abs, "utf-8");
+	} catch {
+		return null;
+	}
+	if (!/\bdefineEnv\s*\(/.test(source)) return null;
+	if (!/export\s+default\b/.test(source)) return null;
+	return {
+		filePath: abs,
+		relativePath: toRelative(abs, cwd)
+	};
+}
+/** 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 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));
+	}
+	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));
+	return {
+		classes,
+		routes,
+		tokens,
+		injects,
+		collisions: findCollisions(classes),
+		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts")
+	};
+}
+//#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, 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']>\`,
+// and \`@Value('PORT')\` to resolve.
+import './registry'
+import './routes'
+${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 {}
+`;
+}
+/** Write all generated `.d.ts` files to `outDir` */
+async function generateTypes(opts) {
+	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, 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 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 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(indexFile, indexContent, "utf-8");
+	const written = [
+		registryFile,
+		servicesFile,
+		modulesFile,
+		routesFile,
+		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");
+	return {
+		registryEntries: classTokens.length,
+		serviceTokens: new Set(allServices).size,
+		moduleTokens: modules.length,
+		routeEntries: routes.length,
+		envWritten: envContent !== null,
+		written,
+		resolvedCollisions: collisions.length
+	};
+}
+//#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
+*/
+/** 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 result = await generateTypes({
+		classes: scan.classes,
+		routes: scan.routes,
+		tokens: scan.tokens,
+		injects: scan.injects,
+		collisions: scan.collisions,
+		env: envFile === false ? null : scan.env,
+		outDir,
+		allowDuplicates,
+		schemaValidator
+	});
+	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" : "";
+		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+	}
+	return {
+		scan,
+		result
+	};
+}
+//#endregion
+export { runTypegen };
+
+//# sourceMappingURL=typegen-UejiKdXA.mjs.map