@forinda/kickjs-cli 3.1.3 → 4.0.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.1.3
+ * @forinda/kickjs-cli v4.0.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,13 +8,13 @@
  *
  * @license MIT
  */
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import * as clack from "@clack/prompts";
 import pc from "picocolors";
 import pkg from "pluralize";
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** Write a file, creating parent directories if needed. Skips writing in dry run mode. */
 async function writeFileSafe(filePath, content) {
@@ -1543,15 +1543,15 @@ function generateEntryFile(name, template, version, packages = []) {
 			const gqlAdapters = [];
 			if (packages.includes("devtools")) {
 				gqlImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				gqlAdapters.push(`    new DevToolsAdapter(),`);
+				gqlAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				gqlImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				gqlAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				gqlAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("swagger")) {
 				gqlImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				gqlAdapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				gqlAdapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -1584,15 +1584,15 @@ ${gqlAdapters.length ? gqlAdapters.join("\n") + "\n" : ""}    new GraphQLAdapter
 			const cqrsAdapters = [];
 			if (packages.includes("otel")) {
 				cqrsImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				cqrsAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				cqrsAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("devtools")) {
 				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				cqrsAdapters.push(`    new DevToolsAdapter(),`);
+				cqrsAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				cqrsAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("graphql")) {
 				cqrsImports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -1611,7 +1611,7 @@ ${cqrsImports.length ? cqrsImports.join("\n") + "\n" : ""}import { modules } fro
 
 // Export the app for the Vite plugin (dev mode)
 export const app = await bootstrap({
-  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
+  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
 })
 `;
 		}
@@ -1620,15 +1620,15 @@ export const app = await bootstrap({
 			const adapters = [];
 			if (packages.includes("swagger")) {
 				imports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				adapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				adapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			if (packages.includes("devtools")) {
 				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				adapters.push(`    new DevToolsAdapter(),`);
+				adapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				imports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				adapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				adapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("graphql")) {
 				imports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -1652,15 +1652,15 @@ export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters:
 			const restAdapters = [];
 			if (packages.includes("devtools")) {
 				restImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				restAdapters.push(`    new DevToolsAdapter(),`);
+				restAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				restAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("otel")) {
 				restImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				restAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				restAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -2980,6 +2980,8 @@ Copy \`.env.example\` to \`.env\` and configure:
 function generateClaude(name, template, pm) {
 	return `# CLAUDE.md — ${name} Development Guide
 
+> **Read \`AGENTS.md\` first.** It is the canonical, multi-agent reference for this project (Claude, Copilot, Codex, Gemini, etc.). This file contains the same project context distilled for Claude, plus Claude-specific notes. When the two disagree on anything substantive, treat \`AGENTS.md\` as authoritative and flag the discrepancy.
+
 ## Project Overview
 
 This is a **${{
@@ -3036,7 +3038,7 @@ generated \`KickRoutes\` namespace (refreshed on \`kick dev\` and \`kick typegen
 \`\`\`ts
 import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
 
-@Controller('/users')
+@Controller()
 export class UserController {
   @Get('/')
   async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
@@ -3071,9 +3073,12 @@ export class UserService {
 
 ### Modules
 
-Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`:
+Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`.
+
+> **Naming matters.** Module files **must** be named \`<name>.module.ts\` and live under \`src/modules/\`. The Vite plugin auto-discovers files matching \`*.module.[tj]sx?\` for HMR — a misnamed file (e.g., \`projects.ts\`) won't trigger a graceful module rebuild on save and will require a full server restart. The CLI generator (\`kick g module <name>\`) follows this convention automatically.
 
 \`\`\`ts
+// src/modules/users/users.module.ts   (named <feature>.module.ts)
 import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
 import { UserController } from './user.controller'
 
@@ -3124,6 +3129,8 @@ ctx.notFound()            // 404 Not Found
 ctx.badRequest(msg)       // 400 Bad Request
 \`\`\`
 
+> **Context decorators** — when a middleware's only job is to populate \`ctx.set/get\` for the handler to read, prefer \`defineContextDecorator()\` over \`@Middleware()\`. Typed via \`ContextMeta\`, supports \`dependsOn\` ordering, validates the pipeline at boot. Full pattern reference in \`AGENTS.md\` and at <https://forinda.github.io/kick-js/guide/context-decorators>.
+
 ## CLI Generators
 
 Generate code with the \`kick\` CLI:
@@ -3312,7 +3319,7 @@ Run tests:
 ## Decorators Reference
 
 ### Route Decorators
-- \`@Controller('/path')\` — define controller prefix
+- \`@Controller()\` — mark a class as an HTTP controller (path comes from \`routes().path\`)
 - \`@Get('/'), @Post('/'), @Put('/'), @Delete('/'), @Patch('/')\` — HTTP methods
 - \`@Middleware(fn)\` — attach middleware
 - \`@Public()\` — skip authentication (requires @forinda/kickjs-auth)
@@ -3387,6 +3394,8 @@ ${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| E
 
 ### Module Pattern (${template.toUpperCase()})
 
+> **Vite HMR auto-discovery contract:** module files **must** be named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and live under \`src/modules/\`. The Vite plugin scans for \`*.module.[tj]sx?\` to drive graceful HMR rebuilds; renaming a file to \`projects.ts\` (no \`.module\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\`kick g module <name>\`) follows the convention; manual files must too.
+
 Each module in \`src/modules/<name>/\` typically contains:
 
 ${template === "ddd" ? `\`\`\`
@@ -3457,7 +3466,7 @@ Then:
 If not using generators:
 
 - [ ] Create \`src/modules/<name>/<name>.controller.ts\`
-- [ ] Add \`@Controller('/path')\` decorator
+- [ ] Add \`@Controller()\` decorator
 - [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
 - [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
 - [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
@@ -3519,8 +3528,8 @@ import { AuthAdapter, JwtStrategy } from '@forinda/kickjs-auth'
 bootstrap({
   modules,
   adapters: [
-    new AuthAdapter({
-      strategies: [new JwtStrategy({ secret: process.env.JWT_SECRET! })],
+    AuthAdapter({
+      strategies: [JwtStrategy({ secret: process.env.JWT_SECRET! })],
     }),
   ],
 })
@@ -3550,7 +3559,7 @@ import { WsAdapter } from '@forinda/kickjs-ws'
 
 bootstrap({
   modules,
-  adapters: [new WsAdapter()],
+  adapters: [WsAdapter()],
 })
 \`\`\`
 
@@ -3654,7 +3663,7 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 ### HTTP Routes
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Controller('/path')\` | Define route prefix |
+| \`@Controller()\` | Define route prefix |
 | \`@Get('/'), @Post('/')\` | HTTP method handlers |
 | \`@Middleware(fn)\` | Attach middleware |
 | \`@Public()\` | Skip auth (requires auth adapter) |
@@ -3670,6 +3679,27 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 | \`@Inject('token')\` | Token-based injection |
 | \`@Value('VAR')\` | Inject env variable |
 
+### Context Decorators
+
+Typed, ordered way to populate \`ctx.set/get\` keys before the handler runs.
+Use this **instead of \`@Middleware()\`** when the middleware's only output
+is a value other code reads off \`ctx\`.
+
+| Concept | Where it lives |
+|---------|----------------|
+| \`defineContextDecorator({ key, deps, dependsOn, optional, onError, resolve })\` | \`@forinda/kickjs\` |
+| Method/class decorator | \`@LoadX\` on a controller method/class |
+| Module hook | \`AppModule.contributors?(): ContributorRegistration[]\` |
+| Adapter hook | \`AppAdapter.contributors?(): ContributorRegistration[]\` |
+| Global registration | \`bootstrap({ contributors: [LoadX.registration] })\` |
+| Type augmentation | \`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\` |
+
+Precedence high → low: **method > class > module > adapter > global**.
+Cycles and missing \`dependsOn\` keys throw at \`app.setup()\` (boot fails
+fast). The \`onError\` hook is async-permitted.
+
+Full guide: <https://forinda.github.io/kick-js/guide/context-decorators>.
+
 ${template === "graphql" ? `### GraphQL
 | Decorator | Purpose |
 |-----------|---------|
@@ -3692,9 +3722,11 @@ ${template === "graphql" ? `### GraphQL
 2. **DI not working** — Ensure \`reflect-metadata\` is imported in \`src/index.ts\`
 3. **Tests failing randomly** — Missing \`Container.reset()\` in \`beforeEach\`
 4. **Routes not found** — Check controller path and module registration
-5. **HMR not working** — Verify \`vite.config.ts\` has \`hmr: true\`
+5. **HMR not working** — Two checks: (a) \`vite.config.ts\` has \`hmr: true\`; (b) module file is named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and lives under \`src/modules/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed module file (e.g., \`projects.ts\`) silently degrades to a full restart on every save.
 6. **Decorators not working** — Check \`tsconfig.json\` has \`experimentalDecorators: true\`
 7. **\`config.get('YOUR_KEY')\` returns \`undefined\`** — \`src/index.ts\` is missing \`import './config'\`. That side-effect import registers the env schema with kickjs (\`loadEnv(envSchema)\` runs at module load). Without it, \`ConfigService\` falls back to the base schema (\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` only) and every user-defined key reads as \`undefined\`. \`@Value()\` may *appear* to work because of a raw \`process.env\` fallback, but Zod coercion and schema defaults are silently skipped — investigate \`src/index.ts\` and \`src/config/index.ts\` first.
+8. **Used \`@Middleware()\` to compute a value for \`ctx\`** — prefer \`defineContextDecorator()\` (see Context Decorators above). It's typed via \`ContextMeta\`, supports \`dependsOn\` for ordering, and validates the pipeline at boot. \`@Middleware()\` is for response short-circuiting, stream mutation, and pre-route-matching work.
+9. **Context contributor's \`dependsOn\` key not produced anywhere** — boot throws \`MissingContributorError\` naming the dependent and the route. Either remove the dep or register a contributor that produces the key (at any precedence level: method/class/module/adapter/global).
 
 ## CLI Commands Reference
 
@@ -3772,7 +3804,7 @@ async function initProject(options) {
 		}
 	}
 	try {
-		const { runTypegen } = await import("./typegen-0X9tc3wa.mjs");
+		const { runTypegen } = await import("./typegen-vI1eqGLK.mjs");
 		await runTypegen({
 			cwd: dir,
 			allowDuplicates: true,
@@ -3870,7 +3902,10 @@ async function loadKickConfig(cwd) {
 		try {
 			const { pathToFileURL } = await import("node:url");
 			const mod = await import(pathToFileURL(filepath).href);
-			return mod.default ?? mod;
+			const config = mod.default ?? mod;
+			const warnings = validateAssetMap(config, cwd);
+			for (const warning of warnings) console.warn(`  Warning: ${warning}`);
+			return config;
 		} 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;
@@ -3878,7 +3913,126 @@ async function loadKickConfig(cwd) {
 	}
 	return null;
 }
+/**
+* Validate `assetMap` entries on a loaded config. Returns a list of
+* human-readable warnings; the caller decides how to surface them
+* (typically `console.warn`). Never throws — `kick g` and other
+* unrelated commands should keep working even when the assetMap is
+* misconfigured.
+*
+* Checks:
+*
+* - Each entry's `src` is a non-empty string.
+* - The `src` directory exists on disk (otherwise the typegen + build
+*   steps will fail later with cryptic errors).
+* - `dest` doesn't escape the project root (defensive — a `dest:
+*   '../../etc'` typo could write files outside the workspace).
+* - The namespace key is a non-empty string and doesn't include a
+*   `/` (would conflict with the `<namespace>/<key>` manifest format).
+*/
+function validateAssetMap(config, cwd) {
+	const warnings = [];
+	if (!config?.assetMap) return warnings;
+	const root = resolve(cwd);
+	for (const [namespace, entry] of Object.entries(config.assetMap)) {
+		if (!namespace || namespace.includes("/")) {
+			warnings.push(`assetMap key '${namespace}' is invalid — must be a non-empty string without '/'`);
+			continue;
+		}
+		if (typeof entry?.src !== "string" || entry.src.length === 0) {
+			warnings.push(`assetMap.${namespace} is missing a non-empty 'src' field`);
+			continue;
+		}
+		if (!existsSync(resolve(cwd, entry.src))) warnings.push(`assetMap.${namespace}.src ('${entry.src}') does not exist — typegen + build will fail`);
+		if (entry.dest) {
+			if (escapesRoot(resolve(cwd, entry.dest), root)) warnings.push(`assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — refusing to copy`);
+		}
+	}
+	return warnings;
+}
+/**
+* Returns true when `path` (absolute) resolves outside of `root`
+* (also absolute). Uses `path.relative` for accuracy:
+*
+* - The result is empty when paths are identical (inside).
+* - It starts with `..` when the path traverses outside the root.
+* - It's absolute (Windows: cross-drive) when there's no relative
+*   path between them.
+*
+* Avoids the prefix-match pitfalls of `startsWith` (e.g. `/app`
+* matching `/app2/...`, or case-mismatches on macOS / Windows).
+*/
+function escapesRoot(path, root) {
+	const rel = relative(root, path);
+	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
+}
+//#endregion
+//#region src/generator-extension/define.ts
+/**
+* Identity factory — returns the spec verbatim. Exists for type
+* inference and forward-compatibility (future fields can be added with
+* defaults).
+*
+* @example
+* ```ts
+* import { defineGenerator } from '@forinda/kickjs-cli'
+*
+* export default [
+*   defineGenerator({
+*     name: 'command',
+*     description: 'Generate a CQRS command + handler',
+*     files: (ctx) => [
+*       {
+*         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,
+*         content: `// command for ${ctx.pascal}`,
+*       },
+*     ],
+*   }),
+* ]
+* ```
+*/
+function defineGenerator(spec) {
+	return spec;
+}
+//#endregion
+//#region src/generator-extension/context.ts
+/** Convert any string to snake_case (`UserPost` / `user-post` → `user_post`). */
+function toSnakeCase(name) {
+	return toKebabCase(name).replace(/-/g, "_");
+}
+/**
+* Build a {@link GeneratorContext} from the raw name + invocation
+* arguments. Centralises the case-transformation logic so every plugin
+* generator sees the same shape regardless of how the name was typed
+* on the command line (`Post` vs `post` vs `user_post`).
+*/
+function buildGeneratorContext(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const usePlural = input.pluralize ?? true;
+	const pascal = toPascalCase(input.name);
+	const camel = toCamelCase(input.name);
+	const kebab = toKebabCase(input.name);
+	const snake = toSnakeCase(input.name);
+	const ctx = {
+		name: input.name,
+		pascal,
+		camel,
+		kebab,
+		snake,
+		modulesDir: input.modulesDir ?? "src/modules",
+		cwd,
+		args: input.args ?? [],
+		flags: input.flags ?? {}
+	};
+	if (usePlural) {
+		const pluralKebab = pluralize(kebab);
+		ctx.pluralKebab = pluralKebab;
+		ctx.pluralPascal = toPascalCase(pluralKebab);
+		ctx.pluralCamel = toCamelCase(pluralKebab);
+	}
+	return ctx;
+}
 //#endregion
-export { defineConfig, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
+export { buildGeneratorContext, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
 
 //# sourceMappingURL=index.mjs.map