@akash-chowdhury-24/deployhub 2.0.11 → 2.0.13

package/README.md

@@ -225,10 +225,12 @@ Or push to `main` / `master` — the generated workflow runs the same command.
 **Useful follow-up commands:**
 
 ```bash
-deployhub artifact list              # see uploaded versions
-deployhub artifact restore v1.2.3    # download a past build
+deployhub artifact list              # local artifacts
+deployhub artifact list --remote     # include storage history.json
+deployhub artifact restore <buildId> # download a past build
 deployhub deploy                     # deploy latest artifact without rebuilding
-deployhub rollback v1.2.2            # roll back on server
+deployhub rollback                   # previous build from history
+deployhub rollback <buildId>         # exact build (required if semver is ambiguous)
 deployhub logs                       # last deployment logs
 ```
 
@@ -269,7 +271,17 @@ deployhub doctor
 deployhub build
 ```
 
-Artifacts appear under `artifact/{projectName}/{date}/v{version}/` locally **and** in your S3 bucket.
+Artifacts appear under `artifact/{projectName}/{date}/v{buildId}/` locally.
+
+**Remote storage** (S3 and other providers) uses a different layout:
+
+```text
+{project}/builds/{buildId}/artifact.zip   # immutable per CI/build
+{project}/history.json                    # newest-first index for rollback / list --remote
+{project}/latest/artifact.zip             # mutable pointer overwritten every upload (NOT a backup)
+```
+
+`buildId` is unique per pipeline run (e.g. `1.0.6-a1b2c3d`) even if `package.json` semver is unchanged. Legacy keys `{project}/v{semver}/artifact.zip` are no longer written; they remain readable for older uploads only.
 
 ### Same steps for other languages
 
@@ -943,12 +955,12 @@ Run `deployhub doctor` after any config change.
 | `deployhub init` | Interactive project setup |
 | `deployhub build` | Full pipeline: detect → install → test → build → artifact → storage → deploy |
 | `deployhub artifact create` | Create artifact from current build |
-| `deployhub artifact list` | List all artifacts |
-| `deployhub artifact restore <version>` | Download and extract an artifact |
+| `deployhub artifact list [--remote]` | List local artifacts; `--remote` merges storage `history.json` |
+| `deployhub artifact restore <buildId\|semver>` | Download and extract an artifact |
 | `deployhub storage add <provider>` | Add storage provider credentials |
 | `deployhub storage list` | List storage providers and connection status |
 | `deployhub deploy` | Deploy latest artifact |
-| `deployhub rollback [version]` | Rollback to a previous version |
+| `deployhub rollback [buildId\|semver]` | Previous build, or exact buildId (ambiguous semver lists matches and exits) |
 | `deployhub logs` | Show logs from last deployment |
 | `deployhub doctor` | Pre-flight checks |
 | `deployhub verify` | Health check on configured endpoint |
@@ -1029,13 +1041,13 @@ If checks fail:
 
 ## Artifact Structure
 
-Each build creates:
+Each build creates a **local** directory:
 
 ```
 artifact/
   {projectName}/
     {YYYY-MM-DD}/
-      v{semver}/
+      v{buildId}/
         artifact.zip
         metadata.json
         logs.txt
@@ -1045,6 +1057,18 @@ artifact/
         README.md
 ```
 
+`buildId` looks like `{semver}-{gitSha|ciId|timestamp}` (unique every pipeline run).
+
+**Remote keys** (all storage providers):
+
+```
+{project}/builds/{buildId}/artifact.zip
+{project}/history.json
+{project}/latest/artifact.zip    # overwritten every build — convenience pointer only, not version history
+```
+
+Legacy (read-only fallback, no longer written): `{project}/v{semver}/artifact.zip`
+
 `deployment.json` records server deployment metadata per environment:
 
 ```json

package/package.json

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

package/src/artifact/engine.js

@@ -5,6 +5,7 @@ import { execa } from 'execa';
 import { createLogger } from '../logger/index.js';
 import { generateChecksums, formatChecksums } from '../utils/checksums.js';
 import { getProjectVersion } from '../utils/version.js';
