@wirecat/cli-core 0.382.0 → 0.383.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 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

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/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);
+};

package/dist/documents/push-model.d.ts

@@ -0,0 +1,89 @@
+/** A local file a push mirrors: its path relative to the mirrored folder, with `/` separators. */
+export interface LocalDocument {
+    path: string;
+    absolute: string;
+    hash: string;
+    kind: string;
+}
+export interface Pushed<S> {
+    id: string;
+    url: string;
+    /** What the provider reads back after its own write; the next push compares the remote against it. */
+    snapshot: S;
+}
+/**
+ * What an update found before writing. Only `write` reaches the remote, so a conflict or a file with nothing to
+ * change never counts as a write.
+ */
+export type Prepared<S> = {
+    conflict: string;
+} | {
+    missing: true;
+} | {
+    unchanged: Pushed<S>;
+} | {
+    write(): Promise<Pushed<S>>;
+};
+/**
+ * A provider that writes local files as its own native documents. Every write is one provider call per
+ * file (or one all-or-nothing batch): a write cut in half would read back as somebody else's edit.
+ */
+export interface DocumentTarget<S> {
+    identity(): Promise<string>;
+    /** The provider's document kind for a local path, or undefined when the path is not pushed. */
+    kindOf(path: string): string | undefined;
+    /** Finds the folder carrying `origin` or creates it: a crash between create and save must not duplicate it. */
+    ensureFolder(input: {
+        parent: string;
+        name: string;
+        origin: string;
+    }): Promise<string>;
+    findByOrigin(origin: string): Promise<Pushed<S> | undefined>;
+    create(input: {
+        file: LocalDocument;
+        name: string;
+        parent: string;
+        origin: string;
+        operationId: string;
+        signal?: AbortSignal;
+    }): Promise<Pushed<S>>;
+    /** Reads the remote and compares it with `recorded`; a conflict instead of a write unless `force`. */
+    prepare(input: {
+        id: string;
+        file: LocalDocument;
+        recorded: S;
+        force: boolean;
+        signal?: AbortSignal;
+    }): Promise<Prepared<S>>;
+}
+export interface PushEntry<S> {
+    id: string;
+    url: string;
+    kind: string;
+    hash: string;
+    snapshot: S;
+    pushedAt: string;
+}
+export interface PushState<S> {
+    version: 1;
+    principal: string;
+    root: string;
+    target: string;
+    folders: Record<string, string>;
+    entries: Record<string, PushEntry<S>>;
+    /** Saved before a create, so a crash after the provider wrote but before this state was saved finds the file. */
+    pending: Record<string, {
+        origin: string;
+        operationId: string;
+    }>;
+}
+export interface PushStatePort<S> {
+    read(): PushState<S>;
+    save(state: PushState<S>): void;
+}
+export interface PushPlan {
+    create: LocalDocument[];
+    update: LocalDocument[];
+    unchanged: LocalDocument[];
+    orphans: string[];
+}

package/dist/documents/push-model.js

@@ -0,0 +1 @@
+export {};

package/dist/documents.d.ts

@@ -1,3 +1,4 @@
+export { readSpreadsheet } from "./attachments/documents.js";
 export type { Engine, Extraction, FileHint, LoadEngine } from "./attachments/extract.js";
 export { extractText, importEngine, MAX_FILE_BYTES, MAX_TEXT_CHARS } from "./attachments/extract.js";
 export { attachmentMaxBytes } from "./attachments/limits.js";

package/dist/documents.js

@@ -1,3 +1,4 @@
+export { readSpreadsheet } from "./attachments/documents.js";
 export { extractText, importEngine, MAX_FILE_BYTES, MAX_TEXT_CHARS } from "./attachments/extract.js";
 export { attachmentMaxBytes } from "./attachments/limits.js";
 export { columnName, sheetText } from "./attachments/sheets.js";

package/dist/errors/reasons.js

