@ultimat3/cli 27.2.3 → 27.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.2.3",
+  "version": "27.4.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.2.3",
-    "@ultimat3/admin": "27.2.3",
-    "@ultimat3/ai": "27.2.3",
-    "@ultimat3/auth": "27.2.3",
-    "@ultimat3/cache": "27.2.3",
-    "@ultimat3/core": "27.2.3",
-    "@ultimat3/db": "27.2.3",
-    "@ultimat3/entity": "27.2.3",
-    "@ultimat3/flags": "27.2.3",
-    "@ultimat3/http": "27.2.3",
-    "@ultimat3/i18n": "27.2.3",
-    "@ultimat3/jobs": "27.2.3",
-    "@ultimat3/mail": "27.2.3",
-    "@ultimat3/manifest": "27.2.3",
-    "@ultimat3/mcp": "27.2.3",
-    "@ultimat3/money": "27.2.3",
-    "@ultimat3/notify": "27.2.3",
-    "@ultimat3/policy": "27.2.3",
-    "@ultimat3/pwa": "27.2.3",
-    "@ultimat3/query": "27.2.3",
-    "@ultimat3/realtime": "27.2.3",
-    "@ultimat3/render": "27.2.3",
-    "@ultimat3/schema": "27.2.3",
-    "@ultimat3/seo": "27.2.3",
-    "@ultimat3/storage": "27.2.3",
-    "@ultimat3/testing": "27.2.3",
-    "@ultimat3/time": "27.2.3",
+    "@ultimat3/action": "27.4.0",
+    "@ultimat3/admin": "27.4.0",
+    "@ultimat3/ai": "27.4.0",
+    "@ultimat3/auth": "27.4.0",
+    "@ultimat3/cache": "27.4.0",
+    "@ultimat3/core": "27.4.0",
+    "@ultimat3/db": "27.4.0",
+    "@ultimat3/entity": "27.4.0",
+    "@ultimat3/flags": "27.4.0",
+    "@ultimat3/http": "27.4.0",
+    "@ultimat3/i18n": "27.4.0",
+    "@ultimat3/jobs": "27.4.0",
+    "@ultimat3/mail": "27.4.0",
+    "@ultimat3/manifest": "27.4.0",
+    "@ultimat3/mcp": "27.4.0",
+    "@ultimat3/money": "27.4.0",
+    "@ultimat3/notify": "27.4.0",
+    "@ultimat3/policy": "27.4.0",
+    "@ultimat3/pwa": "27.4.0",
+    "@ultimat3/query": "27.4.0",
+    "@ultimat3/realtime": "27.4.0",
+    "@ultimat3/render": "27.4.0",
+    "@ultimat3/schema": "27.4.0",
+    "@ultimat3/seo": "27.4.0",
+    "@ultimat3/storage": "27.4.0",
+    "@ultimat3/testing": "27.4.0",
+    "@ultimat3/time": "27.4.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-config-load.ts

@@ -6,8 +6,7 @@
 // why: Bun exposes no path-join primitive, and the config path is app-root-relative.
 import { join } from 'node:path';
 import type { AppConfig, AppConfigInput } from '@ultimat3/core';
-import { ConfigInvalidError, defineConfig, describeValue } from '@ultimat3/core';
-import { APP_CONFIG_FILE } from './app-root';
+import { APP_CONFIG_FILE, ConfigInvalidError, defineConfig, describeValue } from '@ultimat3/core';
 
 /** The export every app declares. Named, never default — the CLI and the runtime both import it. */
 export const APP_CONFIG_EXPORT = 'config';

package/src/app-env.ts

@@ -5,9 +5,14 @@
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL, parseEnvKeys, pushWired } from '@ultimat3/core';
+import {
+  APP_CONFIG_FILE,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  parseEnvKeys,
+  pushWired,
+} from '@ultimat3/core';
 import { appConfigExport, loadAppConfig } from './app-config-load';
-import { APP_CONFIG_FILE } from './app-root';
 import type { AppSecretFacts } from './framework-env';
 import { appEnvExample, configOwes, FRAMEWORK_SECRETS } from './framework-env';
 import type { Finding } from './output';

package/src/app-layout.ts

