@ultimat3/cli 27.6.1 → 27.8.0

package/src/i18n-index.ts

@@ -9,7 +9,10 @@
 // why: Bun has no synchronous existence check — `Bun.file(p).exists()` is async, and this decides
 // whether to write at all, before any await the caller could interleave with.
 import { existsSync } from 'node:fs';
+import { stripComments } from '@ultimat3/core';
 import { APP_CATALOGS_PATH } from '@ultimat3/i18n/app-catalogs';
+import type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import { containedPath } from './generate-write';
 import type { Finding } from './output';
 import { CATALOG_ROOT, i18nIndex, localeEntry, localeImport } from './templates';
@@ -30,6 +33,8 @@ export interface IndexSync {
   /** False for an app with no i18n package, or an index this writer refused to edit. */
   readonly registered: boolean;
   readonly findings: readonly Finding[];
+  /** The index, when this changed its bytes — a run's file list names every file it touched. */
+  readonly edited?: readonly string[];
 }
 
 const CATALOG_IMPORT = /^import (\w+) from '\.\.\/catalogs\/([^']+)\.json';$/gm;
@@ -48,31 +53,42 @@ const importedLocales = (source: string): readonly string[] =>
  * stay. A shape with no `locales: { … }` object to add to is refused with the edit named, never
  * overwritten: it was, on every `x g`, with a template hard-coding `default: 'en'`.
  */
