cursedbelt-server 4.3.0 → 4.4.0

package/dist/server/d1/index.d.ts

@@ -15,7 +15,6 @@
  * ```
  */
 export { backupFor, type BackupPoint, checkpointWal, createLocalBackup, createTimeTravelBackup, type DatabaseBackup, type LocalBackupOpts, type TimeTravelOpts, } from './backup';
-export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
 export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';

package/dist/server/d1/index.js

@@ -15,7 +15,13 @@
  * ```
  */
 export { backupFor, checkpointWal, createLocalBackup, createTimeTravelBackup, } from './backup';
-export { createD1Kysely, D1LikeDialect } from './kysely';
+// 🔴 `./kysely` is deliberately NOT re-exported here — import it from
+// `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
+// `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it
+// made `import 'cursedbelt-server/d1'` throw `Cannot find package 'kysely'` for every app
+// that does not use the query builder — which per `../db/kysely.ts`'s own header is most
+// of them, since business tables stay on raw statements. Measured 2026-09-18 against the
+// published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -78,6 +78,12 @@
 			"source": "./src/server/d1/index.ts",
 			"import": "./dist/server/d1/index.js"
 		},
+		"./d1/kysely": {
+			"types": "./dist/server/d1/kysely.d.ts",
+			"bun": "./src/server/d1/kysely.ts",
+			"source": "./src/server/d1/kysely.ts",
+			"import": "./dist/server/d1/kysely.js"
+		},
 		"./d1/testing": {
 			"types": "./dist/server/d1/fakeD1.d.ts",
 			"bun": "./src/server/d1/fakeD1.ts",

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * A public subpath must not STATICALLY drag an OPTIONAL peer, because a static import is
+ * paid at import time by every consumer — including the ones that will never call it.
+ *
+ * ## 🔴 This is the same defect for the THIRD time, and the first two are why the rule is
+ * a check rather than a sentence
+ *
+ * `cursedbelt/src/barrelsReachNoOptionalPeer.spec.ts` carries the full history; the short
+ * version is that `apps/collections` once imported a TYPE from `cursedbelt/server/storage`
+ * and paid for it with `error: Cannot find package 'otplib'` and four dead route suites,
+ * because the barrel reached `streamToken.ts` → the `../auth` index → `totp.ts` → an
+ * optional peer. The app installed a one-time-password library to satisfy a claim shape.
+ *
+ * When the server tier split into this package (task 148), the RUNTIME-FIXTURE half came
+ * with it as `leafSubpathsImportNothing.spec.ts` — but that spec proves what a declared
+ * ZERO-RUNTIME LEAF pulls in, and a barrel is neither. So the barrel half stayed behind in
+ * `cursedbelt`, pointed at `./react`, and **this package shipped with no barrel check at
+ * all.**
+ *
+ * 🔴 It cost exactly what the first two cost, measured 2026-09-18 against the PUBLISHED
+ * `cursedbelt-server@4.3.0` tarball in a clean directory:
+ *
+ *     $ bun add cursedbelt-server && bun -e 'import "cursedbelt-server/d1"'
+ *     error: Cannot find package 'kysely' from …/src/server/d1/kysely.ts
+ *
+ * `./d1`'s index re-exported `./kysely`, which statically imports real VALUES from
+ * `kysely` (`Kysely`, `SqliteAdapter`, `SqliteQueryCompiler` — not types, so they cannot be
+ * erased). `kysely` is an optional peer. So the D1 seam — the thing the whole fleet is
+ * meant to port ONTO — could not be imported by any app that had not already installed a
+ * query builder, which by `../db/kysely.ts`'s own header is most of them: *"Business /
+ * `data JSON` tables stay on raw `db.query()` — do NOT add them here"*. The seam was
+ * unusable by precisely the apps it was built for.
+ *
+ * The fix was to give `createD1Kysely` its own subpath (`./d1/kysely`) and take it out of
+ * the barrel. This spec is what stops the fourth occurrence.
+ *
+ * ## What it measures
+ *
+ * Every subpath in the `exports` map is bundled with bare imports left external, and the
+ * remaining static specifiers are read out of the emitted JS. A DYNAMIC `await
+ * import('sharp')` inside the function that needs it matches neither branch of
+ * {@link STATIC_SPECIFIER} and must not — that is the lazy shape this file exists to
+ * permit, not forbid.
+ *
+ * ## Verified failing before it was trusted (2026-09-18)
+ *
+ *   · re-adding `export … from './kysely'` to `src/server/d1/index.ts`
+ *       → red: "./d1 statically drags optional peer(s): kysely"
+ *   · adding `import 'plainjob';` to `src/server/d1/local.ts` — two hops out of the
+ *     barrel, which grepping the index file cannot see
+ *       → red identically. That is the branch that matters.
+ *   · removing `'./jobs'` from {@link MAY_DRAG} → red, proving the allowlist is load-bearing
+ *     rather than decorative.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * The subpaths whose whole PURPOSE is the optional peer they pull, mapped to what they are
+ * allowed to pull and why. An entry here is a promise that the peer is the point of the
+ * subpath — not a place to park a new drag.
+ *
+ * 🔴 Measured 2026-09-18: these three are the ONLY subpaths in the map that reach an
+ * optional peer. Everything else is clean, which is what makes this list an allowlist
+ * rather than a baseline — it can only shrink.
+ */
+const MAY_DRAG: Record<string, readonly string[]> = {
+	// The whole-package barrel. It exists to re-export everything, so it necessarily reaches
+	// what the specific subpaths reach. An app importing `cursedbelt-server` whole is asking
+	// for that; an app importing `cursedbelt-server/d1` is not, and that is the distinction
+	// this spec protects.
+	'.': ['kysely', 'kysely-bun-sqlite', 'otplib', 'plainjob'],
+	// `createD1Kysely` IS the kysely adapter. Split out of `./d1` on 2026-09-18 precisely so
+	// the seam itself stops paying for it — see the header.
+	'./d1/kysely': ['kysely'],
+	// The job queue is plainjob. Nothing else here is.
+	'./jobs': ['plainjob'],
+};
+
+const OPTIONAL_PEERS = new Set(
+	Object.entries(
+		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},
+	)
+		.filter(([, meta]) => meta?.optional === true)
+		.map(([name]) => name),
+);
+
+/**
+ * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.
+ *
+ * Anchored on the `from` clause rather than on a line starting with `import`, so a
+ * multi-line named import still counts — bun emits `import {\n … \n} from "pkg";` and a
+ * line-anchored pattern silently misses it. A dynamic `import("pkg")` matches neither
+ * branch, which is deliberate.
+ */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+/** `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`. */
+const packageOf = (specifier: string): string | undefined => {
+	const parts = specifier.split('/');
+	return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/**
+ * Bundle one entry and return the bare packages it still imports.
+ *
+ * 🔴 A bundle that did not happen must never read as a subpath that pulls nothing, so a
+ * non-zero exit or an empty bundle THROWS rather than returning an empty set. That is the
+ * one way a check like this dies quietly.
+ */
+const staticExternalsOf = (entry: string, subpath: string): Set<string> => {
+	const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-server-barrel-scan/${subpath.replace(/[^a-z0-9]+/gi, '-')}`;
+	const build = Bun.spawnSync(['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir], {
+		cwd: REPO,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+	const emitted = [...new Bun.Glob('**/*.js').scanSync({ cwd: outdir, onlyFiles: true })];
+	const bundle = emitted.map((f) => readFileSync(`${outdir}/${f}`, 'utf8')).join('\n');
+	if (build.exitCode !== 0 || bundle.trim() === '') {
+		throw new Error(
+			`could not bundle ${subpath} (${entry}, exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
+		);
+	}
+	const found = new Set<string>();
+	for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
+		const specifier = match[1] ?? match[2];
+		if (specifier === undefined || specifier.startsWith('.') || specifier.startsWith('bun:')) continue;
+		const name = packageOf(specifier);
+		if (name !== undefined) found.add(name);
+	}
+	return found;
+};
+
+/** Every subpath with a `source` entry — the ones whose real graph can be measured. */
+const SUBPATHS = Object.entries(pkg.exports as Record<string, { source?: string }>)
+	.filter(([, e]) => typeof e?.source === 'string' && /\.tsx?$/.test(e.source))
+	.map(([subpath, e]) => ({ subpath, entry: (e as { source: string }).source }));
+
+describe('no public subpath statically drags an optional peer', () => {
+	it('measures a non-trivial number of subpaths, so a broken exports map cannot pass vacuously', () => {
+		expect(SUBPATHS.length).toBeGreaterThan(20);
+		expect(OPTIONAL_PEERS.size).toBeGreaterThan(0);
+	});
+
+	for (const { subpath, entry } of SUBPATHS) {
+		const allowed = MAY_DRAG[subpath] ?? [];
+		it(`${subpath} drags ${allowed.length === 0 ? 'no optional peer' : allowed.join(' + ') + ' and nothing more'}`, () => {
+			const dragged = [...staticExternalsOf(entry, subpath)].filter((n) => OPTIONAL_PEERS.has(n)).sort();
+			const unexpected = dragged.filter((n) => !allowed.includes(n));
+			expect(
+				unexpected,
+				`${subpath} statically drags optional peer(s): ${unexpected.join(', ')}\n` +
+					`  Every app importing '${pkg.name}${subpath.slice(1)}' must now install them or crash on import.\n` +
+					`  Give the adapter its own subpath and take it out of this barrel — see ./d1/kysely, which is\n` +
+					`  exactly this fix applied on 2026-09-18 after the published 4.3.0 could not be imported at all.`,
+			).toEqual([]);
+
+			// The allowlist may only shrink: an entry that no longer drags what it promised is
+			// a stale exception, and a stale exception is how a list like this stops meaning
+			// anything.
+			const stale = allowed.filter((n) => !dragged.includes(n));
+			expect(stale, `${subpath} is allowed to drag ${stale.join(', ')} but no longer does — remove the exception`).toEqual(
+				[],
+			);
+		});
+	}
+});

package/src/server/d1/index.ts

@@ -25,7 +25,13 @@ export {
 	type LocalBackupOpts,
 	type TimeTravelOpts,
 } from './backup';
-export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+// 🔴 `./kysely` is deliberately NOT re-exported here — import it from
+// `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
+// `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it
+// made `import 'cursedbelt-server/d1'` throw `Cannot find package 'kysely'` for every app
+// that does not use the query builder — which per `../db/kysely.ts`'s own header is most
+// of them, since business tables stay on raw statements. Measured 2026-09-18 against the
+// published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';