@forinda/kickjs-cli 2.2.4 → 2.3.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.2.4
+ * @forinda/kickjs-cli v2.3.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -9,12 +9,13 @@
  * @license MIT
  */
 import { Command } from "commander";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
-import { execSync, fork } from "node:child_process";
+import { execSync, fork, spawn } from "node:child_process";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import pkg from "pluralize";
 import { arch, platform, release } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -742,18 +743,30 @@ export class UserService {
 
 ### Modules
 
-Register controllers and providers in modules:
+Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`:
 
 \`\`\`ts
-import { Module } from '@forinda/kickjs'
+import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
 import { UserController } from './user.controller'
-import { UserService } from './user.service'
 
-@Module({
-  controllers: [UserController],
-  providers: [UserService],
-})
-export class UserModule {}
+export class UserModule implements AppModule {
+  routes(): ModuleRoutes {
+    return {
+      path: '/users',
+      router: buildRoutes(UserController),
+      controller: UserController,
+    }
+  }
+}
+\`\`\`
+
+Register all modules in \`src/modules/index.ts\`:
+
+\`\`\`ts
+import type { AppModuleClass } from '@forinda/kickjs'
+import { UserModule } from './user/user.module'
+
+export const modules: AppModuleClass[] = [UserModule]
 \`\`\`
 
 ### RequestContext
@@ -864,6 +877,86 @@ Hot-reload of \`.env\` changes during dev is wired up automatically via
 \`envWatchPlugin()\` in \`vite.config.ts\` — edit \`.env\`, the dev server
 reloads, and the next \`config.get()\` re-parses with the new values.
 
+### Standalone Env Utilities (No DI Required)
+
+These functions work anywhere — scripts, CLI tools, plain files, outside \`@Service\`/\`@Controller\`:
+
+\`\`\`ts
+import { defineEnv, loadEnv, getEnv, reloadEnv, resetEnvCache, baseEnvSchema } from '@forinda/kickjs/config'
+import { z } from 'zod'
+
+// Define and parse schema
+const schema = defineEnv((base) =>
+  base.extend({ DATABASE_URL: z.string().url() })
+)
+const env = loadEnv(schema)      // Parse + validate process.env
+console.log(env.PORT)            // 3000 (coerced to number)
+console.log(env.DATABASE_URL)    // validated URL string
+
+// Get single value
+const port = getEnv('PORT')      // typed after kick typegen
+
+// Reload after .env changes (HMR calls this automatically)
+reloadEnv()
+
+// Reset cache in tests that swap schemas
+resetEnvCache()
+\`\`\`
+
+| Function | Purpose |
+|----------|---------|
+| \`defineEnv(fn)\` | Extend base schema with custom Zod keys |
+| \`loadEnv(schema?)\` | Parse \`process.env\`, validate, cache, return typed object |
+| \`getEnv(key, schema?)\` | Get single validated env value |
+| \`reloadEnv()\` | Re-read \`.env\` from disk, re-parse with same schema |
+| \`resetEnvCache()\` | Clear parsed cache AND registered schema (for tests) |
+| \`baseEnvSchema\` | Base Zod schema: \`PORT\`, \`NODE_ENV\`, \`LOG_LEVEL\` |
+
+## Standalone Utilities (No DI Required)
+
+These utilities work outside decorated classes:
+
+### Logger
+
+\`\`\`ts
+import { Logger, createLogger } from '@forinda/kickjs'
+
+const log = Logger.for('MyScript')    // Static factory
+log.info('Processing started')
+log.error('Something failed')
+
+const log2 = createLogger('Worker')   // Function form
+\`\`\`
+
+### Injection Tokens
+
+\`\`\`ts
+import { createToken } from '@forinda/kickjs'
+
+// Type-safe DI tokens for factory/interface binding
+const DB_URL = createToken<string>('config.database.url')
+const FEATURE_FLAGS = createToken<FeatureFlags>('app.features')
+\`\`\`
+
+### Reactivity
+
+\`\`\`ts
+import { ref, computed, watch, reactive } from '@forinda/kickjs'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+const stop = watch(() => count.value, (val) => console.log(val))
+count.value++  // logs 1
+\`\`\`
+
+### HTTP Errors
+
+\`\`\`ts
+import { HttpException, HttpStatus } from '@forinda/kickjs'
+
+throw new HttpException(HttpStatus.NOT_FOUND, 'User not found')
+\`\`\`
+
 ## Testing
 
 Tests live in \`src/**/*.test.ts\`:
@@ -898,7 +991,6 @@ Run tests:
 - \`@Roles('admin', 'user')\` — role-based access control
 
 ### DI Decorators
-- \`@Module({ controllers, providers, imports })\` — define module
 - \`@Service()\` — singleton service (DI-registered)
 - \`@Repository()\` — repository (semantic alias for @Service)
 - \`@Autowired()\` — property injection
@@ -976,7 +1068,7 @@ ${template === "ddd" ? `\`\`\`
 ├── <name>.repository.ts     # Data access (@Repository)
 ├── <name>.dto.ts            # Request/response schemas (Zod)
 ├── <name>.entity.ts         # Domain entity (optional)
-└── <name>.module.ts         # Module definition (@Module)
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : template === "cqrs" ? `\`\`\`
 <name>/
@@ -990,7 +1082,7 @@ ${template === "ddd" ? `\`\`\`
 │   └── <name>-created.event.ts
 ├── <name>.controller.ts     # HTTP routes
 ├── <name>.repository.ts     # Data access
-└── <name>.module.ts         # Module definition
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : template === "graphql" ? `\`\`\`
 resolvers/
@@ -1003,7 +1095,7 @@ resolvers/
 ├── <name>.controller.ts     # HTTP routes (@Controller)
 ├── <name>.service.ts        # Business logic (@Service)
 ├── <name>.dto.ts            # Request/response schemas (Zod)
-└── <name>.module.ts         # Module definition (@Module)
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : `\`\`\`
 src/
@@ -1039,8 +1131,8 @@ If not using generators:
 - [ ] Create \`src/modules/<name>/<name>.controller.ts\`
 - [ ] Add \`@Controller('/path')\` decorator
 - [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
-- [ ] Create module file with \`@Module({ controllers: [NameController] })\`
-- [ ] Register module in \`src/modules/index.ts\`
+- [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
+- [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
 - [ ] Test with \`kick dev\`
 
 ### Manual Service
@@ -1048,7 +1140,7 @@ If not using generators:
 - [ ] Create \`src/modules/<name>/<name>.service.ts\`
 - [ ] Add \`@Service()\` decorator
 - [ ] Inject dependencies with \`@Autowired()\`
-- [ ] Register in module \`providers\` array
+- [ ] Inject via \`@Autowired()\` where needed
 - [ ] Write unit tests
 
 ### New Middleware
@@ -1073,9 +1165,12 @@ Use \`kick add\` to install KickJS packages with correct peer dependencies:
 ### Generate CRUD Module
 
 \`\`\`bash
-kick g scaffold user name:string email:string age:number
+kick g scaffold user name:string email:string:optional age:number
 \`\`\`
 
+Append \`:optional\` for optional fields (shell-safe, no quoting needed).
+Quoted \`?\` syntax also works: \`"email:string?"\` or \`"email?:string"\`.
+
 This creates a full CRUD module with:
 - Controller with GET, POST, PUT, DELETE routes
 - Service with business logic
@@ -1191,7 +1286,17 @@ private config!: ConfigService
 const port = this.config.get('PORT')  // typed: number
 \`\`\`
 
-3. **Direct \`process.env\`** — avoid in app code; bypasses Zod
+3. **Standalone utilities** (no DI — works in scripts, CLI, plain files):
+\`\`\`ts
+import { loadEnv, getEnv, reloadEnv, resetEnvCache } from '@forinda/kickjs/config'
+
+const env = loadEnv(schema)         // Parse + validate all vars
+const port = getEnv('PORT')         // Single value lookup
+reloadEnv()                         // Re-read .env from disk
+resetEnvCache()                     // Full reset (for tests)
+\`\`\`
+
+4. **Direct \`process.env\`** — avoid in app code; bypasses Zod
    coercion and the typed \`KickEnv\` registry.
 
 > **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
@@ -1200,6 +1305,22 @@ const port = this.config.get('PORT')  // typed: number
 > \`@Value()\` only works because of its raw \`process.env\` fallback —
 > Zod coercion + schema defaults are silently skipped.
 
+## Standalone Utilities (No DI Required)
+
+These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller\`:
+
+| Utility | Import | Example |
+|---------|--------|---------|
+| \`Logger.for(name)\` | \`@forinda/kickjs\` | \`const log = Logger.for('MyScript')\` |
+| \`createLogger(name)\` | \`@forinda/kickjs\` | \`const log = createLogger('Worker')\` |
+| \`createToken<T>(name)\` | \`@forinda/kickjs\` | \`const TOKEN = createToken<string>('db.url')\` |
+| \`ref(value)\` | \`@forinda/kickjs\` | \`const count = ref(0)\` |
+| \`computed(fn)\` | \`@forinda/kickjs\` | \`const doubled = computed(() => count.value * 2)\` |
+| \`watch(source, cb)\` | \`@forinda/kickjs\` | \`watch(() => count.value, (v) => log(v))\` |
+| \`reactive(obj)\` | \`@forinda/kickjs\` | \`const state = reactive({ count: 0 })\` |
+| \`HttpException\` | \`@forinda/kickjs\` | \`throw new HttpException(404, 'Not found')\` |
+| \`HttpStatus\` | \`@forinda/kickjs\` | \`HttpStatus.NOT_FOUND // 404\` |
+
 ## Key Decorators
 
 ### HTTP Routes
@@ -1214,7 +1335,7 @@ const port = this.config.get('PORT')  // typed: number
 ### Dependency Injection
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Module({})\` | Define feature module |
+| \`AppModule\` interface | Define feature module (implements \`routes()\`) |
 | \`@Service()\` | Register singleton service |
 | \`@Repository()\` | Register repository |
 | \`@Autowired()\` | Property injection |
@@ -1310,6 +1431,26 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
 	await writeFileSafe(join(dir, "CLAUDE.md"), generateClaude(name, template, packageManager));
 	await writeFileSafe(join(dir, "AGENTS.md"), generateAgents(name, template, packageManager));
+	if (options.installDeps) {
+		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
+		try {
+			execSync(`${packageManager} install`, {
+				cwd: dir,
+				stdio: "inherit"
+			});
+			console.log("\n  Dependencies installed successfully!");
+		} catch {
+			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
+		}
+	}
+	try {
+		const { runTypegen } = await Promise.resolve().then(() => typegen_exports);
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
 	if (options.initGit) try {
 		execSync("git init", {
 			cwd: dir,
@@ -1331,26 +1472,6 @@ async function initProject(options) {
 	} catch {
 		log("Warning: git init failed (git may not be installed)");
 	}
-	if (options.installDeps) {
-		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
-		try {
-			execSync(`${packageManager} install`, {
-				cwd: dir,
-				stdio: "inherit"
-			});
-			console.log("\n  Dependencies installed successfully!");
-		} catch {
-			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
-		}
-	}
-	try {
-		const { runTypegen } = await Promise.resolve().then(() => typegen_exports);
-		await runTypegen({
-			cwd: dir,
-			allowDuplicates: true,
-			silent: true
-		});
-	} catch {}
 	console.log("\n  Project scaffolded successfully!");
 	console.log();
 	const needsCd = dir !== process.cwd();
@@ -1522,26 +1643,18 @@ function toKebabCase(name) {
 }
 /**
 * Pluralize a kebab-case name for directory/file names.
-* If already plural (ends in 's'), returns as-is.
+* Uses the `pluralize` npm package for correct English pluralization
+* including irregulars (person → people, status → statuses, child → children).
 */
 function pluralize(name) {
-	if (name.endsWith("s")) return name;
-	if (name.endsWith("x") || name.endsWith("z")) return name + "es";
-	if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
-	if (name.endsWith("y") && !/[aeiou]y$/.test(name)) return name.slice(0, -1) + "ies";
-	return name + "s";
+	return pkg.plural(name);
 }
 /**
 * Pluralize a PascalCase name for class identifiers.
-* If already plural (ends in 's'), returns as-is.
 * Used for `List${pluralPascal}UseCase` to avoid `ListUserssUseCase`.
 */
 function pluralizePascal(name) {
-	if (name.endsWith("s")) return name;
-	if (name.endsWith("x") || name.endsWith("z")) return name + "es";
-	if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
-	if (name.endsWith("y") && !/[aeiou]y$/i.test(name)) return name.slice(0, -1) + "ies";
-	return name + "s";
+	return pkg.plural(name);
 }
 //#endregion
 //#region src/generators/templates/module-index.ts
@@ -3541,6 +3654,140 @@ export class ${pascal}Adapter implements AppAdapter {
 	return files;
 }
 //#endregion
+//#region src/generators/plugin.ts
+/**
+* Scaffold a `KickPlugin` under `src/plugins/<name>.plugin.ts`.
+*
+* Plugins are the canonical place to wire DI bindings, load extra
+* modules, add middleware, or attach startup hooks without writing a
+* full adapter. The generated template implements every optional
+* `KickPlugin` hook with commented examples so users can uncomment
+* the ones they need and delete the rest.
+*/
+async function generatePlugin(options) {
+	const { name, outDir } = options;
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const factoryName = `${toCamelCase(name)}Plugin`;
+	const files = [];
+	const filePath = join(outDir, `${kebab}.plugin.ts`);
+	await writeFileSafe(filePath, `import type { KickPlugin, Container, AppAdapter, AppModuleClass } from '@forinda/kickjs'
+
+/**
+ * Options for the ${pascal} plugin.
+ *
+ * Plugins typically take a small options object in their factory so
+ * callers can configure them inline at bootstrap time. Keep the
+ * shape narrow — anything derived from the environment should be
+ * read via \`getEnv\` inside the plugin itself, not forced onto the
+ * caller.
+ */
+export interface ${pascal}PluginOptions {
+  // Add your plugin options here, for example:
+  // enabled?: boolean
+  // apiKey?: string
+}
+
+/**
+ * ${pascal} plugin.
+ *
+ * A \`KickPlugin\` bundles DI bindings, modules, adapters, and
+ * middleware into one object that can be added to \`bootstrap({ plugins })\`.
+ * Every hook is optional — delete the ones you don't need and keep
+ * only the surface your plugin actually uses.
+ *
+ * Lifecycle order:
+ *
+ *   1. \`register(container)\`   — runs before user modules load. Use
+ *      it to bind services that modules depend on.
+ *   2. \`modules()\`               — plugin modules load before user modules.
+ *   3. \`adapters()\`              — plugin adapters are added before user adapters.
+ *   4. \`middleware()\`            — plugin middleware runs before user middleware.
+ *   5. \`onReady(container)\`     — runs after the app has fully bootstrapped.
+ *   6. \`shutdown()\`              — runs on graceful shutdown.
+ *
+ * @example
+ * \`\`\`ts
+ * import { bootstrap } from '@forinda/kickjs'
+ * import { ${factoryName} } from './plugins/${kebab}.plugin'
+ *
+ * export const app = await bootstrap({
+ *   modules,
+ *   plugins: [${factoryName}({ /* options */ })],
+ * })
+ * \`\`\`
+ */
+export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin {
+  return {
+    name: '${kebab}',
+
+    /**
+     * Register DI bindings before modules load.
+     * Use \`container.registerInstance(TOKEN, value)\` for singletons
+     * and \`container.registerFactory(TOKEN, () => ...)\` for lazy
+     * constructions.
+     */
+    register(container: Container): void {
+      // Example: bind a configured service to a DI token
+      // container.registerInstance(MY_TOKEN, new MyService(options))
+    },
+
+    /**
+     * Return module classes this plugin contributes to the app.
+     * These load before user modules, so plugin controllers and
+     * services are available for user code to \`@Autowired\`.
+     */
+    modules(): AppModuleClass[] {
+      return [
+        // ExampleModule,
+      ]
+    },
+
+    /**
+     * Return adapter instances to be added to the application.
+     * Plugin adapters are added before user adapters.
+     */
+    adapters(): AppAdapter[] {
+      return [
+        // new MyAdapter({ ... }),
+      ]
+    },
+
+    /**
+     * Return Express middleware entries to be added to the global
+     * pipeline. Plugin middleware runs before user-defined middleware.
+     */
+    middleware(): any[] {
+      return [
+        // helmet(),
+        // myCustomMiddleware(options),
+      ]
+    },
+
+    /**
+     * Called after the application has fully bootstrapped. Use this
+     * for post-startup work like logging, health checks, or warming
+     * a cache. Runs once per process.
+     */
+    async onReady(container: Container): Promise<void> {
+      // const logger = container.resolve(Logger)
+      // logger.info('${pascal} plugin ready')
+    },
+
+    /**
+     * Called during graceful shutdown. Clean up any long-lived
+     * resources this plugin owns (connections, timers, subscriptions).
+     */
+    async shutdown(): Promise<void> {
+      // await this.connection?.close()
+    },
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
 //#region src/utils/resolve-out-dir.ts
 /**
 * DDD folder mapping — nested layered architecture.
@@ -3585,13 +3832,14 @@ const CQRS_FOLDER_MAP = {
 *   3. Standalone default directory
 */
 function resolveOutDir(options) {
-	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd" } = options;
+	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd", shouldPluralize = true } = options;
 	if (outDir) return resolve(outDir);
 	if (moduleName) {
 		const folderMap = pattern === "ddd" ? DDD_FOLDER_MAP : pattern === "cqrs" ? CQRS_FOLDER_MAP : FLAT_FOLDER_MAP;
-		const plural = pluralize(toKebabCase(moduleName));
+		const kebab = toKebabCase(moduleName);
+		const folder = shouldPluralize ? pluralize(kebab) : kebab;
 		const subfolder = folderMap[type] ?? "";
-		const base = join(modulesDir, plural);
+		const base = join(modulesDir, folder);
 		return resolve(subfolder ? join(base, subfolder) : base);
 	}
 	return resolve(defaultDir);
@@ -3606,7 +3854,8 @@ async function generateMiddleware(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/middleware",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const camel = toCamelCase(name);
@@ -3650,7 +3899,8 @@ async function generateGuard(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/guards",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const camel = toCamelCase(name);
@@ -3707,7 +3957,8 @@ async function generateService(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/services",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3736,7 +3987,8 @@ async function generateController(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/controllers",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3777,7 +4029,8 @@ async function generateDto(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/dtos",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3996,7 +4249,10 @@ export class ${pascal}Job {
 *   json      → z.any()
 *   enum:a,b  → z.enum(['a','b'])
 *
-* Append ? for optional: title:string  body:text?  published:boolean?
+* Mark optional fields — three equivalent syntaxes:
+*   body:text:optional  ← recommended (shell-safe, no quoting needed)
+*   body?:text          ← needs quoting in bash/zsh ("body?:text")
+*   body:text?          ← needs quoting in bash/zsh ("body:text?")
 */
 const TYPE_MAP = {
 	string: {
@@ -4048,11 +4304,23 @@ function parseFields(raw) {
 	return raw.map((f) => {
 		const colonIdx = f.indexOf(":");
 		if (colonIdx === -1) throw new Error(`Invalid field: "${f}". Use format: name:type (e.g. title:string)`);
-		const namePart = f.slice(0, colonIdx);
-		const typePart = f.slice(colonIdx + 1);
+		let namePart = f.slice(0, colonIdx);
+		let typePart = f.slice(colonIdx + 1);
 		if (!namePart || !typePart) throw new Error(`Invalid field: "${f}". Use format: name:type (e.g. title:string)`);
-		const optional = typePart.endsWith("?");
-		const cleanType = optional ? typePart.slice(0, -1) : typePart;
+		let optional = false;
+		if (typePart.endsWith(":optional")) {
+			typePart = typePart.slice(0, -9);
+			optional = true;
+		}
+		if (namePart.endsWith("?")) {
+			namePart = namePart.slice(0, -1);
+			optional = true;
+		}
+		if (typePart.endsWith("?")) {
+			typePart = typePart.slice(0, -1);
+			optional = true;
+		}
+		const cleanType = typePart;
 		if (cleanType.startsWith("enum:")) {
 			const values = cleanType.slice(5).split(",");
 			return {
@@ -4517,14 +4785,16 @@ async function autoRegisterModule(modulesDir, pascal, plural) {
 //#region src/generators/test.ts
 async function generateTest(options) {
 	const { name, moduleName, modulesDir } = options;
+	const shouldPluralize = options.pluralize ?? true;
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
 	const files = [];
 	let outDir;
 	if (options.outDir) outDir = resolve(options.outDir);
 	else if (moduleName) {
-		const modPlural = pluralize(toKebabCase(moduleName));
-		outDir = resolve(join(modulesDir ?? "src/modules", modPlural, "__tests__"));
+		const modKebab = toKebabCase(moduleName);
+		const modFolder = shouldPluralize ? pluralize(modKebab) : modKebab;
+		outDir = resolve(join(modulesDir ?? "src/modules", modFolder, "__tests__"));
 	} else outDir = resolve("src/__tests__");
 	const filePath = join(outDir, `${kebab}.test.ts`);
 	await writeFileSafe(filePath, `import { describe, it, expect, beforeEach } from 'vitest'
