@ultimat3/cli 20.2.1 → 22.0.0

package/src/templates/scaffold-repo.ts

@@ -64,9 +64,9 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "dev": "x dev",
     "check": "bin/check",
     "verify": "x verify",
-    "typecheck": "tsc -b --pretty",
+    "typecheck": "tsc -p . --pretty",
     "lint": "biome check .",
-    "test": "bun test",
+    "test": "bun test --isolate",
     "db:migrate": "x db migrate",
     "db:seed": "x db seed"
   },
@@ -89,6 +89,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/i18n": "^${version}",
     "@ultimat3/jobs": "^${version}",
     "@ultimat3/mcp": "^${version}",
+    "@ultimat3/money": "^${version}",
     "@ultimat3/policy": "^${version}",
     "@ultimat3/pwa": "^${version}",
     "@ultimat3/query": "^${version}",
@@ -106,14 +107,16 @@ const rootPackage = (app: NameSet, version: string): string => `{
 
 /**
  * `"incremental": true` is ONE line and it is the difference between a 4.9s typecheck and a 92s
- * one. `x verify`'s first step is `tsc -b`, and `-b` decides "up to date?" by comparing emitted
- * OUTPUTS against inputs — with `noEmit` and no `composite`/`references`, the output it looks for
- * is an `app.config.js` that will never exist (`Project 'tsconfig.json' is out of date because
- * output file 'app.config.js' does not exist`), so every run rebuilt the whole program from
- * scratch, forever. Measured on a 166-file scaffold with no source change between runs: 92s wall
- * / 43s user CPU without it, 4.9s / 8.8s warm with it, and the whole gate at 12s rather than
- * 24-71s. This was the only tree in the framework without incremental typechecking — the repo
- * root has 32 `references` and `examples/dummy/tsconfig.json` sets `composite`.
+ * one. Measured on a 166-file scaffold with no source change between runs: 92s wall / 43s user CPU
+ * without it, 4.9s / 8.8s warm with it.
+ *
+ * The typecheck is `tsc -p .`, never `-b`, `As of 2026-09-23` (#450) — here, in the scaffold's
+ * `typecheck` script, and in `x verify`'s step (`verify-typecheck.ts`, for any root without
+ * `references`). `-b` decides "up to date?" by MTIME, and Bun installs a dependency as hardlinks
+ * carrying its cache's old mtimes: upgrading to a version already in the cache left every input
+ * older than the buildinfo, so `-b` skipped the program and reported green while a cold CI was
+ * red. `-p` with `incremental` compares content hashes. `-b` also wanted an emitted
+ * `app.config.js` that `noEmit` never writes, which is why this line was first needed.
  *
  * The note lives HERE and not in the emitted file, for the reason `biome.json` below gives: an
  * app author has no use for eight lines of framework archaeology in their own tsconfig, and

package/src/templates/scaffold-roles.ts

@@ -4,9 +4,23 @@
 // many answers as the app has folders, and the framework's two tracked apps already disagree.
 
 import type { GeneratedFile } from './naming';
+import { wrapList } from './wrap';
 
-const rolesSource =
-  (): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
+/**
+ * A role's grants as Biome prints them. The example slice's \`post:read\`/\`post:write\` ride along
+ * with it: \`x g resource post\` would have granted them, and the scaffold writes that result.
+ */
+const grants = (base: string, example: string | undefined): string =>
+  wrapList(
+    '    ',
+    'grants: [',
+    [base, ...(example === undefined ? [] : [example])].map((grant) => `'${grant}'`),
+    '],',
+  );
+
+const rolesSource = (
+  example: boolean,
+): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
 // permission set before any policy runs, so a rule never reasons about the hierarchy.
 //
 // ONE file, and it lives in shared/ — the leaf both site/ and app/ already import, and the one the
@@ -16,8 +30,9 @@ const rolesSource =
 // role HERE; calling defineRoles() again from a feature folder works and is the drift this file
 // exists to prevent.
 //
-// \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\`. Granting them is this
-// file's job — a permission no role holds is one no actor can ever exercise.
+// \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\` and grants them below —
+// read to member, write to admin. A permission no role holds is one no actor can ever exercise,
+// and \`x verify\`'s policy step refuses it (X_PERMISSION_UNGRANTED).
 
 import { definePermissions, defineRoles } from '@ultimat3/policy';
 
@@ -32,11 +47,11 @@ export const appPermissions = definePermissions(['admin:read', 'dashboard:read']
 export const roles = defineRoles({
   member: {
     description: 'Signed in. Reads the app surface.',
-    grants: ['dashboard:read'],
+${grants('dashboard:read', example ? 'post:read' : undefined)}
   },
   admin: {
     description: 'Runs the app: the /admin surface, plus everything a member may do.',
-    grants: ['admin:read'],
+${grants('admin:read', example ? 'post:write' : undefined)}
     inherits: ['member'],
   },
 });
@@ -49,12 +64,25 @@ import { expandRoles, isKnownPermission, rolesGranting } from '@ultimat3/policy'
 import { expect, unitTest } from '@ultimat3/testing';
 import { appPermissions, roles } from './roles';
 
+// Every feature's policy.ts, imported the way the boot scan imports it: \`x g policy\` grants the
+// permissions a policy.ts DECLARES, so the registry below is only whole once they have run.
+const features = new Bun.Glob('{app,site}/*/policy.ts');
+for await (const file of features.scan({ cwd: \`\${import.meta.dir}/..\` })) {
+  await import(\`\${import.meta.dir}/../\${file}\`);
+}
+
 // The map is passed explicitly rather than read off the module-global one: a test that depended on
 // which module imported first would pass alone and fail inside a suite.
 
+// Subsets, never exact lists: every \`x g policy\` adds a grant here, and a pinned list would make
+// the generator's correct edit a red test.
 unitTest('admin inherits every member grant and adds its own', () => {
-  expect(expandRoles(['member'], roles)).toEqual(['dashboard:read']);
-  expect(expandRoles(['admin'], roles)).toEqual(['admin:read', 'dashboard:read']);
+  const member = expandRoles(['member'], roles);
+  const admin = expandRoles(['admin'], roles);
+  expect(member).toContain('dashboard:read');
+  expect(member).not.toContain('admin:read');
+  expect(admin).toContain('admin:read');
+  for (const permission of member) expect(admin).toContain(permission);
 });
 
 unitTest('a role nobody declared grants nothing', () => {
@@ -88,9 +116,9 @@ unitTest('the routes this app ships require permissions this app declares', () =
 `;
 
 /** `apps/web/shared/roles.ts` and its test. Written by `x new`, with or without the example slice. */
