fix: enforce Node.js 18.17.0+ requirement and add version validation

- Update Node.js requirement to 18.17.0+ (minimum) or 20.0.0+ (recommended LTS)
- Add engines field to package.json to enforce Node.js version
- Create .nvmrc file for nvm users (Node.js 20)
- Update Dockerfile to use node:20-alpine
- Update CI/CD workflows to use Node.js 20
- Add comprehensive Node.js version check script (check_node_version.sh)
- Enhance setup_environment.sh with Node.js version validation
- Update README.md and DEPLOYMENT.md with version requirements and troubleshooting
- Add detailed troubleshooting section for 'Cannot find module node:path' error

Fixes QA-reported issue where Node.js < 18.17.0 fails with node:path error.
Users with Node.js 18.0.0-18.16.x will now get clear error messages and upgrade instructions.

Author: T-DevH

.github/workflows/ci-cd.yml

@@ -22,7 +22,7 @@ jobs:
     strategy:
       matrix:
         python-version: [3.11]
-        node-version: [18]
+        node-version: [20]
 
     steps:
     - name: Checkout code

.github/workflows/release.yml

@@ -29,7 +29,7 @@ jobs:
     - name: Set up Node.js
       uses: actions/setup-node@v4
       with:
-        node-version: '18'
+        node-version: '20'
         cache: 'npm'
         cache-dependency-path: package-lock.json
 

DEPLOYMENT.md

@@ -24,19 +24,22 @@ Complete deployment guide for the Warehouse Operational Assistant with Docker an
 git clone https://github.com/T-DevH/Multi-Agent-Intelligent-Warehouse.git
 cd Multi-Agent-Intelligent-Warehouse
 
-# 2. Setup environment
+# 2. Verify Node.js version (recommended before setup)
+./scripts/setup/check_node_version.sh
+
+# 3. Setup environment
 ./scripts/setup/setup_environment.sh
 
-# 3. Configure environment variables (REQUIRED before starting services)
+# 4. Configure environment variables (REQUIRED before starting services)
 # Create .env file for Docker Compose (recommended location)
 cp .env.example deploy/compose/.env
 # Or create in project root: cp .env.example .env
 # Edit with your values: nano deploy/compose/.env
 
-# 4. Start infrastructure services
+# 5. Start infrastructure services
 ./scripts/setup/dev_up.sh
 
-# 5. Run database migrations
+# 6. Run database migrations
 source env/bin/activate
 
 # Option A: Using psql (requires PostgreSQL client installed)
@@ -53,19 +56,19 @@ PGPASSWORD=${POSTGRES_PASSWORD:-changeme} psql -h localhost -p 5435 -U warehouse
 # docker-compose -f deploy/compose/docker-compose.dev.yaml exec -T timescaledb psql -U warehouse -d warehouse < data/postgres/004_inventory_movements_schema.sql
 # docker-compose -f deploy/compose/docker-compose.dev.yaml exec -T timescaledb psql -U warehouse -d warehouse < scripts/setup/create_model_tracking_tables.sql
 
-# 6. Create default users
+# 7. Create default users
 python scripts/setup/create_default_users.py
 
-# 7. Generate demo data (optional but recommended)
+# 8. Generate demo data (optional but recommended)
 python scripts/data/quick_demo_data.py
 
-# 8. Generate historical demand data for forecasting (optional, required for Forecasting page)
+# 9. Generate historical demand data for forecasting (optional, required for Forecasting page)
 python scripts/data/generate_historical_demand.py
 
-# 9. Start API server
+# 10. Start API server
 ./scripts/start_server.sh
 
-# 10. Start frontend (in another terminal)
+# 11. Start frontend (in another terminal)
 cd src/ui/web
 npm install
 npm start
@@ -93,7 +96,10 @@ npm start
 
 ### Common Prerequisites
 - Python 3.9+ (for local development)
-- Node.js 18+ and npm (for frontend)
+- **Node.js 20.0.0+** (LTS recommended) and npm (for frontend)
+  - **Minimum**: Node.js 18.17.0+ (required for `node:path` protocol support)
+  - **Recommended**: Node.js 20.x LTS for best compatibility
+  - **Note**: Node.js 18.0.0 - 18.16.x will fail with `Cannot find module 'node:path'` error during frontend build
 - Git
 - PostgreSQL client (`psql`) - Required for running database migrations
   - **Ubuntu/Debian**: `sudo apt-get install postgresql-client`
