cursedbelt-server 1.0.0

package/src/lockfileIsTracked.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * 🔴 Rule 2 of this generation: `bun install --frozen-lockfile` must pass on a
+ * CLEAN CHECKOUT — not merely in the tree an agent happens to be sitting in.
+ *
+ * ── What this cost, 2026-09-13 ──────────────────────────────────────────────
+ * `.gitignore` carried a `bun.lock` stanza with a comment explaining it was
+ * temporary: the only lockfile that could exist at the time recorded a
+ * proof-only local pack of `cwip`, and committing that would have reintroduced
+ * the `file:` dependency the package had just removed. The reasoning was sound
+ * and the expiry condition — "until cwip is on the registry" — was real. It was
+ * also written in a comment, which nothing can evaluate. `cwip@3.0.2` went to
+ * the registry and the stanza stayed, so rule 2 was true of every working tree
+ * and false of every fresh clone: exactly the case the rule exists for, and the
+ * one nobody hits until they are the person doing the clone.
+ *
+ * A temporary ignore needs a check that notices when it stopped being true.
+ * This is that check. `git check-ignore` is the whole mechanism, because the
+ * failure is not "the lockfile is missing" — it is "git has been told to throw
+ * it away", which is invisible in a tree that already has one.
+ *
+ * Deliberately NOT `git ls-files bun.lock`: a regenerated lockfile is untracked
+ * until it is staged, and a check that reds on work-in-progress teaches people
+ * to skip it. Ignored-vs-not is the property that actually regresses.
+ */
+import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url))
+
+describe('bun.lock is part of the checkout', () => {
+  test('the lockfile exists', () => {
+    expect(
+      existsSync(new URL('../bun.lock', import.meta.url)),
+      'no bun.lock — regenerate it with `bun install`, or `bun install --frozen-lockfile` cannot pass for anyone cloning this',
+    ).toBe(true)
+  })
+
+  test('git is not told to ignore it', () => {
+    const git = spawnSync('git', ['check-ignore', '-q', 'bun.lock'], { cwd: repoRoot })
+    if (git.error) return // no git on this host: nothing to assert about ignore rules
+
+    // exit 0 = the path IS ignored; 1 = it is not; anything else = git could not tell us.
+    expect(
+      git.status,
+      'bun.lock is gitignored, so a fresh clone has no lockfile and `bun install --frozen-lockfile` cannot pass there. Delete the stanza from .gitignore rather than the assertion.',
+    ).not.toBe(0)
+  })
+})