@@ -0,0 +1,46 @@
+// The one feature layout, made a build error: a primitive module `actions.ts` (or `live`,
+// `queries`, `jobs`, `tasks`) beside the directory of the same name is refused. `x g` writes the
+// directory form — `<slice>/actions/<name>.ts`, one primitive per file — and an app that also keeps
+// `actions.ts` has two homes for one kind of thing, where `./actions` resolves to the file and never
+// the directory. A component module beside its folder (`ui.tsx` + `ui/`) is not a primitive's home,
+// and `x g resource` writes exactly that pair.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import type { Finding } from './output';
+
+/** The directories `x g` writes primitives into — the only names the refusal reads. */
+export const PRIMITIVE_DIRS: ReadonlySet<string> = new Set([
+  'actions',
+  'live',
+  'queries',
+  'jobs',
+  'tasks',
+]);
+
+const MODULE = /^(?<stem>.+)\.(?:ts|tsx)$/;
+
+/** Every primitive module `X.ts` among `files` beside a directory `X/` holding another of them. */
+export function siblingModuleFindings(files: readonly SourceFile[]): readonly Finding[] {
+  const directories = new Set<string>();
+  for (const { path } of files) {
+    const parts = path.split('/');
+    for (let depth = 1; depth < parts.length; depth += 1) {
+      directories.add(parts.slice(0, depth).join('/'));
+    }
+  }
+  return files.flatMap(({ path }): Finding[] => {
+    const stem = MODULE.exec(path)?.groups?.['stem'];
+    const name = stem?.split('/').at(-1) ?? '';
+    if (stem === undefined || !PRIMITIVE_DIRS.has(name) || !directories.has(stem)) return [];
+    return [
+      {
+        code: 'X_LAYOUT_SIBLING_MODULE',
+        cause: `${path} sits beside the directory ${stem}/ — \`./${name}\` resolves to the file, and the directory form is the one layout`,
+        fix: `x verify --only boundaries --json   # move each declaration in ${path} to ${stem}/<its-export-in-kebab-case>.ts, then delete ${path}`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      },
+    ];
+  });
+}

package/src/app-load.ts

@@ -6,6 +6,7 @@
 // Bun ships no `Bun.*` path API: `join`/`resolve` reach the files a scan imports.
 import { join, resolve } from 'node:path';
 import { isAction, isMutator, listActions, registerActions } from '@ultimat3/action';
+import { APP_CONFIG_FILE } from '@ultimat3/core';
 import { describeEntities, registeredEntities } from '@ultimat3/entity';
 import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import { appLocaleSet, UNDECLARED_LOCALES } from '@ultimat3/i18n/app-catalogs';
@@ -35,7 +36,7 @@ import {
   trackModule,
   trackStylesheets,
 } from './app-reload-graph';
-import { API_INDEX, APP_CONFIG_FILE } from './app-root';
+import { API_INDEX } from './app-root';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';

package/src/app-root.ts

@@ -1,12 +1,10 @@
 // Locating the app. `app.config.ts` is the one config file, so it is also the one root marker —
 // commands that need an app resolve it here and nowhere else, and the failure names the fix.
 
-import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
+import { APP_CONFIG_FILE, appDirOf } from '@ultimat3/core';
 import { BunVersionError, NotInAppError } from './errors';
 
-export const APP_CONFIG_FILE = 'app.config.ts';
-
 /**
  * The one file `defineApi` is called from in a scaffolded app — here, beside the config file, so
  * the module scan can import it first without pulling the generators into the serve graph.
@@ -46,18 +44,12 @@ export interface AppRoot {
   readonly manifestPath: string;
 }
 
-/** Walk up from `from` looking for `app.config.ts`. Returns undefined outside an app. */
+/** Walk up from `from` looking for `app.config.ts` (core's `appDirOf`). Undefined outside an app. */
 export function findAppRoot(from: string): AppRoot | undefined {
-  let dir = resolve(from);
-  for (;;) {
-    const configPath = join(dir, APP_CONFIG_FILE);
-    if (existsSync(configPath)) {
-      return { dir, configPath, manifestPath: join(dir, MANIFEST_FILE) };
-    }
-    const parent = dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
+  const dir = appDirOf(from);
+  return dir === undefined
+    ? undefined
+    : { dir, configPath: join(dir, APP_CONFIG_FILE), manifestPath: join(dir, MANIFEST_FILE) };
 }
 
 export function requireAppRoot(command: string, from: string): AppRoot {

package/src/boundary-findings.ts

@@ -5,6 +5,7 @@
 
 import type { SourceFile } from './app-boundaries';
 import { appImportGraph, checkImportRules, readAppSources } from './app-boundaries';
+import { siblingModuleFindings } from './app-layout';
 import { appTransportFindings } from './app-transport';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { Finding } from './output';
@@ -44,5 +45,6 @@ export async function appBoundaryFindings(
   return [
     ...withCutEdits(checkImportRules(files), appImportGraph(files)),
     ...(await appTransportFindings(root, files)),
+    ...siblingModuleFindings(files),
   ];
 }

package/src/cmd-clean-spec.ts

@@ -0,0 +1,13 @@
+// `x clean`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-clean.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const cleanSpec: CommandSpec = {
+  name: 'clean',
+  summary:
+    'remove what test runs leave behind: migrated test templates, .x/cache, stray .x folders, stale probe databases',
+  usage: 'x clean [--dry-run] [--json]',
+  requiresApp: true,
+  flags: [{ name: 'dry-run', type: 'boolean', summary: 'name what would go, remove nothing' }],
+};

package/src/cmd-clean.ts

@@ -0,0 +1,36 @@
+// `x clean` — every test leftover the framework knows of, cleared on demand (#738): the migrated
+// test-database templates under `.x/test-db`, the whole `.x/cache`, the `.x` folders a process
+// started in a source folder once wrote beside the code, and — with `TEST_DATABASE_URL` set — the
+// probe databases whose run is over. The test runner sweeps the same set before every run, keeping
+// the newest two of each cache (`test-housekeeping.ts`); this is the same sweep, keeping none.
+// Never touched: `.x/pgdata` (the dev database), `.x/storage`, the build output.
+
+import { requireAppRoot } from './app-root';
+import { cleanSpec } from './cmd-clean-spec';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool } from './parse';
+import { tidyTestState } from './test-housekeeping';
+
+export const cleanCommand: CliCommand = {
+  spec: cleanSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('clean', ctx.cwd).dir;
+    const dryRun = flagBool(ctx.args, 'dry-run');
+    const report = await tidyTestState({ root, mode: 'all', env: ctx.env, dryRun });
+    const count = report.paths.length + report.databases.length;
+    return {
+      ok: true,
+      command: 'clean',
+      summary:
+        count === 0
+          ? msg('cli.clean.nothing')
+          : msg(dryRun ? 'cli.clean.would' : 'cli.clean.removed', {
+              paths: report.paths.length,
+              databases: report.databases.length,
+            }),
+      data: { dryRun, paths: [...report.paths], databases: [...report.databases] },
+    };
+  },
+};

package/src/cmd-env-spec.ts

@@ -1,8 +1,8 @@
 // `x env`'s declaration, apart from its body: the parser, `x help` and the `errors` step
 // read it without loading `cmd-env.ts`, which `registry.ts` imports only when the command runs.
 
