@ultimat3/cli 7.0.0 → 8.0.0

package/src/cmd-db.ts

@@ -14,24 +14,11 @@ import { join } from 'node:path';
 import { resolveEnvironment } from '@ultimat3/core';
 import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
 import { postgresDriver } from '@ultimat3/entity';
-import { BackfillPendingError } from '@ultimat3/jobs';
-import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { runBackfillCommand } from './cmd-db-backfill';
 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';
@@ -46,14 +33,8 @@ import {
   selectSeeds,
 } from './db-seed';
 import { resolveServices } from './dev-services';
-import {
-  BadFlagError,
-  CliNotImplementedError,
-  MissingSubcommandError,
-  UnknownCommandError,
-} from './errors';
+import { 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';
@@ -82,6 +63,9 @@ export const dbCommand: CliCommand = {
     // 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',
@@ -92,31 +76,56 @@ export const dbCommand: CliCommand = {
         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: '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',
+        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: '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',
+        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'],
       },
-      { 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.
       {
@@ -141,7 +150,7 @@ export const dbCommand: CliCommand = {
     if (sub === 'reset') return runReset(ctx, root);
     if (sub === 'seed') return runSeed(ctx, root);
     if (sub === 'studio') throw plannedSubcommand('db', 'studio');
-    if (sub === 'backfill') return runBackfill(ctx, root);
+    if (sub === 'backfill') return runBackfillCommand(ctx, root);
     if (sub === 'branch') return runBranchCommand(ctx, root);
 
     // Never a fall-through. This used to end `return runBranch(ctx, root, argument ?? 'preview')`,
@@ -360,133 +369,3 @@ function seedPassResult(
     data: seedPassToJson(rows),
   };
 }
-
-/**
- * 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',
-  });
-}
-
-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),
-    };
-  });
-}
-
-/**
- * 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),
-    };
-  });
-}
-
-/**
- * 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);
-  });
-}
-
-/**
- * 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

@@ -9,6 +9,7 @@ import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 
 /**
  * Ordered, and the order is the design. `migrate` GATES — it runs to completion before anything
@@ -63,6 +64,16 @@ export interface DeployPlan {
   readonly image: string;
   /** Ordered: migrate runs to completion before any role that serves traffic starts. */
   readonly steps: readonly { readonly role: string; readonly command: readonly string[] }[];
+  /**
+   * The environment every step runs with — how the COMPOSE method carries the image, because
+   * `docker-compose.prod.yml` resolves each service from `${IMAGE:-ultimate-app:latest}` and
+   * `docker compose` takes no image argument. Without it `--image` decided nothing: the plan
+   * reported the reference the operator asked for while the six steps read `IMAGE` off the
+   * ambient environment, or deployed `ultimate-app:latest` where it was unset. Helm carries none
+   * — the chart reads `--set image.repository/tag`, and an env var it never looks at would be a
+   * second answer to which image is being deployed.
+   */
+  readonly env: Readonly<Record<string, string>>;
 }
 
 /**
@@ -100,6 +111,7 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
     }
     return {
       image,
+      env: {},
       steps: [
         {
           role: 'all',
@@ -117,6 +129,10 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
   }
   return {
     image,
+    // The one place the compose file's own variable is named. `docker/docker-compose.prod.yml`'s
+    // header documents `IMAGE=… docker compose …` as the way to run it by hand; this is that line,
+    // performed.
+    env: { IMAGE: image },
     steps: DEPLOY_ROLES.map((role) => ({
       role,
       command: [
@@ -132,6 +148,19 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
   };
 }
 
+/**
+ * One step, as the line an operator would type — the environment first, then the command.
+ *
+ * `plan.env` is the compose file's own `IMAGE=…` variable, and it is what makes `--image` true on
+ * that method: a rendered line without it deploys `docker-compose.prod.yml`'s DEFAULT image. Both
+ * renderers and the failure `fix:` go through here, so the plan `--json` reports, the plan the
+ * terminal shows and the line the refusal hands back can never name three different deployments.
+ */
+const stepLine = (env: Readonly<Record<string, string>>, command: readonly string[]): string =>
+  [...Object.entries(env).map(([name, value]) => `${name}=${quoteArg(value)}`), ...command].join(
+    ' ',
+  );
+
 export const deployCommand: CliCommand = {
   spec: {
     name: 'deploy',
@@ -165,6 +194,9 @@ export const deployCommand: CliCommand = {
     const planJson: JsonValue = {
       image: plan.image,
       method,
+      // Reported, because it is what makes `image` above true on the compose method — a dry run
+      // that names an image the steps do not carry is the defect this field closed.
+      env: { ...plan.env },
       steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
     };
     if (flagBool(ctx.args, 'dry-run')) {
@@ -173,11 +205,13 @@ export const deployCommand: CliCommand = {
         command: 'deploy',
         summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
         data: planJson,
-        lines: plan.steps.map((step) => `  ${step.role.padEnd(10)} ${step.command.join(' ')}`),
+        lines: plan.steps.map(
+          (step) => `  ${step.role.padEnd(10)} ${stepLine(plan.env, step.command)}`,
+        ),
       };
     }
     for (const step of plan.steps) {
-      const result = await ctx.runner(step.command, { cwd: root });
+      const result = await ctx.runner(step.command, { cwd: root, env: plan.env });
       if (!result.ok) {
         return {
           ok: false,
@@ -187,7 +221,7 @@ export const deployCommand: CliCommand = {
             {
               code: 'X_DEPLOY_FAILED',
               cause: `role "${step.role}" step exited ${result.code}`,
-              fix: `${step.command.join(' ')}   # run it directly to see the full output`,
+              fix: `${stepLine(plan.env, step.command)}   # run it directly to see the full output`,
               docs: 'https://ultimate.dev/errors/X_DEPLOY_FAILED',
             },
           ],

package/src/cmd-dev.ts

@@ -302,7 +302,7 @@ export const devCommand: CliCommand = {
     // `fix:` named `x dev`. Neither is discoverable from the message; both are trivial once the
     // preflight has the state directory and the port in front of it.
     const services = resolveServices(root, ctx.env);
-    const { clearedStale } = await preflight({
+    const { clearedStale, release } = await preflight({
       stateDir: services.stateDir,
       port,
       // The address the web role will actually bind, never a wider one: probing `0.0.0.0` would
@@ -310,6 +310,9 @@ export const devCommand: CliCommand = {
       hostname: DEV_BINDING.hostname,
       embeddedDb: services.db.mode === 'embedded',
     });
+    // The directory is CLAIMED from here down, so a boot that throws has to give it back — the
+    // `releaseBoot` shape, with one acquisition. Without it the first failed `x dev` in a shell
+    // refuses every later one with a pid that is no longer running.
     const server = await startDev({
       root,
       port,
@@ -319,6 +322,9 @@ export const devCommand: CliCommand = {
         if (!ctx.args.json)
           process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
       },
+    }).catch((error: unknown) => {
+      release();
+      throw error;
     });
     const result: CommandResult = {
       ok: server.findings.length === 0,

package/src/cmd-errors.ts

@@ -1,4 +1,4 @@
-import { singleLine } from '@ultimat3/core';
+import { nearestName, singleLine } from '@ultimat3/core';
 // `x errors explain <CODE>` / `x errors list` — the error table, programmatically. An agent that
 // hits an `X_*` code should not have to leave the terminal to learn what it means, and a code it
 // invented should come back refused: the answer to an unregistered code is "no such code", never
@@ -13,7 +13,6 @@ import { ErrorCodeUnknownError, MissingPositionalError } from './errors';
 import { explainErrorCode, explainEveryErrorCode } from './mcp-errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
-import { nearest } from './parse';
 
 export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
 
@@ -44,7 +43,7 @@ const detailLines = (explanation: ErrorExplanation): readonly string[] => [
 function explainOne(code: string): CommandResult {
   const explanation = explainErrorCode(code);
   if (explanation === undefined) {
-    const suggestion = nearest(
+    const suggestion = nearestName(
       code,
       explainEveryErrorCode().map((entry) => entry.code),
     );

package/src/cmd-fix.ts

@@ -3,6 +3,7 @@
 // (`docs/architecture/02-boundaries.md`) — a caller runs the printed edit, or the generated
 // `git mv`, itself.
 
+import { nearestName } from '@ultimat3/core';
 import { appImportGraph, readAppSources } from './app-boundaries';
 import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
@@ -11,7 +12,6 @@ import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, FixTargetUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-import { nearest } from './parse';
 
 export type { BoundaryCut };
 export { planBoundaryCuts };
@@ -39,7 +39,7 @@ function resolveTarget(input: string, paths: readonly string[]): string {
   // Compare on the last segment too: a wrong directory is the common miss, and edit distance
   // over the whole path would score every file in the right directory as equally far away.
   const suggestion =
-    nearest(input, [...paths]) ??
+    nearestName(input, [...paths]) ??
     paths.find((path) => path.split('/').at(-1) === input.split('/').at(-1));
   throw new FixTargetUnknownError({
     file: input,
@@ -105,7 +105,7 @@ export const fixCommand: CliCommand = {
     const root = requireAppRoot('fix', ctx.cwd).dir;
     // Refused before the scan, never defaulted to `''`: an empty string reached `resolveTarget` as
     // a file NAME, so a bare `x fix` answered X_FIX_TARGET_UNKNOWN with `"" is not one of the 42
-    // source file(s)…` — and `nearest('')` almost never suggests anything, so the fix degraded to
+    // source file(s)…` — and `nearestName('')` almost never suggests anything, so the fix degraded to
     // `x routes --json` for a caller who had simply not said which file.
     const file = ctx.args.positionals[0];
     if (file === undefined) {

package/src/cmd-i18n.ts

@@ -8,7 +8,8 @@
 // would, and `node:path` because Bun exposes no path API to build what either of them takes.
 import { type FileHandle, mkdir, open } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { catalogKeys } from '@ultimat3/i18n';
+import type { Catalog } from '@ultimat3/i18n';
+import { auditCatalogs, catalogKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -17,11 +18,17 @@ import {
   auditApp,
   loadCatalogs,
   resolveDefaultLocale,
+  scanSource,
   seedCatalog,
   serializeCatalog,
   syncCatalog,
 } from './i18n-audit';
-import { checkRegistration, missingKeyFindings } from './i18n-registration';
+import {
+  checkRegistration,
+  loudMiss,
+  missingKeyFindings,
+  withPlaceholdersMissing,
+} from './i18n-registration';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { renderTable } from './table';
@@ -102,7 +109,11 @@ function resolveOneLocale(ctx: CommandContext, sub: string): string {
 }
 
 async function runCheck(root: string): Promise<CommandResult> {
-  const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
+  const { report: audited, catalogs, extraction, ignoreUnused } = await auditApp(root);
+  // Corrected once, before anything reads it: the table's `missing` column, the summary count, the
+  // findings and `--json`'s `data` are four projections of one report, and a placeholder counted in
+  // only some of them is the command disagreeing with itself about the same app.
+  const report = withPlaceholdersMissing(audited, catalogs);
   // The runtime question, asked after the file question and never instead of it: a catalog can be
   // complete on disk, used everywhere in source, and reach no registry at all (issue #249).
   const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
@@ -182,6 +193,40 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   };
 }
 
+/**
+ * `x i18n sync <defaultLocale>` merges the default locale into itself, so `added` was empty **by
+ * construction** — exit 0, "0 key(s) added", and `x i18n check` still red over the same keys. That
+ * command is `X_CATALOG_MISSING_KEYS`'s own `fix:`, and `i18n` is a step of the gate, so the only
+ * escape left was a hand edit nothing named.
+ *
+ * The source of truth for the default locale is not another catalog — there is none above it — it
+ * is the SOURCE: every key `t()` calls that this catalog does not define, seeded with `loudMiss`,
+ * the marker `@ultimat3/i18n` already renders for an absent key. The author is then one obvious
+ * edit per key from done, with each key sitting exactly where that edit goes — and the gate stays
+ * RED until they make it, because `withPlaceholdersMissing` counts every one as still missing.
+ *
+ * The seeding and the refusal read ONE definition of the marker (`i18n-registration.ts`): two
+ * spellings would be a placeholder this command writes and the gate cannot see.
+ *
+ * The list is the `missing` one `x i18n check` prints and `X_CATALOG_MISSING_KEYS` names, read
+ * through the same two functions the check reads it through: `auditCatalogs` rather than
+ * `missingFrom`, because a `pl` catalog defining `items_many` and no bare `items` is complete and a
+ * plain key diff would seed a placeholder over it, then `withPlaceholdersMissing` so "missing"
+ * means here exactly what it means to the gate.
+ */
+async function untranslatedKeys(
+  root: string,
+  catalogs: Readonly<Record<string, Catalog>>,
+  locale: string,
+): Promise<readonly string[]> {
+  const extraction = await scanSource(root);
+  const report = withPlaceholdersMissing(auditCatalogs({ extraction, catalogs }), catalogs);
+  return report.locales.find((audit) => audit.locale === locale)?.missing ?? [];
+}
+
+const placeholderCatalog = (keys: readonly string[]): Catalog =>
+  Object.fromEntries(keys.map((key) => [key, loudMiss(key)]));
+
 async function runSync(root: string, ctx: CommandContext): Promise<CommandResult> {
   const locale = resolveOneLocale(ctx, 'sync');
   const catalogs = await loadCatalogs(root);
@@ -197,7 +242,12 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
 
   const app = await loadApp(root);
   const from = resolveDefaultLocale(app.defaultLocale, catalogs);
-  const source = from === undefined ? {} : (catalogs[from] ?? {});
+  // `from === locale` is the default locale asked to sync itself, and `undefined` is an app with
+  // no resolvable default at all — one branch, because both have no catalog to merge from.
+  const seeded = from === undefined || from === locale;
+  const source = seeded
+    ? placeholderCatalog(await untranslatedKeys(root, catalogs, locale))
+    : (catalogs[from] ?? {});
   const { merged, added } = syncCatalog(target, source);
   if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
 
@@ -208,8 +258,20 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
     ok: true,
     command: 'i18n',
     summary: msg('cli.i18n.synced', { locale, from: from ?? locale, added: added.length, total }),
+    // The keys themselves, raw — `runCheck` lists gaps the same way, because a key is a value an
+    // author copies and never prose the catalog owns.
+    lines: seeded ? added.map((key) => `  ${key}`) : [],
     findings: app.findings,
-    data: { locale, from: from ?? locale, added, total, path: catalogPath(locale) },
+    data: {
+      locale,
+      from: from ?? locale,
+      added,
+      total,
+      path: catalogPath(locale),
+      // Which of `added` still need a human. Empty on a real merge, where every value is a real
+      // string copied from the default locale — `--json` must be able to tell the two apart.
+      placeholders: seeded ? added : [],
+    },
   };
 }
 

package/src/cmd-jobs.ts

@@ -227,10 +227,33 @@ export const jobsCommand: CliCommand = {
       { name: 'state', type: 'string', summary: 'filter by job state' },
       { name: 'limit', type: 'string', summary: 'max rows to return' },
       { name: 'name', type: 'string', summary: 'filter by job name' },
-      { name: 'from-step', type: 'string', summary: 'retry: drop this step so it re-executes' },
-      { name: 'reason', type: 'string', summary: 'cancel: why, recorded on the job' },
-      { name: 'to', type: 'string', summary: 'drain target driver: memory, redis, nats' },
-      { name: 'dry-run', type: 'boolean', summary: 'drain: report the plan, move nothing' },
+      // Each of these is read by ONE subcommand — `retryJob`, `cancelJob`, `runDrain` — and says
+      // so in its own summary. The scope is what makes the parser refuse it anywhere else instead
+      // of accepting it and ignoring it: `x db gen --dry-run` parsed and wrote the migration.
+      {
+        name: 'from-step',
+        type: 'string',
+        summary: 'retry: drop this step so it re-executes',
+        subcommands: ['retry'],
+      },
+      {
+        name: 'reason',
+        type: 'string',
+        summary: 'cancel: why, recorded on the job',
+        subcommands: ['cancel'],
+      },
+      {
+        name: 'to',
+        type: 'string',
+        summary: 'drain: target driver — memory, redis, nats',
+        subcommands: ['drain'],
+      },
+      {
+        name: 'dry-run',
+        type: 'boolean',
+        summary: 'drain: report the plan, move nothing',
+        subcommands: ['drain'],
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {

package/src/cmd-mcp.ts

@@ -114,19 +114,28 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
 }
 
 /**
- * stdout is the WIRE. `dispatch.ts` renders a `CommandResult` only after `run` resolves, and this
- * resolves when the peer closes stdin — so the command's own output cannot reach stdout while a
- * session is live, and nothing here writes to it directly.
+ * What the session reports when it is over — on STDERR, which is the half this file's header
+ * claimed and did not have. `dispatch` renders a `CommandResult` only after `run` resolves, and
+ * this resolves when the peer closes stdin, so nothing lands mid-session; but fd 1 under this
+ * transport carries JSON-RPC frames, and `✓ mcp stdio serving 13 tools` arriving on it after the
+ * loop is a malformed frame to a peer still draining, and a second document under `--json`.
+ *
+ * Its own function so the addressing is testable without a live peer: `serveStdio` resolves only
+ * when stdin closes, so a test that had to reach it could not assert anything about it.
  */
+export const stdioResult = (tools: number): CommandResult => ({
+  ok: true,
+  command: 'mcp',
+  summary: msg('cli.mcp.serving', { transport: 'stdio', tools }),
+  data: { transport: 'stdio', tools },
+  stream: 'stderr',
+});
+
+/** stdout is the WIRE: `serveStdio` owns fd 1 for as long as the peer holds stdin open. */
 async function serveOverStdio(host: CliMcpServer): Promise<CommandResult> {
   await serveStdio({ server: host.server, caller: host.caller });
   await host.close();
-  return {
-    ok: true,
-    command: 'mcp',
-    summary: msg('cli.mcp.serving', { transport: 'stdio', tools: host.tools.length }),
-    data: { transport: 'stdio', tools: host.tools.length },
-  };
+  return stdioResult(host.tools.length);
 }
 
 /**