@ultimat3/cli 8.0.0 → 10.0.0

package/src/dev-runtime.ts

@@ -4,6 +4,8 @@
 // boot installs, only backed by embedded drivers.
 
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { configureAuthLimiters, postgresAuthLimiter, resetAuthLimiters } from '@ultimat3/auth';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
 import {
@@ -11,6 +13,7 @@ import {
   registerReadinessCheck,
   renderThrowable,
   resolveEnvironment,
+  systemClock,
 } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
 import { postgresRateLimitStore } from '@ultimat3/http';
@@ -27,7 +30,8 @@ import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
 import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
-import { startCacheTiers } from './dev-cache';
+import { loadCacheTiers, startCacheTiers } from './dev-cache';
+import { installRetentionSweep } from './dev-purge';
 import type { DevDbClient } from './dev-queue';
 import { pgExecutorFor, startQueue } from './dev-queue';
 import type { DevServices, Env } from './dev-services';
@@ -182,8 +186,14 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   // missing" from a helper the operator never configured. Not an outright ban on the local disk in
   // production: a single-node Compose deploy on a mounted volume WITH a real secret is a rung on
   // the scale ladder, and refusing it would be a deploy-shape decision, not a security fix.
-  if (!isLocal() && usesDevStorageSecret()) {
-    throw new LocalDiskUnsafeError({ environment: resolveEnvironment(), root });
+  // `{ env }` on ALL THREE, never the ambient `process.env`: this function is HANDED the boot's
+  // environment and reads `S3_BUCKET` off it one branch above, so a guard asking a second source
+  // could answer `development` for a process booting as `production` — or, with
+  // `usesDevStorageSecret({ env })` left bare, refuse a boot whose own env carries a real
+  // `STORAGE_SIGNING_SECRET` because the PROCESS does not. Which environment, whether a secret
+  // exists, and the name the message prints are one question about one table.
+  if (!isLocal({ env }) && usesDevStorageSecret({ env })) {
+    throw new LocalDiskUnsafeError({ environment: resolveEnvironment({ env }), root });
   }
   try {
     mkdirSync(root, { recursive: true });
@@ -194,7 +204,9 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
       `mount a writable volume at ${root}, or set S3_ENDPOINT and S3_BUCKET to use object storage instead`,
     );
   }
-  return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
+  // The guard three lines up reads `env`; so must the disk it guards. Otherwise the boot's
+  // environment decides whether signing is allowed and the process's decides what key is used.
+  return defineStorage({ disks: { local: localDriver({ root, env }) }, default: 'local' });
 }
 
 /**
@@ -288,16 +300,45 @@ export async function startServices(
   const bus: TransportSelection = selectTransport(env);
   const queue = await startQueue(services, overrides);
   const { db, jobs, outbox, events } = queue;
+  // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
+  // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
+  // `undefined`), one wrapper.
+  const executor = pgExecutorFor(db);
+  const rateLimitStore = postgresRateLimitStore({ executor });
   // Boot is a sequence of external resources, and every step after the first can reject — the
   // queue is already up, so from here an unwind must release it exactly like everything after it.
+  // Which is why the `try` opens on the NEXT line and not eight steps further down: it did, and
+  // the steps above it registered process-wide state (`configureAuthLimiters`, the `purge()` job
+  // and its `task`) that throws on a name a previous boot in this process left in the registry —
+  // `X_JOB_NAME_TAKEN`, outside the unwind, so `x dev` exited holding the PGlite lock, the pool
+  // and the ambient accessors. Nothing may be pushed onto `started` from outside this block.
   const started: (() => void | Promise<void>)[] = [() => queue.stop()];
-  // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
-  // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
-  // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
-  // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
-  // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
-  started.push(probedReadinessCheck('database', () => db.ping()));
   try {
+    // Where failed sign-ins are counted, installed BEFORE `loadApp` for the reason the idempotency
+    // store is: `defineAuth` is the app's call and it runs when the app's modules import, so a seam
+    // filled afterwards is one every app would have to fill itself. A FACTORY and not a limiter —
+    // the app declares `maxAttempts`/`windowMs`/`lockoutMs` and this boot has not read them yet, so
+    // a limiter built here would be refused by `assertAuthLimiterPolicy` on any app that tuned one.
+    //
+    // Until this line every deployment the framework produces counted lockouts per POD, while
+    // `x new` scaffolds `replicas: 2` and `docker/helm` runs three — `maxAttempts × N` guesses per
+    // account, and a lockout one replica established invisible to the rest.
+    configureAuthLimiters((policy) =>
+      postgresAuthLimiter({ executor, clock: systemClock, policy }),
+    );
+    started.push(() => resetAuthLimiters());
+    // The hourly sweep over the three framework tables this boot is responsible for. Every one of
+    // them ships a `purgeExpired()` that nothing called, so every row written was a row kept —
+    // `x_rate_limit` takes one upsert per request the web role serves, assets included.
+    started.push(
+      installRetentionSweep({ idempotency: queue.idempotency, rateLimit: rateLimitStore }),
+    );
+    // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
+    // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
+    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+    // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
+    // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
+    started.push(probedReadinessCheck('database', () => db.ping()));
     // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
     // first change nobody receives, and the socket is a resource the unwind below has to release.
     // A supplied transport is already connected and is NOT closed here: whoever built it owns its
@@ -331,7 +372,13 @@ export async function startServices(
     // recomputed every cached read. Released with `resetTiers()`, which drops the whole registry:
     // this boot is the only thing that registers one, and a tier left behind would purge for a
     // process that has stopped.
-    started.push(startCacheTiers({ env, purge, transport }));
+    // The ladder is the app's declaration, never the environment's. `cache.tiers` was declared,
+    // validated and documented while NOTHING read it — so an app asking for one rung got four,
+    // and one asking for a shared tier got whatever `REDIS_URL` happened to say. `.x` is
+    // `resolveServices`' own join, so its parent is the app root: the one fact this function needs
+    // and does not already carry.
+    const tiers = await loadCacheTiers(dirname(services.stateDir));
+    started.push(startCacheTiers({ env, purge, transport, tiers }));
 
     return {
       services,
@@ -343,12 +390,12 @@ export async function startServices(
       storage,
       mail,
       mailDetail: selection.detail,
+      // Built above, beside the auth limiter factory and the retention sweep that purges its
+      // table: three readers of one executor, resolved once. `startWeb` is what an override
+      // replaces it at.
+      rateLimitStore,
       // The env key that selected the bus — or the honest answer that no env key did, because a
       // boot line reading `NATS_URL` over a transport the host handed in is a lie a script parses.
-      // The same executor the jobs driver, the outbox, the event bus and the idempotency store
-      // run on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
-      // `undefined`), one wrapper. `startWeb` is what an override replaces it at.
-      rateLimitStore: postgresRateLimitStore({ executor: pgExecutorFor(db) }),
       transportDetail: overrides?.transport === undefined ? bus.detail : 'runtime override',
       presenceTtlMs: bus.presenceTtlMs,
       purge,

package/src/dev-storage.ts

@@ -151,8 +151,14 @@ export function parseByteRange(
   if (from === '' && to === '') return undefined;
   if (from === '') {
     const wanted = Number(to);
-    // A suffix longer than the object is the whole object, not a refusal.
-    return wanted === 0 ? UNSATISFIABLE : { start: Math.max(size - wanted, 0), end: size - 1 };
+    // A suffix longer than the object is the whole object, not a refusal — but there is no whole
+    // object to fall back to at `size === 0`, and the arithmetic below answers `{ start: 0, end:
+    // -1 }`, which the route renders as `content-range: bytes 0--1/0` with status 206. RFC 9110
+    // requires 416. The non-suffix branch already gets this right through `start >= size`; this
+    // one had no equivalent test.
+    return size === 0 || wanted === 0
+      ? UNSATISFIABLE
+      : { start: Math.max(size - wanted, 0), end: size - 1 };
   }
   const start = Number(from);
   const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);

package/src/dev-sync.ts

@@ -2,7 +2,7 @@
 // Split from `dev-roles.ts` because it is the one role with an authenticator, a presence registry
 // and a listener of its own — and because that file is the boot's index, not its detail.
 
-import { createContext, logger } from '@ultimat3/core';
+import { createContext, logger, UltimateError } from '@ultimat3/core';
 import { listQueries } from '@ultimat3/query';
 import {
   ChannelHub,
@@ -15,8 +15,43 @@ import {
   SocketRegistry,
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
+import { neighbouringPort, PORT_RANGE } from './flag-number';
 import { syncAuthenticator } from './sync-authenticator';
 
+/**
+ * Beside its one thrower rather than in `errors.ts`, which is at 461 of the 500-line ceiling —
+ * the arrangement `db-seed.ts` and `metrics-endpoint.ts` already take. The code is
+ * `X_PORT_INVALID`, this package's own: "the port asked for is not one" is what it already means,
+ * and a second code for the same fact is the synonym the registry exists to prevent.
+ */
+class SyncPortUnavailableError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_INVALID',
+      cause: `the sync role binds PORT + 1, and PORT=${input.port} is the top of the range — it would ask for ${input.port + 1}, which is not a TCP port`,
+      fix: `x dev --port ${neighbouringPort(input.port)}   # leaves ${PORT_RANGE.max} free for the sync node`,
+      meta: { port: input.port },
+    });
+  }
+}
+
+/**
+ * The port the sync node listens on. `PORT + 1`, and `0` stays `0` — the kernel picks, and adding
+ * one to it would pick a specific port instead.
+ *
+ * REFUSED at the top of the range, never clamped. `PORT_RANGE.max` is 65535 and `portValue`
+ * accepts it, so `x dev --port 65535` handed `Bun.serve` 65536 and the bare `RangeError` reached
+ * the terminal as `X_CLI_UNEXPECTED` with `fix: x doctor --json`. Clamping to 65534 would be worse
+ * than refusing: `PORT + 1` is the rule `docker/docker-compose.prod.yml` publishes `3001:3001`
+ * from and `docker/helm` derives `PORT = .port - 1` from, so a node quietly on `PORT - 1` is a
+ * socket nothing else in the deployment computes.
+ */
+export function syncPortFor(port: number): number {
+  if (port === 0) return 0;
+  if (port >= PORT_RANGE.max) throw new SyncPortUnavailableError({ port });
+  return port + 1;
+}
+
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
@@ -97,7 +132,7 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   });
   await node.start();
   try {
-    const listener = listenSyncNode(node, { port: options.port === 0 ? 0 : options.port + 1 });
+    const listener = listenSyncNode(node, { port: syncPortFor(options.port) });
     return {
       url: listener.url,
       stop: async () => {

package/src/document-styles.ts

@@ -4,8 +4,10 @@
 // browser drops every one of those declarations from, byte-for-byte identical to a working page
 // apart from the styling nobody sees missing. A silent failure is exactly what axiom 3 exists for.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Surface } from '@ultimat3/render';
-import { routeEntries, stylesFor } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 import type { Finding } from './output';
 
 /** The stylesheet an app is expected to own, named in the fix so it is one edit, not a hunt. */
@@ -48,7 +50,7 @@ export function checkDocumentStyles(documents: readonly SurfaceDocument[]): read
       code: 'X_STYLES_GLOBAL_MISSING',
       cause: `a ${document.surface}/ document carries ${document.css.length} characters of CSS and defines no :root custom properties, so every var(--color-*) and var(--space-*) in it resolves to nothing`,
       fix: `add apps/web/${APP_GLOBAL_STYLESHEET} containing \`@use '@ultimat3/ui/global.scss';\` and apps/web/${APP_GLOBAL_MODULE} containing \`import './global.scss';\``,
-      docs: 'https://ultimate.dev/errors/X_STYLES_GLOBAL_MISSING',
+      docs: ERROR_DOCS_URL,
       at: `apps/web/${APP_GLOBAL_STYLESHEET}`,
     }));
 }

