@ultimat3/cli 22.2.1 → 22.3.0

package/src/seo-routes.ts

@@ -0,0 +1,69 @@
+// `GET /robots.txt` and `GET /sitemap.xml` from a running web role — the files the static export
+// writes, answered by the process for a deploy that serves its pages from a container. Mounted by
+// `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
+
+import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
+import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
+
+export interface SeoRoutesOptions {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** `site.origin` and `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). */
+  readonly site?: SiteSettings;
+}
+
+/**
+ * The public origin — `publicOrigin()`: `APP_URL`, `SITE_ORIGIN`, then `site.origin` — else the
+ * request's own. A container behind an ingress sees its pod address as the request's host, which
+ * is why the declared origin comes first — a sitemap of `http://10.0.0.7:3000/…` indexes nothing.
+ */
+function originOf(options: SeoRoutesOptions, request: UltimateRequest): string {
+  return publicOrigin(options.env, options.site ?? NO_SITE_SETTINGS) ?? new URL(request.url).origin;
+}
+
+/**
+ * Per request, never cached across one: `prerender()` may enumerate rows that change, and a
+ * crawler asks for these a handful of times a day. An hour of shared cache is what a CDN keeps.
+ */
+const SEO_CACHE = { mode: 'public', maxAgeSeconds: 3600 } as const;
+
+export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
+  const environment: Environment =
+    tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
+  const answer = async (request: UltimateRequest) =>
+    await siteSeo({
+      baseUrl: originOf(options, request),
+      environment,
+      disallow: options.site?.disallow ?? [],
+    });
+
+  return [
+    {
+      method: 'GET',
+      path: ROBOTS_PATH,
+      meta: { name: 'seo.robots', auth: 'public', tags: ['seo'] },
+      handler: async (request: UltimateRequest): Promise<Response> =>
+        applyCacheHeaders(
+          new Response((await answer(request)).robots, {
+            headers: { 'content-type': 'text/plain; charset=utf-8' },
+          }),
+          SEO_CACHE,
+        ),
+    },
+    {
+      method: 'GET',
+      path: SITEMAP_PATH,
+      meta: { name: 'seo.sitemap', auth: 'public', tags: ['seo'] },
+      // The first file is `/sitemap.xml` in both shapes: the whole urlset, or the index of parts.
+      handler: async (request: UltimateRequest): Promise<Response> =>
+        applyCacheHeaders(
+          new Response((await answer(request)).sitemaps[0]?.xml ?? '', {
+            headers: { 'content-type': 'application/xml; charset=utf-8' },
+          }),
+          SEO_CACHE,
+        ),
+    },
+  ];
+}

package/src/serve-boot.ts

@@ -25,9 +25,11 @@ import { appRoutes } from './runtime-render';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
 import { servedStorage, storageRoutes } from './runtime-storage';
