@ultimat3/cli 22.14.0 → 23.0.0

package/src/runtime-admin.ts

@@ -0,0 +1,141 @@
+// Mounting the app's generated admin. `defineAdmin()` declares it; this file is the whole of what
+// serves it — one catch-all under each admin's base path, in `x dev` and in the container alike,
+// through the same document pipeline every page uses. The CLI contributes the HTTP crossing and
+// nothing else: which screen a URL names, who may see it and what it renders are the admin's.
+
+import type { AdminApp, AdminRouteConfig } from '@ultimat3/admin';
+import type { Route, RouteMeta } from '@ultimat3/http';
+import { asCtx, html, redirect, routeNotFound } from '@ultimat3/http';
+import type { RouteEntry } from '@ultimat3/render';
+import { compilePattern } from '@ultimat3/render';
+import { renderSsr } from '@ultimat3/render/server';
+import type { DocumentOptions } from './document-options';
+import { routeDocument } from './runtime-render';
+
+/**
+ * `@ultimat3/admin`'s `ADMIN_MOUNTS`, read off the GLOBAL symbol registry rather than imported.
+ * Importing that package loads every screen and registers its stylesheets, so an app that declared
+ * no admin would carry one into its documents (axiom 6); asking the registry costs nothing. An app
+ * that DID declare one has already loaded the package, which is when `screens()` below imports it.
+ */
+const ADMIN_MOUNTS: symbol = Symbol.for('ultimate.admin.mounts');
+
+/** The file a mounted screen is attributed to — a package, because no app file declares it. */
+export const ADMIN_MOUNT_FILE = '@ultimat3/admin';
+
+const declared = (): ReadonlyMap<string, AdminApp> => {
+  const held = (globalThis as { [key: symbol]: unknown })[ADMIN_MOUNTS];
+  return held instanceof Map ? (held as ReadonlyMap<string, AdminApp>) : new Map();
+};
+
+export interface AdminMountOptions extends Pick<DocumentOptions, 'themeHead' | 'origin'> {
+  readonly buildId: string;
+}
+
+/**
+ * The route table's own entry shape, for a screen nobody registered there: the document builder
+ * reads a `RouteEntry`, and an admin screen is a route — `ssr`, gated, `hydrate: 'never'` — whose
+ * component is the body the screen just answered with.
+ */
+const entryFor = (route: AdminRouteConfig, body: unknown): RouteEntry => ({
+  file: ADMIN_MOUNT_FILE,
+  path: route.path,
+  // An admin screen is behind sign-in: it carries the `app/` surface's stylesheet, never `site/`'s.
+  surface: 'app',
+  config: route.config,
+  suspenseBoundaries: 0,
+  islands: [],
+  pattern: compilePattern(route.path),
+  component: () => body,
+});
+
+/**
+ * `auth: 'required'` is the pipeline's half — nobody anonymous reaches a screen, and a sign-in
+ * redirect is the app's own. `enforcedBy: 'handler'` is the other half: the screen holds the row a
+ * row-level rule reads, so deciding in the `authz` stage too would be a second authz system that
+ * knows strictly less and answers first.
+ */
+const metaFor = (base: string): RouteMeta => ({
+  name: `admin:${base}`,
+  auth: 'required',
+  policy: 'admin:read',
+  enforcedBy: 'handler',
+  render: 'ssr',
+  tags: ['admin'],
+});
+
+async function answer(
+  base: string,
+  method: 'GET' | 'POST',
+  options: AdminMountOptions,
+  request: Parameters<Route['handler']>[0],
+  context: Parameters<Route['handler']>[1],
+): Promise<Response> {
+  // Read per request, never captured: `x dev` re-evaluates the module that declares the admin
+  // when it changes, and the admin a request meets is the one the author just saved.
+  const app = declared().get(base);
+  // Dynamic, and only here: reached only when an admin is mounted, by which point the app has
+  // already loaded the package — and after `loadApp` installed the `.tsx` loader its screens need.
+  const { adminRouteMatch } = await import('@ultimat3/admin');
+  const matched = app === undefined ? null : adminRouteMatch(app, request.url.pathname);
+  if (app === undefined || matched === null) throw routeNotFound(method, request.url.pathname);
+
+  const form = method === 'POST' ? await request.bodyRaw() : null;
+  const response = await matched.route.respond({
+    ctx: await app.requestCtx(request.raw),
+    params: matched.params,
+    url: request.url.href,
+    method,
+    // A POST with no body is a form with no fields — a button-only form posts exactly that.
+    form: method === 'POST' ? (isRecord(form) ? form : {}) : null,
+  });
+  if (response.kind === 'redirect') {
+    // 303, always: the browser must GET the page it lands on, not re-POST the form at it.
+    const moved = redirect(response.location, 303);
+    moved.headers.set('cache-control', 'private, no-store');
+    return moved;
+  }
+
+  const entry = entryFor(matched.route, response.body);
+  const data = { url: request.url.href, params: matched.params };
+  const result = await renderSsr(
+    { entry, params: matched.params, url: request.url, ctx: asCtx(context) },
+    () =>
+      routeDocument(entry, data, {
+        ...(options.themeHead === undefined ? {} : { themeHead: options.themeHead }),
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+      }),
+    { buildId: options.buildId, status: response.status },
+  );
+  // `renderSsr` answers the string the render function returned; a stream is `stream`'s shape.
+  const document = typeof result.body === 'string' ? result.body : '';
+  return html(document, { status: result.status, headers: result.headers });
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const METHODS: readonly ('GET' | 'POST')[] = ['GET', 'POST'];
+
+/**
+ * Two paths per admin and two methods on each: the base path itself (the dashboard) and one
+ * catch-all under it. The admin's own table is matched INSIDE the handler, against the table as
+ * it is now — so a page added in a save is served without this list being rebuilt, and a URL the
+ * admin does not declare is the framework's ordinary 404.
+ *
+ * Empty for an app that declared no admin: nothing is mounted, and nothing is imported.
+ */
+export function adminMountRoutes(options: AdminMountOptions): readonly Route[] {
+  return [...declared().keys()].flatMap((base) =>
+    [base, `${base}/*rest`].flatMap((path) =>
+      METHODS.map(
+        (method): Route => ({
+          method,
+          path,
+          meta: metaFor(base),
+          handler: (request, context) => answer(base, method, options, request, context),
+        }),
+      ),
+    ),
+  );
+}

package/src/runtime-hooks.ts

@@ -1,8 +1,8 @@
-// The two seams `@ultimat3/http` leaves open, bound to the packages that own them. `authorize`
+// The seams `@ultimat3/http` leaves open, bound to the packages that own them. `authorize`
 // decides for pages only, from the SAME `Policy` object every other surface evaluates — the route
 // table's declared permission — so a denial in `x dev` is the one production produces.
 
-import { actorOf } from '@ultimat3/action';
+import { actorOf, explainActionPathMiss } from '@ultimat3/action';
 import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
 import { asCtx, configuredAuthenticator } from '@ultimat3/http';
 import type { KnownPermission, Policy } from '@ultimat3/policy';
@@ -57,6 +57,9 @@ export function devHooks(options: DevHookOptions = {}): ServerHooks {
     ...(authenticate === undefined ? {} : { authenticate }),
     ...(devNotices === undefined ? {} : { devNotices }),
     ...(errorPage === undefined ? {} : { errorPage }),
+    // Every web role, `x dev` and the container alike: a caller that derived an action's URL under
+    // the wrong `pathStyle` is told which one this app serves, not that no route exists.
+    explainMiss: explainActionPathMiss,
     authorize: (route, _request, ctx): AuthzDecision => {
       // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
       // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level

package/src/runtime-queue.ts

@@ -33,6 +33,7 @@ import {
   setJobsFacade,
 } from '@ultimat3/jobs';
 import { applyFrameworkSchema } from './framework-schema';
+import { appExtensions } from './migration-extensions';
 import type { DevServices } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { attachReplica, type ReplicaEnv, replicaUrlFor } from './runtime-replica';
@@ -93,7 +94,13 @@ export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
     binding.mode === 'embedded'
       ? // `pgliteDataDir` is `@ultimat3/db`'s own reader of the `pglite://` form; a second parser
         // here is a second thing to keep right when the form changes.
-        createPgliteClient({ dataDir: pgliteDataDir(binding.url) })
+        // Linked at boot, from the app's own migrations: PGlite cannot `create extension` one it
+        // was not handed, and the schema dump's scratch replay already asks this same reader — an
+        // app that replayed in the gate and failed in `x dev` was the two disagreeing.
+        createPgliteClient({
+          dataDir: pgliteDataDir(binding.url),
+          extensions: () => appExtensions(services.root),
+        })
       : createPostgresClient({ url: binding.url });
   const attached = attachReplica(client, replicaUrlFor(binding, env));
   setDbClient(attached.client);

package/src/runtime-render.ts

@@ -16,6 +16,7 @@
 
 // why: Bun ships no path API; an island's file is its route file's directory joined to its `src`.
 import { posix } from 'node:path';
+import { actionPathStyle } from '@ultimat3/action';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx } from '@ultimat3/core';
 import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
@@ -27,15 +28,10 @@ import type {
 } from '@ultimat3/http';
 import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
 import { currentLocale, localeConfig } from '@ultimat3/i18n';
-import type {
-  ClientSyncHead,
-  IslandCollector,
-  RenderResult,
-  RouteData,
-  RouteEntry,
-} from '@ultimat3/render';
+import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
 import {
   clientBootTags,
+  clientPathStyleTags,
   clientPersistTags,
   clientScopeTag,
   clientSyncTags,
@@ -65,6 +61,7 @@ import {
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import type { DocumentOptions } from './document-options';
 import { realtimeIslandFiles } from './island-realtime';
 import {
   type NavigationDocumentHead,
@@ -72,64 +69,21 @@ import {
   navigationTagsOf,
   principalRelocation,
 } from './page-navigation';
+import type { StaticResult } from './static-document';
+import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
 
-/**
- * Specifier → built chunk URL, bound to the route file the specifier is written relative to.
- * Supplied by whoever built the islands (`x dev`, the container, the static build); absent means
- * no island was built, and a page that renders one then fails by name rather than emitting a
- * `data-x-entry` nothing can import.
- */
-export type IslandResolver = (routeFile: string) => (src: string) => string;
-
-export interface DocumentOptions {
-  readonly resolveIsland?: IslandResolver;
-  /**
-   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
-   * from `pwa-artifacts.ts`, or absent when the app is not installable.
-   *
-   * A document-level string rather than something a route's `meta()` returns: it is the same three
-   * elements on every page of the app, an installable app is one whose EVERY page carries them
-   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
-   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
-   * boot knows it, the renderer cannot ask.
-   */
-  readonly pwaHead?: string | ((locale: string) => string);
-  /**
-   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
-   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
-   * decided by `app.config.ts`, which the boot read and the renderer cannot.
-   */
-  readonly themeHead?: string;
-  /**
-   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
-   * document this process serves. Principal-free, so a shareable document carries it too; absent
-   * for a caller that serves no socket at all (the static export).
-   */
-  readonly sync?: ClientSyncHead;
-  /**
-   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
-   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
-   * with no scope carries none.
-   */
-  readonly persisted?: () => readonly string[];
-  /**
-   * The public origin canonical, `og:url` and hreflang are absolute against — `publicOrigin()`
-   * from `site-config.ts`. Absent, the request's own origin: a relative canonical is one a crawler
-   * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
-   */
-  readonly origin?: string;
-  /**
-   * The client router — `pageNavigation(…).head`. A document of a surface listed in
-   * `navigation.client` names it; every other document carries none of it.
-   */
-  readonly navigation?: NavigationDocumentHead;
-}
+export type { DocumentOptions, IslandResolver } from './document-options';
 
 export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
   /** Injected so a test can drive the ISR store without a timer. */
   readonly isr?: IsrController;
+  /**
+   * Keep each `static` document after its first render (`static-document.ts`). The container sets
+   * it; `x dev` never does — a save changes the page, its stylesheet's URL and its islands'.
+   */
+  readonly memoStatic?: boolean;
 }
 
 /** What a route's `meta(data)` is given. `url` is a string because that is what `ld.*` embeds. */
@@ -162,6 +116,7 @@ const headFor = async (
 ): Promise<string> => {
   const meta = metaContextFor(ctx, data);
   const url = new URL(ctx.url);
+  const router = navigationTagsOf(options.navigation, entry);
   return (
     renderHead(
       headFromMeta(
@@ -177,7 +132,11 @@ const headFor = async (
         }),
         [
           ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
-          ...navigationTagsOf(options.navigation, entry),
+          // Every document, shareable ones included: the style is the app's, not a visitor's, and
+          // it is the only way an island's `rpc()` learns it. Read per render — `defineApi` may run
+          // after these routes are built. `'resource'`, the default, is no tag.
+          ...clientPathStyleTags(actionPathStyle()),
+          ...router,
           // The page boot rides the scope tag: its whole job — restoring a principal's persisted
           // records and replaying its queued writes — is per principal, and a shareable document
           // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
@@ -188,6 +147,8 @@ const headFor = async (
       ),
     ) +
     (options.themeHead ?? '') +
+    // One mechanism per document: the router prefetches for itself, the browser for the rest.
+    (router.length === 0 ? (options.speculationHead ?? '') : '') +
     // Per locale: each links its own locale's manifest (`PwaArtifacts.headFor`).
     (typeof options.pwaHead === 'function' ? options.pwaHead(meta.locale) : (options.pwaHead ?? ''))
   );
@@ -469,6 +430,7 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? createIsrController({ buildId: options.buildId });
+  const memo = createStaticMemo();
   return routeEntries().map((registered) => ({
     method: 'GET' as const,
     path: registered.path,
@@ -481,6 +443,13 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
       // A soft visit onto another principal's document is a real load — answered before `load`.
       const moved = principalRelocation(entry, request, asCtx(ctx), options.buildId);
       if (moved !== undefined) return moved;
+      // A static page already rendered by this process is answered without `load` or a render.
+      const key =
+        options.memoStatic === true
+          ? staticMemoKey(entry, request.url, asCtx(ctx).locale)
+          : undefined;
+      const kept = key === undefined ? undefined : memo.get(key);
+      if (kept !== undefined) return staticResponse(request, kept);
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
       // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
       // object, so a route's `load` runs exactly once however its mode splits head from body.
@@ -490,7 +459,14 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
       // 3xx because a rendered document has no `Location`; this is the path that has one.
       const to = takeRedirect(ctx);
       if (to !== undefined) return loadRedirect(entry, to);
-      return responseOf(await resultFor(entry, data, loaded, options, isr, asCtx(ctx)));
+      const result = await resultFor(entry, data, loaded, options, isr, asCtx(ctx));
+      if (entry.config.render !== 'static' || typeof result.body !== 'string') {
+        return responseOf(result);
+      }
+      const document: StaticResult = { ...result, body: result.body };
+      if (key !== undefined) memo.set(key, document);
+      // The ETag was only ever a header: a matching `If-None-Match` is a 304, not the page again.
+      return staticResponse(request, document);
     },
   }));
 }

package/src/runtime-services.ts

@@ -182,7 +182,8 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
           bucket,
           endpoint: binding.url,
           ...(env['S3_REGION'] === undefined ? {} : { region: env['S3_REGION'] }),
-          // MinIO needs path style; R2 and AWS do not. Declared, never sniffed from the endpoint.
+          // A gateway addressed by host and port needs path style; R2 and AWS do not. Declared,
+          // never sniffed from the endpoint.
           forcePathStyle: env['S3_FORCE_PATH_STYLE'] === '1',
         }),
       },

package/src/scaffold-typecheck.ts

@@ -151,6 +151,7 @@ const overlay = (root: string, app: string): string =>
           // name, and `cli/serve` as `packages/cli/serve`. Longest prefix wins, so these are
           // consulted first. `@ultimat3/cli/serve` is what `x new`'s `apps/web/server.ts` imports.
           '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
+          '@ultimat3/query/client': [`${root}/packages/query/src/client`],
           '@ultimat3/render/server': [`${root}/packages/render/src/server`],
           '@ultimat3/cli/serve': [`${root}/packages/cli/src/serve-entry`],
           '@ultimat3/testing/test-types': [`${root}/packages/testing/src/test-types`],

package/src/schema-dump-drift.ts

@@ -0,0 +1,64 @@
+// The `drift` step's fourth rail: is the committed schema dump what the migrations produce, and
+// does a database loaded from it come back the same? The other three rails read files and open
+// nothing; this one replays the migrations on a scratch embedded database, because "what the
+// migrations produce" is a fact only a database can state.
+
+// why: Bun has no directory probe — `Bun.file().exists()` answers about a file.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Migration } from '@ultimat3/db';
+import type { SchemaDumpDifference } from '@ultimat3/db/schema-dump';
+import { compareSchemaDump, schemaDumpDrift } from '@ultimat3/db/schema-dump';
+import {
+  hasSchemaDump,
+  type ReplayedSchema,
+  readSchemaDump,
+  replayFor,
+  SCHEMA_DUMP_DIR,
+} from './db-schema-dump';
+import { dumpNeverGenerated, replayFailure } from './db-schema-refresh';
+import { DB_PACKAGE } from './drift';
+import { readMigrations } from './migrations';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Injected so this module's rules are testable without booting a database per case. */
+export type SchemaReplay = (migrations: readonly Migration[]) => Promise<ReplayedSchema>;
+
+const findingFor = (difference: SchemaDumpDifference): Finding => ({
+  ...findingFrom(schemaDumpDrift(difference)),
+  docs: ERROR_DOCS_URL,
+  at: `${SCHEMA_DUMP_DIR}/${difference.path}`,
+});
+
+/**
+ * Empty result = the dump is the migrations' own.
+ *
+ * An app with no migration and no dump owes none — zero recorded against zero dumped is agreement,
+ * the rule `checkSourceDrift` states for entities, and what keeps `x new --no-example` green. From
+ * the first migration on the dump is owed: a missing directory is one finding naming the command
+ * that writes it, reported without booting a database.
+ *
+ * Both halves are reported together. A stale file and a dump that does not round-trip are two
+ * repairs, and hiding the second behind the first hands out `x db gen` for a dump regenerating
+ * cannot fix.
+ */
+export async function checkSchemaDump(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+  replay: SchemaReplay = replayFor(root, env, true),
+): Promise<readonly Finding[]> {
+  if (!existsSync(join(root, DB_PACKAGE))) return [];
+  const migrations = await readMigrations(root);
+  if (!hasSchemaDump(root)) return migrations.length === 0 ? [] : [dumpNeverGenerated()];
+  const committed = await readSchemaDump(root);
+  let replayed: ReplayedSchema;
+  try {
+    replayed = await replay(migrations);
+  } catch (error) {
+    return [replayFailure(error)];
+  }
+  return [...compareSchemaDump(committed, replayed.files), ...replayed.reload].map(findingFor);
+}