8000 Deployment hardening: input mapping, audio backends, logging, smoke tests by jmahmood · Pull Request #19 · jmahmood/CardBrick · GitHub
[go: up one dir, main page]

Skip to content

Deployment hardening: input mapping, audio backends, logging, smoke tests - #19

Merged
jmahmood merged 8 commits into
masterfrom
claude/vocab-phase-cards
Jul 7, 2026
Merged

jmahmood merged 8 commits into
masterfrom
claude/vocab-phase-cards

Conversation

@jmahmood
@jmahmood jmahmood commented Jul 7, 2026
Copy link
Copy Markdown
Owner

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

  • Semantic input mapping (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.
  • InputTranslator: Converts pygame events to semantic actions; keyboard fallback for desktop testing.
  • Input mapping persists to disk and can be rewritten by an in-app calibration screen.

Audio

  • Pluggable backends (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.
  • Respects CARDBRICK_AUDIO and CARDBRICK_AUDIO_CMD environment overrides.
  • All failures logged so the on-device log explains silent sessions.

Logging & Diagnostics

  • File logging (bootlog.py): Rotating log file under the data directory with startup diagnostics (pygame versions, display size, font resolution, joystick count).
  • Smoke tests (smoke.py): Non-interactive pre-flight checks (--smoke-test) verify database, settings, cards, scheduler, audio, and joystick before deployment.
  • Error screens (errors.py): Fatal startup errors (display init, font support) render as readable full-screen messages with log path and next steps.

Data & Paths

  • AppPaths (paths.py): Unified data-directory resolution with priority: CLI arg → CARD_BRICK_DATA_DIR env → CARDBRICK_DATA env → Knulli /userdata/saves/cardbrick → ./data.
  • All mutable state (database, settings, logs, input mapping) lives under a single writable root, keeping the app/runtime bundle read-only.

Display & Scaling

  • Canvas-based rendering: All drawing targets a fixed logical canvas (default 640×480, the RG35XX SP panel) which is scaled to the real display. Integer scaling when it fits; otherwise smooth scaling.
  • Display init errors are caught and shown as readable screens rather than crashing.

Vocabulary Cards

  • Four-phase vocab card type (vocab_card.py, vocab_csv.py): New card layout with word, gendered forms, definitions, image, example sentence, and example audio.
  • CSV importer (vocab_csv.py): Alternative to .apkg for spreadsheet-sourced decks; stable card identity via word hash.
  • Storage schema v3: New vocab_cards table and card_type column; .apkg importer detects vocab models by field names.

Deployment

  • Knulli launch script (deploy/knulli/launch_cardbrick_spanish.sh): Template for on-device execution; handles system vs. bundled Python, vendored dependencies, and logging.
  • Bundled DejaVu Sans font: Reliable Spanish glyph coverage (á é í ó ú ñ ü ¿ ¡) on handhelds.
  • Deployment docs: package_layout.md, smoke_test_checklist.md, and README.md updates explain the build process and pre-flight steps.

App Initialization

  • FontSupportError: Fail fast with an actionable message if pygame.font is missing (e.g., from-source build without SDL_ttf).
  • DisplayInitError: Catch and display display init failures.
  • QuitApp exception: Unwinds screen loops cleanly on exit.
  • Startup now logs pygame versions, display diagnost

https://claude.ai/code/session_01X51wk4Xi1jmeu4Fddmsz3Y

claude added 8 commits July 4, 2026 19:17
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
@jmahmood
jmahmood merged commit 2e62392 into master Jul 7, 2026
1 of 4 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.

2 participants

0