@wirecat/cli-core 0.545.0 → 0.546.0

package/dist/calendar/expand.js

@@ -0,0 +1,340 @@
+const DAY = 86_400_000;
+const WEEKDAYS = ["SU", "MO", "TU", "WE", "TH", "FR", "SA"];
+const FREQUENCIES = new Set(["DAILY", "WEEKLY", "MONTHLY", "YEARLY"]);
+const PARTS = new Set(["FREQ", "INTERVAL", "COUNT", "UNTIL", "BYDAY", "BYMONTHDAY", "BYMONTH", "BYSETPOS", "WKST"]);
+const BY_DAY = /^([+-]?\d{1,2})?(MO|TU|WE|TH|FR|SA|SU)$/u;
+const STAMP = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})(Z?))?$/u;
+/** A runaway rule (FREQ=DAILY from 1900) still ends: the window's end stops it long before this. */
+const MOST_PERIODS = 200_000;
+const numbers = (text, low, high) => {
+    const values = text.split(",").map(Number);
+    return values.every((one) => Number.isInteger(one) && one !== 0 && Math.abs(one) >= low && Math.abs(one) <= high)
+        ? values
+        : undefined;
+};
+/** RFC 5545 §3.3.10 as far as calendar feeds use it; anything else is a reason, never a guess. */
+const ruleOf = (line) => {
+    const parts = new Map();
+    for (const part of line.replace(/^RRULE:/iu, "").split(";")) {
+        const [key = "", value = ""] = part.split("=");
+        parts.set(key.trim().toUpperCase(), value.trim().toUpperCase());
+    }
+    for (const key of parts.keys())
+        if (!PARTS.has(key))
+            return `RRULE part ${key} is not expanded`;
+    const freq = parts.get("FREQ") ?? "";
+    if (!FREQUENCIES.has(freq))
+        return `RRULE FREQ=${freq} is not expanded`;
+    const rule = { freq, interval: Number(parts.get("INTERVAL") ?? 1), wkst: 1 };
+    if (!Number.isInteger(rule.interval) || rule.interval < 1)
+        return "RRULE INTERVAL is not a whole number from 1";
+    if (parts.has("COUNT")) {
+        rule.count = Number(parts.get("COUNT"));
+        if (!Number.isInteger(rule.count) || rule.count < 1)
+            return "RRULE COUNT is not a whole number from 1";
+    }
+    if (parts.has("UNTIL"))
+        rule.until = parts.get("UNTIL");
+    const days = parts.get("BYDAY");
+    if (days !== undefined) {
+        rule.byDay = [];
+        for (const day of days.split(",")) {
+            const found = BY_DAY.exec(day);
+            if (!found)
+                return `RRULE BYDAY ${day} is not a day`;
+            rule.byDay.push({ nth: found[1] ? Number(found[1]) : null, day: WEEKDAYS.indexOf(found[2]) });
+        }
+    }
+    for (const [key, field, high] of [
+        ["BYMONTHDAY", "byMonthDay", 31],
+        ["BYMONTH", "byMonth", 12],
+        ["BYSETPOS", "bySetPos", 366],
+    ]) {
+        const text = parts.get(key);
+        if (text === undefined)
+            continue;
+        const values = numbers(text, 1, high);
+        if (!values || (key === "BYMONTH" && values.some((one) => one < 0)))
+            return `RRULE ${key}=${text} is not expanded`;
+        rule[field] = values;
+    }
+    const wkst = parts.get("WKST");
+    if (wkst !== undefined) {
+        if (!WEEKDAYS.includes(wkst))
+            return `RRULE WKST=${wkst} is not a day`;
+        rule.wkst = WEEKDAYS.indexOf(wkst);
+    }
+    return rule;
+};
+const formatters = new Map();
+const formatterOf = (zone) => {
+    let formatter = formatters.get(zone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat("en-CA", {
+            timeZone: zone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hourCycle: "h23",
+        });
+        formatters.set(zone, formatter);
+    }
+    return formatter;
+};
+/** The wall clock in `zone` at `at`, as `YYYY-MM-DD` and `HH:MM:SS`. */
+const wallClock = (at, zone) => {
+    const parts = Object.fromEntries(formatterOf(zone)
+        .formatToParts(at)
+        .map((part) => [part.type, part.value]));
+    return { date: `${parts.year}-${parts.month}-${parts.day}`, time: `${parts.hour}:${parts.minute}:${parts.second}` };
+};
+const offsetAt = (at, zone) => {
+    const { date, time } = wallClock(at, zone);
+    return Date.parse(`${date}T${time}Z`) - Math.floor(at / 1000) * 1000;
+};
+/**
+ * A wall-clock time in `zone` as epoch ms. A time a clock change skips is read with the offset before the change, so it
+ * lands after it, and a repeated one takes its first moment (RFC 5545 §3.3.5): a slot is moved, never dropped.
+ */
+export const localMoment = (date, time, zone) => {
+    const guess = Date.parse(`${date}T${time}Z`);
+    const before = guess - offsetAt(guess - DAY / 2, zone);
+    const after = guess - offsetAt(guess + DAY / 2, zone);
+    const exact = [before, after].filter((at) => {
+        const shown = wallClock(at, zone);
+        return shown.date === date && shown.time === time;
+    });
+    return exact.length === 2 ? Math.min(before, after) : (exact[0] ?? before);
+};
+const plusDays = (date, days) => {
+    const [year, month, day] = date.split("-").map(Number);
+    return new Date(Date.UTC(year, month - 1, day + days)).toISOString().slice(0, 10);
+};
+const dayOf = (date) => new Date(`${date}T00:00:00Z`).getUTCDay();
+const pad = (value) => String(value).padStart(2, "0");
+const dateOf = (year, month, day) => `${year}-${pad(month)}-${pad(day)}`;
+const daysIn = (year, month) => new Date(Date.UTC(year, month, 0)).getUTCDate();
+const daysBetween = (from, to) => Math.round((Date.parse(to) - Date.parse(from)) / DAY);
+/** The days of a set that BYDAY names: every such weekday, or with a number the nth of them, from the end if negative. */
+const pickDays = (all, byDay) => byDay.flatMap(({ nth, day }) => {
+    const matching = all.filter((date) => dayOf(date) === day);
+    if (nth === null)
+        return matching;
+    const picked = nth > 0 ? matching[nth - 1] : matching[matching.length + nth];
+    return picked ? [picked] : [];
+});
+const monthDays = (year, month) => Array.from({ length: daysIn(year, month) }, (_, n) => dateOf(year, month, n + 1));
+const byMonthDay = (year, month, days) => days.flatMap((day) => {
+    const size = daysIn(year, month);
+    const at = day > 0 ? day : size + day + 1;
+    return at >= 1 && at <= size ? [dateOf(year, month, at)] : [];
+});
+/** One month's days under BYMONTHDAY and BYDAY, or the start's day of the month without either. */
+const inMonth = (year, month, rule, startDay) => {
+    const byDays = rule.byDay ? pickDays(monthDays(year, month), rule.byDay) : undefined;
+    const byDates = rule.byMonthDay ? byMonthDay(year, month, rule.byMonthDay) : undefined;
+    if (byDays && byDates)
+        return byDates.filter((date) => byDays.includes(date));
+    if (byDays)
+        return byDays;
+    if (byDates)
+        return byDates;
+    return startDay <= daysIn(year, month) ? [dateOf(year, month, startDay)] : [];
+};
+const setPos = (dates, positions) => {
+    if (!positions)
+        return dates;
+    return positions.flatMap((at) => {
+        const picked = at > 0 ? dates[at - 1] : dates[dates.length + at];
+        return picked ? [picked] : [];
+    });
+};
+const sorted = (dates) => [...new Set(dates)].sort();
+/** The candidate dates of the nth period of the rule, in order. */
+const periodDates = (rule, start, n) => {
+    const [year, month, day] = start.split("-").map(Number);
+    const step = n * rule.interval;
+    const inMonths = (dates) => rule.byMonth ? dates.filter((date) => rule.byMonth?.includes(Number(date.slice(5, 7)))) : dates;
+    if (rule.freq === "DAILY") {
+        const date = plusDays(start, step);
+        const [y, m] = [Number(date.slice(0, 4)), Number(date.slice(5, 7))];
+        if (rule.byMonthDay && !byMonthDay(y, m, rule.byMonthDay).includes(date))
+            return [];
+        if (rule.byDay && !rule.byDay.some(({ day: weekday }) => weekday === dayOf(date)))
+            return [];
+        return inMonths([date]);
+    }
+    if (rule.freq === "WEEKLY") {
+        const weekStart = plusDays(plusDays(start, -((dayOf(start) - rule.wkst + 7) % 7)), 7 * step);
+        const days = rule.byDay ? rule.byDay.map(({ day: weekday }) => weekday) : [dayOf(start)];
+        const dates = days.map((weekday) => plusDays(weekStart, (weekday - rule.wkst + 7) % 7));
+        return setPos(sorted(inMonths(dates)), rule.bySetPos);
+    }
+    if (rule.freq === "MONTHLY") {
+        const total = month - 1 + step;
+        const [y, m] = [year + Math.floor(total / 12), (total % 12) + 1];
+        if (rule.byMonth && !rule.byMonth.includes(m))
+            return [];
+        return setPos(sorted(inMonth(y, m, rule, day)), rule.bySetPos);
+    }
+    const y = year + step;
+    if (!rule.byMonth && rule.byDay && !rule.byMonthDay) {
+        const all = Array.from({ length: 12 }, (_, at) => monthDays(y, at + 1)).flat();
+        return setPos(sorted(pickDays(all, rule.byDay)), rule.bySetPos);
+    }
+    const months = rule.byMonth ?? (rule.byMonthDay ? Array.from({ length: 12 }, (_, at) => at + 1) : [month]);
+    return setPos(sorted(months.flatMap((m) => inMonth(y, m, rule, day))), rule.bySetPos);
+};
+/** The first day of the nth period, so a rule that matches no day still stops at the window's end. */
+const periodStart = (rule, start, n) => {
+    const step = n * rule.interval;
+    if (rule.freq === "DAILY")
+        return plusDays(start, step);
+    if (rule.freq === "WEEKLY")
+        return plusDays(start, 7 * step - ((dayOf(start) - rule.wkst + 7) % 7));
+    const [year, month] = start.split("-").map(Number);
+    if (rule.freq === "YEARLY")
+        return dateOf(year + step, 1, 1);
+    const total = month - 1 + step;
+    return dateOf(year + Math.floor(total / 12), (total % 12) + 1, 1);
+};
+/** A DATE or DATE-TIME of UNTIL, EXDATE or RDATE: `date` always, `at` for a time; floating times are read in `zone`. */
+const stampOf = (text, zone, tzid) => {
+    const found = STAMP.exec(text.trim());
+    if (!found)
+        return undefined;
+    const [, year, month, day, hour, minute, second, utc] = found;
+    const date = `${year}-${month}-${day}`;
+    if (hour === undefined)
+        return { date };
+    const time = `${hour}:${minute}:${second}`;
+    return { date, at: utc ? Date.parse(`${date}T${time}Z`) : localMoment(date, time, tzid ?? zone) };
+};
+/** The values of every `EXDATE` or `RDATE` line, with its TZID; a PERIOD's start stands for it. */
+const listed = (lines, name, zone) => lines
+    .filter((line) => line.toUpperCase().startsWith(name))
+    .flatMap((line) => {
+    const colon = line.indexOf(":");
+    const tzid = /;TZID=([^;:]+)/iu.exec(line.slice(0, colon))?.[1]?.replace(/^"|"$/gu, "");
+    return line
+        .slice(colon + 1)
+        .split(",")
+        .map((value) => stampOf(value.split("/")[0] ?? "", zone, tzid))
+        .filter((one) => one !== undefined);
+});
+/** Why a series cannot be expanded here, or `null` when it can. */
+export const unexpandable = (recurrence) => {
+    const rules = (recurrence ?? []).filter((line) => /^RRULE[:;]/iu.test(line));
+    if ((recurrence ?? []).some((line) => /^EXRULE[:;]/iu.test(line)))
+        return "EXRULE is not expanded";
+    if (rules.length > 1)
+        return "more than one RRULE is not expanded";
+    const [line] = rules;
+    if (line === undefined)
+        return null;
+    const rule = ruleOf(line);
+    return typeof rule === "string" ? rule : null;
+};
+const utcStamp = (at) => new Date(at)
+    .toISOString()
+    .replace(/[-:]/gu, "")
+    .replace(/\.\d{3}/u, "");
+/**
+ * The slots of a series inside the window, as occurrences: its RRULE, plus RDATE, less EXDATE, which come back
+ * `cancelled` so a stored slot is cancelled. Times repeat in the series' own zone, so a weekly 10:00 stays 10:00
+ * across a clock change. An override (an iCalendar RECURRENCE-ID) takes the place of the slot it names.
+ */
+export const expandSeries = (series, window, overrides = []) => {
+    const recurrence = series.recurrence ?? [];
+    if (unexpandable(recurrence) !== null || series.startsAt == null)
+        return [];
+    const zone = series.timezone ?? "UTC";
+    const allDay = series.allDay === true && typeof series.startDate === "string";
+    const start = allDay ? series.startDate : wallClock(series.startsAt, zone).date;
+    const time = allDay ? "00:00:00" : wallClock(series.startsAt, zone).time;
+    const length = (series.endsAt ?? series.startsAt) - series.startsAt;
+    const days = allDay && series.endDate ? Math.max(1, daysBetween(start, series.endDate)) : 1;
+    const line = recurrence.find((one) => /^RRULE[:;]/iu.test(one));
+    const rule = line === undefined ? undefined : ruleOf(line);
+    const until = rule?.until === undefined ? undefined : stampOf(rule.until, zone);
+    const momentOf = (date) => (allDay ? localMoment(date, "00:00:00", zone) : localMoment(date, time, zone));
+    const past = (date, at) => until !== undefined && (allDay || until.at === undefined ? date > until.date : at > until.at);
+    const dates = [{ date: start, at: series.startsAt }];
+    if (rule) {
+        let count = 1;
+        outer: for (let n = 0; n < MOST_PERIODS; n++) {
+            if (Date.parse(periodStart(rule, start, n)) > window.to + DAY)
+                break;
+            for (const date of periodDates(rule, start, n)) {
+                if (date <= start)
+                    continue;
+                const at = momentOf(date);
+                if (past(date, at) || (rule.count !== undefined && count >= rule.count) || at >= window.to)
+                    break outer;
+                dates.push({ date, at });
+                count++;
+            }
+        }
+    }
+    for (const extra of listed(recurrence, "RDATE", zone)) {
+        const at = allDay ? momentOf(extra.date) : (extra.at ?? momentOf(extra.date));
+        if (!dates.some((one) => one.at === at))
+            dates.push({ date: extra.date, at });
+    }
+    const excluded = listed(recurrence, "EXDATE", zone);
+    const isExcluded = ({ date, at }) => excluded.some((one) => (allDay || one.at === undefined ? one.date === date : one.at === at));
+    const originalOf = ({ date, at }) => (allDay ? Date.parse(`${date}T00:00:00Z`) : at);
+    const replaced = new Map(overrides.map((one) => [one.originalStartsAt, one]));
+    const inWindow = (entry) => entry.startsAt != null &&
+        entry.startsAt < window.to &&
+        Math.max(entry.endsAt ?? entry.startsAt, entry.startsAt + 1) > window.from;
+    const slotId = (original) => `${series.externalId}_${allDay ? new Date(original).toISOString().slice(0, 10).replaceAll("-", "") : utcStamp(original)}`;
+    const slots = [];
+    for (const one of dates.sort((a, b) => a.at - b.at)) {
+        const original = originalOf(one);
+        const override = replaced.get(original);
+        replaced.delete(original);
+        const cancelled = isExcluded(one);
+        const base = override && !cancelled ? override : series;
+        const endDate = allDay ? plusDays(one.date, days) : null;
+        const slot = {
+            ...base,
+            externalId: slotId(original),
+            kind: "occurrence",
+            seriesExternalId: series.externalId,
+            originalStartsAt: original,
+            exception: cancelled || override !== undefined,
+            status: cancelled ? "cancelled" : (base.status ?? "confirmed"),
+            recurrence: null,
+            etag: null,
+            ...(override && !cancelled
+                ? {}
+                : {
+                    startsAt: one.at,
+                    endsAt: allDay ? momentOf(endDate) : one.at + length,
+                    startDate: allDay ? one.date : null,
+                    endDate,
+                }),
+        };
+        if (inWindow(slot))
+            slots.push(slot);
+    }
+    for (const [original, override] of replaced) {
+        const slot = {
+            ...override,
+            externalId: slotId(original),
+            kind: "occurrence",
+            seriesExternalId: series.externalId,
+            originalStartsAt: original,
+            exception: true,
+            recurrence: null,
+            etag: null,
+        };
+        if (inWindow(slot))
+            slots.push(slot);
+    }
+    return slots;
+};

