@ultimat3/cli 29.4.0 → 30.1.0

package/src/upgrade-plan.ts

@@ -0,0 +1,214 @@
+// `x upgrade`'s decision, pure: the pins an app holds and the versions npm publishes in, the one hop
+// a run may make and the wiki section that walks it out. One major per run, so a red gate is that
+// hop's. No I/O: `cmd-upgrade.ts` reads, this decides, and every refusal is thrown from here.
+
+import { UltimateError } from '@ultimat3/core';
+import { quoteArg } from './shell-quote';
+
+export interface UpgradePin {
+  /** The manifest holding it, relative to the app root. */
+  readonly file: string;
+  readonly name: string;
+  readonly spec: string;
+}
+
+export interface UpgradeSection {
+  readonly title: string;
+  readonly url: string;
+  /** The same section as an `x docs` topic, answered whole from the wiki the CLI tarball ships. */
+  readonly local: string;
+}
+
+export interface UpgradeHop {
+  /** The lowest version any workspace pins. */
+  readonly from: string;
+  readonly to: string;
+  /** What a bare `x upgrade` would take after this hop, or null when nothing is left to take. */
+  readonly next: string | null;
+  /** Already where this run was aimed: the newest release only when `next` is null. */
+  readonly atTarget: boolean;
+  /** Null when no major is crossed: a walkthrough exists per major and nothing under one. */
+  readonly section: UpgradeSection | null;
+}
+
+const WIKI_PAGE = 'https://github.com/developerz-ai/ultimate/wiki/Upgrading';
+
+/** The walkthroughs whose heading names one release rather than `<major-1>.x`, as recorded. */
+const RECORDED_FROM: ReadonlyMap<number, string> = new Map([
+  [5, '4.1.0'],
+  [4, '3.0.0'],
+  [3, '2.0.0'],
+]);
+
+const PIN = /^(?:\^|~|>=)?(\d+)(?:\.(\d+|x))?(?:\.(\d+|x))?$/;
+const RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+type Triple = readonly [number, number, number];
+
+const part = (text: string | undefined): number =>
+  text === undefined || text === 'x' ? 0 : Number(text);
+
+/** The version a dependency spec starts from, or undefined when it names none (`workspace:*`). */
+export function pinVersion(spec: string): string | undefined {
+  const match = PIN.exec(spec.trim());
+  if (match === null) return undefined;
+  return `${part(match[1])}.${part(match[2])}.${part(match[3])}`;
+}
+
+/** A plain release's three numbers; a prerelease is not a release, so it answers undefined. */
+export function releaseOf(version: string): Triple | undefined {
+  const match = RELEASE.exec(version);
+  return match === null ? undefined : [part(match[1]), part(match[2]), part(match[3])];
+}
+
+const tripleOf = (version: string): Triple => releaseOf(version) ?? [0, 0, 0];
+
+const compare = (a: string, b: string): number => {
+  const left = tripleOf(a);
+  const right = tripleOf(b);
+  return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
+};
+
+const majorOf = (version: string): number => tripleOf(version)[0];
+
+/** The walkthrough that gets an app into `major`, built from the heading rule. */
+export function sectionFor(major: number): UpgradeSection {
+  const from = RECORDED_FROM.get(major) ?? `${String(major - 1)}.x`;
+  const title = `${from} → ${String(major)}.0.0, entry by entry`;
+  // GitHub's slug, read off the live page: lowercase, every other character dropped, then one
+  // hyphen per space — the arrow leaves two spaces, so `28x--2900-entry-by-entry`.
+  const anchor = title
+    .toLowerCase()
+    .replace(/[^a-z0-9 _-]/g, '')
+    .replaceAll(' ', '-');
+  return { title, url: `${WIKI_PAGE}#${anchor}`, local: `wiki.Upgrading#${anchor}` };
+}
+
+const newestOfMajor = (major: number, released: readonly string[]): string | undefined =>
+  released.filter((version) => majorOf(version) === major).at(-1);
+
+const nextMajorNewest = (from: string, released: readonly string[]): string | undefined => {
+  const major = released.map(majorOf).find((candidate) => candidate > majorOf(from));
+  return major === undefined ? undefined : newestOfMajor(major, released);
+};
+
+/** What a bare run takes from `from`: the next major's newest, else this major's newest. */
+const bareTarget = (from: string, released: readonly string[]): string | undefined => {
+  const next = nextMajorNewest(from, released);
+  if (next !== undefined) return next;
+  const newest = newestOfMajor(majorOf(from), released);
+  return newest !== undefined && compare(newest, from) > 0 ? newest : undefined;
+};
+
+const unreadablePin = (cause: string, file: string): UltimateError =>
+  new UltimateError({
+    code: 'X_UPGRADE_PIN_UNREADABLE',
+    cause,
+    fix: `x upgrade --json   # after editing ${file} so every @ultimat3/* dependency carries a version`,
+  });
+
+/** Every pin's version, or the refusal naming the first pin that has none. */
+function readVersions(pins: readonly UpgradePin[]): readonly string[] {
+  if (pins.length === 0) {
+    throw unreadablePin(
+      'no workspace package.json depends on any @ultimat3/* package, so there is no version to hop from',
+      'package.json',
+    );
+  }
+  return pins.map((pin) => {
+    const version = pinVersion(pin.spec);
+    if (version === undefined) {
+      throw unreadablePin(
+        `${pin.file} depends on ${pin.name} as "${pin.spec}", which names no version to hop from`,
+        pin.file,
+      );
+    }
+    return version;
+  });
+}
+
+/**
+ * The version that brings a mixed set level: the newest release in the high pin's major at or above
+ * it, since the pin itself may name nothing npm has. Past every release of its major, the next one.
+ */
+const aligningVersion = (high: string, released: readonly string[]): string => {
+  const newest = newestOfMajor(majorOf(high), released);
+  if (newest !== undefined && compare(newest, high) >= 0) return newest;
+  return nextMajorNewest(high, released) ?? high;
+};
+
+const tooWide = (cause: string, target: string | undefined): UltimateError =>
+  new UltimateError({
+    code: 'X_UPGRADE_HOP_TOO_WIDE',
+    cause,
+    fix: target === undefined ? 'x upgrade --json' : `x upgrade --to ${quoteArg(target)} --json`,
+  });
+
+/** The refusals of an asked-for target; a target that passes is a legal hop. */
+function checkTarget(input: {
+  readonly to: string;
+  readonly low: string;
+  readonly high: string;
+  readonly released: readonly string[];
+}): void {
+  const { to, low, high, released } = input;
+  if (!released.includes(to)) {
+    throw new UltimateError({
+      code: 'X_UPGRADE_VERSION_UNPUBLISHED',
+      cause: `--to ${to} is not a release npm publishes for @ultimat3/cli`,
+      fix: 'bun pm view @ultimat3/cli versions --json   # then: x upgrade --to <one of them> --json',
+    });
+  }
+  // A mixed set has one way out, so every refusal over it names that way: a fix aimed at the next
+  // major of the lowest pin would itself be refused, for sitting below the highest.
+  const aligning = aligningVersion(high, released);
+  const way = low === high ? bareTarget(low, released) : aligning;
+  if (compare(to, high) < 0) {
+    throw tooWide(`--to ${to} is below the ${high} this app already pins`, way);
+  }
+  // The second operand is what makes the mixed refusal's own fix runnable: `^6` beside `^19` is told
+  // `--to <19.x>`, which brings the straggler level and crosses nothing the rest of the app has not.
+  const widest = Math.max(majorOf(nextMajorNewest(low, released) ?? low), majorOf(aligning));
+  if (majorOf(to) > widest) {
+    throw tooWide(
+      `--to ${to} skips a major: from ${low} a run reaches ${String(widest)}.x at most, so each hop's gate attributes its red to that hop`,
+      way,
+    );
+  }
+}
+
+/** The one hop this run may make, or the refusal saying why it may not. */
+export function planHop(input: {
+  readonly pins: readonly UpgradePin[];
+  readonly versions: readonly string[];
+  readonly to?: string;
+}): UpgradeHop {
+  const { pins, to } = input;
+  const distinct = [...new Set(readVersions(pins))].sort(compare);
+  const low = distinct[0] ?? '0.0.0';
+  const high = distinct.at(-1) ?? low;
+  const released = input.versions.filter((version) => releaseOf(version) !== undefined);
+  released.sort(compare);
+
+  if (to === undefined && distinct.length > 1) {
+    // The stragglers, not the first few: `^19.4.0` nineteen times says nothing about the one `^19.3.1`.
+    const stragglers = pins.filter((pin) => pinVersion(pin.spec) !== high);
+    const held = stragglers.map((pin) => `${pin.file}: ${pin.name} ${pin.spec}`);
+    throw new UltimateError({
+      code: 'X_UPGRADE_MIXED_PINS',
+      cause: `the workspaces pin ${distinct.join(', ')}, and the framework only moves in lockstep. ${String(held.length)} of ${String(pins.length)} below ${high}: ${held.slice(0, 6).join('; ')}`,
+      fix: `x upgrade --to ${quoteArg(aligningVersion(high, released))} --json`,
+    });
+  }
+  if (to !== undefined) checkTarget({ to, low, high, released });
+
+  const target = to ?? bareTarget(low, released) ?? low;
+  const after = bareTarget(target, released) ?? null;
+  return {
+    from: low,
+    to: target,
+    next: after,
+    atTarget: distinct.length === 1 && target === low,
+    section: majorOf(target) > majorOf(high) ? sectionFor(majorOf(target)) : null,
+  };
+}

