claude-brain 0.15.2 → 0.17.0

package/packs/backend/node.json

@@ -1,173 +1,173 @@
-{
-  "id": "backend/node",
-  "name": "Node.js Backend Patterns",
-  "version": "1.0.0",
-  "stack": ["node", "express", "fastify", "hono", "nestjs", "elysia", "bun"],
-  "description": "Error handling, streams, worker threads, security, graceful shutdown, and server patterns",
-  "author": "claude-brain",
-  "entries": [
-    {
-      "type": "best-practice",
-      "category": "Error Handling",
-      "title": "Centralize error handling middleware",
-      "content": "Use a centralized error handling middleware/handler instead of try/catch in every route. Map error types to HTTP status codes. Log the full error server-side but return safe messages to clients.",
-      "confidence": 0.95,
-      "tags": ["node", "error-handling", "middleware"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Error Handling",
-      "title": "Handle unhandled rejections and exceptions",
-      "content": "Always register handlers for 'uncaughtException' and 'unhandledRejection' process events. Log the error and perform graceful shutdown. These are last-resort safety nets.",
-      "confidence": 0.95,
-      "tags": ["node", "error-handling", "process"],
-      "example": "process.on('unhandledRejection', (reason) => { logger.fatal({ reason }, 'Unhandled rejection'); shutdown(); })"
-    },
-    {
-      "type": "pattern",
-      "category": "Graceful Shutdown",
-      "title": "Implement graceful shutdown",
-      "content": "Handle SIGTERM and SIGINT signals to gracefully shut down. Stop accepting new connections, finish in-flight requests, close database connections, then exit. This prevents data corruption during deployments.",
-      "confidence": 0.95,
-      "tags": ["node", "shutdown", "deployment"],
-      "example": "process.on('SIGTERM', async () => { await server.close(); await db.close(); process.exit(0); })"
-    },
-    {
-      "type": "best-practice",
-      "category": "Security",
-      "title": "Validate all input at system boundaries",
-      "content": "Validate and sanitize all external input (request body, query params, headers) at the API boundary using a schema validation library (Zod, Joi, AJV). Never trust client data.",
-      "confidence": 0.95,
-      "tags": ["node", "security", "validation"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Security",
-      "title": "Never expose internal errors to clients",
-      "content": "Don't send stack traces, database errors, or internal paths to API clients. Map all errors to safe, generic messages with appropriate HTTP status codes. Log the full error server-side only.",
-      "confidence": 0.95,
-      "tags": ["node", "security", "error-handling"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Security",
-      "title": "Use parameterized queries for databases",
-      "content": "Always use parameterized queries or an ORM for database operations. Never concatenate user input into SQL strings. This prevents SQL injection, the most critical web vulnerability.",
-      "confidence": 0.95,
-      "tags": ["node", "security", "sql-injection", "database"]
-    },
-    {
-      "type": "pattern",
-      "category": "Architecture",
-      "title": "Separate route handlers from business logic",
-      "content": "Keep route handlers thin — they should parse input, call service functions, and format responses. Business logic belongs in service modules that are independently testable and reusable.",
-      "confidence": 0.9,
-      "tags": ["node", "architecture", "separation-of-concerns"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Logging",
-      "title": "Use structured logging with levels",
-      "content": "Use a structured logger (pino, winston) that outputs JSON. Include request IDs, timestamps, and context. Use log levels (debug, info, warn, error, fatal) consistently.",
-      "confidence": 0.9,
-      "tags": ["node", "logging", "observability"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Performance",
-      "title": "Don't block the event loop",
-      "content": "Avoid synchronous operations (readFileSync, crypto, JSON.parse on large data) in request handlers. Use async alternatives, worker threads, or break work into chunks with setImmediate.",
-      "confidence": 0.95,
-      "tags": ["node", "performance", "event-loop"]
-    },
-    {
-      "type": "pattern",
-      "category": "Streams",
-      "title": "Use streams for large data processing",
-      "content": "Process large files, HTTP bodies, and datasets with streams instead of loading everything into memory. Pipe readable to writable streams. Use pipeline() for proper error handling.",
-      "confidence": 0.9,
-      "tags": ["node", "streams", "performance"],
-      "example": "import { pipeline } from 'stream/promises';\nawait pipeline(readStream, transform, writeStream);"
-    },
-    {
-      "type": "best-practice",
-      "category": "Configuration",
-      "title": "Use environment variables for configuration",
-      "content": "Load configuration from environment variables, not hardcoded values. Use a library (dotenv, env-schema) to validate env vars at startup. Fail fast if required configuration is missing.",
-      "confidence": 0.9,
-      "tags": ["node", "configuration", "environment"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Security",
-      "title": "Never store secrets in code or git",
-      "content": "Don't commit API keys, database passwords, or tokens to version control. Use environment variables, secret management services (Vault, AWS Secrets Manager), or .env files in .gitignore.",
-      "confidence": 0.95,
-      "tags": ["node", "security", "secrets"]
-    },
-    {
-      "type": "best-practice",
-      "category": "API Design",
-      "title": "Use proper HTTP status codes",
-      "content": "Return semantically correct HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 500 (Server Error).",
-      "confidence": 0.9,
-      "tags": ["node", "api", "http", "rest"]
-    },
-    {
-      "type": "pattern",
-      "category": "Middleware",
-      "title": "Use middleware for cross-cutting concerns",
-      "content": "Implement authentication, rate limiting, request logging, CORS, and compression as middleware. This keeps route handlers focused on business logic and makes concerns reusable.",
-      "confidence": 0.9,
-      "tags": ["node", "middleware", "architecture"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Performance",
-      "title": "Implement connection pooling for databases",
-      "content": "Always use connection pooling for database connections. Creating a new connection per request is slow and exhausts database limits. Most ORMs and drivers support pooling out of the box.",
-      "confidence": 0.9,
-      "tags": ["node", "database", "performance", "connection-pooling"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Security",
-      "title": "Set appropriate security headers",
-      "content": "Use helmet or set security headers manually: Content-Security-Policy, X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options. These prevent common web attacks.",
-      "confidence": 0.9,
-      "tags": ["node", "security", "headers"]
-    },
-    {
-      "type": "pattern",
-      "category": "Testing",
-      "title": "Use dependency injection for testability",
-      "content": "Pass dependencies (database, logger, external services) as constructor/function parameters instead of importing singletons. This enables easy mocking in tests and flexible composition.",
-      "confidence": 0.85,
-      "tags": ["node", "testing", "dependency-injection"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Error Handling",
-      "title": "Avoid empty catch blocks",
-      "content": "Never swallow errors silently with empty catch blocks. At minimum, log the error. Silently ignoring errors makes debugging impossible and can mask serious issues.",
-      "confidence": 0.95,
-      "tags": ["node", "error-handling"]
-    },
-    {
-      "type": "best-practice",
-      "category": "API Design",
-      "title": "Implement request rate limiting",
-      "content": "Add rate limiting to protect against abuse and DDoS. Use token bucket or sliding window algorithms. Apply stricter limits to authentication endpoints. Return 429 Too Many Requests.",
-      "confidence": 0.9,
-      "tags": ["node", "security", "rate-limiting", "api"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Memory",
-      "title": "Watch for memory leaks in long-running processes",
-      "content": "Node.js servers can leak memory through event listeners, caches without size limits, closures holding references, and global arrays. Monitor heap usage and use WeakMap/WeakRef where appropriate.",
-      "confidence": 0.85,
-      "tags": ["node", "memory", "performance", "debugging"]
-    }
-  ]
-}
+{
+  "id": "backend/node",
+  "name": "Node.js Backend Patterns",
+  "version": "1.0.0",
+  "stack": ["node", "express", "fastify", "hono", "nestjs", "elysia", "bun"],
+  "description": "Error handling, streams, worker threads, security, graceful shutdown, and server patterns",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Error Handling",
+      "title": "Centralize error handling middleware",
+      "content": "Use a centralized error handling middleware/handler instead of try/catch in every route. Map error types to HTTP status codes. Log the full error server-side but return safe messages to clients.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling", "middleware"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Error Handling",
+      "title": "Handle unhandled rejections and exceptions",
+      "content": "Always register handlers for 'uncaughtException' and 'unhandledRejection' process events. Log the error and perform graceful shutdown. These are last-resort safety nets.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling", "process"],
+      "example": "process.on('unhandledRejection', (reason) => { logger.fatal({ reason }, 'Unhandled rejection'); shutdown(); })"
+    },
+    {
+      "type": "pattern",
+      "category": "Graceful Shutdown",
+      "title": "Implement graceful shutdown",
+      "content": "Handle SIGTERM and SIGINT signals to gracefully shut down. Stop accepting new connections, finish in-flight requests, close database connections, then exit. This prevents data corruption during deployments.",
+      "confidence": 0.95,
+      "tags": ["node", "shutdown", "deployment"],
+      "example": "process.on('SIGTERM', async () => { await server.close(); await db.close(); process.exit(0); })"
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Validate all input at system boundaries",
+      "content": "Validate and sanitize all external input (request body, query params, headers) at the API boundary using a schema validation library (Zod, Joi, AJV). Never trust client data.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "validation"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Security",
+      "title": "Never expose internal errors to clients",
+      "content": "Don't send stack traces, database errors, or internal paths to API clients. Map all errors to safe, generic messages with appropriate HTTP status codes. Log the full error server-side only.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "error-handling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Use parameterized queries for databases",
+      "content": "Always use parameterized queries or an ORM for database operations. Never concatenate user input into SQL strings. This prevents SQL injection, the most critical web vulnerability.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "sql-injection", "database"]
+    },
+    {
+      "type": "pattern",
+      "category": "Architecture",
+      "title": "Separate route handlers from business logic",
+      "content": "Keep route handlers thin — they should parse input, call service functions, and format responses. Business logic belongs in service modules that are independently testable and reusable.",
+      "confidence": 0.9,
+      "tags": ["node", "architecture", "separation-of-concerns"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Logging",
+      "title": "Use structured logging with levels",
+      "content": "Use a structured logger (pino, winston) that outputs JSON. Include request IDs, timestamps, and context. Use log levels (debug, info, warn, error, fatal) consistently.",
+      "confidence": 0.9,
+      "tags": ["node", "logging", "observability"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Don't block the event loop",
+      "content": "Avoid synchronous operations (readFileSync, crypto, JSON.parse on large data) in request handlers. Use async alternatives, worker threads, or break work into chunks with setImmediate.",
+      "confidence": 0.95,
+      "tags": ["node", "performance", "event-loop"]
+    },
+    {
+      "type": "pattern",
+      "category": "Streams",
+      "title": "Use streams for large data processing",
+      "content": "Process large files, HTTP bodies, and datasets with streams instead of loading everything into memory. Pipe readable to writable streams. Use pipeline() for proper error handling.",
+      "confidence": 0.9,
+      "tags": ["node", "streams", "performance"],
+      "example": "import { pipeline } from 'stream/promises';\nawait pipeline(readStream, transform, writeStream);"
+    },
+    {
+      "type": "best-practice",
+      "category": "Configuration",
+      "title": "Use environment variables for configuration",
+      "content": "Load configuration from environment variables, not hardcoded values. Use a library (dotenv, env-schema) to validate env vars at startup. Fail fast if required configuration is missing.",
+      "confidence": 0.9,
+      "tags": ["node", "configuration", "environment"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Security",
+      "title": "Never store secrets in code or git",
+      "content": "Don't commit API keys, database passwords, or tokens to version control. Use environment variables, secret management services (Vault, AWS Secrets Manager), or .env files in .gitignore.",
+      "confidence": 0.95,
+      "tags": ["node", "security", "secrets"]
+    },
+    {
+      "type": "best-practice",
+      "category": "API Design",
+      "title": "Use proper HTTP status codes",
+      "content": "Return semantically correct HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 500 (Server Error).",
+      "confidence": 0.9,
+      "tags": ["node", "api", "http", "rest"]
+    },
+    {
+      "type": "pattern",
+      "category": "Middleware",
+      "title": "Use middleware for cross-cutting concerns",
+      "content": "Implement authentication, rate limiting, request logging, CORS, and compression as middleware. This keeps route handlers focused on business logic and makes concerns reusable.",
+      "confidence": 0.9,
+      "tags": ["node", "middleware", "architecture"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Implement connection pooling for databases",
+      "content": "Always use connection pooling for database connections. Creating a new connection per request is slow and exhausts database limits. Most ORMs and drivers support pooling out of the box.",
+      "confidence": 0.9,
+      "tags": ["node", "database", "performance", "connection-pooling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Security",
+      "title": "Set appropriate security headers",
+      "content": "Use helmet or set security headers manually: Content-Security-Policy, X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options. These prevent common web attacks.",
+      "confidence": 0.9,
+      "tags": ["node", "security", "headers"]
+    },
+    {
+      "type": "pattern",
+      "category": "Testing",
+      "title": "Use dependency injection for testability",
+      "content": "Pass dependencies (database, logger, external services) as constructor/function parameters instead of importing singletons. This enables easy mocking in tests and flexible composition.",
+      "confidence": 0.85,
+      "tags": ["node", "testing", "dependency-injection"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Error Handling",
+      "title": "Avoid empty catch blocks",
+      "content": "Never swallow errors silently with empty catch blocks. At minimum, log the error. Silently ignoring errors makes debugging impossible and can mask serious issues.",
+      "confidence": 0.95,
+      "tags": ["node", "error-handling"]
+    },
+    {
+      "type": "best-practice",
+      "category": "API Design",
+      "title": "Implement request rate limiting",
+      "content": "Add rate limiting to protect against abuse and DDoS. Use token bucket or sliding window algorithms. Apply stricter limits to authentication endpoints. Return 429 Too Many Requests.",
+      "confidence": 0.9,
+      "tags": ["node", "security", "rate-limiting", "api"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Memory",
+      "title": "Watch for memory leaks in long-running processes",
+      "content": "Node.js servers can leak memory through event listeners, caches without size limits, closures holding references, and global arrays. Monitor heap usage and use WeakMap/WeakRef where appropriate.",
+      "confidence": 0.85,
+      "tags": ["node", "memory", "performance", "debugging"]
+    }
+  ]
+}