@ultimat3/cli 24.0.0 → 25.1.0

package/src/cmd-i18n.ts

@@ -185,7 +185,7 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const path = catalogPath(locale);
   const app = await loadApp(root);
   const catalogs = await loadCatalogs(root);
-  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const from = resolveDefaultLocale(app.locales.defaultLocale, catalogs);
   const seeded = seedCatalog(from === undefined ? {} : (catalogs[from] ?? {}));
   await writeNewCatalog(join(root, path), locale, serializeCatalog(seeded));
   // The second half of adding a locale, and without it this command SHIPPED A RED GATE: the file
@@ -259,13 +259,15 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   }
 
   const app = await loadApp(root);
-  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const from = resolveDefaultLocale(app.locales.defaultLocale, catalogs);
   // `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.
+  // A real merge copies the default locale's strings MARKED (`seedCatalog`, as `x i18n add` does):
+  // copied bare they rendered English to every `fr` reader under a green gate.
   const seeded = from === undefined || from === locale;
   const source = seeded
     ? placeholderCatalog(await untranslatedKeys(root, catalogs, locale))
-    : (catalogs[from] ?? {});
+    : seedCatalog(catalogs[from] ?? {});
   const { merged, added } = syncCatalog(target, source);
   if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
   // Unconditional, and not only when keys moved: a catalog that reached disk some other way — a
@@ -282,8 +284,8 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
     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}`) : [],
+    // author copies and never prose the catalog owns. Every added key is one a human still owes.
+    lines: added.map((key) => `  ${key}`),
     findings,
     data: {
       locale,
@@ -292,9 +294,10 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
       total,
       path: catalogPath(locale),
       registered,
-      // 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 : [],
+      // Which of `added` still need a human: all of them. `⟦key⟧` where there was no catalog to
+      // copy from, `⟦<default string>⟧` on a real merge — both are what `x i18n check` counts as
+      // missing until replaced, so `--json` never reports a copy as a translation.
+      placeholders: added,
     },
   };
 }

package/src/cmd-jobs-spec.ts

@@ -15,17 +15,14 @@ export const JOBS_SUBCOMMANDS = [
   'drain',
 ] as const;
 
-/**
- * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
- * Closed, and read three ways: the flag summary, the refusal, and the `memory` case below.
- */
-export const DRAIN_TARGETS = ['redis', 'nats'] as const;
-
 export const jobsSpec: CommandSpec = {
   name: 'jobs',
-  summary: 'list, show, retry, cancel, remove and promote jobs; pause and resume a queue; drain',
+  // Never ENDING in "(planned)": that suffix is how `x help` and the planned-table tests tell a
+  // planned COMMAND from a shipped one, and `x jobs` ships — only its `drain` does not.
+  summary:
+    'list, show, retry, cancel, remove and promote jobs; pause and resume a queue (drain is planned)',
   usage:
-    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain --to <driver>] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
+    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
@@ -41,8 +38,8 @@ export const jobsSpec: CommandSpec = {
       summary: 'ls: the next page — the cursor the previous page printed',
       subcommands: ['ls'],
     },
-    // 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
+    // Each of these is read by ONE subcommand — `retryJob`, `cancelJob` — 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',
@@ -56,17 +53,5 @@ export const jobsSpec: CommandSpec = {
       summary: 'cancel: why, recorded on the job',
       subcommands: ['cancel'],
     },
-    {
-      name: 'to',
-      type: 'string',
-      summary: `drain: target driver — ${DRAIN_TARGETS.join(', ')}`,
-      subcommands: ['drain'],
-    },
-    {
-      name: 'dry-run',
-      type: 'boolean',
-      summary: 'drain: report the plan, move nothing',
-      subcommands: ['drain'],
-    },
   ],
 };

package/src/cmd-jobs.ts

@@ -1,6 +1,6 @@
-// `x jobs ls|show|retry|cancel|rm|promote|pause|resume|drain` — introspect and recover the job queue, bound to
-// `@ultimat3/jobs`'s
-// own introspection so the CLI, `/_x` and MCP report identically. This file is CLI wiring only:
+// `x jobs ls|show|retry|cancel|rm|promote|pause|resume` — introspect and recover the job queue,
+// bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP report identically;
+// `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver. CLI wiring only:
 // the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
 // `jobs-table.ts`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
 
