nodejs-quickstart-structure 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.17.0] - 2026-03-23
+
+### Added
+- **Kafka KRaft Mode Integration**: Modernized Kafka setups across all templates (MVC & Clean Architecture) by completely removing the Zookeeper dependency and enabling KRaft mode in `docker-compose.yml`, reducing project orchestration overhead.
+- **End-to-End (E2E) Verification Framework**: Implemented dedicated Docker container targeted end-to-end tests (`tests/e2e/`) utilizing Supertest via dynamic `SERVER_URL` mapping to eliminate port collisions and test the fully assembled container cluster directly.
+- **Enhanced Validation Pipelines**: Automatically executes the `npm run test:e2e` suite at the conclusion of internal validations across the entire platform matrix for improved CI accountability.
+
+### Refactored
+- **Test Directory Strict Isolation**: Restructured internal code generation workflows (`lib/modules/`) to pipe all generated `.spec` files strictly into a dedicated `tests/unit/` subdirectory, cleanly abstracting unit specifications from end-to-end specifications.
+
+## [1.16.2] - 2026-03-19
+
+### Changed
+- **Major Dependency Upgrades**: Upgraded core CLI dependencies to their latest stable versions for better performance and security:
+  - `commander`: Upgraded from `^13.1.0` to `^14.0.3`.
+  - `ejs`: Upgraded from `^3.1.10` to `^5.0.1`.
+  - `inquirer`: Upgraded from `^12.4.1` to `^13.3.2`.
+- **Verified Compatibility**: Validated the generator across multiple complex project configurations including TypeScript/MVC, JavaScript/Clean Architecture, Kafka messaging, and Redis/PostgreSQL integration.
+- **Update jest.config.js**: Update jest.config.js (or your test runner config) with new global thresholds:
+```
+  globalThreshold: {
+    branches: 70,
+    functions: 80,
+    lines: 80,
+    statements: 80,
+  },
+```
+
 ## [1.16.1] - 2026-03-17
 
 ### Refactored

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Pau Dang
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -18,7 +18,7 @@ A powerful CLI tool to scaffold production-ready Node.js microservices with buil
 - **Communication Flow**: Scaffold APIs using **REST**, **GraphQL** (with Apollo Server), or **Kafka** (event-driven).
 - **Caching Layer**: Choose between **Redis** or built-in **Memory Cache** for data caching.
 - **Centralized Error Handling**: Every project ships with a global error handler, custom error classes and structured JSON error responses — consistent across REST & GraphQL.
-- **Dockerized**: Automatically generates `docker-compose.yml` for DB, Kafka, Redis, and Zookeeper.
+- **Dockerized**: Automatically generates `docker-compose.yml` for DB, Kafka, and Redis.
 - **Database Migrations/Schemas**: Integrated **Flyway** for SQL migrations or **Mongoose** schemas for MongoDB.
 - **Professional Standards**: Generated projects come with highly professional, industry-standard tooling.
 
@@ -35,7 +35,7 @@ We don't just generate boilerplate; we generate **production-ready** foundations
 -   **🔍 Code Quality**: Pre-configured `Eslint` and `Prettier` for consistent coding standards.
 -   **🛡️ Security**: Built-in `Helmet`, `HPP`, `CORS`, and Rate-Limiting middleware.
 -   **🚨 Error Handling**: Centralized global error middleware with custom error classes and structured JSON responses. GraphQL uses Apollo's `formatError` hook; REST uses Express error middleware.
--   **🧪 Testing Excellence**: Integrated `Jest` and `Supertest`. Every generated project maintains **>70% Unit Test coverage** for controllers, services, and resolvers out of the box.
+-   **🧪 Testing Excellence**: Integrated `Jest` and `Supertest`. Every generated project maintains **>80% Unit Test coverage** for controllers, services, and resolvers out of the box.
 -   **🔄 CI/CD Integration**: Pre-configured workflows for **GitHub Actions**, **Jenkins**, and **GitLab CI**.
 -   **⚓ Git Hooks**: `Husky` and `Lint-Staged` to ensure no bad code is ever committed.
 -   **🤝 Reliability**: Health Checks (`/health`) with deep database pings, Infrastructure Retry Logic (handling Docker startup delays), and Graceful Shutdown workflows.
@@ -51,7 +51,7 @@ The CLI supports a massive number of configurations to fit your exact needs:
     -   **Clean Architecture**: 60 variants (Languages × Databases × Communication Patterns × Caching)
 -   **480 Total Scenarios**:
     -   Every combination can be generated with or without (**GitHub Actions CI/CD** / **Jenkins** or **GitLab CI**), tripling the possibilities.
-    -   Every single one of these 480 scenarios is verified to be compatible with our 70% Coverage Threshold policy.
+    -   Every single one of these 480 scenarios is verified to be compatible with our 80% Coverage Threshold policy.
 
 For a detailed list of all supported cases, check out [docs/generateCase.md](docs/generateCase.md).
 

package/bin/index.js

