@teamscala/service-boot 0.23.412 → 0.23.413

package/src/build-client-assets.ts

@@ -22,793 +22,36 @@
  * resolved versions of the third-party deps the closure imports) is hashed by
  * CONTENT and stored in the manifest; the rebuild is skipped only when the
  * current closure hashes to the same fingerprint (cache-key-hashes-source-
- * inputs-only — never mtime; see computeInputFingerprint for why mtime silently
+ * inputs-only — never mtime; see input-fingerprint.ts for why mtime silently
  * served stale bundles on Railway). bun.lock is deliberately NOT hashed — it
  * encodes every @teamscala/* version including backend packages outside this
  * service's client bundle, so folding it in would rebuild on every publish
- * (the publish→rebuild storm; `no-uncontrolled-repetition-or-cascade`). First
- * pm2 restart after a real closure change pays the full build cost; unchanged
+ * (the publish→rebuild storm; `no-uncontrolled-repetition-or-cascade`). A
+ * restart after a real closure change pays the full build cost; unchanged
  * restarts skip. Stale hashed outputs from a prior build are removed in the
  * same pass so dist/client/ doesn't accumulate dead files.
+ *
+ * This module is the ORCHESTRATION unit: fingerprint check → host-wide lock
+ * → parallel hydrate/CSS builds → manifest write (or failure tombstone). The
+ * individual concerns live as siblings under ./build-client-assets/
+ * (input-hashing, source-candidates, input-fingerprint, manifest,
+ * hashed-output, hydrate-bundle, sourcemaps-upload, styles-build, build-lock)
+ * — split when the parent held them all at 962 lines.
  */
 
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, rename, rm } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
 import { withFileLock } from "@teamscala/file-lock/with-lock";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { userHome } from "@teamscala/os/host-paths";
