typefaster-cli 0.1.0__tar.gz

typefaster_cli-0.1.0/.dockerignore

@@ -0,0 +1,18 @@
+**/__pycache__/
+**/*.pyc
+.venv/
+venv/
+.git/
+.github/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.db
+*.db-wal
+*.db-shm
+infra/nginx/certs/
+docs/
+tests/
+server/tests/

typefaster_cli-0.1.0/.env.example

@@ -0,0 +1,13 @@
+# Copy to .env and adjust before `docker compose up`.
+
+# REQUIRED: a long random string. Generate with:  openssl rand -hex 32
+TYPEFASTER_JWT_SECRET=
+
+# Comma-separated allowed origins for CORS (use your domain in production).
+TYPEFASTER_CORS_ORIGINS=*
+
+# Access token lifetime in minutes (default 1 day).
+TYPEFASTER_ACCESS_TOKEN_MINUTES=1440
+
+# Host port to expose the server on for local dev (nginx handles prod).
+SERVER_PORT=8000

typefaster_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: 🐛 Bug report
+description: Report something that doesn't work as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for the report! Please fill in the details below.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including any incorrect numbers (WPM/accuracy/time).
+      placeholder: "e.g. Quick Race showed 2222 WPM after a normal run…"
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `typefaster`
+        2. Choose Quick Race
+        3. Type the quote normally
+        4. See …
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Offline race / timing / WPM
+        - Ghost races
+        - Stats / history / leaderboard
+        - Daily challenge
+        - Online multiplayer (server/lobbies)
+        - Install / packaging
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `typefaster version`
+      placeholder: "typefaster 0.1.0"
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, terminal emulator, Python version (`python3 --version`).
+      placeholder: "macOS 14, iTerm2, Python 3.12.3"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / traceback (optional)
+      render: shell

typefaster_cli-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & discussion
+    url: https://github.com/Anoshor/typefaster-cli/discussions
+    about: Ask questions, share scores, or propose ideas before filing an issue.

typefaster_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: 💡 Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do, and what's missing or awkward today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? Mockups / example commands welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Gameplay / modes
+        - Ghosts
+        - Stats / progression
+        - Online multiplayer
+        - Terminal UI / UX
+        - Packaging / distribution
+        - Other
+    validations:
+      required: true

typefaster_cli-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+# Summary
+
+<!-- What does this PR do and why? -->
+
+## Changes
+
+-
+
+## Checklist
+
+- [ ] `make check` passes (ruff + mypy + pytest)
+- [ ] Added/updated tests for the change
+- [ ] Updated docs if behavior or commands changed
+- [ ] (If the server changed) `cd server && pytest` passes
+- [ ] (If quotes changed) regenerated `quotes.json` via `scripts/seed_quotes.py`
+
+## Related issues
+
+<!-- e.g. Closes #123 -->

typefaster_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: lint · type · test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check client tests
+
+      - name: Format check (black)
+        run: black --check client tests
+
+      - name: Type check (mypy)
+        run: mypy
+
+      - name: Test (pytest)
+        run: pytest --cov=typefaster --cov-report=xml
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+
+  server:
+    name: server lint · test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install shared + server
+        run: |
+          python -m pip install ./shared
+          python -m pip install "./server[dev]"
+      - name: Lint (ruff)
+        run: ruff check server shared --select E,F,I,UP,B --ignore UP042
+      - name: Test (pytest)
+        run: cd server && pytest
+
+  build:
+    name: build wheel
+    runs-on: ubuntu-latest
+    needs: [quality, server]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

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

@@ -0,0 +1,55 @@
+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
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        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@v4
+        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@v4
+        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@v4
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

typefaster_cli-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Local game data (SQLite lives in the OS data dir, but ignore stray copies)
+*.db
+*.db-wal
+*.db-shm
+typefaster.db*
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

typefaster_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to TYPEFASTER-CLI
+
+Thanks for your interest in improving TYPEFASTER! Contributions of all kinds are
+welcome — bug reports, quotes, features, docs, and code.
+
+## Project layout
+
+```
+client/typefaster/   the CLI app  (domain · services · infra · ui · net · assets)
+server/app/          online server (FastAPI · ws · repositories · security)
+shared/              schemas, WS protocol, scoring, anti-cheat
+tests/               client tests   ·   server/tests/  server tests
+docs/                architecture, schemas, protocol, deployment, releasing
+```
+
+Architecture follows clean layering: **domain** (pure) ← **services** ←
+**infra**/**ui**. The domain never imports Rich/Textual/SQLite. Please keep new
+code in the right layer.
+
+## Development setup
+
+Requires **Python 3.11+** (the repo is developed against 3.12).
+
+```bash
+git clone https://github.com/Anoshor/typefaster-cli && cd typefaster-cli
+python3.12 -m venv .venv && source .venv/bin/activate
+make install            # editable install + dev deps
+make play               # launch the game
+```
+
+> The package lives at `client/typefaster`. The `Makefile` exports
+> `PYTHONPATH=client`, so `make` targets always work regardless of how the
+> editable install resolves on your OS. If you run tools directly, prefix with
+> `PYTHONPATH=client`.
+
+## Before opening a PR
+
+Run the full check suite — CI runs the same thing:
+
+```bash
+make check              # ruff + mypy + pytest   (client)
+cd server && pip install -e ".[dev]" && pytest   # if you touched the server
+```
+
+Quality gates (all must pass):
+- **ruff** — lint + import sorting
+- **black** — formatting (`make format` to auto-fix)
+- **mypy --strict** — types (the `typefaster` package)
+- **pytest** — tests; add/adjust tests for any behavior change
+
+## Guidelines
+
+- **Keep the domain pure** and deterministic (time is injected via `Clock`).
+- **Add tests** for new logic. UI gets Textual pilot smoke tests; logic gets
+  unit/integration tests.
+- **Conventional, focused commits** and small PRs are easier to review.
+- **Adding quotes?** Edit `scripts/seed_quotes.py`, run it, and commit the
+  regenerated `client/typefaster/assets/quotes.json`
+  (`python scripts/seed_quotes.py && python scripts/seed_quotes.py --check`).
+- Don't commit generated artifacts (`dist/`, caches) — they're git-ignored.
+
+## Reporting bugs / requesting features
+
+Use the issue templates (Bug report / Feature request). For race-result or
+timing bugs, please include your terminal, OS, and the exact steps.
+
+## Code of conduct
+
+Be respectful and constructive. We follow the spirit of the
+[Contributor Covenant](https://www.contributor-covenant.org/).
+
+By contributing, you agree your contributions are licensed under the project's
+[MIT License](LICENSE).

typefaster_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TYPEFASTER-CLI authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typefaster_cli-0.1.0/Makefile

@@ -0,0 +1,68 @@
+# TYPEFASTER-CLI — developer commands
+# Phase 1 (offline) targets are active. `up`/`down` arrive with Phase 2 (Docker/Redis).
+
+.DEFAULT_GOAL := help
+PYTHON ?= python3
+
+# Make the package importable from the monorepo layout (client/typefaster)
+# regardless of how the editable install resolves paths on a given OS.
+export PYTHONPATH := client
+
+.PHONY: help install dev play test test-cov lint format typecheck check seed clean up down
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install package + dev deps in editable mode
+	$(PYTHON) -m pip install -e ".[dev]"
+
+dev: install ## Alias for a full dev environment setup
+	@echo "Dev environment ready. Run 'make play' to start the game."
+
+play: ## Launch the game (offline)
+	typefaster
+
+test: ## Run the test suite
+	pytest
+
+test-cov: ## Run tests with coverage report
+	pytest --cov=typefaster --cov-report=term-missing
+
+lint: ## Ruff lint
+	ruff check client tests
+
+format: ## Auto-format (black) + autofix (ruff)
+	black client tests
+	ruff check --fix client tests
+
+typecheck: ## MyPy static type check
+	mypy
+
+check: lint typecheck test ## Run lint + typecheck + tests (CI parity)
+
+seed: ## Validate / (re)build the quotes dataset
+	$(PYTHON) scripts/seed_quotes.py
+
+clean: ## Remove caches and build artifacts
+	rm -rf .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage build dist *.egg-info
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+
+# ── Online stack (Phase 2) ─────────────────────────────────────────────
+up: ## Start the online stack (redis + server) via Docker Compose
+	docker compose up -d --build
+
+up-proxy: ## Start the full stack including the nginx TLS proxy
+	docker compose --profile proxy up -d --build
+
+down: ## Stop the online stack
+	docker compose down
+
+logs: ## Tail server logs
+	docker compose logs -f server
+
+server-dev: ## Run the server locally (needs a local Redis on :6379)
+	cd server && uvicorn app.main:app --reload --port 8000
+
+server-test: ## Run the server test suite
+	cd server && pytest

typefaster_cli-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: typefaster-cli
+Version: 0.1.0
+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-CLI
+
+[![CI](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Anoshor/typefaster-cli/actions/workflows/ci.yml)
+[![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.
+
+> Not a web app. Not a browser game. Not a desktop GUI.
+> A polished **Python terminal application** that works offline first, then scales to internet multiplayer.
+
+```bash
+typefaster
+```
+
+…and you're racing within seconds. No login, no server, no Docker, no internet required.
+
+---
+
+## Status
+
+| Phase | Scope | State |
+|-------|-------|-------|
+| **Phase 1** | Offline experience: races, ghosts, profile, stats, history, daily challenge | ✅ **Implemented & tested** |
+| **Phase 2** | Online multiplayer: FastAPI + Redis + WebSockets, auth, lobbies, leaderboards, anti-cheat, Docker | ✅ **Implemented & tested** |
+
+Both phases are implemented. Offline play needs only `pip install`; online play
+adds a Dockerized server (see [Online play](#online-play-phase-2)).
+
+---
+
+## What Phase 1 delivers
+
+- **Instant offline races** — random quote, live WPM / accuracy / progress / timer.
+- **30 / 60 / 120 second** race modes.
+- **Ghost races** against your `personal-best`, `last`, or a `random` historical run, animated live.
+- **Local profile & stats** in SQLite — races played/won, best/avg WPM, best/avg accuracy, total chars, total time, full history.
+- **Daily challenge** — same quote for everyone each day, with a local daily leaderboard.
+- **Polished TUI** built on **Textual** + **Rich**, keyboard-only, resize-aware.
+
+## Planned CLI
+
+```bash
+typefaster                                   # launch straight into the game
+typefaster race --time 60 --ghost personal-best
+typefaster race --ghost last
+typefaster race --ghost random
+typefaster daily
+typefaster profile
+typefaster stats
+typefaster history
+```
+
+---
+
+## Tech stack
+
+**Client (Phase 1):** Python 3.11+, Typer, Rich, Textual, SQLite (stdlib), platformdirs.
+**Server (Phase 2):** FastAPI, asyncio, WebSockets, Pydantic, Redis, Docker Compose.
+
+## Repository layout
+
+```
+typefaster-cli/
+├── client/typefaster/   # CLI app: domain · services · infra · ui · net · assets
+├── server/app/          # FastAPI server: routers · ws · repositories · security
+├── shared/              # shared schemas, WS protocol, scoring, anti-cheat
+├── infra/               # redis.conf · nginx.conf (TLS + WS proxy)
+├── docs/                # architecture, schemas, protocol, deployment, roadmap
+├── tests/               # client unit · integration · UI smoke
+├── scripts/             # quote dataset tooling
+├── docker-compose.yml   # redis + server (+ nginx via --profile proxy)
+├── pyproject.toml · Makefile · README.md
+```
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design.
+
+## Online play (Phase 2)
+
+Run the server stack (Redis + FastAPI + WebSockets) with Docker:
+
+```bash
+cp .env.example .env       # set TYPEFASTER_JWT_SECRET
+make up                    # redis + server on :8000  (make up-proxy adds nginx TLS)
+```
+
+Then, from the client:
+
+```bash
+typefaster register alice          # create an account
+typefaster login alice
+typefaster lobby create --name "Friday Sprint" --time 60
+typefaster lobby join ABC123       # join a friend's private lobby
+typefaster lobby list              # browse public lobbies
+typefaster leaderboard global      # global | daily | weekly
+typefaster logout
+```
+
+The server is **authoritative**: it controls race start/finish, re-scores every
+result, and runs anti-cheat before writing leaderboards. See the docs:
+
+- [API specification](docs/api-spec.md)
+- [WebSocket protocol](docs/websocket-protocol.md)
+- [Redis schema](docs/redis-schema.md)
+- [Deployment guide (single Linux VM)](docs/deployment.md)
+
+The client points at `http://localhost:8000` by default; set `server_url` in
+`~/.config/typefaster/auth.json` to target a deployed server.
+
+## Development
+
+```bash
+make install   # editable install + dev deps
+make play      # launch the game
+make test      # pytest
+make lint      # ruff
+make typecheck # mypy
+make format    # black + ruff --fix
+make check     # lint + typecheck + test (CI parity)
+```
+
+> **Note on the monorepo layout:** the importable package lives at
+> `client/typefaster`. A normal install (`pip install .`, used by Docker and end
+> users) places it on the path automatically. For local development the
+> `Makefile` exports `PYTHONPATH=client`, so `make play` / `make test` always
+> work. If you invoke tools directly, prefix with `PYTHONPATH=client` (e.g.
+> `PYTHONPATH=client python -m typefaster`).
+
+## Design preferences locked for Phase 1
+
+- **Quotes:** curated public-domain set, tagged `short` / `medium` / `long` for difficulty buckets and 30/60/120s fit.
+- **Backspace:** allowed (MonkeyType-style) — corrections permitted, original errors still count toward accuracy; exposed as a Settings toggle.
+
+## License
+
+MIT.