nodejs-quickstart-structure 1.19.1 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.1] - 2026-04-07
+
+### Added
+- **Universal CI/CD Support (Phase 8)**: Expanded the generator's CI/CD capabilities to include out-of-the-box support for **Bitbucket Pipelines** and **CircleCI**.
+- **Modernized Pipe & Orb Integration**: 
+  - Bitbucket templates now utilize official Atlassian Pipes for automated Snyk security scans and SonarCloud analysis.
+  - CircleCI configurations (v2.1) are optimized with official Orbs (`circleci/node`, `snyk/snyk`) for advanced dependency caching and security execution.
+- **Project Blueprints (CI/CD Guide)**: Launched a comprehensive "CI/CD Setup Guide" in the VitePress documentation, providing step-by-step configuration workflows for all 5 supported platforms (GitHub, GitLab, Jenkins, Bitbucket, CircleCI).
+- **CLI Ecosystem Sync**: Updated the interactive prompts and command-line flags to seamlessly integrate the new CI/CD choices while maintaining 100% backward compatibility.
+- **Enterprise Readness Documentation**: Updated the generated `README.md` templates to officially include Bitbucket and CircleCI in the supported feature set.
+
+
+## [2.0.0] - 2026-04-02
+
+### Added
+- **Next-Gen Web UI Configurator (v2.0.0)**: Launched a fully interactive, browser-based visual generator featuring real-time architecture visualization. 
+- **1,680+ Combinations Automated**: Mapped out the entire 1:1 file logic for the permutations mathematically validated across Clean Architecture, MVC, WebSockets, Kafka, Docker, databases, etc.
+- **AI-Native Discovery Protocol**: Integrated `llms.txt` standards across the repository and documentation to provide explicit architectural context for AI coding assistants (Claude, GPT-4, Cursor).
+- **Growth-Driven Developer Experience**: Orchestrated a high-conversion "Star on GitHub" funnel within the CLI and Web Configurator to bridge the gap between downloads and community support.
+- **Zero-Impact CLI Parity**: Advanced flag generation system in the Web UI allows 1-click clipboard exporting to seamlessly execute the backend `init` command without hanging on any interactive prompts.
+- **Exhaustive 1,680 Validation Script**: Introduced automation logic to assert successful output generation spanning every configuration option matrix.
+- **Strategic Social Proof**: Re-engineered the project's documentation and landing page to emphasize real-world adoption (4,000+ downloads) and architectural credibility.
+
 ## [1.19.1] - 2026-04-01
 
 ### Fixed

package/README.md

