@forinda/kickjs-cli 3.1.3 → 3.2.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.1.3
+ * @forinda/kickjs-cli v3.2.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -711,6 +711,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 **${{
@@ -802,9 +804,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'
 
@@ -855,6 +860,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:
@@ -1118,6 +1125,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" ? `\`\`\`
@@ -1401,6 +1410,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 |
 |-----------|---------|
@@ -1423,9 +1453,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
 

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.1.3
+ * @forinda/kickjs-cli v3.2.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -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 **${{
@@ -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:
@@ -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" ? `\`\`\`
@@ -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-C30frihW.mjs");
 		await runTypegen({
 			cwd: dir,
 			allowDuplicates: true,