@ultimat3/cli 1.1.0 → 2.0.0

package/src/cmd-db.ts

@@ -1,187 +1,364 @@
-// `x db gen|migrate|reset|studio|branch` — everything that touches the database, including the
-// branch DB that makes destructive work safe. An agent that can clone the database in a second
-// can migrate, seed and break things without a human deciding whether to let it.
+// `x db gen|migrate|reset|studio|branch|backfill` — everything that touches the database. One
+// subcommand per line and no fall-through: a word this file does not know is refused, never
+// re-read as an argument to the last branch. `branch` itself is `cmd-db-branch.ts`.
+//
+// Every subcommand here runs `@ultimat3/db`'s own engine, which is the engine `ROLE=migrate` runs
+// (`serve.ts`): one `x_migrations` ledger, one checksum rule, one advisory lock, from a laptop to
+// a release phase. Until 1.2.0 these shelled out to `bunx drizzle-kit` — a second engine with a
+// second journal, declared in no `package.json` and fetched unpinned at run time.
 
-import { existsSync, readdirSync } from 'node:fs';
+// `node:fs/promises` for `rm` — `Bun.file().delete()` takes one file, and `x db reset` removes a
+// directory tree. `node:path` for `join` — Bun exposes no path joiner.
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { branchPglite } from '@ultimat3/db';
+import { resolveEnvironment } from '@ultimat3/core';
+import { type DriftReport, driftError } from '@ultimat3/db';
+import { BackfillPendingError } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { runBranchCommand } from './cmd-db-branch';
+import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
+import type { BackfillAction, BackfillPlanRow } from './db-backfill';
+import {
+  listBackfills,
+  pendingReport,
+  pendingToJson,
+  planToJson,
+  readAppliedMigrations,
+  renderBackfillTable,
+  renderPendingTable,
+  renderPlanTable,
+  runBackfills,
+} from './db-backfill';
+import { BRANCH_SUBCOMMANDS } from './db-branch';
+import { stepFinding } from './db-finding';
+import { generateAppMigration } from './db-generate';
 import { resolveServices } from './dev-services';
-import { checkDrift, writeSchemaHash } from './drift';
-import { CliNotImplementedError } from './errors';
-import type { ExecResult } from './exec';
-import { execOutput } from './exec';
+import {
+  BadFlagError,
+  CliNotImplementedError,
+  MissingSubcommandError,
+  UnknownCommandError,
+} from './errors';
+import { withJobDriver } from './jobs-driver';
+import { backfillToJson } from './jobs-json';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
-import { flagString } from './parse';
+import { flagBool, flagString } from './parse';
+import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch'] as const;
+export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch', 'backfill'] as const;
 
