@ultimat3/cli 20.2.1 → 21.0.0

package/src/verify-run.ts

@@ -14,7 +14,7 @@ import {
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 
 /**
- * Run every step in order, never bailing early: an agent fixing three things at once needs all
+ * Run every step, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
  *
  * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
@@ -26,61 +26,43 @@ export async function runVerify(
   ctx: VerifyContext,
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
-  const results: StepResult[] = [];
   const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  const byName = new Map<string, StepResult>();
+  const began = performance.now();
+  // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
+  // the list, so a one-step run (`--only`) and a list with no serial suite keep today's order.
+  const overlapping = selected.some((step) => step.name === SERIAL_SUITES[0]);
+  const beside = overlapping ? selected.filter((step) => BESIDE_SERIAL_SUITES.has(step.name)) : [];
+  let pending: Promise<void> | undefined;
+  const join = async (): Promise<void> => {
+    await pending;
+    pending = undefined;
+  };
   for (const step of selected) {
-    const applies = step.applies === undefined ? true : await step.applies(ctx);
-    if (!applies) {
-      // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
-      // that claim, committed — so "nothing to check" now means the suite was deleted, and the
-      // gate says so on the step's own line rather than counting one more thing not to worry
-      // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
-      // the summary, `data.failed`, and the reference-app gate's own red list.
-      const required = floorRequires(floor, step.name);
-      results.push({
-        name: step.name,
-        ok: !required,
-        durationMs: 0,
-        skipped: !required,
-        findings: required ? [vanishedSuiteFinding(step.name)] : [],
-      });
-      continue;
+    if (beside.includes(step)) continue;
+    if (step.name === SERIAL_SUITES[0]) {
+      pending = Promise.all(
+        beside.map(async (other) => {
+          byName.set(other.name, await runStep(other, ctx, floor));
+        }),
+      ).then(() => undefined);
+    } else if (!SERIAL_SUITES.includes(step.name)) {
+      await join();
     }
-    const started = performance.now();
-    const outcome = await step.run(ctx).catch(
-      (error: unknown): StepOutcome => ({
-        ok: false,
-        findings: [findingOf(error, step.name)],
-      }),
-    );
-    // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
-    // over an all-skipped file, so the counts are the only channel that can tell the two apart.
-    // ONE definition of "nothing ran", read twice, because the floor decides which of the two
-    // things it means — exactly as it already does for a step whose `applies` said no.
-    const tests = outcome.tests;
-    const nothingRan = tests !== undefined && tests.ran === 0;
-    const required = floorRequires(floor, step.name);
-    // A step the floor requires whose suite executed nothing is the same vanished suite as a step
-    // with no files at all — the run just had to finish before it could be seen. Appended to the
-    // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
-    const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
-    results.push({
-      name: step.name,
-      ok: outcome.ok && vanished.length === 0,
-      durationMs: Math.round(performance.now() - started),
-      // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
-      // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
-      // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
-      skipped: nothingRan && !required,
-      findings: [...outcome.findings, ...vanished],
-      ...(outcome.output === undefined ? {} : { output: outcome.output }),
-      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
-      ...(tests === undefined ? {} : { tests }),
-    });
+    byName.set(step.name, await runStep(step, ctx, floor));
   }
+  await join();
+  // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
+  // every gate parsing either read the same sequence they always did.
+  const results = selected.flatMap((step) => {
+    const result = byName.get(step.name);
+    return result === undefined ? [] : [result];
+  });
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
   const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
-  const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  // WALL time, not the sum of step times: with steps overlapping, the sum overstates what a run
+  // costs, and the wall clock is the number a CI job waits on.
+  const totalMs = Math.round(performance.now() - began);
   const summary = verifySummary({
     results,
     failed: failedSteps,
@@ -139,6 +121,79 @@ function verifySummary(input: {
   return msg(clean ? 'cli.verify.fail' : 'cli.verify.failSkipped', params);
 }
 
+/**
+ * `x verify`'s wall time was the SUM of 20 serial steps (#14, the DX ledger): measured locally, 395s,
+ * of which `lint`, `boundaries`, `filesize`, `package-shape` and `errors` were 127s spent while
+ * nothing else ran. They read the tree and write nothing a later step reads (`lint` is biome over
+ * files; the rest are in-process scans), so they run BESIDE the serial suites — `live` and `e2e`
+ * are one worker each, Postgres- and browser-bound, and mostly waiting. `typecheck` stays first
+ * and alone: `tsc -b` writes `.tsbuildinfo` and `dist/`, and `unit` saturates every core.
+ */
+export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
+  'lint',
+  'boundaries',
+  'filesize',
+  'package-shape',
+  'errors',
+]);
+
+/** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
+export const SERIAL_SUITES: readonly string[] = ['live', 'job', 'e2e', 'eval'];
+
+async function runStep(
+  step: VerifyStep,
+  ctx: VerifyContext,
+  floor: Awaited<ReturnType<typeof readVerifyFloor>>,
+): Promise<StepResult> {
+  const applies = step.applies === undefined ? true : await step.applies(ctx);
+  if (!applies) {
+    // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
+    // that claim, committed — so "nothing to check" now means the suite was deleted, and the
+    // gate says so on the step's own line rather than counting one more thing not to worry
+    // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
+    // the summary, `data.failed`, and the reference-app gate's own red list.
+    const required = floorRequires(floor, step.name);
+    return {
+      name: step.name,
+      ok: !required,
+      durationMs: 0,
+      skipped: !required,
+      findings: required ? [vanishedSuiteFinding(step.name)] : [],
+    };
+  }
+  const started = performance.now();
+  const outcome = await step.run(ctx).catch(
+    (error: unknown): StepOutcome => ({
+      ok: false,
+      findings: [findingOf(error, step.name)],
+    }),
+  );
+  // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
+  // over an all-skipped file, so the counts are the only channel that can tell the two apart.
+  // ONE definition of "nothing ran", read twice, because the floor decides which of the two
+  // things it means — exactly as it already does for a step whose `applies` said no.
+  const tests = outcome.tests;
+  const nothingRan = tests !== undefined && tests.ran === 0;
+  const required = floorRequires(floor, step.name);
+  // A step the floor requires whose suite executed nothing is the same vanished suite as a step
+  // with no files at all — the run just had to finish before it could be seen. Appended to the
+  // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
+  const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
+  return {
+    name: step.name,
+    ok: outcome.ok && vanished.length === 0,
+    durationMs: Math.round(performance.now() - started),
+    // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
+    // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
+    // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
+    skipped: nothingRan && !required,
+    findings: [...outcome.findings, ...vanished],
+    ...(outcome.output === undefined ? {} : { output: outcome.output }),
+    ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+    ...(tests === undefined ? {} : { tests }),
+  };
+}
+
 function findingOf(error: unknown, step: string): Finding {
   // A step may throw anything, including an Error that fights being read: `instanceof` runs a
   // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the

package/src/verify-tests.ts

@@ -19,6 +19,7 @@ import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
 import { defaultWorkers } from './test-workers';
+import { withE2eApp } from './verify-e2e';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
 import { runParallel } from './verify-test-run';
@@ -162,6 +163,12 @@ const ignoreFlags = (patterns: readonly string[]): readonly string[] =>
 export const typeFiltersOf = (type: Exclude<TestType, 'unit'>): readonly string[] =>
   OWNERSHIP.filter(([owner]) => owner === type).map(([, filter]) => filter);
 
+/**
+ * An e2e test's own budget: a first navigation waits on `x dev` compiling the route and its island,
+ * which bun's default 5 s does not cover — a timeout there reads as an app bug that is not one.
+ */
+export const E2E_TEST_TIMEOUT_MS = 60_000;
+
 /** Unit is everything the typed suites do not claim, so no test can fall between two steps. */
 export const testStepCommand = (type: TestType): readonly string[] =>
   type === 'unit'
