@forinda/kickjs-cli 4.1.0 → 5.0.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v4.1.0
+ * @forinda/kickjs-cli v5.0.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -108,15 +108,9 @@ async function fileExists(filePath) {
 const PACKAGE_DEPS = {
 	auth: "@forinda/kickjs-auth",
 	swagger: "@forinda/kickjs-swagger",
-	otel: "@forinda/kickjs-otel",
 	ws: "@forinda/kickjs-ws",
 	queue: "@forinda/kickjs-queue",
-	cron: "@forinda/kickjs-cron",
-	mailer: "@forinda/kickjs-mailer",
-	graphql: "@forinda/kickjs-graphql",
-	devtools: "@forinda/kickjs-devtools",
-	notifications: "@forinda/kickjs-notifications",
-	"multi-tenant": "@forinda/kickjs-multi-tenant"
+	devtools: "@forinda/kickjs-devtools"
 };
 /** Generate package.json with template-aware dependencies */
 function generatePackageJson(name, template, kickjsVersion, packages = []) {
@@ -129,15 +123,10 @@ function generatePackageJson(name, template, kickjsVersion, packages = []) {
 		pino: "^10.3.1",
 		"pino-pretty": "^13.1.3"
 	};
-	if (template === "graphql") {
-		baseDeps["@forinda/kickjs-graphql"] = kickjsVersion;
-		baseDeps["graphql"] = "^16.11.0";
-	}
 	for (const pkg of packages) {
 		const dep = PACKAGE_DEPS[pkg];
 		if (dep && !baseDeps[dep]) baseDeps[dep] = kickjsVersion;
 	}
-	if (packages.includes("graphql") && !baseDeps["graphql"]) baseDeps["graphql"] = "^16.11.0";
 	return JSON.stringify({
 		name,
 		version: kickjsVersion.replace("^", ""),
@@ -342,54 +331,9 @@ export default defineConfig({
 */
 function generateEntryFile(name, template, version, packages = []) {
 	switch (template) {
-		case "graphql": {
-			const gqlImports = [];
-			const gqlAdapters = [];
-			if (packages.includes("devtools")) {
-				gqlImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				gqlAdapters.push(`    DevToolsAdapter(),`);
-			}
-			if (packages.includes("otel")) {
-				gqlImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				gqlAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
-			}
-			if (packages.includes("swagger")) {
-				gqlImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				gqlAdapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
-			}
-			return `import 'reflect-metadata'
-// Side-effect import — registers the extended env schema with kickjs
-// **before** any controller / service / @Value gets resolved. Without
-// this line ConfigService.get('YOUR_KEY') returns undefined because the
-// cached schema would still be the base shape. See guide/configuration.
-import './config'
-import { bootstrap } from '@forinda/kickjs'
-import { GraphQLAdapter } from '@forinda/kickjs-graphql'
-${gqlImports.length ? gqlImports.join("\n") + "\n" : ""}import { modules } from './modules'
-
-// Import your resolvers here
-// import { UserResolver } from './resolvers/user.resolver'
-
-// Export the app for the Vite plugin (dev mode)
-export const app = await bootstrap({
-  modules,
-  adapters: [
-${gqlAdapters.length ? gqlAdapters.join("\n") + "\n" : ""}    new GraphQLAdapter({
-      resolvers: [/* UserResolver */],
-      // Add custom type definitions here:
-      // typeDefs: userTypeDefs,
-    }),
-  ],
-})
-`;
-		}
 		case "cqrs": {
 			const cqrsImports = [];
 			const cqrsAdapters = [];
-			if (packages.includes("otel")) {
-				cqrsImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				cqrsAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
-			}
 			if (packages.includes("devtools")) {
 				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
 				cqrsAdapters.push(`    DevToolsAdapter(),`);
@@ -398,10 +342,6 @@ ${gqlAdapters.length ? gqlAdapters.join("\n") + "\n" : ""}    new GraphQLAdapter
 				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
 				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
-			if (packages.includes("graphql")) {
-				cqrsImports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
-				cqrsAdapters.push(`    new GraphQLAdapter({ resolvers: [] }),`);
-			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
 // **before** any controller / service / @Value gets resolved. Without
@@ -430,14 +370,6 @@ export const app = await bootstrap({
 				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
 				adapters.push(`    DevToolsAdapter(),`);
 			}
-			if (packages.includes("otel")) {
-				imports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				adapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
-			}
-			if (packages.includes("graphql")) {
-				imports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
-				adapters.push(`    new GraphQLAdapter({ resolvers: [] }),`);
-			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
 // **before** any controller / service / @Value gets resolved. Without
@@ -462,10 +394,6 @@ export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters:
 				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
 				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
-			if (packages.includes("otel")) {
-				restImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				restAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
-			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
 // **before** any controller / service / @Value gets resolved. Without
@@ -685,15 +613,13 @@ export default defineConfig({
 function generateReadme(name, template, pm) {
 	const templateLabels = {
 		rest: "REST API",
-		graphql: "GraphQL API",
 		ddd: "Domain-Driven Design",
 		cqrs: "CQRS + Event-Driven",
 		minimal: "Minimal"
 	};
 	const packages = ["@forinda/kickjs", "@forinda/kickjs-vite"];
 	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
-	if (template === "graphql") packages.push("@forinda/kickjs-graphql");
-	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws", "@forinda/kickjs-otel");
+	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws");
 	return `# ${name}
 
 A **${templateLabels[template] ?? "REST API"}** built with [KickJS](https://forinda.github.io/kick-js/) — a decorator-driven Node.js framework on Express 5 and TypeScript.
@@ -738,11 +664,11 @@ kick add auth          # Authentication (JWT, API key, OAuth)
 kick add swagger       # OpenAPI documentation
 kick add ws            # WebSocket support
 kick add queue         # Background job processing
-kick add mailer        # Email sending
-kick add cron          # Scheduled tasks
 kick add --list        # Show all available packages
 \`\`\`
 
+For email, scheduled tasks, multi-tenancy, OpenTelemetry, GraphQL, and notifications use the BYO recipes in the [KickJS guides](https://forinda.github.io/kick-js/guide/) — they wire the upstream library through \`defineAdapter()\` / \`definePlugin()\` directly, so you keep control of the integration.
+
 ## Environment Variables
 
 Copy \`.env.example\` to \`.env\` and configure:
@@ -917,8 +843,8 @@ mistakes:
     property assignment (\`ctx.tenant = …\`) sticks to the contributor
     instance only — the handler instance never sees it.
   - **Read across instances via \`ctx.set\` / \`ctx.get\`** (or
-    \`requestStore.getStore()?.values.get('key')\` from a service that
-    has no \`ctx\` reference). \`ctx.req\` works because the underlying
+    \`getRequestValue(key)\` from a service that has no \`ctx\` reference
+    — typed via \`MetaValue<K>\`). \`ctx.req\` works because the underlying
     Express request is shared; bespoke property assignments don't.
 
 - **Test isolation** — default to \`Container.create()\` for fresh DI state.
@@ -986,7 +912,7 @@ package additions, env access patterns, troubleshooting) is detailed below.
 | Module registry | \`src/modules/index.ts\` |
 | Feature modules | \`src/modules/<module-name>/\` |
 | **Module entry file** | \`src/modules/<name>/<name>.module.ts\` (filename suffix is required — see Vite HMR contract below) |
-${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Env values | \`.env\` |
+| Env values | \`.env\` |
 | Env schema (Zod) | \`src/config/index.ts\` |
 | TypeScript config | \`tsconfig.json\` |
 | Vite config (HMR) | \`vite.config.ts\` |
@@ -1023,12 +949,6 @@ ${template === "ddd" ? `\`\`\`
 ├── <name>.repository.ts     # Data access
 └── <name>.module.ts         # Module definition (implements AppModule)
 \`\`\`
-` : template === "graphql" ? `\`\`\`
-resolvers/
-├── <name>.resolver.ts       # @Resolver, @Query, @Mutation
-├── <name>.types.ts          # GraphQL type definitions
-└── <name>.service.ts        # Business logic
-\`\`\`
 ` : template === "rest" ? `\`\`\`
 <name>/
 ├── <name>.controller.ts     # HTTP routes (@Controller)
@@ -1301,15 +1221,7 @@ fast). The \`onError\` hook is async-permitted.
 
 Full guide: <https://forinda.github.io/kick-js/guide/context-decorators>.
 
-${template === "graphql" ? `### GraphQL
-| Decorator | Purpose |
-|-----------|---------|
-| \`@Resolver()\` | GraphQL resolver class |
-| \`@Query()\` | Query handler |
-| \`@Mutation()\` | Mutation handler |
-| \`@Arg('name')\` | Resolver argument |
-
-` : ""}${template === "cqrs" ? `### Background Jobs
+${template === "cqrs" ? `### Background Jobs
 | Decorator | Purpose |
 |-----------|---------|
 | \`@Job('name')\` | Queue job handler |
@@ -1567,10 +1479,11 @@ Precedence high → low: **method > class > module > adapter > global**.
 Cycles or unmet \`dependsOn\` keys throw \`MissingContributorError\` at boot.
 
 **Critical rules — all stem from the same shared-via-ALS instance model**:
-- Every per-request stage (middleware → contributors → handler) gets its OWN \`RequestContext\` instance, but they all read/write the SAME \`AsyncLocalStorage\`-backed Map (\`requestStore.getStore().values\`).
+- Every per-request stage (middleware → contributors → handler) gets its OWN \`RequestContext\` instance, but they all read/write the SAME \`AsyncLocalStorage\`-backed bag.
 - **\`resolve\` and \`onError\` must RETURN the value** — the runner writes it via \`ctx.set(key, value)\`. Direct property assignment (\`ctx.tenant = …\`) sticks to one instance only and the handler instance never sees it.
 - \`ctx.set('tenant', x)\` then \`ctx.get('tenant')\` works across instances. \`ctx.req.headers[...]\` works (the underlying Express request is shared).
-- Services can read contributor output without a \`ctx\` reference via \`requestStore.getStore()?.values.get('tenant')\` — same Map, no DI plumbing needed.
+- Services with no \`ctx\` reference: \`getRequestValue('tenant')\` returns \`MetaValue<'tenant'> | undefined\` (typed via the augmented \`ContextMeta\`). For \`requestId\` use \`getRequestStore()\`.
+- **No \`setRequestValue\` — writes flow through \`ctx.set\` or a contributor's return value.** Avoids "spooky action at a distance" where any service can pollute the per-request bag.
 
 **Don't use this for**: response short-circuit, stream mutation, or
 pre-route-matching work — keep \`@Middleware()\` for those.
@@ -1643,7 +1556,6 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
 	await writeFileSafe(join(dir, "src/modules/hello/hello.controller.ts"), generateHelloController());
 	await writeFileSafe(join(dir, "src/modules/hello/hello.module.ts"), generateHelloModule());
-	if (template === "graphql") await writeFileSafe(join(dir, "src/resolvers/.gitkeep"), "");
 	await writeFileSafe(join(dir, "kick.config.ts"), generateKickConfig(template, defaultRepo, packageManager));
 	await writeFileSafe(join(dir, "vitest.config.ts"), generateVitestConfig());
 	await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
@@ -1699,7 +1611,6 @@ async function initProject(options) {
 	if (!options.installDeps) log(`  ${packageManager} install`);
 	const genHint = {
 		rest: "kick g module user",
-		graphql: "kick g resolver user",
 		ddd: "kick g module user --repo drizzle",
 		cqrs: "kick g module user --pattern cqrs",
 		minimal: "# add your routes to src/index.ts"
@@ -1721,7 +1632,6 @@ async function initProject(options) {
 	log("  kick g guard <name>       Route guard (auth, roles, etc.)");
 	log("  kick g adapter <name>     AppAdapter with lifecycle hooks");
 	log("  kick g dto <name>         Zod DTO schema");
-	if (template === "graphql") log("  kick g resolver <name>    GraphQL resolver");
 	if (template === "cqrs") log("  kick g job <name>         Queue job processor");
 	log("  kick g config             Generate kick.config.ts");
 	log("");
@@ -1729,8 +1639,7 @@ async function initProject(options) {
 	log("  kick add <pkg>            Install a KickJS package + peers");
 	log("  kick add --list           Show all available packages");
 	log("");
-	log("Available: auth, swagger, graphql, drizzle, prisma, ws, cron,");
-	log("           queue, mailer, otel, devtools, multi-tenant, notifications, mcp, testing");
+	log("Available: auth, swagger, drizzle, prisma, ws, queue, devtools, mcp, testing");
 	log("");
 }
 //#endregion
@@ -1816,11 +1725,6 @@ const OPTIONAL_PACKAGES = [
 		label: "Swagger",
 		hint: "OpenAPI docs"
 	},
-	{
-		value: "otel",
-		label: "OpenTelemetry",
-		hint: "tracing & metrics"
-	},
 	{
 		value: "ws",
 		label: "WebSocket",
@@ -1831,39 +1735,14 @@ const OPTIONAL_PACKAGES = [
 		label: "Queue",
 		hint: "BullMQ/RabbitMQ/Kafka"
 	},
-	{
-		value: "cron",
-		label: "Cron",
-		hint: "scheduled jobs"
-	},
-	{
-		value: "mailer",
-		label: "Mailer",
-		hint: "SMTP, Resend, SES"
-	},
-	{
-		value: "graphql",
-		label: "GraphQL",
-		hint: "resolvers, GraphiQL"
-	},
 	{
 		value: "devtools",
 		label: "DevTools",
 		hint: "debug dashboard"
-	},
-	{
-		value: "notifications",
-		label: "Notifications",
-		hint: "email, Slack, Discord"
-	},
-	{
-		value: "multi-tenant",
-		label: "Multi-Tenant",
-		hint: "tenant resolution"
 	}
 ];
 function registerInitCommand(program) {
-	program.command("new [name]").alias("init").description("Create a new KickJS project (use \".\" for current directory)").option("-d, --directory <dir>", "Target directory (defaults to project name)").option("--pm <manager>", "Package manager: pnpm | npm | yarn | bun").option("--git", "Initialize git repository").option("--no-git", "Skip git initialization").option("--install", "Install dependencies after scaffolding").option("--no-install", "Skip dependency installation").option("-f, --force", "Remove existing files without prompting").option("-t, --template <type>", "Project template: rest | graphql | ddd | cqrs | minimal").option("-r, --repo <type>", "Default repository: prisma | drizzle | inmemory | custom").option("--packages <packages>", "Comma-separated packages to include (e.g. auth,swagger,otel)").action(async (name, opts) => {
+	program.command("new [name]").alias("init").description("Create a new KickJS project (use \".\" for current directory)").option("-d, --directory <dir>", "Target directory (defaults to project name)").option("--pm <manager>", "Package manager: pnpm | npm | yarn | bun").option("--git", "Initialize git repository").option("--no-git", "Skip git initialization").option("--install", "Install dependencies after scaffolding").option("--no-install", "Skip dependency installation").option("-f, --force", "Remove existing files without prompting").option("-t, --template <type>", "Project template: rest | ddd | cqrs | minimal").option("-r, --repo <type>", "Default repository: prisma | drizzle | inmemory | custom").option("--packages <packages>", "Comma-separated packages to include (e.g. auth,swagger,ws,queue)").action(async (name, opts) => {
 		intro("KickJS — Create a new project");
 		if (!name) name = await text({
 			message: "Project name",
@@ -1907,11 +1786,6 @@ function registerInitCommand(program) {
 					label: "REST API",
 					hint: "Express + Swagger"
 				},
-				{
-					value: "graphql",
-					label: "GraphQL API",
-					hint: "GraphQL + GraphiQL"
-				},
 				{
 					value: "ddd",
 					label: "DDD",
@@ -4060,7 +3934,6 @@ function resolveRepoType(config) {
 * Patterns:
 *   rest         — flat folder: controller + service + DTOs + repo
 *   ddd          — nested DDD: presentation/ application/ domain/ infrastructure/
-*   graphql      — flat folder: resolver + service + DTOs + repo (future)
 *   cqrs         — commands, queries, events with WS/queue integration
 *   minimal      — just controller + module index
 */
@@ -4173,7 +4046,13 @@ async function generateAdapter(options) {
 	const pascal = toPascalCase(name);
 	const files = [];
 	const filePath = join(outDir, `${kebab}.adapter.ts`);
-	await writeFileSafe(filePath, `import { defineAdapter, type AdapterContext, type AdapterMiddleware } from '@forinda/kickjs'
+	await writeFileSafe(filePath, `import {
+  defineAdapter,
+  type AdapterContext,
+  type AdapterMiddleware,
+  type ContributorRegistrations,
+  type Constructor,
+} from '@forinda/kickjs'
 
 /**
  * Configuration for the ${pascal} adapter.
@@ -4194,7 +4073,12 @@ export interface ${pascal}AdapterConfig {
  * factory's call / \`.scoped()\` / \`.async()\` surfaces for free.
  *
  * Hooks into the Application lifecycle to add middleware, routes,
- * or external service connections.
+ * Context Contributors, or external service connections.
+ *
+ * Every lifecycle hook below is OPTIONAL. The scaffold emits all of
+ * them so adopters can browse what's available and delete what they
+ * don't need — \`build()\` returning \`{}\` is also valid for an adapter
+ * that only contributes config defaults.
  *
  * @example
  * \`\`\`ts
@@ -4210,59 +4094,126 @@ export interface ${pascal}AdapterConfig {
 export const ${pascal}Adapter = defineAdapter<${pascal}AdapterConfig>({
   name: '${pascal}Adapter',
   defaults: {
-    // Default config values go here
+    // Default config values go here. The adopter's overrides shallow-merge
+    // on top of these before \`build()\` runs.
   },
-  build: (_config, { name: _name }) => ({
-    /**
-     * Return middleware entries that the Application will mount.
-     * \`phase\` controls 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, res, next) => {
-        //     res.setHeader('X-${pascal}', 'true')
-        //     next()
-        //   },
-        // },
-      ]
-    },
-
-    /**
-     * Called before global middleware. Use this to mount routes that
-     * bypass the middleware stack (health checks, docs UI, static
-     * assets).
-     */
-    beforeMount(_ctx: AdapterContext): void {
-      // Example:
-      // _ctx.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(_ctx: AdapterContext): void {
-      // Example: _ctx.container.bindToken(MY_TOKEN, new MyService(_config))
-    },
+  build: (_config, { name: _name }) => {
+    // Closures inside \`build()\` are how each adapter instance owns its
+    // own state (database client, Map, timer handle, …). The same
+    // \`_config\` is visible to every hook below.
 
-    /**
-     * Called after the HTTP server is listening. Use this to attach
-     * to the raw http.Server (Socket.IO, gRPC, etc).
-     */
-    afterStart(_ctx: AdapterContext): void {
-      // Example: const io = new Server(_ctx.server)
-    },
-
-    /** Called on graceful shutdown. Clean up connections. */
-    async shutdown(): Promise<void> {
-      // Example: await this.pool.end()
-    },
-  }),
+    return {
+      /**
+       * Express middleware entries the Application mounts at named phases.
+       *
+       * \`phase\` controls where each handler sits in the pipeline:
+       *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'.
+       *
+       * \`path\` (optional) scopes the entry to a path prefix.
+       *
+       * Delete this hook entirely if you don't add middleware.
+       */
+      middleware(): AdapterMiddleware[] {
+        return [
+          // Example: add a custom header to all responses
+          // {
+          //   phase: 'beforeGlobal',
+          //   handler: (_req, res, next) => {
+          //     res.setHeader('X-${pascal}', 'true')
+          //     next()
+          //   },
+          // },
+          // Example: scope a rate limiter to one path prefix
+          // {
+          //   phase: 'beforeRoutes',
+          //   path: '/api/v1/auth',
+          //   handler: rateLimit({ max: 10 }),
+          // },
+        ]
+      },
+
+      /**
+       * Runs BEFORE global middleware. Mount routes that should bypass the
+       * middleware stack — health checks, docs UI, static assets, OAuth
+       * callbacks. Anything you want reachable even if a global middleware
+       * later in the chain rejects requests.
+       *
+       * Delete this hook if you have no early routes.
+       */
+      beforeMount(_ctx: AdapterContext): void {
+        // Example:
+        // _ctx.app.get('/${kebab}/status', (_req, res) => res.json({ status: 'ok' }))
+      },
+
+      /**
+       * Fires once per controller class as the router mounts. Use this to
+       * collect route metadata for OpenAPI specs, dependency graphs, route
+       * inventories, devtools dashboards.
+       *
+       * Delete this hook unless your adapter introspects the route registry.
+       */
+      onRouteMount(_controllerClass: Constructor, _mountPath: string): void {
+        // Example (Swagger-style): collect routes for the spec.
+        // openApiSpec.addController(_controllerClass, _mountPath)
+      },
+
+      /**
+       * Runs AFTER modules + routes are wired, BEFORE the server starts.
+       * Right place for late-stage DI registrations or final config validation.
+       *
+       * Delete this hook if there's nothing to wire post-modules.
+       */
+      beforeStart(_ctx: AdapterContext): void {
+        // Example: _ctx.container.registerInstance(MY_TOKEN, new MyService(_config))
+      },
+
+      /**
+       * Runs AFTER the HTTP server is listening. The raw \`http.Server\` is
+       * available on \`ctx.server\` — attach upgrade handlers (Socket.IO,
+       * gRPC, GraphQL subscriptions), warm caches, log a banner.
+       *
+       * Delete this hook if you don't need the running server reference.
+       */
+      afterStart(_ctx: AdapterContext): void {
+        // Example: const io = new Server(_ctx.server)
+      },
+
+      /**
+       * Returns Context Contributors to merge into every route's pipeline
+       * at the \`'adapter'\` precedence level. Per-route handlers can
+       * override the value at the method / class / module level.
+       *
+       * Delete this hook unless your adapter ships typed per-request values
+       * (auth user, tenant, locale, feature flags, geo, etc).
+       */
+      contributors(): ContributorRegistrations {
+        return [
+          // Example:
+          // import { defineHttpContextDecorator } from '@forinda/kickjs'
+          // declare module '@forinda/kickjs' { interface ContextMeta { ${kebab}: { id: string } } }
+          // const Load${pascal} = defineHttpContextDecorator({
+          //   key: '${kebab}',
+          //   resolve: (ctx) => ({ id: ctx.req.headers['x-${kebab}-id'] as string }),
+          // })
+          // return [Load${pascal}.registration]
+        ]
+      },
+
+      /**
+       * Runs on graceful shutdown (SIGINT/SIGTERM). Clean up long-lived
+       * resources the adapter owns: close connections, flush buffers,
+       * cancel timers. The framework runs every adapter's \`shutdown\`
+       * concurrently via \`Promise.allSettled\` — one failure won't block
+       * sibling adapters.
+       *
+       * Delete this hook if your adapter holds no resources.
+       */
+      async shutdown(): Promise<void> {
+        // Example: await this.pool.end()
+        // Example: clearInterval(this.heartbeatTimer)
+      },
+    }
+  },
 })
 `);
 	files.push(filePath);
@@ -4290,6 +4241,7 @@ async function generatePlugin(options) {
   type AppAdapter,
   type AppModuleClass,
   type Container,
+  type ContributorRegistrations,
 } from '@forinda/kickjs'
 
 /**
@@ -4321,8 +4273,9 @@ export interface ${pascal}PluginConfig {
  *   2. \`modules()\`            — plugin modules load before user modules.
  *   3. \`adapters()\`           — plugin adapters mount before user adapters.
  *   4. \`middleware()\`         — plugin middleware runs before user middleware.
- *   5. \`onReady(container)\`   — runs after the app has fully bootstrapped.
- *   6. \`shutdown()\`           — runs on graceful shutdown.
+ *   5. \`contributors()\`       — Context Contributors merged into every route.
+ *   6. \`onReady(container)\`   — runs after the app has fully bootstrapped.
+ *   7. \`shutdown()\`           — runs on graceful shutdown.
  *
  * @example
  * \`\`\`ts
@@ -4383,6 +4336,27 @@ export const ${pascal}Plugin = definePlugin<${pascal}PluginConfig>({
       ]
     },
 
+    /**
+     * Return Context Contributors to merge into every route's pipeline.
+     * Plugins contribute at the same \`'adapter'\` precedence level as
+     * adapters — overrideable per-route at the method / class / module
+     * level. See https://forinda.github.io/kick-js/guide/context-decorators
+     *
+     * Delete this hook if your plugin doesn't ship typed per-request values.
+     */
+    contributors(): ContributorRegistrations {
+      return [
+        // Example:
+        // import { defineHttpContextDecorator } from '@forinda/kickjs'
+        // declare module '@forinda/kickjs' { interface ContextMeta { ${kebab}: { foo: string } } }
+        // const Load${pascal} = defineHttpContextDecorator({
+        //   key: '${kebab}',
+        //   resolve: (ctx) => ({ foo: ctx.req.headers['x-${kebab}'] as string }),
+        // })
+        // return [Load${pascal}.registration]
+      ]
+    },
+
     /**
      * Called after the application has fully bootstrapped. Use this
      * for post-startup work like logging, health checks, or warming
@@ -4839,7 +4813,6 @@ function escapesRoot$1(path, root) {
 //#region src/generators/agent-docs.ts
 const VALID_TEMPLATES = new Set([
 	"rest",
-	"graphql",
 	"ddd",
 	"cqrs",
 	"minimal"
@@ -5151,82 +5124,6 @@ export class AuthService {
 `;
 }
 //#endregion
-//#region src/generators/resolver.ts
-async function generateResolver(options) {
-	const { name, outDir } = options;
-	const pascal = toPascalCase(name);
-	const kebab = toKebabCase(name);
-	const camel = toCamelCase(name);
-	const files = [];
-	const write = async (relativePath, content) => {
-		const fullPath = join(outDir, relativePath);
-		await writeFileSafe(fullPath, content);
-		files.push(fullPath);
-	};
-	await write(`${kebab}.resolver.ts`, `import { Service } from '@forinda/kickjs'
-import { Resolver, Query, Mutation, Arg } from '@forinda/kickjs-graphql'
-
-/**
- * ${pascal} GraphQL Resolver
- *
- * Decorators:
- *   @Resolver(typeName?) — marks this class as a GraphQL resolver
- *   @Query(name?, { returnType?, description? }) — defines a query field
- *   @Mutation(name?, { returnType?, description? }) — defines a mutation field
- *   @Arg(name, type?) — marks a method parameter as a GraphQL argument
- */
-@Service()
-@Resolver('${pascal}')
-export class ${pascal}Resolver {
-  private items: Array<{ id: string; name: string }> = []
-
-  @Query('${camel}s', { returnType: '[${pascal}]', description: 'List all ${camel}s' })
-  findAll() {
-    return this.items
-  }
-
-  @Query('${camel}', { returnType: '${pascal}', description: 'Get a ${camel} by ID' })
-  findById(@Arg('id', 'ID!') id: string) {
-    return this.items.find((item) => item.id === id) ?? null
-  }
-
-  @Mutation('create${pascal}', { returnType: '${pascal}', description: 'Create a new ${camel}' })
-  create(@Arg('name', 'String!') name: string) {
-    const item = { id: String(this.items.length + 1), name }
-    this.items.push(item)
-    return item
-  }
-
-  @Mutation('update${pascal}', { returnType: '${pascal}', description: 'Update a ${camel}' })
-  update(@Arg('id', 'ID!') id: string, @Arg('name', 'String!') name: string) {
-    const item = this.items.find((i) => i.id === id)
-    if (item) item.name = name
-    return item
-  }
-
-  @Mutation('delete${pascal}', { returnType: 'Boolean', description: 'Delete a ${camel}' })
-  remove(@Arg('id', 'ID!') id: string) {
-    const idx = this.items.findIndex((i) => i.id === id)
-    if (idx === -1) return false
-    this.items.splice(idx, 1)
-    return true
-  }
-}
-`);
-	await write(`${kebab}.typedefs.ts`, `/**
- * ${pascal} GraphQL type definitions.
- * Pass to GraphQLAdapter's typeDefs option to register custom types.
- */
-export const ${camel}TypeDefs = \`
-  type ${pascal} {
-    id: ID!
-    name: String!
-  }
-\`
-`);
-	return files;
-}
-//#endregion
 //#region src/generators/job.ts
 async function generateJob(options) {
 	const { name, outDir } = options;
@@ -6389,10 +6286,8 @@ function extractAugmentationsFromSource(source, filePath, cwd) {
 				const closeBrace = findBalancedBrace(source, bracePos);
 				if (closeBrace >= 0) {
 					const body = source.slice(bracePos + 1, closeBrace);
-					const descMatch = /\bdescription\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
-					const exampleMatch = /\bexample\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
-					description = descMatch ? descMatch[1] : null;
-					example = exampleMatch ? exampleMatch[1] : null;
+					description = readStringField(body, "description");
+					example = readStringField(body, "example");
 				}
 			}
 		}
@@ -6407,6 +6302,46 @@ function extractAugmentationsFromSource(source, filePath, cwd) {
 	return out;
 }
 /**
+* Pull a string-valued field out of a JS object-literal body, respecting
+* the opening quote so the value isn't truncated at the first foreign
+* quote character. Handles backslash escapes inside the literal.
+*
+* Why a custom parser instead of one regex per delimiter: real-world
+* `defineAugmentation` calls embed all three quote characters at once
+* — backtick template literals carrying TS shapes like
+* `'free' | 'pro'` (single quotes) AND `\`ctx.get(...)\`` (escaped
+* backticks). A character-class regex like `[^'"`]+` truncates on the
+* first foreign quote it sees. This walker scans char-by-char from
+* the matched delimiter and only stops on the matching one.
+*/
+function readStringField(body, field) {
+	const m = new RegExp(`\\b${field}\\s*:\\s*(['"\`])`, "g").exec(body);
+	if (!m) return null;
+	const quote = m[1];
+	const start = m.index + m[0].length;
+	let i = start;
+	let raw = null;
+	while (i < body.length) {
+		const ch = body[i];
+		if (ch === "\\") {
+			i += 2;
+			continue;
+		}
+		if (ch === quote) {
+			raw = body.slice(start, i);
+			break;
+		}
+		i++;
+	}
+	if (raw === null) return null;
+	return raw.replace(/\\(.)/g, (_m, c) => {
+		if (c === "n") return "\n";
+		if (c === "t") return "	";
+		if (c === "r") return "\r";
+		return c;
+	});
+}
+/**
 * Default search order for the env schema file. Newer projects keep
 * the schema under `src/config/` so the framework's "config" concept
 * has a single home; older scaffolds dropped it at `src/env.ts` (kept
@@ -7417,10 +7352,6 @@ const GENERATORS = [
 		name: "test <name>",
 		description: "Vitest test scaffold            [-m module]"
 	},
-	{
-		name: "resolver <name>",
-		description: "GraphQL @Resolver class"
-	},
 	{
 		name: "job <name>",
 		description: "Queue @Job processor"
@@ -7622,14 +7553,6 @@ function registerGenerateCommand(program) {
 			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) => {
-		const dryRun = isDryRun(cmd);
-		setDryRun(dryRun);
-		printGenerated(await generateResolver({
-			name,
-			outDir: resolve(opts.out)
-		}), dryRun);
-	});
 	gen.command("job <name>").description("Generate a @Job queue processor with @Process handlers").option("-o, --out <dir>", "Output directory", "src/jobs").option("-q, --queue <name>", "Queue name (default: <name>-queue)").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
@@ -7699,7 +7622,7 @@ function registerGenerateCommand(program) {
 			force: opts.force
 		}), dryRun);
 	});
-	gen.command("agents").alias("agent-docs").alias("ai-docs").description("Regenerate AGENTS.md + CLAUDE.md + kickjs-skills.md (sync after framework upgrades)").option("--only <which>", "Limit scope: agents | claude | skills | both (agents+claude) | all (default: all)", "all").option("--name <name>", "Project name (defaults to package.json name)").option("--pm <pm>", "Package manager (defaults to package.json packageManager)").option("--template <template>", "Template: rest | graphql | ddd | cqrs | minimal").option("-f, --force", "Overwrite existing files without prompting").action(async (opts, cmd) => {
+	gen.command("agents").alias("agent-docs").alias("ai-docs").description("Regenerate AGENTS.md + CLAUDE.md + kickjs-skills.md (sync after framework upgrades)").option("--only <which>", "Limit scope: agents | claude | skills | both (agents+claude) | all (default: all)", "all").option("--name <name>", "Project name (defaults to package.json name)").option("--pm <pm>", "Package manager (defaults to package.json packageManager)").option("--template <template>", "Template: rest | ddd | cqrs | minimal").option("-f, --force", "Overwrite existing files without prompting").action(async (opts, cmd) => {
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
 		const only = opts.only ?? "all";
@@ -8282,11 +8205,6 @@ const PACKAGE_REGISTRY = {
 		peers: [],
 		description: "OpenAPI spec + Swagger UI + ReDoc"
 	},
-	graphql: {
-		pkg: "@forinda/kickjs-graphql",
-		peers: ["graphql"],
-		description: "GraphQL resolvers + GraphiQL"
-	},
 	drizzle: {
 		pkg: "@forinda/kickjs-drizzle",
 		peers: ["drizzle-orm"],
@@ -8302,11 +8220,6 @@ const PACKAGE_REGISTRY = {
 		peers: ["socket.io"],
 		description: "WebSocket with @WsController decorators"
 	},
-	otel: {
-		pkg: "@forinda/kickjs-otel",
-		peers: ["@opentelemetry/api"],
-		description: "OpenTelemetry tracing + metrics"
-	},
 	devtools: {
 		pkg: "@forinda/kickjs-devtools",
 		peers: [],
@@ -8318,16 +8231,6 @@ const PACKAGE_REGISTRY = {
 		peers: ["jsonwebtoken"],
 		description: "Authentication — JWT, API key, and custom strategies"
 	},
-	mailer: {
-		pkg: "@forinda/kickjs-mailer",
-		peers: ["nodemailer"],
-		description: "Email sending — SMTP, Resend, SES, or custom provider"
-	},
-	cron: {
-		pkg: "@forinda/kickjs-cron",
-		peers: ["croner"],
-		description: "Cron job scheduling (production-grade with croner)"
-	},
 	queue: {
 		pkg: "@forinda/kickjs-queue",
 		peers: [],
@@ -8348,16 +8251,6 @@ const PACKAGE_REGISTRY = {
 		peers: ["kafkajs"],
 		description: "Queue with Kafka"
 	},
-	"multi-tenant": {
-		pkg: "@forinda/kickjs-multi-tenant",
-		peers: [],
-		description: "Tenant resolution middleware"
-	},
-	notifications: {
-		pkg: "@forinda/kickjs-notifications",
-		peers: [],
-		description: "Multi-channel notifications — email, Slack, Discord, webhook"
-	},
 	mcp: {
 		pkg: "@forinda/kickjs-mcp",
 		peers: ["@modelcontextprotocol/sdk"],
@@ -8411,7 +8304,7 @@ function printPackageList() {
 		const peers = info.peers.length ? ` (+ ${info.peers.join(", ")})` : "";
 		console.log(`    ${padded} ${info.description}${peers}`);
 	}
-	console.log("\n  Usage: kick add graphql drizzle otel");
+	console.log("\n  Usage: kick add auth drizzle swagger");
 	console.log("         kick add queue:bullmq");
 	console.log();
 }