@ultimat3/cli 7.0.0 → 8.0.0

package/src/templates/guard-raw-colour.ts

@@ -0,0 +1,138 @@
+// The `raw-colour` guard `x new` ships: no stylesheet in this app names a colour.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `verify-checks.ts` said it rode
+// on `packages/ui/src/tokens/tokens.test.ts`, which covers the framework's stylesheets and never
+// the app's, so `color: #ff0000` in a scaffolded `page.module.scss` was green on `x verify`.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'raw-colour';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-colour: every colour in this app is a semantic token, so dark theme is not a later project.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to. Delete it to drop the rule.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/** A hex literal. \`#{$x}\` is Sass interpolation, not a colour, and \`{\` is not a hex digit. */
+const HEX = /#[0-9a-fA-F]{3,8}\\b/;
+const CHANNEL_FUNCTION = /\\b(?:rgba?|hsla?|lab|lch|oklab|oklch|color)\\(/i;
+/** The named colours a human actually types. The full CSS list would report \`.item\` selectors. */
+const NAMED =
+  /\\b(?:white|black|red|green|blue|yellow|orange|purple|pink|brown|gray|grey|silver|navy|teal|olive|lime|aqua|maroon|fuchsia|gold|beige|coral|crimson|indigo|violet|khaki|salmon|tan|turquoise|wheat)\\b/i;
+
+/**
+ * A DECLARATION, never a whole line: a selector carries no colon, so \`#hero { … }\` is not a value
+ * and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ */
+const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+
+export interface StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+/**
+ * Comments blanked rather than removed, so the reported line number still points at the source
+ * line. \`//\` is skipped when a \`:\` precedes it — \`url(https://…)\` is a value, not a comment.
+ */
+const blankComments = (scss: string): string =>
+  scss
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/** Quoted text is a filename or a token name, never a colour: \`url('red.png')\`, \`role('bg')\`. */
+const unquote = (value: string): string => value.replaceAll(/'[^']*'|"[^"]*"/g, ' ');
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawColours(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = match[1] ?? '';
+      const value = unquote(match[2] ?? '');
+      const literal = HEX.exec(value) ?? CHANNEL_FUNCTION.exec(value) ?? NAMED.exec(value);
+      if (literal === null) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(scss, match.index)} sets \${property} to the raw colour \${literal[0]} — a value no theme can restate, so dark theme renders it unchanged\`,
+        fix: \`replace \${literal[0]} in \${file.path} with tokens.role('fg'), tokens.role('bg') or the role this element means, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a stylesheet names a semantic token, never a colour',
+  async check(root) {
+    const files: StyleFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.scss').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      if (path.includes('node_modules/')) continue;
+      files.push({ path, scss: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return rawColours(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { rawColours } from './raw-colour';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+
+unitTest('a hex literal in a declaration is refused', () => {
+  const findings = rawColours(sheet('.hero {\\n  color: #ff0000;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('#ff0000');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('rgb(), hsl() and a named colour are the same rule', () => {
+  expect(rawColours(sheet('.a { background: rgb(1 2 3); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { background: hsl(1 2% 3%); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { border-color: white; }'))).toHaveLength(1);
+});
+
+unitTest('a token, a selector and a quoted filename are not colours', () => {
+  expect(rawColours(sheet(".a { background: tokens.role('bg'); }"))).toEqual([]);
+  expect(rawColours(sheet('#hero { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet(".a { background: url('red-hero.png'); }"))).toEqual([]);
+});
+
+unitTest('a commented-out colour is a note, not a declaration', () => {
+  expect(rawColours(sheet('// color: #ff0000;\\n.a { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet('/* color: #ff0000; */\\n.a { padding: 0; }'))).toEqual([]);
+});
+`;
+
+/** `guards/raw-colour.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawColourGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/raw-colour.ts', contents: source() },
+  { path: 'guards/raw-colour.test.ts', contents: test() },
+];

package/src/templates/guard-untranslated-string.ts

@@ -0,0 +1,138 @@
+// The `untranslated-string` guard `x new` ships: no user-facing string is typed into a page.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — a hardcoded JSX string sitting
+// beside a `t()` call in a scaffolded page was green on `x verify`, and `x i18n check` cannot see
+// it either: a literal that is in no catalog is a literal the catalog audit has no key for.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'untranslated-string';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// untranslated-string: every user-facing string on a rendered surface goes through \`t()\`.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * \`<tag …>text</tag>\`, matched on the CLOSING tag rather than on the next \`<\`.
+ *
+ * That is the whole reason this rule can run over TypeScript at all: \`createSignal<State>('idle')\`
+ * is a \`>\` followed by prose-shaped source, and a pattern reading to the next \`<\` reports every
+ * generic in the file. A closing tag that names the same element cannot be a type argument.
+ *
+ * Only the INNERMOST element matches — the content class excludes \`<\` and \`>\` — which is what the
+ * rule wants: a parent whose children are elements has no text of its own.
+ */
+const ELEMENT = /<([A-Za-z][\\w.:-]*)(?:\\s[^<>]*)?>([^<>]*?)<\\/\\1>/g;
+/** A \`{…}\` child is an expression — \`{t('key')}\`, \`{props.row.title}\` — never typed prose. */
+const EXPRESSION = /\\{[^{}]*\\}/g;
+/** Two word characters in a row. One is \`&\`, \`×\`, an initial — never a sentence. */
+const PROSE = /[\\p{L}\\p{N}]{2,}/u;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function untranslatedStrings(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(ELEMENT)) {
+      const typed = (match[2] ?? '').replaceAll(EXPRESSION, ' ').trim();
+      if (!PROSE.test(typed)) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(text, match.index)} renders the typed string "\${typed}" inside <\${match[1] ?? 'element'}> — it is in no catalog, so every locale but the one it was typed in reads it verbatim\`,
+        fix: \`add a key for "\${typed}" to packages/i18n/catalogs/en.json, render it as {t('…')} in \${file.path}, then: x i18n check\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a rendered string comes from t(), never typed into the page',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // Every rendered surface: an app's \`site/\` and \`app/\`, and the shared components under
+    // \`packages/*/src\` — \`x new\` scaffolds a \`packages/ui\` whose components render to a user, so
+    // a hardcoded string there used to be green. \`api/\` renders nothing and \`shared/\` is a leaf of
+    // helpers; \`packages/*/dist\` is a build output, not source.
+    //
+    // TWO globs, never one with a leading \`{a,b}\` group: \`Bun.Glob.scan()\` matches nothing at all
+    // for a pattern that starts with a brace group — measured — so folding these into one line
+    // silently turns the guard off, which is worse than the hole it closes.
+    for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
+        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      }
+    }
+    return untranslatedStrings(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { untranslatedStrings } from './untranslated-string';
+
+const file = (source: string) => [{ path: 'apps/web/site/page.tsx', source }];
+
+unitTest('a typed JSX string is refused, and the finding quotes it', () => {
+  const findings = untranslatedStrings(file('<h1>Welcome back</h1>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('Welcome back');
+});
+
+unitTest('a t() child satisfies it, and so does any other expression', () => {
+  expect(untranslatedStrings(file("<h1>{t('site.home.title')}</h1>"))).toEqual([]);
+  expect(untranslatedStrings(file('<li class={styles.item}>{row.title}</li>'))).toEqual([]);
+});
+
+// The reason the rule reads a CLOSING tag: a generic type argument is a > followed by source that
+// looks exactly like prose, and a pattern reading to the next < reports every one of them.
+unitTest('a generic type argument is not a JSX text node', () => {
+  const generic = "const [state, setState] = createSignal<SaveState>('idle');\\nconst n = 1;";
+  expect(untranslatedStrings(file(generic))).toEqual([]);
+});
+
+unitTest('one word character is a symbol, not a sentence', () => {
+  expect(untranslatedStrings(file('<span>&</span>'))).toEqual([]);
+});
+`;
+
+/** `guards/untranslated-string.ts` and its test. The directory is the registration. */
+export const untranslatedStringGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/untranslated-string.ts', contents: source() },
+  { path: 'guards/untranslated-string.test.ts', contents: test() },
+];