package/src/drift.ts

@@ -11,6 +11,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
 import { loadApp } from './app-load';
@@ -181,7 +182,7 @@ export async function checkSourceDrift(
         code: 'X_DB_DRIFT',
         cause: 'packages/db has a schema but no migration recorded it',
         fix: 'x db gen "initial"',
-        docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+        docs: ERROR_DOCS_URL,
         at: MIGRATIONS_DIR,
       },
     ];
@@ -192,7 +193,7 @@ export async function checkSourceDrift(
       code: 'X_DB_DRIFT',
       cause: `schema hashes to ${current}, newest migration ${latest.file} recorded ${latest.hash}`,
       fix: 'x db gen "describe the change"',
-      docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+      docs: ERROR_DOCS_URL,
       at: `${DB_PACKAGE}/src`,
     },
   ];

package/src/error-codes.ts

@@ -1,5 +1,5 @@
 // The X_* codes owned by @ultimat3/cli, and nothing else: the two lists, their titles, the one
-// registration call and `docsFor`. Every code names the exact command that resolves it, because
+// registration call. Every code names the exact command that resolves it, because
 // the CLI is the surface an agent reads first — a failure here has to be actionable without a doc
 // lookup or a second round-trip. The classes that throw these codes live in `./errors`.
 import { registerErrorCodes } from '@ultimat3/core';
