vibecarbon 0.5.0 → 0.6.0

package/src/create.js

@@ -1245,6 +1245,9 @@ ADMIN_PASSWORD=${escapeDotenv(variables.ADMIN_PASSWORD)}
 
 # Site URL
 SITE_URL="http://localhost:5173"
+# Public canonical URL baked into the client (og: tags, sitemap). Overridden at
+# deploy with the real apex domain; localhost is correct for local dev.
+VITE_PUBLIC_URL="http://localhost:5173"
 
 # =============================================================================
 # OAUTH PROVIDERS (optional)
@@ -1269,10 +1272,10 @@ STRIPE_WEBHOOK_SECRET=""
 
 # SMTP Email (shared by Supabase Auth and app transactional emails)
 SMTP_HOST=""
-SMTP_PORT=465
+SMTP_PORT=587
 SMTP_USER=""
 SMTP_PASS=""
-SMTP_ADMIN_EMAIL="noreply@example.com"
+SMTP_ADMIN_EMAIL=""
 SMTP_SENDER_NAME="${variables.PROJECT_NAME}"
 
 # =============================================================================

package/src/deploy.js

@@ -50,6 +50,7 @@ import {
   setupHA as setupHetznerDnsHA,
   setupSimple as setupHetznerDnsSimple,
 } from './lib/hetzner-dns.js';
+import { requireLicense } from './lib/licensing/index.js';
 import { detectPackageManager } from './lib/project.js';
 import { assertInProjectDir } from './lib/project-guard.js';
 import { HetznerS3Provider, sanitizeBucketName } from './lib/providers/hetzner-s3.js';
@@ -101,6 +102,11 @@ const SPEC = {
       value: '<id>',
       description: 'Primary Hetzner region (e.g. hel1, nbg1, fsn1)',
     },
