@forinda/kickjs-cli 8.4.0 → 8.6.0

package/dist/{types-CW4qiwB1.mjs → types-lHwt_SNI.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.4.0
+ * @forinda/kickjs-cli v8.6.0
  *
  * Copyright (c) Felix Orinda
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-cli",
-  "version": "8.4.0",
+  "version": "8.6.0",
   "description": "CLI for KickJS — project scaffolding, DDD module generation, dev/build/start",
   "keywords": [
     "kickjs",
@@ -29,30 +29,31 @@
   },
   "files": [
     "bin.js",
-    "dist"
+    "dist",
+    "templates"
   ],
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "commander": "^15.0.0",
     "glob": "^13.0.6",
     "jiti": "^2.7.0",
-    "oxc-parser": "^0.150.0",
-    "oxfmt": "^0.68.0",
+    "oxc-parser": "^0.151.0",
+    "oxfmt": "^0.70.0",
     "picocolors": "^1.1.1",
     "pluralize": "^8.0.0",
-    "@forinda/kickjs-cli-kit": "0.1.2",
-    "@forinda/kickjs-db": "7.3.0",
-    "@forinda/kickjs": "8.6.0"
+    "@forinda/kickjs": "8.7.0",
+    "@forinda/kickjs-db": "7.4.0",
+    "@forinda/kickjs-cli-kit": "0.1.2"
   },
   "devDependencies": {
     "@swc/core": "^1.16.2",
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@types/pg": "^8.23.1",
     "@types/pluralize": "^0.0.33",
     "@typescript/typescript6": "^6.0.2",
     "pg": "^8.23.0",
     "typescript": "^7.0.2",
-    "vite": "^8.3.0",
+    "vite": "^8.3.1",
     "vitest": "^5.0.1",
     "@forinda/kickjs-ai": "8.0.0"
   },

package/templates/base/feature.json

@@ -0,0 +1,18 @@
+{
+  "dependencies": ["@forinda/kickjs", "@forinda/kickjs-schema", "dotenv", "reflect-metadata"],
+  "devDependencies": [
+    "@forinda/kickjs-cli",
+    "@forinda/kickjs-testing",
+    "@forinda/kickjs-vite",
+    "@types/supertest",
+    "@swc/core",
+    "@types/node",
+    "unplugin-swc",
+    "vite",
+    "supertest",
+    "vitest",
+    "typescript",
+    "oxfmt",
+    "oxlint"
+  ]
+}

package/templates/base/files/README.md