@@ -217,4 +217,11 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(CLI_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-export const docsFor = (code: CliErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// This file exports NO `docsFor(code)`, and adding one back is the defect. A CLI error passes no
+// `docs:` at all — `UltimateError` fills it from `describeErrorCode(code).docs`, which is
+// `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every code, never one per code, because `wiki/`
+// is the framework's only public documentation surface and a code lives there in a TABLE ROW, which
+// has no anchor. A `Finding` is a plain object with no constructor to fill it, so it carries
+// `ERROR_DOCS_URL` imported from core — the same constant, not a second copy of it. The
+// `https://ultimate.dev/errors/<code>` links `docsFor` built until 9.x answered 404, host included,
+// on every error the CLI has ever thrown.

package/src/error-contract.ts

@@ -6,7 +6,7 @@
 
 // `join` is `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
 import { createHelperResolver } from './fix-imports';
 import { scanFixSites } from './fix-scan';
@@ -63,7 +63,7 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
   code: 'X_ERROR_FIX_INVALID',
   cause: problem,
   fix: `rewrite the fix at ${site.at}:${site.line} as a command to run, a call to paste, or an edit naming a file`,
-  docs: docsFor('X_ERROR_FIX_INVALID'),
+  docs: ERROR_DOCS_URL,
   at: `${site.at}:${site.line}`,
 });
 
