typefaster-cli 0.1.4__tar.gz → 0.3.1__tar.gz

typefaster_cli-0.3.1/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Every change requests a review from the project owner by default.
+# https://docs.github.com/articles/about-code-owners
+*       @Anoshor

{typefaster_cli-0.1.4 → typefaster_cli-0.3.1}/.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -43,7 +43,7 @@ jobs:
 
       - name: Upload coverage artifact
         if: matrix.python-version == '3.12'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage
           path: coverage.xml
@@ -52,8 +52,8 @@ jobs:
     name: server lint · test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -70,8 +70,8 @@ jobs:
     name: dependency audit (pip-audit)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -86,14 +86,14 @@ jobs:
     runs-on: ubuntu-latest
     needs: [quality, server]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
       - run: python -m pip install build
       - run: python -m build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/*

{typefaster_cli-0.1.4 → typefaster_cli-0.3.1}/.github/workflows/codeql.yml

@@ -16,8 +16,8 @@ jobs:
       actions: read
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: github/codeql-action/init@v3
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
         with:
           languages: python
-      - uses: github/codeql-action/analyze@v3
+      - uses: github/codeql-action/analyze@v4

typefaster_cli-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,145 @@
+name: Release
+
+# Publishes to PyPI and creates a GitHub Release whenever you push a version tag
+# (e.g. `git tag v0.1.0 && git push origin v0.1.0`).
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API tokens stored in the repo. You
+# must configure the trusted publisher once on PyPI (see docs/RELEASING.md).
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write   # create the GitHub Release
+  id-token: write   # OIDC token for PyPI Trusted Publishing
+  packages: write   # push the server image to GHCR
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build            # creates dist/*.whl and dist/*.tar.gz
+      - run: python -m pip install twine && twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # optional: add manual approval in repo settings
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  bump-homebrew:
+    name: bump Homebrew tap formula
+    needs: publish-pypi          # only bump once the sdist is live on PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the tap repo
+        uses: actions/checkout@v7
+        with:
+          repository: Anoshor/homebrew-typefaster
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}   # fine-grained PAT, contents:write on the tap
+          path: tap
+
+      - name: Update url + sha256 from PyPI
+        env:
+          VERSION: ${{ github.ref_name }}            # e.g. v0.2.1
+        run: |
+          python3 - <<'PY'
+          import json, os, re, sys, time, urllib.request
+
+          version = os.environ["VERSION"].lstrip("v")
+          api = f"https://pypi.org/pypi/typefaster-cli/{version}/json"
+
+          # PyPI's JSON index can lag a few seconds behind the upload; retry.
+          data = None
+          for attempt in range(10):
+              try:
+                  with urllib.request.urlopen(api) as r:
+                      data = json.load(r)
+                  break
+              except Exception as e:                  # noqa: BLE001
+                  print(f"attempt {attempt+1}: {e}; retrying in 6s")
+                  time.sleep(6)
+          if data is None:
+              sys.exit(f"could not fetch {api}")
+
+          sdist = next(u for u in data["urls"] if u["packagetype"] == "sdist")
+          url, sha = sdist["url"], sdist["digests"]["sha256"]
+          print(f"new url:  {url}\nnew sha:  {sha}")
+
+          path = "tap/Formula/typefaster.rb"
+          text = open(path, encoding="utf-8").read()
+          # Only touch the top-level url/sha256 (everything before the first resource).
+          head, sep, rest = text.partition("\n  resource ")
+          head = re.sub(r'url "[^"]*"', f'url "{url}"', head, count=1)
+          head = re.sub(r'sha256 "[^"]*"', f'sha256 "{sha}"', head, count=1)
+          open(path, "w", encoding="utf-8").write(head + sep + rest)
+          PY
+
+      - name: Commit & push the bump
+        working-directory: tap
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet; then
+            echo "Formula already up to date — nothing to bump."
+            exit 0
+          fi
+          git add Formula/typefaster.rb
+          git commit -m "typefaster ${VERSION#v}"
+          git push
+
+  server-image:
+    name: build & push server image (GHCR)
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/typefaster-server
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: server/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

{typefaster_cli-0.1.4 → typefaster_cli-0.3.1}/.gitignore

@@ -30,3 +30,4 @@ typefaster.db*
 .vscode/
 .DS_Store
 .env
+docs/MARKETING.md

typefaster_cli-0.3.1/CLAUDE.md

@@ -0,0 +1,110 @@
+# CLAUDE.md
+
+Guidance for working in this repo. TYPEFASTER is a terminal-first typing game:
+an offline TUI plus an online real-time multiplayer server. Distributed via PyPI
+(`typefaster-cli`) and a Homebrew tap. Hosted at $0 on an Oracle Always-Free VM.
+
+## Repo layout
+
+```
+client/typefaster/   the CLI/TUI app  (domain · services · infra · ui · net · assets)
+server/app/          online server (FastAPI · WebSockets · Redis · routers · ws)
+shared/typefaster_shared/   schemas (dto), WS events, scoring, anti-cheat — used by both
+tests/               client tests (unit/ + integration/)
+server/tests/        server tests (fakeredis + Starlette TestClient)
+docs/                architecture, schemas, WS protocol, deploy, security, releasing
+Formula lives in a SEPARATE repo: Anoshor/homebrew-typefaster (the tap).
+```
+
+## Architecture & layering (do not violate)
+
+Clean layering, enforced by convention:
+
+- **`domain/`** is pure: dataclasses, enums, and deterministic logic. It must NOT
+  import Rich/Textual/SQLite/httpx. Time is injected (`Clock`), so logic is
+  unit-testable without a real clock.
+- **`services/`** orchestrate domain + repositories. UI-free, reusable headlessly.
+- **`infra/`** (SQLite, config, paths, quote loader) and **`ui/`** (Textual)
+  depend inward only.
+- **Repository port**: `infra/repository.py` is a `typing.Protocol`; the SQLite
+  impl satisfies it. Services depend on the Protocol, not SQLite.
+- **Server is authoritative**: the WS server re-scores every race from raw inputs
+  using `shared/typefaster_shared/scoring.py` (the SAME math as the client's
+  `domain/calculators.py`) and never trusts client-reported WPM/accuracy.
+
+When adding code, put it in the right layer and keep `domain/` pure.
+
+## Commands
+
+Client (from repo root; uses `client/` on PYTHONPATH via the Makefile):
+```bash
+make install     # editable install + dev deps into a venv
+make play        # launch the TUI (offline)
+make check       # ruff + mypy --strict + pytest  ← run before every PR
+make test        # pytest only
+make up / down   # start/stop the online stack (redis + server) via Docker
+```
+
+Server (separate package; mirror CI exactly):
+```bash
+cd server && pytest                                   # server suite (fakeredis)
+ruff check server shared --select E,F,I,UP,B --ignore UP042   # the server lint gate
+```
+
+Notes:
+- The package lives at `client/typefaster`; `make` sets `PYTHONPATH=client`. If
+  running tools directly, prefix with `PYTHONPATH=client`.
+- Client gate = ruff + black + mypy --strict + pytest. **Server CI runs ruff +
+  pytest only — no mypy** (the server has known pre-existing mypy noise from the
+  untyped `typefaster_shared` import; don't chase it).
+- Tests use markers: `unit`, `integration`, `ui` (Textual pilot smoke tests).
+
+## Conventions
+
+- Add/adjust tests for any behavior change. UI gets Textual pilot smoke tests in
+  `tests/integration/test_ui_smoke.py`; logic gets unit/integration tests.
+- Adding a TUI screen: create it under `ui/screens/`, register it in `_PANELS`
+  in `ui/app.py`, and add a menu row in `ui/screens/main_menu.py`. Read-only
+  panels subclass `PanelScreen` (`ui/screens/_base.py`); override `body()`.
+- Adding a SQLite migration: append a `(version, sql)` tuple to `_MIGRATIONS` in
+  `infra/migrations.py` (use `IF NOT EXISTS`; never edit a shipped migration).
+- Adding quotes: edit `scripts/seed_quotes.py`, run it, commit the regenerated
+  `client/typefaster/assets/quotes.json`.
+- Conventional, focused commits. Don't commit generated artifacts (git-ignored).
+
+## Release flow (automated)
+
+Per release, edit the version in **two** files that must stay in sync:
+`pyproject.toml` and `client/typefaster/__init__.py`. Then:
+```bash
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+The tag triggers `.github/workflows/release.yml`, which: builds → publishes to
+PyPI (OIDC Trusted Publishing, gated by the `pypi` environment approval) →
+creates a GitHub Release → **auto-bumps the Homebrew tap formula** (needs the
+`HOMEBREW_TAP_TOKEN` secret) → pushes the server image to GHCR.
+
+## Git / PR workflow
+
+`main` is protected: PRs require a passing CI + a CODEOWNERS review before merge;
+no force-push/deletion. As repo admin you can bypass for your own pushes, but
+prefer feature branches. Branch from `main`; do not commit directly unless asked.
+
+## Key facts / gotchas
+
+- **Public server**: client default `server_url` lives in
+  `client/typefaster/net/token_store.py` (`DEFAULT_SERVER_URL`). It self-heals a
+  dead `*.trycloudflare.com` URL to the default on load.
+- **Online is server-authoritative** with per-IP rate limiting on auth/oauth and
+  app-layer flood guards (see `docs/ddos-protection.md`). A true volumetric DDoS
+  needs an upstream edge (Cloudflare) — app code can't stop it.
+- **Daily challenge** is keyed by UTC date (`datetime.now(UTC).date()`), matching
+  how results are filed — don't switch it to local `date.today()`.
+- **Secrets are never committed.** JWT secret + OAuth client IDs/secret live only
+  in `/opt/typefaster/.env` on the VM. `.env` and `docs/MARKETING.md` are
+  git-ignored.
+- **Two repos by design**: the code repo and the mandatory `homebrew-typefaster`
+  tap (one formula file, auto-bumped by CI). The tap is not a second project to
+  maintain.
+- The TUI footer credits "Anoshor Paul" intentionally; keep it.
+- $0 hosting is a project goal — prefer free tiers; flag anything that adds cost.

{typefaster_cli-0.1.4 → typefaster_cli-0.3.1}/CONTRIBUTING.md

@@ -48,6 +48,25 @@ Quality gates (all must pass):
 - **mypy --strict** — types (the `typefaster` package)
 - **pytest** — tests; add/adjust tests for any behavior change
 
+## Pull request process
+
+`main` is a protected branch — you can't push to it directly. Work on a fork or
+a feature branch and open a PR:
+
+1. **Fork** the repo (or branch, if you're a collaborator) and create a topic
+   branch: `git checkout -b fix/ghost-timing`.
+2. Make your change with tests, then run `make check` locally.
+3. **Open a PR** against `main`. CI runs automatically.
+4. **All checks must be green** — `lint · type · test (3.11/3.12)`,
+   `server lint · test`, and `dependency audit (pip-audit)`.
+5. A **maintainer review is required** (you'll be auto-requested via
+   `CODEOWNERS`), and any review conversations must be resolved before merge.
+6. Keep PRs small and focused; squash-friendly, conventional commit messages
+   help.
+
+Dependency and GitHub-Actions updates are proposed automatically by Dependabot —
+no action needed from contributors.
+
 ## Guidelines
 
 - **Keep the domain pure** and deterministic (time is injected via `Clock`).

typefaster_cli-0.3.1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: typefaster-cli
+Version: 0.3.1
+Summary: A terminal-first typing game inspired by MonkeyType and TypeRacer.
+Project-URL: Homepage, https://github.com/Anoshor/typefaster-cli
+Project-URL: Repository, https://github.com/Anoshor/typefaster-cli
+Author: Anoshor Paul
+License: MIT
+License-File: LICENSE
+Keywords: cli,game,monkeytype,terminal,tui,typeracer,typing,wpm
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.60
+Requires-Dist: typer>=0.12
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: textual-dev>=1.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ⌨ TYPEFASTER
+
+[![CI](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/typefaster-cli)](https://pypi.org/project/typefaster-cli/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A **terminal-first** typing game inspired by MonkeyType and TypeRacer — race
+quotes, beat your ghost, climb leaderboards, and play **live multiplayer** with
+friends. Pure TUI, no browser, no GUI.
+
+```bash
+brew install Anoshor/typefaster/typefaster   # or: pipx install typefaster-cli
+typefaster
+```
+
+---
+
+## Install
+
+**Homebrew** (macOS / Linux)
+```bash
+brew install Anoshor/typefaster/typefaster
+# or tap once, then use the short name:
+brew tap anoshor/typefaster && brew install typefaster
+```
+
+**pipx** (any OS with Python 3.11+) — fastest install
+```bash
+pipx install typefaster-cli
+```
+
+Verify: `typefaster version` · Upgrade: `brew upgrade typefaster` or `pipx upgrade typefaster-cli`
+
+## Play (offline — no account, no internet)
+
+Just run it:
+```bash
+typefaster
+```
+Keyboard-only menu:
+- **Quick Race** — a fresh random quote each time; race your personal-best ghost.
+- **Time Attack** — type for 30 / 60 / 120s (←/→ to change the duration inline).
+- **Practice** — pick a mode/ghost.
+- **Daily Challenge** — same quote for everyone each day, local leaderboard.
+- **🎯 Typing Coach** — see the keys you miss most, a per-key accuracy heatmap, and
+  finger-position tips; press **d** to launch a drill weighted toward your weak
+  keys. All computed locally — no account, no internet, no AI service.
+- **Stats / History / Profile / Leaderboard / Settings**.
+
+**Practice modes (MonkeyType-style):** in **Settings**, toggle **Lowercase only**
+or **Words only** (pure a–z, no punctuation or numbers) to strip the text down.
+
+Live WPM, accuracy, progress, and an animated ghost bar. Backspace corrects
+mistakes (original errors still count, MonkeyType-style). All progress is saved
+locally in SQLite.
+
+Direct commands too:
+```bash
+typefaster race                      # quote race
+typefaster race --mode time --time 60
+typefaster daily
+typefaster stats   |   typefaster history
+```
+
+## Play online (multiplayer lobbies)
+
+It works out of the box against the public server — **no setup**. From the main
+menu pick **Account** to register/login, then **Play Online**:
+
+```text
+Account      → Register / Login (password, GitHub, or Google)
+Play Online  → ➕ Create a lobby  → share the join code
+             → or type a friend's code + Enter to join
+```
+In the waiting room press **R** to ready; the **server** runs the countdown,
+sends everyone the same quote, shows live progress bars, and scores results
+authoritatively (with anti-cheat). **Esc** leaves.
+
+Prefer the CLI?
+```bash
+typefaster register <name>      # or: typefaster login --github / --google
+typefaster lobby create --name "Friday" --time 60
+typefaster lobby join ABC123
+typefaster leaderboard global   # global | daily | weekly
+```
+
+## Self-host the server (optional)
+
+The game ships pointing at a public server, but you can run your own:
+```bash
+git clone https://github.com/Anoshor/typefaster-cli && cd typefaster-cli
+cp .env.example .env            # set TYPEFASTER_JWT_SECRET
+make up                         # Redis + FastAPI server on :8000 (Docker)
+typefaster config set-server http://localhost:8000
+```
+Deploy guides: [`docs/deploy-oracle.md`](docs/deploy-oracle.md) (free 24/7 VM) ·
+[`docs/deploy-fly.md`](docs/deploy-fly.md) · TLS + hardening in
+[`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md).
+
+## How it works
+
+- **Client**: Python · Typer (CLI) · Textual + Rich (TUI) · SQLite (local
+  progress) · httpx + websockets (online).
+- **Server**: FastAPI · WebSockets · Redis · Pydantic — **server-authoritative**
+  race timing and scoring.
+- Deep dive: [`docs/DEEPDIVE.md`](docs/DEEPDIVE.md) · architecture:
+  [`docs/architecture.md`](docs/architecture.md).
+
+## Develop
+
+```bash
+make install     # editable install + dev deps
+make play        # run it
+make check       # ruff + mypy + pytest  (CI parity)
+```
+Contributions welcome! `main` is protected — fork, branch, and open a PR; CI must
+pass and a maintainer review is required before merge. Full guide:
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Crafted by **Anoshor Paul**.

typefaster_cli-0.3.1/README.md

@@ -0,0 +1,123 @@
+# ⌨ TYPEFASTER
+
+[![CI](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/typefaster-cli)](https://pypi.org/project/typefaster-cli/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A **terminal-first** typing game inspired by MonkeyType and TypeRacer — race
+quotes, beat your ghost, climb leaderboards, and play **live multiplayer** with
+friends. Pure TUI, no browser, no GUI.
+
+```bash
+brew install Anoshor/typefaster/typefaster   # or: pipx install typefaster-cli
+typefaster
+```
+
+---
+
+## Install
+
+**Homebrew** (macOS / Linux)
+```bash
+brew install Anoshor/typefaster/typefaster
+# or tap once, then use the short name:
+brew tap anoshor/typefaster && brew install typefaster
+```
+
+**pipx** (any OS with Python 3.11+) — fastest install
+```bash
+pipx install typefaster-cli
+```
+
+Verify: `typefaster version` · Upgrade: `brew upgrade typefaster` or `pipx upgrade typefaster-cli`
+
+## Play (offline — no account, no internet)
+
+Just run it:
+```bash
+typefaster
+```
+Keyboard-only menu:
+- **Quick Race** — a fresh random quote each time; race your personal-best ghost.
+- **Time Attack** — type for 30 / 60 / 120s (←/→ to change the duration inline).
+- **Practice** — pick a mode/ghost.
+- **Daily Challenge** — same quote for everyone each day, local leaderboard.
+- **🎯 Typing Coach** — see the keys you miss most, a per-key accuracy heatmap, and
+  finger-position tips; press **d** to launch a drill weighted toward your weak
+  keys. All computed locally — no account, no internet, no AI service.
+- **Stats / History / Profile / Leaderboard / Settings**.
+
+**Practice modes (MonkeyType-style):** in **Settings**, toggle **Lowercase only**
+or **Words only** (pure a–z, no punctuation or numbers) to strip the text down.
+
+Live WPM, accuracy, progress, and an animated ghost bar. Backspace corrects
+mistakes (original errors still count, MonkeyType-style). All progress is saved
+locally in SQLite.
+
+Direct commands too:
+```bash
+typefaster race                      # quote race
+typefaster race --mode time --time 60
+typefaster daily
+typefaster stats   |   typefaster history
+```
+
+## Play online (multiplayer lobbies)
+
+It works out of the box against the public server — **no setup**. From the main
+menu pick **Account** to register/login, then **Play Online**:
+
+```text
+Account      → Register / Login (password, GitHub, or Google)
+Play Online  → ➕ Create a lobby  → share the join code
+             → or type a friend's code + Enter to join
+```
+In the waiting room press **R** to ready; the **server** runs the countdown,
+sends everyone the same quote, shows live progress bars, and scores results
+authoritatively (with anti-cheat). **Esc** leaves.
+
+Prefer the CLI?
+```bash
+typefaster register <name>      # or: typefaster login --github / --google
+typefaster lobby create --name "Friday" --time 60
+typefaster lobby join ABC123
+typefaster leaderboard global   # global | daily | weekly
+```
+
+## Self-host the server (optional)
+
+The game ships pointing at a public server, but you can run your own:
+```bash
+git clone https://github.com/Anoshor/typefaster-cli && cd typefaster-cli
+cp .env.example .env            # set TYPEFASTER_JWT_SECRET
+make up                         # Redis + FastAPI server on :8000 (Docker)
+typefaster config set-server http://localhost:8000
+```
+Deploy guides: [`docs/deploy-oracle.md`](docs/deploy-oracle.md) (free 24/7 VM) ·
+[`docs/deploy-fly.md`](docs/deploy-fly.md) · TLS + hardening in
+[`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md).
+
+## How it works
+
+- **Client**: Python · Typer (CLI) · Textual + Rich (TUI) · SQLite (local
+  progress) · httpx + websockets (online).
+- **Server**: FastAPI · WebSockets · Redis · Pydantic — **server-authoritative**
+  race timing and scoring.
+- Deep dive: [`docs/DEEPDIVE.md`](docs/DEEPDIVE.md) · architecture:
+  [`docs/architecture.md`](docs/architecture.md).
+
+## Develop
+
+```bash
+make install     # editable install + dev deps
+make play        # run it
+make check       # ruff + mypy + pytest  (CI parity)
+```
+Contributions welcome! `main` is protected — fork, branch, and open a PR; CI must
+pass and a maintainer review is required before merge. Full guide:
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Crafted by **Anoshor Paul**.

{typefaster_cli-0.1.4 → typefaster_cli-0.3.1}/client/typefaster/__init__.py

@@ -1,3 +1,3 @@
 """TYPEFASTER-CLI — a terminal-first typing game."""
 
-__version__ = "0.1.4"
+__version__ = "0.3.1"