@ultimat3/cli 27.10.1 → 27.10.3

package/package.json

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

package/src/flag-number.ts

@@ -3,6 +3,7 @@
 // probed `NaN`, which `portFree` reports as free — a check that CANNOT FAIL — `x dev --port abc`
 // handed `NaN` to `Bun.serve` and bound an arbitrary port, and `x test --workers 4abc` ran four.
 
+import { UltimateError } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
@@ -80,3 +81,37 @@ export const neighbouringPort = (port: number): number =>
  */
 export const portPairAfter = (port: number): number =>
   port + 2 < PORT_RANGE.max ? port + 2 : port - 2;
+
+/**
+ * Beside its one thrower rather than in `errors.ts`, which is near its 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;
+}

package/src/metrics-endpoint.ts

@@ -3,6 +3,7 @@
 // `docker/helm`'s HPAs read a number instead of `<unknown>`. Opening it starts the process's own
 // series (`process_*`): a role that can be scraped reports what it costs.
 
+import type { Role } from '@ultimat3/core';
 import {
   BUILD_ID_HEADER,
   finiteCount,
@@ -18,7 +19,7 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { neighbouringPort } from './flag-number';
+import { neighbouringPort, PORT_RANGE, syncPortFor } from './flag-number';
 import { quoteArg } from './shell-quote';
 
 /**
@@ -55,6 +56,60 @@ export class MetricsPortInUseError extends UltimateError {
   }
 }
 
+/**
+ * The same code, for a collision the kernel may NOT report: bound to `localhost` where that names
+ * both `::1` and `127.0.0.1`, a scrape listener and a role on one number each get an address family
+ * and both succeed, and the browser's requests reach `/metrics`'s `not found` (CI, 2026-10-14). So
+ * it is refused by number, before either binds. The fix names 9090 unless a role holds it.
+ */
+// Which ports this boot's own roles bind, and a scrape port apart from them: one copy, read by
+// both openers of the scrape listener — `startRoles` and `serve.ts`, which opens it before the roles.
+
+/** A port one of this process's own roles binds — what a scrape port must never be. */
+export interface RolePort {
+  readonly role: string;
+  readonly port: number;
+}
+
+/**
+ * The web role's port, and the sync node's — `syncPortFor`'s answer, the one rule the node binds
+ * by (so it refuses the top of the range here exactly as the boot would). Port 0 reserves nothing:
+ * the kernel picks, and never a bound port.
+ */
+export function rolePorts(port: number, roles: readonly Role[]): readonly RolePort[] {
+  if (port === 0) return [];
+  return [
+    ...(roles.includes('web') ? [{ role: 'web', port }] : []),
+    ...(roles.includes('sync') ? [{ role: 'sync', port: syncPortFor(port) }] : []),
+  ];
+}
+
+/**
+ * A port a `fix:` may name: `preferred` unless a role holds it, else the first free one above every
+ * reservation, else the first below — a handful of reservations can never fill the range.
+ */
+export function portApartFrom(reserved: readonly RolePort[], preferred: number): number {
+  const held = new Set(reserved.map((one) => one.port));
+  if (!held.has(preferred)) return preferred;
+  for (let port = Math.max(...held) + 1; port <= PORT_RANGE.max; port += 1) {
+    if (!held.has(port)) return port;
+  }
+  let port = Math.min(...held) - 1;
+  while (held.has(port)) port -= 1;
+  return port;
+}
+
+export class MetricsPortSharedError extends UltimateError {
+  constructor(input: { port: number; with: RolePort; reserved: readonly RolePort[] }) {
+    const apart = portApartFrom(input.reserved, DEFAULT_METRICS_PORT);
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the metrics port ${input.port} is this process's ${input.with.role} port ${input.with.port}, so two listeners would answer on one number`,
+      fix: `METRICS_PORT=${quoteArg(String(apart))} x dev --json`,
+    });
+  }
+}
+
 /**
  * Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. Read
  * through `stringField`, never `error instanceof Error` plus a property access: both run on a value
@@ -83,6 +138,8 @@ export interface MetricsEndpointOptions {
    * `x dev` with no `METRICS_PORT`, where two apps on one laptop both default to 9090.
    */
   readonly whenTaken?: 'refuse' | 'free';
