@jterrazz/test 14.0.1 → 14.2.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/appium.adapter.js

@@ -179,12 +179,12 @@ function projectScreen(xml) {
 }
 //#endregion
 //#region src/integrations/appium/appium.adapter.ts
-const ACTION_TIMEOUT_MS = 3e4;
+const DEFAULT_ACTION_TIMEOUT_MS = 3e4;
 const POLL_INTERVAL_MS = 500;
 /** How many candidates the ambiguity error enumerates before truncating. */
 const MAX_REPORTED_MATCHES = 10;
 /** WebDriverAgent builds once per simulator — the first session is the slow one. */
-const WDA_LAUNCH_TIMEOUT_MS = 24e4;
+const DEFAULT_WDA_LAUNCH_TIMEOUT_MS = 24e4;
 const delay = (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 /** Escape a name for an NSPredicate single-quoted string literal. */
 function escapePredicate(value) {
@@ -213,6 +213,19 @@ function scopeChain(element) {
 	for (let current = element; current; current = current.scope) chain.unshift(current);
 	return chain;
 }
+/**
+* Load webdriverio's session factory, naming the install when the optional
+* peer dependency is absent. Lazy: the dependency is only required by a spec
+* that actually opens the app.
+*/
+async function loadRemote() {
+	try {
+		const { remote: remoteFn } = await import("webdriverio");
+		return remoteFn;
+	} catch {
+		throw new Error(".open() requires webdriverio (optional peer dependency): npm install -D appium webdriverio && npx appium driver install xcuitest");
+	}
+}
 /** Capture one candidate's evidence for the ambiguity refusal. */
 async function captureMatch(element) {
 	const [type, label, value, identifier] = await Promise.all([
@@ -241,10 +254,27 @@ async function captureMatch(element) {
 * this module is only loaded when a spec calls `.open()`.
 */
 var AppiumAdapter = class {
+	/** The verb poll budget — the runner's `timeouts.action`, or the default. */
+	actionTimeoutMs;
 	driver = null;
+	/** The WebDriverAgent launch budget — the runner's `timeouts.launch`, or the default. */
+	launchTimeoutMs;
 	options;
+	/**
+	* The session factory. Absent in production — webdriverio is then loaded
+	* lazily on the first `open()`. Injected by this module's own unit test,
+	* which drives the waits over a stub driver with no simulator in reach
+	* (mocks are CODE here, CONVENTIONS I4).
+	*/
+	remote;
 	constructor(options) {
-		this.options = options;
+		this.options = {
+			serverUrl: options.serverUrl,
+			udid: options.udid
+		};
+		this.remote = options.remote;
+		this.actionTimeoutMs = options.timeouts?.action ?? DEFAULT_ACTION_TIMEOUT_MS;
+		this.launchTimeoutMs = options.timeouts?.launch ?? DEFAULT_WDA_LAUNCH_TIMEOUT_MS;
 	}
 	async close() {
 		if (this.driver) {
@@ -305,7 +335,7 @@ var AppiumAdapter = class {
 	*/
 	async resolveOne(driver, element, verb, cardinality) {
 		const chain = scopeChain(element);
-		const deadline = Date.now() + ACTION_TIMEOUT_MS;
+		const deadline = Date.now() + this.actionTimeoutMs;
 		let scrollAttempted = false;
 		for (;;) {
 			const resolved = await this.resolveChain(driver, chain, cardinality, { tryScroll: !scrollAttempted });
@@ -367,17 +397,12 @@ var AppiumAdapter = class {
 			const labels = [...new Set([...source.matchAll(/label="(?<label>[^"]{2,60})"/g)].map((match) => match.groups?.["label"] ?? ""))].slice(0, 15);
 			if (labels.length > 0) excerpt = `\nCurrently on screen: ${labels.join(" | ")}`;
 		} catch {}
-		return /* @__PURE__ */ new Error(`${verb}(${formatElement(element)}) timed out after ${ACTION_TIMEOUT_MS}ms — no visible match.${excerpt}`);
+		return /* @__PURE__ */ new Error(`${verb}(${formatElement(element)}) timed out after ${this.actionTimeoutMs}ms — no visible match.${excerpt}`);
 	}
 	/** Create the shared driver session (once), with an actionable error when webdriverio is absent. */
 	async session(bundleId) {
 		if (this.driver) return this.driver;
-		let remoteFn;
-		try {
-			({remote: remoteFn} = await import("webdriverio"));
-		} catch {
-			throw new Error(".open() requires webdriverio (optional peer dependency): npm install -D appium webdriverio && npx appium driver install xcuitest");
-		}
+		const remoteFn = this.remote ?? await loadRemote();
 		const url = new URL(this.options.serverUrl);
 		this.driver = await remoteFn({
 			capabilities: {
@@ -385,7 +410,7 @@ var AppiumAdapter = class {
 				"appium:bundleId": bundleId,
 				"appium:noReset": true,
 				"appium:udid": this.options.udid,
-				"appium:wdaLaunchTimeout": WDA_LAUNCH_TIMEOUT_MS,
+				"appium:wdaLaunchTimeout": this.launchTimeoutMs,
 				platformName: "iOS"
 			},
 			hostname: url.hostname,

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

@@ -932,6 +932,95 @@ function removeContainers(ids) {
 	} catch {}
 }
 //#endregion
+//#region src/core/specification/shared/resolve.ts
+/** What makes a directory a project root — a manifest, or a test stack. */
+const ROOT_MARKERS = ["package.json", "docker/compose.test.yaml"];
+/**
+* The NEAREST ancestor of `startDir` (itself included) carrying a root marker,
+* `undefined` when none does.
+*
+* Both markers are probed at each ancestor, in ONE walk. Two walks — the
+* compose file all the way up, then `package.json` all the way up — made the
+* further directory win: in a workspace, a `docker/compose.test.yaml` at the
+* repository root outranked the `package.json` of the very package being
+* tested, and every path the runner resolved was measured from the wrong unit.
+* The unit is the nearest thing that declares itself a project.
+*
+* The existence probe is injected so the lint layer can pass its cached one
+* (A9's `a9w-redundant-root` derives the same root, and must derive it the
+* same way).
+*/
+function findRoot(startDir, exists) {
+	let dir = startDir;
+	for (;;) {
+		if (ROOT_MARKERS.some((marker) => exists(resolve(dir, marker)))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/**
+* Auto-discover the project root from a starting directory (CONVENTIONS A9):
+* walk up to the first directory that carries `package.json` or
+* `docker/compose.test.yaml`; if none does, the starting directory itself.
+*/
+function discoverRoot(startDir) {
+	return findRoot(startDir, existsSync) ?? startDir;
+}
+/**
+* Resolve the project root for a specification. An explicit `root` option is
+* an override (resolved from the caller's directory when relative); when
+* absent, the root is auto-discovered by walking up from the calling
+* specification file.
+*/
+function resolveRoot(root, callerDir) {
+	if (!root) return discoverRoot(callerDir);
+	if (isAbsolute(root)) return root;
+	return resolve(callerDir, root);
+}
+/**
+* Resolve a command — checks node_modules/.bin, then treats as absolute/PATH.
+*/
+function resolveCommand(command, root) {
+	if (isAbsolute(command)) return command;
+	const binPath = resolve(root, "node_modules/.bin", command);
+	if (existsSync(binPath)) return binPath;
+	const cwdBinPath = resolve(process.cwd(), "node_modules/.bin", command);
+	if (existsSync(cwdBinPath)) return cwdBinPath;
+	return command;
+}
+/**
+* The realpath form of a working directory — what a child process prints as
+* `$PWD` (macOS resolves the tmpdir symlink), and therefore what `{{workdir}}`
+* compares against. Falls back to the path itself when it cannot be resolved.
+*
+* @internal Shared by the result scope, the literate runner and `$WORKDIR`.
+*/
+function safeRealpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* Expand the `$WORKDIR` token in every string value of a child environment —
+* the one place the token is spelled out, for both doors (`.env()` on the
+* chain, `env:` in a `<case>.spec.yaml`).
+*
+* It expands to the RESOLVED directory, never the raw temp path: a value the
+* child receives comes back in its output, and it must come back spelled the
+* way `{{workdir}}` holds it (realpath form, CONVENTIONS D4). Expanding the raw
+* path made `HOME=$WORKDIR` on macOS echo `/var/folders/…` against a
+* `{{workdir}}` holding `/private/var/folders/…` — a golden no run could match.
+*/
+function expandWorkdir(env, workDir) {
+	const workdir = safeRealpath(workDir);
+	const expanded = {};
+	for (const [key, value] of Object.entries(env)) expanded[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workdir) : value;
+	return expanded;
+}
+//#endregion
 //#region src/core/specification/shared/result/result.ts
 /**
 * Base result - common accessors available after any action type.
@@ -986,20 +1075,6 @@ var BaseResult = class {
 	}
 };
 /**
-* The realpath form of a working directory — what a child process prints as
-* `$PWD` (macOS resolves the tmpdir symlink), and therefore what `{{workdir}}`
-* compares against. Falls back to the path itself when it cannot be resolved.
-*
-* @internal Shared with the literate runner, which builds its own file-wide scope.
-*/
-function safeRealpath(path) {
-	try {
-		return realpathSync(path);
-	} catch {
-		return path;
-	}
-}
-/**
 * Enforce CONVENTIONS A7: with two or more databases in the services record
 * the `database` option is mandatory on `.seed()` / `.table()`; with exactly
 * one it is forbidden (redundant).
@@ -1650,11 +1725,6 @@ function documentEnv(document, config, displayPath) {
 	}
 	return env;
 }
-function expandWorkdir(env, workDir) {
-	const resolved = {};
-	for (const [key, value] of Object.entries(env)) resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
-	return resolved;
-}
 /**
 * Run one spec document end to end and resolve with the LAST run's result —
 * the handle a `.test.ts` adds its own assertion to (a directory golden, a
@@ -1727,5 +1797,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 { formatResponseDiff as A, structuralSubset as B, text as C, diffDirectories as D, DirectoryAccessor as E, mergePreservingPlaceholders as F, mergeTextPreservingPlaceholders as I, placeholderPatternSource as L, formatStdoutDiff as M, formatTableDiff as N, walkDirectory as O, hasPlaceholders as P, renderExpected as R, TextAccessor as S, FilesystemAccessor as T, textEquals as V, findContainersByLabel as _, specDescription as a, TableAccessor as b, shouldUpdateSnapshots as c, BaseResult as d, validateDatabaseOption as f, resolveRoot as g, resolveCommand as h, runSpecDocument as i, formatStartupReport as j, formatDirectoryDiff as k, ContainerAccessor as l, expandWorkdir as m, SQLITE_TEMPLATE_DIR as n, ServeAdapter as o, discoverRoot as p, VITEST_ARTIFACTS_DIR as r, UPDATE_HINT as s, COVERAGE_DIR as t, CliResult as u, inspectContainer as v, getCallerDir as w, JsonAccessor as x, removeContainers as y, structuralEquals as z };

package/dist/index.d.ts

@@ -798,6 +798,24 @@ interface DeviceOpenOptions {
   /** The interaction scenario to run after launch; the capture reflects the final state. */
   scenario?: MobileScenario;
 }
+/**
+ * How long a device session waits, in milliseconds. Every field is optional
+ * and falls back to the framework's own default, so a runner states only the
+ * wait it needs to move — the defaults suit a release build, and a project
+ * that drives a DEV build pays for its bundler's cold boot.
+ */
+interface DeviceTimeouts {
+  /**
+   * How long every verb polls for a visible match before refusing.
+   * Default: `30_000` — enough for a cold app boot on a release bundle.
+   */
+  action?: number;
+  /**
+   * How long the FIRST session waits for WebDriverAgent to build and
+   * launch on the simulator. Default: `240_000`.
+   */
+  launch?: number;
+}
 /**
  * Abstract device interface for the mobile specification runner.
  * One implementation lives in `integrations/appium/` — a single driver
@@ -876,8 +894,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. */
@@ -1767,6 +1794,13 @@ interface MobileSpecificationOptions {
    * file when absent.
    */
   root?: string;
+  /**
+   * How long this runner's session waits, in milliseconds — every field
+   * optional, each falling back to the framework's default. A project
+   * driving a DEV build states the wait its bundler's cold boot needs
+   * (`{ action: 45_000 }`) instead of sleeping inside its scenarios.
+   */
+  timeouts?: DeviceTimeouts;
 }
 /**
  * The record returned by {@link startMobile | specification.mobile}.
@@ -2230,7 +2264,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>;
@@ -2479,4 +2537,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliInput, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, type DeviceTimeouts, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };

package/dist/index.js

@@ -1,8 +1,8 @@
 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 { A as formatResponseDiff, B as structuralSubset, C as text, D as diffDirectories, E as DirectoryAccessor, F as mergePreservingPlaceholders, I as mergeTextPreservingPlaceholders, M as formatStdoutDiff, N as formatTableDiff, O as walkDirectory, R as renderExpected, S as TextAccessor, T as FilesystemAccessor, V as textEquals, _ as findContainersByLabel, b as TableAccessor, c as shouldUpdateSnapshots, d as BaseResult, f as validateDatabaseOption, g as resolveRoot, h as resolveCommand, i as runSpecDocument, j as formatStartupReport, k as formatDirectoryDiff, l as ContainerAccessor, m as expandWorkdir, n as SQLITE_TEMPLATE_DIR, o as ServeAdapter, p as discoverRoot, s as UPDATE_HINT, u as CliResult, v as inspectContainer, w as getCallerDir, x as JsonAccessor, y as removeContainers, z as structuralEquals } 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 { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
@@ -1092,8 +1092,10 @@ var SpecificationBuilder = class {
 	* Set environment variables for the command process. Merged on top of process.env.
 	* Use `null` to unset a variable. Multiple calls merge.
 	*
-	* The token `$WORKDIR` (in any value) is replaced with the actual working
-	* directory at run-time — useful for tests that need a fully isolated `HOME`.
+	* The token `$WORKDIR` (in any value) is replaced at run-time with the
+	* spec's working directory in its resolved form — the same string
+	* `{{workdir}}` asserts against — so a path handed to the child comes back
+	* matchable. Useful for tests that need a fully isolated `HOME`.
 	*
 	* @example
 	*   cli.env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status");
@@ -1346,14 +1348,8 @@ var SpecificationBuilder = class {
 		}
 	}
 	resolveEnv(workDir) {
-		const keys = Object.keys(this.commandEnv);
-		if (keys.length === 0) return;
-		const resolved = {};
-		for (const key of keys) {
-			const value = this.commandEnv[key];
-			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
-		}
-		return resolved;
+		if (Object.keys(this.commandEnv).length === 0) return;
+		return expandWorkdir(this.commandEnv, workDir);
 	}
 	prepareWorkDir() {
 		return mkdtempSync(resolve(tmpdir(), "spec-command-"));
@@ -1726,7 +1722,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 +1737,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 +1797,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 +1808,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 +1818,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);
 		}
@@ -1890,64 +1886,6 @@ var Orchestrator = class {
 	}
 };
 //#endregion
-//#region src/core/specification/shared/resolve.ts
-/** What makes a directory a project root — a manifest, or a test stack. */
-const ROOT_MARKERS = ["package.json", "docker/compose.test.yaml"];
-/**
-* The NEAREST ancestor of `startDir` (itself included) carrying a root marker,
-* `undefined` when none does.
-*
-* Both markers are probed at each ancestor, in ONE walk. Two walks — the
-* compose file all the way up, then `package.json` all the way up — made the
-* further directory win: in a workspace, a `docker/compose.test.yaml` at the
-* repository root outranked the `package.json` of the very package being
-* tested, and every path the runner resolved was measured from the wrong unit.
-* The unit is the nearest thing that declares itself a project.
-*
-* The existence probe is injected so the lint layer can pass its cached one
-* (A9's `a9w-redundant-root` derives the same root, and must derive it the
-* same way).
-*/
-function findRoot(startDir, exists) {
-	let dir = startDir;
-	for (;;) {
-		if (ROOT_MARKERS.some((marker) => exists(resolve(dir, marker)))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return;
-		dir = parent;
-	}
-}
-/**
-* Auto-discover the project root from a starting directory (CONVENTIONS A9):
-* walk up to the first directory that carries `package.json` or
-* `docker/compose.test.yaml`; if none does, the starting directory itself.
-*/
-function discoverRoot(startDir) {
-	return findRoot(startDir, existsSync) ?? startDir;
-}
-/**
-* Resolve the project root for a specification. An explicit `root` option is
-* an override (resolved from the caller's directory when relative); when
-* absent, the root is auto-discovered by walking up from the calling
-* specification file.
-*/
-function resolveRoot(root, callerDir) {
-	if (!root) return discoverRoot(callerDir);
-	if (isAbsolute(root)) return root;
-	return resolve(callerDir, root);
-}
-/**
-* Resolve a command — checks node_modules/.bin, then treats as absolute/PATH.
-*/
-function resolveCommand(command, root) {
-	if (isAbsolute(command)) return command;
-	const binPath = resolve(root, "node_modules/.bin", command);
-	if (existsSync(binPath)) return binPath;
-	const cwdBinPath = resolve(process.cwd(), "node_modules/.bin", command);
-	if (existsSync(cwdBinPath)) return cwdBinPath;
-	return command;
-}
-//#endregion
 //#region src/core/specification/shared/services.ts
 function getWorkerId() {
 	return process.env.VITEST_POOL_ID ?? "0";
@@ -2615,6 +2553,7 @@ async function startMobile(options) {
 			const { AppiumAdapter } = await import("./appium.adapter.js");
 			device = new AppiumAdapter({
 				serverUrl: appium.url,
+				timeouts: options.timeouts,
 				udid
 			});
 		}
@@ -2860,7 +2799,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 +2828,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 +2847,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 +2943,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 +3045,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 { L as placeholderPatternSource, P as hasPlaceholders, V as textEquals } 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.2.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",