keystrike 1.1.0__tar.gz

keystrike-1.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+htmlcov/
+.coverage
+.coverage.*
+*.log
+.DS_Store
+.claude/

keystrike-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Shelemetev
+
+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.

keystrike-1.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: keystrike
+Version: 1.1.0
+Summary: Adaptive drills for your weakest keys
+Project-URL: Homepage, https://github.com/egno/keystrike
+Project-URL: Repository, https://github.com/egno/keystrike
+Project-URL: Issues, https://github.com/egno/keystrike/issues
+Author: Aleksandr Shelemetev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: keybr,textual,tui,tutor,typing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.12
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: textual>=0.85
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Keystrike
+
+Adaptive drills for your weakest keys — an offline terminal typing tutor inspired by
+[keybr.com](https://www.keybr.com/). Stats stay on your machine; nothing phones home.
+
+![Keystrike demo](https://raw.githubusercontent.com/egno/keystrike/v1.1.0/docs/assets/demo.gif)
+
+## What it does
+
+Keystrike tracks how fast and accurately you type each key, unlocks new letters as
+you hit your targets, and generates practice text that overweight your current weak
+spot. Switch keyboard layouts (QWERTY, Dvorak, Colemak, Colemak Mod-DH, or your own
+TOML) and each layout keeps its own history.
+
+## Features
+
+- **Adaptive engine** — row-weighted key unlock order, speed+accuracy confidence
+  gates, Markov word drills with a guaranteed focus letter.
+- **Per-layout stats** — heatmap with per-key confidence and urgency; WPM/accuracy
+  trends; press a key on the heatmap for that key's history.
+- **Daily learn budget** — optional cap on adaptive minutes per calendar day.
+- **Custom layouts** — drop `*.toml` files into your config layouts directory; no
+  restart needed.
+- **Git backup sync** — optional CLI to push/pull settings and sessions to a private
+  remote (union-merge sessions, last-write-wins settings).
+- **Offline by default** — JSONL session logs and a local stats cache under
+  platformdirs paths; sync is opt-in.
+
+## Install
+
+Requires **Python 3.12+** and a terminal with **raw-mode keyboard input**
+([Terminal setup](#terminal-setup)).
+
+```bash
+pipx install keystrike    # or: uv tool install keystrike
+keystrike                 # launch TUI (default)
+keystrike --version
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/egno/keystrike
+cd keystrike
+uv sync --no-dev
+uv run keystrike
+```
+
+## Usage
+
+### Home
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Start adaptive practice |
+| `s` | Stats |
+| `o` | Settings |
+| `l` | Cycle layout |
+| `Ctrl+Q` | Quit |
+
+On other screens, `Esc` / `q` goes back. Settings saves with `Ctrl+S`.
+
+### Practice
+
+Adaptive mode disables backspace — mistakes stay in the record so confidence scores
+stay honest. The HUD shows live accuracy, remaining daily learn time, and the current
+focus key. When a session ends, the next lesson starts automatically unless you go
+back or hit your daily limit.
+
+### Stats
+
+Recent sessions are listed below the heatmap. **Press any key on the heatmap** to
+drill into that key's confidence trend; `Esc` / `q` returns to the overview.
+
+### Settings
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| Layout | `qwerty` | Any bundled or custom layout |
+| Target speed | 46 WPM | Or CPM — your unlock threshold |
+| Letters unlocked up front | 16 | Force-unlocked before confidence gating |
+| Daily learn limit | 10 min | `0` = unlimited |
+
+## Backup sync
+
+Opt-in git sync for backing up or moving data between machines. Requires `git` on
+`PATH` and a **private** remote (sessions contain your typing history).
+
+```bash
+keystrike sync init git@github.com:you/keystrike-backup.git   # one-time
+keystrike sync push      # local → remote
+keystrike sync pull      # remote → local (rebuilds stats cache)
+keystrike sync status    # diff summary
+```
+
+Sync merges sessions by `session_id` (union), resolves settings by `updated_at`
+(last-write-wins), and copies layout files both ways. The stats cache is excluded —
+pull triggers a rebuild.
+
+## Data locations
+
+| Path | Contents |
+| --- | --- |
+| `~/.config/keystrike/settings.toml` | User settings |
+| `~/.config/keystrike/layouts/` | Custom layout TOML files |
+| `~/.config/keystrike/sync.toml` | Sync remote config (after `sync init`) |
+| `~/.local/share/keystrike/sessions/` | Session JSONL logs (Linux) |
+| `~/Library/Application Support/keystrike/` | Same on macOS |
+
+Windows uses `%APPDATA%` / `%LOCALAPPDATA%` equivalents via [platformdirs](https://github.com/tox-dev/platformdirs).
+
+## Terminal setup
+
+Keystrike captures every keystroke in raw mode via [Textual](https://textual.textualize.io/).
+
+Works out of the box in **Terminal.app**, **iTerm2**, and most Linux terminals.
+
+### Windows
+
+Use **[Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701)** —
+the legacy conhost host has unreliable raw-mode support. Run `keystrike` inside WT,
+not cmd.exe. Raw mode is not verified on every Windows build; please
+[open an issue](https://github.com/egno/keystrike/issues) if something breaks.
+
+## Development
+
+```bash
+uv sync                  # runtime + dev (pytest, pyright)
+uv run pytest -q
+uv run pyright
+uv sync --all-groups      # + ruff + snapshot tests (desktop only)
+uv run ruff check
+```
+
+Dependency groups: `dev` (default, pure Python — safe on Termux), `lint` (Ruff),
+`snapshot` (`pytest-textual-snapshot`). Keep native-wheel tools out of `dev`; see
+`pyproject.toml` for why.
+
+Regenerate the demo GIF after UI snapshot changes:
+
+```bash
+uv sync --group snapshot
+uv run pytest tests/presentation/test_snapshots.py --snapshot-update
+uv pip install pillow cairosvg   # one-off; system cairo on macOS/Linux
+uv run python scripts/generate_demo_gif.py
+```
+
+## License
+
+MIT

keystrike-1.1.0/README.md

@@ -0,0 +1,150 @@
+# Keystrike
+
+Adaptive drills for your weakest keys — an offline terminal typing tutor inspired by
+[keybr.com](https://www.keybr.com/). Stats stay on your machine; nothing phones home.
+
+![Keystrike demo](https://raw.githubusercontent.com/egno/keystrike/v1.1.0/docs/assets/demo.gif)
+
+## What it does
+
+Keystrike tracks how fast and accurately you type each key, unlocks new letters as
+you hit your targets, and generates practice text that overweight your current weak
+spot. Switch keyboard layouts (QWERTY, Dvorak, Colemak, Colemak Mod-DH, or your own
+TOML) and each layout keeps its own history.
+
+## Features
+
+- **Adaptive engine** — row-weighted key unlock order, speed+accuracy confidence
+  gates, Markov word drills with a guaranteed focus letter.
+- **Per-layout stats** — heatmap with per-key confidence and urgency; WPM/accuracy
+  trends; press a key on the heatmap for that key's history.
+- **Daily learn budget** — optional cap on adaptive minutes per calendar day.
+- **Custom layouts** — drop `*.toml` files into your config layouts directory; no
+  restart needed.
+- **Git backup sync** — optional CLI to push/pull settings and sessions to a private
+  remote (union-merge sessions, last-write-wins settings).
+- **Offline by default** — JSONL session logs and a local stats cache under
+  platformdirs paths; sync is opt-in.
+
+## Install
+
+Requires **Python 3.12+** and a terminal with **raw-mode keyboard input**
+([Terminal setup](#terminal-setup)).
+
+```bash
+pipx install keystrike    # or: uv tool install keystrike
+keystrike                 # launch TUI (default)
+keystrike --version
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/egno/keystrike
+cd keystrike
+uv sync --no-dev
+uv run keystrike
+```
+
+## Usage
+
+### Home
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Start adaptive practice |
+| `s` | Stats |
+| `o` | Settings |
+| `l` | Cycle layout |
+| `Ctrl+Q` | Quit |
+
+On other screens, `Esc` / `q` goes back. Settings saves with `Ctrl+S`.
+
+### Practice
+
+Adaptive mode disables backspace — mistakes stay in the record so confidence scores
+stay honest. The HUD shows live accuracy, remaining daily learn time, and the current
+focus key. When a session ends, the next lesson starts automatically unless you go
+back or hit your daily limit.
+
+### Stats
+
+Recent sessions are listed below the heatmap. **Press any key on the heatmap** to
+drill into that key's confidence trend; `Esc` / `q` returns to the overview.
+
+### Settings
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| Layout | `qwerty` | Any bundled or custom layout |
+| Target speed | 46 WPM | Or CPM — your unlock threshold |
+| Letters unlocked up front | 16 | Force-unlocked before confidence gating |
+| Daily learn limit | 10 min | `0` = unlimited |
+
+## Backup sync
+
+Opt-in git sync for backing up or moving data between machines. Requires `git` on
+`PATH` and a **private** remote (sessions contain your typing history).
+
+```bash
+keystrike sync init git@github.com:you/keystrike-backup.git   # one-time
+keystrike sync push      # local → remote
+keystrike sync pull      # remote → local (rebuilds stats cache)
+keystrike sync status    # diff summary
+```
+
+Sync merges sessions by `session_id` (union), resolves settings by `updated_at`
+(last-write-wins), and copies layout files both ways. The stats cache is excluded —
+pull triggers a rebuild.
+
+## Data locations
+
+| Path | Contents |
+| --- | --- |
+| `~/.config/keystrike/settings.toml` | User settings |
+| `~/.config/keystrike/layouts/` | Custom layout TOML files |
+| `~/.config/keystrike/sync.toml` | Sync remote config (after `sync init`) |
+| `~/.local/share/keystrike/sessions/` | Session JSONL logs (Linux) |
+| `~/Library/Application Support/keystrike/` | Same on macOS |
+
+Windows uses `%APPDATA%` / `%LOCALAPPDATA%` equivalents via [platformdirs](https://github.com/tox-dev/platformdirs).
+
+## Terminal setup
+
+Keystrike captures every keystroke in raw mode via [Textual](https://textual.textualize.io/).
+
+Works out of the box in **Terminal.app**, **iTerm2**, and most Linux terminals.
+
+### Windows
+
+Use **[Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701)** —
+the legacy conhost host has unreliable raw-mode support. Run `keystrike` inside WT,
+not cmd.exe. Raw mode is not verified on every Windows build; please
+[open an issue](https://github.com/egno/keystrike/issues) if something breaks.
+
+## Development
+
+```bash
+uv sync                  # runtime + dev (pytest, pyright)
+uv run pytest -q
+uv run pyright
+uv sync --all-groups      # + ruff + snapshot tests (desktop only)
+uv run ruff check
+```
+
+Dependency groups: `dev` (default, pure Python — safe on Termux), `lint` (Ruff),
+`snapshot` (`pytest-textual-snapshot`). Keep native-wheel tools out of `dev`; see
+`pyproject.toml` for why.
+
+Regenerate the demo GIF after UI snapshot changes:
+
+```bash
+uv sync --group snapshot
+uv run pytest tests/presentation/test_snapshots.py --snapshot-update
+uv pip install pillow cairosvg   # one-off; system cairo on macOS/Linux
+uv run python scripts/generate_demo_gif.py
+```
+
+## License
+
+MIT

keystrike-1.1.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "keystrike"
+version = "1.1.0"
+description = "Adaptive drills for your weakest keys"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Aleksandr Shelemetev" }]
+keywords = ["typing", "tutor", "keybr", "textual", "tui"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Education",
+]
+
+dependencies = [
+  "textual>=0.85",
+  "platformdirs>=4.2",
+  "typer>=0.12",
+]
+
+[project.scripts]
+keystrike = "keystrike.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/egno/keystrike"
+Repository = "https://github.com/egno/keystrike"
+Issues = "https://github.com/egno/keystrike/issues"
+
+# Runtime deps are in [project].dependencies above.
+# uv sync --no-dev  → runtime only
+# uv sync           → runtime + dev (default group; pure Python)
+# uv sync --all-groups → + lint (Ruff; desktop only)
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "pyright>=1.1.380",
+]
+lint = [
+  "ruff>=0.6",  # manylinux wheels only; sdist → maturin (no Android wheel)
+]
+snapshot = [
+  "pytest-textual-snapshot>=1.1",  # jinja2 → markupsafe; no Android wheels
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/keystrike"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.claude",
+  "/.github",
+  "/tests",
+  "/docs",
+  "/scripts",
+  "/uv.lock",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E", "F", "I", "B", "UP", "SIM", "RUF", "PL", "PT", "ANN",
+]
+ignore = [
+  "ANN401",   # allow Any where genuinely needed
+  "PLR0913",  # constructor with many injected deps is fine
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN", "PLR2004", "S101"]
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["."]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportMissingParameterType = false
+reportUnknownParameterType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportPrivateUsage = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers -m 'not snapshot'"
+markers = [
+  "snapshot: visual regression (requires pytest-textual-snapshot)",
+]

keystrike-1.1.0/src/keystrike/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

keystrike-1.1.0/src/keystrike/__main__.py

@@ -0,0 +1,9 @@
+from keystrike.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

keystrike-1.1.0/src/keystrike/app.py

@@ -0,0 +1,111 @@
+"""Composition root: wire all dependencies and return a ready-to-run KeystrikeApp."""
+
+from dataclasses import dataclass
+from random import Random
+
+from keystrike.application.build_lesson import BuildLesson
+from keystrike.application.learn_budget_use_cases import GetDailyLearnBudget
+from keystrike.application.prepare_practice import PreparePracticeSession
+from keystrike.application.session_use_cases import (
+    FinishSession,
+    RecordKeystroke,
+    StartSession,
+)
+from keystrike.application.settings_use_cases import CycleLayout, UpdateSettings
+from keystrike.application.stats_use_cases import GetHeatmap, GetHistory, RebuildAggregates
+from keystrike.application.sync_use_cases import GetSyncStatus, InitSync, PullSync, PushSync
+from keystrike.infrastructure.aggregates_cache import FileAggregatesCache
+from keystrike.infrastructure.clock import MonotonicClock
+from keystrike.infrastructure.id_gen import UlidGenerator
+from keystrike.infrastructure.languages import BundledLanguageProvider
+from keystrike.infrastructure.layout_repo import CompositeLayoutRepository
+from keystrike.infrastructure.paths import default_paths, ensure_dirs
+from keystrike.infrastructure.session_repo_jsonl import JsonlSessionRepository
+from keystrike.infrastructure.settings_repo_toml import TomlSettingsRepository
+from keystrike.infrastructure.sync_git import GitSyncGateway
+from keystrike.presentation.textual_app import KeystrikeApp
+
+
+@dataclass(frozen=True, slots=True)
+class SyncServices:
+    init: InitSync
+    pull: PullSync
+    push: PushSync
+    status: GetSyncStatus
+
+
+def build_sync() -> SyncServices:
+    paths = default_paths()
+    ensure_dirs(paths)
+    session_repo = JsonlSessionRepository(paths)
+    aggregates_cache = FileAggregatesCache(paths)
+    store = GitSyncGateway(paths)
+    rebuild = RebuildAggregates(repo=session_repo, cache=aggregates_cache)
+    return SyncServices(
+        init=InitSync(gateway=store),
+        pull=PullSync(gateway=store, rebuild=rebuild),
+        push=PushSync(gateway=store),
+        status=GetSyncStatus(gateway=store),
+    )
+
+
+def build() -> KeystrikeApp:
+    paths = default_paths()
+    ensure_dirs(paths)
+
+    clock = MonotonicClock()
+    id_gen = UlidGenerator()
+    session_repo = JsonlSessionRepository(paths)
+    settings_repo = TomlSettingsRepository(paths)
+    layout_repo = CompositeLayoutRepository(paths)
+    aggregates_cache = FileAggregatesCache(paths)
+    language_provider = BundledLanguageProvider()
+
+    start = StartSession(clock=clock, id_gen=id_gen)
+    record = RecordKeystroke(clock=clock, repo=session_repo)
+    finish = FinishSession(
+        clock=clock,
+        repo=session_repo,
+        aggregates_cache=aggregates_cache,
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+    )
+    rebuild_aggregates = RebuildAggregates(repo=session_repo, cache=aggregates_cache)
+    get_heatmap = GetHeatmap(cache=aggregates_cache, settings_repo=settings_repo)
+    get_history = GetHistory(repo=session_repo)
+    get_daily_learn_budget = GetDailyLearnBudget(
+        clock=clock,
+        repo=session_repo,
+        settings_repo=settings_repo,
+    )
+    cycle_layout = CycleLayout(settings_repo=settings_repo, layout_repo=layout_repo)
+    update_settings = UpdateSettings(repo=settings_repo)
+    build_lesson = BuildLesson(
+        layout_repo=layout_repo,
+        aggregates_cache=aggregates_cache,
+        settings_repo=settings_repo,
+        language_provider=language_provider,
+        rng=Random(),
+    )
+    prepare_practice = PreparePracticeSession(
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+        build_lesson=build_lesson,
+        get_daily_learn_budget=get_daily_learn_budget,
+    )
+
+    return KeystrikeApp(
+        clock=clock,
+        start=start,
+        record=record,
+        finish=finish,
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+        prepare_practice=prepare_practice,
+        rebuild_aggregates=rebuild_aggregates,
+        get_heatmap=get_heatmap,
+        get_history=get_history,
+        cycle_layout=cycle_layout,
+        update_settings=update_settings,
+        get_daily_learn_budget=get_daily_learn_budget,
+    )