@ultimat3/cli 22.15.0 → 24.0.0

package/src/templates/scaffold-app.ts

@@ -16,11 +16,21 @@ import { rolesFiles } from './scaffold-roles';
 import { shellFiles } from './scaffold-shell';
 import { siteFiles } from './scaffold-site';
 
+// `typecheck` is the ROOT program, as in every workspace `x new` writes: a type extension declared in
+// one workspace (`PermissionRegistry` in `app/*/policy.ts`) is in force only where its file is in
+// the program, and the app's own `tsconfig.json` passed in `apps/admin` what the gate refuses.
+//
 // The one dependency this manifest names, and it is not decoration: every page below reads its
 // strings through `@<app>/i18n`'s `useT()`, so the surface that renders a string DEPENDS on the
 // module that registers the catalogs. An undeclared workspace dependency resolves through the root
 // symlink and then breaks the day the app is built anywhere else.
-const webPackage = (app: NameSet): string => `{
+//
+// `@<app>/db` joins it with the example slice, whose repo.ts reads through the typed handle that
+// package exports. Under `--no-example` nothing here imports it yet, so it is not declared — the
+// first `x g entity` writes the line with the repo that needs it (`handle-registration.ts`).
+const webPackage = (app: NameSet, example: boolean): string => {
+  const db = example ? `\n    "@${app.kebab}/db": "0.0.0",` : '';
+  return `{
   "name": "@${app.kebab}/web",
   "version": "0.0.0",
   "private": true,
@@ -30,13 +40,14 @@ const webPackage = (app: NameSet): string => `{
     "./*.tsx": "./*.tsx"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
   },
-  "dependencies": {
+  "dependencies": {${db}
     "@${app.kebab}/i18n": "0.0.0"
   }
 }
 `;
+};
 
 // The ambient \`*.module.scss\` declaration is not reachable through an import, so a program that
 // only sees this app's files would report TS2307 on every stylesheet. Naming it in \`include\`
@@ -47,27 +58,39 @@ const tsconfig = (): string => `{
 }
 `;
 
-const offlineTest =
-  (): string => `// The offline fallback has to render with nothing: no network, no session, no database, and no
+const offlineTest = (
+  app: NameSet,
+): 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';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import * as page from './page';
 
-const ctx = { params: {}, url: 'https://example.test/offline' };
+const url = 'https://example.test/offline';
+
+unitTest('the offline fallback renders with no actor, and says the network is gone', async () => {
+  const t = useT();
+  // No actor and no context: exactly what the service worker has when it serves this.
+  const view = await renderRoute(page, { url });
+  expect(view.html.match(/<h1\\b/g)).toHaveLength(1);
+  expect(view.text).toBe(\`\${t('app.offline.title')} \${t('app.offline.description')}\`);
+  expect(view.islands).toEqual([]);
+});
 
 unitTest('the offline fallback is static, precached, and ships no JavaScript', async () => {
-  expect(config.render).toBe('static');
+  const view = await renderRoute(page, { url });
+  expect(page.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');
+  expect(page.config.offline).toBe('precache');
+  expect(page.config.hydrate).toBe('never');
+  expect(page.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);
+  expect(view.meta.robots?.index).toBe(false);
 });
 `;
 
@@ -103,7 +126,7 @@ export const config = defineRoute({
   }),
 });
 
