spinuptui 0.19.0

package/src/lib/probe.ts

@@ -0,0 +1,183 @@
+// Tier-2 stack probe: on-demand SSH inspection of a single site's filesystem to
+// NAME what Tier-1 can only bucket (especially Non-WP apps) and read the WP
+// version. This is the authoritative layer over the public_folder heuristic in
+// `stack.ts`.
+//
+// SpinupWP on-disk layout (verified live): the site's system user (`site_user`)
+// home dir IS the site root; the project lives at `$HOME/files` and the webroot
+// is `$HOME/files` + the site's `public_folder` (e.g. `/public/`, `/web/`, `/`).
+//
+//   WHMCS     → webroot has configuration.php AND vendor/whmcs/
+//   Bedrock   → files-root composer.json references roots/bedrock (or config/application.php)
+//   Laravel   → files-root has artisan
+//   WordPress → `wp core version` run from the webroot (works for Bedrock too,
+//               via the site's wp-cli.yml), with a wp-includes/version.php fallback
+//
+// Strictly read-only and non-interactive (BatchMode), exactly like the health
+// view's SSH usage.
+
+import type { Server, Site } from "../api/types.ts"
+import { theme } from "./theme.ts"
+
+export type ProbeKind = "wordpress" | "bedrock" | "whmcs" | "laravel" | "static" | "unknown"
+
+// `onSelection` brightens the colors that are too low-contrast on the focused
+// (bright-green) selection background — green-on-green and the faint greys.
+export function probeKindColor(kind: ProbeKind, onSelection = false): string {
+  switch (kind) {
+    case "wordpress":
+      return theme.accent
+    case "bedrock":
+      return onSelection ? theme.text : theme.good
+    case "whmcs":
+      return theme.purple
+    case "laravel":
+      return theme.warn
+    case "static":
+      return onSelection ? theme.text : theme.textDim
+    case "unknown":
+      return onSelection ? theme.text : theme.textFaint
+  }
+}
+
+export interface ProbeResult {
+  kind: ProbeKind
+  app: string // app family: "WordPress" | "Bedrock" | "WHMCS" | "Laravel" | "Unknown"
+  version: string | null // WP/app version when known
+  label: string // display label, e.g. "WHMCS", "WordPress 7.0", "Bedrock · WP 6.9.4"
+}
+
+export type ProbeOutcome =
+  | { ok: true; target: string; result: ProbeResult }
+  | { ok: false; target: string; error: string }
+
+// Per-site SSH target. Unlike the health view (which connects as any site_user
+// on the server), a probe must run as THIS site's user so `$HOME` is its dir.
+export function resolveSiteSshTarget(site: Site, server: Server | undefined, sshUser: string | null): string {
+  const ip = server?.ip_address
+  if (!ip) return ""
+  const user = sshUser || site.site_user || "root"
+  return `${user}@${ip}`
+}
+
+const SSH_OPTS = [
+  "-o", "BatchMode=yes",
+  "-o", "ConnectTimeout=7",
+  "-o", "StrictHostKeyChecking=accept-new",
+  "-o", "ControlMaster=auto",
+  "-o", "ControlPath=/tmp/spinup-cm-%r@%h:%p",
+  "-o", "ControlPersist=30s",
+]
+
+// public_folder comes from the API; restrict it to a safe path charset before
+// embedding it in the remote command. Anything unexpected falls back to "/".
+function safePublicFolder(pf: string | null): string {
+  if (!pf || !/^[A-Za-z0-9/_.-]*$/.test(pf)) return "/"
+  return pf
+}
+
+function buildRemoteScript(publicFolder: string | null): string {
+  const pf = safePublicFolder(publicFolder)
+  return [
+    'F="$HOME/files"',
+    `W="$HOME/files${pf}"`,
+    'echo ===BEDROCK; grep -q "roots/bedrock" "$F/composer.json" 2>/dev/null && echo yes || echo no',
+    'echo ===APPLICATION; test -f "$F/config/application.php" && echo yes || echo no',
+    'echo ===ARTISAN; test -f "$F/artisan" && echo yes || echo no',
+    'echo ===WHMCSCONF; test -f "$W/configuration.php" && echo yes || echo no',
+    'echo ===WHMCSVENDOR; test -d "$W/vendor/whmcs" && echo yes || echo no',
+    'echo ===WPVERSION; (cd "$W" 2>/dev/null && wp core version 2>/dev/null) || grep -oE "wp_version = .[0-9.]+" "$W/wp-includes/version.php" 2>/dev/null | grep -oE "[0-9][0-9.]*" | head -1',
+    'echo ===INDEXHTML; test -f "$W/index.html" && echo yes || echo no',
+    'echo ===INDEXPHP; test -f "$W/index.php" && echo yes || echo no',
+    "echo ===END",
+  ].join("; ")
+}
+
+export async function probeSite(
+  site: Site,
+  server: Server | undefined,
+  sshUser: string | null,
+): Promise<ProbeOutcome> {
+  const target = resolveSiteSshTarget(site, server, sshUser)
+  if (!target) return { ok: false, target: "(no IP)", error: "Site's server has no IP address." }
+
+  let proc: ReturnType<typeof Bun.spawn>
+  try {
+    proc = Bun.spawn(["ssh", ...SSH_OPTS, target, buildRemoteScript(site.public_folder)], {
+      stdout: "pipe",
+      stderr: "pipe",
+      stdin: "ignore",
+    })
+  } catch (err) {
+    return { ok: false, target, error: `Failed to launch ssh: ${(err as Error).message}` }
+  }
+
+  const timeout = setTimeout(() => {
+    try {
+      proc.kill()
+    } catch {
+      /* already gone */
+    }
+  }, 15000)
+
+  const exitCode = await proc.exited
+  clearTimeout(timeout)
+  const stdout = await new Response(proc.stdout as ReadableStream<Uint8Array>).text()
+  const stderr = await new Response(proc.stderr as ReadableStream<Uint8Array>).text()
+
+  if (exitCode !== 0 || !stdout.includes("===END")) {
+    const reason = stderr.trim().split("\n").slice(-2).join(" ") || `ssh exited with code ${exitCode}`
+    return { ok: false, target, error: reason }
+  }
+
+  return { ok: true, target, result: classify(parseSections(stdout)) }
+}
+
+// Parse the labelled `===KEY` sections into single trimmed string values.
+function parseSections(out: string): Record<string, string> {
+  const sections: Record<string, string[]> = {}
+  let current = ""
+  for (const rawLine of out.split("\n")) {
+    const line = rawLine.replace(/\r$/, "")
+    const m = line.match(/^===([A-Z0-9]+)$/)
+    if (m) {
+      current = m[1]
+      sections[current] = []
+    } else if (current) {
+      sections[current].push(line)
+    }
+  }
+  const flat: Record<string, string> = {}
+  for (const [k, lines] of Object.entries(sections)) flat[k] = lines.join("\n").trim()
+  return flat
+}
+
+// Turn raw signals into a named stack. Order matters: name the distinctive apps
+// (WHMCS, Bedrock, Laravel) before falling back to a generic WordPress version.
+export function classify(sig: Record<string, string>): ProbeResult {
+  const wpVersion = sig.WPVERSION ? sig.WPVERSION.trim() || null : null
+
+  if (sig.WHMCSCONF === "yes" && sig.WHMCSVENDOR === "yes") {
+    return { kind: "whmcs", app: "WHMCS", version: null, label: "WHMCS" }
+  }
+  if (sig.BEDROCK === "yes" || sig.APPLICATION === "yes") {
+    return {
+      kind: "bedrock",
+      app: "Bedrock",
+      version: wpVersion,
+      label: wpVersion ? `Bedrock · WP ${wpVersion}` : "Bedrock",
+    }
+  }
+  if (sig.ARTISAN === "yes") {
+    return { kind: "laravel", app: "Laravel", version: null, label: "Laravel" }
+  }
+  if (wpVersion) {
+    return { kind: "wordpress", app: "WordPress", version: wpVersion, label: `WordPress ${wpVersion}` }
+  }
+  // No recognized server-side app: an index.html with no index.php is a static
+  // site. Stay conservative — anything ambiguous remains "Unknown".
+  if (sig.INDEXHTML === "yes" && sig.INDEXPHP !== "yes") {
+    return { kind: "static", app: "Static HTML", version: null, label: "Static HTML" }
+  }
+  return { kind: "unknown", app: "Unknown", version: null, label: "Unknown" }
+}

