@ultimat3/cli 29.4.0 → 30.0.0

package/src/affected-unowned.ts

@@ -0,0 +1,43 @@
+// The checkout's top-level directories that no workspace owns or contains — in this repository,
+// `scripts/`: tests that import packages by relative path and declare no dependency on any, so the
+// workspace graph cannot say which change reaches them. `affected.ts` runs them for every change
+// that selects a workspace at all.
+
+// why: Bun ships no directory listing with file types.
+import { readdir } from 'node:fs/promises';
+import type { WorkspaceNode } from './workspace-graph';
+
+/** Never a home for a test the run should select: dependencies, git, build state. */
+const SKIPPED = (name: string): boolean => name.startsWith('.') || name === 'node_modules';
+
+/** A root-level workspace (`''` or `.`) owns the whole checkout. */
+const isRoot = (dir: string): boolean => dir === '' || dir === '.';
+
+/**
+ * Pure: `entries` (top-level directory names) less any that is, or holds, a workspace — sorted.
+ * A directory that holds one (`packages/`, `examples/`) is answered for by the graph.
+ */
+export function unownedDirs(
+  graph: readonly WorkspaceNode[],
+  entries: readonly string[],
+): readonly string[] {
+  if (graph.some((node) => isRoot(node.dir))) return [];
+  return entries
+    .filter((entry) => !SKIPPED(entry))
+    .filter(
+      (entry) => !graph.some((node) => node.dir === entry || node.dir.startsWith(`${entry}/`)),
+    )
+    .sort();
+}
+
+/** The same, read off the checkout root's own directory listing. */
+export async function readUnownedDirs(
+  root: string,
+  graph: readonly WorkspaceNode[],
+): Promise<readonly string[]> {
+  const listed = await readdir(root, { withFileTypes: true });
+  return unownedDirs(
+    graph,
+    listed.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
+  );
+}

package/src/affected.ts

@@ -13,6 +13,7 @@
 // directory is checkout-relative while a caller's scan yields paths relative to its own root.
 import { join, relative } from 'node:path';
 import { singleLine, UltimateError } from '@ultimat3/core';
+import { readUnownedDirs } from './affected-unowned';
 import { BadFlagError } from './errors';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
@@ -99,8 +100,21 @@ export interface AffectedPlan {
    */
   readonly rootWide: readonly string[];
   readonly workspaces: readonly WorkspaceNode[];
+  /**
+   * The root directories no workspace owns (`affected-unowned.ts`) — `scripts/` here — selected
+   * whenever any workspace is: their tests import packages by relative path, declare no
+   * dependency, and so are reached by a change the graph has no edge for. Empty when nothing is
+   * affected, and when the plan is root-wide (which already selects them).
+   */
+  readonly unowned: readonly string[];
 }
 
