@forinda/kickjs-cli 5.11.0 → 6.0.0

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 
-import { Command } from "commander";
-
+import { GeneratorArg, GeneratorContext, GeneratorFile, GeneratorFlag, GeneratorSpec, KickCliPlugin as KickCliPlugin$1, KickCliPluginContext as KickCliPluginContext$1, KickPluginConflictError, defineCliPlugin, defineGenerator } from "@forinda/kickjs-cli-kit";
 //#region src/commands/doctor.d.ts
 /**
  * `kick doctor` — pre-flight checks for a KickJS project's dev
@@ -101,911 +100,356 @@ declare function defineDoctorExtension(ext: DoctorExtension): DoctorExtension;
  */
 declare function defineDoctorCheck(check: DoctorCheck): DoctorCheck;
 //#endregion
-//#region src/typegen/scanner.d.ts
-/**
- * Static scanner for KickJS decorated classes and DI tokens.
- *
- * Walks `src/**\/*.ts` (excluding tests and node_modules) and extracts:
- *
- * - Decorated classes (`@Service`, `@Controller`, `@Repository`, etc.)
- * - `createToken<T>('name')` definitions
- * - `@Inject('literal')` calls
- *
- * The output feeds the type generator, which emits `.kickjs/types/*.d.ts`
- * files used by the user's tsc to make `container.resolve()` and module
- * discovery type-safe.
- *
- * This is intentionally regex-based (not AST-based) to avoid the
- * ts-morph / typescript compiler dependency. Pattern from
- * `packages/vite/src/module-discovery.ts` which already uses regex
- * to detect `*.module.ts` exports.
- *
- * ## Collision detection
- *
- * Two classes with the same name across different files is a collision.
- * The scanner records all collisions in `ScanResult.collisions` so the
- * caller (generator) can decide whether to hard-error or auto-namespace.
- *
- * @module @forinda/kickjs-cli/typegen/scanner
- */
-/** Decorators that mark a class as DI-managed */
-declare const DECORATOR_NAMES: readonly ['Service', 'Controller', 'Repository', 'Injectable', 'Component', 'Module'];
-type DecoratorName = (typeof DECORATOR_NAMES)[number];
-/** A single discovered decorated class */
-interface DiscoveredClass {
-  /** Class name (e.g., 'UserService') */
-  className: string;
-  /** Decorator that marked it (e.g., 'Service') */
-  decorator: DecoratorName;
-  /** Absolute file path */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-  /** True if exported as `default` */
-  isDefault: boolean;
-}
-/** A single route handler discovered on a controller class */
-interface DiscoveredRoute {
-  /** Owning controller class name (e.g. 'UserController') */
-  controller: string;
-  /** Handler method name on the controller (e.g. 'getUser') */
-  method: string;
-  /** HTTP verb (uppercase) */
-  httpMethod: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-  /** Route path including parameter placeholders (e.g. '/:id/posts/:postId') */
-  path: string;
-  /** URL path parameter names extracted from `:placeholder` segments */
-  pathParams: string[];
-  /**
-   * Whitelisted query field names extracted from `@ApiQueryParams({...})`.
-   * `null` means no `@ApiQueryParams` was found on this method (so the
-   * generator emits an unconstrained `query` shape). An empty array means
-   * the decorator existed but no fields could be statically extracted
-   * (e.g. an opaque imported config).
-   */
-  queryFilterable: string[] | null;
-  querySortable: string[] | null;
-  querySearchable: string[] | null;
-  /**
-   * Schema identifiers referenced from the route decorator's second arg
-   * (e.g. `@Post('/', { body: createTaskSchema })`). `null` means no
-   * such reference; the value carries the identifier and the resolved
-   * import source (relative module path) if known.
-   */
-  bodySchema: SchemaRef | null;
-  querySchema: SchemaRef | null;
-  paramsSchema: SchemaRef | null;
-  /** Absolute file path of the controller */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-}
-/** A statically-resolved schema identifier reference */
-interface SchemaRef {
-  /** The identifier as written (e.g. `createTaskSchema`) */
-  identifier: string;
+//#region src/plugin/types.d.ts
+/** CLI plugin context with the host config narrowed to `KickConfig`. */
+type KickCliPluginContext = KickCliPluginContext$1<KickConfig>;
+/** A CLI plugin with the host config narrowed to `KickConfig`. */
+type KickCliPlugin = KickCliPlugin$1<KickConfig>;
+//#endregion
+//#region src/config.d.ts
+/** A custom command that developers can register via kick.config.ts */
+interface KickCommandDefinition {
+  /** The command name (e.g. 'db:migrate', 'seed', 'proto:gen') */
+  name: string;
+  /** Description shown in --help */
+  description: string;
   /**
-   * Resolved module specifier (relative path or bare module name) where
-   * the identifier is defined. `null` means the source could not be
-   * statically determined (the generator falls back to `unknown`).
+   * Shell command(s) to run. Can be a single string or an array of
+   * sequential steps. Use {args} as a placeholder for CLI arguments.
+   *
+   * @example
+   * 'npx drizzle-kit migrate'
+   * ['npx drizzle-kit generate', 'npx drizzle-kit migrate']
    */
-  source: string | null;
-}
-/** A `createToken<T>('name')` call discovered in source */
-interface DiscoveredToken {
-  /** The literal string passed to `createToken()` */
-  name: string;
-  /** The const variable name on the LHS, if any */
-  variable: string | null;
-  /** Absolute file path */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-}
-/** An `@Inject('literal')` call discovered in source */
-interface DiscoveredInject {
-  /** The literal string passed to `@Inject()` */
-  name: string;
-  /** Absolute file path */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-}
-/** A name collision — same class name in two or more files */
-interface ClassCollision {
-  /** The colliding class name */
-  className: string;
-  /** All files declaring the class */
-  classes: DiscoveredClass[];
+  steps: string | string[];
+  /** Optional aliases (e.g. ['migrate'] for 'db:migrate') */
+  aliases?: string[];
 }
+/** Project pattern — controls what generators produce and which deps are installed */
+type ProjectPattern = 'rest' | 'minimal';
+/** Package manager used for `kick add` and other dep-installing commands */
+type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
 /**
- * Information about a discovered env schema file. The typegen
- * generator uses this to emit a `KickEnv` + `NodeJS.ProcessEnv`
- * augmentation that flows through to `@Value` and `process.env`.
+ * Built-in repository type with first-class code generation support.
  *
- * `null` means no env file was found at the configured location.
+ * Only `inmemory` remains built-in (zero-dep, framework-owned). The
+ * `prisma` and `drizzle` ORM presets are **deprecated** — they now
+ * scaffold a generic custom-repository stub like any other name (see
+ * {@link DEPRECATED_REPO_TYPES}). Bring your own DB by passing a name:
+ * `repo: { name: 'postgres' }`.
  */
-interface DiscoveredEnv {
-  /** Absolute path to the env schema file */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
+type BuiltinRepoType$1 = 'inmemory';
+/** Custom repository type — generates a stub with TODO markers */
+interface CustomRepoType {
+  name: string;
 }
+/** Repository type — built-in string or custom object */
+type RepoTypeConfig = BuiltinRepoType$1 | CustomRepoType;
 /**
- * A plugin or adapter discovered in source — either via `defineAdapter({ name })`
- * / `definePlugin({ name })` calls, or via a class that `implements AppAdapter`
- * and declares a string-literal `name` field.
+ * Supported schema validators for `kick typegen` body/query/params
+ * type extraction.
  *
- * The `name` here is the literal string passed to the framework (the value
- * `dependsOn` references), NOT the symbol on the LHS. `defineAdapter` lets
- * authors choose any name they want; the symbol is irrelevant at runtime.
+ * - `'zod'` — emits `import('zod').infer<typeof schema>` (default)
+ * - `'kickjs-schema'` — emits `InferSchemaOutput<typeof schema>` from
+ *   `@forinda/kickjs-schema`, works with Zod, Valibot, Yup, and any
+ *   Standard Schema v1 or KickSchema adapter
+ * - `false` — disables schema-driven body typing (fields stay `unknown`)
  */
-interface DiscoveredPluginOrAdapter {
-  /** Whether this is a plugin (`definePlugin`) or adapter (`defineAdapter` / class) */
-  kind: 'plugin' | 'adapter';
-  /** The string literal passed as `name` (the value `dependsOn` references) */
-  name: string;
-  /** Absolute file path */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-}
+type SchemaValidator = 'zod' | 'kickjs-schema' | false;
 /**
- * A context key discovered from a `defineContextDecorator({ key })` or
- * `defineHttpContextDecorator({ key })` call (including the curried
- * `.withParams<P>()({ key })` form). Feeds the `kick/context` typegen
- * plugin, which emits the `ContextKeys` augmentation so `dependsOn`
- * typo-checking is automatic and complete.
+ * 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 DiscoveredContextKey {
-  /** The literal `key:` value the contributor writes. */
-  key: string;
-  /** Absolute file path. */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes. */
-  relativePath: string;
+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;
+  /**
+   * How file extensions feed into manifest keys. Default `'auto'`.
+   *
+   * - `'strip'` — drop the extension. `pages/index.pug` →
+   *   `'pages/index'`. Two siblings with the same basename collide;
+   *   last-walk-order wins, others are silently dropped. Opt-in
+   *   only — kept for backward compatibility with projects that
+   *   relied on this contract.
+   * - `'with-extension'` — keep every extension on every key. Best
+   *   when the namespace holds extension siblings (`index.pug` +
+   *   `index.html` + `index.css` in `src/pages/`); every file
+   *   reaches the manifest under its full path.
+   * - `'auto'` — strip when basenames are unique, keep extensions
+   *   on collision groups. Singleton files keep their short key;
+   *   `pages/index.{pug,html,css}` becomes
+   *   `pages/index.pug` / `pages/index.html` / `pages/index.css`.
+   *   No data loss; non-colliding namespaces stay on the short
+   *   keys they had before.
+   *
+   * @default 'auto'
+   */
+  keys?: 'auto' | 'strip' | 'with-extension';
 }
 /**
- * A `defineAugmentation('Name', meta)` call discovered in source. Plugins
- * call this to advertise an augmentable interface so the typegen can list
- * every augmentation surface in one generated file.
+ * Database settings consumed by `kick db generate`, `kick db migrate`,
+ * and the M4.C composite-type detection gate. Mirrors the runtime
+ * `DbConfig` shape from `@forinda/kickjs-db` — duplicated here so
+ * adopters who only install `@forinda/kickjs-cli` can set the block
+ * without pulling `@forinda/kickjs-db` types into their kick.config.ts
+ * resolution. The CLI loads kick.config.ts through `loadKickConfig`,
+ * then `resolveDbConfig` re-reads this block from the same module and
+ * normalises defaults (`schemaPath` / `migrationsDir` / `dialect`).
+ *
+ * @example
+ * ```ts
+ * defineConfig({
+ *   db: {
+ *     schemaPath: 'src/db/schema.ts',
+ *     migrationsDir: 'db/migrations',
+ *     dialect: 'postgres',
+ *     connectionString: process.env.DATABASE_URL,
+ *   },
+ * })
+ * ```
  */
-interface DiscoveredAugmentation {
-  /** The literal string passed as the first arg to `defineAugmentation` */
-  name: string;
-  /** Optional `description` extracted from the second-arg object literal */
-  description: string | null;
-  /** Optional `example` extracted from the second-arg object literal */
-  example: string | null;
-  /** Absolute file path */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-}
-/**
- * A decorated class whose file sits inside a module directory but
- * isn't picked up by any of the module's `import.meta.glob(...)`
- * patterns. Surfaced as a typegen warning per forinda/kick-js#235 §4
- * so adopters notice silent registration drift before it bites them
- * at runtime with a `MissingContributorError` or wrong code path.
- */
-interface OrphanedClass {
-  /** The decorated class name */
-  className: string;
-  /** Absolute path of the class file */
-  filePath: string;
-  /** Path relative to scan root, with forward slashes */
-  relativePath: string;
-  /** Absolute path of the module file whose globs didn't match */
-  moduleFilePath: string;
-  /** The decorator name (`Service`, `Controller`, `Repository`, …) */
-  decorator: DecoratorName;
-}
-/** Aggregated scanner output */
-interface ScanResult {
-  classes: DiscoveredClass[];
-  routes: DiscoveredRoute[];
-  tokens: DiscoveredToken[];
-  injects: DiscoveredInject[];
-  collisions: ClassCollision[];
-  /** Discovered env schema file (or null if none found at the configured path) */
-  env: DiscoveredEnv | null;
-  /** Plugins/adapters discovered via `defineAdapter`/`definePlugin`/`implements AppAdapter` */
-  pluginsAndAdapters: DiscoveredPluginOrAdapter[];
-  /** Augmentation interfaces declared via `defineAugmentation('Name', meta)` */
-  augmentations: DiscoveredAugmentation[];
-  /** Context keys from `define(Http)ContextDecorator({ key })` calls */
-  contextKeys: DiscoveredContextKey[];
+interface KickDbConfigBlock {
   /**
-   * Decorated classes that sit inside a module directory but aren't
-   * picked up by any of the module's `import.meta.glob(...)` patterns.
-   * Empty when every decorator file is matched. forinda/kick-js#235 §4.
+   * Path to the schema module (`pgEnum` / `table` declarations).
+   * Defaults to `'src/db/schema.ts'`.
    */
-  orphanedClasses: OrphanedClass[];
-}
-/** Options for the scanner */
-interface ScanOptions {
-  /** Root directory to scan (e.g., absolute path to `src`) */
-  root: string;
-  /** Project root used to compute relative paths (e.g., process.cwd()) */
-  cwd: string;
-  /** Glob-like extensions to scan */
-  extensions?: string[];
-  /** Substrings that exclude a path (matched against relative path) */
-  exclude?: string[];
+  schemaPath?: string;
   /**
-   * Path to the env schema file, relative to `cwd`. Defaults to
-   * `'src/env.ts'`. The file must contain a `defineEnv(...)` call
-   * with a default export for the typegen to emit a typed `KickEnv`
-   * augmentation. If the file does not exist or doesn't match the
-   * expected shape, env typing is skipped silently.
+   * Where `kick db generate` writes migration directories. Defaults
+   * to `'db/migrations'`.
    */
-  envFile?: string;
-}
-//#endregion
-//#region src/typegen/plugin.d.ts
-interface TypegenLogger {
-  info(msg: string): void;
-  warn(msg: string): void;
-  error(msg: string): void;
-}
-interface TypegenContext {
-  cwd: string;
-  config: KickConfig;
-  /** Dynamic-import a TS module (Node loader). Used by plugins that need to
-   * read the adopter's schema / route map / asset registry at generate time. */
-  importTs<T = unknown>(absPath: string): Promise<T>;
-  /** Write under `cwd`. Caller passes a relPath (e.g. `.kickjs/types/foo.d.ts`). */
-  writeFile(relPath: string, contents: string): Promise<void>;
+  migrationsDir?: string;
+  /** SQL dialect. Defaults to `'postgres'`. */
+  dialect?: 'postgres' | 'sqlite' | 'mysql';
   /**
-   * Run `scanProject` once per typegen pass, memoizing the result so
-   * multiple plugins (`kick/routes`, `kick/env`, future adopter plugins)
-   * share a single fs walk + AST extraction.
-   *
-   * The runner uses an order-independent cache key derived from the
-   * resolved options (`root`, `cwd`, `extensions`, `exclude`, `envFile`)
-   * — semantically equal options hit the cache regardless of how the
-   * caller built the literal. (We deliberately don't `JSON.stringify`
-   * the options for caching since that would be sensitive to property
-   * insertion order.) Plugins that don't need scanner data can ignore
-   * this method entirely.
-   *
-   * Implementation lives in the runner so test harnesses can inject
-   * a stub scanner; plugins only see the function.
+   * Postgres connection string for the built-in pgAdapter path. Read
+   * from the `DATABASE_URL` env var when omitted. Used by
+   * `kick db migrate*` and the M4.C composite-type gate at
+   * `kick db generate`.
    */
-  getScanResult(opts: ScanOptions): Promise<ScanResult>;
-  log: TypegenLogger;
+  connectionString?: string;
+  /**
+   * Escape hatch: a factory returning a fully-constructed
+   * MigrationAdapter (typed loosely here so the CLI types don't pull
+   * `@forinda/kickjs-db` into adopter projects that don't import it).
+   * Takes precedence over `connectionString` when both are set.
+   */
+  adapter?: () => unknown | Promise<unknown>;
 }
-interface TypegenPlugin {
-  /** Stable id — used as filename: `.kickjs/types/${id}<outExtension>` (slashes → `__`). */
-  id: string;
-  /** Glob patterns the Vite watcher subscribes to; change → re-run this plugin. */
-  inputs: string[];
+/** Typegen settings — controls .kickjs/types/* generation */
+interface TypegenConfig {
   /**
-   * Output filename extension. Default `.d.ts` — the right choice for
-   * pure module-augmentation plugins (kick/db, kick/assets) since
-   * declaration files don't need the runtime-import dance.
-   *
-   * `kick/routes` overrides to `.ts` because it emits hoisted
-   * `import type {...} from '...'` lines at the top of the file. Inline
-   * `import('...').X` references inside `.d.ts` silently degrade to
-   * `unknown` under `moduleResolution: 'bundler'`; emitting `.ts`
-   * sidesteps that quirk and gets full type resolution.
-   *
-   * Adopter-supplied plugins should leave this unset unless they hit
-   * the same hoisted-import constraint.
+   * Source directory to scan for controllers and decorators.
+   * Defaults to `'src'`.
    */
-  outExtension?: string;
+  srcDir?: string;
   /**
-   * Return the augmentation source (without banner — runner prepends).
-   * Return null to skip emission (e.g. no schema file present).
+   * Output directory for generated `.d.ts` files.
+   * Defaults to `'.kickjs/types'`.
    */
-  generate(ctx: TypegenContext): Promise<string | null>;
-}
-interface TypegenPluginResult {
-  id: string;
-  status: 'written' | 'unchanged' | 'skipped' | 'error';
-  outFile?: string;
-}
-/**
- * Identity factory for {@link TypegenPlugin}. Returns the spec verbatim.
- * Exists for type inference and forward-compatibility — future
- * fields can be added with defaults without breaking adopters.
- *
- * Mirrors {@link defineGenerator} ergonomics. Use at the call site so
- * the plugin's `generate(ctx)` body gets a fully-typed `ctx` without
- * an explicit annotation:
- *
- * @example
- * ```ts
- * import { defineTypegen } from '@forinda/kickjs-cli'
- *
- * export const drizzleTypegen = defineTypegen({
- *   id: 'drizzle',
- *   inputs: ['src/db/schema.ts'],
- *   async generate(ctx) {
- *     const schema = await ctx.importTs(`${ctx.cwd}/src/db/schema.ts`)
- *     return `// declare module …`
- *   },
- * })
- * ```
- */
-declare function defineTypegen(spec: TypegenPlugin): TypegenPlugin;
-//#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 drizzle-typegen 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;
+  outDir?: string;
   /**
-   * Working directory the CLI was invoked from. May be a nested subdirectory
-   * if the adopter ran `kick g ...` from `src/modules/foo/` — for "write
-   * files relative to the project" use {@link projectRoot} instead.
+   * Schema validator used to derive `body` types from route metadata.
+   *
+   * - `'zod'` — emit `z.infer<typeof <importedSchema>>` for any schema
+   *   referenced as a named identifier in `@Get/@Post/...({ body, query, params })`.
+   * - `false` — disable schema-driven body typing.
+   *
+   * Future: `'joi' | 'yup' | 'json-schema'` plus a `{ name; module }`
+   * escape hatch for custom adapters.
+   *
+   * @default 'zod'
    */
-  cwd: string;
+  schemaValidator?: SchemaValidator;
   /**
-   * Resolved project root — the nearest ancestor directory of {@link cwd}
-   * containing `kick.config.{ts,js,mjs,json}` (or `package.json` as a
-   * fallback). Always set; falls back to `cwd` when no marker is found.
+   * Path to the project's env schema file (relative to project root).
+   * Must default-export a `defineEnv(...)` schema for typegen to emit
+   * the typed `KickEnv` global registry.
+   *
+   * Set to `false` to disable env typing entirely.
    *
-   * Use this when writing files that must land at a known location
-   * regardless of where the adopter typed the command. `kick g ...` from
-   * inside `src/modules/foo/` will still see `projectRoot` pointing at
-   * the directory that owns `kick.config.ts`.
+   * @default 'src/env.ts'
    */
-  projectRoot: 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 {
+  envFile?: string | false;
   /**
-   * Output path. Relative paths resolve against `ctx.cwd`; absolute
-   * paths are used as-is. Parent directories are created automatically.
+   * Built-in or user typegen plugin ids to skip during `kick typegen`,
+   * `kick dev`, and `kick typegen --watch`.
+   *
+   * The plugin still loads and merge-time conflict detection still
+   * runs — only the `generate()` invocation is skipped — so adopters
+   * who want to hand-write `KickDbRegister` (manual typeof-schema
+   * augmentation) can disable `'kick/db'` and keep the rest:
+   *
+   * @example
+   * typegen: {
+   *   disable: ['kick/db'],   // hand-written register.ts owns the type
+   * }
+   *
+   * Unrecognised ids are ignored — the list is treated as a wishlist,
+   * not a strict registry.
    */
-  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;
+  disable?: string[];
 }
-/**
- * Spec returned by {@link defineGenerator}. Plugin discovery files
- * export `GeneratorSpec[]` as their default export.
- */
-interface GeneratorSpec {
+/** Module generation settings — controls how `kick g module` produces code */
+interface ModuleConfig {
+  /** Where modules live (default: 'src/modules') */
+  dir?: string;
   /**
-   * Dispatch name — `kick g <name>` looks for an exact match against
-   * this string after the built-in generators are checked.
+   * Default repository implementation for generators.
+   *
+   * Built-in types (string): `'drizzle'`, `'inmemory'`, `'prisma'`
+   * — generate fully working repository code.
+   *
+   * Custom types (object): `{ name: 'typeorm' }`
+   * — generate a stub repository with TODO markers.
+   *
+   * @example
+   * repo: 'prisma'                // built-in
+   * repo: { name: 'typeorm' }     // custom
    */
-  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/plugin/types.d.ts
-/**
- * Runtime context handed to `register()` — saves callbacks from
- * re-loading config or guessing cwd. Forward-compatible: future fields
- * land here without changing the callback signature.
- */
-interface KickCliPluginContext {
+  repo?: RepoTypeConfig;
+  /** Schema output directory (e.g. 'src/db/schema' for Drizzle, 'prisma/' for Prisma) */
+  schemaDir?: string;
   /**
-   * Working directory the CLI was invoked from. Plugin authors that need
-   * a stable "project base" location (e.g. to write artifacts, resolve
-   * config-relative paths) should prefer {@link projectRoot} over `cwd`
-   * — `cwd` is whatever the adopter typed the command from, including
-   * arbitrary subdirectories.
+   * Whether to pluralize module names in generated code.
+   * When true (default), `kick g module user` creates `src/modules/users/`.
+   * When false, it creates `src/modules/user/` and uses singular names throughout.
    */
-  cwd: string;
+  pluralize?: boolean;
   /**
-   * Resolved project root — the directory `loadKickConfig` walked up to
-   * via `findProjectRoot()`. Always set to a usable absolute path: when
-   * a `kick.config.{ts,js,mjs,json}` is found, that directory; otherwise
-   * the nearest ancestor with a `package.json`; otherwise `cwd` itself.
+   * Import path for the Prisma generated client in `--repo prisma` templates.
+   * Must resolve within `src/` for path alias compatibility.
    *
-   * Populated by `mergeCliPlugins.register()` from the same resolution
-   * that `cli.ts` performs at startup, so plugin authors get a coherent
-   * view of the project root without re-walking the filesystem.
+   * @default '@prisma/client' (Prisma 5/6)
+   * @example
+   * prismaClientPath: '@/generated/prisma/client'  // Prisma 7+
+   * prismaClientPath: './generated/prisma/client'   // relative
    */
-  projectRoot: string;
-  /** Resolved kick.config.ts (null if the project has none). */
-  config: KickConfig | null;
-  log: (msg: string) => void;
+  prismaClientPath?: string;
   /**
-   * Plugin-shipped generators merged from built-ins + adopter
-   * `kick.config.ts > plugins[]`. Populated by `mergeCliPlugins` and
-   * threaded through so `register()` callbacks (notably
-   * `kick/generate`) can register each plugin generator as a real
-   * Commander subcommand — without that, plugin generators only fire
-   * via the bare-action dispatch and are invisible to `kick g --help`.
+   * Module declaration style emitted by `kick g module` and the
+   * project scaffold.
    *
-   * Optional so light test harnesses that call `plugin.register(program)`
-   * directly (no merge step) stay unaffected.
-   */
-  generators?: DiscoveredGenerator[];
-}
-interface KickCliPlugin {
-  /** Stable identifier — used in error messages on conflict + de-dup. */
-  name: string;
-  commands?: KickCommandDefinition[];
-  /** Programmatic command registration. Called once at CLI startup. */
-  register?: (program: Command, ctx: KickCliPluginContext) => void | Promise<void>;
-  typegens?: TypegenPlugin[];
-  generators?: GeneratorSpec[];
-}
-/** Identity helper — exists for type inference + parity with definePlugin. */
-declare function defineCliPlugin(p: KickCliPlugin): KickCliPlugin;
-declare class KickPluginConflictError extends Error {
-  constructor(kind: 'plugin' | 'command' | 'typegen' | 'generator', id: string, owners: string[]);
-}
-//#endregion
-//#region src/config.d.ts
-/** A custom command that developers can register via kick.config.ts */
-interface KickCommandDefinition {
-  /** The command name (e.g. 'db:migrate', 'seed', 'proto:gen') */
-  name: string;
-  /** Description shown in --help */
-  description: string;
-  /**
-   * Shell command(s) to run. Can be a single string or an array of
-   * sequential steps. Use {args} as a placeholder for CLI arguments.
+   * - `'define'` (default) — `defineModule({ name, build: () => ({...}) })`
+   *   factory form. Mirrors `defineAdapter` / `definePlugin` /
+   *   `defineContextDecorator`.
+   * - `'class'` — legacy `class FooModule implements AppModule { ... }`
+   *   form. Still fully supported by the framework loader; pin to this
+   *   value for projects that prefer the class shape (existing-codebase
+   *   consistency, class-decorator setups, etc).
    *
-   * @example
-   * 'npx drizzle-kit migrate'
-   * ['npx drizzle-kit generate', 'npx drizzle-kit migrate']
+   * The framework runtime accepts both shapes regardless of this
+   * setting — the flag controls codegen output only. `kick g module`
+   * inserts the matching call form into `src/modules/index.ts`
+   * (`Module()` vs `Module`); `kick rm module` matches both.
+   *
+   * @default 'define'
    */
-  steps: string | string[];
-  /** Optional aliases (e.g. ['migrate'] for 'db:migrate') */
-  aliases?: string[];
-}
-/** Project pattern — controls what generators produce and which deps are installed */
-type ProjectPattern = 'rest' | 'ddd' | 'cqrs' | 'minimal';
-/** Package manager used for `kick add` and other dep-installing commands */
-type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
-/** Built-in repository types with first-class code generation support */
-type BuiltinRepoType$1 = 'drizzle' | 'inmemory' | 'prisma';
-/** Custom repository type — generates a stub with TODO markers */
-interface CustomRepoType {
-  name: string;
+  style?: 'define' | 'class';
 }
-/** Repository type — built-in string or custom object */
-type RepoTypeConfig = BuiltinRepoType$1 | CustomRepoType;
-/**
- * Supported schema validators for `kick typegen` body/query/params
- * type extraction.
- *
- * - `'zod'` — emits `import('zod').infer<typeof schema>` (default)
- * - `'kickjs-schema'` — emits `InferSchemaOutput<typeof schema>` from
- *   `@forinda/kickjs-schema`, works with Zod, Valibot, Yup, and any
- *   Standard Schema v1 or KickSchema adapter
- * - `false` — disables schema-driven body typing (fields stay `unknown`)
- */
-type SchemaValidator = 'zod' | 'kickjs-schema' | 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 {
+/** Configuration for the kick.config.ts file */
+interface KickConfig {
   /**
-   * 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).
+   * Project pattern — controls default generator behavior.
+   * - 'rest' — Express + Swagger (default)
+   * - 'ddd' — Full DDD modules with use cases, entities, value objects
+   * - 'cqrs' — CQRS with commands, queries, events, WebSocket + queue
+   * - 'minimal' — Bare Express with no scaffolding
    */
-  src: string;
+  pattern?: ProjectPattern;
   /**
-   * 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/...`).
+   * Module generation settings — directory, repo type, pluralization, schema dir.
+   *
+   * @example
+   * modules: {
+   *   dir: 'src/modules',
+   *   repo: 'prisma',
+   *   pluralize: false,
+   *   schemaDir: 'prisma/',
+   * }
    */
-  dest?: string;
+  modules?: ModuleConfig;
   /**
-   * 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).
+   * Package manager used by `kick add` (and any future dep-installing command)
+   * to install dependencies. When set, overrides lockfile auto-detection so
+   * commands always use the project's intended package manager.
+   *
+   * Priority (highest first):
+   * 1. `--pm` flag on the CLI
+   * 2. `packageManager` in kick.config
+   * 3. `packageManager` field in package.json (corepack convention)
+   * 4. Lockfile detection (pnpm-lock.yaml → pnpm, yarn.lock → yarn)
+   * 5. `'npm'`
+   *
+   * @example
+   * packageManager: 'pnpm'
    */
-  glob?: string;
+  packageManager?: PackageManager;
   /**
-   * How file extensions feed into manifest keys. Default `'auto'`.
+   * DI token scope prefix used by code generators. Every scaffolded
+   * `createToken<T>('<scope>/<area>/<key>')` substitutes this string
+   * for `<scope>`. Generators emit org-scoped tokens out of the box
+   * so adopter projects pass `kick-lint`'s `token-reserved-prefix`
+   * rule (which forbids the reserved `kick/` prefix on third-party
+   * code) without manual rename.
    *
-   * - `'strip'` — drop the extension. `pages/index.pug` →
-   *   `'pages/index'`. Two siblings with the same basename collide;
-   *   last-walk-order wins, others are silently dropped. Opt-in
-   *   only — kept for backward compatibility with projects that
-   *   relied on this contract.
-   * - `'with-extension'` — keep every extension on every key. Best
-   *   when the namespace holds extension siblings (`index.pug` +
-   *   `index.html` + `index.css` in `src/pages/`); every file
-   *   reaches the manifest under its full path.
-   * - `'auto'` — strip when basenames are unique, keep extensions
-   *   on collision groups. Singleton files keep their short key;
-   *   `pages/index.{pug,html,css}` becomes
-   *   `pages/index.pug` / `pages/index.html` / `pages/index.css`.
-   *   No data loss; non-colliding namespaces stay on the short
-   *   keys they had before.
+   * Resolution order (highest first):
+   * 1. This field, when set
+   * 2. `package.json` `name` field — `@scope/pkg` → `'scope'`,
+   *    bare `pkg` → `'pkg'`
+   * 3. Fallback `'app'`
    *
-   * @default 'auto'
+   * @example
+   * tokenScope: 'mycorp'
+   * // → createToken<...>('mycorp/users/repository')
    */
-  keys?: 'auto' | 'strip' | 'with-extension';
-}
-/**
- * Database settings consumed by `kick db generate`, `kick db migrate`,
- * and the M4.C composite-type detection gate. Mirrors the runtime
- * `DbConfig` shape from `@forinda/kickjs-db` — duplicated here so
- * adopters who only install `@forinda/kickjs-cli` can set the block
- * without pulling `@forinda/kickjs-db` types into their kick.config.ts
- * resolution. The CLI loads kick.config.ts through `loadKickConfig`,
- * then `resolveDbConfig` re-reads this block from the same module and
- * normalises defaults (`schemaPath` / `migrationsDir` / `dialect`).
- *
- * @example
- * ```ts
- * defineConfig({
- *   db: {
- *     schemaPath: 'src/db/schema.ts',
- *     migrationsDir: 'db/migrations',
- *     dialect: 'postgres',
- *     connectionString: process.env.DATABASE_URL,
- *   },
- * })
- * ```
- */
-interface KickDbConfigBlock {
+  tokenScope?: string;
   /**
-   * Path to the schema module (`pgEnum` / `table` declarations).
-   * Defaults to `'src/db/schema.ts'`.
+   * Directories to copy to dist/ after build.
+   * Useful for EJS templates, email templates, static assets, etc.
+   *
+   * @example
+   * ```ts
+   * copyDirs: [
+   *   'src/views',                          // copies to dist/src/views
+   *   { src: 'src/views', dest: 'dist/views' }, // custom dest
+   *   'src/emails',
+   * ]
+   * ```
    */
-  schemaPath?: string;
+  copyDirs?: Array<string | {
+    src: string;
+    dest?: string;
+  }>;
   /**
-   * Where `kick db generate` writes migration directories. Defaults
-   * to `'db/migrations'`.
-   */
-  migrationsDir?: string;
-  /** SQL dialect. Defaults to `'postgres'`. */
-  dialect?: 'postgres' | 'sqlite' | 'mysql';
-  /**
-   * Postgres connection string for the built-in pgAdapter path. Read
-   * from the `DATABASE_URL` env var when omitted. Used by
-   * `kick db migrate*` and the M4.C composite-type gate at
-   * `kick db generate`.
-   */
-  connectionString?: string;
-  /**
-   * Escape hatch: a factory returning a fully-constructed
-   * MigrationAdapter (typed loosely here so the CLI types don't pull
-   * `@forinda/kickjs-db` into adopter projects that don't import it).
-   * Takes precedence over `connectionString` when both are set.
-   */
-  adapter?: () => unknown | Promise<unknown>;
-}
-/** Typegen settings — controls .kickjs/types/* generation */
-interface TypegenConfig {
-  /**
-   * Source directory to scan for controllers and decorators.
-   * Defaults to `'src'`.
-   */
-  srcDir?: string;
-  /**
-   * Output directory for generated `.d.ts` files.
-   * Defaults to `'.kickjs/types'`.
-   */
-  outDir?: string;
-  /**
-   * Schema validator used to derive `body` types from route metadata.
-   *
-   * - `'zod'` — emit `z.infer<typeof <importedSchema>>` for any schema
-   *   referenced as a named identifier in `@Get/@Post/...({ body, query, params })`.
-   * - `false` — disable schema-driven body typing.
-   *
-   * Future: `'joi' | 'yup' | 'json-schema'` plus a `{ name; module }`
-   * escape hatch for custom adapters.
-   *
-   * @default 'zod'
-   */
-  schemaValidator?: SchemaValidator;
-  /**
-   * Path to the project's env schema file (relative to project root).
-   * Must default-export a `defineEnv(...)` schema for typegen to emit
-   * the typed `KickEnv` global registry.
-   *
-   * Set to `false` to disable env typing entirely.
-   *
-   * @default 'src/env.ts'
-   */
-  envFile?: string | false;
-  /**
-   * Built-in or user typegen plugin ids to skip during `kick typegen`,
-   * `kick dev`, and `kick typegen --watch`.
-   *
-   * The plugin still loads and merge-time conflict detection still
-   * runs — only the `generate()` invocation is skipped — so adopters
-   * who want to hand-write `KickDbRegister` (manual typeof-schema
-   * augmentation) can disable `'kick/db'` and keep the rest:
-   *
-   * @example
-   * typegen: {
-   *   disable: ['kick/db'],   // hand-written register.ts owns the type
-   * }
-   *
-   * Unrecognised ids are ignored — the list is treated as a wishlist,
-   * not a strict registry.
-   */
-  disable?: string[];
-}
-/** Module generation settings — controls how `kick g module` produces code */
-interface ModuleConfig {
-  /** Where modules live (default: 'src/modules') */
-  dir?: string;
-  /**
-   * Default repository implementation for generators.
-   *
-   * Built-in types (string): `'drizzle'`, `'inmemory'`, `'prisma'`
-   * — generate fully working repository code.
-   *
-   * Custom types (object): `{ name: 'typeorm' }`
-   * — generate a stub repository with TODO markers.
-   *
-   * @example
-   * repo: 'prisma'                // built-in
-   * repo: { name: 'typeorm' }     // custom
-   */
-  repo?: RepoTypeConfig;
-  /** Schema output directory (e.g. 'src/db/schema' for Drizzle, 'prisma/' for Prisma) */
-  schemaDir?: string;
-  /**
-   * Whether to pluralize module names in generated code.
-   * When true (default), `kick g module user` creates `src/modules/users/`.
-   * When false, it creates `src/modules/user/` and uses singular names throughout.
-   */
-  pluralize?: boolean;
-  /**
-   * Import path for the Prisma generated client in `--repo prisma` templates.
-   * Must resolve within `src/` for path alias compatibility.
-   *
-   * @default '@prisma/client' (Prisma 5/6)
-   * @example
-   * prismaClientPath: '@/generated/prisma/client'  // Prisma 7+
-   * prismaClientPath: './generated/prisma/client'   // relative
-   */
-  prismaClientPath?: string;
-  /**
-   * Module declaration style emitted by `kick g module` and the
-   * project scaffold.
-   *
-   * - `'define'` (default) — `defineModule({ name, build: () => ({...}) })`
-   *   factory form. Mirrors `defineAdapter` / `definePlugin` /
-   *   `defineContextDecorator`.
-   * - `'class'` — legacy `class FooModule implements AppModule { ... }`
-   *   form. Still fully supported by the framework loader; pin to this
-   *   value for projects that prefer the class shape (existing-codebase
-   *   consistency, class-decorator setups, etc).
-   *
-   * The framework runtime accepts both shapes regardless of this
-   * setting — the flag controls codegen output only. `kick g module`
-   * inserts the matching call form into `src/modules/index.ts`
-   * (`Module()` vs `Module`); `kick rm module` matches both.
-   *
-   * @default 'define'
-   */
-  style?: 'define' | 'class';
-}
-/** Configuration for the kick.config.ts file */
-interface KickConfig {
-  /**
-   * Project pattern — controls default generator behavior.
-   * - 'rest' — Express + Swagger (default)
-   * - 'ddd' — Full DDD modules with use cases, entities, value objects
-   * - 'cqrs' — CQRS with commands, queries, events, WebSocket + queue
-   * - 'minimal' — Bare Express with no scaffolding
-   */
-  pattern?: ProjectPattern;
-  /**
-   * Module generation settings — directory, repo type, pluralization, schema dir.
-   *
-   * @example
-   * modules: {
-   *   dir: 'src/modules',
-   *   repo: 'prisma',
-   *   pluralize: false,
-   *   schemaDir: 'prisma/',
-   * }
-   */
-  modules?: ModuleConfig;
-  /**
-   * Package manager used by `kick add` (and any future dep-installing command)
-   * to install dependencies. When set, overrides lockfile auto-detection so
-   * commands always use the project's intended package manager.
-   *
-   * Priority (highest first):
-   * 1. `--pm` flag on the CLI
-   * 2. `packageManager` in kick.config
-   * 3. `packageManager` field in package.json (corepack convention)
-   * 4. Lockfile detection (pnpm-lock.yaml → pnpm, yarn.lock → yarn)
-   * 5. `'npm'`
-   *
-   * @example
-   * packageManager: 'pnpm'
-   */
-  packageManager?: PackageManager;
-  /**
-   * DI token scope prefix used by code generators. Every scaffolded
-   * `createToken<T>('<scope>/<area>/<key>')` substitutes this string
-   * for `<scope>`. Generators emit org-scoped tokens out of the box
-   * so adopter projects pass `kick-lint`'s `token-reserved-prefix`
-   * rule (which forbids the reserved `kick/` prefix on third-party
-   * code) without manual rename.
-   *
-   * Resolution order (highest first):
-   * 1. This field, when set
-   * 2. `package.json` `name` field — `@scope/pkg` → `'scope'`,
-   *    bare `pkg` → `'pkg'`
-   * 3. Fallback `'app'`
-   *
-   * @example
-   * tokenScope: 'mycorp'
-   * // → createToken<...>('mycorp/users/repository')
-   */
-  tokenScope?: string;
-  /**
-   * Directories to copy to dist/ after build.
-   * Useful for EJS templates, email templates, static assets, etc.
-   *
-   * @example
-   * ```ts
-   * copyDirs: [
-   *   'src/views',                          // copies to dist/src/views
-   *   { src: 'src/views', dest: 'dist/views' }, // custom dest
-   *   'src/emails',
-   * ]
-   * ```
-   */
-  copyDirs?: Array<string | {
-    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 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?: {
     /**
@@ -1158,7 +602,7 @@ declare function loadKickConfig(startDir: string): Promise<KickConfig | null>;
 type ModuleStyle = 'define' | 'class';
 //#endregion
 //#region src/generators/module.d.ts
-type BuiltinRepoType = 'drizzle' | 'inmemory' | 'prisma';
+type BuiltinRepoType = 'inmemory';
 type RepoType = BuiltinRepoType | (string & {});
 interface GenerateModuleOptions {
   name: string;
@@ -1193,9 +637,7 @@ interface GenerateModuleOptions {
  * Generate a module — structure depends on the project pattern.
  *
  * Patterns:
- *   rest         — flat folder: controller + service + DTOs + repo
- *   ddd          — nested DDD: presentation/ application/ domain/ infrastructure/
- *   cqrs         — commands, queries, events with WS/queue integration
+ *   rest         — flat folder: controller + service + DTOs + repo (default)
  *   minimal      — just controller + module index
  */
 declare function generateModule(options: GenerateModuleOptions): Promise<string[]>;
@@ -1274,7 +716,7 @@ interface GenerateDtoOptions {
 declare function generateDto(options: GenerateDtoOptions): Promise<string[]>;
 //#endregion
 //#region src/generators/project.d.ts
-type ProjectTemplate = 'rest' | 'ddd' | 'cqrs' | 'minimal';
+type ProjectTemplate = 'rest' | 'minimal';
 type SchemaLib = 'zod' | 'valibot' | 'yup';
 interface InitProjectOptions {
   name: string;
@@ -1309,6 +751,374 @@ declare function initProject(options: InitProjectOptions): Promise<void>;
  */
 declare function findProjectRoot(startDir?: string): string;
 //#endregion
+//#region src/typegen/scanner.d.ts
+/**
+ * Static scanner for KickJS decorated classes and DI tokens.
+ *
+ * Walks `src/**\/*.ts` (excluding tests and node_modules) and extracts:
+ *
+ * - Decorated classes (`@Service`, `@Controller`, `@Repository`, etc.)
+ * - `createToken<T>('name')` definitions
+ * - `@Inject('literal')` calls
+ *
+ * The output feeds the type generator, which emits `.kickjs/types/*.d.ts`
+ * files used by the user's tsc to make `container.resolve()` and module
+ * discovery type-safe.
+ *
+ * This is intentionally regex-based (not AST-based) to avoid the
+ * ts-morph / typescript compiler dependency. Pattern from
+ * `packages/vite/src/module-discovery.ts` which already uses regex
+ * to detect `*.module.ts` exports.
+ *
+ * ## Collision detection
+ *
+ * Two classes with the same name across different files is a collision.
+ * The scanner records all collisions in `ScanResult.collisions` so the
+ * caller (generator) can decide whether to hard-error or auto-namespace.
+ *
+ * @module @forinda/kickjs-cli/typegen/scanner
+ */
+/** Decorators that mark a class as DI-managed */
+declare const DECORATOR_NAMES: readonly ['Service', 'Controller', 'Repository', 'Injectable', 'Component', 'Module'];
+type DecoratorName = (typeof DECORATOR_NAMES)[number];
+/** A single discovered decorated class */
+interface DiscoveredClass {
+  /** Class name (e.g., 'UserService') */
+  className: string;
+  /** Decorator that marked it (e.g., 'Service') */
+  decorator: DecoratorName;
+  /** Absolute file path */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+  /** True if exported as `default` */
+  isDefault: boolean;
+}
+/** A single route handler discovered on a controller class */
+interface DiscoveredRoute {
+  /** Owning controller class name (e.g. 'UserController') */
+  controller: string;
+  /** Handler method name on the controller (e.g. 'getUser') */
+  method: string;
+  /** HTTP verb (uppercase) */
+  httpMethod: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  /** Route path including parameter placeholders (e.g. '/:id/posts/:postId') */
+  path: string;
+  /** URL path parameter names extracted from `:placeholder` segments */
+  pathParams: string[];
+  /**
+   * Whitelisted query field names extracted from `@ApiQueryParams({...})`.
+   * `null` means no `@ApiQueryParams` was found on this method (so the
+   * generator emits an unconstrained `query` shape). An empty array means
+   * the decorator existed but no fields could be statically extracted
+   * (e.g. an opaque imported config).
+   */
+  queryFilterable: string[] | null;
+  querySortable: string[] | null;
+  querySearchable: string[] | null;
+  /**
+   * Schema identifiers referenced from the route decorator's second arg
+   * (e.g. `@Post('/', { body: createTaskSchema })`). `null` means no
+   * such reference; the value carries the identifier and the resolved
+   * import source (relative module path) if known.
+   */
+  bodySchema: SchemaRef | null;
+  querySchema: SchemaRef | null;
+  paramsSchema: SchemaRef | null;
+  /** Absolute file path of the controller */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/** A statically-resolved schema identifier reference */
+interface SchemaRef {
+  /** The identifier as written (e.g. `createTaskSchema`) */
+  identifier: string;
+  /**
+   * Resolved module specifier (relative path or bare module name) where
+   * the identifier is defined. `null` means the source could not be
+   * statically determined (the generator falls back to `unknown`).
+   */
+  source: string | null;
+}
+/** A `createToken<T>('name')` call discovered in source */
+interface DiscoveredToken {
+  /** The literal string passed to `createToken()` */
+  name: string;
+  /** The const variable name on the LHS, if any */
+  variable: string | null;
+  /** Absolute file path */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/** An `@Inject('literal')` call discovered in source */
+interface DiscoveredInject {
+  /** The literal string passed to `@Inject()` */
+  name: string;
+  /** Absolute file path */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/** A name collision — same class name in two or more files */
+interface ClassCollision {
+  /** The colliding class name */
+  className: string;
+  /** All files declaring the class */
+  classes: DiscoveredClass[];
+}
+/**
+ * Information about a discovered env schema file. The typegen
+ * generator uses this to emit a `KickEnv` + `NodeJS.ProcessEnv`
+ * augmentation that flows through to `@Value` and `process.env`.
+ *
+ * `null` means no env file was found at the configured location.
+ */
+interface DiscoveredEnv {
+  /** Absolute path to the env schema file */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/**
+ * A plugin or adapter discovered in source — either via `defineAdapter({ name })`
+ * / `definePlugin({ name })` calls, or via a class that `implements AppAdapter`
+ * and declares a string-literal `name` field.
+ *
+ * The `name` here is the literal string passed to the framework (the value
+ * `dependsOn` references), NOT the symbol on the LHS. `defineAdapter` lets
+ * authors choose any name they want; the symbol is irrelevant at runtime.
+ */
+interface DiscoveredPluginOrAdapter {
+  /** Whether this is a plugin (`definePlugin`) or adapter (`defineAdapter` / class) */
+  kind: 'plugin' | 'adapter';
+  /** The string literal passed as `name` (the value `dependsOn` references) */
+  name: string;
+  /** Absolute file path */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/**
+ * A context key discovered from a `defineContextDecorator({ key })` or
+ * `defineHttpContextDecorator({ key })` call (including the curried
+ * `.withParams<P>()({ key })` form). Feeds the `kick/context` typegen
+ * plugin, which emits the `ContextKeys` augmentation so `dependsOn`
+ * typo-checking is automatic and complete.
+ */
+interface DiscoveredContextKey {
+  /** The literal `key:` value the contributor writes. */
+  key: string;
+  /** Absolute file path. */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes. */
+  relativePath: string;
+}
+/**
+ * A `defineAugmentation('Name', meta)` call discovered in source. Plugins
+ * call this to advertise an augmentable interface so the typegen can list
+ * every augmentation surface in one generated file.
+ */
+interface DiscoveredAugmentation {
+  /** The literal string passed as the first arg to `defineAugmentation` */
+  name: string;
+  /** Optional `description` extracted from the second-arg object literal */
+  description: string | null;
+  /** Optional `example` extracted from the second-arg object literal */
+  example: string | null;
+  /** Absolute file path */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+}
+/**
+ * A decorated class whose file sits inside a module directory but
+ * isn't picked up by any of the module's `import.meta.glob(...)`
+ * patterns. Surfaced as a typegen warning per forinda/kick-js#235 §4
+ * so adopters notice silent registration drift before it bites them
+ * at runtime with a `MissingContributorError` or wrong code path.
+ */
+interface OrphanedClass {
+  /** The decorated class name */
+  className: string;
+  /** Absolute path of the class file */
+  filePath: string;
+  /** Path relative to scan root, with forward slashes */
+  relativePath: string;
+  /** Absolute path of the module file whose globs didn't match */
+  moduleFilePath: string;
+  /** The decorator name (`Service`, `Controller`, `Repository`, …) */
+  decorator: DecoratorName;
+}
+/** Aggregated scanner output */
+interface ScanResult {
+  classes: DiscoveredClass[];
+  routes: DiscoveredRoute[];
+  tokens: DiscoveredToken[];
+  injects: DiscoveredInject[];
+  collisions: ClassCollision[];
+  /** Discovered env schema file (or null if none found at the configured path) */
+  env: DiscoveredEnv | null;
+  /** Plugins/adapters discovered via `defineAdapter`/`definePlugin`/`implements AppAdapter` */
+  pluginsAndAdapters: DiscoveredPluginOrAdapter[];
+  /** Augmentation interfaces declared via `defineAugmentation('Name', meta)` */
+  augmentations: DiscoveredAugmentation[];
+  /** Context keys from `define(Http)ContextDecorator({ key })` calls */
+  contextKeys: DiscoveredContextKey[];
+  /**
+   * Decorated classes that sit inside a module directory but aren't
+   * picked up by any of the module's `import.meta.glob(...)` patterns.
+   * Empty when every decorator file is matched. forinda/kick-js#235 §4.
+   */
+  orphanedClasses: OrphanedClass[];
+}
+/** Options for the scanner */
+interface ScanOptions {
+  /** Root directory to scan (e.g., absolute path to `src`) */
+  root: string;
+  /** Project root used to compute relative paths (e.g., process.cwd()) */
+  cwd: string;
+  /** Glob-like extensions to scan */
+  extensions?: string[];
+  /** Substrings that exclude a path (matched against relative path) */
+  exclude?: string[];
+  /**
+   * Path to the env schema file, relative to `cwd`. Defaults to
+   * `'src/env.ts'`. The file must contain a `defineEnv(...)` call
+   * with a default export for the typegen to emit a typed `KickEnv`
+   * augmentation. If the file does not exist or doesn't match the
+   * expected shape, env typing is skipped silently.
+   */
+  envFile?: string;
+  /**
+   * Directory for the persistent per-file extraction cache. When set,
+   * unchanged files (matched by `mtimeMs:size` signature) are served
+   * from `<cacheDir>/scan.json` instead of being re-read and re-scanned.
+   * Omit to disable caching (every scan is a cold read — the original
+   * behaviour). Typically `<cwd>/.kickjs/cache`.
+   */
+  cacheDir?: string;
+}
+//#endregion
+//#region src/typegen/plugin.d.ts
+interface TypegenLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+interface TypegenContext {
+  cwd: string;
+  config: KickConfig;
+  /** Dynamic-import a TS module (Node loader). Used by plugins that need to
+   * read the adopter's schema / route map / asset registry at generate time. */
+  importTs<T = unknown>(absPath: string): Promise<T>;
+  /** Write under `cwd`. Caller passes a relPath (e.g. `.kickjs/types/foo.d.ts`). */
+  writeFile(relPath: string, contents: string): Promise<void>;
+  /**
+   * Run `scanProject` once per typegen pass, memoizing the result so
+   * multiple plugins (`kick/routes`, `kick/env`, future adopter plugins)
+   * share a single fs walk + AST extraction.
+   *
+   * The runner uses an order-independent cache key derived from the
+   * resolved options (`root`, `cwd`, `extensions`, `exclude`, `envFile`)
+   * — semantically equal options hit the cache regardless of how the
+   * caller built the literal. (We deliberately don't `JSON.stringify`
+   * the options for caching since that would be sensitive to property
+   * insertion order.) Plugins that don't need scanner data can ignore
+   * this method entirely.
+   *
+   * Implementation lives in the runner so test harnesses can inject
+   * a stub scanner; plugins only see the function.
+   */
+  getScanResult(opts: ScanOptions): Promise<ScanResult>;
+  log: TypegenLogger;
+}
+interface TypegenPlugin {
+  /** Stable id — used as filename: `.kickjs/types/${id}<outExtension>` (slashes → `__`). */
+  id: string;
+  /** Glob patterns the Vite watcher subscribes to; change → re-run this plugin. */
+  inputs: string[];
+  /**
+   * Output filename extension. Default `.d.ts` — the right choice for
+   * pure module-augmentation plugins (kick/db, kick/assets) since
+   * declaration files don't need the runtime-import dance.
+   *
+   * `kick/routes` overrides to `.ts` because it emits hoisted
+   * `import type {...} from '...'` lines at the top of the file. Inline
+   * `import('...').X` references inside `.d.ts` silently degrade to
+   * `unknown` under `moduleResolution: 'bundler'`; emitting `.ts`
+   * sidesteps that quirk and gets full type resolution.
+   *
+   * Adopter-supplied plugins should leave this unset unless they hit
+   * the same hoisted-import constraint.
+   */
+  outExtension?: string;
+  /**
+   * Return the augmentation source (without banner — runner prepends).
+   * Return null to skip emission (e.g. no schema file present).
+   */
+  generate(ctx: TypegenContext): Promise<string | null>;
+}
+interface TypegenPluginResult {
+  id: string;
+  status: 'written' | 'unchanged' | 'skipped' | 'error';
+  outFile?: string;
+}
+/**
+ * Identity factory for {@link TypegenPlugin}. Returns the spec verbatim.
+ * Exists for type inference and forward-compatibility — future
+ * fields can be added with defaults without breaking adopters.
+ *
+ * Mirrors {@link defineGenerator} ergonomics. Use at the call site so
+ * the plugin's `generate(ctx)` body gets a fully-typed `ctx` without
+ * an explicit annotation:
+ *
+ * @example
+ * ```ts
+ * import { defineTypegen } from '@forinda/kickjs-cli'
+ *
+ * export const drizzleTypegen = defineTypegen({
+ *   id: 'drizzle',
+ *   inputs: ['src/db/schema.ts'],
+ *   async generate(ctx) {
+ *     const schema = await ctx.importTs(`${ctx.cwd}/src/db/schema.ts`)
+ *     return `// declare module …`
+ *   },
+ * })
+ * ```
+ */
+declare function defineTypegen(spec: TypegenPlugin): TypegenPlugin;
+//#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