@@ -557,6 +563,56 @@ kubectl exec -i -n warehouse-assistant deployment/postgres -- psql -U warehouse
 
 ### Common Issues
 
+#### Node.js Version Error: "Cannot find module 'node:path'"
+
+**Symptom:**
+```
+Error: Cannot find module 'node:path'
+Failed to compile.
+[eslint] Cannot read config file
+```
+
+**Cause:**
+- Node.js version is too old (below 18.17.0)
+- The `node:path` protocol requires Node.js 18.17.0+ or 20.0.0+
+
+**Solution:**
+1. Check your Node.js version:
+   ```bash
+   node --version
+   ```
+
+2. If version is below 18.17.0, upgrade Node.js:
+   ```bash
+   # Using nvm (recommended)
+   nvm install 20
+   nvm use 20
+   
+   # Or download from https://nodejs.org/
+   ```
+
+3. Verify the version:
+   ```bash
+   node --version  # Should show v20.x.x or v18.17.0+
+   ```
+
+4. Clear node_modules and reinstall:
+   ```bash
+   cd src/ui/web
+   rm -rf node_modules package-lock.json
+   npm install
+   ```
+
+5. Run the version check script:
+   ```bash
+   ./scripts/setup/check_node_version.sh
+   ```
+
+**Prevention:**
+- Always check Node.js version before starting: `./scripts/setup/check_node_version.sh`
+- Use `.nvmrc` file: `cd src/ui/web && nvm use`
+- Ensure CI/CD uses Node.js 20+
+
 #### Port Already in Use
 
 ```bash

Dockerfile

@@ -4,7 +4,7 @@
 # =============================================================================
 # Frontend Build Stage
 # =============================================================================
-FROM node:18-alpine AS frontend-builder
+FROM node:20-alpine AS frontend-builder
 
 WORKDIR /app/src/ui/web
 

README.md

@@ -179,7 +179,10 @@ For more security information, see [docs/secrets.md](docs/secrets.md) and [SECUR
 ### Prerequisites
 
 - **Python 3.9+** (check with `python3 --version`)
-- **Node.js 18+** and npm (check with `node --version` and `npm --version`)
+- **Node.js 20.0.0+** (LTS recommended) and npm (check with `node --version` and `npm --version`)
+  - **Minimum**: Node.js 18.17.0+ (required for `node:path` protocol support)
+  - **Recommended**: Node.js 20.x LTS for best compatibility
+  - **Note**: Node.js 18.0.0 - 18.16.x will fail with `Cannot find module 'node:path'` error
 - **Docker** and Docker Compose
 - **Git** (to clone the repository)
 - **PostgreSQL client** (`psql`) - Required for running database migrations
@@ -197,19 +200,22 @@ For the fastest local development setup:
 git clone https://github.com/T-DevH/Multi-Agent-Intelligent-Warehouse.git
 cd Multi-Agent-Intelligent-Warehouse
 
-# 2. Setup environment
+# 2. Verify Node.js version (recommended before setup)
+./scripts/setup/check_node_version.sh
+
+# 3. Setup environment
 ./scripts/setup/setup_environment.sh
 
-# 3. Configure environment variables (REQUIRED before starting services)
+# 4. Configure environment variables (REQUIRED before starting services)
 # Create .env file for Docker Compose (recommended location)
 cp .env.example deploy/compose/.env
 # Or create in project root: cp .env.example .env
 # Edit with your values: nano deploy/compose/.env
 
-# 4. Start infrastructure services
+# 5. Start infrastructure services
 ./scripts/setup/dev_up.sh
 
-# 5. Run database migrations
+# 6. Run database migrations
 source env/bin/activate
 
 # Option A: Using psql (requires PostgreSQL client installed)
@@ -223,19 +229,19 @@ PGPASSWORD=${POSTGRES_PASSWORD:-changeme} psql -h localhost -p 5435 -U warehouse
 # docker-compose -f deploy/compose/docker-compose.dev.yaml exec -T timescaledb psql -U warehouse -d warehouse < data/postgres/000_schema.sql
 # (Repeat for other schema files)
 
-# 6. Create default users
+# 7. Create default users
 python scripts/setup/create_default_users.py
 
-# 7. Generate demo data (optional but recommended)
+# 8. Generate demo data (optional but recommended)
 python scripts/data/quick_demo_data.py
 
-# 8. Generate historical demand data for forecasting (optional, required for Forecasting page)
+# 9. Generate historical demand data for forecasting (optional, required for Forecasting page)
 python scripts/data/generate_historical_demand.py
 
-# 9. Start API server
+# 10. Start API server
 ./scripts/start_server.sh
 
-# 10. Start frontend (in another terminal)
+# 11. Start frontend (in another terminal)
 cd src/ui/web
 npm install
 npm start
@@ -289,6 +295,16 @@ python setup_nvidia_api.py
 
 ### Troubleshooting
 
+**Node.js Version Issues:**
+- **Error: "Cannot find module 'node:path'"**: Your Node.js version is too old
+  - Check version: `node --version`
+  - Minimum required: Node.js 18.17.0+
+  - Recommended: Node.js 20.x LTS
+  - Run version check: `./scripts/setup/check_node_version.sh`
+  - Upgrade: `nvm install 20 && nvm use 20` (if using nvm)
+  - Or download from: https://nodejs.org/
+  - After upgrading, clear and reinstall: `cd src/ui/web && rm -rf node_modules package-lock.json && npm install`
+
 **Database Connection Issues:**
 - Ensure Docker containers are running: `docker ps`
 - Check TimescaleDB logs: `docker logs wosa-timescaledb`
@@ -300,6 +316,11 @@ python setup_nvidia_api.py
 - Use the startup script: `./scripts/start_server.sh`
 - See [DEPLOYMENT.md](DEPLOYMENT.md) troubleshooting section
 
+**Frontend Build Issues:**
+- Verify Node.js version: `./scripts/setup/check_node_version.sh`
+- Clear node_modules: `cd src/ui/web && rm -rf node_modules package-lock.json && npm install`
+- Check for port conflicts: Ensure port 3001 is available
+
 **For more help:** See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed troubleshooting or open an issue on GitHub.
 
 ## Multi-Agent System

scripts/setup/check_node_version.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Node.js version check script for Warehouse Operational Assistant
+# Checks if Node.js version meets minimum requirements
+
+set -e
+
+MIN_NODE_VERSION="18.17.0"
+RECOMMENDED_NODE_VERSION="20.0.0"
+MIN_NPM_VERSION="9.0.0"
+
+echo "🔍 Checking Node.js and npm versions..."
+echo ""
+
+# Check if Node.js is installed
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js is not installed."
+    echo "   Please install Node.js $RECOMMENDED_NODE_VERSION+ (minimum: $MIN_NODE_VERSION)"
+    echo "   Download from: https://nodejs.org/"
+    echo ""
+    echo "   Or use nvm (Node Version Manager):"
+    echo "   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash"
+    echo "   nvm install 20"
+    echo "   nvm use 20"
+    exit 1
+fi
+
+# Get Node.js version
+NODE_VERSION=$(node --version | cut -d'v' -f2)
+NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d'.' -f1)
+NODE_MINOR=$(echo "$NODE_VERSION" | cut -d'.' -f2)
+NODE_PATCH=$(echo "$NODE_VERSION" | cut -d'.' -f3)
+
+echo "📦 Node.js version: $NODE_VERSION"
+
+# Parse minimum version for comparison
+MIN_MAJOR=$(echo "$MIN_NODE_VERSION" | cut -d'.' -f1)
+MIN_MINOR=$(echo "$MIN_NODE_VERSION" | cut -d'.' -f2)
+MIN_PATCH=$(echo "$MIN_NODE_VERSION" | cut -d'.' -f3)
+
+# Check if version meets minimum requirements
+VERSION_OK=false
+if [ "$NODE_MAJOR" -gt "$MIN_MAJOR" ]; then
+    VERSION_OK=true
+elif [ "$NODE_MAJOR" -eq "$MIN_MAJOR" ]; then
+    if [ "$NODE_MINOR" -gt "$MIN_MINOR" ]; then
+        VERSION_OK=true
+    elif [ "$NODE_MINOR" -eq "$MIN_MINOR" ]; then
+        if [ "$NODE_PATCH" -ge "$MIN_PATCH" ]; then
+            VERSION_OK=true
+        fi
+    fi
+fi
+
+if [ "$VERSION_OK" = false ]; then
+    echo "❌ Node.js version $NODE_VERSION is too old."
+    echo "   Minimum required: $MIN_NODE_VERSION"
+    echo "   Recommended: $RECOMMENDED_NODE_VERSION+ (LTS)"
+    echo ""
+    echo "   Note: Node.js 18.0.0 - 18.16.x will fail with 'Cannot find module node:path' error"
+    echo ""
+    echo "   Upgrade options:"
+    echo "   1. Download from: https://nodejs.org/"
+    echo "   2. Use nvm: nvm install 20 && nvm use 20"
+    exit 1
+fi
+
+# Check if version is recommended
+if [ "$NODE_MAJOR" -lt 20 ]; then
+    echo "⚠️  Node.js 18.17.0+ detected. Node.js 20.x LTS is recommended for best compatibility."
+else
+    echo "✅ Node.js version meets requirements (20.x LTS)"
+fi
+
+# Check npm version
+if ! command -v npm &> /dev/null; then
+    echo "⚠️  npm is not installed. Please install npm $MIN_NPM_VERSION+"
+    exit 1
+fi
+
+NPM_VERSION=$(npm --version)
+echo "📦 npm version: $NPM_VERSION"
+
+# Check npm version meets minimum
+NPM_MAJOR=$(echo "$NPM_VERSION" | cut -d'.' -f1)
+MIN_NPM_MAJOR=$(echo "$MIN_NPM_VERSION" | cut -d'.' -f1)
+
+if [ "$NPM_MAJOR" -lt "$MIN_NPM_MAJOR" ]; then
+    echo "⚠️  npm version $NPM_VERSION is below recommended minimum ($MIN_NPM_VERSION)"
+    echo "   Consider upgrading: npm install -g npm@latest"
+else
+    echo "✅ npm version meets requirements"
+fi
+
+echo ""
+echo "✅ Node.js and npm version check passed!"
+echo ""
+
+# Check for .nvmrc file and suggest using it
+if [ -f "src/ui/web/.nvmrc" ]; then
+    NVMRC_VERSION=$(cat src/ui/web/.nvmrc)
+    echo "💡 Tip: This project uses Node.js $NVMRC_VERSION (see src/ui/web/.nvmrc)"
+    echo "   If using nvm, run: cd src/ui/web && nvm use"
+fi
+

scripts/setup/setup_environment.sh

@@ -21,6 +21,48 @@ fi
 PYTHON_VERSION=$(python3 --version | cut -d' ' -f2 | cut -d'.' -f1,2)
 echo "✅ Found Python $PYTHON_VERSION"
 
+# Check Node.js version
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js is not installed. Please install Node.js 20.0.0+ (or minimum 18.17.0+) first."
+    echo "   Recommended: Node.js 20.x LTS"
+    exit 1
+fi
+
+NODE_VERSION=$(node --version | cut -d'v' -f2)
+NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d'.' -f1)
+NODE_MINOR=$(echo "$NODE_VERSION" | cut -d'.' -f2)
+NODE_PATCH=$(echo "$NODE_VERSION" | cut -d'.' -f3)
+
+echo "✅ Found Node.js $NODE_VERSION"
+
+# Check if Node.js version meets requirements
+# Minimum: 18.17.0, Recommended: 20.0.0+
+if [ "$NODE_MAJOR" -lt 18 ]; then
+    echo "❌ Node.js version $NODE_VERSION is too old. Please install Node.js 18.17.0+ (recommended: 20.x LTS)"
+    exit 1
+elif [ "$NODE_MAJOR" -eq 18 ]; then
+    if [ "$NODE_MINOR" -lt 17 ]; then
+        echo "❌ Node.js version $NODE_VERSION is too old. Please install Node.js 18.17.0+ (recommended: 20.x LTS)"
+        echo "   Note: Node.js 18.0.0 - 18.16.x will fail with 'Cannot find module node:path' error"
+        exit 1
+    elif [ "$NODE_MINOR" -eq 17 ] && [ "$NODE_PATCH" -lt 0 ]; then
+        echo "❌ Node.js version $NODE_VERSION is too old. Please install Node.js 18.17.0+ (recommended: 20.x LTS)"
+        exit 1
+    else
+        echo "⚠️  Node.js 18.17.0+ detected. Node.js 20.x LTS is recommended for best compatibility."
+    fi
+elif [ "$NODE_MAJOR" -ge 20 ]; then
+    echo "✅ Node.js version meets requirements (20.x LTS recommended)"
+fi
+
+# Check npm version
+if ! command -v npm &> /dev/null; then
+    echo "⚠️  npm is not installed. Please install npm 9.0.0+"
+else
+    NPM_VERSION=$(npm --version)
+    echo "✅ Found npm $NPM_VERSION"
+fi
+
 # Create virtual environment if it doesn't exist
 if [ ! -d "env" ]; then
     echo "📦 Creating virtual environment..."

src/ui/web/.nvmrc

@@ -0,0 +1 @@
+20