sportsing 0.1.2 → 0.2.1

package/src/commands/cross.ts

@@ -0,0 +1,354 @@
+// Bare `sportsing today | next | me` — your favorite teams' games across every
+// registered sport, each row tagged with its sport — and bare
+// `sportsing live --notify`, one alerter polling every sport with a favorite. Any other bare command is
+// per-sport: it gets a hint naming the sports that have it, never a silent
+// fallback to one sport.
+//
+// SPORTS below is the one sport registry: src/index.ts builds its
+// `sportsing <sport> …` namespaces from it, so a new sport is aggregated here
+// as soon as it's routable.
+
+import { c } from "../ansi.ts";
+import { LIVE_REFRESH_MS, pollAlerters, raise, type Alerter } from "../alerts.ts";
+import { getMatches } from "../api.ts";
+import { getFavorites } from "../config.ts";
+import { getTeams } from "../espn.ts";
+import { fmtDate, gameLine, matchLine, relativeTime } from "../format.ts";
+import type { GameState } from "../game.ts";
+import { fifa, fifaHasCommand } from "../sports/fifa.ts";
+import { NBA, nba } from "../sports/nba.ts";
+import { NHL, nhl } from "../sports/nhl.ts";
+import type { Match } from "../types.ts";
+import { fifaAlerter } from "./live.ts";
+import { EXAMPLE_TEAM, addDays, localDateOf, matchHasTeam, withFallback, ymd } from "./_lib.ts";
+import {
+  favoriteIds,
+  gameHasTeam,
+  gamesOnDays,
+  leagueAlerter,
+  leagueHasCommand,
+  parseOffset,
+  teamSeason,
+  type LeagueConfig,
+} from "./league.ts";
+
+/** One game, sport-neutral: enough to sort, pick, and print it. */
+export interface Row {
+  id: string;
+  /** ISO start time. */
+  start: string;
+  state: GameState;
+  /** The sport's own aligned game line. */
+  line: string;
+}
+
+/** One favorite team and its games, ascending by start. */
+export interface TeamRows {
+  team: string;
+  rows: Row[];
+}
+
+export interface Sport {
+  /** CLI namespace and favorites key, e.g. "nba". */
+  key: string;
+  label: string;
+  icon: string;
+  /** `sportsing <key> …` dispatcher. */
+  run: (args: string[]) => unknown | Promise<unknown>;
+  /** True if `sportsing <key> <cmd>` exists. */
+  has: (cmd: string) => boolean;
+  /** Favorite teams' games on one local day; null when the sport has no favorites. */
+  favoritesOn: (day: Date) => Promise<Row[] | null>;
+  /** Each favorite team's schedule; null when the sport has no favorites. */
+  favoriteTeams: () => Promise<TeamRows[] | null>;
+  /** Favorite-team live alerter; null when the sport has no favorites. */
+  alerter: () => Promise<Alerter | null>;
+}
+
+// ── FIFA (football-data `Match`) ─────────────────────────────────────────────
+
+/** 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";
+}
+
+const matchRow = (m: Match): Row => ({ id: String(m.id), start: m.utcDate, state: matchState(m), line: matchLine(m) });
+
+const allMatches = () =>
+  withFallback(
+    async () => (await getMatches({})).matches,
+    (all) => all,
+  );
+
+const FIFA: Sport = {
+  key: "fifa",
+  label: "FIFA",
+  icon: "⚽",
+  run: fifa,
+  has: fifaHasCommand,
+  alerter: fifaAlerter,
+  async favoritesOn(day) {
+    const favs = await getFavorites("fifa");
+    if (favs.length === 0) return null;
+    // football-data filters by UTC date; fetch ±1 day and keep the local day.
+    const date = ymd(day);
+    const onDay = (all: Match[]) => all.filter((m) => localDateOf(m.utcDate) === date);
+    const matches = await withFallback(
+      async () => onDay((await getMatches({ dateFrom: ymd(addDays(day, -1)), dateTo: ymd(addDays(day, 1)) })).matches),
+      onDay,
+    );
+    const needles = favs.map((f) => f.toLowerCase());
+    return matches.filter((m) => needles.some((n) => matchHasTeam(m, n))).map(matchRow);
+  },
+  async favoriteTeams() {
+    const favs = await getFavorites("fifa");
+    if (favs.length === 0) return null;
+    const matches = (await allMatches()).map((m) => ({ m, row: matchRow(m) }));
+    return favs.map((team) => ({
+      team,
+      rows: matches
+        .filter(({ m }) => matchHasTeam(m, team.toLowerCase()))
+        .map(({ row }) => row)
+        .sort(byStart),
+    }));
+  },
+};
+
+// ── ESPN leagues (sport-neutral `Game`) ──────────────────────────────────────
+
+function league(cfg: LeagueConfig, run: Sport["run"]): Sport {
+  const favoriteTeamsOf = async () => {
+    const favs = await getFavorites(cfg.sport);
+    if (favs.length === 0) return null;
+    const teams = await getTeams(cfg.league);
+    return { teams, ids: favoriteIds(cfg, teams, favs) };
+  };
+  return {
+    key: cfg.sport,
+    label: cfg.label,
+    icon: cfg.icon,
+    run,
+    has: leagueHasCommand,
+    alerter: () => leagueAlerter(cfg),
+    async favoritesOn(day) {
+      const favs = await favoriteTeamsOf();
+      if (!favs) return null;
+      const games = await gamesOnDays(cfg, day, 1);
+      return games
+        .filter((g) => gameHasTeam(g, favs.ids))
+        .map((g) => ({ id: g.id, start: g.date, state: g.state, line: gameLine(g, cfg.periods) }));
+    },
+    async favoriteTeams() {
+      const favs = await favoriteTeamsOf();
+      if (!favs) return null;
+      return Promise.all(
+        [...favs.ids].map(async (id) => ({
+          team: favs.teams.find((t) => t.id === id)!.name,
+          rows: (await teamSeason(cfg, id)).map((g) => ({
+            id: g.id,
+            start: g.date,
+            state: g.state,
+            line: gameLine(g, cfg.periods),
+          })),
+        })),
+      );
+    },
+  };
+}
+
+/** Every registered sport, in display order. */
+export const SPORTS: Sport[] = [FIFA, league(NBA, nba), league(NHL, nhl)];
+
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+
+const byStart = (a: Row, b: Row) => Date.parse(a.start) - Date.parse(b.start);
+
+/** A sport tag + the game line, e.g. "🏀 NBA   UTAH  @  DEN …". */
+export function tagged(sport: Pick<Sport, "icon" | "label">, line: string): string {
+  return `${sport.icon} ${c.bold(sport.label.padEnd(4))}  ${line}`;
+}
+
+/** A team's most recent finished game and its next not-yet-started one. */
+export function lastAndNext(rows: Row[], now: number): { last: Row | null; next: Row | null } {
+  const sorted = [...rows].sort(byStart);
+  return {
+    last: sorted.filter((r) => r.state === "post").at(-1) ?? null,
+    next: sorted.find((r) => r.state === "pre" && Date.parse(r.start) >= now) ?? null,
+  };
+}
+
+/** Each team's next game, one copy per game (two favorites can meet), soonest first. */
+export function nextPerTeam(teams: TeamRows[], now: number): Row[] {
+  const byId = new Map<string, Row>();
+  for (const t of teams) {
+    const n = lastAndNext(t.rows, now).next;
+    if (n) byId.set(n.id, n);
+  }
+  return [...byId.values()].sort(byStart);
+}
+
+/**
+ * What to say for a bare command that can't run cross-sport: the per-sport
+ * forms of it (args kept), or "unknown" if no sport has it. `optionsGiven`
+ * marks a cross-sport command whose options only make sense per sport.
+ */
+export function bareHint(cmd: string, args: string[], sports: Pick<Sport, "key" | "has">[], optionsGiven = false): string[] {
+  const forms = sports.filter((s) => s.has(cmd)).map((s) => ["sportsing", s.key, cmd, ...args].join(" "));
+  if (forms.length === 0) return [`Unknown command: ${cmd}`, "Run `sportsing help` for usage."];
+  const why = optionsGiven ? `Bare \`${cmd}\` takes no options — add a sport:` : `\`${cmd}\` needs a sport:`;
+  return [why, "  " + forms.join(" · ")];
+}
+
+/** "Add a favorite" hint, one example per sport. */
+export function noFavoritesHint(sports: Pick<Sport, "key">[]): string[] {
+  const examples = sports.map((s) => `sportsing ${s.key} fav add ${EXAMPLE_TEAM[s.key] ?? "<team>"}`);
+  return [
+    c.dim("No favorite teams yet — add one with ") + c.bold("sportsing <sport> fav add <team>"),
+    c.dim("  e.g. " + examples.join(" · ")),
+  ];
+}
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run `load` for every sport. A sport that fails is reported and skipped (and
+ * the exit code set) so the others still print; sports with no favorites
+ * (null) are dropped. Null when there's nothing to show: no sport has
+ * favorites (the add-a-favorite hint is printed), or every sport with
+ * favorites failed.
+ */
+async function perSport<T>(sports: Sport[], load: (s: Sport) => Promise<T | null>): Promise<{ sport: Sport; data: T }[] | null> {
+  const settled = await Promise.allSettled(sports.map(load));
+  const out: { sport: Sport; data: T }[] = [];
+  let failed = false;
+  settled.forEach((r, i) => {
+    const sport = sports[i]!;
+    if (r.status === "rejected") {
+      failed = true;
+      console.error(c.yellow(`Couldn't load ${sport.label}: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`));
+      process.exitCode = 1;
+    } else if (r.value !== null) {
+      out.push({ sport, data: r.value });
+    }
+  });
+  if (out.length > 0) return out;
+  // Nothing to show: every sport failed (errors already printed) or none has favorites.
+  if (!failed) for (const l of noFavoritesHint(sports)) console.log(l);
+  return null;
+}
+
+/** `today [--tomorrow|--yesterday|--offset N]` — your teams' games on one local day. */
+export async function today(sports: Sport[], args: string[]): Promise<void> {
+  const offset = parseOffset(args);
+  const day = addDays(new Date(), offset);
+  const loaded = await perSport(sports, (s) => s.favoritesOn(day));
+  if (!loaded) return;
+  const rows = loaded
+    .flatMap(({ sport, data }) => data.map((row) => ({ sport, row })))
+    .sort((a, b) => byStart(a.row, b.row));
+
+  const label = offset === 0 ? "Today" : offset === 1 ? "Tomorrow" : offset === -1 ? "Yesterday" : ymd(day);
+  console.log(c.bold(c.cyan(`★ Your teams — ${label} (${ymd(day)})`)));
+  if (rows.length === 0) {
+    console.log(c.dim("\nNo games for your teams."));
+    return;
+  }
+  console.log();
+  for (const { sport, row } of rows) console.log("  " + tagged(sport, row.line));
+}
+
+/** `next` — each favorite team's next game, soonest first, with countdowns. */
+export async function next(sports: Sport[]): Promise<void> {
+  const loaded = await perSport(sports, (s) => s.favoriteTeams());
+  if (!loaded) return;
+  const now = Date.now();
+  const rows = loaded
+    .flatMap(({ sport, data }) => nextPerTeam(data, now).map((row) => ({ sport, row })))
+    .sort((a, b) => byStart(a.row, b.row));
+
+  console.log(c.bold(c.cyan("★ Your teams — Next up")));
+  if (rows.length === 0) {
+    console.log(c.dim("\nNo upcoming games for your teams."));
+    return;
+  }
+  for (const { sport, row } of rows) {
+    console.log("\n  " + tagged(sport, row.line));
+    console.log(`  ${c.bold(fmtDate(row.start))}  ${c.green("— starts " + relativeTime(row.start))}`);
+  }
+}
+
+/** `me` — every favorite team, every sport: last result and next game. */
+export async function me(sports: Sport[]): Promise<void> {
+  const loaded = await perSport(sports, (s) => s.favoriteTeams());
+  if (!loaded) return;
+  const now = Date.now();
+
+  console.log(c.bold(c.cyan("★ My teams")));
+  for (const { sport, data } of loaded) {
+    for (const t of data) {
+      const { last, next } = lastAndNext(t.rows, now);
+      console.log("\n" + `${sport.icon} ${c.bold(t.team)} ${c.dim(sport.label)}`);
+      if (last) console.log("  " + c.dim("last ") + last.line);
+      if (next) console.log("  " + c.dim("next ") + next.line + c.green("  " + relativeTime(next.start)));
+      if (!last && !next) console.log(c.dim("  no games found"));
+    }
+  }
+}
+
+/** Startup line for bare `live`, e.g. "NBA: Utah Jazz · NHL: Utah Mammoth". */
+export function alertersSummary(alerters: Pick<Alerter, "label" | "teams">[]): string {
+  return alerters.map((a) => `${a.label}: ${a.teams.join(", ")}`).join(" · ");
+}
+
+/**
+ * `live --notify [--quiet]` — favorite-team alerts for every sport with a
+ * favorite, from one process. A sport that can't start (e.g. FIFA without an
+ * API key) or whose poll fails is reported and the rest carry on. There's no
+ * cross-sport board: without --quiet each alert is also logged to stdout.
+ */
+export async function live(sports: Sport[], args: string[]): Promise<void> {
+  const unknown = args.filter((a) => a !== "--notify" && a !== "--quiet");
+  if (!args.includes("--notify") || unknown.length > 0) {
+    console.error(c.red("Bare `live` is the cross-sport alerter: sportsing live --notify [--quiet]"));
+    console.error(c.dim("For a live board add a sport: " + sports.filter((s) => s.has("live")).map((s) => `sportsing ${s.key} live`).join(" · ")));
+    process.exitCode = 1;
+    return;
+  }
+  const quiet = args.includes("--quiet");
+  const loaded = await perSport(sports, (s) => s.alerter());
+  if (!loaded) return;
+  const alerters = loaded.map(({ data }) => data);
+  console.error(c.dim(`Favorite-team alerts running (${alertersSummary(alerters)}) — Ctrl-C to stop.`));
+
+  const tick = async () => {
+    const alerts = await pollAlerters(alerters, (a, e) =>
+      console.error(c.yellow(`${a.label} alerts: ${e instanceof Error ? e.message : String(e)}`)),
+    );
+    for (const a of alerts) {
+      raise(a);
+      if (!quiet) console.log(`${c.dim(new Date().toLocaleTimeString())}  ${c.bold(a.title)}  ${a.body}`);
+    }
+  };
+  // The first poll only sets each sport's baseline.
+  await tick();
+  const interval = setInterval(() => void tick(), LIVE_REFRESH_MS);
+  process.on("SIGINT", () => {
+    clearInterval(interval);
+    process.exit(0);
+  });
+}
+
+/** Dispatch a bare `sportsing <cmd> …` (no sport prefix). */
+export async function bare(cmd: string, args: string[]): Promise<void> {
+  if (cmd === "today" || cmd === "t") return today(SPORTS, args);
+  if (cmd === "live") return live(SPORTS, args);
+  const run = cmd === "next" || cmd === "n" ? next : cmd === "me" ? me : null;
+  if (run && args.length === 0) return run(SPORTS);
+  // Options on `next`/`me` (e.g. `--team`) are per-sport: say so rather than ignore them.
+  const [first, ...rest] = bareHint(cmd, args, SPORTS, run !== null);
+  console.error(c.red(first!));
+  for (const l of rest) console.error(c.dim(l));
+  process.exitCode = 1;
+}

