@bobfrankston/mailx 1.0.1

package/README.md

@@ -0,0 +1,160 @@
+# mailx — Email Client
+
+A local-first email client with IMAP sync, full offline reading, and a standalone native app. Replaces Thunderbird/Outlook.
+
+## Quick Start
+
+```bash
+npm start                  # Start server (auto-restarts on changes)
+# Open http://localhost:9333 in browser
+
+launch.ps1                 # Or use the native WebView2 app
+launch.ps1 -restart        # Kill existing server and restart
+```
+
+## Setup
+
+### 1. Config Pointer (~/.mailx/config.json)
+
+Points to the shared settings file and local store:
+
+```json
+{
+  "settingsPath": "C:/Users/You/OneDrive/home/.mailx/settings.jsonc",
+  "storePath": "C:/Users/You/.mailx/mailxstore"
+}
+```
+
+- **settingsPath** — Path to shared settings (can be on OneDrive/Dropbox for multi-machine sync)
+- **storePath** — Where cached message bodies are stored (local, not synced)
+
+If `config.json` doesn't exist, settings default to `~/.mailx/settings.jsonc`.
+
+### 2. Settings File (settings.jsonc)
+
+```jsonc
+{
+  "accounts": [
+    {
+      "id": "work",               // Unique ID (internal)
+      "name": "Work Email",        // Display name in UI
+      "email": "bob@example.com",
+      "imap": {
+        "host": "imap.example.com",
+        "port": 993,
+        "tls": true,
+        "auth": "password",        // "password" or "oauth2"
+        "user": "bob",
+        "password": "secret"
+      },
+      "smtp": {
+        "host": "smtp.example.com",
+        "port": 587,
+        "tls": true,
+        "auth": "password",
+        "user": "bob",
+        "password": "secret"
+      },
+      "enabled": true
+    },
+    {
+      "id": "gmail",
+      "name": "Gmail",
+      "email": "bob@gmail.com",
+      "imap": {
+        "host": "imap.gmail.com", "port": 993, "tls": true,
+        "auth": "oauth2", "user": "bob@gmail.com"
+      },
+      "smtp": {
+        "host": "smtp.gmail.com", "port": 587, "tls": true,
+        "auth": "oauth2", "user": "bob@gmail.com"
+      },
+      "enabled": true
+    }
+  ],
+  "sync": {
+    "intervalMinutes": 5,          // Full sync interval
+    "historyDays": 30              // Days of history (0 = all)
+  },
+  "ui": {
+    "theme": "dark",
+    "folderWidth": 220,
+    "listViewerSplit": 40,
+    "fontSize": 14
+  },
+  // Auto-populated when you click "Always allow from sender/domain"
+  "remoteAllowList": {
+    "senders": [],
+    "domains": []
+  }
+}
+```
+
+### 3. Gmail OAuth
+
+1. [Google Cloud Console](https://console.cloud.google.com/) → create project
+2. Enable Gmail API (and People API for contacts)
+3. Create OAuth 2.0 credentials (Desktop app)
+4. Download `credentials.json` to the iflow package directory
+5. First connect opens browser for consent. Tokens cached and refresh automatically.
+
+## Usage
+
+### Reading Mail
+- **Folder tree** (left) — click to view, expand/collapse subfolders
+- **Message list** (center) — click to preview, scroll for more
+- **Preview pane** (right) — shows message content
+- **All Inboxes** — unified view across all accounts
+
+### Composing
+- **Compose** — toolbar or Ctrl+N
+- **Reply / Reply All / Forward** — Ctrl+R / Ctrl+Shift+R / toolbar
+- **Send** — Ctrl+Enter
+- **From field** — pick from dropdown or type any address
+- **Address autocomplete** — type in To/Cc/Bcc, Tab accepts first match, Ctrl+K to trigger
+- **Auto-save** — drafts saved every 5 seconds
+
+### Managing Messages
+- **Delete** — Del, Ctrl+D, or trash button → moves to Trash
+- **Undo delete** — Ctrl+Z within 30 seconds
+- **Flag/unflag** — click the star ☆/★
+- **Search** — type in search bar. Qualifiers: `from:name`, `to:name`, `subject:text`
+- **Remote content** — blocked by default. Click "Load this time" or "Always from sender/domain"
+
+### View Options (View menu)
+- **Two-line view** — From+Date on line 1, Subject on line 2
+- **Preview pane** — toggle on/off
+- **Flagged only** — show only starred messages
+
+### Keyboard Shortcuts
+| Key | Action |
+|-----|--------|
+| Ctrl+N | New message |
+| Ctrl+R | Reply |
+| Ctrl+Shift+R | Reply All |
+| Del / Ctrl+D | Delete |
+| Ctrl+Z | Undo delete |
+| Ctrl+K | Address completion |
+| Ctrl+Enter | Send (compose) |
+| Escape | Discard / Clear search |
+| F5 | Sync |
+
+## Data Storage
+
+| File | Location | Purpose |
+|------|----------|---------|
+| config.json | ~/.mailx/ | Points to settings file |
+| settings.jsonc | OneDrive or ~/.mailx/ | Accounts, prefs (shared across machines) |
+| mailx.db | ~/.mailx/ | SQLite — headers, contacts, sync state |
+| mailxstore/ | ~/.mailx/ | Cached message bodies (.eml) |
+| window.json | ~/.mailx/ | Window position (per machine) |
+| mailx.log | project dir | Server log with timestamps |
+
+## Architecture
+
+- **Local-first** — changes update local DB immediately, background worker syncs to IMAP
+- **Offline reading** — full message bodies cached during sync
+- **IMAP IDLE** — instant new mail notifications + 30s poll fallback
+- **Outbox** — queued in IMAP Outbox folder with multi-machine interlock via flags
+- **Remote content blocking** — HTML sanitized server-side, CSP in iframe, per-sender/domain allow-list
+- **Search** — SQLite FTS5 full-text index with qualifiers

package/bin/mailx.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * mailx launcher — starts the server and opens the browser.
+ * Usage: mailx [--external] [--no-browser]
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import net from "node:net";
+
+const PORT = 9333;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverScript = path.join(__dirname, "..", "packages", "mailx-server", "index.js");
+
+function isPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(true));
+        server.once("listening", () => { server.close(); resolve(false); });
+        server.listen(port, "127.0.0.1");
+    });
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+    const noBrowser = args.includes("--no-browser");
+    const inUse = await isPortInUse(PORT);
+
+    if (inUse) {
+        console.log(`mailx server already running on port ${PORT}`);
+    } else {
+        console.log(`Starting mailx server on port ${PORT}...`);
+        const serverArgs = [serverScript, ...args.filter(a => a === "--external")];
+        const child = spawn(process.execPath, serverArgs, {
+            stdio: "inherit",
+            detached: false,
+        });
+        child.unref();
+
+        // Wait for server to be ready
+        for (let i = 0; i < 60; i++) {
+            await new Promise(r => setTimeout(r, 500));
+            if (await isPortInUse(PORT)) break;
+        }
+    }
+
+    if (!noBrowser) {
+        const url = `http://localhost:${PORT}`;
+        const { exec } = await import("node:child_process");
+        if (process.platform === "win32") exec(`start "" "${url}"`);
+        else if (process.platform === "darwin") exec(`open "${url}"`);
+        else exec(`xdg-open "${url}"`);
+        console.log(`Opened ${url}`);
+    }
+}
+
+main().catch(console.error);

