spinuptui 0.19.0

package/src/lib/local.ts

@@ -0,0 +1,116 @@
+// Local working-copy linking — Phase 1 (link + view, no mutation).
+//
+// Bridges SpinupWP's remote site inventory to the user's LOCAL dev copies so
+// the TUI can later help with continued management (the Bedrock composer-update
+// → push → auto-deploy loop). This module owns the link *shape* and the
+// read-only validation of a configured link; it never mutates anything.
+//
+// A link is keyed by SpinupWP site id (stable across domain renames) and stores
+// the local `path` plus an explicitly-captured `localUrl` (we don't guess it —
+// the URL is recorded as entered, per the locked spec). `localUrl` is host-tool
+// agnostic on purpose: it's whatever serves the local copy — Valet, Cove,
+// LocalWP, Herd, DDEV, `artisan serve`, etc. We never assume a specific tool.
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+
+export interface LocalLink {
+  // Recorded for display / sanity-checking against the live site domain.
+  domain: string
+  // Local filesystem path to the working copy. Stored as entered (may use `~`);
+  // expanded only at point of use so the config stays readable/portable.
+  path: string
+  // The URL where the local copy is served (e.g. https://example.test). Stored
+  // explicitly, not derived, and tool-agnostic. May be empty.
+  localUrl: string
+}
+
+// Normalize a stored link, tolerating older configs that used `valetUrl` before
+// the field was generalized to `localUrl`. Reads either key; emits `localUrl`.
+export function normalizeLink(raw: LocalLink & { valetUrl?: string }): LocalLink {
+  return { domain: raw.domain, path: raw.path, localUrl: raw.localUrl ?? raw.valetUrl ?? "" }
+}
+
+// Resolution of a link against the filesystem, computed on demand (cheap — one
+// focused site at a time). `kind` mirrors the stack buckets used elsewhere.
+export type LocalKind = "bedrock" | "wp" | "unknown"
+export interface LocalState {
+  exists: boolean
+  kind: LocalKind
+  // Short human label for the detail field, e.g. "Bedrock" / "WordPress".
+  label: string
+}
+
+// Expand a leading `~` to the user's home directory. Leaves other paths as-is.
+export function expandPath(path: string): string {
+  if (path === "~") return homedir()
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2))
+  return path
+}
+
+// Files that signal "a project root lives here" — used to locate the working
+// copy and to read its git/.env. Deliberately marker-based (not folder-name
+// based) so layouts like `app/`, `public/`, `web/` all work without hardcoding
+// any one developer's convention.
+function hasProjectMarkers(dir: string): boolean {
+  return (
+    existsSync(join(dir, "composer.json")) ||
+    existsSync(join(dir, ".git")) ||
+    existsSync(join(dir, ".env")) ||
+    existsSync(join(dir, "wp-config.php")) ||
+    existsSync(join(dir, "config", "application.php"))
+  )
+}
+
+// Resolve the actual project root within a linked folder: the folder itself if
+// it holds markers, else the first immediate subdirectory that does (so a
+// domain folder containing the app in `app/`, `public/`, etc. resolves without
+// us naming the convention). Read-only; never throws.
+export function findProjectRoot(dir: string): string {
+  if (hasProjectMarkers(dir)) return dir
+  try {
+    for (const child of readdirSync(dir)) {
+      if (child.startsWith(".")) continue
+      const c = join(dir, child)
+      if (hasProjectMarkers(c)) return c
+    }
+  } catch {
+    // unreadable — fall through to the folder itself
+  }
+  return dir
+}
+
+// Classify a local working copy by reading a few marker files (read-only):
+//   Bedrock = composer.json requiring roots/bedrock, or config/application.php
+//   WordPress = wp-config.php at the root (or a public/ webroot)
+// Anything that exists but matches neither is "unknown".
+function classify(dir: string): LocalKind {
+  const composer = join(dir, "composer.json")
+  if (existsSync(composer)) {
+    try {
+      if (readFileSync(composer, "utf8").includes("roots/bedrock")) return "bedrock"
+    } catch {
+      // unreadable composer.json — fall through to other markers
+    }
+  }
+  if (existsSync(join(dir, "config", "application.php"))) return "bedrock"
+  if (existsSync(join(dir, "wp-config.php")) || existsSync(join(dir, "public", "wp-config.php"))) return "wp"
+  return "unknown"
+}
+
+const KIND_LABEL: Record<LocalKind, string> = {
+  bedrock: "Bedrock",
+  wp: "WordPress",
+  unknown: "unrecognized",
+}
+
+// Validate a configured link against the local filesystem. Never throws. The
+// stored path is the project *folder*; we classify at its detected root so a
+// nested layout (app/, public/, …) still reports the right stack.
+export function resolveLocalLink(link: LocalLink): LocalState {
+  const dir = expandPath(link.path)
+  if (!existsSync(dir)) return { exists: false, kind: "unknown", label: "missing" }
+  const kind = classify(findProjectRoot(dir))
+  return { exists: true, kind, label: KIND_LABEL[kind] }
+}

