@ultimat3/cli 10.0.0 → 11.1.0

package/src/live-routes.ts

@@ -0,0 +1,181 @@
+// One question only this package can ask: a route SUBSCRIBES to live rows, and does anything on
+// that route ever run in a browser to receive them? `@ultimat3/realtime` cannot see a route and
+// `@ultimat3/render` may not import realtime, so the two halves meet here — beside the island
+// build, which is the other place the route table and the client graph are both in scope.
+//
+// The failure it closes is silent by construction (#271): with no island the page server-renders
+// its `loading` branch, answers 200, and stays that way forever — nothing throws, nothing logs,
+// and every suite passes.
+
+// why: Bun exposes no path API, and a route file's imports are resolved against its own directory.
+import { join, posix } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { RouteEntry } from '@ultimat3/render';
+import { ISLAND_EXTENSION, routeEntries } from '@ultimat3/render';
+import type { Finding } from './output';
+
+/**
+ * The exports that only work with a registered `LiveClient`. Each one either subscribes, mutates
+ * or reads the connection, so a module naming one is a module that needs a browser to have booted
+ * it — `hasLiveClient` and `LiveClient` itself are deliberately absent: the first IS the guard, and
+ * the second is what an island's `mount()` constructs.
+ */
+export const LIVE_HOOKS = [
+  'useLive',
+  'liveHookFor',
+  'useConnection',
+  'useMutation',
+  'useMutationQueue',
+] as const;
+
+/**
+ * The one escape hatch, and it is a call an author writes on purpose: a module that ASKS whether
+ * there is a client has already written what happens when there is none. `app/update-banner.tsx`
+ * in the reference app is the shape — imported by the layout, so by every page, and correct on all
+ * of them.
+ */
+const GUARD = 'hasLiveClient';
+
+/** Value imports only: `import type` is erased, so it boots nothing and needs nothing. */
+const REALTIME_IMPORT = /import\s+([^;]*?)from\s*['"]@ultimat3\/realtime(?:\/[\w-]+)?['"]/g;
+
+const bindingsOf = (clause: string): readonly string[] =>
+  (/\{([^}]*)\}/.exec(clause)?.[1] ?? '')
+    .split(',')
+    .map((entry) => entry.split(/\bas\b/)[0]?.trim() ?? '')
+    .filter((name) => name.length > 0 && !name.startsWith('type '));
+
+/**
+ * Which live hooks one module imports, or `[]` — including for a module that guards, which is a
+ * per-FILE verdict on purpose: the guard is written next to the read it protects.
+ */
+export function liveHooksIn(source: string): readonly string[] {
+  const hooks: string[] = [];
+  for (const match of source.matchAll(REALTIME_IMPORT)) {
+    const clause = match[1] ?? '';
+    if (clause.trimStart().startsWith('type ')) continue;
+    const names = bindingsOf(clause);
+    if (names.includes(GUARD)) return [];
+    for (const hook of LIVE_HOOKS) if (names.includes(hook)) hooks.push(hook);
+  }
+  return hooks;
+}
+
+/** What a relative specifier can be on disk. The list `fix-imports.ts` already resolves against. */
+const candidates = (base: string): readonly string[] => [
+  `${base}.ts`,
+  `${base}.tsx`,
+  `${base}/index.ts`,
+  `${base}/index.tsx`,
+];
+
+async function readModule(
+  root: string,
+  file: string,
+): Promise<{ path: string; source: string } | undefined> {
+  for (const path of file.endsWith('.ts') || file.endsWith('.tsx') ? [file] : candidates(file)) {
+    const handle = Bun.file(join(root, path));
+    if (await handle.exists()) return { path, source: await handle.text() };
+  }
+  return undefined;
+}
+
+/** Where a route's graph first reaches a live hook. */
+export interface LiveReach {
+  /** App-root-relative module that imports it. */
+  readonly at: string;
+  readonly hook: string;
+}
+
+/**
+ * Walk the route module's own import graph and answer the first live hook in it.
+ *
+ * Relative specifiers only. A bare one resolves through `node_modules` or a workspace name, and
+ * following either would mean guessing which package a name came from — the limit `fix-imports.ts`
+ * records for the same walk. So this UNDER-reports rather than over-reports: a finding here is
+ * always a real one, which is what lets the rule ship with no pin table.
+ */
+export async function liveReachOf(root: string, file: string): Promise<LiveReach | undefined> {
+  const seen = new Set<string>();
+  const queue = [file];
+  while (queue.length > 0) {
+    const next = queue.shift();
+    if (next === undefined || seen.has(next)) continue;
+    seen.add(next);
+    const module = await readModule(root, next);
+    if (module === undefined) continue;
+    const hook = liveHooksIn(module.source)[0];
+    if (hook !== undefined) return { at: module.path, hook };
+    const loader = module.path.endsWith('x') ? 'tsx' : 'ts';
+    // Bun's transpiler is the parser, exactly as in `scripts/boundaries.ts`: it erases type-only
+    // imports and finds the dynamic ones, which no regex over this source could do.
+    for (const scanned of new Bun.Transpiler({ loader }).scanImports(module.source)) {
+      if (!scanned.path.startsWith('.')) continue;
+      queue.push(posix.normalize(posix.join(posix.dirname(module.path), scanned.path)));
+    }
+  }
+  return undefined;
+}
+
+export interface LiveRouteGap extends LiveReach {
+  readonly route: string;
+  readonly file: string;
+  /** What the route declares. `'never'` is the second way nothing boots. */
+  readonly hydrate: string;
+  readonly islands: readonly string[];
+}
+
+/** The `x g island` invocation that fixes it, built from this route's own file — never a placeholder. */
+const generatorFor = (file: string): string => {
+  const dir = posix.dirname(file);
+  return `x g island ${posix.basename(dir)} --at ${dir}`;
+};
+
+/**
+ * Every route that reads live rows with nothing to receive them. Two shapes, one condition — no
+ * island at all, and an island the route declares `hydrate: 'never'` for. `X_ISLAND_NOT_HYDRATED`
+ * covers the second only at render time, and only for a render that reaches the island, so a route
+ * can hold the contradiction and never be asked.
+ */
+export async function liveRouteGaps(
+  root: string,
+  entries: readonly RouteEntry[],
+): Promise<readonly LiveRouteGap[]> {
+  const gaps: LiveRouteGap[] = [];
+  for (const entry of entries) {
+    if (entry.surface === 'api') continue;
+    if (entry.islands.length > 0 && entry.config.hydrate !== 'never') continue;
+    const reach = await liveReachOf(root, entry.file);
+    if (reach === undefined) continue;
+    gaps.push({
+      ...reach,
+      route: entry.path,
+      file: entry.file,
+      hydrate: entry.config.hydrate,
+      islands: entry.islands,
+    });
+  }
+  return gaps;
+}
+
+export const liveRouteFindingFor = (gap: LiveRouteGap): Finding => ({
+  code: 'X_LIVE_ROUTE_NO_ISLAND',
+  cause:
+    `${gap.route} reads ${gap.hook}() (${gap.at}) and ` +
+    (gap.islands.length === 0
+      ? 'declares no island'
+      : `declares hydrate: 'never' beside ${gap.islands.join(', ')}`) +
+    ', so no module of this route ever runs in a browser: its rows have nowhere to arrive and the page renders its loading branch forever, at 200',
+  fix:
+    `${generatorFor(gap.file)}, declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) above defineRoute in ${gap.file}, ` +
+    `and move the ${gap.hook}() read into its mount() — which is where setLiveClient() can be called`,
+  docs: ERROR_DOCS_URL,
+  at: gap.at,
+});
+
+/**
+ * What this rule contributes to `x verify`'s `budgets` step — the step that already loaded the app
+ * and already asks what JavaScript a route's document boots.
+ */
+export const liveRouteFindings = async (root: string): Promise<readonly Finding[]> =>
+  (await liveRouteGaps(root, routeEntries())).map(liveRouteFindingFor);