package/src/templates/guard-unzoned-date.ts

@@ -0,0 +1,142 @@
+// The `unzoned-date` guard `x new` ships: no date is formatted without an explicit IANA zone.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `toLocaleDateString('en-US')`
+// in a scaffolded page was green on `x verify`, and it renders the SERVER's zone, so the same row
+// reads as two different days depending on which container answered.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'unzoned-date';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// unzoned-date: a date is stored in UTC and formatted with an explicit IANA zone, never with the
+// host's ambient one. \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside
+// the \`boundaries\` step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/** Every call whose output depends on a zone. The \`(\` is the start of the argument list. */
+const FORMATTER = /(?:\\.toLocale(?:Date|Time)?String|Intl\\.DateTimeFormat)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/**
+ * Comments blanked IN PLACE — not deleted — so the line number a finding reports still points at
+ * the source line. What it does not blank is a string body: a call spelled inside a quoted string
+ * is reported, which is the one false positive this rule can produce and the reason its own test
+ * lives in \`guards/\`, which nothing here scans.
+ */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/**
+ * The call's own argument list, from its \`(\` to the \`)\` that closes it. Depth-counted rather
+ * than "up to the next \`)\`": \`toLocaleDateString(locale, { timeZone: zoneFor(x) })\` closes twice
+ * before the one that ends the call, and reading only the first would report a zoned call.
+ */
+function argumentsOf(text: string, open: number): string {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '(') depth += 1;
+    else if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return text.slice(open + 1, index);
+    }
+  }
+  return text.slice(open + 1);
+}
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(FORMATTER)) {
+      const open = match.index + match[0].length - 1;
+      if (argumentsOf(text, open).includes('timeZone')) continue;
+      const line = lineOf(text, match.index);
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
+        fix: \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a date is never formatted without an explicit IANA time zone',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test's subject is often the wrong shape on purpose, and \`node_modules\` is not this
+      // app's source. Neither exclusion hides a rendered date from a user.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return unzonedDates(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { unzonedDates } from './unzoned-date';
+
+const file = (source: string) => [{ path: 'apps/web/app/dashboard/page.tsx', source }];
+
+unitTest('toLocaleDateString with no timeZone is refused', () => {
+  const findings = unzonedDates(file("const shown = at.toLocaleDateString('en-US');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.fix).toContain('timeZone');
+});
+
+unitTest('an explicit zone satisfies it, even nested behind another call', () => {
+  const zoned = "at.toLocaleDateString('en-US', { timeZone: zoneFor(actor) });";
+  expect(unzonedDates(file(zoned))).toEqual([]);
+});
+
+unitTest('Intl.DateTimeFormat and toLocaleTimeString are the same rule', () => {
+  expect(unzonedDates(file("new Intl.DateTimeFormat('en-US').format(at);"))).toHaveLength(1);
+  expect(unzonedDates(file("at.toLocaleTimeString('en-US');"))).toHaveLength(1);
+});
+
+unitTest('a commented-out call is a note, not a call', () => {
+  expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
+});
+`;
+
+/** `guards/unzoned-date.ts` and its test. No index, no registry — the directory registers it. */
+export const unzonedDateGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/unzoned-date.ts', contents: source() },
+  { path: 'guards/unzoned-date.test.ts', contents: test() },
+];

