@ultimat3/cli 17.0.0 → 19.0.0

package/src/sw-artifacts.ts

@@ -0,0 +1,162 @@
+// `sw.js` and its registration script, built from the route table and the island bundle — the one
+// caller of `@ultimat3/pwa`'s `generateServiceWorker`, which had none outside its own package
+// until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
+// file, this one needs a booted app and a finished build.
+
+import type { PrecacheAsset, PrecacheManifest, PwaRoute } from '@ultimat3/pwa';
+import { generateServiceWorker } from '@ultimat3/pwa';
+import type { RouteDescriptor } from '@ultimat3/render';
+import type { IslandBundle } from './island-bundle';
+import { msg } from './messages';
+import type { PwaArtifacts } from './pwa-artifacts';
+
+/** Root scope, so `/sw.js` and nothing under a directory — `assertScope` refuses the rest. */
+export const SERVICE_WORKER_PATH = '/sw.js';
+export const SW_SCOPE = '/';
+
+/**
+ * The registration is an EXTERNAL script, never inline, and that is a CSP fact rather than a
+ * preference: `startWeb` computes a `script-src` sha256 for each inline script it serves, so an
+ * unhashed one is blocked in the container while passing report-only under `x dev` — which is
+ * exactly how the hydration runtime shipped broken once already.
+ */
+export const SW_REGISTER_PATH = '/x-sw-register.js';
+
+export interface ServiceWorkerArtifacts {
+  /** `sw.js`, deterministic for identical input. */
+  readonly source: string;
+  /** `x-sw-register.js`, the four lines that install it. */
+  readonly register: string;
+  /** The `<script src>` tag, appended to `PwaArtifacts.head` by every surface that serves it. */
+  readonly head: string;
+  readonly precache: PrecacheManifest;
+  /** Precache budget findings — reported by `x build`, so the ceiling is not a designed thing. */
+  readonly warnings: readonly string[];
+}
+
+export interface ServiceWorkerInput {
+  /**
+   * What `loadPwaArtifacts` read out of `app.config.ts`. The whole object rather than three loose
+   * fields, because a second reader of that file is a second answer to what the app declared.
+   */
+  readonly pwa: PwaArtifacts;
+  readonly buildId: string;
+  readonly routes: readonly RouteDescriptor[];
+  readonly islands: IslandBundle;
+}
+
+/**
+ * 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.
+ */
+const pwaRoutes = (routes: readonly RouteDescriptor[]): 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.
+  routes.flatMap((route): 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 [];
+    return [
+      {
+        path: route.path,
+        surface: route.surface,
+        mode: route.mode,
+        offline: route.offline,
+        dynamic: route.dynamic,
+      },
+    ];
+  });
+
+/**
+ * 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.
+ *
+ * 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]
+    .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));
+
+/**
+ * Four lines, and every one of them earns it. `load` because registration competes with the page's
+ * own first paint for the same network. `scope: '/'` stated rather than inferred, so a change to
+ * where the file is served is a build-time refusal (`assertScope`) instead of a worker that
+ * silently controls a subdirectory. The `catch` because a registration that throws in a browser
+ * with service workers disabled — an incognito profile, an enterprise policy — must not take an
+ * otherwise working page down with it.
+ */
+const registerSource = (): string =>
+  `if ('serviceWorker' in navigator) {
+  addEventListener('load', function () {
+    navigator.serviceWorker
+      .register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: ${JSON.stringify(SW_SCOPE)} })
+      .catch(function (error) { console.warn('service worker registration failed', error); });
+  });
+}
+`;
+
+/**
+ * Build the worker, or answer `undefined` for an app that declared no PWA.
+ *
+ * A bad `sw.js` is sticky in a way a manifest is not: a manifest a browser dislikes is ignored, a
+ * worker that installs and caches wrong keeps serving wrong bytes until the user clears site data.
+ * That is why this landed only once a real browser could be driven —
+ * `packages/cli/e2e/service-worker.e2e.test.ts` installs the emitted worker in Chrome, takes the
+ * network away and asserts the fallback renders.
+ *
+ * `pwa.enabled` is the one switch, and it is already spent: `loadPwaArtifacts` answers `undefined`
+ * for an app that declared no PWA, so a caller only reaches this with an installable one.
+ * `defineConfig` refuses `enabled: true` without an absolute `offline.fallback`, and a
+ * hand-written config that lacks one reads as `null` here — so `requireOfflineFallback` inside
+ * `generateServiceWorker` can never be the thing that fails, and the app gets no worker rather
+ * than a worker caching a path nobody declared.
+ */
+export function serviceWorkerArtifacts(
+  input: ServiceWorkerInput,
+): ServiceWorkerArtifacts | undefined {
+  const pwa = input.pwa;
+  if (pwa.offline.fallback === null) return undefined;
+  const output = generateServiceWorker(
+    pwaRoutes(input.routes),
+    {
+      scope: SW_SCOPE,
+      swPath: SERVICE_WORKER_PATH,
+      offline: {
+        fallback: pwa.offline.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),
+    },
+    input.buildId,
+  );
+  return {
+    source: output.source,
+    register: registerSource(),
+    head: `<script src="${SW_REGISTER_PATH}" defer></script>`,
+    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
+    // one thing the generator cannot say: `generateServiceWorker` emits a push handler only when a
+    // VAPID key comes with the capability, and drops it in SILENCE otherwise. `pwa.push: true` in
+    // an `app.config.ts` therefore wires nothing and reports nothing, which is `jobs.driver`'s
+    // shape one package over.
+    warnings: [...output.warnings, ...pushWarning(pwa)],
+  };
+}
+
+/**
+ * `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
+ * does nothing is the defect this framework keeps re-shipping, and a warning naming the missing
+ * half is the smallest honest answer until the key exists.
+ */
+const pushWarning = (pwa: PwaArtifacts): readonly string[] =>
+  pwa.push ? [msg('cli.build.pushUnwired')] : [];

