@ultimat3/cli 29.4.0 → 30.1.0

package/src/verify-skip-ceiling.ts

@@ -0,0 +1,87 @@
+// `skipCeiling` in `x.verify.json`: how many tests a step may skip before the gate stops calling it
+// a run. The floor refuses a step that ran NOTHING; a step that ran 8 of 17 behind
+// `skipIf(!process.env.TYPO)` was green. Judged where the verdict is (CI, and `x verify merge`),
+// never on a laptop without services, which stays a dev loop.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import type { Finding } from './output';
+import type { TestCounts } from './test-counts';
+
+/** The floor's skip-ceiling key. Named once: the problem quotes it and the fix repairs it. */
+export const SKIP_CEILING_FIELD = 'skipCeiling';
+
+/** Step name → the most tests it may skip. */
+export type SkipCeiling = Readonly<Record<string, number>>;
+
+/** `{ "<step>": n }`, a whole number at or above zero per step the gate runs, or the problems. */
+export function readSkipCeiling(
+  payload: Record<string, unknown> | undefined,
+  declared: readonly string[],
+): { ceiling?: SkipCeiling; problems: readonly string[] } {
+  const raw = payload?.[SKIP_CEILING_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { problems: [`"${SKIP_CEILING_FIELD}" is not an object of { "<step>": tests }`] };
+  }
+  const problems: string[] = [];
+  const ceiling = new Map<string, number>();
+  for (const [step, n] of Object.entries(raw)) {
+    if (!declared.includes(step)) {
+      problems.push(`"${SKIP_CEILING_FIELD}" names ${step}, which x verify does not run`);
+    } else if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0) {
+      problems.push(
+        `"${SKIP_CEILING_FIELD}" gives ${step} ${JSON.stringify(n)}, which is not a whole number of tests`,
+      );
+    } else ceiling.set(step, n);
+  }
+  return {
+    ...(ceiling.size === 0 ? {} : { ceiling: Object.fromEntries(ceiling) }),
+    problems,
+  };
+}
+
+/** `CI` as GitHub, GitLab and most runners set it; `false`/`0`/empty is a laptop that said so. */
+export const inCi = (env: Readonly<Record<string, string | undefined>>): boolean => {
+  const value = env['CI'];
+  return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+};
+
+const ceilingOf = (ceiling: SkipCeiling | undefined, step: string): number | undefined =>
+  ceiling !== undefined && Object.hasOwn(ceiling, step) ? ceiling[step] : undefined;
+
+/**
+ * The verdict on one step's counts — the whole run's, or the merged shards'. Over the ceiling is a
+ * finding; under it nothing; no ceiling and something skipped is a WARNING naming the number to
+ * write, since a new app holds nothing yet and a gate must not invent the bar.
+ */
+export function judgeSkips(
+  step: string,
+  tests: TestCounts | undefined,
+  ceiling: SkipCeiling | undefined,
+): { readonly findings: readonly Finding[]; readonly warnings: readonly string[] } {
+  if (tests === undefined || tests.ran === 0) return { findings: [], warnings: [] };
+  const allowed = ceilingOf(ceiling, step);
+  if (allowed === undefined) {
+    return tests.skipped === 0
+      ? { findings: [], warnings: [] }
+      : {
+          findings: [],
+          warnings: [
+            `${step} skipped ${String(tests.skipped)} of ${String(tests.ran + tests.skipped)} test(s): hold it with "${SKIP_CEILING_FIELD}": { "${step}": ${String(tests.skipped)} } in x.verify.json`,
+          ],
+        };
+  }
+  if (tests.skipped <= allowed) return { findings: [], warnings: [] };
+  return {
+    findings: [
+      {
+        code: 'X_VERIFY_SKIPS_OVER_CEILING',
+        cause: `the ${step} step skipped ${String(tests.skipped)} test(s) and ran ${String(tests.ran)}; x.verify.json "${SKIP_CEILING_FIELD}" allows ${String(allowed)}`,
+        fix: `x test ${renderFixShellArg(step, '<step>')} --json   # then set what the skipped tests need, or raise "${SKIP_CEILING_FIELD}" for ${step} in x.verify.json with the reason in the diff`,
+        docs: ERROR_DOCS_URL,
+        at: 'x.verify.json',
+      },
+    ],
+    warnings: [],
+  };
+}

package/src/verify-step.ts

