@ultimat3/cli 22.15.0 → 24.0.0

package/src/serve-drain.ts

@@ -1,41 +1,17 @@
-// `app.config.ts`'s `drain` and `health` sections, read for the production boot — the same import
-// every other config reader here makes (`theme-boot.ts`, `app-auth.ts`), because the config is a
-// module. Both shape what `/readyz` tells the load balancer.
+// `app.config.ts`'s `drain` and `health` sections for the production boot, off the one loader
+// (`app-config-load.ts`). Both shape what `/readyz` tells the load balancer.
 
 import type { DrainConfig, HealthConfig } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * The declared section, or `undefined` when the app has none (a config not built by
- * `defineConfig`, or no config file): `@ultimat3/http` then keeps core's own default. A value that
- * is not a number is left for core to refuse, where the rule lives, rather than dropped here.
- */
+/** The declared section, or `undefined` for a root with no config file — core keeps its default. */
 export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig> | undefined> {
-  const path = `${root}/${APP_CONFIG_FILE}`;
-  if (!(await Bun.file(path).exists())) return undefined;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const drain = isRecord(config) ? config['drain'] : undefined;
-  if (!isRecord(drain) || !Object.hasOwn(drain, 'readinessGraceMs')) return undefined;
-  return { readinessGraceMs: drain['readinessGraceMs'] as number };
+  const drain = (await loadAppConfig(root))?.drain;
+  return drain === undefined ? undefined : { readinessGraceMs: drain.readinessGraceMs };
 }
 
-/**
- * `health.readiness`, or `undefined` when the app declares none (core keeps `'dependencies'`). The
- * value is handed to `configureLifecycle` as written, so a bad one is refused by core's own rule.
- */
+/** `health.readiness`, or `undefined` for a root with no config file (core keeps its default). */
 export async function loadHealthConfig(root: string): Promise<Partial<HealthConfig> | undefined> {
-  const path = `${root}/${APP_CONFIG_FILE}`;
-  if (!(await Bun.file(path).exists())) return undefined;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const health = isRecord(config)
-    ? (config['health'] as Partial<HealthConfig> | undefined)
-    : undefined;
-  if (!isRecord(health) || health.readiness === undefined) return undefined;
-  return { readiness: health.readiness };
+  const health = (await loadAppConfig(root))?.health;
+  return health === undefined ? undefined : { readiness: health.readiness };
 }

package/src/serve-env.ts

@@ -42,22 +42,25 @@ export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
 /**
  * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
  * to `web` would start a process that serves nothing the operator asked for and reports healthy.
+ * Empty or blank is unset, read the way `PORT` and `HOST` are — not a role name nobody typed.
  */
 export function roleFromEnv(env: Env): Role {
-  const raw = env['ROLE'] ?? 'web';
-  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
-  return raw;
+  const raw = env['ROLE']?.trim();
+  const role = raw === undefined || raw.length === 0 ? 'web' : raw;
+  if (!isRole(role)) throw new RoleUnknownError({ role, known: ROLES });
+  return role;
 }
 
 /**
- * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
- * partially-parsed port is a deploy that binds somewhere nobody asked for.
+ * `Number.parseInt` would read `80abc` as 80, and `Number` reads `0x1F90` as 8080 and `8e3` as
+ * 8000, so the whole string has to be decimal digits — a port spelled any other way is a deploy
+ * that binds somewhere nobody wrote down.
  */
 function portValue(env: Env, name: string, fallback: number): number {
   const raw = env[name];
   if (raw === undefined || raw.trim().length === 0) return fallback;
   const port = Number(raw.trim());
-  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+  if (!/^\d+$/.test(raw.trim()) || !Number.isInteger(port) || port < 0 || port > 65_535)
     throw new PortInvalidError({ value: raw, name });
   return port;
 }

package/src/serve-prebuilt-paths.ts

