@djm204/agent-skills 1.0.0

package/templates/engineering/web-backend/.cursor/rules/database-patterns.mdc

@@ -0,0 +1,73 @@
+---
+description: Database Patterns
+alwaysApply: false
+---
+
+# Database Patterns
+
+Best practices for working with databases in backend applications.
+
+## Core Principles
+
+- Separate database operations from business logic (repository pattern)
+- Use transactions for related operations to maintain consistency
+- Handle connection errors with retry and exponential backoff
+
+## Query Optimization
+
+- **Select only needed fields**: Avoid `SELECT *` in production queries
+- **Use pagination**: Offset-based for simple cases, cursor-based for large datasets
+- **Avoid N+1**: Use joins/includes or batch queries with `WHERE id IN (...)`
+- **Index frequently queried columns**: Composite indexes for common query patterns
+
+```ts
+// Bad: N+1
+for (const post of posts) {
+  post.author = await db.user.findUnique({ where: { id: post.authorId } });
+}
+// Good: Single query
+const posts = await db.post.findMany({ include: { author: true } });
+```
+
+## Migrations
+
+- Version-control all migrations sequentially
+- Write reversible migrations (up + down)
+- Test in staging before production
+- Consider zero-downtime migrations for large tables
+
+## Connection Pooling
+
+- Match pool size to expected concurrency
+- Set idle and connection timeouts
+- Handle pool exhaustion with query timeouts
+
+## Data Integrity
+
+```sql
+-- Use constraints
+PRIMARY KEY (id)
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+UNIQUE (email)
+CHECK (price >= 0)
+
+-- Use appropriate types
+id UUID, email VARCHAR(255), price DECIMAL(10,2), created_at TIMESTAMPTZ
+```
+
+## Soft Deletes
+
+When needed, add `deletedAt` column and filter with `WHERE deletedAt IS NULL`. Be consistent across queries.
+
+## Security
+
+- **Always parameterized queries**: Never interpolate user input into SQL
+- **Encrypt sensitive data at rest**: SSN, tokens, PII
+- **Audit logging**: Track changes for sensitive operations with userId, action, timestamp
+
+```ts
+// Good
+await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+// Bad: SQL injection
+await db.query(`SELECT * FROM users WHERE id = '${userId}'`);
+```

package/templates/engineering/web-backend/.cursor/rules/error-handling.mdc

