@ultimat3/cli 23.0.0 → 25.0.0

package/src/cmd-build.ts

@@ -4,19 +4,21 @@
 
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
+import { ERROR_DOCS_URL, frameworkVersion, UltimateError, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { buildSpec } from './cmd-build-spec';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
-import { BadFlagError, BuildEntryMissingError, UnknownCommandError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
+import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
 import { PREBUILT_DIR } from './serve-prebuilt-paths';
+import { quoteArg } from './shell-quote';
 import type { StaticReport } from './static-report';
 import {
   readStaticReport,
@@ -24,6 +26,22 @@ import {
   renderStaticReport,
   staticReportData,
 } from './static-report';
+import type { VerifyStepName } from './verify-step';
+
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
+    });
+  }
+}
 
 export const BUILD_TARGETS = ['docker', 'binary', 'static', 'prebuilt'] as const;
 
@@ -85,24 +103,94 @@ export function dockerArgs(root: string, tag: string, buildId: string): readonly
 }
 
 /**
- * The define is not optional. A single-file executable carries no `package.json`, so
- * `frameworkVersion()` has nothing to read and throws — which is exactly how this target came to
- * compile an artifact that could never boot. The value is this CLI's own `@ultimat3/core`, which is
- * the app's too: the packages release in lockstep and `x new` pins them together.
+ * What `--platform` may name: Bun's own `--target` spellings, so the flag maps onto Bun's one to
+ * one and an agent who knows Bun's list knows this one. Four, not Bun's every target — these are
+ * the hosts the framework is tested on; a musl or baseline build is `bun build` by hand.
+ */
+export const BINARY_PLATFORMS = [
+  'bun-linux-x64',
+  'bun-linux-arm64',
+  'bun-windows-x64',
+  'bun-darwin-arm64',
+] as const;
+
+export type BinaryPlatform = (typeof BINARY_PLATFORMS)[number];
+
+/** `--platform`, checked before the gate runs: an unknown value is a typo, never a guess. */
+export function readPlatform(raw: string | undefined): BinaryPlatform | undefined {
+  if (raw === undefined) return undefined;
+  const known: readonly string[] = BINARY_PLATFORMS;
+  if (known.includes(raw)) return raw as BinaryPlatform;
+  throw new BadFlagError({
+    flag: 'platform',
+    command: 'build',
+    reason: `${quoteArg(raw)} is not a platform x build compiles for — one of ${BINARY_PLATFORMS.join(', ')}`,
+    fix: 'x build --target binary --platform bun-linux-x64',
+  });
+}
+
+/**
+ * The path the executable really lands at. Bun names a Windows executable `<out>.exe` — whether
+ * `--platform bun-windows-x64` asked for it or the host is Windows and no platform was named — so
+ * the `.exe` is appended HERE and passed to `--outfile`, and the path reported is the path written.
+ */
+export function binaryOutfile(
+  out: string,
+  platform: BinaryPlatform | undefined,
+  host: string = process.platform,
+): string {
+  const windows = platform === undefined ? host === 'win32' : platform.startsWith('bun-windows-');
+  return windows && !out.toLowerCase().endsWith('.exe') ? `${out}.exe` : out;
+}
+
+/**
+ * The define answers `frameworkVersion()` for framework code BUNDLED into an executable, where no
+ * `package.json` exists — the reason this target once compiled an artifact that could never boot,
+ * and why `docker/Dockerfile`'s self-contained `x` still needs it. Here nothing framework is
+ * bundled any more (`LAUNCHER_EXTERNALS`): `@ultimat3/core` loads from the app's `node_modules` and
+ * reads its own manifest, so the define reaches no module of this graph. It stays as a pin on that
+ * one version, this CLI's own — the packages release in lockstep and `x new` pins them together.
  *
  * `externalArgs()` is not optional either, and for the opposite reason: it names the one specifier
  * this graph must NOT resolve. `apps/web/server.ts` reaches `serve.ts`, which reaches the island
  * builder, which reaches `@babel/core` — whose `.cts`-config loader requires a package we
  * deliberately do not install. Bun 1.3 fails the compile on it. See `compile-externals.ts`.
+ *
+ * The two autoload flags are what make the binary a LAUNCHER at all. It imports the app tree it is
+ * started in at run time — `app.config.ts`, then every module under `apps/*` — and a standalone
+ * executable reads neither `package.json` nor `tsconfig.json` at run time by default (Bun:
+ * `--compile-autoload-{package-json,tsconfig}`, both off). With no `package.json` the resolver
+ * ignores `exports`, so every `@ultimat3/*` (`exports` → `./src/index.ts`) was
+ * `Cannot find module '@ultimat3/core' from '<app>/app.config.ts'` and the binary never answered
+ * `/healthz` — on Windows, where CI first ran it, and on Linux alike. With no `tsconfig.json` the
+ * app's own `paths` aliases fail the same way. `e2e/binary-launch.e2e.test.ts` compiles and runs it.
+ */
+/**
+ * The framework is resolved from the app tree at run time, never bundled into the binary. The app's
+ * own modules import `@ultimat3/*` from its `node_modules` — they are loaded off disk, after the
+ * build — so a bundled copy was a SECOND instance of every package: the app's `configureAuthenticator`
+ * filled the disk copy's slot while the bundled server read its own, empty one (measured:
+ * `X_CONFIG_INVALID … no authenticator is configured` on a scaffold that installs one), and every
+ * registry split the same way. One instance is the one the app's imports reach.
  */
-export function binaryArgs(root: string, out: string): readonly string[] {
+const LAUNCHER_EXTERNALS: readonly string[] = ['@ultimat3/*'];
+
+export function binaryArgs(
+  root: string,
+  out: string,
+  platform?: BinaryPlatform,
+): readonly string[] {
   return [
     'bun',
     'build',
     '--compile',
     '--minify',
+    ...(platform === undefined ? [] : ['--target', platform]),
     '--define',
     `${VERSION_DEFINE}=${JSON.stringify(frameworkVersion())}`,
+    '--compile-autoload-package-json',
+    '--compile-autoload-tsconfig',
+    ...LAUNCHER_EXTERNALS.flatMap((specifier) => ['--external', specifier]),
     ...externalArgs(),
     join(root, BUILD_ENTRY.binary),
     '--outfile',
@@ -122,10 +210,12 @@ export function argsFor(
     readonly out: string;
     /** The docker target's `BUILD_ID` build arg — `appManifest(root)`'s own. */
     readonly buildId?: string;
+    /** The binary target's `--platform`, as Bun's `--target`. */
+    readonly platform?: BinaryPlatform;
   },
 ): readonly string[] {
   if (target === 'docker') return dockerArgs(paths.root, paths.tag, paths.buildId ?? 'dev');
-  if (target === 'binary') return binaryArgs(paths.root, paths.out);
+  if (target === 'binary') return binaryArgs(paths.root, paths.out, paths.platform);
   return staticArgs(paths.root, paths.out);
 }
 
@@ -158,6 +248,8 @@ export function buildResult(input: {
   readonly command: readonly string[];
   readonly result: ExecResult;
   readonly report?: StaticReport;
+  /** The binary target's `--platform`, when one was named. */
+  readonly platform?: BinaryPlatform;
 }): CommandResult {
   const { report, result, target } = input;
   const output = result.ok ? '' : execOutput(result);
@@ -177,6 +269,7 @@ export function buildResult(input: {
         ],
     data: {
       target,
+      ...(input.platform === undefined ? {} : { platform: input.platform }),
       artifact: input.artifact,
       durationMs: result.durationMs,
       ...(result.ok ? {} : { output }),
@@ -190,6 +283,47 @@ export function buildResult(input: {
   };
 }
 
+/** The flags only some targets read. */
+const TARGET_SCOPED_FLAGS = ['tag', 'out', 'platform', 'preflight'] as const;
+
+type TargetScopedFlag = (typeof TARGET_SCOPED_FLAGS)[number];
+
+/** The optional flags each target READS. One table, so a flag cannot be read by one and ignored. */
+const TARGET_FLAGS: ReadonlyMap<BuildTarget, readonly TargetScopedFlag[]> = new Map([
+  ['docker', ['tag', 'preflight']],
+  ['binary', ['out', 'platform', 'preflight']],
+  ['static', ['out', 'preflight']],
+  // The boot reads ONE place, and the image holds no devDependencies to run a gate with.
+  ['prebuilt', []],
+]);
+
+/** Why a target takes no `--<flag>`, in the words its refusal prints. */
+const UNREAD_BECAUSE: Readonly<Record<TargetScopedFlag, string>> = {
+  tag: 'only the docker target tags an image',
+  out: 'the docker target writes an image, not a path',
+  platform: 'only the binary target compiles an executable for a platform',
+  preflight: 'the prebuilt target runs no gate: `x verify` ran before `docker build` was called',
+};
+
+/**
+ * A flag the chosen target never reads is refused before the gate runs. Accepted and dropped, it
+ * printed a green build: `--out dist` on `docker` and `--tag` on `binary` read as if they landed.
+ */
+function refuseUnreadFlags(args: ParsedArgs, target: BuildTarget): void {
+  for (const flag of TARGET_SCOPED_FLAGS) {
+    if (!args.flags.has(flag) || TARGET_FLAGS.get(target)?.includes(flag) === true) continue;
+    throw new BadFlagError({
+      flag,
+      command: 'build',
+      reason:
+        target === 'prebuilt' && flag !== 'preflight'
+          ? `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`
+          : `--target ${target} never reads it: ${UNREAD_BECAUSE[flag]}`,
+      fix: `x build --target ${quoteArg(target)}`,
+    });
+  }
+}
+
 /**
  * `x build --target prebuilt`: the island chunks and compiled stylesheets, written by the process
  * `docker build` runs after the source is copied in. No gate and no subprocess — the image holds
@@ -198,17 +332,7 @@ export function buildResult(input: {
  * A module that would not import fails the image build rather than warning into a build log
  * nobody reads: its stylesheets are missing from the store, and every pod would compile them.
  */
-async function buildPrebuilt(ctx: CommandContext, root: string): Promise<CommandResult> {
-  // The boot reads ONE place; a flag that seemed to move it would write a store no pod opens.
-  for (const flag of ['tag', 'out']) {
-    if (flagString(ctx.args, flag) === undefined) continue;
-    throw new BadFlagError({
-      flag,
-      command: 'build',
-      reason: `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`,
-      fix: 'x build --target prebuilt',
-    });
-  }
+async function buildPrebuilt(root: string): Promise<CommandResult> {
   const started = Bun.nanoseconds();
   const { prebuildImage } = await import('./image-prepare');
   const built = await prebuildImage(root);
@@ -230,7 +354,7 @@ async function buildPrebuilt(ctx: CommandContext, root: string): Promise<Command
 }
 
 /** The static steps `x build` runs before it builds, and `--no-preflight` leaves to the gate. */
-export const PREFLIGHT_STEPS: readonly string[] = [
+export const PREFLIGHT_STEPS: readonly VerifyStepName[] = [
   'typecheck',
   'lint',
   'boundaries',
@@ -248,7 +372,9 @@ export const buildCommand: CliCommand = {
     // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
     // an agent spends on the wrong question.
     requireEntry(root, target);
-    if (target === 'prebuilt') return buildPrebuilt(ctx, root);
+    refuseUnreadFlags(ctx.args, target);
+    const platform = readPlatform(flagString(ctx.args, 'platform'));
+    if (target === 'prebuilt') return buildPrebuilt(root);
 
     // Run static verify steps before building — unless the caller is a gate that runs the same
     // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the
@@ -268,10 +394,11 @@ export const buildCommand: CliCommand = {
     // A relative `--out` is a path the caller typed from where they stand, so it resolves against
     // the cwd — against the root it landed somewhere else whenever `x build` ran from `apps/web`.
     const outFlag = flagString(ctx.args, 'out');
-    const out =
+    const requested =
       outFlag === undefined
         ? join(root, '.x', target === 'static' ? 'static' : 'app')
         : resolve(ctx.cwd, outFlag);
+    const out = target === 'binary' ? binaryOutfile(requested, platform) : requested;
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
     // The docker target stamps the manifest's build id into the image, so no role derives one at
     // boot. The island chunks and stylesheets are the image build's own (`--target prebuilt`).
@@ -282,6 +409,7 @@ export const buildCommand: CliCommand = {
       tag,
       out,
       ...(buildId === undefined ? {} : { buildId }),
+      ...(platform === undefined ? {} : { platform }),
     });
     // Removed BEFORE the builder runs, so a build that writes no inventory can never be reported
     // with the last one's: a stale emitted list is worse than none, because it reads as this run's.
@@ -297,6 +425,7 @@ export const buildCommand: CliCommand = {
       command,
       result,
       ...(report === undefined ? {} : { report }),
+      ...(platform === undefined ? {} : { platform }),
     });
   },
 };

package/src/cmd-db-backfill.ts

@@ -23,7 +23,7 @@ import { BadFlagError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { backfillToJson } from './jobs-json';
 import { msg } from './messages';
-import type { CommandResult } from './output';
+import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
@@ -106,7 +106,7 @@ function readShape(args: ParsedArgs): { readonly shape: BackfillShape; readonly
     return refuseShape(
       second.startsWith('--') ? second.slice(2) : 'name',
       `x db backfill was asked for ${asked.join(' and ')} — one shape per invocation: --list, --pending, <name> or --all`,
-      `x db backfill ${asked[0]} --json`,
+      `x db backfill ${quoteArg(asked[0] ?? '--pending')} --json`,
     );
   }
   if (asked.length === 0) {
@@ -171,15 +171,22 @@ async function runBackfillList(ctx: CommandContext, root: string): Promise<Comma
  * The alarm the framework did not have. Non-zero when anything is unswept, so a cron or a deploy
  * check can read the exit code — a `--json` nobody has to parse to know something is wrong.
  * `loadApp` first: importing the app's modules IS the declaration, and a diff run without it
- * would report a clean database against an empty declaration list.
+ * would report a clean database against an empty declaration list. Its findings fail the run for
+ * the same reason: a module that would not import may be the one declaring the unswept backfill.
  */
 async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   return withJobDriver(root, ctx, async (driver) => {
     const report = await pendingReport(driver, environment);
+    const findings = [
+      ...report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      ...loadFindings,
+    ];
     return {
-      ok: report.pending.length === 0,
+      ok: findings.length === 0,
       command: 'db',
       summary:
         report.pending.length === 0
@@ -188,9 +195,7 @@ async function runBackfillPending(ctx: CommandContext, root: string): Promise<Co
               count: report.pending.length,
               declared: report.rows.length,
             }),
-      findings: report.pending.map((row) =>
-        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
-      ),
+      findings,
       lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
       data: pendingToJson(report),
     };
@@ -208,7 +213,7 @@ async function runBackfillPass(
   root: string,
   names: readonly string[] | 'all',
 ): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   const write = flagBool(ctx.args, 'write');
   return withJobDriver(root, ctx, async (driver) => {
@@ -220,16 +225,24 @@ async function runBackfillPass(
       environment,
       appliedMigrations: await readAppliedMigrations(),
     });
-    return backfillPassResult(rows, write);
+    return backfillPassResult(rows, write, loadFindings);
   });
 }
 
 /**
  * A blocked or deduped name is a finding and a non-zero exit, and every OTHER name still ran —
- * that isolation is what stops one wedged cleanup blocking every later one forever.
+ * that isolation is what stops one wedged cleanup blocking every later one forever. A module that
+ * would not import fails the pass too: `--all` over it plans every backfill but the unloaded ones.
  */
-function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
-  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+function backfillPassResult(
+  rows: readonly BackfillPlanRow[],
+  write: boolean,
+  loadFindings: readonly Finding[],
+): CommandResult {
+  const findings = [
+    ...rows.flatMap((row) => (row.finding === null ? [] : [row.finding])),
+    ...loadFindings,
+  ];
   // Counted per action, never derived from the total: a deduped pass is neither enqueued nor
   // blocked, and `rows.length - enqueued` reported it as blocked while `--json` reported it as
   // deduped. `planToJson` is the same list, so the two renders now add up to the same run.

package/src/cmd-db-branch.ts

@@ -4,7 +4,7 @@
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
 import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
-import { createPostgresClient, type DbClient } from '@ultimat3/db';
+import { type DbClient, postgresClient } from '@ultimat3/db';
 import type { CommandContext } from './command';
 import type { BranchRow } from './db-branch';
 import {
@@ -62,7 +62,7 @@ function branchRetry(word: string, name: string | undefined): string {
  * database routinely outlives the 10s a `web` profile allows.
  */
 async function withBranchClient<T>(url: string, fn: (client: DbClient) => Promise<T>): Promise<T> {
-  const client = createPostgresClient({ url, role: 'migrate', applicationName: 'x-db-branch' });
+  const client = postgresClient({ url, role: 'migrate', applicationName: 'x-db-branch' });
   try {
     return await fn(client);
   } finally {

package/src/cmd-db.ts

@@ -11,7 +11,7 @@
 // directory tree. `node:path` for `join` — Bun exposes no path joiner.
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { resolveEnvironment } from '@ultimat3/core';
+import { NotImplementedError, resolveEnvironment } from '@ultimat3/core';
 import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
 import { postgresDriver } from '@ultimat3/entity';
 import { requireAppRoot } from './app-root';
@@ -40,7 +40,7 @@ import {
   selectSeeds,
 } from './db-seed';
 import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
-import { CliNotImplementedError, MissingSubcommandError, UnknownCommandError } from './errors';
+import { MissingSubcommandError, UnknownCommandError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -254,9 +254,12 @@ async function runMigrate(
 async function runReset(ctx: CommandContext, root: string): Promise<CommandResult> {
   const services = resolveServices(root, ctx.env);
   if (services.db.mode === 'external') {
-    throw new CliNotImplementedError({
-      feature: 'x db reset against an external Postgres',
-      fix: 'drop and recreate the database yourself, then run: x db migrate',
+    throw new NotImplementedError({
+      // The usual way here is an EXPORTED `DATABASE_URL` (an integration suite's Postgres) that
+      // the shell handed down, so the variable is named and the embedded reset is one command (#674).
+      cause:
+        'DATABASE_URL is set, so x db reset would target an external Postgres — dropping a database this process does not own is not implemented in this build',
+      fix: 'env -u DATABASE_URL x db reset   # resets the embedded database instead — or drop and recreate the external one yourself, then run: x db migrate',
     });
   }
   // A running `x dev` has this directory open: deleting it under a live embedded Postgres is data
@@ -301,7 +304,8 @@ async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult
   });
   if (chosen.length === 0) {
     return {
-      ok: true,
+      // A seed module that would not import may hold the seed that was asked for.
+      ok: discovery.findings.length === 0,
       command: 'db',
       summary: msg('cli.db.seed.none'),
       findings: discovery.findings,

package/src/cmd-deploy-compose.ts

@@ -0,0 +1,94 @@
+// The compose half of `x deploy`'s rollout: which serving roles can start their new container
+// BEFORE the old one stops, read off the app's compose file. The sequence that does it is
+// `cmd-deploy-start-first.ts`.
+// `docker compose up -d <role>` alone is stop-first — it recreates, so the role serves nothing
+// between the old container's exit and the new one's healthcheck.
+
+/**
+ * How one serving role is rolled. `start-first` is the zero-downtime path; `stop-first` is
+ * compose's own recreate, kept where two containers of the role cannot coexist, with the reason.
+ */
+export type ComposeStrategy =
+  | { readonly kind: 'start-first'; readonly replicas: number }
+  | { readonly kind: 'stop-first'; readonly why: string };
+
+/** The roles that stay up serving — the only ones a rollout strategy applies to. */
+export const SERVING_ROLES = ['web', 'sync', 'worker', 'scheduler'] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * The host port a `ports:` entry pins, or `undefined` when Docker picks it. Short syntax is
+ * `[[ip:]host:]container[/proto]`: `3000` and `127.0.0.1::3000` leave the host side to Docker, so
+ * any number of replicas bind; `3000:3000` and `127.0.0.1:3001:3001` name one, which exactly one
+ * container can hold. Long syntax pins one when `published` is said.
+ */
+function pinnedHostPort(entry: unknown): string | undefined {
+  if (isRecord(entry)) {
+    const published = entry['published'];
+    return published === undefined || published === null || published === ''
+      ? undefined
+      : String(published);
+  }
+  if (typeof entry !== 'string') return undefined;
+  const spec = entry.replace(/^\[[^\]]*\]:/, '').split('/')[0] ?? '';
+  const parts = spec.split(':');
+  const host = parts.length === 3 ? parts[1] : parts.length === 2 ? parts[0] : '';
+  return host === undefined || host === '' ? undefined : host;
+}
+
+/** One service's strategy: start-first unless something in its definition forbids a second copy. */
+function strategyOf(service: unknown): ComposeStrategy {
+  if (!isRecord(service)) {
+    return { kind: 'stop-first', why: 'the compose file declares no such service' };
+  }
+  if (service['container_name'] !== undefined) {
+    return {
+      kind: 'stop-first',
+      why: 'container_name names exactly one container, so a second replica cannot be created',
+    };
+  }
+  if (service['network_mode'] === 'host') {
+    return {
+      kind: 'stop-first',
+      why: 'network_mode: host binds the host ports directly, so two replicas collide',
+    };
+  }
+  const ports = Array.isArray(service['ports']) ? service['ports'] : [];
+  const pinned = ports.map(pinnedHostPort).find((port) => port !== undefined);
+  if (pinned !== undefined) {
+    return {
+      kind: 'stop-first',
+      why: `publishes host port ${pinned}, which one container can bind — remove ports: and route through a proxy on the compose network to roll it start-first`,
+    };
+  }
+  const deploy = service['deploy'];
+  const declared = isRecord(deploy) ? deploy['replicas'] : undefined;
+  const replicas =
+    typeof declared === 'number' && Number.isSafeInteger(declared) && declared >= 0 ? declared : 1;
+  return { kind: 'start-first', replicas };
+}
+
+/**
+ * Every serving role's strategy, from the compose file's text. A file that is absent or does not
+ * parse decides nothing: every role keeps stop-first, and compose reports the file's own error
+ * when the step runs — this reader is never a second validator of it.
+ */
+export function composeStrategies(text: string | undefined): ReadonlyMap<string, ComposeStrategy> {
+  let parsed: unknown;
+  try {
+    parsed = text === undefined ? undefined : Bun.YAML.parse(text);
+  } catch {
+    parsed = undefined;
+  }
+  const services = isRecord(parsed) ? parsed['services'] : undefined;
+  if (!isRecord(services)) return new Map();
+  return new Map(SERVING_ROLES.map((role) => [role, strategyOf(services[role])]));
+}
+
+/** The compose file at `path`, or `undefined` when there is none to read. */
+export async function readComposeFile(path: string): Promise<string | undefined> {
+  const file = Bun.file(path);
+  return (await file.exists()) ? file.text() : undefined;
+}

package/src/cmd-deploy-drain.ts

@@ -0,0 +1,48 @@
+// What a helm deploy tells the chart about the drain: `app.config.ts`'s `drain` section — the ONE
+// drain budget since 25.0.0 deleted `http.drainTimeoutMs` — in the seconds `docker/helm` derives
+// each role's terminationGracePeriodSeconds from. Passed on every upgrade, so a raised
+// budget can never ship against a grace period sized for 25 s.
+
+import type { DrainConfig } from '@ultimat3/core';
+import { isUltimateError, READINESS_GRACE_DEFAULT_MS } from '@ultimat3/core';
+import { loadDrainConfig } from './serve-drain';
+
+const seconds = (ms: number): number => Math.ceil(ms / 1000);
+
+/**
+ * The `--set` pairs, or none when the app declares no budget (the chart's defaults are core's).
+ * The chart's `drain.deadlineSeconds` is ONE budget for every role, and so is `drain.deadlineMs`:
+ * the web role drains on it too. The margins stay the chart's.
+ *
+ * The grace is budgeted at no less than core's production default: the value read here is resolved
+ * in THIS process's environment, and an `x deploy` run under `NODE_ENV=development` resolves the
+ * grace to 0 while the pod it deploys runs with 5 s. Over-budgeting costs a pod nothing — it exits
+ * when its drain does — and under-budgeting is a SIGKILL mid-drain.
+ */
+export function helmDrainOverrides(drain: Partial<DrainConfig> | undefined): readonly string[] {
+  const out: string[] = [];
+  if (drain?.deadlineMs !== undefined) {
+    out.push('--set', `drain.deadlineSeconds=${seconds(drain.deadlineMs)}`);
+  }
+  if (drain === undefined) return out;
+  const grace = Math.max(drain.readinessGraceMs ?? 0, READINESS_GRACE_DEFAULT_MS);
+  out.push('--set', `drain.readinessGraceSeconds=${seconds(grace)}`);
+  return out;
+}
+
+/**
+ * The overrides for the app at `root`, off the one config loader. An `app.config.ts` the loader
+ * refuses yields no drain section, and the chart's defaults stand: `X_CONFIG_INVALID`'s own fix for
+ * a helm deploy is `--release <name>`, which must stay a way out, and the pods this upgrade starts
+ * refuse the same config at boot — which `helm upgrade --wait` reports as the failed rollout it is.
+ */
+export async function readHelmDrainOverrides(root: string): Promise<readonly string[]> {
+  let drain: Partial<DrainConfig> | undefined;
+  try {
+    drain = await loadDrainConfig(root);
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_CONFIG_INVALID') throw error;
+    return [];
+  }
+  return helmDrainOverrides(drain);
+}

package/src/cmd-deploy-helm.ts

@@ -8,8 +8,7 @@
 // why: Bun exposes no path-join primitive; the chart path is handed to helm as one joined string.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { BadFlagError } from './errors';
 
 /** Long enough for a migration a pre-upgrade hook must finish; helm's own 5m default is not. */
@@ -67,16 +66,18 @@ export function readLabel(flag: 'namespace' | 'release', raw: string): string {
  */
 export async function readReleaseName(root: string, flag: string | undefined): Promise<string> {
   if (flag !== undefined) return readLabel('release', flag);
-  const module = (await import(join(root, APP_CONFIG_FILE))) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const name = isRecord(config) ? config['name'] : undefined;
+  const config = await loadAppConfig(root);
+  // `unknown`, not the declared `string`: core reads an absent name as `"undefined"` and lets it by.
+  const name: unknown = config?.name;
   if (typeof name === 'string' && name.length <= RELEASE_MAX && LABEL.test(name)) return name;
   throw new UltimateError({
     code: 'X_CONFIG_INVALID',
     cause:
       typeof name === 'string'
         ? `app.config.ts names the app "${name.slice(0, 80)}", which is not a helm release name (a DNS-1123 label of at most ${RELEASE_MAX} characters)`
-        : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
+        : config === undefined
+          ? `${root} has no app.config.ts, and x deploy --method helm names the release after its config.name`
+          : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
     fix: 'name the release explicitly: x deploy --method helm --release my-app --json',
   });
 }