@ultimat3/cli 24.0.0 → 25.0.0

package/src/templates/scaffold-dashboard-shared.ts

@@ -22,7 +22,7 @@ export const routeConfig = (load: string): string => `export const config = defi
   // toggle, provider, the ui runtime they share and the error registry are the rest. It was
   // 60.9kb before the framework stopped shipping solid-js twice and the i18n catalog with it
   // (issue #490), which is what put this at 64kb; 60kb is the figure the scaffold budgets held
-  // before that, kept rather than tightened so a Bun patch cannot red a first \`bin/check\`.
+  // before that, kept rather than tightened so a Bun patch cannot red a first \`bun run check\`.
   budget: { js: '60kb' },${load}
   meta: ({ t }) => ({
     title: t('app.dashboard.title'),
@@ -55,4 +55,65 @@ export const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as token
   margin-inline: auto;
   color: tokens.role('fg');
 }
+
+// The trend beside the ring and the dial: side by side once the main column is wide enough for the
+// area chart to keep its 14 day labels legible, stacked before that.
+.charts {
+  display: grid;
+  gap: tokens.space(6);
+  min-inline-size: 0;
+
+  @include tokens.respond-to('lg') {
+    grid-template-columns: minmax(0, 2fr) minmax(0, 1fr);
+    align-items: start;
+  }
+}
+
+// The ring and the dial share a column: two across on a tablet, where one alone would leave half
+// the row empty, one above the other on a phone and in the narrow side column of a monitor.
+.side {
+  display: grid;
+  gap: tokens.space(4);
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 14rem), 1fr));
+}
+`;
+
+/**
+ * `apps/web/shared/theme.ts`: the app's brand, which the boot reads by this path and inlines in every
+ * document (`theme-brand.ts`). Emitted as the default theme — `defineTheme({})` renders no CSS, so
+ * no tag and no CSP entry — with the preset one edit away: the look is the app's choice (axiom 8).
+ */
+export const themeFile =
+  (): string => `// This app's brand: the boot reads \`brand\` from this file and inlines it in every document,
+// after global.scss, with its hash in the CSP. \`defineTheme({})\` is @ultimat3/ui's default theme
+// and renders nothing, so today no tag is emitted.
+//
+// \`defineTheme()\` is the one seam for restyling — colours, radii, fonts and shadows by role,
+// validated at the call. The dashboard look (near-black panels, a cyan accent, glowing edges, its
+// own eight chart series) is one edit:
+//
+//   export const brand = defineTheme({ preset: 'scifi' });
+//
+// Every other slot layers onto the preset role by role:
+//   defineTheme({ preset: 'scifi', colors: { dark: { 'chart-1': '120 220 255' } } })
+// A preset never forces a theme: to open dark whatever the OS says, set \`theme.defaultMode\` in
+// app.config.ts.
+import { defineTheme } from '@ultimat3/ui';
+
+export const brand = defineTheme({});
+`;
+
+/** Its test: what the brand renders is a fact the app pins, so opting in is a visible diff. */
+export const themeTest =
+  (): string => `// The brand the boot inlines. The default theme renders no CSS — no \`<style>\`, no CSP entry —
+// and the preset is a whole palette; either way \`defineTheme()\` validated it at import.
+import { expect, unitTest } from '@ultimat3/testing';
+import { defineTheme } from '@ultimat3/ui';
+import { brand } from './theme';
+
+unitTest('the app ships the default theme until it opts into a preset', () => {
+  expect(brand.css).toBe('');
+  // The opt-in is one edit, and what it would ship is real CSS the boot inlines.
+  expect(defineTheme({ preset: 'scifi' }).css).toContain('--color-');
+});
 `;

package/src/templates/scaffold-dashboard.ts

@@ -2,25 +2,29 @@
 // stopped being an `<h1>` in a panel. Two shapes, one per `x new` invocation, and both show only
 // what is true of the app that was just written:
 //
