@wirecat/cli-core 0.401.0 → 0.403.0

package/dist/cli/setup-answers.d.ts

@@ -0,0 +1,24 @@
+import type { Level } from "../sends/permissions.js";
+/** "allow" leaves every profile as its own configuration says. */
+export declare const PERMISSION_ANSWERS: readonly ["readonly", "ask", "allow"];
+export type PermissionAnswer = (typeof PERMISSION_ANSWERS)[number];
+/**
+ * The first-run answers every WireCat CLI shares. Languages live in the store (`search_stemmers`), so only the
+ * fact that they were asked is kept here.
+ */
+export interface SetupAnswers {
+    languages?: true;
+    tools?: true;
+    permissions?: PermissionAnswer;
+}
+export declare const QUESTIONS: readonly ["languages", "tools", "permissions"];
+export type Question = (typeof QUESTIONS)[number];
+export declare const readSetupAnswers: (path: string) => SetupAnswers;
+export declare const unanswered: (answers: SetupAnswers) => Question[];
+/** A section written wrongly is replaced; a file that is not JSON at all still refuses, naming itself. */
+export declare const writeSetupAnswers: (path: string, answers: SetupAnswers) => void;
+/**
+ * The level no command of any WireCat tool goes above, or `undefined` when the owner chose to leave them as they
+ * are. A file that cannot be read keeps everything read-only: reads still work, and `setup` writes it again.
+ */
+export declare const permissionCeiling: (path: string) => Level | undefined;

package/dist/cli/setup-answers.js

@@ -0,0 +1,47 @@
+import { CliError } from "@wirecat/cli-base";
+import { readSharedSection, writeSharedSection } from "../store/shared-config.js";
+/** "allow" leaves every profile as its own configuration says. */
+export const PERMISSION_ANSWERS = ["readonly", "ask", "allow"];
+export const QUESTIONS = ["languages", "tools", "permissions"];
+const SECTION = "setup";
+export const readSetupAnswers = (path) => {
+    const section = readSharedSection(path, SECTION);
+    if (section === undefined)
+        return {};
+    const answers = section;
+    if (section === null ||
+        typeof section !== "object" ||
+        Array.isArray(section) ||
+        (answers.languages !== undefined && answers.languages !== true) ||
+        (answers.tools !== undefined && answers.tools !== true) ||
+        (answers.permissions !== undefined && !PERMISSION_ANSWERS.includes(answers.permissions)))
+        throw new CliError("configuration_error", `${path}: ${SECTION} holds what setup asked — languages: true, tools: true, permissions: ${PERMISSION_ANSWERS.join(" | ")}`);
+    return answers;
+};
+export const unanswered = (answers) => QUESTIONS.filter((question) => answers[question] === undefined);
+/** A section written wrongly is replaced; a file that is not JSON at all still refuses, naming itself. */
+export const writeSetupAnswers = (path, answers) => {
+    let kept = {};
+    try {
+        kept = readSetupAnswers(path);
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || !error.message.includes(`${SECTION} holds`))
+            throw error;
+    }
+    writeSharedSection(path, SECTION, { ...kept, ...answers });
+};
+/**
+ * The level no command of any WireCat tool goes above, or `undefined` when the owner chose to leave them as they
+ * are. A file that cannot be read keeps everything read-only: reads still work, and `setup` writes it again.
+ */
+export const permissionCeiling = (path) => {
+    let answer;
+    try {
+        answer = readSetupAnswers(path).permissions;
+    }
+    catch {
+        return "readonly";
+    }
+    return answer === "allow" ? undefined : answer;
+};

package/dist/documents/index.d.ts

