# @mac-sync

Unified macOS sync agent — Messages, Photos, Mail, Calendar (2-way), Reminders (2-way), Notes (2-way via AppleScript), Calls (read-only), Contacts, plus message search/embeddings — in one menu-bar app + one server.

Latest plan: `~/.claude/plans/magical-tumbling-peach.md`.

## Structure

```
@packages/
  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)
  icalls/                ICallsSync SwiftPM target    (read-only Mac → server)
  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
```

## 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.

## 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