@@ -173,6 +180,7 @@ export const testStepCommand = (type: TestType): readonly string[] =>
     : [
         'bun',
         'test',
+        ...(type === 'e2e' ? [`--timeout=${String(E2E_TEST_TIMEOUT_MS)}`] : []),
         ...ignoreFlags([...NEVER_A_TEST, ...disownedBy(type)]),
         ...typeFiltersOf(type),
       ];
@@ -203,10 +211,19 @@ export const resetTestDiscovery = (): void => discovered.clear();
 const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
   const command = testStepCommand(type);
   const envOverrides = testEnvOverrides(ctx.root, ctx.env ?? Bun.env);
-  const result = await ctx.runner(command, {
-    cwd: ctx.root,
-    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
-  });
+  const exec = (e2e: { command: readonly string[]; env: typeof envOverrides }) =>
+    ctx.runner(e2e.command, {
+      cwd: ctx.root,
+      ...(Object.keys(e2e.env).length === 0 ? {} : { env: e2e.env }),
+    });
+  // The e2e step drives a real browser against the app it spawns, when this machine has one.
+  const result =
+    type === 'e2e'
+      ? await withE2eApp(
+          { root: ctx.root, isApp: isApp(ctx.root), command, env: envOverrides },
+          exec,
+        )
+      : await exec({ command, env: envOverrides });
   return {
     ...fromExec(result, {
       code: 'X_TEST_FAILED',

package/src/worker-bundle.ts

@@ -0,0 +1,192 @@
+// The page's framework scripts (plan 101), each built as its own classic-script browser bundle,
+// addressed by a hash of its source graph, served `immutable` by the same route in `x dev` and the
+// container: the ONE sync worker (`@ultimat3/realtime/sync-worker`, slice 11) and the ONE page boot
+// (`@ultimat3/realtime/boot` — the disk restore and the outbox, once per page instead of once per
+// island). A new deploy is a new URL, so an old tab keeps what it started with.
+
+// why: Bun ships no path API; the entry is resolved to a file and named in the cause.
+import { dirname, join, relative } from 'node:path';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
+import { describeBuildError, graphHash, stripDebugId } from './island-bundle';
+
+/** Under the dev namespace `/_x` — where the socket it opens (`/_x/sync`) already lives. */
+export const SYNC_WORKER_BASE_PATH = '/_x/sync-worker';
+
+/** What an app resolves: realtime's worker entry, from the APP's install, never the CLI's own. */
+export const SYNC_WORKER_SPECIFIER = '@ultimat3/realtime/sync-worker';
+
+/** Under the dev namespace too; one per document that carries a principal scope. */
+export const PAGE_BOOT_BASE_PATH = '/_x/page-boot';
+
+/** Realtime's page boot, from the APP's install. */
+export const PAGE_BOOT_SPECIFIER = '@ultimat3/realtime/boot';
+
+/** One framework script: the sync worker or the page boot. */
+export interface FrameworkScript {
+  /** `<base>/<hash>.js` — what the document names. */
+  readonly url: string;
+  readonly code: string;
+  readonly bytes: number;
+}
+
+/** The worker, by the name every caller already uses. */
+export type SyncWorkerChunk = FrameworkScript;
+
+export interface BuildSyncWorkerOptions {
+  /** An absolute entry path. Absent resolves `SYNC_WORKER_SPECIFIER` from `root`. */
+  readonly entry?: string;
+}
+
+/**
+ * `undefined` when the app cannot resolve realtime's worker: an app with no realtime has no
+ * socket to share, and the tab-side host falls back to an in-page engine by design (slice 11's
+ * transparent fallback) — absence is an answer, not a failure.
+ */
+export function buildSyncWorker(
+  root: string,
+  options: BuildSyncWorkerOptions = {},
+): Promise<FrameworkScript | undefined> {
+  return buildFrameworkScript(
+    root,
+    'sync worker',
+    SYNC_WORKER_SPECIFIER,
+    SYNC_WORKER_BASE_PATH,
+    options.entry,
+  );
+}
+
+/**
+ * The page boot, or `undefined` for an app with no realtime (nothing to restore, no outbox). A
+ * document then carries no boot script, and `pageRealtime().booted` answers at once.
+ */
+export function buildPageBoot(
+  root: string,
+  options: BuildSyncWorkerOptions = {},
+): Promise<FrameworkScript | undefined> {
+  return buildFrameworkScript(
+    root,
+    'page boot',
+    PAGE_BOOT_SPECIFIER,
+    PAGE_BOOT_BASE_PATH,
+    options.entry,
+  );
+}
+
+async function buildFrameworkScript(
+  root: string,
+  what: FrameworkScriptKind,
+  specifier: string,
+  basePath: string,
+  explicit: string | undefined,
+): Promise<FrameworkScript | undefined> {
+  const entry = explicit ?? resolveEntry(root, specifier);
+  if (entry === undefined) return undefined;
+  const label = relative(root, entry);
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [entry],
+      target: 'browser',
+      // A CLASSIC script: `new SharedWorker(url, { name })` with no `type: 'module'` runs it, and a
+      // `<script defer>` runs it before any island module that follows it in the document.
+      format: 'iife',
+      splitting: false,
+      minify: true,
+      // `island-bundle.ts`'s reasons, verbatim: a chunk is only ever built to be shipped, and the
+      // map's `sourcesContent` is the one stable identity a minified bundle has.
+      define: { 'process.env.NODE_ENV': '"production"' },
+      sourcemap: 'external',
+    });
+  } catch (error) {
+    throw new FrameworkScriptBuildFailedError({
+      what,
+      entry: label,
+      logs: describeBuildError(error),
+    });
+  }
+  const output = built.outputs.find((artifact) => artifact.kind === 'entry-point');
+  const map = built.outputs.find((artifact) => artifact.kind === 'sourcemap');
+  if (!built.success || output === undefined || map === undefined) {
+    throw new FrameworkScriptBuildFailedError({
+      what,
+      entry: label,
+      logs: built.logs.map((log) => String(log)).join('; '),
+    });
+  }
+  const code = stripDebugId(await output.text());
+  return {
+    url: `${basePath}/${graphHash(specifier, await map.text())}.js`,
+    code,
+    bytes: new TextEncoder().encode(code).byteLength,
+  };
+}
+
+/**
+ * The app's realtime, from the root or — in a workspace app, where `@ultimat3/realtime` is a
+ * dependency of `apps/<app>` and not of the root (`examples/dummy`) — from the first app that has
+ * it: where its islands resolve it, which is the copy the scripts must match. Resolving from the
+ * root alone built no worker and no boot for such an app, silently.
+ */
+function resolveEntry(root: string, specifier: string): string | undefined {
+  for (const dir of [root, ...appDirs(root)]) {
+    try {
+      return Bun.resolveSync(specifier, dir);
+    } catch {
+      // Not installed here, or a realtime that predates the export: try the next app.
+    }
+  }
+  return undefined;
+}
+
+function appDirs(root: string): readonly string[] {
+  const glob = new Bun.Glob('apps/*/package.json');
+  return [...glob.scanSync({ cwd: root, onlyFiles: true })]
+    .sort()
+    .map((file) => join(root, dirname(file)));
+}
+
+/** The script a build produced, read per request so `x dev` and the container share one route. */
+export type SyncWorkerSource = () => FrameworkScript | undefined;
+
+export function syncWorkerRoutes(source: SyncWorkerSource): readonly Route[] {
+  return [scriptRoute(SYNC_WORKER_BASE_PATH, 'assets.sync-worker', 'sync worker', source)];
+}
+
+export function pageBootRoutes(source: SyncWorkerSource): readonly Route[] {
+  return [scriptRoute(PAGE_BOOT_BASE_PATH, 'assets.page-boot', 'page boot', source)];
+}
+
+function scriptRoute(
+  basePath: string,
+  name: string,
+  what: string,
+  source: SyncWorkerSource,
+): Route {
+  return {
+    method: 'GET',
+    path: `${basePath}/:file`,
+    meta: { name, auth: 'public', tags: ['assets'] },
+    handler: (request: UltimateRequest): Response => {
+      const script = source();
+      if (script === undefined || script.url !== request.pathname) {
+        return json(
+          {
+            ok: false,
+            error: {
+              code: 'X_ROUTE_NOT_FOUND',
+              cause: `no ${what} is built at ${request.pathname} — the document that named it was rendered against another build`,
+              fix: `reload the page — this process serves only the ${what} it built`,
+            },
+          },
+          { status: 404 },
+        );
+      }
+      return applyCacheHeaders(
+        new Response(script.code, { headers: { 'content-type': 'text/javascript' } }),
+        { mode: 'immutable' },
+      );
+    },
+  };
+}