-const failure = (result: ExecResult, code: string, fix: string): Finding => ({
-  code,
-  cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
-  fix,
-  docs: `https://ultimate.dev/errors/${code}`,
-});
-
-/** `x db branch <name>` on a real Postgres: copy-on-write clone, cheap and disposable. */
-export function branchSql(source: string, branch: string): string {
-  return `CREATE DATABASE "${branch}" TEMPLATE "${source}"`;
-}
+export const dbCommand: CliCommand = {
+  spec: {
+    name: 'db',
+    summary: 'gen, migrate, reset, studio, branch, backfill',
+    usage:
+      'x db gen "add publish_at" | migrate | reset | 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 },
+    flags: [
+      { name: 'name', type: 'string', summary: 'migration or branch name, or backfill to filter' },
+      { name: 'list', type: 'boolean', summary: 'backfill: print the x_backfills ledger' },
+      {
+        name: 'pending',
+        type: 'boolean',
+        summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
+      },
+      { name: 'all', type: 'boolean', summary: 'backfill: every pending sweep, isolated per name' },
+      { name: 'write', type: 'boolean', summary: 'backfill: enqueue the pass; dry run without it' },
+      {
+        name: 'force',
+        type: 'boolean',
+        summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
+      },
+      {
+        name: 'status',
+        type: 'string',
+        summary: 'backfill: filter by running, completed or failed',
+      },
+      { name: 'limit', type: 'string', summary: 'backfill: max ledger rows to return' },
+      // 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',
+      },
+    ],
+  },
+  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`
+    // drops the database, so "whatever the caller left out" is not a safe guess for any of the six.
+    // The parser refuses a bare `x db`; this covers a `ParsedArgs` built by hand.
+    const sub = ctx.args.subcommand;
+    if (sub === undefined)
+      throw new MissingSubcommandError({ command: 'db', known: DB_SUBCOMMANDS });
+    const argument = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
 
-export function branchDatabaseName(source: string, branch: string): string {
-  return `${source}_branch_${branch.replace(/[^a-zA-Z0-9_]/g, '_')}`;
-}
+    if (sub === 'gen') return runGen(ctx, root, argument ?? 'change');
+    if (sub === 'migrate') return runMigrate(ctx, root, msg('cli.db.migrate.applied'));
+    if (sub === 'reset') return runReset(ctx, root);
+    if (sub === 'studio') throw plannedSubcommand('db', 'studio');
+    if (sub === 'backfill') return runBackfill(ctx, root);
+    if (sub === 'branch') return runBranchCommand(ctx, root);
 
-export const previewUrl = (branch: string, port: number): string =>
-  `http://${branch}.localhost:${port}`;
+    // Never a fall-through. This used to end `return runBranch(ctx, root, argument ?? 'preview')`,
+    // so ANY subcommand the parser had not already refused was reinterpreted as a branch NAME and
+    // cloned a database out of it. A word this command does not know is a refusal, not a guess.
+    throw new UnknownCommandError({
+      path: `db ${sub}`,
+      known: DB_SUBCOMMANDS,
+      // Help, and not the nearest name: `studio` is planned, and `branch`/`backfill` both need a
+      // word this refusal does not have — a suggestion that refuses in turn is not a fix.
+      suggestion: 'help db',
+    });
+  },
+};
 
