apple-mail-mcp 2.8.2 → 2.8.3

package/build/utils/applescript.js

@@ -1,446 +0,0 @@
-/**
- * AppleScript Execution Utilities
- *
- * This module provides a safe interface for executing AppleScript commands
- * on macOS. It handles script execution, error capture, and result parsing.
- *
- * @module utils/applescript
- */
-import { execSync, spawnSync } from "child_process";
-/**
- * Default execution timeout for AppleScript commands in milliseconds.
- * 30 seconds is sufficient for most operations, including complex
- * searches on large mailboxes. Can be overridden per-call.
- */
-const DEFAULT_TIMEOUT_MS = 30000;
-/**
- * Maximum stdout/stderr buffer (bytes) for an osascript invocation.
- *
- * Node's `execSync` defaults to a 1 MB `maxBuffer`; exceeding it throws
- * `ENOBUFS`, which we surface as a failure and callers convert to `null`. Mail
- * operations routinely exceed 1 MB — `getRawSource` reads the entire raw MIME
- * (a 20 MB attachment is explicitly anticipated), `getMessageContent` returns
- * the full source, and large `search`/`list` result sets accumulate — so the
- * default silently breaks exactly the large / attachment-bearing messages where
- * it matters most (issue #27). Default to 64 MB; override with
- * `APPLE_MAIL_MCP_MAX_BUFFER` (bytes).
- */
-const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-/**
- * Resolve the osascript output buffer size, honoring the
- * `APPLE_MAIL_MCP_MAX_BUFFER` environment override (bytes).
- */
-function getMaxBuffer() {
-    const raw = process.env.APPLE_MAIL_MCP_MAX_BUFFER;
-    if (raw !== undefined) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0)
-            return n;
-    }
-    return DEFAULT_MAX_BUFFER_BYTES;
-}
-/**
- * Default retry configuration.
- * - 1 attempt means no retries (default behavior)
- * - Use maxRetries: 3 for exponential backoff with 1s/2s delays
- */
-const DEFAULT_MAX_RETRIES = 1;
-const DEFAULT_RETRY_DELAY_MS = 1000;
-/**
- * Check if debug/verbose logging is enabled.
- * Set DEBUG=1 or DEBUG=true or VERBOSE=1 to enable.
- */
-const isDebugEnabled = () => {
-    const debug = process.env.DEBUG;
-    const verbose = process.env.VERBOSE;
-    return debug === "1" || debug === "true" || verbose === "1" || verbose === "true";
-};
-/**
- * Log a debug message if debug mode is enabled.
- *
- * @param message - The message to log
- * @param data - Optional additional data to log
- */
-function debugLog(message, data) {
-    if (!isDebugEnabled())
-        return;
-    const timestamp = new Date().toISOString();
-    if (data !== undefined) {
-        console.error(`[DEBUG ${timestamp}] ${message}`, data);
-    }
-    else {
-        console.error(`[DEBUG ${timestamp}] ${message}`);
-    }
-}
-/**
- * Escapes a string for safe inclusion in a shell command.
- *
- * When passing AppleScript to osascript via shell, we need to handle
- * the interaction between shell quoting and AppleScript string literals.
- * This function escapes single quotes since we wrap the script in single quotes.
- *
- * @param script - The raw AppleScript code
- * @returns Shell-safe version of the script
- *
- * @example
- * // Input: tell app "Notes" to get note "Rob's Note"
- * // Output: tell app "Notes" to get note "Rob'\''s Note"
- */
-function escapeForShell(script) {
-    // Replace single quotes with: end quote, escaped quote, start quote
-    // This is the standard shell escaping pattern for single-quoted strings
-    return script.replace(/'/g, "'\\''");
-}
-/**
- * Headroom (ms) between the in-AppleScript `with timeout` and the outer
- * osascript process timeout. The script-level timeout must fire *first* so
- * Mail.app aborts the operation from inside its own AppleScript dispatch —
- * cleanly releasing the event queue — before Node SIGKILLs the osascript
- * process. Killing osascript alone does not stop work already dispatched into
- * Mail.app, which is what wedges Mail.app for subsequent calls (issue #11).
- */
-const SCRIPT_TIMEOUT_HEADROOM_MS = 5000;
-/**
- * Wraps a script body in an AppleScript `with timeout` block so any Apple
- * Event that honors timeouts (most Mail.app operations do) aborts cleanly
- * rather than holding Mail.app's single-threaded AppleScript dispatch queue
- * open indefinitely.
- *
- * The timeout is set a few seconds below the osascript process timeout so the
- * in-Mail abort wins the race against the outer process kill.
- *
- * @param script - The AppleScript body
- * @param processTimeoutMs - The outer osascript process timeout
- * @returns The script wrapped in `with timeout … end timeout`
- */
-function wrapWithTimeout(script, processTimeoutMs) {
-    const seconds = Math.max(1, Math.ceil((processTimeoutMs - SCRIPT_TIMEOUT_HEADROOM_MS) / 1000));
-    return `with timeout of ${seconds} seconds\n${script}\nend timeout`;
-}
-/**
- * Checks if an error is a timeout error from execSync.
- *
- * Node.js throws errors with specific properties when a child process
- * is killed due to timeout.
- *
- * @param error - The caught error object
- * @returns True if this was a timeout error
- */
-function isTimeoutError(error) {
-    if (error instanceof Error) {
-        const execError = error;
-        // executeAppleScript kills a timed-out osascript with SIGKILL; execSync also
-        // sets killed=true on its own timeout. Treat any killed osascript
-        // (SIGTERM/SIGKILL) as a timeout/abnormal exit rather than leaking the raw
-        // "Command failed" string downstream.
-        return (execError.killed === true || execError.signal === "SIGTERM" || execError.signal === "SIGKILL");
-    }
-    return false;
-}
-/**
- * Error patterns that indicate transient failures worth retrying.
- * These typically occur when Mail.app is busy or temporarily unresponsive.
- */
-const RETRYABLE_ERROR_PATTERNS = [
-    /timed? out/i,
-    /not responding/i,
-    /connection.*invalid/i,
-    /lost connection/i,
-    /busy/i,
-];
-/**
- * Checks if an error message indicates a transient failure that should be retried.
- *
- * @param errorMessage - The error message to check
- * @returns True if this error is worth retrying
- */
-function isRetryableError(errorMessage) {
-    return RETRYABLE_ERROR_PATTERNS.some((pattern) => pattern.test(errorMessage));
-}
-/**
- * Synchronous sleep using the system's sleep command.
- * Used between retry attempts for exponential backoff.
- *
- * This is more efficient than a busy-wait loop as it doesn't
- * consume CPU cycles during the delay.
- *
- * Uses spawnSync instead of execSync to avoid interference with
- * execSync mocks in tests.
- *
- * @param ms - Milliseconds to sleep
- */
-function sleep(ms) {
-    // Use system sleep command with fractional seconds support
-    // This avoids CPU-spinning busy wait while keeping the code synchronous
-    const seconds = ms / 1000;
-    const result = spawnSync("sleep", [seconds.toString()], { stdio: "ignore" });
-    if (result.error) {
-        // Fallback to busy-wait if sleep command fails (shouldn't happen on macOS)
-        const end = Date.now() + ms;
-        while (Date.now() < end) {
-            // Busy wait fallback
-        }
-    }
-}
-/**
- * User-friendly error messages mapped from common AppleScript errors.
- * Each entry maps a pattern (regex or string) to a user-friendly message.
- */
-const ERROR_MAPPINGS = [
-    // Permission errors
-    {
-        pattern: /not authorized|not permitted|access.*denied/i,
-        message: "Permission denied. Grant automation access in System Preferences > Privacy & Security > Automation.",
-    },
-    // Application not running
-    {
-        pattern: /application isn't running|not running/i,
-        message: "Mail.app is not responding. Try opening Mail.app manually.",
-    },
-    // Connection errors
-    {
-        pattern: /connection is invalid|lost connection/i,
-        message: "Lost connection to Mail.app. The app may have crashed or been restarted.",
-    },
-    // Message not found
-    {
-        pattern: /can't get message/i,
-        message: "Message not found. The message may have been deleted or moved.",
-    },
-    // Mailbox not found
-    {
-        pattern: /can't get mailbox "([^"]+)"/i,
-        message: 'Mailbox "$1" not found. Use list-mailboxes to see available mailboxes.',
-    },
-    // Account not found
-    {
-        pattern: /can't get account "([^"]+)"/i,
-        message: 'Account "$1" not found. Use list-accounts to see available accounts.',
-    },
-    // Send failed
-    {
-        pattern: /couldn't send|send failed|cannot send/i,
-        message: "Failed to send email. Check your network connection and Mail.app settings.",
-    },
-    // Offline
-    {
-        pattern: /offline|no connection/i,
-        message: "Mail.app is offline. Check your network connection.",
-    },
-    // Cannot delete (various reasons)
-    {
-        pattern: /can't delete|cannot delete/i,
-        message: "Cannot delete. The message may be locked or in use.",
-    },
-    // Syntax/script errors (usually programming bugs)
-    {
-        pattern: /syntax error|expected/i,
-        message: "Internal error. Please report this issue.",
-    },
-];
-/**
- * Parses error output from osascript to extract meaningful error messages.
- *
- * osascript errors typically include execution error numbers and descriptions.
- * This function attempts to extract the human-readable portion and map it
- * to a user-friendly message with helpful suggestions.
- *
- * @param errorOutput - Raw error string from execSync
- * @returns User-friendly error message with suggested action
- */
-function parseErrorMessage(errorOutput) {
-    // First, extract the core error message from AppleScript format
-    let coreError = errorOutput;
-    // Check for execution error format: "execution error: Message (-1234)"
-    const executionError = errorOutput.match(/execution error: (.+?)(?:\s*\(-?\d+\))?$/m);
-    if (executionError) {
-        coreError = executionError[1].trim();
-    }
-    // Try to match against known error patterns for user-friendly messages
-    for (const { pattern, message } of ERROR_MAPPINGS) {
-        const match = coreError.match(pattern);
-        if (match) {
-            // Replace $1, $2, etc. with captured groups
-            let result = message;
-            for (let i = 1; i < match.length; i++) {
-                result = result.replace(`$${i}`, match[i] || "");
-            }
-            return result;
-        }
-    }
-    // Fall back to basic "Can't get X" parsing
-    const notFoundError = coreError.match(/Can't get (.+?)\./);
-    if (notFoundError) {
-        return `Not found: ${notFoundError[1]}`;
-    }
-    // Never leak Node's raw `Command failed: osascript -e '<entire script>'` to the
-    // user — it means osascript exited abnormally with no parseable AppleScript
-    // error (killed under load, Mail.app relaunching, or Automation denied).
-    if (/^Command failed:\s*osascript/.test(coreError.trim())) {
-        return ("Mail.app scripting failed (osascript exited abnormally). Mail may be " +
-            "unresponsive or relaunching, or Automation permission was denied — check " +
-            "System Settings > Privacy & Security > Automation, and try again.");
-    }
-    // Return cleaned version of original error
-    return coreError.trim() || "Unknown AppleScript error";
-}
-/**
- * Executes an AppleScript command and returns a structured result.
- *
- * This function serves as the bridge between TypeScript and macOS AppleScript.
- * It handles the complexity of shell escaping, execution, and error handling
- * so that calling code can work with clean TypeScript interfaces.
- *
- * The script is executed synchronously via the `osascript` command-line tool.
- * Multi-line scripts are supported and preserved (important for AppleScript
- * tell blocks and repeat loops).
- *
- * @param script - The AppleScript code to execute
- * @param options - Optional execution settings (timeout, etc.)
- * @returns A result object with success status and output or error message
- *
- * @example
- * ```typescript
- * // Basic usage with default timeout (30 seconds)
- * const result = executeAppleScript(`
- *   tell application "Notes"
- *     get name of every note
- *   end tell
- * `);
- *
- * // With custom timeout for complex operations
- * const result = executeAppleScript(complexScript, { timeoutMs: 60000 });
- *
- * if (result.success) {
- *   console.log("Notes:", result.output);
- * } else {
- *   console.error("Failed:", result.error);
- * }
- * ```
- */
-export function executeAppleScript(script, options = {}) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
-    // Validate input - empty scripts are likely programmer errors
-    if (!script || !script.trim()) {
-        return {
-            success: false,
-            output: "",
-            error: "Cannot execute empty AppleScript",
-        };
-    }
-    // Prepare the script:
-    // 1. Trim leading/trailing whitespace (cosmetic)
-    // 2. Preserve internal newlines (required for AppleScript syntax)
-    // 3. Wrap in `with timeout` so a stuck Mail.app operation aborts from
-    //    inside its own dispatch before the process timeout kills osascript (#11)
-    // 4. Escape for shell execution
-    const preparedScript = escapeForShell(wrapWithTimeout(script.trim(), timeoutMs));
-    // Build the osascript command
-    // We use single quotes to wrap the script, which is why we escape
-    // single quotes within the script itself
-    const command = `osascript -e '${preparedScript}'`;
-    // Debug: Log the script being executed
-    debugLog("Executing AppleScript", {
-        scriptPreview: script.trim().substring(0, 200) + (script.length > 200 ? "..." : ""),
-        timeout: timeoutMs,
-        maxRetries,
-    });
-    let lastError = null;
-    const startTime = Date.now();
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        const attemptStart = Date.now();
-        try {
-            // Execute synchronously - MCP tools are inherently synchronous
-            // and Apple Notes operations are fast enough that async isn't needed
-            const output = execSync(command, {
-                encoding: "utf8",
-                timeout: timeoutMs,
-                // SIGKILL (not the default SIGTERM): a wedged osascript blocked on an
-                // unresponsive Mail.app can ignore SIGTERM, leaking processes that pile
-                // up and worsen the contention. SIGKILL guarantees the process is reaped
-                // when the timeout fires. (#11)
-                killSignal: "SIGKILL",
-                // Raise the output cap well above Node's 1 MB default so large message
-                // sources / attachment payloads aren't truncated into an ENOBUFS
-                // failure. (#27)
-                maxBuffer: getMaxBuffer(),
-                // Capture stderr separately to get error details
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            const duration = Date.now() - attemptStart;
-            debugLog("AppleScript succeeded", {
-                attempt,
-                duration: `${duration}ms`,
-                outputLength: output.length,
-                outputPreview: output.substring(0, 100) + (output.length > 100 ? "..." : ""),
-            });
-            return {
-                success: true,
-                output: output.trim(),
-            };
-        }
-        catch (error) {
-            // execSync throws on non-zero exit codes
-            // The error object contains stderr output with AppleScript error details
-            const attemptDuration = Date.now() - attemptStart;
-            let errorMessage;
-            let isTimeout = false;
-            let rawError;
-            // Check for timeout first - provide specific message
-            if (isTimeoutError(error)) {
-                isTimeout = true;
-                const timeoutSecs = Math.round(timeoutMs / 1000);
-                errorMessage = `Operation timed out after ${timeoutSecs} seconds. Mail.app may be unresponsive or the operation involves too many messages.`;
-            }
-            else if (error instanceof Error) {
-                rawError = error.message;
-                // Node's ExecException includes stderr in the message
-                errorMessage = parseErrorMessage(error.message);
-            }
-            else if (typeof error === "string") {
-                rawError = error;
-                errorMessage = parseErrorMessage(error);
-            }
-            else {
-                errorMessage = "AppleScript execution failed with unknown error";
-            }
-            // Debug: Log error details
-            debugLog("AppleScript failed", {
-                attempt,
-                duration: `${attemptDuration}ms`,
-                totalElapsed: `${Date.now() - startTime}ms`,
-                isTimeout,
-                errorMessage,
-                rawError: rawError?.substring(0, 500),
-            });
-            lastError = {
-                success: false,
-                output: "",
-                error: errorMessage,
-            };
-            // Check if we should retry
-            const canRetry = isTimeout || isRetryableError(errorMessage);
-            const hasAttemptsLeft = attempt < maxRetries;
-            if (canRetry && hasAttemptsLeft) {
-                const delayMs = retryDelayMs * Math.pow(2, attempt - 1);
-                console.error(`AppleScript retry: Attempt ${attempt}/${maxRetries} failed with "${errorMessage}". Retrying in ${delayMs}ms...`);
-                sleep(delayMs);
-                // Continue to next attempt
-            }
-            else {
-                // Log final error and return
-                if (isTimeout) {
-                    console.error(`AppleScript timeout: ${errorMessage}`);
-                }
-                else {
-                    console.error(`AppleScript error: ${errorMessage}`);
-                }
-                return lastError;
-            }
-        }
-    }
-    // Return the last error (all retries exhausted - shouldn't reach here normally)
-    return lastError;
-}

package/build/utils/attachmentMaterialize.d.ts

@@ -1,9 +0,0 @@
-import type { AttachmentInput } from "../types.js";
-export interface MaterializedAttachments {
-    /** Absolute file paths ready to hand to the AppleScript attachment builder. */
-    paths: string[];
-    /** Remove any temp files created; safe to call always. */
-    cleanup: () => void;
-}
-export declare function materializeAttachments(attachments?: AttachmentInput[]): MaterializedAttachments;
-//# sourceMappingURL=attachmentMaterialize.d.ts.map

package/build/utils/attachmentMaterialize.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"attachmentMaterialize.d.ts","sourceRoot":"","sources":["../../src/utils/attachmentMaterialize.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,sBAAsB,CAAC,WAAW,CAAC,EAAE,eAAe,EAAE,GAAG,uBAAuB,CAsB/F"}

package/build/utils/attachmentMaterialize.js

@@ -1,38 +0,0 @@
-/**
- * Materialize inline (base64) attachments to temp files (B4).
- *
- * The AppleScript send/draft path attaches files by POSIX path, so inline
- * base64 content is written to a throwaway temp dir first and cleaned up after
- * the operation. Plain string entries (existing absolute paths) pass through.
- *
- * @module utils/attachmentMaterialize
- */
-import { writeFileSync, rmSync, mkdtempSync } from "fs";
-import { join } from "path";
-import { tmpdir } from "os";
-export function materializeAttachments(attachments) {
-    if (!attachments || attachments.length === 0) {
-        return { paths: [], cleanup: () => undefined };
-    }
-    let dir = null;
-    const paths = attachments.map((a) => {
-        if (typeof a === "string")
-            return a;
-        if (!a.filename || !a.contentBase64) {
-            throw new Error("Inline attachment requires both filename and contentBase64.");
-        }
-        if (!dir)
-            dir = mkdtempSync(join(tmpdir(), "amcp-att-"));
-        const safeName = a.filename.replace(/[/\\]/g, "_");
-        const p = join(dir, safeName);
-        writeFileSync(p, Buffer.from(a.contentBase64, "base64"));
-        return p;
-    });
-    return {
-        paths,
-        cleanup: () => {
-            if (dir)
-                rmSync(dir, { recursive: true, force: true });
-        },
-    };
-}

package/build/utils/mimeParse.d.ts

@@ -1,62 +0,0 @@
-/**
- * MIME Source Parser for Attachment Extraction
- *
- * Parses raw email MIME source to extract attachment metadata and content.
- * Used as a fallback when AppleScript's `mail attachments` returns empty
- * (which happens across all account types: iCloud, Google, Exchange).
- *
- * @module utils/mimeParse
- */
-export interface MimeAttachmentInfo {
-    /** Filename from Content-Disposition or Content-Type name parameter */
-    name: string;
-    /** MIME type from Content-Type header */
-    mimeType: string;
-    /** Size in bytes from Content-Disposition size parameter, or estimated from body */
-    size: number;
-}
-export interface MimeAttachmentData extends MimeAttachmentInfo {
-    /** Decoded binary content */
-    data: Buffer;
-}
-/**
- * Parse MIME source and return metadata for all file attachments.
- * Skips inline dispositions (signature images, etc.). Descends into
- * nested multipart/* containers.
- *
- * @param source - Raw MIME source of the email
- * @returns Array of attachment metadata (name, mimeType, size)
- */
-export declare function parseMimeAttachments(source: string): MimeAttachmentInfo[];
-/**
- * Extract the decoded `text/html` body from raw MIME source.
- *
- * Used by get-message's `preferHtml` path so it returns the actual HTML body
- * rather than the entire raw MIME blob (headers + base64 attachments), which is
- * both wrong and enormous (#32). Handles both multipart messages (walks leaf
- * parts, descending into nested multipart/* containers) and a non-multipart
- * message whose top-level Content-Type is text/html. Bodies are decoded per
- * Content-Transfer-Encoding (base64 / quoted-printable / raw) and returned as
- * UTF-8 text.
- *
- * @param source - Raw MIME source of the email
- * @returns The decoded HTML body, or null if the message has no text/html part
- */
-export declare function extractHtmlBody(source: string): string | null;
-/**
- * Extract the decoded `text/plain` body from raw MIME source. Mirror of
- * extractHtmlBody; used by the IMAP get-message path (#43 Phase 3) to render a
- * message fetched by UID. Returns null when there's no text/plain part.
- */
-export declare function extractTextBody(source: string): string | null;
-/**
- * Extract and decode a specific attachment from MIME source by filename.
- * Supports base64, quoted-printable, and 7bit/8bit/binary transfer encodings.
- * Descends into nested multipart/* containers.
- *
- * @param source - Raw MIME source of the email
- * @param attachmentName - Filename to extract
- * @returns Decoded attachment data, or null if not found
- */
-export declare function extractMimeAttachment(source: string, attachmentName: string): MimeAttachmentData | null;
-//# sourceMappingURL=mimeParse.d.ts.map

package/build/utils/mimeParse.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mimeParse.d.ts","sourceRoot":"","sources":["../../src/utils/mimeParse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAqMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAyBzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,kBAAkB,GAAG,IAAI,CAwB3B"}