package/src/mcp-errors.ts

@@ -48,6 +48,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_JOB_UNKNOWN: 'x jobs ls --json',
   X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
   X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
+  X_ERROR_FIX_PATH_MISSING:
+    'x verify --json   # the finding names the fix line and the path it cites',
   X_WORKSPACE_DEP_UNDECLARED:
     'x verify --json   # the package-shape finding carries the dependency line to add',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
@@ -60,6 +62,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_ERROR_CODE_UNDOCUMENTED: 'x verify --json   # the finding names the code and the missing page',
   X_ERROR_CODE_UNREGISTERED:
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
+  X_ERROR_CODE_UNRESOLVED:
+    'x verify --json   # the finding names the file, the line and the name it could not resolve',
   X_CLI_UNEXPECTED: 'x doctor --json',
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',
@@ -89,6 +93,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // this fix builds an image, writes no `.x/build-stats.json`, and the next `x verify` reports the
   // same code. Byte-identical to `checkBudgets`'s own finding, which is the other half of the pair.
   X_BUDGET_UNMEASURED: 'x build --target static --json && x verify --json',
+  // `x routes` first, because the finding is about a ROUTE and the table names its file and its
+  // islands; the generator that fixes it takes the directory that table just printed.
+  X_LIVE_ROUTE_NO_ISLAND: 'x routes --json   # then: x g island <route-dir> --at <route-dir>',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
   X_BUILD_ENTRY_MISSING:
     'x new scratch-app --dry-run --json   # the file list names every entry a build needs',

