spinuptui 0.19.0

package/src/lib/serverCreate.ts

@@ -0,0 +1,161 @@
+// Pure helpers for the "create a server" flow (backlog item 5, build 1).
+// No I/O — the API calls live in the client; the orchestration in the store.
+// Here: map a source server's provider/specs onto the provider metadata catalog,
+// format specs + cost, and suggest a server name from the existing fleet.
+
+import type { Server, ProviderMetadata, ProviderSize, ProviderRegion } from "../api/types.ts"
+
+// The provider keys the API recognizes for metadata + create.
+export type ProviderKey = "digitalocean" | "vultr" | "linode" | "hetzner"
+export const PROVIDER_KEYS: ProviderKey[] = ["digitalocean", "vultr", "linode", "hetzner"]
+
+// All regions across continents, flattened in catalog order (for the picker).
+export function allRegions(md: ProviderMetadata | undefined): ProviderRegion[] {
+  if (!md) return []
+  return Object.values(md.regions).flat()
+}
+
+// A sensible default region (first available, else first overall).
+export function firstRegion(md: ProviderMetadata | undefined): ProviderRegion | undefined {
+  const all = allRegions(md)
+  return all.find((r) => r.available !== false) ?? all[0]
+}
+
+// Normalize the API's free-form provider_name ("DigitalOcean", "Akamai/Linode",
+// "Hetzner Cloud") to the key the metadata + create endpoints use.
+export function providerKeyFromName(name: string | null | undefined): ProviderKey | null {
+  const n = (name ?? "").toLowerCase()
+  if (n.includes("digitalocean") || n.includes("digital ocean")) return "digitalocean"
+  if (n.includes("vultr")) return "vultr"
+  if (n.includes("linode") || n.includes("akamai")) return "linode"
+  if (n.includes("hetzner")) return "hetzner"
+  return null
+}
+
+// A human label for a provider key (for the form + confirm screens).
+export function providerLabel(key: ProviderKey): string {
+  return { digitalocean: "DigitalOcean", vultr: "Vultr", linode: "Linode", hetzner: "Hetzner" }[key]
+}
+
+export function sizeBySlug(md: ProviderMetadata | undefined, slug: string | null | undefined): ProviderSize | undefined {
+  if (!md || !slug) return undefined
+  return md.sizes.find((s) => s.slug === slug)
+}
+
+// Flatten the continent-grouped regions to find one by slug. Case-insensitive
+// because a Server's `region` comes back as a code ("HIL") while the metadata
+// slugs are lowercase ("hil").
+export function regionBySlug(md: ProviderMetadata | undefined, slug: string | null | undefined): ProviderRegion | undefined {
+  if (!md || !slug) return undefined
+  const target = slug.toLowerCase()
+  for (const group of Object.values(md.regions)) {
+    const hit = group.find((r) => r.slug.toLowerCase() === target)
+    if (hit) return hit
+  }
+  return undefined
+}
+
+// Parse a Server's human-readable `size` ("8 GB / 4 vCPUs") into specs. The API
+// returns this display string, NOT a size slug, so matching to the catalog is by
+// vCPU + memory rather than by slug.
+export function parseSizeSpec(display: string | null | undefined): { vcpus: number | null; memoryMb: number | null } {
+  const d = display ?? ""
+  const mem = /(\d+(?:\.\d+)?)\s*(gb|mb)/i.exec(d)
+  const memoryMb = mem ? Math.round(parseFloat(mem[1]) * (/gb/i.test(mem[2]) ? 1024 : 1)) : null
+  const cpu = /(\d+)\s*v?cpu/i.exec(d)
+  const vcpus = cpu ? parseInt(cpu[1], 10) : null
+  return { vcpus, memoryMb }
+}
+
+// Match a vCPU+memory spec to the closest size slug from a CANDIDATE list. Pass
+// the region's available sizes (sizesForRegion) — NOT the whole catalog — so we
+// never match a size that isn't offered in the chosen region. (A provider can have
+// several sizes with identical specs across region-specific lines, e.g. Hetzner's
+// EU-only `cx33` vs the global `cpx31`, both 4 vCPU / 8 GB; matching globally can
+// pick one the region doesn't sell, which then gets dropped.) This is the basis
+// for carrying a chosen spec across providers when switching. Returns null only
+// when the candidate list is empty.
+export function matchSizeBySpec(sizes: ProviderSize[], vcpus: number | null, memoryMb: number | null): string | null {
+  if (sizes.length === 0) return null
+  const byCpu = vcpus != null ? sizes.filter((s) => s.vcpus === vcpus) : []
+  const pool = byCpu.length ? byCpu : sizes
+  if (memoryMb == null) return pool[0].slug
+  let best = pool[0]
+  let bestDiff = Infinity
+  for (const s of pool) {
+    const diff = Math.abs(s.memory - memoryMb)
+    if (diff < bestDiff) {
+      bestDiff = diff
+      best = s
+    }
+  }
+  return best.slug
+}
+
+// Convenience: match a Server's display `size` string ("8 GB / 4 vCPUs") against a
+// candidate list.
+export function matchSizeSlug(sizes: ProviderSize[], display: string | null | undefined): string | null {
+  const { vcpus, memoryMb } = parseSizeSpec(display)
+  return matchSizeBySpec(sizes, vcpus, memoryMb)
+}
+
+// The sizes a given region offers, as full size objects, in catalog order.
+// Falls back to all sizes if the region isn't found (older/unknown region slug).
+export function sizesForRegion(md: ProviderMetadata | undefined, regionSlug: string | null | undefined): ProviderSize[] {
+  if (!md) return []
+  const region = regionBySlug(md, regionSlug)
+  if (!region) return md.sizes
+  const allowed = new Set(region.sizes)
+  const inRegion = md.sizes.filter((s) => allowed.has(s.slug))
+  return inRegion.length ? inRegion : md.sizes
+}
+
+// "2 vCPU / 4 GB / 80 GB" — memory comes back in MB.
+export function formatSize(s: ProviderSize): string {
+  const mem = s.memory >= 1024 ? `${Math.round(s.memory / 1024)} GB` : `${s.memory} MB`
+  return `${s.vcpus} vCPU / ${mem} / ${s.disk} GB`
+}
+
+// "$8.49/mo" (+ backups when enabled and priced).
+export function formatCost(s: ProviderSize | undefined, backups = false): string {
+  if (!s || typeof s.priceMonthly !== "number") return "—"
+  let total = s.priceMonthly
+  if (backups && typeof s.backupPriceMonthly === "number") total += s.backupPriceMonthly
+  return `$${total.toFixed(2)}/mo`
+}
+
+// Parse a name into (prefix, number, suffix) when it has a numbered component,
+// e.g. "web11.example.com" → ["web", 11, ".example.com"]. Null when unnumbered.
+function parseNumbered(name: string): { prefix: string; num: number; suffix: string } | null {
+  const m = /^(.*?)(\d+)(\D.*)?$/.exec(name ?? "")
+  if (!m) return null
+  return { prefix: m[1], num: Number(m[2]), suffix: m[3] ?? "" }
+}
+
+// Suggest the next server name from the fleet's naming convention. Detects a
+// numbered pattern (prefix + number + optional suffix, e.g. "web11.example.com")
+// and proposes the next in the dominant series ("web12.example.com"). Returns ""
+// when no numbered convention is detectable — the user names it themselves.
+export function suggestServerName(servers: Server[]): string {
+  // Group numbered names by (prefix, suffix); track the count + the max number.
+  const groups = new Map<string, { prefix: string; suffix: string; max: number; count: number }>()
+  for (const s of servers) {
+    const p = parseNumbered(s.name ?? "")
+    if (!p) continue
+    const key = JSON.stringify([p.prefix, p.suffix]) // unambiguous composite key
+    const g = groups.get(key)
+    if (!g) groups.set(key, { prefix: p.prefix, suffix: p.suffix, max: p.num, count: 1 })
+    else {
+      g.max = Math.max(g.max, p.num)
+      g.count += 1
+    }
+  }
+  if (groups.size === 0) return ""
+  // Prefer the convention used by the most servers; break ties by higher number.
+  let best: { prefix: string; suffix: string; max: number; count: number } | null = null
+  for (const g of groups.values()) {
+    if (!best || g.count > best.count || (g.count === best.count && g.max > best.max)) best = g
+  }
+  if (!best) return ""
+  return `${best.prefix}${best.max + 1}${best.suffix}`
+}