@@ -0,0 +1,61 @@
+# {{name}}
+
+A **{{templateLabel}}** built with [KickJS](https://kickjs.app/) — a decorator-driven Node.js framework for TypeScript that runs on Express, Fastify, or h3 (swap the engine in one line).
+
+## Getting Started
+
+```bash
+{{packageManager}} install
+kick dev
+```
+
+## Scripts
+
+| Command                              | Description                          |
+| ------------------------------------ | ------------------------------------ |
+| `kick dev`                           | Start dev server with Vite HMR       |
+| `kick build`                         | Production build                     |
+| `kick start`                         | Run production build                 |
+| `{{packageManager}} run test`        | Run tests with Vitest                |
+| `kick g module <name>`               | Generate a DDD module                |
+| `kick g scaffold <name> <fields...>` | Generate CRUD from field definitions |
+| `kick add <package>`                 | Add a KickJS package                 |
+
+## Project Structure
+
+```
+src/
+├── index.ts           # Application entry point
+├── modules/           # Feature modules (controllers, services, repos)
+│   └── index.ts       # Module registry
+└── ...
+```
+
+## Packages
+
+{{packages}}
+
+## Adding Features
+
+```bash
+kick add swagger       # OpenAPI documentation
+kick add ws            # WebSocket support
+kick add queue         # Background job processing
+kick add --list        # Show all available packages
+```
+
+For email, scheduled tasks, multi-tenancy, OpenTelemetry, GraphQL, and notifications use the BYO recipes in the [KickJS guides](https://kickjs.app/guide/) — they wire the upstream library through `defineAdapter()` / `definePlugin()` directly, so you keep control of the integration.
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+| Variable   | Default       | Description |
+| ---------- | ------------- | ----------- |
+| `PORT`     | `3000`        | Server port |
+| `NODE_ENV` | `development` | Environment |
+
+## Learn More
+
+- [KickJS Documentation](https://kickjs.app/)
+- [CLI Reference](https://kickjs.app/api/cli.html)

package/templates/base/files/_dot_editorconfig

@@ -0,0 +1,13 @@
+# https://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/base/files/_dot_env

@@ -0,0 +1,2 @@
+PORT=3000
+NODE_ENV=development

package/templates/base/files/_dot_env.example

@@ -0,0 +1,2 @@
+PORT=3000
+NODE_ENV=development

package/templates/base/files/_dot_env.test

@@ -0,0 +1,9 @@
+# Read INSTEAD of .env when NODE_ENV=test (or under vitest).
+# No fallback to .env — declare here everything the suite needs, so a
+# missing var fails the run instead of silently resolving to your dev value.
+#
+# Not committed. Add new keys to .env.test.example too, with placeholder
+# values — never real endpoints or credentials.
+NODE_ENV=test
+PORT=0
+LOG_LEVEL=silent

package/templates/base/files/_dot_env.test.example

@@ -0,0 +1,11 @@
+# Template for .env.test. Copy it and fill in your machine's values:
+#   cp .env.test.example .env.test
+# Read INSTEAD of .env when NODE_ENV=test (or under vitest).
+# No fallback to .env — declare here everything the suite needs, so a
+# missing var fails the run instead of silently resolving to your dev value.
+#
+# This file is committed; .env.test is not. Keep the two in step, with
+# placeholder values here — never real endpoints or credentials.
+NODE_ENV=test
+PORT=0
+LOG_LEVEL=silent

package/templates/base/files/_dot_gitattributes

@@ -0,0 +1,18 @@
+# Auto-detect text files and normalise line endings to LF
+* text=auto eol=lf
+
+# Explicitly mark generated / binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+
+# Lock files — treat as generated
+pnpm-lock.yaml -diff linguist-generated
+yarn.lock -diff linguist-generated
+package-lock.json -diff linguist-generated

package/templates/base/files/_dot_gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.env
+# Machine-specific: each developer's test env differs (database names, ports).
+# The shared template is the committed `.env.test.example`.
+.env.test
+*.local
+coverage/
+.DS_Store
+*.tsbuildinfo
+.kickjs/
+# Platform build output — written by `kick build:netlify` / `kick build:vercel`.
+.netlify/
+.vercel/

package/templates/base/files/_dot_oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "ignorePatterns": ["**/dist/", "**/.kickjs/", "**/node_modules/"]
+}

package/templates/base/files/kick.config.ts

@@ -0,0 +1,58 @@
+import { defineConfig } from '@forinda/kickjs-cli'
+
+export default defineConfig({
+  pattern: '{{template}}',
+  // The HTTP engine this app boots on (matches `bootstrap({ runtime })` in
+  // src/index.ts). Dep-aware commands read it: `kick add upload` installs the
+  // engine's multipart driver, `kick doctor` checks the engine peers, and
+  // `kick typegen` flips the runtime escape-hatch types to this engine.
+  runtime: '{{runtime}}',
+  // Pinned so `kick add` and other dep-installing commands always use the
+  // project's intended package manager, regardless of which lockfile exists.
+  packageManager: '{{packageManager}}',
+  modules: {
+    dir: 'src/modules',
+    // @kick:repo
+    pluralize: true,
+  },
+
+  // `kick typegen` populates `.kickjs/types/` so `Ctx<KickRoutes.X['method']>`
+  // resolves to fully-typed params/body/query. Auto-runs on `kick dev`.
+  // `'kickjs-schema'` routes inference through `InferSchemaOutput` so the
+  // typegen works for any wrapped schema (Zod / Valibot / Yup). Switch
+  // to `'zod'` if you ship Zod schemas without `fromZod()` wrapping, or
+  // set `schemaValidator: false` to skip schema-driven body typing.
+  typegen: {
+    schemaValidator: 'kickjs-schema',
+    // @kick:typegen-option
+  },
+
+  commands: [
+    {
+      name: 'test',
+      description: 'Run tests with Vitest',
+      steps: 'vitest run',
+    },
+    {
+      name: 'lint',
+      description: 'Lint with oxlint',
+      steps: 'oxlint src/',
+    },
+    {
+      name: 'format',
+      description: 'Format code with oxfmt',
+      steps: 'oxfmt src/',
+    },
+    {
+      name: 'format:check',
+      description: 'Check formatting without writing',
+      steps: 'oxfmt --check src/',
+    },
+    {
+      name: 'ci:check',
+      description: 'Run typecheck + lint + format check',
+      steps: ['kick typecheck', 'oxlint src/', 'oxfmt --check src/'],
+      aliases: ['verify'],
+    },
+  ],
+})

package/templates/base/files/src/modules/hello/hello.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get, Autowired, type Ctx } from '@forinda/kickjs'
+import { HelloService } from './hello.service'
+
+// `Ctx<KickRoutes.HelloController['<method>']>` is generated by
+// `kick typegen` (auto-run on `kick dev`). The first run after a fresh
+// scaffold creates `.kickjs/types/routes.ts` so this file typechecks.
+// See https://kickjs.app/guide/typegen.
+
+@Controller()
+export class HelloController {
+  @Autowired() private readonly helloService!: HelloService
+
+  // Return-value handlers: the runtime sends the returned payload as
+  // 200 json, and `kick typegen` infers the response type into
+  // `KickRoutes.Api` — which is what makes the typed client
+  // (@forinda/kickjs-client) end-to-end type-safe.
+  @Get('/')
+  index(_ctx: Ctx<KickRoutes.HelloController['index']>) {
+    return this.helloService.greet('World')
+  }
+
+  @Get('/health')
+  health(_ctx: Ctx<KickRoutes.HelloController['health']>) {
+    return this.helloService.healthCheck()
+  }
+}

package/templates/base/files/src/modules/hello/hello.module.ts

@@ -0,0 +1,21 @@
+import { defineModule } from '@forinda/kickjs'
+import { HelloController } from './hello.controller'
+
+export const HelloModule = defineModule({
+  name: 'HelloModule',
+  build: () => ({
+    // `register(container)` is optional — only implement it when you need
+    // to bind a token to a concrete implementation, e.g.
+    //   register(container) {
+    //     container.registerFactory(USER_REPOSITORY, () => container.resolve(InMemoryUserRepository))
+    //   }
+    // The HelloService uses @Service() so the decorator handles registration.
+
+    routes() {
+      return {
+        path: '/hello',
+        controller: HelloController,
+      }
+    },
+  }),
+})

package/templates/base/files/src/modules/hello/hello.service.ts

@@ -0,0 +1,12 @@
+import { Service } from '@forinda/kickjs'
+
+@Service()
+export class HelloService {
+  greet(name: string) {
+    return { message: `Hello ${name} from KickJS!`, timestamp: new Date().toISOString() }
+  }
+
+  healthCheck() {
+    return { status: 'ok', uptime: process.uptime() }
+  }
+}

package/templates/base/files/src/modules/index.ts

@@ -0,0 +1,7 @@
+import { defineModules } from '@forinda/kickjs'
+import { HelloModule } from './hello/hello.module'
+
+// Remove HelloModule and run: kick g module <name>
+// `defineModules()` returns a chainable list — `kick g module` appends
+// `.mount(NewModule())` to the chain on every generation.
+export const modules = defineModules().mount(HelloModule())

package/templates/base/files/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node", "vite/client"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "outDir": "dist",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", ".kickjs/types/**/*.d.ts", ".kickjs/types/**/*.ts"]
+}

package/templates/base/files/vite.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vite'
+import { fileURLToPath } from 'node:url'
+import swc from 'unplugin-swc'
+import { kickjsVitePlugin, envWatchPlugin } from '@forinda/kickjs-vite'
+
+export default defineConfig({
+  oxc: false,
+  plugins: [
+    swc.vite(),
+    kickjsVitePlugin({ entry: 'src/index.ts' }),
+    // Watches .env files and triggers a full reload on change so the
+    // dev server picks up env tweaks without a manual restart.
+    envWatchPlugin(),
+  ],
+  // @kick:vite-option
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  build: {
+    target: 'node20',
+    ssr: true,
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      input: fileURLToPath(new URL('./src/index.ts', import.meta.url)),
+      output: { format: 'esm' },
+    },
+  },
+})

package/templates/base/files/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config.ts'
+
+// A `vitest.config.ts` OVERRIDES `vite.config.ts` outright — vitest does not
+// merge the two, and it never reads tsconfig `paths`. Restating settings here
+// would mean the `@` alias lives in three files and drifts in two of them, so
+// merge the real config instead: the alias, plugins, and ssr externals all come
+// from one place.
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      globals: true,
+      environment: 'node',
+      include: ['src/**/*.test.ts'],
+    },
+  }),
+)

package/templates/feature-devtools/feature.json

