@ultimat3/cli 10.0.0 → 11.0.0

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',
@@ -89,6 +91,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() },
+  ];
+}

package/src/templates/scaffold-mcp-package.ts

@@ -2,6 +2,7 @@
 // action registry rather than re-listed, plus the test that pins every projected tool describing
 // itself.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { packageShapeFiles } from './scaffold-package-shape';
 
@@ -44,9 +45,11 @@ const mcpIndex = (
   app: NameSet,
 ): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
 // read-only helpers here. Authorization is the action's policy, unchanged.
-import * as api from '@${app.kebab}/web/api/health';
-import { registerActions } from '@ultimat3/action';
-import { defineAppMcp } from '@ultimat3/mcp';
+${sortedImports([
+  `import * as api from '@${app.kebab}/web/api/health';`,
+  `import { registerActions } from '@ultimat3/action';`,
+  `import { defineAppMcp } from '@ultimat3/mcp';`,
+])}
 
 // Names come from export names, so the registry agrees with the module the app already wrote.
 registerActions(api);

package/src/templates/scaffold-repo.ts

@@ -63,6 +63,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/core": "^${version}",
     "@ultimat3/db": "^${version}",
     "@ultimat3/entity": "^${version}",
+    "@ultimat3/http": "^${version}",
     "@ultimat3/i18n": "^${version}",
     "@ultimat3/jobs": "^${version}",
     "@ultimat3/mcp": "^${version}",

package/src/verify-checks.ts

@@ -27,6 +27,7 @@ import { checkSourceDrift } from './drift';
 import { checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
+import { liveRouteFindings } from './live-routes';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -171,7 +172,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'budgets',
-    summary: 'per-route JS bytes and LCP, and the global style layer every document carries',
+    summary:
+      'per-route JS bytes and LCP, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
     // The global-style assertion rides here rather than becoming an eighteenth step, because this
     // step already asks the one question it asks: what does the document this build emits actually
     // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
@@ -202,6 +204,10 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       return fromFindings([
         ...findings,
         ...checkDocumentStyles(documentSurfaces()),
+        // The third rider, and the same question this step already asks one level down: what
+        // JavaScript does this route's document boot? A live read with no island is a route
+        // whose answer is "none", which no suite can fail on — the page renders, at 200.
+        ...(await liveRouteFindings(ctx.root)),
         ...checkBudgets(manifest, stats),
       ]);
     },