@ultimat3/cli 22.15.0 → 24.0.0

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

@@ -2,13 +2,16 @@
 // and the deterministic seed. No business logic — that is the package's own stated boundary, and it
 // is why `example` reaches only the two files describing the slice's table.
 //
-// No migration. `x db gen` is the ONE writer of `packages/db/migrations`, and a scaffold that hand-
-// wrote `0000_initial.sql` was a second one: it declared a `posts` table the generator had never
-// diffed, so the first `x db gen` saw a schema the ledger already claimed and the two disagreed
-// about what "initial" meant. `x db gen "initial"` is the app's first command instead — it writes
-// the `.sql`, the `.snapshot.json` and the `.hash` together, which no hand-written file can.
+// No migration and no schema dump. `x db gen` is the ONE writer of `packages/db/migrations` and
+// of `packages/db/schema`, and a scaffold that hand-wrote `0000_initial.sql` was a second one: it
+// declared a `posts` table the generator had never diffed, so the first `x db gen` saw a schema
+// the ledger already claimed and the two disagreed about what "initial" meant. `x db gen
+// "initial"` is the app's first command instead — it writes the `.sql`, the `.snapshot.json`, the
+// `.hash` and the dump together, which no hand-written file can.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
+import { dbClientFiles } from './scaffold-db-client';
 import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
 
 const DESCRIPTION = 'Entity re-exports and SQL migrations, no business logic';
@@ -45,10 +48,14 @@ const dbPackage = (app: NameSet, example: boolean): string =>
     : workspacePackageJson(app, 'db', DESCRIPTION);
 
 const dbIndex =
