cursedbelt 2.6.1 → 2.8.0

package/src/react/file-tree/FileTree.tsx

@@ -68,6 +68,8 @@ import type {
 } from 'react';
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
+  type AccessMarkCopy,
+  accessMarkCopy,
   describeDrop,
   descendantIdsOf,
   type DropOffer,
@@ -225,6 +227,19 @@ export interface FileTreeProps {
   /** Whether an in-flight external drag is one this tree wants. Default: any drag. */
   acceptsExternalDrag?: (event: ReactDragEvent) => boolean;
 
+  /**
+   * What the 🔒 access mark SAYS, per access state — hover text on the mark a row
+   * with `access: 'private' | 'locked'` draws.
+   *
+   * 🔴 The defaults speak collections' vocabulary ("hidden from a locked page"),
+   * because that is the app the mark was built for — but the mark itself is generic
+   * and the words are not. The vault's protected folders wear the same padlock
+   * meaning "everything in here needs the master password", and a tooltip claiming
+   * they are hidden would be false: the rows are visible, their SECRETS are sealed.
+   * An app whose privacy model has its own name passes its own words.
+   */
+  accessCopy?: AccessMarkCopy;
+
   /** Narrow the tree to matching rows, keeping the folders on the way to each. */
   filter?: string;
   /** What to show when there are no rows — differs between "nothing here" and "no match". */
@@ -331,6 +346,7 @@ export function FileTree({
   renderAccessory,
   onDropExternal,
   acceptsExternalDrag,
+  accessCopy,
   filter,
   empty = 'Nothing here yet.',
   ariaLabel = 'Files',
@@ -1255,18 +1271,10 @@ export function FileTree({
                   is the twisty's, and a folder losing its arrow would lose the control that
                   opens it) and never moves with how many actions a consumer wired up.
                 */}
+                {/* The mark's words are the consumer's when it has its own privacy
+                    vocabulary — see accessMarkCopy for why the defaults are collections'. */}
                 {node.access === 'private' || node.access === 'locked' ? (
-                  <Tooltip
-                    content={
-                      node.access === 'locked'
-                        ? 'Hidden — unlock to see what is in here'
-                        : // Deliberately "this or what is in it": a consumer sets `private` both
-                          // for a row that is itself private and for a public folder holding
-                          // private children (collections does exactly that), and a wording that
-                          // claimed only the first would be false on half the rows it marks.
-                          'Private — this, or something in it, is hidden from a locked page'
-                    }
-                  >
+                  <Tooltip content={accessMarkCopy(node.access, accessCopy)}>
                     {/* Not `aria-hidden`: this is the one thing on the row a screen reader
                         cannot work out from anything else, and the name alone would announce a
                         private folder identically to a public one. */}

package/src/react/file-tree/index.ts

@@ -13,6 +13,8 @@
 //
 // Its own subpath so an app with a flat list never pulls the gesture in.
 export {
+  type AccessMarkCopy,
+  accessMarkCopy,
   descendantIdsOf,
   type DropOffer,
   type FileTreeAccess,

package/src/server/sync/alarm.spec.ts

@@ -0,0 +1,149 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSyncAlarm } from "./alarm";
+
+/**
+ * 🔴 `tmpdir()`, not vault's `scratchDir()` — the seam moved when this engine did.
+ *
+ * In `apps/vault` this suite imported `scripts/testScratch`, an opt-in helper that
+ * hands out a directory under `$FORGE_STATE` and sweeps it. cursedbelt solves the
+ * same problem one level lower: `forceTestEnv.ts` is a bunfig PRELOAD that
+ * redirects `$TMPDIR` itself for every test process in the repo (rationale and the
+ * 4,950× measurement behind it are in `scripts/testTmpRoot.ts`). So a plain
+ * `mkdtempSync(join(tmpdir(), …))` here already lands in the small, swept root —
+ * and reaching back for the app's helper would be a cross-repo import that only
+ * resolves while the copy in vault still exists.
+ */
+const dirs: string[] = [];
+const scratchDir = (prefix: string): string => {
+	const dir = mkdtempSync(join(tmpdir(), `cb-${prefix}-`));
+	dirs.push(dir);
+	return dir;
+};
+afterAll(() => {
+	for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function makeAlarm(overrides: { threshold?: number; reRaiseMs?: number } = {}) {
+	const dir = scratchDir("sync-alarm");
+	const raised: string[] = [];
+	let clock = 1_000_000;
+	const alarm = createSyncAlarm({
+		statePath: join(dir, "alarm.json"),
+		threshold: overrides.threshold ?? 3,
+		reRaiseMs: overrides.reRaiseMs ?? 60_000,
+		notify: (_title, body) => raised.push(body),
+		now: () => clock,
+		appName: "station",
+	});
+	return { alarm, raised, tick: (ms: number) => (clock += ms) };
+}
+
+describe("sync alarm", () => {
+	test("raises after the threshold of paused rounds, not before", () => {
+		const { alarm, raised } = makeAlarm();
+		alarm.record("paused", "doc.set");
+		alarm.record("paused", "doc.set");
+		expect(raised).toHaveLength(0);
+		alarm.record("paused", "doc.set");
+		expect(raised).toHaveLength(1);
+		expect(raised[0]).toContain("doc.set");
+	});
+
+	test("re-raises only after the re-raise window", () => {
+		const { alarm, raised, tick } = makeAlarm();
+		for (let i = 0; i < 5; i++) alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		tick(59_000);
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		tick(2_000);
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(2);
+	});
+
+	test("ok resets the counter; unreachable neither counts nor resets", () => {
+		const { alarm, raised } = makeAlarm();
+		alarm.record("paused", "k");
+		alarm.record("paused", "k");
+		// The nightly window: unreachable rounds must not walk the counter to the
+		// threshold, and must not clear a genuine pause streak either.
+		alarm.record("unreachable");
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		alarm.record("ok");
+		alarm.record("paused", "k");
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1); // streak restarted from zero
+	});
+
+	test("auth refusals raise with the re-link message", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 1 });
+		alarm.record("auth");
+		expect(raised[0]).toContain("Re-link");
+	});
+
+	test("state survives a process restart (same state file)", () => {
+		const dir = scratchDir("sync-alarm");
+		const statePath = join(dir, "alarm.json");
+		const raised: string[] = [];
+		const make = () =>
+			createSyncAlarm({
+				statePath,
+				threshold: 3,
+				notify: (_t, b) => raised.push(b),
+				now: () => 5_000,
+			});
+		make().record("paused", "k");
+		make().record("paused", "k");
+		make().record("paused", "k");
+		expect(raised).toHaveLength(1);
+	});
+});
+
+/**
+ * 🔴 The outcome that was missing, and the eight days it cost.
+ *
+ * The console's subdomain cutover left the Mac's sync dialer aimed at a host
+ * that had become a 301. It followed the redirect into a Cloudflare Access login
+ * page and threw a JSON parse error every round — neither `paused` (nothing was
+ * version-skewed), nor `auth` (no token was refused), nor `unreachable` (the
+ * peer answered). So the alarm recorded NOTHING while every mirrored report on
+ * prod froze, each still rendering a confident age.
+ */
+describe("a sustained hard ERROR raises, exactly like a sustained pause", () => {
+	test("consecutive errors cross the threshold and the alarm names the real error", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		expect(raised).toHaveLength(0);
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		expect(raised).toHaveLength(1);
+		// The message carries the cause, because "failed (ignored)" being
+		// uninformative is the whole reason this outcome exists.
+		expect(raised[0]).toContain("text/html");
+	});
+
+	test("one good round clears the counter", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "boom");
+		alarm.record("error", "boom");
+		alarm.record("ok");
+		alarm.record("error", "boom");
+		alarm.record("error", "boom");
+		expect(raised).toHaveLength(0);
+	});
+
+	test("an UNREACHABLE peer between errors neither counts nor resets", () => {
+		// The nightly EC2 sleep sits in the middle of a real outage all the time.
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "boom");
+		alarm.record("unreachable");
+		alarm.record("error", "boom");
+		alarm.record("unreachable");
+		alarm.record("error", "boom");
+		expect(raised).toHaveLength(1);
+	});
+});

