nhl-tui 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(gh pr:*)"
+    ]
+  }
+}

package/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run check
+
+      - name: Build
+        run: npm run build
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for contributing to `nhl-tui`.
+
+## Before You Open A PR
+
+Run:
+
+```bash
+npm run check
+npm run build
+```
+
+## Project Structure
+
+Keep the layering intact:
+
+- `src/api`: endpoint access only
+- `src/domain`: normalization, diffing, events, reducer logic
+- `src/ui`: Ink rendering and input dispatch only
+
+## Trademark And Content Guidance
+
+Please do not add:
+
+- NHL logos
+- team logos
+- league or club branding assets
+- broadcast audio or video
+- copyrighted media or artwork sourced from NHL properties
+
+The UI should use team abbreviations and text-based presentation only.
+
+## Design Constraints
+
+- keep the UI terminal-native and keyboard-first
+- prefer dense, stable layouts over web-style components
+- avoid leaking raw upstream payloads into the UI layer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean McCann
+
+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,222 @@
+# nhl-tui
+
+A terminal UI for following NHL games, built with TypeScript, Node.js, React, and Ink.
+
+`nhl-tui` is designed to feel like a real TUI, not a web dashboard squeezed into a terminal. It opens on a compact scoreboard, supports keyboard-first navigation, drills into live game detail, and keeps NHL-specific logic out of the rendering layer.
+
+## Status
+
+This is an early but usable v1.
+
+Current capabilities:
+
+- date-based scoreboard browsing
+- stable row selection
+- game detail view with summary, play-by-play, and box score tabs
+- adaptive polling for scoreboard and game detail
+- standings screen with conference playoff-cut grouping
+- leaders screen with top-10 skater and goalie stat tables
+- diff-based domain events for goals, game starts, period changes, and finals
+- queued goal banners
+- reducer-based state management with separate API, domain, and UI layers
+
+## Screens
+
+Scoreboard:
+
+- grouped by `LIVE`, `UPCOMING`, and `FINAL`
+- away and home team abbreviations
+- score and game state
+- live period and clock
+- scheduled puck drop time for upcoming games
+
+Game detail:
+
+- summary
+- play-by-play
+- box score
+
+Standings:
+
+- Eastern and Western conference sections
+- top three teams in each division
+- two conference wild card teams
+- teams below the wild card line
+
+Leaders:
+
+- skater leaders for points, goals, and assists
+- goalie leaders for goals against average, save percentage, and shutouts
+- top 10 rows per table
+
+The summary view includes scoring, penalties, and three stars. Where the upstream payload exposes enough information, player labels are rendered as sweater number plus short name, for example `97 C. McDavid`.
+
+## Quick Start
+
+### Requirements
+
+- Node.js 22+
+- network access to `https://api-web.nhle.com`
+
+### Run locally
+
+```bash
+npm install
+npm start
+```
+
+### Build the CLI
+
+```bash
+npm run build
+node dist/index.js
+```
+
+The package is configured with a `nhl-tui` bin entry for future npm publishing.
+
+## Releases
+
+GitHub Releases are automated with Actions on semantic-version tags. Pushing a tag such as `v0.1.0` runs typecheck and build, then creates a GitHub Release with generated notes.
+
+Example:
+
+```bash
+git checkout main
+git pull
+git tag v0.1.0
+git push origin main --tags
+```
+
+Version selection is still manual. The workflow only builds and publishes the GitHub Release after the tag exists.
+
+## Controls
+
+### Scoreboard
+
+- `up` / `down`: move selection
+- `left` / `right`: previous or next date
+- `g`: jump to top
+- `G`: jump to bottom
+- `enter`: open selected game
+- `s`: open standings
+- `l`: open leaders
+- `r`: manual refresh
+- `esc` or `q`: quit
+
+### Standings view
+
+- `esc`: back to scoreboard
+
+### Leaders view
+
+- `esc`: back to scoreboard
+
+### Game view
+
+- `left` / `right`: cycle tabs
+- `1`: summary
+- `2`: play-by-play
+- `3`: box score
+- `r`: manual refresh
+- `esc`: back to scoreboard
+- `q`: quit
+
+## Architecture
+
+The app is split into three layers:
+
+- `src/api`
+  Public endpoint access only.
+- `src/domain`
+  Stable types, normalization, diffing, event emission, and reducer logic.
+- `src/ui`
+  Ink components that render already-processed state and dispatch actions.
+
+Runtime flow:
+
+`fetch -> normalize -> diff -> emit events -> reducer -> Ink render`
+
+Ink is only the renderer. Components do not interpret raw upstream payloads.
+
+The data-fetching layer is intentionally isolated in `src/api` so endpoints can be swapped or replaced if upstream services change.
+
+## Data Sources And API Usage
+
+Game data is retrieved from publicly accessible endpoints used by NHL web applications.
+
+Current endpoint usage is isolated in `src/api/nhl.ts`:
+
+- `/v1/score/YYYY-MM-DD`
+- `/v1/standings/YYYY-MM-DD`
+- `/v1/skater-stats-leaders/current?categories=points,goals,assists&limit=10`
+- `/v1/goalie-stats-leaders/current?categories=goalsAgainstAverage,savePctg,shutouts&limit=10`
+- `/v1/gamecenter/{gameId}/landing`
+- `/v1/gamecenter/{gameId}/play-by-play`
+- `/v1/gamecenter/{gameId}/boxscore`
+
+No API key is currently required for these endpoints, but their availability and permitted use can change over time.
+
+The application uses adaptive polling to minimize load on upstream services. It limits requests to the current scoreboard date or the currently selected game, slows down aggressively when possible, and is intended for personal and educational use. The standings screen is fetched once per selected date and then served from in-memory state. The leaders screen is also fetched once and then served from in-memory state.
+
+## Legal And Trademark Considerations
+
+This project is not affiliated with, endorsed by, or sponsored by the National Hockey League.
+
+Additional safeguards and project conventions:
+
+- The UI uses team abbreviations only, not team logos or NHL branding assets.
+- The repository does not bundle NHL logos, team logos, broadcast assets, or other league branding materials.
+- This project does not stream NHL video, bundle broadcast media, or distribute copyrighted game footage or other copyrighted media.
+- `NHL`, team names, club names, logos, shields, and other league or team branding remain the property of their respective owners.
+- References to the league, clubs, players, and game data are for identification and informational use only.
+- This project is intended for personal and educational use. The MIT license applies to this source code, but it does not grant any rights to NHL trademarks, logos, or media.
+- Public NHL web endpoints and related terms may change or be restricted at any time, and this project should not be presented as an official NHL product or service.
+
+## Events
+
+Meaningful state transitions are detected in the domain layer by diffing normalized snapshots.
+
+Current event types:
+
+- `goal_scored`
+- `game_started`
+- `period_changed`
+- `game_ended`
+
+Goal events are surfaced through a queued banner system so multiple notifications do not overlap.
+
+## Development
+
+Useful commands:
+
+```bash
+npm start
+npm run check
+npm run build
+```
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+Before opening a PR, run:
+
+```bash
+npm run check
+npm run build
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor expectations, including trademark and branding restrictions.
+
+## Roadmap
+
+Likely next improvements:
+
+- play-by-play-id-based event detection instead of score-only goal diffs
+- additional domain events such as penalties, lead changes, and goalie pulls
+- optional sound hooks driven from emitted domain events
+- richer box score and play-by-play layouts
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](./LICENSE).

package/dist/api/nhl.js

@@ -0,0 +1,37 @@
+const BASE_URL = "https://api-web.nhle.com/v1";
+async function requestJson(path) {
+    const response = await fetch(`${BASE_URL}${path}`, {
+        headers: {
+            "user-agent": "nhl-tui/0.1.0",
+            accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`NHL API request failed: ${response.status} ${response.statusText} ${text}`.trim());
+    }
+    return response.json();
+}
+export class NhlApi {
+    async fetchScoreboard(scoreboardDate) {
+        return requestJson(`/score/${scoreboardDate}`);
+    }
+    async fetchStandings(scoreboardDate) {
+        return requestJson(`/standings/${scoreboardDate}`);
+    }
+    async fetchSkaterLeaders(limit = 10) {
+        return requestJson(`/skater-stats-leaders/current?categories=points,goals,assists&limit=${limit}`);
+    }
+    async fetchGoalieLeaders(limit = 10) {
+        return requestJson(`/goalie-stats-leaders/current?categories=goalsAgainstAverage,savePctg,shutouts&limit=${limit}`);
+    }
+    async fetchSummary(gameId) {
+        return requestJson(`/gamecenter/${gameId}/landing`);
+    }
+    async fetchPlayByPlay(gameId) {
+        return requestJson(`/gamecenter/${gameId}/play-by-play`);
+    }
+    async fetchBoxScore(gameId) {
+        return requestJson(`/gamecenter/${gameId}/boxscore`);
+    }
+}

package/dist/app/dates.js

@@ -0,0 +1,36 @@
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+function parseScoreboardDate(scoreboardDate) {
+    const [year, month, day] = scoreboardDate.split("-").map(Number);
+    return new Date(year, (month ?? 1) - 1, day ?? 1);
+}
+export function todayScoreboardDate(now = new Date()) {
+    return [now.getFullYear(), pad(now.getMonth() + 1), pad(now.getDate())].join("-");
+}
+export function shiftScoreboardDate(scoreboardDate, deltaDays) {
+    const nextDate = parseScoreboardDate(scoreboardDate);
+    nextDate.setDate(nextDate.getDate() + deltaDays);
+    return todayScoreboardDate(nextDate);
+}
+export function compareScoreboardDateToToday(scoreboardDate, now = new Date()) {
+    const today = todayScoreboardDate(now);
+    if (scoreboardDate < today) {
+        return -1;
+    }
+    if (scoreboardDate > today) {
+        return 1;
+    }
+    return 0;
+}
+export function formatScoreboardDateLabel(scoreboardDate, now = new Date()) {
+    const date = parseScoreboardDate(scoreboardDate);
+    const isToday = compareScoreboardDateToToday(scoreboardDate, now) === 0;
+    const parts = new Intl.DateTimeFormat(undefined, {
+        weekday: "short",
+        month: "short",
+        day: "numeric",
+        year: date.getFullYear() === now.getFullYear() ? undefined : "numeric",
+    }).format(date);
+    return isToday ? `Today  ${parts}` : parts;
+}

package/dist/app/input.js

@@ -0,0 +1,97 @@
+const gameTabs = ["summary", "pbp", "box"];
+function cycleGameTab(currentTab, direction) {
+    const currentIndex = gameTabs.indexOf(currentTab);
+    const nextIndex = (currentIndex + direction + gameTabs.length) % gameTabs.length;
+    return gameTabs[nextIndex] ?? currentTab;
+}
+export function handleAppInput(input, key, state, dispatch, quit) {
+    if (state.screen.type === "standings" || state.screen.type === "leaders") {
+        if (key.escape) {
+            dispatch({ type: "go_back" });
+            return;
+        }
+    }
+    if (input === "q") {
+        quit();
+        return;
+    }
+    if (state.screen.type === "scoreboard" && key.escape) {
+        quit();
+        return;
+    }
+    if (input === "r") {
+        if (state.screen.type !== "standings" && state.screen.type !== "leaders") {
+            dispatch({ type: "manual_refresh_requested" });
+        }
+        return;
+    }
+    if (input === "g") {
+        dispatch({ type: "jump_selection", target: "top" });
+        return;
+    }
+    if (input === "G") {
+        dispatch({ type: "jump_selection", target: "bottom" });
+        return;
+    }
+    if (state.screen.type === "scoreboard" && input === "s") {
+        dispatch({ type: "open_standings" });
+        return;
+    }
+    if (state.screen.type === "scoreboard" && input === "l") {
+        dispatch({ type: "open_leaders" });
+        return;
+    }
+    if (state.screen.type === "scoreboard") {
+        if (key.leftArrow) {
+            dispatch({ type: "change_scoreboard_date", delta: -1 });
+            return;
+        }
+        if (key.rightArrow) {
+            dispatch({ type: "change_scoreboard_date", delta: 1 });
+            return;
+        }
+    }
+    if (state.screen.type === "scoreboard" && key.upArrow) {
+        dispatch({ type: "move_selection", delta: -1 });
+        return;
+    }
+    if (state.screen.type === "scoreboard" && key.downArrow) {
+        dispatch({ type: "move_selection", delta: 1 });
+        return;
+    }
+    if (key.return && state.screen.type === "scoreboard") {
+        dispatch({ type: "open_selected_game" });
+        return;
+    }
+    if (state.screen.type === "game") {
+        if (key.escape) {
+            dispatch({ type: "go_back" });
+            return;
+        }
+        if (key.leftArrow) {
+            dispatch({
+                type: "set_tab",
+                tab: cycleGameTab(state.screen.tab, -1),
+            });
+            return;
+        }
+        if (key.rightArrow) {
+            dispatch({
+                type: "set_tab",
+                tab: cycleGameTab(state.screen.tab, 1),
+            });
+            return;
+        }
+        if (input === "1") {
+            dispatch({ type: "set_tab", tab: "summary" });
+            return;
+        }
+        if (input === "2") {
+            dispatch({ type: "set_tab", tab: "pbp" });
+            return;
+        }
+        if (input === "3") {
+            dispatch({ type: "set_tab", tab: "box" });
+        }
+    }
+}