vibecarbon 0.1.0

package/src/lib/deploy/prompts.js

@@ -0,0 +1,545 @@
+/**
+ * Deployment Prompts
+ * Interactive CLI flow for gathering deployment configuration
+ */
+
+import * as p from '@clack/prompts';
+import { getZones as cloudflareGetZones } from '../cloudflare.js';
+import { c, printBanner } from '../colors.js';
+import { loadProjectConfig } from '../config.js';
+import { getZones as hetznerDnsGetZones } from '../hetzner-dns.js';
+import { getApiToken, getS3Credentials } from '../hetzner-guided-setup.js';
+import { HetznerS3Provider, sanitizeBucketName } from '../providers/hetzner-s3.js';
+import { HetznerProvider } from '../providers/index.js';
+import { validateDomain } from '../validators.js';
+import { VERSION } from '../version.js';
+import {
+  DEFAULT_WORKER_MAX,
+  DEFAULT_WORKER_MIN,
+  getBranchName,
+  getProviderConfig,
+  normalizeEnvName,
+} from './utils.js';
+
+// Re-export constants
+export { DEFAULT_WORKER_MAX, DEFAULT_WORKER_MIN };
+
+/**
+ * Resolve deploy mode (compose vs kubernetes) based on args and existing config.
+ */
+export async function resolveDeployMode(args, envConfig) {
+  // Respect existing environment's deploy mode + HA setting
+  if (envConfig.deployMode) {
+    return { deployMode: envConfig.deployMode, ha: envConfig.ha?.enabled || false };
+  }
+
+  // Diamond or Scale tier features: resolve from CLI flags
+  if (args.compose && args.ha) return { deployMode: 'compose-ha', ha: true };
+  if (args.compose) return { deployMode: 'compose', ha: false };
+  if (args.k8s && args.ha) return { deployMode: 'kubernetes', ha: true };
+  if (args.k8s) return { deployMode: 'kubernetes', ha: false };
+  if (args.ha) return { deployMode: 'kubernetes', ha: true };
+
+  // Non-interactive: default to compose when --yes and no mode flags
+  if (args.yes) {
+    return { deployMode: 'compose', ha: false };
+  }
+
+  // Interactive: Simple choices optimized for robustness
+  const mode = await p.select({
+    message: 'Deployment architecture:',
+    options: [
+      {
+        value: 'compose',
+        label: 'Docker Compose (Fast)',
+        hint: '1 VPS - Best for startups and internal tools',
+      },
+      {
+        value: 'compose-ha',
+        label: 'Docker Compose HA (Auto Failover)',
+        hint: '2 VPS - Simple failover without K8s complexity',
+      },
+      {
+        value: 'kubernetes',
+        label: 'Kubernetes (Auto Scaling)',
+        hint: 'k3s + Autoscaling - Best for high-traffic apps',
+      },
+      {
+        value: 'kubernetes-ha',
+        label: 'Kubernetes HA (Auto Scaling + Failover)',
+        hint: 'Multi-region cluster - Maximum availability',
+      },
+    ],
+  });
+
+  if (p.isCancel(mode)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  if (mode === 'kubernetes-ha') return { deployMode: 'kubernetes', ha: true };
+  if (mode === 'compose-ha') return { deployMode: 'compose-ha', ha: true };
+  return { deployMode: mode, ha: false };
+}
+
+/**
+ * Helper: fetch DNS zones with retry on transient network errors
+ */
+async function fetchZonesWithRetry(fetchFn, providerLabel) {
+  const s = p.spinner();
+  let lastError;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    s.start(
+      attempt === 1
+        ? `Fetching your ${providerLabel} zones`
+        : `Retrying zone fetch (attempt ${attempt}/3)`,
+    );
+    try {
+      const zones = await fetchFn();
+      s.stop('Zones retrieved');
+      return zones;
+    } catch (error) {
+      lastError = error;
+      const isTransient =
+        error.message?.includes('fetch failed') ||
+        error.message?.includes('ECONNRESET') ||
+        error.message?.includes('ETIMEDOUT');
+      if (!isTransient || attempt === 3) {
+        s.stop(`Failed to fetch ${providerLabel} zones: ${error.message}`);
+        throw error;
+      }
+      s.stop(`Zone fetch failed (${error.message}), retrying...`);
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Helper: select a zone and prompt for domain
+ */
+async function selectZoneAndDomain(zones, providerLabel, existingDomain) {
+  let selectedZone;
+
+  if (existingDomain) {
+    const domainParts = existingDomain.split('.');
+    for (let i = 0; i < domainParts.length - 1; i++) {
+      const possibleZone = domainParts.slice(i).join('.');
+      selectedZone = zones.find((z) => z.name === possibleZone);
+      if (selectedZone) break;
+    }
+    if (selectedZone) {
+      p.log.info(`Auto-detected zone: ${c.bold(selectedZone.name)}`);
+      return { zone: selectedZone, domain: existingDomain };
+    }
+  }
+
+  if (zones.length === 1) {
+    selectedZone = zones[0];
+    p.log.info(`Using zone: ${c.bold(selectedZone.name)}`);
+  } else {
+    const zoneOptions = zones.map((z) => ({ value: z, label: z.name }));
+    selectedZone = await p.select({
+      message: `Select your ${providerLabel} DNS zone`,
+      options: zoneOptions,
+    });
+    if (p.isCancel(selectedZone)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  const suggestedDomain = `app.${selectedZone.name}`;
+  const chosenDomain = await p.text({
+    message: `Domain name for ${selectedZone.name}`,
+    placeholder: suggestedDomain,
+    defaultValue: suggestedDomain,
+    initialValue: existingDomain || undefined,
+    validate: (v) => {
+      if (!v) return undefined;
+      const domainErr = validateDomain(v);
+      if (domainErr) return domainErr;
+      if (!v.endsWith(selectedZone.name) && v !== selectedZone.name) {
+        return `Domain must be under ${selectedZone.name} (e.g., app.${selectedZone.name})`;
+      }
+      return undefined;
+    },
+  });
+  if (p.isCancel(chosenDomain)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return { zone: selectedZone, domain: chosenDomain || null };
+}
+
+/**
+ * Gather full deployment configuration through interactive prompts and CLI args
+ */
+export async function gatherDeploymentConfig(args) {
+  console.clear();
+  printBanner();
+  p.intro(`${c.bold('vibecarbon deploy')} ${c.dim(`v${VERSION}`)}`);
+
+  const projectConfig = loadProjectConfig();
+  if (!projectConfig) {
+    p.log.error('No Vibecarbon project found. Run this command from your project directory.');
+    process.exit(1);
+  }
+
+  const services = projectConfig.services || {};
+  const environment = normalizeEnvName(args.env || 'prod');
+  const envConfig = projectConfig.environments?.[environment] || {};
+  const resuming = envConfig.status === 'deploying';
+
+  if (resuming) {
+    p.log.info(`Resuming previous deployment to ${c.bold(environment)}...`);
+  } else {
+    p.log.info(`Deploying to environment: ${c.bold(environment)}`);
+  }
+
+  const { deployMode, ha } = await resolveDeployMode(args, envConfig);
+  const isComposeDeploy = deployMode === 'compose' || deployMode === 'compose-ha';
+  const config = {
+    environment,
+    provider: 'hetzner',
+    ha,
+    observability: services.observability || false,
+    deployMode,
+  };
+  const providerConfig = getProviderConfig(config.provider);
+
+  // Direct vs Push prompt (compose only, when CI/CD is configured).
+  //
+  // K8s is local-first via deployK3s — no prompt, no choice. Compose with
+  // CI/CD offers both paths: direct is faster (~30s warm) but bypasses
+  // the CI review workflow; push is slower (~3 min) but goes through GHA
+  // and deploys via Flux.
+  //
+  // Skipped when:
+  //   - -y / --yes — non-interactive auto-detects (push if CI configured,
+  //     direct otherwise)
+  //   - CI/CD not configured — direct is the only option anyway
+  //
+  // Mutates args.direct / args.push so the downstream resolveBuildMode call
+  // in orchestrator picks up the selection. Pre-PR-5 the operator could
+  // also set these via CLI flags; PR 5 dropped that surface — this prompt
+  // is now the only path to the override.
+  if (isComposeDeploy && !args.yes && !resuming) {
+    const { ciAvailable } = await import('../ci-setup.js');
+    if (ciAvailable()) {
+      const choice = await p.select({
+        message: 'How would you like to deploy?',
+        options: [
+          {
+            value: 'direct',
+            label: 'Direct',
+            hint: 'Build here and push to the server (~30s warm, no CI)',
+          },
+          {
+            value: 'push',
+            label: 'Push',
+            hint: 'Commit + GitHub Actions build & deploy (~3 min)',
+          },
+        ],
+        initialValue: 'direct',
+      });
+      if (p.isCancel(choice)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+      }
+      if (choice === 'direct') args.direct = true;
+      else if (choice === 'push') args.push = true;
+    }
+  }
+
+  // Region Selection (Aggressive Default)
+  let region = args.region || envConfig.region || 'nbg1'; // Nuremberg as default robust region
+  if (!args.region && !envConfig.region && !args.yes) {
+    const regionOptions = Object.entries(providerConfig.regions).map(([id, name]) => ({
+      value: id,
+      label: `${id} - ${name}`,
+    }));
+    region = await p.select({
+      message: 'Region:',
+      options: regionOptions,
+      initialValue: region,
+    });
+    if (p.isCancel(region)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  let secondaryRegion = null;
+  if (ha) {
+    secondaryRegion =
+      args.secondaryRegion || envConfig.secondaryRegion || (region === 'nbg1' ? 'fsn1' : 'nbg1');
+  }
+
+  const apiToken = await getApiToken(projectConfig.projectName);
+  if (!apiToken) {
+    p.log.error('API token required');
+    process.exit(1);
+  }
+
+  await HetznerProvider.fetchServerTypes(apiToken);
+  const regionDefaults = HetznerProvider.getRegionDefaults(region);
+
+  // Server Type Selection (Streamlined)
+  let serverType, masterServerType, workerServerType, supabaseServerType;
+
+  if (isComposeDeploy) {
+    // Compose = single-host Supabase stack, so use the medium-tier default
+    // (2+ vCPU, 4+ GB) for the whole box. regionDefaults.supabaseType is
+    // live-catalog-derived so it avoids retired SKUs like cpx21 in EU.
+    serverType = args.serverType || envConfig.serverType || regionDefaults.supabaseType;
+    masterServerType = workerServerType = supabaseServerType = serverType;
+  } else {
+    // `--type <x>` (args.serverType) acts as a blanket fallback for all three
+    // node roles when a role-specific flag isn't set. Matches the compose
+    // case's simpler mental model and lets e2e pin the whole cluster
+    // to a single known-good SKU via `--type cx23`.
+    const blanket = args.serverType || envConfig.serverType;
+    masterServerType =
+      args.masterServerType || envConfig.masterServerType || blanket || regionDefaults.masterType;
+    supabaseServerType =
+      args.supabaseServerType ||
+      envConfig.supabaseServerType ||
+      blanket ||
+      regionDefaults.supabaseType;
+    workerServerType =
+      args.workerServerType || envConfig.workerServerType || blanket || regionDefaults.workerType;
+    serverType = workerServerType;
+  }
+
+  // DNS provider selection.
+  //
+  // Default is Hetzner: the same Cloud API token (`apiToken` resolved above)
+  // already administers Hetzner DNS zones, so there's zero extra setup for
+  // operators who keep DNS in Hetzner. Cloudflare is offered as an opt-in;
+  // if selected without a saved token, we prompt for one (with an offer to
+  // save). Manual skips DNS automation entirely.
+  //
+  // (cert-manager DNS-01 for Hetzner reads the Cloud API token from Secret
+  // `hetzner` / key `token`; the legacy separate DNS Console token was
+  // retired in May 2026 when Hetzner folded zone management into the main
+  // Cloud Console.)
+  let dnsProvider = args.dnsProvider || envConfig.dnsProvider;
+  let domain = args.domain || envConfig.domain || null;
+  let cloudflareZoneId = envConfig.dns?.cloudflareZoneId || null;
+  let hetznerDnsZoneId = envConfig.dns?.hetznerZoneId || null;
+
+  const { loadCredentials, saveCredentials } = await import('../config.js');
+  const savedCreds = loadCredentials();
+  let cloudflareApiToken =
+    process.env.CLOUDFLARE_API_TOKEN || savedCreds.cloudflare?.apiToken || null;
+
+  if (!dnsProvider) {
+    if (args.yes) {
+      dnsProvider = 'hetzner';
+    } else {
+      const choice = await p.select({
+        message: 'DNS provider:',
+        options: [
+          {
+            value: 'hetzner',
+            label: 'Hetzner DNS',
+            hint: 'Uses your Hetzner Cloud API token (no extra setup)',
+          },
+          {
+            value: 'cloudflare',
+            label: 'Cloudflare',
+            hint: cloudflareApiToken ? 'API token saved' : 'Will prompt for API token',
+          },
+          {
+            value: 'manual',
+            label: 'Manual',
+            hint: 'Skip DNS automation — configure records yourself',
+          },
+        ],
+        initialValue: 'hetzner',
+      });
+      if (p.isCancel(choice)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+      }
+      dnsProvider = choice;
+    }
+  }
+
+  // Cloudflare selected without a saved/env token → prompt for one (and
+  // offer to persist). Under --yes we cannot prompt; fall back to manual
+  // with a clear warning.
+  if (dnsProvider === 'cloudflare' && !cloudflareApiToken) {
+    if (args.yes) {
+      p.log.warn(
+        'Cloudflare selected but no API token found (env CLOUDFLARE_API_TOKEN or ~/.vibecarbon/credentials.json). Falling back to manual DNS.',
+      );
+      dnsProvider = 'manual';
+    } else {
+      const token = await p.password({
+        message: 'Cloudflare API token:',
+        validate: (v) => (v && v.length > 0 ? undefined : 'Token is required'),
+      });
+      if (p.isCancel(token)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+      }
+      cloudflareApiToken = token;
+      const persist = await p.confirm({
+        message: 'Save token to ~/.vibecarbon/credentials.json for future deploys?',
+        initialValue: true,
+      });
+      if (!p.isCancel(persist) && persist) {
+        saveCredentials({ cloudflare: { apiToken: cloudflareApiToken } });
+        p.log.success('Cloudflare API token saved');
+      }
+    }
+  }
+
+  // Auto-discover zone IDs when a domain is already configured (config-driven
+  // re-deploys land here without prompting).
+  if (domain && dnsProvider === 'cloudflare' && !cloudflareZoneId && cloudflareApiToken) {
+    try {
+      const zones = await cloudflareGetZones(cloudflareApiToken);
+      const zone = zones.find((z) => domain.endsWith(z.name));
+      if (zone) cloudflareZoneId = zone.id;
+    } catch {
+      /* ignore */
+    }
+  }
+  if (domain && dnsProvider === 'hetzner' && !hetznerDnsZoneId) {
+    try {
+      const zones = await hetznerDnsGetZones(apiToken);
+      const zone = zones.find((z) => domain.endsWith(z.name));
+      if (zone) hetznerDnsZoneId = zone.id;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // Interactive zone-and-domain selection when no domain is configured yet.
+  // Skipped under --yes (only the auto-discovery above runs).
+  if (!args.yes) {
+    if (dnsProvider === 'cloudflare' && !cloudflareZoneId && cloudflareApiToken) {
+      try {
+        const zones = await fetchZonesWithRetry(
+          () => cloudflareGetZones(cloudflareApiToken),
+          'Cloudflare',
+        );
+        const result = await selectZoneAndDomain(zones, 'Cloudflare', domain);
+        domain = result.domain;
+        cloudflareZoneId = result.zone.id;
+      } catch (err) {
+        p.log.warn(`Cloudflare unavailable (${err.message}). Falling back to manual DNS.`);
+        dnsProvider = 'manual';
+      }
+    } else if (dnsProvider === 'hetzner' && !hetznerDnsZoneId) {
+      try {
+        const zones = await fetchZonesWithRetry(() => hetznerDnsGetZones(apiToken), 'Hetzner');
+        if (zones.length === 0) {
+          p.log.warn('No Hetzner DNS zones found on this account. Falling back to manual DNS.');
+          dnsProvider = 'manual';
+        } else {
+          const result = await selectZoneAndDomain(zones, 'Hetzner', domain);
+          domain = result.domain;
+          hetznerDnsZoneId = result.zone.id;
+        }
+      } catch (err) {
+        p.log.warn(`Hetzner DNS unavailable (${err.message}). Falling back to manual DNS.`);
+        dnsProvider = 'manual';
+      }
+    }
+  }
+
+  // S3 (Standardized)
+  let s3AccessKey = args.s3AccessKey || envConfig.s3?.accessKey;
+  let s3SecretKey = args.s3SecretKey || null;
+  // Env-var override (HETZNER_S3_REGION) sits between explicit CLI flag and
+  // project config so operators can route the Pulumi-state + backup buckets
+  // to a different Hetzner OS region during a regional incident without
+  // editing .vibecarbon.json. Mirrors HETZNER_API_TOKEN's role for the cloud
+  // API. Surfaced after 2026-04-29 nbg1 OS degradation killed both HA
+  // scenarios on Pulumi backend ops (lock delete 503, history save 504,
+  // checkpoint read conn-reset).
+  const s3Region =
+    args.s3Region ||
+    process.env.HETZNER_S3_REGION ||
+    envConfig.s3?.region ||
+    HetznerS3Provider.resolveS3Region(region);
+
+  if (!s3AccessKey) {
+    const credentials = await getS3Credentials(projectConfig.projectName);
+    s3AccessKey = credentials.accessKey;
+    s3SecretKey = credentials.secretKey;
+  }
+
+  const s3Provider = new HetznerS3Provider(s3AccessKey, s3SecretKey, s3Region);
+  const bucketName = sanitizeBucketName(projectConfig.projectName);
+  const backupBucketName = sanitizeBucketName(projectConfig.projectName, 'backups');
+  const backupConfig = {
+    schedule: args.backupSchedule || envConfig.backup?.schedule || '0 */6 * * *',
+    retentionDays: Number.parseInt(
+      args.backupRetentionDays || envConfig.backup?.retentionDays || '30',
+      10,
+    ),
+  };
+
+  const branchName = getBranchName(config.environment);
+
+  if (!args.yes && !resuming) {
+    p.note(
+      `
+Env:      ${c.bold(config.environment)}
+Region:   ${c.bold(region)}${ha ? ` + ${secondaryRegion}` : ''}
+Stack:    ${c.bold(isComposeDeploy ? 'Docker Compose' : 'Kubernetes (k3s)')}
+Domain:   ${c.bold(domain || 'None')}
+    `,
+      'Deployment Summary',
+    );
+
+    const confirmed = await p.confirm({ message: 'Proceed?', initialValue: true });
+    if (!confirmed || p.isCancel(confirmed)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  return {
+    projectConfig,
+    envConfig,
+    environment,
+    resuming,
+    config,
+    apiToken,
+    region,
+    secondaryRegion,
+    serverType,
+    masterServerType,
+    supabaseServerType,
+    workerServerType,
+    minWorkers: args.minWorkers ?? DEFAULT_WORKER_MIN,
+    maxWorkers: args.maxWorkers ?? DEFAULT_WORKER_MAX,
+    domain,
+    dnsProvider,
+    cloudflareApiToken,
+    cloudflareZoneId,
+    hetznerDnsZoneId,
+    s3Config: {
+      accessKey: s3AccessKey,
+      secretKey: s3SecretKey,
+      bucket: bucketName,
+      region: s3Region,
+      endpoint: s3Provider.getEndpoint(),
+    },
+    backupS3Config: {
+      bucket: backupBucketName,
+      region: s3Region,
+      endpoint: s3Provider.getEndpoint(),
+    },
+    backupConfig,
+    services,
+    branchName,
+  };
+}

package/src/lib/deploy/remote-build.js

@@ -0,0 +1,130 @@
+/**
+ * Remote Build Logic
+ * Uses native Docker via SSH contexts to build images directly on target architecture.
+ * Bypasses local QEMU and remote registries for maximum speed.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { runCommand } from '../command.js';
+import { perfTimer } from '../perf.js';
+
+/**
+ * Execute a remote build using native Docker over SSH
+ * @param {string} ip - Remote host IP
+ * @param {string} sshKeyPath - Path to the SSH private key
+ * @param {string} imageTag - The tag to apply to the built image
+ * @param {string} cwd - The build context directory (usually project root)
+ * @param {Record<string, string>} buildArgs - Key/value pairs for --build-arg
+ * @returns {Promise<boolean>} Success
+ */
+export async function buildRemote(ip, sshKeyPath, imageTag, cwd, buildArgs = {}) {
+  const s = p.spinner();
+  s.start(`Building image natively on ${ip}...`);
+
+  const dockerHost = `ssh://root@${ip}`;
+
+  // Create a temporary directory for our SSH wrapper
+  const tempBinDir = mkdtempSync(join(tmpdir(), 'vc-bin-'));
+  const sshWrapperPath = join(tempBinDir, 'ssh');
+
+  // Create an SSH wrapper script that forces our options. Docker uses the
+  // system 'ssh' command found in PATH — we prepend a temp dir containing
+  // this wrapper so Docker's SSH transport picks it up instead. Pass the
+  // key path via env var rather than string-interpolating into the script
+  // to keep shell-escaping concerns out of the picture (paths with spaces
+  // or quotes would otherwise break the wrapper).
+  const sshWrapper = `#!/bin/bash
+exec /usr/bin/ssh -i "$VIBECARBON_SSH_KEY" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o BatchMode=yes -o ConnectTimeout=30 "$@"
+`;
+  writeFileSync(sshWrapperPath, sshWrapper, { mode: 0o755 });
+
+  const env = {
+    ...process.env,
+    DOCKER_HOST: dockerHost,
+    DOCKER_BUILDKIT: '1',
+    PATH: `${tempBinDir}:${process.env.PATH}`, // Prepend our wrapper
+    VIBECARBON_SSH_KEY: sshKeyPath,
+  };
+
+  try {
+    // 1. Ensure the host is reachable and sshd is ready. Caller has usually
+    // already gone through setupServer/waitForDockerReady, so SSH is live by
+    // attempt 0; the fast leg [1, 1, 2, 2] catches that path quickly. Tail
+    // keeps 5s pacing for the rare genuinely slow-coming-up case.
+    // Gated under perfTimer because the SSH-probe wait is invisible to the
+    // outer `deploy.image.remoteBuild` timer (which only covers the docker
+    // build subprocess) — and analysis of iter-reliab3 showed the wrapper
+    // running 71s longer than the longest child timer, suggesting this
+    // probe loop is sometimes burning serious time we couldn't attribute.
+    const sshProbeT = perfTimer('deploy.image.remoteBuild.sshProbe');
+    const SSH_DELAYS_MS = [
+      1000, 1000, 2000, 2000, 5000, 5000, 5000, 5000, 5000, 5000, 5000, 5000, 5000, 10_000, 10_000,
+    ];
+    let sshReady = false;
+    for (let i = 0; i < SSH_DELAYS_MS.length; i++) {
+      try {
+        // Bare `ssh` resolves through PATH to the wrapper script written
+        // above (sshWrapper) which adds -i + -o BatchMode=yes etc.; the
+        // wrapper is the only `ssh` on PATH for this child process.
+        // shell-safety-ignore: ssh is the PATH-prepended wrapper, not system ssh
+        runCommand(['ssh', `root@${ip}`, 'echo', 'ready'], { silent: true, env });
+        sshReady = true;
+        break;
+      } catch {
+        await new Promise((r) => setTimeout(r, SSH_DELAYS_MS[i]));
+      }
+    }
+    sshProbeT.end();
+
+    if (!sshReady) {
+      s.stop('Remote SSH not reachable');
+      return false;
+    }
+
+    // 2. Run the build directly on the remote host via DOCKER_HOST=ssh://...
+    const args = ['docker', 'build', '-t', imageTag, '.'];
+
+    for (const [key, value] of Object.entries(buildArgs)) {
+      args.push('--build-arg', `${key}=${value}`);
+    }
+
+    // The build itself is the dominant cost on direct-mode deploys; gate it
+    // behind a perfTimer so cold (first-build, ~2-5min) vs warm (cached
+    // BuildKit, 1-3s) is attributable in the trace.
+    //
+    // runCommand without silent:true returns `false` on non-zero exit instead
+    // of throwing (see lib/command.js:135). Without this check, a failed
+    // remote build silently proceeded to `s.stop('Image built natively')`,
+    // returning true to the HA fan; the missing image then surfaced ~3 min
+    // later as `pull access denied for <project>-app` during compose up
+    // (compose-ha 2026-05-09T00:38 e2 failure). Treat the false return as a
+    // hard failure so the error path captures + reports it.
+    const buildT = perfTimer('deploy.image.remoteBuild');
+    const buildOk = runCommand(args, {
+      cwd,
+      stdio: 'inherit',
+      env,
+      timeout: 600000,
+    });
+    buildT.end();
+    if (buildOk === false) {
+      throw new Error(`docker build failed on ${ip} for tag ${imageTag}`);
+    }
+
+    s.stop(`Image built natively: ${imageTag}`);
+    return true;
+  } catch (error) {
+    s.stop(`Remote build failed`);
+    p.log.error(error.message);
+    return false;
+  } finally {
+    try {
+      rmSync(tempBinDir, { recursive: true, force: true });
+    } catch {
+      /* ignore cleanup errors */
+    }
+  }
+}