nodejs-structure-cli 1.0.0

package/templates/common/kafka/ts/messaging/welcomeEmailConsumer.spec.ts.ejs

@@ -0,0 +1,86 @@
+import { WelcomeEmailConsumer } from '<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>@/messaging/consumers/instances/welcomeEmailConsumer<% } %>';
+import logger from '<%= loggerPath %>';
+
+jest.mock('<%= loggerPath %>');
+
+describe('WelcomeEmailConsumer', () => {
+    let consumer: WelcomeEmailConsumer;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        consumer = new WelcomeEmailConsumer();
+    });
+
+    it('should log welcome email simulation for USER_CREATED action', async () => {
+        const data = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'test@example.com'
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Consumer: Received USER_CREATED.')
+        );
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('📧 Sending welcome email to \'test@example.com\'... Done!')
+        );
+    });
+
+    it('should log update simulation for USER_UPDATED action', async () => {
+        const data = {
+            action: 'USER_UPDATED',
+            payload: {
+                id: 1,
+                email: 'updated@example.com'
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Consumer: Received USER_UPDATED.')
+        );
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('🔄 Updating user records for \'1\' (Email: updated@example.com)... Done!')
+        );
+    });
+
+    it('should log deletion simulation for USER_DELETED action', async () => {
+        const data = {
+            action: 'USER_DELETED',
+            payload: {
+                id: 1
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Consumer: Received USER_DELETED.')
+        );
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('🗑️ Cleaning up data for user \'1\'... Done!')
+        );
+    });
+
+    it('should log error for invalid data', async () => {
+        const data = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'invalid-email'
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.error).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Invalid user event data:'),
+            expect.anything()
+        );
+    });
+});

package/templates/common/kafka/ts/messaging/welcomeEmailConsumer.ts.ejs

@@ -0,0 +1,38 @@
+import { BaseConsumer } from '<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/baseConsumer<% } else { %>@/messaging/baseConsumer<% } %>';
+import logger from '<%= loggerPath %>';
+import { UserEventSchema } from '<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/schemas/userEventSchema<% } else { %>@/messaging/schemas/userEventSchema<% } %>';
+import { ERROR_MESSAGES } from '@/utils/errorMessages';
+import { KAFKA_ACTIONS } from '@/utils/kafkaEvents';
+
+export class WelcomeEmailConsumer extends BaseConsumer {
+  topic = 'user-topic';
+  groupId = 'welcome-email-group';
+
+  async handle(data: unknown) {
+    const result = UserEventSchema.safeParse(data);
+    
+    if (!result.success) {
+      logger.error(`[Kafka] ${ERROR_MESSAGES.INVALID_USER_DATA}:`, result.error.format());
+      return;
+    }
+
+    const { action, payload } = result.data;
+
+    switch (action) {
+      case KAFKA_ACTIONS.USER_CREATED:
+        logger.info(`[Kafka] Consumer: Received ${KAFKA_ACTIONS.USER_CREATED}.`);
+        logger.info(`[Kafka] Consumer: 📧 Sending welcome email to '${payload.email}'... Done!`);
+        break;
+      case KAFKA_ACTIONS.USER_UPDATED:
+        logger.info(`[Kafka] Consumer: Received ${KAFKA_ACTIONS.USER_UPDATED}.`);
+        logger.info(`[Kafka] Consumer: 🔄 Updating user records for '${payload.id}' (Email: ${payload.email})... Done!`);
+        break;
+      case KAFKA_ACTIONS.USER_DELETED:
+        logger.info(`[Kafka] Consumer: Received ${KAFKA_ACTIONS.USER_DELETED}.`);
+        logger.info(`[Kafka] Consumer: 🗑️ Cleaning up data for user '${payload.id}'... Done!`);
+        break;
+      default:
+        logger.warn(`[Kafka] Unknown action: ${action}`);
+    }
+  }
+}

package/templates/common/kafka/ts/services/kafkaService.spec.ts.ejs

