typefaster-cli 0.1.0__py3-none-any.whl

typefaster/domain/typing_engine.py

@@ -0,0 +1,150 @@
+"""The typing engine — pure state machine over a stream of keystrokes.
+
+Time is injected (millisecond timestamps passed in), so the engine is fully
+deterministic and unit-testable without a clock.
+
+Backspace model (MonkeyType-style, the locked Phase 1 decision)
+---------------------------------------------------------------
+- Typing any character advances the cursor; a wrong char is recorded in place
+  (shown red by the UI) and the cursor still advances.
+- Backspace moves the cursor back one and clears that slot's correctness, so the
+  player can retype it. Backspace is *not* counted as a keystroke.
+- Accuracy is measured over **every** character keystroke (including ones later
+  corrected), so corrections don't inflate accuracy. Completion/progress is
+  measured from the current buffer state.
+"""
+
+from __future__ import annotations
+
+from .calculators import accuracy, raw_wpm, wpm
+from .models import GhostKind, RaceKind, RaceResult, ReplayPoint
+
+
+class TypingEngine:
+    """Processes keystrokes against a target string."""
+
+    def __init__(self, target: str, *, allow_backspace: bool = True) -> None:
+        if not target:
+            raise ValueError("target text must not be empty")
+        self.target = target
+        self.allow_backspace = allow_backspace
+
+        # Per-index correctness of the current buffer: None=untyped, True/False.
+        self._states: list[bool | None] = [None] * len(target)
+        self._cursor = 0  # index of the next character to type
+
+        # Lifetime keystroke counters (corrections do not decrement these).
+        self._total_keystrokes = 0
+        self._correct_keystrokes = 0
+
+        self._timeline: list[ReplayPoint] = [ReplayPoint(0, 0.0)]
+        self._last_progress_pct = 0.0
+
+    # ── input ──────────────────────────────────────────────────────────
+    def type_char(self, char: str, t_ms: int) -> None:
+        """Apply a single character keypress at time ``t_ms``."""
+        if self.finished:
+            return
+        if len(char) != 1:
+            raise ValueError("type_char expects exactly one character")
+
+        expected = self.target[self._cursor]
+        is_correct = char == expected
+        self._states[self._cursor] = is_correct
+        self._cursor += 1
+
+        self._total_keystrokes += 1
+        if is_correct:
+            self._correct_keystrokes += 1
+
+        self._record(t_ms)
+
+    def backspace(self, t_ms: int) -> None:
+        """Move the cursor back one position and clear that slot."""
+        if not self.allow_backspace:
+            return
+        if self._cursor == 0:
+            return
+        self._cursor -= 1
+        self._states[self._cursor] = None
+        self._record(t_ms)
+
+    # ── derived state ──────────────────────────────────────────────────
+    @property
+    def cursor(self) -> int:
+        return self._cursor
+
+    @property
+    def states(self) -> list[bool | None]:
+        """Read-only view of per-index correctness (for the UI to render)."""
+        return list(self._states)
+
+    @property
+    def correct_chars(self) -> int:
+        return sum(1 for s in self._states if s is True)
+
+    @property
+    def incorrect_chars(self) -> int:
+        return sum(1 for s in self._states if s is False)
+
+    @property
+    def total_keystrokes(self) -> int:
+        return self._total_keystrokes
+
+    @property
+    def correct_keystrokes(self) -> int:
+        return self._correct_keystrokes
+
+    @property
+    def progress(self) -> float:
+        """Completion fraction 0..1 based on cursor position."""
+        return self._cursor / len(self.target)
+
+    @property
+    def finished(self) -> bool:
+        return self._cursor >= len(self.target)
+
+    def live_wpm(self, elapsed_ms: int) -> float:
+        return wpm(self.correct_chars, elapsed_ms)
+
+    def live_accuracy(self) -> float:
+        return accuracy(self._correct_keystrokes, self._total_keystrokes)
+
+    # ── timeline / result ──────────────────────────────────────────────
+    def _record(self, t_ms: int) -> None:
+        pct = round(self.progress * 100.0, 2)
+        if pct != self._last_progress_pct:
+            self._timeline.append(ReplayPoint(t_ms, pct))
+            self._last_progress_pct = pct
+
+    @property
+    def timeline(self) -> list[ReplayPoint]:
+        return list(self._timeline)
+
+    def result(
+        self,
+        elapsed_ms: int,
+        *,
+        kind: RaceKind = RaceKind.QUOTE,
+        mode_seconds: int = 0,
+        ghost_kind: GhostKind | None = None,
+        ghost_won: bool | None = None,
+    ) -> RaceResult:
+        """Snapshot the final result for an elapsed duration.
+
+        ``mode_seconds`` is the time limit for TIME mode, or 0 for QUOTE mode.
+        """
+        return RaceResult(
+            wpm=round(self.live_wpm(elapsed_ms), 2),
+            raw_wpm=round(raw_wpm(self._total_keystrokes, elapsed_ms), 2),
+            accuracy=round(self.live_accuracy(), 4),
+            correct_chars=self.correct_chars,
+            incorrect_chars=self.incorrect_chars,
+            progress=round(self.progress, 4),
+            duration_ms=elapsed_ms,
+            mode_seconds=mode_seconds,
+            kind=kind,
+            timeline=self.timeline,
+            ghost_kind=ghost_kind,
+            ghost_won=ghost_won,
+        )

