@ultimat3/cli 29.3.2 → 30.0.0

package/src/client-errors-script.ts

@@ -0,0 +1,74 @@
+// Single responsibility: the browser half of client error reporting — the text of
+// `/x-client-errors.js`. Two window listeners, one observer on the island failure marker, the caps,
+// and a same-origin `fetch`. Generated as a string so `hydrate.ts` pays no byte for an app that
+// has the feature off; the route that receives it is `client-errors-routes.ts`.
+
+import { CLIENT_BUILD_META } from '@ultimat3/core';
+import { ISLAND_FAILED_ATTRIBUTE, NAVIGATED_EVENT } from '@ultimat3/render';
+
+/** Named by every `app/` document of an app that turned `clientErrors.enabled` on. */
+export const CLIENT_ERRORS_SCRIPT_PATH = '/x-client-errors.js';
+
+/** Where a report is POSTed. Beside `/_storage`: a framework route no page can shadow. */
+export const CLIENT_ERRORS_PATH = '/_client-errors';
+
+/** Reports one document may send. A loop that throws per frame costs five requests, not 60/s. */
+export const CLIENT_ERRORS_MAX_REPORTS = 5;
+
+/** Per-field caps, shared by the sender (which cuts) and the route (which refuses past them). */
+export const CLIENT_ERRORS_LIMITS = Object.freeze({
+  message: 1_000,
+  stack: 8_000,
+  path: 2_048,
+  island: 128,
+  build: 128,
+});
+
+/**
+ * The script. Rules it keeps, each one a line below:
+ * - an `error` counts only when its `filename` is on this origin, which drops an extension's, a
+ *   CDN's and the opaque `Script error.` a cross-origin script raises; a `Script error.` with no
+ *   stack is dropped wherever it claims to come from;
+ * - a rejection whose stack names only other origins is someone else's;
+ * - an island whose `mount()` rejected never reaches `unhandledrejection` (the hydration runtime
+ *   catches it), so the `data-x-failed` marker is watched instead, including one set before this
+ *   script ran;
+ * - at most five per document and one per distinct message, the path with no query string, the
+ *   build id the DOCUMENT was rendered by (`data-build` on this script's own tag), and `fetch`
+ *   with `keepalive` so a report survives the tab closing;
+ * - every cap is per DOCUMENT: the client router runs this script once per tab and swaps pages
+ *   under it, so `NAVIGATED_EVENT` resets the count and the dedupe and rescans the new body; the
+ *   dedupe key carries the path; the build is read at send time from the swapped-in
+ *   `x-ultimate-build` meta (the tag's `data-build` when there is none); an island ELEMENT is
+ *   reported once, so one the router carried across (`data-x-persist`) is not re-reported;
+ * - it never throws and never reports itself: every listener is wrapped, the rejection of its
+ *   own `fetch` is handled, and a failure raised while sending is not re-entered.
+ */
+export function clientErrorsScript(): string {
+  const limits = CLIENT_ERRORS_LIMITS;
+  return `(function(){try{
+var d=document,o=location.origin,n=0,seen={},busy=0,A='${ISLAND_FAILED_ATTRIBUTE}';
+var s=d.currentScript,b0=s&&s.getAttribute('data-build')||'';
+function build(){var m=d.querySelector&&d.querySelector('meta[name="${CLIENT_BUILD_META}"]');return m&&m.getAttribute('content')||b0}
+function cut(v,m){return typeof v==='string'?v.slice(0,m):''}
+function send(k,m,st,i){if(busy||n>=${CLIENT_ERRORS_MAX_REPORTS})return;busy=1;try{
+m=cut(m,${limits.message});var key=location.pathname+'|'+k+'|'+(i||'')+'|'+m;if(seen[key])return;seen[key]=1;n++;
+var body={kind:k,message:m,path:cut(location.pathname,${limits.path}),build:cut(build(),${limits.build})};
+st=cut(st,${limits.stack});if(st)body.stack=st;if(i)body.island=cut(i,${limits.island});
+var p=fetch('${CLIENT_ERRORS_PATH}',{method:'POST',keepalive:true,credentials:'same-origin',
+headers:{'content-type':'application/json'},body:JSON.stringify(body)});
+if(p&&typeof p.then==='function')p.then(null,function(){})}catch(x){}finally{busy=0}}
+window.addEventListener('error',function(e){try{var f=e&&e.filename;
+if(typeof f!=='string'||f.indexOf(o+'/')!==0)return;var st=e.error&&e.error.stack;
+if(e.message==='Script error.'&&!st)return;send('error',e.message,st)}catch(x){}});
+window.addEventListener('unhandledrejection',function(e){try{var r=e&&e.reason;
+var st=r&&typeof r.stack==='string'?r.stack:'';if(st&&st.indexOf(o+'/')<0)return;
+send('rejection',r&&typeof r.message==='string'?r.message:String(r),st)}catch(x){}});
+function isl(el){if(el&&el.getAttribute&&!el.__xr&&el.getAttribute(A)!==null){el.__xr=1;send('island',el.getAttribute(A),'',el.getAttribute('data-x-island'))}}
+if(typeof MutationObserver==='function')new MutationObserver(function(ms){for(var i=0;i<ms.length;i++){try{isl(ms[i].target)}catch(x){}}})
+.observe(d.documentElement,{subtree:true,attributes:true,attributeFilter:[A]});
+function scan(){var f=d.querySelectorAll('['+A+']');for(var j=0;j<f.length;j++)isl(f[j])}scan();
+d.addEventListener('${NAVIGATED_EVENT}',function(){try{n=0;seen={};scan()}catch(x){}});
+}catch(x){}})();
+`;
+}