@@ -0,0 +1,19 @@
+// Where the image's prebuilt store lives and the one command that writes it. A leaf with no
+// import, so the Dockerfile template, the build command and the container boot all spell them
+// from here without loading each other.
+
+/**
+ * App-root-relative. NOT under `.x/`: that is the state directory, which the scaffolded compose
+ * topology mounts a tmpfs over and every ignore file drops, so a store written there never reached
+ * a running container. Under `node_modules` because that is the one directory every tool already
+ * leaves alone — git, the linter, every source walker and the image context — and the one the
+ * image build has just written, so it is in a layer and readable under a read-only root.
+ */
+export const PREBUILT_DIR = 'node_modules/.cache/ultimate';
+
+export const PREBUILT_ISLANDS_DIR = `${PREBUILT_DIR}/islands`;
+
+export const PREBUILT_SASS_DIR = `${PREBUILT_DIR}/sass`;
+
+/** The Dockerfile line that writes the store — one spelling, for the template and every `fix:`. */
+export const PREBUILT_COMMAND = 'bun node_modules/@ultimat3/cli/src/bin.ts build --target prebuilt';

package/src/serve-prebuilt.ts

@@ -0,0 +1,84 @@
+// The image's prebuilt store, as a container sees it: where `x build --target prebuilt` wrote the
+// island chunks and the compiled stylesheets during `docker build`, and the one log line a role
+// owes when it had to build either at boot instead. A leaf of the boot graph — the half that
+// WRITES the store (`image-prepare.ts`) carries the island builder and is never loaded here.
+
+// why: the store is adopted before the first app module is imported, and that import path is
+// synchronous end to end (`compileStylesheet` runs inside Bun's `onLoad`); Bun has no sync exists.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import type { Role } from '@ultimat3/core';
+import { logger, UltimateError } from '@ultimat3/core';
+import { sassCompilations, setSassCacheDir } from '@ultimat3/render/server';
+import { PREBUILT_COMMAND, PREBUILT_SASS_DIR } from './serve-prebuilt-paths';
+
+/**
+ * Points the Sass cache at the image's own entries, when the image has any. Before the app is
+ * imported, because importing a page IS compiling its stylesheet. An entry is keyed by the
+ * sheet's absolute path, which is why the store is written inside the image build: same `WORKDIR`,
+ * same paths. Answers whether there was a store to adopt.
+ */
+export function adoptPrebuiltStyles(root: string): boolean {
+  const dir = join(root, PREBUILT_SASS_DIR);
+  if (!existsSync(dir)) return false;
+  setSassCacheDir(dir);
+  return true;
+}
+
+/** What a role built at boot that the image build exists to have built once. */
+export interface BootBuilds {
+  /** Island chunks built by this boot, and the one sentence saying why the store was not served. */
+  readonly islands?: { readonly chunks: number; readonly reason: string };
+  /** Stylesheets this boot ran Sass for. */
+  readonly stylesheets: number;
+  readonly elapsedMs: number;
+}
+
+/**
+ * Logged, never thrown: a build at boot is correct and only slow, so the role serves what it
+ * would have served — it pays seconds of CPU and a compiler's worth of memory on every start.
+ */
+export class ImageNotPrebuiltError extends UltimateError {
+  constructor(input: { readonly role: Role } & BootBuilds) {
+    const islands = input.islands;
+    const built = [
+      ...(islands === undefined
+        ? []
+        : [`built ${String(islands.chunks)} island chunk(s) because ${islands.reason}`]),
+      ...(input.stylesheets === 0
+        ? []
+        : [`compiled ${String(input.stylesheets)} stylesheet(s) the image holds no result for`]),
+    ];
+    super({
+      code: 'X_IMAGE_NOT_PREBUILT',
+      cause: `the ${input.role} role ${built.join(' and ')}, ${String(input.elapsedMs)} ms into its boot — work this image repeats on every start of every replica`,
+      fix: `edit docker/Dockerfile: add RUN ${PREBUILT_COMMAND} after COPY . . in the runtime stage, then rebuild the image`,
+      meta: {
+        role: input.role,
+        islands: islands?.chunks ?? 0,
+        stylesheets: input.stylesheets,
+        elapsedMs: input.elapsedMs,
+      },
+    });
+  }
+}
+
+/** Starts counting what a boot compiles; the answer is what `reportBootBuilds` is handed. */
+export function watchBootBuilds(): (islands?: BootBuilds['islands']) => BootBuilds {
+  const started = Bun.nanoseconds();
+  const compiled = sassCompilations();
+  return (islands) => ({
+    ...(islands === undefined || islands.chunks === 0 ? {} : { islands }),
+    stylesheets: sassCompilations() - compiled,
+    elapsedMs: Math.round((Bun.nanoseconds() - started) / 1e6),
+  });
+}
+
+/** One `error` line when the boot built anything, and nothing when it built nothing. */
+export function reportBootBuilds(role: Role, builds: BootBuilds): boolean {
+  if (builds.islands === undefined && builds.stylesheets === 0) return false;
+  const error = new ImageNotPrebuiltError({ role, ...builds });
+  logger.error(error.format(), { code: error.code, ...error.meta });
+  return true;
+}

