@wirecat/cli-core 0.381.0 → 0.383.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ shape of this file.
 
 ## Unreleased
 
+## 0.383.0 — 22.10.2026
+
+### Added
+
+- **`readSpreadsheet(bytes, "xlsx" | "ods")` from `@wirecat/cli-core/documents`** returns a workbook's cells per
+  worksheet (values as displayed), the same reader text extraction uses, so a provider can mirror a workbook's tabs.
+- **Push local files into a provider as native documents (`@wirecat/cli-core/documents`).** `pushDocuments` mirrors
+  a local folder one way through a provider's `DocumentTarget`: new files are created, changed files updated, and
+  unchanged files skipped by content hash with no remote call. Before a create it saves a pending origin key, so a
+  crash after the provider wrote finds the file (`findByOrigin`) instead of creating a duplicate. The provider's
+  `prepare` compares the remote with the last push before writing; a remote copy changed since then is a conflict
+  unless `force`, and only the `write` step passes the guard. A local delete is reported as an
+  orphan and nothing is ever deleted remotely. `planPush` is the pure plan behind `dryRun`; `scanLocal` skips hidden
+  files, editor leftovers and symbolic links. Every write passes through the caller's `guard` with its own operation
+  id. For documents with structure, `markdownBlocks` (async, its parser loaded on first use) parses Markdown (CommonMark and GFM tables, task lists,
+  strikethrough) into `Block`s a provider writes natively, `diffBlocks` gives the edits that leave unchanged blocks
+  in place, and `reconcileBlocks` lets a checklist tick change on either side without a conflict. See
+  [documents](docs/dev/DOCUMENTS.md#push-local-files-to-a-provider).
+
+## 0.382.0 — 22.10.2026
+
+### Added
+
+- **A chat's state from the phone (store version 28).** The store keeps `Chat.muted`, `Chat.archived` and two new
+  fields: `mutedUntil` (when a mute ends, UTC; none is for good) and `markedUnread` (the owner marked the chat unread).
+  A `ChatUpdate` that leaves one out keeps the stored value, and a mute past its end reads as over. Stored chats show
+  them, and `chat` gains `muted_until` and `marked_unread`. So `inbox` and `review` over the store now leave out muted
+  and archived chats, as they do for a messenger that answers live, and `inbox` takes in a chat marked unread with its
+  newest message from someone else. tg and max send `muted` and `archived` in their chat lists, so their stored chats
+  now show them too.
+- **The store can count unread messages** for a messenger that sets `unreadCounts: "store"`: each new message from
+  someone else that `watch` or `listen` saves after the messenger's last count adds one, and a whole-chat `chats read`
+  stores 0. `store.messages.saveMessages` takes `countUnread`. tg and max leave it unset and count as before. See
+  [adapters](docs/dev/ADAPTERS.md).
+- **Delivered and read on the owner's own messages (store version 27).** `Message.delivery` (`delivered` or `read`)
+  says how far the owner's message in a one-to-one chat got; a `watch` event `{ event: "delivery", chatId, chatTitle,
+  messageId, delivery, at }` (`MessageDeliveryEvent`) carries a receipt as it comes. `store.messages.saveDelivery` and
+  a saved message's own `delivery` keep it in the new `messages.delivery` column, only on the owner's messages and
+  only ever forward. Stored messages show it as `delivery`. tg and max send none and see no change. See
+  [adapters](docs/dev/ADAPTERS.md).
+
 ## 0.381.0 — 22.10.2026
 
 ### Added
@@ -14,6 +55,10 @@ shape of this file.
 - **Meeting search finds words speech recognition cut off.** A stored word of four letters or more that begins a
   query word, and that the Russian dictionary does not know, widens it: «може» for «может», «напри» for «например».
   Real shorter words («после» for «последующих») still do not. This is ztx's rule, behind the dictionary.
+- **A meeting answer names what about it is doubtful, in `issues`.** `MEETING_ISSUES` lists the values; today one,
+  `time_without_zone`: the provider sent a time with no zone, and it was read in the computer's zone. A provider
+  adapter keeps the data and puts the issue in the meeting's `metadata.issues`; `meetingItem` shows the known ones and
+  leaves the field out when there are none. No store change.
 
 - **People's reactions in the store (store version 26).** For a messenger that sends one person's reaction change at a
   time (WhatsApp), a `watch` event `{ event: "person_reaction", chatId, chatTitle, messageId, reaction }`
@@ -30,6 +75,11 @@ shape of this file.
   (U+FE0F, U+FE0E, or the U+200D joiner) that a typed one lacks, so "Семья❤️" did not find the chat "Семья❤". Names
   now compare without those marks and with accented letters in one form, still ignoring case, wherever a chat or a
   person is named (`pickChat`, `pickPerson`, a stored alias).
+- **`from:` finds a speaker known only by name across meetings.** A participant keyed by name in one meeting
+  (`name:…@account/occurrence:n`, as zoom-cli's `.txt` speakers and nameless API participants are) is grouped with
+  the same name elsewhere, and with the one identified speaker of that name when there is exactly one. Before,
+  each meeting's copy was a separate candidate, so `from:"Name"` was ambiguous. Candidates with an email show it.
+
 - **A store the process may not write is a permission error, not a crash.** Opening the store for writing where the
   file or its folder is read-only (`EROFS`, `EACCES`, `EPERM`) was reported as `internal_error` "this is a bug".
   It is now `permission_error` (exit 5) with reason `store.not-writable`, and the message names no path.

package/dist/attachments/documents.d.ts

@@ -1,6 +1,9 @@
 import type { Extraction, FileHint } from "../readers/types.js";
+import { type Sheet } from "./sheets.js";
 export type DocumentKind = "odt" | "ods" | "odp" | "xlsx" | "pptx" | "epub";
 export declare const documentKind: (hint: FileHint) => DocumentKind | undefined;
 /** v2 for spreadsheets: rows under their header instead of one line per cell, so older text is read again. */
 export declare const documentExtractor: (kind: DocumentKind) => string;
+/** The cells of an XLSX or ODS workbook, one `Sheet` per worksheet in workbook order, values as displayed. */
+export declare const readSpreadsheet: (bytes: Uint8Array, kind: "xlsx" | "ods", signal?: AbortSignal) => Promise<Sheet[]>;
 export declare const readDocument: (bytes: Uint8Array, kind: DocumentKind, signal?: AbortSignal) => Promise<Extraction>;

package/dist/attachments/documents.js

@@ -393,6 +393,23 @@ const readBook = (archive, output) => {
         visit(bodies[0]);
     }
 };
+/** The cells of an XLSX or ODS workbook, one `Sheet` per worksheet in workbook order, values as displayed. */
+export const readSpreadsheet = async (bytes, kind, signal) => {
+    try {
+        const archive = await readContainer(bytes, signal);
+        const sheets = kind === "xlsx" ? readSheet(archive) : readOdf(archive, kind, new Output());
+        if (!sheets)
+            throw new Error("wrong_format");
+        return sheets;
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("validation_error", `the ${kind.toUpperCase()} workbook could not be read`, {
+            reason: "spreadsheet.unreadable",
+        });
+    }
+};
 export const readDocument = async (bytes, kind, signal) => {
     const extractor = documentExtractor(kind);
     try {

package/dist/cli/bot/watch.js

@@ -140,6 +140,9 @@ export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects
         else if (event.event === "star") {
             context.streams.data(`${event.starred ? "starred" : "unstarred"} in ${title(event.chatId)}: message ${event.messageId}\n`);
         }
+        else if (event.event === "delivery") {
+            context.streams.data(`${event.delivery} in ${title(event.chatId)}: message ${event.messageId}\n`);
+        }
         else if (event.event === "chat_event") {
             context.streams.data(`${event.change.event} in ${title(event.chatId)}\n`);
         }

package/dist/cli/messenger/chat-answers.d.ts

@@ -61,7 +61,9 @@ export declare const chatShown: (account: AccountKey, card: Parameters<typeof ch
     last_message_at: string | null;
     participants_count: number | null;
     muted?: boolean | undefined;
+    muted_until?: string | undefined;
     archived?: boolean | undefined;
+    marked_unread?: boolean | undefined;
     membership_state?: "archived" | "external" | "imported" | "joined" | "left" | "public" | undefined;
     parent_chat_id?: string | undefined;
     scope?: "personal" | "work" | undefined;

package/dist/cli/messenger/chat-answers.js

@@ -28,7 +28,9 @@ export const chatAnswer = (account, chat) => defined({
     last_message_at: chat.lastMessageAt,
     participants_count: chat.participantsCount,
     muted: chat.muted,
+    muted_until: chat.mutedUntil ?? undefined,
     archived: chat.archived,
+    marked_unread: chat.markedUnread,
     membership_state: chat.membershipState,
     parent_chat_id: chat.parentChatId ?? undefined,
     scope: chat.scope,

package/dist/cli/messenger/chat-lists.d.ts

@@ -21,7 +21,9 @@ export declare const chatsList: (services: Services, query: QueryWords, paging:
     last_message_at: string | null;
     participants_count: number | null;
     muted?: boolean | undefined;
+    muted_until?: string | undefined;
     archived?: boolean | undefined;
+    marked_unread?: boolean | undefined;
     membership_state?: "archived" | "external" | "imported" | "joined" | "left" | "public" | undefined;
     parent_chat_id?: string | undefined;
     scope?: "personal" | "work" | undefined;

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

@@ -236,12 +236,12 @@ type ConnectionWaits = Pick<BaseEnvironment, "closeWaitMs" | "rekeyPacing">;
  * does not `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again.
  * A connection opened with `listen: true` is left to its `watch` and `feed`, which save the same.
  */
