@ultimat3/cli 20.2.1 → 22.0.0

package/src/cmd-routes-spec.ts

@@ -0,0 +1,12 @@
+// `x routes`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-routes.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const routesSpec: CommandSpec = {
+  name: 'routes',
+  summary: 'the route table: path, surface, render mode, hydrate, offline',
+  usage: 'x routes [--surface site|app|api|shared] [--json]',
+  requiresApp: true,
+  flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
+};

package/src/cmd-routes.ts

@@ -8,6 +8,7 @@ import type { RouteDescriptor, Surface } from '@ultimat3/render';
 import { describeRoutes, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { msg } from './messages';
@@ -65,13 +66,7 @@ export function readSurfaceFilter(raw: string | undefined): Surface | undefined
 }
 
 export const routesCommand: CliCommand = {
-  spec: {
-    name: 'routes',
-    summary: 'the route table: path, surface, render mode, hydrate, offline',
-    usage: 'x routes [--surface site|app|api|shared] [--json]',
-    requiresApp: true,
-    flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
-  },
+  spec: routesSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
     // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s

package/src/cmd-secrets-spec.ts

@@ -0,0 +1,19 @@
+// `x secrets`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-secrets.ts`, which `registry.ts` imports only when the command runs.
+
+import { ENV_SCHEMA_EXPORT } from './app-env';
+import type { CommandSpec } from './parse';
+
+export const SECRETS_SUBCOMMANDS = ['show', 'init', 'edit', 'set', 'rotate'] as const;
+
+export const secretsSpec: CommandSpec = {
+  name: 'secrets',
+  summary: `the committed encrypted secrets, decrypted into the ${ENV_SCHEMA_EXPORT} variables of the same names`,
+  usage: 'x secrets [show|init|edit|set <NAME>|rotate] [--json]',
+  requiresApp: true,
+  subcommands: [...SECRETS_SUBCOMMANDS],
+  // The bare `x secrets` answers without a key ever leaving the file. Declared, not inherited
+  // from the array's order — `init`, `edit`, `set` and `rotate` all write.
+  defaultSubcommand: 'show',
+  flags: [],
+};

package/src/cmd-secrets.ts

@@ -30,6 +30,7 @@ import {
 } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
+import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
   MissingPositionalError,
@@ -39,9 +40,11 @@ import {
 } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { recoverRotation, rotateMasterKey } from './secrets-rotation';
+import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
 
-export const SECRETS_SUBCOMMANDS = ['show', 'init', 'edit', 'set', 'rotate'] as const;
+export { SECRETS_SUBCOMMANDS } from './cmd-secrets-spec';
 
 /** In order of precedence. `VISUAL` outranks `EDITOR` by POSIX convention on an interactive tty. */
 export const EDITOR_VARS = ['VISUAL', 'EDITOR'] as const;
@@ -74,9 +77,10 @@ interface Session {
   readonly key: MasterKeyRef;
 }
 
-const open = (ctx: CommandContext, subcommand: string): Session => {
+/** The root and its key — after finishing or abandoning a rotation a crash interrupted. */
+const open = async (ctx: CommandContext, subcommand: string): Promise<Session> => {
   const root = requireAppRoot(`secrets ${subcommand}`, ctx.cwd).dir;
-  return { root, key: requireMasterKey(root, ctx.env) };
+  return { root, key: await recoverRotation(root, requireMasterKey(root, ctx.env)) };
 };
 
 const names = (values: SecretValues): readonly string[] => Object.keys(values).sort();
@@ -148,7 +152,7 @@ async function init(ctx: CommandContext): Promise<CommandResult> {
  * of the two harms. Leaving decrypted values on disk so they can be recovered is the larger one.
  */
 async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'edit');
+  const { root, key } = await open(ctx, 'edit');
   const editor = EDITOR_VARS.map((name) => ctx.env[name]).find(
     (value): value is string => value !== undefined && value.trim().length > 0,
   );
@@ -157,9 +161,9 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
   const dir = await mkdtemp(join(tmpdir(), 'ultimate-secrets-'));
   const buffer = join(dir, 'secrets.json');
   const shred = (): void => rmSync(dir, { recursive: true, force: true });
-  // A `finally` does not run for a signal, and Ctrl-C inside an editor kills this process too.
-  process.once('SIGINT', shred);
-  process.once('SIGTERM', shred);
+  // A `finally` does not run for a signal, and Ctrl-C inside an editor kills this process too —
+  // after the shred, which `shredOnSignal` runs and then re-raises the signal for.
+  const unlisten = shredOnSignal(shred);
   try {
     await Bun.write(buffer, serializeSecretValues(before));
     // `$EDITOR` may carry flags (`code --wait`), and there is no shell here to split them.
@@ -195,8 +199,7 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
     };
   } finally {
     shred();
-    process.off('SIGINT', shred);
-    process.off('SIGTERM', shred);
+    unlisten();
   }
 }
 