@@ -27,6 +27,11 @@ export const VERIFY_STEP_NAMES = [
   'contract',
   'live',
   'job',
+  // Its own step, not a rider on `job` or `contract`: those ask whether the tests someone WROTE
+  // pass, and this asks what every primitive does when it actually runs with no test written — a
+  // different question with a different fix (an override in `apps/web/exercise.ts`). After `job`,
+  // the last suite it can stand beside without a browser; before `e2e`, the costliest.
+  'exercise',
   'e2e',
   'eval',
   'drift',

package/src/verify-tests.ts

@@ -185,7 +185,8 @@ export const testStepCommand = (type: TestType, pace?: MachinePace): readonly st
  * "no test files matched", a red gate reporting a suite that by its own rule is not here.
  *
  * Memoized because `runVerify` asks `applies` and then `run`, and a repeated walk of the whole
- * tree per type is the cost this change exists to remove.
+ * tree per type is the cost this change exists to remove. For one run only: `runVerify` clears it
+ * first, since the dev MCP host's `verify` tool runs the gate again in the same process.
  */
 const discovered = new Map<string, readonly TestFile[]>();
 
@@ -198,11 +199,27 @@ const filesFor = async (root: string, type: TestType): Promise<readonly TestFile
   return files;
 };
 
-/** Test seam: a fixture that writes new test files under a root this process already scanned. */
+/** `runVerify` starts every run here; a test that calls a step outside `runVerify` does too. */
 export const resetTestDiscovery = (): void => discovered.clear();
 
-const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
-  const command = testStepCommand(type, ctx.pace);
+/**
+ * `files`, when given, is a `--shard` slice: the same one process and the same per-test deadline,
+ * over an explicit list instead of the type's own globs — `runParallel` hands `bun test` its files
+ * the same way. Serial is a fact about ONE machine (one replication slot, one browser); each CI
+ * runner starts its own services, so a slice per runner shares nothing with another runner's.
+ */
+const runSerial = async (
+  ctx: VerifyContext,
+  type: TestType,
+  files?: readonly string[],
+): Promise<StepOutcome> => {
+  const whole = testStepCommand(type, ctx.pace);
+  const command =
+    files === undefined
+      ? whole
+      : // Its flags kept — the deadline and the ignore list — and its type filters replaced by
+        // the slice: `bun test` reads a positional as a path filter either way.
+        [...whole.filter((arg, at) => at < 2 || arg.startsWith('--')), ...[...files].sort()];
   const envOverrides = { ...testEnvOverrides(ctx.root, ctx.env ?? Bun.env), ...paceEnv(ctx.pace) };
   const exec = (e2e: { command: readonly string[]; env: typeof envOverrides }) =>
     ctx.runner(e2e.command, {
@@ -229,7 +246,7 @@ const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcom
 };
 
 const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
-  if (isSerial(type)) return runSerial(ctx, type);
+  if (isSerial(type) && ctx.shard === undefined) return runSerial(ctx, type);
   const discoveredFiles = await filesFor(ctx.root, type);
   // Under `--shard`, this job runs its slice and says which — `x verify merge` checks the slices.
   // An EMPTY slice is a pass with zero tests, never the serial fallback below (which would run
@@ -245,6 +262,9 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
   if (shard !== undefined && shard.files.length === 0) {
     return { ok: true, findings: [], workers: 0, tests: { ran: 0, skipped: 0 }, shard };
   }
+  if (isSerial(type) && shard !== undefined) {
+    return { ...(await runSerial(ctx, type, shard.files)), shard };
+  }
   const files =
     shard === undefined
       ? discoveredFiles

package/src/view-drift.ts

@@ -0,0 +1,55 @@
+// Single responsibility: `X_ENTITY_VIEW_DRIFT` — a view entity's declared `columns` against the
+// output columns of the view the migrations created. Only a database can say what a query
+// outputs, so this reads the `drift` step's scratch replay (`schema-dump-drift.ts`), never source.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { EntityDescriptionLike } from '@ultimat3/db';
+import type { CatalogDescription } from '@ultimat3/db/schema-dump';
+import { MIGRATIONS_DIR } from './migrations';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+const named = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(', ');
+
+/**
+ * One finding per view, naming both directions: a declared column the view does not output is a
+ * `42703` on every read; an output no column names is data the entity can never reach. A view the
+ * replay did not create is `X_DB_SCHEMA_UNMIGRATED`'s (`schema-diff-views.ts`), and a catalog that
+ * carries no columns — one built by hand — states nothing to hold the entity to.
+ */
+export function viewColumnFindings(
+  entities: readonly EntityDescriptionLike[],
+  catalog: CatalogDescription,
+): readonly Finding[] {
+  const created = new Map(catalog.views.map((view) => [view.name, view.columns]));
+  return entities.flatMap((entity): readonly Finding[] => {
+    if (entity.view === undefined) return [];
+    const output = created.get(entity.table);
+    if (output === undefined) return [];
+    const declared = entity.columns.map((column) => column.column);
+    const unproduced = declared.filter((name) => !output.includes(name));
+    const unnamed = output.filter((name) => !declared.includes(name));
+    if (unproduced.length === 0 && unnamed.length === 0) return [];
+    const said = [
+      ...(unproduced.length === 0
+        ? []
+        : [
+            `view entity ${entity.name} declares ${named(unproduced)}, which view "${entity.table}" does not output`,
+          ]),
+      ...(unnamed.length === 0
+        ? []
+        : [
+            `view "${entity.table}" outputs ${named(unnamed)}, which no column of view entity ${entity.name} names`,
+          ]),
+    ].join('; ');
+    return [
+      {
+        code: 'X_ENTITY_VIEW_DRIFT',
+        cause: `${said} — its columns are ${output.join(', ')}`,
+        fix: `x entities show ${quoteArg(entity.name)} --json   # then make columns name exactly the view's output, or change view.sql, and run x db gen "record ${entity.table}"`,
+        docs: ERROR_DOCS_URL,
+        at: MIGRATIONS_DIR,
+      },
+    ];
+  });
+}

package/src/worker-bundle.ts

@@ -7,7 +7,7 @@
 // why: Bun ships no path API; the entry is resolved to a file and named in the cause.
 import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE, textResponse } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
 import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
@@ -224,7 +224,8 @@ function scriptRoute(
         return applyCacheHeaders(missing, NO_STORE);
       }
       return applyCacheHeaders(
-        new Response(script.code, { headers: { 'content-type': 'text/javascript' } }),
+        // `textResponse` for the length it declares: `compress` reads nothing undeclared.
+        textResponse(script.code, { headers: { 'content-type': 'text/javascript' } }),
         { mode: 'immutable' },
       );
     },

