@bobfrankston/mailx 1.0.37 → 1.0.39

package/README.md

@@ -35,47 +35,76 @@ Once OneDrive syncs, mailx picks up your accounts automatically.
 
 (On Windows `~` means `%USERPROFILE%`, e.g., `C:\Users\You\.mailx\settings.jsonc`)
 
+**Gmail -- minimal config (just your email):**
+```jsonc
+{
+  "accounts": [
+    { "email": "you@gmail.com" }
+  ]
+}
+```
+
+mailx auto-fills Gmail's IMAP/SMTP/OAuth settings. First run opens a browser for OAuth consent.
+
+**Standard IMAP -- just host and password:**
 ```jsonc
 {
   "accounts": [
     {
-      "id": "mymail",                 // Internal ID (no spaces, lowercase)
-      "name": "Your Name",            // Sender name in From: header
-      "label": "Work",                // Display label in UI (optional, defaults to name)
-      "email": "you@example.com",     // Your email address
+      "email": "you@example.com",
+      "password": "your-password",
+      "imap": { "host": "imap.example.com" },
+      "smtp": { "host": "smtp.example.com" }
+    }
+  ]
+}
+```
+
+Defaults: port 993/587, TLS on, auth password, username = email address. Only provide fields that differ from defaults.
+
+**Full config with all optional fields:**
+```jsonc
+{
+  "accounts": [
+    {
+      "id": "mymail",                 // Internal ID (default: domain name)
+      "name": "Your Name",            // From: header name (default: local part of email)
+      "label": "Work",                // UI display label (default: name)
+      "email": "you@example.com",
       "imap": {
-        "host": "imap.example.com",   // IMAP server
-        "port": 993,                  // Usually 993 for SSL/TLS
-        "tls": true,
-        "auth": "password",           // "password" or "oauth2" (Gmail)
-        "user": "you@example.com",    // IMAP username
-        "password": "your-password"   // IMAP password (not needed for oauth2)
+        "host": "imap.example.com",   // Default: imap.{domain}
+        "port": 993,                  // Default: 993
+        "tls": true,                  // Default: true
+        "auth": "password",           // Default: "password" (or "oauth2" for Gmail/Outlook)
+        "user": "you@example.com",    // Default: email address
+        "password": "your-password"
       },
       "smtp": {
-        "host": "smtp.example.com",   // SMTP server
-        "port": 587,                  // Usually 587 for STARTTLS
-        "tls": true,
+        "host": "smtp.example.com",   // Default: smtp.{domain}
+        "port": 587,                  // Default: 587
+        "tls": true,                  // Default: true
         "auth": "password",
         "user": "you@example.com",
         "password": "your-password"
       },
-      "enabled": true,
-      "defaultSend": true,            // Use this account for sending when From doesn't match
-      "relayDomains": [],             // Domains to skip in Delivered-To (optional)
-      "deliveredToPrefix": []         // Prefixes to strip from Delivered-To alias (optional)
+      "enabled": true,                // Default: true
+      "defaultSend": true,            // Use this account when From doesn't match
+      "relayDomains": [],             // Domains to skip in Delivered-To chain
+      "deliveredToPrefix": []         // Prefixes to strip from Delivered-To alias
     }
   ],
   "sync": {
-    "intervalMinutes": 5,             // Full sync interval (minutes)
-    "historyDays": 0                  // Days of history to sync (0 = all)
+    "intervalMinutes": 5,             // Default: 5
+    "historyDays": 0                  // Default: 30 (0 = all)
   },
   "ui": {
-    "theme": "system",                // "system", "dark", or "light"
-    "fontSize": 15
+    "theme": "system"                 // "system" (default), "dark", or "light"
   }
 }
 ```
 
+**Known providers with automatic defaults:** Gmail, Google, Outlook, Hotmail, Yahoo, iCloud. For these, only `email` is required.
+
 No `config.jsonc` needed -- when it doesn't exist, mailx reads settings directly from `~/.mailx/`.
 
 **Step 2.** Run `mailx` and open `http://127.0.0.1:9333` in your browser.