package/src/upgrade-registry.ts

@@ -0,0 +1,53 @@
+// What npm publishes, as `bun pm view` answers it: every version of the CLI, and the Bun floor of one.
+// Through the app's own registry config, because `bun pm view` runs from the app root. Any failure
+// here is `X_UPGRADE_REGISTRY_UNREACHABLE`, and it can only fire before the hop has written anything.
+
+import { UltimateError } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+
+const PACKAGE = '@ultimat3/cli';
+const VERSIONS = t.array(t.string);
+const ENGINES = t.object({ bun: t.optional(t.string) });
+
+const unreachable = (result: ExecResult): UltimateError =>
+  new UltimateError({
+    code: 'X_UPGRADE_REGISTRY_UNREACHABLE',
+    cause: `${result.command.slice(1).join(' ')} exited ${String(result.code)}: ${execOutput(result).slice(-500) || 'no output'}`,
+    fix: 'bun pm view @ultimat3/cli version   # once this answers, re-run: x upgrade --json',
+  });
+
+/** A child's stdout as JSON, or undefined: a foreign answer that will not parse is not a crash. */
+export const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const view = async (runner: Runner, cwd: string, args: readonly string[]): Promise<ExecResult> => {
+  const result = await runner([process.execPath, 'pm', 'view', ...args, '--json'], { cwd });
+  if (!result.ok) throw unreachable(result);
+  return result;
+};
+
+/** Every version npm publishes for the CLI, as npm orders them. */
+export async function publishedVersions(runner: Runner, cwd: string): Promise<readonly string[]> {
+  const result = await view(runner, cwd, [PACKAGE, 'versions']);
+  const parsed = VERSIONS.safeParse(parseJson(result.stdout));
+  if (parsed.issues !== undefined) throw unreachable(result);
+  return parsed.value as readonly string[];
+}
+
+/** `engines.bun` of one release; undefined when that release declares none. */
+export async function releaseBunRange(
+  runner: Runner,
+  cwd: string,
+  version: string,
+): Promise<string | undefined> {
+  const result = await view(runner, cwd, [`${PACKAGE}@${version}`, 'engines']);
+  const parsed = ENGINES.safeParse(parseJson(result.stdout));
+  return parsed.issues === undefined ? (parsed.value as { readonly bun?: string }).bun : undefined;
+}

