waterplane 0.0.1 → 0.1.6

package/packages/host/dist/healthwatch.js

@@ -0,0 +1,334 @@
+/**
+ * The per-repo health index, kept current without being asked.
+ *
+ * The pure arithmetic is `shared/healthindex.ts`; this is the plumbing around
+ * it: where the series file is, when the engine is run again, what is cached
+ * for `/api/repos`, and the one push a called move earns.
+ *
+ *  - **Weekly refresh.** An hourly sweep runs `refreshRepoHealth` for every repo
+ *    that already has a series file and whose last host refresh is over 7 days
+ *    old — SEQUENTIALLY, never two engines at once. A repo with no series file
+ *    is never started: measuring a repo for the first time is a person's tap.
+ *  - **Boot computes without refreshing**, so the chip has a value at once.
+ *  - **`/api/repos` reads the cache only** (`summaryFor`); the engine never runs
+ *    in a request path. Unknown ⇒ absent, never 0. The cache is keyed to the
+ *    series file's mtime+size: the file is also rewritten from OUTSIDE this
+ *    host (a CLI re-cut, the VS Code extension), and a chip cached at boot
+ *    then read "Health 112" beside an index view computing 98 off the file.
+ *    A changed stamp re-derives the index from the file (one stat per call,
+ *    no engine run).
+ *  - **One push per repo per week**: `(week, kind)` last notified is persisted
+ *    in `<STATE_DIR>/healthindex.json`, so a restart does not re-fire.
+ *  - **A NEW severe alert pushes once** (see `maybeNotifySevere`): keyed
+ *    `(week, alert:subject)` in the same state file, written before the push.
+ *  - Failures degrade to absent + a reason, logged once; no push on error.
+ *  - `WATERPLANE_HEALTH_WEEKLY=0` stops the refresh and the push (the chip and
+ *    the route still read whatever series exists).
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { BRAND, LEGACY, healthIndexResponseOf, logTag, repoHealthIndexOf, } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+import { contextLimitsFor } from "./compliance.js";
+import { discoverTargets } from "./repos.js";
+import { refreshRepoHealth, resolveRepoHealthEngine } from "./repohealth.js";
+import { engineApproved } from "./repohealthapproval.js";
+import { env } from "./env.js";
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+const SWEEP_MS = Math.max(5_000, Number(env("HEALTH_SWEEP_MS") || 60 * 60_000));
+/** A repo is refreshed when its last refresh is older than this. */
+export const HEALTH_REFRESH_MS = 7 * 24 * 60 * 60_000;
+/** After a refresh that did not succeed, wait this long before trying that repo again. */
+const RETRY_MS = 6 * 60 * 60_000;
+export const SERIES_FILE = "repohealth.jsonl";
+/** Rows exist and size was measured, but none carries `lineMean`: an older engine wrote the series. */
+export const STALE_ENGINE_REASON = `this series was measured by an older engine (size has no line-weighted mean) and needs re-measuring: rm <repo>/${BRAND.stateDirName}/repohealth.jsonl && node tools/repohealth.mjs update --root=<repo>`;
+/** The series file for a worktree: current state dir name first, then each legacy one. */
+export function seriesPathOf(wt) {
+    for (const d of [BRAND.stateDirName, ...LEGACY.map((l) => l.stateDirName)]) {
+        const p = join(wt, d, SERIES_FILE);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function readSeriesFile(wt) {
+    const p = seriesPathOf(wt);
+    if (!p)
+        return null;
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function seriesStampOf(wt) {
+    const p = seriesPathOf(wt);
+    if (!p)
+        return null;
+    try {
+        const st = statSync(p);
+        return `${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return null;
+    }
+}
+const keyOf = (wt) => { try {
+    return realpathSync(wt);
+}
+catch {
+    return wt;
+} };
+export class HealthWatch {
+    deps;
+    state = new Map();
+    cache = new Map();
+    /** The series stamp each cache entry was derived from ("none" = no file). */
+    stamps = new Map();
+    lastAttempt = new Map();
+    logged = new Set();
+    timer = null;
+    sweeping = false;
+    path;
+    constructor(deps) {
+        this.deps = deps;
+        this.path = deps.statePath ?? join(hostStateDir(deps.root), "healthindex.json");
+        const raw = readJsonGuarded(this.path, null);
+        for (const [wt, v] of Object.entries(raw?.repos ?? {})) {
+            if (!v || typeof v !== "object")
+                continue;
+            this.state.set(wt, {
+                lastRefresh: Number.isFinite(v.lastRefresh) ? v.lastRefresh : undefined,
+                notified: typeof v.notified === "string" ? v.notified : undefined,
+                alerted: Array.isArray(v.alerted) ? v.alerted.filter((x) => typeof x === "string") : undefined,
+            });
+        }
+    }
+    now() { return (this.deps.now ?? Date.now)(); }
+    weekly() { return (this.deps.enabled ?? (() => env("HEALTH_WEEKLY") !== "0"))(); }
+    text(wt) { return (this.deps.readSeries ?? readSeriesFile)(wt); }
+    stamp(wt) {
+        try {
+            return (this.deps.seriesStamp ?? seriesStampOf)(wt) ?? "none";
+        }
+        catch {
+            return "none";
+        }
+    }
+    /** Compute from existing series for every repo, WITHOUT refreshing; then start the sweep. */
+    async start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.sweep(), SWEEP_MS);
+        this.timer.unref?.();
+        try {
+            for (const r of await this.deps.repos())
+                this.recompute(r.worktreePath);
+        }
+        catch (e) {
+            this.logOnce("boot", e);
+        }
+        void this.sweep();
+    }
+    stop() { if (this.timer)
+        clearInterval(this.timer); this.timer = null; }
+    /**
+     * The summary for `/api/repos`, or undefined. Served from the cache while the
+     * series file is the one it was derived from; re-derived from the file (no
+     * engine) when its stamp moved since — never a number older than the file.
+     */
+    summaryFor(wt) {
+        const k = keyOf(wt);
+        if (this.stamps.get(k) !== this.stamp(wt))
+            this.recompute(wt);
+        return this.cache.get(k);
+    }
+    /** The whole answer for the route, computed from the series file now (cheap, no engine). */
+    respond(wt) {
+        const lr = this.state.get(keyOf(wt))?.lastRefresh;
+        const lastRefresh = lr ? new Date(lr).toISOString() : null;
+        try {
+            return healthIndexResponseOf(this.text(wt), {
+                warnChars: this.deps.warnChars(wt), now: this.now(), lastRefresh,
+                noSeries: "this repo has no repo-health series yet", staleEngine: STALE_ENGINE_REASON,
+            });
+        }
+        catch (e) {
+            this.logOnce(wt, e);
+            return { series: null, move: null, words: null, lastRefresh, reason: "the series could not be read" };
+        }
+    }
+    /** Recompute one repo's cache from its series file. Returns the response used. */
+    recompute(wt) {
+        const k = keyOf(wt);
+        // Stamp BEFORE reading: a write landing mid-read leaves a stale stamp, so
+        // the next call re-derives rather than keeping the half-old answer.
+        this.stamps.set(k, this.stamp(wt));
+        const r = this.respond(wt);
+        const s = repoHealthIndexOf(r.series, r.move);
+        if (s)
+            this.cache.set(k, s);
+        else
+            this.cache.delete(k);
+        return r;
+    }
+    /**
+     * One push when the latest scored week has a severe alert subject the previous
+     * scored week did not. Silent on the first scored week (no previous point) and
+     * for a repo severe all along (the previous point is computed from the same
+     * rows, so a re-measured history never reads as news). Sent together with a
+     * move in the same sweep (`maybeNotify`); worst first.
+     */
+    maybeNotifySevere(wt, r) {
+        if (!this.weekly() || !r.series)
+            return null;
+        const pts = r.series.points;
+        const last = pts[pts.length - 1];
+        const prev = pts[pts.length - 2];
+        if (!last || !prev)
+            return null;
+        // A gap week is a central or prereg definition change: its alerts are the new
+        // definition's first reading, not news about the repo.
+        if (last.gap)
+            return null;
+        const was = new Set(prev.alerts.filter((a) => a.level === "severe").map((a) => a.subject));
+        const k = keyOf(wt);
+        const st = this.state.get(k) ?? {};
+        const done = new Set((st.alerted ?? []).filter((x) => x.startsWith(`${last.week}:`)));
+        const fresh = last.alerts
+            .filter((a) => a.level === "severe" && !was.has(a.subject) && !done.has(`${last.week}:alert:${a.subject}`))
+            .sort((a, b) => a.score - b.score);
+        if (!fresh.length)
+            return null;
+        // Remember BEFORE sending: a crash between the two loses a push, never repeats one.
+        for (const a of fresh)
+            done.add(`${last.week}:alert:${a.subject}`);
+        this.state.set(k, { ...st, alerted: [...done] });
+        this.persist();
+        return { title: (name) => `${name}: severe health warning`, texts: fresh.map((a) => a.text) };
+    }
+    /**
+     * ONE push per repo per sweep, because both kinds share a tag and the later
+     * would silently replace the earlier. A new severe alert leads (title, its
+     * texts), and a called move's body follows it; either alone is sent as itself.
+     */
+    maybeNotify(wt, repoId, repoName, r) {
+        const move = this.maybeNotifyMove(wt, repoName, r);
+        const severe = this.maybeNotifySevere(wt, r);
+        const tag = `health:${repoId}`;
+        if (severe) {
+            const body = [...severe.texts, ...(move ? [move.body] : [])].join("\n");
+            this.deps.notify("health", { title: severe.title(repoName), body, tag });
+        }
+        else if (move) {
+            this.deps.notify("health", { title: move.title, body: move.body, tag });
+        }
+    }
+    maybeNotifyMove(wt, repoName, r) {
+        if (!this.weekly() || !r.series || !r.move?.kind || !r.words)
+            return null;
+        const week = r.series.points[r.series.points.length - 1]?.week;
+        if (!week)
+            return null;
+        const k = keyOf(wt);
+        const mark = `${week}:${r.move.kind}`;
+        const st = this.state.get(k) ?? {};
+        if (st.notified === mark)
+            return null;
+        // Remember BEFORE sending: a crash between the two loses a push, never repeats one.
+        this.state.set(k, { ...st, notified: mark });
+        this.persist();
+        const title = r.words.title.includes(repoName) ? r.words.title : `${repoName}: ${r.words.title}`;
+        return { title, body: r.words.body };
+    }
+    /** Whether a repo with a series is due its weekly engine run. */
+    due(wt) {
+        const k = keyOf(wt);
+        const now = this.now();
+        const last = this.state.get(k)?.lastRefresh;
+        if (last !== undefined && now - last <= HEALTH_REFRESH_MS)
+            return false;
+        const tried = this.lastAttempt.get(k);
+        return !(tried !== undefined && now - tried < RETRY_MS);
+    }
+    /** Note that a refresh succeeded elsewhere (the manual route) and recompute. */
+    refreshed(wt) {
+        const k = keyOf(wt);
+        this.state.set(k, { ...this.state.get(k), lastRefresh: this.now() });
+        this.persist();
+        return this.recompute(wt);
+    }
+    async sweep() {
+        if (this.sweeping)
+            return;
+        this.sweeping = true;
+        try {
+            const repos = await this.deps.repos();
+            for (const r of repos) {
+                const wt = r.worktreePath;
+                try {
+                    if (this.text(wt) === null) {
+                        this.cache.delete(keyOf(wt));
+                        continue;
+                    }
+                    if (this.weekly() && this.due(wt)) {
+                        this.lastAttempt.set(keyOf(wt), this.now());
+                        let ok = false;
+                        try {
+                            ok = await this.deps.refresh(wt);
+                        }
+                        catch (e) {
+                            this.logOnce(wt, e);
+                        }
+                        if (ok)
+                            this.refreshed(wt);
+                    }
+                    this.maybeNotify(wt, r.id, r.repoName, this.recompute(wt));
+                }
+                catch (e) {
+                    this.logOnce(wt, e);
+                }
+            }
+        }
+        catch (e) {
+            this.logOnce("sweep", e);
+        }
+        finally {
+            this.sweeping = false;
+        }
+    }
+    logOnce(key, e) {
+        if (this.logged.has(key))
+            return;
+        this.logged.add(key);
+        console.log(`${logTag} health index · ${key}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    persist() {
+        try {
+            mkdirSync(hostStateDir(this.deps.root), { recursive: true });
+            const repos = {};
+            for (const [k, v] of this.state)
+                repos[k] = v;
+            writeJsonAtomic(this.path, { version: 1, repos }, { space: 2 });
+        }
+        catch { /* an unwritable state dir means a re-notify after a restart, not a crash */ }
+    }
+}
+/** The production wiring: the real discovery, engine and context-weight line. */
+export function createHealthWatch(root, notify) {
+    return new HealthWatch({
+        root, notify,
+        repos: async () => (await discoverTargets(root)).filter((t) => t.isPrimary).map((t) => ({ id: t.id, repoName: t.repoName, worktreePath: t.worktreePath })),
+        refresh: async (wt) => {
+            // A repo's own committed engine never runs unapproved: skip, don't throw.
+            // (The bundled engine's refresh drops the repo's own commands by itself.)
+            if (resolveRepoHealthEngine(wt)?.kind === "repo" && !engineApproved(wt, root))
+                return false;
+            return (await refreshRepoHealth(wt, { root })).last?.ok === true;
+        },
+        warnChars: (wt) => contextLimitsFor(wt).effective.maxChars ?? null,
+    });
+}
+//# sourceMappingURL=healthwatch.js.map

package/packages/host/dist/healthwatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthwatch.js","sourceRoot":"","sources":["../src/healthwatch.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/host.d.ts

@@ -0,0 +1,51 @@
+import type { HostStat } from "@waterplane/shared";
+/** CPU/memory/load snapshot of this machine. Cheap, synchronous, no shell. */
+export declare function hostStat(): HostStat;
+export interface GpuStat {
+    pct: number;
+    memInUse: number;
+}
+/**
+ * Parse `ioreg -r -d 1 -c IOAccelerator`'s text dump for the two
+ * `PerformanceStatistics` fields this app draws.
+ *
+ * Exported so the shape is pinned with no GPU present — the same reason
+ * `parsePs` is exported from `localrt.ts`. This is not plist/JSON, just a
+ * key=value dump; it degrades to `null` on a miss rather than a 0 standing in
+ * for "unreadable" (this repo's rule: a heuristic degrades to absent, never
+ * to a plausible wrong number).
+ *
+ * **Both keys are read from the SAME `PerformanceStatistics` block, and only
+ * when there is exactly one.** A machine with two accelerators (an Intel
+ * iGPU+dGPU pair, a Mac Pro) prints one block per device; scanning the two
+ * keys independently over the whole dump could pair one device's utilization
+ * with the OTHER device's memory figure — a composite neither device reports,
+ * which is the "plausible wrong number" this rule exists to forbid. Several
+ * blocks is therefore `null`, the same as none.
+ */
+export declare function parseGpuIoreg(text: string): GpuStat | null;
+/**
+ * GPU utilization + memory in use, off `ioreg` — Apple Silicon only. No other
+ * platform has a reader here, so this returns `null` on anything but macOS
+ * with no subprocess spawned at all, and `null` again on any failure of the
+ * one it does spawn (`ioreg` missing, no accelerator, unparsable output).
+ * Costs one subprocess call, so it is only worth polling from a loop that is
+ * already paying for one (`localrt.ts`).
+ */
+export declare function readGpuStat(): Promise<GpuStat | null>;
+/**
+ * Capture the whole desktop screen to `destPath` (a .png). Platform-specific;
+ * throws if no capture tool is available. macOS uses the built-in
+ * `screencapture`; a host in WSL asks Windows (PowerShell, the primary display,
+ * DPI-aware so a scaled display is not captured at its logical size); other Linux
+ * tries common tools in turn.
+ */
+export declare function takeScreenshot(destPath: string): Promise<void>;
+/** PowerShell 5.1: the primary display at its real pixel size, as a PNG at `winPath`. */
+export declare function windowsScreenshotScript(winPath: string): string;
+/**
+ * Set the desktop host's system clipboard to `text` (phone→desktop paste).
+ * Platform-specific: macOS `pbcopy`, Windows `clip`, Linux tries the common
+ * tools in turn. Throws if no clipboard tool is available.
+ */
+export declare function setHostClipboard(text: string): Promise<void>;

package/packages/host/dist/host.js

@@ -0,0 +1,153 @@
+/** Desktop-host introspection: resource load + screen capture of the machine
+ *  running the daemon. The phone uses these to peek at "what's going on there". */
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { execFileP as pexecFile } from "./proc.js";
+import { encodePs, isWsl, psQuote } from "./ocrlocal.js";
+/** CPU/memory/load snapshot of this machine. Cheap, synchronous, no shell. */
+export function hostStat() {
+    const load = os.loadavg();
+    const cores = os.cpus().length || 1;
+    return {
+        platform: process.platform,
+        hostname: os.hostname(),
+        cores,
+        loadavg: [load[0], load[1], load[2]],
+        cpuPct: Math.round((load[0] / cores) * 100),
+        memTotal: os.totalmem(),
+        memFree: os.freemem(),
+        uptime: os.uptime(),
+        checkedAt: Date.now(),
+    };
+}
+/**
+ * Parse `ioreg -r -d 1 -c IOAccelerator`'s text dump for the two
+ * `PerformanceStatistics` fields this app draws.
+ *
+ * Exported so the shape is pinned with no GPU present — the same reason
+ * `parsePs` is exported from `localrt.ts`. This is not plist/JSON, just a
+ * key=value dump; it degrades to `null` on a miss rather than a 0 standing in
+ * for "unreadable" (this repo's rule: a heuristic degrades to absent, never
+ * to a plausible wrong number).
+ *
+ * **Both keys are read from the SAME `PerformanceStatistics` block, and only
+ * when there is exactly one.** A machine with two accelerators (an Intel
+ * iGPU+dGPU pair, a Mac Pro) prints one block per device; scanning the two
+ * keys independently over the whole dump could pair one device's utilization
+ * with the OTHER device's memory figure — a composite neither device reports,
+ * which is the "plausible wrong number" this rule exists to forbid. Several
+ * blocks is therefore `null`, the same as none.
+ */
+export function parseGpuIoreg(text) {
+    const blocks = [...text.matchAll(/"PerformanceStatistics"\s*=\s*\{([^}]*)\}/g)];
+    if (blocks.length !== 1)
+        return null;
+    const body = blocks[0][1];
+    const pct = /"Device Utilization %"=(\d+)/.exec(body);
+    const mem = /"In use system memory"=(\d+)/.exec(body);
+    if (!pct || !mem)
+        return null;
+    return { pct: Number(pct[1]), memInUse: Number(mem[1]) };
+}
+/**
+ * GPU utilization + memory in use, off `ioreg` — Apple Silicon only. No other
+ * platform has a reader here, so this returns `null` on anything but macOS
+ * with no subprocess spawned at all, and `null` again on any failure of the
+ * one it does spawn (`ioreg` missing, no accelerator, unparsable output).
+ * Costs one subprocess call, so it is only worth polling from a loop that is
+ * already paying for one (`localrt.ts`).
+ */
+export async function readGpuStat() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const { stdout } = await pexecFile("ioreg", ["-r", "-d", "1", "-c", "IOAccelerator"], { timeout: 1500, maxBuffer: 8 * 1024 * 1024 });
+        return parseGpuIoreg(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture the whole desktop screen to `destPath` (a .png). Platform-specific;
+ * throws if no capture tool is available. macOS uses the built-in
+ * `screencapture`; a host in WSL asks Windows (PowerShell, the primary display,
+ * DPI-aware so a scaled display is not captured at its logical size); other Linux
+ * tries common tools in turn.
+ */
+export async function takeScreenshot(destPath) {
+    if (process.platform === "darwin") {
+        await pexecFile("screencapture", ["-x", destPath]); // -x = silent (no shutter)
+        return;
+    }
+    if (process.platform === "linux" && isWsl()) {
+        const { stdout } = await pexecFile("wslpath", ["-w", destPath], { timeout: 5000 });
+        await pexecFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encodePs(windowsScreenshotScript(stdout.trim()))], { timeout: 30_000 });
+        return;
+    }
+    if (process.platform === "linux") {
+        const attempts = [
+            ["gnome-screenshot", ["-f", destPath]],
+            ["scrot", ["-o", destPath]],
+            ["import", ["-window", "root", destPath]], // ImageMagick
+        ];
+        let lastErr;
+        for (const [bin, args] of attempts) {
+            try {
+                await pexecFile(bin, args);
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+            }
+        }
+        throw new Error(`no screenshot tool (install gnome-screenshot/scrot/imagemagick): ${String(lastErr)}`);
+    }
+    throw new Error(`screenshot unsupported on ${process.platform}`);
+}
+/** PowerShell 5.1: the primary display at its real pixel size, as a PNG at `winPath`. */
+export function windowsScreenshotScript(winPath) {
+    return `$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition 'using System.Runtime.InteropServices; public static class WpDpi { [DllImport("user32.dll")] public static extern bool SetProcessDPIAware(); }'
+$null = [WpDpi]::SetProcessDPIAware()
+Add-Type -AssemblyName System.Windows.Forms, System.Drawing
+$b = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds
+$bmp = New-Object System.Drawing.Bitmap $b.Width, $b.Height
+$g = [System.Drawing.Graphics]::FromImage($bmp)
+$g.CopyFromScreen($b.Left, $b.Top, 0, 0, $bmp.Size)
+$bmp.Save(${psQuote(winPath)}, [System.Drawing.Imaging.ImageFormat]::Png)
+$g.Dispose(); $bmp.Dispose()
+`;
+}
+/**
+ * Set the desktop host's system clipboard to `text` (phone→desktop paste).
+ * Platform-specific: macOS `pbcopy`, Windows `clip`, Linux tries the common
+ * tools in turn. Throws if no clipboard tool is available.
+ */
+export async function setHostClipboard(text) {
+    const candidates = process.platform === "darwin" ? [["pbcopy", []]]
+        : process.platform === "win32" ? [["clip", []]]
+            : [["wl-copy", []], ["xclip", ["-selection", "clipboard"]], ["xsel", ["--clipboard", "--input"]]];
+    let lastErr;
+    for (const [bin, args] of candidates) {
+        try {
+            await pipeToStdin(bin, args, text);
+            return;
+        }
+        catch (e) {
+            lastErr = e;
+        }
+    }
+    throw new Error(`no clipboard tool available on ${process.platform}: ${String(lastErr)}`);
+}
+/** Run `bin args`, writing `input` to its stdin; resolve on clean exit. */
+function pipeToStdin(bin, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args);
+        child.on("error", reject); // ENOENT: tool not installed
+        child.stdin.on("error", reject); // EPIPE: tool bailed before reading
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`${bin} exited ${code}`))));
+        child.stdin.end(input);
+    });
+}
+//# sourceMappingURL=host.js.map

package/packages/host/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/hoststore.d.ts

@@ -0,0 +1,24 @@
+import type { HostStoreOutcome, HostStoreReport } from "@waterplane/shared";
+/** The store directory — the one every store constructor writes under. */
+export declare function hostStoreDir(root: string): string;
+/**
+ * What the store holds, as rows.
+ *
+ * Never throws: an unreadable store answers an empty report with `partial`, the
+ * way every other reading in this daemon degrades to absent rather than to a
+ * wrong number.
+ */
+export declare function hostStoreReport(root: string, now?: number): HostStoreReport;
+/**
+ * Remove one clearable row's files.
+ *
+ * `at` is the instant the report a person read was taken: nothing written since
+ * goes. That is the same promise the transport sweep makes by sending its rows,
+ * kept here with one number because the individual files were never the
+ * decision — nobody chooses which thumbnails to keep.
+ *
+ * Refuses in words rather than silently doing nothing: an id that is not
+ * clearable, or not a catalogue id at all, comes back as a sentence with
+ * `deleted: 0`.
+ */
+export declare function clearHostStore(root: string, store: string, at: number): HostStoreOutcome;