package/src/sw-routes.ts

@@ -0,0 +1,53 @@
+// The two GET routes that serve what `sw-artifacts.ts` built, and the cache policy each one needs.
+// Split from the emitter because mounting is HTTP and generation is a build: `prerender.ts` writes
+// both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
+
+import type { CacheHint, Route } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import type { ServiceWorkerArtifacts } from './sw-artifacts';
+import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
+
+/**
+ * `no-store`, and it is the one asset here that must be. A cached `sw.js` is a worker that cannot
+ * be replaced: the browser re-fetches it to decide whether an update exists, and an intermediary
+ * answering the old bytes pins every client to the deploy that shipped them. Browsers cap SW
+ * script caching at 24h on their own; this removes the question.
+ */
+const SW_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
+
+/** Content-addressed in neither path, so the register script gets the favicon's hour. */
+const REGISTER_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/** `/sw.js` and `/x-sw-register.js`, mounted by `x dev` and by the container alike. */
+export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly Route[] => [
+  {
+    method: 'GET',
+    path: SERVICE_WORKER_PATH,
+    meta: { name: 'pwa.serviceWorker', auth: 'public' },
+    handler: () =>
+      applyCacheHeaders(
+        new Response(artifacts.source, {
+          headers: {
+            'content-type': 'text/javascript; charset=utf-8',
+            // Without it the browser refuses to let a worker served from `/` control `/`, which
+            // is the failure `assertScope` cannot see: the scope a REGISTRATION asks for has to be
+            // allowed by the script's own response, not only by its path.
+            'service-worker-allowed': SW_SCOPE,
+          },
+        }),
+        SW_CACHE,
+      ),
+  },
+  {
+    method: 'GET',
+    path: SW_REGISTER_PATH,
+    meta: { name: 'pwa.serviceWorkerRegister', auth: 'public' },
+    handler: () =>
+      applyCacheHeaders(
+        new Response(artifacts.register, {
+          headers: { 'content-type': 'text/javascript; charset=utf-8' },
+        }),
+        REGISTER_CACHE,
+      ),
+  },
+];

package/src/templates/naming.ts

