@ultimat3/cli 19.3.2 → 19.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.3.2",
+  "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.2",
-    "@ultimat3/admin": "19.3.2",
-    "@ultimat3/ai": "19.3.2",
-    "@ultimat3/auth": "19.3.2",
-    "@ultimat3/cache": "19.3.2",
-    "@ultimat3/core": "19.3.2",
-    "@ultimat3/db": "19.3.2",
-    "@ultimat3/entity": "19.3.2",
-    "@ultimat3/flags": "19.3.2",
-    "@ultimat3/http": "19.3.2",
-    "@ultimat3/i18n": "19.3.2",
-    "@ultimat3/jobs": "19.3.2",
-    "@ultimat3/mail": "19.3.2",
-    "@ultimat3/manifest": "19.3.2",
-    "@ultimat3/mcp": "19.3.2",
-    "@ultimat3/money": "19.3.2",
-    "@ultimat3/notify": "19.3.2",
-    "@ultimat3/policy": "19.3.2",
-    "@ultimat3/pwa": "19.3.2",
-    "@ultimat3/query": "19.3.2",
-    "@ultimat3/realtime": "19.3.2",
-    "@ultimat3/render": "19.3.2",
-    "@ultimat3/schema": "19.3.2",
-    "@ultimat3/scraping": "19.3.2",
-    "@ultimat3/seo": "19.3.2",
-    "@ultimat3/storage": "19.3.2",
-    "@ultimat3/testing": "19.3.2",
-    "@ultimat3/time": "19.3.2",
+    "@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);
+}

package/src/verify-checks.ts

@@ -50,14 +50,21 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
     summary: 'tsc -b across every project the root references',
