nodejs-structure-cli 1.0.0

package/templates/clean-architecture/ts/src/usecases/updateUser.spec.ts.ejs

@@ -0,0 +1,48 @@
+import UpdateUser from '@/usecases/updateUser';
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching !== 'None') { -%>
+import cacheService from '<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>';
+<%_ } -%>
+
+jest.mock('@/infrastructure/repositories/UserRepository');
+<%_ if (caching !== 'None') { -%>
+jest.mock('<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>', () => ({
+    get: jest.fn(),
+    set: jest.fn(),
+    del: jest.fn()
+}));
+<%_ } -%>
+
+describe('UpdateUser UseCase', () => {
+    let updateUser: UpdateUser;
+    let mockUserRepository: jest.Mocked<UserRepository>;
+
+    beforeEach(() => {
+        mockUserRepository = new UserRepository() as jest.Mocked<UserRepository>;
+        updateUser = new UpdateUser(mockUserRepository);
+        jest.clearAllMocks();
+    });
+
+    it('should update and return the user', async () => {
+        const id = 1;
+        const data = { name: 'Updated Name' };
+        const expectedUser = { id, name: 'Updated Name', email: 'test@test.com' };
+
+        mockUserRepository.update.mockResolvedValue(expectedUser as any);
+
+        const result = await updateUser.execute(id, data);
+
+        expect(mockUserRepository.update).toHaveBeenCalledWith(id, data);
+        expect(result).toEqual(expectedUser);
+<%_ if (caching !== 'None') { -%>
+        expect(cacheService.del).toHaveBeenCalledWith('users:all');
+<%_ } %>
+    });
+
+    it('should throw an error if repository fails', async () => {
+        const error = new Error('Database error');
+        mockUserRepository.update.mockRejectedValue(error);
+
+        await expect(updateUser.execute(1, { name: 'Test' })).rejects.toThrow(error);
+    });
+});

package/templates/clean-architecture/ts/src/usecases/updateUser.ts.ejs

@@ -0,0 +1,10 @@
+import User from '../domain/user';
+import { UserRepository } from '../infrastructure/repositories/UserRepository';
+
+export default class UpdateUser {
+    constructor(private userRepository: UserRepository) {}
+
+    async execute(id: string, data: Partial<User>): Promise<User | null> {
+        return await this.userRepository.update(id, data);
+    }
+}

package/templates/clean-architecture/ts/src/utils/errorMessages.ts

@@ -0,0 +1,12 @@
+export const ERROR_MESSAGES = {
+    USER_NOT_FOUND: 'User not found',
+    RESOURCE_NOT_FOUND: 'Resource not found',
+    INVALID_USER_DATA: 'Invalid user event data',
+    INTERNAL_SERVER_ERROR: 'Internal Server Error',
+    BAD_REQUEST: 'Bad Request',
+    FETCH_USERS_ERROR: 'Error fetching users',
+    CREATE_USER_ERROR: 'Error creating user',
+    UPDATE_USER_ERROR: 'Error updating user',
+    DELETE_USER_ERROR: 'Error deleting user',
+    DATABASE_PING_FAILED: 'Health Check Database Ping Failed',
+} as const;

package/templates/clean-architecture/ts/src/utils/errorMiddleware.ts.ejs

@@ -0,0 +1,27 @@
+import { Request, Response } from 'express';
+import logger from '@/infrastructure/log/logger';
+import { ApiError } from '@/errors/ApiError';
+import { HTTP_STATUS } from '@/utils/httpCodes';
+
+export const errorMiddleware = (err: Error, req: Request, res: Response, _next: unknown) => {
+  let error = err;
+
+  if (!(error instanceof ApiError)) {
+    const statusCode = HTTP_STATUS.INTERNAL_SERVER_ERROR;
+    const message = error.message || 'Internal Server Error';
+    error = new ApiError(statusCode, message, false, err.stack);
+  }
+
+  const { statusCode, message } = error as ApiError;
+
+  if (statusCode === HTTP_STATUS.INTERNAL_SERVER_ERROR) {
+    logger.error(`${statusCode} - ${message} - ${req.originalUrl} - ${req.method} - ${req.ip}`);
+    logger.error(error.stack || 'No stack trace');
+  }
+
+  res.status(statusCode).json({
+    statusCode,
+    message,
+    ...(process.env.NODE_ENV === 'development' && { stack: error.stack }),
+  });
+};

package/templates/clean-architecture/ts/src/utils/httpCodes.ts