-async function runBranch(
-  ctx: CommandContext,
-  root: string,
-  branch: string,
-): Promise<CommandResult> {
-  const services = resolveServices(root, ctx.env);
-  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
-  const url = previewUrl(branch, port);
-  if (services.db.mode === 'embedded') {
-    // @ultimat3/db owns embedded branching, name validation and the on-disk layout. Shelling out
-    // to `cp` here was a second implementation of all three — and `--reflink` is a GNU-only flag.
-    try {
-      const info = await branchPglite(branch, { from: services.db.url });
-      return {
-        ok: true,
-        command: 'db',
-        summary: msg('cli.db.branch.ready', { name: branch }),
-        data: { branch, database: info.dataDir, preview: url, mode: 'embedded' },
-      };
-    } catch (error) {
-      return {
-        ok: false,
-        command: 'db',
-        summary: msg('cli.usage'),
-        findings: [findingFrom(error)],
-      };
-    }
-  }
-  const source = services.db.url.split('/').at(-1) ?? 'postgres';
-  const database = branchDatabaseName(source, branch);
-  const psql = await ctx.runner(['psql', services.db.url, '-c', branchSql(source, database)], {
-    cwd: root,
-  });
-  if (!psql.ok) {
+/**
+ * Source in, files out — no database is opened, so this answers the same in CI and on a laptop
+ * with nothing running. A diff that finds nothing writes nothing and still exits 0: "no change" is
+ * an answer, and an empty migration would take a ledger row and a checksum forever.
+ */
+async function runGen(ctx: CommandContext, root: string, name: string): Promise<CommandResult> {
+  let generated: Awaited<ReturnType<typeof generateAppMigration>>;
+  try {
+    generated = await generateAppMigration(root, {
+      name,
+      allowDestructive: flagBool(ctx.args, 'allow-destructive'),
+    });
+  } catch (error) {
     return {
       ok: false,
       command: 'db',
-      summary: msg('cli.usage'),
-      findings: [
-        failure(
-          psql,
-          'X_DB_BRANCH_FAILED',
-          `close open connections to "${source}" (a TEMPLATE clone needs none), then retry`,
-        ),
-      ],
+      summary: msg('cli.db.gen.failed'),
+      findings: [stepFinding(error, 'X_DB_GEN_FAILED')],
+    };
+  }
+  const migration = generated.migration;
+  if (migration === undefined) {
+    return {
+      ok: generated.findings.length === 0,
+      command: 'db',
+      summary: msg('cli.db.gen.unchanged'),
+      findings: generated.findings,
+      data: { migration: null, files: [] },
     };
   }
   return {
     ok: true,
     command: 'db',
-    summary: msg('cli.db.branch.ready', { name: branch }),
-    data: { branch, database, preview: url, mode: 'external' },
+    summary: msg('cli.db.gen.written', { id: migration.id }),
+    lines: generated.files.map((file) => `  ${file}`),
+    data: {
+      migration: migration.id,
+      name: migration.name,
+      files: [...generated.files],
+      schemaHash: generated.schemaHash ?? null,
+    },
   };
 }
 
-export const dbCommand: CliCommand = {
-  spec: {
-    name: 'db',
-    summary: 'gen, migrate, reset, studio, branch',
-    usage: 'x db gen "add publish_at" | migrate | reset | studio | branch <name>',
-    requiresApp: true,
-    subcommands: DB_SUBCOMMANDS,
-    flags: [{ name: 'name', type: 'string', summary: 'migration or branch name' }],
-  },
-  async run(ctx: CommandContext): Promise<CommandResult> {
-    const root = requireAppRoot('db', ctx.cwd).dir;
-    const sub = ctx.args.subcommand ?? 'migrate';
-    const argument = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+/**
+ * The post-migrate report, rendered. Through `driftError` rather than a second literal: the
+ * three-line `X_DB_DRIFT` output is pinned by the framework contract, and this command must not be
+ * where a copy of it drifts from the one `x verify` prints.
+ */
+export const driftFindings = (report: DriftReport): readonly Finding[] =>
+  report.differences.map((difference) => findingFrom(driftError(difference)));
+
+/**
+ * `runMigrations` is `serve.ts`'s, unchanged and unwrapped: the developer applying a migration and
+ * the release-phase container applying it run the same function, over the same file list, through
+ * the same ledger, and verify the same post-condition — the live schema against that ledger. A
+ * database that migrated cleanly and still disagrees is the failure this command exists to
+ * surface, and only a check that opened the connection can see it.
+ *
+ * The *source* half — an entity edited with no migration generated — is `x verify`'s `drift` step
+ * (`checkSourceDrift`) and is deliberately not repeated here: two reporters of one condition is the
+ * duplication this package's own rule forbids, and that one needs no database at all.
+ */
+async function runMigrate(
+  ctx: CommandContext,
+  root: string,
+  summary: string,
+): Promise<CommandResult> {
+  try {
+    const migrated = await runMigrations({ root, env: ctx.env });
+    const report = migrated.report;
+    return {
+      ok: migrated.drift.ok,
+      command: 'db',
+      summary,
+      findings: driftFindings(migrated.drift),
+      data: {
+        applied: report.applied.map((entry) => entry.id),
+        skipped: report.skipped.length,
+        appVersion: report.appVersion,
+        durationMs: report.durationMs,
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command: 'db',
+      summary: msg('cli.db.migrate.failed'),
+      findings: [stepFinding(error, 'X_DB_MIGRATE_FAILED')],
+    };
+  }
+}
 
-    if (sub === 'gen') {
-      const name = (argument ?? 'change').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'generate', '--name', name], {
-        cwd: root,
-      });
-      if (!result.ok) {
-        return {
-          ok: false,
-          command: 'db',
-          summary: msg('cli.usage'),
-          findings: [failure(result, 'X_DB_GEN_FAILED', 'x doctor --json')],
-        };
-      }
-      const hash = await writeSchemaHash(root, latestMigration(root, name));
-      return {
-        ok: true,
-        command: 'db',
-        summary: `migration ${name} generated`,
-        data: { migration: name, schemaHash: hash },
-      };
-    }
+/**
+ * Embedded only: `rm -rf` against a database this process does not own is not a reset, it is an
+ * outage. The data directory goes before the migrator starts, so the run that follows is a fresh
+ * database with an empty ledger rather than a re-apply over a live one.
+ */
+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',
+    });
+  }
+  await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
+  return runMigrate(ctx, root, msg('cli.db.reset.done'));
+}
 
