@wirecat/cli-core 0.385.0 → 0.387.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ shape of this file.
 
 ## Unreleased
 
+## 0.387.0 — 22.10.2026
+
+### Added
+
+- `dateWindow` and `DateWindow` from `./cli`: `--since-time` and `--until-time` read together, with the
+  `meta.timezone` and `meta.window` an answer reports them by (WC-TIME-3, WC-TIME-5).
+
+## 0.386.0 — 22.10.2026
+
+### Added
+
+- **Document sync works both ways.** `pushDocuments` reads every mirrored file back on each run and merges changes
+  made in the provider into the local file. Only the lines of changed blocks are rewritten, and a tick is flipped in
+  place. A conflict lists the changed parts and when each side changed, and the run goes on with the other files;
+  `keep: "local" | "remote" | "both"` settles conflicts. New: `mergeBlocks`, `spliceMarkdown`, `blocksMarkdown`,
+  `inlineMarkdown`, `placedMarkdownBlocks`.
+
+### Changed — may break callers
+
+- `PushOptions.force` is replaced by `keep` (settle conflicts) and `recreate` (create a remotely deleted file again);
+  `prepare` gets `keep` instead of `force`. Its update result is `{ local?, afterLocal?, remote, write }`:
+  `remote: false` writes only the local file; `afterLocal` is saved between the local and the remote write. `PushResult` adds `pulled`; a conflict may carry `parts`, `localChangedAt`,
+  `remoteChangedAt` and `remoteChangedBy`. `reconcileBlocks` is removed; `mergeBlocks` replaces it.
+
 ## 0.385.0 — 22.10.2026
 
 ### Fixed

package/dist/cli/index.d.ts

@@ -27,7 +27,7 @@ export { guardedApp, guardedPress, guardedStart, type Pressed } from "../sends/b
 export { guardedClose, guardedCreatePoll, guardedVote } from "../sends/polls.js";
 export type { InboxReader } from "../services/inbox.js";
 export { INBOX_CHATS, newIn, REVIEW_CHATS, reviewIn, unreadIn } from "../services/inbox.js";
-export { momentOf } from "../services/moment.js";
+export { type DateWindow, dateWindow, momentOf } from "../services/moment.js";
 export { maskedAccount } from "../services/people.js";
 export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";

package/dist/cli/index.js

@@ -22,7 +22,7 @@ export { currentRun, inRun, useAsProcessRun } from "../runs/scope.js";
 export { guardedApp, guardedPress, guardedStart } from "../sends/buttons.js";
 export { guardedClose, guardedCreatePoll, guardedVote } from "../sends/polls.js";
 export { INBOX_CHATS, newIn, REVIEW_CHATS, reviewIn, unreadIn } from "../services/inbox.js";
-export { momentOf } from "../services/moment.js";
+export { dateWindow, momentOf } from "../services/moment.js";
 export { maskedAccount } from "../services/people.js";
 export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";

package/dist/documents/index.d.ts