-  (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
-// @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
+  (): string => `// Schema, migrations and the typed handle — no business logic lives in this package.
+// \`db\` is the handle \`./client\` builds over the app's entities: \`db.<table>\`, which is what a
+// feature's repo.ts reads through. \`sql\` and \`withTransaction\` are @ultimat3/db's own, and the
+// connection pool behind all three is one, sized by ROLE.
 export type { DbClient, SqlFragment } from '@ultimat3/db';
-export { db, sql, withTransaction } from '@ultimat3/db';
+export { sql, withTransaction } from '@ultimat3/db';
+export type { Db } from './client';
+export { db, driver, selectDriver } from './client';
 export * as schema from './schema';
 `;
 
@@ -151,11 +158,86 @@ export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
 });
 `;
 
+const dbSeedTest = (app: NameSet, example: boolean): string =>
+  example
+    ? `// The seed, run against the in-memory driver: the rows it writes, whose they are, and that a
+// second run writes nothing. The org is the point — a row seeded under any other id is one the
+// development viewer's tenant policy refuses, and the dashboard then counts zero.
+${sortedImports([
+  `import { DEMO_ORG_ID } from '@${app.kebab}/web/shared/demo-org';`,
+  "import { createContext, runWithContext } from '@ultimat3/core';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
+])}
+import { db, driver } from './client';
+import { ${app.camel}Seed } from './seed';
+
+/** The development viewer's org: every read below runs as an actor inside it. */
+const asViewer = <T>(run: () => Promise<T>): Promise<T> =>
+  runWithContext(createContext({ actor: testActor('viewer', { orgId: DEMO_ORG_ID }).actor }), run);
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('the seed writes its posts under the demo org', async () => {
+  const run = await ${app.camel}Seed.run({ driver });
+  expect(run.metrics).toEqual({ inserted: 2, updated: 0, skipped: 0 });
+  const rows = await asViewer(() => db.posts.where({ orgId: DEMO_ORG_ID }).orderBy('title').all());
+  expect(rows.map((row) => row.title)).toEqual(['Hello ${app.pascal}', 'Second post']);
+  expect(rows.map((row) => row.price.minor)).toEqual([0, 1900]);
+});
+
+unitTest('a replay writes nothing: its ids are derived from labels, never generated', async () => {
+  await ${app.camel}Seed.run({ driver });
+  const replay = await ${app.camel}Seed.run({ driver });
+  expect(replay.metrics).toEqual({ inserted: 0, updated: 0, skipped: 2 });
+});
+`
+    : `// The seed as \`x db seed\` finds it: a declared \`defineSeed()\` under this app's name, which
+// writes nothing until an entity exists. The day it inserts a row, the last assertion says so.
+import { isSeed } from '@ultimat3/entity';
+import { expect, unitTest } from '@ultimat3/testing';
+import { driver } from './client';
+import { ${app.camel}Seed } from './seed';
+
+unitTest('the seed is one x db seed discovers, in the dev tier', () => {
+  expect(isSeed(${app.camel}Seed)).toBe(true);
+  expect(${app.camel}Seed.name).toBe('${app.kebab}');
+  // \`dev\`: fixture data, never loaded into production. \`reference\` is the other tier.
+  expect(${app.camel}Seed.tier).toBe('dev');
+});
+
+unitTest('it writes nothing yet', async () => {
+  const run = await ${app.camel}Seed.run({ driver });
+  expect(run.metrics).toEqual({ inserted: 0, updated: 0, skipped: 0 });
+});
+`;
+
+/**
+ * `packages/db/schema/` is written by `x db gen` and held by the `drift` step, so two things about
+ * it are git's to know. `linguist-generated` collapses it in a review — the migration is what a
+ * human reads; the dump is its projection. `text eol=lf` is not cosmetic: the gate compares bytes,
+ * and a checkout that rewrote line endings would be `X_SCHEMA_DUMP_DRIFT` on a correct tree.
+ *
+ * The attributes ship; the directory does not. `x new` scaffolds no migration, so there is nothing
+ * to dump until the first `x db gen` — which creates it.
+ */
+export const DB_GITATTRIBUTES = `# Generated by \`x db gen\` from the migrations and held equal to them by \`x verify\`'s drift
+# step (X_SCHEMA_DUMP_DRIFT). Review the migration, not this projection of it.
+schema/** linguist-generated=true text eol=lf
+`;
+
 /** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
 export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [
   { path: 'packages/db/package.json', contents: dbPackage(app, example) },
+  { path: 'packages/db/.gitattributes', contents: DB_GITATTRIBUTES },
   ...packageShapeFiles(app, 'db', DESCRIPTION),
   { path: 'packages/db/src/index.ts', contents: dbIndex() },
+  // The typed handle and its test — `scaffold-db-client.ts`, shared with `x g entity`.
+  ...dbClientFiles(app, example),
   { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },
   { path: 'packages/db/src/seed.ts', contents: dbSeed(app, example) },
+  { path: 'packages/db/src/seed.test.ts', contents: dbSeedTest(app, example) },
 ];

package/src/templates/scaffold-docs.ts

@@ -22,14 +22,23 @@ not exist — five of these had an empty column and were each measured green on
 | Rule | Detail | Refused by |
 |---|---|---|
 | One gate | \`bin/check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request |
+| Coverage | the unit suite covers 95% of the lines and functions of this app's own source — every file under \`apps/\` and \`packages/\`, one no test loads counted at 0%. A floor, not the goal: a test added to raise it is proven by mutation — break the source, watch it go red, restore | \`X_COVERAGE_BELOW_FLOOR\` on the \`unit\` step; \`coverage\` in \`x.verify.json\` states the floor, and it only rises |
 | One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
 | Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
 | Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
+| Repos | a \`repo.ts\` reads through the typed handle, never a \`sql\` literal the handle can express | \`guards/repo-raw-sql.ts\` |
 | Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix | \`guards/bare-error.ts\` |
 | Money | \`{ minor, currency }\`, never a float — \`money()\` on the column | the type: \`price: 19.99\` is TS2322, \`number\` is not \`MoneyInput\` |
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+| Lengths | a length is a token or \`rem()\`, never a raw \`px\` | \`guards/raw-length.ts\` |
+| Breakpoints | a viewport query names a breakpoint rung (\`respond-up\`, \`respond-down\`, \`respond-between\`), never a width | \`guards/raw-breakpoint.ts\` |
+| Layers | a \`z-index\` is a named layer, never a number | \`guards/raw-z-index.ts\` |
+| Shadows | a shadow comes off the shadow scale, never a hand-written offset and blur | \`guards/raw-shadow.ts\` |
+| Timing | a duration and an easing curve come off the motion scale, never a literal | \`guards/raw-motion.ts\` |
+| Classes | a class a component reads off its stylesheet is one that sheet compiles | \`guards/undefined-style-class.ts\` |
+| Properties | a custom property a stylesheet reads is one the app declares | \`guards/undeclared-custom-property.ts\` |
 | Interaction | a click is answered by a control — never a \`<div onClick>\`, and never a \`role=\` where the native tag exists | \`guards/semantic-interactive.ts\` |
 | Focus | \`outline: none\` replaces the ring in the same rule or the one beside it, or it does not remove it | \`guards/focus-visible.ts\` |
 | Images | every image carries width + height or an aspect-ratio, and the priority one is never \`loading="lazy"\` | \`guards/image-dimensions.ts\` |
@@ -51,6 +60,23 @@ unit of review, and \`x verify\` refuses it. The one exemption is a file that is
 it has one job by construction, and its length tracks the API's size rather than its complexity;
 one statement of logic in such a file re-arms the ceiling on the same save.
 
+Coverage counts execution, not validation: 100% is reachable with zero assertions, and a covered
+branch whose test cannot fail is worse than an uncovered one, because it reads as done. An
+\`exclude\` entry under \`coverage\` is for code a unit test cannot execute — an island's
+browser-only mount, a container entry point — carries its \`why\`, and is printed by \`x doctor\`.
+
+Every test the scaffold and the generators write is the idiom to copy. All of them run on the
+\`unit\` step — in process, on the in-memory driver, with no database, browser or server:
+
+| What | How its test runs it | Copy from |
+|---|---|---|
+| a page | \`renderRoute(page, { url, actor })\` — \`load\`, \`meta\` and the page on one resolution; assert on \`view.text\`, \`view.html\`, \`view.meta\`, \`view.islands\` | \`apps/web/app/dashboard/page.test.ts\` |
+| a component | \`renderView(Component, props)\` | \`apps/web/shared/shell.test.ts\` |
+| an island | \`mountIsland\`, once per state its \`*.island.states.ts\` declares | \`apps/web/shared/theme-toggle.island.test.ts\` |
+| an action or a query | \`target.as(actor, input)\` — the refusal first, then what it answers | \`apps/web/api/health.test.ts\` |
+| a job, a task, a backfill | \`test('…', async ({ runJobs }) => …)\` — a worker in this process; assert on \`trace.steps\` and each run's \`outcome\` | what \`x g job\` writes |
+| a repo, a seed | as an actor, \`runWithContext(createContext({ actor }), …)\`, with \`driver.reset?.()\` after each | \`packages/db/src/seed.test.ts\` |
+
 Money is the one row with no guard, deliberately: a float has no static signature a text rule can
 see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
@@ -86,6 +112,9 @@ ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in t
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
   only place that list is stated.
 - Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
+- \`x db gen\` also writes \`packages/db/schema/\` — the whole schema as SQL, one file per table.
+  Read it; never edit it. \`x verify\` fails with \`X_SCHEMA_DUMP_DRIFT\` when it is not what the
+  migrations produce, and \`x db gen\` rewrites it.
 - \`x doctor\` explains a broken environment and prints the fix command for every finding.
 
 \`.claude/\` holds the harness that reads this file: \`/feature\`, \`/planx\`, \`/verify\` and four
@@ -182,7 +211,12 @@ exec bunx x verify "$@"
 
 const composeDev = (
   app: NameSet,
-): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+): string => `# Optional: x dev needs none of this. Use it when you want a real Postgres, NATS and S3 locally:
+#
+#   docker compose -f docker/docker-compose.dev.yml up -d
+#   DATABASE_URL=postgres://postgres:${app.kebab}@127.0.0.1:5432/${app.kebab} NATS_URL=nats://127.0.0.1:4222 \\
+#   S3_ENDPOINT=http://127.0.0.1:9000 S3_BUCKET=${app.kebab} S3_FORCE_PATH_STYLE=1 \\
+#   S3_ACCESS_KEY_ID=${app.kebab} S3_SECRET_ACCESS_KEY=${app.kebab}-dev x dev
 #
 # Every published port binds 127.0.0.1, not 0.0.0.0. This stack ships its credentials in the file,
 # as a dev stack reasonably does — so the short form \`'5432:5432'\` would put an authenticated
@@ -204,13 +238,24 @@ services:
     image: nats:2-alpine
     command: ['-js']
     ports: ['127.0.0.1:4222:4222']
+  # Versity S3 Gateway over a directory: a directory under /data is a bucket, so the volume mounted
+  # at /data/${app.kebab} IS the bucket — ready on the first \`up\`, no CreateBucket call. It checks
+  # the region a request was signed for, and an app that sets no S3_REGION signs for \`auto\` — so
+  # that is this gateway's region. A server for a laptop; production is any S3-compatible endpoint.
   s3:
-    image: minio/minio
-    command: ['server', '/data']
+    image: versity/versitygw:v1.8.0
     environment:
-      MINIO_ROOT_USER: ${app.kebab}
-      MINIO_ROOT_PASSWORD: ${app.kebab}-dev
+      VGW_BACKEND: posix
+      VGW_BACKEND_ARG: /data
+      VGW_PORT: ':9000'
+      VGW_REGION: auto
+      ROOT_ACCESS_KEY: ${app.kebab}
+      ROOT_SECRET_KEY: ${app.kebab}-dev
     ports: ['127.0.0.1:9000:9000']
+    volumes: ['s3bucket:/data/${app.kebab}']
+
+volumes:
+  s3bucket:
 `;
 
 /** Docs, shims and container files for a new app, in the order a reader meets them. */