package/src/upgrade-report.ts

@@ -0,0 +1,139 @@
+// What `x upgrade` says: the one report every outcome carries, the terminal's lines projected from it,
+// and the sentence naming what to do next. No decisions and no I/O: `cmd-upgrade.ts` hands in the facts.
+
+import { msg } from './messages';
+import type { JsonValue } from './output';
+import type { AgentsLinkState } from './upgrade-agents-link';
+import type { BunEdit, BunManual } from './upgrade-bun-floor';
+import type { GateFinding, HopGate, RepoScript } from './upgrade-gate';
+import type { UpgradeHop, UpgradePin } from './upgrade-plan';
+
+export interface PlannedWrites {
+  /** Absolute path to final text; a manifest holding both a pin and a floor is written once. */
+  readonly files: ReadonlyMap<string, string>;
+  readonly edited: readonly BunEdit[];
+  readonly manual: readonly BunManual[];
+}
+
+/** The strongest check a hop had: the verdict `done` rests on, stated rather than implied. */
+export type HopProof = 'verify' | 'scripts' | 'none';
+
+export const proofOf = (gate: HopGate | undefined, scripts: readonly RepoScript[]): HopProof =>
+  gate !== undefined ? 'verify' : scripts.length > 0 ? 'scripts' : 'none';
+
+/** What the agent does next, as a sentence naming the commands. */
+export const thenLine = (input: {
+  readonly hop: UpgradeHop;
+  readonly dryRun: boolean;
+  readonly app: boolean;
+  readonly gate: HopGate | undefined;
+  readonly scripts: readonly RepoScript[];
+}): string => {
+  const { hop, dryRun, app, gate, scripts } = input;
+  if (hop.atTarget) {
+    return hop.next === null
+      ? msg('cli.upgrade.then.atLatest', { version: hop.to })
+      : msg('cli.upgrade.then.atTarget', { version: hop.to, next: hop.next });
+  }
+  if (dryRun) {
+    return app
+      ? msg('cli.upgrade.then.dryRun')
+      : msg('cli.upgrade.then.dryRunNoApp', {
+          scripts: scripts.map((script) => `bun run ${script.name}`).join(', ') || 'nothing',
+        });
+  }
+  if (!app) {
+    if (scripts.length === 0) return msg('cli.upgrade.then.noProof', { to: hop.to });
+    return scripts.every((script) => script.ok === true)
+      ? msg('cli.upgrade.then.scriptsGreen', { to: hop.to })
+      : msg('cli.upgrade.then.scriptsRed', { to: hop.to });
+  }
+  if (gate?.verify.ok !== true) return msg('cli.upgrade.then.red', { to: hop.to });
+  return hop.next === null
+    ? msg('cli.upgrade.then.last', { to: hop.to })
+    : msg('cli.upgrade.then.walk', { to: hop.to, next: hop.next });
+};
+
+const findingLines = (findings: readonly GateFinding[]): readonly string[] =>
+  findings.flatMap((finding) => [
+    `  ${finding.code}${finding.step === undefined ? '' : ` [${finding.step}]`}${finding.at === undefined ? '' : ` (${finding.at})`}`,
+    `    fix: ${finding.fix}`,
+  ]);
+
+/** The terminal's form of the report: the url first, then each finding's `fix:`. */
+export const humanLines = (input: {
+  readonly hop: UpgradeHop;
+  readonly writes: PlannedWrites;
+  readonly gate: HopGate | undefined;
+  readonly scripts: readonly RepoScript[];
+  readonly then: string;
+  readonly agentsMd?: AgentsLinkState;
+}): readonly string[] => {
+  const { hop, writes, gate, scripts, then, agentsMd } = input;
+  return [
+    ...(hop.section === null
+      ? []
+      : [msg('cli.upgrade.read', { title: hop.section.title, url: hop.section.url })]),
+    ...writes.edited.map((edit) =>
+      msg('cli.upgrade.bunEdited', { path: edit.path, from: edit.from, to: edit.to }),
+    ),
+    ...writes.manual.map((site) =>
+      msg('cli.upgrade.bunManual', { path: site.path, line: site.line, why: site.why }),
+    ),
+    ...(agentsMd === 'link' || agentsMd === 'differs'
+      ? [msg(agentsMd === 'link' ? 'cli.upgrade.agentsMd.link' : 'cli.upgrade.agentsMd.differs')]
+      : []),
+    ...(gate?.guards.missing ?? []).map((guard) => msg('cli.upgrade.guard', { fix: guard.add })),
+    ...(gate?.guards.differs ?? []).map((guard) =>
+      msg('cli.upgrade.guard', { fix: guard.refresh }),
+    ),
+    ...findingLines([...(gate?.manifest.findings ?? []), ...(gate?.verify.findings ?? [])]),
+    ...scripts
+      .filter((script) => script.ok === false)
+      .map((script) => msg('cli.upgrade.scriptRed', { name: script.name })),
+    msg('cli.upgrade.then', { then }),
+  ];
+};
+
+const asJson = (value: unknown): JsonValue => value as JsonValue;
+
+/** The one shape every outcome reports: `--json` and the terminal project this and nothing else. */
+export const report = (input: {
+  readonly hop: UpgradeHop;
+  readonly done: boolean;
+  readonly dryRun: boolean;
+  readonly pins: readonly UpgradePin[];
+  readonly bunFrom: string | null;
+  readonly bunTo: string | null;
+  readonly writes: PlannedWrites;
+  readonly app: boolean;
+  readonly gate: HopGate | undefined;
+  readonly scripts: readonly RepoScript[];
+  readonly then: string;
+  /** What the hop does to `AGENTS.md` (`upgrade-agents-link.ts`); absent when no hop is planned. */
+  readonly agentsMd?: AgentsLinkState;
+}): JsonValue => {
+  const { hop, done, dryRun, pins, bunFrom, bunTo, writes, app, gate, scripts, then } = input;
+  return asJson({
+    from: hop.from,
+    to: hop.to,
+    next: hop.next,
+    done,
+    dryRun,
+    app,
+    proof: dryRun ? 'none' : proofOf(gate, scripts),
+    section: hop.section,
+    pins: hop.atTarget
+      ? []
+      : pins.map((pin) => ({ file: pin.file, name: pin.name, from: pin.spec, to: hop.to })),
+    bun: { from: bunFrom, to: bunTo, edited: writes.edited, manual: writes.manual },
+    agentsMd: input.agentsMd ?? null,
+    guards: gate?.guards ?? null,
+    manifest: gate?.manifest ?? null,
+    verify: gate?.verify ?? null,
+    scripts,
+    then,
+  });
+};
+
+export const NO_WRITES: PlannedWrites = { files: new Map(), edited: [], manual: [] };