package/dist/calendar/feeds.d.ts

@@ -0,0 +1,96 @@
+import type { CalendarInput, EntryInput, EventStore, StoredCalendar } from "../meetings/index.js";
+import { type IcsEvent } from "./ics.js";
+import type { CalendarExpander, CalendarSource, SyncWindow } from "./source.js";
+import { type CalendarSyncOptions, type CalendarSyncReport } from "./sync.js";
+/** A feed's calendar id: `ics:` and a random id, never the address or anything made from it. */
+export declare const FEED_PREFIX = "ics:";
+export declare const isFeedCalendar: (calendar: Pick<StoredCalendar, "externalId">) => boolean;
+/** One feed the profile follows. `url` may hold a private token: it is a secret, kept as one and never printed. */
+export interface FeedRecord {
+    id: string;
+    url: string;
+    /** The owner's `--title`, or the feed's own name when he gave none. */
+    title: string | null;
+}
+/** Where the profile's feeds are kept: the keyring, or a 0600 file, as the CLI keeps its other secrets. */
+export interface FeedRegistry {
+    read(): Promise<FeedRecord[]>;
+    write(feeds: FeedRecord[]): Promise<void>;
+}
+export interface FeedLimits {
+    /** Decoded bytes, so a compressed answer cannot grow past it. */
+    maxBytes: number;
+    timeoutMs: number;
+    redirects: number;
+}
+export declare const FEED_LIMITS: FeedLimits;
+export interface FeedSyncStats {
+    calendarId: number;
+    events: number;
+    skipped: number;
+}
+/** The profile's iCalendar feeds: a source the engine expands locally, and how one is added and forgotten. */
+export interface CalendarFeeds {
+    readonly source: CalendarSource;
+    readonly expand: CalendarExpander;
+    /** Reads the feed once to check it, then keeps its address. */
+    add(url: string, options?: {
+        title?: string;
+    }): Promise<{
+        calendar: CalendarInput;
+        events: number;
+    }>;
+    /** Forgets the feed's address; its stored events are the caller's to drop. */
+    remove(externalId: string): Promise<void>;
+    /** What the last sync read from each feed, and how many of its events it could not take. */
+    stats(): FeedSyncStats[];
+}
+/** `webcal://` is `https://`: calendar apps write it so a click opens them, and the feed itself is served over https. */
+export declare const feedAddress: (text: string) => URL;
+export interface FetchFeedOptions {
+    /** Names the feed in errors; the address never appears in one. */
+    name: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    limits?: FeedLimits;
+}
+/**
+ * The feed's text: http or https, each redirect followed by hand and only to https, the body cut off at its limit and
+ * the request at its time. Errors name the feed and the status, never the address, which may hold a token.
+ */
+export declare const fetchFeed: (address: string, options: FetchFeedOptions) => Promise<string>;
+/** One feed event in the neutral words, its text cleaned as an invitation's is: feed text is somebody else's. */
+export declare const feedEntry: (event: IcsEvent, zone: string) => EntryInput;
+export interface FeedRead {
+    entries: EntryInput[];
+    overrides: Map<string, (EntryInput & {
+        originalStartsAt: number;
+    })[]>;
+    name: string | null;
+    timezone: string | null;
+    events: number;
+    skipped: number;
+}
+/** A feed's events inside the window, its series with their overrides, and what it could not take. */
+export declare const readFeed: (text: string, zone: string, window?: SyncWindow) => FeedRead;
+export interface IcsFeedsOptions {
+    registry: FeedRegistry;
+    /** The zone a floating time is read in when the feed names none. */
+    zone: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    limits?: FeedLimits;
+}
+/**
+ * The profile's feeds as one calendar source with `expands: "local"` and a full list on every sync: a feed has no
+ * cursor. The expander a sync is given reads the overrides of the feed `changes()` just read.
+ */
+export declare const icsFeeds: (options: IcsFeedsOptions) => CalendarFeeds;
+export type FeedsSyncReport = CalendarSyncReport & {
+    feeds?: FeedSyncStats[];
+};
+/**
+ * The provider's calendars, then the profile's feeds, under one budget and in one report: the feeds are calendars of
+ * the same account, synced by their own source because they expand their series here.
+ */
+export declare const syncWithFeeds: (source: CalendarSource, feeds: CalendarFeeds | undefined, store: EventStore, options: CalendarSyncOptions) => Promise<FeedsSyncReport>;