koreader_D00901 0.1.0__tar.gz

koreader_d00901-0.1.0/LICENSE

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

koreader_d00901-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: koreader_D00901
+Version: 0.1.0
+Summary: Install KOReader on a Kindle Keyboard (K3) from Linux.
+Keywords: kindle,koreader,kindle-keyboard,k3,jailbreak,e-reader
+Author: Seth Barrett
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Installation/Setup
+Requires-Dist: textual>=8.2,<9
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/sethbarrett50/koreader_D00901
+Project-URL: Issues, https://github.com/sethbarrett50/koreader_D00901/issues
+Description-Content-Type: text/markdown
+
+# KOReader installer for the Kindle Keyboard (K3)
+
+Use this at your own risk: it modifies your Kindle's firmware and I am not responsible for a unit that stops working.
+
+## What this does
+
+`koreader-d00901` (the `koreader_D00901` Python package) downloads pinned, checksum-verified packages and stages them on a Kindle Keyboard (K3) that is mounted as a USB drive. It chains:
+
+1. The jailbreak, which lets the Kindle install custom update packages.
+2. MKK (the developer certificates the Kindle needs to run custom Kindlets such as KUAL).
+   MKK's 2014 certificates expired in April 2025, so the installer then applies NiLuJe's 2025 developer keystore update, which adds the certificates current KUAL is signed with.
+3. KUAL (the Kindle Unified Application Launcher), copied into `documents/`.
+4. KOReader, merged into the Kindle's root.
+5. Optionally, USBNetwork (`--usbnet`), for ssh access over USB.
+
+## Before you start
+
+- Charge the Kindle fully.
+- Deregister it: Settings > Registration > Deregister.
+- Turn wireless off.
+- Find your firmware version at the bottom of the Settings page (for example 3.4.2).
+- Find your serial prefix: the first four characters of the serial number (B006, B008 or B00A), listed under Device Info or on the back of the unit.
+
+## Which files your Kindle needs
+
+The installer picks the right files from your serial prefix and firmware range.
+
+| Serial prefix | Variant |
+| ------------- | ------- |
+| B006          | k3g     |
+| B008          | k3w     |
+| B00A          | k3gb    |
+
+Firmware 3.0-3.2 uses the jailbreak file marked `-3.0-to-3.2`. Firmware 3.3-3.4 uses the plain jailbreak file. The installer asks for the range as `3.0-3.2` or `3.3-3.4`.
+
+## Running the installer
+
+Install from PyPI, then connect the Kindle in USB drive mode and start the full-screen installer:
+
+```
+uv tool install koreader_D00901    # or: pipx install koreader_D00901
+koreader-d00901-tui
+```
+
+To run it once without installing anything, use `uvx --from koreader_D00901 koreader-d00901-tui`. From a clone of this repo, use `uv run koreader-d00901-tui`.
+
+Pick the firmware range and serial prefix, press **Install**, and follow the on-screen steps. Between updates it shows what to do on the Kindle, has an **Eject Kindle** button, and waits for **Continue**. **Dry run** shows the plan without changing anything.
+
+The same install also runs as a plain terminal script. Do a dry run first: it prints the plan and changes nothing.
+
+```
+uv run koreader-d00901 --dry-run
+```
+
+Then run it for real:
+
+```
+uv run koreader-d00901
+```
+
+Flags (both commands take the same ones, except that `--dry-run` is CLI-only):
+
+- `--dry-run`: print the plan only.
+- `--mount PATH`: the Kindle's USB mount point. Without it the installer looks for a volume labelled Kindle.
+- `--fw RANGE`: firmware range, `3.0-3.2` or `3.3-3.4`. Asked interactively if omitted.
+- `--prefix PREFIX`: serial prefix, `B006`, `B008` or `B00A`. Asked interactively if omitted.
+- `--usbnet`: also install USBNetwork.
+- `--wipe-books`: delete the existing books in `documents/` before installing, which is handy for second-hand units. It lists everything it will delete and asks you to type `wipe` (the TUI shows a confirmation dialog). It keeps `KUAL-KDK-1.0.azw2` and the `dictionaries` folder, and never touches anything outside `documents/`. With `--dry-run` it only lists what it would delete.
+- `--cache DIR`: where downloads are kept (default `~/.cache/k3-koreader`).
+- `--log-file FILE`: where the debug log goes (default `CACHE/install.log`).
+- `-v`, `--verbose`: also print debug logging on the terminal (CLI only).
+- `--version`: print the version.
+
+Every run writes a debug log. If an install fails, check `~/.cache/k3-koreader/install.log` first.
+
+Each download is checked against the sha256 in `packages.json` and rejected if it does not match.
+
+## On the Kindle
+
+For each update the installer stages one `.bin` file and pauses. Then:
+
+1. Eject and unplug the Kindle (safely eject it first; the update cannot run in USB drive mode).
+2. Press [HOME] > [MENU] > Settings > [MENU] > Update Your Kindle.
+3. Wait for the reboot, reconnect in USB drive mode and press Enter in the installer.
+
+The order is jailbreak, then MKK, then the 2025 keystore (then USBNetwork if requested). After the last step, eject the Kindle, open KUAL from the library and choose KOReader.
+
+## If something goes wrong
+
+- Update Your Kindle is greyed out: the wrong file was staged. Check your serial prefix and firmware range and run the installer again.
+- Never force an update by rebooting the Kindle by hand.
+- If the Kindle hangs, hold the power button for about 15 seconds for a hard reboot.
+- Deregistering or an over-the-air (OTA) update can remove the developer certificates. Reinstall MKK when that happens.
+- KUAL says the title is "not signed by a registered developer": the 2025 keystore update did not apply. Copy `Update-mkk-20250419-<variant>-<prefix>_keystore-install.bin` from `DevCerts-20250419-KeyStore.zip` to the Kindle root and run Update Your Kindle again.
+
+## USBNetwork (optional)
+
+After installing with `--usbnet`, enable it from the Kindle's search bar:
+
+1. Type `;debugOn` and press Enter.
+2. Type `~usbNetwork` and press Enter.
+3. Type `;debugOff` and press Enter.
+
+Then connect over USB. On Debian the Kindle appears as a USB network interface, often `usb0` (check with `ip link`). Assign the computer side its address:
+
+```
+sudo ip addr add 192.168.2.1/24 dev usb0
+sudo ip link set usb0 up
+```
+
+(The older equivalent is `sudo ifconfig usb0 192.168.2.1`.) Then use `ssh root@192.168.2.2`. Login is passwordless only over USB with Wi-Fi mode off.
+
+Before ejecting, bring the interface down with `sudo ip link set usb0 down`, and enter `~usbNetwork` again on the Kindle to switch back to USB drive mode.
+
+## Pinned packages
+
+| Package    | File                                     | sha256 (first 12) |
+| ---------- | ---------------------------------------- | ----------------- |
+| jailbreak  | kindle-jailbreak-0.13.N-r18833.tar.xz    | 8f5c8a78e3c4      |
+| mkk        | kindle-mkk-20141129-r18833.tar.xz        | 3d7289f1ddcf      |
+| keystore   | DevCerts-20250419-KeyStore.zip           | 48426add32e3      |
+| kual       | KUAL-v2.7.37-gfcb45b5-20250419.tar.xz    | 40c4b6871221      |
+| usbnet     | kindle-usbnetwork-0.57.N-k3.zip          | 7d210bc41619      |
+| koreader   | koreader-kindle-legacy-v2026.07.1.zip    | 0ed8d5eec422      |
+
+## Credits
+
+- Jailbreak: https://www.mobileread.com/forums/showthread.php?t=225030
+- 2025 developer keystore (NiLuJe, 2025-04-19): https://www.mobileread.com/forums/attachment.php?attachmentid=215127&d=1745098511
+- KUAL: https://www.mobileread.com/forums/showthread.php?t=203326
+- USBNetwork: https://www.mobileread.com/forums/showthread.php?t=88004
+- KOReader: https://github.com/koreader/koreader
+
+## Development
+
+```
+make sync       # uv sync --dev (ruff, ty, pytest)
+make lint       # ruff format + ruff check --fix
+make typecheck  # ty check
+make test       # pytest
+make ci         # everything CI runs, without fixes
+make build      # sdist + wheel into dist/
+make smoke      # install the wheel in a clean env and run both commands
+make version-check  # package changed since the last tag? then the version must be bumped
+uv run python -m koreader_d00901.pins   # re-download every pin and check it (about 100 MB)
+```
+
+CI (`.github/workflows/ci.yml`) runs `make ci`, `make build` and `make smoke` on Python 3.14 for every push and PR. A weekly pin check (`.github/workflows/pins.yml`, also runnable from the Actions tab) re-downloads every package in `packages.json`, verifies its sha256, and confirms that it still holds every file the installer stages for each serial prefix and firmware range. If upstream drifts, it opens an issue (or comments on the open one).
+
+### Releasing
+
+1. Bump `version` in `pyproject.toml` (`uv version --bump patch`, `minor` or `major`), then merge to `main`. CI's `make version-check` fails any PR that changes `src/`, the dependencies or `uv.lock` since the last `vX.Y.Z` tag without raising the version, so every release gets a new version on PyPI.
+2. Tag the merge commit `vX.Y.Z` (matching that version) and push the tag: `git tag v0.1.0 && git push origin v0.1.0`.
+3. `.github/workflows/release.yml` checks the tag against the version, runs `make ci`, builds and smoke-tests the wheel, and publishes it to PyPI through trusted publishing (no API token is stored anywhere).
+
+One-time setup on PyPI, before the first release: at https://pypi.org/manage/account/publishing/ add a pending trusted publisher with project `koreader_D00901`, owner `sethbarrett50`, repository `koreader_D00901`, workflow `release.yml` and environment `pypi`. In the GitHub repo settings, create an environment named `pypi` (adding yourself as a required reviewer gives you a manual approval step before each upload).
+
+The code lives in `src/koreader_d00901/`:
+
+- `plan.py`: which files a given serial prefix and firmware range need.
+- `packages.py`: downloading, verifying and unpacking the packages pinned in `packages.json`.
+- `device.py`: everything that touches the Kindle's USB volume.
+- `cli.py` / `tui.py`: the two front ends.
+- `errors.py`: `InstallerError` and its subclasses, which are reported to the user as one line.
+- `logs.py`: logging setup (a debug log file on every run).
+- `pins.py`: the upstream pin check used by the weekly workflow.

