@ultimat3/cli 22.3.0 → 22.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.0",
+  "version": "22.3.1",
   "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.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",
+    "@ultimat3/action": "22.3.1",
+    "@ultimat3/admin": "22.3.1",
+    "@ultimat3/ai": "22.3.1",
+    "@ultimat3/auth": "22.3.1",
+    "@ultimat3/cache": "22.3.1",
+    "@ultimat3/core": "22.3.1",
+    "@ultimat3/db": "22.3.1",
+    "@ultimat3/entity": "22.3.1",
+    "@ultimat3/flags": "22.3.1",
+    "@ultimat3/http": "22.3.1",
+    "@ultimat3/i18n": "22.3.1",
+    "@ultimat3/jobs": "22.3.1",
+    "@ultimat3/mail": "22.3.1",
+    "@ultimat3/manifest": "22.3.1",
+    "@ultimat3/mcp": "22.3.1",
+    "@ultimat3/money": "22.3.1",
+    "@ultimat3/notify": "22.3.1",
+    "@ultimat3/policy": "22.3.1",
+    "@ultimat3/pwa": "22.3.1",
+    "@ultimat3/query": "22.3.1",
+    "@ultimat3/realtime": "22.3.1",
+    "@ultimat3/render": "22.3.1",
+    "@ultimat3/schema": "22.3.1",
+    "@ultimat3/seo": "22.3.1",
+    "@ultimat3/storage": "22.3.1",
+    "@ultimat3/testing": "22.3.1",
+    "@ultimat3/time": "22.3.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/browser-launcher-fake.ts

@@ -26,6 +26,8 @@ export interface FakeShotPage {
   readonly url: string;
   readonly html: string;
   readonly evaluate?: Readonly<Record<string, string>> | undefined;
+  /** The document's HTTP status. Absent is 200 — the page was recorded because it exists. */
+  readonly status?: number | undefined;
 }
 
 /** A PNG signature, and nothing behind it: deterministic bytes, never a render. */
