@wirecat/cli-core 0.597.0 → 0.599.0

package/dist/cli/store-recover.js

@@ -0,0 +1,153 @@
+import { existsSync } from "node:fs";
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { explainDamage } from "../store/damage.js";
+import { storeHealth } from "../store/health.js";
+import { storePath } from "../store/path.js";
+import { activeTimers, recoverStore, sqlite3Program, storeHolders, tableRows, } from "../store/recover.js";
+import { openSqlite } from "../store/store.js";
+import { environmentOf, outputFor } from "./context.js";
+import { LOCAL_READ, LOCAL_WRITE } from "./effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
+/** The tables whose counts say what the store holds; every other table is in `store info`. */
+const COUNTED = [
+    "accounts",
+    "chats",
+    "messages",
+    "attachments",
+    "emails",
+    "documents",
+    "notes",
+    "meetings",
+    "chunks",
+    "embeddings",
+    "mentions",
+];
+const stopTimers = (timers) => `systemctl --user stop ${timers.join(" ")}`;
+/** `store recover`: what is wrong with the store and what to run, reading every page; changes nothing. */
+export const storeRecoveryCheck = async (env, command) => {
+    const path = storePath(env);
+    if (!existsSync(path))
+        return { path, exists: false, ok: true, next: [] };
+    const health = await storeHealth(path, { deep: true });
+    let rows = {};
+    try {
+        const { database } = await openSqlite(path, { readOnly: true });
+        try {
+            const all = tableRows(database);
+            rows = Object.fromEntries(COUNTED.filter((table) => table in all).map((table) => [table, all[table] ?? null]));
+        }
+        finally {
+            database.close();
+        }
+    }
+    catch { }
+    const explanation = explainDamage(health, command);
+    const inUse = storeHolders(path) ?? null;
+    const timers = activeTimers() ?? null;
+    const sqlite3 = sqlite3Program();
+    const next = health.ok
+        ? []
+        : [
+            ...(timers?.length ? [stopTimers(timers)] : []),
+            ...(inUse ?? []).map(({ pid, name }) => `stop ${name} (process ${pid}): it has the store open`),
+            ...(sqlite3.usable ? [] : ["install sqlite3 3.43 or newer (apt install sqlite3, brew install sqlite)"]),
+            `${command} store recover run`,
+        ];
+    return {
+        path,
+        exists: true,
+        ok: health.ok,
+        seconds: Math.round(health.ms / 100) / 10,
+        problems: health.problems ?? 0,
+        damagedTables: health.damagedTables ?? [],
+        damagedSearchIndexes: (health.searchIndexes ?? [])
+            .filter((index) => !index.ok)
+            .map(({ name, error }) => ({ name, ...(error ? { error } : {}) })),
+        rows,
+        explanation,
+        inUse,
+        timers,
+        sqlite3: { version: sqlite3.version, usable: sqlite3.usable },
+        next,
+    };
+};
+/** `store recover run`: refuses while a WireCat timer is scheduled, so none writes to the file being replaced. */
+export const storeRecoveryRun = async (env, { command, version, note, timers: scheduled = activeTimers, copy, }) => {
+    const timers = scheduled() ?? [];
+    if (timers.length > 0)
+        throw new CliError("validation_error", `stop the timers first, they open the store: ${stopTimers(timers)}`, {
+            reason: "store.in-use",
+        });
+    const recovery = await recoverStore({
+        path: storePath(env),
+        command,
+        ...(version ? { version } : {}),
+        ...(note ? { note } : {}),
+        ...(copy ? { copy } : {}),
+    });
+    const mail = recovery.mailToFetch.map(({ account, emails }) => `mail <profile of ${account}> sync --rescan   # ${emails} emails`);
+    const lostMail = recovery.lost.some(({ table }) => table === "emails") && mail.length === 0
+        ? ["mail <profile> sync --rescan   # each mail profile"]
+        : [];
+    const { health, copyErrors, ...kept } = recovery;
+    return {
+        ...kept,
+        copyErrors: copyErrors.length,
+        checkedOk: health.ok,
+        next: [...mail, ...lostMail, "systemctl --user start <the timers stopped before>"],
+    };
+};
+/** The lines a person reads under the answer; the JSON carries the same in its fields. */
+export const recoveryNotes = (answer) => {
+    if ("keptAt" in answer) {
+        const lost = answer.lost.map(({ table, before, read, kept }) => `${table}: ${kept} kept of ${before ?? "an uncountable number"}${read > kept ? `, ${read - kept} read but unusable` : ""}`);
+        return [
+            `recovered in ${answer.seconds.total} s; the damaged file is kept at ${answer.keptAt}`,
+            ...(lost.length ? lost : ["no table lost a row"]),
+            ...answer.dangling.map(({ table, parent, rows }) => `${rows} rows of ${table} point at ${parent} rows the store does not hold`),
+            ...answer.next.map((line) => `next: ${line}`),
+        ];
+    }
+    if (!answer.exists)
+        return ["no store yet"];
+    if (answer.ok)
+        return [`the store is healthy (checked every page and search index in ${answer.seconds} s)`];
+    const why = answer.explanation;
+    return [
+        ...(why ? [why.what, ...why.impact, why.externalUnaffected] : []),
+        ...answer.next.map((line) => `next: ${line}`),
+    ];
+};
+/** `store recover` and `store recover run`, for a CLI whose commands run on cli-core's context. */
+export const storeRecoverCommand = ({ command, version }) => {
+    const recover = annotate(new Command("recover"), { effects: LOCAL_READ, examples: [`${command} store recover`] })
+        .summary("what is damaged in the store and how to recover it")
+        .description("check every page and search index of the store, say what is damaged, what it means and the commands that recover it; changes nothing")
+        .action(async function () {
+        const output = outputFor(this);
+        const answer = await storeRecoveryCheck(environmentOf(this).env ?? process.env, command);
+        renderAnswer(this, output, itemOf(snakeKeys(answer)));
+        if (output.format === "pretty")
+            for (const line of recoveryNotes(answer))
+                output.renderer.note(line);
+    });
+    recover.addCommand(annotate(new Command("run"), { effects: LOCAL_WRITE, examples: [`${command} store recover run`] })
+        .summary("rebuild a damaged store from every row it can read")
+        .description("copy every readable row into a new file with the sqlite3 program, rebuild the search indexes, mentions and vector index, " +
+        "check it, and put it in place of the store; the damaged file is kept beside it. Refuses while a WireCat timer or process has the store")
+        .action(async function () {
+        const output = outputFor(this);
+        const answer = await storeRecoveryRun(environmentOf(this).env ?? process.env, {
+            command,
+            ...(version ? { version } : {}),
+            note: (text) => output.renderer.note(text),
+        });
+        renderAnswer(this, output, itemOf(snakeKeys(answer)));
+        if (output.format === "pretty")
+            for (const line of recoveryNotes(answer))
+                output.renderer.note(line);
+    }));
+    return recover;
+};