package/src/upgrade-root.ts

@@ -0,0 +1,74 @@
+// Where `x upgrade` works: the app, or a repository that holds pins and no `app.config.ts`, which can
+// still hop and just cannot be gated. Never a directory above the repository the cwd is in, and never
+// a workspace member when a root claims it: the hop moves the whole set or none of it.
+
+// why: a submodule's or worktree's `.git` is a file, and Bun.file cannot tell either kind exists.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join, dirname or relative primitive.
+import { dirname, join, relative, resolve } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import { appDirsBelow, findAppRoot, requireAppRoot } from './app-root';
+import { parseManifest, readManifests, readPins } from './upgrade-pins';
+import { workspaceGlobs, workspaceManifestPaths } from './workspace-graph';
+
+export interface UpgradeRoot {
+  readonly dir: string;
+  /** Whether `dir` holds `app.config.ts`, so `x verify` can answer for it. */
+  readonly app: boolean;
+}
+
+/** `from`, then each directory above it, stopping at the repository's own root: any `.git`. */
+function ancestors(from: string): readonly string[] {
+  const dirs: string[] = [];
+  let dir = from;
+  for (;;) {
+    dirs.push(dir);
+    const parent = dirname(dir);
+    if (parent === dir || existsSync(join(dir, '.git'))) return dirs;
+    dir = parent;
+  }
+}
+
+const holdsPins = async (dir: string): Promise<boolean> =>
+  (await Bun.file(join(dir, 'package.json')).exists()) &&
+  readPins(await readManifests(dir)).length > 0;
+
+const claims = async (root: string, member: string): Promise<boolean> => {
+  const path = join(root, 'package.json');
+  const file = Bun.file(path);
+  if (!(await file.exists())) return false;
+  const globs = workspaceGlobs(parseManifest(path, await file.text()));
+  const manifest = `${relative(root, member).replaceAll('\\', '/')}/package.json`;
+  return (await workspaceManifestPaths(root, globs)).includes(manifest);
+};
+
+/** The app at or above `from`; else the nearest manifest holding pins, or the root claiming it. */
+export async function findUpgradeRoot(from: string): Promise<UpgradeRoot> {
+  const start = resolve(from);
+  const app = findAppRoot(start);
+  if (app !== undefined) return { dir: app.dir, app: true };
+
+  const chain = ancestors(start);
+  let nearest: number | undefined;
+  for (const [index, dir] of chain.entries()) {
+    if (await holdsPins(dir)) {
+      nearest = index;
+      break;
+    }
+  }
+  const held = nearest === undefined ? undefined : chain[nearest];
+  if (held === undefined) {
+    throw new UltimateError({
+      code: 'X_UPGRADE_PIN_UNREADABLE',
+      cause: `no package.json at or above ${start} depends on any @ultimat3/* package, so there is nothing to hop from`,
+      fix: 'x upgrade --json   # from the directory whose package.json holds the @ultimat3/* dependencies',
+    });
+  }
+  let dir = held;
+  for (const above of chain.slice((nearest ?? 0) + 1)) {
+    if (await claims(above, dir)) dir = above;
+  }
+  // An app below is gated from its own directory: a hop from here would claim no gate it could have.
+  if (appDirsBelow(dir).length > 0) requireAppRoot('upgrade', dir);
+  return { dir, app: false };
+}