@@ -1,14 +1,15 @@
-export { type BlockHunk, diffBlocks, type Reconciled, reconcileBlocks } from "../services/documents/block-diff.js";
+export { type BlockConflict, type BlockHunk, diffBlocks, type Merged, mergeBlocks, } 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 { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.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 PushConflict, 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 { markdownBlocks, type PlacedBlock, placedMarkdownBlocks } 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 type { ConflictPart, DocumentTarget, Keep, LocalDocument, Prepared, PushEntry, Pushed, PushPlan, PushState, PushStatePort, RemoteChange, } from "./push-model.js";
 export { within } from "./scope.js";

package/dist/documents/index.js

@@ -1,11 +1,12 @@
-export { diffBlocks, reconcileBlocks } from "../services/documents/block-diff.js";
+export { diffBlocks, mergeBlocks, } 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 { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.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 { markdownBlocks, placedMarkdownBlocks } from "./markdown-blocks.js";
 export { within } from "./scope.js";

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

@@ -1,3 +1,15 @@
 import { type Block } from "./blocks.js";
+/**
+ * A block and the source it came from: `[start, end)` offsets into the Markdown. Blocks cut from one source
+ * stretch (a paragraph and its images, the paragraphs of one quote) share it. `column` is where a list item's
+ * text starts, which is how far a nested item under it must be indented.
+ */
+export interface PlacedBlock {
+    block: Block;
+    start: number;
+    end: number;
+    column?: number;
+}
 /** Markdown (CommonMark + GFM tables, task lists and strikethrough) as the blocks a provider can write natively. */
 export declare const markdownBlocks: (markdown: string) => Promise<Block[]>;
+export declare const placedMarkdownBlocks: (markdown: string) => Promise<PlacedBlock[]>;

package/dist/documents/markdown-blocks.js

@@ -7,7 +7,8 @@ const loadParser = () => (parser ??= Promise.all([
     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) => {
+export const markdownBlocks = async (markdown) => (await placedMarkdownBlocks(markdown)).map((placed) => placed.block);
+export const placedMarkdownBlocks = async (markdown) => {
     const tree = (await loadParser())(markdown);
     const definitions = new Map();
     const collect = (node) => {
@@ -64,30 +65,33 @@ export const markdownBlocks = async (markdown) => {
             last.text = last.text.trimEnd();
         return normalizeInlines(out);
     };
-    const withImages = (block) => {
+    const spanOf = (node) => ({ start: node.position?.start.offset ?? 0, end: node.position?.end.offset ?? 0 });
+    const withImages = (block, span) => {
         const found = images.splice(0);
-        if (block?.kind === "paragraph" && !block.inlines.length)
-            return found;
-        return block ? [block, ...found] : found;
+        const blocks = block?.kind === "paragraph" && !block.inlines.length ? found : block ? [block, ...found] : found;
+        return blocks.map((one) => ({ block: one, ...span }));
     };
     const textOf = (node) => node.children.flatMap((child) => child.type === "paragraph" || child.type === "heading" ? inlinesOf(child.children) : []);
     const blocks = (nodes, depth = 0) => nodes.flatMap((node) => {
+        const span = spanOf(node);
         switch (node.type) {
             case "heading":
-                return withImages({ kind: "heading", level: node.depth, inlines: trimmed(inlinesOf(node.children)) });
+                return withImages({ kind: "heading", level: node.depth, inlines: trimmed(inlinesOf(node.children)) }, span);
             case "paragraph":
-                return withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(node.children)) });
+                return withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(node.children)) }, span);
             case "code":
-                return [{ kind: "code", ...(node.lang ? { language: node.lang } : {}), text: node.value }];
+                return [{ block: { kind: "code", ...(node.lang ? { language: node.lang } : {}), text: node.value }, ...span }];
             case "blockquote":
-                return node.children.flatMap((child) => child.type === "paragraph" || child.type === "heading"
-                    ? withImages({ kind: "quote", inlines: trimmed(inlinesOf(child.children)) })
-                    : blocks([child], depth));
+                return node.children
+                    .flatMap((child) => child.type === "paragraph" || child.type === "heading"
+                    ? withImages({ kind: "quote", inlines: trimmed(inlinesOf(child.children)) }, span)
+                    : blocks([child], depth))
+                    .map((placed) => ({ ...placed, ...span }));
             case "thematicBreak":
-                return [{ kind: "rule" }];
+                return [{ block: { kind: "rule" }, ...span }];
             case "table": {
                 const [head, ...rows] = node.children.map((row) => row.children.map((cell) => trimmed(inlinesOf(cell.children))));
-                return [{ kind: "table", header: head ?? [], rows }];
+                return [{ block: { kind: "table", header: head ?? [], rows }, ...span }];
             }
             case "list":
                 return node.children.flatMap((item) => {
@@ -100,23 +104,31 @@ export const markdownBlocks = async (markdown) => {
                         inlines: trimmed(first && first.type === "paragraph" ? inlinesOf(first.children) : []),
                     };
                     const tail = first && first.type !== "paragraph" ? [first, ...rest] : rest;
+                    const own = {
+                        start: spanOf(item).start,
+                        end: first?.type === "paragraph" ? spanOf(first).end : spanOf(item).start,
+                    };
+                    const marker = /^([-+*]|\d{1,9}[.)])( {1,4}|(?=\n)|$)/.exec(markdown.slice(own.start))?.[0].length ?? 2;
+                    const column = (item.position?.start.column ?? 1) - 1 + marker;
                     return [
-                        ...withImages(head),
+                        ...withImages(head, own).map((placed) => ({ ...placed, column })),
                         ...tail.flatMap((child) => child.type === "list"
                             ? blocks([child], depth + 1)
                             : child.type === "paragraph"
-                                ? withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(child.children)) })
+                                ? withImages({ kind: "paragraph", inlines: trimmed(inlinesOf(child.children)) }, spanOf(child))
                                 : blocks([child], depth)),
                     ];
                 });
             case "html":
-                return [{ kind: "paragraph", inlines: [{ text: node.value }] }];
+                return [{ block: { kind: "paragraph", inlines: [{ text: node.value }] }, ...span }];
             case "definition":
             case "footnoteDefinition":
             case "yaml":
                 return [];
             default:
-                return "children" in node ? withImages({ kind: "paragraph", inlines: trimmed(textOf(node)) }) : [];
+                return "children" in node
+                    ? withImages({ kind: "paragraph", inlines: trimmed(textOf(node)) }, span)
+                    : [];
         }
     });
     return blocks(tree.children);

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

@@ -11,17 +11,40 @@ export interface Pushed<S> {
     /** What the provider reads back after its own write; the next push compares the remote against it. */
     snapshot: S;
 }
