@akash-chowdhury-24/deployhub 2.0.17 → 2.0.19

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).
@@ -909,6 +972,8 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 - Cluster connectivity test during `init`
 - On deploy: registry login → reuse or build image → push (unique tag unless `DOCKER_IMAGE_TAG` is set) → ensure namespace exists (prompt locally / auto-create in CI) → `kubectl apply` → `kubectl set image` with the full resolved image ref → `kubectl rollout restart` when that ref is unchanged so pods pick up a new digest
 
+> **Limitation — multiple Kubernetes clusters:** A generated workflow writes **one** kubeconfig file per job. Multiple Kubernetes environments that target **different clusters** in the same workflow run are not yet fully supported (follow-up). Same-cluster multi-namespace / multi-env is fine.
+
 **After `init`:**
 1. Verify context: `kubectl config get-contexts`
 2. Copy `.env.example` → `.env`; set `DOCKER_IMAGE_NAME`, registry username/token, and (for local deploys) `KUBECONFIG` / `KUBE_CONTEXT` / `KUBE_NAMESPACE` as needed
@@ -1029,7 +1094,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.17",
+  "version": "2.0.19",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/core/environments.js

@@ -161,8 +161,13 @@ export function resolveDefaultEnvironmentName(config) {
 }
 
 /**
- * Enabled environment names (for `--env all` and pipeline defaults).
+ * Enabled environment names — **the single source of truth** for “which envs
+ * apply” across CLI, pipeline gating, workflow secret injection, and dropdowns.
+ * Do not add a parallel helper that re-filters `environments` by `enabled`
+ * (that shape caused Build/Dispatch secret asymmetry when lists drifted).
+ *
  * Falls back to legacy `deploy[]` when present and environments lack `enabled`.
+ * Used for `--env all` and pipeline defaults.
  *
  * @param {Record<string, unknown>} config
  * @returns {string[]}

package/src/core/stages.js

@@ -24,11 +24,14 @@ import {
  * - GitHub Actions push: every enabled env with trigger "push".
  * - workflow_dispatch: none here (explicit deploy step handles --env).
  *
+ * Separate from workflow secret injection: CI may inject secrets for all
+ * enabled envs, but only `trigger: "push"` envs are deployed on push.
+ *
  * @param {import('./config.js').DeployHubConfig} config
  * @param {Record<string, string|undefined>} [env]
  * @returns {string[]}
  */