+import { resolveBuildId } from '../utils/build-id.js';
 import { generateNginxConfig } from '../utils/nginx.js';
 import {
   ensureDeployScaffold,
@@ -238,12 +239,13 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
  */
 export function getArtifactDir(config, cwd = process.cwd()) {
   const date = new Date().toISOString().slice(0, 10);
+  const buildId = config.buildId || config.version || '0.0.0';
   return path.join(
     cwd,
     'artifact',
     config.project,
     date,
-    `v${config.version}`
+    `v${buildId}`
   );
 }
 
@@ -257,6 +259,10 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
   const log = createLogger('artifact');
   const version = config.version || (await getProjectVersion(cwd));
   config.version = version;
+  if (!config.buildId) {
+    const { buildId } = resolveBuildId({ semver: version });
+    config.buildId = buildId;
+  }
 
   const artifactDir = getArtifactDir(config, cwd);
   const stagingDir = path.join(artifactDir, '_staging');
@@ -266,7 +272,7 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
   const artifactType = resolveArtifactType(config);
   const settings = resolveBuildSettings(config);
 
-  log.info(`Staging ${projectType} artifact...`);
+  log.info(`Staging ${projectType} artifact (buildId=${config.buildId})...`);
 
   await ensureDeployScaffold(cwd, config, config.environments || {}, { silent: false });
 
@@ -288,6 +294,7 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
   const metadata = {
     project: config.project,
     version,
+    buildId: config.buildId,
     timestamp,
     gitCommit: git.commit,
     branch: git.branch,

package/src/commands/artifact.js

@@ -5,7 +5,10 @@ import {
   listLocalArtifacts,
   extractArtifact,
 } from '../artifact/engine.js';
-import { downloadFromFirst } from '../storage/index.js';
+import { downloadArtifactEntry, loadArtifactHistory, downloadFromFirst } from '../storage/index.js';
+import {
+  legacyArtifactRemoteKey,
+} from '../utils/build-id.js';
 import fs from 'fs-extra';
 import path from 'path';
 
@@ -29,53 +32,97 @@ export function registerArtifactCommand(program) {
 
   artifact
     .command('list')
-    .description('List all artifacts')
-    .action(async () => {
+    .description('List local artifacts (add --remote to include storage history.json)')
+    .option('--remote', 'Also list builds from remote history.json')
+    .action(async (opts) => {
       loadEnv();
+      const config = await loadConfig();
       const artifacts = await listLocalArtifacts();
 
+      console.log(chalk.bold('\nLocal artifacts:\n'));
       if (artifacts.length === 0) {
-        console.log(chalk.yellow('No local artifacts found.'));
-        return;
+        console.log(chalk.yellow('  (none)'));
+      } else {
+        for (const a of artifacts) {
+          const sizeMb = (a.size / 1024 / 1024).toFixed(2);
+          console.log(
+            `  ${chalk.cyan(a.version)}  ${a.date}  ${a.project}  ${sizeMb} MB`
+          );
+          console.log(chalk.gray(`    ${a.path}`));
+        }
       }
 
-      console.log(chalk.bold('\nArtifacts:\n'));
-      for (const a of artifacts) {
-        const sizeMb = (a.size / 1024 / 1024).toFixed(2);
-        console.log(
-          `  ${chalk.cyan(a.version)}  ${a.date}  ${a.project}  ${sizeMb} MB`
-        );
-        console.log(chalk.gray(`    ${a.path}`));
+      if (opts.remote) {
+        console.log(chalk.bold('\nRemote history (storage):\n'));
+        try {
+          const history = await loadArtifactHistory(config.storage || [], config.project);
+          if (history.length === 0) {
+            console.log(chalk.yellow('  (no history.json found)'));
+          } else {
+            for (const e of history) {
+              console.log(
+                `  ${chalk.cyan(e.buildId)}  semver=${e.semver}  ${e.uploadedAt || ''}`
+              );
+              console.log(chalk.gray(`    ${e.remoteKey}`));
+            }
+          }
+        } catch (err) {
+          console.log(
+            chalk.yellow(
+              `  Could not load remote history: ${err instanceof Error ? err.message : String(err)}`
+            )
+          );
+        }
       }
+
       console.log('');
     });
 
   artifact
-    .command('restore <version>')
-    .description('Download and extract an artifact by version')
-    .action(async (version) => {
+    .command('restore <versionOrBuildId>')
+    .description('Download and extract an artifact by buildId or legacy semver')
+    .action(async (versionOrBuildId) => {
       loadEnv();
       const config = await loadConfig();
       const cwd = process.cwd();
+      const needle = String(versionOrBuildId).replace(/^v/i, '');
 
       const local = await listLocalArtifacts(cwd);
-      const localMatch = local.find((a) => a.version === version);
+      const localMatch = local.find(
+        (a) => a.version === needle || a.version === versionOrBuildId
+      );
 
       if (localMatch) {
-        const extractTo = path.join(cwd, '.deployhub-restore', `v${version}`);
+        const extractTo = path.join(cwd, '.deployhub-restore', `v${localMatch.version}`);
         await extractArtifact(localMatch.path, extractTo);
         console.log(chalk.green(`Restored to ${extractTo}`));
         return;
       }
 
-      const remoteKey = `${config.project}/v${version}/artifact.zip`;
-      const restoreDir = path.join(cwd, '.deployhub-restore', `v${version}`);
+      const history = await loadArtifactHistory(config.storage || [], config.project);
+      const histMatch =
+        history.find((e) => e.buildId === needle || e.buildId === versionOrBuildId) ||
+        history.find((e) => e.semver === needle);
+
+      const restoreDir = path.join(cwd, '.deployhub-restore', `v${needle}`);
       await fs.ensureDir(restoreDir);
       const zipPath = path.join(restoreDir, 'artifact.zip');
 
-      console.log(`Downloading v${version} from storage...`);
-      const provider = await downloadFromFirst(config.storage, remoteKey, zipPath);
-      console.log(chalk.gray(`Downloaded from ${provider}`));
+      if (histMatch) {
+        console.log(`Downloading ${histMatch.buildId} from storage...`);
+        const provider = await downloadArtifactEntry(
+          config.storage,
+          config,
+          histMatch,
+          zipPath
+        );
+        console.log(chalk.gray(`Downloaded from ${provider}`));
+      } else {
+        const remoteKey = legacyArtifactRemoteKey(config.project, needle);
+        console.log(`Downloading legacy key ${remoteKey} from storage...`);
+        const provider = await downloadFromFirst(config.storage, remoteKey, zipPath);
+        console.log(chalk.gray(`Downloaded from ${provider}`));
+      }
 
       const versionDir = path.join(restoreDir, 'artifact');
       await fs.ensureDir(versionDir);

package/src/commands/rollback.js

@@ -8,42 +8,45 @@ import axios from 'axios';
  */
 export function registerRollbackCommand(program) {
   program
-    .command('rollback [version]')
-    .description('Rollback to a previous artifact version')
-    .action(async (version) => {
+    .command('rollback [versionOrBuildId]')
+    .description(
+      'Rollback to a previous artifact build (omit arg = previous build; use exact buildId if semver is ambiguous)'
+    )
+    .action(async (versionOrBuildId) => {
       loadEnv();
       const config = await loadConfig();
 
-      if (!version) {
-        const { listLocalArtifacts } = await import('../artifact/engine.js');
-        const artifacts = await listLocalArtifacts();
-        if (artifacts.length < 2) {
-          console.error(chalk.red('No previous version available for rollback'));
-          process.exit(1);
+      try {
+        const { entry } = await rollbackToVersion(config, versionOrBuildId);
+        if (!versionOrBuildId) {
+          console.log(chalk.gray(`Rolled back to previous build: ${entry.buildId}`));
         }
-        version = artifacts[1].version;
-        console.log(chalk.gray(`Rolling back to previous version: v${version}`));
-      }
-
-      await rollbackToVersion(config, version);
 
-      if (config.healthCheck?.url) {
-        try {
-          const response = await axios.get(config.healthCheck.url, {
-            timeout: (config.healthCheck.timeout || 30) * 1000,
-            validateStatus: () => true,
-          });
-          if (response.status >= 200 && response.status < 400) {
-            console.log(chalk.green(`Health check passed: HTTP ${response.status}`));
-          } else {
-            console.log(chalk.yellow(`Health check returned HTTP ${response.status}`));
+        if (config.healthCheck?.url) {
+          try {
+            const response = await axios.get(config.healthCheck.url, {
+              timeout: (config.healthCheck.timeout || 30) * 1000,
+              validateStatus: () => true,
+            });
+            if (response.status >= 200 && response.status < 400) {
+              console.log(chalk.green(`Health check passed: HTTP ${response.status}`));
+            } else {
+              console.log(chalk.yellow(`Health check returned HTTP ${response.status}`));
+            }
+          } catch (err) {
+            console.log(
+              chalk.yellow(
+                `Health check failed: ${err instanceof Error ? err.message : String(err)}`
+              )
+            );
           }
-        } catch (err) {
-          console.log(chalk.yellow(`Health check failed: ${err instanceof Error ? err.message : String(err)}`));
         }
-      }
 
-      console.log(chalk.green(`✓ Rolled back to v${version}`));
+        console.log(chalk.green(`✓ Rolled back to ${entry.buildId}`));
+      } catch (err) {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+      }
     });
 }
 

package/src/core/config.js

@@ -47,6 +47,7 @@ const EnvironmentSchema = z.object({
 const ConfigSchema = z.object({
   project: z.string(),
   version: z.string().optional(),
+  buildId: z.string().optional(),
   projectType: z.enum(['frontend', 'backend', 'both']).default('frontend'),
   framework: z.string().optional(),
   language: z.string().optional(),

package/src/core/stages.js

@@ -6,6 +6,7 @@ import { deployToAll } from '../deployment/index.js';
 import { sendNotifications } from '../notifications/index.js';
 import axios from 'axios';
 import { getProjectVersion } from '../utils/version.js';
+import { resolveBuildId } from '../utils/build-id.js';
 import { ensureDeployScaffold } from '../utils/scaffold.js';
 
 /**
@@ -41,8 +42,10 @@ export function buildPipelineStages(config, cwd, state) {
             ctx.config.port = detected.port;
           }
         }
-        // Resolve version before docker so pipeline build and deploy share the same tag
+        // Semver label (package.json) + unique buildId (shared with image tag when DOCKER_IMAGE_TAG unset)
         ctx.config.version = await getProjectVersion(ctx.cwd);
+        const { buildId } = resolveBuildId({ semver: ctx.config.version });
+        ctx.config.buildId = buildId;
         const scaffold = await ensureDeployScaffold(
           ctx.cwd,
           ctx.config,
@@ -123,6 +126,10 @@ export function buildPipelineStages(config, cwd, state) {
         if (!ctx.config.version) {
           ctx.config.version = await getProjectVersion(ctx.cwd);
         }
+        if (!ctx.config.buildId) {
+          const { buildId } = resolveBuildId({ semver: ctx.config.version });
+          ctx.config.buildId = buildId;
+        }
         const result = await createArtifact(
           ctx.config,
           /** @type {string[]} */ (ctx.state.deployedTargets || []),

package/src/storage/index.js

@@ -1,4 +1,6 @@
 import path from 'path';
+import fs from 'fs-extra';
+import os from 'os';
 import { createLogger } from '../logger/index.js';
 import { createAwsProvider } from './providers/aws.js';
 import { createLocalProvider } from './providers/local.js';
@@ -7,8 +9,19 @@ import { createGcpProvider } from './providers/gcp.js';
 import { createGdriveProvider } from './providers/gdrive.js';
 import { createDropboxProvider } from './providers/dropbox.js';
 import { createFtpProvider } from './providers/ftp.js';
+import {
+  buildArtifactRemoteKey,
+  historyRemoteKey,
+  latestArtifactRemoteKey,
+  legacyArtifactRemoteKey,
+  resolveBuildId,
+} from '../utils/build-id.js';
+import {
+  parseArtifactHistory,
+  prependHistoryEntry,
+} from '../utils/artifact-history.js';
 
-/** @type {Record<string, (env?: Record<string, string>) => import('./providers/aws.js').default>} */
+/** @type {Record<string, (env?: Record<string, string>) => ReturnType<typeof createAwsProvider>>} */
 const PROVIDER_FACTORIES = {
   aws: createAwsProvider,
   local: createLocalProvider,
@@ -32,21 +45,112 @@ export function getStorageProvider(name, env = process.env) {
 }
 
 /**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ */
+function ensureBuildIdentity(config) {
+  if (!config.version) {
+    config.version = '0.0.0';
+  }
+  if (!config.buildId) {
+    const { buildId } = resolveBuildId({ semver: config.version });
+    config.buildId = buildId;
+  }
+}
+
+/**
+ * Read history.json from the first provider that has it.
+ * @param {string[]} providers
+ * @param {string} project
+ * @returns {Promise<import('../utils/artifact-history.js').ArtifactHistoryEntry[]>}
+ */
+export async function loadArtifactHistory(providers, project) {
+  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);
+    }
+  } catch {
+    return [];
+  } finally {
+    await fs.remove(tmp).catch(() => {});
+  }
+  return [];
+}
+
+/**
+ * @param {ReturnType<typeof getStorageProvider>} provider
+ * @param {string} project
+ * @param {import('../utils/artifact-history.js').ArtifactHistoryEntry[]} history
+ */
+async function writeArtifactHistory(provider, project, history) {
+  const key = historyRemoteKey(project);
+  const tmp = path.join(os.tmpdir(), `deployhub-history-write-${Date.now()}.json`);
+  await fs.writeJson(tmp, history, { spaces: 2 });
+  try {
+    await provider.upload(tmp, key);
+  } finally {
+    await fs.remove(tmp).catch(() => {});
+  }
+}
+
+/**
+ * Upload artifact zip under a unique build key, update latest/ pointer and history.json.
+ * Does NOT write legacy `{project}/v{semver}/artifact.zip` (retired for new uploads;
+ * legacy keys remain readable for older artifacts).
+ *
  * @param {string[]} providers
  * @param {string} zipPath
  * @param {import('../core/config.js').DeployHubConfig} config
  */
 export async function uploadToAll(providers, zipPath, config) {
   const log = createLogger('storage');
-  const remoteKey = `${config.project}/v${config.version}/artifact.zip`;
+  ensureBuildIdentity(config);
+
+  const buildId = /** @type {string} */ (config.buildId);
+  const remoteKey = buildArtifactRemoteKey(config.project, buildId);
+  const latestKey = latestArtifactRemoteKey(config.project);
+  const entry = {
+    buildId,
+    semver: String(config.version || '0.0.0').replace(/^v/i, ''),
+    uploadedAt: new Date().toISOString(),
+    remoteKey,
+  };
 
   const uploads = providers.map(async (name) => {
     try {
       const provider = getStorageProvider(name);
-      log.info(`Uploading to ${name}...`);
+      log.info(`Uploading build ${buildId} to ${name}...`);
       await provider.upload(zipPath, remoteKey);
-      log.success(`Uploaded to ${name}`);
-      return { name, success: true };
+      // Intentional overwrite: mutable "current" pointer, not a versioned backup.
+      await provider.upload(zipPath, latestKey);
+
+      let history = [];
+      try {
+        const histKey = historyRemoteKey(config.project);
+        if (await provider.verify(histKey)) {
+          const tmp = path.join(os.tmpdir(), `deployhub-hist-${name}-${Date.now()}.json`);
+          try {
+            await provider.download(histKey, tmp);
+            history = parseArtifactHistory(await fs.readFile(tmp, 'utf8'));
+          } finally {
+            await fs.remove(tmp).catch(() => {});
+          }
+        }
+      } catch {
+        history = [];
+      }
+
+      const next = prependHistoryEntry(history, entry);
+      await writeArtifactHistory(provider, config.project, next);
+
+      log.success(`Uploaded to ${name} (${remoteKey})`);
+      return { name, success: true, remoteKey, buildId };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       throw new Error(`Storage upload to ${name} failed: ${message}`);
@@ -73,6 +177,27 @@ export async function downloadFromFirst(providers, remoteKey, localPath) {
   throw new Error(`Artifact not found in any configured storage provider`);
 }
 
+/**
+ * Download a build by history entry, with legacy key fallback for pre-buildId uploads.
+ *
+ * @param {string[]} providers
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {{ remoteKey: string, buildId: string, semver: string }} entry
+ * @param {string} localPath
+ */
+export async function downloadArtifactEntry(providers, config, entry, localPath) {
+  try {
+    return await downloadFromFirst(providers, entry.remoteKey, localPath);
+  } catch {
+    const legacyKey = legacyArtifactRemoteKey(config.project, entry.semver);
+    const log = createLogger('storage');
+    log.warn(
+      `Build key not found; trying legacy key ${legacyKey} (may be an overwritten single-slot artifact)`
+    );
+    return downloadFromFirst(providers, legacyKey, localPath);
+  }
+}
+
 /**
  * @param {string} name
  */
@@ -99,11 +224,18 @@ export async function testAllProviders(providers) {
     }
     return {
       name,
-      status: 'error',
-      error: result.reason?.message || String(result.reason),
+      status: 'failed',
+      error: result.reason instanceof Error ? result.reason.message : String(result.reason),
     };
   });
 }
 
-export { PROVIDER_FACTORIES };
-export default { getStorageProvider, uploadToAll, downloadFromFirst, testProvider, testAllProviders };
+export default {
+  getStorageProvider,
+  uploadToAll,
+  downloadFromFirst,
+  downloadArtifactEntry,
+  loadArtifactHistory,
+  testProvider,
+  testAllProviders,
+};

package/src/utils/artifact-history.js

@@ -0,0 +1,155 @@
+/**
+ * Artifact upload history (newest-first) and rollback target resolution.
+ */
+
+/**
+ * @typedef {{
+ *   buildId: string,
+ *   semver: string,
+ *   uploadedAt: string,
+ *   remoteKey: string,
+ * }} ArtifactHistoryEntry
+ */
+
+/**
+ * @param {string|unknown} raw
+ * @returns {ArtifactHistoryEntry[]}
+ */
+export function parseArtifactHistory(raw) {
+  if (!raw) return [];
+  try {
+    const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!Array.isArray(data)) return [];
+    return data
+      .filter(
+        (e) =>
+          e &&
+          typeof e === 'object' &&
+          typeof e.buildId === 'string' &&
+          typeof e.remoteKey === 'string'
+      )
+      .map((e) => ({
+        buildId: String(e.buildId),
+        semver: String(e.semver || '').replace(/^v/i, '') || '0.0.0',
+        uploadedAt: String(e.uploadedAt || ''),
+        remoteKey: String(e.remoteKey),
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {ArtifactHistoryEntry[]} history
+ * @param {ArtifactHistoryEntry} entry
+ * @returns {ArtifactHistoryEntry[]}
+ */
+export function prependHistoryEntry(history, entry) {
+  const filtered = history.filter((e) => e.buildId !== entry.buildId);
+  return [entry, ...filtered];
+}
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+export function normalizeVersionArg(input) {
+  return String(input || '')
+    .trim()
+    .replace(/^v/i, '');
+}
+
+/**
+ * Resolve which history entry to roll back to.
+ *
+ * @param {ArtifactHistoryEntry[]} history newest-first
+ * @param {string} [versionOrBuildId] omitted = previous build (history[1])
+ * @returns {{
+ *   ok: true,
+ *   entry: ArtifactHistoryEntry,
+ * } | {
+ *   ok: false,
+ *   reason: 'empty'|'no-previous'|'not-found'|'ambiguous',
+ *   message: string,
+ *   matches?: ArtifactHistoryEntry[],
+ * }}
+ */
+export function resolveRollbackTarget(history, versionOrBuildId) {
+  if (!history.length) {
+    return {
+      ok: false,
+      reason: 'empty',
+      message: 'No artifact history found in storage. Deploy at least once first.',
+    };
+  }
+
+  if (!versionOrBuildId) {
+    if (history.length < 2) {
+      return {
+        ok: false,
+        reason: 'no-previous',
+        message: 'No previous build available for rollback (only one build in history).',
+      };
+    }
+    return { ok: true, entry: history[1] };
+  }
+
+  const needle = normalizeVersionArg(versionOrBuildId);
+
+  const exact = history.find((e) => e.buildId === needle || e.buildId === versionOrBuildId);
+  if (exact) {
+    return { ok: true, entry: exact };
+  }
+
+  const current = history[0];
+  const semverMatches = history.filter(
+    (e) => e.semver === needle || `v${e.semver}` === String(versionOrBuildId).trim()
+  );
+
+  if (semverMatches.length === 0) {
+    return {
+      ok: false,
+      reason: 'not-found',
+      message: `No artifact found for '${versionOrBuildId}'. Use an exact buildId from: deployhub artifact list --remote`,
+    };
+  }
+
+  const nonCurrent = semverMatches.filter((e) => e.buildId !== current.buildId);
+
+  if (nonCurrent.length === 1) {
+    return { ok: true, entry: nonCurrent[0] };
+  }
+
+  if (nonCurrent.length === 0) {
+    return {
+      ok: false,
+      reason: 'not-found',
+      message: `Only the current build matches semver '${needle}' (${current.buildId}). Nothing to roll back to for that label.`,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: 'ambiguous',
+    message: `Multiple builds match semver '${needle}'. Re-run with an exact buildId:`,
+    matches: nonCurrent,
+  };
+}
+
+/**
+ * @param {ArtifactHistoryEntry[]} matches
+ * @returns {string}
+ */
+export function formatAmbiguousRollbackMatches(matches) {
+  return matches
+    .map((e) => `  ${e.buildId}  uploadedAt=${e.uploadedAt || '(unknown)'}  key=${e.remoteKey}`)
+    .join('\n');
+}
+
+export default {
+  parseArtifactHistory,
+  prependHistoryEntry,
+  normalizeVersionArg,
+  resolveRollbackTarget,
+  formatAmbiguousRollbackMatches,
+};

package/src/utils/build-id.js

@@ -0,0 +1,149 @@
+/**
+ * Unique per-build identity shared by artifact storage keys and (when unset)
+ * Docker image tags.
+ */
+
+import { execFileSync } from 'child_process';
+
+/** @typedef {'git'|'ci'|'timestamp'} BuildStampSource */
+
+/**
+ * High-resolution timestamp stamp (seconds+ms) for uniqueness in fast rebuild loops.
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function highResBuildStamp(now = new Date()) {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  const h = String(now.getHours()).padStart(2, '0');
+  const min = String(now.getMinutes()).padStart(2, '0');
+  const sec = String(now.getSeconds()).padStart(2, '0');
+  const ms = String(now.getMilliseconds()).padStart(3, '0');
+  return `${y}.${m}.${d}.${h}${min}-${sec}${ms}`;
+}
+
+/**
+ * @returns {string|null}
+ */
+function defaultGetGitShortSha() {
+  try {
+    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return sha || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Unique build stamp: git SHA → CI id → high-res timestamp.
+ * Does not read DOCKER_IMAGE_TAG (explicit image tags stay separate from artifact identity).
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {{
+ *   getGitShortSha?: () => string|null,
+ *   now?: () => Date,
+ * }} [options]
+ * @returns {{ stamp: string, source: BuildStampSource }}
+ */
+export function resolveUniqueBuildStamp(env = process.env, options = {}) {
+  const getGitShortSha = options.getGitShortSha || defaultGetGitShortSha;
+  const gitSha = getGitShortSha();
+  if (gitSha) {
+    return { stamp: gitSha, source: 'git' };
+  }
+
+  const ciTag =
+    (env.GITHUB_SHA && String(env.GITHUB_SHA).slice(0, 7)) ||
+    env.GITHUB_RUN_ID ||
+    env.CI_COMMIT_SHORT_SHA ||
+    env.CI_PIPELINE_ID;
+  if (ciTag) {
+    return { stamp: String(ciTag), source: 'ci' };
+  }
+
+  const now = options.now ? options.now() : new Date();
+  return { stamp: highResBuildStamp(now), source: 'timestamp' };
+}
+
+/**
+ * Sanitize for use in paths and image tags.
+ * @param {string} value
+ * @returns {string}
+ */
+export function sanitizeBuildIdPart(value) {
+  return String(value)
+    .replace(/^v/i, '')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'build';
+}
+
+/**
+ * @param {{
+ *   semver?: string,
+ *   env?: Record<string, string|undefined>,
+ *   getGitShortSha?: () => string|null,
+ *   now?: () => Date,
+ * }} [options]
+ * @returns {{ buildId: string, semver: string, stamp: string, source: BuildStampSource }}
+ */
+export function resolveBuildId(options = {}) {
+  const env = options.env || process.env;
+  const semver = sanitizeBuildIdPart(options.semver || '0.0.0');
+  const { stamp, source } = resolveUniqueBuildStamp(env, options);
+  const safeStamp = sanitizeBuildIdPart(stamp);
+  return {
+    buildId: `${semver}-${safeStamp}`,
+    semver,
+    stamp: safeStamp,
+    source,
+  };
+}
+
+/**
+ * Remote key for an immutable build artifact.
+ * @param {string} project
+ * @param {string} buildId
+ */
+export function buildArtifactRemoteKey(project, buildId) {
+  return `${project}/builds/${buildId}/artifact.zip`;
+}
+
+/**
+ * Mutable pointer overwritten every upload (not a backup slot).
+ * @param {string} project
+ */
+export function latestArtifactRemoteKey(project) {
+  return `${project}/latest/artifact.zip`;
+}
+
+/**
+ * @param {string} project
+ */
+export function historyRemoteKey(project) {
+  return `${project}/history.json`;
+}
+
+/**
+ * Pre-buildId legacy key (read-only fallback; never written by new uploads).
+ * @param {string} project
+ * @param {string} semver
+ */
+export function legacyArtifactRemoteKey(project, semver) {
+  return `${project}/v${sanitizeBuildIdPart(semver)}/artifact.zip`;
+}
+
+export default {
+  highResBuildStamp,
+  resolveUniqueBuildStamp,
+  resolveBuildId,
+  sanitizeBuildIdPart,
+  buildArtifactRemoteKey,
+  latestArtifactRemoteKey,
+  historyRemoteKey,
+  legacyArtifactRemoteKey,
+};

package/src/utils/docker-image.js

@@ -2,53 +2,27 @@
  * Shared Docker image naming for pipeline builds and deploy.
  */
 
-import { execFileSync } from 'child_process';
+import { resolveUniqueBuildStamp, highResBuildStamp } from './build-id.js';
 
-/** @typedef {'explicit'|'git'|'ci'|'timestamp'} ImageTagSource */
+/** @typedef {'explicit'|'git'|'ci'|'timestamp'|'buildId'} ImageTagSource */
 
 export const EXPLICIT_IMAGE_TAG_WARNING =
   'DOCKER_IMAGE_TAG is set — reusing the same tag across deploys can leave Kubernetes pods on a stale image (imagePullPolicy defaults to IfNotPresent) unless imagePullPolicy is Always or a rollout restart runs.';
 
-/**
- * High-resolution timestamp for image tags only (artifact versioning keeps getDateVersion()).
- * Minute prefix matches getDateVersion(); seconds+ms avoid collisions in fast rebuild loops.
- * @param {Date} [now]
- * @returns {string}
- */
+/** @deprecated use highResBuildStamp from build-id.js — kept for existing imports/tests */
 export function highResImageTagFallback(now = new Date()) {
-  const y = now.getFullYear();
-  const m = String(now.getMonth() + 1).padStart(2, '0');
-  const d = String(now.getDate()).padStart(2, '0');
-  const h = String(now.getHours()).padStart(2, '0');
-  const min = String(now.getMinutes()).padStart(2, '0');
-  const sec = String(now.getSeconds()).padStart(2, '0');
-  const ms = String(now.getMilliseconds()).padStart(3, '0');
-  return `${y}.${m}.${d}.${h}${min}-${sec}${ms}`;
-}
-
-/**
- * @returns {string|null}
- */
-function defaultGetGitShortSha() {
-  try {
-    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    return sha || null;
-  } catch {
-    return null;
-  }
+  return highResBuildStamp(now);
 }
 
 /**
- * Resolve image tag when DOCKER_IMAGE_TAG is unset: git SHA → CI id → high-res timestamp.
- * Does not use config.version (static package versions would prevent redeploys).
+ * Resolve image tag when DOCKER_IMAGE_TAG is unset: prefer config.buildId (same
+ * pipeline identity as the artifact), else git SHA → CI id → high-res timestamp.
  *
  * @param {Record<string, string|undefined>} [env]
  * @param {{
  *   getGitShortSha?: () => string|null,
  *   now?: () => Date,
+ *   buildId?: string,
  * }} [options]
  * @returns {{ imageTag: string, tagSource: ImageTagSource }}
  */
@@ -58,23 +32,12 @@ export function resolveImageTag(env = process.env, options = {}) {
     return { imageTag: explicit, tagSource: 'explicit' };
   }
 
-  const getGitShortSha = options.getGitShortSha || defaultGetGitShortSha;
-  const gitSha = getGitShortSha();
-  if (gitSha) {
-    return { imageTag: gitSha, tagSource: 'git' };
-  }
-
-  const ciTag =
-    (env.GITHUB_SHA && String(env.GITHUB_SHA).slice(0, 7)) ||
-    env.GITHUB_RUN_ID ||
-    env.CI_COMMIT_SHORT_SHA ||
-    env.CI_PIPELINE_ID;
-  if (ciTag) {
-    return { imageTag: String(ciTag), tagSource: 'ci' };
+  if (options.buildId) {
+    return { imageTag: options.buildId, tagSource: 'buildId' };
   }
 
-  const now = options.now ? options.now() : new Date();
-  return { imageTag: highResImageTagFallback(now), tagSource: 'timestamp' };
+  const { stamp, source } = resolveUniqueBuildStamp(env, options);
+  return { imageTag: stamp, tagSource: source };
 }
 
 /**
@@ -95,7 +58,10 @@ export function resolveImageTag(env = process.env, options = {}) {
  */
 export function resolveDockerImageRef(config, env = process.env, options = {}) {
   const imageName = env.DOCKER_IMAGE_NAME || config.project;
-  const { imageTag, tagSource } = resolveImageTag(env, options);
+  const { imageTag, tagSource } = resolveImageTag(env, {
+    ...options,
+    buildId: /** @type {{ buildId?: string }} */ (config).buildId,
+  });
   const registryUrl = env.DOCKER_REGISTRY_URL || '';
 
   const repository =

package/src/utils/rollback/engine.js

@@ -1,7 +1,11 @@
-import { downloadFromFirst } from '../../storage/index.js';
+import { downloadArtifactEntry, loadArtifactHistory } from '../../storage/index.js';
 import { getDeploymentProvider } from '../../deployment/index.js';
 import { extractArtifact } from '../../artifact/engine.js';
 import { createLogger } from '../../logger/index.js';
+import {
+  formatAmbiguousRollbackMatches,
+  resolveRollbackTarget,
+} from '../artifact-history.js';
 import fs from 'fs-extra';
 import path from 'path';
 
@@ -25,21 +29,38 @@ async function rollbackTarget(config, artifactDir, envName) {
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
- * @param {string} version
+ * @param {string} [versionOrBuildId]
  * @param {string} [cwd]
  */
-export async function rollbackToVersion(config, version, cwd = process.cwd()) {
+export async function rollbackToVersion(config, versionOrBuildId, cwd = process.cwd()) {
   const log = createLogger('rollback');
-  const remoteKey = `${config.project}/v${version}/artifact.zip`;
-  const restoreDir = path.join(cwd, '.deployhub-restore', `v${version}`);
+  const providers = config.storage || [];
+  if (providers.length === 0) {
+    throw new Error('No storage providers configured — cannot download artifact for rollback');
+  }
+
+  const history = await loadArtifactHistory(providers, config.project);
+  const resolved = resolveRollbackTarget(history, versionOrBuildId);
+
+  if (!resolved.ok) {
+    if (resolved.reason === 'ambiguous' && resolved.matches) {
+      throw new Error(
+        `${resolved.message}\n${formatAmbiguousRollbackMatches(resolved.matches)}`
+      );
+    }
+    throw new Error(resolved.message);
+  }
+
+  const entry = resolved.entry;
+  const restoreDir = path.join(cwd, '.deployhub-restore', `v${entry.buildId}`);
   const artifactDir = path.join(restoreDir, 'artifact');
 
-  log.info(`Downloading artifact v${version}...`);
+  log.info(`Downloading artifact buildId=${entry.buildId} (semver=${entry.semver})...`);
   await fs.emptyDir(restoreDir);
   await fs.ensureDir(artifactDir);
 
   const zipPath = path.join(artifactDir, 'artifact.zip');
-  await downloadFromFirst(config.storage, remoteKey, zipPath);
+  await downloadArtifactEntry(providers, config, entry, zipPath);
 
   log.info('Extracting artifact for rollback...');
   const extractedDir = path.join(artifactDir, '_extracted');
@@ -54,7 +75,7 @@ export async function rollbackToVersion(config, version, cwd = process.cwd()) {
   const targets = config.deploy || [];
   if (targets.length === 0) {
     log.warn('No deployment targets configured');
-    return artifactDir;
+    return { artifactDir, entry };
   }
 
   log.info('Redeploying previous artifact to server targets...');
@@ -62,8 +83,8 @@ export async function rollbackToVersion(config, version, cwd = process.cwd()) {
     await rollbackTarget(config, artifactDir, envName);
   }
 
-  log.success(`Rollback to v${version} complete`);
-  return artifactDir;
+  log.success(`Rollback to buildId=${entry.buildId} complete`);
+  return { artifactDir, entry };
 }
 
 export default { rollbackToVersion };