@akash-chowdhury-24/deployhub 2.0.18 → 2.0.20

package/README.md

@@ -257,15 +257,78 @@ deployhub logs                       # last deployment logs
 | Argument | Behavior |
 |----------|----------|
 | *(none)* | Rolls back to the **previous** build (second entry in newest-first history) |
-| Exact `buildId` | Rolls back to that specific build |
+| Exact `buildId` | Rolls back to that specific build **if it appears in that env's history** |
 | Semver / version string matching **multiple** builds | Does **not** guess — prints the matching `buildId`s and exits; re-run with an exact one |
 
 `buildId` looks like `{semver}-{stamp}` where the stamp is a short git SHA when available, otherwise a CI run id, otherwise a high-resolution timestamp. When `DOCKER_IMAGE_TAG` is left unset, Docker and Kubernetes use that same `buildId` as the image tag — so you can correlate an artifact in storage with the image that was pushed.
 
+### Rollback is scoped per environment
+
+Each environment maintains its own independent deploy history. When you roll back an environment, DeployHub only considers builds that were actually deployed **to that environment** — never builds deployed to a different environment, even if they're more recent or share the same project.
+
+For example: if `development` has deployed builds A, C, and D (in that order), and `production` has separately deployed builds B and D, then rolling back `production` moves it from D to B — **not** to C, even though C is technically a more recent build overall, because C was never deployed to `production` in the first place.
+
+You also cannot roll back an environment to a specific `buildId` that was never deployed to that environment — even with `deployhub rollback <buildId> --env <name>`, DeployHub will refuse if that buildId doesn't appear in that environment's own history. This guarantees every rollback returns an environment to a build that was genuinely running there before, never a build it never actually had.
+
+Storage layout (per project):
+
+```text
+{project}/builds/{buildId}/artifact.zip          # immutable build blobs (shared)
+{project}/envs/{env}/history.json                # that env's deploy history only
+{project}/envs/{env}/latest/artifact.zip         # last successful deploy to that env
+{project}/history.json                           # build catalog / legacy default-env history
+```
+
 For CI-triggered rollback, see [CI rollback](#ci-rollback-deployhub-rollbackyml).
 
 ---
 
+## Multi-environment deployments
+
+DeployHub supports multiple named environments in one project (e.g. `development` + `production`), each with its own method, secrets, trigger, and deploy history.
+
+### Commands
+
+```bash
+deployhub env list
+deployhub env add staging --method ssh          # or omit --method for interactive prompts
+deployhub env enable staging
+deployhub env disable staging
+deployhub env remove staging
+
+deployhub deploy --env staging
+deployhub deploy --env all                      # every enabled environment
+
+deployhub rollback --env production
+deployhub rollback 1.2.3-abc1234 --env staging
+deployhub rollback --env all                    # each env rolls back independently
+
+deployhub sync-workflows                        # regenerate deployhub.yml + deployhub-rollback.yml
+```
+
+### Trigger defaults
+
+| Situation | Default `trigger` |
+|-----------|-------------------|
+| Single-environment `init` | `"push"` — auto-deploy on push to main (original DeployHub behavior) |
+| First / grandfathered env in multi-env `init` | `"push"` |
+| Additional environments | `"manual"` — deploy only via Actions → Run workflow or `deployhub deploy --env` |
+
+Multi-env `init` prints a reminder naming which environments are push vs manual and how to edit `deployhub.config.json` (`environments.<name>.trigger`) if you want a different mix. After changing triggers or envs, run `deployhub sync-workflows` and commit the regenerated YAML.
+
+On a GitHub Actions **push**, `deployhub build` only auto-deploys environments with `trigger: "push"`. Environments with `trigger: "manual"` are never deployed on push — even though their secrets are present in the job for dispatch/rollback.
+
+### Secret naming
+
+| Environment | GitHub Secret / env var style |
+|-------------|-------------------------------|
+| Grandfathered / original (`unprefixedSecretEnvironment`) | Unprefixed: `SSH_HOST`, `SSH_KEY`, `DOCKER_IMAGE_NAME`, … |
+| Every additional environment | Prefixed: `PRODUCTION_SSH_HOST`, `STAGING_DOCKER_IMAGE_NAME`, … |
+
+Build and Dispatch workflow steps share the **same** secret set (all enabled environments). Trigger only controls which environments are deployed on push — not which secrets are injected.
+
+---
+
 ## Walkthrough: Storage only
 
 Use this when you want **versioned build artifacts in the cloud** but deploy manually (or add deployment later).
@@ -555,6 +618,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.
@@ -1031,7 +1096,7 @@ Run `deployhub doctor` after any config change.
 | `deployhub clean` | Remove old local artifacts |
 | `deployhub update` | Check for CLI updates |
 
-**Tests:** `npm test` — currently **270 passing** across the Jest suites.
+**Tests:** `npm test` — currently **320 passing** across the Jest suites.
 
 ## GitHub Secrets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "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/github-actions.js

@@ -1,8 +1,10 @@
 import fs from 'fs-extra';
 import path from 'path';
 import yaml from 'js-yaml';
+import chalk from 'chalk';
+import semver from 'semver';
 import { fileURLToPath } from 'url';
-import { getWorkflowHeaderComment } from './author.js';
+import { getWorkflowHeaderComment, getDeployHubVersion } from './author.js';
 import {
   generateDeploymentEnvSection,
   getDeploymentWorkflowSecretKeys,
@@ -144,28 +146,63 @@ export function getCliInstallSpec(cliSource) {
  * Version/range suitable as a package.json dependency VALUE for this CLI
  * (key is already NPM_PACKAGE — do not embed the package name again).
  *
+ * Reads the running CLI's package version dynamically. Never hardcode a
+ * specific semver fallback (e.g. "1.0.6") — if resolution fails, use "latest".
+ *
  * @param {string} [cliSource]
+ * @param {{ packageJsonPath?: string }} [opts] — test override: read this package.json
  * @returns {string}
  */
-export function getCliPackageJsonDependencyVersion(cliSource) {
+export function getCliPackageJsonDependencyVersion(cliSource, opts = {}) {
   const normalized = normalizeCliSource(cliSource);
   if (normalized === DEFAULT_NPM_CLI_SOURCE) {
+    const resolved = readCliPackageVersion(opts.packageJsonPath);
+    if (resolved) return `^${resolved}`;
+    return 'latest';
+  }
+  // github: / file: specs are valid package.json dependency values as-is
+  return getCliInstallSpec(cliSource);
+}
+
+/**
+ * Resolve the running CLI package version for dependency ranges.
+ * Order: explicit package.json path (tests) → package.json next to this
+ * package root → getDeployHubVersion() (covers __DEPLOYHUB_VERSION__ in
+ * pkg binaries). Never returns a hardcoded stale semver.
+ *
+ * @param {string} [packageJsonPath]
+ * @returns {string|null}
+ */
+function readCliPackageVersion(packageJsonPath) {
+  const candidates = [];
+  if (packageJsonPath) {
+    candidates.push(packageJsonPath);
+  } else {
+    candidates.push(
+      path.join(path.dirname(fileURLToPath(import.meta.url)), '../../package.json')
+    );
+  }
+
+  for (const pkgPath of candidates) {
     try {
-      const pkgPath = path.join(
-        path.dirname(fileURLToPath(import.meta.url)),
-        '../../package.json'
-      );
       const pkg = fs.readJsonSync(pkgPath);
-      if (typeof pkg.version === 'string' && pkg.version.trim()) {
-        return `^${pkg.version.trim()}`;
+      if (typeof pkg.version === 'string' && /^\d+\.\d+\.\d+/.test(pkg.version.trim())) {
+        return pkg.version.trim();
       }
     } catch {
-      // fall through
+      // try next
     }
-    return 'latest';
   }
-  // github: / file: specs are valid package.json dependency values as-is
-  return getCliInstallSpec(cliSource);
+
+  try {
+    const v = getDeployHubVersion();
+    if (typeof v === 'string' && /^\d+\.\d+\.\d+/.test(v.trim())) {
+      return v.trim();
+    }
+  } catch {
+    // ignore
+  }
+  return null;
 }
 
 /**
@@ -956,20 +993,133 @@ export async function getWorkflowDriftDoctorChecks(cwd, config) {
   return checks;
 }
 
+/**
+ * Extract a comparable base semver from a package.json dependency value
+ * (`^2.0.19`, `~2.0.19`, `2.0.19`). Returns null for `latest`, git URLs,
+ * or anything that is not a valid semver range/version.
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function parseDependencyBaseVersion(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (
+    trimmed === 'latest' ||
+    trimmed.startsWith('github:') ||
+    trimmed.startsWith('file:') ||
+    trimmed.startsWith('git+') ||
+    trimmed.includes('://')
+  ) {
+    return null;
+  }
+  const coerced = semver.coerce(trimmed);
+  return coerced ? coerced.version : null;
+}
+
+/**
+ * Decide whether to write a new DeployHub dependency version into a project
+ * package.json. Never allows a lower semver to overwrite a higher existing pin.
+ *
+ * @param {string|null|undefined} existingValue
+ * @param {string} proposedValue
+ * @returns {{ write: boolean, value: string, warning: string|null }}
+ */
+export function decideDeployhubDependencyVersionWrite(existingValue, proposedValue) {
+  const proposed = typeof proposedValue === 'string' ? proposedValue.trim() : '';
+  if (!proposed) {
+    return {
+      write: false,
+      value: typeof existingValue === 'string' ? existingValue : '',
+      warning:
+        '⚠ Skipped updating package.json dependency version: resolved DeployHub version was empty.',
+    };
+  }
+
+  if (existingValue == null || existingValue === '') {
+    return { write: true, value: proposed, warning: null };
+  }
+
+  const existingBase = parseDependencyBaseVersion(existingValue);
+  const proposedBase = parseDependencyBaseVersion(proposed);
+
+  if (!existingBase || !proposedBase) {
+    return {
+      write: false,
+      value: String(existingValue),
+      warning:
+        `⚠ Skipped updating package.json dependency version: could not compare ` +
+        `existing "${existingValue}" with resolved "${proposed}" as semver. ` +
+        `Leaving the existing entry untouched.`,
+    };
+  }
+
+  if (semver.lt(proposedBase, existingBase)) {
+    return {
+      write: false,
+      value: String(existingValue),
+      warning:
+        `⚠ Skipped updating package.json dependency version: the currently\n` +
+        `  resolved DeployHub CLI version (${proposedBase}) is lower than what's already\n` +
+        `  pinned (${existingBase}). Keeping the existing, newer version to avoid a\n` +
+        `  downgrade. If this is unexpected, check that you're running the\n` +
+        `  intended CLI version (which deployhub / npm ls -g @akash-chowdhury-24/deployhub).`,
+    };
+  }
+
+  // existing <= proposed → write (first-time already handled; upgrade or same)
+  return { write: true, value: proposed, warning: null };
+}
+
 /**
  * @param {string} cliSource
  * @param {string} [cwd]
+ * @param {{ packageJsonPath?: string, proposedVersion?: string }} [opts]
+ *        `proposedVersion` / `packageJsonPath` are for tests (mock resolved CLI version).
  */
-export async function addDeployhubToPackageJson(cliSource, cwd = process.cwd()) {
+export async function addDeployhubToPackageJson(cliSource, cwd = process.cwd(), opts = {}) {
   const pkgPath = path.join(cwd, 'package.json');
   if (!(await fs.pathExists(pkgPath))) return;
 
   const pkg = await fs.readJson(pkgPath);
   pkg.devDependencies = pkg.devDependencies || {};
+
+  const existingDev = pkg.devDependencies[NPM_PACKAGE];
+  const existingProd =
+    pkg.dependencies && typeof pkg.dependencies === 'object'
+      ? pkg.dependencies[NPM_PACKAGE]
+      : undefined;
+  const existing =
+    existingDev != null && existingDev !== ''
+      ? existingDev
+      : existingProd != null && existingProd !== ''
+        ? existingProd
+        : null;
+
   // package.json value must be a semver range / "latest" / git URL — never "name@version"
   // (that form is only for `npm install <spec>` via getCliInstallSpec).
-  pkg.devDependencies[NPM_PACKAGE] = getCliPackageJsonDependencyVersion(cliSource);
+  const proposed =
+    typeof opts.proposedVersion === 'string' && opts.proposedVersion.trim()
+      ? opts.proposedVersion.trim()
+      : getCliPackageJsonDependencyVersion(cliSource, opts);
+
+  const decision = decideDeployhubDependencyVersionWrite(existing, proposed);
+  if (decision.warning) {
+    console.log(chalk.yellow(decision.warning));
+  }
+  if (decision.write) {
+    // Prefer updating whichever field already held the entry; default to devDependencies.
+    if (existingProd != null && existingProd !== '' && (existingDev == null || existingDev === '')) {
+      pkg.dependencies = pkg.dependencies || {};
+      pkg.dependencies[NPM_PACKAGE] = decision.value;
+    } else {
+      pkg.devDependencies[NPM_PACKAGE] = decision.value;
+    }
+  }
+
   delete pkg.devDependencies.deployhub;
+  if (pkg.dependencies) delete pkg.dependencies.deployhub;
   pkg.scripts = pkg.scripts || {};
   pkg.scripts['deployhub:build'] = 'deployhub build';
   await fs.writeJson(pkgPath, pkg, { spaces: 2 });

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,
+};