@@ -8,10 +8,6 @@ import { renderFixShellArg } from '@ultimat3/core';
 import type { JobDriver } from '@ultimat3/jobs';
 import {
   cancelJob,
-  createNatsDriver,
-  createRedisDriver,
-  DEFAULT_JOB_PAGE,
-  jobCursor,
   MAX_JOB_PAGE,
   pauseQueue,
   promoteJob,
@@ -20,18 +16,15 @@ import {
 } from '@ultimat3/jobs';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
-import { DRAIN_TARGETS, jobsSpec } from './cmd-jobs-spec';
+import { jobsSpec } from './cmd-jobs-spec';
+import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
-import type { DrainOutcome } from './jobs-drain';
-import { drainJobs } from './jobs-drain';
 import { withJobDriver } from './jobs-driver';
 import {
   backfillToJson,
   deadLetterToJson,
   depthToJson,
-  drainFailureToJson,
-  drainSkipToJson,
   jobRecordToJson,
   jobTraceToJson,
   pausedToJson,
@@ -41,30 +34,9 @@ import { listJobs, retryJob, showJob } from './jobs-report';
 import { renderJobTable } from './jobs-table';
 import { msg } from './messages';
 import type { CommandResult } from './output';
-import { flagBool, flagString } from './parse';
+import { flagString } from './parse';
 
-export { DRAIN_TARGETS, JOBS_SUBCOMMANDS } from './cmd-jobs-spec';
-
-/**
- * `memory` was on that list until 2026-09 and could not be: `createMemoryDriver()` is a `Map` in
- * THIS process, so `x jobs drain --to memory` enqueued each job into it and then `ack`ed the
- * durable row off the source. Reproduced against two real drivers — source ready 1 -> 0, target
- * ready 1, `ok: true` — and the target dies with the command. `wiki/CLI-Reference.md` said the
- * crash window "duplicates a job … instead of losing it"; this target lost every one of them.
- *
- * Refused by NAME rather than folded into the unknown-value message, for `cmd-deploy.ts`'s
- * `readMethod` reason: `--to memory` is a spelling that used to work, so a reader who types it is
- * owed the fact that it moved work into a process that is about to exit, not a list of words.
- */
-function refuseMemoryTarget(): never {
-  throw new BadFlagError({
-    flag: 'to',
-    command: 'jobs',
-    reason:
-      'memory is a Map inside this process — the drain would ack every durable row and lose the copy when the command exits',
-    fix: 'x jobs drain --to redis --json   # or --to nats; --dry-run reports the plan and moves nothing',
-  });
-}
+export { JOBS_SUBCOMMANDS } from './cmd-jobs-spec';
 
 /**
  * A uuid in any spelling Postgres' `uuid` input accepts: canonical, upper-case, unhyphenated,
@@ -114,42 +86,10 @@ function refuseOversizedPage(limit: string | undefined): void {
     command: 'jobs',
     reason: `one page holds at most ${MAX_JOB_PAGE} jobs`,
     // The bound is the queue's own constant, screened like any value spliced into a command.
-    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.next as --after for the page that follows`,
+    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
   });
 }
 
-function requireEnvUrl(env: CommandContext['env'], name: string, target: string): string {
-  const value = env[name];
-  if (value === undefined || value.trim().length === 0) {
-    throw new BadFlagError({
-      flag: 'to',
-      command: 'jobs',
-      reason: `--to ${target} needs ${name} set in the environment`,
-    });
-  }
-  return value;
-}
-
-/**
- * `redis`/`nats` are honest `X_NOT_IMPLEMENTED` stubs in `@ultimat3/jobs` — building one here is
- * fine even though every `enqueue` on it will fail; `drainJobs` reports that per record. What is
- * NOT fine is a target that accepts every enqueue and then vanishes, which is why `memory` is
- * refused first and by name rather than falling into the closed-set message below.
- * Exported so a test can drive the `--to`/env-var validation without a driver or a boot.
- */
-export function buildDrainTarget(to: string | undefined, env: CommandContext['env']): JobDriver {
-  if (to === 'memory') refuseMemoryTarget();
-  if (to === undefined || !(DRAIN_TARGETS as readonly string[]).includes(to)) {
-    throw new BadFlagError({
-      flag: 'to',
-      command: 'jobs',
-      reason: `expects one of: ${DRAIN_TARGETS.join(', ')}`,
-    });
-  }
-  if (to === 'redis') return createRedisDriver({ url: requireEnvUrl(env, 'REDIS_URL', 'redis') });
-  return createNatsDriver({ servers: [requireEnvUrl(env, 'NATS_URL', 'nats')] });
-}
-
 async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
   const limit = flagString(ctx.args, 'limit');
   refuseOversizedPage(limit);
@@ -160,11 +100,9 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
     limit,
     after: flagString(ctx.args, 'after'),
   });
