@akash-chowdhury-24/deployhub 2.0.19 → 2.0.21

package/README.md

@@ -31,17 +31,52 @@ Downloads the latest release from [GitHub Releases](https://github.com/Akash-Cho
 curl -fsSL https://raw.githubusercontent.com/Akash-Chowdhury-24/DeployHub/main/install.sh | sh
 ```
 
-Supported platforms: Linux x64, macOS x64, macOS ARM64. If the binary download fails, the script falls back to `npm install -g`.
+Supported platforms: Linux x64, macOS x64, macOS ARM64. If the binary download fails, the script falls back to `npm install -g`. After install it warns if `deployhub` on PATH still resolves to a different (e.g. older npm-global) binary — see the Windows notes below for the same dual-channel conflict.
+
+> **macOS `install.sh` — UNTESTED on real hardware in this project’s verification so far**
+>
+> Release assets `deployhub-macos-x64` and `deployhub-macos-arm64` are published and downloadable, and `install.sh` has `darwin` / `x86_64` / `arm64` branches that *should* select those names. The PATH-collision warning and clean/no-collision cases were proven on **Windows** (native) and **Linux** (Docker). They have **not** been run on a real Mac (Intel or Apple Silicon). Linux Docker proof does **not** cover macOS: different `uname` platform branch, different binary assets, BSD userland (`sed` / `readlink` / etc.), and default interactive shell is **zsh** (Catalina+) — the script does not edit `.zshrc` / `.zprofile` / `.bashrc` at all; for a non-sudo install it only prints that you must ensure `~/.local/bin` is on PATH. Treat first macOS binary install as unverified until someone pastes real Terminal output for collision + clean cases on both arch flavors (or at least the arch you use).
 
 ### Standalone binary (Windows)
 
-Run in PowerShell:
+Run in **PowerShell** (does **not** require an elevated/Administrator session — installs under your user profile only):
 
 ```powershell
 irm https://raw.githubusercontent.com/Akash-Chowdhury-24/DeployHub/main/install.ps1 | iex
 ```
 
-Installs to `%LOCALAPPDATA%\Programs\DeployHub` and adds it to your user PATH. On Windows ARM64, the script installs via npm instead (no native binary yet).
+**What the script actually does:**
+- **x64:** downloads the GitHub Release asset `deployhub-win.exe` and saves it as `%LOCALAPPDATA%\Programs\DeployHub\deployhub.exe` (plain `deployhub` on PATH), then appends that folder to your **user** `PATH` (not machine-wide).
+- **ARM64:** there is no Windows ARM64 binary yet — the script skips the download and runs `npm install -g @akash-chowdhury-24/deployhub@latest` immediately (**requires Node.js 18+**).
+- **Failed x64 download:** the script **does** fall back to the same npm global install (also requires Node.js 18+). If you have neither a working download nor Node.js, installation fails.
+- **No checksum/signature check in the script** — release assets include a `checksums.txt` (SHA-256), but `install.ps1` does not verify it automatically. Binaries are **not Authenticode code-signed**.
+- **PATH collision warning:** if an older install (commonly `npm install -g`) still resolves first, the script prints a warning with `Get-Command deployhub -All` / `npm uninstall -g` guidance. `install.sh` on Linux/macOS does the same check (`type -a deployhub`).
+
+> **Open a new PowerShell window after installing.** User `PATH` changes do not apply to the window that ran `iex`. Until you open a new session, `deployhub` may be “not recognized” even though the install succeeded.
+
+> **Previously installed via npm?** Binary and npm installs can both put `deployhub` on PATH. After the binary installer finishes, if `deployhub --version` still shows an older version, run `Get-Command deployhub -All` (Windows) or `type -a deployhub` (Linux/macOS). Remove the stale npm copy with `npm uninstall -g @akash-chowdhury-24/deployhub`, or put `%LOCALAPPDATA%\Programs\DeployHub` (Windows) / `/usr/local/bin` or `~/.local/bin` (Unix) earlier in PATH. Then open a **new** terminal and re-check `--version`.
+
+> **Windows `pkg` binary — what is and isn’t verified**
+>
+> DeployHub’s only native-adjacent dependency is **`ssh2`** (used by SSH / EC2 / Azure VM / GCP VM). It optionally uses `cpu-features` and an optional `sshcrypto.node` binding; both are try/catch’d and fall back to pure JS/`crypto` when missing. `cpu-features` is **not** listed in `pkg.assets` and is typically absent from installs — that is expected. Storage SDKs (`@aws-sdk/*`, `@azure/storage-blob`, `@google-cloud/storage`, `googleapis`, `dropbox`, `basic-ftp`) and `execa` (Docker / Kubernetes / cloud-CLI lookups) are pure JS / HTTP / process-spawn.
+>
+> **Exercised on the published `deployhub-win.exe` (module load / CLI spawn — not a full live deploy):**
+> - CLI boot (`--version` / `--help`)
+> - **SSH path:** `ssh2`/`node-ssh` load and attempt a real TCP connect (failed on missing key / `ECONNREFUSED` — i.e. past native-load risk)
+> - **AWS S3 SDK** load (SDK warning + doctor AWS check ran)
+> - **Azure / GCP / Google Drive / Dropbox / local** storage provider modules load (doctor checks ran; failures were credentials/API/ENOENT — not `MODULE_NOT_FOUND`)
+> - **Docker** via `execa` → host `docker.exe` (daemon pipe missing is an environment issue; spawn worked)
+> - **Kubernetes** via `execa` → host `kubectl` (cluster unreachable; spawn worked)
+>
+> **Still unproven end-to-end on Windows binary against real infrastructure:** a successful SSH session to a live host (auth + remote commands), a successful S3 (or other cloud) upload with real credentials, and a successful Docker/Kubernetes deploy. Those remain first-real-use risks for network/auth/config — not for missing native addons based on current evidence. If SSH from the `.exe` misbehaves oddly, compare with `npm install -g @akash-chowdhury-24/deployhub` (requires Node.js 18+).
+
+Manual checksum check (optional, recommended for locked-down environments):
+
+```powershell
+# After install, or after downloading deployhub-win.exe from the release page:
+Get-FileHash "$env:LOCALAPPDATA\Programs\DeployHub\deployhub.exe" -Algorithm SHA256
+# Compare to the deployhub-win.exe line in checksums.txt from the same release.
+```
 
 ### Manual download
 
@@ -618,6 +653,8 @@ All JS frontends share the same install/build flow: `npm ci` → `npm run build`
 - **Install:** Composer (on CI and server).
 - **Deploy:** SSH with PHP-FPM or `php artisan` for Laravel.
 
+> ⚠️ **PHP-FPM deployments restart the FPM service for the ENTIRE host on every deploy.** If you run multiple DeployHub-managed environments on the same server, deploying ANY of them will briefly interrupt in-flight requests for ALL of them. For production use with multiple environments, either use separate hosts per environment, or set up per-environment PHP-FPM pools manually (not yet automated by DeployHub).
+
 ### Java
 
 - **Detect:** `pom.xml` with Spring Boot.
@@ -1059,6 +1096,15 @@ Prefer `deployhub init` over hand-writing config — it sets adapters, workflow,
 | Tests fail in CI | Set `"pipeline": { "test": false }` temporarily, or fix tests |
 | Monorepo subfolders | Edit `buildCommand` paths in `deployhub.config.json` after init |
 
+### Windows install (`install.ps1`)
+
+| Problem | Fix |
+|---------|-----|
+| `irm` / `iex` blocked, or SmartScreen / Defender flags `deployhub.exe` | The Windows binary is **not Authenticode code-signed**, so SmartScreen often warns on first run. Click **More info → Run anyway**, or download `deployhub-win.exe` + `checksums.txt` from [Releases](https://github.com/Akash-Chowdhury-24/DeployHub/releases/latest) and verify the SHA-256 hash before running. If your org blocks unsigned binaries entirely, install via npm instead: `npm install -g @akash-chowdhury-24/deployhub` (requires Node.js 18+). |
+| `deployhub : The term 'deployhub' is not recognized` right after install | **Open a new PowerShell window** first — user `PATH` updates do not apply to the session that ran `iex`. Confirm the file exists at `%LOCALAPPDATA%\Programs\DeployHub\deployhub.exe`. If it is missing, re-run the install script or use the npm fallback. |
+| `deployhub --version` shows an unexpected / old version | Compare against the [latest release tag](https://github.com/Akash-Chowdhury-24/DeployHub/releases/latest). Run `Get-Command deployhub -All` (Windows) or `type -a deployhub` (Unix) — an older **npm global** install often wins PATH order. Fix: `npm uninstall -g @akash-chowdhury-24/deployhub`, or put the binary install dir first in PATH, then open a **new** terminal. Force a clean binary reinstall: delete `%LOCALAPPDATA%\Programs\DeployHub`, re-run `install.ps1`, open a new PowerShell window. |
+| Binary download fails and npm fallback errors | The x64 script falls back to `npm install -g …` when the GitHub download fails. That fallback **requires Node.js 18+ and npm on PATH**. Without Node, fix network access to GitHub Releases, or install Node and retry. |
+
 Run `deployhub doctor` after any config change.
 
 ---

package/install.ps1

@@ -1,11 +1,19 @@
 # DeployHub install script for Windows
-# Author: Akash Chowdhury — canonical source: src/utils/author.js
+# Author: Akash Chowdhury - canonical source: src/utils/author.js
 # Repository: https://github.com/Akash-Chowdhury-24/DeployHub
+#
+# IMPORTANT: PowerShell variable names are CASE-INSENSITIVE.
+# Never use $BinaryName / $binaryName as two different values - the second write
+# overwrites the first (that bug previously saved deployhub-win.exe instead of deployhub.exe).
 
 $ErrorActionPreference = "Stop"
 
 $GitHubRepo = "Akash-Chowdhury-24/DeployHub"
-$BinaryName = "deployhub.exe"
+# Filename on disk after install (what PATH resolves as `deployhub`)
+$InstalledExeName = "deployhub.exe"
+# GitHub Release asset name for Windows x64
+$ReleaseAssetName = "deployhub-win.exe"
+$NpmPackage = "@akash-chowdhury-24/deployhub"
 
 function Get-LatestVersion {
     $release = Invoke-RestMethod -Uri "https://api.github.com/repos/$GitHubRepo/releases/latest"
@@ -20,46 +28,163 @@ function Get-InstallDir {
     return $localBin
 }
 
+function Refresh-SessionPathFromPersistent {
+    # Rebuild PATH the way a NEW PowerShell window would see it after our User PATH edit.
+    # Do NOT prepend the install dir here - that would hide npm-global collisions
+    # (user PATH appends DeployHub at the end; npm often wins earlier in PATH).
+    $machinePath = [Environment]::GetEnvironmentVariable("Path", "Machine")
+    $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+    if ($machinePath -and $userPath) {
+        $env:Path = "$machinePath;$userPath"
+    } elseif ($userPath) {
+        $env:Path = $userPath
+    } elseif ($machinePath) {
+        $env:Path = $machinePath
+    }
+}
+
 function Add-ToPath {
     param([string]$Dir)
     $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
     if ($userPath -notlike "*$Dir*") {
-        [Environment]::SetEnvironmentVariable("Path", "$userPath;$Dir", "User")
-        $env:Path = "$env:Path;$Dir"
+        if ([string]::IsNullOrWhiteSpace($userPath)) {
+            [Environment]::SetEnvironmentVariable("Path", $Dir, "User")
+        } else {
+            [Environment]::SetEnvironmentVariable("Path", "$userPath;$Dir", "User")
+        }
         Write-Host "Added $Dir to user PATH"
     }
+    Refresh-SessionPathFromPersistent
+}
+
+function Get-VersionFromOutput {
+    param([string]$Output)
+    if ([string]::IsNullOrWhiteSpace($Output)) { return $null }
+    $line = ($Output -split "`r?`n" | Where-Object { $_.Trim() -ne '' } | Select-Object -First 1)
+    if (-not $line) { return $null }
+    if ($line -match '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)') {
+        return $Matches[1]
+    }
+    return $line.Trim()
+}
+
+function Warn-PathCollision {
+    param(
+        [string]$InstallDir,
+        [string]$InstalledExe,
+        [string]$ExpectedTag
+    )
+
+    $expectedVersion = $ExpectedTag.TrimStart('v')
+    $directOut = & $InstalledExe --version 2>&1 | Out-String
+    $directVersion = Get-VersionFromOutput $directOut
+
+    Write-Host ""
+    Write-Host "Installed binary reports: $(if ($directVersion) { $directVersion } else { '(unknown)' }) ($InstalledExe)"
+
+    # Re-sync PATH from Machine+User so this check matches a freshly opened shell.
+    Refresh-SessionPathFromPersistent
+
+    $resolved = $null
+    try {
+        $resolved = Get-Command deployhub -ErrorAction Stop
+    } catch {
+        Write-Host "Note: 'deployhub' is not yet visible on PATH in this session." -ForegroundColor Yellow
+        Write-Host "Open a NEW PowerShell window, then run: deployhub --version" -ForegroundColor Yellow
+        return
+    }
+
+    $resolvedPath = $resolved.Source
+    # Prefer .exe over .cmd/.ps1 shims when comparing versions of what PATH runs
+    $pathOut = & deployhub --version 2>&1 | Out-String
+    $pathVersion = Get-VersionFromOutput $pathOut
+
+    $installedFull = [System.IO.Path]::GetFullPath($InstalledExe)
+    $resolvedFull = [System.IO.Path]::GetFullPath($resolvedPath)
+
+    # npm global on Windows resolves to deployhub.cmd / deployhub.ps1, not our .exe
+    $sameFile = ($installedFull -ieq $resolvedFull)
+    $versionMatch = $pathVersion -and $expectedVersion -and ($pathVersion -eq $expectedVersion)
+
+    if ($sameFile -and $versionMatch) {
+        Write-Host "PATH resolves to the newly installed binary ($pathVersion). OK."
+        Write-Host "Still open a NEW PowerShell window before day-to-day use so user PATH updates apply cleanly."
+        return
+    }
+
+    if ((-not $sameFile) -or (-not $versionMatch)) {
+        Write-Host ""
+        Write-Host "WARNING: Installed DeployHub $expectedVersion to $InstallDir," -ForegroundColor Yellow
+        Write-Host "  but running 'deployhub --version' currently resolves to a DIFFERENT" -ForegroundColor Yellow
+        Write-Host "  installation reporting a different version (or path)." -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "  Expected:  $installedFull  ($expectedVersion)"
+        Write-Host "  Resolved:  $resolvedFull  ($(if ($pathVersion) { $pathVersion } else { 'unknown version' }))"
+        Write-Host ""
+        Write-Host "  This usually means an older install (e.g. via 'npm install -g') is earlier in your PATH."
+        Write-Host ""
+        Write-Host "  To see every 'deployhub' on your PATH, run:"
+        Write-Host "    Get-Command deployhub -All"
+        Write-Host ""
+        Write-Host "  To remove a conflicting npm install:"
+        Write-Host "    npm uninstall -g $NpmPackage"
+        Write-Host ""
+        Write-Host "  Or reorder your PATH so $InstallDir comes first."
+        Write-Host ""
+        Write-Host "  This check rebuilds PATH from your saved Machine+User environment" -ForegroundColor Yellow
+        Write-Host "  (same order a NEW PowerShell window would use). After fixing PATH," -ForegroundColor Yellow
+        Write-Host "  open a NEW window and run: deployhub --version" -ForegroundColor Yellow
+    }
 }
 
 try {
     $arch = $env:PROCESSOR_ARCHITECTURE
     if ($arch -eq "ARM64") {
-        $binaryName = "deployhub-macos-arm64"  # no Windows ARM64 binary yet
-        Write-Host "Windows ARM64 detected — no native binary available yet. Installing via npm instead..."
-        npm install -g @akash-chowdhury-24/deployhub@latest
+        Write-Host "Windows ARM64 detected - no native binary available yet. Installing via npm instead..."
+        npm install -g "$NpmPackage@latest"
         exit 0
-    } else {
-        $binaryName = "deployhub-win.exe"
     }
 
     $version = Get-LatestVersion
-    $assetName = $binaryName
-    $url = "https://github.com/$GitHubRepo/releases/download/$version/$assetName"
+    $url = "https://github.com/$GitHubRepo/releases/download/$version/$ReleaseAssetName"
     $installDir = Get-InstallDir
-    $dest = Join-Path $installDir $BinaryName
+    $dest = Join-Path $installDir $InstalledExeName
 
-    Write-Host "Downloading DeployHub $version for Windows..."
-    Invoke-WebRequest -Uri $url -OutFile $dest -UseBasicParsing
+    Write-Host "Downloading DeployHub $version for Windows ($ReleaseAssetName -> $InstalledExeName)..."
+    # Download to a temp name first, then rename - avoids leaving a half-written deployhub.exe
+    $tmpDest = Join-Path $installDir ("deployhub-download-" + [guid]::NewGuid().ToString("n") + ".exe")
+    try {
+        Invoke-WebRequest -Uri $url -OutFile $tmpDest -UseBasicParsing
+        if (-not (Test-Path $tmpDest) -or (Get-Item $tmpDest).Length -eq 0) {
+            throw "Binary download failed"
+        }
+        # Remove any legacy misnamed asset from older install.ps1 (PowerShell case-bug).
+        $legacy = Join-Path $installDir $ReleaseAssetName
+        if (Test-Path $legacy) {
+            Remove-Item -Force $legacy -ErrorAction SilentlyContinue
+        }
+        Move-Item -Force -Path $tmpDest -Destination $dest
+    } finally {
+        if (Test-Path $tmpDest) {
+            Remove-Item -Force $tmpDest -ErrorAction SilentlyContinue
+        }
+    }
 
     if (-not (Test-Path $dest) -or (Get-Item $dest).Length -eq 0) {
-        throw "Binary download failed"
+        throw "Binary install failed - $InstalledExeName missing after download"
+    }
+
+    if ((Split-Path -Leaf $dest) -ne $InstalledExeName) {
+        throw "Internal error: installed file is not named $InstalledExeName"
     }
 
     Add-ToPath $installDir
     Write-Host "DeployHub $version installed to $dest"
-    & $dest --version
+    Write-Host "On-disk filename: $(Split-Path -Leaf $dest)"
+    Warn-PathCollision -InstallDir $installDir -InstalledExe $dest -ExpectedTag $version
 }
 catch {
     Write-Host "Binary install failed ($($_.Exception.Message)). Falling back to npm..." -ForegroundColor Yellow
-    npm install -g @akash-chowdhury-24/deployhub@latest
+    npm install -g "$NpmPackage@latest"
     Write-Host "DeployHub installed via npm."
 }

package/install.sh

@@ -8,6 +8,8 @@ set -e
 GITHUB_REPO="Akash-Chowdhury-24/DeployHub"
 INSTALL_DIR="/usr/local/bin"
 BINARY_NAME="deployhub"
+NPM_PACKAGE="@akash-chowdhury-24/deployhub"
+INSTALLED_PATH=""
 
 detect_platform() {
   OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
@@ -50,7 +52,7 @@ fetch_latest_version() {
 
   if [ -z "$VERSION" ]; then
     echo "Could not determine latest release version. Falling back to npm install." >&2
-    npm install -g @akash-chowdhury-24/deployhub@latest
+    npm install -g "${NPM_PACKAGE}@latest"
     echo "DeployHub installed via npm."
     exit 0
   fi
@@ -71,19 +73,22 @@ download_binary() {
   if [ ! -s "$TMP" ]; then
     echo "Binary download failed. Falling back to npm install." >&2
     rm -f "$TMP"
-    npm install -g @akash-chowdhury-24/deployhub@latest
+    npm install -g "${NPM_PACKAGE}@latest"
     echo "DeployHub installed via npm."
     exit 0
   fi
 
   if [ "$(id -u)" -eq 0 ]; then
     install -m 755 "$TMP" "${INSTALL_DIR}/${BINARY_NAME}"
+    INSTALLED_PATH="${INSTALL_DIR}/${BINARY_NAME}"
   else
     if command -v sudo >/dev/null 2>&1; then
       sudo install -m 755 "$TMP" "${INSTALL_DIR}/${BINARY_NAME}"
+      INSTALLED_PATH="${INSTALL_DIR}/${BINARY_NAME}"
     else
       mkdir -p "${HOME}/.local/bin"
       install -m 755 "$TMP" "${HOME}/.local/bin/${BINARY_NAME}"
+      INSTALLED_PATH="${HOME}/.local/bin/${BINARY_NAME}"
       echo "Installed to ${HOME}/.local/bin/${BINARY_NAME} — ensure it is on your PATH"
     fi
   fi
@@ -91,9 +96,82 @@ download_binary() {
   rm -f "$TMP"
 }
 
+# Compare PATH-resolved `deployhub` to the binary we just installed.
+warn_path_collision() {
+  EXPECTED_VERSION="${VERSION#v}"
+  if [ -z "$INSTALLED_PATH" ] || [ ! -x "$INSTALLED_PATH" ]; then
+    return 0
+  fi
+
+  INSTALL_BIN_DIR="$(dirname "$INSTALLED_PATH")"
+  # Put install dir on PATH only if missing, and APPEND (do not prepend).
+  # Prepending would hide an older npm-global install that sits earlier on PATH —
+  # the same failure mode the Windows installer hit.
+  case ":${PATH}:" in
+    *":${INSTALL_BIN_DIR}:"*) ;;
+    *) PATH="${PATH}:${INSTALL_BIN_DIR}"; export PATH ;;
+  esac
+
+  DIRECT_OUT="$("$INSTALLED_PATH" --version 2>/dev/null || true)"
+  DIRECT_VER="$(printf '%s\n' "$DIRECT_OUT" | head -n 1 | tr -d '\r' | sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*[-0-9A-Za-z.]*\).*/\1/p')"
+
+  echo ""
+  echo "Installed binary reports: ${DIRECT_VER:-unknown} ($INSTALLED_PATH)"
+
+  if ! command -v deployhub >/dev/null 2>&1; then
+    echo "Note: 'deployhub' is not yet visible on PATH in this shell."
+    echo "Open a NEW terminal, then run: deployhub --version"
+    return 0
+  fi
+
+  RESOLVED_PATH="$(command -v deployhub)"
+  PATH_OUT="$(deployhub --version 2>/dev/null || true)"
+  PATH_VER="$(printf '%s\n' "$PATH_OUT" | head -n 1 | tr -d '\r' | sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*[-0-9A-Za-z.]*\).*/\1/p')"
+
+  # Resolve symlinks where possible for a fair path comparison.
+  # Prefer `realpath` (GNU coreutils; also present on recent macOS).
+  # Do NOT use `readlink -f` — that flag is GNU-only; BSD readlink on macOS
+  # rejects `-f` (the `|| echo` fallback usually masks it, but it is not portable).
+  INST_REAL="$INSTALLED_PATH"
+  RES_REAL="$RESOLVED_PATH"
+  if command -v realpath >/dev/null 2>&1; then
+    INST_REAL="$(realpath "$INSTALLED_PATH" 2>/dev/null || echo "$INSTALLED_PATH")"
+    RES_REAL="$(realpath "$RESOLVED_PATH" 2>/dev/null || echo "$RESOLVED_PATH")"
+  fi
+
+  if [ "$INST_REAL" = "$RES_REAL" ] && [ -n "$PATH_VER" ] && [ "$PATH_VER" = "$EXPECTED_VERSION" ]; then
+    echo "PATH resolves to the newly installed binary ($PATH_VER). OK."
+    echo "Still open a NEW terminal before day-to-day use so your shell profile PATH applies cleanly."
+    return 0
+  fi
+
+  echo ""
+  echo "WARNING: Installed DeployHub ${EXPECTED_VERSION} to ${INSTALLED_PATH},"
+  echo "  but running 'deployhub --version' currently resolves to a DIFFERENT"
+  echo "  installation reporting a different version (or path)."
+  echo ""
+  echo "  Expected:  ${INST_REAL}  (${EXPECTED_VERSION})"
+  echo "  Resolved:  ${RES_REAL}  (${PATH_VER:-unknown version})"
+  echo ""
+  echo "  This usually means an older install (e.g. via 'npm install -g') is earlier in your PATH."
+  echo ""
+  echo "  To see every 'deployhub' on your PATH, run:"
+  echo "    type -a deployhub"
+  echo "    # or: which -a deployhub"
+  echo ""
+  echo "  To remove a conflicting npm install:"
+  echo "    npm uninstall -g ${NPM_PACKAGE}"
+  echo ""
+  echo "  Or reorder your PATH so the directory containing the new binary comes first."
+  echo ""
+  echo "  This check uses the CURRENT shell PATH (install dir appended only if it was"
+  echo "  missing — not prepended, so earlier npm installs are not hidden). After fixing"
+  echo "  PATH, open a NEW terminal and run: deployhub --version"
+}
+
 detect_platform
 fetch_latest_version
 download_binary
 
 echo "DeployHub ${VERSION} installed successfully."
