icloud-mcp 2.5.0 → 2.7.0

package/lib/imap.js

@@ -1,14 +1,17 @@
 import { ImapFlow } from 'imapflow';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
 import {
   decodeTransferEncoding, decodeCharset, stripHtml, extractRawHeader,
   findTextPart, findAttachments, estimateEmailSize, stripSubjectPrefixes
 } from './mime.js';
+import { dataFile } from './data-paths.js';
 
-const MANIFEST_FILE = join(homedir(), '.icloud-mcp-move-manifest.json');
-const RULES_FILE = join(homedir(), '.icloud-mcp-rules.json');
+function manifestFile() {
+  return dataFile('.icloud-mcp-move-manifest.json');
+}
+function rulesFile() {
+  return dataFile('.icloud-mcp-rules.json');
+}
 const MAX_HISTORY = 5;
 
 // ─── Connection helpers ───────────────────────────────────────────────────────
@@ -20,7 +23,7 @@ function createClient(creds) {
   const host = creds?.host || 'imap.mail.me.com';
   const user = creds?.user || process.env.IMAP_USER;
   const pass = creds?.pass || process.env.IMAP_PASSWORD;
-  return new ImapFlow({
+  const client = new ImapFlow({
     host,
     port: 993,
     secure: true,
@@ -30,6 +33,14 @@ function createClient(creds) {
     greetingTimeout: 15_000,     // 15s to receive IMAP greeting after connect
     socketTimeout: 60_000,       // 60s of inactivity before socket is killed
   });
+  // ImapFlow emits 'error' on socket timeouts and resets. With no listener, Node
+  // throws it as an uncaught exception and the whole server exits mid-operation.
+  // The connection closes either way and pending commands reject, so the tool
+  // call that owns this client still gets an error to report.
+  client.on('error', (err) => {
+    process.stderr.write(`[imap] connection error: ${err.message}\n`);
+  });
+  return client;
 }
 
 // ─── Managed client helpers ───────────────────────────────────────────────────
@@ -45,7 +56,14 @@ let _lastConnectTime = 0;
 let _connectGate = Promise.resolve();
 const MIN_CONNECT_INTERVAL = 10; // ms between connection initiations
 
+// Test seam. Production leaves this null, so clients are created exactly as before.
+let imapClientFactory = null;
+export function setImapClientFactory(factory) {
+  imapClientFactory = factory;
+}
+
 export function createRateLimitedClient(creds) {
+  if (imapClientFactory) return imapClientFactory(creds);
   const client = createClient(creds);
   const originalConnect = client.connect.bind(client);
   client.connect = async () => {
@@ -85,16 +103,17 @@ const ATTACHMENT_SCAN_LIMIT = 500; // max UIDs to scan client-side for hasAttach
 const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024; // 20 MB cap for get_attachment downloads
 
 function readManifest() {
-  if (!existsSync(MANIFEST_FILE)) return { current: null, history: [] };
+  const file = manifestFile();
+  if (!existsSync(file)) return { current: null, history: [] };
   try {
-    return JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
+    return JSON.parse(readFileSync(file, 'utf8'));
   } catch {
     return { current: null, history: [] };
   }
 }
 
 function writeManifest(data) {
-  writeFileSync(MANIFEST_FILE, JSON.stringify(data, null, 2));
+  writeFileSync(manifestFile(), JSON.stringify(data, null, 2));
 }
 
 function updateManifest(updater) {
@@ -732,9 +751,9 @@ export async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = fa
       if (msg) {
         emails.push({
           uid,
-          subject: msg.envelope.subject,
-          from: msg.envelope.from?.[0]?.address,
-          date: msg.envelope.date,
+          subject: msg.envelope?.subject,
+          from: msg.envelope?.from?.[0]?.address,
+          date: msg.envelope?.date,
           flagged: msg.flags.has('\\Flagged'),
           seen: msg.flags.has('\\Seen')
         });
@@ -751,9 +770,9 @@ export async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = fa
   for await (const msg of client.fetch(range, { envelope: true, flags: true })) {
     emails.push({
       uid: msg.uid,
-      subject: msg.envelope.subject,
-      from: msg.envelope.from?.[0]?.address,
-      date: msg.envelope.date,
+      subject: msg.envelope?.subject,
+      from: msg.envelope?.from?.[0]?.address,
+      date: msg.envelope?.date,
       flagged: msg.flags.has('\\Flagged'),
       seen: msg.flags.has('\\Seen')
     });
@@ -786,7 +805,7 @@ export async function getTopSenders(mailbox = 'INBOX', sampleSize = 500, maxResu
   let count = 0;
 
   for await (const msg of client.fetch(range, { envelope: true })) {
-    const address = msg.envelope.from?.[0]?.address;
+    const address = msg.envelope?.from?.[0]?.address;
     if (address) {
       senderCounts[address] = (senderCounts[address] || 0) + 1;
       const domain = address.split('@')[1];
@@ -815,7 +834,7 @@ export async function getUnreadSenders(mailbox = 'INBOX', sampleSize = 500, maxR
   }
 
   for await (const msg of client.fetch(recentUids, { envelope: true }, { uid: true })) {
-    const address = msg.envelope.from?.[0]?.address;
+    const address = msg.envelope?.from?.[0]?.address;
     if (address) senderCounts[address] = (senderCounts[address] || 0) + 1;
   }
 
@@ -836,9 +855,9 @@ export async function getEmailsBySender(sender, mailbox = 'INBOX', limit = 10, c
     if (msg) {
       emails.push({
         uid,
-        subject: msg.envelope.subject,
-        from: msg.envelope.from?.[0]?.address,
-        date: msg.envelope.date,
+        subject: msg.envelope?.subject,
+        from: msg.envelope?.from?.[0]?.address,
+        date: msg.envelope?.date,
         flagged: msg.flags.has('\\Flagged'),
         seen: msg.flags.has('\\Seen')
       });
@@ -848,11 +867,22 @@ export async function getEmailsBySender(sender, mailbox = 'INBOX', limit = 10, c
   return { total, showing: emails.length, emails };
 }
 
-export async function bulkDeleteBySender(sender, mailbox = 'INBOX', creds = null) {
+export async function bulkDeleteBySender(sender, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldDelete: uids.length,
+      sender,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'delete', uid, mailbox, sender })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
@@ -864,7 +894,7 @@ export async function bulkDeleteBySender(sender, mailbox = 'INBOX', creds = null
   return { deleted, sender };
 }
 
-export async function markOlderThanRead(days, mailbox = 'INBOX', creds = null) {
+export async function markOlderThanRead(days, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
@@ -872,6 +902,17 @@ export async function markOlderThanRead(days, mailbox = 'INBOX', creds = null) {
   date.setDate(date.getDate() - days);
   const raw = await client.search({ before: date, seen: false }, { uid: true });
   const uids = Array.isArray(raw) ? raw : [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldMarkRead: uids.length,
+      olderThan: date.toISOString(),
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'mark_read', uid, mailbox })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { marked: 0, olderThan: date.toISOString() }; }
   await client.messageFlagsAdd(uids, ['\\Seen'], { uid: true });
   await client.logout();
@@ -889,18 +930,39 @@ export async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'I
   await client.mailboxOpen(sourceMailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
   await client.logout();
-  if (dryRun) return { dryRun: true, wouldMove: uids.length, sender, sourceMailbox, targetMailbox };
+  if (dryRun) {
+    return {
+      dryRun: true,
+      wouldMove: uids.length,
+      sender,
+      sourceMailbox,
+      targetMailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'move', uid, sender, sourceMailbox, targetMailbox })),
+    };
+  }
   if (uids.length === 0) return { moved: 0 };
   await ensureMailbox(targetMailbox, creds);
   const result = await safeMoveEmails(uids, sourceMailbox, targetMailbox, creds);
   return { ...result, sender, targetMailbox };
 }
 
-export async function bulkDeleteBySubject(subject, mailbox = 'INBOX', creds = null) {
+export async function bulkDeleteBySubject(subject, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ subject }, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldDelete: uids.length,
+      subject,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'delete', uid, mailbox, subject })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
@@ -912,13 +974,24 @@ export async function bulkDeleteBySubject(subject, mailbox = 'INBOX', creds = nu
   return { deleted, subject };
 }
 
-export async function deleteOlderThan(days, mailbox = 'INBOX', creds = null) {
+export async function deleteOlderThan(days, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const date = new Date();
   date.setDate(date.getDate() - days);
   const uids = (await client.search({ before: date }, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldDelete: uids.length,
+      olderThan: date.toISOString(),
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'delete', uid, mailbox })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
   let deleted = 0;
   for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
@@ -943,9 +1016,9 @@ export async function getEmailsByDateRange(startDate, endDate, mailbox = 'INBOX'
     if (msg) {
       emails.push({
         uid,
-        subject: msg.envelope.subject,
-        from: msg.envelope.from?.[0]?.address,
-        date: msg.envelope.date,
+        subject: msg.envelope?.subject,
+        from: msg.envelope?.from?.[0]?.address,
+        date: msg.envelope?.date,
         flagged: msg.flags.has('\\Flagged'),
         seen: msg.flags.has('\\Seen')
       });
@@ -955,36 +1028,71 @@ export async function getEmailsByDateRange(startDate, endDate, mailbox = 'INBOX'
   return { total, showing: emails.length, emails };
 }
 
-export async function bulkMarkRead(mailbox = 'INBOX', sender = null, creds = null) {
+export async function bulkMarkRead(mailbox = 'INBOX', sender = null, creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = sender ? { from: sender, seen: false } : { seen: false };
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldMarkRead: uids.length,
+      sender: sender || 'all',
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'mark_read', uid, mailbox, sender: sender || 'all' })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { marked: 0 }; }
   await client.messageFlagsAdd(uids, ['\\Seen'], { uid: true });
   await client.logout();
   return { marked: uids.length, sender: sender || 'all' };
 }
 
-export async function bulkMarkUnread(mailbox = 'INBOX', sender = null, creds = null) {
+export async function bulkMarkUnread(mailbox = 'INBOX', sender = null, creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = sender ? { from: sender, seen: true } : { seen: true };
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return {
+      dryRun: true,
+      wouldMarkUnread: uids.length,
+      sender: sender || 'all',
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'mark_unread', uid, mailbox, sender: sender || 'all' })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { marked: 0 }; }
   await client.messageFlagsRemove(uids, ['\\Seen'], { uid: true });
   await client.logout();
   return { marked: uids.length, sender: sender || 'all' };
 }
 
-export async function bulkFlag(filters, flagged, mailbox = 'INBOX', creds = null) {
+export async function bulkFlag(filters, flagged, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const query = buildQuery(filters);
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    const action = flagged ? 'flag' : 'unflag';
+    return {
+      dryRun: true,
+      wouldAffect: uids.length,
+      [flagged ? 'wouldFlag' : 'wouldUnflag']: uids.length,
+      filters,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action, uid, mailbox })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { flagged: 0 }; }
   if (flagged) {
     await client.messageFlagsAdd(uids, ['\\Flagged'], { uid: true });
@@ -995,12 +1103,25 @@ export async function bulkFlag(filters, flagged, mailbox = 'INBOX', creds = null
   return { [flagged ? 'flagged' : 'unflagged']: uids.length, filters };
 }
 
-export async function bulkFlagBySender(sender, flagged, mailbox = 'INBOX', creds = null) {
+export async function bulkFlagBySender(sender, flagged, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const raw = await client.search({ from: sender }, { uid: true });
   const uids = Array.isArray(raw) ? raw : [];
+  if (dryRun) {
+    await client.logout();
+    const action = flagged ? 'flag' : 'unflag';
+    return {
+      dryRun: true,
+      wouldAffect: uids.length,
+      [flagged ? 'wouldFlag' : 'wouldUnflag']: uids.length,
+      sender,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action, uid, mailbox, sender })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { [flagged ? 'flagged' : 'unflagged']: 0, sender }; }
   if (flagged) {
     await client.messageFlagsAdd(uids, ['\\Flagged'], { uid: true });
@@ -1042,7 +1163,13 @@ export async function emptyTrash(dryRun = false, creds = null) {
 
   if (dryRun) {
     await safeClose(client);
-    return { dryRun: true, wouldDelete: uids.length, mailbox };
+    return {
+      dryRun: true,
+      wouldDelete: uids.length,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'delete', uid, mailbox })),
+    };
   }
 
   if (uids.length === 0) {
@@ -1069,7 +1196,17 @@ export async function archiveOlderThan(days, targetMailbox, sourceMailbox = 'INB
   const raw = await client.search({ before: date }, { uid: true });
   const uids = Array.isArray(raw) ? raw : [];
   await client.logout();
-  if (dryRun) return { dryRun: true, wouldMove: uids.length, olderThan: date.toISOString(), sourceMailbox, targetMailbox };
+  if (dryRun) {
+    return {
+      dryRun: true,
+      wouldMove: uids.length,
+      olderThan: date.toISOString(),
+      sourceMailbox,
+      targetMailbox,
+      uids,
+      changes: uids.map(uid => ({ action: 'move', uid, sourceMailbox, targetMailbox })),
+    };
+  }
   if (uids.length === 0) return { moved: 0, olderThan: date.toISOString(), sourceMailbox, targetMailbox };
   await ensureMailbox(targetMailbox, creds);
   const result = await safeMoveEmails(uids, sourceMailbox, targetMailbox, creds);
@@ -1251,10 +1388,20 @@ export async function renameMailbox(oldName, newName, creds = null) {
   return { renamed: { from: oldName, to: newName } };
 }
 
-export async function deleteMailbox(name, creds = null) {
+export async function deleteMailbox(name, creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   try {
+    if (dryRun) {
+      const status = await client.status(name, { messages: true });
+      return {
+        dryRun: true,
+        wouldDelete: true,
+        mailbox: name,
+        messageCount: status.messages,
+        changes: [{ action: 'delete_mailbox', mailbox: name, messageCount: status.messages }],
+      };
+    }
     await Promise.race([
       client.mailboxDelete(name),
       new Promise((_, reject) =>
@@ -1357,9 +1504,9 @@ export async function getEmailContent(uid, mailbox = 'INBOX', maxChars = 8000, i
   const attachments = meta.bodyStructure ? findAttachments(meta.bodyStructure) : [];
   const result = {
     uid: meta.uid,
-    subject: meta.envelope.subject,
-    from: meta.envelope.from?.[0]?.address,
-    date: meta.envelope.date,
+    subject: meta.envelope?.subject,
+    from: meta.envelope?.from?.[0]?.address,
+    date: meta.envelope?.date,
     flags: [...meta.flags],
     attachments: {
       count: attachments.length,
@@ -1373,11 +1520,11 @@ export async function getEmailContent(uid, mailbox = 'INBOX', maxChars = 8000, i
     const rawRefs = extractRawHeader(meta.headers, 'references');
     const rawUnsub = extractRawHeader(meta.headers, 'list-unsubscribe');
     result.headers = {
-      to: meta.envelope.to?.map(a => a.address) ?? [],
-      cc: meta.envelope.cc?.map(a => a.address) ?? [],
-      replyTo: meta.envelope.replyTo?.[0]?.address ?? null,
-      messageId: meta.envelope.messageId ?? null,
-      inReplyTo: meta.envelope.inReplyTo ?? null,
+      to: meta.envelope?.to?.map(a => a.address) ?? [],
+      cc: meta.envelope?.cc?.map(a => a.address) ?? [],
+      replyTo: meta.envelope?.replyTo?.[0]?.address ?? null,
+      messageId: meta.envelope?.messageId ?? null,
+      inReplyTo: meta.envelope?.inReplyTo ?? null,
       references: rawRefs ? rawRefs.split(/\s+/).filter(s => s.startsWith('<')) : [],
       listUnsubscribe: rawUnsub || null
     };
@@ -1396,7 +1543,7 @@ export async function listAttachments(uid, mailbox = 'INBOX', creds = null) {
   const attachments = meta.bodyStructure ? findAttachments(meta.bodyStructure) : [];
   return {
     uid: meta.uid,
-    subject: meta.envelope.subject,
+    subject: meta.envelope?.subject,
     attachmentCount: attachments.length,
     attachments
   };
@@ -1555,10 +1702,26 @@ export async function markAsRead(uid, seen, mailbox = 'INBOX', creds = null) {
   return true;
 }
 
-export async function deleteEmail(uid, mailbox = 'INBOX', creds = null) {
+export async function deleteEmail(uid, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
+  if (dryRun) {
+    const msg = await client.fetchOne(uid, { envelope: true }, { uid: true });
+    await client.logout();
+    if (!msg) throw new Error(`Email UID ${uid} not found`);
+    return {
+      dryRun: true,
+      wouldDelete: 1,
+      changes: [{
+        action: 'delete',
+        uid,
+        mailbox,
+        subject: msg.envelope?.subject ?? null,
+        from: msg.envelope?.from?.[0]?.address ?? null,
+      }],
+    };
+  }
   await client.messageDelete(uid, { uid: true });
   await client.logout();
   return true;
@@ -1609,8 +1772,13 @@ export async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters
 
   const extraQuery = buildQuery(filters);
   const hasExtra = Object.keys(extraQuery).length > 0 && !extraQuery.all;
+  // Both sides can carry an OR (keyword search and the domain filter). A query
+  // object holds only one 'or' key, so fold the filter's OR into each text branch.
+  const merged = textQuery?.or && extraQuery.or
+    ? { ...textQuery, ...extraQuery, or: textQuery.or.map(part => ({ ...part, or: extraQuery.or })) }
+    : { ...textQuery, ...extraQuery };
   const finalQuery = textQuery
-    ? (hasExtra ? { ...textQuery, ...extraQuery } : textQuery)
+    ? (hasExtra ? merged : textQuery)
     : (hasExtra ? extraQuery : { all: true });
 
   let uids = (await client.search(finalQuery, { uid: true })) ?? [];
@@ -1631,9 +1799,9 @@ export async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters
     if (msg) {
       emails.push({
         uid,
-        subject: msg.envelope.subject,
-        from: msg.envelope.from?.[0]?.address,
-        date: msg.envelope.date,
+        subject: msg.envelope?.subject,
+        from: msg.envelope?.from?.[0]?.address,
+        date: msg.envelope?.date,
         flagged: msg.flags.has('\\Flagged'),
         seen: msg.flags.has('\\Seen')
       });
@@ -1668,10 +1836,27 @@ export async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters
   return { total: uids.length, showing: emails.length, emails };
 }
 
-export async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX', creds = null) {
+export async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
+  if (dryRun) {
+    const msg = await client.fetchOne(uid, { envelope: true }, { uid: true });
+    await client.logout();
+    if (!msg) throw new Error(`Email UID ${uid} not found`);
+    return {
+      dryRun: true,
+      wouldMove: 1,
+      changes: [{
+        action: 'move',
+        uid,
+        sourceMailbox,
+        targetMailbox,
+        subject: msg.envelope?.subject ?? null,
+        from: msg.envelope?.from?.[0]?.address ?? null,
+      }],
+    };
+  }
   await client.messageMove(uid, targetMailbox, { uid: true });
   await client.logout();
   return true;
@@ -1680,7 +1865,13 @@ export async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX', cre
 function buildQuery(filters) {
   const query = {};
   if (filters.sender) query.from = filters.sender;
-  if (filters.domain) query.from = filters.domain.replace(/^@/, '');
+  // iCloud's FROM search is inconsistent with domains: the bare domain misses some
+  // senders (e.g. "Name <someone@example.com>") that "@domain" finds, so match
+  // either form.
+  if (filters.domain) {
+    const domain = filters.domain.replace(/^@/, '');
+    query.or = [{ from: domain }, { from: `@${domain}` }];
+  }
   if (filters.subject) query.subject = filters.subject;
   if (filters.before) query.before = new Date(filters.before);
   if (filters.since) query.since = new Date(filters.since);
@@ -1732,7 +1923,15 @@ export async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX',
   if (limit !== null) uids = uids.slice(0, limit);
 
   if (dryRun) {
-    return { dryRun: true, wouldMove: uids.length, sourceMailbox, targetMailbox, filters };
+    return {
+      dryRun: true,
+      wouldMove: uids.length,
+      sourceMailbox,
+      targetMailbox,
+      filters,
+      uids,
+      changes: uids.map(uid => ({ action: 'move', uid, sourceMailbox, targetMailbox })),
+    };
   }
   if (uids.length === 0) return { moved: 0, sourceMailbox, targetMailbox };
 
@@ -1762,7 +1961,14 @@ export async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = fals
 
   if (dryRun) {
     await client.logout();
-    return { dryRun: true, wouldDelete: uids.length, sourceMailbox, filters };
+    return {
+      dryRun: true,
+      wouldDelete: uids.length,
+      sourceMailbox,
+      filters,
+      uids,
+      changes: uids.map(uid => ({ action: 'delete', uid, mailbox: sourceMailbox })),
+    };
   }
   if (uids.length === 0) { await client.logout(); return { deleted: 0, sourceMailbox }; }
 
@@ -1810,13 +2016,14 @@ export async function countEmails(filters, mailbox = 'INBOX', creds = null) {
 // ─── Saved Rules ─────────────────────────────────────────────────────────────
 
 function readRules() {
-  if (!existsSync(RULES_FILE)) return { rules: [] };
-  try { return JSON.parse(readFileSync(RULES_FILE, 'utf8')); }
+  const file = rulesFile();
+  if (!existsSync(file)) return { rules: [] };
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
   catch { return { rules: [] }; }
 }
 
 function writeRules(data) {
-  writeFileSync(RULES_FILE, JSON.stringify(data, null, 2));
+  writeFileSync(rulesFile(), JSON.stringify(data, null, 2));
 }
 
 export function createRule(name, filters, action, description = '') {
@@ -1849,22 +2056,48 @@ export function listRules() {
   return { rules: readRules().rules };
 }
 
-export function deleteRule(name) {
+export function deleteRule(name, dryRun = false) {
   const data = readRules();
   const idx = data.rules.findIndex(r => r.name === name);
   if (idx === -1) throw new Error(`Rule '${name}' not found.`);
+  const rule = data.rules[idx];
+  if (dryRun) {
+    return {
+      dryRun: true,
+      wouldDelete: true,
+      name,
+      changes: [{
+        action: 'delete_rule',
+        name,
+        description: rule.description,
+        filters: rule.filters,
+        ruleAction: rule.action,
+      }],
+    };
+  }
   data.rules.splice(idx, 1);
   writeRules(data);
   return { deleted: true, name };
 }
 
-async function bulkMarkByFilters(filters, read, mailbox = 'INBOX', creds = null) {
+async function bulkMarkByFilters(filters, read, mailbox = 'INBOX', creds = null, dryRun = false) {
   const client = createRateLimitedClient(creds);
   await client.connect();
   await client.mailboxOpen(mailbox);
   const base = buildQuery(filters);
   const query = { ...base, ...(read ? { seen: false } : { seen: true }) };
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    const action = read ? 'mark_read' : 'mark_unread';
+    return {
+      dryRun: true,
+      wouldAffect: uids.length,
+      mailbox,
+      uids,
+      changes: uids.map(uid => ({ action, uid, mailbox })),
+    };
+  }
   if (uids.length === 0) { await client.logout(); return { marked: 0 }; }
   if (read) {
     await client.messageFlagsAdd(uids, ['\\Seen'], { uid: true });
@@ -1883,34 +2116,14 @@ async function executeRule(rule, dryRun = false) {
       return bulkMove(filters, action.targetMailbox, sourceMailbox, dryRun);
     case 'delete':
       return bulkDelete(filters, sourceMailbox, dryRun);
-    case 'mark_read': {
-      if (dryRun) {
-        const { count } = await countEmails(filters, sourceMailbox);
-        return { dryRun: true, wouldAffect: count ?? 0 };
-      }
-      return bulkMarkByFilters(filters, true, sourceMailbox);
-    }
-    case 'mark_unread': {
-      if (dryRun) {
-        const { count } = await countEmails(filters, sourceMailbox);
-        return { dryRun: true, wouldAffect: count ?? 0 };
-      }
-      return bulkMarkByFilters(filters, false, sourceMailbox);
-    }
-    case 'flag': {
-      if (dryRun) {
-        const { count } = await countEmails(filters, sourceMailbox);
-        return { dryRun: true, wouldAffect: count ?? 0 };
-      }
-      return bulkFlag(filters, true, sourceMailbox);
-    }
-    case 'unflag': {
-      if (dryRun) {
-        const { count } = await countEmails(filters, sourceMailbox);
-        return { dryRun: true, wouldAffect: count ?? 0 };
-      }
-      return bulkFlag(filters, false, sourceMailbox);
-    }
+    case 'mark_read':
+      return bulkMarkByFilters(filters, true, sourceMailbox, null, dryRun);
+    case 'mark_unread':
+      return bulkMarkByFilters(filters, false, sourceMailbox, null, dryRun);
+    case 'flag':
+      return bulkFlag(filters, true, sourceMailbox, null, dryRun);
+    case 'unflag':
+      return bulkFlag(filters, false, sourceMailbox, null, dryRun);
     default:
       throw new Error(`Unknown action type: ${action.type}`);
   }