-  // A FULL page may have another behind it: `next` is the cursor that asks for it, and `null`
-  // says this was the last one — so a walk never has to guess from a row count.
-  const size = limit === undefined ? DEFAULT_JOB_PAGE : Number(limit);
-  const last = result.rows[result.rows.length - 1];
-  const next = last === undefined || result.rows.length < size ? null : jobCursor(last);
+  // `nextCursor` exists exactly when a row past this page does (`listJobs` asks the queue), so a
+  // full last page prints no "next page" a caller would follow to an empty one.
+  const next = result.nextCursor;
   const [paused, workers] = await Promise.all([
     driver.introspect?.pausedQueues() ?? [],
     driver.introspect?.workers() ?? [],
@@ -215,7 +153,8 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
       rows: result.rows.map(jobRecordToJson),
       deadLetters: result.deadLetters.map(deadLetterToJson),
       backfills: result.backfills.map(backfillToJson),
-      next,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
       pausedQueues: paused.map(pausedToJson),
       workers: workers.map(workerToJson),
     },
@@ -310,59 +249,6 @@ async function runPause(
   };
 }
 
-/**
- * A skipped candidate is not an error — a job whose `runAt` has not arrived is unclaimable by
- * design — so it carries no `X_*` finding. It still fails the command: `x jobs drain` is run to
- * empty a driver, and a partial move that exited 0 would read as "the queue is clear".
- *
- * Exported, and separate from the flag reading above it, because every target the flag now accepts
- * needs a server: a test can produce a real outcome from two drivers and render THAT, where
- * driving the whole command would need a redis or a nats to move anything at all.
- */
-export function drainResult(outcome: DrainOutcome): CommandResult {
-  const dryRun = outcome.dryRun;
-  const findings = outcome.failures.map((failure) => failure.finding);
-  const lines: string[] = [];
-  if (outcome.skipped.length > 0) {
-    const count = outcome.skipped.length;
-    lines.push(`  ${msg('cli.jobs.skipped', { count, from: outcome.from })}`);
-    for (const skip of outcome.skipped) {
-      lines.push(`    ${skip.id}  ${skip.name}  (${skip.queue})  ${skip.state}  ${skip.reason}`);
-    }
-  }
-  const partial = outcome.skipped.length > 0;
-  return {
-    ok: findings.length === 0 && !partial,
-    command: 'jobs',
-    summary: msg(partial ? 'cli.jobs.drainedPartial' : 'cli.jobs.drained', {
-      count: dryRun ? outcome.candidates.length : outcome.moved.length,
-      from: outcome.from,
-      to: outcome.to,
-      skipped: outcome.skipped.length,
-    }),
-    lines,
-    findings,
-    data: {
-      from: outcome.from,
-      to: outcome.to,
-      dryRun: outcome.dryRun,
-      candidates: outcome.candidates.map(jobRecordToJson),
-      moved: outcome.moved.map(jobRecordToJson),
-      skipped: outcome.skipped.map(drainSkipToJson),
-      failures: outcome.failures.map(drainFailureToJson),
-    },
-  };
-}
-
-/** The move, then the render. The target is built ABOVE `withJobDriver` — see `run` below. */
-async function runDrain(
-  driver: JobDriver,
-  target: JobDriver,
-  ctx: CommandContext,
-): Promise<CommandResult> {
-  return drainResult(await drainJobs(driver, target, flagBool(ctx.args, 'dry-run')));
-}
-
 /** The subcommands that answer a `JobTrace`. `ls`, `rm`, `promote` and the rest read rows only. */
 const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
 
