sportsing 0.2.0 → 0.3.0

package/src/daemon.ts

@@ -0,0 +1,409 @@
+// The always-on `sportsing daemon`: a per-user launchd agent that polls every
+// sport with a favorite and, when a favorite's game starts, opens it the way
+// `<sport> watch` would (or notifies, per `daemon.mode`). Everything here is
+// pure — start detection, dedupe, poll cadence, the launchd plist, the
+// `launchctl print` parse, and the status/staleness verdict — so it's
+// unit-tested without launchd, the real config, or the network. The command
+// (src/commands/daemon.ts) does the IO.
+
+import type { Game, GameState } from "./game.ts";
+import type { InstallMethod } from "./upgrade.ts";
+import { planWatch, watchOf, type WatchContext } from "./watch-route.ts";
+
+/** launchd label, plist basename, and `launchctl … gui/<uid>/<label>` target. */
+export const DAEMON_LABEL = "com.sportsing.daemon";
+
+export const DAEMON_MODES = ["open", "notify"] as const;
+export type DaemonMode = (typeof DAEMON_MODES)[number];
+export const DEFAULT_DAEMON_MODE: DaemonMode = "open";
+
+/** A stored/typed mode, or null when it isn't one. */
+export function parseDaemonMode(v: unknown): DaemonMode | null {
+  const s = typeof v === "string" ? v.trim().toLowerCase() : "";
+  return (DAEMON_MODES as readonly string[]).includes(s) ? (s as DaemonMode) : null;
+}
+
+/** Stored mode, defaulting to `open` for unset/unknown values. */
+export function daemonModeOf(stored: unknown): DaemonMode {
+  return parseDaemonMode(stored) ?? DEFAULT_DAEMON_MODE;
+}
+
+// ── Games ────────────────────────────────────────────────────────────────────
+
+/** What a game start does, as `<sport> watch` would decide it. */
+export type Route =
+  /** A stream to open; `note` says which service and why. */
+  | { kind: "open"; note: string }
+  /** Over the air only — nothing to open; `message` names the channel. */
+  | { kind: "tune"; message: string }
+  /** Can't be watched (or placed); `message` says why. */
+  | { kind: "none"; message: string };
+
+/** One favorite-team game as the daemon sees it, sport-neutral. */
+export interface DaemonGame {
+  /** `<sport>:<game id>` — the dedupe key. */
+  key: string;
+  sport: string;
+  icon: string;
+  /** "DEN @ UTAH" (away @ home). */
+  fixture: string;
+  /** ISO scheduled start. */
+  start: string;
+  state: GameState;
+  /** argv (after the sportsing executable) that opens it with no TTY. */
+  openArgs: string[];
+  /** argv for an interactive `watch` (click-to-watch, in a Terminal window). */
+  clickArgs: string[];
+  route: Route;
+}
+
+/**
+ * How an ESPN-league game start is routed — the same decision `<sport> watch`
+ * makes: with subscriptions, the watchability resolver (Fubo / League Pass
+ * open, over-the-air names the channel, unwatchable says why); without them,
+ * the configured / league-default provider, if any.
+ */
+export function leagueRoute(g: Game, watch: WatchContext | null, fallback: string | null): Route {
+  if (!watch) {
+    return fallback
+      ? { kind: "open", note: `${fallback} (no subscriptions set)` }
+      : { kind: "none", message: "no streaming provider — run `sportsing subscriptions set …`" };
+  }
+  const plan = planWatch(watchOf(g, watch), fallback);
+  return plan.kind === "open" ? { kind: "open", note: plan.note } : plan;
+}
+
+/** The daemon's view of an ESPN-league game; `favIds` picks the team `watch` follows. */
+export function leagueDaemonGame(
+  sport: string,
+  icon: string,
+  g: Game,
+  favIds: ReadonlySet<string>,
+  route: Route,
+): DaemonGame {
+  // Either favorite's id finds the same game; prefer home, as `watch` does.
+  const team = [g.home, g.away].find((t) => favIds.has(t.id))?.id ?? g.home.id;
+  return {
+    key: `${sport}:${g.id}`,
+    sport,
+    icon,
+    fixture: `${g.away.abbreviation} @ ${g.home.abbreviation}`,
+    start: g.date,
+    state: g.state,
+    openArgs: [sport, "watch", team, "--supervised"],
+    clickArgs: [sport, "watch", team],
+    route,
+  };
+}
+
+/** Short "where it'll open" text for status lines. */
+export function routeWhere(r: Route, mode: DaemonMode): string {
+  if (r.kind === "open") return mode === "open" ? `opens ${r.note}` : `notifies (click to open ${r.note})`;
+  if (r.kind === "tune") return `notifies: ${r.message}`;
+  return `notifies: ✗ ${r.message}`;
+}
+
+// ── Cadence ──────────────────────────────────────────────────────────────────
+
+/** Poll interval when no favorite game is close. */
+export const SPARSE_POLL_MS = 10 * 60_000;
+/** Poll interval from LEAD_MS before a scheduled start until it goes live. */
+export const TIGHT_POLL_MS = 30_000;
+/** How long before a scheduled start polling tightens. */
+export const LEAD_MS = 15 * 60_000;
+/** How long past its scheduled start a not-yet-live game is still awaited
+ *  (delayed starts, a lagging feed) — matches `watch`'s START_GRACE_MS. */
+export const START_GRACE_MS = 3 * 60 * 60_000;
+
+/** The not-yet-started game the daemon is waiting for: the earliest `pre`
+ *  game that's upcoming or still within START_GRACE_MS of its start. */
+export function nextUp(games: DaemonGame[], now: number): DaemonGame | null {
+  return (
+    games
+      .filter((g) => g.state === "pre" && Date.parse(g.start) >= now - START_GRACE_MS)
+      .sort((a, b) => Date.parse(a.start) - Date.parse(b.start))[0] ?? null
+  );
+}
+
+/**
+ * How long to sleep before the next poll: tight (30s) from LEAD_MS before the
+ * next game's scheduled start until it flips live — including past the start
+ * for a delayed one — else sparse, waking early enough to be tight by LEAD_MS.
+ */
+export function pollDelayMs(games: DaemonGame[], now: number): number {
+  const n = nextUp(games, now);
+  if (!n) return SPARSE_POLL_MS;
+  const untilLead = Date.parse(n.start) - LEAD_MS - now;
+  if (untilLead <= 0) return TIGHT_POLL_MS;
+  return Math.min(SPARSE_POLL_MS, Math.max(TIGHT_POLL_MS, untilLead));
+}
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+export interface NextGame {
+  key: string;
+  icon: string;
+  fixture: string;
+  start: string;
+  /** routeWhere() text. */
+  where: string;
+}
+
+export interface LastAction {
+  at: string;
+  key: string;
+  icon: string;
+  fixture: string;
+  /** What was done: "opened", "notified", "dry-run", "failed". */
+  did: string;
+  detail: string;
+}
+
+/** The daemon's persisted state (heartbeat, dedupe set, what it's doing). */
+export interface DaemonState {
+  pid: number;
+  startedAt: string;
+  version: string;
+  mode: DaemonMode;
+  /** Last completed poll. */
+  heartbeat: string | null;
+  /** The sleep chosen after that poll. */
+  pollMs: number;
+  next: NextGame | null;
+  lastAction: LastAction | null;
+  /** Game key → when it was acted on. A game is acted on at most once. */
+  acted: Record<string, string>;
+  /** Sport label → error from the last poll (that sport was skipped). */
+  errors: Record<string, string>;
+}
+
+/** How long acted-on keys are remembered (well past any game's length). */
+export const ACTED_TTL_MS = 7 * 24 * 60 * 60_000;
+
+/** Acted-on keys younger than ACTED_TTL_MS. */
+export function pruneActed(acted: Record<string, string>, now: number): Record<string, string> {
+  return Object.fromEntries(Object.entries(acted).filter(([, at]) => now - Date.parse(at) < ACTED_TTL_MS));
+}
+
+/** Live favorite games not yet acted on — what this poll should open. */
+export function startsToAct(games: DaemonGame[], acted: Record<string, string>): DaemonGame[] {
+  const seen = new Set<string>();
+  return games.filter((g) => {
+    if (g.state !== "in" || Object.hasOwn(acted, g.key) || seen.has(g.key)) return false;
+    seen.add(g.key);
+    return true;
+  });
+}
+
+/** Parse a state file's JSON; null for anything malformed. */
+export function parseDaemonState(raw: unknown): DaemonState | null {
+  const s = raw as Partial<DaemonState> | null;
+  if (!s || typeof s !== "object" || typeof s.pid !== "number" || typeof s.startedAt !== "string") return null;
+  return {
+    pid: s.pid,
+    startedAt: s.startedAt,
+    version: typeof s.version === "string" ? s.version : "?",
+    mode: daemonModeOf(s.mode),
+    heartbeat: typeof s.heartbeat === "string" ? s.heartbeat : null,
+    pollMs: typeof s.pollMs === "number" && s.pollMs > 0 ? s.pollMs : SPARSE_POLL_MS,
+    next: s.next ?? null,
+    lastAction: s.lastAction ?? null,
+    acted: s.acted && typeof s.acted === "object" ? s.acted : {},
+    errors: s.errors && typeof s.errors === "object" ? s.errors : {},
+  };
+}
+
+// ── Status ───────────────────────────────────────────────────────────────────
+
+/** A heartbeat older than this means the loop is wedged: ~3 poll intervals,
+ *  never under 3 minutes (a tight-poll fetch can legitimately take a while). */
+export function staleAfterMs(pollMs: number): number {
+  return Math.max(3 * pollMs, 3 * 60_000);
+}
+
+export interface ServiceInfo {
+  /** launchd has the job loaded. */
+  loaded: boolean;
+  /** Its running process, if any. */
+  pid?: number;
+}
+
+export type DaemonLevel =
+  /** Not installed (no plist, nothing loaded). */
+  | "off"
+  /** Installed, but no process is running it. */
+  | "down"
+  /** Running, but it hasn't completed a poll yet. */
+  | "starting"
+  /** Running, heartbeat stale. */
+  | "stuck"
+  /** Running and polling. */
+  | "on";
+
+export interface DaemonStatus {
+  level: DaemonLevel;
+  installed: boolean;
+  pid: number | null;
+  state: DaemonState | null;
+  /** ms since the last heartbeat, when there is one. */
+  heartbeatAgeMs: number | null;
+}
+
+/**
+ * The daemon's health. `service` comes from launchd (`daemon status`) or, for
+ * the cheap footer, from probing the state file's pid. The state only counts
+ * when it belongs to the running process.
+ */
+export function evaluateStatus(o: { installed: boolean; service: ServiceInfo; state: DaemonState | null; now: number }): DaemonStatus {
+  const pid = o.service.pid ?? null;
+  const base = { installed: o.installed, pid, state: o.state, heartbeatAgeMs: null as number | null };
+  if (!o.installed && !o.service.loaded) return { ...base, level: "off" };
+  if (pid === null) return { ...base, level: "down" };
+  const mine = o.state && o.state.pid === pid ? o.state : null;
+  if (!mine?.heartbeat) {
+    const since = mine ? o.now - Date.parse(mine.startedAt) : 0;
+    return { ...base, level: since > staleAfterMs(TIGHT_POLL_MS) ? "stuck" : "starting" };
+  }
+  const age = o.now - Date.parse(mine.heartbeat);
+  return { ...base, heartbeatAgeMs: age, level: age > staleAfterMs(mine.pollMs) ? "stuck" : "on" };
+}
+
+/** `daemon status` exits 0 only for this. */
+export function isHealthy(s: DaemonStatus): boolean {
+  return s.level === "on";
+}
+
+/** "7:00 PM" today, else "Sat 7:00 PM" (local time). */
+export function whenLabel(iso: string, now: number): string {
+  const d = new Date(iso);
+  const time = d.toLocaleString(undefined, { hour: "numeric", minute: "2-digit" });
+  if (d.toDateString() === new Date(now).toDateString()) return time;
+  return `${d.toLocaleString(undefined, { weekday: "short" })} ${time}`;
+}
+
+/** "45s", "12m", "3h 5m", "2d 4h". */
+export function fmtDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
+/** The one-line footer under bare today / next / me. */
+export function footerLine(s: DaemonStatus, now: number): string {
+  switch (s.level) {
+    case "off":
+      return "daemon: off — sportsing daemon install";
+    case "down":
+      return "daemon: down — installed but not running (sportsing daemon status)";
+    case "starting":
+      return "daemon: starting — sportsing daemon status";
+    case "stuck": {
+      const age = s.heartbeatAgeMs === null ? "no poll yet" : `last poll ${fmtDuration(s.heartbeatAgeMs)} ago`;
+      return `daemon: stuck — ${age} (sportsing daemon logs)`;
+    }
+    case "on": {
+      const n = s.state?.next;
+      return n ? `daemon: on — waiting for ${n.fixture} ${whenLabel(n.start, now)}` : "daemon: on — no favorite games coming up";
+    }
+  }
+}
+
+/** Pull `state` and `pid` out of `launchctl print gui/<uid>/<label>`. */
+export function parseLaunchctlPrint(out: string): ServiceInfo & { state?: string } {
+  const state = out.match(/^\s*state = (.+)$/m)?.[1]?.trim();
+  const pidStr = out.match(/^\s*pid = (\d+)/m)?.[1];
+  const pid = pidStr ? Number(pidStr) : undefined;
+  return { loaded: true, ...(state ? { state } : {}), ...(pid && state === "running" ? { pid } : {}) };
+}
+
+// ── launchd agent ────────────────────────────────────────────────────────────
+
+/**
+ * ProgramArguments for `sportsing daemon run`, pinned to the stable paths of
+ * how this copy was installed — so the agent keeps working across
+ * `sportsing upgrade` (which reinstalls into the same prefix). The bin is a
+ * Bun script, so it's run by an absolute Bun (launchd's PATH has no Bun):
+ * the bun-global install's own, else the `bun` on the installing shell's PATH
+ * (a stable shim like ~/.bun/bin/bun), else the running one. Null for
+ * installs with no stable path (npx/bunx caches, unrecognised).
+ */
+export function daemonProgram(
+  m: InstallMethod,
+  o: { execPath: string; bunOnPath: string | null; exists: (p: string) => boolean },
+): string[] | null {
+  const bun = o.bunOnPath ?? o.execPath;
+  const run = ["daemon", "run"];
+  switch (m.kind) {
+    case "npm-global":
+      return [bun, `${m.prefix}/bin/sportsing`, ...run];
+    case "bun-global": {
+      const own = `${m.bunInstall}/bin/bun`;
+      return [o.exists(own) ? own : bun, `${m.bunInstall}/bin/sportsing`, ...run];
+    }
+    case "source":
+      return [bun, `${m.root}/src/index.ts`, ...run];
+    case "compiled":
+      return [o.execPath, ...run];
+    default:
+      return null;
+  }
+}
+
+/** PATH for the agent: the installing shell's PATH (so terminal-notifier,
+ *  osascript and Chrome resolve as they do for you), plus the system dirs,
+ *  de-duplicated in order. */
+export function agentPath(shellPath: string | undefined, extra: string[] = []): string {
+  const sys = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+  const parts = [...extra, ...(shellPath ?? "").split(":"), ...sys].filter(Boolean);
+  return [...new Set(parts)].join(":");
+}
+
+function xml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/**
+ * The LaunchAgent plist: run at login, restart if it exits (throttled), log
+ * stdout+stderr to `logPath`. AbandonProcessGroup keeps a game window the
+ * daemon opened alive across a daemon restart (e.g. after an upgrade).
+ */
+export function launchAgentPlist(o: { label: string; program: string[]; logPath: string; path: string; home: string }): string {
+  const args = o.program.map((a) => `    <string>${xml(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(o.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>WorkingDirectory</key>
+  <string>${xml(o.home)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xml(o.path)}</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xml(o.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(o.logPath)}</string>
+</dict>
+</plist>
+`;
+}

package/src/index.ts

@@ -3,6 +3,8 @@ import { c } from "./ansi.ts";
 import { ApiError } from "./api.ts";
 import { SPORTS as REGISTRY, bare } from "./commands/cross.ts";
 import { subscriptions } from "./commands/subscriptions.ts";
+import { upgrade } from "./commands/upgrade.ts";
+import { daemon } from "./commands/daemon.ts";
 import pkg from "../package.json" with { type: "json" };
 
 // Single source of truth: package.json (a hardcoded copy drifted to a stale
@@ -38,6 +40,8 @@ ${b("YOUR TEAMS")} ${c.dim("(favorites across every sport, each row tagged with
 
 ${b("SETTINGS")}
   ${c.green("subscriptions")}      What you can watch with + home market ${c.dim("— alias: subs")}
+  ${c.green("upgrade")}            Install the latest release ${c.dim("(--check: just compare versions)")}
+  ${c.green("daemon")}             Always-on watcher that opens your teams' games ${c.dim("(install · status · logs · mode · uninstall)")}
 
 ${b("EXAMPLES")}
   sportsing fifa today
@@ -69,6 +73,14 @@ async function dispatch(): Promise<void> {
     await subscriptions(rest);
     return;
   }
+  if (first === "upgrade") {
+    await upgrade(rest, VERSION);
+    return;
+  }
+  if (first === "daemon") {
+    await daemon(rest, VERSION);
+    return;
+  }
 
   // Bare `today`/`next`/`me`/`live` run across every sport; anything else gets a hint.
   await bare(first, rest);

package/src/match-util.ts

@@ -3,8 +3,16 @@
 // like events.ts can share one source of truth without events.ts taking a
 // dependency on the I/O-bearing command layer.
 
+import type { GameState } from "./game.ts";
 import type { Match } from "./types.ts";
 
+/** A football-data match status as a sport-neutral game state. */
+export function matchState(m: Pick<Match, "status">): GameState {
+  if (m.status === "IN_PLAY" || m.status === "PAUSED") return "in";
+  if (m.status === "FINISHED" || m.status === "AWARDED") return "post";
+  return "pre";
+}
+
 /** True if either side of the match matches `needle` (lowercased) by name/tla/shortName. */
 export function matchHasTeam(m: Match, needle: string): boolean {
   const fields = [

package/src/upgrade.ts

@@ -0,0 +1,182 @@
+// Pure helpers behind `sportsing upgrade`: work out how the running copy was
+// installed, compare versions, and build the reinstall command. No I/O here —
+// the command (src/commands/upgrade.ts) does the realpath, fetch and spawn.
+
+export const PACKAGE = "sportsing";
+export const REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
+
+export type InstallMethod =
+  /** `npm install -g` — the script lives at `<prefix>/lib/node_modules/sportsing/…`. */
+  | { kind: "npm-global"; prefix: string }
+  /** `bun add -g` — the script lives at `<bunInstall>/install/global/node_modules/sportsing/…`. */
+  | { kind: "bun-global"; bunInstall: string }
+  /** A one-off `npx` / `bunx` run out of a temp cache. */
+  | { kind: "ephemeral" }
+  /** `bun run build`'s standalone `dist/sportsing`. */
+  | { kind: "compiled" }
+  /** A git checkout run with `bun run src/index.ts`. */
+  | { kind: "source"; root: string }
+  /** A project-local dependency or anything else we don't recognise. */
+  | { kind: "unknown" };
+
+const PKG_SEG = `/node_modules/${PACKAGE}/`;
+
+/**
+ * Classify the running copy from the realpath of its entry script (`Bun.main`).
+ * Order matters: temp caches also contain `node_modules/sportsing/`, so they're
+ * ruled out before the global-install patterns.
+ */
+export function detectInstall(scriptPath: string): InstallMethod {
+  const p = scriptPath.replace(/\\/g, "/");
+
+  // Compiled binaries report a virtual path inside Bun's embedded filesystem.
+  if (p.includes("/$bunfs/") || p.includes("~BUN/")) return { kind: "compiled" };
+
+  if (p.includes(PKG_SEG)) {
+    // npx: ~/.npm/_npx/<hash>/node_modules/sportsing; bunx: $TMPDIR/bunx-<uid>-sportsing@…/node_modules/sportsing
+    if (p.includes("/_npx/") || /\/bunx-[^/]*\//.test(p)) return { kind: "ephemeral" };
+
+    const bun = p.match(/^(.*)\/install\/global\/node_modules\/sportsing\//);
+    if (bun) return { kind: "bun-global", bunInstall: bun[1]! };
+
+    const npm = p.match(/^(.*)\/lib\/node_modules\/sportsing\//);
+    if (npm) return { kind: "npm-global", prefix: npm[1]! };
+
+    return { kind: "unknown" };
+  }
+
+  const src = p.match(/^(.*)\/src\/index\.ts$/);
+  if (src) return { kind: "source", root: src[1]! };
+
+  // A compiled binary renamed or run from a real path (older Bun / other OS).
+  if (!p.endsWith(".ts") && !p.endsWith(".js")) return { kind: "compiled" };
+
+  return { kind: "unknown" };
+}
+
+export function canSelfUpgrade(m: InstallMethod): m is Extract<InstallMethod, { kind: "npm-global" | "bun-global" }> {
+  return m.kind === "npm-global" || m.kind === "bun-global";
+}
+
+/** Human description of the install, for status lines. */
+export function describeInstall(m: InstallMethod): string {
+  switch (m.kind) {
+    case "npm-global":
+      return `npm global install (${m.prefix})`;
+    case "bun-global":
+      return `bun global install (${m.bunInstall})`;
+    case "ephemeral":
+      return "npx/bunx temporary cache";
+    case "compiled":
+      return "compiled standalone binary";
+    case "source":
+      return `source checkout (${m.root})`;
+    case "unknown":
+      return "unrecognised install";
+  }
+}
+
+/** How to update an install `sportsing upgrade` won't touch itself. */
+export function manualUpgradeHint(m: InstallMethod): string {
+  switch (m.kind) {
+    case "source":
+      return `This is a source checkout. Update it with git:\n  cd ${m.root} && git pull && bun install`;
+    case "compiled":
+      return "This is a compiled standalone binary. Rebuild it from an updated checkout:\n  git pull && bun install && bun run build";
+    case "ephemeral":
+      return `This is a temporary npx/bunx copy. Run the latest directly:\n  npx ${PACKAGE}@latest   (or: bunx ${PACKAGE}@latest)\nor install it globally so \`sportsing upgrade\` can manage it:\n  npm install -g ${PACKAGE}   (or: bun add -g ${PACKAGE})`;
+    case "unknown":
+      return `Couldn't tell how this copy was installed. Reinstall it with your package manager:\n  npm install -g ${PACKAGE}@latest   (or: bun add -g ${PACKAGE}@latest)`;
+    default:
+      return "";
+  }
+}
+
+export interface Command {
+  cmd: string[];
+  /** Where the upgraded `sportsing` bin lands, to confirm the new version. */
+  bin: string;
+}
+
+/**
+ * The reinstall command for a self-upgradable install. For npm, prefer the
+ * node + npm sitting in that prefix (nvm's *active* node may be a different
+ * version) and pin `--prefix` so the package lands back where it came from.
+ * `exists` is injected so this stays pure.
+ */
+export function installCommand(
+  m: Extract<InstallMethod, { kind: "npm-global" | "bun-global" }>,
+  exists: (path: string) => boolean,
+): Command {
+  const spec = `${PACKAGE}@latest`;
+  if (m.kind === "bun-global") {
+    const localBun = `${m.bunInstall}/bin/bun`;
+    return {
+      cmd: [exists(localBun) ? localBun : "bun", "add", "-g", spec],
+      bin: `${m.bunInstall}/bin/${PACKAGE}`,
+    };
+  }
+  const node = `${m.prefix}/bin/node`;
+  const npm = `${m.prefix}/bin/npm`;
+  const runner = exists(npm) ? (exists(node) ? [node, npm] : [npm]) : ["npm"];
+  return {
+    cmd: [...runner, "install", "-g", "--prefix", m.prefix, spec],
+    bin: `${m.prefix}/bin/${PACKAGE}`,
+  };
+}
+
+interface Semver {
+  core: [number, number, number];
+  pre: string[];
+}
+
+function parseSemver(v: string): Semver | null {
+  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!m) return null;
+  return { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split(".") : [] };
+}
+
+export function isValidVersion(v: string): boolean {
+  return parseSemver(v) !== null;
+}
+
+/** semver precedence: -1 if a < b, 0 if equal, 1 if a > b. Throws on a malformed version. */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) throw new Error(`Not a semver version: ${!pa ? a : b}`);
+  for (let i = 0; i < 3; i++) {
+    if (pa.core[i]! !== pb.core[i]!) return pa.core[i]! < pb.core[i]! ? -1 : 1;
+  }
+  // A release outranks any of its prereleases.
+  if (!pa.pre.length || !pb.pre.length) {
+    if (pa.pre.length === pb.pre.length) return 0;
+    return pa.pre.length ? -1 : 1;
+  }
+  for (let i = 0; i < Math.max(pa.pre.length, pb.pre.length); i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) return Number(x) < Number(y) ? -1 : 1;
+    if (xn !== yn) return xn ? -1 : 1; // numeric identifiers sort before alphanumeric
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Pull `version` out of the registry's `/<pkg>/latest` document. */
+export function parseRegistryLatest(body: unknown): string {
+  const v = (body as { version?: unknown } | null)?.version;
+  if (typeof v !== "string" || !isValidVersion(v)) throw new Error("Registry response had no valid version.");
+  return v;
+}
+
+/** Pull the version out of `sportsing --version` output (`sportsing 0.2.1`). */
+export function parseVersionOutput(out: string): string | null {
+  const m = out.match(/sportsing\s+v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+  return m ? m[1]! : null;
+}