package/src/templates/scaffold-guards.ts

@@ -11,31 +11,74 @@
 // about: a control a keyboard cannot reach, a focus ring taken away and not replaced, an image with
 // no box, an animation the compositor cannot run, and an island nobody has seen fail. Each is
 // statically decidable from the file alone — the reason those five and not the many that are not.
+//
+// The seven after those are about the STYLESHEET, which Biome does not read at all: a length, a
+// breakpoint, a layer, a shadow and a tempo off their scales, a class the sheet never compiled and
+// a custom property nothing declares. Until they shipped, raw colour was the only one of the
+// design system's rules a scaffolded app's gate held.
+//
+// And one is about DATA: a `repo.ts` reads through the typed handle. It ships because the generator
+// used to emit string SQL, and every app that started from it copied the shape.
 
 import { animatedLayoutPropertyGuardFiles } from './guard-animated-layout-property';
 import { bareErrorGuardFiles } from './guard-bare-error';
 import { focusVisibleGuardFiles } from './guard-focus-visible';
 import { imageDimensionsGuardFiles } from './guard-image-dimensions';
 import { islandWithoutStatesGuardFiles } from './guard-island-without-states';
+import { rawBreakpointGuardFiles } from './guard-raw-breakpoint';
 import { rawColourGuardFiles } from './guard-raw-colour';
