@ultimat3/cli 23.0.0 → 24.0.0

package/src/templates/route.ts

@@ -33,12 +33,9 @@ const OFFLINE: Record<Surface, string> = { site: 'precache', app: 'runtime' };
 /**
  * Structured, not a literal string: the route and the test that pins it read the same fact.
  *
- * `lcp` is deliberately NOT here. `RouteBudget.lcp` is accepted by `defineRoute`, and nothing in
- * the framework can produce the `lcpMs` that `checkBudgets` compares it against — `prerender.ts`
- * emits static HTML and there is no browser in the build to observe a paint. A scaffolded `lcp`
- * was therefore a budget that reads as declared, is never weighed, and passes silently the moment
- * a `build-stats.json` row exists: the false green `budgets.ts`'s own header forbids. Scaffolding
- * only what the build measures is the half of "delete it or thread it" that `x new` can act on.
+ * `js` is the one budget a route can declare: it is the one the build weighs. `lcp` was scaffolded
+ * here once and then deleted from `RouteBudget` itself — nothing in the framework observes a
+ * paint, so it read as declared and was never weighed.
  */
 const BUDGET: Record<Surface, { readonly js: string }> = {
   site: { js: '0kb' },

package/src/templates/scaffold-app.ts

@@ -16,6 +16,10 @@ import { rolesFiles } from './scaffold-roles';
 import { shellFiles } from './scaffold-shell';
 import { siteFiles } from './scaffold-site';
 
+// `typecheck` is the ROOT program, as in every workspace `x new` writes: a type extension declared in
+// one workspace (`PermissionRegistry` in `app/*/policy.ts`) is in force only where its file is in
+// the program, and the app's own `tsconfig.json` passed in `apps/admin` what the gate refuses.
+//
 // The one dependency this manifest names, and it is not decoration: every page below reads its
 // strings through `@<app>/i18n`'s `useT()`, so the surface that renders a string DEPENDS on the
 // module that registers the catalogs. An undeclared workspace dependency resolves through the root
@@ -36,7 +40,7 @@ const webPackage = (app: NameSet, example: boolean): string => {
     "./*.tsx": "./*.tsx"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
   },
   "dependencies": {${db}
     "@${app.kebab}/i18n": "0.0.0"
@@ -260,7 +264,7 @@ const adminPackage = (app: NameSet): string => `{
     "./*.tsx": "./*.tsx"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
   },
   "dependencies": {
     "@${app.kebab}/db": "0.0.0",

package/src/templates/scaffold-container-compose.ts

@@ -25,6 +25,11 @@ export const composeProdFile = (
 #
 #   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
 #
+# Two origins the file cannot know, so ${PROD_ENV_FILE} states them: SYNC_URL, where a page dials
+# the socket (ws://<host>:3001/_x/sync), and APP_URL, where the pages are served
+# (http://<host>:3000) — the sync node admits a socket from APP_URL's origin and no other once
+# declared; undeclared, from the origin it was reached on.
+#
 # A published host port has exactly one binder, so \`web\` and \`sync\` run at 1 here. Compose is one
 # box; horizontal scaling of those two belongs to an orchestrator — \`docker/helm\`, beside this
 # file, is the chart \`x deploy --method helm\` installs. To scale them on one box anyway, drop
@@ -129,7 +134,11 @@ services:
 
   sync:
     <<: *image
-    environment: [ROLE=sync]
+    # The page is :3000 and this socket :3001 — two origins — and the node admits an upgrade from
+    # APP_URL's origin and no other once declared (scheme, host and port, exactly); undeclared, from
+    # the origin it was reached on. Unset, every websocket is 403 X_SOCKET_ORIGIN_REFUSED, so it is
+    # required: the same value web builds its links from.
+    environment: [ROLE=sync, 'APP_URL=\${APP_URL:?set APP_URL=http://<host>:3000 — the origin the pages are served on, see wiki/Deployment.md}']
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }

package/src/templates/scaffold-container.ts

@@ -30,14 +30,16 @@ const dockerfile = (
 # install refuses. \`bunfig.toml\` survives because its \`[install]\` section is input to the install,
 # and so does a \`.tgz\`: a \`file:\` tarball dependency (a vendored or private package) is resolved
 # from the file itself, and without it the frozen install cannot find what the lockfile names.
-FROM oven/bun:1.4-alpine AS manifests
+# The tag names the series for the reader; the digest is what builds — a tag is a pointer its
+# publisher can move. Dependabot's docker ecosystem moves the digest together with the tag.
+FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS manifests
 WORKDIR /app
 COPY . .
 RUN find . ! -type d ! -name package.json ! -name bunfig.toml ! -name '*.tgz' -delete \\
  && find . -type d -empty -delete
 
 # ---------- deps: runtime dependencies only, cached on the lockfile and the manifests ----------
-FROM oven/bun:1.4-alpine AS deps
+FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS deps
 WORKDIR /app
 COPY --from=manifests /app ./
 COPY bun.lock ./

package/src/templates/scaffold-db-client.ts

@@ -74,7 +74,7 @@ export const dbClientSource = (
 // same two lines: its import, and \`<tableName>: <entity>,\` in the set.
 
 ${sortedImports([
-  "import { resolveEnvironment } from '@ultimat3/core';",
+  "import { storeMode } from '@ultimat3/core';",
   "import { type Driver, database, memoryDriver, postgresDriver } from '@ultimat3/entity';",
   ...entries.map(handleImportLine),
 ])}
@@ -86,9 +86,11 @@ ${sortedImports([
  * \`postgresDriver()\` takes no connection: it resolves \`@ultimat3/db\`'s process client, which is
  * the embedded PGlite under \`x dev\` and the \`DATABASE_URL\` pool in a container. \`bun test\`
  * installs no client, so a test gets the in-memory driver — the same contract, no database.
+ * \`storeMode\` is core's one answer to that question, shared with every other seam that has a
+ * memory and a database store.
  */
 export const selectDriver = (env: Readonly<Record<string, string | undefined>>): Driver =>
-  resolveEnvironment({ env }) === 'test' ? memoryDriver() : postgresDriver();
+  storeMode(env) === 'memory' ? memoryDriver() : postgresDriver();
 
 export const driver = selectDriver(Bun.env);
 

package/src/templates/scaffold-helm-fences.ts

@@ -0,0 +1,76 @@
+// What a compromised pod of the scaffolded chart can reach: its `/tmp`, bounded, and its ports,
+// fenced by one NetworkPolicy per role. The framework chart's own (`docker/helm/`), mirrored —
+// `scaffold-helm-parity.test.ts` holds the two to each other.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const volumes = (app: NameSet): string => `{{/*
+The writable scratch every pod mounts at /tmp — the root filesystem is read-only. Bounded, because
+an emptyDir with no sizeLimit is node disk: one role filling /tmp evicts its NEIGHBOURS for disk
+pressure, where with a limit the kubelet evicts that pod alone.
+*/}}
+{{- define "${app.kebab}.tmpVolume" -}}
+- name: tmp
+  emptyDir:
+    sizeLimit: {{ required "tmp.sizeLimit is unset — set it in your values (e.g. 512Mi): an unbounded /tmp is node disk" (default dict .Values.tmp).sizeLimit | quote }}
+{{- end -}}
+`;
+
+const networkPolicy = (app: NameSet): string => `{{/*
+One NetworkPolicy per enabled role: \`http\` (web, sync) from networkPolicy.httpFrom, \`metrics\`
+(every role) from networkPolicy.metricsFrom, nothing else. A \`from\` that renders empty is omitted,
+which Kubernetes reads as "any source". Egress is filtered only when networkPolicy.egress lists
+rules — the database, NATS and object store are your addresses, so list DNS too. Serving roles
+only: the migrate Job is a pre-install hook that runs before this exists, and opens no port.
+*/}}
+{{- if .Values.networkPolicy.enabled }}
+{{- range $role, $cfg := .Values.roles }}
+{{- if $cfg.enabled }}
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  podSelector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ $.Release.Name }}
+      app.kubernetes.io/component: {{ $role }}
+  policyTypes:
+    - Ingress
+    {{- if $.Values.networkPolicy.egress }}
+    - Egress
+    {{- end }}
+  ingress:
+    {{- if $cfg.port }}
+    - ports:
+        - port: http
+          protocol: TCP
+      {{- with $.Values.networkPolicy.httpFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+    {{- end }}
+    - ports:
+        - port: metrics
+          protocol: TCP
+      {{- with $.Values.networkPolicy.metricsFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+  {{- with $.Values.networkPolicy.egress }}
+  egress: {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
+{{- end }}
+{{- end }}
+`;
+
+/** The bounded /tmp helper and the per-role NetworkPolicy, as two files of the chart's templates. */
+export function helmFenceFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/helm/templates/_volumes.tpl', contents: volumes(app) },
+    { path: 'docker/helm/templates/networkpolicy.yaml', contents: networkPolicy(app) },
+  ];
+}

package/src/templates/scaffold-helm-templates.ts

@@ -3,6 +3,7 @@
 // Split from scaffold-helm.ts, which holds the chart's INPUTS (Chart.yaml, values.yaml).
 
 import type { GeneratedFile, NameSet } from './naming';
+import { helmFenceFiles } from './scaffold-helm-fences';
 
 const helpers = (
   app: NameSet,
@@ -79,13 +80,28 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     - name: METRICS_PORT
       value: {{ $root.Values.metricsPort | quote }}
     {{- end }}
+    {{- /*
+    The sync node's page origin, from the one place this chart already knows it. Undeclared, a node
+    reached over plain http behind this Ingress admits BOTH spellings of its host — the plain-http
+    page included. env.APP_URL wins when set; an APP_URL kept in the Secret is shadowed for this
+    role, so pages served from another host than the Ingress's must say so in env.
+    */}}
+    {{- if and (eq $role "sync") $root.Values.ingress.enabled (not (hasKey $root.Values.env "APP_URL")) }}
+    - name: APP_URL
+      value: {{ printf "%s://%s" (ternary "https" "http" $root.Values.ingress.tls) $root.Values.ingress.host | quote }}
+    {{- end }}
     {{- range $key, $value := $root.Values.env }}
     - name: {{ $key }}
       value: {{ $value | quote }}
     {{- end }}
+  {{- /*
+  The Secret a role reads, per role: roles.<role>.existingSecret (or migrate.existingSecret) names a
+  narrower one than the release-wide existingSecret, so the migrate Job's schema-owning credential
+  need not sit on a web pod. Both unset is a render error, not a pod with no configuration.
+  */}}
   envFrom:
     - secretRef:
-        name: {{ $root.Values.existingSecret }}
+        name: {{ required (printf "no Secret for role %s — set existingSecret, or roles.%s.existingSecret, in your values" $role $role) (default $root.Values.existingSecret $cfg.existingSecret) }}
   {{- if or $cfg.port $scraped }}
   ports:
     {{- if $cfg.port }}
@@ -100,8 +116,10 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   {{/*
   Probes follow the role, because the roles do not agree on what they open. web and sync serve
   HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
-  listener is their only port — so they take liveness on it and NO readiness: nothing routes to
-  them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+  listener is their only port — so they take liveness on it. Readiness for replicator alone, on
+  /readyz of that listener: 503 while the replication stream is down, so the pod shows 0/1 instead
+  of a healthy pod feeding nothing. Their headless Service publishes not-ready addresses, so a
+  not-ready pod is still scraped.
 
   Every one of them takes a startupProbe too, because no listener opens early: the server builds
   the app's islands before any role binds a port, and a liveness probe counting from container
@@ -134,6 +152,11 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 5
     failureThreshold: 30
+  {{- if eq $role "replicator" }}
+  readinessProbe:
+    httpGet: { path: '/readyz?deep=1', port: metrics }
+    periodSeconds: 10
+  {{- end }}
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
@@ -194,8 +217,7 @@ spec:
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" $ | nindent 8 }}
 {{- end }}
 {{- end }}
 `;
@@ -219,6 +241,9 @@ spec:
   type: ClusterIP
   {{- if not $cfg.port }}
   clusterIP: None
+  # Scraped whether or not ready: a replicator whose stream is down (readiness 503) is the pod
+  # whose metrics matter most, and nothing routes to these addresses anyway.
+  publishNotReadyAddresses: true
   {{- end }}
   selector:
     app.kubernetes.io/instance: {{ $.Release.Name }}
@@ -267,8 +292,7 @@ spec:
       containers:
         {{- include "${app.kebab}.container" (dict "role" "migrate" "cfg" .Values.migrate "root" .) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" . | nindent 8 }}
 {{- end }}
 `;
 
@@ -382,5 +406,6 @@ export function helmTemplateFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'docker/helm/templates/migrate-job.yaml', contents: migrateJob(app) },
     { path: 'docker/helm/templates/ingress.yaml', contents: ingress(app) },
     { path: 'docker/helm/templates/hpa.yaml', contents: hpa(app) },
+    ...helmFenceFiles(app),
   ];
 }

package/src/templates/scaffold-helm.ts

@@ -31,11 +31,41 @@ image:
 
 # Non-secret configuration. Secrets come from an existing Secret, never from this file:
 #   kubectl create secret generic ${app.kebab}-secrets --from-literal=DATABASE_URL=...
+#
+# APP_URL — the pages' public origin — is what the sync node admits a websocket from. With the
+# ingress below enabled the chart SETS it on the sync role from ingress.host (https when
+# ingress.tls), because an undeclared node behind a TLS ingress also admits the plain-http page.
+# Set it here when the pages are served from another host or port than that (a CDN domain, a
+# SYNC_URL of its own): this value wins, and without it every websocket from those pages is
+# 403 X_SOCKET_ORIGIN_REFUSED.
 env:
   NODE_ENV: production
 
 existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, ULTIMATE_CURSOR_SECRET
 
+# The release-wide Secret above is every role's DEFAULT: \`existingSecret\` under a role
+# (roles.web.existingSecret, migrate.existingSecret) names that role's own, so the migrate Job's
+# schema-owning DATABASE_URL need not sit on a web pod.
+
+# The /tmp every pod mounts (the root filesystem is read-only), bounded: past this the kubelet
+# evicts the pod that filled it, never its neighbours for node disk pressure.
+tmp:
+  sizeLimit: 512Mi
+
+# One NetworkPolicy per serving role (templates/networkpolicy.yaml): \`http\` from httpFrom,
+# \`metrics\` from metricsFrom, nothing else. Inert on a CNI that does not enforce NetworkPolicy.
+#   httpFrom     empty = any source; narrow it to your ingress controller's namespace, e.g.
+#                [{ namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: ingress-nginx } } }]
+#   metricsFrom  default: any pod in the cluster and no address outside it
+#   egress       OFF while empty; a list turns on egress filtering with exactly those rules —
+#                the database, NATS, the object store and DNS are your addresses, so list all of them
+networkPolicy:
+  enabled: true
+  httpFrom: []
+  metricsFrom:
+    - namespaceSelector: {}
+  egress: []
+
 # The scrape listener every serving role opens, on its own port and never the app's: the ingress
 # routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
 # METRICS_PORT in the container; move one and the other follows.
@@ -153,7 +183,7 @@ ingress:
 `;
 
 /**
- * The chart for a new app: five kinds of object, all of them core Kubernetes. A ServiceMonitor and
+ * The chart for a new app: six kinds of object, all of them core Kubernetes. A ServiceMonitor and
  * a PodDisruptionBudget are deliberately absent — the first needs a CRD `helm install` fails on
  * where no Prometheus operator is installed, and both are cluster policy rather than app topology.
  */

package/src/templates/scaffold-repo.ts

@@ -41,6 +41,14 @@ const BIOME_VERSION = '2.5.8';
  */
 const TYPESCRIPT_VERSION = '^7.0.2';
 
+/**
+ * The Solid runtime every island and `@ultimat3/ui` component renders with, exact for the reason
+ * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.15`, and a scaffold
+ * that installed an older runtime than the compiler targets drifted as a buried literal (1.9.14
+ * beside the repository's 1.9.15). `scaffold-repo.test.ts` holds it equal to the root manifest's.
+ */
+const SOLID_VERSION = '1.9.15';
+
 // `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
 // (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor
 // BELOW the CLI the app then runs, so on a box with Bun 1.3.x `bun install` succeeded and the very
@@ -99,7 +107,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/schema": "^${version}",
     "@ultimat3/seo": "^${version}",
     "@ultimat3/ui": "^${version}",
-    "solid-js": "1.9.14"
+    "solid-js": "${SOLID_VERSION}"
   },
   "engines": {
     "bun": ">=${REQUIRED_BUN}"

package/src/templates/scaffold-shell.ts

@@ -272,17 +272,11 @@ const toggleIsland =
 // browser downloads. Named by SPECIFIER from the page, never by import:
 //   const ThemeSwitch = island({ src: '../../shared/theme-toggle.island.tsx', props: ['locale'] });
 //
-// The control itself is the catalog's \`ThemeToggle\`; this file is the runtime it needs and the
-// one decision the framework cannot make for it — see \`bootedEnv\` below.
+// The control itself is the catalog's \`ThemeToggle\`; this file is only the runtime it needs. It
+// reads the browser on its own: the theme the boot stamped on \`<html>\`, then \`theme.defaultMode\`
+// (stamped beside it), then the OS.
 
-import {
-  browserThemeEnv,
-  setSolidRuntime,
-  THEME_ATTRIBUTE,
-  type ThemeEnv,
-  ThemeToggle,
-  UiProvider,
-} from '@ultimat3/ui';
+import { setSolidRuntime, ThemeToggle, UiProvider } from '@ultimat3/ui';
 import {
   createContext,
   createEffect,
@@ -298,17 +292,6 @@ export interface ThemeToggleIslandProps {
   readonly locale: string;
 }
 
-/**
- * With no stored choice the catalog's \`resolveTheme\` asks the OS — but the document already wears
- * the theme the framework's boot script stamped from \`theme.defaultMode\` (dark, in this app), so
- * a toggle that asked the OS would show one theme while the page wore another. The boot's verdict
- * is on \`<html>\` before this runs: read it once, and let a stored choice win as it does there.
- */
-export const bootedEnv = (): ThemeEnv => {
-  const booted = document.documentElement.getAttribute(THEME_ATTRIBUTE) === 'dark';
-  return { ...browserThemeEnv(), prefersDark: () => booted };
-};
-
 /**
  * The one export the hydration runtime calls. \`setSolidRuntime\` comes FIRST and is not optional:
  * \`@ultimat3/ui\` imports types from solid-js and never a runtime, so the reactive graph a
@@ -318,12 +301,11 @@ export const bootedEnv = (): ThemeEnv => {
  */
 export function mount(el: HTMLElement, props: ThemeToggleIslandProps): void {
   setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
-  const env = bootedEnv();
   el.textContent = '';
   render(
     () => (
       <UiProvider locale={props.locale}>
-        <ThemeToggle mode="toggle" env={env} />
+        <ThemeToggle mode="toggle" />
       </UiProvider>
     ),
     el,
@@ -353,15 +335,13 @@ export const themeToggleStates = defineIslandStates({
 
 const toggleTest =
   (): string => `// The toggle the browser actually runs: built with the same \`buildIslands\` as \`x build\`, mounted
-// against a DOM small enough to read, and clicked. What it pins is the one decision this island
-// makes — the boot's verdict on \`<html>\` is what the control starts from, and a click writes the
-// key the boot script reads back on the next load.
+// against a DOM small enough to read, and clicked. What it pins: the boot's verdict on \`<html>\` is
+// what the control starts from, and a click writes the key the boot script reads back next load.
 
 import { join } from 'node:path';
 import { buildIslands } from '@ultimat3/cli';
 import { describeIslandState, expect, test } from '@ultimat3/testing';
-import { THEME_ATTRIBUTE, THEME_STORAGE_KEY } from '@ultimat3/ui';
-import { bootedEnv } from './theme-toggle.island';
+import { THEME_ATTRIBUTE, THEME_DEFAULT_ATTRIBUTE, THEME_STORAGE_KEY } from '@ultimat3/ui';
 import { themeToggleStates } from './theme-toggle.island.states';
 
 /** What the island reads through \`browserThemeEnv\`: storage and the OS query, both fakes. */
@@ -371,11 +351,19 @@ const localStorage = {
   setItem: (key: string, value: string): void => void stored.set(key, value),
   removeItem: (key: string): void => void stored.delete(key),
 };
+/** One OS query, shared by every \`matchMedia\` call: \`flipOs\` changes it and tells the listeners. */
+const os = { dark: false, listeners: new Set<() => void>() };
 const matchMedia = (): Record<string, unknown> => ({
-  matches: false,
-  addEventListener: () => {},
-  removeEventListener: () => {},
+  get matches(): boolean {
+    return os.dark;
+  },
+  addEventListener: (_type: string, listener: () => void) => void os.listeners.add(listener),
+  removeEventListener: (_type: string, listener: () => void) => void os.listeners.delete(listener),
 });
+const flipOs = (dark: boolean): void => {
+  os.dark = dark;
+  for (const listener of os.listeners) listener();
+};
 
 // The state \`x shot --island theme-toggle\` photographs is the state this mounts: one manifest,
 // so the picture and the assertion cannot be of two different components.
@@ -404,12 +392,27 @@ describeIslandState(themeToggleStates, 'default', island, (mounted) => {
     expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
   });
 
-  test('the env the island builds starts from the theme stamped on <html>', () => {
-    // The fake document is still installed here, so this reads exactly what \`mount\` read.
+  test('with nothing stored, a click flips the theme the boot stamped — not the OS', () => {
+    // The OS fake says light. The boot stamped this app's \`defaultMode\`, dark, so the visible
+    // theme is dark and the first click must go light; a toggle that asked the OS would write the
+    // dark already on screen and look dead.
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
     mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'dark');
-    expect(bootedEnv().prefersDark()).toBe(true);
-    mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'light');
-    expect(bootedEnv().prefersDark()).toBe(false);
+    expect(mounted().fire('button', 'click')).toBe(true);
+    expect(stored.get(THEME_STORAGE_KEY)).toBe('light');
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('light');
+  });
+
+  test("an OS flip is followed while nothing is stored and the app's default is 'system'", () => {
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'system');
+    flipOs(true);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
+    // A fixed default is the app's own opinion: the OS does not override it.
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
+    flipOs(false);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
   });
 });
 `;

package/src/test-counts.ts

@@ -5,6 +5,8 @@
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { parseBunTest } from './mcp-test-output';
+// One reader of bun's `N errors` line, shared with MCP `tests.run` — never a second regex.
+import { errorsIn } from './mcp-test-run';
 
 export interface TestCounts {
   /** Tests that executed — passed plus failed. A failed test is a test that ran. */
@@ -20,12 +22,6 @@ export interface TestCounts {
   readonly errors?: number;
 }
 
-/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
-const errorsIn = (output: string): number => {
-  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
-  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
-};
-
 /**
  * Summed across every process the step spawned, because a step is one line in the gate whether it
  * ran on one worker or eight.

package/src/test-ignores.ts

@@ -0,0 +1,25 @@
+// The ONE policy for which paths are never a test the gate runs here, projected twice: the path
+// predicate `discoverTests` filters by and the `--path-ignore-patterns` the serial steps pass to
+// `bun test`. A leaf, so `test-select.ts` and `verify-tests.ts` (which import each other) share it.
+
+/** Build output and installed packages: never a test, at ANY depth — a workspace's `dist/` too. */
+const IGNORED_ANYWHERE = ['dist', 'node_modules'] as const;
+
+/**
+ * Nested projects with their own gate (`examples/`, `dummy/`, run by
+ * `scripts/reference-app-gate.ts`) and the root `build/` — skipped AT THE ROOT only. Matched at any
+ * depth they swallowed an app's own slice: `x g resource build` lost 14 of its 16 test files and
+ * `x g resource example` its `examples/` page tests, from `x test` and the gate alike.
+ */
+const IGNORED_AT_ROOT = ['build', 'examples', 'dummy'] as const;
+
+/** Whether a root-relative POSIX path is excluded from every test selection. */
+export const isIgnoredTestPath = (path: string): boolean =>
+  IGNORED_ANYWHERE.some((dir) => `/${path}`.includes(`/${dir}/`)) ||
+  IGNORED_AT_ROOT.some((dir) => path.startsWith(`${dir}/`));
+
+/** The same policy as `bun test --path-ignore-patterns` globs, relative to the run's root. */
+export const IGNORED_TEST_PATTERNS: readonly string[] = [
+  ...IGNORED_ANYWHERE.map((dir) => `**/${dir}/**`),
+  ...IGNORED_AT_ROOT.map((dir) => `${dir}/**`),
+];

package/src/test-passes.ts

@@ -24,8 +24,6 @@ export interface PassInput {
   readonly workers: number;
   /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
   readonly type?: TestType;
-  /** Set for a `--worker I` rerun, which is one process by construction. */
-  readonly shard?: number;
 }
 
 const widthFor = (files: readonly TestFile[], workers: number): number =>
@@ -45,22 +43,9 @@ const widthFor = (files: readonly TestFile[], workers: number): number =>
  *
  * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
  * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
- *
- * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
- * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
- * different set of files from shard i of the run it reproduces.
  */
 export function testPasses(input: PassInput): readonly TestPass[] {
   const serialTypes = new Set<TestType>(SERIAL_TYPES);
-  if (input.shard !== undefined) {
-    return [
-      {
-        files: input.files,
-        workers: widthFor(input.files, input.workers),
-        ...(input.type === undefined ? {} : { type: input.type }),
-      },
-    ];
-  }
   const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
   const passes: TestPass[] = [];
   // Cheapest first, and the widest first: the pool run is most of the corpus and most of the

package/src/test-select.ts

@@ -9,6 +9,7 @@ import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { isIgnoredTestPath } from './test-ignores';
 import type { TestType } from './verify-tests';
 import { ownerOf, TEST_TYPES } from './verify-tests';
 
@@ -27,20 +28,10 @@ const TEST_GLOB = '**/*.test.{ts,tsx}';
 
 /**
  * The root `test` script's ignore list, kept identical so `x test` and `bun run test` see one
- * suite. `e2e/` is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is
- * a suite nobody runs until CI says so. `examples/` is, because the reference app is a separate
- * project with its own gate — `x verify` there, not `x test` here.
- *
- * `dummy/` and `build/` complete the list `verify-tests.ts` already excluded (`NEVER_A_TEST`). The
- * comment above claimed the two agreed and they did not: `x test unit` discovered 464 files where
- * the gate's `unit` step ran 441, so the gate's own test steps — which now select through this
- * function — would have started running a nested demo app's suite on the framework's gate.
- *
- * Both directories are gated where they belong, by `scripts/reference-app-gate.ts` running
- * `x verify` inside each app — see `NEVER_A_TEST` for why that is the only place they run.
+ * suite — `test-ignores.ts` holds it, and the serial steps' argv projects the same policy. `e2e/`
+ * is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is a suite nobody
+ * runs until CI says so.
  */
-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
@@ -58,7 +49,7 @@ export async function discoverTests(
   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 (isIgnoredTestPath(path)) 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 });