@@ -132,7 +132,7 @@ const undocumentedFinding = (code: string, at: string, line: number, page: strin
   code: 'X_ERROR_CODE_UNDOCUMENTED',
   cause: `${code} is declared at ${at}:${line} and ${page} has no entry for it`,
   fix: `add a row for ${code} to ${page}, with its cause and the command that fixes it`,
-  docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -163,7 +163,7 @@ const unregisteredFinding = (code: string, page: string): Finding => ({
   code: 'X_ERROR_CODE_UNREGISTERED',
   cause: `${page} documents ${code} as a live code and nothing registers it, so "x errors explain ${code}" refuses a code this page promises`,
   fix: `register ${code} through registerErrorCodes() in its package's src/errors.ts, or move its row under "${RESERVED_HEADING}" in ${page}`,
-  docs: docsFor('X_ERROR_CODE_UNREGISTERED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -249,7 +249,7 @@ export async function checkErrorCodeDocs(root: string, page: string): Promise<re
         code: 'X_ERROR_CODE_UNDOCUMENTED',
         cause: `the error reference ${page} does not exist, so no code can be documented`,
         fix: `create ${page} with a row per X_* code, or stop naming it as the error reference`,
-        docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+        docs: ERROR_DOCS_URL,
         at: page,
       },
     ];

package/src/errors.ts

@@ -2,7 +2,6 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -11,7 +10,6 @@ export class UnknownCommandError extends UltimateError {
       code: 'X_CLI_UNKNOWN_COMMAND',
       cause: `"x ${input.path}" is not a command (known: ${input.known.join(', ')})`,
       fix: input.suggestion === undefined ? 'x help' : `x ${input.suggestion}`,
-      docs: docsFor('X_CLI_UNKNOWN_COMMAND'),
     });
   }
 }