-import { spawnSync } from "@teamscala/os/spawn";
-import { compile } from "tailwindcss";
-// Input hashing lives in its own module — build-client-assets.ts held six
-// distinct concerns at 1221 lines (single-purpose-file measures export-name
-// cohesion, so it never flagged this). computeInputFingerprint below still
-// composes these two; the rest of that unit is private to the module.
+import { CLIENT_BUILD_LOCK, getClientBuildLockTimeoutMs } from "./build-client-assets/build-lock.ts";
+import { buildHydrateBundle } from "./build-client-assets/hydrate-bundle.ts";
+import { computeInputFingerprint } from "./build-client-assets/input-fingerprint.ts";
 import {
-	hashResolvedPackageStylesheets,
-	hashTeamgbgJsGraph,
-} from "./build-client-assets/input-hashing.ts";
-import { scanSourceCandidates } from "./build-client-assets/source-candidates.ts";
-import * as v from "valibot";
-
-const HYDRATE_BASE = "hydrate";
-const STYLES_BASE = "styles";
-const MANIFEST_FILE = "asset-manifest.json";
-
-/**
- * Read ONLY the tombstone state of the current manifest — the runtime
- * (read-html-template, ui-service) calls this to decide whether to surface a
- * build-failure signal. Returns null when the manifest is fresh (no
- * `buildFailed`). Decoupled from the full AssetManifest read so the runtime
- * never depends on the build internals.
- */
-export async function readClientBuildStatus(
-	cwd = process.cwd(),
-): Promise<{ failed: true; reason?: string; at?: string } | { failed: false }> {
-	const path = join(cwd, "dist", "client", MANIFEST_FILE);
-	if (!(await Bun.file(path).exists())) return { failed: false };
-	try {
-		const parsed = (await Bun.file(path).json()) as Partial<AssetManifest>;
-		if (parsed.buildFailed === true) {
-			return {
-				failed: true,
-				reason: parsed.buildFailedReason,
-				at: parsed.buildFailedAt,
-			};
-		}
-	} catch {}
-	return { failed: false };
-}
-
-// Single shared host lock serialising the heavy boot-time client build across
-// ALL kind:ui services (client-asset-builds-serialize-via-lock). A publish of a
-// widely-consumed package makes the dep-sync restart every consumer at
-// once; without this lock each one rebuilds its hydrate bundle + Tailwind CSS
-// simultaneously and N concurrent builds saturate the host (load 36, each ~15s
-// build starved to ~10min, services offline — 2026-06-13). The build sibling of
-// `restart-drivers-serialize-via-lock`'s `.scala-pm2-restart.lock`.
-const CLIENT_BUILD_LOCK = join(userHome(), ".scala-client-build.lock");
-// Generous: serialised builds drain well within this. On timeout we build
-// UNLOCKED (fail-open) — the lock is a thundering-herd optimisation, never a
-// correctness gate, and must never block a boot. TTL is DB-driven
-// (config/build-client-assets), promoted from the former hardcoded constant.
-const DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS = 600_000;
-let cachedClientBuildLockTimeoutMs: number | undefined;
-async function getClientBuildLockTimeoutMs(): Promise<number> {
-	if (cachedClientBuildLockTimeoutMs !== undefined) return cachedClientBuildLockTimeoutMs;
-	// Fail-soft to the hardcoded default: the deploy-build bake runs this in a
-	// standalone subprocess with NO registered Prisma client (a pre-DB build
-	// context), so loadRegistryConfig throws "Prisma client not registered". The
-	// lock is a thundering-herd optimisation, never a correctness gate ("must
-	// never block a boot"), and the TTL has a safe hardcoded default — so a
-	// registry-read failure must degrade to the default, never abort the bake.
-	try {
-		const row = await loadRegistryConfig("config", "build-client-assets", v.looseObject({}));
-		cachedClientBuildLockTimeoutMs =
-			(row?.client_build_lock_timeout_ms as number | undefined) ??
-			DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS;
-	} catch {
-		cachedClientBuildLockTimeoutMs = DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS;
-	}
-	return cachedClientBuildLockTimeoutMs;
-}
-
-interface AssetManifest {
-	stylesPath: string;
-	hydratePath: string;
-	// Content fingerprint of the CLIENT-BUNDLE DEPENDENCY CLOSURE (source
-	// entrypoints + @teamscala/* JS/CSS in the closure + third-party closure-dep
-	// versions), hashed by CONTENT — never mtime (cache-key-hashes-source-
-	// inputs-only). The boot/build freshness check rebuilds iff this differs
-	// from the current closure. mtime comparison is fundamentally broken on
-	// Railway: deploy-build bakes the bundle at image-build time, and under the
-	// hoisted linker + warm `bun-install` cache the installed @teamscala/* files
-	// are hardlinks carrying OLD extraction mtimes while the baked manifest's
-	// mtime is newer — so `source.mtime > manifest.mtime` is false and the
-	// build wrongly skips, baking (then serving forever) a STALE client bundle
-	// even though a newer @teamscala/* version is installed. Observed 2026-06-14:
-	// scala-gpt shipped ui-foundation < 85 in the bundle while a newer version
-	// was installed, so a published+installed fix never reached the browser.
-	// Content hashing of the closure is immune to mtime games. bun.lock is
-	// excluded by design — see computeInputFingerprint.
-	inputFingerprint?: string;
-	// TOMBSTONE fields — present iff the last build FAILED (no-silent-reverts).
-	// `buildFailed: true` + reason + timestamp are written by performBuild
-	// before it re-throws. The next boot's fingerprint check sees the
-	// `failed:<iso>` sentinel and cannot match → forces a retry (no silent
-	// skip on the stale manifest). read-html-template reads these to stamp
-	// the served HTML with the failure status (operator-visible signal that
-	// the bundle is stale, not fresh).
-	buildFailed?: boolean;
-	buildFailedReason?: string;
-	buildFailedAt?: string;
-}
-
-// Last-resort paths for a tombstone when no prior successful manifest exists
-// (first-ever boot fails). Points at the unhashed build names so an operator
-// inspecting the manifest sees a real (if 404-ing) target rather than a
-// mystery sentinel.
-const FALLBACK_MANIFEST: { stylesPath: string; hydratePath: string } = {
-	stylesPath: "/assets/styles.css",
-	hydratePath: "/assets/hydrate.js",
-};
-
-async function fileHash(path: string): Promise<string> {
-	const buf = await Bun.file(path).text();
-	return createHash("sha256").update(buf).digest("hex").slice(0, 10);
-}
-
-async function readManifest(outDir: string): Promise<AssetManifest | null> {
-	const path = join(outDir, MANIFEST_FILE);
-	if (!(await Bun.file(path).exists())) return null;
-	try {
-		const parsed = await Bun.file(path).json() as Partial<AssetManifest>;
-		if (parsed.stylesPath && parsed.hydratePath) {
-			return {
-				stylesPath: parsed.stylesPath,
-				hydratePath: parsed.hydratePath,
-				inputFingerprint: parsed.inputFingerprint,
-				buildFailed: parsed.buildFailed,
-				buildFailedReason: parsed.buildFailedReason,
-				buildFailedAt: parsed.buildFailedAt,
-			};
-		}
-		return null;
-	} catch {
-		return null;
-	}
-}
-
-async function writeManifest(
-	outDir: string,
-	manifest: AssetManifest,
-): Promise<void> {
-	await Bun.write(
-		join(outDir, MANIFEST_FILE),
-		`${JSON.stringify(manifest, null, 2)}\n`,
-	);
-}
-
-async function removeStaleHashedFiles(
-	outDir: string,
-	base: string,
-	ext: string,
-	keep: string,
-): Promise<void> {
-	if (!(await Bun.file(outDir).exists())) return;
-	const re = new RegExp(`^${base}-[a-f0-9]+\\.${ext}$`);
-	for (const name of (await readdir(outDir, "utf-8"))) {
-		if (re.test(name) && name !== keep) {
-			try {
-				await rm(join(outDir, name));
-			} catch {}
-		}
-	}
-}
-
-async function buildHydrateBundle(
-	cwd: string,
-	log: ReturnType<typeof getAppLogger>,
-): Promise<string | null> {
-	const entry = join(cwd, "src", "entry-client.ts");
-	const outDir = join(cwd, "dist", "client");
-	const tmpFile = join(outDir, `${HYDRATE_BASE}.js`);
-
-	if (!(await Bun.file(entry).exists())) {
-		log.warn(
-			`[build-client-assets] src/entry-client.ts not found at ${entry} — skipping JS bundle`,
-		);
-		return null;
-	}
-
-	await mkdir(outDir, { recursive: true });
-
-	// Resilience (block-and-provider-error-isolation applied to the BUILD): a
-	// page-manifest.ts lazy import of a block whose component no longer resolves
-	// (a block_schema deactivation or a removed package export whose manifest
-	// regen never propagated) MUST NOT fail the whole bundle and crash-loop the
-	// service. Seven UI services went down at once this way on 2026-06-13. Such
-	// an import is EXTERNALIZED instead: the build succeeds, the service boots,
-	// and at runtime that one lazy import rejects into the block's
-	// BlockErrorBoundary — the dead block degrades, the page + service stay up.
-	// Only UNRESOLVABLE @teamgbg specifiers are touched (resolvable ones fall
-	// through to Bun's normal resolution unchanged). Surfaced via warn so it is
-	// never silent; the `no-dead-block-imports-in-manifest` guard still flags the
-	// stale manifest so it gets regenerated.
-	const externalizedBlocks: string[] = [];
-	const resilientBlockPlugin: Bun.BunPlugin = {
-		name: "resilient-block-imports",
-		setup(build: { onResolve: (opts: { filter: RegExp }, cb: (args: { path: string }) => { path: string; external: boolean } | undefined) => void }) {
-			// Externalize an unresolvable @teamscala/* block import (a deactivated
-			// block_schema whose manifest regen never propagated) or a broken
-			// third-party internal (@fullcalendar/core/internal.js during a version
-			// mismatch) so it degrades ONE block at runtime instead of crash-looping
-			// the service (2026-07-21 portal outage: @fullcalendar 7.x + plugins 6.x
-			// → unresolvable internal.js → 21 crash-loop restarts).
-			//
-			// The filter is deliberately NARROW — only the package prefixes where
-			// unresolvable imports actually occur — NOT every bare import. The prior
-			// broad /^(?![./])/ filter intercepted resolvable shared packages too,
-			// and onResolve pass-through (return undefined) on a shared
-			// sideEffects:false package (@tanstack/react-query, imported across many
-			// lazy block chunks) tripped Bun's code-splitter: it emitted a dead
-			// `export{...}`-with-no-`from` facade and tree-shook away the entire
-			// query-core implementation → a fatal hydration SyntaxError that froze
-			// agents.scala.business while every component reported healthy
-			// (2026-07-22; see the dead-facade gate + minifyIdentifiers:false
-			// below). Intercepts of node builtins (stream/web) likewise pulled them
-			// into the browser build. The narrow filter leaves @tanstack/* + builtins
-			// to Bun's native (correct) resolution. A future unresolvable import
-			// OUTSIDE these prefixes fails loud via the manifest guard + build
-			// tombstone (no-dead-block-imports-in-manifest) — never silent.
-			// Entry-point imports are excluded — those must fail loudly (silently
-			// externalizing a core import turns a build error into a mystery runtime
-			// crash; containment must not become a swallow).
-			build.onResolve({ filter: /^(@teamgbg\/|@fullcalendar\/)/ }, (args) => {
-				if (args.importer === entry) return undefined;
-				try {
-					Bun.resolveSync(args.path, cwd);
-					return undefined;
-				} catch {
-					if (!externalizedBlocks.includes(args.path)) externalizedBlocks.push(args.path);
-					return { path: args.path, external: true };
-				}
-			});
-		},
-	};
-
-	let result: Awaited<ReturnType<typeof Bun.build>>;
-	try {
-		result = await Bun.build({
-			entrypoints: [entry],
-			target: "browser",
-			outdir: outDir,
-			naming: `${HYDRATE_BASE}.js`,
-			// minifyIdentifiers is DISABLED (whitespace + syntax/dead-code minify
-			// kept): under code-splitting, identifier mangling interacting with a
-			// shared sideEffects:false package (@tanstack/react-query) trips Bun's
-			// splitter to tree-shake away the entire implementation and emit a dead
-			// re-export facade — a fatal hydration SyntaxError that froze
-			// agents.scala.business while every component reported healthy
-			// (2026-07-22; reproduces in stable 1.3.14 + canary 1.4.0, so an upstream
-			// fix is not near). Whitespace + syntax minify retain the bulk of the
-			// size win; only name-mangling is dropped. The post-build dead-facade
-			// gate below fails the build LOUD if this or any future regression slips
-			// a fatal facade through on any UI service.
-			minifyWhitespace: process.env.NODE_ENV === "production",
-			minifySyntax: process.env.NODE_ENV === "production",
-			minifyIdentifiers: false,
-			// Bun plugin type
-			plugins: [resilientBlockPlugin],
-			// Code-splitting honours `lazy-blocks-per-page`: page-manifest.ts wraps
-			// every block in `lazy(() => import())`, so splitting emits the heavy
-			// Plate editor + each lazy block as a SEPARATE chunk loaded on demand
-			// instead of inlining all of them into one ~12.5MB entry. The initial
-			// download drops ~10× (entry ~1.2MB; chunks lazy). splitting:false was
-			// drift that defeated the lazy manifest. SSR safety is intact — the
-			// page-server awaits stream.allReady before flushing (render-page-html),
-			// so every block is server-rendered and hydration is consistent.
-			splitting: true,
-			// External source maps so minified client stacks resolve to source in
-			// GlitchTip (uploaded post-build by uploadSourceMaps via the official
-			// glitchtip-cli debug-ID flow). Maps are deleted after upload — never
-			// served; the debug IDs injected into the bundles are all the SDK needs.
-			sourcemap: "external",
-			// Chunks are referenced by absolute /assets/ URL (served by
-			// register-static-assets' /assets/* handler), never a relative path that
-			// could mis-resolve under a record route like /?id=<uuid>.
-			publicPath: "/assets/",
-			external: ["*.css"],
-		});
-	} catch (e) {
-		// Bun.build can THROW (not return {success:false}) on certain failure
-		// modes — e.g. entrypoint resolves to a path Bun can't read, or an
-		// internal panic. Without this catch the boot path swallows the
-		// useful diagnostic and the operator sees only "Bundle failed".
-		// AggregateError carries the per-file resolution list in .errors —
-		// without serializing it the operator sees only "Bundle failed"
-		// (cost a full Railway round-trip per guess on 2026-06-05).
-		const subErrors =
-			e instanceof AggregateError
-				? e.errors.map((se) => (se instanceof Error ? se.message : String(se)))
-				: [];
-		log.error(`[build-client-assets] Bun.build threw`, {
-			message: e instanceof Error ? e.message : String(e),
-			errors: subErrors,
-			stack: e instanceof Error ? e.stack : undefined,
-			entry,
-			outDir,
-		});
-		throw new Error(
-			`[build-client-assets] Bun.build threw: ${e instanceof Error ? e.message : String(e)}${subErrors.length ? `\n${subErrors.join("\n")}` : ""}`,
-		);
-	}
-
-	if (!result.success) {
-		// Bun.build's `.logs` is the verbose-build-message list. Each log is an
-		// object with at minimum `{ level, message, position }`. Some failures
-		// surface with an empty logs array — happens when Bun bails before
-		// resolution (e.g. missing entrypoint after symlink-walk). Always emit
-		// the full JSON form via the logger so service-runtime's structured
-		// error trail captures every field, not just a `.message`-joined string.
-		log.error(`[build-client-assets] Bun.build failed`, {
-			logs: result.logs.map((l) => ({
-				level: (l as { level?: string }).level,
-				message: l.message,
-				position: (l as { position?: unknown }).position,
-			})),
-			outputs: result.outputs.length,
-			entry,
-			outDir,
-		});
-		const messages = result.logs.length
-			? result.logs
-					.map(
-						(l) => `[${(l as { level?: string }).level ?? "?"}] ${l.message}`,
-					)
-					.join("\n")
-			: "(no log entries — likely entrypoint resolution failure)";
-		throw new Error(`[build-client-assets] Bun.build failed:\n${messages}`);
-	}
-
-	// dead-facade prevention gate (agents.scala.business 2026-07-22): a Bun
-	// splitter+tree-shake bug (stable 1.3.14 + canary 1.4.0) can emit a "dead
-	// facade" chunk — `export { ... }` with NO `from` clause and NO local binding
-	// definitions — a fatal SyntaxError at module load that kills React hydration
-	// SILENTLY (the whole dashboard froze while every component reported healthy).
-	// The narrow resilientBlockPlugin filter + minifyIdentifiers:false above
-	// prevent the known trigger (@tanstack/react-query under split); this gate
-	// makes the CLASS unshippable — any dead facade from ANY package on ANY UI
-	// service fails the build LOUD here instead of freezing the page. Detection
-	// is POSITION-INDEPENDENT — a named export{} ANYWHERE in the comment-stripped
-	// body, with no `from` clause and no local declaration/import backing the
-	// names, is the facade (Bun could prefix it with a directive or statement, not
-	// only emit it at the very start — a positional assumption is a known way to
-	// be silently bypassed; a valid local-export chunk carries a
-	// class/function/const/var/let/import, a valid re-export carries `from`).
-	const deadFacades: string[] = [];
-	for (const out of result.outputs) {
-		if (out.kind !== "chunk") continue;
-		let text: string;
-		try {
-			text = await Bun.file(out.path).text();
-		} catch {
-			continue;
-		}
-		const stripped = text
-			.replace(/\/\/#.*$/gms, "")
-			.replace(/\/\/[^\n]*/g, "")
-			.replace(/\/\*[\s\S]*?\*\//g, "")
-			.trim();
-		if (
-			/export\s*\{[^}]*\}/.test(stripped) &&
-			!/\bfrom\s*["']/.test(stripped) &&
-			!/\b(?:class|function|const|var|let|import)\b/.test(stripped)
-		) {
-			deadFacades.push(out.path.split("/").pop() ?? out.path);
-		}
-	}
-	if (deadFacades.length > 0) {
-		log.error(`[build-client-assets] dead-facade gate: refusing to ship fatal bundle`, {
-			deadFacades,
-			hint: "A dead facade (export{} with no from/source) is a fatal hydration SyntaxError. Investigate a shared sideEffects:false package under splitting, or a Bun splitter+minifyIdentifiers regression.",
-		});
-		throw new Error(
-			`[build-client-assets] Bun.build emitted ${deadFacades.length} dead facade chunk(s) (export{} with no from/source — a fatal hydration SyntaxError). Refusing to ship a broken bundle. Files: ${deadFacades.join(", ")}`,
-		);
-	}
-
-	const hash = await fileHash(tmpFile);
-	const hashedName = `${HYDRATE_BASE}-${hash}.js`;
-	const hashedPath = join(outDir, hashedName);
-	await rename(tmpFile, hashedPath);
-	removeStaleHashedFiles(outDir, HYDRATE_BASE, "js", hashedName);
-
-	// Splitting emits one chunk per lazy import() alongside the entry. Keep the
-	// chunks THIS build produced; drop stale ones so dist/client/ doesn't
-	// accumulate hundreds of orphaned chunks per rebuild.
-	const currentChunks = new Set(
-		result.outputs
-			.filter((o) => o.kind === "chunk")
-			.map((o) => o.path.split("/").pop() as string),
-	);
-	await removeStaleChunks(outDir, currentChunks);
-
-	// Bundle telemetry → logger (single-logger-entry-point → GlitchTip): the
-	// initial-download size + lazy-chunk footprint are visible per build, so a
-	// regression (splitting silently off, or a heavy dep landing in the entry)
-	// surfaces as a number instead of a mystery "slow page".
-	const entryBytes = (await Bun.file(hashedPath).stat()).size;
-	let chunkBytes = 0;
-	for (const name of currentChunks) {
-		try {
-			chunkBytes += (await Bun.file(join(outDir, name)).stat()).size;
-		} catch {}
-	}
-	log.info(
-		`[build-client-assets] hydrate built → ${hashedName} (entry ${(entryBytes / 1024).toFixed(0)}KB + ${currentChunks.size} lazy chunks ${(chunkBytes / 1048576).toFixed(1)}MB)`,
-		{ entryBytes, chunkCount: currentChunks.size, chunkBytes },
-	);
-	if (externalizedBlocks.length > 0) {
-		// The service boots; these blocks degrade at runtime (BlockErrorBoundary)
-		// instead of crash-looping the whole service. The stale manifest still
-		// needs regenerating — surfaced here AND by no-dead-block-imports-in-manifest.
-		log.warn(
-			`[build-client-assets] ${externalizedBlocks.length} unresolvable block import(s) externalized (degraded, not fatal) — regenerate this service's page-manifest: ${externalizedBlocks.join(", ")}`,
-			{ externalizedBlocks },
-		);
-	}
-	// Upload source maps to GlitchTip (best-effort, dev-host-only) + delete the
-	// .map files so source never ships publicly. See uploadSourceMaps.
-	await uploadSourceMaps(outDir, hash, log);
-	return `/assets/${hashedName}`;
-}
-
-/**
- * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
- * flow (the documented first-class mechanism — `sourcemaps inject` then
- * `sourcemaps upload --release`; see telemetry.md `client-errors-report-to-glitchtip`
- * + https://glitchtip.com/documentation/cli). Debug IDs injected into the served
- * bundles + uploaded maps are the matching mechanism — robust vs URL-prefix
- * guessing. Best-effort + dev-host-only: skips silently when the CLI or
- * SENTRY_AUTH_TOKEN is absent (Railway builds don't install the CLI; prod source
- * maps are a follow-up). The .map files are deleted after upload — source never
- * ships publicly; the debug IDs in the served bundles are all the SDK needs.
- */
-async function uploadSourceMaps(
-	outDir: string,
-	release: string,
-	log: ReturnType<typeof getAppLogger>,
-): Promise<void> {
-	const token = process.env.SENTRY_AUTH_TOKEN;
-	const sentryUrl = process.env.SENTRY_URL;
-	if (!token || !sentryUrl) return; // best-effort: no token/URL → skip
-	const org = process.env.SENTRY_ORG ?? "scala";
-	const project = process.env.SENTRY_PROJECT ?? "scala-hub";
-	const cli = join(userHome(), ".local", "bin", "glitchtip-cli");
-	const headers = { Authorization: `Bearer ${token}` };
-	try {
-		// Inject debug IDs into the bundles + maps (if glitchtip-cli is present).
-		// The CLI is optional — only used for the inject step.
-		if (existsSync(cli)) {
-			spawnSync({
-				name: "glitchtip-cli-sourcemaps-inject",
-				command: [cli, "sourcemaps", "inject", outDir],
-				env: { ...process.env, SENTRY_AUTH_TOKEN: token },
-				timeoutMs: 60_000,
-				captureStderr: true,
-			});
-		}
-		// Upload source maps via the direct release-files API (NOT the CLI's
-		// chunk-upload — that hits a host-mismatch behind reverse proxies: the
-		// server returns a stale internal URL the CLI refuses to send the token to).
-		// The direct API posts to SENTRY_URL (which we control) — no server-returned
-		// URL, no host mismatch.
-		await fetch(`${sentryUrl}/api/0/organizations/${org}/releases/`, {
-			method: "POST",
-			headers: { ...headers, "Content-Type": "application/json" },
-			body: JSON.stringify({ version: release, projects: [project] }),
-		});
-		let uploaded = 0;
-		for (const name of await readdir(outDir, "utf-8")) {
-			if (!name.endsWith(".map")) continue;
-			try {
-				const mapBytes = await Bun.file(join(outDir, name)).bytes();
-				const form = new FormData();
-				form.append("name", `~/assets/${name.replace(".map", "")}`);
-				form.append("file", new Blob([mapBytes]), name);
-				const res = await fetch(
-					`${sentryUrl}/api/0/projects/${org}/${project}/releases/${release}/files/`,
-					{ method: "POST", headers, body: form },
-				);
-				if (res.ok) uploaded++;
-			} catch {}
-		}
-		log.info("[build-client-assets] source maps uploaded to GlitchTip", {
-			release,
-			project,
-			uploaded,
-		});
-	} catch (err) {
-		log.warn("[build-client-assets] source-map upload error (best-effort, skipped)", {
-			release,
-			error: err instanceof Error ? err.message : String(err),
-		});
-	}
-	// Delete the .map files — never serve source. The debug IDs injected into the
-	// served bundles are all the SDK needs; the maps live in GlitchTip keyed by them.
-	for (const name of await readdir(outDir, "utf-8")) {
-		if (name.endsWith(".map")) {
-			try {
-				await rm(join(outDir, name));
-			} catch {}
-		}
-	}
-}
-
-// Remove hashed code-split chunks no longer referenced by the current entry.
-// Keyed off the build's own output list (the only authoritative current set),
-// never a name pattern guess — a build emits N `chunk-*.js`; the previous
-// build's are orphaned the moment the entry's hash changes.
-async function removeStaleChunks(
-	outDir: string,
-	keep: Set<string>,
-): Promise<void> {
-	if (!(await Bun.file(outDir).exists())) return;
-	for (const name of (await readdir(outDir, "utf-8"))) {
-		if (/^chunk-[A-Za-z0-9]+\.js$/.test(name) && !keep.has(name)) {
-			try {
-				await rm(join(outDir, name));
-			} catch {}
-		}
-	}
-}
-
-async function resolveStylesheetRaw(
-	id: string,
-	base: string,
-	cwd: string,
-): Promise<{ path: string; base: string; content: string }> {
-	if (id === "tailwindcss") {
-		const r = await Bun.resolve("tailwindcss/index.css", cwd);
-		return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
-	}
-	try {
-		const r = await Bun.resolve(id, base);
-		return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
-	} catch {}
-	if (!id.startsWith(".")) {
-		try {
-			const pkgPath = await Bun.resolve(id + "/package.json", cwd);
-			const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
-			const entry =
-				pkg.exports?.["."]?.style || pkg.style || pkg.main;
-			if (entry) {
-				const r = resolve(dirname(pkgPath), entry);
-				return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
-			}
-		} catch {}
-	}
-	const r = resolve(base, id);
-	return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
-}
-
-// Tailwind v4's compile() invokes `loadStylesheet` for DIRECT @imports in the
-// entry (app.css) but does NOT re-invoke it for @imports WITHIN the loaded
-// content — so a package styles.css that itself `@import "./Leaf.css"` (a
-// nested RELATIVE import) has its leaf silently dropped from the prod bundle.
-// This dropped every block-specific class reachable only via a nested
-// relative @import (project-list-view/ProjectListView.css's
-// .nested-list-table-host, audit-block's nested css, etc.) while direct
-// package @imports (generic-ui/blk-utilities → .blk-*) survived — the
-// 2026-07-05 #6 outage (broken projects UI). Inline nested @imports here so
-// the content returned to Tailwind is flat; the compile() loadStylesheet
-// callback then never sees a nested @import it would drop. Cycle-safe via
-// `seen` (mirrors hashResolvedPackageStylesheet's transitive walk).
-const CSS_IMPORT_RE = /@import\s+(?:url\()?\s*["']([^"']+)["']\s*\)?[^;]*;?/g;
-async function inlineCssImports(
-	css: string,
-	base: string,
-	cwd: string,
-	seen: Set<string>,
-): Promise<string> {
-	let result = "";
-	let lastIdx = 0;
-	for (const m of css.matchAll(CSS_IMPORT_RE)) {
-		const spec = m[1].trim();
-		result += css.slice(lastIdx, m.index);
-		lastIdx = (m.index ?? 0) + m[0].length;
-		// Keep the tailwindcss entry verbatim (Tailwind compile owns it —
-		// including any trailing `source(none)` etc. — via m[0]).
-		if (spec === "tailwindcss" || spec.startsWith("tailwindcss/")) {
-			result += m[0];
-			continue;
-		}
-		if (seen.has(spec)) continue; // cycle guard
-		seen.add(spec);
-		try {
-			const resolved = await resolveStylesheetRaw(spec, base, cwd);
-			result += await inlineCssImports(resolved.content, resolved.base, cwd, seen);
-		} catch {
-			result += m[0]; // unresolved — keep literal; CSS/Tailwind will surface it
-		}
-	}
-	result += css.slice(lastIdx);
-	return result;
-}
-
-async function bunResolveStylesheet(
-	id: string,
-	base: string,
-	cwd: string,
-): Promise<{ path: string; base: string; content: string }> {
-	const resolved = await resolveStylesheetRaw(id, base, cwd);
-	if (id === "tailwindcss" || id.startsWith("tailwindcss/")) return resolved;
-	const content = await inlineCssImports(resolved.content, resolved.base, cwd, new Set([resolved.path]));
-	return { ...resolved, content };
-}
-
-// The app owns its fonts via an explicit, CSP-allowlisted <link> in index.html
-// (Google Fonts — `style-src ... fonts.googleapis.com`, `font-src ...
-// fonts.gstatic.com`). Third-party package CSS MUST NOT inject its own remote
-// `@import url(http…)`: @puckeditor/core/dist/index.css opens with
-// `@import "https://rsms.me/inter/inter.css"`, an arbitrary CDN our CSP does
-// NOT allow. The Tailwind compile inlines that mid-output, where it was either
-// silently dropped (CSS spec: @import must precede all rules) OR — once hoisted —
-// blocked by CSP, leaving a console error on every page; either way the font
-// never loaded and the site fell back to a system font (scala-docs 2026-06-13).
-// So every remote @import is STRIPPED from the compiled bundle: a package can
-// never inject a CDN font/stylesheet, and the only font source is the app-owned
-// index.html link. Fixed once at the single CSS chokepoint; guarded by
-// `css-build-strips-remote-imports`.
-const REMOTE_IMPORT_RE =
-	/^[ \t]*@import\s+(?:url\(\s*)?["']https?:\/\/[^"')]+["']\s*\)?[^;]*;[ \t]*\n?/gm;
-
-export function stripRemoteImports(css: string): string {
-	return css.replace(REMOTE_IMPORT_RE, "");
-}
-
-
-async function buildTailwindCss(
-	cwd: string,
-	log: ReturnType<typeof getAppLogger>,
-): Promise<string | null> {
-	const entry = join(cwd, "src", "app.css");
-	const outDir = join(cwd, "dist", "client");
-	const tmpFile = join(outDir, `${STYLES_BASE}.css`);
-
-	if (!(await Bun.file(entry).exists())) {
-		log.warn(
-			`[build-client-assets] src/app.css not found at ${entry} — skipping CSS build`,
-		);
-		return null;
-	}
-
-	await mkdir(outDir, { recursive: true });
-
-	const cssSource = await readFile(entry, "utf-8");
-	const compiler = await compile(cssSource, {
-		base: cwd,
-		async loadStylesheet(id, base) {
-			return bunResolveStylesheet(id, base, cwd);
-		},
-		async loadModule(id, base) {
-			const r = await Bun.resolve(id, base);
-			const mod = await import(r);
-			return { path: r, base: dirname(r), module: mod.default ?? mod };
-		},
-	});
-
-	// Scan every resolved @source for candidate class names — WITHOUT this the
-	// build emits no content-driven utilities (the unstyled-editor bug above).
-	const candidates = await scanSourceCandidates(compiler.sources, log);
-	const cssOutput = stripRemoteImports(compiler.build(candidates));
-	log.info(
-		`[build-client-assets] tailwind: ${candidates.length} candidate(s) from ${compiler.sources.length} source(s)`,
-	);
-
-	await Bun.write(tmpFile, cssOutput);
-
-	const hash = await fileHash(tmpFile);
-	const hashedName = `${STYLES_BASE}-${hash}.css`;
-	const hashedPath = join(outDir, hashedName);
-	await rename(tmpFile, hashedPath);
-	removeStaleHashedFiles(outDir, STYLES_BASE, "css", hashedName);
-
-	log.info(`[build-client-assets] styles.css built → ${hashedName} (in-process Bun compile)`);
-	return `/assets/${hashedName}`;
-}
-
-// Content fingerprint of the client-bundle dependency CLOSURE — hashed by
-// CONTENT, never mtime (cache-key-hashes-source-inputs-only). Rebuild iff this
-// differs from the fingerprint stored in the existing manifest. Scoped to the
-// CLOSURE (not all of node_modules) so a @teamscala/* publish that is not in this
-// service's client bundle cannot trigger a rebuild — the publish→rebuild storm
-// is architecturally impossible (`no-uncontrolled-repetition-or-cascade`).
-//
-// Inputs (everything that can change the emitted bytes):
-//   src/entry-client.ts — the bundle entrypoint.
-//   src/page-manifest.ts — the generated block→component map the bundle is built
-//                       from; a codegen regen (block added/removed) changes it,
-//                       and the hydrate bundle MUST rebuild or new blocks render
-//                       empty → hydration mismatch.
-//   src/app.css        — the Tailwind entry.
-//   @teamscala/* JS closure (hashTeamgbjJsGraph) — the CONTENT of every @teamscala/*
-//                       module reachable from the client entrypoints. Content
-//                       (not version) so a mid-install stale bake (bun.lock
-//                       ahead of node_modules — the lock can name a new version
-//                       while the prior bytes are still on disk) is detected on
-//                       the next boot and self-heals (scala-agents 2026-07-12).
-//   @teamscala/* CSS closure (hashResolvedPackageStylesheets) — the CONTENT of
-//                       every package stylesheet app.css @imports (transitively).
-//   third-party closure-boundary versions (hashTeamgbgJsGraph) — the resolved
-//                       VERSION of each third-party package the client closure
-//                       imports (react, etc.). Third-party modules are not
-//                       content-walked (large; pinned by bun.lock + change only
-//                       on a version bump), but a version bump of a closure dep
-//                       MUST invalidate, so the installed package.json#version
-//                       is folded. This is the closure-scoped replacement for
-//                       hashing all of bun.lock: react bumping in the closure
-//                       still rebuilds, while a backend @teamscala/* publish
-//                       outside the closure does not.
-// NB: bun.lock is INTENTIONALLY NOT an input. It encodes every resolved
-//    @teamscala/* version (backend packages included), so it invalidates on every
-//    publish — the false-invalidation source that made every UI service rebuild
-//    on a backend publish. The closure inputs above are a strict improvement:
-//    they catch every change that affects THIS bundle AND nothing that doesn't.
-export async function computeInputFingerprint(cwd: string): Promise<string> {
-	// Keyed on each input's RELATIVE label + CONTENT only — never the absolute
-	// path (that would make the fingerprint cwd-dependent and defeat the skip
-	// across two checkouts of the same service). bun.lock is DELIBERATELY
-	// EXCLUDED — it encodes EVERY resolved @teamscala/* version, so folding it in
-	// invalidates on every publish including packages NOT in this service's
-	// client bundle (the publish→rebuild storm — `no-uncontrolled-repetition-
-	// or-cascade`). The closure content hashes below (hashTeamgbgJsGraph +
-	// hashResolvedPackageStylesheets) + the third-party closure-boundary
-	// versions cover every dependency change that ACTUALLY affects this bundle,
-	// so a non-closure publish changes nothing here → zero rebuild. Rebuild
-	// iff this fingerprint differs from the one stored in the manifest.
-	const sources: Array<[label: string, path: string]> = [
-		["src/entry-client.ts", join(cwd, "src", "entry-client.ts")],
-		["src/page-manifest.ts", join(cwd, "src", "page-manifest.ts")],
-		["src/app.css", join(cwd, "src", "app.css")],
-	];
-	const h = createHash("sha256");
-	for (const [label, path] of sources) {
-		// Missing input contributes a stable sentinel rather than throwing — a
-		// backend service has no app.css, and that absence is itself part of the
-		// fingerprint. `(await Bun.file().text())` is parenthesised so a missing
-		// file's sync TypeError is caught (bun-async-file-operations).
-		try {
-			h.update(label).update("\0").update(await Bun.file(path).text()).update("\0");
-		} catch {
-			h.update(label).update("\0<absent>\0");
-		}
-	}
-	// Fold the resolved CONTENT of every @teamscala/* stylesheet app.css @imports
-	// (client-asset-cache-key-embeds-package-content). bun.lock pins versions; the
-	// build reads bytes. When they diverge (boot built mid-install), the lock-only
-	// fingerprint false-matches and skips forever — hashing the bytes closes it.
-	await hashResolvedPackageStylesheets(cwd, h);
-	// Fold in the resolved CONTENT of every @teamscala/* JS/TS module reachable
-	// from the client entrypoints (hashTeamgbgJsGraph). bun.lock pins versions;
-	// the build reads BYTES — and a boot can build MID-INSTALL (the package-
-	// poller restarts the service after writing the new bun.lock but before
-	// node_modules extraction finishes), so Bun.build faithfully bakes the OLD
-	// @teamgbg JS while the lock-derived fingerprint is stored as "current".
-	// Every later restart then recomputes the same lock fingerprint → skip →
-	// STALE bundle served forever (scala-agents 2026-07-12: hydrate-4dad7478bd
-	// carried zero of portal-ui@2.4.41's markers across restarts). Bun.build
-	// itself is NOT caching — an isolated repro proves it reads fresh content
-	// across processes — so the fix is to make the fingerprint cover the actual
-	// @teamgbg JS bytes (the JS analogue of hashResolvedPackageStylesheets,
-	// which already closes this exact race for CSS). A stale bake then hashes
-	// differently from the freshly-installed bytes → rebuild → self-heals.
-	await hashTeamgbgJsGraph(cwd, h);
-	return h.digest("hex").slice(0, 16);
-}
+	FALLBACK_MANIFEST,
+	readManifest,
+	writeManifest,
+} from "./build-client-assets/manifest.ts";
+import { buildTailwindCss } from "./build-client-assets/styles-build.ts";
 
 export async function buildClientAssets(serviceSlug: string): Promise<void> {
 	const log = getAppLogger();