package/src/commands/fav.ts

@@ -1,47 +1,50 @@
 import { c } from "../ansi.ts";
 import { getFavorites, addFavorite, removeFavorite } from "../config.ts";
+import { EXAMPLE_TEAM } from "./_lib.ts";
 
-// `sportsing fifa fav [add|rm|list] [team]` — manage favorite teams.
-// Team names are free-text (e.g. "USA", "Brazil") matched case-insensitively
-// elsewhere; multi-word names work unquoted ("fav add South Korea").
-export async function fav(args: string[]): Promise<void> {
+// `sportsing <sport> fav [add|rm|list] [team]` — manage a sport's favorite teams.
+// Favorites are scoped per sport (stored `<sport>:<team>`), so `nba:UTAH` and
+// `nhl:UTAH` coexist. Team names are free-text (e.g. "USA", "Brazil") matched
+// case-insensitively elsewhere; multi-word names work unquoted ("fav add South Korea").
+export async function fav(args: string[], sport: string): Promise<void> {
   const [sub, ...rest] = args;
   const team = rest.join(" ").trim();
 
   if (!sub || sub === "list") {
-    printList(await getFavorites());
+    printList(await getFavorites(sport), sport);
     return;
   }
 
   if (sub === "add") {
-    if (!team) return usage("fav add <team>");
-    const { added, favorites } = await addFavorite(team);
+    if (!team) return usage(sport, "fav add <team>");
+    const { added, favorites } = await addFavorite(sport, team);
     console.log(added ? c.green(`★ Added ${team}.`) : c.yellow(`${team} is already a favorite.`));
-    printList(favorites);
+    printList(favorites, sport);
     return;
   }
 
   if (sub === "rm" || sub === "remove") {
-    if (!team) return usage("fav rm <team>");
-    const { removed, favorites } = await removeFavorite(team);
+    if (!team) return usage(sport, "fav rm <team>");
+    const { removed, favorites } = await removeFavorite(sport, team);
     console.log(removed ? c.green(`Removed ${team}.`) : c.yellow(`"${team}" wasn't in your favorites.`));
-    printList(favorites);
+    printList(favorites, sport);
     return;
   }
 
-  usage("fav <add|rm|list> [team]");
+  usage(sport, "fav <add|rm|list> [team]");
 }
 
-function printList(favorites: string[]): void {
+function printList(favorites: string[], sport: string): void {
   if (favorites.length === 0) {
-    console.log(c.dim("No favorite teams yet. Add one: ") + c.bold("sportsing fifa fav add USA"));
+    const example = EXAMPLE_TEAM[sport] ?? "<team>";
+    console.log(c.dim("No favorite teams yet. Add one: ") + c.bold(`sportsing ${sport} fav add ${example}`));
     return;
   }
   console.log(c.bold(c.cyan("★ Favorite teams")));
   for (const f of favorites) console.log("  " + f);
 }
 
-function usage(form: string): void {
-  console.error(c.red(`Usage: sportsing fifa ${form}`));
+function usage(sport: string, form: string): void {
+  console.error(c.red(`Usage: sportsing ${sport} ${form}`));
   process.exitCode = 1;
 }

package/src/commands/league-ai.ts

@@ -0,0 +1,201 @@
+// `sportsing <nba|nhl> analyze|predict|recap <team> [team] [--prompt]` — the
+// AI commands for the ESPN-backed leagues. Same model as the World Cup versions
+// (src/commands/analyze.ts, predict.ts, recap.ts): sportsing fetches + fences the
+// data and posts the prompt to the ask bus for an EXTERNAL Claude agent (a
+// `/loop sportsing fifa serve` session) — it never runs a model itself. --prompt
+// prints the assembled prompt instead of posting it.
+//
+// The prompts and the stats they carry are per-sport (src/league-ai.ts). Teams
+// and games come in through `LeagueGames` (built by league.ts), so every lookup
+// is by ESPN team id within one league.
+
+import { c } from "../ansi.ts";
+import { postQuestion, waitForAnswer, isServing, type AskSource } from "../ask-bus.ts";
+import type { EspnGameSummary, EspnTeam } from "../espn.ts";
+import type { Game } from "../game.ts";
+import { buildAnalyzePrompt, buildPredictPrompt, catchupInput, sportAiFor, teamForm, type SportAi } from "../league-ai.ts";
+import { buildRecapPrompt, hasNotableEvents, requestRecap } from "../recap.ts";
+import type { LeagueConfig } from "./league.ts";
+
+/** One league's data, as the AI commands need it. */
+export interface LeagueGames {
+  /** Resolve user input to a team in this league, or null. */
+  team(input: string): Promise<EspnTeam | null>;
+  /** Every game in one team's season (preseason through postseason), ascending. */
+  season(teamId: string): Promise<Game[]>;
+  /** Box score + play-by-play for one game, or null if ESPN has none. */
+  summary(gameId: string): Promise<EspnGameSummary | null>;
+}
+
+const ANSWER_TIMEOUT_MS = 180_000;
+
+// ── Pure selection (unit-tested) ─────────────────────────────────────────────
+
+/** The game to analyze or recap: a live one if any, else the most recent finished one. */
+export function pickPlayed(games: Game[]): Game | null {
+  const live = games.find((g) => g.state === "in");
+  if (live) return live;
+  return games.filter((g) => g.state === "post").sort((a, b) => Date.parse(b.date) - Date.parse(a.date))[0] ?? null;
+}
+
+/** The game to predict: the soonest one that hasn't started (never a finished one). */
+export function pickUpcoming(games: Game[], now: number): Game | null {
+  return (
+    games
+      .filter((g) => g.state === "pre" && Date.parse(g.date) >= now)
+      .sort((a, b) => Date.parse(a.date) - Date.parse(b.date))[0] ?? null
+  );
+}
+
+/** Only the games involving `teamId` (both sides checked; ids are league-scoped). */
+export function withTeam(games: Game[], teamId: string): Game[] {
+  return games.filter((g) => g.home.id === teamId || g.away.id === teamId);
+}
+
+// ── Shared plumbing ──────────────────────────────────────────────────────────
+
+/**
+ * Positional terms → one or two teams. The whole phrase is tried first (so
+ * "Utah Jazz" is one team), then each term on its own ("jazz nuggets").
+ * Throws a user-facing error for anything unresolvable.
+ */
+export async function resolveTerms(cfg: LeagueConfig, games: LeagueGames, terms: string[]): Promise<EspnTeam[]> {
+  const whole = await games.team(terms.join(" "));
+  if (whole) return [whole];
+  if (terms.length > 2) throw new Error(`Couldn't resolve "${terms.join(" ")}" to one or two ${cfg.label} teams.`);
+  const out: EspnTeam[] = [];
+  for (const t of terms) {
+    const team = await games.team(t);
+    if (!team) throw new Error(`Unknown ${cfg.label} team "${t}". Use an ESPN abbreviation or a team name.`);
+    out.push(team);
+  }
+  return out;
+}
+
+interface Setup {
+  ai: SportAi;
+  promptOnly: boolean;
+  teams: EspnTeam[];
+}
+
+/** Parse args and resolve teams; null (with a usage error printed) if there's nothing to do. */
+async function setup(cfg: LeagueConfig, games: LeagueGames, cmd: string, args: string[]): Promise<Setup | null> {
+  const ai = sportAiFor(cfg.league);
+  if (!ai) throw new Error(`${cmd} isn't available for ${cfg.label}.`);
+  const terms = args.filter((a) => !a.startsWith("--"));
+  if (terms.length === 0) {
+    console.error(c.red(`Usage: sportsing ${cfg.sport} ${cmd} <team> [team] [--prompt]`));
+    process.exitCode = 1;
+    return null;
+  }
+  return { ai, promptOnly: args.includes("--prompt"), teams: await resolveTerms(cfg, games, terms) };
+}
+
+/** The first team's season, narrowed to games against the second team if given. */
+async function candidateGames(games: LeagueGames, teams: EspnTeam[]): Promise<Game[]> {
+  const season = await games.season(teams[0]!.id);
+  return teams[1] ? withTeam(season, teams[1].id) : season;
+}
+
+const who = (teams: EspnTeam[]) => teams.map((t) => t.name).join(" vs ");
+
+/** Post a prompt to the ask bus and print the answer (or the no-agent hint). */
+async function ask(source: AskSource, prompt: string, context: string, hint: string, heading: string): Promise<void> {
+  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 fifa serve — it answers every sport)\n"));
+  const id = await postQuestion({ source, question: prompt, context, hint, maxChars: null });
+  const answer = await waitForAnswer(id, ANSWER_TIMEOUT_MS);
+  if (answer === 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 fifa serve  (it answers every sport)"));
+    console.error(c.dim("Or run with --prompt to get the prompt and use it elsewhere."));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(heading + "\n");
+  console.log(answer);
+}
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+
+/** `analyze <team> [team] [--prompt]` — a read of the live or latest finished game. */
+export async function leagueAnalyze(cfg: LeagueConfig, games: LeagueGames, args: string[]): Promise<void> {
+  const s = await setup(cfg, games, "analyze", args);
+  if (!s) return;
+  const g = pickPlayed(await candidateGames(games, s.teams));
+  if (!g) {
+    console.log(c.dim(`No played ${cfg.label} game found for ${who(s.teams)}. Analysis needs a game that has started.`));
+    return;
+  }
+  const summary = await games.summary(g.id);
+  if (!summary || summary.home.stats.length === 0 || summary.away.stats.length === 0) {
+    console.log(c.dim(`No team stats for ${g.name} yet — nothing to analyze.`));
+    return;
+  }
+  const prompt = buildAnalyzePrompt(s.ai, g, summary);
+  if (s.promptOnly) return void console.log(prompt);
+  await ask(
+    "analyze",
+    prompt,
+    g.name,
+    "Follow the format requested in the prompt (a 4–6 sentence read, plain prose).",
+    c.bold(c.cyan(`${cfg.icon} ${g.name} — analysis`)) + "  " + c.dim(summary.detail),
+  );
+}
+
+/** `predict <team> [team] [--prompt]` — the next game's likely outcome from both teams' form. */
+export async function leaguePredict(cfg: LeagueConfig, games: LeagueGames, args: string[]): Promise<void> {
+  const s = await setup(cfg, games, "predict", args);
+  if (!s) return;
+  const first = await games.season(s.teams[0]!.id);
+  const pool = s.teams[1] ? withTeam(first, s.teams[1].id) : first;
+  const g = pickUpcoming(pool, Date.now());
+  if (!g) {
+    console.log(c.dim(`No upcoming ${cfg.label} game found for ${who(s.teams)}.`));
+    return;
+  }
+  // Each side's form comes from its own season (the first team's is already in hand).
+  const seasonOf = (id: string) => (id === s.teams[0]!.id ? Promise.resolve(first) : games.season(id));
+  const [homeSeason, awaySeason] = await Promise.all([seasonOf(g.home.id), seasonOf(g.away.id)]);
+  const prompt = buildPredictPrompt(s.ai, g, teamForm(homeSeason, g.home.id), teamForm(awaySeason, g.away.id));
+  if (s.promptOnly) return void console.log(prompt);
+  await ask(
+    "predict",
+    prompt,
+    g.name,
+    "Follow the format requested in the prompt (scoreline, win probabilities, 2–3 sentences).",
+    c.bold(c.cyan(`${cfg.icon} ${g.name} — prediction`)),
+  );
+}
+
+/** `recap <team> [team] [--prompt]` — "here's what you missed" for the live or latest game. */
+export async function leagueRecap(cfg: LeagueConfig, games: LeagueGames, args: string[]): Promise<void> {
+  const s = await setup(cfg, games, "recap", args);
+  if (!s) return;
+  const g = pickPlayed(await candidateGames(games, s.teams));
+  if (!g) {
+    console.log(c.dim(`No ${cfg.label} game in progress or played for ${who(s.teams)} — nothing to recap.`));
+    return;
+  }
+  const summary = await games.summary(g.id);
+  if (!summary) {
+    console.log(c.dim(`No play-by-play for ${g.name} yet — nothing to recap.`));
+    return;
+  }
+  const input = catchupInput(s.ai, g, summary);
+  if (s.promptOnly) return void console.log(buildRecapPrompt(input));
+
+  if (hasNotableEvents(input.events) && (await isServing())) {
+    process.stderr.write(c.dim("Posted to the ask bus — waiting for your Claude agent to answer…\n"));
+  }
+  const res = await requestRecap(input);
+  if (res.ok) {
+    console.log(c.bold(c.cyan(`${cfg.icon} ${input.fixture} — catch up`)) + "  " + c.dim(`${input.scoreline} · ${input.detail}`) + "\n");
+    console.log(res.recap);
+    return;
+  }
+  if (res.reason === "empty") return void console.log(c.dim(res.message));
+  console.error(c.yellow(res.message));
+  console.error(c.dim("Or run with --prompt to get the prompt and recap elsewhere."));
+  process.exitCode = 1;
+}