@@ -1,85 +1,90 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { getProjectDetails } from '../lib/prompts.js';
-import { generateProject } from '../lib/generator.js';
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-
-const program = new Command();
-
-program
-    .name('nodejs-quickstart')
-    .description('🚀 CLI to scaffold production-ready Node.js microservices.\n\nGenerates projects with:\n- MVC or Clean Architecture\n- REST or Kafka\n- MySQL, PostgreSQL, or MongoDB\n- Docker, Flyway & Mongoose support')
-    .version(pkg.version, '-v, --version', 'Output the current version')
-    .addHelpText('after', `\n${chalk.yellow('Example:')}\n  $ nodejs-quickstart init   ${chalk.gray('# Start the interactive setup')}\n`);
-
-program
-    .command('init')
-    .description('Initialize a new Node.js project')
-    .option('-n, --project-name <name>', 'Project name')
-    .option('-l, --language <language>', 'Language (JavaScript, TypeScript)')
-    .option('-a, --architecture <architecture>', 'Architecture (MVC, Clean Architecture)')
-    .option('--view-engine <view>', 'View Engine (None, EJS, Pug) - MVC only')
-    .option('-d, --database <database>', 'Database (MySQL, PostgreSQL)')
-    .option('--db-name <name>', 'Database name')
-    .option('-c, --communication <communication>', 'Communication (REST APIs, GraphQL, Kafka)')
-    .option('--ci-provider <provider>', 'CI/CD Provider (None, GitHub Actions, Jenkins)')
-    .option('--caching <type>', 'Caching Layer (None/Redis)')
-    .action(async (options) => {
-        // Fix for Commander camelCase conversion
-        if (options.ciProvider) {
-            options.ciProvider = options.ciProvider;
-        }
-
-        console.log(chalk.blue('Welcome to the Node.js Quickstart Generator!'));
-
-        try {
-            const answers = await getProjectDetails(options);
-            console.log(chalk.green('\nConfiguration received:'));
-            console.log(JSON.stringify(answers, null, 2));
-
-            console.log(chalk.yellow('\nGenerating project...'));
-            await generateProject(answers);
-
-            console.log(chalk.green('\n✔ Project generated successfully!'));
-            
-            console.log(chalk.magenta('\n🚀 Project is AI-Ready!'));
-            console.log(chalk.magenta('-----------------------------------------'));
-            console.log(chalk.magenta('🤖 We detected you are using AI tools.'));
-            console.log(chalk.magenta(`📍 Use Cursor? We've configured '.cursorrules' for you.`));
-            console.log(chalk.magenta(`📍 Use ChatGPT/Gemini? Check the 'prompts/' folder for Agent Skills.`));
-            console.log(chalk.magenta('-----------------------------------------'));
-
-            let manualStartInstructions = `\n${chalk.yellow('Development:')}\n  cd ${answers.projectName}\n  npm install`;
-            
-            const needsInfrastructure = answers.database !== 'None' || answers.caching === 'Redis' || answers.communication === 'Kafka';
-            
-            if (needsInfrastructure) {
-                let servicesToStart = '';
-                if (answers.database !== 'None') servicesToStart += ' db';
-                if (answers.caching === 'Redis') servicesToStart += ' redis';
-                if (answers.communication === 'Kafka') servicesToStart += ' zookeeper kafka';
-                
-                manualStartInstructions += `\n  docker-compose up -d${servicesToStart}  # Start infrastructure first\n  npm run dev`;
-            } else {
-                manualStartInstructions += `\n  npm run dev`;
-            }
-            
-            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}\n\n${chalk.yellow('Production (PM2):')}\n  npm run build\n  npm run deploy\n  npx pm2 logs`));
-
-        } catch (error) {
-            console.error(chalk.red('Error generating project:'), error);
-            process.exit(1);
-        }
-    });
-program.parse(process.argv);
-
-if (!process.argv.slice(2).length) {
-    program.outputHelp();
-}
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getProjectDetails } from '../lib/prompts.js';
+import { generateProject } from '../lib/generator.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+    .name('nodejs-quickstart')
+    .description('🚀 CLI to scaffold production-ready Node.js microservices.\n\nGenerates projects with:\n- MVC or Clean Architecture\n- REST or Kafka\n- MySQL, PostgreSQL, or MongoDB\n- Docker, Flyway & Mongoose support')
+    .version(pkg.version, '-v, --version', 'Output the current version')
+    .addHelpText('after', `\n${chalk.yellow('Example:')}\n  $ nodejs-quickstart init   ${chalk.gray('# Start the interactive setup')}\n`);
+
+program
+    .command('init')
+    .description('Initialize a new Node.js project')
+    .option('-n, --project-name <name>', 'Project name')
+    .option('-l, --language <language>', 'Language (JavaScript, TypeScript)')
+    .option('-a, --architecture <architecture>', 'Architecture (MVC, Clean Architecture)')
+    .option('--view-engine <view>', 'View Engine (None, EJS, Pug) - MVC only')
+    .option('-d, --database <database>', 'Database (MySQL, PostgreSQL)')
+    .option('--db-name <name>', 'Database name')
+    .option('-c, --communication <communication>', 'Communication (REST APIs, GraphQL, Kafka)')
+    .option('--ci-provider <provider>', 'CI/CD Provider (None, GitHub Actions, Jenkins)')
+    .option('--caching <type>', 'Caching Layer (None/Redis)')
+    .action(async (options) => {
+        // Fix for Commander camelCase conversion
+        if (options.ciProvider) {
+            options.ciProvider = options.ciProvider;
+        }
+
+        console.log(chalk.blue('Welcome to the Node.js Quickstart Generator!'));
+
+        try {
+            const answers = await getProjectDetails(options);
+            console.log(chalk.green('\nConfiguration received:'));
+            console.log(JSON.stringify(answers, null, 2));
+
+            console.log(chalk.yellow('\nGenerating project...'));
+            await generateProject(answers);
+
+            console.log(chalk.green('\n✔ Project generated successfully!'));
+            
+            console.log(chalk.magenta('\n🚀 Project is AI-Ready!'));
+            console.log(chalk.magenta('-----------------------------------------'));
+            console.log(chalk.magenta('🤖 We detected you are using AI tools.'));
+            console.log(chalk.magenta(`📍 Use Cursor? We've configured '.cursorrules' for you.`));
+            console.log(chalk.magenta(`📍 Use ChatGPT/Gemini? Check the 'prompts/' folder for Agent Skills.`));
+            console.log(chalk.magenta('-----------------------------------------'));
+
+            let manualStartInstructions = `\n${chalk.yellow('Development:')}\n  cd ${answers.projectName}\n  npm install`;
+            
+            const needsInfrastructure = answers.database !== 'None' || answers.caching === 'Redis' || answers.communication === 'Kafka';
+            
+            if (needsInfrastructure) {
+                let servicesToStart = '';
+                if (answers.database === 'MongoDB') servicesToStart += ' db';
+                else if (answers.database !== 'None') servicesToStart += ' db flyway';
+                if (answers.caching === 'Redis') servicesToStart += ' redis';
+                if (answers.communication === 'Kafka') servicesToStart += ' kafka';
+                
+                manualStartInstructions += `\n  docker-compose up -d${servicesToStart}  # Start infrastructure first\n  npm run dev`;
+            } else {
+                manualStartInstructions += `\n  npm run dev`;
+            }
+            
+            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}\n\n${chalk.yellow('Production (PM2):')}\n  npm run build\n  npm run deploy\n  npx pm2 logs`));
+
+        } catch (error) {
+            if (error.name === 'ExitPromptError') {
+                console.log(chalk.yellow('\n\n👋 Goodbye! Setup cancelled.'));
+                process.exit(0);
+            }
+            console.error(chalk.red('Error generating project:'), error);
+            process.exit(1);
+        }
+    });
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}

package/lib/modules/app-setup.js

@@ -73,7 +73,7 @@ export const renderErrorMiddleware = async (templatePath, targetDir, config) =>
     const specExt = language === 'TypeScript' ? 'ts' : 'js';
     const specTemplatePath = path.join(templatePath, '../../common/src/utils', `errorMiddleware.spec.${specExt}.ejs`);
     if (await fs.pathExists(specTemplatePath)) {
-        const testUtilsDir = path.join(targetDir, 'tests', 'utils');
+        const testUtilsDir = path.join(targetDir, 'tests', 'unit', 'utils');
         await fs.ensureDir(testUtilsDir);
         const specContent = ejs.render(await fs.readFile(specTemplatePath, 'utf-8'), config);
         await fs.writeFile(path.join(testUtilsDir, `errorMiddleware.spec.${specExt}`), specContent);
@@ -89,7 +89,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         const userControllerSpecName = language === 'TypeScript' ? 'userController.spec.ts' : 'userController.spec.js';
         
         const userControllerPath = path.join(targetDir, 'src/controllers', userControllerName);
-        const userControllerSpecPath = path.join(targetDir, 'tests/controllers', userControllerSpecName);
+        const userControllerSpecPath = path.join(targetDir, 'tests/unit/controllers', userControllerSpecName);
         
         const userControllerTemplate = path.join(templatePath, 'src/controllers', `${userControllerName}.ejs`);
         const userControllerSpecTemplate = path.join(templatePath, 'src/controllers', `${userControllerSpecName}.ejs`);
@@ -101,7 +101,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         }
         
         if (await fs.pathExists(userControllerSpecTemplate)) {
-            await fs.ensureDir(path.join(targetDir, 'tests/controllers'));
+            await fs.ensureDir(path.join(targetDir, 'tests/unit/controllers'));
             const content = ejs.render(await fs.readFile(userControllerSpecTemplate, 'utf-8'), { ...config });
             await fs.writeFile(userControllerSpecPath, content);
             await fs.remove(path.join(targetDir, 'src/controllers', `${userControllerSpecName}.ejs`));
@@ -113,7 +113,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         const repoSpecName = language === 'TypeScript' ? 'UserRepository.spec.ts' : 'UserRepository.spec.js';
         
         const repoPath = path.join(targetDir, 'src/infrastructure/repositories', repoName);
-        const repoSpecPath = path.join(targetDir, 'tests/infrastructure/repositories', repoSpecName);
+        const repoSpecPath = path.join(targetDir, 'tests/unit/infrastructure/repositories', repoSpecName);
         
         const repoTemplate = path.join(templatePath, 'src/infrastructure/repositories', `${repoName}.ejs`);
         const repoSpecTemplate = path.join(templatePath, 'src/infrastructure/repositories', `${repoSpecName}.ejs`);
@@ -124,7 +124,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
             await fs.remove(path.join(targetDir, 'src/infrastructure/repositories', `${repoName}.ejs`));
         }
         if (await fs.pathExists(repoSpecTemplate)) {
-            await fs.ensureDir(path.join(targetDir, 'tests/infrastructure/repositories'));
+            await fs.ensureDir(path.join(targetDir, 'tests/unit/infrastructure/repositories'));
             const content = ejs.render(await fs.readFile(repoSpecTemplate, 'utf-8'), { ...config });
             await fs.writeFile(repoSpecPath, content);
             await fs.remove(path.join(targetDir, 'src/infrastructure/repositories', `${repoSpecName}.ejs`));
@@ -134,7 +134,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         const controllerSpecName = language === 'TypeScript' ? 'userController.spec.ts' : 'userController.spec.js';
         
         const controllerPath = path.join(targetDir, 'src/interfaces/controllers', controllerName);
-        const controllerSpecPath = path.join(targetDir, 'tests/interfaces/controllers', controllerSpecName);
+        const controllerSpecPath = path.join(targetDir, 'tests/unit/interfaces/controllers', controllerSpecName);
         
         const controllerTemplate = path.join(templatePath, 'src/interfaces/controllers', `${controllerName}.ejs`);
         const controllerSpecTemplate = path.join(templatePath, 'src/interfaces/controllers', `${controllerSpecName}.ejs`);
@@ -146,7 +146,7 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         }
         
         if (await fs.pathExists(controllerSpecTemplate)) {
-            await fs.ensureDir(path.join(targetDir, 'tests/interfaces/controllers'));
+            await fs.ensureDir(path.join(targetDir, 'tests/unit/interfaces/controllers'));
             const content = ejs.render(await fs.readFile(controllerSpecTemplate, 'utf-8'), { ...config });
             await fs.writeFile(controllerSpecPath, content);
             await fs.remove(path.join(targetDir, 'src/interfaces/controllers', `${controllerSpecName}.ejs`));
@@ -191,9 +191,9 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         // Render health route spec template
         const healthSpecTemplatePath = path.join(templatePath, '../../common/health', healthExt, `healthRoute.spec.${healthExt}.ejs`);
         if (await fs.pathExists(healthSpecTemplatePath)) {
-            let testRouteDestDir = path.join(targetDir, 'tests', 'routes');
+            let testRouteDestDir = path.join(targetDir, 'tests', 'unit', 'routes');
             if (architecture === 'Clean Architecture') {
-                testRouteDestDir = path.join(targetDir, 'tests', 'interfaces', 'routes');
+                testRouteDestDir = path.join(targetDir, 'tests', 'unit', 'interfaces', 'routes');
             }
             await fs.ensureDir(testRouteDestDir);
             const specContent = ejs.render(await fs.readFile(healthSpecTemplatePath, 'utf-8'), config);
@@ -215,13 +215,40 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         // Render graceful shutdown spec template
         const shutdownSpecTemplatePath = path.join(templatePath, '../../common/shutdown', shutdownExt, `gracefulShutdown.spec.${shutdownExt}.ejs`);
         if (await fs.pathExists(shutdownSpecTemplatePath)) {
-            const testUtilsDestDir = path.join(targetDir, 'tests', 'utils');
+            const testUtilsDestDir = path.join(targetDir, 'tests', 'unit', 'utils');
             await fs.ensureDir(testUtilsDestDir);
             const specContent = ejs.render(await fs.readFile(shutdownSpecTemplatePath, 'utf-8'), config);
             await fs.writeFile(path.join(testUtilsDestDir, `gracefulShutdown.spec.${shutdownExt}`), specContent);
         }
     }
 
+    // Advanced E2E Testing Generation
+    const e2eExt = language === 'TypeScript' ? 'ts' : 'js';
+    const e2eTemplatePath = path.join(templatePath, '../../common/src/tests/e2e', `e2e.users.test.${e2eExt}.ejs`);
+
+    if (await fs.pathExists(e2eTemplatePath)) {
+        let e2eDestDir = path.join(targetDir, 'tests', 'e2e');
+        await fs.ensureDir(e2eDestDir);
+
+        const e2eContent = ejs.render(await fs.readFile(e2eTemplatePath, 'utf-8'), { ...config });
+        await fs.writeFile(path.join(e2eDestDir, `e2e.users.test.${e2eExt}`), e2eContent);
+    }
+
+    // E2E Test Orchestrator Generation
+    const e2eOrchestratorTemplatePath = path.join(templatePath, '../../common/scripts', 'run-e2e.js.ejs');
+    if (await fs.pathExists(e2eOrchestratorTemplatePath)) {
+        let scriptsDestDir = path.join(targetDir, 'scripts');
+        await fs.ensureDir(scriptsDestDir);
+
+        const orchestratorContent = ejs.render(await fs.readFile(e2eOrchestratorTemplatePath, 'utf-8'), { ...config });
+        await fs.writeFile(path.join(scriptsDestDir, 'run-e2e.js'), orchestratorContent);
+        
+        // Cleanup the raw ejs copy in target
+        if (await fs.pathExists(path.join(scriptsDestDir, 'run-e2e.js.ejs'))) {
+            await fs.remove(path.join(scriptsDestDir, 'run-e2e.js.ejs'));
+        }
+    }
+
     // GraphQL Setup
     if (config.communication === 'GraphQL') {
         const ext = language === 'TypeScript' ? 'ts' : 'js';
@@ -342,13 +369,23 @@ export const processAllTests = async (targetDir, config) => {
                 await processDir(itemPath);
             } else if (itemPath.endsWith('.spec.ts') || 
                 itemPath.endsWith('.spec.js') || 
+                itemPath.endsWith('.test.ts') || 
+                itemPath.endsWith('.test.js') || 
                 itemPath.endsWith('.spec.ts.ejs') || 
-                itemPath.endsWith('.spec.js.ejs')) {
+                itemPath.endsWith('.spec.js.ejs') || 
+                itemPath.endsWith('.test.ts.ejs') || 
+                itemPath.endsWith('.test.js.ejs')) {
                 const relativePath = path.relative(srcDir, itemPath);
 
                 const cleanRelativePath = relativePath.replace(/\.ejs$/, '');
 
-                const targetTestPath = path.join(testsDir, cleanRelativePath);
+                // Exclude e2e if it accidentally falls here, as it's processed separately
+                if (cleanRelativePath.includes('e2e')) {
+                    await fs.remove(itemPath);
+                    continue;
+                }
+
+                const targetTestPath = path.join(testsDir, 'unit', cleanRelativePath);
 
                 await fs.ensureDir(path.dirname(targetTestPath));
 

package/lib/modules/caching-setup.js

@@ -64,7 +64,7 @@ export const setupCaching = async (templatesDir, targetDir, config) => {
                 const specLoggerPath = architecture === 'Clean Architecture' ? '@/infrastructure/log/logger' : '@/utils/logger';
                 const specRedisPath = architecture === 'Clean Architecture' ? '@/infrastructure/caching/redisClient' : '@/config/redisClient';
                 const specContent = ejs.render(specTemplate, { ...config, loggerPath: specLoggerPath, redisClientPath: specRedisPath });
-                const specTarget = cacheTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
+                const specTarget = cacheTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}unit${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
                 await fs.ensureDir(path.dirname(specTarget));
                 await fs.writeFile(specTarget, specContent);
             }

package/lib/modules/config-files.js

@@ -47,6 +47,11 @@ export const renderProfessionalConfig = async (templatesDir, targetDir, config)
     const jestTemplate = await fs.readFile(path.join(templatesDir, 'common', 'jest.config.js.ejs'), 'utf-8');
     const jestContent = ejs.render(jestTemplate, { ...config });
     await fs.writeFile(path.join(targetDir, 'jest.config.js'), jestContent);
+    
+    // E2E Config
+    const jestE2eTemplate = await fs.readFile(path.join(templatesDir, 'common', 'jest.e2e.config.js.ejs'), 'utf-8');
+    const jestE2eContent = ejs.render(jestE2eTemplate, { ...config });
+    await fs.writeFile(path.join(targetDir, 'jest.e2e.config.js'), jestE2eContent);
 };
 
 export const renderAiNativeFiles = async (templatesDir, targetDir, config) => {

package/lib/modules/database-setup.js

@@ -67,7 +67,7 @@ export const setupDatabase = async (templatesDir, targetDir, config) => {
             if (await fs.pathExists(specTemplateSource)) {
                 const specTemplate = await fs.readFile(specTemplateSource, 'utf-8');
                 const specContent = ejs.render(specTemplate, { ...config });
-                const specTarget = dbConfigTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
+                const specTarget = dbConfigTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}unit${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
                 await fs.ensureDir(path.dirname(specTarget));
                 await fs.writeFile(specTarget, specContent);
             }
@@ -108,7 +108,7 @@ export const generateModels = async (templatesDir, targetDir, config) => {
         if (await fs.pathExists(modelSpecTemplateSource)) {
             const modelSpecTemplate = await fs.readFile(modelSpecTemplateSource, 'utf-8');
             const modelSpecContent = ejs.render(modelSpecTemplate, { ...config });
-            const modelSpecTarget = modelTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
+            const modelSpecTarget = modelTarget.replace(`${path.sep}src${path.sep}`, `${path.sep}tests${path.sep}unit${path.sep}`).replace(`.${langExt}`, `.spec.${langExt}`);
             await fs.ensureDir(path.dirname(modelSpecTarget));
             await fs.writeFile(modelSpecTarget, modelSpecContent);
         }

package/lib/modules/kafka-setup.js

@@ -63,9 +63,9 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
         const specContent = ejs.render(await fs.readFile(kafkaConfigSpecTemplate, 'utf-8'), { ...config });
         let specTarget;
         if (architecture === 'MVC') {
-            specTarget = path.join(targetDir, 'tests', 'config', kafkaConfigSpecFileName);
+            specTarget = path.join(targetDir, 'tests', 'unit', 'config', kafkaConfigSpecFileName);
         } else {
-            specTarget = path.join(targetDir, 'tests', 'infrastructure', 'config', kafkaConfigSpecFileName);
+            specTarget = path.join(targetDir, 'tests', 'unit', 'infrastructure', 'config', kafkaConfigSpecFileName);
         }
         await fs.ensureDir(path.dirname(specTarget));
         await fs.writeFile(specTarget, specContent);
@@ -79,7 +79,7 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
     if (architecture === 'Clean Architecture') {
         // Clean Architecture Restructuring
         await fs.ensureDir(path.join(targetDir, 'src/infrastructure/messaging'));
-        await fs.ensureDir(path.join(targetDir, 'tests/infrastructure/messaging'));
+        await fs.ensureDir(path.join(targetDir, 'tests/unit/infrastructure/messaging'));
         await fs.ensureDir(path.join(targetDir, 'src/infrastructure/config'));
 
         const serviceExt = language === 'TypeScript' ? 'ts' : 'js';
@@ -93,7 +93,7 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
         if (await fs.pathExists(path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`))) {
             await fs.move(
                 path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`),
-                path.join(targetDir, `tests/infrastructure/messaging/kafkaClient.spec.${serviceExt}`),
+                path.join(targetDir, `tests/unit/infrastructure/messaging/kafkaClient.spec.${serviceExt}`),
                 { overwrite: true }
             );
         }
@@ -131,7 +131,7 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             const specTemplateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.spec.${langExt}.ejs`);
             if (await fs.pathExists(specTemplateSource)) {
                 const specContent = ejs.render(await fs.readFile(specTemplateSource, 'utf-8'), { ...config, loggerPath });
-                const specDest = path.join(targetDir, 'tests', `${t.dest}.spec.${langExt}`);
+                const specDest = path.join(targetDir, 'tests', 'unit', `${t.dest}.spec.${langExt}`);
                 await fs.ensureDir(path.dirname(specDest));
                 await fs.writeFile(specDest, specContent);
             }
@@ -162,17 +162,17 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             const specTemplateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.spec.${langExt}.ejs`);
             if (await fs.pathExists(specTemplateSource)) {
                 const specContent = ejs.render(await fs.readFile(specTemplateSource, 'utf-8'), { ...config, loggerPath });
-                const specDest = path.join(targetDir, 'tests', `${t.dest}.spec.${langExt}`);
+                const specDest = path.join(targetDir, 'tests', 'unit', `${t.dest}.spec.${langExt}`);
                 await fs.ensureDir(path.dirname(specDest));
                 await fs.writeFile(specDest, specContent);
             }
         }
 
         if (await fs.pathExists(path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`))) {
-            await fs.ensureDir(path.join(targetDir, 'tests/services'));
+            await fs.ensureDir(path.join(targetDir, 'tests/unit/services'));
             await fs.move(
                 path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`),
-                path.join(targetDir, `tests/services/kafkaService.spec.${serviceExt}`),
+                path.join(targetDir, `tests/unit/services/kafkaService.spec.${serviceExt}`),
                 { overwrite: true }
             );
         }

package/lib/prompts.js

@@ -15,7 +15,7 @@ export const getProjectDetails = async (options = {}) => {
             when: !options.projectName
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'language',
             message: 'Select Language:',
             choices: ['JavaScript', 'TypeScript'],
@@ -23,7 +23,7 @@ export const getProjectDetails = async (options = {}) => {
             when: !options.language
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'architecture',
             message: 'Select Architecture:',
             choices: ['MVC', 'Clean Architecture'],
@@ -31,7 +31,7 @@ export const getProjectDetails = async (options = {}) => {
             when: !options.architecture
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'viewEngine',
             message: 'Select View Engine:',
             choices: ['None', 'EJS', 'Pug'],
@@ -39,7 +39,7 @@ export const getProjectDetails = async (options = {}) => {
             default: 'None'
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'database',
             message: 'Select Database:',
             choices: ['None', 'MySQL', 'PostgreSQL', 'MongoDB'],
@@ -55,7 +55,7 @@ export const getProjectDetails = async (options = {}) => {
             when: (answers) => !options.dbName && (options.database || answers.database) !== 'None'
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'communication',
             message: 'Microservices Communication:',
             choices: ['REST APIs', 'GraphQL', 'Kafka'],
@@ -63,7 +63,7 @@ export const getProjectDetails = async (options = {}) => {
             when: !options.communication
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'caching',
             message: 'Caching Layer:',
             choices: ['None', 'Redis', 'Memory Cache'],
@@ -71,7 +71,7 @@ export const getProjectDetails = async (options = {}) => {
             when: (answers) => !options.caching && (options.database || answers.database) !== 'None'
         },
         {
-            type: 'list',
+            type: 'select',
             name: 'ciProvider',
             message: 'Select CI/CD Provider:',
             choices: ['None', 'GitHub Actions', 'Jenkins', 'GitLab CI'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "type": "module",
   "description": "The ultimate nodejs quickstart structure CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",
@@ -40,10 +40,10 @@
   "license": "ISC",
   "dependencies": {
     "chalk": "^5.4.1",
-    "commander": "^13.1.0",
-    "ejs": "^3.1.10",
+    "commander": "^14.0.3",
+    "ejs": "^5.0.1",
     "fs-extra": "^11.3.0",
-    "inquirer": "^12.4.1"
+    "inquirer": "^13.3.2"
   },
   "files": [
     "bin",

package/templates/common/.cursorrules.ejs

@@ -20,7 +20,7 @@ When indexing or searching the workspace, ignore the following paths to prevent
 
 ### 1. Testing First
 - Every new service or controller method MUST have a test file in `tests/`.
-- **Coverage Gate**: Aim for > 70% coverage (Statement/Line/Function/Branch).
+- **Coverage Gate**: Aim for > 80% coverage (Statement/Line/Function/Branch).
 - **Format**: Use Jest with the AAA (Arrange, Act, Assert) pattern.
 - **Isolation**: Mock external dependencies (DB, Redis, etc.) using `jest.mock()`.
 

package/templates/common/.env.example.ejs

@@ -28,7 +28,7 @@ DB_NAME=<%= dbName %>
 
 <%_ if (communication === 'Kafka') { -%>
 # Communication
-KAFKA_BROKER=localhost:9092
+KAFKA_BROKER=localhost:9093
 KAFKA_CLIENT_ID=<%= projectName %>
 KAFKA_GROUP_ID=<%= projectName %>-group
 <%_ } -%>

package/templates/common/.gitlab-ci.yml.ejs

@@ -22,12 +22,22 @@ lint_code:
   script:
     - npm run lint
 
-run_tests:
+run_unit_tests:
   stage: test
   image: node:22-alpine
   script:
     - npm run test:coverage
 
+run_e2e_tests:
+  stage: test
+  image: docker:20.10.16
+  services:
+    - docker:20.10.16-dind
+  script:
+    - apk add --no-cache nodejs npm docker-compose
+    - npm ci
+    - npm run test:e2e
+
 build_app:
   stage: build
   image: node:22-alpine

package/templates/common/Jenkinsfile.ejs

@@ -19,12 +19,18 @@ pipeline {
             }
         }
 
-        stage('Test') {
+        stage('Unit Test') {
             steps {
                 sh 'npm run test:coverage'
             }
         }
 
+        stage('E2E Test') {
+            steps {
+                sh 'npm run test:e2e'
+            }
+        }
+
         // stage('Build') {
         //     steps {
         //         sh 'npm run build'

package/templates/common/README.md.ejs

@@ -124,7 +124,7 @@ This project demonstrates a production-ready Kafka flow:
 2. **Consumer**: `WelcomeEmailConsumer` listens to `user-topic` and simulates sending an email.
 
 ### How to verify:
-1. Ensure infrastructure is running: `docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> zookeeper kafka<% } %>`
+1. Ensure infrastructure is running: `docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>`
 2. Start the app: `npm run dev`
 3. Trigger an event by creating a user (via Postman or curl):
    ```bash
@@ -167,7 +167,7 @@ To run the Node.js application locally while using Docker for the infrastructure
 
 ```bash
 # Start infrastructure
-docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> zookeeper kafka<% } %>
+docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>
 
 # Start the application
 npm run dev
@@ -215,7 +215,7 @@ npm install
 2. **Start Infrastructure (DB, Redis, Kafka, etc.) in the background**
 *(This specifically starts the background services without running the application inside Docker, allowing PM2 to handle it).*
 ```bash
-docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> zookeeper kafka<% } %>
+docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>
 ```
 3. **Wait 5-10s** for the database to fully initialize.
 4. **Deploy the App using PM2 in Cluster Mode**
@@ -248,6 +248,6 @@ docker-compose down
 This project is "AI-Ready" out of the box. We have pre-configured industry-leading AI context files to bridge the gap between "Generated Code" and "AI-Assisted Development."
 
 - **Magic Defaults**: We've automatically tailored your AI context to focus on **<%= projectName %>** and its specific architectural stack (<%= architecture %>, <%= database %>, etc.).
-- **Use Cursor?** We've configured **`.cursorrules`** at the root. It enforces project standards (70% coverage, MVC/Clean) directly within the editor. 
+- **Use Cursor?** We've configured **`.cursorrules`** at the root. It enforces project standards (80% coverage, MVC/Clean) directly within the editor. 
   - *Pro-tip*: You can customize the `Project Goal` placeholder in `.cursorrules` to help the AI understand your specific business logic!
 - **Use ChatGPT/Gemini/Claude?** Check the **`prompts/`** directory. It contains highly-specialized Agent Skill templates. You can copy-paste these into any LLM to give it a "Senior Developer" understanding of your codebase immediately.

package/templates/common/_github/workflows/ci.yml

@@ -33,8 +33,11 @@ jobs:
     - name: Lint Code
       run: npm run lint
       
-    - name: Run Tests
+    - name: Run Unit Tests
       run: npm run test:coverage
       
+    - name: Run E2E Tests
+      run: npm run test:e2e
+      
     - name: Build
       run: npm run build --if-present

package/templates/common/caching/js/redisClient.spec.js.ejs

@@ -1,5 +1,3 @@
-const Redis = require('ioredis');
-
 jest.mock('ioredis', () => {
   const mRedis = jest.fn(() => ({
     on: jest.fn(),

package/templates/common/docker-compose.yml.ejs

@@ -14,7 +14,7 @@ services:
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
     environment:
-      - KAFKA_BROKER=kafka:29092
+      - KAFKA_BROKER=kafka:9092
       - KAFKAJS_NO_PARTITIONER_WARNING=1
       - PORT=3000
 <%_ if (caching === 'Redis') { -%>
@@ -131,27 +131,20 @@ services:
       - db
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-  zookeeper:
-    image: confluentinc/cp-zookeeper:7.4.0
-    environment:
-      ZOOKEEPER_CLIENT_PORT: 2181
-      ZOOKEEPER_TICK_TIME: 2000
-    ports:
-      - "${ZOOKEEPER_PORT:-2181}:2181"
-
   kafka:
-    image: confluentinc/cp-kafka:7.4.0
-    depends_on:
-      - zookeeper
+    image: bitnamilegacy/kafka:3.4.1-debian-12-r39
     ports:
-      - "${KAFKA_PORT:-9092}:9092"
+      - "${KAFKA_EXTERNAL_PORT:-9093}:9093"
     environment:
-      KAFKA_BROKER_ID: 1
-      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
-      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
-      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
-      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
-      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      - KAFKA_ENABLE_KRAFT=yes
+      - KAFKA_CFG_PROCESS_ROLES=broker,controller
+      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@localhost:9094
+      - KAFKA_CFG_NODE_ID=1
+      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:${KAFKA_PORT:-9093}
+      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,PLAINTEXT_HOST://:9093,CONTROLLER://:9094
+      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
+      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
+      - KAFKA_CFG_INTER_BROKER_LISTENER_NAME=PLAINTEXT
 <%_ } -%>
 <%_ if (caching === 'Redis') { -%>
   redis:

package/templates/common/ecosystem.config.js.ejs

@@ -15,7 +15,7 @@ module.exports = {
       REDIS_PASSWORD: "",
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-      KAFKA_BROKER: "127.0.0.1:9092",
+      KAFKA_BROKER: "127.0.0.1:9093",
       KAFKAJS_NO_PARTITIONER_WARNING: 1,
 <%_ } -%>
 <%_ if (database !== 'None') { -%>

package/templates/common/jest.config.js.ejs

@@ -3,6 +3,7 @@ module.exports = {
   coverageDirectory: 'coverage',
   collectCoverageFrom: ['src/**/*.{js,ts}'],
   testMatch: ['**/*.test.ts', '**/*.test.js', '**/*.spec.ts', '**/*.spec.js'],
+  testPathIgnorePatterns: ['/node_modules/', '/tests/e2e/'],
   <% if (language === 'TypeScript') { %>preset: 'ts-jest',<% } %>
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
@@ -22,10 +23,10 @@ module.exports = {
   ],
   coverageThreshold: {
     global: {
-      branches: 65,
-      functions: 70,
-      lines: 70,
-      statements: 70
+      branches: 70,
+      functions: 80,
+      lines: 80,
+      statements: 80
     }
   }
 };

package/templates/common/jest.e2e.config.js.ejs

@@ -0,0 +1,8 @@
+<%_ if (language === 'TypeScript') { _%>/* eslint-disable @typescript-eslint/no-require-imports */<%_ } _%>
+module.exports = {
+  ...require('./jest.config'),
+  testMatch: ['<rootDir>/tests/e2e/**/*.test.ts', '<rootDir>/tests/e2e/**/*.test.js'],
+  testPathIgnorePatterns: ['/node_modules/'],
+  testTimeout: 30000,
+  clearMocks: true
+};

package/templates/common/package.json.ejs

@@ -16,7 +16,9 @@
 <% } -%>
     "test": "jest",
     "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage"
+    "test:coverage": "jest --coverage",
+    "test:e2e:run": "jest --config ./jest.e2e.config.js --passWithNoTests",
+    "test:e2e": "node scripts/run-e2e.js"
   },
   "dependencies": {
     "express": "^4.18.2",
@@ -62,15 +64,13 @@
     "@types/express": "^4.17.21",
     "@types/cors": "^2.8.17",
     "@types/hpp": "^0.2.3",
-<% if (caching === 'Redis') { %>    "@types/ioredis": "^5.0.0",
-<% } -%>
 <% if (caching === 'Memory Cache') { %>    "@types/node-cache": "^4.2.5",
 <% } -%>
 <% if (database === 'PostgreSQL') { %>    "@types/pg": "^8.10.9",
 <% } -%>
-<%_ if (database === 'MySQL' || database === 'PostgreSQL') { -%>
+<% 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"<% } %><% } %>,
@@ -89,12 +89,14 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
     "@types/jest": "^29.5.14",
-    "supertest": "6.3.3",
+    "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",
-    "supertest": "6.3.3"<% } %>
+    "wait-on": "^7.2.0",
+    "supertest": "^7.1.3"<% } %>
   },
   "lint-staged": {
     "*.{js,ts}": [

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

@@ -21,6 +21,6 @@ Please provide the code implementation following these steps:
 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 > 70%!
+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

@@ -32,7 +32,7 @@ We use the MVC (Model-View-Controller) pattern.
 <% } -%>
 
 ## Core Standards
-1. **Testing**: We enforce > 70% coverage. Tests use Jest and the AAA (Arrange, Act, Assert) pattern.
+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') { -%>

package/templates/common/scripts/run-e2e.js.ejs

@@ -0,0 +1,63 @@
+/* eslint-disable */
+const { execSync } = require('child_process');
+const path = require('path');
+
+// Set a specific port for E2E tests to avoid collisions with local development
+process.env.PORT = '3001';
+const TEST_PORT = process.env.PORT;
+
+const execute = (command) => {
+    console.log(`\n> ${command}`);
+    // Run commands from the project root instead of the scripts folder
+    execSync(command, { stdio: 'inherit', cwd: path.resolve(__dirname, '../') });
+};
+
+let composeCmd = 'docker-compose';
+try {
+    execSync('docker compose version', { stdio: 'ignore' });
+    composeCmd = 'docker compose';
+} catch (e) {
+    // fallback to docker-compose
+}
+
+let currentProcessStartedDocker = false;
+
+try {
+    let isAlreadyUp = false;
+    try {
+        // Silently check if the endpoint is already live (1.5-second timeout)
+        execSync(`npx wait-on http-get://127.0.0.1:${TEST_PORT}/health -t 1500`, { 
+            stdio: 'ignore',
+            cwd: path.resolve(__dirname, '../') 
+        });
+        isAlreadyUp = true;
+    } catch (e) {
+        isAlreadyUp = false;
+    }
+
+    if (isAlreadyUp) {
+        console.log('Infrastructure is already running! Skipping Docker spin-up...');
+    } else {
+        console.log(`Starting Docker Compose infrastructure using '${composeCmd}'...`);
+        execute(`${composeCmd} up -d --build`);
+        currentProcessStartedDocker = true;
+
+        console.log('Waiting for application healthcheck to turn green (120s timeout)...');
+        // Using wait-on to poll the universal /health endpoint injected into all architectures
+        execute(`npx wait-on http-get://127.0.0.1:${TEST_PORT}/health -t 120000`);
+        console.log('Infrastructure is healthy!');
+    }
+
+    console.log('Running E2E tests...');
+    execute('npm run test:e2e:run');
+} catch (error) {
+    console.error('E2E tests failed or infrastructure did not boot in time.');
+    process.exitCode = 1;
+} finally {
+    if (currentProcessStartedDocker) {
+        console.log('Tearing down isolated Docker Compose infrastructure...');
+        execute(`${composeCmd} down`);
+    } else {
+        console.log('Leaving preexisting infrastructure running.');
+    }
+}

