typefaster-cli 0.1.0__py3-none-any.whl

typefaster/cli.py

@@ -0,0 +1,196 @@
+"""Typer entry point.
+
+``typefaster`` launches straight into the game. Subcommands cover direct race
+launches and non-interactive stats output.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .domain.errors import InvalidRaceModeError
+from .domain.models import GhostKind, RaceMode
+from .services.container import build_app
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=False,
+    help="TYPEFASTER — a terminal-first typing game.",
+)
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Launch the game when no subcommand is given."""
+    if ctx.invoked_subcommand is None:
+        from .ui.app import run
+
+        run()
+
+
+def _parse_ghost(value: str | None) -> GhostKind | None:
+    if value is None:
+        return None
+    try:
+        return GhostKind(value)
+    except ValueError as exc:
+        raise typer.BadParameter("ghost must be one of: personal-best, last, random") from exc
+
+
+@app.command()
+def race(
+    mode: str = typer.Option(
+        "quote", "--mode", "-m", help="quote (finish one text) or time (type for N seconds)."
+    ),
+    time: int = typer.Option(60, "--time", "-t", help="TIME mode duration: 30, 60, or 120."),
+    ghost: str | None = typer.Option(
+        None, "--ghost", "-g", help="QUOTE mode ghost: personal-best | last | random."
+    ),
+) -> None:
+    """Start a race directly.
+
+    Examples:
+      typefaster race                         # quote mode, random text
+      typefaster race --ghost personal-best   # quote mode vs your best (same text)
+      typefaster race --mode time --time 60   # type for 60 seconds
+    """
+    from .domain.models import RaceKind
+    from .services.race_service import RaceConfig
+    from .ui.app import run
+
+    if mode not in ("quote", "time"):
+        raise typer.BadParameter("mode must be 'quote' or 'time'")
+    if mode == "time":
+        try:
+            race_mode = RaceMode.from_seconds(time)
+        except InvalidRaceModeError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        run(initial_race=RaceConfig(kind=RaceKind.TIME, mode=race_mode))
+    else:
+        run(initial_race=RaceConfig(kind=RaceKind.QUOTE, ghost_kind=_parse_ghost(ghost)))
+
+
+@app.command()
+def daily() -> None:
+    """Play today's daily challenge."""
+    from .domain.models import RaceKind
+    from .services.race_service import RaceConfig
+    from .ui.app import run
+
+    run(initial_race=RaceConfig(kind=RaceKind.QUOTE, daily=True))
+
+
+@app.command()
+def profile() -> None:
+    """Print your local profile."""
+    services = build_app()
+    try:
+        p = services.profile.get()
+        table = Table(title="Profile", show_header=False)
+        table.add_column(style="grey58", justify="right")
+        table.add_column()
+        table.add_row("Name", p.display_name)
+        table.add_row("Member since", (p.created_at or "—")[:10])
+        table.add_row("Races played", str(p.races_played))
+        table.add_row("Races won", str(p.races_won))
+        table.add_row("Best WPM", f"{p.best_wpm:.0f}")
+        table.add_row("Best accuracy", f"{p.best_accuracy * 100:.1f}%")
+        console.print(table)
+    finally:
+        services.close()
+
+
+@app.command()
+def stats() -> None:
+    """Print summary statistics."""
+    services = build_app()
+    try:
+        s = services.stats.summary()
+        p = s.profile
+        table = Table(title="Stats", show_header=False)
+        table.add_column(style="grey58", justify="right")
+        table.add_column()
+        table.add_row("Races played", str(p.races_played))
+        table.add_row("Best WPM", f"{p.best_wpm:.0f}")
+        table.add_row("Avg WPM", f"{s.avg_wpm:.0f}")
+        table.add_row("Best accuracy", f"{p.best_accuracy * 100:.1f}%")
+        table.add_row("Avg accuracy", f"{s.avg_accuracy * 100:.1f}%")
+        table.add_row("Total chars", f"{p.total_chars:,}")
+        table.add_row("Quote best WPM", f"{s.quote_best_wpm:.0f}")
+        for seconds in (30, 60, 120):
+            table.add_row(f"Time {seconds}s best WPM", f"{s.time_best_by_mode.get(seconds, 0):.0f}")
+        console.print(table)
+    finally:
+        services.close()
+
+
+@app.command()
+def history(limit: int = typer.Option(20, "--limit", "-n", help="Rows to show.")) -> None:
+    """Print recent race history."""
+    services = build_app()
+    try:
+        records = services.stats.history(limit=limit)
+        if not records:
+            console.print("[grey58]No races yet. Run [bold]typefaster[/] to play![/]")
+            return
+        table = Table(title="History")
+        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],
+            )
+        console.print(table)
+    finally:
+        services.close()
+
+
+@app.command()
+def reset(
+    all: bool = typer.Option(False, "--all", help="Wipe ALL local race history and stats."),
+) -> None:
+    """Clean up local data. By default removes only impossible (e.g. pasted) runs."""
+    services = build_app()
+    try:
+        if all:
+            typer.confirm("Delete ALL local race history and stats?", abort=True)
+            services.repo.wipe()
+            console.print("[green]All local race data cleared.[/]")
+        else:
+            removed = services.repo.delete_implausible_races()
+            console.print(
+                f"[green]Removed {removed} impossible run(s)[/] and recomputed your stats."
+            )
+    finally:
+        services.close()
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    console.print(f"typefaster {__version__}")
+
+
+# ── online (Phase 2) commands ──────────────────────────────────────────
+from .net import commands as _online  # noqa: E402
+
+app.command("register")(_online.register)
+app.command("login")(_online.login)
+app.command("logout")(_online.logout)
+app.command("leaderboard")(_online.leaderboard)
+app.add_typer(_online.lobby_app, name="lobby")
+
+
+if __name__ == "__main__":
+    app()

