@semanticintent/semantic-chirp-intelligence-mcp 3.1.0 → 4.0.0

package/build/services/LeagueDataService.js

@@ -0,0 +1,130 @@
+/**
+ * 🏒 League Data Service — league state from the store, in the shape analyses expect
+ *
+ * v3 read rosters from Yahoo and parsed them out of deeply nested, irregular
+ * fantasy JSON. v4 reads the same information from what the user pasted, and
+ * presents it in exactly the shape the existing analyses already consume — so
+ * the intelligence layer is untouched by the change of source.
+ *
+ * 🏛️ Rule 1 (Semantic Over Structural): analyses ask for "my roster", not for a
+ * provider's payload. Where that roster comes from is not their concern.
+ * 🏛️ Rule 3 (Observable Anchoring): when no roster has been provided, this
+ * reports that plainly. It never returns an empty roster that would read as
+ * "you have no players" rather than "you have not told me your players".
+ */
+import { ROSTER_STORE } from './RosterStore.js';
+import { NHL_STATS } from './NhlStatsService.js';
+/** Why a roster could not be produced, phrased for the person reading it. */
+export const NO_ROSTER_MESSAGE = 'No roster has been provided yet. Paste yours with `set_roster` — copy it from ' +
+    'any fantasy site, or just list the player names, one per line.';
+export const NO_OPPONENT_MESSAGE = 'No opponent roster has been provided. Paste one with `set_opponent_roster` to ' +
+    'enable head-to-head analysis.';
+export class LeagueDataService {
+    /**
+     * The user's roster, or null when none has been stored.
+     *
+     * Enriches each player with their current NHL club and eligible positions,
+     * so a roster pasted weeks ago still reflects trades and call-ups.
+     */
+    getRoster() {
+        return this.toLeagueRoster(ROSTER_STORE.getRoster('roster'), 'my-team');
+    }
+    /** The stored opponent roster, or null. */
+    getOpponentRoster() {
+        return this.toLeagueRoster(ROSTER_STORE.getRoster('opponent'), 'opponent-team');
+    }
+    hasRoster() {
+        return (ROSTER_STORE.getRoster('roster')?.players.length ?? 0) > 0;
+    }
+    hasOpponent() {
+        return (ROSTER_STORE.getRoster('opponent')?.players.length ?? 0) > 0;
+    }
+    getStandings() {
+        return ROSTER_STORE.getStandings();
+    }
+    /**
+     * Every NHL player not on the stored roster, as an analysis-shaped pool.
+     *
+     * This replaces the Yahoo free-agent list. It cannot know who is *available*
+     * in a given league — ownership is league-private — so it deliberately
+     * describes itself as "not on your roster" rather than "available". Callers
+     * must not present these as confirmed waiver adds.
+     */
+    getPlayerPool(options = {}) {
+        const owned = new Set((ROSTER_STORE.getRoster('roster')?.players ?? []).map(p => p.player_id));
+        const opponentOwned = new Set((ROSTER_STORE.getRoster('opponent')?.players ?? []).map(p => p.player_id));
+        // Fantasy platforms say LW/RW; the NHL says L/R.
+        const wanted = String(options.position ?? '').toUpperCase()
+            .replace(/^LW$/, 'L')
+            .replace(/^RW$/, 'R');
+        const pool = NHL_STATS.getAll()
+            .filter(p => !owned.has(p.player_id) && !opponentOwned.has(p.player_id))
+            .filter(p => !wanted || p.position === wanted)
+            .map(p => ({
+            player_id: p.player_id,
+            name: p.name,
+            position: this.eligiblePositions(p.position),
+            team: p.team,
+            selected_position: '',
+            status: '',
+            stats: p.stats,
+            // Kept for analyses written against Yahoo's ownership figure. There is
+            // no public equivalent, so it is explicitly null rather than a guess.
+            percent_owned: null
+        }));
+        pool.sort((a, b) => {
+            const av = a.position === 'G' ? (a.stats?.wins ?? 0) : (a.stats?.points ?? 0);
+            const bv = b.position === 'G' ? (b.stats?.wins ?? 0) : (b.stats?.points ?? 0);
+            return bv - av;
+        });
+        return options.limit ? pool.slice(0, options.limit) : pool;
+    }
+    /** Why a pool is not a waiver wire, in words a tool can print. */
+    static POOL_CAVEAT = 'These are NHL players not on the rosters you have provided, ranked by last ' +
+        'season production. Whether any of them is actually available in your league ' +
+        'is league-private and cannot be determined from public data — check before adding.';
+    toLeagueRoster(stored, keyPrefix) {
+        if (!stored || stored.players.length === 0)
+            return null;
+        return {
+            team_key: keyPrefix,
+            team_name: stored.label,
+            players: stored.players.map(p => this.toLeaguePlayer(p))
+        };
+    }
+    toLeaguePlayer(stored) {
+        // Re-resolve against the live index so a player traded since the paste
+        // reports their current club rather than a stale one.
+        const live = NHL_STATS.getById(stored.player_id);
+        const team = live?.team ?? stored.team;
+        const position = live?.position ?? stored.position;
+        return {
+            player_id: stored.player_id,
+            name: stored.name,
+            position: this.eligiblePositions(position),
+            team,
+            // A paste without slot information means the player is simply rostered;
+            // treat that as an active lineup spot rather than inventing a bench.
+            selected_position: stored.slot ?? position,
+            status: '',
+            stats: live?.stats
+        };
+    }
+    /**
+     * Map an NHL position code to fantasy-eligible positions.
+     *
+     * The NHL publishes L / R / C / D / G. Fantasy platforms speak LW / RW, and
+     * treat wingers as winger-eligible, so translate rather than pass through.
+     */
+    eligiblePositions(positionCode) {
+        switch (String(positionCode).toUpperCase()) {
+            case 'L': return 'LW';
+            case 'R': return 'RW';
+            case 'C': return 'C';
+            case 'D': return 'D';
+            case 'G': return 'G';
+            default: return positionCode || '';
+        }
+    }
+}
+export const LEAGUE_DATA = new LeagueDataService();

