@devmunna/agent-skillkit 0.1.0

package/skills/express-mvc-prisma/references/module-scaffold.md

@@ -0,0 +1,253 @@
+# Module Scaffold Reference
+
+Complete 4-file template. Replace `user`/`User`/`users` with your resource name.
+
+---
+
+## {module}.validation.js
+
+Validates `body`, `params`, and `query` using Zod v4. One schema per endpoint.
+
+```js
+import { z } from 'zod';
+
+// Body schema for POST /users
+export const createUserSchema = z.object({
+  body: z.object({
+    name:     z.string().min(2, 'Name min 2 chars').max(100),
+    email:    z.string().email('Invalid email'),
+    password: z.string().min(8, 'Password min 8 chars'),
+    role:     z.enum(['USER', 'ADMIN']).default('USER'),
+  }).strict(),
+});
+
+// Body + params for PATCH /users/:id
+export const updateUserSchema = z.object({
+  params: z.object({ id: z.string().uuid('Invalid ID') }),
+  body: z.object({
+    name:  z.string().min(2).max(100).optional(),
+    email: z.string().email().optional(),
+    role:  z.enum(['USER', 'ADMIN']).optional(),
+  }).strict(),
+});
+
+// Params only for GET /users/:id, DELETE /users/:id
+export const userIdSchema = z.object({
+  params: z.object({ id: z.string().uuid('Invalid ID') }),
+});
+
+// Query for GET /users?page=1&limit=10&search=
+export const listUsersSchema = z.object({
+  query: z.object({
+    page:   z.coerce.number().int().positive().default(1),
+    limit:  z.coerce.number().int().positive().max(100).default(10),
+    search: z.string().optional(),
+    role:   z.enum(['USER', 'ADMIN']).optional(),
+  }),
+});
+
+/** @typedef {import('zod').infer<typeof createUserSchema>['body']} CreateUserDto */
+/** @typedef {import('zod').infer<typeof updateUserSchema>['body']} UpdateUserDto */
+```
+
+---
+
+## {module}.service.js
+
+Business logic + all Prisma calls. Throw `AppError` for expected failures.
+Never import `res` or `req` here.
+
+```js
+import { Prisma } from '@prisma/client';
+import prisma     from '../../config/db.js';
+import { AppError } from '../../utils/AppError.js';
+import bcrypt      from 'bcrypt';
+
+export const userService = {
+
+  async getAll({ page = 1, limit = 10, search, role } = {}) {
+    const skip  = (page - 1) * limit;
+    const where = {};
+    if (role)   where.role = role;
+    if (search) where.OR   = [
+      { name:  { contains: search, mode: 'insensitive' } },
+      { email: { contains: search, mode: 'insensitive' } },
+    ];
+
+    const [data, total] = await prisma.$transaction([
+      prisma.user.findMany({
+        where,
+        skip,
+        take: limit,
+        orderBy: { createdAt: 'desc' },
+        select: { id: true, name: true, email: true, role: true, createdAt: true },
+      }),
+      prisma.user.count({ where }),
+    ]);
+
+    return { data, total, page, limit };
+  },
+
+  async getById(id) {
+    const user = await prisma.user.findUnique({
+      where:  { id },
+      select: { id: true, name: true, email: true, role: true, createdAt: true },
+    });
+    if (!user) throw new AppError('User not found', 404);
+    return user;
+  },
+
+  async create(data) {
+    const exists = await prisma.user.findUnique({ where: { email: data.email } });
+    if (exists) throw new AppError('Email already registered', 409);
+
+    const passwordHash = await bcrypt.hash(data.password, 12);
+
+    try {
+      const user = await prisma.user.create({
+        data:   { ...data, password: passwordHash },
+        select: { id: true, name: true, email: true, role: true, createdAt: true },
+      });
+      return user;
+    } catch (err) {
+      if (err instanceof Prisma.PrismaClientKnownRequestError) {
+        if (err.code === 'P2002') throw new AppError('Email already registered', 409);
+      }
+      throw err;
+    }
+  },
+
+  async update(id, data) {
+    try {
+      return await prisma.user.update({
+        where:  { id },
+        data,
+        select: { id: true, name: true, email: true, role: true, updatedAt: true },
+      });
+    } catch (err) {
+      if (err instanceof Prisma.PrismaClientKnownRequestError) {
+        if (err.code === 'P2025') throw new AppError('User not found', 404);
+      }
+      throw err;
+    }
+  },
+
+  async remove(id) {
+    try {
+      await prisma.user.delete({ where: { id } });
+    } catch (err) {
+      if (err instanceof Prisma.PrismaClientKnownRequestError) {
+        if (err.code === 'P2025') throw new AppError('User not found', 404);
+      }
+      throw err;
+    }
+  },
+};
+```
+
+---
+
+## {module}.controller.js
+
+HTTP layer only. No business logic, no Prisma, no try/catch.
+Express v5 auto-forwards async errors to the global error handler.
+
+```js
+import { userService }          from './user.service.js';
+import { sendSuccess }          from '../../utils/response.js';
+
+export const userController = {
+
+  getAll: async (req, res) => {
+    const result = await userService.getAll(req.query);
+    sendSuccess(res, 'Users fetched', result);
+  },
+
+  getById: async (req, res) => {
+    const user = await userService.getById(req.params.id);
+    sendSuccess(res, 'User fetched', user);
+  },
+
+  create: async (req, res) => {
+    const user = await userService.create(req.body);
+    sendSuccess(res, 'User created', user, 201);
+  },
+
+  update: async (req, res) => {
+    const user = await userService.update(req.params.id, req.body);
+    sendSuccess(res, 'User updated', user);
+  },
+
+  remove: async (req, res) => {
+    await userService.remove(req.params.id);
+    sendSuccess(res, 'User deleted');
+  },
+};
+```
+
+---
+
+## {module}.routes.js
+
+Wires middleware → controller. Route order matters: specific before dynamic.
+
+```js
+import { Router }      from 'express';
+import { validate }    from '../../middlewares/validate.middleware.js';
+import { authenticate, requireRole } from '../../middlewares/auth.middleware.js';
+import {
+  createUserSchema, updateUserSchema,
+  userIdSchema, listUsersSchema,
+} from './user.validation.js';
+import { userController } from './user.controller.js';
+
+const router = Router();
+
+router.get(  '/',    authenticate, validate(listUsersSchema),  userController.getAll);
+router.get(  '/:id', authenticate, validate(userIdSchema),     userController.getById);
+router.post( '/',    authenticate, validate(createUserSchema),  userController.create);
+router.patch('/:id', authenticate, validate(updateUserSchema),  userController.update);
+router.delete('/:id',authenticate, validate(userIdSchema),     userController.remove);
+
+export default router;
+```
+
+---
+
+## Register in src/routes/index.js
+
+```js
+import userRouter from '../modules/user/user.routes.js';
+
+router.use('/users', userRouter);
+```
+
+---
+
+## Pagination Response Shape
+
+```json
+{
+  "success": true,
+  "message": "Users fetched",
+  "data": [...],
+  "meta": {
+    "total": 85,
+    "page": 2,
+    "limit": 10,
+    "totalPages": 9,
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
+```
+
+Single item:
+```json
+{ "success": true, "message": "User fetched", "data": { "id": "...", "name": "..." } }
+```
+
+Deleted / no data:
+```json
+{ "success": true, "message": "User deleted" }
+```

