fitzroy 1.1.1 → 1.2.0

package/dist/cli.js

@@ -1301,6 +1301,27 @@ var init_coaches_votes = __esm({
   }
 });
 
+// src/lib/concurrency.ts
+async function batchedMap(items, fn, options) {
+  const batchSize = options?.batchSize ?? 5;
+  const delayMs = options?.delayMs ?? 0;
+  const results = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+    if (delayMs > 0 && i + batchSize < items.length) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  return results;
+}
+var init_concurrency = __esm({
+  "src/lib/concurrency.ts"() {
+    "use strict";
+  }
+});
+
 // src/lib/validation.ts
 import { z } from "zod/v4";
 var AflApiTokenSchema, CompetitionSchema, CompetitionListSchema, CompseasonSchema, CompseasonListSchema, RoundSchema, RoundListSchema, ScoreSchema, PeriodScoreSchema, TeamScoreSchema, CfsMatchTeamSchema, CfsMatchSchema, CfsScoreSchema, CfsVenueSchema, MatchItemSchema, MatchItemListSchema, CfsPlayerInnerSchema, statNum, PlayerGameStatsSchema, PlayerStatsItemSchema, PlayerStatsListSchema, RosterPlayerSchema, TeamPlayersSchema, MatchRosterSchema, TeamItemSchema, TeamListSchema, SquadPlayerInnerSchema, SquadPlayerItemSchema, SquadSchema, SquadListSchema, WinLossRecordSchema, LadderEntryRawSchema, LadderResponseSchema;
@@ -1589,6 +1610,7 @@ var TOKEN_URL, API_BASE, CFS_BASE, AflApiClient;
 var init_afl_api = __esm({
   "src/sources/afl-api.ts"() {
     "use strict";
+    init_concurrency();
     init_errors();
     init_result();
     init_validation();
@@ -1599,6 +1621,7 @@ var init_afl_api = __esm({
       fetchFn;
       tokenUrl;
       cachedToken = null;
+      pendingAuth = null;
       constructor(options) {
         this.fetchFn = options?.fetchFn ?? globalThis.fetch;
         this.tokenUrl = options?.tokenUrl ?? TOKEN_URL;
@@ -1606,9 +1629,21 @@ var init_afl_api = __esm({
       /**
        * Authenticate with the WMCTok token endpoint and cache the token.
        *
+       * Concurrent callers share the same in-flight request to avoid
+       * redundant token fetches (thundering herd prevention).
+       *
        * @returns The access token on success, or an error Result.
        */
       async authenticate() {
+        if (this.pendingAuth) {
+          return this.pendingAuth;
+        }
+        this.pendingAuth = this.doAuthenticate().finally(() => {
+          this.pendingAuth = null;
+        });
+        return this.pendingAuth;
+      }
+      async doAuthenticate() {
         try {
           const response = await this.fetchFn(this.tokenUrl, {
             method: "POST",
@@ -1863,7 +1898,7 @@ var init_afl_api = __esm({
           return roundsResult;
         }
         const providerIds = roundsResult.data.flatMap((r) => r.providerId ? [r.providerId] : []);
-        const results = await Promise.all(providerIds.map((id) => this.fetchRoundMatchItems(id)));
+        const results = await batchedMap(providerIds, (id) => this.fetchRoundMatchItems(id));
         const allItems = [];
         for (const result of results) {
           if (!result.success) {
@@ -2221,8 +2256,9 @@ async function fetchFixture(query) {
   const roundProviderIds = roundsResult.data.flatMap(
     (r) => r.providerId ? [{ providerId: r.providerId, roundNumber: r.roundNumber }] : []
   );
-  const roundResults = await Promise.all(
-    roundProviderIds.map((r) => client.fetchRoundMatchItems(r.providerId))
+  const roundResults = await batchedMap(
+    roundProviderIds,
+    (r) => client.fetchRoundMatchItems(r.providerId)
   );
   const fixtures = [];
   for (let i = 0; i < roundResults.length; i++) {
@@ -2238,6 +2274,7 @@ async function fetchFixture(query) {
 var init_fixture = __esm({
   "src/api/fixture.ts"() {
     "use strict";
+    init_concurrency();
     init_errors();
     init_result();
     init_team_mapping();
@@ -3034,8 +3071,9 @@ async function fetchLineup(query) {
   if (matchItems.data.length === 0) {
     return err(new AflApiError(`No matches found for round ${query.round}`));
   }
-  const rosterResults = await Promise.all(
-    matchItems.data.map((item) => client.fetchMatchRoster(item.match.matchId))
+  const rosterResults = await batchedMap(
+    matchItems.data,
+    (item) => client.fetchMatchRoster(item.match.matchId)
   );
   const lineups = [];
   for (const rosterResult of rosterResults) {
@@ -3047,6 +3085,7 @@ async function fetchLineup(query) {
 var init_lineup2 = __esm({
   "src/api/lineup.ts"() {
     "use strict";
+    init_concurrency();
     init_errors();
     init_result();
     init_afl_api();
@@ -3365,8 +3404,9 @@ async function fetchPlayerStats(query) {
         teamIdMap.set(item.match.homeTeamId, item.match.homeTeam.name);
         teamIdMap.set(item.match.awayTeamId, item.match.awayTeam.name);
       }
-      const statsResults = await Promise.all(
-        matchItemsResult.data.map((item) => client.fetchPlayerStats(item.match.matchId))
+      const statsResults = await batchedMap(
+        matchItemsResult.data,
+        (item) => client.fetchPlayerStats(item.match.matchId)
       );
       const allStats = [];
       for (let i = 0; i < statsResults.length; i++) {
@@ -3434,6 +3474,7 @@ async function fetchPlayerStats(query) {
 var init_player_stats2 = __esm({
   "src/api/player-stats.ts"() {
     "use strict";
+    init_concurrency();
     init_errors();
     init_result();
     init_afl_api();
@@ -3556,6 +3597,94 @@ var init_index = __esm({
   }
 });
 
+// src/cli/flags.ts
+var SEASON_FLAG, OPTIONAL_SEASON_FLAG, ROUND_FLAG, REQUIRED_ROUND_FLAG, SOURCE_FLAG, COMPETITION_FLAG, OPTIONAL_COMPETITION_FLAG, OUTPUT_FLAGS, REQUIRED_TEAM_FLAG, TEAM_FLAG, PLAYER_FLAG;
+var init_flags = __esm({
+  "src/cli/flags.ts"() {
+    "use strict";
+    SEASON_FLAG = {
+      season: {
+        type: "string",
+        description: "Season year (e.g. 2025)",
+        required: true,
+        alias: "s"
+      }
+    };
+    OPTIONAL_SEASON_FLAG = {
+      season: {
+        type: "string",
+        description: "Season year (e.g. 2025)",
+        alias: "s"
+      }
+    };
+    ROUND_FLAG = {
+      round: {
+        type: "string",
+        description: "Round number",
+        alias: "r"
+      }
+    };
+    REQUIRED_ROUND_FLAG = {
+      round: {
+        type: "string",
+        description: "Round number",
+        required: true,
+        alias: "r"
+      }
+    };
+    SOURCE_FLAG = {
+      source: {
+        type: "string",
+        description: "Data source",
+        default: "afl-api"
+      }
+    };
+    COMPETITION_FLAG = {
+      competition: {
+        type: "string",
+        description: "Competition code (AFLM or AFLW)",
+        default: "AFLM",
+        alias: "c"
+      }
+    };
+    OPTIONAL_COMPETITION_FLAG = {
+      competition: {
+        type: "string",
+        description: "Competition code (AFLM or AFLW)",
+        alias: "c"
+      }
+    };
+    OUTPUT_FLAGS = {
+      json: { type: "boolean", description: "Output as JSON", alias: "j" },
+      csv: { type: "boolean", description: "Output as CSV" },
+      format: { type: "string", description: "Output format: table, json, csv" },
+      full: { type: "boolean", description: "Show all columns in table output" }
+    };
+    REQUIRED_TEAM_FLAG = {
+      team: {
+        type: "string",
+        description: "Team name, abbreviation, or ID (e.g. Carlton, CARL, 5)",
+        required: true,
+        alias: "t"
+      }
+    };
+    TEAM_FLAG = {
+      team: {
+        type: "string",
+        description: "Filter by team name",
+        alias: "t"
+      }
+    };
+    PLAYER_FLAG = {
+      player: {
+        type: "string",
+        description: "Filter by player name",
+        alias: "p"
+      }
+    };
+  }
+});
+
 // src/cli/formatters/csv.ts
 function escapeField(value) {
   if (value.includes(",") || value.includes('"') || value.includes("\n") || value.includes("\r")) {
@@ -3822,6 +3951,29 @@ function resolveTeamIdentifier(raw, teams) {
   const validNames = teams.map((t) => `${t.name} (${t.abbreviation})`).join(", ");
   throw new Error(`Unknown team: "${raw}" \u2014 valid teams are: ${validNames}`);
 }
+function resolveMatchByTeam(teamSearch, matchItems) {
+  const normalised = normaliseTeamName(teamSearch);
+  const lower = teamSearch.toLowerCase();
+  const matches = matchItems.filter((item) => {
+    const home = item.match.homeTeam.name;
+    const away = item.match.awayTeam.name;
+    return normaliseTeamName(home) === normalised || normaliseTeamName(away) === normalised || home.toLowerCase().includes(lower) || away.toLowerCase().includes(lower);
+  });
+  const singleMatch = matches[0];
+  if (matches.length === 1 && singleMatch) {
+    return singleMatch.match.matchId;
+  }
+  if (matches.length === 0) {
+    const available = matchItems.map((item) => `${item.match.homeTeam.name} vs ${item.match.awayTeam.name}`).join(", ");
+    throw new Error(
+      `No match found for "${teamSearch}" in this round. Available matches: ${available}`
+    );
+  }
+  const ambiguous = matches.map((item) => `${item.match.homeTeam.name} vs ${item.match.awayTeam.name}`).join(", ");
+  throw new Error(
+    `Multiple matches found for "${teamSearch}": ${ambiguous}. Please be more specific.`
+  );
+}
 var VALID_SOURCES, VALID_COMPETITIONS, VALID_FORMATS;
 var init_validation2 = __esm({
   "src/cli/validation.ts"() {
@@ -3844,6 +3996,7 @@ var init_matches = __esm({
   "src/cli/commands/matches.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
     init_ui();
     init_validation2();
@@ -3862,18 +4015,11 @@ var init_matches = __esm({
         description: "Fetch match results for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        round: { type: "string", description: "Round number" },
-        source: { type: "string", description: "Data source", default: "afl-api" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...ROUND_FLAG,
+        ...SOURCE_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
@@ -3903,6 +4049,203 @@ var init_matches = __esm({
   }
 });
 
+// src/lib/fuzzy.ts
+function levenshteinDistance(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  if (la === 0) return lb;
+  if (lb === 0) return la;
+  if (la < lb) return levenshteinDistance(b, a);
+  const row = Array.from({ length: lb + 1 }, (_, i) => i);
+  for (let i = 1; i <= la; i++) {
+    let prev = i;
+    for (let j = 1; j <= lb; j++) {
+      const current = row[j - 1];
+      const rowJ = row[j];
+      if (current === void 0 || rowJ === void 0) continue;
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(rowJ + 1, prev + 1, current + cost);
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[lb] = prev;
+  }
+  return row[lb] ?? 0;
+}
+function fuzzySearch(query, candidates, keySelector, options) {
+  const maxResults = options?.maxResults ?? 10;
+  const threshold = options?.threshold ?? 0.4;
+  const lowerQuery = query.toLowerCase();
+  const results = [];
+  for (const item of candidates) {
+    const key = keySelector(item).toLowerCase();
+    if (key === lowerQuery) {
+      results.push({ item, score: 0 });
+      continue;
+    }
+    if (key.startsWith(lowerQuery)) {
+      results.push({ item, score: 0.1 });
+      continue;
+    }
+    if (key.includes(lowerQuery)) {
+      results.push({ item, score: 0.3 });
+      continue;
+    }
+    const maxLen = Math.max(lowerQuery.length, key.length);
+    if (maxLen === 0) continue;
+    const distance = levenshteinDistance(lowerQuery, key);
+    const normalised = distance / maxLen;
+    if (normalised <= threshold) {
+      const score = 0.4 + normalised / threshold * 0.6;
+      results.push({ item, score });
+    }
+  }
+  results.sort((a, b) => {
+    if (a.score !== b.score) return a.score - b.score;
+    return keySelector(a.item).localeCompare(keySelector(b.item));
+  });
+  return results.slice(0, maxResults);
+}
+var init_fuzzy = __esm({
+  "src/lib/fuzzy.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/resolvers.ts
+import { isCancel, select } from "@clack/prompts";
+async function resolveTeamOrPrompt(query, teams) {
+  try {
+    return resolveTeamIdentifier(query, teams);
+  } catch {
+  }
+  const matches = fuzzySearch(query.trim(), teams, (t) => t.name, {
+    maxResults: 5,
+    threshold: 0.4
+  });
+  const abbrevMatches = fuzzySearch(query.trim(), teams, (t) => t.abbreviation, {
+    maxResults: 5,
+    threshold: 0.4
+  });
+  const seen = new Set(matches.map((m) => m.item.teamId));
+  for (const m of abbrevMatches) {
+    if (!seen.has(m.item.teamId)) {
+      matches.push(m);
+      seen.add(m.item.teamId);
+    }
+  }
+  matches.sort((a, b) => a.score - b.score);
+  return disambiguate(
+    query.trim(),
+    matches.map((m) => ({ value: m.item.teamId, label: m.item.name, score: m.score })),
+    teams.map((t) => `${t.name} (${t.abbreviation})`),
+    "team"
+  );
+}
+async function resolveTeamNameOrPrompt(query, teamNames) {
+  const trimmed = query.trim();
+  const canonical = normaliseTeamName(trimmed);
+  const candidates = teamNames ?? [...AFL_SENIOR_TEAMS];
+  if (candidates.includes(canonical)) {
+    return canonical;
+  }
+  const items = candidates.map((name) => ({ name }));
+  const matches = fuzzySearch(trimmed, items, (t) => t.name, {
+    maxResults: 5,
+    threshold: 0.4
+  });
+  return disambiguate(
+    trimmed,
+    matches.map((m) => ({ value: m.item.name, label: m.item.name, score: m.score })),
+    candidates,
+    "team"
+  );
+}
+async function resolveMatchOrPrompt(query, matchItems) {
+  try {
+    return resolveMatchByTeam(query, matchItems);
+  } catch {
+  }
+  const labelledItems = matchItems.map((item) => ({
+    item,
+    label: `${item.match.homeTeam.name} vs ${item.match.awayTeam.name}`
+  }));
+  const matches = fuzzySearch(query, labelledItems, (l) => l.label, {
+    maxResults: 5,
+    threshold: 0.5
+  });
+  const homeMatches = fuzzySearch(query, matchItems, (i) => i.match.homeTeam.name, {
+    maxResults: 5,
+    threshold: 0.4
+  });
+  const awayMatches = fuzzySearch(query, matchItems, (i) => i.match.awayTeam.name, {
+    maxResults: 5,
+    threshold: 0.4
+  });
+  const seen = new Set(matches.map((m) => m.item.item.match.matchId));
+  for (const m of homeMatches) {
+    if (!seen.has(m.item.match.matchId)) {
+      const label = `${m.item.match.homeTeam.name} vs ${m.item.match.awayTeam.name}`;
+      matches.push({ item: { item: m.item, label }, score: m.score });
+      seen.add(m.item.match.matchId);
+    }
+  }
+  for (const m of awayMatches) {
+    if (!seen.has(m.item.match.matchId)) {
+      const label = `${m.item.match.homeTeam.name} vs ${m.item.match.awayTeam.name}`;
+      matches.push({ item: { item: m.item, label }, score: m.score });
+      seen.add(m.item.match.matchId);
+    }
+  }
+  matches.sort((a, b) => a.score - b.score);
+  const available = matchItems.map(
+    (item) => `${item.match.homeTeam.name} vs ${item.match.awayTeam.name}`
+  );
+  return disambiguate(
+    query,
+    matches.map((m) => ({
+      value: m.item.item.match.matchId,
+      label: m.item.label,
+      score: m.score
+    })),
+    available,
+    "match"
+  );
+}
+async function disambiguate(query, options, allLabels, entityName) {
+  const best = options[0];
+  if (!best) {
+    throw new Error(
+      `No ${entityName} found for "${query}". Valid options: ${allLabels.join(", ")}`
+    );
+  }
+  if (best.score < 0.2 || options.length === 1) {
+    return best.value;
+  }
+  if (isTTY2) {
+    const choice = await select({
+      message: `Multiple ${entityName}s matched "${query}". Which did you mean?`,
+      options: options.map((o) => ({ value: o.value, label: o.label }))
+    });
+    if (isCancel(choice)) {
+      process.exit(0);
+    }
+    return choice;
+  }
+  console.error(`Matched "${query}" \u2192 ${best.label}`);
+  return best.value;
+}
+var isTTY2;
+var init_resolvers = __esm({
+  "src/cli/resolvers.ts"() {
+    "use strict";
+    init_fuzzy();
+    init_team_mapping();
+    init_validation2();
+    isTTY2 = process.stdout.isTTY === true;
+  }
+});
+
 // src/cli/commands/stats.ts
 var stats_exports = {};
 __export(stats_exports, {
@@ -3914,7 +4257,11 @@ var init_stats = __esm({
   "src/cli/commands/stats.ts"() {
     "use strict";
     init_index();
+    init_fuzzy();
+    init_afl_api();
+    init_flags();
     init_formatters();
+    init_resolvers();
     init_ui();
     init_validation2();
     DEFAULT_COLUMNS2 = [
@@ -3932,27 +4279,32 @@ var init_stats = __esm({
         description: "Fetch player statistics for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        round: { type: "string", description: "Round number" },
-        "match-id": { type: "string", description: "Specific match ID" },
-        source: { type: "string", description: "Data source", default: "afl-api" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...ROUND_FLAG,
+        match: { type: "string", description: "Filter by team name to find a specific match" },
+        "match-id": { type: "string", description: "Specific match provider ID (advanced)" },
+        ...SOURCE_FLAG,
+        ...COMPETITION_FLAG,
+        ...PLAYER_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
         const round = args.round ? validateRound(args.round) : void 0;
-        const matchId = args["match-id"];
         const source = validateSource(args.source);
         const competition = validateCompetition(args.competition);
         const format = validateFormat(args.format);
+        let matchId = args["match-id"];
+        if (!matchId && args.match && round != null) {
+          const client = new AflApiClient();
+          const seasonResult = await client.resolveCompSeason(competition, season);
+          if (!seasonResult.success) throw seasonResult.error;
+          const itemsResult = await client.fetchRoundMatchItemsByNumber(seasonResult.data, round);
+          if (!itemsResult.success) throw itemsResult.error;
+          matchId = await resolveMatchOrPrompt(args.match, itemsResult.data);
+        } else if (args.match && round == null) {
+          throw new Error("--match requires --round (-r) to identify which round to search.");
+        }
         const result = await withSpinner(
           "Fetching player stats\u2026",
           () => fetchPlayerStats({ source, season, round, matchId, competition })
@@ -3960,7 +4312,14 @@ var init_stats = __esm({
         if (!result.success) {
           throw result.error;
         }
-        const data = result.data;
+        let data = result.data;
+        if (args.player) {
+          const playerMatches = fuzzySearch(args.player, data, (p) => p.displayName, {
+            maxResults: 50,
+            threshold: 0.4
+          });
+          data = playerMatches.map((m) => m.item);
+        }
         showSummary(
           `Loaded ${data.length} player stat lines for ${season}${round ? ` round ${round}` : ""}`
         );
@@ -3988,6 +4347,7 @@ var init_fixture2 = __esm({
   "src/cli/commands/fixture.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
     init_ui();
     init_validation2();
@@ -4004,18 +4364,11 @@ var init_fixture2 = __esm({
         description: "Fetch fixture/schedule for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        round: { type: "string", description: "Round number" },
-        source: { type: "string", description: "Data source", default: "afl-api" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...ROUND_FLAG,
+        ...SOURCE_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
@@ -4056,6 +4409,7 @@ var init_ladder3 = __esm({
   "src/cli/commands/ladder.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
     init_ui();
     init_validation2();
@@ -4074,18 +4428,11 @@ var init_ladder3 = __esm({
         description: "Fetch ladder standings for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        round: { type: "string", description: "Round number" },
-        source: { type: "string", description: "Data source", default: "afl-api" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...ROUND_FLAG,
+        ...SOURCE_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
@@ -4150,7 +4497,10 @@ var init_lineup3 = __esm({
   "src/cli/commands/lineup.ts"() {
     "use strict";
     init_index();
+    init_afl_api();
+    init_flags();
     init_formatters();
+    init_resolvers();
     init_ui();
     init_validation2();
     DEFAULT_COLUMNS5 = [
@@ -4166,27 +4516,29 @@ var init_lineup3 = __esm({
         description: "Fetch match lineups for a round"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        round: { type: "string", description: "Round number", required: true },
-        "match-id": { type: "string", description: "Specific match ID" },
-        source: { type: "string", description: "Data source", default: "afl-api" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...REQUIRED_ROUND_FLAG,
+        match: { type: "string", description: "Filter by team name to find a specific match" },
+        "match-id": { type: "string", description: "Specific match provider ID (advanced)" },
+        ...SOURCE_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
         const round = validateRound(args.round);
-        const matchId = args["match-id"];
         const source = validateSource(args.source);
         const competition = validateCompetition(args.competition);
         const format = validateFormat(args.format);
+        let matchId = args["match-id"];
+        if (!matchId && args.match) {
+          const client = new AflApiClient();
+          const seasonResult = await client.resolveCompSeason(competition, season);
+          if (!seasonResult.success) throw seasonResult.error;
+          const itemsResult = await client.fetchRoundMatchItemsByNumber(seasonResult.data, round);
+          if (!itemsResult.success) throw itemsResult.error;
+          matchId = await resolveMatchOrPrompt(args.match, itemsResult.data);
+        }
         const result = await withSpinner(
           "Fetching lineups\u2026",
           () => fetchLineup({ source, season, round, matchId, competition })
@@ -4225,7 +4577,9 @@ var init_squad = __esm({
   "src/cli/commands/squad.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
+    init_resolvers();
     init_ui();
     init_validation2();
     DEFAULT_COLUMNS6 = [
@@ -4241,34 +4595,22 @@ var init_squad = __esm({
         description: "Fetch team squad for a season"
       },
       args: {
-        "team-id": {
-          type: "string",
-          description: "Team ID, abbreviation, or name (e.g. 5, CARL, Carlton)",
-          required: true
-        },
-        season: { type: "string", description: "Season year (e.g. 2025)", required: true },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...REQUIRED_TEAM_FLAG,
+        ...SEASON_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
         const competition = validateCompetition(args.competition);
         const format = validateFormat(args.format);
-        let teamId = args["team-id"].trim();
-        const isNumeric = /^\d+$/.test(teamId);
-        if (!isNumeric) {
+        let teamId = args.team.trim();
+        if (!/^\d+$/.test(teamId)) {
           const teamsResult = await withSpinner("Resolving team\u2026", () => fetchTeams({ competition }));
           if (!teamsResult.success) {
             throw teamsResult.error;
           }
-          teamId = resolveTeamIdentifier(args["team-id"], teamsResult.data);
+          teamId = await resolveTeamOrPrompt(args.team, teamsResult.data);
         }
         const result = await withSpinner(
           "Fetching squad\u2026",
@@ -4303,6 +4645,7 @@ var init_teams2 = __esm({
   "src/cli/commands/teams.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
     init_ui();
     init_validation2();
@@ -4318,12 +4661,9 @@ var init_teams2 = __esm({
         description: "Fetch team list"
       },
       args: {
-        competition: { type: "string", description: "Competition code (AFLM or AFLW)" },
+        ...OPTIONAL_COMPETITION_FLAG,
         "team-type": { type: "string", description: "Team type filter" },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const competition = validateOptionalCompetition(args.competition);
@@ -4372,6 +4712,7 @@ var init_team_stats2 = __esm({
   "src/cli/commands/team-stats.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
     init_ui();
     init_validation2();
@@ -4393,17 +4734,14 @@ var init_team_stats2 = __esm({
         description: "Fetch team aggregate statistics for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2024)", required: true },
+        ...SEASON_FLAG,
         source: {
           type: "string",
           description: "Data source (footywire, afl-tables)",
           default: "footywire"
         },
         summary: { type: "string", description: "Summary type: totals or averages", default: "totals" },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
@@ -4444,7 +4782,9 @@ var init_player_details2 = __esm({
   "src/cli/commands/player-details.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
+    init_resolvers();
     init_ui();
     init_validation2();
     DEFAULT_COLUMNS9 = [
@@ -4462,37 +4802,31 @@ var init_player_details2 = __esm({
         description: "Fetch player biographical details for a team"
       },
       args: {
-        team: { type: "positional", description: "Team name (e.g. Carlton, Hawthorn)", required: true },
+        ...REQUIRED_TEAM_FLAG,
         source: {
           type: "string",
           description: "Data source: afl-api, footywire, afl-tables",
           default: "afl-api"
         },
-        season: { type: "string", description: "Season year (for AFL API source, e.g. 2025)" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...OPTIONAL_SEASON_FLAG,
+        ...COMPETITION_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const source = validateSource(args.source);
         const competition = validateCompetition(args.competition);
         const format = validateFormat(args.format);
         const season = validateOptionalSeason(args.season) ?? resolveDefaultSeason(competition);
+        const team = await resolveTeamNameOrPrompt(args.team);
         const result = await withSpinner(
           "Fetching player details\u2026",
-          () => fetchPlayerDetails({ source, team: args.team, season, competition })
+          () => fetchPlayerDetails({ source, team, season, competition })
         );
         if (!result.success) {
           throw result.error;
         }
         const data = result.data;
-        showSummary(`Loaded ${data.length} players for ${args.team} (${source})`);
+        showSummary(`Loaded ${data.length} players for ${team} (${source})`);
         const formatOptions = {
           json: args.json,
           csv: args.csv,
@@ -4517,7 +4851,9 @@ var init_coaches_votes2 = __esm({
   "src/cli/commands/coaches-votes.ts"() {
     "use strict";
     init_index();
+    init_flags();
     init_formatters();
+    init_resolvers();
     init_ui();
     init_validation2();
     DEFAULT_COLUMNS10 = [
@@ -4534,33 +4870,27 @@ var init_coaches_votes2 = __esm({
         description: "Fetch AFLCA coaches votes for a season"
       },
       args: {
-        season: { type: "string", description: "Season year (e.g. 2024)", required: true },
-        round: { type: "string", description: "Round number" },
-        competition: {
-          type: "string",
-          description: "Competition code (AFLM or AFLW)",
-          default: "AFLM"
-        },
-        team: { type: "string", description: "Filter by team name" },
-        json: { type: "boolean", description: "Output as JSON" },
-        csv: { type: "boolean", description: "Output as CSV" },
-        format: { type: "string", description: "Output format: table, json, csv" },
-        full: { type: "boolean", description: "Show all columns in table output" }
+        ...SEASON_FLAG,
+        ...ROUND_FLAG,
+        ...COMPETITION_FLAG,
+        ...TEAM_FLAG,
+        ...OUTPUT_FLAGS
       },
       async run({ args }) {
         const season = validateSeason(args.season);
         const round = args.round ? validateRound(args.round) : void 0;
         const competition = validateCompetition(args.competition);
         const format = validateFormat(args.format);
+        const team = args.team ? await resolveTeamNameOrPrompt(args.team) : void 0;
         const result = await withSpinner(
           "Fetching coaches votes\u2026",
-          () => fetchCoachesVotes({ season, round, competition, team: args.team })
+          () => fetchCoachesVotes({ season, round, competition, team })
         );
         if (!result.success) {
           throw result.error;
         }
         const data = result.data;
-        const teamSuffix = args.team ? ` for ${args.team}` : "";
+        const teamSuffix = team ? ` for ${team}` : "";
         const roundSuffix = round ? ` round ${round}` : "";
         showSummary(`Loaded ${data.length} vote records for ${season}${roundSuffix}${teamSuffix}`);
         const formatOptions = {
@@ -4609,7 +4939,7 @@ ${issueLines.join("\n")}`;
 var main = defineCommand11({
   meta: {
     name: "fitzroy",
-    version: "1.1.1",
+    version: "1.2.0",
     description: "CLI for fetching AFL data \u2014 match results, player stats, fixtures, ladders, and more"
   },
   subCommands: {

package/dist/index.d.ts

@@ -1777,13 +1777,18 @@ declare class AflApiClient {
 	private readonly fetchFn;
 	private readonly tokenUrl;
 	private cachedToken;
+	private pendingAuth;
 	constructor(options?: AflApiClientOptions);
 	/**
 	* Authenticate with the WMCTok token endpoint and cache the token.
 	*
+	* Concurrent callers share the same in-flight request to avoid
+	* redundant token fetches (thundering herd prevention).
+	*
 	* @returns The access token on success, or an error Result.
 	*/
 	authenticate(): Promise<Result<string, AflApiError>>;
+	private doAuthenticate;
 	/**
 	* Whether the cached token is still valid (not expired).
 	*/

package/dist/index.js

@@ -1407,6 +1407,22 @@ async function fetchCoachesVotes(query) {
   return ok(votes);
 }
 
+// src/lib/concurrency.ts
+async function batchedMap(items, fn, options) {
+  const batchSize = options?.batchSize ?? 5;
+  const delayMs = options?.delayMs ?? 0;
+  const results = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+    if (delayMs > 0 && i + batchSize < items.length) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  return results;
+}
+
 // src/lib/validation.ts
 import { z } from "zod/v4";
 var AflApiTokenSchema = z.object({
@@ -1692,6 +1708,7 @@ var AflApiClient = class {
   fetchFn;
   tokenUrl;
   cachedToken = null;
+  pendingAuth = null;
   constructor(options) {
     this.fetchFn = options?.fetchFn ?? globalThis.fetch;
     this.tokenUrl = options?.tokenUrl ?? TOKEN_URL;
@@ -1699,9 +1716,21 @@ var AflApiClient = class {
   /**
    * Authenticate with the WMCTok token endpoint and cache the token.
    *
+   * Concurrent callers share the same in-flight request to avoid
+   * redundant token fetches (thundering herd prevention).
+   *
    * @returns The access token on success, or an error Result.
    */
   async authenticate() {
+    if (this.pendingAuth) {
+      return this.pendingAuth;
+    }
+    this.pendingAuth = this.doAuthenticate().finally(() => {
+      this.pendingAuth = null;
+    });
+    return this.pendingAuth;
+  }
+  async doAuthenticate() {
     try {
       const response = await this.fetchFn(this.tokenUrl, {
         method: "POST",
@@ -1956,7 +1985,7 @@ var AflApiClient = class {
       return roundsResult;
     }
     const providerIds = roundsResult.data.flatMap((r) => r.providerId ? [r.providerId] : []);
-    const results = await Promise.all(providerIds.map((id) => this.fetchRoundMatchItems(id)));
+    const results = await batchedMap(providerIds, (id) => this.fetchRoundMatchItems(id));
     const allItems = [];
     for (const result of results) {
       if (!result.success) {
@@ -2290,8 +2319,9 @@ async function fetchFixture(query) {
   const roundProviderIds = roundsResult.data.flatMap(
     (r) => r.providerId ? [{ providerId: r.providerId, roundNumber: r.roundNumber }] : []
   );
-  const roundResults = await Promise.all(
-    roundProviderIds.map((r) => client.fetchRoundMatchItems(r.providerId))
+  const roundResults = await batchedMap(
+    roundProviderIds,
+    (r) => client.fetchRoundMatchItems(r.providerId)
   );
   const fixtures = [];
   for (let i = 0; i < roundResults.length; i++) {
@@ -3042,8 +3072,9 @@ async function fetchLineup(query) {
   if (matchItems.data.length === 0) {
     return err(new AflApiError(`No matches found for round ${query.round}`));
   }
-  const rosterResults = await Promise.all(
-    matchItems.data.map((item) => client.fetchMatchRoster(item.match.matchId))
+  const rosterResults = await batchedMap(
+    matchItems.data,
+    (item) => client.fetchMatchRoster(item.match.matchId)
   );
   const lineups = [];
   for (const rosterResult of rosterResults) {
@@ -3334,8 +3365,9 @@ async function fetchPlayerStats(query) {
         teamIdMap.set(item.match.homeTeamId, item.match.homeTeam.name);
         teamIdMap.set(item.match.awayTeamId, item.match.awayTeam.name);
       }
-      const statsResults = await Promise.all(
-        matchItemsResult.data.map((item) => client.fetchPlayerStats(item.match.matchId))
+      const statsResults = await batchedMap(
+        matchItemsResult.data,
+        (item) => client.fetchPlayerStats(item.match.matchId)
       );
       const allStats = [];
       for (let i = 0; i < statsResults.length; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fitzroy",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "TypeScript library and CLI for AFL data — match results, player stats, fixtures, ladders, and more",
   "type": "module",
   "main": "./dist/index.js",