Calendar Scheduling skill for Claude Code

#!/usr/bin/env python3
"""Build or lint RFC 5545 iCalendar (.ics) files. Standard library only (Python 3.10+).

Build an event (UTC times by default; --keep-tzid emits TZID + a generated VTIMEZONE):
  python3 make_ics.py build --summary "Design review" --start 2026-11-03T15:00 \
      --duration 45 --tz America/New_York --organizer [email protected] \
      --attendee [email protected] --alarm 15 --method REQUEST -o invite.ics

Lint an existing file (exit 1 on errors):
  python3 make_ics.py check invite.ics
"""
from __future__ import annotations

import argparse
import re
import sys
import uuid
from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

CRLF = "\r\n"


def escape_text(value: str) -> str:
    """Escape a TEXT value per RFC 5545 section 3.3.11."""
    return (
        value.replace("\\", "\\\\")
        .replace(";", "\\;")
        .replace(",", "\\,")
        .replace("\r\n", "\\n")
        .replace("\n", "\\n")
    )


def fold(line: str) -> str:
    """Fold a content line to at most 75 octets per physical line, never splitting a UTF-8 char."""
    out, current, size = [], "", 0
    limit = 75
    for ch in line:
        n = len(ch.encode("utf-8"))
        if size + n > limit:
            out.append(current)
            current, size = " " + ch, 1 + n  # continuation lines start with one space
        else:
            current += ch
            size += n
    out.append(current)
    return CRLF.join(out)


def fmt_utc(dt: datetime) -> str:
    return dt.astimezone(timezone.utc).strftime("%Y%m%dT%H%M%SZ")


def fmt_local(dt: datetime) -> str:
    return dt.strftime("%Y%m%dT%H%M%S")


def fmt_offset(td: timedelta) -> str:
    total = int(td.total_seconds())
    sign = "+" if total >= 0 else "-"
    total = abs(total)
    return f"{sign}{total // 3600:02d}{(total % 3600) // 60:02d}"


def vtimezone(tz: ZoneInfo, year: int) -> list[str]:
    """Generate a VTIMEZONE with explicit (non-recurring) transitions for one year."""
    lines = ["BEGIN:VTIMEZONE", f"TZID:{tz.key}"]
    start = datetime(year, 1, 1, tzinfo=timezone.utc)
    prev = start.astimezone(tz)
    transitions = []
    t = start
    while t.year == year:
        nxt = t + timedelta(hours=1)
        cur = nxt.astimezone(tz)
        if cur.utcoffset() != prev.utcoffset():
            transitions.append((prev, cur))
        prev, t = cur, nxt
    if not transitions:
        off = fmt_offset(prev.utcoffset())
        lines += ["BEGIN:STANDARD", "DTSTART:19700101T000000", f"TZOFFSETFROM:{off}",
                  f"TZOFFSETTO:{off}", f"TZNAME:{prev.tzname()}", "END:STANDARD"]
    for before, after in transitions:
        kind = "DAYLIGHT" if after.dst() else "STANDARD"
        # DTSTART of an observance is expressed in the local time in effect *before* it.
        local_start = (after.astimezone(timezone.utc) + before.utcoffset()).replace(tzinfo=None)
        lines += [f"BEGIN:{kind}", f"DTSTART:{fmt_local(local_start)}",
                  f"TZOFFSETFROM:{fmt_offset(before.utcoffset())}",
                  f"TZOFFSETTO:{fmt_offset(after.utcoffset())}",
                  f"TZNAME:{after.tzname()}", f"END:{kind}"]
    lines.append("END:VTIMEZONE")
    return lines


