@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/contacts/index.js

@@ -9,6 +9,10 @@ const {
 } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { quoteSearchPhrase } = require('../utils/odata-helpers');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { dryRunResult, dryRunUnsupported } = require('../utils/safety');
+const { log } = require('../utils/logger');
 
 /**
  * Contact field presets for different use cases
@@ -195,20 +199,9 @@ async function handleListContacts(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error listing contacts: ${error.message}` },
-      ],
-    };
+    return toolError(`Error listing contacts: ${error.message}`);
   }
 }
 
@@ -221,7 +214,7 @@ async function handleSearchContacts(args) {
   const verbosity = args.outputVerbosity || 'standard';
 
   if (!query) {
-    return { content: [{ type: 'text', text: 'Search query is required.' }] };
+    return toolError('Search query is required.');
   }
 
   try {
@@ -252,7 +245,7 @@ async function handleSearchContacts(args) {
       );
     } catch (filterError) {
       // Fallback: fetch all contacts and filter client-side if $filter is unsupported
-      console.error(
+      log.debug(
         `Contact $filter failed (${filterError.message}), falling back to client-side filter`
       );
       const allParams = {
@@ -295,20 +288,9 @@ async function handleSearchContacts(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error searching contacts: ${error.message}` },
-      ],
-    };
+    return toolError(`Error searching contacts: ${error.message}`);
   }
 }
 
@@ -319,7 +301,7 @@ async function handleGetContact(args) {
   const contactId = args.id;
 
   if (!contactId) {
-    return { content: [{ type: 'text', text: 'Contact ID is required.' }] };
+    return toolError('Contact ID is required.');
   }
 
   try {
@@ -346,20 +328,9 @@ async function handleGetContact(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error getting contact: ${error.message}` },
-      ],
-    };
+    return toolError(`Error getting contact: ${error.message}`);
   }
 }
 
@@ -387,14 +358,9 @@ async function handleCreateContact(args) {
     (Array.isArray(emails) && emails[0]);
 
   if (!resolvedDisplayName && !email && !(emails && emails.length > 0)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least displayName, firstName/lastName, email, or emails is required.',
-        },
-      ],
-    };
+    return toolError(
+      'At least displayName, firstName/lastName, email, or emails is required.'
+    );
   }
 
   try {
@@ -453,20 +419,9 @@ async function handleCreateContact(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error creating contact: ${error.message}` },
-      ],
-    };
+    return toolError(`Error creating contact: ${error.message}`);
   }
 }
 
@@ -478,7 +433,7 @@ async function handleUpdateContact(args) {
     args;
 
   if (!id) {
-    return { content: [{ type: 'text', text: 'Contact ID is required.' }] };
+    return toolError('Contact ID is required.');
   }
 
   try {
@@ -521,23 +476,37 @@ async function handleUpdateContact(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error updating contact: ${error.message}` },
-      ],
-    };
+    return toolError(`Error updating contact: ${error.message}`);
   }
 }
 
+/**
+ * dryRun preview for delete (#274): which contact would be lost. Reads only.
+ */
+async function previewDeleteContact(accessToken, contactId) {
+  const contact = await callGraphAPI(
+    accessToken,
+    'GET',
+    `me/contacts/${contactId}`,
+    null,
+    { $select: 'displayName,emailAddresses,companyName' }
+  );
+  const details = [
+    ...(contact.emailAddresses || []).map((e) => e.address).filter(Boolean),
+    contact.companyName,
+  ].filter(Boolean);
+  const name = contact.displayName || '(no name)';
+  return dryRunResult(
+    [
+      `Deletes contact '${name}'${details.length > 0 ? ` (${details.join('; ')})` : ''}.`,
+      "It doesn't go to Deleted Items, and Graph doesn't document a way to restore it (Outlook's \"Recover deleted items\" may work for a limited time, but don't rely on it), so treat it as permanent.",
+    ],
+    { action: 'delete', contactId, displayName: contact.displayName }
+  );
+}
+
 /**
  * Delete contact handler
  */