package/dist/crm/cli/index.js

@@ -3,7 +3,7 @@ import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
 import { Argument, InvalidArgumentError } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
-import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
+import { environmentOf, inCommandRun, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { FETCH, LOCAL_READ, NO_EFFECTS, REMOTE_WRITE } from "../../cli/effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys, snakeKeysKeeping } from "../../cli/envelope.js";
@@ -142,7 +142,7 @@ const dealKeys = snakeKeysKeeping(["providerMetadata"]);
 const marked = (items, untrusted) => items.map((item) => ({ ...dealKeys(item), untrusted }));
 const addCrmCommandsDefinition = (program, options) => {
     const now = () => options.now?.() ?? Date.now();
-    const within = async (command, work) => {
+    const within = (command, work) => inCommandRun(command, async () => {
         const run = await options.open(command, { readOnly: metaOf(command).effects?.local !== "write" });
         let body;
         try {
@@ -152,7 +152,7 @@ const addCrmCommandsDefinition = (program, options) => {
             await run.close?.();
         }
         renderAnswer(command, outputFor(command), body);
-    };
+    });
     const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} work ${line}`) });
     example(answerEntity(annotate(program.command("sync"), { effects: FETCH, offline: false, cooperative: true, partial: true }), "crm_sync", crmSync).description("bring the CRM's copy in the local store up to date: pipelines, companies, contacts, deals and leads that " +
         "changed since the last sync, or everything with --rescan; a run stops before its deadline or --max-pages " +
@@ -444,7 +444,8 @@ const addCrmCommandsDefinition = (program, options) => {
         .description("the CRM's custom fields of one kind, in its order, with a list field's options")
         .argument("<kind>", fieldKinds.join(", "))
         .option("--limit <n>", `fields per page, 1–${MOST}`, integer(MOST), 50)
-        .option("--page <n>", "which page, starting at 1", integer(1_000_000), 1)
+        // No default: the run's settings refuse --all beside a --page, given or defaulted.
+        .option("--page <n>", "which page, starting at 1", integer(1_000_000))
         .option("--all", "every field, no paging"), FIELDS_QUERY), "fields list deals", "fields list people --json").action(async (kind, words, opts, command) => {
         if (!fieldKinds.includes(kind))
             throw new CliError("validation_error", `fields are listed for ${fieldKinds.join(", ")}; got ${kind}`, {
@@ -454,12 +455,13 @@ const addCrmCommandsDefinition = (program, options) => {
         queryTerms(words, FIELDS_QUERY, "fields list");
         await within(command, async (run) => {
             const found = await run.store.crm.fields(run.account, FIELD_KINDS[kind]);
-            const offset = opts.all ? 0 : (opts.page - 1) * opts.limit;
+            const page = opts.page ?? 1;
+            const offset = opts.all ? 0 : (page - 1) * opts.limit;
             const end = opts.all ? found.length : offset + opts.limit;
             return listOf(pathOf(command).join(" "), {
                 items: found.slice(offset, end).map((field) => ({ ...field, untrusted: FIELD_UNTRUSTED })),
                 limit: opts.all ? Math.max(1, found.length) : opts.limit,
-                page: opts.page,
+                page,
                 has_more: found.length > end,
                 ...(words.length ? { args: { query: words } } : {}),
             });

package/dist/errors/reasons.js

@@ -156,6 +156,14 @@ const OTHERS = [
     ],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
+    validation("store.in-use", "a process or a scheduled timer has the store open; stop it, then recover the store"),
+    [
+        "store.sqlite3-missing",
+        "configuration_error",
+        "recovering the store needs the sqlite3 program, 3.43 or newer, with its .recover command",
+    ],
+    validation("store.recovery-failed", "the recovered store did not pass its check, so the store was left as it was"),
+    validation("store.changed-during-recovery", "the store was written to during the recovery, so it was left as it was"),
     [
         "store.vector-extension-missing",
         "configuration_error",

package/dist/kit/index.d.ts

@@ -2,5 +2,6 @@ export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { type ContractCase, type ContractOptions, contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { type FakeAdapter, fakeAdapter } from "./fake.js";
 export { type McpStdio, type McpStdioStreams, type McpToolResult, mcpOverStdio } from "./mcp-stdio.js";
+export { neverAnswers, type RunScopeCase, type RunScopeOptions, runScopeCases } from "./run-scope.js";
 export { type SearchRecipes, searchRecipes, seedSearchRecipes } from "./search-recipes.js";
 export { BUSY_PAGE, contractSeed, digitIds, type IdKind, type IdMaker, type Seed, wordIds } from "./seed.js";

package/dist/kit/index.js

@@ -2,5 +2,6 @@ export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { fakeAdapter } from "./fake.js";
 export { mcpOverStdio } from "./mcp-stdio.js";
+export { neverAnswers, runScopeCases } from "./run-scope.js";
 export { searchRecipes, seedSearchRecipes } from "./search-recipes.js";
 export { BUSY_PAGE, contractSeed, digitIds, wordIds } from "./seed.js";

package/dist/kit/run-scope.d.ts

@@ -0,0 +1,34 @@
+import { type ProgramDefinition, type RunOptions } from "../cli/program.js";
+export interface RunScopeCase {
+    name: string;
+    /** Throws an `AssertionError` when the command does not run inside cli-core's run. */
+    run(): Promise<void>;
+}
+export interface RunScopeOptions {
+    /** The CLI's own program definition, as its `run()` hands it to cli-core. */
+    definition: ProgramDefinition;
+    /**
+     * The words that run each remote command to success against the answering fake, by command path:
+     * `{ "comments show": ["personal", "comments", "show", "c1"] }`. A write whose level is `ask` needs a profile that
+     * allows it, or its refusal fails the case.
+     */
+    commands: Record<string, readonly string[]>;
+    /** Remote commands left out, each with its reason: one that listens until stopped, one that asks npm. */
+    skip?: Record<string, string>;
+    /** What `run()` gets beside the streams: the keyring, and the fake that answers every request. */
+    answering: () => RunOptions;
+    /** The same, with a fake that takes every request and never settles it, `neverAnswers` for an HTTP service. */
+    silent: () => RunOptions;
+    /** The `--timeout` a silent run gets; 100 ms. */
+    timeoutMs?: number;
+}
+/** A `fetch` that never settles, not even on abort: only the run's own deadline can end the command. */
+export declare const neverAnswers: typeof fetch;
+/**
+ * Cases that each remote command runs inside cli-core's run — `baseContext(command, resolveSettings).run(body)` — and
+ * not beside it, so `--record` keeps a run named after the command (WC-LIFE-15); and that `--timeout` ends it when
+ * its service never answers, a write as `outcome_unknown` (WC-LIFE-5, WC-LIFE-9). The recorded case is the one that
+ * catches a command beside the run: `run()`'s own deadline still ends such a command on time. The first case fails
+ * on a remote command with no words and no skip.
+ */
+export declare const runScopeCases: (options: RunScopeOptions) => RunScopeCase[];

package/dist/kit/run-scope.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { metaOf } from "@wirecat/cli-base/commands";
+import { createProgram, run } from "../cli/program.js";
+import { findRun, runsDirFor } from "../runs/run.js";
+/** A `fetch` that never settles, not even on abort: only the run's own deadline can end the command. */
+export const neverAnswers = (() => new Promise(() => { }));
+const GRACE_MS = 2000;
+const remoteCommands = (program, path = []) => program.commands.flatMap((command) => {
+    const at = [...path, command.name()];
+    if (command.commands.length > 0)
+        return remoteCommands(command, at);
+    const meta = metaOf(command);
+    const remote = meta.effects?.remote;
+    return remote && remote !== "none" ? [{ path: at.join(" "), remote, partial: meta.partial === true }] : [];
+});
+const within = async (ms, what, body) => {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new assert.AssertionError({ message: what })), ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([body, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const parsed = (text) => {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Cases that each remote command runs inside cli-core's run — `baseContext(command, resolveSettings).run(body)` — and
+ * not beside it, so `--record` keeps a run named after the command (WC-LIFE-15); and that `--timeout` ends it when
+ * its service never answers, a write as `outcome_unknown` (WC-LIFE-5, WC-LIFE-9). The recorded case is the one that
+ * catches a command beside the run: `run()`'s own deadline still ends such a command on time. The first case fails
+ * on a remote command with no words and no skip.
+ */
+export const runScopeCases = (options) => {
+    const { definition, commands, skip = {}, timeoutMs = 100 } = options;
+    const { app } = definition;
+    const cli = async (argv, given) => {
+        const out = [];
+        const err = [];
+        const env = {
+            ...process.env,
+            ...given.env,
+            [`${app.envPrefix}_STATE_DIR`]: mkdtempSync(join(tmpdir(), "run-scope-")),
+        };
+        const code = await run(argv, definition, {
+            ...given,
+            env,
+            tty: false,
+            streams: { data: (text) => out.push(text), diagnostic: (text) => err.push(text) },
+        });
+        return { code, out: out.join(""), err: err.join(""), env };
+    };
+    const machine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=")) ? [...words] : [...words, "--json"];
+    const recordedCase = (path, words) => ({
+        name: `${path} runs in a recorded run named after it`,
+        run: async () => {
+            const ran = await within(GRACE_MS, `${path} did not end against the answering fake`, (async () => cli(["--record", ...machine(words)], options.answering()))());
+            assert.equal(ran.code, 0, `${path} must succeed against the answering fake; it exited ${ran.code}: ${ran.err}`);
+            const runId = parsed(ran.out)?.meta?.run_id;
+            assert.equal(typeof runId, "string", `${path} answered without meta.run_id`);
+            assert.doesNotMatch(String(runId), /-process-/, `${path} answered outside a run of its own: ${runId}`);
+            const kept = findRun(runsDirFor(app, ran.env), String(runId));
+            assert.ok(kept, `--record kept no run ${runId} for ${path}`);
+            assert.equal(kept.metadata.command, path, `the run of ${path} is named ${kept.metadata.command}`);
+        },
+    });
+    const timeoutCase = ({ path, remote, partial }, words) => {
+        const expected = remote === "write" ? "outcome_unknown" : "timeout";
+        return {
+            name: `${path} ends in ${expected}${partial ? " or a partial answer" : ""} at --timeout when the service never answers`,
+            run: async () => {
+                const ran = await within(timeoutMs + GRACE_MS, `${path} was still running ${GRACE_MS} ms after its --timeout ${timeoutMs}ms`, cli(["--timeout", `${timeoutMs}ms`, ...machine(words)], options.silent()));
+                const answered = parsed(ran.out)?.meta?.complete;
+                if (partial && ran.code === 0 && answered === false)
+                    return;
+                const code = parsed(ran.err)?.error?.code;
+                assert.equal(code, expected, `${path} against a silent service ended in ${String(code)}: ${ran.out}${ran.err}`);
+            },
+        };
+    };
+    const remote = remoteCommands(createProgram(definition));
+    const coverage = {
+        name: "every remote command has its words or a reason to skip it",
+        run: async () => {
+            const missing = remote.map(({ path }) => path).filter((path) => !(path in commands) && !(path in skip));
+            assert.deepEqual(missing, [], `remote commands with no words in \`commands\` and no reason in \`skip\``);
+            const known = new Set(remote.map(({ path }) => path));
+            const stray = [...Object.keys(commands), ...Object.keys(skip)].filter((path) => !known.has(path));
+            assert.deepEqual(stray, [], "paths in `commands` or `skip` that are not remote commands of this program");
+        },
+    };
+    return [
+        coverage,
+        ...remote.flatMap((one) => {
+            const words = commands[one.path];
+            return words ? [recordedCase(one.path, words), timeoutCase(one, words)] : [];
+        }),
+    ];
+};