package/src/namedSubpathsResolve.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Every `cursedbelt/<subpath>` this repo NAMES must be one it actually exports
+ * (2026-09-13).
+ *
+ * Removing the 23 subpaths nothing referenced left 19 sentences in `src` and
+ * `docs` still advertising them — `cursedbelt/ctgr`, `cursedbelt/server/media`,
+ * `cursedbelt/tokens` and friends, each one a copy-pasteable import that now
+ * throws ERR_PACKAGE_PATH_NOT_EXPORTED. Nothing could see them, because a
+ * subpath named in prose is invisible to `tsc` (it is a comment), invisible to
+ * Biome (it is a string), and invisible to `check-paths.ts` (it is not a
+ * filesystem path). The only reason those 19 were found is that one agent
+ * grepped for them by hand while deleting the exports.
+ *
+ * That is the drift this file exists to make impossible: the manifest and the
+ * prose describing it can no longer disagree without something going red.
+ *
+ * 🔴 Bun.Glob + Bun.file, NOT node:fs — this package's test preload virtualizes
+ * node:fs, so a readdirSync/readFileSync scan reads MOCK data and passes against
+ * files it never opened. Same trap as publishShape.spec.ts; see its header.
+ *
+ * Escape hatch: a line that must name a removed subpath (a changelog entry, a
+ * migration note) carries `subpath-check:ignore` and is skipped.
+ */
+const ROOTS = ['src', 'scripts', 'docs'] as const;
+
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|mp4|webm|mp3|wav|pdf|zip|gz|woff2?|ttf|otf|eot|wasm)$/i;
+
+const IGNORE = 'subpath-check:ignore';
+
+/**
+ * `cursedbelt/<subpath>` wherever it appears — code, comment or markdown. The
+ * trailing class stops `cursedbelt/react` from matching inside
+ * `cursedbelt/react/timeline`, so a removed deep subpath cannot hide behind a
+ * live shallow one.
+ *
+ * The leading `(?<![\w/.-])` is what separates an IMPORT SPECIFIER from a REPO
+ * PATH: `packages/cursedbelt/src/...` and `../cursedbelt/scripts/...` name files
+ * on disk (check-paths.ts' job), not subpaths, and flagging them would make this
+ * gate unpassable and therefore useless.
+ */
+// Parameterized on pkg.name since the 2026-09-15 split: in THIS repo a bare
+// `cursedbelt/...` mention names the react package's surface, not ours, and
+// only `cursedbelt-core/...` mentions are checkable against our own manifest.
+const NAMED = new RegExp(String.raw`(?<![\w/.-])${pkg.name}(\/[a-z0-9][a-z0-9._/-]*[a-z0-9])`, 'gi');
+
+/** First segment is a directory in THIS repo ⇒ the mention is a file path. */
+const REPO_DIRS = /^\/(src|scripts|dist|docs|e2e|demo|node_modules|releases)(\/|$)/;
+
+/**
+ * Ends in a file extension ⇒ a file path, not a subpath — except the three CSS
+ * entries, which genuinely ARE exports (`cursedbelt/styles.css`).
+ */
+const FILE_EXT = /\.(?!css$)[a-z0-9]+$/i;
+
+const exported = new Set(Object.keys(pkg.exports).map((k) => k.replace(/^\./, '')));
+
+// This file and the task/report prose quoting the removal are allowed to name them.
+const SELF = 'namedSubpathsResolve.spec.ts';
+
+type Offence = { file: string; line: number; subpath: string; text: string };
+
+let cache: Promise<Offence[]> | undefined;
+const offences = (): Promise<Offence[]> => {
+	cache ??= (async () => {
+		const repo = `${import.meta.dir}/..`;
+		const found: Offence[] = [];
+		for (const root of ROOTS) {
+			const dir = `${repo}/${root}`;
+			for (const rel of new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true })) {
+				if (BINARY.test(rel) || rel.endsWith(SELF)) continue;
+				const text = await Bun.file(`${dir}/${rel}`).text();
+				const lines = text.split('\n');
+				for (let i = 0; i < lines.length; i++) {
+					const line = lines[i] ?? '';
+					if (line.includes(IGNORE)) continue;
+					for (const m of line.matchAll(NAMED)) {
+						const subpath = m[1] ?? '';
+						if (exported.has(subpath)) continue;
+						if (REPO_DIRS.test(subpath) || FILE_EXT.test(subpath)) continue;
+						found.push({ file: `${root}/${rel}`, line: i + 1, subpath, text: line.trim() });
+					}
+				}
+			}
+		}
+		return found;
+	})();
+	return cache;
+};
+
+describe('subpaths named in this repo resolve', () => {
+	it('has scanned a real source tree', async () => {
+		// Guards the whole file: if the glob or the fs mock ever returns nothing,
+		// the assertion below passes vacuously and the gate quietly dies.
+		const repo = `${import.meta.dir}/..`;
+		let seen = 0;
+		for (const root of ROOTS) {
+			for (const _ of new Bun.Glob('**/*').scanSync({ cwd: `${repo}/${root}`, onlyFiles: true })) seen++;
+		}
+		expect(seen).toBeGreaterThan(100);
+	});
+
+	it('knows what the manifest exports', () => {
+		// If `exports` is ever read wrong, every offence below silently becomes one.
+		expect(exported.has('')).toBe(true); // the "." root entry
+		expect(exported.has('/master-lock')).toBe(true);
+		expect(exported.has('/react')).toBe(false); // the react tier stayed in `cursedbelt` at the 2026-09-15 split
+	});
+
+	it('names no subpath package.json does not export', async () => {
+		const dead = await offences();
+		expect(
+			dead,
+			`these name a cursedbelt subpath that is not in package.json exports — a consumer who\n` +
+				`copies one gets ERR_PACKAGE_PATH_NOT_EXPORTED. Point at the surviving subpath, or at\n` +
+				`the repo path, or mark the line \`${IGNORE}\`:\n` +
+				dead.map((d) => `  ${d.file}:${d.line}  cursedbelt${d.subpath}\n      ${d.text}`).join('\n'),
+		).toEqual([]);
+	});
+});