-//   --example     the seeded `post` slice: a stat row, a bar chart of posts per day, the latest
-//                 posts in a table. Real rows from the app's own repo, aggregated by a pure view
-//                 module this file also emits.
+//   --example     the seeded `post` slice: a stat row, an area chart of posts per day, a ring of
+//                 free against paid, a dial of this week's share, the latest posts in a table.
+//                 Real rows from the app's own repo, aggregated by a pure view module this file
+//                 also emits.
 //   --no-example  no entity, so no rows to count and nothing honest to chart. Framework facts
 //                 instead — routes, locales, roles, version — and the route table. A chart of
 //                 invented numbers would teach the wrong thing to every app that starts here.
 //
-// One island on the page, the theme toggle (`scaffold-shell.ts`); the tiles, chart and table are
+// One island on the page, the theme toggle (`scaffold-shell.ts`); the tiles, charts and table are
 // server markup, which is what keeps the route inside its 60kb budget.
 
 import type { GeneratedFile, NameSet } from './naming';
 import { bareDashboardFiles } from './scaffold-dashboard-bare';
 import { exampleDashboardFiles } from './scaffold-dashboard-example';
-import { DASHBOARD_DIR, dashboardStyle } from './scaffold-dashboard-shared';
+import { DASHBOARD_DIR, dashboardStyle, themeFile, themeTest } from './scaffold-dashboard-shared';
 
 /** `apps/web/app/dashboard/`, in the shape the invocation earns. */
 export function dashboardFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
   return [
     ...(example ? exampleDashboardFiles(app) : bareDashboardFiles(app)),
     { path: `${DASHBOARD_DIR}/page.module.scss`, contents: dashboardStyle() },
+    // Both shapes: the look is the app's to choose whether or not it has an entity yet.
+    { path: 'apps/web/shared/theme.ts', contents: themeFile() },
+    { path: 'apps/web/shared/theme.test.ts', contents: themeTest() },
   ];
 }

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

@@ -165,7 +165,7 @@ const dbSeedTest = (app: NameSet, example: boolean): string =>
 // 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 { ctxOf, runWithContext } from '@ultimat3/core';",
   "import { testActor } from '@ultimat3/policy';",
   "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
 ])}