+import { APP_CONFIG_FILE } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT } from './app-env';
-import { APP_CONFIG_FILE } from './app-root';
 import type { CommandSpec } from './parse';
 
 export const envSpec: CommandSpec = {

package/src/doctor-offline.ts

@@ -3,10 +3,9 @@
 // `cmd-doctor.ts`'s job is the probe rather than the loading — the `db-backfill.ts` split, one
 // diagnostic over.
 
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { APP_CONFIG_FILE, ERROR_DOCS_URL } from '@ultimat3/core';
 import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
-import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { quoteArg } from './shell-quote';

package/src/error-codes.ts

@@ -232,6 +232,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_PACKAGE_TEST_ONLY_SHIPPED',
   'X_ISLAND_MODULE_DUPLICATED',
   'X_BACKFILL_SLICE_ENTITY',
+  'X_LAYOUT_SIBLING_MODULE',
 ] as const;
 
 /**
@@ -420,6 +421,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PACKAGE_TEST_ONLY_SHIPPED: 'a test-only module ships in the tarball',
   X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
   X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
+  X_LAYOUT_SIBLING_MODULE: 'a primitive module beside its directory',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/index.ts

@@ -162,6 +162,10 @@ export { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 export { eachSourceFile, isGenerated, isTest, SOURCE_GLOBS } from './source-files';
 export type { SkippedRoute, StaticReport } from './static-report';
 export { parseStaticReport } from './static-report';
+export type { MigratedDatabaseOptions } from './test-database';
+export { migratedDatabase, migratedTemplate } from './test-database';
+export type { HousekeepingOptions, HousekeepingReport } from './test-housekeeping';
+export { tidyTestState } from './test-housekeeping';
 export { filesIn, testArgs } from './test-shards';
 export { defaultWorkers } from './test-workers';
 export { scanCodeDeclarations, scanCodeFixSites, scanCodes } from './ts-scan';

package/src/manifest-staleness.ts

@@ -6,11 +6,10 @@
 import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join primitive; Bun.file takes a path already joined.
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { APP_CONFIG_FILE, ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
-import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 

package/src/mcp-errors.ts

@@ -302,6 +302,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'gh issue create --repo developerz-ai/ultimate --title "X_ISLAND_MODULE_DUPLICATED"   # paste this error\'s --json as the body: the framework bundled one of its own modules twice',
   X_BACKFILL_SLICE_ENTITY:
     'x errors explain X_BACKFILL_SLICE_ENTITY --json   # the refusal itself names the x g job line for this slice',
+  X_LAYOUT_SIBLING_MODULE:
+    'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -341,6 +341,10 @@ const CATALOG = {
     'coverage: this shard measured its own slice — x verify merge folds every shard and judges the floor',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
+  'cli.clean.nothing': 'nothing to clean: no test leftovers under this app',
+  'cli.clean.removed': 'removed {paths} path(s) and {databases} probe database(s)',
+  'cli.clean.would':
+    'would remove {paths} path(s) and {databases} probe database(s) — --dry-run removed nothing',
   'cli.env.checked': '{count} declared variable(s), all present and valid',
   'cli.env.invalid': '{count} of {total} declared variable(s) missing or malformed',
   'cli.env.wrote': 'wrote {path} — {count} declared variable(s)',

package/src/registry.ts

@@ -10,6 +10,7 @@ import { affectedSpec } from './cmd-affected-spec';
 import { authSpec } from './cmd-auth-spec';
 import { buildSpec } from './cmd-build-spec';
 import { ciSpec } from './cmd-ci-spec';
+import { cleanSpec } from './cmd-clean-spec';
 import { dbSpec } from './cmd-db-spec';
 import { deploySpec } from './cmd-deploy-spec';
 import { devSpec } from './cmd-dev-spec';
@@ -89,6 +90,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
   lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
   lazy(vapidSpec, async () => (await import('./cmd-vapid')).vapidCommand),
+  lazy(cleanSpec, async () => (await import('./cmd-clean')).cleanCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/test-database.ts

@@ -0,0 +1,133 @@
+// Single responsibility: the app's migrated test database — a fresh embedded Postgres holding the
+// framework schema (`x_jobs`, `x_users`, …) and every app migration, exactly what `x db migrate`
+// and `x dev` apply, so a test exercises the schema production runs and never a hand copy of it.
+//
+// Booted from a cached TEMPLATE: the migrated data directory, dumped once per (PGlite, framework
+// schema, migrations) and kept under the APP ROOT's `.x/test-db` (`test-db-template.ts`). A fresh
+// in-memory PGlite runs initdb (~4 s) and then every migration in every test file; restoring the
+// dump is ~0.5 s. A changed migration is a different key, so a stale template is never loaded, and
+// writing the new one evicts the old ones (#738). An app's hand-rolled copy of this kept them all.
+//
+// Per-test data hygiene is `reusableDatabase` (`@ultimat3/testing`): one database per test worker,
+// its data put back to this template's before every file. The wiki's Testing page is the recipe.
+
+import { appDirOf, assert } from '@ultimat3/core';
+import {
+  migrate,
+  PGLITE_PACKAGE,
+  type PgliteClient,
+  type PgliteModule,
+  pgliteClient,
+  pgliteVersion,
+  raw,
+} from '@ultimat3/db';
+import { applyFrameworkSchema, FRAMEWORK_SCHEMA } from './framework-schema';
+import { readMigrations } from './migrations';
+import { readTemplate, templateKey, templatePath, writeTemplate } from './test-db-template';
+
+export interface MigratedDatabaseOptions {
+  /** The app root, or any folder inside the app: the template lives under the root's `.x/`. */
+  readonly root: string;
+  /** A directory to put the database ON DISK instead of in memory (an empty one), for a test whose second process opens it. */
+  readonly dataDir?: string | undefined;
+  /** Extensions a migration creates (`citext`): PGlite links one only when told at boot. */
+  readonly extensions?: readonly string[] | undefined;
+}
+
+interface DumpablePglite {
+  dumpDataDir(compression?: 'none'): Promise<Blob>;
+}
+
+type PgliteClass = PgliteModule['PGlite'];
+
+/** Held in a variable, as `@ultimat3/db` holds it: a literal would make `tsc` resolve an optional peer. */
+const importPglite = async (): Promise<PgliteClass> =>
+  ((await import(PGLITE_PACKAGE)) as unknown as PgliteModule).PGlite;
+
+/** One template per key for the life of the process: the second file in a worker reads no disk. */
+const held = new Map<string, Blob>();
+
+/** Bumped when how a template is BUILT changes, so a template built the old way is rebuilt. */
+const TEMPLATE_RECIPE = 'framework-schema+migrations+checkpoint:1';
+
+async function buildTemplate(
+  PGlite: PgliteClass,
+  root: string,
+  extensions: readonly string[] | undefined,
+): Promise<Blob> {
+  // Built through the framework's own loader (its parsers, its extension linking), with the
+  // instance captured so its data directory can be dumped once the schema is in.
+  let driver: DumpablePglite | undefined;
+  const Capturing = class extends (PGlite as unknown as new (...args: unknown[]) => object) {
+    constructor(...args: unknown[]) {
+      super(...args);
+      driver = this as unknown as DumpablePglite;
+    }
+  } as unknown as PgliteClass;
+  const client = pgliteClient({
+    load: async () => ({ PGlite: Capturing }),
+    ...(extensions === undefined ? {} : { extensions }),
+  });
+  try {
+    await applyFrameworkSchema((statement) => client.execute(raw(statement)));
+    await migrate({ migrations: await readMigrations(root), client, lock: false });
+    // Without a checkpoint every boot from the template replays the migrations' WAL as crash
+    // recovery (~130 ms of each ~600 ms boot, measured on notificado.co).
+    await client.execute(raw('CHECKPOINT'));
+    const captured = driver as DumpablePglite | undefined;
+    assert(
+      captured !== undefined,
+      'the migrated test template ran its schema, and no PGlite instance was constructed to dump',
+      'report it: pgliteClient booted a driver this module did not hand it',
+    );
+    return await captured.dumpDataDir('none');
+  } finally {
+    await client.close();
+  }
+}
+
+/** The migrated template for the app `root` is in: from memory, from `.x/test-db`, or built now. */
+export async function migratedTemplate(options: MigratedDatabaseOptions): Promise<Blob> {
+  const PGlite = await importPglite();
+  // The migrations are read from the app ROOT whichever folder the caller named.
+  const root = appDirOf(options.root) ?? options.root;
+  const key = templateKey([
+    (await pgliteVersion()) ?? 'unknown',
+    JSON.stringify(FRAMEWORK_SCHEMA),
+    JSON.stringify(await readMigrations(root)),
+    JSON.stringify(options.extensions ?? []),
+    TEMPLATE_RECIPE,
+  ]);
+  const memo = held.get(key);
+  if (memo !== undefined) return memo;
+  const path = templatePath(root, key);
+  const template =
+    (await readTemplate(path)) ??
+    (await (async () => {
+      const built = await buildTemplate(PGlite, root, options.extensions);
+      await writeTemplate(path, built);
+      return built;
+    })());
+  held.set(key, template);
+  return template;
+}
+
+/**
+ * A fresh database with the framework schema and every migration applied, booted from the cached
+ * template. The caller owns it: `close()` when done. It is not installed as `db()` — the recipe
+ * (`reusableDatabase` + `setDbClient`) does that.
+ */
+export async function migratedDatabase(options: MigratedDatabaseOptions): Promise<PgliteClient> {
+  const PGlite = await importPglite();
+  const template = await migratedTemplate(options);
+  const FromTemplate = class extends (PGlite as unknown as new (...args: unknown[]) => object) {
+    constructor(dataDir?: unknown, init?: Record<string, unknown>) {
+      super(dataDir, { ...init, loadDataDir: template });
+    }
+  } as unknown as PgliteClass;
+  return pgliteClient({
+    ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+    ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
+    load: async () => ({ PGlite: FromTemplate }),
+  });
+}