@@ -371,13 +257,11 @@ export const jobsCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'ls';
-    // BEFORE `withJobDriver`, which boots the SOURCE queue and pings it. `--to` is a flag, so
-    // whether it names a durable driver is answerable with no server at all — and reading it
-    // inside meant `x jobs drain --to memory` on a box whose database is down reported the boot
-    // failure instead of `X_CLI_BAD_FLAG`, i.e. the operator repaired Postgres to be told the
-    // word they typed was refused by name. It also opens a connection to a target the command
-    // then refuses, which is a socket nothing closes.
-    const target = sub === 'drain' ? buildDrainTarget(flagString(ctx.args, 'to'), ctx.env) : null;
+    // BEFORE `withJobDriver`, which boots the source queue: the answer needs no server, so a box
+    // whose database is down gets it rather than the boot failure of a queue never to be used —
+    // and nothing is leased. 24.x's `--to`/`--dry-run` are deleted, so the parser refuses them
+    // (`X_CLI_BAD_FLAG`); only a bare `x jobs drain` reaches this answer.
+    if (sub === 'drain') throw plannedSubcommand('jobs', 'drain');
     // A TRACE is the queue row projected through the job's own declaration — its concurrency key,
     // its retry schedule — and a declaration exists in this process only once the app is loaded.
     // Unloaded, `show` answered `concurrencyKey: null` and `retryDelaysMs: []` for every job of
@@ -391,13 +275,10 @@ export const jobsCommand: CliCommand = {
       if (sub === 'rm') return runRm(driver, ctx);
       if (sub === 'promote') return runPromote(driver, ctx);
       if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
-      if (target !== null) return runDrain(driver, target, ctx);
       return runLs(driver, ctx);
     });
   },
 };
 
-export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
-export { drainJobs } from './jobs-drain';
 export type { JobsListFilter, JobsListResult } from './jobs-report';
 export { listJobs, retryJob, showJob } from './jobs-report';

package/src/cmd-mcp.ts

@@ -10,7 +10,7 @@ import {
   timingSafeEqual,
   UltimateError,
 } from '@ultimat3/core';