typefaster/infra/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure adapters: SQLite, config, clock, quote/replay loaders."""

typefaster/infra/clock.py

@@ -0,0 +1,36 @@
+"""Injectable clock so timing stays out of the pure domain and tests stay
+deterministic."""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol
+
+
+class Clock(Protocol):
+    def now_ms(self) -> int:
+        """Monotonic milliseconds. Only differences are meaningful."""
+        ...
+
+
+class SystemClock:
+    """Production clock backed by ``time.monotonic``."""
+
+    def now_ms(self) -> int:
+        return int(time.monotonic() * 1000)
+
+
+class FakeClock:
+    """Manually advanced clock for tests."""
+
+    def __init__(self, start_ms: int = 0) -> None:
+        self._t = start_ms
+
+    def now_ms(self) -> int:
+        return self._t
+
+    def advance(self, ms: int) -> None:
+        self._t += ms
+
+    def set(self, ms: int) -> None:
+        self._t = ms

typefaster/infra/config.py

@@ -0,0 +1,41 @@
+"""User settings persistence.
+
+Settings (not gameplay data) are stored as a small JSON file in the OS config
+dir. Gameplay data lives in SQLite per the project's storage policy.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .paths import config_path
+
+
+@dataclass(slots=True)
+class Settings:
+    theme: str = "dark"
+    default_time: int = 60
+    allow_backspace: bool = True
+    default_ghost: str = "personal-best"
+    sound: bool = False
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Settings:
+        path = path or config_path()
+        if not path.exists():
+            settings = cls()
+            settings.save(path)
+            return settings
+        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 config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(self), indent=2), encoding="utf-8")

typefaster/infra/db.py

