apple-pim-cli 3.0.0

package/lib/cli-runner.js

@@ -0,0 +1,98 @@
+import { spawn } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
+import { homedir } from "os";
+
+/**
+ * Locate Swift CLI binaries by checking multiple locations in order.
+ * @param {string[]} extraLocations - Additional directories to check first.
+ * @returns {string} Path to the directory containing CLI binaries.
+ */
+export function findSwiftBinDir(extraLocations = []) {
+  const locations = [
+    ...extraLocations,
+    // ~/.local/bin (setup.sh --install target)
+    join(homedir(), ".local", "bin"),
+  ];
+
+  for (const loc of locations) {
+    if (existsSync(join(loc, "calendar-cli"))) {
+      return loc;
+    }
+  }
+
+  // Return first location as default (will fail with helpful error)
+  return locations[0];
+}
+
+/**
+ * Helper to calculate relative date string from days offset.
+ * @param {number} daysOffset - Number of days to offset from today.
+ * @returns {string} Date in YYYY-MM-DD format.
+ */
+export function relativeDateString(daysOffset) {
+  const date = new Date();
+  date.setDate(date.getDate() + daysOffset);
+  return date.toISOString().split("T")[0];
+}
+
+/** Default timeout for CLI execution (30 seconds). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Factory: creates a runCLI function bound to a specific binary directory.
+ * @param {string} binDir - Directory containing the Swift CLI binaries.
+ * @param {Object} envOverrides - Extra env vars to pass to every spawn call.
+ * @param {{ timeoutMs?: number }} options - Options (e.g. timeout).
+ * @returns {{ runCLI: (cli: string, args: string[]) => Promise<object> }}
+ */
+export function createCLIRunner(binDir, envOverrides = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  async function runCLI(cli, args) {
+    return new Promise((resolve, reject) => {
+      const cliPath = join(binDir, cli);
+      const proc = spawn(cliPath, args, {
+        env: { ...process.env, ...envOverrides },
+      });
+
+      let stdout = "";
+      let stderr = "";
+      let killed = false;
+
+      const timer = setTimeout(() => {
+        killed = true;
+        proc.kill("SIGTERM");
+        reject(new Error(`CLI timed out after ${timeoutMs}ms: ${cli} ${args.join(" ")}`));
+      }, timeoutMs);
+
+      proc.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        clearTimeout(timer);
+        if (killed) return; // already rejected by timeout
+        if (code === 0) {
+          try {
+            resolve(JSON.parse(stdout));
+          } catch {
+            resolve({ success: true, output: stdout });
+          }
+        } else {
+          reject(new Error(stderr || `CLI exited with code ${code}`));
+        }
+      });
+
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        if (killed) return;
+        reject(new Error(`Failed to run CLI: ${err.message}`));
+      });
+    });
+  }
+
+  return { runCLI };
+}

package/lib/handlers/apple-pim.js

