@akash-chowdhury-24/deployhub 2.0.36 → 2.0.40

package/README.md

@@ -753,6 +753,51 @@ You can enable **multiple providers** — DeployHub uploads to all of them in pa
 
 ---
 
+## Custom deploy hooks
+
+SSH-based deploys (`ssh`, `ec2`, `azure-vm`, `gcp-vm`, and `docker` with `remote.mode: "ssh"`) can run your own commands on the remote host as part of deploy and rollback. Use them for migrations, cache clearing, or a notification — anything you currently SSH in to do by hand.
+
+| Hook | When it runs | Typical use | Failure default |
+|------|----------------|-------------|-----------------|
+| `preDeploy` | After the artifact/image is ready and the host is reachable, **before** the running app/container is replaced or started | DB migrations that must finish before new code runs | Abort the deploy (`continueOnError: false`) |
+| `postDeploy` | After the app is up (SSH start / docker-ssh port publish) | Cache warm, Slack ping, non-critical cleanup | Continue (`continueOnError: true` when added via `init` / `env add`) |
+| `rollback` | During `deployhub rollback`, in the same slot as `preDeploy` — before the restored version takes over | Your own down-migration. DeployHub does not reverse migrations for you | Abort the rollback (`continueOnError: false`) |
+
+Commands run over the **existing** SSH session (not a second connection), unless a successful hook sets `"reconnect": true`. Kubernetes and Docker `local` / `raw` modes do not support hooks (no persistent remote shell session); configuring them there fails loudly at deploy/rollback.
+
+On docker-ssh, `preDeploy` / `rollback` run **before** remote registry login and `docker stop`/`run`, so a hook can install Docker on a bare host. `postDeploy` runs **after** the port-publish inspect check (`docker inspect` confirms `0.0.0.0:<port>->`). A hook that curls the app's published port therefore sees a container DeployHub already treated as published. If that inspect fails, `postDeploy` does not run.
+
+Hook `command` strings are raw remote shell — there is **no** `{{buildId}}` / `{{containerName}}` / `{{port}}` / `{{environment}}` substitution. Hardcode values per environment (or read them from the remote environment). Extra Docker environments use an env-scoped container name (`{project}-{env}`; the first/grandfathered env stays `{project}`), so a hook that `docker exec myapp …` on staging will miss `myapp-staging`.
+
+Hook commands that look like they embed a secret (`--password`, `-p secret`, `TOKEN=…`) are not printed in full in the `$ …` log line. This is a best-effort check, not encryption: hook stdout/stderr is still logged, so prefer env vars on the remote host over inline secrets.
+
+Set `"reconnect": true` on a hook when the command only takes effect on a **new SSH login** — the usual case is `sudo usermod -aG docker $USER`. After that command succeeds, DeployHub closes the current session and opens a new one before the next hook or deploy step. Failed commands never reconnect. Omitted / `false` (the default) never reconnects.
+
+`init` and `env add` ask optionally — default is skip. After each command they ask **Add another … command?** so one stage can collect several entries (no cap), and whether that command needs an SSH reconnect (`[y/N]`, default N). `--yes` / non-interactive env add still writes no hooks. Example:
+
+```json
+"environments": {
+  "production": {
+    "config": {
+      "hooks": {
+        "preDeploy": [
+          { "command": "sudo usermod -aG docker ec2-user", "reconnect": true },
+          { "command": "docker exec myapp python manage.py migrate", "continueOnError": false, "timeoutMs": 60000 }
+        ],
+        "postDeploy": [
+          { "command": "curl -s https://hooks.slack.com/services/T000/B000/xxx -d deployed", "continueOnError": true }
+        ],
+        "rollback": [
+          { "command": "docker exec myapp python manage.py migrate 0042_previous", "continueOnError": false }
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
 ## Choosing a deployment method
 
 DeployHub supports six deployment targets. Pick based on what infrastructure you already have — DeployHub does not provision servers, VMs, or clusters for you.
@@ -808,6 +853,8 @@ sudo usermod -aG docker your-ssh-user
 
 Then **reconnect** (group membership applies on the next login). `deployhub doctor` reports this if missing (it prints the exact `usermod` line). See [Docker](#docker) below.
 
+You can also put that bootstrap in **preDeploy hooks** on a bare host (install Docker, `usermod`, `"reconnect": true`). Registry login runs **after** preDeploy, so those hooks get a chance to install `docker` before `docker login`. Failed login used to abort first (`docker: command not found`) and skip the hooks.
+
 ### SSH
 
 **Verification:** Real-world verified DEPLOY and ROLLBACK.
@@ -857,7 +904,7 @@ Then **reconnect** (group membership applies on the next login). `deployhub doct
 - [ ] Docker installed (`docker --version` works) — on this machine / CI for **local** and **raw**; on the remote Linux host for **ssh**
 - [ ] Registry account if pushing private images
 - [ ] `docker-compose.yml` in project if you use multi-service Compose (not auto-generated)
