@forinda/kickjs-cli 3.2.0 → 4.0.0

package/dist/index.d.mts

@@ -38,6 +38,33 @@ type RepoTypeConfig = BuiltinRepoType$1 | CustomRepoType;
  * entirely (the route entries will keep `body: unknown`).
  */
 type SchemaValidator = 'zod' | false;
+/**
+ * One entry in the typed `assetMap` config record (`assets-plan.md`).
+ * Each entry names a source directory whose files become addressable
+ * via the `assets.<name>.*` typed accessor at runtime.
+ */
+interface AssetMapEntry {
+  /**
+   * Source directory, relative to project root. Required. The directory
+   * must exist when `kick build` runs — `loadKickConfig` warns when an
+   * entry points at a missing directory but doesn't fail the load
+   * (the typegen + build steps surface the error in context instead).
+   */
+  src: string;
+  /**
+   * Destination directory inside `dist/`. Defaults to `dist/<name>/`
+   * where `<name>` is the assetMap key. Override when the consumer of
+   * the assets expects a non-standard layout (e.g. an existing
+   * downstream tool reads from `dist/templates/...`).
+   */
+  dest?: string;
+  /**
+   * Glob pattern for which files to include. Defaults to `**\/*` (all
+   * files). Files that don't match are NOT copied — `assetMap` is
+   * selective by design (unlike `copyDirs` which copies everything).
+   */
+  glob?: string;
+}
 /** Typegen settings — controls .kickjs/types/* generation */
 interface TypegenConfig {
   /**
@@ -150,14 +177,6 @@ interface KickConfig {
    * packageManager: 'pnpm'
    */
   packageManager?: PackageManager;
-  /** @deprecated Use `modules.dir` instead */
-  modulesDir?: string;
-  /** @deprecated Use `modules.repo` instead */
-  defaultRepo?: RepoTypeConfig;
-  /** @deprecated Use `modules.schemaDir` instead */
-  schemaDir?: string;
-  /** @deprecated Use `modules.pluralize` instead */
-  pluralize?: boolean;
   /**
    * Directories to copy to dist/ after build.
    * Useful for EJS templates, email templates, static assets, etc.
@@ -175,6 +194,48 @@ interface KickConfig {
     src: string;
     dest?: string;
   }>;
+  /**
+   * Build output settings. The asset manager + `kick build`'s copy
+   * steps honour these — adopters who use Vite's `build.outDir =
+   * 'out'` (or any non-default) should mirror the value here so
+   * `assets.x.y()` paths line up with where Vite actually wrote.
+   *
+   * @example
+   * ```ts
+   * build: { outDir: 'out' }
+   * ```
+   */
+  build?: {
+    /**
+     * Output directory, relative to project root. Defaults to
+     * `'dist'`. The asset manager emits its manifest + copies
+     * assetMap entries into this directory (under a per-namespace
+     * subdirectory by default; override per-entry via `dest`).
+     */
+    outDir?: string;
+  };
+  /**
+   * Typed, addressable assets — see `assets-plan.md`. Each entry maps
+   * a logical namespace name to a source directory. The build pipeline
+   * auto-derives the necessary copy step + emits a manifest at
+   * `dist/.kickjs-assets.json`; the runtime exposes
+   * `import { assets } from '@forinda/kickjs'` so adopters can resolve
+   * paths without dev/prod branching.
+   *
+   * `copyDirs` is unchanged — `assetMap` is a separate, opt-in surface.
+   * Adopters who want raw directory copies keep using `copyDirs`; those
+   * who want typed addressable assets add `assetMap` entries.
+   *
+   * @example
+   * ```ts
+   * assetMap: {
+   *   mails: { src: 'src/templates/mails' },
+   *   reports: { src: 'src/templates/reports', glob: '**\/*.{ejs,html}' },
+   *   schemas: { src: 'src/schemas', glob: '**\/*.json' },
+   * }
+   * ```
+   */
+  assetMap?: Record<string, AssetMapEntry>;
   /**
    * Typegen settings — controls `.kickjs/types/*` generation including
    * the schema validator used for body type extraction.
@@ -309,6 +370,188 @@ interface InitProjectOptions {
 /** Scaffold a new KickJS project */
 declare function initProject(options: InitProjectOptions): Promise<void>;
 //#endregion
+//#region src/generator-extension/define.d.ts
+/**
+ * Plugin generator API per architecture.md §21.2.3 — lets first-party
+ * AND third-party packages ship `kick g <name>` scaffolders the same
+ * way the framework's built-in generators do.
+ *
+ * Plugins declare a discovery file in their `package.json`:
+ *
+ * ```json
+ * {
+ *   "name": "@my-org/kickjs-cqrs",
+ *   "kickjs": { "generators": "./dist/generators.js" }
+ * }
+ * ```
+ *
+ * The discovery file exports a typed manifest:
+ *
+ * ```ts
+ * import { defineGenerator } from '@forinda/kickjs-cli'
+ *
+ * export default [
+ *   defineGenerator({
+ *     name: 'command',
+ *     description: 'Generate a CQRS command + handler',
+ *     args: [{ name: 'name', required: true }],
+ *     files: (ctx) => [
+ *       {
+ *         path: `src/modules/${ctx.kebab}/commands/create-${ctx.kebab}.command.ts`,
+ *         content: `// generated command for ${ctx.pascal}`,
+ *       },
+ *     ],
+ *   }),
+ * ]
+ * ```
+ *
+ * `kick g command Order` then dispatches against the registered
+ * generator and writes the returned files relative to `cwd`.
+ */
+/**
+ * Resolved naming variants + project context handed to a generator's
+ * `files()` factory. Keys mirror `TemplateContext` so first-party
+ * generators that rely on the same shape can be migrated to plugin
+ * generators without rewriting their templates.
+ */
+interface GeneratorContext {
+  /** Raw name passed on the command line (`kick g resolver UserPost` → `'UserPost'`). */
+  name: string;
+  /** PascalCase form (`UserPost`). */
+  pascal: string;
+  /** kebab-case form (`user-post`). */
+  kebab: string;
+  /** camelCase form (`userPost`). */
+  camel: string;
+  /** snake_case form (`user_post`). */
+  snake: string;
+  /** Pluralized PascalCase (`UserPosts`) — present when the project enables `pluralize`. */
+  pluralPascal?: string;
+  /** Pluralized kebab-case (`user-posts`). */
+  pluralKebab?: string;
+  /** Pluralized camelCase (`userPosts`). */
+  pluralCamel?: string;
+  /** Modules directory from `kick.config.ts` (default `'src/modules'`). */
+  modulesDir: string;
+  /** Working directory for the generator — usually `process.cwd()`. */
+  cwd: string;
+  /** Positional arguments passed AFTER the name (e.g. `kick g command Order extra1 extra2` → `['extra1', 'extra2']`). */
+  args: string[];
+  /** Flag values from the command line — booleans for switches, strings for `--key value`. */
+  flags: Record<string, string | boolean>;
+}
+/** A single output file the generator wants written. */
+interface GeneratorFile {
+  /**
+   * Output path. Relative paths resolve against `ctx.cwd`; absolute
+   * paths are used as-is. Parent directories are created automatically.
+   */
+  path: string;
+  /** File contents written verbatim (UTF-8). */
+  content: string;
+}
+/** CLI argument descriptor surfaced in `kick g --list` help. */
+interface GeneratorArg {
+  name: string;
+  required?: boolean;
+  description?: string;
+}
+/** CLI flag descriptor — boolean unless `takesValue: true`. */
+interface GeneratorFlag {
+  name: string;
+  alias?: string;
+  description?: string;
+  takesValue?: boolean;
+}
+/**
+ * Spec returned by {@link defineGenerator}. Plugin discovery files
+ * export `GeneratorSpec[]` as their default export.
+ */
+interface GeneratorSpec {
+  /**
+   * Dispatch name — `kick g <name>` looks for an exact match against
+   * this string after the built-in generators are checked.
+   */
+  name: string;
+  /** Description shown in `kick g --list` and `--help`. */
+  description: string;
+  /** Optional argument descriptors — informational, surfaced in help output. */
+  args?: readonly GeneratorArg[];
+  /** Optional flag descriptors — informational, surfaced in help output. */
+  flags?: readonly GeneratorFlag[];
+  /** Build the output files for one invocation. May return a Promise. */
+  files(ctx: GeneratorContext): GeneratorFile[] | Promise<GeneratorFile[]>;
+}
+/**
+ * Identity factory — returns the spec verbatim. Exists for type
+ * inference and forward-compatibility (future fields can be added with
+ * defaults).
+ *
+ * @example
+ * ```ts
+ * import { defineGenerator } from '@forinda/kickjs-cli'
+ *
+ * export default [
+ *   defineGenerator({
+ *     name: 'command',
+ *     description: 'Generate a CQRS command + handler',
+ *     files: (ctx) => [
+ *       {
+ *         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,
+ *         content: `// command for ${ctx.pascal}`,
+ *       },
+ *     ],
+ *   }),
+ * ]
+ * ```
+ */
+declare function defineGenerator(spec: GeneratorSpec): GeneratorSpec;
+//#endregion
+//#region src/generator-extension/discover.d.ts
+/**
+ * One row in the discovered registry. `source` is the npm package name
+ * the generator came from — surfaced in error messages so adopters can
+ * see which plugin owns a given generator.
+ */
+interface DiscoveredGenerator {
+  source: string;
+  spec: GeneratorSpec;
+}
+/**
+ * Plugin discovery result, kept around even when no generators were
+ * registered so callers can distinguish "no plugins installed" from
+ * "no plugins matched the requested name."
+ */
+interface DiscoveryResult {
+  generators: DiscoveredGenerator[];
+  /** Packages whose `kickjs.generators` was loaded successfully. */
+  loaded: string[];
+  /**
+   * Packages we tried to load but failed — typically a missing entry
+   * file or a default export that wasn't an array of GeneratorSpec.
+   */
+  failed: Array<{
+    source: string;
+    reason: string;
+  }>;
+}
+//#endregion
+//#region src/generator-extension/context.d.ts
+/**
+ * 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`).
+ */
+declare function buildGeneratorContext(input: {
+  name: string;
+  args?: string[];
+  flags?: Record<string, string | boolean>;
+  modulesDir?: string;
+  cwd?: string;
+  pluralize?: boolean;
+}): GeneratorContext;
+//#endregion
 //#region src/utils/naming.d.ts
 /** Convert a name to PascalCase */
 declare function toPascalCase(name: string): string;
@@ -323,5 +566,5 @@ declare function toKebabCase(name: string): string;
  */
 declare function pluralize(name: string): string;
 //#endregion
-export { type KickCommandDefinition, type KickConfig, defineConfig, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
+export { type DiscoveredGenerator, type DiscoveryResult, type GeneratorArg, type GeneratorContext, type GeneratorFile, type GeneratorFlag, type GeneratorSpec, type KickCommandDefinition, type KickConfig, buildGeneratorContext, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/utils/naming.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/generator-extension/define.ts","../src/generator-extension/discover.ts","../src/generator-extension/context.ts","../src/utils/naming.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.2.0
+ * @forinda/kickjs-cli v4.0.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,13 +8,13 @@
  *
  * @license MIT
  */
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import * as clack from "@clack/prompts";
 import pc from "picocolors";
 import pkg from "pluralize";
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** Write a file, creating parent directories if needed. Skips writing in dry run mode. */
 async function writeFileSafe(filePath, content) {
@@ -1543,15 +1543,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
@@ -1584,15 +1584,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'`);
@@ -1611,7 +1611,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  ],`}
 })
 `;
 		}
@@ -1620,15 +1620,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'`);
@@ -1652,15 +1652,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
@@ -3038,7 +3038,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']>) {
@@ -3319,7 +3319,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)
@@ -3466,7 +3466,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)
@@ -3528,8 +3528,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! })],
     }),
   ],
 })