@@ -217,7 +220,7 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
       example: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
     });
   }
-  const { root, key } = open(ctx, 'set');
+  const { root, key } = await open(ctx, 'set');
   const before = await readSecretsFile(root, key);
   // Exactly one trailing newline, because `echo` adds one and a secret with a stray `\n` fails
   // against the service it authenticates to with an error that names nothing.
@@ -242,23 +245,18 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
 }
 
 /**
- * A new master key over the same values. The committed file is written FIRST and the key file last,
- * because only one of the two can be recovered: `secrets.enc.json` is in git, and a master key that
- * is half-overwritten is gone. Interrupted between the two writes, the old key still on disk meets
- * a file it cannot open — `X_SECRETS_KEY_MISMATCH`, whose fix restores the file from git.
+ * A new master key over the same values: staged beside the old one, the file sealed with it, then
+ * made live (`rotateMasterKey`). Sealed first with the key file written last, a crash between the
+ * two left a committed file no key on disk could open.
  */
 async function rotate(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'rotate');
+  const { root, key } = await open(ctx, 'rotate');
   const values = await readSecretsFile(root, key);
   const previous = await masterKeyIdOf(key);
-  const next: MasterKeyRef = {
-    hex: generateMasterKey(),
-    source: 'file',
-    at: masterKeyPath(root),
-  };
-  await writeSecretsFile(root, values, next);
+  // Ignored BEFORE any key file is written, staged one included; the order inside is
+  // `secrets-rotation.ts`'s: stage the key, seal, then rename it live.
   await ensureIgnored(root);
