@ultimat3/cli 19.3.3 → 19.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.3.3",
+  "version": "19.4.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": "19.3.3",
-    "@ultimat3/admin": "19.3.3",
-    "@ultimat3/ai": "19.3.3",
-    "@ultimat3/auth": "19.3.3",
-    "@ultimat3/cache": "19.3.3",
-    "@ultimat3/core": "19.3.3",
-    "@ultimat3/db": "19.3.3",
-    "@ultimat3/entity": "19.3.3",
-    "@ultimat3/flags": "19.3.3",
-    "@ultimat3/http": "19.3.3",
-    "@ultimat3/i18n": "19.3.3",
-    "@ultimat3/jobs": "19.3.3",
-    "@ultimat3/mail": "19.3.3",
-    "@ultimat3/manifest": "19.3.3",
-    "@ultimat3/mcp": "19.3.3",
-    "@ultimat3/money": "19.3.3",
-    "@ultimat3/notify": "19.3.3",
-    "@ultimat3/policy": "19.3.3",
-    "@ultimat3/pwa": "19.3.3",
-    "@ultimat3/query": "19.3.3",
-    "@ultimat3/realtime": "19.3.3",
-    "@ultimat3/render": "19.3.3",
-    "@ultimat3/schema": "19.3.3",
-    "@ultimat3/scraping": "19.3.3",
-    "@ultimat3/seo": "19.3.3",
-    "@ultimat3/storage": "19.3.3",
-    "@ultimat3/testing": "19.3.3",
-    "@ultimat3/time": "19.3.3",
+    "@ultimat3/action": "19.4.0",
+    "@ultimat3/admin": "19.4.0",
+    "@ultimat3/ai": "19.4.0",
+    "@ultimat3/auth": "19.4.0",
+    "@ultimat3/cache": "19.4.0",
+    "@ultimat3/core": "19.4.0",
+    "@ultimat3/db": "19.4.0",
+    "@ultimat3/entity": "19.4.0",
+    "@ultimat3/flags": "19.4.0",
+    "@ultimat3/http": "19.4.0",
+    "@ultimat3/i18n": "19.4.0",
+    "@ultimat3/jobs": "19.4.0",
+    "@ultimat3/mail": "19.4.0",
+    "@ultimat3/manifest": "19.4.0",
+    "@ultimat3/mcp": "19.4.0",
+    "@ultimat3/money": "19.4.0",
+    "@ultimat3/notify": "19.4.0",
+    "@ultimat3/policy": "19.4.0",
+    "@ultimat3/pwa": "19.4.0",
+    "@ultimat3/query": "19.4.0",
+    "@ultimat3/realtime": "19.4.0",
+    "@ultimat3/render": "19.4.0",
+    "@ultimat3/schema": "19.4.0",
+    "@ultimat3/scraping": "19.4.0",
+    "@ultimat3/seo": "19.4.0",
+    "@ultimat3/storage": "19.4.0",
+    "@ultimat3/testing": "19.4.0",
+    "@ultimat3/time": "19.4.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/dev-roles.ts

@@ -8,7 +8,13 @@
 
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
-import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
+import type {
+  RateLimitStore,
+  Route,
+  ServerHandle,
+  ServerHooks,
+  WebSocketMount,
+} from '@ultimat3/http';
 import {
   configuredAuthenticator,
   configuredHttp,
@@ -26,7 +32,7 @@ import {
   jobDriver,
   pgSchedulerState,
 } from '@ultimat3/jobs';
-import type { LiveQueryRegistry } from '@ultimat3/realtime/server';
+import type { LiveQueryRegistry, SyncWs } from '@ultimat3/realtime/server';
 import type { LiveReplicator } from '@ultimat3/testing';
 import { devHooks } from './dev-hooks';
 import type { LiveFeed } from './dev-live-feed';
@@ -36,7 +42,7 @@ import type { RunningReplicator } from './dev-replicator';
 import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
-import { startSync } from './dev-sync';
+import { prepareSync, type RunningSync } from './dev-sync';
 import { errorPageHook } from './error-pages';
 import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
 import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
@@ -270,7 +276,9 @@ function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefin
   return supplied;
 }
 
