typefaster-cli 0.1.0__py3-none-any.whl

typefaster/net/token_store.py

@@ -0,0 +1,46 @@
+"""Local persistence of the auth token and server URL."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from ..infra.paths import config_dir
+
+
+def _auth_path() -> Path:
+    return config_dir() / "auth.json"
+
+
+@dataclass(slots=True)
+class Session:
+    server_url: str = "http://localhost:8000"
+    token: str | None = None
+    username: str | None = None
+
+    @property
+    def logged_in(self) -> bool:
+        return bool(self.token)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Session:
+        path = path or _auth_path()
+        if not path.exists():
+            return cls()
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return cls()
+        known = set(cls.__slots__)
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+    def save(self, path: Path | None = None) -> None:
+        path = path or _auth_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(self), indent=2), encoding="utf-8")
+
+    def clear(self, path: Path | None = None) -> None:
+        self.token = None
+        self.username = None
+        self.save(path)

typefaster/services/__init__.py

@@ -0,0 +1 @@
+"""Application services orchestrating the domain and infrastructure layers."""

typefaster/services/container.py

@@ -0,0 +1,42 @@
+"""Composition root — wires settings, repository, and services together."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..infra.config import Settings
+from ..infra.sqlite_repository import SQLiteRepository
+from .daily_service import DailyService
+from .ghost_service import GhostService
+from .profile_service import ProfileService
+from .race_service import RaceService
+from .stats_service import StatsService
+
+
+@dataclass(slots=True)
+class App:
+    settings: Settings
+    repo: SQLiteRepository
+    race: RaceService
+    profile: ProfileService
+    stats: StatsService
+    daily: DailyService
+    ghosts: GhostService
+
+    def close(self) -> None:
+        self.repo.close()
+
+
+def build_app(db_path: Path | str | None = None) -> App:
+    settings = Settings.load()
+    repo = SQLiteRepository(db_path)
+    return App(
+        settings=settings,
+        repo=repo,
+        race=RaceService(repo, allow_backspace=settings.allow_backspace),
+        profile=ProfileService(repo),
+        stats=StatsService(repo),
+        daily=DailyService(repo),
+        ghosts=GhostService(repo),
+    )

typefaster/services/daily_service.py