@@ -5699,56 +5969,72 @@ function registerGenerateCommand(program) {
 			outDir: resolve(opts.out)
 		}), dryRun);
 	});
+	gen.command("plugin <name>").description("Generate a KickPlugin with DI, modules, adapters, middleware, and lifecycle hooks").option("-o, --out <dir>", "Output directory", "src/plugins").action(async (name, opts, cmd) => {
+		const dryRun = isDryRun(cmd);
+		setDryRun(dryRun);
+		printGenerated(await generatePlugin({
+			name,
+			outDir: resolve(opts.out)
+		}), dryRun);
+	});
 	gen.command("middleware <name>").description("Generate an Express middleware function\n  Use -m to scope it to a module: kick g middleware auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateMiddleware({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("guard <name>").description("Generate a route guard (auth, roles, etc.)\n  Use -m to scope it to a module: kick g guard admin -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateGuard({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("service <name>").description("Generate a @Service() class\n  Use -m to scope it to a module: kick g service payment -m orders").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateService({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("controller <name>").description("Generate a @Controller() class with basic routes\n  Use -m to scope it to a module: kick g controller auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateController({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 		await runPostTypegen(dryRun);
 	});
@@ -5756,24 +6042,28 @@ function registerGenerateCommand(program) {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateDto({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("test <name>").description("Generate a Vitest test scaffold\n  Use -m to scope it to a module: kick g test user-service -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module's __tests__/ folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
-		const modulesDir = resolveModuleConfig(await loadKickConfig(process.cwd())).dir ?? "src/modules";
+		const mc = resolveModuleConfig(await loadKickConfig(process.cwd()));
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateTest({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
-			modulesDir
+			modulesDir,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("resolver <name>").description("Generate a GraphQL @Resolver class with @Query and @Mutation methods").option("-o, --out <dir>", "Output directory", "src/resolvers").action(async (name, opts, cmd) => {
@@ -5793,11 +6083,11 @@ function registerGenerateCommand(program) {
 			queue: opts.queue
 		}), dryRun);
 	});
-	gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text published:boolean?\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Append ? for optional fields: description:text?").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts, cmd) => {
+	gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text:optional published:boolean:optional\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Optional: append :optional (shell-safe):  description:text:optional\n            or use ? with quoting:           \"description:text?\" or \"description?:text\"").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		if (rawFields.length === 0) {
-			console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text published:boolean\n");
+			console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text:optional published:boolean:optional\n  Optional: append :optional (shell-safe, no quoting needed)\n");
 			process.exit(1);
 		}
 		const mc = resolveModuleConfig(await loadKickConfig(process.cwd()));
@@ -6292,6 +6582,11 @@ const PACKAGE_REGISTRY = {
 		peers: [],
 		description: "Multi-channel notifications — email, Slack, Discord, webhook"
 	},
+	mcp: {
+		pkg: "@forinda/kickjs-mcp",
+		peers: ["@modelcontextprotocol/sdk"],
+		description: "Model Context Protocol server — expose @Controller endpoints as AI tools"
+	},
 	testing: {
 		pkg: "@forinda/kickjs-testing",
 		peers: [],
@@ -6375,6 +6670,616 @@ function registerAddCommand(program) {
 	});
 }
 //#endregion
+//#region src/explain/known-issues.ts
+function includesAll(haystack, needles) {
+	const lower = haystack.toLowerCase();
+	return needles.every((n) => lower.includes(n.toLowerCase()));
+}
+function includesAny(haystack, needles) {
+	const lower = haystack.toLowerCase();
+	return needles.some((n) => lower.includes(n.toLowerCase()));
+}
+const KNOWN_ISSUES = [
+	{ match(input, _ctx) {
+		const hasConfigGetUndefined = includesAll(input, ["config", "get"]) && includesAny(input, ["undefined", "null"]);
+		const hasValueUndefined = input.includes("@Value") && includesAny(input, ["undefined", "is not defined"]);
+		if (!hasConfigGetUndefined && !hasValueUndefined) return null;
+		return {
+			confidence: hasConfigGetUndefined && hasValueUndefined ? 90 : 75,
+			diagnosis: {
+				id: "env-schema-not-registered",
+				title: "ConfigService.get() returns undefined for user-defined keys",
+				explanation: "Your src/index.ts is missing `import \"./config\"`. That side-effect import\nregisters the env schema with kickjs at module-load time. Without it,\nConfigService falls back to the base schema (PORT/NODE_ENV/LOG_LEVEL only)\nand every user-defined key reads as undefined. @Value() may *appear* to\nwork via a raw process.env fallback, but Zod coercion and schema defaults\nare silently skipped.",
+				fix: "Add this line to src/index.ts near the top, before bootstrap() runs:",
+				codeBefore: "import 'reflect-metadata'\nimport { bootstrap } from '@forinda/kickjs'\nimport { modules } from './modules'\n",
+				codeAfter: "import 'reflect-metadata'\nimport './config'  // ← add this — registers env schema\nimport { bootstrap } from '@forinda/kickjs'\nimport { modules } from './modules'\n",
+				docs: "https://forinda.github.io/kick-js/guide/configuration.html#wiring-the-schema-at-startup"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		const hasTestContext = includesAny(input, [
+			"vitest",
+			"test",
+			"spec",
+			"__tests__",
+			".test."
+		]);
+		if (!includesAny(input, [
+			"already registered",
+			"already exists",
+			"duplicate",
+			"has been registered"
+		])) return null;
+		return {
+			confidence: hasTestContext ? 85 : 60,
+			diagnosis: {
+				id: "container-not-reset-in-tests",
+				title: "DI container leaks between test cases",
+				explanation: "KickJS decorators register classes on the global Container at import time.\nWhen vitest re-imports your modules across tests, the same class can be\nregistered twice and the container throws. The fix is to wipe the\ncontainer between tests so each case starts fresh.",
+				fix: "Add Container.reset() to a beforeEach hook in the failing test file:",
+				codeAfter: "import { describe, it, beforeEach } from 'vitest'\nimport { Container } from '@forinda/kickjs'\n\ndescribe('UserController', () => {\n  beforeEach(() => Container.reset())\n\n  it('does the thing', async () => { /* ... */ })\n})",
+				docs: "https://forinda.github.io/kick-js/guide/testing.html"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		if (!(input.includes("@Module") || includesAll(input, ["Module", "is not a function"]) || includesAll(input, ["Module", "no exported member"]))) return null;
+		return {
+			confidence: 80,
+			diagnosis: {
+				id: "module-decorator-not-found",
+				title: "KickJS does not have a @Module decorator (different pattern from NestJS)",
+				explanation: "NestJS uses @Module({ controllers, providers }). KickJS uses an interface\npattern instead: a class implements AppModule and exposes routes() that\nreturns the controller wiring. This was a deliberate choice — modules\nbecome explicit values rather than metadata, which makes them easier to\ncompose, test, and serialize.",
+				fix: "Replace the @Module decorator with an AppModule class:",
+				codeBefore: "import { Module } from '@forinda/kickjs'  // ← does not exist\nimport { UserController } from './user.controller'\n\n@Module({\n  controllers: [UserController],\n})\nexport class UserModule {}",
+				codeAfter: "import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'\nimport { UserController } from './user.controller'\n\nexport class UserModule implements AppModule {\n  routes(): ModuleRoutes {\n    return {\n      path: '/users',\n      router: buildRoutes(UserController),\n      controller: UserController,\n    }\n  }\n}",
+				docs: "https://forinda.github.io/kick-js/guide/project-structure.html"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		if (!/KickRoutes\s*\[\s*['"](GET|POST|PUT|PATCH|DELETE)/i.test(input)) return null;
+		return {
+			confidence: 95,
+			diagnosis: {
+				id: "legacy-kick-routes-bracket-syntax",
+				title: "KickRoutes['POST /users'] is the legacy v1 syntax",
+				explanation: "KickJS v2 changed the typegen output from a flat string-keyed map to a\nnamespaced shape: KickRoutes.UserController[\"create\"] instead of\nKickRoutes[\"POST /users\"]. The new form is per-controller, per-method,\nand matches the actual class names so refactors propagate via\nrename-symbol instead of grep.",
+				fix: "Update the Ctx<...> type parameter to use the namespace form:",
+				codeBefore: "@Post('/', { body: createUserSchema })\ncreate(ctx: Ctx<KickRoutes['POST /users']>) { /* ... */ }",
+				codeAfter: "@Post('/', { body: createUserSchema, name: 'CreateUser' })\ncreate(ctx: Ctx<KickRoutes.UserController['create']>) { /* ... */ }",
+				docs: "https://forinda.github.io/kick-js/guide/typegen.html"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		const hasCluster = includesAny(input, [
+			"cluster",
+			"workers",
+			"two ports",
+			"duplicate server"
+		]);
+		const hasDevSignal = includesAny(input, [
+			"kick dev",
+			"vite",
+			"eaddrinuse",
+			"5173",
+			"5174",
+			"two servers"
+		]);
+		if (!hasCluster || !hasDevSignal) return null;
+		return {
+			confidence: 85,
+			diagnosis: {
+				id: "cluster-in-vite-dev",
+				title: "Cluster mode is incompatible with `kick dev` (Vite owns the server)",
+				explanation: "In dev mode, Vite owns the HTTP server. If your bootstrap passes\ncluster: { workers: N }, the framework forks N workers, each of which\nspins up its own Vite instance on a separate port. The fix landed in\nv2.2.5: McpAdapter (and bootstrap()) now detects Vite dev mode and\nsilently skips cluster, with a warning. If you see this on an older\nversion, upgrade or guard the cluster option behind NODE_ENV.",
+				fix: "Either upgrade to v2.2.5+ or gate cluster mode on production:",
+				codeAfter: "export const app = await bootstrap({\n  modules,\n  cluster: process.env.NODE_ENV === 'production' ? { workers: 4 } : false,\n})",
+				docs: "https://forinda.github.io/kick-js/guide/cluster.html"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		if (!includesAny(input, [
+			"reflect-metadata",
+			"Reflect.getMetadata is not a function",
+			"Reflect.defineMetadata",
+			"design:type",
+			"design:paramtypes"
+		])) return null;
+		return {
+			confidence: 90,
+			diagnosis: {
+				id: "reflect-metadata-missing",
+				title: "reflect-metadata is not loaded — DI cannot read decorator types",
+				explanation: "The DI container reads constructor parameter types via the\nreflect-metadata polyfill. The polyfill must be imported once,\nbefore any decorator runs. Most projects do this at the top of\nsrc/index.ts; missing the import causes obscure \"design:paramtypes\"\nor \"Reflect.getMetadata is not a function\" errors at runtime.",
+				fix: "Add the import at the very top of src/index.ts:",
+				codeAfter: "import 'reflect-metadata'  // ← must be the FIRST import\nimport './config'\nimport { bootstrap } from '@forinda/kickjs'\nimport { modules } from './modules'\n\nexport const app = await bootstrap({ modules })",
+				docs: "https://forinda.github.io/kick-js/guide/dependency-injection.html"
+			}
+		};
+	} },
+	{ match(input, _ctx) {
+		if (!includesAny(input, [
+			"404",
+			"cannot get",
+			"cannot post",
+			"no route"
+		])) return null;
+		return {
+			confidence: 50,
+			diagnosis: {
+				id: "module-not-registered",
+				title: "A 404 may indicate a module is not in the modules array",
+				explanation: "KickJS only mounts modules listed in `src/modules/index.ts`. If you\ngenerated a module via `kick g module foo` but the routes don't appear,\nthe most likely cause is that the module is missing from the exported\narray. The CLI usually wires this automatically, but a hand-edit can\ndrop the entry.",
+				fix: "Open src/modules/index.ts and verify the module is in the array:",
+				codeAfter: "import type { AppModuleClass } from '@forinda/kickjs'\nimport { UserModule } from './users/user.module'\nimport { TaskModule } from './tasks/task.module'  // ← was this missing?\n\nexport const modules: AppModuleClass[] = [UserModule, TaskModule]",
+				docs: "https://forinda.github.io/kick-js/guide/project-structure.html"
+			}
+		};
+	} }
+];
+/**
+* Run every matcher against the input and return the highest-confidence
+* hit, or `null` if no matcher cleared the 40-confidence threshold.
+*/
+function findBestMatch(input, ctx) {
+	let best = null;
+	for (const issue of KNOWN_ISSUES) {
+		let match = null;
+		try {
+			match = issue.match(input, ctx);
+		} catch {
+			continue;
+		}
+		if (!match || match.confidence < 40) continue;
+		if (!best || match.confidence > best.confidence) best = match;
+	}
+	return best;
+}
+//#endregion
+//#region src/explain/ai-fallback.ts
+/**
+* Ask the configured LLM for a diagnosis of `options.input`.
+*
+* Returns a discriminated result; callers should never assume the
+* LLM was reachable or produced valid output. The function catches
+* every expected failure mode and maps it to a friendly `unavailable`
+* or `error` result — the CLI can then decide how to present it.
+*/
+async function askAi(options) {
+	const provider = options.provider ?? "openai";
+	const apiKey = process.env.OPENAI_API_KEY;
+	if (provider === "openai" && !apiKey) return {
+		kind: "unavailable",
+		reason: "OPENAI_API_KEY environment variable is not set",
+		suggestion: "Set OPENAI_API_KEY in your shell, e.g.\n  export OPENAI_API_KEY=\"sk-...\"\n\nThen re-run `kick explain --ai \"<your error>\"`."
+	};
+	let aiModule;
+	try {
+		aiModule = await import("@forinda/kickjs-ai");
+	} catch {
+		return {
+			kind: "unavailable",
+			reason: "@forinda/kickjs-ai is not installed",
+			suggestion: "Install the AI package to enable the LLM fallback:\n  kick add ai\n\nOr manually:\n  pnpm add @forinda/kickjs-ai"
+		};
+	}
+	const { OpenAIProvider } = aiModule;
+	const instance = new OpenAIProvider({
+		apiKey,
+		defaultChatModel: options.model ?? "gpt-4o-mini"
+	});
+	const systemPrompt = buildSystemPrompt(options.cwd);
+	const userPrompt = `Error or stack trace:\n\n${options.input.trim()}`;
+	try {
+		const diagnosis = parseDiagnosisFromResponse((await instance.chat({ messages: [{
+			role: "system",
+			content: systemPrompt
+		}, {
+			role: "user",
+			content: userPrompt
+		}] })).content);
+		if (!diagnosis) return {
+			kind: "error",
+			message: "The LLM responded but the payload was not valid JSON in the expected shape. Try again, or file an issue with the error text."
+		};
+		return {
+			kind: "ok",
+			diagnosis
+		};
+	} catch (err) {
+		return {
+			kind: "error",
+			message: `LLM request failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+}
+/**
+* Build the system prompt that tells the LLM what KickJS is and how
+* to structure its response. The prompt is deliberately prescriptive:
+* the caller needs a JSON payload it can render via the same formatter
+* the known-issues path uses, so freeform text doesn't work.
+*
+* Keep this prompt short — every token counts at inference time and
+* the CLI is often called interactively.
+*/
+function buildSystemPrompt(cwd) {
+	return [
+		"You are a diagnostic assistant for KickJS, a decorator-driven Node.js",
+		"framework built on Express 5 and TypeScript. KickJS projects use:",
+		"  - @Controller, @Get, @Post, @Autowired, @Service, @Value decorators",
+		"  - An AppModule interface with a routes() method (NOT a @Module decorator)",
+		"  - Zod schemas as both runtime validators and OpenAPI sources",
+		"  - Ctx<KickRoutes.ControllerName['method']> for typed request context",
+		"  - src/config/index.ts with defineEnv/loadEnv for env schema",
+		"  - A side-effect `import \"./config\"` in src/index.ts to register the schema",
+		"  - Container.reset() in beforeEach for DI test isolation",
+		"",
+		"When the user gives you an error message or stack trace, produce a",
+		"structured diagnosis that helps them fix the bug. You MUST respond",
+		"with a single JSON object (no surrounding prose, no markdown fences)",
+		"matching this shape:",
+		"",
+		"{",
+		"  \"id\": \"<kebab-case-identifier>\",",
+		"  \"title\": \"<one-line problem summary>\",",
+		"  \"explanation\": \"<multi-line explanation of what is wrong>\",",
+		"  \"fix\": \"<multi-line instructions for fixing the problem>\",",
+		"  \"codeBefore\": \"<optional: broken code snippet>\",",
+		"  \"codeAfter\": \"<optional: corrected code snippet>\",",
+		"  \"docs\": \"<optional: KickJS doc URL that discusses this topic>\"",
+		"}",
+		"",
+		"The KickJS docs live at https://forinda.github.io/kick-js/ — prefer",
+		"that domain for any doc links you suggest.",
+		cwd ? `The project is located at ${cwd}.` : ""
+	].filter((line) => line.length > 0).join("\n");
+}
+/**
+* Extract a `Diagnosis` object from the LLM response content.
+*
+* Tries three strategies in order:
+*   1. Parse the whole content as JSON directly
+*   2. Strip a surrounding markdown fence (```json ... ```)
+*   3. Find the first balanced `{ ... }` block and parse that
+*
+* Returns null if none of the strategies produce a valid object with
+* at least the required fields (id, title, explanation, fix).
+*/
+function parseDiagnosisFromResponse(content) {
+	const attempts = [
+		content,
+		stripMarkdownFence(content),
+		extractFirstJsonObject(content)
+	].filter((s) => s !== null);
+	for (const attempt of attempts) try {
+		const parsed = JSON.parse(attempt);
+		if (isValidDiagnosis(parsed)) return parsed;
+	} catch {
+		continue;
+	}
+	return null;
+}
+function stripMarkdownFence(text) {
+	const match = text.match(/```(?:json)?\s*\n([\s\S]*?)```/);
+	return match ? match[1]?.trim() ?? null : null;
+}
+function extractFirstJsonObject(text) {
+	const start = text.indexOf("{");
+	if (start === -1) return null;
+	let depth = 0;
+	let inString = false;
+	let escape = false;
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (escape) {
+			escape = false;
+			continue;
+		}
+		if (ch === "\\" && inString) {
+			escape = true;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === "{") depth++;
+		if (ch === "}") {
+			depth--;
+			if (depth === 0) return text.slice(start, i + 1);
+		}
+	}
+	return null;
+}
+function isValidDiagnosis(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.id === "string" && typeof v.title === "string" && typeof v.explanation === "string" && typeof v.fix === "string";
+}
+//#endregion
+//#region src/commands/explain.ts
+/**
+* `kick explain` — explain a KickJS error and suggest a fix.
+*
+* The command takes an error message (positional arg, --message flag,
+* or stdin), runs it through a registry of known KickJS pitfalls, and
+* prints the highest-confidence diagnosis with a code fix and a doc
+* link. If no matcher hits, it prints a "no match" message — the
+* --ai flag (planned) will fall back to an LLM call against the
+* registered AiProvider.
+*
+* The known-issues registry lives in src/explain/known-issues.ts and
+* is the single source of truth for KickJS-specific advice. Adding a
+* new entry takes ~30 lines and gives every user a permanent fix path.
+*
+* @example
+* ```bash
+* # As a positional arg
+* kick explain "config.get('DATABASE_URL') returned undefined"
+*
+* # Via stdin (pipe a stack trace)
+* pnpm test 2>&1 | kick explain
+*
+* # Via --message flag
+* kick explain --message "Reflect.getMetadata is not a function"
+* ```
+*/
+function registerExplainCommand(program) {
+	program.command("explain [message]").description("Explain a KickJS error and suggest a fix").option("-m, --message <text>", "Error message to explain (alternative to positional arg)").option("--ai", "Fall back to LLM if no known-issue matches (requires @forinda/kickjs-ai)").option("--model <name>", "Model name for the --ai fallback", "gpt-4o-mini").option("--json", "Output the diagnosis as JSON for tooling integration").action(async (positional, opts) => {
+		const input = await resolveInput(positional, opts.message);
+		if (!input || input.trim().length === 0) {
+			process.stderr.write("Error: no input provided.\n\nPass a message as a positional arg, --message flag, or pipe via stdin:\n  kick explain \"config.get returned undefined\"\n  pnpm test 2>&1 | kick explain\n");
+			process.exit(1);
+		}
+		const ctx = buildExplainContext();
+		const match = findBestMatch(input, ctx);
+		if (opts.json && match) {
+			process.stdout.write(JSON.stringify({
+				matched: true,
+				...match
+			}, null, 2) + "\n");
+			return;
+		}
+		if (match) {
+			printDiagnosis(input, match.diagnosis, match.confidence);
+			return;
+		}
+		if (!opts.ai) {
+			if (opts.json) {
+				process.stdout.write(JSON.stringify({ matched: false }, null, 2) + "\n");
+				process.exit(2);
+			}
+			printNoMatch(input, false);
+			process.exit(2);
+		}
+		const result = await askAi({
+			input,
+			model: opts.model,
+			cwd: ctx.cwd
+		});
+		if (opts.json) {
+			process.stdout.write(JSON.stringify(aiResultToJson(result), null, 2) + "\n");
+			process.exit(result.kind === "ok" ? 0 : 2);
+		}
+		printAiResult(input, result);
+		process.exit(result.kind === "ok" ? 0 : 2);
+	});
+}
+/** Serialize an AskAiResult for `--json` output. */
+function aiResultToJson(result) {
+	if (result.kind === "ok") return {
+		matched: true,
+		source: "ai",
+		diagnosis: result.diagnosis
+	};
+	if (result.kind === "unavailable") return {
+		matched: false,
+		aiUnavailable: true,
+		reason: result.reason
+	};
+	return {
+		matched: false,
+		aiError: true,
+		error: result.message
+	};
+}
+/** Render an AskAiResult to stdout using the same formatting as local matches. */
+function printAiResult(input, result) {
+	if (result.kind === "ok") {
+		printDiagnosis(input, result.diagnosis, -1, true);
+		return;
+	}
+	if (result.kind === "unavailable") {
+		process.stdout.write(`\n  Explaining: ${truncate(input.trim(), 200)}\n\n`);
+		process.stdout.write(`  AI fallback unavailable: ${result.reason}\n\n`);
+		process.stdout.write(`${indent(result.suggestion, "  ")}\n\n`);
+		return;
+	}
+	process.stdout.write(`\n  Explaining: ${truncate(input.trim(), 200)}\n\n`);
+	process.stdout.write(`  AI fallback error: ${result.message}\n\n`);
+}
+/**
+* Resolve the error text from positional arg, --message flag, or stdin.
+*
+* Precedence: positional > flag > stdin. We only read stdin if neither
+* of the first two were provided AND stdin is not a TTY (i.e. something
+* is being piped in). Reading from a real TTY would hang waiting for
+* the user to type, which is never what they want.
+*/
+async function resolveInput(positional, flag) {
+	if (positional && positional.trim().length > 0) return positional;
+	if (flag && flag.trim().length > 0) return flag;
+	if (process.stdin.isTTY) return "";
+	return readStdinAll();
+}
+function readStdinAll() {
+	return new Promise((resolve, reject) => {
+		let buffer = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => {
+			buffer += chunk;
+		});
+		process.stdin.on("end", () => resolve(buffer));
+		process.stdin.on("error", reject);
+	});
+}
+/**
+* Build a small context object the matchers can use to check project
+* state — e.g. "does this project have a src/config/index.ts?".
+*
+* Kept intentionally minimal to avoid pulling the full kick.config
+* loader into a fast-path command. Matchers should treat this as
+* best-effort and degrade gracefully when ctx is undefined.
+*/
+function buildExplainContext() {
+	const cwd = process.cwd();
+	return {
+		cwd,
+		hasFile: (path) => existsSync(resolve(cwd, path))
+	};
+}
+function printDiagnosis(input, d, confidence, aiLabel = false) {
+	const inputSnippet = truncate(input.trim(), 200);
+	const label = aiLabel ? "AI-generated — verify before applying" : labelConfidence(confidence);
+	process.stdout.write(`\n  Explaining: ${inputSnippet}\n`);
+	process.stdout.write(`\n  Match: ${d.id}  (${label})\n`);
+	process.stdout.write(`  Title: ${d.title}\n`);
+	process.stdout.write(`\n  Diagnosis:\n${indent(d.explanation, "    ")}\n`);
+	process.stdout.write(`\n  Fix:\n${indent(d.fix, "    ")}\n`);
+	if (d.codeBefore) process.stdout.write(`\n  Before:\n${indent(d.codeBefore, "      ")}\n`);
+	if (d.codeAfter) process.stdout.write(`\n  After:\n${indent(d.codeAfter, "      ")}\n`);
+	if (d.docs) process.stdout.write(`\n  Docs: ${d.docs}\n`);
+	process.stdout.write("\n");
+}
+function printNoMatch(input, aiRequested) {
+	const snippet = truncate(input.trim(), 200);
+	process.stdout.write(`\n  Explaining: ${snippet}\n\n`);
+	if (aiRequested) process.stdout.write("  No known-issue matched, and --ai fallback is not yet wired.\n  When @forinda/kickjs-ai ships its provider implementations,\n  this command will call the configured LLM with the error +\n  project context and return a structured fix.\n\n");
+	else process.stdout.write("  No known-issue matched. Things you can try:\n\n    1. Check the framework docs for the error keywords:\n       https://forinda.github.io/kick-js/\n\n    2. Re-run with --ai to fall back to an LLM (requires\n       @forinda/kickjs-ai with a configured provider):\n       kick explain --ai \"<your error>\"\n\n    3. File an issue with the error text:\n       https://github.com/forinda/kick-js/issues/new\n\n");
+}
+function indent(text, prefix) {
+	return text.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
+function truncate(text, max) {
+	if (text.length <= max) return text;
+	return text.slice(0, max - 1) + "…";
+}
+function labelConfidence(score) {
+	if (score >= 90) return "high confidence";
+	if (score >= 70) return "good match";
+	if (score >= 50) return "medium confidence";
+	return "low confidence — verify manually";
+}
+//#endregion
+//#region src/commands/mcp.ts
+/**
+* `kick mcp` — Model Context Protocol commands.
+*
+* Two subcommands:
+* - `kick mcp` (default → `start`): runs the built application as an
+*   MCP server over stdio. The user's app must already wire `McpAdapter`
+*   from `@forinda/kickjs-mcp` into its bootstrap. The CLI just spawns
+*   the built entry as a subprocess with `KICK_MCP_STDIO=1`, which the
+*   adapter detects and uses to switch its transport from
+*   StreamableHTTP to stdio. The subprocess inherits stdin/stdout/stderr
+*   so the MCP wire protocol flows directly between the parent process
+*   (the MCP client — Claude Code, Cursor, etc.) and the child app.
+* - `kick mcp init`: generates a `.mcp.json` config file pointing at
+*   this project, ready to drop into a Claude Code / Cursor workspace.
+*
+* Logs MUST go to stderr in stdio mode — anything written to stdout
+* corrupts the JSON-RPC protocol stream. Pino's default stream is
+* stderr already, so this works out of the box for KickJS apps using
+* the framework's bundled logger.
+*/
+function registerMcpCommand(program) {
+	const mcp = program.command("mcp").description("Model Context Protocol commands (start | init)");
+	mcp.command("start", { isDefault: true }).description("Run the built application as an MCP server over stdio").option("-e, --entry <file>", "Entry file", "dist/index.js").option("--node-arg <arg...>", "Extra arguments to pass to node").action(runMcpServer);
+	mcp.command("init").description("Generate .mcp.json for Claude Code / Cursor / Zed").option("-n, --name <name>", "Server name (defaults to package.json name)").option("-o, --out <file>", "Output file", ".mcp.json").option("-f, --force", "Overwrite an existing entry without prompting").option("--global", "Write to ~/.mcp.json instead of the project root").action(initMcpConfig);
+}
+function runMcpServer(opts) {
+	const entry = resolve(opts.entry);
+	if (!existsSync(entry)) {
+		process.stderr.write(`Error: entry file not found: ${entry}\n\nBuild the app first with \`kick build\`, or pass a custom entry:\n  kick mcp -e dist/server.js\n`);
+		process.exit(1);
+	}
+	const nodeArgs = [...opts.nodeArg ?? [], entry];
+	const child = spawn(process.execPath, nodeArgs, {
+		stdio: "inherit",
+		env: {
+			...process.env,
+			KICK_MCP_STDIO: "1",
+			NODE_ENV: process.env.NODE_ENV ?? "production"
+		}
+	});
+	child.on("error", (err) => {
+		process.stderr.write(`Failed to start MCP server: ${err.message}\n`);
+		process.exit(1);
+	});
+	child.on("exit", (code, signal) => {
+		if (signal) {
+			process.kill(process.pid, signal);
+			return;
+		}
+		process.exit(code ?? 0);
+	});
+	const forward = (signal) => {
+		if (!child.killed) child.kill(signal);
+	};
+	process.on("SIGINT", () => forward("SIGINT"));
+	process.on("SIGTERM", () => forward("SIGTERM"));
+}
+function initMcpConfig(opts) {
+	const cwd = process.cwd();
+	const projectName = readPackageName(cwd) ?? basename(cwd);
+	const serverName = opts.name ?? projectName;
+	const outPath = opts.global ? resolve(process.env.HOME ?? ".", ".mcp.json") : resolve(cwd, opts.out);
+	const entry = {
+		command: "kick",
+		args: ["mcp"],
+		cwd
+	};
+	let config = { mcpServers: {} };
+	if (existsSync(outPath)) try {
+		const raw = readFileSync(outPath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && parsed.mcpServers) config = { mcpServers: { ...parsed.mcpServers } };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`Error: existing ${outPath} is not valid JSON (${message}).\nFix the file or pass --force to overwrite the entry.\n`);
+		process.exit(1);
+	}
+	if (config.mcpServers[serverName] && !opts.force) {
+		process.stderr.write(`Error: an entry for "${serverName}" already exists in ${outPath}.\nPass --force to overwrite it, or use --name to pick a different key.\n`);
+		process.exit(1);
+	}
+	config.mcpServers[serverName] = entry;
+	writeFileSync(outPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+	process.stdout.write(`\n  ✓ Wrote MCP server entry "${serverName}" to ${outPath}\n\n  To activate it:\n    1. Build your app:    kick build\n    2. Restart your MCP client (Claude Code, Cursor, Zed)\n    3. The server should appear in the client's tool picker\n\n`);
+}
+/**
+* Read the `name` field from the project's `package.json`. Returns
+* null if the file is missing or unparseable — callers fall back to
+* the directory name in that case.
+*/
+function readPackageName(cwd) {
+	const pkgPath = resolve(cwd, "package.json");
+	if (!existsSync(pkgPath)) return null;
+	try {
+		const raw = readFileSync(pkgPath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.name === "string") return parsed.name;
+		return null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/commands/tinker.ts
 function registerTinkerCommand(program) {
 	program.command("tinker").description("Interactive REPL with DI container and services loaded").option("-e, --entry <file>", "Entry file to load", "src/index.ts").action(async (opts) => {
@@ -6613,10 +7518,10 @@ function registerTypegenCommand(program) {
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const pkg$1 = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 async function main() {
 	const program = new Command();
-	program.name("kick").description("KickJS — A production-grade, decorator-driven Node.js framework").version(pkg.version);
+	program.name("kick").description("KickJS — A production-grade, decorator-driven Node.js framework").version(pkg$1.version);
 	const config = await loadKickConfig(process.cwd());
 	registerInitCommand(program);
 	registerGenerateCommand(program);
@@ -6625,6 +7530,8 @@ async function main() {
 	registerInspectCommand(program);
 	registerAddCommand(program);
 	registerListCommand(program);
+	registerExplainCommand(program);
+	registerMcpCommand(program);
 	registerTinkerCommand(program);
 	registerRemoveCommand(program);
 	registerTypegenCommand(program);