@@ -0,0 +1,101 @@
+export async function handleApplePim(args, runCLI) {
+  switch (args.action) {
+    case "status": {
+      const status = {};
+      const domains = [
+        { name: "calendars", cli: "calendar-cli" },
+        { name: "reminders", cli: "reminder-cli" },
+        { name: "contacts", cli: "contacts-cli" },
+        { name: "mail", cli: "mail-cli" },
+      ];
+
+      const statusMessages = {
+        authorized: "Full access granted",
+        notDetermined: "Permission not yet requested. Run authorize to prompt.",
+        denied: "Access denied. Enable in System Settings > Privacy & Security.",
+        restricted: "Access restricted by system policy (MDM or parental controls).",
+        writeOnly: "Write-only access. Upgrade in System Settings > Privacy & Security.",
+        unavailable: "Not available",
+      };
+
+      for (const domain of domains) {
+        try {
+          const result = await runCLI(domain.cli, ["auth-status"]);
+          const auth = result.authorization || "unknown";
+          status[domain.name] = {
+            enabled: true,
+            authorization: auth,
+            message: result.message || statusMessages[auth] || `Status: ${auth}`,
+          };
+        } catch (err) {
+          status[domain.name] = {
+            enabled: false,
+            authorization: "error",
+            message: err.message,
+          };
+        }
+      }
+
+      return { status };
+    }
+
+    case "authorize": {
+      const targetDomain = args.domain;
+      const results = {};
+      const domains = [
+        { name: "calendars", cli: "calendar-cli", args: ["list"] },
+        { name: "reminders", cli: "reminder-cli", args: ["lists"] },
+        { name: "contacts", cli: "contacts-cli", args: ["groups"] },
+        { name: "mail", cli: "mail-cli", args: ["accounts"] },
+      ];
+
+      const toAuthorize = targetDomain
+        ? domains.filter((d) => d.name === targetDomain)
+        : domains;
+
+      for (const domain of toAuthorize) {
+        try {
+          await runCLI(domain.cli, domain.args);
+          results[domain.name] = { success: true, message: "Access authorized" };
+        } catch (err) {
+          const msg = err.message.toLowerCase();
+          if (msg.includes("denied") || msg.includes("not granted")) {
+            results[domain.name] = {
+              success: false,
+              message:
+                "Access denied. The user must manually enable access:\n" +
+                "1. Open System Settings > Privacy & Security\n" +
+                `2. Find the ${domain.name === "mail" ? "Automation" : domain.name.charAt(0).toUpperCase() + domain.name.slice(1)} section\n` +
+                "3. Enable access for the terminal application\n" +
+                "4. Restart the terminal and try again",
+            };
+          } else if (msg.includes("not running") && domain.name === "mail") {
+            results[domain.name] = {
+              success: false,
+              message: "Mail.app must be running before authorization can be requested.",
+            };
+          } else {
+            results[domain.name] = { success: false, message: err.message };
+          }
+        }
+      }
+
+      return { results };
+    }
+
+    case "config_show": {
+      const configArgs = ["config", "show"];
+      if (args.profile) configArgs.push("--profile", args.profile);
+      return await runCLI("calendar-cli", configArgs);
+    }
+
+    case "config_init": {
+      const configArgs = ["config", "init"];
+      if (args.profile) configArgs.push("--profile", args.profile);
+      return await runCLI("calendar-cli", configArgs);
+    }
+
+    default:
+      throw new Error(`Unknown apple-pim action: ${args.action}`);
+  }
+}

package/lib/handlers/calendar.js

@@ -0,0 +1,69 @@
+import { relativeDateString } from "../cli-runner.js";
+import {
+  buildCalendarCreateArgs,
+  buildCalendarDeleteArgs,
+  buildCalendarUpdateArgs,
+} from "../tool-args.js";
+
+export async function handleCalendar(args, runCLI) {
+  const cliArgs = [];
+
+  switch (args.action) {
+    case "list":
+      return await runCLI("calendar-cli", ["list"]);
+
+    case "events":
+      cliArgs.push("events");
+      if (args.calendar) cliArgs.push("--calendar", args.calendar);
+      if (args.lastDays !== undefined) {
+        cliArgs.push("--from", relativeDateString(-args.lastDays));
+      } else if (args.from) {
+        cliArgs.push("--from", args.from);
+      }
+      if (args.nextDays !== undefined) {
+        cliArgs.push("--to", relativeDateString(args.nextDays));
+      } else if (args.to) {
+        cliArgs.push("--to", args.to);
+      }
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("calendar-cli", cliArgs);
+
+    case "get":
+      if (!args.id) throw new Error("Event ID is required for calendar get");
+      return await runCLI("calendar-cli", ["get", "--id", args.id]);
+
+    case "search":
+      if (!args.query) throw new Error("Search query is required for calendar search");
+      cliArgs.push("search", args.query);
+      if (args.calendar) cliArgs.push("--calendar", args.calendar);
+      if (args.from) cliArgs.push("--from", args.from);
+      if (args.to) cliArgs.push("--to", args.to);
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("calendar-cli", cliArgs);
+
+    case "create":
+      return await runCLI(
+        "calendar-cli",
+        buildCalendarCreateArgs(args, args.calendar)
+      );
+
+    case "update":
+      return await runCLI("calendar-cli", buildCalendarUpdateArgs(args));
+
+    case "delete":
+      return await runCLI("calendar-cli", buildCalendarDeleteArgs(args));
+
+    case "batch_create":
+      if (!args.events || !Array.isArray(args.events) || args.events.length === 0) {
+        throw new Error("Events array is required and cannot be empty");
+      }
+      return await runCLI("calendar-cli", [
+        "batch-create",
+        "--json",
+        JSON.stringify(args.events),
+      ]);
+
+    default:
+      throw new Error(`Unknown calendar action: ${args.action}`);
+  }
+}