-export async function syncI18nIndex(root: string): Promise<IndexSync> {
-  const indexAbsolute = containedPath(root, APP_CATALOGS_PATH);
-  if (!existsSync(indexAbsolute)) return { registered: false, findings: [] };
-  const current = await Bun.file(indexAbsolute).text();
-  const onDisk = await catalogLocales(root);
+export async function syncI18nIndex(
+  root: string,
+  disk: GenerateDisk = appDisk(root),
+  /** Locales whose catalog a dry run PLANS: on the real disk only once the run has written. */
+  planned: readonly string[] = [],
+): Promise<IndexSync> {
+  const current = await disk.read(APP_CATALOGS_PATH);
+  if (current === undefined) return { registered: false, findings: [] };
+  const onDisk = [...new Set([...(await catalogLocales(root)), ...planned])].sort();
   const imported = importedLocales(current);
-  if (current === i18nIndex(imported)) {
-    await Bun.write(indexAbsolute, i18nIndex(onDisk));
-    return { registered: true, findings: [] };
-  }
+  const write = async (next: string): Promise<IndexSync> => {
+    if (next === current) return { registered: true, findings: [] };
+    await disk.write(APP_CATALOGS_PATH, next);
+    return { registered: true, findings: [], edited: [APP_CATALOGS_PATH] };
+  };
+  if (current === i18nIndex(imported)) return write(i18nIndex(onDisk));
   const missing = onDisk.filter((locale) => !imported.includes(locale));
   if (missing.length === 0) return { registered: true, findings: [] };
   const edited = withLocales(current, missing);
   if (edited === undefined) return { registered: false, findings: [refusal(missing)] };
-  await Bun.write(indexAbsolute, edited);
-  return { registered: true, findings: [] };
+  return write(edited);
 }
 
 /** Each import after the last catalog import (or at the top), each entry at the object's end. */
 function withLocales(source: string, locales: readonly string[]): string | undefined {
-  const object = LOCALES_OBJECT.exec(source);
+  // Found on the comment-stripped text (same offsets): a `locales: { … }` in a comment above the
+  // call is prose, and it was the one this edited.
+  const object = LOCALES_OBJECT.exec(stripComments(source));
   if (object === null) return undefined;
-  const body = (object[2] ?? '').trim().replace(/,$/, '');
+  const [whole, head = '', inner = ''] = object;
+  // A comment INSIDE the object cannot be carried through a one-line rewrite: refused, with the
+  // edit named, rather than dropped.
+  if (source.slice(object.index, object.index + whole.length) !== whole) return undefined;
+  const body = inner.trim().replace(/,$/, '');
   const entries = [body, ...locales.map(localeEntry)].filter((part) => part !== '').join(', ');
-  const withEntries = source.replace(LOCALES_OBJECT, `$1 ${entries} $3`);
+  const withEntries = `${source.slice(0, object.index)}${head} ${entries} }${source.slice(object.index + whole.length)}`;
   const imports = locales.map(localeImport).join('\n');
   const lastImport = [...withEntries.matchAll(CATALOG_IMPORT)].at(-1);
   if (lastImport === undefined) return `${imports}\n${withEntries}`;

package/src/isr-query-advice.ts

@@ -0,0 +1,63 @@
+// What `x verify` says about the query an `isr` route keys on. Advice and not a finding: the scan
+// reads source text, so it can miss a read made through a helper and can name one that is not a
+// query read at all — and a route that declared nothing works as it always did. Both are exactly
+// what a reader should hear about before a visitor finds it.
+
+// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
+import { join } from 'node:path';
+import { stripComments } from '@ultimat3/core';
+import { describePages } from '@ultimat3/render';
+import { msg } from './messages';
+
+const MEMBER_READ = /\bquery\s*\??\.\s*([A-Za-z_$][\w$]*)\b(?!\s*\()/g;
+const BRACKET_READ = /\bquery\s*(?:\?\.)?\[\s*['"]([^'"]+)['"]\s*\]/g;
+const SEARCH_PARAM_READ = /\bsearchParams\s*\??\.\s*(?:get|getAll|has)\(\s*['"]([^'"]+)['"]/g;
+
+/**
+ * The query parameter names a route module reads, as far as its text says: `query.name`,
+ * `query?.name`, `query['name']` and `searchParams.get('name')` (also `getAll`, `has`). A call
+ * (`query.where(…)`) is a method, not a parameter. Sorted, each once.
+ */
+export function queryReads(source: string): readonly string[] {
+  const code = stripComments(source);
+  const names = new Set<string>();
+  for (const pattern of [MEMBER_READ, BRACKET_READ, SEARCH_PARAM_READ]) {
+    for (const match of code.matchAll(pattern)) {
+      if (match[1] !== undefined) names.add(match[1]);
+    }
+  }
+  return [...names].sort();
+}
+
+const listed = (names: readonly string[]): string => names.map((name) => `'${name}'`).join(', ');
+
+/**
+ * One line per `isr` route with no `revalidate.query` — it renders and stores a page for every
+ * distinct query string, so `?x=1`, `?x=2`, … evict its real pages and cost a render each — and
+ * one per parameter a route's module reads and its declaration omits: the page is stored under a
+ * key without it, so every visitor gets the document rendered for whichever value arrived first.
+ */
+export async function isrQueryAdvice(root: string): Promise<readonly string[]> {
+  const advice: string[] = [];
+  for (const route of describePages()) {
+    if (route.mode !== 'isr') continue;
+    const declared = route.revalidateQuery ?? null;
+    if (declared === null) {
+      advice.push(msg('cli.verify.isrQueryUndeclared', { file: route.file }));
+      continue;
+    }
+    const module = Bun.file(join(root, route.file));
+    if (!(await module.exists())) continue;
+    for (const name of queryReads(await module.text())) {
+      if (declared.includes(name)) continue;
+      advice.push(
+        msg('cli.verify.isrQueryOmitted', {
+          file: route.file,
+          name,
+          declared: listed([...declared, name].sort()),
+        }),
+      );
+    }
+  }
+  return advice;
+}

package/src/isr-query-guard.ts

@@ -0,0 +1,49 @@
+// The `query` object a page component is handed. For an `isr` route that declared
+// `revalidate.query` it holds the declared parameters only — and, outside production, it says so
+// once when the page reads any other one: that read is a document varying on something its stored
+// key does not carry, which is one visitor's page answered to every visitor after.
+
+import type { ResolveEnvironmentOptions } from '@ultimat3/core';
+import { logger, tryResolveEnvironment } from '@ultimat3/core';
+import type { RouteEntry } from '@ultimat3/render';
+
+type Query = Readonly<Record<string, string>>;
+
+/** `<route file>\u0000<parameter>` already told — bounded by what the app's source can read. */
+const told = new Set<string>();
+
+/** Names every object answers and a renderer or a serializer may ask for: never a parameter. */
+const isProbe = (name: string): boolean =>
+  name in Object.prototype || name === 'then' || name === 'toJSON';
+
+export function routeQuery(
+  entry: RouteEntry,
+  url: URL,
+  env?: ResolveEnvironmentOptions['env'],
+): Query {
+  const query: Query = Object.fromEntries(url.searchParams);
+  const declared = entry.config.render === 'isr' ? entry.config.revalidate?.query : undefined;
+  if (declared === undefined) return query;
+  // Production pays nothing: the plain object, no trap. (`undefined`: an unreadable environment,
+  // which is not a development one either.)
+  const environment = tryResolveEnvironment(env === undefined ? undefined : { env });
+  if (environment === 'production' || environment === undefined) return query;
+  return new Proxy(query, {
+    get(target, name, receiver) {
+      if (typeof name === 'string' && !declared.includes(name) && !isProbe(name)) {
+        const key = `${entry.file}\u0000${name}`;
+        if (!told.has(key)) {
+          told.add(key);
+          const widened = [...declared, name].sort().map((one) => `'${one}'`);
+          logger.warn('isr.query.unkeyed-read', {
+            route: entry.file,
+            param: name,
+            cause: `the page read query.${name}, and revalidate.query does not list it — the stored page is keyed without it, so every visitor gets the document rendered for whichever value arrived first`,
+            fix: `query: [${widened.join(', ')}]   // in revalidate, in ${entry.file}`,
+          });
+        }
+      }
+      return Reflect.get(target, name, receiver);
+    },
+  });
+}

package/src/mcp-host.ts

@@ -105,7 +105,8 @@ export function lazyServices(input: DevHostInput): LazyServices {
   // one connection wedged every later tool call in the session with that first error, and the only
   // way out was restarting the host — `startServices` unwinds everything it started before it
   // rejects, so there is nothing left over for a second attempt to collide with.
-  const boot = retryMemo(() => startServices(services, input.env));
+  // `[]`: this host starts no role, so it only ever publishes to the bus and never waits for it.
+  const boot = retryMemo(() => startServices(services, input.env, undefined, 'apply', []));
   let closed = false;
   return {
     services,

package/src/messages.ts

@@ -328,6 +328,10 @@ const CATALOG = {
   // counts — so the line says how many and `x test <type>` prints the names.
   'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
   'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
+  'cli.verify.isrQueryUndeclared':
+    "{file}: render 'isr' with no revalidate.query — its stored pages are keyed on the whole query string, so any visitor can mint one per request. Declare revalidate: { query: [] } (or the parameters the page varies on)",
+  'cli.verify.isrQueryOmitted':
+    '{file}: reads the query parameter "{name}", which revalidate.query does not list — the page is stored under a key without it, so every visitor gets the document rendered for whichever value arrived first. Declare query: [{declared}], or stop reading it',
   // The other shape the same counts can take: a suite that reported no test at all, skipped ones
   // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
   // no skipped test to read a reason off, so the files the step selected hold no test.

package/src/role-sync-bus-wait.ts

@@ -0,0 +1,66 @@
+// Single responsibility: what the `sync` role does when its node cannot start because the bus is
+// away. A `ROLE=sync` container refuses its boot — it has nothing to serve without the bus.
+// `x dev` runs every role in one process, so there the node stays mounted and NOT ready, and is
+// started when the bus answers: the pages, the worker and the scheduler never went down with it.
+
+import { isUltimateError, logger } from '@ultimat3/core';
+import type { SyncNode, Transport } from '@ultimat3/realtime/server';
+
+export interface BusWaitRuntime {
+  readonly transport: Pick<Transport, 'onReconnect'>;
+  /** `RunningServices.busTolerated`: the boot is `x dev`, and a bus that is away is waited for. */
+  readonly busTolerated?: boolean | undefined;
+}
+
+/**
+ * Start the node, or — tolerated, with the bus away — leave it unstarted and start it on the
+ * transport's next recovery. Until then an upgrade is shed with a 503 and a retry delay
+ * (`sync-upgrade.ts`), so an open page keeps asking and goes live with no restart. Any other
+ * refusal, and every refusal outside `x dev`, is the boot's. Returns what stops the wait.
+ */
+export async function startOrWaitForBus(
+  node: Pick<SyncNode, 'start'>,
+  runtime: BusWaitRuntime,
+): Promise<() => void> {
+  const refused = await node.start().then(
+    () => undefined,
+    (error: unknown) => ({ error }),
+  );
+  if (refused === undefined) return () => undefined;
+  const { error } = refused;
+  if (
+    runtime.busTolerated !== true ||
+    !isUltimateError(error) ||
+    error.code !== 'X_TRANSPORT_UNAVAILABLE'
+  ) {
+    throw error;
+  }
+  // Once, with the refusal a container would have exited on.
+  logger.warn('sync node is waiting for the bus: sockets are refused until it answers', {
+    code: error.code,
+    cause: error.cause,
+    fix: error.fix,
+  });
+  let waiting = true;
+  let off = (): void => undefined;
+  const attempt = (): void => {
+    if (!waiting) return;
+    void node.start().then(
+      () => {
+        if (!waiting) return;
+        waiting = false;
+        off();
+        logger.info('sync node started: the bus answered');
+      },
+      // Still away, or away again: the next recovery asks once more.
+      () => undefined,
+    );
+  };
+  off = runtime.transport.onReconnect(attempt);
+  // The dial may have landed between the refusal and the line above; asking again costs nothing.
+  attempt();
+  return () => {
+    waiting = false;
+    off();
+  };
+}

package/src/role-sync.ts

@@ -26,6 +26,7 @@ import {
 import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
+import { startOrWaitForBus } from './role-sync-bus-wait';
 import type { Env } from './runtime-bindings';
 import { syncAuthenticator } from './sync-authenticator';
 import { syncOriginsFrom } from './sync-url';
@@ -327,14 +328,17 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
       ttlMs: options.runtime.presenceTtlMs,
     }),
   });
-  await node.start();
+  const stopWaiting = await startOrWaitForBus(node, options.runtime);
   return {
     node,
     registry,
     // The node's OWN path, asked rather than restated: `SyncNodeOptions.path` is settable and a
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
-    stop: () => node.stop(),
+    stop: async () => {
+      stopWaiting();
+      await node.stop();
+    },
     listen: async (appUrl) => {
       origins.push(...devOrigins(options, origins, appUrl));
       return await listen(options, node, { registry, hub }, appUrl);

package/src/runtime-bus.ts

@@ -0,0 +1,198 @@
+// Single responsibility: the fanout bus as ONE boot holds it — what the roles it starts do with
+// the bus, the dial that calls for, the readiness check, and the label the boot line prints.
+//
+// The rule is the role's, not the transport's. A `sync` node serves sockets from the bus and a
+// replicator feeds them: neither can work without it, so each awaits the dial and refuses its
+// boot, coded, inside a bounded wait. `web`, `worker` and `scheduler` only PUBLISH — channel
+// events and cache invalidations, both of which mean "re-read" — so for them the bus is dialled in
+// the background and a dead one is `degraded`: the pod still boots, serves and runs jobs. Until
+// 2026-10 every role awaited the dial and the JetStream bucket, so a web pod that restarted while
+// NATS was down took the app's pages, webhooks and send jobs down with a feature none of them use.
+//
+// `x dev` is the one boot that TOLERATES a missing bus for a role that serves from it: it runs
+// every role in one process, so the `sync` role's refusal took the pages, the worker and the
+// scheduler down with it — the same outage, on the developer's own machine. There the refusal is
+// logged once, coded, the dial goes on in the background, and the pages run without live until it
+// lands. A `ROLE=sync` container keeps the hard refusal: it has nothing else to serve.
+
+import type { RealtimeConfig, Role } from '@ultimat3/core';
+import { isUltimateError, logger, registerReadinessCheck } from '@ultimat3/core';
+import type { BusUse, SelectTransportOptions, Transport } from '@ultimat3/realtime/server';
+import { selectTransport, setChannelTransport } from '@ultimat3/realtime/server';
+import type { Env } from './runtime-bindings';
+
+/**
+ * What a process running `roles` does with the bus. `undefined` — a boot that names no roles — is
+ * held to the strictest reading, the one every boot had. `realtime.enabled: false` starts neither
+ * realtime role (`role-realtime.ts`), so nothing in such a process waits for the bus.
+ */
+export function busUseFor(
+  roles: readonly Role[] | undefined,
+  realtime: Pick<RealtimeConfig, 'enabled'>,
+): BusUse {
+  if (roles === undefined) return 'sockets';
+  if (!realtime.enabled) return 'publish';
+  if (roles.includes('sync')) return 'sockets';
+  return roles.includes('replicator') ? 'feed' : 'publish';
+}
+
+/** A transport that says whether it is connected. NATS does; the in-process bus has nothing to be. */
+interface ConnectableTransport {
+  readonly connected: boolean;
+}
+
+const saysConnected = (transport: Transport): transport is Transport & ConnectableTransport =>
+  typeof (transport as Partial<ConnectableTransport>).connected === 'boolean';
+
+/**
+ * The boot line's `bus=` value: `nats(up)`, `nats(connecting)`, or the bare name of a bus with no
+ * connection to lose. A fixed vocabulary a script may parse, never a catalog lookup.
+ */
+export function busLabel(transport: Transport): string {
+  if (!saysConnected(transport)) return transport.name;
+  return `${transport.name}(${transport.connected ? 'up' : 'connecting'})`;
+}
+
+export interface RunningBus {
+  readonly transport: Transport;
+  /** The env key that selected the bus — never the url behind it — or `runtime override`. */
+  readonly detail: string;
+  /** Everything `start()` acquired, newest first; the first failure is rethrown, every step runs. */
+  stop(): Promise<void>;
+}
+
+/**
+ * How long `x dev` waits for a bus its realtime roles need before it boots without one. Short on
+ * purpose: a NATS started beside it is reachable by then, and one that is not is dialled in the
+ * background anyway.
+ */
+export const DEV_BUS_WAIT_MS = 3_000;
+
+export interface SelectedBus {
+  readonly use: BusUse;
+  /**
+   * `x dev` with a role that serves from the bus: a bus that is away is waited for in the
+   * background rather than refused (`RunningServices.busTolerated`).
+   */
+  readonly tolerant: boolean;
+  /** What the sync role must give `PresenceRegistry` (`RunningServices.presenceTtlMs`). */
+  readonly presenceTtlMs: number;
+  /**
+   * Dial as `use` calls for, install the transport as the process's channel bus, and register its
+   * readiness check. Rejects — with nothing left registered or open — only for a use that cannot
+   * work without the bus.
+   */
+  start(): Promise<RunningBus>;
+}
+
+export interface SelectBusInput {
+  readonly env: Env;
+  readonly realtime: RealtimeConfig;
+  /** The roles this process will start; `undefined` when the caller does not know. */
+  readonly roles: readonly Role[] | undefined;
+  /** `RuntimeOverrides.transport`: already connected, and its owner's to close. */
+  readonly override?: Transport | undefined;
+  /** Injected by a test: a fake dial, a short wait. */
+  readonly select?: SelectTransportOptions | undefined;
+  /** The boot is `x dev`: every role in one process, on the developer's machine. */
+  readonly dev?: boolean | undefined;
+}
+
+/**
+ * Selection is pure — it parses env and constructs, it dials nothing — so a config and an
+ * environment that disagree refuse here, before any service starts (`selectTransport`).
+ */
+export function selectBus(input: SelectBusInput): SelectedBus {
+  const use = busUseFor(input.roles, input.realtime);
+  const tolerant = input.dev === true && use !== 'publish';
+  const selection = selectTransport(input.env, input.realtime, {
+    ...(tolerant ? { connectWithinMs: DEV_BUS_WAIT_MS } : {}),
+    ...input.select,
+    use,
+  });
+  return {
+    use,
+    tolerant,
+    presenceTtlMs: selection.presenceTtlMs,
+    async start(): Promise<RunningBus> {
+      const started: (() => void | Promise<void>)[] = [];
+      const stop = async (): Promise<void> => {
+        let failure: { readonly error: unknown } | undefined;
+        for (const step of started.splice(0).reverse()) {
+          try {
+            await step();
+          } catch (error) {
+            failure ??= { error };
+          }
+        }
+        if (failure !== undefined) throw failure.error;
+      };
+      try {
+        // A supplied transport is already connected and is NOT closed here: whoever built it owns
+        // its socket, which is why the override skips both halves rather than only the dial.
+        let transport = input.override;
+        if (transport === undefined) {
+          // Before the dial, not after: a dial refused for being late is still in flight inside
+          // the client library, and closing the transport is what releases whatever it lands as.
+          started.push(() => selection.transport.close());
+          try {
+            await selection.connect();
+          } catch (error) {
+            if (!tolerant || !isUltimateError(error) || error.code !== 'X_TRANSPORT_UNAVAILABLE') {
+              throw error;
+            }
+            // Said ONCE, with the refusal a container would have exited on. The transport is not
+            // closed: its dial loop goes on, and `ultimate bus` is the line that says it landed.
+            logger.warn('ultimate bus is away: x dev serves without live until it answers', {
+              code: error.code,
+              cause: error.cause,
+              fix: error.fix,
+            });
+          }
+          transport = selection.transport;
+        }
+        // The bus an app's own code publishes a channel event on (`publishChannelEvent`), in EVERY
+        // role: the hub is the `sync` role's, so a job or an action reached none, and an
+        // events-only channel — the one kind that needs no replicator — could be fed by nothing
+        // but a socket.
+        started.push(setChannelTransport(transport));
+        // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
+        // synchronous getter over the client's own state, so no probe is needed; the in-process
+        // bus has nothing to lose a connection to, and a check that can only answer `true` is a
+        // number in `registered` that means nothing.
+        if (saysConnected(transport)) {
+          const connectable = transport;
+          started.push(
+            registerReadinessCheck(
+              'transport',
+              () => connectable.connected,
+              // A publisher serves without the bus, so losing it must not pull the pod from the
+              // ingress — it is reported, and `/readyz?deep=1` is where a monitor reads it.
+              // `x dev` serves its pages from the same process: its bus is a degradation too.
+              { onFailure: use === 'publish' || tolerant ? 'degraded' : 'failing' },
+            ),
+          );
+          // Each time the bus comes (back) up, on one line: the boot line may have said
+          // `connecting`, and this is the other half of it.
+          started.push(
+            connectable.onReconnect(() => {
+              logger.info('ultimate bus', { bus: busLabel(connectable), use });
+            }),
+          );
+        }
+        return {
+          transport,
+          // 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.
+          detail: input.override === undefined ? selection.detail : 'runtime override',
+          stop,
+        };
+      } catch (error) {
+        // The refusal is the failure worth reporting, not a release on the way out.
+        await stop().catch(() => undefined);
+        throw error;
+      }
+    },
+  };
+}