soccer-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpunkySarb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# ⚽ soccer-cli
+
+Live football scores, **ball-by-ball commentary**, and a **live ASCII pitch** — right in your terminal. Built for the 2026 World Cup, works for every major league. **No API key required.**
+
+```
+⚽ FIFA WORLD CUP 2026                          ● 1 LIVE · ⟳15s
+  MATCHES
+  ───────────────────────────────────────────────────────────
+  ▸ 🇲🇽 Mexico        2-1   South Africa 🇿🇦     ● 67'
+    🇰🇷 South Korea   0-0   Czechia 🇨🇿          31'
+
+  🇲🇽 Mexico  2 : 1  South Africa 🇿🇦    ● 67'
+  58% Possession 42%   ·   12 Shots 7   ·   5 On target 3
+  ╭────────────────────────────────────────────────────────╮
+  │ ·····┆    ★             ┆                  ┆····· │
+  │▐  ★  ┆   ●          (   •   )               ┆     ▌│
+  │ ·····┆                   ┆                  ┆····· │
+  ╰────────────────────────────────────────────────────────╯
+   ● Mexico →    ← South Africa ●    67' ★ GOAL
+```
+
+## Install
+
+```bash
+npm install -g soccer-cli
+soccer
+```
+
+…or run it without installing:
+
+```bash
+npx soccer-cli
+```
+
+## Usage
+
+```bash
+soccer                      # FIFA World Cup (default)
+soccer --league eng.1       # Premier League
+soccer --date 20260611      # a specific day's fixtures
+soccer --once               # print one snapshot and exit (great for piping)
+soccer --help
+```
+
+### Keys
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` (or `j` / `k`) | Move between matches |
+| `p` | Toggle the live pitch |
+| `r` | Force refresh |
+| `q` / `Esc` | Quit |
+
+### Leagues
+
+Any ESPN soccer slug works — a few common ones:
+
+`fifa.world` (World Cup) · `eng.1` (Premier League) · `esp.1` (La Liga) · `ger.1` (Bundesliga) · `ita.1` (Serie A) · `fra.1` (Ligue 1) · `uefa.champions` · `usa.1` (MLS) · `bra.1` (Brasileirão)
+
+## What you get
+
+- **Live scores** that auto-refresh
+- **Ball-by-ball commentary** in a clean, word-wrapped table
+- **A live pitch** plotting where the action is — goals (★), the latest play (●), and a fading trail of recent events
+- **Match stats** — possession, shots, on-target, corners, fouls
+- **Country flags** for every nation
+
+## Data
+
+Powered by ESPN's public (unofficial) feed. Not affiliated with ESPN or FIFA. Endpoints are undocumented and may change without notice.
+
+## License
+
+MIT © [SpunkySarb](https://github.com/SpunkySarb)

package/dist/index.js

@@ -0,0 +1,802 @@
+#!/usr/bin/env node
+
+// bin/index.ts
+import process2 from "process";
+
+// src/app.ts
+import logUpdate from "log-update";
+import readline from "readline";
+import process from "process";
+
+// src/flags.ts
+import { createRequire } from "module";
+import countries from "i18n-iso-countries";
+var require2 = createRequire(import.meta.url);
+try {
+  countries.registerLocale(require2("i18n-iso-countries/langs/en.json"));
+} catch {
+}
+var WHITE = "\u{1F3F3}\uFE0F";
+var FIFA_TO_ISO2 = {
+  // Hosts / CONCACAF
+  USA: "US",
+  MEX: "MX",
+  CAN: "CA",
+  CRC: "CR",
+  PAN: "PA",
+  HON: "HN",
+  JAM: "JM",
+  SLV: "SV",
+  GUA: "GT",
+  HAI: "HT",
+  TRI: "TT",
+  CUB: "CU",
+  CUW: "CW",
+  SUR: "SR",
+  // CONMEBOL
+  BRA: "BR",
+  ARG: "AR",
+  URU: "UY",
+  COL: "CO",
+  ECU: "EC",
+  PAR: "PY",
+  CHI: "CL",
+  PER: "PE",
+  BOL: "BO",
+  VEN: "VE",
+  // UEFA
+  FRA: "FR",
+  GER: "DE",
+  ESP: "ES",
+  POR: "PT",
+  NED: "NL",
+  ITA: "IT",
+  BEL: "BE",
+  CRO: "HR",
+  SUI: "CH",
+  DEN: "DK",
+  POL: "PL",
+  SRB: "RS",
+  AUT: "AT",
+  CZE: "CZ",
+  SWE: "SE",
+  NOR: "NO",
+  UKR: "UA",
+  TUR: "TR",
+  GRE: "GR",
+  HUN: "HU",
+  ROU: "RO",
+  RUS: "RU",
+  SVK: "SK",
+  SVN: "SI",
+  FIN: "FI",
+  ISL: "IS",
+  ALB: "AL",
+  BIH: "BA",
+  BUL: "BG",
+  MKD: "MK",
+  GEO: "GE",
+  IRL: "IE",
+  LUX: "LU",
+  MNE: "ME",
+  KVX: "XK",
+  // CAF
+  RSA: "ZA",
+  MAR: "MA",
+  SEN: "SN",
+  NGA: "NG",
+  EGY: "EG",
+  CMR: "CM",
+  GHA: "GH",
+  ALG: "DZ",
+  TUN: "TN",
+  CIV: "CI",
+  MLI: "ML",
+  BFA: "BF",
+  COD: "CD",
+  ANG: "AO",
+  CPV: "CV",
+  GUI: "GN",
+  GAB: "GA",
+  ZAM: "ZM",
+  KEN: "KE",
+  UGA: "UG",
+  NAM: "NA",
+  MTN: "MR",
+  EQG: "GQ",
+  BEN: "BJ",
+  MOZ: "MZ",
+  // AFC
+  JPN: "JP",
+  KOR: "KR",
+  KSA: "SA",
+  IRN: "IR",
+  AUS: "AU",
+  QAT: "QA",
+  IRQ: "IQ",
+  UAE: "AE",
+  UZB: "UZ",
+  JOR: "JO",
+  CHN: "CN",
+  OMA: "OM",
+  BHR: "BH",
+  SYR: "SY",
+  PRK: "KP",
+  THA: "TH",
+  VIE: "VN",
+  IDN: "ID",
+  IND: "IN",
+  LBN: "LB",
+  KGZ: "KG",
+  // OFC
+  NZL: "NZ",
+  NCL: "NC",
+  FIJ: "FJ",
+  TAH: "PF"
+};
+var SPECIAL = {
+  ENG: "\u{1F3F4}\u{E0067}\u{E0062}\u{E0065}\u{E006E}\u{E0067}\u{E007F}",
+  // England
+  SCO: "\u{1F3F4}\u{E0067}\u{E0062}\u{E0073}\u{E0063}\u{E0074}\u{E007F}",
+  // Scotland
+  WAL: "\u{1F3F4}\u{E0067}\u{E0062}\u{E0077}\u{E006C}\u{E0073}\u{E007F}"
+  // Wales
+};
+function iso2ToFlag(iso2) {
+  const up = iso2.toUpperCase();
+  if (up.length !== 2) return "";
+  const base = 127462;
+  return String.fromCodePoint(base + (up.charCodeAt(0) - 65)) + String.fromCodePoint(base + (up.charCodeAt(1) - 65));
+}
+function flagFor(code, name) {
+  const cc = code?.toUpperCase();
+  if (cc && SPECIAL[cc]) return SPECIAL[cc];
+  if (cc && FIFA_TO_ISO2[cc]) return iso2ToFlag(FIFA_TO_ISO2[cc]);
+  if (name) {
+    const a2 = countries.getAlpha2Code(name, "en");
+    if (a2) return iso2ToFlag(a2);
+  }
+  return WHITE;
+}
+
+// src/espn.ts
+var BASE = "https://site.api.espn.com/apis/site/v2/sports/soccer";
+var HEADERS = { "User-Agent": "worldcup-cli", Accept: "application/json" };
+var EspnError = class extends Error {
+};
+async function getJson(url, signal) {
+  let res;
+  try {
+    res = await fetch(url, { headers: HEADERS, signal });
+  } catch (e) {
+    if (e?.name === "AbortError") throw e;
+    throw new EspnError(`Network error: ${e?.message ?? e}`);
+  }
+  if (!res.ok) throw new EspnError(`ESPN ${res.status} ${res.statusText}`);
+  return res.json();
+}
+function num(s) {
+  if (s === null || s === void 0 || s === "") return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+function toState(s) {
+  return s === "in" ? "in" : s === "post" ? "post" : "pre";
+}
+var STATE_ORDER = { in: 0, pre: 1, post: 2 };
+function parseSide(c2) {
+  const t = c2?.team ?? {};
+  const abbr = t.abbreviation ?? t.shortDisplayName ?? "???";
+  return {
+    id: String(t.id ?? ""),
+    abbr,
+    name: t.displayName ?? t.name ?? abbr,
+    shortName: t.shortDisplayName ?? t.name ?? abbr,
+    score: num(c2?.score),
+    homeAway: c2?.homeAway === "away" ? "away" : "home",
+    flag: flagFor(abbr, t.displayName ?? t.name)
+  };
+}
+function parseMatch(e) {
+  const comp = e.competitions?.[0] ?? {};
+  const comps = comp.competitors ?? [];
+  const home = parseSide(comps.find((c2) => c2.homeAway === "home") ?? comps[0] ?? {});
+  const away = parseSide(comps.find((c2) => c2.homeAway === "away") ?? comps[1] ?? {});
+  const st = e.status?.type ?? {};
+  return {
+    id: String(e.id),
+    date: e.date ?? "",
+    state: toState(st.state),
+    clock: e.status?.displayClock ?? "",
+    shortDetail: st.shortDetail ?? st.description ?? "",
+    detail: st.detail ?? "",
+    completed: !!st.completed,
+    home,
+    away
+  };
+}
+async function fetchScoreboard(league2, dateYYYYMMDD, signal) {
+  const q = dateYYYYMMDD ? `?dates=${dateYYYYMMDD}` : "";
+  const data = await getJson(`${BASE}/${league2}/scoreboard${q}`, signal);
+  const matches = (data.events ?? []).map(parseMatch);
+  matches.sort((a, b) => {
+    const s = STATE_ORDER[a.state] - STATE_ORDER[b.state];
+    if (s !== 0) return s;
+    return (a.date || "").localeCompare(b.date || "");
+  });
+  return matches;
+}
+function classifyEvent(typeText, scoringPlay) {
+  const t = typeText.toLowerCase();
+  if (t.includes("own goal")) return "own-goal";
+  if (t.includes("penalty") && /miss|saved|no goal|off target/.test(t)) return "penalty-miss";
+  if (t.includes("penalty") && (scoringPlay || t.includes("scored") || t.includes("goal"))) return "penalty-goal";
+  if (t.includes("goal") || scoringPlay) return "goal";
+  if (t.includes("yellow") && t.includes("red")) return "yellow-red";
+  if (t.includes("red")) return "red";
+  if (t.includes("yellow")) return "yellow";
+  if (t.includes("substitution")) return "sub";
+  if (t.includes("var")) return "var";
+  return "other";
+}
+var WANTED_STATS = [
+  { name: "possessionPct", label: "Possession" },
+  { name: "totalShots", label: "Shots" },
+  { name: "shotsOnTarget", label: "On target" },
+  { name: "wonCorners", label: "Corners" },
+  { name: "foulsCommitted", label: "Fouls" },
+  { name: "saves", label: "Saves" }
+];
+function fmtStat(name, v) {
+  if (v === void 0 || v === null) return "-";
+  if (name === "possessionPct") return `${v}%`;
+  return String(v);
+}
+function isGoalText(text) {
+  return /goal!/i.test(text) && !/disallowed|no goal|chalked off|ruled out/i.test(text);
+}
+async function fetchSummary(league2, eventId, signal) {
+  const data = await getJson(`${BASE}/${league2}/summary?event=${eventId}`, signal);
+  const hcomp = data.header?.competitions?.[0] ?? {};
+  const hcomps = hcomp.competitors ?? [];
+  const home = parseSide(hcomps.find((c2) => c2.homeAway === "home") ?? hcomps[0] ?? {});
+  const away = parseSide(hcomps.find((c2) => c2.homeAway === "away") ?? hcomps[1] ?? {});
+  const st = hcomp.status?.type ?? {};
+  const commentary = (data.commentary ?? []).map((c2) => {
+    const play = c2.play ?? {};
+    const px = play.fieldPositionX;
+    const py = play.fieldPositionY;
+    const hasPos = typeof px === "number" && typeof py === "number" && !(px === 0 && py === 0);
+    return {
+      sequence: Number(c2.sequence ?? 0),
+      time: c2.time?.displayValue ?? "",
+      text: c2.text ?? "",
+      isGoal: isGoalText(c2.text ?? ""),
+      x: hasPos ? px : void 0,
+      y: hasPos ? py : void 0,
+      teamId: play.team?.id ? String(play.team.id) : void 0,
+      playType: play.type?.text
+    };
+  }).sort((a, b) => b.sequence - a.sequence);
+  const keyEvents = (data.keyEvents ?? []).map((k) => {
+    const typeText = k.type?.text ?? "";
+    return {
+      id: String(k.id ?? ""),
+      kind: classifyEvent(typeText, !!k.scoringPlay),
+      typeText,
+      clock: k.clock?.displayValue ?? "",
+      teamId: k.team?.id ? String(k.team.id) : void 0,
+      team: k.team?.displayName,
+      player: k.participants?.[0]?.athlete?.displayName,
+      text: k.text ?? "",
+      scoringPlay: !!k.scoringPlay
+    };
+  });
+  const teams = data.boxscore?.teams ?? [];
+  const statsOf = (side, ha) => {
+    const byId = teams.find((t) => String(t.team?.id ?? "") === side.id);
+    if (byId) return byId.statistics ?? [];
+    const byHa = teams.find((t) => t.homeAway === ha);
+    return byHa?.statistics ?? [];
+  };
+  const homeStats = statsOf(home, "home");
+  const awayStats = statsOf(away, "away");
+  const val = (arr, name) => arr.find((s) => s.name === name)?.displayValue;
+  const stats = [];
+  for (const w of WANTED_STATS) {
+    const h = val(homeStats, w.name);
+    const a = val(awayStats, w.name);
+    if (h === void 0 && a === void 0) continue;
+    stats.push({ label: w.label, home: fmtStat(w.name, h), away: fmtStat(w.name, a) });
+  }
+  return {
+    id: String(eventId),
+    state: toState(st.state),
+    clock: hcomp.status?.displayClock ?? "",
+    shortDetail: st.shortDetail ?? "",
+    detail: st.detail ?? "",
+    venue: data.gameInfo?.venue?.fullName,
+    home,
+    away,
+    commentary,
+    keyEvents,
+    stats
+  };
+}
+
+// src/render.ts
+import Table from "cli-table3";
+import pc3 from "picocolors";
+import stringWidth2 from "string-width";
+
+// src/theme.ts
+import pc from "picocolors";
+var SYM = {
+  live: "\u25CF",
+  goal: "\u26BD",
+  yellow: "\u{1F7E8}",
+  // 🟨
+  red: "\u{1F7E5}",
+  // 🟥
+  sub: "\u{1F501}",
+  // 🔁
+  var: "\u{1F4FA}",
+  // 📺
+  dot: "\u2022",
+  refresh: "\u27F3",
+  ball: "\u26BD",
+  sel: "\u25B8"
+};
+var c = {
+  title: (s) => pc.bold(pc.magenta(s)),
+  live: (s) => pc.green(s),
+  finished: (s) => pc.cyan(s),
+  upcoming: (s) => pc.gray(s),
+  score: (s) => pc.bold(pc.white(s)),
+  dim: (s) => pc.gray(s),
+  goal: (s) => pc.bold(pc.green(s)),
+  yellow: (s) => pc.yellow(s),
+  red: (s) => pc.bold(pc.red(s)),
+  accent: (s) => pc.magenta(s),
+  sel: (s) => pc.bold(pc.magenta(s))
+};
+function commentaryColor(text, isGoal) {
+  const t = text.toLowerCase();
+  if (isGoal) return c.goal;
+  if (t.includes("red card")) return c.red;
+  if (t.includes("yellow card") || t.includes("booked")) return c.yellow;
+  if (t.includes("penalty")) return c.accent;
+  if (/(half time|full time|first half|second half|kick-?off|kicks off|begins|ends|lineups|added time)/.test(t)) {
+    return c.dim;
+  }
+  if (t.includes("substitution") || t.includes("replaces")) return pc.cyan;
+  return (s) => s;
+}
+
+// src/format.ts
+function truncate(s, max) {
+  if (max <= 1) return s.slice(0, Math.max(0, max));
+  return s.length > max ? s.slice(0, max - 1) + "\u2026" : s;
+}
+function kickoffLocal(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleString(void 0, {
+    weekday: "short",
+    hour: "numeric",
+    minute: "2-digit"
+  });
+}
+
+// src/pitch.ts
+import pc2 from "picocolors";
+import stringWidth from "string-width";
+var HOME = pc2.cyan;
+var AWAY = pc2.magenta;
+var LINE = (s) => pc2.gray(s);
+function mapEvent(x, y, isHome, IW, IH) {
+  const xAbs = isHome ? 1 - x : x;
+  const yAbs = isHome ? y : 1 - y;
+  const col = Math.max(0, Math.min(IW - 1, Math.round(xAbs * (IW - 1))));
+  const row = Math.max(0, Math.min(IH - 1, Math.round(yAbs * (IH - 1))));
+  return { col, row };
+}
+function renderPitch(detail, innerWidth) {
+  const IW = Math.max(34, Math.min(innerWidth - 4, 60));
+  const IH = 9;
+  const grid = Array.from({ length: IH }, () => Array.from({ length: IW }, () => " "));
+  const rmid = Math.floor(IH / 2);
+  const cmid = Math.floor(IW / 2);
+  const boxW = 6;
+  for (let r = 0; r < IH; r++) grid[r][cmid] = LINE("\u2506");
+  if (cmid - 3 > boxW) {
+    grid[rmid][cmid - 3] = LINE("(");
+    grid[rmid][cmid + 3] = LINE(")");
+  }
+  grid[rmid][cmid] = LINE("\u2022");
+  const r1 = rmid - 2;
+  const r2 = rmid + 2;
+  for (let r = r1; r <= r2; r++) {
+    if (r < 0 || r >= IH) continue;
+    grid[r][boxW] = LINE("\u2506");
+    grid[r][IW - 1 - boxW] = LINE("\u2506");
+  }
+  for (let cc = 1; cc < boxW; cc++) {
+    if (r1 >= 0) {
+      if (grid[r1][cc] === " ") grid[r1][cc] = LINE("\xB7");
+      if (grid[r1][IW - 1 - cc] === " ") grid[r1][IW - 1 - cc] = LINE("\xB7");
+    }
+    if (r2 < IH) {
+      if (grid[r2][cc] === " ") grid[r2][cc] = LINE("\xB7");
+      if (grid[r2][IW - 1 - cc] === " ") grid[r2][IW - 1 - cc] = LINE("\xB7");
+    }
+  }
+  for (let r = rmid - 1; r <= rmid + 1; r++) {
+    if (r < 0 || r >= IH) continue;
+    grid[r][0] = LINE("\u2590");
+    grid[r][IW - 1] = LINE("\u258C");
+  }
+  const events = detail.commentary.filter((c2) => c2.x != null && c2.y != null);
+  const homeId = detail.home.id;
+  const plot = (e, ch) => {
+    const { col, row } = mapEvent(e.x, e.y, e.teamId === homeId, IW, IH);
+    grid[row][col] = ch;
+  };
+  const recent = events.slice(0, 7);
+  for (let i = recent.length - 1; i >= 1; i--) {
+    const e = recent[i];
+    plot(e, (e.teamId === homeId ? HOME : AWAY)(pc2.dim("\u2219")));
+  }
+  for (const g of events.filter((e) => e.isGoal)) plot(g, pc2.bold(pc2.green("\u2605")));
+  const newest = recent[0];
+  if (newest) {
+    plot(newest, newest.isGoal ? pc2.bold(pc2.green("\u2605")) : pc2.bold((newest.teamId === homeId ? HOME : AWAY)("\u25CF")));
+  }
+  const top = LINE(`  \u256D${"\u2500".repeat(IW)}\u256E`);
+  const bot = LINE(`  \u2570${"\u2500".repeat(IW)}\u256F`);
+  const body = grid.map((r) => `${LINE("  \u2502")}${r.join("")}${LINE("\u2502")}`);
+  const latest = events[0];
+  let legend = `   ${HOME("\u25CF")} ${detail.home.flag} ${pc2.bold(truncate(detail.home.name, 16))} ${pc2.gray("\u2192")}    ${pc2.gray("\u2190")} ${pc2.bold(truncate(detail.away.name, 16))} ${detail.away.flag} ${AWAY("\u25CF")}`;
+  if (latest) {
+    const tag = latest.isGoal ? pc2.bold(pc2.green("\u2605 GOAL")) : pc2.gray(latest.playType || "ball");
+    legend += `    ${pc2.gray(latest.time)} ${tag}`;
+  }
+  void stringWidth;
+  return [top, ...body, bot, legend].join("\n");
+}
+
+// src/render.ts
+var CHARS = {
+  top: "\u2500",
+  "top-mid": "\u252C",
+  "top-left": "\u256D",
+  "top-right": "\u256E",
+  bottom: "\u2500",
+  "bottom-mid": "\u2534",
+  "bottom-left": "\u2570",
+  "bottom-right": "\u256F",
+  left: "\u2502",
+  "left-mid": "\u251C",
+  mid: "\u2500",
+  "mid-mid": "\u253C",
+  right: "\u2502",
+  "right-mid": "\u2524",
+  middle: "\u2502"
+};
+function makeTable(opts) {
+  return new Table({
+    chars: CHARS,
+    style: { head: [], border: ["gray"], "padding-left": 1, "padding-right": 1 },
+    ...opts
+  });
+}
+function padEndW(s, w) {
+  const d = w - stringWidth2(s);
+  return d > 0 ? s + " ".repeat(d) : s;
+}
+function padCenterW(s, w) {
+  const d = Math.max(0, w - stringWidth2(s));
+  const left = Math.floor(d / 2);
+  return " ".repeat(left) + s + " ".repeat(d - left);
+}
+function headerLine(s, width) {
+  const left = c.title(`${SYM.ball} ${s.title}`);
+  const live = s.matches.filter((m) => m.state === "in").length;
+  const liveTxt = live > 0 ? `${c.live(`${SYM.live} ${live} LIVE`)}  ` : "";
+  const upd = s.updatedAt ? new Date(s.updatedAt).toLocaleTimeString() : "\u2014";
+  const cd = s.countdown != null ? `  ${SYM.refresh}${s.countdown}s` : "";
+  const right = `${liveTxt}${pc3.gray(`${s.matches.length} matches \xB7 ${upd}${cd}`)}`;
+  const pad = Math.max(1, width - stringWidth2(left) - stringWidth2(right));
+  return `${left}${" ".repeat(pad)}${right}`;
+}
+function fixturesList(s, width) {
+  const NAME = 14;
+  const COLW = NAME + 3;
+  const lines = [`  ${pc3.bold(pc3.gray("MATCHES"))}`, pc3.gray(`  ${"\u2500".repeat(Math.min(width - 2, 64))}`)];
+  s.matches.forEach((m, i) => {
+    const sel = i === s.selected;
+    const home = padEndW(`${m.home.flag} ${truncate(m.home.name, NAME)}`, COLW);
+    const away = padEndW(`${truncate(m.away.name, NAME)} ${m.away.flag}`, COLW);
+    const score = m.state === "pre" ? pc3.gray(" v ") : padCenterW(c.score(`${m.home.score ?? 0}-${m.away.score ?? 0}`), 5);
+    const status = m.state === "in" ? c.live(`${SYM.live} ${m.clock || "LIVE"}`) : m.state === "post" ? c.finished(m.shortDetail || "FT") : c.upcoming(kickoffLocal(m.date) || "Scheduled");
+    const arrow = sel ? c.sel(SYM.sel) : " ";
+    const row = `  ${arrow} ${sel ? c.sel(home) : home} ${score}  ${sel ? c.sel(away) : away}  ${status}`;
+    lines.push(row);
+  });
+  return lines.join("\n");
+}
+function scoreStrip(s, m) {
+  const d = s.detail && s.detail.id === m.id ? s.detail : null;
+  const home = d?.home ?? m.home;
+  const away = d?.away ?? m.away;
+  const state = d?.state ?? m.state;
+  const clock = d?.clock || m.clock;
+  const badge = state === "in" ? c.live(`${SYM.live} ${clock || "LIVE"}`) : state === "post" ? c.finished(d?.shortDetail || m.shortDetail || "FT") : c.upcoming(kickoffLocal(m.date) || "Scheduled");
+  const hs = home.score ?? "\u2013";
+  const as = away.score ?? "\u2013";
+  const hn = pc3.bold(truncate(home.name, 22));
+  const an = pc3.bold(truncate(away.name, 22));
+  return `  ${home.flag} ${hn}  ${c.score(String(hs))} ${pc3.gray(":")} ${c.score(String(as))}  ${an} ${away.flag}    ${badge}`;
+}
+function statsStrip(d, width) {
+  if (!d || d.stats.length === 0) return "";
+  const sep = pc3.gray("   \xB7   ");
+  let line = "  ";
+  let count = 0;
+  for (const st of d.stats) {
+    const piece = `${pc3.white(st.home)} ${pc3.gray(st.label)} ${pc3.white(st.away)}`;
+    const next = count === 0 ? line + piece : line + sep + piece;
+    if (stringWidth2(next) > width) break;
+    line = next;
+    count += 1;
+  }
+  return count > 0 ? line : "";
+}
+function commentaryTable(d, width, budget) {
+  const textCol = Math.max(30, width - 9);
+  const wrapW = textCol - 2;
+  const t = makeTable({
+    head: [pc3.gray("Min"), pc3.gray("Commentary")],
+    colWidths: [6, textCol],
+    wordWrap: true
+  });
+  let used = 0;
+  for (const line of d.commentary) {
+    const text = truncate(line.text, wrapW * 2);
+    const wrapped = Math.max(1, Math.ceil(stringWidth2(text) / wrapW));
+    if (used + wrapped > budget && used > 0) break;
+    used += wrapped;
+    t.push([c.accent(line.time), commentaryColor(line.text, line.isGoal)(text)]);
+  }
+  if (used === 0) return pc3.gray("  Awaiting first updates\u2026");
+  return t.toString();
+}
+function preNote(m, width) {
+  const ko = kickoffLocal(m.date) || m.detail || "TBD";
+  return [
+    `  ${pc3.gray("Kickoff:")} ${pc3.bold(ko)}`,
+    `  ${pc3.gray(truncate(m.detail || "", width))}`,
+    `  ${pc3.gray(`Live commentary & stats appear at kickoff ${SYM.ball}`)}`
+  ].join("\n");
+}
+function footer(s) {
+  const pitch = s.showPitch ? "[p] pitch\u2713" : "[p] pitch";
+  return pc3.gray(`  [\u2191\u2193] navigate \xB7 ${pitch} \xB7 [q] quit \xB7 data: ESPN (unofficial) \xB7 ${s.league}`);
+}
+function renderFrame(s) {
+  const W = Math.min((s.cols || 80) - 2, 118);
+  if (s.error && s.matches.length === 0) {
+    return `${pc3.red(`\u26A0 Could not reach ESPN: ${s.error}`)}
+${pc3.gray("Will keep retrying\u2026")}`;
+  }
+  if (s.matches.length === 0) {
+    return `${headerLine(s, W)}
+${pc3.gray("  No matches found for this view.")}`;
+  }
+  const cur = s.matches[s.selected] ?? null;
+  const out = [headerLine(s, W), "", fixturesList(s, W)];
+  if (cur) {
+    out.push("", scoreStrip(s, cur));
+    const d = s.detail && s.detail.id === cur.id ? s.detail : null;
+    if (cur.state === "pre") {
+      out.push(preNote(cur, W));
+    } else if (s.detailLoading && !d) {
+      out.push(pc3.gray("  loading match\u2026"));
+    } else if (d) {
+      const stats = statsStrip(d, W);
+      if (stats) out.push(stats);
+      const hasPos = d.commentary.some((cl) => cl.x != null && cl.y != null);
+      const pitchH = s.showPitch && hasPos ? 12 : 0;
+      if (pitchH) out.push(renderPitch(d, W));
+      const overhead = 2 + (s.matches.length + 2) + 2 + (stats ? 1 : 0) + 1 + 4 + pitchH;
+      const budget = Math.min(40, Math.max(4, (s.rows || 24) - overhead));
+      out.push(commentaryTable(d, W, budget));
+    }
+  }
+  if (!s.once) out.push(footer(s));
+  return out.join("\n");
+}
+
+// src/app.ts
+async function runApp(opts) {
+  const boardMs = Math.max(5, opts.refreshSec) * 1e3;
+  const detailMs = Math.max(5, Math.min(opts.refreshSec, 12)) * 1e3;
+  const state = {
+    matches: [],
+    detail: null,
+    selected: 0,
+    error: null,
+    updatedAt: null,
+    detailLoading: false,
+    countdown: null,
+    showPitch: true
+  };
+  const draw = () => logUpdate(
+    renderFrame({
+      title: opts.title,
+      league: opts.league,
+      once: opts.once,
+      matches: state.matches,
+      detail: state.detail,
+      selected: state.selected,
+      error: state.error,
+      updatedAt: state.updatedAt,
+      detailLoading: state.detailLoading,
+      countdown: state.countdown,
+      showPitch: state.showPitch,
+      cols: process.stdout.columns ?? (Number(process.env.COLUMNS) || 80),
+      rows: process.stdout.rows ?? (Number(process.env.LINES) || 24)
+    })
+  );
+  const loadBoard = async () => {
+    try {
+      const matches = await fetchScoreboard(opts.league, opts.date);
+      state.matches = matches;
+      state.error = null;
+      state.updatedAt = Date.now();
+      if (state.selected > matches.length - 1) state.selected = Math.max(0, matches.length - 1);
+    } catch (e) {
+      if (e?.name !== "AbortError") state.error = e?.message ?? String(e);
+    }
+  };
+  let detailReq = 0;
+  const loadDetail = async () => {
+    const cur = state.matches[state.selected];
+    if (!cur) {
+      state.detail = null;
+      return;
+    }
+    const id = cur.id;
+    const my = ++detailReq;
+    state.detailLoading = true;
+    try {
+      const detail = await fetchSummary(opts.league, id);
+      if (my !== detailReq) return;
+      state.detail = detail;
+    } catch {
+    } finally {
+      if (my === detailReq) state.detailLoading = false;
+    }
+  };
+  await loadBoard();
+  const liveIdx = state.matches.findIndex((m) => m.state === "in");
+  if (liveIdx >= 0) state.selected = liveIdx;
+  await loadDetail();
+  draw();
+  if (opts.once || !process.stdin.isTTY) {
+    logUpdate.done();
+    return;
+  }
+  state.countdown = Math.round(boardMs / 1e3);
+  const boardTimer = setInterval(async () => {
+    await loadBoard();
+    state.countdown = Math.round(boardMs / 1e3);
+    draw();
+  }, boardMs);
+  const detailTimer = setInterval(async () => {
+    await loadDetail();
+    draw();
+  }, detailMs);
+  const tick = setInterval(() => {
+    if (state.countdown != null) state.countdown = Math.max(0, state.countdown - 1);
+    draw();
+  }, 1e3);
+  const cleanup = () => {
+    clearInterval(boardTimer);
+    clearInterval(detailTimer);
+    clearInterval(tick);
+    process.stdin.off("keypress", onKey);
+    try {
+      process.stdin.setRawMode(false);
+    } catch {
+    }
+    logUpdate.done();
+    process.stdout.write("\n");
+    process.exit(0);
+  };
+  const reselect = async (delta) => {
+    const next = Math.min(state.matches.length - 1, Math.max(0, state.selected + delta));
+    if (next === state.selected) return;
+    state.selected = next;
+    state.detail = null;
+    draw();
+    await loadDetail();
+    draw();
+  };
+  const onKey = (_str, key) => {
+    if (!key) return;
+    if (key.name === "q" || key.name === "escape" || key.ctrl && key.name === "c") {
+      cleanup();
+      return;
+    }
+    if (key.name === "up" || key.name === "k") void reselect(-1);
+    else if (key.name === "down" || key.name === "j") void reselect(1);
+    else if (key.name === "p") {
+      state.showPitch = !state.showPitch;
+      draw();
+    } else if (key.name === "r") void loadBoard().then(draw);
+  };
+  readline.emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on("keypress", onKey);
+}
+
+// bin/index.ts
+var argv = process2.argv.slice(2);
+function opt(name) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : void 0;
+}
+function flag(name) {
+  return argv.includes(name);
+}
+if (flag("--help") || flag("-h")) {
+  console.log(`
+  \u26BD soccer \u2014 live football scores & commentary in your terminal
+
+  Usage
+    $ soccer [options]
+
+  Options
+    --league <slug>    ESPN league slug (default: fifa.world)
+                       e.g. eng.1, esp.1, ger.1, ita.1, uefa.champions
+    --date <YYYYMMDD>  Show a specific day's fixtures
+    --refresh <sec>    Auto-refresh interval (default: 15, min 5)
+    --once             Print one snapshot and exit (good for piping/cron)
+    --title <text>     Override the header title
+    -h, --help         Show this help
+
+  Keys
+    \u2191/\u2193 or j/k         Move between matches
+    r                  Force refresh
+    q or Esc           Quit
+
+  Examples
+    $ soccer                            # FIFA World Cup, live
+    $ soccer --league eng.1             # Premier League
+    $ soccer --date 20260611 --once     # snapshot of a given day
+
+  Data: ESPN's public (unofficial) feed. No API key required.
+`);
+  process2.exit(0);
+}
+var league = opt("--league") ?? "fifa.world";
+var date = opt("--date");
+var refreshSec = Number(opt("--refresh") ?? "15") || 15;
+var once = flag("--once") || !process2.stdin.isTTY;
+var TITLES = {
+  "fifa.world": "FIFA WORLD CUP 2026",
+  "eng.1": "PREMIER LEAGUE",
+  "esp.1": "LA LIGA",
+  "ger.1": "BUNDESLIGA",
+  "ita.1": "SERIE A",
+  "fra.1": "LIGUE 1",
+  "uefa.champions": "CHAMPIONS LEAGUE"
+};
+var title = opt("--title") ?? TITLES[league] ?? league.toUpperCase();
+runApp({ league, title, date, refreshSec, once }).catch((err) => {
+  console.error(err);
+  process2.exit(1);
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "soccer-cli",
+  "version": "0.1.0",
+  "description": "Live football scores, ball-by-ball commentary, and a live ASCII pitch in your terminal. Built for the 2026 World Cup, works for every major league. No API key required.",
+  "type": "module",
+  "bin": {
+    "soccer": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx bin/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "soccer",
+    "football",
+    "world-cup",
+    "fifa",
+    "cli",
+    "tui",
+    "live-scores",
+    "commentary",
+    "terminal",
+    "espn"
+  ],
+  "author": "SpunkySarb <sarbsagar143@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpunkySarb/soccer-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SpunkySarb/soccer-cli/issues"
+  },
+  "homepage": "https://github.com/SpunkySarb/soccer-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cli-table3": "^0.6.5",
+    "i18n-iso-countries": "^7.13.0",
+    "log-update": "^6.1.0",
+    "picocolors": "^1.1.1",
+    "string-width": "^7.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}