@ultimat3/cli 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -7,12 +7,13 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
+| Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
-| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
+| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error`. A class may sit beside its one thrower when `errors.ts` has no room under the 500-line ceiling — `db-seed.ts` and `metrics-endpoint.ts` do |
 | Subprocesses | only through `exec.ts`, so a test can inject a fake `Runner` |
 | Templates | `templates/*.ts` return strings; no fixture files on disk |
 | Strings | rendered output through `messages.ts`, missing key renders `⟦key⟧` — see below for what is *not* rendered output |
@@ -285,6 +286,7 @@ regex and `+` is a quantifier — `n1` is what actually selects these tests.
 | `drift.ts` | `checkSourceDrift`: the `.hash` sidecar `x verify`'s `drift` step compares, no database needed |
 | `db-destructive.ts` | `checkDestructiveMigrations`: the same step's second half — every committed `up` that drops, truncates or retypes must carry `-- destructive: true` |
 | `db-backfill.ts` | `x db backfill --list`: the flag parsing, the ledger read and the table |
+| `db-seed.ts` | `x db seed`, everything except the argv: `SEED_GLOBS` (where a seed is declared), `discoverSeeds`, `parseSeedTierFlag`, `selectSeeds` (which seeds this invocation runs, and its two refusals — `X_DECLARATION_UNKNOWN` and `X_SEED_ENVIRONMENT`), `runSeeds` (one transaction **per seed**, never one around the run) and the two renderers. The `db-backfill.ts` split repeated: a driver plus plain strings in, plain rows out, so every rule is testable with no `ParsedArgs` and no boot. Which tiers an environment takes is `@ultimat3/entity`'s `seedTiersFor` — two copies of "may this seed run" would be two answers |
 
 `jobs-driver.ts` is the ONE place a CLI command gets hold of the app's queue — `withJobDriver`,
 which `x jobs` and `x db backfill` both call. It reuses an ambient `jobDriver()` when a process
@@ -399,6 +401,29 @@ with nothing running, and against a database three migrations behind. An app who
 load generates **nothing**: a short registry is indistinguishable from deleted entities, and the
 diff would be a DROP nobody asked for.
 
+**An empty diff re-records the `.hash` sidecar, and that is what makes `X_DB_DRIFT` followable.**
+The hash `checkSourceDrift` compares covers every non-test file under `packages/db/src` — a seed, a
+helper, a decorator — not only the ones that imply DDL, and narrowing that glob would trade a loud
+error for a silent gap in the one check that catches "entities changed and no migration was
+generated". So detection stays broad and the REMEDY carries the weight: `x db gen "describe the
+change"` — the exact `fix:` the error hands out — records the current hash against the newest
+migration when the diff is empty, instead of writing nothing and leaving the gate red forever with
+hand-editing a generated file as the only way out. `GeneratedFiles.outcome` is the four things a run
+can be — `generated`, `hash-recorded`, `unchanged`, `blocked` — and `runGen` projects it onto
+`--json` on **every** branch: reporting `hash-recorded` as `generated` would name a migration nobody
+can apply, and reporting it as `unchanged` would hide a file this command wrote. That second one
+shipped: the no-migration branch hardcoded `data: { migration: null, files: [] }`, so the run that
+wrote the sidecar reported writing nothing to the machine reading the output.
+
+Nothing is masked, and the branch proves it rather than promising it: `loadApp` reported no findings
+(the registry is whole, never short), `declaredSchema` returned a real snapshot (`X_MIGRATION_SNAPSHOT_MISSING`
+otherwise), and the emptiness is `generateMigration`'s own verdict — the same call the written path
+takes. A migration with no migration id to record against writes nothing, which is the
+`x new --no-example` case: an entity against zero migrations is `create table` for all of it and
+never an empty diff. `reconcileSchemaHash` also declines to write when an OLDER migration already
+recorded the hash, because `checkSourceDrift` already answers clean there and restamping the newest
+sidecar would claim it produced a schema it did not — one predicate, `isRecorded`, read by both.
+
 One migration is one file, split by a lone `-- down` line. `<id>.down.sql` is a pre-1.2.0
 hand-written layout and `readMigrations` skips it — read as a migration it sorts next to its own
 `up` and drops every table the pair exists to reverse.
@@ -488,8 +513,10 @@ session-scoped and the grant dies when the connection returns to the pool, so ev
 itself as leader and a rolling update double-fires every task.
 
 The relay runs on `worker` and only `worker` — the role that exists wherever jobs run at all.
-Duplicating it is safe (publish-then-mark is at-least-once and the idempotency key collapses the
-repeat) but pointless.
+Duplicating it is safe — the claim is a **lease** taken in the statement that locks the row
+(`@ultimat3/jobs`' `outbox-pg.ts`, fenced on `claimed_by`), so two relays never hold one batch —
+but pointless. The idempotency key is not the reason and never was: its conflict target is a
+partial index over live states, so it collapses a repeat only while the first job is still live.
 
 `SQL_IDEMPOTENCY_TABLE` is applied beside `SQL_JOBS_TABLE`, and the store is installed by the boot
 rather than by the app, even though `@ultimat3/action` documents
@@ -581,6 +608,16 @@ route: a tenant-scoped key takes `AUTHORIZED_OBJECT_CACHE` (`private, max-age=0`
 `authorization`/`cookie`), and only a key no tenant owns keeps `immutable`. A genuinely public image
 belongs under `apps/web/site/`, which is a static asset and never touches that disk.
 
+**A variant is CACHED only at a width the framework can mint.** The cache key is built entirely
+from caller-supplied query values, so `?w=1`, `?w=2`, … each wrote a new object to the app's only
+disk, on a route every signed-in tenant may reach for their own keys. `@ultimat3/seo`'s
+`MAX_IMAGE_WIDTH` (8192) bounds that and does not close it. `isMintableWidth` is the bound:
+`DEFAULT_WIDTHS` **plus the source's own intrinsic width**, which is exactly the set `usableWidths`
+puts in a `srcset` — the constant alone would refuse the widest entry of any image whose intrinsic
+width is not one of the eight. Anything outside it is still served; only the `put` is refused, so
+no caller gains a new 4xx. `?q=` is deliberately still unbounded here — the closed set for quality
+is `@ultimat3/seo`'s to declare, not this file's.
+
 `ICON_SOURCE` lives here, not in `cmd-doctor.ts`, because this is the module that reads it: the
 diagnostic checks what `x dev` serves, so one constant cannot pass the check and serve nothing.
 It is a **PNG** — core decodes PNG and JPEG only, and the SVG this used to name could never

package/README.md

@@ -82,6 +82,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `dispatch.ts` | parse → run → render → exit; the only I/O boundary |
 | `parse.ts` | flags, subcommands, `--json`, `--help`, suggestions |
 | `flag-number.ts` | the one integer-flag reader — `--port`, `--workers`, `--shard` |
+| `shell-quote.ts` | the one POSIX quoter for a value pasted into a `fix:` or a reproduce line |
 | `output.ts` | one data shape, two renderers, the 3-line error format |
 | `registry.ts` | the one command list |
 | `generate-kinds.ts` | which generators exist, and how a command line names one |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -35,28 +35,28 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/admin": "2.0.0",
-    "@ultimat3/ai": "2.0.0",
-    "@ultimat3/cache": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/entity": "2.0.0",
-    "@ultimat3/http": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/mail": "2.0.0",
-    "@ultimat3/manifest": "2.0.0",
-    "@ultimat3/mcp": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/pwa": "2.0.0",
-    "@ultimat3/query": "2.0.0",
-    "@ultimat3/realtime": "2.0.0",
-    "@ultimat3/render": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/seo": "2.0.0",
-    "@ultimat3/storage": "2.0.0",
-    "@ultimat3/testing": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/action": "3.0.0",
+    "@ultimat3/admin": "3.0.0",
+    "@ultimat3/ai": "3.0.0",
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/entity": "3.0.0",
+    "@ultimat3/http": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/mail": "3.0.0",
+    "@ultimat3/manifest": "3.0.0",
+    "@ultimat3/mcp": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/pwa": "3.0.0",
+    "@ultimat3/query": "3.0.0",
+    "@ultimat3/realtime": "3.0.0",
+    "@ultimat3/render": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/seo": "3.0.0",
+    "@ultimat3/storage": "3.0.0",
+    "@ultimat3/testing": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/budgets.ts

@@ -123,6 +123,23 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
 
 const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
 const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
+const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
+
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
+ * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
+ * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
+ * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
+ * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
+ */
+const carriesJson = (attrs: string): boolean => {
+  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
+  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
+  // test alone charged an SEO structured-data block as executable JavaScript all over again.
+  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
+  return type.trim().toLowerCase().endsWith('json');
+};
+
 /**
  * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
  * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
@@ -144,8 +161,9 @@ export interface MeasuredJs {
 }
 
 /**
- * What a rendered document actually makes the browser execute: the bytes of every inline script,
- * the size of every file a `src` points at, and the size of every island chunk it boots. Measured
+ * What a rendered document actually makes the browser execute: the bytes of every inline script
+ * the parser will run, the size of every file a `src` points at, and the size of every island
+ * chunk it boots. A JSON-typed script is skipped — it is data the parser never runs. Measured
  * from the emitted HTML rather than from the declared graph, because the graph is what a route
  * *says* it ships and this gate exists to catch the case where those two disagree.
  */