+import { seoRoutes } from './seo-routes';
 import { loadDrainConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import type { ServedApp, 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';
@@ -137,9 +139,12 @@ async function webSurface(
   // 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);
+  const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
   // 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.
@@ -173,14 +178,17 @@ async function webSurface(
     // 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 }),
     // The page's one socket: its worker script, served beside the islands for their reason.
     ...sync.routes,
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
-      sync: sync.head,
+      ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
       themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of

package/src/shot-locale.ts

@@ -0,0 +1,67 @@
+// Which locale a picture is of. `x shot` pins `Accept-Language` on every capture — to `--locale`
+// when one is asked for and to the app's DEFAULT locale otherwise — so a screenshot never depends
+// 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 { BadFlagError } from './errors';
+
+export interface ShotLocales {
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+}
+
+/** 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`. */
+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,
+  };
+}
+
+/** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */
+export function readLocaleFlag(value: string | undefined, app: ShotLocales): string | undefined {
+  if (value === undefined) return undefined;
+  if (app.locales.includes(value)) return value;
+  throw new BadFlagError({
+    flag: 'locale',
+    command: 'shot',
+    reason: `"${value}" is not one of the app's locales (${app.locales.join(', ')})`,
+    fix: `x shot / --locale ${app.defaultLocale} --json`,
+  });
+}
+
+/**
+ * The path a visitor in `locale` opens: unchanged for the default locale, `/<locale>/…` for any
+ * other. The root keeps its trailing slash (`/en/`), which is the directory a static export writes
+ * the prefixed home page to.
+ */
+export function localizedShotPath(route: string, locale: string, defaultLocale: string): string {
+  if (locale === defaultLocale) return route;
+  return route === '/' ? `/${locale}/` : `/${locale}${route}`;
+}
+
+/** The header every capture sends. One key, lower-case, as CDP forwards it verbatim. */
+export const acceptLanguageHeaders = (locale: string): Readonly<Record<string, string>> => ({
+  'accept-language': locale,
+});

package/src/site-asset-routes.ts

@@ -0,0 +1,106 @@
+// Serving `apps/web/site/assets/**` at the hashed URLs `asset()` mints. Mounted by `assetRoutes`,
+// which both `x dev` and the container compose, so a picture that paints on a laptop paints in the
+// image. Byte ranges are answered because Safari will not play an `<video>` from a server that
+// ignores `Range`, and a film that plays everywhere but an iPhone is not a film that ships.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { SiteAsset, SiteAssetTable } from './site-assets';
+import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
+
+/** The URL is the content, so the answer is `public, max-age=31536000, immutable`. */
+export const SITE_ASSET_CACHE: CacheHint = { mode: 'immutable' };
+
+const notFound = (code: string, cause: string, fix: string): Response =>
+  json({ ok: false, error: { code, cause, fix } }, { status: 404 });
+
+/** One `bytes=` range, resolved against the file's size; `null` when it cannot be satisfied. */
+export function byteRange(
+  header: string | null,
+  size: number,
+): { readonly start: number; readonly end: number } | null | undefined {
+  if (header === null) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  // A multi-range or a unit we do not speak: RFC 9110 lets a server ignore Range and send it all.
+  if (match === null) return undefined;
+  const [, from = '', to = ''] = match;
+  if (from === '' && to === '') return null;
+  if (from === '') {
+    const suffix = Number(to);
+    if (suffix === 0) return null;
+    return { start: Math.max(0, size - suffix), end: size - 1 };
+  }
+  const start = Number(from);
+  const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);
+  if (start >= size || end < start) return null;
+  return { start, end };
+}
+
+function assetResponse(asset: SiteAsset, range: string | null): Response {
+  const file = Bun.file(asset.file);
+  const headers: Record<string, string> = {
+    'content-type': asset.contentType,
+    'accept-ranges': 'bytes',
+  };
+  const wanted = byteRange(range, asset.bytes);
+  if (wanted === null) {
+    return new Response(null, {
+      status: 416,
+      headers: { ...headers, 'content-range': `bytes */${String(asset.bytes)}` },
+    });
+  }
+  if (wanted === undefined) {
+    return applyCacheHeaders(new Response(file, { headers }), SITE_ASSET_CACHE);
+  }
+  return applyCacheHeaders(
+    new Response(file.slice(wanted.start, wanted.end + 1), {
+      status: 206,
+      headers: {
+        ...headers,
+        'content-range': `bytes ${String(wanted.start)}-${String(wanted.end)}/${String(asset.bytes)}`,
+      },
+    }),
+    SITE_ASSET_CACHE,
+  );
+}
+
+/**
+ * Only the HASHED name is served, and only while the bytes still hash to it: an immutable answer
+ * under a URL whose bytes changed would be cached for a year by every CDN that saw it. A stale
+ * hash is a document from an earlier build, and says so.
+ */
+export function siteAssetRoutes(table: SiteAssetTable): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${SITE_ASSET_BASE_PATH}/*file`,
+      meta: { name: 'assets.site', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const named = parseHashedAssetUrl(request.pathname);
+        if (named === undefined) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${request.pathname} is not a hashed site asset URL`,
+            "name the file with asset('assets/…') in the page, which returns the URL this route serves",
+          );
+        }
+        let asset: SiteAsset;
+        try {
+          asset = table.resolve(named.path);
+        } catch (error) {
+          if (!isUltimateError(error)) throw error;
+          return notFound(error.code, error.cause, error.fix);
+        }
+        if (asset.hash !== named.hash) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${named.path} is at ${asset.url} now — the document asking for ${request.pathname} was rendered against earlier bytes`,
+            'reload the page; it names the current URL',
+          );
+        }
+        return assetResponse(asset, request.headers.get('range'));
+      },
+    },
+  ];
+}

package/src/site-assets.ts

@@ -0,0 +1,177 @@
+// The site asset table: every file under `apps/web/site/assets/`, named by a content-hashed URL.
+// One table per app root answers all three questions — the URL `asset()` returns while a page
+// renders, the file `/assets/*` serves, and the copy `x build --target static` writes — so the
+// page, the container and the CDN can never name one file three ways.
+
+// why: `asset()` is called from a synchronous render, so the table answers synchronously — and Bun
+// ships no sync stat or sync read; `join`/`relative` because Bun ships no path API either.
+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';
+
+/** 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}`;
+
+/** The URL prefix every hashed asset is served under, and the export directory it is copied to. */
+export const SITE_ASSET_BASE_PATH = `/${ASSET_DIR}`;
+
+/** What each served extension IS. `vtt` carries a charset: captions are text a player decodes. */
+export const ASSET_CONTENT_TYPES: Readonly<Record<AssetExtension, string>> = {
+  avif: 'image/avif',
+  webp: 'image/webp',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  woff2: 'font/woff2',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  vtt: 'text/vtt; charset=utf-8',
+};
+
+export interface SiteAsset {
+  /** As `asset()` names it: `assets/brand/logo.svg`. */
+  readonly path: AssetPath;
+  /** Absolute path on disk. */
+  readonly file: string;
+  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  readonly hash: string;
+  /** `/assets/brand/logo.<hash>.svg`. */
+  readonly url: string;
+  readonly contentType: string;
+  readonly bytes: number;
+}
+
+const splitExtension = (path: string): { readonly stem: string; readonly extension: string } => {
+  const dot = path.lastIndexOf('.');
+  return { stem: path.slice(0, dot), extension: path.slice(dot + 1) };
+};
+
+/** The hash goes before the extension, so a static host still infers the type from the name. */
+export function hashedAssetUrl(path: AssetPath, hash: string): string {
+  const { stem, extension } = splitExtension(path);
+  return `/${stem}.${hash}.${extension}`;
+}
+
+const HASHED = /^\/(assets\/.+)\.([0-9a-f]{8})\.([a-z0-9]+)$/i;
+
+/** The inverse of `hashedAssetUrl`: which asset a request names, and at which content. */
+export function parseHashedAssetUrl(
+  pathname: string,
+): { readonly path: AssetPath; readonly hash: string } | undefined {
+  const match = HASHED.exec(pathname);
+  if (match === null) return undefined;
+  const path = `${match[1] ?? ''}.${match[3] ?? ''}`;
+  if (assetPathProblem(path) !== undefined) return undefined;
+  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;
+  /** Every servable file under the source directory, sorted by path. */
+  all(): readonly SiteAsset[];
+}
+
+const missing = (path: string, cause: string): AssetMissingError =>
+  new AssetMissingError(
+    `asset(${JSON.stringify(path)}): ${cause}`,
+    `add the file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}, or correct the path passed to asset(), then x build --target static --json`,
+  );
+
+/**
+ * A stat per call, a read only when the file changed: `x dev` sees an edited image under a new URL
+ * on the next render with no watcher, and the container — whose files never change — pays one
+ * `stat` per `asset()` call and nothing else. One behaviour in both, never a dev-only rescan.
+ */
+export function createSiteAssetTable(root: string): SiteAssetTable {
+  const source = join(root, SITE_ASSETS_SOURCE);
+  const cache = new Map<string, { readonly stamp: string; readonly asset: SiteAsset }>();
+
+  const resolve = (path: AssetPath): SiteAsset => {
+    const problem = assetPathProblem(path);
+    if (problem !== undefined) throw missing(path, problem);
+    const file = join(source, path.slice(ASSET_DIR.length + 1));
+    let stamp: string;
+    try {
+      const stat = statSync(file);
+      if (!stat.isFile()) throw missing(path, `${file} is not a file`);
+      stamp = `${String(stat.mtimeMs)}:${String(stat.size)}`;
+    } catch (error) {
+      if (error instanceof AssetMissingError) throw error;
+      throw missing(path, `no file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}`);
+    }
+    const cached = cache.get(path);
+    if (cached !== undefined && cached.stamp === stamp) return cached.asset;
+    const bytes = readFileSync(file);
+    const hash = hashBytes(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();
+    const asset: SiteAsset = {
+      path,
+      file,
+      hash,
+      url: hashedAssetUrl(path, hash),
+      contentType: Object.hasOwn(ASSET_CONTENT_TYPES, extension)
+        ? ASSET_CONTENT_TYPES[extension as AssetExtension]
+        : 'application/octet-stream',
+      bytes: bytes.byteLength,
+    };
+    cache.set(path, { stamp, asset });
+    return asset;
+  };
+
+  const all = (): readonly SiteAsset[] => {
+    const found: SiteAsset[] = [];
+    let files: string[];
+    try {
+      files = [...new Bun.Glob('**/*').scanSync({ cwd: source, onlyFiles: true })];
+    } catch {
+      // No `assets/` directory is an app with no assets, not an error.
+      return [];
+    }
+    for (const relativePath of files.sort()) {
+      const path = `${ASSET_DIR}/${relativePath.split('\\').join('/')}`;
+      // A source file beside its renditions (a `.psd`, a `README.md`) is not a served asset.
+      if (assetPathProblem(path) !== undefined) continue;
+      found.push(resolve(path as AssetPath));
+    }
+    return found;
+  };
+
+  return { resolve, all };
+}
+
+/** One table per root, so the renderer and the route read the same cache. */
+const tables = new Map<string, SiteAssetTable>();
+
+export function siteAssetTable(root: string): SiteAssetTable {
+  let table = tables.get(root);
+  if (table === undefined) {
+    table = createSiteAssetTable(root);
+    tables.set(root, table);
+  }
+  return table;
+}
+
+/**
+ * Every asset, copied into the static export under its hashed URL — a static host serves with no
+ * process behind it, so the artifact carries every byte a document names. Returns the URLs written.
+ */
+export function writeSiteAssets(root: string, out: string): readonly string[] {
+  const written: string[] = [];
+  for (const asset of siteAssetTable(root).all()) {
+    const target = join(out, asset.url.slice(1));
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(asset.file, target);
+    written.push(asset.url);
+  }
+  return written;
+}

package/src/site-config.ts

@@ -0,0 +1,79 @@
+// 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.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, Environment } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+export interface SiteSettings {
+  /** `site.origin`, trailing slash removed; `null` when the app declares none. */
+  readonly origin: string | null;
+  /** `seo.robots.disallow` — the paths a production `robots.txt` keeps crawlers out of. */
+  readonly disallow: readonly string[];
+}
+
+export const NO_SITE_SETTINGS: SiteSettings = { origin: null, disallow: [] };
+
+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;
+  return {
+    origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
+    disallow: [...config.seo.robots.disallow],
+  };
+}
+
+/**
+ * The declared public origin: `APP_URL` (what the runtime already names it — OAuth's redirect, the
+ * sync node's admitted origin), then `SITE_ORIGIN` (the static build's), then `site.origin`.
+ * The environment first because one image is deployed to staging and production under two
+ * origins; the config line is what a deploy that sets neither falls back to. `undefined` when
+ * nothing names one — the caller decides whether the request's own origin will do.
+ */
+export function publicOrigin(
+  env: Readonly<Record<string, string | undefined>>,
+  site: SiteSettings,
+): string | undefined {
+  for (const key of ['APP_URL', 'SITE_ORIGIN']) {
+    const declared = env[key]?.trim() ?? '';
+    if (declared !== '') return trimSlash(declared);
+  }
+  return site.origin ?? undefined;
+}
+
+/**
+ * The sentence a production build prints when no origin was declared. Every canonical, `og:url`,
+ * hreflang and sitemap `<loc>` is then built against a placeholder, and a search engine indexes a
+ * page whose canonical names a host the site is not on. A warning, not a refusal: a production
+ * build on a laptop is how a deploy is rehearsed.
+ */
+export function originWarning(environment: Environment, declared: string | undefined): string[] {
+  if (environment !== 'production' || declared !== undefined) return [];
+  return [
+    'no public origin: set APP_URL (or SITE_ORIGIN) or `site: { origin }` in app.config.ts — ' +
+      'canonical, og:url, hreflang and the sitemap are absolute against a placeholder',
+  ];
+}