def build(args: argparse.Namespace) -> int:
    try:
        tz = ZoneInfo(args.tz)
    except ZoneInfoNotFoundError:
        print(f"error: unknown IANA time zone {args.tz!r}", file=sys.stderr)
        return 1
    start = datetime.fromisoformat(args.start)
    start = start.replace(tzinfo=tz) if start.tzinfo is None else start.astimezone(tz)
    if args.end:
        end = datetime.fromisoformat(args.end)
        end = end.replace(tzinfo=tz) if end.tzinfo is None else end.astimezone(tz)
    else:
        end = start + timedelta(minutes=args.duration)
    if end <= start:
        print("error: end must be after start", file=sys.stderr)
        return 1
    if args.method == "REQUEST" and not args.organizer:
        print("error: METHOD:REQUEST requires --organizer", file=sys.stderr)
        return 1

    method = "CANCEL" if args.cancel else args.method
    lines = ["BEGIN:VCALENDAR", "VERSION:2.0", f"PRODID:{args.prodid}", "CALSCALE:GREGORIAN"]
    if method:
        lines.append(f"METHOD:{method}")
    if args.keep_tzid:
        lines += vtimezone(tz, start.year)
    uid = args.uid or f"{uuid.uuid4()}@{args.domain}"
    lines += ["BEGIN:VEVENT", f"UID:{uid}", f"DTSTAMP:{fmt_utc(datetime.now(timezone.utc))}"]
    if args.keep_tzid:
        lines += [f"DTSTART;TZID={tz.key}:{fmt_local(start)}", f"DTEND;TZID={tz.key}:{fmt_local(end)}"]
    else:
        lines += [f"DTSTART:{fmt_utc(start)}", f"DTEND:{fmt_utc(end)}"]
    lines += [f"SEQUENCE:{args.sequence}", f"SUMMARY:{escape_text(args.summary)}"]
    if args.description:
        lines.append(f"DESCRIPTION:{escape_text(args.description)}")
    if args.location:
        lines.append(f"LOCATION:{escape_text(args.location)}")
    if args.url:
        lines.append(f"URL:{args.url}")
    if args.organizer:
        lines.append(f"ORGANIZER:mailto:{args.organizer}")
    for a in args.attendee or []:
        lines.append(f"ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:mailto:{a}")
    lines.append(f"STATUS:{'CANCELLED' if args.cancel else 'CONFIRMED'}")
    if args.alarm is not None and not args.cancel:
        lines += ["BEGIN:VALARM", "ACTION:DISPLAY", f"DESCRIPTION:{escape_text(args.summary)}",
                  f"TRIGGER:-PT{args.alarm}M", "END:VALARM"]
    lines += ["END:VEVENT", "END:VCALENDAR"]

    body = CRLF.join(fold(l) for l in lines) + CRLF
    if args.output:
        with open(args.output, "w", encoding="utf-8", newline="") as fh:
            fh.write(body)
        print(f"wrote {args.output} (UID {uid})", file=sys.stderr)
    else:
        sys.stdout.write(body)
    return 0


DT_RE = re.compile(r"^(\d{8})(T(\d{6})(Z)?)?$")


def parse_dt(params: dict, value: str) -> datetime | None:
    m = DT_RE.match(value)
    if not m:
        return None
    if not m.group(2):
        return datetime.strptime(m.group(1), "%Y%m%d").replace(tzinfo=timezone.utc)
    dt = datetime.strptime(m.group(1) + m.group(3), "%Y%m%d%H%M%S")
    if m.group(4):
        return dt.replace(tzinfo=timezone.utc)
    tzid = params.get("TZID")
    if tzid:
        try:
            return dt.replace(tzinfo=ZoneInfo(tzid))
        except ZoneInfoNotFoundError:
            return dt.replace(tzinfo=timezone.utc)
    return dt.replace(tzinfo=timezone.utc)  # floating time; compare naively