package/src/workspace-graph.ts

@@ -67,6 +67,31 @@ export function workspaceGlobs(manifest: unknown): readonly string[] {
   return Array.isArray(field) ? stringsOf(field) : stringsOf(asRecord(field)?.['packages']);
 }
 
+/**
+ * The one walker over `workspaces`: every manifest the globs claim, root-relative, POSIX and sorted,
+ * never a vendored one. A `!` entry subtracts, as npm reads it. Handed to `Bun.Glob` it is a glob of
+ * its own, matching every file in the tree that is not that manifest.
+ */
+export async function workspaceManifestPaths(
+  root: string,
+  globs: readonly string[],
+): Promise<readonly string[]> {
+  const excluded = globs
+    .filter((glob) => glob.startsWith('!'))
+    .map((glob) => new Bun.Glob(glob.slice(1).replace(/\/+$/, '')));
+  const found = new Set<string>();
+  for (const glob of globs.filter((candidate) => !candidate.startsWith('!'))) {
+    const manifests = new Bun.Glob(`${glob.replace(/\/+$/, '')}/package.json`);
+    for await (const path of manifests.scan({ cwd: root, absolute: false })) {
+      const manifest = path.replaceAll('\\', '/');
+      const dir = manifest.slice(0, -'/package.json'.length);
+      if (isVendored(manifest) || excluded.some((negated) => negated.match(dir))) continue;
+      found.add(manifest);
+    }
+  }
+  return [...found].sort();
+}
+
 const declaredDepsOf = (manifest: Record<string, unknown>): readonly string[] =>
   DEPENDENCY_FIELDS.flatMap((field) => Object.keys(asRecord(manifest[field]) ?? {}));
 
