feat(sync): wire up cf-core sync module for cross-device localStorage #151

New issue

Open

opened 2026-06-05 12:53:51 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-06-05 12:53:51 -07:00

Owner

Context

circuitforge_core.sync (cf-core #56 + #57) ships a shared opt-in localStorage sync module. Kiwi is the primary motivation — cook log and bookmarks are localStorage-only today.

What to wire up

Install dep: pip install -e ../circuitforge-core[sync]
In app/main.py (FastAPI lifespan), add:

from circuitforge_core.sync import make_sync_router, SyncConfig

sync_router = make_sync_router(
    product="kiwi",
    get_session=_sessions.dependency(),
    require_paid=_sessions.require_tier("paid"),
    config=SyncConfig.from_env("kiwi"),
)
app.include_router(sync_router, prefix="/sync", tags=["sync"])

Add SYNC_DB_PATH / CLOUD_DATA_ROOT to .env.example
Add frontend sync toggle UI (settings page) — one toggle per data class:
- kiwi:cook_log
- kiwi:bookmarks
- kiwi:dismissed
Wire localStorage writes to call POST /sync/push after save (Paid+ only)
On app load (Paid+), call GET /sync/pull and merge into localStorage

Notes

Prefs default to disabled — no pre-checked boxes, consent is per data class
DELETE /sync/all and DELETE /sync/data must be accessible from account/settings (any tier)
Unblocks cross-device orbital recipe cadence (kiwi#120 deferred aspect)

References

cf-core sync module: circuitforge_core/sync/
cf-core #56 (storage), #57 (consent layer)

## Context `circuitforge_core.sync` (cf-core #56 + #57) ships a shared opt-in localStorage sync module. Kiwi is the primary motivation — cook log and bookmarks are localStorage-only today. ## What to wire up 1. Install dep: `pip install -e ../circuitforge-core[sync]` 2. In `app/main.py` (FastAPI lifespan), add: ```python from circuitforge_core.sync import make_sync_router, SyncConfig sync_router = make_sync_router( product="kiwi", get_session=_sessions.dependency(), require_paid=_sessions.require_tier("paid"), config=SyncConfig.from_env("kiwi"), ) app.include_router(sync_router, prefix="/sync", tags=["sync"]) ``` 3. Add `SYNC_DB_PATH` / `CLOUD_DATA_ROOT` to `.env.example` 4. Add frontend sync toggle UI (settings page) — one toggle per data class: - `kiwi:cook_log` - `kiwi:bookmarks` - `kiwi:dismissed` 5. Wire localStorage writes to call `POST /sync/push` after save (Paid+ only) 6. On app load (Paid+), call `GET /sync/pull` and merge into localStorage ## Notes - Prefs default to disabled — no pre-checked boxes, consent is per data class - `DELETE /sync/all` and `DELETE /sync/data` must be accessible from account/settings (any tier) - Unblocks cross-device orbital recipe cadence (kiwi#120 deferred aspect) ## References - cf-core sync module: `circuitforge_core/sync/` - cf-core #56 (storage), #57 (consent layer)