@forinda/kickjs-cli 0.3.0

package/dist/cli.js

@@ -0,0 +1,1264 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { resolve } from "path";
+
+// src/generators/project.ts
+import { join } from "path";
+
+// src/utils/fs.ts
+import { writeFile, mkdir, access, readFile } from "fs/promises";
+import { dirname } from "path";
+async function writeFileSafe(filePath, content) {
+  await mkdir(dirname(filePath), {
+    recursive: true
+  });
+  await writeFile(filePath, content, "utf-8");
+}
+__name(writeFileSafe, "writeFileSafe");
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(fileExists, "fileExists");
+
+// src/generators/project.ts
+async function initProject(options) {
+  const { name, directory, packageManager = "pnpm" } = options;
+  const dir = directory;
+  console.log(`
+  Creating KickJS project: ${name}
+`);
+  await writeFileSafe(join(dir, "package.json"), JSON.stringify({
+    name,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      dev: "kick dev",
+      "dev:debug": "kick dev:debug",
+      build: "kick build",
+      start: "kick start",
+      test: "vitest run",
+      "test:watch": "vitest",
+      typecheck: "tsc --noEmit",
+      lint: "eslint src/",
+      format: "prettier --write src/"
+    },
+    dependencies: {
+      "@forinda/kickjs-core": "^0.1.0",
+      "@forinda/kickjs-http": "^0.1.0",
+      "@forinda/kickjs-config": "^0.1.0",
+      "@forinda/kickjs-swagger": "^0.1.0",
+      express: "^5.1.0",
+      "reflect-metadata": "^0.2.2",
+      zod: "^4.3.6",
+      pino: "^10.3.1",
+      "pino-pretty": "^13.1.3"
+    },
+    devDependencies: {
+      "@forinda/kickjs-cli": "^0.1.0",
+      "@swc/core": "^1.7.28",
+      "@types/express": "^5.0.6",
+      "@types/node": "^24.5.2",
+      "unplugin-swc": "^1.5.9",
+      vite: "^7.3.1",
+      "vite-node": "^5.3.0",
+      vitest: "^3.2.4",
+      typescript: "^5.9.2",
+      prettier: "^3.8.1"
+    }
+  }, null, 2));
+  await writeFileSafe(join(dir, "vite.config.ts"), `import { defineConfig } from 'vite'
+import { resolve } from 'path'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  plugins: [swc.vite()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  server: {
+    watch: { usePolling: false },
+    hmr: true,
+  },
+  build: {
+    target: 'node20',
+    ssr: true,
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      input: resolve(__dirname, 'src/index.ts'),
+      output: { format: 'esm' },
+    },
+  },
+})
+`);
+  await writeFileSafe(join(dir, "tsconfig.json"), JSON.stringify({
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: [
+        "ES2022"
+      ],
+      types: [
+        "node"
+      ],
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      sourceMap: true,
+      declaration: true,
+      experimentalDecorators: true,
+      emitDecoratorMetadata: true,
+      outDir: "dist",
+      rootDir: "src",
+      paths: {
+        "@/*": [
+          "./src/*"
+        ]
+      }
+    },
+    include: [
+      "src"
+    ]
+  }, null, 2));
+  await writeFileSafe(join(dir, ".prettierrc"), JSON.stringify({
+    semi: false,
+    singleQuote: true,
+    trailingComma: "all",
+    printWidth: 100,
+    tabWidth: 2
+  }, null, 2));
+  await writeFileSafe(join(dir, ".gitignore"), `node_modules/
+dist/
+.env
+coverage/
+.DS_Store
+*.tsbuildinfo
+`);
+  await writeFileSafe(join(dir, ".env"), `PORT=3000
+NODE_ENV=development
+`);
+  await writeFileSafe(join(dir, ".env.example"), `PORT=3000
+NODE_ENV=development
+`);
+  await writeFileSafe(join(dir, "src/index.ts"), `import 'reflect-metadata'
+import { bootstrap } from '@forinda/kickjs-http'
+import { SwaggerAdapter } from '@forinda/kickjs-swagger'
+import { modules } from './modules'
+
+bootstrap({
+  modules,
+  adapters: [
+    new SwaggerAdapter({
+      info: { title: '${name}', version: '0.1.0' },
+    }),
+  ],
+})
+`);
+  await writeFileSafe(join(dir, "src/modules/index.ts"), `import type { AppModuleClass } from '@forinda/kickjs-core'
+
+export const modules: AppModuleClass[] = []
+`);
+  await writeFileSafe(join(dir, "vitest.config.ts"), `import { defineConfig } from 'vitest/config'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  plugins: [swc.vite()],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})
+`);
+  console.log("  Project scaffolded successfully!");
+  console.log();
+  console.log("  Next steps:");
+  console.log(`    cd ${name}`);
+  console.log(`    ${packageManager} install`);
+  console.log(`    kick g module user`);
+  console.log(`    kick dev`);
+  console.log();
+  console.log("  Commands:");
+  console.log("    kick dev         Start dev server with Vite HMR");
+  console.log("    kick build       Production build via Vite");
+  console.log("    kick start       Run production build");
+  console.log("    kick g module X  Generate a DDD module");
+  console.log();
+}
+__name(initProject, "initProject");
+
+// src/commands/init.ts
+function registerInitCommand(program) {
+  program.command("new <name>").alias("init").description("Create a new KickJS project").option("-d, --directory <dir>", "Target directory (defaults to project name)").option("--pm <manager>", "Package manager: pnpm | npm | yarn", "pnpm").action(async (name, opts) => {
+    const directory = resolve(opts.directory || name);
+    await initProject({
+      name,
+      directory,
+      packageManager: opts.pm
+    });
+  });
+}
+__name(registerInitCommand, "registerInitCommand");
+
+// src/commands/generate.ts
+import { resolve as resolve2 } from "path";
+
+// src/generators/module.ts
+import { join as join2 } from "path";
+
+// src/utils/naming.ts
+function toPascalCase(name) {
+  return name.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^(.)/, (c) => c.toUpperCase());
+}
+__name(toPascalCase, "toPascalCase");
+function toCamelCase(name) {
+  const pascal = toPascalCase(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+__name(toCamelCase, "toCamelCase");
+function toKebabCase(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+__name(toKebabCase, "toKebabCase");
+function pluralize(name) {
+  if (name.endsWith("s")) return name;
+  if (name.endsWith("x") || name.endsWith("z")) return name + "es";
+  if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
+  if (name.endsWith("y") && !/[aeiou]y$/.test(name)) return name.slice(0, -1) + "ies";
+  return name + "s";
+}
+__name(pluralize, "pluralize");
+function pluralizePascal(name) {
+  if (name.endsWith("s")) return name;
+  if (name.endsWith("x") || name.endsWith("z")) return name + "es";
+  if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
+  if (name.endsWith("y") && !/[aeiou]y$/i.test(name)) return name.slice(0, -1) + "ies";
+  return name + "s";
+}
+__name(pluralizePascal, "pluralizePascal");
+
+// src/generators/module.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+async function generateModule(options) {
+  const { name, modulesDir, noEntity, noTests, repo = "inmemory", minimal } = options;
+  const kebab = toKebabCase(name);
+  const pascal = toPascalCase(name);
+  const camel = toCamelCase(name);
+  const plural = pluralize(kebab);
+  const pluralPascal = pluralizePascal(pascal);
+  const moduleDir = join2(modulesDir, plural);
+  const files = [];
+  const write = /* @__PURE__ */ __name(async (relativePath, content) => {
+    const fullPath = join2(moduleDir, relativePath);
+    await writeFileSafe(fullPath, content);
+    files.push(fullPath);
+  }, "write");
+  await write("index.ts", `/**
+ * ${pascal} Module
+ *
+ * Self-contained feature module following Domain-Driven Design (DDD).
+ * Registers dependencies in the DI container and declares HTTP routes.
+ *
+ * Structure:
+ *   presentation/    \u2014 HTTP controllers (entry points)
+ *   application/     \u2014 Use cases (orchestration) and DTOs (validation)
+ *   domain/          \u2014 Entities, value objects, repository interfaces, domain services
+ *   infrastructure/  \u2014 Repository implementations (in-memory, Drizzle, Prisma, etc.)
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs-core'
+import { buildRoutes } from '@forinda/kickjs-http'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './domain/repositories/${kebab}.repository'
+import { ${repo === "inmemory" ? `InMemory${pascal}Repository` : `Drizzle${pascal}Repository`} } from './infrastructure/repositories/${repo === "inmemory" ? `in-memory-${kebab}` : `drizzle-${kebab}`}.repository'
+import { ${pascal}Controller } from './presentation/${kebab}.controller'
+
+// Eagerly load decorated classes so @Service()/@Repository() decorators register in the DI container
+import.meta.glob(
+  ['./domain/services/**/*.ts', './application/use-cases/**/*.ts', '!./**/*.test.ts'],
+  { eager: true },
+)
+
+export class ${pascal}Module implements AppModule {
+  /**
+   * Register module dependencies in the DI container.
+   * Bind repository interface tokens to their implementations here.
+   * To swap implementations (e.g. in-memory -> Drizzle), change the factory target.
+   */
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repo === "inmemory" ? `InMemory${pascal}Repository` : `Drizzle${pascal}Repository`}),
+    )
+  }
+
+  /**
+   * Declare HTTP routes for this module.
+   * The path is prefixed with the global apiPrefix and version (e.g. /api/v1/${plural}).
+   * Passing 'controller' enables automatic OpenAPI spec generation via SwaggerAdapter.
+   */
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`);
+  await write(`presentation/${kebab}.controller.ts`, `/**
+ * ${pascal} Controller
+ *
+ * Presentation layer \u2014 handles HTTP requests and delegates to use cases.
+ * Each method receives a RequestContext with typed body, params, and query.
+ *
+ * Decorators:
+ *   @Controller(path?) \u2014 registers this class as an HTTP controller
+ *   @Get/@Post/@Put/@Delete(path?, validation?) \u2014 defines routes with optional Zod validation
+ *   @Autowired() \u2014 injects dependencies lazily from the DI container
+ *   @Middleware(...handlers) \u2014 attach middleware at class or method level
+ *
+ * Add Swagger decorators (@ApiTags, @ApiOperation, @ApiResponse) from @forinda/kickjs-swagger
+ * for automatic OpenAPI documentation.
+ */
+import { Controller, Get, Post, Put, Delete, Autowired } from '@forinda/kickjs-core'
+import { RequestContext } from '@forinda/kickjs-http'
+import { Create${pascal}UseCase } from '../application/use-cases/create-${kebab}.use-case'
+import { Get${pascal}UseCase } from '../application/use-cases/get-${kebab}.use-case'
+import { List${pluralPascal}UseCase } from '../application/use-cases/list-${plural}.use-case'
+import { Update${pascal}UseCase } from '../application/use-cases/update-${kebab}.use-case'
+import { Delete${pascal}UseCase } from '../application/use-cases/delete-${kebab}.use-case'
+import { create${pascal}Schema } from '../application/dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from '../application/dtos/update-${kebab}.dto'
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private create${pascal}UseCase!: Create${pascal}UseCase
+  @Autowired() private get${pascal}UseCase!: Get${pascal}UseCase
+  @Autowired() private list${pluralPascal}UseCase!: List${pluralPascal}UseCase
+  @Autowired() private update${pascal}UseCase!: Update${pascal}UseCase
+  @Autowired() private delete${pascal}UseCase!: Delete${pascal}UseCase
+
+  @Post('/', { body: create${pascal}Schema })
+  async create(ctx: RequestContext) {
+    const result = await this.create${pascal}UseCase.execute(ctx.body)
+    ctx.created(result)
+  }
+
+  @Get('/')
+  async list(ctx: RequestContext) {
+    const result = await this.list${pluralPascal}UseCase.execute()
+    ctx.json(result)
+  }
+
+  @Get('/:id')
+  async getById(ctx: RequestContext) {
+    const result = await this.get${pascal}UseCase.execute(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema })
+  async update(ctx: RequestContext) {
+    const result = await this.update${pascal}UseCase.execute(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  async remove(ctx: RequestContext) {
+    await this.delete${pascal}UseCase.execute(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`);
+  await write(`application/dtos/create-${kebab}.dto.ts`, `import { z } from 'zod'
+
+/**
+ * Create ${pascal} DTO \u2014 Zod schema for validating POST request bodies.
+ * This schema is passed to @Post('/', { body: create${pascal}Schema }) for automatic validation.
+ * It also generates OpenAPI request body docs when SwaggerAdapter is used.
+ *
+ * Add more fields as needed. Supported Zod types:
+ *   z.string(), z.number(), z.boolean(), z.enum([...]),
+ *   z.array(), z.object(), .optional(), .default(), .transform()
+ */
+export const create${pascal}Schema = z.object({
+  name: z.string().min(1, 'Name is required').max(200),
+})
+
+export type Create${pascal}DTO = z.infer<typeof create${pascal}Schema>
+`);
+  await write(`application/dtos/update-${kebab}.dto.ts`, `import { z } from 'zod'
+
+export const update${pascal}Schema = z.object({
+  name: z.string().min(1).max(200).optional(),
+})
+
+export type Update${pascal}DTO = z.infer<typeof update${pascal}Schema>
+`);
+  await write(`application/dtos/${kebab}-response.dto.ts`, `export interface ${pascal}ResponseDTO {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+`);
+  const useCases = [
+    {
+      file: `create-${kebab}.use-case.ts`,
+      content: `/**
+ * Create ${pascal} Use Case
+ *
+ * Application layer \u2014 orchestrates a single business operation.
+ * Use cases are thin: validate input (via DTO), call domain/repo, return response.
+ * Keep business rules in the domain service, not here.
+ */
+import { Service, Inject } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Create${pascal}DTO } from '../dtos/create-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Create${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.create(dto)
+  }
+}
+`
+    },
+    {
+      file: `get-${kebab}.use-case.ts`,
+      content: `import { Service, Inject } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Get${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+}
+`
+    },
+    {
+      file: `list-${plural}.use-case.ts`,
+      content: `import { Service, Inject } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class List${pluralPascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(): Promise<${pascal}ResponseDTO[]> {
+    return this.repo.findAll()
+  }
+}
+`
+    },
+    {
+      file: `update-${kebab}.use-case.ts`,
+      content: `import { Service, Inject } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Update${pascal}DTO } from '../dtos/update-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Update${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.update(id, dto)
+  }
+}
+`
+    },
+    {
+      file: `delete-${kebab}.use-case.ts`,
+      content: `import { Service, Inject } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+
+@Service()
+export class Delete${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<void> {
+    await this.repo.delete(id)
+  }
+}
+`
+    }
+  ];
+  for (const uc of useCases) {
+    await write(`application/use-cases/${uc.file}`, uc.content);
+  }
+  await write(`domain/repositories/${kebab}.repository.ts`, `/**
+ * ${pascal} Repository Interface
+ *
+ * Domain layer \u2014 defines the contract for data access.
+ * The interface lives in the domain layer; implementations live in infrastructure.
+ * This inversion of dependencies keeps the domain pure and testable.
+ *
+ * To swap implementations (e.g. in-memory -> Drizzle -> Prisma),
+ * change the factory in the module's register() method.
+ */
+import type { ${pascal}ResponseDTO } from '../../application/dtos/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '../../application/dtos/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '../../application/dtos/update-${kebab}.dto'
+
+export interface I${pascal}Repository {
+  findById(id: string): Promise<${pascal}ResponseDTO | null>
+  findAll(): Promise<${pascal}ResponseDTO[]>
+  create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO>
+  update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO>
+  delete(id: string): Promise<void>
+}
+
+export const ${pascal.toUpperCase()}_REPOSITORY = Symbol('I${pascal}Repository')
+`);
+  await write(`domain/services/${kebab}-domain.service.ts`, `/**
+ * ${pascal} Domain Service
+ *
+ * Domain layer \u2014 contains business rules that don't belong to a single entity.
+ * Use this for cross-entity logic, validation rules, and domain invariants.
+ * Keep it free of HTTP/framework concerns.
+ */
+import { Service, Inject, HttpException } from '@forinda/kickjs-core'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../repositories/${kebab}.repository'
+
+@Service()
+export class ${pascal}DomainService {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async ensureExists(id: string): Promise<void> {
+    const entity = await this.repo.findById(id)
+    if (!entity) {
+      throw HttpException.notFound('${pascal} not found')
+    }
+  }
+}
+`);
+  if (repo === "inmemory") {
+    await write(`infrastructure/repositories/in-memory-${kebab}.repository.ts`, `/**
+ * In-Memory ${pascal} Repository
+ *
+ * Infrastructure layer \u2014 implements the repository interface using a Map.
+ * Useful for prototyping and testing. Replace with a database implementation
+ * (Drizzle, Prisma, etc.) for production use.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { randomUUID } from 'node:crypto'
+import { Repository, HttpException } from '@forinda/kickjs-core'
+import type { I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../../application/dtos/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '../../application/dtos/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '../../application/dtos/update-${kebab}.dto'
+
+@Repository()
+export class InMemory${pascal}Repository implements I${pascal}Repository {
+  private store = new Map<string, ${pascal}ResponseDTO>()
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.store.get(id) ?? null
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return Array.from(this.store.values())
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const now = new Date().toISOString()
+    const entity: ${pascal}ResponseDTO = {
+      id: randomUUID(),
+      name: dto.name,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.store.set(entity.id, entity)
+    return entity
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const existing = this.store.get(id)
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    const updated = { ...existing, ...dto, updatedAt: new Date().toISOString() }
+    this.store.set(id, updated)
+    return updated
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.store.has(id)) throw HttpException.notFound('${pascal} not found')
+    this.store.delete(id)
+  }
+}
+`);
+  }
+  if (!noEntity && !minimal) {
+    await write(`domain/entities/${kebab}.entity.ts`, `/**
+ * ${pascal} Entity
+ *
+ * Domain layer \u2014 the core business object.
+ * Uses a private constructor with static factory methods (create, reconstitute)
+ * to enforce invariants. Properties are accessed via getters to maintain encapsulation.
+ *
+ * Patterns used:
+ *   - Private constructor: prevents direct instantiation
+ *   - create(): factory for new entities (generates ID, sets timestamps)
+ *   - reconstitute(): factory for rebuilding from persistence (no side effects)
+ *   - changeName(): mutation method that enforces business rules
+ */
+import { ${pascal}Id } from '../value-objects/${kebab}-id.vo'
+
+interface ${pascal}Props {
+  id: ${pascal}Id
+  name: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export class ${pascal} {
+  private constructor(private props: ${pascal}Props) {}
+
+  static create(params: { name: string }): ${pascal} {
+    const now = new Date()
+    return new ${pascal}({
+      id: ${pascal}Id.create(),
+      name: params.name,
+      createdAt: now,
+      updatedAt: now,
+    })
+  }
+
+  static reconstitute(props: ${pascal}Props): ${pascal} {
+    return new ${pascal}(props)
+  }
+
+  get id(): ${pascal}Id {
+    return this.props.id
+  }
+  get name(): string {
+    return this.props.name
+  }
+  get createdAt(): Date {
+    return this.props.createdAt
+  }
+  get updatedAt(): Date {
+    return this.props.updatedAt
+  }
+
+  changeName(name: string): void {
+    if (!name || name.trim().length === 0) {
+      throw new Error('Name cannot be empty')
+    }
+    this.props.name = name.trim()
+    this.props.updatedAt = new Date()
+  }
+
+  toJSON() {
+    return {
+      id: this.props.id.toString(),
+      name: this.props.name,
+      createdAt: this.props.createdAt.toISOString(),
+      updatedAt: this.props.updatedAt.toISOString(),
+    }
+  }
+}
+`);
+    await write(`domain/value-objects/${kebab}-id.vo.ts`, `/**
+ * ${pascal} ID Value Object
+ *
+ * Domain layer \u2014 wraps a primitive ID with type safety and validation.
+ * Value objects are immutable and compared by value, not reference.
+ *
+ *   ${pascal}Id.create()    \u2014 generate a new UUID
+ *   ${pascal}Id.from(id)    \u2014 wrap an existing ID string (validates non-empty)
+ *   id.equals(other)  \u2014 compare two IDs by value
+ */
+import { randomUUID } from 'node:crypto'
+
+export class ${pascal}Id {
+  private constructor(private readonly value: string) {}
+
+  static create(): ${pascal}Id {
+    return new ${pascal}Id(randomUUID())
+  }
+
+  static from(id: string): ${pascal}Id {
+    if (!id || id.trim().length === 0) {
+      throw new Error('${pascal}Id cannot be empty')
+    }
+    return new ${pascal}Id(id)
+  }
+
+  toString(): string {
+    return this.value
+  }
+
+  equals(other: ${pascal}Id): boolean {
+    return this.value === other.value
+  }
+}
+`);
+  }
+  await autoRegisterModule(modulesDir, pascal, plural);
+  return files;
+}
+__name(generateModule, "generateModule");
+async function autoRegisterModule(modulesDir, pascal, plural) {
+  const indexPath = join2(modulesDir, "index.ts");
+  const exists = await fileExists(indexPath);
+  if (!exists) {
+    await writeFileSafe(indexPath, `import type { AppModuleClass } from '@forinda/kickjs-core'
+import { ${pascal}Module } from './${plural}'
+
+export const modules: AppModuleClass[] = [${pascal}Module]
+`);
+    return;
+  }
+  let content = await readFile2(indexPath, "utf-8");
+  const importLine = `import { ${pascal}Module } from './${plural}'`;
+  if (!content.includes(`${pascal}Module`)) {
+    const lastImportIdx = content.lastIndexOf("import ");
+    if (lastImportIdx !== -1) {
+      const lineEnd = content.indexOf("\n", lastImportIdx);
+      content = content.slice(0, lineEnd + 1) + importLine + "\n" + content.slice(lineEnd + 1);
+    } else {
+      content = importLine + "\n" + content;
+    }
+    content = content.replace(/(=\s*\[)([\s\S]*?)(])/, (_match, open, existing, close) => {
+      const trimmed = existing.trim();
+      if (!trimmed) {
+        return `${open}${pascal}Module${close}`;
+      }
+      const needsComma = trimmed.endsWith(",") ? "" : ",";
+      return `${open}${existing.trimEnd()}${needsComma} ${pascal}Module${close}`;
+    });
+  }
+  await writeFile2(indexPath, content, "utf-8");
+}
+__name(autoRegisterModule, "autoRegisterModule");
+
+// src/generators/adapter.ts
+import { join as join3 } from "path";
+async function generateAdapter(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const pascal = toPascalCase(name);
+  const files = [];
+  const filePath = join3(outDir, `${kebab}.adapter.ts`);
+  await writeFileSafe(filePath, `import type { Express } from 'express'
+import type { AppAdapter, AdapterMiddleware, Container } from '@forinda/kickjs-core'
+
+export interface ${pascal}AdapterOptions {
+  // Add your adapter configuration here
+}
+
+/**
+ * ${pascal} adapter.
+ *
+ * Hooks into the Application lifecycle to add middleware, routes,
+ * or external service connections.
+ *
+ * Usage:
+ *   bootstrap({
+ *     adapters: [new ${pascal}Adapter({ ... })],
+ *   })
+ */
+export class ${pascal}Adapter implements AppAdapter {
+  name = '${pascal}Adapter'
+
+  constructor(private options: ${pascal}AdapterOptions = {}) {}
+
+  /**
+   * Return middleware entries that the Application will mount.
+   * Use \`phase\` to control where in the pipeline they run:
+   *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'
+   */
+  middleware(): AdapterMiddleware[] {
+    return [
+      // Example: add a custom header to all responses
+      // {
+      //   phase: 'beforeGlobal',
+      //   handler: (_req: any, res: any, next: any) => {
+      //     res.setHeader('X-${pascal}', 'true')
+      //     next()
+      //   },
+      // },
+      // Example: scope middleware to a specific path
+      // {
+      //   phase: 'beforeRoutes',
+      //   path: '/api/v1/admin',
+      //   handler: myAdminMiddleware(),
+      // },
+    ]
+  }
+
+  /**
+   * Called before global middleware.
+   * Use this to mount routes that bypass the middleware stack
+   * (health checks, docs UI, static assets).
+   */
+  beforeMount(app: Express, container: Container): void {
+    // Example: mount a status route
+    // app.get('/${kebab}/status', (_req, res) => {
+    //   res.json({ status: 'ok' })
+    // })
+  }
+
+  /**
+   * Called after modules and routes are registered, before the server starts.
+   * Use this for late-stage DI registrations or config validation.
+   */
+  beforeStart(app: Express, container: Container): void {
+    // Example: register a service in the DI container
+    // container.registerInstance(MY_TOKEN, new MyService(this.options))
+  }
+
+  /**
+   * Called after the HTTP server is listening.
+   * Use this to attach to the raw http.Server (Socket.IO, gRPC, etc).
+   */
+  afterStart(server: any, container: Container): void {
+    // Example: attach Socket.IO
+    // const io = new Server(server)
+    // container.registerInstance(SOCKET_IO, io)
+  }
+
+  /**
+   * Called on graceful shutdown. Clean up connections.
+   */
+  async shutdown(): Promise<void> {
+    // Example: close a connection pool
+    // await this.pool.end()
+  }
+}
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateAdapter, "generateAdapter");
+
+// src/generators/middleware.ts
+import { join as join4 } from "path";
+async function generateMiddleware(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const camel = toCamelCase(name);
+  const files = [];
+  const filePath = join4(outDir, `${kebab}.middleware.ts`);
+  await writeFileSafe(filePath, `import type { Request, Response, NextFunction } from 'express'
+
+export interface ${toPascalCase(name)}Options {
+  // Add configuration options here
+}
+
+/**
+ * ${toPascalCase(name)} middleware.
+ *
+ * Usage in bootstrap:
+ *   middleware: [${camel}()]
+ *
+ * Usage with adapter:
+ *   middleware() { return [{ handler: ${camel}(), phase: 'afterGlobal' }] }
+ *
+ * Usage with @Middleware decorator:
+ *   @Middleware(${camel}())
+ */
+export function ${camel}(options: ${toPascalCase(name)}Options = {}) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Implement your middleware logic here
+    next()
+  }
+}
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateMiddleware, "generateMiddleware");
+
+// src/generators/guard.ts
+import { join as join5 } from "path";
+async function generateGuard(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const camel = toCamelCase(name);
+  const pascal = toPascalCase(name);
+  const files = [];
+  const filePath = join5(outDir, `${kebab}.guard.ts`);
+  await writeFileSafe(filePath, `import { Container, HttpException } from '@forinda/kickjs-core'
+import type { RequestContext } from '@forinda/kickjs-http'
+
+/**
+ * ${pascal} guard.
+ *
+ * Guards protect routes by checking conditions before the handler runs.
+ * Return early with an error response to block access.
+ *
+ * Usage:
+ *   @Middleware(${camel}Guard)
+ *   @Get('/protected')
+ *   async handler(ctx: RequestContext) { ... }
+ */
+export async function ${camel}Guard(ctx: RequestContext, next: () => void): Promise<void> {
+  // Example: check for an authorization header
+  const header = ctx.headers.authorization
+  if (!header?.startsWith('Bearer ')) {
+    ctx.res.status(401).json({ message: 'Missing or invalid authorization header' })
+    return
+  }
+
+  const token = header.slice(7)
+
+  try {
+    // Verify the token using a service from the DI container
+    // const container = Container.getInstance()
+    // const authService = container.resolve(AuthService)
+    // const payload = authService.verifyToken(token)
+    // ctx.set('auth', payload)
+
+    next()
+  } catch {
+    ctx.res.status(401).json({ message: 'Invalid or expired token' })
+  }
+}
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateGuard, "generateGuard");
+
+// src/generators/service.ts
+import { join as join6 } from "path";
+async function generateService(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const pascal = toPascalCase(name);
+  const files = [];
+  const filePath = join6(outDir, `${kebab}.service.ts`);
+  await writeFileSafe(filePath, `import { Service } from '@forinda/kickjs-core'
+
+@Service()
+export class ${pascal}Service {
+  // Inject dependencies via constructor
+  // constructor(
+  //   @Inject(MY_REPO) private readonly repo: IMyRepository,
+  // ) {}
+}
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateService, "generateService");
+
+// src/generators/controller.ts
+import { join as join7 } from "path";
+async function generateController(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const pascal = toPascalCase(name);
+  const files = [];
+  const filePath = join7(outDir, `${kebab}.controller.ts`);
+  await writeFileSafe(filePath, `import { Controller, Get, Post, Autowired } from '@forinda/kickjs-core'
+import type { RequestContext } from '@forinda/kickjs-http'
+
+@Controller()
+export class ${pascal}Controller {
+  // @Autowired() private myService!: MyService
+
+  @Get('/')
+  async list(ctx: RequestContext) {
+    ctx.json({ message: '${pascal} list' })
+  }
+
+  @Post('/')
+  async create(ctx: RequestContext) {
+    ctx.created({ message: '${pascal} created', data: ctx.body })
+  }
+}
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateController, "generateController");
+
+// src/generators/dto.ts
+import { join as join8 } from "path";
+async function generateDto(options) {
+  const { name, outDir } = options;
+  const kebab = toKebabCase(name);
+  const pascal = toPascalCase(name);
+  const camel = toCamelCase(name);
+  const files = [];
+  const filePath = join8(outDir, `${kebab}.dto.ts`);
+  await writeFileSafe(filePath, `import { z } from 'zod'
+
+export const ${camel}Schema = z.object({
+  // Define your schema fields here
+  name: z.string().min(1).max(200),
+})
+
+export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
+`);
+  files.push(filePath);
+  return files;
+}
+__name(generateDto, "generateDto");
+
+// src/commands/generate.ts
+function printGenerated(files) {
+  const cwd = process.cwd();
+  console.log(`
+  Generated ${files.length} file${files.length === 1 ? "" : "s"}:`);
+  for (const f of files) {
+    console.log(`    ${f.replace(cwd + "/", "")}`);
+  }
+  console.log();
+}
+__name(printGenerated, "printGenerated");
+function registerGenerateCommand(program) {
+  const gen = program.command("generate").alias("g").description("Generate code scaffolds");
+  gen.command("module <name>").description("Generate a full DDD module with all layers").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--repo <type>", "Repository implementation: inmemory | drizzle", "inmemory").option("--minimal", "Only generate index.ts and controller").option("--modules-dir <dir>", "Modules directory", "src/modules").action(async (name, opts) => {
+    const files = await generateModule({
+      name,
+      modulesDir: resolve2(opts.modulesDir),
+      noEntity: opts.entity === false,
+      noTests: opts.tests === false,
+      repo: opts.repo,
+      minimal: opts.minimal
+    });
+    printGenerated(files);
+  });
+  gen.command("adapter <name>").description("Generate an AppAdapter with lifecycle hooks and middleware support").option("-o, --out <dir>", "Output directory", "src/adapters").action(async (name, opts) => {
+    const files = await generateAdapter({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+  gen.command("middleware <name>").description("Generate an Express middleware function").option("-o, --out <dir>", "Output directory", "src/middleware").action(async (name, opts) => {
+    const files = await generateMiddleware({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+  gen.command("guard <name>").description("Generate a route guard (auth, roles, etc.)").option("-o, --out <dir>", "Output directory", "src/guards").action(async (name, opts) => {
+    const files = await generateGuard({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+  gen.command("service <name>").description("Generate a @Service() class").option("-o, --out <dir>", "Output directory", "src/services").action(async (name, opts) => {
+    const files = await generateService({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+  gen.command("controller <name>").description("Generate a @Controller() class with basic routes").option("-o, --out <dir>", "Output directory", "src/controllers").action(async (name, opts) => {
+    const files = await generateController({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+  gen.command("dto <name>").description("Generate a Zod DTO schema").option("-o, --out <dir>", "Output directory", "src/dtos").action(async (name, opts) => {
+    const files = await generateDto({
+      name,
+      outDir: resolve2(opts.out)
+    });
+    printGenerated(files);
+  });
+}
+__name(registerGenerateCommand, "registerGenerateCommand");
+
+// src/utils/shell.ts
+import { execSync } from "child_process";
+function runShellCommand(command, cwd) {
+  execSync(command, {
+    cwd,
+    stdio: "inherit"
+  });
+}
+__name(runShellCommand, "runShellCommand");
+
+// src/commands/run.ts
+function registerRunCommands(program) {
+  program.command("dev").description("Start development server with Vite HMR (zero-downtime reload)").option("-e, --entry <file>", "Entry file", "src/index.ts").option("-p, --port <port>", "Port number").action((opts) => {
+    const envVars = [];
+    if (opts.port) envVars.push(`PORT=${opts.port}`);
+    const cmd = `npx vite-node --watch ${opts.entry}`;
+    const fullCmd = envVars.length ? `${envVars.join(" ")} ${cmd}` : cmd;
+    console.log(`
+  KickJS dev server starting...`);
+    console.log(`  Entry:  ${opts.entry}`);
+    console.log(`  HMR:    enabled (vite-node)
+`);
+    try {
+      runShellCommand(fullCmd);
+    } catch {
+    }
+  });
+  program.command("build").description("Build for production via Vite").action(() => {
+    console.log("\n  Building for production...\n");
+    runShellCommand("npx vite build");
+  });
+  program.command("start").description("Start production server").option("-e, --entry <file>", "Entry file", "dist/index.js").option("-p, --port <port>", "Port number").action((opts) => {
+    const envVars = [
+      "NODE_ENV=production"
+    ];
+    if (opts.port) envVars.push(`PORT=${opts.port}`);
+    runShellCommand(`${envVars.join(" ")} node ${opts.entry}`);
+  });
+  program.command("dev:debug").description("Start dev server with Node.js inspector").option("-e, --entry <file>", "Entry file", "src/index.ts").option("-p, --port <port>", "Port number").action((opts) => {
+    const envVars = opts.port ? `PORT=${opts.port} ` : "";
+    try {
+      runShellCommand(`${envVars}npx vite-node --inspect --watch ${opts.entry}`);
+    } catch {
+    }
+  });
+}
+__name(registerRunCommands, "registerRunCommands");
+
+// src/commands/info.ts
+import { platform, release, arch } from "os";
+function registerInfoCommand(program) {
+  program.command("info").description("Print system and framework info").action(() => {
+    console.log(`
+  KickJS CLI
+
+  System:
+    OS:       ${platform()} ${release()} (${arch()})
+    Node:     ${process.version}
+
+  Packages:
+    @forinda/kickjs-core     workspace
+    @forinda/kickjs-http     workspace
+    @forinda/kickjs-config   workspace
+    @forinda/kickjs-cli      workspace
+`);
+  });
+}
+__name(registerInfoCommand, "registerInfoCommand");
+
+// src/commands/custom.ts
+function registerCustomCommands(program, config) {
+  if (!config?.commands?.length) return;
+  for (const cmd of config.commands) {
+    registerSingleCommand(program, cmd);
+  }
+}
+__name(registerCustomCommands, "registerCustomCommands");
+function registerSingleCommand(program, def) {
+  const command = program.command(def.name).description(def.description);
+  if (def.aliases) {
+    for (const alias of def.aliases) {
+      command.alias(alias);
+    }
+  }
+  command.allowUnknownOption(true);
+  command.argument("[args...]", "Additional arguments passed to the command");
+  command.action((args) => {
+    const extraArgs = args.join(" ");
+    const steps = Array.isArray(def.steps) ? def.steps : [
+      def.steps
+    ];
+    for (const step of steps) {
+      const finalCmd = extraArgs ? `${step} ${extraArgs}` : step;
+      console.log(`  $ ${finalCmd}`);
+      try {
+        runShellCommand(finalCmd);
+      } catch (err) {
+        console.error(`  Command failed: ${def.name}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  });
+}
+__name(registerSingleCommand, "registerSingleCommand");
+
+// src/config.ts
+import { readFile as readFile3, access as access2 } from "fs/promises";
+import { join as join9 } from "path";
+var CONFIG_FILES = [
+  "kick.config.ts",
+  "kick.config.js",
+  "kick.config.mjs",
+  "kick.config.json"
+];
+async function loadKickConfig(cwd) {
+  for (const filename of CONFIG_FILES) {
+    const filepath = join9(cwd, filename);
+    try {
+      await access2(filepath);
+    } catch {
+      continue;
+    }
+    if (filename.endsWith(".json")) {
+      const content = await readFile3(filepath, "utf-8");
+      return JSON.parse(content);
+    }
+    try {
+      const { pathToFileURL } = await import("url");
+      const mod = await import(pathToFileURL(filepath).href);
+      return mod.default ?? mod;
+    } catch (err) {
+      if (filename.endsWith(".ts")) {
+        console.warn(`Warning: Failed to load ${filename}. TypeScript config files require a runtime loader (e.g. tsx, ts-node) or use kick.config.js/.mjs instead.`);
+      }
+      continue;
+    }
+  }
+  return null;
+}
+__name(loadKickConfig, "loadKickConfig");
+
+// src/cli.ts
+async function main() {
+  const program = new Command();
+  program.name("kick").description("KickJS \u2014 A production-grade, decorator-driven Node.js framework").version("0.1.0");
+  const config = await loadKickConfig(process.cwd());
+  registerInitCommand(program);
+  registerGenerateCommand(program);
+  registerRunCommands(program);
+  registerInfoCommand(program);
+  registerCustomCommands(program, config);
+  program.showHelpAfterError();
+  await program.parseAsync(process.argv);
+}
+__name(main, "main");
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map