@@ -0,0 +1,81 @@
+import { KafkaService } from '<% if (architecture === "Clean Architecture") { %>@/infrastructure/messaging/kafkaClient<% } else { %>@/services/kafkaService<% } %>';
+import { kafka } from '<%= configPath %>';
+
+jest.mock('<%= configPath %>', () => ({
+    kafka: {
+        producer: jest.fn().mockReturnValue({
+            connect: jest.fn().mockResolvedValue(undefined),
+            send: jest.fn().mockResolvedValue(undefined),
+            disconnect: jest.fn().mockResolvedValue(undefined),
+        }),
+        consumer: jest.fn().mockReturnValue({
+            connect: jest.fn().mockResolvedValue(undefined),
+            subscribe: jest.fn().mockResolvedValue(undefined),
+            run: jest.fn().mockResolvedValue(undefined),
+            disconnect: jest.fn().mockResolvedValue(undefined),
+        }),
+    },
+}));
+
+jest.mock('<%= loggerPath %>');
+
+describe('KafkaService', () => {
+    let kafkaService: KafkaService;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        kafkaService = new KafkaService();
+    });
+
+    it('should connect producer and consumer', async () => {
+        await kafkaService.connect();
+        const producer = (kafka.producer as jest.Mock).mock.results[0].value;
+        const consumer = (kafka.consumer as jest.Mock).mock.results[0].value;
+
+        expect(producer.connect).toHaveBeenCalled();
+        expect(consumer.connect).toHaveBeenCalled();
+        expect(consumer.subscribe).toHaveBeenCalledWith(expect.objectContaining({ topic: 'user-topic', fromBeginning: true }));
+        expect(consumer.run).toHaveBeenCalled();
+    });
+
+    it('should send a message', async () => {
+        await kafkaService.connect();
+        const topic = 'test-topic';
+        const message = JSON.stringify({ action: 'TEST', payload: { email: 'test@example.com' } });
+        await kafkaService.sendMessage(topic, message);
+        const producer = (kafka.producer as jest.Mock).mock.results[0].value;
+
+        expect(producer.send).toHaveBeenCalledWith({
+            topic,
+            messages: [{ value: message }],
+        });
+    });
+
+    it('should retry connection on failure', async () => {
+        const producer = (kafka.producer as jest.Mock).mock.results[0].value;
+        producer.connect
+            .mockRejectedValueOnce(new Error('Connection failed'))
+            .mockResolvedValueOnce(undefined);
+        
+        jest.useFakeTimers();
+        const connectPromise = kafkaService.connect(2);
+        
+        await jest.advanceTimersByTimeAsync(10000);
+        await connectPromise;
+        
+        expect(producer.connect).toHaveBeenCalledTimes(2);
+    });
+
+    it('should throw error if producer not connected', async () => {
+        await expect(kafkaService.sendMessage('topic', 'msg')).rejects.toThrow('[Kafka] Producer not connected');
+    });
+
+    it('should disconnect producer and consumer', async () => {
+        await kafkaService.disconnect();
+        const producer = (kafka.producer as jest.Mock).mock.results[0].value;
+        const consumer = (kafka.consumer as jest.Mock).mock.results[0].value;
+
+        expect(producer.disconnect).toHaveBeenCalled();
+        expect(consumer.disconnect).toHaveBeenCalled();
+    });
+});

package/templates/common/kafka/ts/services/kafkaService.ts.ejs