package/lib/handlers/contact.js

@@ -0,0 +1,42 @@
+import {
+  buildContactCreateArgs,
+  buildContactUpdateArgs,
+} from "../tool-args.js";
+
+export async function handleContact(args, runCLI) {
+  const cliArgs = [];
+
+  switch (args.action) {
+    case "groups":
+      return await runCLI("contacts-cli", ["groups"]);
+
+    case "list":
+      cliArgs.push("list");
+      if (args.group) cliArgs.push("--group", args.group);
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("contacts-cli", cliArgs);
+
+    case "search":
+      if (!args.query) throw new Error("Search query is required for contact search");
+      cliArgs.push("search", args.query);
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("contacts-cli", cliArgs);
+
+    case "get":
+      if (!args.id) throw new Error("Contact ID is required for contact get");
+      return await runCLI("contacts-cli", ["get", "--id", args.id]);
+
+    case "create":
+      return await runCLI("contacts-cli", buildContactCreateArgs(args));
+
+    case "update":
+      return await runCLI("contacts-cli", buildContactUpdateArgs(args));
+
+    case "delete":
+      if (!args.id) throw new Error("Contact ID is required for contact delete");
+      return await runCLI("contacts-cli", ["delete", "--id", args.id]);
+
+    default:
+      throw new Error(`Unknown contact action: ${args.action}`);
+  }
+}

package/lib/handlers/mail.js