package/skills/express-mvc-prisma/references/prisma-setup.md

@@ -0,0 +1,97 @@
+# Prisma Setup Reference
+
+## Installation
+
+```bash
+npm install @prisma/client
+npm install -D prisma
+npx prisma init --datasource-provider postgresql
+```
+
+---
+
+## prisma/schema.prisma — Base Template
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  name      String
+  password  String
+  role      Role     @default(USER)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("users")
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+**Conventions:**
+- Always use `uuid()` for IDs (not auto-increment)
+- Always add `createdAt` + `updatedAt` to every model
+- Use `@@map("snake_case_table_name")` to keep DB column names clean
+- Use enums for fixed value sets (role, status, type)
+
+---
+
+## Migration Commands
+
+```bash
+npx prisma migrate dev --name init     # Create + apply migration (dev)
+npx prisma migrate deploy              # Apply migrations in production
+npx prisma migrate reset               # Reset DB (dev only — destroys data)
+npx prisma generate                    # Regenerate client after schema change
+npx prisma studio                      # Open visual DB browser
+```
+
+---
+
+## Handling Prisma Errors in Repository
+
+```js
+import { Prisma } from '@prisma/client';
+
+try {
+  // ...prisma call
+} catch (error) {
+  if (error instanceof Prisma.PrismaClientKnownRequestError) {
+    switch (error.code) {
+      case 'P2002': throw new AppError('Duplicate entry: ' + error.meta?.target, 409);
+      case 'P2025': throw new AppError('Record not found', 404);
+      case 'P2003': throw new AppError('Related record not found', 400);
+      case 'P2014': throw new AppError('Relation violation', 400);
+      default: throw error;
+    }
+  }
+  throw error;
+}
+```
+
+---
+
+## Transaction Example
+
+```js
+const result = await prisma.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.product.update({
+    where: { id: orderData.productId },
+    data: { stock: { decrement: orderData.quantity } },
+  });
+  return order;
+});
+```

