@wirecat/cli-core 0.545.0 → 0.547.0

package/dist/calendar/feeds.js

@@ -0,0 +1,324 @@
+import { createHash, randomBytes } from "node:crypto";
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { zonedMoment } from "@wirecat/cli-base/query";
+import { runBudget } from "../background/budget.js";
+import { calendarText, joinUrlWithoutQuery } from "../meetings/index.js";
+import { expandSeries, unexpandable } from "./expand.js";
+import { readIcs } from "./ics.js";
+import { syncCalendars } from "./sync.js";
+/** A feed's calendar id: `ics:` and a random id, never the address or anything made from it. */
+export const FEED_PREFIX = "ics:";
+export const isFeedCalendar = (calendar) => calendar.externalId.startsWith(FEED_PREFIX);
+export const FEED_LIMITS = { maxBytes: 10 * 1024 * 1024, timeoutMs: 30_000, redirects: 5 };
+const invalidAddress = (why) => new CliError("validation_error", `the feed address ${why}`, { reason: "feed.address-invalid" });
+/** `webcal://` is `https://`: calendar apps write it so a click opens them, and the feed itself is served over https. */
+export const feedAddress = (text) => {
+    let url;
+    try {
+        url = new URL(text.trim().replace(/^webcals?:\/\//iu, "https://"));
+    }
+    catch {
+        throw invalidAddress("is not a URL; give the feed's https:// or webcal:// address");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw invalidAddress("must start with https://, http:// or webcal://");
+    if (url.username || url.password)
+        throw invalidAddress("must not hold a user name or a password");
+    return url;
+};
+const sameAddress = (a, b) => feedAddress(a).href === feedAddress(b).href;
+const readBody = async (response, name, maxBytes) => {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            await reader.cancel();
+            throw new CliError("validation_error", `${name} is larger than ${Math.round(maxBytes / 1024 / 1024)} MB`, {
+                reason: "feed.too-large",
+            });
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder("utf-8").decode(Buffer.concat(chunks));
+};
+const STATUS_ERRORS = {
+    401: ["authentication_error", "feed.refused"],
+    403: ["permission_error", "feed.refused"],
+    404: ["not_found", "feed.gone"],
+    410: ["not_found", "feed.gone"],
+};
+/**
+ * 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 const fetchFeed = async (address, options) => {
+    const { name, limits = FEED_LIMITS } = options;
+    const run = options.fetch ?? fetch;
+    const timeout = AbortSignal.timeout(limits.timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let url = feedAddress(address);
+    try {
+        for (let hop = 0;; hop++) {
+            const response = await run(url, {
+                redirect: "manual",
+                signal,
+                headers: { accept: "text/calendar, text/plain;q=0.5, */*;q=0.1" },
+            });
+            const location = response.headers.get("location");
+            if (response.status >= 300 && response.status < 400 && location) {
+                await response.body?.cancel();
+                if (hop >= limits.redirects)
+                    throw new CliError("provider_error", `${name} sent the request on more than ${limits.redirects} times`, {
+                        reason: "feed.refused",
+                    });
+                const next = new URL(location, url);
+                if (next.protocol !== "https:")
+                    throw new CliError("validation_error", `${name} sent the request on to an address that is not https`, {
+                        reason: "feed.redirect-refused",
+                    });
+                url = next;
+                continue;
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                const [code, reason] = STATUS_ERRORS[response.status] ?? ["provider_error", "feed.refused"];
+                throw new CliError(code, `${name} answered HTTP ${response.status}`, {
+                    reason,
+                    status: response.status,
+                    retryable: response.status >= 500 || response.status === 429,
+                });
+            }
+            return await readBody(response, name, limits.maxBytes);
+        }
+    }
+    catch (error) {
+        if (isCliError(error))
+            throw error;
+        if (options.signal?.aborted)
+            throw new CliError("cancelled", `reading ${name} was cancelled`);
+        if (timeout.aborted)
+            throw new CliError("timeout", `${name} did not answer within ${Math.round(limits.timeoutMs / 1000)} s`, {
+                reason: "feed.timeout",
+                retryable: true,
+            });
+        // The cause's code only: a fetch error's message may quote the address.
+        const cause = error.cause?.code;
+        throw new CliError("network_error", `${name} could not be reached${typeof cause === "string" ? ` (${cause})` : ""}`, {
+            reason: "feed.unreachable",
+            retryable: true,
+        });
+    }
+};
+const SPAN = { start: 0, end: 0 };
+const firstLink = (text) => text?.match(/https?:\/\/[^\s<>"')\]]+/iu)?.[0];
+/** One feed event in the neutral words, its text cleaned as an invitation's is: feed text is somebody else's. */
+export const feedEntry = (event, zone) => {
+    const allDay = event.startDate !== undefined;
+    const timezone = allDay ? zone : (event.timezone ?? null);
+    const recurrence = event.recurrence?.length ? event.recurrence : null;
+    return {
+        externalId: event.uid,
+        kind: recurrence ? "series" : "single",
+        icalUid: event.uid,
+        status: event.status ?? "confirmed",
+        title: calendarText(event.title, { dropSecretLines: false }),
+        description: calendarText(event.description),
+        location: calendarText(event.location),
+        startsAt: allDay ? zonedMoment(event.startDate, zone, SPAN) : (event.startsAt ?? null),
+        endsAt: allDay ? zonedMoment(event.endDate, zone, SPAN) : (event.endsAt ?? null),
+        allDay,
+        startDate: event.startDate ?? null,
+        endDate: event.endDate ?? null,
+        timezone,
+        recurrence,
+        eventType: "default",
+        transparency: event.transparency ?? null,
+        visibility: null,
+        ownResponse: null,
+        organizer: event.organizer ? { email: event.organizer.email, name: event.organizer.name ?? null } : null,
+        participants: (event.attendees ?? []).map((one) => ({
+            email: one.email,
+            name: one.name ?? null,
+            response: one.response ?? null,
+            ...(one.optional ? { optional: true } : {}),
+        })),
+        joinUrl: joinUrlWithoutQuery(firstLink(event.location) ?? firstLink(event.description)),
+        conference: null,
+        url: event.url ?? null,
+        sequence: null,
+        // The engine keeps a series' slots as they are while its version stays the same.
+        etag: createHash("sha256").update(JSON.stringify(event)).digest("hex").slice(0, 32),
+        externalUpdatedAt: null,
+        metadata: null,
+        attachments: [],
+    };
+};
+const inWindow = (entry, window) => entry.startsAt != null &&
+    entry.startsAt < window.to &&
+    (entry.kind === "series" || Math.max(entry.endsAt ?? entry.startsAt, entry.startsAt + 1) > window.from);
+const zoneOk = (zone) => {
+    if (!zone)
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** `X-WR-TIMEZONE`: the zone a feed's floating times are written in, when it names one. */
+const feedZone = (text) => /^X-WR-TIMEZONE:(.+)$/imu.exec(text)?.[1]?.trim();
+/** A feed's events inside the window, its series with their overrides, and what it could not take. */
+export const readFeed = (text, zone, window) => {
+    const named = feedZone(text);
+    const where = zoneOk(named) ? named : zone;
+    const read = readIcs(text, where, { overrides: true });
+    let skipped = read.skipped.length;
+    const entries = [];
+    for (const event of read.events) {
+        const entry = feedEntry(event, where);
+        if (entry.kind === "series" && unexpandable(entry.recurrence) !== null) {
+            skipped++;
+            continue;
+        }
+        if (!window || inWindow(entry, window))
+            entries.push(entry);
+    }
+    const series = new Set(entries.filter((one) => one.kind === "series").map((one) => one.externalId));
+    const inFeed = new Set(read.events.map((one) => one.uid));
+    const overrides = new Map();
+    for (const override of read.overrides) {
+        if (!series.has(override.uid)) {
+            if (!inFeed.has(override.uid))
+                skipped++;
+            continue;
+        }
+        const entry = { ...feedEntry(override, where), originalStartsAt: override.recurrenceId };
+        overrides.set(override.uid, [...(overrides.get(override.uid) ?? []), entry]);
+    }
+    return {
+        entries,
+        overrides,
+        name: calendarText(read.name, { dropSecretLines: false }),
+        timezone: zoneOk(named) ? named : null,
+        events: read.events.length + read.overrides.length,
+        skipped,
+    };
+};
+const calendarOf = (feed, timezone = null) => ({
+    externalId: `${FEED_PREFIX}${feed.id}`,
+    title: feed.title,
+    timezone,
+    accessRole: "reader",
+    primary: false,
+    syncByDefault: true,
+});
+/**
+ * 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 const icsFeeds = (options) => {
+    const overridesOf = new WeakMap();
+    const stats = new Map();
+    const feedOf = async (externalId) => {
+        const feed = (await options.registry.read()).find((one) => `${FEED_PREFIX}${one.id}` === externalId);
+        if (!feed)
+            throw new CliError("configuration_error", `the address of feed ${externalId} is no longer kept on this computer`, {
+                reason: "feed.no-address",
+            });
+        return feed;
+    };
+    const read = (url, name) => fetchFeed(url, {
+        name,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.limits ? { limits: options.limits } : {}),
+    });
+    const source = {
+        provider: "ics",
+        traits: { expands: "local", cursorHoldsWindow: false, fullListOnly: true },
+        async calendars() {
+            return (await options.registry.read()).map((feed) => calendarOf(feed));
+        },
+        async changes(calendar, { window }) {
+            const feed = await feedOf(calendar.externalId);
+            const text = await read(feed.url, `feed ${calendar.id}`);
+            const found = readFeed(text, calendar.timezone ?? options.zone, window);
+            for (const entry of found.entries) {
+                const changed = found.overrides.get(entry.externalId);
+                if (changed)
+                    overridesOf.set(entry, changed);
+            }
+            stats.set(calendar.id, { calendarId: calendar.id, events: found.events, skipped: found.skipped });
+            return { entries: found.entries, removed: [], cursor: null };
+        },
+    };
+    return {
+        source,
+        expand: (series, window) => expandSeries(series, window, overridesOf.get(series) ?? []),
+        async add(url, { title } = {}) {
+            const address = feedAddress(url).href;
+            const feeds = await options.registry.read();
+            if (feeds.some((one) => sameAddress(one.url, address)))
+                throw new CliError("validation_error", "this profile follows a feed at this address already", {
+                    reason: "feed.duplicate",
+                });
+            const found = readFeed(await read(address, "the feed"), options.zone);
+            const feed = {
+                id: randomBytes(6).toString("hex"),
+                url: address,
+                title: title?.trim() || found.name || new URL(address).hostname,
+            };
+            await options.registry.write([...feeds, feed]);
+            return { calendar: calendarOf(feed, found.timezone), events: found.events };
+        },
+        async remove(externalId) {
+            const feeds = await options.registry.read();
+            await options.registry.write(feeds.filter((one) => `${FEED_PREFIX}${one.id}` !== externalId));
+        },
+        stats: () => [...stats.values()],
+    };
+};
+/**
+ * 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 const syncWithFeeds = async (source, feeds, store, options) => {
+    const budget = options.budget ?? runBudget();
+    const first = await syncCalendars(source, store, { ...options, budget });
+    if (!feeds)
+        return first;
+    const second = await syncCalendars(feeds.source, store, { ...options, budget, expand: feeds.expand });
+    if (second.calendars === 0)
+        return first;
+    const complete = first.complete && second.complete;
+    const stopped = first.stopped ?? second.stopped;
+    const hint = first.hint ?? second.hint;
+    const sum = (field) => first.progress[field] + second.progress[field];
+    return {
+        ...first,
+        calendars: first.calendars + second.calendars,
+        synced: [...first.synced, ...second.synced],
+        notSynced: [...first.notSynced, ...second.notSynced],
+        complete,
+        state: first.state === "complete" && second.state === "complete" ? "complete" : "partial",
+        ...(stopped ? { stopped } : {}),
+        progress: {
+            calendars: sum("calendars"),
+            calendarsDone: sum("calendarsDone"),
+            requests: budget.used,
+            saved: sum("saved"),
+            steps: sum("steps"),
+        },
+        ...(hint ? { hint } : {}),
+        feeds: feeds.stats(),
+    };
+};

package/dist/calendar/ics.d.ts

@@ -45,11 +45,22 @@ export interface IcsSkip {
     uid: string | null;
     reason: string;
 }
+/** One changed occurrence of a repeating event: `recurrenceId` is the slot it replaces, as `originalStartsAt`. */
+export interface IcsOverride extends IcsEvent {
+    recurrenceId: number;
+}
+export interface IcsRead {
+    events: IcsEvent[];
+    skipped: IcsSkip[];
+    /** With `overrides`: the changed occurrences, which are otherwise skipped. */
+    overrides: IcsOverride[];
+    /** The calendar's own name (`X-WR-CALNAME`), as the text has it. */
+    name: string | null;
+}
 /**
  * The VEVENTs of an iCalendar text; times with neither `Z` nor a TZID are read in `zone`. An event that cannot be
  * imported alone is in `skipped` with the reason; a text with no VCALENDAR is refused.
  */
-export declare const readIcs: (text: string, zone: string) => {
-    events: IcsEvent[];
-    skipped: IcsSkip[];
-};
+export declare const readIcs: (text: string, zone: string, options?: {
+    overrides?: boolean;
+}) => IcsRead;

package/dist/calendar/ics.js

@@ -182,12 +182,14 @@ const emailOf = (value) => {
         .toLowerCase();
     return /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(email) ? email : null;
 };
-const eventOf = (lines, zone) => {
+const slotMoment = (moment) => ("date" in moment ? Date.parse(`${moment.date}T00:00:00Z`) : moment.at);
+const eventOf = (lines, zone, overrides = false) => {
     const one = (name) => lines.find((line) => line.name === name);
     const uid = one("UID")?.value.trim();
     if (!uid)
         throw new Error("the event has no UID");
-    if (one("RECURRENCE-ID"))
+    const recurrenceLine = one("RECURRENCE-ID");
+    if (recurrenceLine && !overrides)
         throw new Error("a changed occurrence of a repeating event (RECURRENCE-ID) is not imported on its own");
     const startLine = one("DTSTART");
     if (!startLine)
@@ -264,13 +266,13 @@ const eventOf = (lines, zone) => {
     const url = one("URL")?.value.trim();
     if (url)
         event.url = url;
-    return event;
+    return recurrenceLine ? { ...event, recurrenceId: slotMoment(momentOf(recurrenceLine, zone)) } : event;
 };
 /**
  * The VEVENTs of an iCalendar text; times with neither `Z` nor a TZID are read in `zone`. An event that cannot be
  * imported alone is in `skipped` with the reason; a text with no VCALENDAR is refused.
  */
-export const readIcs = (text, zone) => {
+export const readIcs = (text, zone, options = {}) => {
     const unfolded = text.replace(/^\uFEFF/u, "").replace(/\r?\n[ \t]/gu, "");
     const lines = unfolded.split(/\r?\n/u).filter((line) => line.trim() !== "");
     if (!/^BEGIN:VCALENDAR$/iu.test(lines[0]?.trim() ?? ""))
@@ -279,6 +281,8 @@ export const readIcs = (text, zone) => {
         });
     const events = [];
     const skipped = [];
+    const overrides = [];
+    let name = null;
     let held = null;
     // Components inside a VEVENT, such as VALARM, are passed over whole.
     let inner = 0;
@@ -291,15 +295,22 @@ export const readIcs = (text, zone) => {
             held = [];
             continue;
         }
-        if (held === null)
+        if (held === null) {
+            if (line.name === "X-WR-CALNAME" && name === null)
+                name = unescapeText(line.value).trim() || null;
             continue;
+        }
         if (line.name === "BEGIN")
             inner++;
         else if (line.name === "END" && inner > 0)
             inner--;
         else if (line.name === "END" && value === "VEVENT") {
             try {
-                events.push(eventOf(held, zone));
+                const event = eventOf(held, zone, options.overrides);
+                if ("recurrenceId" in event)
+                    overrides.push(event);
+                else
+                    events.push(event);
             }
             catch (error) {
                 const uid = held.find(({ name }) => name === "UID")?.value.trim() || null;
@@ -310,5 +321,5 @@ export const readIcs = (text, zone) => {
         else if (inner === 0)
             held.push(line);
     }
-    return { events, skipped };
+    return { events, skipped, overrides, name };
 };

package/dist/calendar/index.d.ts

@@ -1,5 +1,7 @@
 export type { CalendarAccessRole, CalendarInput, EntryAttachment, EntryAttachmentInput, EntryEventType, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EntryTransparency, EntryVisibility, EventDetails, EventFilter, EventStore, LinkReview, ParticipantResponse, ReviewDecision, StoredCalendar, StoredEntry, StoredParticipant, } from "../meetings/index.js";
-export { type IcsEvent, type IcsSkip, readIcs, writeIcs } from "./ics.js";
+export { expandSeries, localMoment, unexpandable } from "./expand.js";
+export { type CalendarFeeds, FEED_LIMITS, FEED_PREFIX, type FeedLimits, type FeedRecord, type FeedRegistry, type FeedSyncStats, type FeedsSyncReport, feedAddress, fetchFeed, icsFeeds, isFeedCalendar, readFeed, syncWithFeeds, } from "./feeds.js";
+export { type IcsEvent, type IcsOverride, type IcsRead, type IcsSkip, readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export type { BusyTimes, CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, FreeBusyRequest, SearchPage, SyncWindow, } from "./source.js";
 export { type CalendarCursor, type CalendarSyncOptions, type CalendarSyncReport, type CalendarSyncResult, calendarStatus, calendarSyncWindow, type PendingRound, parseCalendarCursor, syncCalendars, } from "./sync.js";

package/dist/calendar/index.js

@@ -1,3 +1,5 @@
+export { expandSeries, localMoment, unexpandable } from "./expand.js";
+export { FEED_LIMITS, FEED_PREFIX, feedAddress, fetchFeed, icsFeeds, isFeedCalendar, readFeed, syncWithFeeds, } from "./feeds.js";
 export { readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export { calendarStatus, calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";

package/dist/calendar/server-search.js

@@ -1,4 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
+import { isFeedCalendar } from "./feeds.js";
 const iso = (at) => (at == null ? null : new Date(at).toISOString());
 /**
  * The provider's own search over the calendars the account syncs, earliest first, stored nowhere. A calendar the owner
@@ -7,7 +8,8 @@ const iso = (at) => (at == null ? null : new Date(at).toISOString());
 export const serverSearchAnswer = async (source, store, { accountId, account, query, limit }) => {
     if (!source.search)
         throw new CliError("configuration_error", "this calendar provider has no search of its own");
-    const calendars = (await store.calendars(accountId)).filter(({ synced, deletedAt }) => synced && deletedAt === null);
+    // A feed is read whole into the store, so the stored search already covers it; the provider has never seen it.
+    const calendars = (await store.calendars(accountId)).filter((calendar) => calendar.synced && calendar.deletedAt === null && !isFeedCalendar(calendar));
     if (calendars.length === 0)
         throw new CliError("validation_error", "no calendar syncs yet; run sync, or calendars sync <calendar>", {
             reason: "search.no-calendars",

package/dist/calendar/writes.js

@@ -5,6 +5,7 @@ import { guardFor } from "../sends/guard.js";
 import { guardedWrite } from "../sends/guarded.js";
 import { DEFAULT_PERMISSIONS, levelFor } from "../sends/permissions.js";
 import { newOperationId } from "../sends/send-id.js";
+import { isFeedCalendar } from "./feeds.js";
 import { readIcs } from "./ics.js";
 import { calendarIn, entryItem, eventIdOf, eventOf, plusDays } from "./reads.js";
 import { kindBoundLines, repeatRule, ruleCount, ruleEnd, ruleEndingBefore, ruleLine, splitDates } from "./recurrence.js";
@@ -184,8 +185,17 @@ const savedAfterCreate = async (context, id, save) => {
             `sync to store it — do not create it again: a create repeated with ${context.names.id} ${id} finds it`, { ...(isCliError(error) ? error.details : {}), operation_id: id, id });
     }
 };
+const READ_ONLY = new Set(["reader", "free-busy"]);
+/** A calendar the account may only read refuses here, before any question is asked or anything is journaled. */
+const writable = (calendar) => {
+    if (READ_ONLY.has(calendar.accessRole ?? ""))
+        throw new CliError("permission_error", isFeedCalendar(calendar)
+            ? `calendar ${calendar.id} is a feed, read again from its address on every sync; its events cannot be changed`
+            : `calendar ${calendar.id} is read-only for this account`, { reason: "calendar.read-only", sent: false });
+    return calendar;
+};
 export const createEvent = async (context, calendarReference, fields, options = {}) => {
-    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const calendar = writable(await calendarIn(context.store, context.accountId, calendarReference));
     const draft = draftOf(fields, context.zone, { whole: true });
     const id = idOf(context, options.id);
     const notify = notifyOf(context, options.notify, (draft.attendees?.length ?? 0) > 0);
@@ -209,7 +219,7 @@ export const createEventFromText = async (context, calendarReference, text, opti
         throw new CliError("validation_error", "the text is empty: say what, when and where");
     if (line.length > TEXT_MAX || /[\r\n]/u.test(line))
         throw new CliError("validation_error", `the text is one line of at most ${TEXT_MAX} characters`);
-    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const calendar = writable(await calendarIn(context.store, context.accountId, calendarReference));
     const notify = options.notify ?? false;
     const guard = writeGuard(context, keysFor(context, "quick-add", notify));
     const id = newEventId();
@@ -251,7 +261,7 @@ export const importEvents = async (context, calendarReference, text) => {
             : "the file holds no event (VEVENT)", { reason: "ics.no-events", skipped: skipped.map(({ uid, reason }) => ({ uid, reason })) });
     if (events.length > IMPORT_MAX)
         throw new CliError("validation_error", `the file holds ${events.length} events; one import takes at most ${IMPORT_MAX}`, { reason: "ics.too-many" });
-    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const calendar = writable(await calendarIn(context.store, context.accountId, calendarReference));
     const guard = writeGuard(context, keysFor(context, "import", false));
     const id = newEventId();
     const imported = [];
@@ -300,6 +310,7 @@ const targetOf = async (context, reference, { calendar, scope }) => {
     if (live.length > 1)
         throw new CliError("validation_error", `${reference} is on calendars ${live.map(({ calendarId }) => calendarId).join(", ")}; name one with ` +
             `${context.names.calendar}`, { param: context.names.calendar });
+    const owner = writable(calendars.find(({ id }) => id === entry.calendarId));
     let target = entry;
     if (scope !== "this") {
         const flag = scope === "series" ? context.names.series : context.names.following;
@@ -316,7 +327,7 @@ const targetOf = async (context, reference, { calendar, scope }) => {
             sent: false,
         });
     return {
-        calendar: calendars.find(({ id }) => id === entry.calendarId),
+        calendar: owner,
         entry,
         target,
         participants: details.participants.filter(({ entryId }) => entryId === entry.id),

package/dist/cli/after-dashes.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from "commander";
+declare module "@wirecat/cli-base/commands" {
+    interface CommandMeta {
+        /**
+         * Every word after `--` stays a positional, even one spelled as this command's option: the command takes free
+         * text (a message, a title, another program's arguments), where `--json` may be the text itself.
+         */
+        literal_after_dashes?: boolean;
+    }
+}
+/**
+ * `messages sync -- -100 --json` as `messages sync --json -- -100`: agents copy `-- <id> --json` from old skill
+ * text, and a negative id needs no `--` anyway. Only a word that is exactly one of the command's options moves, with
+ * the value it takes; a command marked `literal_after_dashes` keeps every word after `--` as it is.
+ */
+export declare const liftOptionsAfterDashes: (argv: readonly string[], target: (words: string[]) => Command | undefined) => string[];

package/dist/cli/after-dashes.js

@@ -0,0 +1,41 @@
+import { metaOf } from "@wirecat/cli-base/commands";
+const optionsOf = (command) => {
+    const found = new Map();
+    for (let at = command; at; at = at.parent)
+        for (const option of at.options)
+            if (option.long && !found.has(option.long))
+                found.set(option.long, option);
+    return found;
+};
+/**
+ * `messages sync -- -100 --json` as `messages sync --json -- -100`: agents copy `-- <id> --json` from old skill
+ * text, and a negative id needs no `--` anyway. Only a word that is exactly one of the command's options moves, with
+ * the value it takes; a command marked `literal_after_dashes` keeps every word after `--` as it is.
+ */
+export const liftOptionsAfterDashes = (argv, target) => {
+    const end = argv.indexOf("--");
+    if (end < 0)
+        return [...argv];
+    const command = target(argv.slice(0, end));
+    if (!command || metaOf(command).literal_after_dashes)
+        return [...argv];
+    const options = optionsOf(command);
+    const moved = [];
+    const kept = [];
+    for (let index = end + 1; index < argv.length; index++) {
+        const word = argv[index];
+        const equals = word.indexOf("=");
+        const option = word.startsWith("--") ? options.get(equals < 0 ? word : word.slice(0, equals)) : undefined;
+        if (!option) {
+            kept.push(word);
+            continue;
+        }
+        moved.push(word);
+        // An optional value is left alone: after `--` the next word is as likely the positional as the value.
+        if (option.required && equals < 0 && index + 1 < argv.length)
+            moved.push(argv[++index]);
+    }
+    if (moved.length === 0)
+        return [...argv];
+    return [...argv.slice(0, end), ...moved, "--", ...kept];
+};

package/dist/cli/bot/context.d.ts

@@ -44,7 +44,7 @@ export declare const botContext: (command: Command, bot: BotMessenger) => {
      * its section sets one.
      */
     guard: (permissionDefaults?: Readonly<Record<PermissionKey, Level>>) => import("../../sends/guard.js").SendGuard;
-    /** A chat id, `user:<id>`, or the title of a chat this bot has seen — never a guess. */
+    /** A chat id, `user:<id>`, a `chat:` or `msg:` reference, or the title of a chat this bot has seen — never a guess. */
     chatRef: (typed: string) => BotChatRef;
     readSecret: (prompt: string) => Promise<string>;
     /** A client for this token, closed when the command ends. */

package/dist/cli/bot/context.js

@@ -1,4 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
+import { chatReferenceOf, wrongAccount } from "../../domain/ref-arguments.js";
 import { pickChat } from "../../resolve.js";
 import { sendGuard } from "../../sends/guard.js";
 import { SendJournal } from "../../sends/journal.js";
@@ -75,9 +76,16 @@ export const botContext = (command, bot) => {
             recipients: recipients(),
             warn: base.renderer.warn,
         }),
-        /** A chat id, `user:<id>`, or the title of a chat this bot has seen — never a guess. */
+        /** A chat id, `user:<id>`, a `chat:` or `msg:` reference, or the title of a chat this bot has seen — never a guess. */
         chatRef: (typed) => {
             const trimmed = typed.trim();
+            const named = chatReferenceOf(trimmed, bot.provider);
+            if (named) {
+                const own = registry.botId();
+                if (own === undefined || own !== named.account)
+                    throw wrongAccount(named, { account: own, profile });
+                return named.chat;
+            }
             if (/^-?\d+$/.test(trimmed) || /^user:\d+$/.test(trimmed))
                 return trimmed;
             const known = registry.list();

package/dist/cli/bot/messages.js

@@ -63,6 +63,7 @@ const seen = (context, message) => {
         context.registry.observe([{ id: message.chatId }]);
 };
 const sendCommand = (bot) => annotate(new Command("send"), {
+    literal_after_dashes: true,
     effects: REMOTE_WRITE,
     examples: botExamples(bot, 'messages send Team "Doors open at 9"', 'messages send Team "Here it is" --file report.pdf'),
 })
@@ -199,6 +200,7 @@ const showCommand = (bot) => annotate(new Command("show"), { effects: REMOTE_REA
     });
 });
 const editCommand = (bot) => annotate(new Command("edit"), {
+    literal_after_dashes: true,
     effects: REMOTE_WRITE,
     examples: botExamples(bot, 'messages edit Team 101 "Doors open at 10"'),
 })

package/dist/cli/bot/setup.js

@@ -53,6 +53,7 @@ export const botMenuCommand = (bot) => {
         });
     };
     annotate(command.command("set"), {
+        literal_after_dashes: true,
         effects: REMOTE_WRITE,
         examples: botExamples(bot, 'commands set "start=Begin here" "help=What I can do"'),
     })

package/dist/cli/contract-templates.js

@@ -65,11 +65,11 @@ export const sharedCommandTemplate = (app, name) => {
         annotate(notes.command("show"), { effects: LOCAL_READ, output: { entity: "note" } })
             .description("show one note")
             .argument("<note>", "stored note reference");
-        annotate(notes.command("add"), { effects: LOCAL_WRITE, output: { entity: "note" } })
+        annotate(notes.command("add"), { effects: LOCAL_WRITE, output: { entity: "note" }, literal_after_dashes: true })
             .description("write a note")
             .argument("<text>", "note text")
             .option("--subject <ref>", "stored resource the note describes");
-        annotate(notes.command("edit"), { effects: LOCAL_WRITE, output: { entity: "note" } })
+        annotate(notes.command("edit"), { effects: LOCAL_WRITE, output: { entity: "note" }, literal_after_dashes: true })
             .description("change a note")
             .argument("<note>", "stored note reference")
             .argument("<text>", "replacement text");