apple-pim-cli 3.0.0

package/lib/tool-args.js

@@ -0,0 +1,116 @@
+export function buildCalendarDeleteArgs(args) {
+  const deleteArgs = ["delete", "--id", args.id];
+  if (args.futureEvents) deleteArgs.push("--future-events");
+  return deleteArgs;
+}
+
+export function buildCalendarCreateArgs(args, targetCalendar) {
+  const cliArgs = ["create", "--title", args.title, "--start", args.start];
+  if (args.end) cliArgs.push("--end", args.end);
+  if (args.duration) cliArgs.push("--duration", String(args.duration));
+  if (targetCalendar) cliArgs.push("--calendar", targetCalendar);
+  if (args.location) cliArgs.push("--location", args.location);
+  if (args.notes) cliArgs.push("--notes", args.notes);
+  if (args.url) cliArgs.push("--url", args.url);
+  if (args.allDay) cliArgs.push("--all-day");
+  if (args.alarm) {
+    for (const minutes of args.alarm) {
+      cliArgs.push("--alarm", String(minutes));
+    }
+  }
+  if (args.recurrence) {
+    cliArgs.push("--recurrence", JSON.stringify(args.recurrence));
+  }
+  return cliArgs;
+}
+
+export function buildCalendarUpdateArgs(args) {
+  const cliArgs = ["update", "--id", args.id];
+  if (args.title) cliArgs.push("--title", args.title);
+  if (args.start) cliArgs.push("--start", args.start);
+  if (args.end) cliArgs.push("--end", args.end);
+  if (args.location) cliArgs.push("--location", args.location);
+  if (args.notes) cliArgs.push("--notes", args.notes);
+  if (args.url) cliArgs.push("--url", args.url);
+  if (args.recurrence) cliArgs.push("--recurrence", JSON.stringify(args.recurrence));
+  if (args.futureEvents) cliArgs.push("--future-events");
+  return cliArgs;
+}
+
+export function buildReminderCreateArgs(args, targetList) {
+  const cliArgs = ["create", "--title", args.title];
+  if (targetList) cliArgs.push("--list", targetList);
+  if (args.due) cliArgs.push("--due", args.due);
+  if (args.notes) cliArgs.push("--notes", args.notes);
+  if (args.priority !== undefined) cliArgs.push("--priority", String(args.priority));
+  if (args.url) cliArgs.push("--url", args.url);
+  if (args.alarm) {
+    for (const minutes of args.alarm) {
+      cliArgs.push("--alarm", String(minutes));
+    }
+  }
+  if (args.location) cliArgs.push("--location", JSON.stringify(args.location));
+  if (args.recurrence) cliArgs.push("--recurrence", JSON.stringify(args.recurrence));
+  return cliArgs;
+}
+
+export function buildReminderUpdateArgs(args) {
+  const cliArgs = ["update", "--id", args.id];
+  if (args.title) cliArgs.push("--title", args.title);
+  if (args.due) cliArgs.push("--due", args.due);
+  if (args.notes) cliArgs.push("--notes", args.notes);
+  if (args.priority !== undefined) cliArgs.push("--priority", String(args.priority));
+  if (args.url !== undefined) cliArgs.push("--url", args.url);
+  if (args.location) cliArgs.push("--location", JSON.stringify(args.location));
+  if (args.recurrence) cliArgs.push("--recurrence", JSON.stringify(args.recurrence));
+  return cliArgs;
+}
+
+function pushJSONIfNonEmpty(cliArgs, flag, value) {
+  if (Array.isArray(value) && value.length > 0) {
+    cliArgs.push(flag, JSON.stringify(value));
+  }
+}
+
+function pushContactSharedFields(cliArgs, args) {
+  if (args.firstName) cliArgs.push("--first-name", args.firstName);
+  if (args.lastName) cliArgs.push("--last-name", args.lastName);
+  if (args.middleName) cliArgs.push("--middle-name", args.middleName);
+  if (args.namePrefix) cliArgs.push("--name-prefix", args.namePrefix);
+  if (args.nameSuffix) cliArgs.push("--name-suffix", args.nameSuffix);
+  if (args.nickname) cliArgs.push("--nickname", args.nickname);
+  if (args.previousFamilyName) cliArgs.push("--previous-family-name", args.previousFamilyName);
+  if (args.phoneticGivenName) cliArgs.push("--phonetic-given-name", args.phoneticGivenName);
+  if (args.phoneticMiddleName) cliArgs.push("--phonetic-middle-name", args.phoneticMiddleName);
+  if (args.phoneticFamilyName) cliArgs.push("--phonetic-family-name", args.phoneticFamilyName);
+  if (args.phoneticOrganizationName) cliArgs.push("--phonetic-organization-name", args.phoneticOrganizationName);
+  if (args.organization) cliArgs.push("--organization", args.organization);
+  if (args.jobTitle) cliArgs.push("--job-title", args.jobTitle);
+  if (args.department) cliArgs.push("--department", args.department);
+  if (args.contactType) cliArgs.push("--contact-type", args.contactType);
+  if (args.email) cliArgs.push("--email", args.email);
+  if (args.phone) cliArgs.push("--phone", args.phone);
+  pushJSONIfNonEmpty(cliArgs, "--emails", args.emails);
+  pushJSONIfNonEmpty(cliArgs, "--phones", args.phones);
+  pushJSONIfNonEmpty(cliArgs, "--addresses", args.addresses);
+  pushJSONIfNonEmpty(cliArgs, "--urls", args.urls);
+  pushJSONIfNonEmpty(cliArgs, "--social-profiles", args.socialProfiles);
+  pushJSONIfNonEmpty(cliArgs, "--instant-messages", args.instantMessages);
+  pushJSONIfNonEmpty(cliArgs, "--relations", args.relations);
+  if (args.birthday) cliArgs.push("--birthday", args.birthday);
+  pushJSONIfNonEmpty(cliArgs, "--dates", args.dates);
+  if (args.notes) cliArgs.push("--notes", args.notes);
+}
+
+export function buildContactCreateArgs(args) {
+  const cliArgs = ["create"];
+  if (args.name) cliArgs.push("--name", args.name);
+  pushContactSharedFields(cliArgs, args);
+  return cliArgs;
+}
+
+export function buildContactUpdateArgs(args) {
+  const cliArgs = ["update", "--id", args.id];
+  pushContactSharedFields(cliArgs, args);
+  return cliArgs;
+}

