@jterrazz/test 15.0.0 → 15.1.1

package/dist/index.js

@@ -1,5 +1,5 @@
 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 { 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 { B as text, C as FilesystemAccessor, E as walkDirectory, F as findContainersByLabel, I as inspectContainer, L as removeContainers, M as structuralEquals, N as structuralSubset, O as mergePreservingPlaceholders, P as textEquals, R as JsonAccessor, S as resolveRoot, T as diffDirectories, V as getCallerDir, _ as validateDatabaseOption, b as expandWorkdir, c as shouldUpdateSnapshots, d as formatStartupReport, f as formatStdoutDiff, g as BaseResult, h as CliResult, i as runSpecDocument, j as renderExpected, k as mergeTextPreservingPlaceholders, l as formatDirectoryDiff, m as ContainerAccessor, n as SQLITE_TEMPLATE_DIR, o as ServeAdapter, p as formatTableDiff, s as UPDATE_HINT, u as formatResponseDiff, v as TableAccessor, w as DirectoryAccessor, x as resolveCommand, y as discoverRoot, z as TextAccessor } 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, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
@@ -13,25 +13,6 @@ import Database from "better-sqlite3";
 import { createHash } from "node:crypto";
 import { mockDeep } from "vitest-mock-extended";
 import MockDatePackage from "mockdate";
-//#region src/core/specification/shared/registry.ts
-let containerIntegrations = null;
-const composeServiceFactories = /* @__PURE__ */ new Map();
-/** Wire the container runtimes. Called by the package entry point. */
-function registerContainerIntegrations(integrations) {
-	containerIntegrations = integrations;
-}
-/** Wire a service auto-detection factory (e.g. `'postgres'`, `'redis'`). */
-function registerComposeServiceFactory(type, factory) {
-	composeServiceFactories.set(type, factory);
-}
-function getContainerIntegrations() {
-	if (!containerIntegrations) throw new Error("@jterrazz/test: container integrations are not registered — import from '@jterrazz/test' (the package entry point wires them).");
-	return containerIntegrations;
-}
-function getComposeServiceFactory(type) {
-	return composeServiceFactories.get(type);
-}
-//#endregion
 //#region src/integrations/compose/compose-parser.ts
 /**
 * Parse a docker-compose file and extract service definitions.
@@ -58,7 +39,7 @@ function parseComposeFile(filePath) {
 		const environment = {};
 		if (def.environment) if (Array.isArray(def.environment)) for (const env of def.environment) {
 			const [key, ...rest] = String(env).split("=");
-			environment[key] = rest.join("=");
+			if (key !== void 0) environment[key] = rest.join("=");
 		}
 		else Object.assign(environment, def.environment);
 		const volumes = def.volumes ? def.volumes.map((v) => String(v)) : [];
@@ -351,7 +332,7 @@ var TestcontainersAdapter = class {
 		const { GenericContainer, Wait } = await import("testcontainers");
 		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort);
 		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
-		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/, 2));
+		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/u, 2));
 		if (this.reuse) builder = builder.withReuse();
 		this.container = await builder.start();
 	}
@@ -375,7 +356,7 @@ var TestcontainersAdapter = class {
 	async getLogs() {
 		if (!this.container) return "";
 		const stream = await this.container.logs();
-		return new Promise((resolve) => {
+		return await new Promise((resolve) => {
 			let output = "";
 			stream.on("data", (chunk) => {
 				output += chunk.toString();
@@ -390,6 +371,25 @@ var TestcontainersAdapter = class {
 	}
 };
 //#endregion
+//#region src/specification/facets/_common/registry.ts
+let containerIntegrations = null;
+const composeServiceFactories = /* @__PURE__ */ new Map();
+/** Wire the container runtimes. Called by the package entry point. */
+function registerContainerIntegrations(integrations) {
+	containerIntegrations = integrations;
+}
+/** Wire a service auto-detection factory (e.g. `'postgres'`, `'redis'`). */
+function registerComposeServiceFactory(type, factory) {
+	composeServiceFactories.set(type, factory);
+}
+function getContainerIntegrations() {
+	if (!containerIntegrations) throw new Error("@jterrazz/test: container integrations are not registered — import from '@jterrazz/test' (the package entry point wires them).");
+	return containerIntegrations;
+}
+function getComposeServiceFactory(type) {
+	return composeServiceFactories.get(type);
+}
+//#endregion
 //#region src/integrations/hono/hono.adapter.ts
 /**
 * Server adapter that dispatches requests in-process through a Hono app instance.
@@ -423,17 +423,48 @@ var HonoAdapter = class {
 	}
 };
 //#endregion
-//#region src/core/http-files/http-file.ts
+//#region src/specification/facets/_common/result/response.ts
+/**
+* Read-only accessor for an HTTP response.
+*
+* Assertions go through `expect()`:
+* `expect(result.response).toMatch('created.http')` compares status,
+* a subset of headers, and the JSON body against `_expected/<name>` —
+* with `{{placeholder}}` support in all three.
+*/
+var ResponseAccessor = class {
+	/** The parsed JSON response body (null when parsing failed). */
+	body;
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** Response headers as a flat, lower-cased key-value map. */
+	headers;
+	/** The HTTP response status code. */
+	status;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	constructor(response, testDir, captures) {
+		this.body = response.body;
+		this.headers = response.headers;
+		this.status = response.status;
+		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
+	}
+};
+//#endregion
+//#region src/specification/http-files/http-file.ts
 function splitSections(content) {
-	const lines = content.split(/\r?\n/);
+	const lines = content.split(/\r?\n/u);
 	let index = 0;
-	while (index < lines.length && lines[index].trim() === "") index++;
+	while (lines[index]?.trim() === "") index++;
 	const startLine = lines[index] ?? "";
 	index++;
 	const headerLines = [];
-	while (index < lines.length && lines[index].trim() !== "") {
-		headerLines.push(lines[index]);
+	let header = lines[index];
+	while (header !== void 0 && header.trim() !== "") {
+		headerLines.push(header);
 		index++;
+		header = lines[index];
 	}
 	return {
 		body: lines.slice(index + 1).join("\n").trim(),
@@ -453,20 +484,22 @@ function parseHeaders(headerLines, fileName) {
 /** Parse a `_requests/*.http` file. First line must be `METHOD /path`. */
 function parseRequestFile(content, fileName) {
 	const { body, headerLines, startLine } = splitSections(content);
-	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/.exec(startLine.trim());
-	if (!start?.groups) throw new Error(`${fileName}: first line must be "METHOD /path" (e.g. "POST /users"), got "${startLine}"`);
+	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/u.exec(startLine.trim());
+	const method = start?.groups?.method;
+	const path = start?.groups?.path;
+	if (method === void 0 || path === void 0) throw new Error(`${fileName}: first line must be "METHOD /path" (e.g. "POST /users"), got "${startLine}"`);
 	return {
 		body: body.length > 0 ? body : void 0,
 		headers: parseHeaders(headerLines, fileName),
-		method: start.groups.method,
-		path: start.groups.path
+		method,
+		path
 	};
 }
 /** Parse a response `.http` file. First line must be `HTTP/1.1 <status>`. */
 function parseResponseFile(content, fileName) {
 	const { body, headerLines, startLine } = splitSections(content);
-	const start = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/.exec(startLine.trim());
-	if (!start?.groups) throw new Error(`${fileName}: first line must be "HTTP/1.1 <status>" (e.g. "HTTP/1.1 200 OK"), got "${startLine}"`);
+	const status = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/u.exec(startLine.trim())?.groups?.status;
+	if (status === void 0) throw new Error(`${fileName}: first line must be "HTTP/1.1 <status>" (e.g. "HTTP/1.1 200 OK"), got "${startLine}"`);
 	let parsedBody;
 	if (body.length > 0) try {
 		parsedBody = JSON.parse(body);
@@ -477,7 +510,7 @@ function parseResponseFile(content, fileName) {
 		body: parsedBody,
 		hasBody: body.length > 0,
 		headers: parseHeaders(headerLines, fileName),
-		status: start.groups.status
+		status
 	};
 }
 const STATUS_TEXT = {
@@ -505,10 +538,7 @@ function serializeResponseFile(response) {
 	const statusText = STATUS_TEXT[statusNumber];
 	const lines = [`HTTP/1.1 ${response.status}${statusText ? ` ${statusText}` : ""}`];
 	for (const [name, value] of Object.entries(response.headers)) lines.push(`${name}: ${value}`);
-	if (response.hasBody) {
-		lines.push("");
-		lines.push(typeof response.body === "string" && !isJsonLike(response.body) ? response.body : JSON.stringify(response.body, null, 4));
-	}
+	if (response.hasBody) lines.push("", typeof response.body === "string" && !isJsonLike(response.body) ? response.body : JSON.stringify(response.body, null, 4));
 	return `${lines.join("\n")}\n`;
 }
 function isJsonLike(text) {
@@ -520,35 +550,6 @@ function isJsonLike(text) {
 	}
 }
 //#endregion
-//#region src/core/specification/shared/result/response.ts
-/**
-* Read-only accessor for an HTTP response.
-*
-* Assertions go through `expect()`:
-* `expect(result.response).toMatch('created.http')` compares status,
-* a subset of headers, and the JSON body against `_expected/<name>` —
-* with `{{placeholder}}` support in all three.
-*/
-var ResponseAccessor = class {
-	/** The parsed JSON response body (null when parsing failed). */
-	body;
-	/** @internal Ref-capture scope shared by the current spec execution. */
-	captures;
-	/** Response headers as a flat, lower-cased key-value map. */
-	headers;
-	/** The HTTP response status code. */
-	status;
-	/** @internal Test-file directory — fixture resolution root for matchers. */
-	testDir;
-	constructor(response, testDir, captures) {
-		this.body = response.body;
-		this.headers = response.headers;
-		this.status = response.status;
-		this.testDir = testDir;
-		this.captures = captures ?? new CaptureScope();
-	}
-};
-//#endregion
 //#region src/vitest/matchers.ts
 /**
 * Vitest custom matchers for `@jterrazz/test` accessors.
@@ -570,7 +571,7 @@ const FAIL = (message) => ({
 	pass: false
 });
 function requireExtension(name, subject) {
-	if (!/\.[A-Za-z0-9]+$/.test(name)) throw new Error(`toMatch("${name}"): the extension is part of the name and is required for ${subject} subjects (e.g. "help.txt").`);
+	if (!/\.[A-Za-z0-9]+$/u.test(name)) throw new Error(`toMatch("${name}"): the extension is part of the name and is required for ${subject} subjects (e.g. "help.txt").`);
 }
 function formatJson(value) {
 	return `${JSON.stringify(value, null, 4)}\n`;
@@ -639,7 +640,7 @@ function buildUpdatedResponse(previous, actual, workdir) {
 * @internal Exported for unit tests.
 */
 function compareResponse(name, expected, actual, scope) {
-	if (!(/^\d+$/.test(expected.status) ? Number(expected.status) === actual.status : structuralEquals(expected.status, String(actual.status), scope))) return `Response status mismatch (${name})\n  expected: ${expected.status}\n  received: ${actual.status}`;
+	if (!(/^\d+$/u.test(expected.status) ? Number(expected.status) === actual.status : structuralEquals(expected.status, String(actual.status), scope))) return `Response status mismatch (${name})\n  expected: ${expected.status}\n  received: ${actual.status}`;
 	for (const [key, value] of Object.entries(expected.headers)) {
 		const actualValue = actual.headers[key.toLowerCase()];
 		if (actualValue === void 0 || !structuralEquals(value, actualValue, scope)) return `Response header mismatch (${name})\n  header: ${key}\n  expected: ${value}\n  received: ${actualValue ?? "(absent)"}`;
@@ -756,7 +757,10 @@ function toContain(received, expected) {
 async function toMatchRows(received, expected) {
 	if (!(received instanceof TableAccessor)) throw new TypeError("toMatchRows: unsupported subject — expected result.table(...).");
 	const actual = await received.query(expected.columns);
-	const pass = actual.length === expected.rows.length && expected.rows.every((row, i) => row.length === actual[i].length && row.every((cell, j) => structuralEquals(cell, actual[i][j], received.captures)));
+	const pass = actual.length === expected.rows.length && expected.rows.every((row, i) => {
+		const actualRow = actual[i];
+		return actualRow !== void 0 && row.length === actualRow.length && row.every((cell, j) => structuralEquals(cell, actualRow[j], received.captures));
+	});
 	return {
 		message: () => pass ? `expected table "${received.name}" not to match the given rows` : formatTableDiff(received.name, expected.columns, expected.rows.map((row) => row.map((cell) => renderExpected(cell))), actual),
 		pass
@@ -815,7 +819,7 @@ async function registerMatchers() {
 	}
 }
 //#endregion
-//#region src/core/specification/api/result.ts
+//#region src/specification/facets/api/result.ts
 /** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
 var HttpResult = class extends BaseResult {
 	responseData;
@@ -833,7 +837,7 @@ var HttpResult = class extends BaseResult {
 	}
 };
 //#endregion
-//#region src/core/specification/mobile/result.ts
+//#region src/specification/facets/mobile/result.ts
 /** Result from a `.open()` action — the screen as the device saw it, final state. */
 var ScreenResult = class extends BaseResult {
 	capturedScreen;
@@ -857,7 +861,7 @@ var ScreenResult = class extends BaseResult {
 	}
 };
 //#endregion
-//#region src/core/specification/website/result.ts
+//#region src/specification/facets/website/result.ts
 /** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
 var FetchResult = class extends BaseResult {
 	exchange;
@@ -879,7 +883,7 @@ var FetchResult = class extends BaseResult {
 	}
 	/** The `location` header of a redirect response, or undefined. */
 	get location() {
-		return this.exchange.headers["location"];
+		return this.exchange.headers.location;
 	}
 	/** The HTTP response status code — redirects surface as 3xx, never followed. */
 	get status() {
@@ -979,7 +983,7 @@ function namedMetas(metas) {
 	return named;
 }
 //#endregion
-//#region src/core/specification/shared/binding.ts
+//#region src/specification/facets/_common/binding.ts
 /**
 * Compose-binding resolution and the case conversions it shares with the
 * automatic env injection (CONVENTIONS A6 / B6).
@@ -995,7 +999,7 @@ function namedMetas(metas) {
 * `-`, everything is lowercased. `analyticsDb` → `analytics-db`, `db` → `db`.
 */
 function toKebabCase(key) {
-	return key.replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<lower>-$<upper>").toLowerCase();
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").toLowerCase();
 }
 /**
 * Convert a record key to CONSTANT_CASE for env injection: insert `_` at
@@ -1003,7 +1007,7 @@ function toKebabCase(key) {
 * uppercase. `analyticsDb` → `ANALYTICS_DB`, `db-main` → `DB_MAIN`, `db` → `DB`.
 */
 function toConstantCase(key) {
-	return key.replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<lower>_$<upper>").replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+	return key.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>_$<upper>").replaceAll(/[^A-Za-z0-9]/gu, "_").toUpperCase();
 }
 /**
 * Resolve the compose service a record key binds to (CONVENTIONS A6).
@@ -1028,7 +1032,7 @@ function resolveComposeBinding(key, explicitComposeName, serviceNames) {
 	return key;
 }
 //#endregion
-//#region src/core/specification/shared/builder.ts
+//#region src/specification/facets/_common/builder.ts
 /**
 * Fluent builder for declaring a single test specification.
 *
@@ -1146,8 +1150,8 @@ var SpecificationBuilder = class {
 	* @example
 	*   const result = await api.request("create-user.http");
 	*/
-	request(file) {
-		return this.executeHttp({
+	async request(file) {
+		return await this.executeHttp({
 			method: "",
 			path: "",
 			requestFile: file
@@ -1159,8 +1163,8 @@ var SpecificationBuilder = class {
 	* @example
 	*   const result = await api.get("/api/items");
 	*/
-	get(path) {
-		return this.executeHttp({
+	async get(path) {
+		return await this.executeHttp({
 			method: "GET",
 			path
 		});
@@ -1173,24 +1177,24 @@ var SpecificationBuilder = class {
 	* @example
 	*   const result = await api.post("/api/items", { name: "Widget" });
 	*/
-	post(path, body) {
-		return this.executeHttp({
+	async post(path, body) {
+		return await this.executeHttp({
 			body,
 			method: "POST",
 			path
 		});
 	}
 	/** Send a PUT request to the server adapter and resolve with the result. */
-	put(path, body) {
-		return this.executeHttp({
+	async put(path, body) {
+		return await this.executeHttp({
 			body,
 			method: "PUT",
 			path
 		});
 	}
 	/** Send a DELETE request to the server adapter and resolve with the result. */
-	delete(path) {
-		return this.executeHttp({
+	async delete(path) {
+		return await this.executeHttp({
 			method: "DELETE",
 			path
 		});
@@ -1215,10 +1219,10 @@ var SpecificationBuilder = class {
 	*   const result = await cli.exec(["init", "build"]);
 	*   const result = await cli.exec("dev --port 0", { waitFor: "Listening on", timeout: 10_000 });
 	*/
-	exec(args = "", options) {
+	async exec(args = "", options) {
 		if (Array.isArray(args) && args.length === 0) throw new Error("exec([]) requires at least one command");
 		if (options && Array.isArray(args)) throw new Error(".exec(): waitFor/timeout options are not supported with a command sequence");
-		return this.executeCommand({
+		return await this.executeCommand({
 			args,
 			options
 		});
@@ -1238,9 +1242,9 @@ var SpecificationBuilder = class {
 	*   const result = await cli.run('no-estate.spec.yaml');
 	*   await expect(result.directory('out')).toMatch('scaffold');
 	*/
-	run(file, options) {
+	async run(file, options) {
 		const workDir = this.prepareWorkDir();
-		return this.executeSetup(workDir, () => this.runLiterateAction(workDir, file, options));
+		return await this.executeSetup(workDir, async () => await this.runLiterateAction(workDir, file, options));
 	}
 	/**
 	* Perform one raw HTTP GET against the website under test and resolve
@@ -1253,8 +1257,8 @@ var SpecificationBuilder = class {
 	*   expect(result.status).toBe(200);
 	*   expect(result.body).toMatch('robots.txt');
 	*/
-	fetch(path) {
-		return this.executeSetup(null, () => this.runFetchAction(path));
+	async fetch(path) {
+		return await this.executeSetup(null, async () => await this.runFetchAction(path));
 	}
 	/**
 	* Render the page in the shared browser instance and resolve with the
@@ -1271,8 +1275,8 @@ var SpecificationBuilder = class {
 	*   });
 	*   expect(result.url).toContain('/articles');
 	*/
-	visit(path, scenario) {
-		return this.executeSetup(null, () => this.runVisitAction(path, scenario));
+	async visit(path, scenario) {
+		return await this.executeSetup(null, async () => await this.runVisitAction(path, scenario));
 	}
 	/**
 	* Terminate and relaunch the app on the simulator, apply the deep link,
@@ -1289,8 +1293,8 @@ var SpecificationBuilder = class {
 	*       await visitor.see(content('rapports'));
 	*   });
 	*/
-	open(deepLink, scenario) {
-		return this.executeSetup(null, () => this.runOpenAction(deepLink, scenario));
+	async open(deepLink, scenario) {
+		return await this.executeSetup(null, async () => await this.runOpenAction(deepLink, scenario));
 	}
 	/**
 	* Execute the named job registered via the `jobs` option of
@@ -1300,14 +1304,14 @@ var SpecificationBuilder = class {
 	*   const result = await jobs.intercept(classifyArticle).trigger('report-refresh');
 	*/
 	async trigger(name) {
-		return this.executeSetup(null, () => this.runJobAction(name));
+		return await this.executeSetup(null, async () => await this.runJobAction(name));
 	}
 	async executeHttp(request) {
-		return this.executeSetup(null, () => this.runHttpAction(request));
+		return await this.executeSetup(null, async () => await this.runHttpAction(request));
 	}
 	async executeCommand(action) {
 		const workDir = this.prepareWorkDir();
-		return this.executeSetup(workDir, () => this.runCommandAction(workDir, action));
+		return await this.executeSetup(workDir, async () => await this.runCommandAction(workDir, action));
 	}
 	/**
 	* Shared setup pipeline: reset databases, run seeds, copy fixtures,
@@ -1378,9 +1382,8 @@ var SpecificationBuilder = class {
 	}
 	async runFetchAction(path) {
 		const baseUrl = this.requireBaseUrl("fetch");
-		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
 		const response = await fetch(`${baseUrl}${path}`, {
-			headers,
+			headers: this.requestHeaders,
 			redirect: "manual"
 		});
 		const body = await response.text();
@@ -1453,7 +1456,7 @@ var SpecificationBuilder = class {
 	* redis). `.env()` overrides; `null` unsets.
 	*/
 	serviceEnv() {
-		const services = this.config.services;
+		const { services } = this.config;
 		if (!services || Object.keys(services).length === 0) return;
 		const env = {};
 		const sqlHandles = [];
@@ -1463,8 +1466,10 @@ var SpecificationBuilder = class {
 			if (handle.createDatabaseAdapter() !== null) sqlHandles.push(handle);
 			if (handle.type === "redis") redisHandles.push(handle);
 		}
-		if (sqlHandles.length === 1) env.DATABASE_URL = sqlHandles[0].connectionString;
-		if (redisHandles.length === 1) env.REDIS_URL = redisHandles[0].connectionString;
+		const [onlySql] = sqlHandles;
+		if (sqlHandles.length === 1 && onlySql !== void 0) env.DATABASE_URL = onlySql.connectionString;
+		const [onlyRedis] = redisHandles;
+		if (redisHandles.length === 1 && onlyRedis !== void 0) env.REDIS_URL = onlyRedis.connectionString;
 		return env;
 	}
 	/**
@@ -1474,7 +1479,7 @@ var SpecificationBuilder = class {
 	*/
 	childEnv(workDir) {
 		let env = this.serviceEnv();
-		const dockerConfig = this.config.dockerConfig;
+		const { dockerConfig } = this.config;
 		if (dockerConfig && this.config.dockerTestRunId) env = {
 			...env,
 			[dockerConfig.envVar]: this.config.dockerTestRunId
@@ -1486,9 +1491,9 @@ var SpecificationBuilder = class {
 		};
 		return env;
 	}
-	runLiterateAction(workDir, file, options) {
+	async runLiterateAction(workDir, file, options) {
 		const filePath = resolve(this.testDir, file);
-		return runSpecDocument({
+		return await runSpecDocument({
 			baseEnv: this.childEnv(workDir),
 			frozen: options?.frozen,
 			config: this.config,
@@ -1500,7 +1505,7 @@ var SpecificationBuilder = class {
 	}
 	async runCommandAction(workDir, action) {
 		if (!this.config.command) throw new Error("Command actions require a command adapter");
-		const dockerConfig = this.config.dockerConfig;
+		const { dockerConfig } = this.config;
 		const testRunId = this.config.dockerTestRunId;
 		const env = this.childEnv(workDir);
 		let commandOutput;
@@ -1549,13 +1554,13 @@ function withDockerTestRunId(config) {
 function createApiFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		delete: (path) => start().delete(path),
-		get: (path) => start().get(path),
+		delete: async (path) => await start().delete(path),
+		get: async (path) => await start().get(path),
 		headers: (headers) => start().headers(headers),
 		intercept: interceptOn(start),
-		post: (path, body) => start().post(path, body),
-		put: (path, body) => start().put(path, body),
-		request: (file) => start().request(file),
+		post: async (path, body) => await start().post(path, body),
+		put: async (path, body) => await start().put(path, body),
+		request: async (file) => await start().request(file),
 		seed: (file, options) => start().seed(file, options)
 	};
 }
@@ -1567,7 +1572,7 @@ function createJobsFacet(config) {
 	return {
 		intercept: interceptOn(start),
 		seed: (file, options) => start().seed(file, options),
-		trigger: (name) => start().trigger(name)
+		trigger: async (name) => await start().trigger(name)
 	};
 }
 /**
@@ -1576,10 +1581,10 @@ function createJobsFacet(config) {
 function createWebsiteFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
-		fetch: (path) => start().fetch(path),
+		fetch: async (path) => await start().fetch(path),
 		headers: (headers) => start().headers(headers),
 		intercept: interceptOn(start),
-		visit: (path, scenario) => start().visit(path, scenario)
+		visit: async (path, scenario) => await start().visit(path, scenario)
 	};
 }
 /**
@@ -1589,7 +1594,7 @@ function createMobileFacet(config) {
 	const start = () => new SpecificationBuilder(config, getCallerDir());
 	return {
 		intercept: interceptOn(start),
-		open: (deepLink, scenario) => start().open(deepLink, scenario)
+		open: async (deepLink, scenario) => await start().open(deepLink, scenario)
 	};
 }
 /**
@@ -1600,14 +1605,14 @@ function createCliFacet(config) {
 	const start = () => new SpecificationBuilder(resolved, getCallerDir());
 	return {
 		env: (env) => start().env(env),
-		exec: (args, options) => start().exec(args, options),
+		exec: async (args, options) => await start().exec(args, options),
 		fixture: (path) => start().fixture(path),
-		run: (file, options) => start().run(file, options),
+		run: async (file, options) => await start().run(file, options),
 		seed: (file, options) => start().seed(file, options)
 	};
 }
 //#endregion
-//#region src/core/specification/shared/docker-reader.ts
+//#region src/specification/facets/_common/docker-reader.ts
 /**
 * Build the `docker(containerId)` reader handed out by `specification.api()`
 * and `specification.cli()` — a lazy accessor over `docker inspect`.
@@ -1622,7 +1627,7 @@ function createDockerReader(testDir) {
 	};
 }
 //#endregion
-//#region src/core/specification/shared/compose-file.ts
+//#region src/specification/facets/_common/compose-file.ts
 /**
 * Detect the service type from the image name.
 */
@@ -1648,7 +1653,7 @@ function findComposeFile(projectRoot) {
 	return null;
 }
 //#endregion
-//#region src/core/specification/shared/orchestrator.ts
+//#region src/specification/facets/_common/orchestrator.ts
 /**
 * Orchestrator for test infrastructure.
 * Integration: starts services via testcontainers.
@@ -1721,7 +1726,9 @@ var Orchestrator = class {
 				handle
 			});
 		}
-		await Promise.all([...containerServices.map(({ container }) => container.start()), ...embeddedServices.map(async (handle) => {
+		await Promise.all([...containerServices.map(async ({ container }) => {
+			await container.start();
+		}), ...embeddedServices.map(async (handle) => {
 			await handle.initialize(composeDir, this.root);
 			handle.started = true;
 			this.running.push({
@@ -1880,13 +1887,14 @@ var Orchestrator = class {
 	getAppUrl() {
 		const composePath = findComposeFile(this.root);
 		if (!composePath || !this.composeStack) return null;
-		const appService = getContainerIntegrations().parseComposeFile(composePath).appService;
-		if (!appService || appService.ports.length === 0) return null;
-		return `http://localhost:${this.composeStack.getMappedPort(appService.name, appService.ports[0].container)}`;
+		const { appService } = getContainerIntegrations().parseComposeFile(composePath);
+		const [firstPort] = appService?.ports ?? [];
+		if (!appService || firstPort === void 0) return null;
+		return `http://localhost:${this.composeStack.getMappedPort(appService.name, firstPort.container)}`;
 	}
 };
 //#endregion
-//#region src/core/specification/shared/services.ts
+//#region src/specification/facets/_common/services.ts
 function getWorkerId() {
 	return process.env.VITEST_POOL_ID ?? "0";
 }
@@ -1898,7 +1906,7 @@ async function releaseIsolation(services) {
 	for (const service of Object.values(services)) await service.isolation().release();
 }
 function declaredDatabaseKeys(services) {
-	return Object.keys(services).filter((key) => services[key].createDatabaseAdapter() !== null);
+	return Object.entries(services).filter(([, service]) => service.createDatabaseAdapter() !== null).map(([key]) => key);
 }
 /** Start a services record via testcontainers and acquire worker isolation. */
 async function startServices(services, root) {
@@ -1917,7 +1925,7 @@ async function startServices(services, root) {
 	};
 }
 //#endregion
-//#region src/core/specification/api/fetch.adapter.ts
+//#region src/specification/facets/api/fetch.adapter.ts
 /**
 * Transient connection-level failures against a live compose app. Under
 * parallel load (every `api-stack` worker hammering its own compose project)
@@ -1940,7 +1948,9 @@ function isTransientConnectionError(error) {
 	const cause = error.cause;
 	return cause?.code !== void 0 && TRANSIENT_CONNECTION_CODES.has(cause.code) || error.message.includes("fetch failed");
 }
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const delay = async (ms) => {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+};
 /**
 * Server adapter that sends real HTTP requests via the Fetch API.
 * Used by the `e2e()` specification runner to hit a live server.
@@ -1948,7 +1958,7 @@ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var FetchAdapter = class {
 	baseUrl;
 	constructor(url) {
-		this.baseUrl = url.replace(/\/$/, "");
+		this.baseUrl = url.replace(/\/$/u, "");
 	}
 	async request(method, path, body, headers) {
 		const init = {
@@ -1986,7 +1996,7 @@ var FetchAdapter = class {
 	}
 };
 //#endregion
-//#region src/core/specification/api/start-api.ts
+//#region src/specification/facets/api/start-api.ts
 function resolveMode(explicit) {
 	const value = explicit ?? process.env.TEST_MODE ?? "node";
 	if (value !== "compose" && value !== "node") throw new Error(`Invalid test mode "${value}" — expected 'node' or 'compose' (options.mode or TEST_MODE).`);
@@ -2035,13 +2045,15 @@ async function startApi(options) {
 			interceptDisabledReason: "intercepts are in-process (MSW) and not available in compose mode — keep intercept specs in node-only vitest projects.",
 			server: new FetchAdapter(appUrl)
 		}),
-		cleanup: () => orchestrator.stopCompose(),
+		cleanup: async () => {
+			await orchestrator.stopCompose();
+		},
 		docker: createDockerReader(callerDir),
 		orchestrator
 	};
 }
 //#endregion
-//#region src/core/specification/cli/exec.adapter.ts
+//#region src/specification/facets/cli/exec.adapter.ts
 const DEFAULT_WATCH_TIMEOUT = 1e4;
 /** Grace period between SIGTERM and the SIGKILL escalation. */
 const KILL_GRACE_MS = 2e3;
@@ -2070,17 +2082,19 @@ function buildEnv(extra) {
 *
 * @internal Exported for unit tests (driven with a fake child).
 */
-function observeProcess(child, options) {
+async function observeProcess(child, options) {
 	const timeout = options.timeout ?? DEFAULT_WATCH_TIMEOUT;
-	const waitFor = options.waitFor;
-	return new Promise((resolve) => {
+	const { waitFor } = options;
+	return await new Promise((resolve) => {
 		let stdout = "";
 		let stderr = "";
 		let resolved = false;
 		let exited = false;
 		let patternMatched = false;
 		let killTimer = null;
-		const timeoutTimer = setTimeout(() => finish(124), timeout);
+		const timeoutTimer = setTimeout(() => {
+			finish(124);
+		}, timeout);
 		timeoutTimer.unref?.();
 		const terminate = () => {
 			if (exited) return;
@@ -2185,7 +2199,7 @@ var ExecAdapter = class {
 			} catch {}
 			return child.kill(signal);
 		};
-		return observeProcess({
+		return await observeProcess({
 			kill,
 			on: child.on.bind(child),
 			stderr: child.stderr,
@@ -2194,7 +2208,7 @@ var ExecAdapter = class {
 	}
 };
 //#endregion
-//#region src/core/specification/cli/start-cli.ts
+//#region src/specification/facets/cli/start-cli.ts
 async function startCli(bin, options = {}) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2226,7 +2240,7 @@ async function startCli(bin, options = {}) {
 	};
 }
 //#endregion
-//#region src/core/specification/jobs/start-jobs.ts
+//#region src/specification/facets/jobs/start-jobs.ts
 async function startJobs(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2251,7 +2265,7 @@ async function startJobs(options) {
 	};
 }
 //#endregion
-//#region src/core/specification/shared/stub-backend.ts
+//#region src/specification/facets/_common/stub-backend.ts
 /**
 * The declared stub backend — a small `node:http` server the website and
 * mobile runners start when their `backend` option is present. It serves the
@@ -2295,7 +2309,9 @@ var StubBackend = class {
 		this.server = server;
 		await new Promise((resolve, reject) => {
 			server.once("error", reject);
-			server.listen(this.options.port ?? 0, "127.0.0.1", () => resolve());
+			server.listen(this.options.port ?? 0, "127.0.0.1", () => {
+				resolve();
+			});
 		});
 		const address = server.address();
 		if (address === null || typeof address === "string") throw new Error("stub backend: could not determine the listening port");
@@ -2304,12 +2320,14 @@ var StubBackend = class {
 	}
 	/** Stop the server (idempotent). */
 	async stop() {
-		const server = this.server;
+		const { server } = this;
 		if (!server) return;
 		this.server = null;
 		server.closeAllConnections();
 		await new Promise((resolve) => {
-			server.close(() => resolve());
+			server.close(() => {
+				resolve();
+			});
 		});
 	}
 	/**
@@ -2423,7 +2441,7 @@ async function readBody(request) {
 	}
 }
 //#endregion
-//#region src/core/specification/mobile/appium-server.ts
+//#region src/specification/facets/mobile/appium-server.ts
 const APPIUM_READY_TIMEOUT_MS = 6e4;
 /**
 * The guidance thrown when the optional peers are missing — the exact fix,
@@ -2447,12 +2465,14 @@ async function startAppiumServer(root) {
 		timeout: APPIUM_READY_TIMEOUT_MS
 	}, root, "mobile");
 	return {
-		stop: () => serve.stop(),
+		stop: async () => {
+			await serve.stop();
+		},
 		url: await serve.start()
 	};
 }
 //#endregion
-//#region src/core/specification/mobile/simulator.ts
+//#region src/specification/facets/mobile/simulator.ts
 /**
 * Simulator resolution — `device: { name, os? }` → one booted UDID.
 *
@@ -2465,8 +2485,10 @@ const run = promisify(execFile);
 const BOOT_TIMEOUT_MS = 12e4;
 /** `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `iOS 26.5`. */
 function runtimeLabel(runtime) {
-	const match = /SimRuntime\.(?<platform>[A-Za-z]+)-(?<version>[\d-]+)$/.exec(runtime);
-	return match?.groups ? `${match.groups["platform"]} ${match.groups["version"].replaceAll("-", ".")}` : runtime;
+	const match = /SimRuntime\.(?<platform>[A-Za-z]+)-(?<version>[\d-]+)$/u.exec(runtime);
+	const platform = match?.groups?.platform;
+	const version = match?.groups?.version;
+	return platform === void 0 || version === void 0 ? runtime : `${platform} ${version.replaceAll("-", ".")}`;
 }
 /** Flatten the per-runtime record into one available-device list. */
 function listSimulators(listJson) {
@@ -2495,9 +2517,10 @@ function selectSimulator(listJson, criteria) {
 	const available = listSimulators(listJson);
 	const matches = available.filter((device) => device.name === criteria.name && (criteria.os === void 0 || osMatches(device.os, criteria.os)));
 	const wanted = criteria.os === void 0 ? `"${criteria.name}"` : `"${criteria.name}" on ${criteria.os}`;
-	if (matches.length === 0) throw new Error(`specification.mobile(): no simulator matches ${wanted}.\nAvailable devices:\n${formatListing(available)}`);
+	const [only] = matches;
+	if (only === void 0) throw new Error(`specification.mobile(): no simulator matches ${wanted}.\nAvailable devices:\n${formatListing(available)}`);
 	if (matches.length > 1) throw new Error(`specification.mobile(): ${matches.length} simulators match ${wanted} — add \`os:\` or \`udid:\` to pick one.\nMatched:\n${formatListing(matches)}`);
-	return matches[0];
+	return only;
 }
 /** Resolve `device: { name, os? }` to a UDID via `xcrun simctl`. */
 async function resolveSimulatorUdid(criteria) {
@@ -2533,7 +2556,7 @@ async function ensureBooted(udid) {
 	], { timeout: BOOT_TIMEOUT_MS });
 }
 //#endregion
-//#region src/core/specification/mobile/start-mobile.ts
+//#region src/specification/facets/mobile/start-mobile.ts
 async function startMobile(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2580,7 +2603,7 @@ async function startMobile(options) {
 	};
 }
 //#endregion
-//#region src/core/specification/website/start-website.ts
+//#region src/specification/facets/website/start-website.ts
 async function startWebsite(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
@@ -2602,7 +2625,7 @@ async function startWebsite(options) {
 			await backend?.stop();
 			throw error;
 		}
-	} else baseUrl = options.url.replace(/\/$/, "");
+	} else baseUrl = options.url.replace(/\/$/u, "");
 	let browser = null;
 	const getBrowser = async () => {
 		if (!browser) {
@@ -2632,31 +2655,7 @@ async function startWebsite(options) {
 	};
 }
 //#endregion
-//#region src/core/specification/shared/specification.ts
-/**
-* The five specification constructors (CONVENTIONS A2) — created in a
-* `*.specification.ts` file under `specs/`, destructured with canonical
-* names, and cleaned up via `afterAll(cleanup)` (A1/A3/A4).
-*
-* @example
-*   // specs/api/api.specification.ts
-*   export const { api, cleanup } = await specification.api({
-*       services: { db: postgres() },
-*       server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
-*   });
-*   afterAll(cleanup);
-*
-*   // specs/jobs/jobs.specification.ts
-*   export const { jobs, cleanup } = await specification.jobs({
-*       services: { db: postgres() },
-*       jobs: ({ db }) => [nightlyReport(db)],
-*   });
-*   afterAll(cleanup);
-*
-*   // specs/setup/cli.specification.ts
-*   export const { cli, cleanup } = await specification.cli('my-cli');
-*   afterAll(cleanup);
-*/
+//#region src/specification/facets/_common/specification.ts
 const specification = {
 	/**
 	* Test an HTTP app. Mode `'node'` (default) starts the declared services
@@ -2694,7 +2693,7 @@ const specification = {
 	website: startWebsite
 };
 //#endregion
-//#region src/core/specification/website/elements.ts
+//#region src/specification/facets/website/elements.ts
 const named = (kind) => (name, options) => ({
 	kind,
 	name,
@@ -3078,7 +3077,7 @@ function sqlite(options = {}) {
 	return new SqliteHandle(options);
 }
 //#endregion
-//#region src/core/contracts/filters.ts
+//#region src/specification/contracts/filters.ts
 /** Does an observed text satisfy a declared {@link TextFilter}? */
 function matchesText(filter, actual) {
 	if (filter === void 0) return true;
@@ -3152,7 +3151,9 @@ const anthropic = {
 		};
 	},
 	/** Response: wrap data in Anthropic messages format. */
-	reply: buildReply,
+	reply(data) {
+		return buildReply(data);
+	},
 	/** Response: return an Anthropic error. */
 	error(status, message) {
 		return {
@@ -3176,7 +3177,7 @@ const anthropic = {
 	}
 };
 //#endregion
-//#region src/core/contracts/http.ts
+//#region src/specification/contracts/http.ts
 function wrapJson(data) {
 	return {
 		status: 200,
@@ -3426,7 +3427,9 @@ const openai = {
 	* @example
 	*   openai.reply({ categories: ['TECH'] })
 	*/
-	reply: buildChatReply,
+	reply(data) {
+		return buildChatReply(data);
+	},
 	/** Response: return an OpenAI error. */
 	error(status, message) {
 		return {