@@ -27,7 +25,6 @@ export class BadFlagError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `--${input.flag} on "x ${input.command}": ${input.reason}`,
       fix: input.fix ?? `x ${input.command} --help`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -46,7 +43,6 @@ export class MissingPositionalError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" needs a <${input.positional}> positional and got none`,
       fix: input.example,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -70,7 +66,6 @@ export class MissingSubcommandError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" takes a subcommand and got none (one of: ${input.known.join(', ')})`,
       fix: `x help ${input.command}`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -82,7 +77,6 @@ export class VerifyFailedError extends UltimateError {
       code: 'X_VERIFY_FAILED',
       cause: `${input.failed.length} verify step(s) failed: ${input.failed.join(', ')}`,
       fix: 'x verify --json',
-      docs: docsFor('X_VERIFY_FAILED'),
     });
   }
 }
@@ -94,7 +88,6 @@ export class NotInAppError extends UltimateError {
       code: 'X_NOT_IN_APP',
       cause: `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
       fix: 'x new myapp && cd myapp',
-      docs: docsFor('X_NOT_IN_APP'),
     });
   }
 }
@@ -106,7 +99,6 @@ export class BunVersionError extends UltimateError {
       code: 'X_BUN_VERSION',
       cause: `Bun ${input.found} is older than the required ${input.required}`,
       fix: 'bun upgrade',
-      docs: docsFor('X_BUN_VERSION'),
     });
   }
 }
@@ -127,7 +119,6 @@ export class NoTestFilesError extends UltimateError {
       code: 'X_TEST_NO_FILES',
       cause: `no *.test.ts files${where} under ${input.root}`,
       fix: parts.length === 0 ? 'x test --json   # run it from the repo root' : 'x test',
-      docs: docsFor('X_TEST_NO_FILES'),
     });
   }
 }
@@ -146,7 +137,6 @@ export class ScaffoldPathEscapeError extends UltimateError {
       fix:
         input.fix ??
         `make the path relative to the app root with no ".." segment, then re-run: bun test packages/cli/src/scaffold-typecheck.contract.test.ts`,
-      docs: docsFor('X_SCAFFOLD_PATH_ESCAPE'),
     });
   }
 }
@@ -163,7 +153,6 @@ export class GenerateJsonInvalidError extends UltimateError {
       code: 'X_GENERATE_JSON_INVALID',
       cause: `${input.path} is declared merge: 'json' but the generator's own contents for it do not parse as a JSON object`,
       fix: `fix the template that emits ${input.path}, then re-run: bun test packages/cli/src/cmd-generate.test.ts`,
-      docs: docsFor('X_GENERATE_JSON_INVALID'),
     });
   }
 }