-  writeMasterKeyFile(root, next.hex);
+  const next = await rotateMasterKey(root, values);
   const keyId = await masterKeyIdOf(next);
   return {
     ok: true,
@@ -286,7 +284,7 @@ async function rotate(ctx: CommandContext): Promise<CommandResult> {
  * `x secrets edit`. A `--reveal` flag would be a second path that `--json` could not honour.
  */
 async function show(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'show');
+  const { root, key } = await open(ctx, 'show');
   const values = await readSecretsFile(root, key);
   const schema = await loadEnvSchema(root);
   const summaries = describeSecrets(values);
@@ -337,17 +335,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
 
 export function createSecretsCommand(io: SecretsIo): CliCommand {
   return {
-    spec: {
-      name: 'secrets',
-      summary: `the committed encrypted secrets, decrypted into the ${ENV_SCHEMA_EXPORT} variables of the same names`,
-      usage: 'x secrets [show|init|edit|set <NAME>|rotate] [--json]',
-      requiresApp: true,
-      subcommands: [...SECRETS_SUBCOMMANDS],
-      // The bare `x secrets` answers without a key ever leaving the file. Declared, not inherited
-      // from the array's order — `init`, `edit`, `set` and `rotate` all write.
-      defaultSubcommand: 'show',
-      flags: [],
-    },
+    spec: secretsSpec,
     async run(ctx: CommandContext): Promise<CommandResult> {
       switch (ctx.args.subcommand ?? 'show') {
         case 'init':

package/src/cmd-shot-island.ts

@@ -9,10 +9,10 @@
 
 // why: no Bun native joins or resolves a path; `--out` is resolved against the app root.
 import { join, resolve } from 'node:path';
-import type { ScrapeDriver } from '@ultimat3/scraping';
 import type { IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
 import { findIslandStates } from '@ultimat3/testing';
 import { appBrowser } from './browser-launcher';
+import type { ShotDriver } from './browser-launcher-port';
 import { BadFlagError } from './errors';
 import type { IslandBrowser } from './island-shot';
 import { ISLAND_SHOT_DIR, runIslandShot, runIslandSweep } from './island-shot';
@@ -39,19 +39,18 @@ export function islandBrowser(input: {
   readonly executablePath?: string | undefined;
   readonly cdpUrl?: string | undefined;
 }): IslandBrowser {
-  const byViewport = new Map<string, Promise<ScrapeDriver>>();
-  return (viewport: IslandViewport): Promise<ScrapeDriver> => {
+  const byViewport = new Map<string, Promise<ShotDriver>>();
+  return (viewport: IslandViewport): Promise<ShotDriver> => {
     const key = `${viewport.width}x${viewport.height}`;
-    const held = byViewport.get(key);
-    if (held !== undefined) return held;
-    const started = appBrowser({
-      root: input.root,
-      ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
-      ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
-      viewport: { width: viewport.width, height: viewport.height },
-    });
-    byViewport.set(key, started);
-    return started;
+    const held =
+      byViewport.get(key) ??
+      appBrowser({
+        ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
+        viewport: { width: viewport.width, height: viewport.height },
+      });
+    byViewport.set(key, held);
+    return held;
   };
 }
 

package/src/cmd-shot-spec.ts

@@ -0,0 +1,53 @@
+// `x shot`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-shot.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+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> | --island <name> [--state <id>] | --all-islands [--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)' },
+    { name: 'out', type: 'string', summary: 'where shot.png and verdict.json are written' },
+    { name: 'full', type: 'boolean', summary: 'whole page, not the fold', default: true },
+    { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
+    { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
+    { name: 'browser', type: 'string', summary: 'Chrome or Chromium binary to launch' },
+    {
+      name: 'cdp-url',
+      type: 'string',
+      summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
+    },
+    { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
+    {
+      name: 'theme',
+      type: 'string',
+      summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
+    },
+    // 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
+    // axiom 1 refuses.
+    {
+      name: 'island',
+      type: 'string',
+      summary: 'photograph one island in every state it declares',
+    },
+    {
+      name: 'state',
+      type: 'string',
+      summary: 'one declared state of that island, not all of them',
+    },
+    // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
+    // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
+    // reader could type that could not be read as a mistyped one. A boolean cannot be confused
+    // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
+    {
+      name: 'all-islands',
+      type: 'boolean',
+      summary: 'every island in the app, in every state it declares, plus an index.md',
+    },
+  ],
+};

package/src/cmd-shot.ts

@@ -8,10 +8,10 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ColorScheme, ScrapeDriver, ScrapePage, ScrapeSession } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
+import type { ShotColorScheme, ShotDriver, ShotPage, ShotSession } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS, systemShotClock } from './cdp-shot-clock';
 import {
   islandShot,
   islandShotResult,
@@ -22,6 +22,7 @@ import {
   refuseSweepWithRoute,
   refuseSweepWithState,
 } from './cmd-shot-island';
+import { shotSpec } from './cmd-shot-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
@@ -181,7 +182,7 @@ const intFlag = (
 export interface ShotRun {
   readonly route: string;
   readonly outDir: string;
-  readonly driver: ScrapeDriver;
+  readonly driver: ShotDriver;
   readonly boot: () => Promise<ShotServer>;
   readonly settleMs: number;
   readonly timeoutMs: number;
@@ -200,7 +201,7 @@ export interface ShotRun {
    * neither: the box's own preference and the app's own default — what `x shot` has always done,
    * and the point of `defaultMode` — and `ui.shot` names one explicitly for exactly that reason.
    */
-  readonly colorScheme?: ColorScheme | undefined;
+  readonly colorScheme?: ShotColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
   /**
    * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
@@ -209,7 +210,7 @@ export interface ShotRun {
    * caller who never calls it gets the count from the first settle.
    */
   readonly act?:
-    | ((page: ScrapePage, settle: () => Promise<IslandCount | null>) => Promise<void>)
+    | ((page: ShotPage, settle: () => Promise<IslandCount | null>) => Promise<void>)
     | undefined;
 }
 
@@ -226,7 +227,7 @@ const quietly = async (stop: () => Promise<void>): Promise<void> => {
  */
 export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   const server = await options.boot();
-  let session: ScrapeSession | undefined;
+  let session: ShotSession | undefined;
   try {
     const requestedUrl = new URL(options.route, server.url).toString();
     session = await options.driver.open({
@@ -235,7 +236,7 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       // inside your network is the widest SSRF surface an app can own, and a screenshot command is
       // not the place to open it by default. Every refusal lands in the verdict's `refused` count.
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
-      clock: systemScrapeClock,
+      clock: systemShotClock,
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
@@ -312,54 +313,7 @@ export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
 });
 
 export const shotCommand: CliCommand = {
-  spec: {
-    name: 'shot',
-    summary: 'photograph one route, one island in a state it declares, or every island in the app',
-    usage:
-      'x shot <route> | --island <name> [--state <id>] | --all-islands [--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)' },
-      { name: 'out', type: 'string', summary: 'where shot.png and verdict.json are written' },
-      { name: 'full', type: 'boolean', summary: 'whole page, not the fold', default: true },
-      { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
-      { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
-      { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
-      {
-        name: 'cdp-url',
-        type: 'string',
-        summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
-      },
-      { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
-      {
-        name: 'theme',
-        type: 'string',
-        summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
-      },
-      // 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
-      // axiom 1 refuses.
-      {
-        name: 'island',
-        type: 'string',
-        summary: 'photograph one island in every state it declares',
-      },
-      {
-        name: 'state',
-        type: 'string',
-        summary: 'one declared state of that island, not all of them',
-      },
-      // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
-      // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
-      // reader could type that could not be read as a mistyped one. A boolean cannot be confused
-      // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
-      {
-        name: 'all-islands',
-        type: 'boolean',
-        summary: 'every island in the app, in every state it declares, plus an index.md',
-      },
-    ],
-  },
+  spec: shotSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('shot', ctx.cwd).dir;
     // Every value read before anything boots: a typo must not cost a browser and a dev server to
@@ -396,8 +350,7 @@ export const shotCommand: CliCommand = {
     // Which browser this run gets — start one here, or attach to one somebody else is running.
     // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
     // provider session exists to pay for a typo. It also PROBES for an installed Chrome and refuses
-    // when there is none: `puppeteer-core` bundles no browser, so a missing one used to surface as
-    // a library throw one embedded Postgres later.
+    // when there is none, so a missing browser costs no embedded Postgres boot.
     const { cdpUrl, executablePath } = shotBrowserChoice({
       cdpFlag: flagString(ctx.args, 'cdp-url'),
       browserFlag: flagString(ctx.args, 'browser'),
@@ -423,10 +376,8 @@ export const shotCommand: CliCommand = {
         await islandShot({ ...shared, island, ...(state === undefined ? {} : { state }) }),
       );
     }
-    // Resolved before the boot for the same reason: an app with no browser installed must not pay
-    // an embedded Postgres to be told to run `bun add -d puppeteer-core`.
+    // Built before the boot, for the same reason.
     const driver = await appBrowser({
-      root,
       ...(executablePath === undefined ? {} : { executablePath }),
       ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });

package/src/cmd-tasks-spec.ts

@@ -0,0 +1,21 @@
+// `x tasks`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-tasks.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const tasksSpec: CommandSpec = {
+  name: 'tasks',
+  summary: 'cron tasks, their timezone and their next run',
+  usage: 'x tasks [list|show <name>] [--count n] [--json]',
+  requiresApp: true,
+  subcommands: ['list', 'show'],
+  defaultSubcommand: 'list',
+  flags: [
+    {
+      name: 'count',
+      type: 'string',
+      summary: 'show: how many upcoming occurrences to list',
+      subcommands: ['show'],
+    },
+  ],
+};

package/src/cmd-tasks.ts

@@ -8,6 +8,7 @@ import type { TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { tasksSpec } from './cmd-tasks-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, DeclarationUnknownError } from './errors';
 import { msg } from './messages';
@@ -130,22 +131,7 @@ function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[
 }
 
 export const tasksCommand: CliCommand = {
-  spec: {
-    name: 'tasks',
-    summary: 'cron tasks, their timezone and their next run',
-    usage: 'x tasks [list|show <name>] [--count n] [--json]',
-    requiresApp: true,
-    subcommands: ['list', 'show'],
-    defaultSubcommand: 'list',
-    flags: [
-      {
-        name: 'count',
-        type: 'string',
-        summary: 'show: how many upcoming occurrences to list',
-        subcommands: ['show'],
-      },
-    ],
-  },
+  spec: tasksSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('tasks', ctx.cwd).dir;
     const { findings } = await loadApp(root);

package/src/cmd-test-spec.ts

@@ -0,0 +1,54 @@
+// `x test`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-test.ts`, which `registry.ts` imports only when the command runs.
+
+import { TEST_TYPES } from '@ultimat3/testing/test-types';
+import { DEFAULT_BASE } from './affected';
+import type { CommandSpec } from './parse';
+import { SERIAL_TYPES, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+
+export const testSpec: CommandSpec = {
+  name: 'test',
+  summary:
+    'run one test type — or the whole suite — across N workers, one isolated database per worker',
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
+  positionalChoices: TEST_TYPES,
+  // The one command that hands a tail to another tool — `bun test` — and the reason
+  // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
+  // dropped both, so a run that measured no coverage reported exactly what a coverage run does.
+  passthrough: true,
+  flags: [
+    {
+      name: 'workers',
+      type: 'string',
+      summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
+    },
+    {
+      name: 'worker',
+      type: 'string',
+      summary:
+        'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
+    },
+    { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
+    {
+      name: 'sample',
+      type: 'string',
+      summary:
+        'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
+    },
+    {
+      name: 'affected',
+      type: 'boolean',
+      summary: 'only the workspaces a diff touches, and everything that depends on one of them',
+    },
+    {
+      name: 'base',
+      type: 'string',
+      summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+    },
+    {
+      name: 'dirty',
+      type: 'boolean',
+      summary: '--affected: also count uncommitted work, whichever agent in this checkout made it',
+    },
+  ],
+};

package/src/cmd-test.ts

@@ -7,6 +7,7 @@
 
 import type { AffectedScope } from './affected';
 import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
+import { testSpec } from './cmd-test-spec';
 import type { CliCommand, CommandContext } from './command';
 import { ok } from './command';
 import { BadFlagError, NoTestFilesError } from './errors';
@@ -18,9 +19,9 @@ import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
 import { runShards } from './test-shards';
-import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { defaultWorkers, SERIAL_TYPES, WORKER_CEILING } from './test-workers';
 import type { TestType } from './verify-tests';
-import { SERIAL_TYPES, TEST_TYPES } from './verify-tests';
+import { TEST_TYPES } from './verify-tests';
 
 /**
  * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
@@ -100,53 +101,7 @@ const withScope = (result: CommandResult, scope: AffectedScope): CommandResult =
 });
 
 export const testCommand: CliCommand = {
-  spec: {
-    name: 'test',
-    summary:
-      'run one test type — or the whole suite — across N workers, one isolated database per worker',
-    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
-    positionalChoices: TEST_TYPES,
-    // The one command that hands a tail to another tool — `bun test` — and the reason
-    // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
-    // dropped both, so a run that measured no coverage reported exactly what a coverage run does.
-    passthrough: true,
-    flags: [
-      {
-        name: 'workers',
-        type: 'string',
-        summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
-      },
-      {
-        name: 'worker',
-        type: 'string',
-        summary:
-          'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
-      },
-      { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
-      {
-        name: 'sample',
-        type: 'string',
-        summary:
-          'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
-      },
-      {
-        name: 'affected',
-        type: 'boolean',
-        summary: 'only the workspaces a diff touches, and everything that depends on one of them',
-      },
-      {
-        name: 'base',
-        type: 'string',
-        summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
-      },
-      {
-        name: 'dirty',
-        type: 'boolean',
-        summary:
-          '--affected: also count uncommitted work, whichever agent in this checkout made it',
-      },
-    ],
-  },
+  spec: testSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const type = readOnlyType(ctx.args.positionals);
     const filter = flagString(ctx.args, 'filter');

package/src/cmd-verify-spec.ts

@@ -0,0 +1,28 @@
+// `x verify`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-verify.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+
+export const verifySpec: CommandSpec = {
+  name: 'verify',
+  summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
+  usage: 'x verify [--only <step>] [--workers N] [--json]',
+  requiresApp: true,
+  // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
+  // spread, never which steps run. `--only` runs one step and says so in both renderers —
+  // never silently, which is the whole of what makes it safe to have.
+  flags: [
+    {
+      name: 'workers',
+      type: 'string',
+      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+    },
+    {
+      name: 'only',
+      type: 'string',
+      summary:
+        'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
+    },
+  ],
+};