-export function rolesFiles(): readonly GeneratedFile[] {
+export function rolesFiles(example = false): readonly GeneratedFile[] {
   return [
-    { path: 'apps/web/shared/roles.ts', contents: rolesSource() },
+    { path: 'apps/web/shared/roles.ts', contents: rolesSource(example) },
     { path: 'apps/web/shared/roles.test.ts', contents: rolesTest() },
   ];
 }

package/src/templates/slice-foundation.ts

@@ -3,7 +3,7 @@
 // `policyFiles`; the five generators that write *into* a slice imported the same files and wrote
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
-import { stripComments } from '../ts-scan';
+import { stripComments } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';

package/src/templates/wrap.ts

@@ -80,7 +80,10 @@ const compareSpecifiers = (left: string, right: string): number => {
  * than spelled in each template, because the correct spelling is not knowable at authoring time.
  */
 export const sortSpecifiers = (names: readonly string[]): readonly string[] =>
-  [...names].sort(compareSpecifiers);
+  [...names].sort((left, right) => compareSpecifiers(bare(left), bare(right)));
+
+/** An inline \`type X\` sorts as \`X\`: Biome orders by the imported name, never by the modifier. */
+const bare = (name: string): string => (name.startsWith('type ') ? name.slice(5) : name);
 
 /**
  * A named import, sorted and wrapped. Its own function because the braces are spaced on one line

package/src/test-passes.ts

@@ -3,8 +3,9 @@
 // this file decides how many, and `test-shards.ts` spends them.
 
 import type { TestFile } from './test-select';
+import { SERIAL_TYPES } from './test-workers';
 import type { TestType } from './verify-tests';
-import { ownerOf, SERIAL_TYPES } from './verify-tests';
+import { ownerOf } from './verify-tests';
 
 /** One `bun test` invocation: which files, how wide, and the type its reproduce line names. */
 export interface TestPass {

package/src/test-workers.ts

@@ -5,6 +5,7 @@
 
 // Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
 import { cpus } 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. */
 export function availableCpus(): number {
@@ -48,3 +49,28 @@ 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)));
+
+/**
+ * Which types run across worker processes, and why the other two cannot.
+ *
+ * Parallel is safe when the only thing a test file shares with another file is the database, and
+ * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
+ * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
+ * framework — the permission set, the roles, the entity/action/query registries, the error-code
+ * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.
+ *
+ * | Type | Why |
+ * |---|---|
+ * | `live` | **serial.** A logical replication slot and a publication are named at the Postgres
+ * CLUSTER level, not inside a database, and this repo's own feed tests hard-code
+ * `x_live_slot` / `x_live_pub` against `TEST_REPLICATION_URL` — the one server, never a per-worker
+ * clone. Two workers would race `pg_create_logical_replication_slot` and the loser's failure would
+ * read as a flake. A per-worker database does not isolate a cluster-wide object |
+ * | `e2e` | **serial.** It runs against the *built output*: one `dist/`, one service-worker
+ * registration, one browser profile. There is nothing per-worker to hand it, and the type is
+ * seconds at most, so a split would buy a race and no time |
+ *
+ * The two are named here rather than tested for, because "can this type be sharded?" is a design
+ * fact about the type, not something a run can discover about itself.
+ */
+export const SERIAL_TYPES: readonly TestType[] = ['live', 'e2e'];

package/src/ts-scan.ts

@@ -30,14 +30,11 @@ export interface CodeScan {
   readonly unresolved: readonly UnresolvedCodeSite[];
 }
 
-// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — lives in
-// `@ultimat3/core`'s `source-mask.ts` since 2026-09-05, because `@ultimat3/i18n`'s key extractor
-// (tier 1) needed it and could not reach a tier-5 package. Re-exported here so every scanner in
-// this package, and this package's public API, keep the names they had.
+// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — is
+// `@ultimat3/core`'s (`source-mask.ts`), imported from there by every scanner. It was re-exported
+// here and from this package's barrel: two import paths for one function (22.0.0 removed both).
 import { endOfLiteral, maskLiterals, QUOTES, stripComments } from '@ultimat3/core';
 
-export { endOfLiteral, maskLiterals, QUOTES, stripComments };
-
 // `ReadonlySet`, so a consumer cannot mutate what every scan in this package reads.
 export const OPENERS: ReadonlySet<string> = new Set(['(', '[', '{']);
 export const CLOSERS: ReadonlySet<string> = new Set([')', ']', '}']);

package/src/tsconfig-references.ts

@@ -7,9 +7,8 @@
 // root that has no `tsconfig.json` at all, so an `existsSync` ahead of it was a second question
 // with one answer.
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
 import type { Finding } from './output';
-import { maskLiterals, stripComments } from './ts-scan';
 
 const ROOT_TSCONFIG = 'tsconfig.json';
 

package/src/verify-checks.ts

@@ -15,12 +15,13 @@ import {
 import type { MetaIssue } from '@ultimat3/seo';
 import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
-import { checkAppBoundaries } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
-import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
 import { policyFindings } from './app-permissions';
 import { APP_CONFIG_FILE } from './app-root';
+import { asyncPageFindings } from './async-pages';
+import { appBoundaryFindings } from './boundary-findings';
 import { checkBudgets, readBuildStats } from './budgets';
 import { checkDestructiveMigrations } from './db-destructive';
 import { checkUngeneratableMigrations } from './db-ungeneratable';
@@ -28,17 +29,21 @@ import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkErrorCodeResolution, checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
+import { unregisteredJobFindings } from './job-registration';
 import { liveRouteFindings } from './live-routes';
+import { withLoadFindings, withoutLoadFindings } from './load-findings';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { checkMigrationDrift } from './schema-drift';
 import { scanSiteMeta } from './seo-meta';
+import { quoteArg } from './shell-quote';
 import { readStaticReport } from './static-report';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
+import { typecheckArgs } from './verify-typecheck';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 import { checkWorkspaceDependencies } from './workspace-graph';
 
@@ -49,22 +54,21 @@ const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
-    summary: 'tsc -b across every project the root references',
+    summary: 'tsc -b across every project the root references, tsc -p . where it references none',
     // `typecheckBin` (`x.verify.json`, beside `agentsMdMaxBytes`) swaps the binary and nothing
-    // else: same `-b --pretty false` invocation, same output format to parse, same `X_TYPECHECK_
-    // FAILED` finding either way. Absent means `tsc` — the only checker every app already has,
-    // since `typescript` is a framework dependency and a drop-in replacement is the app's own
-    // devDependency to add, never a default this step could assume.
+    // else: same invocation, same output format to parse, same `X_TYPECHECK_FAILED` finding either
+    // way. Absent means `tsc` — the only checker every app already has, since `typescript` is a
+    // framework dependency and a drop-in replacement is the app's own devDependency to add, never
+    // a default this step could assume. `-b` or `-p .` is `typecheckArgs`' call (#450).
     async run(ctx) {
       const floor = await readVerifyFloor(ctx.root);
-      const bin = floor?.typecheckBin ?? 'tsc';
-      const result = await ctx.runner(['bunx', bin, '-b', '--pretty', 'false'], {
-        cwd: ctx.root,
-      });
+      const argv = await typecheckArgs(ctx.root, floor?.typecheckBin ?? 'tsc');
+      const result = await ctx.runner(['bunx', ...argv], { cwd: ctx.root });
       return fromExec(result, {
         code: 'X_TYPECHECK_FAILED',
         cause: 'the project does not typecheck',
-        fix: `bunx ${bin} -b --pretty false`,
+        // Joined, never spliced: `typecheckBin` is a value from the app's `x.verify.json`.
+        fix: ['bunx', ...argv.map(quoteArg)].join(' '),
       });
     },
   },
@@ -99,7 +103,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // extension model rejects.
     run: async (ctx) =>
       fromFindings([
-        ...(await checkAppBoundaries(ctx.root)),
+        ...(await appBoundaryFindings(ctx.root)),
         ...(await guardFindings(ctx.root)),
         ...(await hostFindings(ctx, 'boundaries')),
       ]),
@@ -187,10 +191,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     async run(ctx) {
       const committed = await readAppManifest(ctx.root);
       const { manifest, findings } = await appManifest(ctx.root);
-      return fromFindings([
+      // A module that will not import is `manifest`'s to report (`load-findings.ts`).
+      return withoutLoadFindings(ctx.root, [
         ...findings,
         ...(committed === undefined ? [] : contractFindings(committed, manifest)),
-        ...(await specFindings(ctx.root, manifest)),
+        ...(await openApiStaleness(ctx.root, manifest)),
       ]);
     },
   },
@@ -224,21 +229,27 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // reported under `X_ISLAND_PROPS_INVALID` — the build's own sentence, naming the prop and
       // its bytes — and not as an `X_BUDGET_UNMEASURED` whose fix is to go and read this file.
       const report = await readStaticReport(ctx.root);
-      // The load's own findings, FIRST and never dropped. A module that would not import registers
-      // no route, so its budget is missing from the manifest and every route it declared reads as
-      // `X_BUDGET_UNMEASURED` — the symptom, pointing the reader at `x build` for a file that will
-      // not compile. `contract-diff` reports these too when it applies; two red steps naming one
-      // broken module is honest, and one of them silently green over it is the false green.
+      // The load's own findings are `manifest`'s, reported there once; this step's output says so.
+      // A module that would not import registers no route, so every route it declared still reads
+      // as `X_BUDGET_UNMEASURED` here — the symptom stays this step's, and the gate stays red.
       const { manifest, findings } = await appManifest(ctx.root);
-      return fromFindings([
+      const outcome = await withoutLoadFindings(ctx.root, [
         ...findings,
         ...checkDocumentStyles(documentSurfaces()),
         // The third rider, and the same question this step already asks one level down: what
         // JavaScript does this route's document boot? A live read with no island is a route
         // whose answer is "none", which no suite can fail on — the page renders, at 200.
         ...(await liveRouteFindings(ctx.root)),
+        // The fourth: a data read in an async Page rather than in `load` (`async-pages.ts`).
+        ...asyncPageFindings(),
         ...checkBudgets(manifest, stats, report?.unmeasured),
       ]);
+      // What no build can weigh, said out loud rather than dropped (`measure-paths.ts`).
+      const notes = (report?.unmeasured ?? [])
+        .filter((one) => one.weighable === false)
+        .map((one) => `not weighed: ${one.reason}`);
+      const output = [outcome.output, ...notes].filter((line) => line !== undefined).join('\n');
+      return output === '' ? outcome : { ...outcome, output };
     },
   },
   {
@@ -293,7 +304,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // registers no routes — SKIPPED there, never passed, for the reason `i18n` gives: a step that
     // answers `ok` about nothing is the vacuous green these checks exist to refuse.
     applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
-    run: async (ctx) => fromFindings(await policyFindings(ctx.root)),
+    run: async (ctx) => withoutLoadFindings(ctx.root, await policyFindings(ctx.root)),
   },
   {
     name: 'manifest',
@@ -315,9 +326,16 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // and reading it after the check would enforce the default on a repo that raised it.
       const floor = await readVerifyFloor(ctx.root);
       const agents = await checkAgentsMd(ctx.root, floor?.agentsMdMaxBytes);
+      // The app's load failures, once, here — every other step that loaded it points at this one.
+      const app = existsSync(join(ctx.root, APP_CONFIG_FILE));
+      const drift = await driftFindings(ctx.root);
       const findings = [
         ...manifestMissingFindings(ctx.root),
-        ...(await driftFindings(ctx.root)),
+        ...(app ? await withLoadFindings(ctx.root, drift) : drift),
+        // An app only: the framework monorepo declares no `defineApi`, so it has no list to be in.
+        ...(existsSync(join(ctx.root, APP_CONFIG_FILE))
+          ? await unregisteredJobFindings(ctx.root)
+          : []),
         ...(await envExampleFindings(ctx.root)),
         ...floorProblemFindings(floor),
         ...agents.findings,
@@ -394,22 +412,6 @@ function contractFindings(before: Manifest, after: Manifest): readonly Finding[]
   }
 }
 
-/** The typed client is generated from `openapi.json`, so a stale spec ships a wrong client. */
-async function specFindings(root: string, manifest: Manifest): Promise<readonly Finding[]> {
-  const path = join(root, OPENAPI_FILE);
-  if (!existsSync(path)) 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,
-    },
-  ];
-}
-
 /**
  * One `MetaIssue` as the gate reports it. `at` is the route FILE and never the URL: every seo error
  * already names the file in its cause, and `at` is what an agent opens.

package/src/verify-e2e.ts

@@ -0,0 +1,41 @@
+// What the gate's `e2e` step does around the suite in an APP: when this machine has a browser, it
+// runs the suite with the e2e preload and names the app root, and the PRELOAD spawns the app — so
+// the app lives in the test process, where `deploy.newBuild()` can restart it. No browser, or not an
+// app: the suite runs as before and its browser-backed cases skip — or refuse under
+// `E2E_BROWSER_REQUIRED=1`.
+
+import { E2E_ROOT_ENV, findChrome } from '@ultimat3/testing';
+import type { ExecResult } from './exec';
+
+/**
+ * The preload `bun test` is handed, beside the app's own from `bunfig.toml` — `@ultimat3/testing`'s,
+ * resolved from here to the absolute path the child process loads. A FUNCTION, resolved when a run
+ * needs it: at module scope it ran on every import of the registry, and a compiled `x` binary —
+ * whose `/$bunfs` holds no `node_modules` — died at boot resolving a file it never uses.
+ */
+export const e2ePreload = (): string =>
+  Bun.resolveSync('@ultimat3/testing/e2e-preload', import.meta.dir);
+
+export interface E2eRun {
+  readonly command: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/** Wrap one e2e `bun test` invocation: `run` receives the command and extra environment to use. */
+export async function withE2eApp(
+  input: {
+    readonly root: string;
+    readonly isApp: boolean;
+    readonly command: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+  },
+  run: (e2e: E2eRun) => Promise<ExecResult>,
+): Promise<ExecResult> {
+  const chrome = input.isApp ? await findChrome(Bun.env) : undefined;
+  if (chrome === undefined) return run({ command: input.command, env: input.env });
+  const [bun = 'bun', test = 'test', ...rest] = input.command;
+  return run({
+    command: [bun, test, '--preload', e2ePreload(), ...rest],
+    env: { ...input.env, [E2E_ROOT_ENV]: input.root },
+  });
+}