+/**
+ * The CLI is the tool every test run goes through — `x test`, the gate's steps, the preloads — so a
+ * change to its own source is a change to how every workspace is checked, not to one workspace.
+ */
+export const TOOL_WORKSPACE = '@ultimat3/cli';
+
 const byName = (a: WorkspaceNode, b: WorkspaceNode): number => (a.name > b.name ? 1 : -1);
 
 /**
@@ -110,6 +124,7 @@ const byName = (a: WorkspaceNode, b: WorkspaceNode): number => (a.name > b.name
 export function planAffected(
   graph: readonly WorkspaceNode[],
   changed: readonly string[],
+  unownedDirs: readonly string[] = [],
 ): AffectedPlan {
   const ignored = changed.filter(isDoc);
   const considered = changed.filter((path) => !isDoc(path));
@@ -117,18 +132,20 @@ export function planAffected(
   const seeds = new Set<string>();
   for (const path of considered) {
     const node = owningWorkspace(graph, path);
-    if (node === undefined) rootWide.push(path);
+    if (node === undefined || node.name === TOOL_WORKSPACE) rootWide.push(path);
     else seeds.add(node.name);
   }
   if (rootWide.length > 0) {
-    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName) };
+    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName), unowned: [] };
   }
   const reached = withDependents(graph, seeds);
+  const workspaces = graph.filter((node) => reached.has(node.name)).sort(byName);
   return {
     changed,
     ignored,
     rootWide,
-    workspaces: graph.filter((node) => reached.has(node.name)).sort(byName),
+    workspaces,
+    unowned: workspaces.length === 0 ? [] : [...unownedDirs],
   };
 }
 
@@ -266,8 +283,8 @@ export interface AffectedScope {
 export const scopePrefixes = (plan: AffectedPlan, root: string, cwd: string): readonly string[] =>
   plan.rootWide.length > 0
     ? ['']
-    : plan.workspaces
-        .map((workspace) => relative(cwd, join(root, workspace.dir)).split('\\').join('/'))
+    : [...plan.workspaces.map((workspace) => workspace.dir), ...plan.unowned]
+        .map((dir) => relative(cwd, join(root, dir)).split('\\').join('/'))
         .filter((path) => !path.startsWith('..'));
 
 export const inScope = (path: string, prefixes: readonly string[]): boolean =>
@@ -290,9 +307,11 @@ export interface AffectedScopeOptions {
 export async function affectedScope(options: AffectedScopeOptions): Promise<AffectedScope> {
   const selection = readAffectedSelection(options.args, options.command);
   const root = await gitRoot(options.runner, options.cwd, options.command);
+  const graph = await readWorkspaceGraph(root);
   const plan = planAffected(
-    await readWorkspaceGraph(root),
+    graph,
     await changedFiles(options.runner, { cwd: root, command: options.command, selection }),
+    await readUnownedDirs(root, graph),
   );
   return {
     selection,

package/src/app-boundaries.ts

@@ -35,6 +35,8 @@ export const BOUNDARY_CODES = [
   'X_BOUNDARY_ROUTE_TO_DB',
   'X_BOUNDARY_SERVICE_TO_HTTP',
   'X_BOUNDARY_SURFACE_IMPORT',
+  // `package-boundaries.ts`'s: it reads `packages/`, which this module's surface graph never holds.
+  'X_BOUNDARY_PACKAGE_TO_APP',
 ] as const;
 
 export type BoundaryCode = (typeof BOUNDARY_CODES)[number];
@@ -192,6 +194,32 @@ const generate = (kind: 'query' | 'action', path: string, then: string): string
   return `x g ${kind} ${named}   # ${then} ${commentSafe(path)}`;
 };
 
+/** The slice a route's import lands in, or `undefined` for a package like `@acme/db`. */
+const sliceOfImport = (path: string, specifier: string): string | undefined => {
+  // Resolved already where `scan` knew the file, and still relative where it did not.
+  const target = specifier.startsWith('.') ? normalize(join(dirname(path), specifier)) : specifier;
+  const [, surface, slice, rest] = /^apps\/[^/]+\/([^/]+)\/([^/]+)\/(.+)$/.exec(target) ?? [];
+  return surface !== undefined && SURFACE_NAMES.has(surface) && rest !== undefined
+    ? slice
+    : undefined;
+};
+
+/**
+ * A read through a database import. Into a slice, the query belongs there: without `--feature` a
+ * singular name wrote 14 files, a new entity and a table nobody asked for. A route named for its
+ * slice takes `<slice>-read`, since a query named as the entity collides with its import. With no
+ * slice to read, a new one is what the fix has to name.
+ */
+const routeToDbFix = (path: string, specifier: string): string => {
+  const then = `then call it from ${commentSafe(path)}`;
+  const subject = subjectOf(path);
+  const named = subject === undefined ? '<name>' : quoteArg(subject);
+  const slice = sliceOfImport(path, specifier);
+  if (slice === undefined) return `x g resource ${named}   # ${then}`;
+  const query = subject === slice || subject === `${slice}s` ? quoteArg(`${slice}-read`) : named;
+  return `x g query ${query} --feature ${quoteArg(slice)}   # ${then}`;
+};
+
 /**
  * Both fixes are one runnable line, with the rest of the instruction behind a `#` — a fix a
  * caller has to edit before it runs is prose, and prose is what "errors are instructions" bans.
@@ -204,7 +232,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
         findings.push({
           code: 'X_BOUNDARY_ROUTE_TO_DB',
           cause: `route imports the database ("${specifier}")${isRepoSpecifier(specifier) ? ', through a repo' : ''} — routes call actions and queries`,
-          fix: generate('query', file.path, 'then call it from'),
+          fix: routeToDbFix(file.path, specifier),
           docs: ERROR_DOCS_URL,
           at: file.path,
         });

package/src/app-evals.ts

@@ -7,6 +7,7 @@
 
 import {
   baselinePath,
+  describeAgents,
   describeEvals,
   EvalBaselineMissingError,
   EvalMissingError,
@@ -36,10 +37,17 @@ export async function checkEvalCoverage(root: string): Promise<readonly Finding[
   // Loading is idempotent per process: `x verify` loads the app once and every later step,
   // including the manifest, reads the same registries.
   await loadApp(root);
-  return promptsWithoutEvals().map((prompt) => ({
-    ...findingFrom(new EvalMissingError({ prompt: prompt.ref, id: prompt.id })),
-    at: prompt.ref,
-  }));
+  // An agent's prompt is measured by the agent arm — its tools and turns — so the fix names it.
+  const agents = new Map(describeAgents().map((fact) => [fact.prompt, fact.name]));
+  return promptsWithoutEvals().map((prompt) => {
+    const agent = agents.get(prompt.ref);
+    const missing = new EvalMissingError({
+      prompt: prompt.ref,
+      id: prompt.id,
+      ...(agent === undefined ? {} : { agent }),
+    });
+    return { ...findingFrom(missing), at: prompt.ref };
+  });
 }
 
 /**

package/src/app-load-unresolved.ts

@@ -0,0 +1,62 @@
+// A module that imports what does not resolve. It was `X_CLI_UNEXPECTED`, once per module reaching
+// it, with `x doctor --json` as the fix, and doctor answered "shippable": the cycle closed on itself.
+// Leaf module: `output.ts` reads it for a throw outside the scan, and the scan for one inside it.
+
+// why: a synchronous probe for an installed package's manifest; Bun ships no path helpers.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stringField } from '@ultimat3/core';
+import type { Finding } from './output';
+import { posixRelative } from './posix-path';
+import { quoteArg } from './shell-quote';
+
+export const IMPORT_UNRESOLVED = 'X_APP_IMPORT_UNRESOLVED';
+
+/** npm's own shape, so `@/lib/x` (a path alias) and `node:nope` are not offered to `bun add`. */
+const PACKAGE_NAME = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*/;
+
+/** `@scope/pkg/sub` → `@scope/pkg`, or `undefined` for what no install can resolve. */
+export const installablePackage = (specifier: string): string | undefined => {
+  const name = PACKAGE_NAME.exec(specifier)?.[0];
+  if (name === undefined) return undefined;
+  const rest = specifier.slice(name.length);
+  return rest === '' || rest.startsWith('/') ? name : undefined;
+};
+
+/** Is `pkg` in a `node_modules` the referrer resolves through, as the resolver walks: up to `/`. */
+const isInstalled = (pkg: string, referrer: string): boolean => {
+  for (let dir = dirname(referrer); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'node_modules', pkg, 'package.json'))) return true;
+    if (dirname(dir) === dir) return false;
+  }
+};
+
+/**
+ * Bun's `ResolveMessage`, read through `stringField`: a caught value this process did not build. The
+ * `specifier` and `referrer` are the failing import's own, however many modules were importing the
+ * file that holds it, which is what makes one finding per specifier true.
+ */
+export function unresolvedImportFinding(error: unknown, root: string): Finding | undefined {
+  if (stringField(error, 'code') !== 'ERR_MODULE_NOT_FOUND') return undefined;
+  const specifier = stringField(error, 'specifier');
+  if (specifier === undefined) return undefined;
+  const referrer = stringField(error, 'referrer');
+  const at = referrer === undefined ? undefined : posixRelative(root, referrer);
+  const where = at ?? 'an app module';
+  const named = installablePackage(specifier);
+  // Installed, and missing only the subpath: `bun add` would exit 0 and change nothing.
+  const installed = named !== undefined && referrer !== undefined && isInstalled(named, referrer);
+  const pkg = installed ? undefined : named;
+  const edit = `grep -nF -- ${quoteArg(specifier)} ${quoteArg(where)}   # the import no file resolves: edit it`;
+  return {
+    code: IMPORT_UNRESOLVED,
+    cause: installed
+      ? `${where} imports "${specifier}", and ${String(named)} is installed with no such subpath`
+      : pkg === undefined
+        ? `${where} imports "${specifier}", which resolves to no file`
+        : `an app module imports ${pkg}, which is not installed`,
+    fix: pkg === undefined ? edit : `bun add ${quoteArg(pkg)}`,
+    ...(at === undefined ? {} : { at }),
+    meta: { specifier },
+  };
+}