@@ -89,26 +114,20 @@ export async function scanWorkspaces(root: string): Promise<WorkspaceScan> {
   const rootManifest = await readManifest(join(root, 'package.json'));
   const found: { dir: string; name: string; version: string; declared: readonly string[] }[] = [];
   const unreadable: string[] = [];
-  for (const pattern of workspaceGlobs(rootManifest)) {
-    for await (const relative of new Bun.Glob(`${pattern}/package.json`).scan({
-      cwd: root,
-      absolute: false,
-    })) {
-      if (isVendored(relative)) continue;
-      const manifest = await readManifest(join(root, relative));
-      const name = manifest?.['name'];
-      if (manifest === undefined || typeof name !== 'string' || name === '') {
-        unreadable.push(relative.replaceAll('\\', '/'));
-        continue;
-      }
-      const version = manifest['version'];
-      found.push({
-        dir: relative.replaceAll('\\', '/').slice(0, -'/package.json'.length),
-        name,
-        version: typeof version === 'string' ? version : '0.0.0',
-        declared: declaredDepsOf(manifest),
-      });
+  for (const relative of await workspaceManifestPaths(root, workspaceGlobs(rootManifest))) {
+    const manifest = await readManifest(join(root, relative));
+    const name = manifest?.['name'];
+    if (manifest === undefined || typeof name !== 'string' || name === '') {
+      unreadable.push(relative);
+      continue;
     }
+    const version = manifest['version'];
+    found.push({
+      dir: relative.slice(0, -'/package.json'.length),
+      name,
+      version: typeof version === 'string' ? version : '0.0.0',
+      declared: declaredDepsOf(manifest),
+    });
   }
   found.sort((left, right) => left.dir.localeCompare(right.dir));
   const names = new Set<string>();

package/src/write-generated.ts

@@ -0,0 +1,43 @@
+// Write one planned file to disk: bytes through `Bun.write`, a `link` entry as a relative symlink.
+// The copy fallback is Windows-only, where creating a symlink needs Developer Mode or an elevated
+// token and `symlink` fails with EPERM; anywhere else a failed link is a real error and surfaces.
+
+// why: Bun ships no symlink or mkdir API, nor a path API to find the link's parent directory.
+import { mkdir, rm, symlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { stringField } from '@ultimat3/core';
+import type { GeneratedFile } from './templates';
+
+/** The OS refusing the privilege, not the call being wrong: only these fall back to a copy. */
+const PRIVILEGE_CODES: ReadonlySet<string> = new Set(['EPERM', 'EACCES', 'ENOTSUP', 'ENOSYS']);
+
+export interface WriteGeneratedSeams {
+  readonly link?: (target: string, path: string) => Promise<void>;
+  readonly platform?: NodeJS.Platform;
+}
+
+/** `'link'` when a symlink landed, `'copy'` when Windows refused one and the text was written. */
+export async function writeGenerated(
+  root: string,
+  file: GeneratedFile,
+  seams: WriteGeneratedSeams = {},
+): Promise<'file' | 'link' | 'copy'> {
+  const path = join(root, file.path);
+  if (file.merge !== undefined || file.link === undefined) {
+    await Bun.write(path, file.contents);
+    return 'file';
+  }
+  // `'file'`: Windows cannot infer the kind of a target written after its link.
+  const link = seams.link ?? ((target: string, at: string) => symlink(target, at, 'file'));
+  await mkdir(dirname(path), { recursive: true });
+  await rm(path, { force: true });
+  try {
+    await link(file.link, path);
+    return 'link';
+  } catch (error) {
+    const windows = (seams.platform ?? process.platform) === 'win32';
+    if (!windows || !PRIVILEGE_CODES.has(stringField(error, 'code') ?? '')) throw error;
+    await Bun.write(path, file.contents);
+    return 'copy';
+  }
+}

package/src/zone-boot.ts

@@ -0,0 +1,20 @@
+// `time.detect`'s boot fact: the zone script's tag and the CSP source that admits exactly it, or
+// nothing for an app that left detection off. Composed into `app/` documents only, by the one
+// head both boots spread (`clientScriptHeads`), so `site/` never pays for it (axiom 6).
+
+import type { AppTimeConfig } from '@ultimat3/core';
+import { cspHashSource } from '@ultimat3/http';
+import { renderHead, zoneScript, zoneScriptBody } from '@ultimat3/render';
+
+export interface ZoneBoot {
+  /** The rendered `<script>`, for the `app/` document head. */
+  readonly head: string;
+  /** The `script-src` source that admits exactly that tag's body. */
+  readonly cspSource: string;
+}
+
+/** Tag and hash from ONE body, as `themeBoot` does. `undefined` unless the app said `detect`. */
+export function zoneBoot(time: AppTimeConfig | undefined): ZoneBoot | undefined {
+  if (time?.detect !== true) return undefined;
+  return { head: renderHead([zoneScript()]), cspSource: cspHashSource(zoneScriptBody()) };
+}