package/client/app.js

@@ -0,0 +1,431 @@
+/**
+ * mailx client entry point.
+ * Wires together all UI components and WebSocket connection.
+ */
+import { initFolderTree, refreshFolderTree } from "./components/folder-tree.js";
+import { initMessageList, loadMessages, loadUnifiedInbox, loadSearchResults, reloadCurrentFolder } from "./components/message-list.js";
+import { showMessage, getCurrentMessage } from "./components/message-viewer.js";
+import { connectWebSocket, onWsEvent, triggerSync, getAccounts } from "./lib/api-client.js";
+// ── Wire up components ──
+const folderTree = document.getElementById("folder-tree");
+initFolderTree(folderTree, (accountId, folderId, folderName, specialUse) => {
+    loadMessages(accountId, folderId, 1, specialUse);
+    document.title = `mailx - ${folderName}`;
+}, () => {
+    // Unified inbox handler
+    loadUnifiedInbox();
+    document.title = "mailx - All Inboxes";
+});
+initMessageList((accountId, uid) => {
+    showMessage(accountId, uid);
+    // Enable action buttons when a message is selected
+    for (const id of ["btn-reply", "btn-reply-all", "btn-forward", "btn-delete", "btn-flag"]) {
+        const btn = document.getElementById(id);
+        if (btn)
+            btn.disabled = false;
+    }
+});
+// ── Toolbar actions ──
+document.getElementById("btn-sync")?.addEventListener("click", async () => {
+    const btn = document.getElementById("btn-sync");
+    btn.disabled = true;
+    btn.classList.add("syncing");
+    const statusSync = document.getElementById("status-sync");
+    if (statusSync)
+        statusSync.textContent = "Syncing...";
+    try {
+        await triggerSync();
+        // Button stays spinning — WebSocket syncProgress/folderCountsChanged will update UI
+        // Set a timeout to re-enable if no WebSocket response
+        setTimeout(() => {
+            btn.disabled = false;
+            btn.classList.remove("syncing");
+            refreshFolderTree();
+            reloadCurrentFolder();
+            if (statusSync && statusSync.textContent === "Syncing...") {
+                statusSync.textContent = `Synced ${new Date().toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit", hour12: false })}`;
+            }
+        }, 30000);
+    }
+    catch (e) {
+        if (statusSync)
+            statusSync.textContent = `Sync error: ${e.message}`;
+        btn.disabled = false;
+        btn.classList.remove("syncing");
+    }
+});
+document.getElementById("btn-restart")?.addEventListener("click", async () => {
+    const statusSync = document.getElementById("status-sync");
+    if (statusSync)
+        statusSync.textContent = "Restarting...";
+    try {
+        await fetch("/api/restart", { method: "POST" });
+    }
+    catch { /* server is shutting down */ }
+    // Server broadcasts reload event; if missed, WebSocket reconnect will trigger page reload
+});
+async function openCompose(mode) {
+    const current = getCurrentMessage();
+    const accounts = await getAccounts();
+    const accountId = current?.accountId || accounts[0]?.id || "";
+    const msg = current?.message;
+    const rePrefix = /^(re|fwd?):\s*/i;
+    const cleanSubject = msg ? msg.subject.replace(rePrefix, "") : "";
+    const init = {
+        mode,
+        accountId,
+        to: [],
+        cc: [],
+        subject: "",
+        bodyHtml: "",
+        inReplyTo: "",
+        references: [],
+        accounts: accounts.map((a) => ({ id: a.id, name: a.name, email: a.email })),
+    };
+    if (msg && mode === "reply") {
+        init.to = [msg.from];
+        init.subject = `Re: ${cleanSubject}`;
+        init.bodyHtml = quoteBody(msg);
+        init.inReplyTo = msg.messageId;
+        init.references = [...(msg.references || []), msg.messageId];
+    }
+    else if (msg && mode === "replyAll") {
+        init.to = [msg.from, ...msg.to.filter((a) => a.address !== msg.from.address)];
+        init.cc = msg.cc || [];
+        init.subject = `Re: ${cleanSubject}`;
+        init.bodyHtml = quoteBody(msg);
+        init.inReplyTo = msg.messageId;
+        init.references = [...(msg.references || []), msg.messageId];
+    }
+    else if (msg && mode === "forward") {
+        init.subject = `Fwd: ${cleanSubject}`;
+        init.bodyHtml = forwardBody(msg);
+    }
+    // Store init data for compose window to pick up
+    sessionStorage.setItem("composeInit", JSON.stringify(init));
+    window.open("/compose/compose.html", "_blank", "width=800,height=600,menubar=no,toolbar=no,status=no");
+}
+function quoteBody(msg) {
+    const date = new Date(msg.date).toLocaleString();
+    const from = msg.from.name ? `${msg.from.name} <${msg.from.address}>` : msg.from.address;
+    const body = msg.bodyHtml || `<pre>${msg.bodyText || ""}</pre>`;
+    return `<br><div class="reply"><p>On ${date}, ${from} wrote:</p><blockquote>${body}</blockquote></div>`;
+}
+function forwardBody(msg) {
+    const date = new Date(msg.date).toLocaleString();
+    const from = msg.from.name ? `${msg.from.name} &lt;${msg.from.address}&gt;` : msg.from.address;
+    const to = msg.to.map((a) => a.name ? `${a.name} &lt;${a.address}&gt;` : a.address).join(", ");
+    const body = msg.bodyHtml || `<pre>${msg.bodyText || ""}</pre>`;
+    return `<br><div class="reply"><p>---------- Forwarded message ----------<br>From: ${from}<br>Date: ${date}<br>Subject: ${msg.subject}<br>To: ${to}</p>${body}</div>`;
+}
+let lastDeleted = null;
+let undoTimeout = null;
+async function deleteCurrentMessage() {
+    const current = getCurrentMessage();
+    if (!current)
+        return;
+    const { accountId, message } = current;
+    try {
+        const res = await fetch(`/api/message/${accountId}/${message.uid}`, { method: "DELETE" });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || res.statusText);
+        }
+        lastDeleted = { accountId, uid: message.uid, folderId: message.folderId, subject: message.subject };
+        // Show undo notification in status bar
+        const statusSync = document.getElementById("status-sync");
+        if (statusSync)
+            statusSync.textContent = `Deleted "${message.subject.substring(0, 40)}" — Ctrl+Z to undo`;
+        // Clear undo after 30 seconds
+        if (undoTimeout)
+            clearTimeout(undoTimeout);
+        undoTimeout = setTimeout(() => {
+            lastDeleted = null;
+            if (statusSync?.textContent?.includes("Ctrl+Z"))
+                statusSync.textContent = "";
+        }, 30000);
+        // Clear the preview pane
+        const bodyEl = document.getElementById("mv-body");
+        const headerEl = document.getElementById("mv-header");
+        if (bodyEl)
+            bodyEl.innerHTML = `<div class="mv-empty">Select a message to read</div>`;
+        if (headerEl)
+            headerEl.hidden = true;
+        reloadCurrentFolder();
+    }
+    catch (e) {
+        console.error(`Delete failed: ${e.message}`);
+    }
+}
+async function undoDelete() {
+    if (!lastDeleted)
+        return;
+    const { accountId, uid, folderId } = lastDeleted;
+    try {
+        const res = await fetch(`/api/message/${accountId}/${uid}/undelete`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ folderId }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || res.statusText);
+        }
+        const statusSync = document.getElementById("status-sync");
+        if (statusSync)
+            statusSync.textContent = "Message restored";
+        lastDeleted = null;
+        if (undoTimeout)
+            clearTimeout(undoTimeout);
+        reloadCurrentFolder();
+    }
+    catch (e) {
+        console.error(`Undo failed: ${e.message}`);
+    }
+}
+document.getElementById("btn-delete")?.addEventListener("click", deleteCurrentMessage);
+document.getElementById("btn-compose")?.addEventListener("click", () => openCompose("new"));
+document.getElementById("btn-reply")?.addEventListener("click", () => openCompose("reply"));
+document.getElementById("btn-reply-all")?.addEventListener("click", () => openCompose("replyAll"));
+document.getElementById("btn-forward")?.addEventListener("click", () => openCompose("forward"));
+// ── Search ──
+let searchTimeout;
+const searchInput = document.getElementById("search-input");
+searchInput?.addEventListener("input", () => {
+    clearTimeout(searchTimeout);
+    searchTimeout = setTimeout(() => {
+        const query = searchInput.value.trim();
+        if (query.length >= 2) {
+            loadSearchResults(query);
+            document.title = `mailx - Search: ${query}`;
+        }
+        else if (query.length === 0) {
+            // Clear search — reload current folder
+            reloadCurrentFolder();
+        }
+    }, 400);
+});
+// Enter triggers immediate search
+searchInput?.addEventListener("keydown", (e) => {
+    if (e.key === "Enter") {
+        clearTimeout(searchTimeout);
+        const query = searchInput.value.trim();
+        if (query) {
+            loadSearchResults(query);
+            document.title = `mailx - Search: ${query}`;
+        }
+    }
+    if (e.key === "Escape") {
+        searchInput.value = "";
+        reloadCurrentFolder();
+    }
+});
+// ── Open links from email body in system browser ──
+window.addEventListener("message", (e) => {
+    if (e.data?.type === "openLink" && e.data.url) {
+        window.open(e.data.url, "_blank", "noopener,noreferrer");
+    }
+});
+// ── Splitter drag ──
+const splitter = document.getElementById("splitter-h");
+if (splitter) {
+    // Restore saved position
+    const saved = localStorage.getItem("mailx-split");
+    if (saved)
+        document.documentElement.style.setProperty("--list-viewer-split", saved);
+    let dragging = false;
+    let startX;
+    let startSplit;
+    splitter.addEventListener("pointerdown", (e) => {
+        dragging = true;
+        startX = e.clientX;
+        const mainArea = document.querySelector(".main-area");
+        startSplit = mainArea.getBoundingClientRect().width * (parseFloat(getComputedStyle(document.documentElement).getPropertyValue("--list-viewer-split")) / 100);
+        splitter.setPointerCapture(e.pointerId);
+    });
+    splitter.addEventListener("pointermove", (e) => {
+        if (!dragging)
+            return;
+        const mainArea = document.querySelector(".main-area");
+        const totalWidth = mainArea.getBoundingClientRect().width;
+        const newSplit = ((startSplit + (e.clientX - startX)) / totalWidth) * 100;
+        const clamped = Math.max(15, Math.min(85, newSplit));
+        const val = `${clamped}%`;
+        document.documentElement.style.setProperty("--list-viewer-split", val);
+        localStorage.setItem("mailx-split", val);
+    });
+    splitter.addEventListener("pointerup", () => { dragging = false; });
+}
+// ── WebSocket for live updates ──
+connectWebSocket();
+onWsEvent((event) => {
+    const statusSync = document.getElementById("status-sync");
+    switch (event.type) {
+        case "connected":
+            if (statusSync)
+                statusSync.textContent = "Connected";
+            // Refresh folder counts on reconnect (non-disruptive)
+            refreshFolderTree();
+            break;
+        case "syncProgress":
+            if (statusSync)
+                statusSync.textContent = `Sync: ${event.phase} ${event.progress}%`;
+            break;
+        case "folderCountsChanged": {
+            refreshFolderTree();
+            // Only reload message list if user isn't reading a message
+            if (!getCurrentMessage())
+                reloadCurrentFolder();
+            // Sync finished — re-enable sync button
+            const syncBtn = document.getElementById("btn-sync");
+            if (syncBtn) {
+                syncBtn.disabled = false;
+                syncBtn.classList.remove("syncing");
+            }
+            if (statusSync)
+                statusSync.textContent = `Synced ${new Date().toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit", hour12: false })}`;
+            break;
+        }
+        case "reload":
+            location.reload();
+            break;
+        case "error":
+            if (statusSync)
+                statusSync.textContent = `Error: ${event.message}`;
+            break;
+    }
+});
+// ── Keyboard shortcuts ──
+document.addEventListener("keydown", (e) => {
+    // Ctrl+N or Ctrl+Shift+M = Compose
+    if ((e.ctrlKey && e.key === "n") || (e.ctrlKey && e.shiftKey && e.key === "M")) {
+        e.preventDefault();
+        openCompose("new");
+    }
+    // Ctrl+R = Reply
+    if (e.ctrlKey && e.key === "r" && !e.shiftKey) {
+        e.preventDefault();
+        openCompose("reply");
+    }
+    // Ctrl+Shift+R = Reply All
+    if (e.ctrlKey && e.shiftKey && e.key === "R") {
+        e.preventDefault();
+        openCompose("replyAll");
+    }
+    // Ctrl+D or Delete = Delete message
+    if ((e.ctrlKey && e.key === "d") || e.key === "Delete") {
+        e.preventDefault();
+        deleteCurrentMessage();
+    }
+    // Ctrl+Z = Undo delete
+    if (e.ctrlKey && e.key === "z") {
+        if (lastDeleted) {
+            e.preventDefault();
+            undoDelete();
+        }
+    }
+    // F5 = Sync
+    if (e.key === "F5") {
+        e.preventDefault();
+        document.getElementById("btn-sync")?.click();
+    }
+});
+// ── View menu ──
+const viewBtn = document.getElementById("btn-view");
+const viewDropdown = document.getElementById("view-dropdown");
+const optTwoLine = document.getElementById("opt-two-line");
+const optPreview = document.getElementById("opt-preview");
+const optFlagged = document.getElementById("opt-flagged");
+// Toggle dropdown
+viewBtn?.addEventListener("click", (e) => {
+    e.stopPropagation();
+    if (viewDropdown)
+        viewDropdown.hidden = !viewDropdown.hidden;
+});
+document.addEventListener("click", () => {
+    if (viewDropdown)
+        viewDropdown.hidden = true;
+});
+// Restore saved view settings
+const savedTwoLine = localStorage.getItem("mailx-two-line") === "true";
+const savedPreview = localStorage.getItem("mailx-preview") !== "false"; // default true
+const savedFlagged = localStorage.getItem("mailx-flagged") === "true";
+if (optTwoLine)
+    optTwoLine.checked = savedTwoLine;
+if (optPreview)
+    optPreview.checked = savedPreview;
+if (optFlagged)
+    optFlagged.checked = savedFlagged;
+if (savedTwoLine)
+    document.getElementById("message-list")?.classList.add("two-line");
+if (!savedPreview)
+    document.querySelector(".main-area")?.classList.add("no-preview");
+if (savedFlagged)
+    document.getElementById("ml-body")?.classList.add("flagged-only");
+// Two-line toggle
+optTwoLine?.addEventListener("change", () => {
+    const list = document.getElementById("message-list");
+    if (optTwoLine.checked) {
+        list?.classList.add("two-line");
+    }
+    else {
+        list?.classList.remove("two-line");
+    }
+    localStorage.setItem("mailx-two-line", String(optTwoLine.checked));
+});
+// Preview pane toggle
+optPreview?.addEventListener("change", () => {
+    const main = document.querySelector(".main-area");
+    if (optPreview.checked) {
+        main?.classList.remove("no-preview");
+    }
+    else {
+        main?.classList.add("no-preview");
+    }
+    localStorage.setItem("mailx-preview", String(optPreview.checked));
+});
+// Flagged-only filter
+optFlagged?.addEventListener("change", () => {
+    const body = document.getElementById("ml-body");
+    if (optFlagged.checked) {
+        body?.classList.add("flagged-only");
+    }
+    else {
+        body?.classList.remove("flagged-only");
+    }
+    localStorage.setItem("mailx-flagged", String(optFlagged.checked));
+});
+const isApp = typeof mailxapi !== "undefined" && mailxapi?.isApp;
+fetch("/api/version").then(r => r.json()).then(d => {
+    const el = document.getElementById("app-version");
+    if (el)
+        el.textContent = `mailx s${d.server}/c${d.client}${isApp ? "" : " [browser]"}`;
+}).catch(async () => {
+    // Server not running — try to start it if we're in the app
+    if (isApp) {
+        await mailxapi.ensureServer();
+        location.reload();
+    }
+    else {
+        const el = document.getElementById("app-version");
+        if (el)
+            el.textContent = "mailx [server offline]";
+    }
+});
+// ── Sync pending indicator ──
+setInterval(async () => {
+    try {
+        const res = await fetch("/api/sync/pending");
+        if (!res.ok)
+            return;
+        const data = await res.json();
+        const el = document.getElementById("status-pending");
+        if (el) {
+            el.textContent = data.pending > 0 ? `↻ ${data.pending} pending` : "";
+            el.style.color = data.pending > 0 ? "oklch(0.75 0.15 60)" : "";
+        }
+    }
+    catch { /* offline */ }
+}, 5000);
+console.log("mailx client initialized");
+//# sourceMappingURL=app.js.map