typefaster/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure domain layer — no third-party, UI, or storage dependencies."""

typefaster/domain/anti_cheat.py

@@ -0,0 +1,46 @@
+"""Offline plausibility checks for a finished race.
+
+Pure and dependency-free. Mirrors the server's anti-cheat thresholds
+(``typefaster_shared.anti_cheat``) so offline and online behave consistently.
+A flagged race is shown to the player but is *not* recorded (no stats, no
+personal best), preventing pastes / held keys / auto-input from polluting data.
+"""
+
+from __future__ import annotations
+
+# The fastest sustained human typing is ~215 WPM; bursts peak near ~300.
+MAX_PLAUSIBLE_WPM = 300.0
+MAX_PLAUSIBLE_RAW_WPM = 400.0
+MIN_KEYSTROKE_INTERVAL_MS = 12.0  # below ~10000 cpm is non-human
+
+
+def evaluate(
+    *,
+    wpm: float,
+    raw_wpm: float,
+    duration_ms: int,
+    total_keystrokes: int,
+    quote_length: int,
+    pasted: bool = False,
+) -> tuple[bool, tuple[str, ...]]:
+    """Return ``(suspicious, reasons)`` for a finished race."""
+    reasons: list[str] = []
+
+    if pasted:
+        reasons.append("paste detected")
+    if wpm > MAX_PLAUSIBLE_WPM:
+        reasons.append("impossible WPM")
+    if raw_wpm > MAX_PLAUSIBLE_RAW_WPM:
+        reasons.append("impossible burst speed")
+
+    if (
+        total_keystrokes > 5
+        and duration_ms > 0
+        and duration_ms / total_keystrokes < MIN_KEYSTROKE_INTERVAL_MS
+    ):
+        reasons.append("superhuman cadence")
+
+    if quote_length >= 40 and duration_ms < 1000:
+        reasons.append("impossible completion time")
+
+    return bool(reasons), tuple(reasons)

typefaster/domain/calculators.py

@@ -0,0 +1,47 @@
+"""Typing-speed and accuracy math. Pure functions, MonkeyType-style.
+
+Definitions
+-----------
+- A "word" is normalized to 5 characters.
+- ``wpm``      = (correct_chars / 5) / minutes
+- ``raw_wpm``  = (total_typed_chars / 5) / minutes  (errors included)
+- ``accuracy`` = correct_keystrokes / total_keystrokes  (0..1)
+
+All functions guard against division by zero and return 0.0 for empty input.
+"""
+
+from __future__ import annotations
+
+CHARS_PER_WORD = 5
+
+
+def _minutes(elapsed_ms: int) -> float:
+    return elapsed_ms / 1000.0 / 60.0
+
+
+def wpm(correct_chars: int, elapsed_ms: int) -> float:
+    """Net words-per-minute based on correctly typed characters."""
+    minutes = _minutes(elapsed_ms)
+    if minutes <= 0:
+        return 0.0
+    return (correct_chars / CHARS_PER_WORD) / minutes
+
+
+def raw_wpm(total_typed_chars: int, elapsed_ms: int) -> float:
+    """Gross words-per-minute including incorrect characters."""
+    minutes = _minutes(elapsed_ms)
+    if minutes <= 0:
+        return 0.0
+    return (total_typed_chars / CHARS_PER_WORD) / minutes
+
+
+def accuracy(correct_keystrokes: int, total_keystrokes: int) -> float:
+    """Fraction of character keystrokes that were correct (0..1)."""
+    if total_keystrokes <= 0:
+        return 0.0
+    return correct_keystrokes / total_keystrokes
+
+
+def round_stats(value: float, digits: int = 1) -> float:
+    """Round a stat for display/storage consistency."""
+    return round(value, digits)

typefaster/domain/errors.py

@@ -0,0 +1,19 @@
+"""Domain-level exceptions."""
+
+from __future__ import annotations
+
+
+class TypefasterError(Exception):
+    """Base class for all application errors."""
+
+
+class NoQuotesError(TypefasterError):
+    """Raised when the quote dataset is empty or missing."""
+
+
+class GhostUnavailableError(TypefasterError):
+    """Raised when a requested ghost has no historical data to race against."""
+
+
+class InvalidRaceModeError(TypefasterError):
+    """Raised when an unsupported race duration is requested."""

typefaster/domain/ghost.py

@@ -0,0 +1,61 @@
+"""Ghost progress sampling and the GhostSource protocol.
+
+A ghost is a stored replay timeline (list of ``ReplayPoint``). During a live
+race the UI asks ``progress_at(timeline, t_ms)`` for the ghost's completion
+percentage at the current elapsed time, interpolating linearly between points
+for smooth animation.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .models import Ghost, ReplayPoint
+
+
+def progress_at(timeline: list[ReplayPoint], t_ms: int) -> float:
+    """Return the ghost's progress percentage (0..100) at time ``t_ms``.
+
+    Linearly interpolates between the two surrounding timeline points. Clamps
+    to the first/last point outside the recorded range.
+    """
+    if not timeline:
+        return 0.0
+    if t_ms <= timeline[0].t_ms:
+        return timeline[0].progress_pct
+    if t_ms >= timeline[-1].t_ms:
+        return timeline[-1].progress_pct
+
+    # Binary-search-free linear scan is fine for short timelines.
+    prev = timeline[0]
+    for point in timeline[1:]:
+        if t_ms <= point.t_ms:
+            span = point.t_ms - prev.t_ms
+            if span <= 0:
+                return point.progress_pct
+            ratio = (t_ms - prev.t_ms) / span
+            return prev.progress_pct + ratio * (point.progress_pct - prev.progress_pct)
+        prev = point
+    return timeline[-1].progress_pct
+
+
+def ghost_won(ghost_timeline: list[ReplayPoint], player_duration_ms: int) -> bool:
+    """Whether the ghost finished (reached 100%) before the player did."""
+    if not ghost_timeline:
+        return False
+    for point in ghost_timeline:
+        if point.progress_pct >= 100.0:
+            return point.t_ms < player_duration_ms
+    return False
+
+
+class GhostSource(Protocol):
+    """A source that can produce a ghost to race against.
+
+    Phase 1 implements ``personal-best``, ``last`` and ``random`` over SQLite.
+    Phase 2 adds a remote/network-backed source with the same interface.
+    """
+
+    def load(self) -> Ghost | None:
+        """Return a ghost, or ``None`` if no historical data is available."""
+        ...

