vibecarbon 0.10.0 → 0.11.0

package/src/lib/deploy/compose/index.js

@@ -19,6 +19,7 @@ import * as p from '@clack/prompts';
 import { runCommandAsync } from '../../command.js';
 import { knownHostsPathForKey } from '../../host-keys.js';
 import { perfAsync, perfTimer } from '../../perf.js';
+import { runWithRetry } from '../../retry.js';
 import { parseDotenv, shEscape } from '../../shell.js';
 import { sshRunScript } from '../../ssh.js';
 import { postAdminUser, waitForGotrueHealth } from '../admin-user.js';
@@ -123,45 +124,50 @@ export async function sshRunAsync(ip, sshKeyPath, command, options = {}) {
   // the retry loop can catch them. We apply ignoreError ourselves after retries.
   const runOpts = { silent: true, timeout, ...rest };
 
-  for (let attempt = 0; attempt < retries; attempt++) {
-    try {
-      return await runCommandAsync(sshArgs, runOpts);
-    } catch (err) {
-      const msg = err.message || '';
-      const isConnectionError =
-        msg.includes('Connection reset') ||
-        msg.includes('Connection refused') ||
-        msg.includes('Connection closed') ||
-        msg.includes('kex_exchange_identification') ||
-        msg.includes('ssh_exchange_identification') ||
-        msg.includes('No route to host');
-      // Timeouts are transient too: a freshly-provisioned Hetzner VPS can
-      // have unattended-upgrades chewing CPU/disk in the background after
-      // cloud-init's marker file lands — SSH responds, but each command
-      // takes longer. Observed in iter-validate4 compose-ha restore where
-      // dockerLogin (a tiny stdin-script SSH call with a 30s timeout)
-      // hit the timeout twice in a row on the primary VPS without
-      // retry. The retry budget here (3 attempts × 5s backoff) is small
-      // enough that real hangs still surface fast, but absorbs the
-      // background-work blip on a healthy server.
-      const isTimeout =
-        msg.includes('timed out') ||
-        msg.includes('Command was killed with SIGTERM') ||
-        msg.includes('ETIMEDOUT');
-      const isTransient = isConnectionError || isTimeout;
-
-      if (isTransient && attempt < retries - 1) {
+  // attempts = delaysMs.length + 1, so retries=3 (default) => 2 delays => 3
+  // total attempts, matching the old hand-rolled `for (attempt < retries)` loop.
+  const delaysMs = Array.from({ length: Math.max(0, retries - 1) }, () => 5000);
+  const ATTEMPTS = delaysMs.length + 1;
+
+  try {
+    return await runWithRetry(() => runCommandAsync(sshArgs, runOpts), {
+      delaysMs,
+      isTransient: (err) => {
+        const msg = err.message || '';
+        const isConnectionError =
+          msg.includes('Connection reset') ||
+          msg.includes('Connection refused') ||
+          msg.includes('Connection closed') ||
+          msg.includes('kex_exchange_identification') ||
+          msg.includes('ssh_exchange_identification') ||
+          msg.includes('No route to host');
+        // Timeouts are transient too: a freshly-provisioned Hetzner VPS can
+        // have unattended-upgrades chewing CPU/disk in the background after
+        // cloud-init's marker file lands — SSH responds, but each command
+        // takes longer. Observed in iter-validate4 compose-ha restore where
+        // dockerLogin (a tiny stdin-script SSH call with a 30s timeout)
+        // hit the timeout twice in a row on the primary VPS without
+        // retry. The retry budget here (3 attempts × 5s backoff) is small
+        // enough that real hangs still surface fast, but absorbs the
+        // background-work blip on a healthy server.
+        const isTimeout =
+          msg.includes('timed out') ||
+          msg.includes('Command was killed with SIGTERM') ||
+          msg.includes('ETIMEDOUT');
+        return isConnectionError || isTimeout;
+      },
+      onRetry: (err, attempt) => {
+        const msg = err.message || '';
         console.error(
-          `[retry] ssh ${ip}: attempt ${attempt + 1}/${retries} failed (${msg.slice(0, 80).split('\n')[0]}); retrying in 5s`,
+          `[retry] ssh ${ip}: attempt ${attempt}/${ATTEMPTS} failed (${msg.slice(0, 80).split('\n')[0]}); retrying in 5s`,
         );
-        await new Promise((r) => setTimeout(r, 5000));
-        continue;
-      }
-
-      // All retries exhausted — respect ignoreError if set
-      if (ignoreError) return null;
-      throw err;
-    }
+      },
+    });
+  } catch (err) {
+    // All retries exhausted (or the error was non-transient) — respect
+    // ignoreError if set.
+    if (ignoreError) return null;
+    throw err;
   }
 }
 

package/src/lib/deploy/compose/single.js

@@ -0,0 +1,421 @@
+/**
+ * Single-server Compose deployment (tier: 'compose').
+ *
+ * Extracted verbatim from the orchestrator's STEP 5 inline compose-single
+ * branch. Provisions one Hetzner VPS (or reuses an existing one), transfers
+ * the image (local sideload / direct build / GHCR pull), writes DNS before
+ * compose-up (HTTP-01 ordering fix), reconciles the stack, runs migrations +
+ * admin-user creation, gates on an app-health probe, and installs the backup
+ * cron. Returns the persisted-config server descriptor.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { loadCredentials } from '../../config.js';
+import { waitForDNSPropagation } from '../../dns-propagation.js';
+import { knownHostsPathForKey, seedKnownHosts } from '../../host-keys.js';
+import { perfAsync } from '../../perf.js';
+import { sideloadCompose } from '../image.js';
+import { buildRemote } from '../remote-build.js';
+import { generateSSHKeyPair } from '../utils.js';
+
+export async function deployComposeSingle(ctx) {
+  const {
+    projectConfig,
+    environment,
+    envConfig,
+    region,
+    serverType,
+    services,
+    domain,
+    dnsProvider,
+    apiToken,
+    cloudflareApiToken,
+    cloudflareZoneId,
+    hetznerDnsZoneId,
+    backupConfig,
+    imageRef,
+    bundlePath,
+    ciReady,
+    s3Config,
+    state,
+    dnsChallenge,
+    dnsWarmupPromise,
+    isDirectDeploy,
+    isComposeLocal,
+    localImageTag,
+    composeLocalBuildPromise,
+  } = ctx;
+
+  const {
+    setupServer,
+    dockerLoginOnServer,
+    startComposeStack,
+    runMigrations,
+    createAdminUser,
+    setupComposeBackupCron,
+  } = await import('./index.js');
+  const { setupServerFiles, waitForSSH: waitForComposeSSH } = await import('./index.js');
+  const sshKeyPath = join(process.cwd(), '.vibecarbon', `deploy_key_${environment}`);
+
+  let serverIp = envConfig.servers?.[0]?.ip || null;
+  // Track the Hetzner server's API id + literal name so destroy can find
+  // the VPS without falling back to the literal string "master" (which
+  // never matches the Pulumi-assigned name `${projectName}-${env}`).
+  // Without this, destroy → re-deploy hits 'server name is already used
+  // (uniqueness_error)' because the previous VPS was never deleted
+  // (caught in compose restore matrix runs).
+  let serverHetznerId = envConfig.servers?.[0]?.id || null;
+  let serverHetznerName = envConfig.servers?.[0]?.hetznerName || null;
+  if (!serverIp) {
+    generateSSHKeyPair(sshKeyPath);
+    const { upStack } = await import('../../iac/index.js');
+    const { buildHetznerComposeProgram } = await import('../../iac/programs/hetzner-compose.js');
+    const program = buildHetznerComposeProgram({
+      projectName: projectConfig.projectName,
+      environment,
+      sshPublicKey: readFileSync(`${sshKeyPath}.pub`, 'utf-8').trim(),
+      location: region,
+      serverType: serverType || 'cx23',
+      labels: { 'managed-by': 'vibecarbon' },
+      allowedSshIps: (projectConfig.operatorCidrs ?? []).map((e) => e.cidr),
+    });
+    // VM provisioning via Pulumi — typical 30-90s on Hetzner cx23.
+    const result = await perfAsync('deploy.iac.upStack', () =>
+      upStack(environment, program, { hcloudToken: apiToken, s3Config }),
+    );
+    serverIp = result.outputs.serverIp;
+    serverHetznerId = result.outputs.serverId || null;
+    serverHetznerName = `${projectConfig.projectName}-${environment}`;
+    await perfAsync('deploy.iac.waitForSSH', () => waitForComposeSSH(serverIp, sshKeyPath, 30));
+    // Trusted host-key seed on fresh provision — captures the new VPS's
+    // host key via ssh-keyscan into the per-env known_hosts so the pinned
+    // SSH opts (accept-new) become a strict pin for this deploy and every
+    // later command. Re-seeding here also cleanly re-pins a Hetzner-
+    // recycled IP (destroy → redeploy). Best-effort: falls back to
+    // accept-new TOFU if the scan can't reach the server yet. See
+    // host-keys.js seedKnownHosts for the full security rationale.
+    await seedKnownHosts(knownHostsPathForKey(sshKeyPath), serverIp);
+  }
+
+  // --- Warm path (StateTracker) ---
+  // On a second deploy against an already-provisioned server, skip the
+  // idempotent-but-slow steps (cloud-init probe, GHCR login, bundle rsync)
+  // when their inputs haven't changed. `docker compose up -d` is cheap
+  // and always runs — it applies diffs to the live stack.
+  const setupInputs = { serverIp };
+  if (!state.shouldSkip('compose-setup-server', setupInputs)) {
+    state.startStep('compose-setup-server', setupInputs);
+    // Cloud-init readiness probe — first-deploy spends 20-40s here while
+    // ufw + unattended-upgrades land. Warm deploys hit the ready marker
+    // immediately, so this is mostly cold-deploy noise.
+    await perfAsync('deploy.compose.cloudInitReady', async () => {
+      if (isDirectDeploy || isComposeLocal) {
+        // Both direct (build over DOCKER_HOST=ssh://) and local
+        // (sideload via docker save | ssh docker load) need dockerd
+        // up on the server before they can proceed. Push mode doesn't
+        // because the server pulls from GHCR after compose-up starts.
+        const { waitForDockerReady } = await import('./index.js');
+        await setupServer(serverIp, sshKeyPath);
+        await waitForDockerReady(serverIp, sshKeyPath);
+      } else {
+        await setupServer(serverIp, sshKeyPath);
+      }
+    });
+    state.completeStep('compose-setup-server', { serverIp });
+  }
+
+  // --- Image transfer to server (mode-dependent) ---
+  if (isComposeLocal) {
+    // Local-build path: the build was kicked off in parallel with
+    // iac.upStack at the top of this function. By the time we reach
+    // here (post-cloudInitReady), the build has almost always finished.
+    // Await the promise (cheap if already settled) then sideload the
+    // image tarball over SSH. Sideload uses docker save | gzip | ssh
+    // | docker load — gzip drops ~600MB → ~150-200MB on the wire.
+    //
+    // Both run silently (build is silent:true; sideload streams no stdout),
+    // so without a spinner this is a 15-30s dead pause right after "Proceed"
+    // on warm redeploys (where the upStack spinner that normally overlaps
+    // the build was skipped). Drive a spinner so the operator sees progress.
+    const imageSpinner = p.spinner();
+    imageSpinner.start('Building app image');
+    await composeLocalBuildPromise;
+    imageSpinner.message('Sideloading app image to the server');
+    await perfAsync('deploy.image.sideload', async () =>
+      sideloadCompose({
+        tag: localImageTag,
+        sshTarget: `root@${serverIp}`,
+        sshKey: sshKeyPath,
+      }),
+    );
+    imageSpinner.stop('App image built and sideloaded');
+  } else if (isDirectDeploy) {
+    // Direct path: build the image on the server via DOCKER_HOST=ssh://.
+    // BuildKit caches aggressively, so unchanged source rebuilds in 1-3s.
+    // Slower than local+sideload (no upStack overlap) but works when the
+    // operator has no local Docker — selected by --direct or by
+    // resolveBuildMode's docker-not-found fallback. VITE_* args plumbed
+    // through here for the same reason as the local-build path above.
+    const { collectComposeBuildArgs } = await import('./build-args.js');
+    const directBuildArgs = collectComposeBuildArgs(process.cwd(), {
+      projectName: projectConfig.projectName,
+      domain,
+    });
+    const success = await perfAsync('deploy.image.directBuild', () =>
+      buildRemote(serverIp, sshKeyPath, localImageTag, process.cwd(), directBuildArgs),
+    );
+    if (!success) process.exit(1);
+  }
+
+  // --- Docker Hub login (skip if creds unchanged) ---
+  // Without this, the reconcile script's `docker compose pull` for
+  // Supabase service images (rest, auth, storage, kong, imgproxy, etc.)
+  // hits Docker Hub anonymously. A fresh Hetzner VPS shares a NAT range
+  // with many other deploys, so the per-IP unauthenticated pull quota
+  // is routinely exhausted — observed 2026-04-26 matrix run #3
+  // ("toomanyrequests: You have reached your unauthenticated pull rate
+  // limit"). Compose-HA + scale already log in; this brings the
+  // single-compose deploy path in line.
+  const dockerHubCreds = loadCredentials().dockerHub || null;
+  if (dockerHubCreds) {
+    const dhLoginInputs = {
+      serverIp,
+      registry: 'docker.io',
+      user: dockerHubCreds.username,
+      tokenFp: dockerHubCreds.token ? dockerHubCreds.token.slice(0, 8) : '',
+    };
+    if (!state.shouldSkip('compose-dockerhub-login', dhLoginInputs)) {
+      state.startStep('compose-dockerhub-login', dhLoginInputs);
+      await dockerLoginOnServer(serverIp, sshKeyPath, dockerHubCreds);
+      state.completeStep('compose-dockerhub-login', { serverIp });
+    }
+  }
+
+  // --- GHCR login (skip if creds unchanged) ---
+  if (ciReady.ghcrPullCreds) {
+    const loginInputs = {
+      serverIp,
+      registry: 'ghcr.io',
+      user: ciReady.ghcrPullCreds.owner,
+      // Hash the token's fingerprint, not the token itself — we don't
+      // want the token written to .vibecarbon/deploy-state-*.json.
+      tokenFp: ciReady.ghcrPullCreds.token ? ciReady.ghcrPullCreds.token.slice(0, 8) : '',
+    };
+    if (!state.shouldSkip('compose-ghcr-login', loginInputs)) {
+      state.startStep('compose-ghcr-login', loginInputs);
+      await dockerLoginOnServer(serverIp, sshKeyPath, {
+        username: ciReady.ghcrPullCreds.owner,
+        token: ciReady.ghcrPullCreds.token,
+        registry: 'ghcr.io',
+      });
+      state.completeStep('compose-ghcr-login', { serverIp });
+    }
+  }
+
+  // --- Bundle rsync (skip when bundle inputs unchanged) ---
+  const bundleInputs = {
+    serverIp,
+    projectName: projectConfig.projectName,
+    imageRef,
+    domain,
+    services,
+  };
+  if (!state.shouldSkip('compose-setup-files', bundleInputs)) {
+    state.startStep('compose-setup-files', bundleInputs);
+    // setupServerFiles tars the bundle locally + streams over ssh +
+    // extracts on the server in one pipeline. Bucket the whole upload
+    // here; the inner tar/upload split is captured in compose/index.js.
+    await perfAsync('deploy.bundle.upload', () =>
+      setupServerFiles(serverIp, sshKeyPath, projectConfig.projectName, {
+        ...services,
+        domain,
+        image: imageRef,
+        bundlePath,
+      }),
+    );
+    state.completeStep('compose-setup-files', { serverIp });
+  }
+
+  // --- DNS update + propagation wait BEFORE compose-up ---
+  //
+  // Traefik attempts ACME HTTP-01 challenges immediately on container
+  // start and bursts ~7 attempts in ~30s before giving up. If LE's
+  // DNS resolver sees stale or absent records on those attempts,
+  // every challenge fails with "no valid A records found" and
+  // acme.json ends the deploy with zero certs issued — browser
+  // sees TRAEFIK DEFAULT CERT and NET::ERR_CERT_AUTHORITY_INVALID.
+  //
+  // The warm-up that fires in Step 4 writes a 0.0.0.0 placeholder;
+  // LE specifically rejects 0.0.0.0 as not-a-valid-A-record. So even
+  // when warm-up "succeeds," it doesn't help ACME — it actively
+  // poisons the resolver state until the real IP overwrites it.
+  //
+  // Fix (RCA from vibecarbon.com cold-deploy 2026-05-19): swap the
+  // ordering. Write the real IP now, wait for it to propagate to
+  // public resolvers, then start compose. Traefik's first ACME
+  // attempt sees real DNS, succeeds on the first try.
+  //
+  // The compose-HA path already writes DNS before compose-up at
+  // src/lib/deploy/compose/ha.js — single-region compose was the
+  // outlier that ran startComposeStack first then updated DNS.
+  if (domain && dnsProvider && dnsProvider !== 'manual') {
+    await perfAsync('deploy.dns.warm', async () => {
+      await dnsWarmupPromise;
+    });
+    const dnsUpdateInputs = { domain, dnsProvider, serverIp };
+    if (!state.shouldSkip('compose-dns-update', dnsUpdateInputs)) {
+      state.startStep('compose-dns-update', dnsUpdateInputs);
+      const { setupSimple: updateDnsIp } =
+        dnsProvider === 'cloudflare'
+          ? await import('../../cloudflare.js')
+          : await import('../../hetzner-dns.js');
+      const token = dnsProvider === 'cloudflare' ? cloudflareApiToken : apiToken;
+      const zoneId = dnsProvider === 'cloudflare' ? cloudflareZoneId : hetznerDnsZoneId;
+      const dnsSpinner = p.spinner();
+      dnsSpinner.start(`Pointing ${domain} → ${serverIp}...`);
+      await perfAsync('deploy.dns.create', () => updateDnsIp(token, zoneId, domain, serverIp));
+      dnsSpinner.stop(`DNS A record set: ${domain} → ${serverIp}`);
+      state.completeStep('compose-dns-update', { serverIp });
+    }
+    // HTTP-01 only: block compose-up until public resolvers see the real
+    // IP. 120s budget covers Cloudflare's typical edge propagation (under
+    // 60s) with margin. Returns false on timeout; we proceed anyway —
+    // Traefik can still acquire certs on its own retries, the customer
+    // just sees a brief self-signed-cert window. Hard-failing here would
+    // mask deploys that succeed eventually.
+    //
+    // DNS-01 (managed providers) skips this entirely: lego validates via a
+    // TXT record it writes through the provider API, so cert issuance does
+    // not wait on the A record propagating. The A record we just wrote
+    // propagates in the background; the post-deploy health probe uses
+    // localhost + Host header and never depends on it.
+    //
+    // Visible spinner so the operator isn't staring at a frozen
+    // "Yes" screen for up to 120s on a cold deploy where the DNS
+    // edge is slow. `timer` indicator forces the rendered string to
+    // change every second so progress remains visibly alive.
+    if (!dnsChallenge) {
+      const dnsSpinner = p.spinner({ indicator: 'timer' });
+      dnsSpinner.start(`Waiting for ${domain} to resolve to ${serverIp}`);
+      const dnsPropagated = await perfAsync('deploy.dns.waitForPropagation', () =>
+        waitForDNSPropagation(domain, serverIp, 120_000),
+      );
+      dnsSpinner.stop(
+        dnsPropagated
+          ? `DNS resolves: ${domain} → ${serverIp}`
+          : `DNS propagation timed out — proceeding anyway`,
+      );
+    }
+  }
+
+  // `docker compose up -d` is idempotent and cheap — always run so a
+  // config tweak that didn't change the bundle hash (e.g. env var)
+  // still takes effect. Reconcile.sh on the server runs `docker compose
+  // pull` (when not local image) + `docker compose up -d` — see
+  // compose/index.js for the inner perf instrumentation.
+  await perfAsync('deploy.reconcile.run', () =>
+    startComposeStack(serverIp, sshKeyPath, projectConfig.projectName, services),
+  );
+
+  // Apply app migrations + reload PostgREST. The orchestrator's inline
+  // single-compose path previously skipped this (only deployComposeHA ran
+  // runMigrations), so compose-single shipped an EMPTY app schema — 0 public
+  // tables, every DB-backed feature 500'd, and db_schema verify failed with
+  // PGRST205. runMigrations waits for supabase_admin, applies each
+  // supabase/migrations/* with ON_ERROR_STOP=1 (a real failure aborts the
+  // deploy rather than silently shipping a schema-less prod), then reloads
+  // PostgREST's schema cache. Mirrors the HA path.
+  await perfAsync('deploy.compose.migrations', () =>
+    runMigrations(serverIp, sshKeyPath, projectConfig.projectName),
+  );
+
+  // Create the production app super-admin in auth.users via GoTrue's admin
+  // API. Same class of trap as runMigrations above: this inline single-
+  // compose path previously skipped it (only deployComposeHA called
+  // createAdminUser), so a single-server deploy shipped a prod app the
+  // operator couldn't actually log into — the only admin user lived in
+  // their local Docker. Idempotent (422 = already exists); a failure here
+  // is a warning, not a hard abort, so a transient GoTrue blip doesn't
+  // fail an otherwise-healthy deploy — re-running `vibecarbon deploy`
+  // retries it.
+  const adminResult = await perfAsync('deploy.compose.createAdminUser', () =>
+    createAdminUser(serverIp, sshKeyPath, projectConfig.projectName),
+  );
+  if (adminResult.success) {
+    p.log.success(adminResult.message);
+  } else {
+    p.log.warn(`${adminResult.message}. Run \`vibecarbon deploy\` again to retry.`);
+  }
+
+  // --- Verifiable success gate ---
+  // Probe the app's own /api/health endpoint on the server itself (via
+  // localhost + Host header), bypassing DNS/TLS. A successful deploy
+  // must yield an HTTP 2xx here; otherwise fail the deploy loudly with
+  // container state + log tail.
+  //
+  // verifyAppHealth polls every 10s for up to 3 minutes while the app
+  // container restarts and binds port 3000. Without a visible spinner
+  // the operator just sees a frozen "Stack reconciled" line for that
+  // entire window — observed 2026-05-19 vibecarbon.com re-deploy
+  // where compose-up finished in ~5s but the app took ~3min to come
+  // back, leaving the screen looking hung. `timer` indicator so the
+  // elapsed-seconds counter ticks visibly even on terminals where
+  // the spinner frame-character animation gets throttled under load.
+  const { verifyAppHealth } = await import('./index.js');
+  const healthSpinner = p.spinner({ indicator: 'timer' });
+  healthSpinner.start('Waiting for app to start serving requests');
+  let health;
+  try {
+    health = await perfAsync('deploy.health.probe', () =>
+      verifyAppHealth(serverIp, sshKeyPath, projectConfig.projectName, {
+        domain,
+      }),
+    );
+  } catch (err) {
+    healthSpinner.stop('App health probe errored', 1);
+    throw err;
+  }
+  if (!health.healthy) {
+    healthSpinner.stop(`App not serving requests (status: ${health.status})`, 1);
+    p.log.error(
+      `Deploy produced an unhealthy app (probe status: ${health.status}):\n${health.details}`,
+    );
+    process.exit(1);
+  }
+  healthSpinner.stop(`App is serving requests (HTTP ${health.status})`);
+
+  // Install the scheduled wal-g backup cron on the server. Without this,
+  // a fresh compose deploy collects + persists backupConfig (envConfig.backup)
+  // but never schedules a backup — backups only ran after a `vibecarbon scale`
+  // event (scale.js was the lone caller). setupComposeBackupCron defaults the
+  // schedule + retain when backupConfig is absent, so it always installs a
+  // sensible cron. wal-g reads its S3 config from the db container env
+  // (rendered into .env at deploy) — the cron just runs compose-backup.sh,
+  // which self-skips (exit 0) when no S3 backup target is configured, so an
+  // always-installed cron never hard-fails on a no-S3 deploy.
+  //
+  // A cron-install failure must NOT fail an already-healthy deploy: the app
+  // is serving by this point. Downgrade to a warning so a transient ssh/cron
+  // hiccup doesn't roll back a successful deploy.
+  try {
+    await perfAsync('deploy.compose.backupCron', async () =>
+      setupComposeBackupCron(serverIp, sshKeyPath, projectConfig.projectName, backupConfig),
+    );
+  } catch (err) {
+    p.log.warn(`Scheduled backup cron install failed (deploy still succeeded): ${err.message}`);
+  }
+
+  // No ACME self-heal needed here. Managed-DNS deploys (cloudflare/hetzner)
+  // issue certs via DNS-01, which has no HTTP-01-vs-DNS-propagation race to
+  // recover from; `manual` DNS was never self-healed (we don't manage its
+  // records). The old acme.json poll + Traefik restart (acme-verify.js)
+  // existed only for the HTTP-01 race the DNS-01 switch eliminates.
+
+  return {
+    masterIp: serverIp,
+    serverId: serverHetznerId || 'manual',
+    serverName: serverHetznerName,
+  };
+}

package/src/lib/deploy/image.js

@@ -13,6 +13,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { runCommandAsync } from '../command.js';
 import { knownHostsPathForKey } from '../host-keys.js';
 import { shEscape } from '../shell.js';
 
@@ -95,9 +96,9 @@ export function inspectGitState(cwd) {
  *
  * @param {string} projectDir - Project root with the Dockerfile.
  * @param {{projectName: string, timestamp?: string, rebuild?: boolean, tagPrefix?: string, buildArgs?: Record<string,string>}} options
- * @returns {{tag: string, gitSha: string, isDirty: boolean}}
+ * @returns {Promise<{tag: string, gitSha: string, isDirty: boolean}>}
  */
-export function buildLocalImage(projectDir, options) {
+export async function buildLocalImage(projectDir, options) {
   const { projectName, rebuild = false, tagPrefix, buildArgs = {} } = options;
   if (!projectName) {
     throw new Error('buildLocalImage: projectName is required');
@@ -124,7 +125,15 @@ export function buildLocalImage(projectDir, options) {
   }
   args.push('-t', tag, projectDir);
 
-  execFileSync('docker', args, { stdio: 'inherit' });
+  // silent: false (the default) inherits stdio so the operator sees layer
+  // progress — but runCommandAsync only *rejects* on nonzero exit when
+  // silent:true; with inherited stdio it resolves `false` instead (see
+  // global constraints). The old execFileSync({stdio:'inherit'}) threw on
+  // its own, so we must replicate "fail loudly" by hand here.
+  const ok = await runCommandAsync(['docker', ...args], {});
+  if (ok === false) {
+    throw new Error(`buildLocalImage: docker build failed for ${tag}`);
+  }
   return { tag, gitSha, isDirty };
 }
 
@@ -150,8 +159,9 @@ function defaultTimestamp() {
  * `pipefail` so a docker-save / gzip failure isn't masked by ssh's exit code.
  *
  * @param {{tag: string, sshTarget: string, sshKey?: string}} args
+ * @returns {Promise<void>}
  */
-export function sideloadCompose({ tag, sshTarget, sshKey }) {
+export async function sideloadCompose({ tag, sshTarget, sshKey }) {
   // SSH options mirror remote-build.js's wrapper + the compose deploy path:
   //   * Host-key pinned per-env (knownHostsPathForKey), NOT /dev/null + no.
   //     accept-new TOFU's an ephemeral/recycled Hetzner IP but rejects a
@@ -177,15 +187,17 @@ export function sideloadCompose({ tag, sshTarget, sshKey }) {
   // key warning + `docker load`'s "Loaded image:" success line both bypass
   // the clack gutter when inherited and print flush-left, breaking the
   // visual flow. On success we don't need either; on failure we surface
-  // the captured stderr for debugging via the thrown Error.
+  // the captured stderr for debugging via the thrown Error. silent:true is
+  // required both to get the capture and because runCommandAsync only
+  // rejects (rather than resolving `false`) on nonzero exit in that mode.
   try {
-    execFileSync('bash', ['-c', cmd], { stdio: ['ignore', 'pipe', 'pipe'] });
+    await runCommandAsync(['bash', '-c', cmd], { silent: true });
   } catch (err) {
     const stderr = err.stderr?.toString().trim() || '';
     const stdout = err.stdout?.toString().trim() || '';
     // Surface whatever signal the operator can act on: child stderr first
     // (real ssh / docker errors), then stdout, then the wrapping error's
-    // message (preserves "Connection refused" when execFileSync's own
+    // message (preserves "Connection refused" when runCommandAsync's own
     // error string is the only thing we have).
     const detail = [stderr, stdout, err.message].filter(Boolean).join('\n').trim();
     const wrapped = new Error(`sideloadCompose failed (exit ${err.status ?? '?'}): ${detail}`);