@forinda/kickjs-cli 2.2.3 → 2.2.5

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.2.3
+ * @forinda/kickjs-cli v2.2.5
  *
  * Copyright (c) Felix Orinda
  *
@@ -15,6 +15,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
 import { execSync, fork } from "node:child_process";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import pkg from "pluralize";
 import { arch, platform, release } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -742,18 +743,30 @@ export class UserService {
 
 ### Modules
 
-Register controllers and providers in modules:
+Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`:
 
 \`\`\`ts
-import { Module } from '@forinda/kickjs'
+import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
 import { UserController } from './user.controller'
-import { UserService } from './user.service'
 
-@Module({
-  controllers: [UserController],
-  providers: [UserService],
-})
-export class UserModule {}
+export class UserModule implements AppModule {
+  routes(): ModuleRoutes {
+    return {
+      path: '/users',
+      router: buildRoutes(UserController),
+      controller: UserController,
+    }
+  }
+}
+\`\`\`
+
+Register all modules in \`src/modules/index.ts\`:
+
+\`\`\`ts
+import type { AppModuleClass } from '@forinda/kickjs'
+import { UserModule } from './user/user.module'
+
+export const modules: AppModuleClass[] = [UserModule]
 \`\`\`
 
 ### RequestContext
@@ -864,6 +877,86 @@ Hot-reload of \`.env\` changes during dev is wired up automatically via
 \`envWatchPlugin()\` in \`vite.config.ts\` — edit \`.env\`, the dev server
 reloads, and the next \`config.get()\` re-parses with the new values.
 
+### Standalone Env Utilities (No DI Required)
+
+These functions work anywhere — scripts, CLI tools, plain files, outside \`@Service\`/\`@Controller\`:
+
+\`\`\`ts
+import { defineEnv, loadEnv, getEnv, reloadEnv, resetEnvCache, baseEnvSchema } from '@forinda/kickjs/config'
+import { z } from 'zod'
+
+// Define and parse schema
+const schema = defineEnv((base) =>
+  base.extend({ DATABASE_URL: z.string().url() })
+)
+const env = loadEnv(schema)      // Parse + validate process.env
+console.log(env.PORT)            // 3000 (coerced to number)
+console.log(env.DATABASE_URL)    // validated URL string
+
+// Get single value
+const port = getEnv('PORT')      // typed after kick typegen
+
+// Reload after .env changes (HMR calls this automatically)
+reloadEnv()
+
+// Reset cache in tests that swap schemas
+resetEnvCache()
+\`\`\`
+
+| Function | Purpose |
+|----------|---------|
+| \`defineEnv(fn)\` | Extend base schema with custom Zod keys |
+| \`loadEnv(schema?)\` | Parse \`process.env\`, validate, cache, return typed object |
+| \`getEnv(key, schema?)\` | Get single validated env value |
+| \`reloadEnv()\` | Re-read \`.env\` from disk, re-parse with same schema |
+| \`resetEnvCache()\` | Clear parsed cache AND registered schema (for tests) |
+| \`baseEnvSchema\` | Base Zod schema: \`PORT\`, \`NODE_ENV\`, \`LOG_LEVEL\` |
+
+## Standalone Utilities (No DI Required)
+
+These utilities work outside decorated classes:
+
+### Logger
+
+\`\`\`ts
+import { Logger, createLogger } from '@forinda/kickjs'
+
+const log = Logger.for('MyScript')    // Static factory
+log.info('Processing started')
+log.error('Something failed')
+
+const log2 = createLogger('Worker')   // Function form
+\`\`\`
+
+### Injection Tokens
+
+\`\`\`ts
+import { createToken } from '@forinda/kickjs'
+
+// Type-safe DI tokens for factory/interface binding
+const DB_URL = createToken<string>('config.database.url')
+const FEATURE_FLAGS = createToken<FeatureFlags>('app.features')
+\`\`\`
+
+### Reactivity
+
+\`\`\`ts
+import { ref, computed, watch, reactive } from '@forinda/kickjs'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+const stop = watch(() => count.value, (val) => console.log(val))
+count.value++  // logs 1
+\`\`\`
+
+### HTTP Errors
+
+\`\`\`ts
+import { HttpException, HttpStatus } from '@forinda/kickjs'
+
+throw new HttpException(HttpStatus.NOT_FOUND, 'User not found')
+\`\`\`
+
 ## Testing
 
 Tests live in \`src/**/*.test.ts\`:
@@ -898,7 +991,6 @@ Run tests:
 - \`@Roles('admin', 'user')\` — role-based access control
 
 ### DI Decorators
-- \`@Module({ controllers, providers, imports })\` — define module
 - \`@Service()\` — singleton service (DI-registered)
 - \`@Repository()\` — repository (semantic alias for @Service)
 - \`@Autowired()\` — property injection
@@ -976,7 +1068,7 @@ ${template === "ddd" ? `\`\`\`
 ├── <name>.repository.ts     # Data access (@Repository)
 ├── <name>.dto.ts            # Request/response schemas (Zod)
 ├── <name>.entity.ts         # Domain entity (optional)
-└── <name>.module.ts         # Module definition (@Module)
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : template === "cqrs" ? `\`\`\`
 <name>/
@@ -990,7 +1082,7 @@ ${template === "ddd" ? `\`\`\`
 │   └── <name>-created.event.ts
 ├── <name>.controller.ts     # HTTP routes
 ├── <name>.repository.ts     # Data access
-└── <name>.module.ts         # Module definition
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : template === "graphql" ? `\`\`\`
 resolvers/
@@ -1003,7 +1095,7 @@ resolvers/
 ├── <name>.controller.ts     # HTTP routes (@Controller)
 ├── <name>.service.ts        # Business logic (@Service)
 ├── <name>.dto.ts            # Request/response schemas (Zod)
-└── <name>.module.ts         # Module definition (@Module)
+└── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
 ` : `\`\`\`
 src/
@@ -1039,8 +1131,8 @@ If not using generators:
 - [ ] Create \`src/modules/<name>/<name>.controller.ts\`
 - [ ] Add \`@Controller('/path')\` decorator
 - [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
-- [ ] Create module file with \`@Module({ controllers: [NameController] })\`
-- [ ] Register module in \`src/modules/index.ts\`
+- [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
+- [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
 - [ ] Test with \`kick dev\`
 
 ### Manual Service
@@ -1048,7 +1140,7 @@ If not using generators:
 - [ ] Create \`src/modules/<name>/<name>.service.ts\`
 - [ ] Add \`@Service()\` decorator
 - [ ] Inject dependencies with \`@Autowired()\`
-- [ ] Register in module \`providers\` array
+- [ ] Inject via \`@Autowired()\` where needed
 - [ ] Write unit tests
 
 ### New Middleware
@@ -1073,9 +1165,12 @@ Use \`kick add\` to install KickJS packages with correct peer dependencies:
 ### Generate CRUD Module
 
 \`\`\`bash
-kick g scaffold user name:string email:string age:number
+kick g scaffold user name:string email:string:optional age:number
 \`\`\`
 
+Append \`:optional\` for optional fields (shell-safe, no quoting needed).
+Quoted \`?\` syntax also works: \`"email:string?"\` or \`"email?:string"\`.
+
 This creates a full CRUD module with:
 - Controller with GET, POST, PUT, DELETE routes
 - Service with business logic
@@ -1191,7 +1286,17 @@ private config!: ConfigService
 const port = this.config.get('PORT')  // typed: number
 \`\`\`
 
-3. **Direct \`process.env\`** — avoid in app code; bypasses Zod
+3. **Standalone utilities** (no DI — works in scripts, CLI, plain files):
+\`\`\`ts
+import { loadEnv, getEnv, reloadEnv, resetEnvCache } from '@forinda/kickjs/config'
+
+const env = loadEnv(schema)         // Parse + validate all vars
+const port = getEnv('PORT')         // Single value lookup
+reloadEnv()                         // Re-read .env from disk
+resetEnvCache()                     // Full reset (for tests)
+\`\`\`
+
+4. **Direct \`process.env\`** — avoid in app code; bypasses Zod
    coercion and the typed \`KickEnv\` registry.
 
 > **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
@@ -1200,6 +1305,22 @@ const port = this.config.get('PORT')  // typed: number
 > \`@Value()\` only works because of its raw \`process.env\` fallback —
 > Zod coercion + schema defaults are silently skipped.
 
+## Standalone Utilities (No DI Required)
+
+These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller\`:
+
+| Utility | Import | Example |
+|---------|--------|---------|
+| \`Logger.for(name)\` | \`@forinda/kickjs\` | \`const log = Logger.for('MyScript')\` |
+| \`createLogger(name)\` | \`@forinda/kickjs\` | \`const log = createLogger('Worker')\` |
+| \`createToken<T>(name)\` | \`@forinda/kickjs\` | \`const TOKEN = createToken<string>('db.url')\` |
+| \`ref(value)\` | \`@forinda/kickjs\` | \`const count = ref(0)\` |
+| \`computed(fn)\` | \`@forinda/kickjs\` | \`const doubled = computed(() => count.value * 2)\` |
+| \`watch(source, cb)\` | \`@forinda/kickjs\` | \`watch(() => count.value, (v) => log(v))\` |
+| \`reactive(obj)\` | \`@forinda/kickjs\` | \`const state = reactive({ count: 0 })\` |
+| \`HttpException\` | \`@forinda/kickjs\` | \`throw new HttpException(404, 'Not found')\` |
+| \`HttpStatus\` | \`@forinda/kickjs\` | \`HttpStatus.NOT_FOUND // 404\` |
+
 ## Key Decorators
 
 ### HTTP Routes
@@ -1214,7 +1335,7 @@ const port = this.config.get('PORT')  // typed: number
 ### Dependency Injection
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Module({})\` | Define feature module |
+| \`AppModule\` interface | Define feature module (implements \`routes()\`) |
 | \`@Service()\` | Register singleton service |
 | \`@Repository()\` | Register repository |
 | \`@Autowired()\` | Property injection |
@@ -1310,6 +1431,26 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
 	await writeFileSafe(join(dir, "CLAUDE.md"), generateClaude(name, template, packageManager));
 	await writeFileSafe(join(dir, "AGENTS.md"), generateAgents(name, template, packageManager));
+	if (options.installDeps) {
+		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
+		try {
+			execSync(`${packageManager} install`, {
+				cwd: dir,
+				stdio: "inherit"
+			});
+			console.log("\n  Dependencies installed successfully!");
+		} catch {
+			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
+		}
+	}
+	try {
+		const { runTypegen } = await Promise.resolve().then(() => typegen_exports);
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
 	if (options.initGit) try {
 		execSync("git init", {
 			cwd: dir,
@@ -1331,26 +1472,6 @@ async function initProject(options) {
 	} catch {
 		log("Warning: git init failed (git may not be installed)");
 	}
-	if (options.installDeps) {
-		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
-		try {
-			execSync(`${packageManager} install`, {
-				cwd: dir,
-				stdio: "inherit"
-			});
-			console.log("\n  Dependencies installed successfully!");
-		} catch {
-			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
-		}
-	}
-	try {
-		const { runTypegen } = await Promise.resolve().then(() => typegen_exports);
-		await runTypegen({
-			cwd: dir,
-			allowDuplicates: true,
-			silent: true
-		});
-	} catch {}
 	console.log("\n  Project scaffolded successfully!");
 	console.log();
 	const needsCd = dir !== process.cwd();
@@ -1522,26 +1643,18 @@ function toKebabCase(name) {
 }
 /**
 * Pluralize a kebab-case name for directory/file names.
-* If already plural (ends in 's'), returns as-is.
+* Uses the `pluralize` npm package for correct English pluralization
+* including irregulars (person → people, status → statuses, child → children).
 */
 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";
+	return pkg.plural(name);
 }
 /**
 * Pluralize a PascalCase name for class identifiers.
-* If already plural (ends in 's'), returns as-is.
 * Used for `List${pluralPascal}UseCase` to avoid `ListUserssUseCase`.
 */
 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";
+	return pkg.plural(name);
 }
 //#endregion
 //#region src/generators/templates/module-index.ts
@@ -3585,13 +3698,14 @@ const CQRS_FOLDER_MAP = {
 *   3. Standalone default directory
 */
 function resolveOutDir(options) {
-	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd" } = options;
+	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd", shouldPluralize = true } = options;
 	if (outDir) return resolve(outDir);
 	if (moduleName) {
 		const folderMap = pattern === "ddd" ? DDD_FOLDER_MAP : pattern === "cqrs" ? CQRS_FOLDER_MAP : FLAT_FOLDER_MAP;
-		const plural = pluralize(toKebabCase(moduleName));
+		const kebab = toKebabCase(moduleName);
+		const folder = shouldPluralize ? pluralize(kebab) : kebab;
 		const subfolder = folderMap[type] ?? "";
-		const base = join(modulesDir, plural);
+		const base = join(modulesDir, folder);
 		return resolve(subfolder ? join(base, subfolder) : base);
 	}
 	return resolve(defaultDir);
@@ -3606,7 +3720,8 @@ async function generateMiddleware(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/middleware",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const camel = toCamelCase(name);
@@ -3650,7 +3765,8 @@ async function generateGuard(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/guards",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const camel = toCamelCase(name);
@@ -3707,7 +3823,8 @@ async function generateService(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/services",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3736,7 +3853,8 @@ async function generateController(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/controllers",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3777,7 +3895,8 @@ async function generateDto(options) {
 		moduleName,
 		modulesDir,
 		defaultDir: "src/dtos",
-		pattern
+		pattern,
+		shouldPluralize: options.pluralize ?? true
 	});
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
@@ -3996,7 +4115,10 @@ export class ${pascal}Job {
 *   json      → z.any()
 *   enum:a,b  → z.enum(['a','b'])
 *
-* Append ? for optional: title:string  body:text?  published:boolean?
+* Mark optional fields — three equivalent syntaxes:
+*   body:text:optional  ← recommended (shell-safe, no quoting needed)
+*   body?:text          ← needs quoting in bash/zsh ("body?:text")
+*   body:text?          ← needs quoting in bash/zsh ("body:text?")
 */
 const TYPE_MAP = {
 	string: {
@@ -4048,11 +4170,23 @@ function parseFields(raw) {
 	return raw.map((f) => {
 		const colonIdx = f.indexOf(":");
 		if (colonIdx === -1) throw new Error(`Invalid field: "${f}". Use format: name:type (e.g. title:string)`);
-		const namePart = f.slice(0, colonIdx);
-		const typePart = f.slice(colonIdx + 1);
+		let namePart = f.slice(0, colonIdx);
+		let typePart = f.slice(colonIdx + 1);
 		if (!namePart || !typePart) throw new Error(`Invalid field: "${f}". Use format: name:type (e.g. title:string)`);
-		const optional = typePart.endsWith("?");
-		const cleanType = optional ? typePart.slice(0, -1) : typePart;
+		let optional = false;
+		if (typePart.endsWith(":optional")) {
+			typePart = typePart.slice(0, -9);
+			optional = true;
+		}
+		if (namePart.endsWith("?")) {
+			namePart = namePart.slice(0, -1);
+			optional = true;
+		}
+		if (typePart.endsWith("?")) {
+			typePart = typePart.slice(0, -1);
+			optional = true;
+		}
+		const cleanType = typePart;
 		if (cleanType.startsWith("enum:")) {
 			const values = cleanType.slice(5).split(",");
 			return {
@@ -4517,14 +4651,16 @@ async function autoRegisterModule(modulesDir, pascal, plural) {
 //#region src/generators/test.ts
 async function generateTest(options) {
 	const { name, moduleName, modulesDir } = options;
+	const shouldPluralize = options.pluralize ?? true;
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
 	const files = [];
 	let outDir;
 	if (options.outDir) outDir = resolve(options.outDir);
 	else if (moduleName) {
-		const modPlural = pluralize(toKebabCase(moduleName));
-		outDir = resolve(join(modulesDir ?? "src/modules", modPlural, "__tests__"));
+		const modKebab = toKebabCase(moduleName);
+		const modFolder = shouldPluralize ? pluralize(modKebab) : modKebab;
+		outDir = resolve(join(modulesDir ?? "src/modules", modFolder, "__tests__"));
 	} else outDir = resolve("src/__tests__");
 	const filePath = join(outDir, `${kebab}.test.ts`);
 	await writeFileSafe(filePath, `import { describe, it, expect, beforeEach } from 'vitest'
@@ -5703,52 +5839,60 @@ function registerGenerateCommand(program) {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateMiddleware({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("guard <name>").description("Generate a route guard (auth, roles, etc.)\n  Use -m to scope it to a module: kick g guard admin -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateGuard({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("service <name>").description("Generate a @Service() class\n  Use -m to scope it to a module: kick g service payment -m orders").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateService({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("controller <name>").description("Generate a @Controller() class with basic routes\n  Use -m to scope it to a module: kick g controller auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateController({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 		await runPostTypegen(dryRun);
 	});
@@ -5756,24 +5900,28 @@ function registerGenerateCommand(program) {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const config = await loadKickConfig(process.cwd());
-		const modulesDir = resolveModuleConfig(config).dir ?? "src/modules";
+		const mc = resolveModuleConfig(config);
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateDto({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
 			modulesDir,
-			pattern: config?.pattern
+			pattern: config?.pattern,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("test <name>").description("Generate a Vitest test scaffold\n  Use -m to scope it to a module: kick g test user-service -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module's __tests__/ folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
-		const modulesDir = resolveModuleConfig(await loadKickConfig(process.cwd())).dir ?? "src/modules";
+		const mc = resolveModuleConfig(await loadKickConfig(process.cwd()));
+		const modulesDir = mc.dir ?? "src/modules";
 		printGenerated(await generateTest({
 			name,
 			outDir: opts.out,
 			moduleName: opts.module,
-			modulesDir
+			modulesDir,
+			pluralize: mc.pluralize ?? true
 		}), dryRun);
 	});
 	gen.command("resolver <name>").description("Generate a GraphQL @Resolver class with @Query and @Mutation methods").option("-o, --out <dir>", "Output directory", "src/resolvers").action(async (name, opts, cmd) => {
@@ -5793,11 +5941,11 @@ function registerGenerateCommand(program) {
 			queue: opts.queue
 		}), dryRun);
 	});
-	gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text published:boolean?\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Append ? for optional fields: description:text?").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts, cmd) => {
+	gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text:optional published:boolean:optional\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Optional: append :optional (shell-safe):  description:text:optional\n            or use ? with quoting:           \"description:text?\" or \"description?:text\"").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		if (rawFields.length === 0) {
-			console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text published:boolean\n");
+			console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text:optional published:boolean:optional\n  Optional: append :optional (shell-safe, no quoting needed)\n");
 			process.exit(1);
 		}
 		const mc = resolveModuleConfig(await loadKickConfig(process.cwd()));
@@ -6613,10 +6761,10 @@ function registerTypegenCommand(program) {
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const pkg$1 = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 async function main() {
 	const program = new Command();
-	program.name("kick").description("KickJS — A production-grade, decorator-driven Node.js framework").version(pkg.version);
+	program.name("kick").description("KickJS — A production-grade, decorator-driven Node.js framework").version(pkg$1.version);
 	const config = await loadKickConfig(process.cwd());
 	registerInitCommand(program);
 	registerGenerateCommand(program);

package/dist/index.d.mts

@@ -228,6 +228,7 @@ interface GenerateMiddlewareOptions {
   moduleName?: string;
   modulesDir?: string;
   pattern?: ProjectPattern;
+  pluralize?: boolean;
 }
 declare function generateMiddleware(options: GenerateMiddlewareOptions): Promise<string[]>;
 //#endregion
@@ -238,6 +239,7 @@ interface GenerateGuardOptions {
   moduleName?: string;
   modulesDir?: string;
   pattern?: ProjectPattern;
+  pluralize?: boolean;
 }
 declare function generateGuard(options: GenerateGuardOptions): Promise<string[]>;
 //#endregion
@@ -248,6 +250,7 @@ interface GenerateServiceOptions {
   moduleName?: string;
   modulesDir?: string;
   pattern?: ProjectPattern;
+  pluralize?: boolean;
 }
 declare function generateService(options: GenerateServiceOptions): Promise<string[]>;
 //#endregion
@@ -258,6 +261,7 @@ interface GenerateControllerOptions {
   moduleName?: string;
   modulesDir?: string;
   pattern?: ProjectPattern;
+  pluralize?: boolean;
 }
 declare function generateController(options: GenerateControllerOptions): Promise<string[]>;
 //#endregion
@@ -268,6 +272,7 @@ interface GenerateDtoOptions {
   moduleName?: string;
   modulesDir?: string;
   pattern?: ProjectPattern;
+  pluralize?: boolean;
 }
 declare function generateDto(options: GenerateDtoOptions): Promise<string[]>;
 //#endregion
@@ -294,7 +299,8 @@ declare function toCamelCase(name: string): string;
 declare function toKebabCase(name: string): string;
 /**
  * Pluralize a kebab-case name for directory/file names.
- * If already plural (ends in 's'), returns as-is.
+ * Uses the `pluralize` npm package for correct English pluralization
+ * including irregulars (person → people, status → statuses, child → children).
  */
 declare function pluralize(name: string): string;
 //#endregion

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/utils/naming.ts"],"mappings":";;;UAIiB,qBAAA;EAAqB;EAEpC,IAAA;EAFoC;EAIpC,WAAA;EAAA;;;;;AAeF;;;EANE,KAAA;EAMwB;EAJxB,OAAA;AAAA;;KAIU,cAAA;;KAGA,iBAAA;;UAKK,cAAA;EACf,IAAA;AAAA;;KAIU,cAAA,GAAiB,iBAAA,GAAkB,cAAA;;;AAS/C;;;;;KAAY,eAAA;;UAGK,aAAA;EAuBkB;;;;EAlBjC,MAAA;EA4BA;;;AAIF;EA3BE,MAAA;;;;;;;;;;;AAiEF;;EApDE,eAAA,GAAkB,eAAA;EA6DR;;;;;;;;;EAnDV,OAAA;AAAA;;UAIe,YAAA;EAiEf;EA/DA,GAAA;EAiEA;;;;;;;;;;;;;EAnDA,IAAA,GAAO,cAAA;EAuFL;EArFF,SAAA;EAqFQ;AAKV;;;;EApFE,SAAA;EAoF2B;;;;AA6B7B;;;;;EAvGE,gBAAA;AAAA;;UAIe,UAAA;;;;AC7GjB;;;;;EDsHE,OAAA,GAAU,cAAA;ECrHQ;;;;AAOnB;;;;;;;ED0HC,OAAA,GAAU,YAAA;ECnHV;EDuHA,UAAA;ECtHA;EDwHA,WAAA,GAAc,cAAA;ECtHd;EDwHA,SAAA;ECvHA;EDyHA,SAAA;ECrHA;;;AAwBF;;;;;;;;;;ED2GE,QAAA,GAAW,KAAA;IAAiB,GAAA;IAAa,IAAA;EAAA;;;;AE/J3C;;;;;;;;EF2KE,OAAA,GAAU,aAAA;;EAEV,QAAA,GAAW,qBAAA;;EAEX,KAAA;IACE,UAAA;IACA,MAAA;IACA,aAAA;IACA,MAAA;EAAA;AAAA;;iBAKY,YAAA,CAAa,MAAA,EAAQ,UAAA,GAAa,UAAA;;iBA6B5B,cAAA,CAAe,GAAA,WAAc,OAAA,CAAQ,UAAA;;;KChN/C,eAAA;AAAA,KACA,QAAA,GAAW,eAAA;AAAA,UASb,qBAAA;EACR,IAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;EACA,IAAA,GAAO,QAAA;EACP,OAAA;EACA,KAAA;EACA,OAAA,GAAU,cAAA;EACV,MAAA;EDVwB;ECYxB,SAAA;EDTyB;ECWzB,gBAAA;AAAA;;ADNF;;;;;AAKA;;;;iBCyBsB,cAAA,CAAe,OAAA,EAAS,qBAAA,GAAwB,OAAA;;;UCzD5D,sBAAA;EACR,IAAA;EACA,MAAA;AAAA;AAAA,iBAGoB,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCH9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,oBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,OAAA;;;UCR1D,sBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCR9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,kBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;KCkB3D,eAAA;AAAA,UAEK,kBAAA;EACR,IAAA;EACA,SAAA;EACA,cAAA;EACA,OAAA;EACA,WAAA;EACA,QAAA,GAAW,eAAA;EACX,WAAA;AAAA;;iBAIoB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;;iBC5ChD,YAAA,CAAa,IAAA;;iBAOb,WAAA,CAAY,IAAA;;iBAMZ,WAAA,CAAY,IAAA;;;;;iBAWZ,SAAA,CAAU,IAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/utils/naming.ts"],"mappings":"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"}