@jterrazz/test 14.0.0 → 14.1.0

package/README.md

@@ -6,7 +6,7 @@ Declarative testing framework for APIs, jobs, CLIs, websites, and mobile apps. F
 npm install -D @jterrazz/test vitest
 ```
 
-Everything imports from `@jterrazz/test` — the one exception is the tool-facing `@jterrazz/test/oxlint` subpath (the zero-runtime lint plugin and its config fragment), which never loads any test runtime.
+Everything a spec needs imports from `@jterrazz/test`. The exceptions are the two TOOL subpaths, which no spec ever imports: `@jterrazz/test/oxlint` (the zero-runtime lint plugin and its config fragment, loading no test runtime) and `@jterrazz/test/vitest` (what `vitest.config.ts` imports — the `defineSpecConfig()` preset and the `literate()` plugin).
 
 ## Quick start
 
@@ -172,7 +172,9 @@ Resolution: `options.mode` > `TEST_MODE` env var > `'node'`. Only `.api()` has a
 
 ```typescript
 // vitest.config.ts — the mode switch lives HERE
-export default defineConfig({
+import { defineSpecConfig } from '@jterrazz/test/vitest';
+
+export default defineSpecConfig({
     test: {
         projects: [
             { test: { name: 'http', include: ['specs/api/**/*.test.ts'] } },
@@ -262,6 +264,30 @@ The handle destructures to `{ mobile, cleanup, udid }` (plus `backendUrl` with `
 
 When `root` is absent, the framework walks up from the specification file to the **nearest** directory carrying `package.json` or `docker/compose.test.yaml`. In a workspace that is the member being tested, not the repository root above it. Pass `root` only when the convention does not fit. `root` is strictly the **project root** (compose detection + local-bin resolution, or the cwd of a `specification.website()` server command) — it is not a fixtures root; `.fixture()` resolves its own paths.
 
+## vitest config — `defineSpecConfig()`
+
+`@jterrazz/test/vitest` is the subpath `vitest.config.ts` imports, never a spec. Beside `literate()` it exports the shared preset: what you pass is a plain vite/vitest config merged **over** its defaults, and `literate:` adds the plugin.
+
+```typescript
+import { defineSpecConfig } from '@jterrazz/test/vitest';
+
+export default defineSpecConfig({
+    literate: { specification: './specs/cli/cli.specification.ts' },
+    test: { include: ['specs/**/*.test.ts'] },
+});
+```
+
+| Sets                               | To                                                     |
+| ---------------------------------- | ------------------------------------------------------ |
+| `cacheDir`                         | `.artifacts/vitest`                                    |
+| `test.coverage.reportsDirectory`   | `.artifacts/vitest/coverage` (bring your own provider) |
+| `test.testTimeout` / `hookTimeout` | `30_000`                                               |
+| `test.exclude`                     | vitest's defaults **+** `**/_fixtures/**`              |
+
+Nothing else: `fileParallelism`, `reporters`, `environment` and every `include` stay yours. Inline `projects` inherit the same defaults (vitest gives a project nothing from the root), arrays are concatenated rather than replaced, and scalars you state win. Full walkthrough, including migrating a hand-rolled config: [docs/01-getting-started.md](docs/01-getting-started.md#vitest-config-the-preset).
+
+Every artefact a run produces lands under `.artifacts/<tool>/` — one `.gitignore` line, one `rm -rf`. Per-run scratch (a CLI spec's temp cwd, a browser profile) stays in the OS temp dir.
+
 ## Builder API
 
 ### Setup (chainable)
@@ -412,10 +438,12 @@ test('deploy spawns a labelled container', async () => {
 | ------------ | -------------------------------- | ------------------------------------- |
 | `postgres()` | `composeService`, `image`, `env` | `postgresql://user:pass@host:port/db` |
 | `redis()`    | `composeService`, `image`        | `redis://host:port`                   |
-| `sqlite()`   | `init` or `prismaSchema`         | `file:/tmp/....sqlite`                |
+| `sqlite()`   | `init` or `prismaSchema`         | `file:/…/….sqlite`                    |
 
 `docker/compose.test.yaml` is the single source of truth for test infrastructure; `docker/<service>/init.sql` runs when the corresponding service starts. Parallel isolation is automatic per vitest worker: postgres clones a schema, redis assigns a database index, sqlite copies the template file, compose mode gets a dedicated project.
 
+`sqlite()` caches its schema template inside the project — `.artifacts/vitest/sqlite/template-<key>.sqlite` — so two checkouts never share one, and workers racing for a cold cache wait for the one that is building rather than all building at once. Details: [docs/08-services.md](docs/08-services.md#where-the-template-lives).
+
 ## Mocking utilities
 
 ```typescript

package/dist/{literate.js → artifacts.js}

@@ -1547,7 +1547,11 @@ function atLine(error, filePath, line) {
 	error.stack = `${error.name}: ${error.message}\n    at ${filePath}:${line}:1`;
 	return error;
 }
-/** Compare one run against what the command actually did. */
+/**
+* Compare one run against what the command actually did — its exit code, its
+* streams and its `files:`, all read at the same instant: the moment that
+* command returned.
+*/
 function assertRun(document, outcome, context, workDir, scope) {
 	const { actual, run } = outcome;
 	if (actual.exitCode !== run.exitCode) throw failure(document, run, context, [[
@@ -1682,9 +1686,9 @@ async function runSpecDocument(options) {
 		...servers.env,
 		...documentEnv(document, config, displayPath)
 	}, workDir);
-	let outcomes;
+	const rewriting = shouldUpdateSnapshots() && options.frozen !== true;
+	const outcomes = [];
 	try {
-		outcomes = [];
 		for (const run of document.runs) {
 			const actual = run.waitFor === null ? await config.command.exec(run.command, workDir, env, {
 				stdin: run.stdin ?? void 0,
@@ -1693,21 +1697,22 @@ async function runSpecDocument(options) {
 				timeout: run.timeout ?? void 0,
 				waitFor: run.waitFor
 			}, env);
-			outcomes.push({
+			const outcome = {
 				actual,
 				run,
 				stderr: comparable(actual.stderr, config.transform),
 				stdout: comparable(actual.stdout, config.transform)
-			});
+			};
+			outcomes.push(outcome);
+			if (!rewriting) assertRun(document, outcome, {
+				displayPath,
+				filePath
+			}, workDir, scope);
 		}
 	} finally {
 		await servers.stop();
 	}
-	if (shouldUpdateSnapshots() && options.frozen !== true) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
-	else for (const outcome of outcomes) assertRun(document, outcome, {
-		displayPath,
-		filePath
-	}, workDir, scope);
+	if (rewriting) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
 	return new CliResult({
 		commandOutput: outcomes.at(-1).actual,
 		config,
@@ -1722,5 +1727,11 @@ async function runSpecDocument(options) {
 function specDescription(content, displayPath) {
 	return readSpecFile(content, displayPath).document.description;
 }
+/** Everything a vitest run generates. */
+const VITEST_ARTIFACTS_DIR = `.artifacts/vitest`;
+/** Where the coverage provider writes its report. */
+const COVERAGE_DIR = `${VITEST_ARTIFACTS_DIR}/coverage`;
+/** Where `sqlite()` caches the schema template it copies per worker. */
+const SQLITE_TEMPLATE_DIR = `${VITEST_ARTIFACTS_DIR}/sqlite`;
 //#endregion
-export { placeholderPatternSource as A, formatResponseDiff as C, hasPlaceholders as D, formatTableDiff as E, structuralEquals as M, structuralSubset as N, mergePreservingPlaceholders as O, textEquals as P, formatDirectoryDiff as S, formatStdoutDiff as T, getCallerDir as _, shouldUpdateSnapshots as a, diffDirectories as b, BaseResult as c, inspectContainer as d, removeContainers as f, text as g, TextAccessor as h, UPDATE_HINT as i, renderExpected as j, mergeTextPreservingPlaceholders as k, validateDatabaseOption as l, JsonAccessor as m, specDescription as n, ContainerAccessor as o, TableAccessor as p, ServeAdapter as r, CliResult as s, runSpecDocument as t, findContainersByLabel as u, FilesystemAccessor as v, formatStartupReport as w, walkDirectory as x, DirectoryAccessor as y };
+export { hasPlaceholders as A, diffDirectories as C, formatStartupReport as D, formatResponseDiff as E, structuralEquals as F, structuralSubset as I, textEquals as L, mergeTextPreservingPlaceholders as M, placeholderPatternSource as N, formatStdoutDiff as O, renderExpected as P, DirectoryAccessor as S, formatDirectoryDiff as T, JsonAccessor as _, specDescription as a, getCallerDir as b, shouldUpdateSnapshots as c, BaseResult as d, validateDatabaseOption as f, TableAccessor as g, removeContainers as h, runSpecDocument as i, mergePreservingPlaceholders as j, formatTableDiff as k, ContainerAccessor as l, inspectContainer as m, SQLITE_TEMPLATE_DIR as n, ServeAdapter as o, findContainersByLabel as p, VITEST_ARTIFACTS_DIR as r, UPDATE_HINT as s, COVERAGE_DIR as t, CliResult as u, TextAccessor as v, walkDirectory as w, FilesystemAccessor as x, text as y };

package/dist/index.d.ts

@@ -876,8 +876,17 @@ interface ServiceHandle {
   createDatabaseAdapter: () => DatabasePort | null;
   /** Verify the service is ready and accepting connections. Throws with context if not. */
   healthcheck: () => Promise<void>;
-  /** Run initialization scripts (e.g., init.sql). Throws with SQL error context if it fails. */
-  initialize: (composeDir: string) => Promise<void>;
+  /**
+   * Run initialization scripts (e.g., init.sql). Throws with SQL error
+   * context if it fails.
+   *
+   * `composeDir` is where the compose file lives — where a service reads its
+   * `init.sql` from. `root` is the project root the specification resolved
+   * (A9), handed down so a service that CACHES something writes it under the
+   * project's own `.artifacts/`, never in a machine-global directory two
+   * checkouts would share.
+   */
+  initialize: (composeDir: string, root: string) => Promise<void>;
   /** Reset state between tests (truncate tables, flush cache, etc.) */
   reset: () => Promise<void>;
   /** Get the isolation strategy for parallel test execution. */
@@ -948,8 +957,9 @@ declare class HttpResult extends BaseResult {
  * for each run, {@link ServeAdapter} for `serve:`, the `{{token}}` engine for
  * every comparison, and {@link mergeTextPreservingPlaceholders} for the
  * rewrite. What is new here is only the ORCHESTRATION the chain cannot express:
- * several commands sharing one working directory, each asserted, none stopping
- * the run.
+ * several commands sharing one working directory, each judged the moment it
+ * ends — so what a run states about that directory is what IT left there, and
+ * the first run to disagree is the one the failure names.
  */
 /**
  * A server a document may start by name (`serve: mcp`), registered once per app
@@ -2229,7 +2239,31 @@ declare class SqliteHandle implements DatabasePort, ServiceHandle {
   buildConnectionString(): string;
   createDatabaseAdapter(): DatabasePort;
   healthcheck(): Promise<void>;
-  initialize(): Promise<void>;
+  /**
+   * Make the schema template available, building it if this worker is the one
+   * that gets to.
+   *
+   * The template is cached under the PROJECT's `.artifacts/vitest/sqlite/`,
+   * keyed by schema. `root` is the root the specification resolved (A9); a
+   * handle initialised outside an orchestrator — a unit test holding one
+   * directly — falls back to the same walk from the cwd.
+   *
+   * One worker builds, the others WAIT: the lock is taken with an exclusive
+   * create, so exactly one wins, and a loser polls until the winner is done
+   * rather than proceeding into a second concurrent `prisma db push` on the
+   * same file (which is what `database is locked` was).
+   */
+  initialize(_composeDir?: string, root?: string): Promise<void>;
+  /**
+   * Build the template on a private path, then rename it into place.
+   *
+   * The rename is what makes a half-built template unobservable: it is atomic
+   * within a filesystem, so a reader sees either the previous template or the
+   * finished one. Building in place could not promise that — `prisma db push`
+   * writes the SQLite header long before the tables exist, and a reader that
+   * arrived in between accepted a valid-looking file with nothing in it.
+   */
+  private buildTemplate;
   private getDb;
   private closeDb;
   seed(sql: string): Promise<void>;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { a as copyPlan, c as GROUND_EXPECTED, d as GROUND_SEEDS, i as match, n as Matcher, t as CaptureScope, u as GROUND_REQUESTS } from "./match.js";
-import { C as formatResponseDiff, E as formatTableDiff, M as structuralEquals, N as structuralSubset, O as mergePreservingPlaceholders, P as textEquals, S as formatDirectoryDiff, T as formatStdoutDiff, _ as getCallerDir, a as shouldUpdateSnapshots, b as diffDirectories, c as BaseResult, d as inspectContainer, f as removeContainers, g as text, h as TextAccessor, i as UPDATE_HINT, j as renderExpected, k as mergeTextPreservingPlaceholders, l as validateDatabaseOption, m as JsonAccessor, o as ContainerAccessor, p as TableAccessor, r as ServeAdapter, s as CliResult, t as runSpecDocument, u as findContainersByLabel, v as FilesystemAccessor, w as formatStartupReport, x as walkDirectory, y as DirectoryAccessor } from "./literate.js";
+import { C as diffDirectories, D as formatStartupReport, E as formatResponseDiff, F as structuralEquals, I as structuralSubset, L as textEquals, M as mergeTextPreservingPlaceholders, O as formatStdoutDiff, P as renderExpected, S as DirectoryAccessor, T as formatDirectoryDiff, _ as JsonAccessor, b as getCallerDir, c as shouldUpdateSnapshots, d as BaseResult, f as validateDatabaseOption, g as TableAccessor, h as removeContainers, i as runSpecDocument, j as mergePreservingPlaceholders, k as formatTableDiff, l as ContainerAccessor, m as inspectContainer, n as SQLITE_TEMPLATE_DIR, o as ServeAdapter, p as findContainersByLabel, s as UPDATE_HINT, u as CliResult, v as TextAccessor, w as walkDirectory, x as FilesystemAccessor, y as text } from "./artifacts.js";
 import { a as isContract, i as defineContracts, n as contractsOf, o as isContracts, r as defineContract, t as ContractQueue } from "./queue.js";
-import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
@@ -1726,7 +1726,7 @@ var Orchestrator = class {
 			});
 		}
 		await Promise.all([...containerServices.map(({ container }) => container.start()), ...embeddedServices.map(async (handle) => {
-			await handle.initialize(composeDir);
+			await handle.initialize(composeDir, this.root);
 			handle.started = true;
 			this.running.push({
 				handle,
@@ -1741,7 +1741,7 @@ var Orchestrator = class {
 				const port = container.getMappedPort(handle.defaultPort);
 				handle.connectionString = handle.buildConnectionString(host, port);
 				await handle.healthcheck();
-				await handle.initialize(composeDir);
+				await handle.initialize(composeDir, this.root);
 				handle.started = true;
 				reports.push({
 					name: handle.composeName ?? handle.type,
@@ -1801,7 +1801,7 @@ var Orchestrator = class {
 		const declaredComposeNames = /* @__PURE__ */ new Set();
 		for (const handle of Object.values(this.services)) {
 			if (handle.defaultPort === 0) {
-				await handle.initialize(composeDir);
+				await handle.initialize(composeDir, this.root);
 				handle.started = true;
 				continue;
 			}
@@ -1812,7 +1812,7 @@ var Orchestrator = class {
 			const port = this.composeStack.getMappedPort(handle.composeName, handle.defaultPort);
 			handle.connectionString = handle.buildConnectionString("localhost", port);
 			await handle.healthcheck();
-			await handle.initialize(composeDir);
+			await handle.initialize(composeDir, this.root);
 			handle.started = true;
 		}
 		for (const service of composeConfig.infraServices) {
@@ -1822,7 +1822,7 @@ var Orchestrator = class {
 			const handle = factory(service);
 			const port = this.composeStack.getMappedPort(service.name, handle.defaultPort);
 			handle.connectionString = handle.buildConnectionString("localhost", port);
-			await handle.initialize(composeDir);
+			await handle.initialize(composeDir, this.root);
 			handle.started = true;
 			this.composeHandles.push(handle);
 		}
@@ -2860,7 +2860,16 @@ function prismaPushCommand(prismaSchema) {
 	return `${PRISMA_PUSH} --schema ${JSON.stringify(resolve(prismaSchema))}`;
 }
 /** Every template file this package writes carries that prefix, then its key. */
-const TEMPLATE_PREFIX = "jterrazz-test-sqlite-template";
+const TEMPLATE_PREFIX = "template";
+/**
+* How long a waiter tolerates a lock nobody is touching before deciding its
+* holder died mid-build and taking over. A cold `prisma db push` is the slowest
+* build there is and finishes far inside this; a crashed holder would otherwise
+* wedge the suite forever.
+*/
+const LOCK_STALE_MS = 12e4;
+/** How often a waiter re-checks the lock. */
+const LOCK_POLL_MS = 50;
 /**
 * The schema source as bytes: a file's content, or every file under a
 * directory in a stable order (a Prisma `schema/` folder is a directory). Each
@@ -2880,12 +2889,12 @@ function schemaBytes(path) {
 * The name of the template database for a set of options — `<prefix>-<sha8>`,
 * the digest taken over the schema KIND, its resolved path and its content.
 *
-* The template lives in the machine-global OS tmpdir, so the name is the only
-* thing keeping two projects apart. A single fixed name meant the first project
-* to run on a machine built the template and every other project that day
-* silently inherited its tables — the file is header-valid, so the staleness
-* check accepts it and the schema never gets built. Keying on the schema makes
-* reuse mean "the same schema", which is what the cache was ever for.
+* The key survives the move out of the OS tmpdir. Within one project it is what
+* makes reuse mean "the same schema": editing a schema builds a new template
+* instead of inheriting the old one — the stale file is header-valid, so the
+* validity check would accept it and the tables would never be rebuilt. It also
+* keeps two checkouts of the SAME project apart when a schema differs between
+* them, on top of the separation the per-project folder already gives.
 */
 function sqliteTemplateName(options = {}) {
 	let fingerprint;
@@ -2899,6 +2908,76 @@ function sqliteTemplateName(options = {}) {
 	const key = createHash("sha256").update(fingerprint).digest("hex").slice(0, 8);
 	return `${TEMPLATE_PREFIX}-${key}.sqlite`;
 }
+/**
+* The directory a project caches its schema templates in —
+* `<root>/.artifacts/vitest/sqlite/`, created on demand.
+*
+* A project, not a machine. The template used to live in the OS tmpdir, where
+* two checkouts of the same repository shared one file: whichever ran first
+* built it, the other silently inherited that schema, and a branch that changed
+* the schema poisoned the branch beside it. A path under the project root
+* cannot be reached from another checkout at all.
+*/
+function sqliteTemplateDir(root) {
+	const dir = resolve(root, SQLITE_TEMPLATE_DIR);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+/**
+* Take the build lock, or report that someone else holds it.
+*
+* `wx` is the whole point: the file is created and claimed in ONE syscall, so
+* two workers cannot both come out of it believing they won. The former
+* check-then-write pair could, and both then ran `prisma db push` against the
+* same file — the `database is locked` failure a consumer keeps
+* `fileParallelism: false` for.
+*
+* @internal Exported for unit tests.
+*/
+function acquireTemplateLock(lockPath) {
+	let fd;
+	try {
+		fd = openSync(lockPath, "wx");
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		throw error;
+	}
+	try {
+		writeSync(fd, process.pid.toString());
+	} finally {
+		closeSync(fd);
+	}
+	return true;
+}
+/** Drop the build lock. A lock already gone is not an error — the goal is met. */
+function releaseTemplateLock(lockPath) {
+	try {
+		unlinkSync(lockPath);
+	} catch {}
+}
+/**
+* Whether a lock has gone untouched long enough that its holder must be dead.
+* A lock that no longer exists is not stale — the waiter simply retries.
+*
+* @internal Exported for unit tests.
+*/
+function isStaleTemplateLock(lockPath, now = Date.now()) {
+	try {
+		return now - statSync(lockPath).mtimeMs > LOCK_STALE_MS;
+	} catch {
+		return false;
+	}
+}
+/** Remove a file and the WAL sidecars SQLite may have left beside it. */
+function removeDatabaseFiles(path) {
+	for (const suffix of [
+		"",
+		"-wal",
+		"-shm"
+	]) try {
+		unlinkSync(`${path}${suffix}`);
+	} catch {}
+}
 var SqliteHandle = class {
 	type = "sqlite";
 	composeName = null;
@@ -2925,50 +3004,78 @@ var SqliteHandle = class {
 		return this;
 	}
 	async healthcheck() {}
-	async initialize() {
-		this.templatePath = resolve(tmpdir(), sqliteTemplateName(this.options));
+	/**
+	* Make the schema template available, building it if this worker is the one
+	* that gets to.
+	*
+	* The template is cached under the PROJECT's `.artifacts/vitest/sqlite/`,
+	* keyed by schema. `root` is the root the specification resolved (A9); a
+	* handle initialised outside an orchestrator — a unit test holding one
+	* directly — falls back to the same walk from the cwd.
+	*
+	* One worker builds, the others WAIT: the lock is taken with an exclusive
+	* create, so exactly one wins, and a loser polls until the winner is done
+	* rather than proceeding into a second concurrent `prisma db push` on the
+	* same file (which is what `database is locked` was).
+	*/
+	async initialize(_composeDir, root) {
+		const projectRoot = root ?? discoverRoot(process.cwd());
+		this.templatePath = resolve(sqliteTemplateDir(projectRoot), sqliteTemplateName(this.options));
 		const lockPath = `${this.templatePath}.lock`;
-		if (existsSync(lockPath)) {
-			const start = Date.now();
-			while (existsSync(lockPath) && Date.now() - start < 3e4) await new Promise((r) => setTimeout(r, 100));
-		}
-		if (existsSync(this.templatePath)) {
-			if (isValidSqliteTemplate(this.templatePath)) {
-				this.connectionString = `file:${this.templatePath}`;
-				this.started = true;
-				return;
+		for (;;) {
+			if (isValidSqliteTemplate(this.templatePath)) break;
+			if (!acquireTemplateLock(lockPath)) {
+				if (isStaleTemplateLock(lockPath)) releaseTemplateLock(lockPath);
+				else await new Promise((wake) => setTimeout(wake, LOCK_POLL_MS));
+				continue;
 			}
 			try {
-				unlinkSync(this.templatePath);
-			} catch {}
+				await this.buildTemplate();
+			} finally {
+				releaseTemplateLock(lockPath);
+			}
+			break;
 		}
-		const { writeFileSync } = await import("node:fs");
-		writeFileSync(lockPath, process.pid.toString());
-		if (this.prismaSchema) {
-			const { execSync } = await import("node:child_process");
-			execSync(prismaPushCommand(this.prismaSchema), {
-				env: {
-					...process.env,
-					DATABASE_URL: `file:${this.templatePath}`,
-					PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION: "yes"
-				},
-				stdio: "pipe"
-			});
-			const tmpDb = new Database(this.templatePath);
-			tmpDb.pragma("wal_checkpoint(TRUNCATE)");
-			tmpDb.close();
-		} else if (this.initSql) {
-			const sql = readFileSync(this.initSql, "utf8");
-			const templateDb = new Database(this.templatePath);
-			templateDb.exec(sql);
-			templateDb.close();
-		} else new Database(this.templatePath).close();
-		try {
-			unlinkSync(lockPath);
-		} catch {}
 		this.connectionString = `file:${this.templatePath}`;
 		this.started = true;
 	}
+	/**
+	* Build the template on a private path, then rename it into place.
+	*
+	* The rename is what makes a half-built template unobservable: it is atomic
+	* within a filesystem, so a reader sees either the previous template or the
+	* finished one. Building in place could not promise that — `prisma db push`
+	* writes the SQLite header long before the tables exist, and a reader that
+	* arrived in between accepted a valid-looking file with nothing in it.
+	*/
+	async buildTemplate() {
+		const buildPath = `${this.templatePath}.${process.pid}.building`;
+		removeDatabaseFiles(buildPath);
+		try {
+			if (this.prismaSchema) {
+				const { execSync } = await import("node:child_process");
+				execSync(prismaPushCommand(this.prismaSchema), {
+					env: {
+						...process.env,
+						DATABASE_URL: `file:${buildPath}`,
+						PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION: "yes"
+					},
+					stdio: "pipe"
+				});
+				const tmpDb = new Database(buildPath);
+				tmpDb.pragma("wal_checkpoint(TRUNCATE)");
+				tmpDb.close();
+			} else if (this.initSql) {
+				const sql = readFileSync(this.initSql, "utf8");
+				const templateDb = new Database(buildPath);
+				templateDb.exec(sql);
+				templateDb.close();
+			} else new Database(buildPath).close();
+			renameSync(buildPath, this.templatePath);
+		} finally {
+			removeDatabaseFiles(buildPath);
+		}
+	}
 	getDb() {
 		const dbPath = this.workerDbPath || this.templatePath;
 		if (!this.db) {
@@ -2999,7 +3106,7 @@ var SqliteHandle = class {
 		return {
 			acquire: async (workerId) => {
 				this.closeDb();
-				this.workerDbPath = resolve(tmpdir(), `test-worker-${workerId}-${Date.now()}.sqlite`);
+				this.workerDbPath = resolve(tmpdir(), `test-worker-${workerId}-${process.pid}-${Date.now()}.sqlite`);
 				copyFileSync(this.templatePath, this.workerDbPath);
 				this.connectionString = `file:${this.workerDbPath}`;
 			},

package/dist/oxlint.cjs

@@ -341,7 +341,7 @@ const RULE_DOCS = {
 	},
 	"c1-domain-structure": {
 		channel: "statique",
-		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `facet` (test au root de la facette OU un dossier domaine plus bas, jamais plus profond), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`. Dans tous les modes, `off` compris : un dossier à underscore initial est du SOL, jamais un domaine — aucune spec ne vit dedans.",
+		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `facet` (test au root de la facette OU un dossier domaine plus bas, jamais plus profond), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`. Dans tous les modes, `off` compris : un dossier à underscore initial est du SOL, jamais un domaine — aucune spec ne vit dedans. Une exception, et une seule : le sol peut être du CODE, et un `<module>.test.ts` posé À CÔTÉ du `<module>.ts` qu’il teste y est légal (c’est la loi I2) ; un test sans module voisin, ou un `*.specification.ts`, reste une violation.",
 		family: "C",
 		id: "C1",
 		rationale: "Une profondeur fixe rend la place de chaque fichier prévisible et détectable statiquement."
@@ -1604,6 +1604,14 @@ const TEST_SUFFIX = ".test.ts";
 const SPECIFICATION_SUFFIX = ".specification.ts";
 const DEFAULT_DEPTH = "facet-domain";
 /**
+* Whether a file is the unit test of the module it sits beside — `x.test.ts`
+* next to `x.ts`, which is the whole of I2's pairing. This is what tells a
+* ground MODULE's test from a spec that wandered into the ground.
+*/
+function testsItsNeighbour(filename) {
+	return filename.endsWith(TEST_SUFFIX) && isFile(`${filename.slice(0, -8)}.ts`);
+}
+/**
 * CONVENTIONS C1' — the shape of a spec tree, DECLARED by the consumer.
 *
 * A project states which shape its `specs/` tree has; the rule checks that one.
@@ -1649,9 +1657,15 @@ const DEFAULT_DEPTH = "facet-domain";
 *
 * The ground clause holds in every mode, `off` included: a directory whose name
 * carries a LEADING UNDERSCORE is ground — what the specs of a row stand on —
-* and never a domain, so no spec may live inside one. That is not a question of
+* and never a domain, so no SPEC may live inside one. That is not a question of
 * depth, which is why no project's declared shape switches it off.
 *
+* Ground is not always inert, though: it may be CODE the specs stand on — the
+* build of the subject under test, a harness the runner spawns. A `<module>.ts`
+* there keeps its own unit test under I2's law, `<module>.test.ts` NEXT to it,
+* and the clause lets that one pair through. Nothing else: a test with no module
+* beside it, or a `*.specification.ts`, is a spec that wandered into the ground.
+*
 * Module tests under `src/` follow the neighbour rule (I2) and are out of scope
 * in every mode.
 */
@@ -1666,7 +1680,7 @@ const c1DomainStructure = {
 			if (base.endsWith(TEST_SUFFIX) || base.endsWith(SPECIFICATION_SUFFIX)) {
 				const ground = anchor.relative.slice(0, -1).find((segment) => segment.startsWith("_"));
 				if (ground !== void 0) {
-					context.report({
+					if (!testsItsNeighbour(context.filename)) context.report({
 						data: { ground },
 						messageId: "specInGround",
 						node
@@ -1733,7 +1747,7 @@ const c1DomainStructure = {
 		defaultOptions: [{ depth: DEFAULT_DEPTH }],
 		docs: RULE_DOCS["c1-domain-structure"],
 		messages: {
-			specInGround: "A spec must not live under \"{{ground}}/\" — a leading underscore marks GROUND (what the specs of a row stand on: _fixtures/, _expected/, _requests/, _seeds/), never a domain (C1 — see docs/10-linting.md).",
+			specInGround: "A spec must not live under \"{{ground}}/\" — a leading underscore marks GROUND (what the specs of a row stand on: _fixtures/, _expected/, _requests/, _seeds/), never a domain (C1 — see docs/10-linting.md). Ground that is CODE keeps its own unit test: `<module>.test.ts` NEXT to the `<module>.ts` it tests (I2), and nothing else.",
 			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (C1 — see docs/10-linting.md).",
 			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (C1 — see docs/10-linting.md).",
 			testAtSpecsRoot: "A `*.test.ts` must live in a directory under specs/ — with `depth: \"mirror\"` the tree mirrors a structure, and the specs root mirrors nothing (C1 — see docs/10-linting.md).",

package/dist/oxlint.js

@@ -337,7 +337,7 @@ const RULE_DOCS = {
 	},
 	"c1-domain-structure": {
 		channel: "statique",
-		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `facet` (test au root de la facette OU un dossier domaine plus bas, jamais plus profond), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`. Dans tous les modes, `off` compris : un dossier à underscore initial est du SOL, jamais un domaine — aucune spec ne vit dedans.",
+		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `facet` (test au root de la facette OU un dossier domaine plus bas, jamais plus profond), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`. Dans tous les modes, `off` compris : un dossier à underscore initial est du SOL, jamais un domaine — aucune spec ne vit dedans. Une exception, et une seule : le sol peut être du CODE, et un `<module>.test.ts` posé À CÔTÉ du `<module>.ts` qu’il teste y est légal (c’est la loi I2) ; un test sans module voisin, ou un `*.specification.ts`, reste une violation.",
 		family: "C",
 		id: "C1",
 		rationale: "Une profondeur fixe rend la place de chaque fichier prévisible et détectable statiquement."
@@ -1600,6 +1600,14 @@ const TEST_SUFFIX = ".test.ts";
 const SPECIFICATION_SUFFIX = ".specification.ts";
 const DEFAULT_DEPTH = "facet-domain";
 /**
+* Whether a file is the unit test of the module it sits beside — `x.test.ts`
+* next to `x.ts`, which is the whole of I2's pairing. This is what tells a
+* ground MODULE's test from a spec that wandered into the ground.
+*/
+function testsItsNeighbour(filename) {
+	return filename.endsWith(TEST_SUFFIX) && isFile(`${filename.slice(0, -8)}.ts`);
+}
+/**
 * CONVENTIONS C1' — the shape of a spec tree, DECLARED by the consumer.
 *
 * A project states which shape its `specs/` tree has; the rule checks that one.
@@ -1645,9 +1653,15 @@ const DEFAULT_DEPTH = "facet-domain";
 *
 * The ground clause holds in every mode, `off` included: a directory whose name
 * carries a LEADING UNDERSCORE is ground — what the specs of a row stand on —
-* and never a domain, so no spec may live inside one. That is not a question of
+* and never a domain, so no SPEC may live inside one. That is not a question of
 * depth, which is why no project's declared shape switches it off.
 *
+* Ground is not always inert, though: it may be CODE the specs stand on — the
+* build of the subject under test, a harness the runner spawns. A `<module>.ts`
+* there keeps its own unit test under I2's law, `<module>.test.ts` NEXT to it,
+* and the clause lets that one pair through. Nothing else: a test with no module
+* beside it, or a `*.specification.ts`, is a spec that wandered into the ground.
+*
 * Module tests under `src/` follow the neighbour rule (I2) and are out of scope
 * in every mode.
 */
@@ -1662,7 +1676,7 @@ const c1DomainStructure = {
 			if (base.endsWith(TEST_SUFFIX) || base.endsWith(SPECIFICATION_SUFFIX)) {
 				const ground = anchor.relative.slice(0, -1).find((segment) => segment.startsWith("_"));
 				if (ground !== void 0) {
-					context.report({
+					if (!testsItsNeighbour(context.filename)) context.report({
 						data: { ground },
 						messageId: "specInGround",
 						node
@@ -1729,7 +1743,7 @@ const c1DomainStructure = {
 		defaultOptions: [{ depth: DEFAULT_DEPTH }],
 		docs: RULE_DOCS["c1-domain-structure"],
 		messages: {
-			specInGround: "A spec must not live under \"{{ground}}/\" — a leading underscore marks GROUND (what the specs of a row stand on: _fixtures/, _expected/, _requests/, _seeds/), never a domain (C1 — see docs/10-linting.md).",
+			specInGround: "A spec must not live under \"{{ground}}/\" — a leading underscore marks GROUND (what the specs of a row stand on: _fixtures/, _expected/, _requests/, _seeds/), never a domain (C1 — see docs/10-linting.md). Ground that is CODE keeps its own unit test: `<module>.test.ts` NEXT to the `<module>.ts` it tests (I2), and nothing else.",
 			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (C1 — see docs/10-linting.md).",
 			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (C1 — see docs/10-linting.md).",
 			testAtSpecsRoot: "A `*.test.ts` must live in a directory under specs/ — with `depth: \"mirror\"` the tree mirrors a structure, and the specs root mirrors nothing (C1 — see docs/10-linting.md).",

package/dist/queue.js

@@ -1,5 +1,5 @@
 import { t as CaptureScope } from "./match.js";
-import { A as placeholderPatternSource, D as hasPlaceholders, P as textEquals } from "./literate.js";
+import { A as hasPlaceholders, L as textEquals, N as placeholderPatternSource } from "./artifacts.js";
 //#region src/core/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape

package/dist/spec-document.js

@@ -1,4 +1,4 @@
-import { LineCounter, Scalar, Scalar as Scalar$1, isMap, isScalar, isSeq, parseDocument } from "yaml";
+import { LineCounter, Scalar, Scalar as Scalar$1, isMap, isScalar, isSeq, parseDocument, visit } from "yaml";
 //#region src/integrations/yaml/document.ts
 /** A line that opens a mapping key — `  key:` or `  - key:`, never block-scalar text. */
 const KEY_LINE = /^(?<indent> +)(?:- )?[A-Za-z_$'"][^\n]*:/;
@@ -65,7 +65,8 @@ function parseYamlSource(text) {
 			lineCounter
 		}),
 		indent: detectIndent(text),
-		lineAt: (offset) => lineCounter.linePos(offset).line
+		lineAt: (offset) => lineCounter.linePos(offset).line,
+		text
 	};
 }
 /** The YAML parser's own errors, with their line — an empty list when it parsed. */
@@ -88,16 +89,94 @@ function blockScalar(text) {
 	scalar.type = Scalar.BLOCK_LITERAL;
 	return scalar;
 }
+/** The first offset of the line `offset` sits on. */
+function lineStart(text, offset) {
+	return text.lastIndexOf("\n", offset - 1) + 1;
+}
+/** Back over the whitespace before `offset`, to just past the `:` or `-` that owns it. */
+function afterOwner(text, offset) {
+	let at = offset;
+	while (at > 0 && /\s/.test(text[at - 1])) at -= 1;
+	return at;
+}
+/** How many spaces a line opens with. */
+function indentOf(text, offset) {
+	const start = lineStart(text, offset);
+	return /^ */.exec(text.slice(start))[0].length;
+}
+/**
+* Every OUTERMOST flow collection of a document, in source order. A nested one
+* is part of its parent's text and is restored with it, so descending past a
+* flow collection would splice the same span twice.
+*/
+function flowCollections(text) {
+	const found = [];
+	const take = (node) => {
+		if (node.flow !== true || !node.range) return;
+		const from = afterOwner(text, node.range[0]);
+		found.push({
+			ownerIndent: indentOf(text, from === 0 ? 0 : from - 1),
+			range: [from, node.range[1]],
+			text: text.slice(from, node.range[1]),
+			value: JSON.stringify(node.toJSON())
+		});
+		return visit.SKIP;
+	};
+	visit(parseDocument(text), {
+		Map: (_key, node) => take(node),
+		Seq: (_key, node) => take(node)
+	});
+	return found;
+}
+/**
+* Give every flow collection the rewrite did not change back exactly as it was
+* written — padding, quotes and line breaks included.
+*
+* The `yaml` writer has ONE house style for `{ … }` and `[ … ]`, and it is not
+* the repository formatter's: oxfmt pads a flow mapping and not a flow sequence,
+* and explodes a long one over several lines, while the writer emits `[ 'a' ]`
+* on one line whatever its width. Re-emitting an untouched collection therefore
+* hands the formatter something to undo, and `check --fix` and `oxfmt` rewrite
+* each other for ever. A collection nobody touched belongs to its author, not to
+* either tool.
+*
+* A rendered collection is matched to a source one by VALUE and by the
+* INDENTATION of the line that owns it: the same content under the same key is
+* the same collection, and the indentation guard is what keeps the inner lines
+* of a multi-line spelling true where a fix moved that key. Anything unmatched
+* — added, removed, edited — keeps the writer's rendering.
+*/
+function restoreUntouchedFlow(rendered, text) {
+	const sources = flowCollections(text);
+	if (sources.length === 0) return rendered;
+	const taken = /* @__PURE__ */ new Set();
+	const splices = [];
+	for (const target of flowCollections(rendered)) {
+		const at = sources.findIndex((candidate, index) => !taken.has(index) && candidate.value === target.value && candidate.ownerIndent === target.ownerIndent);
+		if (at === -1) continue;
+		taken.add(at);
+		splices.push({
+			range: target.range,
+			text: sources[at].text
+		});
+	}
+	let out = rendered;
+	for (const splice of splices.toReversed()) out = out.slice(0, splice.range[0]) + splice.text + out.slice(splice.range[1]);
+	return out;
+}
 /**
 * Render a document back to text, in the indentation it was read with.
 * `lineWidth: 0` disables the folding of long lines — a golden is compared byte
 * for byte, so nothing may decide on its own where to break one.
+*
+* What the caller did not change comes back as it was written — see
+* {@link restoreUntouchedFlow} for the one construct the writer restyles.
 */
 function renderYamlSource(source) {
-	return source.document.toString({
+	return restoreUntouchedFlow(source.document.toString({
 		indent: source.indent,
 		lineWidth: 0
-	});
+	}), source.text);
 }
 //#endregion
 //#region src/core/literate/spec-document.ts

package/dist/vitest.d.ts

@@ -1,3 +1,4 @@
+import { ViteUserConfig } from "vitest/config";
 //#region src/vitest/literate-plugin.d.ts
 interface LiterateOptions {
   /**
@@ -38,4 +39,22 @@ interface LiteratePlugin {
 }
 declare function literate(options: LiterateOptions): LiteratePlugin;
 //#endregion
-export { type LiterateOptions, type LiteratePlugin, literate };
+//#region src/vitest/preset.d.ts
+/**
+ * Options are a vite/vitest config plus one key of the framework's own.
+ * Everything stated here wins over the preset's defaults.
+ */
+interface SpecConfig extends ViteUserConfig {
+  /**
+   * Turns every matching `<case>.spec.yaml` into a test file bound to the
+   * named specification — the {@link literate} plugin, added to `plugins`.
+   *
+   * Declare it here for a config with no `projects`. With projects, the glob
+   * has to join the include of the ONE project that collects those documents,
+   * so the plugin goes in that project's own `plugins` instead.
+   */
+  literate?: LiterateOptions;
+}
+declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
+//#endregion
+export { type LiterateOptions, type LiteratePlugin, type SpecConfig, defineSpecConfig, literate };

package/dist/vitest.js

@@ -1,6 +1,7 @@
-import { n as specDescription } from "./literate.js";
+import { a as specDescription, r as VITEST_ARTIFACTS_DIR, t as COVERAGE_DIR } from "./artifacts.js";
 import { readFileSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
+import { configDefaults, mergeConfig } from "vitest/config";
 //#region src/vitest/literate-plugin.ts
 /**
 * The `literate()` vite plugin — door one of the spec-document format.
@@ -66,4 +67,101 @@ function literate(options) {
 	};
 }
 //#endregion
-export { literate };
+//#region src/vitest/preset.ts
+/**
+* `defineSpecConfig()` — the shared vitest config every repository of the
+* ecosystem starts from.
+*
+* Fourteen hand-rolled `vitest.config.ts` files had converged on the same
+* handful of settings and disagreed on the rest by accident; the preset is
+* their common ground, stated once. A consumer writes ONE call and keeps
+* everything vitest offers: what it passes is a plain vite/vitest config,
+* merged OVER the defaults, so any of them is overridable in place.
+*
+* ```typescript
+* // vitest.config.ts
+* import { defineSpecConfig } from '@jterrazz/test/vitest';
+*
+* export default defineSpecConfig({
+*     literate: { specification: './specs/cli/cli.specification.ts' },
+*     test: {
+*         projects: [
+*             { test: { include: ['src/**\/*.test.ts'], name: 'unit' } },
+*             { test: { include: ['specs/api/**\/*.test.ts'], name: 'api' } },
+*         ],
+*     },
+* });
+* ```
+*/
+/**
+* A run's budget. Vitest's own 5s test / 10s hook defaults were raised by every
+* repository that starts real infrastructure, and none of them meant 5s — a
+* container boot, a `prisma db push` or a `next build` all outlive it. 30s is
+* the value the ecosystem's configs already converged on; a suite that needs
+* more (a simulator cold boot, a real image build) states its own per project.
+*/
+const TEST_TIMEOUT_MS = 3e4;
+const HOOK_TIMEOUT_MS = 3e4;
+/**
+* What a spec STANDS ON is never itself a test: `_fixtures/` holds inputs —
+* deliberately-wrong twins, fixture projects a spec lints — and collecting them
+* runs a repository's own counter-examples as if they were its suite. Every
+* config that ever hit it added the same line by hand.
+*
+* Merged, not replaced: vite concatenates arrays, so a consumer's `exclude`
+* ADDS to this list and never has to spread `configDefaults.exclude` again.
+*/
+const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
+/**
+* Defaults a vitest PROJECT accepts. `coverage` and `reporters` are root-only
+* options (vitest omits them from a project's config), so they are absent here
+* on purpose — setting them would be silently dropped.
+*/
+function projectDefaults() {
+	return {
+		cacheDir: VITEST_ARTIFACTS_DIR,
+		test: {
+			exclude: EXCLUDE,
+			hookTimeout: HOOK_TIMEOUT_MS,
+			testTimeout: TEST_TIMEOUT_MS
+		}
+	};
+}
+/** Defaults for the root config — the project ones, plus what only a root carries. */
+function rootDefaults() {
+	return {
+		cacheDir: VITEST_ARTIFACTS_DIR,
+		test: {
+			coverage: { reportsDirectory: COVERAGE_DIR },
+			exclude: EXCLUDE,
+			hookTimeout: HOOK_TIMEOUT_MS,
+			testTimeout: TEST_TIMEOUT_MS
+		}
+	};
+}
+/**
+* A project inherits NOTHING from the root `test` block — vitest resolves each
+* project as its own config — so the defaults are merged into every inline one.
+* A project declared as a glob string, a promise or a function is handed back
+* untouched: there is no object to merge into.
+*/
+function withProjectDefaults(project) {
+	if (typeof project !== "object" || project === null || "then" in project) return project;
+	return mergeConfig(projectDefaults(), project);
+}
+function defineSpecConfig(config = {}) {
+	const { literate: literateOptions, ...userConfig } = config;
+	const stated = literateOptions ? mergeConfig({ plugins: [literate(literateOptions)] }, userConfig) : userConfig;
+	const merged = mergeConfig(rootDefaults(), stated);
+	const projects = merged.test?.projects;
+	if (!projects) return merged;
+	return {
+		...merged,
+		test: {
+			...merged.test,
+			projects: projects.map(withProjectDefaults)
+		}
+	};
+}
+//#endregion
+export { defineSpecConfig, literate };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "14.0.0",
+    "version": "14.1.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",