package/openclaw.plugin.json

@@ -0,0 +1,31 @@
+{
+  "id": "apple-pim-cli",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "binDir": {
+        "type": "string",
+        "description": "Path to Swift CLI binaries directory"
+      },
+      "profile": {
+        "type": "string",
+        "description": "Default PIM config profile name"
+      },
+      "configDir": {
+        "type": "string",
+        "description": "Default PIM config directory"
+      }
+    }
+  },
+  "uiHints": {
+    "binDir": {
+      "label": "CLI Binary Directory"
+    },
+    "profile": {
+      "label": "PIM Profile"
+    },
+    "configDir": {
+      "label": "Config Directory"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "apple-pim-cli",
+  "version": "3.0.0",
+  "description": "OpenClaw plugin for macOS Calendar, Reminders, Contacts, and Mail via native Swift CLIs",
+  "type": "module",
+  "scripts": {
+    "prepack": "rm -rf lib && cp -R ../lib .",
+    "postpack": "rm -rf lib && ln -s ../lib ."
+  },
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  },
+  "files": [
+    "src/",
+    "lib/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "calendar",
+    "reminders",
+    "contacts",
+    "mail",
+    "eventkit",
+    "macos",
+    "pim"
+  ],
+  "author": {
+    "name": "Omar Shahine",
+    "email": "omar@shahine.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omarshahine/Apple-PIM-Agent-Plugin.git",
+    "directory": "openclaw"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "os": ["darwin"],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mailparser": "^3.9.3",
+    "turndown": "^7.2.2"
+  }
+}