package/src/verify-budgets-build.ts

@@ -0,0 +1,118 @@
+// The budgets step's first half: when the stats on disk cannot be read as this tree's, run the one
+// builder (`x build --target static`) through the step's runner, so the build is a tagged child
+// under the step's deadline. Its output goes to `.x/verify-static`, never over a deployable
+// `.x/static`; the stats it weighs always land in `.x/build-stats.json` (`prerender.ts`).
+
+// why: Bun exposes no path-join primitive; every path here is assembled from the app root.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, isCompiledBundle } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import { BUILD_STATS_FILE, readBuildStats } from './budgets';
+import type { BudgetsFreshness } from './budgets-freshness';
+import { budgetsFreshness } from './budgets-freshness';
+import type { Runner } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import type { Finding } from './output';
+import { newestSourceMtime } from './source-mtime';
+import { documentIn } from './upgrade-gate';
+
+/** Where the gate's own build writes its pages: inside `.x/`, gitignored, apart from `.x/static`. */
+export const VERIFY_STATIC_OUT = join('.x', 'verify-static');
+
+/** `x build`'s argv, spawned as this process's own CLI: the source entry, or a compiled binary. */
+export function verifyBuildCommand(): readonly string[] {
+  // `--no-capture`: the gate weighs script bytes, and a card is a picture — so a machine with no
+  // Chrome stays green on an app that declares `og.capture` (`cmd-shot.ts`'s header is why).
+  const words = [
+    'build',
+    '--target',
+    'static',
+    '--no-preflight',
+    '--no-capture',
+    '--out',
+    VERIFY_STATIC_OUT,
+  ];
+  const self = isCompiledBundle(import.meta.dir) ? [] : [join(import.meta.dir, 'bin.ts')];
+  return [process.execPath, ...self, ...words, '--json'];
+}
+
+const statsMtime = async (path: string): Promise<number | undefined> => {
+  const file = Bun.file(path);
+  return (await file.exists()) ? file.lastModified : undefined;
+};
+
+/** The stats file's state against this tree. */
+export async function statsFreshness(root: string): Promise<BudgetsFreshness> {
+  const stats = await readBuildStats(root);
+  const path = join(root, BUILD_STATS_FILE);
+  return budgetsFreshness({
+    stats,
+    statsMtimeMs: stats === undefined ? undefined : await statsMtime(path),
+    newestSourceMtimeMs: await newestSourceMtime(root),
+  });
+}
+
+const FINDING = t.object({
+  code: t.string,
+  cause: t.string,
+  fix: t.string,
+  docs: t.optional(t.string),
+  at: t.optional(t.string),
+});
+const BUILD_DOCUMENT = t.object({
+  findings: t.optional(t.array(FINDING)),
+  data: t.optional(t.object({ output: t.optional(t.string) })),
+});
+
+interface BuildDocument {
+  readonly findings?: readonly Finding[];
+  readonly data?: { readonly output?: string };
+}
+
+export interface MeasuredFirst {
+  readonly state: BudgetsFreshness;
+  /** Whether this step spawned the build. */
+  readonly built: boolean;
+  /** The build's own findings when it failed: the step's, unchanged. Empty when it passed. */
+  readonly findings: readonly Finding[];
+  /** One line saying the step built and why, then a failed build's output. Absent when fresh. */
+  readonly output?: string;
+}
+
+/**
+ * Build first unless the stats are fresh. A failed build's findings are returned as the build
+ * reported them, its code and its `fix:`; a build that printed no document is `X_BUILD_FAILED` with
+ * what it printed, and the command that shows it again.
+ */
+export async function measureIfStale(ctx: {
+  readonly root: string;
+  readonly runner: Runner;
+}): Promise<MeasuredFirst> {
+  const state = await statsFreshness(ctx.root);
+  if (state === 'fresh') return { state, built: false, findings: [] };
+  const command = verifyBuildCommand();
+  const result = await ctx.runner(command, { cwd: ctx.root });
+  const ran = msg('cli.verify.budgets.built', {
+    state,
+    out: VERIFY_STATIC_OUT,
+    ms: result.durationMs,
+  });
+  if (result.ok) return { state, built: true, findings: [], output: ran };
+  const parsed = BUILD_DOCUMENT.safeParse(documentIn(result.stdout));
+  const document = parsed.issues === undefined ? (parsed.value as BuildDocument) : undefined;
+  const reported = document?.findings ?? [];
+  const output = document?.data?.output ?? execOutput(result);
+  const findings: readonly Finding[] =
+    reported.length > 0
+      ? reported
+      : [
+          {
+            code: 'X_BUILD_FAILED',
+            cause: `${command.slice(-8).join(' ')} exited ${String(result.code)} with no JSON report, so x verify could not weigh this tree`,
+            fix: 'x build --target static --json',
+            docs: ERROR_DOCS_URL,
+          },
+        ];
+  return { state, built: true, findings, output: [ran, output].join('\n') };
+}