@forinda/kickjs-cli 5.0.2 → 5.2.0

package/dist/index.d.mts

@@ -1,4 +1,435 @@
 
+import { Command } from "commander";
+
+//#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 `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;
+}
+/** 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[];
+}
+/** 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;
+}
+//#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';
+  outFile?: string;
+}
+//#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/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 {
+  cwd: string;
+  /** Resolved kick.config.ts (null if the project has none). */
+  config: KickConfig | null;
+  log: (msg: string) => void;
+}
+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 {
@@ -64,6 +495,28 @@ interface AssetMapEntry {
    * 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';
 }
 /** Typegen settings — controls .kickjs/types/* generation */
 interface TypegenConfig {
@@ -100,6 +553,24 @@ interface TypegenConfig {
    * @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 {
@@ -176,6 +647,25 @@ interface KickConfig {
    * 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.
@@ -249,6 +739,20 @@ interface KickConfig {
   typegen?: TypegenConfig;
   /** Custom commands that extend the CLI */
   commands?: KickCommandDefinition[];
+  /**
+   * CLI plugins — bundled commands + typegens contributed by external
+   * packages (e.g. `@forinda/kickjs-cli-drizzle`). Plugin commands
+   * appear first; adopter `commands` overrides plugin commands of the
+   * same name. Duplicate commands or typegen ids across two plugins
+   * fail-fast at CLI startup.
+   *
+   * @example
+   * import { drizzlePlugin } from '@forinda/kickjs-cli-drizzle'
+   * export default defineConfig({
+   *   plugins: [drizzlePlugin({ schemaPath: 'src/db/schema' })],
+   * })
+   */
+  plugins?: KickCliPlugin[];
   /** Code style overrides (auto-detected from prettier when possible) */
   style?: {
     semicolons?: boolean;
@@ -279,6 +783,14 @@ interface GenerateModuleOptions {
   pluralize?: boolean;
   /** Prisma client import path (default: '@prisma/client', Prisma 7+: '@/generated/prisma/client') */
   prismaClientPath?: string;
+  /**
+   * DI-token scope prefix substituted into emitted `createToken<T>()`
+   * literals. Resolved by the orchestrating command from
+   * `kick.config.ts > tokenScope` or the project's package.json.
+   * Falls back to `'app'` when not set so the generator can be called
+   * without a config in tests/fixtures.
+   */
+  tokenScope?: string;
 }
 /**
  * Generate a module — structure depends on the project pattern.
@@ -379,143 +891,6 @@ 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
@@ -575,5 +950,5 @@ declare function toKebabCase(name: string): string;
  */
 declare function pluralize(name: string): string;
 //#endregion
-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 };
+export { type DiscoveredGenerator, type DiscoveryResult, type GeneratorArg, type GeneratorContext, type GeneratorFile, type GeneratorFlag, type GeneratorSpec, type KickCliPlugin, type KickCliPluginContext, type KickCommandDefinition, type KickConfig, KickPluginConflictError, type TypegenContext, type TypegenPlugin, type TypegenPluginResult, buildGeneratorContext, defineCliPlugin, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
 //# sourceMappingURL=index.d.mts.map