@forwardimpact/basecamp 0.1.0

package/template/.claude/skills/sync-apple-calendar/references/SCHEMA.md

@@ -0,0 +1,80 @@
+# Apple Calendar Database Schema
+
+The Apple Calendar SQLite database uses Core Data. Key tables and their actual
+column names (verified on macOS Sonoma+).
+
+## CalendarItem (events and reminders)
+
+| Column           | Type    | Notes                                                      |
+| ---------------- | ------- | ---------------------------------------------------------- |
+| `ROWID`          | INTEGER | Primary key                                                |
+| `summary`        | TEXT    | Event title                                                |
+| `start_date`     | REAL    | Core Data timestamp (seconds since 2001-01-01 UTC)         |
+| `end_date`       | REAL    | Core Data timestamp (null for all-day events)              |
+| `start_tz`       | TEXT    | IANA timezone (e.g., `Europe/Paris`), `_float` for all-day |
+| `end_tz`         | TEXT    | IANA timezone, `_float` for all-day                        |
+| `all_day`        | INTEGER | 1 = all-day event                                          |
+| `location_id`    | INTEGER | FK → Location.ROWID                                        |
+| `description`    | TEXT    | Event notes/body                                           |
+| `organizer_id`   | INTEGER | FK → Identity.ROWID                                        |
+| `calendar_id`    | INTEGER | FK → Calendar.ROWID                                        |
+| `has_attendees`  | INTEGER | 1 = event has attendees                                    |
+| `conference_url` | TEXT    | Video call URL (often null — check description too)        |
+| `entity_type`    | INTEGER | 2 = calendar event                                         |
+
+## Identity (organizer info)
+
+| Column         | Type | Notes                                                         |
+| -------------- | ---- | ------------------------------------------------------------- |
+| `display_name` | TEXT | Full name (e.g., `"Chen, Sarah"`)                             |
+| `address`      | TEXT | Email with `mailto:` prefix (e.g., `"mailto:sarah@acme.com"`) |
+| `first_name`   | TEXT | Usually null — `display_name` is the reliable field           |
+| `last_name`    | TEXT | Usually null — `display_name` is the reliable field           |
+
+**IMPORTANT:** Identity does NOT have an `email` column. Use `address` and strip
+the `mailto:` prefix. Use `display_name` for the name (not
+`first_name`/`last_name`, which are typically null).
+
+## Participant (attendees and organizer)
+
+| Column        | Type    | Notes                                              |
+| ------------- | ------- | -------------------------------------------------- |
+| `ROWID`       | INTEGER | Primary key                                        |
+| `entity_type` | INTEGER | 7 = attendee, 8 = organizer                        |
+| `owner_id`    | INTEGER | FK → CalendarItem.ROWID                            |
+| `identity_id` | INTEGER | FK → Identity.ROWID (for display_name lookup)      |
+| `email`       | TEXT    | Email address (no `mailto:` prefix)                |
+| `status`      | INTEGER | EKParticipantStatus (see mapping below)            |
+| `role`        | INTEGER | 0 = unknown, 1 = required, 2 = optional, 3 = chair |
+| `is_self`     | INTEGER | 1 = this is the calendar owner                     |
+
+**IMPORTANT:** Participant does NOT have `display_name`, `first_name`, or
+`last_name` columns. To get the attendee's name, JOIN with Identity via
+`identity_id`. There is NO `Attendee` table — only use `Participant`.
+
+### EKParticipantStatus mapping
+
+| Value | Status     |
+| ----- | ---------- |
+| 0     | unknown    |
+| 1     | pending    |
+| 2     | accepted   |
+| 3     | declined   |
+| 4     | tentative  |
+| 5     | delegated  |
+| 6     | completed  |
+| 7     | in-process |
+
+## Calendar (calendar metadata)
+
+| Column  | Type    | Notes         |
+| ------- | ------- | ------------- |
+| `ROWID` | INTEGER | Primary key   |
+| `title` | TEXT    | Calendar name |
+
+## Location
+
+| Column  | Type    | Notes           |
+| ------- | ------- | --------------- |
+| `ROWID` | INTEGER | Primary key     |
+| `title` | TEXT    | Location string |

