spinuptui 0.19.0

package/src/lib/cloneDomains.ts

@@ -0,0 +1,112 @@
+// Carry a site's additional domains onto its clone. A freshly created dest site
+// answers ONLY its primary domain (nginx server_name has nothing else — verified on
+// the test boxes), so without this step the DNS cutover would repoint www/extra
+// hostnames at a server that doesn't serve them. Redirect settings (enabled/type/
+// destination) are copied verbatim from the source. Idempotent: domains already on
+// the dest are skipped, so per-site retries re-run it safely.
+
+import type { SpinupWPClientLike } from "../api/client.ts"
+import type { AdditionalDomain } from "../api/types.ts"
+
+const EVENT_DONE = new Set(["deployed", "completed", "provisioned", "finished", "success"])
+const EVENT_FAIL = new Set(["failed", "errored", "error"])
+
+type PollOutcome = { outcome: "done" } | { outcome: "failed" } | { outcome: "timeout"; lastStatus?: string }
+
+// 5s cadence; a transient failure to READ the event is not the event failing —
+// tolerate a few consecutive API errors (the client already absorbs 429 bursts).
+// The timeout is a generous BACKSTOP, not an expectation: SpinupWP serializes
+// events per server, so under a concurrent clone an add-domain event can sit
+// queued for minutes behind site-creates. (The 2026-07-07 sparkmamas run sat
+// queued 173s and a flat 180s deadline declared it failed 12s before it
+// deployed — every timeout must be reported as a timeout, never as a failure.)
+export async function pollEvent(client: SpinupWPClientLike, eventId: number, timeoutMs = 1_800_000, pollMs = 5000): Promise<PollOutcome> {
+  const deadline = Date.now() + timeoutMs
+  let apiErrs = 0
+  let lastStatus: string | undefined
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollMs))
+    try {
+      const e = await client.getEvent(eventId)
+      apiErrs = 0
+      lastStatus = e.status
+      if (EVENT_FAIL.has(e.status)) return { outcome: "failed" }
+      if (EVENT_DONE.has(e.status) || e.finished_at) return { outcome: "done" }
+    } catch {
+      if (++apiErrs >= 3) return { outcome: "timeout", lastStatus }
+    }
+  }
+  // One last look before giving up — the event may have finished on the wire.
+  try {
+    const e = await client.getEvent(eventId)
+    if (EVENT_FAIL.has(e.status)) return { outcome: "failed" }
+    if (EVENT_DONE.has(e.status) || e.finished_at) return { outcome: "done" }
+    lastStatus = e.status
+  } catch {
+    /* keep the polled status */
+  }
+  return { outcome: "timeout", lastStatus }
+}
+
+export interface DomainSyncResult {
+  added: string[]
+  skipped: string[] // already present on the dest (retry path)
+  failed: { domain: string; error: string }[]
+}
+
+export async function syncAdditionalDomains(
+  client: SpinupWPClientLike,
+  destSiteId: number,
+  sourceDomains: AdditionalDomain[],
+  log?: (entry: Record<string, unknown>) => void,
+): Promise<DomainSyncResult> {
+  const result: DomainSyncResult = { added: [], skipped: [], failed: [] }
+  if (sourceDomains.length === 0) return result
+  // A failed listing falls back to "add everything" — a duplicate add errors
+  // per-domain and lands in `failed` with the API's message rather than hiding.
+  let existing = new Set<string>()
+  try {
+    existing = new Set((await client.listSiteDomains(destSiteId)).map((d) => d.domain))
+  } catch {
+    /* fall through */
+  }
+  for (const d of sourceDomains) {
+    if (existing.has(d.domain)) {
+      result.skipped.push(d.domain)
+      continue
+    }
+    try {
+      const ev = await client.addSiteDomain(destSiteId, {
+        domain: d.domain,
+        redirect: d.redirect ? { enabled: d.redirect.enabled, type: d.redirect.type, destination: d.redirect.destination } : undefined,
+      })
+      const res = await pollEvent(client, ev.event_id)
+      if (res.outcome === "done") {
+        result.added.push(d.domain)
+        log?.({ event: "domain-add", destSiteId, domain: d.domain, eventId: ev.event_id, ok: true })
+      } else if (res.outcome === "timeout") {
+        // NOT a SpinupWP failure — we stopped waiting. Retrying the site is safe
+        // (already-present domains are skipped), so point the user there.
+        const error = `gave up waiting for add-domain event ${ev.event_id}${res.lastStatus ? ` (still "${res.lastStatus}")` : ""} — it may yet finish on SpinupWP; retry the site to re-check`
+        result.failed.push({ domain: d.domain, error })
+        log?.({ event: "domain-add", destSiteId, domain: d.domain, eventId: ev.event_id, ok: false, outcome: "timeout", lastStatus: res.lastStatus })
+      } else {
+        // Pull the event's own output so the roster/log say WHY, not just "failed".
+        let out = ""
+        try {
+          out = ((await client.getEvent(ev.event_id)).output ?? "").trim()
+        } catch {
+          /* best-effort */
+        }
+        const error = `add-domain event ${ev.event_id} failed${out ? `: …${out.slice(-200)}` : " on SpinupWP"}`
+        result.failed.push({ domain: d.domain, error })
+        log?.({ event: "domain-add", destSiteId, domain: d.domain, eventId: ev.event_id, ok: false, output: out })
+      }
+    } catch (err) {
+      const error = (err as Error).message
+      result.failed.push({ domain: d.domain, error })
+      log?.({ event: "domain-add", destSiteId, domain: d.domain, ok: false, error })
+    }
+  }
+  return result
+}

