fplkit 1.4.1__tar.gz → 2.0.0__tar.gz

{fplkit-1.4.1 → fplkit-2.0.0}/.agents/TOOLS.md

@@ -27,8 +27,8 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
 | `status` | Show FPL gameweek status and upcoming deadlines | Yes | General | No | direct-api |
 | `fixtures` | Show fixtures for a gameweek | Yes | General | No | direct-api |
-| `player` | Look up a player's stats, xG, ownership and fixture run. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW); panel shows `xPts` (ep_next). `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
-| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Sortable by `ep_next`/`ep_this` (FPL predicted points); both in JSON output | Yes | General | No | direct-api |
+| `player` | Look up a player's stats, xG, ownership and fixture run. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
+| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Sortable by `ep_next`/`ep_this` (FPL predicted points); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction | Yes | General | No | direct-api |
 | `history` | Show historical player performance across seasons | Yes | General | No | direct-api |
 | `league` | Show live league standings for Classic and Draft leagues | No | General | No | direct-api |
 | `fdr` | Analyse fixture difficulty - easy runs, blanks, doubles | Yes | General | No | via-agent |

{fplkit-1.4.1 → fplkit-2.0.0}/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [1.4.2] - 2026-05-24
+
+### Bug Fixes
+
+- feat(scout): bind player clubs to current-season reference (#40)
+- feat(sell-prices refresh): Add retry logic to /api/me/ polling with hydration race handling (#39)
+
+### Scout
+
+- enforce player_reference as a strict allowlist (#41)
+
+## [1.4.1] - 2026-05-17
+
+### Refactoring
+
+- refactor FPL scraper to fetch API directly instead of intercepting (#37)
+
 ## [1.4.0] - 2026-05-17
 
 ### Bug Fixes
@@ -109,4 +126,3 @@ All notable changes to this project will be documented in this file.
 
 - CI pipeline and PyPI publish for v1.0.0 (#1)
 
-

{fplkit-1.4.1 → fplkit-2.0.0}/CLAUDE.md

@@ -3,7 +3,7 @@ fpl-cli - CLI tool for Fantasy Premier League analysis (classic + draft).
 
 ## Setup & Dev
 ```bash
-source .venv/bin/activate && pip install -e ".[dev]"
+source .venv/bin/activate && pip install -e ".[dev]"            # local only — web sessions install globally via setup script
 ruff check fpl_cli/            # Lint
 pyright fpl_cli/               # Type check
 pytest tests/                 # Tests

{fplkit-1.4.1 → fplkit-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fplkit
-Version: 1.4.1
+Version: 2.0.0
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli

{fplkit-1.4.1 → fplkit-2.0.0}/docs/command-reference.md

@@ -379,7 +379,7 @@ The FPL API provides gameweek point predictions for every player:
 | **ep_next** | FPL's predicted points for the next gameweek. Shown as `xPts` on the Points/PPG panel line. Available as a `--sort` field in `fpl stats`. |
 | **ep_this** | FPL's predicted points for the current gameweek (freezes after GW deadline, enabling predicted-vs-actual comparison with `event_points`). JSON only - not shown in the panel. |
 
-Both fields default to `0.0` for unavailable/injured players. In JSON output, they appear under `info.ep_next` and `info.ep_this` for `fpl player`, and as top-level record fields in `fpl stats --format json`.
+Both fields are `None` on the `Player` model when FPL provides no projection (e.g. unavailable/injured players, end of season). The Rich panel for `fpl player` omits the `xPts` segment of the Points line in that case, and the `fpl stats` table renders the cell as `—`. JSON output emits `null` when FPL provides no projection, so consumers can distinguish missing data from a genuine `0.0` projection — `info.ep_next`/`info.ep_this` for `fpl player`, and the top-level `ep_next`/`ep_this` record fields in `fpl stats --format json`.
 
 #### Player Detail Flags
 

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.1'
-__version_tuple__ = version_tuple = (1, 4, 1)
+__version__ = version = '2.0.0'
+__version_tuple__ = version_tuple = (2, 0, 0)
 
 __commit_id__ = commit_id = None

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/agents/data/scout.py

@@ -49,10 +49,16 @@ class ScoutAgent(Agent):
         Returns:
             Formatted position reference string.
         """
-        # Filter to relevant players: ownership > 1% OR form > 3 OR minutes > 500
+        # Filter to relevant players: ownership > 1% OR form > 3 OR minutes > 500.
+        # Also include any player with active news (e.g. injury return, late-fitness
+        # flags) so post-injury returnees with low minutes still appear in the
+        # reference and don't force the LLM to guess their club.
         relevant = [
             p for p in players
-            if p.selected_by_percent > 1.0 or p.form > 3.0 or p.minutes > 500
+            if p.selected_by_percent > 1.0
+            or p.form > 3.0
+            or p.minutes > 500
+            or bool(p.news)
         ]
 
         # Group by position

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/cli/_helpers.py

@@ -268,5 +268,9 @@ def _format_sort_value(field: str, value) -> str:
     if fmt == "pct":
         return f"{value:.1f}%"
     if field in _PLAYERS_FLOAT_FIELDS:
-        return f"{value:.1f}"
+        # Missing-data UX: render em dash. A table column can't be omitted
+        # per-row, so we substitute a visible placeholder. The Rich panel
+        # in `fpl player` drops the whole segment instead — different
+        # surface, different right answer.
+        return f"{value:.1f}" if value is not None else "—"
     return str(value)

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/cli/player.py

@@ -288,8 +288,8 @@ def player_command(
                                 "form": float(p.form),
                                 "total_points": p.total_points,
                                 "points_per_game": float(p.points_per_game),
-                                "ep_next": float(p.ep_next),
-                                "ep_this": float(p.ep_this),
+                                "ep_next": p.ep_next,
+                                "ep_this": p.ep_this,
                                 "goals_scored": p.goals_scored,
                                 "assists": p.assists,
                                 "expected_assists": float(p.expected_assists),
@@ -423,11 +423,19 @@ def player_command(
 
                     # Build panel lines conditionally
                     is_gk = p.position_name == "GK"
+                    # Missing-data UX: drop the xPts segment entirely. The panel is
+                    # a single-row free-form layout, so removing the label reads cleaner
+                    # than rendering "xPts: —". The stats table takes the opposite
+                    # approach (em dash) because per-row column omission isn't an option.
                     lines = [
                         f"[bold]{p.web_name}[/bold] ({p.full_name})",
                         f"Team: {team_name} | Position: {p.position_name}",
                         f"Price: £{p.price:.1f}m | Form: {p.form:.1f}",
-                        f"Points: {p.total_points} | PPG: {p.points_per_game:.1f} | xPts: {p.ep_next:.1f}",
+                        (
+                            f"Points: {p.total_points} | PPG: {p.points_per_game:.1f} | xPts: {p.ep_next:.1f}"
+                            if p.ep_next is not None
+                            else f"Points: {p.total_points} | PPG: {p.points_per_game:.1f}"
+                        ),
                     ]
                     rv, rc = rolling_scores.get(p.id, (None, None))
                     if rv is not None:

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/cli/stats.py

@@ -280,6 +280,8 @@ def stats_command(
                 effective_sort = "total_points"
 
             # Sort
+            # Null-scored players sort to bottom regardless of direction
+            bottom = float("-inf") if not reverse else float("inf")
             if effective_sort in _VALUE_SORT_FIELDS:
                 if effective_sort == "rolling_pts_per_m":
                     rolling_score_map: dict[int, float | None] = {
@@ -290,8 +292,6 @@ def stats_command(
                     score_map = quality_map
                 else:
                     score_map = value_map
-                # Null-scored players sort to bottom regardless of direction
-                bottom = float("-inf") if not reverse else float("inf")
 
                 def _value_key(p: Player) -> float:
                     v = score_map.get(p.id)
@@ -300,7 +300,12 @@ def stats_command(
                 filtered.sort(key=_value_key, reverse=not reverse)
             else:
                 attr = _SORT_FIELD_ALIASES.get(effective_sort, effective_sort)
-                filtered.sort(key=lambda p: getattr(p, attr), reverse=not reverse)
+
+                def _attr_key(p: Player) -> float:
+                    v = getattr(p, attr)
+                    return v if v is not None else bottom
+
+                filtered.sort(key=_attr_key, reverse=not reverse)
 
             # Limit
             filtered = filtered[:limit]
@@ -366,8 +371,8 @@ def stats_command(
                             "defensive_contribution_per_90": float(p.defensive_contribution_per_90),
                             "form_per_m": float(p.value_form),
                             "pts_per_m": float(p.value_season),
-                            "ep_next": float(p.ep_next),
-                            "ep_this": float(p.ep_this),
+                            "ep_next": p.ep_next,
+                            "ep_this": p.ep_this,
                             **(
                                 {
                                     "quality_score": quality_map.get(p.id),

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/models/player.py

@@ -90,8 +90,8 @@ class Player(BaseModel):
     expected_goals_conceded: float = Field(default=0.0, alias="expected_goals_conceded")
 
     # FPL predicted points
-    ep_next: float = 0.0
-    ep_this: float = 0.0
+    ep_next: float | None = None
+    ep_this: float | None = None
 
     # Defensive
     defensive_contribution: int = 0

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/prompts/scout.py

@@ -34,11 +34,16 @@ ALWAYS:
 - Flag confidence level (High/Medium/Low) based on source agreement and recency
 - Interpret signals for the user - don't just report raw quotes
 - Note when trusted voices disagree with mainstream opinion
+- Source every player's current club from the <player_reference> block - never infer it from prior-season knowledge
+- Treat <player_reference> as a strict allowlist: every player you name anywhere in the output (BUY tables, SELL tables, Differential Whispers, Contrarian Take) MUST appear in it
 
 NEVER:
 - Repeat statistical analysis (xG, form scores, PPG) - the user has this
 - Give generic advice without specific sourcing
 - Present rumour as fact without flagging uncertainty
+- Guess a player's club from memory; player transfers between seasons make prior knowledge unreliable
+- Surface players who are not in <player_reference>, even if community chatter mentions them - they are not in this season's FPL pool (likely transferred abroad, retired, or never were in the PL)
+- Emit placeholder rows like "PlayerX? — not listed in your FPL pool, so skipping". Silently exclude out-of-pool names instead; return fewer rows (or omit the section) rather than padding
 </rules>"""
 
 SCOUT_USER_PROMPT_TEMPLATE = """Surface qualitative FPL intelligence for Gameweek {gameweek}.
@@ -51,12 +56,21 @@ This query runs 24-30 hours before deadline, after most press conferences.
 3. Check r/FantasyPL for community momentum - who's being quietly accumulated, what the RMT thread is converging on
 4. Identify narrative breaks - players being over-sold or under-bought based on reactive sentiment
 5. Note any blank/double GW planning implications from @BenCrellin
+
+When scanning external sources, treat any player name you don't find in <player_reference> as out-of-pool: they're not in this season's FPL game (transferred abroad, retired, or wrong league) and must not appear anywhere in your output, even if the community is discussing them.
 </research_focus>
 
-<player_positions>
-IMPORTANT: Use this official FPL position reference when categorising players. Do NOT guess positions.
+<player_reference>
+Authoritative directory of player → (club, position) for THIS season, sourced from live FPL data. Each entry is formatted as `Name (CLUB)`.
+
+Use this as the ONLY source of truth for both:
+- The "Club" column in your output tables (clubs change between seasons; do NOT use prior-season knowledge)
+- The position grouping (DEF / MID / FWD)
+
+If a player you want to recommend is not listed here, either omit them or explicitly flag "club unknown" rather than guessing.
+
 {position_reference}
-</player_positions>
+</player_reference>
 
 <unavailable_players>
 CRITICAL: The following players are INJURED, SUSPENDED, or otherwise UNAVAILABLE according to current FPL data. Do NOT recommend any of these players under any circumstances, even if web sources suggest them (those sources may be outdated).
@@ -70,24 +84,24 @@ CRITICAL: The following players are INJURED, SUSPENDED, or otherwise UNAVAILABLE
 
 | Player | Club | Signal | Source | Confidence |
 |--------|------|--------|--------|------------|
-[2-3 players with qualitative buy signals - what do the watchers see that stats don't show yet?]
+[Up to 3 players from <player_reference> with qualitative buy signals - what do the watchers see that stats don't show yet? Fewer rows are fine; omit the section entirely if no one in the pool qualifies. Do NOT pad with out-of-pool names.]
 
 **MIDFIELDERS**
 
 | Player | Club | Signal | Source | Confidence |
 |--------|------|--------|--------|------------|
-[2-3 players with qualitative buy signals]
+[Up to 3 players from <player_reference> with qualitative buy signals. Fewer or zero is acceptable.]
 
 **FORWARDS**
 
 | Player | Club | Signal | Source | Confidence |
 |--------|------|--------|--------|------------|
-[1-2 players with qualitative buy signals]
+[Up to 2 players from <player_reference> with qualitative buy signals. Fewer or zero is acceptable.]
 
 ## SELL Signals
 | Player | Club | Signal Type | Detail | Confidence |
 |--------|------|-------------|--------|------------|
-[3-5 players to avoid - categorise as: Rotation Risk, Eye-Test Warning, or Narrative Trap]
+[Up to 5 players from <player_reference> to avoid - categorise as: Rotation Risk, Eye-Test Warning, or Narrative Trap. Fewer rows are fine; omit if no one qualifies.]
 
 ## Strategic Intel
 - **Blank/Double GW Watch:** Any planning implications from Ben Crellin or fixture news
@@ -100,7 +114,8 @@ CRITICAL: The following players are INJURED, SUSPENDED, or otherwise UNAVAILABLE
 - Confidence = High when multiple trusted sources agree + recent (last 48h); Medium when single source or older; Low when speculative/emerging
 - Prioritise actionable, time-sensitive intel over comprehensive coverage
 - If a trusted voice contradicts the crowd, highlight it
-- CRITICAL: Always check <player_positions> reference before assigning a player to DEFENDERS/MIDFIELDERS/FORWARDS
+- CRITICAL: Always check <player_reference> before filling the Club column or assigning a player to DEFENDERS/MIDFIELDERS/FORWARDS. The reference reflects current-season clubs; your prior knowledge does not.
+- CRITICAL: <player_reference> is the complete allowlist of in-pool players. If a name you're considering is not in it, drop the row — never emit "Player? — not in pool" placeholders, and never pad to hit a row count.
 </quality_requirements>"""
 
 

{fplkit-1.4.1 → fplkit-2.0.0}/fpl_cli/scraper/fpl_prices.py

@@ -217,27 +217,40 @@ class FPLPriceScraper:
             finally:
                 await browser.close()
 
+    # `or {}` on each step: FPL briefly returns {"player": null} in the post-login
+    # window before the session is fully hydrated. .get(key, {}) only defaults on
+    # missing keys, not on explicit nulls, so chain through `or {}` to be safe.
+    _ME_RETRY_ATTEMPTS = 5
+    _ME_RETRY_DELAY_MS = 1000
+
     async def _fetch_my_team(self, page) -> dict | None:
         """Fetch /api/me/ and /api/my-team/{id}/ from the authenticated session.
 
         Returns the my-team payload, or None if either call fails (in which case the
         caller falls back to DOM extraction).
         """
-        try:
-            me = await page.evaluate(
-                "async () => (await fetch('/api/me/', {credentials: 'include'})).json()"
-            )
-        except Exception as e:  # noqa: BLE001 — scraper resilience
-            logger.debug("Failed to fetch /api/me/: %s", e)
-            return None
+        me: dict | None = None
+        entry_id = None
+        for attempt in range(self._ME_RETRY_ATTEMPTS):
+            try:
+                me = await page.evaluate(
+                    "async () => (await fetch('/api/me/', {credentials: 'include'})).json()"
+                )
+            except Exception as e:  # noqa: BLE001 — scraper resilience
+                logger.debug("Failed to fetch /api/me/: %s", e)
+                return None
+            entry_id = ((me or {}).get("player") or {}).get("entry")
+            if entry_id:
+                break
+            if attempt < self._ME_RETRY_ATTEMPTS - 1:
+                await page.wait_for_timeout(self._ME_RETRY_DELAY_MS)
 
-        # `or {}` on each step: FPL briefly returns {"player": null} in the post-login
-        # window before the session is fully hydrated. .get(key, {}) only defaults on
-        # missing keys, not on explicit nulls, so chain through `or {}` to be safe.
-        player = (me or {}).get("player") or {}
-        entry_id = player.get("entry")
         if not entry_id:
-            logger.debug("No entry id in /api/me/ response: %s", me)
+            logger.debug(
+                "No entry id in /api/me/ after %d retries: %s",
+                self._ME_RETRY_ATTEMPTS,
+                me,
+            )
             return None
 
         try:
@@ -380,12 +393,22 @@ class FPLPriceScraper:
 
     async def _extract_finances(self, page, my_entry_response: dict | None = None) -> TeamFinances:
         """Extract financial data - tries intercepted API data first, falls back to DOM."""
-        if my_entry_response:
+        fallback_reason: str | None = None
+        if my_entry_response is None:
+            fallback_reason = (
+                "API /api/me/ returned no entry id after retries (post-login hydration race?)"
+            )
+        else:
             finances = await self._extract_from_intercepted(page, my_entry_response)
             if finances and not finances.is_suspect:
                 return finances
+            fallback_reason = (
+                "API /api/my-team/ returned no usable squad data; fell back to DOM extraction"
+            )
 
-        return await self._extract_via_dom(page)
+        finances = await self._extract_via_dom(page)
+        finances.extraction_errors.append(fallback_reason)
+        return finances
 
     async def _extract_from_intercepted(self, page, my_entry_response: dict) -> TeamFinances | None:
         """Build TeamFinances from intercepted /api/my-team/ response data."""

{fplkit-1.4.1 → fplkit-2.0.0}/tests/test_agents_data.py

@@ -1206,6 +1206,46 @@ Sources:
             assert isinstance(result.data["content_clean"], str)
             assert isinstance(result.data["citations"], list)
 
+    def test_build_position_reference_includes_news_flagged_players(self, agent):
+        """Low-minutes players with active news (e.g. injury returnees) must
+        appear in the reference so the LLM doesn't have to guess their club."""
+        from fpl_cli.models.player import PlayerPosition
+        from tests.conftest import make_player
+
+        # A defender just back from injury: low ownership, low form, low
+        # minutes — would be excluded by the old filter, but has news.
+        returnee = make_player(
+            id=99,
+            web_name="Returnee",
+            team_id=7,
+            position=PlayerPosition.DEFENDER,
+            selected_by_percent=0.3,
+            form=1.0,
+            minutes=120,
+            news="Back in training, hopeful for involvement",
+        )
+        ref = agent.build_position_reference([returnee], {7: "MCI"})
+        assert "Returnee (MCI)" in ref
+
+    def test_build_position_reference_excludes_irrelevant_players(self, agent):
+        """Players with no news, no minutes, no form, and tiny ownership
+        should still be excluded to keep the reference compact."""
+        from fpl_cli.models.player import PlayerPosition
+        from tests.conftest import make_player
+
+        irrelevant = make_player(
+            id=100,
+            web_name="Bench",
+            team_id=7,
+            position=PlayerPosition.DEFENDER,
+            selected_by_percent=0.1,
+            form=0.0,
+            minutes=0,
+            news="",
+        )
+        ref = agent.build_position_reference([irrelevant], {7: "MCI"})
+        assert "Bench" not in ref
+
     async def test_run_cleans_citations_correctly(self, agent):
         """Test that citations are properly cleaned from content."""
         response_with_citations = LLMResponse(

{fplkit-1.4.1 → fplkit-2.0.0}/tests/test_cli_format_suppression.py

@@ -248,8 +248,8 @@ class TestPlayerFormatSuppression:
         player.direct_freekicks_order = None
         player.defensive_contribution_per_90 = 0.0
         player.penalties_saved = 0
-        player.ep_next = 0.0
-        player.ep_this = 0.0
+        player.ep_next = None
+        player.ep_this = None
         return player
 
     def _mock_team(self):

{fplkit-1.4.1 → fplkit-2.0.0}/tests/test_cli_player.py

@@ -729,6 +729,50 @@ class TestPlayerQualityValueScores:
         assert "xPts: 8.5" in result.output
         assert "ep_this" not in result.output
 
+    def test_rich_panel_omits_ep_next_when_none(self):
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=None),
+        ])
+        result = _run([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        assert "xPts" not in result.output
+        # Rest of the Points line must still render — confirms only the xPts
+        # segment was dropped, not the entire row.
+        assert "Points:" in result.output
+        assert "PPG:" in result.output
+
+    def test_rich_panel_shows_ep_next_when_zero(self):
+        # Guards against a future `if p.ep_next:` regression that would
+        # swallow genuine 0.0 projections (distinct from None).
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=0.0),
+        ])
+        result = _run([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        assert "xPts: 0.0" in result.output
+
+    def test_json_ep_next_none_serialises_as_null(self):
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=None, ep_this=None),
+        ])
+        result = _run_json([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        info = json.loads(result.output)["data"][0]["info"]
+        assert info["ep_next"] is None
+        assert info["ep_this"] is None
+
     def test_gk_uses_without_xgi_weights(self):
         """GK quality_score should differ from MID due to without_xgi path."""
         client, fixture_agent, ratings_svc = _make_mocks()

{fplkit-1.4.1 → fplkit-2.0.0}/tests/test_cli_stats.py

@@ -235,6 +235,47 @@ class TestPlayersSort:
         assert result.exit_code == 0, result.output
         assert result.output.index("Fit") < result.output.index("Injured")
 
+    def test_sort_ep_next_none_sorts_to_bottom(self):
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+        assert result.output.index("HasValue") < result.output.index("NullEp")
+
+    def test_sort_ep_next_all_none_does_not_crash(self):
+        players = [
+            make_player(id=1, web_name="Alpha", team_id=1, ep_next=None),
+            make_player(id=2, web_name="Beta", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+
+    def test_sort_ep_next_none_sorts_to_bottom_in_ascending(self):
+        # --reverse activates the float("inf") sentinel branch of the sort
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next", "--reverse"], client=client)
+        assert result.exit_code == 0, result.output
+        assert result.output.index("HasValue") < result.output.index("NullEp")
+
+    def test_sort_ep_next_none_renders_em_dash_in_table(self):
+        # Exercises the _format_sort_value None -> "—" branch
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+        assert "—" in result.output
+
 
 class TestPlayersErrors:
     def test_invalid_team_shows_valid_options(self):
@@ -294,6 +335,21 @@ class TestPlayersJsonFormat:
         assert "Salah" in result.output
         assert result.output.strip()[0] != "["
 
+    def test_json_ep_next_none_serialises_as_null(self):
+        players = [
+            make_player(
+                id=1, web_name="NullEp", team_id=1,
+                position=PlayerPosition.MIDFIELDER,
+                ep_next=None, ep_this=None,
+            ),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--format", "json"], client=client)
+        assert result.exit_code == 0, result.output
+        record = json.loads(result.output)["data"][0]
+        assert record["ep_next"] is None
+        assert record["ep_this"] is None
+
 
 class TestStatsDraftOwnership:
     """Tests for auto-enabled draft ownership column based on format."""