@bobfrankston/rmfmail 1.2.49 → 1.2.65

package/docs/config-help.md

@@ -0,0 +1,131 @@
+# Config files
+
+Help text shown in-app next to each JSONC config file in the **Settings → Edit config files...** dialog. Each `##` section is matched by filename.
+
+Comments (`//`, `/* */`) and trailing commas are allowed — mailx parses these files with a JSONC parser.
+
+## accounts.jsonc
+
+Defines the mail accounts mailx syncs. Stored on Google Drive so it's shared across all your devices.
+
+```jsonc
+{
+  "accounts": [
+    {
+      "id": "gmail",                    // short, unique, lowercase — used as folder name on disk
+      "name": "Bob",                    // display name used as the From: name
+      "email": "bob@gmail.com",         // primary address for this account
+      "defaultSend": true,              // pre-select this account in compose
+      "identityDomains": ["bob.ma"],    // extra domains to recognize as "you" for reply-from detection
+      "sig": {                          // signature appended to NEW messages
+        "text": "Bob Frankston\nhttps://frankston.com"
+      }
+    },
+    {
+      "id": "work",
+      "name": "Bob",
+      "email": "bob@example.com",
+      "imap": {                         // explicit IMAP/SMTP for non-auto-detected providers
+        "host": "imap.example.com",
+        "port": 993,
+        "tls": true
+      },
+      "smtp": {
+        "host": "smtp.example.com",
+        "port": 465,
+        "tls": true
+      },
+      "spam": "Junk"                    // override the spam folder name for this account
+    }
+  ]
+}
+```
+
+**Fields:**
+
+- `id` — unique, lowercase, no spaces. Changing it renames the local cache folder.
+- `name` — display name used in the From: header.
+- `email` — primary identity address.
+- `defaultSend` — if multiple accounts, the one with `defaultSend: true` is pre-selected in compose.
+- `identityDomains` — additional domains to recognize as yours (aliases, plus-addressing, forwarded domains). Used for reply auto-From detection.
+- `imap` / `smtp` — server config. Omit for Gmail/Outlook/Yahoo/iCloud (auto-detected from the email domain).
+- `spam` — override the spam/junk folder name if auto-detection picks the wrong one.
+- `sig` — signature object. `text` is appended to NEW messages with the standard `-- ` separator (newlines preserved). Only applied to brand-new messages today; replies/forwards skip it. Future options will cover replies, per-account toggles, and a `"html": true` flag for raw HTML signatures.
+
+Gmail accounts automatically use the Gmail REST API (no IMAP). Everything else uses IMAP via iflow-direct.
+
+Restart mailx after editing to pick up changes.
+
+## allowlist.jsonc
+
+Controls which remote images/content are allowed in the message viewer without the "Show images" banner.
+
+```jsonc
+{
+  "domains": [
+    "github.com",                       // wildcard subdomains implied
+    "stripe.com",
+    "list-manage.com"                   // Mailchimp tracking — remove if you want to block
+  ],
+  "senders": [
+    "notifications@github.com",         // full address match
+    "*@anthropic.com"                   // wildcard: anything from this domain
+  ]
+}
+```
+
+**Fields:**
+
+- `domains` — remote images are fetched if their host matches (with subdomain wildcarding).
+- `senders` — messages from these senders get images auto-loaded regardless of image host.
+
+Content-Security-Policy still blocks scripts regardless — this only affects image/CSS loading.
+
+## clients.jsonc
+
+Per-device registrations. Each mailx install writes its hostname here so you can see which devices have synced recently.
+
+```jsonc
+{
+  "clients": [
+    {
+      "id": "desktop-abc123",           // auto-generated on first run
+      "hostname": "MYPC",
+      "platform": "win32",
+      "lastSeen": "2026-04-18T14:00:00Z"
+    }
+  ]
+}
+```
+
+Normally there's no reason to edit this by hand. Useful for removing stale device entries, or migrating a device to a new ID.
+
+## config.jsonc
+
+**Local per-machine configuration**, stored at `~/.mailx/config.jsonc`. This file is NOT synced to the cloud — it's how each machine knows where the shared config lives and which store path to use.
+
+```jsonc
+{
+  "sharedDir": {
+    "provider": "gdrive",               // cloud provider (only "gdrive" supported)
+    "path": "mailx",                    // folder name on Google Drive
+    "folderId": "1ABC...xyz"            // GDrive folder ID (API-resolved, don't edit)
+  },
+  "storePath": "C:/Users/Bob/.mailx/store",  // where .eml message bodies live locally
+
+  "accountOverrides": {                 // optional: per-machine overrides to accounts.jsonc
+    "work": {
+      "imap": { "host": "127.0.0.1", "port": 1143 }  // e.g., tunnel on this machine only
+    }
+  }
+}
+```
+
+**Fields:**
+
+- `sharedDir.provider` — cloud storage. Currently only `gdrive`.
+- `sharedDir.path` / `folderId` — the folder on the cloud where shared config + cache metadata live.
+- `storePath` — where `.eml` bodies are cached locally. Changing requires moving existing files.
+- `accountOverrides` — override parts of an account's config on this machine only (different IMAP host when behind a VPN, for example). Keys match the `id` in accounts.jsonc.
+
+Delete and re-run `mailx -setup` to reconfigure from scratch.

