Solidify sync engine + add web UI

Author: salaamdev

.env.local.example

@@ -6,14 +6,15 @@ TASK_SYNC_PROVIDER_B=microsoft
 TASK_SYNC_STATE_DIR=.task-sync
 TASK_SYNC_LOG_LEVEL=info
 
-# Google Tasks
+# Google Tasks — https://console.cloud.google.com/
 TASK_SYNC_GOOGLE_CLIENT_ID=
 TASK_SYNC_GOOGLE_CLIENT_SECRET=
 TASK_SYNC_GOOGLE_REFRESH_TOKEN=
-TASK_SYNC_GOOGLE_TASKLIST_ID=@default
+# TASK_SYNC_GOOGLE_TASKLIST_ID=@default
 
-# Microsoft To Do
+# Microsoft To Do — https://portal.azure.com/
 TASK_SYNC_MS_CLIENT_ID=
-TASK_SYNC_MS_TENANT_ID=common
+TASK_SYNC_MS_CLIENT_SECRET=
+TASK_SYNC_MS_TENANT_ID=consumers
 TASK_SYNC_MS_REFRESH_TOKEN=
 # TASK_SYNC_MS_LIST_ID=

.gitignore

@@ -18,3 +18,9 @@ yarn-error.log*
 
 # OS
 .DS_Store
+
+# web
+web/.next/
+web/node_modules/
+web/out/
+web/next-env.d.ts

README.md

@@ -2,162 +2,251 @@
 
 Sync tasks between **Google Tasks** and **Microsoft To Do**.
 
-Providers:
+Works as a CLI for power users, or as a self-hosted web UI for everyone else.
 
-- Google Tasks (OAuth refresh-token)
-- Microsoft To Do via Microsoft Graph (OAuth refresh-token)
+## Features
 
-## Quickstart
+- **Bidirectional sync** between Google Tasks and Microsoft To Do
+- **Field-level conflict resolution** (last-write-wins per field)
+- **Cold-start matching** — deduplicates tasks on first sync by title + notes
+- **Delete propagation** — tombstones prevent resurrecting deleted tasks
+- **Dry-run mode** — preview changes before applying
+- **Polling mode** — auto-sync on an interval
+- **Web UI** — connect accounts with OAuth, sync with one click
+- **Self-hosted** — your data stays on your machine
 
-### Requirements
+## Requirements
 
 - Node.js **>= 22**
 
-### Install
+## Quick Start — Web UI
 
-```bash
-npm install
-```
+The web UI lets you connect your Google and Microsoft accounts via OAuth
+and sync tasks with one click. No manual token management needed.
 
-### Build + run doctor
+### 1. Set up OAuth apps
 
-```bash
-npm run build
-node dist/cli.js doctor
-```
+**Google Tasks:**
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or select existing)
+3. Enable the **Google Tasks API**
+4. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**
+5. Application type: **Web application**
+6. Add authorized redirect URI: `http://localhost:3000/api/auth/google/callback`
+7. Copy the **Client ID** and **Client Secret**
 
