cursedbelt-server 1.0.0

package/dist/server/retention/store.js

@@ -0,0 +1,251 @@
+/**
+ * The fleet's retention SOURCE OF TRUTH on disk — where declarations are
+ * published and where the owner's overrides are read from.
+ *
+ * ── Why a file and not an API ───────────────────────────────────────────────
+ * The station has to show, and let the owner change, the policy for apps that
+ * are not running. Most satellites are started on demand; `orch` is a daemon but
+ * `notes`, `roms`, `vault` and the rest are usually down, and the whole point of
+ * the UI is to answer "what is keeping my disk full" without booting anything.
+ * An HTTP endpoint per app could not answer that, would need an auth model per
+ * app, and would make a stopped app look policy-less rather than idle.
+ *
+ * So an app PUBLISHES its declarations (a description of what it owns, plus what
+ * it last measured and swept) and READS overrides. The station reads every
+ * publication and is the only writer of overrides. Nothing has to be up for the
+ * owner to see the fleet, and no app parses another app's database.
+ *
+ * ── One file per app, deliberately ──────────────────────────────────────────
+ * `apps/<app>.json`, never one shared registry file. Several satellites boot at
+ * once (the station's start-all, a `bun run dev` fan-out, launchd at login), and
+ * a shared file that concurrent writers read-modify-write loses records — the
+ * exact bug the agent-coordination board is one-file-per-record to avoid. Each
+ * app owns exactly one path and can only ever clobber itself.
+ *
+ * `overrides.json` IS a single file, because it has a single writer (the
+ * station) and because the owner's settings for the whole fleet are one thing to
+ * back up, copy to a box, or read at a glance.
+ *
+ * ── Where it lives ──────────────────────────────────────────────────────────
+ * `<app-data-home>/retention` — one root shared by every local app, so the
+ * station sees one fleet. The home is CONFIGURATION ({@link resolveAppDataHome}):
+ * `$APP_DATA_HOME` when a machine keeps every app's data under one root, else the
+ * OS's own convention (`$XDG_DATA_HOME`, `~/Library/Application Support`).
+ *
+ * 🔴 It was `~/<a private dotfolder>` until 2026-09-13, hardcoded, in a PUBLISHED
+ * package — so anyone who installed cursedbelt got a library hunting for one
+ * person's directory layout. A library may know what its caller told it and what
+ * the OS says; it may not know the name of a folder in somebody's home.
+ *
+ * A deployed box under `ProtectSystem=strict` has only its own data dir writable,
+ * so it falls back to `$APP_DATA_DIR/retention`: the app still sweeps on the same
+ * code and the same defaults, and a station instance on that box reads that box's
+ * fleet. The resolution probes WRITABILITY rather than assuming, because the
+ * failure it prevents — an app whose every publish silently EROFS-es — is
+ * invisible until someone asks why the UI is empty.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome } from "../paths/appDataHome";
+import { retentionKey } from "./policy";
+/**
+ * A FUNCTION, not a shared constant. `writeRetentionOverride` mutates what
+ * `readRetentionOverrides` hands it, so a module-level empty object would be
+ * aliased into every caller: the first write on a machine with no overrides file
+ * would edit the constant itself, and a later read of an unrelated home would
+ * return those overrides. Caught by `store.test.ts`.
+ */
+const emptyOverrides = () => ({ version: 1, updatedAt: 0, overrides: {} });
+let cachedHome = null;
+/** Can we create and write inside this directory? Probed, never assumed. */
+function isUsable(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, ".write-probe");
+        writeFileSync(probe, "");
+        rmSync(probe, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the retention home. See the module note for the ordering rationale.
+ * Cached per process — it is consulted on every sweep and cannot change under a
+ * running app.
+ */
+export function resolveRetentionHome(env = process.env) {
+    if (cachedHome)
+        return cachedHome;
+    const candidates = [];
+    if (env.RETENTION_HOME)
+        candidates.push(env.RETENTION_HOME);
+    // An explicitly CONFIGURED home is used whether or not it exists yet — the
+    // operator naming it is the statement that it is the right place.
+    const configured = env[APP_DATA_HOME_ENV]?.trim();
+    if (configured)
+        candidates.push(join(configured, "retention"));
+    const conventional = resolveAppDataHome({ env });
+    // The OS convention is only PREFERRED when it is already there: on a deployed
+    // box creating it would either fail (read-only namespace) or strand a
+    // publication somewhere no station instance looks.
+    if (!configured && existsSync(conventional))
+        candidates.push(join(conventional, "retention"));
+    if (env.APP_DATA_DIR)
+        candidates.push(join(env.APP_DATA_DIR, "retention"));
+    candidates.push(join(conventional, "retention"));
+    for (const candidate of candidates) {
+        if (isUsable(candidate)) {
+            cachedHome = candidate;
+            return candidate;
+        }
+    }
+    // Nothing is writable — return the conventional path anyway. Every writer here
+    // is best-effort and will log its failure; retention must not stop an app from
+    // booting.
+    cachedHome = join(conventional, "retention");
+    return cachedHome;
+}
+/** Test seam — point the home somewhere else for this process. */
+export function setRetentionHomeForTests(home) {
+    cachedHome = home;
+}
+const appsDir = (home) => join(home, "apps");
+const overridesPath = (home) => join(home, "overrides.json");
+/** A file name cannot be derived from an app key without pinning the charset. */
+const SAFE_APP = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Write whole, atomically: a reader must never see half a file. `rename` inside
+ * one directory is atomic on every filesystem this fleet runs on, and the temp
+ * name carries the pid so two writers cannot share a scratch path.
+ */
+function writeJsonAtomic(path, value) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+function readJson(path, fallback) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // Absent is the normal first-run case; corrupt is a truncated write from a
+        // killed process. Both mean "no settings yet" — never a boot failure.
+        return fallback;
+    }
+}
+/**
+ * Publish one app's resources. Best-effort by contract: a retention publication
+ * that cannot be written is a missing row in a dashboard, and must never take
+ * down the app that owns the data.
+ */
+export function publishRetention(publication, options = {}) {
+    const home = options.home ?? resolveRetentionHome();
+    if (!SAFE_APP.test(publication.app))
+        return false;
+    try {
+        mkdirSync(appsDir(home), { recursive: true });
+        writeJsonAtomic(join(appsDir(home), `${publication.app}.json`), {
+            version: 1,
+            publishedAt: Date.now(),
+            ...publication,
+        });
+        return true;
+    }
+    catch (error) {
+        options.log?.(`⚠️  retention: could not publish ${publication.app} — ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/** Every app's publication, newest-published first. */
+export function readRetentionRegistry(home = resolveRetentionHome()) {
+    const dir = appsDir(home);
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const publications = [];
+    for (const name of names) {
+        const parsed = readJson(join(dir, name), null);
+        if (parsed && Array.isArray(parsed.resources) && typeof parsed.app === "string") {
+            publications.push(parsed);
+        }
+    }
+    return publications.sort((a, b) => (b.publishedAt ?? 0) - (a.publishedAt ?? 0));
+}
+export function readRetentionOverrides(home = resolveRetentionHome()) {
+    const file = readJson(overridesPath(home), emptyOverrides());
+    if (!file || typeof file !== "object" || typeof file.overrides !== "object" || !file.overrides) {
+        return emptyOverrides();
+    }
+    return { version: 1, updatedAt: file.updatedAt ?? 0, overrides: file.overrides };
+}
+/**
+ * Apply one override. Read-modify-write, so an unrelated resource's setting is
+ * never lost to a concurrent edit of this one; the station is the only writer,
+ * which is what keeps that honest.
+ *
+ * A patch field set to `undefined` is left alone; set to `null` it is CLEARED,
+ * which is how the UI's "reset to default" works — deleting the key is the only
+ * way to make the declaration's default authoritative again, since a stored
+ * value that merely equals the default would freeze the resource at today's
+ * number if the default ever moves.
+ */
+export function writeRetentionOverride(app, id, patch, options = {}) {
+    const home = options.home ?? resolveRetentionHome();
+    const now = options.now ?? Date.now();
+    const file = readRetentionOverrides(home);
+    const key = retentionKey(app, id);
+    if (patch === null) {
+        delete file.overrides[key];
+    }
+    else {
+        const current = { ...(file.overrides[key] ?? {}) };
+        for (const field of ["days", "maxItems", "maxBytes"]) {
+            if (field in patch) {
+                const value = patch[field];
+                if (value === null)
+                    delete current[field];
+                else if (typeof value === "number" && Number.isFinite(value))
+                    current[field] = value;
+            }
+        }
+        if ("enabled" in patch) {
+            const value = patch.enabled;
+            if (value === null)
+                delete current.enabled;
+            else if (typeof value === "boolean")
+                current.enabled = value;
+        }
+        if ("note" in patch) {
+            const value = patch.note;
+            if (value === null || value === "")
+                delete current.note;
+            else if (typeof value === "string")
+                current.note = value.slice(0, 500);
+        }
+        current.updatedAt = now;
+        if (options.updatedBy)
+            current.updatedBy = options.updatedBy;
+        // An override with nothing left in it is not an override — drop the key so
+        // the resource reads as "default" rather than as a customized row that
+        // happens to change nothing.
+        const meaningful = current.days !== undefined ||
+            current.maxItems !== undefined ||
+            current.maxBytes !== undefined ||
+            current.enabled !== undefined ||
+            current.note !== undefined;
+        if (meaningful)
+            file.overrides[key] = current;
+        else
+            delete file.overrides[key];
+    }
+    file.updatedAt = now;
+    mkdirSync(home, { recursive: true });
+    writeJsonAtomic(overridesPath(home), file);
+    return file;
+}

package/dist/server/retention/sweeper.d.ts

@@ -0,0 +1,69 @@
+import type { EffectiveRetentionPolicy } from "./policy";
+import type { RetentionSweepReport } from "./store";
+import type { RetentionTarget } from "./target";
+/** Default cadence. Diagnostic data is not urgent; four sweeps a day is plenty. */
+export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
+/** How often to notice an overrides edit. */
+export declare const OVERRIDES_PULSE_MS = 60000;
+export interface ResourceOutcome {
+    key: string;
+    policy: EffectiveRetentionPolicy;
+    report: RetentionSweepReport;
+}
+export interface RetentionRunReport {
+    at: number;
+    resources: ResourceOutcome[];
+    /** Totals across every resource, for one honest log line. */
+    totals: {
+        aged: number;
+        overflow: number;
+        bytesFreed: number;
+        errors: number;
+    };
+}
+export interface RetentionSweeper {
+    start(): void;
+    stop(): void;
+    /** A supervisor's liveness poke — rebuild a timer lost to sleep/hibernate. */
+    ensureAlive(): void;
+    /** Run one sweep synchronously. Never throws. */
+    sweepNow(now?: number): RetentionRunReport;
+    /** Measure and republish without deleting anything — what the UI reads. */
+    publish(): void;
+    /** What each resource WOULD remove right now, under the current policy. */
+    preview(now?: number): Array<{
+        key: string;
+        policy: EffectiveRetentionPolicy;
+        aged: number;
+        overflow: number;
+    }>;
+    status(): {
+        app: string;
+        home: string;
+        disabled: boolean;
+        lastRun: RetentionRunReport | null;
+        nextRunAt: number | null;
+        lastError: string | null;
+    };
+}
+export interface CreateRetentionSweeperOptions {
+    app: string;
+    targets: RetentionTarget[];
+    intervalMs?: number;
+    bootDelayMs?: number;
+    /** How often to notice an overrides edit. Injectable so tests need not wait a minute. */
+    pulseMs?: number;
+    /** `local` / `prod` / `dev` — informational, shown in the UI. */
+    instance?: string;
+    /**
+     * Kill switch. `RETENTION_DISABLED=1` in the app's environment stops every
+     * sweep while still publishing measurements, so the UI shows the sizes AND
+     * says plainly that nothing is being pruned. A silent kill switch would be
+     * indistinguishable from a broken timer.
+     */
+    disabled?: boolean;
+    home?: string;
+    log?: (line: string) => void;
+    now?: () => number;
+}
+export declare function createRetentionSweeper(options: CreateRetentionSweeperOptions): RetentionSweeper;

package/dist/server/retention/sweeper.js

@@ -0,0 +1,289 @@
+/**
+ * The sweep RUNTIME — one timer per app that applies the fleet policy to every
+ * resource that app declared, publishes what it found, and never takes the app
+ * down when it fails.
+ *
+ * Generalized from `apps/orch/src/server/eventRetention.ts`, which had all of
+ * this already for exactly one table: the boot delay, the liveness kick, the
+ * never-throw sweep, the status readout. Those were not incidental — each is a
+ * failure that had already happened once — so they are kept verbatim in spirit
+ * and made to serve every resource in the fleet instead of one.
+ *
+ * ── Overrides take effect within a minute, not within an interval ───────────
+ * A sweep runs every 6 hours by default. If the owner's change in the station UI
+ * only applied on that cadence, the control would appear to do nothing for most
+ * of a day — the "button that visibly does nothing" failure this fleet has
+ * already paid for elsewhere. So a light PULSE timer stats `overrides.json` once
+ * a minute and sweeps early when it has changed since the last applied read.
+ * One `stat` a minute is free; a UI whose settings look inert is not.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { assertRetentionDeclaration, resolveRetentionPolicy, retentionKey } from "./policy";
+import { publishRetention, readRetentionOverrides, resolveRetentionHome } from "./store";
+/** Default cadence. Diagnostic data is not urgent; four sweeps a day is plenty. */
+export const DEFAULT_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** How often to notice an overrides edit. */
+export const OVERRIDES_PULSE_MS = 60_000;
+const formatBytes = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+};
+export function createRetentionSweeper(options) {
+    const { app, targets } = options;
+    const intervalMs = options.intervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    const bootDelayMs = options.bootDelayMs ?? 60_000;
+    const home = options.home ?? resolveRetentionHome();
+    const log = options.log ?? ((line) => console.log(`[${app}] ${line}`));
+    const now = options.now ?? (() => Date.now());
+    const disabled = options.disabled ?? process.env.RETENTION_DISABLED === "1";
+    // Fail at construction, where the stack names the app — not at the first sweep
+    // six hours later, in a daemon nobody is watching. A duplicate key is the
+    // nastier of the two: two resources sharing one override would let the owner
+    // change a number and silently govern the wrong thing.
+    const seenKeys = new Set();
+    for (const target of targets) {
+        assertRetentionDeclaration(target.declaration);
+        const key = retentionKey(target.declaration.app, target.declaration.id);
+        if (seenKeys.has(key)) {
+            throw new Error(`retention: duplicate resource key "${key}" — ids must be unique within an app`);
+        }
+        seenKeys.add(key);
+    }
+    let timer = null;
+    let pulse = null;
+    let stopped = true;
+    let nextRunAt = null;
+    let lastRun = null;
+    let lastError = null;
+    let lastBeatAt = now();
+    let appliedOverridesAt = 0;
+    const overridesFile = join(home, "overrides.json");
+    function policiesNow() {
+        const file = readRetentionOverrides(home);
+        appliedOverridesAt = Math.max(appliedOverridesAt, file.updatedAt ?? 0);
+        const resolved = new Map();
+        for (const target of targets) {
+            const declaration = target.declaration;
+            const policy = resolveRetentionPolicy(declaration, file.overrides[`${declaration.app}:${declaration.id}`]);
+            resolved.set(policy.key, policy);
+        }
+        return resolved;
+    }
+    /** Measure every resource and write the publication the station UI reads. */
+    function publish(lastReports) {
+        const resources = [];
+        for (const target of targets) {
+            const key = `${target.declaration.app}:${target.declaration.id}`;
+            let measurement;
+            try {
+                measurement = target.measure();
+            }
+            catch (error) {
+                log(`⚠️  retention: could not measure ${key} — ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const previous = lastRun?.resources.find((r) => r.key === key)?.report;
+            const lastSweep = lastReports?.get(key) ?? previous;
+            resources.push({
+                declaration: target.declaration,
+                ...(measurement ? { measurement } : {}),
+                ...(lastSweep ? { lastSweep } : {}),
+            });
+        }
+        publishRetention({
+            app,
+            ...(options.instance ? { instance: options.instance } : {}),
+            ...(disabled ? { sweepDisabled: true } : {}),
+            resources,
+        }, { home, log });
+    }
+    function sweepNow(at = now()) {
+        lastBeatAt = at;
+        const outcomes = [];
+        const totals = { aged: 0, overflow: 0, bytesFreed: 0, errors: 0 };
+        const reports = new Map();
+        let policies;
+        try {
+            policies = policiesNow();
+        }
+        catch (error) {
+            // A malformed declaration must not wedge the timer — report and skip.
+            lastError = error instanceof Error ? error.message : String(error);
+            log(`⚠️  retention: cannot resolve policies — ${lastError}`);
+            const report = { at, resources: [], totals: { ...totals, errors: 1 } };
+            lastRun = report;
+            return report;
+        }
+        for (const target of targets) {
+            const key = `${target.declaration.app}:${target.declaration.id}`;
+            const policy = policies.get(key);
+            if (!policy)
+                continue;
+            let report;
+            if (disabled) {
+                report = { at, aged: 0, overflow: 0 };
+            }
+            else {
+                try {
+                    report = target.sweep(policy, at);
+                }
+                catch (error) {
+                    // A busy/locked database is a transient the next sweep clears; one
+                    // broken resource must never stop the others.
+                    const message = error instanceof Error ? error.message : String(error);
+                    report = { at, aged: 0, overflow: 0, error: message };
+                    totals.errors++;
+                    log(`⚠️  retention: ${key} sweep failed — ${message}`);
+                }
+            }
+            totals.aged += report.aged;
+            totals.overflow += report.overflow;
+            totals.bytesFreed += report.bytesFreed ?? 0;
+            reports.set(key, report);
+            outcomes.push({ key, policy, report });
+            // An archiving resource that refuses to trim looks EXACTLY like one with
+            // nothing to do — same zeros, same silence — so the refusal has to be the
+            // noisy case. It means the archive's collector has stopped, which is a
+            // disk problem on its way to becoming a data problem.
+            if (report.blocked) {
+                log(`⚠️  retention: ${key} did NOT trim — ${report.blocked}`);
+            }
+            if (report.overflow > 0) {
+                log(`⚠️  retention: ${key} OVERFLOW — ${report.overflow} oldest item(s) dropped to hold it at ` +
+                    `${policy.maxItems}. These went regardless of the age rule: something is writing far ` +
+                    "faster than expected. A bound that declines to bind is not a bound.");
+            }
+        }
+        const report = { at, resources: outcomes, totals };
+        lastRun = report;
+        if (totals.errors === 0)
+            lastError = null;
+        // Silence is the healthy steady state — log only a sweep that changed something.
+        if (totals.aged > 0 || totals.overflow > 0) {
+            // "pruned" and "archived" are not the same event and must not read as one:
+            // the first is data the owner agreed to lose, the second is data that moved.
+            const archived = outcomes.reduce((sum, o) => sum + (o.report.archived ?? 0), 0);
+            log(`retention: pruned ${totals.aged + totals.overflow - archived} item(s)` +
+                (archived > 0 ? `, archived ${archived}` : "") +
+                (totals.bytesFreed > 0 ? `, ${formatBytes(totals.bytesFreed)} reclaimed` : "") +
+                ` across ${outcomes.filter((o) => o.report.aged + o.report.overflow > 0).length} resource(s)`);
+        }
+        publish(reports);
+        return report;
+    }
+    function schedule(delayMs = intervalMs) {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        nextRunAt = now() + delayMs;
+        timer = setTimeout(() => {
+            timer = null;
+            sweepNow();
+            schedule();
+        }, delayMs);
+        // Unref'd for the same reason the pulse is, and it was the one that mattered:
+        // a 6-hour `setTimeout` is a 6-hour reason for a process not to exit. Every
+        // caller that owns a drain calls `stop()`, but `apps/vault` deliberately has
+        // no signal handler (launchd restarts it), and without this a SIGTERM there
+        // would hang until the timer fired or the supervisor lost patience and
+        // SIGKILLed — which is exactly how a WAL gets left half-closed. Housekeeping
+        // must never be the last thing holding a process open.
+        timer.unref?.();
+    }
+    /** Notice an overrides edit made by the station and act on it promptly. */
+    function checkOverrides() {
+        if (stopped)
+            return;
+        try {
+            const mtime = statSync(overridesFile).mtimeMs;
+            if (mtime > appliedOverridesAt) {
+                appliedOverridesAt = mtime;
+                log("retention: policy changed — sweeping now");
+                sweepNow();
+                schedule();
+            }
+        }
+        catch {
+            // No overrides file yet is the normal case on a fresh machine.
+        }
+    }
+    return {
+        start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            lastBeatAt = now();
+            // Publish immediately so the UI has the fleet's sizes without waiting for
+            // the first sweep — a dashboard that is blank for a minute after boot
+            // reads as broken.
+            try {
+                publish();
+            }
+            catch (error) {
+                log(`⚠️  retention: initial publish failed — ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                appliedOverridesAt = statSync(overridesFile).mtimeMs;
+            }
+            catch {
+                appliedOverridesAt = 0;
+            }
+            schedule(Math.min(bootDelayMs, intervalMs));
+            pulse = setInterval(checkOverrides, options.pulseMs ?? OVERRIDES_PULSE_MS);
+            // Never hold the process open for housekeeping.
+            pulse.unref?.();
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            if (pulse)
+                clearInterval(pulse);
+            timer = null;
+            pulse = null;
+            nextRunAt = null;
+        },
+        ensureAlive() {
+            if (stopped)
+                return;
+            // ~3 missed intervals, floored so a fast test cadence is not declared
+            // wedged the moment it is a beat late — the watchdog's shape.
+            const staleAfterMs = Math.max(intervalMs * 3, 90_000);
+            if (now() - lastBeatAt <= staleAfterMs)
+                return;
+            log("⚠️  retention: LIVENESS KICK — sweep timer silent (system sleep/hibernate?) — sweeping now");
+            sweepNow();
+            schedule();
+        },
+        sweepNow,
+        publish: () => publish(),
+        preview(at = now()) {
+            const policies = policiesNow();
+            const rows = [];
+            for (const target of targets) {
+                const key = `${target.declaration.app}:${target.declaration.id}`;
+                const policy = policies.get(key);
+                if (!policy)
+                    continue;
+                try {
+                    const { aged, overflow } = target.preview(policy, at);
+                    rows.push({ key, policy, aged, overflow });
+                }
+                catch {
+                    rows.push({ key, policy, aged: 0, overflow: 0 });
+                }
+            }
+            return rows;
+        },
+        status: () => ({ app, home, disabled, lastRun, nextRunAt, lastError }),
+    };
+}