@ultimat3/cli 20.2.1 → 22.0.0

package/src/cmd-build-spec.ts

@@ -0,0 +1,16 @@
+// `x build`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-build.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const buildSpec: CommandSpec = {
+  name: 'build',
+  summary: 'build a container image, a single binary, or a prerendered static site',
+  usage: 'x build --target docker|binary|static [--tag name] [--out path] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
+    { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
+    { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
+  ],
+};

package/src/cmd-build.ts

@@ -2,15 +2,17 @@
 // means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
 
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, frameworkVersion, 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 { BuildEntryMissingError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
+import { prepareImage } from './image-prepare';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
@@ -56,9 +58,24 @@ export function requireEntry(root: string, target: BuildTarget): string {
   return absolute;
 }
 
-/** One image for every role; ROLE selects behaviour at start, so there is one artifact to promote. */
-export function dockerArgs(root: string, tag: string): readonly string[] {
-  return ['docker', 'build', '-f', join(root, BUILD_ENTRY.docker), '-t', tag, root];
+/**
+ * One image for every role; ROLE selects behaviour at start, so there is one artifact to promote.
+ * `BUILD_ID` is the manifest's own build id, passed as the build arg the scaffolded Dockerfile
+ * declares: without it the image's `BUILD_ID` was empty and every role computed one at boot, so
+ * two replicas of one image could disagree about the id their clients are served against.
+ */
+export function dockerArgs(root: string, tag: string, buildId: string): readonly string[] {
+  return [
+    'docker',
+    'build',
+    '-f',
+    join(root, BUILD_ENTRY.docker),
+    '--build-arg',
+    `BUILD_ID=${buildId}`,
+    '-t',
+    tag,
+    root,
+  ];
 }
 
 /**
@@ -93,9 +110,15 @@ export function staticArgs(root: string, out: string): readonly string[] {
 
 export function argsFor(
   target: BuildTarget,
-  paths: { readonly root: string; readonly tag: string; readonly out: string },
+  paths: {
+    readonly root: string;
+    readonly tag: string;
+    readonly out: string;
+    /** The docker target's `BUILD_ID` build arg — `appManifest(root)`'s own. */
+    readonly buildId?: string;
+  },
 ): readonly string[] {
-  if (target === 'docker') return dockerArgs(paths.root, paths.tag);
+  if (target === 'docker') return dockerArgs(paths.root, paths.tag, paths.buildId ?? 'dev');
   if (target === 'binary') return binaryArgs(paths.root, paths.out);
   return staticArgs(paths.root, paths.out);
 }
@@ -162,17 +185,7 @@ export function buildResult(input: {
 }
 
 export const buildCommand: CliCommand = {
-  spec: {
-    name: 'build',
-    summary: 'build a container image, a single binary, or a prerendered static site',
-    usage: 'x build --target docker|binary|static [--tag name] [--out path] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
-      { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
-      { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
-    ],
-  },
+  spec: buildSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('build', ctx.cwd).dir;
     const target = readTarget(flagString(ctx.args, 'target'));
@@ -186,15 +199,28 @@ export const buildCommand: CliCommand = {
     const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
       staticSteps.includes(step.name),
     );
-    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner });
+    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner, env: ctx.env });
     if (!verifyResult.ok) {
       return preflightResult(verifyResult);
     }
 
+    // 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 =
-      flagString(ctx.args, 'out') ?? join(root, '.x', target === 'static' ? 'static' : 'app');
+      outFlag === undefined
+        ? join(root, '.x', target === 'static' ? 'static' : 'app')
+        : resolve(ctx.cwd, outFlag);
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
-    const command = argsFor(target, { root, tag, out });
+    // The docker target stamps the manifest's build id into the image, and writes the island
+    // chunks the image serves, so a container boot neither re-derives the one nor rebuilds the other.
+    const buildId = target === 'docker' ? await prepareImage(root) : undefined;
+    const command = argsFor(target, {
+      root,
+      tag,
+      out,
+      ...(buildId === undefined ? {} : { buildId }),
+    });
     // 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.
     if (target === 'static') await removeStaticReport(root);

