| name | google-sync-debug |
| description | Diagnoses Compass Google Calendar sync, OAuth, webhook, job, connection-health, and SSE failures by tracing the correct browser, backend, sync-service, provider, and storage boundary. Use when Google events are stale, imports or watches fail, reconnect is required, sync jobs stall, or connection health reports attention. |
Debug Google sync
Find the failing boundary before changing code. Read:
docs/features/google-sync-and-sse-flow.mddocs/development/local-development.mddocs/development/testing-playbook.md#testing-realtime-and-sync-changes
Never print credentials, refresh tokens, internal auth tokens, notification
tokens, or the contents of compass.yaml.
1. Classify the symptom
Identify the first observable failure:
- OAuth cannot start or complete
- provider connection is missing, revoked, or requires reconnect
- initial import or repair does not finish
- Compass changes do not reach Google
- Google changes do not reach Compass
- backend changes arrive but the browser stays stale
- sync jobs remain pending, leased, or retrying
- health/readiness reports attention
Record user state, environment, effective service URLs, calendar/provider, and
the last successful step without collecting sensitive payloads.
2. Verify local prerequisites
Invoke /local-dev-bootstrap for incomplete setup.
- Backend, sync service, MongoDB, and web must use the current worktree's
effective ports.
- Google OAuth credentials and redirect URIs must match the selected port.
- Browser API and SSE traffic can remain local.
- Google watch notifications require a public HTTPS
sync.callbackBaseUrl
(proxied as /sync/*).
- A local HTTP backend can support OAuth and initial import but not inbound
Google webhook delivery.
Check backend and sync liveness/readiness before debugging domain logic.
3. Trace the relevant path
Connection and OAuth
Trace web authorization → backend-facing connection API → sync internal auth →
provider auth adapter → encrypted credential custody → connection metadata.
Verify signed OAuth state, callback URL, scopes, and reconnect/revocation state.
Compass to Google
Trace the browser mutation → backend event command/integration boundary → sync
command/job → provider writer → invalidation/change feed → backend SSE publish →
web query invalidation.
Google to Compass
Trace provider webhook → notification verification → subscription/resource →
pull job → provider reader → normalized event persistence → invalidation/change
feed → backend SSE → web refetch.
Use correlation/job/resource identifiers where available, but redact provider
payload content in reports.
4. Distinguish common failures
- OAuth redirect mismatch is not a webhook reachability failure.
- A successful optimistic UI update does not prove backend or provider
persistence.
- A successful provider write does not prove invalidation/SSE delivery.
- A healthy SSE connection does not prove the sync job ran.
- Missing Google credentials can leave the sync service healthy but passive.
- Mongo readiness failure should be fixed before investigating provider calls.
- Revoked refresh tokens require reconnect behavior, not retry loops.
- Expired/missing subscriptions should flow through renewal/reconciliation.
5. Test the narrowest layer
- Provider-independent logic: focused
packages/sync unit test
- Storage, leasing, custody, or job behavior:
*.db.test.ts then
bun run test:sync
- Backend integration/SSE emitter: focused backend test then
bun run test:backend
- Web listener/refetch state: focused web test then
bun run test:web
- Shared payload/contract:
bun run test:core, affected consumers, and
bun run type-check
Use test adapters and drivers. Do not call real Google APIs from automated
tests or weaken notification verification to simplify a test.
Report
State:
- failing boundary and evidence
- last confirmed successful boundary
- root cause or remaining hypotheses, clearly separated
- safe fix and regression coverage
- commands/scenarios run
- setup limitation when live webhook or OAuth behavior could not be exercised