@@ -79,6 +79,17 @@ export const plural = (input: string): string => {
 
 export const titleKey = (input: string): string => `app.${kebab(input)}.title`;
 
+/**
+ * A human title from a slug: `ledger-demo` -> `Ledger Demo`. Its one caller is the scaffolded
+ * `pwa.name`, which is what a browser shows a person in the install prompt — `app.name` is a slug
+ * by `NAME_RE` and `pascal` would offer to install `LedgerDemo`. Not a `NameSet` member: every
+ * other field there names a code identifier, and this one is prose.
+ */
+export const titleCase = (input: string): string =>
+  words(input)
+    .map((word) => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`)
+    .join(' ');
+
 export interface NameSet {
   readonly raw: string;
   readonly kebab: string;

package/src/templates/scaffold-app.ts

@@ -190,16 +190,63 @@ unitTest('the dashboard renders on the server, is gated, and has an offline stra
 });
 `;
 
+const offlineTest =
+  (): string => `// The offline fallback has to render with nothing: no network, no session, no database, and no
+// JavaScript. Every one of those is a config field here, and every one of them rots the moment
+// someone adds an import or a policy — at which point the page the service worker precaches is a
+// page that cannot render when it is finally needed.
+import { metaContextFor, routeDataFor } from '@ultimat3/render';
+import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+const ctx = { params: {}, url: 'https://example.test/offline' };
+
+unitTest('the offline fallback is static, precached, and ships no JavaScript', async () => {
+  expect(config.render).toBe('static');
+  // 'precache', or the document that answers a lost network is itself fetched over the network.
+  expect(config.offline).toBe('precache');
+  expect(config.hydrate).toBe('never');
+  expect(config.budget.js).toBe('0kb');
+  // A cached error page has nothing to index, and an indexed one outranks the page it stood in for
+  // on the day the crawler happened to be offline.
+  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
+  expect(meta.robots?.index).toBe(false);
+});
+`;
+
 const offlineFallback = (
   app: NameSet,
-): string => `// The offline fallback. Every app/ route with offline: 'runtime' falls back here, so a train
-// tunnel shows the product's own shell instead of the browser's error page.
+): string => `// The offline fallback, and it is a ROUTE — \`pwa.offline.fallback\` in app.config.ts names this
+// path, the generated sw.js precaches it, and every app/ route with offline: 'runtime' falls back
+// here. So a train tunnel shows the product's own shell instead of the browser's error page.
+//
+// site/ and render: 'static', deliberately: the document that answers a lost network has to render
+// with no network, no session and no database, which is what site/ guarantees and app/ (ssr |
+// stream) cannot. \`offline: 'precache'\` for the same reason one level down — a fallback fetched
+// over the network when the network is gone is not a fallback.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import styles from './offline.module.scss';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  offline: 'precache',
+  hydrate: 'never',
+  budget: { js: '0kb' },
+  meta: ({ t }) => ({
+    title: t('app.offline.title'),
+    description: t('app.offline.description'),
+    // A cached error page has nothing to index, and an indexed one outranks the page it stood in
+    // for on the day the crawler happened to be offline.
+    robots: { index: false },
+  }),
+});
 
-export function OfflineFallback() {
+export function OfflinePage() {
   const t = useT();
 
   return (
@@ -390,8 +437,12 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // policy and `shared/roles.ts` declares the grants, and until this file existed nothing
     // answered "who is this?" — so every one of those routes refused every request.
     ...authFiles(app),
-    { path: 'apps/web/app/offline.tsx', contents: offlineFallback(app) },
-    { path: 'apps/web/app/offline.module.scss', contents: offlineStyle() },
+    // `site/offline/page.tsx`, not `app/offline.tsx`: the directory is the URL and `<name>.tsx` is
+    // not a route file, so the old path shipped a component nothing rendered and left `/offline` a
+    // URL the generated service worker could not fall back to.
+    { path: 'apps/web/site/offline/page.tsx', contents: offlineFallback(app) },
+    { path: 'apps/web/site/offline/page.module.scss', contents: offlineStyle() },
+    { path: 'apps/web/site/offline/page.test.ts', contents: offlineTest() },
     // The third surface, and the one call that registers what the app declares — `scaffold-api.ts`.
     ...apiFiles(example),
     { path: 'apps/web/shared/tokens.scss', contents: sharedTokens() },

package/src/templates/scaffold-repo.ts

@@ -8,6 +8,7 @@ import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
 import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
+import { titleCase } from './naming';
 import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
@@ -180,7 +181,22 @@ export const config = defineConfig({
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, transport: 'memory' },
-  pwa: { enabled: true, offline: 'runtime' },
+  // \`name\` and \`colors\` are what an install prompt shows and what a browser paints the splash
+  // with before any stylesheet has loaded — the four values the framework cannot derive, so
+  // \`defineConfig\` refuses \`pwa.enabled: true\` without them. Raw hex is legal here and nowhere
+  // else in an app.
+  pwa: {
+    enabled: true,
+    // The document an offline navigation gets when the cache has no answer, and the path
+    // \`apps/web/site/offline/page.tsx\` serves. Required once \`enabled\` is true: an installable
+    // app that shows the browser's error page offline is the failure the block exists to prevent.
+    offline: { fallback: '/offline' },
+    name: '${titleCase(app.raw)}',
+    colors: {
+      light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' },
+      dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' },
+    },
+  },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
 `;