sportsing 0.1.0

package/src/espn.ts

@@ -0,0 +1,307 @@
+// ESPN's free, no-key JSON API — the stats source for the live 2026 World Cup.
+// Used by stats / predict. Returns per-team match statistics (possession,
+// shots, passes, cards…), rosters, and key events for `soccer/fifa.world`.
+//
+// Undocumented/unofficial: the shapes here are observed, not contracted, and
+// could change. All ESPN-specific parsing is contained in this module so a
+// break is a one-file fix. Reuses api.ts's disk cache.
+
+import { cached, ApiError } from "./api.ts";
+import { c } from "./ansi.ts";
+
+const BASE = "https://site.api.espn.com/apis/site/v2/sports/soccer/fifa.world";
+
+/**
+ * Detect a *structurally* wrong scoreboard response. ESPN is unofficial and
+ * returns HTTP 200 even when its JSON shape drifts, so the parser's `?? ""`
+ * fallbacks would silently degrade to blank stats — indistinguishable from
+ * "no data yet". This keys on shape, NOT emptiness: a date with no matches
+ * (`events: []`) and a pre-kickoff match with no stats are both fine.
+ *
+ * Off when: the `events` key is missing or not an array, or an *in-play* event
+ * has zero competitors or unnamed ("?") teams (a live match always has named
+ * competitors — if it doesn't, the nested shape changed).
+ */
+export function looksOff(raw: any): boolean {
+  if (!raw || typeof raw !== "object" || !Array.isArray(raw.events)) return true;
+  for (const e of raw.events) {
+    const comp = e?.competitions?.[0];
+    // Status lives on the competition, but ESPN sometimes mirrors it on the event
+    // itself — check both, same fallback normalizeEvent uses.
+    const state = comp?.status?.type?.state ?? e?.status?.type?.state;
+    if (state !== "in") continue; // only live matches must have full structure
+    const competitors = comp?.competitors ?? [];
+    if (competitors.length === 0) return true;
+    if (!competitors.every((cc: any) => cc?.team?.displayName ?? cc?.team?.name)) return true;
+  }
+  return false;
+}
+
+let driftWarned = false;
+
+/** Emit the ESPN-drift warning to stderr, at most once per process run. */
+function warnDriftOnce(): void {
+  if (driftWarned) return;
+  driftWarned = true;
+  console.error(c.yellow("⚠ ESPN data looks off — its format may have changed; it's an unofficial API."));
+}
+
+/** WC2026 scoreboard search window (YYYYMMDD) — opening day → final. */
+export const TOURNAMENT_START = "20260611";
+export const TOURNAMENT_END = "20260719";
+
+export interface EspnCompetitor {
+  homeAway: "home" | "away";
+  name: string;
+  abbreviation: string;
+  score: string;
+}
+
+export interface EspnEvent {
+  id: string;
+  date: string;
+  name: string;
+  /** "pre" (scheduled), "in" (live), "post" (finished). */
+  state: "pre" | "in" | "post";
+  detail: string; // e.g. "FT", "45'", "1:00 - 1st Half"
+  competitors: EspnCompetitor[];
+}
+
+/** One team's stat block for a match: a flat list of named stat rows. */
+export interface EspnTeamStats {
+  team: string;
+  abbreviation: string;
+  stats: { name: string; label: string; value: string }[];
+}
+
+function normalizeEvent(e: any): EspnEvent {
+  const comp = e.competitions?.[0] ?? {};
+  return {
+    id: String(e.id),
+    date: e.date,
+    name: e.name ?? e.shortName ?? "",
+    state: comp.status?.type?.state ?? e.status?.type?.state ?? "pre",
+    detail: comp.status?.type?.shortDetail ?? e.status?.type?.shortDetail ?? "",
+    competitors: (comp.competitors ?? []).map((c: any) => ({
+      homeAway: c.homeAway,
+      name: c.team?.displayName ?? c.team?.name ?? "?",
+      abbreviation: c.team?.abbreviation ?? "",
+      score: c.score ?? "",
+    })),
+  };
+}
+
+/** Scoreboard events for a date or `YYYYMMDD-YYYYMMDD` range. */
+export async function getScoreboard(dates: string, ttlMs = 60_000): Promise<EspnEvent[]> {
+  const raw = await cached<any>(`espn_sb_${dates}`, ttlMs, async () => {
+    const res = await fetch(`${BASE}/scoreboard?dates=${dates}`);
+    if (!res.ok) throw new ApiError(res.status, `ESPN scoreboard request failed (HTTP ${res.status}).`);
+    return res.json();
+  });
+  if (looksOff(raw)) warnDriftOnce();
+  return (raw.events ?? []).map(normalizeEvent);
+}
+
+/** Every tournament event — played and upcoming (opening day → final). The full
+ *  window so `predict` can see matches days out, not just the next day. */
+export async function getEvents(ttlMs = 60_000): Promise<EspnEvent[]> {
+  return getScoreboard(`${TOURNAMENT_START}-${TOURNAMENT_END}`, ttlMs);
+}
+
+function eventHasTeam(e: EspnEvent, term: string): boolean {
+  return e.competitors.some(
+    (c) => c.name.toLowerCase().includes(term) || c.abbreviation.toLowerCase() === term,
+  );
+}
+
+/**
+ * Resolve free-text terms to a single event. Every term must match a team
+ * (so "USA" → any USA game; "USA Paraguay" → that specific game). With
+ * `playedOnly`, ignores not-yet-started games. Returns the most recent match.
+ */
+export async function findEvent(terms: string[], opts: { playedOnly?: boolean } = {}): Promise<EspnEvent | null> {
+  const t = terms.map((s) => s.toLowerCase());
+  let events = (await getEvents()).filter((e) => t.every((term) => eventHasTeam(e, term)));
+  if (opts.playedOnly) events = events.filter((e) => e.state !== "pre");
+  events.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  return events[0] ?? null;
+}
+
+export interface H2HGame {
+  date: string;
+  score: string;
+  result: "W" | "D" | "L" | "?";
+}
+
+/** Prior meetings between the two sides of an event (summary headToHeadGames),
+ *  results from the first listed team's perspective. */
+export async function getHeadToHead(
+  eventId: string,
+  ttlMs = 60 * 60_000,
+): Promise<{ team: string; games: H2HGame[] }> {
+  // Separate cache key from getMatchStats (which also hits /summary on a short
+  // TTL) — a shared key would let the shorter TTL win and refetch H2H needlessly.
+  const raw = await cached<any>(`espn_h2h_${eventId}`, ttlMs, async () => {
+    const res = await fetch(`${BASE}/summary?event=${eventId}`);
+    if (!res.ok) throw new ApiError(res.status, `ESPN summary request failed (HTTP ${res.status}).`);
+    return res.json();
+  });
+  const block = (raw.headToHeadGames ?? [])[0];
+  if (!block) return { team: "", games: [] };
+  const games: H2HGame[] = (block.events ?? []).map((e: any) => {
+    const [a, b] = String(e.score ?? "").split("-").map(Number);
+    const result: H2HGame["result"] =
+      a === undefined || b === undefined || Number.isNaN(a) || Number.isNaN(b) ? "?" : a > b ? "W" : a < b ? "L" : "D";
+    return { date: String(e.gameDate ?? e.date ?? "").slice(0, 10), score: String(e.score ?? ""), result };
+  });
+  return { team: block.team?.displayName ?? "", games };
+}
+
+export interface LiveMatch {
+  detail: string; // clock/status, e.g. "66'", "HT", "FT"
+  state: "pre" | "in" | "post";
+  kickoff: string; // ISO kickoff time (for the pre-game countdown)
+  homeAbbr: string;
+  awayAbbr: string;
+  homeScore: string;
+  awayScore: string;
+  possession?: [string, string];
+  shots?: [string, string];
+  onTarget?: [string, string];
+  /** Market-implied win % (de-vigged) from ESPN odds: [home, draw, away], 0–100. */
+  winProb?: [number, number, number];
+  /** Raw 3-way odds line, e.g. "QAT +1500 / X +600 / SUI -525". */
+  oddsLine?: string;
+  /** Notable in-match events (goals, cards, subs…), most recent first. */
+  events?: { clock: string; type: string; team: string; text: string }[];
+}
+
+/** American moneyline → implied probability (0–1). */
+function mlToProb(ml: number): number {
+  return ml >= 0 ? 100 / (ml + 100) : -ml / (-ml + 100);
+}
+
+/** Fresh live state for one match in a single call: clock + score (summary
+ *  header) and stats (boxscore). Short TTL — this drives the live overlay. */
+export async function getLiveMatch(eventId: string, ttlMs = 5_000): Promise<LiveMatch | null> {
+  const raw = await cached<any>(`espn_live_${eventId}`, ttlMs, async () => {
+    const res = await fetch(`${BASE}/summary?event=${eventId}`);
+    if (!res.ok) throw new ApiError(res.status, `ESPN summary request failed (HTTP ${res.status}).`);
+    return res.json();
+  });
+  const comp = raw.header?.competitions?.[0];
+  if (!comp) return null;
+  const hc = (comp.competitors ?? []).find((c: any) => c.homeAway === "home");
+  const ac = (comp.competitors ?? []).find((c: any) => c.homeAway === "away");
+  const teams = raw.boxscore?.teams ?? [];
+  const byAbbr = (a?: string) => teams.find((t: any) => t.team?.abbreviation === a);
+  const ht = byAbbr(hc?.team?.abbreviation) ?? teams[0];
+  const at = byAbbr(ac?.team?.abbreviation) ?? teams[1];
+  const stat = (t: any, n: string): string | undefined => {
+    const s = (t?.statistics ?? []).find((x: any) => x.name === n);
+    return s ? String(s.displayValue) : undefined;
+  };
+  const pair = (n: string): [string, string] | undefined => {
+    const h = stat(ht, n);
+    const a = stat(at, n);
+    return h === undefined && a === undefined ? undefined : [h ?? "—", a ?? "—"];
+  };
+  const homeAbbr = hc?.team?.abbreviation ?? "?";
+  const awayAbbr = ac?.team?.abbreviation ?? "?";
+
+  // Notable in-match events (goals, cards, subs, VAR…) from the summary's
+  // keyEvents feed — most recent first, capped so the overlay panel stays small.
+  const events = (raw.keyEvents ?? [])
+    .map((k: any) => ({
+      clock: k.clock?.displayValue ?? "",
+      type: k.type?.text ?? "",
+      team: k.team?.abbreviation ?? k.team?.displayName ?? "",
+      text: k.text ?? k.shortText ?? "",
+    }))
+    .filter((e: { type: string; text: string }) => e.type || e.text)
+    .reverse()
+    .slice(0, 8);
+
+  // Win probability + odds line, derived from the 3-way moneyline.
+  let winProb: [number, number, number] | undefined;
+  let oddsLine: string | undefined;
+  const o = raw.pickcenter?.[0] ?? raw.odds?.[0];
+  const hml = o?.homeTeamOdds?.moneyLine;
+  const aml = o?.awayTeamOdds?.moneyLine;
+  const dml = o?.drawOdds?.moneyLine;
+  if (typeof hml === "number" && typeof aml === "number" && typeof dml === "number") {
+    const ph = mlToProb(hml);
+    const pd = mlToProb(dml);
+    const pa = mlToProb(aml);
+    const sum = ph + pd + pa;
+    winProb = sum > 0 ? [Math.round((ph / sum) * 100), Math.round((pd / sum) * 100), Math.round((pa / sum) * 100)] : undefined;
+    const fmt = (n: number) => (n >= 0 ? "+" + n : String(n));
+    oddsLine = `${homeAbbr} ${fmt(hml)} / X ${fmt(dml)} / ${awayAbbr} ${fmt(aml)}`;
+  }
+
+  return {
+    detail: comp.status?.type?.shortDetail ?? "",
+    state: comp.status?.type?.state ?? "pre",
+    kickoff: comp.date ?? "",
+    homeAbbr,
+    awayAbbr,
+    homeScore: String(hc?.score ?? "0"),
+    awayScore: String(ac?.score ?? "0"),
+    possession: pair("possessionPct"),
+    shots: pair("totalShots"),
+    onTarget: pair("shotsOnTarget"),
+    winProb,
+    oddsLine,
+    events,
+  };
+}
+
+/** Resolve terms to the *currently relevant* match: live now → today → next
+ *  upcoming → most recent. (findEvent returns the latest-scheduled, which is
+ *  wrong for "watch <team>" when a team has several fixtures.) */
+export async function findCurrentMatch(terms: string[]): Promise<EspnEvent | null> {
+  const t = terms.map((s) => s.toLowerCase());
+  const events = (await getEvents()).filter((e) => t.every((term) => eventHasTeam(e, term)));
+  if (!events.length) return null;
+  const live = events.find((e) => e.state === "in");
+  if (live) return live;
+  const today = new Date().toLocaleDateString();
+  const todayGame = events.find((e) => new Date(e.date).toLocaleDateString() === today);
+  if (todayGame) return todayGame;
+  const upcoming = events.filter((e) => e.state === "pre").sort((a, b) => +new Date(a.date) - +new Date(b.date))[0];
+  if (upcoming) return upcoming;
+  return events.sort((a, b) => +new Date(b.date) - +new Date(a.date))[0] ?? null;
+}
+
+/** The match `watch --wait` should poll toward: a currently-live one matching
+ *  `terms` (or any live match if `terms` is empty), else the soonest upcoming.
+ *  Returns null when nothing matching is live or scheduled. Short default TTL so
+ *  the kickoff→in-play transition is seen promptly. ESPN's `state` is the live
+ *  signal (no key, same source the overlay follows — unlike the lagging
+ *  football-data feed behind `live`). */
+export async function resolveWatchTarget(terms: string[], ttlMs = 15_000): Promise<EspnEvent | null> {
+  const t = terms.map((s) => s.toLowerCase());
+  const events = (await getEvents(ttlMs)).filter((e) => t.every((term) => eventHasTeam(e, term)));
+  const live = events.find((e) => e.state === "in");
+  if (live) return live;
+  return events.filter((e) => e.state === "pre").sort((a, b) => +new Date(a.date) - +new Date(b.date))[0] ?? null;
+}
+
+/** Per-team statistics for one event (from the summary boxscore). */
+export async function getMatchStats(eventId: string, ttlMs = 60_000): Promise<EspnTeamStats[]> {
+  const raw = await cached<any>(`espn_sum_${eventId}`, ttlMs, async () => {
+    const res = await fetch(`${BASE}/summary?event=${eventId}`);
+    if (!res.ok) throw new ApiError(res.status, `ESPN summary request failed (HTTP ${res.status}).`);
+    return res.json();
+  });
+  const teams = raw.boxscore?.teams ?? [];
+  return teams.map((t: any) => ({
+    team: t.team?.displayName ?? t.team?.name ?? "?",
+    abbreviation: t.team?.abbreviation ?? "",
+    stats: (t.statistics ?? []).map((s: any) => ({
+      name: s.name,
+      label: s.label ?? s.name,
+      value: String(s.displayValue ?? s.value ?? ""),
+    })),
+  }));
+}

