Repository navigation
Deployment hardening: input mapping, audio backends, logging, smoke tests - #19
Merged
Merged
Conversation
Deployment hardening only — no new study features. Makes the FSRS/
pygame path realistically deployable on Batocera-derived handhelds
without on-device pip, compilation, Anki, Rust, or webviews.
Input (the big one):
- New cardbrick/input_map.py: raw SDL button indices are never trusted.
Events translate to semantic actions (south/east/west/north_button,
l1, r1, select, start, dpad_*) via a JSON mapping persisted in the
data dir; defaults are only a starting guess.
- In-app controller diagnostic (raw event + semantic + study action
viewer) and calibration screen ("press the BOTTOM face button...")
reachable from Parent Mode or --input-diagnostic; hold any button 3 s
to enter calibration even with a totally wrong mapping. Handles
d-pads exposed as hats, axes, or buttons; joystick hot-plug handled.
- Child UI uses physical-position labels (Bottom=Good, Right=Again,
Left=Easy, Top=Hard), never A/B/X/Y.
- Own exit paths: START->summary->quit, SELECT+START held 2 s force-
exits from anywhere (state already committed per answer), Esc on
desktop. No RetroArch hotkey assumptions.
Filesystem / durability:
- New cardbrick/paths.py: one writable data root resolved as
--data-dir > CARD_BRICK_DATA_DIR > CARDBRICK_DATA (legacy) >
/userdata/saves/cardbrick (Knulli) > ./data; app/runtime bundle stays
read-only. All paths logged at startup.
- Automatic cardbrick.db.backup-* before any schema migration of an
existing database; migration actions logged.
Observability:
- New cardbrick/bootlog.py: rotating file log (logs/cardbrick.log) with
version, Python/platform, paths, SDL video/audio drivers, display and
logical size, joystick names/GUIDs, font, pygame flavour, fsrs
version. Failures (db, migration, audio, media, import, settings,
mapping) all logged.
- New cardbrick/errors.py: visible error screens (plain English + log
path + safe next action) instead of silent exits.
- New cardbrick/smoke.py + --smoke-test flag: non-interactive PASS/
WARN/FAIL checks of data dir, log, settings, DB+migrations, cards,
profile, scheduler query, pygame, display, Spanish font glyphs,
joystick, audio backend, input mapping.
Audio without SDL_mixer:
- audio.py rewritten with pluggable backends: pygame.mixer is optional
(needs SDL_mixer) so playback falls back to CLI players (mpg123,
ogg123, aplay, paplay, ffplay) launched non-blocking, then to a
logged no-op. CARDBRICK_AUDIO / CARDBRICK_AUDIO_CMD overrides.
Rendering / fonts:
- Bundled assets/fonts/DejaVuSans.ttf (Bitstream Vera licence included)
as the explicit default; full á é í ó ú ñ ü ¿ ¡ coverage; fallbacks
logged. No reliance on pygame.font.Font(None).
- Logical 640x480 canvas scaled to the real display with optional
integer scaling + letterboxing ("integer_scaling" setting); SDL video
driver env-configurable and logged; display init failure is a clear
error, not a crash.
- Review screen redraws only on input (1 s heartbeat), no per-frame
SQL/font/surface churn.
Modes / routing:
- --desktop / --knulli flags (auto-detected via /userdata otherwise);
--verbose. First run with an empty database routes to Parent Mode;
configured devices boot straight toward study. requirements now
pygame-ce + fsrs + typing-extensions.
Deployment kit (deploy/knulli/):
- launch_cardbrick_spanish.sh template (data dir, SDL driver, bundled
runtime/vendored deps wiring, log redirection, auto smoke test on
first boot), README (paths, import, profile, reset-without-history-
loss, exits, "Things We Deliberately Avoid"), package_layout.md
(PC-side bundling with pip --platform manylinux2014_aarch64),
requirements-runtime.txt, smoke_test_checklist.md (15-step manual
pre-flight incl. battery-pull recovery).
Tests: 69 passing (was 39) — adds input mapping (defaults, persistence,
unknown events, axis debounce, force-exit), data-dir resolution,
audio backend selection/degradation, and smoke-test pass/warn/fail
cases. Headless end-to-end drivers re-verified (full child session,
parent screens, legacy reviewer, diagnostic + calibration).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
A from-source pygame build (the silent result of pip installing classic pygame on a Python with no prebuilt wheel, e.g. 3.14 on macOS) can lack SDL_ttf, leaving pygame.font a stub that raises "partially initialized module 'pygame.font'" on first use. Handle it explicitly: - app.ensure_font_support() probes the real font module at startup and raises FontSupportError with the actual fix (install pygame-ce or use a Python with prebuilt wheels); main prints it clearly instead of a raw ImportError, since a text error screen cannot render without fonts. - Smoke test: pygame/display/font/joystick/audio sub-checks are now individually isolated, so a broken optional module is reported as its own labelled failure (previously it was mislabelled "pygame init" and aborted the joystick/audio checks). Classic pygame on Python >= 3.13 is flagged as a WARN with the same guidance. - Audio: add macOS afplay to the CLI fallback players. - README: "pick a Python with prebuilt wheels" note. - Tests: font-less pygame fails only the font check (others still run), ensure_font_support diagnosis, afplay coverage. 72 passing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
New card type (card_type='vocab') alongside the existing basic front/ back cards — both coexist in the same deck/queue, FSRS scheduling is identical either way, only the review UI and import differ. Review flow, matching the deck's word -> example -> image -> definition structure: D-pad reveals the next phase; there are no separate rating buttons for these cards — pressing "I know this" (bottom button) at phase 0/1/2/3 maps directly to Easy/Good/Hard/Again. L1 replays whichever audio belongs to the current phase (word audio at phase 0, example audio from phase 1 on). The example sentence's headword is highlighted by case-insensitive substring match (no HTML/CSS rendering, per the project's existing scope boundary); images are decoded once per card and cached, not reloaded per frame. Storage: new vocab_cards table (word, gendered forms, definitions, image filename, example sentence/audio/translation, JP fields, report link), keyed to cards.id; cards gains a card_type column. Re-importing updates content only, never review progress (schema v3, migrates in place with the existing backup-before-migration mechanism). Import, two paths: - .apkg: the note type is detected by field *names* (Word first, an Example ES field present) rather than a hardcoded Anki model id, so it survives regeneration in genanki. A plain Basic/reversed note in the same deck still imports through the existing path unchanged. - CSV (cardbrick/vocab_csv.py): an alternative for spreadsheet-sourced data, same column spec. Audio/image cells accept either a bare filename or an Anki-style tag ([sound:...], <img src=...>). Card identity is a stable hash of the Word field (documented assumption: Word must stay unique and unedited across re-imports, since a CSV row has no Anki note id to key on). --media-dir copies referenced files in by name. main.py: `import` now dispatches on file extension (.csv vs .apkg); added --media-dir and --deck for the CSV path. Tests: 19 new (storage round-trip + migration, apkg field-name detection incl. a mixed vocab+basic deck, CSV import incl. header case/order-insensitivity, re-import dedup, bare-filename vs Anki-tag cells, missing-media handling). Full suite 91 passing. Also drove the actual pygame review UI headlessly end-to-end (real image decode, phase reveals via D-pad, "I know this" at each phase verified against the correct FSRS rating, including the existing Again-requeues-within- session behavior) as a manual smoke check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
A CLI-only "admin" command group (deliberately not exposed in Parent
Mode's on-device UI) for operations that discard data outright:
python main.py admin purge-decks [--deck NAME ...] [--yes]
Deletes cards for the named decks (or every deck if none given) along
with their FSRS review state, review log entries, and vocab-card
content via the existing ON DELETE CASCADE relationships; child
profiles and settings are untouched. Always backs up the database to
cardbrick.db.backup-purge-<timestamp> before deleting, and always
prompts "Type 'yes' to confirm:" unless --yes is passed.
storage.py: new deck_names_list(), count_cards_in_decks(), and
purge_decks() methods — the SQL stays owned by storage.py, main.py only
handles confirmation/backup/reporting.
Tests: storage-level cascade correctness (all-decks vs named-decks,
profiles/settings untouched) and CLI-level behavior (abort without
confirmation, --yes skips the prompt, unknown deck errors without
deleting, backup file is created and restorable, no-op on an empty
database). 105 tests passing overall. Also manually walked the CLI:
abort preserves data, --yes purges and leaves a restorable backup.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
Anki's default export (the "Support older Anki versions" checkbox left
unchecked, which is the default in current Anki) writes *only*
collection.anki21b (zstd+protobuf) plus a collection.anki21 that looks
like a valid legacy collection but is actually a one-note placeholder
("Please update to the latest Anki version, then import the .colpkg/
.apkg file again."). The importer was reading that stub as if it were
the real deck and reporting a clean "Imported 1 cards from 1 notes"
success — a silent near-total data loss for any deck exported this way
(the reported real-world case: a 413KB, ~1000+ note deck imported as
a single card with no error).
Detect and reject the stub before importing anything: raise the
existing "re-export with the checkbox checked" ApkgError whenever
either (a) collection.anki21b is present in the archive and the legacy
collection has at most one note, or (b) a note's content is literally
Anki's own placeholder text — independent signals so a wording change
in one Anki version doesn't silently defeat the check. A genuinely
tiny real deck (no anki21b alongside it) still imports normally.
Tests: the exact real-world placeholder text, the count-based fallback
with different wording, a true one-card deck with no anki21b (must
still import), and anki21b-only archives. Also reproduced the report
directly — built a synthetic .apkg matching the user's file size
(~413KB) and confirmed the CLI now fails with clear instructions
instead of "succeeding" with 1 card. 109 tests passing overall.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
The CardBrick-style appliance had no way to choose which imported deck a child studies — only category (tag) filtering existed. The legacy prototype reviewer (python main.py review) has always had a deck picker; the new appliance was missing the equivalent, which matters once more than one deck is imported (e.g. a large vocab deck alongside a sample/test deck). Storage: child_profiles gains active_decks (same convention as active_categories — None = all decks, [] = none active, a list = that subset), migrated in place (schema v3 -> v4). queue_candidates() takes an optional decks filter, applied in SQL (a card has exactly one deck, unlike tags) rather than in Python. Service: get_due_cards()/counts_for_queue() gain deck_filter, falling back to the profile's active_decks the same way category_filter falls back to active_categories; an explicit deck_filter still overrides the profile default. Deck and category filters combine with AND. UI: new Parent Mode "Decks" screen, factored out alongside Categories into a shared _screen_multi_select() helper (same toggle-list/save behavior, parameterized by title/items/profile field) rather than duplicating ~60 lines. Child Start now shows the active deck under the category line. CLI: `profile --decks NAME[,NAME...]` / `--decks all`, and `profile` now also prints "Available decks" for reference. Tests: queue_candidates deck filtering (incl. the empty-list edge case), profile active_decks round-trip and migration, deck+category combination, CLI --decks flag, plus a headless end-to-end drive of the actual Decks screen (navigate Parent Mode -> Decks -> select one deck -> verify the child-facing queue is restricted to it). Fixed two existing headless smoke scripts whose hardcoded Parent Mode menu navigation shifted by one position now that Decks was inserted above Categories. 128 tests passing overall. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
Parent Mode's Decks screen (added last round) only configures which decks are *assigned* to a child — it never gave the child a way to choose which one to actually study. With more than one deck assigned, Child Start silently combined them all with no picker of any kind, which is the gap being reported. New DECK_SELECT screen, inserted between Child Start and Review: - Skipped automatically when at most one deck is assigned (the common case) — no extra tap when there's no real choice, per the "child mode should start quickly" principle. - Shown when more than one deck is assigned: D-pad to choose between each assigned deck individually or "All assigned decks" combined, bottom button to confirm, right button to back out. Due-card counts for every option are computed once up front, not per frame. - The choice is a per-sitting override (StudySession now takes an optional deck_filter), not a change to the parent's assignment — picking "French" this session doesn't touch active_decks. session.py: StudySession(..., deck_filter=None) threads straight through to ReviewService.get_due_cards, which already supported this override convention from the previous change. Tests: StudySession honours an explicit deck_filter and falls back to the profile's active_decks when None. Also drove the actual screens headlessly end-to-end: two decks assigned -> picker appears -> picking one deck restricts the session to only its cards; one deck assigned -> picker is skipped and review starts immediately. 130 tests passing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
Sessions were already recorded (sessions table: started_at, ended_at,
cards_reviewed), so this is a read view over existing data — no schema
change.
storage.sessions_in_range(profile_id, start, end): (started_at,
cards_reviewed) for a profile's sessions in a half-open UTC window.
service.sessions_per_day(profile_id, year, month) -> {day: count}:
groups by *local* calendar day (timestamps are stored UTC; the DB
window is padded a day each side so a session whose UTC instant sits
just outside the month but whose local day is inside still counts).
Only sessions with cards_reviewed > 0 earn a stamp, so opening the app
and backing out doesn't.
app.screen_calendar / _draw_calendar: a month grid (Sunday-first, via
stdlib calendar) with a coloured stamp on each studied day showing that
day's session count inside it — the count is the feature, since the
child is meant to log sessions repeatedly. Today is outlined; a
subtitle sums the month. Month nav via L1/R1 or D-pad left/right,
Bottom jumps to today, SELECT exits. Reachable from the start screen
(Top), the session-complete screen (Top — the natural "you earned a
stamp" moment), and Parent Mode; it returns to whichever screen opened
it (_calendar_return).
Tests: sessions_per_day (repeated same-day sessions, empty session
earns no stamp, spread across days, other-month/other-profile
exclusion, empty month, December->January window rollover) and the
sessions_in_range profile/window filter. Also rendered the screen
headlessly (screenshot) and drove Child Start -> Top -> Calendar ->
month nav -> back through the state machine. 138 tests passing.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR hardens CardBrick for reliable deployment on Knulli-style handhelds by introducing semantic input mapping, pluggable audio backends, comprehensive logging, and pre-flight smoke tests. The app now never trusts raw SDL button indices, gracefully degrades when audio/fonts are unavailable, and provides actionable diagnostics on startup and in the log file.
Key Changes
Input & Controller
input_map.py): Raw SDL button indices are translated to semantic actions ("south_button", "dpad_up", etc.) via a JSON mapping calibrated per-device. Face buttons are labelled by physical position ("Bottom = Good") rather than vendor labels (A/B/X/Y), avoiding confusion on cheap handhelds.Audio
audio.py): Tries pygame.mixer first, falls back to CLI players (mpg123, ffplay, aplay, etc.), then silent no-op. Never crashes due to missing audio.CARDBRICK_AUDIOandCARDBRICK_AUDIO_CMDenvironment overrides.Logging & Diagnostics
bootlog.py): Rotating log file under the data directory with startup diagnostics (pygame versions, display size, font resolution, joystick count).smoke.py): Non-interactive pre-flight checks (--smoke-test) verify database, settings, cards, scheduler, audio, and joystick before deployment.errors.py): Fatal startup errors (display init, font support) render as readable full-screen messages with log path and next steps.Data & Paths
paths.py): Unified data-directory resolution with priority: CLI arg →CARD_BRICK_DATA_DIRenv →CARDBRICK_DATAenv → Knulli/userdata/saves/cardbrick→./data.Display & Scaling
Vocabulary Cards
vocab_card.py,vocab_csv.py): New card layout with word, gendered forms, definitions, image, example sentence, and example audio.vocab_csv.py): Alternative to .apkg for spreadsheet-sourced decks; stable card identity via word hash.vocab_cardstable andcard_typecolumn;.apkgimporter detects vocab models by field names.Deployment
deploy/knulli/launch_cardbrick_spanish.sh): Template for on-device execution; handles system vs. bundled Python, vendored dependencies, and logging.package_layout.md,smoke_test_checklist.md, andREADME.mdupdates explain the build process and pre-flight steps.App Initialization
https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y