fix: auto-detect and upgrade Node.js to >= 22.22.0 across Linux, macOS and Windows

- Add smart Node.js compatibility checking (>= 22.22.0) required by Angular CLI 22
- Upgrade portable Node.js fallback download to v22.23.2 LTS across Linux, macOS and Windows
- Add automatic upgrade paths using nvm, NodeSource 22.x (with sudo/root), and winget
- Display detected Node.js version in toolchain readiness summary

scripts/install_deps.ps1

@@ -107,17 +107,44 @@ function Install-PortablePlatformTools {
     return $false
 }
 
+function Test-NodeCompatible {
+    if (-not (Test-CommandExists "node") -or -not (Test-CommandExists "npm")) { return $false }
+    try {
+        $verRaw = (& node -v 2>$null)
+        if (-not $verRaw) { return $false }
+        $verStr = $verRaw.ToString().Trim().TrimStart('v')
+        $parts = $verStr.Split('.')
+        if ($parts.Count -ge 2) {
+            $major = [int]$parts[0]
+            $minor = [int]$parts[1]
+            if ($major -ge 26) { return $true }
+            if ($major -ge 24 -and $minor -ge 15) { return $true }
+            if ($major -ge 22 -and $minor -ge 22) { return $true }
+        }
+    } catch {
+        return $false
+    }
+    return $false
+}
+
 function Install-PortableNode {
     $nodeDir = "$env:LOCALAPPDATA\Programs\node"
     if (Test-Path "$nodeDir\node.exe") {
         $env:PATH = "$nodeDir;$env:PATH"
+        if (Test-NodeCompatible) {
             return $true
         }
-    Write-Host "   [INFO] Installing portable Node.js LTS in user space..." -ForegroundColor Cyan
+    }
+    Write-Host "   [INFO] Installing portable Node.js LTS (v22.23.2) in user space..." -ForegroundColor Cyan
     try {
-        $zipPath = "$env:TEMP\node-v20-win-x64.zip"
-        Invoke-WebRequest -Uri "https://nodejs.org/dist/v20.18.3/node-v20.18.3-win-x64.zip" -OutFile $zipPath -UseBasicParsing
+        $nodeVer = "v22.23.2"
+        $arch = if ([System.Environment]::Is64BitOperatingSystem) {
+            if ($env:PROCESSOR_ARCHITECTURE -match "ARM64") { "arm64" } else { "x64" }
+        } else { "x64" }
+        $zipPath = "$env:TEMP\node-$nodeVer-win-$arch.zip"
+        Invoke-WebRequest -Uri "https://nodejs.org/dist/$nodeVer/node-$nodeVer-win-$arch.zip" -OutFile $zipPath -UseBasicParsing
         $extractDir = "$env:TEMP\node_extract"
+        if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force -ErrorAction SilentlyContinue }
         New-Item -ItemType Directory -Path $extractDir -Force | Out-Null
         Expand-Archive -Path $zipPath -DestinationPath $extractDir -Force
         $extractedFolder = Get-ChildItem -Path $extractDir -Directory | Select-Object -First 1
@@ -130,7 +157,7 @@ function Install-PortableNode {
         Remove-Item $extractDir -Recurse -Force -ErrorAction SilentlyContinue
         if (Test-Path "$nodeDir\node.exe") {
             $env:PATH = "$nodeDir;$env:PATH"
-            Write-Host "   ✔ Portable Node.js installed in user space." -ForegroundColor Green
+            Write-Host "   ✔ Portable Node.js $nodeVer installed in user space." -ForegroundColor Green
             return $true
         }
     } catch {
@@ -243,11 +270,28 @@ $ShowcaseIndex = "$RootDir\apps\showcase_ui\dist\frontend\browser\index.html"
 $ShowcaseIndexAlt1 = "$RootDir\apps\showcase_ui\dist\browser\index.html"
 $ShowcaseIndexAlt2 = "$RootDir\apps\showcase_ui\dist\index.html"
 if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1)) -and (-not (Test-Path $ShowcaseIndexAlt2))) {
-    if (-not (Test-CommandExists "npm")) {
+    if (-not (Test-NodeCompatible)) {
+        if (Test-CommandExists "node") {
+            $curVer = (& node -v 2>$null)
+            Write-Host "   ⚡ Detected Node.js $curVer, but Angular CLI requires Node.js >= v22.22.0." -ForegroundColor Yellow
+        } else {
+            Write-Host "   ⚡ Node.js/npm not found (required for Showcase UI)." -ForegroundColor Cyan
+        }
+
+        # 1. Try nvm if available on Windows
+        if (Test-CommandExists "nvm") {
+            Write-Host "   📦 Installing Node.js 22 LTS via nvm..." -ForegroundColor Cyan
+            & nvm install 22.23.2 | Out-Null
+            & nvm use 22.23.2 | Out-Null
+            Update-EnvironmentPath
+        }
+
+        # 2. Try WinGet
+        if (-not (Test-NodeCompatible)) {
             $useWinGetNode = $false
             if (Test-CommandExists "winget") {
                 if ([Console]::IsInputRedirected -eq $false) {
-                $ans = Read-Host "   Install Node.js via WinGet (may require Administrator)? [Y/n]"
+                    $ans = Read-Host "   Install/Upgrade Node.js via WinGet (may require Administrator)? [Y/n]"
                     if ($ans -eq "" -or $ans -match "^[Yy]") {
                         $useWinGetNode = $true
                     }
@@ -257,18 +301,21 @@ if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1))
             }
 
             if ($useWinGetNode) {
-            Write-Host "   ⚡ Node.js/npm not found. Installing Node.js LTS via WinGet..." -ForegroundColor Cyan
+                Write-Host "   ⚡ Installing/Upgrading Node.js LTS via WinGet..." -ForegroundColor Cyan
                 winget install --id OpenJS.NodeJS.LTS -e --accept-source-agreements --accept-package-agreements --silent 2>$null | Out-Null
                 Update-EnvironmentPath
             }
+        }
 
-        # Zero-admin user-space fallback for Node.js if still not found
-        if (-not (Test-CommandExists "npm")) {
+        # 3. Zero-admin user-space fallback for Node.js if still not compatible
+        if (-not (Test-NodeCompatible)) {
             Install-PortableNode
         }
     }
 
-    if (Test-CommandExists "npm") {
+    if (Test-NodeCompatible) {
+        $nodeVer = (& node -v 2>$null)
+        Write-Host "   ✔ Node.js $nodeVer is ready." -ForegroundColor Green
         Write-Host "   🎨 Compiling Angular Showcase UI..." -ForegroundColor Cyan
         Push-Location "$RootDir\apps\showcase_ui"
         try {
@@ -285,7 +332,7 @@ if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1))
             Pop-Location
         }
     } else {
-        Write-Host "   ⚠ Could not find npm. Showcase UI will show fallback notice on launch." -ForegroundColor DarkYellow
+        Write-Host "   ⚠ Could not configure compatible Node.js (>= 22.22.0). Showcase UI will show fallback notice on launch." -ForegroundColor DarkYellow
     }
 } else {
     Write-Host "   ✔ Showcase UI build already exists." -ForegroundColor Green
@@ -297,7 +344,12 @@ $tools = @("adb", "ffmpeg", "scrcpy", "uv", "npm")
 foreach ($t in $tools) {
     if (Test-CommandExists $t) {
         $p = (Get-Command $t).Source
+        if ($t -eq "npm" -and (Test-CommandExists "node")) {
+            $nVer = (& node -v 2>$null)
+            Write-Host "   ✔ $t ($nVer) -> $p" -ForegroundColor Green
+        } else {
             Write-Host "   ✔ $t -> $p" -ForegroundColor Green
+        }
     } else {
         Write-Host "   ○ $t -> Not found in PATH (Fallbacks active)" -ForegroundColor DarkYellow
     }

scripts/install_deps.sh

@@ -115,6 +115,27 @@ request_sudo() {
     return 1
 }
 
+# Helper to check if Node.js & npm meet Angular CLI 22 requirement (>= 22.22.0, >= 24.15.0, or >= 26.0.0)
+is_node_compatible() {
+    if ! has_cmd node || ! has_cmd npm; then
+        return 1
+    fi
+    local node_ver
+    node_ver="$(node -v 2>/dev/null | tr -d 'v')"
+    [ -z "${node_ver}" ] && return 1
+    local major minor
+    major="$(echo "${node_ver}" | cut -d. -f1)"
+    minor="$(echo "${node_ver}" | cut -d. -f2)"
+    if [ "${major}" -ge 26 ] 2>/dev/null; then
+        return 0
+    elif [ "${major}" -ge 24 ] 2>/dev/null; then
+        [ "${minor}" -ge 15 ] 2>/dev/null && return 0
+    elif [ "${major}" -ge 22 ] 2>/dev/null; then
+        [ "${minor}" -ge 22 ] 2>/dev/null && return 0
+    fi
+    return 1
+}
+
 echo -e "${BOLD}1. Detecting Operating System & Environment...${NC}"
 echo -e "   Platform: ${BLUE}${OS_TYPE}${NC} (${ARCH_TYPE})"
 echo -e "   Root Dir: ${DIM}${ROOT_DIR}${NC}"
@@ -346,48 +367,78 @@ setup_showcase_ui() {
             export PATH="${HOME}/.local/share/node/bin:${PATH}"
         fi
 
-        if ! has_cmd npm; then
-            echo -e "   ${YELLOW}⚡ npm/Node.js not found. Auto-installing Node.js...${NC}"
-            if [ "${OS_TYPE}" = "Darwin" ] && has_cmd brew; then
-                brew install node >/dev/null 2>&1 || true
-            elif [ "${OS_TYPE}" = "Linux" ]; then
-                if request_sudo "install Node.js and npm"; then
+        # Check if nvm already has a compatible Node version installed
+        if ! is_node_compatible && (command -v nvm >/dev/null 2>&1 || type nvm >/dev/null 2>&1); then
+            nvm use 22 >/dev/null 2>&1 || true
+        fi
+
+        if ! is_node_compatible; then
+            if has_cmd node; then
+                local current_node="$(node -v 2>/dev/null)"
+                echo -e "   ${YELLOW}⚡ Detected Node.js ${current_node}, but Angular CLI requires Node.js >= v22.22.0. Upgrading Node.js...${NC}"
+            else
+                echo -e "   ${YELLOW}⚡ Node.js/npm not found. Auto-installing Node.js 22 LTS for Showcase UI compilation...${NC}"
+            fi
+
+            # 1. Try installing Node 22 via nvm if available
+            if command -v nvm >/dev/null 2>&1 || type nvm >/dev/null 2>&1; then
+                echo -e "   ${CYAN}📦 Installing Node.js 22 LTS via nvm...${NC}"
+                nvm install 22 >/dev/null 2>&1 || true
+                nvm use 22 >/dev/null 2>&1 || true
+            fi
+
+            # 2. Try brew on macOS
+            if ! is_node_compatible && [ "${OS_TYPE}" = "Darwin" ] && has_cmd brew; then
+                brew install node >/dev/null 2>&1 || brew upgrade node >/dev/null 2>&1 || true
+            fi
+
+            # 3. Try Linux package managers with sudo / root
+            if ! is_node_compatible && [ "${OS_TYPE}" = "Linux" ]; then
+                if request_sudo "install or upgrade Node.js to >= 22.22.0"; then
                     local SUDO_PREFIX=""
                     if [ "$(id -u)" -ne 0 ]; then SUDO_PREFIX="sudo"; fi
                     if has_cmd apt-get; then
-                        ${SUDO_PREFIX} apt-get update -qq && ${SUDO_PREFIX} apt-get install -y -qq nodejs npm || true
+                        echo -e "   ${CYAN}📦 Configuring NodeSource Node.js 22 LTS repository...${NC}"
+                        curl -fsSL https://deb.nodesource.com/setup_22.x | ${SUDO_PREFIX} bash - >/dev/null 2>&1 || true
+                        ${SUDO_PREFIX} apt-get install -y -qq nodejs || true
                     elif has_cmd dnf; then
-                        ${SUDO_PREFIX} dnf install -y nodejs npm || true
+                        curl -fsSL https://rpm.nodesource.com/setup_22.x | ${SUDO_PREFIX} bash - >/dev/null 2>&1 || true
+                        ${SUDO_PREFIX} dnf install -y nodejs || true
                     elif has_cmd pacman; then
                         ${SUDO_PREFIX} pacman -S --noconfirm nodejs npm || true
                     fi
                 fi
+            fi
 
-                # If still not found, download portable Node.js into user space
-                if ! has_cmd npm; then
+            # 4. Standalone portable Node.js LTS (zero-admin user space fallback, guaranteed compatible)
+            if ! is_node_compatible; then
                 local ARCH="$(uname -m)"
                 local NODE_ARCH=""
                 case "${ARCH}" in
                     x86_64|amd64) NODE_ARCH="x64" ;;
                     aarch64|arm64) NODE_ARCH="arm64" ;;
                 esac
-                    if [ -n "${NODE_ARCH}" ]; then
-                        local NODE_VER="v20.18.3"
+                local OS_SYS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+                if [ -n "${NODE_ARCH}" ] && { [ "${OS_SYS}" = "linux" ] || [ "${OS_SYS}" = "darwin" ]; }; then
+                    local NODE_VER="v22.23.2"
                     local NODE_DIR="${HOME}/.local/share/node"
                     echo -e "   ${CYAN}📦 Installing portable Node.js ${NODE_VER} in user space (~/.local)...${NC}"
+                    rm -rf "${NODE_DIR}"
                     mkdir -p "${NODE_DIR}" "${HOME}/.local/bin"
-                        if curl -fsSL "https://nodejs.org/dist/${NODE_VER}/node-${NODE_VER}-linux-${NODE_ARCH}.tar.gz" | tar -xz -C "${NODE_DIR}" --strip-components=1 2>/dev/null; then
+                    if curl -fsSL "https://nodejs.org/dist/${NODE_VER}/node-${NODE_VER}-${OS_SYS}-${NODE_ARCH}.tar.gz" | tar -xz -C "${NODE_DIR}" --strip-components=1 2>/dev/null; then
                         ln -sf "${NODE_DIR}/bin/node" "${HOME}/.local/bin/node"
                         ln -sf "${NODE_DIR}/bin/npm" "${HOME}/.local/bin/npm"
                         ln -sf "${NODE_DIR}/bin/npx" "${HOME}/.local/bin/npx"
                         export PATH="${NODE_DIR}/bin:${HOME}/.local/bin:${PATH}"
-                        fi
+                        hash -r 2>/dev/null || true
+                        echo -e "   ${GREEN}✓ Portable Node.js ${NODE_VER} installed in user space.${NC}"
                     fi
                 fi
             fi
         fi
 
-        if has_cmd npm; then
+        if is_node_compatible; then
+            echo -e "   ${GREEN}✓ Node.js $(node -v 2>/dev/null) and npm $(npm -v 2>/dev/null) ready.${NC}"
             echo -e "   ${YELLOW}🎨 Building Angular Showcase UI...${NC}"
             (
                 cd "${ROOT_DIR}/apps/showcase_ui"
@@ -404,7 +455,7 @@ setup_showcase_ui() {
             )
             echo -e "   ${GREEN}✓ Showcase UI compiled successfully.${NC}"
         else
-            echo -e "   ${YELLOW}⚠ Could not find npm. Showcase UI will show fallback notice on launch.${NC}"
+            echo -e "   ${YELLOW}⚠ Could not configure compatible Node.js (>= 22.22.0). Showcase UI will show fallback notice on launch.${NC}"
         fi
     else
         echo -e "   ${GREEN}✓ Showcase UI build already exists.${NC}"
@@ -420,7 +471,13 @@ verify_readiness() {
         if has_cmd "$t"; then
             local loc
             loc="$(command -v "$t")"
+            if [ "$t" = "npm" ] && has_cmd node; then
+                local n_ver
+                n_ver="$(node -v 2>/dev/null || echo '')"
+                echo -e "   ${GREEN}✔ ${t}${NC} (${n_ver}) -> ${DIM}${loc}${NC}"
+            else
                 echo -e "   ${GREEN}✔ ${t}${NC} -> ${DIM}${loc}${NC}"
+            fi
         else
             echo -e "   ${YELLOW}○ ${t}${NC} -> ${YELLOW}Not found in PATH (Fallbacks active)${NC}"
         fi

scripts/start.ps1

@@ -102,17 +102,44 @@ function Install-PortablePlatformTools {
     return $false
 }
 
+function Test-NodeCompatible {
+    if (-not (Test-CommandExists "node") -or -not (Test-CommandExists "npm")) { return $false }
+    try {
+        $verRaw = (& node -v 2>$null)
+        if (-not $verRaw) { return $false }
+        $verStr = $verRaw.ToString().Trim().TrimStart('v')
+        $parts = $verStr.Split('.')
+        if ($parts.Count -ge 2) {
+            $major = [int]$parts[0]
+            $minor = [int]$parts[1]
+            if ($major -ge 26) { return $true }
+            if ($major -ge 24 -and $minor -ge 15) { return $true }
+            if ($major -ge 22 -and $minor -ge 22) { return $true }
+        }
+    } catch {
+        return $false
+    }
+    return $false
+}
+
 function Install-PortableNode {
     $nodeDir = "$env:LOCALAPPDATA\Programs\node"
     if (Test-Path "$nodeDir\node.exe") {
         $env:PATH = "$nodeDir;$env:PATH"
+        if (Test-NodeCompatible) {
             return $true
         }
-    Write-Host "   [INFO] Installing portable Node.js LTS in user space..." -ForegroundColor Cyan
+    }
+    Write-Host "   [INFO] Installing portable Node.js LTS (v22.23.2) in user space..." -ForegroundColor Cyan
     try {
-        $zipPath = "$env:TEMP\node-v20-win-x64.zip"
-        Invoke-WebRequest -Uri "https://nodejs.org/dist/v20.18.3/node-v20.18.3-win-x64.zip" -OutFile $zipPath -UseBasicParsing
+        $nodeVer = "v22.23.2"
+        $arch = if ([System.Environment]::Is64BitOperatingSystem) {
+            if ($env:PROCESSOR_ARCHITECTURE -match "ARM64") { "arm64" } else { "x64" }
+        } else { "x64" }
+        $zipPath = "$env:TEMP\node-$nodeVer-win-$arch.zip"
+        Invoke-WebRequest -Uri "https://nodejs.org/dist/$nodeVer/node-$nodeVer-win-$arch.zip" -OutFile $zipPath -UseBasicParsing
         $extractDir = "$env:TEMP\node_extract"
+        if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force -ErrorAction SilentlyContinue }
         New-Item -ItemType Directory -Path $extractDir -Force | Out-Null
         Expand-Archive -Path $zipPath -DestinationPath $extractDir -Force
         $extractedFolder = Get-ChildItem -Path $extractDir -Directory | Select-Object -First 1
@@ -125,7 +152,7 @@ function Install-PortableNode {
         Remove-Item $extractDir -Recurse -Force -ErrorAction SilentlyContinue
         if (Test-Path "$nodeDir\node.exe") {
             $env:PATH = "$nodeDir;$env:PATH"
-            Write-Host "   [OK] Portable Node.js installed in user space." -ForegroundColor Green
+            Write-Host "   [OK] Portable Node.js $nodeVer installed in user space." -ForegroundColor Green
             return $true
         }
     } catch {
@@ -206,12 +233,29 @@ $ShowcaseIndex = "$RootDir\apps\showcase_ui\dist\frontend\browser\index.html"
 $ShowcaseIndexAlt1 = "$RootDir\apps\showcase_ui\dist\browser\index.html"
 $ShowcaseIndexAlt2 = "$RootDir\apps\showcase_ui\dist\index.html"
 if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1)) -and (-not (Test-Path $ShowcaseIndexAlt2))) {
-    if (-not (Test-CommandExists "npm")) {
+    if (-not (Test-NodeCompatible)) {
+        if (Test-CommandExists "node") {
+            $curVer = (& node -v 2>$null)
+            Write-Host "   [INFO] Detected Node.js $curVer, but Angular CLI requires Node.js >= v22.22.0." -ForegroundColor Yellow
+        } else {
+            Write-Host "   [INFO] Node.js/npm not found (required for Showcase UI)." -ForegroundColor Cyan
+        }
+
+        # 1. Try nvm if available on Windows
+        if (Test-CommandExists "nvm") {
+            Write-Host "   [INFO] Installing Node.js 22 LTS via nvm..." -ForegroundColor Cyan
+            & nvm install 22.23.2 | Out-Null
+            & nvm use 22.23.2 | Out-Null
+            Update-EnvironmentPath
+        }
+
+        # 2. Try WinGet
+        if (-not (Test-NodeCompatible)) {
             $useWinGetNode = $false
             if (Test-CommandExists "winget") {
                 if ([Console]::IsInputRedirected -eq $false) {
-                Write-Host "   [INFO] Node.js/npm not found (required for Showcase UI)." -ForegroundColor Cyan
-                $ans = Read-Host "      Install Node.js via WinGet (may require Administrator)? [Y/n]"
+                    Write-Host "   [INFO] Node.js >= v22.22.0 required for Showcase UI." -ForegroundColor Cyan
+                    $ans = Read-Host "      Install/Upgrade Node.js via WinGet (may require Administrator)? [Y/n]"
                     if ($ans -eq "" -or $ans -match "^[Yy]") {
                         $useWinGetNode = $true
                     }
@@ -221,18 +265,21 @@ if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1))
             }
 
             if ($useWinGetNode) {
-            Write-Host "   [INFO] Installing Node.js LTS via WinGet..." -ForegroundColor Yellow
+                Write-Host "   [INFO] Installing/Upgrading Node.js LTS via WinGet..." -ForegroundColor Yellow
                 winget install --id OpenJS.NodeJS.LTS -e --accept-source-agreements --accept-package-agreements --silent 2>$null | Out-Null
                 Update-EnvironmentPath
             }
+        }
 
-        # Zero-admin user-space fallback for Node.js if still not found
-        if (-not (Test-CommandExists "npm")) {
+        # 3. Zero-admin user-space fallback for Node.js if still not compatible
+        if (-not (Test-NodeCompatible)) {
             Install-PortableNode
         }
     }
 
-    if (Test-CommandExists "npm") {
+    if (Test-NodeCompatible) {
+        $nodeVer = (& node -v 2>$null)
+        Write-Host "   [OK] Node.js $nodeVer is ready." -ForegroundColor Green
         Write-Host "   [INFO] Showcase UI build not found. Compiling Angular Showcase UI..." -ForegroundColor Yellow
         Push-Location "$RootDir\apps\showcase_ui"
         try {
@@ -249,7 +296,7 @@ if ((-not (Test-Path $ShowcaseIndex)) -and (-not (Test-Path $ShowcaseIndexAlt1))
             Pop-Location
         }
     } else {
-        Write-Host "   [WARN] Node.js/npm not found. Showcase UI will show fallback notice on launch." -ForegroundColor DarkYellow
+        Write-Host "   [WARN] Node.js >= v22.22.0 not found. Showcase UI will show fallback notice on launch." -ForegroundColor DarkYellow
     }
 }
 

start.sh

@@ -94,6 +94,27 @@ request_sudo() {
     return 1
 }
 
+# Helper to check if Node.js & npm meet Angular CLI 22 requirement (>= 22.22.0, >= 24.15.0, or >= 26.0.0)
+is_node_compatible() {
+    if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+        return 1
+    fi
+    local node_ver
+    node_ver="$(node -v 2>/dev/null | tr -d 'v')"
+    [ -z "${node_ver}" ] && return 1
+    local major minor
+    major="$(echo "${node_ver}" | cut -d. -f1)"
+    minor="$(echo "${node_ver}" | cut -d. -f2)"
+    if [ "${major}" -ge 26 ] 2>/dev/null; then
+        return 0
+    elif [ "${major}" -ge 24 ] 2>/dev/null; then
+        [ "${minor}" -ge 15 ] 2>/dev/null && return 0
+    elif [ "${major}" -ge 22 ] 2>/dev/null; then
+        [ "${minor}" -ge 22 ] 2>/dev/null && return 0
+    fi
+    return 1
+}
+
 # 2. Check or install uv (Fast Python package manager)
 if ! command -v uv >/dev/null 2>&1; then
     echo -e "${YELLOW}⚡ uv not found. Installing Astral uv...${NC}"
@@ -226,50 +247,78 @@ if [ ! -f "${SHOWCASE_INDEX}" ] && [ ! -f "${SHOWCASE_INDEX_ALT1}" ] && [ ! -f "
         export PATH="${HOME}/.local/share/node/bin:${PATH}"
     fi
 
-    if ! command -v npm >/dev/null 2>&1; then
+    # Check if nvm already has a compatible Node version installed
+    if ! is_node_compatible && (command -v nvm >/dev/null 2>&1 || type nvm >/dev/null 2>&1); then
+        nvm use 22 >/dev/null 2>&1 || true
+    fi
+
+    if ! is_node_compatible; then
         OS_NAME="$(uname -s)"
-        echo -e "   ${YELLOW}⚡ npm/Node.js not found. Auto-installing Node.js for Showcase UI compilation...${NC}"
-        if [ "${OS_NAME}" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
-            brew install node >/dev/null 2>&1 || true
-        elif [ "${OS_NAME}" = "Linux" ]; then
-            if request_sudo "install Node.js and npm"; then
+        if command -v node >/dev/null 2>&1; then
+            echo -e "   ${YELLOW}⚡ Detected Node.js $(node -v 2>/dev/null), but Angular CLI requires Node.js >= v22.22.0. Upgrading Node.js...${NC}"
+        else
+            echo -e "   ${YELLOW}⚡ Node.js/npm not found. Auto-installing Node.js 22 LTS for Showcase UI compilation...${NC}"
+        fi
+
+        # 1. Try installing Node 22 via nvm if available
+        if command -v nvm >/dev/null 2>&1 || type nvm >/dev/null 2>&1; then
+            echo -e "   ${CYAN}📦 Installing Node.js 22 LTS via nvm...${NC}"
+            nvm install 22 >/dev/null 2>&1 || true
+            nvm use 22 >/dev/null 2>&1 || true
+        fi
+
+        # 2. Try brew on macOS
+        if ! is_node_compatible && [ "${OS_NAME}" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
+            brew install node >/dev/null 2>&1 || brew upgrade node >/dev/null 2>&1 || true
+        fi
+
+        # 3. Try Linux package managers with sudo / root
+        if ! is_node_compatible && [ "${OS_NAME}" = "Linux" ]; then
+            if request_sudo "install or upgrade Node.js to >= 22.22.0"; then
                 SUDO_PREFIX=""
                 if [ "$(id -u)" -ne 0 ]; then SUDO_PREFIX="sudo"; fi
                 if command -v apt-get >/dev/null 2>&1; then
-                    ${SUDO_PREFIX} apt-get update -qq && ${SUDO_PREFIX} apt-get install -y -qq nodejs npm || true
+                    echo -e "   ${CYAN}📦 Configuring NodeSource Node.js 22 LTS repository...${NC}"
+                    curl -fsSL https://deb.nodesource.com/setup_22.x | ${SUDO_PREFIX} bash - >/dev/null 2>&1 || true
+                    ${SUDO_PREFIX} apt-get install -y -qq nodejs || true
                 elif command -v dnf >/dev/null 2>&1; then
-                    ${SUDO_PREFIX} dnf install -y nodejs npm || true
+                    curl -fsSL https://rpm.nodesource.com/setup_22.x | ${SUDO_PREFIX} bash - >/dev/null 2>&1 || true
+                    ${SUDO_PREFIX} dnf install -y nodejs || true
                 elif command -v pacman >/dev/null 2>&1; then
                     ${SUDO_PREFIX} pacman -S --noconfirm nodejs npm || true
                 fi
             fi
+        fi
 
-            # If npm still not found (e.g. no root/sudo privileges on cloud workstation):
-            if ! command -v npm >/dev/null 2>&1; then
+        # 4. Standalone portable Node.js LTS (zero-admin user space fallback, guaranteed compatible)
+        if ! is_node_compatible; then
             ARCH="$(uname -m)"
             NODE_ARCH=""
             case "${ARCH}" in
                 x86_64|amd64) NODE_ARCH="x64" ;;
                 aarch64|arm64) NODE_ARCH="arm64" ;;
             esac
-                if [ -n "${NODE_ARCH}" ]; then
-                    NODE_VER="v20.18.3"
+            OS_SYS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+            if [ -n "${NODE_ARCH}" ] && { [ "${OS_SYS}" = "linux" ] || [ "${OS_SYS}" = "darwin" ]; }; then
+                NODE_VER="v22.23.2"
                 NODE_DIR="${HOME}/.local/share/node"
                 echo -e "   ${CYAN}📦 Installing portable Node.js ${NODE_VER} in user space (~/.local)...${NC}"
+                rm -rf "${NODE_DIR}"
                 mkdir -p "${NODE_DIR}" "${HOME}/.local/bin"
-                    if curl -fsSL "https://nodejs.org/dist/${NODE_VER}/node-${NODE_VER}-linux-${NODE_ARCH}.tar.gz" | tar -xz -C "${NODE_DIR}" --strip-components=1 2>/dev/null; then
+                if curl -fsSL "https://nodejs.org/dist/${NODE_VER}/node-${NODE_VER}-${OS_SYS}-${NODE_ARCH}.tar.gz" | tar -xz -C "${NODE_DIR}" --strip-components=1 2>/dev/null; then
                     ln -sf "${NODE_DIR}/bin/node" "${HOME}/.local/bin/node"
                     ln -sf "${NODE_DIR}/bin/npm" "${HOME}/.local/bin/npm"
                     ln -sf "${NODE_DIR}/bin/npx" "${HOME}/.local/bin/npx"
                     export PATH="${NODE_DIR}/bin:${HOME}/.local/bin:${PATH}"
-                        echo -e "   ${GREEN}✓ Portable Node.js installed in user space.${NC}"
-                    fi
+                    hash -r 2>/dev/null || true
+                    echo -e "   ${GREEN}✓ Portable Node.js ${NODE_VER} installed in user space.${NC}"
                 fi
             fi
         fi
     fi
 
-    if command -v npm >/dev/null 2>&1; then
+    if is_node_compatible; then
+        echo -e "   ${GREEN}✓ Node.js $(node -v 2>/dev/null) and npm $(npm -v 2>/dev/null) ready.${NC}"
         echo -e "   ${YELLOW}🎨 Showcase UI build not found. Compiling Angular Showcase UI...${NC}"
         (
             cd "${SCRIPT_DIR}/apps/showcase_ui"
@@ -286,7 +335,7 @@ if [ ! -f "${SHOWCASE_INDEX}" ] && [ ! -f "${SHOWCASE_INDEX_ALT1}" ] && [ ! -f "
             npm run build
         )
     else
-        echo -e "   ${YELLOW}⚠ Could not auto-install Node.js. Showcase UI will serve fallback build notice.${NC}"
+        echo -e "   ${YELLOW}⚠ Could not configure compatible Node.js (>= 22.22.0). Showcase UI will serve fallback build notice.${NC}"
     fi
 fi