@ultimat3/cli 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -34,27 +34,27 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "1.1.0",
-    "@ultimat3/admin": "1.1.0",
-    "@ultimat3/ai": "1.1.0",
-    "@ultimat3/cache": "1.1.0",
-    "@ultimat3/core": "1.1.0",
-    "@ultimat3/db": "1.1.0",
-    "@ultimat3/entity": "1.1.0",
-    "@ultimat3/http": "1.1.0",
-    "@ultimat3/i18n": "1.1.0",
-    "@ultimat3/jobs": "1.1.0",
-    "@ultimat3/mail": "1.1.0",
-    "@ultimat3/manifest": "1.1.0",
-    "@ultimat3/mcp": "1.1.0",
-    "@ultimat3/policy": "1.1.0",
-    "@ultimat3/pwa": "1.1.0",
-    "@ultimat3/query": "1.1.0",
-    "@ultimat3/realtime": "1.1.0",
-    "@ultimat3/render": "1.1.0",
-    "@ultimat3/seo": "1.1.0",
-    "@ultimat3/storage": "1.1.0",
-    "@ultimat3/testing": "1.1.0",
-    "@ultimat3/time": "1.1.0"
+    "@ultimat3/action": "1.2.0",
+    "@ultimat3/admin": "1.2.0",
+    "@ultimat3/ai": "1.2.0",
+    "@ultimat3/cache": "1.2.0",
+    "@ultimat3/core": "1.2.0",
+    "@ultimat3/db": "1.2.0",
+    "@ultimat3/entity": "1.2.0",
+    "@ultimat3/http": "1.2.0",
+    "@ultimat3/i18n": "1.2.0",
+    "@ultimat3/jobs": "1.2.0",
+    "@ultimat3/mail": "1.2.0",
+    "@ultimat3/manifest": "1.2.0",
+    "@ultimat3/mcp": "1.2.0",
+    "@ultimat3/policy": "1.2.0",
+    "@ultimat3/pwa": "1.2.0",
+    "@ultimat3/query": "1.2.0",
+    "@ultimat3/realtime": "1.2.0",
+    "@ultimat3/render": "1.2.0",
+    "@ultimat3/seo": "1.2.0",
+    "@ultimat3/storage": "1.2.0",
+    "@ultimat3/testing": "1.2.0",
+    "@ultimat3/time": "1.2.0"
   }
 }

package/src/cmd-dev.ts

@@ -8,7 +8,7 @@ import { watch } from 'node:fs';
 import { join } from 'node:path';
 import { listActions, toRoute } from '@ultimat3/action';
 import type { Role } from '@ultimat3/core';
