@ultimat3/cli 21.0.0 → 22.1.0

package/src/serve-boot.ts

@@ -0,0 +1,192 @@
+// The web and background roles' boot, after the services are up: the app loaded, its route table
+// built, the roles started. Split from `serve.ts` (the entry points) at its line ceiling; the rules
+// that file's header states — the SAME boot `x dev` runs, minus the watcher, `/_x` and `dev: true`
+// — are this file's.
+
+import type { Role } from '@ultimat3/core';
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
+import { apiRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
+import { errorPageStyleSources } from './error-page-csp';
+import { islandRoutes } from './island-routes';
+import { loadOrBuildIslands } from './island-store';
+import type { MetricsEndpoint } from './metrics-endpoint';
+import { startOtlpExport } from './otlp-export';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { startRoles } from './role-start';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import { replicaOverrides } from './runtime-replica';
+import type { RunningServices } from './runtime-services';
+import { storageRoutes } from './runtime-storage';
+import { loadDrainConfig } from './serve-drain';
+import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
+import type { ServedApp, ServeOptions } from './serve-types';
+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';
+
+/** The half of `serveApp` whose every acquisition is registered for rollback. */
+export async function bootRoles(boot: {
+  readonly options: ServeOptions;
+  readonly role: Role;
+  readonly runtime: RunningServices;
+  readonly acquired: (() => void | Promise<void>)[];
+  /** The scrape listener `serveApp` opened before any of this work; `startRoles` adopts it. */
+  readonly metrics: MetricsEndpoint;
+}): Promise<ServedApp> {
+  const { options, role, runtime, acquired, metrics } = boot;
+  // Importing the app's modules IS the registration: every route, action and job below is
+  // whatever this call put in the registries.
+  await loadApp(options.root);
+  // The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
+  // answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only
+  // when unstamped, because a stamped image already paid for it at build time and a replica's boot
+  // should not repeat it — the load above is the part every boot needs either way.
+  const stamped = options.env['BUILD_ID'];
+  const buildId =
+    stamped !== undefined && stamped.length > 0
+      ? stamped
+      : (await appManifest(options.root)).manifest.buildId;
+  // Before the first socket opens: everything above this line fails loudly into the container's
+  // own logs, everything below it is a served request, a claimed job or a routed frame.
+  configureReporting(options.env, buildId);
+  // Beside error reporting, and for the same reason it is here: `OTEL_EXPORTER_OTLP_ENDPOINT` is
+  // in the shipped chart and nothing read it, so every deployment that configured a collector got
+  // an empty dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink
+  // with a different lifetime — so this is the production boot's alone (axiom 6).
+  const stopOtlp = startOtlpExport(options.env);
+  acquired.push(stopOtlp);
+  // Only the web role serves pages, so only it builds islands and assembles a route table: a
+  // worker, scheduler, sync or replicator pod compiled every island of the app on every boot for
+  // nothing it would ever serve (plan 101, slice 12 e).
+  const web = role === 'web' ? await webSurface(options, runtime, buildId) : undefined;
+  const port = options.port ?? portFromEnv(options.env);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
+  // still wins — that is the deploy talking.
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
+  const drain = await loadDrainConfig(options.root);
+  const replicaOverride = replicaOverrides(options.runtime, runtime.services.db, options.env);
+  const running = await startRoles({
+    roles: [role],
+    port,
+    metricsPort,
+    metrics,
+    buildId,
+    runtime,
+    routes: web?.routes ?? [],
+    env: options.env,
+    // 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),
+    // 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: web === undefined ? [] : await errorPageStyleSources(options.root),
+    inlineScripts: web === undefined ? [] : [web.themeCsp],
+    // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
+    // process and `x dev` cannot answer a browser differently.
+    root: options.root,
+    http: containerBinding(options.env, options.hostname),
+    // `app.config.ts`'s drain section: the readiness grace the chart's grace period is sized for.
+    ...(drain === undefined ? {} : { drain }),
+    // The read-replica scope rides in FRONT of whatever the host supplied, or the host's own value
+    // passes through untouched. `DATABASE_REPLICA_URL` was read by no booted process before this:
+    // `defaultClient()` is the one composer of a replicated pair and it runs only when an app
+    // installed no client, which no framework boot leaves true (`runtime-queue.ts`).
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
+  });
+  acquired.push(() => running.stop());
+  return {
+    kind: 'served',
+    role,
+    url: running.url,
+    buildId,
+    running,
+    runtime,
+    async stop() {
+      await running.stop();
+      await runtime.stop();
+      // Last: the exporters outlive the roles they were recording, so the drain's own spans and
+      // the final counter snapshot still have somewhere to go.
+      stopOtlp();
+    },
+  };
+}
+
+/** What only the web role serves: its islands, its documents and every route beside them. */
+async function webSurface(
+  options: ServeOptions,
+  runtime: RunningServices,
+  buildId: string,
+): Promise<{ readonly routes: readonly Route[]; readonly themeCsp: string }> {
+  // Read from the store `x build --target docker` 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, and logged with its reason.
+  const islands = 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));
+  // 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);
+  // 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,
+        });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
+  const routes: readonly Route[] = [
+    ...apiRoutes(),
+    ...mcpMount.routes,
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...assetRoutes({
+      root: options.root,
+      storage: runtime.storage,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: runtime.storage }),
+    ...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()),
+    // 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,
+      persisted: sync.persisted,
+      themeHead: theme.head,
+      ...(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
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
+  ];
+  return { routes, themeCsp: theme.cspSource };
+}

package/src/serve-drain.ts

@@ -0,0 +1,24 @@
+// `app.config.ts`'s `drain` section, 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.
+
+import type { DrainConfig } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+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.
+ */
+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 };
+}

package/src/serve-entry.ts

@@ -0,0 +1,6 @@
+// `@ultimat3/cli/serve`: what a container's `apps/web/server.ts` imports, and nothing else. The
+// `@ultimat3/cli` barrel is 1,349 modules — every command, every template, the e2e driver — and a
+// production process that booted through it loaded all of them to call one function.
+
+export { runRole } from './serve';
+export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types';

package/src/serve-env.ts

@@ -0,0 +1,116 @@
+// What a container's environment decides about a boot: which role, which port, which interface,
+// and where errors are reported. Split from `serve.ts`, which re-exports every name here.
+
+import type { Role } from '@ultimat3/core';
+import { configureErrorReporting, isRole, ROLES, sentryErrorReporter } from '@ultimat3/core';
+import { PortInvalidError, RoleUnknownError } from './errors';
+import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
+import type { WebBinding } from './role-start';
+import type { Env } from './runtime-bindings';
+
+export const DEFAULT_PORT = 3000;
+
+/**
+ * Every interface, which is what a role binds when nothing says otherwise: a container bound to
+ * loopback is unreachable through its own port mapping. `HOST` and `ServeOptions.hostname` are the
+ * two ways of saying otherwise — see `hostnameFromEnv`.
+ */
+export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
+
+/**
+ * The interface the `web` and `sync` roles bind, and the metrics endpoint with them (`WebBinding`
+ * is one decision). Read the way `PORT` is: empty or whitespace is the default.
+ *
+ * Exists because a container had exactly one binding, `0.0.0.0`, and an app whose auth mode is
+ * "nobody logs in, one implicit actor" must refuse a public interface — so it could not run in a
+ * container at all. `HOST=127.0.0.1` is unreachable through `docker run -p` (the proxy connects to
+ * the container's bridge address, never its loopback); it is reachable where the container shares
+ * the host's network namespace (`--network host`), or through a sidecar and `ssh -L` inside it —
+ * which is the exposure such an app wants. Not `HOSTNAME`: Docker sets that to the container id.
+ */
+export function hostnameFromEnv(env: Env): string {
+  const raw = env['HOST']?.trim();
+  return raw === undefined || raw.length === 0 ? CONTAINER_BINDING.hostname : raw;
+}
+
+/** What `serveApp` hands `startRoles`: the caller's hostname, else `HOST`, else every interface. */
+export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
+  dev: false,
+  hostname: hostname ?? hostnameFromEnv(env),
+});
+
+/**
+ * `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.
+ */
+export function roleFromEnv(env: Env): Role {
+  const raw = env['ROLE'] ?? 'web';
+  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
+  return raw;
+}
+
+/**
+ * `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.
+ */
+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)
+    throw new PortInvalidError({ value: raw, name });
+  return port;
+}
+
+/** Every PaaS injects `PORT` and routes traffic to exactly it. */
+export function portFromEnv(env: Env): number {
+  return portValue(env, 'PORT', DEFAULT_PORT);
+}
+
+/**
+ * The scrape port, deliberately its own env var and not `PORT + n`: an operator who moves the app
+ * port must not silently move the port their Prometheus is configured against, and the roles that
+ * set no `PORT` at all — `worker`, `scheduler`, `replicator` — still need this one.
+ */
+export function metricsPortFromEnv(env: Env): number {
+  return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
+}
+
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `role-start.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
+/**
+ * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
+ * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
+ * wire format behind it is documented and self-hostable, and `SENTRY_DSN` is what every monitor
+ * that speaks it already documents — inventing a second spelling would mean an operator's existing
+ * tooling sets a variable this framework ignores. Exactly the precedent
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` already sets in `docker/helm/values.yaml`.
+ */
+export const ERROR_DSN_KEY = 'SENTRY_DSN';
+
+/**
+ * Switch reporting on for this process. Unset DSN leaves core's no-op reporter in place, so a
+ * laptop and a CI run pay nothing and page nobody — and the release every event carries is the
+ * build id this boot already computed, never a second identity for the same deploy.
+ */
+export function configureReporting(env: Env, buildId: string): void {
+  const dsn = env[ERROR_DSN_KEY]?.trim();
+  configureErrorReporting({
+    release: buildId,
+    // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
+    // never connected looks exactly like an app that never failed.
+    ...(dsn === undefined || dsn.length === 0 ? {} : { reporter: sentryErrorReporter({ dsn }) }),
+  });
+}

package/src/serve-types.ts

@@ -0,0 +1,55 @@
+// The shapes a production boot takes and answers. Split from `serve.ts`, which re-exports them.
+
+import type { Role } from '@ultimat3/core';
+import type { DriftReport, MigrationReport } from '@ultimat3/db';
+import type { RunningRoles } from './role-start';
+import type { Env } from './runtime-bindings';
+import type { RuntimeOverrides } from './runtime-overrides';
+import type { RunningServices } from './runtime-services';
+
+export interface ServeOptions {
+  readonly root: string;
+  readonly env: Env;
+  /** Overrides `ROLE`; `runRole` reads the environment when this is absent. */
+  readonly role?: Role;
+  /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
+  readonly port?: number;
+  /** Overrides `METRICS_PORT`, on the same terms. */
+  readonly metricsPort?: number;
+  /**
+   * Overrides `HOST`: the interface the HTTP roles bind. An app that must never answer on a public
+   * interface passes `'127.0.0.1'` here rather than trusting the deployment to set the variable.
+   */
+  readonly hostname?: string;
+  /**
+   * The drivers this deployment supplies instead of the ones the environment would select.
+   *
+   * This field is why `apps/web/server.ts` can stay three lines and still run a custom queue, a
+   * shared ISR store or an app's own middleware. Before it there was nowhere to hand the framework
+   * a driver, so the only way was an ambient setter from an app module — which `loadApp` imports
+   * AFTER `startServices` has captured its own, giving a process that enqueues to one queue and
+   * claims from another. `startRoles` now refuses that split outright.
+   */
+  readonly runtime?: RuntimeOverrides;
+}
+
+export interface ServedApp {
+  readonly kind: 'served';
+  readonly role: Role;
+  /** `http://…` for the web role; null for the roles that open no HTTP socket. */
+  readonly url: string | null;
+  readonly buildId: string;
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  stop(): Promise<void>;
+}
+
+export interface MigratedApp {
+  readonly kind: 'migrated';
+  readonly role: 'migrate';
+  readonly report: MigrationReport;
+  /** The post-condition: the live schema against the ledger this run just wrote. */
+  readonly drift: DriftReport;
+}
+
+export type StartedApp = ServedApp | MigratedApp;