-    if (sub === 'migrate') {
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      const drift = await checkDrift(root);
-      return {
-        ok: result.ok && drift.length === 0,
-        command: 'db',
-        summary: result.ok ? 'migrations applied' : 'migration failed',
-        findings: result.ok ? drift : [failure(result, 'X_DB_MIGRATE_FAILED', 'x db reset')],
-        data: { applied: result.ok },
-      };
-    }
+/**
+ * Four shapes, one subcommand: `--list` reads the `x_backfills` ledger, `--pending` diffs it
+ * against what the app DECLARED, and `<name>` / `--all` gate a pass and put it on the queue. A
+ * bare `x db backfill` is still refused rather than defaulted — the four answer four different
+ * questions, and picking one for the operator is the ambiguity axiom 1 exists to refuse.
+ *
+ * An empty ledger is `ok: true`. "Nothing has swept this database yet" is an answer to the
+ * question asked, and a command that failed over it would be unrunnable on a fresh app.
+ */
+async function runBackfill(ctx: CommandContext, root: string): Promise<CommandResult> {
+  if (flagBool(ctx.args, 'list')) return runBackfillList(ctx, root);
+  const all = flagBool(ctx.args, 'all');
+  const name = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+  if (flagBool(ctx.args, 'pending')) return runBackfillPending(ctx, root);
+  if (all) return runBackfillPass(ctx, root, 'all');
+  if (name !== undefined) return runBackfillPass(ctx, root, [name]);
+  throw new BadFlagError({
+    flag: 'list',
+    command: 'db',
+    reason:
+      'x db backfill needs a shape: --list (the ledger), --pending (declared minus completed), <name> or --all (run one, or every pending one)',
+    fix: 'x db backfill --pending --json',
+  });
+}
 
-    if (sub === 'reset') {
-      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',
-        });
-      }
-      await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
-      const migrate = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      return {
-        ok: migrate.ok,
-        command: 'db',
-        summary: migrate.ok ? 'database reset and migrated' : 'reset failed',
-        findings: migrate.ok ? [] : [failure(migrate, 'X_DB_MIGRATE_FAILED', 'x doctor --json')],
-        data: { stateDir: services.stateDir },
-      };
-    }
+async function runBackfillList(ctx: CommandContext, root: string): Promise<CommandResult> {
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await listBackfills(driver, {
+      name: flagString(ctx.args, 'name'),
+      status: flagString(ctx.args, 'status'),
+      limit: flagString(ctx.args, 'limit'),
+    });
+    return {
+      ok: true,
+      command: 'db',
+      summary:
+        rows.length === 0
+          ? msg('cli.db.backfill.empty')
+          : msg('cli.db.backfill.listed', { count: rows.length }),
+      lines: rows.length === 0 ? [] : renderBackfillTable(rows).map((line) => `  ${line}`),
+      data: rows.map(backfillToJson),
+    };
+  });
+}
 