@@ -545,12 +514,17 @@ async function handleDeleteContact(args) {
   const contactId = args.id;
 
   if (!contactId) {
-    return { content: [{ type: 'text', text: 'Contact ID is required.' }] };
+    return toolError('Contact ID is required.');
   }
 
   try {
     const accessToken = await ensureAuthenticated();
 
+    // dryRun: say which contact would be lost; delete nothing.
+    if (args.dryRun) {
+      return await previewDeleteContact(accessToken, contactId);
+    }
+
     const endpoint = `me/contacts/${contactId}`;
     await callGraphAPI(accessToken, 'DELETE', endpoint);
 
@@ -565,20 +539,9 @@ async function handleDeleteContact(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error deleting contact: ${error.message}` },
-      ],
-    };
+    return toolError(`Error deleting contact: ${error.message}`);
   }
 }
 
@@ -590,7 +553,7 @@ async function handleSearchPeople(args) {
   const count = Math.min(args.count || 25, 50);
 
   if (!query) {
-    return { content: [{ type: 'text', text: 'Search query is required.' }] };
+    return toolError('Search query is required.');
   }
 
   try {
@@ -658,20 +621,9 @@ async function handleSearchPeople(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error searching people: ${error.message}` },
-      ],
-    };
+    return toolError(`Error searching people: ${error.message}`);
   }
 }
 