def check(args: argparse.Namespace) -> int:
    raw = open(args.file, "rb").read()
    errors, warnings = [], []
    text = raw.decode("utf-8", errors="replace")
    if b"\r\n" not in raw:
        errors.append("lines must end with CRLF")
    if re.search(rb"(?<!\r)\n", raw):
        warnings.append("found bare LF line endings (some clients tolerate, Outlook may not)")
    physical = re.split(r"\r?\n", text)
    for i, line in enumerate(physical, 1):
        if len(line.encode("utf-8")) > 75:
            errors.append(f"physical line {i} is {len(line.encode('utf-8'))} octets (max 75; fold it)")
    # unfold
    logical = []
    for line in physical:
        if line.startswith((" ", "\t")) and logical:
            logical[-1] += line[1:]
        elif line:
            logical.append(line)

    stack, events, tzids_defined, tzids_used = [], [], set(), set()
    cal_props, method = set(), None
    for line in logical:
        name_part, _, value = line.partition(":")
        name, *param_parts = name_part.split(";")
        name = name.upper()
        params = dict(p.split("=", 1) for p in param_parts if "=" in p)
        if name == "BEGIN":
            stack.append(value.upper())
            if value.upper() == "VEVENT":
                events.append({})
            continue
        if name == "END":
            if not stack or stack[-1] != value.upper():
                errors.append(f"END:{value} does not match BEGIN:{stack[-1] if stack else '(none)'}")
            else:
                stack.pop()
            continue
        if stack == ["VCALENDAR"]:
            cal_props.add(name)
            if name == "METHOD":
                method = value.upper()
        if stack and stack[-1] == "VTIMEZONE" and name == "TZID":
            tzids_defined.add(value)
        if "TZID" in params:
            tzids_used.add(params["TZID"])
        if stack and stack[-1] == "VEVENT":
            events[-1].setdefault(name, []).append((params, value))
    if stack:
        errors.append(f"unclosed components: {stack}")
    for req in ("VERSION", "PRODID"):
        if req not in cal_props:
            errors.append(f"VCALENDAR missing {req}")
    for tzid in sorted(tzids_used - tzids_defined):
        errors.append(f"TZID={tzid} used but no matching VTIMEZONE")
    if not events:
        errors.append("no VEVENT found")
    for n, ev in enumerate(events, 1):
        label = f"VEVENT #{n}"
        for req in ("UID", "DTSTAMP", "DTSTART"):
            if req not in ev:
                errors.append(f"{label} missing {req}")
        if "DTEND" in ev and "DURATION" in ev:
            errors.append(f"{label} has both DTEND and DURATION")
        if method == "REQUEST" and "ORGANIZER" not in ev:
            errors.append(f"{label} METHOD:REQUEST requires ORGANIZER")
        if "DTSTART" in ev and "DTEND" in ev:
            s = parse_dt(*ev["DTSTART"][0])
            e = parse_dt(*ev["DTEND"][0])
            if s and e and e <= s:
                errors.append(f"{label} DTEND is not after DTSTART")
        for prop in ("SUMMARY", "DESCRIPTION", "LOCATION"):
            for _, v in ev.get(prop, []):
                if re.search(r"(?<!\\)[,;]", v):
                    warnings.append(f"{label} {prop} has unescaped ',' or ';'")
    for w in warnings:
        print(f"warn: {w}")
    for e in errors:
        print(f"error: {e}")
    print(f"{args.file}: {len(events)} event(s), {len(errors)} error(s), {len(warnings)} warning(s)")
    return 1 if errors else 0


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = p.add_subparsers(dest="cmd", required=True)
    b = sub.add_parser("build", help="write a single-event .ics")
    b.add_argument("--summary", required=True)
    b.add_argument("--start", required=True, help="ISO 8601 local time in --tz, e.g. 2026-11-03T15:00")
    b.add_argument("--end", help="ISO 8601 end; alternatively use --duration")
    b.add_argument("--duration", type=int, default=30, help="minutes (default 30)")
    b.add_argument("--tz", default="UTC", help="IANA zone of --start/--end (default UTC)")
    b.add_argument("--keep-tzid", action="store_true", help="emit TZID times plus a VTIMEZONE instead of UTC")
    b.add_argument("--uid", help="stable UID; reuse it for updates and cancellations")
    b.add_argument("--domain", default="example.invalid", help="domain suffix for generated UIDs")
    b.add_argument("--sequence", type=int, default=0, help="increment on every update to the same UID")
    b.add_argument("--description")
    b.add_argument("--location")
    b.add_argument("--url")
    b.add_argument("--organizer", help="organizer email")
    b.add_argument("--attendee", action="append", help="attendee email (repeatable)")
    b.add_argument("--alarm", type=int, help="VALARM minutes before start")
    b.add_argument("--method", choices=["PUBLISH", "REQUEST"], help="iTIP method (REQUEST for email invites)")
    b.add_argument("--cancel", action="store_true", help="emit METHOD:CANCEL / STATUS:CANCELLED")
    b.add_argument("--prodid", default="-//example//scheduling//EN")
    b.add_argument("-o", "--output")
    c = sub.add_parser("check", help="lint an existing .ics")
    c.add_argument("file")
    args = p.parse_args()
    return build(args) if args.cmd == "build" else check(args)


if __name__ == "__main__":
    sys.exit(main())