@@ -0,0 +1,95 @@
+import { kafka } from '<%= configPath %>';
+import { EachMessagePayload, Producer, Consumer } from 'kafkajs';
+import logger from '<%= loggerPath %>';
+
+export class KafkaService {
+    private producer: Producer;
+    private consumer: Consumer;
+    private isConnected = false;
+    private connectionPromise: Promise<void> | null = null;
+
+    constructor() {
+        this.producer = kafka.producer();
+        this.consumer = kafka.consumer({ groupId: 'test-group' });
+    }
+
+    async connect(retries = 10) {
+        if (this.connectionPromise) return this.connectionPromise;
+
+        this.connectionPromise = (async () => {
+            let attempt = 0;
+            // Auto-register WelcomeEmailConsumer if it exists
+            // Note: Dynamic import used here for simplicity and to avoid startup crashes.
+            // In enterprise production, consider using Dependency Injection.
+            const { WelcomeEmailConsumer } = await import('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>@/messaging/consumers/instances/welcomeEmailConsumer<% } %>');
+            while (attempt < retries) {
+                try {
+                    await this.producer.connect();
+                    await this.consumer.connect();
+                    logger.info('[Kafka] Producer connected successfully');
+                    logger.info('[Kafka] Consumer connected successfully');
+                    this.isConnected = true;
+
+                    try {
+                        const welcomeConsumer = new WelcomeEmailConsumer();
+                        await this.consumer.subscribe({ topic: welcomeConsumer.topic, fromBeginning: true });
+                        logger.info(`[Kafka] Registered consumer for topic: ${welcomeConsumer.topic}`);
+                        
+                        await this.consumer.run({
+                            eachMessage: async (payload) => welcomeConsumer.onMessage(payload),
+                        });
+                    } catch (e) {
+                        // Fallback or no consumers found
+                        logger.warn(`[Kafka] Could not load WelcomeEmailConsumer, using fallback: ${(e as Error).message}`);
+                        await this.consumer.subscribe({ topic: 'user-topic', fromBeginning: true });
+                        await this.consumer.run({
+                            eachMessage: async ({ message }: EachMessagePayload) => {
+                                logger.info(`[Kafka] Consumer: Received message on user-topic: ${message.value?.toString()}`);
+                            },
+                        });
+                    }
+                    return; // Success
+                } catch (error) {
+                    attempt++;
+                    logger.error(`[Kafka] Connection attempt ${attempt} failed:`, (error as Error).message);
+                    if (attempt >= retries) {
+                        throw error;
+                    }
+                    await new Promise(res => setTimeout(res, 3000));
+                }
+            }
+        })();
+
+        return this.connectionPromise;
+    }
+
+    async sendMessage(topic: string, message: string, key?: string) {
+        if (this.connectionPromise) {
+            await this.connectionPromise;
+        }
+
+        if (!this.isConnected) {
+            throw new Error('[Kafka] Producer not connected. Check logs for connection errors.');
+        }
+
+        await this.producer.send({
+            topic,
+            messages: [
+                { key, value: message },
+            ],
+        });
+        try {
+            const parsed = JSON.parse(message);
+            logger.info(`[Kafka] Producer: Sent ${parsed.action} event for '${parsed.payload?.email || 'unknown'}'`);
+        } catch {
+            logger.info(`[Kafka] Producer: Sent message to ${topic}`);
+        }
+    }
+
+    async disconnect() {
+        await this.producer.disconnect();
+        await this.consumer.disconnect();
+    }
+}
+
+export const kafkaService = new KafkaService();

package/templates/common/kafka/ts/utils/kafkaEvents.ts.ejs

@@ -0,0 +1,5 @@
+export enum KAFKA_ACTIONS {
+    USER_CREATED = 'USER_CREATED',
+    USER_UPDATED = 'USER_UPDATED',
+    USER_DELETED = 'USER_DELETED'
+}

package/templates/common/migrate-mongo-config.js.ejs

@@ -0,0 +1,31 @@
+const config = {
+  mongodb: {
+    url: process.env.MONGO_URI || `mongodb://${process.env.DB_HOST || 'localhost'}:27017`,
+    databaseName: process.env.DB_NAME || '<%= dbName %>',
+
+    options: {
+      // useNewUrlParser: true, // No longer needed in Node.js driver v4+
+      // useUnifiedTopology: true, // No longer needed in Node.js driver v4+
+      // connectTimeoutMS: 3600000, // increase connection timeout to 1 hour
+      // socketTimeoutMS: 3600000, // increase socket timeout to 1 hour
+    }
+  },
+
+  // The migrations dir, can be an relative or absolute path. Only edit this when really necessary.
+  migrationsDir: "migrations",
+
+  // The mongodb collection where the applied changes are stored. Only edit this when really necessary.
+  changelogCollectionName: "changelog",
+
+  // The file extension to create migrations and search for in migration dir 
+  migrationFileExtension: ".js",
+
+  // Enable the algorithm to create a checksum of the file contents and use that in the comparison to determine
+  // if the file should be run.  Requires that scripts are coded to be run multiple times.
+  useFileHash: false,
+
+  // Don't change this, unless you know what you are doing
+  moduleSystem: 'commonjs',
+};
+
+module.exports = config;