package/src/lib/cloneLog.ts

@@ -0,0 +1,85 @@
+// Persistent clone-job logging (born from the 2026-07-02 web2→mercury failure,
+// where all six errors were truncated to 24 chars in the roster and lost when the
+// app closed). One JSONL file per clone job under <configDir>/logs/; every sudo
+// script the pull chains run is recorded with its full stdout/stderr so a failed
+// site can be diagnosed after the fact. Secrets (sudo + generated DB passwords)
+// are redacted before anything touches disk.
+
+import { appendFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs"
+import { join } from "node:path"
+import { configDir } from "../config.ts"
+
+// Big outputs (composer, tar) are capped; keep the TAIL — errors come last.
+const FIELD_CAP = 16_000
+
+// Retention: swept every time a new job's logger is created (the only moment the
+// app touches this dir), so nothing accumulates without a natural purge point. A
+// log survives only while it's BOTH younger than MAX_AGE and among the newest
+// MAX_LOGS. Copy a log elsewhere to keep it past retention.
+const MAX_AGE_DAYS = 30
+const MAX_LOGS = 20
+
+function pruneOldLogs(dir: string): void {
+  try {
+    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+    const logs = readdirSync(dir)
+      .filter((f) => f.startsWith("clone-") && f.endsWith(".jsonl"))
+      .map((f) => {
+        const path = join(dir, f)
+        return { path, mtime: statSync(path).mtimeMs }
+      })
+      .sort((a, b) => b.mtime - a.mtime)
+    for (const [i, l] of logs.entries()) {
+      // The new job's log is about to join — keep MAX_LOGS-1 existing at most.
+      if (l.mtime < cutoff || i >= MAX_LOGS - 1) {
+        try {
+          unlinkSync(l.path)
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+  } catch {
+    /* pruning must never break a clone */
+  }
+}
+
+export class CloneLogger {
+  readonly path: string
+  private secrets: string[] = []
+
+  constructor(label: string) {
+    const dir = join(configDir(), "logs")
+    try {
+      mkdirSync(dir, { recursive: true })
+    } catch {
+      /* logging is best-effort */
+    }
+    pruneOldLogs(dir)
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
+    const slug = label.replace(/[^a-zA-Z0-9.-]+/g, "_").slice(0, 60)
+    this.path = join(dir, `clone-${stamp}-${slug}.jsonl`)
+  }
+
+  // Register strings that must never reach disk (passwords). Call before log().
+  redact(...secrets: (string | undefined)[]): void {
+    for (const s of secrets) if (s && s.length >= 4 && !this.secrets.includes(s)) this.secrets.push(s)
+  }
+
+  private clean(v: unknown): unknown {
+    if (typeof v !== "string") return v
+    let s = v
+    for (const secret of this.secrets) s = s.split(secret).join("[redacted]")
+    return s.length > FIELD_CAP ? `…[${s.length - FIELD_CAP} chars trimmed]…${s.slice(-FIELD_CAP)}` : s
+  }
+
+  log(entry: Record<string, unknown>): void {
+    try {
+      const out: Record<string, unknown> = { ts: new Date().toISOString() }
+      for (const [k, v] of Object.entries(entry)) out[k] = this.clean(v)
+      appendFileSync(this.path, JSON.stringify(out) + "\n")
+    } catch {
+      /* never let logging break a clone */
+    }
+  }
+}

package/src/lib/dbBackup.ts

@@ -0,0 +1,198 @@
+// Download a production database backup over SSH.
+//
+// Mirrors the proven sync-prod-to-local pattern: export to a stage file OUTSIDE
+// the public webroot (in $HOME), gzip it remotely, scp it down into the linked
+// project's `sql/` dir, then remove the remote copy.
+//
+// We deliberately do NOT stream `wp db export -` to stdout: plugins print to
+// stdout during WP bootstrap (e.g. GiveWP deprecation notices), which would
+// corrupt the dump. `wp db export <file>` writes pure SQL regardless of that
+// noise. SSH is non-interactive (BatchMode) — SpinupWP sites are key-only, so
+// this works headlessly from the user's agent; a missing key fails fast.
+
+import { existsSync, mkdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import type { Server, Site } from "../api/types.ts"
+import { expandPath, type LocalLink } from "./local.ts"
+
+export const SSH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", "-o", "StrictHostKeyChecking=accept-new"]
+
+// ssh uses -p for a non-default port, scp uses -P.
+export const sshPort = (port: number | null | undefined) => (port && port !== 22 ? ["-p", String(port)] : [])
+export const scpPort = (port: number | null | undefined) => (port && port !== 22 ? ["-P", String(port)] : [])
+
+// Derive a SpinupWP site's absolute remote document root. SpinupWP serves each
+// site from `/sites/{domain}/files{public_folder}`; the API's `public_folder` is
+// only the suffix (e.g. "/public/" for standard WP, "/web/" for Bedrock), so we
+// join it onto the fixed base. wp-cli finds the install from this cwd.
+export function remoteDocRoot(domain: string, publicFolder: string | null): string {
+  const suffix = (publicFolder ?? "public").replace(/^\/+|\/+$/g, "") // strip surrounding slashes
+  const base = `/sites/${domain}/files`
+  return suffix ? `${base}/${suffix}` : base
+}
+
+const p2 = (n: number) => String(n).padStart(2, "0")
+
+// Timestamped backup base name, e.g. "hoperedefined.org_2026-06-22_1113".
+export function backupBaseName(domain: string, now: Date): string {
+  const d = `${now.getFullYear()}-${p2(now.getMonth() + 1)}-${p2(now.getDate())}`
+  const t = `${p2(now.getHours())}${p2(now.getMinutes())}`
+  return `${domain}_${d}_${t}`
+}
+
+export interface DbBackupPlan {
+  user: string
+  host: string
+  port: number | null
+  docroot: string
+  // The gzipped stage file, named relative to $HOME so scp can address it
+  // directly (e.g. "hoperedefined.org_2026-06-22_1113.sql.gz").
+  remoteGz: string
+  destDir: string // local <projectRoot>/sql
+  destPath: string // local absolute path of the downloaded .sql.gz
+}
+
+export type PlanResult = { ok: true; plan: DbBackupPlan } | { ok: false; error: string }
+
+// Resolve everything needed to run a backup, or a human-readable reason it can't
+// run. The destination lives in the linked working copy, so an unlinked (or
+// missing) local path is a hard stop.
+export function planDbBackup(
+  site: Site,
+  server: Server | undefined,
+  sshUser: string | null,
+  link: LocalLink | undefined,
+  now: Date,
+): PlanResult {
+  const host = server?.ip_address
+  const user = site.site_user ?? sshUser
+  if (!host || !user) return { ok: false, error: "Missing site user or server IP — can't reach the site." }
+  if (!link) return { ok: false, error: "Not linked — press L to link a local copy first." }
+  const dir = expandPath(link.path)
+  if (!existsSync(dir)) return { ok: false, error: "Local path is missing — press L to fix the link." }
+
+  // Drop the backup in the folder the user linked (where `t` opens a terminal),
+  // under a sql/ subdir — same convention as the sync-prod-to-local script.
+  const destDir = join(dir, "sql")
+  const remoteGz = `${backupBaseName(site.domain, now)}.sql.gz`
+  return {
+    ok: true,
+    plan: {
+      user,
+      host,
+      port: server?.ssh_port ?? null,
+      docroot: remoteDocRoot(site.domain, site.public_folder),
+      remoteGz,
+      destDir,
+      destPath: join(destDir, remoteGz),
+    },
+  }
+}
+
+export type DbBackupStage = "export" | "download" | "cleanup" | "done" | "error"
+
+export interface DbBackupProgress {
+  stage: DbBackupStage
+  domain: string
+  destPath?: string
+  bytes?: number
+  error?: string
+  failedStage?: DbBackupStage // which step broke, so the UI can mark it ✕
+}
+
+export function isDbBackupInFlight(p: DbBackupProgress | undefined): boolean {
+  return p != null && p.stage !== "done" && p.stage !== "error"
+}
+
+// Run a child process to completion, capturing output with a hard timeout. An
+// optional cwd lets callers run local `wp` in a project directory.
+export async function runProcess(
+  cmd: string[],
+  timeoutMs: number,
+  cwd?: string,
+  env?: Record<string, string>,
+): Promise<{ code: number; stderr: string }> {
+  let proc: ReturnType<typeof Bun.spawn>
+  try {
+    proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", stdin: "ignore", cwd, env })
+  } catch (err) {
+    return { code: -1, stderr: `Failed to launch ${cmd[0]}: ${(err as Error).message}` }
+  }
+  const timer = setTimeout(() => {
+    try {
+      proc.kill()
+    } catch {
+      /* already gone */
+    }
+  }, timeoutMs)
+  const code = await proc.exited
+  clearTimeout(timer)
+  const stderr = await new Response(proc.stderr as ReadableStream<Uint8Array>).text()
+  return { code, stderr }
+}
+
+// Pick a meaningful error line out of ssh/wp stderr, skipping the deprecation /
+// warning noise WordPress plugins emit during bootstrap.
+export function meaningfulError(stderr: string, fallback: string): string {
+  const lines = stderr
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .filter((l) => !/^(PHP\s+)?(Deprecated|Warning|Notice):/i.test(l))
+  return lines[lines.length - 1] || fallback
+}
+
+// Run the full backup, reporting each stage through `onProgress`. Resolves with
+// the terminal progress (done | error). Never throws.
+export async function runDbBackup(
+  plan: DbBackupPlan,
+  domain: string,
+  onProgress: (p: DbBackupProgress) => void,
+): Promise<DbBackupProgress> {
+  const target = `${plan.user}@${plan.host}`
+  const fail = (error: string, failedStage: DbBackupStage): DbBackupProgress => {
+    const p: DbBackupProgress = { stage: "error", domain, error, failedStage }
+    onProgress(p)
+    return p
+  }
+
+  // 1) Export on the remote into a $HOME stage file (outside the webroot) and
+  //    gzip it. `wp db export <file>` writes pure SQL even when plugins print to
+  //    stdout; --single-transaction avoids locking the live DB during the dump.
+  onProgress({ stage: "export", domain })
+  const sql = plan.remoteGz.replace(/\.gz$/, "") // <base>.sql
+  const remoteScript =
+    `set -e; cd '${plan.docroot}'; ` +
+    `wp db export "$HOME/${sql}" --single-transaction >/dev/null; ` +
+    `gzip -f "$HOME/${sql}"`
+  const exp = await runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, remoteScript], 300_000)
+  if (exp.code !== 0) return fail(`Remote export failed — ${meaningfulError(exp.stderr, `ssh exit ${exp.code}.`)}`, "export")
+
+  // 2) Download the gzip into the project's sql/ dir.
+  onProgress({ stage: "download", domain })
+  try {
+    mkdirSync(plan.destDir, { recursive: true })
+  } catch {
+    /* best-effort; scp surfaces a real write failure */
+  }
+  const dl = await runProcess(["scp", ...SSH_OPTS, ...scpPort(plan.port), `${target}:${plan.remoteGz}`, plan.destPath], 300_000)
+  if (dl.code !== 0) {
+    // Still try to remove the remote stage file so it doesn't linger.
+    void runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, `rm -f "$HOME/${plan.remoteGz}"`], 30_000)
+    return fail(`Download failed — ${meaningfulError(dl.stderr, `scp exit ${dl.code}.`)}`, "download")
+  }
+
+  // 3) Remove the remote stage file.
+  onProgress({ stage: "cleanup", domain })
+  await runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, `rm -f "$HOME/${plan.remoteGz}"`], 30_000)
+
+  let bytes: number | undefined
+  try {
+    bytes = statSync(plan.destPath).size
+  } catch {
+    /* file exists per scp exit 0; size is cosmetic */
+  }
+  const done: DbBackupProgress = { stage: "done", domain, destPath: plan.destPath, bytes }
+  onProgress(done)
+  return done
+}

