@wirecat/cli-core 0.564.0 → 0.566.0

package/dist/calendar/cli/index.js

@@ -1,17 +1,19 @@
 import { CliError } from "@wirecat/cli-base";
-import { annotate, sharedCommand } from "@wirecat/cli-base/commands";
+import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
 import { timezoneOf } from "@wirecat/cli-base/query";
 import { clockMeta } from "@wirecat/cli-base/standards";
 import { Argument, InvalidArgumentError, Option } from "commander";
 import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { changesStore, ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
+import { renderAnswer } from "../../cli/envelope.js";
 import { queryTerms, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { secretInput } from "../../runs/run-context.js";
 import { searchEvents } from "../../services/events-search.js";
 import { dateWindow } from "../../services/moment.js";
+import { embedEvents } from "../../services/notes-search.js";
 import { linkPeople } from "../../services/people.js";
 import { BUSY_QUERY, BUSY_QUERY_NOTE, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
 import { isFeedCalendar, isPlainHttp, syncWithFeeds } from "../feeds.js";
@@ -22,6 +24,8 @@ import { bothSearchAnswer, serverSearchAnswer } from "../server-search.js";
 import { calendarStatus } from "../sync.js";
 import { createEvent, createEventFromText, deleteEvent, EVENT_RESPONSES, IMPORT_MAX, importEvents, moveEvent, respondToEvent, updateEvent, } from "../writes.js";
 import { CALENDARS_QUERY, declareCalendarAnswers, PEOPLE_QUERY } from "./answers.js";
+import { hitsBody, itemBody, listBody, messagesOf, pathOf } from "./bodies.js";
+import { ICS_MAX_BYTES, readIcsFile, writeIcsFile } from "./files.js";
 import { localTimesView } from "./local-times.js";
 import { addRemind } from "./remind.js";
 import { addSearchAll } from "./search-all.js";
@@ -41,8 +45,6 @@ const REVIEW_UNTRUSTED = ["candidates.title"];
 const SEARCH_UNTRUSTED = ["hits.title", "hits.location", "hits.excerpt"];
 const SERVER_SEARCH_UNTRUSTED = ["hits.title", "hits.location"];
 const IMPORT_UNTRUSTED = ["imported.uid", "imported.entry.title", "skipped.uid", "skipped.reason"];
-/** The largest .ics file `events import` reads. */
-const ICS_MAX_BYTES = 10 * 1024 * 1024;
 const eachMarked = (answer, untrusted) => ({
     ...answer,
     items: answer.items.map((item) => ({ ...item, untrusted })),
@@ -64,47 +66,42 @@ const minutes = (text) => {
         throw new InvalidArgumentError("expected 5 to 1440 minutes");
     return value;
 };
-const addCalendarCommandsDefinition = (program, deps) => {
+/** A search tops up its pending word index before it answers, which is a write; every other read only reads. */
+const readsOnly = (command) => metaOf(command).effects?.local !== "write" && pathOf(command)[0] !== "search";
+const addCalendarCommandsDefinition = (program, options) => {
     const mounted = new Set(program.commands);
-    const now = () => deps.now?.() ?? Date.now();
-    const zone = () => timezoneOf(deps.timezone);
-    const print = (value, command) => {
-        const opts = command.optsWithGlobals();
-        deps.write(value, opts.json ? "json" : opts.jsonl ? "jsonl" : "text", (body) => localTimesView(body ?? value, zone(), outputFor(command).color));
+    const now = () => options.now?.() ?? Date.now();
+    const zone = () => timezoneOf(options.timezone);
+    const answer = (command, body, view) => {
+        const output = outputFor(command);
+        renderAnswer(command, output, body, view ?? ((shown) => localTimesView(shown, zone(), output.color)));
     };
-    const messages = (what) => {
-        if (!deps.messages)
-            throw new CliError("configuration_error", `${what} needs the shared store`);
-        return deps.messages;
-    };
-    const personOfEmail = deps.messages
-        ? async (email) => {
-            const person = await messages("a person").people.personOf({ provider: "email", id: email });
-            return person ? `person:${person.uid}` : null;
+    /** Opens the profile for `work` and closes it before the answer prints, also when `work` fails. */
+    const within = async (command, work, view) => {
+        const run = await options.open(command, { readOnly: readsOnly(command) });
+        let body;
+        try {
+            body = await work(run);
         }
-        : undefined;
-    const personId = async (reference) => {
-        const text = reference.replace(/^person:/u, "");
-        if (/^[1-9]\d*$/u.test(text))
-            return Number(text);
-        const person = await messages("person:").people.personOf({ provider: "email", id: text.trim().toLowerCase() });
-        return person ? Number(person.uid) : null;
-    };
-    const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${program.name()} personal ${line}`) });
-    const source = () => {
-        if (!deps.source)
-            throw new CliError("configuration_error", "the calendar provider is unavailable");
-        return deps.source;
+        finally {
+            await run.close?.();
+        }
+        answer(command, body, view);
     };
+    const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} personal ${line}`) });
     const calendars = annotate(program.command("calendars").description("the account's calendars"), { effects: GROUP });
     withQuery(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json", "calendars list synced:true"), CALENDARS_QUERY).action(async (words, _opts, command) => {
         const terms = [...queryTerms(words, CALENDARS_QUERY, "calendars list")];
-        const found = [...(await source().calendars()), ...((await deps.feeds?.source.calendars()) ?? [])];
-        const listed = await deps.store.saveCalendars(deps.accountId, found, now());
-        const items = listed
-            .map(calendarItem)
-            .filter((item) => terms.every(([field, value]) => String(item[field]) === value));
-        print({ items, page: 1, limit: items.length, hasMore: false }, command);
+        await within(command, async (run) => {
+            // WC-CMD-20: the provider's list has no filter for these terms (Google's calendarList.list takes only a minimum
+            // access role, and synced is this store's own), and every calendar it answers is saved, so they narrow here.
+            const found = [...(await run.source().calendars()), ...((await run.feeds?.().source.calendars()) ?? [])];
+            const listed = await run.store.saveCalendars(run.accountId, found, now());
+            const items = listed
+                .map(calendarItem)
+                .filter((item) => terms.every(([field, value]) => String(item[field]) === value));
+            return listBody(command, { items, page: 1 });
+        });
     });
     for (const [name, synced] of [
         ["sync", true],
@@ -113,50 +110,58 @@ const addCalendarCommandsDefinition = (program, deps) => {
         example(annotate(calendars.command(name), { effects: LOCAL_WRITE })
             .description(synced ? "sync this calendar from now on" : "stop syncing this calendar; what is stored stays")
             .argument("<calendar>", "the calendar's id, the provider's id, or its title"), `calendars ${name} 3`).action(async (reference, _opts, command) => {
-            const calendar = await calendarIn(deps.store, deps.accountId, reference);
-            await deps.store.setCalendarSynced(calendar.id, synced, now());
-            print(calendarItem({ ...calendar, synced }), command);
+            await within(command, async (run) => {
+                const calendar = await calendarIn(run.store, run.accountId, reference);
+                await run.store.setCalendarSynced(calendar.id, synced, now());
+                return itemBody(calendarItem({ ...calendar, synced }));
+            });
         });
-    if (deps.feeds) {
-        const feeds = () => deps.feeds;
+    if (options.feeds) {
+        const feedsOf = (run) => {
+            if (!run.feeds)
+                throw new CliError("configuration_error", "this profile follows no feeds");
+            return run.feeds();
+        };
         example(
         // A fetch, but also a new secret and a new address every later sync reads: the read-only lock refuses it.
         changesStore(annotate(calendars.command("add"), { effects: FETCH, offline: false, mcp: false }))
             .description("follow an iCalendar feed, such as a holiday calendar or a published .ics address, as a read-only calendar " +
-            "of this profile; sync reads it again each time. The address is kept as a secret and never printed")
+            "of this profile that sync reads again each time; the address is kept as a secret and never printed")
             .summary("follow an iCalendar feed as a read-only calendar")
             .addArgument(secretInput(new Argument("<url>", "the feed's https://, http:// or webcal:// address")))
             .option("--title <title>", "the calendar's title; the feed's own name if not given"), "calendars add webcal://example.com/holidays.ics --title Holidays").action(async (url, opts, command) => {
             if (command.optsWithGlobals().offline)
                 throw new CliError("permission_error", "calendars add reads the feed; leave out --offline");
-            const { calendar, events } = await feeds().add(url, opts.title === undefined ? {} : { title: opts.title });
-            if (isPlainHttp(url))
-                outputFor(command).renderer.warn("this feed's address starts with http://, so the feed and any token in its address travel unencrypted; " +
-                    "use https:// if the server offers it");
-            const [saved] = await deps.store.saveCalendars(deps.accountId, [calendar], now());
-            print({
-                ...calendarItem(saved),
-                events,
-                hint: `run ${lineOf(command, "sync")} to store its events`,
-            }, command);
+            await within(command, async (run) => {
+                const { calendar, events } = await feedsOf(run).add(url, opts.title === undefined ? {} : { title: opts.title });
+                if (isPlainHttp(url))
+                    outputFor(command).renderer.warn("this feed's address starts with http://, so the feed and any token in its address travel unencrypted; " +
+                        "use https:// if the server offers it");
+                const [saved] = await run.store.saveCalendars(run.accountId, [calendar], now());
+                return itemBody({
+                    ...calendarItem(saved),
+                    events,
+                    hint: `run ${lineOf(command, "sync")} to store its events`,
+                });
+            });
         });
         example(annotate(calendars.command("remove"), { effects: LOCAL_WRITE, mcp: false })
             .description("stop following a feed calendars add added: its address is forgotten and its stored events are deleted, " +
-            "not cancelled. Only a feed; calendars unsync stops a provider's calendar")
+            "not cancelled; only a feed, as calendars unsync stops a provider's calendar")
             .argument("<calendar>", "the feed calendar's id, its ics: id, or its title"), "calendars remove 7").action(async (reference, _opts, command) => {
-            const calendar = await calendarIn(deps.store, deps.accountId, reference);
-            if (!isFeedCalendar(calendar))
-                throw new CliError("validation_error", `calendar ${calendar.id} is not a feed; calendars remove takes only feeds`, {
-                    reason: "feed.not-a-feed",
-                });
-            await feeds().remove(calendar.externalId);
-            const { entries, events } = await deps.store.forgetCalendar(calendar.id, now());
-            print({ ...calendarItem({ ...calendar, synced: false }), removed: entries, events }, command);
+            await within(command, async (run) => {
+                const calendar = await calendarIn(run.store, run.accountId, reference);
+                if (!isFeedCalendar(calendar))
+                    throw new CliError("validation_error", `calendar ${calendar.id} is not a feed; calendars remove takes only feeds`, { reason: "feed.not-a-feed" });
+                await feedsOf(run).remove(calendar.externalId);
+                const { entries, events } = await run.store.forgetCalendar(calendar.id, now());
+                return itemBody({ ...calendarItem({ ...calendar, synced: false }), removed: entries, events });
+            });
         });
     }
-    if (deps.freeBusy)
+    if (options.freeBusy)
         example(withQuery(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false, partial: true }).description("when calendars and people are taken, asked of the provider and not stored; with --duration-minutes, " +
-            "the free stretches they share"), BUSY_QUERY).addHelpText("after", BUSY_QUERY_NOTE), "calendars busy person:ana@example.com --json", "calendars busy start>=2026-11-02 end<=2026-11-06 person:ana@example.com --duration-minutes 30 " +
+            "the free stretches they share"), BUSY_QUERY).addHelpText("after", BUSY_QUERY_NOTE), "calendars busy person:ana@example.com --json", "calendars busy starts_at>=2026-11-02 ends_at<=2026-11-06 person:ana@example.com --duration-minutes 30 " +
             "--hours 10:00-16:00")
             .option("--duration-minutes <minutes>", "find free stretches at least this long, 5–1440", minutes)
             .option("--hours <from-to>", "working hours in your time zone, Monday to Friday, with --duration-minutes", "09:00-17:00")
@@ -166,12 +171,15 @@ const addCalendarCommandsDefinition = (program, deps) => {
                     reason: "busy.offline",
                 });
             const hours = workingHoursOf(opts.hours);
-            const query = await busyQuery(words, { store: deps.store, accountId: deps.accountId, zone: zone(), now: now() });
-            print(await busyAnswer(source(), query, {
-                zone: zone(),
-                now: now(),
-                ...(opts.durationMinutes === undefined ? {} : { slot: { minutes: opts.durationMinutes, hours } }),
-            }), command);
+            await within(command, async (run) => {
+                const query = await busyQuery(words, { store: run.store, accountId: run.accountId, zone: zone(), now: now() });
+                const { meta, ...busy } = await busyAnswer(run.source(), query, {
+                    zone: zone(),
+                    now: now(),
+                    ...(opts.durationMinutes === undefined ? {} : { slot: { minutes: opts.durationMinutes, hours } }),
+                });
+                return itemBody(busy, { meta });
+            });
         });
     example(annotate(program.command("sync"), {
         effects: FETCH,
@@ -188,133 +196,149 @@ const addCalendarCommandsDefinition = (program, deps) => {
         if (command.optsWithGlobals().full)
             throw new CliError("validation_error", "sync starts over with --rescan; --full only widens output");
         const { signal } = environmentOf(command);
-        const report = await syncWithFeeds(source(), deps.feeds, deps.store, {
-            accountId: deps.accountId,
-            now: now(),
-            budget: runBudgetOf(command, opts.maxPages),
-            ...(signal ? { signal } : {}),
-            ...(opts.rescan ? { full: true } : {}),
-            ...(deps.expand ? { expand: deps.expand } : {}),
-        });
-        if (opts.embed && !deps.embed)
-            throw new CliError("configuration_error", "this tool cannot embed events");
-        // A run its budget stopped has no time left for the model; the run that finishes the round embeds.
-        const embeddings = opts.embed && !report.stopped ? await deps.embed?.(EMBED_MAX) : undefined;
-        const timeout = command.optsWithGlobals().timeout;
-        // The same command again, never --rescan: that would drop the round this run leaves in progress. A run that moved
-        // nothing on would only repeat itself, so it gets no step an agent may run unasked.
-        const stuck = report.state === "partial" && report.progress.steps === 0 && !report.synced.some((one) => one.error);
-        const next = report.state === "partial" && !stuck && !report.synced.some((one) => one.error !== undefined)
-            ? [
-                {
-                    kind: "command",
-                    step: "calendar.sync",
-                    command: "sync",
-                    args: Object.fromEntries(Object.entries({ max_pages: opts.maxPages, timeout, embed: opts.embed }).filter(([, value]) => value !== undefined)),
-                    why: "the sync stopped before its end to answer in time; running it again goes on from where it stopped",
-                    safe_to_auto_execute: true,
-                },
-            ]
-            : undefined;
-        const progressAt = lineOf(command, "store status");
-        report.hint = stuck
-            ? `this run moved nothing on: raise --timeout or --max-pages, then run sync again; see progress: ${progressAt}`
-            : report.state === "partial"
-                ? `run sync again to continue; see progress: ${progressAt}`
-                : report.hint;
-        if (report.hint === undefined)
-            delete report.hint;
-        const failed = report.synced.filter((one) => one.error !== undefined);
-        if (failed.length)
-            // A failure prints nothing on stdout (WC-OUT-14), so the error carries every calendar's result.
-            throw new CliError("provider_error", `${failed.map((one) => `calendar ${one.calendarId} (${one.title ?? one.externalId}): ${one.error}`).join("; ")}` +
-                " — run sync again to retry", {
+        await within(command, async (run) => {
+            if (opts.embed && !run.messages)
+                throw new CliError("configuration_error", "this tool cannot embed events");
+            const report = await syncWithFeeds(run.source(), run.feeds?.(), run.store, {
+                accountId: run.accountId,
+                now: now(),
+                budget: runBudgetOf(command, opts.maxPages),
+                ...(signal ? { signal } : {}),
+                ...(opts.rescan ? { full: true } : {}),
+                ...(run.expand ? { expand: run.expand } : {}),
+            });
+            // A run its budget stopped has no time left for the model; the run that finishes the round embeds.
+            const embeddings = opts.embed && !report.stopped && run.messages
+                ? await embedEvents(run.messages, {
+                    maxChunks: EMBED_MAX,
+                    ...(run.env ? { env: run.env } : {}),
+                    command: options.app.command,
+                })
+                : undefined;
+            const failed = report.synced.filter((one) => one.error !== undefined);
+            const timeout = command.optsWithGlobals().timeout;
+            // The same command again, never --rescan: that would drop the round this run leaves in progress. A run that
+            // moved nothing on would only repeat itself, so it gets no step; a sync sends the provider no write, so
+            // running it again is safe.
+            const stuck = report.state === "partial" && report.progress.steps === 0 && failed.length === 0;
+            const why = failed.length
+                ? "a calendar failed to sync; running sync again retries it"
+                : "the sync stopped before its end to answer in time; running it again goes on from there";
+            const next = failed.length || (report.state === "partial" && !stuck)
+                ? [
+                    {
+                        kind: "command",
+                        step: "calendar.sync",
+                        command: "sync",
+                        args: Object.fromEntries(Object.entries({ max_pages: opts.maxPages, timeout, embed: opts.embed }).filter(([, value]) => value !== undefined)),
+                        why,
+                        safe_to_auto_execute: true,
+                    },
+                ]
+                : undefined;
+            const progressAt = lineOf(command, "store status");
+            report.hint = failed.length
+                ? `${failed.map((one) => `calendar ${one.calendarId} (${one.title ?? one.externalId}): ${one.error}`).join("; ")}` +
+                    " — run sync again to retry"
+                : stuck
+                    ? `this run moved nothing on: raise --timeout or --max-pages, then run sync again; see progress: ${progressAt}`
+                    : report.state === "partial"
+                        ? `run sync again to continue; see progress: ${progressAt}`
+                        : report.hint;
+            if (report.hint === undefined)
+                delete report.hint;
+            // What the healthy calendars brought is saved and answered; each failed one is an issue (WC-OUT-7, WC-OUT-8).
+            const issues = failed.map((one) => ({
+                code: "provider_error",
                 reason: "sync.partial",
-                calendars: report.synced.map((one) => ({
-                    calendar_id: String(one.calendarId),
-                    external_id: one.externalId,
-                    title: one.title,
-                    round: one.round,
-                    state: one.state,
-                    saved: one.saved,
-                    removed: one.removed,
-                    occurrences: one.occurrences,
-                    ...(one.error === undefined ? {} : { error: one.error }),
-                })),
-                retryable: true,
-                // A sync sends the provider no write, so running it again changes nothing there.
-                sent: false,
+                source: `calendar:${one.calendarId}`,
+            }));
+            const partial = report.state === "partial" || issues.length > 0;
+            return itemBody({ ...report, ...(embeddings === undefined ? {} : { embeddings }) }, {
+                ...(partial ? { meta: { complete: false, ...(issues.length ? { issues } : {}) } } : {}),
+                ...(next ? { next } : {}),
             });
-        print({ ...report, ...(embeddings === undefined ? {} : { embeddings }), ...(next ? { next } : {}) }, command);
+        });
     });
     const store = annotate(program.command("store").description("the local store of calendar events"), {
         effects: GROUP,
     });
     example(annotate(store.command("status"), { effects: LOCAL_READ }).description("how far each synced calendar's sync is: entries done, partial or complete, and when it last moved"), "store status --json").action(async (_opts, command) => {
-        print(await calendarStatus(deps.store, deps.accountId, {
-            profile: deps.profile ?? `account ${deps.accountId}`,
-            now: now(),
-        }), command);
+        await within(command, async (run) => listBody(command, await calendarStatus(run.store, run.accountId, { profile: run.profile, now: now() })));
     });
+    const personOfEmail = (run) => {
+        const shared = run.messages;
+        return shared
+            ? async (email) => {
+                const person = await shared.people.personOf({ provider: "email", id: email });
+                return person ? `person:${person.uid}` : null;
+            }
+            : undefined;
+    };
+    const personId = (run) => async (reference) => {
+        const text = reference.replace(/^person:/u, "");
+        if (/^[1-9]\d*$/u.test(text))
+            return Number(text);
+        const person = await messagesOf(run, "person:").people.personOf({
+            provider: "email",
+            id: text.trim().toLowerCase(),
+        });
+        return person ? Number(person.uid) : null;
+    };
     const events = annotate(program.command("events").description("the account's stored events"), { effects: GROUP });
     example(withQuery(annotate(events.command("list"), { effects: LOCAL_READ, partial: true }).description("list stored events, earliest first; --source reads several accounts as one list"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), "events list 'starts_at:[2026-11-02 TO 2026-11-07}' --json", "events list ends_at>=today person:ana@example.com", "events list overlapping:true --source all")
         .option("--limit <n>", "events per page, 1–1000", integer, 100)
         .option("--page <n>", "which page, starting at 1", integer, 1)
         .option("--source <accounts>", "calendar accounts held in the store to read as one list: all, a provider, or a list such as " +
-        `${program.name()}:work,${program.name()}:personal or group:<name>; the profile's account when absent`)
+        `${options.app.command}:work,${options.app.command}:personal or group:<name>; the profile's account when absent`)
         .action(async (words, opts, command) => {
-        const own = { id: deps.accountId, key: deps.account };
-        const { accounts, skipped } = opts.source === undefined
-            ? { accounts: [own], skipped: [] }
-            : await sourceAccounts(messages("--source"), deps.account, opts.source, program.name());
-        if (deps.locked && accounts.some(({ id }) => id !== own.id))
-            throw new CliError("permission_error", "this process is locked to one profile; --source may name only its own account", { reason: "profile.locked" });
-        const filter = await eventsFilter(words, {
-            store: deps.store,
-            accountId: deps.accountId,
-            accountIds: accounts.map(({ id }) => id),
-            zone: zone(),
-            now: now(),
-            personOf: personId,
+        await within(command, async (run) => {
+            const own = { id: run.accountId, key: run.account };
+            const { accounts, skipped } = opts.source === undefined
+                ? { accounts: [own], skipped: [] }
+                : await sourceAccounts(messagesOf(run, "--source"), run.account, opts.source, options.app.command);
+            if (run.locked && accounts.some(({ id }) => id !== own.id))
+                throw new CliError("permission_error", "this process is locked to one profile; --source may name only its own account", { reason: "profile.locked" });
+            const filter = await eventsFilter(words, {
+                store: run.store,
+                accountId: run.accountId,
+                accountIds: accounts.map(({ id }) => id),
+                zone: zone(),
+                now: now(),
+                personOf: personId(run),
+            });
+            return listBody(command, eachMarked(await eventsAnswer(run.store, filter && { ...filter, limit: opts.limit }, opts.page), EVENT_ITEM_UNTRUSTED), { ...(await accountsMeta(run.store, accounts, skipped, now())), ...clockMeta(now(), zone()) });
         });
-        print({
-            ...eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }, opts.page), EVENT_ITEM_UNTRUSTED),
-            meta: { ...(await accountsMeta(deps.store, accounts, skipped, now())), ...clockMeta(now(), zone()) },
-        }, command);
     });
-    const exporter = example(withQuery(annotate(events.command("export"), { effects: deps.writeFile ? LOCAL_WRITE : LOCAL_READ }).description(`write stored events as iCalendar (.ics), at most ${EXPORT_MAX}: one with id:<id>, or those the query ` +
-        "finds; each occurrence of a repeating event as an event of its own"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), ...(deps.writeFile
-        ? [
-            "events export id:42 --output planning.ics",
-            "events export 'starts_at:[2026-11-02 TO 2026-11-09}' NOT event_type:birthday --output week.ics",
-        ]
-        : ["events export id:42", "events export 'starts_at:[2026-11-02 TO 2026-11-09}' NOT event_type:birthday"]));
+    const exporter = example(withQuery(annotate(events.command("export"), { effects: LOCAL_WRITE }).description(`write stored events as iCalendar (.ics), at most ${EXPORT_MAX}: one with id:<id>, or those the query ` +
+        "finds; each occurrence of a repeating event as an event of its own"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), "events export id:42 --output planning.ics", "events export 'starts_at:[2026-11-02 TO 2026-11-09}' NOT event_type:birthday --output week.ics");
     // Not over MCP: an agent would choose where on the owner's disk to write. It gets the text in the answer.
-    if (deps.writeFile)
-        writesFileOnlyWith(exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent")), "output");
+    writesFileOnlyWith(exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent")), "output");
     exporter.action(async (words, opts, command) => {
-        const filter = await eventsFilter(words, {
-            store: deps.store,
-            accountId: deps.accountId,
-            zone: zone(),
-            now: now(),
-            personOf: personId,
-        });
-        const exported = await eventsIcs(deps.store, deps.accountId, filter, { now: now(), product: program.name() });
-        if (opts.output === undefined) {
-            print({ ...exported, untrusted: ["content"] }, command);
-            return;
-        }
-        if (!opts.output.trim())
+        if (opts.output !== undefined && !opts.output.trim())
             throw new CliError("validation_error", "--output names no file");
-        await deps.writeFile?.(opts.output, exported.content);
-        print({ format: exported.format, events: exported.events, output: opts.output }, command);
+        await within(command, async (run) => {
+            const filter = await eventsFilter(words, {
+                store: run.store,
+                accountId: run.accountId,
+                zone: zone(),
+                now: now(),
+                personOf: personId(run),
+            });
+            const exported = await eventsIcs(run.store, run.accountId, filter, { now: now(), product: options.app.command });
+            if (opts.output === undefined)
+                return itemBody({ ...exported, untrusted: ["content"] });
+            await (options.writeFile ?? writeIcsFile)(opts.output, exported.content);
+            return itemBody({ format: exported.format, events: exported.events, output: opts.output });
+        });
     });
     example(annotate(events.command("show"), { effects: LOCAL_READ })
         .description("one event: its calendar copies, attendees with their person, Drive files and history")
         .argument("<event>", "the event's id, or event:<id>"), "events show event:42 --json").action(async (reference, _opts, command) => {
-        const shown = await eventAnswer(await eventOf(deps.store, deps.accountId, eventIdOf(reference)), personOfEmail);
-        print({ ...shown, untrusted: CALENDAR_UNTRUSTED_FIELDS }, command);
+        await within(command, async (run) => {
+            const shown = await eventAnswer(await eventOf(run.store, run.accountId, eventIdOf(reference)), personOfEmail(run));
+            return itemBody({ ...shown, untrusted: CALENDAR_UNTRUSTED_FIELDS });
+        });
     });
     example(annotate(events.command("prepare"), { effects: LOCAL_READ, partial: true })
         .description("before a meeting: the event, its attendees with their answer, and each one's latest messages, mail and " +
@@ -329,60 +353,48 @@ const addCalendarCommandsDefinition = (program, deps) => {
             zone: zone(),
             now: now(),
         });
-        const details = reference === undefined
-            ? await nextMeeting(deps.store, deps.accountId, now())
-            : await eventOf(deps.store, deps.accountId, eventIdOf(reference));
-        const { meta, ...prepared } = await eventPreparation(details, {
-            store: deps.store,
-            messages: messages("events prepare"),
-            account: { id: deps.accountId, key: deps.account },
-            personOf: personOfEmail ?? (async () => null),
-            now: now(),
-            ...(opts.limit === undefined ? {} : { limit: opts.limit }),
-            ...(window.since === undefined ? {} : { since: window.since }),
+        await within(command, async (run) => {
+            const details = reference === undefined
+                ? await nextMeeting(run.store, run.accountId, now())
+                : await eventOf(run.store, run.accountId, eventIdOf(reference));
+            const { meta, ...prepared } = await eventPreparation(details, {
+                store: run.store,
+                messages: messagesOf(run, "events prepare"),
+                account: { id: run.accountId, key: run.account },
+                personOf: personOfEmail(run) ?? (async () => null),
+                now: now(),
+                ...(opts.limit === undefined ? {} : { limit: opts.limit }),
+                ...(window.since === undefined ? {} : { since: window.since }),
+            });
+            return itemBody(prepared, { meta: { ...meta, ...window.meta, ...clockMeta(now(), zone()) } });
         });
-        print({ ...prepared, meta: { ...meta, ...window.meta, ...clockMeta(now(), zone()) } }, command);
     });
-    if (deps.writes)
-        addRemind(events, deps.writes, { deps, now, zone, print, example });
-    const app = deps.messages ? deps.app : undefined;
-    const searches = annotate(program
-        .command("search")
-        .description(app
-        ? "find stored things by text: events, or all of messages, notes and events"
-        : "find stored things by text: events"), { effects: GROUP });
-    if (app)
-        addSearchAll(searches, { deps, app, zone, messages, example });
-    const search = example(annotate(searches.command("events"), { effects: deps.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
-        .description(deps.serverSearch
+    if (options.writes)
+        addRemind(events, { within, now, zone, example });
+    const searches = annotate(program.command("search").description("find stored things by text: events, or all of messages, notes and events"), { effects: GROUP });
+    addSearchAll(searches, { within, app: options.app, zone, example });
+    const search = example(annotate(searches.command("events"), { effects: options.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
+        .description(options.serverSearch
         ? "find stored events by words, and by meaning when its model is downloaded; with --backend server, ask " +
             "the provider instead, or with --backend both, ask both"
         : "find stored events by words, and by meaning when its model is downloaded")
-        .argument("<query...>", "what to find in titles, descriptions, places and attendees"), "search events roadmap planning --json", ...(deps.serverSearch
+        .argument("<query...>", "what to find in titles, descriptions, places and attendees"), "search events roadmap planning --json", ...(options.serverSearch
         ? ["search events --backend server quarterly review", "search events --backend both quarterly review"]
         : []))
         .option("--limit <n>", "events per page", integer, 20)
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it", (text) => (text === "0" ? 0 : integer(text)), 0)
         .option("--exact", "every word as written, no word stems")
         .option("--newest", "latest start first instead of best first");
-    if (deps.serverSearch)
+    if (options.serverSearch)
         search.addOption(new Option("--backend <archive|server|both>", "where to search: archive, the local store, or server, the provider's own search over the synced calendars, " +
             "earliest first; both gives the store's hits, each the provider also found marked server, then the " +
             "provider's other hits, one page with no cursor")
             .choices(["archive", "server", "both"])
             .default("archive"));
     search.action(async (words, opts, command) => {
-        const archived = () => searchEvents(messages("search"), words.join(" "), {
-            accounts: [deps.account],
-            limit: opts.limit,
-            offset: opts.cursor,
-            timezone: zone(),
-            command: program.name(),
-            ...(opts.exact ? { exact: true } : {}),
-            ...(opts.newest ? { newest: true } : {}),
-        });
-        if (opts.backend === "server" || opts.backend === "both") {
-            const flag = `search events --backend ${opts.backend}`;
+        const flag = `search events --backend ${opts.backend}`;
+        const server = opts.backend === "server" || opts.backend === "both";
+        if (server) {
             if (command.optsWithGlobals().offline)
                 throw new CliError("permission_error", `${flag} asks the provider; leave out --offline`, {
                     reason: "search.offline",
@@ -393,90 +405,111 @@ const addCalendarCommandsDefinition = (program, deps) => {
                 });
             if (opts.cursor || opts.newest)
                 throw new CliError("validation_error", `${flag} takes neither --cursor nor --newest: the provider ranks and pages its own hits`, { reason: "search.server-options" });
-            const served = await serverSearchAnswer(source(), deps.store, {
-                accountId: deps.accountId,
-                account: deps.account,
+        }
+        await within(command, async (run) => {
+            const archived = () => searchEvents(messagesOf(run, "search"), words.join(" "), {
+                accounts: [run.account],
+                limit: opts.limit,
+                offset: opts.cursor,
+                timezone: zone(),
+                command: options.app.command,
+                ...(opts.exact ? { exact: true } : {}),
+                ...(opts.newest ? { newest: true } : {}),
+            });
+            if (!server)
+                return hitsBody(command, { ...(await archived()), untrusted: SEARCH_UNTRUSTED });
+            const served = await serverSearchAnswer(run.source(), run.store, {
+                accountId: run.accountId,
+                account: run.account,
                 query: words.join(" "),
                 limit: opts.limit,
             });
             if (opts.backend === "server")
-                print({ ...served, untrusted: SERVER_SEARCH_UNTRUSTED }, command);
-            else
-                print({
-                    ...(await bothSearchAnswer(deps.store, deps.accountId, await archived(), served, opts.limit)),
-                    untrusted: SEARCH_UNTRUSTED,
-                }, command);
-            return;
-        }
-        print({ ...(await archived()), untrusted: SEARCH_UNTRUSTED }, command);
+                return hitsBody(command, { ...served, untrusted: SERVER_SEARCH_UNTRUSTED });
+            return hitsBody(command, {
+                ...(await bothSearchAnswer(run.store, run.accountId, await archived(), served, opts.limit)),
+                untrusted: SEARCH_UNTRUSTED,
+            });
+        });
     });
-    if (deps.writes)
-        addEventWrites(events, deps.writes, { deps, now, zone, print, example });
+    if (options.writes)
+        addEventWrites(events, options.writes, { within, now, zone, example, readFile: options.readFile });
     const people = annotate(program.command("people").description("the people in the account's events"), {
         effects: GROUP,
     });
     withQuery(example(annotate(people.command("list"), { effects: LOCAL_READ }).description("one event's attendees, or everyone attending this week's events"), "people list --json", "people list event:42"), PEOPLE_QUERY).action(async (words, _opts, command) => {
         const reference = queryTerms(words, PEOPLE_QUERY, "people list").get("event");
         const event = reference === undefined ? undefined : eventIdOf(reference);
-        const filter = event === undefined ? weekFilter(deps.accountId, zone(), now()) : undefined;
-        const people = await peopleAnswer(deps.store, deps.accountId, {
-            ...(event === undefined ? {} : { event }),
-            ...(filter ? { filter } : {}),
-            ...(personOfEmail ? { personOf: personOfEmail } : {}),
+        await within(command, async (run) => {
+            const filter = event === undefined ? weekFilter(run.accountId, zone(), now()) : undefined;
+            const personOf = personOfEmail(run);
+            const found = await peopleAnswer(run.store, run.accountId, {
+                ...(event === undefined ? {} : { event }),
+                ...(filter ? { filter } : {}),
+                ...(personOf ? { personOf } : {}),
+            });
+            return listBody(command, eachMarked(found, ATTENDEE_UNTRUSTED));
         });
-        print(eachMarked(people, ATTENDEE_UNTRUSTED), command);
     });
     example(annotate(people.command("link"), { effects: LOCAL_WRITE })
         .description("join an attendee to a person the owner knows elsewhere")
         .argument("<person>", "an attendee's address as email:<address>, or a person:<id>")
         .argument("<other>", "the same person in another tool, as <provider>:<person>, or me"), "people link email:ana@example.com telegram:12345").action(async (person, other, _opts, command) => {
-        const linked = await linkPeople(messages("people link"), deps.account, person, other);
-        print({
-            person: `person:${linked.uid}`,
-            name: linked.name,
-            identities: linked.identities.map(({ provider, id }) => `${provider}:${id}`),
-        }, command);
+        await within(command, async (run) => {
+            const linked = await linkPeople(messagesOf(run, "people link"), run.account, person, other);
+            return itemBody({
+                person: `person:${linked.uid}`,
+                name: linked.name,
+                identities: linked.identities.map(({ provider, id }) => `${provider}:${id}`),
+            });
+        });
     });
     const links = annotate(program.command("links").description("calendar copies the rules could not join alone"), {
         effects: GROUP,
     });
     example(annotate(links.command("review"), { effects: LOCAL_READ }).description("copies that fit two or more events equally well, waiting for the owner's choice"), "links review --json").action(async (_opts, command) => {
-        // Locked to a profile (WC-ACCT-5), or with no shared store to name the others by, only the profile's own account.
-        const own = deps.locked || !deps.messages;
-        const answer = await reviewsAnswer(deps.store, own ? [deps.accountId] : undefined);
-        const accounts = own
-            ? [`${deps.account.provider}:${deps.account.account}`]
-            : await calendarAccountNames(deps.store, messages("links review"), deps.account);
-        print({ ...eachMarked(answer, REVIEW_UNTRUSTED), meta: { accounts, complete: true } }, command);
+        await within(command, async (run) => {
+            // Locked to a profile (WC-ACCT-5), or with no shared store to name the others by, only the profile's own account.
+            const own = run.locked || !run.messages;
+            const found = await reviewsAnswer(run.store, own ? [run.accountId] : undefined);
+            const accounts = own
+                ? [`${run.account.provider}:${run.account.account}`]
+                : await calendarAccountNames(run.store, messagesOf(run, "links review"), run.account);
+            return listBody(command, eachMarked(found, REVIEW_UNTRUSTED), { accounts, complete: true });
+        });
     });
     example(annotate(links.command("resolve"), { effects: LOCAL_WRITE })
         .description("join a copy to the event you choose, or keep it apart")
         .argument("<review>", "the review's id from links review")
         .argument("<choice>", "one of its candidates, as event:<id>, or apart"), "links resolve 7 event:42").action(async (review, choice, _opts, command) => {
-        print(await resolveAnswer(deps.store, deps.accountId, review, choice, now()), command);
+        await within(command, async (run) => itemBody(await resolveAnswer(run.store, run.accountId, review, choice, now())));
     });
     const leaves = (command) => command.commands.length ? command.commands.flatMap(leaves) : [command];
     declareCalendarAnswers(program, program.commands.filter((one) => !mounted.has(one)).flatMap(leaves));
 };
 const collect = (value, previous = []) => [...previous, value];
-const addEventWrites = (events, writes, { deps, now, zone, print, example }) => {
-    const context = (command) => ({
-        store: deps.store,
-        accountId: deps.accountId,
-        writes,
-        ask: terminalAsker(command),
-        now: now(),
-        zone: zone(),
-        names: {
-            notify: "--notify or --no-notify",
-            id: "--operation-id",
-            calendar: "--calendar",
-            series: "--series",
-            following: "--following",
-            repeat: "--repeat",
-        },
-    });
-    const printWritten = (value, command) => print({ ...value, untrusted: CALENDAR_UNTRUSTED_FIELDS }, command);
+const addEventWrites = (events, traits, { within, now, zone, example, readFile }) => {
+    const contextOf = (run, command) => {
+        if (!run.writes)
+            throw new CliError("configuration_error", "this profile cannot write to its calendars");
+        return {
+            store: run.store,
+            accountId: run.accountId,
+            writes: run.writes(),
+            ask: terminalAsker(command),
+            now: now(),
+            zone: zone(),
+            names: {
+                notify: "--notify or --no-notify",
+                id: "--operation-id",
+                calendar: "--calendar",
+                series: "--series",
+                following: "--following",
+                repeat: "--repeat",
+            },
+        };
+    };
+    const written = (command, write) => within(command, async (run) => itemBody({ ...(await write(contextOf(run, command))), untrusted: CALENDAR_UNTRUSTED_FIELDS }));
     // Left out on purpose: with other attendees the owner must choose, so neither switch is the default.
     const notify = (command) => command
         .option("--notify", "the provider mails the other attendees; needs events.notify allowed; this or --no-notify is required " +
@@ -508,7 +541,7 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
     const target = (command) => command
         .argument("<event>", "the event's id, or event:<id>")
         .option("--calendar <id>", "the calendar, by id or title, when the event is on more than one of the account's");
-    const quick = writes.writer.quickAdd !== undefined;
+    const quick = traits.quickAdd === true;
     const create = example(notify(fields(write("create"), false)
         .description(quick
         ? "add an event to a calendar; with --repeat, one that repeats; with --text, one the provider reads " +
@@ -521,20 +554,18 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
         "--repeat 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12'");
     if (quick)
         create.option("--text <text>", "one line the provider reads the title, date, time and place from, in place of the other fields; nobody is " +
-            "mailed without --notify, and a retry after outcome_unknown may add the event twice");
+            "mailed without --notify");
     create.action(async (calendar, opts, command) => {
         const { notify: choice, operationId: id, text, ...rest } = opts;
+        const options = { ...(choice === undefined ? {} : { notify: choice }), ...(id === undefined ? {} : { id }) };
         if (text !== undefined) {
             const given = Object.keys(fieldsOf(rest));
-            if (given.length || id !== undefined)
-                throw new CliError("validation_error", `--text takes the whole event from its line; leave out ${[...given.map(flagOf), ...(id === undefined ? [] : ["--operation-id"])].join(", ")}`, { reason: "event.text-with-fields", param: "--text" });
-            printWritten(await createEventFromText(context(command), calendar, text, choice === undefined ? {} : { notify: choice }), command);
+            if (given.length)
+                throw new CliError("validation_error", `--text takes the whole event from its line; leave out ${given.map(flagOf).join(", ")}`, { reason: "event.text-with-fields", param: "--text" });
+            await written(command, (context) => createEventFromText(context, calendar, text, options));
             return;
         }
-        printWritten(await createEvent(context(command), calendar, fieldsOf(rest), {
-            ...(choice === undefined ? {} : { notify: choice }),
-            ...(id === undefined ? {} : { id }),
-        }), command);
+        await written(command, (context) => createEvent(context, calendar, fieldsOf(rest), options));
     });
     example(notify(target(fields(write("update"), true))
         .description("change an event; with --series every occurrence of the repeating event, with --following this " +
@@ -544,44 +575,40 @@ const addEventWrites = (events, writes, { deps, now, zone, print, example }) =>
         "with the change")
         .option("--operation-id <id>", "with --following, the operation_id an outcome_unknown named: a retry finds that new series")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify", "events update event:42 --series --repeat 'FREQ=WEEKLY;BYDAY=TU;UNTIL=20261231T230000Z' --no-notify", "events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify").action(async (reference, opts, command) => {
         const { calendar: _calendar, series: _series, following: _following, notify: _notify, operationId: id, ...rest } = opts;
-        printWritten(await updateEvent(context(command), reference, fieldsOf(rest), {
-            ...choicesOf(opts),
-            ...(id === undefined ? {} : { id }),
-        }), command);
+        await written(command, (context) => updateEvent(context, reference, fieldsOf(rest), { ...choicesOf(opts), ...(id === undefined ? {} : { id }) }));
     });
     example(notify(target(write("delete"))
         .description("delete an event; a whole repeating event, or every later occurrence, needs events.delete.series " +
         "allowed first")
         .option("--series", "delete the whole repeating event, not only this occurrence")
         .option("--following", "delete this occurrence and every later one: the repeating event ends before it")), "events delete event:42 --no-notify", "events delete event:42 --following --no-notify").action(async (reference, opts, command) => {
-        printWritten(await deleteEvent(context(command), reference, choicesOf(opts)), command);
+        await written(command, (context) => deleteEvent(context, reference, choicesOf(opts)));
     });
-    const readFile = deps.readFile;
-    if (writes.writer.importEvent && readFile)
+    if (traits.importEvent)
         example(write("import")
             .description(`add the events of an iCalendar (.ics) file to a calendar, at most ${IMPORT_MAX}, each under its own UID; ` +
             "nobody is mailed; a changed occurrence of a repeating event (RECURRENCE-ID) is skipped")
             .argument("<calendar>", "the calendar's id, the provider's id, or its title")
             .argument("<file>", "the .ics file to read"), "events import Work planning.ics").action(async (calendar, file, _opts, command) => {
-            const text = await readFile(file);
+            const text = await (readFile ?? readIcsFile)(file);
             if (Buffer.byteLength(text, "utf8") > ICS_MAX_BYTES)
                 throw new CliError("validation_error", `${file} is larger than ${ICS_MAX_BYTES / 1024 / 1024} MB`, {
                     reason: "ics.too-large",
                 });
-            print({ ...(await importEvents(context(command), calendar, text)), untrusted: IMPORT_UNTRUSTED }, command);
+            await within(command, async (run) => itemBody({ ...(await importEvents(contextOf(run, command), calendar, text)), untrusted: IMPORT_UNTRUSTED }));
         });
-    if (writes.writer.move)
+    if (traits.move)
         example(notify(target(write("move"))
             .description("move an event, with its id, to another calendar of the account; a repeating one moves whole")
             .requiredOption("--to-calendar <id>", "the calendar to move it to: its id, the provider's id, or its title")
             .option("--series", "move the whole repeating event an occurrence belongs to")), "events move event:42 --to-calendar 4 --no-notify").action(async (reference, opts, command) => {
             const { series, calendar, notify } = opts;
-            printWritten(await moveEvent(context(command), reference, opts.toCalendar, choicesOf({ series, calendar, notify })), command);
+            await written(command, (context) => moveEvent(context, reference, opts.toCalendar, choicesOf({ series, calendar, notify })));
         });
     example(notify(target(write("respond"))
         .description("answer an invitation; the organiser is told only with --notify")
         .addArgument(new Argument("<response>", "the answer").choices(EVENT_RESPONSES))), "events respond event:42 accepted --notify").action(async (reference, response, opts, command) => {
-        printWritten(await respondToEvent(context(command), reference, response, choicesOf(opts)), command);
+        await written(command, (context) => respondToEvent(context, reference, response, choicesOf(opts)));
     });
 };
 // honoursDryRun: a host program other than `run` would otherwise let a write through under --dry-run.