@@ -0,0 +1,7 @@
+export const HTTP_STATUS = {
+    OK: 200,
+    CREATED: 201,
+    BAD_REQUEST: 400,
+    NOT_FOUND: 404,
+    INTERNAL_SERVER_ERROR: 500
+} as const;

package/templates/common/.cursorrules.ejs

@@ -0,0 +1,60 @@
+# Cursor AI Coding Rules for <%= projectName %>
+
+## Project Context
+You are an expert working on **<%= projectName %>**.
+- **Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication**: <%= communication %>
+
+## Excluded Files/Folders
+When indexing or searching the workspace, ignore the following paths to prevent context pollution:
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.git/`
+
+## Strict Rules
+
+### 1. Testing First
+- Every new service or controller method MUST have a test file in `tests/`.
+- **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()`.
+
+### 2. Error Handling
+- Do NOT use generic `Error`.
+- Use custom classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+<% if (language === 'TypeScript') { -%>
+- Use `HTTP_STATUS` constants from `@/utils/httpCodes` for status codes.
+<% } else { -%>
+- Use `HTTP_STATUS` constants from `../utils/httpCodes.js` for status codes.
+<% } -%>
+
+### 3. File Naming & Style
+- **Controllers**: camelCase (e.g., `userController.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Services**: camelCase (e.g., `userService.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Routes**: camelCase (e.g., `userRoutes.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+<% if (language === 'TypeScript') { -%>
+- **Imports**: Use path aliases (e.g., `@/services/...`) instead of relative paths.
+- **Typing**: Ensure strong typing for interfaces and DTOs. Do not use `any` unless absolutely necessary.
+<% } else { -%>
+- **Imports**: Use relative paths as dictated by the directory structure.
+<% } -%>
+
+### 4. Architecture Standards
+<% if (architecture === 'Clean Architecture') { -%>
+- Enforce strict separation of concerns:
+  - `domain`: Entities and enterprise business rules.
+  - `usecases`: Application business rules.
+  - `interfaces`: Controllers and Routes.
+  - `infrastructure`: Frameworks, Database, Caching, and Web Server.
+- Dependencies point inward toward the `domain`.
+<% } else { -%>
+- Enforce MVC standards:
+  - `models`: Data layer.
+  - `controllers`: Request handlers and business logic.
+  - `routes`: Define endpoints routing to controllers.
+<% } -%>

package/templates/common/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+npm-debug.log
+dist
+.env
+.git
+.gitignore
+README.md
+docker-compose.yml
+test_results.log
+flyway/sql
+.cursorrules
+prompts

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

@@ -0,0 +1,60 @@
+# Application
+PORT=3000
+NODE_ENV=development
+
+<%_ if (database !== 'None') { -%>
+# Database
+<%_ if (database === 'MySQL') { -%>
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=root
+DB_NAME=<%= dbName %>
+<%_ } -%>
+<%_ if (database === 'PostgreSQL') { -%>
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=root
+DB_NAME=<%= dbName %>
+<%_ } -%>
+<%_ if (database === 'MongoDB') { -%>
+DB_HOST=localhost
+DB_PORT=27017
+DB_NAME=<%= dbName %>
+<%_ } -%>
+<%_ } -%>
+
+
+<%_ if (communication === 'Kafka') { -%>
+# Communication
+KAFKA_BROKER=localhost:9093
+KAFKA_CLIENT_ID=<%= projectName %>
+KAFKA_GROUP_ID=<%= projectName %>-group
+<%_ } -%>
+
+<%_ if (caching === 'Redis') { -%>
+# Caching
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+<%_ } -%>
+
+<%_ if (auth === 'JWT') { -%>
+# Auth (JWT)
+JWT_SECRET=your_jwt_secret_here
+JWT_EXPIRES_IN=1d
+<%_ } -%>
+
+<%_ if (auth === 'Better-Auth') { -%>
+# Auth (Better-Auth)
+BETTER_AUTH_SECRET=your_better_auth_secret_here
+BETTER_AUTH_URL=http://localhost:3000
+<%_ } -%>
+
+<%_ if (auth === 'OAuth' || googleLogin === 'Google Login') { -%>
+# OAuth (Google)
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
+<%_ } -%>

package/templates/common/.gitattributes

@@ -0,0 +1,46 @@
+# Enforce LF endings for all text files
+* text=auto eol=lf
+
+# Explicitly handle common text file types
+*.js      text eol=lf
+*.ts      text eol=lf
+*.tsx     text eol=lf
+*.jsx     text eol=lf
+*.mjs     text eol=lf
+*.cjs     text eol=lf
+*.json    text eol=lf
+*.md      text eol=lf
+*.sh      text eol=lf
+*.yml     text eol=lf
+*.yaml    text eol=lf
+*.html    text eol=lf
+*.css     text eol=lf
+*.scss    text eol=lf
+*.less    text eol=lf
+*.graphql text eol=lf
+*.sql     text eol=lf
+*.pug     text eol=lf
+
+# Configuration files
+.env*          text eol=lf
+.editorconfig  text eol=lf
+.prettierrc    text eol=lf
+.eslintrc*     text eol=lf
+.gitignore     text eol=lf
+.dockerignore  text eol=lf
+.gitattributes text eol=lf
+
+# Assets
+*.png     binary
+*.jpg     binary
+*.jpeg    binary
+*.gif     binary
+*.ico     binary
+*.webp    binary
+*.avif    binary
+*.pdf     binary
+*.woff    binary
+*.woff2   binary
+*.ttf     binary
+*.eot     binary
+*.svg     text eol=lf

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

@@ -0,0 +1,86 @@
+variables:
+  NODE_ENV: 'test'
+
+stages:
+  - lint
+  - test
+<% if (includeSecurity) { %>
+  - security
+  - quality
+<% } %>
+  - build
+
+cache:
+  paths:
+    - node_modules/
+
+install_dependencies:
+  stage: .pre
+  image: node:22-slim
+  script:
+    - npm ci
+
+lint_code:
+  stage: lint
+  image: node:22-slim
+  script:
+    - npm run lint
+
+run_unit_tests:
+  stage: test
+  image: node:22-slim
+  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
+<% if (includeSecurity) { %>
+snyk_scan:
+  stage: security
+  image: node:22-alpine
+  script:
+    - npm ci
+    - npm run snyk:test
+  only:
+    - main
+
+snyk_container_scan:
+  stage: security
+  image: docker:20.10.16
+  services:
+    - docker:20.10.16-dind
+  script:
+    - apk add --no-cache nodejs npm
+    - npm install -g snyk
+    - docker build -t <%= projectName %>:latest .
+    - snyk container test <%= projectName %>:latest --file=Dockerfile --severity-threshold=high --skip-unused-projects
+
+sonarqube_check:
+  stage: quality
+  image: 
+    name: sonarsource/sonar-scanner-cli:latest
+    entrypoint: [""]
+  variables:
+    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
+    GIT_DEPTH: "0"
+  cache:
+    key: "${CI_JOB_NAME}"
+    paths:
+      - .sonar/cache
+  script:
+    - sonar-scanner
+  only:
+    - main
+<% } %>
+build_app:
+  stage: build
+  image: node:22-alpine
+  script:
+    - npm run build --if-present

package/templates/common/.lintstagedrc

@@ -0,0 +1,6 @@
+{
+  "*.{js,ts}": [
+    "eslint --fix",
+    "prettier --write"
+  ]
+}

package/templates/common/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/templates/common/.snyk.ejs

@@ -0,0 +1,45 @@
+# Snyk (https://snyk.io) policy file, default is to interrupt on any vulnerability found.
+# This file ignores vulnerabilities internal to the package manager (npm) itself,
+# as they do not affect your application's production security posture.
+version: v1.18.2
+ignore:
+  # Minimatch ReDoS/Complexity in npm internal dependencies
+  SNYK-JS-MINIMATCH-15353387:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  SNYK-JS-MINIMATCH-15353389:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  SNYK-JS-MINIMATCH-15309438:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  # Tar Symlink Attack in npm internal dependencies
+  SNYK-JS-TAR-15456201:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  SNYK-JS-TAR-15416075:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  SNYK-JS-TAR-15307072:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  # Brace-expansion Infinite Loop in npm internal dependencies
+  SNYK-JS-BRACEEXPANSION-15789759:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  SNYK-JS-ISAACSBRACEEXPANSION-15208653:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'
+  # Picomatch ReDoS in npm internal dependencies
+  SNYK-JS-PICOMATCH-15765511:
+    - '*':
+        reason: Internal npm dependency, does not affect application runtime.
+        expires: '2027-03-27T10:00:00.000Z'

package/templates/common/Dockerfile

@@ -0,0 +1,73 @@
+# ==========================================
+# Stage 1: Builder
+# ==========================================
+FROM node:22-alpine AS builder
+
+# Upgrade OS packages to fix upstream vulnerabilities (Snyk-detected)
+RUN apk update && apk upgrade && \
+    apk add --no-cache ca-certificates zlib>=1.3.2-r0 --repository=http://dl-cdn.alpinelinux.org/alpine/edge/main
+
+WORKDIR /app
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
+
+# Upgrade npm using corepack (safer in Alpine)
+RUN corepack enable && corepack prepare npm@11.6.4 --activate
+
+COPY package*.json ./
+COPY tsconfig*.json ./
+
+# Install ALL dependencies (including devDeps for build)
+RUN npm ci --no-audit --no-fund || npm ci --no-audit --no-fund || npm ci --no-audit --no-fund
+
+COPY . .
+
+# Build for production
+<% if (language === 'TypeScript') { %>RUN npm run build<% } %>
+
+# ==========================================
+# Stage 2: Production
+# ==========================================
+FROM node:22-alpine AS production
+
+# Upgrade OS packages to fix upstream vulnerabilities (Snyk-detected)
+RUN apk update && apk upgrade && \
+    apk add --no-cache ca-certificates zlib>=1.3.2-r0 --repository=http://dl-cdn.alpinelinux.org/alpine/edge/main
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
+
+# Upgrade npm using corepack (safer in Alpine)
+RUN corepack enable && corepack prepare npm@11.6.4 --activate
+
+COPY package*.json ./
+
+# Install ONLY production dependencies
+RUN npm ci --only=production --ignore-scripts --no-audit --no-fund || npm ci --only=production --ignore-scripts --no-audit --no-fund || npm ci --only=production --ignore-scripts --no-audit --no-fund
+
+# Remove npm and caches to achieve Zero-Vulnerability status in the final image
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx /root/.npm /root/.cache
+
+# Copy built artifacts from builder
+<% if (language === 'TypeScript') { %>
+COPY --from=builder /app/dist ./dist
+<% } else { %>
+COPY --from=builder /app/src ./src
+<% } %>
+
+# Copy other necessary files (like views if MVC)
+<% if (viewEngine && viewEngine !== 'None') { %>
+COPY --from=builder /app/src/views ./dist/views
+<% if (viewEngine && viewEngine !== 'None') { %>COPY --from=builder /app/public ./public<% } %>
+<% } %>
+
+EXPOSE 3000
+
+# Create logs directory and give permissions to node user
+RUN mkdir -p logs && chown -R node:node logs
+
+USER node
+
+# Start application directly with node (safe even without npm)
+CMD ["node", "<% if (language === 'TypeScript') { %>dist/index.js<% } else { %>src/index.js<% } %>"]

package/templates/common/Jenkinsfile.ejs

@@ -0,0 +1,87 @@
+pipeline {
+    agent any
+
+    environment {
+        CI = 'true'
+    }
+
+    stages {
+        stage('Install Dependencies') {
+            steps {
+                // Use npm ci for clean install if package-lock.json exists, else npm install
+                sh 'if [ -f package-lock.json ]; then npm ci; else npm install; fi'
+            }
+        }
+
+        stage('Lint') {
+            steps {
+                sh 'npm run lint'
+            }
+        }
+
+        stage('Unit Test') {
+            steps {
+                sh 'npm run test:coverage'
+            }
+        }
+
+        stage('E2E Test') {
+            steps {
+                sh 'npm run test:e2e'
+            }
+        }
+
+<% if (includeSecurity) { %>
+        stage('SonarQube Analysis') {
+            environment {
+                scannerHome = tool 'SonarScanner'
+            }
+            steps {
+                withSonarQubeEnv('SonarQube') {
+                    sh "${scannerHome}/bin/sonar-scanner"
+                }
+            }
+        }
+
+        stage('Security Scan') {
+            steps {
+                sh 'npm audit --audit-level=high'
+                sh 'npm run snyk:test'
+            }
+        }
+
+        stage('Snyk Container Scan') {
+            steps {
+                script {
+                    sh 'docker build -t <%= projectName %>:latest .'
+                    sh 'snyk container test <%= projectName %>:latest --file=Dockerfile --severity-threshold=high --skip-unused-projects'
+                }
+            }
+        }
+<% } %>
+        // stage('Docker Build & Push') {
+        //     steps {
+        //         script {
+        //             docker.withRegistry('https://registry.hub.docker.com', 'docker-hub-credentials') {
+        //                 def appImage = docker.build("my-image:${env.BUILD_ID}")
+        //                 appImage.push()
+        //                 appImage.push("latest")
+        //             }
+        //         }
+        //     }
+        // }
+
+        // stage('Deploy to Staging') {
+        //     steps {
+        //         sh './scripts/deploy.sh staging'
+        //     }
+        // }
+    }
+
+    post {
+        always {
+            // Clean up workspace
+            cleanWs()
+        }
+    }
+}