package/src/events.ts

@@ -0,0 +1,85 @@
+// Pure match-snapshot diffing: turn two successive score polls into discrete
+// favourite-team events (kickoff / goal / full-time). No I/O — the live tick
+// (AGT-508) holds the previous snapshot and feeds successive polls in here, then
+// routes the returned events to notify(). Idempotent: diffing a snapshot against
+// itself yields nothing, so the same transition never alerts twice.
+
+import { teamLabel } from "./format.ts";
+import { matchHasTeam } from "./match-util.ts";
+import type { Match, MatchStatus } from "./types.ts";
+
+export type MatchEventKind = "kickoff" | "goal" | "full-time";
+
+export interface MatchEvent {
+  kind: MatchEventKind;
+  matchId: number;
+  /** Short fixture label, e.g. "USA vs ENG". */
+  fixture: string;
+  home: string;
+  away: string;
+  /** Scoreline at the moment of the event (0–0 at kickoff, final at full-time). */
+  score: { home: number; away: number };
+  /** For goals only: which side scored. */
+  scoringSide?: "home" | "away";
+}
+
+const PRE: ReadonlySet<MatchStatus> = new Set(["SCHEDULED", "TIMED"]);
+const LIVE: ReadonlySet<MatchStatus> = new Set(["IN_PLAY", "PAUSED"]);
+const POST: ReadonlySet<MatchStatus> = new Set(["FINISHED", "AWARDED"]);
+
+/** Current goals for each side, treating a not-yet-reported score as 0. */
+function goalsOf(m: Match): { home: number; away: number } {
+  return { home: m.score.fullTime.home ?? 0, away: m.score.fullTime.away ?? 0 };
+}
+
+/**
+ * Diff two match-list snapshots into favourite-team events.
+ *
+ * - `kickoff`   — status moved pre (SCHEDULED/TIMED) → live (IN_PLAY/PAUSED)
+ * - `goal`      — a side's goal count increased (one event per side that scored)
+ * - `full-time` — status moved live → post (FINISHED/AWARDED)
+ *
+ * Only matches involving a favourite team are considered. A match must appear in
+ * both snapshots (keyed by id) to diff a transition; brand-new entries are skipped
+ * until there is a prior state to compare against. Pure and order-stable.
+ *
+ * Polling-model caveat: at most one `goal` event is emitted per side per tick.
+ * If a side's count jumps by more than one between polls (a multi-goal burst in
+ * one interval), it collapses to a single event carrying the resulting scoreline —
+ * the intermediate goals are not reconstructable from two snapshots.
+ */
+export function diffEvents(prev: Match[], cur: Match[], favorites: string[]): MatchEvent[] {
+  const favs = favorites.map((f) => f.trim().toLowerCase()).filter(Boolean);
+  if (favs.length === 0) return [];
+
+  const prevById = new Map(prev.map((m) => [m.id, m]));
+  const events: MatchEvent[] = [];
+
+  for (const m of cur) {
+    if (!favs.some((n) => matchHasTeam(m, n))) continue;
+    const before = prevById.get(m.id);
+    if (!before) continue; // need a prior state to diff a transition
+
+    const base = {
+      matchId: m.id,
+      fixture: `${teamLabel(m.homeTeam)} vs ${teamLabel(m.awayTeam)}`,
+      home: teamLabel(m.homeTeam),
+      away: teamLabel(m.awayTeam),
+    };
+    const score = goalsOf(m);
+
+    if (PRE.has(before.status) && LIVE.has(m.status)) {
+      events.push({ kind: "kickoff", ...base, score });
+    }
+
+    const wasScore = goalsOf(before);
+    if (score.home > wasScore.home) events.push({ kind: "goal", ...base, score, scoringSide: "home" });
+    if (score.away > wasScore.away) events.push({ kind: "goal", ...base, score, scoringSide: "away" });
+
+    if (LIVE.has(before.status) && POST.has(m.status)) {
+      events.push({ kind: "full-time", ...base, score });
+    }
+  }
+
+  return events;
+}

