@ultimat3/cli 15.0.0 → 17.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "15.0.0",
+  "version": "17.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "15.0.0",
-    "@ultimat3/admin": "15.0.0",
-    "@ultimat3/ai": "15.0.0",
-    "@ultimat3/auth": "15.0.0",
-    "@ultimat3/cache": "15.0.0",
-    "@ultimat3/core": "15.0.0",
-    "@ultimat3/db": "15.0.0",
-    "@ultimat3/entity": "15.0.0",
-    "@ultimat3/flags": "15.0.0",
-    "@ultimat3/http": "15.0.0",
-    "@ultimat3/i18n": "15.0.0",
-    "@ultimat3/jobs": "15.0.0",
-    "@ultimat3/mail": "15.0.0",
-    "@ultimat3/manifest": "15.0.0",
-    "@ultimat3/mcp": "15.0.0",
-    "@ultimat3/money": "15.0.0",
-    "@ultimat3/notify": "15.0.0",
-    "@ultimat3/policy": "15.0.0",
-    "@ultimat3/pwa": "15.0.0",
-    "@ultimat3/query": "15.0.0",
-    "@ultimat3/realtime": "15.0.0",
-    "@ultimat3/render": "15.0.0",
-    "@ultimat3/schema": "15.0.0",
-    "@ultimat3/scraping": "15.0.0",
-    "@ultimat3/seo": "15.0.0",
-    "@ultimat3/storage": "15.0.0",
-    "@ultimat3/testing": "15.0.0",
-    "@ultimat3/time": "15.0.0",
+    "@ultimat3/action": "17.0.0",
+    "@ultimat3/admin": "17.0.0",
+    "@ultimat3/ai": "17.0.0",
+    "@ultimat3/auth": "17.0.0",
+    "@ultimat3/cache": "17.0.0",
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/db": "17.0.0",
+    "@ultimat3/entity": "17.0.0",
+    "@ultimat3/flags": "17.0.0",
+    "@ultimat3/http": "17.0.0",
+    "@ultimat3/i18n": "17.0.0",
+    "@ultimat3/jobs": "17.0.0",
+    "@ultimat3/mail": "17.0.0",
+    "@ultimat3/manifest": "17.0.0",
+    "@ultimat3/mcp": "17.0.0",
+    "@ultimat3/money": "17.0.0",
+    "@ultimat3/notify": "17.0.0",
+    "@ultimat3/policy": "17.0.0",
+    "@ultimat3/pwa": "17.0.0",
+    "@ultimat3/query": "17.0.0",
+    "@ultimat3/realtime": "17.0.0",
+    "@ultimat3/render": "17.0.0",
+    "@ultimat3/schema": "17.0.0",
+    "@ultimat3/scraping": "17.0.0",
+    "@ultimat3/seo": "17.0.0",
+    "@ultimat3/storage": "17.0.0",
+    "@ultimat3/testing": "17.0.0",
+    "@ultimat3/time": "17.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/dev-roles.ts

@@ -14,6 +14,7 @@ import {
   configuredHttp,
   createServer,
   defineHttpConfig,
+  MAX_PROXY_HOPS,
   mergeHttpConfig,
 } from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
@@ -188,6 +189,23 @@ function warnIfUnauthenticatable(routes: readonly Route[]): void {
   );
 }
 
