@jterrazz/test 14.0.1 → 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}

@@ -1727,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. */
@@ -2230,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/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/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.1",
+    "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",