@@ -182,7 +171,6 @@ export class CatalogExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists`,
       fix: `x i18n sync ${input.locale}`,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }
@@ -198,7 +186,6 @@ export class AppPackageInvalidError extends UltimateError {
       code: 'X_APP_PACKAGE_INVALID',
       cause: `${input.path} ${input.problem}, so the manifest has no app name or version to gate on`,
       fix: 'bun pm pkg set name=my-app version=0.1.0',
-      docs: docsFor('X_APP_PACKAGE_INVALID'),
     });
   }
 }
@@ -216,7 +203,6 @@ export class ErrorCodeUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x errors list --json'
           : `x errors explain ${input.suggestion}`,
-      docs: docsFor('X_ERROR_CODE_UNKNOWN'),
     });
   }
 }
@@ -243,7 +229,6 @@ export class DeclarationUnknownError extends UltimateError {
         input.suggestion === undefined
           ? `x ${input.kind} list --json`
           : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
-      docs: docsFor('X_DECLARATION_UNKNOWN'),
     });
   }
 }
@@ -255,7 +240,6 @@ export class JobUnknownError extends UltimateError {
       code: 'X_JOB_UNKNOWN',
       cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
       fix: 'x jobs ls --json',
-      docs: docsFor('X_JOB_UNKNOWN'),
     });
   }
 }
@@ -274,7 +258,6 @@ export class FixTargetUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x routes --json   # every registered route file, app-root-relative'
           : `x fix boundary ${input.suggestion}`,
-      docs: docsFor('X_FIX_TARGET_UNKNOWN'),
     });
   }
 }
@@ -290,7 +273,6 @@ export class BuildEntryMissingError extends UltimateError {
       code: 'X_BUILD_ENTRY_MISSING',
       cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
       fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-      docs: docsFor('X_BUILD_ENTRY_MISSING'),
     });
   }
 }
@@ -306,7 +288,6 @@ export class IslandBuildFailedError extends UltimateError {
       code: 'X_BUILD_FAILED',
       cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
       fix: `bun build --target browser ${input.file}`,
-      docs: docsFor('X_BUILD_FAILED'),
     });
   }
 }
@@ -321,7 +302,6 @@ export class RoleUnknownError extends UltimateError {
       code: 'X_ROLE_UNKNOWN',
       cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
       fix: `docker run -e ROLE=web my-app:latest   # one of: ${input.known.join(', ')}`,
-      docs: docsFor('X_ROLE_UNKNOWN'),
     });
   }
 }
@@ -344,7 +324,6 @@ export class RuntimeDriverSplitError extends UltimateError {
       // queues, and "they match" is exactly the reading that makes this bug invisible.
       cause: `an app module installed a ${input.driver} driver (ambient: "${input.ambient}") that is not the object this boot captured ("${input.captured}"), so enqueues and claims would use different queues`,
       fix: `pass the driver to the boot instead of installing it from an app module: runRole({ root, env, runtime: { ${input.driver}: yourDriver } })`,
-      docs: docsFor('X_RUNTIME_DRIVER_SPLIT'),
     });
   }
 }