package/src/client-vitals-route.ts

@@ -0,0 +1,197 @@
+// Single responsibility: the server half of real-user timings — `GET /x-client-vitals.js` and
+// `POST /_client-vitals`, which turns one beacon into histogram samples labelled by route PATTERN
+// and metric. Anonymous, stored nowhere but the metric: no actor, no path, no row. A framework
+// route like `/_client-errors`, never an action: it must not appear in OpenAPI or as an MCP tool.
+
+import type { ClientVitalsConfig, ClientVitalsSurface } from '@ultimat3/core';
+import { histogram, isJsonObject, proveSameOrigin, readWithinLimit } from '@ultimat3/core';
+import type { RequestContext, Route, UltimateRequest } from '@ultimat3/http';
+import { NO_STORE, selfOrigin } from '@ultimat3/http';
+import { routeEntries } from '@ultimat3/render';
+import type { ClientErrorPage } from './client-errors-routes';
+import {
+  CLIENT_VITAL_NAMES,
+  CLIENT_VITALS_PATH,
+  CLIENT_VITALS_SCRIPT_PATH,
+  type ClientVitalName,
+  clientVitalsHead,
+  clientVitalsScript,
+} from './client-vitals-script';
+import { revalidatedResponse } from './revalidated-response';
+
+/** A beacon is one path and five numbers; 4 KiB is that with room, and nothing more. */
+export const CLIENT_VITALS_MAX_BODY_BYTES = 4 * 1024;
+
+/** One beacon per page view: sixty a minute per address is a reader opening a page a second. */
+export const CLIENT_VITALS_PER_MINUTE = 60;
+
+/** A timing past a minute is a backgrounded tab's clock, not what a user waited for. */
+const MAX_MS = 60_000;
+/** CLS is unitless; real pages sit under 1, and a value past 10 is a measurement gone wrong. */
+const MAX_CLS = 10;
+
+/** A path, never a URL and never a query: the same screen `/_client-errors` applies. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the class REFUSES them, by design.
+const PATH = /^\/[^?#\s\x00-\x1f\x7f]{0,2047}$/;
+
+const NAMES: ReadonlySet<string> = new Set(CLIENT_VITAL_NAMES);
+const isVitalName = (name: string): name is ClientVitalName => NAMES.has(name);
+
+/**
+ * Two instruments, declared once. Labels are `route` (a pattern from the route table) and `metric`
+ * (one of four), so the series count is the page count times four, whatever the traffic sends.
+ */
+const seconds = histogram('web_vital_seconds', {
+  unit: 's',
+  description: 'Real-user page timings (LCP, FCP, INP, TTFB), by route pattern and metric',
+  bounds: [0.05, 0.1, 0.2, 0.3, 0.5, 0.8, 1, 1.8, 2.5, 3, 4, 6, 10, 20, 60],
+});
+const shift = histogram('web_vital_cls', {
+  unit: '1',
+  description: 'Real-user cumulative layout shift, by route pattern',
+  bounds: [0.01, 0.05, 0.1, 0.15, 0.25, 0.5, 1, 2],
+});
+
+export interface ClientVitalsRouteOptions {
+  readonly pages?: () => readonly ClientErrorPage[];
+}
+
+/** The most specific page on a listed surface the path names — its PATTERN, else nothing. */
+function patternOf(
+  pages: readonly ClientErrorPage[],
+  surfaces: readonly ClientVitalsSurface[],
+  path: string,
+): string | undefined {
+  let best: ClientErrorPage | undefined;
+  for (const page of pages) {
+    if (!surfaces.some((surface) => surface === page.surface)) continue;
+    if (!page.pattern.regex.test(path)) continue;
+    if (best === undefined || page.pattern.specificity > best.pattern.specificity) best = page;
+  }
+  return best?.path;
+}
+
+/** Same-origin evidence, or the beacon is dropped: a cross-site page must not skew the numbers. */
+function sameOrigin(request: UltimateRequest, ctx: RequestContext): boolean {
+  return proveSameOrigin({
+    selfOrigins: [selfOrigin(ctx.url, ctx.https)],
+    origin: request.header('origin'),
+    secFetchSite: request.header('sec-fetch-site') || null,
+    listed: () => false,
+    listName: "the app's own origin",
+  }).ok;
+}
+
+/** The beacon's `{ path, vitals }`, or `undefined` — never a reason: a probe learns nothing. */
+async function beaconOf(request: UltimateRequest) {
+  const read = await readWithinLimit(request.raw.body, CLIENT_VITALS_MAX_BODY_BYTES);
+  if ('over' in read) return undefined;
+  let body: unknown;
+  try {
+    body = JSON.parse(new TextDecoder().decode(read.bytes));
+  } catch {
+    return undefined;
+  }
+  if (!isJsonObject(body) || typeof body['path'] !== 'string') return undefined;
+  const vitals = body['vitals'];
+  if (!isJsonObject(vitals) || !PATH.test(body['path'])) return undefined;
+  return { path: body['path'], vitals };
+}
+
+/** Records every known, in-range timing; drops the rest one by one. */
+function record(route: string, vitals: Readonly<Record<string, unknown>>): void {
+  for (const [name, value] of Object.entries(vitals)) {
+    if (!isVitalName(name) || typeof value !== 'number' || !Number.isFinite(value)) continue;
+    if (value < 0) continue;
+    if (name === 'cls') {
+      if (value <= MAX_CLS) shift.record(value, { route });
+    } else if (value <= MAX_MS) {
+      seconds.record(value / 1000, { route, metric: name });
+    }
+  }
+}
+
+export function clientVitalsRoutes(
+  config: ClientVitalsConfig,
+  options: ClientVitalsRouteOptions = {},
+): readonly Route[] {
+  const pages = options.pages ?? routeEntries;
+  const source = clientVitalsScript(config.sampleRate);
+  const answered = (): Response => new Response(null, { status: 204 });
+  return [
+    {
+      method: 'GET',
+      path: CLIENT_VITALS_SCRIPT_PATH,
+      meta: { name: 'clientVitals.script', auth: 'public' },
+      // Revalidated, as `/x-client-errors.js` is: a changed rate reaches a returning tab.
+      handler: (request) => revalidatedResponse(request, source, 'text/javascript; charset=utf-8'),
+    },
+    {
+      method: 'POST',
+      path: CLIENT_VITALS_PATH,
+      meta: {
+        name: 'clientVitals.beacon',
+        // Anonymous by design: a timing names no one, so no sign-in stands in front of it.
+        auth: 'public',
+        cache: NO_STORE,
+        // Per address, on the app's own rate-limit store — the stage `/_client-errors` uses.
+        rateLimit: 'clientVitals.beacon',
+        rateLimitBucket: {
+          capacity: CLIENT_VITALS_PER_MINUTE,
+          refillPerSecond: CLIENT_VITALS_PER_MINUTE / 60,
+        },
+      },
+      // Every outcome is the same 204: a refusal that said why would teach a probe the shape.
+      handler: async (request, ctx) => {
+        if (!sameOrigin(request, ctx)) return answered();
+        const beacon = await beaconOf(request);
+        if (beacon === undefined) return answered();
+        const route = patternOf(pages(), config.surfaces, beacon.path);
+        if (route !== undefined) record(route, beacon.vitals);
+        return answered();
+      },
+    },
+  ];
+}
+
+export interface ClientVitalsSurfaceMount {
+  readonly routes: readonly Route[];
+  /** For `DocumentOptions.appHead`, `''` when `app` is not listed. */
+  readonly appHead: string;
+  /** For the `site/` document head, `''` unless `site` is listed — the static path opts in. */
+  readonly siteHead: string;
+}
+
+/** What a boot mounts for `clientErrors.vitals`: nothing at all unless enabled. */
+export function clientVitalsSurface(
+  config: ClientVitalsConfig | undefined,
+  options: ClientVitalsRouteOptions = {},
+): ClientVitalsSurfaceMount | undefined {
+  if (config?.enabled !== true) return undefined;
+  const head = (surface: ClientVitalsSurface): string =>
+    config.surfaces.includes(surface) ? clientVitalsHead() : '';
+  return {
+    routes: clientVitalsRoutes(config, options),
+    appHead: head('app'),
+    siteHead: head('site'),
+  };
+}
+
+/**
+ * The document heads the browser scripts compose into — for `DocumentOptions`, spread. The one
+ * place `x dev` and the container combine them, so the two cannot name different scripts. A key
+ * is absent rather than `''` when nothing rides it. `zone` (`time.detect`, `zone-boot.ts`) is an
+ * `app/` tag only: a `site/` page is a file, and a file cannot answer in the visitor's zone.
+ */
+export function clientScriptHeads(
+  errors: { readonly head: string } | undefined,
+  vitals: ClientVitalsSurfaceMount | undefined,
+  zone?: { readonly head: string } | undefined,
+): { readonly appHead?: string; readonly siteHead?: string } {
+  const appHead = (zone?.head ?? '') + (errors?.head ?? '') + (vitals?.appHead ?? '');
+  const siteHead = vitals?.siteHead ?? '';
+  return {
+    ...(appHead === '' ? {} : { appHead }),
+    ...(siteHead === '' ? {} : { siteHead }),
+  };
+}