package/skills/apple-pim/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: apple-pim
+description: |
+  Native macOS personal information management for calendars, reminders, contacts, and local Mail.app. Use when the user wants to schedule meetings, create events, check their calendar, create or complete reminders, look up contacts, find someone's phone number or email, manage tasks and to-do lists, triage local Mail.app messages, or troubleshoot EventKit, Contacts, or Mail.app permissions on macOS.
+license: MIT
+compatibility: |
+  macOS only. Requires TCC permissions for Calendars, Reminders, and Contacts via Privacy & Security settings. Mail features require Mail.app running with Automation permission granted.
+metadata:
+  author: Omar Shahine
+  version: 3.0.0
+  openclaw:
+    os: [darwin]
+    requires:
+      bins: [calendar-cli]
+---
+
+# Apple PIM (EventKit, Contacts & Mail)
+
+## Overview
+
+Apple provides frameworks and scripting interfaces for personal information management:
+- **EventKit**: Calendars and Reminders
+- **Contacts**: Address book management
+- **Mail.app**: Local email via JXA (JavaScript for Automation)
+
+EventKit and Contacts require explicit user permission via privacy prompts. Mail.app requires Automation permission and must be running.
+
+## Tools
+
+This plugin provides 5 tools:
+
+| Tool | Actions | Domain |
+|------|---------|--------|
+| `apple_pim_calendar` | `list`, `events`, `get`, `search`, `create`, `update`, `delete`, `batch_create` | Calendar events via EventKit |
+| `apple_pim_reminder` | `lists`, `items`, `get`, `search`, `create`, `complete`, `update`, `delete`, `batch_create`, `batch_complete`, `batch_delete` | Reminders via EventKit |
+| `apple_pim_contact` | `groups`, `list`, `search`, `get`, `create`, `update`, `delete` | Contacts framework |
+| `apple_pim_mail` | `accounts`, `mailboxes`, `messages`, `get`, `search`, `update`, `move`, `delete`, `batch_update`, `batch_delete` | Mail.app via JXA |
+| `apple_pim_system` | `status`, `authorize`, `config_show`, `config_init` | Authorization & configuration |
+
+## Authorization & Permissions
+
+### Permission Model
+
+Each PIM domain requires separate macOS authorization:
+
+| Domain | Framework | Permission Section |
+|--------|-----------|-------------------|
+| Calendars | EventKit | Privacy & Security > Calendars |
+| Reminders | EventKit | Privacy & Security > Reminders |
+| Contacts | Contacts | Privacy & Security > Contacts |
+| Mail | Automation (JXA) | Privacy & Security > Automation |
+
+### Authorization States
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| `notDetermined` | Never requested | Use `apple_pim_system` with action `authorize` to trigger prompt |
+| `authorized` | Full access granted | Ready to use |
+| `denied` | User refused access | Must enable in System Settings manually |
+| `restricted` | System policy (MDM, parental) | Cannot override |
+| `writeOnly` | Limited write access (macOS 17+) | Upgrade to Full Access in Settings |
+
+## Configuration (PIMConfig)
+
+The PIM CLIs share a configuration system for filtering calendars/reminder lists and setting defaults.
+
+### Config File Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.config/apple-pim/config.json` | Base configuration |
+| `~/.config/apple-pim/profiles/{name}.json` | Named profile overrides |
+
+### Example Config
+
+```json
+{
+  "calendars": {
+    "enabled": true,
+    "mode": "blocklist",
+    "items": ["US Holidays", "Birthdays"],
+    "default": "Personal"
+  },
+  "reminders": {
+    "enabled": true,
+    "mode": "allowlist",
+    "items": ["Tasks", "Shopping", "Work"],
+    "default": "Tasks"
+  },
+  "contacts": { "enabled": true },
+  "mail": { "enabled": true }
+}
+```
+
+### Filter Modes
+
+| Mode | Behavior |
+|------|----------|
+| `all` | No filtering — all calendars/lists are visible (default) |
+| `allowlist` | Only calendars/lists named in `items` are visible |
+| `blocklist` | All calendars/lists are visible EXCEPT those named in `items` |
+
+### Multi-Agent Isolation
+
+All 5 tools accept optional `configDir` and `profile` parameters for per-call workspace isolation:
+
+```
+apple_pim_calendar({ action: "list", configDir: "~/agents/travel/apple-pim" })
+apple_pim_calendar({ action: "list", profile: "work" })
+```
+
+**Priority chain**: Tool parameter > plugin config > env var > default (`~/.config/apple-pim/`)
+
+## Best Practices
+
+### Calendar Management
+1. **Use default calendar for new events** when user doesn't specify
+2. **Preserve recurrence rules** when updating recurring events
+3. **Handle `.thisEvent` vs `.futureEvents`** span for recurring event edits
+4. **Use `batch_create`** when creating multiple events for efficiency
+
+### EKSpan for Recurring Events
+
+| Span | Effect | When to Use |
+|------|--------|-------------|
+| `.thisEvent` | Affects only the single occurrence | Default for delete and update |
+| `.futureEvents` | Affects this and all future occurrences | Use when ending a series |
+
+- **Delete**: Default is `.thisEvent`. Pass `futureEvents: true` to use `.futureEvents`.
+- **Update**: Default is `.thisEvent`. Pass `futureEvents: true` to apply to future occurrences.
+- **Remove recurrence**: Pass `recurrence: { frequency: "none" }` with `futureEvents: true`.
+
+### Reminder Management
+1. **Default to incomplete reminders** when listing
+2. **Use filters**: `overdue` for urgent, `today` for daily planning, `week` for review
+3. **Use batch operations** (`batch_complete`, `batch_delete`) for multiple items
+
+### Contact Management
+1. **Preserve existing data** when updating (only modify changed fields)
+2. **Handle labeled values carefully** — don't lose non-primary entries
+
+### Mail Management
+1. **Mail.app must be running** for all operations
+2. **Use batch operations** (`batch_update`, `batch_delete`) for inbox triage
+3. **Message IDs are RFC 2822** — stable across mailbox moves
+4. **Use mailbox/account hints** for faster lookups
+
+### Error Handling
+1. **Check authorization first** with `apple_pim_system` action `status`
+2. **Use `apple_pim_system` action `authorize`** for `notDetermined` domains
+3. **Guide users to System Settings** for `denied` domains
+
+## Troubleshooting
+
+### Permission Issues
+- Use `apple_pim_system` with action `status` to check all domains
+- Use `apple_pim_system` with action `authorize` to trigger prompts
+- Check System Settings > Privacy & Security
+
+### Binary Not Found
+- Run `./setup.sh --install` to build and install CLIs to `~/.local/bin/`
+- Or set `binDir` in plugin config to point to your build directory
+
+### Configuration Issues
+- **Unexpected filtering**: Use `apple_pim_system` action `config_show` to verify active config
+- **Missing calendars/lists**: Use `apple_pim_system` action `config_init` to discover available items

