borse 0.1.0__tar.gz

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

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    name: ✨ Full CI Audit Workflow
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 🧾 Checkout code
+        uses: actions/checkout@v6
+
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: 📦 Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: 📥 Install dependencies
+        run: uv sync
+
+      - name: 🧼 Check formatting
+        run: uv run prek --all-files
+
+      - name: 🧪 Run tests
+        run: uv run prek --all-files --hook-stage pre-push

borse-0.1.0/.github/workflows/conv-commit.yml

@@ -0,0 +1,16 @@
+name: "Conventional commits"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - reopened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  main:
+    uses: vEnhance/dotfiles/.github/workflows/conv-commit.yml@main

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

@@ -0,0 +1,35 @@
+name: PyPI Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/borse
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install Hatch
+        run: pipx install hatch
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/hatch
+          key: ${{ runner.os }}-hatch
+          restore-keys: ${{ runner.os }}-hatch
+      - name: Build package
+        run: hatch build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

borse-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

borse-0.1.0/.pre-commit-config.yml

@@ -0,0 +1,85 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+  - pre-push
+
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        types: [python]
+      - id: ruff
+        name: ruff check
+        args: [--fix]
+        types: [python]
+
+  - repo: https://github.com/JoC0de/pre-commit-prettier
+    rev: v3.8.1
+    hooks:
+      - id: prettier
+        types_or: [css, javascript, markdown, json, toml, yaml]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.3.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args:
+          [
+            feat,
+            fix,
+            build,
+            ci,
+            chore,
+            docs,
+            drop,
+            edit,
+            perf,
+            polish,
+            root,
+            refactor,
+            revert,
+            style,
+            temp,
+            tests,
+          ]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

borse-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# Borse Development Guide
+
+A terminal curses game for practicing Morse code, Braille, and flag semaphore reading.
+
+## Quick Start
+
+```bash
+uv sync           # Install dependencies
+uv run borse      # Run the game
+```
+
+## Project Structure
+
+```
+src/borse/
+├── main.py       # Entry point, curses wrapper
+├── game.py       # Curses UI, menu, and game loop
+├── morse.py      # Morse code encoding (dots and dashes)
+├── braille.py    # Braille 3x2 ASCII art (filled/unfilled circles)
+├── semaphore.py  # Flag semaphore 5x5 ASCII art
+├── words.py      # Common English word list
+├── config.py     # User configuration (~/.config/borse/config.toml)
+└── progress.py   # Daily progress tracking
+```
+
+## Development Commands
+
+```bash
+uv run pytest              # Run all tests (63 tests)
+uv run ruff check src      # Lint
+uv run ruff format src     # Format
+uv run ty check src        # Type check
+```
+
+## Configuration
+
+User config stored in `~/.config/borse/config.toml`:
+
+- `progress_file`: Path to progress JSON file
+- `words_per_game`: Number of words per session (default: 10)
+
+## Adding New Features
+
+- **New encoding**: Add module in `src/borse/`, implement `get_display_lines(word) -> list[str]`
+- **New words**: Edit `COMMON_WORDS` list in `words.py`
+- **Game modes**: Add to `GameMode` enum and `MODE_DISPLAY_FUNCS` in `game.py`

borse-0.1.0/LICENSE

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

