@akash-chowdhury-24/deployhub 2.0.13 → 2.0.14

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

package/src/utils/docker-image-deploy.js

@@ -10,6 +10,7 @@ import {
   generateSpringRuntimeDockerfile,
   isFrontendStaticFramework,
   isInterpretedBackendFramework,
+  replaceDockerImageTag,
   resolveDockerImageRef,
   EXPLICIT_IMAGE_TAG_WARNING,
 } from './docker-image.js';
@@ -67,8 +68,9 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
   /**
    * Push only when registry credentials are configured. Avoids a noisy failed
    * push to Docker Hub for local-only image names.
+   * @param {string} [imageRef]
    */
-  async function maybePushImage() {
+  async function maybePushImage(imageRef = fullImage) {
     if (!hasRegistryCredentials()) {
       log.info(
         'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
@@ -76,12 +78,12 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
       return;
     }
 
-    log.info(`Pushing ${fullImage} to registry...`);
-    await execa('docker', ['push', fullImage], {
+    log.info(`Pushing ${imageRef} to registry...`);
+    await execa('docker', ['push', imageRef], {
       stdio: 'inherit',
       env: getDockerEnv(),
     });
-    log.success(`Pushed ${fullImage}`);
+    log.success(`Pushed ${imageRef}`);
   }
 
   /**
@@ -102,21 +104,22 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
   /**
    * Prefer the image already built during the pipeline `docker` stage.
    * Retag when the pipeline used `:latest` and deploy needs a version tag.
+   * @param {string} [imageRef]
    */
-  async function ensureImageFromPipeline() {
-    if (await imageExistsLocally(fullImage)) {
-      log.info(`Reusing existing image ${fullImage}`);
+  async function ensureImageFromPipeline(imageRef = fullImage) {
+    if (await imageExistsLocally(imageRef)) {
+      log.info(`Reusing existing image ${imageRef}`);
       return true;
     }
 
     const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
-      (ref) => ref !== fullImage
+      (ref) => ref !== imageRef
     );
 
     for (const candidate of candidates) {
       if (!(await imageExistsLocally(candidate))) continue;
-      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
-      await execa('docker', ['tag', candidate, fullImage], {
+      log.info(`Re-tagging pipeline image ${candidate} → ${imageRef}`);
+      await execa('docker', ['tag', candidate, imageRef], {
         stdio: 'inherit',
         env: getDockerEnv(),
       });
@@ -211,12 +214,13 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
 
   /**
    * @param {string} artifactDir
+   * @param {string} [imageRef]
    */
-  async function buildFromArtifactContents(artifactDir) {
+  async function buildFromArtifactContents(artifactDir, imageRef = fullImage) {
     const zipPath = path.join(artifactDir, 'artifact.zip');
     if (!(await fs.pathExists(zipPath))) {
       throw new Error(
-        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
+        `No local image found for ${imageRef} and no artifact.zip to build from. ` +
           'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
       );
     }
@@ -281,7 +285,7 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
         await prepareBackendBuildContext(buildContext, metadata, framework, port);
       }
 
-      await execa('docker', ['build', '-t', fullImage, '.'], {
+      await execa('docker', ['build', '-t', imageRef, '.'], {
         cwd: buildContext,
         stdio: 'inherit',
         env: getDockerEnv(),
@@ -295,36 +299,55 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
   /**
    * Ensure a deployable image exists locally, then push when credentials are set.
    * @param {string} artifactDir
-   * @param {{ skipPush?: boolean }} [options]
+   * @param {{
+   *   skipPush?: boolean,
+   *   fullImage?: string,
+   *   skipImageReuse?: boolean,
+   * }} [options]
    */
   async function ensureImageReadyForDeploy(artifactDir, options = {}) {
+    const imageRef = options.fullImage || fullImage;
+    const latestRef = options.fullImage
+      ? replaceDockerImageTag(options.fullImage, 'latest')
+      : latestImage;
+    const lastSlash = imageRef.lastIndexOf('/');
+    const lastColon = imageRef.lastIndexOf(':');
+    const effectiveTag =
+      lastColon > lastSlash ? imageRef.slice(lastColon + 1) : 'latest';
+
     await dockerLogin();
 
-    const reused = await ensureImageFromPipeline();
+    let reused = false;
+    if (!options.skipImageReuse) {
+      reused = await ensureImageFromPipeline(imageRef);
+    } else {
+      log.info(`Skipping local image reuse — rebuilding ${imageRef} from artifact`);
+    }
+
     let ranCompose = false;
 
     if (!reused) {
-      const result = await buildFromArtifactContents(artifactDir);
+      const result = await buildFromArtifactContents(artifactDir, imageRef);
       ranCompose = Boolean(result?.ranCompose);
     }
 
     if (ranCompose) {
-      return { ranCompose: true };
+      return { ranCompose: true, fullImage: imageRef };
     }
 
     if (!options.skipPush) {
-      await maybePushImage();
+      await maybePushImage(imageRef);
     }
 
     const dockerEnv = getDockerEnv();
-    if (imageTag !== 'latest' && fullImage !== latestImage) {
-      await execa('docker', ['tag', fullImage, latestImage], {
+    if (effectiveTag !== 'latest' && imageRef !== latestRef) {
+      await execa('docker', ['tag', imageRef, latestRef], {
         stdio: 'pipe',
         env: dockerEnv,
       }).catch(() => {});
     }
 
-    return { ranCompose: false };
+    return { ranCompose: false, fullImage: imageRef };
   }
 
   return {

package/src/utils/docker-image.js

@@ -41,12 +41,12 @@ export function resolveImageTag(env = process.env, options = {}) {
 }
 
 /**
+ * Same repository naming as resolveDockerImageRef, with an explicit tag.
+ * Ignores DOCKER_IMAGE_TAG / git / CI — used when restoring a known buildId.
+ *
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {Record<string, string|undefined>} [env]
- * @param {{
- *   getGitShortSha?: () => string|null,
- *   now?: () => Date,
- * }} [options]
+ * @param {string} imageTag
  * @returns {{
  *   imageName: string,
  *   imageTag: string,
@@ -56,12 +56,8 @@ export function resolveImageTag(env = process.env, options = {}) {
  *   tagSource: ImageTagSource,
  * }}
  */
-export function resolveDockerImageRef(config, env = process.env, options = {}) {
+export function resolveDockerImageRefForTag(config, env = process.env, imageTag) {
   const imageName = env.DOCKER_IMAGE_NAME || config.project;
-  const { imageTag, tagSource } = resolveImageTag(env, {
-    ...options,
-    buildId: /** @type {{ buildId?: string }} */ (config).buildId,
-  });
   const registryUrl = env.DOCKER_REGISTRY_URL || '';
 
   const repository =
@@ -75,6 +71,47 @@ export function resolveDockerImageRef(config, env = process.env, options = {}) {
     fullImage: `${repository}:${imageTag}`,
     latestImage: `${repository}:latest`,
     legacyLatestImage: `${config.project}:latest`,
+    tagSource: 'buildId',
+  };
+}
+
+/**
+ * Replace the tag portion of a docker image ref (handles registry:port/name:tag).
+ * @param {string} imageRef
+ * @param {string} newTag
+ */
+export function replaceDockerImageTag(imageRef, newTag) {
+  const lastSlash = imageRef.lastIndexOf('/');
+  const lastColon = imageRef.lastIndexOf(':');
+  if (lastColon > lastSlash) {
+    return `${imageRef.slice(0, lastColon)}:${newTag}`;
+  }
+  return `${imageRef}:${newTag}`;
+}
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string|undefined>} [env]
+ * @param {{
+ *   getGitShortSha?: () => string|null,
+ *   now?: () => Date,
+ * }} [options]
+ * @returns {{
+ *   imageName: string,
+ *   imageTag: string,
+ *   fullImage: string,
+ *   latestImage: string,
+ *   legacyLatestImage: string,
+ *   tagSource: ImageTagSource,
+ * }}
+ */
+export function resolveDockerImageRef(config, env = process.env, options = {}) {
+  const { imageTag, tagSource } = resolveImageTag(env, {
+    ...options,
+    buildId: /** @type {{ buildId?: string }} */ (config).buildId,
+  });
+  return {
+    ...resolveDockerImageRefForTag(config, env, imageTag),
     tagSource,
   };
 }
@@ -217,6 +254,8 @@ export function describeInterpretedBackendGap(framework) {
 
 export default {
   resolveDockerImageRef,
+  resolveDockerImageRefForTag,
+  replaceDockerImageTag,
   resolveImageTag,
   highResImageTagFallback,
   EXPLICIT_IMAGE_TAG_WARNING,