@@ -162,7 +180,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   };
 
   for (const match of html.matchAll(SCRIPT_TAG)) {
-    const src = SRC_ATTR.exec(match.groups?.['attrs'] ?? '')?.groups?.['src'];
+    const attrs = match.groups?.['attrs'] ?? '';
+    if (carriesJson(attrs)) continue;
+    const src = SRC_ATTR.exec(attrs)?.groups?.['src'];
     if (src === undefined) {
       jsBytes += Buffer.byteLength(match.groups?.['body'] ?? '', 'utf8');
       continue;

package/src/cmd-db-branch.ts

@@ -11,6 +11,7 @@ import {
   branchDatabaseName,
   createExternalBranch,
   createPgliteBranch,
+  databaseNameOf,
   dropExternalBranch,
   dropPgliteBranch,
   isBranchName,
@@ -27,6 +28,7 @@ import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagString, nearest } from './parse';
+import { portFromEnv } from './serve';
 import { renderTable } from './table';
 
 /**
@@ -145,7 +147,9 @@ async function runCreate(
   services: DevServices,
   name: string,
 ): Promise<CommandResult> {
-  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
+  // `portFromEnv`, never a bare `Number.parseInt`: the latter reads `PORT=abc` as `NaN` and put
+  // `http://feat.localhost:NaN` in `data.preview` — a machine-readable field naming no port.
+  const port = portFromEnv(ctx.env);
   let branch: BranchRow;
   try {
     branch =
@@ -205,7 +209,7 @@ function notABranch(services: DevServices, name: string): CommandResult {
   const target =
     services.db.mode === 'embedded'
       ? pgliteBranchLocation(services.db.url, name)
-      : branchDatabaseName(services.db.url.split('/').at(-1) ?? 'postgres', name);
+      : branchDatabaseName(databaseNameOf(services.db.url), name);
   return failure(msg('cli.db.branch.failed'), {
     code: 'X_DB_BRANCH_FAILED',
     cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,

package/src/cmd-db.ts

@@ -1,4 +1,4 @@
-// `x db gen|migrate|reset|studio|branch|backfill` — everything that touches the database. One
+// `x db gen|migrate|reset|seed|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`.
 //
@@ -12,7 +12,8 @@
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveEnvironment } from '@ultimat3/core';
-import { type DriftReport, driftError } from '@ultimat3/db';
+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';
@@ -34,6 +35,16 @@ import {
 import { BRANCH_SUBCOMMANDS } from './db-branch';
 import { stepFinding } from './db-finding';
 import { generateAppMigration } from './db-generate';
+import type { SeedPassRow } from './db-seed';
+import {
+  discoverSeeds,
+  parseSeedTierFlag,
+  renderSeedTable,
+  runSeeds,
+  seedPassToJson,
+  seedTotals,
+  selectSeeds,
+} from './db-seed';
 import { resolveServices } from './dev-services';
 import {
   BadFlagError,
@@ -49,14 +60,22 @@ import { findingFrom } from './output';
 import { flagBool, flagString } from './parse';
 import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch', 'backfill'] as const;
+export const DB_SUBCOMMANDS = [
+  'gen',
+  'migrate',
+  'reset',
+  'seed',
+  'studio',
+  'branch',
+  'backfill',
+] as const;
 
 export const dbCommand: CliCommand = {
   spec: {
     name: 'db',
-    summary: 'gen, migrate, reset, studio, branch, backfill',
+    summary: 'gen, migrate, reset, seed, 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]',
+      '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
@@ -64,7 +83,21 @@ export const dbCommand: CliCommand = {
     // 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: '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',
+      },
+      {
+        name: 'dry-run',
+        type: 'boolean',
+        summary: 'seed: report what each seed would write, and write nothing',
+      },
       { name: 'list', type: 'boolean', summary: 'backfill: print the x_backfills ledger' },
       {
         name: 'pending',
@@ -106,6 +139,7 @@ export const dbCommand: CliCommand = {
     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 === 'seed') return runSeed(ctx, root);
     if (sub === 'studio') throw plannedSubcommand('db', 'studio');
     if (sub === 'backfill') return runBackfill(ctx, root);
     if (sub === 'branch') return runBranchCommand(ctx, root);
@@ -125,8 +159,14 @@ export const dbCommand: CliCommand = {
 
 /**
  * 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.
+ * with nothing running. A diff that finds nothing writes no MIGRATION and still exits 0: "no
+ * change" is an answer, and an empty migration would take a ledger row and a checksum forever. It
+ * may still write the `.hash` sidecar `x verify`'s `drift` step reads, which is what makes
+ * `X_DB_DRIFT`'s `fix:` — this command — a real instruction rather than a no-op.
+ *
+ * So there are THREE answers, not two, and `--json` carries `outcome` on every one: collapsing
+ * `hash-recorded` into either neighbour tells the machine reading this output that a migration
+ * exists when none does, or that nothing was written when the sidecar was.
  */
 async function runGen(ctx: CommandContext, root: string, name: string): Promise<CommandResult> {
   let generated: Awaited<ReturnType<typeof generateAppMigration>>;
@@ -148,9 +188,21 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
     return {
       ok: generated.findings.length === 0,
       command: 'db',
-      summary: msg('cli.db.gen.unchanged'),
+      // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
+      // the `drift` step reads back.
+      summary:
+        generated.outcome === 'hash-recorded'
+          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+          : msg('cli.db.gen.unchanged'),
       findings: generated.findings,
-      data: { migration: null, files: [] },
+      // `files` is what this command WROTE, so the empty array here was a false claim.
+      lines: generated.files.map((file) => `  ${file}`),
+      data: {
+        outcome: generated.outcome,
+        migration: null,
+        files: [...generated.files],
+        schemaHash: generated.schemaHash ?? null,
+      },
     };
   }
   return {
@@ -159,6 +211,7 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
     summary: msg('cli.db.gen.written', { id: migration.id }),
     lines: generated.files.map((file) => `  ${file}`),
     data: {
+      outcome: generated.outcome,
       migration: migration.id,
       name: migration.name,
       files: [...generated.files],
@@ -233,6 +286,81 @@ async function runReset(ctx: CommandContext, root: string): Promise<CommandResul
   return runMigrate(ctx, root, msg('cli.db.reset.done'));
 }
 
+/**
+ * `x db seed [<name>]` — the fixture graph, applied and replayable.
+ *
+ * The environment is resolved BEFORE anything is imported or connected: a run this environment does
+ * not take must refuse without having opened a connection to the database it was refusing to write
+ * to. `selectSeeds` asks the same question a second time, on the seeds themselves, because seeding
+ * is the one irreversible thing this command does (`db-seed.ts`).
+ *
+ * `withJobDriver` is the boot, though nothing here claims a job: it is the CLI's one answer to
+ * "which database is this command talking to", and it also puts a real queue behind any
+ * `handle.enqueue()` a seeded write triggers. A second boot path would be a second answer.
+ */
+async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const environment = resolveEnvironment({ env: ctx.env });
+  const requested = parseSeedTierFlag(
+    flagString(ctx.args, 'tier') ?? ctx.env['ULTIMATE_SEED_TIER'],
+  );
+  const name = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const discovery = await discoverSeeds(root);
+  const chosen = selectSeeds({
+    discovered: discovery.seeds,
+    ...(name === undefined ? {} : { name }),
+    environment,
+    requested,
+  });
+  if (chosen.length === 0) {
+    return {
+      ok: true,
+      command: 'db',
+      summary: msg('cli.db.seed.none'),
+      findings: discovery.findings,
+      data: seedPassToJson([]),
+    };
+  }
+  return withJobDriver(root, ctx, async () => {
+    const rows = await runSeeds({
+      seeds: chosen,
+      driver: postgresDriver(),
+      dryRun,
+      env: ctx.env,
+      // One transaction per seed, so a seed that throws takes only its own rows with it.
+      transaction: (work) => withTransaction(() => work()),
+    });
+    return seedPassResult(rows, dryRun, discovery.findings);
+  });
+}
+
+function seedPassResult(
+  rows: readonly SeedPassRow[],
+  dryRun: boolean,
+  findings: readonly Finding[],
+): CommandResult {
+  const totals = seedTotals(rows);
+  const failures = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+  return {
+    ok: failures.length === 0 && findings.length === 0,
+    command: 'db',
+    summary:
+      totals.failed > 0
+        ? msg('cli.db.seed.failed', { failed: totals.failed, count: rows.length })
+        : dryRun
+          ? msg('cli.db.seed.dryRun', { count: rows.length })
+          : msg('cli.db.seed.done', {
+              count: rows.length,
+              inserted: totals.inserted,
+              updated: totals.updated,
+              skipped: totals.skipped,
+            }),
+    findings: [...failures, ...findings],
+    lines: renderSeedTable(rows).map((line) => `  ${line}`),
+    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

package/src/cmd-dev.ts

@@ -42,6 +42,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
+import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
 const DEFAULT_PORT = 3000;
@@ -185,6 +186,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
+    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
+    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
+    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
+    metricsPort: metricsPortFor(options.env, options.port),
     buildId,
     runtime,
     routes,
@@ -266,14 +271,16 @@ export const devCommand: CliCommand = {
   spec: {
     name: 'dev',
     summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
-    usage: 'x dev [--port 3000] [--role web,worker] [--json]',
+    usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
       {
         name: 'role',
         type: 'string',
-        summary: `roles to run (default: all of ${DEV_ROLES.join(',')})`,
+        // `replicator` is named because it is selectable and NOT default — it takes a replication
+        // slot on a shared database, which is not something every `x dev` should do by starting.
+        summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
       },
       { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
     ],

package/src/cmd-doctor.ts

@@ -11,9 +11,10 @@ import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
 import { ICON_SOURCE } from './dev-assets';
 import { checkSourceDrift } from './drift';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
+import type { ParsedArgs } from './parse';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -126,7 +127,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       finding(
         'X_PORT_IN_USE',
         `port ${probe.port} is already listening`,
-        `x dev --port ${probe.port + 1}`,
+        `x dev --port ${neighbouringPort(probe.port)}`,
       ),
     );
   }
@@ -165,6 +166,18 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   return findings;
 }
 
+/**
+ * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
+ * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
+ * succeeds — so the port check could not fail, which is worse than not running it.
+ */
+export const doctorPort = (args: ParsedArgs): number =>
+  intFlagOr(
+    args,
+    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
+    DEFAULT_DOCTOR_PORT,
+  );
+
 const portFree = async (port: number): Promise<boolean> => {
   try {
     const server = Bun.serve({ port, fetch: () => new Response('') });
@@ -213,11 +226,7 @@ export const doctorCommand: CliCommand = {
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = intFlagOr(
-      ctx.args,
-      { name: 'port', command: 'doctor', ...PORT_RANGE, example: 'x doctor --port 3000' },
-      DEFAULT_DOCTOR_PORT,
-    );
+    const port = doctorPort(ctx.args);
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
     return {
       ok: findings.length === 0,

package/src/cmd-new.ts

@@ -67,7 +67,7 @@ export const newCommand: CliCommand = {
   spec: {
     name: 'new',
     summary: 'scaffold a new Ultimate monorepo that already runs',
-    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--json]',
+    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--force] [--json]',
     flags: [
       { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
       {

package/src/cmd-test.ts

@@ -9,9 +9,10 @@ import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
-import { quoteArg, runShards } from './test-shards';
-import { defaultWorkers } from './test-workers';
+import { runShards } from './test-shards';
+import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
@@ -25,6 +26,12 @@ const readIndex = (args: ParsedArgs, name: string, min: number): number | undefi
     name,
     command: 'test',
     min,
+    // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
+    // accepted, `planShards` clamps only to the file count, and `runParallel` `Promise.all`s them —
+    // one Bun process per test FILE, each with the framework module graph and a cloned database.
+    // `--worker` is an index into that split, so the same bound holds it (the exact upper index is
+    // `workers - 1`, refused a line below by the check that knows the real width).
+    max: WORKER_CEILING,
     example: `x test --${name} ${Math.max(min, 1)}`,
   });
 
@@ -54,7 +61,11 @@ export const testCommand: CliCommand = {
     usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
-      { name: 'workers', type: 'string', summary: 'process count (default: CPUs - 1, max 8)' },
+      {
+        name: 'workers',
+        type: 'string',
+        summary: `process count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      },
       {
         name: 'worker',
         type: 'string',