-    if (sub === 'studio') {
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'studio'], { cwd: root });
-      return {
-        ok: result.ok,
-        command: 'db',
-        summary: result.ok ? 'studio exited' : 'studio failed to start',
-        findings: result.ok ? [] : [failure(result, 'X_DB_STUDIO_FAILED', 'x doctor --json')],
-      };
-    }
+/**
+ * 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.
+ */
+async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  return withJobDriver(root, ctx, async (driver) => {
+    const report = await pendingReport(driver, environment);
+    return {
+      ok: report.pending.length === 0,
+      command: 'db',
+      summary:
+        report.pending.length === 0
+          ? msg('cli.db.backfill.swept', { declared: report.rows.length })
+          : msg('cli.db.backfill.pending', {
+              count: report.pending.length,
+              declared: report.rows.length,
+            }),
+      findings: report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
+      data: pendingToJson(report),
+    };
+  });
+}
 
-    return runBranch(ctx, root, argument ?? 'preview');
-  },
-};
+/**
+ * DRY RUN by default: `--write` is never implied, because the alternative is a command whose
+ * inspection form writes to a production table. What `--write` does is ENQUEUE — the queue is a
+ * job's execution surface, so the sweep runs on the workers already serving the new release
+ * rather than inside this process.
+ */
+async function runBackfillPass(
+  ctx: CommandContext,
+  root: string,
+  names: readonly string[] | 'all',
+): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  const write = flagBool(ctx.args, 'write');
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await runBackfills({
+      driver,
+      names,
+      write,
+      force: flagBool(ctx.args, 'force'),
+      environment,
+      appliedMigrations: await readAppliedMigrations(),
+    });
+    return backfillPassResult(rows, write);
+  });
+}
 
-/** drizzle-kit names files `<index>_<name>.sql`; the hash sidecar has to match that base name. */
-function latestMigration(root: string, name: string): string {
-  const dir = join(root, 'packages', 'db', 'migrations');
-  if (!existsSync(dir)) return `0000_${name}`;
-  const matches = readdirSync(dir)
-    .filter((file) => file.endsWith(`_${name}.sql`))
-    .sort();
-  const newest = matches.at(-1);
-  return newest === undefined ? `0000_${name}` : newest.replace(/\.sql$/, '');
+/**
+ * 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.
+ */
+function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
+  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+  // 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.
+  const tally = (action: BackfillAction): number =>
+    rows.filter((row) => row.action === action).length;
+  return {
+    ok: findings.length === 0,
+    command: 'db',
+    summary: write
+      ? msg('cli.db.backfill.planned', {
+          count: rows.length,
+          enqueued: tally('enqueued'),
+          deduped: tally('deduped'),
+          blocked: tally('blocked'),
+        })
+      : msg('cli.db.backfill.dryRun', { count: rows.length }),
+    findings,
+    lines: rows.length === 0 ? [] : renderPlanTable(rows).map((line) => `  ${line}`),
+    data: planToJson(rows),
+  };
 }

package/src/cmd-deploy.ts