@@ -0,0 +1,13 @@
+{
+  "dependencies": ["@forinda/kickjs-devtools"],
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs-devtools",
+        "names": ["DevToolsAdapter"]
+      },
+      "slot": "adapter",
+      "code": "DevToolsAdapter()"
+    }
+  ]
+}

package/templates/feature-queue/feature.json

@@ -0,0 +1,16 @@
+{
+  "dependencies": ["@forinda/kickjs-queue", "bullmq", "ioredis"],
+  "builds": {
+    "msgpackr-extract": false
+  },
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs-queue",
+        "names": ["QueueAdapter"]
+      },
+      "slot": "adapter",
+      "code": "// BullMQ over Redis. Nothing connects until a @Job class or a queue\n// is used, so the app boots without Redis running.\nQueueAdapter({\n  redis: {\n    host: process.env.REDIS_HOST ?? '127.0.0.1',\n    port: Number(process.env.REDIS_PORT ?? 6379),\n  },\n})"
+    }
+  ]
+}

package/templates/feature-queue/files/_dot_env.append

@@ -0,0 +1,2 @@
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379

package/templates/feature-queue/files/_dot_env.example.append

@@ -0,0 +1,2 @@
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379

package/templates/feature-swagger/feature.json

@@ -0,0 +1,16 @@
+{
+  "dependencies": ["@forinda/kickjs-swagger"],
+  "builds": {
+    "@scarf/scarf": true
+  },
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs-swagger",
+        "names": ["SwaggerAdapter"]
+      },
+      "slot": "adapter",
+      "code": "SwaggerAdapter({ info: { title: '{{name}}', version: '{{version}}' } })"
+    }
+  ]
+}

package/templates/feature-ws/feature.json

@@ -0,0 +1,13 @@
+{
+  "dependencies": ["@forinda/kickjs-ws", "ws"],
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs-ws",
+        "names": ["WsAdapter"]
+      },
+      "slot": "adapter",
+      "code": "// WebSocket upgrades on /ws \u2014 see guide/websockets.\nWsAdapter({ path: '/ws' })"
+    }
+  ]
+}

package/templates/fullstack-root/files/_dot_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+# Platform build output — written by `kick build:netlify` / `kick build:vercel`.
+.netlify/
+.vercel/

package/templates/fullstack-root/files/netlify.toml

@@ -0,0 +1,13 @@
+[build]
+command = "{{packageManager}} run build:netlify"
+publish = "web/dist"
+
+[build.environment]
+NODE_VERSION = "22"
+
+# Client-side routes fall back to the app shell. The function claims /api/*
+# through its own `config.path`, so this rule never sees those requests.
+[[redirects]]
+from = "/*"
+to = "/index.html"
+status = 200