@@ -3559,7 +3559,7 @@ import { WsAdapter } from '@forinda/kickjs-ws'
 
 bootstrap({
   modules,
-  adapters: [new WsAdapter()],
+  adapters: [WsAdapter()],
 })
 \`\`\`
 
@@ -3663,7 +3663,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) |
@@ -3804,7 +3804,7 @@ async function initProject(options) {
 		}
 	}
 	try {
-		const { runTypegen } = await import("./typegen-C30frihW.mjs");
+		const { runTypegen } = await import("./typegen-vI1eqGLK.mjs");
 		await runTypegen({
 			cwd: dir,
 			allowDuplicates: true,
@@ -3902,7 +3902,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;
@@ -3910,7 +3913,126 @@ 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(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(path, root) {
+	const rel = relative(root, path);
+	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
+}
+//#endregion
+//#region src/generator-extension/define.ts
+/**
+* Identity factory — returns the spec verbatim. Exists for type
+* inference and forward-compatibility (future fields can be added with
+* defaults).
+*
+* @example
+* ```ts
+* import { defineGenerator } from '@forinda/kickjs-cli'
+*
+* export default [
+*   defineGenerator({
+*     name: 'command',
+*     description: 'Generate a CQRS command + handler',
+*     files: (ctx) => [
+*       {
+*         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,
+*         content: `// command for ${ctx.pascal}`,
+*       },
+*     ],
+*   }),
+* ]
+* ```
+*/
+function defineGenerator(spec) {
+	return spec;
+}
+//#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;
+}
 //#endregion
-export { defineConfig, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
+export { buildGeneratorContext, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
 
 //# sourceMappingURL=index.mjs.map