package/dist/mcp/app-server.js

@@ -124,8 +124,13 @@ export const serveAppOverStdio = async (command, context, options) => {
     });
     const ended = await new Promise((resolve) => {
         wire.ended.then(() => resolve("input"));
-        if (own)
-            signal?.addEventListener("abort", () => resolve("stopped"), { once: true });
+        if (own) {
+            // A stop that came before this line fires no abort event.
+            if (signal?.aborted)
+                resolve("stopped");
+            else
+                signal?.addEventListener("abort", () => resolve("stopped"), { once: true });
+        }
         else {
             process.once("SIGINT", () => resolve("stopped"));
             process.once("SIGTERM", () => resolve("stopped"));

package/dist/meetings/cli/index.d.ts

@@ -11,6 +11,11 @@ export interface MeetingCommandDeps {
     importHelp?: string;
     writeFile?: (path: string, content: string) => Promise<void>;
     write: (value: unknown, format: "json" | "jsonl" | "text") => void;
+    /**
+     * Runs a command that reaches the account inside cli-core's run, so it is recorded and ended by `--timeout`:
+     * `inCommandRun` from `@wirecat/cli-core/cli`. Required, since this module cannot reach the run itself.
+     */
+    inRun: <T>(command: Command, body: () => Promise<T>) => Promise<T>;
     now?: () => number;
 }
 export { addMeetingPassageCommand, createMeetingPassageCommand, type MeetingPassageFlags, meetingPassageRequest, } from "./passage.js";

package/dist/meetings/cli/index.js

@@ -121,14 +121,15 @@ const addMeetingCommandsDefinition = (program, deps) => {
         .option("--since-time <time>", "fetch meetings starting at or after this ISO 8601 date or time", date)
         .option("--lookback-days <days>", "revisit recent occurrences for late transcripts (0–31)", lookbackDays, 0)
         .action(async (opts, command) => {
-        if (!deps.source)
+        const source = deps.source;
+        if (!source)
             throw new MeetingError("configuration_error", "meeting source is unavailable");
-        print(await pull(deps.source, deps.store, {
+        await deps.inRun(command, async () => print(await pull(source, deps.store, {
             accountId: deps.accountId,
             since: opts.sinceTime === undefined ? undefined : new Date(opts.sinceTime).toISOString(),
             now: deps.now?.(),
             lookbackMs: opts.lookbackDays * 86400000,
-        }), command);
+        }), command));
     });
     const importCommand = annotate(group.command("import"), {
         effects: LOCAL_WRITE,

package/dist/store/damage.d.ts

@@ -0,0 +1,19 @@
+import type { StoreHealth } from "./health.js";
+/**
+ * What a damaged store means, in the owner's words: one structure the CLIs render and the desktop app can show as it
+ * is. Built from a health check only, so it never reads the damaged file again.
+ */
+export interface DamageExplanation {
+    what: string;
+    causes: string[];
+    investigate: string[];
+    impact: string[];
+    externalUnaffected: string;
+    steps: string[];
+}
+/**
+ * Tables a recovery rebuilds from the others: search indexes, the vector index, what the indexing finds, and the
+ * vectors, which a search by meaning computes again for any text that has none.
+ */
+export declare const isDerivedTable: (table: string, searchIndexes: readonly string[]) => boolean;
+export declare const explainDamage: (health: StoreHealth, command: string) => DamageExplanation | null;

package/dist/store/damage.js

@@ -0,0 +1,58 @@
+const DERIVED = new Set(["mentions", "involvements", "embeddings"]);
+const named = (tables) => tables.length <= 5 ? tables.join(", ") : `${tables.slice(0, 5).join(", ")} and ${tables.length - 5} more`;
+/**
+ * Tables a recovery rebuilds from the others: search indexes, the vector index, what the indexing finds, and the
+ * vectors, which a search by meaning computes again for any text that has none.
+ */
+export const isDerivedTable = (table, searchIndexes) => DERIVED.has(table) ||
+    table.startsWith("vector_index_") ||
+    searchIndexes.some((index) => table === index || table.startsWith(`${index}_`));
+const WIRECAT_UNITS = ["memo-*", "mail-*", "tg-*", "max-*", "wirecat-*"];
+export const explainDamage = (health, command) => {
+    if (health.ok)
+        return null;
+    const indexNames = (health.searchIndexes ?? []).map((index) => index.name);
+    const badIndexes = (health.searchIndexes ?? []).filter((index) => !index.ok).map((index) => index.name);
+    const tables = (health.damagedTables ?? []).map((one) => one.table).filter((table) => table !== null);
+    const sources = tables.filter((table) => !isDerivedTable(table, indexNames));
+    const derived = [...new Set([...tables.filter((table) => isDerivedTable(table, indexNames)), ...badIndexes])];
+    const unopened = health.error !== undefined;
+    const what = unopened
+        ? `the store file cannot be opened: ${health.error}`
+        : health.checked === "quick"
+            ? "the store file's header or schema is damaged"
+            : `the store file is damaged: ${health.problems ?? 0} problems` +
+                (sources.length ? ` in the data of ${named(sources)}` : "") +
+                (derived.length ? `${sources.length ? ", and" : " in"} the search data of ${named(derived)}` : "");
+    const impact = [
+        ...(sources.length
+            ? [`some rows of ${named(sources)} cannot be read; a recovery keeps every row it can read and names the rest`]
+            : []),
+        ...(derived.length
+            ? [`searches may miss results or fail; ${named(derived)} hold nothing that is not elsewhere, and are rebuilt`]
+            : []),
+        "reads that do not touch a damaged page work; a write that touches one fails until the store is recovered",
+    ];
+    return {
+        what,
+        causes: [
+            "the computer lost power or crashed, or the disk filled up, while a tool was writing",
+            "the file was copied, restored or synced while a tool had it open, or it sits in a synced or network folder",
+            "a fault of the disk itself",
+        ],
+        investigate: [
+            `journalctl --user ${WIRECAT_UNITS.map((unit) => `-u '${unit}'`).join(" ")} --since -14d | grep -i -e malformed -e corrupt -e 'disk full'`,
+            "journalctl -k --since -14d | grep -i -e 'I/O error' -e nvme -e ata",
+            `df -h ${health.path.replace(/\/[^/]*$/, "")}`,
+            ...(health.checked === "quick" ? [`${command} store recover`] : []),
+        ],
+        impact,
+        externalUnaffected: "only this computer's copy is damaged: Telegram, MAX, the mail servers and Google Drive keep their own data, " +
+            "so whatever is lost here can be fetched again by a sync",
+        steps: [
+            "stop every timer and server of the WireCat tools; `store recover run` lists the ones still running",
+            `${command} store recover run`,
+            "run the fetch commands it prints, then start the timers again",
+        ],
+    };
+};

package/dist/store/health.d.ts

@@ -0,0 +1,50 @@
+import type { CacheDatabase } from "./driver.js";
+/** One table's share of what `PRAGMA quick_check` found; `table` is null for pages no table claims. */
+export interface DamagedTable {
+    table: string | null;
+    problems: number;
+    /** The first line SQLite gave for it: page and cell numbers, never row content. */
+    sample: string;
+}
+export interface SearchIndexHealth {
+    name: string;
+    ok: boolean;
+    error?: string;
+}
+export interface StoreHealth {
+    path: string;
+    /** `quick`: the file header and the schema only, in milliseconds. `deep`: every page and every search index. */
+    checked: "quick" | "deep";
+    ok: boolean;
+    error?: string;
+    file?: {
+        bytes: number;
+        pages: number;
+        pageSize: number;
+        freePages: number;
+    };
+    damagedTables?: DamagedTable[];
+    /** Lines `quick_check` gave in all, capped at `QUICK_CHECK_LIMIT`. */
+    problems?: number;
+    searchIndexes?: SearchIndexHealth[];
+    ms: number;
+}
+export declare const QUICK_CHECK_LIMIT = 10000;
+/** What `doctor` checks by default, said where it answers. */
+export declare const QUICK_HEALTH_CHECKS = "the file header, its size against its page count, and the schema's own pages";
+export declare const fts5Tables: (database: CacheDatabase) => {
+    name: string;
+    sql: string;
+    external: boolean;
+}[];
+/** Groups the lines by the table whose tree they name: `Tree <root page> …` or `NULL value in <table>.<column>`. */
+export declare const damagedTables: (database: CacheDatabase, lines: string[]) => DamagedTable[];
+/** `rank = 0` checks the index's own structure, the only check a contentless index has; it writes nothing. */
+export declare const searchIndexHealth: (database: CacheDatabase) => SearchIndexHealth[];
+/**
+ * The store's health without changing it. `quick` takes milliseconds at any size; `deep` reads every page
+ * (about 30 s for 6 GB) and checks every search index, under a transaction it rolls back.
+ */
+export declare const storeHealth: (path: string, { deep }?: {
+    deep?: boolean;
+}) => Promise<StoreHealth>;