@@ -0,0 +1,101 @@
+import { formatMailGetResult } from "../mail-format.js";
+
+export async function handleMail(args, runCLI) {
+  const cliArgs = [];
+
+  switch (args.action) {
+    case "accounts":
+      return await runCLI("mail-cli", ["accounts"]);
+
+    case "mailboxes":
+      cliArgs.push("mailboxes");
+      if (args.account) cliArgs.push("--account", args.account);
+      return await runCLI("mail-cli", cliArgs);
+
+    case "messages":
+      cliArgs.push("messages");
+      if (args.mailbox) cliArgs.push("--mailbox", args.mailbox);
+      if (args.account) cliArgs.push("--account", args.account);
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      if (args.filter) cliArgs.push("--filter", args.filter);
+      return await runCLI("mail-cli", cliArgs);
+
+    case "get": {
+      if (!args.id) throw new Error("Message ID is required for mail get");
+      const getArgs = ["get", "--id", args.id];
+      if (args.mailbox) getArgs.push("--mailbox", args.mailbox);
+      if (args.account) getArgs.push("--account", args.account);
+      if (args.format === "markdown") getArgs.push("--include-source");
+      const result = await runCLI("mail-cli", getArgs);
+      return await formatMailGetResult(result, args.format || "plain");
+    }
+
+    case "search":
+      if (!args.query) throw new Error("Search query is required for mail search");
+      cliArgs.push("search", args.query);
+      if (args.field) cliArgs.push("--field", args.field);
+      if (args.mailbox) cliArgs.push("--mailbox", args.mailbox);
+      if (args.account) cliArgs.push("--account", args.account);
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("mail-cli", cliArgs);
+
+    case "update": {
+      if (!args.id) throw new Error("Message ID is required for mail update");
+      const updateArgs = ["update", "--id", args.id];
+      if (args.read !== undefined) updateArgs.push("--read", String(args.read));
+      if (args.flagged !== undefined) updateArgs.push("--flagged", String(args.flagged));
+      if (args.junk !== undefined) updateArgs.push("--junk", String(args.junk));
+      if (args.mailbox) updateArgs.push("--mailbox", args.mailbox);
+      if (args.account) updateArgs.push("--account", args.account);
+      return await runCLI("mail-cli", updateArgs);
+    }
+
+    case "move": {
+      if (!args.id) throw new Error("Message ID is required for mail move");
+      if (!args.toMailbox) throw new Error("Target mailbox (toMailbox) is required for mail move");
+      const moveArgs = ["move", "--id", args.id, "--to-mailbox", args.toMailbox];
+      if (args.toAccount) moveArgs.push("--to-account", args.toAccount);
+      if (args.mailbox) moveArgs.push("--mailbox", args.mailbox);
+      if (args.account) moveArgs.push("--account", args.account);
+      return await runCLI("mail-cli", moveArgs);
+    }
+
+    case "delete": {
+      if (!args.id) throw new Error("Message ID is required for mail delete");
+      const delArgs = ["delete", "--id", args.id];
+      if (args.mailbox) delArgs.push("--mailbox", args.mailbox);
+      if (args.account) delArgs.push("--account", args.account);
+      return await runCLI("mail-cli", delArgs);
+    }
+
+    case "batch_update": {
+      if (!args.ids || !Array.isArray(args.ids) || args.ids.length === 0) {
+        throw new Error("IDs array is required and cannot be empty");
+      }
+      const updates = args.ids.map((id) => {
+        const obj = { id };
+        if (args.read !== undefined) obj.read = args.read;
+        if (args.flagged !== undefined) obj.flagged = args.flagged;
+        if (args.junk !== undefined) obj.junk = args.junk;
+        return obj;
+      });
+      const batchArgs = ["batch-update", "--json", JSON.stringify(updates)];
+      if (args.mailbox) batchArgs.push("--mailbox", args.mailbox);
+      if (args.account) batchArgs.push("--account", args.account);
+      return await runCLI("mail-cli", batchArgs);
+    }
+
+    case "batch_delete": {
+      if (!args.ids || !Array.isArray(args.ids) || args.ids.length === 0) {
+        throw new Error("IDs array is required and cannot be empty");
+      }
+      const batchArgs = ["batch-delete", "--json", JSON.stringify(args.ids)];
+      if (args.mailbox) batchArgs.push("--mailbox", args.mailbox);
+      if (args.account) batchArgs.push("--account", args.account);
+      return await runCLI("mail-cli", batchArgs);
+    }
+
+    default:
+      throw new Error(`Unknown mail action: ${args.action}`);
+  }
+}

package/lib/handlers/reminder.js