@@ -3,6 +3,7 @@ export { type Complete, extractMemories } from "../services/documents/extraction
 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 MirrorTrigger, type MirrorWatchEvent, type MirrorWatchOptions, watchMirrors, } from "../services/documents/mirror-watch.js";
 export { conflictReport, fileMirrorState, type Mirror, type MirrorSyncOptions, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export type { SyncOptions } from "../services/documents/ports.js";
 export { extractDocumentMemories, type ImportedSource, type ProposalOptions } from "../services/documents/proposals.js";

package/dist/documents/index.js

@@ -3,6 +3,7 @@ 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 { watchMirrors, } from "../services/documents/mirror-watch.js";
 export { conflictReport, fileMirrorState, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export { extractDocumentMemories } from "../services/documents/proposals.js";
 export { planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";

package/dist/mcp/agent.js

@@ -6,7 +6,7 @@ import { VOCABULARY } from "@wirecat/cli-base/standards/tables";
 import * as v from "valibot";
 import { changesMessenger } from "../cli/effects.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
-import { AUTHORITY_KEY, authorityAllowed, keyForCommand, levelFor, readKeysForCommand, } from "../sends/permissions.js";
+import { AUTHORITY_KEY, authorityAllowed, botApiAllowed, isBotApi, keyForCommand, levelFor, readKeysForCommand, } from "../sends/permissions.js";
 const TYPES = new Map(VOCABULARY.flags.map((flag) => [flag.name, flag.type]));
 // `<name|id>` is one argument: its field is `name_or_id`.
 const snake = (name) => name.replaceAll("|", "_or_").replace(/[^a-z0-9]+/gi, "_");
@@ -150,7 +150,8 @@ export const toolsFromCommands = (commands, options = {}) => {
         info.mcp !== false &&
         info.lifetime === undefined &&
         !(readOnly && (changesMessenger(info) || authority?.(info.path))) &&
-        (levels === undefined || refusal(info, levels, keyOf, authority) === undefined))
+        (levels === undefined ||
+            (refusal(info, levels, keyOf, authority) === undefined && (!isBotApi(info.path) || botApiAllowed(levels)))))
         .map((info) => ({
         command: info.path.slice(root.length).join(" "),
         path: info.path,
@@ -230,6 +231,7 @@ export const runCommandForAgent = async (program, path, input, ctx) => {
                 },
                 ...(ctx.overrides?.length ? { overrides: ctx.overrides } : {}),
                 authority: levels !== undefined && authorityAllowed(levels),
+                botApi: levels !== undefined && botApiAllowed(levels),
             },
             // Opened only when the command asks: a read the store answers never connects.
             ...(lend

package/dist/search/dictionary.d.ts

@@ -0,0 +1,20 @@
+/** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
+export declare const DICTIONARIES: {
+    readonly russian: "dictionary-ru";
+    readonly english: "dictionary-en";
+    readonly spanish: "dictionary-es";
+};
+export type DictionaryLanguage = keyof typeof DICTIONARIES;
+/**
+ * `known`: whether a folded word the index stores is real in one of `languages` that write in its alphabet.
+ * `covers`: whether any of them does; without one, a garbled spelling cannot be told from a real word.
+ */
+export declare const knownWord: (languages: readonly DictionaryLanguage[]) => {
+    covers: (word: string) => boolean;
+    known: (word: string) => boolean;
+};
+/** The dictionaries of the store's stemmers: Russian for Cyrillic, each named Latin stemmer for Latin. */
+export declare const dictionaryLanguages: (stemmers: {
+    cyrillic: string;
+    latin: string;
+}) => DictionaryLanguage[];

package/dist/search/dictionary.js

@@ -0,0 +1,106 @@
+import { readFileSync } from "node:fs";
+import { fold } from "../store/normalize.js";
+/** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
+export const DICTIONARIES = { russian: "dictionary-ru", english: "dictionary-en", spanish: "dictionary-es" };
+/** `fold`, without Unicode normalisation for plain Russian letters: it would double the time Russian loads in. */
+const folded = (word) => /^[а-яё'-]*$/.test(word) ? word.replaceAll("ё", "е").replaceAll("й", "и") : fold(word);
+const loaded = new Map();
+/**
+ * Hunspell's own check, an affix at a time, instead of nspell's: nspell expands Russian's 146,269 entries into
+ * 1.44 million forms (1.4 s, 172 MB) where this loads in about 0.2 s. The index stores words folded as `normalize`
+ * folds them, so entries, affixes and conditions are folded too; a condition such as `[^ейоь]` then refuses и as
+ * well, which changed none of 12,769 sample words. Continuation classes and compounds are not followed: a word
+ * only they make counts as unknown and may widen.
+ */
+const dictionary = (language) => {
+    const cached = loaded.get(language);
+    if (cached)
+        return cached;
+    const file = (name) => readFileSync(new URL(name, import.meta.resolve(DICTIONARIES[language])), "utf8");
+    const words = new Map();
+    for (const line of file("index.dic").split("\n").slice(1)) {
+        const [entry, flags = ""] = line.trim().split("/");
+        if (!entry)
+            continue;
+        // Names and abbreviations are capitalised in the dictionary; the index is lower case.
+        const spelled = entry.toLowerCase();
+        const key = folded(spelled);
+        words.set(key, (words.get(key) ?? "") + flags);
+    }
+    const suffixes = new Map();
+    const prefixes = new Map();
+    const crosses = new Set();
+    let longest = 0;
+    for (const line of file("index.aff").split("\n")) {
+        const [kind, flag, strip, add, condition] = line.trim().split(/\s+/);
+        if ((kind !== "SFX" && kind !== "PFX") || flag === undefined || strip === undefined || add === undefined)
+            continue;
+        if (!condition) {
+            if (strip === "Y")
+                crosses.add(`${kind}${flag}`);
+            continue;
+        }
+        const affix = folded(add.split("/")[0].replace(/^0$/, ""));
+        const pattern = condition === "." ? "" : folded(condition);
+        const into = kind === "SFX" ? suffixes : prefixes;
+        const rules = into.get(affix) ?? [];
+        rules.push({
+            flag,
+            strip: strip === "0" ? "" : folded(strip),
+            condition: new RegExp(kind === "SFX" ? `${pattern}$` : `^${pattern}`),
+            cross: crosses.has(`${kind}${flag}`),
+        });
+        into.set(affix, rules);
+        longest = Math.max(longest, affix.length);
+    }
+    const made = { words, suffixes, prefixes, longest };
+    loaded.set(language, made);
+    return made;
+};
+const entry = ({ words }, key, rule, also) => {
+    const flags = words.get(key) ?? "";
+    return flags.includes(rule.flag) && (also === undefined || flags.includes(also)) && rule.condition.test(key);
+};
+/** A suffix on a dictionary word; `prefix` is the flag of a prefix already taken off, which both must allow. */
+const suffixed = (found, word, prefix) => {
+    for (let cut = 0; cut <= Math.min(word.length - 1, found.longest); cut++)
+        for (const rule of found.suffixes.get(word.slice(word.length - cut)) ?? [])
+            if ((prefix === undefined || rule.cross) &&
+                entry(found, word.slice(0, word.length - cut) + rule.strip, rule, prefix))
+                return true;
+    return false;
+};
+const spelled = (language, word) => {
+    const found = dictionary(language);
+    if (found.words.has(word) || suffixed(found, word))
+        return true;
+    for (let cut = 1; cut <= Math.min(word.length - 1, found.longest); cut++)
+        for (const rule of found.prefixes.get(word.slice(0, cut)) ?? []) {
+            const rest = rule.strip + word.slice(cut);
+            if (entry(found, rest, rule) || (rule.cross && suffixed(found, rest, rule.flag)))
+                return true;
+        }
+    return false;
+};
+const CYRILLIC = /\p{Script=Cyrillic}/u;
+const SCRIPT_OF = {
+    russian: "cyrillic",
+    english: "latin",
+    spanish: "latin",
+};
+/**
+ * `known`: whether a folded word the index stores is real in one of `languages` that write in its alphabet.
+ * `covers`: whether any of them does; without one, a garbled spelling cannot be told from a real word.
+ */
+export const knownWord = (languages) => {
+    const byScript = (word) => {
+        const script = CYRILLIC.test(word) ? "cyrillic" : "latin";
+        return languages.filter((language) => SCRIPT_OF[language] === script);
+    };
+    return {
+        covers: (word) => byScript(word).length > 0,
+        known: (word) => byScript(word).some((language) => spelled(language, word)),
+    };
+};
+/** The dictionaries of the store's stemmers: Russian for Cyrillic, each named Latin stemmer for Latin. */
+export const dictionaryLanguages = (stemmers) => [stemmers.cyrillic, ...stemmers.latin.split(",")].filter((name) => Object.hasOwn(DICTIONARIES, name));

package/dist/sends/guard.d.ts

@@ -71,6 +71,8 @@ export interface SendGuardOptions {
     now?: () => Date;
 }
 /** A write the profile's level refuses, worded alike by the guard and by the check before connecting. */
+/** A write the first-run answer stops, whatever the profile allows. */
+export declare const ceilingRefusal: (key: PermissionKey, command: string) => CliError;
 export declare const levelRefusal: (refused: {
     profile: string;
     command: string;

package/dist/sends/guard.js

@@ -3,7 +3,7 @@ import { CliError } from "@wirecat/cli-base";
 import { MESSENGER_CHANGE_REFUSAL, readOnlyRefusal } from "../ports/app.js";
 import { FloodMemory, floodPathFor, holdEnd } from "./flood.js";
 import { SendJournal, sendsPathFor, } from "./journal.js";
-import { keyForWrite, levelFor, skipFlagFor } from "./permissions.js";
+import { CEILING_KEY, keyForWrite, levelFor, skipFlagFor } from "./permissions.js";
 import { RecipientList, recipientsPathFor } from "./recipients.js";
 const HOUR_MS = 60 * 60 * 1000;
 /**
@@ -51,8 +51,13 @@ const weightOf = ({ kind = "message", action, count, people }) => kind === "dele
 /** A scheduled message counts in the hour the provider sends it. */
 const timeOf = (entry) => Date.parse(entry.scheduledFor ?? entry.at);
 /** A write the profile's level refuses, worded alike by the guard and by the check before connecting. */
-export const levelRefusal = (refused, fix = `${refused.command} ${refused.profile} config set permissions.${refused.key} allow`) => new CliError("permission_error", `profile ${refused.profile} does not let ${refused.key} write (permissions.${refused.named} is ${refused.level}, ` +
-    `from the ${refused.permissionSources[refused.named ?? ""] ?? "default"}); to allow it: ${fix}`, { permission: refused.key });
+/** A write the first-run answer stops, whatever the profile allows. */
+export const ceilingRefusal = (key, command) => new CliError("permission_error", `${key} is not allowed: setup's answer keeps every WireCat tool read-only; ` +
+    `the owner changes it at a terminal with \`${command} setup\``, { permission: key });
+export const levelRefusal = (refused, fix = `${refused.command} ${refused.profile} config set permissions.${refused.key} allow`) => refused.named === CEILING_KEY
+    ? ceilingRefusal(refused.key, refused.command)
+    : new CliError("permission_error", `profile ${refused.profile} does not let ${refused.key} write (permissions.${refused.named} is ${refused.level}, ` +
+        `from the ${refused.permissionSources[refused.named ?? ""] ?? "default"}); to allow it: ${fix}`, { permission: refused.key });
 /**
  * These stop a model that was talked into sending by a message it read. They do **not** stop an
  * agent that edits the configuration itself — that needs a boundary outside this process

package/dist/sends/permissions.d.ts

@@ -21,6 +21,15 @@ export declare const DEFAULT_PERMISSIONS: Readonly<Record<PermissionKey, Level>>
 export declare const AUTHORITY_KEY: PermissionKey;
 /** Whether these levels let an agent run a command that changes what a later run may do; `ask` does, as for any write. */
 export declare const authorityAllowed: (levels: Readonly<Record<PermissionKey, Level>>) => boolean;
+/** Lets an MCP server offer `bot api`, whose calls skip the send guard and the bot's recipient list (NEED-1679). */
+export declare const BOT_API_KEY: PermissionKey;
+export declare const isBotApi: (path: readonly string[]) => boolean;
+/**
+ * Deny by default for an MCP server only: the key stays out of `DEFAULT_PERMISSIONS` because the command line's
+ * `bot api` is checked per operation (`bot.api.<operation>`), and a default there would deny it for the owner too.
+ * A broader `bot: allow` does not lift it; `ask` goes ahead over MCP, as for any write.
+ */
+export declare const botApiAllowed: (levels: Readonly<Record<PermissionKey, Level>>) => boolean;
 /** The resources at the top of the command tree, which `readOnly` and `allow` turn read-only as a whole. */
 export declare const RESOURCES: readonly ["messages", "reactions", "polls", "topics", "chats", "contacts", "account", "bot", "conversations", "tags", "mentions", "search", "searches", "tasks", "replies", "attachments", "stats", "store", "metadata", "mcp", "server", "models", "schedule", "doctor", "images"];
 /** The command path an old `allow` word stood for, as one key — what an MCP tool's `permission` is checked against. */
@@ -34,6 +43,11 @@ export declare const layerPermissions: (layers: readonly [string, Readonly<Recor
     levels: Record<string, "allow" | "ask" | "deny" | "readonly">;
     sources: Record<string, string>;
 };
+/**
+ * The owner's first-run answer, held among a profile's levels: no key of any profile goes above it. Only `setup`
+ * at a terminal writes it, so an agent cannot lift it with `config set`.
+ */
+export declare const CEILING_KEY = "*";
 /**
  * The most specific key the owner set wins. A built-in default (`DEFAULT_PERMISSIONS`) only ever
  * tightens: against a broader key of the owner's, the stricter of the two holds — so

package/dist/sends/permissions.js

@@ -107,6 +107,18 @@ export const authorityAllowed = (levels) => {
     const { level } = levelFor(levels, AUTHORITY_KEY);
     return level === "allow" || level === "ask";
 };
+/** Lets an MCP server offer `bot api`, whose calls skip the send guard and the bot's recipient list (NEED-1679). */
+export const BOT_API_KEY = "bot.api";
+export const isBotApi = (path) => path[0] === "bot" && path[1] === "api";
+/**
+ * Deny by default for an MCP server only: the key stays out of `DEFAULT_PERMISSIONS` because the command line's
+ * `bot api` is checked per operation (`bot.api.<operation>`), and a default there would deny it for the owner too.
+ * A broader `bot: allow` does not lift it; `ask` goes ahead over MCP, as for any write.
+ */
+export const botApiAllowed = (levels) => {
+    const { level } = levelFor(levels, BOT_API_KEY, { ...DEFAULT_PERMISSIONS, [BOT_API_KEY]: "deny" });
+    return level === "allow" || level === "ask";
+};
 /** The resources at the top of the command tree, which `readOnly` and `allow` turn read-only as a whole. */
 export const RESOURCES = [
     "messages",
@@ -195,6 +207,11 @@ export const layerPermissions = (layers) => {
     }
     return { levels, sources };
 };
+/**
+ * The owner's first-run answer, held among a profile's levels: no key of any profile goes above it. Only `setup`
+ * at a terminal writes it, so an agent cannot lift it with `config set`.
+ */
+export const CEILING_KEY = "*";
 const ALLOWED = { level: "allow", key: null };
 const ORDER = { deny: 0, readonly: 1, ask: 2, allow: 3 };
 const nearest = (levels, key) => {
@@ -218,9 +235,14 @@ const FORMER_KEYS = { "chats.unmute": "chats.mute" };
  * A path nothing names is allowed.
  */
 export const levelFor = (permissions, key, defaults = DEFAULT_PERMISSIONS) => {
+    const found = profileLevel(permissions, key, defaults);
+    const ceiling = permissions[CEILING_KEY];
+    return ceiling && ORDER[ceiling] < ORDER[found.level] ? { level: ceiling, key: CEILING_KEY } : found;
+};
+const profileLevel = (permissions, key, defaults) => {
     const former = FORMER_KEYS[key];
     if (former !== undefined && permissions[key] === undefined)
-        return levelFor(permissions, former, defaults);
+        return profileLevel(permissions, former, defaults);
     const own = nearest(permissions, key);
     const builtIn = nearest(defaults, key);
     if (!builtIn || (own && own.depth >= builtIn.depth))

package/dist/services/documents/mirror-watch.d.ts

@@ -0,0 +1,39 @@
+import { CliError } from "@wirecat/cli-base";
+import type { PushStatePort } from "../../documents/push-model.js";
+import { type Mirror } from "./mirrors.js";
+/** What started a cycle: the first run, a local save, a remote change, the periodic local check, or a full run. */
+export type MirrorTrigger = "start" | "local" | "remote" | "check" | "full";
+export type MirrorWatchEvent<T> = {
+    triggers: MirrorTrigger[];
+    mirrors: string[];
+    result: T;
+} | {
+    triggers: MirrorTrigger[];
+    mirrors: string[];
+    error: CliError;
+};
+export interface MirrorWatchOptions<S> {
+    mirrors: Mirror[];
+    signal: AbortSignal;
+    kindOf(path: string): string | undefined;
+    stateOf(mirror: Mirror): PushStatePort<S>;
+    /** Ids of the mirrors whose remote files changed since the last call, or `all` when the provider cannot tell. */
+    remoteChanges?(signal: AbortSignal): Promise<string[] | "all">;
+    pollMs?: number;
+    quietMs?: number;
+    /** How often local files are compared with the state, for file events the system dropped. */
+    checkMs?: number;
+    /** How often every mirror is synced whatever the triggers said, for remote changes the provider listed late. */
+    fullMs?: number;
+    watchFolder?(root: string, changed: () => void): () => void;
+    sleep?(milliseconds: number, signal: AbortSignal): Promise<void>;
+    now?(): number;
+}
+/**
+ * Keeps mirrors in sync until `signal` aborts: a cycle at start, then one for each mirror whose files were saved
+ * (after `quietMs` without another save), whose remote files changed, or whose files differ from the state at the
+ * periodic check; every mirror at each full run. A local trigger syncs only when the files differ from the state, so
+ * the files a pull writes do not start another cycle. A failed cycle is reported and its mirrors tried again at the
+ * next poll; the watch goes on.
+ */
+export declare function watchMirrors<S, T>(sync: (mirrors: Mirror[], signal: AbortSignal) => Promise<T>, options: MirrorWatchOptions<S>): AsyncGenerator<MirrorWatchEvent<T>, void, void>;

package/dist/services/documents/mirror-watch.js

@@ -0,0 +1,155 @@
+import { watch } from "node:fs";
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { mirrorStatus } from "./mirrors.js";
+import { skippedName } from "./push.js";
+const sleep = (milliseconds, signal) => new Promise((resolve) => {
+    const finish = () => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", finish);
+        resolve();
+    };
+    const timer = setTimeout(finish, milliseconds);
+    signal.addEventListener("abort", finish, { once: true });
+});
+const watchFolder = (root, changed) => {
+    try {
+        const watcher = watch(root, { recursive: true }, (_event, name) => {
+            if (name === null || !name.split(/[\\/]/).some(skippedName))
+                changed();
+        });
+        // A lost watcher only delays a sync until the periodic check; it never stops the watch.
+        watcher.on("error", () => watcher.close());
+        return () => watcher.close();
+    }
+    catch {
+        return () => { };
+    }
+};
+const failure = (error) => isCliError(error) ? error : new CliError("provider_error", "the sync cycle failed");
+/**
+ * Keeps mirrors in sync until `signal` aborts: a cycle at start, then one for each mirror whose files were saved
+ * (after `quietMs` without another save), whose remote files changed, or whose files differ from the state at the
+ * periodic check; every mirror at each full run. A local trigger syncs only when the files differ from the state, so
+ * the files a pull writes do not start another cycle. A failed cycle is reported and its mirrors tried again at the
+ * next poll; the watch goes on.
+ */
+export async function* watchMirrors(sync, options) {
+    const { mirrors, signal } = options;
+    const pollMs = options.pollMs ?? 60_000;
+    const quietMs = options.quietMs ?? 2_000;
+    const checkMs = options.checkMs ?? 300_000;
+    const fullMs = options.fullMs ?? 1_800_000;
+    const now = options.now ?? Date.now;
+    const wait = options.sleep ?? sleep;
+    const byId = new Map(mirrors.map((mirror) => [mirror.id, mirror]));
+    const saved = new Map();
+    const retry = new Set();
+    let wake = new AbortController();
+    const closers = mirrors.map((mirror) => (options.watchFolder ?? watchFolder)(mirror.path, () => {
+        saved.set(mirror.id, now());
+        wake.abort();
+    }));
+    const differs = async (ids) => {
+        const chosen = [...ids].flatMap((id) => byId.get(id) ?? []);
+        try {
+            const items = await mirrorStatus(chosen, options.kindOf, options.stateOf);
+            return items.filter((item) => item.create.length || item.update.length).map((item) => item.id);
+        }
+        catch {
+            // An unreadable folder is for the sync to report.
+            return chosen.map((mirror) => mirror.id);
+        }
+    };
+    const run = async (triggers, ids) => {
+        const chosen = mirrors.filter((mirror) => ids.has(mirror.id));
+        const names = chosen.map((mirror) => mirror.id);
+        try {
+            return { triggers, mirrors: names, result: await sync(chosen, signal) };
+        }
+        catch (error) {
+            for (const id of names)
+                retry.add(id);
+            return { triggers, mirrors: names, error: failure(error) };
+        }
+    };
+    try {
+        if (signal.aborted)
+            return;
+        const first = await run(["start"], new Set(byId.keys()));
+        // A cycle cut short by the stop is the stop, not a failure.
+        if (signal.aborted && "error" in first)
+            return;
+        yield first;
+        let nextPoll = now() + pollMs;
+        let nextCheck = now() + checkMs;
+        let nextFull = now() + fullMs;
+        while (!signal.aborted) {
+            let due = Math.min(nextPoll, nextCheck, nextFull);
+            for (const at of saved.values())
+                due = Math.min(due, at + quietMs);
+            const until = due - now();
+            if (until > 0) {
+                await wait(until, AbortSignal.any([signal, wake.signal]));
+                if (wake.signal.aborted)
+                    wake = new AbortController();
+                if (signal.aborted)
+                    return;
+                continue;
+            }
+            const at = now();
+            const triggers = [];
+            const ids = new Set();
+            const add = (trigger, found) => {
+                const before = ids.size;
+                for (const id of found)
+                    ids.add(id);
+                if (ids.size > before && !triggers.includes(trigger))
+                    triggers.push(trigger);
+            };
+            if (at >= nextFull) {
+                add("full", byId.keys());
+                nextFull = at + fullMs;
+                nextCheck = at + checkMs;
+                nextPoll = at + pollMs;
+                saved.clear();
+                retry.clear();
+            }
+            else {
+                const settled = [...saved].filter(([, saveAt]) => saveAt + quietMs <= at).map(([id]) => id);
+                for (const id of settled)
+                    saved.delete(id);
+                if (settled.length)
+                    add("local", await differs(settled));
+                if (at >= nextCheck) {
+                    add("check", await differs(byId.keys()));
+                    nextCheck = at + checkMs;
+                }
+                if (at >= nextPoll) {
+                    nextPoll = at + pollMs;
+                    add("remote", retry);
+                    retry.clear();
+                    if (options.remoteChanges)
+                        try {
+                            const changed = await options.remoteChanges(signal);
+                            add("remote", changed === "all" ? byId.keys() : changed.filter((id) => byId.has(id)));
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                return;
+                            yield { triggers: ["remote"], mirrors: [], error: failure(error) };
+                        }
+                }
+            }
+            if (signal.aborted || !ids.size)
+                continue;
+            const event = await run(triggers, ids);
+            if (signal.aborted && "error" in event)
+                return;
+            yield event;
+        }
+    }
+    finally {
+        for (const close of closers)
+            close();
+    }
+}

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

@@ -60,6 +60,8 @@ export interface PushResult {
     };
     stopped?: true;
 }
+/** Hidden files, `node_modules` and editor leftovers: never mirrored, and never a reason to sync. */
+export declare const skippedName: (name: string) => boolean;
 /** 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[];

package/dist/services/documents/push.js

@@ -4,6 +4,8 @@ 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)$/;
+/** Hidden files, `node_modules` and editor leftovers: never mirrored, and never a reason to sync. */
+export const skippedName = (name) => SKIPPED.test(name);
 const hashFile = (path) => new Promise((done, fail) => {
     const hash = createHash("sha256");
     createReadStream(path)

package/dist/store/shared-config.d.ts

@@ -12,6 +12,10 @@ export declare const readTaskCategoryEdits: (path: string) => TaskCategoryEdits
 export declare const applyTaskCategoryEdits: (base: readonly TaskCategory[], edits: TaskCategoryEdits, path: string) => readonly TaskCategory[];
 /** The edits that turn the default list into `list`, for moving a list an older build saved in the store. */
 export declare const editsFrom: (list: readonly TaskCategory[]) => TaskCategoryEdits;
+/** One section of the file, or `undefined` when the file or the section is missing. */
+export declare const readSharedSection: (path: string, section: string) => unknown;
+/** Writes one section (or drops it, with `undefined`), keeping every other key of the file. */
+export declare const writeSharedSection: (path: string, section: string, value: unknown) => void;
 /** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
 export declare const writeTaskCategoryEdits: (path: string, edits: TaskCategoryEdits | undefined) => void;
 /** Read again only when the file changed: a sync asks for the list once per message. */

package/dist/store/shared-config.js

@@ -39,7 +39,7 @@ const readJson = (path) => {
 };
 /** The `task_categories` section, or `undefined` when the file or the section is missing. */
 export const readTaskCategoryEdits = (path) => {
-    const section = readJson(path)?.[SECTION];
+    const section = readSharedSection(path, SECTION);
     if (section === undefined)
         return undefined;
     if (section === null || typeof section !== "object" || Array.isArray(section))
@@ -77,18 +77,22 @@ export const editsFrom = (list) => {
     }
     return edits;
 };
-/** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
-export const writeTaskCategoryEdits = (path, edits) => {
+/** One section of the file, or `undefined` when the file or the section is missing. */
+export const readSharedSection = (path, section) => readJson(path)?.[section];
+/** Writes one section (or drops it, with `undefined`), keeping every other key of the file. */
+export const writeSharedSection = (path, section, value) => {
     const file = readJson(path) ?? {};
-    if (edits === undefined || Object.keys(edits).length === 0)
-        delete file[SECTION];
+    if (value === undefined)
+        delete file[section];
     else
-        file[SECTION] = edits;
+        file[section] = value;
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${process.pid}.tmp`;
     writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
     renameSync(temporary, path);
 };
+/** Writes the section (or drops it, with `undefined`), keeping every other key of the file. */
+export const writeTaskCategoryEdits = (path, edits) => writeSharedSection(path, SECTION, edits === undefined || Object.keys(edits).length === 0 ? undefined : edits);
 /** Read again only when the file changed: a sync asks for the list once per message. */
 export const taskCategoriesReader = (path) => {
     let seen;