koreader_d00901-0.1.0/README.md

@@ -0,0 +1,166 @@
+# KOReader installer for the Kindle Keyboard (K3)
+
+Use this at your own risk: it modifies your Kindle's firmware and I am not responsible for a unit that stops working.
+
+## What this does
+
+`koreader-d00901` (the `koreader_D00901` Python package) downloads pinned, checksum-verified packages and stages them on a Kindle Keyboard (K3) that is mounted as a USB drive. It chains:
+
+1. The jailbreak, which lets the Kindle install custom update packages.
+2. MKK (the developer certificates the Kindle needs to run custom Kindlets such as KUAL).
+   MKK's 2014 certificates expired in April 2025, so the installer then applies NiLuJe's 2025 developer keystore update, which adds the certificates current KUAL is signed with.
+3. KUAL (the Kindle Unified Application Launcher), copied into `documents/`.
+4. KOReader, merged into the Kindle's root.
+5. Optionally, USBNetwork (`--usbnet`), for ssh access over USB.
+
+## Before you start
+
+- Charge the Kindle fully.
+- Deregister it: Settings > Registration > Deregister.
+- Turn wireless off.
+- Find your firmware version at the bottom of the Settings page (for example 3.4.2).
+- Find your serial prefix: the first four characters of the serial number (B006, B008 or B00A), listed under Device Info or on the back of the unit.
+
+## Which files your Kindle needs
+
+The installer picks the right files from your serial prefix and firmware range.
+
+| Serial prefix | Variant |
+| ------------- | ------- |
+| B006          | k3g     |
+| B008          | k3w     |
+| B00A          | k3gb    |
+
+Firmware 3.0-3.2 uses the jailbreak file marked `-3.0-to-3.2`. Firmware 3.3-3.4 uses the plain jailbreak file. The installer asks for the range as `3.0-3.2` or `3.3-3.4`.
+
+## Running the installer
+
+Install from PyPI, then connect the Kindle in USB drive mode and start the full-screen installer:
+
+```
+uv tool install koreader_D00901    # or: pipx install koreader_D00901
+koreader-d00901-tui
+```
+
+To run it once without installing anything, use `uvx --from koreader_D00901 koreader-d00901-tui`. From a clone of this repo, use `uv run koreader-d00901-tui`.
+
+Pick the firmware range and serial prefix, press **Install**, and follow the on-screen steps. Between updates it shows what to do on the Kindle, has an **Eject Kindle** button, and waits for **Continue**. **Dry run** shows the plan without changing anything.
+
+The same install also runs as a plain terminal script. Do a dry run first: it prints the plan and changes nothing.
+
+```
+uv run koreader-d00901 --dry-run
+```
+
+Then run it for real:
+
+```
+uv run koreader-d00901
+```
+
+Flags (both commands take the same ones, except that `--dry-run` is CLI-only):
+
+- `--dry-run`: print the plan only.
+- `--mount PATH`: the Kindle's USB mount point. Without it the installer looks for a volume labelled Kindle.
+- `--fw RANGE`: firmware range, `3.0-3.2` or `3.3-3.4`. Asked interactively if omitted.
+- `--prefix PREFIX`: serial prefix, `B006`, `B008` or `B00A`. Asked interactively if omitted.
+- `--usbnet`: also install USBNetwork.
+- `--wipe-books`: delete the existing books in `documents/` before installing, which is handy for second-hand units. It lists everything it will delete and asks you to type `wipe` (the TUI shows a confirmation dialog). It keeps `KUAL-KDK-1.0.azw2` and the `dictionaries` folder, and never touches anything outside `documents/`. With `--dry-run` it only lists what it would delete.
+- `--cache DIR`: where downloads are kept (default `~/.cache/k3-koreader`).
+- `--log-file FILE`: where the debug log goes (default `CACHE/install.log`).
+- `-v`, `--verbose`: also print debug logging on the terminal (CLI only).
+- `--version`: print the version.
+
+Every run writes a debug log. If an install fails, check `~/.cache/k3-koreader/install.log` first.
+
+Each download is checked against the sha256 in `packages.json` and rejected if it does not match.
+
+## On the Kindle
+
+For each update the installer stages one `.bin` file and pauses. Then:
+
+1. Eject and unplug the Kindle (safely eject it first; the update cannot run in USB drive mode).
+2. Press [HOME] > [MENU] > Settings > [MENU] > Update Your Kindle.
+3. Wait for the reboot, reconnect in USB drive mode and press Enter in the installer.
+
+The order is jailbreak, then MKK, then the 2025 keystore (then USBNetwork if requested). After the last step, eject the Kindle, open KUAL from the library and choose KOReader.
+
+## If something goes wrong
+
+- Update Your Kindle is greyed out: the wrong file was staged. Check your serial prefix and firmware range and run the installer again.
+- Never force an update by rebooting the Kindle by hand.
+- If the Kindle hangs, hold the power button for about 15 seconds for a hard reboot.
+- Deregistering or an over-the-air (OTA) update can remove the developer certificates. Reinstall MKK when that happens.
+- KUAL says the title is "not signed by a registered developer": the 2025 keystore update did not apply. Copy `Update-mkk-20250419-<variant>-<prefix>_keystore-install.bin` from `DevCerts-20250419-KeyStore.zip` to the Kindle root and run Update Your Kindle again.
+
+## USBNetwork (optional)
+
+After installing with `--usbnet`, enable it from the Kindle's search bar:
+
+1. Type `;debugOn` and press Enter.
+2. Type `~usbNetwork` and press Enter.
+3. Type `;debugOff` and press Enter.
+
+Then connect over USB. On Debian the Kindle appears as a USB network interface, often `usb0` (check with `ip link`). Assign the computer side its address:
+
+```
+sudo ip addr add 192.168.2.1/24 dev usb0
+sudo ip link set usb0 up
+```
+
+(The older equivalent is `sudo ifconfig usb0 192.168.2.1`.) Then use `ssh root@192.168.2.2`. Login is passwordless only over USB with Wi-Fi mode off.
+
+Before ejecting, bring the interface down with `sudo ip link set usb0 down`, and enter `~usbNetwork` again on the Kindle to switch back to USB drive mode.
+
+## Pinned packages
+
+| Package    | File                                     | sha256 (first 12) |
+| ---------- | ---------------------------------------- | ----------------- |
+| jailbreak  | kindle-jailbreak-0.13.N-r18833.tar.xz    | 8f5c8a78e3c4      |
+| mkk        | kindle-mkk-20141129-r18833.tar.xz        | 3d7289f1ddcf      |
+| keystore   | DevCerts-20250419-KeyStore.zip           | 48426add32e3      |
+| kual       | KUAL-v2.7.37-gfcb45b5-20250419.tar.xz    | 40c4b6871221      |
+| usbnet     | kindle-usbnetwork-0.57.N-k3.zip          | 7d210bc41619      |
+| koreader   | koreader-kindle-legacy-v2026.07.1.zip    | 0ed8d5eec422      |
+
+## Credits
+
+- Jailbreak: https://www.mobileread.com/forums/showthread.php?t=225030
+- 2025 developer keystore (NiLuJe, 2025-04-19): https://www.mobileread.com/forums/attachment.php?attachmentid=215127&d=1745098511
+- KUAL: https://www.mobileread.com/forums/showthread.php?t=203326
+- USBNetwork: https://www.mobileread.com/forums/showthread.php?t=88004
+- KOReader: https://github.com/koreader/koreader
+
+## Development
+
+```
+make sync       # uv sync --dev (ruff, ty, pytest)
+make lint       # ruff format + ruff check --fix
+make typecheck  # ty check
+make test       # pytest
+make ci         # everything CI runs, without fixes
+make build      # sdist + wheel into dist/
+make smoke      # install the wheel in a clean env and run both commands
+make version-check  # package changed since the last tag? then the version must be bumped
+uv run python -m koreader_d00901.pins   # re-download every pin and check it (about 100 MB)
+```
+
+CI (`.github/workflows/ci.yml`) runs `make ci`, `make build` and `make smoke` on Python 3.14 for every push and PR. A weekly pin check (`.github/workflows/pins.yml`, also runnable from the Actions tab) re-downloads every package in `packages.json`, verifies its sha256, and confirms that it still holds every file the installer stages for each serial prefix and firmware range. If upstream drifts, it opens an issue (or comments on the open one).
+
+### Releasing
+
+1. Bump `version` in `pyproject.toml` (`uv version --bump patch`, `minor` or `major`), then merge to `main`. CI's `make version-check` fails any PR that changes `src/`, the dependencies or `uv.lock` since the last `vX.Y.Z` tag without raising the version, so every release gets a new version on PyPI.
+2. Tag the merge commit `vX.Y.Z` (matching that version) and push the tag: `git tag v0.1.0 && git push origin v0.1.0`.
+3. `.github/workflows/release.yml` checks the tag against the version, runs `make ci`, builds and smoke-tests the wheel, and publishes it to PyPI through trusted publishing (no API token is stored anywhere).
+
+One-time setup on PyPI, before the first release: at https://pypi.org/manage/account/publishing/ add a pending trusted publisher with project `koreader_D00901`, owner `sethbarrett50`, repository `koreader_D00901`, workflow `release.yml` and environment `pypi`. In the GitHub repo settings, create an environment named `pypi` (adding yourself as a required reviewer gives you a manual approval step before each upload).
+
+The code lives in `src/koreader_d00901/`:
+
+- `plan.py`: which files a given serial prefix and firmware range need.
+- `packages.py`: downloading, verifying and unpacking the packages pinned in `packages.json`.
+- `device.py`: everything that touches the Kindle's USB volume.
+- `cli.py` / `tui.py`: the two front ends.
+- `errors.py`: `InstallerError` and its subclasses, which are reported to the user as one line.
+- `logs.py`: logging setup (a debug log file on every run).
+- `pins.py`: the upstream pin check used by the weekly workflow.

