@akash-chowdhury-24/deployhub 2.0.13 → 2.0.15

package/src/deployment/providers/ec2.js

@@ -20,7 +20,8 @@ export function createEc2Provider(config, envName, env = process.env) {
 
     if (!instanceId) {
       throw new Error(
-        'EC2 host unknown. Set SSH_HOST to your instance public IP, or set EC2_INSTANCE_ID with AWS credentials for auto lookup.'
+        'Could not resolve host via EC2 instance lookup, and no SSH_HOST was set — ' +
+          'provide SSH_HOST (instance public IP/DNS) or set EC2_INSTANCE_ID with AWS credentials for auto lookup.'
       );
     }
 
@@ -58,34 +59,54 @@ export function createEc2Provider(config, envName, env = process.env) {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(
-        `Could not resolve public IP for ${instanceId} — ${msg}. Set SSH_HOST manually or install/configure AWS CLI with ec2:DescribeInstances access.`
+        `Could not resolve host via EC2 instance lookup (${instanceId}): ${msg}. ` +
+          'Set SSH_HOST to the instance public IP/DNS, or fix AWS CLI credentials / ec2:DescribeInstances access.'
       );
     }
   }
 
-  const sshProvider = createSshProvider(config, envName, env);
-
-  async function connect() {
+  /**
+   * Resolve host (skipping cloud lookup when SSH_HOST/environment.host is set),
+   * then create an SSH provider that closes over the resolved host.
+   */
+  async function getSshProvider() {
     const host = await resolveHost();
+    if (!host) {
+      throw new Error(
+        'Could not resolve host via EC2 instance lookup, and no SSH_HOST was set — provide one or the other.'
+      );
+    }
     const environment = config.environments[envName];
-    if (environment && !environment.host) {
+    if (environment) {
       environment.host = host;
     }
-    if (!env.SSH_HOST) {
-      env.SSH_HOST = host;
-    }
-    return sshProvider.connect();
+    return createSshProvider(config, envName, { ...env, SSH_HOST: host });
   }
 
   return {
-    ...sshProvider,
-    connect,
-    deploy: sshProvider.deploy.bind(sshProvider),
-    rollback: sshProvider.rollback.bind(sshProvider),
-    healthCheck: sshProvider.healthCheck.bind(sshProvider),
-    testConnection: async () => {
-      const ssh = await connect();
-      ssh.dispose();
+    async connect() {
+      const ssh = await getSshProvider();
+      return ssh.connect();
+    },
+    async deploy(artifactDir, options) {
+      const ssh = await getSshProvider();
+      return ssh.deploy(artifactDir, options);
+    },
+    async rollback(artifactDir, meta) {
+      const ssh = await getSshProvider();
+      return ssh.rollback(artifactDir, meta);
+    },
+    async healthCheck() {
+      const ssh = await getSshProvider();
+      return ssh.healthCheck();
+    },
+    async testConnection() {
+      const ssh = await getSshProvider();
+      return ssh.testConnection();
+    },
+    async runRemoteCheck(command) {
+      const ssh = await getSshProvider();
+      return ssh.runRemoteCheck(command);
     },
   };
 }

package/src/deployment/providers/gcp-vm.js

@@ -21,7 +21,8 @@ export function createGcpVmProvider(config, envName, env = process.env) {
 
     if (!projectId || !zone || !instanceName) {
       throw new Error(
-        'GCP VM host unknown. Set SSH_HOST to your instance external IP, or set GCP_PROJECT_ID, GCP_ZONE, and GCP_INSTANCE_NAME for auto lookup.'
+        'Could not resolve host via GCP instance lookup, and no SSH_HOST was set — ' +
+          'provide SSH_HOST (instance external IP/DNS) or set GCP_PROJECT_ID, GCP_ZONE, and GCP_INSTANCE_NAME for auto lookup.'
       );
     }
 
@@ -59,34 +60,54 @@ export function createGcpVmProvider(config, envName, env = process.env) {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(
-        `Could not resolve external IP for ${instanceName} — ${msg}. Set SSH_HOST manually or run gcloud auth login and verify project/zone/instance name.`
+        `Could not resolve host via GCP instance lookup (${instanceName}): ${msg}. ` +
+          'Set SSH_HOST to the instance external IP/DNS, or run gcloud auth login and verify project/zone/instance name.'
       );
     }
   }
 
-  const sshProvider = createSshProvider(config, envName, env);
-
-  async function connect() {
+  /**
+   * Resolve host (skipping cloud lookup when SSH_HOST/environment.host is set),
+   * then create an SSH provider that closes over the resolved host.
+   */
+  async function getSshProvider() {
     const host = await resolveHost();
+    if (!host) {
+      throw new Error(
+        'Could not resolve host via GCP instance lookup, and no SSH_HOST was set — provide one or the other.'
+      );
+    }
     const environment = config.environments[envName];
-    if (environment && !environment.host) {
+    if (environment) {
       environment.host = host;
     }
-    if (!env.SSH_HOST) {
-      env.SSH_HOST = host;
-    }
-    return sshProvider.connect();
+    return createSshProvider(config, envName, { ...env, SSH_HOST: host });
   }
 
   return {
-    ...sshProvider,
-    connect,
-    deploy: sshProvider.deploy.bind(sshProvider),
-    rollback: sshProvider.rollback.bind(sshProvider),
-    healthCheck: sshProvider.healthCheck.bind(sshProvider),
-    testConnection: async () => {
-      const ssh = await connect();
-      ssh.dispose();
+    async connect() {
+      const ssh = await getSshProvider();
+      return ssh.connect();
+    },
+    async deploy(artifactDir, options) {
+      const ssh = await getSshProvider();
+      return ssh.deploy(artifactDir, options);
+    },
+    async rollback(artifactDir, meta) {
+      const ssh = await getSshProvider();
+      return ssh.rollback(artifactDir, meta);
+    },
+    async healthCheck() {
+      const ssh = await getSshProvider();
+      return ssh.healthCheck();
+    },
+    async testConnection() {
+      const ssh = await getSshProvider();
+      return ssh.testConnection();
+    },
+    async runRemoteCheck(command) {
+      const ssh = await getSshProvider();
+      return ssh.runRemoteCheck(command);
     },
   };
 }

package/src/deployment/providers/kubernetes.js

@@ -5,6 +5,7 @@ import os from 'os';
 import { createLogger } from '../../logger/index.js';
 import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
 import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
+import { resolveDockerImageRefForTag } from '../../utils/docker-image.js';
 import { ensureKubernetesNamespace } from '../../utils/kubernetes-namespace.js';
 import { syncKubernetesDeploymentImage } from '../../utils/kubernetes-deploy-image.js';
 
@@ -50,10 +51,24 @@ export function createKubernetesProvider(config, envName, env = process.env) {
 
   /**
    * @param {string} artifactDir
+   * @param {{ fullImage?: string, skipImageReuse?: boolean }} [options]
    */
-  async function deploy(artifactDir) {
+  async function deploy(artifactDir, options = {}) {
+    const imageRef = options.fullImage || imageOps.fullImage;
+    const isRollbackRedeploy = Boolean(options.skipImageReuse);
+
     log.info(`Deploying to Kubernetes (namespace: ${namespace}${context ? `, context: ${context}` : ''})...`);
 
+    // Rollback always rebuilds and must push — without registry creds the cluster
+    // cannot pull the new tag and would sit in ImagePullBackOff after a false success.
+    if (isRollbackRedeploy && !imageOps.hasRegistryCredentials()) {
+      throw new Error(
+        'Kubernetes rollback requires DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN ' +
+          `so the rebuilt image (${imageRef}) can be pushed for the cluster to pull. ` +
+          'Set those credentials and retry.'
+      );
+    }
+
     const manifestDir = artifactDir;
     const hasManifests =
       (await fs.pathExists(path.join(manifestDir, 'k8s'))) ||
@@ -65,8 +80,11 @@ export function createKubernetesProvider(config, envName, env = process.env) {
       );
     }
 
-    log.info(`Ensuring container image ${imageOps.fullImage} is built and pushed before apply...`);
-    const imageResult = await imageOps.ensureImageReadyForDeploy(artifactDir);
+    log.info(`Ensuring container image ${imageRef} is built and pushed before apply...`);
+    const imageResult = await imageOps.ensureImageReadyForDeploy(artifactDir, {
+      fullImage: options.fullImage,
+      skipImageReuse: options.skipImageReuse,
+    });
     if (imageResult.ranCompose) {
       log.warn(
         'docker compose was used — ensure the cluster can pull the resulting image from your registry.'
@@ -93,23 +111,60 @@ export function createKubernetesProvider(config, envName, env = process.env) {
     // If the live ref already equals fullImage, rollout restart so a new digest is pulled.
     await syncKubernetesDeploymentImage({
       deploymentName,
-      fullImage: imageOps.fullImage,
+      fullImage: imageRef,
       kubectlArgs,
       getKubectlEnv,
       log,
     });
 
+    // Rollback-only safety net: wait until pods are actually healthy (catches ImagePullBackOff).
+    if (isRollbackRedeploy) {
+      const timeout = '120s';
+      log.info(
+        `Waiting for deployment/${deploymentName} rollout to complete (timeout ${timeout})...`
+      );
+      try {
+        await execa(
+          'kubectl',
+          kubectlArgs([
+            'rollout',
+            'status',
+            `deployment/${deploymentName}`,
+            `--timeout=${timeout}`,
+          ]),
+          { stdio: 'inherit', env: getKubectlEnv() }
+        );
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `Kubernetes rollback failed: deployment/${deploymentName} did not become healthy within ${timeout}. ` +
+            `The cluster may be unable to pull ${imageRef} (ImagePullBackOff) or pods are failing. ${detail}`
+        );
+      }
+    }
+
     log.success('Kubernetes deployment complete');
   }
 
-  async function rollback(artifactDir) {
-    log.info('Rolling back Kubernetes deployment...');
-    await execa('kubectl', kubectlArgs(['rollout', 'undo', `deployment/${deploymentName}`]), {
-      stdio: 'inherit',
-      env: getKubectlEnv(),
-    }).catch(async () => {
-      log.warn('kubectl rollout undo failed — redeploying previous artifact instead');
-      await deploy(artifactDir);
+  /**
+   * Artifact-based rollback: restore buildId X's code and image (not cluster undo history).
+   * @param {string} artifactDir
+   * @param {{ buildId?: string, semver?: string, remoteKey?: string }} [meta]
+   */
+  async function rollback(artifactDir, meta = {}) {
+    if (!meta.buildId) {
+      throw new Error(
+        'Kubernetes rollback requires buildId from the restored artifact history entry'
+      );
+    }
+
+    const rollbackImage = resolveDockerImageRefForTag(config, env, meta.buildId).fullImage;
+    log.info(
+      `Rolling back Kubernetes to buildId=${meta.buildId} (image: ${rollbackImage})...`
+    );
+    await deploy(artifactDir, {
+      fullImage: rollbackImage,
+      skipImageReuse: true,
     });
   }
 

package/src/deployment/providers/ssh.js

@@ -405,7 +405,7 @@ export function createSshProvider(config, envName, env = process.env) {
     return result.code === 0 && result.stdout.trim() === 'yes';
   }
 
-  async function rollback(artifactDir) {
+  async function rollback(artifactDir, _meta) {
     await deploy(artifactDir);
   }
 

package/src/storage/index.js

@@ -20,6 +20,7 @@ import {
   parseArtifactHistory,
   prependHistoryEntry,
 } from '../utils/artifact-history.js';
+import { summarizeStorageError } from './storage-errors.js';
 
 /** @type {Record<string, (env?: Record<string, string>) => ReturnType<typeof createAwsProvider>>} */
 const PROVIDER_FACTORIES = {
@@ -59,28 +60,51 @@ function ensureBuildIdentity(config) {
 
 /**
  * Read history.json from the first provider that has it.
+ * Missing keys across all providers → { entries: [], source: null }.
+ * Auth / network / permission failures → thrown with a concise actionable message
+ * (not silently treated as "no history").
+ *
  * @param {string[]} providers
  * @param {string} project
- * @returns {Promise<import('../utils/artifact-history.js').ArtifactHistoryEntry[]>}
+ * @returns {Promise<{
+ *   entries: import('../utils/artifact-history.js').ArtifactHistoryEntry[],
+ *   source: string|null,
+ * }>}
  */
 export async function loadArtifactHistory(providers, project) {
+  if (!providers || providers.length === 0) {
+    return { entries: [], source: null };
+  }
+
   const key = historyRemoteKey(project);
   const tmp = path.join(os.tmpdir(), `deployhub-history-${Date.now()}.json`);
+
   try {
     for (const name of providers) {
-      const provider = getStorageProvider(name);
-      const exists = await provider.verify(key);
-      if (!exists) continue;
-      await provider.download(key, tmp);
-      const raw = await fs.readFile(tmp, 'utf8');
-      return parseArtifactHistory(raw);
+      try {
+        const provider = getStorageProvider(name);
+        const exists = await provider.verify(key);
+        if (!exists) continue;
+
+        await provider.download(key, tmp);
+        const raw = await fs.readFile(tmp, 'utf8');
+        return {
+          entries: parseArtifactHistory(raw),
+          source: name,
+        };
+      } catch (err) {
+        const reason = summarizeStorageError(err);
+        throw new Error(
+          `Could not check remote history via ${name}: ${reason} — ` +
+            'verify your storage credentials and configuration are correct.'
+        );
+      }
     }
-  } catch {
-    return [];
   } finally {
     await fs.remove(tmp).catch(() => {});
   }
-  return [];
+
+  return { entries: [], source: null };
 }
 
 /**

package/src/storage/providers/aws.js

@@ -2,6 +2,7 @@ import { S3Client, HeadBucketCommand, DeleteObjectCommand, GetObjectCommand } fr
 import { Upload } from '@aws-sdk/lib-storage';
 import fs from 'fs-extra';
 import path from 'path';
+import { isNotFoundStorageError } from '../storage-errors.js';
 
 /**
  * @param {Record<string, string>} env
@@ -65,6 +66,8 @@ export function createAwsProvider(env = process.env) {
 
   /**
    * @param {string} remoteKey
+   * @returns {Promise<boolean>} true if object exists; false if missing.
+   *   Auth / network / permission errors are rethrown (not treated as missing).
    */
   async function verify(remoteKey) {
     try {
@@ -72,8 +75,9 @@ export function createAwsProvider(env = process.env) {
         new GetObjectCommand({ Bucket: bucket, Key: remoteKey })
       );
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      if (isNotFoundStorageError(err)) return false;
+      throw err;
     }
   }
 

package/src/storage/providers/dropbox.js

@@ -1,6 +1,7 @@
 import { Dropbox } from 'dropbox';
 import fs from 'fs-extra';
 import path from 'path';
+import { isNotFoundStorageError } from '../storage-errors.js';
 
 export function createDropboxProvider(env = process.env) {
   const token = env.DROPBOX_ACCESS_TOKEN;
@@ -24,13 +25,18 @@ export function createDropboxProvider(env = process.env) {
     await fs.writeFile(localPath, fileBlob);
   }
 
+  /**
+   * @param {string} remoteKey
+   * @returns {Promise<boolean>}
+   */
   async function verify(remoteKey) {
     const key = remoteKey.startsWith('/') ? remoteKey : `/${remoteKey}`;
     try {
       await dbx.filesGetMetadata({ path: key });
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      if (isNotFoundStorageError(err)) return false;
+      throw err;
     }
   }
 

package/src/storage/providers/ftp.js

@@ -1,6 +1,7 @@
 import { Client } from 'basic-ftp';
 import fs from 'fs-extra';
 import path from 'path';
+import { isNotFoundStorageError } from '../storage-errors.js';
 
 export function createFtpProvider(env = process.env) {
   const host = env.FTP_HOST;
@@ -38,6 +39,10 @@ export function createFtpProvider(env = process.env) {
     });
   }
 
+  /**
+   * @param {string} remoteKey
+   * @returns {Promise<boolean>}
+   */
   async function verify(remoteKey) {
     const remotePath = `${basePath}/${remoteKey}`;
     try {
@@ -45,8 +50,9 @@ export function createFtpProvider(env = process.env) {
         await client.size(remotePath);
       });
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      if (isNotFoundStorageError(err)) return false;
+      throw err;
     }
   }
 

package/src/storage/storage-errors.js

@@ -0,0 +1,106 @@
+/**
+ * Shared helpers for storage provider errors (history load, verify, etc.).
+ */
+
+/**
+ * Concise, actionable one-line reason — no SDK stack dumps.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function summarizeStorageError(err) {
+  if (!err) return 'unknown error';
+
+  if (typeof err === 'string') {
+    return truncateReason(err);
+  }
+
+  const e = /** @type {Record<string, unknown>} */ (err);
+  const name = typeof e.name === 'string' ? e.name : '';
+  const code =
+    typeof e.Code === 'string'
+      ? e.Code
+      : typeof e.code === 'string'
+        ? e.code
+        : '';
+  const message =
+    err instanceof Error
+      ? err.message
+      : typeof e.message === 'string'
+        ? e.message
+        : String(err);
+
+  const firstLine = message.split(/\r?\n/)[0].trim();
+
+  // Prefer a short "AccessDenied: ..." style when the SDK exposes a name/code.
+  const label = [name, code].find(
+    (v) => v && v !== 'Error' && !firstLine.includes(v)
+  );
+  const combined = label ? `${label}: ${firstLine}` : firstLine;
+  return truncateReason(combined || 'unknown error');
+}
+
+/**
+ * @param {string} text
+ */
+function truncateReason(text) {
+  const cleaned = text.replace(/\s+/g, ' ').trim();
+  if (cleaned.length <= 200) return cleaned;
+  return `${cleaned.slice(0, 197)}...`;
+}
+
+/**
+ * True when an error almost certainly means the object/key is missing
+ * (as opposed to auth, network, or permission failures).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isNotFoundStorageError(err) {
+  if (!err || typeof err !== 'object') return false;
+  const e = /** @type {Record<string, unknown>} */ (err);
+  const status =
+    (e.$metadata &&
+      typeof e.$metadata === 'object' &&
+      /** @type {{ httpStatusCode?: number }} */ (e.$metadata).httpStatusCode) ||
+    (typeof e.statusCode === 'number' ? e.statusCode : undefined) ||
+    (typeof e.status === 'number' ? e.status : undefined);
+
+  const name = String(e.name || e.Code || e.code || '');
+  const msg = String(e.message || '').toLowerCase();
+  const blob = `${name} ${msg}`;
+
+  // Auth / permission / credential failures are never "not found"
+  if (
+    /\b(accessdenied|access denied|invalidaccesskey|forbidden|unauthorized|credentials|signaturedoesnotmatch|expiredtoken)\b/i.test(
+      blob
+    )
+  ) {
+    return false;
+  }
+
+  if (status === 403 || status === 401) return false;
+
+  if (status === 404) return true;
+
+  if (/^(NoSuchKey|NotFound|NotFoundError|ENOENT)$/i.test(name)) return true;
+
+  if (
+    /\b(nosuchkey|not\s*found|no such file|path\/not_found)\b/i.test(msg) ||
+    /\bthe specified key does not exist\b/i.test(msg)
+  ) {
+    return true;
+  }
+
+  // Dropbox often uses 409 with path/not_found
+  if (status === 409 && /not_found/i.test(msg + name + JSON.stringify(e.error || ''))) {
+    return true;
+  }
+
+  // FTP / classic responses
+  if (/\b550\b/.test(msg) && /not found|no such|failed to open/i.test(msg)) {
+    return true;
+  }
+
+  return false;
+}
+
+export default { summarizeStorageError, isNotFoundStorageError };