@akash-chowdhury-24/deployhub 2.0.11 → 2.0.14

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.14",
   "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/cli/index.js

@@ -13,6 +13,7 @@ import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerVerifyCommand } from '../commands/verify.js';
 import { registerCleanCommand } from '../commands/clean.js';
 import { registerUpdateCommand } from '../commands/update.js';
+import { registerSyncWorkflowsCommand } from '../commands/sync-workflows.js';
 import { formatVersionOutput, printBanner, shouldShowBanner } from '../utils/author.js';
 
 loadEnv();
@@ -41,5 +42,6 @@ registerDoctorCommand(program);
 registerVerifyCommand(program);
 registerCleanCommand(program);
 registerUpdateCommand(program);
+registerSyncWorkflowsCommand(program);
 
 program.parse();

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,105 @@ 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 { entries: history, source } = await loadArtifactHistory(
+            config.storage || [],
+            config.project
+          );
+          if (history.length === 0) {
+            console.log(
+              chalk.yellow(
+                '  No artifact history found for this project — you may not have deployed any builds yet.'
+              )
+            );
+          } else {
+            if (source) {
+              console.log(chalk.gray(`  Source: ${source}`));
+              console.log('');
+            }
+            for (const e of history) {
+              console.log(
+                `  ${chalk.cyan(e.buildId)}  semver=${e.semver}  ${e.uploadedAt || ''}`
+              );
+              console.log(chalk.gray(`    ${e.remoteKey}`));
+            }
+          }
+        } catch (err) {
+          const detail = err instanceof Error ? err.message : String(err);
+          console.log(chalk.red(`  ${detail}`));
+        }
       }
+
       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.entries.find((e) => e.buildId === needle || e.buildId === versionOrBuildId) ||
+        history.entries.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/doctor.js

@@ -7,7 +7,7 @@ import axios from 'axios';
 import { loadConfig, loadEnv } from '../core/config.js';
 import { testProvider } from '../storage/index.js';
 import { getDeploymentProvider } from '../deployment/index.js';
-import { PROVIDER_ENV_MAP } from '../utils/github-actions.js';
+import { PROVIDER_ENV_MAP, getRollbackWorkflowDoctorCheck } from '../utils/github-actions.js';
 import { printDoctorFooter } from '../utils/author.js';
 import { createLocalProvider } from '../storage/providers/local.js';
 import {
@@ -888,11 +888,28 @@ export function registerDoctorCommand(program) {
           return {
             name: 'GitHub Actions',
             pass: false,
-            message: 'Workflow file missing — run deployhub init',
+            message: 'Workflow file missing — run deployhub init or deployhub sync-workflows',
           };
         })
       );
 
+      const hasStorage = (config.storage || []).length > 0;
+      const hasDeploy = (config.deploy || []).length > 0;
+      if (hasStorage && hasDeploy) {
+        results.push(
+          await runCheck('Rollback workflow', async () => {
+            const check = await getRollbackWorkflowDoctorCheck(cwd, config);
+            return (
+              check || {
+                name: 'Rollback workflow',
+                pass: true,
+                message: 'Skipped',
+              }
+            );
+          })
+        );
+      }
+
       results.push(
         await runCheck('Storage write', async () => {
           const provider = createLocalProvider();

package/src/commands/init.js

@@ -535,6 +535,7 @@ export function registerInitCommand(program) {
       console.log(chalk.bold('Generated files:'));
       console.log('  • deployhub.config.json');
       console.log('  • .github/workflows/deployhub.yml');
+      console.log('  • .github/workflows/deployhub-rollback.yml');
       console.log('  • .env.example');
       console.log('');
       printAuthorFooter();

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/commands/sync-workflows.js

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+import { loadConfig, loadEnv } from '../core/config.js';
+import {
+  writeWorkflowFile,
+  DEPLOY_WORKFLOW_FILENAME,
+  ROLLBACK_WORKFLOW_FILENAME,
+} from '../utils/github-actions.js';
+
+/**
+ * Regenerate GitHub Actions workflows from deployhub.config.json (no interactive init).
+ * @param {import('commander').Command} program
+ */
+export function registerSyncWorkflowsCommand(program) {
+  program
+    .command('sync-workflows')
+    .description(
+      'Regenerate .github/workflows/deployhub.yml and deployhub-rollback.yml from deployhub.config.json'
+    )
+    .action(async () => {
+      loadEnv();
+      const cwd = process.cwd();
+      const config = await loadConfig(cwd);
+
+      const storage = config.storage || [];
+      const deploy = config.deploy || [];
+      const environments = config.environments || {};
+      const cliSource = config.cli?.source;
+
+      await writeWorkflowFile(storage, deploy, environments, cwd, cliSource, config);
+
+      console.log(chalk.green('✓ Regenerated GitHub Actions workflows:'));
+      console.log(`  • .github/workflows/${DEPLOY_WORKFLOW_FILENAME}`);
+      console.log(`  • .github/workflows/${ROLLBACK_WORKFLOW_FILENAME}`);
+      console.log('');
+      console.log(
+        chalk.gray(
+          'Commit and push these files, then use Actions → DeployHub Rollback (workflow_dispatch) to roll back.'
+        )
+      );
+    });
+}
+
+export default { registerSyncWorkflowsCommand };

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/deployment/index.js

@@ -71,13 +71,14 @@ export async function deployToAll(config, artifactDir, envNames) {
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {string} artifactDir
  * @param {string[]} [envNames]
+ * @param {{ buildId?: string, semver?: string, remoteKey?: string }} [meta]
  */
-export async function rollbackAll(config, artifactDir, envNames) {
+export async function rollbackAll(config, artifactDir, envNames, meta) {
   const targets = envNames || config.deploy || [];
   for (const envName of targets) {
     const envConfig = config.environments[envName];
     const provider = getDeploymentProvider(envConfig.type, config, envName);
-    await provider.rollback(artifactDir);
+    await provider.rollback(artifactDir, meta);
   }
 }
 

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

@@ -21,7 +21,8 @@ export function createAzureVmProvider(config, envName, env = process.env) {
 
     if (!subscriptionId || !resourceGroup || !vmName) {
       throw new Error(
-        'Azure VM host unknown. Set SSH_HOST to your VM public IP, or set AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, and AZURE_VM_NAME for auto lookup.'
+        'Could not resolve host via Azure VM lookup, and no SSH_HOST was set — ' +
+          'provide SSH_HOST (VM public IP/DNS) or set AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, and AZURE_VM_NAME for auto lookup.'
       );
     }
 
@@ -55,34 +56,54 @@ export function createAzureVmProvider(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 VM ${vmName} — ${msg}. Set SSH_HOST manually or run az login and verify resource group/VM name.`
+        `Could not resolve host via Azure VM lookup (${vmName}): ${msg}. ` +
+          'Set SSH_HOST to the VM public IP/DNS, or run az login and verify resource group/VM 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 Azure VM 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);
     },
   };
 }