package/skills/express-mvc-prisma/references/response-helpers.md

@@ -0,0 +1,157 @@
+# Response Helpers Reference
+
+---
+
+## src/utils/response.js
+
+```js
+/**
+ * Send a successful JSON response.
+ * If data has { data, total, page, limit } shape → auto-adds meta pagination block.
+ */
+export const sendSuccess = (res, message, data = null, statusCode = 200) => {
+  const body = { success: true, message };
+
+  if (data !== null) {
+    if (isPaginated(data)) {
+      body.data = data.data;
+      body.meta = buildMeta(data);
+    } else {
+      body.data = data;
+    }
+  }
+
+  return res.status(statusCode).json(body);
+};
+
+const isPaginated = (d) =>
+  d !== null &&
+  typeof d === 'object' &&
+  'data' in d &&
+  'total' in d &&
+  'page' in d &&
+  'limit' in d;
+
+const buildMeta = ({ total, page, limit }) => ({
+  total,
+  page,
+  limit,
+  totalPages: Math.ceil(total / limit),
+  hasNext:    page * limit < total,
+  hasPrev:    page > 1,
+});
+```
+
+---
+
+## Usage in controllers
+
+```js
+// List (auto-paginates)
+sendSuccess(res, 'Users fetched', { data: users, total, page, limit });
+
+// Single item
+sendSuccess(res, 'User fetched', user);
+
+// Created
+sendSuccess(res, 'User created', user, 201);
+
+// Deleted / no data
+sendSuccess(res, 'User deleted');
+```
+
+---
+
+## Response Shapes
+
+### Single item
+```json
+{
+  "success": true,
+  "message": "User fetched",
+  "data": { "id": "uuid", "name": "Alice", "email": "alice@example.com" }
+}
+```
+
+### Paginated list
+```json
+{
+  "success": true,
+  "message": "Users fetched",
+  "data": [...],
+  "meta": {
+    "total": 85,
+    "page": 2,
+    "limit": 10,
+    "totalPages": 9,
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
+```
+
+### Created (201)
+```json
+{ "success": true, "message": "User created", "data": { "id": "...", "name": "..." } }
+```
+
+### No data (delete, void operations)
+```json
+{ "success": true, "message": "User deleted" }
+```
+
+### Error (from errorHandler)
+```json
+{
+  "success": false,
+  "message": "User not found"
+}
+```
+
+### Validation error (from validate middleware)
+```json
+{
+  "success": false,
+  "message": "Invalid email",
+  "errors": [
+    { "field": "body.email", "message": "Invalid email" }
+  ]
+}
+```
+
+---
+
+## Pagination in service layer
+
+```js
+async getAll({ page = 1, limit = 10, search } = {}) {
+  const skip  = (page - 1) * limit;
+  const where = search
+    ? { name: { contains: search, mode: 'insensitive' } }
+    : {};
+
+  const [data, total] = await prisma.$transaction([
+    prisma.user.findMany({ where, skip, take: limit, orderBy: { createdAt: 'desc' } }),
+    prisma.user.count({ where }),
+  ]);
+
+  return { data, total, page, limit }; // sendSuccess auto-detects this shape
+}
+```
+
+---
+
+## HTTP Status Codes
+
+| Code | Use case |
+|------|---------|
+| 200 | OK — GET, PATCH, DELETE success |
+| 201 | Created — POST success |
+| 400 | Bad Request — business logic error |
+| 401 | Unauthorized — missing or invalid token |
+| 403 | Forbidden — authenticated, insufficient role |
+| 404 | Not Found |
+| 409 | Conflict — duplicate entry |
+| 422 | Unprocessable — validation error |
+| 429 | Too Many Requests — rate limit |
+| 500 | Internal Server Error |

