@ultimat3/cli 19.1.3 → 19.3.1

package/src/style-routes.ts

@@ -0,0 +1,56 @@
+// Serving the surface stylesheets. `x dev` and the container mount the same route over the same
+// table, for `island-routes.ts`' reason: the URL is minted by one resolver and baked into the
+// document, so a dev-only path would be a page that paints in `x dev` and renders naked in the
+// image.
+
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { StyleBundle } from './style-bundle';
+import { STYLE_BASE_PATH } from './style-bundle';
+
+/**
+ * A getter, not the bundle: `x dev` re-registers island CSS on every watcher tick, and a table
+ * captured when the route was mounted would serve the stylesheet as it was at boot for the rest of
+ * the session.
+ */
+export type StyleSource = () => StyleBundle;
+
+/**
+ * The URL is content-addressed, so the bytes behind it never change and the answer is
+ * `public, max-age=31536000, immutable` — the same headers an island chunk earns, and the whole
+ * reason this is a file rather than 157 kB of `<style>` inside a `no-store` document.
+ *
+ * A miss can only be a document older than this process's registry, which is a fact worth stating
+ * rather than a bare 404 whose meaning an agent has to guess.
+ */
+export function styleRoutes(source: StyleSource): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${STYLE_BASE_PATH}/*file`,
+      meta: { name: 'assets.style', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const chunk = source().chunkAt(request.pathname);
+        if (chunk === undefined) {
+          return json(
+            {
+              ok: false,
+              error: {
+                code: 'X_ROUTE_NOT_FOUND',
+                cause: `no surface stylesheet is registered at ${request.pathname} — the document that asked for it was rendered against an older build`,
+                // No `x` citation, for `island-routes.ts`' reason: this route is mounted in
+                // exactly two places (`cmd-dev.ts`, `serve.ts`) and neither reads `.x/static`.
+                fix: 'reload the page — this process serves only the stylesheet its own modules registered, and the document holding this URL came from an earlier build',
+              },
+            },
+            { status: 404 },
+          );
+        }
+        return applyCacheHeaders(
+          new Response(chunk.css, { headers: { 'content-type': 'text/css; charset=utf-8' } }),
+          { mode: 'immutable' },
+        );
+      },
+    },
+  ];
+}

package/src/sw-artifacts.ts

@@ -9,6 +9,7 @@ import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
 import { msg } from './messages';
 import type { PwaArtifacts } from './pwa-artifacts';
+import type { StyleBundle } from './style-bundle';
 
 /** Root scope, so `/sw.js` and nothing under a directory — `assertScope` refuses the rest. */
 export const SERVICE_WORKER_PATH = '/sw.js';
@@ -43,15 +44,47 @@ export interface ServiceWorkerInput {
   readonly buildId: string;
   readonly routes: readonly RouteDescriptor[];
   readonly islands: IslandBundle;
+  /**
+   * The surface stylesheets every document links. Precached beside the island chunks and for the
+   * same reason: they are content-addressed and served `immutable`, and a document that reaches
+   * the offline fallback with no CSS is a page the visitor cannot read.
+   */
+  readonly styles: StyleBundle;
+  /**
+   * What the build RENDERED, keyed by the route path it was rendered for. Optional because only a
+   * static export has documents to hash: `x dev` and the container emit the worker at boot, where
+   * no page has been built yet, and `buildPrecacheManifest` falls back to the build id for a route
+   * this map does not name.
+   */
+  readonly documents?: ReadonlyMap<string, RenderedDocument>;
+}
+
+/**
+ * One rendered document, as the precache manifest needs it.
+ *
+ * `revision` is `contentHash(html)` — `@ultimat3/render`'s own, the function that already stamps
+ * an ETag — and never the build id. `precache.ts`' header states the rule and nothing kept it:
+ * `pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+ * `{"url":"/","revision":"build-aaa","bytes":0}` and two deploys of a byte-identical site
+ * re-fetched every precached document. The zero was the second half — `DEFAULT_PRECACHE_WARN_BYTES`
+ * is a 5 MB budget over a total that could not count one byte of HTML.
+ */
+export interface RenderedDocument {
+  readonly revision: string;
+  readonly bytes: number;
 }
 
 /**
  * The route table, as the service worker sees it. `api/` is dropped: an API response is a JSON
  * document whose freshness is the app's business, and precaching one serves a stale answer to a
- * client that had a network. Only the four fields `PwaRoute` reads cross — a descriptor carries
- * budgets and policy flags that a browser has no use for.
+ * client that had a network. Only the fields a browser can act on cross — a descriptor carries
+ * budgets and policy flags it has no use for — plus, for a route this build rendered, the content
+ * hash and the byte count of the document it produced.
  */
