@ultimat3/cli 20.1.3 → 20.1.4

package/package.json

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

package/src/cmd-mcp.ts

@@ -1,4 +1,4 @@
-// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 13 tools, the JSON-RPC
+// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 15 tools, the JSON-RPC
 // dispatch, both transports and the structural SQL refusals all come from `@ultimat3/mcp`; the CLI
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
@@ -117,7 +117,7 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
  * What the session reports when it is over — on STDERR, which is the half this file's header
  * claimed and did not have. `dispatch` renders a `CommandResult` only after `run` resolves, and
  * this resolves when the peer closes stdin, so nothing lands mid-session; but fd 1 under this
- * transport carries JSON-RPC frames, and `✓ mcp stdio serving 13 tools` arriving on it after the
+ * transport carries JSON-RPC frames, and `✓ mcp stdio serving 15 tools` arriving on it after the
  * loop is a malformed frame to a peer still draining, and a second document under `--json`.
  *
  * Its own function so the addressing is testable without a live peer: `serveStdio` resolves only

package/src/cmd-shot.ts

@@ -8,7 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+import type { ColorScheme, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -190,6 +190,12 @@ export interface ShotRun {
    * with `--port 0` the port — and therefore the origin — does not exist until after the boot.
    */
   readonly extraHosts?: string | undefined;
+  /**
+   * What `prefers-color-scheme` the page sees, emulated BEFORE navigation so the boot script's
+   * "system" branch answers the same on every box. Absent means the box's own preference — what
+   * `x shot` has always done — and `ui.shot` names one explicitly for exactly that reason.
+   */
+  readonly colorScheme?: ColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
 }
 
@@ -219,6 +225,7 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
+    if (options.colorScheme !== undefined) await page.colorScheme(options.colorScheme);
     await page.goto(requestedUrl, { timeout: options.timeoutMs });
     if (options.settleMs > 0) await Bun.sleep(options.settleMs);
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no

package/src/error-codes.ts

@@ -154,6 +154,9 @@ export const CLI_OWNED_ERROR_CODES = [
   // repair is an install, and only `duplicate-packages.ts` can see that.
   'X_PACKAGE_DUPLICATED',
   'X_SHOT_BROWSER_MISSING',
+  // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
+  'X_UI_SHOT_ROUTE_UNKNOWN',
+  'X_UI_SHOT_ROUTE_UNBUDGETED',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
   // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
@@ -297,6 +300,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'ui.shot was asked for a path no route answers',
+  X_UI_SHOT_ROUTE_UNBUDGETED: 'ui.shot refused a route that declares no budget.js',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',

package/src/mcp-errors.ts

@@ -55,6 +55,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'x routes --json   # then ui.shot with one of its path values',
+  X_UI_SHOT_ROUTE_UNBUDGETED:
+    "x build --target static --json && x verify --only budgets --json   # after declaring budget: { js: '<n>kb' } in the route file",
   // The four island-capture codes. Each one's real repair is an edit to the app's own states file
   // or component, which no command can perform — so each names the command that REPRODUCES it with
   // the file and the reason attached, which is the runnable half.

package/src/mcp-host.ts

@@ -44,6 +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 { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
 import { testEnvOverrides } from './test-dotenv';
@@ -281,6 +282,8 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
 
     explainError: explainErrorCode,
 
+    ...uiCapabilities({ root, env }),
+
     async verify(fix: boolean): Promise<VerifyResult> {
       // The one safe autofix this repo actually has. Anything more would be the gate rewriting
       // code it was asked to judge.

package/src/mcp-ui.ts

@@ -0,0 +1,136 @@
+// The dev MCP server's two eyes: `ui.shot` (a route) and `ui.island` (a component's states), as
+// the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a browser is the CLI's
+// to launch. Both are `x shot` under another name: the same server lookup (a running `x dev` is
+// reused through its lock, otherwise a scratch one boots), the same driver, the same verdict.
+// Nothing here is a new capability; it is the existing one made reachable from inside the loop
+// an agent already works in, so "does it look right" stops needing a hand-written script.
+
+// why: Bun exposes no path-join primitive, and the picture's directory is a path an agent opens.
+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 { 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 { shotBrowserChoice } from './shot-browser';
+import { devServerFor } from './shot-server';
+import { verdictJson } from './shot-verdict';
+
+/** Kernel-picked, as `x shot` picks it: a scratch server never fights another project for :3000. */
+const SCRATCH_PORT = 0;
+
+/**
+ * The route a picture is of has to be a route this app declares WITH a JS budget. The gate
+ * refuses an unmeasured route (`X_BUDGET_UNMEASURED`), and a picture of a route nobody has
+ * finished declaring is a picture of a draft — an agent judging it would judge the wrong thing.
+ * Matched on the declared pattern, so `/links/abc123` finds `/links/:slug`.
+ */
+export interface DeclaredRoute {
+  readonly path: string;
+  readonly file: string;
+  readonly budgetJs: string | null;
+}
+
+export function assertBudgetedRoute(route: string, declared: readonly DeclaredRoute[]): void {
+  const path = route.split('?')[0] ?? route;
+  const hit = declared.find((entry) => matches(entry.path, path));
+  if (hit === undefined) {
+    throw new UltimateError({
+      code: 'X_UI_SHOT_ROUTE_UNKNOWN',
+      cause: `no route in this app answers ${route}`,
+      fix: 'x routes --json   # then ui.shot with one of its `path` values',
+    });
+  }
+  if (hit.budgetJs === null) {
+    throw new UltimateError({
+      code: 'X_UI_SHOT_ROUTE_UNBUDGETED',
+      cause: `${hit.file} declares no budget.js, so x verify would refuse it as X_BUDGET_UNMEASURED — a picture of it would be a picture of a draft`,
+      fix: `declare budget: { js: '<n>kb' } in ${hit.file}, then: x build --target static --json && x verify --only budgets --json`,
+    });
+  }
+}
+
+/** `/links/:slug` matches `/links/abc123`; one segment per `:param`, no globbing. */
+export function matches(pattern: string, path: string): boolean {
+  const want = pattern.split('/');
+  const have = path.split('/');
+  if (want.length !== have.length) return false;
+  return want.every((segment, index) => segment.startsWith(':') || segment === have[index]);
+}
+
+export interface UiHostInput {
+  readonly root: string;
+  readonly env: Env;
+}
+
+export function uiCapabilities(input: UiHostInput): {
+  shotRoute(shot: UiShotInput): Promise<UiShotResult>;
+  shotIsland(island: UiIslandInput): Promise<UiIslandResult>;
+} {
+  const { root, env } = input;
+  const boot = () => devServerFor(root, env, SCRATCH_PORT);
+  // 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 });
+
+  return {
+    async shotRoute(shot) {
+      assertBudgetedRoute(shot.route, describeRoutes());
+      const { cdpUrl, executablePath } = browser();
+      const driver = await appBrowser({
+        root,
+        viewport: shot.viewport,
+        ...(executablePath === undefined ? {} : { executablePath }),
+        ...(cdpUrl === undefined ? {} : { cdpUrl }),
+      });
+      // 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(
+        root,
+        SHOT_DIR,
+        shotSlug(shot.route),
+        `${shot.viewport.width}x${shot.viewport.height}-${shot.colorScheme}`,
+      );
+      const artifacts = await runShot({
+        route: shot.route,
+        outDir,
+        driver,
+        boot,
+        settleMs: DEFAULT_SETTLE_MS,
+        timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+        fullPage: shot.fullPage,
+        colorScheme: shot.colorScheme,
+      });
+      return {
+        ok: artifacts.verdict.ok,
+        image: artifacts.image,
+        verdictFile: artifacts.verdictFile,
+        verdict: verdictJson(artifacts.verdict),
+      };
+    },
+
+    async shotIsland(island) {
+      const { cdpUrl, executablePath } = browser();
+      const artifacts = await islandShot({
+        root,
+        island: island.island,
+        ...(island.state === undefined ? {} : { state: island.state }),
+        settleMs: DEFAULT_SETTLE_MS,
+        timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+        ...(executablePath === undefined ? {} : { executablePath }),
+        ...(cdpUrl === undefined ? {} : { cdpUrl }),
+        boot,
+      });
+      return {
+        ok: artifacts.verdict.ok,
+        dir: artifacts.dir,
+        verdictFile: artifacts.verdictFile,
+        verdict: islandVerdictJson(artifacts.verdict),
+      };
+    },
+  };
+}

package/src/output.ts

@@ -64,7 +64,7 @@ export interface CommandResult {
    * Which fd this result is written to. `stdout` for every command, absent included — and
    * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
    * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
-   * 13 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   * 15 tools` line printed after the loop exits is a malformed frame to whatever is reading.
    *
    * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
    * where a rendered line goes, and a payload that also claimed it would be a second answer to a

package/src/templates/guard-unzoned-date.ts

@@ -74,10 +74,17 @@ export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
       const open = match.index + match[0].length - 1;
       if (argumentsOf(text, open).includes('timeZone')) continue;
       const line = lineOf(text, match.index);
+      // The bare \`.toLocaleString(\` is ALSO \`Number.prototype.toLocaleString\`, and a regex cannot
+      // tell a count from a date. The match stands — a date formatted this way is the defect this
+      // guard exists for — but the fix names the number exit too, because \`{ timeZone }\` is not
+      // one: a number ignores it, and an author following the fix verbatim would ship a lie.
+      const bare = match[0].trim() === '.toLocaleString(';
       findings.push({
         code: CODE,
         cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
-        fix: \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        fix: bare
+          ? \`in \${file.path}: a Date → pass an explicit IANA zone, at.toLocaleString(locale, { timeZone: 'UTC' }); a NUMBER → new Intl.NumberFormat(locale).format(n) instead — then: x verify\`
+          : \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
         at: file.path,
       });
     }
@@ -130,6 +137,16 @@ unitTest('Intl.DateTimeFormat and toLocaleTimeString are the same rule', () => {
   expect(unzonedDates(file("at.toLocaleTimeString('en-US');"))).toHaveLength(1);
 });
 
+unitTest('the bare toLocaleString names the number exit, since a count matches it too', () => {
+  const findings = unzonedDates(file("const shown = count.toLocaleString('en-US');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.fix).toContain('Intl.NumberFormat');
+  expect(findings[0]?.fix).toContain('timeZone');
+  // The dated forms are unambiguous and keep the zone-only fix.
+  const dated = unzonedDates(file("at.toLocaleDateString('en-US');"));
+  expect(dated[0]?.fix).not.toContain('Intl.NumberFormat');
+});
+
 unitTest('a commented-out call is a note, not a call', () => {
   expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
 });