@@ -362,7 +341,6 @@ export class PortInvalidError extends UltimateError {
       code: 'X_PORT_INVALID',
       cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
       fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} my-app:latest`,
-      docs: docsFor('X_PORT_INVALID'),
     });
   }
 }
@@ -382,7 +360,6 @@ export class EnvSchemaMissingError extends UltimateError {
       code: 'X_CONFIG_INVALID',
       cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
       fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-      docs: docsFor('X_CONFIG_INVALID'),
     });
   }
 }
@@ -394,7 +371,6 @@ export class CliNotImplementedError extends UltimateError {
       code: 'X_NOT_IMPLEMENTED',
       cause: `${input.feature} is not implemented in this build`,
       fix: input.fix,
-      docs: docsFor('X_NOT_IMPLEMENTED'),
     });
   }
 }
@@ -410,7 +386,7 @@ export class CliNotImplementedError extends UltimateError {
  */
 export class StorageUnwritableError extends UltimateError {
   constructor(cause: string, fix: string) {
-    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix, docs: docsFor('X_STORAGE_UNWRITABLE') });
+    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix });
   }
 }
 
@@ -435,7 +411,6 @@ export class LocalDiskUnsafeError extends UltimateError {
         `disk at ${input.root} — and with no STORAGE_SIGNING_SECRET it would sign upload grants ` +
         'with the development key published in @ultimat3/storage',
       fix: 'export S3_ENDPOINT=https://s3.example.com S3_BUCKET=my-app-uploads   # or keep the disk on a mounted volume: export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
-      docs: docsFor('X_ENV_MISSING'),
     });
   }
 }
@@ -450,7 +425,6 @@ export class SecretsEditorMissingError extends UltimateError {
       code: 'X_SECRETS_EDITOR_MISSING',
       cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
       fix: 'EDITOR=nano x secrets edit',
-      docs: docsFor('X_SECRETS_EDITOR_MISSING'),
     });
   }
 }
@@ -466,7 +440,6 @@ export class SecretsEditFailedError extends UltimateError {
       code: 'X_SECRETS_EDIT_FAILED',
       cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
       fix: 'x secrets edit',
-      docs: docsFor('X_SECRETS_EDIT_FAILED'),
     });
   }
 }
@@ -483,7 +456,6 @@ export class SecretsExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists, and x secrets init would replace it`,
       fix: input.fix,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }

package/src/flag-reads.ts

@@ -9,7 +9,7 @@
 
 // `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join, relative } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
 import { GLOBAL_FLAGS } from './parse';
@@ -64,7 +64,7 @@ const unreadFinding = (declared: DeclaredFlag, at: string): Finding => ({
   code: 'X_CLI_FLAG_UNREAD',
   cause: `x ${declared.command} declares --${declared.flag.name} ("${declared.flag.summary}") and no file in the CLI's source reads it, so the flag parses and changes nothing`,
   fix: `read it in ${at} with flag${declared.flag.type === 'boolean' ? 'Bool' : 'String'}(ctx.args, '${declared.flag.name}'), or delete it from the spec's flags`,
-  docs: docsFor('X_CLI_FLAG_UNREAD'),
+  docs: ERROR_DOCS_URL,
   at,
 });
 

package/src/generate-write.ts

@@ -7,6 +7,7 @@
 // app root, and `node:path` is the only API that resolves one. `node:fs` for the exists check.
 import { existsSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
 import { mergeJsonDeep } from './json-merge';
 import type { Finding } from './output';
@@ -125,7 +126,7 @@ async function planJsonMerge(
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
         fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };
@@ -178,7 +179,7 @@ function planFile(
         // when run, and a `fix:` is copied and pasted verbatim. Same construction as
         // `generate-kinds.ts`'s `assertSurfaceSupported`.
         fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };

package/src/guards.ts

@@ -9,7 +9,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderCauseValue, renderThrowable } from '@ultimat3/core';
 import { fixProblem } from './error-contract';
 import type { Finding } from './output';
 import type { HostCheck } from './verify-step';
@@ -105,7 +105,7 @@ const failed = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_FAILED',
   cause,
   fix: `return a finding from ${path} instead of throwing, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_FAILED',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -113,7 +113,7 @@ const invalid = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_INVALID',
   cause,
   fix: `export a \`guard\` object — { summary, check } — from ${path}, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -121,7 +121,7 @@ const findingInvalid = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_FINDING_INVALID',
   cause: `${path} returned a finding that is not one: ${cause}`,
   fix: `rewrite what ${path} returns as a code, a cause and a fix naming a command or a file, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_FINDING_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 

package/src/index.ts

@@ -221,12 +221,7 @@ export {
 } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
-export type {
-  PrerenderedPage,
-  PrerenderOptions,
-  PrerenderReport,
-  UnmeasuredRoute,
-} from './prerender';
+export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
@@ -254,6 +249,7 @@ export type {
   SkippedRoute,
   SkipReason,
   StaticReport,
+  UnmeasuredRoute,
 } from './static-report';
 export {
   parseStaticReport,