package/skills/express-mvc-prisma/references/zod-validation.md

@@ -0,0 +1,157 @@
+# Zod v4 Validation Reference
+
+---
+
+## validate.middleware.js
+
+Validates `body`, `params`, and `query` in one call. Uses Zod v4 `.issues` API.
+
+```js
+import { AppError } from '../utils/AppError.js';
+
+export const validate = (schema) => (req, res, next) => {
+  const result = schema.safeParse({
+    body:   req.body,
+    params: req.params,
+    query:  req.query,
+  });
+
+  if (!result.success) {
+    // Zod v4: use .issues (not .flatten())
+    const errors = result.error.issues.map((i) => ({
+      field:   i.path.join('.'),
+      message: i.message,
+    }));
+    return next(new AppError(errors[0]?.message || 'Validation failed', 422, errors));
+  }
+
+  // Replace with parsed/coerced/defaulted values
+  if (result.data.body)   req.body   = result.data.body;
+  if (result.data.params) req.params = result.data.params;
+  if (result.data.query)  req.query  = result.data.query;
+
+  next();
+};
+```
+
+---
+
+## Schema Structure
+
+Always use `z.object({ body?, params?, query? })` for the validate middleware:
+
+```js
+import { z } from 'zod';
+
+// POST body only
+export const createSchema = z.object({
+  body: z.object({ name: z.string().min(1), email: z.string().email() }).strict(),
+});
+
+// Params + body
+export const updateSchema = z.object({
+  params: z.object({ id: z.string().uuid() }),
+  body: z.object({
+    name:  z.string().min(1).optional(),
+    email: z.string().email().optional(),
+  }).strict(),
+});
+
+// Params only
+export const idSchema = z.object({
+  params: z.object({ id: z.string().uuid() }),
+});
+
+// Query only (list / paginate)
+export const listSchema = z.object({
+  query: z.object({
+    page:   z.coerce.number().int().positive().default(1),
+    limit:  z.coerce.number().int().positive().max(100).default(10),
+    search: z.string().optional(),
+  }),
+});
+```
+
+---
+
+## Zod v4 Validator Reference
+
+### Strings
+```js
+z.string().min(1, 'Required').max(255)
+z.string().email()
+z.string().uuid()
+z.string().url()
+z.string().regex(/^\d{6}$/, 'Must be 6 digits')
+z.string().trim().toLowerCase()          // transform on parse
+z.string().nonempty()                    // min(1) shorthand
+```
+
+### Numbers
+```js
+z.number().int().positive()
+z.number().min(0).max(100)
+z.coerce.number().int().positive()       // always use coerce for query params
+```
+
+### Optional / Nullable
+```js
+z.string().optional()    // string | undefined
+z.string().nullable()    // string | null
+z.string().nullish()     // string | null | undefined
+z.string().default('x')  // fallback when undefined
+```
+
+### Enums
+```js
+z.enum(['USER', 'ADMIN', 'MANAGER'])
+```
+
+### Objects
+```js
+z.object({ name: z.string() }).strict()      // fail on unknown keys
+z.object({ name: z.string() }).partial()     // all optional
+z.object({ name: z.string() }).passthrough() // allow extra keys
+```
+
+### Arrays
+```js
+z.array(z.string()).min(1).max(50)
+z.array(z.string().uuid())
+```
+
+### Dates
+```js
+z.coerce.date()                              // "2024-01-01" → Date
+z.date().min(new Date())                     // must be in the future
+```
+
+### Transformations
+```js
+z.string().transform((v) => v.trim().toLowerCase())
+z.preprocess((v) => Number(v), z.number())
+```
+
+### Cross-field validation
+```js
+z.object({
+  password:        z.string().min(8),
+  confirmPassword: z.string(),
+}).refine((d) => d.password === d.confirmPassword, {
+  message: 'Passwords do not match',
+  path:    ['confirmPassword'],
+});
+```
+
+### Zod v4 error format in validate middleware response
+
+```json
+{
+  "success": false,
+  "message": "Invalid email",
+  "errors": [
+    { "field": "body.email", "message": "Invalid email" },
+    { "field": "body.name",  "message": "Name min 2 chars" }
+  ]
+}
+```