package/src/lib/mediaFallback.ts

@@ -0,0 +1,288 @@
+// Production media fallback for a linked local site.
+//
+// After a `p` prod→local DB sync the local DB is current but media files aren't
+// pulled down, so browsing locally shows broken images. This drops a small,
+// self-contained mu-plugin into the LOCAL WordPress copy that rewrites any
+// uploads URL whose file is MISSING locally to the production origin — so images
+// resolve without syncing the (often huge) media library.
+//
+// The feature is LOCAL-ONLY and read-only on production (it just hotlinks the
+// site's own production images). Its on/off state is the file's presence — no
+// config flag — so enabling/disabling is just writing/removing the plugin. The
+// plugin self-configures from `wp_get_upload_dir()` (correct for Standard WP,
+// Bedrock, and multisite) and self-disables when running on the production
+// domain, so it's inert if ever deployed.
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs"
+import { join } from "node:path"
+import type { Site } from "../api/types.ts"
+import { expandPath, findProjectRoot, type LocalLink } from "./local.ts"
+
+const PLUGIN_FILE = "spinup-media-fallback.php"
+// Identifies a plugin WE generated, so we never touch a user's own file.
+const MARKER = "spinup:media-fallback"
+// Bumped whenever the generated PHP changes; an installed file older than this
+// surfaces an "update available" prompt in the overlay. A file carrying our
+// marker but no version tag predates versioning and counts as v1.
+const PLUGIN_VERSION = 2
+
+export interface MediaFallbackPlan {
+  localRoot: string // where the local WordPress install lives
+  muDir: string // the mu-plugins dir (created on enable)
+  pluginPath: string // muDir/spinup-media-fallback.php
+  prodOrigin: string // https://prod-domain — the fallback source
+  stack: "bedrock" | "standard"
+  enabled: boolean // our plugin currently present
+  version: number // the version this build would write
+  installedVersion: number | null // version on disk, or null when not installed
+  updateAvailable: boolean // installed but older than `version`
+}
+
+export type MediaFallbackResult = { ok: true; plan: MediaFallbackPlan } | { ok: false; error: string }
+
+// Bedrock keeps wp-content under web/app; Standard WP under wp-content. Detect by
+// the on-disk content dir so the plugin lands where WordPress autoloads mu-plugins.
+function contentMuDir(localRoot: string): { dir: string; stack: "bedrock" | "standard" } {
+  if (existsSync(join(localRoot, "web", "app"))) return { dir: join(localRoot, "web", "app", "mu-plugins"), stack: "bedrock" }
+  return { dir: join(localRoot, "wp-content", "mu-plugins"), stack: "standard" }
+}
+
+// True only when the file exists AND carries our marker (never report or remove a
+// user's own same-named plugin).
+function isOurs(pluginPath: string): boolean {
+  return installedVersion(pluginPath) !== null
+}
+
+// Version of an installed plugin: the tagged number, 1 for a marked-but-untagged
+// file (predates versioning), or null when the file is absent / not ours.
+function installedVersion(pluginPath: string): number | null {
+  try {
+    const txt = readFileSync(pluginPath, "utf8")
+    if (!txt.includes(MARKER)) return null
+    const m = txt.match(/spinup:media-fallback v(\d+)/)
+    return m ? parseInt(m[1], 10) : 1
+  } catch {
+    return null
+  }
+}
+
+export function planMediaFallback(site: Site, link: LocalLink | undefined): MediaFallbackResult {
+  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 { dir: muDir, stack } = contentMuDir(localRoot)
+  const pluginPath = join(muDir, PLUGIN_FILE)
+  const prodOrigin = `${site.https?.enabled ? "https" : "http"}://${site.domain}`
+  const iv = installedVersion(pluginPath)
+  return {
+    ok: true,
+    plan: {
+      localRoot,
+      muDir,
+      pluginPath,
+      prodOrigin,
+      stack,
+      enabled: iv !== null,
+      version: PLUGIN_VERSION,
+      installedVersion: iv,
+      updateAvailable: iv !== null && iv < PLUGIN_VERSION,
+    },
+  }
+}
+
+// Write (or refresh) the mu-plugin. Idempotent; safe to call repeatedly.
+export function enableMediaFallback(plan: MediaFallbackPlan): void {
+  mkdirSync(plan.muDir, { recursive: true })
+  writeFileSync(plan.pluginPath, pluginSource(plan.prodOrigin))
+}
+
+// Remove the mu-plugin — but only if it's the one we generated.
+export function disableMediaFallback(plan: MediaFallbackPlan): void {
+  if (isOurs(plan.pluginPath)) unlinkSync(plan.pluginPath)
+}
+
+// The generated mu-plugin. String.raw keeps PHP backslashes (regex) intact; the
+// only interpolation is the production origin. The marker comment must survive.
+function pluginSource(origin: string): string {
+  return String.raw`<?php
+/**
+ * Plugin Name: Spinup Media Fallback (local dev)
+ * Description: Serve missing local uploads from production so images resolve without syncing the whole media library. Managed by spinup — safe to delete.
+ *
+ * ${MARKER} v${PLUGIN_VERSION}
+ *
+ * Generated by the spinup TUI for local development. When an uploaded file is
+ * not present locally, its URL is rewritten to the production origin below.
+ * Self-disables when the site runs on its production domain, so it is inert if
+ * ever deployed. Define SPINUP_MEDIA_FALLBACK_DISABLE truthy to force it off.
+ */
+
+if (!defined('ABSPATH')) {
+    return;
+}
+
+if (!defined('SPINUP_MEDIA_FALLBACK_ORIGIN')) {
+    define('SPINUP_MEDIA_FALLBACK_ORIGIN', '${origin}');
+}
+
+/**
+ * Active only on a non-production host (computed once, lazily — after options are
+ * loaded). Prevents borrowing from ourselves and makes an accidental deploy inert.
+ */
+function spinup_mf_active() {
+    static $active = null;
+    if ($active !== null) {
+        return $active;
+    }
+    $active = false;
+    if (defined('SPINUP_MEDIA_FALLBACK_DISABLE') && SPINUP_MEDIA_FALLBACK_DISABLE) {
+        return $active;
+    }
+    $origin = SPINUP_MEDIA_FALLBACK_ORIGIN;
+    $prod_host = $origin ? parse_url($origin, PHP_URL_HOST) : '';
+    $home_host = parse_url(home_url(), PHP_URL_HOST);
+    if (!$prod_host || !$home_host) {
+        return $active;
+    }
+    $suffix = '.' . $prod_host;
+    // On the production domain (or a clone using it)? Then do nothing.
+    if ($home_host === $prod_host || substr($home_host, -strlen($suffix)) === $suffix) {
+        return $active;
+    }
+    $active = true;
+    return $active;
+}
+
+/**
+ * [local base URL, local base dir, production base URL] for uploads. Cached.
+ */
+function spinup_mf_base() {
+    static $cache = null;
+    if ($cache !== null) {
+        return $cache;
+    }
+    $u = wp_get_upload_dir();
+    $base_url = rtrim($u['baseurl'], '/');
+    $base_dir = rtrim($u['basedir'], '/');
+    $path = parse_url($base_url, PHP_URL_PATH);
+    $prod_base = rtrim(SPINUP_MEDIA_FALLBACK_ORIGIN, '/') . $path;
+    $cache = array($base_url, $base_dir, $prod_base);
+    return $cache;
+}
+
+/**
+ * Is the uploads-relative file (e.g. /2024/05/x-300x200.jpg) present locally?
+ */
+function spinup_mf_local_has($rel) {
+    $base = spinup_mf_base();
+    $rel_path = strtok($rel, '?'); // drop any ?ver= cache buster
+    return @file_exists($base[1] . $rel_path);
+}
+
+/**
+ * Rewrite a full local uploads URL to production when the file is missing.
+ */
+function spinup_mf_map_url($url) {
+    if (!is_string($url) || $url === '' || !spinup_mf_active()) {
+        return $url;
+    }
+    $base = spinup_mf_base();
+    if (strpos($url, $base[0]) !== 0) {
+        return $url;
+    }
+    $rel = substr($url, strlen($base[0]));
+    if (spinup_mf_local_has($rel)) {
+        return $url;
+    }
+    return $base[2] . $rel;
+}
+
+// Core-generated URLs (blocks, themes, and the admin media library).
+add_filter('wp_get_attachment_url', 'spinup_mf_map_url', 99);
+add_filter('wp_get_attachment_image_src', function ($image) {
+    if (is_array($image) && isset($image[0])) {
+        $image[0] = spinup_mf_map_url($image[0]);
+    }
+    return $image;
+}, 99);
+add_filter('wp_calculate_image_srcset', function ($sources) {
+    if (is_array($sources)) {
+        foreach ($sources as $k => $s) {
+            if (isset($s['url'])) {
+                $sources[$k]['url'] = spinup_mf_map_url($s['url']);
+            }
+        }
+    }
+    return $sources;
+}, 99);
+
+/**
+ * Would a local-origin request for $path 404? Decide from the real document root
+ * (what the web server itself would resolve), so this works for ANY path — the
+ * current uploads dir, a legacy /wp-content/uploads after a Bedrock conversion,
+ * or a CDN-offloaded path. Returns the production URL to use, or null to keep the
+ * local one. Deferring to production by path means production's own routing
+ * (redirects, S3/CDN) resolves whatever we hand it.
+ */
+function spinup_mf_map_path($path) {
+    $root = isset($_SERVER['DOCUMENT_ROOT']) ? rtrim($_SERVER['DOCUMENT_ROOT'], '/') : '';
+    if ($root !== '' && @file_exists($root . $path)) {
+        return null; // present locally — leave it
+    }
+    return rtrim(SPINUP_MEDIA_FALLBACK_ORIGIN, '/') . $path;
+}
+
+// Front-end catch-all: rewrite any local-origin media URL in the final HTML whose
+// file is missing locally — covers hardcoded URLs and page builders (e.g.
+// Elementor inline background-image CSS) that bypass the attachment filters, plus
+// JSON-escaped URLs (\/) that Elementor embeds for galleries/lightboxes.
+add_action('template_redirect', function () {
+    if (!spinup_mf_active()) {
+        return;
+    }
+    if (is_admin() || is_feed()
+        || (defined('DOING_AJAX') && DOING_AJAX)
+        || (defined('REST_REQUEST') && REST_REQUEST)
+        || (defined('WP_CLI') && WP_CLI)) {
+        return;
+    }
+    ob_start('spinup_mf_filter_html');
+});
+
+function spinup_mf_filter_html($html) {
+    if (!is_string($html) || $html === '' || !spinup_mf_active()) {
+        return $html;
+    }
+    $home_host = parse_url(home_url(), PHP_URL_HOST);
+    if (!$home_host) {
+        return $html;
+    }
+    $host = preg_quote($home_host, '#');
+    // Media-ish extensions worth a production fallback (not js/css — those are
+    // local code, and the file-exists check would leave them alone anyway).
+    $ext = 'jpe?g|png|gif|webp|avif|svg|bmp|ico|tiff?|heic|pdf|mp4|m4v|mov|webm|ogv|mp3|wav|ogg|m4a|woff2?|ttf|otf|eot';
+    // A slash that may be JSON-escaped (\/), so one pass matches plain, protocol-
+    // relative, and escaped URLs alike.
+    $sl = '(?:\\\\?/)';
+    $seg = '[^\s"\'()<>\\\\/]';
+    $re = '#(?:https?:)?' . $sl . $sl . $host . '(?:' . $sl . $seg . '+)+\.(?:' . $ext . ')(?:\?' . $seg . '*)?#i';
+    return preg_replace_callback($re, function ($m) use ($host) {
+        $url = $m[0];
+        $escaped = strpos($url, '\\/') !== false;
+        $norm = $escaped ? str_replace('\\/', '/', $url) : $url;
+        $rest = preg_replace('#^(?:https?:)?//' . $host . '#i', '', $norm); // /path(?query)
+        $qpos = strpos($rest, '?');
+        $path = $qpos === false ? $rest : substr($rest, 0, $qpos);
+        $query = $qpos === false ? '' : substr($rest, $qpos);
+        $prod = spinup_mf_map_path($path);
+        if ($prod === null) {
+            return $m[0];
+        }
+        $out = $prod . $query;
+        return $escaped ? str_replace('/', '\\/', $out) : $out;
+    }, $html);
+}
+`
+}