package/src/messages.ts

@@ -135,10 +135,12 @@ const CATALOG = {
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  // `x db gen "initial"` is a first step, not an optional one: the scaffold writes no migration, so
-  // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
-  'cli.new.done':
-    'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
+  // `bin/setup` and nothing else: the scaffold ships it, `README.md` and `bin/check` both name it,
+  // and it is the only spelling that is right on a fresh clone — it installs, writes
+  // `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no migration, so the
+  // drift step is red until it has), migrates and seeds. The four-command line this replaced named
+  // `x dev` off a tree where nothing had installed the CLI yet, and skipped the seed entirely.
+  'cli.new.done': 'created {name} — next: cd {name} && bin/setup && x dev',
   // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
   // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
   // command is a broken one — the same split `Finding.fix` already makes.

package/src/prerender.ts

@@ -13,6 +13,8 @@ import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
+import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
+import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
@@ -95,6 +97,9 @@ function heaviestSource(
 
 export const DEFAULT_ORIGIN = 'https://localhost';
 
+/** The one status a static export can answer for itself: a path that matches no file. */
+const NOT_FOUND_STATUS = 404;
+
 /**
  * Prerendering and measuring are two questions, and conflating them made `X_BUDGET_UNMEASURED`
  * unclosable by any invocation: only `static` was ever rendered, so a `budget:` on an ssr, isr,
@@ -127,6 +132,21 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // behind it, so the artifact carries every byte the browser will ask for.
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
+  // Same rule, one asset further: a browser asks for `/favicon.ico` on the first page it loads,
+  // and a static export has no route to answer it — so the bytes the served surfaces would have
+  // returned go into the artifact instead of leaving a 404 in every visitor's console.
+  await Bun.write(
+    join(options.out, FAVICON_PATH.slice(1)),
+    (await faviconBytes(options.root)).bytes,
+  );
+  // And the one error page a static host serves ITSELF: `404.html` at the export root is what S3,
+  // Cloudflare Pages, Netlify and nginx all reach for when a path matches no file. The app's own
+  // file if it wrote one, the framework's page otherwise — the same two rungs the served process
+  // answers a 404 with, so the artifact and the server cannot disagree about one document.
+  await Bun.write(
+    join(options.out, STATIC_ERROR_PAGE),
+    await errorPageDocument(options.root, NOT_FOUND_STATUS),
+  );
 
   // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
   // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
@@ -186,6 +206,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       skipped.push(skippedRoute(facts, 'no-prerender-paths'));
       continue;
     }
+    // One stats row per ROUTE, holding its heaviest page. `checkBudgets` looks a route up by
+    // `route.url`, which is the manifest's DECLARED pattern (`/blog/:slug`), and this pushed the
+    // FILLED path (`/blog/hello`) — so no dynamic static route has ever been weighed: every one
+    // was `X_BUDGET_UNMEASURED` and `X_BUDGET_EXCEEDED` could not fire for the whole class. The
+    // heaviest page and not the first, because a budget is a ceiling: the page that breaks it is
+    // the one the route has to answer for. `pages` below still names every filled path.
+    let heaviest: RouteStats | undefined;
     for (const artifact of artifacts) {
       const file = join(options.out, artifact.outputPath);
       const bytes = await Bun.write(file, artifact.html);
@@ -200,12 +227,14 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
       const chain = heaviestSource(islands, measured.entries);
-      routes.push({
-        path: artifact.path,
+      if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
+      heaviest = {
+        path: entry.path,
         jsBytes: measured.jsBytes,
         ...(chain === undefined ? {} : { heaviestChain: chain }),
-      });
+      };
     }
+    if (heaviest !== undefined) routes.push(heaviest);
   }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does

package/src/script-csp.ts

@@ -0,0 +1,17 @@
+// Every inline `<script>` body a served process can put in a document, as the `script-src` sources
+// that admit it. The mirror of `style-csp.ts`, and needed for the same reason: `script-src` was
+// `'self' 'wasm-unsafe-eval'` while every document carrying an island shipped the hydration runtime
+// INLINE, so under the enforced policy a container serves (`dev: false`) no island ever booted —
+// invisible in `x dev`, where the policy is report-only.
+
+import { cspHashSource } from '@ultimat3/http';
+import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
+
+/**
+ * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
+ * reach it. Read from `@ultimat3/render`'s own enumeration rather than restated here — the body
+ * the document carries and the body the policy hashes have to be one string.
+ */
+export function inlineScriptSources(): readonly string[] {
+  return [...new Set(HYDRATE_RUNTIME_BODIES.map(cspHashSource))].sort();
+}

package/src/serve.ts

@@ -328,6 +328,9 @@ async function bootRoles(boot: {
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
+    // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
+    // process and `x dev` cannot answer a browser differently.
+    root: options.root,
     http: CONTAINER_BINDING,
     ...(options.runtime === undefined ? {} : { overrides: options.runtime }),
   });
@@ -367,6 +370,14 @@ export async function runRole(options: ServeOptions): Promise<StartedApp> {
   }
   const app = await serveApp({ ...options, role });
   logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
-  await holdUntilShutdown('serve', () => app.stop())();
+  // `exit` because this is the one entry point with nothing above it: `bin.ts` ends in
+  // `process.exit(code)` and `apps/web/server.ts` — which is what awaits this — does not. One
+  // non-unref'd interval anywhere in the app then holds an event loop that has nothing left to do,
+  // until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs a drained process.
+  await holdUntilShutdown('serve', () => app.stop(), {
+    exit: (code) => {
+      process.exit(code);
+    },
+  })();
   return app;
 }

package/src/templates/admin-page.ts

@@ -5,6 +5,7 @@
 // declaration here would hand back the unguarded second way in that seam exists to close.
 
 import { catalogJson } from './catalog-json';
+import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
@@ -47,15 +48,18 @@ const catalogImport = (module: string | undefined): string =>
 /**
  * The two imports, in the order biome's organize-imports wants — which DEPENDS on the app's scope
  * and cannot be hardcoded either way. An app catalog (`@myapp/i18n`) sorts BEFORE
- * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it. Emitting one fixed order makes
- * every generated admin page a lint error in exactly one of the two cases, and each case is
- * covered by a different job — the fallback by `templates`' own linter test, the app-scoped one
- * only by `scaffold-smoke`, which runs the generators against a real scaffold.
+ * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it, and `@zebra/i18n` after that.
+ * Emitting one fixed order makes every generated admin page a lint error in one of those cases.
+ *
+ * `sortedImports` is this sort, moved to `templates/imports.ts` so the four scaffold sites that
+ * had the same mix and none of the fix share it — `x new zebra` was four `organizeImports` errors
+ * on its first `x verify`.
  */
 const pageImports = (module: string | undefined): string =>
-  [`import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`, catalogImport(module)]
-    .sort((a, b) => (a.slice(a.indexOf("'")) < b.slice(b.indexOf("'")) ? -1 : 1))
-    .join('\n');
+  sortedImports([
+    `import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`,
+    catalogImport(module),
+  ]);
 
 /** `useT()` is per render, so the component binds it in its own body. */
 const translatorBinding = (module: string | undefined): string =>

package/src/templates/imports.ts

@@ -0,0 +1,26 @@
+// The order Biome's `organizeImports` wants for a generated file — COMPUTED, because it depends on
+// the app's own scope and no fixed order can be right for every app.
+//
+// `import { useT } from '@myapp/i18n'` sorts BEFORE `@ultimat3/render`; `@zebra/i18n` sorts after
+// it. Every template wrote one fixed order, so `x new zebra` scaffolded four files Biome refuses
+// (`assist/source/organizeImports`, measured: `apps/web/site/page.tsx`,
+// `apps/web/app/dashboard/page.tsx`, `apps/admin/app/admin/page.tsx`, `packages/mcp/src/index.ts`)
+// and the app's very first `x verify` was red on its `lint` step. `x new alpha` was clean, which is
+// why nothing caught it: both CI fixtures — `demoapp` and `bareapp` — sort before `ultimat3`.
+//
+// `templates/admin-page.ts` already did this by hand for its two lines; this is that sort, in one
+// place, for every generator that mixes an app specifier with a framework one.
+
+/** The quoted specifier a line imports from — the only thing Biome orders these lines by. */
+const specifierOf = (line: string): string => line.slice(line.indexOf("'"));
+
+/**
+ * One import block, sorted the way Biome would sort it.
+ *
+ * BARE specifiers only (`@myapp/i18n`, `@ultimat3/render`, `solid-js`). A relative specifier
+ * (`./page.module.scss`) belongs to a LATER group and sorts before every `@` by plain string
+ * compare, so passing one here would emit the block Biome then moves — the exact defect this
+ * exists to end. Templates write those lines after the block, where they already are.
+ */
+export const sortedImports = (lines: readonly string[]): string =>
+  [...lines].sort((a, b) => (specifierOf(a) < specifierOf(b) ? -1 : 1)).join('\n');

package/src/templates/route.ts

@@ -5,6 +5,7 @@
 // fallback is a blank screen on a train.
 
 import { catalogJson } from './catalog-json';
+import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { kebab, pascal, titleKey } from './naming';
@@ -112,8 +113,7 @@ const pageSource = (surface: Surface, path: string, module: string | undefined):
   return `// Route: /${path} on the ${surface} surface. Config first: render mode, offline
 // strategy and budget are declarations, not runtime choices.
 
-${catalogImport(module)}
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([catalogImport(module), `import { defineRoute } from '@ultimat3/render';`])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({

package/src/templates/scaffold-app.ts

@@ -2,8 +2,10 @@
 // already speaks MCP, and the mobile/desktop placeholders that exist so adding them later is not
 // a restructure. Every file here is real, typed and covered — no placeholder that fails to boot.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
+import { authFiles } from './scaffold-auth';
 import { entryFiles } from './scaffold-entries';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
@@ -47,8 +49,10 @@ const sitePage = (
 // \`t\` in @ultimat3/i18n. That import is what puts the module holding \`defineCatalogs()\` in
 // this page's graph, so rendering a string is what registers the catalogs. A page that reached
 // past it shipped every string as \`\u27e6key\u27e7\` with \`x verify\` green (issue #249).
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({
@@ -126,8 +130,10 @@ const dashboardPage = (
 // as their data resolves.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({
@@ -323,8 +329,10 @@ const adminPage = (
 // user's agents can drive the user's product with the user's permissions.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 
 export const config = defineRoute({
   render: 'ssr',
@@ -377,6 +385,10 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage(app) },
     { path: 'apps/web/app/dashboard/page.module.scss', contents: dashboardStyle() },
     { path: 'apps/web/app/dashboard/page.test.ts', contents: dashboardTest() },
+    // The third piece of the authz story the scaffold already tells twice: the routes declare a
+    // 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() },
     // The third surface, and the one call that registers what the app declares — `scaffold-api.ts`.

package/src/templates/scaffold-auth.ts

@@ -0,0 +1,151 @@
+// The scaffold's answer to "who is this?", which it did not have.
+//
+// `hooks.authenticate` is the ONLY place an actor can come from, and nothing in a generated app
+// called `configureAuthenticator()` — so a fresh `x new` booted with
+// `X_CONFIG_INVALID: 7 route(s) declare auth: 'required' and no authenticator is configured` on
+// every start, and its own `/dashboard` answered 401 on the first click. The scaffold declares the
+// routes and the roles; this is the missing third piece, and it is deliberately the smallest one
+// that can be honest: a viewer named by a cookie, installed in `development` and nowhere else.
+//
+// The alternative — dropping `policy:` from the scaffolded routes — was refused: a dashboard that
+// declares no policy is registered `auth: 'public'`, which also skips `render-ssr`'s gated branch,
+// so the document ships with no `vary: cookie` and a shared cache may hand one visitor's page to
+// the next. The scaffold would teach the wrong shape to every app that starts from it.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const devActor = (
+  app: NameSet,
+): string => `// Who a browser is until this app issues sessions of its own.
+//
+// \`hooks.authenticate\` is the one place an actor can come from. Without it every request is
+// anonymous, so each route declaring a \`policy:\` answers 401 and the boot warns
+// \`X_CONFIG_INVALID\` — which is what a scaffolded app did on its very first \`x dev\`.
+//
+// DEVELOPMENT ONLY, and the guard is the point: a viewer that followed this to staging would sign
+// every visitor in as an admin. \`bun test\` sets \`NODE_ENV=test\`, so it does not install there
+// either — a fixture mints its own actor, and a second one arriving from a cookie would decide
+// which actor a test is about.
+//
+// REPLACE IT with the real thing: resolve a session cookie to a row, and return that actor.
+// Everything downstream — pages, policies, live subscribers, MCP tools — reads what this returns.
+import { type Actor, logger, tryResolveEnvironment } from '@ultimat3/core';
+import { configureAuthenticator, readCookie } from '@ultimat3/http';
+
+/** Set it to a role from \`apps/web/shared/roles.ts\` to browse as that role. */
+export const DEV_ROLE_COOKIE = '${app.kebab}_dev_role';
+
+/** The roles \`shared/roles.ts\` declares. A cookie naming anything else falls back. */
+export const DEV_ROLES = ['member', 'admin'] as const;
+
+export type DevRole = (typeof DEV_ROLES)[number];
+
+/** The one that can open every scaffolded route, including \`/admin\`. */
+export const DEFAULT_DEV_ROLE: DevRole = 'admin';
+
+const isDevRole = (value: string | null): value is DevRole =>
+  value !== null && (DEV_ROLES as readonly string[]).includes(value);
+
+/**
+ * An unknown cookie value falls back rather than refusing: the cookie is a viewing convenience,
+ * and a typo that resolved nobody would reproduce the 401 this module exists to remove.
+ */
+export const devRoleFrom = (cookieHeader: string | null): DevRole => {
+  const named = readCookie(cookieHeader, DEV_ROLE_COOKIE);
+  return isDevRole(named) ? named : DEFAULT_DEV_ROLE;
+};
+
+/**
+ * \`roles\`, never a permission list: \`can()\` expands the role map at decision time, so a grant
+ * moved between roles reaches this actor without an edit here.
+ */
+export const devActorFor = (role: DevRole): Actor => ({
+  kind: 'user',
+  id: 'dev-actor',
+  orgId: 'dev-org',
+  roles: [role],
+  // Both required, and both deliberately empty: \`scopes\` is the framework's own escape hatch
+  // (\`tenancy:cross\`) and \`permissions\` is a DIRECT grant that bypasses the role map — a
+  // development viewer holds exactly what its role holds, and nothing a rule cannot explain.
+  scopes: [],
+  permissions: [],
+});
+
+/**
+ * Installs it, and says so — loudly, because a silent stand-in for authentication is the one thing
+ * worse than none. Returns whether it installed, so the test can assert both halves.
+ */
+export function installDevAuthenticator(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (tryResolveEnvironment({ env }) !== 'development') return false;
+  configureAuthenticator((request) => devActorFor(devRoleFrom(request.header('cookie'))));
+  logger.warn('every request is answered as a development viewer', {
+    role: DEFAULT_DEV_ROLE,
+    cause:
+      'apps/web/app/auth/dev-actor.ts installs a viewer in development only, because this app issues no session yet',
+    fix: \`browse as someone else: document.cookie = '\${DEV_ROLE_COOKIE}=member'\`,
+  });
+  return true;
+}
+
+// Module scope, which IS the wiring: the boot scan imports every module under \`apps/*\` before a
+// listener binds, and \`x dev\` and the container both read the configured value back at start.
+installDevAuthenticator();
+`;
+
+const devActorTest =
+  (): string => `// The two halves that make a development-only stand-in safe: it resolves the cookie, and it does
+// not install itself anywhere but development.
+import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
+import { actorHas } from '@ultimat3/policy';
+import { expect, unitTest } from '@ultimat3/testing';
+import { roles } from '../../shared/roles';
+import {
+  DEFAULT_DEV_ROLE,
+  DEV_ROLE_COOKIE,
+  devActorFor,
+  devRoleFrom,
+  installDevAuthenticator,
+} from './dev-actor';
+
+unitTest('the cookie names the role, and anything else falls back', () => {
+  expect(devRoleFrom(\`\${DEV_ROLE_COOKIE}=member\`)).toBe('member');
+  expect(devRoleFrom(\`\${DEV_ROLE_COOKIE}=nobody\`)).toBe(DEFAULT_DEV_ROLE);
+  expect(devRoleFrom(null)).toBe(DEFAULT_DEV_ROLE);
+});
+
+unitTest('the actor it mints holds what the role map grants it, and nothing else', () => {
+  // \`actorHas\` and not \`holds\`: this is the function \`can()\` itself calls, so the assertion is
+  // the pipeline's own decision rather than a second implementation of it. The map is passed
+  // explicitly — a test that depended on which module imported first would pass alone and fail
+  // inside a suite.
+  expect(actorHas(devActorFor('admin'), 'admin:read', roles)).toBe(true);
+  expect(actorHas(devActorFor('member'), 'dashboard:read', roles)).toBe(true);
+  // The whole reason this is development-only: a member is not an admin, and neither is a deploy.
+  expect(actorHas(devActorFor('member'), 'admin:read', roles)).toBe(false);
+});
+
+unitTest('it installs in development and in no other environment', () => {
+  // This process is \`test\`, so the module-scope call at the bottom of dev-actor.ts installed
+  // nothing — which is what keeps a fixture's own actor the only one a test can be about.
+  expect(configuredAuthenticator()).toBeUndefined();
+
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'production' })).toBe(false);
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'staging' })).toBe(false);
+  expect(configuredAuthenticator()).toBeUndefined();
+
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);
+  expect(configuredAuthenticator()).toBeDefined();
+  // Process-global, so the case that installed one takes it back out.
+  resetAuthenticator();
+});
+`;
+
+/** The app's development viewer, beside the roles it names. */
+export function authFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/app/auth/dev-actor.ts', contents: devActor(app) },
+    { path: 'apps/web/app/auth/dev-actor.test.ts', contents: devActorTest() },
+  ];
+}