typefaster/domain/models.py

@@ -0,0 +1,186 @@
+"""Core domain models. Pure dataclasses and enums — no I/O."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .errors import InvalidRaceModeError
+
+
+class Difficulty(str, Enum):
+    """Quote length bucket."""
+
+    SHORT = "short"
+    MEDIUM = "medium"
+    LONG = "long"
+
+    @staticmethod
+    def from_length(length: int) -> Difficulty:
+        if length < 120:
+            return Difficulty.SHORT
+        if length < 250:
+            return Difficulty.MEDIUM
+        return Difficulty.LONG
+
+
+class RaceMode(int, Enum):
+    """Supported race durations, in seconds."""
+
+    SHORT = 30
+    NORMAL = 60
+    LONG = 120
+
+    @staticmethod
+    def from_seconds(seconds: int) -> RaceMode:
+        try:
+            return RaceMode(seconds)
+        except ValueError as exc:  # pragma: no cover - trivial
+            raise InvalidRaceModeError(
+                f"Unsupported race mode: {seconds}s (use 30, 60, or 120)"
+            ) from exc
+
+
+class GhostKind(str, Enum):
+    """The three offline ghost sources."""
+
+    PERSONAL_BEST = "personal-best"
+    LAST = "last"
+    RANDOM = "random"
+
+
+class RaceKind(str, Enum):
+    """How a race is bounded and measured.
+
+    - ``QUOTE``: type one fixed quote to completion; measured by time-to-finish
+      and WPM. Ghost races (same text) live here.
+    - ``TIME``: type continuously for a fixed number of seconds (text streams);
+      measured by WPM over the full duration.
+
+    The two are scored and stored separately — they are not comparable.
+    """
+
+    QUOTE = "quote"
+    TIME = "time"
+
+
+@dataclass(frozen=True, slots=True)
+class Quote:
+    """A piece of text to be typed."""
+
+    ext_id: str
+    text: str
+    source: str | None = None
+
+    @property
+    def length(self) -> int:
+        return len(self.text)
+
+    @property
+    def difficulty(self) -> Difficulty:
+        return Difficulty.from_length(self.length)
+
+
+@dataclass(frozen=True, slots=True)
+class Keystroke:
+    """A single character input event with a millisecond timestamp."""
+
+    char: str
+    t_ms: int
+    correct: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayPoint:
+    """A point on a race's progress timeline.
+
+    Serialized form matches the spec: ``{"t": <ms>, "p": <percent 0-100>}``.
+    """
+
+    t_ms: int
+    progress_pct: float
+
+
+@dataclass(frozen=True, slots=True)
+class Ghost:
+    """An opponent reconstructed from a stored replay timeline.
+
+    ``quote`` is the exact text the ghost was recorded on, so a ghost race uses
+    identical text for a fair head-to-head.
+    """
+
+    kind: GhostKind
+    label: str
+    timeline: list[ReplayPoint]
+    wpm: float = 0.0
+    quote: Quote | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RaceResult:
+    """The computed outcome of a finished race."""
+
+    wpm: float
+    raw_wpm: float
+    accuracy: float
+    correct_chars: int
+    incorrect_chars: int
+    progress: float  # 0..1
+    duration_ms: int
+    mode_seconds: int  # TIME mode: the limit (30/60/120). QUOTE mode: 0.
+    kind: RaceKind = RaceKind.QUOTE
+    timeline: list[ReplayPoint] = field(default_factory=list)
+    ghost_kind: GhostKind | None = None
+    ghost_won: bool | None = None
+    # Set when the run is implausible (paste/auto-input) — not recorded.
+    suspicious: bool = False
+    flags: tuple[str, ...] = ()
+
+    @property
+    def completed(self) -> bool:
+        return self.progress >= 1.0
+
+
+@dataclass(slots=True)
+class Profile:
+    """Local player profile with denormalized lifetime aggregates."""
+
+    display_name: str = "you"
+    created_at: str = ""
+    races_played: int = 0
+    races_won: int = 0
+    best_wpm: float = 0.0
+    best_accuracy: float = 0.0
+    total_chars: int = 0
+    total_time_ms: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RaceRecord:
+    """A persisted race row, returned for history/stats views."""
+
+    id: int
+    quote_source: str | None
+    mode_seconds: int
+    started_at: str
+    duration_ms: int
+    wpm: float
+    raw_wpm: float
+    accuracy: float
+    correct_chars: int
+    incorrect_chars: int
+    progress: float
+    is_daily: bool
+    ghost_kind: GhostKind | None
+    ghost_won: bool | None
+    kind: RaceKind = RaceKind.QUOTE
+
+
+@dataclass(frozen=True, slots=True)
+class DailyChallenge:
+    """A day's shared challenge plus local aggregates."""
+
+    day: str  # YYYY-MM-DD
+    quote: Quote
+    best_wpm: float = 0.0
+    attempts: int = 0