package/src/noPathDeps.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Rule 1 of `~/code` (2026-09-12): share by published version, never by path.
+ *
+ * `file:`, `link:`, `workspace:*` and a directory-valued `overrides` entry each
+ * defeat `bun install --frozen-lockfile`, and a `file:` install is served from a
+ * cache keyed on the VERSION STRING — so re-packing the same version silently
+ * ships stale bytes straight through `bun install --force`. That is the defect
+ * that made a `cursed-satellites` change cost twenty minutes; this is the line
+ * that stops it coming back one convenient shortcut at a time.
+ */
+const PATHY = /^(file:|link:|workspace:|portal:)/;
+
+describe('no path dependencies', () => {
+	for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'overrides'] as const) {
+		it(`${field} names no path-valued spec`, () => {
+			const block = (pkg as Record<string, unknown>)[field] as Record<string, string> | undefined;
+			const bad = Object.entries(block ?? {}).filter(([, v]) => typeof v === 'string' && PATHY.test(v));
+			expect(bad, `share by published version, never by path:\n  ${bad.map(([k, v]) => `${k} = ${v}`).join('\n  ')}`).toEqual([]);
+		});
+	}
+});

package/src/publishShape.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * What this exists for (2026-09-12).
+ *
+ * Two ways this package can publish something that installs clean and does not
+ * work, both found the hard way while extracting it from the monorepo:
+ *
+ * 1. `exports` resolves the `bun` and `source` conditions to `./src/*.ts`, but
+ *    `files` shipped only `dist`. Every consumer runs bun, so every subpath
+ *    resolved to a path that was not in the tarball. Invisible under a `file:`
+ *    link, because the whole directory was there.
+ *
+ * 2. A `tsc` run with no tsconfig falls back to defaults and emits `.js`/`.d.ts`
+ *    NEXT TO the sources. Those get packed, and a consumer's bun condition then
+ *    loads the stale `.js` instead of the `.ts` — a second module instance, so
+ *    every module-level singleton silently doubles.
+ *
+ * Both are one assertion each, and both fail loudly at `bun test` rather than at
+ * a consumer's runtime three repos away.
+ */
+// 🔴 Bun.Glob, NOT node:fs: this package's own test preload virtualizes node:fs
+// (`[cwip/testing] System mocks enabled`), so readdirSync here returns MOCK data
+// and the assertion below passes against a directory it never read. Cost an hour
+// to find; the scan must not go through a mocked module.
+const emittedInSrc = (): string[] => {
+	const all = new Set([...new Bun.Glob('**/*').scanSync({ cwd: import.meta.dir })]);
+	// A hand-written ambient declaration (css.d.ts) has no .ts sibling and is
+	// legitimate; an EMITTED one always sits next to the source it came from.
+	return [...all].filter((f) => {
+		if (f.endsWith('.js') || f.endsWith('.js.map')) return true;
+		if (!f.endsWith('.d.ts')) return false;
+		return all.has(`${f.slice(0, -5)}.ts`) || all.has(`${f.slice(0, -5)}.tsx`);
+	});
+};
+
+describe('publish shape', () => {
+	it('ships every directory its exports resolve into', () => {
+		const files = (pkg as { files?: string[] }).files ?? [];
+		const roots = new Set<string>();
+		for (const entry of Object.values((pkg as { exports: Record<string, unknown> }).exports)) {
+			if (typeof entry !== 'object' || entry === null) continue;
+			for (const target of Object.values(entry as Record<string, string>)) {
+				if (typeof target === 'string' && target.startsWith('./')) {
+					const top = target.slice(2).split('/')[0];
+					if (top !== undefined) roots.add(top);
+				}
+			}
+		}
+		for (const root of roots) {
+			expect(
+				files.some((f) => f === root || f.startsWith(`${root}/`)),
+				`exports resolve into "${root}/" but package.json files does not ship it`,
+			).toBe(true);
+		}
+	});
+
+	it('has no compiled output sitting in src', () => {
+		const emitted = emittedInSrc();
+		expect(emitted, `tsc emitted into src instead of dist:\n  ${emitted.slice(0, 10).join('\n  ')}`).toEqual([]);
+	});
+
+	it('declares bin paths npm will actually keep', () => {
+		// npm rejects a "./"-prefixed bin value, calls the NAME invalid, and drops
+		// the entry — with a warning, not an error. The package publishes fine and
+		// installs with no CLI at all. Invisible under a file: link, where the bin
+		// is linked from the source manifest before npm ever normalises it.
+		const bin = (pkg as { bin?: Record<string, string> }).bin ?? {};
+		const prefixed = Object.entries(bin).filter(([, v]) => v.startsWith('./'));
+		expect(
+			prefixed,
+			`npm drops "./"-prefixed bin entries on publish:\n  ${prefixed.map(([k, v]) => `${k} = ${v}`).join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('lists "types" first in every conditional export', () => {
+		// Condition order is significant and "types" must win, or tsc resolves the
+		// `bun`/`source` condition and typechecks our shipped .ts instead of the
+		// .d.ts. A consumer then inherits type errors from OUR optional peers —
+		// cursedbelt could not typecheck against cwip because `unpdf`, an optional
+		// peer it does not install, was reachable through cwip/src.
+		const wrong = Object.entries((pkg as { exports: Record<string, unknown> }).exports)
+			.filter(([, e]) => typeof e === 'object' && e !== null && 'types' in e)
+			.filter(([, e]) => Object.keys(e as object)[0] !== 'types')
+			.map(([k]) => k);
+		expect(wrong, `"types" must be the first condition:\n  ${wrong.join('\n  ')}`).toEqual([]);
+	});
+});

package/src/server/activity/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `cursedbelt-server/activity` — the fleet's ONE append-only activity/audit
+ * stream: who did what, to which record, when, and how it went.
+ *
+ * The vocabulary is `cursedbelt-core/activity` (pure), this is the storage + query
+ * half, and the console's **Event Logs** tab is the fleet-wide reader — it asks
+ * every live deployment through `satellite-kit/metrics`' bearer-gated
+ * `?view=events`, so an app is on the board by writing events, with no
+ * admin-side wiring at all.
+ *
+ * ── Retention ───────────────────────────────────────────────────────────────
+ * This package never deletes an event. An app whose stream is high-volume opts
+ * into the fleet standard (`docs/retention.md` in `cursed-satellites`) by
+ * declaring the table, which puts the number under the owner's control in the
+ * station rather than in a constant here:
+ *
+ * ```ts
+ * createSqliteTableTarget({
+ *   db, table: ACTIVITY_EVENTS_TABLE, timeColumn: "at", timeFormat: "iso",
+ *   declaration: { app: "notes", id: "activity", label: "Activity log",
+ *     category: "event-log", unit: "rows", location: "notes.sqlite · activity_events",
+ *     consequence: "Who did what, for hindsight. Losing it costs no data." },
+ * })
+ * ```
+ *
+ * An app whose stream is a handful of rows a month — an audit of destructive
+ * actions, say — is right to declare NOTHING and say so: the standard is opt-in
+ * by category, and an audit trail of production deletions is precisely the data
+ * a 14-day cutoff must not reach.
+ */
+export { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations";
+export { shareEventsSource, type ShareEventsSourceOptions } from "./shareSource";
+export { createActivityLog } from "./store";
+export type {
+	ActivityFacet,
+	ActivityFacets,
+	ActivityLog,
+	ActivityLogOptions,
+	ActivityPage,
+	ActivityQuery,
+	ActivitySource,
+} from "./store";
+// Re-exported so a server consumer needs ONE import for the whole contract; the
+// pure entry (`cursedbelt-core/activity`) stays available for a browser or a spec.
+export {
+	ACTIVITY_OUTCOMES,
+	activityFromShareEvent,
+	activitySubject,
+	describeActivityEvent,
+	describeActivityResource,
+	isActivityAction,
+	isActivityOutcome,
+} from "cursedbelt-core/activity/model";
+export type {
+	ActivityEvent,
+	ActivityEventInput,
+	ActivityOutcome,
+	ActivityResource,
+} from "cursedbelt-core/activity/model";

package/src/server/activity/migrations.ts

@@ -0,0 +1,67 @@
+import type { Database } from "bun:sqlite";
+import type { Migration } from "../migration/types";
+
+/** The one table this primitive owns. Exported so an app can declare a retention
+ *  target over it (see this module's `index.ts` for the recipe). */
+export const ACTIVITY_EVENTS_TABLE = "activity_events";
+
+/**
+ * ONE append-only table per app, not a shadow table per business table.
+ *
+ * The stream's whole value is being readable as one list — "everything that
+ * happened in `notes` yesterday", "everything `curt@…` did", "everything that
+ * touched person `3f2`" — and a per-table history cannot answer any of those
+ * without a UNION nobody maintains. `(kind, resource_id)` plays the role a
+ * shadow table would, and is a business key the app already has rather than a
+ * migration in `cursedbelt`.
+ *
+ * 🔴 **Append only.** There is no update and no delete verb anywhere in this
+ * package. The one sanctioned deleter is the fleet retention standard
+ * (`satellite-kit/retention`), which an app opts into by declaring this table as
+ * an `event-log`/`audit-log` resource — a control the owner can see and change,
+ * rather than a cutoff buried in a store.
+ */
+export const ACTIVITY_MIGRATIONS: readonly Migration[] = [
+	{
+		name: "0001_activity_events",
+		up(db: Database): void {
+			db.run(`
+				CREATE TABLE IF NOT EXISTS ${ACTIVITY_EVENTS_TABLE} (
+					event_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+					at          TEXT NOT NULL,
+					app         TEXT NOT NULL,
+					actor       TEXT NOT NULL,
+					action      TEXT NOT NULL,
+					kind        TEXT,
+					resource_id TEXT,
+					outcome     TEXT NOT NULL DEFAULT 'ok'
+					            CHECK (outcome IN ('ok', 'denied', 'error')),
+					note        TEXT NOT NULL DEFAULT '',
+					data        TEXT
+				)
+			`);
+			// The stream itself, newest first — the read every screen starts from.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_activity_events_at
+				 ON ${ACTIVITY_EVENTS_TABLE} (at DESC, event_id DESC)`,
+			);
+			// "Everything this person did" — the offboarding and the who-broke-it
+			// question, and the one a fleet-wide search runs first.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_activity_events_actor
+				 ON ${ACTIVITY_EVENTS_TABLE} (actor, event_id DESC)`,
+			);
+			// "Everything that ever happened to this record."
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_activity_events_resource
+				 ON ${ACTIVITY_EVENTS_TABLE} (kind, resource_id, event_id DESC)`,
+			);
+			// "Everything backups ever did" — an action-prefix filter is a range
+			// scan on this index, which is why the vocabulary is dotted.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_activity_events_action
+				 ON ${ACTIVITY_EVENTS_TABLE} (action, event_id DESC)`,
+			);
+		},
+	},
+];

package/src/server/activity/shareSource.ts

@@ -0,0 +1,57 @@
+/**
+ * The sharing primitive, as a contributor to the activity stream.
+ *
+ * 🔴 This is the whole point of `sources`: `cursedbelt-server/sharing` already
+ * keeps an audit trail nothing ever deletes, in `share_events`, and it is
+ * guaranteed to be complete (no grant can be made without a row — see that
+ * store's property 1). So the activity stream READS it where it lives rather
+ * than asking an app to mirror it. One row, one truth, no drift, and nothing to
+ * reconcile if a mirror write is ever missed.
+ *
+ * ```ts
+ * const activity = createActivityLog({
+ *   db, app: "family", sources: [shareEventsSource({ app: "family" })],
+ * });
+ * ```
+ *
+ * The mapping is field-for-field the one `activityFromShareEvent` performs in
+ * the vocabulary, and `store.spec.ts` asserts the two agree — a SQL projection
+ * and a TypeScript function are two implementations of one shape, so the suite
+ * pins them together rather than trusting that they were written on the same
+ * afternoon.
+ *
+ * `share_events.app` is NULL for a GROUP lifecycle event (creating a group is
+ * about no single resource), so the app is coalesced to the log's own name: a
+ * fleet-wide board merges on that column and an unlabeled row would be
+ * unattributable.
+ */
+import { SHARE_EVENTS_TABLE } from "../sharing/migrations";
+import type { ActivitySource } from "./store";
+
+export interface ShareEventsSourceOptions {
+	/** The satellite this log speaks for — the same value passed to
+	 *  `createActivityLog`, used where a group event names no resource. */
+	app: string;
+	/** Overridden only by a test hosting the table under another name. */
+	table?: string;
+	/** The contributor name, which prefixes every id it produces. */
+	name?: string;
+}
+
+export function shareEventsSource(options: ShareEventsSourceOptions): ActivitySource {
+	const table = options.table ?? SHARE_EVENTS_TABLE;
+	const name = options.name ?? "share";
+	return {
+		name,
+		requiresTable: table,
+		// Column contract: source, seq, at, app, actor, action, kind, resource_id,
+		// outcome, note, data — in this order. See `ActivitySource`.
+		sql: `SELECT '${name}' AS source, event_id AS seq, at, COALESCE(app, ?) AS app, actor,
+		             'share.' || action AS action, kind, resource_id,
+		             'ok' AS outcome, note,
+		             json_object('subjectType', subject_type, 'subjectId', subject_id,
+		                         'level', level, 'previousLevel', previous_level) AS data
+		        FROM ${table}`,
+		params: [options.app],
+	};
+}