@ultimat3/cli 22.2.1 → 22.3.0

package/src/templates/scaffold-entries.ts

@@ -65,9 +65,7 @@ const prerender =
 // landed on disk — which is what \`x build --target static --json\` reads back.
 
 import { join } from 'node:path';
-import { DEFAULT_ORIGIN, type PrerenderReport, prerenderSite } from '@ultimat3/cli';
-import { routeEntries } from '@ultimat3/render';
-import { buildRobots, buildSitemap, type RouteRecord } from '@ultimat3/seo';
+import { loadSiteSettings, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
 
 const root = join(import.meta.dir, '..', '..');
 const flag = Bun.argv.indexOf('--out');
@@ -79,47 +77,35 @@ const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', '
 const origin = Bun.env.SITE_ORIGIN;
 
 /**
- * The route table as \`@ultimat3/seo\` reads it. \`RouteRecord\` is a static row and \`defineRoute\`
- * is a live declaration, so one has to be projected onto the other — and \`prerenderSite\` has
- * already loaded the app by the time this runs, which is what fills \`routeEntries()\`.
+ * \`sitemap.xml\` and \`robots.txt\`, into the same directory the HTML went: a static export is
+ * served with no process behind it, so the CDN needs the files. \`siteSeo\` is the same answer a
+ * running web role serves at \`/sitemap.xml\` and \`/robots.txt\` — the public \`site/\` routes, a
+ * page whose \`meta\` says \`robots: { index: false }\` left out — so a crawler reads one sitemap
+ * from the CDN and from the container.
  *
- * A DYNAMIC route contributes exactly the URLs this build enumerated for it, read back off the
- * report rather than by calling \`prerender()\` a second time: the sitemap then cannot name a page
- * the artifact does not contain, which is the only failure mode a sitemap really has.
- */
-const siteRoutes = (report: PrerenderReport): readonly RouteRecord[] =>
-  routeEntries()
-    .filter((entry) => entry.surface === 'site')
-    .map((entry) => ({
-      path: entry.path,
-      file: entry.file,
-      surface: 'site' as const,
-      render: entry.config.render,
-      prerender: () =>
-        report.pages.filter((page) => page.route === entry.path).map((page) => page.path),
-    }));
-
-/**
- * \`sitemap.xml\` and \`robots.txt\`, into the same directory the HTML went. Both belong to the
- * ARTIFACT rather than to a request: a static export is served with no process behind it, so a
- * route that answered them at run time would be a file the CDN never has.
+ * A DYNAMIC route contributes exactly the URLs this build emitted for it, read back off the report
+ * rather than by calling \`prerender()\` a second time: the sitemap then cannot name a page the
+ * artifact does not contain.
  *
- * \`buildRobots\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
+ * \`robots.txt\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
  * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
  */
-async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<readonly string[]> {
-  const sitemap = await buildSitemap(siteRoutes(report), { baseUrl });
-  // Past 50,000 URLs \`files\` are \`/sitemap-N.xml\` and the index is \`/sitemap.xml\`; below it,
-  // \`files\` is that one file and there is no index. Writing both lists covers each case once.
-  const written = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
-  for (const file of written) await Bun.write(join(out, file.path), file.xml);
-  await Bun.write(join(out, 'robots.txt'), buildRobots({ baseUrl, sitemaps: ['/sitemap.xml'] }));
-  return [...written.map((file) => file.path), '/robots.txt'];
+async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]> {
+  const seo = await siteSeo({
+    // The origin the pages were built against, so the sitemap and every canonical agree.
+    baseUrl: report.origin,
+    disallow: (await loadSiteSettings(root)).disallow,
+    pagesFor: (route) =>
+      report.pages.filter((page) => page.route === route).map((page) => page.path),
+  });
+  for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
+  await Bun.write(join(out, 'robots.txt'), seo.robots);
+  return [...seo.sitemaps.map((file) => file.path), '/robots.txt'];
 }
 
 if (import.meta.main) {
   const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
-  const seo = await writeSeoFiles(report, origin ?? DEFAULT_ORIGIN);
+  const seo = await writeSeoFiles(report);
   await Bun.stdout.write(
     \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report, seo })}\\n\`,
   );

package/src/test-select.ts

@@ -5,7 +5,7 @@
 import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
-import { nearestName } from '@ultimat3/core';
+import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
@@ -45,17 +45,21 @@ const IGNORED = ['/dist/', '/build/', '/node_modules/', '/examples/', '/dummy/']
  * File size stands in for duration: cheap to read, and it correlates far better than file count.
  * `type`, when given, narrows to exactly the files verify-tests.ts would run for that suite — one
  * owner per path, decided by `ownerOf` there and never a second time here.
+ *
+ * `filter` is one substring or several: a path is kept when it contains ANY of them, so an app's
+ * scoped runner hands `x test` every affected slice at once instead of one process per slice.
  */
 export async function discoverTests(
   root: string,
-  filter?: string,
+  filter?: string | readonly string[],
   type?: TestType,
 ): Promise<readonly TestFile[]> {
+  const filters = filter === undefined ? undefined : typeof filter === 'string' ? [filter] : filter;
   const files: TestFile[] = [];
   for await (const found of new Bun.Glob(TEST_GLOB).scan({ cwd: root, absolute: false })) {
     const path = found.split('\\').join('/');
     if (IGNORED.some((part) => `/${path}`.includes(part))) continue;
-    if (filter !== undefined && !path.includes(filter)) continue;
+    if (filters !== undefined && !filters.some((part) => path.includes(part))) continue;
     if (type !== undefined && !belongsToType(path, type)) continue;
     files.push({ path, bytes: Bun.file(join(root, path)).size });
   }
@@ -134,6 +138,29 @@ export function readSample(args: ParsedArgs): number | undefined {
   return value;
 }
 
+/**
+ * `--filter`'s value as the list `discoverTests` matches: comma-separated, each item trimmed. An
+ * empty item is refused rather than dropped — `''` is a substring of every path, so `a,,b` would
+ * quietly widen a narrowed run back to the whole suite.
+ */
+export function readFilters(raw: string | undefined): readonly string[] | undefined {
+  if (raw === undefined) return undefined;
+  const items = raw.split(',').map((item) => item.trim());
+  if (items.some((item) => item === '')) {
+    const kept = items.filter((item) => item !== '');
+    throw new BadFlagError({
+      flag: 'filter',
+      command: 'test',
+      reason: `"${raw}" holds an empty path, and an empty substring matches every test file`,
+      fix:
+        kept.length === 0
+          ? 'x test --json'
+          : `x test --filter ${renderFixShellArg(kept.join(','), '<path,path>')}`,
+    });
+  }
+  return items;
+}
+
 /** The selection, as `NoTestFilesError` wants it: only the parts the caller actually asked for. */
 export function missingSelection(
   type: TestType | undefined,

package/src/test-workers.ts

@@ -3,8 +3,9 @@
 // suite two different ways, and the `--worker N` reproduction a shard failure prints would then
 // name a shard the gate never ran.
 
-// Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
-import { cpus } from 'node:os';
+// Bun ships no CPU-count or free-memory primitive: `cpus()` is the fallback when navigator cannot
+// answer, and `freemem()` is the only reader of available memory.
+import { cpus, freemem } from 'node:os';
 import type { TestType } from '@ultimat3/testing';
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
@@ -14,7 +15,7 @@ export function availableCpus(): number {
 }
 
 /**
- * Deliberately MORE workers than cores, with a ceiling.
+ * Deliberately MORE workers than cores, bounded by memory rather than by a fixed count.
  *
  * `cpus - 1` is the intuitive default and it was measured to be worthless exactly where it has to
  * pay off. On a 4-core `ubuntu-latest` — the runner this repo commits to — the `unit` step:
@@ -32,23 +33,62 @@ export function availableCpus(): number {
  * resolution, on `--isolate` rebuilding a registry per file, and on waiting for its database.
  * Oversubscribing fills those stalls.
  *
- * The ceiling is memory, not cores. A worker is a whole Bun process with the framework's module
- * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite, so
- * width costs hundreds of MB per step. It binds on a developer's 12- or 32-core machine, which is
- * exactly where an unbounded count would swap.
+ * The bound is memory, not cores. A worker is a whole Bun process with the framework's module
+ * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite. Until
+ * 22.3 that was a FIXED ceiling of 8, which held a 12-core box to 8 workers with 30 GB free: the
+ * notificado.co `unit` step (381 files) sat at 51s on 8 workers against a 90s gate budget. The
+ * ceiling is now what the machine can actually hold — `os.freemem()` (MemAvailable on Linux, so
+ * reclaimable page cache counts as free) divided by `WORKER_BYTES` — which still binds on a small
+ * CI runner and on a loaded laptop, the two places an unbounded count would swap.
  *
  * The floor of 2 keeps a 1-core box sharding rather than silently reverting to serial.
  */
-export const WORKER_CEILING = 8;
-
-/** Oversubscription factor. See the table above — it is measured, not chosen for roundness. */
 export const WORKER_OVERSUBSCRIBE = 1.5;
 
 /** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
 export const WORKER_FLOOR = 2;
 
-export const defaultWorkers = (available: number = availableCpus()): number =>
-  Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
+/**
+ * What one test worker is budgeted at, for the memory bound above. MEASURED — peak RSS of the whole
+ * `x test unit` process tree on the notificado.co corpus (381 files, PGlite per worker), 12-core
+ * box, `As of 2026-09-25`:
+ *
+ *   | workers | peak tree RSS |
+ *   |---------|---------------|
+ *   | 8       | 20.7 GB       |
+ *   | 12      | 22.5 GB       |
+ *   | 16      | 24.3 GB       |
+ *
+ * The MARGINAL worker costs ~0.45 GB (the slope); the ~17 GB intercept is the corpus itself —
+ * every file's module graph and database, retained per worker — and does not shrink with fewer
+ * workers, so it is not this bound's to budget. The constant is the slope doubled and rounded to a
+ * power of two, because free memory is read once, before a single worker has started.
+ */
+export const WORKER_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * The most `--workers` accepts, on either command. Not a default and not a memory rule — a sanity
+ * bound: without one `--workers 5000` parsed, the run clamped only to the file count, and it
+ * started one Bun process per test FILE. An explicit width below it is the caller's call.
+ */
+export const WORKER_CEILING = 64;
+
+/** Bun ships no memory primitive; `freemem()` is libuv's MemAvailable on Linux. */
+export const availableMemory = (): number => freemem();
+
+/**
+ * `ceil(cpus x 1.5)`, held to what free memory can carry and never below the floor. The file-count
+ * clamp is `test-passes.ts`'s (every pass is clamped to its own file list), because only the
+ * caller knows the selection.
+ */
+export const defaultWorkers = (
+  available: number = availableCpus(),
+  freeBytes: number = availableMemory(),
+): number => {
+  const byCpu = Math.ceil(available * WORKER_OVERSUBSCRIBE);
+  const byMemory = Math.floor(freeBytes / WORKER_BYTES);
+  return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
+};
 
 /**
  * Which types run across worker processes, and why the other two cannot.

package/src/verify-run.ts

@@ -17,16 +17,18 @@ import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
  * Run every step, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
  *
- * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
- * so that every caller of the runner — the command, `x build`, the MCP host — gets the banner and
- * the `--json` flag with it, instead of one of them filtering a list quietly.
+ * `ctx.only` narrows the list to the steps it names, kept in declared order. The narrowing lives
+ * HERE rather than in `cmd-verify.ts` so that every caller of the runner — the command, `x build`,
+ * the MCP host — gets the banner and the `--json` flag with it, instead of one of them filtering a
+ * list quietly.
  */
 export async function runVerify(
   steps: readonly VerifyStep[],
   ctx: VerifyContext,
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
-  const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  const only = onlyList(ctx.only);
+  const selected = only === undefined ? steps : steps.filter((step) => only.includes(step.name));
   const byName = new Map<string, StepResult>();
   const began = performance.now();
   // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
@@ -75,7 +77,7 @@ export async function runVerify(
     // Rendered through the catalog like every other summary this file emits; the machine marker
     // is `data.notAGateRun` below. It was a bare `NOT A GATE RUN` constant, which put one
     // user-facing string outside `messages.ts` for a fact `--json` was already carrying twice.
-    summary: ctx.only === undefined ? summary : msg('cli.verify.notAGateRun', { summary }),
+    summary: only === undefined ? summary : msg('cli.verify.notAGateRun', { summary }),
     steps: results,
     // `skipped` is a list beside `failed` and not a count, because the two answer the same kind of
     // question — *which* steps, not how many — and a caller ratcheting on coverage needs the names.
@@ -85,13 +87,18 @@ export async function runVerify(
       durationMs: totalMs,
       // A BOOLEAN beside the banner, so a reader of `--json` never has to substring-match a
       // summary line to learn that this run checked one thing.
-      ...(ctx.only === undefined ? {} : { notAGateRun: true, only: ctx.only }),
+      // `only` is always the LIST, in declared order — one name is a list of one.
+      ...(only === undefined ? {} : { notAGateRun: true, only: [...only] }),
     },
     // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
   };
 }
 
+/** One name or several, as one list — the context accepts both, every reader here wants a list. */
+const onlyList = (only: VerifyContext['only']): readonly string[] | undefined =>
+  only === undefined ? undefined : typeof only === 'string' ? [only] : only;
+
 /**
  * What the counts are allowed to claim. A step that does not apply is recorded green so the run
  * continues, and the summary counted it among the "all 17 steps passed" — so a repo whose `job`

package/src/verify-step.ts

@@ -79,15 +79,18 @@ export interface VerifyContext {
    */
   readonly workers?: number;
   /**
-   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. The
+   * Some steps, by name — an iteration loop, and the one thing here that IS a narrowing. The
    * whole gate costs minutes (3m19s at the framework root on 12 cores, `As of 2026-09-23`), which
-   * is the cost of asking a question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
-   * mechanical rather than remembered: a run with this set prints `NOT A GATE RUN` in the summary
-   * AND carries `notAGateRun` in `--json` (`verify-run.ts`), so no reader of either can mistake it
-   * for the gate; and nothing writes `x.verify.json`, so the suite floor cannot be lowered by a
-   * run that never executed the suites. Green still means the no-flag run, unchanged.
+   * is the cost of asking a question about one step. A list (`x verify --only typecheck,lint`) runs
+   * in ONE process, so an app's scoped runner stops paying a CLI boot and an app load per step.
+   * It does not weaken axiom 5, and the two rules that keep it honest are mechanical rather than
+   * remembered: a run with this set prints `NOT A GATE RUN` in the summary AND carries `notAGateRun`
+   * in `--json` (`verify-run.ts`), so no reader of either can mistake it for the gate; and nothing
+   * writes `x.verify.json`, so the suite floor cannot be lowered by a run that never executed the
+   * suites — even a list naming every step. Green still means the no-flag run, unchanged. A single
+   * name is accepted for the callers that narrow to one (`scripts/verify.ts`).
    */
-  readonly only?: VerifyStepName;
+  readonly only?: VerifyStepName | readonly VerifyStepName[];
 }
 
 export interface StepOutcome {