@@ -26,6 +26,9 @@ const OTHERS = [
     validation("extraction.text-too-long", "the text is too long for memory extraction"),
     validation("file.locked", "another process holds the file's lock"),
     ["profile.wrong-account", "authentication_error", "the signed-in source account does not match this profile"],
+    validation("push.too-many-files", "the folder holds more files than one push takes"),
+    validation("push.unreadable", "the folder to push could not be read"),
+    validation("spreadsheet.unreadable", "the workbook could not be read"),
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
     validation("catalog.scope-limit", "the selected catalog exceeds its entry limit"),

package/dist/services/documents/block-diff.d.ts

@@ -0,0 +1,24 @@
+import { type Block } from "../../documents/blocks.js";
+/** `base[from, to)` is replaced by `blocks`; an empty range is an insert, an empty `blocks` a delete. */
+export interface BlockHunk {
+    from: number;
+    to: number;
+    blocks: Block[];
+}
+/** The edits that turn `base` into `next`, leaving every unchanged block in place. */
+export declare const diffBlocks: (base: Block[], next: Block[]) => BlockHunk[];
+export type Reconciled = {
+    status: "clean";
+    blocks: Block[];
+    ticksKept: number;
+} | {
+    status: "conflict";
+};
+/**
+ * What a push may write. `recorded` is what the last push wrote and read back, `current` the remote
+ * now, `local` the file now and `lastLocal` the file as the last push read it. Any remote change other
+ * than a checklist tick is a conflict, so the push never overwrites someone's edit. A tick follows the
+ * side that changed it: the local file when its tick differs from `lastLocal`, the remote otherwise —
+ * judged on every push, so a remote tick is not undone once the remote and `recorded` agree again.
+ */
+export declare const reconcileBlocks: (recorded: Block[], current: Block[], local: Block[], lastLocal: Block[]) => Reconciled;

package/dist/services/documents/block-diff.js

@@ -0,0 +1,91 @@
+import { blockKey, blockShape } from "../../documents/blocks.js";
+const MAX_CELLS = 4_000_000;
+/** Longest common subsequence: index pairs [inA, inB] of blocks with equal keys, in order. */
+const matches = (a, b, keyOf) => {
+    const ka = a.map(keyOf);
+    const kb = b.map(keyOf);
+    let start = 0;
+    while (start < ka.length && start < kb.length && ka[start] === kb[start])
+        start++;
+    let endA = ka.length;
+    let endB = kb.length;
+    while (endA > start && endB > start && ka[endA - 1] === kb[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const rows = endA - start;
+    const cols = endB - start;
+    const pairs = [];
+    for (let i = 0; i < start; i++)
+        pairs.push([i, i]);
+    if (rows * cols > MAX_CELLS) {
+        // Too large to align: the changed middle is rewritten as one block of edits.
+    }
+    else if (rows && cols) {
+        const table = new Uint32Array((rows + 1) * (cols + 1));
+        for (let i = rows - 1; i >= 0; i--)
+            for (let j = cols - 1; j >= 0; j--)
+                table[i * (cols + 1) + j] =
+                    ka[start + i] === kb[start + j]
+                        ? table[(i + 1) * (cols + 1) + j + 1] + 1
+                        : Math.max(table[(i + 1) * (cols + 1) + j], table[i * (cols + 1) + j + 1]);
+        let i = 0;
+        let j = 0;
+        while (i < rows && j < cols) {
+            if (ka[start + i] === kb[start + j]) {
+                pairs.push([start + i, start + j]);
+                i++;
+                j++;
+            }
+            else if (table[(i + 1) * (cols + 1) + j] >= table[i * (cols + 1) + j + 1])
+                i++;
+            else
+                j++;
+        }
+    }
+    for (let offset = 0; offset < ka.length - endA; offset++)
+        pairs.push([endA + offset, endB + offset]);
+    return pairs;
+};
+/** The edits that turn `base` into `next`, leaving every unchanged block in place. */
+export const diffBlocks = (base, next) => {
+    const hunks = [];
+    let a = 0;
+    let b = 0;
+    for (const [i, j] of [...matches(base, next, blockKey), [base.length, next.length]]) {
+        if (i > a || j > b)
+            hunks.push({ from: a, to: i, blocks: next.slice(b, j) });
+        a = i + 1;
+        b = j + 1;
+    }
+    return hunks;
+};
+const isCheck = (block) => block?.kind === "item" && block.list === "check";
+/**
+ * What a push may write. `recorded` is what the last push wrote and read back, `current` the remote
+ * now, `local` the file now and `lastLocal` the file as the last push read it. Any remote change other
+ * than a checklist tick is a conflict, so the push never overwrites someone's edit. A tick follows the
+ * side that changed it: the local file when its tick differs from `lastLocal`, the remote otherwise —
+ * judged on every push, so a remote tick is not undone once the remote and `recorded` agree again.
+ */
+export const reconcileBlocks = (recorded, current, local, lastLocal) => {
+    const sameShape = recorded.length === current.length &&
+        recorded.every((block, index) => blockShape(block) === blockShape(current[index]));
+    if (!sameShape)
+        return { status: "conflict" };
+    const before = new Map(matches(local, lastLocal, blockShape));
+    const blocks = local.map((block) => ({ ...block }));
+    let ticksKept = 0;
+    for (const [i, j] of matches(current, local, blockShape)) {
+        const remote = current[i];
+        const mine = blocks[j];
+        const last = lastLocal[before.get(j) ?? -1];
+        if (!isCheck(remote) || !isCheck(mine) || !isCheck(last))
+            continue;
+        if (Boolean(mine.checked) === Boolean(last.checked) && Boolean(remote.checked) !== Boolean(mine.checked)) {
+            mine.checked = Boolean(remote.checked);
+            ticksKept++;
+        }
+    }
+    return { status: "clean", blocks, ticksKept };
+};

package/dist/services/documents/push.d.ts

@@ -0,0 +1,60 @@
+import { CliError } from "@wirecat/cli-base";
+import type { DocumentTarget, LocalDocument, PushPlan, PushState, PushStatePort } from "../../documents/push-model.js";
+export interface PushOptions<S> {
+    /** Absolute path of the local folder being mirrored. */
+    root: string;
+    /** Remote folder id the mirror writes into. */
+    folder: string;
+    target: DocumentTarget<S>;
+    state: PushStatePort<S>;
+    principal: string;
+    force?: boolean;
+    dryRun?: boolean;
+    /** Runs one remote write behind the provider's permission checks and write journal. */
+    guard<T>(attempt: {
+        action: "create" | "update" | "folder";
+        path: string;
+        operationId: string;
+    }, act: () => Promise<T>): Promise<T>;
+    operationId(): string;
+    errorOf(error: unknown): CliError;
+    assertHeld(): void;
+    signal?: AbortSignal;
+    maxFiles?: number;
+    now?(): number;
+}
+export interface PushResult {
+    created: string[];
+    updated: string[];
+    unchanged: number;
+    conflicts: {
+        path: string;
+        url: string;
+        reason: string;
+    }[];
+    missing: string[];
+    orphans: {
+        path: string;
+        url: string;
+    }[];
+    errors: {
+        path: string;
+        code: string;
+        message: string;
+    }[];
+    unsupported: number;
+    plan?: {
+        create: string[];
+        update: string[];
+        orphans: string[];
+    };
+    stopped?: true;
+}
+/** Files under `root` the target pushes. Hidden files, editor leftovers and symbolic links are never followed. */
+export declare const scanLocal: (root: string, kindOf: (path: string) => string | undefined, maxFiles?: number) => Promise<{
+    files: LocalDocument[];
+    unsupported: number;
+}>;
+/** What a push would do, from the local files and the last push alone: no remote read. */
+export declare const planPush: <S>(files: LocalDocument[], state: PushState<S>) => PushPlan;
+export declare const pushDocuments: <S>(options: PushOptions<S>) => Promise<PushResult>;

package/dist/services/documents/push.js

@@ -0,0 +1,218 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, posix } from "node:path";
+import { CliError, isCliError } from "@wirecat/cli-base";
+const SKIPPED = /^(\.|node_modules$|~\$)|(~|\.swp|\.tmp)$/;
+const hashFile = (path) => new Promise((done, fail) => {
+    const hash = createHash("sha256");
+    createReadStream(path)
+        .on("data", (chunk) => hash.update(chunk))
+        .on("error", fail)
+        .on("end", () => done(hash.digest("hex")));
+});
+/** Files under `root` the target pushes. Hidden files, editor leftovers and symbolic links are never followed. */
+export const scanLocal = async (root, kindOf, maxFiles = 10_000) => {
+    const files = [];
+    let unsupported = 0;
+    const walk = async (relative) => {
+        const entries = await readdir(join(root, relative), { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (SKIPPED.test(entry.name) || entry.isSymbolicLink())
+                continue;
+            const path = relative ? posix.join(relative, entry.name) : entry.name;
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile()) {
+                const kind = kindOf(path);
+                if (!kind) {
+                    unsupported++;
+                    continue;
+                }
+                if (files.length >= maxFiles)
+                    throw new CliError("validation_error", `the folder holds more than ${maxFiles} files to push`, {
+                        reason: "push.too-many-files",
+                    });
+                const absolute = join(root, path);
+                files.push({ path, absolute, kind, hash: await hashFile(absolute) });
+            }
+        }
+    };
+    try {
+        await walk("");
+    }
+    catch (error) {
+        if (isCliError(error))
+            throw error;
+        throw new CliError("validation_error", "the folder to push could not be read", { reason: "push.unreadable" });
+    }
+    return { files, unsupported };
+};
+/** What a push would do, from the local files and the last push alone: no remote read. */
+export const planPush = (files, state) => {
+    const plan = { create: [], update: [], unchanged: [], orphans: [] };
+    const seen = new Set();
+    for (const file of files) {
+        seen.add(file.path);
+        const entry = state.entries[file.path];
+        if (!entry)
+            plan.create.push(file);
+        else if (entry.hash !== file.hash)
+            plan.update.push(file);
+        else
+            plan.unchanged.push(file);
+    }
+    plan.orphans = Object.keys(state.entries).filter((path) => !seen.has(path));
+    return plan;
+};
+const originOf = (principal, root, folder, path) => createHash("sha256")
+    .update(JSON.stringify([principal, root, folder, path]))
+    .digest("hex")
+    .slice(0, 32);
+export const pushDocuments = async (options) => {
+    const { root, folder, target, principal, force = false, signal } = options;
+    const now = options.now ?? Date.now;
+    if (signal?.aborted)
+        throw new CliError("cancelled", "push was cancelled");
+    if ((await target.identity()) !== principal)
+        throw new CliError("authentication_error", "signed-in account does not match this profile", {
+            reason: "profile.wrong-account",
+        });
+    const state = options.state.read();
+    if (state.principal !== principal || state.root !== root || state.target !== folder)
+        throw new CliError("configuration_error", "push state belongs to another account or mirror");
+    const save = () => options.state.save(state);
+    if (!options.dryRun)
+        for (const [path, pending] of Object.entries(state.pending)) {
+            const found = await target.findByOrigin(pending.origin);
+            // An empty hash makes this pass update the found file from the local one.
+            if (found)
+                state.entries[path] = { ...found, kind: target.kindOf(path) ?? "", hash: "", pushedAt: "" };
+            delete state.pending[path];
+            save();
+        }
+    const { files, unsupported } = await scanLocal(root, (path) => target.kindOf(path), options.maxFiles);
+    const plan = planPush(files, state);
+    const result = {
+        created: [],
+        updated: [],
+        unchanged: plan.unchanged.length,
+        conflicts: [],
+        missing: [],
+        orphans: plan.orphans.map((path) => ({ path, url: state.entries[path]?.url ?? "" })),
+        errors: [],
+        unsupported,
+    };
+    if (options.dryRun) {
+        result.plan = {
+            create: plan.create.map((file) => file.path),
+            update: plan.update.map((file) => file.path),
+            orphans: plan.orphans,
+        };
+        return result;
+    }
+    const folderOf = async (path) => {
+        const directory = posix.dirname(path);
+        if (directory === ".")
+            return folder;
+        const known = state.folders[directory];
+        if (known)
+            return known;
+        const parent = await folderOf(directory);
+        const operationId = options.operationId();
+        options.assertHeld();
+        const id = await options.guard({ action: "folder", path: directory, operationId }, () => target.ensureFolder({
+            parent,
+            name: posix.basename(directory),
+            origin: originOf(principal, root, folder, `${directory}/`),
+        }));
+        state.folders[directory] = id;
+        save();
+        return id;
+    };
+    const create = async (file) => {
+        const parent = await folderOf(file.path);
+        const operationId = options.operationId();
+        const origin = originOf(principal, root, folder, file.path);
+        state.pending[file.path] = { origin, operationId };
+        save();
+        options.assertHeld();
+        const pushed = await options.guard({ action: "create", path: file.path, operationId }, () => target.create({
+            file,
+            name: posix.basename(file.path),
+            parent,
+            origin,
+            operationId,
+            ...(signal ? { signal } : {}),
+        }));
+        state.entries[file.path] = { ...pushed, kind: file.kind, hash: file.hash, pushedAt: new Date(now()).toISOString() };
+        delete state.pending[file.path];
+        save();
+        result.created.push(file.path);
+    };
+    const work = [
+        ...plan.create.map((file) => ({ file, create: true })),
+        ...plan.update.map((file) => ({ file, create: false })),
+    ];
+    for (const job of work.sort((a, b) => a.file.path.localeCompare(b.file.path))) {
+        if (signal?.aborted) {
+            result.stopped = true;
+            break;
+        }
+        const { file } = job;
+        try {
+            const entry = state.entries[file.path];
+            if (job.create || !entry) {
+                await create(file);
+                continue;
+            }
+            const prepared = await target.prepare({
+                id: entry.id,
+                file,
+                recorded: entry.snapshot,
+                force,
+                ...(signal ? { signal } : {}),
+            });
+            if ("conflict" in prepared) {
+                result.conflicts.push({ path: file.path, url: entry.url, reason: prepared.conflict });
+                continue;
+            }
+            if ("missing" in prepared) {
+                if (!force) {
+                    result.missing.push(file.path);
+                    continue;
+                }
+                delete state.entries[file.path];
+                await create(file);
+                continue;
+            }
+            let pushed;
+            if ("unchanged" in prepared) {
+                pushed = prepared.unchanged;
+                result.unchanged++;
+            }
+            else {
+                const operationId = options.operationId();
+                options.assertHeld();
+                pushed = await options.guard({ action: "update", path: file.path, operationId }, () => prepared.write());
+                result.updated.push(file.path);
+            }
+            state.entries[file.path] = {
+                ...pushed,
+                kind: file.kind,
+                hash: file.hash,
+                pushedAt: new Date(now()).toISOString(),
+            };
+            save();
+        }
+        catch (error) {
+            const failure = options.errorOf(error);
+            if (failure.code === "cancelled") {
+                result.stopped = true;
+                break;
+            }
+            result.errors.push({ path: file.path, code: failure.code, message: failure.message });
+        }
+    }
+    return result;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.382.0",
+  "version": "0.383.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -182,6 +182,9 @@
     "liquidjs": "10.30.0",
     "lossless-json": "4.3.0",
     "mammoth": "1.13.0",
+    "mdast-util-from-markdown": "2.1.0",
+    "mdast-util-gfm": "3.1.0",
+    "micromark-extension-gfm": "3.0.0",
     "ogg-opus-decoder": "1.7.5",
     "psl": "1.15.0",
     "qrcode-generator": "2.0.4",
@@ -200,6 +203,7 @@
     "@cspell/dict-ru_ru": "2.3.3",
     "@modelcontextprotocol/client": "2.2.0",
     "@napi-rs/canvas": "1.0.10",
+    "@types/mdast": "4.0.4",
     "@types/node": "^22.20.4",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.2",