@@ -0,0 +1,23 @@
+"""Daily challenge: deterministic shared quote + local daily leaderboard."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from ..domain.models import DailyChallenge, RaceRecord
+from ..infra import quote_loader
+from ..infra.repository import Repository
+
+
+class DailyService:
+    def __init__(self, repo: Repository) -> None:
+        self._repo = repo
+
+    def today(self, day: date | None = None) -> DailyChallenge:
+        day = day or date.today()
+        quote = quote_loader.daily_quote(day)
+        return self._repo.get_or_create_daily(day.isoformat(), quote)
+
+    def leaderboard(self, day: date | None = None, limit: int = 20) -> list[RaceRecord]:
+        day = day or date.today()
+        return self._repo.daily_leaderboard(day.isoformat(), limit=limit)

typefaster/services/ghost_service.py

@@ -0,0 +1,50 @@
+"""Build ghost opponents from stored replays."""
+
+from __future__ import annotations
+
+from ..domain.errors import GhostUnavailableError
+from ..domain.models import Ghost, GhostKind
+from ..infra.repository import Repository
+
+_LABELS = {
+    GhostKind.PERSONAL_BEST: "PB",
+    GhostKind.LAST: "Last",
+    GhostKind.RANDOM: "Random",
+}
+
+
+class GhostService:
+    def __init__(self, repo: Repository) -> None:
+        self._repo = repo
+
+    def load(self, kind: GhostKind) -> Ghost:
+        """Return a ghost for the requested kind, or raise if no data exists."""
+        if kind is GhostKind.PERSONAL_BEST:
+            data = self._repo.personal_best_replay()
+        elif kind is GhostKind.LAST:
+            data = self._repo.last_replay()
+        else:
+            data = self._repo.random_replay()
+
+        if data is None:
+            raise GhostUnavailableError(
+                f"No historical run available for ghost '{kind.value}'. Finish a race first!"
+            )
+        timeline, wpm, quote = data
+        return Ghost(kind=kind, label=_LABELS[kind], timeline=timeline, wpm=wpm, quote=quote)
+
+    def best_for_quote(self, ext_id: str) -> Ghost | None:
+        """A ghost recorded on a specific quote (e.g. your best daily run)."""
+        data = self._repo.best_replay_for_quote(ext_id)
+        if data is None:
+            return None
+        timeline, wpm, quote = data
+        return Ghost(
+            kind=GhostKind.PERSONAL_BEST, label="PB", timeline=timeline, wpm=wpm, quote=quote
+        )
+
+    def try_load(self, kind: GhostKind) -> Ghost | None:
+        try:
+            return self.load(kind)
+        except GhostUnavailableError:
+            return None

typefaster/services/profile_service.py

@@ -0,0 +1,18 @@
+"""Profile read/repair operations."""
+
+from __future__ import annotations
+
+from ..domain.models import Profile
+from ..infra.repository import Repository
+
+
+class ProfileService:
+    def __init__(self, repo: Repository) -> None:
+        self._repo = repo
+
+    def get(self) -> Profile:
+        return self._repo.get_profile()
+
+    def repair(self) -> Profile:
+        """Recompute denormalized aggregates from the race table."""
+        return self._repo.recompute_profile()

typefaster/services/race_service.py

@@ -0,0 +1,152 @@
+"""Coordinate a race: choose the text/ghost/mode, then persist the result.
+
+The interactive typing loop lives in the UI layer (Textual), which drives a
+``TypingEngine``. This service handles everything around that: setup and
+persistence. Keeping it UI-free means the same flow can be reused headlessly
+(tests) and adapted server-side in Phase 2.
+
+Two race kinds (see ``RaceKind``):
+- QUOTE: one fixed quote, raced to completion. Ghosts (same text) live here.
+- TIME: type continuously for N seconds; text streams from many quotes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+
+from ..domain.models import Ghost, GhostKind, Quote, RaceKind, RaceMode, RaceResult
+from ..infra import quote_loader
+from ..infra.repository import Repository
+from .ghost_service import GhostService
+
+# Placeholder quote row that TIME-mode races reference (they have no single text).
+_TIME_QUOTE = Quote(ext_id="__time_mode__", text="(time mode)", source="Time")
+
+
+@dataclass(frozen=True, slots=True)
+class RaceConfig:
+    """A request to start a race (what the UI/CLI chooses)."""
+
+    kind: RaceKind = RaceKind.QUOTE
+    mode: RaceMode = RaceMode.NORMAL
+    ghost_kind: GhostKind | None = None
+    daily: bool = False
+
+
+@dataclass(slots=True)
+class RaceSetup:
+    quote: Quote  # the row persisted with the race
+    target_text: str  # what the player actually types (streamed for TIME mode)
+    kind: RaceKind
+    mode: RaceMode  # the time limit for TIME mode (ignored for QUOTE)
+    ghost: Ghost | None
+    allow_backspace: bool
+    is_daily: bool
+    started_at: str
+
+
+@dataclass(slots=True)
+class RaceSummary:
+    result: RaceResult
+    race_id: int
+    new_personal_best: bool
+    previous_best_wpm: float
+
+
+class RaceService:
+    def __init__(self, repo: Repository, *, allow_backspace: bool = True) -> None:
+        self._repo = repo
+        self._ghosts = GhostService(repo)
+        self._allow_backspace = allow_backspace
+
+    def prepare(
+        self,
+        *,
+        kind: RaceKind = RaceKind.QUOTE,
+        mode: RaceMode = RaceMode.NORMAL,
+        ghost_kind: GhostKind | None = None,
+        daily: bool = False,
+    ) -> RaceSetup:
+        if kind is RaceKind.TIME:
+            return self._prepare_time(mode)
+        return self._prepare_quote(mode, ghost_kind, daily)
+
+    def _prepare_quote(
+        self, mode: RaceMode, ghost_kind: GhostKind | None, daily: bool
+    ) -> RaceSetup:
+        ghost: Ghost | None = None
+        if daily:
+            quote = quote_loader.daily_quote(date.today())
+            # Daily ghost = your best run on *today's* quote (same text), if any.
+            ghost = self._ghosts.best_for_quote(quote.ext_id)
+        elif ghost_kind is not None:
+            # Explicit "vs PB/Last/Random": race the ghost's exact text for a
+            # fair head-to-head.
+            ghost = self._ghosts.try_load(ghost_kind)
+            quote = ghost.quote if ghost and ghost.quote else quote_loader.random_quote()
+        else:
+            # Quick race: a fresh random quote every time. Attach a ghost only
+            # if you've raced this exact quote before.
+            quote = quote_loader.random_quote()
+            ghost = self._ghosts.best_for_quote(quote.ext_id)
+
+        return RaceSetup(
+            quote=quote,
+            target_text=quote.text,
+            kind=RaceKind.QUOTE,
+            mode=mode,
+            ghost=ghost,
+            allow_backspace=self._allow_backspace,
+            is_daily=daily,
+            started_at=datetime.now(UTC).isoformat(),
+        )
+
+    def _prepare_time(self, mode: RaceMode) -> RaceSetup:
+        # Enough text that even a very fast typist won't run out before time:
+        # ~300 WPM * 5 chars = 1500 chars/min, plus a safety buffer.
+        target_chars = int(mode.value / 60 * 1500) + 600
+        text = _stream_text(target_chars)
+        return RaceSetup(
+            quote=_TIME_QUOTE,
+            target_text=text,
+            kind=RaceKind.TIME,
+            mode=mode,
+            ghost=None,  # ghosts are a QUOTE-mode feature
+            allow_backspace=self._allow_backspace,
+            is_daily=False,
+            started_at=datetime.now(UTC).isoformat(),
+        )
+
+    def finish(self, setup: RaceSetup, result: RaceResult) -> RaceSummary:
+        # Compare against the best of the *same* kind so the two don't mix.
+        previous_best = self._best_wpm_for_kind(result.kind)
+        race_id = self._repo.save_race(
+            result=result,
+            quote=setup.quote,
+            started_at=setup.started_at,
+            is_daily=setup.is_daily,
+        )
+        return RaceSummary(
+            result=result,
+            race_id=race_id,
+            new_personal_best=result.wpm > previous_best,
+            previous_best_wpm=previous_best,
+        )
+
+    def _best_wpm_for_kind(self, kind: RaceKind) -> float:
+        if kind is RaceKind.QUOTE:
+            best = self._repo.best_quote_run()
+            return best[0] if best else 0.0
+        return max(self._repo.best_by_mode(RaceKind.TIME).values(), default=0.0)
+
+
+def _stream_text(min_chars: int) -> str:
+    """Concatenate random quotes into one continuous block of >= min_chars."""
+    parts: list[str] = []
+    total = 0
+    while total < min_chars:
+        q = quote_loader.random_quote()
+        parts.append(q.text)
+        total += len(q.text) + 1
+    return " ".join(parts)