package/templates/common/migrations/init.js.ejs

@@ -0,0 +1,23 @@
+module.exports = {
+  async up(db, client) {
+    const adminEmail = 'admin@example.com';
+    const existingAdmin = await db.collection('users').findOne({ email: adminEmail });
+
+    if (!existingAdmin) {
+      await db.collection('users').insertOne({
+        name: 'Admin User',
+        email: adminEmail,
+        createdAt: new Date(),
+        updatedAt: new Date()
+      });
+      console.log('Admin User seeded successfully');
+    } else {
+      console.log('Admin User already exists, skipping seed');
+    }
+  },
+
+  async down(db, client) {
+    // Optional: Undo the seed. Usually for seeds we might want to keep data, but strictly speaking 'down' should reverse 'up'.
+    // await db.collection('users').deleteOne({ email: 'admin@example.com' });
+  }
+};

package/templates/common/package.json.ejs

@@ -0,0 +1,137 @@
+{
+  "name": "<%= projectName %>",
+  "version": "1.0.0",
+  "description": "Generated by nodejs-quickstart",
+  "main": "<% if (language === 'TypeScript') { %>dist/index.js<% } else { %>src/index.js<% } %>",
+  "scripts": {
+    "start": "<% if (language === 'TypeScript') { %>node dist/index.js<% } else { %>node src/index.js<% } %>",
+    "dev": "<% if (language === 'TypeScript') { %>nodemon --exec ts-node -r tsconfig-paths/register src/index.ts<% } else { %>nodemon src/index.js<% } %>"<% if (language === 'TypeScript') { %>,
+    "build": "rimraf dist && tsc && tsc-alias<% if (viewEngine && viewEngine !== 'None') { %> && cpx \"src/views/**/*\" dist/views<% } %><% if (communication === 'REST APIs' || communication === 'Kafka') { %> && cpx \"src/**/*.yml\" dist/<% } %>"<% } %>,
+    "deploy": "npx pm2 start ecosystem.config.js --env production",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "prepare": "node -e \"if (require('fs').existsSync('.git')) { try { require('child_process').execSync('husky install', { stdio: 'inherit' }); } catch (e) { console.error('Husky installation failed:', e.message); } }\"",
+<% if (database === 'MongoDB') { %>    "migrate": "migrate-mongo up",
+<% } -%>
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:e2e:run": "jest --config ./jest.e2e.config.js --passWithNoTests",
+    "test:e2e": "node scripts/run-e2e.js"<% if (includeSecurity) { %>,
+    "security:check": "npm audit && npm run snyk:test",
+    "snyk:test": "snyk test"<% } %>
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.5",
+    "jake": "^11.9.5",
+    "micromatch": "^4.0.8",
+    "braces": "^3.0.3",
+    "picomatch": "^4.0.4",
+    "lodash": "^4.17.23"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "dotenv": "^16.3.1",
+    "zod": "^3.22.4",
+<% if (database === 'MySQL') { %>    "mysql2": "^3.6.5",
+    "sequelize": "^6.35.2",
+<% } -%>
+<% if (database === 'PostgreSQL') { %>    "pg": "^8.11.3",
+    "sequelize": "^6.35.2",
+<% } -%>
+<% if (database === 'MongoDB') { %>    "mongoose": "^8.0.3",
+    "migrate-mongo": "^11.0.0",
+<% } -%>
+<% if (communication === 'Kafka') { %>    "kafkajs": "^2.2.4",
+<% } -%>
+<% if (caching === 'Redis') { %>    "ioredis": "^5.3.2",
+<% } -%>
+<% if (caching === 'Memory Cache') { %>    "node-cache": "^5.1.2",
+<% } -%>
+<% if (viewEngine === 'EJS') { %>    "ejs": "^3.1.10",
+<% } -%>
+<% if (viewEngine === 'Pug') { %>    "pug": "^3.0.2",
+<% } -%>
+    "cors": "^2.8.5",
+    "helmet": "^7.1.0",
+    "hpp": "^0.2.3",
+    "express-rate-limit": "^7.1.5",
+    "winston": "^3.11.0",
+    "winston-daily-rotate-file": "^5.0.0",
+    "morgan": "^1.10.0"<% if (communication === 'REST APIs' || communication === 'Kafka') { %>,
+    "swagger-ui-express": "^5.0.0",
+    "yamljs": "^0.3.0"<% } %><% if (communication === 'GraphQL') { %>,
+    "@apollo/server": "^5.5.0",
+    "@as-integrations/express4": "^1.1.2",
+    "graphql": "^16.8.1",
+    "@graphql-tools/merge": "^9.0.3"<% } -%>
+<% if (includeMulter) { %>,
+    "multer": "^1.4.5-lts.1"<% } -%>
+<% if (auth === 'JWT') { %>,
+    "jsonwebtoken": "^9.0.2",
+    "bcryptjs": "^2.4.3"<% } -%>
+<% if (auth === 'Better-Auth') { %>,
+    "better-auth": "^1.1.0"<% } -%>
+<% if (auth === 'OAuth' || googleLogin === 'Google Login') { %>,
+    "passport": "^0.7.0",
+    "passport-google-oauth20": "^2.0.0"<% } %>
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"<% if (language === 'TypeScript') { %>,
+    "typescript": "^5.3.3",
+    "ts-node": "^10.9.2",
+    "@types/node": "^20.10.5",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "@types/hpp": "^0.2.3",
+<% if (includeMulter) { -%>    "@types/multer": "^1.4.11",
+<% } -%>
+<% if (auth === 'JWT') { -%>    "@types/jsonwebtoken": "^9.0.5",
+    "@types/bcryptjs": "^2.4.6",
+<% } -%>
+<% if (auth === 'OAuth' || googleLogin === 'Google Login') { -%>    "@types/passport": "^1.0.16",
+    "@types/passport-google-oauth20": "^2.0.14",
+<% } -%>
+<% if (caching === 'Memory Cache') { %>    "@types/node-cache": "^4.2.5",
+<% } -%>
+<% if (database === 'PostgreSQL') { %>    "@types/pg": "^8.10.9",
+<% } -%>
+<% if (database === 'MySQL' || database === 'PostgreSQL') { -%>
+    "@types/sequelize": "^4.28.19",
+<% } -%>
+    "@types/morgan": "^1.9.9",
+    "rimraf": "^6.0.1"<% if ((viewEngine && viewEngine !== 'None') || communication === 'REST APIs' || communication === 'Kafka') { %>,
+    "cpx2": "^8.0.0"<% } %><% } %>,
+    "eslint": "^10.1.0",
+    "@eslint/js": "^9.20.0",
+    "globals": "^15.14.0",
+    "prettier": "^3.5.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import-x": "^4.6.1",
+    "eslint-import-resolver-typescript": "^3.7.0",
+    "husky": "^8.0.3",
+    "lint-staged": "^15.4.3",
+    "snyk": "^1.1295.0"<% if (language === 'TypeScript') { %>,
+    "typescript-eslint": "^8.24.1",<%_ if (communication === 'REST APIs' || communication === 'Kafka') { %>
+    "@types/swagger-ui-express": "^4.1.6",
+    "@types/yamljs": "^0.2.34",<%_ } %>
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "@types/jest": "^29.5.14",
+    "wait-on": "^7.2.0",
+    "supertest": "^7.1.3",
+    "tsconfig-paths": "^4.2.0",
+    "tsc-alias": "^1.8.10",
+    "@types/supertest": "^6.0.2"<% } else { %>,
+    "jest": "^29.7.0",
+    "wait-on": "^7.2.0",
+    "supertest": "^7.1.3"<% } %>
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/templates/common/prompts/add-feature.md.ejs

@@ -0,0 +1,26 @@
+# Add New Feature
+
+I want to add a new feature to the existing application. 
+Please follow the strict standards defined in the project context.
+
+## Feature Description
+[INSERT EXPLANATION OF WHAT YOU WANT TO ADD HERE]
+
+## Implementation Guidelines
+
+Please provide the code implementation following these steps:
+
+1. **Plan first**: Outline the files you need to create/modify and the logic they'll contain.
+<% if (architecture === 'Clean Architecture') { -%>
+2. **Domain/Entity**: Define the core entity structure or interfaces if applicable.
+3. **Use Case**: Implement the business logic handling the feature.
+4. **Adapter (Controller & Route)**: Create the necessary endpoints and validate input.
+5. **Infrastructure (Repository)**: Implement database queries or external service calls.
+<% } else { -%>
+2. **Model**: Define the database schema/model if applicable.
+3. **Controller**: Implement the business logic and request handling.
+4. **Route**: Create the API endpoints and wire them to the controller.
+<% } -%>
+6. **Testing**: Write comprehensive Jest unit tests covering the "Happy Path" and "Edge Cases/Errors" (AAA pattern). Remember, our coverage requirement is > 80%!
+
+Please provide the plan first so I can review it before we write the code.

package/templates/common/prompts/project-context.md.ejs

@@ -0,0 +1,43 @@
+# Project Context
+
+Hello AI! I am working on a Node.js project. Here is the context to help you understand the architecture, domain, and standards.
+
+## Domain Overview
+**Project Name**: <%= projectName %>
+You are an expert working on **<%= projectName %>**.
+**Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+*(Keep this goal in mind when writing business logic, proposing data schemas, or considering edge cases like security and performance.)*
+
+## Tech Stack
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication Protocol**: <%= communication %>
+<% if (caching !== 'None') { -%>
+- **Caching**: <%= caching %>
+<% } -%>
+
+## High-Level Architecture
+<% if (architecture === 'Clean Architecture') { -%>
+We use Clean Architecture. The project separates concerns into:
+- `src/domain`: Core entities and rules. No external dependencies.
+- `src/usecases`: Application business logic.
+- `src/interfaces`: Adapters (Controllers, Routes) that mediate between the outside world and use cases.
+- `src/infrastructure`: External tools (Database, Web Server, Config, Caching).
+<% } else { -%>
+We use the MVC (Model-View-Controller) pattern.
+- `src/models`: Database schemas/models.
+- `src/controllers`: Handling incoming requests and implementing business logic.
+- `src/routes`: API endpoints mapped to controllers.
+<% } -%>
+
+## Core Standards
+1. **Testing**: We enforce > 80% coverage. Tests use Jest and the AAA (Arrange, Act, Assert) pattern.
+2. **Error Handling**: We use centralized custom errors (e.g., `ApiError`) and global error middleware. Status codes come from standard constants, not hardcoded numbers.
+3. **Paths & Naming**:
+<% if (language === 'TypeScript') { -%>
+   - We use `@/` path aliases for internal imports.
+<% } -%>
+   - Files are mostly `camelCase`.
+
+Please acknowledge you understand this context by saying "Context loaded successfully! How can I help you build the <%= projectName %>?"

package/templates/common/prompts/troubleshoot.md.ejs

@@ -0,0 +1,28 @@
+# Troubleshoot Error
+
+I am encountering an error in the <%= projectName %> application. Please help me diagnose and fix it based on our architectural standards.
+
+## The Error Log / Issue Description
+\`\`\`
+[PASTE YOUR ERROR LOG OR DESCRIBE THE ISSUE HERE]
+\`\`\`
+
+## Context Variables
+- **Architecture**: <%= architecture %>
+- **Language**: <%= language %>
+
+## Guidelines for Fixing
+
+When analyzing this error, please keep these project standards in mind:
+
+1. **Centralized Error Handling**: 
+   - Ensure the error uses the standard custom error classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+   - If an error occurs in a controller, it should be passed to the global error middleware via `throw` (for async handlers, or `next(error)` in MVC).
+2. **Standard Status Codes**:
+   - Verify that appropriate status codes from `httpCodes` are being used correctly, rather than generic 500s unless unexpected.
+3. **Dependencies**:
+   - Check if this is a connection issue (e.g., Database, Kafka, Redis) and see if our standard configuration or health checks provide hints.
+4. **Fix Suggestion**:
+   - Explain *why* the error happened.
+   - Provide a targeted code fix matching our coding style (<%= language %>, <%= architecture %>).
+   - Only modify what is strictly necessary to solve the issue.