2026-05-15 17:05:13 -07:00
|
|
|
# @mac-sync
|
|
|
|
|
|
2026-05-15 18:02:04 -07:00
|
|
|
Unified macOS sync agent — Messages, Photos, Mail, Calendar (2-way), Reminders (2-way), Notes (2-way via AppleScript), Contacts, plus message search/embeddings — in one menu-bar app + one server.
|
2026-05-15 17:05:13 -07:00
|
|
|
|
2026-05-15 18:02:04 -07:00
|
|
|
Latest plan: `~/.claude/plans/magical-tumbling-peach.md`.
|
2026-05-15 17:05:13 -07:00
|
|
|
|
|
|
|
|
## Structure
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
@packages/
|
2026-05-15 18:02:04 -07:00
|
|
|
shared/ MacSyncShared SwiftPM target
|
|
|
|
|
• Sync/ BaseSyncManager, BlobSyncManager,
|
|
|
|
|
SendQueueClient, SyncConnectionError
|
|
|
|
|
• Storage/ ActivityLog, ConfigFile
|
|
|
|
|
• Transport/ Shared, DeviceRegistration
|
|
|
|
|
• Util/ ContentTypeMapping, PhoneUtils,
|
|
|
|
|
AppleScriptEscape
|
|
|
|
|
• WebServer/ LocalWebServer
|
|
|
|
|
imessage/ IMessageSync SwiftPM target (bidirectional via
|
|
|
|
|
SendQueueClient,
|
|
|
|
|
wrapping the legacy
|
|
|
|
|
server-side
|
|
|
|
|
icloud.send_queue table;
|
|
|
|
|
attachment blob upload)
|
|
|
|
|
iphoto/ IPhotoSync SwiftPM target (read-only Mac → server,
|
|
|
|
|
photo blob upload)
|
|
|
|
|
imail/ IMailSync SwiftPM target (bidirectional via AppleScript)
|
|
|
|
|
ical/ ICalSync SwiftPM target (bidirectional via SendQueueClient)
|
|
|
|
|
ireminders/ IReminderSync SwiftPM target (bidirectional via SendQueueClient)
|
|
|
|
|
inotes/ INoteSync SwiftPM target (bidirectional via AppleScript)
|
|
|
|
|
contacts-sync-core/ ContactsSyncCore SwiftPM target (Contacts.framework
|
|
|
|
|
→ server)
|
|
|
|
|
src/client/ MacSyncApp executable (menu bar app)
|
|
|
|
|
src/server/ Hono + Bun + PostgreSQL server (TypeScript)
|
|
|
|
|
• features/embedding — message embedding pipeline
|
|
|
|
|
• features/search — semantic + keyword search with cache
|
|
|
|
|
• features/imessage — iMessage ingestion / send queue
|
|
|
|
|
• features/prospect — outreach prospect graph
|
|
|
|
|
deploy/ install.sh, LaunchAgent template, systemd units
|
|
|
|
|
web/ React SPA dashboard
|
2026-05-15 17:05:13 -07:00
|
|
|
```
|
|
|
|
|
|
2026-05-15 18:02:04 -07:00
|
|
|
## Architecture invariants
|
|
|
|
|
|
|
|
|
|
- **One sync manager per module**, all extending `BaseSyncManager<Stats, SyncError>`.
|
|
|
|
|
Blob-uploading modules (iMessage attachments, iPhoto) additionally use
|
|
|
|
|
`BlobSyncManager` for the blob upload pipeline.
|
|
|
|
|
- **One send queue contract**. Per-module Postgres tables (`icloud.<module>_send_queue`)
|
|
|
|
|
use the shared `createSendQueueRepo` factory. iMessage's legacy `icloud.send_queue`
|
|
|
|
|
table predates the factory and stays on its own bespoke schema, but the Mac
|
|
|
|
|
client polls all of them via the same generic `SendQueueClient<Transport>`
|
|
|
|
|
(60s for calendar/reminders/notes, 30s for iMessage).
|
|
|
|
|
- **Single AppleScript escape helper** — `MacSyncShared/Util/AppleScriptEscape.swift`.
|
|
|
|
|
- **Embedding/search pipeline** is server-side only. The Mac client ingests
|
|
|
|
|
messages; embedding generation, search caching, and sync-history bookkeeping
|
|
|
|
|
all live on the server.
|
|
|
|
|
|
2026-05-15 17:05:13 -07:00
|
|
|
## Dev
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
make build # swift build --product MacSyncApp
|
|
|
|
|
make test # swift test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Safety
|
|
|
|
|
|
|
|
|
|
- NEVER commit — external service handles commits
|
|
|
|
|
- NEVER pkill node
|
|
|
|
|
- NEVER use file: or link: in package.json
|