package/src/lib/siteDoctor.ts

@@ -0,0 +1,260 @@
+// The site doctor (site monitoring Phase 2) — an on-demand, READ-ONLY diagnosis
+// of the "200 OK but wrong page" failure class. Pure HTTP: no SSH, no Kuma, no
+// writes, so it works on any site with zero setup.
+//
+// The centerpiece is the cache differential. SpinupWP's nginx page cache
+// answers with `fastcgi-cache: HIT|MISS|BYPASS` and honors the default
+// `wordpress_no_cache` cookie exclusion (both verified live on production
+// boxes, and the header set is what the spinupwp plugin registers with WP
+// core's Site Health page-cache test). So the doctor fetches the page twice —
+// once normally (cache-eligible) and once with the bypass cookie (same URL,
+// only the cache layer differs) — and compares WP's body_class() template
+// tokens between the two. A mismatch is PROOF the cache is serving a different
+// template than PHP renders right now: the purge-fixable condition, diagnosed
+// rather than guessed. The headers tell us which layer answered each request,
+// so the differential asserts its own validity instead of assuming it.
+//
+// Verdict precedence: down > partial-outage > stale-cache > recalibrate >
+// healthy, with "inconclusive" when the evidence doesn't support any of them.
+// The doctor ends at diagnosis + a copyable runbook — deliberately no auto-heal
+// (the operator does the surgery; builder-specific lines appear only on
+// positive evidence in the served markup).
+
+import { bodyClassOf } from "./siteFingerprint.ts"
+
+export interface DoctorCheck {
+  label: string
+  status: "ok" | "warn" | "bad" | "info"
+  detail: string
+}
+
+// "partial-outage" is the nastiest verdict: cached pages serve 200 while fresh
+// renders (or the wp-admin door) throw 5xx — anonymous visitors look fine, but
+// admins, logged-in users and everything uncached is failing. Verified real:
+// SpinupWP's default object-cache drop-in makes a dead Redis FATAL on every
+// page-cache miss, and a plugin/theme fatal produces the same signature.
+// Page-watching monitors sleep straight through it; this is where the doctor
+// catches it.
+export type DoctorVerdict = "healthy" | "stale-cache" | "recalibrate" | "partial-outage" | "down" | "inconclusive"
+
+export interface DoctorReport {
+  verdict: DoctorVerdict
+  summary: string
+  checks: DoctorCheck[]
+  runbook: string[] // shell lines (plus comments) when something is fixable; empty otherwise
+}
+
+interface Probe {
+  ok: boolean
+  status: number
+  ms: number
+  html: string
+  cache: string | null // fastcgi-cache header, uppercased
+  bypassReason: string | null
+  error?: string
+}
+
+const FETCH_TIMEOUT_MS = 20_000
+const MAX_HTML_BYTES = 512 * 1024
+
+// The body_class() tokens that identify WHICH template won — the set the
+// differential compares. Cosmetic/theme classes are deliberately excluded so a
+// plugin adding a class doesn't read as a template change.
+const TEMPLATE_TOKEN =
+  /^(home|blog|front-page|search|search-results|search-no-results|error404|single|singular|page|archive|category|tag|author|date|attachment|page-id-\d+|postid-\d+|single-[a-z0-9_-]+)$/
+
+async function probe(url: string, cookie?: string): Promise<Probe> {
+  const started = performance.now()
+  try {
+    const res = await fetch(url, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: {
+        "user-agent": "spinup-tui (site doctor)",
+        "cache-control": "no-store",
+        ...(cookie ? { cookie } : {}),
+      },
+    })
+    const html = (await res.text()).slice(0, MAX_HTML_BYTES)
+    return {
+      ok: res.ok,
+      status: res.status,
+      ms: Math.round(performance.now() - started),
+      html,
+      cache: res.headers.get("fastcgi-cache")?.toUpperCase() ?? null,
+      bypassReason: res.headers.get("fastcgi-cache-bypass-reason"),
+    }
+  } catch (err) {
+    return { ok: false, status: 0, ms: Math.round(performance.now() - started), html: "", cache: null, bypassReason: null, error: (err as Error).message }
+  }
+}
+
+function templateTokens(html: string): string[] | null {
+  const cls = bodyClassOf(html)
+  if (!cls) return null
+  const tokens = cls.tokens.filter((t) => TEMPLATE_TOKEN.test(t)).sort()
+  return tokens.length > 0 ? tokens : null
+}
+
+export async function runSiteDoctor(opts: {
+  url: string
+  expectedKeyword?: string | null // the calibrated fingerprint, when one exists
+  pageCacheEnabled?: boolean | null // from the SpinupWP API; null = unknown
+  sshTarget?: string | null // "site_user@host" for the runbook's ssh line
+  isWordPress?: boolean // enables the wp-login.php door probe
+  loginPath?: string // where the login lives (Bedrock relocates it to /wp/wp-login.php)
+}): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = []
+  const runbook: string[] = []
+
+  const partialOutageRunbook = (why: string) => {
+    if (opts.sshTarget) runbook.push(`ssh ${opts.sshTarget}`)
+    runbook.push("tail -n 50 ~/logs/*error*.log   # the fatal will be here")
+    runbook.push(`# ${why}`)
+    runbook.push("# front pages are cached, so visitors look fine — admins and logged-in users are not")
+  }
+
+  const cached = await probe(opts.url)
+  if (!cached.ok) {
+    checks.push({ label: "reachability", status: "bad", detail: cached.error ?? `answered ${cached.status}` })
+    return { verdict: "down", summary: "The site isn't answering — this isn't a cache problem.", checks, runbook }
+  }
+  checks.push({ label: "reachability", status: "ok", detail: `200 in ${cached.ms}ms` })
+
+  const fresh = await probe(opts.url, "wordpress_no_cache=1")
+
+  // What layer served the plain request?
+  if (cached.cache === "HIT") {
+    checks.push({ label: "page cache", status: "ok", detail: "served from the page cache (HIT)" })
+  } else if (cached.cache) {
+    checks.push({ label: "page cache", status: "info", detail: `${cached.cache} — freshly rendered, nothing stale to compare` })
+  } else if (opts.pageCacheEnabled === false) {
+    checks.push({ label: "page cache", status: "info", detail: "disabled for this site (per SpinupWP)" })
+  } else {
+    checks.push({ label: "page cache", status: "warn", detail: "no fastcgi-cache header — cache layer not verifiable here" })
+  }
+
+  // Did the bypass actually bypass? The header proves it either way. With the
+  // page cache off, every render is fresh and there's nothing to bypass — that
+  // is expected state, not a warning.
+  const cacheOff = opts.pageCacheEnabled === false && !cached.cache
+  const bypassConfirmed = fresh.ok && fresh.cache === "BYPASS"
+  if (bypassConfirmed) {
+    checks.push({ label: "bypass", status: "ok", detail: `fresh render confirmed (BYPASS: ${fresh.bypassReason ?? "cookie"}) in ${fresh.ms}ms` })
+  } else if (cacheOff && fresh.ok) {
+    checks.push({ label: "bypass", status: "info", detail: "page cache off — every render is already fresh" })
+  } else if (fresh.ok) {
+    checks.push({ label: "bypass", status: "warn", detail: `couldn't confirm a fresh render (${fresh.cache ?? "no cache header"}) — differential unverified` })
+  } else if (fresh.status >= 500 || fresh.status === 0) {
+    // Cached 200 + fresh 5xx IS the partial outage (verified live: a dead Redis
+    // is fatal on cache misses with SpinupWP's default drop-in; a plugin/theme
+    // fatal looks identical). Nothing further is measurable — diagnose and stop.
+    checks.push({ label: "fresh render", status: "bad", detail: fresh.error ?? `PHP fails when the cache is bypassed (HTTP ${fresh.status})` })
+    partialOutageRunbook("if the server's redis monitor is red, Redis is the cause; otherwise it's a PHP fatal")
+    return {
+      verdict: "partial-outage",
+      summary: "Cached pages serve fine, but fresh renders are failing — a partial outage the cached-page monitors can't see.",
+      checks,
+      runbook,
+    }
+  } else {
+    checks.push({ label: "bypass", status: "warn", detail: `bypass request answered ${fresh.status} — differential unverified` })
+  }
+
+  // The differential: cached template identity vs freshly rendered identity.
+  const cachedTokens = templateTokens(cached.html)
+  const freshTokens = fresh.ok ? templateTokens(fresh.html) : null
+  let staleCache = false
+  if (cached.cache === "HIT" && bypassConfirmed && cachedTokens && freshTokens) {
+    if (cachedTokens.join(" ") === freshTokens.join(" ")) {
+      checks.push({ label: "template", status: "ok", detail: `cached and fresh renders agree (${freshTokens.slice(0, 3).join(" ")})` })
+    } else {
+      staleCache = true
+      checks.push({ label: "template", status: "bad", detail: `cached says “${cachedTokens.join(" ")}” but PHP renders “${freshTokens.join(" ")}”` })
+    }
+  } else if (cachedTokens && freshTokens) {
+    checks.push({ label: "template", status: "info", detail: `both renders show “${freshTokens.slice(0, 3).join(" ")}” (differential not provable this pass)` })
+  } else {
+    checks.push({ label: "template", status: "info", detail: "no body_class() tokens to compare — theme doesn't emit them" })
+  }
+
+  // The calibrated fingerprint, when the site has one.
+  let recalibrate = false
+  if (opts.expectedKeyword) {
+    const inCached = cached.html.includes(opts.expectedKeyword)
+    const inFresh = fresh.ok ? fresh.html.includes(opts.expectedKeyword) : null
+    if (inCached) {
+      checks.push({ label: "fingerprint", status: "ok", detail: "calibrated fingerprint present on the live page" })
+    } else if (inFresh) {
+      staleCache = true
+      checks.push({ label: "fingerprint", status: "bad", detail: "missing from the cached page but present in a fresh render" })
+    } else {
+      recalibrate = true
+      checks.push({ label: "fingerprint", status: "warn", detail: "gone from the live site entirely — the page changed, not the cache" })
+    }
+  }
+
+  // The wp-admin door. A fatal confined to admin-facing code produces "site
+  // serves fine, wp-admin shows the critical-error screen" — a real incident
+  // shape. /wp-login.php is never page-cached (default `wp-.*.php` path
+  // exclusion) and renders through a full WP load, so a 5xx here is unambiguous.
+  // Anything else non-200 (basic auth, relocated login, hardening) is normal
+  // protection — report it, judge nothing.
+  let loginFatal = false
+  if (opts.isWordPress) {
+    let loginUrl: string | null = null
+    try {
+      loginUrl = new URL(opts.loginPath ?? "/wp-login.php", opts.url).toString()
+    } catch {
+      // Unparseable base URL — skip the probe.
+    }
+    if (loginUrl) {
+      const login = await probe(loginUrl)
+      if (login.ok) {
+        checks.push({ label: "wp-admin door", status: "ok", detail: `login page renders (${login.ms}ms)` })
+      } else if (login.status >= 500) {
+        loginFatal = true
+        checks.push({ label: "wp-admin door", status: "bad", detail: `login page throws HTTP ${login.status} — admin-facing fatal` })
+      } else if (login.status > 0) {
+        checks.push({ label: "wp-admin door", status: "info", detail: `answered ${login.status} — protected or relocated; can't judge` })
+      } else {
+        checks.push({ label: "wp-admin door", status: "warn", detail: login.error ?? "login probe failed" })
+      }
+    }
+  }
+
+  if (fresh.ok) {
+    checks.push({
+      label: "timing",
+      status: "info",
+      detail: cached.cache === "HIT" ? `cached ${cached.ms}ms · uncached ${fresh.ms}ms` : `renders: ${cached.ms}ms · ${fresh.ms}ms`,
+    })
+  }
+
+  if (loginFatal) {
+    partialOutageRunbook("the front end renders fine — the fatal is in admin-facing code (a plugin's admin hooks, most likely)")
+    return {
+      verdict: "partial-outage",
+      summary: "The site serves fine, but wp-admin is throwing a fatal — visitors won't notice; you can't log in.",
+      checks,
+      runbook,
+    }
+  }
+  if (staleCache) {
+    // Builder-specific runbook lines only on positive evidence in the markup.
+    const elementor = /wp-content\/plugins\/elementor\/|elementor-kit-\d/.test(fresh.ok ? fresh.html : cached.html)
+    if (opts.sshTarget) runbook.push(`ssh ${opts.sshTarget}`)
+    if (elementor) runbook.push("wp elementor flush_css   # elementor detected — this also purges SpinupWP's caches")
+    else runbook.push("wp spinupwp cache purge-site")
+    runbook.push("# or: press P on this site (purge via API), then re-run d")
+    return { verdict: "stale-cache", summary: "The page cache is serving a different page than PHP renders — purge it.", checks, runbook }
+  }
+  if (recalibrate) {
+    return { verdict: "recalibrate", summary: "The site renders fine but no longer matches its calibrated fingerprint — press f to recalibrate.", checks, runbook }
+  }
+  if (cachedTokens || opts.expectedKeyword) {
+    const proved = cached.cache === "HIT" && bypassConfirmed
+    return { verdict: "healthy", summary: proved ? "Serving the right page, and the cache agrees with a fresh render." : "Serving the right page.", checks, runbook }
+  }
+  return { verdict: "inconclusive", summary: "Reachable, but there's no template identity or fingerprint to judge against.", checks, runbook }
+}