package/templates/fullstack-root/files/vercel.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "buildCommand": "{{packageManager}} run build:vercel"
+}

package/templates/host-config/files/netlify.toml

@@ -0,0 +1,6 @@
+[build]
+command = "{{packageManager}} run build:netlify"
+publish = "dist/public"
+
+[build.environment]
+NODE_VERSION = "22"

package/templates/host-config/files/vercel.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "buildCommand": "{{packageManager}} run build:vercel"
+}

package/templates/runtime-express/feature.json

@@ -0,0 +1,22 @@
+{
+  "dependencies": ["express"],
+  "devDependencies": ["@types/express"],
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs",
+        "names": ["expressRuntime"]
+      },
+      "slot": "runtime",
+      "code": "runtime: expressRuntime()"
+    },
+    {
+      "import": {
+        "from": "express",
+        "default": "express"
+      },
+      "slot": "middleware",
+      "code": "// Express needs a body parser; Fastify and h3 parse bodies natively.\nexpress.json()"
+    }
+  ]
+}

package/templates/runtime-fastify/feature.json

@@ -0,0 +1,13 @@
+{
+  "dependencies": ["fastify", "@fastify/middie", "serve-static"],
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs/fastify",
+        "names": ["fastifyRuntime"]
+      },
+      "slot": "runtime",
+      "code": "runtime: fastifyRuntime()"
+    }
+  ]
+}

package/templates/runtime-h3/feature.json

@@ -0,0 +1,13 @@
+{
+  "dependencies": ["h3", "serve-static"],
+  "integrations": [
+    {
+      "import": {
+        "from": "@forinda/kickjs/h3",
+        "names": ["h3Runtime"]
+      },
+      "slot": "runtime",
+      "code": "runtime: h3Runtime()"
+    }
+  ]
+}

package/templates/schema-valibot/feature.json

@@ -0,0 +1,3 @@
+{
+  "dependencies": ["valibot"]
+}

package/templates/schema-valibot/files/src/config/index.ts

@@ -0,0 +1,41 @@
+import { loadEnvFromSchema } from '@forinda/kickjs/config'
+import { fromValibot } from '@forinda/kickjs-schema/valibot'
+import * as v from 'valibot'
+
+/**
+ * Project environment schema (Valibot).
+ *
+ * `fromValibot` wraps the Valibot schema as a `KickSchema` so the
+ * env loader, validate middleware, and swagger spec generator all see
+ * the same shape. The default export is the contract `kick typegen`
+ * reads to populate `KickEnv` via `InferSchemaOutput<typeof _envSchema>`
+ * — that's what makes `@Value('FOO')` autocomplete and
+ * `process.env.FOO` typed.
+ *
+ * @example
+ *   DATABASE_URL: v.pipe(v.string(), v.url()),
+ *   JWT_SECRET:   v.pipe(v.string(), v.minLength(32)),
+ *   REDIS_URL:    v.optional(v.pipe(v.string(), v.url())),
+ */
+const envSchema = fromValibot(
+  v.object({
+    PORT: v.optional(v.pipe(v.string(), v.transform(Number)), '3000'),
+    NODE_ENV: v.optional(v.picklist(['development', 'production', 'test']), 'development'),
+    LOG_LEVEL: v.optional(v.string(), 'info'),
+    // DATABASE_URL: v.pipe(v.string(), v.url()),
+  }),
+)
+
+/**
+ * IMPORTANT — side effect: register the schema with kickjs's env cache
+ * **at module-load time**. `ConfigService` and `@Value()` both consume
+ * this cache, and they will fall back to the base schema (or undefined)
+ * if no extended schema has been registered before they're resolved.
+ *
+ * As long as `src/index.ts` imports this file (`import './config'`) at
+ * the top — before `bootstrap()` runs — every controller and service
+ * in the app sees the typed extended values.
+ */
+export const env = loadEnvFromSchema(envSchema)
+
+export default envSchema

package/templates/schema-yup/feature.json

@@ -0,0 +1,3 @@
+{
+  "dependencies": ["yup"]
+}