@ultimat3/cli 22.2.2 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.2.2",
+  "version": "22.3.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.2.2",
-    "@ultimat3/admin": "22.2.2",
-    "@ultimat3/ai": "22.2.2",
-    "@ultimat3/auth": "22.2.2",
-    "@ultimat3/cache": "22.2.2",
-    "@ultimat3/core": "22.2.2",
-    "@ultimat3/db": "22.2.2",
-    "@ultimat3/entity": "22.2.2",
-    "@ultimat3/flags": "22.2.2",
-    "@ultimat3/http": "22.2.2",
-    "@ultimat3/i18n": "22.2.2",
-    "@ultimat3/jobs": "22.2.2",
-    "@ultimat3/mail": "22.2.2",
-    "@ultimat3/manifest": "22.2.2",
-    "@ultimat3/mcp": "22.2.2",
-    "@ultimat3/money": "22.2.2",
-    "@ultimat3/notify": "22.2.2",
-    "@ultimat3/policy": "22.2.2",
-    "@ultimat3/pwa": "22.2.2",
-    "@ultimat3/query": "22.2.2",
-    "@ultimat3/realtime": "22.2.2",
-    "@ultimat3/render": "22.2.2",
-    "@ultimat3/schema": "22.2.2",
-    "@ultimat3/seo": "22.2.2",
-    "@ultimat3/storage": "22.2.2",
-    "@ultimat3/testing": "22.2.2",
-    "@ultimat3/time": "22.2.2",
+    "@ultimat3/action": "22.3.0",
+    "@ultimat3/admin": "22.3.0",
+    "@ultimat3/ai": "22.3.0",
+    "@ultimat3/auth": "22.3.0",
+    "@ultimat3/cache": "22.3.0",
+    "@ultimat3/core": "22.3.0",
+    "@ultimat3/db": "22.3.0",
+    "@ultimat3/entity": "22.3.0",
+    "@ultimat3/flags": "22.3.0",
+    "@ultimat3/http": "22.3.0",
+    "@ultimat3/i18n": "22.3.0",
+    "@ultimat3/jobs": "22.3.0",
+    "@ultimat3/mail": "22.3.0",
+    "@ultimat3/manifest": "22.3.0",
+    "@ultimat3/mcp": "22.3.0",
+    "@ultimat3/money": "22.3.0",
+    "@ultimat3/notify": "22.3.0",
+    "@ultimat3/policy": "22.3.0",
+    "@ultimat3/pwa": "22.3.0",
+    "@ultimat3/query": "22.3.0",
+    "@ultimat3/realtime": "22.3.0",
+    "@ultimat3/render": "22.3.0",
+    "@ultimat3/schema": "22.3.0",
+    "@ultimat3/seo": "22.3.0",
+    "@ultimat3/storage": "22.3.0",
+    "@ultimat3/testing": "22.3.0",
+    "@ultimat3/time": "22.3.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -13,7 +13,13 @@ import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { listQueries, registerQueries } from '@ultimat3/query';
 import type { RouteConfig } from '@ultimat3/render';
-import { isRouteConfig, pageComponentOf, registerRoute, routeEntries } from '@ultimat3/render';
+import {
+  isRouteConfig,
+  pageComponentOf,
+  registerRoute,
+  routeEntries,
+  setAssetResolver,
+} from '@ultimat3/render';
 // For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
 // installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
 // every app module below is loaded by the dynamic `import()` in this file. Before the render
@@ -27,6 +33,7 @@ import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { siteAssetTable } from './site-assets';
 import { isTest } from './source-files';
 
 /** Every place an app keeps code the framework has to see. */
@@ -113,6 +120,10 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   // path — under the container's `WORKDIR /app` that path's first segment is `app/`, and every
   // sheet, the site's included, classified as app CSS.
   setStylesheetRoot(root);
+  // And before any page renders: `asset('assets/…')` answers from this app's own table, in
+  // `x dev`, the container and the static build alike — one install, three processes.
+  const assets = siteAssetTable(root);
+  setAssetResolver((path) => assets.resolve(path).url);
   const files: string[] = [];
   const findings: Finding[] = [];
 

package/src/browser-launcher-port.ts

