vibecarbon 0.1.0

package/src/backup.js

@@ -0,0 +1,786 @@
+/**
+ * Vibecarbon Backup Command
+ *
+ * Interactive-by-default. Bare `vibecarbon backup` walks the operator
+ * through env → action prompts; positional and flag seeds skip the
+ * corresponding prompt. Off-TTY usage requires explicit flags up front
+ * (the TTY guard names exactly which ones).
+ *
+ * Form rule: vibecarbon uses single-dash flags only — see
+ * memory:feedback_cli_single_dash_flags.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { downloadS3Backup, listS3Backups } from './lib/backup-s3.js';
+import { renderHelp } from './lib/cli/help.js';
+import { parseFlags } from './lib/cli/parse-flags.js';
+import { selectAction } from './lib/cli/select-action.js';
+import { selectEnvironment } from './lib/cli/select-environment.js';
+import { requireTTYOrFlags } from './lib/cli/tty-guard.js';
+import { c, printBanner } from './lib/colors.js';
+import {
+  loadBackupS3Config,
+  loadCredentials,
+  loadProjectConfig,
+  loadS3Config,
+} from './lib/config.js';
+import { getS3Credentials } from './lib/hetzner-guided-setup.js';
+import { requireLicense } from './lib/licensing/index.js';
+import { ensureOperatorIpAccess } from './lib/operator-ip.js';
+import { perfAsync } from './lib/perf.js';
+import { assertInProjectDir } from './lib/project-guard.js';
+import {
+  getPostgresPod,
+  getSSHKeyPath,
+  scpDownload,
+  sshKubectl,
+  sshRun,
+  sshRunScript,
+} from './lib/ssh.js';
+import { createTracker } from './lib/tracker.js';
+import { validateBackupFilename } from './lib/validators.js';
+import { VERSION } from './lib/version.js';
+
+// ============================================================================
+// COMMAND SPEC — single source of truth for argv parsing AND help output.
+// ============================================================================
+
+/** @type {import('./lib/cli/parse-flags.js').CommandSpec & { summary?: string, examples?: Array<{ command: string, description?: string }> }} */
+const SPEC = {
+  name: 'backup',
+  summary: 'Create or manage database backups',
+  positional: [
+    {
+      name: 'env',
+      optional: true,
+      description: 'Environment to act on (skips the env prompt)',
+    },
+  ],
+  flags: [
+    { name: 'h', boolean: true, description: 'Show this help' },
+    { name: 'v', boolean: true, description: 'Show version' },
+    { name: 'y', boolean: true, description: 'Skip confirmation prompts' },
+    {
+      name: 'l',
+      boolean: true,
+      description: 'List backups (read-only; equivalent to -action list)',
+    },
+    { name: 'env', value: '<name>', description: 'Environment seed (alternative to positional)' },
+    {
+      name: 'action',
+      value: '<verb>',
+      enum: ['create', 'list', 'download'],
+      description: 'Action seed (skips the action prompt)',
+    },
+    {
+      name: 'source',
+      value: '<file>',
+      description: 'Backup filename (required for non-interactive download)',
+    },
+  ],
+  examples: [
+    { command: 'vibecarbon backup', description: 'prompts for env and action' },
+    { command: 'vibecarbon backup prod -l', description: 'list backups for prod' },
+    { command: 'vibecarbon backup prod', description: 'env seeded; prompts for action' },
+    {
+      command: 'vibecarbon backup -env prod -action download -source myapp_20260507.tar.gz',
+      description: 'scripted download',
+    },
+  ],
+};
+
+const ACTION_CHOICES = [
+  { value: 'create', label: 'Create a new backup', hint: 'triggers a fresh dump' },
+  { value: 'list', label: 'List existing backups', hint: 'read-only' },
+  { value: 'download', label: 'Download a backup', hint: 'fetch a file locally' },
+];
+
+// ============================================================================
+// LEGACY POD HELPERS (used when a k8s env has no S3 configured)
+// ============================================================================
+
+async function listPodBackups(ip, sshKeyPath) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+
+  try {
+    const output = sshKubectl(ip, sshKeyPath, [
+      'exec',
+      '-n',
+      'vibecarbon',
+      pod,
+      '--',
+      'sh',
+      '-c',
+      'ls -lhS /backups/*_full.tar.gz /backups/*.sql.gz 2>/dev/null || echo NO_BACKUPS',
+    ]);
+
+    if (output === 'NO_BACKUPS' || !output) {
+      return [];
+    }
+
+    return output
+      .split('\n')
+      .filter((line) => line.includes('.tar.gz') || line.includes('.sql.gz'))
+      .map((line) => {
+        const parts = line.split(/\s+/);
+        return {
+          size: parts[4],
+          date: `${parts[5]} ${parts[6]} ${parts[7]}`,
+          name: parts[parts.length - 1].replace('/backups/', ''),
+        };
+      });
+  } catch {
+    return [];
+  }
+}
+
+async function downloadPodBackup(ip, sshKeyPath, filename) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+
+  // Copy from pod to host
+  sshKubectl(ip, sshKeyPath, ['cp', `vibecarbon/${pod}:/backups/${filename}`, `/tmp/${filename}`]);
+
+  // SCP from host to local
+  const localPath = join(process.cwd(), filename);
+  scpDownload(ip, sshKeyPath, `/tmp/${filename}`, localPath);
+
+  // Clean up remote temp file
+  sshRun(ip, sshKeyPath, ['rm', '-f', `/tmp/${filename}`]);
+
+  return localPath;
+}
+
+// ============================================================================
+// K8S JOB BACKUP (triggers CronJob-based backup)
+// ============================================================================
+
+function triggerBackupJob(ip, sshKeyPath) {
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[:.]/g, '-')
+    .replace('T', '-')
+    .slice(0, 19)
+    .toLowerCase();
+  const jobName = `backup-manual-${timestamp}`;
+
+  // Create a one-off Job from the CronJob template
+  sshKubectl(ip, sshKeyPath, [
+    'create',
+    'job',
+    `--from=cronjob/backup`,
+    jobName,
+    '-n',
+    'vibecarbon',
+  ]);
+
+  // Poll the Job's conditions every 5s for either Complete=True or
+  // Failed=True. We avoid `kubectl wait --for=condition=Complete
+  // --timeout=300s` because the wait can only watch ONE condition, so on
+  // a CrashLoopBackOff that ends in Failed it would burn the FULL 5 min
+  // before timing out. By that point kubelet had GC'd the failed Pod
+  // (observed 2026-04-28 e2e — the Pod was visible in events but
+  // kubectl get returned nothing, so the diagnostic captured no logs).
+  // Polling for both conditions returns within ~5s of Failed, while
+  // the Pod is still alive and its logs are still kubectl-reachable.
+  // CRITICAL: capture pod logs and describe IN-LINE the moment Failed=True
+  // is detected. Doing this in a follow-up SSH session race-loses to Pod GC
+  // (observed iter-reliab2 2026-05-01: Job condition Failed but follow-up
+  // diagnostic returned "No pod matching" because controller-manager already
+  // GC'd the failed Pod within the ~1s window between SSH sessions).
+  try {
+    sshRunScript(
+      ip,
+      sshKeyPath,
+      `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+DEADLINE=$(($(date +%s) + 300))
+RESULT="timeout"
+while [ $(date +%s) -lt $DEADLINE ]; do
+  CONDS=$(kubectl get job ${jobName} -n vibecarbon -o jsonpath='{range .status.conditions[*]}{.type}={.status};{end}' 2>/dev/null || echo "")
+  case "$CONDS" in
+    *"Complete=True"*) RESULT="complete"; break ;;
+    *"Failed=True"*) RESULT="failed"; break ;;
+  esac
+  sleep 5
+done
+echo "JOB_RESULT=$RESULT"
+if [ "$RESULT" = "complete" ]; then
+  exit 0
+fi
+# Capture diagnostics WHILE pod is still alive — controller GCs failed
+# Job pods quickly after the Failed condition fires.
+echo ""
+echo "=== INLINE FAILURE DIAGNOSTICS (captured before pod GC) ==="
+echo "=== Job status ==="
+kubectl get job ${jobName} -n vibecarbon -o yaml 2>&1 | grep -E "^  (active|conditions|failed|ready|succeeded|terminating)|^    " | head -30
+echo ""
+echo "=== All pods in namespace ==="
+kubectl get pods -n vibecarbon -o wide 2>&1
+echo ""
+echo "=== Pod events (matching ${jobName} or backup-manual) ==="
+kubectl get events -n vibecarbon --field-selector involvedObject.kind=Pod --sort-by=.lastTimestamp 2>&1 | grep -E "${jobName}|backup-manual" | tail -30
+echo ""
+PODS=$(kubectl get pods -n vibecarbon -o name 2>/dev/null | grep "${jobName}" || true)
+if [ -z "\${PODS}" ]; then
+  echo "=== No pod matching ${jobName} found — already GC'd ==="
+else
+  for pod in \${PODS}; do
+    echo "=== \${pod}: container statuses (exit code disambiguates failure) ==="
+    kubectl get \${pod} -n vibecarbon -o jsonpath='restartCount={.status.containerStatuses[*].restartCount}{"\\n"}lastTerminated={.status.containerStatuses[*].lastState.terminated}{"\\n"}currentState={.status.containerStatuses[*].state}{"\\n"}' 2>&1
+    echo ""
+    echo "=== \${pod}: kubectl describe ==="
+    kubectl describe \${pod} -n vibecarbon 2>&1 | tail -60
+    echo "=== \${pod}: current container logs ==="
+    kubectl logs \${pod} -n vibecarbon --tail=200 2>&1 || true
+    echo "=== \${pod}: --previous logs (the crashed-container output) ==="
+    kubectl logs \${pod} -n vibecarbon --previous --tail=200 2>&1 || true
+  done
+fi
+exit 1`,
+      { timeout: 420_000 },
+    );
+  } catch (waitErr) {
+    // Dump pod status, events, AND logs to help diagnose why the job didn't
+    // complete. An earlier version of this block gated the --previous log
+    // capture on a label-selector query that mysteriously returned "No
+    // resources found" while the same pod was visible by name in events
+    // (observed 2026-04-28 k8s e2e). Now we find pods by NAME
+    // pattern instead — Job-managed pods are guaranteed to be named
+    // `<jobName>-<5char>` so a `grep ${jobName}` over the unfiltered pod
+    // list always works. We also capture exit codes via jsonpath (works
+    // even when both current+previous logs are empty — exit code 126/127/
+    // SIGKILL alone disambiguates "image bad / OOMKilled / segfault") and
+    // run kubectl describe for runtime context that bare logs miss.
+    let podDiag = '';
+    try {
+      podDiag = sshRunScript(
+        ip,
+        sshKeyPath,
+        `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+echo "=== CronJob image ==="
+kubectl get cronjob backup -n vibecarbon -o jsonpath="{.spec.jobTemplate.spec.template.spec.containers[0].image}" 2>&1
+echo ""
+echo "=== Job status ==="
+kubectl get job ${jobName} -n vibecarbon -o yaml 2>&1 | grep -E "^  (active|conditions|failed|ready|succeeded|terminating)|^    " | head -30
+echo "=== All pods in namespace (no label filter) ==="
+kubectl get pods -n vibecarbon -o wide 2>&1
+echo "=== Pod events (last 30) ==="
+kubectl get events -n vibecarbon --field-selector involvedObject.kind=Pod --sort-by=.lastTimestamp 2>&1 | grep -E "${jobName}|backup-manual" | tail -30
+# Find pods by NAME pattern (not label) — labels on freshly-failed Job pods
+# can return empty even when the pod exists; name pattern matches because
+# Job pods are deterministically named <jobName>-<5char>.
+PODS=$(kubectl get pods -n vibecarbon -o name 2>/dev/null | grep "${jobName}" || true)
+if [ -z "\${PODS}" ]; then
+  echo "=== No pod matching ${jobName} found — already GC'd? ==="
+else
+  for pod in \${PODS}; do
+    echo "=== \${pod}: container statuses (exit code disambiguates the failure) ==="
+    kubectl get \${pod} -n vibecarbon -o jsonpath='restartCount={.status.containerStatuses[*].restartCount}{"\\n"}lastTerminated={.status.containerStatuses[*].lastState.terminated}{"\\n"}currentState={.status.containerStatuses[*].state}{"\\n"}' 2>&1
+    echo ""
+    echo "=== \${pod}: kubectl describe ==="
+    kubectl describe \${pod} -n vibecarbon 2>&1 | tail -50
+    echo "=== \${pod}: current container logs ==="
+    kubectl logs \${pod} -n vibecarbon --tail=100 2>&1 || true
+    echo "=== \${pod}: --previous logs (the crashed-container output) ==="
+    kubectl logs \${pod} -n vibecarbon --previous --tail=100 2>&1 || true
+  done
+fi`,
+        { timeout: 90_000 },
+      );
+    } catch {
+      podDiag = '(diagnostic SSH failed)';
+    }
+    throw new Error(
+      `Backup job ${jobName} did not complete:\n${podDiag}\n\nkubectl wait error: ${waitErr.message}`,
+    );
+  }
+
+  return jobName;
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+export async function run(args) {
+  const { values, positional, errors } = parseFlags(args, SPEC);
+
+  if (errors.length > 0) {
+    for (const e of errors) {
+      process.stderr.write(`${c.error('✗')} ${e}\n`);
+    }
+    process.stderr.write(`Run ${c.info('vibecarbon backup -h')} for usage.\n`);
+    process.exit(1);
+  }
+
+  if (values.h) {
+    process.stdout.write(renderHelp(SPEC));
+    return;
+  }
+  if (values.v) {
+    console.log(`vibecarbon v${VERSION}`);
+    return;
+  }
+
+  // Validate -source format up front — all downstream code trusts it.
+  if (values.source) {
+    const err = validateBackupFilename(/** @type {string} */ (values.source));
+    if (err) {
+      process.stderr.write(`${c.error('✗')} Invalid -source: ${err}\n`);
+      process.exit(1);
+    }
+  }
+
+  // Project guard runs before banner so an accidental `vibecarbon
+  // backup` from a parent directory emits the canonical message.
+  assertInProjectDir();
+
+  requireLicense('backup');
+  printBanner();
+  p.intro(`${c.bold('vibecarbon backup')} ${c.dim(`v${VERSION}`)}`);
+
+  const projectConfig = loadProjectConfig();
+  const envCount = Object.keys(projectConfig.environments || {}).length;
+  // Positional wins over flag when both are supplied — bare-form is the
+  // canonical surface, the flag is the scripting alternative.
+  const envSeed =
+    /** @type {string|undefined} */ (positional.env) ||
+    /** @type {string|null} */ (values.env) ||
+    null;
+  // -l is shorthand for -action list; if both supplied, -l wins.
+  const actionSeed = values.l ? 'list' : /** @type {string|null} */ (values.action);
+
+  // TTY guard for the env + action prompts. Action-specific prompts
+  // (confirm-on-create, source-on-download) get their own gate after
+  // the action is known, so the failure message names exactly the
+  // flag the operator missed for *this* invocation.
+  requireTTYOrFlags({
+    requirements: [
+      {
+        flag: 'env',
+        description: 'name an environment to back up',
+        satisfied: !!envSeed || envCount <= 1,
+      },
+      {
+        flag: 'action',
+        description: 'choose an action (create, list, download — or pass -l for list)',
+        satisfied: !!actionSeed,
+      },
+    ],
+  });
+
+  const { envName, envConfig } = await selectEnvironment(projectConfig, {
+    actionVerb: 'back up',
+    seed: envSeed,
+  });
+
+  const serverIp = envConfig.servers?.[0]?.ip;
+  if (!serverIp) {
+    p.log.error(`No server IP found for environment '${envName}'.`);
+    process.exit(1);
+  }
+
+  const action = await selectAction({
+    message: `What do you want to do for ${c.bold(envName)}?`,
+    choices: ACTION_CHOICES,
+    seed: actionSeed,
+  });
+
+  // Operator-IP whitelist refresh happens before any command that
+  // touches the live cluster. Listing is read-only via S3 only when
+  // S3 is configured; if we'd fall back to pod-listing it still hits
+  // the cluster. Run the firewall check for everything except the
+  // S3-only list path (handled inside the dispatch below).
+  await ensureFirewallAccessIfNeeded({
+    action,
+    projectConfig,
+    envName,
+    envConfig,
+    yes: !!values.y,
+  });
+
+  // SSH key is required for everything (compose path AND k8s pod-list
+  // fallback). Bail early with a clear message if it's missing.
+  const sshKeyPath = getSSHKeyPath(envName);
+  if (!existsSync(sshKeyPath)) {
+    p.log.error(`SSH key not found: ${sshKeyPath}`);
+    p.log.info(
+      'The deployment key is created during deploy and is required for backup operations.',
+    );
+    process.exit(1);
+  }
+
+  // Action-specific TTY checks fire after we know the action so the
+  // missing-flag message is precise.
+  if (action === 'create' && !values.y) {
+    requireTTYOrFlags({
+      requirements: [{ flag: 'y', description: 'skip the confirmation prompt', satisfied: false }],
+    });
+  }
+  if (action === 'download' && !values.source) {
+    requireTTYOrFlags({
+      requirements: [
+        {
+          flag: 'source',
+          description: 'name the backup file to download',
+          satisfied: false,
+        },
+      ],
+    });
+  }
+
+  // Resolve mode + S3 config
+  const projectName = projectConfig.projectName || 'project';
+  const isCompose = envConfig.deployMode === 'compose' || envConfig.deployMode === 'compose-ha';
+  const s3Config = await resolveS3Config({ isCompose, envName, projectName });
+  const useS3 = Boolean(s3Config?.secretKey);
+
+  if (!isCompose) {
+    if (useS3) {
+      p.log.info(`S3 storage: ${c.dim(s3Config.bucket)} (${s3Config.region})`);
+    } else {
+      p.log.warn('No S3 storage configured — backups cannot be persisted.');
+      p.log.info(
+        `Configure S3 during deployment or with: ${c.info(`vibecarbon deploy ${envName}`)}`,
+      );
+      p.log.info('Without S3, backup data is lost when the Job pod terminates.');
+    }
+  }
+
+  const tracker = createTracker('backup', { environment: envName });
+  const s = tracker.spinner();
+
+  if (action === 'list') {
+    await runList({ s, isCompose, useS3, s3Config, serverIp, sshKeyPath, projectName, envName });
+    p.outro('');
+    return;
+  }
+
+  if (action === 'download') {
+    await runDownload({
+      s,
+      source: /** @type {string} */ (values.source),
+      isCompose,
+      useS3,
+      s3Config,
+      serverIp,
+      sshKeyPath,
+      projectName,
+    });
+    p.outro('');
+    return;
+  }
+
+  // action === 'create'
+  await runCreate({
+    s,
+    isCompose,
+    useS3,
+    s3Config,
+    serverIp,
+    sshKeyPath,
+    projectName,
+    envName,
+    yes: !!values.y,
+  });
+  tracker.finish();
+  p.outro(c.success('Done'));
+}
+
+// ============================================================================
+// ORCHESTRATION HELPERS
+// ============================================================================
+
+/**
+ * Refresh operator-IP firewall allowlist when the action would hit
+ * the cluster. Listing via S3 alone doesn't need this; everything
+ * else does.
+ */
+async function ensureFirewallAccessIfNeeded({ action, projectConfig, envName, envConfig, yes }) {
+  // Skip the firewall check for read-only list ops — they may hit
+  // S3 only (when configured), and even when they fall back to the
+  // pod, the existing key-based SSH already establishes access.
+  if (action === 'list') return;
+
+  const apiToken = loadCredentials()?.hetzner?.apiToken;
+  if (!apiToken) return;
+
+  try {
+    const isHA = envConfig.deployMode === 'compose-ha' || !!envConfig.ha?.enabled;
+    const result = await ensureOperatorIpAccess({
+      projectConfig,
+      environment: envName,
+      isHA,
+      apiToken,
+      yes,
+      onMessage: (msg) => p.log.info(msg),
+    });
+    if (result.added) {
+      p.log.success(`Firewall updated: SSH/k8s API now allow ${result.cidr}`);
+    }
+  } catch (err) {
+    p.log.error(`Operator-IP check failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** Resolve the S3 config for the deploy mode, merging credentials when needed. */
+async function resolveS3Config({ isCompose, envName, projectName }) {
+  if (isCompose) {
+    const backupS3 = loadBackupS3Config(envName);
+    if (!backupS3) return null;
+    const creds = await getS3Credentials(projectName, { save: false });
+    if (!creds) return null;
+    return { ...backupS3, accessKey: creds.accessKey, secretKey: creds.secretKey };
+  }
+
+  // K8s mode: prefer the dedicated backup bucket, fall back to
+  // storage. Either way, top up credentials from credentials.json
+  // when the config didn't carry them.
+  const backupS3 = loadBackupS3Config(envName);
+  const storageS3 = loadS3Config(envName);
+  let s3Config = backupS3 || storageS3;
+  if (s3Config && !s3Config.secretKey) {
+    const creds = await getS3Credentials(projectName, { save: false });
+    if (creds) {
+      s3Config = { ...s3Config, accessKey: creds.accessKey, secretKey: creds.secretKey };
+    }
+  }
+  return s3Config;
+}
+
+async function runList({
+  s,
+  isCompose,
+  useS3,
+  s3Config,
+  serverIp,
+  sshKeyPath,
+  projectName,
+  envName,
+}) {
+  s.start('Listing backups');
+
+  if (isCompose) {
+    if (useS3) {
+      try {
+        const backups = await listS3Backups(s3Config);
+        s.stop('Backups retrieved from S3');
+        printBackupList(backups, envName);
+      } catch (error) {
+        s.stop('Failed to list S3 backups');
+        p.log.error(error.message);
+      }
+    } else {
+      try {
+        const output = sshRunScript(
+          serverIp,
+          sshKeyPath,
+          `ls -lhS /opt/${projectName}/backups/*_full.tar.gz 2>/dev/null || echo NO_BACKUPS`,
+        );
+        s.stop('Backups retrieved');
+
+        if (output === 'NO_BACKUPS' || !output.trim()) {
+          p.log.info('No backups found.');
+          p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+        } else {
+          const lines = output.trim().split('\n').filter(Boolean);
+          p.log.info(`${c.bold(`Backups for ${envName}`)} (${lines.length} found):`);
+          for (const line of lines) {
+            p.log.message(`  ${line}`);
+          }
+        }
+      } catch (error) {
+        s.stop('Failed to list backups');
+        p.log.error(error.message);
+      }
+    }
+    return;
+  }
+
+  // K8s
+  if (useS3) {
+    try {
+      const backups = await listS3Backups(s3Config);
+      s.stop('Backups retrieved from S3');
+      printBackupList(backups, envName);
+    } catch (error) {
+      s.stop('Failed to list S3 backups');
+      p.log.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const backups = await listPodBackups(serverIp, sshKeyPath);
+  s.stop('Backups retrieved');
+  printBackupList(backups, envName);
+}
+
+function printBackupList(backups, envName) {
+  if (!backups || backups.length === 0) {
+    p.log.info('No backups found.');
+    p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+    return;
+  }
+  p.log.info(`${c.bold(`Backups for ${envName}`)} (${backups.length} found):`);
+  for (const backup of backups) {
+    p.log.message(`  ${c.dim(backup.date.padEnd(22))} ${backup.size.padStart(10)}  ${backup.name}`);
+  }
+}
+
+async function runDownload({
+  s,
+  source,
+  isCompose,
+  useS3,
+  s3Config,
+  serverIp,
+  sshKeyPath,
+  projectName,
+}) {
+  s.start(`Downloading ${source}`);
+  try {
+    if (isCompose) {
+      const localPath = join(process.cwd(), source);
+      if (useS3) {
+        await downloadS3Backup(s3Config, `backups/${source}`, localPath);
+      } else {
+        scpDownload(serverIp, sshKeyPath, `/opt/${projectName}/backups/${source}`, localPath);
+      }
+      s.stop('Download complete');
+      p.log.success(`Saved to ${c.bold(localPath)}`);
+      return;
+    }
+
+    // K8s
+    if (useS3) {
+      const localPath = join(process.cwd(), source);
+      await downloadS3Backup(s3Config, `backups/${source}`, localPath);
+      s.stop('Download complete');
+      p.log.success(`Saved to ${c.bold(localPath)}`);
+    } else {
+      const localPath = await downloadPodBackup(serverIp, sshKeyPath, source);
+      s.stop('Download complete');
+      p.log.success(`Saved to ${c.bold(localPath)}`);
+    }
+  } catch (error) {
+    s.stop('Download failed');
+    p.log.error(error.message);
+    process.exit(1);
+  }
+}
+
+async function runCreate({
+  s,
+  isCompose,
+  useS3,
+  s3Config,
+  serverIp,
+  sshKeyPath,
+  projectName,
+  envName,
+  yes,
+}) {
+  if (!yes) {
+    const confirm = await p.confirm({
+      message: `Create a database backup for ${c.bold(envName)} (${serverIp})?`,
+    });
+    if (p.isCancel(confirm) || !confirm) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  if (isCompose) {
+    s.start('Creating backup via Docker Compose...');
+    try {
+      const { backupCompose, uploadComposeBackupToS3 } = await import(
+        './lib/deploy/compose/index.js'
+      );
+      const backupFile = backupCompose(serverIp, sshKeyPath, projectName);
+      s.stop('Backup created');
+      p.log.success(`Backup: ${c.bold(backupFile)}`);
+      p.log.info(`Location: /opt/${projectName}/backups/${backupFile}`);
+
+      if (useS3) {
+        s.start('Uploading backup to S3...');
+        try {
+          await uploadComposeBackupToS3(serverIp, sshKeyPath, projectName, backupFile, s3Config);
+          s.stop(`Uploaded to S3: ${s3Config.bucket}/backups/${backupFile}`);
+        } catch (uploadError) {
+          s.stop(`S3 upload failed: ${uploadError.message}`);
+          p.log.warn('Backup is available on the server but was not uploaded to S3.');
+          // Dump the raw error to stderr so automation captures the
+          // actual AWS SDK error code + HTTP status — the spinner
+          // message above hides the detail e2e/CI needs.
+          console.error(
+            `[backup] S3 upload failed — name=${uploadError.name} code=${uploadError.Code ?? uploadError.code ?? 'n/a'} status=${uploadError.$metadata?.httpStatusCode ?? 'n/a'} bucket=${s3Config.bucket} endpoint=${s3Config.endpoint} region=${s3Config.region}`,
+          );
+          if (uploadError.stack) {
+            console.error(uploadError.stack);
+          }
+        }
+      } else {
+        p.log.info(`Download: scp root@${serverIp}:/opt/${projectName}/backups/${backupFile} .`);
+      }
+    } catch (error) {
+      s.stop('Backup failed');
+      p.log.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // K8s — trigger via CronJob template
+  s.start('Creating backup (triggering Kubernetes Job)');
+  try {
+    const jobName = await perfAsync('backup.triggerJob', async () =>
+      triggerBackupJob(serverIp, sshKeyPath),
+    );
+    s.stop('Backup created');
+
+    if (useS3) {
+      p.log.success(`Backup uploaded to S3: ${c.bold(s3Config.bucket)}/backups/`);
+      p.log.info(`Job: ${c.dim(jobName)}`);
+      p.log.info(`List backups: ${c.info(`vibecarbon backup ${envName} -l`)}`);
+    } else {
+      p.log.warn(`Backup Job ran: ${c.bold(jobName)}`);
+      p.log.warn('No S3 configured — backup was NOT persisted (lost when pod terminated).');
+      p.log.info('Configure S3 storage during deploy to enable persistent backups.');
+    }
+
+    // On a TTY, offer to download the freshly-created backup.
+    if (useS3 && !yes) {
+      const shouldDownload = await p.confirm({
+        message: 'Download the latest backup locally?',
+        initialValue: false,
+      });
+      if (shouldDownload && !p.isCancel(shouldDownload)) {
+        s.start('Fetching latest backup from S3');
+        const backups = await perfAsync('backup.listS3', () => listS3Backups(s3Config));
+        if (backups.length > 0) {
+          const latest = backups[0];
+          const localPath = join(process.cwd(), latest.name);
+          s.message(`Downloading ${latest.name} (${latest.size})`);
+          await perfAsync('backup.downloadS3', () =>
+            downloadS3Backup(s3Config, latest.key, localPath),
+          );
+          s.stop('Download complete');
+          p.log.success(`Saved to ${c.bold(localPath)}`);
+        } else {
+          s.stop('No backups found in S3 (backup may still be uploading).');
+        }
+      }
+    }
+  } catch (error) {
+    s.stop('Backup failed');
+    p.log.error(error.message);
+    process.exit(1);
+  }
+}
+
+// Re-export SPEC + parseFlags so existing parser tests can continue to
+// import a `parseArgs` symbol if any do; the canonical form is parseFlags.
+export { SPEC };