package/src/server/sync/alarm.ts

@@ -0,0 +1,137 @@
+/**
+ * Pause-alarm escalation — notes' `syncAlarm` generalized. A sync that is version-
+ * skew paused or auth-refused for a sustained stretch is a real problem the owner
+ * must hear about (the 2026-07-31 notes incident: prod ran stale code most of a day
+ * and only an owner eyeballing counts caught it). An UNREACHABLE peer neither counts
+ * nor resets — the nightly EC2 sleep must never false-alarm.
+ *
+ * State is a small JSON file so the alarm survives process restarts; the notifier is
+ * a seam (macOS `osascript` by default) so tests and non-Mac hosts inject their own.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * 🔴 `error` joined on 2026-08-21, and it is the outcome that was MISSING.
+ *
+ * The console's subdomain cutover left the Mac's `STATION_SYNC_URL` pointing at
+ * a host that had become a 301; the dialer followed it into a Cloudflare Access
+ * login page and threw `Failed to parse JSON` every round. That is neither
+ * `paused` (nothing is version-skewed) nor `auth` (no token was refused) nor
+ * `unreachable` (the peer answered), so it recorded NOTHING — the timer logged
+ * `[sync] failed (ignored)` and the alarm's counter sat at zero while every
+ * mirrored report on prod froze for days, each still rendering a confident age.
+ *
+ * A sustained hard error is exactly as bad as a sustained pause and is now
+ * counted the same. `unreachable` remains the one outcome that neither counts
+ * nor resets, because the nightly EC2 sleep must never false-alarm.
+ */
+export type AlarmOutcome = "ok" | "paused" | "auth" | "error" | "unreachable";
+
+interface AlarmState {
+	consecutiveBad: number;
+	firstBadAt: number | null;
+	lastRaisedAt: number | null;
+	lastReason: string | null;
+}
+
+const EMPTY: AlarmState = {
+	consecutiveBad: 0,
+	firstBadAt: null,
+	lastRaisedAt: null,
+	lastReason: null,
+};
+
+export interface SyncAlarmOptions {
+	/** Where the counter lives (survives restarts). */
+	statePath: string;
+	/** Rounds of paused/auth before raising (with the round cadence, pick so the
+	 *  threshold lands around ~45 min of sustained pause). */
+	threshold?: number;
+	/** Re-raise cadence while the condition persists. Default 4h. */
+	reRaiseMs?: number;
+	/** Present the alarm. Default: macOS notification via osascript. */
+	notify?: (title: string, body: string) => void;
+	now?: () => number;
+	appName?: string;
+}
+
+export interface SyncAlarm {
+	/** Record one sync round's outcome; raises when the threshold crosses. */
+	record(outcome: AlarmOutcome, reason?: string): void;
+}
+
+function defaultNotify(title: string, body: string): void {
+	try {
+		const esc = (s: string) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+		Bun.spawnSync([
+			"osascript",
+			"-e",
+			`display notification "${esc(body)}" with title "${esc(title)}"`,
+		]);
+	} catch {
+		// A notifier must never take the loop down.
+	}
+}
+
+export function createSyncAlarm(options: SyncAlarmOptions): SyncAlarm {
+	const threshold = options.threshold ?? 9;
+	const reRaiseMs = options.reRaiseMs ?? 4 * 60 * 60_000;
+	const notify = options.notify ?? defaultNotify;
+	const now = options.now ?? Date.now;
+	const appName = options.appName ?? "sync";
+
+	const load = (): AlarmState => {
+		try {
+			if (!existsSync(options.statePath)) return { ...EMPTY };
+			return {
+				...EMPTY,
+				...(JSON.parse(readFileSync(options.statePath, "utf8")) as Partial<AlarmState>),
+			};
+		} catch {
+			return { ...EMPTY };
+		}
+	};
+	const save = (state: AlarmState): void => {
+		try {
+			mkdirSync(dirname(options.statePath), { recursive: true });
+			writeFileSync(options.statePath, JSON.stringify(state));
+		} catch {
+			// Losing the counter degrades to a later alarm, never to a crash.
+		}
+	};
+
+	return {
+		record(outcome, reason) {
+			const state = load();
+			if (outcome === "ok") {
+				save({ ...EMPTY });
+				return;
+			}
+			if (outcome === "unreachable") return; // neither counts nor resets
+			state.consecutiveBad += 1;
+			state.lastReason = reason ?? outcome;
+			if (state.firstBadAt === null) state.firstBadAt = now();
+			const due =
+				state.consecutiveBad >= threshold &&
+				(state.lastRaisedAt === null || now() - state.lastRaisedAt >= reRaiseMs);
+			if (due) {
+				state.lastRaisedAt = now();
+				const since = state.firstBadAt
+					? new Date(state.firstBadAt).toLocaleTimeString()
+					: "a while";
+				notify(
+					outcome === "error" ? `${appName}: sync is FAILING` : `${appName}: sync is paused`,
+					outcome === "auth"
+						? `The sync token is being refused (since ${since}). Re-link the peer.`
+						: outcome === "error"
+							? // Names the real error, because this alarm's whole reason for
+								// existing is that "failed (ignored)" was invisible.
+								`Every sync round has failed since ${since}: ${state.lastReason}`
+							: `Push has been paused on "${state.lastReason}" since ${since} — the peer likely needs a deploy.`,
+				);
+			}
+			save(state);
+		},
+	};
+}

