Files
cardputerzero-sync/chat-summaries/2026-11-18_09-15-cardputerzero-photo-sync-summary.md

62 lines
7.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CardputerZero Photo Sync — Implementation Summary
**Date:** 2026-11-18 09:15 EST
**Branch:** `feat/cardputerzero-photo-sync`
**Range:** `23db23a` (design spec & plan) → `6685844` (final fix wave)
---
## Task Description
Implemented an end-to-end, zero-external-Python-dependency one-way photo syncing system for the **M5Stack CardputerZero** (Raspberry Pi CM0, `arm64` Debian Linux, 320×170 non-touch LCD, `cp0-keys` 46-key matrix keyboard, `APPLaunch`) and **macOS** over an existing private **Tailscale** tailnet:
1. **`mac-receiver/`**: Background macOS HTTP receiver daemon (`MacReceiverServer`) + `cp0-mac-sync` CLI + `LaunchAgent` installer saving uploaded photos to `~/Pictures/CardputerZero/<folder_label>/<rel_path>` with atomic `.part` staging, SHA-256 verification, non-overwriting collision naming, and debounced macOS Notification Center summaries.
2. **`device-daemon/`**: On-device Python `cp0-syncd` (`systemd --user`) service with SQLite WAL queue (`SyncStore`, keyed on `(folder_id, rel_path, sha256)`), Linux `ctypes` `inotify` + fallback polling watcher (`INotifyWatcher`) supporting removable SD mounts via ancestor watches, sleep-aware wake-probe uploader (`Uploader`), and `AF_UNIX` JSON IPC server (`IpcServer`).
3. **`device-ui/`**: C++17 `320×170` companion UI (`cp0-sync-ui`) styled with `shadcn/ui` Zinc Dark & balanced Zinc Light themes (`[T]` live toggle), segmented `1 Status · 2 Folders · 3 Logs` tabs, Tailscale peer & custom `host[:port]` target picker (`[C]`), directory tree drill-down (`[A]`), non-destructive folder removal confirmation (`[D]`), retry trigger (`[R]`), FreeType2 + 5×7 fallback font rendering, macOS SDL2 simulator, Linux `fbdev`+`evdev` backend, and optional LVGL v9 hooks (`CP0_HAS_LVGL`).
4. **`packaging/`**: Debian `arm64` `.deb` builder (`build-deb.sh`, `Dockerfile.arm64`), `cp0-syncd.service` (`systemd --user`), `APPLaunch` `cp0-sync.desktop` & `80×80` icon (`cp0-sync.png`), Debian maintainer scripts (`control`, `postinst`, `prerm`), and packaging verification tests.
---
## Key Changes Made
| Commit | Summary |
|---|---|
| `23db23a` | Design specification (`docs/superpowers/specs/2026-11-18-cardputerzero-photo-sync-design.md`) and 7-task TDD plan |
| `555919a`, `23ed06f` | `mac-receiver/cp0_mac_receiver/{__init__,config,server}.py` & `tests/test_server.py` (Tailscale/loopback IP allowlist, atomic `.part` upload, `osascript` `on run argv` escaping) |
| `a5f8c5d` | `mac-receiver/cp0_mac_receiver/cli.py`, `bin/{cp0-mac-receiver,cp0-mac-sync}`, `tests/test_cli.py` (`set-dir`, `set-port`, `install-service`, `uninstall-service`, `status`, `logs`) |
| `69224f3` | `device-daemon/cp0_syncd/{__init__,config,store}.py` & `tests/test_store_and_config.py` (overlap guard, unique label disambiguation, SQLite WAL state/dedup/log store) |
| `da4d963`, `c6a672f` | `device-daemon/cp0_syncd/{watcher,uploader,ipc,daemon}.py`, `bin/cp0-syncd`, `tests/test_daemon_integration.py` (Linux `ctypes` `inotify` + fallback poller, crash `UPLOADING` recovery, atomic `_state_lock` wake/probe handling, uniform subdir prefix ignore, `AF_UNIX` JSON IPC) |
| `b6fcf5a`, `8ea46a2` | `device-ui/CMakeLists.txt`, `src/{theme,ipc_client}.{hpp,cpp}`, `tests/test_ipc_and_theme.cpp` (non-blocking IPC client, fail-closed corrupt SQLite fallback, Tailscale peer parser, Zinc Dark/Light palettes) |
| `7d369b2`, `eeacf0e` | `device-ui/src/{ui_controller,app_ui}.{hpp,cpp}`, `src/fb_blit.hpp`, `src/main.cpp`, `tests/test_ui_navigation.cpp` (320×170 renderer, modals, `cp0-keys`/SDL2/`fbdev`+`evdev` loops, bounds/bitfield-checked framebuffer blit, `CP0_HAS_LVGL` lifecycle, cross-tab feedback toasts) |
| `ec8a414` | `packaging/{Dockerfile.arm64,build-deb.sh,cp0-syncd.service,cp0-sync.desktop,cp0-sync.png}`, `packaging/debian/{control,postinst,prerm}`, `packaging/tests/test_packaging.py` |
| `6685844` | Final cross-component fixes: gate SQLite fallback folder synthesis on `!config_loaded`, show top-bar `"Daemon Off"` badge when `from_fallback` is true, and add `60s` socket timeout (`408`), `X-CP0-Mtime` validation / pre-replace `os.utime`, `.expanduser()`, and directory-collision `400`/`500` handling in `server.py` |
*(41 files added across implementation commits prior to this summary.)*
---
## Verification Results
Observed on `6685844`:
- **Mac Receiver (`PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v`, `BypassSandbox: true`):** `24/24` passed in `6.319s` (`OK`).
- **Device Daemon (`PYTHONPATH=device-daemon:mac-receiver python3 -W error -m unittest discover -s device-daemon/tests -v`, `BypassSandbox: true`):** `25/25` passed in `4.766s` (`OK`, zero warnings).
- **Companion UI (`cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure -V`, `BypassSandbox: true`):** Clean build (`-Wall -Wextra -Wpedantic`, zero warnings) and `2/2` tests passed in `0.18 sec` (`test_ipc_and_theme` `0.16s`, `test_ui_navigation` `0.01s`).
- **Packaging (`python3 -m unittest discover -s packaging/tests -v`):** `7/7` passed in `0.134s` (`OK`).
- **ARM64 Container Verification (observed at `ec8a414` before final `mac-receiver` / `device-ui` `6685844` edits):** Built `cp0-sync_1.0.0_m5stack1_arm64.deb` (`98704` bytes) under `linux/arm64` `debian:bookworm-slim` (`CP0_UI_TARGET_DEVICE=ON` zero `g++` warnings, `ctest` `2/2`, `dpkg-deb -I/-c`, `dpkg -i`/`-r`, and `device-daemon/tests` `25/25` exercising real Linux kernel `ctypes` `inotify`).
---
## Lessons Learned
1. **Pre-empt Python/C++ schema & fallback drift:** Pinning the 18-key `status` IPC JSON schema early kept Python `daemon.py` and C++ `ipc_client.cpp` in sync, and checking SQLite fallback behavior against `remove_folder` caught subtle ghost-folder and stale `"Mac Online"` badge mismatches across offline daemon restarts.
2. **Isolating hardware-specific code behind testable C++ headers:** Extracting `UiController` and `fb_blit.hpp` (`pack_fb_channel` / `blit_framebuffer`) allowed deterministic `ctest` coverage on macOS for keyboard modal flows, RGB/BGR bitfields, and stride bounds before compiling the Linux `fbdev`/`evdev` target inside ARM64 Docker.
3. **Sandboxed socket testing & GPG commits:** Loopback TCP and `AF_UNIX` tests predictably hit macOS sandbox `EPERM`, so pure logic/UI/packaging tests run inside the sandbox while live socket suites and GPG-signed commits isolate cleanly to single `BypassSandbox: true` steps.
---
## Follow-Up Items
- **On real CardputerZero hardware:** Re-build the `.deb` via `./packaging/build-deb.sh` (so `6685844` changes are included), optionally place `Inter-Regular.ttf` / `JetBrainsMono-Regular.ttf` in `packaging/fonts/` for FreeType glyphs instead of the 5×7 bitmap fallback, install `cp0-sync_1.0.0_m5stack1_arm64.deb` via `sudo dpkg -i`, and test `/dev/fb0`, `cp0-keys` `evdev`, `APPLaunch`, and `systemctl --user status cp0-syncd`.
- **On Mac:** Install the receiver daemon via `mac-receiver/bin/cp0-mac-sync install-service` and verify live end-to-end Tailscale transfers from the device.
- **Deferred minor improvements (non-blocking):** Unicode multi-byte UTF-8 glyph rendering in `app_ui.cpp`, clamping `log_scroll` upper bound to `logs.size() - 6` in `ui_controller.cpp`, explicit `libc6, libstdc++6` in `packaging/debian/control`, `LC_NUMERIC` / `EINTR` hardening in `ipc_client.cpp`, transaction context around `SyncStore.log`, and separating `launchd` stdout/stderr log path from `RotatingFileHandler`.