-export function OfflinePage() {
+export function Page() {
   const t = useT();
 
   return (
@@ -167,6 +190,25 @@ const sharedGlobalModule =
 import './global.scss';
 `;
 
+const sharedGlobalTest =
+  (): string => `// The global layer reaches this app's module graph through exactly one edge. Cut it and every
+// \`var(--…)\` a component emits resolves to nothing: the app renders unstyled, with every test of
+// every component still green.
+import { registeredStylesheets } from '@ultimat3/render/server';
+import { expect, unitTest } from '@ultimat3/testing';
+import './global';
+
+unitTest('importing shared/global registers the one global stylesheet', () => {
+  const sheets = registeredStylesheets().filter((sheet) => sheet.global);
+  expect(sheets.map((sheet) => sheet.file.split('/').slice(-3).join('/'))).toEqual([
+    'web/shared/global.scss',
+  ]);
+  // The custom properties themselves, declared once on the root — what \`tokens.role()\` refers to.
+  expect(sheets[0]?.css).toContain(':root{');
+  expect(sheets[0]?.css).toContain('--color-bg:');
+});
+`;
+
 const sharedActor =
   (): string => `// The actor type both surfaces agree on. Policies read this and nothing else, so authz cannot
 // disagree between HTTP, live queries, jobs and MCP.
@@ -208,8 +250,10 @@ unitTest('holds answers from the role map, and an anonymous actor holds nothing'
 });
 `;
 
-// Same one dependency as `apps/web`, and for the same reason: `app/admin/page.tsx` reads its
-// strings through `@<app>/i18n`'s `useT()`.
+// Two dependencies, and they are the edges this workspace has: `app/admin/admin.ts` reads the
+// app's typed handle from `@<app>/db`, and its test loads the role map from `@<app>/web`.
+// Undeclared, they exist only inside the root tsconfig's `paths`, where `bun --filter` and every
+// change-detection tool are blind to them.
 const adminPackage = (app: NameSet): string => `{
   "name": "@${app.kebab}/admin",
   "version": "0.0.0",
@@ -220,47 +264,125 @@ const adminPackage = (app: NameSet): string => `{
     "./*.tsx": "./*.tsx"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
   },
   "dependencies": {
-    "@${app.kebab}/i18n": "0.0.0"
+    "@${app.kebab}/db": "0.0.0",
+    "@${app.kebab}/web": "0.0.0"
   }
 }
 `;
 
-const adminPage = (
+const adminDeclaration = (
   app: NameSet,
-): string => `// The generated admin dashboard. It ships an MCP surface over the app's own actions, so the
-// user's agents can drive the user's product with the user's permissions.
+): string => `// The whole admin dashboard. \`defineAdmin()\` serves a list, a detail and a form for every entity
+// below at /admin/<entity> — the columns, filters, validation and labels are derived from the
+// entity, the rows are read through the app's own typed handle, and \`x dev\` mounts the screens.
+// There is no page file, no repo adapter and no screen glue to write.
+//
+// It also ships an MCP surface over the same resources, so the user's agents can drive the user's
+// product with the user's permissions (\`adminMcp\`).
+${sortedImports([
+  `import { db } from '@${app.kebab}/db';`,
+  `import { adminEntitiesOf, defineAdmin } from '@ultimat3/admin';`,
+])}
 
-// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+export const admin = defineAdmin({
+  // Every entity the handle serves: \`x g entity\` adds one there, and it is an admin screen on
+  // the next boot. Name them one by one instead — \`entities: [post]\` — to leave a table out.
+  entities: adminEntitiesOf(db),
+  db,
+  // Who may do what is the app's role map (shared/roles.ts), asked permission by permission:
+  // \`admin:read\` + \`<table>:read\` to look, \`admin:write\` + \`<table>:write\` to create or edit,
+  // \`admin:destroy\` + \`<table>:delete\` to delete. \`x g entity\` grants a new table's three to
+  // the \`admin\` role; a role holding only the two \`:read\` grants is a view-only operator.
+  // Per-entity overrides — list columns, scopes, a row scope, which columns are sensitive — go in
+  // \`resources: { <entity>: … }\`. \`x g resource <name> --admin\` writes one and lists it here.
+});
+`;
+
+const adminDeclarationTest = (
+  app: NameSet,
+): string => `// The admin is one declaration, so what can go wrong is what it DERIVES: a route table with a
+// screen behind every path, each gated — and an authz that asks the role map for every permission,
+// so the admin role runs it and nobody else does.
+//
+// The role map is imported here because nothing else would load it: the boot scan reads
+// shared/roles.ts before the first request, and a test that reaches the admin directly has to say
+// so — without it the \`admin\` role grants nothing and every decision below is a refusal.
 ${sortedImports([
-  `import { useT } from '@${app.kebab}/i18n';`,
-  `import { defineRoute } from '@ultimat3/render';`,
+  `import { roles } from '@${app.kebab}/web/shared/roles';`,
+  `import { adminRoutes, permissionsForOperation } from '@ultimat3/admin';`,
+  `import { expect, unitTest } from '@ultimat3/testing';`,
 ])}
+import { admin } from './admin';
+
+const ctxFor = (roles: readonly string[]) =>
+  admin.ctx({ actor: { id: 'a', roles }, requestId: 'test' });
+
+unitTest('every admin route is gated and has a screen', () => {
+  const routes = adminRoutes(admin);
+  expect(routes.map((route) => route.path)).toContain('/admin');
+  for (const route of routes) {
+    // The coarse gate is the first permission of the route's own pair: \`admin:read\` for a
+    // screen that reads, \`admin:write\` for a form. Never absent.
+    expect(route.config.policy?.permission).toBe(route.permissions[0] ?? '');
+    expect(route.config.policy?.permission.startsWith('admin:')).toBe(true);
+    expect(typeof route.respond).toBe('function');
+  }
+});
 
-export const config = defineRoute({
-  render: 'ssr',
-  // Stated on a page whose body is one \`<h1>\`, and it costs nothing: the hydration runtime is
-  // emitted per island DIRECTIVE, so \`hydrateRuntime([])\` is \`''\` and this document ships 0 bytes
-  // (\`packages/render/src/hydrate.ts\`). It buys the first island being ONE file's edit —
-  // \`hydrate: 'never'\` beside an island is \`X_ISLAND_NOT_HYDRATED\`, which defineRoute refuses.
-  hydrate: 'idle',
-  offline: 'network-only',
-  // Behind auth, so the mode has to render per request: \`ssr\` and \`stream\` both do, and both take
-  // a \`policy\`. \`static\` and \`isr\` refuse one outright — a file on disk has no actor to decide
-  // against, and an ISR document is cached per URL, so the first actor's HTML would be served to
-  // every later one who passes the same policy.
-  policy: { permission: 'admin:read' },
-  budget: { js: '120kb' },
-  meta: ({ t }) => ({ title: t('admin.home.title'), description: t('admin.home.description') }),
+unitTest('one resource per entity on the handle, each reading through it', () => {
+  for (const resource of admin.resources) {
+    expect(admin.routes.map((route) => route.path)).toContain(\`/admin\${resource.path}\`);
+    expect(resource.repo).toBeDefined();
+  }
 });
 
-export function AdminHome() {
-  const t = useT();
+unitTest('the admin role holds every permission the admin derives, and a member none', () => {
+  // Every route's pair and every operation's — a delete has no route of its own, it is a POST at
+  // the row's URL — asked of the role map by name: a table the handle gained without its three
+  // grants in shared/roles.ts fails HERE, not as a 403 an operator reports.
+  const required = [
+    ...new Set([
+      ...admin.routes.flatMap((route) => route.permissions),
+      ...admin.resources.flatMap((resource) =>
+        resource.operations.flatMap((op) => permissionsForOperation(resource.permission, op)),
+      ),
+    ]),
+  ];
+  expect(required).toContain('admin:read');
+  for (const permission of required) {
+    const asked = { permission, subject: { entity: 'any' } };
+    const granted = admin.authz.decide({ ...asked, actor: ctxFor(['admin']).actor });
+    expect({ permission, allowed: granted.allowed }).toEqual({ permission, allowed: true });
+  }
+  // Held whether or not the app has a table yet: the first \`x g entity\` must find them here.
+  expect(roles.admin.grants).toContain('admin:write');
+  expect(roles.admin.grants).toContain('admin:destroy');
+  const refused = admin.authz.decide({
+    permission: 'admin:write',
+    actor: ctxFor(['member']).actor,
+  });
+  expect(refused.allowed).toBe(false);
+  expect(refused.permission).toBe('admin:write');
+});
 
-  return <h1>{t('admin.home.title')}</h1>;
-}
+unitTest('the dashboard answers 200 for the admin role and 403 for anyone else', async () => {
+  const [home] = adminRoutes(admin);
+  const ask = (roles: readonly string[]) =>
+    home?.respond({
+      ctx: ctxFor(roles),
+      params: {},
+      url: 'http://localhost/admin',
+      method: 'GET',
+      form: null,
+    });
+  const allowed = await ask(['admin']);
+  expect(allowed?.kind === 'document' && allowed.status).toBe(200);
+  const denied = await ask(['member']);
+  expect(denied?.kind === 'document' && denied.status).toBe(403);
+});
 `;
 
 const placeholder = (surface: string, app: NameSet): string => `# ${surface}
@@ -280,7 +402,7 @@ restructure.
  * slice itself is written elsewhere. */
 export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
   return [
-    { path: 'apps/web/package.json', contents: webPackage(app) },
+    { path: 'apps/web/package.json', contents: webPackage(app, example) },
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
     // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
     ...entryFiles(),
@@ -302,12 +424,13 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // 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() },
+    { path: 'apps/web/site/offline/page.test.ts', contents: offlineTest(app) },
     // 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() },
     { path: 'apps/web/shared/global.scss', contents: sharedGlobalStyle() },
     { path: 'apps/web/shared/global.ts', contents: sharedGlobalModule() },
+    { path: 'apps/web/shared/global.test.ts', contents: sharedGlobalTest() },
     { path: 'apps/web/shared/actor.ts', contents: sharedActor() },
     { path: 'apps/web/shared/actor.test.ts', contents: sharedActorTest() },
     // The one org the dev actor, the seed and the dashboard all name — `scaffold-demo-org.ts`.
@@ -319,12 +442,13 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     ...rolesFiles(example),
     { path: 'apps/admin/package.json', contents: adminPackage(app) },
     { path: 'apps/admin/tsconfig.json', contents: tsconfig() },
-    // `apps/admin/app/admin/page.tsx`, not `apps/admin/app/page.tsx`: the directory IS the URL,
-    // relative to the surface root, so the shallower path resolves to `/` and collides with
-    // `apps/web/site/page.tsx` — `x dev` loads both surfaces into one route table and the
-    // scaffolded app failed its own `x routes` with X_ROUTE_DUPLICATE. `/admin` also matches
-    // @ultimat3/admin's own `basePath` default, so the two agree instead of merely not clashing.
-    { path: 'apps/admin/app/admin/page.tsx', contents: adminPage(app) },
+    // `apps/admin/app/admin/admin.ts`: a DECLARATION, not a page. `defineAdmin()` registers the
+    // admin and `x dev` mounts every screen it derives under `/admin` (`runtime-admin.ts`), so the
+    // app carries no route file for it. It sits under `app/` because that is where the boot scan
+    // looks — a module nothing imports declares nothing — and its test rides beside it, because
+    // generated source with no test is uncovered source in an app whose gate holds a floor.
+    { path: 'apps/admin/app/admin/admin.ts', contents: adminDeclaration(app) },
+    { path: 'apps/admin/app/admin/admin.test.ts', contents: adminDeclarationTest(app) },
     { path: 'apps/mobile/README.md', contents: placeholder('mobile', app) },
     { path: 'apps/desktop/README.md', contents: placeholder('desktop', app) },
   ];

package/src/templates/scaffold-auth.ts

@@ -36,35 +36,39 @@ const devActor = (
 import { type Actor, logger, tryResolveEnvironment } from '@ultimat3/core';
 import { configureAuthenticator, readCookie } from '@ultimat3/http';
 import { DEMO_ORG_ID } from '../../shared/demo-org';
+import { roles } from '../../shared/roles';
 
-/** Set it to a role from \`apps/web/shared/roles.ts\` to browse as that role. */
+/** Set it to a role \`apps/web/shared/roles.ts\` declares 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';
+/** With NO cookie: the one that can open every scaffolded route, including \`/admin\`. */
+export const DEFAULT_DEV_ROLE = 'admin';
 
-const isDevRole = (value: string | null): value is DevRole =>
-  value !== null && (DEV_ROLES as readonly string[]).includes(value);
+/**
+ * The roles a cookie may name: the ones \`shared/roles.ts\` declares, read off the map itself. A
+ * list spelled here went stale the day a role was added there — the new role was "unknown", and
+ * unknown fell back to admin, so browsing as a read-only role silently browsed as the most
+ * privileged one.
+ */
+export const declaredDevRoles = (): readonly string[] => Object.keys(roles);
 
 /**
- * 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.
+ * The role a request browses as, or \`undefined\` for a cookie naming a role nobody declared.
+ * No cookie at all is the default viewer; a cookie that names something else is a statement this
+ * module cannot honour, and it is never answered with more than was asked for.
  */
-export const devRoleFrom = (cookieHeader: string | null): DevRole => {
+export const devRoleFrom = (cookieHeader: string | null): string | undefined => {
   const named = readCookie(cookieHeader, DEV_ROLE_COOKIE);
-  return isDevRole(named) ? named : DEFAULT_DEV_ROLE;
+  if (named === null) return DEFAULT_DEV_ROLE;
+  // \`Object.hasOwn\`, never \`in\`: a cookie saying \`constructor\` names no role.
+  return Object.hasOwn(roles, named) ? named : undefined;
 };
 
 /**
  * \`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 => ({
+export const devActorFor = (role: string): Actor => ({
   kind: 'user',
   id: 'dev-actor',
   // The seed's org, never an invented string: a generated tenant policy compares it with a uuid.
@@ -77,6 +81,30 @@ export const devActorFor = (role: DevRole): Actor => ({
   permissions: [],
 });
 
+/** The one method this reads off a request. */
+interface HeaderRequest {
+  header(name: string): string | null;
+}
+
+/**
+ * What \`hooks.authenticate\` is handed: the request's cookie header decides the role. Named, and
+ * typed by the one method it reads, so a test calls it with a header and no server.
+ *
+ * A cookie naming an undeclared role answers \`null\` — ANONYMOUS, the least a request can be —
+ * and says so, with the value it read and the roles it could have named.
+ */
+export const devAuthenticate = (request: HeaderRequest): Actor | null => {
+  const cookieHeader = request.header('cookie');
+  const role = devRoleFrom(cookieHeader);
+  if (role !== undefined) return devActorFor(role);
+  logger.warn('the development role cookie names no declared role: answering as anonymous', {
+    named: readCookie(cookieHeader, DEV_ROLE_COOKIE),
+    declared: declaredDevRoles(),
+    fix: \`document.cookie = '\${DEV_ROLE_COOKIE}=\${DEFAULT_DEV_ROLE}'   # or declare the role in apps/web/shared/roles.ts\`,
+  });
+  return null;
+};
+
 /**
  * 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.
@@ -85,7 +113,7 @@ export function installDevAuthenticator(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): boolean {
   if (tryResolveEnvironment({ env, fallback: 'production' }) !== 'development') return false;
-  configureAuthenticator((request) => devActorFor(devRoleFrom(request.header('cookie'))));
+  configureAuthenticator(devAuthenticate);
   logger.warn('every request is answered as a development viewer', {
     role: DEFAULT_DEV_ROLE,
     cause:
@@ -103,6 +131,7 @@ 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 { setLogSink } from '@ultimat3/core';
 import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
 import { actorHas } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
@@ -110,15 +139,27 @@ import { roles } from '../../shared/roles';
 import {
   DEFAULT_DEV_ROLE,
   DEV_ROLE_COOKIE,
+  declaredDevRoles,
   devActorFor,
+  devAuthenticate,
   devRoleFrom,
   installDevAuthenticator,
 } from './dev-actor';
 
-unitTest('the cookie names the role, and anything else falls back', () => {
+unitTest('the cookie names a DECLARED role; with no cookie it is the default viewer', () => {
   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);
+  // Read off the role map, so a role added to shared/roles.ts is one this cookie can name.
+  expect(declaredDevRoles()).toEqual(Object.keys(roles));
+  expect(declaredDevRoles()).toContain(DEFAULT_DEV_ROLE);
+});
+
+unitTest('a cookie naming an undeclared role is never the default viewer', () => {
+  // It fell back to admin: a typo, or a role not declared yet, browsed as the most privileged
+  // role there is — and a "read-only role cannot write" check passed for the wrong reason.
+  for (const named of ['nobody', 'Admin', 'constructor', '']) {
+    expect(devRoleFrom(\`\${DEV_ROLE_COOKIE}=\${named}\`)).toBeUndefined();
+  }
 });
 
 unitTest('the actor it mints holds what the role map grants it, and nothing else', () => {
@@ -147,10 +188,33 @@ unitTest('it installs in development and in no other environment', () => {
   expect(configuredAuthenticator()).toBeUndefined();
 
   expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);
-  expect(configuredAuthenticator()).toBeDefined();
+  expect(configuredAuthenticator()).toBe(devAuthenticate);
   // Process-global, so the case that installed one takes it back out.
   resetAuthenticator();
 });
+
+unitTest('what it installs answers a request from its cookie header, and no other', () => {
+  const cookie = \`\${DEV_ROLE_COOKIE}=member\`;
+  const request = { header: (name: string) => (name === 'cookie' ? cookie : null) };
+  expect(devAuthenticate(request)?.roles).toEqual(['member']);
+  // A request with no cookie is the default viewer, never an anonymous one.
+  expect(devAuthenticate({ header: () => null })?.roles).toEqual([DEFAULT_DEV_ROLE]);
+});
+
+unitTest('an undeclared role is answered as ANONYMOUS, and the log names what it read', () => {
+  const lines: Record<string, unknown>[] = [];
+  const previous = setLogSink((line) => lines.push(JSON.parse(line) as Record<string, unknown>));
+  try {
+    const cookie = \`\${DEV_ROLE_COOKIE}=auditor\`;
+    expect(devAuthenticate({ header: () => cookie })).toBeNull();
+  } finally {
+    setLogSink(previous);
+  }
+  expect(lines).toHaveLength(1);
+  expect(lines[0]?.level).toBe('warn');
+  expect(lines[0]?.named).toBe('auditor');
+  expect(lines[0]?.declared).toEqual(Object.keys(roles));
+});
 `;
 
 /** The app's development viewer, beside the roles it names. */

package/src/templates/scaffold-browser-client.ts

@@ -0,0 +1,90 @@
+// `apps/web/shared/browser-client.ts` — the two typed clients an island calls, and the test beside
+// them. Split from scaffold-api.ts because that file writes the SERVER half of the API surface;
+// this is the browser's projection of it, shaped from `api/index.ts`'s `Api` type and nothing else.
+
+import type { GeneratedFile } from './naming';
+
+const browserClient = (): string => `/**
+ * The typed clients an ISLAND calls: \`browserClient.health({})\` writes, \`browserQueries.<name>(input)\`
+ * reads. Every action and query this app registers is a method here, typed from its own schemas,
+ * with no codegen step. The \`Api\` import is type-only, so no module edge reaches a feature's
+ * implementation and \`site/\` islands may use these too (\`site/\` may not import \`app/\`).
+ *
+ * Origin-relative: a browser posts to the page's own origin. No \`pathStyle\` either — the server
+ * stamps \`defineApi({ http: { pathStyle } })\` into every document and the client reads it there,
+ * so there is nothing here to keep in step.
+ *
+ * An island never calls \`fetch\`: a raw request in browser code is X_BROWSER_TRANSPORT_BYPASS on
+ * \`x verify\`. \`@ultimat3/query/client\`, not the barrel — the barrel carries the server's registry
+ * and is X_BROWSER_SERVER_BARREL in a browser chunk.
+ */
+
+import { rpc } from '@ultimat3/action';
+import { queryClient } from '@ultimat3/query/client';
+import type { Api } from '../api';
+
+export const browserClient = rpc<Api['actions']>({ baseUrl: '' });
+export const browserQueries = queryClient<Api['queries']>({ baseUrl: '' });
+`;
+
+/** The read the example slice registers; `--no-example` registers none, so it asserts none. */
+const exampleRead = `
+unitTest('browserQueries reads a query over GET, its input in the search string', async () => {
+  const seen = await recording(
+    () => Response.json([]),
+    // No org: the read is the caller's own org, decided on the server from the session.
+    () => browserQueries.postList({ limit: 10 }),
+  );
+  expect(seen.answer).toEqual([]);
+  expect(seen.requests).toEqual([{ method: 'GET', url: '/_x/query/post-list?limit=10' }]);
+});
+`;
+
+const browserClientTest = (
+  example: boolean,
+): string => `// The island's typed clients reach the server the way the server serves it: an action is a POST to
+// its derived path on the page's own origin, a read is a GET under /_x/query. Asserted on the wire
+// — the one place a renamed action or a moved origin would show.
+import { expect, unitTest } from '@ultimat3/testing';
+import { browserClient${example ? ', browserQueries' : ''} } from './browser-client';
+
+interface Sent {
+  readonly method: string | undefined;
+  readonly url: string;
+}
+
+/** Runs \`call\` against a \`fetch\` that records each request and answers with \`respond()\`. */
+async function recording<T>(
+  respond: () => Response,
+  call: () => Promise<T>,
+): Promise<{ readonly answer: T; readonly requests: readonly Sent[] }> {
+  const requests: Sent[] = [];
+  const real = globalThis.fetch;
+  globalThis.fetch = (async (url: string, init?: RequestInit) => {
+    requests.push({ method: init?.method, url });
+    return respond();
+  }) as typeof fetch;
+  try {
+    return { answer: await call(), requests };
+  } finally {
+    globalThis.fetch = real;
+  }
+}
+
+unitTest('browserClient posts an action to its derived path on the page origin', async () => {
+  const seen = await recording(
+    () => Response.json({ ok: true, role: 'web' }),
+    () => browserClient.health({}),
+  );
+  expect(seen.answer).toEqual({ ok: true, role: 'web' });
+  expect(seen.requests).toEqual([{ method: 'POST', url: '/api/healths/invoke' }]);
+});
+${example ? exampleRead : ''}`;
+
+/** The client and its test, in `shared/` because both `site/` and `app/` islands import it. */
+export function browserClientFiles(example: boolean): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/shared/browser-client.ts', contents: browserClient() },
+    { path: 'apps/web/shared/browser-client.test.ts', contents: browserClientTest(example) },
+  ];
+}

package/src/templates/scaffold-container-compose.ts

@@ -25,6 +25,11 @@ export const composeProdFile = (
 #
 #   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
 #
+# Two origins the file cannot know, so ${PROD_ENV_FILE} states them: SYNC_URL, where a page dials
+# the socket (ws://<host>:3001/_x/sync), and APP_URL, where the pages are served
+# (http://<host>:3000) — the sync node admits a socket from APP_URL's origin and no other once
+# declared; undeclared, from the origin it was reached on.
+#
 # A published host port has exactly one binder, so \`web\` and \`sync\` run at 1 here. Compose is one
 # box; horizontal scaling of those two belongs to an orchestrator — \`docker/helm\`, beside this
 # file, is the chart \`x deploy --method helm\` installs. To scale them on one box anyway, drop
@@ -129,7 +134,11 @@ services:
 
   sync:
     <<: *image
-    environment: [ROLE=sync]
+    # The page is :3000 and this socket :3001 — two origins — and the node admits an upgrade from
+    # APP_URL's origin and no other once declared (scheme, host and port, exactly); undeclared, from
+    # the origin it was reached on. Unset, every websocket is 403 X_SOCKET_ORIGIN_REFUSED, so it is
+    # required: the same value web builds its links from.
+    environment: [ROLE=sync, 'APP_URL=\${APP_URL:?set APP_URL=http://<host>:3000 — the origin the pages are served on, see wiki/Deployment.md}']
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }