@devmunna/agent-skillkit 0.1.0

package/skills/express-mvc-prisma/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: express-mvc-prisma
+version: 2.0.0
+description: >
+  Use this skill for any Express.js backend task: project setup, new module, route/controller/service/validation, Prisma queries, error handling, auth, middleware, or API design. Triggers: "Express API", "add a module", "create CRUD", "validate request", "set up Prisma", "JWT auth", "error handling", "Express folder structure". Always enforce the 4-file module structure and all patterns below — even when the user only asks for a single file.
+stack: [express, prisma, postgresql, zod, jwt]
+depends: [node-base]
+---
+
+# Express + Prisma + Zod — Production Skill
+
+**Version target:** Express v5 · Prisma v5 · Zod v4 · Node.js 20+ (ESM)
+
+---
+
+## Tech Stack
+
+| Layer | Package |
+|---|---|
+| Framework | express v5 |
+| ORM | @prisma/client v5 |
+| Database | PostgreSQL |
+| Validation | zod v4 |
+| Auth | jsonwebtoken + bcrypt |
+| Security | helmet + cors + express-rate-limit |
+| Logging | morgan (dev) |
+| Config | dotenv + Zod env validation |
+
+---
+
+## Project Structure
+
+```
+src/
+├── config/
+│   ├── db.js              # Prisma singleton
+│   └── env.js             # Zod-validated env vars
+├── middlewares/
+│   ├── auth.middleware.js  # JWT + role guard
+│   ├── validate.middleware.js
+│   └── errorHandler.js    # Global error + 404
+├── modules/               # Every feature = 4 files
+│   └── {module}/
+│       ├── {module}.routes.js
+│       ├── {module}.controller.js
+│       ├── {module}.service.js
+│       └── {module}.validation.js
+├── utils/
+│   ├── AppError.js        # Operational error class
+│   └── response.js        # sendSuccess / sendError
+├── routes/
+│   └── index.js           # Mounts all module routers
+└── app.js                 # Express app (no listen)
+server.js                  # Entry: connect DB → listen
+```
+
+---
+
+## Module Pattern — 4 Files (strict)
+
+Every feature module has exactly 4 files. No more, no less.
+
+```
+modules/{module}/
+├── {module}.routes.js       # Router + middleware chain
+├── {module}.controller.js   # HTTP only — call service, send response
+├── {module}.service.js      # Business logic + Prisma calls
+└── {module}.validation.js   # Zod schemas for body / params / query
+```
+
+**Rules:**
+- Controllers are HTTP adapters only — no business logic, no Prisma imports
+- Services contain all business logic and all Prisma calls
+- Services throw `new AppError(message, statusCode)` — never `res.json` from service
+- **Express v5**: async errors in route handlers are forwarded automatically — no `catchAsync` or `try/catch` needed in controllers
+- Validation schemas live in `*.validation.js` — imported by routes
+
+See `references/module-scaffold.md` for the complete 4-file template.
+
+---
+
+## Express v5 — Key Change
+
+> Express 5 natively handles rejected async route handlers. Do not wrap controllers in `catchAsync` or `try/catch`. Throw errors from services; the global error handler catches them.
+
+```js
+// Express v5 — async errors auto-forwarded to errorHandler
+export const getById = async (req, res) => {
+  const user = await userService.getById(req.params.id); // throws AppError if not found
+  sendSuccess(res, 'User fetched', user);
+};
+// No try/catch. No catchAsync. Express v5 handles it.
+```
+
+---
+
+## Error Flow
+
+```
+Service throws AppError  →  Controller throws (auto, Express v5)  →  errorHandler middleware
+Prisma error             →  errorHandler maps P2002 / P2025
+JWT error                →  errorHandler maps JsonWebTokenError / TokenExpiredError
+Zod error (fallback)     →  errorHandler maps ZodError
+```
+
+See `references/error-handling.md`.
+
+---
+
+## Response Helpers — `src/utils/response.js`
+
+```js
+sendSuccess(res, message, data?, statusCode = 200)
+sendError(res, message, statusCode = 500)   // used by errorHandler only
+```
+
+Pagination is auto-detected: if `data` has `{ data, total, page, limit }` shape, `meta` block is added.
+
+See `references/response-helpers.md`.
+
+---
+
+## Validation — Zod v4
+
+Schemas in `{module}.validation.js`. Validate body + params + query in one call.
+Error accessor in v4: `result.error.issues` (not `.flatten()`).
+
+```js
+// validate middleware wraps schema per request segment
+validate(createUserSchema)   // validates body, params, query from schema shape
+```
+
+See `references/zod-validation.md`.
+
+---
+
+## Authentication
+
+JWT Bearer token. Auth middleware sets `req.user`.
+Role guard: `requireRole('ADMIN')` middleware.
+
+See `references/auth.md`.
+
+---
+
+## Prisma Conventions
+
+- UUID primary keys (`@default(uuid())`)
+- `createdAt` + `updatedAt` on every model
+- `@@map("snake_case_table")` on every model
+- `@@index([foreignKey])` on every FK
+- Catch `PrismaClientKnownRequestError` in **service layer** (not controller, not global handler)
+
+See `references/prisma-setup.md`.
+
+---
+
+## Core References
+
+| Topic | File |
+|---|---|
+| Module scaffold (4-file template) | `references/module-scaffold.md` |
+| Boilerplate (app.js, server.js, env, db) | `references/boilerplate.md` |
+| Error handling (AppError, global handler) | `references/error-handling.md` |
+| Auth (JWT middleware, auth module) | `references/auth.md` |
+| Zod v4 validation patterns | `references/zod-validation.md` |
+| Response helpers + pagination | `references/response-helpers.md` |
+| Prisma schema, migrations, queries | `references/prisma-setup.md` |

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

