vibecarbon 0.1.0

package/src/restore.js

@@ -0,0 +1,871 @@
+/**
+ * Vibecarbon Restore Command
+ *
+ * Interactive-by-default. Bare `vibecarbon restore` walks the operator
+ * through env selection → source selection → confirm → restore.
+ * Positional and flag seeds skip the corresponding prompt. `-l` lists
+ * available backups for an env without restoring (the read-only path
+ * that was missing from the old CLI).
+ *
+ * `-source <name-or-path>` subsumes the old `--file` / `--from-s3` split:
+ * if the value resolves to an existing local file, treat it as a local
+ * upload-and-restore; otherwise validate as an S3 backup name and
+ * restore from S3.
+ *
+ * Form rule: vibecarbon uses single-dash flags only — see
+ * memory:feedback_cli_single_dash_flags.
+ */
+
+import { existsSync, unlinkSync } from 'node:fs';
+import { basename, 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 { 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,
+  scpUpload,
+  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: 'restore',
+  summary: 'Restore a database from a backup',
+  positional: [
+    {
+      name: 'env',
+      optional: true,
+      description: 'Environment to restore (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 available backups (read-only; does not restore)',
+    },
+    { name: 'env', value: '<name>', description: 'Environment seed (alternative to positional)' },
+    {
+      name: 'source',
+      value: '<file-or-name-or-latest>',
+      description: 'Backup source: local file path, S3 backup name, or `latest`',
+    },
+  ],
+  examples: [
+    { command: 'vibecarbon restore', description: 'prompts for env and backup' },
+    { command: 'vibecarbon restore prod -l', description: 'list available backups for prod' },
+    {
+      command: 'vibecarbon restore prod -source myapp_20260507.tar.gz',
+      description: 'restore a specific backup from S3',
+    },
+    {
+      command: 'vibecarbon restore prod -source ./backup.tar.gz -y',
+      description: 'restore from a local file, skipping confirmation',
+    },
+    {
+      command: 'vibecarbon restore prod -y -source latest',
+      description: 'restore the most-recent S3 backup, non-interactively',
+    },
+  ],
+};
+
+// ============================================================================
+// KUBECTL HELPERS (k8s mode)
+// ============================================================================
+
+function listRemoteBackups(ip, sshKeyPath) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+
+  try {
+    const output = sshKubectl(ip, sshKeyPath, [
+      'exec',
+      '-n',
+      'vibecarbon',
+      pod,
+      '--',
+      'sh',
+      '-c',
+      'ls -lt /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 [];
+  }
+}
+
+// ============================================================================
+// RESTORE OPERATIONS (k8s mode)
+// ============================================================================
+
+function scaleDownApp(ip, sshKeyPath) {
+  sshKubectl(ip, sshKeyPath, ['scale', 'deployment', 'app', '-n', 'vibecarbon', '--replicas=0']);
+
+  try {
+    sshKubectl(ip, sshKeyPath, [
+      'rollout',
+      'status',
+      'deployment/app',
+      '-n',
+      'vibecarbon',
+      '--timeout=60s',
+    ]);
+  } catch {
+    // Continue even if timeout
+  }
+}
+
+function scaleUpApp(ip, sshKeyPath) {
+  sshKubectl(ip, sshKeyPath, ['scale', 'deployment', 'app', '-n', 'vibecarbon', '--replicas=2']);
+}
+
+function verifyPostgres(ip, sshKeyPath) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+  sshKubectl(ip, sshKeyPath, [
+    'exec',
+    '-n',
+    'vibecarbon',
+    pod,
+    '--',
+    'pg_isready',
+    '-U',
+    'postgres',
+  ]);
+}
+
+/**
+ * Restore from a full archive (.tar.gz containing postgres.sql.gz + optional storage.tar.gz)
+ */
+function restoreFromArchive(ip, sshKeyPath, remotePath) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+
+  // Extract the archive on the server — argv form; remotePath is never shell-interpolated.
+  sshRun(ip, sshKeyPath, ['mkdir', '-p', '/tmp/restore']);
+  // GNU tar strips leading `/` by default (no `-P` / `--absolute-names`),
+  // so absolute paths in a hostile archive never escape /tmp/restore.
+  sshRun(ip, sshKeyPath, [
+    'tar',
+    '--no-xattrs',
+    '--no-same-owner',
+    '-xzf',
+    remotePath,
+    '-C',
+    '/tmp/restore',
+  ]);
+
+  // Check archive contents
+  const contents = sshRun(ip, sshKeyPath, ['ls', '/tmp/restore/']);
+
+  // Restore database
+  if (contents.includes('postgres.sql.gz')) {
+    sshKubectl(ip, sshKeyPath, [
+      'cp',
+      '/tmp/restore/postgres.sql.gz',
+      `vibecarbon/${pod}:/tmp/postgres.sql.gz`,
+    ]);
+    sshKubectl(ip, sshKeyPath, [
+      'exec',
+      '-n',
+      'vibecarbon',
+      pod,
+      '--',
+      'sh',
+      '-c',
+      'gunzip -c /tmp/postgres.sql.gz | psql -U supabase_admin postgres',
+    ]);
+    sshKubectl(ip, sshKeyPath, [
+      'exec',
+      '-n',
+      'vibecarbon',
+      pod,
+      '--',
+      'rm',
+      '-f',
+      '/tmp/postgres.sql.gz',
+    ]);
+  }
+
+  // Restore storage files if present and using file backend
+  if (contents.includes('storage.tar.gz')) {
+    // kubectl get returns empty string if STORAGE_BACKEND env var is unset;
+    // default to 'file' so the legacy single-backend path still works.
+    let storageBackend;
+    try {
+      storageBackend = sshKubectl(ip, sshKeyPath, [
+        'get',
+        'deployment',
+        'storage',
+        '-n',
+        'vibecarbon',
+        '-o',
+        'jsonpath={.spec.template.spec.containers[0].env[?(@.name=="STORAGE_BACKEND")].value}',
+      ]);
+    } catch {
+      storageBackend = 'file';
+    }
+    if (!storageBackend) storageBackend = 'file';
+
+    if (storageBackend === 'file') {
+      const storagePod = sshKubectl(ip, sshKeyPath, [
+        'get',
+        'pods',
+        '-n',
+        'vibecarbon',
+        '-l',
+        'app.kubernetes.io/name=supabase-storage',
+        '-o',
+        'jsonpath={.items[0].metadata.name}',
+      ]);
+
+      sshKubectl(ip, sshKeyPath, [
+        'cp',
+        '/tmp/restore/storage.tar.gz',
+        `vibecarbon/${storagePod}:/tmp/storage.tar.gz`,
+      ]);
+      sshKubectl(ip, sshKeyPath, [
+        'exec',
+        '-n',
+        'vibecarbon',
+        storagePod,
+        '--',
+        'sh',
+        '-c',
+        'tar --no-xattrs --no-same-owner -xzf /tmp/storage.tar.gz -C / && rm -f /tmp/storage.tar.gz',
+      ]);
+    } else {
+      p.log.info('Storage backend is S3 — skipping file restore (files already in S3)');
+    }
+  }
+
+  // Cleanup
+  sshRun(ip, sshKeyPath, ['rm', '-rf', '/tmp/restore']);
+}
+
+/**
+ * Restore from a legacy .sql.gz file (database only)
+ */
+function restoreFromSqlGz(ip, sshKeyPath, backupName) {
+  const pod = getPostgresPod(ip, sshKeyPath);
+
+  // backupName is validated via validateBackupFilename at entry; still pass it
+  // as a positional sh arg so the remote shell never expands it as code.
+  sshKubectl(ip, sshKeyPath, [
+    'exec',
+    '-n',
+    'vibecarbon',
+    pod,
+    '--',
+    'sh',
+    '-c',
+    'gunzip -c "/backups/$1" | psql -U supabase_admin postgres',
+    '_',
+    backupName,
+  ]);
+}
+
+async function restoreFromRemote(ip, sshKeyPath, backupName) {
+  scaleDownApp(ip, sshKeyPath);
+
+  if (backupName.endsWith('_full.tar.gz')) {
+    restoreFromArchive(ip, sshKeyPath, `/tmp/${backupName}`);
+  } else {
+    restoreFromSqlGz(ip, sshKeyPath, backupName);
+  }
+
+  scaleUpApp(ip, sshKeyPath);
+  verifyPostgres(ip, sshKeyPath);
+}
+
+async function uploadAndRestore(ip, sshKeyPath, localFile) {
+  const filename = basename(localFile);
+
+  // Upload local file to server
+  scpUpload(ip, sshKeyPath, localFile, `/tmp/${filename}`);
+
+  scaleDownApp(ip, sshKeyPath);
+
+  if (filename.endsWith('_full.tar.gz')) {
+    restoreFromArchive(ip, sshKeyPath, `/tmp/${filename}`);
+  } else if (filename.endsWith('.sql.gz')) {
+    const pod = getPostgresPod(ip, sshKeyPath);
+    sshKubectl(ip, sshKeyPath, [
+      'cp',
+      `/tmp/${filename}`,
+      `vibecarbon/${pod}:/backups/${filename}`,
+    ]);
+    restoreFromSqlGz(ip, sshKeyPath, filename);
+  }
+
+  // Clean up temp file on host
+  sshRun(ip, sshKeyPath, ['rm', '-f', `/tmp/${filename}`]);
+
+  scaleUpApp(ip, sshKeyPath);
+  verifyPostgres(ip, sshKeyPath);
+}
+
+// ============================================================================
+// SOURCE INTERPRETATION
+// ============================================================================
+
+/**
+ * The `-source` flag accepts either a local file path or an S3 backup
+ * name. Existence on disk is the signal: if the value resolves to a
+ * file we treat it as upload-and-restore; otherwise we validate as an
+ * S3 backup name and restore from S3.
+ *
+ * @param {string} source
+ * @returns {{ kind: 'local', path: string, name: string } | { kind: 's3', name: string }}
+ */
+function classifySource(source) {
+  if (existsSync(source)) {
+    return { kind: 'local', path: source, name: basename(source) };
+  }
+  // Not a local path — assume S3 backup name. Validate format up front
+  // so downstream code can trust it.
+  const err = validateBackupFilename(source);
+  if (err) {
+    p.log.error(`Invalid -source: ${err}`);
+    p.log.info(
+      `Expected a local file path or S3 backup name (e.g. myapp_20260507_120000_full.tar.gz)`,
+    );
+    process.exit(1);
+  }
+  return { kind: 's3', name: source };
+}
+
+// ============================================================================
+// 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 restore -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;
+  }
+
+  // Project guard runs before banner so an accidental `vibecarbon
+  // restore` from a parent directory emits the canonical message.
+  assertInProjectDir();
+
+  requireLicense('restore');
+  printBanner();
+  p.intro(`${c.bold('vibecarbon restore')} ${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;
+
+  // Top-level TTY guard: env prompt fires if multi-env and no seed.
+  // Source-prompt requirements gate after the env is resolved (since
+  // the picker depends on which backups exist for the env).
+  requireTTYOrFlags({
+    requirements: [
+      {
+        flag: 'env',
+        description: 'name an environment to restore',
+        satisfied: !!envSeed || envCount <= 1,
+      },
+    ],
+  });
+
+  const { envName, envConfig } = await selectEnvironment(projectConfig, {
+    actionVerb: 'restore',
+    seed: envSeed,
+  });
+
+  const serverIp = envConfig.servers?.[0]?.ip;
+  if (!serverIp) {
+    p.log.error(`No server IP found for environment '${envName}'.`);
+    process.exit(1);
+  }
+
+  // Source TTY guard fires *before* infrastructure checks so the
+  // off-TTY error message is "needs -source" rather than "SSH key
+  // not found" — the latter would correctly diagnose a different
+  // problem but obscures what the operator actually needs to fix
+  // for a scripted invocation.
+  if (!values.l && !values.source) {
+    requireTTYOrFlags({
+      requirements: [
+        {
+          flag: 'source',
+          description: 'name the backup to restore (S3 name or local file path)',
+          satisfied: false,
+        },
+      ],
+    });
+  }
+
+  // Operator-IP firewall refresh — the listing path needs SSH/k8s
+  // reachability too (we may fall back to a pod-list when S3 isn't
+  // configured), so we run this regardless of -l.
+  const apiToken = loadCredentials()?.hetzner?.apiToken;
+  if (apiToken) {
+    try {
+      const isHA = envConfig.deployMode === 'compose-ha' || !!envConfig.ha?.enabled;
+      const result = await ensureOperatorIpAccess({
+        projectConfig,
+        environment: envName,
+        isHA,
+        apiToken,
+        yes: !!values.y,
+        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);
+    }
+  }
+
+  // SSH key is required for everything restore touches.
+  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 restore operations.',
+    );
+    process.exit(1);
+  }
+
+  const projectName = projectConfig.projectName || 'project';
+  const isCompose = envConfig.deployMode === 'compose' || envConfig.deployMode === 'compose-ha';
+
+  // -l: list-only path. Read-only; print and exit.
+  if (values.l) {
+    await runList({ isCompose, envName, projectName, serverIp, sshKeyPath });
+    p.outro('');
+    return;
+  }
+
+  // Resolve mode-specific S3 config + the chosen backup source.
+  const s3 = await resolveS3({ isCompose, envName, projectName });
+  const useS3 = Boolean(s3?.secretKey);
+
+  // `-source latest` is a non-interactive sentinel that routes through the
+  // same auto-pick path the interactive prompt uses under `-y` — the newest
+  // S3 backup wins. Lets scripted callers (e2e, post-incident
+  // restores) ask for "the most recent" without first listing + parsing
+  // names from `vibecarbon backup -l`.
+  const wantsLatest = values.source === 'latest';
+  const chosenSource =
+    !wantsLatest && values.source
+      ? classifySource(/** @type {string} */ (values.source))
+      : await pickInteractiveSource({
+          isCompose,
+          envName,
+          projectName,
+          serverIp,
+          sshKeyPath,
+          s3,
+          useS3,
+          yes: wantsLatest || !!values.y,
+        });
+
+  if (!chosenSource) {
+    p.log.error('No backup selected.');
+    process.exit(1);
+  }
+
+  // Confirmation gates
+  p.log.warn('This will overwrite the current database!');
+  p.log.message(`  ${c.dim('Environment'.padEnd(14))} ${c.bold(envName)}`);
+  p.log.message(`  ${c.dim('Server'.padEnd(14))} ${c.bold(serverIp)}`);
+  p.log.message(`  ${c.dim('Backup'.padEnd(14))} ${c.bold(chosenSource.name)}`);
+
+  if (!values.y) {
+    const confirm = await p.confirm({
+      message: `Restore ${c.bold(chosenSource.name)} to ${c.bold(envName)}?`,
+    });
+    if (p.isCancel(confirm) || !confirm) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+
+    if (envName === 'prod' || envName === 'production') {
+      const doubleConfirm = await p.text({
+        message: `Type "${envName}" to confirm restoration of production database:`,
+        validate: (v) => (v !== envName ? `Please type "${envName}" to confirm` : undefined),
+      });
+      if (p.isCancel(doubleConfirm)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+      }
+    }
+  }
+
+  // Dispatch by mode
+  const tracker = createTracker('restore', { environment: envName });
+  const s = tracker.spinner();
+
+  try {
+    if (isCompose) {
+      await runComposeRestore({
+        s,
+        chosenSource,
+        envName,
+        projectName,
+        serverIp,
+        sshKeyPath,
+        s3WithCreds: s3,
+      });
+    } else {
+      await runK8sRestore({
+        s,
+        chosenSource,
+        envName,
+        serverIp,
+        sshKeyPath,
+        s3,
+        useS3,
+      });
+    }
+  } catch (error) {
+    s.stop('Restore failed');
+    p.log.error(error.message);
+    if (!isCompose) {
+      p.log.warn('The app deployment may need to be manually scaled back up:');
+      p.log.info(
+        `  ssh root@${serverIp} "kubectl scale deployment app -n vibecarbon --replicas=2"`,
+      );
+    }
+    process.exit(1);
+  }
+
+  tracker.finish();
+  p.outro(c.success('Done'));
+}
+
+// ============================================================================
+// ORCHESTRATION HELPERS
+// ============================================================================
+
+async function resolveS3({ 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 };
+  }
+  const backupS3 = loadBackupS3Config(envName);
+  const storageS3 = loadS3Config(envName);
+  let s3 = backupS3 || storageS3;
+  if (s3 && !s3.secretKey) {
+    const creds = await getS3Credentials(projectName, { save: false });
+    if (creds) {
+      s3 = { ...s3, accessKey: creds.accessKey, secretKey: creds.secretKey };
+    }
+  }
+  return s3;
+}
+
+async function runList({ isCompose, envName, projectName, serverIp, sshKeyPath }) {
+  const s3 = await resolveS3({ isCompose, envName, projectName });
+  const useS3 = Boolean(s3?.secretKey);
+
+  if (useS3) {
+    try {
+      const backups = await listS3Backups(s3);
+      printBackupList(backups, envName);
+    } catch (error) {
+      p.log.error(`Failed to list S3 backups: ${error.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (isCompose) {
+    try {
+      const output = sshRunScript(
+        serverIp,
+        sshKeyPath,
+        `ls -lt /opt/${projectName}/backups/*_full.tar.gz 2>/dev/null || echo NO_BACKUPS`,
+      );
+      if (output === 'NO_BACKUPS' || !output.trim()) {
+        p.log.info('No backups found.');
+        p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+        return;
+      }
+      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) {
+      p.log.error(`Failed to list backups: ${error.message}`);
+    }
+    return;
+  }
+
+  // K8s pod fallback
+  const backups = listRemoteBackups(serverIp, sshKeyPath);
+  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 pickInteractiveSource({
+  isCompose,
+  envName,
+  projectName,
+  serverIp,
+  sshKeyPath,
+  s3,
+  useS3,
+  yes,
+}) {
+  const tracker = createTracker('restore.pickSource', { environment: envName });
+  const s = tracker.spinner();
+
+  if (useS3) {
+    s.start('Fetching available backups from S3');
+    const backups = await listS3Backups(s3);
+    s.stop('Backups retrieved');
+    if (backups.length === 0) {
+      p.log.error('No backups found in S3.');
+      p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+      process.exit(1);
+    }
+    if (yes) {
+      const latest = backups[0].name;
+      p.log.info(`Auto-selected latest backup: ${c.bold(latest)}`);
+      return { kind: 's3', name: latest };
+    }
+    const selected = await p.select({
+      message: 'Select backup to restore:',
+      options: backups.map((b) => ({
+        value: b.name,
+        label: b.name,
+        hint: `${b.size} — ${b.date}`,
+      })),
+    });
+    if (p.isCancel(selected)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+    return { kind: 's3', name: /** @type {string} */ (selected) };
+  }
+
+  // Non-S3 fallback: list from server filesystem (compose) or pod (k8s).
+  if (isCompose) {
+    s.start('Listing available backups');
+    const output = sshRunScript(
+      serverIp,
+      sshKeyPath,
+      `ls -t /opt/${projectName}/backups/*_full.tar.gz 2>/dev/null || echo NO_BACKUPS`,
+    );
+    s.stop('');
+    if (output === 'NO_BACKUPS' || !output.trim()) {
+      p.log.error('No backups found on the server.');
+      p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+      process.exit(1);
+    }
+    const names = output
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((f) => basename(f));
+    if (yes) {
+      const latest = names[0];
+      p.log.info(`Auto-selected latest backup: ${c.bold(latest)}`);
+      return { kind: 's3', name: latest };
+    }
+    const selected = await p.select({
+      message: 'Select backup to restore:',
+      options: names.map((b) => ({ value: b, label: b })),
+    });
+    if (p.isCancel(selected)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+    return { kind: 's3', name: /** @type {string} */ (selected) };
+  }
+
+  // K8s pod fallback
+  s.start('Fetching available backups');
+  const backups = listRemoteBackups(serverIp, sshKeyPath);
+  s.stop('Backups retrieved');
+  if (backups.length === 0) {
+    p.log.error('No backups found on the server.');
+    p.log.info(`Create one with: ${c.info(`vibecarbon backup ${envName}`)}`);
+    process.exit(1);
+  }
+  if (yes) {
+    const latest = backups[0].name;
+    p.log.info(`Auto-selected latest backup: ${c.bold(latest)}`);
+    return { kind: 's3', name: latest };
+  }
+  const selected = await p.select({
+    message: 'Select backup to restore:',
+    options: backups.map((b) => ({ value: b.name, label: b.name, hint: `${b.size} — ${b.date}` })),
+  });
+  if (p.isCancel(selected)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+  return { kind: 's3', name: /** @type {string} */ (selected) };
+}
+
+async function runComposeRestore({
+  s,
+  chosenSource,
+  envName,
+  projectName,
+  serverIp,
+  sshKeyPath,
+  s3WithCreds,
+}) {
+  const backupFile = chosenSource.name;
+
+  if (chosenSource.kind === 'local') {
+    p.log.info(`Uploading local file: ${c.bold(chosenSource.path)}`);
+    scpUpload(serverIp, sshKeyPath, chosenSource.path, `/opt/${projectName}/backups/${backupFile}`);
+  } else if (s3WithCreds?.secretKey) {
+    s.start(`Downloading ${backupFile} from S3 to server`);
+    const tmpLocal = join(process.cwd(), `.restore-tmp-${backupFile}`);
+    try {
+      await downloadS3Backup(s3WithCreds, `backups/${backupFile}`, tmpLocal);
+      scpUpload(serverIp, sshKeyPath, tmpLocal, `/opt/${projectName}/backups/${backupFile}`);
+      try {
+        unlinkSync(tmpLocal);
+      } catch {
+        // ignore cleanup errors
+      }
+      s.stop('Backup transferred to server');
+    } catch (error) {
+      s.stop(`S3 download failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  s.start('Restoring database...');
+  const { restoreCompose } = await import('./lib/deploy/compose/index.js');
+  restoreCompose(serverIp, sshKeyPath, projectName, backupFile);
+  s.stop('Database restored');
+  p.log.success('Restore completed successfully');
+  // env name is unused by restoreCompose but kept in the closure for
+  // diagnostic logging consistency.
+  void envName;
+}
+
+async function runK8sRestore({ s, chosenSource, envName, serverIp, sshKeyPath, s3, useS3 }) {
+  s.start('Restoring database (app will be temporarily unavailable)');
+
+  if (chosenSource.kind === 'local') {
+    if (!chosenSource.path.endsWith('.sql.gz') && !chosenSource.path.endsWith('.tar.gz')) {
+      throw new Error('Backup file must be a .sql.gz or .tar.gz file');
+    }
+    await perfAsync('restore.uploadAndRestore', () =>
+      uploadAndRestore(serverIp, sshKeyPath, chosenSource.path),
+    );
+    s.stop('Database restored');
+  } else if (useS3) {
+    s.message('Downloading backup from S3');
+    const tempPath = join(process.cwd(), `.restore-tmp-${chosenSource.name}`);
+    await perfAsync('restore.downloadS3', () =>
+      downloadS3Backup(s3, `backups/${chosenSource.name}`, tempPath),
+    );
+    s.message('Uploading backup to server');
+    await perfAsync('restore.scpUpload', async () =>
+      scpUpload(serverIp, sshKeyPath, tempPath, `/tmp/${chosenSource.name}`),
+    );
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // ignore cleanup errors
+    }
+    s.message('Restoring database');
+    await perfAsync('restore.restoreFromRemote', () =>
+      restoreFromRemote(serverIp, sshKeyPath, chosenSource.name),
+    );
+    s.stop('Database restored');
+  } else {
+    // Pod-only fallback: backup name refers to a file already in the pod.
+    await restoreFromRemote(serverIp, sshKeyPath, chosenSource.name);
+    s.stop('Database restored');
+  }
+
+  p.log.success('Restore completed successfully');
+  p.log.info('The application has been scaled back up.');
+  p.log.info(`Verify with: ${c.info(`vibecarbon status ${envName}`)}`);
+}
+
+// ============================================================================
+// EXPORTS FOR TESTING
+// ============================================================================
+
+export { SPEC };