+/** Which side a stretch both sides changed keeps: the local file, the remote, or both one after the other. */
+export type Keep = "local" | "remote" | "both";
+/** One stretch both sides changed, as text a person can compare. */
+export interface ConflictPart {
+    base: string;
+    local: string;
+    remote: string;
+}
+/** The remote's last change, when the provider can tell. */
+export interface RemoteChange {
+    changedAt?: string;
+    changedBy?: string;
+}
 /**
- * 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.
+ * What a sync found before writing. `local` is the file's new content when the remote changed it; `write` runs
+ * after it and reaches the remote only when `remote` is true, so a conflict or a file with nothing to change
+ * never counts as a write.
  */
 export type Prepared<S> = {
     conflict: string;
+    parts?: ConflictPart[];
+    remote?: RemoteChange;
 } | {
     missing: true;
 } | {
     unchanged: Pushed<S>;
 } | {
+    local?: string;
+    /**
+     * Recorded once `local` is written and before the remote write: both sides as the remote is now. If the
+     * remote write then fails, the next run sends the file's changes against it and settles nothing twice.
+     */
+    afterLocal?: S;
+    remote: boolean;
     write(): Promise<Pushed<S>>;
 };
 /**
@@ -47,12 +70,15 @@ export interface DocumentTarget<S> {
         operationId: string;
         signal?: AbortSignal;
     }): Promise<Pushed<S>>;
-    /** Reads the remote and compares it with `recorded`; a conflict instead of a write unless `force`. */
+    /**
+     * Reads the remote and merges it with the local file against `recorded`, what the last sync left on both sides.
+     * A stretch both sides changed is a conflict unless `keep` says which side wins.
+     */
     prepare(input: {
         id: string;
         file: LocalDocument;
         recorded: S;
-        force: boolean;
+        keep?: Keep;
         signal?: AbortSignal;
     }): Promise<Prepared<S>>;
 }

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

@@ -1,4 +1,5 @@
 import { type Block } from "../../documents/blocks.js";