package/src/lib/siteFingerprint.ts

@@ -0,0 +1,108 @@
+// Derive a template-identity fingerprint from a site's LIVE front page — the
+// calibration step behind the front-page Kuma monitor (site monitoring Phase 1).
+//
+// Why not a hand-picked headline keyword: content is the one thing a site owner
+// is allowed to change, so a headline monitor breaks the day someone edits the
+// copy. WordPress instead stamps the winning template into body_class() on every
+// request (`home` / `page-id-N` / `front-page` vs `search` / `error404`), so a
+// template-derived token catches "the page cache is serving the wrong page" —
+// verified live 2026-07-04: a page-cache incident served `class="search …"`
+// where `class="home …"` belonged, with HTTP 200 the whole time.
+//
+// The candidate ladder (most → least distinctive) is read from what the page
+// ACTUALLY serves right now — the page is presumed healthy at calibration time:
+//   1. body class starting with `home`/`blog` → `class="home` (prefix-anchored,
+//      can't false-match in prose)
+//   2. a `page-id-N` token → `page-id-N`
+//   3. a `front-page` token → `front-page`
+//   4. the canonical <link> tag → its exact text
+// Non-WP sites and body_class-less themes fall down the ladder naturally
+// (canonical), and a page with none of these reports WHY instead of registering
+// a junk monitor.
+//
+// Validation: a throwaway search URL (`?s=…` — bypasses the page cache and, on
+// WP, renders a different template) is fetched and the chosen keyword must be
+// ABSENT there; a keyword that also matches the search template couldn't
+// discriminate. Sites that ignore `?s=` (serve the same page back) make the
+// probe inconclusive — the fingerprint is then accepted unvalidated, with a note.
+
+export interface Fingerprint {
+  kind: "body-class" | "canonical"
+  keyword: string // the literal substring the Kuma keyword monitor asserts
+  detail: string // human-readable description for the overlay / done message
+}
+
+export type DeriveResult = { ok: true; fingerprint: Fingerprint; validated: boolean; note?: string } | { ok: false; error: string }
+
+const FETCH_TIMEOUT_MS = 20_000
+// The body tag and canonical link live near the top of the document; capping the
+// read keeps a pathological page from ballooning memory.
+const MAX_HTML_BYTES = 512 * 1024
+
+async function fetchHtml(url: string): Promise<{ ok: true; html: string } | { ok: false; error: string }> {
+  try {
+    const res = await fetch(url, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { "user-agent": "spinup-tui (front-page fingerprint calibration)" },
+    })
+    if (!res.ok) return { ok: false, error: `The page answered ${res.status} — calibrate while it's healthy.` }
+    return { ok: true, html: (await res.text()).slice(0, MAX_HTML_BYTES) }
+  } catch (err) {
+    return { ok: false, error: `Couldn't fetch ${url}: ${(err as Error).message}` }
+  }
+}
+
+export function bodyClassOf(html: string): { quote: string; tokens: string[] } | null {
+  const body = html.match(/<body[^>]*>/i)?.[0]
+  if (!body) return null
+  const cls = body.match(/class\s*=\s*(?:"([^"]*)"|'([^']*)')/i)
+  if (!cls) return null
+  const value = (cls[1] ?? cls[2] ?? "").trim()
+  if (!value) return null
+  return { quote: cls[1] != null ? '"' : "'", tokens: value.split(/\s+/) }
+}
+
+function candidatesFrom(html: string): Fingerprint[] {
+  const out: Fingerprint[] = []
+  const cls = bodyClassOf(html)
+  if (cls) {
+    const first = cls.tokens[0]
+    if (first === "home" || first === "blog") {
+      out.push({ kind: "body-class", keyword: `class=${cls.quote}${first}`, detail: `body class “${first}”` })
+    }
+    const pageId = cls.tokens.find((t) => /^page-id-\d+$/.test(t))
+    if (pageId) out.push({ kind: "body-class", keyword: pageId, detail: `body class “${pageId}”` })
+    if (cls.tokens.includes("front-page")) out.push({ kind: "body-class", keyword: "front-page", detail: "body class “front-page”" })
+  }
+  const canonical = html.match(/<link[^>]*rel=["']canonical["'][^>]*>/i)?.[0]
+  // A canonical tag is only a usable keyword when it's a sane length (some SEO
+  // plugins emit data-bloated tags that would make a brittle, unreadable match).
+  if (canonical && canonical.length <= 300) out.push({ kind: "canonical", keyword: canonical, detail: "canonical link tag" })
+  return out
+}
+
+export async function deriveFingerprint(homeUrl: string): Promise<DeriveResult> {
+  const home = await fetchHtml(homeUrl)
+  if (!home.ok) return { ok: false, error: home.error }
+  const candidates = candidatesFrom(home.html)
+  if (candidates.length === 0) {
+    return { ok: false, error: "No template fingerprint on the front page (no WP body classes or canonical link) — this site would need a hand-made keyword monitor in Kuma." }
+  }
+
+  const sep = homeUrl.includes("?") ? "&" : "?"
+  const probe = await fetchHtml(`${homeUrl}${sep}s=spinup-fingerprint-probe`)
+  if (!probe.ok) return { ok: true, fingerprint: candidates[0]!, validated: false, note: "comparison probe unreachable — fingerprint unvalidated" }
+
+  const homeCls = bodyClassOf(home.html)
+  const probeCls = bodyClassOf(probe.html)
+  if (homeCls && probeCls && homeCls.tokens.join(" ") === probeCls.tokens.join(" ")) {
+    // The site serves the same page for `?s=` (no search feature) — the probe
+    // can't tell a distinctive keyword from a useless one.
+    return { ok: true, fingerprint: candidates[0]!, validated: false, note: "site ignores search URLs — fingerprint unvalidated" }
+  }
+
+  const distinct = candidates.find((c) => !probe.html.includes(c.keyword))
+  if (distinct) return { ok: true, fingerprint: distinct, validated: true }
+  return { ok: false, error: "Every candidate fingerprint also appears on a non-front page — nothing distinctive to monitor." }
+}

package/src/lib/spinupweb.ts

@@ -0,0 +1,33 @@
+// Deep links into the SpinupWP web app.
+//
+// A recurring pattern: when the API can't *act* on something (e.g. it exposes
+// `upgrade_required` but has no upgrade endpoint), give the user a one-keystroke
+// jump to the exact page in SpinupWP where they can. URLs are account-scoped:
+//
+//   https://spinupwp.app/{accountSlug}/servers/{id}
+//   https://spinupwp.app/{accountSlug}/sites/{id}
+//
+// The API doesn't expose the account slug, so it comes from config. Without it
+// we fall back to the dashboard root rather than guessing a broken URL.
+
+const WEB_BASE = "https://spinupwp.app"
+
+export function serverWebUrl(id: number, accountSlug: string | null): string {
+  return accountSlug ? `${WEB_BASE}/${accountSlug}/servers/${id}` : WEB_BASE
+}
+
+export function siteWebUrl(id: number, accountSlug: string | null): string {
+  return accountSlug ? `${WEB_BASE}/${accountSlug}/sites/${id}` : WEB_BASE
+}
+
+// Account Settings → Server Providers (where the server_provider ids live).
+export function serverProvidersSettingsUrl(accountSlug: string | null): string {
+  return accountSlug ? `${WEB_BASE}/${accountSlug}/settings#server-providers` : WEB_BASE
+}
+
+// A site's SFTP & SSH section — where you add an SSH key to the SITE USER so
+// Spinup can connect to that site (the vanity flow deep-links here for the manual
+// key step). The key is per-site, not a server sudo user.
+export function siteSftpUrl(id: number, accountSlug: string | null): string {
+  return accountSlug ? `${WEB_BASE}/${accountSlug}/sites/${id}#sftp` : WEB_BASE
+}