-- [ ] **SSH mode only:** [one-time server setup](#one-time-server-setup-before-your-first-deploy) — Docker on the host and the SSH user in the `docker` group (`sudo usermod -aG docker <user>`, then reconnect)
+- [ ] **SSH mode only:** [one-time server setup](#one-time-server-setup-before-your-first-deploy) — Docker on the host and the SSH user in the `docker` group (`sudo usermod -aG docker <user>`, then reconnect). A `preDeploy` hook can install Docker and run that `usermod` with `"reconnect": true`; registry login happens after preDeploy.
 
 `init` and `env add` ask **Where should the container run?**
 

package/package.json

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

package/src/commands/doctor.js

@@ -53,6 +53,7 @@ import {
   pickPhpFpmUnitName,
   preferredPhpFpmUnitName,
 } from '../utils/php-fpm.js';
+import { getHooksDoctorChecks } from '../deployment/hooks.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -1409,6 +1410,10 @@ export function registerDoctorCommand(program) {
           informationalCheckNames.add(branchCheck.name);
           results.push(await runCheck(branchCheck.name, async () => branchCheck));
         }
+        for (const hookCheck of getHooksDoctorChecks(config)) {
+          informationalCheckNames.add(hookCheck.name);
+          results.push(await runCheck(hookCheck.name, async () => hookCheck));
+        }
         const driftChecks = await getWorkflowDriftDoctorChecks(cwd, config);
         for (const check of driftChecks) {
           results.push(await runCheck(check.name, async () => check));

package/src/core/config.js

@@ -29,6 +29,13 @@ const SideConfigSchema = z.object({
   port: z.number().optional(),
 });
 
+const HookCommandSchema = z.object({
+  command: z.string().min(1),
+  continueOnError: z.boolean().optional(),
+  timeoutMs: z.number().positive().optional(),
+  reconnect: z.boolean().optional(),
+});
+
 /** Method-specific non-secret settings (host, paths, namespace, image name, etc.). */
 const MethodConfigSchema = z
   .object({
@@ -66,6 +73,17 @@ const MethodConfigSchema = z
       })
       .optional(),
     healthCheckUrl: z.string().optional(),
+    /**
+     * Remote shell hooks for SSH-based methods (ssh / ec2 / azure-vm / gcp-vm /
+     * docker remote.mode ssh). Rejected on kubernetes and docker local/raw.
+     */
+    hooks: z
+      .object({
+        preDeploy: z.array(HookCommandSchema).optional(),
+        postDeploy: z.array(HookCommandSchema).optional(),
+        rollback: z.array(HookCommandSchema).optional(),
+      })
+      .optional(),
     appName: z.string().optional(),
     framework: z.string().optional(),
     port: z.number().optional(),

package/src/deployment/hooks.js

@@ -0,0 +1,269 @@
+/**
+ * Per-environment remote shell hooks (preDeploy / postDeploy / rollback).
+ * One implementation for ssh, ec2, azure-vm, gcp-vm, and docker remote.mode ssh.
+ * Callers must pass the deploy's existing SSH session — do not connect again.
+ */
+
+import { createLogger } from '../logger/index.js';
+import { formatRemoteCommandFailure } from '../utils/shell-quote.js';
+import { getEnvMethod, getEnvSettings } from '../core/environments.js';
+import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
+
+/** @typedef {'preDeploy'|'postDeploy'|'rollback'} HookStage */
+
+/** @type {HookStage[]} */
+export const HOOK_STAGES = ['preDeploy', 'postDeploy', 'rollback'];
+
+const SSH_BASED_METHODS = new Set(['ssh', 'ec2', 'azure-vm', 'gcp-vm']);
+
+/**
+ * @param {unknown} command
+ * @returns {boolean}
+ */
+export function commandLooksSensitive(command) {
+  const c = String(command || '');
+  if (/(?:^|\s)(--password|--passwd|--secret|--token|--api-key)(?:=|\s+)\S+/i.test(c)) {
+    return true;
+  }
+  // `-p secret` but not `-p 22` (SSH port) or `-p22`.
+  if (/(?:^|\s)-p\s+(?!-)(?!\d+\b)\S+/.test(c)) {
+    return true;
+  }
+  if (/(?:PASSWORD|SECRET_ACCESS_KEY|SECRET|TOKEN|API_KEY)\s*=\s*\S+/i.test(c)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} command
+ * @returns {string}
+ */
+export function formatHookCommandForLog(command) {
+  if (commandLooksSensitive(command)) {
+    return '<command withheld — possible credential in hook string>';
+  }
+  return command;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ command: string, continueOnError: boolean, reconnect: boolean, timeoutMs?: number }[]}
+ */
+function normalizeHookList(raw) {
+  if (!Array.isArray(raw)) return [];
+  /** @type {{ command: string, continueOnError: boolean, reconnect: boolean, timeoutMs?: number }[]} */
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const command = /** @type {Record<string, unknown>} */ (item).command;
+    if (typeof command !== 'string' || !command.trim()) continue;
+    const timeoutRaw = /** @type {Record<string, unknown>} */ (item).timeoutMs;
+    const timeoutMs =
+      typeof timeoutRaw === 'number' && Number.isFinite(timeoutRaw) && timeoutRaw > 0
+        ? timeoutRaw
+        : undefined;
+    out.push({
+      command: command.trim(),
+      continueOnError: /** @type {Record<string, unknown>} */ (item).continueOnError === true,
+      reconnect: /** @type {Record<string, unknown>} */ (item).reconnect === true,
+      ...(timeoutMs != null ? { timeoutMs } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, unknown>} [settings]
+ * @returns {{ preDeploy: ReturnType<typeof normalizeHookList>, postDeploy: ReturnType<typeof normalizeHookList>, rollback: ReturnType<typeof normalizeHookList> }}
+ */
+export function getEnvHooks(settings = {}) {
+  const raw = settings.hooks;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { preDeploy: [], postDeploy: [], rollback: [] };
+  }
+  const h = /** @type {Record<string, unknown>} */ (raw);
+  return {
+    preDeploy: normalizeHookList(h.preDeploy),
+    postDeploy: normalizeHookList(h.postDeploy),
+    rollback: normalizeHookList(h.rollback),
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} [settings]
+ * @returns {boolean}
+ */
+export function envHasAnyHooks(settings = {}) {
+  const h = getEnvHooks(settings);
+  return h.preDeploy.length + h.postDeploy.length + h.rollback.length > 0;
+}
+
+/**
+ * @param {string|undefined} method
+ * @param {Record<string, unknown>} [settings]
+ * @returns {boolean}
+ */
+export function hooksSupportedForMethod(method, settings = {}) {
+  if (SSH_BASED_METHODS.has(String(method || ''))) return true;
+  if (method === 'docker') {
+    return resolveDockerRemoteMode(settings) === 'ssh';
+  }
+  return false;
+}
+
+/**
+ * Throw if hooks are configured on a method that cannot run them.
+ * No-op when no hooks are set (additive — existing deploys unchanged).
+ *
+ * @param {string|undefined} method
+ * @param {Record<string, unknown>} [settings]
+ * @param {string} [envName]
+ */
+export function assertHooksAllowed(method, settings = {}, envName = 'this environment') {
+  if (!envHasAnyHooks(settings)) return;
+  if (hooksSupportedForMethod(method, settings)) return;
+
+  let why;
+  if (method === 'kubernetes') {
+    why =
+      'Kubernetes deploys via kubectl, not a persistent remote SSH session.';
+  } else if (method === 'docker') {
+    why =
+      `Docker remote.mode "${resolveDockerRemoteMode(settings)}" has no DeployHub-managed SSH session (hooks require remote.mode "ssh").`;
+  } else {
+    why = `Method "${method}" does not support remote shell hooks.`;
+  }
+  throw new Error(
+    `Hooks are configured for environment "${envName}" but are not supported: ${why} ` +
+      `Remove environments.${envName}.config.hooks or use ssh / ec2 / azure-vm / gcp-vm / docker (remote.mode ssh).`
+  );
+}
+
+/**
+ * Run one hook stage on an already-open SSH session.
+ *
+ * @param {{
+ *   session: { execUnchecked: Function, defaultExecTimeoutMs: number, reconnect?: Function },
+ *   ssh: unknown,
+ *   settings: Record<string, unknown>,
+ *   stage: HookStage,
+ * }} opts
+ * @returns {Promise<unknown>} the SSH connection to keep using (replaced after reconnect)
+ */
+export async function runDeployHooks(opts) {
+  let { session, ssh, settings, stage } = opts;
+  const list = getEnvHooks(settings)[stage] || [];
+  if (list.length === 0) return ssh;
+
+  const log = createLogger(`hook:${stage}`);
+  for (const hook of list) {
+    const timeoutMs = hook.timeoutMs ?? session.defaultExecTimeoutMs;
+    log.info(`$ ${formatHookCommandForLog(hook.command)}`);
+
+    /** @type {{ code?: number|null, stdout?: string, stderr?: string }} */
+    let result;
+    try {
+      result = await session.execUnchecked(ssh, hook.command, {
+        timeoutMs,
+        logCommand: false,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const timedOut = /timed out after/i.test(msg);
+      const wrapped = timedOut
+        ? `${stage} hook timed out after ${timeoutMs}ms`
+        : `${stage} hook failed: ${msg}`;
+      if (hook.continueOnError) {
+        log.warn(wrapped);
+        continue;
+      }
+      log.error(wrapped);
+      throw new Error(wrapped);
+    }
+
+    const out = String(result.stdout || '').trim();
+    if (out) {
+      for (const line of out.split(/\r?\n/)) {
+        log.info(line);
+      }
+    }
+
+    if (result.code !== 0 && result.code !== null && result.code !== undefined) {
+      const failure = formatRemoteCommandFailure(
+        hook.command,
+        result.code,
+        result.stderr,
+        result.stdout
+      );
+      const wrapped = `${stage} hook failed: ${failure}`;
+      if (hook.continueOnError) {
+        log.warn(wrapped);
+        continue;
+      }
+      log.error(wrapped);
+      throw new Error(wrapped);
+    }
+
+    if (hook.reconnect) {
+      log.info('Reconnecting SSH session after hook...');
+      if (typeof session.reconnect !== 'function') {
+        throw new Error(
+          `${stage} hook reconnect failed: SSH session does not support reconnect`
+        );
+      }
+      try {
+        ssh = await session.reconnect(ssh);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const wrapped = `${stage} hook reconnect failed: ${msg}`;
+        log.error(wrapped);
+        throw new Error(wrapped);
+      }
+    }
+  }
+  return ssh;
+}
+
+/**
+ * Informational doctor lines — pass: true, never blocks.
+ *
+ * @param {Record<string, unknown>} config
+ * @returns {{ name: string, pass: boolean, message: string }[]}
+ */
+export function getHooksDoctorChecks(config) {
+  const envs = /** @type {Record<string, unknown>} */ (config.environments || {});
+  /** @type {{ name: string, pass: boolean, message: string }[]} */
+  const checks = [];
+  for (const [name, entry] of Object.entries(envs)) {
+    const settings = getEnvSettings(entry);
+    if (!envHasAnyHooks(settings)) continue;
+    const h = getEnvHooks(settings);
+    const parts = [];
+    if (h.preDeploy.length) parts.push(`${h.preDeploy.length} preDeploy`);
+    if (h.postDeploy.length) parts.push(`${h.postDeploy.length} postDeploy`);
+    if (h.rollback.length) parts.push(`${h.rollback.length} rollback`);
+    const method = getEnvMethod(entry);
+    const supported = hooksSupportedForMethod(method, settings);
+    checks.push({
+      name: `Hooks (${name})`,
+      pass: true,
+      message: supported
+        ? `Hooks configured for '${name}': ${parts.join(', ')}`
+        : `Hooks configured for '${name}' (${parts.join(', ')}) but ${method} does not run them — remove config.hooks or use an SSH-based method`,
+    });
+  }
+  return checks;
+}
+
+export default {
+  HOOK_STAGES,
+  commandLooksSensitive,
+  formatHookCommandForLog,
+  getEnvHooks,
+  envHasAnyHooks,
+  hooksSupportedForMethod,
+  assertHooksAllowed,
+  runDeployHooks,
+  getHooksDoctorChecks,
+};

package/src/deployment/index.js

@@ -8,7 +8,9 @@ import { createLogger } from '../logger/index.js';
 import {
   getEnabledEnvironmentNames,
   getEnvMethod,
+  getEnvSettings,
 } from '../core/environments.js';
+import { assertHooksAllowed } from './hooks.js';
 import { applyEnvSecretOverlay } from './deployment-env.js';
 import { recordEnvDeployment } from '../storage/index.js';
 import { buildArtifactRemoteKey } from '../utils/build-id.js';
@@ -81,6 +83,7 @@ export async function deployToAll(config, artifactDir, envNames) {
     }
 
     const method = getEnvMethod(envConfig);
+    assertHooksAllowed(method, getEnvSettings(envConfig), envName);
     const provider = getDeploymentProvider(method, config, envName);
     log.info(`Deploying to ${envName} (${method})...`);
     await provider.deploy(artifactDir);
@@ -128,7 +131,9 @@ export async function rollbackAll(config, artifactDir, envNames, meta) {
   const targets = envNames || getEnabledEnvironmentNames(config);
   for (const envName of targets) {
     const envConfig = config.environments[envName];
-    const provider = getDeploymentProvider(getEnvMethod(envConfig), config, envName);
+    const method = getEnvMethod(envConfig);
+    assertHooksAllowed(method, getEnvSettings(envConfig), envName);
+    const provider = getDeploymentProvider(method, config, envName);
     await provider.rollback(artifactDir, meta);
   }
 }

package/src/deployment/init-prompts.js

@@ -153,7 +153,137 @@ export async function promptServerDeployment(
   }
 
   const triggerMeta = await promptTriggerAndBranch(options);
-  return { ...methodAnswers, ...triggerMeta };
+  const hookMeta = await promptDeployHooksIfSupported(deployType, methodAnswers);
+  return { ...methodAnswers, ...triggerMeta, ...hookMeta };
+}
+
+/**
+ * Optional pre/post/rollback commands. Skipped unless the method has a
+ * DeployHub-managed SSH session (ssh / ec2 / azure-vm / gcp-vm / docker-ssh).
+ *
+ * @param {string} deployType
+ * @param {Record<string, unknown>} methodAnswers
+ */
+async function promptDeployHooksIfSupported(deployType, methodAnswers) {
+  const sshBased = SSH_BASED.includes(deployType);
+  const dockerSsh = deployType === 'docker' && methodAnswers.remoteMode === 'ssh';
+  if (!sshBased && !dockerSsh) {
+    return {};
+  }
+  return promptDeployHooks();
+}
+
+/**
+ * Collect zero or more commands for one hook stage. First confirm defaults
+ * to no (skippable). "Add another?" also defaults to no. No cap — the
+ * executor already runs the array in order.
+ *
+ * @param {{
+ *   firstConfirmName: string,
+ *   firstMessage: string,
+ *   anotherMessage: string,
+ *   commandMessage: string,
+ *   abortMessage: string,
+ *   abortDefault: boolean,
+ * }} opts
+ * @returns {Promise<{ command: string, continueOnError: boolean }[]>}
+ */
+async function promptHookStageCommands(opts) {
+  const firstName = opts.firstConfirmName;
+  const firstAnswers = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: firstName,
+      message: opts.firstMessage,
+      default: false,
+    },
+  ]);
+  if (!firstAnswers[firstName]) return [];
+
+  /** @type {{ command: string, continueOnError: boolean }[]} */
+  const list = [];
+  for (;;) {
+    const { command, abortOnFailure, reconnect } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'command',
+        message: opts.commandMessage,
+        validate: (input) =>
+          String(input || '').trim() ? true : 'Enter a command to run on the remote host.',
+      },
+      {
+        type: 'confirm',
+        name: 'abortOnFailure',
+        message: opts.abortMessage,
+        default: opts.abortDefault,
+      },
+      {
+        type: 'confirm',
+        name: 'reconnect',
+        message:
+          'Does this command require reconnecting the SSH session afterward? (e.g. it changes group membership or shell environment)',
+        default: false,
+      },
+    ]);
+    /** @type {{ command: string, continueOnError: boolean, reconnect?: boolean }} */
+    const entry = {
+      command: String(command).trim(),
+      continueOnError: abortOnFailure !== true,
+    };
+    if (reconnect === true) entry.reconnect = true;
+    list.push(entry);
+
+    const { addAnother } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'addAnother',
+        message: opts.anotherMessage,
+        default: false,
+      },
+    ]);
+    if (!addAnother) break;
+  }
+  return list;
+}
+
+/**
+ * @returns {Promise<{ hooks?: Record<string, { command: string, continueOnError: boolean }[]> }>}
+ */
+export async function promptDeployHooks() {
+  /** @type {Record<string, { command: string, continueOnError: boolean }[]>} */
+  const hooks = {};
+
+  const preDeploy = await promptHookStageCommands({
+    firstConfirmName: 'addPreDeploy',
+    firstMessage: 'Add a pre-deploy command? (e.g. run migrations)',
+    anotherMessage: 'Add another pre-deploy command?',
+    commandMessage: 'Pre-deploy command:',
+    abortMessage: 'Abort deploy if this command fails?',
+    abortDefault: true,
+  });
+  if (preDeploy.length) hooks.preDeploy = preDeploy;
+
+  const postDeploy = await promptHookStageCommands({
+    firstConfirmName: 'addPostDeploy',
+    firstMessage: 'Add a post-deploy command? (e.g. clear cache, notify)',
+    anotherMessage: 'Add another post-deploy command?',
+    commandMessage: 'Post-deploy command:',
+    abortMessage: 'Abort deploy if this command fails?',
+    abortDefault: false,
+  });
+  if (postDeploy.length) hooks.postDeploy = postDeploy;
+
+  const rollback = await promptHookStageCommands({
+    firstConfirmName: 'addRollback',
+    firstMessage: 'Add a rollback command? (e.g. reverse migration)',
+    anotherMessage: 'Add another rollback command?',
+    commandMessage: 'Rollback command:',
+    abortMessage: 'Abort rollback if this command fails?',
+    abortDefault: true,
+  });
+  if (rollback.length) hooks.rollback = rollback;
+
+  return Object.keys(hooks).length > 0 ? { hooks } : {};
 }
 
 /**
@@ -754,6 +884,7 @@ export function buildServerEnvEntry(
     if (Number.isInteger(n) && n >= 1 && n <= 65535) {
       settings.port = n;
     }
+    attachHooksFromAnswers(settings, deployAnswers);
     return withTriggerAndBranch(
       {
         enabled: true,
@@ -799,6 +930,7 @@ export function buildServerEnvEntry(
     settings.path = settings.deployPath;
   }
 
+  attachHooksFromAnswers(settings, deployAnswers);
   return withTriggerAndBranch(
     {
       enabled: true,
@@ -810,6 +942,20 @@ export function buildServerEnvEntry(
   );
 }
 
+/**
+ * Copy optional hook answers onto the env method config.
+ * @param {Record<string, unknown>} settings
+ * @param {Record<string, unknown>} deployAnswers
+ */
+function attachHooksFromAnswers(settings, deployAnswers) {
+  const raw = deployAnswers && deployAnswers.hooks;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return;
+  const hooks = /** @type {Record<string, unknown>} */ (raw);
+  if (hooks.preDeploy || hooks.postDeploy || hooks.rollback) {
+    settings.hooks = hooks;
+  }
+}
+
 /**
  * Overlay prompt answers onto the env entry. `--yes` / missing answers keep
  * trigger `manual` and omit `branch` (backward compatible).

package/src/deployment/providers/docker.js

@@ -5,6 +5,7 @@ import { resolveDockerImageRefForTag } from '../../utils/docker-image.js';
 import { resolveDockerContainerName } from '../../utils/docker-container-name.js';
 import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environments.js';
 import { createSshExecSession } from '../ssh-connection.js';
+import { assertHooksAllowed, runDeployHooks } from '../hooks.js';
 import { resolveDockerRemoteMode } from '../../utils/docker-remote-mode.js';
 import {
   resolveDockerSshTarget,
@@ -63,9 +64,10 @@ export function createDockerProvider(config, envName, env = process.env) {
 
   /**
    * @param {string} artifactDir
-   * @param {{ fullImage?: string, skipImageReuse?: boolean }} [options]
+   * @param {{ fullImage?: string, skipImageReuse?: boolean, isRollback?: boolean }} [options]
    */
   async function deploy(artifactDir, options = {}) {
+    assertHooksAllowed('docker', settings, envName);
     const imageRef = options.fullImage || fullImage;
     log.info(`Deploying via Docker (image: ${imageRef})...`);
 
@@ -88,7 +90,9 @@ export function createDockerProvider(config, envName, env = process.env) {
       if (publishPort == null) {
         throw new Error(formatDockerSshPortRequired(envName));
       }
-      await deployOverSsh(imageRef, publishPort);
+      await deployOverSsh(imageRef, publishPort, {
+        isRollback: options.isRollback === true,
+      });
       log.success('Docker deployment complete');
       return;
     }
@@ -151,16 +155,25 @@ export function createDockerProvider(config, envName, env = process.env) {
   /**
    * @param {string} imageRef
    * @param {number} port
+   * @param {{ isRollback?: boolean }} [options]
    */
-  async function deployOverSsh(imageRef, port) {
+  async function deployOverSsh(imageRef, port, options = {}) {
+    const isRollback = options.isRollback === true;
     const cmds = buildRemoteDockerCommands(imageRef, containerName, {}, { publishPort: port });
     const session = sshSession();
-    const ssh = await session.connect();
+    let ssh = await session.connect();
     try {
       const registryUser = imageEnv.DOCKER_REGISTRY_USERNAME || '';
       const registryToken = imageEnv.DOCKER_REGISTRY_TOKEN || '';
       const registryUrl = imageEnv.DOCKER_REGISTRY_URL || '';
 
+      ssh = await runDeployHooks({
+        session,
+        ssh,
+        settings,
+        stage: isRollback ? 'rollback' : 'preDeploy',
+      });
+
       if (registryUser && registryToken) {
         const registry = registryUrl || 'https://index.docker.io/v1/';
         log.info('Logging in to container registry on remote host...');
@@ -192,6 +205,10 @@ export function createDockerProvider(config, envName, env = process.env) {
       if (verdict.reason === 'published') {
         log.info(verdict.message);
       }
+
+      if (!isRollback) {
+        ssh = await runDeployHooks({ session, ssh, settings, stage: 'postDeploy' });
+      }
     } finally {
       ssh.dispose();
     }
@@ -220,6 +237,7 @@ export function createDockerProvider(config, envName, env = process.env) {
     await deploy(artifactDir, {
       fullImage: rollbackImage,
       skipImageReuse: true,
+      isRollback: true,
     });
   }
 

package/src/deployment/providers/ssh.js

@@ -2,6 +2,7 @@ import path from 'path';
 import { createLogger } from '../../logger/index.js';
 import { getEnvSettings } from '../../core/config.js';
 import { createSshExecSession } from '../ssh-connection.js';
+import { runDeployHooks } from '../hooks.js';
 import {
   getNginxSitesAvailablePath,
   getNginxSitesEnabledPath,
@@ -540,9 +541,12 @@ export function createSshProvider(config, envName, env = process.env) {
 
   /**
    * @param {string} artifactDir
+   * @param {{ isRollback?: boolean }} [options]
    */
-  async function deploy(artifactDir) {
-    const ssh = await connect();
+  async function deploy(artifactDir, options = {}) {
+    const isRollback = options.isRollback === true;
+    const preStage = isRollback ? 'rollback' : 'preDeploy';
+    let ssh = await connect();
     const projectType = config.projectType || 'frontend';
 
     try {
@@ -555,33 +559,40 @@ export function createSshProvider(config, envName, env = process.env) {
 
       if (projectType === 'both') {
         const remoteStaging = `/tmp/deployhub-staging-${Date.now()}`;
-        await exec(ssh, `mkdir -p ${sh(remoteStaging)}`);
-        await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(remoteStaging)}`);
-
-        await ensureWritableDeployDir(ssh, frontendDeployPath);
-        await exec(
-          ssh,
-          `rsync -a ${sh(remoteStaging)}/ ${sh(frontendDeployPath)}/ --exclude backend || cp -r ${sh(remoteStaging)}/* ${sh(frontendDeployPath)}/`
-        );
-
-        await ensureWritableDeployDir(ssh, backendDeployPath);
-        await exec(
-          ssh,
-          `rsync -a ${sh(remoteStaging)}/backend/ ${sh(backendDeployPath)}/ || cp -r ${sh(remoteStaging)}/backend/* ${sh(backendDeployPath)}/`
-        );
-
-        if (await remoteFileExists(ssh, `${frontendDeployPath}/nginx.conf`)) {
-          await setupNginx(ssh, frontendDeployPath);
+        try {
+          await exec(ssh, `mkdir -p ${sh(remoteStaging)}`);
+          await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(remoteStaging)}`);
+
+          ssh = await runDeployHooks({ session, ssh, settings, stage: preStage });
+
+          await ensureWritableDeployDir(ssh, frontendDeployPath);
+          await exec(
+            ssh,
+            `rsync -a ${sh(remoteStaging)}/ ${sh(frontendDeployPath)}/ --exclude backend || cp -r ${sh(remoteStaging)}/* ${sh(frontendDeployPath)}/`
+          );
+
+          await ensureWritableDeployDir(ssh, backendDeployPath);
+          await exec(
+            ssh,
+            `rsync -a ${sh(remoteStaging)}/backend/ ${sh(backendDeployPath)}/ || cp -r ${sh(remoteStaging)}/backend/* ${sh(backendDeployPath)}/`
+          );
+
+          if (await remoteFileExists(ssh, `${frontendDeployPath}/nginx.conf`)) {
+            await setupNginx(ssh, frontendDeployPath);
+          }
+
+          await runBackendStartSequence(ssh, backendDeployPath);
+        } finally {
+          await exec(ssh, `rm -rf ${sh(remoteStaging)}`).catch(() => {});
         }
-
-        await runBackendStartSequence(ssh, backendDeployPath);
-        await exec(ssh, `rm -rf ${sh(remoteStaging)}`);
       } else if (projectType === 'backend') {
         log.info(`Backend deploy path: ${deployPath}`);
+        ssh = await runDeployHooks({ session, ssh, settings, stage: preStage });
         await extractToPath(ssh, remoteZip, deployPath);
         await runBackendStartSequence(ssh, deployPath);
       } else {
         log.info(`Frontend deploy path: ${deployPath}`);
+        ssh = await runDeployHooks({ session, ssh, settings, stage: preStage });
         await extractToPath(ssh, remoteZip, deployPath);
 
         const framework = config.framework || 'react';
@@ -592,6 +603,10 @@ export function createSshProvider(config, envName, env = process.env) {
         }
       }
 
+      if (!isRollback) {
+        ssh = await runDeployHooks({ session, ssh, settings, stage: 'postDeploy' });
+      }
+
       await exec(ssh, `rm -f ${sh(remoteZip)}`);
       log.success('Deployment complete');
     } finally {
@@ -609,7 +624,7 @@ export function createSshProvider(config, envName, env = process.env) {
   }
 
   async function rollback(artifactDir, _meta) {
-    await deploy(artifactDir);
+    await deploy(artifactDir, { isRollback: true });
   }
 
   async function healthCheck() {

package/src/deployment/ssh-connection.js

@@ -71,14 +71,42 @@ export function createSshExecSession(opts) {
     return ssh;
   }
 
+  /**
+   * Close the current connection and open a new one with the same host/user/key.
+   * Used after a successful hook with `reconnect: true` (e.g. usermod -aG).
+   * Never returns the old session — on failure the previous connection is already closed.
+   *
+   * @param {import('node-ssh').NodeSSH} [oldSsh]
+   */
+  async function reconnect(oldSsh) {
+    try {
+      oldSsh?.dispose();
+    } catch {
+      // already closed
+    }
+    try {
+      const next = await connect();
+      log.info(`Reconnected SSH session to ${user}@${host}:${sshPort}`);
+      return next;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `SSH reconnect failed to ${user}@${host}:${sshPort} — ${msg}. ` +
+          'The previous session was closed; a new connection could not be opened.'
+      );
+    }
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} command
-   * @param {{ timeoutMs?: number }} [execOpts]
+   * @param {{ timeoutMs?: number, logCommand?: boolean }} [execOpts]
    */
   async function runCommand(ssh, command, execOpts = {}) {
     const timeoutMs = execOpts.timeoutMs ?? defaultExecTimeoutMs;
-    log.info(`$ ${command}`);
+    if (execOpts.logCommand !== false) {
+      log.info(`$ ${command}`);
+    }
 
     /** @type {ReturnType<typeof setTimeout> | undefined} */
     let timer;
@@ -106,7 +134,7 @@ export function createSshExecSession(opts) {
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} command
-   * @param {{ timeoutMs?: number }} [execOpts]
+   * @param {{ timeoutMs?: number, logCommand?: boolean }} [execOpts]
    */
   async function exec(ssh, command, execOpts = {}) {
     const result = await runCommand(ssh, command, execOpts);
@@ -129,7 +157,7 @@ export function createSshExecSession(opts) {
    *
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} command
-   * @param {{ timeoutMs?: number }} [execOpts]
+   * @param {{ timeoutMs?: number, logCommand?: boolean }} [execOpts]
    */
   async function execUnchecked(ssh, command, execOpts = {}) {
     return runCommand(ssh, command, execOpts);
@@ -137,6 +165,7 @@ export function createSshExecSession(opts) {
 
   return {
     connect,
+    reconnect,
     exec,
     execUnchecked,
     host,