+    // `typecheckBin` (`x.verify.json`, beside `agentsMdMaxBytes`) swaps the binary and nothing
+    // else: same `-b --pretty false` invocation, same output format to parse, same `X_TYPECHECK_
+    // FAILED` finding either way. Absent means `tsc` — the only checker every app already has,
+    // since `typescript` is a framework dependency and a drop-in replacement is the app's own
+    // devDependency to add, never a default this step could assume.
     async run(ctx) {
-      const result = await ctx.runner(['bunx', 'tsc', '-b', '--pretty', 'false'], {
+      const floor = await readVerifyFloor(ctx.root);
+      const bin = floor?.typecheckBin ?? 'tsc';
+      const result = await ctx.runner(['bunx', bin, '-b', '--pretty', 'false'], {
         cwd: ctx.root,
       });
       return fromExec(result, {
         code: 'X_TYPECHECK_FAILED',
         cause: 'the project does not typecheck',
-        fix: 'bunx tsc -b --pretty false',
+        fix: `bunx ${bin} -b --pretty false`,
       });
     },
   },

package/src/verify-floor.ts

@@ -29,6 +29,18 @@ export interface VerifyFloor {
    * sees, which is the whole safeguard: the number is small, visible, and argued for in one place.
    */
   readonly agentsMdMaxBytes?: number;
+  /**
+   * The binary the `typecheck` step invokes in place of `tsc` — `bunx <typecheckBin> -b --pretty
+   * false`, unchanged otherwise. Absent means `tsc`, which is the only binary every app already
+   * has: `typescript` is a framework dependency, not one this file can assume an app added.
+   *
+   * Here for the same reason `agentsMdMaxBytes` is: this is the file that configures the GATE,
+   * and it is read by the very step the key names. A drop-in `tsc -b` compatible checker (Microsoft's
+   * `tsgo`, `@typescript/native-preview`) is a devDependency + a one-line commit here, never a
+   * hardcoded default — an app that has not installed the binary this names gets `command not
+   * found` from its own shell, not a framework opinion about which compiler is correct.
+   */
+  readonly typecheckBin?: string;
   /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
   readonly problems: readonly string[];
 }
@@ -36,6 +48,9 @@ export interface VerifyFloor {
 /** The floor's budget key. Named once: the problem quotes it and the fix repairs it. */
 export const BUDGET_FIELD = 'agentsMdMaxBytes';
 
+/** The floor's typecheck-binary key. Named once: the problem quotes it and the fix repairs it. */
+export const TYPECHECK_BIN_FIELD = 'typecheckBin';
+
 /**
  * `agentsMdMaxBytes`, or a reason it is not one. A budget that is not a positive whole number is
  * the caller's bug and must not silently fall back to the default: a floor file that says
@@ -57,6 +72,27 @@ function readBudget(payload: Record<string, unknown> | undefined): {
   return { budget: raw, problems: [] };
 }
 
+/**
+ * `typecheckBin`, or a reason it is not one. A non-string value must not silently fall back to
+ * `tsc`: a floor that names `"typecheckBin": 7` and gets `tsc` anyway is a repository that
+ * believes the `typecheck` step is running a checker it is not, which is the same false green
+ * `readBudget` above already refuses for the byte count. An empty string is refused for the same
+ * reason `-b`'s own project argument may not be empty — `bunx '' -b …` is not a step that failed
+ * to typecheck, it is a step that never ran a compiler at all.
+ */
+function readTypecheckBin(payload: Record<string, unknown> | undefined): {
+  bin?: string;
+  problems: readonly string[];
+} {
+  const raw = payload?.[TYPECHECK_BIN_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'string' || raw.trim().length === 0)
+    return {
+      problems: [`"${TYPECHECK_BIN_FIELD}" is ${JSON.stringify(raw)}, which is not a binary name`],
+    };
+  return { bin: raw, problems: [] };
+}
+
 const asRecord = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -86,12 +122,18 @@ export function parseVerifyFloor(
   }
   const record = asRecord(payload);
   const budget = readBudget(record);
+  const typecheckBin = readTypecheckBin(record);
   const steps = record?.['steps'];
   if (!Array.isArray(steps)) {
     return {
       steps: [],
       ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
-      problems: ['it has no "steps" array of step names', ...budget.problems],
+      ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+      problems: [
+        'it has no "steps" array of step names',
+        ...budget.problems,
+        ...typecheckBin.problems,
+      ],
     };
   }
   const named = steps.filter((step): step is string => typeof step === 'string');
@@ -99,8 +141,10 @@ export function parseVerifyFloor(
   return {
     steps: named.filter((step) => declared.includes(step)),
     ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
+    ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
     problems: [
       ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
+      ...typecheckBin.problems,
       ...(unknown.length === 0
         ? []
         : [`"steps" names ${unknown.join(', ')}, which x verify does not run`]),
@@ -185,7 +229,10 @@ export const floorProblemFindings = (floor: VerifyFloor | undefined): readonly F
  * does not fix it is the failure `packages/cli/CLAUDE.md` names, and the budget is the first
  * problem this file can report that is not about `steps` at all.
  */
-const fixFor = (problem: string): string =>
-  problem.includes(`"${BUDGET_FIELD}"`)
-    ? `x verify --json   # then set "${BUDGET_FIELD}" in ${VERIFY_FLOOR_FILE} to a positive whole number of bytes, or drop the key for the ${AGENTS_MD_MAX_BYTES}B default`
-    : `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`;
+const fixFor = (problem: string): string => {
+  if (problem.includes(`"${BUDGET_FIELD}"`))
+    return `x verify --json   # then set "${BUDGET_FIELD}" in ${VERIFY_FLOOR_FILE} to a positive whole number of bytes, or drop the key for the ${AGENTS_MD_MAX_BYTES}B default`;
+  if (problem.includes(`"${TYPECHECK_BIN_FIELD}"`))
+    return `x verify --json   # then set "${TYPECHECK_BIN_FIELD}" in ${VERIFY_FLOOR_FILE} to a non-empty binary name, or drop the key to run tsc`;
+  return `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`;
+};