@@ -76,7 +78,8 @@ function fakePage(byUrl: ReadonlyMap<string, FakeShotPage>, init: ShotSessionIni
     network.push({
       method: 'GET',
       url: page.url,
-      status: 200,
+      // Data the page answers with, never a bound — a recorded page exists, so absent is a 200.
+      status: page.status === undefined ? 200 : page.status,
       resourceType: 'document',
       at: init.clock.now().getTime(),
     });

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 [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--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)' },
@@ -15,6 +15,12 @@ export const shotSpec: CommandSpec = {
     { 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: 'expect-status',
+      type: 'string',
+      summary:
+        'the document status this shot is ok with (e.g. 404); absent: any 2xx, else it fails',
+    },
     { name: 'browser', type: 'string', summary: 'Chrome or Chromium binary to launch' },
     {
       name: 'cdp-url',

package/src/cmd-shot.ts

@@ -45,6 +45,7 @@ import { readThemeFlag, themeChoiceExpression } from './shot-theme';
 import type { IslandCount, ShotArtifacts } from './shot-verdict';
 import {
   buildVerdict,
+  documentStatus,
   ISLAND_PROBE,
   parseIslandProbe,
   shotLines,
@@ -218,6 +219,11 @@ export interface ShotRun {
    */
   readonly acceptLanguage?: string | undefined;
   readonly now?: (() => Date) | undefined;
+  /**
+   * `--expect-status`: the document status this shot is ok with — `404` to photograph the not-found
+   * page on purpose. Absent means any 2xx, and anything else fails the verdict with the status.
+   */
+  readonly expectStatus?: number | undefined;
   /**
    * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
    * reads the DOM here, on the one navigation the picture already paid for. `settle` re-runs the
@@ -265,6 +271,9 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       if (choice !== undefined) await page.prepare(choice);
     }
     await page.goto(requestedUrl, { timeout: options.timeoutMs });
+    // Read NOW as well as at capture: the network ring is bounded, and a page that fires a few
+    // hundred requests while it settles evicts the document entry the verdict needs.
+    const landedStatus = documentStatus(page.network(), page.url());
     if (options.settleMs > 0) await Bun.sleep(options.settleMs);
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no
     // JS engine. `null` says so; a `0` would read as "the route renders no islands", which is a
@@ -303,6 +312,8 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       network: page.network(),
       networkDropped: page.networkDropped(),
       islands,
+      landedStatus,
+      ...(options.expectStatus === undefined ? {} : { expectStatus: options.expectStatus }),
     });
     mkdirSync(options.outDir, { recursive: true });
     const image = join(options.outDir, SHOT_IMAGE);
@@ -387,6 +398,11 @@ export const shotCommand: CliCommand = {
     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);
+    // Read only when given: its absence means "any 2xx", which no single default number can say.
+    const expectStatus =
+      flagString(ctx.args, 'expect-status') === undefined
+        ? undefined
+        : intFlag(ctx.args, 'expect-status', 100, 200, 599);
     // 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
@@ -427,6 +443,7 @@ export const shotCommand: CliCommand = {
       timeoutMs,
       fullPage: flagBool(ctx.args, 'full'),
       extraHosts: flagString(ctx.args, 'allow-hosts'),
+      ...(expectStatus === undefined ? {} : { expectStatus }),
     };
     if (matrix) {
       // `--locale` and `--theme` narrow the matrix to one value of their axis.

package/src/messages.ts

@@ -189,6 +189,12 @@ const CATALOG = {
   'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
   'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
   'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
+  // After the redirect and before everything else: a 404 page can be spotless, and a picture of
+  // "Not found" read as the route is the capture lying about its subject.
+  'cli.shot.status':
+    '{route} answered HTTP {status}, expected {expected} — the picture is that response, not the page',
+  'cli.shot.document': '  document HTTP {status}',
+  'cli.shot.documentUnknown': '  document status not seen — the driver recorded no response for it',
   'cli.shot.server.booted': '  server   booted for this shot on {url}',
   'cli.shot.server.reused': '  server   the x dev already running on {url}',
   'cli.shot.canvas': '  canvas   {width}x{height}',

package/src/shot-verdict.ts

@@ -25,6 +25,9 @@ export const SHOT_MESSAGE_KEYS = [
   'cli.shot.ok',
   'cli.shot.errors',
   'cli.shot.redirected',
+  'cli.shot.status',
+  'cli.shot.document',
+  'cli.shot.documentUnknown',
   'cli.shot.picture',
   'cli.shot.verdict',
   'cli.shot.server.booted',
@@ -146,6 +149,13 @@ export interface ShotInput {
   readonly networkDropped: number;
   /** `null` when the probe could not run or did not parse. Never a zero standing in for unknown. */
   readonly islands: IslandCount | null;
+  /**
+   * The document's status as read right after navigation. Only a fallback: the network ring is
+   * bounded, so on a page of a few hundred requests the document entry may be gone by capture time.
+   */
+  readonly landedStatus?: number | null | undefined;
+  /** `--expect-status`: the one status this shot is ok with. Absent means any 2xx. */
+  readonly expectStatus?: number | undefined;
 }
 
 export interface ShotVerdict extends ShotInput {
@@ -161,10 +171,44 @@ export interface ShotVerdict extends ShotInput {
    * gating, like a console warning: a missing favicon would otherwise fail every shot of every app.
    */
   readonly failed: number;
+  /**
+   * The HTTP status of the document photographed. `null` when no driver response carried one —
+   * "not seen" never gates, like an uncounted island, and is never reported as a 200.
+   */
+  readonly status: number | null;
+  /** The status asked for with `--expect-status`, or `null` for "any 2xx". */
+  readonly expectedStatus: number | null;
   /** What this verdict cannot see, stated every time — a `0` whose blind spots are named. */
   readonly blind: readonly string[];
 }
 
+const withoutFragment = (url: string): string => {
+  const hash = url.indexOf('#');
+  return hash === -1 ? url : url.slice(0, hash);
+};
+
+/**
+ * The status of the LAST document response at `url` — the last, because a reload or a redirect
+ * back re-requests it and the picture is of the latest. The fragment is dropped: `location.href`
+ * keeps it and no request ever carries one.
+ */
+export function documentStatus(network: readonly NetworkEntry[], url: string): number | null {
+  const target = withoutFragment(url);
+  for (let index = network.length - 1; index >= 0; index -= 1) {
+    const entry = network[index];
+    if (entry === undefined || entry.resourceType !== 'document') continue;
+    if (withoutFragment(entry.url) !== target) continue;
+    if (entry.status !== undefined) return entry.status;
+  }
+  return null;
+}
+
+/** ok for a status: the one expected, or any 2xx when none was. Unseen is not a failure. */
+const statusOk = (status: number | null, expected: number | null): boolean => {
+  if (expected !== null) return status === expected;
+  return status === null || (status >= 200 && status < 300);
+};
+
 /**
  * What a shot is blind to, each naming the mechanism rather than apologising. Constant because
  * these are properties of the browser port, not of a run — and in the artifact because `errors: 0`
@@ -183,7 +227,7 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
   lines.filter((line) => line.level === level).length;
 
 /**
- * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * `ok` is five conditions, and every one is something a picture cannot show: nothing on the page
  * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
  * the route that was asked for.
  *
@@ -195,16 +239,23 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
  * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
  * A redirect is a failure of the CAPTURE rather than of the app: an agent that
  * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
+ * A fifth (`As of 2026-09-26`): the document answered 2xx, or exactly `--expect-status`. A 404
+ * page is clean by every other clause, and `x shot /typo` reported it ok.
  */
 export function buildVerdict(input: ShotInput): ShotVerdict {
   const errors = levelCount(input.console, 'error');
+  const status = documentStatus(input.network, input.finalUrl) ?? input.landedStatus ?? null;
+  const expectedStatus = input.expectStatus ?? null;
   return {
     ...input,
     ok:
       errors === 0 &&
       input.pageErrors.length === 0 &&
       (input.islands?.failed ?? 0) === 0 &&
-      input.requestedUrl === input.finalUrl,
+      input.requestedUrl === input.finalUrl &&
+      statusOk(status, expectedStatus),
+    status,
+    expectedStatus,
     redirected: input.requestedUrl !== input.finalUrl,
     errors,
     warnings: levelCount(input.console, 'warn'),
@@ -241,6 +292,8 @@ export function verdictJson(verdict: ShotVerdict): JsonValue {
     requestedUrl: verdict.requestedUrl,
     finalUrl: verdict.finalUrl,
     redirected: verdict.redirected,
+    status: verdict.status,
+    expectedStatus: verdict.expectedStatus,
     server: verdict.server,
     capturedAt: verdict.capturedAt,
     screenshot: verdict.screenshot,
@@ -301,6 +354,9 @@ export function shotLines(artifacts: ShotArtifacts): readonly string[] {
   const canvas = verdict.canvas;
   return [
     msg(`cli.shot.server.${verdict.server}`, { url: verdict.finalUrl }),
+    verdict.status === null
+      ? msg('cli.shot.documentUnknown')
+      : msg('cli.shot.document', { status: verdict.status }),
     canvas === null
       ? msg('cli.shot.canvasUnreadable', { bytes: verdict.bytes.byteLength })
       : msg('cli.shot.canvas', { width: canvas.width, height: canvas.height }),
@@ -338,6 +394,13 @@ export const shotSummary = (verdict: ShotVerdict): string => {
   if (verdict.redirected) {
     return msg('cli.shot.redirected', { route: verdict.route, url: verdict.finalUrl });
   }
+  if (!statusOk(verdict.status, verdict.expectedStatus)) {
+    return msg('cli.shot.status', {
+      route: verdict.route,
+      status: verdict.status ?? 'unseen',
+      expected: verdict.expectedStatus ?? '2xx',
+    });
+  }
   // Ahead of the console count, because a throw is the more severe fact AND the quieter one: an
   // island that died can log nothing at all, so `errors` would report a clean page.
   if (verdict.pageErrors.length > 0) {

package/src/test-workers.ts

@@ -90,6 +90,19 @@ export const defaultWorkers = (
   return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
 };
 
+/**
+ * The width for a parallel suite that SHARES the machine — `x verify` runs the static steps beside
+ * `live`, `job`, `e2e` and `eval` (`verify-run.ts`), and each of those scans is a CPU-bound process
+ * of its own. `defaultWorkers()`' oversubscription fills a worker's own stalls when nothing else
+ * wants the cores; beside six other processes it only multiplies the contention. Measured on
+ * notificado.co, 8 vCPU (#537): at 1.5x, `errors` went 1.8s alone → 7.9s in the gate and
+ * `boundaries` 2.3s → 9.7s. So: one worker per core, still held to what memory can carry.
+ */
+export const sharedWorkers = (
+  available: number = availableCpus(),
+  freeBytes: number = availableMemory(),
+): number => Math.min(defaultWorkers(available, freeBytes), Math.max(WORKER_FLOOR, available));
+
 /**
  * Which types run across worker processes, and why the other two cannot.
  *

package/src/verify-run.ts

@@ -5,6 +5,7 @@
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
+import { sharedWorkers } from './test-workers';
 import {
   floorRequires,
   readVerifyFloor,
@@ -40,6 +41,10 @@ export async function runVerify(
     await pending;
     pending = undefined;
   };
+  // A parallel suite inside that window shares the cores with the static group, so its DEFAULT
+  // width is one per core (`sharedWorkers`); an explicit `--workers` is the caller's and stands.
+  const shared: VerifyContext =
+    ctx.workers === undefined && beside.length > 0 ? { ...ctx, workers: sharedWorkers() } : ctx;
   for (const step of selected) {
     if (beside.includes(step)) continue;
     if (step.name === SERIAL_SUITES[0]) {
@@ -51,7 +56,8 @@ export async function runVerify(
     } else if (!SERIAL_SUITES.includes(step.name)) {
       await join();
     }
-    byName.set(step.name, await runStep(step, ctx, floor));
+    const inWindow = pending !== undefined && SERIAL_SUITES.includes(step.name);
+    byName.set(step.name, await runStep(step, inWindow ? shared : ctx, floor));
   }
   await join();
   // Reported in the declared order, whatever order the steps finished in: the table, `--json` and