-import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
+import { mcpHttpRoute, type StdioTransportInput, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -37,8 +37,12 @@ const isTransport = (value: string): value is Transport =>
 
 /** The catalog, from the server's own registry — never a list kept here. */
 async function catalog(host: CliMcpServer): Promise<CommandResult> {
-  const tools = host.server.list(host.caller);
-  await host.close();
+  let tools: ReturnType<CliMcpServer['server']['list']>;
+  try {
+    tools = host.server.list(host.caller);
+  } finally {
+    await host.close();
+  }
   return {
     ok: true,
     command: 'mcp',
@@ -162,10 +166,24 @@ export const stdioResult = (tools: number): CommandResult => ({
   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();
+/** The pipe a session reads, when it is not this process's own stdin — a test's script. */
+export type StdioPipe = Pick<StdioTransportInput, 'input' | 'write'>;
+
+/**
+ * stdout is the WIRE: `serveStdio` owns fd 1 for as long as the peer holds stdin open. Exported
+ * with `pipe` so a test can end the session with a throw instead of a closed stdin.
+ */
+export async function serveOverStdio(
+  host: CliMcpServer,
+  pipe: StdioPipe = {},
+): Promise<CommandResult> {
+  // `finally`, as `startMcpHttp`'s refused bind does: a session that throws must not leave the
+  // host's PGlite data directory held by a process about to report the failure.
+  try {
+    await serveStdio({ server: host.server, caller: host.caller, ...pipe });
+  } finally {
+    await host.close();
+  }
   return stdioResult(host.tools.length);
 }
 

package/src/cmd-new.ts

@@ -3,9 +3,9 @@
 // Interactive-free: every choice is a flag with a default, because an agent cannot answer prompts.
 
 import { existsSync } from 'node:fs';
-import { chmod } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { AppNameInvalidError, appNameIssue } from './app-name';
 import { dedupe } from './cmd-generate';
 import { newSpec } from './cmd-new-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -18,7 +18,7 @@ import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
-import { appFiles, EXECUTABLE_FILES, names, repoFiles, resourceFiles } from './templates';
+import { appFiles, names, repoFiles, resourceFiles } from './templates';
 import { loadVersion } from './version-loader';
 
 export interface NewAppOptions {
@@ -102,6 +102,15 @@ export async function initRepository(runner: Runner, dir: string): Promise<Repos
   return { initialized: true, committed: true, problem: null };
 }
 
+/** `path` relative to `cwd` when it lies under it, else absolute — never a `../../` walk. */
+const displayPath = (cwd: string, path: string): string => {
+  const rel = relative(cwd, path);
+  return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? path : rel;
+};
+
+/** The `cd` operand of the next-steps line: the target as typed from `cwd`, pasteable verbatim. */
+const cdTarget = (cwd: string, target: string): string => quoteArg(displayPath(cwd, target));
+
 /** Pure: the complete file list for a new app, so `--dry-run` and the test see the same thing. */
 export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   const app = names(options.name);
@@ -145,13 +154,12 @@ export interface WrittenApp {
  * a migration whose snapshot never existed is what made the app's first two database commands
  * refuse each other — `x db migrate` naming `x db gen`, and `x db gen` refusing a sidecar version
  * control never had. The consequence is deliberate: `x verify`'s `drift` step is red on a pristine
- * scaffold until `x db gen "initial"` runs — which `bin/setup` does, and which is what
+ * scaffold until `x db gen "initial"` runs — which `bun run setup` does, and which is what
  * `cli.new.done` tells the author to run.
  */
 export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
   const files = planNewApp(options);
   for (const file of files) await Bun.write(join(target, file.path), file.contents);
-  for (const path of EXECUTABLE_FILES) await chmod(join(target, path), 0o755);
   return { dir: target, files: files.map((file) => file.path) };
 }
 
@@ -210,6 +218,18 @@ export const newCommand: CliCommand = {
         flags: callerFlags(ctx),
       });
     }
+    // After the slug exists and before anything is planned: the slug is `app.config.ts`'s `name`,
+    // and a name core's `defineConfig` refuses is an app that throws at its own first import.
+    const issue = appNameIssue(app.kebab);
+    if (issue !== undefined) {
+      throw new AppNameInvalidError({
+        name: raw,
+        slug: app.kebab,
+        issue,
+        invocation: invocationOf(ctx, 'new'),
+        flags: callerFlags(ctx),
+      });
+    }
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
 
@@ -218,9 +238,17 @@ export const newCommand: CliCommand = {
       return {
         ok: true,
         command: 'new',
-        summary: msg('cli.new.done', { name: app.kebab }),
+        summary: msg('cli.new.dryRun', {
+          name: app.kebab,
+          dir: target,
+          cd: cdTarget(ctx.cwd, target),
+        }),
         data: { dir: target, files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => msg('cli.file.added', { path: `${app.kebab}/${file.path}` })),
+        // Where each file WOULD land, as the caller would reach it: relative to the cwd, `--dir`
+        // included — `${app.kebab}/…` named the wrong place whenever `--dir` was set.
+        lines: files.map((file) =>
+          msg('cli.file.added', { path: displayPath(ctx.cwd, join(target, file.path)) }),
+        ),
       };
     }
     if (existsSync(target) && !flagBool(ctx.args, 'force')) {
@@ -263,7 +291,7 @@ export const newCommand: CliCommand = {
     return {
       ok: true,
       command: 'new',
-      summary: msg('cli.new.done', { name: app.kebab }),
+      summary: msg('cli.new.done', { name: app.kebab, cd: cdTarget(ctx.cwd, target) }),
       data: { dir: written.dir, files: written.files, git },
       lines,
     };

package/src/cmd-planned.ts

@@ -127,6 +127,15 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
     subcommand: 'studio',
     fix: 'x dev   # then the db panel at /_x: schema, rows, and a guarded SQL console',
   },
+  // Planned because Postgres is the one durable job driver: there is nowhere to drain to. The two
+  // `--to` values, `redis` and `nats`, were `X_NOT_IMPLEMENTED` stubs on every method, so a drain
+  // leased the production batch for five minutes, failed each enqueue and nacked it back. 25.0.0
+  // deleted both stubs and the unreachable drain body; a real second driver writes a new one.
+  {
+    command: 'jobs',
+    subcommand: 'drain',
+    fix: 'x jobs ls --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
+  },
 ];
 
 /**

package/src/cmd-routes.ts

@@ -1,11 +1,11 @@
 // `x routes` — the route table as a table, or as JSON. Replaces grepping a router directory, which
 // is what an agent does when the framework has no answer to "what URLs exist".
 //
-// The rows are `@ultimat3/render`'s own `describeRoutes()`: the CLI prints the route table, it
+// The rows are `@ultimat3/render`'s own `describePages()`: the CLI prints the route table, it
 // does not keep a second one.
 
 import type { RouteDescriptor, Surface } from '@ultimat3/render';
-import { describeRoutes, SURFACES } from '@ultimat3/render';
+import { describePages, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { routesSpec } from './cmd-routes-spec';
@@ -97,7 +97,7 @@ export const routesCommand: CliCommand = {
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));
     const { findings } = await loadApp(root);
-    const routes = describeRoutes().filter(
+    const routes = describePages().filter(
       (route) => surface === undefined || route.surface === surface,
     );
     return {

package/src/cmd-shot-matrix.ts

@@ -9,11 +9,13 @@ import { escapeHtml } from '@ultimat3/core';
 import { routeEntries } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import type { ShotRun } from './cmd-shot';
+import { BadFlagError } from './errors';
 import type { CommandResult } from './output';
 import { localizedShotPath } from './shot-locale';
 import type { ShotServer } from './shot-server';
 import { SHOT_DIR } from './shot-server';
 import type { ShotArtifacts } from './shot-verdict';
+import { viewportDir } from './shot-viewport';
 
 export const MATRIX_DIR = join(SHOT_DIR, 'matrix');
 export const MATRIX_INDEX = 'index.html';
@@ -21,7 +23,10 @@ export const MATRIX_INDEX = 'index.html';
 /** The two themes the boot honours from storage. */
 export const MATRIX_THEMES: readonly ('light' | 'dark')[] = ['light', 'dark'];
 
-/** A phone and a desktop, each with the height its class of device is photographed at. */
+/**
+ * A phone and a desktop, each with the height its class of device is photographed at. The default
+ * only: `x shot --matrix --viewport <w>x<h>[,…]` replaces the pair (`shot-viewport.ts`).
+ */
 export const MATRIX_VIEWPORTS: readonly { readonly width: number; readonly height: number }[] = [
   { width: 390, height: 844 },
   { width: 1440, height: 900 },
@@ -35,10 +40,20 @@ export interface MatrixCell {
   readonly viewport: { readonly width: number; readonly height: number };
   /** What the browser opens: the route, prefixed for a non-default locale. */
   readonly path: string;
-  /** Relative to the matrix directory: `<route-slug>/<locale>/<theme>-<width>`. */
+  /** Relative to the matrix directory: `<route-slug>/<locale>/<theme>-<width>x<height>`. */
   readonly dir: string;
 }
 
+/** The matrix photographs ROUTES; `--island`/`--all-islands` beside it is two subjects. */
+export function refuseMatrixWithComponent(): never {
+  throw new BadFlagError({
+    flag: 'matrix',
+    command: 'shot',
+    reason: 'photographs every site route; --island and --all-islands photograph components',
+    fix: 'x shot --matrix --json',
+  });
+}
+
 /** A route a matrix can photograph without inventing a parameter: no `:param`, no `*rest`. */
 export const isMatrixRoute = (path: string): boolean => !/[:*[]/.test(path);
 
@@ -79,7 +94,8 @@ export function planShotMatrix(input: MatrixPlanInput): readonly MatrixCell[] {
             theme,
             viewport,
             path: localizedShotPath(route, locale, input.defaultLocale),
-            dir: join(slug(route), locale, `${theme}-${String(viewport.width)}`),
+            // The whole size, never the width alone: `--viewport 390x844,390x664` is two pictures.
+            dir: join(slug(route), locale, `${theme}-${viewportDir(viewport)}`),
           });
         }
       }
@@ -106,7 +122,7 @@ export function contactSheet(shots: readonly MatrixShot[]): string {
       .filter((shot) => shot.cell.route === route)
       .map((shot) => {
         const { locale, theme, viewport, path } = shot.cell;
-        const label = `${locale} · ${theme} · ${String(viewport.width)}px${shot.ok ? '' : ' · FAILED'}`;
+        const label = `${locale} · ${theme} · ${viewportDir(viewport)}${shot.ok ? '' : ' · FAILED'}`;
         return (
           `<figure${shot.ok ? '' : ' class="failed"'}><a href="${escapeHtml(shot.image)}">` +
           `<img src="${escapeHtml(shot.image)}" alt="${escapeHtml(`${path} ${label}`)}" loading="lazy" ` +
@@ -191,6 +207,7 @@ export async function runShotMatrix(run: MatrixRun): Promise<CommandResult> {
         locale: shot.cell.locale,
         theme: shot.cell.theme,
         width: shot.cell.viewport.width,
+        height: shot.cell.viewport.height,
         image: shot.image,
         ok: shot.ok,
       })),

package/src/cmd-shot-spec.ts

@@ -7,7 +7,7 @@ export const shotSpec: CommandSpec = {
   name: 'shot',
   summary: 'photograph one route, one island in a state it declares, or every island in the app',
   usage:
-    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--cookie <name=value>] [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    'x shot <route> [--locale <l>] [--theme light|dark] [--viewport 390x844,1440x900] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--cookie <name=value>] [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
   requiresApp: true,
   flags: [
     { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -51,7 +51,15 @@ export const shotSpec: CommandSpec = {
       name: 'matrix',
       type: 'boolean',
       summary:
-        'every site route × locale × light/dark × 390/1440 px into .x/shot/matrix/, plus an index.html contact sheet',
+        'every site route × locale × light/dark × 390x844/1440x900 (or --viewport) into .x/shot/matrix/, plus an index.html contact sheet',
+    },
+    // One flag, read as a list, rather than a repeatable one: the parser keeps the last value of a
+    // repeated flag, so `--viewport a --viewport b` would photograph `b` alone and say nothing.
+    {
+      name: 'viewport',
+      type: 'string',
+      summary:
+        '<w>x<h>[,<w>x<h>] — a route once per size into <out>/<w>x<h>/; with --matrix, its sizes',
     },
     // A FLAG on `x shot` and never a second command: photographing a route and photographing a
     // component are one job with two subjects, and a parallel command would be the second path