package/src/app-load.ts

@@ -29,6 +29,7 @@ import {
 // accident one refactor away from compiling every app's `.tsx` to `React.createElement`. The named
 // import is a value import, so the side effect holds without the bare line it replaced.
 import { setStylesheetRoot } from '@ultimat3/render/server';
+import { unresolvedImportFinding } from './app-load-unresolved';
 import {
   evictChanged,
   pinModule,
@@ -61,6 +62,13 @@ const APP_GLOBS = [
  */
 const ENTRY_POINT = /^apps\/[^/]+\/(?:server|prerender)\.tsx?$/;
 
+/**
+ * `apps/<app>/exercise.ts` is `x exercise`'s input, read by that command alone. It imports
+ * `@ultimat3/testing`, a devDependency a production image does not install, so the boot scan that
+ * imported it would fail the module on every start.
+ */
+const EXERCISE_FILE = /^apps\/[^/]+\/exercise\.ts$/;
+
 /**
  * A `*.island.tsx` is a CLIENT entry point and is deliberately not imported here. It registers no
  * primitive — a page names it by specifier, never by import — and importing it would put the one
@@ -138,13 +146,13 @@ export function sortModulePaths(paths: readonly string[]): string[] {
  * Every module path the app globs match, SORTED — with the API index first. `Bun.Glob` answers in
  * directory order, which is the filesystem's — ext4 hashes names with a per-filesystem seed — so
  * two pods of one image imported the app in two orders, registered its stylesheets in two orders,
- * and served two different `/styles/<hash>.css` for one page (notificado.co, 22.3.2). Import order
+ * and served two different `/styles/<hash>.css` for one page (one adopter, 22.3.2). Import order
  * is the stylesheet cascade's order, so it must be the same everywhere.
  *
  * The API index leads because `defineApi({ http: { pathStyle } })` is what every action URL is
  * derived under: sorted, `apps/admin/**` evaluated before it, and a module-level
  * `derivePath('signOut').path` there captured the default style's `/api/outs/sign` — a form
- * posting to a URL no route served (notificado.co, 22.6.0). Anything still evaluated before the
+ * posting to a URL no route served (one adopter, 22.6.0). Anything still evaluated before the
  * declaration (the index's own imports) is refused at it, `X_ACTION_PATH_DERIVED_EARLY`.
  */
 export async function appModulePaths(root: string): Promise<readonly string[]> {
@@ -211,32 +219,33 @@ export async function scanAppModules(root: string, options: ScanOptions): Promis
     // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
     const file = posixRelative(root, absolute);
     if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
-    if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
+    if (
+      ENTRY_POINT.test(file) ||
+      EXERCISE_FILE.test(file) ||
+      CLIENT_ENTRY_POINT.test(file) ||
+      STATES_FILE.test(file)
+    ) {
       continue;
     }
     if (options.include !== undefined && !(await options.include(absolute))) continue;
-    // The source is read BEFORE the import, on the file's first pass and for every route module —
-    // a rescan of any other registered module reads nothing here. What is recorded is bound to the
-    // bytes the module was evaluated from, and a read AFTER the import cannot know which bytes
-    // those were: a save landing between the two bound V1's component to V2's hash, so the next
-    // scan saw nothing to do and served V1 until the save after. Read first, the worst case is one
-    // re-import the next tick, of a file that did change. An untracked scan reads nothing here:
-    // no save lands in an image, so a route module's text is read after its import, once.
+    // The source is read BEFORE the import, on the file's first pass — a rescan of a registered
+    // module reads nothing here. What is recorded is bound to the bytes the module was evaluated
+    // from, and a read AFTER the import cannot know which bytes those were: a save landing between
+    // the two bound V1's component to V2's hash, so the next scan saw nothing to do and served V1
+    // until the save after. Read first, the worst case is one re-import the next tick, of a file
+    // that did change. An untracked scan reads nothing here: no save lands in an image.
     const first = !registered.has(absolute) && !failures.has(absolute);
-    const snapshot =
-      options.track && (first || routeModules.has(absolute))
-        ? await Bun.file(absolute).text()
-        : undefined;
+    const snapshot = options.track && first ? await Bun.file(absolute).text() : undefined;
     if (first && snapshot !== undefined) await trackModule(absolute, snapshot, root);
     let module: Record<string, unknown>;
     try {
       module = (await import(absolute)) as Record<string, unknown>;
     } catch (error) {
-      findings.push({ ...findingFrom(error), at: file });
+      findings.push(unresolvedImportFinding(error, root) ?? { ...findingFrom(error), at: file });
       continue;
     }
     files.push(file);
-    const finding = await register(absolute, file, module, snapshot, options.track);
+    const finding = await register(absolute, file, module, options.track);
     if (finding !== undefined) findings.push(finding);
   }
 
@@ -303,25 +312,22 @@ const emptyAppFinding = (root: string): Finding => ({
 /**
  * Registers a module once; every later call replays whatever the first one reported — except for
  * a route module, which a later call re-registers when the import handed back a new instance.
- * `snapshot` is the source read before this import: always for a first pass and a route module of
- * a TRACKED scan. An untracked one hands none, and a route module's text is read here instead.
  */
 async function register(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
-  snapshot: string | undefined,
   track: boolean,
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
-  if (registered.has(absolute)) return reloadRoute(absolute, file, module, snapshot);
+  if (registered.has(absolute)) return track ? reloadRoute(absolute, file, module) : undefined;
   registered.add(absolute);
   try {
     const config = module['config'];
     const route = isRouteConfig(config) ? config : undefined;
     if (route !== undefined) {
-      registerRouteModule(file, module, route, snapshot ?? (await Bun.file(absolute).text()));
+      registerRouteModule(file, module, route);
       routeModules.set(absolute, module);
     }
     // A pin is the reload graph's: it stops an eviction a process that never rescans never runs,
@@ -364,18 +370,11 @@ function definesPrimitive(module: Record<string, unknown>, route: boolean): bool
   });
 }
 
-/**
- * The route half of a registration, and the whole of a re-registration. `source` is the text the
- * module was imported from — read by the caller BEFORE the import, never here after it — and the
- * hash the entry is bound to is that text's. Until 2026-09-07 this read the file again, and a save
- * between the import and that read registered the old component under the new hash: the next
- * scan compared equal, and the page on disk was not served until the save after it.
- */
+/** The route half of a registration, and the whole of a re-registration. */
 function registerRouteModule(
   file: string,
   module: Record<string, unknown>,
   config: RouteConfig,
-  source: string,
 ): void {
   // The page component comes from the same module as its config, resolved by render's own
   // rule — the CLI does not decide which export is a page any more than it decides what a
@@ -384,9 +383,6 @@ function registerRouteModule(
   registerRoute({
     file,
     config,
-    // The build counts boundaries from the compiled JSX; before a build there is only the
-    // source, and `render: 'stream'` is rejected without one — so count them in the text.
-    suspenseBoundaries: countSuspense(source),
     ...(component === undefined ? {} : { component }),
   });
 }
@@ -401,16 +397,15 @@ function reloadRoute(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
-  source: string | undefined,
 ): Finding | undefined {
   const held = routeModules.get(absolute);
-  if (held === undefined || held === module || source === undefined) return undefined;
+  if (held === undefined || held === module) return undefined;
   try {
     const config = module['config'];
     // A file that stopped being a route is not un-registered — the table has no verb for it, and a
     // deleted file needs a restart either way. Its instance is recorded so the same save is not
     // re-registered on every later tick.
-    if (isRouteConfig(config)) registerRouteModule(file, module, config, source);
+    if (isRouteConfig(config)) registerRouteModule(file, module, config);
     routeModules.set(absolute, module);
     return undefined;
   } catch (error) {
@@ -418,8 +413,6 @@ function reloadRoute(
   }
 }
 
-const countSuspense = (source: string): number => source.match(/<Suspense[\s/>]/g)?.length ?? 0;
-
 /**
  * `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web` — on
  * either separator. A manifest written on Windows split a `\`-path on `/`, kept the whole file as

package/src/app-mcp.ts

@@ -13,12 +13,14 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
-import { jsonResponse, selfOrigin } from '@ultimat3/http';
+import { jsonResponse, originListed, selfOrigin } from '@ultimat3/http';
 import {
   type AppMcp,
+  assertRecipeLinks,
   McpAppUnmountedError,
   McpPathDuplicateError,
   PROTECTED_RESOURCE_WELL_KNOWN,
+  servedRecipes,
 } from '@ultimat3/mcp';
 import { loadAppConfig } from './app-config-load';
 
@@ -103,6 +105,9 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
     const module = (await import(join(root, file))) as Record<string, unknown>;
     const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
     if (endpoints === undefined) continue;
+    // Every endpoint is built by now: an error's declared `docs://recipes/` link must name a recipe
+    // one of them serves (`X_MCP_RECIPE_UNKNOWN`), the union and never one endpoint alone.
+    assertRecipeLinks(servedRecipes());
     return mountEndpoints(endpoints, file);
   }
   return {
@@ -199,8 +204,15 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
         route.handle(request.raw, {
           origin: selfOrigin(ctx.url, ctx.https),
           address: ctx.ip ?? undefined,
+          // A browser `Origin` is proven the way CSRF proves it: this origin, or one listed exactly.
+          listed: (origin) => originListed(ctx.config.cors, origin),
         }),
-      meta: { name, auth: 'public', enforcedBy: 'handler' },
+      // `authenticate` answers nobody: the route's ONE credential is the bearer `resolveToken`
+      // reads, so a session cookie authenticates nothing here. Without it the app's authenticator
+      // made a cookie-carrying (or, under `x dev`, any) request a user's, and CSRF then refused a
+      // token-less MCP client 403 where it is owed the 401 and its challenge. No cookie identifies
+      // anyone, so there is no ambient credential for a forged request to ride.
+      meta: { name, auth: 'public', enforcedBy: 'handler', authenticate: () => null },
     },
     ...metadata,
   ];