package/src/serve-web.ts

@@ -0,0 +1,169 @@
+// What only the web role serves: its islands, its documents and every route beside them. A file
+// of its own so the roles that render nothing never import it — `serve-boot.ts` loads it with
+// `await import()` for `ROLE=web` alone, and `serve-graph.test.ts` pins what every other role is
+// spared: render's server half, the PWA, SEO, MCP and island subsystems.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
+import { mountAppMcp } from './app-mcp';
+import { errorPageStyleSources } from './error-page-csp';
+import { islandRoutes } from './island-routes';
+import type { LoadedIslands } from './island-store';
+import { loadOrBuildIslands } from './island-store';
+import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { adminMountRoutes } from './runtime-admin';
+import { assetRoutes } from './runtime-assets';
+import { attachedIsr } from './runtime-isr';
+import { appRoutes } from './runtime-render';
+import type { RunningServices } from './runtime-services';
+import { servedStorage, storageRoutes } from './runtime-storage';
+import { seoRoutes } from './seo-routes';
+import type { ServeOptions } from './serve-types';
+import { loadSiteSettings, publicOrigin } from './site-config';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+/** Everything `startRoles` is handed that only a process serving documents has. */
+export interface WebSurface {
+  readonly routes: readonly Route[];
+  /** The theme boot and the speculation rules: the two inline bodies every document may carry. */
+  readonly inlineScripts: readonly string[];
+  /** The app's own error pages' `<style>` bodies, which the enforced policy must admit. */
+  readonly inlineStyles: readonly string[];
+  /** Where a browser that opened a guarded page is sent — the declaration `x dev` reads. */
+  readonly signInPath: string | null;
+  /** Present when this boot built the islands itself: how many chunks, and why not the store. */
+  readonly islandsBuilt?: LoadedIslands['built'];
+  /** Detaches the ISR controller from `invalidateTags` — on the boot's stop list. */
+  readonly release: () => void;
+}
+
+export async function webSurface(
+  options: ServeOptions,
+  runtime: RunningServices,
+  buildId: string,
+): Promise<WebSurface> {
+  // Read from the store the image build wrote and VERIFIED against this app and this runtime
+  // (`island-store.ts`); built here only when there is no store to trust, which is correct and
+  // slower — the reason travels back to the boot, which reports it.
+  const { bundle: islands, built: islandsBuilt } = await loadOrBuildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
+  // prevent, and it is the one an operator cannot see without installing the app.
+  const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
+  const site = await loadSiteSettings(options.root);
+  const origin = publicOrigin(options.env, site);
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
+  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The browser's own prefetch, for the documents that carry no router (`navigation.speculation`).
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
+  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
+  // route added here cannot be missing from the precache manifest.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+          scripts: [
+            ...sync.scripts,
+            ...(navigation.script === undefined ? [] : [navigation.script]),
+          ],
+        });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
+  // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
+  const served = servedStorage(runtime.storage);
+  // Attached, so a tag bust marks this process's ISR pages stale. The store is the deployment's
+  // when it supplied one: the default is per process, so twelve replicas hold twelve of them and a
+  // purge regenerates one twelfth of the fleet while the other eleven keep the invalidated page.
+  const isr = attachedIsr({
+    buildId,
+    ...(options.runtime?.isrStore === undefined ? {} : { store: options.runtime.isrStore }),
+  });
+  const routes: readonly Route[] = [
+    ...apiRoutes(),
+    // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
+    // on the store this boot's limiter uses, so one token's allowance is one number fleet-wide.
+    ...apiMountRoutes(options.runtime?.rateLimitStore ?? runtime.rateLimitStore),
+    ...mcpMount.routes,
+    // The app's own plain routes (`apps/<app>/runtime.ts` `routes`), before any page can shadow one.
+    ...(options.runtime?.routes ?? []),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...assetRoutes({
+      root: options.root,
+      storage: served,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: served }),
+    ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
+    // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
+    ...seoRoutes({ env: options.env, site, root: options.root }),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
+    ...navigation.routes,
+    // A page's `POST`, bound to an action (`defineRoute({ post })`) — beside the page's `GET`.
+    ...pagePostRoutes(),
+    // The app's generated admin, when it declared one (`defineAdmin`): every screen under its base
+    // path, served through the same document builder as the pages below. Nothing for an app with
+    // no admin — the registry is asked, the package is not imported.
+    ...adminMountRoutes({
+      buildId: buildId,
+      themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
+    }),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      ...(sync.head === undefined ? {} : { sync: sync.head }),
+      persisted: sync.persisted,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
+      themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
+      // A `static` page is the same bytes for every request of this process: rendered once.
+      memoStatic: true,
+      ...(origin === undefined ? {} : { origin }),
+      ...(pwa === undefined
+        ? {}
+        : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
+      isr: isr.isr,
+    }),
+  ];
+  return {
+    routes,
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: await errorPageStyleSources(options.root),
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
+    ...(islandsBuilt === undefined ? {} : { islandsBuilt }),
+    release: isr.release,
+  };
+}

