@littlebearapps/outlook-assistant 3.13.0 → 3.14.0

package/email/export.js

@@ -20,7 +20,18 @@ const { resolveFolderPath } = require('./folder-utils');
 const { buildMailboxPrefix } = require('../utils/mailbox');
 const { quoteSearchPhrase } = require('../utils/odata-helpers');
 const { safeAttachmentFilename } = require('./attachments');
-const { writeClaimedFile } = require('../utils/safe-write');
+const {
+  writeClaimedFile,
+  ensureOutputDir,
+  writeExplicitFile,
+  confineOutputPath,
+  confineOutputTarget,
+  fileExistsError,
+  pathEntryExists,
+  OutputPathError,
+} = require('../utils/safe-write');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 // Export format constants
 const EXPORT_FORMATS = {
@@ -36,31 +47,55 @@ const EXPORT_FORMATS = {
  * @param {object} args - Tool arguments
  * @param {string} args.id - Email ID (required)
  * @param {string} [args.format] - Export format (mime, eml, markdown, json)
- * @param {string} [args.savePath] - File path to save (optional)
+ * @param {string} [args.savePath] - File path or directory to save to (optional)
+ * @param {string} [args.outputDir] - Directory to save to (optional)
+ * @param {boolean} [args.overwrite] - Replace an existing savePath file (default: false)
  * @param {boolean} [args.includeAttachments] - Include attachments (default: true)
  * @returns {object} - MCP response with export status
  */
 async function handleExportEmail(args) {
   const emailId = args.id;
   const format = (args.format || EXPORT_FORMATS.MARKDOWN).toLowerCase();
-  // F-27: accept `outputDir` (canonical) and `savePath` (legacy alias).
-  // Previously single-message exports ignored outputDir entirely and
-  // hardcoded os.tmpdir(), inconsistent with target=messages.
-  const savePath = args.outputDir || args.savePath;
   const includeAttachments = args.includeAttachments !== false;
+  const overwrite = args.overwrite === true;
   // Message IDs are mailbox-scoped: route to /users/{mailbox} for a shared/
   // delegated mailbox, else /me.
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email ID is required.',
-        },
-      ],
-    };
+    return toolError('Email ID is required.');
+  }
+
+  // Where to write, checked before anything is fetched. F-27: `outputDir`
+  // is always a directory. `savePath` names a directory if one exists
+  // there, otherwise the file to write. With no path, the system temp
+  // directory is used. Writes go to the resolved path, never the raw one.
+  let explicitFile = null;
+  let requestedFile = null; // savePath as given, for messages
+  let explicitBase = null; // allowed directory it is in
+  let targetDir;
+  try {
+    if (args.outputDir) {
+      targetDir = confineOutputPath(args.outputDir);
+    } else if (args.savePath) {
+      const target = confineOutputTarget(args.savePath);
+      const resolved = target.path;
+      if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+        targetDir = resolved;
+      } else {
+        explicitFile = resolved;
+        requestedFile = target.requested;
+        explicitBase = target.base;
+        // Refuse early, before fetching; writeExplicitFile checks again.
+        if (!overwrite && pathEntryExists(explicitFile)) {
+          throw fileExistsError(requestedFile);
+        }
+      }
+    } else {
+      targetDir = confineOutputPath(os.tmpdir());
+    }
+  } catch (error) {
+    return outputPathError(error);
   }
 
   try {
@@ -77,14 +112,7 @@ async function handleExportEmail(args) {
     );
 
     if (!email) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Email with ID ${emailId} not found.`,
-          },
-        ],
-      };
+      return toolError(`Email with ID ${emailId} not found.`);
     }
 
     // Generate filename based on email metadata. The time matters: a
@@ -98,16 +126,6 @@ async function handleExportEmail(args) {
     // Paths claimed while writing this message (main file + attachments).
     const claimedPaths = new Set();
 
-    // Determine the save location. An explicit file path is the caller's to
-    // control — honour it exactly, including overwriting, since that is what
-    // an explicit path means. A directory (or the default temp dir) means we
-    // choose the name, so the write is exclusive (`wx`): it never clobbers an
-    // existing file and never follows a planted symlink.
-    const explicitFile =
-      savePath &&
-      !(fs.existsSync(savePath) && fs.statSync(savePath).isDirectory());
-    const targetDir = explicitFile ? null : savePath || os.tmpdir();
-
     // Export based on format
     let content;
     let attachmentsSaved = [];
@@ -130,34 +148,35 @@ async function handleExportEmail(args) {
     } else if (format === 'mbox' || format === 'html') {
       // F-26: clarify that mbox/html are conversation-only formats so
       // callers don't infer the format itself is unsupported.
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Format '${format}' is only supported for target=conversation. For target=message use one of: ${Object.values(EXPORT_FORMATS).join(', ')}.`,
-          },
-        ],
-      };
+      return toolError(
+        `Format '${format}' is only supported for target=conversation. For target=message use one of: ${Object.values(EXPORT_FORMATS).join(', ')}.`
+      );
     } else {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Unknown format: ${format}. Supported for target=message: ${Object.values(EXPORT_FORMATS).join(', ')}.`,
-          },
-        ],
-      };
+      return toolError(
+        `Unknown format: ${format}. Supported for target=message: ${Object.values(EXPORT_FORMATS).join(', ')}.`
+      );
     }
 
     // Save main file. Auto-create the directory so callers don't have to
-    // pre-mkdir.
+    // pre-mkdir. An explicit file is created exclusively and replaces an
+    // existing file only with overwrite: true. A directory means we choose
+    // the name, so the write is exclusive (`wx`): it never clobbers an
+    // existing file and never follows a planted symlink.
     let finalPath;
+    let replaced = false;
     if (explicitFile) {
-      finalPath = savePath;
-      fs.mkdirSync(path.dirname(finalPath), { recursive: true });
-      fs.writeFileSync(finalPath, content, 'utf8');
+      ({ path: finalPath, replaced } = writeExplicitFile(
+        explicitFile,
+        content,
+        {
+          overwrite,
+          encoding: 'utf8',
+          displayPath: requestedFile,
+          base: explicitBase,
+        }
+      ));
     } else {
-      fs.mkdirSync(targetDir, { recursive: true });
+      ensureOutputDir(targetDir);
       finalPath = writeClaimedFile(
         targetDir,
         defaultBase,
@@ -184,6 +203,7 @@ async function handleExportEmail(args) {
     resultText += `| Property | Value |\n`;
     resultText += `|----------|-------|\n`;
     resultText += `| File | \`${finalPath}\` |\n`;
+    if (replaced) resultText += `| Replaced | yes (existing file) |\n`;
     resultText += `| Format | ${format.toUpperCase()} |\n`;
     resultText += `| Size | ${content.length.toLocaleString()} bytes |\n`;
     resultText += `| Subject | ${email.subject} |\n`;
@@ -206,6 +226,7 @@ async function handleExportEmail(args) {
       ],
       _meta: {
         filePath: finalPath,
+        replaced,
         format: format,
         sizeBytes: content.length,
         attachmentsSaved: attachmentsSaved.length,
@@ -213,28 +234,27 @@ async function handleExportEmail(args) {
       },
     };
   } catch (error) {
+    if (error instanceof OutputPathError) {
+      return outputPathError(error);
+    }
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Export failed: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Export failed: ${error.message}`);
   }
 }
 
+/**
+ * Tool error for a refused output path; rethrows anything else.
+ * @param {Error} error
+ * @returns {object} MCP error response
+ */
+function outputPathError(error) {
+  if (!(error instanceof OutputPathError)) throw error;
+  return toolError(error.message, { nextStep: error.nextStep });
+}
+
 /**
  * Batch export emails handler
  * @param {object} args - Tool arguments
@@ -255,28 +275,25 @@ async function handleBatchExportEmails(args) {
     searchQuery.subject = args.query;
   }
   const format = (args.format || EXPORT_FORMATS.MARKDOWN).toLowerCase();
-  const outputDir = args.outputDir;
   const includeAttachments = args.includeAttachments === true; // Default false for batch
   // Scope the whole batch (search + per-message fetch + attachments) to a
   // shared/delegated mailbox when supplied.
   const mailbox = args.sharedMailbox || args.email || null;
   const prefix = buildMailboxPrefix(mailbox);
 
-  if (!outputDir) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Output directory is required.',
-        },
-      ],
-    };
+  if (!args.outputDir) {
+    return toolError('Output directory is required.');
   }
 
-  // Ensure output directory exists
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
+  // Resolve and check the directory before creating it; write only to the
+  // resolved path.
+  let outputDir;
+  try {
+    outputDir = confineOutputPath(args.outputDir);
+  } catch (error) {
+    return outputPathError(error);
   }
+  ensureOutputDir(outputDir);
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -290,24 +307,29 @@ async function handleBatchExportEmails(args) {
         mailbox
       );
       idsToExport = searchResults.map((e) => e.id);
+      // An empty match is a result, not an error.
+      if (idsToExport.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'No emails matched the search query; nothing was exported.',
+            },
+          ],
+        };
+      }
     }
 
     if (idsToExport.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'No emails to export. Provide emailIds or searchQuery.',
-          },
-        ],
-      };
+      return toolError('No emails to export. Provide emailIds or searchQuery.');
     }
 
-    // Limit batch size (per plan: max 100)
+    // Limit batch size (per plan: max 100), and say so in the result (#279)
     const maxBatch = 100;
+    const limitNote = batchLimitNote(idsToExport.length, emailIds, searchQuery);
     if (idsToExport.length > maxBatch) {
       idsToExport = idsToExport.slice(0, maxBatch);
-      console.error(`Batch export limited to ${maxBatch} emails`);
+      log.debug(`Batch export limited to ${maxBatch} emails`);
     }
 
     // CSV batch export: aggregate all emails into a single CSV file
@@ -333,7 +355,7 @@ async function handleBatchExportEmails(args) {
 
       const csvContent = formatEmailsAsCSV(emails);
       const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-      fs.mkdirSync(outputDir, { recursive: true });
+      ensureOutputDir(outputDir);
       const csvPath = writeClaimedFile(
         outputDir,
         `batch_export_${timestamp}`,
@@ -353,6 +375,7 @@ async function handleBatchExportEmails(args) {
       resultText += `| Output File | \`${csvPath}\` |\n`;
       resultText += `| Format | CSV |\n`;
       resultText += `| Total Size | ${(totalBytes / 1024).toFixed(1)} KB |\n`;
+      resultText += limitNote;
 
       if (failed.length > 0) {
         resultText += `\n### Failed Exports\n\n`;
@@ -407,6 +430,7 @@ async function handleBatchExportEmails(args) {
       0
     );
     resultText += `| Total Size | ${(totalBytes / 1024).toFixed(1)} KB |\n`;
+    resultText += limitNote;
 
     // Requested id -> written path, so a caller can reconcile without
     // listing the directory. A batch that silently lost messages to
@@ -452,25 +476,32 @@ async function handleBatchExportEmails(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Batch export failed: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Batch export failed: ${error.message}`);
+  }
+}
+
+/**
+ * Says when a batch export was cut short, and how to get the rest (#279).
+ * target=messages exports at most 100 messages per call, and a search stops
+ * at searchQuery.maxResults (default 25, max 100).
+ * @param {number} found - IDs given or matched before the cap
+ * @param {string[]} emailIds - IDs the caller passed (empty for a search)
+ * @param {object} searchQuery - The search used when emailIds is empty
+ * @returns {string} - Markdown note, or '' when nothing was left out
+ */
+function batchLimitNote(found, emailIds, searchQuery) {
+  if (emailIds.length > 0) {
+    if (found <= 100) return '';
+    return `\n> Exported the first 100 of ${found} requested messages (limit 100 per call). Export the remaining ${found - 100} IDs in another call.\n`;
   }
+  const searchLimit = Math.min(searchQuery.maxResults || 25, 100);
+  if (found < searchLimit) return '';
+  const raise =
+    searchLimit < 100 ? 'raise `searchQuery.maxResults` (up to 100) or ' : '';
+  return `\n> The search stopped at ${searchLimit} messages, the \`searchQuery.maxResults\` limit (default 25, max 100 per call), so more may match. To get the rest, ${raise}export in date ranges with \`searchQuery.receivedAfter\`/\`receivedBefore\`.\n`;
 }
 
 /**
@@ -707,7 +738,7 @@ async function saveAttachments(
       }
     }
   } catch (error) {
-    console.error(`Failed to save attachments: ${error.message}`);
+    log.debug(`Failed to save attachments: ${error.message}`);
   }
 
   return saved;

package/email/folder-utils.js

@@ -3,6 +3,7 @@
  */
 const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { log } = require('../utils/logger');
 
 /**
  * Cache of folder information to reduce API calls
@@ -74,7 +75,7 @@ async function resolveFolderPath(accessToken, folderName, mailbox = null) {
   // Check if it's a well-known folder (case-insensitive)
   const lowerFolderName = folderName.toLowerCase();
   if (WELL_KNOWN_FOLDERS[lowerFolderName]) {
-    console.error(`Using well-known folder path for "${folderName}"`);
+    log.debug(`Using well-known folder path for "${folderName}"`);
     return scope(WELL_KNOWN_FOLDERS[lowerFolderName], prefix);
   }
 
@@ -93,7 +94,7 @@ async function resolveFolderPath(accessToken, folderName, mailbox = null) {
       mailbox,
     });
     const path = `${prefix}/mailFolders/${resolved.id}/messages`;
-    console.error(`Resolved folder "${folderName}" to path: ${path}`);
+    log.debug(`Resolved folder "${folderName}" to path: ${path}`);
     return path;
   } catch (error) {
     // Surface not-found / ambiguity messages verbatim; wrap anything else.

package/email/headers.js

@@ -7,6 +7,8 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Important headers to highlight (in order of relevance)
@@ -164,14 +166,7 @@ async function handleGetEmailHeaders(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email ID is required.',
-        },
-      ],
-    };
+    return toolError('Email ID is required.');
   }
 
   try {
@@ -206,14 +201,7 @@ async function handleGetEmailHeaders(args) {
       );
 
       if (!email) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Email with ID ${emailId} not found.`,
-            },
-          ],
-        };
+        return toolError(`Email with ID ${emailId} not found.`);
       }
 
       const headers = email.internetMessageHeaders || [];
@@ -296,48 +284,22 @@ async function handleGetEmailHeaders(args) {
         },
       };
     } catch (error) {
-      console.error(`Error getting email headers: ${error.message}`);
+      log.debug(`Error getting email headers: ${error.message}`);
 
       if (error.message.includes("doesn't belong to the targeted mailbox")) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `The email ID seems invalid or doesn't belong to your mailbox.`,
-            },
-          ],
-        };
+        return toolError(
+          `The email ID seems invalid or doesn't belong to your mailbox.`
+        );
       }
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Failed to get email headers: ${error.message}`,
-          },
-        ],
-      };
+      return toolError(`Failed to get email headers: ${error.message}`);
     }
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error accessing email: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing email: ${error.message}`);
   }
 }