-function startWeb(options: StartRolesOptions): ServerHandle {
+/** `mount` is the sync node's socket, served on THIS port as well as its own — why, in `dev-sync`.
+ * Undefined without the `sync` role, and then this server opens no websocket, as it always did. */
+function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): ServerHandle {
   warnIfUnauthenticatable(options.routes);
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
@@ -278,6 +286,7 @@ function startWeb(options: StartRolesOptions): ServerHandle {
   return createServer({
     routes: options.routes,
     role: 'web',
+    ...(mount === undefined ? {} : { websocket: mount }),
     hooks: devHooks({
       ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
       ...(options.root === undefined ? {} : { errorPage: errorPageHook(options.root) }),
@@ -373,11 +382,20 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     });
     started.push(async () => metrics.stop());
 
-    const server = selected.includes('web') ? startWeb(options) : null;
+    // BUILT here, BOUND below, the web role between them: `web` serves the node's socket on its
+    // own port and a listening server cannot be handed one, while the neighbouring-port refusals
+    // are only the right answer once the web port's own has been given.
+    const prepared = selected.includes('sync') ? await prepareSync(options) : null;
+    // One rollback entry, kept current — two would stop the node twice out of a failed boot.
+    let releaseSync = prepared?.stop ?? null;
+    if (prepared !== null) started.push(async () => await releaseSync?.());
+
+    const server = selected.includes('web') ? startWeb(options, prepared?.mount) : null;
     if (server !== null) started.push(() => server.stop());
 
-    const sync = selected.includes('sync') ? await startSync(options) : null;
-    if (sync !== null) started.push(sync.stop);
+    const sync: RunningSync | null =
+      prepared === null ? null : await prepared.listen(server === null ? null : server.url());
+    if (sync !== null) releaseSync = sync.stop;
 
     const worker = selected.includes('worker')
       ? createWorker({

package/src/dev-sync.ts

@@ -3,7 +3,9 @@
 // and a listener of its own — and because that file is the boot's index, not its detail.
 
 import { createContext, logger, UltimateError } from '@ultimat3/core';
+import type { WebSocketMount } from '@ultimat3/http';
 import { listQueries } from '@ultimat3/query';
+import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
   ChannelHub,
   createSyncNode,
@@ -98,6 +100,32 @@ export function syncPortFor(port: number): number {
   return port + 1;
 }
 
+/**
+ * A node that is built and subscribed but bound to nothing yet — the one moment the `web` role can
+ * still mount its socket, since `web` binds its port first and a mount handed over after that is a
+ * server already listening without it.
+ */
+export interface PreparedSync {
+  readonly node: SyncNode;
+  readonly registry: LiveQueryRegistry;
+  /**
+   * The socket as the WEB role can serve it, on the port that role already publishes.
+   *
+   * `x dev` does BOTH: this mount on `PORT`, and the node's own listener on `PORT + 1` below. They
+   * are one node behind two doors, not two nodes — the sockets share the registry, the grants and
+   * the change subscription — and which door a browser uses is whichever one it can reach.
+   * `docker/` publishes the second; a laptop reached through one forwarded port uses the first.
+   */
+  readonly mount: WebSocketMount<SyncWs>;
+  /**
+   * Bind `PORT + 1`, and answer with the same object `startSync` always did. `appUrl` is the web
+   * role's own origin when one runs here, for the line below that names both doors.
+   */
+  listen(appUrl: string | null): Promise<RunningSync>;
+  /** Release the node when nothing ever bound it — a `web` role that threw after it was built. */
+  stop(): Promise<void>;
+}
+
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
@@ -141,13 +169,10 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
 }
 
 /**
- * The sync role owns its own socket: websockets and the request pipeline drain differently.
- *
- * Port 0 is passed straight through rather than incremented — `+ 1` would ask the kernel for
- * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
- * never a string built from the port that was requested.
+ * The node itself: its hub, its registry, its authenticator and its change subscription. Nothing
+ * bound — `listen()` and the `web` role's mount are the two doors, and this is what is behind both.
  */
-export async function startSync(options: StartRolesOptions): Promise<RunningSync> {
+export async function prepareSync(options: StartRolesOptions): Promise<PreparedSync> {
   const sockets = new SocketRegistry();
   const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
   // The node evaluated no credential of its own and no host ever handed it one, so every socket
@@ -180,6 +205,35 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     }),
   });
   await node.start();
+  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(),
+    listen: async (appUrl) => await listen(options, node, registry, appUrl),
+  };
+}
+
+/**
+ * The node's own socket, on `PORT + 1`. The sync role owns it because websockets and the request
+ * pipeline drain differently, and `docker/` publishes it as a service of its own.
+ *
+ * Kept a step of its own so `web` binds BEFORE it: the two refusals below are about a taken
+ * neighbouring port, and reversing the order would answer a second `x dev` on this checkout with
+ * "port 3001 is in use" when the fact worth printing is that 3000 is.
+ *
+ * Port 0 is passed straight through rather than incremented — `+ 1` would ask the kernel for
+ * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
+ * never a string built from the port that was requested.
+ */
+async function listen(
+  options: StartRolesOptions,
+  node: SyncNode,
+  registry: LiveQueryRegistry,
+  appUrl: string | null,
+): Promise<RunningSync> {
   const port = syncPortFor(options.port);
   try {
     // The SAME interface the web role binds, resolved from the same option and the same default.
@@ -192,6 +246,14 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     // seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a reconnect frame
     // whose target does not exist yet.
     const listener = listenSyncNode(node, { port, hostname: binding.hostname, drainGraceMs: 0 });
+    // BOTH doors, named, once. `sync node ready` said only that a node existed: the first question
+    // a failing browser socket raises — "is the ws server up, and where?" — had no answer anywhere
+    // in the boot output, and the port was never printed at all. It is also what an editor's port
+    // forwarding reads: a url in the terminal is how VS Code and a Codespace learn a port exists.
+    logger.info('sync reachable', {
+      node: `${listener.url}${node.path}`,
+      app: appUrl === null ? null : `${appUrl}${node.path}`,
+    });
     return {
       url: listener.url,
       registry,
@@ -207,3 +269,9 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     throw error;
   }
 }
+
+/** Both steps, for a caller with no web role to mount anything on. */
+export async function startSync(options: StartRolesOptions): Promise<RunningSync> {
+  const prepared = await prepareSync(options);
+  return await prepared.listen(null);
+}