@devmunna/agent-skillkit 0.1.0

package/skills/fastify-rest/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: fastify-rest
+version: 1.0.0
+description: >
+  Apply this skill for any Fastify project task: server setup, route declaration, schema validation, plugins, hooks, authentication, error handling, or performance optimization. Triggers: "Fastify server", "Fastify route", "Fastify plugin", "Fastify schema", "Fastify hooks", "Fastify JWT", "register plugin".
+stack: [fastify]
+depends: [node-base]
+---
+
+# Fastify REST API Skill
+
+Production-ready Fastify patterns: plugin architecture, JSON schema validation, hooks, and performance-first design.
+
+---
+
+## Project Structure
+
+```
+src/
+├── app.js              # Fastify instance builder (no listen)
+├── server.js           # Entry point (listen here)
+├── config/
+│   └── env.js          # Validated env (Zod)
+├── plugins/
+│   ├── db.js           # Database plugin (Prisma / Mongoose)
+│   ├── auth.js         # JWT plugin
+│   └── sensible.js     # @fastify/sensible
+├── modules/
+│   └── {module}/
+│       ├── {module}.routes.js    # Route declarations
+│       ├── {module}.schema.js    # JSON schemas
+│       ├── {module}.service.js   # Business logic
+│       └── {module}.repository.js
+└── utils/
+    └── AppError.js
+```
+
+---
+
+## Application Bootstrap
+
+```js
+// src/app.js
+import Fastify from 'fastify';
+import { env } from './config/env.js';
+
+export async function buildApp(opts = {}) {
+  const app = Fastify({
+    logger: env.NODE_ENV === 'development'
+      ? { level: 'info', transport: { target: 'pino-pretty' } }
+      : { level: 'warn' },
+    ...opts,
+  });
+
+  // Register plugins
+  await app.register(import('./plugins/db.js'));
+  await app.register(import('./plugins/auth.js'));
+
+  // Register routes with prefix
+  await app.register(import('./modules/user/user.routes.js'), { prefix: '/api/v1/users' });
+  await app.register(import('./modules/auth/auth.routes.js'), { prefix: '/api/v1/auth' });
+
+  // Health check
+  app.get('/health', async () => ({ status: 'ok' }));
+
+  return app;
+}
+
+// src/server.js
+import { buildApp } from './src/app.js';
+import { env } from './src/config/env.js';
+
+const app = await buildApp();
+
+try {
+  await app.listen({ port: env.PORT, host: '0.0.0.0' });
+} catch (err) {
+  app.log.error(err);
+  process.exit(1);
+}
+```
+
+---
+
+## Plugin Registration
+
+```js
+// src/plugins/db.js
+import fp from 'fastify-plugin';
+import { PrismaClient } from '@prisma/client';
+
+async function dbPlugin(app) {
+  const prisma = new PrismaClient({
+    log: app.config.NODE_ENV === 'development' ? ['query', 'warn', 'error'] : ['error'],
+  });
+
+  await prisma.$connect();
+
+  // Decorate app so all routes can use app.prisma
+  app.decorate('prisma', prisma);
+
+  app.addHook('onClose', async () => {
+    await prisma.$disconnect();
+  });
+}
+
+// fp() makes the plugin available app-wide (not scoped)
+export default fp(dbPlugin, { name: 'prisma' });
+```
+
+---
+
+## Route Declaration with JSON Schema
+
+```js
+// src/modules/user/user.routes.js
+import { userService } from './user.service.js';
+import { createUserSchema, getUserSchema, listUsersSchema } from './user.schema.js';
+
+export default async function userRoutes(app) {
+  // List users
+  app.get('/', { schema: listUsersSchema }, async (req, reply) => {
+    const result = await userService.getAll(req.query);
+    return result;
+  });
+
+  // Get user by ID
+  app.get('/:id', { schema: getUserSchema }, async (req, reply) => {
+    const user = await userService.getById(req.params.id);
+    return user;
+  });
+
+  // Create user (protected)
+  app.post('/', {
+    schema: createUserSchema,
+    preHandler: [app.authenticate],  // JWT guard
+  }, async (req, reply) => {
+    const user = await userService.create(req.body);
+    reply.status(201);
+    return user;
+  });
+
+  // Delete user
+  app.delete('/:id', {
+    schema: { params: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } } } },
+    preHandler: [app.authenticate, app.authorize('ADMIN')],
+  }, async (req, reply) => {
+    await userService.delete(req.params.id);
+    reply.status(204).send();
+  });
+}
+```
+
+---
+
+## JSON Schema Validation
+
+```js
+// src/modules/user/user.schema.js
+
+const userResponse = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    name: { type: 'string' },
+    email: { type: 'string', format: 'email' },
+    role: { type: 'string', enum: ['USER', 'ADMIN'] },
+    createdAt: { type: 'string', format: 'date-time' },
+  },
+};
+
+export const createUserSchema = {
+  body: {
+    type: 'object',
+    required: ['name', 'email', 'password'],
+    properties: {
+      name: { type: 'string', minLength: 2, maxLength: 100 },
+      email: { type: 'string', format: 'email' },
+      password: { type: 'string', minLength: 8 },
+    },
+    additionalProperties: false,
+  },
+  response: {
+    201: userResponse,
+  },
+};
+
+export const listUsersSchema = {
+  querystring: {
+    type: 'object',
+    properties: {
+      page: { type: 'integer', minimum: 1, default: 1 },
+      limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
+      search: { type: 'string' },
+    },
+  },
+};
+
+export const getUserSchema = {
+  params: {
+    type: 'object',
+    required: ['id'],
+    properties: {
+      id: { type: 'string', format: 'uuid' },
+    },
+  },
+  response: {
+    200: userResponse,
+  },
+};
+```
+
+---
+
+## JWT Authentication Plugin
+
+```js
+// src/plugins/auth.js
+import fp from 'fastify-plugin';
+import jwt from '@fastify/jwt';
+import { env } from '../config/env.js';
+
+async function authPlugin(app) {
+  await app.register(jwt, { secret: env.JWT_SECRET });
+
+  // Decorate with authenticate hook
+  app.decorate('authenticate', async function (req, reply) {
+    try {
+      await req.jwtVerify();
+    } catch {
+      reply.status(401).send({ error: 'Unauthorized' });
+    }
+  });
+
+  // Role-based authorization
+  app.decorate('authorize', (role) => async function (req, reply) {
+    if (req.user.role !== role) {
+      reply.status(403).send({ error: 'Forbidden' });
+    }
+  });
+}
+
+export default fp(authPlugin, { name: 'auth' });
+```
+
+---
+
+## Error Handling
+
+```js
+// In app.js — global error handler
+app.setErrorHandler(async (error, req, reply) => {
+  const statusCode = error.statusCode ?? 500;
+
+  if (statusCode >= 500) {
+    app.log.error(error);
+    return reply.status(500).send({ success: false, message: 'Internal server error' });
+  }
+
+  return reply.status(statusCode).send({
+    success: false,
+    message: error.message,
+    ...(error.validation && { validation: error.validation }),
+  });
+});
+
+// In routes — throw to trigger error handler
+app.get('/example', async (req, reply) => {
+  const item = await service.getById(req.params.id);
+  if (!item) {
+    const err = new Error('Not found');
+    err.statusCode = 404;
+    throw err;
+  }
+  return item;
+});
+```
+
+---
+
+## Performance Rules
+
+- Define `response` JSON schemas to activate fast serialization (ajv-compiler bypasses JSON.stringify)
+- Use `app.log` (pino) — never `console.log` in handlers
+- Use `async/await` in handlers and plugins — Fastify handles the promise lifecycle
+- Register all plugins with `fastify-plugin` (`fp`) if they should be available in all scopes
+- Use `onRequest` hook for auth guards over route-level `preHandler` when applying globally