@@ -0,0 +1,66 @@
+---
+description: Error Handling
+alwaysApply: false
+---
+
+# Error Handling
+
+Best practices for handling errors in backend applications.
+
+## Principles
+
+- **Fail fast**: Detect errors early with clear diagnostics
+- **Fail gracefully**: Users get helpful messages, not stack traces
+- **Log with context**: Errors need requestId, userId, path for debugging
+- **Recover when possible**: Retry transient failures with exponential backoff
+
+## Custom Error Classes
+
+```ts
+class AppError extends Error {
+  constructor(public statusCode: number, public code: string,
+    message: string, public details?: unknown) { super(message); }
+}
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(404, 'NOT_FOUND', `${resource} ${id} not found`); }
+}
+```
+
+Extend for ValidationError (422), UnauthorizedError (401), ForbiddenError (403), ConflictError (409).
+
+## Result Types
+
+```ts
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+Use for explicit error handling without exceptions in service layers.
+
+## Global Error Handler
+
+- Log error with context (message, stack, requestId, method, path, userId)
+- Return structured `{error: {code, message, details?}}` for AppError subclasses
+- Return generic 500 for unknown errors — never leak stack traces
+
+## Async Error Handling
+
+Wrap async handlers to forward rejections to error middleware:
+
+```ts
+const asyncHandler = (fn) => (req, res, next) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+```
+
+## Logging Rules
+
+- **Log**: Error message, stack, requestId, userId, resource context
+- **Never log**: Passwords, API keys, tokens, credit cards, PII
+
+## Anti-Patterns
+
+**Swallowing errors**: Empty `catch` blocks. Always log or rethrow.
+
+**Leaking internals**: Returning `error.stack` to client. Use generic messages + requestId.
+
+**Catching too broadly**: One catch for validation + DB + unknown errors. Catch specific types; let unknown errors bubble up.

package/templates/engineering/web-backend/.cursor/rules/overview.mdc

@@ -0,0 +1,74 @@
+---
+description: Web Backend Development
+alwaysApply: false
+---
+
+# Web Backend Development
+
+Guidelines for building robust backend APIs and services.
+
+## Scope
+
+This ruleset applies to:
+- RESTful APIs
+- GraphQL APIs
+- Microservices
+- Backend-for-frontend (BFF) services
+- Server-side web applications
+
+## Core Technologies
+
+Backend development typically involves:
+- Server frameworks (Express, Fastify, Koa, Hono, etc.)
+- Database systems (PostgreSQL, MySQL, MongoDB, Redis, etc.)
+- Authentication/Authorization (JWT, OAuth, sessions)
+- API documentation (OpenAPI/Swagger)
+- Testing frameworks
+
+## Key Principles
+
+### 1. Security First
+Every input is hostile until validated. Defense in depth.
+
+### 2. Reliability
+Handle errors gracefully. Fail fast with clear diagnostics.
+
+### 3. Observability
+Log meaningfully. Track metrics. Enable debugging.
+
+### 4. Scalability
+Design for horizontal scaling. Avoid single points of failure.
+
+## Project Structure
+
+```
+src/
+├── routes/           # Route handlers/controllers
+├── services/         # Business logic
+├── repositories/     # Data access layer
+├── middleware/       # Request/response middleware
+├── lib/              # Shared utilities
+├── types/            # TypeScript definitions
+├── validation/       # Input validation schemas
+└── config/           # Configuration management
+```
+
+## API Design Principles
+
+- Use consistent naming conventions
+- Return appropriate HTTP status codes
+- Provide meaningful error messages
+- Version your APIs
+- Document endpoints thoroughly
+
+## Definition of Done
+
+A backend feature is complete when:
+- [ ] Endpoint works as specified
+- [ ] Input validation implemented
+- [ ] Error handling covers edge cases
+- [ ] Authentication/authorization enforced
+- [ ] Unit and integration tests passing
+- [ ] API documentation updated
+- [ ] No security vulnerabilities
+- [ ] Logging in place for debugging

package/templates/engineering/web-backend/.cursor/rules/security.mdc

@@ -0,0 +1,60 @@
+---
+description: Backend Security
+alwaysApply: false
+---
+
+# Backend Security
+
+Security best practices specific to backend API development.
+
+## Input Validation
+
+- Validate all external input at the boundary with strict schemas (Zod, Joi)
+- Reject invalid input with 422 and structured error details
+- Sanitize HTML content before storage (DOMPurify)
+- Strip sensitive fields (passwordHash, tokens) before returning responses
+
+## Injection Prevention
+
+```ts
+// SQL: Always parameterized
+await db.query('SELECT * FROM users WHERE email = $1', [email]);
+// Command: Use execFile with array args
+execFile('convert', [inputPath, '-resize', '800x600', outputPath]);
+// NoSQL: Validate input types to prevent $gt/$ne injection
+```
+
+Never use string interpolation for queries or shell commands.
+
+## Rate Limiting
+
+- General API: 100 req/min per IP
+- Auth endpoints: 5 attempts per 15min, skip successful requests
+- Per-user limits for expensive operations via Redis counters
+
+## Security Headers
+
+- Use helmet for CSP, HSTS, referrer policy
+- Configure CORS with explicit allowed origins, credentials, methods
+- Limit request body size (`express.json({ limit: '1mb' })`)
+- Reject unexpected Content-Types with 415
+
+## Secrets Management
+
+- Validate env vars at startup with schema (Zod)
+- Never log secrets — log host only, not full connection strings
+- Support secret rotation: accept both old and new secrets during transition
+
+## Audit Logging
+
+Log security events: login attempts (success/failure), permission changes, resource access. Include userId, IP, userAgent, action, timestamp.
+
+## Security Checklist
+
+- [ ] All inputs validated with strict schemas
+- [ ] Parameterized queries everywhere
+- [ ] Rate limiting on all endpoints
+- [ ] Auth + authorization on protected routes
+- [ ] Security headers configured (HSTS, CSP, CORS)
+- [ ] Secrets not in code or logs
+- [ ] Error messages don't leak internals

package/templates/engineering/web-backend/.cursor/rules/testing.mdc

@@ -0,0 +1,74 @@
+---
+description: Backend Testing
+alwaysApply: false
+---
+
+# Backend Testing
+
+Guidelines for testing backend applications effectively.
+
+## Testing Pyramid
+
+1. **Unit Tests** — Fast, isolated, test business logic and utilities
+2. **Integration Tests** — Test with real database, repository layer
+3. **API Tests** — Full HTTP request/response cycle with supertest
+
+## Unit Tests
+
+```ts
+describe('calculateDiscount', () => {
+  it('applies percentage', () => {
+    expect(calculateDiscount(100, { type: 'percentage', value: 10 })).toBe(90);
+  });
+  it('does not go below zero', () => {
+    expect(calculateDiscount(10, { type: 'fixed', value: 20 })).toBe(0);
+  });
+});
+```
+
+## Integration Tests
+
+```ts
+describe('userRepository', () => {
+  beforeEach(() => db.user.deleteMany());
+  it('creates user', async () => {
+    const user = await userRepository.create({ email: 'a@b.com', name: 'Test' });
+    expect(user.id).toBeDefined();
+  });
+  it('throws on duplicate email', async () => {
+    await userRepository.create({ email: 'a@b.com', name: 'U1' });
+    await expect(userRepository.create({ email: 'a@b.com', name: 'U2' })).rejects.toThrow();
+  });
+});
+```
+
+## API Tests
+
+```ts
+it('creates user', async () => {
+  const res = await request(app).post('/users')
+    .set('Authorization', `Bearer ${token}`)
+    .send({ email: 'new@test.com', name: 'New' });
+  expect(res.status).toBe(201);
+});
+it('validates email', async () => {
+  const res = await request(app).post('/users')
+    .set('Authorization', `Bearer ${token}`)
+    .send({ email: 'invalid', name: 'Test' });
+  expect(res.status).toBe(422);
+});
+```
+
+## Mocking
+
+- Mock external services (email, payment) with `vi.mock()`
+- Mock database only for unit-testing service logic; use real DB for integration
+- Use factories with `@faker-js/faker` for test data
+
+## Best Practices
+
+- **Test behavior, not implementation**: Assert on persisted data, not `repo.save` calls
+- **One assertion per concept**: Separate tests for auth, validation, success cases
+- **Descriptive names**: `creates order when cart is valid`, `returns 409 when out of stock`
+- **Co-locate tests**: `userService.test.ts` next to `userService.ts`
+- **Clean state**: Truncate tables in `beforeEach`, use test database

package/templates/engineering/web-backend/CLAUDE.md

@@ -0,0 +1,366 @@
+# Web Backend Development Guide
+
+Comprehensive guidelines for building robust backend APIs and services.
+
+---
+
+## Overview
+
+This guide applies to:
+- RESTful APIs
+- GraphQL APIs
+- Microservices
+- Backend-for-frontend (BFF) services
+
+### Key Principles
+
+1. **Security First** - Every input is hostile until validated
+2. **Reliability** - Handle errors gracefully, fail fast
+3. **Observability** - Log meaningfully, track metrics
+4. **Scalability** - Design for horizontal scaling
+
+### Project Structure
+
+```
+src/
+├── routes/           # Route handlers/controllers
+├── services/         # Business logic
+├── repositories/     # Data access layer
+├── middleware/       # Request/response middleware
+├── lib/              # Shared utilities
+├── types/            # TypeScript definitions
+├── validation/       # Input validation schemas
+└── config/           # Configuration management
+```
+
+---
+
+## API Design
+
+### RESTful Conventions
+
+```
+GET    /users           # List users
+POST   /users           # Create user
+GET    /users/:id       # Get user
+PUT    /users/:id       # Update user
+DELETE /users/:id       # Delete user
+GET    /users/:id/posts # Get user's posts
+```
+
+### HTTP Status Codes
+
+**Success**: 200 OK, 201 Created, 204 No Content
+**Client Errors**: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Error, 429 Rate Limited
+**Server Errors**: 500 Internal Error, 502 Bad Gateway, 503 Service Unavailable
+
+### Response Format
+
+```json
+// Success
+{ "data": { "id": "123", "name": "John" } }
+
+// Error
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [{ "field": "email", "message": "Invalid format" }]
+  }
+}
+
+// Collection
+{
+  "data": [...],
+  "pagination": { "page": 1, "limit": 20, "total": 150 }
+}
+```
+
+### Query Parameters
+
+- **Filtering**: `?role=admin&status=active`
+- **Sorting**: `?sort=-createdAt` (prefix `-` for descending)
+- **Pagination**: `?page=2&limit=20` or `?cursor=xyz&limit=20`
+- **Fields**: `?fields=id,name,email`
+
+---
+
+## Database Patterns
+
+### Data Access Layer
+
+```ts
+// repository/userRepository.ts
+export const userRepository = {
+  async findById(id: string): Promise<User | null> {
+    return db.user.findUnique({ where: { id } });
+  },
+  async create(data: CreateUserInput): Promise<User> {
+    return db.user.create({ data });
+  },
+};
+```
+
+### Transactions
+
+```ts
+await db.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.update({ ... });
+  await tx.payment.create({ ... });
+});
+```
+
+### Avoid N+1 Queries
+
+```ts
+// Bad: N+1
+const posts = await db.post.findMany();
+for (const post of posts) {
+  post.author = await db.user.findUnique({ where: { id: post.authorId } });
+}
+
+// Good: Include
+const posts = await db.post.findMany({ include: { author: true } });
+```
+
+### Use Indexes
+
+```sql
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_posts_user_created ON posts(user_id, created_at);
+```
+
+---
+
+## Authentication & Authorization
+
+### JWT Authentication
+
+```ts
+const generateToken = (user: User): string => {
+  return jwt.sign(
+    { sub: user.id, email: user.email, role: user.role },
+    process.env.JWT_SECRET,
+    { expiresIn: '15m' }
+  );
+};
+```
+
+### Authorization Middleware
+
+```ts
+const requirePermission = (permission: string) => {
+  return (req, res, next) => {
+    const userPermissions = permissions[req.user.role] || [];
+    if (!userPermissions.includes(permission)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  };
+};
+```
+
+### Password Security
+
+- Hash with bcrypt (12+ rounds)
+- Enforce minimum requirements
+- Rate limit login attempts
+
+### Security Best Practices
+
+- Short-lived access tokens + refresh tokens
+- HTTP-only, Secure, SameSite cookies
+- CSRF tokens for session-based auth
+- Never log credentials
+
+---
+
+## Error Handling
+
+### Custom Error Classes
+
+```ts
+class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string,
+    public details?: unknown
+  ) {
+    super(message);
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, details?: ValidationDetail[]) {
+    super(422, 'VALIDATION_ERROR', message, details);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(404, 'NOT_FOUND', `${resource} with id ${id} not found`);
+  }
+}
+```
+
+### Global Error Handler
+
+```ts
+const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
+  logger.error({ error: err.message, stack: err.stack, requestId: req.id });
+
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message, details: err.details },
+    });
+  }
+
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
+  });
+};
+```
+
+### Result Types
+
+```ts
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+const findUser = async (id: string): Promise<Result<User, NotFoundError>> => {
+  const user = await db.user.findUnique({ where: { id } });
+  return user ? { ok: true, value: user } : { ok: false, error: new NotFoundError('User', id) };
+};
+```
+
+---
+
+## Security
+
+### Input Validation
+
+```ts
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+
+const result = CreateUserSchema.safeParse(req.body);
+if (!result.success) {
+  return res.status(422).json({ error: { details: result.error.errors } });
+}
+```
+
+### Injection Prevention
+
+```ts
+// SQL: Always use parameterized queries
+const users = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+
+// Command: Use execFile with array arguments
+execFile('convert', [inputPath, '-resize', '800x600', outputPath]);
+```
+
+### Rate Limiting
+
+```ts
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5,
+  message: { error: 'Too many attempts' },
+});
+
+app.post('/login', authLimiter, loginHandler);
+```
+
+### Security Headers
+
+```ts
+app.use(helmet({
+  contentSecurityPolicy: { ... },
+  hsts: { maxAge: 31536000, includeSubDomains: true },
+}));
+```
+
+### Security Checklist
+
+- [ ] All inputs validated
+- [ ] Parameterized queries
+- [ ] Rate limiting in place
+- [ ] Auth required on protected routes
+- [ ] Security headers configured
+- [ ] Secrets not in code or logs
+- [ ] HTTPS enforced
+- [ ] Dependencies audited
+
+---
+
+## Testing
+
+### Unit Tests
+
+```ts
+describe('calculateDiscount', () => {
+  it('applies percentage discount', () => {
+    expect(calculateDiscount(100, { type: 'percentage', value: 10 })).toBe(90);
+  });
+});
+```
+
+### Integration Tests
+
+```ts
+describe('userRepository', () => {
+  beforeEach(async () => await db.user.deleteMany());
+
+  it('creates a user', async () => {
+    const user = await userRepository.create({ email: 'test@example.com', name: 'Test' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+### API Tests
+
+```ts
+describe('POST /users', () => {
+  it('creates a new user', async () => {
+    const response = await request(app)
+      .post('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ email: 'new@test.com', name: 'New User' });
+
+    expect(response.status).toBe(201);
+    expect(response.body.data.email).toBe('new@test.com');
+  });
+
+  it('validates email format', async () => {
+    const response = await request(app)
+      .post('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ email: 'invalid', name: 'Test' });
+
+    expect(response.status).toBe(422);
+  });
+});
+```
+
+---
+
+## Definition of Done
+
+A backend feature is complete when:
+
+- [ ] Endpoint works as specified
+- [ ] Input validation implemented
+- [ ] Error handling covers edge cases
+- [ ] Authentication/authorization enforced
+- [ ] Unit and integration tests passing
+- [ ] API documentation updated
+- [ ] No security vulnerabilities
+- [ ] Logging in place for debugging
+- [ ] Code reviewed and approved