Design — Working terminal refresh + past/upcoming scores

Date: 2026-07-08 Status: approved (pending spec review)

Context

The first-class surfaces of this project are the terminal TUI (tui/dashboard.py, Textual/Python, launched via the dashboard command → uv run) and the morning paper (morning-paper script → POST /api/edition → puppeteer renders /print to a PDF). The Next.js webapp at :4317 is effectively the backend: it serves /api/* (data) and /print (paper source). The interactive webapp UI is not a priority.

Two problems motivate this work:

1. TUI refresh doesn't work. fetch_sources() calls bare GET /api/sources, which returns cached snapshots only (currentState). The server supports ?fresh=1 (refresh stale sources) and ?force=1 (refresh all), but the TUI never sends them — so pressing r just re-reads the same cache. Root cause: missing query param.

2. No previous-day scores, and no live updates. lib/sources/modules/sports.ts fetches only today → +daysAhead (never yesterday). lib/edition-data.ts:70 already wants yesterday..today for the paper but the data was never fetched. The sports source also refreshes every 600s, so live scores never move in the TUI within a game.

Data source finding

The user's separate sportsball TUI (~/Developer/Home/sportsball, Go/Bubble Tea) keeps live scores fresh. Investigation: it pulls the same ESPN public API the dashboard already uses — https://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/scoreboard (internal/espn/client.go:19). There is no better data to sync to, and sportsball has no API or persisted score store (config.json holds only favorites) — nothing to sync from. So we borrow its techniques, staying independent:

• Flat ~15s poll while live (commands.go:62) — "live scores feel fresh without hammering ESPN"; one scoreboard call per league per tick is cheap.

• Per-league past/future windows (internal/model/league.go:46-51), tuned to each sport's cadence:

  League	ESPN path (sport/league)	back	fwd
  World Cup	soccer/fifa.world	7	7
  MLB	baseball/mlb	2	3
  NBA	basketball/nba	3	4
  WNBA	basketball/wnba	3	4
  NHL	hockey/nhl	3	4
  NFL	football/nfl	8	8

• Favorites live in ~/.config/sportsball/config.json as favorites: [{league, id, abbr, name}]. We reuse these so the user doesn't re-enter teams.

Decisions

• Scores window: per-league (sportsball catalog), superseding an earlier flat "yesterday-only". Better for weekly sports (NFL needs ~8 days back to show the last game).
• Layout: FINAL / TODAY / UPCOMING sections, grouped by league within each. Shared shape across TUI and paper.
• Paper shows FINAL + TODAY only (no UPCOMING).
• Live cadence: force-refresh sports only every 60s while a game is live; otherwise dormant (normal cadence). No overnight hammering.
• Favorites sync: once, on TUI open — not per fetch. Persisted to the sports source config in the DB, so the 6am paper LaunchAgent uses the last-synced favorites.

Changes

1. TUI refresh (tui/dashboard.py)

• fetch_sources(force=False): request /api/sources?force=1 on manual r, ?fresh=1 on the periodic timer. The server already does the upstream re-fetch behind those params.

2. Sports module + schema (lib/sources/modules/sports.ts, lib/schemas/sources/sports.ts)

• Add a league catalog map: ESPN sport/league path + back/forward days, mirrored from sportsball's league.go (table above).
• Fetch each configured league across now-back … now+forward (via the existing per-date collect()), replacing the flat daysAhead / proposed daysBack.
• Payload shape (league, status, state, home, away, homeScore, awayScore, startTime) is unchanged; only the date range widens. state already distinguishes pre/in/post.
• Config still supports explicit leagues (all games) + teams (favorite filters); windows come from the catalog keyed by league path.

3. Favorites sync on TUI open (tui/dashboard.py)

• In on_mount (after the server is confirmed up): read ~/.config/sportsball/config.json; map each favorite via a small league-key→ESPN-path dict (mlb→baseball/mlb, nba→basketball/nba, wnba→basketball/wnba, nhl→hockey/nhl, nfl→football/nfl, worldcup→soccer/fifa.world) into dashboard teams entries ({league: <espnPath>, team: <abbr or name>}), then PATCH /api/sources/{sportsId} once with the updated config.
• Skip silently if the file is absent or the server is unreachable. Leave leagues untouched.
• The per-league window catalog stays only in the TS module; the TUI mirrors just the 6-entry path map (small, stable).

4. Shared bucketing — FINAL / TODAY / UPCOMING

• state=="post" → FINAL (show score); state=="in" or (pre starting today) → TODAY (live games highlighted); pre starting after today → UPCOMING. Group by league within each section, chronological.

5. TUI render_sports + live poll (tui/dashboard.py)

• Replace the current live/today/upcoming buckets (which mislabel finals) with FINAL/TODAY/UPCOMING per §4.
• Track the sports source id and _sports_live (any game state=="in"). A 60s timer: when _sports_live, POST /api/sources/{id}/refresh (force-refresh sports only), then re-render just the Scores panel from the response. Dormant otherwise.

6. Paper (app/print/page.tsx)

• Replace the raw group-by-league dump with FINAL + TODAY sections (§4 bucketing), no UPCOMING. lib/edition-data.ts:70 already clips sports to startYesterday..endToday — leave as-is.

Out of scope

• Webapp SportsBody (components/cards/CardBodies.tsx) — untouched; the wider payload flows through harmlessly (yesterday finals land in its existing "Live/Final" bucket).
• No coupling to the sportsball binary; no export code added there.

Verification

• pnpm typecheck.
• Run dashboard, press r: snapshots update (not cache); during a live game, scores tick ~every 60s; FINAL shows yesterday's results, UPCOMING shows future games.
• Confirm favorites appeared: check the sports source config after opening the TUI.
• Run morning-paper (no --print) and eyeball the PDF's Scores section: FINAL + TODAY only.