package/src/site-seo.ts

@@ -0,0 +1,107 @@
+// `robots.txt` and `sitemap.xml`, off the route table: ONE answer for the static export
+// (`apps/web/prerender.ts` writes it into the artifact) and the running web role (`seo-routes.ts`
+// serves it), so a crawler reads the same two files from a CDN and from a container.
+
+import type { Environment } from '@ultimat3/core';
+import { localeConfig, localizedPath, routedLocales, unlocalizedPath } from '@ultimat3/i18n';
+import type { RouteEntry } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
+import type { RouteRecord, SitemapFile } from '@ultimat3/seo';
+import { buildRobots, buildSitemap, isDynamic } from '@ultimat3/seo';
+import { readSiteMeta } from './seo-meta';
+
+export const ROBOTS_PATH = '/robots.txt';
+export const SITEMAP_PATH = '/sitemap.xml';
+
+export interface SiteSeoOptions {
+  /** The public origin every `<loc>` and the `Sitemap:` line are absolute against. */
+  readonly baseUrl: string;
+  /** Omitted: `ULTIMATE_ENV`, read by `@ultimat3/seo` — anything but `production` disallows. */
+  readonly environment?: Environment | undefined;
+  /**
+   * The concrete pages a build EMITTED for a dynamic route. The static export passes its report's,
+   * so the sitemap cannot name a page the artifact lacks; absent, `prerender()` is asked — which is
+   * the same list, enumerated by the same function the prerenderer calls.
+   */
+  readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
+  /**
+   * `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). Added to the production
+   * `User-agent: *` group; a non-production `robots.txt` still disallows everything.
+   */
+  readonly disallow?: readonly string[] | undefined;
+}
+
+export interface SiteSeo {
+  readonly robots: string;
+  /** Every sitemap file: `/sitemap.xml` alone, or the index at that path first and its parts after. */
+  readonly sitemaps: readonly SitemapFile[];
+}
+
+/** A `site/` page anyone may fetch. A policy on a `site/` route makes it not public, whatever the surface. */
+const isPublicSite = (entry: RouteEntry): boolean =>
+  entry.surface === 'site' && entry.config.policy === undefined;
+
+/**
+ * A dynamic route's pages, UNPREFIXED and once each. A static export's report lists every locale's
+ * copy (`/blog/a` and `/en/blog/a`), and the sitemap localizes each page itself — reading the
+ * prefixed copies back as pages of their own listed `/en/en/blog/a`.
+ */
+const pagesOf = async (entry: RouteEntry, options: SiteSeoOptions): Promise<readonly string[]> => {
+  if (options.pagesFor !== undefined) {
+    return [...new Set(options.pagesFor(entry.path).map((path) => unlocalizedPath(path)))];
+  }
+  const params = await enumeratePrerender(entry);
+  return params.map((set) => fillPath(entry.pattern.source, set));
+};
+
+/**
+ * The public `site/` routes as `@ultimat3/seo` reads them. `meta` is carried where it resolves
+ * without a request (`readSiteMeta`), which is what lets a page's own `robots: { index: false }`
+ * keep it out of the sitemap — a page that asks crawlers to stay away must not be listed for them.
+ */
+async function publicSiteRoutes(options: SiteSeoOptions): Promise<readonly RouteRecord[]> {
+  const metaByPath = new Map((await readSiteMeta()).records.map((r) => [r.path, r.meta]));
+  return routeEntries()
+    .filter(isPublicSite)
+    .map((entry) => {
+      const meta = metaByPath.get(entry.path);
+      return {
+        path: entry.path,
+        file: entry.file,
+        surface: 'site' as const,
+        render: entry.config.render,
+        ...(meta === undefined ? {} : { meta }),
+        ...(isDynamic(entry.path) ? { prerender: () => pagesOf(entry, options) } : {}),
+      };
+    });
+}
+
+export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
+  // Every routed locale, with `xhtml:link` alternates: one `<url>` per page per locale, each
+  // naming the whole cluster and `x-default`. A single-locale app passes none and gets the plain
+  // urlset it always had — an alternates cluster of one is noise.
+  const locales = routedLocales();
+  const defaultLocale = localeConfig().fallback;
+  const sitemap = await buildSitemap(await publicSiteRoutes(options), {
+    baseUrl: options.baseUrl,
+    ...(locales.length < 2
+      ? {}
+      : {
+          locales,
+          defaultLocale,
+          localizePath: (path: string, locale: string) =>
+            localizedPath(path, locale, defaultLocale),
+        }),
+  });
+  // Past 50,000 URLs `files` are `/sitemap-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({
+    baseUrl: options.baseUrl,
+    sitemaps: [SITEMAP_PATH],
+    ...(options.disallow === undefined ? {} : { disallow: options.disallow }),
+    ...(options.environment === undefined ? {} : { environment: options.environment }),
+  });
+  return { robots, sitemaps };
+}