@teamscala/service-boot 0.23.412 → 0.23.413

package/src/build-client-assets/manifest.ts

@@ -0,0 +1,115 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The asset-manifest unit of the client-asset build: the AssetManifest shape,
+ * its read/write, the last-failure tombstone status read the runtime surfaces,
+ * and the first-boot fallback paths.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings — the file held six concerns (manifest, hashed output, hydrate
+ * bundle, source-map upload, stylesheet build, fingerprint, lock, orchestration).
+ *
+ * Byte-for-byte move from the parent — imports adjusted, nothing else.
+ */
+
+import { join } from "node:path";
+
+export const MANIFEST_FILE = "asset-manifest.json";
+
+export 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.
+export const FALLBACK_MANIFEST: { stylesPath: string; hydratePath: string } = {
+	stylesPath: "/assets/styles.css",
+	hydratePath: "/assets/hydrate.js",
+};
+
+/**
+ * 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 };
+}
+
+export 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;
+	}
+}
+
+export async function writeManifest(
+	outDir: string,
+	manifest: AssetManifest,
+): Promise<void> {
+	await Bun.write(
+		join(outDir, MANIFEST_FILE),
+		`${JSON.stringify(manifest, null, 2)}\n`,
+	);
+}

package/src/build-client-assets/sourcemaps-upload.ts

@@ -0,0 +1,101 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
+ * flow, then delete the .map files so source never ships publicly.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
+ * else.
+ */
+
+import { existsSync } from "node:fs";
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { userHome } from "@teamscala/os/host-paths";
+import { spawnSync } from "@teamscala/os/spawn";
+
+/**
+ * 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.
+ */
+export 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 {}
+		}
+	}
+}

package/src/build-client-assets/styles-build.ts

@@ -0,0 +1,179 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The Tailwind stylesheet unit of the client-asset build: Bun-native
+ * stylesheet resolution, recursive inlining of nested @imports (the
+ * 2026-07-05 dropped-leaf outage), stripping of remote (CSP-forbidden)
+ * @imports, and the content-hashed styles-<hash>.css build.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
+ * else.
+ */
+
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { compile } from "tailwindcss";
+import { fileHash, removeStaleHashedFiles } from "./hashed-output.ts";
+import { scanSourceCandidates } from "./source-candidates.ts";
+import { mkdir, rename } from "node:fs/promises";
+
+const STYLES_BASE = "styles";
+
+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, "");
+}
+
+
+export 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}`;
+}

package/src/build-client-assets.test.ts

@@ -15,10 +15,8 @@ import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, describe, expect, test } from "bun:test";
-import {
-	computeInputFingerprint,
-	stripRemoteImports,
-} from "./build-client-assets.ts";
+import { computeInputFingerprint } from "./build-client-assets/input-fingerprint.ts";
+import { stripRemoteImports } from "./build-client-assets/styles-build.ts";
 
 describe("stripRemoteImports", () => {
 	test("removes a remote @import (Puck's rsms.me font)", () => {