+import { rawLengthGuardFiles } from './guard-raw-length';
+import { rawMotionGuardFiles } from './guard-raw-motion';
+import { rawShadowGuardFiles } from './guard-raw-shadow';
+import { rawZIndexGuardFiles } from './guard-raw-z-index';
+import { repoRawSqlGuardFiles } from './guard-repo-raw-sql';
 import { semanticInteractiveGuardFiles } from './guard-semantic-interactive';
+import { undeclaredCustomPropertyGuardFiles } from './guard-undeclared-custom-property';
+import { undefinedStyleClassGuardFiles } from './guard-undefined-style-class';
 import { untranslatedStringGuardFiles } from './guard-untranslated-string';
 import { unzonedDateGuardFiles } from './guard-unzoned-date';
 import type { GeneratedFile } from './naming';
 
+/**
+ * Every guard the framework ships, by the name its file carries — the ONE list. `x new` writes all
+ * of them (`scaffoldGuardFiles`), `x g guard <name>` writes the one it is asked for by name
+ * (`shippedGuardFiles`), and `x doctor` names the ones an app does not have. Sorted, so the three
+ * agree on an order. A new shipped guard is one module beside these and one row here.
+ */
+const SHIPPED: readonly (readonly [string, () => readonly GeneratedFile[]])[] = [
+  ['animated-layout-property', animatedLayoutPropertyGuardFiles],
+  ['bare-error', bareErrorGuardFiles],
+  ['focus-visible', focusVisibleGuardFiles],
+  ['image-dimensions', imageDimensionsGuardFiles],
+  ['island-without-states', islandWithoutStatesGuardFiles],
+  ['raw-breakpoint', rawBreakpointGuardFiles],
+  ['raw-colour', rawColourGuardFiles],
+  ['raw-length', rawLengthGuardFiles],
+  ['raw-motion', rawMotionGuardFiles],
+  ['raw-shadow', rawShadowGuardFiles],
+  ['raw-z-index', rawZIndexGuardFiles],
+  ['repo-raw-sql', repoRawSqlGuardFiles],
+  ['semantic-interactive', semanticInteractiveGuardFiles],
+  ['undeclared-custom-property', undeclaredCustomPropertyGuardFiles],
+  ['undefined-style-class', undefinedStyleClassGuardFiles],
+  ['untranslated-string', untranslatedStringGuardFiles],
+  ['unzoned-date', unzonedDateGuardFiles],
+];
+
+/** The names, in the order every list of them is shown. */
+export const SHIPPED_GUARD_NAMES: readonly string[] = SHIPPED.map(([name]) => name);
+
+/**
+ * The shipped guard of that name with its test, or `undefined` when the name is not one — which
+ * is an app's own convention, and `x g guard` then writes the blank template instead.
+ */
+export const shippedGuardFiles = (name: string): readonly GeneratedFile[] | undefined =>
+  SHIPPED.find(([shipped]) => shipped === name)?.[1]();
+
 /**
  * Every guard `x new` ships, each with its test. One module per guard, because an app deletes a
  * rule it does not want by deleting one file — and a guard the app then writes for itself is
  * `x g guard <name>`, the same shape.
  */