package/templates/common/src/tests/e2e/e2e.users.test.js.ejs

@@ -0,0 +1,49 @@
+const request = require('supertest');
+
+const SERVER_URL = process.env.TEST_URL || `http://127.0.0.1:${process.env.PORT || 3001}`;
+
+describe('E2E User Tests', () => {
+  // Global setup and teardown hooks can be added here
+  // typically for database seeding or external authentication checks prior to E2E.
+  const uniqueEmail = `test_${Date.now()}@example.com`;
+
+<%_ if (communication === 'GraphQL') { _%>
+  it('should create a user and verify flow via GraphQL', async () => {
+    const query = `
+      mutation {
+        createUser(name: "Test User", email: "${uniqueEmail}") {
+          id
+          name
+          email
+        }
+      }
+    `;
+    const response = await request(SERVER_URL)
+      .post('/graphql')
+      .send({ query });
+
+    expect(response.statusCode).toBe(200);
+  });
+<%_ } else if (communication === 'Kafka') { _%>
+  it('should trigger Kafka event for user creation', async () => {
+    const response = await request(SERVER_URL)
+      .post('/api/users')
+      .send({ name: 'Test User', email: uniqueEmail });
+
+    // Assuming the API returns 201 or 404 (if no REST endpoint is exposed in Kafka skeleton)
+    expect([201, 202, 404]).toContain(response.statusCode);
+    
+    // Wait for Kafka to process...
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  });
+<%_ } else { _%>
+  it('should create a user successfully via REST', async () => {
+    const response = await request(SERVER_URL)
+      .post('/api/users')
+      .send({ name: 'Test User', email: uniqueEmail });
+
+    // E2E Tests must have strict and deterministic assertions
+    expect(response.statusCode).toBe(201);
+  });
+<%_ } _%>
+});

package/templates/common/src/tests/e2e/e2e.users.test.ts.ejs

@@ -0,0 +1,49 @@
+import request from 'supertest';
+
+const SERVER_URL = process.env.TEST_URL || `http://127.0.0.1:${process.env.PORT || 3001}`;
+
+describe('E2E User Tests', () => {
+  // Global setup and teardown hooks can be added here
+  // typically for database seeding or external authentication checks prior to E2E.
+  const uniqueEmail = `test_${Date.now()}@example.com`;
+
+<%_ if (communication === 'GraphQL') { _%>
+  it('should create a user and verify flow via GraphQL', async () => {
+    const query = `
+      mutation {
+        createUser(name: "Test User", email: "${uniqueEmail}") {
+          id
+          name
+          email
+        }
+      }
+    `;
+    const response = await request(SERVER_URL)
+      .post('/graphql')
+      .send({ query });
+
+    expect(response.statusCode).toBe(200);
+  });
+<%_ } else if (communication === 'Kafka') { _%>
+  it('should trigger Kafka event for user creation', async () => {
+    const response = await request(SERVER_URL)
+      .post('/api/users')
+      .send({ name: 'Test User', email: uniqueEmail });
+
+    // Assuming the API returns 201 or 404 (if no REST endpoint is exposed in Kafka skeleton)
+    expect([201, 202, 404]).toContain(response.statusCode);
+    
+    // Wait for Kafka to process...
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  });
+<%_ } else { _%>
+  it('should create a user successfully via REST', async () => {
+    const response = await request(SERVER_URL)
+      .post('/api/users')
+      .send({ name: 'Test User', email: uniqueEmail });
+
+    // E2E Tests must have strict and deterministic assertions
+    expect(response.statusCode).toBe(201);
+  });
+<%_ } _%>
+});