@ultimat3/cli 6.0.0 → 8.0.0

package/src/templates/resource-form-island.ts

@@ -0,0 +1,279 @@
+// The slice's client entry: `x g resource <name>` emits its form as an ISLAND, because that is the
+// one shape the framework compiles for a browser. A plain `.tsx` with a signal and an `onSubmit`
+// is not a smaller version of this — the island glob never discovers it, and a server render drops
+// every `on*` prop (`packages/render/src/html.ts`) and reads each signal exactly once.
+
+// Bun ships no path API, and the one arithmetic this file does is a specifier: the island's path
+// seen from the page's directory, which `island-bundle.ts` resolves the same way at build time.
+import { posix } from 'node:path';
+import { upToAppRoot } from './island';
+import type { GeneratedFile, NameSet } from './naming';
+
+/**
+ * What the PAGE has to write, which is not what the island's own directory would suggest.
+ *
+ * `island({ src })` resolves against the route file, and `x g resource widget` writes its page at
+ * `apps/web/app/widgets/` while the island lands in `apps/web/app/widget/` — so the `'./…'` this
+ * file used to print resolved to `apps/web/app/widgets/widget-form.island.tsx`, a path the build
+ * never bundles, and an author following the comment got `X_ISLAND_INVALID`. Derived from the two
+ * directories rather than written down, so it cannot disagree with where the files actually go.
+ */
+export const formIslandSpecifier = (feature: NameSet, dir: string, pageDir: string): string => {
+  const relative = posix.join(posix.relative(pageDir, dir), `${feature.kebab}-form.island.tsx`);
+  return relative.startsWith('.') ? relative : `./${relative}`;
+};
+
+const formIslandSource = (
+  feature: NameSet,
+  specifier: string,
+): string => `// ${feature.pascal}Form: the only module of the ${feature.kebab} slice a browser downloads.
+//
+// The page names this file by SPECIFIER, never by import — and the specifier is resolved against
+// the PAGE, which is one directory across from this one:
+//   const ${feature.pascal}Form = island({
+//     src: '${specifier}',
+//     props: ['endpoint', 'locale', 'labels'],
+//   });
+//   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale} labels={labels} />
+// A string has no import edge, so the page's bundle graph stays the page's (axiom 6).
+
+import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import * as solidRuntime from 'solid-js';
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import styles from './ui.module.scss';
+
+/** Every string this module renders, and the path it posts to. An island's props cross the seam as
+ *  JSON inside the document, so \`t()\`'s catalog cannot travel — the server translates. */
+export interface ${feature.pascal}FormProps {
+  /** \`derivePath('create${feature.pascal}').path\`, minted on the server: one namer for the route. */
+  readonly endpoint: string;
+  /** The request's own locale. A browser has no ambient one the server ever agreed to. */
+  readonly locale: string;
+  readonly labels: {
+    readonly title: string;
+    readonly submit: string;
+    readonly saved: string;
+    readonly retry: string;
+  };
+}
+
+type SaveState = 'idle' | 'saved' | 'failed';
+
+/**
+ * Presentation only: the action this submits to owns validation server-side, so the form never
+ * re-implements the invariant — a blank title fails at the boundary, not in the DOM.
+ *
+ * A plain \`fetch\` to the path the server minted, not the typed client: \`rpc()\` pulls
+ * \`@ultimat3/action\` into the chunk, which is larger than everything else here put together. The
+ * naming rule is still the framework's; only the transport is second.
+ */
+function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Element {
+  const [title, setTitle] = createSignal('');
+  const [state, setState] = createSignal<SaveState>('idle');
+
+  // A rejected \`fetch\` — offline, DNS, an aborted request — is the same OUTCOME as a refused one,
+  // and it is the one \`retry\` exists for. Without the catch, \`setState\` is never reached: the
+  // status line stays empty, and the rejection escapes the \`void send()\` below as an unhandled one.
+  const send = async (): Promise<void> => {
+    try {
+      const response = await fetch(props.endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ title: title() }),
+      });
+      setState(response.ok ? 'saved' : 'failed');
+    } catch {
+      setState('failed');
+    }
+  };
+
+  const status = (): string => {
+    if (state() === 'saved') return props.labels.saved;
+    return state() === 'failed' ? props.labels.retry : '';
+  };
+
+  return (
+    <Form
+      class={styles.item}
+      onSubmit={(event) => {
+        event.preventDefault();
+        void send();
+      }}
+    >
+      <Input
+        aria-label={props.labels.title}
+        value={title()}
+        onInput={(event) => setTitle(event.currentTarget.value)}
+      />
+      <Button type="submit">{props.labels.submit}</Button>
+      <p data-role="status" role="status" aria-live="polite">
+        {status()}
+      </p>
+    </Form>
+  );
+}
+
+/**
+ * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
+ *
+ * \`setSolidRuntime\` comes FIRST and it is not optional: \`@ultimat3/ui\` imports *types* from
+ * solid-js and never a runtime, so the reactive graph a component reaches is the one an entry
+ * registers. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
+ * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
+ *
+ * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
+ * so without it the server's markup stays on screen above a second, live copy of the same thing.
+ */
+export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
+  setSolidRuntime(solidRuntime);
+  el.textContent = '';
+  render(
+    () => (
+      <UiProvider locale={props.locale}>
+        <${feature.pascal}FormBody {...props} />
+      </UiProvider>
+    ),
+    el,
+  );
+}
+`;
+
+const formIslandTest = (
+  feature: NameSet,
+  dir: string,
+): string => `// The form the browser actually runs. \`mountIsland\` builds this entry with the same
+// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
+// runtime does, and drives \`mount\` against a DOM small enough to read.
+//
+// It is the test that keeps this file a CLIENT entry. A generated form that only typechecks is
+// what shipped before: server-rendered, every \`on*\` prop dropped, every signal read once.
+
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type FakeElement,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
+
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
+const ISLAND = '${dir}/${feature.kebab}-form.island.tsx';
+const ENDPOINT = '/api/${feature.kebab}/create-${feature.kebab}';
+
+const LABELS = { title: 'Title', submit: 'Save', saved: 'Saved', retry: 'Try again' };
+
+const calls: { url: string; body: Record<string, unknown> }[] = [];
+
+/** One stub, both outcomes: the mount costs seconds, so the network's answer is a switch. */
+let networkFails = false;
+
+let mounted: MountedIsland;
+
+// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
+// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
+// per case, so the slow work goes where it can be given one and every case shares the result.
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { endpoint: ENDPOINT, locale: 'en', labels: LABELS },
+    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+    shell: '<p>Loading</p>',
+    globals: {
+      fetch: (url: string, init: { body: string }): Promise<{ ok: boolean }> => {
+        calls.push({ url, body: JSON.parse(init.body) as Record<string, unknown> });
+        // What a browser rejects with when there is no network. Not a response: \`response.ok\`
+        // is never read on this path, which is exactly why the form has to catch it.
+        return networkFails
+          ? Promise.reject(new TypeError('Failed to fetch'))
+          : Promise.resolve({ ok: true });
+      },
+    },
+  });
+}, 60_000);
+
+// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
+//
+// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
+// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
+// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
+// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
+// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+
+/**
+ * One mount, driven as a session: the cases below run in order against the same island, because
+ * building the real chunk costs seconds and repeating it per case would pay them for state each
+ * case sets up anyway. What each one asserts is independent.
+ */
+describe('the ${feature.kebab} form island', () => {
+  test('mount replaces the server shell with the editor', () => {
+    expect(mounted.find('p')?.getAttribute('data-role')).toBe('status');
+    // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
+    // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+
+  test('the field tracks, and submit posts what was typed', async () => {
+    const field: FakeElement | null = mounted.find('input');
+    expect(field).not.toBeNull();
+    if (field !== null) field.value = 'First ${feature.camel}';
+    // \`false\` means no handler ran — an island whose onInput never reached the DOM looks
+    // identical to a selector typo otherwise.
+    expect(mounted.fire(field, 'input')).toBe(true);
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+
+    expect(calls).toEqual([{ url: ENDPOINT, body: { title: 'First ${feature.camel}' } }]);
+  });
+
+  test('the status line answers the response', () => {
+    // The signal reached the DOM: an eager JSX factory renders '' here and never runs again.
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.saved);
+  });
+
+  test('a request that never got a response still reaches retry', async () => {
+    // The outcome \`retry\` is FOR. A \`fetch\` that rejects reaches no \`response.ok\`, so without
+    // the catch in \`send\` the status line stays on its last value and the rejection escapes.
+    networkFails = true;
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.retry);
+  });
+});
+`;
+
+/**
+ * The slice's form, as the one client shape: `<dir>/<feature>-form.island.tsx` plus its test.
+ *
+ * `pageDir` is the directory of the page that declares it — the caller's, because only the caller
+ * runs both generators and knows where the other one put its file.
+ */
+export function formIslandFiles(
+  feature: NameSet,
+  dir: string,
+  pageDir: string,
+): readonly GeneratedFile[] {
+  return [
+    {
+      path: `${dir}/${feature.kebab}-form.island.tsx`,
+      contents: formIslandSource(feature, formIslandSpecifier(feature, dir, pageDir)),
+    },
+    {
+      path: `${dir}/${feature.kebab}-form.island.test.ts`,
+      contents: formIslandTest(feature, dir),
+    },
+  ];
+}