package/src/lib/providers.ts

@@ -0,0 +1,284 @@
+// DNS provider access layer (Phase 2, read-only verification) — a small registry
+// so adding a provider is one entry, not edits across the app.
+//
+// Two namespaces meet here:
+//   - host providerKey (from dns.ts): who answers DNS live — route53 | cloudflare
+//     | godaddy | <fallback domain> …  (what the HOST column shows)
+//   - connection provider: who we can hold credentials for — see ConnProvider
+// apiProviderFor() bridges them via each descriptor's `hostKeys`.
+//
+// "Verify" = list the zones a credential can actually see (and, where the API
+// returns them for free, each zone's assigned nameservers). That data drives the
+// ACCESS column: a zone is editable only when a connected account of the SAME
+// provider that hosts it contains it — and, when nameservers are known, only when
+// they match the live authoritative NS (so a stale/duplicate zone doesn't count).
+
+import { awsGet } from "./awsSigV4.ts"
+
+export type ConnProvider = "aws" | "cloudflare" | "godaddy"
+
+// A stored credential for a provider. `creds` is a provider-specific bag (the
+// descriptor's `fields` define its keys); secrets live in config.json (0600).
+export interface Connection {
+  id: string
+  provider: ConnProvider
+  label: string
+  creds: Record<string, string>
+  env?: boolean // sourced from environment (read-only in the UI)
+}
+
+export interface VerifiedZone {
+  apex: string
+  account: string // account identifier/name as the provider reports it
+  nameservers: string[] // assigned NS (lowercased, sorted); [] when the API didn't return them
+}
+
+export interface VerifyResult {
+  ok: boolean
+  zones: VerifiedZone[]
+  accountLabel: string // a default connection label derived from the account(s) seen
+  error?: string
+}
+
+// A credential field rendered in the connect form (besides the always-present label).
+export interface ProviderField {
+  name: string // key in Connection.creds
+  label: string
+  secret?: boolean // render masked (SecretInput)
+  optional?: boolean
+  placeholder?: string
+}
+
+export interface ProviderDescriptor {
+  key: ConnProvider
+  name: string // e.g. "AWS (Route 53)"
+  hostKeys: string[] // dns.ts providerKeys that map to this connection provider
+  fields: ProviderField[]
+  guidance: string // help line under the form
+  // Optional web handoff for the "no API access" fallback (e.g. GoDaddy, whose API
+  // is gated to large accounts). When set, an unconnected zone shows `↗ web` instead
+  // of `○ needs key`, and the connect overlay offers `w` to open `console`.
+  console?: string
+  consoleLabel?: string // button/hint text for the handoff (default "web console")
+  // Longer in-overlay note shown when `console` is set — explains the assumed
+  // access model + the handoff flow.
+  accessNote?: string
+  verify: (creds: Record<string, string>) => Promise<VerifyResult>
+}
+
+function normApex(name: string): string {
+  return name.trim().toLowerCase().replace(/\.$/, "")
+}
+
+// Normalize a nameserver set for comparison: lowercase, drop trailing dots, sort.
+export function normNameservers(ns: string[] | undefined): string[] {
+  return (ns ?? []).map((s) => s.trim().toLowerCase().replace(/\.$/, "")).filter(Boolean).sort()
+}
+
+export function nameserversMatch(a: string[], b: string[]): boolean {
+  if (a.length === 0 || b.length === 0) return false
+  if (a.length !== b.length) return false
+  return a.every((v, i) => v === b[i])
+}
+
+// ---- Cloudflare ------------------------------------------------------------
+
+async function verifyCloudflare(creds: Record<string, string>): Promise<VerifyResult> {
+  const token = creds.token ?? ""
+  try {
+    const zones: VerifiedZone[] = []
+    const accounts = new Set<string>()
+    let page = 1
+    let totalPages = 1
+    do {
+      const res = await fetch(`https://api.cloudflare.com/client/v4/zones?per_page=50&page=${page}`, {
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      })
+      const json = (await res.json()) as {
+        success?: boolean
+        errors?: { message?: string }[]
+        result?: { name: string; name_servers?: string[]; account?: { name?: string } }[]
+        result_info?: { total_pages?: number }
+      }
+      if (!res.ok || !json.success) {
+        return { ok: false, zones: [], accountLabel: "", error: json?.errors?.[0]?.message || `HTTP ${res.status}` }
+      }
+      for (const z of json.result ?? []) {
+        zones.push({ apex: normApex(z.name), account: z.account?.name ?? "", nameservers: normNameservers(z.name_servers) })
+        if (z.account?.name) accounts.add(z.account.name)
+      }
+      totalPages = json.result_info?.total_pages ?? 1
+      page++
+    } while (page <= totalPages)
+    const accountLabel = accounts.size === 1 ? [...accounts][0] : accounts.size > 1 ? `${accounts.size} accounts` : "Cloudflare"
+    return { ok: true, zones, accountLabel }
+  } catch (err) {
+    return { ok: false, zones: [], accountLabel: "", error: (err as Error).message }
+  }
+}
+
+// ---- AWS Route 53 (hand-rolled SigV4) --------------------------------------
+
+function awsErrorMessage(xml: string): string | null {
+  return xml.match(/<Message>([^<]+)<\/Message>/)?.[1] ?? null
+}
+
+async function verifyAws(creds: Record<string, string>): Promise<VerifyResult> {
+  const aws = { accessKeyId: creds.accessKeyId ?? "", secretAccessKey: creds.secretAccessKey ?? "", region: creds.region || undefined }
+  try {
+    const sts = await awsGet(aws, "sts", "sts.amazonaws.com", "/", { Action: "GetCallerIdentity", Version: "2011-06-15" })
+    if (sts.status !== 200) {
+      return { ok: false, zones: [], accountLabel: "", error: awsErrorMessage(sts.body) || `STS HTTP ${sts.status}` }
+    }
+    const accountId = sts.body.match(/<Account>([^<]+)<\/Account>/)?.[1] ?? ""
+
+    // Route 53 ListHostedZones (paginate). We deliberately do NOT fetch each
+    // zone's nameservers (GetHostedZone is one call per zone and Route 53 caps at
+    // ~5 req/s — 27s+ for a large account). AWS zones therefore use membership-
+    // based access (provider-scoped); nameservers stay [] → NS-match falls back.
+    const zones: VerifiedZone[] = []
+    let marker: string | undefined
+    do {
+      const query: Record<string, string> = { maxitems: "100" }
+      if (marker) query.marker = marker
+      const r = await awsGet(aws, "route53", "route53.amazonaws.com", "/2013-04-01/hostedzone", query)
+      if (r.status !== 200) {
+        return { ok: false, zones: [], accountLabel: "", error: awsErrorMessage(r.body) || `Route 53 HTTP ${r.status}` }
+      }
+      for (const block of r.body.split(/<HostedZone>/).slice(1)) {
+        const name = block.match(/<Name>([^<]+)<\/Name>/)?.[1]
+        if (name) zones.push({ apex: normApex(name), account: accountId, nameservers: [] })
+      }
+      marker = /<IsTruncated>true<\/IsTruncated>/.test(r.body)
+        ? r.body.match(/<NextMarker>([^<]+)<\/NextMarker>/)?.[1]
+        : undefined
+    } while (marker)
+
+    return { ok: true, zones, accountLabel: accountId || "AWS" }
+  } catch (err) {
+    return { ok: false, zones: [], accountLabel: "", error: (err as Error).message }
+  }
+}
+
+// ---- GoDaddy (header auth, no signing) -------------------------------------
+
+async function verifyGodaddy(creds: Record<string, string>): Promise<VerifyResult> {
+  const key = creds.apiKey ?? ""
+  const secret = creds.apiSecret ?? ""
+  try {
+    const res = await fetch("https://api.godaddy.com/v1/domains?statuses=ACTIVE&limit=1000", {
+      headers: { Authorization: `sso-key ${key}:${secret}`, Accept: "application/json" },
+    })
+    if (!res.ok) {
+      // GoDaddy gates API access (≈20+ domains / reseller tiers); 403 means this
+      // account can't use the API — the zone stays a web-only (↗) handoff.
+      const body = (await res.json().catch(() => ({}))) as { message?: string }
+      const msg = res.status === 403 ? "This GoDaddy account has no API access (needs 20+ domains / reseller)." : body.message || `HTTP ${res.status}`
+      return { ok: false, zones: [], accountLabel: "", error: msg }
+    }
+    const list = (await res.json()) as { domain: string; nameServers?: string[] }[]
+    const zones: VerifiedZone[] = list.map((d) => ({
+      apex: normApex(d.domain),
+      account: "godaddy",
+      nameservers: normNameservers(d.nameServers),
+    }))
+    return { ok: true, zones, accountLabel: "GoDaddy" }
+  } catch (err) {
+    return { ok: false, zones: [], accountLabel: "", error: (err as Error).message }
+  }
+}
+
+// ---- Registry --------------------------------------------------------------
+
+export const PROVIDER_REGISTRY: Record<ConnProvider, ProviderDescriptor> = {
+  aws: {
+    key: "aws",
+    name: "AWS (Route 53)",
+    hostKeys: ["route53"],
+    fields: [
+      { name: "accessKeyId", label: "Access Key ID", placeholder: "AKIA…" },
+      { name: "secretAccessKey", label: "Secret Access Key", secret: true, placeholder: "secret" },
+      { name: "region", label: "Region (optional, default us-east-1)", optional: true, placeholder: "us-east-1" },
+    ],
+    guidance: "IAM perms: route53 ListHostedZonesByName + ListResourceRecordSets to view; add ChangeResourceRecordSets + GetChange to edit TTLs.",
+    verify: verifyAws,
+  },
+  cloudflare: {
+    key: "cloudflare",
+    name: "Cloudflare",
+    hostKeys: ["cloudflare"],
+    fields: [{ name: "token", label: "API token — DNS:Read to view, DNS:Edit to change TTLs", secret: true, placeholder: "Cloudflare API token" }],
+    guidance: "Create one at dash.cloudflare.com → My Profile → API Tokens (Zone DNS:Edit to edit records).",
+    verify: verifyCloudflare,
+  },
+  godaddy: {
+    key: "godaddy",
+    name: "GoDaddy",
+    hostKeys: ["godaddy"],
+    fields: [
+      { name: "apiKey", label: "API Key", placeholder: "key" },
+      { name: "apiSecret", label: "API Secret", secret: true, placeholder: "secret" },
+    ],
+    guidance:
+      "At developer.godaddy.com → Create New API Key, choose Environment = Production (NOT OTE/test). GoDaddy's API is only available to larger accounts (≈20+ domains / reseller); without it, use w for the Clients hub.",
+    console: "https://hub.godaddy.com/clients?view=table",
+    consoleLabel: "Clients hub",
+    accessNote:
+      "SpinupTUI assumes you manage GoDaddy domains via Delegate Access from one main account. Press w to open your Clients hub (the domain is copied to your clipboard) → Login as the client → paste the domain → Exit access before checking the next.",
+    verify: verifyGodaddy,
+  },
+}
+
+export const ALL_PROVIDERS: ConnProvider[] = Object.keys(PROVIDER_REGISTRY) as ConnProvider[]
+
+// Map a live host providerKey to the connection provider we can authenticate as.
+export function apiProviderFor(hostKey: string): ConnProvider | null {
+  for (const d of Object.values(PROVIDER_REGISTRY)) if (d.hostKeys.includes(hostKey)) return d.key
+  return null
+}
+
+export function verifyConnection(conn: Connection): Promise<VerifyResult> {
+  return PROVIDER_REGISTRY[conn.provider].verify(conn.creds)
+}
+
+// Best-effort web-console deep links for hosts we can't (or don't yet) drive via
+// API — the `↗ web only` handoff. API providers normally resolve to editable/
+// needs-key before reaching here.
+export const PROVIDER_CONSOLE: Record<string, string> = {
+  namecheap: "https://ap.www.namecheap.com/domains/list",
+  dnsme: "https://dnsmadeeasy.com",
+  digitalocean: "https://cloud.digitalocean.com/networking/domains",
+  google: "https://domains.google.com/registrar",
+  netsol: "https://www.networksolutions.com/my-account",
+  dreamhost: "https://panel.dreamhost.com",
+  azure: "https://portal.azure.com",
+  linode: "https://cloud.linode.com/domains",
+  vultr: "https://my.vultr.com/dns/",
+}
+
+// The web handoff (URL + label) for a host, if any: an API provider's console
+// (e.g. GoDaddy's Clients hub), else a web-only host's console. null for hosts
+// managed purely via API (Route 53 / Cloudflare) or unrecognized fallbacks.
+export function consoleForHost(hostKey: string): { url: string; label: string } | null {
+  const prov = apiProviderFor(hostKey)
+  if (prov) {
+    const d = PROVIDER_REGISTRY[prov]
+    return d.console ? { url: d.console, label: d.consoleLabel ?? "web console" } : null
+  }
+  const url = PROVIDER_CONSOLE[hostKey]
+  return url ? { url, label: "web console" } : null
+}
+
+export type AccessState = "editable" | "needs-key" | "web" | "unknown"
+
+// The assumed-normal access note for ANY `web`-state zone (GoDaddy, Namecheap,
+// Network Solutions, any host with a console fallback and no API connection) —
+// most registrars are managed the same way (delegate/reseller access from one
+// main account), so this is a single global default rather than a per-provider
+// one. A user-entered per-zone override (store.zoneAccessNotes) — a genuine
+// exception, e.g. one client's domain a third party actually manages — shows
+// instead, in amber, so it stands out.
+export const DEFAULT_WEB_ACCESS_NOTE = "Delegate Access"
+
+// NOTE: the access decision is computed in the store (accessForZone) — it has the
+// connection data — and is PROVIDER-SCOPED + NS-aware. See store.tsx.

package/src/lib/providersCache.ts

@@ -0,0 +1,105 @@
+// Disk cache of verified provider zone sets, keyed by connection id.
+//
+// Holds only the RESULT of verification (zone names + account labels + an age) —
+// NOT the credentials themselves (those live in config.json). Lets the ACCESS
+// column populate at startup without re-hitting every provider; a visible age +
+// a re-verify key keep it honest. Modeled on dnsCache.ts.
+//
+// Staleness: entries older than STALE_TTL_MS are dropped on load so they re-verify
+// (see STALE_TTL_MS below) — the general-case fix for a zone registered after the
+// last verify (DNS inventory ACCESS column, clone Plan pre-flight), complementing
+// the vanity/clone resolveZoneConn re-verify-on-miss self-heal.
+
+import { join } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { chmod, mkdir } from "node:fs/promises"
+import { configDir } from "../config.ts"
+import type { VerifiedZone } from "./providers.ts"
+
+// v2: VerifiedZone gained `nameservers` + `account` (was accountId/accountName).
+// Old entries are dropped on load so connections re-verify with the new shape.
+const CACHE_VERSION = 2
+
+// Backlog #3 (2026-06-27): entries older than this are dropped on load so they
+// lazily RE-VERIFY (via the "no cache entry → verifyConnectionById" path in the
+// views) instead of serving a stale zone list forever. This is what lets a zone
+// registered since the last verify become visible without a manual bust — the
+// general-case complement to the vanity/clone resolveZoneConn self-heal. We DROP
+// (not eagerly re-verify) on purpose: the cache exists so startup doesn't hit every
+// provider; freshness is reclaimed the next time a view actually needs the zone.
+const STALE_TTL_MS = 24 * 60 * 60 * 1000 // 24h
+
+export interface VerifiedConn {
+  ok: boolean
+  zones: VerifiedZone[]
+  accountLabel: string
+  error?: string
+  verifiedAt: number // epoch ms
+}
+
+interface CacheFile {
+  version: number
+  entries: Record<string, VerifiedConn> // key: connection id
+}
+
+export function providersCachePath(): string {
+  return join(configDir(), "providers-cache.json")
+}
+
+export class ProvidersCache {
+  private entries = new Map<string, VerifiedConn>()
+  private writeChain: Promise<void> = Promise.resolve()
+
+  load(): void {
+    try {
+      const path = providersCachePath()
+      if (!existsSync(path)) return
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as CacheFile
+      if (parsed?.version !== CACHE_VERSION || !parsed.entries) return
+      const now = Date.now()
+      for (const [k, v] of Object.entries(parsed.entries)) {
+        if (!k || !v || typeof v.verifiedAt !== "number") continue
+        if (now - v.verifiedAt > STALE_TTL_MS) continue // stale → drop so it re-verifies
+        this.entries.set(k, v)
+      }
+    } catch {
+      /* ignore corrupt/unreadable cache — start empty */
+    }
+  }
+
+  get(id: string): VerifiedConn | undefined {
+    return this.entries.get(id)
+  }
+
+  snapshot(): Map<string, VerifiedConn> {
+    return new Map(this.entries)
+  }
+
+  async set(id: string, conn: VerifiedConn): Promise<void> {
+    this.entries.set(id, conn)
+    await this.persist()
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.entries.delete(id)) return
+    await this.persist()
+  }
+
+  private persist(): Promise<void> {
+    this.writeChain = this.writeChain.then(() => this.writeFile()).catch(() => {})
+    return this.writeChain
+  }
+
+  private async writeFile(): Promise<void> {
+    await mkdir(configDir(), { recursive: true })
+    const file: CacheFile = { version: CACHE_VERSION, entries: {} }
+    for (const [k, entry] of this.entries) file.entries[k] = entry
+    const path = providersCachePath()
+    await Bun.write(path, JSON.stringify(file, null, 2) + "\n")
+    try {
+      await chmod(path, 0o600)
+    } catch {
+      /* best-effort */
+    }
+  }
+}