-function pipelineDeployTargets(config, env = process.env) {
+export function pipelineDeployTargets(config, env = process.env) {
   if (env.GITHUB_EVENT_NAME === 'workflow_dispatch') {
     return [];
   }

package/src/storage/providers/local.js

@@ -5,7 +5,11 @@ import path from 'path';
  * @param {Record<string, string>} [_env]
  */
 export function createLocalProvider(_env = process.env) {
-  const baseDir = path.join(process.cwd(), '.deployhub-storage');
+  // Tests / isolated runs may pin storage under a temp dir without process.chdir
+  // (chdir races when Jest runs suites in parallel).
+  const baseDir = _env.DEPLOYHUB_LOCAL_STORAGE_DIR
+    ? path.resolve(_env.DEPLOYHUB_LOCAL_STORAGE_DIR)
+    : path.join(process.cwd(), '.deployhub-storage');
 
   /**
    * @param {string} localPath

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,
@@ -14,7 +16,11 @@ import {
   envUsesPrefixedSecrets,
   DEPLOYMENT_ENV_KEYS,
 } from '../deployment/deployment-env.js';
-import { getEnvMethod, getEnvTrigger, isEnvEnabled } from '../core/environments.js';
+import {
+  getEnvMethod,
+  getEnabledEnvironmentNames,
+  isEnvEnabled,
+} from '../core/environments.js';
 
 /** @typedef {'aws'|'azure'|'gcp'|'gdrive'|'dropbox'|'local'|'ftp'|'ssh'} ProviderEnvKey */
 
@@ -140,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;
 }
 
 /**
@@ -259,9 +300,41 @@ function hasKubernetesDeploy(deployEnvironments, environments) {
 }
 
 /**
+ * Secret name for the Configure-kubeconfig setup step.
+ * Must match the env that actually uses kubernetes — when the only k8s env is
+ * non-grandfathered (e.g. production), that is PRODUCTION_KUBECONFIG, not the
+ * unprefixed KUBECONFIG (which would never be injected and leave the file empty).
+ *
+ * LIMITATION (follow-up): GitHub Actions writes exactly ONE kubeconfig file per
+ * job. Multiple Kubernetes environments that target DIFFERENT clusters in the
+ * same workflow run are not yet fully supported — only the first/grandfathered
+ * k8s env's secret is used for the setup step. Track as a product follow-up
+ * before advertising multi-cluster multi-env CI.
+ *
+ * @param {string[]} deployEnvironments
+ * @param {Record<string, { type?: string, method?: string }>} environments
+ * @param {import('../core/config.js').DeployHubConfig|null} config
+ * @returns {string}
+ */
+function resolveKubeconfigWorkflowSecretName(deployEnvironments, environments, config) {
+  const cfg = { ...(config || {}), environments };
+  const k8sNames = deployEnvironments.filter(
+    (n) => getEnvMethod(environments[n]) === 'kubernetes'
+  );
+  if (k8sNames.length === 0) return 'KUBECONFIG';
+  const unprefixed = k8sNames.find((n) => !envUsesPrefixedSecrets(n, cfg));
+  const chosen = unprefixed || k8sNames[0];
+  return envUsesPrefixedSecrets(chosen, cfg)
+    ? prefixSecretKey(chosen, 'KUBECONFIG')
+    : 'KUBECONFIG';
+}
+
+/**
+ * @param {string} [kubeconfigSecretName]
  * @returns {string}
  */
-function getKubernetesSetupSteps() {
+function getKubernetesSetupSteps(kubeconfigSecretName = 'KUBECONFIG') {
+  // One kubeconfig file per job — see resolveKubeconfigWorkflowSecretName LIMITATION.
   return `      - name: Setup kubectl
         uses: azure/setup-kubectl@v4
         with:
@@ -269,7 +342,7 @@ function getKubernetesSetupSteps() {
 
       - name: Configure kubeconfig
         env:
-          KUBECONFIG_SECRET: \${{ secrets.KUBECONFIG }}
+          KUBECONFIG_SECRET: \${{ secrets.${kubeconfigSecretName} }}
         run: |
           mkdir -p "$GITHUB_WORKSPACE/.kube"
           if echo "$KUBECONFIG_SECRET" | base64 -d > "$GITHUB_WORKSPACE/.kube/config" 2>/dev/null; then
@@ -316,27 +389,6 @@ function upsertWorkflowEnvLine(envVars, lhs, valueExpr) {
   envVars.add(`${linePrefix}${valueExpr}`);
 }
 
-/**
- * Enabled environment names from the live `environments` map (preferred over
- * a possibly-stale `deploy[]` argument passed into workflow generators).
- * @param {Record<string, { type?: string, method?: string }>} environments
- * @returns {string[]}
- */
-function listEnabledEnvironmentNames(environments) {
-  return Object.keys(environments || {}).filter((n) => isEnvEnabled(environments[n]));
-}
-
-/**
- * Push-triggered enabled envs — same set `pipelineDeployTargets` deploys in GHA.
- * @param {Record<string, { type?: string, method?: string }>} environments
- * @returns {string[]}
- */
-function listPushEnvironmentNames(environments) {
-  return listEnabledEnvironmentNames(environments).filter(
-    (n) => getEnvTrigger(environments[n]) === 'push'
-  );
-}
-
 /**
  * Shared env entries for deploy and rollback workflows (same secret resolution).
  * Multi-env: each environment contributes its own CI secret names (grandfathered
@@ -400,9 +452,8 @@ export function buildWorkflowEnvEntries(
  * @returns {string}
  */
 function formatEnvironmentChoiceOptions(environments) {
-  const names = Object.keys(environments || {}).filter((n) =>
-    isEnvEnabled(environments[n])
-  );
+  // Single source of truth: getEnabledEnvironmentNames (do not re-filter here).
+  const names = getEnabledEnvironmentNames({ environments });
   const options = [...names, 'all'];
   return options.map((n) => `          - ${n}`).join('\n');
 }
@@ -457,11 +508,10 @@ export function generateWorkflowYaml(
   config = null
 ) {
   const envNames = Object.keys(environments || {});
-  // Secret injection must follow live environments (same as pipelineDeployTargets),
-  // not a possibly-stale deploy[] argument — otherwise push-deployed envs missing
-  // from deploy[] get no secrets in the job env block.
-  const enabledEnvs = listEnabledEnvironmentNames(environments);
-  const pushEnvs = listPushEnvironmentNames(environments);
+  // Secret injection uses ALL enabled environments (not push-only / pipelineDeployTargets).
+  // Prefer live enabled names over a possibly-stale deploy[] argument so no enabled
+  // env is missing from the job env block. Canonical helper: getEnabledEnvironmentNames.
+  const enabledEnvs = getEnabledEnvironmentNames({ ...(config || {}), environments });
   const allDeployNames =
     enabledEnvs.length > 0
       ? enabledEnvs
@@ -469,28 +519,21 @@ export function generateWorkflowYaml(
         ? deployEnvironments
         : envNames;
 
-  // Build step: union of secrets for every push-triggered env (build deploys all of them).
-  const buildSecretEnvs =
-    pushEnvs.length > 0 ? pushEnvs : allDeployNames.slice(0, 1);
-
-  // workflow_dispatch step: union for ALL enabled envs (dropdown can pick any / all).
-  const dispatchSecretEnvs = allDeployNames;
+  // CRITICAL: Build and Deploy (workflow_dispatch) MUST share the same secret union —
+  // every enabled environment. Filtering Build to push-only caused a live regression:
+  // Dispatch correctly got PRODUCTION_* while Build did not, so `deployhub build`'s
+  // push deploy stage failed on production with a missing SSH key. Trigger only
+  // controls which envs the CLI deploys; it must not control which secrets are injected.
+  const secretEnvs =
+    allDeployNames.length > 0 ? allDeployNames : envNames.slice(0, 1);
 
-  const buildEnvVars = buildWorkflowEnvEntries(
-    storageProviders,
-    buildSecretEnvs,
-    environments,
-    config
-  );
-  const buildEnvBlock = formatWorkflowEnvBlock(buildEnvVars);
-
-  const dispatchEnvVars = buildWorkflowEnvEntries(
+  const envVars = buildWorkflowEnvEntries(
     storageProviders,
-    dispatchSecretEnvs,
+    secretEnvs,
     environments,
     config
   );
-  const dispatchEnvBlock = formatWorkflowEnvBlock(dispatchEnvVars);
+  const envBlock = formatWorkflowEnvBlock(envVars);
 
   const installSpec = getCliInstallSpec(cliSource);
   const backendSteps = getBackendSetupSteps(config);
@@ -498,8 +541,13 @@ export function generateWorkflowYaml(
   const githubGitConfigStep = isGithubCliSource(cliSource)
     ? `${getGithubGitConfigStep()}\n`
     : '';
+  const kubeconfigSecret = resolveKubeconfigWorkflowSecretName(
+    allDeployNames,
+    environments,
+    config
+  );
   const kubernetesSteps = hasKubernetesDeploy(allDeployNames, environments)
-    ? `${getKubernetesSetupSteps()}\n`
+    ? `${getKubernetesSetupSteps(kubeconfigSecret)}\n`
     : '';
 
   const projectType = config?.projectType || 'frontend';
@@ -527,7 +575,7 @@ ${envChoiceOptions}
     ? `      - name: Deploy (workflow_dispatch)
         if: github.event_name == 'workflow_dispatch'
         env:
-${dispatchEnvBlock}
+${envBlock}
         run: |
           ENV_INPUT="\${{ inputs.environment }}"
           if [ -z "$ENV_INPUT" ] || [ "$ENV_INPUT" = "all" ]; then
@@ -557,7 +605,7 @@ ${kubernetesSteps}${githubGitConfigStep}      - name: Install project dependenci
       - name: Build (and auto-deploy push-triggered envs)
         run: ${getCliBuildCommand()}
         env:
-${buildEnvBlock}
+${envBlock}
 ${manualDeployStep}`;
 
   return workflow;
@@ -589,7 +637,7 @@ export function generateRollbackWorkflowYaml(
   config = null
 ) {
   const envNames = Object.keys(environments || {});
-  const enabledEnvs = listEnabledEnvironmentNames(environments);
+  const enabledEnvs = getEnabledEnvironmentNames({ ...(config || {}), environments });
   const allDeployNames =
     enabledEnvs.length > 0
       ? enabledEnvs
@@ -609,8 +657,13 @@ export function generateRollbackWorkflowYaml(
   const githubGitConfigStep = isGithubCliSource(cliSource)
     ? `${getGithubGitConfigStep()}\n`
     : '';
+  const kubeconfigSecret = resolveKubeconfigWorkflowSecretName(
+    allDeployNames,
+    environments,
+    config
+  );
   const kubernetesSteps = hasKubernetesDeploy(allDeployNames, environments)
-    ? `${getKubernetesSetupSteps()}\n`
+    ? `${getKubernetesSetupSteps(kubeconfigSecret)}\n`
     : '';
 
   const rollbackCmd = getCliRollbackCommand();
@@ -790,13 +843,14 @@ export function expectedWorkflowSecretKeysFromConfig(config, kind = 'rollback')
   /** @type {string[]} */
   let targets;
   if (kind === 'deploy') {
-    const pushEnvs = listPushEnvironmentNames(environments);
-    const enabled = listEnabledEnvironmentNames(environments);
-    // Deploy workflow Build step uses push envs; doctor also flags dispatch-needed
-    // secrets by using the broader enabled set via kind === 'rollback' / checklist.
-    targets = pushEnvs.length > 0 ? pushEnvs : enabled.slice(0, 1);
+    const enabled = getEnabledEnvironmentNames({ ...config, environments });
+    // Same union as generateWorkflowYaml Build + dispatch steps (all enabled).
+    targets = enabled.length > 0 ? enabled : allNames.slice(0, 1);
   } else {
-    targets = allNames.length > 0 ? listEnabledEnvironmentNames(environments) : allNames;
+    targets =
+      allNames.length > 0
+        ? getEnabledEnvironmentNames({ ...config, environments })
+        : allNames;
     if (targets.length === 0) targets = allNames;
   }
 
@@ -851,7 +905,7 @@ export function detectWorkflowConfigDrift(yamlText, config, filename = DEPLOY_WO
     return { drifted: false, missingEnvs, missingSecrets, summary: '' };
   }
 
-  const envNames = listEnabledEnvironmentNames(config.environments || {});
+  const envNames = getEnabledEnvironmentNames(config);
   const root = /** @type {Record<string, any>} */ (parsed);
   const options = root?.on?.workflow_dispatch?.inputs?.environment?.options;
 
@@ -939,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 });