@@ -6,12 +6,35 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { CliNotImplementedError } from './errors';
+import { BadFlagError, CliNotImplementedError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
 
-export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler'] as const;
+/**
+ * Ordered, and the order is the design. `migrate` GATES — it runs to completion before anything
+ * serves, and a schema difference after it fails the deploy. `backfill` is last and TRIGGERS: a
+ * data sweep put inside a release gate holds the deploy open while a slow UPDATE runs against a
+ * database still serving the PREVIOUS release, so it runs after the new pods are up and the
+ * workers already draining the queue are what perform it. That is also why it is not wired into
+ * `runMigrations()` and never will be.
+ *
+ * `backfill` is a one-shot like `migrate`, so it takes the same `run --rm` shape; the compose
+ * service behind it runs `x db backfill --all --write --json` rather than a `ROLE`, because
+ * `@ultimat3/core`'s `ROLES` is a closed list of process shapes and a sweep trigger is a command.
+ *
+ * ORDER HERE IS NECESSARY AND NOT SUFFICIENT. `docker compose up -d` returns when a container has
+ * STARTED, not when the application inside it is serving, so this list alone puts the trigger after
+ * the serving roles were asked to start and not after they are ready. The barrier that makes
+ * "after" true is declarative and belongs to the compose file, not to this plan: the `backfill`
+ * service needs `depends_on: { web: { condition: service_healthy } }`, which `docker compose run`
+ * honours. Both compose definitions — `docker/docker-compose.prod.yml` and the one
+ * `templates/scaffold-container.ts` scaffolds — still owe that service and that condition.
+ */
+export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
+
+/** The roles that run to completion and exit, as against the ones that stay up serving. */
+const ONE_SHOT_ROLES: readonly string[] = ['migrate', 'backfill'];
 
 export interface DeployPlan {
   readonly image: string;
@@ -19,8 +42,39 @@ export interface DeployPlan {
   readonly steps: readonly { readonly role: string; readonly command: readonly string[] }[];
 }
 
+/**
+ * The chart declares `image` as a MAP — `repository`, `tag`, `pullPolicy` — and `_helpers.tpl`
+ * renders `printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag)`.
+ * `--set image=<ref>` replaces that map with a string, so every workload template fails on
+ * `.repository` and the deploy that was asked to ship one image ships nothing. The reference is
+ * split into the two keys the chart actually reads; a reference with no tag sets only the
+ * repository, which leaves the chart's own `default .Chart.AppVersion` in force.
+ *
+ * The last `:` after the last `/`, because a registry may carry a port: `localhost:5000/app` is a
+ * repository with no tag and `localhost:5000/app:1.2.3` is the same repository with one.
+ */
+export function helmImageOverrides(image: string): readonly string[] {
+  const colon = image.lastIndexOf(':');
+  const tag = colon > image.lastIndexOf('/') ? image.slice(colon + 1) : '';
+  const repository = tag === '' ? image : image.slice(0, colon);
+  return tag === ''
+    ? ['--set', `image.repository=${repository}`]
+    : ['--set', `image.repository=${repository}`, '--set', `image.tag=${tag}`];
+}
+
 export function planDeploy(image: string, method: 'compose' | 'helm', root: string): DeployPlan {
   if (method === 'helm') {
+    // `repo@sha256:…` is a reference this chart cannot express: it renders `repository:tag` and
+    // has no digest branch, so passing one through would deploy `repo@sha256:…:<appVersion>` —
+    // a tag no registry has. Refused here rather than by a `helm upgrade` failing halfway.
+    if (image.lastIndexOf('@') > image.lastIndexOf('/')) {
+      throw new BadFlagError({
+        flag: 'image',
+        command: 'deploy',
+        reason: `"${image}" pins a digest, and docker/helm renders repository:tag with no digest branch`,
+        fix: `x deploy --method helm --image ${image.slice(0, image.lastIndexOf('@'))}:<tag> --json`,
+      });
+    }
     return {
       image,
       steps: [
@@ -32,8 +86,7 @@ export function planDeploy(image: string, method: 'compose' | 'helm', root: stri
             '--install',
             'app',
             join(root, 'docker', 'helm'),
-            '--set',
-            `image=${image}`,
+            ...helmImageOverrides(image),
           ],
         },
       ],
@@ -48,8 +101,8 @@ export function planDeploy(image: string, method: 'compose' | 'helm', root: stri
         'compose',
         '-f',
         join(root, 'docker', 'docker-compose.prod.yml'),
-        role === 'migrate' ? 'run' : 'up',
-        role === 'migrate' ? '--rm' : '-d',
+        ONE_SHOT_ROLES.includes(role) ? 'run' : 'up',
+        ONE_SHOT_ROLES.includes(role) ? '--rm' : '-d',
         role,
       ],
     })),