@ultimat3/cli 9.0.0 → 10.0.0

package/src/prerender.ts

@@ -4,7 +4,7 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
@@ -15,9 +15,13 @@ import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
-import type { SkippedRoute } from './static-report';
+import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
+// Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
+// carries it, and this file already imports that module.
+export type { UnmeasuredRoute };
+
 /**
  * `static` only. `isr` revalidates and `ssr`/`stream` need a process, so writing any of them to
  * disk would publish a page whose staleness nothing can correct — and the route already declared
@@ -46,12 +50,6 @@ export interface PrerenderedPage {
   readonly bytes: number;
 }
 
-/** A route that declared a budget and could not be rendered here, and what stopped it. */
-export interface UnmeasuredRoute {
-  readonly path: string;
-  readonly reason: string;
-}
-
 export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
@@ -130,6 +128,22 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
 
+  // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
+  // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
+  // Called bare, any route whose component, `load` or `meta` reads `useContext()` threw
+  // `X_NO_CONTEXT`: measured against `examples/dummy`, `/posts/new` and `/settings` were filed
+  // unmeasured for that reason alone, and a `render: 'static'` route reading it failed the whole
+  // build. One context for the build, `role: 'web'` because that is the role serving these
+  // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
+  // with the id the report and the stats carry.
+  const ctx = createContext({ role: 'web', buildId });
+  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    runWithContext(ctx, () =>
+      routeDocument(entry, data, {
+        resolveIsland: (file: string) => islands.resolverFor(file),
+      }),
+    );
+
   for (const entry of routeEntries()) {
     const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
     const reason = skipReasonFor(facts);
@@ -141,11 +155,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // routes it never used to touch would be a worse regression than the gap it closes. A route
       // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
       try {
-        const html = await routeDocument(
-          entry,
-          { url: new URL(entry.path, origin).href, params: {} },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        );
+        const html = await document(entry, {
+          url: new URL(entry.path, origin).href,
+          params: {},
+        });
         const measured = await measureDocumentJs(html, options.out);
         const chain = heaviestSource(islands, measured.entries);
         routes.push({
@@ -162,12 +175,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     const artifacts = await renderStatic(
       entry,
-      ({ path, params }) =>
-        routeDocument(
-          entry,
-          { url: new URL(path, origin).href, params },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        ),
+      ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
       { buildId },
     );
     // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
@@ -209,6 +217,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     buildId,
     emitted: pages.map((page) => ({ route: page.route, path: page.path, file: page.file })),
     skipped,
+    // The list `X_BUDGET_UNMEASURED`'s `fix:` cites by name. It rode home on the in-process
+    // `PrerenderReport` and nowhere else, and `cmd-build.ts` discards a successful subprocess's
+    // stdout — so the one command the finding tells an author to run printed no `unmeasured` key
+    // and no reason. Written into the report is what makes the instruction true.
+    unmeasured,
   });
   return {
     out: options.out,

package/src/static-report.ts

@@ -48,6 +48,19 @@ export type SkippedRoute = RouteFacts & {
   readonly why: string;
 };
 
+/**
+ * A route that declared a budget and could not be rendered here, and what stopped it.
+ *
+ * Declared HERE and not in `prerender.ts`, though `prerenderSite` is what fills it: this file is
+ * the report's shape and `prerender.ts` imports it, so the other direction is a cycle. `prerender`
+ * re-exports the name for its own callers.
+ */
+export type UnmeasuredRoute = {
+  /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
+  readonly path: string;
+  readonly reason: string;
+};
+
 /** One HTML file in the artifact, and the declared route that produced it. */
 export type EmittedPage = {
   readonly route: string;
@@ -62,6 +75,15 @@ export type StaticReport = {
   readonly buildId: string;
   readonly emitted: readonly EmittedPage[];
   readonly skipped: readonly SkippedRoute[];
+  /**
+   * Every budgeted route this build could not weigh, with the reason. `X_BUDGET_UNMEASURED`'s own
+   * `fix:` cites this list by name — `x build --target static --json # its "unmeasured" list says
+   * why` — and until it was written here the list existed only on the in-process `PrerenderReport`
+   * and reached no `x` command's output at all: `cmd-build.ts` discards a successful subprocess's
+   * stdout. A `fix:` naming a key nothing prints is axiom 4 inverted at the step meant to unblock
+   * the reader.
+   */
+  readonly unmeasured: readonly UnmeasuredRoute[];
 };
 
 /**
@@ -139,6 +161,9 @@ const isSkipped = (value: unknown): value is SkippedRoute =>
   typeof value['why'] === 'string' &&
   inDomain(SKIP_REASONS, value['reason']);
 
+const isUnmeasured = (value: unknown): value is UnmeasuredRoute =>
+  isRecord(value) && typeof value['path'] === 'string' && typeof value['reason'] === 'string';
+
 const isEmitted = (value: unknown): value is EmittedPage =>
   isRecord(value) &&
   typeof value['route'] === 'string' &&
@@ -152,13 +177,20 @@ const isEmitted = (value: unknown): value is EmittedPage =>
  */
 export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (!isRecord(value)) return undefined;
-  const { target, out, buildId, emitted, skipped } = value;
+  const { target, out, buildId, emitted, skipped, unmeasured } = value;
   if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
     return undefined;
   }
   if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
   if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
-  return { target, out, buildId, emitted, skipped };
+  // OPTIONAL on the way in, total on the way out. `.x/` survives a checkout of an older commit,
+  // and a report written before this field existed has to read as "nothing unmeasured" — refusing
+  // it would answer `X_BUDGET_UNMEASURED` for every route on a build that had weighed them all.
+  // Present and malformed is still no report, exactly as a malformed skip row is.
+  if (unmeasured !== undefined && (!Array.isArray(unmeasured) || !unmeasured.every(isUnmeasured))) {
+    return undefined;
+  }
+  return { target, out, buildId, emitted, skipped, unmeasured: unmeasured ?? [] };
 }
 
 export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
@@ -198,7 +230,9 @@ export async function removeStaticReport(root: string): Promise<void> {
 export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
   // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
   // which the inventory is about — `data` already carries `artifact` and the build's own id.
-  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+  return report === undefined
+    ? {}
+    : { emitted: report.emitted, skipped: report.skipped, unmeasured: report.unmeasured };
 }
 
 /**
@@ -209,6 +243,10 @@ export function renderStaticReport(report: StaticReport): readonly string[] {
   const rows: readonly (readonly string[])[] = [
     ...report.emitted.map((page) => ['emitted', page.route, page.file]),
     ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+    // The same three columns, so the terminal and `--json` carry the same three lists. A route
+    // whose budget could not be weighed is invisible in `emitted` and, when it also rendered, in
+    // `skipped` too — and it is the row `X_BUDGET_UNMEASURED` sends its reader here to read.
+    ...report.unmeasured.map((route) => ['unmeasured', route.path, route.reason]),
   ];
   const widths = [0, 1].map((index) =>
     Math.max(...rows.map((row) => (row[index] ?? '').length), 0),

package/src/templates/scaffold-container.ts

@@ -197,6 +197,18 @@ services:
     deploy: { replicas: 1 } # scales on concurrent websockets, no sticky sessions — pinned by the port
     # The sync role binds PORT + 1. PORT is unset here, so it is 3000 and this listens on 3001.
     ports: ['3001:3001']
+    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
+    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
+    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
+    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
+    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
+    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
+    healthcheck:
+      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      start_period: 30s
+      retries: 3
 
   worker:
     <<: *image

package/src/templates/scaffold-docs.ts

@@ -58,7 +58,7 @@ file in it is deletable.
 
 const readme = (app: NameSet): string => `# ${app.pascal}
 
-Built with [Ultimate](https://ultimate.dev). Bun-only, Postgres, SolidJS.
+Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Postgres, SolidJS.
 
 ## 🚀 Start
 

package/src/templates/scaffold-domain-package.ts

@@ -31,6 +31,9 @@ export type Role = (typeof ROLES)[number];
  * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
  * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,
  * so the fix names the conversion that has to happen first.
+ *
+ * No \`docs:\`: \`UltimateError\` resolves the link from the code's registered descriptor, so it has
+ * one home. A per-code URL written here is a page that does not exist.
  */
 export class ${app.pascal}CurrencyMismatchError extends UltimateError {
   constructor(input: { readonly left: string; readonly right: string }) {
@@ -38,7 +41,6 @@ export class ${app.pascal}CurrencyMismatchError extends UltimateError {
       code: '${currencyCode(app)}',
       cause: \`cannot add \${input.left} to \${input.right}: Money is only additive inside one currency\`,
       fix: \`bun test packages/domain/src/index.test.ts   # add() is defined only inside one currency — convert \${input.right} to \${input.left} before calling it\`,
-      docs: 'https://ultimate.dev/errors/${currencyCode(app)}',
     });
   }
 }

package/src/templates/scaffold-repo.ts

@@ -123,13 +123,21 @@ const envDeclaration = (): string => `${envSchemaSource()}
 export const env = defineEnv(envSchema);`;
 
 /**
- * No `installPrompt`, no `afterSignInPath`, no `modelEnv`. All three were declared by
- * `defineConfig`, defaulted by it, and read by NO file; all three are DELETED from
- * `packages/core/src/config.ts` as of 2026-08-22, whose header now records the removal rather than
- * the marker this comment used to cite. So scaffolding one is no longer a switch with no wire — it
- * is `TS2353` in the generated app's first `x verify`. The note belongs HERE rather than in the
- * emitted file: an app author has no use for a comment about keys their config does not name.
- * `scaffold-config.test.ts` is what keeps them from growing back.
+ * No `installPrompt`, no `afterSignInPath`, no `modelEnv`, and no `realtime.tier`. All four were
+ * declared by `defineConfig`, defaulted by it, and read by NO file; all four are DELETED from
+ * `packages/core/src/config.ts` — the first three as of 2026-08-22, `tier` on 2026-08-23 — whose
+ * header now records the removals rather than the marker this comment used to cite. So scaffolding
+ * one is no longer a switch with no wire: it is `TS2353` in the generated app's first `x verify`,
+ * which is CI's `scaffold-smoke` job. The note belongs HERE rather than in the emitted file: an app
+ * author has no use for a comment about keys their config does not name.
+ *
+ * `tier` is the one that got through, and it says what the list was worth. It accepted
+ * `'channels' | 'live-queries' | 'local-first'`, so `'local-first'` read as a durable client store
+ * that does not exist (`createOpfsLocalStore` throws `X_NOT_IMPLEMENTED`) — silent, and shaped like
+ * a capability. Which realtime tier an app is on is decided by what it DECLARES: a `channel()`
+ * topic, a `live: true` query, a local store. `scaffold-config.test.ts` no longer holds a list of
+ * dead names to remember; it resolves every key path this literal writes against what `defineConfig`
+ * really returns, so the fourteenth deletion fails there with no edit here.
  */
 const appConfig = (
   app: NameSet,
@@ -154,7 +162,7 @@ export const config = defineConfig({
   cache: { tiers: ['request-memo', 'lru'] },
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
-  realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },
+  realtime: { enabled: true, transport: 'memory' },
   pwa: { enabled: true, offline: 'runtime' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });

package/src/templates/slice-foundation.ts

@@ -19,10 +19,7 @@ import { policyFiles } from './policy';
  */
 export type SliceModule = 'entity' | 'policy' | 'errors';
 
-/** The feature's own code, derived once. The `docs:` URL used to be the literal
- * `.../X_NOT_FOUND` beside a `code:` of `X_INVOICE_NOT_FOUND`, so following the link from a real
- * failure landed on a different code's page — the same interpolation `error-codes.ts`'s `docsFor`
- * already does for every framework code. */
+/** The feature's own code, derived once. */
 const notFoundCode = (feature: NameSet): string =>
   `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
 
@@ -41,13 +38,14 @@ const errorsSource = (feature: NameSet): string => {
 
 import { UltimateError } from '@ultimat3/core';
 
+// No \`docs:\`. \`UltimateError\` resolves it from the code's registered descriptor, so the link has
+// one home; a per-code URL written here is a page that does not exist.
 export class ${feature.pascal}NotFoundError extends UltimateError {
   constructor(input: { id: string }) {
     super({
       code: '${errorCode}',
       cause: \`no ${feature.kebab} with id \${input.id}\`,
       fix: 'x queries list --json, then pass an id the ${feature.kebab} read returns',
-      docs: 'https://ultimate.dev/errors/${errorCode}',
     });
   }
 }

package/src/test-shards.ts

@@ -3,8 +3,8 @@
 // cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
 // that rule is this file's, and argv parsing is that one's.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { AffectedSelection } from './affected';
-import { docsFor } from './error-codes';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
@@ -137,7 +137,7 @@ const failureOf = (shard: Shard, code: number, plan: ReproduceOptions): Finding
   code: 'X_TEST_SHARD_FAILED',
   cause: `shard ${shard.index} of ${plan.workers} exited ${code} (${shard.files.length} file(s))`,
   fix: reproduceFor(shard, plan),
-  docs: docsFor('X_TEST_SHARD_FAILED'),
+  docs: ERROR_DOCS_URL,
 });
 
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {

package/src/tsconfig-references.ts

@@ -7,7 +7,7 @@
 // root that has no `tsconfig.json` at all, so an `existsSync` ahead of it was a second question
 // with one answer.
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import { maskLiterals, stripComments } from './ts-scan';
 
@@ -82,7 +82,7 @@ export const unreferencedFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_UNREFERENCED',
   cause: `packages/${dir} is a published workspace and ${ROOT_TSCONFIG} has no reference to it, so tsc -b never builds it`,
   fix: `add { "path": "./packages/${dir}" } to "references" in ${ROOT_TSCONFIG}, then run bunx tsc -b --pretty false`,
-  docs: docsFor('X_PACKAGE_UNREFERENCED'),
+  docs: ERROR_DOCS_URL,
   at: ROOT_TSCONFIG,
 });
 

package/src/verify-checks.ts

@@ -4,6 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import {
   AGENTS_MD_FILENAME,
@@ -330,7 +331,7 @@ async function specFindings(root: string, manifest: Manifest): Promise<readonly
       code: 'X_MANIFEST_STALE',
       cause: `${OPENAPI_FILE} does not match the actions the code registers`,
       fix: 'x manifest',
-      docs: 'https://ultimate.dev/errors/X_MANIFEST_STALE',
+      docs: ERROR_DOCS_URL,
       at: OPENAPI_FILE,
     },
   ];
@@ -344,6 +345,6 @@ const seoFinding = (issue: MetaIssue): Finding => ({
   code: issue.code,
   cause: issue.cause,
   fix: issue.fix,
-  docs: `https://ultimate.dev/errors/${issue.code}`,
+  docs: ERROR_DOCS_URL,
   at: issue.file,
 });

package/src/verify-floor.ts

@@ -7,7 +7,7 @@
 // all, and `join` builds the host-separator path to it.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import type { Finding } from './output';
 import { VERIFY_STEP_NAMES } from './verify-step';
 
@@ -43,8 +43,10 @@ export function parseVerifyFloor(
   try {
     payload = JSON.parse(text);
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    return { steps: [], problems: [`it does not parse as JSON (${reason})`] };
+    // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`: both halves
+    // run on a value this process did not build, and either can throw one line before the guard that
+    // was meant to make the path safe (`metrics-endpoint.ts` states the same rule over `stringField`).
+    return { steps: [], problems: [`it does not parse as JSON (${renderThrowable(error)})`] };
   }
   const steps = asRecord(payload)?.['steps'];
   if (!Array.isArray(steps)) {
@@ -92,7 +94,7 @@ export const vanishedSuiteFinding = (step: string): Finding => ({
   code: 'X_VERIFY_SUITE_VANISHED',
   cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and this run found nothing for it to check`,
   fix: `x verify --json   # restore the ${step} suite, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
-  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  docs: ERROR_DOCS_URL,
   at: VERIFY_FLOOR_FILE,
 });
 
@@ -111,7 +113,7 @@ export const skippedSuiteFinding = (step: string, skipped: number): Finding => (
   code: 'X_VERIFY_SUITE_VANISHED',
   cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and all ${skipped} test(s) it found skipped themselves, so nothing ran`,
   fix: `x test ${step} --json   # then set what the suite skips without, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
-  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  docs: ERROR_DOCS_URL,
   at: VERIFY_FLOOR_FILE,
 });
 
@@ -128,6 +130,6 @@ export const floorProblemFindings = (floor: VerifyFloor | undefined): readonly F
     code: 'X_CONFIG_INVALID',
     cause: `${VERIFY_FLOOR_FILE} is not a suite floor: ${problem}`,
     fix: `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`,
-    docs: docsFor('X_CONFIG_INVALID'),
+    docs: ERROR_DOCS_URL,
     at: VERIFY_FLOOR_FILE,
   }));

package/src/verify-run.ts

@@ -2,7 +2,7 @@
 // `cmd-verify.ts` because `x build` and the MCP host run the gate without going through the
 // command: what a run means — never bail early, count what actually ran — belongs to neither.
 
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import {
@@ -139,6 +139,6 @@ function findingOf(error: unknown, step: string): Finding {
     code: 'X_VERIFY_FAILED',
     cause: `step "${step}" threw: ${cause}`,
     fix: 'x verify --json',
-    docs: 'https://ultimate.dev/errors/X_VERIFY_FAILED',
+    docs: ERROR_DOCS_URL,
   };
 }

package/src/verify-step.ts

@@ -2,6 +2,7 @@
 // repo feeds it findings it could not produce on its own. Split from the step list so a step
 // implementation can live beside the code it checks without importing the list.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
@@ -106,7 +107,7 @@ export function fromExec(result: ExecResult, finding: Omit<Finding, 'docs'>): St
   if (result.ok) return { ok: true, findings: [], output: execOutput(result) };
   return {
     ok: false,
-    findings: [{ ...finding, docs: `https://ultimate.dev/errors/${finding.code}` }],
+    findings: [{ ...finding, docs: ERROR_DOCS_URL }],
     output: execOutput(result),
   };
 }

package/src/verify-test-run.ts

@@ -3,7 +3,7 @@
 // happens to them once selected — a wrong file list is never a race, and a race is never a
 // selection bug.
 
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
@@ -51,7 +51,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
       // The reproduction has to name every input to the split, or it reruns a different file set:
       // `reproduceFor` is the one place that rule lives, shared with `x test`.
       fix: reproduceFor(shard, { workers: shards.length, type: options.type }),
-      docs: docsFor('X_TEST_SHARD_FAILED'),
+      docs: ERROR_DOCS_URL,
     });
   }
   // Only the failing shards' output: a green 8-way split would otherwise print eight summaries,

package/src/workspace-checks.ts

@@ -5,7 +5,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { renderCauseValue } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated } from './source-files';
 import { checkRootReferences } from './tsconfig-references';
@@ -14,13 +14,11 @@ export const LINE_CEILING = 500;
 
 export const PACKAGE_FILES = ['README.md', 'CLAUDE.md', 'tsconfig.json', 'src/index.ts'] as const;
 
-const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 export const tooLongFinding = (path: string, lines: number): Finding => ({
   code: 'X_FILE_TOO_LONG',
   cause: `${path} is ${lines} lines, over the ${LINE_CEILING} line ceiling`,
   fix: `split ${path}: one file, one responsibility`,
-  docs: docs('X_FILE_TOO_LONG'),
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -49,7 +47,7 @@ export const missingFileFinding = (dir: string, file: string, scaffolder: boolea
   fix: scaffolder
     ? `bun run scripts/new-package.ts ${dir} --only ${file}`
     : `add packages/${dir}/${file}, shaped like the one in a sibling package`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/${file}`,
 });
 
@@ -68,7 +66,7 @@ export const badVersionFinding = (dir: string, found: unknown): Finding => ({
   // this finding with a TypeError from inside the gate.
   cause: `packages/${dir}/package.json has no semver "version" (found ${renderCauseValue(found)})`,
   fix: `set a semver "version" in packages/${dir}/package.json, then: bun run verify`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -103,7 +101,7 @@ export const versionSkewFinding = (dir: string, found: string, expected: string)
   code: 'X_RELEASE_VERSION_SKEW',
   cause: `packages/${dir} is at ${found}, not the lockstep version ${expected}`,
   fix: `bun run scripts/release.ts --version ${expected}`,
-  docs: docs('X_RELEASE_VERSION_SKEW'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -116,7 +114,7 @@ export const pinSkewFinding = (
   code: 'X_RELEASE_VERSION_SKEW',
   cause: `packages/${dir} pins ${dep} at ${range}, not the lockstep version ${expected}`,
   fix: `bun run scripts/release.ts --version ${expected}`,
-  docs: docs('X_RELEASE_VERSION_SKEW'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -167,7 +165,7 @@ export const missingPublishedFileFinding = (dir: string, entry: string): Finding
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json ships "${entry}" in "files", but packages/${dir}/${entry} does not exist`,
   fix: `add packages/${dir}/${entry}, or drop "${entry}" from "files" in packages/${dir}/package.json`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -175,7 +173,7 @@ export const publishesTestsFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json does not exclude ${TEST_EXCLUSION} from "files"`,
   fix: `add "${TEST_EXCLUSION}" to "files" in packages/${dir}/package.json, after "src"`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -196,7 +194,7 @@ export const buildArtifactsFinding = (dir: string, count: number): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/src/ contains ${count} build artifacts (.d.ts, .js, .map files)`,
   fix: `find packages/${dir}/src ${SWEEP_PREDICATE} -delete`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/src/`,
 });
 
@@ -209,7 +207,7 @@ export const noFilesAllowlistFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json publishes with no "files" allowlist, so the tarball carries whatever is in the directory`,
   fix: `add "files": ["src", "${TEST_EXCLUSION}", "README.md", "LICENSE"] to packages/${dir}/package.json`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 

package/src/workspace-graph.ts

@@ -4,6 +4,7 @@
 // for `tsc` and is invisible to bun, to `--filter` ordering and to any change-detection tool.
 
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
 import { maskLiterals } from './ts-scan';
@@ -184,7 +185,7 @@ export const unreadableWorkspaceFinding = (path: string): Finding => ({
   code: 'X_APP_PACKAGE_INVALID',
   cause: `${path} is claimed by the root "workspaces" globs and supplies no readable "name"`,
   fix: `repair the JSON and the "name" in ${path}, or drop its directory from "workspaces" in package.json`,
-  docs: 'https://ultimate.dev/errors/X_APP_PACKAGE_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -198,7 +199,7 @@ export const undeclaredWorkspaceDepFinding = (
   // The exact line to paste, at the version the target really carries: a `workspace:*` range would
   // resolve and then fail `checkLockstep`, which compares a sibling pin against the version.
   fix: `add "${to.name}": "${to.version ?? '0.0.0'}" to "dependencies" in ${from.dir}/package.json`,
-  docs: 'https://ultimate.dev/errors/X_WORKSPACE_DEP_UNDECLARED',
+  docs: ERROR_DOCS_URL,
   at: `${from.dir}/package.json`,
 });
 

package/src/write-line.ts

@@ -5,6 +5,9 @@
 
 // `node:fs`, and unavoidable: Bun has no synchronous stdout write of its own.
 import { writeSync } from 'node:fs';
+// The one import beyond `node:fs`, and it costs nothing here: `create-ultimate` reaches this
+// module through `@ultimat3/cli`'s barrel, which has already evaluated core.
+import { stringField } from '@ultimat3/core';
 
 /**
  * Write to stdout and be certain it arrived, even if the next statement exits the process.
@@ -29,7 +32,10 @@ function writeTo(fd: 1 | 2, line: string): void {
     try {
       written += writeSync(fd, buffer, written, buffer.length - written);
     } catch (cause) {
-      if ((cause as NodeJS.ErrnoException).code !== 'EAGAIN') throw cause;
+      // `stringField`, never a cast plus a property read — the rule `metrics-endpoint.ts` states
+      // and `caught-value-reads.test.ts` enforces. Here it is also the difference between
+      // rethrowing and an infinite loop: a `code` that cannot be read must not read as `EAGAIN`.
+      if (stringField(cause, 'code') !== 'EAGAIN') throw cause;
     }
   }
 }