-const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
+const pwaRoutes = (
+  routes: readonly RouteDescriptor[],
+  documents: ReadonlyMap<string, RenderedDocument>,
+): readonly PwaRoute[] =>
   // `flatMap` rather than `filter().map()`: the filter's predicate does not narrow `surface` for
   // the map that follows it, and `PwaRoute` declares the two navigable surfaces only. A cast would
   // hide the day a fifth surface arrives.
@@ -59,6 +92,8 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
     // `shared/` is dropped with `api/`, and for a stronger reason: it is not a URL at all — the
     // surface exists so two routes can import one module, and a browser can never navigate to it.
     if (route.surface !== 'site' && route.surface !== 'app') return [];
+    // A `Map`, so a route path that happens to spell a prototype member cannot answer with one.
+    const document = documents.get(route.path);
     return [
       {
         path: route.path,
@@ -66,19 +101,24 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
         mode: route.mode,
         offline: route.offline,
         dynamic: route.dynamic,
+        // Absent rather than invented for a route no build rendered — an `ssr` page, or one this
+        // pass could not produce. `buildPrecacheManifest` then falls back to the build id, which
+        // is the honest answer when there are no bytes to hash.
+        ...(document === undefined ? {} : { revision: document.revision, bytes: document.bytes }),
       },
     ];
   });
 
 /**
- * Every island chunk, precached. They are content-addressed and served `immutable`, so the
- * revision IS the URL's hash and a byte-identical chunk across deploys is never re-downloaded.
+ * Every island chunk and every surface stylesheet, precached. They are content-addressed and
+ * served `immutable`, so the revision IS the URL's hash and a byte-identical asset across deploys
+ * is never re-downloaded.
  *
  * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
  * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
  */
-const islandAssets = (islands: IslandBundle): readonly PrecacheAsset[] =>
-  [...islands.chunks]
+const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly PrecacheAsset[] =>
+  [...islands.chunks, ...styles.chunks]
     .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