package/src/serve.ts

@@ -13,8 +13,6 @@ import { startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
 import { startQueue } from './runtime-queue';
-import { startServices } from './runtime-services';
-import { bootRoles } from './serve-boot';
 import { containerBinding, metricsPortFor, portFromEnv, roleFromEnv } from './serve-env';
 import type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types';
 
@@ -144,17 +142,16 @@ export async function serveApp(input: ServeOptions): Promise<ServedApp> {
   const metrics = startMetricsEndpoint({
     port: metricsPortFor(options.env, port, options.metricsPort),
     hostname: containerBinding(options.env, options.hostname).hostname,
+    role,
   });
   // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
   const acquired: (() => void | Promise<void>)[] = [() => metrics.stop()];
   try {
-    const runtime = await startServices(
-      resolveServices(options.root, options.env),
-      options.env,
-      options.runtime,
-    );
-    acquired.push(() => runtime.stop());
-    return await bootRoles({ options, role, runtime, acquired, metrics });
+    // Behind `await import()`: `ROLE=migrate` runs in this module too, applies SQL files and
+    // exits, and the services and the role boot are ~240 modules it never calls
+    // (`serve-graph.test.ts` pins the count each role is left with).
+    const { bootServing } = await import('./serve-boot');
+    return await bootServing({ options, role, acquired, metrics });
   } catch (error) {
     await releaseBoot(acquired);
     throw error;

package/src/server-barrels.ts

@@ -0,0 +1,54 @@
+// A package barrel a browser must not import, and the entry it imports instead. `@ultimat3/entity`'s
+// barrel reaches the SQL renderer and `@ultimat3/db` — about a megabyte in an island — while
+// `@ultimat3/entity/record` is the browser half. DERIVED from each manifest's `exports`: a package
+// that publishes a `./record`, `./browser` or `./client` subpath has said its barrel is the server
+// half, so a new browser entry enters this rule by being published, never by being listed here.
+
+import { stripComments } from '@ultimat3/core';
+import { lineIndex } from './ts-scan';
+
+/** The subpath names that declare "this is the browser entry of the package". */
+export const BROWSER_ENTRY_SUBPATHS: ReadonlySet<string> = new Set(['record', 'browser', 'client']);
+
+/** Barrel specifier → the browser entry that replaces it, read off the published specifiers. */
+export function serverBarrels(specifiers: Iterable<string>): ReadonlyMap<string, string> {
+  const barrels = new Map<string, string>();
+  for (const spec of specifiers) {
+    const match = /^(@[\w-]+\/[\w-]+)\/([\w-]+)$/.exec(spec);
+    if (match?.[1] === undefined || !BROWSER_ENTRY_SUBPATHS.has(match[2] ?? '')) continue;
+    barrels.set(match[1], spec);
+  }
+  return barrels;
+}
+
+export interface BarrelImport {
+  readonly line: number;
+  readonly barrel: string;
+  readonly entry: string;
+}
+
+/** `import` / `export … from` / `import()` of a VALUE from the barrel. `import type` runs nothing. */
+const IMPORTS =
+  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)/g;
+
+export function barrelImports(
+  source: string,
+  barrels: ReadonlyMap<string, string>,
+): readonly BarrelImport[] {
+  // Most files import no barrel at all; say so before paying for a comment-stripped copy.
+  if (![...barrels.keys()].some((barrel) => source.includes(barrel))) return [];
+  const code = stripComments(source);
+  const lineAt = lineIndex(code);
+  const found: BarrelImport[] = [];
+  for (const match of code.matchAll(IMPORTS)) {
+    const spec = match[2] ?? match[4] ?? '';
+    const entry = barrels.get(spec);
+    if (entry === undefined) continue;
+    // `import { type A, type B } from …` binds nothing at runtime either.
+    const clause = /\{([^}]*)\}/.exec(match[0])?.[1];
+    const typesOnly = clause?.split(',').every((part) => /^\s*(?:type\s|$)/.test(part));
+    if (typesOnly === true) continue;
+    found.push({ line: lineAt(match.index), barrel: spec, entry });
+  }
+  return found;
+}

package/src/shot-locale.ts

@@ -3,9 +3,7 @@
 // on the language of the machine's Chrome. A non-default locale is also a URL prefix (`/en/…`),
 // because on a `site/` route the unprefixed path is always the default locale whatever the header.
 
-import { join } from 'node:path'; // why: Bun ships no path join.
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { BadFlagError } from './errors';
 
 export interface ShotLocales {
@@ -16,27 +14,11 @@ export interface ShotLocales {
 /** An app that declares nothing is `en` only — the framework's own default. */
 export const FALLBACK_SHOT_LOCALES: ShotLocales = { locales: ['en'], defaultLocale: 'en' };
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/** `app.config.ts`'s `locales` and `defaultLocale`, read the way `loadThemeMode` reads `theme`. */
+/** `app.config.ts`'s `locales` and `defaultLocale`, off the one loader (`app-config-load.ts`). */
 export async function loadShotLocales(root: string): Promise<ShotLocales> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return FALLBACK_SHOT_LOCALES;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return FALLBACK_SHOT_LOCALES;
-  const declared = config['locales'];
-  const locales = Array.isArray(declared)
-    ? declared.filter((locale): locale is string => typeof locale === 'string')
-    : [];
-  const fallback = config['defaultLocale'];
-  const defaultLocale =
-    typeof fallback === 'string' && fallback !== '' ? fallback : (locales[0] ?? 'en');
-  return {
-    locales: locales.length === 0 ? [defaultLocale] : locales,
-    defaultLocale,
-  };
+  const config = await loadAppConfig(root);
+  if (config === undefined) return FALLBACK_SHOT_LOCALES;
+  return { locales: config.locales, defaultLocale: config.defaultLocale };
 }
 
 /** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */

package/src/site-assets.ts

@@ -9,6 +9,7 @@ import { copyFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path'; // why: Bun ships no path API.
 import type { AssetExtension, AssetPath } from '@ultimat3/render';
 import { ASSET_DIR, AssetMissingError, assetPathProblem } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 
 /** App-root-relative, beside `favicon.ico`: `apps/web/site/` is where an app's public files live. */
 export const SITE_ASSETS_SOURCE = `apps/web/site/${ASSET_DIR}`;
@@ -37,7 +38,7 @@ export interface SiteAsset {
   readonly path: AssetPath;
   /** Absolute path on disk. */
   readonly file: string;
-  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  /** `@ultimat3/render`'s `contentHash` of the bytes, 8 hex characters — the one CSS and HTML get. */
   readonly hash: string;
   /** `/assets/brand/logo.<hash>.svg`. */
   readonly url: string;
@@ -69,9 +70,6 @@ export function parseHashedAssetUrl(
   return { path: path as AssetPath, hash: match[2] ?? '' };
 }
 
-const hashBytes = (bytes: Uint8Array): string =>
-  Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0');
-
 export interface SiteAssetTable {
   /** The asset `asset()` named, hashed as the bytes are NOW. Throws `X_ASSET_MISSING`. */
   resolve(path: AssetPath): SiteAsset;
@@ -110,7 +108,7 @@ export function createSiteAssetTable(root: string): SiteAssetTable {
     const cached = cache.get(path);
     if (cached !== undefined && cached.stamp === stamp) return cached.asset;
     const bytes = readFileSync(file);
-    const hash = hashBytes(bytes);
+    const hash = contentHash(bytes);
     // `assetPathProblem` already refused an unknown extension; the guard keeps `constructor` from
     // ever answering an `Object` member if that check is loosened.
     const extension = splitExtension(path).extension.toLowerCase();

package/src/site-config.ts

@@ -1,14 +1,10 @@
 // The public origin and the crawler rules out of `app.config.ts` — `site.origin` and
 // `seo.robots.disallow` — and the one resolution of "which origin is this site served on" every
-// absolute URL a document, a sitemap or a robots file carries is built against. Sibling of
-// `app-auth.ts`'s `loadSignInPath`, and it imports the config for the same reason.
+// absolute URL a document, a sitemap or a robots file carries is built against. Read off the one
+// loader (`app-config-load.ts`).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
-import { join } from 'node:path';
-import type { AppConfig, Environment, SeoSitemapConfig, SitemapLastmod } from '@ultimat3/core';
-import { SITEMAP_LASTMOD_SOURCES } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { Environment, SeoSitemapConfig } from '@ultimat3/core';
+import { loadAppConfig } from './app-config-load';
 
 export interface SiteSettings {
   /** `site.origin`, trailing slash removed; `null` when the app declares none. */
@@ -25,51 +21,16 @@ export const NO_SITE_SETTINGS: SiteSettings = {
   sitemap: { extra: [], lastmod: 'none' },
 };
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * Structural, never `instanceof`, for `loadSignInPath`'s reason: a config that resolved through an
- * older core simply has no `site` section, and that is the "not declared" answer, not a crash.
- */
-const hasSiteSections = (value: unknown): value is Pick<AppConfig, 'site' | 'seo'> =>
-  isRecord(value) &&
-  isRecord(value['site']) &&
-  isRecord(value['seo']) &&
-  isRecord(value['seo']['robots']);
-
 const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
 
 export async function loadSiteSettings(root: string): Promise<SiteSettings> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return NO_SITE_SETTINGS;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!hasSiteSections(config)) return NO_SITE_SETTINGS;
-  const origin = config.site.origin;
+  const config = await loadAppConfig(root);
+  if (config === undefined) return NO_SITE_SETTINGS;
+  const { origin } = config.site;
   return {
-    origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
+    origin: origin === null ? null : trimSlash(origin),
     disallow: [...config.seo.robots.disallow],
-    sitemap: sitemapOf(config.seo),
-  };
-}
-
-/**
- * Structural for `hasSiteSections`' reason: a config resolved through a core older than
- * `seo.sitemap` has no such key, and that is the default, not a crash.
- */
-function sitemapOf(seo: unknown): SeoSitemapConfig {
-  const declared = isRecord(seo) ? seo['sitemap'] : undefined;
-  if (!isRecord(declared)) return NO_SITE_SETTINGS.sitemap;
-  const extra = declared['extra'];
-  const lastmod = declared['lastmod'];
-  return {
-    extra: Array.isArray(extra)
-      ? extra.filter((path): path is string => typeof path === 'string')
-      : [],
-    lastmod: SITEMAP_LASTMOD_SOURCES.includes(lastmod as SitemapLastmod)
-      ? (lastmod as SitemapLastmod)
-      : 'none',
+    sitemap: config.seo.sitemap,
   };
 }
 

package/src/site-seo.ts

@@ -173,7 +173,7 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
             localizedPath(path, locale, defaultLocale),
         }),
   });
-  // Past 50,000 URLs `files` are `/sitemap-N.xml` and the index is `/sitemap.xml`; below it,
+  // Past 50,000 URLs `files` are `/sitemaps/<n>.xml` and the index is `/sitemap.xml`; below it,
   // `files` is that one file and there is no index.
   const sitemaps = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
   const robots = buildRobots({

package/src/sitemap-lastmod.ts

@@ -14,6 +14,9 @@ let builtAt: string | undefined;
 
 const cache = new Map<string, string | undefined>();
 
+/** One `git log -1` over one path; a synchronous wait past this blocks the request serving it. */
+const GIT_DATE_TIMEOUT_MS = 5_000;
+
 /**
  * The `<lastmod>` for one route file, W3C Datetime (ISO 8601, UTC), or `undefined` when the source
  * yields none — a sitemap entry without `<lastmod>` is valid, a wrong one misleads a crawler.
@@ -46,6 +49,8 @@ function gitDate(file: string, root: string): string | undefined {
       cwd: root,
       stdout: 'pipe',
       stderr: 'ignore',
+      // A wedged `git` (a lock, a credential prompt) answers no date: the mtime fallback below.
+      timeout: GIT_DATE_TIMEOUT_MS,
     });
     if (run.exitCode !== 0) return undefined;
     return isoOf(run.stdout.toString().trim());