-### Run sync once
+**Microsoft To Do:**
+
+1. Go to [Azure Portal → App registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
+2. **New registration**
+3. Supported account types: **Personal Microsoft accounts only** (or multi-tenant)
+4. Redirect URI (Web): `http://localhost:3000/api/auth/microsoft/callback`
+5. Go to **API permissions** → Add: `Tasks.ReadWrite`, `User.Read`, `offline_access`
+6. Copy the **Application (client) ID**
+
+### 2. Configure
+
+Create `.env.local` in the project root:
 
 ```bash
-node dist/cli.js sync
+TASK_SYNC_PROVIDER_A=google
+TASK_SYNC_PROVIDER_B=microsoft
+
+TASK_SYNC_GOOGLE_CLIENT_ID=your-google-client-id
+TASK_SYNC_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+TASK_SYNC_MS_CLIENT_ID=your-microsoft-client-id
+TASK_SYNC_MS_TENANT_ID=consumers
 ```
 
-### Polling mode
+### 3. Install and run
 
 ```bash
-# every 5 minutes
-node dist/cli.js sync --poll 5
-
-# or env
-export TASK_SYNC_POLL_INTERVAL_MINUTES=5
-node dist/cli.js sync
+npm install
+npm run web:install
+npm run web:dev
 ```
 
-### Dry-run
+Open [http://localhost:3000](http://localhost:3000). Click **Connect** for each
+provider, approve the OAuth consent, then hit **Sync Now**.
 
-Dry-run still uses your configured providers, but **does not write** any changes.
+### Production
 
 ```bash
-node dist/cli.js sync --dry-run
+npm run web:build
+npm run web:start
 ```
 
-## Configuration (.env)
+## Quick Start — CLI
 
-Create a `.env.local` (recommended) or `.env`:
+For headless environments, scripts, or cron jobs.
 
-### Provider selection
+### 1. Install
 
 ```bash
-TASK_SYNC_PROVIDER_A=google
-TASK_SYNC_PROVIDER_B=microsoft
+npm install
+npm run build
 ```
 
-### State
+### 2. Get refresh tokens
+
+You need refresh tokens for each provider. Helper scripts are included:
 
 ```bash
-TASK_SYNC_STATE_DIR=.task-sync
-TASK_SYNC_LOG_LEVEL=info
+# Google
+export TASK_SYNC_GOOGLE_CLIENT_ID=...
+export TASK_SYNC_GOOGLE_CLIENT_SECRET=...
+npm run oauth:google
+
+# Microsoft
+export TASK_SYNC_MS_CLIENT_ID=...
+export TASK_SYNC_MS_TENANT_ID=consumers
+npm run oauth:microsoft
 ```
 
-### Google Tasks
+Each script opens a browser for consent, then prints the refresh token.
+
+### 3. Configure
+
+Add all tokens to `.env.local`:
 
 ```bash
+TASK_SYNC_PROVIDER_A=google
+TASK_SYNC_PROVIDER_B=microsoft
+
 TASK_SYNC_GOOGLE_CLIENT_ID=...
 TASK_SYNC_GOOGLE_CLIENT_SECRET=...
 TASK_SYNC_GOOGLE_REFRESH_TOKEN=...
-TASK_SYNC_GOOGLE_TASKLIST_ID=@default   # optional
-```
 
-### Microsoft To Do (Graph)
-
-```bash
 TASK_SYNC_MS_CLIENT_ID=...
-TASK_SYNC_MS_TENANT_ID=common   # or your tenant id
+TASK_SYNC_MS_TENANT_ID=consumers
 TASK_SYNC_MS_REFRESH_TOKEN=...
-TASK_SYNC_MS_LIST_ID=...        # optional (defaults to first list)
 ```
 
-Run:
+### 4. Run
 
 ```bash
-task-sync doctor
+# Check config
+node dist/cli.js doctor
+
+# Sync once
+node dist/cli.js sync
+
+# Dry-run (preview changes)
+node dist/cli.js sync --dry-run
+
+# Auto-sync every 5 minutes
+node dist/cli.js sync --poll 5
+
+# JSON output (for scripts)
+node dist/cli.js sync --format json
 ```
 
-to see what's missing.
+## Configuration
 
-## OAuth helper scripts (refresh tokens)
+All configuration is via environment variables. Create a `.env.local` file in the
+project root.
 
-These scripts spin up a local HTTP callback server, print an auth URL, and on success print the refresh token.
+### Required
 
-### Google refresh token
+| Variable | Description |
+|---|---|
+| `TASK_SYNC_PROVIDER_A` | First provider (`google` or `microsoft`) |
+| `TASK_SYNC_PROVIDER_B` | Second provider (`google` or `microsoft`) |
+| `TASK_SYNC_GOOGLE_CLIENT_ID` | Google OAuth client ID |
+| `TASK_SYNC_GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
+| `TASK_SYNC_MS_CLIENT_ID` | Microsoft app (client) ID |
 
-1) Create OAuth credentials in Google Cloud Console:
-- APIs & Services → Credentials
-- Create Credentials → OAuth client ID
-- Application type: **Desktop app** (recommended)
-- Enable the **Google Tasks API** on the project
+### Optional
 
-2) Set env vars and run:
+| Variable | Default | Description |
+|---|---|---|
+| `TASK_SYNC_MS_TENANT_ID` | `consumers` | Azure tenant ID |
+| `TASK_SYNC_GOOGLE_REFRESH_TOKEN` | — | CLI only: Google refresh token |
+| `TASK_SYNC_MS_REFRESH_TOKEN` | — | CLI only: Microsoft refresh token |
+| `TASK_SYNC_GOOGLE_TASKLIST_ID` | `@default` | Google task list to sync |
+| `TASK_SYNC_MS_LIST_ID` | First list | Microsoft To Do list to sync |
+| `TASK_SYNC_STATE_DIR` | `.task-sync` | Directory for sync state |
+| `TASK_SYNC_LOG_LEVEL` | `info` | Log level: `silent\|error\|warn\|info\|debug` |
+| `TASK_SYNC_POLL_INTERVAL_MINUTES` | — | Auto-sync interval (CLI only) |
+| `TASK_SYNC_MODE` | `bidirectional` | Sync mode: `bidirectional\|a-to-b-only\|mirror` |
+| `TASK_SYNC_TOMBSTONE_TTL_DAYS` | `30` | How long to keep delete tombstones |
 
-```bash
-export TASK_SYNC_GOOGLE_CLIENT_ID=...
-export TASK_SYNC_GOOGLE_CLIENT_SECRET=...
-npm run oauth:google
-```
+## How It Works
 
-### Microsoft refresh token
+### Sync State
 
-1) Create an app registration in Azure:
-- Azure Portal → App registrations → New registration
-- Add a **redirect URI** (platform: *Mobile and desktop applications*):
-  - `http://localhost:53683/callback`
-- API permissions (Delegated):
-  - `offline_access`
-  - `User.Read`
-  - `Tasks.ReadWrite`
+`task-sync` stores local state in `.task-sync/state.json`:
 
-2) Run:
+- **`lastSyncAt`** — watermark timestamp for incremental sync
+- **`mappings`** — links canonical task IDs to provider-specific IDs
+- **`tombstones`** — prevents resurrecting deleted tasks
 
-```bash
-export TASK_SYNC_MS_CLIENT_ID=...
-export TASK_SYNC_MS_TENANT_ID=common
-npm run oauth:microsoft
-```
+Delete `.task-sync/` to reset all sync state.
 
-## How state works
+### Web UI Token Storage
 
-`task-sync` writes local state under:
+The web UI stores OAuth refresh tokens in `.task-sync/tokens.json`. These
+tokens never leave your machine. The web server uses them to authenticate
+with Google and Microsoft APIs on your behalf during sync.
 
-- `.task-sync/state.json`
+### Sync Algorithm
 
-This includes:
+1. **Fetch** tasks from all providers (incremental via `lastSyncAt`)
+2. **Cold-start match** — on first run, match tasks by title+notes to avoid duplicates
+3. **Tombstone check** — skip tasks that were intentionally deleted
+4. **Field-level diff** — compare each field (title, notes, status, due date) against the last canonical snapshot
+5. **Conflict resolution** — if multiple providers changed the same field, last-write-wins
+6. **Fan out** — apply the resolved canonical state to all providers
 
-- `lastSyncAt` watermark (ISO timestamp)
-- `mappings`: links a canonical ID to provider IDs
-- `tombstones`: prevents resurrecting deleted tasks
+## Project Structure
 
-Delete `.task-sync/` to reset sync state.
+```
+task-sync/
+├── src/                    # Core engine + CLI
+│   ├── cli.ts              # CLI entry point
+│   ├── sync/engine.ts      # Sync algorithm
+│   ├── providers/          # Google, Microsoft, Mock providers
+│   ├── store/              # State persistence (JSON)
+│   ├── model.ts            # Task data model
+│   └── ...
+├── web/                    # Next.js web UI
+│   ├── app/                # Pages + API routes
+│   │   ├── page.tsx        # Dashboard
+│   │   └── api/            # OAuth + sync endpoints
+│   ├── components/         # React components (shadcn/ui)
+│   └── lib/                # Env loading, token storage
+├── test/                   # Vitest tests
+├── scripts/                # OAuth helper scripts
+└── .env.local              # Your credentials (git-ignored)
+```
 
 ## Development
 
 ```bash
+# Run CLI in dev mode
 npm run dev -- doctor
 npm run dev -- sync --dry-run
+
+# Run web in dev mode (builds core first)
+npm run web:dev
+
+# Tests
 npm test
+
+# Lint & typecheck
 npm run lint
 npm run typecheck
 ```
 
+## Security Notes
+
+- **Self-hosted only** — this project is designed to run on your own machine or server.
+- **No telemetry** — no data is sent anywhere except Google and Microsoft APIs.
+- **Tokens on disk** — refresh tokens are stored in `.task-sync/tokens.json`. Treat this file like a password.
+- **No auth on the web UI** — if you expose the web UI to the internet, put it behind a reverse proxy with authentication (e.g., Caddy, nginx + basic auth, Cloudflare Tunnel).
+
 ## License
 
-MIT (see LICENSE)
+MIT (see [LICENSE](LICENSE))

eslint.config.js

@@ -5,7 +5,7 @@ export default tseslint.config(
   js.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ['dist/**', 'node_modules/**'],
+    ignores: ['dist/**', 'node_modules/**', 'web/**'],
   },
   {
     rules: {

package.json

@@ -11,7 +11,11 @@
     "lint": "eslint .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "oauth:google": "tsx scripts/google_oauth.ts",
-    "oauth:microsoft": "tsx scripts/microsoft_oauth.ts"
+    "oauth:microsoft": "tsx scripts/microsoft_oauth.ts",
+    "web:dev": "npm run build && npm run --prefix web dev",
+    "web:build": "npm run build && npm run --prefix web build",
+    "web:start": "npm run --prefix web start",
+    "web:install": "npm install --prefix web"
   },
   "repository": {
     "type": "git",

src/cli.ts

@@ -90,6 +90,8 @@ program
         clientId: env.TASK_SYNC_MS_CLIENT_ID!,
         tenantId: env.TASK_SYNC_MS_TENANT_ID!,
         refreshToken: env.TASK_SYNC_MS_REFRESH_TOKEN!,
+        // CLI uses public client flow (Mobile/Desktop platform) — no secret needed.
+        // The web UI uses confidential client flow (Web platform) with its own secret.
         listId: env.TASK_SYNC_MS_LIST_ID,
       });
     };