@ultimat3/cli 1.2.0 → 3.0.0

package/src/dev-queue.ts

@@ -1,19 +1,40 @@
 // The database and the job queue, started together and released together. Split from
 // `dev-runtime.ts` because `x jobs` needs exactly this pair and nothing else — and because a
-// process that installs two ambient accessors (`db()`, `jobDriver()`) must have one place that
-// takes both back, or the next command in the same process inherits a driver over a closed socket.
+// process that installs ambient accessors (`db()`, `jobDriver()`, the jobs facade, the event bus)
+// must have one place that takes them all back, or the next command in the same process inherits
+// a driver over a closed socket.
 
-import type { PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
+import {
+  postgresIdempotencyStore,
+  resetIdempotency,
+  SQL_IDEMPOTENCY_TABLE,
+  setIdempotencyStore,
+} from '@ultimat3/action';
+import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
   createPgliteClient,
   createPostgresClient,
+  currentTx,
   pgliteDataDir,
   raw,
   setDbClient,
 } from '@ultimat3/db';
-import type { JobDriver, PgExecutor } from '@ultimat3/jobs';
-import { createPgDriver, resetJobDriver, SQL_JOBS_TABLE, setJobDriver } from '@ultimat3/jobs';
+import type { Tx } from '@ultimat3/entity';
+import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
+import {
+  createJobsFacade,
+  createPgDriver,
+  createPgEventBus,
+  createPgOutboxStore,
+  resetJobDriver,
+  resetJobsFacade,
+  SQL_JOBS_TABLE,
+  setEventBus,
+  setJobDriver,
+  setJobsFacade,
+} from '@ultimat3/jobs';
 import type { DevServices } from './dev-services';
+import type { RuntimeOverrides } from './runtime-overrides';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
@@ -21,6 +42,13 @@ export type DevDbClient = PgliteClient | PostgresClient;
 export interface RunningQueue {
   readonly db: DevDbClient;
   readonly jobs: JobDriver;
+  /**
+   * The `x_outbox` store this boot installed behind `handle.enqueue()`. Returned because the
+   * relay that drains it is a ROLE's decision, not the queue's — `dev-roles.ts` starts one.
+   */
+  readonly outbox: OutboxStore;
+  /** The `x_job_events` bus a `step.waitForEvent` resumes from. Durable, not per-process. */
+  readonly events: EventBus;
   stop(): Promise<void>;
 }
 