-deployhub --version 2>/dev/null || true
+warn_path_collision

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/commands/init.js

@@ -36,7 +36,7 @@ import {
   printDeploymentNextSteps,
   formatSecretChecklistLine,
 } from '../deployment/deployment-env.js';
-import { confirmValueIfContainsSpaces } from '../deployment/init-helpers.js';
+import { confirmValueIfContainsSpaces, normalizeInitHealthCheckUrl } from '../deployment/init-helpers.js';
 
 const FRONTEND_CHOICES = [
   { name: 'React', value: 'react' },
@@ -405,10 +405,13 @@ export function registerInitCommand(program) {
 
           environments[name] = entry;
 
-          if (deployAnswers.healthUrl) {
-            healthUrl = deployAnswers.healthUrl;
-          } else if (!healthUrl && (singleConfig?.port || backendConfig?.port)) {
-            healthUrl = `http://localhost:${singleConfig?.port || backendConfig?.port}/health`;
+          // Only persist a health check URL the user actually entered.
+          // Never synthesize http://localhost:<port>/health — that always fails
+          // from GitHub Actions (remote runner ≠ deploy target) and incorrectly
+          // enables the verify stage when the user left the optional prompt blank.
+          const answered = normalizeInitHealthCheckUrl(deployAnswers.healthUrl);
+          if (answered) {
+            healthUrl = answered;
           }
 
           const secrets = getDockerEnvSecrets(deployAnswers);

package/src/deployment/init-helpers.js

@@ -32,6 +32,18 @@ export function suggestSshUser(osHint) {
   return undefined;
 }
 
+/**
+ * Normalize the optional health-check URL from `deployhub init`.
+ * Blank / whitespace → empty string. Never synthesizes localhost defaults
+ * (those always fail from GitHub Actions runners, which are not the deploy target).
+ *
+ * @param {unknown} answer
+ * @returns {string}
+ */
+export function normalizeInitHealthCheckUrl(answer) {
+  return typeof answer === 'string' && answer.trim() ? answer.trim() : '';
+}
+
 /**
  * @param {string} keyPath
  * @returns {Promise<{ ok: boolean, message: string, fixed?: boolean }>}

package/src/deployment/providers/docker.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import { createLogger } from '../../logger/index.js';
 import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
 import { resolveDockerImageRefForTag } from '../../utils/docker-image.js';
+import { resolveDockerContainerName } from '../../utils/docker-container-name.js';
 import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environments.js';
 
 /**
@@ -15,6 +16,8 @@ export function createDockerProvider(config, envName, env = process.env) {
   const effectiveEnv = mergeMethodSettingsIntoEnv(env, settings);
   const imageOps = createDockerImageDeployContext(config, effectiveEnv, log);
   const { fullImage, getDockerEnv, ensureImageReadyForDeploy } = imageOps;
+  // Env-scoped like PM2/Nginx — same-daemon multi-env must not share one container name.
+  const containerName = resolveDockerContainerName(config, envName);
 
   /**
    * @param {string} artifactDir
@@ -36,11 +39,11 @@ export function createDockerProvider(config, envName, env = process.env) {
 
     await execa(
       'docker',
-      ['rm', '-f', config.project],
+      ['rm', '-f', containerName],
       { stdio: 'pipe', env: dockerEnv }
     ).catch(() => {});
 
-    await execa('docker', ['run', '-d', '--rm', '--name', config.project, imageRef], {
+    await execa('docker', ['run', '-d', '--rm', '--name', containerName, imageRef], {
       stdio: 'inherit',
       env: dockerEnv,
     });
@@ -81,7 +84,7 @@ export function createDockerProvider(config, envName, env = process.env) {
     try {
       const { stdout } = await execa(
         'docker',
-        ['ps', '--filter', `name=${config.project}`, '--format', '{{.Status}}'],
+        ['ps', '--filter', `name=^/${containerName}$`, '--format', '{{.Status}}'],
         { stdio: 'pipe', env: getDockerEnv() }
       );
       return stdout.includes('Up');

package/src/deployment/providers/kubernetes.js

@@ -8,6 +8,7 @@ import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.
 import { resolveDockerImageRefForTag } from '../../utils/docker-image.js';
 import { ensureKubernetesNamespace } from '../../utils/kubernetes-namespace.js';
 import { syncKubernetesDeploymentImage } from '../../utils/kubernetes-deploy-image.js';
+import { resolveKubeNamespace } from '../../utils/kube-namespace-name.js';
 import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environments.js';
 
 /**
@@ -24,8 +25,9 @@ export function createKubernetesProvider(config, envName, env = process.env) {
   const kubeconfig =
     effectiveEnv.KUBECONFIG || path.join(os.homedir(), '.kube', 'config');
   const context = effectiveEnv.KUBE_CONTEXT || '';
-  const namespace =
-    effectiveEnv.KUBE_NAMESPACE || config.project || 'default';
+  // Env-scoped like Nginx/PM2 — same-cluster multi-env must not share one namespace
+  // when settings still default to the project name for every environment.
+  const namespace = resolveKubeNamespace(config, envName, effectiveEnv);
   const deploymentName = sanitizeK8sName(config.project || 'app');
 
   function getKubectlEnv() {

package/src/deployment/providers/ssh.js

@@ -10,6 +10,7 @@ import {
   getNginxConfDPath,
   resolveNginxSiteName,
 } from '../../utils/nginx.js';
+import { resolvePm2AppName } from '../../utils/pm2-app-name.js';
 import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
 
 /** @type {Set<string>} */
@@ -44,8 +45,8 @@ export function createSshProvider(config, envName, env = process.env) {
     settings.frontendDeployPath || deployPath;
   const backendDeployPath =
     settings.backendDeployPath || deployPath;
-  const appName =
-    settings.appName || env.SSH_APP_NAME || config.project;
+  // Env-scoped like Nginx site names — same-host multi-env must not share one PM2 name.
+  const appName = resolvePm2AppName(config, envName, env);
   const port = settings.port || config.port || Number(env.SSH_PORT) || 3000;
   const sshKey = env.SSH_KEY;
   const keyPath = settings.keyPath || env.SSH_KEY_PATH;
@@ -133,6 +134,58 @@ export function createSshProvider(config, envName, env = process.env) {
     );
   }
 
+  /**
+   * Stop a previously managed non-PM2 backend for THIS env only.
+   *
+   * PID-file kill is gated: we only signal a PID if /proc shows our
+   * DEPLOYHUB_APP / deployhub.app marker in cmdline or environ. A stale PID
+   * reused by an unrelated process is left alone (file still removed).
+   * Marker-based pkill remains the primary stop for live processes.
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} targetPath
+   */
+  async function stopScopedBackendProcess(ssh, targetPath) {
+    const pidFile = `${targetPath}/.deployhub.pid`;
+    const markerEnv = `DEPLOYHUB_APP=${appName}`;
+    const markerJvm = `deployhub.app=${appName}`;
+    // Verify-then-kill: only signal a PID if /proc shows our marker in cmdline
+    // or environ. A stale PID reused by an unrelated process is left alone
+    // (the pidfile is still removed so the next start writes a fresh one).
+    await exec(
+      ssh,
+      `if [ -f ${sh(pidFile)} ]; then ` +
+        `pid="$(cat ${sh(pidFile)} 2>/dev/null | tr -cd '0-9')"; ` +
+        `if [ -n "$pid" ] && [ -r "/proc/$pid/cmdline" ]; then ` +
+          `if tr '\\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q -F ${sh(markerEnv)} ` +
+          `|| tr '\\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q -F ${sh(markerJvm)} ` +
+          `|| { [ -r "/proc/$pid/environ" ] && tr '\\0' ' ' < "/proc/$pid/environ" 2>/dev/null | grep -q -F ${sh(markerEnv)}; }; then ` +
+            `kill "$pid" 2>/dev/null || true; ` +
+          `fi; ` +
+        `fi; ` +
+        `rm -f ${sh(pidFile)}; ` +
+      `fi`
+    );
+    // Marker match — covers lost PID files / processes without a readable pidfile.
+    await exec(ssh, `pkill -f ${sh(markerEnv)} || true`);
+    await exec(ssh, `pkill -f ${sh(markerJvm)} || true`);
+  }
+
+  /**
+   * Start a nohup process with DEPLOYHUB_APP marker and write PID file.
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} targetPath
+   * @param {string} command — command body after `nohup` (no trailing &)
+   */
+  async function startScopedNohup(ssh, targetPath, command) {
+    const pidFile = `${targetPath}/.deployhub.pid`;
+    const dir = sh(targetPath);
+    await exec(
+      ssh,
+      `cd ${dir} && DEPLOYHUB_APP=${sh(appName)} nohup ${command} > app.log 2>&1 & echo $! > ${sh(pidFile)}`
+    );
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} targetPath
@@ -141,6 +194,7 @@ export function createSshProvider(config, envName, env = process.env) {
     const framework = resolveFramework();
     const startCommand = resolveStartCommand();
     const dir = sh(targetPath);
+    const pidFile = `${targetPath}/.deployhub.pid`;
 
     if (NODE_FRAMEWORKS.has(framework)) {
       await exec(ssh, `cd ${dir} && npm install --production`);
@@ -172,25 +226,28 @@ export function createSshProvider(config, envName, env = process.env) {
       if (framework === 'django') {
         await exec(ssh, `cd ${dir} && python manage.py migrate`);
       }
+      await stopScopedBackendProcess(ssh, targetPath);
       if (framework === 'fastapi') {
-        await exec(ssh, 'pkill uvicorn || true');
-        await exec(
+        await startScopedNohup(
           ssh,
-          `cd ${dir} && nohup uvicorn main:app --host 0.0.0.0 --port ${port} > app.log 2>&1 &`
+          targetPath,
+          `uvicorn main:app --host 0.0.0.0 --port ${port}`
         );
       } else {
-        await exec(ssh, 'pkill gunicorn || true');
+        // gunicorn --daemon writes its own PID; still set DEPLOYHUB_APP for pkill fallback.
         const appTarget =
           framework === 'django' ? 'config.wsgi:application' : 'app:app';
         await exec(
           ssh,
-          `cd ${dir} && nohup gunicorn ${appTarget} --bind 0.0.0.0:${port} --daemon`
+          `cd ${dir} && DEPLOYHUB_APP=${sh(appName)} gunicorn ${appTarget} --name ${sh(`deployhub-${appName}`)} --bind 0.0.0.0:${port} --pid ${sh(pidFile)} --daemon`
         );
       }
       return;
     }
 
     if (PHP_FRAMEWORKS.has(framework)) {
+      // PHP uses a host-wide `systemctl restart php*-fpm` (see README PHP warning).
+      // Per-env isolation is Nginx site name + deploy path — not automated FPM pools.
       await exec(ssh, `cd ${dir} && composer install --no-dev`);
       if (framework === 'laravel') {
         await exec(ssh, `cd ${dir} && php artisan migrate --force`);
@@ -202,40 +259,36 @@ export function createSshProvider(config, envName, env = process.env) {
     }
 
     if (framework === 'spring' || framework === 'java') {
-      await exec(ssh, `cd ${dir} && pkill -f "*.jar" || true`);
-      await exec(
+      await stopScopedBackendProcess(ssh, targetPath);
+      // -Ddeployhub.app= embeds the env-scoped identity in the JVM command line
+      // so pkill -f DEPLOYHUB_APP=… and the PID file both target only this env.
+      await startScopedNohup(
         ssh,
-        `cd ${dir} && nohup java -jar target/*.jar > app.log 2>&1 &`
+        targetPath,
+        `java -Ddeployhub.app=${appName} -jar target/*.jar`
       );
       return;
     }
 
     if (framework === 'go') {
-      await exec(ssh, `cd ${dir} && pkill ${sh(appName)} || true`);
-      await exec(
-        ssh,
-        `cd ${dir} && nohup ./bin/app > app.log 2>&1 &`
-      );
+      await stopScopedBackendProcess(ssh, targetPath);
+      // Binary is always ./bin/app — must NOT pkill by appName alone (that never
+      // matched the process) and must NOT pkill a bare "app" (cross-env collision).
+      await startScopedNohup(ssh, targetPath, './bin/app');
       return;
     }
 
     if (framework === 'dotnet') {
-      await exec(ssh, `cd ${dir} && pkill -f "dotnet" || true`);
+      await stopScopedBackendProcess(ssh, targetPath);
       const dll = startCommand?.replace('dotnet ', '') || 'App.dll';
-      await exec(
-        ssh,
-        `cd ${dir} && nohup dotnet ${dll} > app.log 2>&1 &`
-      );
+      await startScopedNohup(ssh, targetPath, `dotnet ${dll}`);
       return;
     }
 
     if (framework === 'rails') {
       await exec(ssh, `cd ${dir} && bundle install --deployment`);
-      await exec(ssh, `cd ${dir} && pkill puma || true`);
-      await exec(
-        ssh,
-        `cd ${dir} && nohup bundle exec puma -p ${port} > app.log 2>&1 &`
-      );
+      await stopScopedBackendProcess(ssh, targetPath);
+      await startScopedNohup(ssh, targetPath, `bundle exec puma -p ${port}`);
       return;
     }
 

package/src/utils/docker-container-name.js

@@ -0,0 +1,51 @@
+import { isGrandfatheredNginxEnv } from './nginx.js';
+
+/**
+ * Sanitize a Docker container name (alphanumeric, underscore, hyphen, period).
+ * @param {string} name
+ * @returns {string}
+ */
+export function sanitizeDockerContainerName(name) {
+  return String(name || 'app')
+    .replace(/[^a-zA-Z0-9_.-]/g, '-')
+    .replace(/^[^a-zA-Z0-9]/, 'a');
+}
+
+/**
+ * Whether this env is the grandfathered / single-env case for container naming.
+ * Reuses the same grandfather rule as Nginx / PM2.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @returns {boolean}
+ */
+export function isGrandfatheredDockerContainerEnv(config, envName) {
+  return isGrandfatheredNginxEnv(config, envName);
+}
+
+/**
+ * Resolve the Docker container `--name` for an environment.
+ *
+ * Same risk class as PM2 process names: two docker envs targeting the same
+ * daemon with `docker run --name ${project}` will `docker rm -f` each other.
+ *
+ * - Grandfathered / single-env: `config.project` (unchanged).
+ * - Additional envs: `{project}-{env}`.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @returns {string}
+ */
+export function resolveDockerContainerName(config, envName) {
+  const project = sanitizeDockerContainerName(config.project || 'app');
+  if (isGrandfatheredDockerContainerEnv(config, envName)) {
+    return project;
+  }
+  return `${project}-${sanitizeDockerContainerName(envName)}`;
+}
+
+export default {
+  sanitizeDockerContainerName,
+  isGrandfatheredDockerContainerEnv,
+  resolveDockerContainerName,
+};

package/src/utils/kube-namespace-name.js

@@ -0,0 +1,63 @@
+import { isGrandfatheredNginxEnv } from './nginx.js';
+import { getEnvSettings } from '../core/environments.js';
+import { sanitizeK8sName } from './kubernetes-manifests.js';
+
+/**
+ * Whether this env is the grandfathered / single-env case for namespace naming.
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @returns {boolean}
+ */
+export function isGrandfatheredKubeNamespaceEnv(config, envName) {
+  return isGrandfatheredNginxEnv(config, envName);
+}
+
+/**
+ * Resolve the Kubernetes namespace for an environment.
+ *
+ * Deployment *names* stay project-scoped (safe when namespaces differ). Two
+ * environments targeting the same cluster with the same namespace WILL collide
+ * on Deployment/Service objects — same risk class as PM2/Nginx on one host.
+ *
+ * - Grandfathered / single-env: settings.kubeNamespace || KUBE_NAMESPACE || project
+ *   (unchanged).
+ * - Additional envs: if configured namespace is missing or equals the project /
+ *   grandfathered namespace, auto-scope to `{project}-{env}`. An explicitly
+ *   distinct namespace is kept.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @param {Record<string, string|undefined>} [env] — already secret-overlaid
+ * @returns {string}
+ */
+export function resolveKubeNamespace(config, envName, env = process.env) {
+  const project = sanitizeK8sName(config.project || 'app');
+  const settings = getEnvSettings(config.environments?.[envName]);
+  const configured = String(
+    settings.kubeNamespace || env.KUBE_NAMESPACE || ''
+  ).trim();
+
+  if (isGrandfatheredKubeNamespaceEnv(config, envName)) {
+    return sanitizeK8sName(configured || project);
+  }
+
+  const grandfather =
+    config.unprefixedSecretEnvironment || config.defaultEnvironment || null;
+  let grandfatherNs = project;
+  if (grandfather && config.environments?.[grandfather]) {
+    const gfSettings = getEnvSettings(config.environments[grandfather]);
+    grandfatherNs = sanitizeK8sName(gfSettings.kubeNamespace || project);
+  }
+
+  const defaults = new Set([project, 'default', grandfatherNs]);
+  if (configured && !defaults.has(sanitizeK8sName(configured))) {
+    return sanitizeK8sName(configured);
+  }
+
+  return sanitizeK8sName(`${project}-${envName}`);
+}
+
+export default {
+  isGrandfatheredKubeNamespaceEnv,
+  resolveKubeNamespace,
+};

package/src/utils/pm2-app-name.js

@@ -0,0 +1,71 @@
+import { isGrandfatheredNginxEnv } from './nginx.js';
+import { getEnvSettings } from '../core/environments.js';
+
+/**
+ * Sanitize a name for PM2 process naming (same charset as Nginx site names).
+ * @param {string} name
+ * @returns {string}
+ */
+export function sanitizePm2AppName(name) {
+  return String(name || 'app').replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+/**
+ * Whether this env is the grandfathered / single-env case for process naming.
+ * Reuses the same grandfather rule as Nginx site filenames.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @returns {boolean}
+ */
+export function isGrandfatheredPm2Env(config, envName) {
+  return isGrandfatheredNginxEnv(config, envName);
+}
+
+/**
+ * Resolve the PM2 process name for an environment.
+ *
+ * Same risk class as Nginx site filenames: two backend envs on one host with
+ * the same PM2 name will restart/replace each other's process.
+ *
+ * - Grandfathered / single-env: `settings.appName` || `SSH_APP_NAME` || `project`
+ *   (unchanged — existing single-env PM2 processes keep their name).
+ * - Additional envs: auto-scope to `{project}-{env}` when the configured name
+ *   is missing, equals the project default, or collides with the grandfathered
+ *   env's resolved name. An explicitly distinct `appName` / `SSH_APP_NAME` is kept.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @param {Record<string, string|undefined>} [env] — already secret-overlaid for this env
+ * @returns {string}
+ */
+export function resolvePm2AppName(config, envName, env = process.env) {
+  const project = sanitizePm2AppName(config.project || 'app');
+  const settings = getEnvSettings(config.environments?.[envName]);
+  const configured = (settings.appName || env.SSH_APP_NAME || '').trim();
+
+  if (isGrandfatheredPm2Env(config, envName)) {
+    return sanitizePm2AppName(configured || project);
+  }
+
+  const grandfather =
+    config.unprefixedSecretEnvironment || config.defaultEnvironment || null;
+  let grandfatherName = project;
+  if (grandfather && config.environments?.[grandfather]) {
+    const gfSettings = getEnvSettings(config.environments[grandfather]);
+    grandfatherName = sanitizePm2AppName(gfSettings.appName || project);
+  }
+
+  const defaults = new Set([project, `${project}-api`, grandfatherName]);
+  if (configured && !defaults.has(sanitizePm2AppName(configured))) {
+    return sanitizePm2AppName(configured);
+  }
+
+  return `${project}-${sanitizePm2AppName(envName)}`;
+}
+
+export default {
+  sanitizePm2AppName,
+  isGrandfatheredPm2Env,
+  resolvePm2AppName,
+};