@wirecat/cli-core 0.547.0 → 0.549.0

package/dist/calendar/feeds.js

@@ -26,6 +26,8 @@ export const feedAddress = (text) => {
         throw invalidAddress("must not hold a user name or a password");
     return url;
 };
+/** An `http://` address: allowed, but the feed and any token in its address travel unencrypted. */
+export const isPlainHttp = (text) => feedAddress(text).protocol === "http:";
 const sameAddress = (a, b) => feedAddress(a).href === feedAddress(b).href;
 const readBody = async (response, name, maxBytes) => {
     const reader = response.body?.getReader();
@@ -58,8 +60,17 @@ const STATUS_ERRORS = {
  * The feed's text: http or https, each redirect followed by hand and only to https, the body cut off at its limit and
  * the request at its time. Errors name the feed and the status, never the address, which may hold a token.
  */
-export const fetchFeed = async (address, options) => {
-    const { name, limits = FEED_LIMITS } = options;
+export const fetchFeed = async (address, options) => (await fetchFeedIfChanged(address, options)).text;
+/**
+ * `fetchFeed` that sends `since` as `If-None-Match` and `If-Modified-Since`: `"unchanged"` when the server answers 304,
+ * otherwise the text and the validators to send next time.
+ */
+export const fetchFeedIfChanged = async (address, options) => {
+    const { name, limits = FEED_LIMITS, since } = options;
+    const conditional = {
+        ...(since?.etag ? { "if-none-match": since.etag } : {}),
+        ...(since?.lastModified ? { "if-modified-since": since.lastModified } : {}),
+    };
     const run = options.fetch ?? fetch;
     const timeout = AbortSignal.timeout(limits.timeoutMs);
     const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
@@ -69,8 +80,12 @@ export const fetchFeed = async (address, options) => {
             const response = await run(url, {
                 redirect: "manual",
                 signal,
-                headers: { accept: "text/calendar, text/plain;q=0.5, */*;q=0.1" },
+                headers: { accept: "text/calendar, text/plain;q=0.5, */*;q=0.1", ...conditional },
             });
+            if (response.status === 304 && Object.keys(conditional).length) {
+                await response.body?.cancel();
+                return "unchanged";
+            }
             const location = response.headers.get("location");
             if (response.status >= 300 && response.status < 400 && location) {
                 await response.body?.cancel();
@@ -95,7 +110,11 @@ export const fetchFeed = async (address, options) => {
                     retryable: response.status >= 500 || response.status === 429,
                 });
             }
-            return await readBody(response, name, limits.maxBytes);
+            const text = await readBody(response, name, limits.maxBytes);
+            return {
+                text,
+                validators: { etag: response.headers.get("etag"), lastModified: response.headers.get("last-modified") },
+            };
         }
     }
     catch (error) {
@@ -213,6 +232,19 @@ export const readFeed = (text, zone, window) => {
         skipped,
     };
 };
+const lastRead = (token, window) => {
+    if (token === null)
+        return null;
+    try {
+        const held = JSON.parse(token);
+        if (held?.v !== 1 || held.window?.from !== window.from || held.window.to !== window.to || !held.validators)
+            return null;
+        return held;
+    }
+    catch {
+        return null;
+    }
+};
 const calendarOf = (feed, timezone = null) => ({
     externalId: `${FEED_PREFIX}${feed.id}`,
     title: feed.title,
@@ -236,8 +268,9 @@ export const icsFeeds = (options) => {
             });
         return feed;
     };
-    const read = (url, name) => fetchFeed(url, {
+    const read = (url, name, since) => fetchFeedIfChanged(url, {
         name,
+        ...(since ? { since } : {}),
         ...(options.fetch ? { fetch: options.fetch } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.limits ? { limits: options.limits } : {}),
@@ -248,9 +281,16 @@ export const icsFeeds = (options) => {
         async calendars() {
             return (await options.registry.read()).map((feed) => calendarOf(feed));
         },
-        async changes(calendar, { window }) {
+        async changes(calendar, { cursor, window }) {
             const feed = await feedOf(calendar.externalId);
-            const text = await read(feed.url, `feed ${calendar.id}`);
+            const held = lastRead(cursor, window);
+            const got = await read(feed.url, `feed ${calendar.id}`, held?.validators);
+            if (got === "unchanged") {
+                const [events, skipped] = [held?.events ?? 0, held?.skipped ?? 0];
+                stats.set(calendar.id, { calendarId: calendar.id, events, skipped, unchanged: true });
+                return { entries: [], removed: [], cursor, unchanged: true };
+            }
+            const { text, validators } = got;
             const found = readFeed(text, calendar.timezone ?? options.zone, window);
             for (const entry of found.entries) {
                 const changed = found.overrides.get(entry.externalId);
@@ -258,7 +298,10 @@ export const icsFeeds = (options) => {
                     overridesOf.set(entry, changed);
             }
             stats.set(calendar.id, { calendarId: calendar.id, events: found.events, skipped: found.skipped });
-            return { entries: found.entries, removed: [], cursor: null };
+            const next = validators.etag || validators.lastModified
+                ? { v: 1, validators, window, events: found.events, skipped: found.skipped }
+                : null;
+            return { entries: found.entries, removed: [], cursor: next && JSON.stringify(next) };
         },
     };
     return {
@@ -271,7 +314,7 @@ export const icsFeeds = (options) => {
                 throw new CliError("validation_error", "this profile follows a feed at this address already", {
                     reason: "feed.duplicate",
                 });
-            const found = readFeed(await read(address, "the feed"), options.zone);
+            const found = readFeed((await read(address, "the feed")).text, options.zone);
             const feed = {
                 id: randomBytes(6).toString("hex"),
                 url: address,

package/dist/calendar/source.d.ts

@@ -13,7 +13,10 @@ export interface CalendarSourceTraits {
     expands: "on-request" | "in-changes" | "local";
     /** The cursor encodes the window (Graph delta): a new window means a new full round. */
     cursorHoldsWindow: boolean;
-    /** No incremental cursor: every run is a full list (an ICS feed). */
+    /**
+     * No incremental cursor: every run is a full list (an ICS feed). The token the last list gave still reaches
+     * `changes()`, so the source can ask whether anything changed since.
+     */
     fullListOnly: boolean;
 }
 export interface ChangePage {
@@ -27,6 +30,11 @@ export interface ChangePage {
     nextPage?: string;
     /** On the last page: the cursor for the next run; `null` when the source has none. */
     cursor?: string | null;
+    /**
+     * A full-list source's list is the one its token was given with (an ICS feed's 304): nothing was read, so nothing
+     * is saved and nothing stored is marked unseen. Only on a single page with no entries.
+     */
+    unchanged?: true;
 }
 /** `reset`: the cursor is dead (Google 410, Graph `syncStateNotFound`, CalDAV `valid-sync-token`). */
 export type ChangeResult = ChangePage | {
@@ -61,7 +69,7 @@ export interface CalendarSource {
     readonly provider: string;
     readonly traits: CalendarSourceTraits;
     calendars(): Promise<CalendarInput[]>;
-    /** `cursor: null` asks for a full list of the window. */
+    /** `cursor: null` asks for a full list of the window; a `fullListOnly` source lists in full whatever it is given. */
     changes(calendar: StoredCalendar, request: {
         cursor: string | null;
         page?: string;

package/dist/calendar/sync.d.ts

@@ -23,6 +23,8 @@ export interface PendingRound {
     series: string[];
     /** A full round asks every series it lists; otherwise only those that changed. Absent reads as true. */
     everySeries?: boolean;
+    /** The source said its list is unchanged since `from`: the round marks nothing unseen. */
+    unchanged?: true;
 }
 /** What the engine keeps in `EventStore.cursor`. Version 1 had no `round`, `updatedAt` or `done`. */
 export interface CalendarCursor {

package/dist/calendar/sync.js

@@ -29,7 +29,7 @@ const roundOf = (value) => {
         round.series.some((id) => typeof id !== "string") ||
         (round.everySeries !== undefined && typeof round.everySeries !== "boolean"))
         return undefined;
-    const { full, from, window, startedAt, reset, page, listed, next, series, everySeries } = round;
+    const { full, from, window, startedAt, reset, page, listed, next, series, everySeries, unchanged } = round;
     return {
         full,
         from,
@@ -41,6 +41,7 @@ const roundOf = (value) => {
         next,
         series,
         ...(everySeries === false ? { everySeries } : {}),
+        ...(unchanged === true ? { unchanged } : {}),
     };
 };
 export const parseCalendarCursor = (value) => {
@@ -87,9 +88,9 @@ export const calendarSyncWindow = (now) => {
     return { from: Date.UTC(year - 1, month, date), to: Date.UTC(year, month + 3, date) };
 };
 const CONTINUE = "run sync again to continue";
-const freshRound = (full, from, window, now, reset = false, everySeries = true) => ({
+const freshRound = (full, from, window, now, reset = false, everySeries = true, keepToken = false) => ({
     full,
-    from: full ? null : from,
+    from: full && !keepToken ? null : from,
     window,
     startedAt: now,
     reset,
@@ -112,7 +113,7 @@ const roundFor = (source, stored, { window, now }) => {
     // The daily full round asks only the series that changed, and every series once the window's end moved on far
     // enough that their new slots matter (foundation §6.2 step 7).
     const everySeries = !full || stored?.slotsTo === undefined || window.to - stored.slotsTo >= SLOTS_EVERY;
-    return freshRound(full, stored?.token ?? null, window, now, false, everySeries);
+    return freshRound(full, stored?.token ?? null, window, now, false, everySeries, source.traits.fullListOnly);
 };
 const deadList = (provider) => new CliError("invalid_response", `${provider} refused a full list as a dead cursor`);
 /**
@@ -218,7 +219,9 @@ const syncOne = async ({ source, store, calendar, window, now, expand, budget, s
         }
         if (page.removed.length)
             result.removed += await store.removeEntries(calendar.id, page.removed, now);
-        if (page.nextPage === undefined)
+        if (page.unchanged && source.traits.fullListOnly && page.entries.length === 0 && page.nextPage === undefined)
+            round = { ...round, page: null, listed: true, next: page.cursor ?? null, unchanged: true };
+        else if (page.nextPage === undefined)
             round = { ...round, page: null, listed: true, next: page.cursor ?? null };
         else {
             if (seen.has(page.nextPage))
@@ -260,7 +263,8 @@ const syncOne = async ({ source, store, calendar, window, now, expand, budget, s
     }
     if (signal?.aborted)
         return "cancelled";
-    result.unseen = round.full ? await store.markUnseen(calendar.id, round.startedAt, round.window, now) : 0;
+    result.unseen =
+        round.full && !round.unchanged ? await store.markUnseen(calendar.id, round.startedAt, round.window, now) : 0;
     await save({
         token: round.next,
         window: round.window,

package/dist/calendar/testing/memory.js

@@ -343,6 +343,45 @@ export const memoryEventStore = () => {
         async setCalendarSynced(calendarId, synced) {
             calendarOf(calendarId).synced = synced;
         },
+        async forgetCalendar(calendarId, now) {
+            const calendar = calendarOf(calendarId);
+            const mine = entries.filter((one) => one.calendarId === calendarId);
+            const ids = new Set(mine.map(({ id }) => id));
+            const eventIds = new Set(mine.flatMap(({ eventId }) => (eventId === null ? [] : [eventId])));
+            const seriesIds = new Set(mine.flatMap(({ eventSeriesId }) => (eventSeriesId === null ? [] : [eventSeriesId])));
+            for (let at = entries.length - 1; at >= 0; at--)
+                if (ids.has(entries[at].id))
+                    entries.splice(at, 1);
+            for (let at = revisions.length - 1; at >= 0; at--)
+                if (ids.has(revisions[at].entryId))
+                    revisions.splice(at, 1);
+            for (let at = reviews.length - 1; at >= 0; at--)
+                if (reviews[at].linkableType === "calendar_entry" &&
+                    ids.has(reviews[at].linkableId))
+                    reviews.splice(at, 1);
+            participants = participants.filter((one) => !ids.has(one.entryId));
+            attachments = attachments.filter((one) => !ids.has(one.entryId));
+            for (const id of ids)
+                unlinked.delete(id);
+            let gone = 0;
+            for (const id of eventIds)
+                if (entries.some((one) => one.eventId === id))
+                    refreshEvent(id, now);
+                else if (events.delete(id))
+                    gone++;
+            for (const id of seriesIds)
+                if (entries.some((one) => one.eventSeriesId === id))
+                    refreshSeries(id);
+                else {
+                    series.delete(id);
+                    for (const event of events.values())
+                        if (event.eventSeriesId === id)
+                            event.eventSeriesId = null;
+                }
+            cursors.delete(calendarId);
+            calendars.splice(calendars.indexOf(calendar), 1);
+            return { entries: ids.size, events: gone };
+        },
         async saveEntries(calendarId, list, now) {
             calendarOf(calendarId);
             for (const input of list)

package/dist/cli/answer-entity.d.ts

@@ -1,8 +1,12 @@
 import type { Command } from "commander";
 import type * as v from "valibot";
+import type { RowShape } from "./compact.js";
 /** Provider-specific wire fields must not redefine an entity shared by every CLI. */
 export declare const answerEntity: (command: Command, name: string, schema: v.GenericSchema, options?: {
     project?: v.GenericSchema;
+    row?: RowShape;
 }) => Command;
 export declare const answerEntitySchema: (command: Command | undefined) => v.GenericSchema | undefined;
 export declare const answerProjectionSchema: (command: Command | undefined) => v.GenericSchema | undefined;
+/** The row a command declared with `answerEntity(…, { row })`, while it still answers that entity. */
+export declare const answerRow: (command: Command | undefined) => RowShape | undefined;

package/dist/cli/answer-entity.js

@@ -29,3 +29,8 @@ export const answerProjectionSchema = (command) => {
     const own = command && schemas.get(command);
     return own && metaOf(command).output?.entity === own.name ? own.project : undefined;
 };
+/** The row a command declared with `answerEntity(…, { row })`, while it still answers that entity. */
+export const answerRow = (command) => {
+    const own = command && schemas.get(command);
+    return own && metaOf(command).output?.entity === own.name ? own.row : undefined;
+};

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

@@ -15,6 +15,8 @@ export declare const botContext: (command: Command, bot: BotMessenger) => {
     format: import("@wirecat/cli-base").RenderFormat;
     color: boolean;
     streams: import("@wirecat/cli-base").Streams;
+    compact?: boolean;
+    full?: boolean;
     env: NodeJS.ProcessEnv;
     keyring?: import("@wirecat/cli-base").KeyringStore;
     run: <T>(body: (events: import("../index.js").EventSink) => Promise<T>, options?: {

package/dist/cli/compact.d.ts

@@ -0,0 +1,41 @@
+import type { Command } from "commander";
+import type { Body } from "./envelope.js";
+/** How one column prints. `text` by default. */
+export type RowValue = "text" | "time" | "day" | "count" | "files" | "reply" | "forward";
+export interface RowColumn {
+    /** A snake_case field path in the item (`sender_name`, `last.timestamp`); of several, the first that is set. */
+    field: string | readonly string[];
+    as?: RowValue;
+    /** Printed for a field that is `true`, and after a count: `{ field: ["sender_is_me", "sender_name"], tag: "me" }`. */
+    tag?: string;
+}
+export interface RowShape {
+    /** Printed in order, joined by " · "; the first is the ref. A missing value is left out. */
+    columns: readonly RowColumn[];
+    /** The free text, printed last; the first non-empty field wins. */
+    text?: readonly string[];
+    /** An item answer's lists, drawn as rows of another entity: `{ items: "evidence_item" }`. */
+    sections?: Readonly<Record<string, string>>;
+}
+export interface CompactOptions {
+    /** IANA zone for times; the answer's `meta.timezone` wins. */
+    timezone: string;
+    /** Characters of text kept per row; 0 keeps all (`--full`). Default 400. */
+    textChars?: number;
+}
+export declare const TEXT_CHARS = 400;
+/** Rows for cli-core's shared entities. */
+export declare const SHARED_ROWS: Readonly<Record<string, RowShape>>;
+/** Any record: what names it, what it is called, what state it is in, then what it says. */
+export declare const GENERIC_ROW: RowShape;
+export type RowsResolver = (command: Command | undefined) => RowShape | undefined;
+/** An app's own rows by entity name (or `name.view`). */
+export type RowTable = Readonly<Record<string, RowShape>>;
+/** The row an entity named in a section is drawn with: the app's, the shared one, else the generic one. */
+export declare const rowsOfEntity: (table?: RowTable) => (entity: string) => RowShape;
+/** An app's own rows by entity name, as `entityFields` takes its fields; a shared name is refused. */
+export declare const entityRows: (table: RowTable) => RowsResolver;
+/** The row a command's answer is drawn with: its own, its app's, the shared one, else the generic one. */
+export declare const rowShapeOf: (command: Command | undefined, resolve?: RowsResolver) => RowShape;
+/** The whole answer as compact text: header, rows, footer. Pure: no store, no clock. */
+export declare const compactText: <T>(body: Body<T>, shape: RowShape, options: CompactOptions, rowsOf?: (entity: string) => RowShape) => string;

package/dist/cli/compact.js

@@ -0,0 +1,313 @@
+import { visibleControls } from "@wirecat/cli-base";
+import { metaOf } from "@wirecat/cli-base/commands";
+import { ENTITIES } from "../entities/index.js";
+import { answerRow } from "./answer-entity.js";
+export const TEXT_CHARS = 400;
+const sender = { field: ["sender_is_me", "sender_name"], tag: "me" };
+const messageRow = {
+    columns: [
+        { field: "ref" },
+        { field: "timestamp", as: "time" },
+        { field: "chat_title" },
+        sender,
+        { field: ["reply_to_id", "reply_to.id"], as: "reply" },
+        { field: "forwarded_from", as: "forward" },
+        { field: "attachments", as: "files" },
+    ],
+    text: ["text", "transcript", "excerpt"],
+};
+/** Rows for cli-core's shared entities. */
+export const SHARED_ROWS = {
+    message: messageRow,
+    "message.summary": messageRow,
+    "message.hit": {
+        columns: [
+            { field: "ref" },
+            { field: "timestamp", as: "time" },
+            { field: "chat_title" },
+            sender,
+            { field: "attachments", as: "files" },
+        ],
+        text: ["excerpt", "text"],
+    },
+    chat: {
+        columns: [
+            { field: "ref" },
+            { field: "title" },
+            { field: "kind" },
+            { field: "unread_count", as: "count", tag: "unread" },
+            { field: "last_message_at", as: "time" },
+        ],
+    },
+};
+/** Any record: what names it, what it is called, what state it is in, then what it says. */
+export const GENERIC_ROW = {
+    columns: [
+        { field: ["key", "ref", "id"] },
+        { field: ["title", "name", "path"] },
+        { field: ["state", "status", "due_at"] },
+    ],
+    text: ["text", "excerpt"],
+};
+/** The row an entity named in a section is drawn with: the app's, the shared one, else the generic one. */
+export const rowsOfEntity = (table = {}) => (entity) => (Object.hasOwn(table, entity) ? table[entity] : undefined) ?? SHARED_ROWS[entity] ?? GENERIC_ROW;
+const declaredNames = (command) => {
+    const output = command ? metaOf(command).output : undefined;
+    if (!output)
+        return [];
+    return output.view ? [`${output.entity}.${output.view}`, output.entity] : [output.entity];
+};
+/** An app's own rows by entity name, as `entityFields` takes its fields; a shared name is refused. */
+export const entityRows = (table) => {
+    const shared = Object.keys(table).filter((name) => name in ENTITIES || name in SHARED_ROWS);
+    if (shared.length > 0)
+        throw new Error(`entityRows: ${shared.join(", ")} is cli-core's entity; name yours apart`);
+    return (command) => {
+        const name = declaredNames(command).find((one) => Object.hasOwn(table, one));
+        return name === undefined ? undefined : table[name];
+    };
+};
+/** The row a command's answer is drawn with: its own, its app's, the shared one, else the generic one. */
+export const rowShapeOf = (command, resolve) => {
+    const own = answerRow(command) ?? resolve?.(command);
+    if (own)
+        return own;
+    const shared = declaredNames(command).find((name) => Object.hasOwn(SHARED_ROWS, name));
+    return shared === undefined ? GENERIC_ROW : SHARED_ROWS[shared];
+};
+const isFields = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const present = (value) => value !== null && value !== undefined && value !== "" && value !== false && !(Array.isArray(value) && !value.length);
+const at = (item, path) => path.split(".").reduce((value, key) => (isFields(value) ? value[key] : undefined), item);
+const fieldsOfColumn = (field) => (typeof field === "string" ? [field] : field);
+// A record or a list is not one value; a file list is the only column that reads one, by its own path.
+const printable = (value, column) => present(value) &&
+    (column?.as === "files" || column?.as === "forward" || column?.as === "reply" || !isListOrRecord(value));
+const isListOrRecord = (value) => typeof value === "object" && value !== null;
+const firstSet = (item, field, column) => fieldsOfColumn(field)
+    .map((path) => at(item, path))
+    .find((value) => printable(value, column));
+const sourceOf = (item, column) => fieldsOfColumn(column.field).find((path) => printable(at(item, path), column));
+// Whitespace runs become one space and control or direction characters show, so a text cannot start a row of its own.
+const clean = (text) => visibleControls(text.replace(/\s+/g, " ").trim());
+const cut = (text, chars) => {
+    if (chars <= 0)
+        return text;
+    const letters = Array.from(text);
+    return letters.length <= chars ? text : `${letters.slice(0, chars).join("")}…(+${letters.length - chars})`;
+};
+const clockFor = (zone) => {
+    const format = new Intl.DateTimeFormat("en-CA", {
+        timeZone: zone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    });
+    return {
+        zone,
+        parts: (iso) => {
+            const ms = Date.parse(iso);
+            if (Number.isNaN(ms))
+                return undefined;
+            const part = Object.fromEntries(format.formatToParts(ms).map(({ type, value }) => [type, value]));
+            return { date: `${part.year}-${part.month}-${part.day}`, time: `${part.hour}:${part.minute}` };
+        },
+    };
+};
+const duration = (seconds) => {
+    const whole = Math.round(seconds);
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+};
+const fileTag = (file) => {
+    if (!isFields(file))
+        return undefined;
+    const kind = typeof file.kind === "string" && file.kind !== "" ? file.kind : "file";
+    const extra = typeof file.duration === "number" ? duration(file.duration) : typeof file.name === "string" ? file.name : "";
+    return `[${clean(extra ? `${kind} ${extra}` : kind)}]`;
+};
+const cellOf = (item, column, clock) => {
+    const value = firstSet(item, column.field, column);
+    if (!present(value))
+        return undefined;
+    switch (column.as) {
+        case "time":
+        case "day": {
+            if (typeof value !== "string")
+                return undefined;
+            const parts = clock.parts(value);
+            if (!parts)
+                return { text: clean(value) };
+            const day = parts.date.slice(5);
+            return { text: column.as === "day" ? day : `${day} ${parts.time}`, date: parts.date };
+        }
+        case "count":
+            return typeof value === "number" && value !== 0
+                ? { text: column.tag ? `${value} ${column.tag}` : String(value) }
+                : undefined;
+        case "files": {
+            const tags = (Array.isArray(value) ? value : [value]).map(fileTag).filter((tag) => tag !== undefined);
+            return tags.length ? { text: tags.join(" ") } : undefined;
+        }
+        case "reply": {
+            const id = isFields(value) ? value.id : value;
+            return typeof id === "string" || typeof id === "number" ? { text: `↳#${clean(String(id))}` } : undefined;
+        }
+        case "forward": {
+            const name = isFields(value) ? value.sender_name : value;
+            return { text: typeof name === "string" && name !== "" ? `↪ ${clean(name)}` : "↪" };
+        }
+        default:
+            if (value === true)
+                return column.tag ? { text: column.tag } : undefined;
+            if (typeof value === "string" || typeof value === "number")
+                return { text: clean(String(value)) };
+            return undefined;
+    }
+};
+const textOf = (item, shape, chars) => {
+    const value = (shape.text ?? [])
+        .map((field) => at(item, field))
+        .find((one) => typeof one === "string" && present(one));
+    return typeof value === "string" ? cut(clean(value), chars) : undefined;
+};
+// A line that starts with "# " is the answer's own; a row is shifted so that no item can pass for one.
+const guarded = (line) => (line.startsWith("#") && !/^#[^\s#]/.test(line) ? `\\${line}` : line);
+const REF = /^[a-z]+:\S*\/[^/\s]+$/;
+/** The shared part of the refs up to their last `/`, when every row has one and there is more than one row. */
+const sharedPrefix = (refs) => {
+    if (refs.length < 2 || !refs.every((ref) => ref !== undefined && REF.test(ref)))
+        return undefined;
+    const prefixes = new Set(refs.map((ref) => ref.slice(0, ref.lastIndexOf("/") + 1)));
+    return prefixes.size === 1 ? [...prefixes][0] : undefined;
+};
+const span = (dates) => {
+    if (!dates.length)
+        return undefined;
+    const sorted = [...dates].sort();
+    const first = sorted[0];
+    const last = sorted[sorted.length - 1];
+    return first === last ? first : `${first}…${last}`;
+};
+// A column every row prints the same, a chat's title in a list of its messages, is said once in the header.
+const sameEverywhere = (rows, index) => {
+    const first = rows[0]?.cells[index]?.text;
+    return first !== undefined && rows.every(({ cells }) => cells[index]?.text === first);
+};
+const rowsOfItems = (items, shape, clock, chars) => {
+    const dates = [];
+    const rows = items.map((item) => {
+        if (!isFields(item))
+            return { cells: [], text: clean(String(item)) };
+        const cells = shape.columns.map((column) => cellOf(item, column, clock));
+        for (const cell of cells)
+            if (cell?.date)
+                dates.push(cell.date);
+        return { cells, text: textOf(item, shape, chars), item };
+    });
+    const firstColumn = shape.columns[0];
+    const refs = rows.map(({ item }) => item && firstColumn ? firstSet(item, firstColumn.field) : undefined);
+    const prefix = sharedPrefix(refs.map((ref) => (typeof ref === "string" ? ref : undefined)));
+    const hoisted = rows.length < 2 ? [] : shape.columns.map((_, index) => index > 0 && sameEverywhere(rows, index));
+    const named = hoisted.flatMap((hoist, index) => {
+        const column = shape.columns[index];
+        const item = rows[0]?.item;
+        if (!hoist || !column || !item)
+            return [];
+        return [`${sourceOf(item, column) ?? fieldsOfColumn(column.field)[0]}: ${rows[0]?.cells[index]?.text}`];
+    });
+    const lines = rows.map(({ cells, text, item }) => {
+        const parts = cells.map((cell, index) => (hoisted[index] ? undefined : cell?.text));
+        const shortened = prefix ? clean(prefix) : undefined;
+        if (shortened && parts[0]?.startsWith(shortened))
+            parts[0] = `#${parts[0].slice(shortened.length)}`;
+        const shown = [...parts, text].filter((part) => part !== undefined && part !== "");
+        return guarded(shown.length ? shown.join(" · ") : item ? blockLine(item, chars) : "");
+    });
+    const when = span(dates);
+    const header = [...(prefix ? [`ref: ${clean(prefix)}<id>`] : []), ...named, ...(when ? [when, clock.zone] : [])];
+    return { header, lines };
+};
+const blockLine = (fields, chars) => blockOf(fields, chars).join("  ");
+/** A record as `field: value` lines; a nested record is indented under its field, a list of records counted. */
+const blockOf = (fields, chars, indent = "") => Object.entries(fields)
+    .filter(([name]) => !(name === "priority" && "priority_label" in fields))
+    .filter(([, value]) => present(value) || value === false)
+    .flatMap(([name, value]) => {
+    const label = `${indent}${clean(name)}:`;
+    if (isFields(value))
+        return [label, ...blockOf(value, chars, `${indent}  `)];
+    if (Array.isArray(value))
+        return value.every((one) => !isFields(one) && !Array.isArray(one))
+            ? [`${label} ${cut(clean(value.join(", ")), chars)}`]
+            : [`${label} ${value.length} — --json shows them`];
+    return [`${label} ${cut(clean(String(value)), chars)}`];
+});
+const footerOf = (body) => {
+    const lines = [];
+    const steps = body.next ?? [];
+    const lineOf = (step) => (step.kind === "command" ? (step.line ?? step.command) : undefined);
+    if ("items" in body && body.page.has_more) {
+        const more = steps.find((step) => step.step === "page.next");
+        const line = more?.kind === "command" ? more.line : undefined;
+        const page = body.page;
+        lines.push(`# more: ${clean(line ??
+            (page.mode === "cursor" && page.next_cursor
+                ? `--cursor ${page.next_cursor}`
+                : page.mode === "page" && page.next_page
+                    ? `--page ${page.next_page}`
+                    : "raise --limit"))}`);
+    }
+    for (const missing of body.missing ?? [])
+        lines.push(`# missing: ${clean(missing.field)}: ${clean(missing.why)}`);
+    for (const step of steps) {
+        if (step.step === "page.next" && "items" in body)
+            continue;
+        const line = lineOf(step);
+        lines.push(`# next: ${clean(step.why)}${line ? `: ${clean(line)}` : ""}`);
+    }
+    if (body.meta?.complete === false) {
+        const issues = (body.meta.issues ?? []).map((issue) => `${clean(issue.source)}: ${clean(String(issue.code))}`);
+        lines.push(`# complete: false${issues.length ? ` (${issues.join(", ")})` : ""}`);
+    }
+    if (body.meta?.truncated)
+        lines.push("# truncated: true");
+    return lines;
+};
+const usableZone = (zone) => {
+    if (!zone)
+        return undefined;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: zone });
+        return zone;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The whole answer as compact text: header, rows, footer. Pure: no store, no clock. */
+export const compactText = (body, shape, options, rowsOf = rowsOfEntity()) => {
+    const clock = clockFor(usableZone(body.meta?.timezone) ?? usableZone(options.timezone) ?? "UTC");
+    const chars = options.textChars ?? TEXT_CHARS;
+    let lines = [];
+    if ("items" in body) {
+        const { header, lines: rows } = rowsOfItems(body.items, shape, clock, chars);
+        lines = (header.length ? [`# ${header.join(" · ")}`] : []).concat(rows.length ? rows : ["# nothing found"]);
+    }
+    else if (isFields(body.item)) {
+        const sections = shape.sections ?? {};
+        const rest = Object.fromEntries(Object.entries(body.item).filter(([name]) => !Object.hasOwn(sections, name)));
+        lines = blockOf(rest, chars).map(guarded);
+        for (const [name, entity] of Object.entries(sections)) {
+            const list = body.item[name];
+            if (!Array.isArray(list))
+                continue;
+            const { header, lines: rows } = rowsOfItems(list, rowsOf(entity), clock, chars);
+            lines = lines.concat([`# ${[`${clean(name)}: ${list.length}`, ...header].join(" · ")}`], rows);
+        }
+    }
+    else if (present(body.item))
+        lines = [guarded(cut(clean(String(body.item)), chars))];
+    return lines.concat(footerOf(body)).join("\n");
+};