sportsing 0.1.2 → 0.2.1

package/README.md

@@ -1,19 +1,41 @@
 # ⚽ sportsing
 
-Sports in your terminal — the FIFA World Cup 2026 schedule, favorites, live
-scores, **ambient fav-alerts**, browser streaming, highlights, stats, and AI
-analysis. Runs on [Bun](https://bun.sh); its one runtime dependency,
+Sports in your terminal — the FIFA World Cup 2026, the **NBA**, and the
+**NHL**: schedules, favorites across every sport, live scores, standings, playoff
+brackets, **where to watch**, **ambient fav-alerts**, browser streaming,
+highlights, stats, and AI analysis. Runs on [Bun](https://bun.sh); its one runtime dependency,
 [ui-leaf](https://www.npmjs.com/package/@openthink/ui-leaf), powers the
 browser-streaming window and is installed (with its native binary) automatically.
 
 ```
 sportsing fifa today
-sportsing fifa next --team USA
-sportsing today              # the `fifa` prefix is optional during the World Cup
+sportsing nba schedule --team UTAH
+sportsing nhl next --team UTAH
+sportsing today              # your favorite teams across every sport (fifa, nba, nhl)
 ```
 
+> **Upgrading from 0.1.x?** Bare commands other than `today` / `next` / `me` now
+> need a sport prefix (`sportsing serve` → `sportsing fifa serve`), and favorites
+> are now stored per sport. See **Upgrading to 0.2.0** below.
+
 ## Install
 
+From npm (needs [Bun](https://bun.sh) on your `PATH` — the CLI runs on it):
+
+```sh
+bun install -g sportsing     # or: npm install -g sportsing
+sportsing --version
+```
+
+To update later, run `sportsing upgrade`. It checks npm for the latest release
+and reinstalls it with whichever of npm or bun installed your copy.
+`sportsing upgrade --check` only compares your version with the latest and
+installs nothing. A source checkout, a compiled binary or an `npx`/`bunx`
+run isn't updated in place. For those, the command prints how to update
+instead.
+
+From source:
+
 ```sh
 bun install                 # deps: ui-leaf (+ its browser binary) and dev types
 bun run build               # compiles a standalone binary → dist/sportsing
@@ -39,7 +61,8 @@ scores or tables).
 
 ## Commands
 
-`sportsing fifa <command>` (or just `sportsing <command>` during the Cup):
+`sportsing fifa <command>` (bare `sportsing today|next|me` cover your favorites
+across every sport — see **Your teams, every sport** below):
 
 | Command | What it does |
 |---|---|
@@ -58,7 +81,121 @@ scores or tables).
 Run `sportsing fifa help` for the full list (`serve` and `ask` are the AI-bus
 commands; `ask` is low-level plumbing that `serve` wraps).
 
-## Watch
+## NBA
+
+`sportsing nba <command>` — the NBA via ESPN's free API (no key), preseason
+through playoffs. Times are local; preseason games are tagged `PRE`, postseason
+(incl. play-in) `POST`.
+
+| Command | What it does |
+|---|---|
+| `today [--tomorrow\|--yesterday\|--offset N]` | One day's games |
+| `next` | Next game + countdown |
+| `schedule` | A team's whole season by day (league-wide: next 7 days) |
+| `results` | Finished games, newest first (league-wide: last 7 days) |
+| `standings [--conference X] [--division X]` | Regular-season standings, favorites marked ★ |
+| `season [team]` | Your favorites' season: record, home/away splits, playoff race |
+| `bracket [--season YYYY]` | Playoff bracket (projected before the postseason) |
+| `fav [add\|rm\|list]` | Manage NBA favorites (`fav add UTAH`, `fav add Jazz`) |
+| `watch [team] [--wait] [--provider X] [--url L] [--smoke]` | Open the game where you can watch it — see **Where to watch** below |
+| `live [--notify [--quiet]]` | Auto-refreshing live board; `--notify` alerts for favorites — see **Live fav-alerts** below |
+| `analyze <team> [team]` | AI read of the live or latest game: shooting, boards, turnovers, leaders (answered by `serve`; `--prompt` prints it) |
+| `predict <team> [team]` | AI prediction for the next game from both teams' recent form |
+| `recap <team> [team]` | AI "here's what you missed": lead changes, runs, close-late baskets, quarter scores |
+
+`--team X` (abbreviation or name; NBA.com codes like `UTA` work too) picks one
+team for `today` / `next` / `schedule` / `results`; `--mine` limits them to your
+NBA favorites. NBA favorites are separate from FIFA ones.
+
+`today` / `next` / `schedule` show a **WATCH** column once you've set your
+subscriptions (see **Where to watch**). `sportsing nba watch` opens Jazz games on
+Fubo by default.
+
+`sportsing nba watch [team] --overlay` opens Fubo's NBA hub with a live-stats
+overlay (same gear / settings / spoiler-delay as the FIFA one) that follows the
+game you open, recognized from the page title's English team names. NBA panels:
+score & clock, FG% / 3P%, leaders (PTS / REB / AST), fouls, timeouts. On an NHL
+game page (`sportsing nhl watch --provider fubo --overlay`): score & clock,
+shots on goal, power plays, faceoff %, goalie saves. Both have **Get caught up**
+(a recap up to your delayed stream's moment, via `/loop sportsing serve`). Panel choices are saved per
+provider and sport (`overlayPanels["fubo:nba"]`). `--overlay --smoke` checks the
+overlay renders, then tears the window down.
+
+## NHL
+
+`sportsing nhl <command>` — the same commands as `nba`, for the NHL (ESPN, no
+key), preseason through playoffs, tagged `PRE` / `POST` the same way. Live and
+final status uses hockey periods: `12:34 - 2nd`, `End of 3rd`, `OT`, `SO`,
+`Final/OT`, `Final/SO`.
+
+`--team X` takes an abbreviation or name — `UTAH`, `UTA`, `Mammoth`, and
+NHL.com codes like `TBL` / `LAK` all work. NHL favorites (`fav add UTAH`) are
+separate from NBA and FIFA ones, so the Jazz and the Mammoth can both be `UTAH`.
+
+`standings`, `season`, `bracket`, `watch`, and `analyze` / `predict` / `recap`
+work exactly as for the NBA — the AI prompts speak hockey (goaltending, special
+teams, every goal and penalty). There's
+no default NHL streaming provider: `nhl watch` follows **Where to watch** — an
+over-the-air game prints its channel (e.g. Utah 16) and opens nothing.
+
+## Where to watch (NBA / NHL)
+
+Tell sportsing what you can watch with and where you live, once — it applies to
+every sport:
+
+```sh
+sportsing subscriptions set fubo nba-league-pass local-ota   # whichever you have (or `none`)
+sportsing subscriptions market utah                          # home market (default: utah)
+sportsing subscriptions                                      # show them (alias: subs)
+```
+
+From each game's broadcasts (ESPN), sportsing then works out how *you* can watch
+it:
+
+- **WATCH column** in `today` / `next` / `schedule`: the service (`Fubo`,
+  `NBA League Pass`) or over-the-air channel, `✗` if you can't watch it, `?` if it
+  can't tell. With no subscriptions set, a one-line hint replaces the column.
+- **`<sport> watch`** acts on the same answer: opens Fubo or League Pass, prints
+  the channel for an over-the-air-only game (nothing to open; exits 0), or says
+  why a game isn't watchable (exits 1). `--provider` / `--url` override it.
+- **League Pass** covers out-of-market NBA games only — blacked out when a
+  home-market team plays or the game has a national broadcast. National
+  exclusives you don't carry are flagged.
+
+## Your teams, every sport
+
+Bare `today`, `next`, and `me` (no sport prefix) aggregate your favorite teams
+across every sport, each row tagged with its sport:
+
+```sh
+sportsing nba fav add UTAH && sportsing nhl fav add UTAH
+sportsing today      # the Jazz and the Mammoth today (--tomorrow, --yesterday, --offset N)
+sportsing next       # each favorite's next game + countdown, soonest first
+sportsing me         # last result + next game per favorite team
+```
+
+Bare `live --notify` alerts across every sport too (see **Live fav-alerts**).
+Every other command needs a sport — a bare one (e.g. `sportsing standings`)
+prints the sports that have it and exits non-zero.
+
+Favorites are stored per sport as `<sport>:<team>` (`nba:UTAH`, `nhl:UTAH`,
+`fifa:USA`) in `~/.config/sportsing/config.json`; add and remove them with each
+sport's `fav` command.
+
+## Upgrading to 0.2.0
+
+- **Breaking — bare commands need a sport.** In 0.1.x every bare command ran as a
+  FIFA command (`sportsing serve` meant `sportsing fifa serve`). Now only `today`,
+  `next`, and `me` work bare (across every sport); everything else needs its
+  prefix: `sportsing fifa serve`, `sportsing fifa live --notify`,
+  `sportsing fifa watch USA`, `sportsing fifa fav add USA`, and so on. Update any
+  scripts, aliases, or launchd jobs that call a bare command.
+- **Favorites are scoped by sport.** Existing unprefixed favorites (`"USA"`) are
+  read as FIFA favorites (`fifa:USA`) — nothing is lost. The file is rewritten in
+  the prefixed form the next time you add or remove a favorite. Downgrading to
+  0.1.x after that would see `fifa:USA` as a team name, so don't mix versions.
+
+## Watch (FIFA)
 
 `sportsing fifa watch [team] [team]` opens the broadcast in your own browser
 (your real Chrome, via [ui-leaf](https://www.npmjs.com/package/@openthink/ui-leaf)):
@@ -104,6 +241,8 @@ Turn `live` into an ambient alerter that pings you when your favorite teams play
 sportsing fifa fav add USA                 # set up favorites first
 sportsing fifa live --notify               # live board + OS notifications
 sportsing fifa live --notify --quiet &     # headless: alerts only, backgroundable
+sportsing nba live --notify                # same for the NBA (and `nhl live`)
+sportsing live --notify --quiet &          # one alerter for every sport with a favorite
 ```
 
 Each refresh diffs the latest scores against the previous tick and raises an OS
@@ -115,6 +254,20 @@ full-time alerts exactly once:
 - **Goal** — the scorer and the resulting scoreline (with a sound).
 - **Full time** — the final scoreline.
 
+NBA and NHL alert on what matters per sport, not every basket:
+
+- **NHL** — puck drop, every goal (with a sound), end of each period, overtime /
+  shootout, final.
+- **NBA** — tip-off, lead changes, a close finish (≤ 5 points with ≤ 5:00 left in
+  the 4th or OT, once per game), final.
+- **Tip-off / puck drop** are click-to-watch, routed like `<sport> watch` (see
+  **Where to watch**): a game on Fubo or League Pass opens on click; an
+  over-the-air-only game names its channel instead (nothing to click into).
+
+Bare `sportsing live --notify` polls every sport you have a favorite in from one
+process; a sport that can't load (e.g. FIFA without an API key) is reported and
+the rest keep alerting. Without `--quiet` it logs each alert as a line.
+
 Flags:
 
 - **`--notify`** — fire the alerts. With no favorites set, it warns and runs the
@@ -126,7 +279,7 @@ Flags:
 
 ### Click-to-watch requires `terminal-notifier`
 
-Clickable kickoff notifications use
+Clickable kickoff / tip-off / puck-drop notifications use
 [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) (macOS):
 
 ```sh
@@ -136,7 +289,8 @@ brew install terminal-notifier
 Notifications **degrade gracefully** when it's absent: on macOS they fall back to
 `osascript` (plain banner, no click action); on Linux to `notify-send`; otherwise
 to a terminal bell. Nothing errors — you just don't get the one-click-to-watch
-behavior without `terminal-notifier`.
+behavior without `terminal-notifier`. A click opens a Terminal window running
+`watch` (Ctrl-C or close the stream window to stop).
 
 ## AI (analyze / predict / overlay "Ask Claude" + "Get caught up")
 
@@ -166,18 +320,19 @@ prints this recipe; `sportsing fifa` and the watch nag point at it.
 ### Low-level primitive — `serve`
 
 `sportsing fifa serve` is the bare answerer loop (it powers `analyze` / `predict`
-too). `agent-setup` supersedes the old manual two-step for the agent-driven flow,
+/ `recap` too — for every sport: the bus is shared, so one `fifa serve` answers
+NBA and NHL questions as well). `agent-setup` supersedes the old manual two-step for the agent-driven flow,
 but `serve` remains the primitive if you want to compose it yourself:
 
 ```sh
 sportsing fifa watch --wait    # (backgrounded) opens the game when it's live
-/loop sportsing serve          # answer-only loop — no watch supervision
+/loop sportsing fifa serve     # answer-only loop — no watch supervision
 ```
 
 > **Run the answerer in a minimal-tool session.** Whether via `agent-setup` or
 > `serve`, the loop reads **untrusted** text (viewer questions + raw API fields)
 > into a tool-capable Claude session. Give that session no MCP/file tools and only
-> the `sportsing ask --reply` Bash capability, so a prompt-injection in a question
+> the `sportsing fifa ask --reply` Bash capability, so a prompt-injection in a question
 > can't reach anything dangerous. `serve` prints this reminder each tick.
 
 ## Development

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sportsing",
-  "version": "0.1.2",
-  "description": "Sportsing — the FIFA World Cup 2026 in your terminal: schedule, favorites, live scores, ambient fav-alerts, browser streaming, highlights, stats, and AI analysis.",
+  "version": "0.2.1",
+  "description": "Sportsing — sports in your terminal: the FIFA World Cup 2026, the NBA, and the NHL. Schedules, favorites across every sport, live scores, standings, where-to-watch, browser streaming, highlights, stats, and AI analysis.",
   "type": "module",
   "bin": {
     "sportsing": "src/index.ts"
@@ -34,6 +34,10 @@
     "world-cup",
     "wc2026",
     "soccer",
+    "nba",
+    "nhl",
+    "basketball",
+    "hockey",
     "football",
     "cli",
     "terminal",

package/src/alerts.ts

@@ -0,0 +1,47 @@
+// Ambient favorite-team alerts, sport-neutral. Each sport turns successive
+// score polls into `Alert`s (FIFA: events.ts; NBA/NHL: league-alerts.ts); an
+// `Alerter` wraps that with its own fetch so bare `sportsing live --notify`
+// can poll every sport with a favorite from one process.
+
+import { notify, type NotifyOptions } from "./notify.ts";
+
+/** How often `live` refreshes and alerters poll. */
+export const LIVE_REFRESH_MS = 60_000;
+
+/** One OS notification to raise. */
+export interface Alert {
+  title: string;
+  body: string;
+  options: NotifyOptions;
+}
+
+/** One sport's favorite-team alerter. */
+export interface Alerter {
+  /** Sport label, e.g. "NBA". */
+  label: string;
+  /** The favorite teams it alerts for, for the startup line. */
+  teams: string[];
+  /** Fetch the latest scores and return the new alerts since the previous
+   *  poll. The first poll only sets the baseline (a game already under way
+   *  when you start raises no start alert). */
+  poll: () => Promise<Alert[]>;
+}
+
+/** Raise an alert as a desktop notification. */
+export function raise(a: Alert): void {
+  notify(a.title, a.body, a.options);
+}
+
+/**
+ * Poll every alerter once, concurrently. A sport whose poll fails is handed to
+ * `onError` and contributes nothing this round; the others' alerts still come
+ * back, in alerter order.
+ */
+export async function pollAlerters(alerters: Alerter[], onError: (a: Alerter, e: unknown) => void): Promise<Alert[]> {
+  const settled = await Promise.allSettled(alerters.map((a) => a.poll()));
+  return settled.flatMap((r, i) => {
+    if (r.status === "fulfilled") return r.value;
+    onError(alerters[i]!, r.reason);
+    return [];
+  });
+}

package/src/api.ts

@@ -131,7 +131,7 @@ export async function getOpenFootballMatches(): Promise<Match[]> {
     if (!res.ok)
       throw new ApiError(
         res.status,
-        "Could not fetch the offline fixture schedule — network unavailable. Run `sportsing setup` to add a free API key for live data.",
+        "Could not fetch the offline fixture schedule — network unavailable. Run `sportsing fifa setup` to add a free API key for live data.",
       );
     const data = (await res.json()) as any;
     const out: Match[] = [];

package/src/click-to-watch.ts

@@ -0,0 +1,39 @@
+// Click-to-watch for start-of-game notifications: the shell command a
+// notification runs when clicked (terminal-notifier `-execute`).
+//
+// `watch` is interactive — it blocks until its stream window is closed, and
+// refuses to run without a controlling TTY. terminal-notifier runs `-execute`
+// through /bin/sh with no TTY, so the click opens a Terminal window that runs
+// `watch` there (a TTY, and a Ctrl-C to stop it).
+
+/** POSIX single-quote a string so it's safe as one shell argument. */
+export function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * argv that re-runs this sportsing: the binary itself when compiled
+ * (`bun build --compile`; the entry lives in Bun's virtual /$bunfs), else the
+ * Bun runtime plus the entry script (the npm install runs src/index.ts).
+ */
+export function selfInvocation(main = Bun.main, execPath = process.execPath): string[] {
+  const compiled = main.startsWith("/$bunfs/") || main.includes("~BUN");
+  return compiled ? [execPath] : [execPath, main];
+}
+
+/** `<exe…> <sport> watch <team>`, shell-quoted. */
+export function watchCommand(exe: string[], sport: string, team: string): string {
+  return `${exe.map(shQuote).join(" ")} ${sport} watch ${shQuote(team)}`;
+}
+
+/** Escape a string for an AppleScript double-quoted literal. */
+function osaString(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** A shell command that runs `cmd` in a new macOS Terminal window and brings
+ *  Terminal to the front. */
+export function inTerminal(cmd: string): string {
+  const script = (line: string) => `-e ${shQuote(`tell application "Terminal" to ${line}`)}`;
+  return `osascript ${script(`do script ${osaString(cmd)}`)} ${script("activate")}`;
+}

package/src/commands/_lib.ts

@@ -43,7 +43,7 @@ export async function withFallback<T>(
       console.error(
         c.yellow(
           "No API key set — showing the offline schedule (no live scores/tables).\n" +
-            "Run `sportsing setup` for live data.",
+            "Run `sportsing fifa setup` for live data.",
         ) + "\n",
       );
       const matches = await getOpenFootballMatches();
@@ -70,19 +70,35 @@ export function getFlag(args: string[], flag: string): string | null {
 }
 
 /**
- * If `--mine` is present in args, narrow `matches` to games involving a favorite
- * team. Returns the literal `"no-favorites"` when `--mine` was asked for but no
- * favorites are set, so the caller can show a helpful hint. Without `--mine`,
- * returns the list unchanged.
+ * The favorites `--mine` should filter by for `sport`: null when `--mine` is
+ * absent, the literal `"no-favorites"` when it was asked for but that sport has
+ * none set (so the caller can show a hint), else that sport's favorite names.
+ */
+export async function mineFavorites(args: string[], sport: string): Promise<string[] | null | "no-favorites"> {
+  if (!args.includes("--mine")) return null;
+  const favs = await getFavorites(sport);
+  return favs.length === 0 ? "no-favorites" : favs;
+}
+
+/**
+ * If `--mine` is present in args, narrow football-data `matches` (the FIFA
+ * shape) to games involving a FIFA favorite. Returns `"no-favorites"` when
+ * `--mine` was asked for but none are set. Without `--mine`, returns the list
+ * unchanged. ESPN-league commands filter `Game`s by team id instead (league.ts).
  */
 export async function applyMine(matches: Match[], args: string[]): Promise<Match[] | "no-favorites"> {
-  if (!args.includes("--mine")) return matches;
-  const favs = (await getFavorites()).map((f) => f.toLowerCase());
-  if (favs.length === 0) return "no-favorites";
-  return matches.filter((m) => favs.some((n) => matchHasTeam(m, n)));
+  const favs = await mineFavorites(args, "fifa");
+  if (favs === null) return matches;
+  if (favs === "no-favorites") return favs;
+  const needles = favs.map((f) => f.toLowerCase());
+  return matches.filter((m) => needles.some((n) => matchHasTeam(m, n)));
 }
 
-/** Shared message for `--mine` with no favorites configured. */
-export function noFavoritesHint(): void {
-  console.log(c.dim("No favorite teams yet — add one with ") + c.bold("sportsing fifa fav add USA"));
+/** Example team for "add a favorite" hints, per sport. */
+export const EXAMPLE_TEAM: Record<string, string> = { fifa: "USA", nba: "UTAH", nhl: "UTAH" };
+
+/** Shared message for `--mine` with no favorites configured for `sport`. */
+export function noFavoritesHint(sport = "fifa"): void {
+  const example = EXAMPLE_TEAM[sport] ?? "<team>";
+  console.log(c.dim("No favorite teams yet — add one with ") + c.bold(`sportsing ${sport} fav add ${example}`));
 }

package/src/commands/analyze.ts

@@ -36,7 +36,7 @@ export async function analyze(args: string[]) {
   }
 
   process.stderr.write(c.dim("Posted to the ask bus — waiting for your Claude agent to answer…\n"));
-  process.stderr.write(c.dim("(keep one serving:  /loop sportsing serve)\n"));
+  process.stderr.write(c.dim("(keep one serving:  /loop sportsing fifa serve)\n"));
   const id = await postQuestion({
     source: "analyze",
     question: prompt,
@@ -47,7 +47,7 @@ export async function analyze(args: string[]) {
   const analysis = await waitForAnswer(id, 180_000);
   if (analysis === null) {
     console.error(c.yellow("No Claude agent answered within 3 minutes."));
-    console.error(c.dim("Start a serving agent in another Claude session, then retry:  /loop sportsing serve"));
+    console.error(c.dim("Start a serving agent in another Claude session, then retry:  /loop sportsing fifa serve"));
     console.error(c.dim("Or run with --prompt to get the prompt and analyze elsewhere."));
     process.exitCode = 1;
     return;

package/src/commands/ask.ts

@@ -26,7 +26,7 @@ export async function ask(args: string[]): Promise<void> {
 // self-contained PROMPT (not data): it blocks for the next pending question and
 // emits instructions telling the reading agent to answer it and run the exact
 // `ask --reply` command. Designed to be dropped into a Claude session as
-// `/loop sportsing serve` — each tick serves one question; the model IS the
+// `/loop sportsing fifa serve` — each tick serves one question; the model IS the
 // answerer, so no `claude -p` is ever spawned.
 export async function serve(args: string[]): Promise<void> {
   const waitSec = numFlag(args, "--wait") ?? 60;