koreader_d00901-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "koreader_D00901"
+version = "0.1.0"
+description = "Install KOReader on a Kindle Keyboard (K3) from Linux."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "kindle",
+    "koreader",
+    "kindle-keyboard",
+    "k3",
+    "jailbreak",
+    "e-reader",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Installation/Setup",
+]
+dependencies = ["textual>=8.2,<9"]
+
+[[project.authors]]
+name = "Seth Barrett"
+
+[project.urls]
+Homepage = "https://github.com/sethbarrett50/koreader_D00901"
+Issues = "https://github.com/sethbarrett50/koreader_D00901/issues"
+
+[project.scripts]
+koreader-d00901 = "koreader_d00901.cli:main"
+koreader-d00901-tui = "koreader_d00901.tui:main"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "koreader_d00901"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.15,<1.0.0",
+    "ty>=0.0.97,<0.1.0",
+    "pytest>=9.0.3,<10.0.0",
+]

koreader_d00901-0.1.0/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "koreader_D00901"
+version = "0.1.0"
+description = "Install KOReader on a Kindle Keyboard (K3) from Linux."
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{ name = "Seth Barrett" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["kindle", "koreader", "kindle-keyboard", "k3", "jailbreak", "e-reader"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Installation/Setup",
+]
+dependencies = [
+    "textual>=8.2,<9",
+]
+
+[project.urls]
+Homepage = "https://github.com/sethbarrett50/koreader_D00901"
+Issues = "https://github.com/sethbarrett50/koreader_D00901/issues"
+
+[project.scripts]
+koreader-d00901 = "koreader_d00901.cli:main"
+koreader-d00901-tui = "koreader_d00901.tui:main"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "koreader_d00901"
+
+[dependency-groups]
+dev = [
+  "ruff>=0.15.15,<1.0.0",
+  "ty>=0.0.97,<0.1.0",
+  "pytest>=9.0.3,<10.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.14"

koreader_d00901-0.1.0/src/koreader_d00901/__init__.py

@@ -0,0 +1,8 @@
+"""Install KOReader on a Kindle Keyboard (K3) from Linux."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version('koreader_D00901')
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = '0.0.0'

koreader_d00901-0.1.0/src/koreader_d00901/__main__.py

@@ -0,0 +1,3 @@
+from koreader_d00901.cli import main
+
+raise SystemExit(main())

koreader_d00901-0.1.0/src/koreader_d00901/cli.py

@@ -0,0 +1,168 @@
+"""Command-line installer: prompts on the terminal and waits for Enter between device updates."""
+
+import argparse
+import logging
+import sys
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from koreader_d00901 import __version__, device, packages, plan
+from koreader_d00901.errors import ConfigError, InstallerError
+from koreader_d00901.logs import DEFAULT_CACHE, setup_logging
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+log = logging.getLogger(__name__)
+
+DEVICE_STEPS = (
+    '  First safely eject (unmount) the Kindle and unplug it from the computer;\n'
+    '  the update cannot run while it is in USB drive mode.\n'
+    '  Then on the Kindle: [HOME] > [MENU] > Settings > [MENU] > Update Your Kindle.\n'
+    '  Never reboot the Kindle by hand to force the update.\n'
+    "  If 'Update Your Kindle' is greyed out, the wrong file was staged."
+)
+DONE_MESSAGE = 'Done. Eject the Kindle, then on the device open the KUAL book in your library and choose KOReader.'
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument('--mount', type=Path, help='Kindle USB mount point (auto-detected if omitted)')
+    parser.add_argument('--fw', help='firmware range: ' + ', '.join(plan.FIRMWARE_RANGES))
+    parser.add_argument('--prefix', help='serial prefix: ' + ', '.join(plan.VARIANTS))
+    parser.add_argument('--usbnet', action='store_true', help='also install USBNetwork')
+    parser.add_argument(
+        '--wipe-books', action='store_true', help='delete the existing books in documents/ first (asks to confirm)'
+    )
+    parser.add_argument('--cache', type=Path, default=DEFAULT_CACHE, help='download cache directory')
+    parser.add_argument('--log-file', type=Path, help='debug log file (default CACHE/install.log)')
+    parser.add_argument('-v', '--verbose', action='store_true', help='show debug logging on the console')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+
+def _ask_valid(prompt: str, value: str | None, check: Callable[[str], str], flag: str) -> str:
+    """Validate a flag value (fatal when bad) or prompt until one validates."""
+    if value is not None:
+        try:
+            return check(value)
+        except ConfigError as exc:
+            raise ConfigError(f'{flag}: {exc}') from None
+    while True:
+        try:
+            return check(input(prompt))
+        except ConfigError as exc:
+            print(f'  {exc}')
+
+
+def _copy_with_progress(pairs: list[tuple[Path, Path]], label: str) -> None:
+    """Copy (src, dst) file pairs, printing a running count so slow USB writes don't look hung."""
+    every = max(1, len(pairs) // 100)
+
+    def show(i: int, total: int) -> None:
+        if i % every == 0 or i == total:
+            print(f'\r  {label}: {i}/{total} files', end='', flush=True)
+
+    device.copy_files(pairs, show)
+    print()
+
+
+def _update_step(mount: Path, bin_path: Path, label: str) -> None:
+    device.stage_update(mount, bin_path)
+    print(f'\nStaged {bin_path.name} ({label}).')
+    print(DEVICE_STEPS)
+    input('Press Enter once the Kindle has rebooted and remounted... ')
+    while not mount.is_dir():
+        log.debug('waiting for %s to come back', mount)
+        input(f'Kindle not mounted at {mount} yet; reconnect it in USB drive mode and press Enter... ')
+    if device.update_pending(mount, bin_path):
+        log.warning('%s is still at the Kindle root; the update may not have applied.', bin_path.name)
+
+
+def describe(entries: list[Path], limit: int = 20) -> list[str]:
+    """Display lines for entries of documents/, capped at limit."""
+    lines = [f'  {p.name}{"/" if p.is_dir() else ""}' for p in entries[:limit]]
+    if len(entries) > limit:
+        lines.append(f'  ...and {len(entries) - limit} more')
+    return lines
+
+
+def _wipe_step(mount: Path, dry_run: bool) -> None:
+    entries = device.list_books(mount)
+    if not entries:
+        print('No books to delete in documents/.')
+        return
+    verb = 'would delete' if dry_run else 'will delete'
+    print(f'--wipe-books {verb} {len(entries)} entries in documents/ (keeping KUAL and dictionaries):')
+    print('\n'.join(describe(entries)))
+    if dry_run:
+        return
+    answer = input(f"Type 'wipe' to delete these {len(entries)} entries (anything else skips this step): ")
+    if answer.strip().lower() != 'wipe':
+        print('Skipped; no books were deleted.')
+        log.info('wipe declined')
+        return
+    removed = device.wipe_books(mount, entries)
+    print(f'Deleted {removed} entries.')
+
+
+def run(args: argparse.Namespace) -> int:
+    fw = _ask_valid(f'Firmware range ({"/".join(plan.FIRMWARE_RANGES)}): ', args.fw, plan.check_firmware, '--fw')
+    prefix = _ask_valid(f'Serial prefix ({"/".join(plan.VARIANTS)}): ', args.prefix, plan.check_prefix, '--prefix')
+    files = plan.select_files(fw, prefix, args.usbnet)
+    mount = device.require_mount(args.mount)
+    steps = plan.update_steps(files)
+    log.debug('plan: fw=%s prefix=%s usbnet=%s mount=%s files=%s', fw, prefix, args.usbnet, mount, files)
+
+    if args.dry_run:
+        print(f'Dry run: mount={mount} firmware={fw} prefix={prefix}')
+        if args.wipe_books:
+            _wipe_step(mount, dry_run=True)
+        for key, label in steps:
+            print(f'  would stage {files[key]} ({label})')
+        print(f'  would copy {plan.KUAL_FILE} into documents/')
+        print('  would merge koreader/, extensions/, launchpad/ into the mount root')
+        return 0
+
+    if args.wipe_books:
+        _wipe_step(mount, dry_run=False)
+
+    print('Getting packages (cached after the first run):')
+    roots = packages.fetch_packages(plan.package_keys(files), args.cache, lambda name: print(f'  {name}', flush=True))
+    bins = [(packages.member_path(roots[key], files[key]), label) for key, label in steps]
+    kual = packages.member_path(roots['kual'], files['kual'])
+    for bin_path, label in bins:
+        _update_step(mount, bin_path, label)
+
+    print(f'\nCopying {kual.name} to documents/')
+    device.install_kual(mount, kual)
+
+    pairs = device.koreader_pairs(roots['koreader'], mount)
+    size_mb = sum(src.stat().st_size for src, _ in pairs) / 1e6
+    print(
+        f'Copying KOReader ({len(pairs)} files, {size_mb:.0f} MB). '
+        'This takes several minutes on a K3; leave it plugged in.'
+    )
+    _copy_with_progress(pairs, 'KOReader')
+    print('Flushing writes to the Kindle...', flush=True)
+    device.flush()
+    print(f'\n{DONE_MESSAGE}')
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog='koreader-d00901', description='Install KOReader on a Kindle K3.')
+    add_common_args(parser)
+    parser.add_argument('--dry-run', action='store_true', help='print the plan only')
+    args = parser.parse_args(argv)
+    log_file = args.log_file or args.cache / 'install.log'
+    setup_logging(log_file, verbose=args.verbose)
+    log.debug('koreader-d00901 %s, args=%s', __version__, vars(args))
+    try:
+        return run(args)
+    except InstallerError as exc:
+        log.debug('install failed', exc_info=True)
+        print(f'error: {exc}\n(details in {log_file})', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print('\nInterrupted.')
+        return 130