package/src/format.ts

@@ -0,0 +1,180 @@
+import { c, pad, visibleLen } from "./ansi.ts";
+import type { Match, StandingRow, Stage } from "./types.ts";
+
+export function teamLabel(t: { name: string | null; tla?: string | null }): string {
+  return t.tla || t.name || "TBD";
+}
+
+export function fmtDate(iso: string): string {
+  const d = new Date(iso);
+  return d.toLocaleString(undefined, {
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
+export function fmtTimeOnly(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, { hour: "numeric", minute: "2-digit" });
+}
+
+/** Date-only header, e.g. "Sat, Jun 13" — for grouping a list by day (local). */
+export function fmtDayHeader(iso: string): string {
+  return new Date(iso).toLocaleDateString(undefined, {
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+function statusBadge(m: Match): string {
+  switch (m.status) {
+    case "IN_PLAY":
+      return c.bgGreen(c.bold(" LIVE ")) + (m.minute ? c.green(` ${m.minute}'`) : "");
+    case "PAUSED":
+      return c.yellow("HT");
+    case "FINISHED":
+      return c.dim("FT");
+    case "POSTPONED":
+      return c.red("PPD");
+    case "CANCELLED":
+      return c.red("CANC");
+    case "SUSPENDED":
+      return c.red("SUSP");
+    default:
+      return c.cyan(fmtTimeOnly(m.utcDate));
+  }
+}
+
+/** One match as a single aligned line: "ENG  2 - 1  USA   FT". */
+export function matchLine(m: Match): string {
+  const home = teamLabel(m.homeTeam);
+  const away = teamLabel(m.awayTeam);
+  const hs = m.score.fullTime.home;
+  const as = m.score.fullTime.away;
+  const played = hs != null && as != null;
+
+  const scoreCol = played
+    ? scoreStr(hs, as, m)
+    : c.dim(" v ");
+
+  const homeStr = winnerBold(home, m, "HOME_TEAM");
+  const awayStr = winnerBold(away, m, "AWAY_TEAM");
+
+  return (
+    pad(homeStr, 18, "right") +
+    "  " +
+    pad(scoreCol, 9) +
+    "  " +
+    pad(awayStr, 18, "left") +
+    "  " +
+    statusBadge(m)
+  );
+}
+
+function scoreStr(hs: number, as: number, m: Match): string {
+  const live = m.status === "IN_PLAY" || m.status === "PAUSED";
+  const core = `${hs} - ${as}`;
+  return live ? c.green(c.bold(core)) : c.bold(core);
+}
+
+function winnerBold(name: string, m: Match, side: "HOME_TEAM" | "AWAY_TEAM"): string {
+  return m.score.winner === side ? c.bold(c.white(name)) : name;
+}
+
+export function groupName(g: string | null): string {
+  if (!g) return "";
+  return g.replace("GROUP_", "Group ");
+}
+
+export const STAGE_LABELS: Record<Stage, string> = {
+  GROUP_STAGE: "Group Stage",
+  LAST_32: "Round of 32",
+  LAST_16: "Round of 16",
+  QUARTER_FINALS: "Quarter-finals",
+  SEMI_FINALS: "Semi-finals",
+  THIRD_PLACE: "Third-place Play-off",
+  FINAL: "Final",
+};
+
+/** Canonical stage label for a match: group name (e.g. "Group B") for the group
+ *  stage, or the knockout-round label. Falls back to "Group Stage" when the
+ *  group letter is unknown. */
+export function stageLabel(m: Match): string {
+  return m.stage === "GROUP_STAGE" ? groupName(m.group) || "Group Stage" : STAGE_LABELS[m.stage];
+}
+
+export const KNOCKOUT_ORDER: Stage[] = [
+  "LAST_32",
+  "LAST_16",
+  "QUARTER_FINALS",
+  "SEMI_FINALS",
+  "THIRD_PLACE",
+  "FINAL",
+];
+
+/** Render a standings table for one group. */
+export function standingsTable(group: string | null, rows: StandingRow[]): string {
+  const header =
+    c.dim(
+      pad("#", 2) +
+        " " +
+        pad("Team", 18) +
+        pad("P", 4, "right") +
+        pad("W", 3, "right") +
+        pad("D", 3, "right") +
+        pad("L", 3, "right") +
+        pad("GF", 4, "right") +
+        pad("GA", 4, "right") +
+        pad("GD", 4, "right") +
+        pad("Pts", 5, "right"),
+    );
+  const body = rows
+    .map((r) => {
+      const qualifies = r.position <= 2;
+      const posMark = qualifies ? c.green(String(r.position)) : c.dim(String(r.position));
+      const name = qualifies ? c.bold(teamLabel(r.team)) : teamLabel(r.team);
+      return (
+        pad(posMark, 2) +
+        " " +
+        pad(name, 18) +
+        pad(String(r.playedGames), 4, "right") +
+        pad(String(r.won), 3, "right") +
+        pad(String(r.draw), 3, "right") +
+        pad(String(r.lost), 3, "right") +
+        pad(String(r.goalsFor), 4, "right") +
+        pad(String(r.goalsAgainst), 4, "right") +
+        pad(signed(r.goalDifference), 4, "right") +
+        pad(c.bold(String(r.points)), 5, "right")
+      );
+    })
+    .join("\n");
+  const title = c.bold(c.cyan(groupName(group)));
+  return `${title}\n${header}\n${body}`;
+}
+
+function signed(n: number): string {
+  return n > 0 ? `+${n}` : String(n);
+}
+
+export function heading(text: string): string {
+  const line = "─".repeat(Math.max(visibleLen(text), 8));
+  return `\n${c.bold(c.magenta(text))}\n${c.dim(line)}`;
+}
+
+export function relativeTime(iso: string): string {
+  const diff = new Date(iso).getTime() - Date.now();
+  const abs = Math.abs(diff);
+  const mins = Math.round(abs / 60000);
+  const hours = Math.floor(mins / 60);
+  const days = Math.floor(hours / 24);
+  let s: string;
+  if (days >= 1) s = `${days}d ${hours % 24}h`;
+  else if (hours >= 1) s = `${hours}h ${mins % 60}m`;
+  else s = `${mins}m`;
+  return diff >= 0 ? `in ${s}` : `${s} ago`;
+}
+
+export { visibleLen };

package/src/index.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+import { c } from "./ansi.ts";
+import { ApiError } from "./api.ts";
+import { fifa } from "./sports/fifa.ts";
+
+const VERSION = "0.1.0";
+
+// Sport namespaces. Add a new sport by writing src/sports/<sport>.ts with a
+// dispatcher `(args: string[]) => unknown` and registering it here.
+const SPORTS: Record<string, (args: string[]) => unknown | Promise<unknown>> = {
+  fifa,
+};
+
+function help() {
+  const b = c.bold;
+  console.log(`${b(c.cyan("⚽ sportsing"))} — sports in your terminal  ${c.dim("v" + VERSION)}
+
+${b("USAGE")}
+  sportsing <sport> <command> [options]
+
+${b("SPORTS")}
+  ${c.green("fifa")}               FIFA World Cup 2026 ${c.dim("— sportsing fifa help")}
+
+${b("NOTE")}
+  During the World Cup, the ${b("fifa")} prefix is optional —
+  ${c.dim("sportsing today")} is shorthand for ${c.dim("sportsing fifa today")}.
+
+${b("EXAMPLES")}
+  sportsing fifa today
+  sportsing fifa next --team USA
+  sportsing today              ${c.dim("(= sportsing fifa today)")}
+`);
+}
+
+async function dispatch(): Promise<void> {
+  const [, , first, ...rest] = process.argv;
+
+  if (!first || first === "help" || first === "--help" || first === "-h") return help();
+  if (first === "--version" || first === "-v") {
+    console.log("sportsing " + VERSION);
+    return;
+  }
+
+  // Explicit sport namespace: `sportsing fifa <command>`.
+  const sport = SPORTS[first];
+  if (sport) {
+    await sport(rest);
+    return;
+  }
+
+  // Back-compat: while FIFA is the only sport, a bare `sportsing <command>`
+  // runs as a FIFA command (`sportsing today` == `sportsing fifa today`).
+  // An unknown token surfaces as "Unknown fifa command". Delete this line when
+  // a second sport lands so bare commands require an explicit sport prefix.
+  await fifa([first, ...rest]);
+}
+
+async function main() {
+  try {
+    await dispatch();
+  } catch (e) {
+    if (e instanceof ApiError) {
+      console.error(c.red(`API error (${e.status}): ${e.message}`));
+    } else {
+      console.error(c.red("Error: " + (e instanceof Error ? e.message : String(e))));
+    }
+    process.exitCode = 1;
+  }
+}
+
+main();