+  /** The ports this process's roles bind (web, the sync node beside it): refused as the scrape port. */
+  readonly reserved?: readonly RolePort[];
 }
 
 /**
@@ -165,7 +222,18 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
   // — 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 `role-start.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);
+  const asked = finiteCount('startMetricsEndpoint', 'port', options.port ?? DEFAULT_METRICS_PORT);
+  const shared = asked === 0 ? undefined : options.reserved?.find((one) => one.port === asked);
+  // `free` is the laptop that named no port: a role on the default is the same "taken" as another
+  // app on it, and the answer is the same free port. A port somebody declared is refused.
+  if (shared !== undefined && options.whenTaken !== 'free') {
+    throw new MetricsPortSharedError({
+      port: asked,
+      with: shared,
+      reserved: options.reserved ?? [],
+    });
+  }
+  const port = shared === undefined ? asked : 0;
   let buildId: string | null = null;
   // `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.

package/src/role-start.ts

@@ -32,6 +32,7 @@ import { errorPageHook } from './error-pages';
 import { BadFlagError, RuntimeDriverSplitError } from './errors';
 import {
   DEFAULT_METRICS_PORT,
+  rolePorts,
   startMetricsEndpoint,
   whenMetricsPortTaken,
 } from './metrics-endpoint';
@@ -287,6 +288,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         // `x dev` is one process running several roles: its `process_info` says which.
         role: selected.join('+'),
         whenTaken: whenMetricsPortTaken(binding.dev, options.env),
+        reserved: rolePorts(options.port, selected),
       });
     started.push(async () => metrics.stop());
     // Opened here or adopted from `serve-boot.ts`, this is where the build id is known (#734).

package/src/role-sync.ts

@@ -23,7 +23,7 @@ import {
   SocketRegistry,
   syncNode,
 } from '@ultimat3/realtime/server';
-import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
+import { portPairAfter, syncPortFor } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
 import { startOrWaitForBus } from './role-sync-bus-wait';
@@ -35,23 +35,6 @@ import { syncOriginsFrom } from './sync-url';
 import { trustedHopsFromEnv } from './trusted-hops';
 import { DEV_BINDING } from './web-binding';
 
-/**
- * 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 neighbour was already listening. `X_PORT_IN_USE` is this package's own and is exactly what
  * `x doctor` reports for the same condition, so one taken port has one name wherever it is found.
@@ -96,22 +79,8 @@ export async function syncBindRefusal(
   return new SyncPortInUseError({ port, webPort });
 }
 
-/**
- * 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;
-}
+// Its rule lives in `flag-number.ts`, where the scrape port's reservation reads it too (`rolePorts`).
+export { syncPortFor };
 
 /**
  * A node that is built and subscribed but bound to nothing yet — the one moment the `web` role can

package/src/serve.ts

@@ -9,7 +9,7 @@ import { assertNoSchemaDrift, checkDrift, migrate } from '@ultimat3/db';
 import { loadAppRuntime } from './app-runtime';
 import { acceptCreatedTables } from './db-accept-created';
 import { type BootedHold, holdWhileBooting } from './hold';
-import { startMetricsEndpoint } from './metrics-endpoint';
+import { rolePorts, startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
 import { startQueue } from './runtime-queue';
@@ -143,6 +143,9 @@ export async function serveApp(input: ServeOptions): Promise<ServedApp> {
     port: metricsPortFor(options.env, port, options.metricsPort),
     hostname: containerBinding(options.env, options.hostname).hostname,
     role,
+    // Opened before the roles are, so the check `startRoles` makes is made here: adopted, the
+    // listener is never re-checked, and one on the web or sync port would take it first.
+    reserved: rolePorts(port, [role]),
   });
   // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
   const acquired: (() => void | Promise<void>)[] = [() => metrics.stop()];