@ultimat3/cli 23.0.0 → 25.0.0

package/src/theme-boot.ts

@@ -1,40 +1,15 @@
-// The no-flash theme script, inlined into every document a served or exported process writes,
-// with `theme.defaultMode` from `app.config.ts` as its fallback. Before this the key had no reader
-// at all (pinned as a dead key in `scripts/lib/config-reader-pins.ts`) and neither of the two
-// scripts the framework exported was wired into a document: an app that wanted to open dark had to
-// write its own boot script AND admit it to the CSP by hand — which every app forgot in one of the
-// two places. Sibling of `app-auth.ts`'s `loadSignInPath` and imports the config for the same
-// reason: a regex over the app's source is the pattern `app-load.ts` refuses.
+// The no-flash theme script, inlined into every document a served or exported process writes, with
+// `theme.defaultMode` (off the one loader, `app-config-load.ts`) as its fallback — and the CSP source
+// that admits it, so no app writes its own boot script and forgets to admit it.
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `app-auth.ts` records.
-import { join } from 'node:path';
 import type { ThemeMode } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
 import { renderHead, themeScript, themeScriptBody } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isThemeMode = (value: unknown): value is ThemeMode =>
-  value === 'light' || value === 'dark' || value === 'system';
-
-/**
- * `theme.defaultMode`, or `'system'` — the value `defineConfig` fills in — when the app declares
- * none or the file is absent. Structural, never `instanceof`, for `loadSignInPath`'s reason.
- */
+/** `theme.defaultMode`, or `'system'` — core's own default — for a root with no config file. */
 export async function loadThemeMode(root: string): Promise<ThemeMode> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return 'system';
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return 'system';
-  const theme = config['theme'];
-  if (!isRecord(theme)) return 'system';
-  const mode = theme['defaultMode'];
-  return isThemeMode(mode) ? mode : 'system';
+  return (await loadAppConfig(root))?.theme.defaultMode ?? 'system';
 }
 
 export interface ThemeBoot {
@@ -47,8 +22,8 @@ export interface ThemeBoot {
 /**
  * Tag and hash from ONE body: `themeScriptBody` is what `themeScript` inlines, so a policy hashed
  * here admits the script the document carries and not a restatement of it. The storage key is
- * render's `THEME_STORAGE_KEY`, which `theme-boot.test.ts` pins equal to `@ultimat3/ui`'s — the
- * toggle writes the key the boot reads.
+ * `@ultimat3/core`'s `THEME_STORAGE_KEY`, the one `@ultimat3/ui`'s toggle writes — so the toggle
+ * writes the key the boot reads.
  */
 export function themeBoot(mode: ThemeMode): ThemeBoot {
   const options = { fallback: mode };

package/src/theme-brand.ts

@@ -0,0 +1,66 @@
+// The app's brand, declared once as `export const brand = defineTheme(…)` in
+// `apps/web/shared/theme.ts`, read here and nowhere else: the `<style>` every document the boot
+// renders carries after its stylesheet, and the body `style-src` admits. No module, no brand: an
+// unthemed app emits no tag and extends no policy.
+
+// why: Bun exposes no path-join primitive, and the module path is app-root-relative.
+import { join } from 'node:path';
+import { ConfigInvalidError, describeValue } from '@ultimat3/core';
+import { renderHead } from '@ultimat3/render';
+
+/** The conventional module, beside `shared/global.ts` — one fixed path, as `API_INDEX` is. */
+export const APP_THEME_MODULE = 'apps/web/shared/theme.ts';
+/** The named export the module declares — `@ultimat3/ui`'s README spells it `brand`. */
+export const APP_THEME_EXPORT = 'brand';
+
+export interface ThemeBrand {
+  /** The rendered `<style>`, for `DocumentOptions.brandHead`. */
+  readonly head: string;
+  /** Exactly the text between the tags — the body a boot hands `inlineStyleSources`. */
+  readonly style: string;
+}
+
+/** Code to paste, as `loadAppConfig`'s is: the module path is already in the cause. */
+const FIX = `export const ${APP_THEME_EXPORT} = defineTheme({ preset: 'scifi' });`;
+
+/**
+ * `undefined` when the app has no theme module or its brand renders no CSS. A module that will not
+ * import throws as it did, so a palette `defineTheme()` refuses fails the boot with
+ * `X_UI_CONTRAST_INSUFFICIENT` (or its token code) and not a rewording of it.
+ */
+export async function loadThemeBrand(root: string): Promise<ThemeBrand | undefined> {
+  const path = join(root, APP_THEME_MODULE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  const css = brandCss(path, module);
+  if (css.length === 0) return undefined;
+  // `renderHead` escapes `</` in a style body, which would make the tag's text differ from the
+  // hashed one — so a body that needs escaping is refused above rather than escaped here.
+  return { head: renderHead([{ kind: 'style', key: 'style:brand', content: css }]), style: css };
+}
+
+/**
+ * The brand's stylesheet, read structurally: `@ultimat3/ui` is a tier below and this package does
+ * not import it, so a `Brand` is `{ css: string }`. `defineTheme()` never emits `<` — its values
+ * are validated against grammars that exclude it — so one here came from a hand-built object, and
+ * it is the one character that could end the element and start markup.
+ */
+function brandCss(path: string, module: Record<string, unknown>): string {
+  const brand = Object.hasOwn(module, APP_THEME_EXPORT) ? module[APP_THEME_EXPORT] : undefined;
+  const css = typeof brand === 'object' && brand !== null && 'css' in brand ? brand.css : undefined;
+  if (typeof css !== 'string') {
+    throw new ConfigInvalidError({
+      cause: `${path} exports no ${APP_THEME_EXPORT} built by defineTheme() (${describeValue(brand)}), so no document can carry the app's theme — declare it with defineTheme from @ultimat3/ui`,
+      fix: FIX,
+      meta: { key: APP_THEME_EXPORT },
+    });
+  }
+  if (css.includes('<')) {
+    throw new ConfigInvalidError({
+      cause: `${path}'s ${APP_THEME_EXPORT}.css contains "<", which defineTheme() never emits and which could close the <style> element it is inlined in`,
+      fix: FIX,
+      meta: { key: APP_THEME_EXPORT },
+    });
+  }
+  return css;
+}

package/src/trusted-hops-error.ts

@@ -0,0 +1,17 @@
+// The refusal of a malformed `TRUSTED_PROXY_HOPS` — its own code, never `X_PORT_INVALID`: a proxy
+// count is not a port, and an operator told "is not a TCP port number" looked for the wrong setting.
+
+import { UltimateError } from '@ultimat3/core';
+import { MAX_PROXY_HOPS } from '@ultimat3/http';
+import { quoteArg } from './shell-quote';
+
+export class TrustedProxyHopsInvalidError extends UltimateError {
+  constructor(input: { readonly value: string }) {
+    super({
+      code: 'X_TRUSTED_PROXY_HOPS_INVALID',
+      cause: `TRUSTED_PROXY_HOPS=${quoteArg(input.value)} is not a whole number of proxies from 1 to ${MAX_PROXY_HOPS} — the count that append to x-forwarded-for in front of this process; unset means none`,
+      fix: 'TRUSTED_PROXY_HOPS=1 ROLE=web bun apps/web/server.ts',
+      meta: { value: input.value, max: MAX_PROXY_HOPS },
+    });
+  }
+}

package/src/trusted-hops.ts

@@ -0,0 +1,49 @@
+// How many proxies sit in front of this process, read from `TRUSTED_PROXY_HOPS`. Its own module
+// so both the web role (`role-start.ts`) and the sync node (`role-sync.ts`) read it without one
+// importing the other — `role-start` imports `role-sync`, and the reverse edge was a cycle.
+
+import { MAX_PROXY_HOPS } from '@ultimat3/http';
+import type { Env } from './runtime-bindings';
+import { TrustedProxyHopsInvalidError } from './trusted-hops-error';
+
+/**
+ * How many proxies is too many, and the number is **`@ultimat3/http`'s**, not this file's.
+ *
+ * `defineHttpConfig` screens the same setting — `assertFiniteCount('trustedProxyHops', …,
+ * MAX_PROXY_HOPS)` — and this screen used to say 16 where that one says 64, so one setting had two
+ * ceilings and a deployment behind 20 hops was accepted by the library and refused by the boot.
+ * Widened rather than narrowed: tightening the library would break a shipped public API, while
+ * this end only ever refused topologies http already supports.
+ *
+ * It was a duplicated literal until 2026-08-26, because `@ultimat3/http` did not export the
+ * constant. It does now, so this file IMPORTS it — a downward edge, tier 5 to tier 2 — and there is
+ * no second number left to drift. `runtime-overrides.test.ts` still probes both screens for the
+ * highest count each accepts, and it is kept rather than deleted: it compares BEHAVIOUR, so it also
+ * catches the two disagreeing for a reason a shared constant cannot fix, such as one side gaining a
+ * range check the other does not have.
+ */
+
+/**
+ * How many proxies append to `x-forwarded-for` between the client and this process, or `null`
+ * when nothing in front of it is trusted.
+ *
+ * Read from the environment and not from `app.config.ts`, for the reason `PORT` and `ROLE` are: it
+ * is a fact about the DEPLOYMENT — one image runs behind an ingress in one cluster and behind
+ * nothing on a laptop — and an app that hardcoded it would be wrong in one of the two. `x dev`
+ * sets neither and gets `trustProxy: false`, which is correct: there is no proxy.
+ *
+ * Without this seam a container behind an ingress reads `ctx.ip` as the ingress's own socket
+ * address on every request, so the rate limiter keys the entire fleet's anonymous traffic into ONE
+ * bucket and a single scanner 429s every real signup.
+ */
+export function trustedHopsFromEnv(env: Env): number | null {
+  const raw = env['TRUSTED_PROXY_HOPS']?.trim();
+  if (raw === undefined || raw === '') return null;
+  const hops = Number(raw);
+  // A malformed count is refused rather than defaulted: reading the header at the wrong index is
+  // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
+  if (!/^\d+$/.test(raw) || !Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
+    throw new TrustedProxyHopsInvalidError({ value: raw });
+  }
+  return hops;
+}

package/src/unscanned-admin.ts

@@ -4,7 +4,7 @@
 // silently, which is how the reference app shipped an admin nobody could open.
 
 import { renderFixShellArg, stripComments } from '@ultimat3/core';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { ADMIN_FILE } from './admin-registration';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
@@ -17,7 +17,7 @@ const DECLARES = /\bdefineAdmin\(/;
 
 /** Any admin this process mounted — then every declaration was reached, wherever it sits. */
 export const adminMounted = (): boolean =>
-  describeRoutes().some((route) => route.mount?.by === 'defineAdmin');
+  describePages().some((route) => route.mount?.by === 'defineAdmin');
 
 /** Where the file belongs: its own name under the admin's home, `index.ts` as the declaration. */
 const homeOf = (file: string): string => {

package/src/unthrown-codes.ts

@@ -0,0 +1,26 @@
+// The registered codes this repo no longer throws, as a list `error-unthrown.ts` reads — its own
+// file, so the literals naming the waived codes are not mistaken for a throw site.
+
+/** Where the list lives, so a finding can name the file to edit. */
+export const UNTHROWN_CODES_FILE = 'packages/cli/src/unthrown-codes.ts';
+
+/**
+ * The codes this repo registers and no longer throws — each a decision, and each row on the
+ * reference page says so in words. A LIST, never a prose match: the waiver was any row containing
+ * "not thrown" or "thrown by nothing", so a sentence that happened to use either phrase silenced the
+ * rule for its code. A listing whose code is thrown again, or is not registered, is
+ * `X_ERROR_CODE_UNTHROWN_STALE`.
+ */
+export const UNTHROWN_CODES: ReadonlySet<string> = new Set([
+  // `x db studio` is planned and unreleased; it exits X_NOT_IMPLEMENTED.
+  'X_DB_STUDIO_FAILED',
+  // 21.0.0: there is no LiveClient to register (X_REALTIME_UNINSTALLED replaced it).
+  'X_LIVE_CLIENT_MISSING',
+  // 21.0.0: liveHookFor was deleted; useQuery reads any query.
+  'X_QUERY_NOT_SUBSCRIBABLE',
+  // 21.0.0: the worker no longer POSTs a flush endpoint nothing mounted.
+  'X_PWA_SYNC_FLUSH_FAILED',
+  'X_PWA_SYNC_INCOMPLETE',
+  // 24.0.0: `x test --worker` was deleted; `x verify --only unit --shard i/n` is the one split.
+  'X_TEST_SHARD_FAILED',
+]);

package/src/verify-checks.ts

@@ -6,19 +6,13 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
-import {
-  AGENTS_MD_FILENAME,
-  assertNoDrift,
-  MANIFEST_FILENAME,
-  verifyContract,
-} from '@ultimat3/manifest';
+import { AGENTS_MD_FILENAME, MANIFEST_FILENAME, verifyContract } from '@ultimat3/manifest';
 import type { MetaIssue } from '@ultimat3/seo';
 import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
 import { readAppSources } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
-import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
 import { policyFindings } from './app-permissions';
 import { APP_CONFIG_FILE } from './app-root';
 import { asyncPageFindings } from './async-pages';
@@ -33,6 +27,11 @@ import { catalogFindings } from './i18n-registration';
 import { unregisteredJobFindings } from './job-registration';
 import { liveRouteFindings } from './live-routes';
 import { withLoadFindings, withoutLoadFindings } from './load-findings';
+import {
+  hasCommittedContract,
+  manifestMissingFindings,
+  manifestStaleness,
+} from './manifest-staleness';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -47,7 +46,7 @@ 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 { checkPackageShape, fileSizeReport, hasWorkspacePackages } from './workspace-checks';
 import { checkWorkspaceDependencies } from './workspace-graph';
 
 /** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
@@ -121,7 +120,17 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'filesize',
     summary: 'one file, one job',
-    run: async (ctx) => fromFindings(await checkFileSizes(ctx.root)),
+    // The band below the ceiling rides as warnings: listed in `--json` on a pass, never a failure.
+    run: async (ctx) => {
+      const { findings, warnings } = await fileSizeReport(ctx.root);
+      return {
+        ...fromFindings(findings),
+        warnings: warnings.map(
+          (warning) =>
+            `${warning.path}: ${warning.lines} lines, ${warning.ceiling - warning.lines} under the ${warning.ceiling} line ceiling — plan the split`,
+        ),
+      };
+    },
   },
   {
     name: 'package-shape',
@@ -198,10 +207,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'contract-diff',
     summary: 'the published contract vs the committed manifest',
-    // Either file is a published contract on its own: `openapi.json` generates the typed client,
-    // so gating on the manifest alone let a stale spec ship a wrong client unchecked.
-    applies: async (ctx) =>
-      existsSync(join(ctx.root, MANIFEST_FILENAME)) || existsSync(join(ctx.root, OPENAPI_FILE)),
+    // A BREAKING change against the committed manifest, and nothing else. Whether the committed
+    // files are stale — `openapi.json` included — is the `manifest` step's, through the one check
+    // `x manifest --check` runs (`manifest-staleness.ts`): reported here as well it was two
+    // steps and one command answering one question, and the step named `manifest` saying green.
+    applies: async (ctx) => existsSync(join(ctx.root, MANIFEST_FILENAME)),
     async run(ctx) {
       const committed = await readAppManifest(ctx.root);
       const { manifest, findings } = await appManifest(ctx.root);
@@ -209,14 +219,13 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       return withoutLoadFindings(ctx.root, [
         ...findings,
         ...(committed === undefined ? [] : contractFindings(committed, manifest)),
-        ...(await openApiStaleness(ctx.root, manifest)),
       ]);
     },
   },
   {
     name: 'budgets',
     summary:
-      'per-route JS bytes and LCP, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
+      'per-route JS bytes, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
     // The global-style assertion rides here rather than becoming a step of its own, because this
     // step already asks the one question it asks: what does the document this build emits actually
     // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
@@ -346,7 +355,6 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       const roleLoad = app ? roleLoadFindings(ctx.root, ctx.runner) : Promise.resolve([]);
       const drift = await driftFindings(ctx.root);
       const findings = [
-        ...manifestMissingFindings(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))
@@ -384,41 +392,14 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
 ];
 
 /**
- * The half that had never been asked: is the file there at all? `driftFindings` returns nothing
- * when it is absent — correctly, it has nothing to compare — and `AGENTS.md` line 3 tells an agent
- * that facts live in `x.manifest.json`, `x dev` prints its path, and `x manifest` is the only
- * thing that writes it. Nothing ran it: after `x new`, `bin/setup` and all thirteen generators,
- * `find . -name '*.manifest.json'` returned nothing while this step reported green (#F7).
- *
- * An app root, never this repo: the framework monorepo emits `framework.manifest.json` and has no
- * `x.manifest.json` to be missing, so the `app.config.ts` is what decides — the same discriminator
- * `drift`, `budgets`, `seo`, `i18n` and `policy` each use.
+ * The committed generated files against the code — `x manifest --check`'s check, through its
+ * function. With no committed contract there is nothing to load an app for: an app root is told
+ * its manifest is missing, and the framework monorepo (which has neither file) is told nothing.
  */
-function manifestMissingFindings(root: string): readonly Finding[] {
-  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
-  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
-  return [
-    {
-      code: 'X_MANIFEST_MISSING',
-      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
-      fix: 'x manifest',
-      docs: ERROR_DOCS_URL,
-      at: MANIFEST_FILENAME,
-    },
-  ];
-}
-
-/** `assertNoDrift` throws `X_MANIFEST_DRIFT`; a step reports, so the error becomes a finding. */
 async function driftFindings(root: string): Promise<readonly Finding[]> {
-  const path = join(root, MANIFEST_FILENAME);
-  if (!existsSync(path)) return [];
+  if (!hasCommittedContract(root)) return manifestMissingFindings(root);
   const { manifest, findings } = await appManifest(root);
-  try {
-    await assertNoDrift({ manifest, path });
-    return findings;
-  } catch (error) {
-    return [...findings, { ...findingFrom(error), at: MANIFEST_FILENAME }];
-  }
+  return [...findings, ...(await manifestStaleness(root, manifest))];
 }
 
 /** A breaking change is allowed — with a major bump. `verifyContract` is the one that decides. */

package/src/verify-coverage-run.ts

@@ -14,6 +14,7 @@
 import { rm } from 'node:fs/promises';
 // why: Bun ships no path-join primitive.
 import { dirname, join } from 'node:path';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { CoverageMap } from './coverage-lcov';
 import { fileCoverageOf, mergeCoverage, parseLcov } from './coverage-lcov';
 import type { ExecResult, Runner } from './exec';
@@ -21,7 +22,7 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
-import { failureOf, ISOLATED_TEST_ENV } from './test-shards';
+import { failureOf } from './test-shards';
 import { SLOT_HELD_ENV } from './test-slots';
 import type { StepOutcome } from './verify-step';
 
@@ -113,7 +114,7 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
   const isolate = options.isolate === true;
   const overrides = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
-    ...(isolate ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(isolate ? { [ISOLATED_ENV]: '1' } : {}),
     ...(lease === undefined ? {} : { [SLOT_HELD_ENV]: '1' }),
   };
   const results = new Array<ExecResult>(slices.length);