spinuptui 0.19.0

package/src/lib/dnsRecords.ts

@@ -0,0 +1,411 @@
+// DNS record access layer (Phase 3) — the read + first-write slice for editing a
+// site's hosting records directly at the host, since SpinupWP's API doesn't manage
+// DNS records. Mirrors the providers.ts registry shape: one descriptor per editable
+// provider, so the overlay and store stay provider-agnostic.
+//
+// This is a MIGRATION record manager, NOT a zone editor. We never enumerate a zone:
+// reads are scoped to ONE named record (`getRecord`), so by construction the module
+// can't see — let alone touch — MX/TXT/DKIM/other records. That untouchability is
+// the product's safety guarantee (move the site without knocking out email), and it
+// holds host-agnostically: Route 53 scopes via StartRecordName/Type, Cloudflare via
+// the `?name=&type=` filter.
+//
+// Two distinct writes, two distinct editability questions: `editable` gates the
+// TTL editor (well-defined only when the record HAS a real TTL — not a Route 53
+// alias, not a routing-policy set, not a Cloudflare proxied record, whose TTL is
+// forced to automatic); `valueEditable` gates the DNS-cutover origin-IP repoint
+// (defaults to `editable` when unset — Cloudflare sets it explicitly, since a
+// proxied record's VALUE stays freely PATCHable even though its TTL doesn't). A
+// non-editable record surfaces with a short reason.
+//
+// Two providers are wired: AWS Route 53 (hand-rolled SigV4; the write is an async
+// ChangeResourceRecordSets we poll to INSYNC) and Cloudflare (REST; the PATCH is
+// synchronous). GoDaddy stays a web handoff — its API is gated, like in Phase 2.
+
+import { awsGet, awsPost, type AwsCreds } from "./awsSigV4.ts"
+import type { ConnProvider } from "./providers.ts"
+
+export interface DnsRecord {
+  key: string // stable row key (Route 53: name|type; Cloudflare: record id)
+  recordId?: string // provider record id (Cloudflare PATCH target)
+  name: string // record name (trailing dot stripped)
+  type: string // A, AAAA, CNAME, MX, TXT, …
+  ttl: number | null // current TTL in seconds; null when the record carries no TTL
+  values: string[] // record value(s) — shown, and echoed back on a Route 53 upsert
+  editable: boolean // can we change THIS record's TTL?
+  // Can we repoint THIS record's value (the DNS-cutover write)? Defaults to
+  // `editable` when unset (see module comment) — only set explicitly when it
+  // differs, e.g. Cloudflare's proxied records.
+  valueEditable?: boolean
+  reason?: string // when not editable, the short why (alias / proxied / policy)
+}
+
+export interface RecordResult {
+  ok: boolean
+  zoneId: string // provider zone id (needed again for the write); "" on failure
+  record?: DnsRecord // the single requested record
+  // The zone's declared apex NS records — fuel for the edit-time NS-match gate
+  // (compare to fresh live NS). Omitted by providers whose access is already
+  // NS-matched at connect time (Cloudflare), so the gate simply doesn't apply.
+  apexNs?: string[]
+  error?: string
+}
+
+export interface ChangeResult {
+  ok: boolean
+  // Route 53 applies the change asynchronously; pollId is its change id (poll to
+  // INSYNC). Absent (Cloudflare) means the change already took effect.
+  pollId?: string
+  error?: string
+}
+
+export type ChangeStatus = "pending" | "done" | "failed"
+
+export interface RecordProvider {
+  // Read ONE named record (and return the provider zone id for the follow-up write,
+  // plus the apex NS for the edit-time gate). Scoped on purpose — we never list the
+  // whole zone.
+  getRecord(creds: Record<string, string>, apex: string, name: string, type: string): Promise<RecordResult>
+  // Change one record's TTL. `zoneId` comes from getRecord; `record` carries the
+  // values to preserve (Route 53 needs the full set on an upsert).
+  setTtl(creds: Record<string, string>, zoneId: string, record: DnsRecord, ttl: number): Promise<ChangeResult>
+  // Create (or replace) a single record name → value. Used by the vanity-site flow
+  // to add the server hostname's A record. Resolves the zone itself (no prior
+  // getRecord). Optional — providers without it fall back to a web handoff.
+  createRecord?(creds: Record<string, string>, apex: string, name: string, type: string, value: string, ttl: number): Promise<ChangeResult>
+  // Repoint one EXISTING record to a new value (the DNS cutover write). `zoneId` +
+  // `record` come from getRecord; the record's current TTL/type are preserved.
+  // Optional — providers without it fall back to a manual handoff.
+  setValue?(creds: Record<string, string>, zoneId: string, record: DnsRecord, value: string): Promise<ChangeResult>
+  // Poll an async change to completion. Only providers that return a pollId set this.
+  pollChange?(creds: Record<string, string>, pollId: string): Promise<ChangeStatus>
+}
+
+// ---- TTL presets + helpers -------------------------------------------------
+
+// Common TTLs offered in the picker. The record's current value is always shown
+// too, so any existing TTL is selectable even when it's not on this list.
+export const TTL_PRESETS: { ttl: number; label: string }[] = [
+  { ttl: 300, label: "5 minutes" },
+  { ttl: 1800, label: "30 minutes" },
+  { ttl: 3600, label: "1 hour" },
+  { ttl: 14400, label: "4 hours" },
+  { ttl: 43200, label: "12 hours" },
+  { ttl: 86400, label: "1 day" },
+]
+
+// Sane bounds for the TTL editor. Cloudflare rejects sub-60s TTLs (other than its
+// "automatic" sentinel, which the proxied/auto guard already excludes); Route 53
+// allows lower, but a 1-week ceiling keeps the custom input from fat-fingering a
+// value far outside what anyone wants here.
+const TTL_MAX = 604800 // 7 days
+const TTL_MIN: Record<ConnProvider, number> = { aws: 1, cloudflare: 60, godaddy: 60 }
+
+// Validate a custom TTL for a provider. Returns an error string, or null when ok.
+export function validateTtl(provider: ConnProvider, ttl: number): string | null {
+  if (!Number.isInteger(ttl)) return "TTL must be a whole number of seconds."
+  const min = TTL_MIN[provider]
+  if (ttl < min) return `TTL must be at least ${min}s for this provider.`
+  if (ttl > TTL_MAX) return `TTL can't exceed ${TTL_MAX}s (7 days).`
+  return null
+}
+
+// Humanize a TTL for display (e.g. 3600 → "1h", 5400 → "1h30m").
+export function formatTtl(ttl: number | null): string {
+  if (ttl == null) return "—"
+  if (ttl === 0) return "0"
+  const d = Math.floor(ttl / 86400)
+  const h = Math.floor((ttl % 86400) / 3600)
+  const m = Math.floor((ttl % 3600) / 60)
+  const s = ttl % 60
+  const parts: string[] = []
+  if (d) parts.push(`${d}d`)
+  if (h) parts.push(`${h}h`)
+  if (m) parts.push(`${m}m`)
+  if (s) parts.push(`${s}s`)
+  return parts.join("") || "0"
+}
+
+function stripDot(name: string): string {
+  return name.replace(/\.$/, "")
+}
+
+// Decode the small set of XML entities Route 53 emits in values/names.
+function xmlUnescape(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&")
+}
+
+function xmlEscape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+}
+
+// ---- AWS Route 53 ----------------------------------------------------------
+
+const R53_HOST = "route53.amazonaws.com"
+const R53_BASE = "/2013-04-01"
+
+function awsCreds(creds: Record<string, string>): AwsCreds {
+  return { accessKeyId: creds.accessKeyId ?? "", secretAccessKey: creds.secretAccessKey ?? "", region: creds.region || undefined }
+}
+
+function awsErrorMessage(xml: string): string | null {
+  return xml.match(/<Message>([^<]+)<\/Message>/)?.[1] ?? null
+}
+
+// Find the PUBLIC hosted-zone id for an apex (there can be a private zone of the
+// same name; we only edit the public one). Returns the bare id, e.g. "Z123ABC".
+async function awsZoneId(creds: AwsCreds, apex: string): Promise<{ id: string; error?: string }> {
+  const r = await awsGet(creds, "route53", R53_HOST, `${R53_BASE}/hostedzonesbyname`, { dnsname: apex, maxitems: "10" })
+  if (r.status !== 200) return { id: "", error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+  const want = stripDot(apex).toLowerCase()
+  for (const block of r.body.split(/<HostedZone>/).slice(1)) {
+    const name = block.match(/<Name>([^<]+)<\/Name>/)?.[1]
+    if (!name || stripDot(name).toLowerCase() !== want) continue
+    if (/<PrivateZone>true<\/PrivateZone>/.test(block)) continue // skip private zones
+    const id = block.match(/<Id>([^<]+)<\/Id>/)?.[1]
+    if (id) return { id: id.replace(/^\/hostedzone\//, "") }
+  }
+  return { id: "", error: `No public Route 53 hosted zone for ${want}.` }
+}
+
+function parseRoute53Records(xml: string): DnsRecord[] {
+  const out: DnsRecord[] = []
+  for (const block of xml.split(/<ResourceRecordSet>/).slice(1)) {
+    const body = block.split("</ResourceRecordSet>")[0]
+    const name = body.match(/<Name>([^<]*)<\/Name>/)?.[1]
+    const type = body.match(/<Type>([^<]*)<\/Type>/)?.[1]
+    if (!name || !type) continue
+    const ttlRaw = body.match(/<TTL>(\d+)<\/TTL>/)?.[1]
+    const isAlias = /<AliasTarget>/.test(body)
+    const setId = body.match(/<SetIdentifier>([^<]*)<\/SetIdentifier>/)?.[1]
+    const values = [...body.matchAll(/<Value>([\s\S]*?)<\/Value>/g)].map((m) => xmlUnescape(m[1]))
+    let editable = true
+    let reason: string | undefined
+    if (isAlias) {
+      editable = false
+      reason = "alias"
+    } else if (setId != null) {
+      editable = false
+      reason = "routing policy"
+    } else if (ttlRaw == null) {
+      editable = false
+      reason = "no TTL"
+    }
+    const display = stripDot(xmlUnescape(name))
+    out.push({
+      key: `${display}|${type}|${setId ?? ""}`,
+      name: display,
+      type,
+      ttl: ttlRaw != null ? Number(ttlRaw) : null,
+      values: isAlias ? ["(alias)"] : values,
+      editable,
+      reason,
+    })
+  }
+  return out
+}
+
+// Scoped read: ListResourceRecordSets starting at a name+type returns records AT or
+// AFTER that name, so we ask for a few and pick the exact match (never the zone).
+async function r53RecordAt(creds: AwsCreds, zoneId: string, name: string, type: string): Promise<{ ok: boolean; records: DnsRecord[]; error?: string }> {
+  const r = await awsGet(creds, "route53", R53_HOST, `${R53_BASE}/hostedzone/${zoneId}/rrset`, { name, type, maxitems: "5" })
+  if (r.status !== 200) return { ok: false, records: [], error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+  return { ok: true, records: parseRoute53Records(r.body) }
+}
+
+const route53: RecordProvider = {
+  async getRecord(rawCreds, apex, name, type) {
+    const creds = awsCreds(rawCreds)
+    const zone = await awsZoneId(creds, apex)
+    if (!zone.id) return { ok: false, zoneId: "", error: zone.error }
+    const want = stripDot(name).toLowerCase()
+    const got = await r53RecordAt(creds, zone.id, name, type)
+    if (!got.ok) return { ok: false, zoneId: "", error: got.error }
+    const record = got.records.find((r) => r.name.toLowerCase() === want && r.type === type)
+    if (!record) return { ok: false, zoneId: "", error: `No ${type} record for ${want} in this zone.` }
+    // A second scoped read for the apex NS (the edit-time NS-match gate compares it
+    // to the fresh live NS). Failure here just disables the gate, never the edit.
+    const apexLc = stripDot(apex).toLowerCase()
+    const nsGot = await r53RecordAt(creds, zone.id, apex, "NS")
+    const apexNs = nsGot.records.find((r) => r.type === "NS" && r.name.toLowerCase() === apexLc)?.values ?? []
+    return { ok: true, zoneId: zone.id, record, apexNs }
+  },
+
+  async setTtl(rawCreds, zoneId, record, ttl) {
+    const creds = awsCreds(rawCreds)
+    // UPSERT replaces the whole record set, so echo the existing values back with
+    // the new TTL — anything omitted would be dropped.
+    const valuesXml = record.values.map((v) => `<ResourceRecord><Value>${xmlEscape(v)}</Value></ResourceRecord>`).join("")
+    const body =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<ChangeResourceRecordSetsRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">` +
+      `<ChangeBatch><Comment>spinup: set TTL to ${ttl}</Comment><Changes><Change>` +
+      `<Action>UPSERT</Action><ResourceRecordSet>` +
+      `<Name>${xmlEscape(record.name)}</Name><Type>${record.type}</Type><TTL>${ttl}</TTL>` +
+      `<ResourceRecords>${valuesXml}</ResourceRecords>` +
+      `</ResourceRecordSet></Change></Changes></ChangeBatch>` +
+      `</ChangeResourceRecordSetsRequest>`
+    const r = await awsPost(creds, "route53", R53_HOST, `${R53_BASE}/hostedzone/${zoneId}/rrset/`, body)
+    if (r.status !== 200) return { ok: false, error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+    const changeId = r.body.match(/<Id>([^<]+)<\/Id>/)?.[1]?.replace(/^\/change\//, "")
+    return { ok: true, pollId: changeId }
+  },
+
+  async createRecord(rawCreds, apex, name, type, value, ttl) {
+    const creds = awsCreds(rawCreds)
+    const zone = await awsZoneId(creds, apex)
+    if (!zone.id) return { ok: false, error: zone.error }
+    // UPSERT creates the record, or replaces it if the exact name+type already
+    // exists (the vanity host is purpose-built, so a collision means re-point it
+    // at this server — what we want). The confirm overlay shows the exact write.
+    const body =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<ChangeResourceRecordSetsRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">` +
+      `<ChangeBatch><Comment>spinup: create ${type} ${stripDot(name)}</Comment><Changes><Change>` +
+      `<Action>UPSERT</Action><ResourceRecordSet>` +
+      `<Name>${xmlEscape(stripDot(name))}</Name><Type>${type}</Type><TTL>${ttl}</TTL>` +
+      `<ResourceRecords><ResourceRecord><Value>${xmlEscape(value)}</Value></ResourceRecord></ResourceRecords>` +
+      `</ResourceRecordSet></Change></Changes></ChangeBatch>` +
+      `</ChangeResourceRecordSetsRequest>`
+    const r = await awsPost(creds, "route53", R53_HOST, `${R53_BASE}/hostedzone/${zone.id}/rrset/`, body)
+    if (r.status !== 200) return { ok: false, error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+    const changeId = r.body.match(/<Id>([^<]+)<\/Id>/)?.[1]?.replace(/^\/change\//, "")
+    return { ok: true, pollId: changeId }
+  },
+
+  async setValue(rawCreds, zoneId, record, value) {
+    const creds = awsCreds(rawCreds)
+    // UPSERT the record to the new single value, preserving its TTL (A records carry
+    // one; fall back to 300 if somehow absent). Type/name unchanged → a clean repoint.
+    const ttl = record.ttl ?? 300
+    const body =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<ChangeResourceRecordSetsRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/">` +
+      `<ChangeBatch><Comment>spinup: repoint ${stripDot(record.name)} to ${value}</Comment><Changes><Change>` +
+      `<Action>UPSERT</Action><ResourceRecordSet>` +
+      `<Name>${xmlEscape(record.name)}</Name><Type>${record.type}</Type><TTL>${ttl}</TTL>` +
+      `<ResourceRecords><ResourceRecord><Value>${xmlEscape(value)}</Value></ResourceRecord></ResourceRecords>` +
+      `</ResourceRecordSet></Change></Changes></ChangeBatch>` +
+      `</ChangeResourceRecordSetsRequest>`
+    const r = await awsPost(creds, "route53", R53_HOST, `${R53_BASE}/hostedzone/${zoneId}/rrset/`, body)
+    if (r.status !== 200) return { ok: false, error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+    const changeId = r.body.match(/<Id>([^<]+)<\/Id>/)?.[1]?.replace(/^\/change\//, "")
+    return { ok: true, pollId: changeId }
+  },
+
+  async pollChange(rawCreds, pollId) {
+    const creds = awsCreds(rawCreds)
+    const r = await awsGet(creds, "route53", R53_HOST, `${R53_BASE}/change/${pollId}`)
+    if (r.status !== 200) return "failed"
+    return /<Status>INSYNC<\/Status>/.test(r.body) ? "done" : "pending"
+  },
+}
+
+// ---- Cloudflare ------------------------------------------------------------
+
+const CF_API = "https://api.cloudflare.com/client/v4"
+
+function cfHeaders(token: string): Record<string, string> {
+  return { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }
+}
+
+function cfError(json: { errors?: { message?: string }[] } | undefined, status: number): string {
+  return json?.errors?.[0]?.message || `HTTP ${status}`
+}
+
+async function cfZoneId(token: string, apex: string): Promise<{ id: string; error?: string }> {
+  const res = await fetch(`${CF_API}/zones?name=${encodeURIComponent(apex)}`, { headers: cfHeaders(token) })
+  const json = (await res.json().catch(() => undefined)) as { success?: boolean; result?: { id: string }[]; errors?: { message?: string }[] } | undefined
+  if (!res.ok || !json?.success) return { id: "", error: cfError(json, res.status) }
+  const id = json.result?.[0]?.id
+  return id ? { id } : { id: "", error: `No Cloudflare zone for ${apex}.` }
+}
+
+const cloudflare: RecordProvider = {
+  async getRecord(rawCreds, apex, name, type) {
+    const token = rawCreds.token ?? ""
+    const zone = await cfZoneId(token, apex)
+    if (!zone.id) return { ok: false, zoneId: "", error: zone.error }
+    // Scoped read: filter to the one record by name+type (never the whole zone).
+    const url = `${CF_API}/zones/${zone.id}/dns_records?name=${encodeURIComponent(stripDot(name))}&type=${encodeURIComponent(type)}`
+    const res = await fetch(url, { headers: cfHeaders(token) })
+    const json = (await res.json().catch(() => undefined)) as
+      | { success?: boolean; errors?: { message?: string }[]; result?: { id: string; type: string; name: string; content: string; ttl: number; proxied?: boolean }[] }
+      | undefined
+    if (!res.ok || !json?.success) return { ok: false, zoneId: "", error: cfError(json, res.status) }
+    const r = json.result?.[0]
+    if (!r) return { ok: false, zoneId: "", error: `No ${type} record for ${stripDot(name)} in this zone.` }
+    const proxied = r.proxied === true
+    const record: DnsRecord = {
+      key: r.id,
+      recordId: r.id,
+      name: stripDot(r.name),
+      type: r.type,
+      ttl: r.ttl === 1 ? null : r.ttl, // 1 = Cloudflare "automatic"
+      values: [r.content],
+      editable: !proxied,
+      // The origin-IP PATCH (setValue) only ever touches `content`, leaving
+      // `proxied` untouched — so it works identically whether proxied or not,
+      // even though the TTL editor above stays blocked for a proxied record.
+      valueEditable: true,
+      reason: proxied ? "proxied" : undefined,
+    }
+    // apexNs omitted — Cloudflare access is already NS-matched at connect time.
+    return { ok: true, zoneId: zone.id, record }
+  },
+
+  async setTtl(rawCreds, zoneId, record, ttl) {
+    const token = rawCreds.token ?? ""
+    if (!record.recordId) return { ok: false, error: "Missing Cloudflare record id." }
+    const res = await fetch(`${CF_API}/zones/${zoneId}/dns_records/${record.recordId}`, {
+      method: "PATCH",
+      headers: cfHeaders(token),
+      body: JSON.stringify({ ttl }),
+    })
+    const json = (await res.json().catch(() => undefined)) as { success?: boolean; errors?: { message?: string }[] } | undefined
+    if (!res.ok || !json?.success) return { ok: false, error: cfError(json, res.status) }
+    return { ok: true } // Cloudflare applies synchronously
+  },
+
+  async setValue(rawCreds, zoneId, record, value) {
+    const token = rawCreds.token ?? ""
+    if (!record.recordId) return { ok: false, error: "Missing Cloudflare record id." }
+    // PATCH only the content — name/type/ttl/proxied stay as configured.
+    const res = await fetch(`${CF_API}/zones/${zoneId}/dns_records/${record.recordId}`, {
+      method: "PATCH",
+      headers: cfHeaders(token),
+      body: JSON.stringify({ content: value }),
+    })
+    const json = (await res.json().catch(() => undefined)) as { success?: boolean; errors?: { message?: string }[] } | undefined
+    if (!res.ok || !json?.success) return { ok: false, error: cfError(json, res.status) }
+    return { ok: true } // Cloudflare applies synchronously
+  },
+}
+
+// ---- Registry --------------------------------------------------------------
+
+const RECORD_PROVIDERS: Partial<Record<ConnProvider, RecordProvider>> = {
+  aws: route53,
+  cloudflare,
+}
+
+// The record provider for a connection provider, or null when records aren't
+// API-editable for it (e.g. GoDaddy → web handoff).
+export function recordProviderFor(provider: ConnProvider): RecordProvider | null {
+  return RECORD_PROVIDERS[provider] ?? null
+}
+
+// The TTL the picker should show as "current" for a record whose live TTL is null
+// (Cloudflare auto): default the custom field to a sensible 1h starting point.
+export function defaultTtlFor(record: DnsRecord): number {
+  return record.ttl ?? 3600
+}

package/src/lib/format.ts

@@ -0,0 +1,106 @@
+// Pure formatting helpers — bytes, dates, relative time, truncation, bars.
+
+export function formatBytes(bytes: number | null | undefined, decimals = 1): string {
+  if (bytes == null || isNaN(bytes)) return "—"
+  if (bytes === 0) return "0 B"
+  const k = 1000 // SpinupWP reports disk space in decimal (GB), so use base-1000
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"]
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1)
+  const value = bytes / Math.pow(k, i)
+  return `${value.toFixed(i === 0 ? 0 : decimals)} ${sizes[i]}`
+}
+
+// Percentage of disk used (0–100). Returns 0 when unknown.
+export function diskUsedPct(used?: number | null, total?: number | null): number {
+  if (!total || total <= 0 || used == null) return 0
+  return Math.min(100, Math.max(0, (used / total) * 100))
+}
+
+// A unicode progress bar, e.g. ████████░░░░ for a given fraction.
+export function bar(fraction: number, width = 12): string {
+  const clamped = Math.min(1, Math.max(0, fraction))
+  const filled = Math.round(clamped * width)
+  return "█".repeat(filled) + "░".repeat(width - filled)
+}
+
+export function formatDate(iso: string | null | undefined): string {
+  if (!iso) return "—"
+  const d = new Date(iso)
+  if (isNaN(d.getTime())) return "—"
+  return d.toLocaleString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  })
+}
+
+// Human relative time, e.g. "3m ago", "2h ago", "5d ago".
+export function timeAgo(iso: string | null | undefined): string {
+  if (!iso) return "—"
+  const d = new Date(iso)
+  if (isNaN(d.getTime())) return "—"
+  const secs = Math.floor((Date.now() - d.getTime()) / 1000)
+  if (secs < 0) return "soon"
+  if (secs < 60) return `${secs}s ago`
+  const mins = Math.floor(secs / 60)
+  if (mins < 60) return `${mins}m ago`
+  const hours = Math.floor(mins / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  if (days < 30) return `${days}d ago`
+  const months = Math.floor(days / 30)
+  if (months < 12) return `${months}mo ago`
+  return `${Math.floor(months / 12)}y ago`
+}
+
+// Compact uptime, e.g. "36d 5h", "5h 12m", "3m".
+export function formatUptime(secs: number | null | undefined): string {
+  if (!secs || secs < 0) return "—"
+  const d = Math.floor(secs / 86400)
+  const h = Math.floor((secs % 86400) / 3600)
+  const m = Math.floor((secs % 3600) / 60)
+  if (d > 0) return `${d}d ${h}h`
+  if (h > 0) return `${h}h ${m}m`
+  return `${m}m`
+}
+
+const SPARK_CHARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+
+// Render a series (0..max) as a unicode sparkline of the most recent `width` points.
+export function sparkline(values: number[], width = 30, max = 100): string {
+  if (values.length === 0) return ""
+  const recent = values.slice(-width)
+  return recent
+    .map((v) => {
+      const frac = Math.min(1, Math.max(0, v / max))
+      return SPARK_CHARS[Math.min(SPARK_CHARS.length - 1, Math.round(frac * (SPARK_CHARS.length - 1)))]
+    })
+    .join("")
+}
+
+// Truncate the MIDDLE, keeping the head and tail — for long paths/filenames where
+// both ends matter (e.g. ".../app/sql/site_2026-06-22.sql.gz").
+export function middleTruncate(s: string, max: number): string {
+  if (s.length <= max) return s
+  if (max <= 1) return s.slice(0, Math.max(0, max))
+  const keep = max - 1 // room for the ellipsis
+  const head = Math.ceil(keep / 2)
+  const tail = Math.floor(keep / 2)
+  return s.slice(0, head) + "…" + s.slice(s.length - tail)
+}
+
+export function truncate(s: string | null | undefined, max: number): string {
+  if (!s) return ""
+  if (s.length <= max) return s
+  if (max <= 1) return s.slice(0, max)
+  return s.slice(0, max - 1) + "…"
+}
+
+// Right-pad a string to a fixed visible width (for column alignment).
+export function padEndVis(s: string, width: number): string {
+  const len = s.length
+  if (len >= width) return s
+  return s + " ".repeat(width - len)
+}

package/src/lib/gitStatus.ts

@@ -0,0 +1,37 @@
+// Local git drift for a linked working copy — Phase 4b.
+//
+// Network-free on purpose (no `git fetch`): we only report what's knowable
+// instantly from the local repo — uncommitted changes (dirty) and commits not
+// yet pushed to the upstream (ahead). Together these answer "do I have local
+// work that isn't deployed yet?". "Behind remote" is intentionally omitted (it
+// needs a network fetch + possibly SSH auth, against the app's no-slow-ops rule).
+
+import { expandPath, findProjectRoot } from "./local.ts"
+
+export interface Drift {
+  dirty: boolean // uncommitted working-tree changes
+  ahead: number // commits ahead of the upstream (0 if none / no upstream)
+}
+
+async function git(cwd: string, args: string[]): Promise<{ ok: boolean; out: string }> {
+  try {
+    const proc = Bun.spawn(["git", "-C", cwd, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore" })
+    const out = await new Response(proc.stdout).text()
+    const code = await proc.exited
+    return { ok: code === 0, out: out.trim() }
+  } catch {
+    return { ok: false, out: "" }
+  }
+}
+
+// Compute drift for a link's stored path. Resolves the actual repo root (which
+// may be nested, e.g. app/). Returns null when the path isn't a git repo.
+export async function gitDrift(linkPath: string): Promise<Drift | null> {
+  const dir = findProjectRoot(expandPath(linkPath))
+  const inside = await git(dir, ["rev-parse", "--is-inside-work-tree"])
+  if (!inside.ok || inside.out !== "true") return null
+  const status = await git(dir, ["status", "--porcelain"])
+  const dirty = status.out.length > 0
+  const ahead = await git(dir, ["rev-list", "--count", "@{u}..HEAD"])
+  return { dirty, ahead: ahead.ok ? parseInt(ahead.out, 10) || 0 : 0 }
+}

package/src/lib/jobs.ts

@@ -0,0 +1,32 @@
+// Resumable-job persistence — the shared mechanism described in
+// docs/2026-06-24_clone-to-server-spec.md ("Resumable jobs"). Long-running,
+// fire-and-forget jobs (server create today; clone/dbSync/phpUpgrade next) mirror
+// their state to config.json so a quit/relaunch can re-attach a poller via the
+// stored `eventId` instead of forgetting the work.
+//
+// Only in-flight jobs are persisted; they're removed once terminal. Writes are
+// deliberately rare (once when the job's event id is known, once on completion) —
+// intermediate status is re-fetched on resume, so it needn't be stored.
+
+import { loadConfig, saveConfig, type StoredJob } from "../config.ts"
+
+export type { StoredJob }
+
+// Upsert a job into the persisted set (read-modify-write; saveConfig merges).
+export async function saveJob(job: StoredJob): Promise<void> {
+  const jobs = { ...loadConfig().jobs, [job.id]: job }
+  await saveConfig({ jobs })
+}
+
+// Remove a job from the persisted set. No-op when it isn't present.
+export async function removeJob(id: string): Promise<void> {
+  const jobs = { ...loadConfig().jobs }
+  if (!(id in jobs)) return
+  delete jobs[id]
+  await saveConfig({ jobs })
+}
+
+// A persisted job is in-flight unless it has settled.
+export function isJobInFlight(job: StoredJob | undefined): boolean {
+  return job != null && job.status !== "done" && job.status !== "failed"
+}

package/src/lib/keychain.ts

@@ -0,0 +1,49 @@
+// macOS Keychain storage for sudo passwords (opt-in), via the built-in `security`
+// CLI — zero dependencies, service-scoped to one item per server. The password lives
+// ONLY in the Keychain + the in-memory session ref; it never touches config.json.
+//
+// Off macOS this no-ops (keychainAvailable() === false) and sudo stays in-memory per
+// session, exactly as before. NOTE: `security add-generic-password` takes the password
+// as an argv value (-w), so it's briefly visible to `ps` on the local machine during
+// the write — acceptable for an opt-in convenience on a personal box; documented here.
+
+const SERVICE = "spinup-sudo"
+
+export function keychainAvailable(): boolean {
+  return process.platform === "darwin"
+}
+
+function account(serverId: number): string {
+  return `server-${serverId}`
+}
+
+async function security(args: string[]): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["security", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+    const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited])
+    return { ok: code === 0, stdout, stderr }
+  } catch (err) {
+    return { ok: false, stdout: "", stderr: (err as Error).message }
+  }
+}
+
+// Store (or update) a server's sudo password. Returns false off macOS / on failure.
+export async function setSudoPassword(serverId: number, password: string): Promise<boolean> {
+  if (!keychainAvailable()) return false
+  const r = await security(["add-generic-password", "-U", "-s", SERVICE, "-a", account(serverId), "-w", password])
+  return r.ok
+}
+
+// Retrieve a server's sudo password, or null if absent / denied / off macOS. The first
+// read of an item may surface macOS's own "allow access" prompt (then Always Allow).
+export async function getSudoPassword(serverId: number): Promise<string | null> {
+  if (!keychainAvailable()) return null
+  const r = await security(["find-generic-password", "-s", SERVICE, "-a", account(serverId), "-w"])
+  return r.ok ? r.stdout.replace(/\n+$/, "") : null
+}
+
+// Remove a server's stored sudo password (best-effort).
+export async function deleteSudoPassword(serverId: number): Promise<void> {
+  if (!keychainAvailable()) return
+  await security(["delete-generic-password", "-s", SERVICE, "-a", account(serverId)])
+}