package/src/client-vitals-script.ts

@@ -0,0 +1,56 @@
+// Single responsibility: the browser half of real-user timings — the text of `/x-client-vitals.js`.
+// `PerformanceObserver` for LCP, CLS, INP and FCP, the navigation entry for TTFB, and ONE
+// `sendBeacon` when the page is hidden. Generated as a string so a document with the feature off
+// carries no byte of it; the route that receives the beacon is `client-vitals-route.ts`.
+
+import { finiteOption } from '@ultimat3/core';
+
+/** Named by every document on a surface `clientErrors.vitals.surfaces` lists. */
+export const CLIENT_VITALS_SCRIPT_PATH = '/x-client-vitals.js';
+
+/** Where the beacon lands. Beside `/_client-errors`: a framework route no page can shadow. */
+export const CLIENT_VITALS_PATH = '/_client-vitals';
+
+/** The timings a beacon may carry. CLOSED: the route drops any other name. */
+export const CLIENT_VITAL_NAMES = ['lcp', 'fcp', 'inp', 'ttfb', 'cls'] as const;
+
+export type ClientVitalName = (typeof CLIENT_VITAL_NAMES)[number];
+
+/**
+ * The script. Rules it keeps, each one a line below:
+ * - sampled ONCE per page view, here, against `rate`: a page view that rolled out observes nothing;
+ * - every timing is milliseconds from navigation start; CLS is the largest session window (gaps
+ *   under 1 s, windows capped at 5 s), counting no shift that followed input; INP is the slowest
+ *   interaction the view saw, which is the metric's own reading under 50 interactions;
+ * - one beacon per page view, on the first `visibilitychange` to hidden (or `pagehide`), naming the
+ *   path the view LOADED at — the client router swaps the path under a tab, and a timing taken on
+ *   one page must not be filed under the next;
+ * - a `text/plain` blob: `sendBeacon` with a JSON content type is a preflighted request some
+ *   browsers drop silently, and the route parses the body whatever it was labelled;
+ * - it never throws: an observer type this browser lacks is skipped, and every callback is wrapped.
+ */
+export function clientVitalsScript(sampleRate: number): string {
+  // Interpolated into script text: a number `config.ts` already screened, screened again here
+  // because a `NaN` would print as an identifier and sample every view or none.
+  const rate = finiteOption('clientVitalsScript', 'sampleRate', sampleRate);
+  return `(function(){try{
+if(!(Math.random()<${rate})||typeof PerformanceObserver!=='function')return;
+var v={},p=location.pathname,sent=0,cs=0,cw=0,cf=0,cl=0;
+function ob(t,f,o){try{new PerformanceObserver(function(l){try{l.getEntries().forEach(f)}catch(x){}}).observe(o||{type:t,buffered:true})}catch(x){}}
+ob('largest-contentful-paint',function(e){v.lcp=e.startTime});
+ob('paint',function(e){if(e.name==='first-contentful-paint')v.fcp=e.startTime});
+ob('event',function(e){if(e.interactionId&&(!(v.inp>=e.duration)))v.inp=e.duration},{type:'event',buffered:true,durationThreshold:16});
+ob('layout-shift',function(e){if(e.hadRecentInput)return;var t=e.startTime;
+if(cw&&t-cl<1000&&t-cf<5000){cw+=e.value}else{cw=e.value;cf=t}cl=t;if(cw>cs)cs=cw;v.cls=cs});
+try{var n=performance.getEntriesByType('navigation')[0];if(n&&n.responseStart>0)v.ttfb=n.responseStart}catch(x){}
+function send(){try{if(sent)return;sent=1;
+if(navigator.sendBeacon)navigator.sendBeacon('${CLIENT_VITALS_PATH}',new Blob([JSON.stringify({path:p,vitals:v})],{type:'text/plain'}))}catch(x){}}
+document.addEventListener('visibilitychange',function(){if(document.visibilityState==='hidden')send()});
+addEventListener('pagehide',send);
+}catch(x){}})();
+`;
+}
+
+/** The tag a document on a listed surface carries. */
+export const clientVitalsHead = (): string =>
+  `<script src="${CLIENT_VITALS_SCRIPT_PATH}" defer></script>`;