package/src/cmd-ci-spec.ts

@@ -0,0 +1,24 @@
+// `x ci`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-ci.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
+export const TAIL_LINES = 40;
+
+export const ciSpec: CommandSpec = {
+  name: 'ci',
+  summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
+  usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+  flags: [
+    { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+    { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
+    { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
+    {
+      name: 'tail',
+      type: 'string',
+      summary: `log lines kept per failed job (default ${TAIL_LINES})`,
+    },
+    { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+  ],
+};

package/src/cmd-ci.ts

@@ -9,14 +9,18 @@ import type { CiLogLine } from './ci-log';
 import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
+import { ciSpec, TAIL_LINES } from './cmd-ci-spec';
 import type { CliCommand, CommandContext } from './command';
 import { parseIntFlag } from './flag-number';
+import { commentBlock } from './foreign-text';
 import type { GhRepo } from './gh-target';
 import { currentBranch, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
 
+export { TAIL_LINES } from './cmd-ci-spec';
+
 /**
  * Every catalog key this command renders, declared — `msg()` answers `⟦key⟧` for a key nobody
  * added, which is loud in a terminal and SILENT to a build. `cmd-ci.test.ts` holds this list
@@ -34,9 +38,6 @@ export const CI_MESSAGE_KEYS = [
   'cli.ci.logs.empty',
 ] as const;
 
-/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
-export const TAIL_LINES = 40;
-
 /** How far back a branch's run history is read before "the latest run of each workflow". */
 export const RUN_LOOKBACK = 20;
 
@@ -55,22 +56,7 @@ const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 3248
 const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
 
 export const ciCommand: CliCommand = {
-  spec: {
-    name: 'ci',
-    summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
-    usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
-    flags: [
-      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
-      { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
-      { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
-      {
-        name: 'tail',
-        type: 'string',
-        summary: `log lines kept per failed job (default ${TAIL_LINES})`,
-      },
-      { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
-    ],
-  },
+  spec: ciSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
     const rawRun = flagString(ctx.args, 'run');
@@ -142,7 +128,14 @@ async function inspect(
     const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
     const job = failed.find((candidate) => candidate.name === name);
     for (const finding of findingsFrom(pool)) {
-      findings.push(finding.at === undefined ? { ...finding, at: name } : finding);
+      findings.push({
+        ...finding,
+        at: finding.at ?? name,
+        // Fenced and tagged: the log is foreign text, and a `fix:` reconstructed from it is the
+        // log author's instruction, not this CLI's. `commentBlock` is `x pr review`'s fence.
+        fix: commentBlock(`ci-log ${name}`, [finding.fix]).join('\n'),
+        source: 'ci-log',
+      });
     }
     failures.push({
       job: name,
@@ -229,7 +222,8 @@ function runLines(entry: RunReport): readonly string[] {
       continue;
     }
     out.push(msg('cli.ci.tail', { job: failure.job }));
-    for (const line of failure.tail) out.push(`      | ${line}`);
+    for (const line of commentBlock(`ci-log ${failure.job}`, failure.tail))
+      out.push(`      | ${line}`);
   }
   const jobs = entry.jobs;
   if (jobs !== undefined && jobs.length > failures.length) {
@@ -266,6 +260,8 @@ function runJson(entry: RunReport): JsonValue {
             job: failure.job,
             url: failure.url,
             failedSteps: [...failure.failedSteps],
+            // Raw lines for a machine, labelled as foreign: the log's author wrote every one.
+            tailSource: 'ci-log',
             tail: [...failure.tail],
           })),
         }),

package/src/cmd-db-branch.ts

@@ -23,12 +23,12 @@ import {
   previewUrl,
 } from './db-branch';
 import { stepFinding } from './db-finding';
-import type { DevServices } from './dev-services';
-import { resolveServices } from './dev-services';
 import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagString } from './parse';
+import type { DevServices } from './runtime-bindings';
+import { resolveServices } from './runtime-bindings';
 import { portFromEnv } from './serve';
 import { renderTable } from './table';
 

package/src/cmd-db-spec.ts

@@ -0,0 +1,99 @@
+// `x db`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-db.ts`, which `registry.ts` imports only when the command runs.
+
+import { BRANCH_SUBCOMMANDS } from './db-branch';
+import type { CommandSpec } from './parse';
+
+export const DB_SUBCOMMANDS = [
+  'gen',
+  'migrate',
+  'reset',
+  'seed',
+  'studio',
+  'branch',
+  'backfill',
+] as const;
+
+export const dbSpec: CommandSpec = {
+  name: 'db',
+  summary: 'gen, migrate, reset, seed, studio, branch, backfill',
+  usage:
+    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+  requiresApp: true,
+  subcommands: DB_SUBCOMMANDS,
+  // Declared from the constant `runBranchCommand` validates against, never a second literal: it
+  // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
+  // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
+  subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
+  // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses
+  // it anywhere else: `x db gen --dry-run` used to parse, reach `runGen` and WRITE the
+  // migration. `cmd-db.test.ts` pins summary and scope to the same fact.
+  flags: [
+    {
+      name: 'name',
+      type: 'string',
+      summary: 'migration, branch or seed name, or backfill to filter',
+    },
+    {
+      name: 'tier',
+      type: 'string',
+      summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
+      subcommands: ['seed'],
+    },
+    {
+      name: 'dry-run',
+      type: 'boolean',
+      summary: 'seed: report what each seed would write, and write nothing',
+      subcommands: ['seed'],
+    },
+    {
+      name: 'list',
+      type: 'boolean',
+      summary: 'backfill: print the x_backfills ledger',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'pending',
+      type: 'boolean',
+      summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'all',
+      type: 'boolean',
+      summary: 'backfill: every pending sweep, isolated per name',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'write',
+      type: 'boolean',
+      summary: 'backfill: enqueue the pass; dry run without it',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'force',
+      type: 'boolean',
+      summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'status',
+      type: 'string',
+      summary: 'backfill: filter by running, completed or failed',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'limit',
+      type: 'string',
+      summary: 'backfill: max ledger rows to return',
+      subcommands: ['backfill'],
+    },
+    // Declared because `X_MIGRATION_IRREVERSIBLE`'s own fix line names it. A `fix:` is copied
+    // and run verbatim, so a flag the parser refuses would make the error unfollowable.
+    {
+      name: 'allow-destructive',
+      type: 'boolean',
+      summary: 'let x db gen emit a drop whose down cannot restore the rows',
+    },
+  ],
+};

package/src/cmd-db.ts

@@ -17,9 +17,9 @@ import { postgresDriver } from '@ultimat3/entity';
 import { requireAppRoot } from './app-root';
 import { runBackfillCommand } from './cmd-db-backfill';
 import { runBranchCommand } from './cmd-db-branch';
+import { DB_SUBCOMMANDS, dbSpec } from './cmd-db-spec';
 import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
-import { BRANCH_SUBCOMMANDS } from './db-branch';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
 import type { SeedPassRow } from './db-seed';
@@ -32,109 +32,20 @@ import {
   seedTotals,
   selectSeeds,
 } from './db-seed';
-import { resolveServices } from './dev-services';
+import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
 import { CliNotImplementedError, MissingSubcommandError, UnknownCommandError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagBool, flagString } from './parse';
+import { resolveServices } from './runtime-bindings';
 import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = [
-  'gen',
-  'migrate',
-  'reset',
-  'seed',
-  'studio',
-  'branch',
-  'backfill',
-] as const;
+export { DB_SUBCOMMANDS } from './cmd-db-spec';
 
 export const dbCommand: CliCommand = {
-  spec: {
-    name: 'db',
-    summary: 'gen, migrate, reset, seed, studio, branch, backfill',
-    usage:
-      'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
-    requiresApp: true,
-    subcommands: DB_SUBCOMMANDS,
-    // Declared from the constant `runBranchCommand` validates against, never a second literal: it
-    // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
-    // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
-    subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
-    // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses
-    // it anywhere else: `x db gen --dry-run` used to parse, reach `runGen` and WRITE the
-    // migration. `cmd-db.test.ts` pins summary and scope to the same fact.
-    flags: [
-      {
-        name: 'name',
-        type: 'string',
-        summary: 'migration, branch or seed name, or backfill to filter',
-      },
-      {
-        name: 'tier',
-        type: 'string',
-        summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
-        subcommands: ['seed'],
-      },
-      {
-        name: 'dry-run',
-        type: 'boolean',
-        summary: 'seed: report what each seed would write, and write nothing',
-        subcommands: ['seed'],
-      },
-      {
-        name: 'list',
-        type: 'boolean',
-        summary: 'backfill: print the x_backfills ledger',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'pending',
-        type: 'boolean',
-        summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'all',
-        type: 'boolean',
-        summary: 'backfill: every pending sweep, isolated per name',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'write',
-        type: 'boolean',
-        summary: 'backfill: enqueue the pass; dry run without it',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'force',
-        type: 'boolean',
-        summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'status',
-        type: 'string',
-        summary: 'backfill: filter by running, completed or failed',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'limit',
-        type: 'string',
-        summary: 'backfill: max ledger rows to return',
-        subcommands: ['backfill'],
-      },
-      // Declared because `X_MIGRATION_IRREVERSIBLE`'s own fix line names it. A `fix:` is copied
-      // and run verbatim, so a flag the parser refuses would make the error unfollowable.
-      {
-        name: 'allow-destructive',
-        type: 'boolean',
-        summary: 'let x db gen emit a drop whose down cannot restore the rows',
-      },
-    ],
-  },
+  spec: dbSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('db', ctx.cwd).dir;
     // No default, and no `?? 'migrate'` here either: `gen` writes a migration file and `reset`
@@ -299,6 +210,16 @@ async function runReset(ctx: CommandContext, root: string): Promise<CommandResul
       fix: 'drop and recreate the database yourself, then run: x db migrate',
     });
   }
+  // A running `x dev` has this directory open: deleting it under a live embedded Postgres is data
+  // loss mid-write, not a reset. The dev lock is the one fact that says someone holds it.
+  const holder = liveDevLock(services.stateDir);
+  if (holder !== undefined) {
+    throw new DevAlreadyRunningError({
+      lock: holder,
+      stateDir: services.stateDir,
+      embeddedDb: true,
+    });
+  }
   await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
   return runMigrate(ctx, root, msg('cli.db.reset.done'));
 }

package/src/cmd-deploy-helm.ts

@@ -0,0 +1,136 @@
+// The helm half of `x deploy`: which release, in which namespace, waited on for how long, and what
+// the rollout reported. Split from cmd-deploy.ts, which owns the plan and the compose method.
+//
+// `helm upgrade --install` with no `--wait` exits 0 the moment the API server ACCEPTS the objects,
+// so a deploy whose pods never became ready reported success; and helm's default 5m timeout failed
+// an upgrade whose migrate hook was still applying a long migration, leaving the Job running.
+
+// 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 { BadFlagError } from './errors';
+
+/** Long enough for a migration a pre-upgrade hook must finish; helm's own 5m default is not. */
+export const HELM_DEFAULT_TIMEOUT = '15m';
+
+/** What a helm deploy is aimed at, resolved once from the flags and `app.config.ts`. */
+export interface HelmTarget {
+  readonly release: string;
+  readonly namespace: string | undefined;
+  readonly timeout: string;
+}
+
+/** Helm's own `time.ParseDuration` grammar, positive units only: `15m`, `900s`, `1h30m`. */
+const DURATION = /^(?:\d+(?:h|m|s|ms))+$/;
+/** A namespace and a release are both DNS-1123 labels; helm caps a release at 53 characters. */
+const LABEL = /^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$/;
+const RELEASE_MAX = 53;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/** `--timeout`, screened: a value helm would reject is refused before anything is spawned. */
+export function readHelmTimeout(raw: string | undefined): string {
+  if (raw === undefined) return HELM_DEFAULT_TIMEOUT;
+  if (DURATION.test(raw) && /[1-9]/.test(raw)) return raw;
+  throw new BadFlagError({
+    flag: 'timeout',
+    command: 'deploy',
+    reason: 'it is not a positive helm duration such as 15m, 900s or 1h30m',
+    fix: 'x deploy --method helm --timeout 15m --json',
+  });
+}
+
+/** `--namespace` and `--release`, each a DNS-1123 label or a refusal naming the flag. */
+export function readLabel(flag: 'namespace' | 'release', raw: string): string {
+  const max = flag === 'release' ? RELEASE_MAX : 63;
+  if (raw.length <= max && LABEL.test(raw)) return raw;
+  throw new BadFlagError({
+    flag,
+    command: 'deploy',
+    reason: `it must be a lowercase DNS-1123 label of at most ${max} characters`,
+    fix:
+      flag === 'release'
+        ? 'x deploy --method helm --release my-app --json'
+        : 'x deploy --method helm --namespace my-namespace --json',
+  });
+}
+
+/**
+ * The release name: `--release`, else `app.config.ts`'s `name`. It was the literal `app` for every
+ * app, so two apps deployed to one namespace were one release and the second upgrade replaced the
+ * first. `--release` exists for a release that already carries another name — `app`, for every
+ * cluster an earlier version deployed to — because a release name is cluster state the framework
+ * does not own and cannot rename.
+ */
+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;
+  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',
+    fix: 'name the release explicitly: x deploy --method helm --release my-app --json',
+  });
+}
+
+/** The one `helm upgrade`, waited on: `--wait` for the rollout, `--output json` for the verdict. */
+export function helmUpgradeArgs(
+  root: string,
+  target: HelmTarget,
+  imageOverrides: readonly string[],
+): readonly string[] {
+  return [
+    'helm',
+    'upgrade',
+    '--install',
+    target.release,
+    join(root, 'docker', 'helm'),
+    ...(target.namespace === undefined ? [] : ['--namespace', target.namespace]),
+    '--wait',
+    '--timeout',
+    target.timeout,
+    '--output',
+    'json',
+    ...imageOverrides,
+  ];
+}
+
+/** What `--json` reports about the rollout helm waited on. */
+export interface Rollout {
+  readonly release: string;
+  readonly namespace: string | null;
+  readonly revision: number | null;
+  readonly status: string;
+}
+
+/**
+ * helm's `--output json` release record, read structurally. `status` is helm's own word —
+ * `deployed`, `failed`, `pending-upgrade` — and `unknown` only when helm printed no record at all,
+ * never a guess dressed as one.
+ */
+export function readRollout(target: HelmTarget, stdout: string): Rollout {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    parsed = undefined;
+  }
+  const info = isRecord(parsed) ? parsed['info'] : undefined;
+  const status = isRecord(info) ? info['status'] : undefined;
+  const revision = isRecord(parsed) ? parsed['version'] : undefined;
+  const namespace = isRecord(parsed) ? parsed['namespace'] : undefined;
+  return {
+    release: target.release,
+    namespace: typeof namespace === 'string' ? namespace : (target.namespace ?? null),
+    revision: typeof revision === 'number' ? revision : null,
+    status: typeof status === 'string' ? status : 'unknown',
+  };
+}