@@ -43,38 +71,94 @@ function startDb(services: DevServices): DevDbClient {
  * The fragment is assembled by hand rather than through `sql`` ` because the driver hands over
  * `$1..$n` text it wrote itself plus already-bound values — there is no interpolation to guard.
  */
-function executorFor(client: DevDbClient): PgExecutor {
+export function pgExecutorFor(client: DbClient): PgExecutor {
   return {
     query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
       client.query<R>({ text, values } satisfies SqlFragment),
   };
 }
 
+/**
+ * Every table this process's framework packages own, applied before anything reads one.
+ *
+ * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
+ * applied statement by statement. Safe to split on `;`: both constants are fixed, with no
+ * semicolon inside a literal, and each package's own SQL test is where that stays true.
+ *
+ * `SQL_IDEMPOTENCY_TABLE` is here and not in `@ultimat3/action` because a package that holds no
+ * database dependency cannot apply its own schema — the same reason `SQL_JOBS_TABLE` is applied
+ * here. Without it `postgresIdempotencyStore` is a store whose first reservation fails on a
+ * missing relation, which is how a retried `POST /api/payments/charge` charges a card twice.
+ */
+async function applySchema(client: DevDbClient): Promise<void> {
+  for (const ddl of [SQL_JOBS_TABLE, SQL_IDEMPOTENCY_TABLE]) {
+    for (const statement of ddl.split(';')) {
+      if (statement.trim().length > 0) await client.execute(raw(statement));
+    }
+  }
+}
+
 /**
  * The dev queue is the real Postgres queue on the embedded Postgres — claiming, leases and the
  * one-live-job-per-key index all behave here exactly as in production. A memory queue in dev
  * would hide every bug this driver exists to make impossible.
  *
- * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL
- * is applied statement by statement. Safe to split on `;`: `SQL_JOBS_TABLE` is a fixed constant
- * with no semicolon inside a literal, and `driver-pg-sql.test.ts` is where that stays true.
+ * Three ambient installs, not one, and they go in together because they are one decision:
+ *
+ * - `setJobDriver` is what `jobDriver()` answers and what a worker claims from.
+ * - `setJobsFacade` is what `handle.enqueue()` routes through, so an enqueue inside a request's
+ *   transaction STAGES a row that commits or vanishes with the business rows. Without it the
+ *   fallback facade publishes straight to the driver, and a job for a transaction that rolled
+ *   back still runs. `currentTx()` resolves the executor because a `DbTx` IS a client on the
+ *   transaction's own connection, while the `Tx` token `@ultimat3/entity` hands over is not that
+ *   object — so the token is a key and the ALS is the lookup.
+ * - `setEventBus` makes `step.waitForEvent` durable. The memory bus this replaced forgot every
+ *   pending correlation on restart, which is a job that waits forever.
+ * - `setIdempotencyStore` makes `idempotent: true` mean it across replicas. The memory default is
+ *   one process' worth of keys, so a client retrying `POST /api/payments/charge` after a timeout
+ *   lands on a replica that has never seen the key and charges the card a second time.
+ *
+ * The idempotency store is installed HERE and not from the app, even though
+ * `@ultimat3/action` documents `postgresIdempotencyStore({ executor: Bun.sql })`: `Bun.sql` has no
+ * `.query(text, values)` — it is a tagged template whose positional form is `unsafe` — so that
+ * line does not satisfy `PgExecutor` at all, and a second executor would open a second pool
+ * against a URL this boot already resolved. Boot owns the connection, so boot supplies it.
+ * `startServices` runs before `loadApp`, so the store is in place before `registerAction`
+ * evaluates a `scope: 'shared'` declaration against it.
  */
-async function startJobs(client: DevDbClient): Promise<JobDriver> {
-  for (const statement of SQL_JOBS_TABLE.split(';')) {
-    if (statement.trim().length > 0) await client.execute(raw(statement));
-  }
-  const driver = createPgDriver({ executor: executorFor(client) });
+async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Promise<RunningQueue> {
+  await applySchema(client);
+  const executor = pgExecutorFor(client);
+  const driver = overrides?.jobs ?? createPgDriver({ executor });
   setJobDriver(driver);
-  return driver;
+  const outbox = createPgOutboxStore({
+    executor,
+    // The open transaction is a client on its own connection; the `Tx` token is not that object.
+    txExecutor: () => pgExecutorFor(currentTx() ?? client),
+  });
+  setJobsFacade(
+    createJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
+  );
+  const events = createPgEventBus({ executor });
+  setEventBus(events);
+  setIdempotencyStore(postgresIdempotencyStore({ executor }));
+  return { db: client, jobs: driver, outbox, events, stop: () => releaseQueue(client, driver) };
 }
 
 /**
- * Release both ambient accessors, then the resources behind them, in that order: a driver reset
+ * Release every ambient accessor, then the resources behind them, in that order: a driver reset
  * after its database is closed leaves a window where `jobDriver()` answers over a dead socket.
  * A stale driver is worse than none — the next command sees one installed and skips queue
  * startup entirely, so every query it makes fails on a connection this process already dropped.
+ *
+ * The facade goes with the driver for the same reason: an enqueue routed through a store bound to
+ * a closed client is a staged row nothing will ever publish.
  */
 async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promise<void> {
+  // The idempotency store goes back to the memory default for the same reason the facade does: it
+  // holds this client, and the next command in this process would reserve keys over a closed one.
+  resetIdempotency();
+  resetJobsFacade();
   resetJobDriver();
   setDbClient(undefined);
   await jobs?.close?.();
@@ -87,14 +171,16 @@ async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promi
  * would pay for services it cannot even use. `startServices` builds on this so there is one boot
  * path for "which database" and "which queue", not two.
  */
-export async function startQueue(services: DevServices): Promise<RunningQueue> {
+export async function startQueue(
+  services: DevServices,
+  overrides?: RuntimeOverrides,
+): Promise<RunningQueue> {
   const db = startDb(services);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.
     await db.ping();
-    const jobs = await startJobs(db);
-    return { db, jobs, stop: () => releaseQueue(db, jobs) };
+    return await startJobs(db, overrides);
   } catch (error) {
     // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
     // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to

package/src/dev-render.ts

@@ -2,29 +2,55 @@
 // `@ultimat3/render`'s own function for that mode — the CLI picks the mode and supplies the
 // document, it never decides what a mode means or what headers it earns.
 //
-// The document is head + shell. Islands are the compiled client graph's, and there is no
-// compiled graph before `x build`, so a dev page serves its real `<head>`, its real status and
-// its real cache headers around an empty root — never a 404.
+// The document is head + the route's own component, rendered by `@ultimat3/render`'s server JSX
+// writer, with the surface's compiled CSS inlined. Inlined rather than linked because a `site/`
+// page is a 0kb-JS artifact a CDN serves as one file: a stylesheet link would add a round trip to
+// the render path the mode exists to make cheap, and a static export would need a second file.
 
 import type { Ctx } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
 import { asCtx, html, stream } from '@ultimat3/http';
-import type { IsrController, RenderResult, RouteEntry } from '@ultimat3/render';
+import { currentLocale } from '@ultimat3/i18n';
+import type {
+  IslandCollector,
+  IsrController,
+  RenderResult,
+  RouteData,
+  RouteEntry,
+} from '@ultimat3/render';
 import {
   contentHash,
+  createIslandCollector,
   createIsrController,
   headFromMeta,
+  hydrateRuntime,
+  metaContextFor,
+  renderComponent,
   renderHead,
   renderSpa,
   renderSsr,
+  routeDataFor,
   routeEntries,
   SPA_ROOT_ID,
   seoRenderers,
   staticHeaders,
   streamResult,
+  stylesFor,
 } from '@ultimat3/render';
 
-export interface DevRenderOptions {
+/**
+ * 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;
+}
+
+export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
   /** Injected so a test can drive the ISR store without a timer. */
   readonly isr?: IsrController;
@@ -36,67 +62,173 @@ export interface DevRouteData extends Record<string, unknown> {
   readonly params: RouteParams;
 }
 
-const LANG = 'en';
+/**
+ * `<html lang>` is the request's own locale, never a constant: the `locale` stage negotiated it
+ * one stage before this handler and published it on the context, so a hardcoded `'en'` shipped
+ * every document mislabelled — wrong for a screen reader, wrong for `hreflang`, wrong for a CDN
+ * keying on `content-language`. Outside a request (`x build`'s prerender) it is the app's own
+ * configured fallback, which is the only defensible answer there.
+ */
+const lang = (): string => currentLocale();
 
-const headFor = async (entry: RouteEntry, data: DevRouteData): Promise<string> =>
+const headFor = async (entry: RouteEntry, ctx: DevRouteData, data: RouteData): Promise<string> =>
   renderHead(
-    headFromMeta(await entry.config.meta(data), seoRenderers({ path: new URL(data.url).pathname })),
+    headFromMeta(
+      await entry.config.meta(metaContextFor(ctx, data)),
+      seoRenderers({ path: new URL(ctx.url).pathname }),
+    ),
+  );
+
+/** `<style>` for the surface's own stylesheets, or nothing at all when the surface imports none. */
+const styleTag = (entry: RouteEntry): string => {
+  const css = stylesFor(entry.surface);
+  return css.length === 0 ? '' : `<style>${css}</style>`;
+};
+
+/**
+ * The route's rendered body, inside the hydration root. A module that exports no component (an
+ * `api/` route, or a `spa` whose data is all client-side) renders an empty root, which is the
+ * shell those modes are defined to serve — not a fallback for a component that failed.
+ */
+export async function routeBody(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  islands: IslandCollector,
+): Promise<string> {
+  if (entry.component === undefined) return `<div id="${SPA_ROOT_ID}"></div>`;
+  const url = new URL(ctx.url);
+  const html = await renderComponent(
+    entry.component,
+    // `data` is the route's own `load` result and is what `meta` was just given — the same object,
+    // never a second resolution. `query` is supplied because a page that reads `props.query.x`
+    // otherwise dereferences undefined and takes the whole render down.
+    {
+      data,
+      params: ctx.params,
+      url: ctx.url,
+      query: Object.fromEntries(url.searchParams) as Readonly<Record<string, string>>,
+    },
+    entry.file,
+    { islands },
   );
+  return `<div id="${SPA_ROOT_ID}">${html}</div>`;
+}
+
+/**
+ * One collector per RENDER, never module-global: two requests render different params, and a
+ * shared collector would bill one page for the other's islands. `hydrate` comes off the route, so
+ * an island never declares its own timing, and `resolve` is the build's — identity when nothing
+ * built any, which fails at the first island by name rather than emitting an unusable entry.
+ */
+const collectorFor = (entry: RouteEntry, options: DocumentOptions): IslandCollector =>
+  createIslandCollector({
+    file: entry.file,
+    hydrate: entry.config.hydrate,
+    ...(options.resolveIsland === undefined ? {} : { resolve: options.resolveIsland(entry.file) }),
+  });
 
 /**
- * Head + shell for one route render. Exported because the build's prerenderer must emit the same
+ * Head + body for one route render. Exported because the build's prerenderer must emit the same
  * document `x dev` serves — two document builders is how a page that works in dev ships broken.
  */
-export async function routeDocument(entry: RouteEntry, data: DevRouteData): Promise<string> {
-  return shellFor(await headFor(entry, data));
+export async function routeDocument(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  options: DocumentOptions = {},
+): Promise<string> {
+  return documentFrom(entry, ctx, await routeDataFor(entry.config, ctx), options);
 }
 
-const shellFor = (head: string): string =>
-  `<!doctype html><html lang="${LANG}"><head>${head}</head>` +
-  `<body><div id="${SPA_ROOT_ID}"></div></body></html>`;
+/**
+ * The document from data ALREADY resolved. Split from `routeDocument` so one request resolves
+ * `load` exactly once: `stream` renders head and body separately, and resolving in each would let
+ * a `<title>` describe content the body does not contain.
+ *
+ * The hydration runtime is appended after the body and only after it: what strategies a page needs
+ * is a fact about the islands the walk just recorded, so emitting it earlier would either guess or
+ * ship the whole runtime to a page with no island — the 0kb baseline, spent on nothing.
+ */
+async function documentFrom(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: DocumentOptions,
+): Promise<string> {
+  const islands = collectorFor(entry, options);
+  const [head, body] = await Promise.all([
+    headFor(entry, ctx, data),
+    routeBody(entry, ctx, data, islands),
+  ]);
+  return (
+    `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head>` +
+    `<body>${body}${hydrateRuntime(islands.directives)}</body></html>`
+  );
+}
 
 async function resultFor(
   entry: RouteEntry,
-  data: DevRouteData,
+  request: DevRouteData,
   options: DevRenderOptions,
   isr: IsrController,
   ctx: Ctx,
 ): Promise<RenderResult> {
-  const url = new URL(data.url);
+  const url = new URL(request.url);
+  // ONCE per request, before the mode is chosen. Every branch below reads this same object, so a
+  // route's `load` runs exactly once however its mode splits head from body.
+  const data = await routeDataFor(entry.config, request);
   switch (entry.config.render) {
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
-      const body = await routeDocument(entry, data);
+      const body = await documentFrom(entry, request, data, options);
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () => routeDocument(entry, data));
+      const served = await isr.serve(url.pathname, () =>
+        documentFrom(entry, request, data, options),
+      );
       return served.result;
     }
     case 'spa':
+      // The shell renders no body by definition, but it still carries the surface's CSS: the
+      // client paints into `#x-root` and a flash of unstyled shell is the mode's own regression.
       return renderSpa({
         entry,
         buildId: options.buildId,
-        head: await headFor(entry, data),
+        head: (await headFor(entry, request, data)) + styleTag(entry),
         chunks: [],
-        lang: LANG,
+        lang: lang(),
       });
     case 'stream': {
-      const head = await headFor(entry, data);
+      // The shell IS the component: nothing can yet mark a subtree as a hole. Solid's `Suspense`
+      // is not the missing piece and never will be here — it calls `getContextId()`, which throws
+      // outside a Solid renderer, and this package's JSX factory is inert by design. A hole marker
+      // has to be the framework's own. Until it exists the first flush carries the whole body —
+      // correct output, no streaming benefit.
+      const islands = collectorFor(entry, options);
+      const [head, shell] = await Promise.all([
+        headFor(entry, request, data),
+        routeBody(entry, request, data, islands),
+      ]);
       return streamResult(
         {
-          head: `<!doctype html><html lang="${LANG}"><head>${head}</head><body>`,
-          shell: `<div id="${SPA_ROOT_ID}"></div>`,
+          head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
+          // The runtime rides the first flush, with the shell it boots. A later chunk would leave
+          // the window between flush one and the close with inert islands and no listeners on
+          // them — which is exactly the first-click-lost failure `interaction` replay exists for.
+          shell: `${shell}${hydrateRuntime(islands.directives)}`,
           holes: [],
         },
         { buildId: options.buildId },
       );
     }
     default:
-      return renderSsr({ entry, params: data.params, url, ctx }, () => routeDocument(entry, data), {
-        buildId: options.buildId,
-      });
+      return renderSsr(
+        { entry, params: request.params, url, ctx },
+        () => documentFrom(entry, request, data, options),
+        { buildId: options.buildId },
+      );
   }
 }
 

package/src/dev-roles-fixture.ts

@@ -0,0 +1,67 @@
+// The one `RunningServices` every `dev-roles` test file boots roles against, and the one reset
+// between them. Shared rather than copied, for the reason `policy-fixture.ts` gives: three files
+// start the same roles, and a second copy of the runtime drifts while each file keeps passing.
+//
+// Its own module rather than a `.test.ts` neighbours import, because `tsconfig.json` excludes
+// `*.test.ts` — a fixture written there is one `tsc` never reads.
+
+import { noopPurgeDriver } from '@ultimat3/cache';
+import { resetLifecycle } from '@ultimat3/core';
+import {
+  createMemoryDriver,
+  createMemoryEventBus,
+  createMemoryOutboxStore,
+  resetJobs,
+  resetJobsFacade,
+  resetTasks,
+} from '@ultimat3/jobs';
+import { createMemoryDriver as createMemoryMailDriver } from '@ultimat3/mail';
+import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime';
+import { defineStorage, localDriver } from '@ultimat3/storage';
+import type { RunningServices } from './dev-runtime';
+import { resolveServices } from './dev-services';
+
+/**
+ * Every service a role touches, embedded but real — no PGlite boot for a role-wiring test.
+ *
+ * `root` is a parameter and not a constant: each test file owns its own directory and deletes it,
+ * so two files sharing one on-disk storage root cannot leave the other's fixture half-removed.
+ */
+export function fixtureRuntime(root: string): RunningServices {
+  const services = resolveServices(root, {});
+  const transport = new InProcessTransport();
+  return {
+    services,
+    db: { async ping() {}, async close() {} } as unknown as RunningServices['db'],
+    jobs: createMemoryDriver(),
+    // A real store, not a stub: the `worker` role starts the outbox relay against it, and a relay
+    // whose `claim()` rejects on the first 200ms tick is an unhandled rejection in whichever test
+    // happens to still be running.
+    outbox: createMemoryOutboxStore(),
+    events: createMemoryEventBus(),
+    transport,
+    transportDetail: 'in-process fanout',
+    // The sync role reads this to build its `PresenceRegistry`; the default is what a boot with no
+    // `NATS_URL` resolves to, so the fixture is the real number rather than a rounder one.
+    presenceTtlMs: DEFAULT_PRESENCE_TTL_MS,
+    storage: defineStorage({ disks: { local: localDriver({ root: `${root}/storage` }) } }),
+    mail: createMemoryMailDriver(),
+    mailDetail: 'embedded',
+    purge: noopPurgeDriver(),
+    purgeDetail: 'none',
+    stop: async () => transport.close(),
+  };
+}
+
+/**
+ * The process-global state one started role leaves behind. `resetLifecycle` is the load-bearing
+ * one: core's lifecycle is process-wide and a stopped server leaves it drained, so without it the
+ * SECOND web role in a file answers every request `X_DRAINING` — a suite that only passes when its
+ * tests are run one at a time. `@ultimat3/http`'s own server suite resets it for the same reason.
+ */
+export function resetDevRolesState(): void {
+  resetJobs();
+  resetJobsFacade();
+  resetTasks();
+  resetLifecycle();
+}