@forinda/kickjs-cli 3.1.3 → 4.0.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.1.3
+ * @forinda/kickjs-cli v4.0.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,15 +8,17 @@
  *
  * @license MIT
  */
+import { createRequire } from "node:module";
 import { Command } from "commander";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { execSync, fork, spawn, spawnSync } from "node:child_process";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import * as clack from "@clack/prompts";
 import pc from "picocolors";
 import pkg from "pluralize";
+import { glob, globSync } from "glob";
 import { arch, platform, release } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -296,15 +298,15 @@ function generateEntryFile(name, template, version, packages = []) {
 			const gqlAdapters = [];
 			if (packages.includes("devtools")) {
 				gqlImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				gqlAdapters.push(`    new DevToolsAdapter(),`);
+				gqlAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				gqlImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				gqlAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				gqlAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("swagger")) {
 				gqlImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				gqlAdapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				gqlAdapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -337,15 +339,15 @@ ${gqlAdapters.length ? gqlAdapters.join("\n") + "\n" : ""}    new GraphQLAdapter
 			const cqrsAdapters = [];
 			if (packages.includes("otel")) {
 				cqrsImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				cqrsAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				cqrsAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("devtools")) {
 				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				cqrsAdapters.push(`    new DevToolsAdapter(),`);
+				cqrsAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				cqrsAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("graphql")) {
 				cqrsImports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -364,7 +366,7 @@ ${cqrsImports.length ? cqrsImports.join("\n") + "\n" : ""}import { modules } fro
 
 // Export the app for the Vite plugin (dev mode)
 export const app = await bootstrap({
-  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
+  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
 })
 `;
 		}
@@ -373,15 +375,15 @@ export const app = await bootstrap({
 			const adapters = [];
 			if (packages.includes("swagger")) {
 				imports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				adapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				adapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			if (packages.includes("devtools")) {
 				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				adapters.push(`    new DevToolsAdapter(),`);
+				adapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				imports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				adapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				adapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("graphql")) {
 				imports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -405,15 +407,15 @@ export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters:
 			const restAdapters = [];
 			if (packages.includes("devtools")) {
 				restImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				restAdapters.push(`    new DevToolsAdapter(),`);
+				restAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				restAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("otel")) {
 				restImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				restAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				restAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -711,6 +713,8 @@ Copy \`.env.example\` to \`.env\` and configure:
 function generateClaude(name, template, pm) {
 	return `# CLAUDE.md — ${name} Development Guide
 
+> **Read \`AGENTS.md\` first.** It is the canonical, multi-agent reference for this project (Claude, Copilot, Codex, Gemini, etc.). This file contains the same project context distilled for Claude, plus Claude-specific notes. When the two disagree on anything substantive, treat \`AGENTS.md\` as authoritative and flag the discrepancy.
+
 ## Project Overview
 
 This is a **${{
@@ -767,7 +771,7 @@ generated \`KickRoutes\` namespace (refreshed on \`kick dev\` and \`kick typegen
 \`\`\`ts
 import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
 
-@Controller('/users')
+@Controller()
 export class UserController {
   @Get('/')
   async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
@@ -802,9 +806,12 @@ export class UserService {
 
 ### Modules
 
-Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`:
+Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`.
+
+> **Naming matters.** Module files **must** be named \`<name>.module.ts\` and live under \`src/modules/\`. The Vite plugin auto-discovers files matching \`*.module.[tj]sx?\` for HMR — a misnamed file (e.g., \`projects.ts\`) won't trigger a graceful module rebuild on save and will require a full server restart. The CLI generator (\`kick g module <name>\`) follows this convention automatically.
 
 \`\`\`ts
+// src/modules/users/users.module.ts   (named <feature>.module.ts)
 import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
 import { UserController } from './user.controller'
 
@@ -855,6 +862,8 @@ ctx.notFound()            // 404 Not Found
 ctx.badRequest(msg)       // 400 Bad Request
 \`\`\`
 
+> **Context decorators** — when a middleware's only job is to populate \`ctx.set/get\` for the handler to read, prefer \`defineContextDecorator()\` over \`@Middleware()\`. Typed via \`ContextMeta\`, supports \`dependsOn\` ordering, validates the pipeline at boot. Full pattern reference in \`AGENTS.md\` and at <https://forinda.github.io/kick-js/guide/context-decorators>.
+
 ## CLI Generators
 
 Generate code with the \`kick\` CLI:
@@ -1043,7 +1052,7 @@ Run tests:
 ## Decorators Reference
 
 ### Route Decorators
-- \`@Controller('/path')\` — define controller prefix
+- \`@Controller()\` — mark a class as an HTTP controller (path comes from \`routes().path\`)
 - \`@Get('/'), @Post('/'), @Put('/'), @Delete('/'), @Patch('/')\` — HTTP methods
 - \`@Middleware(fn)\` — attach middleware
 - \`@Public()\` — skip authentication (requires @forinda/kickjs-auth)
@@ -1118,6 +1127,8 @@ ${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| E
 
 ### Module Pattern (${template.toUpperCase()})
 
+> **Vite HMR auto-discovery contract:** module files **must** be named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and live under \`src/modules/\`. The Vite plugin scans for \`*.module.[tj]sx?\` to drive graceful HMR rebuilds; renaming a file to \`projects.ts\` (no \`.module\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\`kick g module <name>\`) follows the convention; manual files must too.
+
 Each module in \`src/modules/<name>/\` typically contains:
 
 ${template === "ddd" ? `\`\`\`
@@ -1188,7 +1199,7 @@ Then:
 If not using generators:
 
 - [ ] Create \`src/modules/<name>/<name>.controller.ts\`
-- [ ] Add \`@Controller('/path')\` decorator
+- [ ] Add \`@Controller()\` decorator
 - [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
 - [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
 - [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
@@ -1250,8 +1261,8 @@ import { AuthAdapter, JwtStrategy } from '@forinda/kickjs-auth'
 bootstrap({
   modules,
   adapters: [
-    new AuthAdapter({
-      strategies: [new JwtStrategy({ secret: process.env.JWT_SECRET! })],
+    AuthAdapter({
+      strategies: [JwtStrategy({ secret: process.env.JWT_SECRET! })],
     }),
   ],
 })
@@ -1281,7 +1292,7 @@ import { WsAdapter } from '@forinda/kickjs-ws'
 
 bootstrap({
   modules,
-  adapters: [new WsAdapter()],
+  adapters: [WsAdapter()],
 })
 \`\`\`
 
@@ -1385,7 +1396,7 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 ### HTTP Routes
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Controller('/path')\` | Define route prefix |
+| \`@Controller()\` | Define route prefix |
 | \`@Get('/'), @Post('/')\` | HTTP method handlers |
 | \`@Middleware(fn)\` | Attach middleware |
 | \`@Public()\` | Skip auth (requires auth adapter) |
@@ -1401,6 +1412,27 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 | \`@Inject('token')\` | Token-based injection |
 | \`@Value('VAR')\` | Inject env variable |
 
+### Context Decorators
+
+Typed, ordered way to populate \`ctx.set/get\` keys before the handler runs.
+Use this **instead of \`@Middleware()\`** when the middleware's only output
+is a value other code reads off \`ctx\`.
+
+| Concept | Where it lives |
+|---------|----------------|
+| \`defineContextDecorator({ key, deps, dependsOn, optional, onError, resolve })\` | \`@forinda/kickjs\` |
+| Method/class decorator | \`@LoadX\` on a controller method/class |
+| Module hook | \`AppModule.contributors?(): ContributorRegistration[]\` |
+| Adapter hook | \`AppAdapter.contributors?(): ContributorRegistration[]\` |
+| Global registration | \`bootstrap({ contributors: [LoadX.registration] })\` |
+| Type augmentation | \`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\` |
+
+Precedence high → low: **method > class > module > adapter > global**.
+Cycles and missing \`dependsOn\` keys throw at \`app.setup()\` (boot fails
+fast). The \`onError\` hook is async-permitted.
+
+Full guide: <https://forinda.github.io/kick-js/guide/context-decorators>.
+
 ${template === "graphql" ? `### GraphQL
 | Decorator | Purpose |
 |-----------|---------|
@@ -1423,9 +1455,11 @@ ${template === "graphql" ? `### GraphQL
 2. **DI not working** — Ensure \`reflect-metadata\` is imported in \`src/index.ts\`
 3. **Tests failing randomly** — Missing \`Container.reset()\` in \`beforeEach\`
 4. **Routes not found** — Check controller path and module registration
-5. **HMR not working** — Verify \`vite.config.ts\` has \`hmr: true\`
+5. **HMR not working** — Two checks: (a) \`vite.config.ts\` has \`hmr: true\`; (b) module file is named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and lives under \`src/modules/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed module file (e.g., \`projects.ts\`) silently degrades to a full restart on every save.
 6. **Decorators not working** — Check \`tsconfig.json\` has \`experimentalDecorators: true\`
 7. **\`config.get('YOUR_KEY')\` returns \`undefined\`** — \`src/index.ts\` is missing \`import './config'\`. That side-effect import registers the env schema with kickjs (\`loadEnv(envSchema)\` runs at module load). Without it, \`ConfigService\` falls back to the base schema (\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` only) and every user-defined key reads as \`undefined\`. \`@Value()\` may *appear* to work because of a raw \`process.env\` fallback, but Zod coercion and schema defaults are silently skipped — investigate \`src/index.ts\` and \`src/config/index.ts\` first.
+8. **Used \`@Middleware()\` to compute a value for \`ctx\`** — prefer \`defineContextDecorator()\` (see Context Decorators above). It's typed via \`ContextMeta\`, supports \`dependsOn\` for ordering, and validates the pipeline at boot. \`@Middleware()\` is for response short-circuiting, stream mutation, and pre-route-matching work.
+9. **Context contributor's \`dependsOn\` key not produced anywhere** — boot throws \`MissingContributorError\` naming the dependent and the route. Either remove the dep or register a contributor that produces the key (at any precedence level: method/class/module/adapter/global).
 
 ## CLI Commands Reference
 
@@ -1883,6 +1917,228 @@ function pluralizePascal(name) {
 	return pkg.plural(name);
 }
 //#endregion
+//#region src/generator-extension/context.ts
+/** Convert any string to snake_case (`UserPost` / `user-post` → `user_post`). */
+function toSnakeCase(name) {
+	return toKebabCase(name).replace(/-/g, "_");
+}
+/**
+* Build a {@link GeneratorContext} from the raw name + invocation
+* arguments. Centralises the case-transformation logic so every plugin
+* generator sees the same shape regardless of how the name was typed
+* on the command line (`Post` vs `post` vs `user_post`).
+*/
+function buildGeneratorContext(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const usePlural = input.pluralize ?? true;
+	const pascal = toPascalCase(input.name);
+	const camel = toCamelCase(input.name);
+	const kebab = toKebabCase(input.name);
+	const snake = toSnakeCase(input.name);
+	const ctx = {
+		name: input.name,
+		pascal,
+		camel,
+		kebab,
+		snake,
+		modulesDir: input.modulesDir ?? "src/modules",
+		cwd,
+		args: input.args ?? [],
+		flags: input.flags ?? {}
+	};
+	if (usePlural) {
+		const pluralKebab = pluralize(kebab);
+		ctx.pluralKebab = pluralKebab;
+		ctx.pluralPascal = toPascalCase(pluralKebab);
+		ctx.pluralCamel = toCamelCase(pluralKebab);
+	}
+	return ctx;
+}
+/** Resolve a generator output path against the context's cwd. */
+function resolveGeneratorPath(ctx, path) {
+	return resolve(ctx.cwd, path);
+}
+/**
+* Dynamic-import a generator manifest file. Wraps `pathToFileURL` so
+* callers don't have to think about Windows/Unix path quirks.
+*/
+async function importManifest(absPath) {
+	return import(pathToFileURL(absPath).href);
+}
+//#endregion
+//#region src/generator-extension/discover.ts
+/**
+* Discover generator manifests shipped by every kickjs plugin in the
+* project's direct deps. Spec rationale: walking the
+* `node_modules/@scope/kickjs-name/` tree is one option, but reading
+* the project's own `package.json` and resolving each dep through
+* Node's module resolver gives:
+*
+*   1. Predictable scoping — only deps the project actually declared
+*      get scanned, no surprises from transitive packages
+*   2. pnpm `.pnpm` store compatibility — `createRequire().resolve()`
+*      handles the symlinked layout correctly
+*   3. Clear error attribution — the source package name is always
+*      known before the import happens
+*
+* The walk is shallow (direct deps only). Transitive plugins that want
+* to expose generators must be re-exported by a direct dep.
+*
+* Caches per-cwd inside one CLI invocation so a single `kick g` call
+* does the disk + import work exactly once even when multiple
+* generators dispatch through the same registry.
+*/
+const cache = /* @__PURE__ */ new Map();
+async function discoverPluginGenerators(cwd) {
+	const cached = cache.get(cwd);
+	if (cached) return cached;
+	const promise = doDiscover(cwd);
+	cache.set(cwd, promise);
+	return promise;
+}
+async function doDiscover(cwd) {
+	const projectPkgPath = resolve(cwd, "package.json");
+	if (!existsSync(projectPkgPath)) return {
+		generators: [],
+		loaded: [],
+		failed: []
+	};
+	const depNames = collectDepNames(JSON.parse(await readFile(projectPkgPath, "utf-8")));
+	const require = createRequire(resolve(cwd, "package.json"));
+	const generators = [];
+	const loaded = [];
+	const failed = [];
+	for (const depName of depNames) {
+		let depPkgPath;
+		try {
+			depPkgPath = require.resolve(`${depName}/package.json`);
+		} catch {
+			continue;
+		}
+		let depPkg;
+		try {
+			depPkg = JSON.parse(await readFile(depPkgPath, "utf-8"));
+		} catch (err) {
+			failed.push({
+				source: depName,
+				reason: `failed to parse package.json: ${err}`
+			});
+			continue;
+		}
+		if (!depPkg.kickjs?.generators) continue;
+		const entryRel = depPkg.kickjs.generators;
+		const entryAbs = resolve(dirname(depPkgPath), entryRel);
+		if (!existsSync(entryAbs)) {
+			failed.push({
+				source: depName,
+				reason: `kickjs.generators points to missing file: ${entryRel}`
+			});
+			continue;
+		}
+		let mod;
+		try {
+			mod = await importManifest(entryAbs);
+		} catch (err) {
+			failed.push({
+				source: depName,
+				reason: `failed to import manifest: ${err}`
+			});
+			continue;
+		}
+		const manifest = mod.default;
+		if (!Array.isArray(manifest)) {
+			failed.push({
+				source: depName,
+				reason: `manifest's default export is not an array of GeneratorSpec`
+			});
+			continue;
+		}
+		for (const entry of manifest) {
+			if (!isGeneratorSpec(entry)) {
+				failed.push({
+					source: depName,
+					reason: `manifest entry is not a valid GeneratorSpec (missing name/files)`
+				});
+				continue;
+			}
+			generators.push({
+				source: depName,
+				spec: entry
+			});
+		}
+		loaded.push(depName);
+	}
+	return {
+		generators,
+		loaded,
+		failed
+	};
+}
+function collectDepNames(pkg) {
+	const set = /* @__PURE__ */ new Set();
+	for (const block of [
+		pkg.dependencies,
+		pkg.devDependencies,
+		pkg.peerDependencies
+	]) {
+		if (!block) continue;
+		for (const name of Object.keys(block)) set.add(name);
+	}
+	return Array.from(set);
+}
+function isGeneratorSpec(entry) {
+	if (!entry || typeof entry !== "object") return false;
+	const e = entry;
+	return typeof e.name === "string" && typeof e.files === "function";
+}
+//#endregion
+//#region src/generator-extension/dispatch.ts
+/**
+* Look up a plugin generator by name and run it. Returns `null` when
+* no plugin generator matches — callers can then fall through to the
+* built-in dispatch (module / scaffold / etc.).
+*
+* The lookup is FIRST-MATCH-WINS in dependency declaration order: if
+* two plugins claim the same generator name, the one whose package was
+* resolved first wins. Adopters with conflicts should rename the
+* generator on their side or pin one of the plugins to a different
+* version.
+*/
+async function tryDispatchPluginGenerator(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const match = findGenerator(await discoverPluginGenerators(cwd), input.generatorName);
+	if (!match) return null;
+	return runGenerator(match.spec, match.source, input, cwd);
+}
+/** Public helper for `kick g --list` — returns every discovered plugin generator. */
+async function listPluginGenerators(cwd) {
+	return discoverPluginGenerators(cwd);
+}
+function findGenerator(discovery, name) {
+	return discovery.generators.find((g) => g.spec.name === name);
+}
+async function runGenerator(spec, source, input, cwd) {
+	const ctx = buildGeneratorContext({
+		name: input.itemName,
+		args: input.args,
+		flags: input.flags,
+		modulesDir: input.modulesDir,
+		pluralize: input.pluralize,
+		cwd
+	});
+	const files = await spec.files(ctx);
+	const written = [];
+	for (const file of files) {
+		const absPath = resolveGeneratorPath(ctx, file.path);
+		await writeFileSafe(absPath, file.content);
+		written.push(absPath);
+	}
+	return {
+		files: written,
+		source
+	};
+}
+//#endregion
 //#region src/generators/templates/module-index.ts
 const repoLabelMap = {
 	inmemory: "in-memory",
@@ -4409,7 +4665,7 @@ import type { RequestContext } from '@forinda/kickjs'
 import { Autowired } from '@forinda/kickjs'
 import { AuthService } from './auth.service'
 
-@Controller('/auth')
+@Controller()
 @Authenticated()
 export class AuthController {
   @Autowired() private authService!: AuthService
@@ -4491,7 +4747,7 @@ import type { RequestContext } from '@forinda/kickjs'
 import { Autowired } from '@forinda/kickjs'
 import { AuthService } from './auth.service'
 
-@Controller('/auth')
+@Controller()
 @Authenticated()
 export class AuthController {
   @Autowired() private authService!: AuthService
@@ -5298,14 +5554,14 @@ const BUILTIN_REPO_TYPES = [
 	"inmemory",
 	"prisma"
 ];
-/** Resolve module config with backward-compatible fallbacks from top-level fields */
+/** Resolve module config from `modules.*` block. */
 function resolveModuleConfig(config) {
 	if (!config) return {};
 	const mc = {
-		dir: config.modules?.dir ?? config.modulesDir,
-		repo: config.modules?.repo ?? config.defaultRepo,
-		schemaDir: config.modules?.schemaDir ?? config.schemaDir,
-		pluralize: config.modules?.pluralize ?? config.pluralize,
+		dir: config.modules?.dir,
+		repo: config.modules?.repo,
+		schemaDir: config.modules?.schemaDir,
+		pluralize: config.modules?.pluralize,
 		prismaClientPath: config.modules?.prismaClientPath
 	};
 	if (mc.repo && typeof mc.repo === "string" && !BUILTIN_REPO_TYPES.includes(mc.repo)) console.warn(`  Warning: modules.repo '${mc.repo}' is not a built-in type (${BUILTIN_REPO_TYPES.join(", ")}). It will generate a stub repository. Use { name: '${mc.repo}' } to silence this warning.`);
@@ -5333,7 +5589,10 @@ async function loadKickConfig(cwd) {
 		try {
 			const { pathToFileURL } = await import("node:url");
 			const mod = await import(pathToFileURL(filepath).href);
-			return mod.default ?? mod;
+			const config = mod.default ?? mod;
+			const warnings = validateAssetMap(config, cwd);
+			for (const warning of warnings) console.warn(`  Warning: ${warning}`);
+			return config;
 		} catch (err) {
 			if (filename.endsWith(".ts")) console.warn(`Warning: Failed to load ${filename}. TypeScript config files require a runtime loader (e.g. tsx, ts-node) or use kick.config.js/.mjs instead.`);
 			continue;
@@ -5341,6 +5600,59 @@ async function loadKickConfig(cwd) {
 	}
 	return null;
 }
+/**
+* Validate `assetMap` entries on a loaded config. Returns a list of
+* human-readable warnings; the caller decides how to surface them
+* (typically `console.warn`). Never throws — `kick g` and other
+* unrelated commands should keep working even when the assetMap is
+* misconfigured.
+*
+* Checks:
+*
+* - Each entry's `src` is a non-empty string.
+* - The `src` directory exists on disk (otherwise the typegen + build
+*   steps will fail later with cryptic errors).
+* - `dest` doesn't escape the project root (defensive — a `dest:
+*   '../../etc'` typo could write files outside the workspace).
+* - The namespace key is a non-empty string and doesn't include a
+*   `/` (would conflict with the `<namespace>/<key>` manifest format).
+*/
+function validateAssetMap(config, cwd) {
+	const warnings = [];
+	if (!config?.assetMap) return warnings;
+	const root = resolve(cwd);
+	for (const [namespace, entry] of Object.entries(config.assetMap)) {
+		if (!namespace || namespace.includes("/")) {
+			warnings.push(`assetMap key '${namespace}' is invalid — must be a non-empty string without '/'`);
+			continue;
+		}
+		if (typeof entry?.src !== "string" || entry.src.length === 0) {
+			warnings.push(`assetMap.${namespace} is missing a non-empty 'src' field`);
+			continue;
+		}
+		if (!existsSync(resolve(cwd, entry.src))) warnings.push(`assetMap.${namespace}.src ('${entry.src}') does not exist — typegen + build will fail`);
+		if (entry.dest) {
+			if (escapesRoot$1(resolve(cwd, entry.dest), root)) warnings.push(`assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — refusing to copy`);
+		}
+	}
+	return warnings;
+}
+/**
+* Returns true when `path` (absolute) resolves outside of `root`
+* (also absolute). Uses `path.relative` for accuracy:
+*
+* - The result is empty when paths are identical (inside).
+* - It starts with `..` when the path traverses outside the root.
+* - It's absolute (Windows: cross-drive) when there's no relative
+*   path between them.
+*
+* Avoids the prefix-match pitfalls of `startsWith` (e.g. `/app`
+* matching `/app2/...`, or case-mismatches on macOS / Windows).
+*/
+function escapesRoot$1(path, root) {
+	const rel = relative(root, path);
+	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
+}
 //#endregion
 //#region src/typegen/scanner.ts
 /** Decorators that mark a class as DI-managed */
@@ -5396,6 +5708,28 @@ const BARE_CREATE_TOKEN_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+
 /** 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
@@ -5742,6 +6076,120 @@ function extractInjectsFromSource(source, filePath, cwd) {
 	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);
+					const descMatch = /\bdescription\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					const exampleMatch = /\bexample\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					description = descMatch ? descMatch[1] : null;
+					example = exampleMatch ? exampleMatch[1] : null;
+				}
+			}
+		}
+		out.push({
+			name,
+			description,
+			example,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
 * 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
@@ -5812,6 +6260,8 @@ async function scanProject(opts) {
 	const routes = [];
 	const tokens = [];
 	const injects = [];
+	const pluginsAndAdapters = [];
+	const augmentations = [];
 	const sources = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let source;
@@ -5824,6 +6274,8 @@ async function scanProject(opts) {
 		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);
@@ -5836,14 +6288,147 @@ async function scanProject(opts) {
 	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")
+		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$1(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$1(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
 }
 //#endregion
 //#region src/typegen/generator.ts
@@ -5981,12 +6566,17 @@ function renderIndex(includeEnv) {
 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.
+// 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" : ""}`;
 }
 /**
@@ -6181,9 +6771,90 @@ ${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) docLines.push(` * ${item.description}`);
+		if (item.example) docLines.push(` * @example`, ` * \`\`\`ts`, ` * ${item.example}`, ` * \`\`\``);
+		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, outDir, allowDuplicates = false, schemaValidator = false } = 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");
@@ -6191,6 +6862,9 @@ async function generateTypes(opts) {
 	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);
@@ -6207,17 +6881,26 @@ async function generateTypes(opts) {
 	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) {
@@ -6225,17 +6908,62 @@ async function generateTypes(opts) {
 		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.
@@ -6280,6 +7008,7 @@ async function runTypegen(opts = {}) {
 		cwd,
 		envFile: envFile === false ? void 0 : envFile
 	});
+	const assets = discoverAssets(opts.assetMap, cwd);
 	const result = await generateTypes({
 		classes: scan.classes,
 		routes: scan.routes,
@@ -6287,20 +7016,36 @@ async function runTypegen(opts = {}) {
 		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" : "";
-		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		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
+		result,
+		tokenWarnings
 	};
 }
 /**
@@ -6457,10 +7202,23 @@ const GENERATORS = [
 		description: "Generate kick.config.ts"
 	}
 ];
-function printGeneratorList() {
-	console.log("\n  Available generators:\n");
+async function printGeneratorList() {
+	console.log("\n  Built-in generators:\n");
 	const maxName = Math.max(...GENERATORS.map((g) => g.name.length));
 	for (const g of GENERATORS) console.log(`    kick g ${g.name.padEnd(maxName + 2)} ${g.description}`);
+	const discovery = await listPluginGenerators(process.cwd());
+	if (discovery.generators.length > 0) {
+		console.log("\n  Plugin generators:\n");
+		const pluginMax = Math.max(...discovery.generators.map((g) => `${g.spec.name} <name>`.length));
+		for (const { source, spec } of discovery.generators) {
+			const usage = `${spec.name} <name>`;
+			console.log(`    kick g ${usage.padEnd(pluginMax + 2)} ${spec.description}  [${source}]`);
+		}
+	}
+	if (discovery.failed.length > 0) {
+		console.log("\n  Failed to load:\n");
+		for (const { source, reason } of discovery.failed) console.log(`    ${source} — ${reason}`);
+	}
 	console.log();
 }
 /**
@@ -6497,7 +7255,7 @@ async function runModuleGeneration(names, opts, dryRun) {
 function registerGenerateCommand(program) {
 	const gen = program.command("generate [names...]").alias("g").description("Generate code scaffolds — bare form `kick g <name>` is shorthand for `kick g module <name>`").option("--list", "List all available generators").option("--dry-run", "Preview files that would be generated without writing them").option("--no-entity", "Skip entity and value object generation (module shortcut)").option("--no-tests", "Skip test file generation (module shortcut)").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("-f, --force", "Overwrite existing files without prompting").action(async (names, opts, cmd) => {
 		if (opts.list) {
-			printGeneratorList();
+			await printGeneratorList();
 			return;
 		}
 		if (!names || names.length === 0) {
@@ -6506,6 +7264,20 @@ function registerGenerateCommand(program) {
 		}
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
+		if (names.length >= 2) {
+			const [generatorName, itemName, ...rest] = names;
+			const result = await tryDispatchPluginGenerator({
+				generatorName,
+				itemName,
+				args: rest,
+				flags: opts,
+				cwd: process.cwd()
+			});
+			if (result) {
+				printGenerated(result.files, dryRun);
+				return;
+			}
+		}
 		await runModuleGeneration(names, opts, dryRun);
 	});
 	gen.command("module <names...>").description("Generate one or more modules (e.g. kick g module user task project)").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("-f, --force", "Overwrite existing files without prompting").action(async (names, opts, cmd) => {
@@ -6735,6 +7507,132 @@ function runNodeWithEnv(entry, env, cwd) {
 	});
 	if (result.status !== 0) process.exit(result.status ?? 1);
 }
+/**
+* Run the full asset build for a loaded config:
+*
+* 1. For each `assetMap` entry, glob → copy → manifest stub.
+* 2. Write `dist/.kickjs-assets.json`.
+*
+* Returns a summary including the manifest contents. No-op (and no
+* manifest written) when `assetMap` is empty / missing — the build
+* pipeline shouldn't litter `dist/` with empty manifests for
+* adopters who don't use the feature.
+*/
+async function buildAssets(config, opts) {
+	const { cwd, silent = false } = opts;
+	const distDir = opts.distDir ?? config?.build?.outDir ?? "dist";
+	const map = config?.assetMap;
+	if (!map || Object.keys(map).length === 0) return null;
+	const log = silent ? () => {} : console.log;
+	const distAbs = resolve(cwd, distDir);
+	mkdirSync(distAbs, { recursive: true });
+	const summary = [];
+	const manifestEntries = {};
+	for (const [namespace, entry] of Object.entries(map)) {
+		const result = await processEntry(namespace, entry, cwd, distAbs);
+		summary.push(result.entrySummary);
+		Object.assign(manifestEntries, result.manifestSlice);
+		log(`    ✓ ${namespace}: ${result.entrySummary.filesCopied} file(s) → ${result.entrySummary.dest}`);
+	}
+	const manifest = {
+		version: 1,
+		entries: manifestEntries
+	};
+	const manifestPath = join(distAbs, ".kickjs-assets.json");
+	writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+	log(`    ✓ wrote manifest → ${relative(cwd, manifestPath)} (${Object.keys(manifestEntries).length} entries)`);
+	return {
+		manifestPath,
+		entries: summary,
+		manifest
+	};
+}
+/** Per-entry inner pipeline — extracted for unit-test reuse. */
+async function processEntry(namespace, entry, cwd, distAbs) {
+	const srcAbs = resolve(cwd, entry.src);
+	const destAbs = entry.dest ? resolve(cwd, entry.dest) : join(distAbs, namespace);
+	if (escapesRoot(destAbs, cwd)) {
+		console.warn(`  ⚠ assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — skipping copy`);
+		return {
+			entrySummary: {
+				namespace,
+				src: entry.src,
+				dest: relative(cwd, destAbs),
+				filesCopied: 0
+			},
+			manifestSlice: {}
+		};
+	}
+	if (!existsSync(srcAbs) || !isDirectorySync(srcAbs)) return {
+		entrySummary: {
+			namespace,
+			src: entry.src,
+			dest: relative(cwd, destAbs),
+			filesCopied: 0
+		},
+		manifestSlice: {}
+	};
+	const matches = await glob(entry.glob ?? "**/*", {
+		cwd: srcAbs,
+		nodir: true,
+		dot: false,
+		posix: true
+	});
+	mkdirSync(destAbs, { recursive: true });
+	const manifestSlice = {};
+	const keyOwner = /* @__PURE__ */ new Map();
+	for (const relPath of matches.sort()) {
+		const srcFile = join(srcAbs, relPath);
+		const destFile = join(destAbs, relPath);
+		mkdirSync(dirname(destFile), { recursive: true });
+		cpSync(srcFile, destFile);
+		const logicalKey = `${namespace}/${stripExt(relPath)}`;
+		const previous = keyOwner.get(logicalKey);
+		if (previous) console.warn(`  ⚠ assetMap collision in '${namespace}': '${previous}' and '${relPath}' both flatten to key '${logicalKey}'. Last-alphabetical wins ('${relPath}'). Rename one of them or set assetMap.${namespace}.glob to filter by extension.`);
+		keyOwner.set(logicalKey, relPath);
+		manifestSlice[logicalKey] = toManifestRelative(distAbs, destFile);
+	}
+	return {
+		entrySummary: {
+			namespace,
+			src: entry.src,
+			dest: relative(cwd, destAbs),
+			filesCopied: matches.length
+		},
+		manifestSlice
+	};
+}
+/** Strip the final extension from a file path (`mails/welcome.ejs` → `mails/welcome`). */
+function stripExt(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
+}
+/**
+* Make `destFile` relative to the manifest's directory + force POSIX
+* separators so the manifest is byte-stable across platforms.
+*/
+function toManifestRelative(manifestDir, destFile) {
+	return relative(manifestDir, destFile).split(/[\\/]/).filter(Boolean).join("/");
+}
+/**
+* Project-root escape check that's safe across symlinks + drive letters.
+* `path.relative` returns `..` segments when the target sits above root,
+* and an absolute path when the two live on different roots (Windows).
+* `startsWith(root)` would miss both cases.
+*/
+function escapesRoot(path, root) {
+	const rel = relative(root, path);
+	if (rel === "") return false;
+	return rel.startsWith("..") || isAbsolute(rel);
+}
+/** Pure helper — `false` for missing, non-dir, or unreadable paths. */
+function isDirectorySync(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
 //#endregion
 //#region src/commands/run.ts
 /**
@@ -6763,7 +7661,8 @@ async function startDevServer(_entry, port) {
 			schemaValidator,
 			envFile,
 			srcDir: devConfig?.typegen?.srcDir,
-			outDir: devConfig?.typegen?.outDir
+			outDir: devConfig?.typegen?.outDir,
+			assetMap: devConfig?.assetMap
 		});
 	} catch (err) {
 		console.warn(`  kick typegen: skipped (${err?.message ?? err})`);
@@ -6788,7 +7687,8 @@ async function startDevServer(_entry, port) {
 				schemaValidator,
 				envFile,
 				srcDir: devConfig?.typegen?.srcDir,
-				outDir: devConfig?.typegen?.outDir
+				outDir: devConfig?.typegen?.outDir,
+				assetMap: devConfig?.assetMap
 			}).catch(() => {});
 		}, 100);
 	};
@@ -6821,7 +7721,8 @@ function registerRunCommands(program) {
 		const { createRequire } = await import("node:module");
 		const { build } = await import(pathToFileURL(createRequire(resolve("package.json")).resolve("vite")).href);
 		await build({ configFile: resolve("vite.config.ts") });
-		const copyDirs = (await loadKickConfig(process.cwd()))?.copyDirs ?? [];
+		const config = await loadKickConfig(process.cwd());
+		const copyDirs = config?.copyDirs ?? [];
 		if (copyDirs.length > 0) {
 			console.log("\n  Copying directories to dist...");
 			for (const entry of copyDirs) {
@@ -6838,8 +7739,32 @@ function registerRunCommands(program) {
 				console.log(`    ✓ ${src} → ${dest}`);
 			}
 		}
+		if (config?.assetMap && Object.keys(config.assetMap).length > 0) {
+			console.log("\n  Building asset map...");
+			try {
+				await buildAssets(config, { cwd: process.cwd() });
+			} catch (err) {
+				console.error(`    ✗ asset build failed: ${err instanceof Error ? err.message : String(err)}`);
+				process.exit(1);
+			}
+		}
 		console.log("\n  Build complete.\n");
 	});
+	program.command("build:assets").description("Rebuild the .kickjs-assets.json manifest under the configured outDir (no JS rebuild)").action(async () => {
+		const config = await loadKickConfig(process.cwd());
+		if (!config?.assetMap || Object.keys(config.assetMap).length === 0) {
+			console.log("  No assetMap entries — nothing to build.");
+			return;
+		}
+		console.log("\n  Building asset map...");
+		try {
+			await buildAssets(config, { cwd: process.cwd() });
+			console.log("\n  Asset build complete.\n");
+		} catch (err) {
+			console.error(`  ✗ ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(1);
+		}
+	});
 	program.command("start").description("Start production server").option("-e, --entry <file>", "Entry file", "dist/index.js").option("-p, --port <port>", "Port number").action((opts) => {
 		const env = { NODE_ENV: "production" };
 		if (opts.port) env.PORT = String(opts.port);
@@ -6871,7 +7796,6 @@ function registerInfoCommand(program) {
   Packages:
     @forinda/kickjs          workspace
     @forinda/kickjs-vite     workspace
-    @forinda/kickjs-config   workspace
     @forinda/kickjs-cli      workspace
 `);
 	});
@@ -8109,7 +9033,8 @@ function registerTypegenCommand(program) {
 			silent: opts.silent,
 			allowDuplicates: opts.allowDuplicates,
 			schemaValidator,
-			envFile
+			envFile,
+			assetMap: config?.assetMap
 		};
 		try {
 			if (opts.watch) {