package/src/cmd-affected.ts

@@ -7,6 +7,7 @@
 // `workspace-graph.ts` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
 
 import { affectedScope } from './affected';
+import { appTestScope } from './affected-tests';
 import { affectedSpec } from './cmd-affected-spec';
 import type { CliCommand, CommandContext } from './command';
 import { msg } from './messages';
@@ -31,6 +32,8 @@ export const AFFECTED_MESSAGE_KEYS = [
   'cli.affected.rootWide',
   'cli.affected.dirty',
   'cli.test.affected.none',
+  'cli.affected.tests',
+  'cli.affected.testsAll',
 ] as const;
 
 export const affectedCommand: CliCommand = {
@@ -46,6 +49,7 @@ export const affectedCommand: CliCommand = {
       command: 'affected',
     });
     const params = { base: selection.base, changed: plan.changed.length };
+    const tests = await appTestScope(ctx.cwd, root, plan.changed);
     const table = renderTable(
       HEADER,
       plan.workspaces.map((workspace) => [workspace.name, workspace.dir]),
@@ -62,6 +66,16 @@ export const affectedCommand: CliCommand = {
         dir: workspace.dir,
       })),
       paths: plan.workspaces.map((workspace) => workspace.dir),
+      ...(tests === undefined
+        ? {}
+        : {
+            tests: {
+              app: tests.app,
+              all: tests.all,
+              forcing: [...tests.forcing],
+              files: [...tests.tests],
+            },
+          }),
     };
     return {
       // An empty answer is a fact, not a failure: a `.md`-only diff genuinely re-checks nothing,
@@ -76,6 +90,15 @@ export const affectedCommand: CliCommand = {
           : msg('cli.affected.count', { ...params, count: plan.workspaces.length }),
       lines: [
         ...(selection.dirty ? [msg('cli.affected.dirty')] : []),
+        ...(tests === undefined
+          ? []
+          : [
+              tests.all
+                ? msg('cli.affected.testsAll', {
+                    files: `${tests.forcing.slice(0, 3).join(', ')}${tests.forcing.length > 3 ? ` (+${tests.forcing.length - 3})` : ''}`,
+                  })
+                : msg('cli.affected.tests', { count: tests.tests.length }),
+            ]),
         ...(plan.rootWide.length === 0
           ? []
           : [msg('cli.affected.rootWide', { files: plan.rootWide.join(', ') })]),

package/src/cmd-build-spec.ts

@@ -8,7 +8,7 @@ export const buildSpec: CommandSpec = {
   summary:
     'build a container image, a single binary, a prerendered static site, or the store an image boots from',
   usage:
-    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--platform bun-target] [--no-preflight] [--json]',
+    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--platform bun-target] [--no-preflight] [--no-capture] [--json]',
   requiresApp: true,
   flags: [
     {
@@ -32,5 +32,11 @@ export const buildSpec: CommandSpec = {
       summary:
         '--no-preflight skips the six static gate steps (typecheck, lint, boundaries, filesize, package-shape, errors) — only when `x verify` runs right after, as in `x build --no-preflight && x verify`',
     },
+    {
+      name: 'capture',
+      type: 'boolean',
+      summary:
+        "static target only: --no-capture stamps every og.capture card's og:image tags and photographs none, so no browser is needed — what `x verify`'s own build passes; a deployable build takes the pictures",
+    },
   ],
 };

package/src/cmd-build.ts

@@ -6,7 +6,9 @@ import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, frameworkVersion, UltimateError, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
+import { BUILD_CAPTURE_ENV } from './build-capture-env';
 import { buildSpec } from './cmd-build-spec';
+import { DEFAULT_IMAGE } from './cmd-deploy-compose';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
@@ -199,8 +201,19 @@ export function binaryArgs(
   ];
 }
 
+/** The module `staticArgs` preloads: the render loader, ahead of the script's whole graph. */
+export const PRERENDER_PRELOAD = join(import.meta.dir, 'prerender-preload.ts');
+
 export function staticArgs(root: string, out: string): readonly string[] {
-  return ['bun', 'run', join(root, BUILD_ENTRY.static), '--out', out];
+  return [
+    'bun',
+    'run',
+    '--preload',
+    PRERENDER_PRELOAD,
+    join(root, BUILD_ENTRY.static),
+    '--out',
+    out,
+  ];
 }
 
 export function argsFor(
@@ -264,7 +277,14 @@ export function buildResult(input: {
           {
             code: 'X_BUILD_FAILED',
             cause: `${input.command.join(' ')} exited ${result.code}`,
-            fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
+            // Static is the build `x verify`'s budgets step runs (plan 101, 21): `x verify` would be
+            // the loop the reader came from, and this command's `data.output` is the builder's own.
+            fix:
+              target === 'docker'
+                ? 'x doctor --json && docker info'
+                : target === 'static'
+                  ? 'x build --target static --json'
+                  : 'x verify --json',
             docs: ERROR_DOCS_URL,
           },
         ],
@@ -285,7 +305,7 @@ export function buildResult(input: {
 }
 
 /** The flags only some targets read. */
-const TARGET_SCOPED_FLAGS = ['tag', 'out', 'platform', 'preflight'] as const;
+const TARGET_SCOPED_FLAGS = ['tag', 'out', 'platform', 'preflight', 'capture'] as const;
 
 type TargetScopedFlag = (typeof TARGET_SCOPED_FLAGS)[number];
 
@@ -293,7 +313,7 @@ type TargetScopedFlag = (typeof TARGET_SCOPED_FLAGS)[number];
 const TARGET_FLAGS: ReadonlyMap<BuildTarget, readonly TargetScopedFlag[]> = new Map([
   ['docker', ['tag', 'preflight']],
   ['binary', ['out', 'platform', 'preflight']],
-  ['static', ['out', 'preflight']],
+  ['static', ['out', 'preflight', 'capture']],
   // The boot reads ONE place, and the image holds no devDependencies to run a gate with.
   ['prebuilt', []],
 ]);
@@ -304,6 +324,7 @@ const UNREAD_BECAUSE: Readonly<Record<TargetScopedFlag, string>> = {
   out: 'the docker target writes an image, not a path',
   platform: 'only the binary target compiles an executable for a platform',
   preflight: 'the prebuilt target runs no gate: `x verify` ran before `docker build` was called',
+  capture: 'only the static target photographs social cards',
 };
 
 /**
@@ -377,9 +398,9 @@ export const buildCommand: CliCommand = {
     const platform = readPlatform(flagString(ctx.args, 'platform'));
     if (target === 'prebuilt') return buildPrebuilt(root);
 
-    // Run static verify steps before building — unless the caller is a gate that runs the same
-    // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the
-    // preflight was the same ~17 s of typecheck/lint/scans paid twice per run. The default stays
+    // Run static verify steps before building — unless the caller is the gate itself, which has
+    // run those six steps already (`x verify`'s budgets step spawns `x build --no-preflight`), where
+    // the preflight was the same ~17 s of typecheck/lint/scans paid twice per run. The default stays
     // safe: a bare `x build` never ships an artifact from a tree that does not typecheck.
     const preflight = ctx.args.flags.get('preflight') !== false;
     if (preflight) {
@@ -405,7 +426,7 @@ export const buildCommand: CliCommand = {
         ? join(root, '.x', target === 'static' ? 'static' : 'app')
         : resolve(ctx.cwd, outFlag);
     const out = target === 'binary' ? binaryOutfile(requested, platform) : requested;
-    const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
+    const tag = flagString(ctx.args, 'tag') ?? DEFAULT_IMAGE;
     // The docker target stamps the manifest's build id into the image, so no role derives one at
     // boot. The island chunks and stylesheets are the image build's own (`--target prebuilt`).
     const buildId =
@@ -420,7 +441,12 @@ export const buildCommand: CliCommand = {
     // Removed BEFORE the builder runs, so a build that writes no inventory can never be reported
     // with the last one's: a stale emitted list is worse than none, because it reads as this run's.
     if (target === 'static') await removeStaticReport(root);
-    const result = await ctx.runner(command, { cwd: root });
+    // `--no-capture` reaches the app's own `prerender.ts` through the env (`build-capture-env.ts`).
+    const capture = ctx.args.flags.get('capture') !== false;
+    const result = await ctx.runner(command, {
+      cwd: root,
+      ...(capture ? {} : { env: { [BUILD_CAPTURE_ENV]: 'off' } }),
+    });
     // `prerenderSite` writes it; an app whose `apps/web/prerender.ts` does not call that writes no
     // `.x/build-stats.json` either, and `x verify`'s `budgets` step already reds that app with
     // `X_BUDGET_UNMEASURED` — so the absence needs no second code here.

package/src/cmd-ci-spec.ts

@@ -12,30 +12,66 @@ export const TAIL_LINES = 40;
  */
 export const CI_EVENTS = ['push', 'pull_request', 'workflow_dispatch'] as const;
 
+/** `runs` is the triage `x ci` has always been; `tested` asks whether a push may reuse a PR run. */
+export const CI_SUBCOMMANDS = ['runs', 'tested'] as const;
+
+/** How old the green PR run `tested` reuses may be: the runner image and the registry move. */
+export const TESTED_MAX_AGE = '24h';
+
+/** The workflow file whose run `tested` reads, when `--workflow` names none. */
+export const TESTED_WORKFLOW = 'ci.yml';
+
 export const ciSpec: CommandSpec = {
   name: 'ci',
-  summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
+  summary:
+    'the workflow runs for this branch and the findings inside the failed steps log; tested: whether a push reuses a green PR run',
   usage:
-    'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--workflow <name>] [--event <push|pull_request|workflow_dispatch>] [--json]',
+    'x ci [runs] [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--workflow <name>] [--event <push|pull_request|workflow_dispatch>] [--json] · x ci tested [--max-age 24h] [--repo owner/name] [--workflow ci.yml] [--json]',
+  subcommands: CI_SUBCOMMANDS,
+  // The bare `x ci` is the triage it always was; `tested` is asked for by name.
+  defaultSubcommand: 'runs',
   flags: [
     { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
-    { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
-    { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
+    {
+      name: 'branch',
+      type: 'string',
+      summary: 'branch to read runs for; this one by default',
+      subcommands: ['runs'],
+    },
+    {
+      name: 'run',
+      type: 'string',
+      summary: 'one run id, instead of this branch latest',
+      subcommands: ['runs'],
+    },
     {
       name: 'tail',
       type: 'string',
       summary: `log lines kept per failed job (default ${TAIL_LINES})`,
+      subcommands: ['runs'],
+    },
+    {
+      name: 'full',
+      type: 'boolean',
+      summary: 'the whole failed-step log, not the tail',
+      subcommands: ['runs'],
     },
-    { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
     {
       name: 'workflow',
       type: 'string',
-      summary: 'only this workflow name or filename (e.g. ci.yml)',
+      summary: `the workflow name or filename to read (e.g. ci.yml); for tested, the one whose run counts (default ${TESTED_WORKFLOW})`,
     },
     {
       name: 'event',
       type: 'string',
       summary: 'only runs of this event (push, pull_request, workflow_dispatch)',
+      subcommands: ['runs'],
+    },
+    {
+      name: 'max-age',
+      type: 'string',
+      summary: `tested: the oldest PR run still reused (default ${TESTED_MAX_AGE})`,
+      subcommands: ['tested'],
     },
   ],
 };