package/src/test-db-template.ts

@@ -0,0 +1,64 @@
+// Single responsibility: where the app's migrated test-database templates live and how one is read
+// and written. A template is a PGlite data directory dumped after the framework schema and every
+// migration ran (`test-database.ts` builds it), keyed by everything that went into it, under the
+// APP ROOT's `.x/test-db` — never the cwd's.
+//
+// Writing a new key evicts the old ones (#738): nothing did, and an app's `.x/test-db` held one
+// ~60 MB file per migration state it ever had — 72, 4.2 GB. The newest previous one stays, since a
+// second run still on the old migrations may be reading it. No lock is needed: a template is read
+// in ONE read, a missing one is a miss, and a write is a temp name renamed into place.
+
+// why: Bun has no mkdir, rename or remove.
+import { mkdir, rename, rm } from 'node:fs/promises';
+// why: Bun ships no path joiner.
+import { basename, dirname } from 'node:path';
+import { appStatePath, evictCacheFiles } from '@ultimat3/core';
+
+/** `.x/<this>` under the app root. */
+export const TEST_DB_DIR = 'test-db';
+
+const TEMPLATE = /^pglite-[0-9a-f]{16}\.tar$/;
+const PARTIAL = /^pglite-[0-9a-f]{16}\.tar\..+\.partial$/;
+
+/** Sixteen hex characters over every input, each length-prefixed so `ab|c` and `a|bc` differ. */
+export function templateKey(parts: readonly string[]): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const part of parts) hasher.update(`${String(part.length)}:${part}`);
+  return hasher.digest('hex').slice(0, 16);
+}
+
+/** `<app root>/.x/test-db/pglite-<key>.tar`, for a process started anywhere inside the app. */
+export const templatePath = (from: string, key: string): string =>
+  appStatePath(from, TEST_DB_DIR, `pglite-${key}.tar`);
+
+/** The whole template in memory, or `undefined` for one that is absent or vanished mid-read. */
+export async function readTemplate(path: string): Promise<Blob | undefined> {
+  try {
+    return new Blob([await Bun.file(path).arrayBuffer()]);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Atomic: several workers may build the same template at once, each renames its own temp file into
+ * place, and a reader sees a whole template or none. Then the eviction. Best effort throughout: a
+ * template that cannot be written costs the next file a rebuild, which is what it cost before.
+ */
+export async function writeTemplate(path: string, template: Blob): Promise<void> {
+  const partial = `${path}.${String(process.pid)}.${crypto.randomUUID()}.partial`;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await Bun.write(partial, template);
+    await rename(partial, path);
+  } catch {
+    await rm(partial, { force: true }).catch(() => undefined);
+    return;
+  }
+  await evictCacheFiles({
+    dir: dirname(path),
+    current: basename(path),
+    matches: (name) => TEMPLATE.test(name),
+    temporary: (name) => PARTIAL.test(name),
+  });
+}

package/src/test-housekeeping.ts

@@ -0,0 +1,197 @@
+// Single responsibility: what a test run leaves behind, swept — the framework's DatabaseCleaner and
+// `tmp:clear` in one place, so an app never accumulates it (#738: one app held 72 migrated
+// templates, 4.2 GB, and `.x/cache` folders beside its source). Two callers, one rule:
+//
+// - the test runner, before every run (`'auto'`): the two newest templates and PGlite snapshots
+//   stay — the current state and the one a second checkout or an older branch may be reading;
+// - `x clean` (`'all'`): every template and the whole `.x/cache`, on demand, `--dry-run` to look.
+//
+// Both remove the `.x` debris a process started in a source folder used to write beside the code,
+// and with `TEST_DATABASE_URL` set, every probe database whose run is provably over. What a
+// developer works in is never touched: `.x/pgdata` (the dev database), `.x/storage`, the build.
+
+// why: Bun has no readdir, rmdir or recursive remove.
+import { readdir, rm, rmdir } from 'node:fs/promises';
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import type { PgExecutor, ProbeDatabaseSweepOptions } from '@ultimat3/core';
+import {
+  APP_CONFIG_FILE,
+  APP_STATE_DIR,
+  appDirOf,
+  evictCacheFiles,
+  sweepStaleProbeDatabases,
+} from '@ultimat3/core';
+import { dbExecutor, postgresClient } from '@ultimat3/db';
+import { TEST_DB_DIR } from './test-db-template';
+
+export type HousekeepingMode = 'auto' | 'all';
+
+export interface ProbeServer {
+  readonly executor: PgExecutor;
+  close(): Promise<void>;
+}
+
+export interface HousekeepingOptions extends ProbeDatabaseSweepOptions {
+  /** The app root, or any folder in it. */
+  readonly root: string;
+  readonly mode: HousekeepingMode;
+  /** Name what would go and remove nothing. */
+  readonly dryRun?: boolean;
+  /** Where `TEST_DATABASE_URL` is read; without it no database is swept and nothing connects. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Seam: how the probe server is reached. Defaults to a one-connection pool. */
+  readonly connect?: (url: string) => Promise<ProbeServer>;
+}
+
+export interface HousekeepingReport {
+  /** Every file and directory removed (or, dry, that would be). */
+  readonly paths: readonly string[];
+  /** Every probe database dropped (or, dry, that would be). */
+  readonly databases: readonly string[];
+}
+
+/** Entries of each cache an `'auto'` sweep keeps: the current state and the newest previous one. */
+const AUTO_KEEP = 2;
+
+const TEMPLATE = /^pglite-[0-9a-f]{16}\.tar$/;
+const TEMPLATE_PARTIAL = /^pglite-[0-9a-f]{16}\.tar\..+\.partial$/;
+const SNAPSHOT = /^pglite-.+\.snapshot$/;
+const SNAPSHOT_TEMP = /^pglite-.+\.snapshot\..+\.tmp$/;
+
+/** Folders a walk for stray `.x` never enters: dependencies, history, and the app's own state. */
+const NEVER_WALKED = new Set(['node_modules', '.git', APP_STATE_DIR]);
+
+/** The bound on a probe server that does not answer: housekeeping never holds a run up. */
+const CONNECT_BUDGET_MS = 5_000;
+
+const defaultConnect = async (url: string): Promise<ProbeServer> => {
+  const client = postgresClient({ url, role: 'web', profile: { max: 1 } });
+  return { executor: dbExecutor(() => client), close: () => client.close() };
+};
+
+/**
+ * `.x` folders below `root` that are not an app's own: the cache a process started in a source
+ * folder wrote beside the code. A folder holding its own `app.config.ts` is another app, whose
+ * `.x` is its own, and is not walked into.
+ */
+async function strayStateDirs(root: string): Promise<readonly string[]> {
+  const found: string[] = [];
+  const walk = async (dir: string, top: boolean): Promise<void> => {
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    if (!top && entries.some((entry) => entry.isFile() && entry.name === APP_CONFIG_FILE)) return;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === APP_STATE_DIR && !top) found.push(join(dir, entry.name));
+      if (NEVER_WALKED.has(entry.name)) continue;
+      await walk(join(dir, entry.name), false);
+    }
+  };
+  await walk(root, true);
+  return found;
+}
+
+/** The stray `.x`'s `cache` goes — the only thing the bug wrote — and the `.x` itself once empty. */
+async function sweepStray(dir: string, dryRun: boolean): Promise<readonly string[]> {
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  const onlyCache = entries.every((name) => name === 'cache');
+  const removed = onlyCache ? [dir] : entries.includes('cache') ? [join(dir, 'cache')] : [];
+  if (!dryRun) {
+    for (const path of removed) await rm(path, { recursive: true, force: true });
+    if (!onlyCache) await rmdir(dir).catch(() => undefined);
+  }
+  return removed;
+}
+
+async function sweepDatabases(options: HousekeepingOptions): Promise<readonly string[]> {
+  const url = options.env['TEST_DATABASE_URL'];
+  if (url === undefined || url.trim().length === 0) return [];
+  let server: ProbeServer | undefined;
+  try {
+    server = await (options.connect ?? defaultConnect)(url);
+    const connected = server;
+    const swept = sweepStaleProbeDatabases(connected.executor, {
+      ...(options.isAlive === undefined ? {} : { isAlive: options.isAlive }),
+      ...(options.now === undefined ? {} : { now: options.now }),
+      dryRun: options.dryRun === true,
+    });
+    const late = Bun.sleep(CONNECT_BUDGET_MS).then(() => [] as readonly string[]);
+    return await Promise.race([swept, late]);
+  } catch {
+    // Best effort: an unreachable server costs the sweep its databases, never the test run.
+    return [];
+  } finally {
+    await server?.close().catch(() => undefined);
+  }
+}
+
+/** Sweep what tests leave behind under the app containing `options.root`. */
+export async function tidyTestState(options: HousekeepingOptions): Promise<HousekeepingReport> {
+  const app = appDirOf(options.root);
+  const root = app ?? options.root;
+  const state = join(root, APP_STATE_DIR);
+  const dryRun = options.dryRun === true;
+  const keep = options.mode === 'all' ? 0 : AUTO_KEEP;
+  const paths: string[] = [
+    ...(await evictCacheFiles({
+      dir: join(state, TEST_DB_DIR),
+      current: undefined,
+      keepPrevious: keep,
+      matches: (name) => TEMPLATE.test(name),
+      temporary: (name) => TEMPLATE_PARTIAL.test(name),
+      dryRun,
+    })),
+  ];
+  if (options.mode === 'all') {
+    const cache = join(state, 'cache');
+    if ((await readdir(cache).catch(() => undefined)) !== undefined) {
+      paths.push(cache);
+      if (!dryRun) await rm(cache, { recursive: true, force: true });
+    }
+  } else {
+    paths.push(
+      ...(await evictCacheFiles({
+        dir: join(state, 'cache'),
+        current: undefined,
+        keepPrevious: keep,
+        matches: (name) => SNAPSHOT.test(name),
+        temporary: (name) => SNAPSHOT_TEMP.test(name),
+        dryRun,
+      })),
+    );
+  }
+  // Only inside an app: outside one (a package's own folder) a `.x` below is that folder's state.
+  if (app !== undefined) {
+    for (const stray of await strayStateDirs(root))
+      paths.push(...(await sweepStray(stray, dryRun)));
+  }
+  return { paths, databases: await sweepDatabases(options) };
+}
+
+/** Roots this process already swept: `x verify` runs several test steps, and one sweep serves all. */
+const swept = new Set<string>();
+
+/**
+ * The test runner's call, before it spawns `bun test` (`x test`, and every test step of `x verify`):
+ * the `'auto'` sweep, once per app per process. Never a reason for a run to fail — housekeeping
+ * that throws is logged nowhere and costs nothing but the leftovers it did not remove.
+ */
+export async function tidyBeforeTestRun(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  tidy: (options: HousekeepingOptions) => Promise<HousekeepingReport> = tidyTestState,
+): Promise<void> {
+  const key = appDirOf(root) ?? root;
+  if (swept.has(key)) return;
+  swept.add(key);
+  try {
+    await tidy({ root: key, mode: 'auto', env });
+  } catch {
+    // Best effort, by design: see above.
+  }
+}

package/src/test-shards.ts

@@ -56,6 +56,7 @@ import { testEnvOverrides } from './test-dotenv';
 export const TEST_TIMINGS_FILE = '.x/test-timings.json';
 
 import { runBatches, testBatches } from './test-batches';
+import { tidyBeforeTestRun } from './test-housekeeping';
 import { testPasses } from './test-passes';
 import type { TestFile } from './test-select';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
@@ -265,6 +266,8 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     workers: options.workers,
     ...(options.type === undefined ? {} : { type: options.type }),
   });
+  // What earlier runs left behind, swept before this one adds to it (#738).
+  await tidyBeforeTestRun(options.root, options.env ?? Bun.env);
   const started = performance.now();
   const steps: StepResult[] = [];
   const spent: JsonValue[] = [];

package/src/verify-checks.ts

@@ -4,7 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { APP_CONFIG_FILE, ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import { AGENTS_MD_FILENAME, MANIFEST_FILENAME, verifyContract } from '@ultimat3/manifest';
 import type { MetaIssue } from '@ultimat3/seo';
@@ -14,7 +14,6 @@ import { readAppSources } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
 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';

package/src/verify-merge.ts

@@ -16,8 +16,7 @@
 import { existsSync } from 'node:fs';
 // why: Bun ships no path-join primitive.
 import { join } from 'node:path';
-import { ERROR_DOCS_URL, renderThrowable, UltimateError } from '@ultimat3/core';
-import { APP_CONFIG_FILE } from './app-root';
+import { APP_CONFIG_FILE, ERROR_DOCS_URL, renderThrowable, UltimateError } from '@ultimat3/core';
 import { judgeCoverage } from './coverage-floor';
 import type { CoverageMap } from './coverage-lcov';
 import { decodeCoverage, mergeCoverage } from './coverage-lcov';

package/src/verify-test-run.ts

@@ -10,6 +10,7 @@ import type { Finding } from './output';
 import { runBatches, testBatches } from './test-batches';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
+import { tidyBeforeTestRun } from './test-housekeeping';
 import type { TestFile } from './test-select';
 import { failureOf, TEST_TIMINGS_FILE, testArgs } from './test-shards';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
@@ -63,6 +64,8 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
     workers,
     options.isolate === true ? BATCH_FILES_PER_WORKER : SHARED_BATCH_FILES_PER_WORKER,
   );
+  // What earlier runs left behind, swept before this one adds to it (#738).
+  await tidyBeforeTestRun(options.root, options.env ?? Bun.env);
   const result = await runBatches({
     runner: options.runner,
     batches,

package/src/verify-tests.ts

@@ -10,10 +10,10 @@
 // and `join` builds the host-separator path to its config file.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { APP_CONFIG_FILE } from '@ultimat3/core';
 import type { TestType } from '@ultimat3/testing';
 import { TEST_TYPES } from '@ultimat3/testing';
 import { checkEvalBaselines, checkEvalCoverage, checkEvalRecording } from './app-evals';
-import { APP_CONFIG_FILE } from './app-root';
 import { judgeCoverage } from './coverage-floor';
 import { msg } from './messages';
 import { countsOf } from './test-counts';