package/src/lib/releaseNotes.ts

@@ -0,0 +1,67 @@
+// "What's new" notes for the version currently running, fetched once from
+// GitHub's release for that exact tag — reuses the same API the update-checker
+// (appUpdate.ts) already polls, so no new infrastructure (no spinuptui.com feed).
+// Shown once via the ReleaseNotes overlay when store.tsx detects the running
+// version hasn't been "seen" yet (config.lastSeenVersion).
+
+import { REPO_SLUG } from "../version.ts"
+
+const FETCH_TIMEOUT_MS = 5000
+
+export interface ReleaseNotesInfo {
+  version: string
+  title: string
+  body: string // raw markdown from the GitHub release body
+  url: string
+}
+
+// Hit GitHub for one specific release's notes; null on any failure (offline, no
+// release published yet for this tag, rate limit). Times out so it can't hang
+// the launch. Unlike appUpdate.ts's "latest release" poll, this targets the
+// EXACT running version's tag, so it's correct even if the user updates across
+// several releases in one hop.
+export async function fetchReleaseNotes(version: string): Promise<ReleaseNotesInfo | null> {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const res = await fetch(`https://api.github.com/repos/${REPO_SLUG}/releases/tags/v${version}`, {
+      headers: {
+        "User-Agent": "spinup-tui",
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      signal: ctrl.signal,
+    })
+    if (!res.ok) return null
+    const json = (await res.json()) as { name?: string; body?: string; html_url?: string }
+    if (!json.body) return null
+    return {
+      version,
+      title: json.name ?? `v${version}`,
+      body: json.body,
+      url: json.html_url ?? `https://github.com/${REPO_SLUG}/releases/tag/v${version}`,
+    }
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export type NoteLine = { kind: "heading" | "bullet" | "text" | "blank"; content: string }
+
+// Strip GitHub-flavored markdown down to something readable as plain terminal
+// text. Not a general markdown parser (no new dependency) — just enough for the
+// shape of notes this project actually writes (see RELEASING.md's house style):
+// an intro line, `##` section headers, `- ` bullets (often **bold**-led), a
+// blank-line-separated Update/Full-changelog footer.
+export function formatReleaseNotesBody(body: string): NoteLine[] {
+  const strip = (s: string) => s.replace(/\*\*/g, "").replace(/`/g, "")
+  return body.split("\n").map((raw): NoteLine => {
+    const line = raw.trimEnd()
+    if (line.trim() === "") return { kind: "blank", content: "" }
+    if (line.startsWith("## ")) return { kind: "heading", content: strip(line.slice(3)) }
+    if (line.startsWith("- ")) return { kind: "bullet", content: strip(line.slice(2)) }
+    return { kind: "text", content: strip(line) }
+  })
+}