+    {
+      name: 'standby-region',
+      value: '<id>',
+      description: 'HA standby/failover region (defaults to a same-continent partner of -region)',
+    },
     {
       name: 'mode',
       value: '<mode>',
@@ -155,11 +161,13 @@ function buildLegacyArgs(values, positional) {
     compose: mode === 'compose' || mode === 'compose-ha',
     k8s: mode === 'k8s' || mode === 'k8s-ha',
     ha: mode === 'compose-ha' || mode === 'k8s-ha',
+    // HA standby region — settable via -standby-region, else the interactive
+    // prompt / saved config / same-continent default fill it in.
+    secondaryRegion: values['standby-region'] || null,
     // Everything below is no longer settable via CLI flag; the
     // interactive prompt + `.vibecarbon.json` cover these. Defaults
     // keep gatherDeploymentConfig's `args.X || envConfig.X || …`
     // chains working unchanged.
-    secondaryRegion: null,
     serverType: null,
     masterServerType: null,
     workerServerType: null,
@@ -207,14 +215,23 @@ async function main() {
     process.exit(0);
   }
 
-  // 0a. Confirm we're inside a Vibecarbon project before doing anything
-  // that walks the tree. An accidental `vibecarbon deploy` from a parent
-  // directory (e.g. ~/repos) would otherwise scan every sibling repo and
-  // dump real tokens to the operator's scrollback before any "no project
-  // found" message could appear.
+  // 0a. Confirm we're inside a Vibecarbon project before anything else.
+  // assertInProjectDir() is the documented FIRST action for every
+  // project-scoped command (see lib/project-guard.js): an accidental
+  // `vibecarbon deploy` from a parent directory (e.g. ~/repos) must print
+  // the canonical "not in a project" message and exit non-zero — it must not
+  // fall through to the license upsell or a secret-scan that walks sibling
+  // repos. This matches scale/backup/restore/failover, which all assert
+  // first; deploy previously gated the license first and so exited 0 (the
+  // upsell path) outside a project, tripping the not-in-project contract.
   assertInProjectDir();
 
-  // 0b. Refuse to deploy if the working tree contains likely secrets.
+  // 0b. Deploying to production requires a paid license. Graphite (free)
+  // covers local create/up/test; deploy/scale/backup/etc. need Diamond+.
+  // Gate after the project check — help/version already returned above.
+  requireLicense('deploy');
+
+  // 0c. Refuse to deploy if the working tree contains likely secrets.
   // We push the project's tracked files to GitHub during deploy (CI,
   // GitOps, throwaway e2e repos), and a leak there is permanent
   // — GitHub's secret-scanner will email the user even if the repo is

package/src/destroy.js

@@ -837,7 +837,12 @@ async function main() {
 
   if (!projectConfig.environments || Object.keys(projectConfig.environments).length === 0) {
     // Check for orphan Pulumi stacks (deployment interrupted before config save)
+    const orphanScan = p.spinner();
+    orphanScan.start('Scanning for orphan Pulumi stacks...');
     const orphans = await findOrphanPulumiStacks(projectConfig);
+    orphanScan.stop(
+      orphans.length > 0 ? `Found ${orphans.length} orphan stack(s)` : 'No orphan stacks found',
+    );
 
     if (orphans.length > 0) {
       p.log.warn('No environments found in .vibecarbon.json');
@@ -906,15 +911,17 @@ async function main() {
         process.exit(1);
       }
 
+      const orphanSpinner = p.spinner();
       for (const orphan of orphans) {
+        orphanSpinner.start(`Destroying orphan stack ${c.bold(orphan.name)} (pulumi destroy)...`);
         try {
           await destroyOrphanPulumiStack(orphan, {
             apiToken: orphanApiToken,
             s3Config: orphanS3Config,
           });
-          p.log.success(`Destroyed: ${orphan.name}`);
+          orphanSpinner.stop(`Destroyed: ${orphan.name}`);
         } catch (error) {
-          p.log.error(`Failed to destroy ${orphan.name}: ${error.message}`);
+          orphanSpinner.error(`Failed to destroy ${orphan.name}: ${error.message}`);
         }
       }
 
@@ -1056,7 +1063,7 @@ ${c.danger('WARNING: All data on these servers will be permanently lost!')}
       try {
         if (envConfig.deployMode === 'compose' || envConfig.deployMode === 'compose-ha') {
           const { backupCompose } = await import('./lib/deploy/compose/index.js');
-          backupCompose(serverIp, sshKeyPath, projectConfig.projectName, {
+          await backupCompose(serverIp, sshKeyPath, projectConfig.projectName, {
             retain: envConfig.backup?.retentionDays,
           });
           backupSpinner.stop('wal-g base backup pushed to S3');
@@ -1215,7 +1222,7 @@ ${c.danger('WARNING: All data on these servers will be permanently lost!')}
       s.start('Stopping Docker Compose services...');
       try {
         const { destroyCompose } = await import('./lib/deploy/compose/index.js');
-        destroyCompose(serverIp, sshKeyPath, projectConfig.projectName);
+        await destroyCompose(serverIp, sshKeyPath, projectConfig.projectName);
         s.stop('Docker Compose services removed');
         results.servers.push(`vps-${serverIp}`);
       } catch (error) {

package/src/failover.js

@@ -18,7 +18,6 @@ import { selectEnvironment } from './lib/cli/select-environment.js';
 import { requireTTYOrFlags } from './lib/cli/tty-guard.js';
 import { createDNSRecord } from './lib/cloudflare.js';
 import { c, printBanner } from './lib/colors.js';
-import { runCommand } from './lib/command.js';
 import { loadCredentials, loadProjectConfig } from './lib/config.js';
 import {
   createDNSRecord as hetznerDnsCreateRecord,
@@ -150,10 +149,10 @@ export function identifyServers(envName, envConfig, _projectConfig) {
  * whether to attempt a pg_basebackup re-seed before promoting the standby.
  * Primary-dead failovers skip the re-seed (can't; best-effort promote).
  */
-function isPrimaryPostgresReady(primaryIp, sshKeyPath) {
+async function isPrimaryPostgresReady(primaryIp, sshKeyPath) {
   try {
-    const pod = getPostgresPod(primaryIp, sshKeyPath);
-    const result = sshKubectl(primaryIp, sshKeyPath, [
+    const pod = await getPostgresPod(primaryIp, sshKeyPath);
+    const result = await sshKubectl(primaryIp, sshKeyPath, [
       'exec',
       '-n',
       'vibecarbon',
@@ -184,31 +183,31 @@ function isPrimaryPostgresReady(primaryIp, sshKeyPath) {
  * true if re-seed succeeded, false if primary was unreachable or re-seed
  * itself failed (caller proceeds to promote with existing state).
  */
-function reseedStandbyFromPrimary(standbyIp, sshKeyPath, primarySupabaseIp) {
+async function reseedStandbyFromPrimary(standbyIp, sshKeyPath, primarySupabaseIp) {
   if (!primarySupabaseIp) return false;
   try {
     // REPL_PASSWORD is written to both primary and standby .env.local at
     // create time; read it from the standby's filesystem (easier than
     // threading through the failover args).
-    const replPassword = sshRun(standbyIp, sshKeyPath, [
+    const replPassword = await sshRun(standbyIp, sshKeyPath, [
       'bash',
       '-c',
       'grep -oE "^REPL_PASSWORD=[\\"\']?[^\\"\'\\n]+" /opt/*/.env.local 2>/dev/null | head -1 | sed -E "s/^REPL_PASSWORD=[\\"\']?//; s/[\\"\']?$//"',
     ]);
     if (!replPassword?.trim()) return false;
 
-    const pod = getPostgresPod(standbyIp, sshKeyPath);
+    const pod = await getPostgresPod(standbyIp, sshKeyPath);
     const script = [
       `rm -rf /var/lib/postgresql/data/*`,
       `PGPASSWORD='${replPassword.trim()}' pg_basebackup -h ${primarySupabaseIp} -p 5432 -U replicator -D /var/lib/postgresql/data -Fp -Xs -R -c fast -S vibecarbon_standby_slot`,
       `echo "primary_slot_name = 'vibecarbon_standby_slot'" >> /var/lib/postgresql/data/postgresql.auto.conf`,
       `chown -R postgres:postgres /var/lib/postgresql/data`,
     ].join('\n');
-    sshKubectl(standbyIp, sshKeyPath, ['exec', '-i', '-n', 'vibecarbon', pod, '--', 'bash'], {
+    await sshKubectl(standbyIp, sshKeyPath, ['exec', '-i', '-n', 'vibecarbon', pod, '--', 'bash'], {
       input: script,
     });
     // Restart the pod to pick up the new PGDATA + recovery config.
-    sshKubectl(standbyIp, sshKeyPath, [
+    await sshKubectl(standbyIp, sshKeyPath, [
       'exec',
       '-n',
       'vibecarbon',
@@ -225,22 +224,22 @@ function reseedStandbyFromPrimary(standbyIp, sshKeyPath, primarySupabaseIp) {
   }
 }
 
-function promoteStandbyDatabase(standbyIp, sshKeyPath) {
+async function promoteStandbyDatabase(standbyIp, sshKeyPath) {
   const _t = perfTimer('failover.promoteStandby');
   try {
-    return _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath);
+    return await _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath);
   } finally {
     _t.end();
   }
 }
 
-function _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath) {
+async function _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath) {
   // Get the postgres pod name via a separate SSH call (avoids local shell expansion of $())
-  const pod = getPostgresPod(standbyIp, sshKeyPath);
+  const pod = await getPostgresPod(standbyIp, sshKeyPath);
 
   // Promote PostgreSQL on standby
   try {
-    sshKubectl(standbyIp, sshKeyPath, [
+    await sshKubectl(standbyIp, sshKeyPath, [
       'exec',
       '-n',
       'vibecarbon',
@@ -258,7 +257,7 @@ function _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath) {
   // Poll until standby is no longer in recovery
   for (let i = 0; i < 30; i++) {
     try {
-      const result = sshKubectl(standbyIp, sshKeyPath, [
+      const result = await sshKubectl(standbyIp, sshKeyPath, [
         'exec',
         '-n',
         'vibecarbon',
@@ -274,16 +273,16 @@ function _promoteStandbyDatabaseImpl(standbyIp, sshKeyPath) {
     } catch {
       // Retry
     }
-    runCommand(['sleep', '2'], { silent: true, ignoreError: true });
+    await new Promise((r) => setTimeout(r, 2000));
   }
 
   return false;
 }
 
-function scaleUpServices(ip, sshKeyPath) {
+async function scaleUpServices(ip, sshKeyPath) {
   const _t = perfTimer('failover.scaleUpServices');
   try {
-    return _scaleUpServicesImpl(ip, sshKeyPath);
+    return await _scaleUpServicesImpl(ip, sshKeyPath);
   } finally {
     _t.end();
   }
@@ -317,10 +316,10 @@ const FAILOVER_DEPLOYMENTS = [
  * the whole failover. Reports each result so the operator can see what
  * actually scaled.
  */
-function scaleDeployments(ip, sshKeyPath, deployments, replicas, label) {
+async function scaleDeployments(ip, sshKeyPath, deployments, replicas, label) {
   for (const dep of deployments) {
     try {
-      sshKubectl(ip, sshKeyPath, [
+      await sshKubectl(ip, sshKeyPath, [
         'scale',
         'deployment',
         dep.name,
@@ -342,7 +341,7 @@ function scaleDeployments(ip, sshKeyPath, deployments, replicas, label) {
   }
 }
 
-function _scaleUpServicesImpl(ip, sshKeyPath) {
+async function _scaleUpServicesImpl(ip, sshKeyPath) {
   // Group by upReplicas so we don't touch the same deployment twice.
   const byReplicas = new Map();
   for (const dep of FAILOVER_DEPLOYMENTS) {
@@ -350,20 +349,26 @@ function _scaleUpServicesImpl(ip, sshKeyPath) {
     byReplicas.get(dep.upReplicas).push(dep);
   }
   for (const [replicas, deps] of byReplicas.entries()) {
-    scaleDeployments(ip, sshKeyPath, deps, replicas, `scale-up standby (replicas=${replicas})`);
+    await scaleDeployments(
+      ip,
+      sshKeyPath,
+      deps,
+      replicas,
+      `scale-up standby (replicas=${replicas})`,
+    );
   }
 }
 
-function waitForHealth(ip, sshKeyPath) {
+async function waitForHealth(ip, sshKeyPath) {
   const _t = perfTimer('failover.waitForHealth');
   try {
-    return _waitForHealthImpl(ip, sshKeyPath);
+    return await _waitForHealthImpl(ip, sshKeyPath);
   } finally {
     _t.end();
   }
 }
 
-function _waitForHealthImpl(ip, sshKeyPath) {
+async function _waitForHealthImpl(ip, sshKeyPath) {
   // The previous implementation curled http://localhost:3000/api/health from
   // the standby master — but K8s app pods don't run on the master's host
   // network (no hostPort:3000), so localhost:3000 has nothing listening and
@@ -373,7 +378,7 @@ function _waitForHealthImpl(ip, sshKeyPath) {
   // surfaces the real failure (ImagePullBackOff, CrashLoop, missing secret)
   // in the kubectl error rather than a generic timeout.
   try {
-    sshKubectl(ip, sshKeyPath, [
+    await sshKubectl(ip, sshKeyPath, [
       'rollout',
       'status',
       'deployment/app',
@@ -470,9 +475,9 @@ async function failoverHACloudflare(envName, envConfig, projectConfig, parsed, t
   // disaster failover) — promotion proceeds with whatever state standby
   // has. Requires primarySupabaseIp from identifyServers (persisted in
   // envConfig.servers by orchestrator.js post-deploy).
-  if (isPrimaryPostgresReady(servers.primary.ip, sshKeyPath)) {
+  if (await isPrimaryPostgresReady(servers.primary.ip, sshKeyPath)) {
     s.start('Re-seeding standby from primary (pg_basebackup)');
-    const reseeded = reseedStandbyFromPrimary(
+    const reseeded = await reseedStandbyFromPrimary(
       servers.standby.ip,
       sshKeyPath,
       servers.primary.supabaseIp,
@@ -484,7 +489,7 @@ async function failoverHACloudflare(envName, envConfig, projectConfig, parsed, t
 
   // Step 1: Promote standby database
   s.start('Promoting standby database');
-  const promoted = promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
+  const promoted = await promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
   s.stop(
     promoted
       ? 'Standby database promoted to primary'
@@ -499,13 +504,19 @@ async function failoverHACloudflare(envName, envConfig, projectConfig, parsed, t
   // scaleDeployments — don't abort the whole failover on one missing
   // chart name.
   s.start('Scaling down old primary services');
-  scaleDeployments(servers.primary.ip, sshKeyPath, FAILOVER_DEPLOYMENTS, 0, 'scale-down primary');
+  await scaleDeployments(
+    servers.primary.ip,
+    sshKeyPath,
+    FAILOVER_DEPLOYMENTS,
+    0,
+    'scale-down primary',
+  );
   s.stop('Old primary services scaled down');
 
   // Step 3: Scale up standby services
   s.start('Scaling up standby services');
   try {
-    scaleUpServices(servers.standby.ip, sshKeyPath);
+    await scaleUpServices(servers.standby.ip, sshKeyPath);
   } catch (error) {
     s.stop('Some services failed to scale');
     p.log.warn(`Scale error: ${error.message}`);
@@ -514,7 +525,7 @@ async function failoverHACloudflare(envName, envConfig, projectConfig, parsed, t
 
   // Wait for health endpoint
   s.start('Waiting for standby health check');
-  const healthy = waitForHealth(servers.standby.ip, sshKeyPath);
+  const healthy = await waitForHealth(servers.standby.ip, sshKeyPath);
   s.stop(healthy ? 'Standby health check passed' : 'Health check timed out');
 
   // Step 4: Switch DNS A record to standby floating IP. proxied:false
@@ -627,9 +638,9 @@ async function failoverHAHetznerDNS(envName, envConfig, projectConfig, parsed, t
   // disaster failover) — promotion proceeds with whatever state standby
   // has. Requires primarySupabaseIp from identifyServers (persisted in
   // envConfig.servers by orchestrator.js post-deploy).
-  if (isPrimaryPostgresReady(servers.primary.ip, sshKeyPath)) {
+  if (await isPrimaryPostgresReady(servers.primary.ip, sshKeyPath)) {
     s.start('Re-seeding standby from primary (pg_basebackup)');
-    const reseeded = reseedStandbyFromPrimary(
+    const reseeded = await reseedStandbyFromPrimary(
       servers.standby.ip,
       sshKeyPath,
       servers.primary.supabaseIp,
@@ -641,7 +652,7 @@ async function failoverHAHetznerDNS(envName, envConfig, projectConfig, parsed, t
 
   // Step 1: Promote standby database
   s.start('Promoting standby database');
-  const promoted = promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
+  const promoted = await promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
   s.stop(
     promoted
       ? 'Standby database promoted to primary'
@@ -655,13 +666,19 @@ async function failoverHAHetznerDNS(envName, envConfig, projectConfig, parsed, t
   // See FAILOVER_DEPLOYMENTS for the chart-canonical names — bare
   // `auth`/`rest`/etc. silently no-op'd in an earlier version.
   s.start('Scaling down old primary services');
-  scaleDeployments(servers.primary.ip, sshKeyPath, FAILOVER_DEPLOYMENTS, 0, 'scale-down primary');
+  await scaleDeployments(
+    servers.primary.ip,
+    sshKeyPath,
+    FAILOVER_DEPLOYMENTS,
+    0,
+    'scale-down primary',
+  );
   s.stop('Old primary services scaled down');
 
   // Step 3: Scale up standby services
   s.start('Scaling up standby services');
   try {
-    scaleUpServices(servers.standby.ip, sshKeyPath);
+    await scaleUpServices(servers.standby.ip, sshKeyPath);
   } catch (error) {
     s.stop('Some services failed to scale');
     p.log.warn(`Scale error: ${error.message}`);
@@ -670,7 +687,7 @@ async function failoverHAHetznerDNS(envName, envConfig, projectConfig, parsed, t
 
   // Wait for health endpoint
   s.start('Waiting for standby health check');
-  const healthy = waitForHealth(servers.standby.ip, sshKeyPath);
+  const healthy = await waitForHealth(servers.standby.ip, sshKeyPath);
   s.stop(healthy ? 'Standby health check passed' : 'Health check timed out');
 
   // Step 4: Update DNS A record via Hetzner DNS API
@@ -756,13 +773,13 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
 
   // Promote standby database
   s.start('Promoting standby database');
-  const promoted = promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
+  const promoted = await promoteStandbyDatabase(servers.standby.ip, sshKeyPath);
   s.stop(promoted ? 'Standby database promoted' : 'Promotion may still be in progress');
 
   // Scale down old primary services to prevent split-brain
   s.start('Scaling down old primary services');
   try {
-    sshKubectl(servers.primary.ip, sshKeyPath, [
+    await sshKubectl(servers.primary.ip, sshKeyPath, [
       'scale',
       'deployment',
       'app',
@@ -770,7 +787,7 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
       'vibecarbon',
       '--replicas=0',
     ]);
-    sshKubectl(servers.primary.ip, sshKeyPath, [
+    await sshKubectl(servers.primary.ip, sshKeyPath, [
       'scale',
       'deployment',
       'auth',
@@ -778,7 +795,7 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
       'vibecarbon',
       '--replicas=0',
     ]);
-    sshKubectl(servers.primary.ip, sshKeyPath, [
+    await sshKubectl(servers.primary.ip, sshKeyPath, [
       'scale',
       'deployment',
       'rest',
@@ -786,7 +803,7 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
       'vibecarbon',
       '--replicas=0',
     ]);
-    sshKubectl(servers.primary.ip, sshKeyPath, [
+    await sshKubectl(servers.primary.ip, sshKeyPath, [
       'scale',
       'deployment',
       'realtime',
@@ -802,7 +819,7 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
   // Scale up services
   s.start('Scaling up standby services');
   try {
-    scaleUpServices(servers.standby.ip, sshKeyPath);
+    await scaleUpServices(servers.standby.ip, sshKeyPath);
   } catch (error) {
     s.stop('Some services failed to scale');
     p.log.warn(`Scale error: ${error.message}`);
@@ -811,7 +828,7 @@ async function failoverHAManual(envName, envConfig, projectConfig, parsed, track
 
   // Wait for health
   s.start('Waiting for standby health check');
-  const healthy = waitForHealth(servers.standby.ip, sshKeyPath);
+  const healthy = await waitForHealth(servers.standby.ip, sshKeyPath);
   s.stop(healthy ? 'Standby health check passed' : 'Health check timed out');
 
   // Print DNS instructions
@@ -841,7 +858,7 @@ async function failoverSingleServer(envName, envConfig) {
     const s = p.spinner();
     s.start('Checking for available backups');
     try {
-      const pod = sshKubectl(serverIp, sshKeyPath, [
+      const pod = await sshKubectl(serverIp, sshKeyPath, [
         'get',
         'pods',
         '-n',
@@ -851,7 +868,7 @@ async function failoverSingleServer(envName, envConfig) {
         '-o',
         'jsonpath={.items[0].metadata.name}',
       ]);
-      const output = sshKubectl(serverIp, sshKeyPath, [
+      const output = await sshKubectl(serverIp, sshKeyPath, [
         'exec',
         '-n',
         'vibecarbon',

package/src/lib/backup-format.js

@@ -0,0 +1,84 @@
+/**
+ * Human-friendly formatting for backup listings.
+ *
+ * Backup filenames embed the canonical backup time as `_YYYYMMDD_HHMMSS_`
+ * (e.g. `myproject_20260519_120001_full.tar.gz`). Both `restore` (the picker)
+ * and `backup list` parse that and render a relative, scannable label —
+ * "Today, 12:00 PM" — instead of the raw S3 key.
+ */
+
+const TS_RE = /_(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})_/;
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * Parse the embedded backup timestamp from a backup filename.
+ * @param {string} name
+ * @returns {Date|null} local-time Date, or null if no timestamp is present
+ */
+export function parseBackupTime(name) {
+  const m = typeof name === 'string' ? name.match(TS_RE) : null;
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m.map(Number);
+  const date = new Date(y, mo - 1, d, h, mi, s);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function clockTime(date) {
+  const h24 = date.getHours();
+  const m = date.getMinutes();
+  const ampm = h24 < 12 ? 'AM' : 'PM';
+  const h = h24 % 12 || 12;
+  return `${h}:${String(m).padStart(2, '0')} ${ampm}`;
+}
+
+function startOfDay(d) {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+}
+
+/**
+ * Render a relative, human-readable label for a backup filename:
+ * "Today, 12:00 PM" / "Yesterday, 6:00 PM" / "May 17, 12:00 PM" /
+ * "Dec 31 2025, 6:00 PM" (older year). Falls back to the raw name if the
+ * timestamp can't be parsed.
+ *
+ * @param {string} name
+ * @param {Date} [now] - injectable for testing; defaults to the current time
+ * @returns {string}
+ */
+/**
+ * Render a Date as a relative, human-readable label.
+ * "Today, 12:00 PM" / "Yesterday, 6:00 PM" / "May 17, 12:00 PM" /
+ * "Dec 31 2025, 6:00 PM" (older year).
+ * @param {Date} date
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function formatDate(date, now = new Date()) {
+  const dayDiff = Math.round((startOfDay(now) - startOfDay(date)) / 86_400_000);
+  let day;
+  if (dayDiff === 0) day = 'Today';
+  else if (dayDiff === 1) day = 'Yesterday';
+  else if (date.getFullYear() === now.getFullYear())
+    day = `${MONTHS[date.getMonth()]} ${date.getDate()}`;
+  else day = `${MONTHS[date.getMonth()]} ${date.getDate()} ${date.getFullYear()}`;
+
+  return `${day}, ${clockTime(date)}`;
+}
+
+export function formatBackupTime(name, now = new Date()) {
+  const date = parseBackupTime(name);
+  if (!date) return name;
+  return formatDate(date, now);
+}
+
+/**
+ * Render an instant (Date or ISO-8601 string, e.g. wal-g's `time` field) using
+ * the same relative labels as formatBackupTime. Returns '' for unparseable input.
+ * @param {Date|string} value
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function formatInstant(value, now = new Date()) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? '' : formatDate(date, now);
+}