+import type { Keep } from "../../documents/push-model.js";
 /** `base[from, to)` is replaced by `blocks`; an empty range is an insert, an empty `blocks` a delete. */
 export interface BlockHunk {
     from: number;
@@ -6,19 +7,27 @@ export interface BlockHunk {
     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 = {
+export declare const diffBlocks: (base: Block[], next: Block[], keyOf?: (block: Block) => string) => BlockHunk[];
+/** A stretch both sides changed differently: the blocks it held at the last sync and on each side now. */
+export interface BlockConflict {
+    base: Block[];
+    local: Block[];
+    remote: Block[];
+}
+export type Merged = {
     status: "clean";
     blocks: Block[];
-    ticksKept: number;
+    conflicts: BlockConflict[];
 } | {
     status: "conflict";
+    conflicts: BlockConflict[];
+} | {
+    status: "unaligned";
 };
 /**
- * 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.
+ * Three-way merge of a document changed on both sides since the last sync. `baseLocal` and `baseRemote` are each
+ * side as the last sync left it; they hold the same blocks, though a tick may differ. Blocks line up by their
+ * shape, so a checklist tick never collides with a text edit: each tick follows the side that changed it, the
+ * remote when neither did. A stretch both sides changed differently is a conflict, settled by `keep` when given.
  */
-export declare const reconcileBlocks: (recorded: Block[], current: Block[], local: Block[], lastLocal: Block[]) => Reconciled;
+export declare const mergeBlocks: (baseLocal: Block[], baseRemote: Block[], local: Block[], remote: Block[], keep?: Keep) => Merged;

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

@@ -48,11 +48,11 @@ const matches = (a, b, keyOf) => {
     return pairs;
 };
 /** The edits that turn `base` into `next`, leaving every unchanged block in place. */
-export const diffBlocks = (base, next) => {
+export const diffBlocks = (base, next, keyOf = blockKey) => {
     const hunks = [];
     let a = 0;
     let b = 0;
-    for (const [i, j] of [...matches(base, next, blockKey), [base.length, next.length]]) {
+    for (const [i, j] of [...matches(base, next, keyOf), [base.length, next.length]]) {
         if (i > a || j > b)
             hunks.push({ from: a, to: i, blocks: next.slice(b, j) });
         a = i + 1;
@@ -61,31 +61,106 @@ export const diffBlocks = (base, next) => {
     return hunks;
 };
 const isCheck = (block) => block?.kind === "item" && block.list === "check";
+const sameKeys = (a, b) => a.length === b.length && a.every((block, index) => blockKey(block) === blockKey(b[index]));
+/** Two hunks touch the same stretch: their ranges overlap, both insert at one point, or one inserts inside the other. */
+const touches = (a, b) => Math.max(a.from, b.from) < Math.min(a.to, b.to) ||
+    a.from === b.from ||
+    (a.from === a.to && b.from < a.from && a.from < b.to) ||
+    (b.from === b.to && a.from < b.from && b.from < a.to);
+const applied = (base, from, to, hunks) => {
+    let out = [];
+    let at = from;
+    for (const hunk of hunks) {
+        out = out.concat(base.slice(at, hunk.from), hunk.blocks);
+        at = hunk.to;
+    }
+    return out.concat(base.slice(at, to));
+};
 /**
- * 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.
+ * Three-way merge of a document changed on both sides since the last sync. `baseLocal` and `baseRemote` are each
+ * side as the last sync left it; they hold the same blocks, though a tick may differ. Blocks line up by their
+ * shape, so a checklist tick never collides with a text edit: each tick follows the side that changed it, the
+ * remote when neither did. A stretch both sides changed differently is a conflict, settled by `keep` when given.
  */
-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))
+export const mergeBlocks = (baseLocal, baseRemote, local, remote, keep) => {
+    if (baseLocal.length !== baseRemote.length ||
+        baseLocal.some((block, index) => blockShape(block) !== blockShape(baseRemote[index])))
+        return { status: "unaligned" };
+    const tagged = [
+        ...diffBlocks(baseLocal, local, blockShape).map((hunk) => ({ ...hunk, side: "local" })),
+        ...diffBlocks(baseRemote, remote, blockShape).map((hunk) => ({ ...hunk, side: "remote" })),
+    ].sort((a, b) => a.from - b.from || a.to - b.to);
+    const clusters = [];
+    for (const hunk of tagged) {
+        const last = clusters.at(-1);
+        if (last?.some((other) => touches(other, hunk)))
+            last.push(hunk);
+        else
+            clusters.push([hunk]);
+    }
+    const unchangedLocal = new Map(matches(baseLocal, local, blockShape));
+    const unchangedRemote = new Map(matches(baseRemote, remote, blockShape));
+    /** A base block neither side replaced: it keeps its place and takes the tick of the side that changed it. */
+    const kept = (index) => {
+        const base = baseLocal[index];
+        const mine = local[unchangedLocal.get(index) ?? -1];
+        const theirs = remote[unchangedRemote.get(index) ?? -1];
+        if (!isCheck(base) || !isCheck(mine) || !isCheck(theirs))
+            return mine ?? theirs ?? base;
+        const changedHere = Boolean(mine.checked) !== Boolean(base.checked);
+        return { ...mine, checked: changedHere ? Boolean(mine.checked) : Boolean(theirs.checked) };
+    };
+    /** One side's replacement, with the other side's tick carried onto items it edited in place. */
+    const oneSide = (hunk) => {
+        if (hunk.to - hunk.from !== hunk.blocks.length)
+            return hunk.blocks;
+        return hunk.blocks.map((block, offset) => {
+            const index = hunk.from + offset;
+            const base = (hunk.side === "local" ? baseRemote : baseLocal)[index];
+            const other = hunk.side === "local" ? remote[unchangedRemote.get(index) ?? -1] : local[unchangedLocal.get(index) ?? -1];
+            const own = (hunk.side === "local" ? baseLocal : baseRemote)[index];
+            if (!isCheck(block) || !isCheck(base) || !isCheck(other) || !isCheck(own))
+                return block;
+            if (Boolean(block.checked) !== Boolean(own.checked) || Boolean(other.checked) === Boolean(base.checked))
+                return block;
+            return { ...block, checked: Boolean(other.checked) };
+        });
+    };
+    let blocks = [];
+    const conflicts = [];
+    let at = 0;
+    for (const cluster of clusters) {
+        const from = cluster.reduce((low, hunk) => Math.min(low, hunk.from), Number.POSITIVE_INFINITY);
+        const to = cluster.reduce((high, hunk) => Math.max(high, hunk.to), 0);
+        for (; at < from; at++)
+            blocks.push(kept(at));
+        at = to;
+        const mine = cluster.filter((hunk) => hunk.side === "local");
+        const theirs = cluster.filter((hunk) => hunk.side === "remote");
+        if (!theirs.length || !mine.length) {
+            let cursor = from;
+            for (const hunk of cluster) {
+                for (; cursor < hunk.from; cursor++)
+                    blocks.push(kept(cursor));
+                blocks = blocks.concat(oneSide(hunk));
+                cursor = hunk.to;
+            }
+            for (; cursor < to; cursor++)
+                blocks.push(kept(cursor));
+            continue;
+        }
+        const localSide = applied(baseLocal, from, to, mine);
+        const remoteSide = applied(baseRemote, from, to, theirs);
+        if (sameKeys(localSide, remoteSide)) {
+            blocks = blocks.concat(localSide);
             continue;
-        if (Boolean(mine.checked) === Boolean(last.checked) && Boolean(remote.checked) !== Boolean(mine.checked)) {
-            mine.checked = Boolean(remote.checked);
-            ticksKept++;
         }
+        conflicts.push({ base: baseLocal.slice(from, to), local: localSide, remote: remoteSide });
+        blocks = blocks.concat(keep === "remote" ? [] : localSide, keep === "local" ? [] : remoteSide);
     }
-    return { status: "clean", blocks, ticksKept };
+    for (; at < baseLocal.length; at++)
+        blocks.push(kept(at));
+    if (conflicts.length && !keep)
+        return { status: "conflict", conflicts };
+    return { status: "clean", blocks, conflicts };
 };

package/dist/services/documents/markdown-splice.d.ts

@@ -0,0 +1,15 @@
+import { type Block, type Inline } from "../../documents/blocks.js";
+/** Inline runs as Markdown; a run of one link is written as one link. `indent` continues a line after a hard break. */
+export declare const inlineMarkdown: (inlines: Inline[], indent?: string) => string;
+/**
+ * Blocks as Markdown, one after another. `columns` holds, per depth, where the text of the list item before
+ * the first block starts, so a nested item lines up under a parent written elsewhere in the file.
+ */
+export declare const blocksMarkdown: (blocks: Block[], columns?: number[]) => string;
+/**
+ * The Markdown file `text` changed so that it reads as `next`, touching only the lines of blocks that differ:
+ * everything else stays byte for byte, line endings and a byte-order mark included. `normalize` maps the file's
+ * blocks one to one onto the form `next` is in. Undefined when the result would not read back as `next`, which
+ * a caller reports instead of writing.
+ */
+export declare const spliceMarkdown: (text: string, next: Block[], normalize?: (blocks: Block[]) => Block[]) => Promise<string | undefined>;

package/dist/services/documents/markdown-splice.js

@@ -0,0 +1,206 @@
+import { blockKey, blockShape, normalizeInlines } from "../../documents/blocks.js";
+import { markdownBlocks, placedMarkdownBlocks } from "../../documents/markdown-blocks.js";
+import { diffBlocks } from "./block-diff.js";
+const escapeText = (text) => text.replace(/[\\`*_[\]<>~|]/g, "\\$&");
+const codeSpan = (text) => {
+    const longest = (text.match(/`+/g) ?? []).reduce((most, run) => Math.max(most, run.length), 0);
+    const fence = "`".repeat(longest + 1);
+    const pad = text.startsWith("`") || text.endsWith("`") ? " " : "";
+    return `${fence}${pad}${text}${pad}${fence}`;
+};
+const linkTarget = (url) => (/[\s()<>]/.test(url) ? `<${url.replace(/[<>]/g, encodeURIComponent)}>` : url);
+const styled = (inline) => {
+    const text = inline.code ? codeSpan(inline.text) : escapeText(inline.text);
+    // A delimiter next to a space does not open or close emphasis, so spaces stay outside the marks.
+    const [, lead = "", core = "", trail = ""] = /^(\s*)([\s\S]*?)(\s*)$/.exec(text) ?? [];
+    if (!core)
+        return text;
+    let marked = core;
+    if (inline.strike)
+        marked = `~~${marked}~~`;
+    if (inline.italic)
+        marked = `*${marked}*`;
+    if (inline.bold)
+        marked = `**${marked}**`;
+    return `${lead}${marked}${trail}`;
+};
+/** Inline runs as Markdown; a run of one link is written as one link. `indent` continues a line after a hard break. */
+export const inlineMarkdown = (inlines, indent = "") => {
+    const runs = normalizeInlines(inlines);
+    let out = "";
+    for (let at = 0; at < runs.length;) {
+        const link = runs[at]?.link;
+        let body = "";
+        for (; at < runs.length && runs[at]?.link === link; at++)
+            body += styled({ ...runs[at], link: undefined });
+        out += link ? `[${body}](${linkTarget(link)})` : body;
+    }
+    return out
+        .replace(/^(#{1,6}\s|[-+*>]\s|[=-]+\s*$)/, "\\$1")
+        .replace(/^(\d{1,9})([.)]\s)/, "$1\\$2")
+        .replaceAll("\n", `\\\n${indent}`);
+};
+const MARKERS = { bullet: "- ", number: "1. ", check: "- " };
+/**
+ * Blocks as Markdown, one after another. `columns` holds, per depth, where the text of the list item before
+ * the first block starts, so a nested item lines up under a parent written elsewhere in the file.
+ */
+export const blocksMarkdown = (blocks, columns = []) => {
+    const lines = [];
+    const depths = [...columns];
+    let previous;
+    for (const block of blocks) {
+        if (previous)
+            lines.push(previous.kind === "item" && block.kind === "item" ? "\n" : "\n\n");
+        previous = block;
+        switch (block.kind) {
+            case "heading":
+                lines.push(`${"#".repeat(block.level)} ${inlineMarkdown(block.inlines)}`);
+                break;
+            case "paragraph":
+                lines.push(inlineMarkdown(block.inlines));
+                break;
+            case "quote":
+                lines.push(`> ${inlineMarkdown(block.inlines, "> ")}`);
+                break;
+            case "code": {
+                const longest = (block.text.match(/^`+/gm) ?? []).reduce((most, run) => Math.max(most, run.length), 2);
+                const fence = "`".repeat(longest + 1);
+                lines.push(`${fence}${block.language ?? ""}\n${block.text}\n${fence}`);
+                break;
+            }
+            case "rule":
+                lines.push("---");
+                break;
+            case "image":
+                lines.push(`![${escapeText(block.alt)}](${linkTarget(block.url)})`);
+                break;
+            case "table": {
+                const width = block.rows.reduce((most, row) => Math.max(most, row.length), Math.max(block.header.length, 1));
+                const row = (cells) => `| ${Array.from({ length: width }, (_, index) => inlineMarkdown(cells[index] ?? []).replaceAll("\\\n", " ") || " ").join(" | ")} |`;
+                lines.push([row(block.header), `|${" --- |".repeat(width)}`, ...block.rows.map(row)].join("\n"));
+                break;
+            }
+            case "item": {
+                const indent = block.depth === 0 ? 0 : (depths[block.depth - 1] ?? block.depth * 2);
+                const marker = MARKERS[block.list];
+                const box = block.list === "check" ? (block.checked ? "[x] " : "[ ] ") : "";
+                const column = indent + marker.length;
+                depths.length = block.depth;
+                depths[block.depth] = column;
+                lines.push(`${" ".repeat(indent)}${marker}${box}${inlineMarkdown(block.inlines, " ".repeat(column))}`);
+                break;
+            }
+        }
+    }
+    return lines.join("");
+};
+const BLANK_BETWEEN = (a, b) => Boolean(a && b) && !(a?.kind === "item" && b?.kind === "item");
+/**
+ * The Markdown file `text` changed so that it reads as `next`, touching only the lines of blocks that differ:
+ * everything else stays byte for byte, line endings and a byte-order mark included. `normalize` maps the file's
+ * blocks one to one onto the form `next` is in. Undefined when the result would not read back as `next`, which
+ * a caller reports instead of writing.
+ */
+export const spliceMarkdown = async (text, next, normalize = (blocks) => blocks) => {
+    const bom = text.startsWith("") ? "" : "";
+    const crlf = text.includes("\r\n");
+    let body = (bom ? text.slice(1) : text).replace(/\r\n/g, "\n");
+    const placed = await placedMarkdownBlocks(body);
+    const current = normalize(placed.map((item) => item.block));
+    if (current.length !== placed.length)
+        return undefined;
+    // A run of blocks replaced one for one is spliced block by block, so a tick next to an edit still flips in place.
+    const single = diffBlocks(current, next).flatMap((hunk) => hunk.to - hunk.from === hunk.blocks.length
+        ? hunk.blocks.map((block, offset) => ({ from: hunk.from + offset, to: hunk.from + offset + 1, blocks: [block] }))
+        : [hunk]);
+    const hunks = grouped(single, placed, current);
+    if (!hunks.length)
+        return text;
+    const lineStart = (offset) => body.lastIndexOf("\n", offset - 1) + 1;
+    for (const [index, hunk] of [...hunks.entries()].reverse()) {
+        const following = hunks[index + 1];
+        const toggled = tick(body, hunk, placed, current);
+        if (toggled !== undefined) {
+            body = toggled;
+            continue;
+        }
+        if (body && !body.endsWith("\n"))
+            body += "\n";
+        const cutStart = hunk.from < placed.length ? lineStart(placed[hunk.from].start) : body.length;
+        const cutEnd = hunk.to < placed.length ? lineStart(placed[hunk.to].start) : body.length;
+        const before = current[hunk.from - 1];
+        const after = following?.from === hunk.to ? (following.blocks[0] ?? current[following.to]) : current[hunk.to];
+        let head = body.slice(0, cutStart);
+        const first = hunk.blocks[0] ?? after;
+        if (BLANK_BETWEEN(before, first) && head && !head.endsWith("\n\n"))
+            head += "\n";
+        let insert = "";
+        if (hunk.blocks.length) {
+            insert = `${blocksMarkdown(hunk.blocks, columnsBefore(placed, hunk.from))}\n`;
+            if (BLANK_BETWEEN(hunk.blocks.at(-1), after))
+                insert += "\n";
+        }
+        body = head + insert + body.slice(cutEnd);
+    }
+    const reread = normalize(await markdownBlocks(body));
+    if (reread.length !== next.length ||
+        reread.some((block, index) => blockKey(block) !== blockKey(next[index])))
+        return undefined;
+    return bom + (crlf ? body.replace(/\n/g, "\r\n") : body);
+};
+/** A hunk that cuts through blocks sharing one source stretch grows to take all of them. */
+const grouped = (hunks, placed, current) => {
+    const shares = (index) => index > 0 && index < placed.length && placed[index]?.start === placed[index - 1]?.start;
+    const out = [];
+    for (const hunk of hunks) {
+        let { from, to } = hunk;
+        while (shares(from))
+            from--;
+        while (shares(to))
+            to++;
+        const blocks = [...current.slice(from, hunk.from), ...hunk.blocks, ...current.slice(hunk.to, to)];
+        const last = out.at(-1);
+        if (last && from < last.to) {
+            last.blocks = [...last.blocks, ...current.slice(last.to, from), ...blocks.slice(Math.max(0, last.to - from))];
+            last.to = Math.max(last.to, to);
+        }
+        else
+            out.push({ from, to, blocks });
+    }
+    return out;
+};
+/** Checklist items whose only change is their tick get their boxes flipped in place. */
+const tick = (body, hunk, placed, current) => {
+    if (hunk.to - hunk.from !== hunk.blocks.length)
+        return undefined;
+    let out = body;
+    for (let offset = hunk.blocks.length - 1; offset >= 0; offset--) {
+        const before = current[hunk.from + offset];
+        const after = hunk.blocks[offset];
+        if (before?.kind !== "item" || after?.kind !== "item" || blockShape(before) !== blockShape(after))
+            return undefined;
+        const { start, end } = placed[hunk.from + offset];
+        const line = out.slice(start, end);
+        const box = /^(\S+\s+)\[[ xX]\]/.exec(line);
+        if (!box)
+            return undefined;
+        out = `${out.slice(0, start)}${box[1]}[${after.checked ? "x" : " "}]${line.slice(box[0].length)}${out.slice(end)}`;
+    }
+    return out;
+};
+/** Where the text of the nearest list item at each depth before `index` starts. */
+const columnsBefore = (placed, index) => {
+    const columns = [];
+    let lowest = Number.POSITIVE_INFINITY;
+    for (let at = index - 1; at >= 0 && lowest > 0; at--) {
+        const item = placed[at];
+        if (item.block.kind !== "item")
+            break;
+        if (item.block.depth < lowest) {
+            lowest = item.block.depth;
+            columns[lowest] = item.column ?? 2 * (lowest + 1);
+        }
+    }
+    return columns;
+};

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

@@ -1,5 +1,5 @@
 import { CliError } from "@wirecat/cli-base";
-import type { DocumentTarget, LocalDocument, PushPlan, PushState, PushStatePort } from "../../documents/push-model.js";
+import type { ConflictPart, DocumentTarget, Keep, LocalDocument, PushPlan, PushState, PushStatePort } from "../../documents/push-model.js";
 export interface PushOptions<S> {
     /** Absolute path of the local folder being mirrored. */
     root: string;
@@ -8,7 +8,10 @@ export interface PushOptions<S> {
     target: DocumentTarget<S>;
     state: PushStatePort<S>;
     principal: string;
-    force?: boolean;
+    /** Settles stretches both sides changed; without it they are conflicts. */
+    keep?: Keep;
+    /** Creates again a remote file that was deleted. */
+    recreate?: boolean;
     dryRun?: boolean;
     /** Runs one remote write behind the provider's permission checks and write journal. */
     guard<T>(attempt: {
@@ -23,15 +26,22 @@ export interface PushOptions<S> {
     maxFiles?: number;
     now?(): number;
 }
+export interface PushConflict {
+    path: string;
+    url: string;
+    reason: string;
+    parts?: ConflictPart[];
+    localChangedAt?: string;
+    remoteChangedAt?: string;
+    remoteChangedBy?: string;
+}
 export interface PushResult {
     created: string[];
     updated: string[];
+    /** Local files rewritten with changes made on the remote. */
+    pulled: string[];
     unchanged: number;
-    conflicts: {
-        path: string;
-        url: string;
-        reason: string;
-    }[];
+    conflicts: PushConflict[];
     missing: string[];
     orphans: {
         path: string;

package/dist/services/documents/push.js

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { readdir } from "node:fs/promises";
-import { join, posix } from "node:path";
+import { chmod, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, 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) => {
@@ -11,6 +11,27 @@ const hashFile = (path) => new Promise((done, fail) => {
         .on("error", fail)
         .on("end", () => done(hash.digest("hex")));
 });
+const hashText = (text) => createHash("sha256").update(text).digest("hex");
+/**
+ * Replaces the file through a temporary file beside it, keeping its mode. Undefined, and nothing written, when
+ * the file no longer has `hash`: someone saved it during the sync.
+ */
+const replaceLocal = async (file, content) => {
+    const temp = join(dirname(file.absolute), `.${basename(file.absolute)}.${randomUUID().slice(0, 8)}.tmp`);
+    const { mode } = await stat(file.absolute);
+    await writeFile(temp, content, { flag: "wx" });
+    try {
+        // A mode passed to the write goes through the umask; set it after, so a group-writable file stays one.
+        await chmod(temp, mode & 0o777);
+        if ((await hashFile(file.absolute)) !== file.hash)
+            return undefined;
+        await rename(temp, file.absolute);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+    return hashText(content);
+};
 /** 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 = [];
@@ -70,7 +91,7 @@ const originOf = (principal, root, folder, path) => createHash("sha256")
     .digest("hex")
     .slice(0, 32);
 export const pushDocuments = async (options) => {
-    const { root, folder, target, principal, force = false, signal } = options;
+    const { root, folder, target, principal, keep, recreate = false, signal } = options;
     const now = options.now ?? Date.now;
     if (signal?.aborted)
         throw new CliError("cancelled", "push was cancelled");
@@ -96,7 +117,8 @@ export const pushDocuments = async (options) => {
     const result = {
         created: [],
         updated: [],
-        unchanged: plan.unchanged.length,
+        pulled: [],
+        unchanged: 0,
         conflicts: [],
         missing: [],
         orphans: plan.orphans.map((path) => ({ path, url: state.entries[path]?.url ?? "" })),
@@ -150,9 +172,11 @@ export const pushDocuments = async (options) => {
         save();
         result.created.push(file.path);
     };
+    // A file unchanged here may have changed remotely, so every mirrored file is read back.
     const work = [
         ...plan.create.map((file) => ({ file, create: true })),
         ...plan.update.map((file) => ({ file, create: false })),
+        ...plan.unchanged.map((file) => ({ file, create: false })),
     ];
     for (const job of work.sort((a, b) => a.file.path.localeCompare(b.file.path))) {
         if (signal?.aborted) {
@@ -170,15 +194,24 @@ export const pushDocuments = async (options) => {
                 id: entry.id,
                 file,
                 recorded: entry.snapshot,
-                force,
+                ...(keep ? { keep } : {}),
                 ...(signal ? { signal } : {}),
             });
             if ("conflict" in prepared) {
-                result.conflicts.push({ path: file.path, url: entry.url, reason: prepared.conflict });
+                const { mtime } = await stat(file.absolute);
+                result.conflicts.push({
+                    path: file.path,
+                    url: entry.url,
+                    reason: prepared.conflict,
+                    ...(prepared.parts ? { parts: prepared.parts } : {}),
+                    localChangedAt: mtime.toISOString(),
+                    ...(prepared.remote?.changedAt ? { remoteChangedAt: prepared.remote.changedAt } : {}),
+                    ...(prepared.remote?.changedBy ? { remoteChangedBy: prepared.remote.changedBy } : {}),
+                });
                 continue;
             }
             if ("missing" in prepared) {
-                if (!force) {
+                if (!recreate) {
                     result.missing.push(file.path);
                     continue;
                 }
@@ -187,20 +220,41 @@ export const pushDocuments = async (options) => {
                 continue;
             }
             let pushed;
+            let hash = file.hash;
             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);
+                // The local file goes first: if the remote write then fails, the next sync finds the same change on
+                // both sides and merges it once.
+                if (prepared.local !== undefined) {
+                    options.assertHeld();
+                    const written = await replaceLocal(file, prepared.local);
+                    if (!written) {
+                        result.conflicts.push({ path: file.path, url: entry.url, reason: "the local file changed during the sync" });
+                        continue;
+                    }
+                    hash = written;
+                    result.pulled.push(file.path);
+                    if (prepared.remote && prepared.afterLocal !== undefined) {
+                        state.entries[file.path] = { ...entry, snapshot: prepared.afterLocal, hash };
+                        save();
+                    }
+                }
+                if (prepared.remote) {
+                    const operationId = options.operationId();
+                    options.assertHeld();
+                    pushed = await options.guard({ action: "update", path: file.path, operationId }, () => prepared.write());
+                    result.updated.push(file.path);
+                }
+                else
+                    pushed = await prepared.write();
             }
             state.entries[file.path] = {
                 ...pushed,
                 kind: file.kind,
-                hash: file.hash,
+                hash,
                 pushedAt: new Date(now()).toISOString(),
             };
             save();

package/dist/store/sqlite/emails.d.ts

@@ -151,7 +151,7 @@ export interface EmailFilter extends MailFilter {
     mailbox?: string;
     /** On the received time, or the sent time when that is unknown: IMAP's SINCE counts by the received day. */
     since?: number;
-    /** Exclusive. */
+    /** Exclusive. `momentOf` and `dateWindow` with `end` give the last millisecond of a day, an inclusive end: add 1. */
     until?: number;
     /** Only emails with an attachment whose text extraction failed with one of these errors. */
     attachmentErrors?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.385.0",
+  "version": "0.387.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",