@@ -5,18 +5,42 @@
 [![npm monthly downloads](https://img.shields.io/npm/dm/nodejs-quickstart-structure.svg?style=flat-square)](https://www.npmjs.com/package/nodejs-quickstart-structure)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://opensource.org/licenses/ISC)
 
-A powerful CLI tool to scaffold production-ready Node.js microservices with built-in best practices, allowing you to choose between **MVC** or **Clean Architecture**, **JavaScript** or **TypeScript**, and your preferred database.
+### 📈 Real-world Adoption
+| **Metric** | **Insight** |
+| :--- | :--- |
+| 🔥 **4,000+** | Downloads on npm |
+| 🚀 **1,200+** | Recent GitHub Clones |
+| 🌍 **Trusted by** | Devs from **Google**, **Viblo**, and global tech teams |
+
+---
+
+A powerful CLI tool to scaffold production-ready Node.js microservices with built-in best practices. Choose between **MVC** or **Clean Architecture**, **JavaScript** or **TypeScript**, and your preferred tech stack in seconds.
+
+🎯 **[Try the Next-Gen Web UI Configurator!](https://paudang.github.io/nodejs-quickstart-structure/)**
+*Generate your exact architecture in the browser with real-time folder simulation.*
 
 ![Demo](docs/demo.gif)
 
 ---
 
+## 🆕 What's New in v2.0.0
+
+The v2.0.0 release is a major leap forward, turning the generator into a **Community Standard** for Node.js development:
+
+- **Next-Gen Web UI Configurator**: A modern, browser-based visual project simulator. Click your stack and copy the generated zero-prompt CLI command instantly! [Try it here](https://paudang.github.io/nodejs-quickstart-structure/).
+- **🦾 AI-Native Foundation**: Built-in `.cursorrules` and Agent skills optimized for **Cursor** & AI coding assistants.
+- **🏗️ Enterprise Clean Architecture**: High-fidelity structure for professional Microservices (TS/JS).
+- **🛡️ Hardened Security**: Integrated Snyk & SonarCloud logic in the core templates.
+- **⚡ Zero-Prompt Workflow**: Generate projects with a single CLI command—no more answering prompts manually.
+
+---
+
 ## 📌 Table of Contents
 
 - [🚀 Quick Start](#-quick-start)
 - [✨ Key Features](#-key-features)
 - [🛡️ Professional Standards](#-professional-standards)
-- [🧩 1,680+ Project Combinations](#-1680-project-combinations)
+- [🧩 2,640+ Project Combinations](#-2640-project-combinations)
 - [⚙️ Configuration Options](#-configuration-options)
 - [🏗️ Generated Project Structure](#-generated-project-structure)
 - [📖 Documentation](#-documentation)
@@ -53,7 +77,6 @@ nodejs-quickstart init
 - **Communication Patterns**: Supports **REST**, **GraphQL** (Apollo), and **Kafka** (Event-driven).
 - **Multi-layer Caching**: Integrated **Redis** or built-in **Memory Cache**.
 - **AI-Native Optimized**: specifically designed for **Cursor** and AI agents, including built-in `.cursorrules` and Agent Skill prompts. 🚀
-- **Next Gen Web UI**: (Coming Soon) A modern, browser-based project selector featuring real-time virtualization — set for release in v2.0.0!
 
 ---
 
@@ -65,19 +88,19 @@ We don't just generate boilerplate; we generate **production-ready** foundations
 - **🛡️ Enterprise Security**: Integrated **Snyk (SCA)**, **SonarCloud (SAST)**, `Helmet`, `HPP`, and Rate-Limiting.
 - **🚨 Robust Error Handling**: Centralized global error middleware with custom error classes (`ApiError`, `NotFoundError`, etc.) — consistent across REST & GraphQL.
 - **🧪 Testing Excellence**: Integrated `Jest` and `Supertest` with **>80% Unit Test coverage** out of the box.
-- **🔄 DevOps & CI/CD**: Optimized **Multi-Stage Dockerfiles**, health checks, infrastructure retry logic, and workflows for **GitHub Actions**, **Jenkins**, and **GitLab CI**.
+- **🔄 DevOps & CI/CD**: Optimized **Multi-Stage Dockerfiles**, health checks, infrastructure retry logic, and workflows for **GitHub Actions**, **Jenkins**, **GitLab CI**, **CircleCI**, and **Bitbucket Pipelines**.
 - **🚀 Scalable Deployment**: Integrated **PM2 Ecosystem** config for zero-downtime reloads.
 
 ---
 
-## 🧩 1,680+ Project Combinations
+## 🧩 2,640+ Project Combinations
 
 The CLI supports a massive number of configurations to fit your exact needs:
 
 - **240 Core Combinations**:
   - **MVC Architecture**: 180 variants (Languages × View Engines × Databases × Communication Patterns × Caching)
   - **Clean Architecture**: 60 variants (Languages × Databases × Communication Patterns × Caching)
-- **1,680+ Total Scenarios**:
+- **2,640+ Total Scenarios**:
   - Every combination can be generated across 3 CI/CD providers.
   - Optional **Enterprise-Grade Security Hardening** doubles the scenarios.
   - Every single scenario is verified to be compatible with our **80% Coverage Threshold** policy.
@@ -94,14 +117,13 @@ The CLI will guide you through:
 5. **Database**: `MySQL` | `PostgreSQL` | `MongoDB`
 6. **Communication**: `REST` | `GraphQL` | `Kafka`
 7. **Caching**: `None` | `Redis` | `Memory Cache`
-8. **CI/CD**: `GitHub Actions` | `Jenkins` | `GitLab CI`
+8. **CI/CD**: `GitHub Actions` | `Jenkins` | `GitLab CI` | `CircleCI` | `Bitbucket Pipelines`
 9. **Security**: (Optional) Snyk & SonarCloud Hardening
 
 ---
 
 ## 🏗️ Generated Project Structure
-
-A typical generated project (TypeScript + Clean Architecture) looks like this:
+Depending on your choices, the structure adapts. Here is a **TypeScript + Clean Architecture** preview:
 
 ```text
 .
@@ -111,12 +133,13 @@ A typical generated project (TypeScript + Clean Architecture) looks like this:
 │   ├── infrastructure/  # DB, External services, Repositories
 │   ├── interfaces/      # Controllers, Routes, GraphQL, Kafka
 │   ├── errors/          # Custom Error Classes
-│   └── index.ts         # Entry point
+│   ├── config/          # Environment & Global settings
+│   └── index.ts         # Server entry point
 ├── flyway/sql/          # SQL migrations (if applicable)
 ├── docker-compose.yml   # Infrastructure services
 ├── package.json         # Scripts and dependencies
-├── tsconfig.json        # TypeScript config
-└── .cursorrules         # AI assistance rules
+├── .cursorrules         # AI assistance rules (The "AI Brain")
+└── .env.example         # Environment template
 ```
 
 ---
@@ -130,9 +153,9 @@ For full guides, architecture deep-dives, and feature references, visit our **[O
 ## ❤️ Support & 🗺️ Roadmap
 
 ### Support the Project
-We just hit **3,000+ downloads**! If this tool helped you, please:
-- Give us a ⭐ on [GitHub](https://github.com/paudang/nodejs-quickstart-structure).
-- Read our [Medium Article](https://medium.com/@paudang/nodejs-quickstart-generator-93c276d60e0b) for tutorials.
+If this tool helped you build your project faster, please support us:
+- Give us a ⭐ on [GitHub](https://github.com/paudang/nodejs-quickstart-structure) to help us reach our next milestone!
+- Read our [Medium Series](https://medium.com/@paudang/nodejs-quickstart-generator-93c276d60e0b) for architecture deep-dives.
 
 ### Roadmap
 Track our progress and vote for features on our public board:
@@ -140,6 +163,18 @@ Track our progress and vote for features on our public board:
 
 ---
 
+## ⭐ Why Star us?
+
+We are on a mission to build the best AI-Native Node.js scaffolding experience. Your star is not just a "like"—it's a vote of confidence that helps us:
+
+1. **Attract Contributors**: More stars attract professional maintainers to keep this project secure and up-to-date.
+2. **AI Model Awareness**: Popular repositories are weighted higher by AI coding assistants (Cursor, Copilot, etc.), making the generated code even better.
+3. **Open Source Sustainability**: It motivates us to keep building and shipping "Enterprise-Grade" features for free.
+
+If this tool saved you hours of work, **[please give us a Star!](https://github.com/paudang/nodejs-quickstart-structure)** 🚀
+
+---
+
 ## License
 
 ISC

package/bin/index.js

@@ -29,8 +29,9 @@ program
     .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, GitLab CI)')
+    .option('--ci-provider <provider>', 'CI/CD Provider (None, GitHub Actions, Jenkins, GitLab CI, Bitbucket Pipelines, CircleCI)')
     .option('--include-security', 'Include Enterprise Security Hardening')
+    .option('--no-include-security', 'Exclude Enterprise Security Hardening')
     .option('--caching <type>', 'Caching Layer (None/Redis)')
     .action(async (options) => {
         // Fix for Commander camelCase conversion
@@ -74,7 +75,12 @@ program
             
             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`));
 
-            console.log(chalk.yellow(`\n⭐ If this tool saved you 5 minutes, please give us a star on GitHub: ${chalk.underline('https://github.com/paudang/nodejs-quickstart-structure')}`));
+            console.log(chalk.magenta('\n' + '★'.repeat(50)));
+            console.log(chalk.white.bold('  Enjoying the Node.js Quickstart Generator?'));
+            console.log(chalk.white(`  If this tool saved you 4+ hours of architecture setup,`));
+            console.log(chalk.white(`  please help us grow by giving us a ⭐ on GitHub!`));
+            console.log(chalk.white(`\n  👉 ${chalk.underline.bold('https://github.com/paudang/nodejs-quickstart-structure')}`));
+            console.log(chalk.magenta('★'.repeat(50) + '\n'));
 
         } catch (error) {
             if (error.name === 'ExitPromptError') {

package/lib/modules/config-files.js

@@ -120,6 +120,16 @@ export const setupCiCd = async (templatesDir, targetDir, config) => {
         const gitlabTemplate = await fs.readFile(path.join(templatesDir, 'common', '.gitlab-ci.yml.ejs'), 'utf-8');
         const gitlabContent = ejs.render(gitlabTemplate, { ...config });
         await fs.writeFile(path.join(targetDir, '.gitlab-ci.yml'), gitlabContent);
+    } else if (ciProvider === 'Bitbucket Pipelines') {
+        const bitbucketTemplate = await fs.readFile(path.join(templatesDir, 'common', 'bitbucket-pipelines.yml.ejs'), 'utf-8');
+        const bitbucketContent = ejs.render(bitbucketTemplate, { ...config });
+        await fs.writeFile(path.join(targetDir, 'bitbucket-pipelines.yml'), bitbucketContent);
+    } else if (ciProvider === 'CircleCI') {
+        const circleCiDir = path.join(targetDir, '.circleci');
+        await fs.ensureDir(circleCiDir);
+        const circleCiTemplate = await fs.readFile(path.join(templatesDir, 'common', '_circleci/config.yml.ejs'), 'utf-8');
+        const circleCiContent = ejs.render(circleCiTemplate, { ...config });
+        await fs.writeFile(path.join(circleCiDir, 'config.yml'), circleCiContent);
     }
 };
 

package/lib/prompts.js

@@ -74,7 +74,7 @@ export const getProjectDetails = async (options = {}) => {
             type: 'select',
             name: 'ciProvider',
             message: 'Select CI/CD Provider:',
-            choices: ['None', 'GitHub Actions', 'Jenkins', 'GitLab CI'],
+            choices: ['None', 'GitHub Actions', 'Jenkins', 'GitLab CI', 'CircleCI', 'Bitbucket Pipelines'],
             default: 'None',
             when: !options.ciProvider
         },
@@ -84,7 +84,7 @@ export const getProjectDetails = async (options = {}) => {
             message: 'Include Enterprise Security Hardening (Big Tech Standard: Snyk, SonarQube)?',
             choices: ['No', 'Yes'],
             default: "No",
-            when: (answers) => !options.includeSecurity && (options.ciProvider || answers.ciProvider) !== 'None'
+            when: (answers) => options.includeSecurity === undefined && (options.ciProvider || answers.ciProvider) !== 'None'
         }
     ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.19.1",
+  "version": "2.0.1",
   "type": "module",
   "description": "The ultimate nodejs quickstart structure CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",
@@ -12,6 +12,7 @@
     "test:e2e": "npm run test:e2e:windows",
     "test:e2e:windows": "node scripts/validate-windows.js",
     "test:e2e:linux": "node scripts/validate-linux.js",
+    "test:validate-command": "node scripts/validate-command.js",
     "test:verify:mongo": "node scripts/verify-migration.js",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
@@ -75,4 +76,4 @@
     "README.md",
     "CHANGELOG.md"
   ]
-}
+}

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

@@ -1,5 +1,7 @@
 variables:
   NODE_ENV: 'test'
+  WAIT_ON_HOST: docker
+  TEST_URL: http://docker:3001
 
 stages:
   - lint
@@ -30,7 +32,7 @@ run_unit_tests:
   stage: test
   image: node:22-slim
   script:
-    - npm run test:coverage
+    - npm run test:coverage -- --maxWorkers=2
 
 run_e2e_tests:
   stage: test

package/templates/common/Jenkinsfile.ejs

@@ -3,6 +3,15 @@ pipeline {
 
     environment {
         CI = 'true'
+        DOCKER_BUILDKIT = '0'
+        PORT = '3001'
+        DB_PORT = '3307'
+        WAIT_ON_HOST = 'host.docker.internal'
+        TEST_URL = 'http://host.docker.internal:3001'
+    }
+
+    tools {
+        nodejs 'nodejs'
     }
 
     stages {
@@ -21,7 +30,7 @@ pipeline {
 
         stage('Unit Test') {
             steps {
-                sh 'npm run test:coverage'
+                sh 'npm run test:coverage -- --maxWorkers=2'
             }
         }
 

package/templates/common/README.md.ejs

@@ -31,7 +31,7 @@ This project follows a strict **7-Step Production-Ready Process** to ensure qual
 -   **Database**: <%= database %> <% if (database !== 'None') { %>(via <%= database === 'MongoDB' ? 'Mongoose' : 'Sequelize' %>)<% } %>.
 -   **Security**: Helmet, CORS, Rate Limiting, HPP, Snyk SCA.
 -   **Quality**: 80%+ Test Coverage, Eslint, Prettier, Husky.
--   **DevOps**: Multi-stage Docker, CI/CD ready (GitHub/GitLab/Jenkins).
+-   **DevOps**: Multi-stage Docker, CI/CD ready (GitHub/GitLab/Jenkins/Bitbucket/CircleCI).
 <% if (includeSecurity) { %>-   **Enterprise Hardening**: SonarCloud SAST, Security Policies.<% } %>
 
 ## 📂 Project Structure

package/templates/common/_circleci/config.yml.ejs

@@ -0,0 +1,96 @@
+version: 2.1
+
+orbs:
+  node: circleci/node@5.2.0
+<% if (includeSecurity) { %>
+  snyk: snyk/snyk@2.1.0
+<% } %>
+
+executors:
+  node-executor:
+    docker:
+      - image: cimg/node:22.0
+  machine-executor:
+    machine:
+      image: ubuntu-2204:current
+
+jobs:
+  lint:
+    executor: node-executor
+    steps:
+      - checkout
+      - node/install-packages
+      - run: npm run lint
+
+  unit_test:
+    executor: node-executor
+    steps:
+      - checkout
+      - node/install-packages
+      - run:
+          name: Run Unit Tests with Coverage
+          command: npm run test:coverage -- --maxWorkers=2
+
+  e2e_test:
+    executor: machine-executor
+    steps:
+      - checkout
+      - node/install:
+          node-version: '22.0'
+      - run: npm ci
+      - run: npm run test:e2e
+
+<% if (includeSecurity) { %>
+  security_scan:
+    executor: node-executor
+    steps:
+      - checkout
+      - node/install-packages
+      - snyk/scan:
+          fail-on-issues: true
+          severity-threshold: high
+
+  sonarqube_analysis:
+    executor: node-executor
+    steps:
+      - checkout
+      - node/install-packages
+      - run:
+          name: SonarQube Analysis
+          command: |
+            # Assuming sonar-scanner is available or run via npx
+            npx sonar-scanner
+<% } %>
+
+  build:
+    executor: node-executor
+    steps:
+      - checkout
+      - node/install-packages
+      - run: npm run build --if-present
+
+workflows:
+  build_and_test:
+    jobs:
+      - lint
+      - unit_test:
+          requires:
+            - lint
+      - e2e_test:
+          requires:
+            - unit_test
+<% if (includeSecurity) { %>
+      - security_scan:
+          requires:
+            - unit_test
+      - sonarqube_analysis:
+          requires:
+            - unit_test
+<% } %>
+      - build:
+          requires:
+            - e2e_test
+<% if (includeSecurity) { %>
+            - security_scan
+            - sonarqube_analysis
+<% } %>

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

@@ -30,7 +30,7 @@ jobs:
       run: npm run lint
       
     - name: Run Unit Tests
-      run: npm run test:coverage
+      run: npm run test:coverage -- --maxWorkers=2
       
     - name: Run E2E Tests
       run: npm run test:e2e

package/templates/common/bitbucket-pipelines.yml.ejs

@@ -0,0 +1,60 @@
+image: node:22-slim
+
+pipelines:
+  default:
+    - step:
+        name: Install Dependencies
+        caches:
+          - node
+        script:
+          - npm ci
+    - parallel:
+        - step:
+            name: Lint Code
+            script:
+              - npm ci
+              - npm run lint
+        - step:
+            name: Run Unit Tests
+            script:
+              - npm ci
+              - npm run test:coverage -- --maxWorkers=2
+    - step:
+        name: Run E2E Tests
+        image: docker:20.10.16
+        services:
+          - docker
+        script:
+          - apk add --no-cache nodejs npm docker-compose
+          - npm ci
+          - export DOCKER_BUILDKIT=0
+          - npm run test:e2e
+<% if (includeSecurity) { %>
+    - parallel:
+        - step:
+            name: Snyk Security Scan
+            script:
+              - pipe: snyk/snyk-scan:1.0.0
+                variables:
+                  SNYK_TOKEN: $SNYK_TOKEN
+                  LANGUAGE: "npm"
+                  SEVERITY_THRESHOLD: "high"
+        - step:
+            name: SonarQube Analysis
+            script:
+              - pipe: sonarsource/sonarcloud-scan:2.0.0
+                variables:
+                  SONAR_TOKEN: $SONAR_TOKEN
+<% } %>
+    - step:
+        name: Build Application
+        script:
+          - npm ci
+          - npm run build --if-present
+
+definitions:
+  services:
+    docker:
+      memory: 2048
+  caches:
+    node: ~/.npm

package/templates/common/caching/clean/ts/updateUser.ts.ejs

@@ -1,4 +1,3 @@
-import { User } from '@/domain/user';
 import { UserRepository } from '@/infrastructure/repositories/UserRepository';
 <%_ if (caching === 'Redis') { -%>
 import cacheService from '@/infrastructure/caching/redisClient';

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

@@ -122,10 +122,12 @@ services:
       FLYWAY_URL: jdbc:mysql://db:3306/<%= dbName %>
       FLYWAY_USER: root
       FLYWAY_PASSWORD: root
+      FLYWAY_BASELINE_ON_MIGRATE: "true"
 <%_ } -%><%_ if (database === 'PostgreSQL') { -%>
       FLYWAY_URL: jdbc:postgresql://db:5432/<%= dbName %>
       FLYWAY_USER: postgres
       FLYWAY_PASSWORD: root
+      FLYWAY_BASELINE_ON_MIGRATE: "true"
 <%_ } -%>
     depends_on:
       - db

package/templates/common/package.json.ejs

@@ -28,7 +28,8 @@
     "micromatch": "^4.0.8",
     "braces": "^3.0.3",
     "picomatch": "^4.0.4",
-    "lodash": "^4.17.23"
+    "lodash": "^4.17.23",
+    "debounce": "^1.2.1"
   },
   "dependencies": {
     "express": "^4.18.2",

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

@@ -3,13 +3,21 @@ 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 TEST_PORT = <% if (database === 'MySQL') { %>process.env.PORT || '3001'<% } else { %>process.env.PORT || '3001'<% } %>;
+const WAIT_ON_HOST = process.env.WAIT_ON_HOST || '127.0.0.1';
 
 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, '../') });
+  console.log(`\n> ${command}`);
+  // Run commands from the project root instead of the scripts folder
+  execSync(command, { 
+    stdio: 'inherit', 
+    cwd: path.resolve(__dirname, '../'),
+    env: { 
+      ...process.env, 
+      PORT: TEST_PORT,
+      DB_PORT: process.env.DB_PORT || '3306'
+    }
+  });
 };
 
 let composeCmd = 'docker-compose';
@@ -26,7 +34,7 @@ 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`, { 
+        execSync(`npx wait-on http-get://${WAIT_ON_HOST}:${TEST_PORT}/health -t 1500`, { 
             stdio: 'ignore',
             cwd: path.resolve(__dirname, '../') 
         });
@@ -42,10 +50,18 @@ try {
         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(`Waiting for application healthcheck to turn green (420s timeout)...`);
+        try {
+            // Using WAIT_ON_HOST to allow containerized CI to hit host ports (e.g. host.docker.internal)
+            execute(`npx wait-on http-get://${WAIT_ON_HOST}:${TEST_PORT}/health -t 420000`);
+            console.log('Infrastructure is healthy!');
+        } catch (e) {
+            console.error('\n❌ Healthcheck timed out! Printing infrastructure logs for debugging:');
+            console.error('------------------------------------------------------------');
+            execute(`${composeCmd} logs --tail=100`);
+            console.error('------------------------------------------------------------');
+            throw e;
+        }
     }
 
     console.log('Running E2E tests...');