@ultimat3/cli 20.1.4 → 20.1.5

package/package.json

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

package/src/cmd-dev.ts

@@ -128,6 +128,9 @@ const envOf = (env: StartDevOptions['env']): { env?: string } => {
  * still be reachable while something is broken.
  */
 export async function startDev(options: StartDevOptions): Promise<DevServer> {
+  // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
+  // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
+  declareDevEnvironment(options.env);
   const services = resolveServices(options.root, options.env);
   const runtime: RunningServices = await startServices(services, options.env);
   // Installed before the app loads, so a span opened during registration is already recorded.
@@ -375,9 +378,6 @@ export const devCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('dev', ctx.cwd).dir;
-    // BEFORE `startDev` imports a single app module — see `dev-environment.ts` for why this must
-    // run this early, and why it mutates the real `process.env` rather than `startDev`'s `env`.
-    declareDevEnvironment(ctx.env);
     // Validated, not `parseInt`'d: `x dev --port abc` handed `NaN` to `Bun.serve`, which binds an
     // arbitrary port — a dev server reachable at an address nothing printed.
     const port = intFlagOr(

package/src/dev-sync.ts

@@ -224,17 +224,27 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
  * 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.
+ * Port 0 is NOT passed through to the kernel. It cannot be incremented (`+ 1` would ask for port
+ * 1), but the web role has bound by the time this runs and `appUrl` carries the port it got — and
+ * `PORT + 1` is the contract every scaffolded `sync-url.ts` computes from and the wiki states. A
+ * scratch server (`x shot`, `ui.shot`) always asks for 0, so before this every one of its
+ * pictures carried `WebSocket … ERR_CONNECTION_REFUSED` for every live island, on the framework's
+ * own account. With no web role to follow, 0 still goes to the kernel. The reported url is the
+ * listener's own bound address either way, never a string built from the port that was requested.
  */
+function syncPortFrom(requested: number, appUrl: string | null): number {
+  if (requested !== 0 || appUrl === null) return syncPortFor(requested);
+  const bound = Number(new URL(appUrl).port);
+  return Number.isInteger(bound) && bound > 0 ? syncPortFor(bound) : 0;
+}
+
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
   registry: LiveQueryRegistry,
   appUrl: string | null,
 ): Promise<RunningSync> {
-  const port = syncPortFor(options.port);
+  const port = syncPortFrom(options.port, appUrl);
   try {
     // The SAME interface the web role binds, resolved from the same option and the same default.
     // Without this the sync node took Bun's `0.0.0.0` while `x dev`'s web role took `localhost`,

package/src/mcp-host.ts

@@ -44,7 +44,7 @@ import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
-import { uiCapabilities } from './mcp-ui';
+import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
 import { testEnvOverrides } from './test-dotenv';
@@ -179,7 +179,11 @@ export async function readOnlyRows(
   return { columns, rows: kept.map((row) => columns.map((column) => row[column])), guards };
 }
 
-function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
+function capabilities(
+  input: DevHostInput,
+  lazy: LazyServices,
+  ui: UiCapabilities,
+): DevCapabilities {
   const { root, runner, env } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
   // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
@@ -282,7 +286,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
 
     explainError: explainErrorCode,
 
-    ...uiCapabilities({ root, env }),
+    ...ui,
 
     async verify(fix: boolean): Promise<VerifyResult> {
       // The one safe autofix this repo actually has. Anything more would be the gate rewriting
@@ -313,11 +317,21 @@ export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpSer
   // every code it could have quoted.
   await Promise.all([loadApp(input.root), loadCodeFixes()]);
   const lazy = lazyServices(input);
+  const ui = uiCapabilities({ root: input.root, env: input.env });
   const introspection = frameworkIntrospection({
     routes: () => describeRoutes(),
     policies: () => policyFacts(),
   });
-  const server = createDevServer({ host: devHost(introspection, capabilities(input, lazy)) });
+  const server = createDevServer({ host: devHost(introspection, capabilities(input, lazy, ui)) });
   const caller = localCaller();
-  return { server, caller, tools: server.tools.names(caller), close: () => lazy.close() };
+  return {
+    server,
+    caller,
+    tools: server.tools.names(caller),
+    // The scratch server first: it holds the same embedded database the lazy services would.
+    close: async () => {
+      await ui.close();
+      await lazy.close();
+    },
+  };
 }

package/src/mcp-ui.ts

@@ -10,14 +10,16 @@ import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
 import type { UiIslandInput, UiIslandResult, UiShotInput, UiShotResult } from '@ultimat3/mcp';
 import { describeRoutes } from '@ultimat3/render';
+import type { ScrapeDriver } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
 import { appBrowser } from './browser-launcher';
 import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import { islandShot } from './cmd-shot-island';
 import type { Env } from './dev-services';
 import { islandVerdictJson } from './island-verdict';
+import { retryMemo } from './retry-memo';
 import { shotBrowserChoice } from './shot-browser';
-import { devServerFor } from './shot-server';
+import { devServerFor, type ShotServer } from './shot-server';
 import { verdictJson } from './shot-verdict';
 
 /** Kernel-picked, as `x shot` picks it: a scratch server never fights another project for :3000. */
@@ -65,28 +67,62 @@ export function matches(pattern: string, path: string): boolean {
 export interface UiHostInput {
   readonly root: string;
   readonly env: Env;
+  /** Injected by a test: the server a picture is of, in place of `devServerFor`. */
+  readonly boot?: (() => Promise<ShotServer>) | undefined;
+  /** Injected by a test: the browser, in place of `appBrowser` (which needs Chrome). */
+  readonly driver?: ((viewport: UiShotInput['viewport']) => Promise<ScrapeDriver>) | undefined;
+  /** Injected by a test: the route table, in place of the registry. */
+  readonly routes?: (() => readonly DeclaredRoute[]) | undefined;
 }
 
-export function uiCapabilities(input: UiHostInput): {
+export interface UiCapabilities {
   shotRoute(shot: UiShotInput): Promise<UiShotResult>;
   shotIsland(island: UiIslandInput): Promise<UiIslandResult>;
-} {
+  /** Stops the scratch server, if one was booted. Never boots one in order to stop it. */
+  close(): Promise<void>;
+}
+
+export function uiCapabilities(input: UiHostInput): UiCapabilities {
   const { root, env } = input;
-  const boot = () => devServerFor(root, env, SCRATCH_PORT);
+  // ONCE per process, never per call. `x shot` the command boots a server, photographs, and
+  // stops it — one process, one lifecycle. The dev MCP server is one process serving many calls,
+  // and a lifecycle drains exactly once: the second `ui.shot` in a session answered
+  // `X_LIFECYCLE_DRAINED`, the third `X_READINESS_CHECK_DUPLICATE`. So the scratch server (or the
+  // running `x dev` the lock names) is memoised for the host's life, `runShot` is handed a handle
+  // whose `stop` is a no-op, and `close()` is what stops it. A boot that rejected is retried on
+  // the next call, and has nothing to stop.
+  const scratch = retryMemo(() => (input.boot ?? (() => devServerFor(root, env, SCRATCH_PORT)))());
+  const boot = async (): Promise<ShotServer> => {
+    const server = await scratch.get();
+    return { url: server.url, origin: server.origin, stop: () => Promise.resolve() };
+  };
   // The same choice `x shot` makes from the environment: `PUPPETEER_EXECUTABLE_PATH`, a
   // provider's CDP URL, or the launcher's own discovery.
   const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
+  const routes = input.routes ?? describeRoutes;
+  let closed = false;
 
   return {
+    async close() {
+      // Idempotent, as `lazyServices().close()` is: the host closes once, a test may close twice,
+      // and a server stopped twice is a second drain on a lifecycle that has none left.
+      if (closed) return;
+      closed = true;
+      await (await scratch.started()?.catch(() => undefined))?.stop();
+    },
+
     async shotRoute(shot) {
-      assertBudgetedRoute(shot.route, describeRoutes());
+      assertBudgetedRoute(shot.route, routes());
       const { cdpUrl, executablePath } = browser();
-      const driver = await appBrowser({
-        root,
-        viewport: shot.viewport,
-        ...(executablePath === undefined ? {} : { executablePath }),
-        ...(cdpUrl === undefined ? {} : { cdpUrl }),
-      });
+      const driver =
+        input.driver === undefined
+          ? await appBrowser({
+              root,
+              viewport: shot.viewport,
+              ...(executablePath === undefined ? {} : { executablePath }),
+              ...(cdpUrl === undefined ? {} : { cdpUrl }),
+            })
+          : await input.driver(shot.viewport);
       // One directory per (route, viewport, scheme), so two pictures of one route at two widths
       // never overwrite each other and an agent can hold both.
       const outDir = join(