@teamscala/service-boot 0.23.440 → 0.23.441

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.440",
+  "version": "0.23.441",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/read-html-template.test.ts

@@ -73,4 +73,24 @@ describe("readHtmlTemplate manifest-keyed cache", () => {
 		expect(html).toContain("/assets/hydrate.js");
 		expect(html).toContain("/assets/styles.css");
 	});
+
+	// The fallback is correct as a LAST RESORT and dangerous as a SILENT one:
+	// the unhashed names it emits were never built, so the page 200s while its
+	// stylesheet 404s. Measured 2026-09-01 — a client-facing proposal served
+	// unstyled while the deploy reported SUCCESS, because nothing anywhere in
+	// the stack distinguished "client build never ran" from "client build fine".
+	// The stamp is what makes the two distinguishable to an operator, a probe,
+	// or a deploy gate, so it is asserted rather than left to inspection.
+	test("stamps the page when no manifest was built, so a dead deploy is visible", async () => {
+		const html = await readHtmlTemplate();
+		expect(html).toContain('name="x-client-build-status"');
+		expect(html).toContain('content="missing-manifest"');
+	});
+
+	test("does not stamp missing-manifest once a real manifest exists", async () => {
+		await writeManifest("/assets/hydrate-abc.js", "/assets/styles-abc.css");
+		const html = await readHtmlTemplate();
+		expect(html).toContain("/assets/hydrate-abc.js");
+		expect(html).not.toContain('content="missing-manifest"');
+	});
 });

package/src/read-html-template.ts

@@ -40,6 +40,7 @@
  */
 
 import { createCache } from "@teamscala/cache/create-cache";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { readClientBuildStatus } from "./build-client-assets/manifest.ts";
 import { join } from "node:path";
 
@@ -93,7 +94,7 @@ async function manifestMtimeMs(): Promise<number> {
 	}
 }
 
-async function loadManifest(): Promise<AssetManifest> {
+async function loadManifest(): Promise<AssetManifest | null> {
 	const path = manifestPath();
 	if (await Bun.file(path).exists()) {
 		try {
@@ -101,10 +102,21 @@ async function loadManifest(): Promise<AssetManifest> {
 			if (parsed.stylesPath && parsed.hydratePath) {
 				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 			}
-		} catch (error) {}
-			getAppLogger().warn("asset manifest unreadable — falling back to default template wiring", error);
+			getAppLogger().warn(
+				`[read-html-template] asset manifest at ${path} is missing stylesPath/hydratePath — serving unbuilt fallback URLs`,
+			);
+		} catch (error) {
+			getAppLogger().warn(
+				`[read-html-template] asset manifest at ${path} is unreadable — serving unbuilt fallback URLs`,
+				error,
+			);
+		}
+		return null;
 	}
-	return FALLBACK;
+	getAppLogger().warn(
+		`[read-html-template] no asset manifest at ${path} — the client build did not run for this deployment; serving unbuilt fallback URLs that will 404`,
+	);
+	return null;
 }
 
 export async function readHtmlTemplate(): Promise<string> {
@@ -113,8 +125,24 @@ export async function readHtmlTemplate(): Promise<string> {
 	if (cached && cached.manifestMtime === manifestMtime) return cached.html;
 	const manifest = await loadManifest();
 	let html = PAGE_DOCUMENT
-		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
-		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath);
+		.replace(/\{\{stylesPath\}\}/g, (manifest ?? FALLBACK).stylesPath)
+		.replace(/\{\{hydratePath\}\}/g, (manifest ?? FALLBACK).hydratePath);
+	// An ABSENT manifest is a failed client build wearing a working service's
+	// clothes: boot succeeds, SSR renders, every response is 200, and the only
+	// symptom is a stylesheet URL that was never built. Measured 2026-09-01 —
+	// proposals.scala.business served a client-facing proposal unstyled while
+	// Railway reported the deploy SUCCESS, because the fallback silently
+	// substitutes unhashed names for assets no build produced. The tombstone
+	// below already exists for a build that FAILED loudly; a build that never
+	// ran must be equally visible, or a broken deployment is indistinguishable
+	// from a working one at every layer that reports on it
+	// (`a-component-may-not-report-a-state-it-has-not-verified`).
+	if (!manifest) {
+		const meta = `<meta name="x-client-build-status" content="missing-manifest" data-reason="no dist/client/asset-manifest.json; asset URLs below are unbuilt and will 404">`;
+		html = html.includes("</head>")
+			? html.replace("</head>", `${meta}</head>`)
+			: `${meta}${html}`;
+	}
 	// Tombstone stamp — surfaces a failed client build at the served layer.
 	// `<meta>` in <head> is the minimum-invasive vehicle (no layout shift, no
 	// JS dependency, visible via view-source / devtools / a future status