@@ -112,28 +141,15 @@ move "%USERPROFILE%\.mailx\settings.jsonc" "%OneDrive%\home\.mailx\settings.json
 - `historyDays` in `config.jsonc` overrides the shared default per machine
 - On new machines, if `config.jsonc` doesn't exist, mailx auto-detects OneDrive at `%OneDrive%/home/.mailx/`
 
-### Adding a Gmail account
+### Gmail OAuth setup
 
-Gmail requires OAuth2 instead of a password:
+Gmail accounts auto-configure -- just add `{ "email": "you@gmail.com" }` to accounts. But OAuth requires a one-time Google Cloud setup:
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a project
 2. Enable the **Gmail API** (and **People API** for contacts)
 3. Create **OAuth 2.0 credentials** (Desktop app type)
 4. Download `credentials.json` to the iflow package directory
-5. Add the Gmail account to `settings.jsonc` with `"auth": "oauth2"`
-6. First connection opens a browser for OAuth consent. Tokens are cached and refresh automatically.
-
-```jsonc
-{
-  "id": "gmail",
-  "name": "Your Name",
-  "label": "Gmail",
-  "email": "you@gmail.com",
-  "imap": { "host": "imap.gmail.com", "port": 993, "tls": true, "auth": "oauth2", "user": "you@gmail.com" },
-  "smtp": { "host": "smtp.gmail.com", "port": 587, "tls": true, "auth": "oauth2", "user": "you@gmail.com" },
-  "enabled": true
-}
-```
+5. First connection opens a browser for OAuth consent. Tokens are cached and refresh automatically.
 
 ## Usage
 

package/bin/mailx.js

