@wirecat/cli-core 0.382.0 → 0.384.0

package/dist/services/admin-statistics.d.ts

@@ -2,6 +2,7 @@ import type { AdminOptions, AdminReport } from "../domain/admin-statistics.js";
 import type { AdminStoreResult, MessageStore } from "../store/store.js";
 import type { ServiceDeps } from "./deps.js";
 import type { SearchQuery } from "./messages.js";
+import { type DateWindow } from "./moment.js";
 import { type RankingSelection } from "./rankings-selection.js";
 export type AdminQuery = SearchQuery & {
     answerers?: string[];
@@ -28,6 +29,8 @@ export interface AdminSelection {
 }
 export interface AdminFound extends AdminStoreResult {
     report: AdminReport;
+    /** How the typed join dates were read, for the answer's `meta`. */
+    timeMeta?: DateWindow["meta"];
     detectorVersion: 1;
     items: (AdminStoreResult["items"][number] & {
         drilldown: {

package/dist/services/admin-statistics.js

@@ -2,7 +2,7 @@ import { CliError, singleLine } from "@wirecat/cli-base";
 import { parseLocator } from "../domain/locator.js";
 import { isId, pickPerson } from "../resolve.js";
 import { prepareLucene, stemExecution } from "./messages-search.js";
-import { momentOf } from "./moment.js";
+import { dateWindow } from "./moment.js";
 import { rankingSelection, readRankingSelection } from "./rankings-selection.js";
 import { searchRecordOf } from "./search-record.js";
 function invalid(message) {
@@ -205,6 +205,12 @@ export const adminStatisticsService = (deps) => ({
         if (pinned &&
             (query.source || query.ast || query.exact || (query.timezone && query.timezone !== prepared.timezone)))
             invalid("a saved report keeps its resolved query, accounts and timezone");
+        const window = dateWindow({
+            ...(query.sinceTime ? { sinceTime: query.sinceTime } : {}),
+            ...(query.untilTime ? { untilTime: query.untilTime } : {}),
+            zone: prepared.timezone,
+            now: cutoff,
+        });
         const options = {
             report,
             cutoff,
@@ -212,12 +218,8 @@ export const adminStatisticsService = (deps) => ({
                 ? pinned.options.olderThan
                 : duration(query.olderThan ?? "24h", "--older-than"),
             within: query.within === undefined && pinned ? pinned.options.within : duration(query.within ?? "7d", "--within"),
-            joinSince: query.sinceTime
-                ? momentOf(query.sinceTime, "--since-time", cutoff, { zone: prepared.timezone })
-                : (pinned?.options.joinSince ?? cutoff - 30 * 86_400_000),
-            joinUntil: query.untilTime
-                ? momentOf(query.untilTime, "--until-time", cutoff, { zone: prepared.timezone, end: true })
-                : (pinned?.options.joinUntil ?? cutoff),
+            joinSince: window.since ?? pinned?.options.joinSince ?? cutoff - 30 * 86_400_000,
+            joinUntil: window.until ?? pinned?.options.joinUntil ?? cutoff,
             minViews: count(query.minViews ?? pinned?.options.minViews ?? 1, "--min-views"),
             maxReplies: count(query.maxReplies ?? pinned?.options.maxReplies ?? 0, "--max-replies"),
             answerers: query.answerers === undefined && pinned
@@ -252,6 +254,7 @@ export const adminStatisticsService = (deps) => ({
         return {
             ...result,
             report,
+            timeMeta: window.meta,
             detectorVersion: 1,
             items: result.items.map((original) => {
                 const identityKnown = known.has(JSON.stringify([original.account.provider, original.account.account, original.id]));

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/dist/services/retention.d.ts

@@ -75,6 +75,13 @@ export declare const retentionService: (deps: ServiceDeps) => {
         }[];
         account: import("../store/types.js").AccountKey;
         report: "retention";
+        timeMeta: {
+            timezone?: string;
+            window?: {
+                since?: string;
+                until?: string;
+            };
+        };
     }>;
     evidence: (target: "messages" | "contacts", reference: string, selection: unknown, query: {
         component: string;

package/dist/services/retention.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { timezoneOf } from "@wirecat/cli-base/query";
 import { storedChatId } from "./message-resolution.js";
-import { momentOf } from "./moment.js";
+import { dateWindow } from "./moment.js";
 export const observationDuration = (text, flag) => {
     const match = /^(\d+(?:\.\d+)?)([smhdw])$/.exec(text);
     const units = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
@@ -14,11 +14,15 @@ export const retentionService = (deps) => ({
     report: async (chat, query = {}) => {
         const cutoff = Date.now();
         const zone = timezoneOf(query.timezone);
+        const window = dateWindow({
+            ...(query.sinceTime === undefined ? {} : { sinceTime: query.sinceTime }),
+            ...(query.untilTime === undefined ? {} : { untilTime: query.untilTime }),
+            zone,
+            now: cutoff,
+        });
         const options = {
-            since: query.sinceTime === undefined
-                ? cutoff - 90 * 86_400_000
-                : momentOf(query.sinceTime, "--since-time", cutoff, { zone }),
-            until: query.untilTime === undefined ? cutoff : momentOf(query.untilTime, "--until-time", cutoff, { zone, end: true }),
+            since: window.since ?? cutoff - 90 * 86_400_000,
+            until: window.until ?? cutoff,
             cutoff,
             checkpoints: (query.checkpoints ?? "1d,7d,30d")
                 .split(",")
@@ -46,6 +50,7 @@ export const retentionService = (deps) => ({
             })),
             account,
             report: "retention",
+            timeMeta: window.meta,
         };
     },
     evidence: async (target, reference, selection, query) => {

package/package.json

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