package/src/lib/open.ts

@@ -0,0 +1,103 @@
+// Open a URL in the user's default browser, cross-platform. Best-effort; never throws.
+
+export function openUrl(url: string): void {
+  try {
+    const platform = process.platform
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open"
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url]
+    Bun.spawn([cmd, ...args], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+  } catch {
+    // ignore — opening a browser is a convenience, not critical
+  }
+}
+
+// Copy text to the system clipboard, cross-platform. Best-effort; never throws.
+// Used by the GoDaddy handoff so the domain is ready to paste after switching
+// into a delegated client account.
+export function copyToClipboard(text: string): void {
+  try {
+    const platform = process.platform
+    const cmd = platform === "darwin" ? ["pbcopy"] : platform === "win32" ? ["clip"] : ["xclip", "-selection", "clipboard"]
+    const proc = Bun.spawn(cmd, { stdin: "pipe", stdout: "ignore", stderr: "ignore" })
+    proc.stdin.write(text)
+    void proc.stdin.end()
+  } catch {
+    // ignore — clipboard is a convenience, not critical
+  }
+}
+
+// macOS has no registered "default terminal" role (unlike the default browser),
+// so we can't ask LaunchServices which terminal to use. The best proxy is
+// $TERM_PROGRAM — the terminal that launched this process sets it — which works
+// well because the app is normally started via the `spinuptui` command from the
+// user's terminal of choice. This maps those values to the app name `open -a`
+// expects. Unknown/unset → Terminal.
+const TERM_PROGRAM_APP: Record<string, string> = {
+  "iTerm.app": "iTerm",
+  Apple_Terminal: "Terminal",
+  WarpTerminal: "Warp",
+  ghostty: "Ghostty",
+  WezTerm: "WezTerm",
+  Hyper: "Hyper",
+  Tabby: "Tabby",
+  vscode: "Visual Studio Code",
+}
+
+// Resolve which macOS terminal app to open. An explicit config override wins;
+// otherwise infer from $TERM_PROGRAM; otherwise fall back to Terminal.
+export function resolveTerminalApp(override?: string | null): string {
+  const o = override?.trim()
+  if (o) return o
+  const tp = process.env.TERM_PROGRAM?.trim()
+  return (tp && TERM_PROGRAM_APP[tp]) || "Terminal"
+}
+
+// The ssh command line for a site shell (adds -p when the port isn't the default).
+export function sshCommand(user: string, host: string, port?: number | null): string {
+  return port && port !== 22 ? `ssh -p ${port} ${user}@${host}` : `ssh ${user}@${host}`
+}
+
+// Open a new terminal window already running `ssh user@host`. Best-effort; never
+// throws. macOS scripts the user's terminal (iTerm or, as a reliable fallback for
+// any other, Terminal); Linux/Windows do their best.
+export function openSshSession(user: string, host: string, port?: number | null, terminalApp?: string | null): void {
+  const cmd = sshCommand(user, host, port)
+  try {
+    const platform = process.platform
+    if (platform === "darwin") {
+      const esc = cmd.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+      const app = resolveTerminalApp(terminalApp)
+      const args =
+        app === "iTerm"
+          ? ["-e", `tell application "iTerm"\ncreate window with default profile command "${esc}"\nactivate\nend tell`]
+          : ["-e", `tell application "Terminal" to do script "${esc}"`, "-e", `tell application "Terminal" to activate`]
+      Bun.spawn(["osascript", ...args], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    } else if (platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", "cmd", "/k", cmd], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    } else {
+      Bun.spawn(["x-terminal-emulator", "-e", cmd], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    }
+  } catch {
+    // ignore — opening a shell is a convenience, not critical
+  }
+}
+
+// Open a terminal window at the given directory (where the user runs editor /
+// composer / git themselves). Best-effort; never throws. macOS opens the user's
+// terminal (see resolveTerminalApp); Linux tries common emulators; Windows opens
+// cmd in the directory.
+export function openTerminalAt(dir: string, terminalApp?: string | null): void {
+  try {
+    const platform = process.platform
+    if (platform === "darwin") {
+      Bun.spawn(["open", "-a", resolveTerminalApp(terminalApp), dir], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    } else if (platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", "cmd", "/k", `cd /d ${dir}`], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    } else {
+      // Try a few common terminal emulators; the first that exists wins.
+      Bun.spawn(["x-terminal-emulator", "--working-directory", dir], { stdout: "ignore", stderr: "ignore", stdin: "ignore" })
+    }
+  } catch {
+    // ignore — opening a terminal is a convenience, not critical
+  }
+}

package/src/lib/phpEol.ts

@@ -0,0 +1,151 @@
+// PHP end-of-life data, computed from real EOL *dates* vs the current date —
+// not a hard-coded "version X and below" cut, which would silently rot as the
+// calendar advances. A version is EOL once its security-support date is past.
+//
+// Hybrid sourcing:
+//   1. An embedded table of php.net's published dates is the offline default,
+//      so flagging is correct with no network.
+//   2. At startup we refresh from endoflife.date (cached to disk), which keeps
+//      the data current and adds versions released after this build.
+//
+// A version with no known date is NOT flagged — we don't guess.
+
+import { join } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { configDir } from "../config.ts"
+
+// Map of "major.minor" → security-support EOL date (ISO). Source: php.net
+// supported-versions schedule. Refreshed at runtime from endoflife.date.
+export const EMBEDDED_PHP_EOL: Record<string, string> = {
+  "7.2": "2020-11-30",
+  "7.3": "2021-12-06",
+  "7.4": "2022-11-28",
+  "8.0": "2023-11-26",
+  "8.1": "2025-12-31",
+  "8.2": "2026-12-31",
+  "8.3": "2027-12-31",
+  "8.4": "2028-12-31",
+  "8.5": "2029-12-31",
+}
+
+// Refresh from the network at most this often.
+const REFRESH_AFTER_MS = 7 * 24 * 60 * 60 * 1000
+const FETCH_TIMEOUT_MS = 6000
+const ENDPOINT = "https://endoflife.date/api/php.json"
+
+export type PhpEolDates = Record<string, string>
+
+interface CacheFile {
+  fetchedAt: number
+  dates: PhpEolDates
+}
+
+export function phpEolCachePath(): string {
+  return join(configDir(), "php-eol.json")
+}
+
+// Normalize "8.2.13" / "8.2" / "8" → "8.2" (the key php.net schedules by).
+function majorMinor(version: string): string | null {
+  const parts = version.split(".")
+  const maj = Number.parseInt(parts[0], 10)
+  if (!Number.isFinite(maj)) return null
+  const min = Number.parseInt(parts[1] ?? "0", 10)
+  return `${maj}.${Number.isFinite(min) ? min : 0}`
+}
+
+// True when `version`'s known EOL date is before `asOf`. Unknown → not flagged.
+export function isPhpEol(version: string | null | undefined, dates: PhpEolDates, asOf: Date = new Date()): boolean {
+  if (!version) return false
+  const key = majorMinor(version)
+  if (!key) return false
+  const eol = dates[key]
+  if (!eol) return false
+  const t = Date.parse(eol)
+  return Number.isFinite(t) && t < asOf.getTime()
+}
+
+// The PHP versions to offer in the upgrade picker. Derived dynamically from the
+// (network-refreshed) EOL schedule so it tracks new releases (8.5, 8.6, …) on its
+// own rather than rotting in a hard-coded list. We keep the modern major (8.x),
+// drop ancient 7.x, and always include the site's current version even if the
+// schedule no longer lists it. Not filtered to "installed on the server" —
+// SpinupWP installs a version on demand the first time a site is assigned it.
+export function offeredPhpVersions(dates: PhpEolDates, current?: string | null): string[] {
+  const set = new Set<string>()
+  for (const key of Object.keys(dates)) {
+    const maj = Number.parseInt(key.split(".")[0] ?? "", 10)
+    if (maj >= 8) set.add(key)
+  }
+  const cur = current ? majorMinor(current) : null
+  if (cur) set.add(cur)
+  return [...set].sort((a, b) => phpSortKey(a) - phpSortKey(b))
+}
+
+// Numeric sort key for "8.10" > "8.2" correctness (major*100 + minor).
+export function phpSortKey(version: string | null | undefined): number {
+  if (!version) return -1
+  const [maj, min] = version.split(".").map((n) => Number.parseInt(n, 10))
+  if (!Number.isFinite(maj)) return -1
+  return maj * 100 + (Number.isFinite(min) ? min : 0)
+}
+
+function loadCache(): CacheFile | null {
+  try {
+    const path = phpEolCachePath()
+    if (!existsSync(path)) return null
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as CacheFile
+    if (!parsed?.dates || typeof parsed.fetchedAt !== "number") return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+// The dates to use right now: embedded defaults overlaid with cached fetch data.
+export function resolvePhpEolDates(): PhpEolDates {
+  return { ...EMBEDDED_PHP_EOL, ...(loadCache()?.dates ?? {}) }
+}
+
+function cacheIsFresh(): boolean {
+  const c = loadCache()
+  return c != null && Date.now() - c.fetchedAt < REFRESH_AFTER_MS
+}
+
+// Fetch the live PHP schedule from endoflife.date. Returns null on any failure
+// (offline, timeout, bad shape) so callers fall back to embedded/cached data.
+async function fetchPhpEolDates(): Promise<PhpEolDates | null> {
+  try {
+    const res = await fetch(ENDPOINT, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    })
+    if (!res.ok) return null
+    const cycles = (await res.json()) as { cycle?: string; eol?: string | boolean }[]
+    if (!Array.isArray(cycles)) return null
+    const dates: PhpEolDates = {}
+    for (const c of cycles) {
+      if (typeof c.cycle === "string" && typeof c.eol === "string") dates[c.cycle] = c.eol
+    }
+    return Object.keys(dates).length > 0 ? dates : null
+  } catch {
+    return null
+  }
+}
+
+// Refresh the cache if stale; returns the freshly merged dates when it updated,
+// or null when nothing changed (cache still fresh, or the fetch failed). Never
+// throws — PHP-EOL data is best-effort decoration.
+export async function refreshPhpEolDates(): Promise<PhpEolDates | null> {
+  if (cacheIsFresh()) return null
+  const fetched = await fetchPhpEolDates()
+  if (!fetched) return null
+  try {
+    await mkdir(configDir(), { recursive: true })
+    const file: CacheFile = { fetchedAt: Date.now(), dates: fetched }
+    await Bun.write(phpEolCachePath(), JSON.stringify(file, null, 2) + "\n")
+  } catch {
+    /* best-effort cache write */
+  }
+  return { ...EMBEDDED_PHP_EOL, ...fetched }
+}