@ultimat3/cli 20.2.1 → 22.0.0

package/README.md

@@ -14,7 +14,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x verify` | **the gate** | 20 named steps, each with pass/fail + duration |
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
 | `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
-| `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
+| `x mcp serve` | `@ultimat3/mcp`'s 18 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
 | `x doctor` | environment, ports, drift, PWA prerequisites | every finding carries a fix command |
 | `x deploy` | container deploy plan | compose or helm; zero platform primitives |
 | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
@@ -118,7 +118,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `app-runtime.ts` | the app's `RuntimeOverrides`: `apps/<app>/runtime.ts` exports `runtime`, read by `x dev` and by `runRole` when its caller passed none |
 | `local-cli.ts` | which `x` runs: a global CLI inside an app hands over to the app's own, because a second module instance is an empty registry |
 | `measurement-actor.ts` | the actor a weigh-and-discard render runs as — every permission, never served |
-| `dev-live-feed.ts` | what feeds the sync node this process booted: the in-process row observer under the embedded database, the WAL decoder with a real one, nothing without the role — `live=` on the ready line |
+| `runtime-live-feed.ts` | what feeds the sync node this process booted: the in-process row observer under the embedded database, the WAL decoder with a real one, nothing without the role — `live=` on the ready line |
 | `app-manifest.ts` | `x.manifest.json`, projected by `@ultimat3/manifest` |
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
@@ -160,3 +160,41 @@ Every emitted source has a `<file>.test.ts` beside it that passes on the first r
 
 `X_CLI_UNKNOWN_COMMAND` `X_CLI_BAD_FLAG` `X_VERIFY_FAILED` `X_NOT_IN_APP` `X_BUN_VERSION`
 `X_NOT_IMPLEMENTED` `X_GUARD_INVALID` `X_GUARD_FAILED` `X_GUARD_FINDING_INVALID`
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `BadFlagError` | `X_CLI_BAD_FLAG` | `src/errors.ts` |
+| `BuildEntryMissingError` | `X_BUILD_ENTRY_MISSING` | `src/build-errors.ts` |
+| `BunVersionError` | `X_BUN_VERSION` | `src/errors.ts` |
+| `CatalogExistsError` | `X_GENERATE_CONFLICT` | `src/errors.ts` |
+| `CdpBrowserMissingError` | `X_CDP_BROWSER_MISSING` | `src/cdp-errors.ts` |
+| `CdpCallFailedError` | `X_CDP_CALL_FAILED` | `src/cdp-errors.ts` |
+| `CdpLaunchFailedError` | `X_CDP_LAUNCH_FAILED` | `src/cdp-errors.ts` |
+| `CdpTimeoutError` | `X_CDP_TIMEOUT` | `src/cdp-errors.ts` |
+| `CliNotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `DeclarationUnknownError` | `X_DECLARATION_UNKNOWN` | `src/errors.ts` |
+| `E2eAppFailedError` | `X_E2E_APP_FAILED` | `src/e2e-errors.ts` |
+| `E2eEvaluateCapturedError` | `X_E2E_EVALUATE_CAPTURED` | `src/e2e-errors.ts` |
+| `E2eEvaluateThrewError` | `X_E2E_EVALUATE_THREW` | `src/e2e-errors.ts` |
+| `E2eEvaluateUnsupportedError` | `X_E2E_EVALUATE_UNSUPPORTED` | `src/e2e-errors.ts` |
+| `E2eLocatorAmbiguousError` | `X_E2E_LOCATOR_AMBIGUOUS` | `src/e2e-errors.ts` |
+| `E2eLocatorEmptyError` | `X_E2E_LOCATOR_EMPTY` | `src/e2e-errors.ts` |
+| `E2eServiceWorkerAbsentError` | `X_E2E_SERVICE_WORKER_ABSENT` | `src/e2e-errors.ts` |
+| `ErrorCodeUnknownError` | `X_ERROR_CODE_UNKNOWN` | `src/errors.ts` |
+| `FixTargetUnknownError` | `X_FIX_TARGET_UNKNOWN` | `src/errors.ts` |
+| `FrameworkSchemaFailedError` | `X_FRAMEWORK_SCHEMA_FAILED` | `src/schema-errors.ts` |
+| `JobUnknownError` | `X_JOB_UNKNOWN` | `src/errors.ts` |
+| `MissingPositionalError` | `X_CLI_BAD_FLAG` | `src/errors.ts` |
+| `MissingSubcommandError` | `X_CLI_BAD_FLAG` | `src/errors.ts` |
+| `NoTestFilesError` | `X_TEST_NO_FILES` | `src/errors.ts` |
+| `NotInAppError` | `X_NOT_IN_APP` | `src/errors.ts` |
+| `PortInvalidError` | `X_PORT_INVALID` | `src/errors.ts` |
+| `QuerySubscribesUnknownError` | `X_QUERY_SUBSCRIBES_UNKNOWN` | `src/db-subscribes.ts` |
+| `RoleUnknownError` | `X_ROLE_UNKNOWN` | `src/errors.ts` |
+| `UnknownCommandError` | `X_CLI_UNKNOWN_COMMAND` | `src/errors.ts` |
+| `VerifyFailedError` | `X_VERIFY_FAILED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./serve": "./src/serve-entry.ts"
   },
   "bin": {
     "x": "./src/bin.ts"
@@ -36,35 +37,34 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@babel/core": "^7.28.4",
-    "@ultimat3/action": "20.2.1",
-    "@ultimat3/admin": "20.2.1",
-    "@ultimat3/ai": "20.2.1",
-    "@ultimat3/auth": "20.2.1",
-    "@ultimat3/cache": "20.2.1",
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/db": "20.2.1",
-    "@ultimat3/entity": "20.2.1",
-    "@ultimat3/flags": "20.2.1",
-    "@ultimat3/http": "20.2.1",
-    "@ultimat3/i18n": "20.2.1",
-    "@ultimat3/jobs": "20.2.1",
-    "@ultimat3/mail": "20.2.1",
-    "@ultimat3/manifest": "20.2.1",
-    "@ultimat3/mcp": "20.2.1",
-    "@ultimat3/money": "20.2.1",
-    "@ultimat3/notify": "20.2.1",
-    "@ultimat3/policy": "20.2.1",
-    "@ultimat3/pwa": "20.2.1",
-    "@ultimat3/query": "20.2.1",
-    "@ultimat3/realtime": "20.2.1",
-    "@ultimat3/render": "20.2.1",
-    "@ultimat3/schema": "20.2.1",
-    "@ultimat3/scraping": "20.2.1",
-    "@ultimat3/seo": "20.2.1",
-    "@ultimat3/storage": "20.2.1",
-    "@ultimat3/testing": "20.2.1",
-    "@ultimat3/time": "20.2.1",
+    "@babel/core": "^8.0.1",
+    "@ultimat3/action": "22.0.0",
+    "@ultimat3/admin": "22.0.0",
+    "@ultimat3/ai": "22.0.0",
+    "@ultimat3/auth": "22.0.0",
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/db": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/flags": "22.0.0",
+    "@ultimat3/http": "22.0.0",
+    "@ultimat3/i18n": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/mail": "22.0.0",
+    "@ultimat3/manifest": "22.0.0",
+    "@ultimat3/mcp": "22.0.0",
+    "@ultimat3/money": "22.0.0",
+    "@ultimat3/notify": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/pwa": "22.0.0",
+    "@ultimat3/query": "22.0.0",
+    "@ultimat3/realtime": "22.0.0",
+    "@ultimat3/render": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/seo": "22.0.0",
+    "@ultimat3/storage": "22.0.0",
+    "@ultimat3/testing": "22.0.0",
+    "@ultimat3/time": "22.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/api-registration.ts

@@ -0,0 +1,124 @@
+// `x g job` / `x g task` / `x g resource` hand what they wrote to `apps/web/api/index.ts`. The scan
+// registers actions and queries by export name on its own and registers NO job: a job module
+// nothing lists keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
+// `x.manifest.json` and in every dead-letter trace — under a green gate (plan 101 slice 11 b).
+
+import { containedPath } from './generate-write';
+import { camel } from './templates/naming';
+import { wrapList } from './templates/wrap';
+
+/** The one file `defineApi` is called from in a scaffolded app. */
+export const API_INDEX = 'apps/web/api/index.ts';
+
+/** One module to import as a namespace and list under a `defineApi` key. */
+export interface ApiEntry {
+  readonly key: 'jobs' | 'tasks';
+  /** The namespace binding: the file's own name, camelCased — `reindexPost`. */
+  readonly binding: string;
+  /** From `apps/web/api/`: `../app/post/jobs/reindex-post`. */
+  readonly specifier: string;
+}
+
+const PRIMITIVE_PATH =
+  /^apps\/web\/(?<rest>[^/]+\/[^/]+\/(?<dir>jobs|tasks)\/(?<file>[a-z0-9-]+))\.ts$/;
+
+/** The job and task modules among the paths a generator wrote. Tests are not modules to list. */
+export function apiEntriesFor(written: readonly string[]): readonly ApiEntry[] {
+  return written.flatMap((path) => {
+    const groups = PRIMITIVE_PATH.exec(path)?.groups;
+    if (groups === undefined) return [];
+    const { rest = '', dir, file = '' } = groups;
+    return [
+      { key: dir === 'tasks' ? 'tasks' : 'jobs', binding: camel(file), specifier: `../${rest}` },
+    ];
+  });
+}
+
+/** Every `[...]` entry of a `key: [...]` list in the `defineApi({ ... })` call. */
+const listOf = (
+  source: string,
+  key: string,
+): { start: number; end: number; items: string[] } | undefined => {
+  const open = new RegExp(`\\n(\\s*)${key}: \\[`).exec(source);
+  if (open === null) return undefined;
+  const start = open.index + open[0].length;
+  const end = source.indexOf(']', start);
+  if (end === -1) return undefined;
+  const items = source
+    .slice(start, end)
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+  return { start, end, items };
+};
+
+/**
+ * `source` with each entry imported and listed. The import joins the `import * as` block in sorted
+ * position; the binding joins its list, which is created after `actions: [...]` when the call has
+ * none. An index that is not the scaffold's shape — no `defineApi({`, no `actions:` list — is
+ * returned untouched with the entries in `skipped`, and the `manifest` step's X_JOB_UNREGISTERED
+ * names the edit.
+ */
+export function insertApiEntries(
+  source: string,
+  entries: readonly ApiEntry[],
+): { readonly source: string; readonly skipped: readonly ApiEntry[] } {
+  let next = source;
+  const skipped: ApiEntry[] = [];
+  for (const entry of entries) {
+    const importLine = `import * as ${entry.binding} from '${entry.specifier}';`;
+    const call = next.indexOf('defineApi({');
+    const actions = listOf(next, 'actions');
+    if (call === -1 || actions === undefined) {
+      skipped.push(entry);
+      continue;
+    }
+    const list = listOf(next, entry.key);
+    if (list?.items.includes(entry.binding) === true) continue;
+    if (list === undefined) {
+      // After `actions: [...],` — the order `x new` writes: actions, queries, jobs, tasks.
+      const after = next.indexOf('\n', actions.end);
+      const line = `  ${entry.key}: [${entry.binding}],`;
+      next = `${next.slice(0, after + 1)}${line}\n${next.slice(after + 1)}`;
+    } else {
+      const items = [...list.items, entry.binding];
+      const lineStart = next.lastIndexOf('\n', list.start) + 1;
+      const indent = /^\s*/.exec(next.slice(lineStart))?.[0] ?? '';
+      const rewritten = wrapList(indent, `${entry.key}: [`, items, ']');
+      next = `${next.slice(0, lineStart)}${rewritten}${next.slice(list.end + 1)}`;
+    }
+    if (!next.includes(importLine)) next = withImport(next, importLine);
+  }
+  return { source: next, skipped };
+}
+
+/**
+ * The import, in the `import * as` block Biome keeps sorted by specifier. Placed before the first
+ * relative import whose specifier sorts after it, or after the last one.
+ */
+function withImport(source: string, importLine: string): string {
+  const specifier = /from '([^']+)'/.exec(importLine)?.[1] ?? '';
+  const lines = source.split('\n');
+  const relative = lines
+    .map((line, index) => ({ line, index, from: /^import .* from '(\.[^']*)';$/.exec(line)?.[1] }))
+    .filter((row) => row.from !== undefined);
+  const before = relative.find((row) => (row.from ?? '') > specifier);
+  const at = before?.index ?? (relative.at(-1)?.index ?? -1) + 1;
+  lines.splice(at, 0, importLine);
+  return lines.join('\n');
+}
+
+/** Performs `insertApiEntries` on the app's index. Answers the paths it rewrote. */
+export async function registerGeneratedPrimitives(
+  root: string,
+  written: readonly string[],
+): Promise<readonly string[]> {
+  const entries = apiEntriesFor(written);
+  const file = containedPath(root, API_INDEX);
+  if (entries.length === 0 || !(await Bun.file(file).exists())) return [];
+  const before = await Bun.file(file).text();
+  const { source } = insertApiEntries(before, entries);
+  if (source === before) return [];
+  await Bun.write(file, source);
+  return [API_INDEX];
+}

package/src/app-artifacts.ts

@@ -0,0 +1,39 @@
+// The two generated contracts an app commits — `x.manifest.json` and `openapi.json` — written by one
+// function, because two commands wrote them and only one wrote both: `x g` refreshed the manifest
+// and left `openapi.json` behind, so its own output failed the `contract-diff` step next.
+
+import { join } from 'node:path'; // why: Bun ships no path-join primitive.
+import type { Manifest } from '@ultimat3/manifest';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { writeAppManifest } from './app-manifest';
+import { OPENAPI_FILE, openApiJson } from './app-openapi';
+
+export interface ArtifactOptions {
+  /** `x manifest --no-openapi` writes the manifest alone. */
+  readonly openapi: boolean;
+  /**
+   * Refresh only what is already committed. `x g` never introduces a generated file an app did not
+   * ask to maintain; `x manifest` is the asking.
+   */
+  readonly onlyExisting: boolean;
+}
+
+/** Writes the app's generated contracts from one projection. Answers the app-relative paths. */
+export async function writeAppArtifacts(
+  root: string,
+  manifest: Manifest,
+  options: ArtifactOptions,
+): Promise<readonly string[]> {
+  const written: string[] = [];
+  const present = async (file: string): Promise<boolean> =>
+    !options.onlyExisting || (await Bun.file(join(root, file)).exists());
+  if (await present(MANIFEST_FILENAME)) {
+    await writeAppManifest(root, manifest);
+    written.push(MANIFEST_FILENAME);
+  }
+  if (options.openapi && (await present(OPENAPI_FILE))) {
+    await Bun.write(join(root, OPENAPI_FILE), openApiJson(manifest));
+    written.push(OPENAPI_FILE);
+  }
+  return written;
+}

package/src/app-boundaries.ts

@@ -17,6 +17,7 @@ import { dirname, join, normalize, relative } from 'node:path/posix';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
+import { scanRuntimeImports, stripShebang } from './import-scan';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
 import { quoteArg } from './shell-quote';
@@ -27,6 +28,7 @@ export const BOUNDARY_CODES = [
   'X_BOUNDARY_APP_TO_API',
   'X_BOUNDARY_ROUTE_TO_DB',
   'X_BOUNDARY_SERVICE_TO_HTTP',
+  'X_BOUNDARY_SURFACE_IMPORT',
 ] as const;
 
 export type BoundaryCode = (typeof BOUNDARY_CODES)[number];
@@ -41,6 +43,8 @@ const CODE_OF: Readonly<Record<BoundaryRule, BoundaryCode>> = {
   'site-imports-app': 'X_BOUNDARY_SITE_TO_APP',
   'shared-is-a-leaf': 'X_BOUNDARY_SHARED_LEAF',
   'app-imports-api-at-runtime': 'X_BOUNDARY_APP_TO_API',
+  // Every other crossing `SURFACE_SPECS` does not allow: the table is the rule (`@ultimat3/render`).
+  'surface-imports-surface': 'X_BOUNDARY_SURFACE_IMPORT',
 };
 
 /**
@@ -68,16 +72,7 @@ const isDbSpecifier = (specifier: string): boolean =>
 const isHttpSpecifier = (specifier: string): boolean =>
   specifier === '@ultimat3/http' || /(^|[/:])https?($|\/)/.test(specifier);
 
-/** The transpiler rejects a shebang, and an app's `bin/` entry points legitimately have one. */
-export const stripShebang = (source: string): string =>
-  source.startsWith('#!') ? source.slice(source.indexOf('\n') + 1) : source;
-
-/** Bun's transpiler is the parser; a regex fallback would miss re-exports and dynamic imports. */
-export function scanRuntimeImports(file: SourceFile): readonly string[] {
-  const loader = file.path.endsWith('x') ? 'tsx' : 'ts';
-  const transpiler = new Bun.Transpiler({ loader });
-  return transpiler.scanImports(stripShebang(file.source)).map((entry) => entry.path);
-}
+export { scanRuntimeImports, stripShebang };
 
 const CANDIDATE_SUFFIXES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'] as const;
 

package/src/app-env.ts

@@ -2,9 +2,9 @@
 // `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
 // declaration, both files (axiom 2) — nothing here holds a second list of variable names.
 
-// Bun ships no equivalent: `existsSync` answers whether this root is an app, `join` builds the
-// host-separator path to the two files this module reads.
+// why: Bun ships no synchronous exists; `existsSync` answers whether this root is an app.
 import { existsSync } from 'node:fs';
+// why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
 import {

package/src/app-load.ts

@@ -5,13 +5,15 @@
 
 // Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
 // relative POSIX path every finding and every manifest fact is keyed by.
-import { relative, sep } from 'node:path';
-import { registerActions } from '@ultimat3/action';
+import { join, relative, sep } from 'node:path';
+import { listActions, registerActions } from '@ultimat3/action';
+import { describeEntities } from '@ultimat3/entity';
 import { localeConfig } from '@ultimat3/i18n';
+import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
-import { registerQueries } from '@ultimat3/query';
+import { listQueries, registerQueries } from '@ultimat3/query';
 import type { RouteConfig } from '@ultimat3/render';
-import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
+import { isRouteConfig, pageComponentOf, registerRoute, routeEntries } from '@ultimat3/render';
 // For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
 // installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
 // every app module below is loaded by the dynamic `import()` in this file. Before the render
@@ -19,10 +21,12 @@ import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render'
 // here is six hops through `error-contract` → `fix-command` → the command registry, which is an
 // accident one refactor away from compiling every app's `.tsx` to `React.createElement`.
 import '@ultimat3/render/server';
+import { APP_CONFIG_FILE } from './app-root';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
 
 /** Every place an app keeps code the framework has to see. */
 const APP_GLOBS = [
@@ -112,8 +116,10 @@ export async function loadApp(root: string): Promise<LoadedApp> {
       // A SEGMENT, never a substring: an app checked out under
       // `~/dev/node_modules-experiments/myapp` answered `includes('node_modules')` for every
       // file it holds, so this loop imported none of them and the app registered nothing.
-      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
+      // The ROOT-RELATIVE path is tested, never the absolute one: an app checked out under
+      // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
       const file = relative(root, absolute).split(sep).join('/');
+      if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
       if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
         continue;
       }
@@ -138,6 +144,16 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   }
 
   files.sort();
+  // An app that imported NOTHING and reported nothing is a registry every later step reads as
+  // empty-and-fine. With an `app.config.ts` beside it, that is never what the author meant.
+  if (
+    files.length === 0 &&
+    findings.length === 0 &&
+    registersNothing() &&
+    (await Bun.file(join(root, APP_CONFIG_FILE)).exists())
+  ) {
+    findings.push(emptyAppFinding(root));
+  }
   // Read after the loop, never before it: `configureLocales` runs on the app's own import.
   return {
     root,
@@ -148,6 +164,22 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   };
 }
 
+/** No primitive in any registry this scan fills — a process that registered some itself is not empty. */
+const registersNothing = (): boolean =>
+  listActions().length === 0 &&
+  listQueries().length === 0 &&
+  routeEntries().length === 0 &&
+  registeredJobs().length === 0 &&
+  registeredTasks().length === 0 &&
+  describeEntities().length === 0;
+
+const emptyAppFinding = (root: string): Finding => ({
+  code: 'X_APP_EMPTY',
+  cause: `${root} has an ${APP_CONFIG_FILE} and loadApp imported no module under ${APP_GLOBS.join(', ')}, so every step reading the registries would check nothing`,
+  fix: 'x doctor --json',
+  at: APP_CONFIG_FILE,
+});
+
 /**
  * Registers a module once; every later call replays whatever the first one reported — except for
  * a route module, which a later call re-registers from disk when its source has changed.

package/src/app-openapi.ts

@@ -5,9 +5,13 @@
 // OpenAPI builder to drift from the ones the packages serve. Until 2026-09 only the actions were
 // here, and every `GET /_x/query/<name>` the server mounted was a route the spec had never heard of.
 
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
 import { buildOpenApi, serializeOpenApi } from '@ultimat3/action';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import { queryOpenApiPaths } from '@ultimat3/query';
+import type { Finding } from './output';
 
 export const OPENAPI_FILE = 'openapi.json';
 
@@ -18,3 +22,26 @@ export const openApiJson = (manifest: Manifest): string => {
   // can never shadow one with the other. `serializeOpenApi` sorts the merged keys.
   return serializeOpenApi({ ...document, paths: { ...document.paths, ...queryOpenApiPaths() } });
 };
+
+/**
+ * The typed client is generated from `openapi.json`, so a stale spec ships a wrong client. One
+ * check, read by `x verify`'s `manifest` step AND `x manifest --check` — which looked at
+ * `x.manifest.json` alone and answered "fresh" over a spec the gate refused.
+ */
+export async function openApiStaleness(
+  root: string,
+  manifest: Manifest,
+): Promise<readonly Finding[]> {
+  const path = join(root, OPENAPI_FILE);
+  if (!(await Bun.file(path).exists())) return [];
+  if ((await Bun.file(path).text()) === openApiJson(manifest)) return [];
+  return [
+    {
+      code: 'X_MANIFEST_STALE',
+      cause: `${OPENAPI_FILE} does not match the actions the code registers`,
+      fix: 'x manifest',
+      docs: ERROR_DOCS_URL,
+      at: OPENAPI_FILE,
+    },
+  ];
+}

package/src/app-root.ts

@@ -24,7 +24,7 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * (`bun run typecheck` is clean against `@types/bun@1.3.14`), and `>=1.4.0` therefore bars Bun 1.3
  * users for a capability the framework does not use. What refused it is a Bun 1.3.14 defect, not
  * the paperwork: a service shutdown against a destroyed database never resolves there
- * (`queue.stop()`, reproduced by `dev-runtime.live.test.ts`), so an app on a runtime this line
+ * (`queue.stop()`, reproduced by `runtime-services.live.test.ts`), so an app on a runtime this line
  * declared supported would hang on graceful shutdown the moment its database went away. The full
  * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
  */

package/src/async-pages.ts

@@ -0,0 +1,32 @@
+// A route whose `Page` is an `async` function and which declares no `load`. It renders — the
+// renderer awaits whatever the component returns — so no suite fails on it, and its data read
+// silently skips everything `load` is for: the route's cache, `meta` computed from the data, the
+// streaming boundary and the measurement render `x build` weighs. The social demo shipped eleven
+// (plan 101 slice 11 l); nothing asked.
+
+import type { RouteEntry } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import type { Finding } from './output';
+
+/** `async function Page` and `async () =>` both construct one; a sync one never does. */
+const isAsync = (value: unknown): boolean =>
+  typeof value === 'function' && value.constructor.name === 'AsyncFunction';
+
+export function asyncPageFinding(file: string): Finding {
+  return {
+    code: 'X_ROUTE_ASYNC_PAGE',
+    cause: `${file} exports an async Page, so its data read bypasses load's caching and meta`,
+    fix: `in ${file}: move each await in Page into export const load = (ctx) => …, and read it with the page's data prop`,
+    at: file,
+  };
+}
+
+/** Every registered route whose page component is async and whose config declares no `load`. */
+export function asyncPageFindings(
+  entries: readonly Pick<RouteEntry, 'file' | 'config' | 'component'>[] = routeEntries(),
+): readonly Finding[] {
+  return entries
+    .filter((entry) => entry.config.load === undefined && isAsync(entry.component))
+    .map((entry) => asyncPageFinding(entry.file))
+    .sort((a, b) => (a.at ?? '').localeCompare(b.at ?? ''));
+}

package/src/bin.ts

@@ -4,6 +4,7 @@
 
 import { dispatch } from './dispatch';
 import { resolveLocalCli } from './local-cli';
+import { cwdFromArgv } from './root-env';
 // The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
 // one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
 // because fd 1 is not always this process's to write on — `x mcp serve --transport stdio` hands it
@@ -15,7 +16,12 @@ import { writeErrorLine, writeLine } from './write-line';
 // `--json` consumer reading fd 1 sees exactly the child's one document. `process.execPath` is the
 // Bun that is already running, never a `PATH` lookup: the child's `import.meta.path` resolves to
 // the app's file, so its own `resolveLocalCli` answers "same file" and the chain stops at one hop.
-const local = resolveLocalCli({ cwd: process.cwd(), selfPath: import.meta.path, env: Bun.env });
+// `--cwd` decides WHICH app's CLI, exactly as it decides which app `dispatch` runs against.
+const local = resolveLocalCli({
+  cwd: cwdFromArgv(Bun.argv.slice(2), process.cwd()),
+  selfPath: import.meta.path,
+  env: Bun.env,
+});
 if (local !== undefined) {
   writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);
   const child = Bun.spawn([process.execPath, local, ...Bun.argv.slice(2)], {

package/src/boundary-findings.ts

@@ -0,0 +1,36 @@
+// The surface findings `x verify` reports, each carrying the CONCRETE edit as its `fix:`. It said
+// `x fix boundary <file>`, which printed a second fix and wrote nothing — a fix whose whole content
+// was another command to run for the real one (plan 101 slice 11 j). The planner is the same one
+// `x fix boundary` prints from, so the gate and the command cannot disagree about the cut.
+
+import { appImportGraph, checkImportRules, readAppSources } from './app-boundaries';
+import { planBoundaryCuts } from './boundary-cuts';
+import type { Finding } from './output';
+
+/** A cut and a finding name one violation when they share its code, its importer and its chain. */
+const keyOf = (code: string, at: string | undefined, cause: string): string =>
+  [code, at ?? '', cause].join('\u0000');
+
+/** `findings` with every surface violation's `fix` replaced by the cut that clears it. */
+export function withCutEdits(
+  findings: readonly Finding[],
+  graph: Parameters<typeof planBoundaryCuts>[1],
+): readonly Finding[] {
+  const edits = new Map<string, string>();
+  for (const finding of findings) {
+    if (finding.at === undefined) continue;
+    for (const cut of planBoundaryCuts(finding.at, graph)) {
+      edits.set(keyOf(cut.code, cut.at, cut.cause), cut.edit);
+    }
+  }
+  return findings.map((finding) => {
+    const edit = edits.get(keyOf(finding.code, finding.at, finding.cause));
+    return edit === undefined ? finding : { ...finding, fix: edit };
+  });
+}
+
+/** Read the app's sources once, check them, and hand back findings whose fix is the edit. */
+export async function appBoundaryFindings(root: string): Promise<readonly Finding[]> {
+  const files = await readAppSources(root);
+  return withCutEdits(checkImportRules(files), appImportGraph(files));
+}