package/src/lib/dbSync.ts

@@ -0,0 +1,253 @@
+// Pull a production database down into the local working copy.
+//
+// Builds on the DB-backup pipeline: export prod (read-only), download the gzip,
+// then IMPORT it into the LOCAL WordPress DB and rewrite URLs so the local copy
+// mirrors production. This is destructive on LOCAL (it overwrites the local DB),
+// but never writes to production — so we back up the local DB first.
+//
+// Works for Standard WP and Bedrock without configuration: local `wp` auto-
+// discovers the install from the linked project dir, and the local URL / table
+// prefix are detected from the link, the project .env, or wp-config.php. It even
+// runs an existing bin/sync.d/post-import.sh hook with the same WEB_DIR /
+// SYNC_REMOTE_HOST / SYNC_LOCAL_HOST env contract as the sync-prod-to-local
+// script, so per-project tweaks (Elementor URL swaps, plugin toggles) carry over.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs"
+import { join, dirname } from "node:path"
+import type { Server, Site } from "../api/types.ts"
+import { expandPath, findProjectRoot, type LocalLink } from "./local.ts"
+import { remoteDocRoot, backupBaseName, SSH_OPTS, sshPort, scpPort, runProcess, meaningfulError } from "./dbBackup.ts"
+
+// Read a KEY=value from a dotenv file, tolerating surrounding quotes. null if absent.
+function readEnvVar(envPath: string, key: string): string | null {
+  try {
+    const m = readFileSync(envPath, "utf8").match(new RegExp(`^\\s*${key}\\s*=\\s*(.*)\\s*$`, "m"))
+    if (!m) return null
+    return m[1].trim().replace(/^['"]|['"]$/g, "") || null
+  } catch {
+    return null
+  }
+}
+
+// Read $table_prefix from a wp-config.php (Standard WP). null if absent.
+function readWpConfigPrefix(configPath: string): string | null {
+  try {
+    const m = readFileSync(configPath, "utf8").match(/\$table_prefix\s*=\s*['"]([^'"]+)['"]/)
+    return m ? m[1] : null
+  } catch {
+    return null
+  }
+}
+
+// Bare host of a URL (drops scheme, path, trailing slash).
+function hostOf(url: string): string {
+  return url.replace(/^[a-z]+:\/\//i, "").replace(/\/.*$/, "").trim()
+}
+
+// An INERT starter post-import hook. Every real command is commented out and the
+// only live line is an echo, so scaffolding-then-pulling can't surprise anyone —
+// the user uncomments what they want deliberately. The comments document the env
+// contract (WEB_DIR / SYNC_REMOTE_HOST / SYNC_LOCAL_HOST, see runDbSync) and the
+// real-world tweaks (Elementor URL swaps, plugin toggles) the hook exists for.
+const SAMPLE_HOOK = `#!/usr/bin/env bash
+set -euo pipefail
+# Runs after Spinup pulls production → local (DB imported, URLs rewritten).
+# Spinup exports these for you:
+#   WEB_DIR           local project root (this script starts here)
+#   SYNC_REMOTE_HOST  production host, e.g. example.com
+#   SYNC_LOCAL_HOST   local host,      e.g. example.test
+cd "$WEB_DIR"
+
+# --- Examples — uncomment what your project needs ----------------------
+# Elementor stores absolute URLs in serialized data; rewrite + reflush:
+# wp elementor replace_urls "https://$SYNC_REMOTE_HOST" "https://$SYNC_LOCAL_HOST"
+# wp elementor flush_css
+#
+# Turn off prod-only plugins locally (keep non-fatal with || true):
+# wp plugin deactivate spinupwp limit-login-attempts-reloaded || true
+# wp plugin activate localdev-switcher || true
+# -----------------------------------------------------------------------
+
+echo "post-import hook ran (nothing to do yet — edit bin/sync.d/post-import.sh)"
+`
+
+// Scaffold the inert sample hook at <localRoot>/bin/sync.d/post-import.sh and
+// mark it executable. Returns the absolute path. Never overwrites an existing
+// file (callers only offer this when no hook is present). Throws on write error.
+export function writeSampleHook(localRoot: string): string {
+  const path = join(localRoot, "bin", "sync.d", "post-import.sh")
+  if (existsSync(path)) return path
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, SAMPLE_HOOK)
+  chmodSync(path, 0o755)
+  return path
+}
+
+export interface DbSyncPlan {
+  user: string
+  host: string
+  port: number | null
+  docroot: string
+  remoteGz: string // $HOME-relative gz produced on the remote
+  localRoot: string // where local `wp` runs (findProjectRoot of the link)
+  sqlDir: string // localRoot/sql
+  downloadPath: string // sqlDir/<base>.sql.gz — the prod dump, kept as a backup
+  localBackupPath: string // sqlDir/local_<ts>.sql.gz — pre-import safety dump
+  remoteOrigin: string // https://prod-domain (rewritten from)
+  localOrigin: string // local URL as entered (rewritten to)
+  remoteHost: string // bare prod host (hook env)
+  localHost: string // bare local host (hook env)
+  hookPath: string | null // bin/sync.d/post-import.sh, if present
+  prefixWarning: string | null // set when remote/local table prefixes differ
+}
+
+export type SyncPlanResult = { ok: true; plan: DbSyncPlan } | { ok: false; error: string }
+
+export function planDbSync(
+  site: Site,
+  server: Server | undefined,
+  sshUser: string | null,
+  link: LocalLink | undefined,
+  now: Date,
+): SyncPlanResult {
+  const host = server?.ip_address
+  const user = site.site_user ?? sshUser
+  if (!host || !user) return { ok: false, error: "Missing site user or server IP — can't reach the site." }
+  if (!link) return { ok: false, error: "Not linked — press L to link a local copy first." }
+  const dir = expandPath(link.path)
+  if (!existsSync(dir)) return { ok: false, error: "Local path is missing — press L to fix the link." }
+
+  const localRoot = findProjectRoot(dir)
+  const envPath = join(localRoot, ".env")
+
+  // Local origin (URL rewrite target): the linked localUrl wins; fall back to the
+  // project .env WP_HOME (Bedrock). Required — without it we'd leave prod URLs.
+  const localUrlRaw = link.localUrl?.trim() || readEnvVar(envPath, "WP_HOME") || ""
+  if (!localUrlRaw) return { ok: false, error: "No local URL — press L to set one (needed to rewrite URLs)." }
+  const localOrigin = localUrlRaw.replace(/\/+$/, "")
+  const localHost = hostOf(localOrigin)
+  const remoteHost = site.domain
+  const remoteOrigin = `${site.https?.enabled ? "https" : "http"}://${remoteHost}`
+
+  // Prefix sanity: a remote↔local table-prefix mismatch makes the imported DB
+  // unusable by local wp (search-replace would target the wrong tables). Warn.
+  const remotePrefix = site.database?.table_prefix ?? null
+  const localPrefix = readEnvVar(envPath, "DB_PREFIX") ?? readWpConfigPrefix(join(localRoot, "wp-config.php"))
+  const prefixWarning =
+    remotePrefix && localPrefix && remotePrefix !== localPrefix
+      ? `Table prefix differs (remote "${remotePrefix}" vs local "${localPrefix}") — the import may not line up.`
+      : null
+
+  const sqlDir = join(localRoot, "sql")
+  const base = backupBaseName(site.domain, now)
+  const stamp = base.slice(base.indexOf("_") + 1) // the date_time part
+  return {
+    ok: true,
+    plan: {
+      user,
+      host,
+      port: server?.ssh_port ?? null,
+      docroot: remoteDocRoot(site.domain, site.public_folder),
+      remoteGz: `${base}.sql.gz`,
+      localRoot,
+      sqlDir,
+      downloadPath: join(sqlDir, `${base}.sql.gz`),
+      localBackupPath: join(sqlDir, `local_${stamp}.sql.gz`),
+      remoteOrigin,
+      localOrigin,
+      remoteHost,
+      localHost,
+      hookPath: existsSync(join(localRoot, "bin", "sync.d", "post-import.sh"))
+        ? join(localRoot, "bin", "sync.d", "post-import.sh")
+        : null,
+      prefixWarning,
+    },
+  }
+}
+
+export type DbSyncStage = "local-backup" | "export" | "download" | "import" | "replace" | "hook" | "done" | "error"
+
+export interface DbSyncProgress {
+  stage: DbSyncStage
+  domain: string
+  downloadPath?: string
+  localBackupPath?: string
+  ranHook?: boolean
+  error?: string
+  failedStage?: DbSyncStage // which step broke, so the UI can mark it ✕
+}
+
+export function isDbSyncInFlight(p: DbSyncProgress | undefined): boolean {
+  return p != null && p.stage !== "done" && p.stage !== "error"
+}
+
+// Run the full pull, reporting each stage. Resolves with the terminal progress
+// (done | error). Never throws. Read-only on production; destructive on local.
+export async function runDbSync(plan: DbSyncPlan, domain: string, onProgress: (p: DbSyncProgress) => void): Promise<DbSyncProgress> {
+  const target = `${plan.user}@${plan.host}`
+  const fail = (error: string, failedStage: DbSyncStage = "local-backup"): DbSyncProgress => {
+    const p: DbSyncProgress = { stage: "error", domain, error, failedStage }
+    onProgress(p)
+    return p
+  }
+  // Prefix the surfaced error with the failing stage so it's self-locating
+  // (e.g. "Local DB backup failed — mysqldump: …" rather than a bare driver line).
+  const stageFail = (label: string, stderr: string, fallback: string, failedStage: DbSyncStage) =>
+    fail(`${label} — ${meaningfulError(stderr, fallback)}`, failedStage)
+  // Run local `wp` through a login shell so the user's PATH (composer/phar) resolves.
+  const wp = (cmd: string, timeoutMs: number, env?: Record<string, string>) => runProcess(["bash", "-lc", cmd], timeoutMs, plan.localRoot, env)
+
+  // 0) wp-cli must exist locally — fail with a clear message rather than cryptically.
+  if ((await wp("command -v wp", 15_000)).code !== 0) return fail("WP-CLI not found locally — install wp-cli to sync.", "local-backup")
+
+  // 1) Safety: back up the LOCAL DB before we overwrite it (file, then gzip).
+  onProgress({ stage: "local-backup", domain })
+  try {
+    mkdirSync(plan.sqlDir, { recursive: true })
+  } catch {
+    /* best-effort */
+  }
+  const localSql = plan.localBackupPath.replace(/\.gz$/, "")
+  const lb = await wp(`wp db export "${localSql}" >/dev/null && gzip -f "${localSql}"`, 300_000)
+  if (lb.code !== 0) return stageFail("Local DB backup failed", lb.stderr, "couldn't export the local database.", "local-backup")
+
+  // 2) Export prod + download the gzip (same remote pipeline as the backup).
+  onProgress({ stage: "export", domain })
+  const sql = plan.remoteGz.replace(/\.gz$/, "")
+  const remoteScript =
+    `set -e; cd '${plan.docroot}'; wp db export "$HOME/${sql}" --single-transaction >/dev/null; gzip -f "$HOME/${sql}"`
+  const exp = await runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, remoteScript], 300_000)
+  if (exp.code !== 0) return stageFail("Remote export failed", exp.stderr, `ssh exit ${exp.code}.`, "export")
+
+  onProgress({ stage: "download", domain })
+  const dl = await runProcess(["scp", ...SSH_OPTS, ...scpPort(plan.port), `${target}:${plan.remoteGz}`, plan.downloadPath], 300_000)
+  if (dl.code !== 0) {
+    void runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, `rm -f "$HOME/${plan.remoteGz}"`], 30_000)
+    return stageFail("Download failed", dl.stderr, `scp exit ${dl.code}.`, "download")
+  }
+  void runProcess(["ssh", ...SSH_OPTS, ...sshPort(plan.port), target, `rm -f "$HOME/${plan.remoteGz}"`], 30_000)
+
+  // 3) Import into local: stream gunzip → wp db cli (no temp extract).
+  onProgress({ stage: "import", domain })
+  const imp = await wp(`gunzip -c "${plan.downloadPath}" | wp db cli`, 600_000)
+  if (imp.code !== 0) return stageFail("Local import failed", imp.stderr, "wp db cli error.", "import")
+
+  // 4) Rewrite production URLs → local URLs.
+  onProgress({ stage: "replace", domain })
+  const sr = await wp(`wp search-replace "${plan.remoteOrigin}" "${plan.localOrigin}" --skip-columns=guid --format=count`, 300_000)
+  if (sr.code !== 0) return stageFail("URL search-replace failed", sr.stderr, "wp search-replace error.", "replace")
+
+  // 5) Optional per-project post-import hook (Elementor swaps, plugin toggles, …).
+  let ranHook = false
+  if (plan.hookPath) {
+    onProgress({ stage: "hook", domain })
+    const env = { ...process.env, WEB_DIR: plan.localRoot, SYNC_REMOTE_HOST: plan.remoteHost, SYNC_LOCAL_HOST: plan.localHost } as Record<string, string>
+    const hk = await runProcess(["bash", plan.hookPath], 300_000, plan.localRoot, env)
+    if (hk.code !== 0) return stageFail("Post-import hook failed", hk.stderr, "hook script error.", "hook")
+    ranHook = true
+  }
+
+  const done: DbSyncProgress = { stage: "done", domain, downloadPath: plan.downloadPath, localBackupPath: plan.localBackupPath, ranHook }
+  onProgress(done)
+  return done
+}