borse-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: borse
+Version: 0.1.0
+Summary: A terminal game for practicing Morse code, Braille, and semaphore.
+Project-URL: repository, https://github.com/vEnhance/borse
+Author-email: Evan Chen <evan@evanchen.cc>
+License: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# borse
+
+**borse** is a terminal program meant to practice
+reading braille, Morse code, and semaphore,
+which are common encodings for
+[puzzle hunts](https://web.evanchen.cc/upload/EvanPuzzleCodings.pdf).
+Also supports A1Z26 practice.
+
+## Usage
+
+```bash
+uvx borse
+```
+
+Or you can install from PyPI by using `uv`, `pip`, etc.
+
+## Configuration
+
+Configuration is stored in `~/.config/borse/config.json` by default:
+
+```json
+{
+  "progress_file": "~/.config/borse/progress.json",
+  "words_per_game": 10
+}
+```
+
+Your daily progress is also automatically saved and displayed on the main menu.
+
+## Hints for memorizing the encodings
+
+Actually this is a note-to-self.
+
+### Remembering braille
+
+For Grade 1 (just the letters `A-Z`),
+the chart on [Wikipedia](https://en.wikipedia.org/wiki/English_Braille)
+is helpful!
+The trick is to memorize just the first 10 symbols for `A-J`,
+which only use the upper four dots.
+That's because `K-T` are the same as `A-J` with one extra dot,
+while `UVXYZ` are `A-E` with one extra dot.
+
+In real life, Grade 2 braille has some additional contractions.
+It might be nice to add these into borse at some point.
+
+### Remembering Morse code
+
+In Morse code, the most frequent letters are shorter.
+So I think it's a lot easier to remember Morse code as a binary tree,
+since the common letters will all be towards the top.
+I found [this picture on the Internet](https://slidetodoc.com/binary-trees-binary-tree-structure-root-node-stores/):
+
+![A Morse code binary tree](morse-tree.jpg)
+
+I think the dot looks like 0 and a dash looks like a (rotated) 1,
+so it makes sense to me that dots are in the left of the tree.
+
+Then you can just memorize the letters in each row in order.
+Here are some terrible mnemonics I made up that worked for me
+for the first three rows (you're on your own for the last one):
+
+- `ET`: Eastern Time, or a [1982 movie][et]
+- `IANM`: I Am Not Mad
+- `SURWDKGO`: [SuperUser][su] [ReWrote][rw] [DynamicKernel][dk] in [GO][go]
+
+(Also, `surdwkgo` is also the name of a
+[Taiwanese CodeForces grandmaster](https://codeforces.com/profile/surwdkgo).)
+
+[et]: https://en.wikipedia.org/wiki/E.T._the_Extra-Terrestrial
+[su]: https://en.wikipedia.org/wiki/Su_(Unix)
+[rw]: https://lean-lang.org/doc/reference/latest/Tactic-Proofs/Tactic-Reference/#rw
+[dk]: https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support
+[go]: https://en.wikipedia.org/wiki/Go_(programming_language)
+
+### Remembering semaphore
+
+If you look at a semaphore chart,
+what you'll find is that there are some groups of adjacent letters
+that just differ in one hand rotating clockwise.
+For example, the letters from `A-G` are obtained
+by fixing one arm at 6 o'clock and rotating the other arm
+all the way from 7:30 to 4:30.
+
+So in my head, I organize the letters in "blocks",
+where each block starts with two arms at a 45-degree angle,
+and then having the other arm rotate clockwise.
+The resulting blocks are then easier to remember:
+
+- **A block**: `ABCDEFG`
+- **H block**: `HIKLMN` (note `J` is missing)
+- **O block**: `OPQRS`
+- **T block**: `TUY` (note the additional `Y`)
+- **# block**: `#JV` (this is the weird exceptions one)
+- **W block**: `WX`
+- **Z block**: `Z`
+
+I don't know if `A HOT #WZ` means anything to you.
+
+## Development
+
+Set up by cloning the repository and running
+
+```bash
+uv sync
+uv run prek install
+```
+
+To manually run the linter and tests
+
+```bash
+uv run prek --all-files # run linter
+uv run prek --all-files --hook-stage pre-push
+```
+
+## FAQ
+
+- _Where does the name come from?_
+
+  From `Braille mORse SEmaphore`.
+
+- _Should "braille" be capitalized?_
+
+  [No](https://www.brailleauthority.org/capitalization/capitalization.html).
+
+- _Why would you spend time learning this?_
+
+  It could be a great conversation starter for a first date…

borse-0.1.0/README.md

@@ -0,0 +1,128 @@
+# borse
+
+**borse** is a terminal program meant to practice
+reading braille, Morse code, and semaphore,
+which are common encodings for
+[puzzle hunts](https://web.evanchen.cc/upload/EvanPuzzleCodings.pdf).
+Also supports A1Z26 practice.
+
+## Usage
+
+```bash
+uvx borse
+```
+
+Or you can install from PyPI by using `uv`, `pip`, etc.
+
+## Configuration
+
+Configuration is stored in `~/.config/borse/config.json` by default:
+
+```json
+{
+  "progress_file": "~/.config/borse/progress.json",
+  "words_per_game": 10
+}
+```
+
+Your daily progress is also automatically saved and displayed on the main menu.
+
+## Hints for memorizing the encodings
+
+Actually this is a note-to-self.
+
+### Remembering braille
+
+For Grade 1 (just the letters `A-Z`),
+the chart on [Wikipedia](https://en.wikipedia.org/wiki/English_Braille)
+is helpful!
+The trick is to memorize just the first 10 symbols for `A-J`,
+which only use the upper four dots.
+That's because `K-T` are the same as `A-J` with one extra dot,
+while `UVXYZ` are `A-E` with one extra dot.
+
+In real life, Grade 2 braille has some additional contractions.
+It might be nice to add these into borse at some point.
+
+### Remembering Morse code
+
+In Morse code, the most frequent letters are shorter.
+So I think it's a lot easier to remember Morse code as a binary tree,
+since the common letters will all be towards the top.
+I found [this picture on the Internet](https://slidetodoc.com/binary-trees-binary-tree-structure-root-node-stores/):
+
+![A Morse code binary tree](morse-tree.jpg)
+
+I think the dot looks like 0 and a dash looks like a (rotated) 1,
+so it makes sense to me that dots are in the left of the tree.
+
+Then you can just memorize the letters in each row in order.
+Here are some terrible mnemonics I made up that worked for me
+for the first three rows (you're on your own for the last one):
+
+- `ET`: Eastern Time, or a [1982 movie][et]
+- `IANM`: I Am Not Mad
+- `SURWDKGO`: [SuperUser][su] [ReWrote][rw] [DynamicKernel][dk] in [GO][go]
+
+(Also, `surdwkgo` is also the name of a
+[Taiwanese CodeForces grandmaster](https://codeforces.com/profile/surwdkgo).)
+
+[et]: https://en.wikipedia.org/wiki/E.T._the_Extra-Terrestrial
+[su]: https://en.wikipedia.org/wiki/Su_(Unix)
+[rw]: https://lean-lang.org/doc/reference/latest/Tactic-Proofs/Tactic-Reference/#rw
+[dk]: https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support
+[go]: https://en.wikipedia.org/wiki/Go_(programming_language)
+
+### Remembering semaphore
+
+If you look at a semaphore chart,
+what you'll find is that there are some groups of adjacent letters
+that just differ in one hand rotating clockwise.
+For example, the letters from `A-G` are obtained
+by fixing one arm at 6 o'clock and rotating the other arm
+all the way from 7:30 to 4:30.
+
+So in my head, I organize the letters in "blocks",
+where each block starts with two arms at a 45-degree angle,
+and then having the other arm rotate clockwise.
+The resulting blocks are then easier to remember:
+
+- **A block**: `ABCDEFG`
+- **H block**: `HIKLMN` (note `J` is missing)
+- **O block**: `OPQRS`
+- **T block**: `TUY` (note the additional `Y`)
+- **# block**: `#JV` (this is the weird exceptions one)
+- **W block**: `WX`
+- **Z block**: `Z`
+
+I don't know if `A HOT #WZ` means anything to you.
+
+## Development
+
+Set up by cloning the repository and running
+
+```bash
+uv sync
+uv run prek install
+```
+
+To manually run the linter and tests
+
+```bash
+uv run prek --all-files # run linter
+uv run prek --all-files --hook-stage pre-push
+```
+
+## FAQ
+
+- _Where does the name come from?_
+
+  From `Braille mORse SEmaphore`.
+
+- _Should "braille" be capitalized?_
+
+  [No](https://www.brailleauthority.org/capitalization/capitalization.html).
+
+- _Why would you spend time learning this?_
+
+  It could be a great conversation starter for a first date…

borse-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "borse"
+description = "A terminal game for practicing Morse code, Braille, and semaphore."
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+dependencies = [
+    "tomli>=2.0.0; python_version < '3.11'",
+    "tomli-w>=1.0.0",
+]
+authors = [{ name = "Evan Chen", email = "evan@evanchen.cc" }]
+license = { text = "MIT" }
+urls = { repository = "https://github.com/vEnhance/borse" }
+dynamic = ["version"]
+
+[project.scripts]
+borse = "borse.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/borse/__about__.py"
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[dependency-groups]
+dev = [
+    "prek>=0.3.1",
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+    "ty>=0.0.1a6",
+]