metacoding 1.0.0 → 1.1.1

package/templates/node/nodejs.coding.instructions.md

@@ -0,0 +1,249 @@
+---
+description: 'Node.js backend development coding standards and best practices'
+applyTo: 'src/**/*.{ts,js}'
+---
+
+# Node.js Backend Development Guidelines
+
+## Core Node.js Principles
+
+- **Event Loop Awareness:** Understand the event loop and avoid blocking operations
+- **Asynchronous Programming:** Use async/await for I/O operations, avoid callback hell
+- **Module System:** Leverage ES modules with proper import/export patterns
+- **Process Management:** Handle process signals and graceful shutdowns
+- **Error Handling:** Implement comprehensive error handling with proper stack traces
+
+## API Development Standards
+
+### RESTful API Design
+
+- **Resource-Based URLs:** Use nouns for endpoints (`/users`, `/orders`, not `/getUsers`)
+- **HTTP Methods:** Use appropriate HTTP verbs (GET, POST, PUT, DELETE, PATCH)
+- **Status Codes:** Return meaningful HTTP status codes (200, 201, 400, 401, 404, 500)
+- **Consistent Response Format:** Standardize API response structure
+- **Versioning:** Implement API versioning (`/api/v1/users`)
+
+```typescript
+// Good: RESTful endpoint structure
+app.get('/api/v1/users/:id', async (req, res) => {
+  try {
+    const user = await userService.findById(req.params.id);
+    res.status(200).json({ data: user, success: true });
+  } catch (error) {
+    res.status(404).json({ error: 'User not found', success: false });
+  }
+});
+```
+
+### Middleware Architecture
+
+- **Authentication Middleware:** Centralize auth logic in reusable middleware
+- **Validation Middleware:** Validate request data before processing
+- **Error Handling Middleware:** Implement global error handling
+- **Logging Middleware:** Log requests, responses, and errors
+- **Rate Limiting:** Protect APIs from abuse
+
+```typescript
+// Example middleware pattern
+const authenticate = (req: Request, res: Response, next: NextFunction) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  if (!token) {
+    return res.status(401).json({ error: 'No token provided' });
+  }
+  // Verify token logic
+  next();
+};
+```
+
+## Database Integration
+
+### Connection Management
+
+- **Connection Pooling:** Use connection pools for database connections
+- **Transaction Handling:** Implement proper transaction management
+- **Migration Strategy:** Use database migrations for schema changes
+- **Environment Configuration:** Separate configs for dev/staging/production
+
+### ORM/Query Builder Best Practices
+
+- **Model Relationships:** Define clear model relationships
+- **Query Optimization:** Avoid N+1 queries, use eager loading appropriately
+- **Data Validation:** Validate data at the model level
+- **Soft Deletes:** Implement soft deletes for audit trails
+
+```typescript
+// Example with proper transaction handling
+async function transferFunds(fromId: string, toId: string, amount: number) {
+  const transaction = await db.transaction();
+  try {
+    await accountService.debit(fromId, amount, { transaction });
+    await accountService.credit(toId, amount, { transaction });
+    await transaction.commit();
+  } catch (error) {
+    await transaction.rollback();
+    throw error;
+  }
+}
+```
+
+## Security Best Practices
+
+### Input Validation and Sanitization
+
+- **Schema Validation:** Use libraries like Joi, Yup, or Zod for input validation
+- **SQL Injection Prevention:** Use parameterized queries or ORM
+- **XSS Prevention:** Sanitize user inputs and use Content Security Policy
+- **CORS Configuration:** Configure CORS appropriately for your use case
+
+### Authentication and Authorization
+
+- **JWT Implementation:** Implement secure JWT token handling
+- **Password Security:** Use bcrypt for password hashing
+- **Rate Limiting:** Implement rate limiting for login attempts
+- **Session Management:** Secure session handling and cleanup
+
+```typescript
+// Example secure password handling
+import bcrypt from 'bcrypt';
+
+async function hashPassword(password: string): Promise<string> {
+  const saltRounds = 12;
+  return bcrypt.hash(password, saltRounds);
+}
+
+async function verifyPassword(
+  password: string,
+  hash: string
+): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+```
+
+## Performance Optimization
+
+### Caching Strategies
+
+- **Redis Integration:** Use Redis for session storage and caching
+- **HTTP Caching:** Implement proper HTTP caching headers
+- **Database Caching:** Cache frequently accessed database queries
+- **CDN Integration:** Use CDNs for static assets
+
+### Memory Management
+
+- **Memory Leak Prevention:** Monitor and prevent memory leaks
+- **Garbage Collection:** Understand V8 garbage collection
+- **Stream Processing:** Use streams for large data processing
+- **Worker Threads:** Utilize worker threads for CPU-intensive tasks
+
+## Error Handling and Logging
+
+### Comprehensive Error Handling
+
+- **Global Error Handler:** Implement application-wide error handling
+- **Custom Error Classes:** Create specific error types for different scenarios
+- **Error Reporting:** Integrate with error tracking services (Sentry, etc.)
+- **Graceful Degradation:** Handle service failures gracefully
+
+```typescript
+// Example custom error classes
+class ValidationError extends Error {
+  constructor(
+    message: string,
+    public field: string
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+class DatabaseError extends Error {
+  constructor(
+    message: string,
+    public query?: string
+  ) {
+    super(message);
+    this.name = 'DatabaseError';
+  }
+}
+```
+
+### Structured Logging
+
+- **Log Levels:** Use appropriate log levels (error, warn, info, debug)
+- **Structured Format:** Use JSON logging for machine readability
+- **Request Correlation:** Implement request ID correlation
+- **Performance Logging:** Log response times and performance metrics
+
+## Environment and Configuration
+
+### Environment Management
+
+- **Environment Variables:** Use .env files for configuration
+- **Configuration Validation:** Validate configuration at startup
+- **Secrets Management:** Secure handling of API keys and secrets
+- **Multi-Environment Support:** Support dev/staging/production configs
+
+### Deployment Considerations
+
+- **Health Checks:** Implement health check endpoints
+- **Graceful Shutdown:** Handle SIGTERM and SIGINT signals
+- **Process Monitoring:** Use PM2 or similar for process management
+- **Container Optimization:** Optimize Docker images for Node.js
+
+```typescript
+// Example graceful shutdown
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM received, shutting down gracefully');
+  await server.close();
+  await database.disconnect();
+  process.exit(0);
+});
+```
+
+## Testing Strategies
+
+### API Testing
+
+- **Integration Tests:** Test complete request/response cycles
+- **Contract Testing:** Verify API contracts and schemas
+- **Load Testing:** Test performance under load
+- **Security Testing:** Test for common vulnerabilities
+
+### Mocking and Stubbing
+
+- **Database Mocking:** Mock database calls in unit tests
+- **External Service Mocking:** Mock third-party API calls
+- **Time Mocking:** Mock dates and times for consistent testing
+- **Environment Mocking:** Mock environment variables
+
+## Package Management
+
+### Dependency Management
+
+- **Lock Files:** Always commit package-lock.json
+- **Security Audits:** Regular npm audit and vulnerability checks
+- **Version Pinning:** Pin critical dependencies to specific versions
+- **Dev Dependencies:** Separate development and production dependencies
+
+### Performance Dependencies
+
+- **Bundle Analysis:** Analyze bundle size and dependencies
+- **Tree Shaking:** Ensure unused code is eliminated
+- **Critical Path:** Optimize critical path dependencies
+- **Lazy Loading:** Implement lazy loading where appropriate
+
+## Monitoring and Observability
+
+### Application Monitoring
+
+- **Metrics Collection:** Collect application and business metrics
+- **Performance Monitoring:** Monitor response times and throughput
+- **Error Tracking:** Track and alert on errors
+- **Custom Dashboards:** Create dashboards for key metrics
+
+### Debugging Tools
+
+- **Node.js Debugger:** Use built-in debugging tools
+- **Memory Profiling:** Profile memory usage and leaks
+- **CPU Profiling:** Identify performance bottlenecks
+- **Distributed Tracing:** Implement distributed tracing for microservices