@@ -120,27 +160,47 @@ export function serviceWorkerArtifacts(
   input: ServiceWorkerInput,
 ): ServiceWorkerArtifacts | undefined {
   const pwa = input.pwa;
-  if (pwa.offline.fallback === null) return undefined;
+  const head = serviceWorkerHead(pwa);
+  const fallback = pwa.offline.fallback;
+  // One predicate DECIDES — `serviceWorkerHead`, so a document can never name a script this
+  // function then declines to emit — and the `null` check is what NARROWS `fallback` below:
+  // TypeScript cannot learn a `string` from the other's answer, and a cast would hide the day the
+  // two stop agreeing.
+  if (head === undefined || fallback === null) return undefined;
+  const documents = input.documents ?? new Map<string, RenderedDocument>();
+  // The offline document is the one entry `buildPrecacheManifest` adds ITSELF, as
+  // `reason: 'fallback'`, ahead of every route — and `add()` keeps the first entry per url, so its
+  // revision is the one that decides. Without this pair it was the build id whatever the build
+  // knew, which re-downloaded the single page an offline navigation depends on on every deploy.
+  // Absent when this pass did not render the fallback (no route serves it — `x doctor` reports
+  // that as `X_PWA_NO_OFFLINE_FALLBACK`), and then `@ultimat3/pwa` falls back to the build id.
+  const fallbackDocument = documents.get(fallback);
   const output = generateServiceWorker(
-    pwaRoutes(input.routes),
+    pwaRoutes(input.routes, documents),
     {
       scope: SW_SCOPE,
       swPath: SERVICE_WORKER_PATH,
+      ...(fallbackDocument === undefined
+        ? {}
+        : {
+            offlineFallbackRevision: fallbackDocument.revision,
+            offlineFallbackBytes: fallbackDocument.bytes,
+          }),
       offline: {
-        fallback: pwa.offline.fallback,
+        fallback,
         ...(pwa.offline.image === null ? {} : { image: pwa.offline.image }),
         ...(pwa.offline.font === null ? {} : { font: pwa.offline.font }),
         neverCache: pwa.offline.neverCache,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: islandAssets(input.islands),
+      assets: staticAssets(input.islands, input.styles),
     },
     input.buildId,
   );
   return {
     source: output.source,
     register: registerSource(),
-    head: `<script src="${SW_REGISTER_PATH}" defer></script>`,
+    head,
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
     // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
@@ -152,6 +212,18 @@ export function serviceWorkerArtifacts(
   };
 }
 
+/**
+ * The one `<script src>` a document needs, or `undefined` for an app that gets no worker.
+ *
+ * Separate from `serviceWorkerArtifacts` because the two are wanted at different moments: a static
+ * export has to put this tag in every document it renders, and the WORKER cannot be emitted until
+ * those documents exist — its precache manifest is built from their content hashes. One predicate
+ * for both (`offline.fallback === null` is `generateServiceWorker`'s refusal, spent early), so a
+ * document can never name a script the export does not carry.
+ */
+export const serviceWorkerHead = (pwa: PwaArtifacts): string | undefined =>
+  pwa.offline.fallback === null ? undefined : `<script src="${SW_REGISTER_PATH}" defer></script>`;
+
 /**
  * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
  * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently

package/src/templates/admin-page.ts

@@ -9,6 +9,7 @@ import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
+import { LINE_WIDTH } from './wrap';
 
 /** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
 export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
@@ -58,9 +59,45 @@ const catalogImport = (module: string | undefined): string =>
 const pageImports = (module: string | undefined): string =>
   sortedImports([
     `import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`,
+    `import { definePermissions } from '@ultimat3/policy';`,
     catalogImport(module),
   ]);
 
+/**
+ * The page DECLARES the permission it requires, in both registries that decide about it.
+ *
+ * `x g admin:page ops` emitted `permissions: ['ops:read']` and nothing anywhere declared
+ * `ops:read`, so `assertPermission` threw X_PERMISSION_UNKNOWN on the first request that reached
+ * the page: a screen the generator built and no actor can open. Nothing catches it either — the
+ * gate's `policy` step reads `roleDefinitions()` and `routeEntries()`, and an admin page is
+ * neither a role nor a route, so `x verify` is green over it.
+ *
+ * Here rather than in a `policy.ts` beside it, because registration is a side effect of IMPORT and
+ * `pages:` already imports this module: a declaration in a file the admin does not import is a
+ * declaration that never runs. `declare module` is the type half — `can()`'s key type reads the
+ * registry, not the `definePermissions` call — and merging an identical member is what lets an app
+ * that already declares this permission keep its own declaration.
+ */
+const declarePermissions = (name: string, permission: string): string => {
+  const line = `export const ${camel(name)}PagePermissions = definePermissions(['${permission}']);`;
+  // Emitted PRE-formatted, because a template cannot run one: past 100 columns biome rewrites this
+  // call across four lines, and `x new zebra`-class names reach it (`emitted-contract.test.ts`
+  // varies both the length and the first letter for exactly this reason).
+  return line.length <= LINE_WIDTH
+    ? line
+    : `export const ${camel(name)}PagePermissions = definePermissions([\n  '${permission}',\n]);`;
+};
+
+const permissionDeclaration = (name: string, permission: string): string => `
+declare module '@ultimat3/policy' {
+  interface PermissionRegistry {
+    '${permission}': true;
+  }
+}
+
+${declarePermissions(name, permission)}
+`;
+
 /** `useT()` is per render, so the component binds it in its own body. */
 const translatorBinding = (module: string | undefined): string =>
   module === undefined ? '' : '\n  const t = useT();\n';
@@ -81,9 +118,12 @@ const pageSource = (
 // so the specifier is relative to wherever \`defineAdmin\` lives:
 //   import { ${declaration}Page } from './${name}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
+//
+// The permission below is declared here AND has to be decided: an authz map built from a fixed
+// list must name '${permission}' too, or a declared permission is still denied for everyone.
 
 ${pageImports(module)}
-
+${permissionDeclaration(name, permission)}
 export function ${Name}Page(props: AdminPageProps) {${translatorBinding(module)}
   return (
     <section>
@@ -108,6 +148,7 @@ const pageTest = (name: string, permission: string): string => {
   const declaration = camel(name);
   return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
 // admin screen from a page, and the two an edit here is most likely to break.
+import { knownPermissions } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { ${declaration}Page } from './${name}';
 
@@ -119,6 +160,13 @@ unitTest('the ${name} admin page is rooted and guarded', () => {
   expect(${declaration}Page.permissions).toContain('${permission}');
 });
 
+// A \`permissions:\` entry no \`definePermissions()\` declares is X_PERMISSION_UNKNOWN on the first
+// request that reaches the page — a screen this generator built and nobody can open. Importing the
+// page above is what registers it, which is why the declaration lives in that file and not beside it.
+unitTest('the ${name} admin page declares its permission', () => {
+  expect(knownPermissions()).toContain('${permission}');
+});
+
 unitTest('the ${name} admin page declares no route of its own', () => {
   // \`pages:\` is the only way in. A \`config\` export here would be a route the frame never guards.
   expect('config' in ${declaration}Page).toBe(false);

package/src/templates/resource-form-island.ts

@@ -39,8 +39,14 @@ const formIslandSource = (
 
 import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
-import * as solidRuntime from 'solid-js';
-import { createSignal } from 'solid-js';
+import {
+  createContext,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  useContext,
+} from 'solid-js';
 import { render } from 'solid-js/web';
 import styles from './ui.module.scss';
 
@@ -123,11 +129,15 @@ function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Eleme
  * registers. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
  * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
  *
+ * Six NAMED imports, never \`import * as solidRuntime\`: a namespace object handed to a function
+ * keeps every export of solid-js alive, and the bundler cannot shake what it cannot see unused —
+ * measured at 14.8 kB minified per island chunk (5.6 kB gzipped) for the namespace form.
+ *
  * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
  * so without it the server's markup stays on screen above a second, live copy of the same thing.
  */
 export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
-  setSolidRuntime(solidRuntime);
+  setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
   el.textContent = '';
   render(
     () => (

package/src/templates/scaffold-container.ts

@@ -6,6 +6,7 @@
 // run-to-completion migrate step are conventions every container platform shares — a Heroku
 // buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
 
+import { SECRETS_KEY_FILE } from '@ultimat3/core';
 import type { GeneratedFile, NameSet } from './naming';
 import { helmFiles } from './scaffold-helm';
 
@@ -81,6 +82,12 @@ ENTRYPOINT ["bun", "apps/web/server.ts"]
  * tells the operator to create, in its own `env_file:` — nor `.env.development`, and both landed in
  * an image layer that `cache-to=mode=max` then pushes to a shared cache. Same four lines the
  * framework's own `docker/Dockerfile.dockerignore` carries, and for the same reason.
+ *
+ * The key file is interpolated from `SECRETS_KEY_FILE` rather than written out, because the
+ * constant is what `findMasterKey` reads: a rename would otherwise leave every app this generator
+ * has ever produced ignoring a filename nothing writes, which reads as a rule still in force.
+ * `scripts/image-contract.ts` holds every ignore file IN THIS TREE to the same line; a generated
+ * app's copy is this template's, and `scaffold-container.test.ts` is where it is judged.
  */
 const dockerignore = (): string => `**/.env
 **/.env.*
@@ -88,6 +95,11 @@ const dockerignore = (): string => `**/.env
 # Same shape, different file: an .npmrc carries a registry auth token, so any that exists in a
 # build context is somebody's local credential and has no business in a layer.
 **/.npmrc
+# Same shape, and this one is the key itself: ${SECRETS_KEY_FILE} decrypts the committed
+# secrets.enc.json beside it, and findMasterKey falls back to the file whenever
+# ULTIMATE_SECRETS_KEY is unset — so a baked copy boots the image on it and the platform's key is
+# never exercised.
+**/${SECRETS_KEY_FILE}
 
 node_modules
 **/node_modules

package/src/templates/scaffold-repo.ts

@@ -307,6 +307,12 @@ const bunfig = (): string => `[test]
 root = "."
 # Frozen clock, seeded RNG, sealed network — nondeterminism in a test is a bug.
 preload = ["@ultimat3/testing/preload"]
+# An island is mounted from a BUILT chunk that \`mountIsland\` writes to a temp .mjs, so
+# \`bun test --coverage\` reports that file: two minified lines, under a name no source has. Bun
+# does not remap a pre-built module through its sourcemap (measured on 1.4.0, and the build does
+# emit one), so the row can only ever be noise — the island's own .island.tsx is not what it
+# describes. Ignoring it removes the phantom; it hides no line any test was covering.
+coveragePathIgnorePatterns = ["**/*.mjs"]
 `;
 
 const scssTypes =
@@ -327,13 +333,18 @@ declare module '*.scss' {
 }
 `;
 
+// Build output is ROOT-ANCHORED, and that is not cosmetic: an unanchored `dist/` or `coverage/`
+// matches a directory of that name at ANY depth, so `apps/web/site/dist/page.tsx` — an app's own
+// `/dist` route, the directory IS the URL — was a file git refused to commit and `x dev` refused to
+// reload. `packages/*/dist/` keeps a workspace's build output ignored without reaching a surface.
 const gitignore = (): string => `node_modules/
 .x/
-dist/
+/dist/
+packages/*/dist/
 *.tsbuildinfo
 .env
 .env.*.local
-coverage/
+/coverage/
 playwright-report/
 test-results/
 `;

package/src/test-passes.ts

@@ -0,0 +1,79 @@
+// Which of a selection's files may share a worker pool, and which may not. `--parallel=N` is the
+// width of the WHOLE run, so a selection holding a `live` or an `e2e` file is more than one run —
+// this file decides how many, and `test-shards.ts` spends them.
+
+import type { TestFile } from './test-select';
+import type { TestType } from './verify-tests';
+import { ownerOf, SERIAL_TYPES } from './verify-tests';
+
+/** One `bun test` invocation: which files, how wide, and the type its reproduce line names. */
+export interface TestPass {
+  readonly files: readonly TestFile[];
+  readonly workers: number;
+  /**
+   * The type this pass is exactly the selection of, when it is one — so a failure's `fix:` names
+   * `x test live --workers 1` and reruns THESE files, not the whole corpus at this width.
+   */
+  readonly type?: TestType;
+}
+
+export interface PassInput {
+  readonly files: readonly TestFile[];
+  /** What the caller asked for, already bounded by `--workers`' own reader. */
+  readonly workers: number;
+  /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
+  readonly type?: TestType;
+  /** Set for a `--worker I` rerun, which is one process by construction. */
+  readonly shard?: number;
+}
+
+const widthFor = (files: readonly TestFile[], workers: number): number =>
+  Math.max(1, Math.min(Math.trunc(workers), files.length || 1));
+
+/**
+ * The passes one invocation becomes. One, for every selection that holds no serial file — which
+ * is every `x test unit`, every `--filter` over a feature's contract tests, and the whole corpus
+ * of an app that has neither.
+ *
+ * `live` and `e2e` are the exception, and `verify-tests.ts` owns both the list and the reasons: a
+ * logical replication slot is named at the Postgres CLUSTER level so a per-worker database does
+ * not isolate it, and `e2e` shares one `dist/` and one browser profile. `x verify` has routed them
+ * through `runSerial` since 2026-08 while `x test` clamped on the POSITIONAL alone — so a bare
+ * `x test --workers 8` ran the very files the gate runs one at a time, eight at a time, and only
+ * a real `TEST_DATABASE_URL` makes that visible.
+ *
+ * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
+ * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
+ *
+ * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
+ * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
+ * different set of files from shard i of the run it reproduces.
+ */
+export function testPasses(input: PassInput): readonly TestPass[] {
+  const serialTypes = new Set<TestType>(SERIAL_TYPES);
+  if (input.shard !== undefined) {
+    return [
+      {
+        files: input.files,
+        workers: widthFor(input.files, input.workers),
+        ...(input.type === undefined ? {} : { type: input.type }),
+      },
+    ];
+  }
+  const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
+  const passes: TestPass[] = [];
+  // Cheapest first, and the widest first: the pool run is most of the corpus and most of the
+  // signal, and a serial suite that needs a database is the one a laptop is least likely to have.
+  if (shared.length > 0) {
+    passes.push({
+      files: shared,
+      workers: widthFor(shared, input.workers),
+      ...(input.type === undefined ? {} : { type: input.type }),
+    });
+  }
+  for (const type of SERIAL_TYPES) {
+    const files = input.files.filter((file) => ownerOf(file.path) === type);
+    if (files.length > 0) passes.push({ files, workers: 1, type });
+  }
+  return passes;
+}