@ultimat3/cli 9.0.0 → 11.0.0

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-mcp-package.ts

@@ -2,6 +2,7 @@
 // action registry rather than re-listed, plus the test that pins every projected tool describing
 // itself.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { packageShapeFiles } from './scaffold-package-shape';
 
@@ -44,9 +45,11 @@ const mcpIndex = (
   app: NameSet,
 ): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
 // read-only helpers here. Authorization is the action's policy, unchanged.
-import * as api from '@${app.kebab}/web/api/health';
-import { registerActions } from '@ultimat3/action';
-import { defineAppMcp } from '@ultimat3/mcp';
+${sortedImports([
+  `import * as api from '@${app.kebab}/web/api/health';`,
+  `import { registerActions } from '@ultimat3/action';`,
+  `import { defineAppMcp } from '@ultimat3/mcp';`,
+])}
 
 // Names come from export names, so the registry agrees with the module the app already wrote.
 registerActions(api);

package/src/templates/scaffold-repo.ts

@@ -63,6 +63,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/core": "^${version}",
     "@ultimat3/db": "^${version}",
     "@ultimat3/entity": "^${version}",
+    "@ultimat3/http": "^${version}",
     "@ultimat3/i18n": "^${version}",
     "@ultimat3/jobs": "^${version}",
     "@ultimat3/mcp": "^${version}",
@@ -123,13 +124,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 +163,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,
@@ -26,6 +27,7 @@ import { checkSourceDrift } from './drift';
 import { checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
+import { liveRouteFindings } from './live-routes';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -170,7 +172,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'budgets',
-    summary: 'per-route JS bytes and LCP, and the global style layer every document carries',
+    summary:
+      'per-route JS bytes and LCP, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
     // The global-style assertion rides here rather than becoming an eighteenth step, because this
     // step already asks the one question it asks: what does the document this build emits actually
     // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
@@ -201,6 +204,10 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       return fromFindings([
         ...findings,
         ...checkDocumentStyles(documentSurfaces()),
+        // The third rider, and the same question this step already asks one level down: what
+        // JavaScript does this route's document boot? A live read with no island is a route
+        // whose answer is "none", which no suite can fail on — the page renders, at 200.
+        ...(await liveRouteFindings(ctx.root)),
         ...checkBudgets(manifest, stats),
       ]);
     },
@@ -330,7 +337,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 +351,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;
     }
   }
 }