@@ -0,0 +1,190 @@
+# Auth Reference
+
+JWT Bearer token auth. Authenticate middleware sets `req.user`. Role guard protects routes.
+
+---
+
+## src/middlewares/auth.middleware.js
+
+```js
+import jwt          from 'jsonwebtoken';
+import { env }      from '../config/env.js';
+import prisma       from '../config/db.js';
+import { AppError } from '../utils/AppError.js';
+
+export const authenticate = async (req, res, next) => {
+  const header = req.headers.authorization;
+  const token  = header?.startsWith('Bearer ') ? header.split(' ')[1] : null;
+
+  if (!token) return next(new AppError('No token provided', 401));
+
+  const payload = jwt.verify(token, env.JWT_SECRET); // throws → caught by errorHandler
+
+  const user = await prisma.user.findUnique({
+    where:  { id: payload.sub },
+    select: { id: true, name: true, email: true, role: true, status: true },
+  });
+
+  if (!user || user.status !== 'ACTIVE') {
+    return next(new AppError('Account not found or inactive', 401));
+  }
+
+  req.user = user;
+  next();
+};
+
+// Role-based guard — use after authenticate
+export const requireRole = (...roles) => (req, res, next) => {
+  if (!roles.includes(req.user.role)) {
+    return next(new AppError('Insufficient permissions', 403));
+  }
+  next();
+};
+```
+
+Usage in routes:
+```js
+router.delete('/:id', authenticate, requireRole('ADMIN'), controller.remove);
+router.patch('/:id',  authenticate, requireRole('ADMIN', 'MANAGER'), controller.update);
+```
+
+---
+
+## Auth Module — 4 Files
+
+### auth.validation.js
+
+```js
+import { z } from 'zod';
+
+export const registerSchema = z.object({
+  body: z.object({
+    name:     z.string().min(2).max(100),
+    email:    z.string().email(),
+    password: z.string().min(8, 'Password must be ≥8 characters'),
+  }).strict(),
+});
+
+export const loginSchema = z.object({
+  body: z.object({
+    email:    z.string().email(),
+    password: z.string().min(1),
+  }).strict(),
+});
+```
+
+### auth.service.js
+
+```js
+import bcrypt from 'bcrypt';
+import jwt    from 'jsonwebtoken';
+import prisma from '../../config/db.js';
+import { env }      from '../../config/env.js';
+import { AppError } from '../../utils/AppError.js';
+
+const signToken = (userId) =>
+  jwt.sign({ sub: userId }, env.JWT_SECRET, { expiresIn: env.JWT_EXPIRES_IN });
+
+export const authService = {
+
+  async register({ name, email, password }) {
+    const exists = await prisma.user.findUnique({ where: { email } });
+    if (exists) throw new AppError('Email already registered', 409);
+
+    const passwordHash = await bcrypt.hash(password, 12);
+
+    const user = await prisma.user.create({
+      data:   { name, email, password: passwordHash },
+      select: { id: true, name: true, email: true, role: true, createdAt: true },
+    });
+
+    const token = signToken(user.id);
+    return { user, token };
+  },
+
+  async login({ email, password }) {
+    const user = await prisma.user.findUnique({ where: { email } });
+    if (!user) throw new AppError('Invalid credentials', 401);
+
+    const valid = await bcrypt.compare(password, user.password);
+    if (!valid) throw new AppError('Invalid credentials', 401);
+
+    const { password: _, ...safeUser } = user;
+    const token = signToken(safeUser.id);
+    return { user: safeUser, token };
+  },
+
+  async me(userId) {
+    const user = await prisma.user.findUnique({
+      where:  { id: userId },
+      select: { id: true, name: true, email: true, role: true, createdAt: true },
+    });
+    if (!user) throw new AppError('User not found', 404);
+    return user;
+  },
+};
+```
+
+### auth.controller.js
+
+```js
+import { authService } from './auth.service.js';
+import { sendSuccess } from '../../utils/response.js';
+
+export const authController = {
+  register: async (req, res) => {
+    const result = await authService.register(req.body);
+    sendSuccess(res, 'Registered successfully', result, 201);
+  },
+
+  login: async (req, res) => {
+    const result = await authService.login(req.body);
+    sendSuccess(res, 'Login successful', result);
+  },
+
+  me: async (req, res) => {
+    const user = await authService.me(req.user.id);
+    sendSuccess(res, 'Profile fetched', user);
+  },
+};
+```
+
+### auth.routes.js
+
+```js
+import { Router }      from 'express';
+import { validate }    from '../../middlewares/validate.middleware.js';
+import { authenticate } from '../../middlewares/auth.middleware.js';
+import { registerSchema, loginSchema } from './auth.validation.js';
+import { authController } from './auth.controller.js';
+
+const router = Router();
+
+router.post('/register', validate(registerSchema), authController.register);
+router.post('/login',    validate(loginSchema),    authController.login);
+router.get('/me',        authenticate,             authController.me);
+
+export default router;
+```
+
+---
+
+## Prisma User Model (minimum)
+
+```prisma
+model User {
+  id        String   @id @default(uuid())
+  name      String
+  email     String   @unique
+  password  String
+  role      Role     @default(USER)
+  status    Status   @default(ACTIVE)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("users")
+}
+
+enum Role   { USER ADMIN MANAGER }
+enum Status { ACTIVE SUSPENDED DELETED }
+```

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

