41 KiB
CardputerZero Photo Sync Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Build an automatic one-way photo syncing system from an M5Stack CardputerZero (CM0 ARM64 Linux) over Tailscale to a macOS receiver, complete with offline queueing, a cp0-mac-sync Mac CLI/LaunchAgent, and a shadcn/ui-styled 320×170 LVGL v9 companion app for APPLaunch.
Architecture: A zero-dependency Python 3 systemd --user background daemon (cp0-syncd) watches user-configured directories via inotify + startup walk, queues photos in SQLite (WAL mode), probes the Mac receiver (cp0-mac-receiver) over Tailscale, and uploads atomically with SHA-256 verification. On the CardputerZero, a C++17/LVGL v9 companion UI (cp0-sync-ui) communicates with cp0-syncd over a Unix domain socket (with read-only SQLite fallback) and ships alongside cp0-syncd in a local arm64 .deb package.
Tech Stack: Python 3.9+ standard library (sqlite3, http.server, urllib, ctypes libc inotify), C++17, LVGL v9, FreeType (Inter + JetBrains Mono), SDL2 (macOS simulator), Linux fbdev/evdev (device), CMake + CPack / dpkg-deb.
Spec: docs/superpowers/specs/2026-11-18-cardputerzero-photo-sync-design.md
Global Constraints
- Target Device: M5Stack CardputerZero (Raspberry Pi CM0, quad-core Cortex-A53, 512 MB RAM, ARM64 Debian Linux, 320×170 non-touch LCD, 46-key
cp0-keysmatrix keyboard,APPLaunch.servicerunning undersystemd --user). - Python Dependencies: Zero third-party
pippackages (python3 (>= 3.9)stdlib only) for bothcp0-syncdandcp0-mac-receiver. - Default Paths: CardputerZero first-run watched folder is
/home/pi/Pictures/DCIM/Camera(resolved via~/Pictures/DCIM/Camera, labelCamera); Mac receiver default root is~/Pictures/CardputerZero/<folder_label>/<rel_path>. - Network & Security: Tailscale strictly private tailnet; no pairing
auth_tokenorX-CP0-Token. Mac receiver listens on0.0.0.0:8765(configurable) and enforces Tailscale CIDR allowlist (100.64.0.0/10,fd7a:115c:a1e0::/48) + loopback (127.0.0.1,::1). - Sync Semantics: Global one-way "upload once" keyed by
(folder_id, rel_path, sha256); never re-uploads if moved/deleted on Mac; never overwrites a different photo on filename collision (<stem>_<YYYYMMDD_HHMMSS>_<sha8><ext>). - UI Theme:
shadcn/uiZinc Dark (#09090bbg,#18181bmuted,#27272a1px border,#fafafafg) and balanced Zinc Light (#fafafabg,#ffffffcard,#f4f4f5muted,#e4e4e71px border,#71717afocus ring,#09090bfg), toggleable live via[T]and persisted inconfig.json. - Packaging: Personal local build
cp0-sync_1.0.0_m5stack1_arm64.deb(noczdev/CardputerZeroRepositoryAppStore submission constraints).
Review Focus
- Percent-encoding of spaces/UTF-8 paths in HTTP headers:
X-CP0-Folder-LabelandX-CP0-Rel-Pathcan contain spaces or non-ASCII characters (e.g.,Trip Photos/café.jpg); bothUploaderandcp0-mac-receivermust percent-encode/decode header values (urllib.parse.quote/unquote) rather than failing HTTP header Latin-1 encoding. (Pinned in Task 1 & Task 4) - Zero-byte media files from crashed camera writes: A
0-byte.jpgwritten before a crash must be skipped with aWARNlog bySyncStore/Watcherrather than uploaded as a corrupt empty file. (Pinned in Task 3) - Queued
PENDINGfile deleted on CardputerZero before Mac wakes:Uploadermust catchFileNotFoundErrorwhen opening aPENDINGfile, delete the stale row fromstate.db, log a warning, and proceed with the remaining queue. (Pinned in Task 4) - Stale Unix socket file after unclean shutdown:
IpcServermust unlink any pre-existing stale socket path beforebind()socp0-syncdrestarts cleanly after power loss. (Pinned in Task 4) - Corrupt or truncated
config.jsonon disk: BothMacConfigandDaemonConfigmust save atomically (.tmp+os.replace) and fall back safely to defaults on malformed JSON rather than crashing on startup. (Pinned in Task 1 & Task 3)
Task 1: Mac Receiver Config, Tailscale IP Filter, & Atomic HTTP Server
Files:
- Create:
mac-receiver/cp0_mac_receiver/__init__.py - Create:
mac-receiver/cp0_mac_receiver/config.py - Create:
mac-receiver/cp0_mac_receiver/server.py - Test:
mac-receiver/tests/test_server.py
Interfaces:
-
Produces:
MacConfig(dest_root: str, listen_host: str, listen_port: int, notify_on_batch: bool, tailscale_only: bool)load_mac_config(path: Path | None = None) -> MacConfigsave_mac_config(cfg: MacConfig, path: Path | None = None) -> Noneis_allowed_client_ip(ip_str: str, tailscale_only: bool) -> boolMacReceiverServer(config_path: Path, notifier: Callable[[int, Path], None] | None = None)with.start(),.shutdown(),.server_address
-
Step 1: Write failing tests for config, IP allowlist,
/health,/upload, dedup, collision rename, path traversal, and percent-encoded headers
# mac-receiver/tests/test_server.py
import hashlib, json, os, tempfile, threading, unittest
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
from cp0_mac_receiver.config import MacConfig, load_mac_config, save_mac_config
from cp0_mac_receiver.server import MacReceiverServer, is_allowed_client_ip
class TestMacConfigAndFilter(unittest.TestCase):
def test_corrupt_config_falls_back_to_defaults(self):
with tempfile.TemporaryDirectory() as tmp:
cfg_path = Path(tmp) / "config.json"
cfg_path.write_text("{broken json")
cfg = load_mac_config(cfg_path)
self.assertEqual(cfg.listen_port, 8765)
self.assertTrue(cfg.tailscale_only)
def test_tailscale_ip_filter(self):
self.assertTrue(is_allowed_client_ip("100.101.102.103", True))
self.assertTrue(is_allowed_client_ip("fd7a:115c:a1e0::1", True))
self.assertTrue(is_allowed_client_ip("127.0.0.1", True))
self.assertFalse(is_allowed_client_ip("192.168.1.50", True))
self.assertTrue(is_allowed_client_ip("192.168.1.50", False))
class TestMacReceiverServer(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.dest_root = Path(self.tmp.name) / "CardputerZero"
self.cfg_path = Path(self.tmp.name) / "config.json"
save_mac_config(MacConfig(dest_root=str(self.dest_root), listen_host="127.0.0.1", listen_port=0, notify_on_batch=True, tailscale_only=True), self.cfg_path)
self.notified = []
self.srv = MacReceiverServer(self.cfg_path, notifier=lambda n, d: self.notified.append((n, d)), debounce_sec=0.05)
self.thread = threading.Thread(target=self.srv.serve_forever, daemon=True)
self.thread.start()
self.base_url = f"http://127.0.0.1:{self.srv.server_port}"
def tearDown(self):
self.srv.shutdown()
self.srv.server_close()
self.tmp.cleanup()
def _upload(self, label: str, rel_path: str, data: bytes, mtime: float = 1700000000.0):
sha = hashlib.sha256(data).hexdigest()
req = Request(f"{self.base_url}/upload", data=data, method="POST", headers={
"Content-Length": str(len(data)),
"X-CP0-Folder-Label": quote(label, safe=""),
"X-CP0-Rel-Path": quote(rel_path, safe="/"),
"X-CP0-SHA256": sha,
"X-CP0-Mtime": str(mtime),
})
return urlopen(req)
def test_health_returns_dest_root(self):
with urlopen(f"{self.base_url}/health") as resp:
self.assertEqual(resp.status, 200)
body = json.loads(resp.read())
self.assertEqual(body["status"], "ok")
self.assertEqual(body["dest_root"], str(self.dest_root))
def test_upload_dedup_collision_and_utf8_headers(self):
payload = b"jpeg-bytes-1"
r1 = json.loads(self._upload("Trip Photos", "2026/café 1.jpg", payload, 1700000123.0).read())
self.assertEqual(r1["status"], "saved")
target = self.dest_root / "Trip Photos" / "2026" / "café 1.jpg"
self.assertEqual(target.read_bytes(), payload)
self.assertEqual(int(target.stat().st_mtime), 1700000123)
r2 = json.loads(self._upload("Trip Photos", "2026/café 1.jpg", payload, 1700000123.0).read())
self.assertEqual(r2["status"], "already_exists")
r3 = json.loads(self._upload("Trip Photos", "2026/café 1.jpg", b"jpeg-bytes-different", 1700000456.0).read())
self.assertEqual(r3["status"], "saved")
self.assertNotEqual(Path(r3["saved_path"]), target)
self.assertEqual(target.read_bytes(), payload)
def test_rejects_path_traversal_and_bad_sha256(self):
with self.assertRaises(HTTPError) as ctx:
self._upload("../etc", "passwd", b"bad")
self.assertEqual(ctx.exception.code, 400)
req = Request(f"{self.base_url}/upload", data=b"abc", method="POST", headers={
"Content-Length": "3", "X-CP0-Folder-Label": "Camera",
"X-CP0-Rel-Path": "a.jpg", "X-CP0-SHA256": "0" * 64, "X-CP0-Mtime": "1700000000",
})
with self.assertRaises(HTTPError) as ctx2:
urlopen(req)
self.assertEqual(ctx2.exception.code, 400)
- Step 2: Run tests to verify they fail
Run: PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
Expected: FAIL (ModuleNotFoundError: No module named 'cp0_mac_receiver').
-
Step 3: Implement
config.pyandserver.pyinmac-receiver/cp0_mac_receiver/ -
config.py:MacConfigdataclass with defaultdest_root = str(Path.home() / "Pictures" / "CardputerZero"),listen_host = "0.0.0.0",listen_port = 8765,notify_on_batch = True,tailscale_only = True; atomic.tmp+os.replacewrites; safe fallback on missing/corrupt JSON; default path~/.config/cp0-mac-sync/config.json(overrideable viaCP0_MAC_CONFIG). -
server.py:is_allowed_client_ip()using Pythonipaddressagainst100.64.0.0/10,fd7a:115c:a1e0::/48,127.0.0.0/8,::1/128(handling IPv4-mapped IPv6::ffff:);MacReceiverServer(ThreadingHTTPServer)reloading config per request soset-dirtakes effect immediately, streaming64 KBchunks to.cp0-<uuid>.part, validatingX-CP0-SHA256and path segments (no../ absolute paths afterunquote), deduplicating identical SHA-256, renaming collisions to<stem>_<YYYYMMDD_HHMMSS>_<sha8><ext>, applyingos.utime, and triggering a debouncedosascriptbatch notification. -
Step 4: Run tests to verify they pass
Run: PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
Expected: PASS (all tests in test_server.py OK).
- Step 5: Commit
git add .gitignore mac-receiver/cp0_mac_receiver/__init__.py mac-receiver/cp0_mac_receiver/config.py mac-receiver/cp0_mac_receiver/server.py mac-receiver/tests/test_server.py
git commit -m "feat(mac-receiver): add config store, Tailscale IP filter, and atomic HTTP receiver"
Task 2: Mac CLI (cp0-mac-sync) & LaunchAgent Service Installer
Files:
- Create:
mac-receiver/cp0_mac_receiver/cli.py - Create:
mac-receiver/bin/cp0-mac-receiver - Create:
mac-receiver/bin/cp0-mac-sync - Test:
mac-receiver/tests/test_cli.py
Interfaces:
-
Consumes:
MacConfig,load_mac_config,save_mac_configfromcp0_mac_receiver.config -
Produces:
LAUNCH_AGENT_LABEL = "com.cardputerzero.photosync"render_launch_agent_plist(receiver_bin: Path, log_path: Path, config_path: Path) -> strrun_cli(argv: list[str], config_path: Path | None = None, plist_path: Path | None = None, runner: Callable[..., CompletedProcess] | None = None) -> int
-
Step 1: Write failing tests for
cp0-mac-syncsubcommands (set-dir,set-port,install-service,uninstall-service,status,logs)
# mac-receiver/tests/test_cli.py
import tempfile, unittest
from pathlib import Path
from subprocess import CompletedProcess
from cp0_mac_receiver.cli import run_cli
from cp0_mac_receiver.config import load_mac_config
class TestMacCli(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.cfg_path = Path(self.tmp.name) / "config.json"
self.plist_path = Path(self.tmp.name) / "com.cardputerzero.photosync.plist"
self.calls = []
def tearDown(self):
self.tmp.cleanup()
def _fake_runner(self, cmd, **kwargs):
self.calls.append(cmd)
return CompletedProcess(cmd, 0, stdout="", stderr="")
def test_set_dir_creates_directory_and_updates_config(self):
new_dir = Path(self.tmp.name) / "Photos" / "CP0"
rc = run_cli(["set-dir", str(new_dir)], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner)
self.assertEqual(rc, 0)
self.assertTrue(new_dir.is_dir())
self.assertEqual(load_mac_config(self.cfg_path).dest_root, str(new_dir.resolve()))
def test_install_and_uninstall_service_writes_and_removes_plist(self):
rc = run_cli(["install-service"], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner)
self.assertEqual(rc, 0)
plist_text = self.plist_path.read_text()
self.assertIn("com.cardputerzero.photosync", plist_text)
self.assertIn("KeepAlive", plist_text)
self.assertTrue(any("launchctl" in c[0] for c in self.calls))
rc2 = run_cli(["uninstall-service"], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner)
self.assertEqual(rc2, 0)
self.assertFalse(self.plist_path.exists())
def test_set_port_validates_range_and_restarts_service(self):
run_cli(["install-service"], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner)
self.calls.clear()
self.assertNotEqual(run_cli(["set-port", "99999"], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner), 0)
rc = run_cli(["set-port", "9100"], config_path=self.cfg_path, plist_path=self.plist_path, runner=self._fake_runner)
self.assertEqual(rc, 0)
self.assertEqual(load_mac_config(self.cfg_path).listen_port, 9100)
self.assertTrue(any("kickstart" in " ".join(c) or "bootstrap" in " ".join(c) for c in self.calls))
- Step 2: Run tests to verify they fail
Run: PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
Expected: FAIL (ModuleNotFoundError: No module named 'cp0_mac_receiver.cli').
-
Step 3: Implement
cli.pyand executable entrypointsbin/cp0-mac-receiverandbin/cp0-mac-sync -
cli.py:argparsesubcommandsinstall-service,uninstall-service,set-dir <path>,set-port <port>,status,logs [--follow]; generates plist viaplistlib.dumps, manageslaunchctl bootout/bootstrap/kickstartforgui/<uid>, queriestailscale status --json(optional best-effort) and local/healthinstatus. -
bin/cp0-mac-receiver:#!/usr/bin/env python3entrypoint setting up rotating logger (~/Library/Logs/cp0-mac-sync.log, 5 MB × 2 backups) and runningMacReceiverServer. -
bin/cp0-mac-sync:#!/usr/bin/env python3entrypoint invokingrun_cli(sys.argv[1:]),chmod +xboth scripts. -
Step 4: Run tests to verify they pass
Run: PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
Expected: PASS (test_server.py and test_cli.py all OK).
- Step 5: Commit
git add mac-receiver/cp0_mac_receiver/cli.py mac-receiver/bin/cp0-mac-receiver mac-receiver/bin/cp0-mac-sync mac-receiver/tests/test_cli.py
git commit -m "feat(mac-receiver): add cp0-mac-sync CLI and LaunchAgent management"
Task 3: On-Device Config & SQLite Queue Store (device-daemon/)
Files:
- Create:
device-daemon/cp0_syncd/__init__.py - Create:
device-daemon/cp0_syncd/config.py - Create:
device-daemon/cp0_syncd/store.py - Test:
device-daemon/tests/test_store_and_config.py
Interfaces:
-
Produces:
WatchedFolder(id: str, path: str, label: str, enabled: bool)DaemonConfig(target_host: str, target_port: int, theme: str, watched_folders: list[WatchedFolder], extensions: list[str], ignore_prefixes: list[str], ignore_suffixes: list[str])load_daemon_config(path: Path | None = None, home_dir: Path | None = None) -> DaemonConfigsave_daemon_config(cfg: DaemonConfig, path: Path | None = None) -> Noneadd_watched_folder(cfg: DaemonConfig, folder_path: str, label: str | None = None) -> tuple[DaemonConfig, WatchedFolder](raisesValueErroron overlap or non-existent dir; auto-disambiguates duplicate labels)remove_watched_folder(cfg: DaemonConfig, folder_id: str) -> DaemonConfigSyncStore(db_path: Path)with WAL mode,enqueue_file(folder_id, abs_path, rel_path, size_bytes, mtime_ns, sha256) -> str,next_pending() -> dict | None,mark_uploading(file_id),mark_synced(file_id),mark_retry(file_id, err),mark_failed(file_id, err),delete_file(file_id),purge_pending_for_folder(folder_id),retry_all_failed() -> int,log(level, message)(pruned to 500 rows),set_meta(key, value),get_status_snapshot(watched_folders) -> dict,is_media_file(path: Path, cfg: DaemonConfig) -> bool
-
Step 1: Write failing tests for default config, label disambiguation, overlap rejection, zero-byte skipping, WAL SQLite dedup, and 500-row log cap
# device-daemon/tests/test_store_and_config.py
import tempfile, unittest
from pathlib import Path
from cp0_syncd.config import (
DaemonConfig, add_watched_folder, load_daemon_config, save_daemon_config,
)
from cp0_syncd.store import SyncStore, compute_sha256, is_media_file
class TestDaemonConfig(unittest.TestCase):
def test_first_run_creates_default_camera_folder_and_theme(self):
with tempfile.TemporaryDirectory() as tmp:
home = Path(tmp) / "home"
cfg_path = Path(tmp) / "config.json"
cfg = load_daemon_config(cfg_path, home_dir=home)
self.assertEqual(cfg.theme, "dark")
self.assertEqual(cfg.target_port, 8765)
self.assertEqual(len(cfg.watched_folders), 1)
self.assertEqual(cfg.watched_folders[0].path, str(home / "Pictures" / "DCIM" / "Camera"))
self.assertEqual(cfg.watched_folders[0].label, "Camera")
def test_corrupt_config_falls_back_to_defaults(self):
with tempfile.TemporaryDirectory() as tmp:
cfg_path = Path(tmp) / "config.json"
cfg_path.write_text("{corrupt")
cfg = load_daemon_config(cfg_path, home_dir=Path(tmp))
self.assertEqual(cfg.theme, "dark")
def test_overlap_rejected_and_duplicate_labels_disambiguated(self):
with tempfile.TemporaryDirectory() as tmp:
d1 = Path(tmp) / "a" / "Camera"
d2 = Path(tmp) / "b" / "Camera"
child = d1 / "sub"
d1.mkdir(parents=True); d2.mkdir(parents=True); child.mkdir()
cfg = DaemonConfig(watched_folders=[])
cfg, wf1 = add_watched_folder(cfg, str(d1))
cfg, wf2 = add_watched_folder(cfg, str(d2))
self.assertEqual(wf1.label, "Camera")
self.assertEqual(wf2.label, "Camera-2")
with self.assertRaises(ValueError):
add_watched_folder(cfg, str(child))
class TestSyncStore(unittest.TestCase):
def test_dedup_zero_byte_skip_and_log_cap(self):
with tempfile.TemporaryDirectory() as tmp:
db = SyncStore(Path(tmp) / "state.db")
img = Path(tmp) / "IMG_0001.jpg"
img.write_bytes(b"photo-bytes")
zero = Path(tmp) / "empty.jpg"
zero.write_bytes(b"")
cfg = DaemonConfig()
self.assertTrue(is_media_file(img, cfg))
self.assertFalse(is_media_file(zero, cfg))
sha = compute_sha256(img)
self.assertEqual(db.enqueue_file("cam", str(img), "IMG_0001.jpg", 11, 1, sha), "enqueued")
row = db.next_pending()
db.mark_synced(row["id"])
self.assertEqual(db.enqueue_file("cam", str(img), "IMG_0001.jpg", 11, 1, sha), "already_synced")
for i in range(550):
db.log("INFO", f"msg {i}")
self.assertEqual(db.log_count(), 500)
db.close()
- Step 2: Run tests to verify they fail
Run: PYTHONPATH=device-daemon python3 -m unittest discover -s device-daemon/tests -v
Expected: FAIL (ModuleNotFoundError: No module named 'cp0_syncd').
-
Step 3: Implement
config.pyandstore.pyindevice-daemon/cp0_syncd/ -
config.py:WatchedFolder+DaemonConfigdataclasses, atomic save (.tmp+os.replace), safe fallback on corrupt JSON, first-run default<home>/Pictures/DCIM/Camera(label"Camera"), canonicalrealpathancestor/descendant overlap detection inadd_watched_folder, andCamera-2label disambiguation. -
store.py:sqlite3connection inWALmode (busy_timeout=5000),filestable with unique index on(folder_id, rel_path, sha256),logstable pruned to newest 500 rows,metakey-value table, andis_media_file()filtering extensions, hidden/temp prefixes/suffixes, and0-byte files. -
Step 4: Run tests to verify they pass
Run: PYTHONPATH=device-daemon python3 -m unittest discover -s device-daemon/tests -v
Expected: PASS (test_store_and_config.py OK).
- Step 5: Commit
git add device-daemon/cp0_syncd/__init__.py device-daemon/cp0_syncd/config.py device-daemon/cp0_syncd/store.py device-daemon/tests/test_store_and_config.py
git commit -m "feat(device-daemon): add daemon config, overlap guard, and SQLite WAL queue store"
Task 4: On-Device inotify Watcher, Wake-Probe Uploader, & Unix Socket IPC
Files:
- Create:
device-daemon/cp0_syncd/watcher.py - Create:
device-daemon/cp0_syncd/uploader.py - Create:
device-daemon/cp0_syncd/ipc.py - Create:
device-daemon/cp0_syncd/daemon.py - Create:
device-daemon/bin/cp0-syncd - Test:
device-daemon/tests/test_daemon_integration.py
Interfaces:
-
Consumes:
DaemonConfig,load_daemon_config,save_daemon_config,add_watched_folder,remove_watched_folder,SyncStore,compute_sha256,is_media_filefrom Task 3 -
Produces:
scan_folder(folder: WatchedFolder, cfg: DaemonConfig, store: SyncStore) -> intInotifyWatcher(on_file_ready: Callable[[WatchedFolder, Path], None], on_dir_created: Callable[[WatchedFolder, Path], None] | None = None)(usesctypeslibc.so.6on Linux with gracefulPollingWatcherfallback for non-Linux/macOS unit tests; tracks nearest existing ancestor for unmounted paths)Uploader(store: SyncStore, get_config: Callable[[], DaemonConfig], wake_event: threading.Event, probe_timeout: float = 3.0)withprocess_once() -> str(backoff sequence[5, 10, 20, 40, 60])IpcServer(sock_path: Path, handler: Callable[[dict], dict])(unlinks stale socket before bind, newline-delimited JSON)SyncDaemonorchestrating watcher + uploader + IPC server forbin/cp0-syncd
-
Step 1: Write failing integration tests covering sleep/wake retry, missing-file purge, 403/500 vs 413 handling, stale socket cleanup, IPC mutations, and end-to-end upload to
MacReceiverServer
# device-daemon/tests/test_daemon_integration.py
import hashlib, json, socket, tempfile, threading, unittest
from pathlib import Path
from cp0_syncd.config import DaemonConfig, WatchedFolder, save_daemon_config
from cp0_syncd.daemon import SyncDaemon
from cp0_syncd.ipc import IpcServer
from cp0_syncd.store import SyncStore
class TestDaemonIntegration(unittest.TestCase):
def test_stale_socket_unlinked_and_ipc_commands_work(self):
with tempfile.TemporaryDirectory() as tmp:
sock_path = Path(tmp) / "cp0-sync.sock"
sock_path.write_text("stale")
srv = IpcServer(sock_path, lambda req: {"ok": True, "cmd": req["cmd"]})
srv.start()
try:
with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as c:
c.connect(str(sock_path))
c.sendall(b'{"cmd":"status"}\n')
resp = json.loads(c.makefile().readline())
self.assertEqual(resp, {"ok": True, "cmd": "status"})
finally:
srv.stop()
def test_sleep_wake_end_to_end_and_missing_file_cleanup(self):
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "mac-receiver"))
from cp0_mac_receiver.config import MacConfig, save_mac_config
from cp0_mac_receiver.server import MacReceiverServer
with tempfile.TemporaryDirectory() as tmp:
cam_dir = Path(tmp) / "Camera"
dest_root = Path(tmp) / "MacDest"
cam_dir.mkdir()
p1 = cam_dir / "IMG_1.jpg"
p2 = cam_dir / "IMG_2.jpg"
p1.write_bytes(b"real-photo-1")
p2.write_bytes(b"real-photo-2")
# Allocate ephemeral unused port, then close before starting MacReceiverServer later
probe_sock = socket.socket()
probe_sock.bind(("127.0.0.1", 0))
port = probe_sock.getsockname()[1]
probe_sock.close()
cfg_path = Path(tmp) / "daemon.json"
db_path = Path(tmp) / "state.db"
sock_path = Path(tmp) / "cp0.sock"
save_daemon_config(DaemonConfig(
target_host="127.0.0.1",
target_port=port,
watched_folders=[WatchedFolder(id="cam", path=str(cam_dir), label="Camera")],
), cfg_path)
daemon = SyncDaemon(cfg_path, db_path, sock_path)
daemon.scan_all()
daemon.uploader.process_once()
self.assertEqual(daemon.store.get_meta("mac_online"), "false")
# Delete IMG_2.jpg while Mac is sleeping, then wake Mac receiver
p2.unlink()
mac_cfg = Path(tmp) / "mac.json"
save_mac_config(MacConfig(dest_root=str(dest_root), listen_host="127.0.0.1", listen_port=port, notify_on_batch=False, tailscale_only=True), mac_cfg)
srv = MacReceiverServer(mac_cfg)
t = threading.Thread(target=srv.serve_forever, daemon=True)
t.start()
try:
daemon.uploader.process_once()
self.assertEqual(daemon.store.get_meta("mac_online"), "true")
self.assertEqual((dest_root / "Camera" / "IMG_1.jpg").read_bytes(), b"real-photo-1")
self.assertFalse((dest_root / "Camera" / "IMG_2.jpg").exists())
self.assertIsNone(daemon.store.next_pending())
finally:
srv.shutdown()
srv.server_close()
daemon.store.close()
- Step 2: Run tests to verify they fail
Run: PYTHONPATH=device-daemon:mac-receiver python3 -m unittest discover -s device-daemon/tests -v
Expected: FAIL (ModuleNotFoundError: No module named 'cp0_syncd.watcher').
-
Step 3: Implement
watcher.py,uploader.py,ipc.py,daemon.py, andbin/cp0-syncd -
watcher.py: Recursivescan_folder()(skips if path missing);InotifyWatcherviactypeslibc.so.6(inotify_init1,inotify_add_watch,inotify_rm_watch,IN_CLOSE_WRITE | IN_MOVED_TO | IN_CREATE | IN_DELETE_SELF) attaching watches to subdirectories dynamically and tracking nearest existing ancestor when a configured SD card mount is missing, plus a cleanPollingWatcherfallback when not on Linux. -
uploader.py:GET /healthprobe (3stimeout) cachingmac_dest_rootinmeta; FIFOPOST /uploadstreaming viahttp.client/urllibwith percent-encodedX-CP0-Folder-Label&X-CP0-Rel-Path; catchesFileNotFoundErrorto remove vanished files cleanly; keepsPENDING+ pauses queue on network/5xx/401/403; marksFAILEDonly on400/413/422; adaptive backoff[5, 10, 20, 40, 60]interrupted immediately bywake_event. -
ipc.py&daemon.py: Unix stream server (unlinks existing socket beforebind()), implementsstatus,sync_now,add_folder,remove_folder,set_target,set_theme,retry_failed. -
bin/cp0-syncd:#!/usr/bin/env python3entrypoint handlingSIGTERM/SIGINTcleanly. -
Step 4: Run all Python tests across both
mac-receiveranddevice-daemon
Run: PYTHONPATH=device-daemon:mac-receiver python3 -m unittest discover -s device-daemon/tests -v && PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
Expected: PASS (all daemon and Mac receiver tests OK).
- Step 5: Commit
git add device-daemon/cp0_syncd/watcher.py device-daemon/cp0_syncd/uploader.py device-daemon/cp0_syncd/ipc.py device-daemon/cp0_syncd/daemon.py device-daemon/bin/cp0-syncd device-daemon/tests/test_daemon_integration.py
git commit -m "feat(device-daemon): add inotify watcher, adaptive wake uploader, and IPC daemon"
Task 5: Companion UI IPC Client, Tailscale Peer Discovery, & shadcn/ui Zinc Theme Tokens
Files:
- Create:
device-ui/CMakeLists.txt - Create:
device-ui/src/ipc_client.hpp - Create:
device-ui/src/ipc_client.cpp - Create:
device-ui/src/theme.hpp - Create:
device-ui/src/theme.cpp - Test:
device-ui/tests/test_ipc_and_theme.cpp
Interfaces:
-
Consumes: Unix socket JSON protocol from Task 4 (
status,sync_now,add_folder,remove_folder,set_target,set_theme,retry_failed) and SQLite WAL fallback~/.local/share/cp0-sync/state.db -
Produces:
struct DaemonStatus,struct FolderStatus,struct LogEntry,struct TailscalePeerclass IpcClient(fetch_status(),send_command(json),read_sqlite_fallback(),parse_tailscale_peers(json_str),list_tailscale_peers())enum class ThemeMode { Dark, Light },struct ShadcnPalette(exact hex tokens from Spec Section 5.4),get_palette(ThemeMode),toggle_theme(ThemeMode)
-
Step 1: Write failing C++ tests for IPC JSON parsing, SQLite fallback reading, Tailscale peer sorting (macOS/Darwin first, self excluded), and Zinc Dark/Light palette tokens
// device-ui/tests/test_ipc_and_theme.cpp
#include "ipc_client.hpp"
#include "theme.hpp"
#include <cassert>
int main() {
auto dark = cp0::get_palette(cp0::ThemeMode::Dark);
auto light = cp0::get_palette(cp0::ThemeMode::Light);
assert(dark.background == 0x09090b && dark.border == 0x27272a && dark.foreground == 0xfafafa);
assert(light.background == 0xfafafa && light.card == 0xffffff && light.border == 0xe4e4e7 && light.ring == 0x71717a);
assert(cp0::toggle_theme(cp0::ThemeMode::Dark) == cp0::ThemeMode::Light);
const char* ts_json = R"({"Self":{"ID":"self1"},"Peer":{"p1":{"HostName":"linux-box","DNSName":"linux.ts.net.","OS":"linux","Online":true,"TailscaleIPs":["100.64.0.2"]},"p2":{"HostName":"macbook","DNSName":"macbook.ts.net.","OS":"macOS","Online":true,"TailscaleIPs":["100.64.0.3"]}}})";
auto peers = cp0::parse_tailscale_peers(ts_json);
assert(peers.size() == 2);
assert(peers[0].hostname == "macbook" && peers[0].os == "macOS");
return 0;
}
(Include tests for IpcClient round-tripping against a real temporary AF_UNIX server socket and reading fallback rows from a temporary sqlite3 DB.)
- Step 2: Configure CMake and run tests to verify failure
Run: cmake -S device-ui -B device-ui/build -DCP0_UI_BUILD_TESTS=ON -DCP0_UI_BUILD_APP=OFF && cmake --build device-ui/build
Expected: FAIL (source files do not exist yet).
-
Step 3: Implement
CMakeLists.txt,theme.hpp/.cpp, andipc_client.hpp/.cpp -
CMakeLists.txt: C++17 projectcp0-sync-ui; optionsCP0_UI_BUILD_TESTS(defaultON) andCP0_UI_BUILD_APP(defaultON); linksSQLite::SQLite3for core library (cp0_ui_core); whenCP0_UI_BUILD_APP=ON, links LVGL v9 (FetchContentor localLVGL_DIR), FreeType2, and SDL2 (macOS/sim) or Linuxfbdev/evdev(CP0_UI_TARGET_DEVICE=ON). -
theme.hpp/.cpp: ExactShadcnPalettecolor tables for Zinc Dark and balanced Zinc Light matching Spec Section 5.4. -
ipc_client.hpp/.cpp: Non-blockingAF_UNIXclient (1stimeout), minimal dependency-free JSON parser/serializer (or single-headernlohmann/json.hppvendored or small parser—keep zero external network/pip requirements),sqlite3read-only fallback (SQLITE_OPEN_READONLY), andtailscale status --jsonpeer extraction prioritizingmacOS/darwinonline peers at top. -
Step 4: Build and run
ctestto verify tests pass
Run: cmake -S device-ui -B device-ui/build -DCP0_UI_BUILD_TESTS=ON -DCP0_UI_BUILD_APP=OFF && cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure
Expected: PASS (test_ipc_and_theme passes).
- Step 5: Commit
git add device-ui/CMakeLists.txt device-ui/src/ipc_client.hpp device-ui/src/ipc_client.cpp device-ui/src/theme.hpp device-ui/src/theme.cpp device-ui/tests/test_ipc_and_theme.cpp
git commit -m "feat(device-ui): add C++ IPC client, Tailscale peer parser, and shadcn Zinc themes"
Task 6: Companion UI 320×170 LVGL Views, Modals, & Keyboard Controller
Files:
- Create:
device-ui/src/ui_controller.hpp - Create:
device-ui/src/ui_controller.cpp - Create:
device-ui/src/app_ui.hpp - Create:
device-ui/src/app_ui.cpp - Create:
device-ui/src/main.cpp - Test:
device-ui/tests/test_ui_navigation.cpp
Interfaces:
-
Consumes:
IpcClient,DaemonStatus,ThemeMode,ShadcnPalette,get_palette,toggle_themefrom Task 5 -
Produces:
enum class ActiveTab { Status = 0, Folders = 1, Logs = 2 }enum class ModalKind { None, TargetPicker, DirPicker, ConfirmRemove, TextInput }class UiController: pure state/keyboard state machine handling1/2/3,Enter,T,C,A,D/Delete,R,j/k/arrow keys,Space,Backspace,Esc/Q, directory traversal, and emittingIpcActionrequestsclass LvglAppView(app_ui.hpp/.cpp): 320×170 LVGL v9 Bento card + segmentedTabsListrenderer with liveapply_theme(ThemeMode)switching and FreeType font loading (Inter+JetBrains Mono, falling back to LVGL built-in Montserrat/Unscii if.ttfabsent)cp0-sync-uiexecutable (main.cpp) supporting--sim/ macOS SDL2 window (320×170) and Linuxfbdev+evdev(cp0-keys)
-
Step 1: Write failing C++ tests for keyboard state transitions (
1/2/3,[T]theme toggle outside vs inside modal,[A]directory drill-down &Spacewatch,[D]confirm Y/N,[C]peer selection,[R]retry failed,Esc/Q)
// device-ui/tests/test_ui_navigation.cpp
#include "ui_controller.hpp"
#include <cassert>
#include <filesystem>
int main() {
cp0::UiController ctrl;
assert(ctrl.state().tab == cp0::ActiveTab::Status);
assert(ctrl.state().theme == cp0::ThemeMode::Dark);
// 'T' toggles theme on main tab, emits SetTheme action
auto action = ctrl.handle_key('t', cp0::KeyCode::Char);
assert(ctrl.state().theme == cp0::ThemeMode::Light);
assert(action.type == cp0::ActionType::SetTheme);
// '2' jumps to Folders, 'A' opens DirPicker, 'T' inside modal opens TextInput instead of toggling theme
ctrl.handle_key('2', cp0::KeyCode::Char);
assert(ctrl.state().tab == cp0::ActiveTab::Folders);
ctrl.handle_key('a', cp0::KeyCode::Char);
assert(ctrl.state().modal == cp0::ModalKind::DirPicker);
auto modal_t = ctrl.handle_key('t', cp0::KeyCode::Char);
assert(ctrl.state().modal == cp0::ModalKind::TextInput);
assert(ctrl.state().theme == cp0::ThemeMode::Light); // unchanged inside modal
(void)modal_t;
// 'Esc' closes modal, 'Esc' again requests Quit
ctrl.handle_key(0, cp0::KeyCode::Escape);
assert(ctrl.state().modal == cp0::ModalKind::None);
auto quit_act = ctrl.handle_key(0, cp0::KeyCode::Escape);
assert(quit_act.type == cp0::ActionType::Quit);
return 0;
}
(Also test [D] -> [Y] folder removal confirmation and DirPicker Enter / Backspace / Space directory selection against a std::filesystem::temp_directory_path() folder tree.)
- Step 2: Build and run
ctestto verify failure
Run: cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure
Expected: FAIL (ui_controller.hpp missing).
-
Step 3: Implement
ui_controller.hpp/.cpp,app_ui.hpp/.cpp,main.cpp, and verify SDL2 simulator build -
Implement
UiControllercleanly separated from LVGL objects so every keyboard shortcut and modal flow is unit-tested inctest. -
Implement
LvglAppViewcreating the 320×170 widget hierarchy matching Spec Section 5.4 (Top bar 24px,Main content 126px,Footer 20pxwith<kbd>keycaps), wiringlv_style_tstyles for Zinc Dark and Zinc Light so[T]swaps styles cleanly without recreating the screen, and loading FreeType fonts (Inter+JetBrains Mono) from/usr/share/cp0-sync/fonts/,/usr/share/fonts/, orassets/fonts/when present, with graceful LVGL built-in Montserrat/Unscii fallback when TTFs are absent. -
Wire
main.cppusinglv_sdl_window_create(320, 170)+lv_sdl_keyboard_create()on macOS/desktop simulator andlv_linux_fbdev_create()+lv_evdev_create()on CardputerZero Linux, pollingIpcClient::fetch_status()every1000 msvialv_timer_create. -
Step 4: Build both
ctestunit tests and full SDL2 app target (CP0_UI_BUILD_APP=ON)
Run: cmake -S device-ui -B device-ui/build -DCP0_UI_BUILD_TESTS=ON -DCP0_UI_BUILD_APP=ON && cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure
Expected: PASS (test_ipc_and_theme and test_ui_navigation pass; cp0-sync-ui binary links cleanly).
- Step 5: Commit
git add device-ui/CMakeLists.txt device-ui/src/ui_controller.hpp device-ui/src/ui_controller.cpp device-ui/src/app_ui.hpp device-ui/src/app_ui.cpp device-ui/src/main.cpp device-ui/tests/test_ui_navigation.cpp
git commit -m "feat(device-ui): add 320x170 LVGL shadcn Bento UI, modals, and keyboard controller"
Task 7: Debian (arm64 .deb) Packaging, APPLaunch Integration, & systemd --user Unit
Files:
- Create:
packaging/cp0-syncd.service - Create:
packaging/cp0-sync.desktop - Create:
packaging/cp0-sync.png(generated cleanly via Pythonstruct/zlibPNG writer or SVG→PNG so zero extra assets needed) - Create:
packaging/debian/control - Create:
packaging/debian/postinst - Create:
packaging/debian/prerm - Create:
packaging/build-deb.sh - Create:
packaging/Dockerfile.arm64 - Test:
packaging/tests/test_packaging.py
Interfaces:
-
Consumes:
device-daemon/bin/cp0-syncd,device-daemon/cp0_syncd/,device-ui/CMake build -
Produces:
cp0-sync_1.0.0_m5stack1_arm64.debcontaining/usr/bin/cp0-sync-ui,/usr/bin/cp0-syncd,/usr/lib/cp0-sync/cp0_syncd/...,/usr/lib/systemd/user/cp0-syncd.service,/usr/share/APPLaunch/applications/cp0-sync.desktop,/usr/share/APPLaunch/share/images/cp0-sync.png -
Step 1: Write failing validation tests verifying packaging metadata, systemd user unit paths, desktop entry fields, maintainer script permissions/hooks, and
cp0-sync.pngvalidity
# packaging/tests/test_packaging.py
import struct, unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
class TestPackagingAssets(unittest.TestCase):
def test_systemd_user_unit_and_desktop_entry(self):
unit = (ROOT / "packaging" / "cp0-syncd.service").read_text()
self.assertIn("ExecStart=/usr/bin/cp0-syncd", unit)
self.assertIn("WantedBy=default.target", unit)
desktop = (ROOT / "packaging" / "cp0-sync.desktop").read_text()
self.assertIn("Exec=/usr/bin/cp0-sync-ui", desktop)
self.assertIn("Icon=/usr/share/APPLaunch/share/images/cp0-sync.png", desktop)
def test_debian_control_and_maintainer_scripts(self):
ctrl = (ROOT / "packaging" / "debian" / "control").read_text()
self.assertIn("Package: cp0-sync", ctrl)
self.assertIn("Architecture: arm64", ctrl)
self.assertIn("python3 (>= 3.9)", ctrl)
postinst = (ROOT / "packaging" / "debian" / "postinst").read_text()
self.assertIn("systemctl --global enable cp0-syncd.service", postinst)
png = (ROOT / "packaging" / "cp0-sync.png").read_bytes()
self.assertEqual(png[:8], b"\x89PNG\r\n\x1a\n")
- Step 2: Run test to verify it fails
Run: python3 -m unittest discover -s packaging/tests -v
Expected: FAIL (FileNotFoundError).
-
Step 3: Create packaging files, icon PNG, maintainer scripts, and ARM64 Docker
.debbuild script -
packaging/cp0-syncd.service:systemd --userservice (Restart=on-failure,RestartSec=5,ExecStart=/usr/bin/cp0-syncd,WantedBy=default.target). -
packaging/cp0-sync.desktop:Type=Application,Name=Photo Sync,Exec=/usr/bin/cp0-sync-ui,Icon=/usr/share/APPLaunch/share/images/cp0-sync.png,Terminal=false. -
packaging/cp0-sync.png: crisp 64×64 zinc/white camera-sync icon PNG. -
packaging/debian/control,postinst(chmod 0755, runssystemctl --global enable cp0-syncd.serviceand starts active user units safely with|| true),prerm(chmod 0755, stops/disables user service on remove). -
packaging/Dockerfile.arm64&packaging/build-deb.sh: buildscp0-sync_1.0.0_m5stack1_arm64.debin--platform linux/arm64Debian Bookworm container (and also supports running directly on CardputerZero over SSH). -
Step 4: Run packaging tests (and build
.debif Dockerlinux/arm64daemon is available)
Run: python3 -m unittest discover -s packaging/tests -v
Expected: PASS (test_packaging.py OK).
- Step 5: Commit
git add packaging/
git commit -m "feat(packaging): add systemd user unit, APPLaunch entry, and arm64 deb builder"