+/**
+ * How many proxies is too many, and the number is **`@ultimat3/http`'s**, not this file's.
+ *
+ * `defineHttpConfig` screens the same setting — `assertFiniteCount('trustedProxyHops', …,
+ * MAX_PROXY_HOPS)` — and this screen used to say 16 where that one says 64, so one setting had two
+ * ceilings and a deployment behind 20 hops was accepted by the library and refused by the boot.
+ * Widened rather than narrowed: tightening the library would break a shipped public API, while
+ * this end only ever refused topologies http already supports.
+ *
+ * It was a duplicated literal until 2026-08-26, because `@ultimat3/http` did not export the
+ * constant. It does now, so this file IMPORTS it — a downward edge, tier 5 to tier 2 — and there is
+ * no second number left to drift. `runtime-overrides.test.ts` still probes both screens for the
+ * highest count each accepts, and it is kept rather than deleted: it compares BEHAVIOUR, so it also
+ * catches the two disagreeing for a reason a shared constant cannot fix, such as one side gaining a
+ * range check the other does not have.
+ */
+
 /**
  * How many proxies append to `x-forwarded-for` between the client and this process, or `null`
  * when nothing in front of it is trusted.
@@ -207,7 +225,7 @@ export function trustedHopsFromEnv(env: Env): number | null {
   const hops = Number(raw);
   // A malformed count is refused rather than defaulted: reading the header at the wrong index is
   // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
-  if (!Number.isInteger(hops) || hops < 1 || hops > 16) {
+  if (!Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
     throw new PortInvalidError({ value: raw, name: 'TRUSTED_PROXY_HOPS' });
   }
   return hops;

package/src/dev-traces.ts

@@ -5,6 +5,7 @@
 
 import type { RequestTrace, SpanKind, TimelineSpan } from '@ultimat3/admin/dev';
 import type { ReadableSpan, SpanExporter } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 // The attribute name is `@ultimat3/db`'s to declare — this reads it rather than restating it, so
 // renaming it there is a compile error here instead of a panel that silently groups nothing.
 import { STATEMENT_ATTRIBUTE } from '@ultimat3/db';
@@ -130,7 +131,10 @@ function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTra
  * root is what keeps a half-finished request, and a job's spans, out of a panel about requests.
  */
 export function createTraceRecorder(options: { limit?: number } = {}): TraceRecorder {
-  const limit = options.limit ?? DEFAULT_LIMIT;
+  // `byTrace.size > NaN` is false on every pass, so an unchecked limit does not widen the buffer —
+  // it deletes the eviction loop, and a dev session then holds every span of every request it has
+  // ever seen. At least 1: a recorder that retains nothing is what `/_x/timeline` reads.
+  const limit = finiteCount('createTraceRecorder', 'limit', options.limit ?? DEFAULT_LIMIT, 1);
   // Insertion-ordered: the oldest trace id is the first key, which is the one eviction drops.
   const byTrace = new Map<string, ReadableSpan[]>();
 

package/src/e2e-page.ts

@@ -2,6 +2,7 @@
 // e2e test drives and `@ultimat3/scraping` owns the only driver that can drive one, and neither
 // may import the other — so the join is here, in the one package allowed to know about both.
 
+import { finiteCount } from '@ultimat3/core';
 import type { LocatorLike, PageLike } from '@ultimat3/testing';
 import { E2eServiceWorkerAbsentError } from './e2e-errors';
 import { evaluateClosure } from './e2e-evaluate';
@@ -30,6 +31,9 @@ export interface E2ePageOptions {
   readonly serviceWorkerTimeoutMs?: number | undefined;
 }
 
+/** Named once, so both refusals below name the call an app's test preload actually makes. */
+const SUBJECT = 'installE2eDriver';
+
 export const DEFAULT_E2E_TIMEOUT_MS = 30_000;
 export const DEFAULT_SERVICE_WORKER_TIMEOUT_MS = 10_000;
 
@@ -82,8 +86,18 @@ const serviceWorkerExpression = (timeoutMs: number): string =>
  */
 export function e2ePage(options: E2ePageOptions): PageLike {
   const page = options.page;
-  const timeout = options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS;
-  const swTimeout = options.serviceWorkerTimeoutMs ?? DEFAULT_SERVICE_WORKER_TIMEOUT_MS;
+  // Both are screened HERE, at construction, and not where they land: `timeout` is handed to a
+  // driver that reads it as a deadline, and `swTimeout` is INTERPOLATED into the in-page source,
+  // where `setTimeout(fn, NaN)` is `setTimeout(fn, 0)` — so a NaN budget makes every
+  // `waitForServiceWorker()` refuse a worker that really did take control. A misdiagnosis reported
+  // as a test failure is worse than the failure. Floor 0, because a driver reads `timeout: 0` as
+  // "no deadline" and that is a value an app is entitled to declare.
+  const timeout = finiteCount(SUBJECT, 'timeoutMs', options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS);
+  const swTimeout = finiteCount(
+    SUBJECT,
+    'serviceWorkerTimeoutMs',
+    options.serviceWorkerTimeoutMs ?? DEFAULT_SERVICE_WORKER_TIMEOUT_MS,
+  );
   const absolute = (url: string): string => new URL(url, options.baseUrl).toString();
   const locate = (selection: E2eSelection): LocatorLike => e2eLocator(page, selection);
 

package/src/island-shot.ts

@@ -5,6 +5,7 @@
 
 // why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
 import { join } from 'node:path';
+import { finiteCount } from '@ultimat3/core';
 import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { systemScrapeClock } from '@ultimat3/scraping';
 import type { IslandShotTarget, IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
@@ -157,6 +158,7 @@ async function captureOne(
   options: IslandShotRun,
   server: ShotServer,
   target: IslandShotTarget,
+  floor: number,
 ): Promise<IslandStateShot> {
   const url = new URL(`${ISLAND_HARNESS_PATH}${target.query}`, server.url).toString();
   let session: ScrapeSession | undefined;
@@ -203,7 +205,6 @@ async function captureOne(
     // Never `fullPage`: the frame is the state's own declared viewport, and a full-page capture
     // would grow with whatever the component scrolled.
     const bytes = await page.screenshot({ fullPage: false });
-    const floor = options.minBytes ?? MIN_SHOT_BYTES;
     if (bytes.byteLength < floor) {
       throw new IslandUnphotographableError({
         island: target.island,
@@ -257,6 +258,11 @@ export async function runIslandShot(options: IslandShotRun): Promise<IslandArtif
   const targets = islandShotTargets(options.manifest).filter(
     (target) => chosen === null || chosen.has(target.state),
   );
+  // Before the boot, and before a browser: `bytes.byteLength < NaN` is false for every picture, so
+  // an unchecked floor does not lower the backstop — it removes it, and "produced nothing and
+  // exited 0" is the one outcome a reader cannot tell from success. 0 stays legal and is what
+  // `island-shot.test.ts` passes: the fake driver answers an 8-byte PNG signature.
+  const floor = finiteCount('runIslandShot', 'minBytes', options.minBytes ?? MIN_SHOT_BYTES);
   const server = await options.boot();
   const shots: IslandStateShot[] = [];
   const failures: unknown[] = [];
@@ -266,7 +272,7 @@ export async function runIslandShot(options: IslandShotRun): Promise<IslandArtif
       // the app CAN produce plus a named reason for each one it cannot, and the missing-shot gate
       // below is what turns those reasons into a non-zero exit.
       try {
-        shots.push(await captureOne(options, server, target));
+        shots.push(await captureOne(options, server, target, floor));
       } catch (error) {
         failures.push(error);
       }

package/src/metrics-endpoint.ts

@@ -3,6 +3,7 @@
 // `docker/helm`'s HPAs read a number instead of `<unknown>`.
 
 import {
+  finiteCount,
   logger,
   METRICS_CONTENT_TYPE,
   METRICS_PATH,
@@ -78,7 +79,11 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // Screened here rather than left to `Bun.serve`, which refuses a `NaN` with a bare `RangeError`
+  // — no code, no `fix:` — at exactly the boot path the refusal below exists to stop reporting
+  // that way. Floor 0, because 0 asks the kernel for a free port and `dev-roles.ts` passes it for
+  // an ephemeral boot; the ceiling stays Bun's, which names the range it refuses.
+  const port = finiteCount('startMetricsEndpoint', 'port', options.port ?? DEFAULT_METRICS_PORT);
   // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
   // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
   // The return type is inferred, keeping `Bun.serve`'s own shape stated once.

package/src/sync-authenticator.ts

@@ -5,7 +5,7 @@
 // by wiring, not by design.
 
 import type { Actor, Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -102,7 +102,13 @@ export function syncAuthenticator(
   // this per connection otherwise.
   const config = upgradeConfig(buildId);
   const clock = options.clock ?? systemClock;
-  const ttlMs = options.ttlMs ?? SYNC_GRANT_TTL_MS;
+  // A credential lifetime, screened where it is declared. `expiresAt` is `now + ttlMs`, and
+  // `GrantBook.expired()` asks `expiresAt <= now` — false for every `now` when the sum is `NaN`,
+  // so the grant never reaches a sweep and the socket keeps a revoked actor's authority for as
+  // long as the tab is open. That is the hole this whole file was written to close, and a `??`
+  // does not close it: `NaN` is not nullish. At least 1ms — a window that has already shut when
+  // the grant is minted is not a window.
+  const ttlMs = finiteCount('syncAuthenticator', 'ttlMs', options.ttlMs ?? SYNC_GRANT_TTL_MS, 1);
 
   const resolve = async (credential: Credential): Promise<SyncGrant | null> => {
     const request = new Request(credential.url, {