@forinda/kickjs-cli-kit 0.1.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.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli-kit v0.1.0
+ * @forinda/kickjs-cli-kit v0.1.1
  *
  * Copyright (c) Felix Orinda
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-cli-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared CLI-plugin contract for KickJS — defineCliPlugin, defineGenerator, and the types CLI plugins implement",
   "keywords": [
     "kickjs",
@@ -20,16 +20,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run --passWithNoTests",
-    "typecheck": "tsgo --noEmit",
-    "clean": "rm -rf dist .wireit",
-    "lint": "tsc --noEmit"
-  },
   "dependencies": {},
   "peerDependencies": {
     "commander": ">=12.0.0"
@@ -56,5 +50,13 @@
   "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"
   }
-}
+}