package/src/server/sync/commands.spec.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { Hono } from "hono";
+import {
+	createCommandQueue,
+	createCommandReceiver,
+	createCommandRemote,
+	startCommandWorker,
+	type SyncCommand,
+} from "./commands";
+
+const queue = () => createCommandQueue(new Database(":memory:"));
+
+describe("command queue", () => {
+	test("enqueue → claim → complete lifecycle", () => {
+		const q = queue();
+		const cmd = q.enqueue("app.start", { key: "notes" }, "prod-ui");
+		expect(cmd.status).toBe("queued");
+		expect(q.pendingCount()).toBe(1);
+		const claimed = q.claimNext("mac");
+		expect(claimed?.uid).toBe(cmd.uid);
+		expect(claimed?.status).toBe("claimed");
+		// Nothing else to claim while it is held.
+		expect(q.claimNext("other")).toBeNull();
+		expect(q.complete(cmd.uid, { started: true })).toBe(true);
+		expect(q.get(cmd.uid)?.status).toBe("done");
+		expect(q.pendingCount()).toBe(0);
+		// Completing twice is refused — the row already finished.
+		expect(q.complete(cmd.uid, {})).toBe(false);
+	});
+
+	test("claims are ordered oldest-first and atomic across workers", () => {
+		const q = queue();
+		const first = q.enqueue("a", null, "ui");
+		const second = q.enqueue("b", null, "ui");
+		expect(q.claimNext("w1")?.uid).toBe(first.uid);
+		expect(q.claimNext("w2")?.uid).toBe(second.uid);
+		expect(q.claimNext("w3")).toBeNull();
+	});
+
+	test("a stale claim is reclaimable (a dead worker cannot strand the queue)", async () => {
+		const q = queue();
+		q.enqueue("a", null, "ui");
+		expect(q.claimNext("w1", 60_000)).not.toBeNull();
+		// Let the claim age past a 1ms stale window, then reclaim it.
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		expect(q.claimNext("w2", 1)?.claimedBy).toBe("w2");
+	});
+
+	test("fail records the error", () => {
+		const q = queue();
+		const cmd = q.enqueue("a", null, "ui");
+		q.claimNext("w");
+		expect(q.fail(cmd.uid, "boom")).toBe(true);
+		const row = q.get(cmd.uid);
+		expect(row?.status).toBe("failed");
+		expect(row?.error).toBe("boom");
+	});
+});
+
+describe("command receiver + remote + worker", () => {
+	function mount(q: ReturnType<typeof createCommandQueue>) {
+		const app = new Hono();
+		app.route(
+			"/api/relay",
+			createCommandReceiver({
+				queue: q,
+				verifyToken: (t) => t === "tok",
+				maxHoldMs: 300,
+				pollStepMs: 20,
+			}),
+		);
+		const remote = createCommandRemote({
+			basePath: "http://peer/api/relay",
+			token: "tok",
+			fetchImpl: ((input: RequestInfo | URL, init?: RequestInit) =>
+				app.request(input as string, init)) as typeof fetch,
+		});
+		return { app, remote };
+	}
+
+	test("held poll returns a queued command immediately, null after the hold", async () => {
+		const q = queue();
+		const { remote } = mount(q);
+		const empty = await remote.poll("mac", 50);
+		expect(empty).toBeNull();
+		q.enqueue("repo.sync", null, "ui");
+		const got = await remote.poll("mac", 50);
+		expect(got?.kind).toBe("repo.sync");
+		await remote.report(got?.uid ?? "", { ok: true, result: { healed: 3 } });
+		expect(q.get(got?.uid ?? "")?.status).toBe("done");
+	});
+
+	test("a command enqueued DURING the hold is delivered within it", async () => {
+		const q = queue();
+		const { remote } = mount(q);
+		const pending = remote.poll("mac", 250);
+		setTimeout(() => q.enqueue("late", null, "ui"), 40);
+		const got = await pending;
+		expect(got?.kind).toBe("late");
+	});
+
+	test("the gate refuses a wrong token uniformly", async () => {
+		const q = queue();
+		const app = new Hono();
+		app.route("/api/relay", createCommandReceiver({ queue: q, verifyToken: (t) => t === "tok" }));
+		const res = await app.request("http://peer/api/relay/pending?wait=0", {
+			headers: { authorization: "Bearer wrong" },
+		});
+		expect(res.status).toBe(401);
+	});
+
+	test("the worker loop polls, executes, reports, and keeps cycling", async () => {
+		const q = queue();
+		const { remote } = mount(q);
+		const executed: string[] = [];
+		const worker = startCommandWorker({
+			resolveRemote: () => remote,
+			execute: async (command: SyncCommand) => {
+				executed.push(command.kind);
+				if (command.kind === "explode") throw new Error("kaboom");
+				return { ok: true };
+			},
+			holdMs: 60,
+			idleGapMs: 5,
+			log: () => {},
+			warn: () => {},
+		});
+		q.enqueue("good", null, "ui");
+		q.enqueue("explode", null, "ui");
+		const deadline = Date.now() + 3_000;
+		while (Date.now() < deadline) {
+			const rows = q.list();
+			if (rows.length === 2 && rows.every((r) => r.status === "done" || r.status === "failed"))
+				break;
+			await new Promise((resolve) => setTimeout(resolve, 20));
+		}
+		worker.stop();
+		expect(executed.sort()).toEqual(["explode", "good"]);
+		const byKind = new Map(q.list().map((r) => [r.kind, r]));
+		expect(byKind.get("good")?.status).toBe("done");
+		expect(byKind.get("explode")?.status).toBe("failed");
+		expect(byKind.get("explode")?.error).toContain("kaboom");
+	});
+});