Skip to content

Kindle Vocabulary Builder → flashcards (manual + wireless hands-free) - #6

Merged
watchmesink merged 2 commits into
codex/flashcards-sm2pp-uploadfrom
kindle-vocab-import
Jul 14, 2026
Merged

watchmesink merged 2 commits into
codex/flashcards-sm2pp-uploadfrom
kindle-vocab-import

Conversation

@watchmesink

@watchmesink watchmesink commented Jul 14, 2026 •

Copy link
Copy Markdown
Owner

Brings Kindle Vocabulary Builder → CrossPoint flashcards in two flavors.

1. Manual / USB importer (scripts/kindle_vocab_sync.py)

Reads new words from a Kindle vocab.db (mounted over USB or copied), routes by language, and pipes them into quizlet_sync.py (auto-translate + upload). Incremental via ~/.crosspoint_sync/kindle_state.json. Optional on-mount launchd agent for Macs. Details in SKILL.md.

2. Fully wireless & hands-free — no USB, no manual run (kindle-device/ + server endpoint)

Solves "no cable, no manual script":

Kindle (look up word) → vocab.db  ──cron on the Kindle, over WiFi──▶  POST /api/kindle/vocab
                                                                      └─ server parses new WORDS (sqlite3),
                                                                         translates, files into decks
  • Server (web/server.js): POST /api/kindle/vocab stores an uploaded vocab.db, reads new WORDS via the sqlite3 CLI, translates (MyMemory: de/uk→en, en→de), dedups by term, and appends to decks/<deck>/kindle-YYYY-MM-DD.txt. Incremental watermark in DATA_DIR/kindle/state.json (never advances past a word that failed to translate). GET /api/kindle/status for monitoring. web/nixpacks.toml installs sqlite3 (Node stays npm-dependency-free).
  • Kindle (kindle-device/upload_vocab.sh): BusyBox-sh uploader that runs on the device from cron and pushes vocab.db over WiFi (curl/wget). Config + jailbreak/KUAL/cron install steps in kindle-device/README.md.

Requires a jailbroken Kindle — Amazon keeps vocab.db device-local with no cloud/API, so on-device code is the only wireless way to read Vocabulary Builder. (No-jailbreak alternative — scraping cloud highlights — is noted in the README.)

Verification

  • node web/test/test.js still green (engine unchanged by this path).
  • Manual importer: synthetic vocab.db (de/uk/en + fr + en-US) → correct extraction/routing; full run against a local server translated + uploaded, saved state, idempotent second run.
  • Server ingestion: uploading a vocab.db over HTTP parsed + translated + filed words into the right decks (german 2 / ukrainian 1 / english 2, French skipped), advanced the watermark, was idempotent on re-upload, and rejected a non-SQLite body.
  • Kindle-side upload_vocab.sh is sh -n clean; not run against a physical device (none available).

🤖 Generated with Claude Code

watchmesink and others added 2 commits July 14, 2026 11:01
New `scripts/kindle_vocab_sync.py`: pulls the words you look up while reading
on a Kindle (its `system/vocabulary/vocab.db`) into the CrossPoint decks.

It reads WORDS added since its last run, routes each by Kindle's own language
tag (de→german, uk→ukrainian, en→english; others skipped), and pipes them into
`quizlet_sync.py` as `[[deck:…]]`-tagged single terms — reusing the existing
MyMemory auto-translation + web/device upload + sync pipeline. No new deps
(stdlib sqlite3 only).

- Incremental: newest processed WORDS.timestamp saved in
  ~/.crosspoint_sync/kindle_state.json; state advances only on a successful
  upload, so nothing is lost if a run fails or the device is asleep.
- DB discovery: autodetects a mounted Kindle, else KINDLE_VOCAB_DB, --db, or
  ~/.crosspoint_sync/vocab.db. Opened read-only (never modifies the Kindle).
- --word-field stem|word, --emit-only, --dry-run, --all; credentials resolve
  from env then ~/.crosspoint_sync/config.json like sync_agent.py.
- Optional `com.crosspoint.kindle-vocab-sync.plist`: event-driven launchd agent
  that imports on volume mount (plug in the Kindle) — no polling.
- SKILL.md + README document the flow.

Verified: synthetic vocab.db (de/uk/en + fr + en-US) → correct extraction,
routing, and stem/word forms; full run against a local web server translated
and uploaded (german 2 / ukrainian 1 / english 2 cards) and saved state; a
second run correctly imported nothing new.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Lets Kindle Vocabulary Builder words reach the decks with no USB cable and no
manually-run script, by having the Kindle push its DB and the web app ingest it.

Server (web/server.js):
- POST /api/kindle/vocab — accepts a raw vocab.db upload, reads new WORDS via the
  sqlite3 CLI (read-only, -json), translates new terms (MyMemory, de/uk->en,
  en->de), dedups by term, and appends them to decks/<deck>/kindle-YYYY-MM-DD.txt
  (the normal deck + device-sync pipeline takes it from there). ?wait=1 returns
  the ingest summary. Incremental via a timestamp watermark in
  DATA_DIR/kindle/state.json; the watermark never advances past a word that
  failed to translate (retried next upload). Rejects non-SQLite bodies.
- GET /api/kindle/status — last import watermark.
- web/nixpacks.toml installs the sqlite3 CLI on Railway (Node stays npm-dep-free).

Kindle side (skill/crosspoint-quizlet-sync/kindle-device/):
- upload_vocab.sh — BusyBox-sh script that runs ON a jailbroken Kindle and
  uploads /mnt/us/system/vocabulary/vocab.db over WiFi (curl or wget), driven by
  cron. Config via vocab_sync.conf(.example). README covers jailbreak/KUAL/cron.

Why jailbreak: Amazon keeps vocab.db device-local with no cloud/API, so the only
wireless way to read Vocabulary Builder is on-device code.

Verified (server side, locally): uploading a synthetic vocab.db over HTTP parses
+ translates + files words into the right decks (german 2 / ukrainian 1 /
english 2, French skipped), advances the watermark, is idempotent on re-upload,
and rejects a non-SQLite body. Kindle-side script is shellcheck-clean but
untested against a physical device (none available).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@watchmesink watchmesink changed the title Import Kindle Vocabulary Builder words into flashcards Kindle Vocabulary Builder → flashcards (manual + wireless hands-free) Jul 14, 2026
@watchmesink
watchmesink merged commit c16409d into codex/flashcards-sm2pp-upload Jul 14, 2026
1 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant