worldcup26-cli 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# worldcup26-cli ⚽
+
+A colorful terminal CLI to follow the **FIFA World Cup 2026** (USA · Canada · Mexico).
+View today's games, group standings, country stats, and the knockout bracket — right from your shell.
+
+```
+$ worldcup --date 2026-06-11
+
+⚽ Matches on Thu, Jun 11, 2026
+
+  🇲🇽 Mexico                  vs  South Africa 🇿🇦  · 13:00 UTC-6 @ Mexico City  [Group A]
+  🇰🇷 South Korea             vs  Czech Republic 🇨🇿  · 20:00 UTC-6 @ Guadalajara  [Group A]
+```
+
+## Features
+
+- **`today`** — matches scheduled for today, with scores once played. For any other day, use the top-level `--date`.
+- **`groups`** — all 12 group tables, or a single group with `--group`. Standings (Pts → GD → GF) are computed from results; the top 2 are highlighted.
+- **`country`** — a team's group, current standing, and full match list, looked up by name (partial, case-insensitive).
+- **`knockout`** — the bracket by stage (Round of 32 → Final), filterable with `--stage`.
+
+## Install
+
+```bash
+npm install -g worldcup26-cli
+worldcup today
+```
+
+Or run it without installing:
+
+```bash
+npx worldcup26-cli groups --group A
+```
+
+> Requires **Node.js ≥ 18** (uses the built-in `fetch`).
+
+## Usage
+
+```bash
+worldcup today                          # today's fixtures
+worldcup --date 2026-06-11              # fixtures for a specific day
+worldcup groups [--group A]             # all groups, or just one
+worldcup country <name>                 # e.g. "mexico", "kor", "brazil"
+worldcup knockout [--stage <name>]      # r32 | r16 | qf | sf | third | final
+worldcup ko --stage final               # 'ko' is an alias for 'knockout'
+
+# Global flags
+-d, --date <YYYY-MM-DD>   # show matches for a specific day
+--refresh                 # bypass the local cache and re-fetch
+--no-color                # plain output (also honors the NO_COLOR env var)
+-v, --version
+-h, --help
+```
+
+## Data source
+
+Match data comes from the public-domain **[openfootball/worldcup.json](https://github.com/openfootball/worldcup.json)** project — no API key required. The CLI fetches it once and caches it at `~/.worldcup-cli/cache.json` (1-hour TTL), so repeat commands are instant and it still works offline from the last successful fetch. Use `--refresh` to force an update.
+
+Scores reflect **final/official results** (updated after matches finish) — there is no live in-progress ticker. Group standings use the common Pts → goal-difference → goals-for tiebreakers (a simplification of the full FIFA criteria).
+
+## Development
+
+```bash
+npm install
+npm run dev -- --date 2026-06-11         # run from source via tsx
+npm run build                            # compile TypeScript to dist/
+node dist/index.js groups                # run the build
+```
+
+### Test it locally as a global command
+
+```bash
+npm run build
+npm link                 # makes `worldcup` available system-wide
+worldcup --date 2026-06-11
+npm unlink -g worldcup26-cli   # when finished
+```
+
+Alternatives without linking: `node dist/index.js <cmd>` or `npm install -g .`.
+
+## Publishing to npm
+
+1. **Check the name is free:** `npm view worldcup26-cli`. If taken, switch to a scoped name (e.g. `@yourname/worldcup26-cli`) in `package.json`.
+2. **Log in:** `npm login`.
+3. **Bump the version:** `npm version patch` (or `minor` / `major`).
+4. **Publish:** `npm publish`.
+   - For a scoped package, the first publish needs `npm publish --access public`.
+   - The `prepublishOnly` script builds `dist/` automatically, and `"files": ["dist"]` keeps the published package lean.
+5. Users can now `npm install -g worldcup26-cli` or `npx worldcup26-cli`.
+
+## Project structure
+
+```
+src/
+  index.ts            # commander program + global flags
+  types.ts            # Match / Score / Standing types
+  data/
+    fetch.ts          # fetch upstream JSON, TTL cache, offline fallback
+    cache.ts          # ~/.worldcup-cli/cache.json read/write
+    flags.ts          # team → flag emoji + 3-letter code
+  lib/
+    standings.ts      # compute group tables from results
+    dates.ts          # date parsing / "today" handling
+    format.ts         # chalk rendering (match lines, tables)
+  commands/
+    today.ts  groups.ts  country.ts  knockout.ts
+```
+
+## License
+
+MIT

package/dist/commands/country.js

@@ -0,0 +1,63 @@
+import chalk from "chalk";
+import { loadTournament } from "../data/fetch.js";
+import { isRealTeam, teamFlag } from "../data/flags.js";
+import { computeStandings } from "../lib/standings.js";
+import { matchLine, matchContext, title, subtle, header } from "../lib/format.js";
+export function registerCountry(program) {
+    program
+        .command("country")
+        .description("Show a country's group, standing, and matches (by name)")
+        .argument("<name>", "country name or part of it, e.g. 'mexico' or 'kor'")
+        .action(async (name, _opts, cmd) => {
+        const global = cmd.optsWithGlobals();
+        const { matches } = await loadTournament({ refresh: global.refresh });
+        // Distinct real team names appearing in the data.
+        const teams = new Set();
+        for (const m of matches) {
+            if (isRealTeam(m.team1))
+                teams.add(m.team1);
+            if (isRealTeam(m.team2))
+                teams.add(m.team2);
+        }
+        const query = name.trim().toLowerCase();
+        const hits = [...teams].filter((t) => t.toLowerCase().includes(query)).sort();
+        if (hits.length === 0) {
+            process.stderr.write(chalk.red(`No team matches "${name}".\n`));
+            process.exitCode = 1;
+            return;
+        }
+        if (hits.length > 1) {
+            console.log(subtle(`Multiple teams match "${name}":`));
+            for (const t of hits)
+                console.log(`  ${teamFlag(t)} ${t}`);
+            console.log(subtle(`\nBe more specific.`));
+            return;
+        }
+        const team = hits[0];
+        const teamMatches = matches
+            .filter((m) => m.team1 === team || m.team2 === team)
+            .sort((a, b) => a.date.localeCompare(b.date));
+        const group = teamMatches.find((m) => m.group)?.group;
+        console.log(title(`\n${teamFlag(team)} ${team}`));
+        if (group) {
+            const rows = computeStandings(matches, group);
+            const idx = rows.findIndex((r) => r.team === team);
+            const row = rows[idx];
+            console.log(subtle(`${group} · currently ${ordinal(idx + 1)}`));
+            if (row) {
+                console.log(`  ${row.played} played · ${chalk.green(row.won + "W")}-${row.drawn}D-${chalk.red(row.lost + "L")} · ` +
+                    `GF ${row.gf} GA ${row.ga} (${row.gd >= 0 ? "+" : ""}${row.gd}) · ${chalk.bold(row.points)} pts`);
+            }
+        }
+        console.log(header("Matches"));
+        for (const m of teamMatches) {
+            console.log(`  ${matchLine(m)}`);
+            console.log(`    ${matchContext(m)}`);
+        }
+    });
+}
+function ordinal(n) {
+    const s = ["th", "st", "nd", "rd"];
+    const v = n % 100;
+    return n + (s[(v - 20) % 10] ?? s[v] ?? s[0]);
+}

package/dist/commands/groups.js

@@ -0,0 +1,38 @@
+import chalk from "chalk";
+import { loadTournament } from "../data/fetch.js";
+import { computeStandings, listGroups } from "../lib/standings.js";
+import { header, standingsTable, title, subtle } from "../lib/format.js";
+/** Accept "A", "a", or "Group A" and normalise to the canonical "Group A". */
+function normaliseGroup(input) {
+    const trimmed = input.trim();
+    const letter = trimmed.replace(/^group\s*/i, "").toUpperCase();
+    return `Group ${letter}`;
+}
+export function registerGroups(program) {
+    program
+        .command("groups")
+        .description("Show group standings — all groups, or one with --group")
+        .option("-g, --group <letter>", "show only this group (e.g. A or 'Group A')")
+        .action(async (opts, cmd) => {
+        const global = cmd.optsWithGlobals();
+        const { matches } = await loadTournament({ refresh: global.refresh });
+        const allGroups = listGroups(matches);
+        let groups = allGroups;
+        if (opts.group) {
+            const target = normaliseGroup(opts.group);
+            if (!allGroups.includes(target)) {
+                process.stderr.write(chalk.red(`Unknown group "${opts.group}". Available: ${allGroups.map((g) => g.replace("Group ", "")).join(", ")}\n`));
+                process.exitCode = 1;
+                return;
+            }
+            groups = [target];
+        }
+        console.log(title(`\n🏆 World Cup 2026 — Group Standings`));
+        for (const group of groups) {
+            const rows = computeStandings(matches, group);
+            console.log(header(group));
+            console.log(standingsTable(rows, 2));
+        }
+        console.log(subtle(`\n${chalk.green("▲")} top 2 advance directly. The 8 best 3rd-placed teams also reach the Round of 32.`));
+    });
+}

package/dist/commands/knockout.js

@@ -0,0 +1,72 @@
+import chalk from "chalk";
+import { loadTournament } from "../data/fetch.js";
+import { matchLine, title, subtle, header } from "../lib/format.js";
+/** Knockout rounds in tournament order, as labelled by OpenFootball. */
+const STAGE_ORDER = [
+    "Round of 32",
+    "Round of 16",
+    "Quarter-final",
+    "Semi-final",
+    "Match for third place",
+    "Final",
+];
+/** Short aliases the user can pass to --stage. */
+const ALIASES = {
+    r32: "Round of 32",
+    "round-of-32": "Round of 32",
+    r16: "Round of 16",
+    "round-of-16": "Round of 16",
+    qf: "Quarter-final",
+    quarter: "Quarter-final",
+    "quarter-final": "Quarter-final",
+    "quarter-finals": "Quarter-final",
+    sf: "Semi-final",
+    semi: "Semi-final",
+    "semi-final": "Semi-final",
+    "semi-finals": "Semi-final",
+    third: "Match for third place",
+    "third-place": "Match for third place",
+    final: "Final",
+};
+function resolveStage(input) {
+    const key = input.trim().toLowerCase();
+    if (ALIASES[key])
+        return ALIASES[key];
+    const exact = STAGE_ORDER.find((s) => s.toLowerCase() === key);
+    return exact ?? null;
+}
+export function registerKnockout(program) {
+    program
+        .command("knockout")
+        .alias("ko")
+        .description("Show the knockout bracket by stage (--stage to filter)")
+        .option("-s, --stage <name>", "filter to one stage (e.g. r16, qf, sf, final)")
+        .action(async (opts, cmd) => {
+        const global = cmd.optsWithGlobals();
+        const { matches } = await loadTournament({ refresh: global.refresh });
+        // Knockout matches have no group label.
+        const knockout = matches.filter((m) => !m.group);
+        let stages = STAGE_ORDER;
+        if (opts.stage) {
+            const resolved = resolveStage(opts.stage);
+            if (!resolved) {
+                process.stderr.write(chalk.red(`Unknown stage "${opts.stage}". Try: r32, r16, qf, sf, third, final.\n`));
+                process.exitCode = 1;
+                return;
+            }
+            stages = [resolved];
+        }
+        console.log(title(`\n🏆 World Cup 2026 — Knockout Stage`));
+        for (const stage of stages) {
+            const games = knockout
+                .filter((m) => m.round === stage)
+                .sort((a, b) => (a.num ?? 0) - (b.num ?? 0));
+            if (games.length === 0)
+                continue;
+            console.log(header(stage));
+            for (const m of games)
+                console.log(`  ${matchLine(m)}`);
+        }
+        console.log(subtle(`\nPlaceholders like "1A" / "2B" / "3A/B/C/D/F" resolve once the groups finish.`));
+    });
+}

package/dist/commands/today.js

@@ -0,0 +1,29 @@
+import { loadTournament } from "../data/fetch.js";
+import { todayISO, formatDate } from "../lib/dates.js";
+import { matchLine, title, subtle } from "../lib/format.js";
+/** Print every match on a given "YYYY-MM-DD" date. Shared by `today` and the root `--date` flag. */
+export async function renderGames(date, refresh) {
+    const { matches } = await loadTournament({ refresh });
+    const games = matches
+        .filter((m) => m.date === date)
+        .sort((a, b) => (a.time ?? "").localeCompare(b.time ?? ""));
+    console.log(title(`\n⚽ Matches on ${formatDate(date)}`));
+    if (games.length === 0) {
+        console.log(subtle(`\nNo games scheduled. The tournament runs Jun 11 – Jul 19, 2026.`));
+        return;
+    }
+    console.log();
+    for (const m of games) {
+        const tag = m.group ? subtle(`[${m.group}]`) : subtle(`[${m.round}]`);
+        console.log(`  ${matchLine(m)}  ${tag}`);
+    }
+}
+export function registerToday(program) {
+    program
+        .command("today")
+        .description("Show today's matches (use the top-level --date for another day)")
+        .action(async (_opts, cmd) => {
+        const global = cmd.optsWithGlobals();
+        await renderGames(todayISO(), Boolean(global.refresh));
+    });
+}

package/dist/data/cache.js

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+const CACHE_DIR = join(homedir(), ".worldcup-cli");
+const CACHE_FILE = join(CACHE_DIR, "cache.json");
+/** Read the cached tournament, or null if there is no (readable) cache. */
+export async function readCache() {
+    try {
+        const raw = await readFile(CACHE_FILE, "utf8");
+        const entry = JSON.parse(raw);
+        if (!entry?.data?.matches)
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the tournament to the on-disk cache, stamping the fetch time. */
+export async function writeCache(data, fetchedAt) {
+    await mkdir(CACHE_DIR, { recursive: true });
+    const entry = { fetchedAt, data };
+    await writeFile(CACHE_FILE, JSON.stringify(entry), "utf8");
+}
+export const cacheLocation = CACHE_FILE;

package/dist/data/fetch.js

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { readCache, writeCache } from "./cache.js";
+const DATA_URL = "https://raw.githubusercontent.com/openfootball/worldcup.json/master/2026/worldcup.json";
+/** Cache time-to-live: results don't change often, so an hour is plenty. */
+const TTL_MS = 60 * 60 * 1000;
+/**
+ * Load the tournament data, preferring a fresh local cache and falling back
+ * gracefully when offline:
+ *   1. Fresh cache (younger than the TTL, unless --refresh) -> use it.
+ *   2. Otherwise fetch upstream, then update the cache.
+ *   3. On network failure, fall back to a stale cache with a warning.
+ *   4. With no cache at all and no network, throw a clear error.
+ */
+export async function loadTournament(opts = {}) {
+    const cached = await readCache();
+    if (!opts.refresh && cached && Date.now() - cached.fetchedAt < TTL_MS) {
+        return cached.data;
+    }
+    try {
+        const res = await fetch(DATA_URL);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        const data = (await res.json());
+        if (!data?.matches?.length)
+            throw new Error("upstream returned no matches");
+        await writeCache(data, Date.now());
+        return data;
+    }
+    catch (err) {
+        if (cached) {
+            const age = Math.round((Date.now() - cached.fetchedAt) / 60000);
+            process.stderr.write(chalk.dim(`! could not reach data source (${describe(err)}); using cached data (~${age} min old)\n`));
+            return cached.data;
+        }
+        throw new Error(`Unable to fetch World Cup data and no local cache is available.\n` +
+            `  Source: ${DATA_URL}\n` +
+            `  Reason: ${describe(err)}\n` +
+            `  Check your internet connection and try again.`);
+    }
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/data/flags.js

@@ -0,0 +1,61 @@
+const TEAMS = {
+    Argentina: { flag: "🇦🇷", code: "ARG" },
+    Algeria: { flag: "🇩🇿", code: "ALG" },
+    Australia: { flag: "🇦🇺", code: "AUS" },
+    Austria: { flag: "🇦🇹", code: "AUT" },
+    Belgium: { flag: "🇧🇪", code: "BEL" },
+    "Bosnia & Herzegovina": { flag: "🇧🇦", code: "BIH" },
+    Brazil: { flag: "🇧🇷", code: "BRA" },
+    Canada: { flag: "🇨🇦", code: "CAN" },
+    "Cape Verde": { flag: "🇨🇻", code: "CPV" },
+    Colombia: { flag: "🇨🇴", code: "COL" },
+    Croatia: { flag: "🇭🇷", code: "CRO" },
+    "Curaçao": { flag: "🇨🇼", code: "CUW" },
+    "Czech Republic": { flag: "🇨🇿", code: "CZE" },
+    "DR Congo": { flag: "🇨🇩", code: "COD" },
+    Ecuador: { flag: "🇪🇨", code: "ECU" },
+    Egypt: { flag: "🇪🇬", code: "EGY" },
+    England: { flag: "🏴󠁧󠁢󠁥󠁮󠁧󠁿", code: "ENG" },
+    France: { flag: "🇫🇷", code: "FRA" },
+    Germany: { flag: "🇩🇪", code: "GER" },
+    Ghana: { flag: "🇬🇭", code: "GHA" },
+    Haiti: { flag: "🇭🇹", code: "HAI" },
+    Iran: { flag: "🇮🇷", code: "IRN" },
+    Iraq: { flag: "🇮🇶", code: "IRQ" },
+    "Ivory Coast": { flag: "🇨🇮", code: "CIV" },
+    Japan: { flag: "🇯🇵", code: "JPN" },
+    Jordan: { flag: "🇯🇴", code: "JOR" },
+    Mexico: { flag: "🇲🇽", code: "MEX" },
+    Morocco: { flag: "🇲🇦", code: "MAR" },
+    Netherlands: { flag: "🇳🇱", code: "NED" },
+    "New Zealand": { flag: "🇳🇿", code: "NZL" },
+    Norway: { flag: "🇳🇴", code: "NOR" },
+    Panama: { flag: "🇵🇦", code: "PAN" },
+    Paraguay: { flag: "🇵🇾", code: "PAR" },
+    Portugal: { flag: "🇵🇹", code: "POR" },
+    Qatar: { flag: "🇶🇦", code: "QAT" },
+    "Saudi Arabia": { flag: "🇸🇦", code: "KSA" },
+    Scotland: { flag: "🏴󠁧󠁢󠁳󠁣󠁴󠁿", code: "SCO" },
+    Senegal: { flag: "🇸🇳", code: "SEN" },
+    "South Africa": { flag: "🇿🇦", code: "RSA" },
+    "South Korea": { flag: "🇰🇷", code: "KOR" },
+    Spain: { flag: "🇪🇸", code: "ESP" },
+    Sweden: { flag: "🇸🇪", code: "SWE" },
+    Switzerland: { flag: "🇨🇭", code: "SUI" },
+    Tunisia: { flag: "🇹🇳", code: "TUN" },
+    Turkey: { flag: "🇹🇷", code: "TUR" },
+    Uruguay: { flag: "🇺🇾", code: "URU" },
+    USA: { flag: "🇺🇸", code: "USA" },
+    Uzbekistan: { flag: "🇺🇿", code: "UZB" },
+};
+const DEFAULT = { flag: "🏳️", code: "?" };
+export function teamFlag(team) {
+    return (TEAMS[team] ?? DEFAULT).flag;
+}
+export function teamCode(team) {
+    return (TEAMS[team] ?? DEFAULT).code;
+}
+/** True when the name is a real team (not a knockout placeholder like "2A"). */
+export function isRealTeam(team) {
+    return team in TEAMS;
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import chalk from "chalk";
+import { registerToday, renderGames } from "./commands/today.js";
+import { registerGroups } from "./commands/groups.js";
+import { registerCountry } from "./commands/country.js";
+import { registerKnockout } from "./commands/knockout.js";
+import { isValidISODate } from "./lib/dates.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const program = new Command();
+program
+    .name("worldcup")
+    .description(pkg.description)
+    .version(pkg.version, "-v, --version", "print the version")
+    .option("-d, --date <YYYY-MM-DD>", "show matches for a specific day")
+    .option("--refresh", "bypass the local cache and re-fetch from the data source")
+    .option("--no-color", "disable colored output")
+    .showHelpAfterError();
+// Honor --no-color (chalk already respects the NO_COLOR env var on its own).
+program.hook("preAction", (thisCommand) => {
+    if (thisCommand.opts().color === false)
+        chalk.level = 0;
+});
+// Bare `worldcup` shows help; `worldcup --date <day>` shows that day's matches.
+program.action(async () => {
+    const opts = program.opts();
+    if (!opts.date) {
+        program.help();
+        return;
+    }
+    if (!isValidISODate(opts.date)) {
+        process.stderr.write(chalk.red(`Invalid date "${opts.date}". Use YYYY-MM-DD.\n`));
+        process.exitCode = 1;
+        return;
+    }
+    await renderGames(opts.date, Boolean(opts.refresh));
+});
+registerToday(program);
+registerGroups(program);
+registerCountry(program);
+registerKnockout(program);
+program.addHelpText("after", `
+Examples:
+  $ worldcup today
+  $ worldcup --date 2026-06-11
+  $ worldcup groups --group A
+  $ worldcup country mexico
+  $ worldcup knockout --stage final
+
+Data: openfootball/worldcup.json (public domain). Cached at ~/.worldcup-cli/.`);
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(chalk.red((err instanceof Error ? err.message : String(err)) + "\n"));
+    process.exitCode = 1;
+});

package/dist/lib/dates.js

@@ -0,0 +1,27 @@
+/** Return today's date as a local "YYYY-MM-DD" string. */
+export function todayISO() {
+    const now = new Date();
+    const y = now.getFullYear();
+    const m = String(now.getMonth() + 1).padStart(2, "0");
+    const d = String(now.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+/** Validate a user-supplied "YYYY-MM-DD" string (loosely). */
+export function isValidISODate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const d = new Date(`${value}T00:00:00`);
+    return !Number.isNaN(d.getTime());
+}
+/** Human-friendly date label, e.g. "Thu, Jun 11 2026". */
+export function formatDate(iso) {
+    const d = new Date(`${iso}T00:00:00`);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return d.toLocaleDateString("en-US", {
+        weekday: "short",
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+    });
+}

package/dist/lib/format.js

@@ -0,0 +1,82 @@
+import chalk from "chalk";
+import { teamCode, teamFlag } from "../data/flags.js";
+import { isPlayed, matchWinner } from "./standings.js";
+import { formatDate } from "./dates.js";
+/** Build the "2 - 1" score with extra-time / penalty annotations. */
+export function scoreString(match) {
+    const s = match.score;
+    if (!s?.ft)
+        return "";
+    const base = `${s.ft[0]} - ${s.ft[1]}`;
+    if (s.p)
+        return `${base} (${s.p[0]}-${s.p[1]} pens)`;
+    if (s.et)
+        return `${base} (a.e.t.)`;
+    return base;
+}
+/**
+ * Render a single match on one line.
+ *   - Played:  🇲🇽 Mexico        2 - 1  South Africa 🇿🇦  (FT)
+ *   - Fixture: 🇲🇽 Mexico         vs   South Africa 🇿🇦  · 13:00 UTC-6 @ Mexico City
+ */
+export function matchLine(match) {
+    const left = `${teamFlag(match.team1)} ${match.team1}`;
+    const right = `${match.team2} ${teamFlag(match.team2)}`;
+    if (isPlayed(match)) {
+        const w = matchWinner(match);
+        const leftStyled = w === 1 ? chalk.green.bold(left) : w === 2 ? chalk.dim(left) : left;
+        const rightStyled = w === 2 ? chalk.green.bold(right) : w === 1 ? chalk.dim(right) : right;
+        const score = chalk.bold(scoreString(match));
+        return `${leftStyled.padEnd(28)} ${score}  ${rightStyled}  ${chalk.dim("(FT)")}`;
+    }
+    const when = [match.time, match.ground ? `@ ${match.ground}` : ""].filter(Boolean).join(" ");
+    return `${left.padEnd(28)} ${chalk.dim("vs")}  ${right}  ${chalk.dim("· " + when)}`;
+}
+/** A short header line, e.g. "── Group A ──". */
+export function header(text) {
+    return chalk.cyan.bold(`\n── ${text} ──`);
+}
+/**
+ * Render a group standings table. The top `qualify` rows are highlighted green
+ * (they advance directly); the rest are plain.
+ */
+export function standingsTable(rows, qualify = 2) {
+    const nameWidth = Math.max(4, ...rows.map((r) => r.team.length));
+    const head = chalk.dim(`  ${pad("Team", nameWidth)}  ${"P".padStart(2)} ${"W".padStart(2)} ${"D".padStart(2)} ${"L".padStart(2)} ${"GF".padStart(3)} ${"GA".padStart(3)} ${"GD".padStart(3)} ${"Pts".padStart(3)}`);
+    const lines = rows.map((r, i) => {
+        const rank = i + 1;
+        const cells = `  ${pad(r.team, nameWidth)}  ${num(r.played)} ${num(r.won)} ${num(r.drawn)} ${num(r.lost)} ` +
+            `${num(r.gf, 3)} ${num(r.ga, 3)} ${signed(r.gd)} ${num(r.points, 3)}`;
+        const marker = rank <= qualify ? chalk.green("▲") : " ";
+        const line = `${marker}${cells}`;
+        return rank <= qualify ? chalk.green(line) : line;
+    });
+    return [head, ...lines].join("\n");
+}
+function pad(s, width) {
+    return s.padEnd(width);
+}
+function num(n, width = 2) {
+    return String(n).padStart(width);
+}
+function signed(n) {
+    const s = n > 0 ? `+${n}` : String(n);
+    return s.padStart(3);
+}
+/** Title used at the top of each command's output. */
+export function title(text) {
+    return chalk.bold.white(text);
+}
+export function subtle(text) {
+    return chalk.dim(text);
+}
+/** Label like "Thu, Jun 11 2026 — Group A" for a match's context. */
+export function matchContext(match) {
+    const parts = [formatDate(match.date)];
+    if (match.group)
+        parts.push(match.group);
+    else
+        parts.push(match.round);
+    return chalk.dim(parts.join(" · "));
+}
+export { teamCode };

package/dist/lib/standings.js

@@ -0,0 +1,88 @@
+/** A match is "played" once it has a full-time score. */
+export function isPlayed(match) {
+    return Array.isArray(match.score?.ft);
+}
+/**
+ * Decide the result from a team1 perspective for the points/knockout winner.
+ * Penalties (`p`) trump extra time (`et`) which trumps full time (`ft`).
+ * Returns 1 (team1), 2 (team2), or 0 (draw — only possible at full time).
+ */
+export function matchWinner(match) {
+    const s = match.score;
+    if (!s)
+        return 0;
+    const decisive = s.p ?? s.et ?? s.ft;
+    if (!decisive)
+        return 0;
+    const [a, b] = decisive;
+    if (a > b)
+        return 1;
+    if (b > a)
+        return 2;
+    return 0;
+}
+/** All distinct group labels present in the data, sorted (Group A .. Group L). */
+export function listGroups(matches) {
+    const groups = new Set();
+    for (const m of matches)
+        if (m.group)
+            groups.add(m.group);
+    return [...groups].sort();
+}
+/** Group matches belonging to a single group label. */
+export function matchesInGroup(matches, group) {
+    return matches.filter((m) => m.group === group);
+}
+/**
+ * Compute a group's standings table from its played matches.
+ * Points: win = 3, draw = 1, loss = 0. Sorted by Points, then GD, then GF.
+ *
+ * Note: the official FIFA tiebreakers (head-to-head, fair play, drawing of
+ * lots) are simplified here to the common three — adequate for a CLI.
+ */
+export function computeStandings(matches, group) {
+    const rows = new Map();
+    const ensure = (team) => {
+        let row = rows.get(team);
+        if (!row) {
+            row = { team, played: 0, won: 0, drawn: 0, lost: 0, gf: 0, ga: 0, gd: 0, points: 0 };
+            rows.set(team, row);
+        }
+        return row;
+    };
+    for (const m of matchesInGroup(matches, group)) {
+        // Seed every fixture so teams with no result yet still appear.
+        ensure(m.team1);
+        ensure(m.team2);
+        if (!isPlayed(m) || !m.score?.ft)
+            continue;
+        const [g1, g2] = m.score.ft;
+        const r1 = ensure(m.team1);
+        const r2 = ensure(m.team2);
+        r1.played++;
+        r2.played++;
+        r1.gf += g1;
+        r1.ga += g2;
+        r2.gf += g2;
+        r2.ga += g1;
+        if (g1 > g2) {
+            r1.won++;
+            r2.lost++;
+            r1.points += 3;
+        }
+        else if (g2 > g1) {
+            r2.won++;
+            r1.lost++;
+            r2.points += 3;
+        }
+        else {
+            r1.drawn++;
+            r2.drawn++;
+            r1.points += 1;
+            r2.points += 1;
+        }
+    }
+    for (const row of rows.values())
+        row.gd = row.gf - row.ga;
+    return [...rows.values()].sort((a, b) => b.points - a.points || b.gd - a.gd || b.gf - a.gf || a.team.localeCompare(b.team));
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "worldcup26-cli",
+  "version": "0.1.0",
+  "description": "A colorful terminal CLI to follow the FIFA World Cup 2026 — today's games, group standings, country stats, and the knockout bracket.",
+  "type": "module",
+  "bin": {
+    "worldcup": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "worldcup",
+    "world-cup",
+    "2026",
+    "football",
+    "soccer",
+    "fifa",
+    "cli",
+    "terminal"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  }
+}