sportsing 0.1.2 → 0.2.0

package/src/format.ts

@@ -1,5 +1,6 @@
 import { c, pad, visibleLen } from "./ansi.ts";
 import type { Match, StandingRow, Stage } from "./types.ts";
+import type { Game, GameCompetitor } from "./game.ts";
 
 export function teamLabel(t: { name: string | null; tla?: string | null }): string {
   return t.tla || t.name || "TBD";
@@ -177,4 +178,90 @@ export function relativeTime(iso: string): string {
   return diff >= 0 ? `in ${s}` : `${s} ago`;
 }
 
+// --- Sport-neutral Game lines (NBA/NHL) ---
+
+/** Season-phase tag: "PRE" for preseason, "POST" for postseason (incl. the
+ *  NBA play-in), "" for the regular season. Plain text, for tests/alignment. */
+export function phaseTag(g: Game): string {
+  return g.seasonType === "preseason" ? "PRE" : g.seasonType === "postseason" ? "POST" : "";
+}
+
+/** How a league names its periods. Leagues that set this get live/final
+ *  status rendered from `period` + `clock` in their own terms (hockey:
+ *  1st/2nd/3rd/OT/SO) instead of the source's status text. */
+export interface PeriodNaming {
+  /** Periods in regulation (NHL: 3). Later periods are overtime. */
+  regulation: number;
+  /** True if a regular-season/preseason tie after one OT goes to a shootout
+   *  (NHL). Postseason overtime never ends in one. */
+  shootout: boolean;
+}
+
+const ordinal = (n: number): string => {
+  const tens = n % 100;
+  const suffix = tens >= 11 && tens <= 13 ? "th" : ["th", "st", "nd", "rd"][n % 10] ?? "th";
+  return n + suffix;
+};
+
+/** Name of period `g.period` under `naming`: "1st".."3rd", then "OT" (playoff
+ *  multi-OT: "2OT", "3OT", …), or "SO" for a shootout. "" before the game. */
+export function periodLabel(g: Pick<Game, "period" | "seasonType">, naming: PeriodNaming): string {
+  const p = g.period;
+  if (p <= 0) return "";
+  if (p <= naming.regulation) return ordinal(p);
+  const ot = p - naming.regulation;
+  if (naming.shootout && g.seasonType !== "postseason" && ot > 1) return "SO";
+  return ot === 1 ? "OT" : `${ot}OT`;
+}
+
+/** Plain status text from period + clock: "12:34 - 2nd", "End of 2nd", "SO",
+ *  "Final", "Final/OT", "Final/SO". Only for live and finished games. A live
+ *  game with no clock at all falls back to the source's text — only an
+ *  explicit "0:00" means the period has ended. */
+export function periodStatus(g: Game, naming: PeriodNaming): string {
+  const label = periodLabel(g, naming);
+  if (g.state === "post") return g.period > naming.regulation ? `Final/${label}` : "Final";
+  if (!label) return g.detail;
+  if (label === "SO") return "SO";
+  if (!g.clock) return g.detail || label;
+  return g.clock !== "0:00" ? `${g.clock} - ${label}` : `End of ${label}`;
+}
+
+/** Status column: local start time before the game, a LIVE badge + the clock
+ *  text during it, the final text after it. Clock/final text comes from the
+ *  league's period naming when given, else the source's own status text. */
+function gameStatus(g: Game, naming?: PeriodNaming): string {
+  if (g.state === "pre") return c.cyan(fmtTimeOnly(g.date));
+  const text = naming ? periodStatus(g, naming) : g.detail;
+  if (g.state === "in") return c.bgGreen(c.bold(" LIVE ")) + (text ? c.green(" " + text) : "");
+  return c.dim(text || "Final");
+}
+
+/** Score as a number for comparison; NaN when not yet scored. */
+const scoreNum = (s: string) => (s === "" ? NaN : Number(s));
+
+function side(t: GameCompetitor, other: GameCompetitor, g: Game): string {
+  const label = t.abbreviation || t.name;
+  if (g.state === "pre") return pad(label, 5) + "    ";
+  const won = g.state === "post" && scoreNum(t.score) > scoreNum(other.score);
+  const text = pad(label, 5) + pad(t.score, 4, "right");
+  return won ? c.bold(c.white(text)) : text;
+}
+
+/** One game as an aligned line, US style (away @ home):
+ *  "UTAH  109  @  DEN    97   Final  PRE". `naming` renders the status in the
+ *  league's period terms (see `PeriodNaming`). */
+export function gameLine(g: Game, naming?: PeriodNaming): string {
+  const tag = phaseTag(g);
+  const tagStr = tag === "PRE" ? c.yellow(tag) : tag === "POST" ? c.magenta(tag) : "";
+  return (
+    side(g.away, g.home, g) +
+    c.dim("  @  ") +
+    side(g.home, g.away, g) +
+    "   " +
+    pad(gameStatus(g, naming), 12) +
+    (tagStr ? " " + tagStr : "")
+  ).trimEnd();
+}
+
 export { visibleLen };

package/src/game-events.ts

@@ -0,0 +1,239 @@
+// Per-sport live event diffing over sport-neutral `Game` snapshots (NBA, NHL).
+//
+// The World Cup path keeps its own football-data `Match` differ (events.ts);
+// this is the ESPN-backed sibling. Each sport gets a rule set, because what is
+// alert-worthy differs: every NHL goal matters, every NBA basket would be noise
+// (so NBA alerts on tip-off, lead changes, a close finish, and the final).
+//
+// Pure apart from the caller-owned `GameMemory`: the live tick holds the
+// previous snapshot plus one memory map per sport, and feeds successive polls
+// in here. Two NBA rules need more than two snapshots — a lead change bridged
+// by a tie (home leads → tied → away leads) and "close-late fires once per
+// game" — so they remember per-game facts in that map. Diffing a snapshot
+// against itself yields nothing, with or without memory.
+
+import type { Game } from "./game.ts";
+
+export type GameEventKind =
+  | "puck-drop"
+  | "tip-off"
+  | "goal"
+  | "period-end"
+  | "overtime"
+  | "shootout"
+  | "lead-change"
+  | "close-late"
+  | "final";
+
+export type Side = "home" | "away";
+
+export interface GameEvent {
+  kind: GameEventKind;
+  gameId: string;
+  /** Short fixture label, away @ home, e.g. "UTAH @ DEN". */
+  fixture: string;
+  home: string;
+  away: string;
+  /** Score at the moment of the event. */
+  score: { home: number; away: number };
+  /** Period the event belongs to — for `period-end`, the period that ended. */
+  period: number;
+  /** Source status text of the newer snapshot, e.g. "End of 1st", "Final/SO". */
+  detail: string;
+  /** `goal`: which side scored. */
+  scoringSide?: Side;
+  /** `lead-change`: which side now leads. */
+  leader?: Side;
+}
+
+/** Per-game facts a rule needs beyond the two snapshots being diffed. */
+export interface GameMemo {
+  /** NBA: the last side seen leading (ties don't clear it). */
+  leader?: Side;
+  /** NBA: close-late already fired (or was already true at baseline). */
+  closeLate?: boolean;
+}
+
+/** Caller-owned, keyed by game id; one map per sport. Entries are tiny and
+ *  are never pruned here — a game can drop out of one poll and come back. */
+export type GameMemory = Map<string, GameMemo>;
+
+/** What a rule emits; `diffGames` stamps on the shared game fields. */
+type Emit = Pick<GameEvent, "kind" | "period"> & Partial<Pick<GameEvent, "scoringSide" | "leader">>;
+
+/** One alert rule: the events for a single game moving `before` → `after`. */
+type Rule = (before: Game, after: Game, memo: GameMemo) => Emit[];
+
+// ── shared helpers ──────────────────────────────────────────────────────────
+
+/** Numeric score, treating "" (not started) or junk as 0. */
+const pts = (score: string): number => Number(score) || 0;
+
+function scoreOf(g: Game): { home: number; away: number } {
+  return { home: pts(g.home.score), away: pts(g.away.score) };
+}
+
+function leaderOf(g: Game): Side | undefined {
+  const s = scoreOf(g);
+  return s.home > s.away ? "home" : s.away > s.home ? "away" : undefined;
+}
+
+/** Seconds left on a game clock ("4:21", "0:00", NBA's sub-minute "45.3"),
+ *  or undefined when there is no parseable clock. */
+export function clockSeconds(clock: string): number | undefined {
+  const m = /^\s*(?:(\d+):)?(\d+(?:\.\d+)?)\s*$/.exec(clock);
+  if (!m) return undefined;
+  return Number(m[1] ?? 0) * 60 + Number(m[2]);
+}
+
+/** Live with the clock run out — between periods (or at the final buzzer,
+ *  before the source flips the game to "post"). */
+const atPeriodEnd = (g: Game): boolean => g.state === "in" && clockSeconds(g.clock) === 0;
+
+// Shared rules.
+
+const start =
+  (kind: "puck-drop" | "tip-off"): Rule =>
+  (b, a) =>
+    b.state === "pre" && a.state === "in" ? [{ kind, period: a.period }] : [];
+
+const final: Rule = (b, a) => (b.state === "in" && a.state === "post" ? [{ kind: "final", period: a.period }] : []);
+
+// ── NHL ─────────────────────────────────────────────────────────────────────
+
+const NHL_REGULATION_PERIODS = 3;
+
+/** A shootout is "period 5" outside the playoffs; playoff OT never ends in one. */
+const inShootout = (g: Game): boolean => g.seasonType !== "postseason" && g.period > NHL_REGULATION_PERIODS + 1;
+
+/**
+ * One goal event per side whose score rose (a multi-goal burst between polls
+ * collapses into one event with the resulting score). Skipped around a
+ * shootout: ESPN credits the shootout winner's +1 only when the game goes
+ * final, and that isn't a goal.
+ */
+const nhlGoals: Rule = (b, a) => {
+  if (inShootout(b) || inShootout(a)) return [];
+  const was = scoreOf(b);
+  const now = scoreOf(a);
+  const out: Emit[] = [];
+  if (now.home > was.home) out.push({ kind: "goal", period: a.period, scoringSide: "home" });
+  if (now.away > was.away) out.push({ kind: "goal", period: a.period, scoringSide: "away" });
+  return out;
+};
+
+/**
+ * End of a period: the clock hit 0:00 in a new snapshot, or the period number
+ * advanced without us ever seeing the 0:00 snapshot (a poll gap). The
+ * game-ending period is covered by `final`, and a shootout has no period end.
+ */
+const nhlPeriodEnd: Rule = (b, a) => {
+  if (b.state !== "in" || a.state !== "in") return [];
+  const out: Emit[] = [];
+  if (a.period > b.period && !atPeriodEnd(b) && !inShootout(b)) out.push({ kind: "period-end", period: b.period });
+  if (atPeriodEnd(a) && !inShootout(a) && !(atPeriodEnd(b) && b.period === a.period)) {
+    out.push({ kind: "period-end", period: a.period });
+  }
+  return out;
+};
+
+/** Entering overtime (each playoff OT period) or the shootout. */
+const nhlOvertime: Rule = (b, a) => {
+  if (b.state !== "in" || a.state !== "in" || a.period <= b.period || a.period <= NHL_REGULATION_PERIODS) return [];
+  return [{ kind: inShootout(a) ? "shootout" : "overtime", period: a.period }];
+};
+
+// ── NBA ─────────────────────────────────────────────────────────────────────
+
+const NBA_FOURTH = 4;
+const CLOSE_LATE_MARGIN = 5;
+const CLOSE_LATE_SECONDS = 5 * 60;
+
+/**
+ * The lead switched sides. Ties don't count as a change, but they don't reset
+ * the memory either, so home leads → tied → away leads (across polls) is one
+ * lead change. Only while live; the final covers a last-gasp swing.
+ */
+const nbaLeadChange: Rule = (b, a, memo) => {
+  const was = leaderOf(b);
+  const now = leaderOf(a);
+  memo.leader ??= was;
+  const changed = a.state === "in" && now !== undefined && now !== was && memo.leader !== undefined && now !== memo.leader;
+  if (now) memo.leader = now;
+  return changed ? [{ kind: "lead-change", period: a.period, leader: now }] : [];
+};
+
+/** Live, in the 4th or any OT, ≤ 5:00 left, margin ≤ 5. */
+function isCloseLate(g: Game): boolean {
+  if (g.state !== "in" || g.period < NBA_FOURTH) return false;
+  const left = clockSeconds(g.clock);
+  if (left === undefined || left > CLOSE_LATE_SECONDS) return false;
+  const s = scoreOf(g);
+  return Math.abs(s.home - s.away) <= CLOSE_LATE_MARGIN;
+}
+
+/**
+ * Close game late — once per game. If the earlier snapshot already qualified
+ * (we started watching mid-crunch), that's the baseline: remember it, no alert.
+ */
+const nbaCloseLate: Rule = (b, a, memo) => {
+  if (memo.closeLate) return [];
+  if (isCloseLate(b)) {
+    memo.closeLate = true;
+    return [];
+  }
+  if (!isCloseLate(a)) return [];
+  memo.closeLate = true;
+  return [{ kind: "close-late", period: a.period }];
+};
+
+// ── rule sets + differ ──────────────────────────────────────────────────────
+
+/** Alert rules per ESPN-backed sport, in emission order. */
+export const GAME_RULES = {
+  nhl: [start("puck-drop"), nhlGoals, nhlPeriodEnd, nhlOvertime, final],
+  nba: [start("tip-off"), nbaLeadChange, nbaCloseLate, final],
+} satisfies Record<string, Rule[]>;
+
+export type GameSport = keyof typeof GAME_RULES;
+
+/** True if `sport` has an alert rule set. */
+export function isGameSport(sport: string): sport is GameSport {
+  return Object.hasOwn(GAME_RULES, sport);
+}
+
+/**
+ * Diff two `Game` snapshots into events using `sport`'s rule set.
+ *
+ * A game must appear in both snapshots (keyed by id) to diff a transition;
+ * brand-new entries are skipped until there is a prior state. Narrowing to
+ * favourite teams is the caller's job (filter `cur` first). Pass the same
+ * `memory` map on every tick for a sport so once-per-game rules hold across
+ * polls; omitted, each call starts fresh.
+ */
+export function diffGames(prev: Game[], cur: Game[], sport: GameSport, memory: GameMemory = new Map()): GameEvent[] {
+  const rules: Rule[] = GAME_RULES[sport];
+  const prevById = new Map(prev.map((g) => [g.id, g]));
+  const events: GameEvent[] = [];
+
+  for (const g of cur) {
+    const before = prevById.get(g.id);
+    if (!before) continue;
+    let memo = memory.get(g.id);
+    if (!memo) memory.set(g.id, (memo = {}));
+
+    const base = {
+      gameId: g.id,
+      fixture: `${g.away.abbreviation} @ ${g.home.abbreviation}`,
+      home: g.home.abbreviation,
+      away: g.away.abbreviation,
+      score: scoreOf(g),
+      detail: g.detail,
+    };
+    for (const rule of rules) {
+      for (const e of rule(before, g, memo)) events.push({ ...base, ...e });
+    }
+  }
+
+  return events;
+}

package/src/game.ts

@@ -0,0 +1,51 @@
+// Sport-neutral game shape for the ESPN-backed leagues (NBA, NHL, …).
+//
+// `types.ts` is football-data.org's soccer shape (goals, groups, stages) and
+// stays the World Cup path's model. NBA/NHL commands consume `Game` instead:
+// periods + a clock, a season phase (preseason through postseason), and the
+// per-game broadcast list that drives "can I watch it". Source-specific
+// parsing lives with its source (ESPN → `toGame` in espn.ts); nothing here
+// knows about any API.
+
+/** "pre" (scheduled), "in" (live), "post" (finished). */
+export type GameState = "pre" | "in" | "post";
+
+export type SeasonPhase = "preseason" | "regular" | "postseason";
+
+/** Who a broadcast is aimed at: everywhere, or one team's home market. */
+export type BroadcastMarket = "national" | "home" | "away";
+
+export interface Broadcast {
+  /** Network / service name as listed, e.g. "Utah 16", "ESPN+", "NBA TV". */
+  name: string;
+  market: BroadcastMarket;
+}
+
+export interface GameCompetitor {
+  /** Source team id (ESPN: Jazz "26", Mammoth "129764"); "" when unknown. */
+  id: string;
+  /** Full name, e.g. "Utah Jazz". */
+  name: string;
+  abbreviation: string;
+  /** Score as displayed; "" before the game starts. */
+  score: string;
+}
+
+export interface Game {
+  id: string;
+  /** ISO start time. */
+  date: string;
+  /** e.g. "Utah Jazz at Denver Nuggets". */
+  name: string;
+  state: GameState;
+  /** Short status text from the source, e.g. "Final/OT", "10/6 - 9:00 PM EDT". */
+  detail: string;
+  /** Current (live) or last (final) period; 0 before the game starts. */
+  period: number;
+  /** Game clock while live (e.g. "4:21"); "" when not in progress. */
+  clock: string;
+  seasonType: SeasonPhase;
+  home: GameCompetitor;
+  away: GameCompetitor;
+  broadcasts: Broadcast[];
+}

package/src/index.ts

@@ -1,15 +1,19 @@
 #!/usr/bin/env bun
 import { c } from "./ansi.ts";
 import { ApiError } from "./api.ts";
-import { fifa } from "./sports/fifa.ts";
+import { SPORTS as REGISTRY, bare } from "./commands/cross.ts";
+import { subscriptions } from "./commands/subscriptions.ts";
+import pkg from "../package.json" with { type: "json" };
 
-const VERSION = "0.1.0";
+// Single source of truth: package.json (a hardcoded copy drifted to a stale
+// 0.1.0 while the package shipped 0.1.2). The JSON import is inlined by
+// `bun build --compile`, and npm always ships package.json.
+const VERSION: string = pkg.version;
 
-// 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,
-};
+// Sport namespaces. Add a new sport by writing src/sports/<sport>.ts and
+// registering it in SPORTS in src/commands/cross.ts (which also makes the bare
+// cross-sport commands include it).
+const SPORTS = Object.fromEntries(REGISTRY.map((s) => [s.key, s.run]));
 
 function help() {
   const b = c.bold;
@@ -17,18 +21,30 @@ function help() {
 
 ${b("USAGE")}
   sportsing <sport> <command> [options]
+  sportsing <today|next|me>          ${c.dim("your favorite teams, every sport")}
+  sportsing live --notify [--quiet]  ${c.dim("alerts for your teams, every sport")}
 
 ${b("SPORTS")}
   ${c.green("fifa")}               FIFA World Cup 2026 ${c.dim("— sportsing fifa help")}
+  ${c.green("nba")}                NBA, preseason through playoffs ${c.dim("— sportsing nba help")}
+  ${c.green("nhl")}                NHL, preseason through playoffs ${c.dim("— sportsing nhl 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("YOUR TEAMS")} ${c.dim("(favorites across every sport, each row tagged with its sport)")}
+  ${c.green("today")}              Your teams' games today ${c.dim("(--tomorrow, --yesterday, --offset N)")}
+  ${c.green("next")}               Each team's next game + countdown
+  ${c.green("me")}                 Dashboard: last result + next game per team
+  ${c.green("live --notify")}      OS alerts for every sport with a favorite ${c.dim("(--quiet: no log; run with &)")}
+  ${c.dim("Add favorites per sport: sportsing nba fav add UTAH")}
+
+${b("SETTINGS")}
+  ${c.green("subscriptions")}      What you can watch with + home market ${c.dim("— alias: subs")}
 
 ${b("EXAMPLES")}
   sportsing fifa today
   sportsing fifa next --team USA
-  sportsing today              ${c.dim("(= sportsing fifa today)")}
+  sportsing nba schedule --team UTAH
+  sportsing nhl next --team UTAH
+  sportsing today              ${c.dim("(your teams, every sport)")}
 `);
 }
 
@@ -48,11 +64,14 @@ async function dispatch(): Promise<void> {
     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]);
+  // Cross-sport settings (not tied to any one sport's namespace).
+  if (first === "subscriptions" || first === "subs") {
+    await subscriptions(rest);
+    return;
+  }
+
+  // Bare `today`/`next`/`me`/`live` run across every sport; anything else gets a hint.
+  await bare(first, rest);
 }
 
 async function main() {