package/docs/edit-in-word-docx.md

@@ -0,0 +1,98 @@
+# Edit-in-Word .docx round-trip — design
+
+> Replaces the current .html round-trip so saving in Word "just works" without
+> Save-As-Web-Page gymnastics. Adds a focus-back hint on save so the user
+> doesn't have to Alt-Tab manually.
+
+## Why
+
+Today, Edit-in-Word writes `<editId>.html` and watches it. Word opens it but
+when the user hits Ctrl+S, Word's default save format is **.docx**, not .html.
+Word writes a *new* `<editId>.docx` file; the watcher misses the save; the
+user's edits never reload into rmfmail.
+
+Two options previously discussed (B watch-both-extensions; C inline hint).
+Picking **A** here: pre-convert to .docx so Word's natural save flow lands in
+the file we're watching.
+
+## Pieces
+
+1. **HTML → DOCX** at edit-start. Library: `html-to-docx` (Node, ~80KB,
+   actively maintained). Output is a Node `Buffer`. Write to
+   `~/.rmfmail/external-edit/<editId>.docx`.
+2. **Watch `<editId>.docx`** instead of `.html`. Same `fs.watch(dir)` mechanic;
+   filter by `<editId>.docx` rather than `<editId>.html`.
+3. **DOCX → HTML** on save. Library: `mammoth` (Node, ~250KB, the de facto
+   DOCX-to-HTML converter). Output is HTML string. Strip its outer wrapper.
+   Emit `wordEditUpdated` as today.
+4. **Focus rmfmail on save**. After parsing the docx, post a host-level
+   "focus this window" message via msger. On Windows that's
+   `SetForegroundWindow` on the WebView2 hwnd — msger already has the hwnd
+   from window create. Add a `focusWindow` IPC method.
+5. **In-compose external-edit indicator**. While `wordEditId` is set, the
+   compose body editor area shows a non-editable status panel:
+
+   ```
+   ╭───────────────────────────────────────╮
+   │ Editing in Word…                       │
+   │ Save in Word → reloads here.           │
+   │                                        │
+   │  [ Reload now ]  [ Send ]  [ Discard ] │
+   ╰───────────────────────────────────────╯
+   ```
+
+   - **Reload now**: read the .docx and parse manually (in case the watcher
+     missed an event)
+   - **Send**: parse current .docx, set as body, fire send (skips the
+     intermediate "switch back to compose, click Send" step)
+   - **Discard**: stop the watcher, delete the temp file, restore original body
+
+## Library deps
+
+| Library | Direction | Size | Notes |
+|---|---|---|---|
+| `html-to-docx` | HTML → DOCX | ~80KB | Pure JS Node. `await asBlob(html)` returns a Buffer. |
+| `mammoth` | DOCX → HTML | ~250KB | De facto standard. Lossy on some Word features (text effects, complex tables) but covers email-shaped content. |
+
+Total ~330KB added to mailx-service. Acceptable; only loaded on Edit-in-Word
+click via dynamic `import()` so cold start cost is zero.
+
+## What we lose
+
+- Round-trip fidelity isn't perfect. Word's docx supports things mammoth
+  doesn't (footnotes, comments, advanced styling). For email composition this
+  is fine — users aren't writing footnotes — but worth knowing.
+- Rich images: html-to-docx handles inline images (data: URIs) reasonably;
+  mammoth round-trips them as `<img src="data:...">`. Should work but needs
+  testing.
+
+## Migration
+
+- Existing watchers at `<editId>.html` keep working until the user reopens an
+  Edit-in-Word session. New session uses .docx.
+- Optionally clean up old `external-edit/*.html` files at startup.
+
+## Implementation order
+
+1. `npm install html-to-docx mammoth` in mailx-service.
+2. Replace `.html` write at `mailx-service/index.ts:660` with .docx via
+   html-to-docx.
+3. Replace watcher target at line 745 with `<editId>.docx`.
+4. Replace read+parse at line 755 with mammoth → HTML.
+5. Add `focusWindow` IPC + msger hook.
+6. Wire in-compose external-edit indicator panel (compose.ts).
+7. Test with a Word install on Windows.
+8. Skip Word path on Mac (Mac Word's docx behavior is the same; should work
+   without changes — but verify).
+
+## Open questions
+
+- Does Mac Word treat .docx the same as Windows Word? (Should — same file
+  format. Verify after impl.)
+- LibreOffice fallback: opens .docx natively, saves to same .docx by default.
+  No special handling needed.
+- Default editor on Linux is usually LibreOffice; Word path n/a.
+
+## Status
+
+Design captured; implementation deferred until user confirms scope.