-export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
-  ...animatedLayoutPropertyGuardFiles(),
-  ...bareErrorGuardFiles(),
-  ...focusVisibleGuardFiles(),
-  ...imageDimensionsGuardFiles(),
-  ...islandWithoutStatesGuardFiles(),
-  ...rawColourGuardFiles(),
-  ...semanticInteractiveGuardFiles(),
-  ...untranslatedStringGuardFiles(),
-  ...unzonedDateGuardFiles(),
-];
+export const scaffoldGuardFiles = (): readonly GeneratedFile[] =>
+  SHIPPED.flatMap(([, files]) => files());

package/src/templates/scaffold-helm-fences.ts

@@ -0,0 +1,76 @@
+// What a compromised pod of the scaffolded chart can reach: its `/tmp`, bounded, and its ports,
+// fenced by one NetworkPolicy per role. The framework chart's own (`docker/helm/`), mirrored —
+// `scaffold-helm-parity.test.ts` holds the two to each other.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const volumes = (app: NameSet): string => `{{/*
+The writable scratch every pod mounts at /tmp — the root filesystem is read-only. Bounded, because
+an emptyDir with no sizeLimit is node disk: one role filling /tmp evicts its NEIGHBOURS for disk
+pressure, where with a limit the kubelet evicts that pod alone.
+*/}}
+{{- define "${app.kebab}.tmpVolume" -}}
+- name: tmp
+  emptyDir:
+    sizeLimit: {{ required "tmp.sizeLimit is unset — set it in your values (e.g. 512Mi): an unbounded /tmp is node disk" (default dict .Values.tmp).sizeLimit | quote }}
+{{- end -}}
+`;
+
+const networkPolicy = (app: NameSet): string => `{{/*
+One NetworkPolicy per enabled role: \`http\` (web, sync) from networkPolicy.httpFrom, \`metrics\`
+(every role) from networkPolicy.metricsFrom, nothing else. A \`from\` that renders empty is omitted,
+which Kubernetes reads as "any source". Egress is filtered only when networkPolicy.egress lists
+rules — the database, NATS and object store are your addresses, so list DNS too. Serving roles
+only: the migrate Job is a pre-install hook that runs before this exists, and opens no port.
+*/}}
+{{- if .Values.networkPolicy.enabled }}
+{{- range $role, $cfg := .Values.roles }}
+{{- if $cfg.enabled }}
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  podSelector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ $.Release.Name }}
+      app.kubernetes.io/component: {{ $role }}
+  policyTypes:
+    - Ingress
+    {{- if $.Values.networkPolicy.egress }}
+    - Egress
+    {{- end }}
+  ingress:
+    {{- if $cfg.port }}
+    - ports:
+        - port: http
+          protocol: TCP
+      {{- with $.Values.networkPolicy.httpFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+    {{- end }}
+    - ports:
+        - port: metrics
+          protocol: TCP
+      {{- with $.Values.networkPolicy.metricsFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+  {{- with $.Values.networkPolicy.egress }}
+  egress: {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
+{{- end }}
+{{- end }}
+`;
+
+/** The bounded /tmp helper and the per-role NetworkPolicy, as two files of the chart's templates. */
+export function helmFenceFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/helm/templates/_volumes.tpl', contents: volumes(app) },
+    { path: 'docker/helm/templates/networkpolicy.yaml', contents: networkPolicy(app) },
+  ];
+}

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

@@ -3,6 +3,7 @@
 // Split from scaffold-helm.ts, which holds the chart's INPUTS (Chart.yaml, values.yaml).
 
 import type { GeneratedFile, NameSet } from './naming';
+import { helmFenceFiles } from './scaffold-helm-fences';
 
 const helpers = (
   app: NameSet,
@@ -79,13 +80,28 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     - name: METRICS_PORT
       value: {{ $root.Values.metricsPort | quote }}
     {{- end }}
+    {{- /*
+    The sync node's page origin, from the one place this chart already knows it. Undeclared, a node
+    reached over plain http behind this Ingress admits BOTH spellings of its host — the plain-http
+    page included. env.APP_URL wins when set; an APP_URL kept in the Secret is shadowed for this
+    role, so pages served from another host than the Ingress's must say so in env.
+    */}}
+    {{- if and (eq $role "sync") $root.Values.ingress.enabled (not (hasKey $root.Values.env "APP_URL")) }}
+    - name: APP_URL
+      value: {{ printf "%s://%s" (ternary "https" "http" $root.Values.ingress.tls) $root.Values.ingress.host | quote }}
+    {{- end }}
     {{- range $key, $value := $root.Values.env }}
     - name: {{ $key }}
       value: {{ $value | quote }}
     {{- end }}
+  {{- /*
+  The Secret a role reads, per role: roles.<role>.existingSecret (or migrate.existingSecret) names a
+  narrower one than the release-wide existingSecret, so the migrate Job's schema-owning credential
+  need not sit on a web pod. Both unset is a render error, not a pod with no configuration.
+  */}}
   envFrom:
     - secretRef:
-        name: {{ $root.Values.existingSecret }}
+        name: {{ required (printf "no Secret for role %s — set existingSecret, or roles.%s.existingSecret, in your values" $role $role) (default $root.Values.existingSecret $cfg.existingSecret) }}
   {{- if or $cfg.port $scraped }}
   ports:
     {{- if $cfg.port }}
@@ -100,8 +116,10 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   {{/*
   Probes follow the role, because the roles do not agree on what they open. web and sync serve
   HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
-  listener is their only port — so they take liveness on it and NO readiness: nothing routes to
-  them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+  listener is their only port — so they take liveness on it. Readiness for replicator alone, on
+  /readyz of that listener: 503 while the replication stream is down, so the pod shows 0/1 instead
+  of a healthy pod feeding nothing. Their headless Service publishes not-ready addresses, so a
+  not-ready pod is still scraped.
 
   Every one of them takes a startupProbe too, because no listener opens early: the server builds
   the app's islands before any role binds a port, and a liveness probe counting from container
@@ -134,6 +152,11 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 5
     failureThreshold: 30
+  {{- if eq $role "replicator" }}
+  readinessProbe:
+    httpGet: { path: '/readyz?deep=1', port: metrics }
+    periodSeconds: 10
+  {{- end }}
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
@@ -194,8 +217,7 @@ spec:
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" $ | nindent 8 }}
 {{- end }}
 {{- end }}
 `;
@@ -219,6 +241,9 @@ spec:
   type: ClusterIP
   {{- if not $cfg.port }}
   clusterIP: None
+  # Scraped whether or not ready: a replicator whose stream is down (readiness 503) is the pod
+  # whose metrics matter most, and nothing routes to these addresses anyway.
+  publishNotReadyAddresses: true
   {{- end }}
   selector:
     app.kubernetes.io/instance: {{ $.Release.Name }}
@@ -267,8 +292,7 @@ spec:
       containers:
         {{- include "${app.kebab}.container" (dict "role" "migrate" "cfg" .Values.migrate "root" .) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" . | nindent 8 }}
 {{- end }}
 `;
 
@@ -382,5 +406,6 @@ export function helmTemplateFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'docker/helm/templates/migrate-job.yaml', contents: migrateJob(app) },
     { path: 'docker/helm/templates/ingress.yaml', contents: ingress(app) },
     { path: 'docker/helm/templates/hpa.yaml', contents: hpa(app) },
+    ...helmFenceFiles(app),
   ];
 }

package/src/templates/scaffold-helm.ts

@@ -31,11 +31,41 @@ image:
 
 # Non-secret configuration. Secrets come from an existing Secret, never from this file:
 #   kubectl create secret generic ${app.kebab}-secrets --from-literal=DATABASE_URL=...
+#
+# APP_URL — the pages' public origin — is what the sync node admits a websocket from. With the
+# ingress below enabled the chart SETS it on the sync role from ingress.host (https when
+# ingress.tls), because an undeclared node behind a TLS ingress also admits the plain-http page.
+# Set it here when the pages are served from another host or port than that (a CDN domain, a
+# SYNC_URL of its own): this value wins, and without it every websocket from those pages is
+# 403 X_SOCKET_ORIGIN_REFUSED.
 env:
   NODE_ENV: production
 
 existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, ULTIMATE_CURSOR_SECRET
 
+# The release-wide Secret above is every role's DEFAULT: \`existingSecret\` under a role
+# (roles.web.existingSecret, migrate.existingSecret) names that role's own, so the migrate Job's
+# schema-owning DATABASE_URL need not sit on a web pod.
+
+# The /tmp every pod mounts (the root filesystem is read-only), bounded: past this the kubelet
+# evicts the pod that filled it, never its neighbours for node disk pressure.
+tmp:
+  sizeLimit: 512Mi
+
+# One NetworkPolicy per serving role (templates/networkpolicy.yaml): \`http\` from httpFrom,
+# \`metrics\` from metricsFrom, nothing else. Inert on a CNI that does not enforce NetworkPolicy.
+#   httpFrom     empty = any source; narrow it to your ingress controller's namespace, e.g.
+#                [{ namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: ingress-nginx } } }]
+#   metricsFrom  default: any pod in the cluster and no address outside it
+#   egress       OFF while empty; a list turns on egress filtering with exactly those rules —
+#                the database, NATS, the object store and DNS are your addresses, so list all of them
+networkPolicy:
+  enabled: true
+  httpFrom: []
+  metricsFrom:
+    - namespaceSelector: {}
+  egress: []
+
 # The scrape listener every serving role opens, on its own port and never the app's: the ingress
 # routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
 # METRICS_PORT in the container; move one and the other follows.
@@ -153,7 +183,7 @@ ingress:
 `;
 
 /**
- * The chart for a new app: five kinds of object, all of them core Kubernetes. A ServiceMonitor and
+ * The chart for a new app: six kinds of object, all of them core Kubernetes. A ServiceMonitor and
  * a PodDisruptionBudget are deliberately absent — the first needs a CRD `helm install` fails on
  * where no Prometheus operator is installed, and both are cluster policy rather than app topology.
  */

package/src/templates/scaffold-http.ts

@@ -49,27 +49,29 @@ const httpConfigTest =
 // only thing that can go wrong is nobody importing the module — which is exactly how a shipped app
 // rendered every string as ⟦key⟧ for a whole release (issue #249), one seam along.
 import { configuredHttp, resetHttpConfig } from '@ultimat3/http';
-import { expect, unitTest } from '@ultimat3/testing';
+import { afterAll, expect, unitTest } from '@ultimat3/testing';
 import './http';
 
+// Read ONCE, at module scope: every case asserts on what the import registered, in any order.
+const declared = configuredHttp();
+
 unitTest('importing the module IS the registration', () => {
-  const declared = configuredHttp();
-  expect(declared).toBeDefined();
   // The list is empty on a fresh scaffold and that is the shipped default; what is asserted is
   // that the KEY reaches the boot, so adding an origin to it takes effect.
   expect(declared?.cors?.origins).toEqual([]);
 });
 
 unitTest('the boot-owned keys are absent — the boot measures them, an app can only guess', () => {
-  const declared = configuredHttp() ?? {};
+  expect(declared).toBeDefined();
   for (const key of ['port', 'hostname', 'dev', 'buildId', 'signInPath']) {
-    expect({ key, declared: Object.hasOwn(declared, key) }).toEqual({ key, declared: false });
+    expect({ key, declared: Object.hasOwn(declared ?? {}, key) }).toEqual({ key, declared: false });
   }
 });
 
 // The registration is process-global, so a suite that left it set would hand the next file this
-// app's config. \`resetHttpConfig()\` is the seam; this is the one place it is called.
-unitTest('and it is resettable, so no test file inherits the server config of another', () => {
+// app's config. \`resetHttpConfig()\` is the seam, and this is the one place it is called — after
+// the cases, so none of them depends on running before it.
+afterAll(() => {
   resetHttpConfig();
   expect(configuredHttp()).toBeUndefined();
 });