typefaster/services/stats_service.py

@@ -0,0 +1,52 @@
+"""Read-side aggregation for the stats / history / leaderboard screens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..domain.models import Profile, RaceKind, RaceRecord
+from ..infra.repository import Repository
+
+
+@dataclass(slots=True)
+class StatsSummary:
+    profile: Profile
+    avg_wpm: float
+    avg_accuracy: float
+    time_best_by_mode: dict[int, float]  # TIME mode: seconds -> best WPM
+    quote_best_wpm: float  # QUOTE mode: best WPM
+    quote_best_ms: int  # QUOTE mode: fastest completion (ms)
+    recent_wpm: list[float]
+
+
+class StatsService:
+    def __init__(self, repo: Repository) -> None:
+        self._repo = repo
+
+    def summary(self) -> StatsSummary:
+        profile = self._repo.get_profile()
+        avg_wpm, avg_acc = self._repo.average_wpm_accuracy()
+        recent = [r.wpm for r in reversed(self._repo.list_history(limit=20))]
+        quote_best = self._repo.best_quote_run()
+        return StatsSummary(
+            profile=profile,
+            avg_wpm=round(avg_wpm, 1),
+            avg_accuracy=round(avg_acc, 4),
+            time_best_by_mode=self._repo.best_by_mode(RaceKind.TIME),
+            quote_best_wpm=quote_best[0] if quote_best else 0.0,
+            quote_best_ms=quote_best[1] if quote_best else 0,
+            recent_wpm=recent,
+        )
+
+    def history(self, limit: int = 20, offset: int = 0) -> list[RaceRecord]:
+        return self._repo.list_history(limit=limit, offset=offset)
+
+    def history_pages(self, page_size: int = 20) -> int:
+        total = self._repo.count_races()
+        return max(1, (total + page_size - 1) // page_size)
+
+    def top_time_runs(self, mode_seconds: int, limit: int = 10) -> list[RaceRecord]:
+        return self._repo.top_runs(mode_seconds, limit=limit, kind=RaceKind.TIME)
+
+    def top_quote_runs(self, limit: int = 10) -> list[RaceRecord]:
+        return self._repo.top_quote_runs(limit=limit)

typefaster/ui/__init__.py

@@ -0,0 +1 @@
+"""Presentation layer — Textual screens and Rich-rendered widgets."""

typefaster/ui/app.py

@@ -0,0 +1,93 @@
+"""The Textual application — screen orchestration and race flow."""
+
+from __future__ import annotations
+
+from textual.app import App
+
+from ..domain.models import RaceResult
+from ..services.container import App as Services
+from ..services.container import build_app
+from ..services.race_service import RaceConfig, RaceSetup
+from .screens.daily import DailyScreen
+from .screens.help import HelpScreen
+from .screens.history import HistoryScreen
+from .screens.leaderboard import LeaderboardScreen
+from .screens.main_menu import MainMenu
+from .screens.practice import PracticeScreen
+from .screens.profile import ProfileScreen
+from .screens.race import RaceScreen
+from .screens.results import ResultsScreen
+from .screens.settings import SettingsScreen
+from .screens.stats import StatsScreen
+from .theme import APP_CSS
+
+_PANELS = {
+    "practice": PracticeScreen,
+    "daily": DailyScreen,
+    "stats": StatsScreen,
+    "history": HistoryScreen,
+    "profile": ProfileScreen,
+    "leaderboard": LeaderboardScreen,
+    "settings": SettingsScreen,
+    "help": HelpScreen,
+}
+
+
+class TypefasterApp(App[None]):
+    """Offline TYPEFASTER terminal app."""
+
+    CSS = APP_CSS
+    TITLE = "TYPEFASTER"
+
+    def __init__(
+        self,
+        services: Services | None = None,
+        *,
+        initial_race: RaceConfig | None = None,
+    ) -> None:
+        super().__init__()
+        self.services: Services = services or build_app()
+        self._last_config: RaceConfig | None = None
+        self._initial_race = initial_race
+
+    def on_mount(self) -> None:
+        self.push_screen(MainMenu())
+        if self._initial_race is not None:
+            self.start_race(self._initial_race)
+
+    # ── navigation helper used by screens ──────────────────────────────
+    def open(self, name: str) -> None:
+        """Push a fresh panel screen by name so its data is always current."""
+        self.push_screen(_PANELS[name]())
+
+    # ── race flow ──────────────────────────────────────────────────────
+    def start_race(self, config: RaceConfig) -> None:
+        setup = self.services.race.prepare(
+            kind=config.kind,
+            mode=config.mode,
+            ghost_kind=config.ghost_kind,
+            daily=config.daily,
+        )
+        self._last_config = config
+        self.push_screen(RaceScreen(setup), lambda result: self._after_race(setup, result))
+
+    def _after_race(self, setup: RaceSetup, result: RaceResult | None) -> None:
+        if result is None:
+            return  # race quit — return to whatever is underneath
+        if result.suspicious:
+            # Implausible run (paste/auto-input): show it, but do not record it.
+            self.push_screen(ResultsScreen(result, setup, summary=None), self._after_results)
+            return
+        summary = self.services.race.finish(setup, result)
+        self.push_screen(ResultsScreen(result, setup, summary=summary), self._after_results)
+
+    def _after_results(self, action: str | None) -> None:
+        if action == "again" and self._last_config is not None:
+            self.start_race(self._last_config)
+
+    def on_unmount(self) -> None:
+        self.services.close()
+
+
+def run(initial_race: RaceConfig | None = None) -> None:
+    TypefasterApp(initial_race=initial_race).run()

typefaster/ui/online_app.py

@@ -0,0 +1,24 @@
+"""A minimal Textual app that hosts the online race screen for one lobby."""
+
+from __future__ import annotations
+
+from textual.app import App
+
+from .screens.online_race import OnlineRaceScreen
+from .theme import APP_CSS
+
+
+class OnlineApp(App[None]):
+    CSS = APP_CSS
+    TITLE = "TYPEFASTER · online"
+
+    def __init__(self, ws_url: str, username: str, mode_seconds: int) -> None:
+        super().__init__()
+        self._args = (ws_url, username, mode_seconds)
+
+    def on_mount(self) -> None:
+        self.push_screen(OnlineRaceScreen(*self._args))
+
+
+def run_online(ws_url: str, username: str, mode_seconds: int) -> None:
+    OnlineApp(ws_url, username, mode_seconds).run()

typefaster/ui/screens/__init__.py

@@ -0,0 +1 @@
+"""Textual screens."""

typefaster/ui/screens/_base.py

@@ -0,0 +1,30 @@
+"""Shared base for read-only panel screens (esc to go back)."""
+
+from __future__ import annotations
+
+from rich.console import RenderableType
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical, VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Static
+
+
+class PanelScreen(Screen[None]):
+    """A titled, scrollable panel. Subclasses implement ``body``."""
+
+    title_text: str = "PANEL"
+    BINDINGS = [("escape", "back", "Back"), ("q", "back", "Back")]
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="panel-wrap"):
+            yield Static(Text(self.title_text, justify="center"), id="title")
+            with VerticalScroll():
+                yield Static(self.body())
+            yield Static("esc back", classes="dim")
+
+    def body(self) -> RenderableType:  # pragma: no cover - overridden
+        return Text("")
+
+    def action_back(self) -> None:
+        self.app.pop_screen()

typefaster/ui/screens/daily.py

@@ -0,0 +1,64 @@
+"""Daily challenge screen — shared quote + local daily leaderboard."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical, VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Static
+
+from ...domain.models import RaceKind
+from ...services.race_service import RaceConfig
+
+
+class DailyScreen(Screen[None]):
+    BINDINGS = [
+        ("enter", "play", "Play"),
+        ("escape", "back", "Back"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="panel-wrap"):
+            yield Static(
+                Text(f"DAILY CHALLENGE · {date.today().isoformat()}", justify="center"),
+                id="title",
+            )
+            with VerticalScroll():
+                yield Static(self._body())
+            yield Static("⏎ play today's challenge    esc back", classes="dim")
+
+    def _body(self) -> Group:
+        svc = self.app.services  # type: ignore[attr-defined]
+        challenge = svc.daily.today()
+        board = svc.daily.leaderboard(limit=10)
+
+        quote = Text()
+        quote.append("Today's quote (same for everyone)\n", style="grey58")
+        quote.append(f'"{challenge.quote.text}"\n', style="italic")
+        quote.append(f"— {challenge.quote.source or 'unknown'}\n", style="grey58")
+        quote.append(
+            f"\nYour best today: {challenge.best_wpm:.0f} wpm  ·  attempts {challenge.attempts}\n",
+            style="bold",
+        )
+
+        table = Table(title="Local daily leaderboard", title_style="bold", expand=True)
+        table.add_column("#", justify="right")
+        table.add_column("WPM", justify="right")
+        table.add_column("Acc", justify="right")
+        if not board:
+            table.add_row("—", "—", "not played yet")
+        for i, r in enumerate(board, 1):
+            table.add_row(str(i), f"{r.wpm:.0f}", f"{r.accuracy * 100:.0f}%")
+        return Group(quote, table)
+
+    def action_play(self) -> None:
+        # Daily is a fixed quote; the ghost (if any) is your best run on it.
+        self.app.start_race(RaceConfig(kind=RaceKind.QUOTE, daily=True))  # type: ignore[attr-defined]
+
+    def action_back(self) -> None:
+        self.app.pop_screen()

typefaster/ui/screens/help.py

@@ -0,0 +1,26 @@
+"""Help overlay."""
+
+from __future__ import annotations
+
+from rich.console import RenderableType
+from rich.table import Table
+
+from ._base import PanelScreen
+
+
+class HelpScreen(PanelScreen):
+    title_text = "HELP"
+
+    def body(self) -> RenderableType:
+        table = Table.grid(padding=(0, 3))
+        table.add_column(style="bold cyan", justify="right")
+        table.add_column()
+        table.add_row("↑ / ↓ , j / k", "move between options")
+        table.add_row("Enter", "select")
+        table.add_row("Esc", "go back")
+        table.add_row("q", "quit")
+        table.add_row("?", "this help")
+        table.add_row("", "")
+        table.add_row("During a race", "just type; Backspace corrects mistakes")
+        table.add_row("", "Esc quits the race")
+        return table

typefaster/ui/screens/history.py

@@ -0,0 +1,34 @@
+"""History screen — most recent races."""
+
+from __future__ import annotations
+
+from rich.console import RenderableType
+from rich.table import Table
+from rich.text import Text
+
+from ._base import PanelScreen
+
+
+class HistoryScreen(PanelScreen):
+    title_text = "HISTORY"
+
+    def body(self) -> RenderableType:
+        records = self.app.services.stats.history(limit=30)  # type: ignore[attr-defined]
+        if not records:
+            return Text("No races yet. Press esc, then start a Quick Race!", style="grey58")
+
+        table = Table(expand=True)
+        table.add_column("Date")
+        table.add_column("Mode", justify="right")
+        table.add_column("WPM", justify="right")
+        table.add_column("Acc", justify="right")
+        table.add_column("Source")
+        for r in records:
+            table.add_row(
+                r.started_at[:16].replace("T", " "),
+                f"{r.mode_seconds}s",
+                f"{r.wpm:.0f}",
+                f"{r.accuracy * 100:.0f}%",
+                (r.quote_source or "—")[:24],
+            )
+        return table