package/templates/node/nodejs.docs.instructions.md

@@ -0,0 +1,234 @@
+---
+description: 'Node.js backend documentation standards and API documentation guidelines'
+applyTo: '**/*.md'
+---
+
+# Node.js Backend Documentation Guidelines
+
+## API Documentation Standards
+
+### OpenAPI/Swagger Documentation
+
+- **Schema Definition:** Define complete API schemas using OpenAPI 3.0+
+- **Interactive Documentation:** Provide interactive API documentation
+- **Code Examples:** Include request/response examples in multiple languages
+- **Authentication Documentation:** Document all authentication methods
+- **Error Response Documentation:** Document all possible error responses
+
+```yaml
+# Example OpenAPI schema
+paths:
+  /api/v1/users:
+    get:
+      summary: Get all users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+```
+
+### Endpoint Documentation
+
+- **Purpose Description:** Clearly describe what each endpoint does
+- **Request Parameters:** Document all query parameters, path parameters, and request body
+- **Response Format:** Document response structure and data types
+- **Status Codes:** List all possible HTTP status codes and their meanings
+- **Rate Limiting:** Document rate limiting rules and headers
+
+### Authentication Documentation
+
+- **Token Format:** Document JWT structure and claims
+- **Authorization Flow:** Describe OAuth or other auth flows
+- **Scope Documentation:** Document API scopes and permissions
+- **Token Refresh:** Document token refresh procedures
+- **Security Headers:** Document required security headers
+
+## Database Documentation
+
+### Schema Documentation
+
+- **Entity Relationship Diagrams:** Visual representation of database schema
+- **Table Descriptions:** Purpose and usage of each table
+- **Column Documentation:** Data types, constraints, and relationships
+- **Index Documentation:** Performance-critical indexes
+- **Migration History:** Document major schema changes
+
+### Data Flow Documentation
+
+- **CRUD Operations:** Document create, read, update, delete patterns
+- **Transaction Boundaries:** Document transaction scopes
+- **Data Validation Rules:** Business rules and constraints
+- **Audit Trail:** Document audit and logging mechanisms
+- **Backup and Recovery:** Document backup strategies
+
+## Environment and Deployment Documentation
+
+### Configuration Documentation
+
+- **Environment Variables:** Complete list with descriptions and examples
+- **Configuration Files:** Document all configuration files and their purpose
+- **Secrets Management:** Document how secrets are handled
+- **Feature Flags:** Document feature flag configurations
+- **Third-Party Services:** Document external service dependencies
+
+```markdown
+## Environment Variables
+
+| Variable     | Description                | Example                             | Required |
+| ------------ | -------------------------- | ----------------------------------- | -------- |
+| DATABASE_URL | Database connection string | postgresql://user:pass@localhost/db | Yes      |
+| JWT_SECRET   | Secret key for JWT tokens  | your-secret-key                     | Yes      |
+| REDIS_URL    | Redis connection string    | redis://localhost:6379              | No       |
+```
+
+### Deployment Documentation
+
+- **Build Process:** Document build and compilation steps
+- **Docker Configuration:** Document container setup and requirements
+- **Health Checks:** Document health check endpoints and criteria
+- **Scaling Considerations:** Document horizontal and vertical scaling
+- **Monitoring Setup:** Document monitoring and alerting configuration
+
+## Error Handling Documentation
+
+### Error Response Format
+
+- **Consistent Structure:** Standardize error response format
+- **Error Codes:** Document custom error codes and meanings
+- **Localization:** Document multi-language error message support
+- **Debug Information:** Document debug info inclusion in development
+- **Error Recovery:** Document error recovery strategies
+
+```typescript
+// Example error response format
+interface ErrorResponse {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    details?: any;
+    timestamp: string;
+    requestId: string;
+  };
+}
+```
+
+### Troubleshooting Guides
+
+- **Common Issues:** Document frequently encountered problems
+- **Debug Steps:** Step-by-step debugging procedures
+- **Log Analysis:** How to interpret logs and error messages
+- **Performance Issues:** Common performance problems and solutions
+- **Service Dependencies:** Troubleshooting external service issues
+
+## Performance Documentation
+
+### Performance Benchmarks
+
+- **Response Time Targets:** Document expected response times
+- **Throughput Metrics:** Document expected requests per second
+- **Resource Usage:** Document memory and CPU usage patterns
+- **Database Performance:** Document query performance expectations
+- **Caching Strategies:** Document caching implementations and TTLs
+
+### Optimization Guidelines
+
+- **Profiling Tools:** Document profiling and monitoring tools
+- **Bottleneck Identification:** Common performance bottlenecks
+- **Optimization Techniques:** Proven optimization strategies
+- **Load Testing:** Document load testing procedures
+- **Capacity Planning:** Guidelines for scaling decisions
+
+## Security Documentation
+
+### Security Architecture
+
+- **Threat Model:** Document potential security threats
+- **Security Controls:** Document implemented security measures
+- **Vulnerability Management:** Document security update procedures
+- **Penetration Testing:** Document security testing procedures
+- **Compliance Requirements:** Document regulatory compliance needs
+
+### Security Configuration
+
+- **HTTPS Configuration:** SSL/TLS setup and best practices
+- **CORS Configuration:** Cross-origin resource sharing setup
+- **Security Headers:** Required security headers and their purposes
+- **Input Validation:** Document validation rules and sanitization
+- **Rate Limiting:** Document rate limiting implementation
+
+## Development Workflow Documentation
+
+### Code Organization
+
+- **Project Structure:** Document folder and file organization
+- **Module Dependencies:** Document internal module relationships
+- **Design Patterns:** Document architectural patterns used
+- **Code Style:** Document coding standards and conventions
+- **Git Workflow:** Document branching and commit strategies
+
+### Development Setup
+
+- **Prerequisites:** Required tools and versions
+- **Installation Steps:** Step-by-step setup instructions
+- **Database Setup:** Local database configuration
+- **Environment Setup:** Development environment configuration
+- **IDE Configuration:** Recommended IDE settings and extensions
+
+### Testing Documentation
+
+- **Test Structure:** Document test organization and naming
+- **Test Data:** Document test fixtures and data setup
+- **Mocking Strategies:** Document mocking patterns
+- **Coverage Requirements:** Document test coverage targets
+- **CI/CD Integration:** Document automated testing in pipelines
+
+## Monitoring and Observability Documentation
+
+### Metrics Documentation
+
+- **Business Metrics:** Key business indicators to track
+- **Technical Metrics:** System performance metrics
+- **Custom Metrics:** Application-specific metrics
+- **Alert Thresholds:** When to alert on metric values
+- **Dashboard Configuration:** Key dashboards and their purposes
+
+### Logging Documentation
+
+- **Log Levels:** When to use each log level
+- **Log Format:** Structured logging format and fields
+- **Log Correlation:** Request tracking and correlation
+- **Log Retention:** Log storage and retention policies
+- **Log Analysis:** Common log analysis patterns
+
+## Runbook Documentation
+
+### Operational Procedures
+
+- **Deployment Procedures:** Step-by-step deployment process
+- **Rollback Procedures:** How to rollback failed deployments
+- **Backup Procedures:** Database and file backup processes
+- **Disaster Recovery:** Recovery procedures for major incidents
+- **Maintenance Windows:** Planned maintenance procedures
+
+### Incident Response
+
+- **On-Call Procedures:** Who to contact during incidents
+- **Escalation Matrix:** When and how to escalate issues
+- **Communication Templates:** Incident communication templates
+- **Post-Incident Reviews:** How to conduct post-mortems
+- **Knowledge Base:** Common issues and their solutions