package/docs/host-abstraction-plan.md

@@ -0,0 +1,169 @@
+# mailx Host Abstraction + msgview Parity Plan
+
+**Status:** step 1 (abstraction package) implemented 2026-04-20. msgview adapter (step 2+) deferred until a Mac client or arm64-without-webkit fallback is actually needed. Resume cold from this doc.
+
+## Why this exists
+
+1. **msger covers most of what we need.** Windows + mainstream x86_64 Linux run msger fine today. The Rust/wry binary links against `libwebkit2gtk-4.1.so.0`; on Debian trixie / Raspberry Pi OS arm64 you install it once (`sudo apt install libwebkit2gtk-4.1-0`) and msger works. Not a regression, just a missing system dep. Older distros with only webkit2gtk 4.0 would need an msger rebuild.
+2. **msgview fills specific gaps.** Electron's bundled Chromium is the natural path for Mac (where msger would need separate webkit work) and a fallback for niche Linux systems where webkit2gtk-4.1 isn't available and can't be installed. It also sidesteps two msger pain points — multi-monitor drag bugs and WebView2 Evergreen auto-update on Windows — but those aren't load-bearing reasons to move existing Windows/Linux users off msger.
+3. **We want mailx to run on both without the call sites caring.** mailx imports a host abstraction; the abstraction picks msger or msgview at runtime. Step 1 (done 2026-04-20) puts the seam in place even before msgview lands, so future platform work is an adapter drop-in instead of a call-site rewrite.
+4. **msger and msgview must stay app-agnostic.** Architectural rule from mailx/CLAUDE.md: *"msger MUST have ZERO knowledge of mailx, iflow, or any application code."* Same rule extends to msgview. Any mailx-specific glue living in the wrappers today must move to mailx. The 2026-04-20 `_msgapi*` service-callback rename in msger Rust was the prerequisite that made both hosts share one generic JS contract.
+
+## Current coupling (survey)
+
+Searched msger + msgview for `mailx` references:
+
+- **msger/shower.ts:125** — doc comment on `setAppName()` says `e.g. setAppName("mailx")`. That's a doc reference only; `setAppName` itself is generic (app passes its own name for per-user bin dir + AUMID). OK to leave, or reword the example to `"myapp"`.
+- **msger/msger-plan.md:70** — explicit rule `"mailxapi.js content (belongs in mailx)"`. Already correct.
+- **msger Rust src** — no mailx/iflow/oauth references. Clean.
+- **msgview** — no mailx references. Pristine.
+
+**Conclusion:** the wrappers are already app-agnostic in code. The factoring work is on the mailx side: today mailx calls `showMessageBox`/`showService` directly from `@bobfrankston/msger`. We introduce a host abstraction so the import swap is one line, and document the contract so the next app (msga, etc.) can use the same interface.
+
+## Current mailx → msger surface
+
+From `bin/mailx.ts:825-900` and `client/lib/mailxapi.js`:
+
+```ts
+import { showMessageBox, showService, setAppName } from "@bobfrankston/msger";
+
+// Desktop launch:
+const handle = showService({
+    title, url, contentDir, initScript, icon, aumid,
+    size: { width, height }, pos: { x, y },
+    escapeCloses: false,
+});
+
+handle.onRequest(async (req) => { /* dispatch req._action → MailxService */ });
+handle.send({ _cbid, result });   // responses and push events
+// handle.close(); handle.result (promise resolving on window close)
+```
+
+**In-WebView side** (`client/lib/mailxapi.js` injected via `initScript`):
+- Exposes `window.callNode(action, args) → Promise<result>` built on `window.msgapi.sendToHost(...)`
+- Receives server-push events via the IPC channel
+- `api-client.ts` auto-detects IPC vs HTTP and routes through `callNode` when IPC is present
+
+**That's the entire surface.** Small and stable.
+
+## The `MailxHost` interface
+
+One interface, two implementations. Lives in mailx (not in msger/msgview).
+
+```ts
+// packages/mailx-host/index.ts
+export interface MailxHostOptions {
+    title: string;
+    url: string;                 // relative to contentDir (e.g. "index.html")
+    contentDir: string;          // served via custom protocol
+    initScript: string;          // mailxapi.js contents, injected pre-page
+    icon?: string;
+    aumid?: string;              // Windows taskbar identity
+    size?: { width: number; height: number };
+    pos?: { x: number; y: number };
+    escapeCloses?: boolean;
+}
+
+export interface MailxHostHandle {
+    onRequest(fn: (req: any) => void | Promise<void>): void;
+    send(msg: any): void;        // push to WebView
+    close(): void;
+    result: Promise<{ closed: boolean }>;
+}
+
+export interface MailxHost {
+    setAppName(name: string): void;
+    showService(opts: MailxHostOptions): MailxHostHandle;
+}
+```
+
+Two impls:
+
+- **`packages/mailx-host-msger/index.ts`** — wraps `@bobfrankston/msger`, delegates 1:1. ~30 LOC.
+- **`packages/mailx-host-msgview/index.ts`** — wraps Electron. Creates `BrowserWindow`, installs `protocol.handle()` for `contentDir`, sets `webPreferences.preload` pointing at a shim that loads the `initScript` string and exposes the same `window.msgapi` / `window.callNode` surface, wires `ipcMain.handle` ↔ `handle.onRequest` / `webContents.send` ↔ `handle.send`. ~150 LOC including the preload shim.
+
+Selection at runtime in `bin/mailx.ts`: env var `MAILX_HOST=msger|msgview` (default msger on Windows, msgview on Linux/Mac), or `--host=` flag.
+
+## msgview parity checklist (from msgx/parity.md)
+
+Mapping each msger capability to Electron:
+
+| msger feature | Electron equivalent | Work needed |
+|---|---|---|
+| Service mode (bidir IPC via stdin/stdout) | `ipcMain.handle` / `webContents.send` | Wire in host shim. Electron's IPC is in-process, strictly better than JSON-line stdio. |
+| `initScript` injection | `webPreferences.preload` | Preload shim evaluates the injected script string in page context before load. |
+| `msger.localhost` custom protocol | `protocol.handle()` (Electron 25+) | Register in host shim on `app.whenReady()`. |
+| `window.msgapi` (TCP/UDP/HTTP, UI control) | Expose via preload + `contextBridge` | Re-implement the subset mailx uses — TCP for iflow transport, UI control (resize, minimize, etc.). Node APIs available in main process, expose narrow surface. |
+| AUMID for taskbar pin | `app.setAppUserModelId(aumid)` | One line. |
+| Navigation gating (same-origin stays, cross-origin external) | `webContents.setWindowOpenHandler` + `will-navigate` | Reuse msger's `url_origin()` logic. |
+| Multi-monitor drag | Chromium native | Disappears for free — msger's `ScaleFactorChanged` bug doesn't exist here. |
+| WebView2 Evergreen auto-update killing windows | N/A | Chromium bundled, doesn't apply. |
+| Stable exe path / timestamped-copy dance | N/A | Electron installer handles this differently (Squirrel/NSIS); no hardlink trick needed. |
+| EPERM cleanup on npm upgrade | N/A | Different install mechanism. |
+| **Detach mode** (child outlives caller) | Harder | See below. |
+| Log path option | Electron `app.setPath("logs", ...)` | Trivial. |
+
+### Detach mode — the one real design decision
+
+msger's detach mode lets the mailx launcher exit while the window keeps running in a forked msger process. Electron doesn't have a natural equivalent — Electron apps are one process tree rooted at the Electron main process.
+
+**Option A: launch Electron as a separate binary.** Install `msgview` as a CLI (`msgview --url=… --content-dir=… --init-script=…`), mailx's host-msgview shim spawns it detached. Closest analog to msger's current model. Downside: two processes (mailx service + Electron), and the service must manage IPC over stdio again.
+
+**Option B: run mailx service INSIDE the Electron main process.** mailx becomes an Electron app. `bin/mailx.ts` bootstraps Electron, creates `MailxService` + `ImapManager` in the main process, opens `BrowserWindow` with preload. Single process, IPC is in-process calls. No detach needed — the window IS the service. This is cleaner and matches how msgview is already structured for its own use case.
+
+**Recommendation: Option B.** Requires `bin/mailx.ts` to detect host mode and, when msgview is selected, re-exec under Electron (or use Electron as the node runtime from the start). The `mailx` CLI entry still works — it just launches Electron instead of plain node. For `--server` mode we keep plain node (no window needed, so no Electron).
+
+## Factoring plan — keep msger/msgview independent of mailx
+
+Where mailx-specific code lives today and where it needs to end up:
+
+| Code | Today | Target |
+|---|---|---|
+| `client/lib/mailxapi.js` | mailx | mailx (unchanged — already correct) |
+| `packages/mailx-service/jsonrpc.ts` | mailx | mailx (unchanged) |
+| `bin/mailx.ts` direct `import "@bobfrankston/msger"` | mailx | Replace with `import { getHost } from "@mailx/host"` |
+| `showService` options shape (title, url, initScript, aumid, etc.) | msger-specific type | Move to `packages/mailx-host/` — msger stays generic, mailx owns the mailx-flavored option shape |
+| `setAppName("mailx")` | called from mailx | Still called from mailx, but through the host abstraction |
+| `window.msgapi` surface | msger defines it | Keep as msger's native API. `mailx-host-msgview` re-implements the same shape via Electron preload so mailx code in the WebView doesn't care which host it's under. |
+| Per-user bin dir `%LOCALAPPDATA%\mailx\bin\` | msger's `getUserBinDir(_appName)` | Unchanged — `setAppName("mailx")` already drives this generically |
+
+**Net effect:** msger and msgview keep zero mailx references. mailx gains three small packages (`mailx-host`, `mailx-host-msger`, `mailx-host-msgview`) that encapsulate the coupling. Next app (msga, etc.) can either copy the `mailx-host-*` pattern or use msger/msgview directly.
+
+### The `window.msgapi` question
+
+mailx code running in the WebView currently calls `window.msgapi.sendToHost(...)`. That's a msger-defined global. Two paths:
+
+- **Keep the name.** `mailx-host-msgview`'s preload exposes `window.msgapi` with the same shape. mailx WebView code is unchanged. msger owns the de-facto standard; msgview implements it.
+- **Rename to `window.mailxHost`.** mailx owns the name; msger and msgview each expose it via their respective injection mechanisms. Cleaner separation but more churn.
+
+**Recommendation: keep `window.msgapi`** — it's already documented as a generic host API, msger defines the canonical shape, and msgview implementing it keeps the WebView code host-agnostic without rename churn.
+
+## Migration sequence
+
+1. **Create `packages/mailx-host`** with the interface + msger impl. Swap `bin/mailx.ts` to use it. Behavior identical; this is pure refactor. **Done 2026-04-20.** The package re-exports `showMessageBox` / `showService` / `setAppName` from msger and exposes a `selectHost()` seam for future impl dispatch. `MAILX_HOST=msger|msgview` env var honored; default is msger on Windows + Linux, would-be msgview on Mac (throws today until step 2 lands).
+2. **Create `packages/mailx-host-msgview`** (deferred until Mac or arm64-fallback need). Add Electron as a dependency. Implement the shim. Add `msgview` package to `y:/dev/utils/msgx/msgview/` if it doesn't already expose a programmatic API (needs check — msgview currently is a standalone JSON viewer, may need its guts extracted into a library).
+3. **Detach decision** (deferred). Pick Option B. Add Electron bootstrap path to `bin/mailx.ts`: when `MAILX_HOST=msgview`, re-exec under Electron. Test on Linux (pi5a) and Windows.
+4. **Port `window.msgapi` surface** used by mailx into the msgview preload. Audit `client/lib/mailxapi.js` for every `msgapi.*` call — that's the minimum surface to re-implement.
+5. **Iflow transport under Electron main.** `NodeTcpTransport` already uses `node:net` / `node:tls`; Electron main has full node, so this should be drop-in. Verify TLS works (Electron bundles OpenSSL, not system).
+6. **Build + packaging.** Decide: separate npm packages for `mailx-host-msger` and `mailx-host-msgview`, or one package with lazy-loaded impls? Probably lazy-load so Electron isn't dragged in for Windows users. Host selection picks impl; unused impl is never required.
+7. **Documentation** in msgx/parity.md: update with msgview side. (Step 1 doc updates done 2026-04-20.)
+
+## Open questions
+
+- **Is msgview already a library, or is it a standalone app?** Need to check `y:/dev/utils/msgx/msgview/index.ts` — if it's CLI-only, we either (a) extract its core into a library `@bobfrankston/msgview-core` or (b) just build the Electron shell directly inside `mailx-host-msgview`. (b) is simpler if msgview's current feature set doesn't include anything we need to reuse.
+- **Windows: keep msger-only.** msger on Windows works well. msgview on Windows stays available via explicit `MAILX_HOST=msgview` for users who want to trade WebView2 Evergreen risk for Electron's bundle size.
+- **Auto-update.** msger has timestamped-exe + stable-hardlink. Electron has Squirrel auto-update. Different mechanisms — do we care about parity here or run two update strategies?
+- **AUMID across hosts.** `com.frankston.mailx` should be the same on both so taskbar pins work whichever host is running.
+- **pi5a as a build host.** User mentioned moving compile tooling from pi4c to pi5a. That's a separate decision, but relevant context: Rust cross-compile for msger aarch64 is still the primary Linux arm64 path (apt-install the webkit2gtk-4.1 system dep is cheap). msgview arm64 only matters if a specific user ends up on a distro that can't provide webkit2gtk-4.1.
+
+## Files to read when resuming
+
+- `y:/dev/utils/msgx/parity.md` — the authoritative msger feature list
+- `y:/dev/utils/msgx/msger/shower.ts` — current msger API surface
+- `y:/dev/utils/msgx/msger/msger-plan.md` — msger's independence rule (line 3)
+- `y:/dev/utils/msgx/msgview/index.ts` + `main.ts` — see what msgview exposes today
+- `y:/dev/email/mailx/bin/mailx.ts:820-900` — mailx's current msger usage
+- `y:/dev/email/mailx/client/lib/mailxapi.js` — the in-WebView IPC bridge (full `window.msgapi` surface used by mailx)
+- `y:/dev/email/mailx/client/lib/api-client.ts` — IPC vs HTTP auto-detection
+- `y:/dev/email/mailx/packages/mailx-service/jsonrpc.ts` — dispatcher (stays unchanged)
+- `y:/dev/email/mailx/CLAUDE.md` — architectural rules (msger independence, transport injection)