@ultimat3/cli 18.0.0 → 19.1.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/entity.ts

@@ -27,6 +27,13 @@ import { entity, invariant, money, text, timestamp, uuid } from '@ultimat3/entit
 export const ${name.camel} = entity('${table}', {
   // Naming the tenant column is what turns tenancy on: a read without an org predicate then
   // fails with X_TENANCY_UNSCOPED instead of leaking another org's rows.
+  //
+  // SINGLE-TENANT APP? There is no flag: \`x g action\`, \`x g query\` and \`x g policy\` decide on
+  // \`orgId\` too, so the edit is per slice and it is this: delete \`tenant: 'orgId'\` and the
+  // \`orgId: uuid()\` column below, drop \`'orgId'\` from \`indexes\`, and in repo.ts turn
+  // \`listByOrg(orgId, limit)\` into \`list(limit)\` with no \`org_id\` predicate and no \`org_id\` in
+  // the insert. entity.test.ts then expects \`$tenantColumn\` null and \`orgScoped\` false, and its
+  // \`row()\` fixture loses \`orgId\`. Nothing else reads the column.
   tenant: 'orgId',
   columns: {
     id: uuid().primaryKey(),

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

@@ -187,7 +187,10 @@ export const config = defineConfig({
   // else in an app.
   pwa: {
     enabled: true,
-    offline: 'runtime',
+    // 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' },

package/src/ts-scan.ts

@@ -30,120 +30,17 @@ export interface CodeScan {
   readonly unresolved: readonly UnresolvedCodeSite[];
 }
 
+// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — lives in
+// `@ultimat3/core`'s `source-mask.ts` since 2026-09-05, because `@ultimat3/i18n`'s key extractor
+// (tier 1) needed it and could not reach a tier-5 package. Re-exported here so every scanner in
+// this package, and this package's public API, keep the names they had.
+import { endOfLiteral, maskLiterals, QUOTES, stripComments } from '@ultimat3/core';
+
+export { endOfLiteral, maskLiterals, QUOTES, stripComments };
+
 // `ReadonlySet`, so a consumer cannot mutate what every scan in this package reads.
-export const QUOTES: ReadonlySet<string> = new Set(["'", '"', '`']);
 export const OPENERS: ReadonlySet<string> = new Set(['(', '[', '{']);
 export const CLOSERS: ReadonlySet<string> = new Set([')', ']', '}']);
-const WORD = /[\w$]/;
-
-/** After one of these words a `/` opens a regex; after any other identifier it divides. */
-const REGEX_AFTER_WORDS = new Set(
-  'await case delete do else in instanceof new of return throw typeof void yield'.split(' '),
-);
-
-/**
- * Index just past the closing quote of the literal opening at `from`, or `from + 1` when a `'`/`"`
- * does not close on its own line — which makes it text, not a literal. Only a template literal may
- * span a newline, so the apostrophe in `<p>Don't panic</p>` is JSX text; read as an opener it ran
- * forward to the next `'` in the FILE (the next `fix:` line) and blanked every declaration between,
- * silently emptying the `errors` gate for the whole file. Same rule `endOfRegex` applies to a `/`.
- * An escaped newline is still a continuation: the escape is consumed before the line test.
- */
-export function endOfLiteral(text: string, from: number): number {
-  const quote = text[from] as string;
-  const spansLines = quote === '`';
-  for (let i = from + 1; i < text.length; i += 1) {
-    if (text[i] === '\\') i += 1;
-    else if (text[i] === quote) return i + 1;
-    else if (!spansLines && text[i] === '\n') return from + 1;
-  }
-  return spansLines ? text.length : from + 1;
-}
-
-/**
- * Whether the `/` at `at` opens a regex rather than divides — the call no scanner without a parser
- * avoids. A regex cannot follow what ends an expression: an identifier that is not one of the words
- * above, a number, `)`, `]`, a string's closing quote. Every other position is an operator's and
- * opens one; `</` and `/>` are JSX delimiters. Read from the masked prefix, so a comment is space.
- */
-function opensRegex(out: readonly string[], at: number): boolean {
-  if (out[at + 1] === '>') return false;
-  let i = at - 1;
-  while (i >= 0 && /\s/.test(out[i] as string)) i -= 1;
-  if (i < 0) return true;
-  const ch = out[i] as string;
-  if (ch === '<' || ch === ')' || ch === ']' || QUOTES.has(ch)) return false;
-  if (!WORD.test(ch)) return true;
-  let start = i;
-  while (start >= 0 && WORD.test(out[start] as string)) start -= 1;
-  return REGEX_AFTER_WORDS.has(out.slice(start + 1, i + 1).join(''));
-}
-
-/**
- * Index just past the closing `/` of the regex opening at `from`, or `from + 1` when it does not
- * close on its own line — a literal may not span one, so an unterminated candidate was a division
- * or a JSX delimiter after all. A `/` inside a `[…]` class does not close the literal.
- */
-function endOfRegex(text: string, from: number): number {
-  let inClass = false;
-  let escaped = false;
-  for (let i = from + 1; i < text.length; i += 1) {
-    const ch = text[i];
-    if (ch === '\n') break;
-    if (escaped) escaped = false;
-    else if (ch === '\\') escaped = true;
-    else if (inClass) inClass = ch !== ']';
-    else if (ch === '[') inClass = true;
-    else if (ch === '/') return i + 1;
-  }
-  return from + 1;
-}
-
-/**
- * Comments — and optionally string contents — replaced by spaces, newlines kept so line numbers
- * survive and quote delimiters kept so the caller can still find where a literal starts and ends.
- * A regex body is masked the same way: `/(['"`])/` holds three quotes that delimit nothing, and
- * reading one as an opening quote desyncs every literal after it.
- */
-function blankRegions(text: string, strings: boolean): string {
-  // `split('')` and NOT `[...text]`: the spread yields one element per CODE POINT while every
-  // index below runs over UTF-16 units (`text.length`, `text[i]`). One astral character — an emoji
-  // in a fixture, `piñata 🎉` — and `out` is shorter than `text`, so every write past it lands a
-  // slot early and the returned mask no longer aligns with the input. Measured: 22 files in this
-  // tree desynced, shipped source included, and eight rules read this mask.
-  const out = text.split('');
-  const blank = (from: number, to: number): void => {
-    for (let n = from; n < to; n += 1) if (out[n] !== '\n') out[n] = ' ';
-  };
-  let i = 0;
-  while (i < text.length) {
-    const ch = text[i] as string;
-    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
-      const line = text[i + 1] === '/';
-      const end = line ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
-      const stop = end === -1 ? text.length : line ? end : end + 2;
-      blank(i, stop);
-      i = stop;
-      continue;
-    }
-    // Not code: a regex body or a literal. `end === i + 1` blanks nothing and steps one char.
-    const end =
-      ch === '/' && opensRegex(out, i)
-        ? endOfRegex(text, i)
-        : QUOTES.has(ch)
-          ? endOfLiteral(text, i)
-          : i + 1;
-    if (strings) blank(i + 1, end - 1);
-    i = end;
-  }
-  return out.join('');
-}
-
-/** Comments gone, string literals intact — what a scan for declared codes reads. */
-export const stripComments = (text: string): string => blankRegions(text, false);
-
-/** Comments and string contents gone, delimiters kept — what a scan for code structure reads. */
-export const maskLiterals = (text: string): string => blankRegions(text, true);
 
 /**
  * Line numbers for one text, in one pass. Counting newlines per lookup is O(index), which a scan