package/template/.claude/skills/sync-apple-calendar/scripts/sync.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Sync Apple Calendar events to ~/.cache/fit/basecamp/apple_calendar/ as JSON.
+
+Queries the macOS Calendar SQLite database for events in a 14-day sliding
+window (past and future) and writes one JSON file per event.
+
+Usage: python3 scripts/sync.py
+
+Requires: macOS with Calendar app configured and Full Disk Access granted.
+"""
+
+import json
+import os
+import subprocess
+from datetime import datetime, timezone, timedelta
+
+EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)
+OUTDIR = os.path.expanduser("~/.cache/fit/basecamp/apple_calendar")
+
+DB_PATHS = [
+    os.path.expanduser(
+        "~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb"
+    ),
+    os.path.expanduser("~/Library/Calendars/Calendar.sqlitedb"),
+]
+
+STATUS_MAP = {
+    0: "unknown",
+    1: "pending",
+    2: "accepted",
+    3: "declined",
+    4: "tentative",
+    5: "delegated",
+    6: "completed",
+    7: "in-process",
+}
+
+ROLE_MAP = {0: "unknown", 1: "required", 2: "optional", 3: "chair"}
+
+
+def find_db():
+    db = next((p for p in DB_PATHS if os.path.exists(p)), None)
+    if not db:
+        print("Error: Apple Calendar database not found. Is Calendar configured?")
+        exit(1)
+    return db
+
+
+def query(db, sql):
+    result = subprocess.run(
+        ["sqlite3", "-readonly", "-json", db, sql], capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        if "database is locked" in result.stderr:
+            import time
+
+            time.sleep(2)
+            result = subprocess.run(
+                ["sqlite3", "-readonly", "-json", db, sql],
+                capture_output=True,
+                text=True,
+            )
+        if result.returncode != 0:
+            print(f"SQLite error: {result.stderr.strip()}")
+            return []
+    return json.loads(result.stdout) if result.stdout.strip() else []
+
+
+def coredata_to_iso(ts, tz_name=None):
+    """Convert Core Data timestamp to ISO 8601."""
+    if ts is None:
+        return None
+    dt = EPOCH + timedelta(seconds=ts)
+    if tz_name and tz_name != "_float":
+        try:
+            from zoneinfo import ZoneInfo
+
+            dt = dt.astimezone(ZoneInfo(tz_name))
+        except Exception:
+            pass
+    return dt.isoformat()
+
+
+def main():
+    db = find_db()
+    os.makedirs(OUTDIR, exist_ok=True)
+
+    now = datetime.now(timezone.utc)
+    start = now - timedelta(days=14)
+    end = now + timedelta(days=14)
+    START_TS = (start - EPOCH).total_seconds()
+    END_TS = (end - EPOCH).total_seconds()
+
+    # Fetch events with a single query
+    events = query(
+        db,
+        f"""
+    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 <= {END_TS}
+        AND COALESCE(ci.end_date, ci.start_date) >= {START_TS}
+        AND ci.summary IS NOT NULL
+        AND ci.summary != ''
+    ORDER BY ci.start_date ASC
+    LIMIT 1000;
+    """,
+    )
+
+    # Collect event IDs for batch attendee query
+    event_ids = [str(ev["id"]) for ev in events]
+
+    # Batch-fetch all attendees in one query (avoids N+1)
+    attendees_by_event = {}
+    if event_ids:
+        id_list = ",".join(event_ids)
+        attendees_raw = query(
+            db,
+            f"""
+        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 ({id_list})
+            AND p.entity_type = 7;
+        """,
+        )
+        for a in attendees_raw:
+            oid = a["owner_id"]
+            attendees_by_event.setdefault(oid, []).append(a)
+
+    # Write event JSON files
+    written_ids = set()
+    for ev in events:
+        eid = ev["id"]
+
+        # Organizer — strip mailto: prefix from Identity.address
+        org_email = ev.get("organizer_email") or None
+        if org_email and org_email.startswith("mailto:"):
+            org_email = org_email[7:]
+
+        # Attendees
+        attendees = []
+        for a in attendees_by_event.get(eid, []):
+            if not a.get("email"):
+                continue
+            attendees.append(
+                {
+                    "email": a["email"],
+                    "name": (a.get("display_name") or "").strip() or None,
+                    "status": STATUS_MAP.get(a.get("status"), "unknown"),
+                    "role": ROLE_MAP.get(a.get("role"), "unknown"),
+                    "self": bool(a.get("is_self")),
+                }
+            )
+
+        is_all_day = bool(ev.get("all_day"))
+
+        event_json = {
+            "id": f"apple_cal_{eid}",
+            "summary": ev["summary"],
+            "start": {
+                "dateTime": coredata_to_iso(ev["start_date"], ev.get("start_tz")),
+                "timeZone": ev.get("start_tz")
+                if ev.get("start_tz") != "_float"
+                else None,
+            },
+            "end": {
+                "dateTime": coredata_to_iso(
+                    ev["end_date"] if ev["end_date"] else ev["start_date"],
+                    ev.get("end_tz"),
+                ),
+                "timeZone": ev.get("end_tz")
+                if ev.get("end_tz") != "_float"
+                else None,
+            },
+            "allDay": is_all_day,
+            "location": ev.get("location") or None,
+            "description": ev.get("description") or None,
+            "conferenceUrl": ev.get("conference_url") or None,
+            "calendar": ev.get("calendar_name") or None,
+            "organizer": {
+                "email": org_email,
+                "name": (ev.get("organizer_name") or "").strip() or None,
+            }
+            if org_email
+            else None,
+            "attendees": attendees if attendees else None,
+        }
+
+        filepath = os.path.join(OUTDIR, f"{eid}.json")
+        with open(filepath, "w") as f:
+            json.dump(event_json, f, indent=2)
+        written_ids.add(f"{eid}.json")
+
+    # Clean up events outside the window
+    removed = 0
+    for fname in os.listdir(OUTDIR):
+        if fname.endswith(".json") and fname not in written_ids:
+            os.remove(os.path.join(OUTDIR, fname))
+            removed += 1
+
+    print(f"Apple Calendar Sync Complete")
+    print(f"Events synced: {len(written_ids)}")
+    print(f"Time window: {start.date()} to {end.date()}")
+    print(f"Files cleaned up: {removed} (outside window)")
+    print(f"Output: {OUTDIR}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,131 @@
+---
+name: sync-apple-mail
+description: Sync email threads from the macOS Mail app's local SQLite database into ~/.cache/fit/basecamp/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/basecamp/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/basecamp/state/apple_mail_last_sync` — last sync timestamp
+  (single-line text file)
+- `~/Library/Mail/V*/MailData/Envelope Index` — Apple Mail SQLite database
+
+## Outputs
+
+- `~/.cache/fit/basecamp/apple_mail/{thread_id}.md` — one markdown file per
+  email thread
+- `~/.cache/fit/basecamp/state/apple_mail_last_sync` — updated with new sync
+  timestamp
+
+---
+
+## Implementation
+
+Run the sync as a single Python script. This avoids N+1 shell invocations and
+handles all data transformation in one pass:
+
+    python3 scripts/sync.py
+
+The script:
+
+1. Finds the Mail database (`~/Library/Mail/V*/MailData/Envelope Index`)
+2. Loads last sync timestamp (or defaults to 30 days ago for first sync)
+3. Discovers the thread grouping column (`conversation_id` or `thread_id`)
+4. Finds threads with new messages since last sync (up to 500)
+5. For each thread: fetches messages, batch-fetches recipients, parses `.emlx`
+   files for full email bodies (falling back to database summaries)
+6. Writes one markdown file per thread to `~/.cache/fit/basecamp/apple_mail/`
+7. Updates sync state timestamp
+8. Reports summary (threads processed, files written)
+
+The script calls `scripts/parse-emlx.py` 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}
+```
+
+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.py)
+- `find` timeout → skip that message's body, use summary
+- Always update sync state, even on partial success
+
+## Constraints
+
+- Open database read-only (`-readonly`)
+- Only sync Inbox and Sent folders
+- Limit to 500 threads per run
+- Incremental: only threads with new messages since last sync

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

@@ -0,0 +1,88 @@
+# 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., `"Olsson, Dick"`) |
+
+**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`)

package/template/.claude/skills/sync-apple-mail/scripts/parse-emlx.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Parse a macOS Mail .emlx or .partial.emlx file and output the plain text body.
+
+Usage: python3 scripts/parse-emlx.py <path-to-emlx-file>
+
+The .emlx format is: first line = byte count, then RFC822 message, then Apple
+plist. This script extracts and prints the plain text body.
+
+If the email has no text/plain part (HTML-only), falls back to stripping HTML
+tags and outputting as plain text.
+
+Exit codes:
+  0 — success (body printed to stdout)
+  1 — file not found or parse error (message on stderr)
+"""
+
+import email
+import html as html_mod
+import re
+import sys
+
+
+def html_to_text(html):
+    """Strip HTML tags and convert to plain text. Uses only stdlib."""
+    # Remove style and script blocks
+    text = re.sub(
+        r"<(style|script)[^>]*>.*?</\1>", "", html, flags=re.DOTALL | re.IGNORECASE
+    )
+    # Replace br and p tags with newlines
+    text = re.sub(r"<br\s*/?\s*>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</p>", "\n", text, flags=re.IGNORECASE)
+    # Strip remaining tags
+    text = re.sub(r"<[^>]+>", "", text)
+    # Decode HTML entities
+    text = html_mod.unescape(text)
+    # Collapse whitespace
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def extract_body(msg):
+    """Extract plain text body from an email message, with HTML fallback."""
+    body = None
+    html_body = None
+
+    if msg.is_multipart():
+        for part in msg.walk():
+            ct = part.get_content_type()
+            if ct == "text/plain" and body is None:
+                charset = part.get_content_charset() or "utf-8"
+                payload = part.get_payload(decode=True)
+                if payload:
+                    body = payload.decode(charset, errors="replace")
+            elif ct == "text/html" and html_body is None:
+                charset = part.get_content_charset() or "utf-8"
+                payload = part.get_payload(decode=True)
+                if payload:
+                    html_body = payload.decode(charset, errors="replace")
+    else:
+        ct = msg.get_content_type()
+        charset = msg.get_content_charset() or "utf-8"
+        payload = msg.get_payload(decode=True)
+        if payload:
+            text = payload.decode(charset, errors="replace")
+            if ct == "text/plain":
+                body = text
+            elif ct == "text/html":
+                html_body = text
+
+    if body:
+        return body
+    elif html_body:
+        return html_to_text(html_body)
+    return None
+
+
+def parse_emlx(path):
+    try:
+        with open(path, "rb") as f:
+            byte_count = int(f.readline())
+            raw = f.read(byte_count)
+            msg = email.message_from_bytes(raw)
+
+            print(f"From: {msg.get('From', 'Unknown')}")
+            print(f"Date: {msg.get('Date', '')}")
+            print("---")
+
+            body = extract_body(msg)
+            if body:
+                print(body)
+    except FileNotFoundError:
+        print(f"Error: File not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error parsing {path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python3 scripts/parse-emlx.py <path>", file=sys.stderr)
+        sys.exit(1)
+    parse_emlx(sys.argv[1])