@forinda/kickjs-cli-kit 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @forinda/kickjs-cli-kit
+
+The shared CLI-plugin contract for KickJS. Defines the types and helpers a package implements to ship `kick`-compatible commands, generators, and typegens — without depending on the full `@forinda/kickjs-cli`.
+
+This is a tiny, dependency-free package (one `commander` peer). You only need it if you're **building** a CLI plugin; app authors never import it directly.
+
+## Why this package exists
+
+The kick CLI mounts first-party plugins (the database tooling, for example). If those packages imported `defineCliPlugin` from `@forinda/kickjs-cli` to describe their commands, that would form a dependency cycle — the CLI already depends on them. Hoisting the **contract** into a standalone package both sides import breaks the cycle:
+
+```
+@forinda/kickjs-cli  ─┐
+                      ├─►  @forinda/kickjs-cli-kit   (contract only)
+@forinda/kickjs-db   ─┘
+```
+
+`@forinda/kickjs-cli` re-exports the whole contract, so `import { defineCliPlugin } from '@forinda/kickjs-cli'` keeps working for app-side `kick.config.ts` plugins.
+
+## Install
+
+```bash
+pnpm add @forinda/kickjs-cli-kit commander
+```
+
+`commander` is a peer dependency (the host CLI provides the `Command` your plugin registers against).
+
+## Quick start
+
+### A CLI plugin
+
+```ts
+import { defineCliPlugin } from '@forinda/kickjs-cli-kit'
+
+export const helloPlugin = defineCliPlugin({
+  name: 'my-org/hello',
+  register(program, ctx) {
+    program
+      .command('hello <name>')
+      .description('Say hello')
+      .action((name: string) => {
+        console.log(`Hello, ${name}! (project: ${ctx.projectRoot})`)
+      })
+  },
+})
+```
+
+Mount it in `kick.config.ts`:
+
+```ts
+import { defineConfig } from '@forinda/kickjs-cli'
+import { helloPlugin } from './tools/hello-plugin'
+
+export default defineConfig({ plugins: [helloPlugin] })
+```
+
+```bash
+kick hello world
+```
+
+### A `kick g <name>` generator
+
+```ts
+import { defineGenerator } from '@forinda/kickjs-cli-kit'
+
+export default [
+  defineGenerator({
+    name: 'widget',
+    description: 'Scaffold a widget',
+    args: [{ name: 'name', required: true }],
+    files: (ctx) => [
+      {
+        path: `src/widgets/${ctx.kebab}.ts`,
+        content: `export class ${ctx.pascal}Widget {}\n`,
+      },
+    ],
+  }),
+]
+```
+
+## Contract surface
+
+| Export                    | Purpose                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `defineCliPlugin(p)`      | Declare a CLI plugin: `name` + `register()` / `commands` / `typegens` / `generators`. |
+| `defineGenerator(spec)`   | Declare a `kick g <name>` scaffolder (returns the spec, typed).                       |
+| `KickCliPlugin<TConfig>`  | The plugin shape. `TConfig` is the host config type (`ctx.config`).                   |
+| `KickCliPluginContext`    | What `register()` receives: `cwd`, `projectRoot`, `config`, `log`.                    |
+| `GeneratorSpec` + co.     | `GeneratorContext` / `GeneratorFile` / `GeneratorArg` / `GeneratorFlag`.              |
+| `KickCommandDefinition`   | A declarative shell-handler command (the `commands` field shape).                     |
+| `CliTypegen`              | Structural typegen shape (the CLI's `TypegenPlugin` satisfies it).                    |
+| `KickPluginConflictError` | Thrown on duplicate plugin / command / typegen / generator ids.                       |
+
+## License
+
+MIT © Felix Orinda

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+
+import { Command } from "commander";
+
+//#region src/generators.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-kit'
+ *
+ * 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;
+  /**
+   * 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.
+   */
+  cwd: string;
+  /**
+   * 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.
+   *
+   * 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`.
+   */
+  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 {
+  /**
+   * 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-kit'
+ *
+ * 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/index.d.ts
+/**
+ * A declarative shell-handler command — the same shape as the
+ * `kick.config.ts > commands` field.
+ */
+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. A single string or an array of sequential
+   * steps. Use `{args}` as a placeholder for forwarded CLI arguments.
+   */
+  steps: string | string[];
+  /** Optional aliases (e.g. ['migrate'] for 'db:migrate'). */
+  aliases?: string[];
+}
+/**
+ * Structural shape of a typegen plugin as seen by the CLI-plugin
+ * contract. The CLI's full `TypegenPlugin` satisfies this (the `ctx`
+ * parameter is intentionally `any` here so the kit doesn't depend on the
+ * CLI's `TypegenContext` / scanner types).
+ */
+interface CliTypegen {
+  id: string;
+  inputs: string[];
+  outExtension?: string;
+  generate(ctx: any): Promise<string | null>;
+}
+/** A plugin generator paired with the plugin name that supplied it. */
+interface DiscoveredGenerator {
+  source: string;
+  spec: GeneratorSpec;
+}
+/**
+ * Runtime context handed to a plugin's `register()`. Forward-compatible:
+ * new fields land here without changing the callback signature.
+ */
+interface KickCliPluginContext<TConfig = unknown> {
+  /** Directory the CLI was invoked from (may be a nested subdirectory). */
+  cwd: string;
+  /**
+   * Resolved project root — the nearest ancestor with a
+   * `kick.config.{ts,js,mjs,json}` (or `package.json`). Prefer this over
+   * `cwd` for writing artifacts at a stable location.
+   */
+  projectRoot: string;
+  /** The loaded host config (the CLI passes its full config). */
+  config: TConfig | null;
+  log: (msg: string) => void;
+  /** Plugin-shipped generators merged by the host, threaded for register(). */
+  generators?: DiscoveredGenerator[];
+}
+/**
+ * A CLI plugin: contributes commands, programmatic command registration,
+ * typegens, and/or generators. Implemented by the CLI's built-ins and by
+ * adopter / first-party packages alike.
+ */
+interface KickCliPlugin<TConfig = unknown> {
+  /** Stable identifier — used in conflict errors + de-dup. */
+  name: string;
+  /** Declarative shell-handler commands. */
+  commands?: KickCommandDefinition[];
+  /** Programmatic command registration, called once at CLI startup. */
+  register?: (program: Command, ctx: KickCliPluginContext<TConfig>) => void | Promise<void>;
+  /** Typegen plugins the host runs after its own pass. */
+  typegens?: CliTypegen[];
+  /** `kick g <name>` scaffolders. */
+  generators?: GeneratorSpec[];
+}
+/**
+ * Identity helper for type inference + parity with `definePlugin` /
+ * `defineAdapter`. Returns the plugin verbatim.
+ */
+declare function defineCliPlugin<TConfig = unknown>(p: KickCliPlugin<TConfig>): KickCliPlugin<TConfig>;
+/** Thrown when two plugins register the same plugin/command/typegen/generator id. */
+declare class KickPluginConflictError extends Error {
+  constructor(kind: 'plugin' | 'command' | 'typegen' | 'generator', id: string, owners: string[]);
+}
+//#endregion
+export { CliTypegen, DiscoveredGenerator, GeneratorArg, GeneratorContext, GeneratorFile, GeneratorFlag, GeneratorSpec, KickCliPlugin, KickCliPluginContext, KickCommandDefinition, KickPluginConflictError, defineCliPlugin, defineGenerator };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/generators.ts","../src/index.ts"],"mappings":";;;;;;;AA4CA;;;;;;;;;;;;;;;;;;;;AA2CA;;;;;AAWA;;;;;;;;;AAOA;;;;;;AAAA,UA7DiB,gBAAA;EAiEf;EA/DA,IAAA;EA+DU;EA7DV,MAAA;EAoE4B;EAlE5B,KAAA;EA2EgB;EAzEhB,KAAA;EA6EW;EA3EX,KAAA;EA2EwD;EAzExD,YAAA;EAyEuD;EAvEvD,WAAA;EA+DA;EA7DA,WAAA;EAiEA;EA/DA,UAAA;EAiEA;;;;;EA3DA,GAAA;EA6DgD;;;;AA0BlD;;;;;;EA5EE,WAAA;EA4EiE;EA1EjE,IAAA;;EAEA,KAAA,EAAO,MAAA;AAAA;ACvDT;AAAA,UD2DiB,aAAA;;;;;EAKf,IAAA;ECrDA;EDuDA,OAAA;AAAA;AC9CF;AAAA,UDkDiB,YAAA;EACf,IAAA;EACA,QAAA;EACA,WAAA;AAAA;;UAIe,aAAA;EACf,IAAA;EACA,KAAA;EACA,WAAA;EACA,UAAA;AAAA;;;;;UAOe,aAAA;ECtDT;;;AAOR;EDoDE,IAAA;ECpDmC;EDsDnC,WAAA;ECtDoC;EDwDpC,IAAA,YAAgB,YAAA;EChDhB;EDkDA,KAAA,YAAiB,aAAA;EChDT;EDkDR,KAAA,CAAM,GAAA,EAAK,gBAAA,GAAmB,aAAA,KAAkB,OAAA,CAAQ,aAAA;AAAA;;;;;ACvC1D;;;;;;;;;;;;;;;;;;;iBDiEgB,eAAA,CAAgB,IAAA,EAAM,aAAA,GAAgB,aAAA;;;;;AApEtD;;UC3DiB,qBAAA;EDgEf;EC9DA,IAAA;EDoEe;EClEf,WAAA;;;;;EAKA,KAAA;EDgEW;EC9DX,OAAA;AAAA;;;;;;;UASe,UAAA;EACf,EAAA;EACA,MAAA;EACA,YAAA;EAKA,QAAA,CAAS,GAAA,QAAW,OAAA;AAAA;;UAIL,mBAAA;EACf,MAAA;EACA,IAAA,EAAM,aAAA;AAAA;;;;;UAOS,oBAAA;EDwDf;ECtDA,GAAA;EDwDA;;;;;EClDA,WAAA;EDoDgD;EClDhD,MAAA,EAAQ,OAAA;EACR,GAAA,GAAM,GAAA;EDiD+D;EC/CrE,UAAA,GAAa,mBAAA;AAAA;;;;;;UAQE,aAAA;EDiEkD;EC/DjE,IAAA;;EAEA,QAAA,GAAW,qBAAA;EAlEI;EAoEf,QAAA,IAAY,OAAA,EAAS,OAAA,EAAS,GAAA,EAAK,oBAAA,CAAqB,OAAA,aAAoB,OAAA;;EAE5E,QAAA,GAAW,UAAA;EApEX;EAsEA,UAAA,GAAa,aAAA;AAAA;;;;AApDf;iBA2DgB,eAAA,mBAAA,CACd,CAAA,EAAG,aAAA,CAAc,OAAA,IAChB,aAAA,CAAc,OAAA;;cAKJ,uBAAA,SAAgC,KAAA;EAC3C,WAAA,CAAY,IAAA,kDAAsD,EAAA,UAAY,MAAA;AAAA"}

package/dist/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * @forinda/kickjs-cli-kit v0.1.1
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+function defineGenerator(spec){return spec}function defineCliPlugin(p){return p}var KickPluginConflictError=class extends Error{constructor(kind,id,owners){super(`Two plugins registered the same ${kind} '${id}': ${owners.join(`, `)}. Plugins must use unique ${kind} names.`),this.name=`KickPluginConflictError`}};export{KickPluginConflictError,defineCliPlugin,defineGenerator};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/generators.ts","../src/index.ts"],"sourcesContent":["/**\n * Plugin generator API per architecture.md §21.2.3 — lets first-party\n * AND third-party packages ship `kick g <name>` scaffolders the same\n * way the framework's built-in generators do.\n *\n * Plugins declare a discovery file in their `package.json`:\n *\n * ```json\n * {\n *   \"name\": \"@my-org/kickjs-cqrs\",\n *   \"kickjs\": { \"generators\": \"./dist/generators.js\" }\n * }\n * ```\n *\n * The discovery file exports a typed manifest:\n *\n * ```ts\n * import { defineGenerator } from '@forinda/kickjs-cli-kit'\n *\n * export default [\n *   defineGenerator({\n *     name: 'command',\n *     description: 'Generate a CQRS command + handler',\n *     args: [{ name: 'name', required: true }],\n *     files: (ctx) => [\n *       {\n *         path: `src/modules/${ctx.kebab}/commands/create-${ctx.kebab}.command.ts`,\n *         content: `// generated command for ${ctx.pascal}`,\n *       },\n *     ],\n *   }),\n * ]\n * ```\n *\n * `kick g command Order` then dispatches against the registered\n * generator and writes the returned files relative to `cwd`.\n */\n\n/**\n * Resolved naming variants + project context handed to a generator's\n * `files()` factory. Keys mirror `TemplateContext` so first-party\n * generators that rely on the same shape can be migrated to plugin\n * generators without rewriting their templates.\n */\nexport interface GeneratorContext {\n  /** Raw name passed on the command line (`kick g drizzle-typegen UserPost` → `'UserPost'`). */\n  name: string\n  /** PascalCase form (`UserPost`). */\n  pascal: string\n  /** kebab-case form (`user-post`). */\n  kebab: string\n  /** camelCase form (`userPost`). */\n  camel: string\n  /** snake_case form (`user_post`). */\n  snake: string\n  /** Pluralized PascalCase (`UserPosts`) — present when the project enables `pluralize`. */\n  pluralPascal?: string\n  /** Pluralized kebab-case (`user-posts`). */\n  pluralKebab?: string\n  /** Pluralized camelCase (`userPosts`). */\n  pluralCamel?: string\n  /** Modules directory from `kick.config.ts` (default `'src/modules'`). */\n  modulesDir: string\n  /**\n   * Working directory the CLI was invoked from. May be a nested subdirectory\n   * if the adopter ran `kick g ...` from `src/modules/foo/` — for \"write\n   * files relative to the project\" use {@link projectRoot} instead.\n   */\n  cwd: string\n  /**\n   * Resolved project root — the nearest ancestor directory of {@link cwd}\n   * containing `kick.config.{ts,js,mjs,json}` (or `package.json` as a\n   * fallback). Always set; falls back to `cwd` when no marker is found.\n   *\n   * Use this when writing files that must land at a known location\n   * regardless of where the adopter typed the command. `kick g ...` from\n   * inside `src/modules/foo/` will still see `projectRoot` pointing at\n   * the directory that owns `kick.config.ts`.\n   */\n  projectRoot: string\n  /** Positional arguments passed AFTER the name (e.g. `kick g command Order extra1 extra2` → `['extra1', 'extra2']`). */\n  args: string[]\n  /** Flag values from the command line — booleans for switches, strings for `--key value`. */\n  flags: Record<string, string | boolean>\n}\n\n/** A single output file the generator wants written. */\nexport interface GeneratorFile {\n  /**\n   * Output path. Relative paths resolve against `ctx.cwd`; absolute\n   * paths are used as-is. Parent directories are created automatically.\n   */\n  path: string\n  /** File contents written verbatim (UTF-8). */\n  content: string\n}\n\n/** CLI argument descriptor surfaced in `kick g --list` help. */\nexport interface GeneratorArg {\n  name: string\n  required?: boolean\n  description?: string\n}\n\n/** CLI flag descriptor — boolean unless `takesValue: true`. */\nexport interface GeneratorFlag {\n  name: string\n  alias?: string\n  description?: string\n  takesValue?: boolean\n}\n\n/**\n * Spec returned by {@link defineGenerator}. Plugin discovery files\n * export `GeneratorSpec[]` as their default export.\n */\nexport interface GeneratorSpec {\n  /**\n   * Dispatch name — `kick g <name>` looks for an exact match against\n   * this string after the built-in generators are checked.\n   */\n  name: string\n  /** Description shown in `kick g --list` and `--help`. */\n  description: string\n  /** Optional argument descriptors — informational, surfaced in help output. */\n  args?: readonly GeneratorArg[]\n  /** Optional flag descriptors — informational, surfaced in help output. */\n  flags?: readonly GeneratorFlag[]\n  /** Build the output files for one invocation. May return a Promise. */\n  files(ctx: GeneratorContext): GeneratorFile[] | Promise<GeneratorFile[]>\n}\n\n/**\n * Identity factory — returns the spec verbatim. Exists for type\n * inference and forward-compatibility (future fields can be added with\n * defaults).\n *\n * @example\n * ```ts\n * import { defineGenerator } from '@forinda/kickjs-cli-kit'\n *\n * export default [\n *   defineGenerator({\n *     name: 'command',\n *     description: 'Generate a CQRS command + handler',\n *     files: (ctx) => [\n *       {\n *         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,\n *         content: `// command for ${ctx.pascal}`,\n *       },\n *     ],\n *   }),\n * ]\n * ```\n */\nexport function defineGenerator(spec: GeneratorSpec): GeneratorSpec {\n  return spec\n}\n","/**\n * `@forinda/kickjs-cli-kit` — the shared CLI-plugin contract.\n *\n * Both `@forinda/kickjs-cli` and packages that want to ship CLI commands\n * (e.g. `@forinda/kickjs-db/cli`) implement these types. Keeping the\n * contract in a dependency-free package breaks the dependency cycle that\n * would form if a package depended on `@forinda/kickjs-cli` to get\n * `defineCliPlugin` while the CLI depended on that package.\n *\n * The contract deliberately keeps the deep cli types loose:\n * - `ctx.config` is generic (`TConfig`, default `unknown`) — the host CLI\n *   passes its full config; consumers narrow as needed.\n * - `typegens` use {@link CliTypegen}, the structural shape the CLI's\n *   `TypegenPlugin` satisfies, so the kit never imports the typegen\n *   scanner.\n *\n * @module @forinda/kickjs-cli-kit\n */\n\nimport type { Command } from 'commander'\n\nexport * from './generators'\nimport type { GeneratorSpec } from './generators'\n\n/**\n * A declarative shell-handler command — the same shape as the\n * `kick.config.ts > commands` field.\n */\nexport interface KickCommandDefinition {\n  /** The command name (e.g. 'db:migrate', 'seed', 'proto:gen'). */\n  name: string\n  /** Description shown in --help. */\n  description: string\n  /**\n   * Shell command(s) to run. A single string or an array of sequential\n   * steps. Use `{args}` as a placeholder for forwarded CLI arguments.\n   */\n  steps: string | string[]\n  /** Optional aliases (e.g. ['migrate'] for 'db:migrate'). */\n  aliases?: string[]\n}\n\n/**\n * Structural shape of a typegen plugin as seen by the CLI-plugin\n * contract. The CLI's full `TypegenPlugin` satisfies this (the `ctx`\n * parameter is intentionally `any` here so the kit doesn't depend on the\n * CLI's `TypegenContext` / scanner types).\n */\nexport interface CliTypegen {\n  id: string\n  inputs: string[]\n  outExtension?: string\n  // `ctx` is `any` so the kit doesn't depend on the CLI's TypegenContext;\n  // the return matches the CLI's TypegenPlugin exactly so the two are\n  // mutually assignable.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  generate(ctx: any): Promise<string | null>\n}\n\n/** A plugin generator paired with the plugin name that supplied it. */\nexport interface DiscoveredGenerator {\n  source: string\n  spec: GeneratorSpec\n}\n\n/**\n * Runtime context handed to a plugin's `register()`. Forward-compatible:\n * new fields land here without changing the callback signature.\n */\nexport interface KickCliPluginContext<TConfig = unknown> {\n  /** Directory the CLI was invoked from (may be a nested subdirectory). */\n  cwd: string\n  /**\n   * Resolved project root — the nearest ancestor with a\n   * `kick.config.{ts,js,mjs,json}` (or `package.json`). Prefer this over\n   * `cwd` for writing artifacts at a stable location.\n   */\n  projectRoot: string\n  /** The loaded host config (the CLI passes its full config). */\n  config: TConfig | null\n  log: (msg: string) => void\n  /** Plugin-shipped generators merged by the host, threaded for register(). */\n  generators?: DiscoveredGenerator[]\n}\n\n/**\n * A CLI plugin: contributes commands, programmatic command registration,\n * typegens, and/or generators. Implemented by the CLI's built-ins and by\n * adopter / first-party packages alike.\n */\nexport interface KickCliPlugin<TConfig = unknown> {\n  /** Stable identifier — used in conflict errors + de-dup. */\n  name: string\n  /** Declarative shell-handler commands. */\n  commands?: KickCommandDefinition[]\n  /** Programmatic command registration, called once at CLI startup. */\n  register?: (program: Command, ctx: KickCliPluginContext<TConfig>) => void | Promise<void>\n  /** Typegen plugins the host runs after its own pass. */\n  typegens?: CliTypegen[]\n  /** `kick g <name>` scaffolders. */\n  generators?: GeneratorSpec[]\n}\n\n/**\n * Identity helper for type inference + parity with `definePlugin` /\n * `defineAdapter`. Returns the plugin verbatim.\n */\nexport function defineCliPlugin<TConfig = unknown>(\n  p: KickCliPlugin<TConfig>,\n): KickCliPlugin<TConfig> {\n  return p\n}\n\n/** Thrown when two plugins register the same plugin/command/typegen/generator id. */\nexport class KickPluginConflictError extends Error {\n  constructor(kind: 'plugin' | 'command' | 'typegen' | 'generator', id: string, owners: string[]) {\n    super(\n      `Two plugins registered the same ${kind} '${id}': ${owners.join(', ')}. ` +\n        `Plugins must use unique ${kind} names.`,\n    )\n    this.name = 'KickPluginConflictError'\n  }\n}\n"],"mappings":";;;;;;;;;;AA2JA,SAAgB,gBAAgB,KAAoC,CAClE,OAAO,KCjDT,SAAgB,gBACd,EACwB,CACxB,OAAO,EAIT,IAAa,wBAAb,cAA6C,KAAM,CACjD,YAAY,KAAsD,GAAY,OAAkB,CAC9F,MACE,mCAAmC,KAAK,IAAI,GAAG,KAAK,OAAO,KAAK,KAAK,CAAC,4BACzC,KAAK,SACnC,CACD,KAAK,KAAO"}

package/package.json

@@ -1,14 +1,62 @@
 {
   "name": "@forinda/kickjs-cli-kit",
-  "version": "0.0.0",
-  "description": "Placeholder for @forinda/kickjs-cli-kit",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "forinda (https://www.npmjs.com/~forinda)",
-  "license": "UNLICENSED",
-  "private": false,
+  "version": "0.1.1",
+  "description": "Shared CLI-plugin contract for KickJS — defineCliPlugin, defineGenerator, and the types CLI plugins implement",
+  "keywords": [
+    "kickjs",
+    "cli",
+    "plugin",
+    "generator",
+    "commander",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "commander": ">=12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "commander": "^14.0.2",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.3"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/cli-kit"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsgo --noEmit",
+    "clean": "rm -rf dist .wireit",
+    "lint": "tsc --noEmit"
   }
 }

package/index.js

@@ -1 +0,0 @@
-// Placeholder