package/src/templates/index.ts

@@ -39,6 +39,9 @@ export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
+export { entryFiles } from './scaffold-entries';
+// The four guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
+export { scaffoldGuardFiles } from './scaffold-guards';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
 export type { SliceModule } from './slice-foundation';

package/src/templates/island.ts

@@ -78,7 +78,8 @@ export function mount(el: HTMLElement, props: ${Name}Props): void {
 `;
 };
 
-const islandStyle = (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and
+const islandStyle =
+  (): string => `// Semantic tokens only — a raw hex here is refused by the boundaries step, not by lint — a dark-theme bug and
 // a lint failure. Scoped by the island build, with the class names the server hashed.
 @use '@ultimat3/ui/tokens' as tokens;
 

package/src/templates/route.ts

@@ -138,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';
 
@@ -349,86 +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.
-//
-// It writes the whole of \`pages\` and \`skipped\`, never a COUNT of either. A count is what let a
-// partial artifact read as a complete one: someone pointed a screenshot tool at \`.x/static\` and
-// filed "the island did not mount" against a route that had never been emitted (issue #242). Each
-// skipped route carries its own \`reason\` and \`why\`, and \`report\` is where the same inventory
-// landed on disk — which is what \`x build --target static --json\` reads back.
-
-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, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report })}\\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
@@ -447,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** | — |