class-ai-agent 1.2.0

package/.claude/rules/error-handling.md

@@ -0,0 +1,92 @@
+# Error Handling
+
+## Core Principles
+- **Never swallow errors silently** — always log or rethrow
+- Use a centralized error handler
+- Return consistent error responses to the API
+- Distinguish between operational errors (expected) and programmer errors (bugs)
+
+## Custom Error Class
+```js
+// src/utils/app-error.js
+class AppError extends Error {
+  constructor(message, statusCode = 500, code = 'INTERNAL_ERROR') {
+    super(message);
+    this.name = 'AppError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export default AppError;
+```
+
+## Throwing Errors
+```js
+// ✅ Use AppError for known operational errors
+if (!user) {
+  throw new AppError('User not found', 404, 'USER_NOT_FOUND');
+}
+
+if (!hasPermission) {
+  throw new AppError('Forbidden', 403, 'ACCESS_DENIED');
+}
+```
+
+## Async Error Handling
+```js
+// ✅ Always wrap async route handlers
+const asyncHandler = (fn) => (req, res, next) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+
+router.get('/users/:id', asyncHandler(async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  res.json({ success: true, data: user });
+}));
+```
+
+## Global Error Handler (Express)
+```js
+// middleware/error-handler.js
+export function errorHandler(err, req, res, next) {
+  const statusCode = err.statusCode || 500;
+  const isOperational = err.isOperational || false;
+
+  // Log all errors
+  logger.error({ err, req: { method: req.method, url: req.url } });
+
+  // Don't expose internal errors to clients
+  if (!isOperational) {
+    return res.status(500).json({
+      success: false,
+      error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' }
+    });
+  }
+
+  res.status(statusCode).json({
+    success: false,
+    error: { code: err.code, message: err.message }
+  });
+}
+```
+
+## Validation Errors
+```js
+// Use a validation library (Zod/Joi/Yup) and throw structured errors
+import { z } from 'zod';
+
+const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2)
+});
+
+function validateUser(data) {
+  const result = userSchema.safeParse(data);
+  if (!result.success) {
+    throw new AppError('Validation failed', 422, 'VALIDATION_ERROR');
+  }
+  return result.data;
+}
+```

package/.claude/rules/git-workflow.md

@@ -0,0 +1,77 @@
+# Git Workflow
+
+## Branch Strategy (Git Flow)
+
+```
+main          — Production-ready code only
+develop       — Integration branch for features
+feature/*     — New features
+fix/*         — Bug fixes
+hotfix/*      — Urgent production fixes
+release/*     — Release preparation
+```
+
+## Branch Naming
+```
+feature/user-authentication
+feature/payment-integration
+fix/login-redirect-bug
+fix/order-calculation-issue
+hotfix/critical-security-patch
+release/v1.2.0
+```
+
+## Commit Message Format (Conventional Commits)
+
+```
+<type>(<scope>): <short description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+| Type | Usage |
+|------|-------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no logic change |
+| `refactor` | Code restructure, no feature/fix |
+| `test` | Adding or fixing tests |
+| `chore` | Build process, dependencies |
+| `perf` | Performance improvement |
+
+### Examples
+```
+feat(auth): add JWT refresh token support
+
+fix(orders): correct total price calculation when discount applied
+
+docs(api): add Swagger annotations to user endpoints
+
+test(users): add unit tests for UserService.findById
+
+chore: upgrade express to v5.0.0
+```
+
+## Pull Request Rules
+- PRs must reference an issue: `Closes #123`
+- Minimum 1 reviewer approval required
+- All CI checks must pass
+- No direct commits to `main` or `develop`
+- PR title must follow conventional commit format
+
+## Commit Best Practices
+- Commit frequently with small, focused changes
+- Each commit should be a single logical change
+- Never commit: `.env` files, secrets, `node_modules`
+- Always run tests before committing
+
+## Tags & Releases
+```bash
+# Tag a release
+git tag -a v1.2.0 -m "Release version 1.2.0"
+git push origin v1.2.0
+```

package/.claude/rules/monitoring.md

@@ -0,0 +1,311 @@
+# Monitoring & Observability
+
+> Standards for logging, metrics, tracing, alerting, and Grafana dashboard design.
+
+## 🔭 The Three Pillars of Observability
+
+| Pillar | Tool | Purpose |
+|--------|------|---------|
+| **Logs** | Winston / Pino + Loki | What happened |
+| **Metrics** | Prometheus + Grafana | How the system is behaving |
+| **Traces** | OpenTelemetry + Jaeger | Why something is slow |
+
+---
+
+## 📝 Logging Rules
+
+### Log Levels
+| Level | When to Use |
+|-------|-------------|
+| `error` | Unexpected failure requiring attention |
+| `warn` | Unexpected but recoverable situation |
+| `info` | Normal significant events (startup, request lifecycle) |
+| `debug` | Detailed debugging info (dev only) |
+| `trace` | Very verbose (never in production) |
+
+### Log Format — Structured JSON (always!)
+```js
+// ✅ Structured log — searchable and parseable
+logger.info({
+  event: 'order.placed',
+  orderId: order.id,
+  userId: user.id,
+  amount: order.total,
+  durationMs: Date.now() - startTime,
+  requestId: req.id,
+});
+
+// ❌ Unstructured log — cannot be queried
+console.log(`Order ${orderId} placed by user ${userId}`);
+```
+
+### Mandatory Fields
+```js
+{
+  level: 'info',
+  timestamp: '2026-01-01T00:00:00.000Z',
+  service: 'order-service',
+  version: '1.2.3',
+  environment: 'production',
+  requestId: 'uuid',          // trace across services
+  userId: 'uuid',             // who triggered it
+  event: 'order.placed',      // what happened
+  durationMs: 45,             // how long
+  // ... domain-specific fields
+}
+```
+
+### What NOT to Log
+```js
+// ❌ Never log sensitive data
+logger.info({ password: user.password });     // NEVER
+logger.info({ token: req.headers.authorization }); // NEVER
+logger.info({ creditCard: payment.card });    // NEVER
+logger.info({ ssn: user.socialSecurityNumber }); // NEVER
+```
+
+### Logger Setup (Pino)
+```js
+// src/utils/logger.js
+import pino from 'pino';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  base: {
+    service: process.env.APP_NAME,
+    version: process.env.npm_package_version,
+    env: process.env.NODE_ENV,
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+});
+```
+
+---
+
+## 📊 Metrics (Prometheus + Grafana)
+
+### Metric Types
+| Type | Use Case | Example |
+|------|----------|---------|
+| **Counter** | Values that only increase | `http_requests_total` |
+| **Gauge** | Values that go up and down | `active_connections`, `memory_usage_bytes` |
+| **Histogram** | Distribution of values | `http_request_duration_seconds` |
+| **Summary** | Pre-calculated percentiles | `request_latency_percentiles` |
+
+### Naming Convention
+```
+# Pattern: {namespace}_{subsystem}_{name}_{unit}
+# All lowercase, underscores, snake_case
+
+http_request_duration_seconds         # histogram
+http_requests_total                   # counter
+http_requests_in_flight               # gauge
+db_query_duration_seconds             # histogram
+cache_hits_total                      # counter
+cache_misses_total                    # counter
+queue_messages_pending                # gauge
+queue_processing_duration_seconds     # histogram
+payment_transactions_total            # counter (+ status label)
+```
+
+### Labels (Dimensions)
+```js
+// ✅ Use labels for meaningful dimensions
+httpRequestCounter.labels({
+  method: req.method,        // GET, POST, etc.
+  route: '/api/v1/users',    // normalized route
+  status_code: res.statusCode,
+  service: 'user-service',
+}).inc();
+
+// ❌ Don't use high-cardinality labels (userId, orderId)
+// This creates millions of time series → kills Prometheus
+```
+
+### Express Middleware for Metrics
+```js
+// middleware/metrics.js
+import client from 'prom-client';
+
+const httpDuration = new client.Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'Duration of HTTP requests in seconds',
+  labelNames: ['method', 'route', 'status_code'],
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+});
+
+export function metricsMiddleware(req, res, next) {
+  const end = httpDuration.startTimer();
+  res.on('finish', () => {
+    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
+  });
+  next();
+}
+
+// Expose metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', client.register.contentType);
+  res.end(await client.register.metrics());
+});
+```
+
+---
+
+## 📈 Grafana Dashboard Design
+
+### Dashboard Naming
+```
+# Pattern: {Service} — {Category}
+User Service — Overview
+User Service — Errors & Latency
+Order Service — Business Metrics
+Infrastructure — Redis
+Infrastructure — PostgreSQL
+```
+
+### Panel Naming
+```
+# Use title case, include units in title
+Request Rate (req/s)
+P99 Latency (ms)
+Error Rate (%)
+Active DB Connections
+Cache Hit Rate (%)
+Queue Depth
+Memory Usage (MB)
+```
+
+### The RED Method (for Services)
+Every service dashboard MUST have these 3 panels:
+- **R** — **Rate**: requests per second
+- **E** — **Errors**: error rate (%)
+- **D** — **Duration**: P50, P95, P99 latency
+
+```promql
+# Rate
+rate(http_requests_total{service="order-service"}[5m])
+
+# Error rate
+rate(http_requests_total{status_code=~"5.."}[5m])
+/ rate(http_requests_total[5m]) * 100
+
+# P99 latency (ms)
+histogram_quantile(0.99,
+  rate(http_request_duration_seconds_bucket{service="order-service"}[5m])
+) * 1000
+```
+
+### The USE Method (for Infrastructure)
+Every infrastructure dashboard MUST have:
+- **U** — **Utilization**: % of resource being used
+- **S** — **Saturation**: queue depth, wait time
+- **E** — **Errors**: error count/rate
+
+### Standard Dashboard Layout
+```
+Row 1: Summary / Health Overview (traffic lights)
+Row 2: RED metrics (Rate, Errors, Duration)
+Row 3: Resource usage (CPU, Memory, DB connections)
+Row 4: Business metrics (orders/min, signups, payments)
+Row 5: Logs panel (Loki integration)
+```
+
+---
+
+## 🚨 Alerting Rules
+
+### Severity Levels
+| Level | Response Time | Example |
+|-------|--------------|---------|
+| `critical` | Immediate (PagerDuty) | Service down, payment failures |
+| `warning` | Within 30min (Slack) | High error rate, slow queries |
+| `info` | Business hours | Unusual traffic patterns |
+
+### Standard Alert Rules (Prometheus AlertManager)
+```yaml
+groups:
+  - name: service-alerts
+    rules:
+      # Service is down
+      - alert: ServiceDown
+        expr: up{job="my-service"} == 0
+        for: 1m
+        severity: critical
+        annotations:
+          summary: "Service {{ $labels.job }} is down"
+
+      # High error rate
+      - alert: HighErrorRate
+        expr: |
+          rate(http_requests_total{status_code=~"5.."}[5m])
+          / rate(http_requests_total[5m]) > 0.05
+        for: 5m
+        severity: warning
+        annotations:
+          summary: "Error rate > 5% on {{ $labels.service }}"
+
+      # High P99 latency
+      - alert: HighLatency
+        expr: |
+          histogram_quantile(0.99,
+            rate(http_request_duration_seconds_bucket[5m])
+          ) > 1
+        for: 5m
+        severity: warning
+        annotations:
+          summary: "P99 latency > 1s on {{ $labels.service }}"
+
+      # Low cache hit rate
+      - alert: LowCacheHitRate
+        expr: |
+          rate(cache_hits_total[5m])
+          / (rate(cache_hits_total[5m]) + rate(cache_misses_total[5m])) < 0.7
+        for: 10m
+        severity: warning
+```
+
+### Alert Naming Convention
+```
+{Severity}{Service}{Problem}
+CriticalPaymentServiceDown
+WarningOrderServiceHighLatency
+WarningRedisLowHitRate
+CriticalDatabaseConnectionsExhausted
+```
+
+---
+
+## 🔍 Distributed Tracing (OpenTelemetry)
+
+```js
+// src/tracing.js
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+
+const sdk = new NodeSDK({
+  traceExporter: new JaegerExporter({ endpoint: process.env.JAEGER_ENDPOINT }),
+  instrumentations: [getNodeAutoInstrumentations()],
+  serviceName: process.env.APP_NAME,
+});
+
+sdk.start();
+```
+
+### Span Naming
+```
+# HTTP: {method} {route}
+GET /api/v1/users/:id
+
+# DB: {operation} {table}
+SELECT users
+INSERT orders
+
+# Cache: {operation} {key_pattern}
+GET user:{id}
+SET session:{id}
+
+# Queue: {operation} {queue_name}
+PUBLISH order.placed
+CONSUME email.send
+```