@@ -0,0 +1,83 @@
+import {
+  buildReminderCreateArgs,
+  buildReminderUpdateArgs,
+} from "../tool-args.js";
+
+export async function handleReminder(args, runCLI) {
+  const cliArgs = [];
+
+  switch (args.action) {
+    case "lists":
+      return await runCLI("reminder-cli", ["lists"]);
+
+    case "items":
+      cliArgs.push("items");
+      if (args.list) cliArgs.push("--list", args.list);
+      if (args.filter) cliArgs.push("--filter", args.filter);
+      if (!args.filter && args.completed) cliArgs.push("--completed");
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("reminder-cli", cliArgs);
+
+    case "get":
+      if (!args.id) throw new Error("Reminder ID is required for reminder get");
+      return await runCLI("reminder-cli", ["get", "--id", args.id]);
+
+    case "search":
+      if (!args.query) throw new Error("Search query is required for reminder search");
+      cliArgs.push("search", args.query);
+      if (args.list) cliArgs.push("--list", args.list);
+      if (args.completed) cliArgs.push("--completed");
+      if (args.limit) cliArgs.push("--limit", String(args.limit));
+      return await runCLI("reminder-cli", cliArgs);
+
+    case "create":
+      return await runCLI(
+        "reminder-cli",
+        buildReminderCreateArgs(args, args.list)
+      );
+
+    case "complete":
+      if (!args.id) throw new Error("Reminder ID is required for reminder complete");
+      cliArgs.push("complete", "--id", args.id);
+      if (args.undo) cliArgs.push("--undo");
+      return await runCLI("reminder-cli", cliArgs);
+
+    case "update":
+      return await runCLI("reminder-cli", buildReminderUpdateArgs(args));
+
+    case "delete":
+      if (!args.id) throw new Error("Reminder ID is required for reminder delete");
+      return await runCLI("reminder-cli", ["delete", "--id", args.id]);
+
+    case "batch_create":
+      if (!args.reminders || !Array.isArray(args.reminders) || args.reminders.length === 0) {
+        throw new Error("Reminders array is required and cannot be empty");
+      }
+      return await runCLI("reminder-cli", [
+        "batch-create",
+        "--json",
+        JSON.stringify(args.reminders),
+      ]);
+
+    case "batch_complete":
+      if (!args.ids || !Array.isArray(args.ids) || args.ids.length === 0) {
+        throw new Error("IDs array is required and cannot be empty");
+      }
+      cliArgs.push("batch-complete", "--json", JSON.stringify(args.ids));
+      if (args.undo) cliArgs.push("--undo");
+      return await runCLI("reminder-cli", cliArgs);
+
+    case "batch_delete":
+      if (!args.ids || !Array.isArray(args.ids) || args.ids.length === 0) {
+        throw new Error("IDs array is required and cannot be empty");
+      }
+      return await runCLI("reminder-cli", [
+        "batch-delete",
+        "--json",
+        JSON.stringify(args.ids),
+      ]);
+
+    default:
+      throw new Error(`Unknown reminder action: ${args.action}`);
+  }
+}

package/lib/mail-format.js

@@ -0,0 +1,65 @@
+import { simpleParser } from "mailparser";
+import TurndownService from "turndown";
+
+const turndown = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  emDelimiter: "_",
+});
+
+function normalizeMarkdown(markdown) {
+  return markdown
+    .replace(/\r\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export async function markdownFromEmailSource(source) {
+  const parsed = await simpleParser(source);
+
+  if (parsed.html) {
+    return normalizeMarkdown(turndown.turndown(parsed.html));
+  }
+
+  if (parsed.textAsHtml) {
+    return normalizeMarkdown(turndown.turndown(parsed.textAsHtml));
+  }
+
+  if (parsed.text) {
+    return normalizeMarkdown(parsed.text);
+  }
+
+  return "";
+}
+
+export async function formatMailGetResult(result, format) {
+  if (format !== "markdown") return result;
+
+  const message = result?.message;
+  if (!message || typeof message !== "object") return result;
+
+  let markdown = "";
+  if (typeof message.source === "string" && message.source.trim().length > 0) {
+    try {
+      markdown = await markdownFromEmailSource(message.source);
+    } catch {
+      // Fall back to Mail.app plain-text extraction if MIME parsing fails.
+      markdown = "";
+    }
+  }
+
+  if (!markdown && typeof message.content === "string") {
+    markdown = normalizeMarkdown(message.content);
+  }
+
+  return {
+    ...result,
+    message: {
+      ...message,
+      content: markdown,
+      contentFormat: "markdown",
+      // Source is only needed for conversion, not for normal tool output.
+      source: undefined,
+    },
+  };
+}