package/src/templates/resource.ts

@@ -13,7 +13,8 @@ import type { GeneratedFile, NameSet } from './naming';
 import { names, pascal } from './naming';
 import { policyFiles } from './policy';
 import { queryFiles } from './query';
-import { routeFiles } from './route';
+import { formIslandFiles } from './resource-form-island';
+import { routeDir, routeFiles } from './route';
 
 const serviceSource = (
   feature: NameSet,
@@ -142,40 +143,6 @@ export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {${tran
 }
 `;
 
-const formSource = (
-  feature: NameSet,
-  module: string | undefined,
-): string => `// Presentation only: the mutator this submits to owns validation server-side, so this form
-// never re-implements the invariant — a blank title fails at the boundary, not in the DOM.
-
-${catalogImport(module)}
-import { createSignal } from 'solid-js';
-import styles from '../ui.module.scss';
-
-export interface ${feature.pascal}FormProps {
-  readonly onSubmit: (title: string) => void;
-}
-
-export function ${feature.pascal}Form(props: ${feature.pascal}FormProps) {
-  const [title, setTitle] = createSignal('');${translatorBinding(module)}
-  return (
-    <form
-      class={styles.item}
-      onSubmit={(event) => {
-        event.preventDefault();
-        props.onSubmit(title());
-      }}
-    >
-      <label>
-        {t('app.${feature.kebab}.titleLabel')}
-        <input value={title()} onInput={(event) => setTitle(event.currentTarget.value)} />
-      </label>
-      <button type="submit">{t('app.${feature.kebab}.submit')}</button>
-    </form>
-  );
-}
-`;
-
 // `admin.<feature>.title` is always here, `--admin` or not: `defineAdmin()` resolves that key the
 // moment anyone writes the override, and a missing key renders ⟦key⟧ and fails the i18n gate,
 // while an unused key is only ever reported (`auditCatalogs` fails on `missing`, never `unused`).
@@ -185,6 +152,8 @@ const catalogSource = (feature: NameSet): string =>
     [`app.${feature.kebab}.updated`]: 'Last updated',
     [`app.${feature.kebab}.titleLabel`]: 'Title',
     [`app.${feature.kebab}.submit`]: 'Save',
+    [`app.${feature.kebab}.saved`]: 'Saved',
+    [`app.${feature.kebab}.retry`]: 'Try again',
     [`admin.${feature.kebab}.title`]: pascal(feature.plural),
   });
 
@@ -204,6 +173,10 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
   const feature = names(rawName);
   const slice: FeatureTarget = { surfaceDir: target.surfaceDir, feature: feature.kebab };
   const dir = `${slice.surfaceDir}/${slice.feature}`;
+  // The page this same call writes, from the function that decides where a route goes — the island
+  // specifier is resolved against it, so re-deriving the path here would be two answers to one
+  // question and only one of them reaches `routeFiles`.
+  const pageDir = routeDir('app', feature.pluralKebab);
   const locales = resolveLocales(target.locales);
   return [
     ...entityFiles(rawName, slice),
@@ -220,18 +193,24 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
       path: `${dir}/ui/${feature.kebab}-card.tsx`,
       contents: cardSource(feature, target.catalogModule),
     },
-    {
-      path: `${dir}/ui/${feature.kebab}-form.tsx`,
-      contents: formSource(feature, target.catalogModule),
-    },
+    ...formIslandFiles(feature, dir, pageDir),
     ...locales.map((locale) => ({
       path: catalogPath(locale),
       contents: catalogSource(feature),
       merge: 'json' as const,
     })),
-    // Always an app route: a slice ships a live query, a form and actions, and `generate()`
+    // Always an app route: a slice ships a live query, a form island and actions, and `generate()`
     // refuses `--surface site` for a resource rather than emit them behind a 0kb budget.
-    ...routeFiles(feature.pluralKebab, { surface: 'app', locales }),
+    //
+    // `catalogModule` travels with it. It did not, so the page a RESOURCE writes imported `t` from
+    // `@ultimat3/i18n` while the components beside it imported `useT` from the app's own catalog
+    // module — one command, two idioms, and the framework-import one is issue #249's: it renders
+    // strings while depending on nothing that registers them.
+    ...routeFiles(feature.pluralKebab, {
+      surface: 'app',
+      locales,
+      ...(target.catalogModule === undefined ? {} : { catalogModule: target.catalogModule }),
+    }),
     ...(target.admin === true ? adminFiles(rawName, slice) : []),
   ];
 }

package/src/templates/route.ts

@@ -19,6 +19,14 @@ export type Surface = 'site' | 'app';
  * that was absent from `x routes`, from the manifest and from `budgets`. Ship the mode that works.
  */
 const RENDER: Record<Surface, string> = { site: 'isr', app: 'ssr' };
+/**
+ * `app` is `'visible'` on a page the generator writes with no island, and that is not an oversight.
+ * A declared strategy costs nothing when there is nothing to hydrate — `hydrateRuntime` is emitted
+ * per island DIRECTIVE and answers `''` for a page with none (`packages/render/src/hydrate.ts`), so
+ * `x routes` reads `visible` while the document ships 0 bytes. What it buys is that adding the
+ * first island is one edit: a declared `'never'` beside an island is `X_ISLAND_NOT_HYDRATED`, which
+ * `defineRoute` refuses on purpose, so the scaffold would break at the moment it is first used.
+ */
 const HYDRATE: Record<Surface, string> = { site: 'never', app: 'visible' };
 const OFFLINE: Record<Surface, string> = { site: 'precache', app: 'runtime' };
 /**
@@ -66,7 +74,12 @@ export const routeParams = (path: string): readonly string[] =>
     return name === undefined ? [] : [name];
   });
 
-const routeDir = (surface: Surface, path: string): string =>
+/**
+ * Where the page lands. Exported because an island's `src` is resolved relative to the PAGE, and
+ * only this function knows where `x g resource`'s page went — a second copy of the formula in the
+ * resource generator is how the specifier it prints stops matching the file it writes.
+ */
+export const routeDir = (surface: Surface, path: string): string =>
   `apps/web/${surface}/${segmentsOf(path).join('/')}`;
 
 /**
@@ -125,7 +138,7 @@ export function ${name}Page() {${translatorBinding(module)}
 };
 
 const styleSource =
-  (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and a lint failure.
+  (): string => `// Semantic tokens only — a raw hex here is refused by the boundaries step (guards/raw-colour.ts), not by lint — a dark-theme bug in every scheme but the one it was written in.
 @use '@ultimat3/ui/tokens' as tokens;
 
 .page {

package/src/templates/scaffold-app.ts

@@ -4,6 +4,7 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
+import { entryFiles } from './scaffold-entries';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
 
@@ -136,6 +137,8 @@ export const config = defineRoute({
   // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
   // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
   render: 'ssr',
+  // Stated with no island on the page, deliberately and for free — \`apps/admin/app/admin/page.tsx\`
+  // carries the reason.
   hydrate: 'visible',
   offline: 'runtime',
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
@@ -325,10 +328,16 @@ import { defineRoute } from '@ultimat3/render';
 
 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, and \`ssr\` is the one mode that can be: it renders per request, so the guard runs
-  // on the server before the page does. \`static\` and \`isr\` refuse a policy outright.
+  // 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') }),
@@ -341,80 +350,6 @@ export function AdminHome() {
 }
 `;
 
-// The two entry files a deploy needs. Both are deliberately thin: which role a container is, which
-// port it binds, how it drains and what a static build enumerates are the framework's answers, so
-// an upgrade moves them without a codemod in every app that ever shipped.
-
-const server =
-  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
-// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
-// applies the migrations and exits. PORT is bound on every interface, because a container bound to
-// localhost is unreachable through its own port mapping.
-
-import { join } from 'node:path';
-import { runRole } from '@ultimat3/cli';
-
-// MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
-//
-//   import { configureIdempotency } from '@ultimat3/action';
-//   configureIdempotency({ scope: 'shared' });
-//
-// \`idempotent: true\` on an action promises that a retry does not repeat the work. Under the
-// process-scoped default that promise holds inside ONE process — a client retrying
-// \`POST /api/payments/charge\` after a timeout lands on another replica, which has never seen the
-// key, and charges the card twice, silently, with \`x verify\` green. Declaring \`'shared'\` is what
-// makes that a boot error (\`X_IDEMPOTENCY_NOT_SHARED\`) unless a shared store is installed.
-// \`runRole\` installs the Postgres one for you, on the connection it resolved from \`DATABASE_URL\`,
-// so the declaration is all this app owes. It must run before \`runRole\` imports the actions.
-
-/**
- * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
- * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
- * holds this module's bundled imports and none of the app's source, and the framework's registries
- * are filled by scanning that source at boot. So a binary reads its root from the directory it is
- * started in — it is a launcher for an app tree, not a self-contained copy of one.
- */
-const root = import.meta.dir.startsWith('/$bunfs')
-  ? process.cwd()
-  : join(import.meta.dir, '..', '..');
-
-// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
-// registries — an unguarded boot would start a server inside \`x verify\`.
-if (import.meta.main) {
-  await runRole({ root, env: Bun.env });
-}
-`;
-
-const prerender =
-  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
-// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
-// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
-//
-// Skipped is not unweighed: a route that declares a \`budget:\` is rendered in memory and measured
-// whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
-// this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
-// the reason is.
-
-import { join } from 'node:path';
-import { prerenderSite } from '@ultimat3/cli';
-
-const root = join(import.meta.dir, '..', '..');
-const flag = Bun.argv.indexOf('--out');
-const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
-// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
-// Property access, not \`Bun.env['SITE_ORIGIN']\`: the scaffolded tsconfig does not set
-// \`noPropertyAccessFromIndexSignature\`, so the bracket form is the one biome's useLiteralKeys
-// reports — a diagnostic in an app's first lint run over a file the app never wrote.
-const origin = Bun.env.SITE_ORIGIN;
-
-if (import.meta.main) {
-  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
-  await Bun.stdout.write(
-    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped, unmeasured: report.unmeasured })}\\n\`,
-  );
-}
-`;
-
 const placeholder = (surface: string, app: NameSet): string => `# ${surface}
 
 Placeholder. The monorepo shape exists now so adding ${surface} later is a new directory, not a
@@ -433,8 +368,8 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
-    { path: 'apps/web/server.ts', contents: server() },
-    { path: 'apps/web/prerender.ts', contents: prerender() },
+    // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
+    ...entryFiles(),
     { path: 'apps/web/site/icon.png', contents: icon() },
     { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
     { path: 'apps/web/site/page.module.scss', contents: siteStyle() },

package/src/templates/scaffold-container.ts

@@ -52,8 +52,10 @@ ENV NODE_ENV=production \\
 # own port mapping, its load balancer and every health probe alike.
 EXPOSE 3000
 
-# Every role serves /healthz and /readyz. /readyz flips to 503 on SIGTERM *before* the socket
-# closes, so a rolling restart drains in-flight work instead of dropping it.
+# The probe for the roles that SERVE HTTP — \`web\` and \`sync\`. /readyz flips to 503 on SIGTERM
+# *before* the socket closes, so a rolling restart drains in-flight work instead of dropping it.
+# Every other role opens the scrape listener alone and never binds $PORT, so each one overrides
+# this in docker/docker-compose.prod.yml rather than reporting \`unhealthy\` for its whole life.
 HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD \\
   bun --eval "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
 
@@ -120,6 +122,22 @@ x-image: &image
   depends_on:
     db: { condition: service_healthy }
 
+# The image's own HEALTHCHECK fetches \`/readyz\` on $PORT, and only \`web\` and \`sync\` open an HTTP
+# socket — every other role gets the scrape listener and nothing else. A service that inherits that
+# probe is fetching a port it never binds: it reports \`unhealthy\` for its whole life and anything
+# gated on it never starts. Probes follow the role here, exactly as they do in \`docker/helm\`.
+x-metrics-probe: &metrics-probe
+  test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:'+(process.env.METRICS_PORT||9090)+'/metrics').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+  interval: 10s
+  timeout: 3s
+  start_period: 30s
+  retries: 3
+
+# Run-once services exit. A probe against an exited container reports \`unhealthy\` forever, and
+# nothing waits on their health — \`service_completed_successfully\` is what the others gate on.
+x-run-once-probe: &run-once-probe
+  disable: true
+
 services:
   db:
     image: postgres:17-alpine
@@ -138,6 +156,7 @@ services:
     <<: *image
     environment: [ROLE=migrate]
     restart: 'no'
+    healthcheck: *run-once-probe
 
   # Run-once, AFTER the new version serves. Deliberately NOT part of the release gate: a slow
   # UPDATE there holds the deploy open against a database still serving the previous version.
@@ -158,6 +177,7 @@ services:
       # listing this last would only look like "after". The image's HEALTHCHECK is what makes it true.
       web: { condition: service_healthy }
     restart: 'no'
+    healthcheck: *run-once-probe
 
   web:
     <<: *image
@@ -184,6 +204,7 @@ services:
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
+    healthcheck: *metrics-probe
     deploy: { replicas: 1 } # scales on queue depth
 
   scheduler:
@@ -192,7 +213,12 @@ services:
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
-    deploy: { replicas: 1 } # fixed 1; leadership is a Postgres advisory lock
+    # Fixed 1. Leadership is an EXPIRING LEASE ROW in \`x_scheduler_leader\` (dev-roles.ts,
+    # driver-pg-ddl.ts), NOT an advisory lock: that grant belongs to the session, not to the
+    # process — it outlives every transaction and no pooled node can renew it or prove it still
+    # holds one. A second instance is harmless but idle.
+    healthcheck: *metrics-probe
+    deploy: { replicas: 1 }
 
 volumes:
   pgdata:
@@ -208,7 +234,7 @@ nothing to rebuild between staging and production.
 | \`web\` | HTTP: pages, actions, assets | \`$PORT\` (default 3000) |
 | \`sync\` | websockets for live queries | \`$PORT + 1\` |
 | \`worker\` | the job queue | — |
-| \`scheduler\` | cron tasks; leadership is a Postgres advisory lock | — |
+| \`scheduler\` | cron tasks; leadership is an expiring lease row in \`x_scheduler_leader\` | — |
 | \`replicator\` | the logical replication slot, exactly one per database | — |
 | \`migrate\` | applies pending migrations and **exits** | — |