nodejs-quickstart-structure 1.16.2 → 1.18.0

package/templates/common/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest `main` branch is supported for security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of this project seriously. If you believe you have found a security vulnerability, please report it following these steps:
+
+1. **Do not open a public issue.**
+2. Send an email to the project maintainers (see `package.json`).
+3. Provide a detailed description of the vulnerability, including steps to reproduce.
+
+We will acknowledge your report within 48 hours and work on a fix as soon as possible.

package/templates/common/_github/workflows/{ci.yml → ci.yml.ejs}

@@ -14,17 +14,13 @@ jobs:
 
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        node-version: [20.x, 22.x]
-
     steps:
     - uses: actions/checkout@v4
     
-    - name: Use Node.js ${{ matrix.node-version }}
+    - name: Use Node.js 22.x
       uses: actions/setup-node@v4
       with:
-        node-version: ${{ matrix.node-version }}
+        node-version: 22.x
         cache: 'npm'
         
     - name: Install Dependencies
@@ -33,8 +29,18 @@ 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
+<% if (includeSecurity) { %>
+    - name: SonarQube Scan
+      uses: SonarSource/sonarqube-scan-action@master
+      env:
+        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+<% } %>

package/templates/common/_github/workflows/security.yml.ejs

@@ -0,0 +1,36 @@
+name: Enterprise Security Scan
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 0 * * 1' # Weekly scan
+
+jobs:
+  node-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Snyk to check for vulnerabilities
+        uses: snyk/actions/node@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --severity-threshold=high
+
+  container-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build -t <%= projectName %>:latest .
+      - name: Run Snyk to check Docker image for vulnerabilities
+        uses: snyk/actions/docker@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          image: <%= projectName %>:latest
+          args: --file=Dockerfile --severity-threshold=high --skip-unused-projects

package/templates/common/_husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

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') { -%>
@@ -99,7 +99,7 @@ services:
       - mongodb_data:/data/db
 
   mongo-migrate:
-    image: node:22-alpine
+    image: node:22-slim
     working_dir: /app
     volumes:
       - .:/app
@@ -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',

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/kafka/js/config/kafka.js

@@ -1,8 +1,9 @@
 const { Kafka } = require('kafkajs');
+const { env } = require('./env');
 
 const kafka = new Kafka({
     clientId: 'nodejs-service',
-    brokers: [process.env.KAFKA_BROKER || 'localhost:9092']
+    brokers: [env.KAFKA_BROKER]
 });
 
 module.exports = { kafka };

package/templates/common/kafka/js/config/kafka.spec.js.ejs

@@ -9,6 +9,12 @@ jest.mock('kafkajs', () => {
     };
 });
 
+jest.mock('<% if (architecture === "MVC") { %>@/config/env<% } else { %>@/infrastructure/config/env<% } %>', () => ({
+    env: {
+        KAFKA_BROKER: 'localhost:9092'
+    }
+}));
+
 describe('Kafka Configuration', () => {
     beforeEach(() => {
         jest.clearAllMocks();

package/templates/common/kafka/ts/config/kafka.spec.ts.ejs

@@ -9,6 +9,12 @@ jest.mock('kafkajs', () => {
     };
 });
 
+jest.mock('@/config/env', () => ({
+    env: {
+        KAFKA_BROKER: 'localhost:9092'
+    }
+}));
+
 describe('Kafka Configuration', () => {
     beforeEach(() => {
         jest.clearAllMocks();

package/templates/common/kafka/ts/config/kafka.ts

@@ -1,6 +1,7 @@
 import { Kafka } from 'kafkajs';
+import { env } from '@/config/env';
 
 export const kafka = new Kafka({
     clientId: 'nodejs-service',
-    brokers: [process.env.KAFKA_BROKER || 'localhost:9092']
+    brokers: [env.KAFKA_BROKER]
 });

package/templates/common/package.json.ejs

@@ -11,12 +11,16 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
-    "prepare": "node -e \"try { require('child_process').execSync('husky install'); } catch (e) { console.log('Not a git repository, skipping husky install'); }\"",
+    "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: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"<% } %>
   },
   "dependencies": {
     "express": "^4.18.2",
@@ -62,15 +66,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"<% } %><% } %>,
@@ -82,19 +84,22 @@
     "eslint-plugin-import-x": "^4.6.1",
     "eslint-import-resolver-typescript": "^3.7.0",
     "husky": "^8.0.3",
-    "lint-staged": "^15.4.3"<% if (language === 'TypeScript') { %>,
+    "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",
-    "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/sonar-project.properties.ejs

@@ -0,0 +1,27 @@
+# SonarCloud/SonarQube Project Configuration
+# See https://docs.sonarqube.org/latest/analysis/analysis-parameters/
+
+sonar.projectKey=your-org-key_<%= projectName %>
+sonar.projectName=<%= projectName %>
+sonar.organization=your-org-key
+sonar.projectVersion=1.0.0
+
+# Path to the source directories
+sonar.sources=src
+# Path to the test directories
+sonar.tests=tests
+
+# Language specific settings
+sonar.javascript.environments=node
+sonar.typescript.tsconfigPath=tsconfig.json
+sonar.javascript.lcov.reportPaths=coverage/lcov.info
+
+# Exclusions
+sonar.exclusions=node_modules/**, dist/**, coverage/**, tests/**
+
+# Quality Gates
+sonar.qualitygate.wait=true
+sonar.qualitygate.timeout=300
+
+# Security Hotspots
+sonar.security.reportPaths=snyk-report.json

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);
+  });
+<%_ } _%>
+});

package/templates/mvc/js/src/index.js.ejs

@@ -1,3 +1,4 @@
+const { env } = require('./config/env');
 const express = require('express');
 const cors = require('cors');
 <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>const apiRoutes = require('./routes/api');<%_ } %>
@@ -16,7 +17,6 @@ const { gqlContext } = require('./graphql/context');
 const swaggerUi = require('swagger-ui-express');
 const swaggerSpecs = require('./config/swagger');
 <%_ } -%>
-const { env } = require('./config/env');
 const setupGracefulShutdown = require('./utils/gracefulShutdown');
 
 const app = express();