@@ -0,0 +1,31 @@
+"""SQLite connection management with sane pragmas and a transaction helper."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+def connect(path: Path | str) -> sqlite3.Connection:
+    """Open a connection with WAL, foreign keys, and row access by name."""
+    conn = sqlite3.connect(str(path), isolation_level=None)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode = WAL;")
+    conn.execute("PRAGMA foreign_keys = ON;")
+    conn.execute("PRAGMA synchronous = NORMAL;")
+    return conn
+
+
+@contextmanager
+def transaction(conn: sqlite3.Connection) -> Iterator[sqlite3.Connection]:
+    """Run a block inside a transaction, committing on success."""
+    conn.execute("BEGIN;")
+    try:
+        yield conn
+    except Exception:
+        conn.execute("ROLLBACK;")
+        raise
+    else:
+        conn.execute("COMMIT;")

typefaster/infra/migrations.py

@@ -0,0 +1,106 @@
+"""Ordered schema migrations, versioned via the ``schema_meta`` table."""
+
+from __future__ import annotations
+
+import sqlite3
+
+# Each migration is (version, SQL). Applied in order; never edit a shipped one.
+_MIGRATIONS: list[tuple[int, str]] = [
+    (
+        1,
+        """
+        CREATE TABLE IF NOT EXISTS schema_meta (
+            key   TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS profile (
+            id            INTEGER PRIMARY KEY CHECK (id = 1),
+            display_name  TEXT NOT NULL DEFAULT 'you',
+            created_at    TEXT NOT NULL,
+            races_played  INTEGER NOT NULL DEFAULT 0,
+            races_won     INTEGER NOT NULL DEFAULT 0,
+            best_wpm      REAL    NOT NULL DEFAULT 0,
+            best_accuracy REAL    NOT NULL DEFAULT 0,
+            total_chars   INTEGER NOT NULL DEFAULT 0,
+            total_time_ms INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE TABLE IF NOT EXISTS quote (
+            id         INTEGER PRIMARY KEY AUTOINCREMENT,
+            ext_id     TEXT UNIQUE,
+            text       TEXT NOT NULL,
+            source     TEXT,
+            length     INTEGER NOT NULL,
+            difficulty TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS race (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            profile_id      INTEGER NOT NULL REFERENCES profile(id),
+            quote_id        INTEGER NOT NULL REFERENCES quote(id),
+            mode_seconds    INTEGER NOT NULL,
+            started_at      TEXT NOT NULL,
+            duration_ms     INTEGER NOT NULL,
+            wpm             REAL NOT NULL,
+            raw_wpm         REAL NOT NULL,
+            accuracy        REAL NOT NULL,
+            correct_chars   INTEGER NOT NULL,
+            incorrect_chars INTEGER NOT NULL,
+            progress        REAL NOT NULL,
+            is_daily        INTEGER NOT NULL DEFAULT 0,
+            ghost_kind      TEXT,
+            ghost_won       INTEGER
+        );
+        CREATE INDEX IF NOT EXISTS idx_race_profile_time ON race(profile_id, started_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_race_wpm          ON race(profile_id, wpm DESC);
+        CREATE INDEX IF NOT EXISTS idx_race_daily        ON race(is_daily, started_at);
+
+        CREATE TABLE IF NOT EXISTS replay (
+            race_id  INTEGER PRIMARY KEY REFERENCES race(id) ON DELETE CASCADE,
+            timeline TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS daily_challenge (
+            day      TEXT PRIMARY KEY,
+            quote_id INTEGER NOT NULL REFERENCES quote(id),
+            best_wpm REAL NOT NULL DEFAULT 0,
+            attempts INTEGER NOT NULL DEFAULT 0
+        );
+        """,
+    ),
+    (
+        2,
+        # Distinguish quote-mode (finish one text) from time-mode (type for N s).
+        # Existing rows predate the split and were single-quote races.
+        """
+        ALTER TABLE race ADD COLUMN race_kind TEXT NOT NULL DEFAULT 'quote';
+        CREATE INDEX IF NOT EXISTS idx_race_kind_wpm ON race(race_kind, mode_seconds, wpm DESC);
+        """,
+    ),
+]
+
+
+def _current_version(conn: sqlite3.Connection) -> int:
+    row = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='schema_meta'"
+    ).fetchone()
+    if row is None:
+        return 0
+    cur = conn.execute("SELECT value FROM schema_meta WHERE key='schema_version'").fetchone()
+    return int(cur["value"]) if cur else 0
+
+
+def migrate(conn: sqlite3.Connection) -> int:
+    """Apply all pending migrations. Returns the resulting schema version."""
+    version = _current_version(conn)
+    for target, sql in _MIGRATIONS:
+        if target > version:
+            conn.executescript(sql)
+            conn.execute(
+                "INSERT INTO schema_meta(key, value) VALUES('schema_version', ?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (str(target),),
+            )
+            version = target
+    return version

typefaster/infra/paths.py

@@ -0,0 +1,35 @@
+"""Resolve OS-appropriate data/config locations via platformdirs.
+
+Honors ``TYPEFASTER_DATA_DIR`` for tests and portable installs.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from platformdirs import user_config_dir, user_data_dir
+
+_APP = "typefaster"
+
+
+def data_dir() -> Path:
+    override = os.environ.get("TYPEFASTER_DATA_DIR")
+    base = Path(override) if override else Path(user_data_dir(_APP, appauthor=False))
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def config_dir() -> Path:
+    override = os.environ.get("TYPEFASTER_CONFIG_DIR")
+    base = Path(override) if override else Path(user_config_dir(_APP, appauthor=False))
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def db_path() -> Path:
+    return data_dir() / "typefaster.db"
+
+
+def config_path() -> Path:
+    return config_dir() / "settings.json"

typefaster/infra/quote_loader.py

@@ -0,0 +1,53 @@
+"""Load the bundled quote dataset and select quotes.
+
+``quotes.json`` ships inside the package (``typefaster/assets``). Each entry:
+``{"id": "...", "text": "...", "source": "..."}``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from datetime import date
+from functools import lru_cache
+from importlib.resources import files
+
+from ..domain.errors import NoQuotesError
+from ..domain.models import Difficulty, Quote
+
+
+@lru_cache(maxsize=1)
+def _load_raw() -> list[dict[str, str]]:
+    resource = files("typefaster.assets").joinpath("quotes.json")
+    data: list[dict[str, str]] = json.loads(resource.read_text(encoding="utf-8"))
+    if not data:
+        raise NoQuotesError("quotes.json is empty")
+    return data
+
+
+def all_quotes() -> list[Quote]:
+    return [Quote(ext_id=q["id"], text=q["text"], source=q.get("source")) for q in _load_raw()]
+
+
+def random_quote(rng: random.Random | None = None) -> Quote:
+    quotes = all_quotes()
+    if not quotes:
+        raise NoQuotesError("no quotes available")
+    r = rng or random
+    return r.choice(quotes)
+
+
+def quotes_by_difficulty(difficulty: Difficulty) -> list[Quote]:
+    return [q for q in all_quotes() if q.difficulty == difficulty]
+
+
+def daily_quote(day: date | None = None) -> Quote:
+    """Deterministically pick the same quote for everyone on a given UTC day."""
+    quotes = all_quotes()
+    if not quotes:
+        raise NoQuotesError("no quotes available")
+    day = day or date.today()
+    digest = hashlib.sha256(day.isoformat().encode("utf-8")).hexdigest()
+    index = int(digest, 16) % len(quotes)
+    return quotes[index]

typefaster/infra/replay_store.py

@@ -0,0 +1,16 @@
+"""Serialize/deserialize replay timelines to the compact ``{t, p}`` JSON form."""
+
+from __future__ import annotations
+
+import json
+
+from ..domain.models import ReplayPoint
+
+
+def serialize(timeline: list[ReplayPoint]) -> str:
+    return json.dumps([{"t": p.t_ms, "p": p.progress_pct} for p in timeline])
+
+
+def deserialize(blob: str) -> list[ReplayPoint]:
+    raw = json.loads(blob)
+    return [ReplayPoint(t_ms=int(item["t"]), progress_pct=float(item["p"])) for item in raw]

typefaster/infra/repository.py

@@ -0,0 +1,63 @@
+"""Repository port (interface). Services depend on this, not on SQLite directly.
+
+Phase 2 can provide an alternative implementation (e.g. Redis-backed sync) that
+satisfies the same protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..domain.models import (
+    DailyChallenge,
+    Profile,
+    Quote,
+    RaceKind,
+    RaceRecord,
+    RaceResult,
+    ReplayPoint,
+)
+
+# A loaded ghost: its replay timeline, the WPM achieved, and the exact quote.
+GhostData = tuple[list[ReplayPoint], float, Quote]
+
+
+class Repository(Protocol):
+    # profile
+    def get_profile(self) -> Profile: ...
+    def recompute_profile(self) -> Profile: ...
+    def delete_implausible_races(self, max_wpm: float = 300.0) -> int: ...
+    def wipe(self) -> None: ...
+
+    # quotes
+    def upsert_quote(self, quote: Quote) -> int: ...
+
+    # races
+    def save_race(
+        self,
+        *,
+        result: RaceResult,
+        quote: Quote,
+        started_at: str,
+        is_daily: bool = False,
+    ) -> int: ...
+
+    def list_history(self, limit: int = 20, offset: int = 0) -> list[RaceRecord]: ...
+    def count_races(self) -> int: ...
+    def average_wpm_accuracy(self) -> tuple[float, float]: ...
+    def best_by_mode(self, kind: RaceKind = ...) -> dict[int, float]: ...
+    def best_quote_run(self) -> tuple[float, int] | None: ...
+    def top_runs(
+        self, mode_seconds: int, limit: int = 10, kind: RaceKind = ...
+    ) -> list[RaceRecord]: ...
+    def top_quote_runs(self, limit: int = 10) -> list[RaceRecord]: ...
+
+    # ghosts (always completed, plausible, quote-mode runs — same text)
+    def personal_best_replay(self) -> GhostData | None: ...
+    def last_replay(self) -> GhostData | None: ...
+    def random_replay(self) -> GhostData | None: ...
+    def best_replay_for_quote(self, ext_id: str) -> GhostData | None: ...
+
+    # daily
+    def get_or_create_daily(self, day: str, quote: Quote) -> DailyChallenge: ...
+    def daily_leaderboard(self, day: str, limit: int = 20) -> list[RaceRecord]: ...