apple-tools-mcp 1.2.1 → 2.0.1

package/indexer.js

@@ -1741,7 +1741,9 @@ export function localDayToMacBounds(startMs, endMs) {
 }
 
 // Date-bounded OccurrenceCache query: one row per occurrence, no GROUP BY ci.ROWID
-export function buildEventsOnDateQuery(startMac, endMac) {
+// includeUid adds the iCal UID that the calendar write tools address events by.
+// Older Calendar schemas may lack the column, so callers can retry without it.
+export function buildEventsOnDateQuery(startMac, endMac, { includeUid = true } = {}) {
   const startBound = Math.floor(Number(startMac));
   const endBound = Math.floor(Number(endMac));
   if (!Number.isFinite(startBound) || !Number.isFinite(endBound)) {
@@ -1755,6 +1757,7 @@ export function buildEventsOnDateQuery(startMac, endMac) {
   return `
       SELECT DISTINCT
         ci.ROWID as itemId,
+        ${includeUid ? "ci.unique_identifier as uid," : "'' as uid,"}
         ci.summary as title,
         datetime(CASE WHEN ci.all_day THEN ${allDayStartMac} ELSE ${timedStart} END + 978307200, 'unixepoch', 'localtime') as start,
         datetime(${occEnd} + 978307200, 'unixepoch', 'localtime') as end,
@@ -1821,9 +1824,11 @@ export function getEventsOnDate(startMs, endMs) {
       return { events: [], error: "Calendar database not found" };
     }
     const { startMac, endMac } = localDayToMacBounds(startMs, endMs);
-    const query = buildEventsOnDateQuery(startMac, endMac);
     let lastError;
     for (let attempt = 0; attempt < 3; attempt++) {
+      // Drop the UID column after a failed first attempt: a schema without
+      // unique_identifier must still return events for calendar_date.
+      const query = buildEventsOnDateQuery(startMac, endMac, { includeUid: attempt === 0 });
       try {
         const events = withCalendarCopy((dbPath) => {
           return safeSqlite3Json(dbPath, query, { timeout: 15000 });

package/lib/appleScript.js

@@ -0,0 +1,416 @@
+/**
+ * AppleScript execution helpers for the write tools.
+ *
+ * Scripts are always built from escaped literals (never string-concatenated
+ * shell) and run through `safeOsascript` (`spawnSync`, `shell: false`).
+ *
+ * This module also classifies macOS TCC (privacy) denials. TCC attributes an
+ * Apple event to the *responsible process*, which for a stdio MCP server is
+ * the app that launched node - not node itself. A host app without the
+ * Contacts/Calendars entitlements therefore makes the child's Apple events
+ * fail no matter what permissions node has. `lib/writeRouting.js` uses this
+ * classification to hand the work to the launchd-started indexer daemon,
+ * where node is the responsible process.
+ */
+
+import fs from "fs";
+import { safeOsascript } from "./shell.js";
+import { escapeAppleScript } from "./validators.js";
+
+export const DEFAULT_SCRIPT_TIMEOUT_MS = 30000;
+
+// Sentinels raised by our scripts so callers can map them to clean errors
+// instead of surfacing raw AppleScript text.
+export const NOT_FOUND_SENTINELS = [
+  "MESSAGE_NOT_FOUND",
+  "EVENT_NOT_FOUND",
+  "EVENTKIT_NOT_FOUND",
+  "CONTACT_NOT_FOUND",
+  "CALENDAR_NOT_FOUND",
+  "CHAT_NOT_FOUND",
+  "ARCHIVE_MAILBOX_NOT_FOUND",
+  "ATTENDEE_NOT_FOUND",
+  "RSVP_NOT_SUPPORTED"
+];
+
+// osascript / TCC denial signatures. Apple reports these as Apple event
+// errors (-1743, -10004) or as "not permitted" / "not authorized" text.
+const TCC_SIGNATURES = [
+  "-1743",
+  "-10004",
+  "-25211",
+  "not authorized to send apple events",
+  "not allowed to send apple events",
+  "is not allowed assistive access",
+  "operation not permitted",
+  "not permitted to access",
+  "access to contacts",
+  "access to calendars",
+  "privacy settings",
+  "errae eventnotpermitted",
+  "errAEEventNotPermitted".toLowerCase()
+];
+
+/**
+ * These read like "the app is missing", but macOS also emits them when the
+ * responsible process may not drive the app at all: a denied Automation
+ * grant frequently surfaces as -1728 / "can't get application" rather than a
+ * clean -1743. When the app is installed, treat them as attribution
+ * failures, not as a missing app.
+ */
+const APP_MISSING_SIGNATURES = [
+  "application isn't running",
+  "can't get application",
+  "can't get every application",
+  "application is not running",
+  "-600",
+  "-1728",
+  "-10810"
+];
+
+// osascript itself is missing: not macOS, or a stripped PATH. Never an
+// attribution problem, because nothing ran.
+//
+// Do **not** match a bare "spawnSync osascript" here. A TCC-denied Mail
+// compose hangs until spawnSync times out (`spawnSync osascript ETIMEDOUT`);
+// that string also contains "spawnSync osascript" and must not be reported
+// as "Mail.app could not be reached".
+const OSASCRIPT_MISSING_SIGNATURES = [
+  "spawnsync osascript enoent",
+  "enoent"
+];
+
+// Hung Apple events. Mini diagnosis: `tell Mail to get name` returns, but
+// `make new outgoing message` blocks until timeout when node → Mail
+// Automation is denied. That hang is a TCC deny, not a missing app.
+const TIMEOUT_SIGNATURES = [
+  "etimedout",
+  "timed out after",
+  "-1712",
+  "appleevent timed out",
+  "apple event timed out"
+];
+
+/**
+ * Standard install locations for the apps this package automates.
+ * Ventura and later keep the first-party apps in /System/Applications.
+ */
+const APP_SEARCH_DIRS = [
+  "/System/Applications",
+  "/Applications",
+  "/System/Applications/Utilities"
+];
+
+/**
+ * @param {string} appName - e.g. "Contacts"
+ * @returns {boolean|null} null when we cannot tell (no app name given)
+ */
+export function appBundleInstalled(appName, existsFn = fs.existsSync) {
+  if (!appName || typeof appName !== "string") return null;
+  if (!/^[A-Za-z ]{1,40}$/.test(appName)) return null;
+  return APP_SEARCH_DIRS.some((dir) => existsFn(`${dir}/${appName}.app`));
+}
+
+/**
+ * @param {string} message
+ * @param {object} [context]
+ * @param {boolean|null} [context.appInstalled] - whether the target app exists
+ * @returns {"tcc"|"timeout"|"not_found"|"attribution"|"app_unavailable"|"unknown"}
+ */
+export function classifyAppleScriptError(message, context = {}) {
+  const text = String(message || "").toLowerCase();
+  for (const sentinel of NOT_FOUND_SENTINELS) {
+    if (text.includes(sentinel.toLowerCase())) return "not_found";
+  }
+  if (OSASCRIPT_MISSING_SIGNATURES.some((sig) => text.includes(sig))) return "app_unavailable";
+  // ETIMEDOUT / -1712 is a hang, not a TCC deny. Mail/Messages still map
+  // this kind to Automation guidance (compose hang = grant missing).
+  // calendar_remove must never print Calendar-denied copy for ETIMEDOUT alone.
+  if (TIMEOUT_SIGNATURES.some((sig) => text.includes(sig))) return "timeout";
+  if (TCC_SIGNATURES.some((sig) => text.includes(sig))) return "tcc";
+  // Calendar delete of a detached event specifier often returns
+  // "Can't get event … (-1728)". That is a missing object, not a missing app.
+  // Check before the generic -1728 / "can't get application" path.
+  if (
+    text.includes("can't get event") ||
+    text.includes("can't get calendar") ||
+    text.includes("can't get theevent")
+  ) {
+    return "not_found";
+  }
+  if (APP_MISSING_SIGNATURES.some((sig) => text.includes(sig))) {
+    // The app is on disk, so "can't get application" means macOS refused to
+    // let the responsible process drive it - an Automation / attribution
+    // problem, not a missing app.
+    return context.appInstalled === true ? "attribution" : "app_unavailable";
+  }
+  return "unknown";
+}
+
+export function isTccDenial(message) {
+  return classifyAppleScriptError(message) === "tcc";
+}
+
+/**
+ * Real Automation / privacy deny codes — not a hung Calendar.app delete.
+ *
+ * Mini calendar_remove: add/edit succeed (Automation granted), then delete
+ * hits spawnSync ETIMEDOUT / AppleEvent -1712. That is an iCloud/CalDAV
+ * hang or a confirmation dialog, not -1743 / -10004. Callers must not
+ * rewrite that as CALENDAR_TCC_GUIDANCE.
+ */
+const HARD_TCC_SIGNATURES = [
+  "-1743",
+  "-10004",
+  "-25211",
+  "not authorized to send apple events",
+  "not allowed to send apple events",
+  "is not allowed assistive access",
+  "operation not permitted",
+  "not permitted to access",
+  "access to contacts",
+  "access to calendars",
+  "privacy settings",
+  "errae eventnotpermitted",
+  "errAEEventNotPermitted".toLowerCase()
+];
+
+export function isHardTccDenial(message) {
+  const text = String(message || "").toLowerCase();
+  return HARD_TCC_SIGNATURES.some((sig) => text.includes(sig));
+}
+
+const APPLEEVENT_CODES = [
+  "-1743",
+  "-10004",
+  "-25211",
+  "-1712",
+  "-1728",
+  "-600",
+  "-10810",
+  "-1708",
+  "-1719",
+  "-10025",
+  "-2700"
+];
+
+/**
+ * Pull known AppleEvent / spawn codes out of osascript stderr so smoke
+ * can print them instead of guessing TCC.
+ */
+export function extractAppleEventCodes(message) {
+  const text = String(message || "");
+  const found = [];
+  for (const code of APPLEEVENT_CODES) {
+    if (text.includes(code) && !found.includes(code)) found.push(code);
+  }
+  if (/etimedout/i.test(text) && !found.includes("ETIMEDOUT")) found.push("ETIMEDOUT");
+  return found;
+}
+
+/**
+ * One-line osascript diagnostic. Always include this on calendar_remove
+ * failure so Mini --apply stops looking like a TCC deny.
+ */
+export function formatOsascriptDiagnostic(result, source = "osascript") {
+  const raw = String(result && result.error ? result.error : "").replace(/\s+/g, " ").trim();
+  const clipped = raw.length > 360 ? `${raw.slice(0, 360)}...` : raw;
+  const kind = (result && result.kind) || "unknown";
+  const codes = extractAppleEventCodes(raw);
+  return `${source} kind=${kind} error=${clipped || "(empty)"}${codes.length ? ` codes=${codes.join(",")}` : ""}`;
+}
+
+/**
+ * Guidance attached to TCC denials. Names the host constraint without
+ * claiming the package can grant another app's entitlements.
+ */
+export const TCC_GUIDANCE =
+  "macOS denied this automation. TCC attributes Apple events to the process responsible for the MCP server, " +
+  "so a host app without the matching automation grant blocks the write even when node has Full Disk Access. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so writes execute under node, or run this server from a host that can be granted Automation access.";
+
+/**
+ * Contacts writes are the sharpest case, and worth separating from contacts
+ * reads: reads query the AddressBook sqlite file directly and only need Full
+ * Disk Access on the responsible process, while writes go through
+ * Contacts.app / CNContactStore, which is gated by the AddressBook privacy
+ * class. A host app built without the AddressBook entitlement is refused
+ * there with no prompt, and no package-side change can alter that.
+ */
+export const CONTACTS_TCC_GUIDANCE =
+  "macOS denied Contacts access for this write. Contacts writes go through Contacts.app (CNContactStore), which is gated by the AddressBook privacy class " +
+  "and attributed to the process responsible for this MCP server - not to node. A host app that was built without the AddressBook entitlement " +
+  "(com.apple.security.personal-information.addressbook) is denied with no prompt, and that cannot be fixed with Full Disk Access or tccutil. " +
+  "Contacts *reads* are unaffected: they query the AddressBook database directly and only need Full Disk Access. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Contacts writes execute under node, which macOS can grant AddressBook access to.";
+
+/**
+ * Calendar has the same split as Contacts: reads in this package are sqlite
+ * queries against Calendar.sqlitedb (Full Disk Access), while writes go
+ * through Calendar.app / EventKit, gated by the calendars privacy class.
+ */
+export const CALENDAR_TCC_GUIDANCE =
+  "macOS denied Calendar access for this write. Calendar writes go through Calendar.app (EventKit), which is gated by the calendars privacy class " +
+  "(com.apple.security.personal-information.calendars) and attributed to the process responsible for this MCP server - not to node. " +
+  "A host app built without that entitlement is denied with no prompt, and Full Disk Access or tccutil cannot change it. " +
+  "Calendar *reads* are unaffected: they query Calendar.sqlitedb directly and only need Full Disk Access. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Calendar writes execute under node, which macOS can grant Calendars access to.";
+
+/**
+ * Shown when the target app is installed but macOS still refused the Apple
+ * event. That is the signature of running under a parent process that
+ * cannot be granted Automation - a foreign shell, an embedded terminal, or
+ * a host app - rather than of a broken install.
+ */
+export const ATTRIBUTION_GUIDANCE =
+  "The app is installed, so this is an Automation / responsible-process problem rather than a missing app: macOS refused to let the process " +
+  "responsible for this server drive it. Start the indexer daemon (apple-tools-indexer / the LaunchAgent) so writes run through the write bridge " +
+  "under launchd-owned node, or run this server from a parent that can hold Automation access (Terminal.app) and approve the prompt.";
+
+/**
+ * Mail writes are gated by Automation → Mail for the responsible process.
+ * A hang or timeout on compose/send is that deny — not "Mail.app missing".
+ * dry_run never sends Apple events to Mail, so it cannot detect the grant.
+ */
+export const MAIL_TCC_GUIDANCE =
+  "macOS denied Mail automation (Apple Events to Mail.app). A hang or timeout on compose or send is a TCC / Automation deny for node → Mail, " +
+  "not Mail.app missing or unavailable. dry_run never talks to Mail, so it cannot detect this grant. " +
+  "Allow node in System Settings → Privacy & Security → Automation for Mail (same Allow-via-prompt as Contacts and Calendar — do not add node via + in a privacy list). " +
+  "A Contacts or Calendar grant does not include Mail. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Mail writes execute under node.";
+
+/**
+ * Messages writes are a separate Automation target from Mail / Contacts / Calendar.
+ */
+export const MESSAGES_TCC_GUIDANCE =
+  "macOS denied Messages automation (Apple Events to Messages.app). A hang or timeout on send is a TCC / Automation deny for node → Messages, " +
+  "not Messages.app missing or unavailable. dry_run never talks to Messages, so it cannot detect this grant. " +
+  "Allow node in System Settings → Privacy & Security → Automation for Messages (same Allow-via-prompt as Mail, Contacts, and Calendar — do not add node via + in a privacy list). " +
+  "A Contacts or Calendar grant does not include Messages. " +
+  "Run the indexer daemon (apple-tools-indexer / the LaunchAgent) so Messages writes execute under node.";
+
+/**
+ * @param {"contacts"|"calendar"|"mail"|"messages"|string} source
+ */
+export function tccGuidanceFor(source) {
+  if (source === "contacts") return CONTACTS_TCC_GUIDANCE;
+  if (source === "calendar") return CALENDAR_TCC_GUIDANCE;
+  if (source === "mail") return MAIL_TCC_GUIDANCE;
+  if (source === "messages") return MESSAGES_TCC_GUIDANCE;
+  return TCC_GUIDANCE;
+}
+
+/**
+ * Run a script and normalize the result.
+ *
+ * Pass `appName` so a refusal can be told apart from a missing app.
+ *
+ * @returns {{ ok: boolean, output: string, error: string|null, kind: string|null }}
+ */
+export function runAppleScript(script, options = {}) {
+  const { timeout = DEFAULT_SCRIPT_TIMEOUT_MS, appName = null, language = null } = options;
+  try {
+    const output = safeOsascript(script, { timeout, language });
+    return { ok: true, output: (output || "").trim(), error: null, kind: null };
+  } catch (e) {
+    const message = e && e.message ? e.message : String(e);
+    return {
+      ok: false,
+      output: "",
+      error: message,
+      kind: classifyAppleScriptError(message, { appInstalled: appBundleInstalled(appName) })
+    };
+  }
+}
+
+/**
+ * Quote a value as an AppleScript string literal.
+ */
+export function asString(value) {
+  return `"${escapeAppleScript(value === undefined || value === null ? "" : String(value))}"`;
+}
+
+/**
+ * Emit a validated integer. Throws rather than interpolating unchecked input.
+ */
+export function asInteger(value, { min = -2147483648, max = 2147483647, field = "value" } = {}) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(`${field} must be an integer between ${min} and ${max}`);
+  }
+  return String(n);
+}
+
+export function asBoolean(value) {
+  return value ? "true" : "false";
+}
+
+/**
+ * AppleScript handler that builds a local `date` from validated integers.
+ * Day is reset to 1 first so setting month never rolls the date forward
+ * (e.g. Jan 31 -> "Feb 31").
+ */
+export const DATE_HANDLER = `on atmMakeDate(y, mo, d, hh, mi)
+  set dt to current date
+  set day of dt to 1
+  set year of dt to y
+  set month of dt to mo
+  set day of dt to d
+  set hours of dt to hh
+  set minutes of dt to mi
+  set seconds of dt to 0
+  return dt
+end atmMakeDate`;
+
+/**
+ * Build the `atmMakeDate(...)` call for a parsed date.
+ * @param {{year:number,month:number,day:number,hour:number,minute:number}} parts
+ */
+export function dateCall(parts) {
+  return `atmMakeDate(${asInteger(parts.year, { min: 1970, max: 2200, field: "year" })}, ` +
+    `${asInteger(parts.month, { min: 1, max: 12, field: "month" })}, ` +
+    `${asInteger(parts.day, { min: 1, max: 31, field: "day" })}, ` +
+    `${asInteger(parts.hour, { min: 0, max: 23, field: "hour" })}, ` +
+    `${asInteger(parts.minute, { min: 0, max: 59, field: "minute" })})`;
+}
+
+/**
+ * Strict datetime parsing for writes.
+ *
+ * Writes never guess: only explicit local datetimes are accepted, so an agent
+ * cannot silently schedule "next tuesday" against the wrong day.
+ * Accepted: "YYYY-MM-DD", "YYYY-MM-DD HH:MM", "YYYY-MM-DDTHH:MM[:SS]".
+ *
+ * @returns {{ parts: object|null, error: string|null, dateOnly: boolean }}
+ */
+export function parseWriteDateTime(value, field = "start") {
+  if (typeof value !== "string" || value.trim() === "") {
+    return { parts: null, error: `${field} is required (use YYYY-MM-DD HH:MM local time)`, dateOnly: false };
+  }
+  const trimmed = value.trim();
+  const match = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2})?)?$/);
+  if (!match) {
+    return {
+      parts: null,
+      error: `${field} must be an explicit local datetime such as 2026-09-20 14:30 (YYYY-MM-DD or YYYY-MM-DD HH:MM). Natural language is not accepted for writes.`,
+      dateOnly: false
+    };
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const dateOnly = match[4] === undefined;
+  const hour = dateOnly ? 0 : Number(match[4]);
+  const minute = dateOnly ? 0 : Number(match[5]);
+
+  if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59) {
+    return { parts: null, error: `${field} is not a valid date/time: ${trimmed}`, dateOnly };
+  }
+  // Reject impossible calendar days (e.g. 2026-02-31).
+  const probe = new Date(year, month - 1, day, hour, minute, 0, 0);
+  if (probe.getFullYear() !== year || probe.getMonth() !== month - 1 || probe.getDate() !== day) {
+    return { parts: null, error: `${field} is not a valid calendar date: ${trimmed}`, dateOnly };
+  }
+
+  return { parts: { year, month, day, hour, minute, iso: trimmed }, error: null, dateOnly };
+}