package/skills/mongoose-odm/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: mongoose-odm
+version: 1.0.0
+description: >
+  Apply this skill for any MongoDB/Mongoose task: schema design, model creation, virtuals, indexes, population, aggregation, transactions, or repository abstraction. Triggers: "Mongoose schema", "MongoDB model", "populate relations", "aggregation pipeline", "MongoDB index", "Mongoose middleware", "MongoDB transaction".
+stack: [mongoose, mongodb]
+depends: []
+---
+
+# Mongoose ODM Skill
+
+Production patterns for MongoDB/Mongoose: schema design, repository abstraction, performance, and transactions.
+
+---
+
+## Installation
+
+```bash
+npm install mongoose
+```
+
+---
+
+## Connection
+
+```js
+// src/config/db.js
+import mongoose from 'mongoose';
+import { env } from './env.js';
+
+let isConnected = false;
+
+export async function connectDB() {
+  if (isConnected) return;
+
+  mongoose.set('strictQuery', true);
+
+  await mongoose.connect(env.MONGODB_URI, {
+    dbName: env.DB_NAME,
+  });
+
+  isConnected = true;
+  console.log('✅ MongoDB connected');
+}
+
+// Handle connection events
+mongoose.connection.on('error', (err) => console.error('MongoDB error:', err));
+mongoose.connection.on('disconnected', () => { isConnected = false; });
+```
+
+---
+
+## Schema Design Conventions
+
+```js
+// src/modules/user/user.model.js
+import mongoose from 'mongoose';
+import bcrypt from 'bcryptjs';
+
+const userSchema = new mongoose.Schema(
+  {
+    name: {
+      type: String,
+      required: [true, 'Name is required'],
+      trim: true,
+      maxlength: [100, 'Name max 100 characters'],
+    },
+    email: {
+      type: String,
+      required: [true, 'Email is required'],
+      unique: true,
+      lowercase: true,
+      trim: true,
+      match: [/^\S+@\S+\.\S+$/, 'Invalid email format'],
+    },
+    password: {
+      type: String,
+      required: true,
+      minlength: 8,
+      select: false, // never returned by default
+    },
+    role: {
+      type: String,
+      enum: ['user', 'admin', 'moderator'],
+      default: 'user',
+    },
+    isActive: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  {
+    timestamps: true,             // adds createdAt + updatedAt automatically
+    versionKey: false,            // removes __v field
+    toJSON: { virtuals: true },   // include virtuals in JSON output
+    toObject: { virtuals: true },
+  }
+);
+
+// Index on frequently queried fields
+userSchema.index({ email: 1 });
+userSchema.index({ role: 1, isActive: 1 });
+
+// Virtual: computed property (not stored in DB)
+userSchema.virtual('fullName').get(function () {
+  return `${this.firstName} ${this.lastName}`;
+});
+
+// Pre-save middleware: hash password
+userSchema.pre('save', async function (next) {
+  if (!this.isModified('password')) return next();
+  this.password = await bcrypt.hash(this.password, 12);
+  next();
+});
+
+// Instance method
+userSchema.methods.comparePassword = async function (candidate) {
+  return bcrypt.compare(candidate, this.password);
+};
+
+// Static method
+userSchema.statics.findByEmail = function (email) {
+  return this.findOne({ email: email.toLowerCase() });
+};
+
+export const User = mongoose.model('User', userSchema);
+```
+
+---
+
+## Repository Pattern
+
+```js
+// src/modules/user/user.repository.js
+import { User } from './user.model.js';
+import { AppError } from '../../utils/AppError.js';
+
+export const userRepository = {
+  async findAll({ page = 1, limit = 10, search, role }) {
+    const query = {};
+    if (search) query.$text = { $search: search };
+    if (role) query.role = role;
+
+    const skip = (page - 1) * limit;
+
+    const [data, total] = await Promise.all([
+      User.find(query)
+        .select('-password')
+        .skip(skip)
+        .limit(limit)
+        .lean(),                    // lean() returns plain objects — faster
+      User.countDocuments(query),
+    ]);
+
+    return { data, total, page, limit };
+  },
+
+  async findById(id) {
+    const user = await User.findById(id).select('-password').lean();
+    if (!user) throw new AppError('User not found', 404);
+    return user;
+  },
+
+  async create(data) {
+    const user = await User.create(data);
+    const { password, ...safe } = user.toObject();
+    return safe;
+  },
+
+  async update(id, data) {
+    const user = await User.findByIdAndUpdate(id, data, {
+      new: true,          // return updated document
+      runValidators: true, // run schema validators on update
+    }).select('-password');
+    if (!user) throw new AppError('User not found', 404);
+    return user;
+  },
+
+  async delete(id) {
+    const user = await User.findByIdAndDelete(id);
+    if (!user) throw new AppError('User not found', 404);
+    return user;
+  },
+};
+```
+
+---
+
+## Population (Relations)
+
+```js
+// Reference (like FK)
+const postSchema = new Schema({
+  author: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
+  tags: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Tag' }],
+});
+
+// Populate at query time
+const posts = await Post.find()
+  .populate('author', 'name email')         // select specific fields
+  .populate('tags', 'name slug')
+  .lean();
+
+// Nested population
+await Post.find().populate({
+  path: 'author',
+  select: 'name',
+  populate: { path: 'profile', select: 'avatar' },
+});
+```
+
+**Rule**: Use `.lean()` with population when you don't need Mongoose document methods. It's 3-10x faster.
+
+---
+
+## Aggregation Pipeline
+
+```js
+// Complex reporting query
+const stats = await Order.aggregate([
+  { $match: { status: 'completed', createdAt: { $gte: startDate } } },
+  {
+    $group: {
+      _id: '$userId',
+      totalOrders: { $sum: 1 },
+      totalRevenue: { $sum: '$total' },
+      avgOrderValue: { $avg: '$total' },
+    },
+  },
+  { $sort: { totalRevenue: -1 } },
+  { $limit: 10 },
+  {
+    $lookup: {
+      from: 'users',
+      localField: '_id',
+      foreignField: '_id',
+      as: 'user',
+      pipeline: [{ $project: { name: 1, email: 1 } }],
+    },
+  },
+  { $unwind: '$user' },
+]);
+```
+
+---
+
+## Transactions
+
+```js
+const session = await mongoose.startSession();
+
+try {
+  session.startTransaction();
+
+  const order = await Order.create([orderData], { session });
+  await Product.findByIdAndUpdate(
+    productId,
+    { $inc: { stock: -quantity } },
+    { session, new: true, runValidators: true }
+  );
+
+  await session.commitTransaction();
+  return order[0];
+} catch (err) {
+  await session.abortTransaction();
+  throw err;
+} finally {
+  session.endSession();
+}
+```
+
+---
+
+## Rules
+
+- Always use `timestamps: true` and `versionKey: false` in schema options
+- Use `select: false` on sensitive fields (password, tokens)
+- Add `lean()` to read-heavy queries not needing Mongoose methods
+- Index all fields used in `find()`, `sort()`, and `$lookup` foreign keys
+- Use `runValidators: true` on `findByIdAndUpdate` — it's off by default
+- Prefer aggregation over application-level data processing for large datasets