clearctx 3.0.0 → 3.1.0

package/skills/nodejs-backend/SKILL.md

@@ -0,0 +1,853 @@
+---
+name: nodejs-backend
+description: Production-grade Node.js/Express.js backend patterns for APIs, middleware, error handling, and operational excellence
+domain: backend
+keywords: [nodejs, express, backend, api, middleware, error-handling, logging, validation]
+version: 1.0.0
+---
+
+# Node.js Backend Expertise
+
+Production-grade patterns for building robust Express.js APIs with operational excellence.
+
+## Worker Context
+
+### Express.js Project Structure
+
+```
+src/
+├── controllers/     # HTTP request handling, response formatting
+├── services/        # Business logic, data orchestration
+├── repositories/    # Data access layer (DB queries)
+├── middleware/      # Cross-cutting concerns
+├── models/          # Data schemas (Zod, Sequelize, Prisma)
+├── utils/           # Helpers, constants
+└── app.js           # Express app setup
+```
+
+**Middleware Execution Order (CRITICAL):**
+```javascript
+// ALWAYS follow this sequence:
+app.use(cors());              // 1. CORS - first to set headers
+app.use(helmet());            // 2. Security headers
+app.use(rateLimit);           // 3. Rate limiting
+app.use(requestIdMiddleware); // 4. Request ID tracking
+app.use(express.json());      // 5. Body parsing
+app.use(authMiddleware);      // 6. Authentication
+// Routes with validation middleware
+app.use('/api', routes);      // 7. Application routes
+app.use(notFoundHandler);     // 8. 404 handler
+app.use(errorHandler);        // 9. Error handler (LAST)
+```
+
+### Centralized Error Handling
+
+**AppError Class (CRITICAL - create this first):**
+```javascript
+// utils/AppError.js
+class AppError extends Error {
+  constructor(message, statusCode, code = 'INTERNAL_ERROR') {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true; // vs programmer errors
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+module.exports = AppError;
+```
+
+**Error Handler Middleware:**
+```javascript
+// middleware/errorHandler.js
+const { logger } = require('../utils/logger');
+
+const errorHandler = (err, req, res, next) => {
+  // Log error with request context
+  logger.error({
+    err,
+    requestId: req.id,
+    method: req.method,
+    path: req.path,
+    userId: req.user?.id
+  });
+
+  // Operational errors (expected)
+  if (err.isOperational) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
+      }
+    });
+  }
+
+  // Programmer errors (unexpected) - don't leak details
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred'
+    }
+  });
+};
+
+module.exports = errorHandler;
+```
+
+**AsyncHandler Wrapper (CRITICAL - use for all async routes):**
+```javascript
+// utils/asyncHandler.js
+const asyncHandler = (fn) => (req, res, next) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+
+module.exports = asyncHandler;
+```
+
+### Middleware Patterns
+
+**Authentication (Bearer Token):**
+```javascript
+// middleware/auth.js
+const AppError = require('../utils/AppError');
+const { verifyToken } = require('../utils/jwt');
+
+const auth = asyncHandler(async (req, res, next) => {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    throw new AppError('Missing or invalid authorization header', 401, 'UNAUTHORIZED');
+  }
+
+  const token = authHeader.substring(7);
+  const payload = verifyToken(token); // throws if invalid
+
+  req.user = payload; // Attach user to request
+  next();
+});
+```
+
+**Request Validation (Zod):**
+```javascript
+// middleware/validate.js
+const { z } = require('zod');
+const AppError = require('../utils/AppError');
+
+const validate = (schema) => (req, res, next) => {
+  try {
+    // Validate body, params, and query
+    const validated = schema.parse({
+      body: req.body,
+      params: req.params,
+      query: req.query
+    });
+
+    // Replace with validated/sanitized data
+    req.body = validated.body || req.body;
+    req.params = validated.params || req.params;
+    req.query = validated.query || req.query;
+
+    next();
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new AppError(
+        'Validation failed',
+        422,
+        'VALIDATION_ERROR',
+        { details: error.errors }
+      );
+    }
+    throw error;
+  }
+};
+
+// Usage in routes:
+const createUserSchema = z.object({
+  body: z.object({
+    email: z.string().email(),
+    password: z.string().min(8),
+    name: z.string().min(1)
+  })
+});
+
+router.post('/users', validate(createUserSchema), createUser);
+```
+
+**Rate Limiting:**
+```javascript
+// middleware/rateLimit.js
+const rateLimit = require('express-rate-limit');
+const RedisStore = require('rate-limit-redis');
+const redis = require('../config/redis');
+
+const limiter = rateLimit({
+  store: new RedisStore({ client: redis }),
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // limit each IP to 100 requests per windowMs
+  message: { error: { code: 'RATE_LIMIT_EXCEEDED', message: 'Too many requests' } },
+  standardHeaders: true,
+  legacyHeaders: false
+});
+```
+
+**Request ID Tracking:**
+```javascript
+// middleware/requestId.js
+const { v4: uuidv4 } = require('uuid');
+
+const requestId = (req, res, next) => {
+  req.id = req.headers['x-request-id'] || uuidv4();
+  res.setHeader('X-Request-ID', req.id);
+  next();
+};
+```
+
+### Request Validation Strategy
+
+**IMPORTANT: Validate at route level, NOT in controllers**
+
+```javascript
+// schemas/user.schema.js
+const { z } = require('zod');
+
+const createUserSchema = z.object({
+  body: z.object({
+    email: z.string().email().toLowerCase(), // Sanitize
+    password: z.string().min(8).max(128),
+    name: z.string().min(1).max(100).trim()
+  })
+});
+
+const updateUserSchema = z.object({
+  params: z.object({
+    id: z.string().uuid()
+  }),
+  body: z.object({
+    name: z.string().min(1).max(100).trim().optional(),
+    bio: z.string().max(500).optional()
+  })
+});
+
+module.exports = { createUserSchema, updateUserSchema };
+```
+
+### Response Format Standards
+
+**Success Responses:**
+```javascript
+// GOOD: Consistent success format
+res.status(200).json({ data: users });
+res.status(201).json({ data: newUser });
+res.status(204).send(); // No content
+```
+
+**Error Responses:**
+```javascript
+// GOOD: Consistent error format
+res.status(400).json({
+  error: {
+    code: 'INVALID_INPUT',
+    message: 'Email is required',
+    details: { field: 'email', reason: 'missing' } // Optional
+  }
+});
+```
+
+**Status Code Reference Table:**
+
+| Code | Use Case | Example |
+|------|----------|---------|
+| 200 | Success (read/update) | `GET /users/:id` |
+| 201 | Created | `POST /users` |
+| 204 | Success, no content | `DELETE /users/:id` |
+| 400 | Bad request | Invalid JSON, malformed data |
+| 401 | Unauthorized | Missing/invalid token |
+| 403 | Forbidden | Valid token, insufficient permissions |
+| 404 | Not found | Resource doesn't exist |
+| 409 | Conflict | Duplicate email, version mismatch |
+| 422 | Validation error | Zod validation failed |
+| 429 | Rate limit exceeded | Too many requests |
+| 500 | Server error | Unexpected error |
+
+### Structured Logging (Pino)
+
+**Setup:**
+```javascript
+// utils/logger.js
+const pino = require('pino');
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label })
+  },
+  redact: {
+    paths: ['password', 'token', 'authorization', '*.password', '*.token'],
+    remove: true
+  }
+});
+
+module.exports = { logger };
+```
+
+**Usage:**
+```javascript
+// GOOD: Structured logging with context
+logger.info({ userId, action: 'login' }, 'User logged in');
+logger.error({ err, requestId: req.id }, 'Database query failed');
+
+// BAD: String concatenation, no structure
+logger.info('User ' + userId + ' logged in');
+```
+
+**NEVER Log These (CRITICAL):**
+- Passwords (plain or hashed)
+- API keys, tokens, secrets
+- Credit card numbers, SSN
+- Full request/response bodies (may contain PII)
+
+### Environment Configuration
+
+**Fail-Fast Validation:**
+```javascript
+// config/env.js
+const { z } = require('zod');
+require('dotenv').config();
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.string().transform(Number).pipe(z.number().min(1).max(65535)),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  REDIS_URL: z.string().url(),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info')
+});
+
+// Validate on startup - crash immediately if invalid
+const env = envSchema.parse(process.env);
+
+module.exports = env;
+```
+
+**NEVER:**
+- Hardcode secrets in source code
+- Commit .env files to git
+- Use default secrets in production
+- Access `process.env` directly (use validated config)
+
+### Graceful Shutdown
+
+**CRITICAL: Drain connections before exit**
+```javascript
+// server.js
+const gracefulShutdown = async (signal) => {
+  logger.info({ signal }, 'Shutdown signal received');
+
+  // Stop accepting new connections
+  server.close(async () => {
+    logger.info('HTTP server closed');
+
+    try {
+      // Close database connections
+      await db.close();
+      logger.info('Database connection closed');
+
+      // Close Redis connections
+      await redis.quit();
+      logger.info('Redis connection closed');
+
+      process.exit(0);
+    } catch (err) {
+      logger.error({ err }, 'Error during shutdown');
+      process.exit(1);
+    }
+  });
+
+  // Force shutdown after 30s
+  setTimeout(() => {
+    logger.error('Forced shutdown after timeout');
+    process.exit(1);
+  }, 30000);
+};
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+// CRITICAL: Handle unhandled rejections
+process.on('unhandledRejection', (reason, promise) => {
+  logger.error({ reason, promise }, 'Unhandled Promise Rejection');
+  process.exit(1);
+});
+```
+
+### Performance Patterns
+
+**Connection Pooling (PostgreSQL):**
+```javascript
+// config/database.js
+const { Pool } = require('pg');
+
+const pool = new Pool({
+  connectionString: env.DATABASE_URL,
+  max: 20, // Max connections in pool
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000
+});
+
+// GOOD: Use pool, not new Client() for each query
+const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+**Compression Middleware:**
+```javascript
+const compression = require('compression');
+
+app.use(compression({
+  filter: (req, res) => {
+    if (req.headers['x-no-compression']) return false;
+    return compression.filter(req, res);
+  },
+  level: 6 // Balance between speed and ratio
+}));
+```
+
+**Streaming Large Payloads:**
+```javascript
+// GOOD: Stream large responses
+router.get('/export', asyncHandler(async (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+  res.setHeader('Content-Disposition', 'attachment; filename="export.json"');
+
+  const stream = await dataService.streamExport();
+  stream.pipe(res);
+}));
+
+// BAD: Load everything into memory
+const allData = await dataService.getAll(); // OOM risk
+res.json(allData);
+```
+
+### Controller-Service-Repository Pattern
+
+**Controller (THIN - only HTTP concerns):**
+```javascript
+// controllers/user.controller.js
+const userService = require('../services/user.service');
+const asyncHandler = require('../utils/asyncHandler');
+
+exports.createUser = asyncHandler(async (req, res) => {
+  const user = await userService.createUser(req.body);
+  res.status(201).json({ data: user });
+});
+
+exports.getUser = asyncHandler(async (req, res) => {
+  const user = await userService.getUser(req.params.id);
+  res.json({ data: user });
+});
+```
+
+**Service (Business Logic):**
+```javascript
+// services/user.service.js
+const userRepository = require('../repositories/user.repository');
+const AppError = require('../utils/AppError');
+const { hashPassword } = require('../utils/password');
+
+exports.createUser = async (data) => {
+  const exists = await userRepository.findByEmail(data.email);
+  if (exists) {
+    throw new AppError('Email already in use', 409, 'EMAIL_CONFLICT');
+  }
+
+  const hashedPassword = await hashPassword(data.password);
+  return userRepository.create({ ...data, password: hashedPassword });
+};
+
+exports.getUser = async (id) => {
+  const user = await userRepository.findById(id);
+  if (!user) {
+    throw new AppError('User not found', 404, 'USER_NOT_FOUND');
+  }
+  return user;
+};
+```
+
+**Repository (Data Access):**
+```javascript
+// repositories/user.repository.js
+const pool = require('../config/database');
+
+exports.create = async (data) => {
+  const result = await pool.query(
+    'INSERT INTO users (email, password, name) VALUES ($1, $2, $3) RETURNING *',
+    [data.email, data.password, data.name]
+  );
+  return result.rows[0];
+};
+
+exports.findById = async (id) => {
+  const result = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
+  return result.rows[0];
+};
+
+exports.findByEmail = async (email) => {
+  const result = await pool.query('SELECT * FROM users WHERE email = $1', [email]);
+  return result.rows[0];
+};
+```
+
+## Conventions
+
+### File Naming
+- **Files:** `camelCase.js` (userController.js, authMiddleware.js)
+- **Classes:** `PascalCase` (AppError, UserService)
+- **Constants:** `UPPER_SNAKE_CASE` (MAX_LOGIN_ATTEMPTS)
+
+### Database
+- **Columns:** `snake_case` (user_id, created_at)
+- **Tables:** `plural` (users, orders, audit_logs)
+- **Foreign keys:** `{table}_id` (user_id, order_id)
+
+### Variable Naming
+- **JavaScript:** `camelCase` (userId, requestData)
+- **SQL params:** `$1, $2` (PostgreSQL) or `?` (MySQL)
+
+### Boolean Handling
+- **Database:** `BOOLEAN` type (true/false)
+- **JavaScript:** `true/false` (not 1/0)
+- **Never:** String booleans ("true", "false")
+
+### Date Handling
+- **Storage:** UTC timestamps (`TIMESTAMP WITH TIME ZONE`)
+- **API:** ISO 8601 strings (`2026-02-15T10:30:00Z`)
+- **NEVER:** Unix timestamps in APIs (use ISO strings)
+
+### Audit Logging
+- **Action names:** lowercase verbs (`created`, `updated`, `deleted`)
+- **Include:** userId, action, resourceType, resourceId, timestamp, changes (optional)
+
+## Common Patterns
+
+### 1. Paginated API Response
+
+```javascript
+// GOOD: Consistent pagination
+router.get('/users', asyncHandler(async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 20;
+  const offset = (page - 1) * limit;
+
+  const { rows: users, count } = await userRepository.findAll({ limit, offset });
+
+  res.json({
+    data: users,
+    pagination: {
+      page,
+      limit,
+      total: count,
+      totalPages: Math.ceil(count / limit)
+    }
+  });
+}));
+```
+
+### 2. Transaction Wrapper
+
+```javascript
+// utils/transaction.js
+const pool = require('../config/database');
+
+const withTransaction = async (callback) => {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const result = await callback(client);
+    await client.query('COMMIT');
+    return result;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+};
+
+// Usage in service:
+exports.transferFunds = async (fromId, toId, amount) => {
+  return withTransaction(async (client) => {
+    await client.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [amount, fromId]);
+    await client.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [amount, toId]);
+    return { success: true };
+  });
+};
+```
+
+### 3. Dependency Injection for Testing
+
+```javascript
+// GOOD: Inject dependencies
+class UserService {
+  constructor(userRepository, emailService) {
+    this.userRepository = userRepository;
+    this.emailService = emailService;
+  }
+
+  async createUser(data) {
+    const user = await this.userRepository.create(data);
+    await this.emailService.sendWelcome(user.email);
+    return user;
+  }
+}
+
+// Easy to mock in tests:
+const mockRepo = { create: jest.fn() };
+const mockEmail = { sendWelcome: jest.fn() };
+const service = new UserService(mockRepo, mockEmail);
+```
+
+### 4. Request Context Logger
+
+```javascript
+// middleware/requestLogger.js
+const { logger } = require('../utils/logger');
+
+const requestLogger = (req, res, next) => {
+  const start = Date.now();
+
+  // Create child logger with request context
+  req.log = logger.child({ requestId: req.id });
+
+  res.on('finish', () => {
+    req.log.info({
+      method: req.method,
+      path: req.path,
+      statusCode: res.statusCode,
+      duration: Date.now() - start,
+      userId: req.user?.id
+    }, 'Request completed');
+  });
+
+  next();
+};
+
+// Usage in controllers:
+req.log.info({ orderId }, 'Processing order');
+```
+
+### 5. Feature Flags
+
+```javascript
+// utils/features.js
+const features = {
+  newCheckout: process.env.FEATURE_NEW_CHECKOUT === 'true',
+  betaSearch: process.env.FEATURE_BETA_SEARCH === 'true'
+};
+
+const isEnabled = (feature) => features[feature] || false;
+
+// Usage:
+if (isEnabled('newCheckout')) {
+  return newCheckoutService.process(order);
+}
+return legacyCheckoutService.process(order);
+```
+
+## Anti-Patterns
+
+### 1. Callback Hell
+
+**BAD:**
+```javascript
+getUserById(id, (err, user) => {
+  if (err) return handleError(err);
+  getOrders(user.id, (err, orders) => {
+    if (err) return handleError(err);
+    processOrders(orders, (err, result) => {
+      if (err) return handleError(err);
+      sendEmail(result, (err) => {
+        if (err) return handleError(err);
+      });
+    });
+  });
+});
+```
+
+**GOOD:**
+```javascript
+const user = await userService.getById(id);
+const orders = await orderService.getByUserId(user.id);
+const result = await orderService.process(orders);
+await emailService.send(result);
+```
+
+### 2. Fat Controllers
+
+**BAD:**
+```javascript
+// Controller doing business logic AND data access
+exports.createUser = asyncHandler(async (req, res) => {
+  const exists = await pool.query('SELECT * FROM users WHERE email = $1', [req.body.email]);
+  if (exists.rows.length > 0) {
+    throw new AppError('Email exists', 409);
+  }
+
+  const hashed = await bcrypt.hash(req.body.password, 10);
+  const result = await pool.query(
+    'INSERT INTO users (email, password) VALUES ($1, $2) RETURNING *',
+    [req.body.email, hashed]
+  );
+
+  await sendEmail(result.rows[0].email, 'Welcome!');
+  res.status(201).json({ data: result.rows[0] });
+});
+```
+
+**GOOD:**
+```javascript
+// Controller delegates to service
+exports.createUser = asyncHandler(async (req, res) => {
+  const user = await userService.createUser(req.body);
+  res.status(201).json({ data: user });
+});
+```
+
+### 3. Ignoring Errors
+
+**BAD:**
+```javascript
+// Swallowing errors
+try {
+  await riskyOperation();
+} catch (err) {
+  // Silent failure - user never knows something broke
+}
+
+// Or worse: empty catch
+doSomething().catch(() => {});
+```
+
+**GOOD:**
+```javascript
+// Proper error handling
+try {
+  await riskyOperation();
+} catch (err) {
+  logger.error({ err }, 'Risky operation failed');
+  throw new AppError('Operation failed', 500, 'OPERATION_ERROR');
+}
+```
+
+### 4. Blocking the Event Loop
+
+**BAD:**
+```javascript
+// Synchronous crypto operations block the event loop
+const bcrypt = require('bcrypt');
+const hashed = bcrypt.hashSync(password, 10); // BLOCKS for ~100ms
+
+// Heavy computation in request handler
+router.get('/report', (req, res) => {
+  const data = processMillionsOfRecords(); // Blocks all other requests
+  res.json(data);
+});
+```
+
+**GOOD:**
+```javascript
+// Use async versions
+const hashed = await bcrypt.hash(password, 10);
+
+// Offload heavy work to worker threads or queues
+const { Worker } = require('worker_threads');
+router.get('/report', asyncHandler(async (req, res) => {
+  const jobId = await jobQueue.add('generateReport', req.query);
+  res.status(202).json({ data: { jobId, status: 'processing' } });
+}));
+```
+
+### 5. SQL Injection
+
+**BAD:**
+```javascript
+// NEVER concatenate user input into SQL
+const userId = req.params.id;
+const query = `SELECT * FROM users WHERE id = '${userId}'`; // VULNERABLE
+const result = await pool.query(query);
+```
+
+**GOOD:**
+```javascript
+// ALWAYS use parameterized queries
+const userId = req.params.id;
+const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+## Integration Notes
+
+### Team Coordination
+
+When working as part of a multi-session team:
+
+1. **Startup:** Call `team_check_inbox()` FIRST to get messages/artifacts from other workers
+2. **Consume Conventions:** Read `shared-conventions` artifact to align on response format, status codes, naming
+3. **Consume Database Schema:** Read schema artifact from database worker to match table/column names exactly
+4. **Publish API Contract:** After implementing routes, publish artifact with:
+   ```json
+   {
+     "routes": [
+       { "method": "POST", "path": "/api/users", "auth": true, "body": "CreateUserSchema" },
+       { "method": "GET", "path": "/api/users/:id", "auth": true, "response": "UserSchema" }
+     ],
+     "schemas": { "CreateUserSchema": {...}, "UserSchema": {...} },
+     "errorCodes": ["VALIDATION_ERROR", "USER_NOT_FOUND", "EMAIL_CONFLICT"]
+   }
+   ```
+5. **Coordinate with Frontend:** Frontend worker consumes your API contract artifact
+6. **Broadcast Completion:** Use `team_broadcast()` when routes are ready for integration testing
+7. **File Paths:** ALWAYS use relative paths (e.g., `src/controllers/user.js`), NEVER absolute paths
+
+### Database Worker Coordination
+
+**CRITICAL: Match database worker's schema exactly**
+- Read their artifact for table names, column names, data types
+- Use their naming conventions (e.g., `user_id` not `userId` in SQL)
+- Follow their foreign key patterns
+- Never create tables yourself - coordinate schema changes
+
+### Frontend Worker Coordination
+
+**Provide clear API contract:**
+- Document all endpoints (method, path, auth requirement)
+- Provide request/response schemas (use Zod schemas as source of truth)
+- List all possible error codes
+- Document pagination format
+- Document authentication (Bearer token in `Authorization` header)
+
+**Example artifact:**
+```json
+{
+  "baseUrl": "/api/v1",
+  "authentication": "Bearer token in Authorization header",
+  "responseFormat": {
+    "success": { "data": "<resource>" },
+    "error": { "error": { "code": "string", "message": "string" } }
+  },
+  "endpoints": [...]
+}
+```
+
+### Testing Coordination
+
+**For integration tests:**
+- Seed database with test data (coordinate with database worker)
+- Provide test fixtures (sample requests/responses)
+- Document test user credentials
+- Clear test data between runs
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2026-02-15
+**Token Count:** ~1950 (under 2000 limit for Worker Context)