@@ -0,0 +1,196 @@
+# Boilerplate Reference
+
+Express v5 project setup — app.js, server.js, env validation, Prisma singleton.
+
+---
+
+## package.json
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev":     "nodemon src/server.js",
+    "start":   "node src/server.js",
+    "migrate": "prisma migrate dev",
+    "studio":  "prisma studio",
+    "seed":    "node prisma/seed.js"
+  },
+  "dependencies": {
+    "@prisma/client":    "^5.0.0",
+    "bcrypt":            "^6.0.0",
+    "cors":              "^2.8.5",
+    "dotenv":            "^16.0.0",
+    "express":           "^5.0.0",
+    "express-rate-limit":"^7.0.0",
+    "helmet":            "^8.0.0",
+    "jsonwebtoken":      "^9.0.0",
+    "morgan":            "^1.10.0",
+    "zod":               "^4.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0",
+    "prisma":  "^5.0.0"
+  }
+}
+```
+
+---
+
+## src/config/env.js
+
+Crash at startup if any required variable is missing.
+
+```js
+import { z }        from 'zod';
+import 'dotenv/config';
+
+const schema = z.object({
+  NODE_ENV:       z.enum(['development', 'production', 'test']).default('development'),
+  PORT:           z.coerce.number().default(3000),
+  DATABASE_URL:   z.string().url('DATABASE_URL must be a valid URL'),
+  JWT_SECRET:     z.string().min(32, 'JWT_SECRET must be ≥32 chars'),
+  JWT_EXPIRES_IN: z.string().default('7d'),
+  CORS_ORIGIN:    z.string().default('*'),
+});
+
+const result = schema.safeParse(process.env);
+
+if (!result.success) {
+  console.error('❌ Invalid environment variables:');
+  result.error.issues.forEach((i) => console.error(` • ${i.path.join('.')}: ${i.message}`));
+  process.exit(1);
+}
+
+export const env = result.data;
+export const isDev = env.NODE_ENV === 'development';
+```
+
+---
+
+## src/config/db.js — Prisma singleton
+
+```js
+import { PrismaClient } from '@prisma/client';
+import { isDev }        from './env.js';
+
+const globalForPrisma = globalThis;
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({ log: isDev ? ['query', 'warn', 'error'] : ['error'] });
+
+if (!isDev) globalForPrisma.prisma = prisma;
+
+export default prisma;
+```
+
+---
+
+## src/app.js
+
+```js
+import express        from 'express';
+import helmet         from 'helmet';
+import cors           from 'cors';
+import morgan         from 'morgan';
+import rateLimit      from 'express-rate-limit';
+import { router }     from './routes/index.js';
+import { errorHandler, notFound } from './middlewares/errorHandler.js';
+import { env, isDev } from './config/env.js';
+
+const app = express();
+
+// Security
+app.use(helmet());
+app.use(cors({ origin: env.CORS_ORIGIN, credentials: true }));
+app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100, standardHeaders: true }));
+
+// Parsing
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true }));
+
+// Logging
+if (isDev) app.use(morgan('dev'));
+
+// Health check (no auth required)
+app.get('/health', (req, res) => res.json({ status: 'ok', timestamp: new Date().toISOString() }));
+
+// API routes
+app.use('/api/v1', router);
+
+// Error handling — must be last
+app.use(notFound);
+app.use(errorHandler);
+
+export { app };
+```
+
+---
+
+## server.js
+
+```js
+import { app }    from './src/app.js';
+import { prisma } from './src/config/db.js';
+import { env }    from './src/config/env.js';
+
+const start = async () => {
+  try {
+    await prisma.$connect();
+    console.log('✅ Database connected');
+
+    const server = app.listen(env.PORT, () => {
+      console.log(`🚀 Server running on port ${env.PORT} [${env.NODE_ENV}]`);
+    });
+
+    // Graceful shutdown
+    const shutdown = async (signal) => {
+      console.log(`\n${signal} received — shutting down gracefully`);
+      server.close(async () => {
+        await prisma.$disconnect();
+        console.log('Database disconnected. Bye 👋');
+        process.exit(0);
+      });
+    };
+
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT',  () => shutdown('SIGINT'));
+
+  } catch (err) {
+    console.error('❌ Startup failed:', err);
+    await prisma.$disconnect();
+    process.exit(1);
+  }
+};
+
+start();
+```
+
+---
+
+## src/routes/index.js
+
+```js
+import { Router } from 'express';
+// import userRouter from '../modules/user/user.routes.js';
+// import authRouter from '../modules/auth/auth.routes.js';
+
+export const router = Router();
+
+// router.use('/auth',  authRouter);
+// router.use('/users', userRouter);
+```
+
+---
+
+## .env.example
+
+```
+NODE_ENV=development
+PORT=3000
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+JWT_SECRET=your-super-secret-key-at-least-32-characters-long
+JWT_EXPIRES_IN=7d
+CORS_ORIGIN=http://localhost:5173
+```

package/skills/express-mvc-prisma/references/error-handling.md

@@ -0,0 +1,121 @@
+# Error Handling Reference
+
+Express v5 + AppError pattern. Errors thrown anywhere in async route handlers automatically reach `errorHandler`.
+
+---
+
+## src/utils/AppError.js
+
+```js
+export class AppError extends Error {
+  constructor(message, statusCode = 500, errors = null) {
+    super(message);
+    this.statusCode    = statusCode;
+    this.status        = statusCode >= 400 && statusCode < 500 ? 'fail' : 'error';
+    this.isOperational = true;
+    this.errors        = errors;   // optional: array of { field, message }
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+---
+
+## src/middlewares/errorHandler.js
+
+Handles all error types in one place. Mount last in `app.js`.
+
+```js
+import { AppError } from '../utils/AppError.js';
+import { Prisma }   from '@prisma/client';
+
+export const errorHandler = (err, req, res, next) => {
+  let statusCode = err.statusCode || 500;
+  let message    = err.message    || 'Internal server error';
+  let errors     = err.errors     || null;
+
+  // Prisma known errors
+  if (err instanceof Prisma.PrismaClientKnownRequestError) {
+    switch (err.code) {
+      case 'P2002': statusCode = 409; message = `Duplicate: ${err.meta?.target}`; break;
+      case 'P2025': statusCode = 404; message = 'Record not found';               break;
+      case 'P2003': statusCode = 400; message = 'Related record not found';       break;
+      case 'P2014': statusCode = 400; message = 'Relation constraint failed';     break;
+      default:      statusCode = 500; message = 'Database error';
+    }
+  }
+
+  // JWT errors
+  if (err.name === 'JsonWebTokenError') { statusCode = 401; message = 'Invalid token'; }
+  if (err.name === 'TokenExpiredError') { statusCode = 401; message = 'Token expired. Please log in again'; }
+
+  // Zod error (if validation middleware was bypassed)
+  if (err.name === 'ZodError') {
+    statusCode = 422;
+    message    = 'Validation failed';
+    errors     = err.issues.map((i) => ({ field: i.path.join('.'), message: i.message }));
+  }
+
+  const isDev = process.env.NODE_ENV === 'development';
+
+  res.status(statusCode).json({
+    success: false,
+    message,
+    ...(errors && { errors }),
+    ...(isDev && !err.isOperational && { stack: err.stack }),
+  });
+};
+
+export const notFound = (req, res, next) => {
+  next(new AppError(`Route not found: ${req.method} ${req.originalUrl}`, 404));
+};
+```
+
+---
+
+## src/app.js — Error middleware order
+
+```js
+// Routes
+app.use('/api/v1', router);
+
+// Must come AFTER routes
+app.use(notFound);
+app.use(errorHandler);
+```
+
+---
+
+## Express v5 — Async Error Propagation
+
+Express v5 automatically catches rejected promises from async route handlers.
+**No `catchAsync` / `asyncHandler` wrapper needed.**
+
+```js
+// Service layer — throw for business errors
+export const getById = async (id) => {
+  const item = await prisma.product.findUnique({ where: { id } });
+  if (!item) throw new AppError('Product not found', 404);    // ← propagates automatically
+  return item;
+};
+
+// Controller — no try/catch
+export const getById = async (req, res) => {
+  const item = await productService.getById(req.params.id);  // throws → errorHandler
+  sendSuccess(res, 'Product fetched', item);
+};
+```
+
+---
+
+## Where Each Error Is Thrown
+
+| Location | Pattern |
+|----------|---------|
+| Service — resource not found | `throw new AppError('X not found', 404)` |
+| Service — conflict | `throw new AppError('Already exists', 409)` |
+| Service — business rule | `throw new AppError('Insufficient balance', 400)` |
+| Service — forbidden | `throw new AppError('Cannot perform this action', 403)` |
+| Repository / service — Prisma | catch `PrismaClientKnownRequestError` → `throw new AppError(...)` |
+| Middleware — auth | `return next(new AppError('No token', 401))` |
+| Controller | **Never throw directly** — delegate to service |