@@ -145,6 +145,13 @@ export interface ShotSessionInit {
   readonly clock: ShotClock;
   /** Per-operation default, in ms. */
   readonly timeoutMs: number;
+  /** CSS pixels the page is laid out in. Absent: the driver's own default. */
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
+  /**
+   * Sent on every request the page makes. `x shot` pins `accept-language` here so a picture is of
+   * the locale asked for, never of whatever language the machine's Chrome happens to speak.
+   */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
 }
 
 export interface ShotSession {

package/src/cdp-shot-driver.ts

@@ -134,9 +134,15 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
         await on('Page.enable');
         await on('Network.enable');
         await on('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+        // Before the first navigation, like the metrics below: a header set after `goto` would
+        // photograph a document negotiated in the machine's own language.
+        if (init.headers !== undefined && Object.keys(init.headers).length > 0) {
+          await on('Network.setExtraHTTPHeaders', { headers: init.headers });
+        }
+        const size = init.viewport ?? viewport;
         await on('Emulation.setDeviceMetricsOverride', {
-          width: viewport.width,
-          height: viewport.height,
+          width: size.width,
+          height: size.height,
           deviceScaleFactor: 1,
           mobile: false,
         });

package/src/cmd-shot-matrix.ts

@@ -0,0 +1,201 @@
+// `x shot --matrix` — every static `site/` route × every locale × light and dark × a phone and a
+// desktop width, into `.x/shot/matrix/`, with an `index.html` contact sheet a reviewer scrolls
+// instead of opening a hundred files. One dev server for the whole run; each cell is an ordinary
+// `runShot`, so a cell's `verdict.json` means exactly what a single shot's does.
+
+// why: no Bun native joins a path.
+import { join, relative } from 'node:path';
+import { routeEntries } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import type { ShotRun } from './cmd-shot';
+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';
+
+export const MATRIX_DIR = join(SHOT_DIR, 'matrix');
+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. */
+export const MATRIX_VIEWPORTS: readonly { readonly width: number; readonly height: number }[] = [
+  { width: 390, height: 844 },
+  { width: 1440, height: 900 },
+];
+
+export interface MatrixCell {
+  /** The declared route, `/precios`. */
+  readonly route: string;
+  readonly locale: string;
+  readonly theme: 'light' | 'dark';
+  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>`. */
+  readonly dir: string;
+}
+
+/** A route a matrix can photograph without inventing a parameter: no `:param`, no `*rest`. */
+export const isMatrixRoute = (path: string): boolean => !/[:*[]/.test(path);
+
+const slug = (route: string): string => {
+  const cleaned = route.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return cleaned === '' ? 'root' : cleaned.toLowerCase();
+};
+
+/**
+ * The app's static `site/` routes, read off the registry `loadApp` fills — the same table the
+ * sitemap and the static export are built from, so the matrix photographs what ships.
+ */
+export async function matrixRoutes(root: string): Promise<readonly string[]> {
+  await loadApp(root);
+  return routeEntries()
+    .filter((entry) => entry.surface === 'site' && isMatrixRoute(entry.path))
+    .map((entry) => entry.path);
+}
+
+export interface MatrixPlanInput {
+  readonly routes: readonly string[];
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+  readonly themes?: readonly ('light' | 'dark')[] | undefined;
+  readonly viewports?: readonly { readonly width: number; readonly height: number }[] | undefined;
+}
+
+/** Every cell, route-major, in a stable order — the contact sheet reads top to bottom by route. */
+export function planShotMatrix(input: MatrixPlanInput): readonly MatrixCell[] {
+  const cells: MatrixCell[] = [];
+  for (const route of input.routes.filter(isMatrixRoute)) {
+    for (const locale of input.locales) {
+      for (const theme of input.themes ?? MATRIX_THEMES) {
+        for (const viewport of input.viewports ?? MATRIX_VIEWPORTS) {
+          cells.push({
+            route,
+            locale,
+            theme,
+            viewport,
+            path: localizedShotPath(route, locale, input.defaultLocale),
+            dir: join(slug(route), locale, `${theme}-${String(viewport.width)}`),
+          });
+        }
+      }
+    }
+  }
+  return cells;
+}
+
+export interface MatrixShot {
+  readonly cell: MatrixCell;
+  readonly ok: boolean;
+  /** Relative to the matrix directory, as the contact sheet links it. */
+  readonly image: string;
+}
+
+const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/**
+ * The contact sheet. System colours only (`Canvas`, `CanvasText`, `Mark`): a generated review page
+ * has no design tokens to read, and a literal colour would be the one this repo refuses.
+ */
+export function contactSheet(shots: readonly MatrixShot[]): string {
+  const routes = [...new Set(shots.map((shot) => shot.cell.route))];
+  const sections = routes.map((route) => {
+    const figures = shots
+      .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'}`;
+        return (
+          `<figure${shot.ok ? '' : ' class="failed"'}><a href="${escapeHtml(shot.image)}">` +
+          `<img src="${escapeHtml(shot.image)}" alt="${escapeHtml(`${path} ${label}`)}" loading="lazy" ` +
+          `width="${String(Math.round(viewport.width / 4))}"></a>` +
+          `<figcaption>${escapeHtml(label)}</figcaption></figure>`
+        );
+      })
+      .join('');
+    return `<section><h2>${escapeHtml(route)}</h2><div class="grid">${figures}</div></section>`;
+  });
+  return [
+    '<!doctype html>',
+    '<html lang="en"><head><meta charset="utf-8"><title>x shot --matrix</title>',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<style>',
+    ':root{color-scheme:light dark}body{margin:1rem;font:14px/1.4 system-ui,sans-serif;',
+    'background:Canvas;color:CanvasText}',
+    '.grid{display:flex;flex-wrap:wrap;gap:1rem;align-items:flex-start}',
+    'figure{margin:0}img{display:block;height:auto;border:1px solid GrayText}',
+    '.failed figcaption{background:Mark;color:MarkText}',
+    '</style></head><body>',
+    `<h1>x shot --matrix — ${String(shots.length)} pictures, ${String(shots.filter((shot) => !shot.ok).length)} failed</h1>`,
+    ...sections,
+    '</body></html>',
+    '',
+  ].join('\n');
+}
+
+export interface MatrixRun {
+  readonly cells: readonly MatrixCell[];
+  /** Absolute matrix directory. */
+  readonly outDir: string;
+  readonly boot: () => Promise<ShotServer>;
+  /** `runShot`, handed in so this module never imports the command that imports it. */
+  readonly shoot: (run: ShotRun) => Promise<ShotArtifacts>;
+  /** Everything a cell shares: the driver, the waits, the hosts. */
+  readonly base: Omit<ShotRun, 'route' | 'outDir' | 'boot' | 'colorScheme' | 'viewport'>;
+}
+
+/**
+ * One server for every cell: booting `x dev` per picture would be a Postgres start per cell, and
+ * reusing is the rule `devServerFor` already follows. The cells share it through a boot that
+ * never stops it; the run stops it once, after the last picture.
+ */
+export async function runShotMatrix(run: MatrixRun): Promise<CommandResult> {
+  const server = await run.boot();
+  const shared: ShotServer = { ...server, stop: () => Promise.resolve() };
+  const shots: MatrixShot[] = [];
+  try {
+    for (const cell of run.cells) {
+      const artifacts = await run.shoot({
+        ...run.base,
+        route: cell.path,
+        outDir: join(run.outDir, cell.dir),
+        boot: () => Promise.resolve(shared),
+        colorScheme: cell.theme,
+        viewport: cell.viewport,
+        acceptLanguage: cell.locale,
+      });
+      shots.push({
+        cell,
+        ok: artifacts.verdict.ok,
+        image: relative(run.outDir, artifacts.image).split('\\').join('/'),
+      });
+    }
+  } finally {
+    await server.stop().catch(() => undefined);
+  }
+  const index = join(run.outDir, MATRIX_INDEX);
+  await Bun.write(index, contactSheet(shots));
+  const failed = shots.filter((shot) => !shot.ok);
+  return {
+    ok: failed.length === 0,
+    command: 'shot',
+    summary: `${String(shots.length)} pictures, ${String(failed.length)} failed — ${index}`,
+    lines: failed.map((shot) => `FAILED ${shot.cell.path} (${shot.cell.dir})`),
+    data: {
+      index,
+      cells: shots.map((shot) => ({
+        route: shot.cell.route,
+        path: shot.cell.path,
+        locale: shot.cell.locale,
+        theme: shot.cell.theme,
+        width: shot.cell.viewport.width,
+        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> | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<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)' },
@@ -27,6 +27,20 @@ export const shotSpec: CommandSpec = {
       type: 'string',
       summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
     },
+    {
+      name: 'locale',
+      type: 'string',
+      summary:
+        "one of the app's locales: sent as Accept-Language, and a /<locale>/ prefix unless it is the default (absent: the default locale, pinned)",
+    },
+    // A flag and not a second command, for `--island`'s reason below: the matrix is many route
+    // shots, each one exactly what `x shot <route> --locale <l> --theme <t>` would take.
+    {
+      name: 'matrix',
+      type: 'boolean',
+      summary:
+        'every site route × locale × light/dark × 390/1440 px into .x/shot/matrix/, plus an index.html contact sheet',
+    },
     // 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.

package/src/cmd-shot.ts

@@ -7,6 +7,7 @@
 
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { renderFixShellArg } from '@ultimat3/core';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -22,6 +23,7 @@ import {
   refuseSweepWithRoute,
   refuseSweepWithState,
 } from './cmd-shot-island';
+import { MATRIX_DIR, matrixRoutes, planShotMatrix, runShotMatrix } from './cmd-shot-matrix';
 import { shotSpec } from './cmd-shot-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
@@ -30,6 +32,12 @@ import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { shotBrowserChoice } from './shot-browser';
+import {
+  acceptLanguageHeaders,
+  loadShotLocales,
+  localizedShotPath,
+  readLocaleFlag,
+} from './shot-locale';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
@@ -202,6 +210,13 @@ export interface ShotRun {
    * and the point of `defaultMode` — and `ui.shot` names one explicitly for exactly that reason.
    */
   readonly colorScheme?: ShotColorScheme | undefined;
+  /** CSS pixels the page is laid out in; absent is the driver's default. */
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
+  /**
+   * Sent as `Accept-Language` on every request. The command always sets it — `--locale`, or the
+   * app's default locale — so a picture never depends on the language of the machine's Chrome.
+   */
+  readonly acceptLanguage?: string | undefined;
   readonly now?: (() => Date) | undefined;
   /**
    * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
@@ -238,6 +253,10 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
       clock: systemShotClock,
       timeoutMs: options.timeoutMs,
+      ...(options.viewport === undefined ? {} : { viewport: options.viewport }),
+      ...(options.acceptLanguage === undefined
+        ? {}
+        : { headers: acceptLanguageHeaders(options.acceptLanguage) }),
     });
     const page = session.page;
     if (options.colorScheme !== undefined) {
@@ -323,6 +342,9 @@ export const shotCommand: CliCommand = {
     const theme = readThemeFlag(flagString(ctx.args, 'theme'));
     const positional = ctx.args.positionals[0];
     const sweep = flagBool(ctx.args, 'all-islands');
+    const matrix = flagBool(ctx.args, 'matrix');
+    const app = await loadShotLocales(root);
+    const locale = readLocaleFlag(flagString(ctx.args, 'locale'), app);
     // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
     // subjects has a belief about which one runs, and half of them would be wrong.
     if (sweep && island !== undefined && island !== '') refuseSweepWithIsland(island);
@@ -333,8 +355,25 @@ export const shotCommand: CliCommand = {
       refuseRouteWithIsland(positional, island);
     }
     const component = sweep || (island !== undefined && island !== '');
+    // The matrix photographs ROUTES; a component beside it is two subjects.
+    if (matrix && component) {
+      throw new BadFlagError({
+        flag: 'matrix',
+        command: 'shot',
+        reason: 'photographs every site route; --island and --all-islands photograph components',
+        fix: 'x shot --matrix --json',
+      });
+    }
     // An island is photographed in BOTH themes by the harness, which owns its `data-theme` and
     // carries no boot script — so a theme asked for beside one is a request nothing could honour.
+    if (component && locale !== undefined) {
+      throw new BadFlagError({
+        flag: 'locale',
+        command: 'shot',
+        reason: 'photographs a route; an island is photographed in the locale its states declare',
+        fix: `x shot / --locale ${renderFixShellArg(locale, '<locale>')} --json`,
+      });
+    }
     if (component && theme !== undefined) {
       throw new BadFlagError({
         flag: 'theme',
@@ -343,7 +382,8 @@ export const shotCommand: CliCommand = {
         fix: 'x shot / --theme light --json',
       });
     }
-    const route = component ? '' : readRoute(positional);
+    // `--matrix` alone is every site route; a route beside it narrows the matrix to that one.
+    const route = component || (matrix && positional === undefined) ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
@@ -381,16 +421,34 @@ export const shotCommand: CliCommand = {
       ...(executablePath === undefined ? {} : { executablePath }),
       ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });
+    const base = {
+      driver,
+      settleMs,
+      timeoutMs,
+      fullPage: flagBool(ctx.args, 'full'),
+      extraHosts: flagString(ctx.args, 'allow-hosts'),
+    };
+    if (matrix) {
+      // `--locale` and `--theme` narrow the matrix to one value of their axis.
+      const cells = planShotMatrix({
+        routes: route === '' ? await matrixRoutes(root) : [route],
+        locales: locale === undefined ? app.locales : [locale],
+        defaultLocale: app.defaultLocale,
+        ...(theme === undefined ? {} : { themes: [theme] }),
+      });
+      const outDir = out === undefined ? join(root, MATRIX_DIR) : resolve(root, out);
+      return runShotMatrix({ cells, outDir, boot, shoot: runShot, base });
+    }
+    const shown = locale ?? app.defaultLocale;
+    const path = localizedShotPath(route, shown, app.defaultLocale);
     return shotResult(
       await runShot({
-        route,
-        outDir: out === undefined ? join(root, SHOT_DIR, shotSlug(route)) : resolve(root, out),
-        driver,
+        ...base,
+        route: path,
+        outDir: out === undefined ? join(root, SHOT_DIR, shotSlug(path)) : resolve(root, out),
         boot,
-        settleMs,
-        timeoutMs,
-        fullPage: flagBool(ctx.args, 'full'),
-        extraHosts: flagString(ctx.args, 'allow-hosts'),
+        // Pinned whether or not `--locale` was given: the default locale, never the box's own.
+        acceptLanguage: shown,
         ...(theme === undefined ? {} : { colorScheme: theme }),
       }),
     );

package/src/cmd-test-spec.ts

@@ -10,7 +10,7 @@ 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>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--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
@@ -20,7 +20,7 @@ export const testSpec: CommandSpec = {
     {
       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 ')}`,
+      summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to free memory, min ${WORKER_FLOOR}; max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
     },
     {
       name: 'worker',
@@ -28,7 +28,17 @@ export const testSpec: CommandSpec = {
       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: 'filter',
+      type: 'string',
+      summary: 'only files whose path contains this substring — or any of several, comma-separated',
+    },
+    {
+      name: 'allow-empty',
+      type: 'boolean',
+      summary:
+        'a selection that matches no test file exits 0 with a line saying so, instead of X_TEST_NO_FILES',
+    },
     {
       name: 'sample',
       type: 'string',

package/src/cmd-test.ts

@@ -17,7 +17,14 @@ import type { CommandResult, JsonValue } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
-import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
+import {
+  discoverTests,
+  missingSelection,
+  readFilters,
+  readSample,
+  readType,
+  sampleFiles,
+} from './test-select';
 import { runShards } from './test-shards';
 import { defaultWorkers, SERIAL_TYPES, WORKER_CEILING } from './test-workers';
 import type { TestType } from './verify-tests';
@@ -100,16 +107,37 @@ const withScope = (result: CommandResult, scope: AffectedScope): CommandResult =
   data: { ...asObject(result.data), affected: affectedScopeJson(scope) },
 });
 
+/** The selection that matched nothing, as one phrase for `cli.test.empty`. */
+const describeSelection = (missing: { type?: string; filter?: string }): string =>
+  [
+    missing.type === undefined ? undefined : `type ${missing.type}`,
+    missing.filter === undefined ? undefined : `"${missing.filter}"`,
+  ]
+    .filter((part) => part !== undefined)
+    .join(' and ') || 'the selection';
+
 export const testCommand: CliCommand = {
   spec: testSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const type = readOnlyType(ctx.args.positionals);
     const filter = flagString(ctx.args, 'filter');
+    const filters = readFilters(filter);
     const sample = readSample(ctx.args);
     const scope = await readAffectedScope(ctx);
-    const discovered = await discoverTests(ctx.cwd, filter, type);
+    const discovered = await discoverTests(ctx.cwd, filters, type);
     if (discovered.length === 0) {
-      throw new NoTestFilesError({ root: ctx.cwd, ...missingSelection(type, filter) });
+      const missing = missingSelection(type, filter);
+      // `--allow-empty` is for a caller that COMPUTED the selection — a scoped runner handing over
+      // the paths a diff touched, some of which hold no test yet. Green, spawning nothing, and
+      // never read as "the suite passed": the line names the selection that matched nothing and
+      // `data.files` is 0. Without the flag an empty selection stays X_TEST_NO_FILES, because a
+      // typo'd `--filter` typed by hand is exactly the run that must not pass.
+      if (flagBool(ctx.args, 'allow-empty')) {
+        return ok('test', msg('cli.test.empty', { selection: describeSelection(missing) }), {
+          data: { ...missing, files: 0, empty: true },
+        });
+      }
+      throw new NoTestFilesError({ root: ctx.cwd, ...missing });
     }
     const selected =
       scope === undefined

package/src/cmd-verify-spec.ts

@@ -7,22 +7,22 @@ import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-worke
 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]',
+  usage: 'x verify [--only <step>[,<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 —
+  // spread, never which steps run. `--only` runs the steps it names 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})`,
+      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to free memory; 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',
+        'run the named step(s), comma-separated, in one process — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
     },
   ],
 };