@forwardimpact/outpost 3.0.3

package/templates/.claude/skills/sync-apple-calendar/scripts/sync.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env bun
+/**
+ * Sync Apple Calendar events to ~/.cache/fit/outpost/apple_calendar/ as JSON.
+ *
+ * Queries the macOS Calendar SQLite database (via node:sqlite) for events in a
+ * sliding window — N days in the past through 14 days in the future. Writes one
+ * JSON file per event and removes files for events that fall outside the window.
+ * Attendee details (name, email, status, role) are batch-fetched and included.
+ *
+ * Requires macOS with Calendar app configured and Full Disk Access granted.
+ */
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`sync-apple-calendar — sync calendar events to JSON
+
+Usage: node scripts/sync.mjs [--days N] [-h|--help]
+
+Options:
+  --days N     Days back to sync (default: 30)
+  -h, --help   Show this help message and exit
+
+Requires macOS with Calendar configured and Full Disk Access granted.`);
+  process.exit(0);
+}
+
+import { DatabaseSync } from "node:sqlite";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+const OUTDIR = join(HOME, ".cache/fit/outpost/apple_calendar");
+
+/** Core Data epoch: 2001-01-01T00:00:00Z */
+const EPOCH_MS = Date.UTC(2001, 0, 1);
+
+const DB_PATHS = [
+  join(
+    HOME,
+    "Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb",
+  ),
+  join(HOME, "Library/Calendars/Calendar.sqlitedb"),
+];
+
+const STATUS_MAP = {
+  0: "unknown",
+  1: "pending",
+  2: "accepted",
+  3: "declined",
+  4: "tentative",
+  5: "delegated",
+  6: "completed",
+  7: "in-process",
+};
+
+const ROLE_MAP = {
+  0: "unknown",
+  1: "required",
+  2: "optional",
+  3: "chair",
+};
+
+/**
+ * Find the Apple Calendar database.
+ * @returns {string}
+ */
+function findDb() {
+  const db = DB_PATHS.find((p) => existsSync(p));
+  if (!db) {
+    console.error(
+      "Error: Apple Calendar database not found. Is Calendar configured?",
+    );
+    process.exit(1);
+  }
+  return db;
+}
+
+/**
+ * Open the database in read-only mode with retry on lock.
+ * @param {string} dbPath
+ * @returns {import("node:sqlite").DatabaseSync}
+ */
+function openDb(dbPath) {
+  try {
+    return new DatabaseSync(dbPath, { readOnly: true });
+  } catch (err) {
+    if (err.message.includes("locked")) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
+      return new DatabaseSync(dbPath, { readOnly: true });
+    }
+    throw err;
+  }
+}
+
+/**
+ * Execute a read-only query and return results.
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {string} sql
+ * @returns {Array<Record<string, any>>}
+ */
+function query(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (err) {
+    console.error(`SQLite error: ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * Convert Core Data timestamp to ISO 8601.
+ * @param {number | null} ts - Seconds since 2001-01-01
+ * @param {string | null} tzName
+ * @returns {string | null}
+ */
+function coredataToIso(ts, tzName) {
+  if (ts == null) return null;
+  const ms = EPOCH_MS + ts * 1000;
+  const dt = new Date(ms);
+
+  if (tzName && tzName !== "_float") {
+    try {
+      return (
+        dt.toLocaleString("sv-SE", { timeZone: tzName }).replace(" ", "T") +
+        getUtcOffset(dt, tzName)
+      );
+    } catch {
+      // Fall through to UTC
+    }
+  }
+  return dt.toISOString();
+}
+
+/**
+ * Get UTC offset string for a timezone at a given instant.
+ * @param {Date} dt
+ * @param {string} tzName
+ * @returns {string} e.g. "+02:00" or "-05:00"
+ */
+function getUtcOffset(dt, tzName) {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: tzName,
+      timeZoneName: "longOffset",
+    }).formatToParts(dt);
+    const tzPart = parts.find((p) => p.type === "timeZoneName");
+    if (tzPart) {
+      // "GMT+2" → "+02:00", "GMT-5:30" → "-05:30", "GMT" → "+00:00"
+      const match = tzPart.value.match(/GMT([+-])(\d{1,2})(?::(\d{2}))?/);
+      if (match) {
+        const sign = match[1];
+        const hours = match[2].padStart(2, "0");
+        const mins = (match[3] ?? "00").padStart(2, "0");
+        return `${sign}${hours}:${mins}`;
+      }
+      return "+00:00"; // GMT with no offset
+    }
+  } catch {
+    // Fallback
+  }
+  return "Z";
+}
+
+// --- Main ---
+
+function fetchEvents(db, startTs, endTs) {
+  return query(
+    db,
+    `
+    SELECT
+      ci.ROWID AS id,
+      ci.summary,
+      ci.start_date,
+      ci.end_date,
+      ci.start_tz,
+      ci.end_tz,
+      ci.all_day,
+      ci.description,
+      ci.has_attendees,
+      ci.conference_url,
+      loc.title AS location,
+      cal.title AS calendar_name,
+      org.address AS organizer_email,
+      org.display_name AS organizer_name
+    FROM CalendarItem ci
+    LEFT JOIN Location loc ON loc.ROWID = ci.location_id
+    LEFT JOIN Calendar cal ON cal.ROWID = ci.calendar_id
+    LEFT JOIN Identity org ON org.ROWID = ci.organizer_id
+    WHERE ci.start_date <= ${endTs}
+      AND COALESCE(ci.end_date, ci.start_date) >= ${startTs}
+      AND ci.summary IS NOT NULL
+      AND ci.summary != ''
+    ORDER BY ci.start_date ASC
+    LIMIT 1000;
+  `,
+  );
+}
+
+function fetchAttendeesByEvent(db, eventIds) {
+  const attendeesByEvent = {};
+  if (eventIds.length === 0) return attendeesByEvent;
+  const idList = eventIds.join(",");
+  const attendeesRaw = query(
+    db,
+    `
+    SELECT p.owner_id, p.email, p.status, p.role, p.is_self, p.entity_type, i.display_name
+    FROM Participant p
+    LEFT JOIN Identity i ON i.ROWID = p.identity_id
+    WHERE p.owner_id IN (${idList}) AND p.entity_type = 7;
+  `,
+  );
+  for (const a of attendeesRaw) {
+    attendeesByEvent[a.owner_id] ??= [];
+    attendeesByEvent[a.owner_id].push(a);
+  }
+  return attendeesByEvent;
+}
+
+function buildAttendeeList(rawAttendees) {
+  const attendees = [];
+  for (const a of rawAttendees) {
+    if (!a.email) continue;
+    attendees.push({
+      email: a.email,
+      name: (a.display_name ?? "").trim() || null,
+      status: STATUS_MAP[a.status] ?? "unknown",
+      role: ROLE_MAP[a.role] ?? "unknown",
+      self: Boolean(a.is_self),
+    });
+  }
+  return attendees.length > 0 ? attendees : null;
+}
+
+function buildOrganizer(ev) {
+  let orgEmail = ev.organizer_email ?? null;
+  if (orgEmail?.startsWith("mailto:")) orgEmail = orgEmail.slice(7);
+  if (!orgEmail) return null;
+  return { email: orgEmail, name: (ev.organizer_name ?? "").trim() || null };
+}
+
+function tzOrNull(tz) {
+  return tz !== "_float" ? tz : null;
+}
+
+function buildEventJson(ev, attendeesByEvent) {
+  return {
+    id: `apple_cal_${ev.id}`,
+    summary: ev.summary,
+    start: {
+      dateTime: coredataToIso(ev.start_date, ev.start_tz),
+      timeZone: tzOrNull(ev.start_tz),
+    },
+    end: {
+      dateTime: coredataToIso(ev.end_date ?? ev.start_date, ev.end_tz),
+      timeZone: tzOrNull(ev.end_tz),
+    },
+    allDay: Boolean(ev.all_day),
+    location: ev.location || null,
+    description: ev.description || null,
+    conferenceUrl: ev.conference_url || null,
+    calendar: ev.calendar_name || null,
+    organizer: buildOrganizer(ev),
+    attendees: buildAttendeeList(attendeesByEvent[ev.id] ?? []),
+  };
+}
+
+function writeEventFiles(events, attendeesByEvent) {
+  const writtenIds = new Set();
+  for (const ev of events) {
+    const eventJson = buildEventJson(ev, attendeesByEvent);
+    const filename = `${ev.id}.json`;
+    writeFileSync(join(OUTDIR, filename), JSON.stringify(eventJson, null, 2));
+    writtenIds.add(filename);
+  }
+  return writtenIds;
+}
+
+function cleanupStaleFiles(writtenIds) {
+  let removed = 0;
+  for (const fname of readdirSync(OUTDIR)) {
+    if (fname.endsWith(".json") && !writtenIds.has(fname)) {
+      unlinkSync(join(OUTDIR, fname));
+      removed++;
+    }
+  }
+  return removed;
+}
+
+function main() {
+  let daysBack = 30;
+  const daysIdx = process.argv.indexOf("--days");
+  if (daysIdx !== -1 && process.argv[daysIdx + 1]) {
+    daysBack = parseInt(process.argv[daysIdx + 1], 10);
+  }
+
+  const dbPath = findDb();
+  mkdirSync(OUTDIR, { recursive: true });
+
+  const now = Date.now();
+  const start = new Date(now - daysBack * 86400000);
+  const end = new Date(now + 14 * 86400000);
+  const startTs = (start.getTime() - EPOCH_MS) / 1000;
+  const endTs = (end.getTime() - EPOCH_MS) / 1000;
+
+  const db = openDb(dbPath);
+
+  try {
+    const events = fetchEvents(db, startTs, endTs);
+    const eventIds = events.map((ev) => String(ev.id));
+    const attendeesByEvent = fetchAttendeesByEvent(db, eventIds);
+    const writtenIds = writeEventFiles(events, attendeesByEvent);
+    const removed = cleanupStaleFiles(writtenIds);
+
+    console.log("Apple Calendar Sync Complete");
+    console.log(`Events synced: ${writtenIds.size}`);
+    console.log(
+      `Time window: ${start.toISOString().slice(0, 10)} to ${end.toISOString().slice(0, 10)}`,
+    );
+    console.log(`Files cleaned up: ${removed} (outside window)`);
+    console.log(`Output: ${OUTDIR}`);
+  } finally {
+    db.close();
+  }
+}
+
+main();

package/templates/.claude/skills/sync-apple-mail/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: sync-apple-mail
+description: Sync email threads from the macOS Mail app's local SQLite database into ~/.cache/fit/outpost/apple_mail/ as markdown files. Use on a schedule or when the user asks to sync their email. Requires macOS with Mail app configured and Full Disk Access granted.
+compatibility: Requires macOS with Apple Mail configured and Full Disk Access granted to the terminal
+---
+
+# Sync Apple Mail
+
+Sync email threads from the macOS Mail app's local SQLite database into
+`~/.cache/fit/outpost/apple_mail/` as markdown files. This is an automated data
+pipeline skill — it ingests raw email data that other skills (like
+`extract-entities`) consume downstream.
+
+## Trigger
+
+Run this skill on a schedule (every 5 minutes) or when the user asks to sync
+their email.
+
+## Prerequisites
+
+- macOS with the built-in Mail app configured
+- Full Disk Access granted to the terminal (System Settings → Privacy & Security
+  → Full Disk Access)
+
+## Inputs
+
+- `~/.cache/fit/outpost/state/apple_mail_last_sync` — last sync timestamp
+  (single-line text file)
+- `~/.cache/fit/outpost/state/apple_mail_last_rowid` — highest message ROWID
+  seen at last sync (single-line text file)
+- `~/Library/Mail/V*/MailData/Envelope Index` — Apple Mail SQLite database
+
+## Outputs
+
+- `~/.cache/fit/outpost/apple_mail/{thread_id}.md` — one markdown file per email
+  thread
+- `~/.cache/fit/outpost/apple_mail/attachments/{thread_id}/` — copied attachment
+  files for each thread (PDFs, images, documents, etc.)
+- `~/.cache/fit/outpost/state/apple_mail_last_sync` — updated with new sync
+  timestamp
+- `~/.cache/fit/outpost/state/apple_mail_last_rowid` — updated with highest
+  ROWID seen
+
+---
+
+## Implementation
+
+Run the sync as a single Node.js script with embedded SQLite. This avoids N+1
+process invocations and handles all data transformation in one pass:
+
+    node scripts/sync.mjs [--days N]
+
+- `--days N` — how many days back to look on first sync (default: 30)
+
+The script:
+
+1. Finds the Mail database (`~/Library/Mail/V*/MailData/Envelope Index`)
+2. Loads last sync timestamp (or defaults to `--days` days ago for first sync)
+3. Discovers the thread grouping column (`conversation_id` or `thread_id`)
+4. Loads last-seen ROWID (or defaults to 0 for first sync)
+5. Finds threads with new messages since last sync (up to 500), using both
+   timestamp and ROWID to catch late-arriving emails (emails downloaded after a
+   delay may have `date_received` before the last sync timestamp, but their
+   ROWID will be higher than the last-seen ROWID)
+6. For each thread: fetches messages, batch-fetches recipients and attachment
+   metadata, parses `.emlx` files for full email bodies (falling back to
+   database summaries), copies attachment files to the output directory
+7. Writes one markdown file per thread to `~/.cache/fit/outpost/apple_mail/`
+8. Updates sync state (timestamp and max ROWID)
+9. Reports summary (threads processed, files written)
+
+The script imports `scripts/parse-emlx.mjs` to extract plain text bodies from
+`.emlx` / `.partial.emlx` files (handles HTML-only emails by stripping tags).
+
+## Database Schema
+
+See [references/SCHEMA.md](references/SCHEMA.md) for the complete Apple Mail
+SQLite schema including table structures, column names, and important caveats
+(e.g., `date_received` is Unix timestamps not Core Data, `addresses.comment`
+holds display names, `recipients` columns are `message`/`address` not
+`message_id`/`address_id`).
+
+## Output Format
+
+Each `{thread_id}.md` file:
+
+```markdown
+# {Base Subject}
+
+**Thread ID:** {thread_id}
+**Message Count:** {count}
+**Flags:** mailing-list, automated
+
+---
+
+### From: {sender_name} <{sender_email}>
+**Date:** {YYYY-MM-DD HH:MM:SS UTC}
+**To:** {name} <{email}>, {name2} <{email2}>
+**Cc:** {name} <{email}>
+
+{email_body_or_summary}
+
+---
+
+### From: {next_sender_name} <{next_sender_email}>
+**Date:** {next_date}
+**To:** ...
+**Cc:** ...
+
+{next_body}
+
+**Attachments:**
+- [report.pdf](attachments/{thread_id}/report.pdf)
+- image001.png *(not available)*
+```
+
+Rules:
+
+- Use the **base subject** (from `subject` column, without `subject_prefix`) as
+  the `# heading`.
+- **Flags line** — only include when at least one flag is set:
+  - `mailing-list` if any message in the thread has `list_id_hash != 0`
+  - `automated` if any message has `automated_conversation = 1`
+  - Omit the `**Flags:**` line entirely if neither flag applies.
+- **Sender** — format as `{sender_name} <{sender_email}>` when display name is
+  present, otherwise just `{sender_email}`.
+- **To/Cc** — include per-message. Format each recipient as `{name} <{email}>`
+  when name exists, otherwise just `{email}`. Omit the line if that field has no
+  recipients.
+
+## Error Handling
+
+- Database not found → Mail not configured, report and stop
+- Permission denied → Full Disk Access not granted, report and stop
+- Database locked → wait 2 seconds, retry once
+- `.emlx` / `.partial.emlx` not found → fall back to database summary field
+- `.emlx` parse error → fall back to database summary field
+- HTML-only email → strip tags and use as plain text body (handled by
+  parse-emlx.mjs)
+- `find` timeout → skip that message's body, use summary; attachment index empty
+- Attachment file not found on disk → listed as `*(not available)*` in markdown
+- Attachment copy fails (permissions, disk full) → listed as `*(not available)*`
+- Filename collision across messages → prefixed with `{message_id}_`
+- Always update sync state, even on partial success
+
+## Constraints
+
+- Open database read-only (`readOnly: true`)
+- Only sync Inbox and Sent folders
+- Limit to 500 threads per run
+- Incremental: only threads with new messages since last sync

package/templates/.claude/skills/sync-apple-mail/references/SCHEMA.md

@@ -0,0 +1,115 @@
+# Apple Mail Database Schema
+
+The Apple Mail SQLite database (`Envelope Index`) stores email metadata. Key
+tables and their actual column names (verified on macOS Sequoia / V10).
+
+Typical path: `~/Library/Mail/V10/MailData/Envelope Index`
+
+## messages (email metadata)
+
+| Column                   | Type    | Notes                                                    |
+| ------------------------ | ------- | -------------------------------------------------------- |
+| `ROWID`                  | INTEGER | Primary key                                              |
+| `sender`                 | INTEGER | FK → addresses.ROWID                                     |
+| `subject`                | INTEGER | FK → subjects.ROWID                                      |
+| `subject_prefix`         | TEXT    | `Re:`, `Fwd:`, etc. (directly on messages, not subjects) |
+| `summary`                | INTEGER | FK → summaries.ROWID                                     |
+| `date_sent`              | INTEGER | Unix timestamp (seconds since 1970-01-01 UTC)            |
+| `date_received`          | INTEGER | Unix timestamp (seconds since 1970-01-01 UTC)            |
+| `mailbox`                | INTEGER | FK → mailboxes.ROWID                                     |
+| `deleted`                | INTEGER | 1 = deleted                                              |
+| `conversation_id`        | INTEGER | Thread grouping ID                                       |
+| `list_id_hash`           | INTEGER | Non-zero = mailing list message                          |
+| `automated_conversation` | INTEGER | 1 = automated/machine-generated                          |
+| `read`                   | INTEGER | 1 = read                                                 |
+| `flagged`                | INTEGER | 1 = flagged                                              |
+
+**IMPORTANT:** `date_received` stores **Unix timestamps** (seconds since
+1970-01-01 UTC), NOT Core Data timestamps (which use 2001-01-01 epoch). Do NOT
+apply Core Data conversion.
+
+## addresses (sender and recipient addresses)
+
+| Column    | Type    | Notes                                |
+| --------- | ------- | ------------------------------------ |
+| `ROWID`   | INTEGER | Primary key                          |
+| `address` | TEXT    | Email address                        |
+| `comment` | TEXT    | Display name (e.g., `"Chen, Sarah"`) |
+
+**IMPORTANT:** The display name is in `comment`, not a `name` or `display_name`
+column.
+
+## subjects
+
+| Column    | Type    | Notes             |
+| --------- | ------- | ----------------- |
+| `ROWID`   | INTEGER | Primary key       |
+| `subject` | TEXT    | Base subject text |
+
+Note: `subject_prefix` (Re:, Fwd:, etc.) is stored on the `messages` table
+directly, not here.
+
+## recipients (To/Cc/Bcc per message)
+
+| Column     | Type    | Notes                       |
+| ---------- | ------- | --------------------------- |
+| `ROWID`    | INTEGER | Primary key                 |
+| `message`  | INTEGER | FK → messages.ROWID         |
+| `address`  | INTEGER | FK → addresses.ROWID        |
+| `type`     | INTEGER | 0 = To, 1 = Cc, 2 = Bcc     |
+| `position` | INTEGER | Order within the type group |
+
+**IMPORTANT:** Column names are `message` and `address` (not `message_id` or
+`address_id`).
+
+## summaries (Apple Intelligence email summaries)
+
+| Column    | Type    | Notes        |
+| --------- | ------- | ------------ |
+| `ROWID`   | INTEGER | Primary key  |
+| `summary` | TEXT    | Summary text |
+
+## mailboxes
+
+| Column  | Type    | Notes                            |
+| ------- | ------- | -------------------------------- |
+| `ROWID` | INTEGER | Primary key                      |
+| `url`   | TEXT    | Mailbox URL (IMAP or EWS format) |
+
+### Mailbox URL patterns
+
+Standard IMAP: `imap://user@host/INBOX`, `imap://user@host/Sent Messages` EWS
+(Exchange): `ews://UUID/Inbox`, `ews://UUID/Sent%20Items`
+
+Use case-insensitive `LIKE` patterns to match both:
+
+- `%/Inbox%` (catches IMAP `/INBOX` and EWS `/Inbox`)
+- `%/INBOX%` (explicit uppercase match)
+- `%/Sent%` (catches `Sent Messages`, `Sent Items`, `Sent%20Items`)
+
+## attachments (email attachments)
+
+| Column          | Type    | Notes                                   |
+| --------------- | ------- | --------------------------------------- |
+| `ROWID`         | INTEGER | Primary key                             |
+| `message`       | INTEGER | FK → messages.ROWID (ON DELETE CASCADE) |
+| `attachment_id` | TEXT    | Used as subdirectory name on disk       |
+| `name`          | TEXT    | Original filename (e.g., `report.pdf`)  |
+
+**Constraints:** `UNIQUE(message, attachment_id)` — each attachment within a
+message has a unique identifier.
+
+**IMPORTANT:** Column is `message` (not `message_id`), matching the convention
+used by the `recipients` table.
+
+### Filesystem mapping
+
+Attachment files on disk follow this path structure:
+
+```
+~/Library/Mail/V10/.../Attachments/{message_ROWID}/{attachment_id}/{filename}
+```
+
+- `{message_ROWID}` — the `messages.ROWID` value (same as `attachments.message`)
+- `{attachment_id}` — the `attachments.attachment_id` value
+- `{filename}` — the actual file on disk (may differ from `attachments.name`)