package/src/index.ts

@@ -0,0 +1,177 @@
+/**
+ * OpenClaw plugin entry for Apple PIM CLI Tools.
+ *
+ * Registers 5 tools that spawn the Swift CLIs directly (no MCP server).
+ * Supports per-call environment isolation via configDir/profile parameters
+ * for multi-agent workspaces.
+ */
+
+import { createCLIRunner, findSwiftBinDir } from "../lib/cli-runner.js";
+import { tools } from "../lib/schemas.js";
+import { markToolResult, getDatamarkingPreamble } from "../lib/sanitize.js";
+import { handleCalendar } from "../lib/handlers/calendar.js";
+import { handleReminder } from "../lib/handlers/reminder.js";
+import { handleContact } from "../lib/handlers/contact.js";
+import { handleMail } from "../lib/handlers/mail.js";
+import { handleApplePim } from "../lib/handlers/apple-pim.js";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { execFileSync } from "child_process";
+import { homedir } from "os";
+
+// OpenClaw plugin config (set by the gateway from openclaw.plugin.json configSchema)
+interface PluginConfig {
+  binDir?: string;
+  profile?: string;
+  configDir?: string;
+}
+
+// Tool args always include optional isolation params
+interface ToolArgs {
+  action: string;
+  configDir?: string;
+  profile?: string;
+  [key: string]: unknown;
+}
+
+// OpenClaw tool registration interface
+interface OpenClawContext {
+  config?: PluginConfig;
+  registerTool(definition: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<{ content: string }>;
+  }): void;
+}
+
+// Map MCP tool names to OpenClaw snake_case names
+const TOOL_NAME_MAP: Record<string, string> = {
+  "calendar": "apple_pim_calendar",
+  "reminder": "apple_pim_reminder",
+  "contact": "apple_pim_contact",
+  "mail": "apple_pim_mail",
+  "apple-pim": "apple_pim_system",
+};
+
+// Map MCP tool names to handler functions
+const HANDLERS: Record<string, (args: ToolArgs, runCLI: (cli: string, args: string[]) => Promise<object>) => Promise<object>> = {
+  "calendar": handleCalendar,
+  "reminder": handleReminder,
+  "contact": handleContact,
+  "mail": handleMail,
+  "apple-pim": handleApplePim,
+};
+
+/**
+ * Resolve the binary directory using a discovery chain:
+ * 1. Plugin config binDir
+ * 2. Env var APPLE_PIM_BIN_DIR
+ * 3. PATH lookup (which calendar-cli)
+ * 4. ~/.local/bin/ (setup.sh --install target)
+ */
+function resolveBinDir(config?: PluginConfig): string {
+  // 1. Plugin config
+  if (config?.binDir && existsSync(join(config.binDir, "calendar-cli"))) {
+    return config.binDir;
+  }
+
+  // 2. Env var
+  const envBinDir = process.env.APPLE_PIM_BIN_DIR;
+  if (envBinDir && existsSync(join(envBinDir, "calendar-cli"))) {
+    return envBinDir;
+  }
+
+  // 3. PATH lookup (execFileSync avoids shell injection)
+  try {
+    const whichResult = execFileSync("which", ["calendar-cli"], { encoding: "utf8" }).trim();
+    if (whichResult) {
+      return dirname(whichResult);
+    }
+  } catch {
+    // Not on PATH, continue
+  }
+
+  // 4-5. Standard locations via findSwiftBinDir
+  return findSwiftBinDir();
+}
+
+/**
+ * Resolve per-call environment overrides for workspace isolation.
+ *
+ * Priority chain (per parameter):
+ * 1. Tool parameter (per-call override)
+ * 2. Plugin config (gateway-level default)
+ * 3. Process env (APPLE_PIM_CONFIG_DIR / APPLE_PIM_PROFILE)
+ * 4. Default (~/.config/apple-pim/)
+ */
+function resolveEnvOverrides(args: ToolArgs, config?: PluginConfig): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  // Resolve configDir
+  const configDir = args.configDir || config?.configDir || process.env.APPLE_PIM_CONFIG_DIR;
+  if (configDir) {
+    env.APPLE_PIM_CONFIG_DIR = configDir.replace(/^~/, homedir());
+  }
+
+  // Resolve profile
+  const profile = args.profile || config?.profile || process.env.APPLE_PIM_PROFILE;
+  if (profile) {
+    env.APPLE_PIM_PROFILE = profile;
+  }
+
+  return env;
+}
+
+/**
+ * OpenClaw plugin activation function.
+ * Called by the OpenClaw gateway when the plugin is loaded.
+ */
+export default function activate(context: OpenClawContext): void {
+  const config = context.config;
+  const binDir = resolveBinDir(config);
+
+  for (const tool of tools) {
+    const openclawName = TOOL_NAME_MAP[tool.name];
+    const handler = HANDLERS[tool.name];
+
+    if (!openclawName || !handler) continue;
+
+    context.registerTool({
+      name: openclawName,
+      description: tool.description,
+      inputSchema: tool.inputSchema as Record<string, unknown>,
+
+      async execute(args: Record<string, unknown>) {
+        // Runtime validation — ensure required 'action' field is present and valid
+        if (typeof args.action !== "string" || !args.action) {
+          return {
+            content: JSON.stringify({ success: false, error: "Missing required 'action' parameter" }, null, 2),
+          };
+        }
+        const toolArgs = args as ToolArgs;
+
+        // Per-call environment isolation — never mutates process.env
+        const envOverrides = resolveEnvOverrides(toolArgs, config);
+        const { runCLI } = createCLIRunner(binDir, envOverrides);
+
+        try {
+          const result = await handler(toolArgs, runCLI);
+
+          // Apply datamarking for prompt injection defense
+          const markedResult = markToolResult(result, tool.name);
+          const preamble = getDatamarkingPreamble(tool.name);
+
+          return {
+            content: `${preamble}\n\n${JSON.stringify(markedResult, null, 2)}`,
+          };
+        } catch (error: unknown) {
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: JSON.stringify({ success: false, error: message }, null, 2),
+          };
+        }
+      },
+    });
+  }
+}