-import { configureTelemetry, noopExporter } from '@ultimat3/core';
+import { configureTelemetry, METRICS_PATH, noopExporter } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
@@ -249,6 +249,9 @@ export const devCommand: CliCommand = {
         url: server.url,
         roles: [...server.roles],
         sync: server.running.syncUrl,
+        // The scrape target, on its own port for every role: what an operator points a Prometheus
+        // at, and the one url here that must NOT be behind the ingress the app's own url is.
+        metrics: `${server.running.metricsUrl}${METRICS_PATH}`,
         stateDir: server.services.stateDir,
         db: server.services.db.url,
         events: server.services.events.url,

package/src/dev-roles.ts

@@ -29,6 +29,7 @@ import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { BadFlagError } from './errors';
+import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 
 /** The roles `x dev` starts when `--role` names none, in boot order. */
 export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
@@ -57,6 +58,12 @@ export interface StartRolesOptions {
    * probe, which is the same failure in four costumes.
    */
   readonly http?: WebBinding;
+  /**
+   * Where the scrape listener binds. Defaults to `DEFAULT_METRICS_PORT`, except when `port` is 0
+   * — a caller asking the kernel for an ephemeral HTTP port is a test, and a test that grabbed
+   * 9090 would fail the next one to run beside it.
+   */
+  readonly metricsPort?: number;
 }
 
 export interface WebBinding {
@@ -73,6 +80,8 @@ export interface RunningRoles {
   readonly url: string | null;
   /** Where the sync role accepts websockets; null when it was not selected. */
   readonly syncUrl: string | null;
+  /** `http://…` — the scrape base. Never null: every role publishes a signal worth scaling on. */
+  readonly metricsUrl: string;
   readonly server: ServerHandle | null;
   readonly worker: Worker | null;
   readonly scheduler: Scheduler | null;
@@ -203,6 +212,15 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
   // Without this a failed `sync` leaves the web server bound and unreachable by any caller.
   const started: (() => Promise<void>)[] = [];
   try {
+    // First, and for every role rather than only the two that open an HTTP socket: `worker` and
+    // `sync` are precisely the roles whose HPAs read a series the process itself has to publish,
+    // and a `worker` container with no listener is an HPA pinned at `<unknown>` forever.
+    const metrics = startMetricsEndpoint({
+      port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
+      ...(options.http === undefined ? {} : { hostname: options.http.hostname }),
+    });
+    started.push(async () => metrics.stop());
+
     const server = selected.includes('web') ? startWeb(options) : null;
     if (server !== null) started.push(() => server.stop());
 
@@ -240,6 +258,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       roles: selected,
       url: server === null ? null : server.url(),
       syncUrl: sync?.url ?? null,
+      metricsUrl: metrics.url,
       server,
       worker,
       scheduler,
@@ -251,6 +270,8 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         await worker?.stop('x dev stopped');
         await sync?.stop();
         await server?.stop();
+        // Last: a scrape taken while the roles above drain is the one that explains the drain.
+        metrics.stop();
       },
     };
   } catch (error) {

package/src/errors.ts

@@ -401,11 +401,13 @@ export class RoleUnknownError extends UltimateError {
  * reports nothing an operator can act on.
  */
 export class PortInvalidError extends UltimateError {
-  constructor(input: { value: string }) {
+  /** `name` so the scrape port reports itself; the code stays one, because the fault is one. */
+  constructor(input: { value: string; name?: string }) {
+    const name = input.name ?? 'PORT';
     super({
       code: 'X_PORT_INVALID',
-      cause: `PORT="${input.value}" is not a TCP port number between 0 and 65535`,
-      fix: 'docker run -e PORT=3000 <image>',
+      cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
+      fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} <image>`,
       docs: docsFor('X_PORT_INVALID'),
     });
   }

package/src/index.ts

@@ -132,6 +132,8 @@ export { renderJobTable } from './jobs-table';
 export type { CliMcpServer, DevHostInput } from './mcp-host';
 export { createDevMcpServer, DEV_TOOL_SCOPES, localCaller } from './mcp-host';
 export { messageKeys, msg } from './messages';
+export type { MetricsEndpoint, MetricsEndpointOptions } from './metrics-endpoint';
+export { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 export { MIGRATIONS_DIR, migrationName, parseMigrationSql, readMigrations } from './migrations';
 export type { CommandResult, Finding, JsonValue, StepResult } from './output';
 export {
@@ -153,6 +155,7 @@ export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
 export {
   CONTAINER_BINDING,
   DEFAULT_PORT,
+  metricsPortFromEnv,
   portFromEnv,
   roleFromEnv,
   runMigrations,

package/src/metrics-endpoint.ts

@@ -0,0 +1,72 @@
+// Single responsibility: the scrape listener every role opens. `@ultimat3/core` declares the
+// series and renders the body; this is the one place a process answers `METRICS_PATH` with it, so
+// `docker/helm`'s HPAs read a number instead of `<unknown>`.
+
+import {
+  logger,
+  METRICS_CONTENT_TYPE,
+  METRICS_PATH,
+  markListening,
+  metricsText,
+} from '@ultimat3/core';
+
+/**
+ * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
+ * `docker/helm/templates/ingress.yaml` routes `path: /` `Prefix` to the web Service, so a
+ * `/metrics` mounted beside `/healthz` on port 3000 is `/metrics` on the internet — route
+ * patterns, request volumes and error rates, published. Nothing in the chart fronts this port:
+ * `service.yaml` only publishes `http`, so the endpoint is cluster-internal by construction
+ * rather than by an ingress exclusion somebody has to remember to write.
+ *
+ * It is also the only thing `worker`, `scheduler` and `replicator` could ever be scraped on —
+ * they open no HTTP socket at all, and `queue_depth` is exactly the signal one of them owns.
+ * 9090 is Prometheus's own convention, so a scrape config that assumes it needs no edit.
+ */
+export const DEFAULT_METRICS_PORT = 9090;
+
+export interface MetricsEndpointOptions {
+  /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
+  readonly port?: number;
+  /** A container must bind every interface; a laptop must not. Same decision as the web role. */
+  readonly hostname?: string;
+}
+
+export interface MetricsEndpoint {
+  /** `http://host:port` — the base the scrape target appends `METRICS_PATH` to. */
+  readonly url: string;
+  stop(): void;
+}
+
+/**
+ * Answers outside the request pipeline, exactly as `/healthz` and `/readyz` do in
+ * `@ultimat3/http`'s `server.ts`: no auth, no rate limit, no locale negotiation. A saturated or
+ * draining process must still be able to say how saturated it is — an autoscaler that loses its
+ * signal at the moment of load is worse than no autoscaler.
+ */
+export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
+  const server = Bun.serve({
+    port: options.port ?? DEFAULT_METRICS_PORT,
+    hostname: options.hostname ?? 'localhost',
+    fetch(request: Request): Response {
+      if (new URL(request.url).pathname !== METRICS_PATH) {
+        return new Response('not found', { status: 404 });
+      }
+      // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot steal
+      // each other's samples — but a cache would hand the second one a stale window.
+      return new Response(metricsText(), {
+        headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+      });
+    },
+  });
+  // Same rule as every other socket the framework opens: announce it, so a request back to it is
+  // recognisably this process calling itself rather than egress the test seal must refuse.
+  const stopListening = markListening(server.url.origin);
+  logger.info('ultimate metrics listening', { url: `${server.url.origin}${METRICS_PATH}` });
+  return {
+    url: server.url.origin,
+    stop(): void {
+      server.stop(true);
+      stopListening();
+    },
+  };
+}

package/src/serve.ts

@@ -22,6 +22,7 @@ import type { Env } from './dev-services';
 import { resolveServices } from './dev-services';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { holdUntilShutdown } from './hold';
+import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 
 export const DEFAULT_PORT = 3000;
@@ -40,19 +41,32 @@ export function roleFromEnv(env: Env): Role {
 }
 
 /**
- * Every PaaS injects `PORT` and routes traffic to exactly it. `Number.parseInt` would read `80abc`
- * as 80, so the whole string has to be a port — a partially-parsed port is a deploy that binds
- * somewhere nobody asked for.
+ * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
+ * partially-parsed port is a deploy that binds somewhere nobody asked for.
  */
-export function portFromEnv(env: Env): number {
-  const raw = env['PORT'];
-  if (raw === undefined || raw.trim().length === 0) return DEFAULT_PORT;
+function portValue(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim().length === 0) return fallback;
   const port = Number(raw.trim());
   if (!Number.isInteger(port) || port < 0 || port > 65_535)
-    throw new PortInvalidError({ value: raw });
+    throw new PortInvalidError({ value: raw, name });
   return port;
 }
 
+/** Every PaaS injects `PORT` and routes traffic to exactly it. */
+export function portFromEnv(env: Env): number {
+  return portValue(env, 'PORT', DEFAULT_PORT);
+}
+
+/**
+ * The scrape port, deliberately its own env var and not `PORT + n`: an operator who moves the app
+ * port must not silently move the port their Prometheus is configured against, and the roles that
+ * set no `PORT` at all — `worker`, `scheduler`, `replicator` — still need this one.
+ */
+export function metricsPortFromEnv(env: Env): number {
+  return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
+}
+
 export interface ServeOptions {
   readonly root: string;
   readonly env: Env;
@@ -60,6 +74,8 @@ export interface ServeOptions {
   readonly role?: Role;
   /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
   readonly port?: number;
+  /** Overrides `METRICS_PORT`, on the same terms. */
+  readonly metricsPort?: number;
 }
 
 export interface ServedApp {
@@ -138,9 +154,17 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     ...assetRoutes({ root: options.root, storage: runtime.storage }),
     ...appRoutes({ buildId }),
   ];
+  const port = options.port ?? portFromEnv(options.env);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
+  // still wins — that is the deploy talking.
+  const metricsPort =
+    options.metricsPort ??
+    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
   const running = await startRoles({
     roles: [role],
-    port: options.port ?? portFromEnv(options.env),
+    port,
+    metricsPort,
     buildId,
     runtime,
     routes,