-export declare const connected: (connection: MessengerAdapter, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, }: Pick<Messenger, "app" | "provider" | "name" | "deletedWithoutChat" | "pace" | "history" | "savedChatId">, { settings, env, renderer }: Pick<BaseContext, "settings" | "env" | "renderer">, events: EventSink, store?: LazyStore, { listen: watching, closeWaitMs, rekeyPacing, }?: Pick<ConnectOptions, "listen"> & ConnectionWaits) => {
+export declare const connected: (connection: MessengerAdapter, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, unreadCounts, }: Pick<Messenger, "app" | "provider" | "name" | "deletedWithoutChat" | "pace" | "history" | "savedChatId" | "unreadCounts">, { settings, env, renderer }: Pick<BaseContext, "settings" | "env" | "renderer">, events: EventSink, store?: LazyStore, { listen: watching, closeWaitMs, rekeyPacing, }?: Pick<ConnectOptions, "listen"> & ConnectionWaits) => {
     adapter: MessengerAdapter;
     close: () => Promise<void>;
 };
 /** `connectFor` and then `connected`, over one store handle: what the reads save and what the adapter looks up. */
-export declare const connectedFor: (command: Command, messenger: Pick<Messenger, "connect" | "app" | "provider" | "name" | "deletedWithoutChat" | "pace" | "history" | "savedChatId">, base: BaseContext, options: ConnectOptions & {
+export declare const connectedFor: (command: Command, messenger: Pick<Messenger, "connect" | "app" | "provider" | "name" | "deletedWithoutChat" | "pace" | "history" | "savedChatId" | "unreadCounts">, base: BaseContext, options: ConnectOptions & {
     events: EventSink;
 }) => Promise<{
     connection: MessengerAdapter;

package/dist/cli/messenger/context.js

@@ -189,7 +189,7 @@ const waitsOf = (command) => {
  * does not `watch` is open: what it queued while nothing was connected is delivered once and cannot be fetched again.
  * A connection opened with `listen: true` is left to its `watch` and `feed`, which save the same.
  */
-export const connected = (connection, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, }, { settings, env, renderer }, events, store = lazyStore(env, app.command), { listen: watching = false, closeWaitMs = SAVES_WAIT_MS, rekeyPacing, } = {}) => {
+export const connected = (connection, { app, provider, name, deletedWithoutChat, pace, history, savedChatId, unreadCounts, }, { settings, env, renderer }, events, store = lazyStore(env, app.command), { listen: watching = false, closeWaitMs = SAVES_WAIT_MS, rekeyPacing, } = {}) => {
     const self = connection.self();
     if (self !== null)
         rememberAccount(app, settings.profile, self, env);
@@ -220,6 +220,7 @@ export const connected = (connection, { app, provider, name, deletedWithoutChat,
             rekeyed: (from, to) => rekeyRecipients(app, settings.profile, env, renderer.warn, from, to),
             recipientIds: () => (new RecipientList(recipientsPathFor(app, settings.profile, env), app.command).read() ?? []).flatMap((recipient) => [recipient.id, ...(recipient.partnerId ? [recipient.partnerId] : [])]),
             ...(history === "store" ? { namesFromStore: savedChatId ? { savedChatId } : {} } : {}),
+            ...(unreadCounts === "store" ? { countsUnread: true } : {}),
         });
     const passives = history === "store" && self !== null && !watching
         ? passivesOf(saving).map((passive) => listened(passive, events, renderer.warn, closeWaitMs))

package/dist/cli/messenger/conversation-answers.d.ts

@@ -175,6 +175,7 @@ export declare const conversationShown: (account: AccountKey, { summary, message
         } | null | undefined;
         scheduled_for?: string | undefined;
         starred?: true | undefined;
+        delivery?: "delivered" | "read" | undefined;
         email?: {
             subject: string | null;
             from: {

package/dist/cli/messenger/message-answers.d.ts

@@ -152,6 +152,7 @@ export declare const threadAnswer: ({ items, ...thread }: ThreadContext, reader:
         } | null | undefined;
         scheduled_for?: string | undefined;
         starred?: true | undefined;
+        delivery?: "delivered" | "read" | undefined;
         email?: {
             subject: string | null;
             from: {

package/dist/cli/messenger/message-items.js

@@ -59,6 +59,7 @@ export const messageItem = (message, reader) => {
         reactions: message.reactions,
         scheduled_for: message.scheduledFor,
         starred: message.starred === true ? true : undefined,
+        delivery: message.delivery,
         email: message.email === undefined
             ? undefined
             : {

package/dist/cli/messenger/message-writes.d.ts

@@ -154,6 +154,7 @@ export declare const writtenAnswer: ({ operationId, sendId, message, scheduledFo
         } | null | undefined;
         scheduled_for?: string | undefined;
         starred?: true | undefined;
+        delivery?: "delivered" | "read" | undefined;
         email?: {
             subject: string | null;
             from: {

package/dist/cli/messenger/serve-relay.d.ts

@@ -32,6 +32,7 @@ export declare const serveRelay: (command: Command, messenger: Messenger) => {
         fetching?: import("../index.js").Fetching;
         history?: "server" | "store";
         historyOnDemand?: boolean;
+        unreadCounts?: "messenger" | "store";
         serverSearch?: boolean | "chat";
         services?: import("../../services/index.js").Override;
         connection?: "exclusive";

package/dist/cli/messenger/stored.d.ts

@@ -39,6 +39,8 @@ export interface Saving {
      * titles `watch` leaves out, are answered from the store first. Its server has no directory to ask.
      */
     namesFromStore?: Pick<MessengerTraits, "savedChatId">;
+    /** `MessengerTraits.unreadCounts: "store"`: a message `watch` or `listen` saves raises its chat's unread count. */
+    countsUnread?: boolean;
 }
 /**
  * The adapter, with what each read answers written to the store. **A failed write never fails the
@@ -48,4 +50,4 @@ export interface Saving {
  * would erase what `chats list` stored. Nor are `chat` and `contact`: a card's member list is not
  * known to be whole, and `saveMembers` replaces the list.
  */
-export declare const stored: (messenger: MessengerAdapter, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, rekeyPacing, closing, namesFromStore, recipientIds, }: Saving) => MessengerAdapter;
+export declare const stored: (messenger: MessengerAdapter, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, rekeyPacing, closing, namesFromStore, recipientIds, countsUnread, }: Saving) => MessengerAdapter;

package/dist/cli/messenger/stored.js

@@ -12,7 +12,7 @@ const REKEY_PACING = { lockMs: 50, pauseMs: 25 };
  * would erase what `chats list` stored. Nor are `chat` and `contact`: a card's member list is not
  * known to be whole, and `saveMembers` replaces the list.
  */
-export const stored = (messenger, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, rekeyPacing = REKEY_PACING, closing, namesFromStore, recipientIds, }) => {
+export const stored = (messenger, { account, store, warn, events, pending, announcing, deletedWithoutChat, profile, rekeyed, rekeyPacing = REKEY_PACING, closing, namesFromStore, recipientIds, countsUnread = false, }) => {
     let warned = false;
     let recorded = profile === undefined;
     const notWritten = (operation, error) => {
@@ -318,7 +318,7 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
                         await rememberTitles(store, account, titles);
                     return (messenger.watch?.((event) => {
                         const seenAt = Date.now();
-                        void save("messages.watch", (opened) => keep(opened, account, event, seenAt, deletedWithoutChat));
+                        void save("messages.watch", (opened) => keep(opened, account, event, seenAt, deletedWithoutChat, countsUnread));
                         onEvent(namesFromStore ? titled(event, titles) : event);
                     }, signal, onReady) ?? Promise.resolve());
                 },
@@ -327,7 +327,7 @@ export const stored = (messenger, { account, store, warn, events, pending, annou
         ...(messenger.listen
             ? {
                 listen: (onEvent, signal) => messenger.listen?.((event) => {
-                    void save("messages.listen", (opened) => keep(opened, account, event, Date.now(), deletedWithoutChat));
+                    void save("messages.listen", (opened) => keep(opened, account, event, Date.now(), deletedWithoutChat, countsUnread));
                     onEvent(event);
                 }, signal) ?? Promise.resolve(),
             }
@@ -541,12 +541,16 @@ const fill = async (store, account, batch) => {
  * Each change as the store keeps it: a message or an edit upserted, a deletion a tombstone, reactions replaced, a
  * voter's vote or a person's reaction replacing their older one, a star set or taken off, a chat event kept once.
  */
-const keep = async (store, account, event, seenAt, among) => {
+const keep = async (store, account, event, seenAt, among, countsUnread) => {
     switch (event.event) {
         case "message":
         case "edit": {
             const { chatTitle, ...message } = event.message;
-            await store.messages.saveMessages(account, message.chatId, [message], { via: "update", seenAt });
+            await store.messages.saveMessages(account, message.chatId, [message], {
+                via: "update",
+                seenAt,
+                ...(countsUnread && event.event === "message" ? { countUnread: true } : {}),
+            });
             return;
         }
         case "delete":
@@ -561,6 +565,9 @@ const keep = async (store, account, event, seenAt, among) => {
         case "star":
             await store.messages.saveStar(account, event.chatId, event.messageId, event.starred);
             return;
+        case "delivery":
+            await store.messages.saveDelivery(account, event.chatId, event.messageId, event.delivery);
+            return;
         case "chat_event":
             await store.roster.saveChatEvents(account, event.chatId, [event.change]);
             return;

package/dist/cli/messenger/watch-command.js

@@ -118,6 +118,8 @@ const describe = (event, render) => {
         }
         case "star":
             return `${event.starred ? "starred" : "unstarred"} in ${event.chatTitle ?? event.chatId}: message ${event.messageId}\n`;
+        case "delivery":
+            return `${event.delivery} in ${event.chatTitle ?? event.chatId}: message ${event.messageId}\n`;
         case "chat_event": {
             const { event: action, by, people } = event.change;
             const who = people.map((one) => one.name ?? one.id).join(", ");

package/dist/documents/blocks.d.ts

@@ -0,0 +1,45 @@
+export interface Inline {
+    text: string;
+    bold?: true;
+    italic?: true;
+    strike?: true;
+    code?: true;
+    link?: string;
+}
+export type ListKind = "bullet" | "number" | "check";
+export type Block = {
+    kind: "heading";
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    inlines: Inline[];
+} | {
+    kind: "paragraph";
+    inlines: Inline[];
+} | {
+    kind: "item";
+    list: ListKind;
+    depth: number;
+    checked?: boolean;
+    inlines: Inline[];
+} | {
+    kind: "code";
+    language?: string;
+    text: string;
+} | {
+    kind: "quote";
+    inlines: Inline[];
+} | {
+    kind: "table";
+    header: Inline[][];
+    rows: Inline[][][];
+} | {
+    kind: "image";
+    url: string;
+    alt: string;
+} | {
+    kind: "rule";
+};
+/** Adjacent runs with the same marks merge and empty runs drop, so two equal texts give one key. */
+export declare const normalizeInlines: (inlines: Inline[]) => Inline[];
+export declare const blockKey: (block: Block) => string;
+/** The same key with checklist ticks left out: two blocks that differ only in a tick share it. */
+export declare const blockShape: (block: Block) => string;

package/dist/documents/blocks.js

@@ -0,0 +1,48 @@
+const MARKS = ["bold", "italic", "strike", "code", "link"];
+const sameMarks = (a, b) => MARKS.every((mark) => a[mark] === b[mark]);
+/** Adjacent runs with the same marks merge and empty runs drop, so two equal texts give one key. */
+export const normalizeInlines = (inlines) => {
+    const out = [];
+    for (const inline of inlines) {
+        if (!inline.text)
+            continue;
+        const last = out.at(-1);
+        if (last && sameMarks(last, inline))
+            last.text += inline.text;
+        else
+            out.push({ ...inline });
+    }
+    return out;
+};
+const inlineKey = (inline) => [inline.text, ...MARKS.map((mark) => inline[mark] ?? "")];
+const key = (block, withChecked) => {
+    switch (block.kind) {
+        case "heading":
+            return [block.kind, block.level, normalizeInlines(block.inlines).map(inlineKey)];
+        case "paragraph":
+        case "quote":
+            return [block.kind, normalizeInlines(block.inlines).map(inlineKey)];
+        case "item":
+            return [
+                block.kind,
+                block.list,
+                block.depth,
+                withChecked && block.list === "check" ? Boolean(block.checked) : "",
+                normalizeInlines(block.inlines).map(inlineKey),
+            ];
+        case "code":
+            return [block.kind, block.language ?? "", block.text];
+        case "table":
+            return [
+                block.kind,
+                [block.header, ...block.rows].map((row) => row.map((cell) => normalizeInlines(cell).map(inlineKey))),
+            ];
+        case "image":
+            return [block.kind, block.url, block.alt];
+        case "rule":
+            return [block.kind];
+    }
+};
+export const blockKey = (block) => JSON.stringify(key(block, true));
+/** The same key with checklist ticks left out: two blocks that differ only in a tick share it. */
+export const blockShape = (block) => JSON.stringify(key(block, false));

package/dist/documents/index.d.ts

@@ -1,9 +1,14 @@
+export { type BlockHunk, diffBlocks, type Reconciled, reconcileBlocks } from "../services/documents/block-diff.js";
 export { type Complete, extractMemories } from "../services/documents/extraction.js";
 export { documentIngestion, type IngestionOptions } from "../services/documents/ingestion.js";
 export { type DocumentKnowledge, documentKnowledge } from "../services/documents/knowledge.js";
 export type { SyncOptions } from "../services/documents/ports.js";
 export { extractDocumentMemories, type ImportedSource, type ProposalOptions } from "../services/documents/proposals.js";
+export { type PushOptions, type PushResult, planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";
 export { type SyncResult, syncDocuments } from "../services/documents/sync.js";
+export { type Block, blockKey, blockShape, type Inline, type ListKind, normalizeInlines } from "./blocks.js";
 export { catalogFiles } from "./catalog.js";
+export { markdownBlocks } from "./markdown-blocks.js";
 export type { DocumentSource, IndexedSource, PictureWriter, SourceChange, SourceContent, SourceFile, SourceIndex, SourceSkip, SourceState, SourceStatePort, SourceWalk, SourceWork, TabText, } from "./model.js";
+export type { DocumentTarget, LocalDocument, Prepared, PushEntry, Pushed, PushPlan, PushState, PushStatePort, } from "./push-model.js";
 export { within } from "./scope.js";

package/dist/documents/index.js

@@ -1,7 +1,11 @@
+export { diffBlocks, reconcileBlocks } from "../services/documents/block-diff.js";
 export { extractMemories } from "../services/documents/extraction.js";
 export { documentIngestion } from "../services/documents/ingestion.js";
 export { documentKnowledge } from "../services/documents/knowledge.js";
 export { extractDocumentMemories } from "../services/documents/proposals.js";
+export { planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";
 export { syncDocuments } from "../services/documents/sync.js";
+export { blockKey, blockShape, normalizeInlines } from "./blocks.js";
 export { catalogFiles } from "./catalog.js";
+export { markdownBlocks } from "./markdown-blocks.js";
 export { within } from "./scope.js";

package/dist/documents/markdown-blocks.d.ts

@@ -0,0 +1,3 @@
+import { type Block } from "./blocks.js";
+/** Markdown (CommonMark + GFM tables, task lists and strikethrough) as the blocks a provider can write natively. */
+export declare const markdownBlocks: (markdown: string) => Promise<Block[]>;

package/dist/documents/markdown-blocks.js

@@ -0,0 +1,123 @@
+import { normalizeInlines } from "./blocks.js";
+// Loaded on first use: importing the documents entry point would otherwise cost every command about 50 ms.
+let parser;
+const loadParser = () => (parser ??= Promise.all([
+    import("mdast-util-from-markdown"),
+    import("mdast-util-gfm"),
+    import("micromark-extension-gfm"),
+]).then(([{ fromMarkdown }, { gfmFromMarkdown }, { gfm }]) => (markdown) => fromMarkdown(markdown, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] })));
+/** Markdown (CommonMark + GFM tables, task lists and strikethrough) as the blocks a provider can write natively. */
+export const markdownBlocks = async (markdown) => {
+    const tree = (await loadParser())(markdown);
+    const definitions = new Map();
+    const collect = (node) => {
+        if (node.type === "definition")
+            definitions.set(node.identifier, node);
+        if ("children" in node)
+            for (const child of node.children)
+                collect(child);
+    };
+    collect(tree);
+    const images = [];
+    const inlinesOf = (nodes, marks = {}) => nodes.flatMap((node) => {
+        switch (node.type) {
+            case "text":
+                return [{ ...marks, text: node.value.replace(/\n/g, " ") }];
+            case "inlineCode":
+                return [{ ...marks, code: true, text: node.value }];
+            case "strong":
+                return inlinesOf(node.children, { ...marks, bold: true });
+            case "emphasis":
+                return inlinesOf(node.children, { ...marks, italic: true });
+            case "delete":
+                return inlinesOf(node.children, { ...marks, strike: true });
+            case "link":
+                return inlinesOf(node.children, { ...marks, link: node.url });
+            case "linkReference": {
+                const url = definitions.get(node.identifier)?.url;
+                return inlinesOf(node.children, url ? { ...marks, link: url } : marks);
+            }
+            case "break":
+                return [{ ...marks, text: "\n" }];
+            case "image":
+                images.push({ kind: "image", url: node.url, alt: node.alt ?? "" });
+                return [];
+            case "imageReference": {
+                const url = definitions.get(node.identifier)?.url;
+                if (url)
+                    images.push({ kind: "image", url, alt: node.alt ?? "" });
+                return [];
+            }
+            case "html":
+                return [{ ...marks, text: node.value }];
+            default:
+                return "children" in node ? inlinesOf(node.children, marks) : [];
+        }
+    });
+    const trimmed = (inlines) => {
+        const out = normalizeInlines(inlines);
+        const first = out[0];
+        const last = out.at(-1);
+        if (first)
+            first.text = first.text.trimStart();
+        if (last)
+            last.text = last.text.trimEnd();
+        return normalizeInlines(out);
+    };
+    const withImages = (block) => {
+        const found = images.splice(0);
+        if (block?.kind === "paragraph" && !block.inlines.length)
+            return found;
+        return block ? [block, ...found] : found;
+    };
+    const textOf = (node) => node.children.flatMap((child) => child.type === "paragraph" || child.type === "heading" ? inlinesOf(child.children) : []);
+    const blocks = (nodes, depth = 0) => nodes.flatMap((node) => {
+        switch (node.type) {
+            case "heading":
+                return withImages({ kind: "heading", level: node.depth, inlines: trimmed(inlinesOf(node.children)) });
+            case "paragraph":
+                return withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(node.children)) });
+            case "code":
+                return [{ kind: "code", ...(node.lang ? { language: node.lang } : {}), text: node.value }];
+            case "blockquote":
+                return node.children.flatMap((child) => child.type === "paragraph" || child.type === "heading"
+                    ? withImages({ kind: "quote", inlines: trimmed(inlinesOf(child.children)) })
+                    : blocks([child], depth));
+            case "thematicBreak":
+                return [{ kind: "rule" }];
+            case "table": {
+                const [head, ...rows] = node.children.map((row) => row.children.map((cell) => trimmed(inlinesOf(cell.children))));
+                return [{ kind: "table", header: head ?? [], rows }];
+            }
+            case "list":
+                return node.children.flatMap((item) => {
+                    const [first, ...rest] = item.children;
+                    const head = {
+                        kind: "item",
+                        list: (item.checked != null ? "check" : node.ordered ? "number" : "bullet"),
+                        depth,
+                        ...(item.checked != null ? { checked: item.checked } : {}),
+                        inlines: trimmed(first && first.type === "paragraph" ? inlinesOf(first.children) : []),
+                    };
+                    const tail = first && first.type !== "paragraph" ? [first, ...rest] : rest;
+                    return [
+                        ...withImages(head),
+                        ...tail.flatMap((child) => child.type === "list"
+                            ? blocks([child], depth + 1)
+                            : child.type === "paragraph"
+                                ? withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(child.children)) })
+                                : blocks([child], depth)),
+                    ];
+                });
+            case "html":
+                return [{ kind: "paragraph", inlines: [{ text: node.value }] }];
+            case "definition":
+            case "footnoteDefinition":
+            case "yaml":
+                return [];
+            default:
+                return "children" in node ? withImages({ kind: "paragraph", inlines: trimmed(textOf(node)) }) : [];
+        }
+    });
+    return blocks(tree.children);
+};