@@ -174,7 +174,7 @@ 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);
+  runWithContext(ctxOf({ 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(() => {

package/src/templates/scaffold-docs.ts

@@ -1,5 +1,5 @@
 // The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
-// the bin/ shims and the optional dev compose. Separated from the config half so neither file has
+// the bin/ scripts and the optional dev compose. Separated from the config half so neither file has
 // to be scrolled to find the other — one file, one job applies to templates too. The image, its
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
 // `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`; the one workflow is
@@ -8,6 +8,7 @@
 import { LINE_CEILING } from '../workspace-checks';
 import { githubFiles } from './github/ci.yml';
 import type { GeneratedFile, NameSet } from './naming';
+import { binFiles } from './scaffold-bin';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
 
@@ -21,7 +22,7 @@ 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 |
+| One gate | \`bun run 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; \`.github/workflows/image.yml\` publishes only a commit it passed |
 | 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\` |
@@ -75,14 +76,14 @@ Every test the scaffold and the generators write is the idiom to copy. All of th
 | 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\` |
+| a repo, a seed | as an actor, \`runWithContext(ctxOf({ 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
 it would be worse than the type that really does.
 
-\`bin/check\` is the gate and \`x verify\` is only its second half: the first is
+\`bun run check\` is the gate and \`x verify\` is only its second half: the first is
 \`x build --target static\`, and the build is what writes the \`.x/build-stats.json\` the
 \`budgets\` step measures. Run \`x verify\` on a tree nobody has built and \`budgets\` is red with
 X_BUDGET_UNMEASURED — the gate reporting on a file that does not exist, not on your code.
@@ -93,8 +94,9 @@ here is generated from it. So the scaffold never clobbers a maintainer policy, t
 clobbers \`AGENTS.md\`, \`bin/\`, \`.claude/\` or \`.github/\`, and deleting either side leaves the
 other exactly as it was.
 
-Commands: \`bin/setup\`, \`bin/dev\`, \`bin/check\`, \`x g <primitive>\`, \`x g guard <name>\`,
-\`x db branch create <name>\`, \`x doctor\`.
+Commands: \`bun run setup\`, \`bun run dev\`, \`bun run check\`, \`x g <primitive>\`,
+\`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`. \`setup\` and \`check\` are
+\`bin/*.ts\` files Bun runs, so all three are the same command in PowerShell, cmd and bash.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -103,10 +105,10 @@ const claude = (app: NameSet): string => `# CLAUDE.md
 
 ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
 
-- Gate: \`bin/check\` (add \`--json\` for machine output — it reaches both halves). It is
+- Gate: \`bun run check\` (add \`--json\` for machine output — it reaches both halves). It is
   \`x build --target static\` and then \`x verify\`; \`x verify\` alone leaves \`budgets\` with
-  nothing to measure. \`.github/workflows/ci.yml\` runs \`bin/setup && bin/check\` on every push
-  and pull request, so CI and your terminal run the same two commands.
+  nothing to measure. \`.github/workflows/ci.yml\` runs \`bun run setup && bun run check\` on
+  every push and pull request, so CI and your terminal run the same two commands.
 - \`.dz/\` belongs to the developerz.ai platform and is additive both ways: the scaffold writes
   nothing there, and nothing there is generated from this repo. Neither side clobbers the other.
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
@@ -129,12 +131,12 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 ## 🚀 Start
 
 \`\`\`sh
-bin/setup     # prerequisites, deps, env, the first migration, migrate, seed, the manifest
-bin/dev       # all roles in one process, embedded Postgres, /_x mounted
-bin/check     # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
+bun run setup   # prerequisites, deps, env, the first migration, migrate, seed, the manifest
+bun run dev     # all roles in one process, embedded Postgres, /_x mounted
+bun run check   # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
-\`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
+\`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bun run setup\` runs
 \`x db gen "initial"\` for you on a fresh clone. Until it has, \`x verify\`'s \`drift\` step is red
 with \`X_DB_DRIFT\`, and that is the fix it names.
 
@@ -150,63 +152,8 @@ with \`X_DB_DRIFT\`, and that is the fix it names.
 | \`packages/*\` | domain, db, i18n, ui, mcp |
 | \`app.config.ts\` | the one config file |
 | \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
-| \`.github/workflows/ci.yml\` | \`bin/setup\` then \`bin/check\`, on push and pull request |
-`;
-
-const binSetup = (): string => `#!/usr/bin/env bash
-# Fresh clone to running. Idempotent: safe to re-run.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-command -v bun >/dev/null || { echo "X_BUN_MISSING: install bun — https://bun.sh"; exit 1; }
-bun install
-[ -f .env.development.local ] || printf '# per-box secrets, gitignored, wins over .env.development\\n' > .env.development.local
-# \`x db gen\` is the ONE writer of packages/db/migrations — the scaffold no longer hand-writes a
-# 0000_initial.sql, because a second writer is how the source and the ledger ended up disagreeing
-# about what "initial" meant. Guarded on the directory rather than on the generator being a no-op:
-# this script is documented idempotent, and the guard is what makes that true here.
-ls packages/db/migrations/*.sql >/dev/null 2>&1 || bunx x db gen "initial"
-bunx x db migrate "$@"
-# \`x db seed\`, never \`bun run\`: the CLI owns the connection, so this reaches the same embedded
-# PGlite the migration above just wrote to. A plain script goes through \`db()\`, which needs a
-# \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres — one line after reporting a
-# successful migration.
-bunx x db seed
-# The file \`AGENTS.md\` line 3 tells an agent facts live in, and \`x dev\` prints the path of. It
-# is a projection of the loaded app, so \`x new\` cannot write it — node_modules does not exist
-# yet — and nothing else ever ran the command: after \`x new\`, \`bin/setup\` and all 13
-# generators, \`find . -name '*.manifest.json'\` returned nothing while \`x verify\` reported
-# \`\u2713 manifest\`. \`x verify\`'s manifest step now refuses its absence (X_MANIFEST_MISSING).
-bunx x manifest
-echo "setup complete — next: bin/dev"
-`;
-
-const binDev = (): string => `#!/usr/bin/env bash
-# Every role in one process: embedded Postgres, in-process NATS, S3 to a local dir.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-exec bunx x dev "$@"
-`;
-
-const binCheck = (): string => `#!/usr/bin/env bash
-# The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-# The build FIRST, and not as a convenience: \`x verify\`'s budgets step compares declared limits
-# against measured bytes in .x/build-stats.json, so with no build it reports X_BUDGET_UNMEASURED and
-# the very first gate anyone runs on a brand-new app is red for a reason that has nothing to do with
-# their code. Cheap on a warm tree, and it makes "green" reachable from a fresh clone.
-#
-# \`--json\` is forwarded to BOTH, or the contract breaks: \`bin/check --json\` would otherwise print
-# the build's human renderer to stdout and then the gate's JSON, and a machine consumer reading one
-# document off stdout gets neither. Both commands emit one object; a reader takes the last line.
-build_flags=""
-for arg in "$@"; do
-  case "$arg" in --json|-j) build_flags="--json" ;; esac
-done
-# \`--no-preflight\`: the build's own preflight is x verify's first six steps (typecheck, lint,
-# boundaries, filesize, package-shape, errors), and the gate below runs them anyway — once is enough.
-bunx x build --target static --no-preflight $build_flags
-exec bunx x verify "$@"
+| \`.github/workflows/ci.yml\` | \`bun run setup\` then \`bun run check\`, on push and pull request |
+| \`.github/workflows/image.yml\` | after a green \`ci\` on the default branch: \`docker/Dockerfile\` to \`ghcr.io\`, tagged \`sha-<7>\`, always on \`ubuntu-latest\` (bash and Docker). \`ci.yml\` runs on \`vars.CI_RUNNER\`, default \`ubuntu-latest\` |
 `;
 
 const composeDev = (
@@ -243,7 +190,7 @@ services:
   # 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: versity/versitygw:v1.8.0
+    image: versity/versitygw:v1.8.0@sha256:30292fc2eeacc67a36993b01f7a7a5e3361a19cced0e80c1d71cfa2a4b0a2499
     environment:
       VGW_BACKEND: posix
       VGW_BACKEND_ARG: /data
@@ -264,9 +211,8 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'README.md', contents: readme(app) },
     { path: 'AGENTS.md', contents: agents(app) },
     { path: 'CLAUDE.md', contents: claude(app) },
-    { path: 'bin/setup', contents: binSetup() },
-    { path: 'bin/dev', contents: binDev() },
-    { path: 'bin/check', contents: binCheck() },
+    // The scripts `bun run setup` and `bun run check` run — TypeScript, so one file per OS.
+    ...binFiles(),
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
     // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
     // in a global config, so it is visible in the scaffold's diff and deletable in one line.
@@ -278,6 +224,3 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     ...containerFiles(app),
   ];
 }
-
-/** Files that must be executable after `x new` writes them. */
-export const EXECUTABLE_FILES: readonly string[] = ['bin/setup', 'bin/dev', 'bin/check'];

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

@@ -23,10 +23,6 @@ import type { MoneyValue as Money } from '@ultimat3/schema';
 
 export type { MoneyValue as Money } from '@ultimat3/schema';
 
-export const ROLES = ['owner', 'member', 'viewer'] as const;
-
-export type Role = (typeof ROLES)[number];
-
 /**
  * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
  * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,

package/src/templates/scaffold-entries.ts

@@ -16,6 +16,7 @@ const server =
 
 import { join } from 'node:path';
 import { runRole } from '@ultimat3/cli/serve';
+import { isCompiledBundle } from '@ultimat3/core';
 
 // MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
 //
@@ -36,10 +37,10 @@ import { runRole } from '@ultimat3/cli/serve';
  * 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.
+ * \`isCompiledBundle\` knows both spellings of that filesystem: \`/$bunfs/\` on Linux and macOS,
+ * \`B:\\~BUN\\\` on Windows.
  */
-const root = import.meta.dir.startsWith('/$bunfs')
-  ? process.cwd()
-  : join(import.meta.dir, '..', '..');
+const root = isCompiledBundle(import.meta.dir) ? 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\`.

package/src/templates/scaffold-env.ts

@@ -4,7 +4,7 @@
 // app whose own `x verify` fails on the drift the framework exists to prevent.
 
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { renderEnvExample } from '@ultimat3/core';
+import { appEnvExample } from '../framework-env';
 
 /**
  * Committed defaults only, so a fresh clone boots with `x dev` and no scavenger hunt. Every
@@ -90,9 +90,12 @@ export function envSchemaSource(schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string
   return lines.join('\n');
 }
 
-/** Byte-identical to what `x env example` writes, because both call core's one renderer. */
+/**
+ * Byte-identical to what `x env example` writes, because both call the one renderer — the app's
+ * declaration, then the framework's deploy-required keys (`framework-env.ts`).
+ */
 export const envExampleSource = (schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string =>
-  renderEnvExample(schema);
+  appEnvExample(schema);
 
 /** Named so a reader of `repoFiles` can see the two projections come from one declaration. */
 export const scaffoldEnvVarNames = (): readonly string[] =>

package/src/templates/scaffold-gitattributes.ts

@@ -0,0 +1,59 @@
+// The root `.gitattributes` `x new` writes: every text file LF in the index and the checkout, every
+// binary type left byte-for-byte. The framework repo's own root file opens with the same block —
+// `scaffold-gitattributes.test.ts` refuses the two drifting apart.
+
+/** The path, relative to the app root — git reads attributes from here for the whole tree. */
+export const ROOT_GITATTRIBUTES_PATH = '.gitattributes';
+
+/**
+ * Binary types an app or the framework plausibly tracks: images, icons, fonts, WebAssembly and the
+ * archives fixtures arrive in. `text=auto` would usually detect them, but "usually" is a heuristic
+ * over the first 8000 bytes — `binary` is the statement, and it also stops a textual diff.
+ */
+export const BINARY_EXTENSIONS: readonly string[] = [
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+  'ico',
+  'woff',
+  'woff2',
+  'ttf',
+  'otf',
+  'wasm',
+  'pdf',
+  'zip',
+  'gz',
+  'tgz',
+  'tar',
+];
+
+/**
+ * `* text=auto eol=lf` is not cosmetic. Git for Windows installs with `core.autocrlf=true`, so a
+ * checkout without it rewrites every file to CRLF: Biome (`lineEnding: "lf"`) then flags every
+ * file, every `split('\n')` scanner sees a trailing `\r`, and every byte-compared artifact — the
+ * manifest, the schema dump, a migration's checksum — reads as drift on a correct tree. Pinned
+ * here, it holds for every clone whatever the contributor's git config says.
+ */
+export const LINE_ENDING_ATTRIBUTES = `# Every text file is LF, in the index and in the checkout, whatever \`core.autocrlf\` says. Git for
+# Windows defaults it to true: without this line a Windows clone is CRLF, Biome flags every file and
+# every byte-compared artifact (manifest, schema dump, migration checksum) reads as drift.
+* text=auto eol=lf
+
+# Binary, stated rather than detected: never line-ending converted, never textually diffed.
+${BINARY_EXTENSIONS.map((extension) => `*.${extension} binary`).join('\n')}
+`;
+
+/** The app's root file: the shared block, then the app's one generated file git should collapse. */
+export const rootGitattributes = (): string => `${LINE_ENDING_ATTRIBUTES}
+# Bun's lockfile. Regenerated by \`bun install\`, never edited by hand.
+bun.lock -diff linguist-generated=true
+`;
+
+/** The file `x new` writes at the app root — one entry in `repoFiles`' list. */
+export const rootGitattributesFile = (): { readonly path: string; readonly contents: string } => ({
+  path: ROOT_GITATTRIBUTES_PATH,
+  contents: rootGitattributes(),
+});

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

@@ -29,11 +29,13 @@ every object would be ${app.kebab}-${app.kebab}-web.
 
 {{/*
 repository:tag, and NOT a single "image" string: x deploy --method helm passes
---set image.repository=... --set image.tag=..., because replacing the map with a string makes
-every workload below fail on .repository and deploy nothing.
+--set-string image.repository=... --set-string image.tag=..., because replacing the map with a
+string makes every workload below fail on .repository and deploy nothing. toString on both halves:
+a plain --set image.tag=1234567 is an int64, which printf renders as %!s(int64=1234567).
 */}}
 {{- define "${app.kebab}.image" -}}
-{{- printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) -}}
+{{- $repository := required "image.repository is empty — set it to the registry path your CI pushes the app image to: --set-string image.repository=ghcr.io/<org>/<app>, or x deploy --method helm --image ghcr.io/<org>/<app>:<tag>" .Values.image.repository -}}
+{{- printf "%s:%s" (toString $repository) (toString (default .Chart.AppVersion .Values.image.tag)) -}}
 {{- end -}}
 
 {{- define "${app.kebab}.labels" -}}
@@ -66,7 +68,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 {{- $envPort = sub (int $cfg.port) 1 -}}
 {{- end -}}
 - name: {{ $role }}
-  image: {{ include "${app.kebab}.image" $root }}
+  image: {{ include "${app.kebab}.image" $root | quote }}
   imagePullPolicy: {{ $root.Values.image.pullPolicy }}
   securityContext: {{- toYaml $root.Values.securityContext | nindent 4 }}
   env:
@@ -116,10 +118,12 @@ 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. 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.
+  listener is their only port — so they take liveness on it, and readiness on /readyz of that same
+  listener: 503 until the role has started and from the first instant of a drain, so a rollout
+  never counts a worker that has not started its role yet. The replicator reads /readyz?deep=1:
+  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
@@ -152,27 +156,69 @@ 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:
+    {{- if eq $role "replicator" }}
     httpGet: { path: '/readyz?deep=1', port: metrics }
     periodSeconds: 10
-  {{- end }}
+    {{- else }}
+    httpGet: { path: /readyz, port: metrics }
+    periodSeconds: 5
+    {{- end }}
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
     failureThreshold: 4
+  {{- /*
+  The worker's retire, opt-in: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
+  the framework's retire: stop claiming, finish every held job however long it takes, abort
+  nothing, then drain and exit 0 — and waits until PID 1 is gone, so the SIGTERM that follows finds
+  nothing left to cut off. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
+  IS PID 1). The kubelet counts the preStop against the grace period, so retireSeconds is added to
+  it and is the longest a retire may take.
+  */}}
+  {{- if and (eq $role "worker") (gt (int $cfg.retireSeconds) 0) }}
+  lifecycle:
+    preStop:
+      exec:
+        command:
+          - bun
+          - -e
+          - "process.kill(1, 'SIGUSR2'); for (;;) { try { process.kill(1, 0); } catch { break; } await Bun.sleep(1000); }"
+  {{- end }}
   {{- end }}
   resources: {{- toYaml $cfg.resources | nindent 4 }}
   volumeMounts:
     - name: tmp
       mountPath: /tmp
 {{- end -}}
+
+{{/*
+A role's terminationGracePeriodSeconds, in the order the kubelet's budget is spent: the preStop
+sleep (web and sync, 1.30+), the worker's opt-in retire (roles.worker.retireSeconds), the
+readiness grace (web and sync — every other role drains with none), the drain budget (app.config.ts drain.deadlineMs, every role) and the teardown margin.
+Defaults: 45s web/sync (40s below 1.30), 35s the rest. x deploy --method helm sets
+drain.deadlineSeconds and drain.readinessGraceSeconds from app.config.ts.
+*/}}
+{{- define "${app.kebab}.terminationGracePeriodSeconds" -}}
+{{- $drain := .root.Values.drain -}}
+{{- $total := add (int $drain.deadlineSeconds) (int $drain.teardownMarginSeconds) -}}
+{{- if eq .role "worker" -}}
+{{- $total = add $total (int .cfg.retireSeconds) -}}
+{{- end -}}
+{{- if .cfg.port -}}
+{{- $total = add $total (int $drain.readinessGraceSeconds) -}}
+{{- if semverCompare ">=1.30-0" .root.Capabilities.KubeVersion.Version -}}
+{{- $total = add $total (int $drain.preStopSleepSeconds) -}}
+{{- end -}}
+{{- end -}}
+{{- $total -}}
+{{- end -}}
 `;
 
 const deployments = (app: NameSet): string => `{{/*
 One Deployment per enabled role, from one image. terminationGracePeriodSeconds covers the preStop
-sleep, the framework's readiness grace and its SIGTERM drain: in-flight requests, open websockets
-and running job steps finish.
+sleep, the framework's readiness grace and its SIGTERM drain — in-flight requests, open websockets
+and running job steps finish — derived per role from drain in values.yaml.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if $cfg.enabled }}
@@ -194,9 +240,21 @@ spec:
     matchLabels:
       app.kubernetes.io/instance: {{ $.Release.Name }}
       app.kubernetes.io/component: {{ $role }}
+  {{/*
+  The replicator is Recreate, never a rolling update: one pod per database holds the replication
+  slot's advisory lock, so a surged pod can only stand by, unready, and maxUnavailable: 0 never
+  terminates the holder it is waiting on — every rollout stalled. Recreate lets the holder go first.
+  */}}
+  {{/* A new pod must stay Ready this long before the rollout counts it and stops an old one, so a
+  role that crashes seconds after its first probe never replaces a working pod. */}}
+  minReadySeconds: {{ $.Values.minReadySeconds | int }}
   strategy:
+    {{- if eq $role "replicator" }}
+    type: Recreate
+    {{- else }}
     type: RollingUpdate
     rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
+    {{- end }}
   template:
     metadata:
       labels:
@@ -208,12 +266,10 @@ spec:
       code that reaches the filesystem, which for a web role is one path traversal. */}}
       automountServiceAccountToken: false
       securityContext: {{- toYaml $.Values.podSecurityContext | nindent 8 }}
-      {{/* Spent in order: the preStop sleep (drain.preStopSleepSeconds, 1.30+), the framework's
-      readiness grace (5s outside local environments) and its drain deadline (25s, which is what
-      X_SHUTDOWN_TIMEOUT's fix line names) — 35s, so 45 leaves 10s before SIGKILL. Raise this WITH
-      configureLifecycle({ deadlineMs, readinessGraceMs }), never instead of it: the drain
-      abandons its hooks at its own deadline. */}}
-      terminationGracePeriodSeconds: 45
+      {{/* Derived per role from the drain values — see the helper in _helpers.tpl. Raise
+      drain.deadlineMs in app.config.ts, never this: the drain abandons its hooks at its own
+      deadline, so a longer grace period alone buys nothing. */}}
+      terminationGracePeriodSeconds: {{ include "${app.kebab}.terminationGracePeriodSeconds" (dict "role" $role "cfg" $cfg "root" $) }}
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
       volumes: