@wirecat/cli-core 0.538.0 → 0.540.0

package/dist/calendar/testing/writer.js

@@ -73,6 +73,46 @@ export const fakeCalendarWriter = (options = {}) => {
             of(calendar.externalId).set(id, entry);
             return answer(entry);
         },
+        /** Reads no date: the event is the whole line as its title, an hour from noon UTC of 2 November 2026. */
+        async quickAdd(calendar, text, { notify }) {
+            const id = `quick${++version}`;
+            calls.push({ write: "quick-add", calendar: calendar.externalId, externalId: id, notify });
+            const noon = Date.UTC(2026, 10, 2, 12);
+            const entry = stamp({
+                externalId: id,
+                icalUid: `${id}@example.com`,
+                kind: "single",
+                status: "confirmed",
+                title: text,
+                startsAt: noon,
+                endsAt: noon + 3_600_000,
+                participants: [],
+            });
+            of(calendar.externalId).set(id, entry);
+            return answer(entry);
+        },
+        /** Keeps one event per UID on a calendar: a UID sent again replaces the event under the same id. */
+        async importEvent(calendar, event) {
+            const held = [...of(calendar.externalId).values()].find((one) => one.icalUid === event.uid);
+            const id = held?.externalId ?? `imported${++version}`;
+            calls.push({ write: "import", calendar: calendar.externalId, externalId: id, notify: false });
+            const entry = stamp({
+                externalId: id,
+                icalUid: event.uid,
+                kind: event.recurrence ? "series" : "single",
+                status: event.status ?? "confirmed",
+                title: event.title,
+                description: event.description ?? null,
+                location: event.location ?? null,
+                ...(event.startDate === undefined
+                    ? { startsAt: event.startsAt ?? null, endsAt: event.endsAt ?? null, timezone: event.timezone ?? null }
+                    : { allDay: true, startDate: event.startDate, endDate: event.endDate ?? null }),
+                ...(event.recurrence ? { recurrence: event.recurrence } : {}),
+                participants: (event.attendees ?? []).map(({ email, name }) => ({ email, name: name ?? null })),
+            });
+            of(calendar.externalId).set(id, entry);
+            return answer(entry);
+        },
         async update(calendar, externalId, patch, { scope, etag, notify }) {
             calls.push({ write: "update", calendar: calendar.externalId, externalId, notify, scope });
             const entry = stamp({ ...current(calendar, externalId, etag), ...fields(patch) });

package/dist/calendar/writer.d.ts

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import type { EntryInput, ParticipantResponse, StoredCalendar } from "../meetings/index.js";
 import type { Level, PermissionKey } from "../sends/permissions.js";
+import type { IcsEvent } from "./ics.js";
 /**
  * A new event in neutral words: a timed one has `startsAt` and `endsAt` (epoch ms, end exclusive) in `timezone`; an
  * all-day one has `startDate` and `endDate` (`YYYY-MM-DD`, end exclusive). A repeating one has `recurrence`, RFC 5545
@@ -64,6 +65,19 @@ export interface CalendarWriter {
         etag: string;
         notify: boolean;
     }): Promise<EntryInput>;
+    /**
+     * Optional: the provider makes an event from one line of text, reading its date, time and place its own way. The
+     * provider picks the id, so a retry after `outcome_unknown` may make a second event.
+     */
+    quickAdd?(calendar: StoredCalendar, text: string, options: {
+        notify: boolean;
+    }): Promise<EntryInput>;
+    /**
+     * Optional: adds a private copy of an event read from an iCalendar file, under its own UID, as Google's
+     * `events.import`. The provider mails nobody. Sending the same UID again goes to the provider again; what it does
+     * with an event it holds already is its own.
+     */
+    importEvent?(calendar: StoredCalendar, event: IcsEvent): Promise<EntryInput>;
     /**
      * Optional: moves the event, keeping its id, to `target`, another calendar of the same account. `etag` is checked
      * before the move; a provider whose move takes no precondition reads the event first. A retry after
@@ -75,7 +89,7 @@ export interface CalendarWriter {
     }): Promise<EntryInput>;
 }
 /** Which write a command makes, for `CalendarWrites.extraKeys`. */
-export type CalendarWrite = "create" | "update" | "delete" | "respond" | "move";
+export type CalendarWrite = "create" | "quick-add" | "import" | "update" | "delete" | "respond" | "move";
 /** Mailing the other attendees: an agent may write to the calendar and still not to people (WC-PERM-14's spirit). */
 export declare const EVENTS_NOTIFY_KEY: PermissionKey;
 export declare const EVENTS_DELETE_SERIES_KEY: PermissionKey;

package/dist/calendar/writer.js

@@ -10,6 +10,8 @@ export const CALENDAR_WRITE_KEYS = [EVENTS_NOTIFY_KEY, EVENTS_DELETE_SERIES_KEY]
  */
 export const CALENDAR_WRITE_DEFAULTS = {
     "events.create": "allow",
+    // One import writes a whole file of events, and may change events the calendar already holds under their UIDs.
+    "events.import": "ask",
     "events.update": "allow",
     "events.respond": "allow",
     "events.move": "allow",

package/dist/calendar/writes.d.ts

@@ -3,6 +3,7 @@ import type { AppIdentity } from "../ports/app.js";
 import type { Warn } from "../runs/events.js";
 import { type Asker, type GuardSettings } from "../sends/guard.js";
 import { type PermissionKey } from "../sends/permissions.js";
+import { entryItem } from "./reads.js";
 import { type CalendarWrite, type CalendarWriter, type EventPatch, type EventResponse } from "./writer.js";
 /** What a CLI or an MCP host hands the calendar writes for one profile. */
 export interface CalendarWrites {
@@ -83,6 +84,51 @@ export declare const createEvent: (context: WriteContext, calendarReference: str
     } | null;
     hint?: string | undefined;
 }>;
+/**
+ * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
+ * the attendees are known only once the provider has read the text.
+ */
+export declare const createEventFromText: (context: WriteContext, calendarReference: string, text: string, options?: {
+    notify?: boolean;
+}) => Promise<{
+    operation_id: string;
+    event: string | null;
+    entry: {
+        id: string;
+        calendar_id: string;
+        external_id: string;
+        kind: import("../meetings/event-store.js").EntryKind;
+        title: string | null;
+        status: import("../meetings/event-store.js").EntryStatus;
+        event_type: import("../meetings/event-store.js").EntryEventType | null;
+        own_response: import("../meetings/event-store.js").ParticipantResponse | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        join_url: string | null;
+        url: string | null;
+        deleted_at: string | null;
+    } | null;
+    hint?: string | undefined;
+}>;
+/** The most events one import sends: a file of more is refused before anything goes. */
+export declare const IMPORT_MAX = 500;
+/**
+ * The events of an iCalendar text into a calendar, one provider call each, in the file's order. The whole import is
+ * one write for the guard: one question, one journal line. A failure part way names the UIDs already imported.
+ */
+export declare const importEvents: (context: WriteContext, calendarReference: string, text: string) => Promise<{
+    operation_id: string;
+    calendar: string;
+    imported: {
+        uid: string;
+        event: string | null;
+        entry: ReturnType<typeof entryItem> | null;
+    }[];
+    skipped: {
+        uid: string | null;
+        reason: string;
+    }[];
+}>;
 interface ScopeChoice {
     calendar?: string;
     series?: boolean;

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 { readIcs } from "./ics.js";
 import { calendarIn, entryItem, eventIdOf, eventOf, plusDays } from "./reads.js";
 import { kindBoundLines, repeatRule, ruleCount, ruleEnd, ruleEndingBefore, ruleLine, splitDates } from "./recurrence.js";
 import { CALENDAR_WRITE_DEFAULTS, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, } from "./writer.js";
@@ -12,6 +13,8 @@ export const EVENT_RESPONSES = ["accepted", "tentative", "declined"];
 /** Each write is checked by its command's path, the key a declared CLI's `commandPermissions` already knows. */
 const COMMAND_KEY = {
     create: "events.create",
+    "quick-add": "events.create",
+    import: "events.import",
     update: "events.update",
     delete: "events.delete",
     respond: "events.respond",
@@ -191,6 +194,101 @@ export const createEvent = async (context, calendarReference, fields, options =
     const [saved] = await savedAfterCreate(context, id, () => context.store.saveEntries(calendar.id, [entry], context.now));
     return answerOf(id, saved, draft.recurrence !== undefined);
 };
+/** The longest line `createEventFromText` sends; a quick add is one sentence, not a description. */
+const TEXT_MAX = 1000;
+/**
+ * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
+ * the attendees are known only once the provider has read the text.
+ */
+export const createEventFromText = async (context, calendarReference, text, options = {}) => {
+    const quickAdd = context.writes.writer.quickAdd;
+    if (!quickAdd)
+        throw new CliError("configuration_error", "this provider cannot make an event from text");
+    const line = text.trim();
+    if (!line)
+        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 notify = options.notify ?? false;
+    const guard = writeGuard(context, keysFor(context, "quick-add", notify));
+    const id = newEventId();
+    let entry;
+    try {
+        entry = await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY["quick-add"], operationId: id, sendId: id, notify }, () => quickAdd.call(context.writes.writer, calendar, line, { notify }));
+    }
+    catch (error) {
+        if (isCliError(error) && error.code === "outcome_unknown")
+            throw new CliError("outcome_unknown", `${error.message} — the provider may have made the event, and a create from text cannot be retried safely: ` +
+                "sync, then look with events list changed_at>=today before adding it again", { ...error.details, operation_id: id, retryable: false });
+        throw error;
+    }
+    let saved;
+    try {
+        ;
+        [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
+    }
+    catch (error) {
+        throw new CliError(isCliError(error) ? error.code : "invalid_response", `the provider made event ${entry.externalId}, but the local store did not save it ` +
+            `(${error instanceof Error ? error.message : String(error)}); sync to store it — do not create it again`, { ...(isCliError(error) ? error.details : {}), operation_id: id, id: entry.externalId, retryable: false });
+    }
+    return answerOf(id, saved, (entry.recurrence?.length ?? 0) > 0);
+};
+/** The most events one import sends: a file of more is refused before anything goes. */
+export const IMPORT_MAX = 500;
+/**
+ * The events of an iCalendar text into a calendar, one provider call each, in the file's order. The whole import is
+ * one write for the guard: one question, one journal line. A failure part way names the UIDs already imported.
+ */
+export const importEvents = async (context, calendarReference, text) => {
+    const writer = context.writes.writer;
+    if (!writer.importEvent)
+        throw new CliError("configuration_error", "this provider cannot import events");
+    const { events, skipped } = readIcs(text, context.zone);
+    if (events.length === 0)
+        throw new CliError("validation_error", skipped.length
+            ? `no event in the file can be imported: ${skipped.map(({ reason }) => reason).join("; ")}`
+            : "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 guard = writeGuard(context, keysFor(context, "import", false));
+    const id = newEventId();
+    const imported = [];
+    await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.import, operationId: id, sendId: id, notify: false }, async () => {
+        for (const event of events) {
+            try {
+                const entry = await writer.importEvent?.call(writer, calendar, event);
+                if (!entry)
+                    throw new CliError("invalid_response", "the provider returned no event");
+                const [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
+                imported.push({
+                    uid: event.uid,
+                    event: saved?.eventId == null ? null : `event:${saved.eventId}`,
+                    entry: saved ? entryItem(saved) : null,
+                });
+            }
+            catch (error) {
+                const done = imported.map(({ uid }) => uid);
+                throw new CliError(isCliError(error) ? error.code : "provider_error", `${error instanceof Error ? error.message : String(error)} — at the event with UID ${event.uid}; ` +
+                    `${done.length} of ${events.length} were imported before it (details.imported). Running the import ` +
+                    "again sends every event again under its UID", {
+                    ...(isCliError(error) ? error.details : {}),
+                    operation_id: id,
+                    imported: done,
+                    failed: event.uid,
+                    retryable: false,
+                });
+            }
+        }
+    });
+    return {
+        operation_id: id,
+        calendar: String(calendar.id),
+        imported,
+        skipped: skipped.map(({ uid, reason }) => ({ uid, reason })),
+    };
+};
 const targetOf = async (context, reference, { calendar, scope }) => {
     const details = await eventOf(context.store, context.accountId, eventIdOf(reference));
     const calendars = await context.store.calendars(context.accountId);

package/dist/cli/bot/mcp.js

@@ -3,7 +3,7 @@ import { CliError } from "@wirecat/cli-base";
 import { annotate, describeProgram } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { environmentOf } from "../context.js";
-import { changesAuthorityAt, fetchesOnlyAt, LOCAL_READ, REMOTE_WRITE } from "../effects.js";
+import { changesAuthorityAt, LOCAL_READ, REMOTE_WRITE, readsOverMcpAt } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
 import { serverEntry } from "../messenger/mcp-command.js";
 import { nextStep, rootOf } from "../steps.js";
@@ -37,7 +37,7 @@ export const botMcpCommand = (bot) => {
             bot,
             program: { run, commands: describeProgram(rootOf(this)) },
             authority: changesAuthorityAt(rootOf(this)),
-            fetchOnly: fetchesOnlyAt(rootOf(this)),
+            fetchOnly: readsOverMcpAt(rootOf(this)),
             settings: context.settings,
             levels: () => bot.resolveSettings(this.optsWithGlobals(), { env: context.env, kind: "bot" }).permissions,
             env: context.env,

package/dist/cli/effects.d.ts

@@ -50,6 +50,20 @@ export declare const changesStore: <T extends Command>(command: T) => T;
 export declare const fetchesOnly: (command: Command) => boolean;
 /** `fetchesOnly` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
 export declare const fetchesOnlyAt: (root: Command) => (path: readonly string[]) => boolean;
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export declare const writesFileOnlyWith: <T extends Command>(command: T, option: string) => T;
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export declare const readsOverMcp: (command: Command) => boolean;
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export declare const readsOverMcpAt: (root: Command) => (path: readonly string[]) => boolean;
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)

package/dist/cli/effects.js

@@ -1,4 +1,4 @@
-import { annotate, annotateOption, metaOf, stepTargets } from "@wirecat/cli-base/commands";
+import { annotate, annotateOption, metaOf, optionMetaOf, stepTargets, } from "@wirecat/cli-base/commands";
 import { Option } from "commander";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { keyForCommand } from "../sends/permissions.js";
@@ -93,6 +93,36 @@ export const fetchesOnlyAt = (root) => (path) => {
         at = at?.commands.find((one) => one.name() === word);
     return at !== undefined && fetchesOnly(at);
 };
+const FILE_OPTION = new WeakMap();
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export const writesFileOnlyWith = (command, option) => {
+    const flag = command.options.find((one) => one.attributeName() === option);
+    if (!flag || optionMetaOf(flag).mcp !== false)
+        throw new Error(`${command.name()}: writesFileOnlyWith needs --${option} added first, as an owner-only option`);
+    FILE_OPTION.set(command, option);
+    return command;
+};
+const writesFileNow = (command) => {
+    const option = FILE_OPTION.get(command);
+    return option === undefined || command.opts()[option] !== undefined;
+};
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export const readsOverMcp = (command) => fetchesOnly(command) || FILE_OPTION.has(command);
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export const readsOverMcpAt = (root) => (path) => {
+    let at = root;
+    for (const word of path)
+        at = at?.commands.find((one) => one.name() === word);
+    return at !== undefined && readsOverMcp(at);
+};
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)
@@ -103,7 +133,8 @@ export const isStoreChange = (command) => {
     return ((effects?.remote === "none" || STORE_WRITES.has(command)) &&
         effects?.local === "write" &&
         !KEPT_UNDER_LOCK.has(command) &&
-        !changesAuthority(command));
+        !changesAuthority(command) &&
+        writesFileNow(command));
 };
 export const STORE_CHANGE_REFUSAL = "change the message store";
 /** ` --dry-run` where the program has it, so an example of a command that calls a provider calls nothing. */

package/dist/cli/envelope.d.ts

@@ -95,6 +95,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
@@ -148,6 +150,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;

package/dist/cli/index.d.ts

@@ -66,7 +66,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { type CliEntry, type EntryContext, type EntryIo, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
@@ -78,7 +78,7 @@ export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIREC
 export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, type McpServerOptions, type McpServerTarget, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";

package/dist/cli/index.js

@@ -58,7 +58,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
@@ -70,7 +70,7 @@ export { firstScreen, installHelp, WIRECAT_TOOLS } from "./help/first-screen.js"
 export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";

package/dist/cli/list-query.d.ts

@@ -4,6 +4,8 @@ import * as v from "valibot";
 import { type ListBody, type ListInput } from "./envelope.js";
 import type { Settings } from "./settings.js";
 export declare const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export declare const QUERY_ARGUMENT = "field:value terms that narrow the list \u2014 the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -31,7 +33,9 @@ export declare const pageOf: ({ limit, page, all }: Pick<Settings, "limit" | "pa
 /** A page-numbered list's answer; under `--all` its limit is what it holds. */
 export declare const pagedList: <T>(command: string, { limit, page, all }: Pick<Settings, "limit" | "page" | "all">, { items, has_more, ...rest }: Omit<ListInput<T>, "limit" | "page" | "cursor">) => ListBody<T>;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, "field:value terms; this list filters by none yet, so any term is refused" | `field:value terms joined by AND that narrow the list; fields: ${string}; e.g. ${string}` | `field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <); fields: ${string}; e.g. ${string}`>]>, undefined>;
+export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, string>]>, undefined>;
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export declare const negatableOf: (registry: QueryRegistry) => string[];
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.
@@ -39,9 +43,10 @@ export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchem
 export declare const nativeTerms: (ast: QueryAst | undefined, command: string) => Map<string, Predicate>;
 /**
  * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
- * asks for both, as AND reads.
+ * asks for both, as AND reads. A `negatable` field may also be excluded, `-field:value` or `NOT field:value`, as
+ * often as wanted; those terms are kept under `-field`.
  */
-export declare const nativeTermLists: (ast: QueryAst | undefined, command: string, repeatable?: readonly string[]) => Map<string, Predicate[]>;
+export declare const nativeTermLists: (ast: QueryAst | undefined, command: string, repeatable?: readonly string[], negatable?: readonly string[]) => Map<string, Predicate[]>;
 /**
  * A store that compares whole values: each field's `field:value` or `field:"two words"`, enum values lowercased
  * as validation already accepts them. A range or wildcard is refused rather than read as a value.

package/dist/cli/list-query.js

@@ -1,9 +1,11 @@
 import { annotate } from "@wirecat/cli-base/commands";
-import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
+import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryDescription, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
 import * as v from "valibot";
 import { queryWordsAfterOptions } from "../meetings/cli/index.js";
 import { listOf } from "./envelope.js";
 export const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export const QUERY_ARGUMENT = "field:value terms that narrow the list — the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -12,9 +14,7 @@ export const withQuery = (command, registry) => {
     const query = defineQuery(registry);
     annotate(command, { query, output: { entity: registry.entity } });
     const shown = askable(query);
-    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0
-        ? "field:value terms that narrow the list — the fields are below"
-        : "field:value terms; this list filters by none yet");
+    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0 ? QUERY_ARGUMENT : "field:value terms; this list filters by none yet");
     if (shown.length > 0)
         command.addHelpText("after", `\n${fieldsHelp({ ...query, fields: shown }, LIST_QUERY_GUIDE)}`);
     return command;
@@ -97,14 +97,11 @@ export const pagedList = (command, { limit, page, all }, { items, has_more, ...r
 /** The fields a list can be narrowed by: a provider list only those its source answers. */
 const askable = (registry) => registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export const queryArgument = (registry) => {
-    const fields = askable(registry);
-    return v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(fields.length === 0
-        ? "field:value terms; this list filters by none yet, so any term is refused"
-        : `${registry.backend === "native"
-            ? "field:value terms joined by AND that narrow the list"
-            : "field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <)"}; fields: ${fields.map((field) => field.name).join(", ")}; e.g. ${fields[0]?.example ?? ""}`)));
-};
+export const queryArgument = (registry) => v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(queryDescription(registry))));
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export const negatableOf = (registry) => askable(registry)
+    .filter((field) => field.negatable)
+    .map((field) => field.name);
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.
@@ -112,9 +109,10 @@ export const queryArgument = (registry) => {
 export const nativeTerms = (ast, command) => new Map([...nativeTermLists(ast, command)].map(([field, [node]]) => [field, node]));
 /**
  * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
- * asks for both, as AND reads.
+ * asks for both, as AND reads. A `negatable` field may also be excluded, `-field:value` or `NOT field:value`, as
+ * often as wanted; those terms are kept under `-field`.
  */
-export const nativeTermLists = (ast, command, repeatable = []) => {
+export const nativeTermLists = (ast, command, repeatable = [], negatable = []) => {
     const terms = new Map();
     if (!ast)
         return terms;
@@ -123,8 +121,16 @@ export const nativeTermLists = (ast, command, repeatable = []) => {
     const add = (node) => {
         if (node.kind === "boolean") {
             for (const clause of node.clauses) {
+                const excluded = clause.occur === "must_not" && clause.node.kind === "predicate" && negatable.includes(clause.node.field);
+                if (excluded && clause.node.kind === "predicate") {
+                    const key = `-${clause.node.field}`;
+                    terms.set(key, [...(terms.get(key) ?? []), clause.node]);
+                    continue;
+                }
                 if (clause.occur !== "must")
-                    queryError("query.unsupported-placement", clause.node.span, "this list takes only field:value terms joined by AND", context);
+                    queryError("query.unsupported-placement", clause.node.span, negatable.length
+                        ? `this list takes only field:value terms joined by AND, and -field:value for ${negatable.join(", ")}`
+                        : "this list takes only field:value terms joined by AND", context);
                 add(clause.node);
             }
             return;

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
+    error?: undefined;
     path: string;
     exists: boolean;
-    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/errors/reasons.js

@@ -62,6 +62,13 @@ const OTHERS = [
     validation("event.repeat-split", "the series cannot be split at this occurrence, or was split there already"),
     validation("event.repeat-count", "a COUNT series is split only with a rule for its new part"),
     validation("event.unmovable", "the provider keeps this kind of event on its calendar"),
+    validation("event.text-with-fields", "--text takes the whole event from its line, so no field option goes with it"),
+    validation("calendar.ambiguous", "two or more calendars have this name; name one by its id"),
+    validation("export.too-many", "the query finds more events than one export writes"),
+    validation("ics.not-icalendar", "the file is not iCalendar"),
+    validation("ics.no-events", "the file holds no event that can be imported"),
+    validation("ics.too-many", "the file holds more events than one import sends"),
+    validation("ics.too-large", "the file is larger than one import reads"),
     ["calendar.read-only", "permission_error", "the calendar takes no new events from this account"],
     ["calendar.unsynced", "not_found", "the calendar account has no synced calendar in the store"],
     ["calendar.sync-incomplete", "not_found", "a synced calendar's sync never finished or is mid-round"],

package/dist/mcp/agent.js

@@ -1,11 +1,13 @@
 import { Readable } from "node:stream";
 import { CliError, captureStreams, errorObjectOf } from "@wirecat/cli-base";
 import { flatten, } from "@wirecat/cli-base/commands";
+import { queryDescription } from "@wirecat/cli-base/query";
 import { writes } from "@wirecat/cli-base/standards";
 import { VOCABULARY } from "@wirecat/cli-base/standards/tables";
 import * as v from "valibot";
 import { commandAvailability } from "../cli/command-availability.js";
 import { changesMessenger } from "../cli/effects.js";
+import { QUERY_ARGUMENT } from "../cli/list-query.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
 import { newRunId } from "../runs/run.js";
 import { enclosingTraceId, inRun, traceOf } from "../runs/scope.js";
@@ -78,10 +80,17 @@ const optionField = (option, long, negated) => {
         },
     };
 };
-const argumentField = (argument) => {
+/** A list's query names its fields here: the help's Fields section, which its description points to, is not sent. */
+const argumentField = (argument, query) => {
+    const own = argument.description || argument.name;
+    const about = query && argument.name === "query"
+        ? own === QUERY_ARGUMENT
+            ? queryDescription(query)
+            : `${own}; ${queryDescription(query)}`
+        : own;
     const one = argument.choices
         ? v.pipe(v.picklist(argument.choices), v.description(argument.description))
-        : text(argument.description || argument.name);
+        : text(about);
     return {
         name: snake(argument.name),
         required: argument.required,
@@ -109,7 +118,7 @@ const stdinField = ({ name, description, json }) => ({
     argv: () => [],
 });
 const fieldsOf = (info, { omit = [], offline = false, stdin }) => {
-    const fields = info.arguments.map(argumentField);
+    const fields = info.arguments.map((argument) => argumentField(argument, info.query));
     const read = stdin?.(info.path);
     if (read)
         fields.push(stdinField(read));

package/dist/mcp/app-server.js

@@ -4,7 +4,7 @@ import { CliError, mcpErrorResult } from "@wirecat/cli-base";
 import { describeProgram } from "@wirecat/cli-base/commands";
 import { skillResource } from "@wirecat/cli-base/skill";
 import { environmentOf } from "../cli/context.js";
-import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, judgedTargets, readsOverMcpAt } from "../cli/effects.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { rootOf } from "../cli/steps.js";
 import { mcpUrlOf } from "../http/public-url.js";
@@ -46,7 +46,7 @@ export const createAppServer = (command, context, options) => {
         currentLevels: levels,
         readOnly: readOnly(),
         authority,
-        fetchOnly: fetchesOnlyAt(root),
+        fetchOnly: readsOverMcpAt(root),
         permissions: options.permissions,
     });
     const availability = (one) => () => {