muneebhashone
diff --git a/‎.claude/commands/create-module.md‎
Lines changed: 93 additions & 0 deletions b/‎.claude/commands/create-module.md‎
Lines changed: 93 additions & 0 deletions
diff --git a/‎.claude/commands/create-seeder.md‎
Lines changed: 80 additions & 0 deletions b/‎.claude/commands/create-seeder.md‎
Lines changed: 80 additions & 0 deletions
diff --git a/‎.claude/settings.local.json‎
Lines changed: 31 additions & 0 deletions b/‎.claude/settings.local.json‎
Lines changed: 31 additions & 0 deletions
diff --git a/‎.cursor/commands/create-module.md‎
Lines changed: 181 additions & 0 deletions b/‎.cursor/commands/create-module.md‎
Lines changed: 181 additions & 0 deletions
@@ -0,0 +1,93 @@
+---
+description: Scaffold a fully-typed module with controller, service, router, schema, and model files
+argument-hint: <moduleName> [--path <apiPath>]
+allowed-tools: Bash, Read, Edit
+model: claude-sonnet-4-5
+---
+
+# Create Module
+
+Generate a complete module with all required files and wire it into the application.
+
+## Task
+
+**Arguments:**
+- `$1` (required): module name (e.g., `product`, `payment`)
+- `$2` (optional): API path flag `--path`
+- `$3` (optional): API path value (e.g., `/api/v1`); defaults to `/api`
+
+**Module Name:** `$1`
+
+1. **Generate module files**
+
+   Run the generator command:
+   ```bash
+   pnpm tbk generate:module $1 $2 $3
+   ```
+
+   This creates:
+
+   - `src/modules/<moduleName>/<moduleName>.dto.ts`
+   - `src/modules/<moduleName>/<moduleName>.model.ts`
+   - `src/modules/<moduleName>/<moduleName>.schema.ts`
+   - `src/modules/<moduleName>/<moduleName>.services.ts`
+   - `src/modules/<moduleName>/<moduleName>.controller.ts`
+   - `src/modules/<moduleName>/<moduleName>.router.ts` (exports `<MODULE>_ROUTER_ROOT` and default router)
+
+2. **Register router in routes**
+
+   Read `src/routes/routes.ts` and add the router registration:
+
+   - Add import at top with other module imports
+   - Add `router.use()` call with other registrations
+   - Use camelCase for router variable name
+   - Use UPPER_SNAKE_CASE for the router root constant
+
+3. **Rebuild OpenAPI documentation**
+
+   ```bash
+   pnpm openapi
+   ```
+
+   Auto-generates Swagger from MagicRouter + Zod schemas.
+
+4. **Typecheck and lint**
+
+   ```bash
+   pnpm typecheck && pnpm lint
+   ```
+
+5. **Register with admin dashboard** (optional)
+
+   Ask the user if they want to add this module to the admin panel.
+
+   If yes, read and edit `src/plugins/admin/registry.ts` to add the resource.
+
+6. **Optional: Create seeder and factory**
+
+   Ask the user if they need test data generation for this module.
+
+   If yes, run:
+   ```bash
+   pnpm tbk make:factory $1/$(echo $1 | sed 's/.*/\u&/')
+   pnpm tbk make:seeder $1/$(echo $1 | sed 's/.*/\u&/')
+   ```
+
+## Verification
+
+After completing all steps, verify:
+
+1. Module files exist in `src/modules/$1/`
+2. Router is registered in `src/routes/routes.ts`
+3. OpenAPI spec regenerated successfully
+4. No type errors or lint warnings
+5. Admin panel configured (if requested)
+
+Report success with the module name and available endpoints.
+
+## Context
+
+- All routes use MagicRouter (NOT plain Express)
+- Response schemas use `R.success()`, `R.paginated()`, `R.error()` builders
+- Controllers use `ResponseExtended<T>` for type-safe responses
+- Update `src/config/env.ts` and `.env.sample` if new env vars are needed
@@ -0,0 +1,80 @@
+---
+description: Scaffold a seeder and factory for a module to populate test data
+argument-hint: <module>/<Name>
+allowed-tools: Bash, Read, Edit
+model: claude-sonnet-4-5
+---
+
+# Create Seeder & Factory
+
+Generate a factory and seeder for an existing module, register it, and optionally run it.
+
+## Task
+
+**Arguments:**
+- `$1` (required): module/name path (e.g., `user/User`, `product/Product`)
+
+Parse `$1` to extract:
+- Module name: everything before `/`
+- Entity name: everything after `/`
+
+## Steps
+
+1. **Generate factory and seeder files**
+
+   Run both commands:
+   ```bash
+   pnpm tbk make:factory $1 && pnpm tbk make:seeder $1
+   ```
+
+   This creates:
+   - `src/modules/{module}/factories/{name}.factory.ts` (exports camelCase factory)
+   - `src/modules/{module}/seeders/{Name}Seeder.ts`
+
+2. **Implement seeder logic**
+
+   Read the generated seeder file and verify it:
+   - Imports the correct factory
+   - Imports the module's model
+   - Has proper collection name in config
+   - Uses factory.build() correctly
+
+   If the seeder needs customization, ask the user about:
+   - Number of records to generate (default: 10)
+   - Any specific field overrides needed
+   - Dependencies on other seeders
+
+3. **Register seeder**
+
+   Read `src/seeders/registry.ts` and add the new seeder to the array:
+   - Import the seeder class
+   - Add it to the `seeders` export array
+
+4. **Run seeders**
+
+   Ask the user if they want to run the seeder now.
+
+   If yes, offer options:
+   - Dry run first (recommended): `pnpm tbk seed --dry-run --only {Name}Seeder`
+   - Run for real: `pnpm tbk seed --only {Name}Seeder`
+   - Fresh run (drops collection): `pnpm tbk seed --fresh --only {Name}Seeder`
+
+   Run the selected command.
+
+## Verification
+
+After completing all steps, verify:
+
+1. Factory file exists with `build()` method
+2. Seeder file exists with correct imports
+3. Seeder registered in `src/seeders/registry.ts`
+4. Dry run executes without errors
+5. Actual seeding creates expected records (if run)
+
+Report success with the seeder name and record count.
+
+## Context
+
+- Factories export `{camelName}Factory` with a `build(i, overrides)` method
+- Seeders use `ctx.refs.set()` and `ctx.refs.get()` to share data between seeders
+- MongoDB must be running before seeding (`docker compose up -d`)
@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(pnpm build:*)",
+      "Bash(node dist/cli.js test-minimal:*)",
+      "Bash(node bin/index.js:*)",
+      "Bash(node -e \"import { pathExists } from ''./dist/cli.js''; console.log(await pathExists(''templates''));\")",
+      "Bash(test:*)",
+      "Bash(/dev/null)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm typecheck:*)",
+      "Bash(xargs:*)",
+      "Bash(if [ -d test-minimal ])",
+      "Bash(then rm -rf test-minimal)",
+      "Bash(fi)",
+      "Bash(node packages/create-tbk-app/dist/cli.js:*)",
+      "Bash(for file in \"c:\\Users\\themuneebh\\repos\\typescript-backend-toolkit\\packages\\create-tbk-app\\templates\\auth\\src\\modules\\auth\\auth.service.ts.hbs\" \"c:\\Users\\themuneebh\\repos\\typescript-backend-toolkit\\packages\\create-tbk-app\\templates\\auth\\src\\modules\\auth\\auth.controller.ts.hbs\" \"c:\\Users\\themuneebh\\repos\\typescript-backend-toolkit\\packages\\create-tbk-app\\templates\\auth\\src\\modules\\auth\\auth.router.ts.hbs\" \"c:\\Users\\themuneebh\\repos\\typescript-backend-toolkit\\packages\\create-tbk-app\\templates\\auth\\src\\plugins\\auth\\index.ts.hbs\" \"c:\\Users\\themuneebh\\repos\\typescript-backend-toolkit\\packages\\create-tbk-app\\templates\\auth\\src\\middlewares\\extract-jwt.ts.hbs\")",
+      "Bash(do)",
+      "Bash(done)",
+      "Bash(if [ -d test-standard-jwt ])",
+      "Bash(then rm -rf test-standard-jwt)",
+      "Bash(node dist/cli.js:*)",
+      "Bash(npx tsc:*)",
+      "Bash(node -e:*)",
+      "Bash(cat:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
@@ -0,0 +1,181 @@
+# Create a new module (tbk CLI)
+
+## Overview
+
+Scaffold a fully-typed module with controller, service, router, schema, and model files, then wire it into the application routing system.
+
+## Inputs
+
+- **moduleName**: module folder/name in `src/modules/` (e.g., `product`)
+- **apiPath**: optional API root path; defaults to `/api` (e.g., `/api/v1`)
+
+## Steps
+
+1. **Generate module files**
+
+   ```bash
+   pnpm tbk generate:module <moduleName> --path <apiPath>
+   ```
+
+   Examples:
+
+   ```bash
+   pnpm tbk generate:module product (recommended)
+   pnpm tbk generate:module product --path /api
+   pnpm tbk generate:module product --path /api/v1
+   ```
+
+   This creates:
+
+   - `src/modules/<moduleName>/<moduleName>.dto.ts`
+   - `src/modules/<moduleName>/<moduleName>.model.ts`
+   - `src/modules/<moduleName>/<moduleName>.schema.ts`
+   - `src/modules/<moduleName>/<moduleName>.services.ts`
+   - `src/modules/<moduleName>/<moduleName>.controller.ts`
+   - `src/modules/<moduleName>/<moduleName>.router.ts` (exports `<MODULE>_ROUTER_ROOT` and default router)
+
+2. **Register router in routes**
+   Add an import and `router.use(...)` in `src/routes/routes.ts`:
+
+   ```ts
+   // add with other imports
+   import <moduleName>Router, { <MODULE_NAME>_ROUTER_ROOT } from '../modules/<moduleName>/<moduleName>.router';
+
+   // add with other router.use calls
+   router.use(<MODULE_NAME>_ROUTER_ROOT, <moduleName>Router);
+   ```
+
+   - Replace `<moduleName>` with your actual module name (e.g., `product`)
+   - Replace `<MODULE_NAME>` with the uppercased module name (e.g., `PRODUCT`)
+
+   Example for `product`:
+
+   ```ts
+   import productRouter, {
+     PRODUCT_ROUTER_ROOT,
+   } from '../modules/product/product.router';
+   router.use(PRODUCT_ROUTER_ROOT, productRouter);
+   ```
+
+3. **Rebuild OpenAPI documentation**
+
+   ```bash
+   pnpm openapi
+   ```
+
+   Auto-generates Swagger from MagicRouter + Zod schemas.
+
+4. **Typecheck and lint**
+
+   ```bash
+   pnpm typecheck && pnpm lint
+   ```
+
+5. **Register with admin dashboard** (if needed)
+
+   Add your module to `src/plugins/admin/registry.ts`:
+
+   ```ts
+   import <ModuleName>Model from '../modules/<moduleName>/<moduleName>.model';
+
+   export const adminResources: AdminResource[] = [
+     // ... existing resources
+     {
+       name: '<moduleName>s',
+       label: '<ModuleName>s',
+       model: <ModuleName>Model,
+       readOnlyFields: ['_id', 'createdAt', 'updatedAt']
+     },
+   ];
+   ```
+
+   - Replace `<moduleName>` with your module name (e.g., `product`)
+   - Replace `<ModuleName>` with PascalCase version (e.g., `Product`)
+   - Adjust `readOnlyFields` as needed for your module
+
+6. **Optional: Create seeder and factory**
+   ```bash
+   pnpm tbk make:factory <moduleName>/<Name>
+   pnpm tbk make:seeder <moduleName>/<Name>
+   ```
+
+## Module Checklist
+
+- [ ] Module files generated successfully
+- [ ] Router registered in `src/routes/routes.ts`
+- [ ] Module registered in admin dashboard (`src/plugins/admin/registry.ts`) (if needed)
+- [ ] OpenAPI documentation rebuilt
+- [ ] Code passes typecheck and lint
+- [ ] Environment variables added to `src/config/env.ts` and `.env.sample` (if needed)
+- [ ] Committed with Conventional Commits format
+
+## Response Validation
+
+Generated modules automatically use the **response validation system**:
+
+- **Response schemas** defined in schema files using `R.success()`, `R.paginated()`, `R.error()` helpers
+- **Response types** exported from schema files for type-safe controllers
+- **Typed response helpers** (`res.ok()`, `res.created()`, `res.noContent()`) in controllers
+- **OpenAPI documentation** includes accurate per-status response schemas
+- **Runtime validation** ensures responses match schemas (configurable via `RESPONSE_VALIDATION` env var)
+
+### Example from generated code:
+
+**Schema file (module.schema.ts):**
+
+```typescript
+import { R } from '../../openapi/response.builders';
+import { itemOutSchema } from './item.dto';
+
+// Response schemas
+export const getItemsResponseSchema = R.paginated(itemOutSchema);
+export const createItemResponseSchema = R.success(itemOutSchema);
+
+// Response types
+export type GetItemsResponseSchema = z.infer<typeof getItemsResponseSchema>;
+export type CreateItemResponseSchema = z.infer<typeof createItemResponseSchema>;
+```
+
+**Router (module.router.ts):**
+
+```typescript
+import { getItemsResponseSchema } from './module.schema';
+
+router.get(
+  '/',
+  {
+    requestType: { query: getItemsSchema },
+    responses: {
+      200: getItemsResponseSchema,
+    },
+  },
+  canAccess(),
+  handleGetItems,
+);
+```
+
+**Controller (module.controller.ts):**
+
+```typescript
+import type { ResponseExtended } from '../../types';
+import type { GetItemsResponseSchema } from './module.schema';
+
+export const handleGetItems = async (
+  req: Request<unknown, unknown, unknown, GetItemsSchemaType>,
+  res: ResponseExtended<GetItemsResponseSchema>,
+) => {
+  const { results, paginatorInfo } = await getItems(req.query);
+  return res.ok?.({
+    success: true,
+    data: { items: results, paginator: paginatorInfo },
+  });
+};
+```
+
+## Notes
+
+- Routes must use `MagicRouter`; the generator already sets this up and defines `<MODULE>_ROUTER_ROOT` using the `--path` you pass
+- Generated code uses **new response validation pattern** - see `docs/RESPONSE_VALIDATION.md` for details
+- Legacy `successResponse()` still works but new pattern is recommended
+- Keep environment configs valid, and update `src/config/env.ts` and `.env.sample` if you introduce new variables
+- Commit with Conventional Commits (e.g., `feat(<moduleName>): add <feature>`)