@@ -680,13 +632,8 @@ const contactsTools = [
   {
     name: 'manage-contact',
     description:
-      "Full CRUD over the signed-in user's personal Outlook contacts (destructive: covers `delete` action). action=`list` (default) returns contacts with pagination via `skip`/`count` (default 50). action=`search` returns contacts matching `query` against name/email (default 25). action=`get` returns full contact detail by `id`. action=`create` adds a new contact and returns its `id`. action=`update` patches the given fields by `id` (only fields passed are changed). action=`delete` permanently removes the contact by `id`. Use `outputVerbosity` (minimal/standard/full) on list/search to control field count. Prefer `search-people` for cross-source relevance ranking (contacts + directory + recent comms) — this tool only searches your personal contact store.",
-    annotations: {
-      title: 'Contacts',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      "Full CRUD over the signed-in user's personal Outlook contacts (destructive: covers `delete` action). action=`list` (default) returns contacts with pagination via `skip`/`count` (default 50). action=`search` returns contacts matching `query` against name/email (default 25). action=`get` returns full contact detail by `id`. action=`create` adds a new contact and returns its `id`. action=`update` patches the given fields by `id` (only fields passed are changed). action=`delete` removes the contact by `id`; it skips Deleted Items, so treat it as permanent and pass `dryRun: true` first to confirm which contact it is. Use `outputVerbosity` (minimal/standard/full) on list/search to control field count. Searches only your personal contact store; for relevance-ranked search across contacts, the directory and recent communications, use `search-people`.",
+    ...toolMetadata('manage-contact', 'Contacts'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -768,12 +715,20 @@ const contactsTools = [
           type: 'string',
           description: 'Personal notes (action=create/update)',
         },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview only (action=delete): nothing is deleted. Shows which contact would be removed. Other actions refuse dryRun and change nothing. Default false.',
+        },
       },
       additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
       const action = args.action || 'list';
+      if (args.dryRun && action !== 'delete') {
+        return dryRunUnsupported('manage-contact', action, 'delete');
+      }
       switch (action) {
         case 'search':
           return handleSearchContacts(args);
@@ -788,28 +743,17 @@ const contactsTools = [
         case 'list':
           return handleListContacts(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, search, get, create, update, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, search, get, create, update, delete.`
+          );
       }
     },
   },
   {
     name: 'search-people',
     description:
-      'Relevance-ranked search across personal contacts, organisation directory, and recent communications via the Microsoft Graph People API (read-only). Returns people objects with `displayName`, `emailAddresses`, `companyName`, `jobTitle`, and relevance metadata — ideal for "who is X?" or "who do I email about Y?" lookups. Use `manage-contact` action=`search` instead when you specifically need entries from your personal contact store only.',
-    annotations: {
-      title: 'People Search',
-      readOnlyHint: true,
-      // openWorldHint: returns directory/people data for external contacts
-      // (org directory + inferred from recent comms). (#92)
-      openWorldHint: true,
-    },
+      'Relevance-ranked search across personal contacts, organisation directory, and recent communications via the Microsoft Graph People API (read-only). Returns people objects with `displayName`, `emailAddresses`, `companyName`, `jobTitle`, and relevance metadata, for "who is X?" or "who do I email about Y?" lookups. For entries from your personal contact store only, use `manage-contact` action=`search`.',
+    ...toolMetadata('search-people', 'People Search'),
     inputSchema: {
       type: 'object',
       properties: {

package/email/attachments.js

@@ -3,14 +3,20 @@
  * Provides tools to list and download email attachments via Microsoft Graph API
  */
 const _https = require('https'); // Reserved for future use
-const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const _config = require('../config'); // Reserved for future use
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { buildMailboxPrefix } = require('../utils/mailbox');
-const { writeClaimedFile } = require('../utils/safe-write');
+const {
+  writeClaimedFile,
+  ensureOutputDir,
+  confineOutputPath,
+  OutputPathError,
+} = require('../utils/safe-write');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 const MAX_FILENAME_LENGTH = 200;
 
@@ -52,14 +58,7 @@ async function handleListAttachments(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Error: messageId is required',
-        },
-      ],
-    };
+    return toolError('Error: messageId is required');
   }
 
   try {
@@ -71,7 +70,7 @@ async function handleListAttachments(args) {
       $select: 'id,name,contentType,size,isInline',
     };
 
-    console.error(`Fetching attachments for message: ${messageId}`);
+    log.debug(`Fetching attachments for message: ${messageId}`);
     const response = await callGraphAPI(
       accessToken,
       'GET',
@@ -113,24 +112,10 @@ async function handleListAttachments(args) {
       error.message === 'Authentication required' ||
       error.message === 'UNAUTHORIZED'
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing attachments: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing attachments: ${error.message}`);
   }
 }
 
@@ -139,7 +124,7 @@ async function handleListAttachments(args) {
  * @param {object} args - Tool arguments
  * @param {string} args.messageId - The ID of the email message
  * @param {string} args.attachmentId - The ID of the attachment
- * @param {string} args.savePath - Optional path to save the file (defaults to current directory)
+ * @param {string} args.savePath - Deprecated alias for outputDir (absolute or ~/…; default: system temp directory)
  * @returns {object} - MCP response with download result
  */
 async function handleDownloadAttachment(args) {
@@ -152,14 +137,19 @@ async function handleDownloadAttachment(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId || !attachmentId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Error: Both messageId and attachmentId are required',
-        },
-      ],
-    };
+    return toolError('Error: Both messageId and attachmentId are required');
+  }
+
+  // Determine save location before fetching anything. F-19: default to
+  // os.tmpdir() instead of cwd so attachments don't silently land in the
+  // source tree when the caller forgets to pass outputDir. The directory
+  // must be inside an allowed base; write only to the resolved path.
+  let outputDir;
+  try {
+    outputDir = confineOutputPath(savePath || os.tmpdir());
+  } catch (error) {
+    if (!(error instanceof OutputPathError)) throw error;
+    return toolError(error.message, { nextStep: error.nextStep });
   }
 
   try {
@@ -167,7 +157,7 @@ async function handleDownloadAttachment(args) {
 
     // First, get attachment metadata to get the filename and content
     const metadataEndpoint = `${prefix}/messages/${messageId}/attachments/${attachmentId}`;
-    console.error(`Fetching attachment metadata: ${attachmentId}`);
+    log.debug(`Fetching attachment metadata: ${attachmentId}`);
 
     const metadata = await callGraphAPI(
       accessToken,
@@ -178,14 +168,7 @@ async function handleDownloadAttachment(args) {
     );
 
     if (!metadata) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'Error: Attachment not found',
-          },
-        ],
-      };
+      return toolError('Error: Attachment not found');
     }
 
     const filename = metadata.name || 'attachment';