package/build/services/NhlScheduleService.js

@@ -0,0 +1,357 @@
+/**
+ * 🗓️ NHL Schedule Service
+ *
+ * The single source of real game-schedule truth for every analysis.
+ *
+ * Before this service existed, the schedule-aware tools estimated games with a
+ * constant (`players * 3.5 * weeks`) or invented them with `Math.random()`.
+ * Everything schedule-shaped now resolves through here, against the NHL's
+ * public club-schedule endpoint:
+ *
+ *   https://api-web.nhle.com/v1/club-schedule-season/{TRICODE}/{SEASON}
+ *
+ * No API key, no auth, ~8s for all 32 clubs cold, then served from a
+ * season-scoped disk cache.
+ *
+ * 🏛️ Rule 1 (Semantic Over Structural): callers ask domain questions
+ * ("how many games in this window?"), not HTTP questions.
+ * 🏛️ Rule 3 (Observable Anchoring): when the schedule cannot be loaded the
+ * service reports `available: false`. It never substitutes an estimate for a
+ * fact — an analysis that cannot see the schedule must say so.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { NHL_TRICODES, toNhlTricode } from '../domain/nhl-teams.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const NHL_API_BASE = 'https://api-web.nhle.com/v1';
+/** Regular season. Preseason is gameType 1, playoffs 3 — neither counts for fantasy. */
+const GAME_TYPE_REGULAR_SEASON = 2;
+/** Cache lifetime. The schedule shifts rarely (postponements), so a day is plenty. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export class NhlScheduleService {
+    schedules = new Map();
+    season = null;
+    loaded = false;
+    loadError = null;
+    inFlight = null;
+    strengths = new Map();
+    strengthsInFlight = null;
+    cacheDir;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir ?? path.join(__dirname, '..', '..', '.nhl-schedule-cache');
+    }
+    // ==========================================
+    // 🎯 Season resolution
+    // ==========================================
+    /**
+     * NHL season id for a date, e.g. 2026-09-01 -> "20262027".
+     * The season rolls over in August: anything from August onward belongs to the
+     * season that starts that calendar year.
+     */
+    static seasonForDate(date = new Date()) {
+        const year = date.getUTCFullYear();
+        const startYear = date.getUTCMonth() >= 7 ? year : year - 1; // month 7 = August
+        return `${startYear}${startYear + 1}`;
+    }
+    // ==========================================
+    // 🎯 Loading
+    // ==========================================
+    /**
+     * Load the full season schedule for all 32 clubs.
+     * Safe to call repeatedly — concurrent callers share one in-flight load.
+     */
+    async load(season) {
+        const target = season ?? NhlScheduleService.seasonForDate();
+        if (this.loaded && this.season === target)
+            return;
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this.performLoad(target).finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async performLoad(season) {
+        this.season = season;
+        this.loadError = null;
+        const cached = this.readCache(season);
+        if (cached) {
+            this.schedules = new Map(Object.entries(cached.teams));
+            this.loaded = true;
+            return;
+        }
+        const results = await Promise.all(NHL_TRICODES.map(async (team) => ({
+            team,
+            games: await this.fetchTeamSeason(team, season)
+        })));
+        const failed = results.filter(r => r.games === null).map(r => r.team);
+        // A partial schedule produces silently wrong comparisons between two teams,
+        // so treat any failure as a failed load rather than serving half the league.
+        if (failed.length > 0) {
+            this.loaded = false;
+            this.loadError =
+                `NHL schedule unavailable for ${failed.length} club(s): ${failed.join(', ')}`;
+            return;
+        }
+        this.schedules = new Map(results.map(r => [r.team, r.games]));
+        this.loaded = true;
+        this.writeCache(season);
+    }
+    async fetchTeamSeason(team, season) {
+        try {
+            const response = await fetch(`${NHL_API_BASE}/club-schedule-season/${team}/${season}`);
+            if (!response.ok)
+                return null;
+            const payload = await response.json();
+            const games = payload?.games ?? [];
+            return games
+                .filter(g => g?.gameType === GAME_TYPE_REGULAR_SEASON && g?.gameDate)
+                .map(g => {
+                const homeAbbr = toNhlTricode(g?.homeTeam?.abbrev);
+                const awayAbbr = toNhlTricode(g?.awayTeam?.abbrev);
+                const isHome = homeAbbr === team;
+                const opponent = isHome ? awayAbbr : homeAbbr;
+                return opponent
+                    ? { date: g.gameDate, opponent, home: isHome }
+                    : null;
+            })
+                .filter((g) => g !== null)
+                .sort((a, b) => a.date.localeCompare(b.date));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ==========================================
+    // 🎯 Availability — never fake a schedule
+    // ==========================================
+    /** Whether real schedule data is loaded and safe to reason from. */
+    isAvailable() {
+        return this.loaded && this.schedules.size === NHL_TRICODES.length;
+    }
+    /** Human-readable reason the schedule is unavailable, if it is. */
+    getUnavailableReason() {
+        if (this.isAvailable())
+            return null;
+        return this.loadError ?? 'NHL schedule has not been loaded yet';
+    }
+    getSeason() {
+        return this.season;
+    }
+    // ==========================================
+    // 🎯 Queries
+    // ==========================================
+    /** All regular-season games for a club, in date order. */
+    getTeamGames(abbr) {
+        const tricode = toNhlTricode(abbr);
+        if (!tricode)
+            return [];
+        return this.schedules.get(tricode) ?? [];
+    }
+    /** Games for a club within an inclusive YYYY-MM-DD date range. */
+    getGamesInRange(abbr, start, end) {
+        return this.getTeamGames(abbr).filter(g => g.date >= start && g.date <= end);
+    }
+    /** Game count for a club within an inclusive date range. */
+    countGamesInRange(abbr, start, end) {
+        return this.getGamesInRange(abbr, start, end).length;
+    }
+    /** Whether a club plays on a given YYYY-MM-DD date. */
+    hasGameOn(abbr, date) {
+        return this.getTeamGames(abbr).some(g => g.date === date);
+    }
+    /** Count of back-to-back game pairs for a club in a range. */
+    countBackToBacks(abbr, start, end) {
+        const games = this.getGamesInRange(abbr, start, end);
+        let count = 0;
+        for (let i = 1; i < games.length; i++) {
+            const previous = Date.parse(`${games[i - 1].date}T00:00:00Z`);
+            const current = Date.parse(`${games[i].date}T00:00:00Z`);
+            if (current - previous === 24 * 60 * 60 * 1000)
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Games per fantasy week for a club, keyed by the Monday that starts the week.
+     * Yahoo fantasy hockey weeks run Monday through Sunday.
+     */
+    getGamesByWeek(abbr) {
+        const byWeek = {};
+        for (const game of this.getTeamGames(abbr)) {
+            const monday = NhlScheduleService.weekStart(game.date);
+            byWeek[monday] = (byWeek[monday] ?? 0) + 1;
+        }
+        return byWeek;
+    }
+    /** Full season profile for one club. */
+    getTeamProfile(abbr) {
+        const tricode = toNhlTricode(abbr);
+        if (!tricode)
+            return null;
+        const games = this.getTeamGames(tricode);
+        const byWeek = this.getGamesByWeek(tricode);
+        const counts = Object.values(byWeek);
+        const firstDate = games[0]?.date ?? '';
+        const lastDate = games[games.length - 1]?.date ?? '';
+        return {
+            team: tricode,
+            total_games: games.length,
+            weeks_with_4_plus: counts.filter(c => c >= 4).length,
+            weeks_with_2_or_fewer: counts.filter(c => c <= 2).length,
+            back_to_backs: this.countBackToBacks(tricode, firstDate, lastDate),
+            games_by_week: byWeek
+        };
+    }
+    /**
+     * Earliest regular-season game date across the league (YYYY-MM-DD).
+     *
+     * Used as the fantasy week-1 anchor when Yahoo's league `start_date` is
+     * unavailable — fantasy hockey week 1 begins with the NHL season.
+     */
+    getSeasonStartDate() {
+        if (!this.isAvailable())
+            return null;
+        let earliest = null;
+        for (const games of this.schedules.values()) {
+            const first = games[0]?.date;
+            if (first && (earliest === null || first < earliest))
+                earliest = first;
+        }
+        return earliest;
+    }
+    /** Season profiles for all 32 clubs. */
+    getAllProfiles() {
+        return NHL_TRICODES
+            .map(t => this.getTeamProfile(t))
+            .filter((p) => p !== null);
+    }
+    /** The Monday (YYYY-MM-DD) that starts the fantasy week containing `date`. */
+    static weekStart(date) {
+        const d = new Date(`${date}T00:00:00Z`);
+        const dayOfWeek = (d.getUTCDay() + 6) % 7; // Monday = 0
+        d.setUTCDate(d.getUTCDate() - dayOfWeek);
+        return d.toISOString().split('T')[0];
+    }
+    /** Add `days` to a YYYY-MM-DD date, returning YYYY-MM-DD. */
+    static addDays(date, days) {
+        const d = new Date(`${date}T00:00:00Z`);
+        d.setUTCDate(d.getUTCDate() + days);
+        return d.toISOString().split('T')[0];
+    }
+    /** Today as YYYY-MM-DD (UTC). */
+    static today() {
+        return new Date().toISOString().split('T')[0];
+    }
+    // ==========================================
+    // 🎯 Opponent strength
+    // ==========================================
+    /**
+     * Load league-wide defensive strength from the NHL standings.
+     *
+     * Matchup difficulty used to be `Math.random() * 100`. This anchors it to
+     * goals allowed per game, ranked across the league. During the offseason the
+     * endpoint returns the last completed season, which is the right baseline for
+     * draft-time analysis anyway.
+     */
+    async loadStandings() {
+        if (this.strengths.size > 0)
+            return;
+        if (this.strengthsInFlight)
+            return this.strengthsInFlight;
+        this.strengthsInFlight = this.performStandingsLoad().finally(() => {
+            this.strengthsInFlight = null;
+        });
+        return this.strengthsInFlight;
+    }
+    async performStandingsLoad() {
+        try {
+            const response = await fetch(`${NHL_API_BASE}/standings/now`);
+            if (!response.ok)
+                return;
+            const payload = await response.json();
+            const rows = payload?.standings ?? [];
+            const parsed = rows
+                .map(row => {
+                const tricode = toNhlTricode(row?.teamAbbrev?.default ?? row?.teamAbbrev);
+                const gamesPlayed = Number(row?.gamesPlayed ?? 0);
+                if (!tricode || gamesPlayed <= 0)
+                    return null;
+                return {
+                    team: tricode,
+                    gaPerGame: Number(row?.goalAgainst ?? 0) / gamesPlayed,
+                    pointPctg: Number(row?.pointPctg ?? 0)
+                };
+            })
+                .filter((r) => r !== null);
+            if (parsed.length === 0)
+                return;
+            // Rank by goals allowed: the stingiest defence is the hardest matchup.
+            const ranked = [...parsed].sort((a, b) => a.gaPerGame - b.gaPerGame);
+            const lastIndex = Math.max(1, ranked.length - 1);
+            ranked.forEach((row, index) => {
+                this.strengths.set(row.team, {
+                    team: row.team,
+                    goals_against_per_game: Number(row.gaPerGame.toFixed(3)),
+                    point_pctg: row.pointPctg,
+                    difficulty: Math.round(100 - (index / lastIndex) * 100)
+                });
+            });
+        }
+        catch (error) {
+            console.error('[DEBUG] Could not load NHL standings:', error);
+        }
+    }
+    /** Whether opponent-strength data is loaded. */
+    hasStandings() {
+        return this.strengths.size > 0;
+    }
+    /** Defensive profile for a club, or null when standings are unavailable. */
+    getTeamStrength(abbr) {
+        const tricode = toNhlTricode(abbr);
+        if (!tricode)
+            return null;
+        return this.strengths.get(tricode) ?? null;
+    }
+    // ==========================================
+    // 🎯 Cache
+    // ==========================================
+    cachePath(season) {
+        return path.join(this.cacheDir, `${season}.json`);
+    }
+    readCache(season) {
+        try {
+            const file = this.cachePath(season);
+            if (!fs.existsSync(file))
+                return null;
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Date.now() - parsed.fetched_at > CACHE_TTL_MS)
+                return null;
+            if (Object.keys(parsed.teams ?? {}).length !== NHL_TRICODES.length)
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeCache(season) {
+        try {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+            const payload = {
+                season,
+                fetched_at: Date.now(),
+                teams: Object.fromEntries(this.schedules)
+            };
+            fs.writeFileSync(this.cachePath(season), JSON.stringify(payload));
+        }
+        catch (error) {
+            // A cache miss costs 8 seconds; it is never worth failing the analysis over.
+            console.error('[DEBUG] Could not write NHL schedule cache:', error);
+        }
+    }
+}
+/** Shared instance — one schedule load serves every analysis in the process. */
+export const NHL_SCHEDULE = new NhlScheduleService();