@@ -172,16 +172,34 @@ async function main() {
 
         let launcherPath = launcherPaths.find(p => fs.existsSync(p));
 
+        // On Linux, skip native launcher if no display server available
+        if (launcherPath && process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+            log("No display server (DISPLAY/WAYLAND_DISPLAY not set) — skipping native launcher");
+            launcherPath = undefined;
+        }
+
         if (launcherPath) {
             console.log("Starting mailx...");
             log(`Launching: ${launcherPath}`);
             const { spawn } = await import("node:child_process");
-            const child = spawn(launcherPath, args, { detached: true, stdio: "ignore" });
-            child.unref();
-            console.log("mailx launched");
+            try {
+                const child = spawn(launcherPath, args, { detached: true, stdio: "ignore" });
+                child.on("error", () => {
+                    console.log("Native launcher failed, starting in browser mode...");
+                    process.argv.push("--server");
+                    main();
+                });
+                child.unref();
+                console.log("mailx launched");
+            } catch (e) {
+                console.log(`Native launcher failed: ${e.message}`);
+                console.log("Starting in browser mode...");
+                process.argv.push("--server");
+                await main();
+            }
         } else {
-            console.log("Native launcher not found, starting in browser mode...");
-            log("Falling back to --server mode");
+            console.log("Starting in browser mode...");
+            log("No native launcher — falling back to --server mode");
             process.argv.push("--server");
             await main(); // recurse with --server
         }

package/client/components/folder-tree.js

@@ -317,7 +317,33 @@ async function loadFolderTree(container) {
     try {
         const accounts = await getAccounts();
         if (accounts.length === 0) {
-            container.innerHTML = `<div class="folder-loading">No accounts configured.<br>Edit ~/.mailx/settings.jsonc</div>`;
+            container.innerHTML = `<div class="folder-loading" style="padding:1rem;line-height:1.8">
+                <strong>No accounts configured</strong><br>
+                Create <code>~/.mailx/settings.jsonc</code> with your email accounts.<br><br>
+                Minimal Gmail example:<br>
+                <code style="display:block;padding:0.5rem;background:var(--color-bg);border-radius:4px;margin:0.5rem 0;white-space:pre">{ "name": "Your Name",
+  "accounts": [
+    { "email": "you@gmail.com" }
+  ]
+}</code>
+                Standard IMAP:<br>
+                <code style="display:block;padding:0.5rem;background:var(--color-bg);border-radius:4px;margin:0.5rem 0;white-space:pre">{ "name": "Your Name",
+  "accounts": [
+    { "email": "you@example.com",
+      "password": "secret",
+      "imap": { "host": "imap.example.com" },
+      "smtp": { "host": "smtp.example.com" }
+    }
+  ]
+}</code>
+                <a href="https://github.com/BobFrankston/mailx#first-time-setup" target="_blank" style="color:var(--color-accent)">Full setup guide</a>
+            </div>`;
+            // Dismiss startup overlay
+            const overlay = document.getElementById("startup-overlay");
+            if (overlay) {
+                overlay.classList.add("hidden");
+                setTimeout(() => overlay.remove(), 400);
+            }
             return;
         }
         // Clear loading state now that we have data

package/client/lib/api-client.js

@@ -30,7 +30,7 @@ async function api(path, options) {
         // Network error — server is down
         if (e.name === "AbortError")
             throw e;
-        throw new Error("Server offline — restart with launch.ps1");
+        throw new Error("Server offline — run: mailx -server");
     }
     if (!res.ok) {
         const err = await res.json().catch(() => ({ error: res.statusText }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -20,7 +20,7 @@
     "postinstall": "node launcher/builder/postinstall.js"
   },
   "dependencies": {
-    "@bobfrankston/iflow": "^1.0.8",
+    "@bobfrankston/iflow": "^1.0.10",
     "@bobfrankston/miscinfo": "^1.0.6",
     "@bobfrankston/oauthsupport": "^1.0.11",
     "@bobfrankston/rust-builder": "^0.1.2",

package/packages/mailx-server/index.js

@@ -41,10 +41,10 @@ console.error = (...args) => {
     origErr(msg);
     logStream.write(msg + "\n");
 };
-const serverPkg = JSON.parse(fs.readFileSync(path.join(import.meta.dirname, "package.json"), "utf-8"));
-const clientPkg = JSON.parse(fs.readFileSync(path.join(import.meta.dirname, "..", "..", "client", "package.json"), "utf-8"));
-const SERVER_VERSION = serverPkg.version;
-const CLIENT_VERSION = clientPkg.version;
+// Read version from root package.json (the published version)
+const rootPkg = JSON.parse(fs.readFileSync(path.join(import.meta.dirname, "..", "..", "package.json"), "utf-8"));
+const SERVER_VERSION = rootPkg.version;
+const CLIENT_VERSION = rootPkg.version;
 // ── Initialize ──
 initLocalConfig();
 const settings = loadSettings();

package/packages/mailx-settings/index.js

@@ -23,6 +23,22 @@ const LOCAL_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".",
 const LOCAL_CONFIG_PATH = path.join(LOCAL_DIR, "config.jsonc");
 const LEGACY_CONFIG_PATH = path.join(LOCAL_DIR, "config.json");
 const DEFAULT_STORE_PATH = path.join(LOCAL_DIR, "mailxstore");
+/** Resolve a path from config — relative to ~/.mailx/, ~ expands to home */
+function resolvePath(p) {
+    if (!p)
+        return p;
+    const home = process.env.USERPROFILE || process.env.HOME || ".";
+    // Expand ~ to home directory
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return path.join(home, p.slice(2));
+    if (p === "~")
+        return home;
+    // Absolute path — use as-is
+    if (path.isAbsolute(p))
+        return p;
+    // Relative — resolve from config directory (~/.mailx/)
+    return path.resolve(LOCAL_DIR, p);
+}
 function readLocalConfig() {
     // Migrate config.json → config.jsonc
     if (!fs.existsSync(LOCAL_CONFIG_PATH) && fs.existsSync(LEGACY_CONFIG_PATH)) {
@@ -35,10 +51,10 @@ function readLocalConfig() {
 function getSharedDir() {
     const config = readLocalConfig();
     if (config.sharedDir)
-        return config.sharedDir;
+        return resolvePath(config.sharedDir);
     // Legacy: derive from settingsPath
     if (config.settingsPath)
-        return path.dirname(config.settingsPath);
+        return path.dirname(resolvePath(config.settingsPath));
     return LOCAL_DIR;
 }
 // ── File helpers ──
@@ -105,6 +121,65 @@ function saveFile(filename, data) {
         catch { /* ignore */ }
     }
 }
+const PROVIDERS = {
+    "gmail.com": {
+        imap: { host: "imap.gmail.com", port: 993, tls: true, auth: "oauth2" },
+        smtp: { host: "smtp.gmail.com", port: 587, tls: true, auth: "oauth2" },
+    },
+    "googlemail.com": {
+        imap: { host: "imap.gmail.com", port: 993, tls: true, auth: "oauth2" },
+        smtp: { host: "smtp.gmail.com", port: 587, tls: true, auth: "oauth2" },
+    },
+    "outlook.com": {
+        imap: { host: "outlook.office365.com", port: 993, tls: true, auth: "oauth2" },
+        smtp: { host: "smtp.office365.com", port: 587, tls: true, auth: "oauth2" },
+    },
+    "hotmail.com": {
+        imap: { host: "outlook.office365.com", port: 993, tls: true, auth: "oauth2" },
+        smtp: { host: "smtp.office365.com", port: 587, tls: true, auth: "oauth2" },
+    },
+    "yahoo.com": {
+        imap: { host: "imap.mail.yahoo.com", port: 993, tls: true, auth: "password" },
+        smtp: { host: "smtp.mail.yahoo.com", port: 587, tls: true, auth: "password" },
+    },
+    "icloud.com": {
+        imap: { host: "imap.mail.me.com", port: 993, tls: true, auth: "password" },
+        smtp: { host: "smtp.mail.me.com", port: 587, tls: true, auth: "password" },
+    },
+};
+/** Fill in provider defaults for an account based on email domain */
+function normalizeAccount(acct, globalName) {
+    const email = acct.email || "";
+    const domain = email.split("@")[1]?.toLowerCase() || "";
+    const provider = PROVIDERS[domain];
+    const user = acct.imap?.user || acct.user || email;
+    return {
+        id: acct.id || domain.split(".")[0] || "account",
+        name: acct.name || globalName || email.split("@")[0],
+        label: acct.label,
+        email,
+        imap: {
+            host: acct.imap?.host || provider?.imap.host || `imap.${domain}`,
+            port: acct.imap?.port || provider?.imap.port || 993,
+            tls: acct.imap?.tls ?? provider?.imap.tls ?? true,
+            auth: acct.imap?.auth || provider?.imap.auth || "password",
+            user: acct.imap?.user || user,
+            password: acct.imap?.password || acct.password,
+        },
+        smtp: {
+            host: acct.smtp?.host || provider?.smtp.host || `smtp.${domain}`,
+            port: acct.smtp?.port || provider?.smtp.port || 587,
+            tls: acct.smtp?.tls ?? provider?.smtp.tls ?? true,
+            auth: acct.smtp?.auth || provider?.smtp.auth || "password",
+            user: acct.smtp?.user || user,
+            password: acct.smtp?.password || acct.password,
+        },
+        enabled: acct.enabled ?? true,
+        defaultSend: acct.defaultSend,
+        relayDomains: acct.relayDomains,
+        deliveredToPrefix: acct.deliveredToPrefix,
+    };
+}
 // ── Defaults ──
 const DEFAULT_ACCOUNTS = [];
 const DEFAULT_PREFERENCES = {
@@ -143,12 +218,14 @@ export function loadAccounts() {
             }
             catch { /* ignore */ }
         }
-        return accounts.accounts || accounts;
+        const raw = accounts.accounts || accounts;
+        const globalName = accounts.name || "";
+        return raw.map((a) => normalizeAccount(a, globalName));
     }
     // Legacy: read from settings.jsonc
     const legacy = loadLegacySettings();
     if (legacy?.accounts)
-        return legacy.accounts;
+        return legacy.accounts.map((a) => normalizeAccount(a, legacy.name));
     return DEFAULT_ACCOUNTS;
 }
 /** Save account configs */
@@ -215,7 +292,7 @@ export function saveSettings(settings) {
 /** Get the local store base path */
 export function getStorePath() {
     const config = readLocalConfig();
-    return config.storePath || DEFAULT_STORE_PATH;
+    return config.storePath ? resolvePath(config.storePath) : DEFAULT_STORE_PATH;
 }
 /** Get the local data directory (DB, store, etc.) */
 export function getConfigDir() {