@@ -196,24 +179,13 @@ async function handleDownloadAttachment(args) {
       const contentBytes = metadata.contentBytes;
 
       if (!contentBytes) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'Error: No content found in attachment',
-            },
-          ],
-        };
+        return toolError('Error: No content found in attachment');
       }
 
-      // Determine save location. F-19: default to os.tmpdir() instead
-      // of cwd so attachments don't silently land in the source tree
-      // when the caller forgets to pass outputDir. Auto-create the
-      // target directory.
+      // Auto-create the target directory.
       // The filename is sender-controlled (GHSA-755c-c45g-69rv): reduce it
       // to a safe basename and never overwrite or follow a symlink.
-      const outputDir = savePath || os.tmpdir();
-      fs.mkdirSync(outputDir, { recursive: true });
+      ensureOutputDir(outputDir);
 
       // Decode base64 and save to file
       const buffer = Buffer.from(contentBytes, 'base64');
@@ -239,14 +211,9 @@ async function handleDownloadAttachment(args) {
       };
     } else if (metadata['@odata.type'] === '#microsoft.graph.itemAttachment') {
       // Item attachments (embedded emails, calendar items) need different handling
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `This is an embedded item attachment (${metadata.name}). Item attachments cannot be downloaded as files directly. They contain embedded Outlook items like emails or calendar events.`,
-          },
-        ],
-      };
+      return toolError(
+        `This is an embedded item attachment (${metadata.name}). Item attachments cannot be downloaded as files directly. They contain embedded Outlook items like emails or calendar events.`
+      );
     } else if (
       metadata['@odata.type'] === '#microsoft.graph.referenceAttachment'
     ) {
@@ -260,38 +227,17 @@ async function handleDownloadAttachment(args) {
         ],
       };
     } else {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Unknown attachment type: ${metadata['@odata.type']}`,
-          },
-        ],
-      };
+      return toolError(`Unknown attachment type: ${metadata['@odata.type']}`);
     }
   } catch (error) {
     if (
       error.message === 'Authentication required' ||
       error.message === 'UNAUTHORIZED'
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error downloading attachment: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error downloading attachment: ${error.message}`);
   }
 }
 
@@ -307,33 +253,19 @@ async function handleGetAttachmentContent(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId || !attachmentId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Error: Both messageId and attachmentId are required',
-        },
-      ],
-    };
+    return toolError('Error: Both messageId and attachmentId are required');
   }
 
   try {
     const accessToken = await ensureAuthenticated();
 
     const endpoint = `${prefix}/messages/${messageId}/attachments/${attachmentId}`;
-    console.error(`Fetching attachment content: ${attachmentId}`);
+    log.debug(`Fetching attachment content: ${attachmentId}`);
 
     const response = await callGraphAPI(accessToken, 'GET', endpoint, null, {});
 
     if (!response) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'Error: Attachment not found',
-          },
-        ],
-      };
+      return toolError('Error: Attachment not found');
     }
 
     const filename = response.name || 'attachment';
@@ -371,7 +303,7 @@ async function handleGetAttachmentContent(args) {
         content: [
           {
             type: 'text',
-            text: `Attachment: ${filename}\nType: ${contentType}\nSize: ${sizeKB} KB\n\nThis is a binary file. Use 'download-attachment' to save it to disk.`,
+            text: `Attachment: ${filename}\nType: ${contentType}\nSize: ${sizeKB} KB\n\nThis is a binary file. Use \`attachments\` action=\`download\` to save it to disk.`,
           },
         ],
       };
@@ -390,24 +322,10 @@ async function handleGetAttachmentContent(args) {
       error.message === 'Authentication required' ||
       error.message === 'UNAUTHORIZED'
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting attachment content: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting attachment content: ${error.message}`);
   }
 }