@jterrazz/test 12.1.0 → 13.0.0

package/dist/literate.js

@@ -0,0 +1,1726 @@
+import { i as SpecSyntaxError, l as updateSpecFile, s as readSpecFile } from "./spec-document.js";
+import { a as copyPlan, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
+import { cpSync, existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { execSync, spawn } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:net";
+//#region src/core/matching/structural.ts
+/**
+* Structural comparison engine shared by every fixture matcher.
+*
+* Handles three kinds of "expected" values:
+* - plain JSON values → strict deep equality
+* - {@link Matcher} instances (code-side `match.*`)
+* - strings containing `{{placeholder}}` forms (file-side fixtures)
+*
+* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
+* works in `expected/*.http` (body and headers), `expected/*.json`, and
+* text snapshots (`expected/*.txt`).
+*
+* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
+* {@link CaptureScope} supplied by the caller.
+*/
+const UUID_SOURCE = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
+const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
+const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
+const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
+const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
+const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
+const INT_SOURCE = String.raw`-?\d+`;
+const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
+const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
+const SHA_SOURCE = "[0-9a-f]{7,64}";
+const HEX_SOURCE = "[0-9a-fA-F]+";
+const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
+const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
+const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
+const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
+const EMBEDDED_SOURCES = {
+	base64: BASE64_SOURCE,
+	date: DATE_SOURCE,
+	duration: DURATION_SOURCE,
+	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
+	float: FLOAT_SOURCE,
+	hex: HEX_SOURCE,
+	int: INT_SOURCE,
+	ip: IP_SOURCE,
+	iso8601: ISO8601_SOURCE,
+	number: NUMBER_SOURCE,
+	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
+	port: PORT_SOURCE,
+	semver: SEMVER_SOURCE,
+	sha: SHA_SOURCE,
+	time: TIME_SOURCE,
+	ulid: ULID_SOURCE,
+	url: URL_SOURCE,
+	uuid: UUID_SOURCE
+};
+const wholeRe = (source) => new RegExp(`^(?:${source})$`);
+const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
+const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "g");
+/** Whether a fixture string contains at least one `{{placeholder}}`. */
+function hasPlaceholders(value) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	return PLACEHOLDER_RE.test(value);
+}
+/** Key-order-independent stringification for captured-object comparison. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function capturedEquals(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
+	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
+	return false;
+}
+function recordRef(name, actual, scope) {
+	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
+	scope.set(name, actual);
+	return true;
+}
+function isPortValue(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+function kindMatches(kind, actual, scope) {
+	switch (kind) {
+		case "any": return true;
+		case "float":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.float.test(actual);
+		case "int":
+			if (typeof actual === "number") return Number.isInteger(actual);
+			return typeof actual === "string" && WHOLE_RES.int.test(actual);
+		case "number":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.number.test(actual);
+		case "port":
+			if (typeof actual === "number") return isPortValue(actual);
+			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
+		case "string": return typeof actual === "string";
+		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
+		default: {
+			const re = WHOLE_RES[kind];
+			return re !== void 0 && typeof actual === "string" && re.test(actual);
+		}
+	}
+}
+function matcherMatches(matcher, actual, scope) {
+	if (matcher.kind === "includes") return typeof actual === "string" && actual.includes(matcher.includes);
+	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
+	if (matcher.kind === "ref") {
+		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
+		return recordRef(matcher.refName, actual, scope);
+	}
+	return kindMatches(matcher.kind, actual, scope);
+}
+function placeholderSource(kind, scope) {
+	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
+	const source = EMBEDDED_SOURCES[kind];
+	if (source) return source;
+	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+function parsePlaceholderString(expected, scope) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	const refs = [];
+	let source = "";
+	let lastIndex = 0;
+	let single = null;
+	let count = 0;
+	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
+		const kind = found.groups.kind;
+		const ref = found.groups.ref;
+		source += escapeRegExp(expected.slice(lastIndex, found.index));
+		source += `(${placeholderSource(kind, scope)})`;
+		refs.push({
+			index: count,
+			kind,
+			ref
+		});
+		count++;
+		lastIndex = found.index + found[0].length;
+		if (found.index === 0 && found[0].length === expected.length) single = {
+			kind,
+			ref
+		};
+	}
+	source += escapeRegExp(expected.slice(lastIndex));
+	return {
+		pattern: new RegExp(`^${source}$`),
+		refs,
+		single,
+		source
+	};
+}
+/**
+* Unanchored regex source matching a fixture string — plain text escaped
+* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
+* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
+*/
+function placeholderPatternSource(expected) {
+	return parsePlaceholderString(expected, new CaptureScope()).source;
+}
+function placeholderStringMatches(expected, actual, scope) {
+	const parsed = parsePlaceholderString(expected, scope);
+	if (parsed.single) {
+		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
+		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
+		return true;
+	}
+	if (typeof actual !== "string" && typeof actual !== "number") return false;
+	const text = String(actual);
+	const found = parsed.pattern.exec(text);
+	if (!found) return false;
+	for (const entry of parsed.refs) {
+		if (!entry.ref) continue;
+		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
+	}
+	return true;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Deep structural equality with matcher / placeholder support. Ref captures
+* are recorded in `scope` in traversal order (arrays left-to-right, object
+* keys in expected-key order).
+*/
+function structuralEquals(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		const expectedKeys = Object.keys(expected);
+		const actualKeys = Object.keys(actual);
+		if (expectedKeys.length !== actualKeys.length) return false;
+		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Deep structural SUBSET match (toMatchObject-style) with matcher /
+* placeholder support. Plain objects match when every expected key is present
+* and recursively subset-matches — the actual value may carry extra keys.
+* Arrays require equal length with each element subset-matched. Leaves fall
+* back to {@link structuralEquals} semantics (matchers, placeholders, strict
+* equality). Used by request-body filters on intercept triggers.
+*/
+function structuralSubset(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Multi-line text comparison with `{{token}}` support — used by text
+* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
+*/
+function textEquals(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return expected === actual;
+	return placeholderStringMatches(expected, actual, scope);
+}
+/**
+* Substring comparison with `{{token}}` support — the `contains` half of the
+* `files:` assertions of a spec document. Without placeholders this is
+* `String.includes`; with them the fixture text becomes an UNANCHORED pattern,
+* so `wrote {{path}}` is found inside a larger file, and its `#ref` captures are
+* recorded exactly as a whole-text comparison records them.
+*/
+function textContains(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return actual.includes(expected);
+	const parsed = parsePlaceholderString(expected, scope);
+	const found = new RegExp(parsed.source).exec(actual);
+	if (!found) return false;
+	return parsed.refs.every((entry) => !entry.ref || recordRef(entry.ref, found[entry.index + 1], scope));
+}
+/**
+* Render an expected value for failure diffs and serialization: Matcher
+* instances become their placeholder text, everything else is untouched.
+*/
+function renderExpected(value) {
+	if (value instanceof Matcher) return value.toString();
+	if (Array.isArray(value)) return value.map((item) => renderExpected(item));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderExpected(item)]));
+	return value;
+}
+/**
+* Substitute the framework-known cwd (`workdir`) for its `{{workdir}}` token in
+* every string leaf of a structured value. The structural mirror of the text
+* path's `actual.replaceAll(workdir, '{{workdir}}')` — so a golden written under
+* `TEST_UPDATE=1` stores the token, not a run-specific temp path (CONVENTIONS
+* D5). A no-op when `workdir` is undefined (no cwd, e.g. api/jobs mode).
+*/
+function substituteWorkdirDeep(value, workdir) {
+	if (typeof value === "string") return value.replaceAll(workdir, "{{workdir}}");
+	if (Array.isArray(value)) return value.map((item) => substituteWorkdirDeep(item, workdir));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteWorkdirDeep(item, workdir)]));
+	return value;
+}
+/**
+* Update-mode merge: rewrite a fixture from the actual output while
+* preserving every segment of the previous fixture that was covered by a
+* placeholder (and still matches the actual value).
+*
+* Token preservation is symmetric with the text path (CONVENTIONS D5): a
+* previous `{{placeholder}}` (including `{{workdir}}`) that still matches the
+* RAW actual value is kept; every other leaf is taken from the actual output
+* with the framework-known cwd substituted back to `{{workdir}}`.
+*/
+function mergePreservingPlaceholders(previous, actual, workdir) {
+	const scope = new CaptureScope(workdir);
+	const subst = (value) => workdir === void 0 ? value : substituteWorkdirDeep(value, workdir);
+	function merge(prev, act) {
+		if (typeof prev === "string" && hasPlaceholders(prev)) return placeholderStringMatches(prev, act, scope) ? prev : subst(act);
+		if (Array.isArray(prev) && Array.isArray(act)) return act.map((item, i) => i < prev.length ? merge(prev[i], item) : subst(item));
+		if (isPlainObject(prev) && isPlainObject(act)) return Object.fromEntries(Object.entries(act).map(([key, item]) => [key, key in prev ? merge(prev[key], item) : subst(item)]));
+		return subst(act);
+	}
+	return merge(previous, actual);
+}
+/**
+* Update-mode merge for text snapshots: a previous line whose placeholders
+* still match an actual line is preserved; every other line is taken from the
+* actual output. Values the framework knows to be dynamic (`{{workdir}}`) are
+* substituted automatically (CONVENTIONS D5).
+*
+* Pairing is by **pattern, not by line index**. The aligned line is tried
+* first, so a golden that still lines up comes back byte-identical; what is
+* left over is then re-paired by matching each remaining previous placeholder
+* line against each unresolved actual line, in file order. That is what makes a
+* MID-FILE INSERTION safe: inserting a line shifts everything below it, and the
+* shifted `{{duration}}` / `{{uuid}}` lines are recognised where they landed
+* instead of being rewritten as raw values. Each previous line is used at most
+* once, so two identical placeholder lines cannot collapse into one.
+*/
+function mergeTextPreservingPlaceholders(previous, actual, scope) {
+	const substituted = scope.workdir === void 0 ? actual : actual.replaceAll(scope.workdir, "{{workdir}}");
+	if (previous === null) return substituted;
+	const prevLines = previous.split("\n");
+	const actualLines = substituted.split("\n");
+	const rawLines = actual.split("\n");
+	const consumed = /* @__PURE__ */ new Set();
+	const covers = (prevIndex, actualIndex) => {
+		const prev = prevLines[prevIndex];
+		if (prev === void 0 || !hasPlaceholders(prev)) return false;
+		const line = actualLines[actualIndex];
+		return textEquals(prev, line, new CaptureScope(scope.workdir)) || textEquals(prev, rawLines[actualIndex] ?? line, new CaptureScope(scope.workdir));
+	};
+	const merged = actualLines.map(() => void 0);
+	for (const [index] of actualLines.entries()) if (covers(index, index)) {
+		merged[index] = prevLines[index];
+		consumed.add(index);
+	}
+	for (const [index, line] of actualLines.entries()) {
+		if (merged[index] !== void 0) continue;
+		for (const [prevIndex] of prevLines.entries()) {
+			if (consumed.has(prevIndex) || !covers(prevIndex, index)) continue;
+			merged[index] = prevLines[prevIndex];
+			consumed.add(prevIndex);
+			break;
+		}
+		merged[index] ??= line;
+	}
+	return merged.join("\n");
+}
+//#endregion
+//#region src/core/specification/shared/reporter.ts
+const GREEN = "\x1B[32m";
+const RED = "\x1B[31m";
+const DIM = "\x1B[2m";
+const BOLD = "\x1B[1m";
+const RESET = "\x1B[0m";
+const BG_CYAN = "\x1B[46m";
+const BLACK = "\x1B[30m";
+const CHECK = "✓";
+const CROSS = "×";
+const ARROW = "→";
+function formatStartupReport(mode, services, app) {
+	const lines = [];
+	lines.push("");
+	lines.push(`${BG_CYAN}${BLACK}${BOLD} INFRA ${RESET} Starting infrastructure...`);
+	lines.push("");
+	for (const service of services) if (service.error) {
+		lines.push(`  ${RED}${CROSS}${RESET} ${service.type} (${service.name})  ${RED}${service.error}${RESET}  ${DIM}${service.durationMs}ms${RESET}`);
+		if (service.logs) {
+			const logLines = service.logs.trim().split("\n").slice(-10);
+			for (const logLine of logLines) lines.push(`    ${DIM}${logLine}${RESET}`);
+		}
+	} else {
+		const conn = service.connectionString ? `${DIM}${service.connectionString}${RESET}` : "";
+		lines.push(`  ${GREEN}${CHECK}${RESET} ${service.type} (${service.name})  ${conn}  ${DIM}${service.durationMs}ms${RESET}`);
+	}
+	if (app) {
+		lines.push("");
+		if (app.type === "in-process") lines.push(`  ${DIM}${ARROW} app: in-process (Hono)${RESET}`);
+		else lines.push(`  ${DIM}${ARROW} app: ${app.url}${RESET}`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+function formatTableDiff(table, columns, expected, actual) {
+	const lines = [];
+	lines.push(`Table "${table}" mismatch`);
+	lines.push(`${DIM}  query: ${columns.join(", ")}${RESET}`);
+	lines.push(`${DIM}  expected: ${rowLabel(expected.length)}${RESET}`);
+	lines.push(`${DIM}  received: ${rowLabel(actual.length)}${RESET}`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected${RESET}`);
+	lines.push(`${RED}+ Received${RESET}`);
+	lines.push("");
+	const header = columns.join("  |  ");
+	lines.push(`${DIM}  ${header}${RESET}`);
+	const maxRows = Math.max(expected.length, actual.length);
+	for (let i = 0; i < maxRows; i++) {
+		const exp = expected[i];
+		const act = actual[i];
+		if (exp && !act) lines.push(`${GREEN}- ${formatRow(exp)}${RESET}`);
+		else if (!exp && act) lines.push(`${RED}+ ${formatRow(act)}${RESET}`);
+		else if (exp && act) if (JSON.stringify(exp) === JSON.stringify(act)) lines.push(`  ${formatRow(act)}`);
+		else {
+			lines.push(`${GREEN}- ${formatRow(exp)}${RESET}`);
+			lines.push(`${RED}+ ${formatRow(act)}${RESET}`);
+		}
+	}
+	if (expected.length === 0 && actual.length === 0) lines.push(`  (empty)`);
+	return lines.join("\n");
+}
+function formatResponseDiff(file, expected, actual) {
+	const lines = [];
+	lines.push(`Response mismatch (${file})`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected${RESET}`);
+	lines.push(`${RED}+ Received${RESET}`);
+	lines.push("");
+	const expectedLines = JSON.stringify(expected, null, 2).split("\n");
+	const actualLines = JSON.stringify(actual, null, 2).split("\n");
+	const maxLines = Math.max(expectedLines.length, actualLines.length);
+	for (let i = 0; i < maxLines; i++) {
+		const exp = expectedLines[i];
+		const act = actualLines[i];
+		if (exp === act) lines.push(`  ${exp}`);
+		else {
+			if (exp !== void 0) lines.push(`${GREEN}- ${exp}${RESET}`);
+			if (act !== void 0) lines.push(`${RED}+ ${act}${RESET}`);
+		}
+	}
+	return lines.join("\n");
+}
+const strictEquals = (expected, actual) => expected === actual;
+function renderLines(expectedLines, actualLines, equals) {
+	const rendered = [];
+	let marked = 0;
+	const maxLines = Math.max(expectedLines.length, actualLines.length);
+	for (let i = 0; i < maxLines; i++) {
+		const exp = expectedLines[i];
+		const act = actualLines[i];
+		if (exp !== void 0 && act !== void 0 && equals(exp, act)) {
+			rendered.push(`  ${exp}`);
+			continue;
+		}
+		marked++;
+		if (exp !== void 0) rendered.push(`${GREEN}- ${exp}${RESET}`);
+		if (act !== void 0) rendered.push(`${RED}+ ${act}${RESET}`);
+	}
+	return {
+		marked,
+		rendered
+	};
+}
+/**
+* Render an expected/received diff over two texts.
+*
+* `equals` is how a line is judged EQUAL. Callers that compare through the
+* `{{token}}` grammar pass a token-aware predicate, so a `{{url}}` line that
+* matched is shown as equal — with its token, not as a `-`/`+` pair against
+* the concrete URL. Marking a line the comparison ACCEPTED buries the one it
+* rejected: the reader then has to work out which of the differences is the
+* actual cause.
+*
+* Safety net: if the token-aware pass marks nothing at all, the whole diff
+* would render as a clean block against a failure that really happened (a
+* `#ref` captured inconsistently across lines, say). The strict rendering is
+* used instead, so a diff always shows the reader something.
+*/
+function formatStdoutDiff(file, expected, actual, options) {
+	const lines = [];
+	lines.push(`Output mismatch (${file})`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected${RESET}`);
+	lines.push(`${RED}+ Received${RESET}`);
+	lines.push("");
+	const expectedLines = expected.split("\n");
+	const actualLines = actual.split("\n");
+	const equals = options?.equals ?? strictEquals;
+	const first = renderLines(expectedLines, actualLines, equals);
+	const rendered = first.marked === 0 && equals !== strictEquals ? renderLines(expectedLines, actualLines, strictEquals).rendered : first.rendered;
+	return [...lines, ...rendered].join("\n");
+}
+function formatDirectoryDiff(fixtureName, diff, hint) {
+	const lines = [];
+	const total = diff.added.length + diff.removed.length + diff.changed.length;
+	lines.push(`Directory mismatch: ${BOLD}${fixtureName}${RESET}`);
+	lines.push(`${DIM}  ${total} difference${total === 1 ? "" : "s"}: ${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} changed${RESET}`);
+	lines.push("");
+	lines.push(`${GREEN}- Expected (fixture)${RESET}`);
+	lines.push(`${RED}+ Received (generated)${RESET}`);
+	lines.push("");
+	for (const path of diff.added) lines.push(`${RED}+ added    ${path}${RESET}  ${DIM}(not in fixture)${RESET}`);
+	for (const path of diff.removed) lines.push(`${GREEN}- removed  ${path}${RESET}  ${DIM}(in fixture, not generated)${RESET}`);
+	for (const { path, expected, actual } of diff.changed) {
+		const expectedLines = expected.split("\n");
+		const actualLines = actual.split("\n");
+		const changedCount = countLineDifferences(expectedLines, actualLines);
+		lines.push(`${BOLD}~ changed  ${path}${RESET}  ${DIM}(${changedCount} line${changedCount === 1 ? "" : "s"} differ)${RESET}`);
+		let shown = 0;
+		const maxShown = 5;
+		const maxLines = Math.max(expectedLines.length, actualLines.length);
+		for (let i = 0; i < maxLines && shown < maxShown; i++) {
+			const exp = expectedLines[i];
+			const act = actualLines[i];
+			if (exp !== act) {
+				lines.push(`${DIM}    line ${i + 1}:${RESET}`);
+				if (exp !== void 0) lines.push(`    ${GREEN}- ${exp}${RESET}`);
+				if (act !== void 0) lines.push(`    ${RED}+ ${act}${RESET}`);
+				shown++;
+			}
+		}
+		if (changedCount > maxShown) lines.push(`    ${DIM}... ${changedCount - maxShown} more line(s)${RESET}`);
+	}
+	lines.push("");
+	lines.push(`${DIM}${hint}${RESET}`);
+	return lines.join("\n");
+}
+function countLineDifferences(expected, actual) {
+	let count = 0;
+	const max = Math.max(expected.length, actual.length);
+	for (let i = 0; i < max; i++) if (expected[i] !== actual[i]) count++;
+	return count;
+}
+function rowLabel(n) {
+	return n === 1 ? "1 row" : `${n} rows`;
+}
+function formatRow(row) {
+	return row.map((v) => String(v ?? "null")).join("  |  ");
+}
+//#endregion
+//#region src/core/specification/shared/result/directory.ts
+const DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	".next",
+	"dist",
+	".turbo",
+	".cache"
+];
+/**
+* Recursively walk a directory, returning sorted relative paths of files only.
+*/
+async function walkDirectory(root, options = {}) {
+	const ignores = /* @__PURE__ */ new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignores.has(entry)) continue;
+			const abs = resolve(current, entry);
+			const stat = statSync(abs);
+			if (stat.isDirectory()) await walk(abs);
+			else if (stat.isFile()) out.push(relative(root, abs).split(sep).join("/"));
+		}
+	}
+	await walk(root);
+	out.sort();
+	return out;
+}
+/**
+* Compare two directory trees file-by-file. Fixture file contents honor the
+* unified `{{token}}` grammar (CONVENTIONS D4) — captures are recorded in
+* `scope` in sorted-path order.
+*/
+async function diffDirectories(expectedRoot, actualRoot, options = {}) {
+	const expectedFiles = await walkDirectory(expectedRoot, options);
+	const actualFiles = await walkDirectory(actualRoot, options);
+	const expectedSet = new Set(expectedFiles);
+	const actualSet = new Set(actualFiles);
+	const scope = options.scope ?? new CaptureScope();
+	const added = actualFiles.filter((f) => !expectedSet.has(f));
+	const removed = expectedFiles.filter((f) => !actualSet.has(f));
+	const changed = [];
+	for (const file of expectedFiles) {
+		if (!actualSet.has(file)) continue;
+		const expected = readFileSync(resolve(expectedRoot, file), "utf8");
+		const actual = readFileSync(resolve(actualRoot, file), "utf8");
+		if (!textEquals(expected, actual, scope)) changed.push({
+			actual,
+			expected,
+			path: file
+		});
+	}
+	return {
+		added,
+		changed,
+		removed
+	};
+}
+/**
+* Read-only accessor for a directory produced by a spec action.
+*
+* Assertions go through `expect()` (async — they walk the disk):
+* `await expect(result.directory('out')).toMatch('scaffold/out')`
+* compares the tree against the fixture directory `expected/<name>/`.
+*/
+var DirectoryAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Absolute path of the directory under assertion. */
+	root;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	constructor(absPath, testDir, captures) {
+		this.root = absPath;
+		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** List all files (recursively) under the directory, sorted. */
+	async files(options = {}) {
+		return walkDirectory(this.root, options);
+	}
+};
+//#endregion
+//#region src/core/specification/shared/result/filesystem.ts
+/**
+* Read-only accessor for the whole temporary working directory used by a
+* command spec.
+*
+* Assertions go through `expect()` (async — they walk the disk):
+* `await expect(result.filesystem).toMatch('scaffolded')` compares the
+* tree against the fixture directory `expected/<name>/`.
+*/
+var FilesystemAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** The absolute path of the temporary working directory. */
+	cwd;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	constructor(cwd, testDir, captures) {
+		this.cwd = cwd;
+		this.testDir = testDir;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** List all files (recursively) under the working directory, sorted. */
+	async files(options = {}) {
+		return walkDirectory(this.cwd, options);
+	}
+};
+//#endregion
+//#region src/core/specification/shared/caller.ts
+/** Sibling module tests are callers, not internals (CONVENTIONS I2). */
+const TEST_FILE = /\.test\.[cm]?[jt]s$/;
+/** Where this very module sits inside the framework's SOURCE tree. */
+const SOURCE_LOCATION = join("core", "specification", "shared");
+/** The real path of `path`, or `path` itself when it cannot be resolved. */
+function realPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* Directory of the running framework module itself. From the built package
+* this is `<package root>/dist`, whatever the resolution path — including a
+* `file:` link, where the real path carries neither `node_modules` nor
+* `/src/…` and would otherwise be mistaken for a caller frame.
+*/
+const FRAMEWORK_DIR = realPath(dirname(fileURLToPath(import.meta.url)));
+/**
+* The directory holding the framework's OWN modules: `<package>/dist` for a
+* built install (everything is bundled there), `<repo>/src` when the framework
+* runs from source — this module's known location inside that tree is what
+* tells the two apart.
+*/
+const FRAMEWORK_TREE = FRAMEWORK_DIR.endsWith(`${sep}${SOURCE_LOCATION}`) ? resolve(FRAMEWORK_DIR, "../../..") : FRAMEWORK_DIR;
+/** Is `path` inside `directory` (strictly — a directory is not inside itself)? */
+function isInside(directory, path) {
+	const rest = relative(directory, path);
+	return rest !== "" && !rest.startsWith("..") && !isAbsolute(rest);
+}
+/**
+* Is this stack frame a module of the framework itself, rather than of the code
+* calling it?
+*
+* Answered by IDENTITY: the frame is inside the framework's own directory.
+* Answering it by substring — `/src/core/`, `/src/integrations/`, `/src/vitest/`
+* — was answering a different question, "does this path look like the framework's
+* layout", and a consumer that happens to have its own `src/core/` matched it.
+* Its files were then skipped as framework internals, and fixture resolution
+* anchored on the wrong directory (or fell through to the cwd) with nothing
+* reported.
+*
+* @internal
+*/
+function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
+	if (TEST_FILE.test(filePath)) return false;
+	return isInside(realPath(frameworkTree), realPath(filePath));
+}
+/**
+* Detect the directory of the first stack frame that lives outside this
+* package. Used to anchor fixture resolution (`seeds/`, `requests/`,
+* `expected/`, …) on the calling test / specification file.
+*
+* @internal
+*/
+function getCallerDir() {
+	const stack = (/* @__PURE__ */ new Error("caller detection")).stack;
+	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
+	const lines = stack.split("\n");
+	for (const line of lines) {
+		const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?(?<filePath>[^:)]+):\d+:\d+/);
+		if (!match?.groups?.filePath) continue;
+		const filePath = match.groups.filePath;
+		if (filePath.includes("node_modules")) continue;
+		if (isFrameworkFrame(filePath)) continue;
+		return resolve(filePath, "..");
+	}
+	return process.cwd();
+}
+//#endregion
+//#region src/core/specification/shared/result/grep.ts
+/**
+* Extract text blocks from output that contain a pattern.
+* Splits by blank lines (how linter/compiler output is structured),
+* returns only blocks matching the pattern.
+*
+* @example
+* expect(grep(result.stdout, "unused-var.ts")).toContain("no-unused-vars")
+* expect(grep(result.stdout, "valid/sorted.ts")).not.toContain("sort-imports")
+*/
+function grep(output, pattern) {
+	return output.replace(/\x1b\[[0-9;]*m/g, "").split(/\n\s*\n/).filter((block) => block.includes(pattern)).join("\n\n");
+}
+//#endregion
+//#region src/core/specification/shared/result/text.ts
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Strip ANSI escape sequences from a string. */
+function stripAnsiCodes(value) {
+	return value.replace(ANSI_RE, "");
+}
+/**
+* Read-only accessor for a captured text handle — THE universal one: stdout,
+* stderr, container logs, and file text all surface as a `TextAccessor`.
+*
+* Backed by a primitive string, exposed via {@link text}, but also provides
+* `toString()` / `valueOf()` for string coercion, so common patterns like
+* `String(result.stdout)` and template-literal interpolation still work.
+*
+* ANSI escape sequences are stripped by default before every comparison
+* (CONVENTIONS D6) — `.text` stays raw. The runner `transform` option remains
+* an escape hatch for application noise not covered by the `{{token}}`
+* grammar.
+*
+* Text operations are **closed** over the type: `.grep(pattern)` returns a
+* `TextAccessor` (not a bare string), preserving the `expected/`-resolution
+* context and the `transform`, so results are chainable
+* (`result.stdout.grep(a).grep(b)`) and snapshot-able
+* (`expect(result.stdout.grep('users.ts')).toMatch('block.txt')`).
+*
+* Assertions go through `expect()` matchers: `expect(result.stdout).toContain(...)`
+* and `expect(result.stdout).toMatch('name.txt')` (resolved against
+* `expected/<name>`, flat — with `{{token}}` support, CONVENTIONS D4).
+*/
+var TextAccessor = class TextAccessor {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal Stream label used in failure messages ("stdout" / "stderr"). */
+	streamName;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	/** The raw captured text (never transformed, ANSI preserved). */
+	text;
+	/** @internal Normaliser applied before comparisons, never to fixtures. */
+	transform;
+	constructor(value, streamName, testDir, options = {}) {
+		this.text = value;
+		this.streamName = streamName;
+		this.testDir = testDir;
+		this.transform = options.transform;
+		this.captures = options.captures ?? new CaptureScope();
+	}
+	/** @internal The text as compared by matchers — ANSI stripped, transform applied. */
+	get comparableText() {
+		const stripped = stripAnsiCodes(this.text);
+		return this.transform ? this.transform(stripped) : stripped;
+	}
+	/**
+	* Keep only the blank-line-separated blocks of the text that contain
+	* `pattern` (how linter/compiler output is structured), returned as a new
+	* `TextAccessor` — the same subject type, so the result is chainable and
+	* snapshot-able. The scalpel for probing large tool outputs; snapshot the
+	* whole surface by default, reach for `.grep()` for targeted checks.
+	*/
+	grep(pattern) {
+		return new TextAccessor(grep(this.text, pattern), this.streamName, this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	toString() {
+		return this.text;
+	}
+	valueOf() {
+		return this.text;
+	}
+};
+/**
+* Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
+* test's directory — the same caller-detection the builders use.
+*
+* The product surface of a test framework is its own error messages, checker
+* output, and reports; those deserve the same goldening as any other output.
+* `text()` makes an ad-hoc string a first-class snapshot subject:
+*
+* ```typescript
+* const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
+* expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to expected/
+* ```
+*
+* ANSI is stripped before every comparison (the raw form stays on `.text`),
+* the `{{token}}` grammar applies to the fixture, and `.grep()` composition
+* works exactly as on any stream accessor.
+*/
+function text(value) {
+	return new TextAccessor(value, "text", getCallerDir());
+}
+//#endregion
+//#region src/core/specification/shared/result/json.ts
+/**
+* Read-only accessor for a JSON payload parsed from a text stream (stdout).
+*
+* Lazily parses the JSON on first use; parse errors are deferred until the
+* value is read so that callers can still read the raw stream text without
+* triggering a throw.
+*
+* ANSI escape sequences are stripped by default before `JSON.parse`
+* (CONVENTIONS D6). When a `transform` is configured on the spec runner, it
+* runs on the stripped text — an escape hatch for application noise not
+* covered by the `{{token}}` grammar.
+*
+* Assertions go through `expect()`: `expect(result.json).toMatch('name.json')`
+* (deep-equal against `expected/<name>`, with `{{placeholder}}` support).
+*/
+var JsonAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	rawText;
+	/** @internal Test-file directory — fixture resolution root for matchers. */
+	testDir;
+	/** @internal */
+	transform;
+	constructor(rawText, testDir, transform, captures) {
+		this.rawText = rawText;
+		this.testDir = testDir;
+		this.transform = transform;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** The parsed JSON value. Throws if the text is not valid JSON. */
+	get value() {
+		const stripped = stripAnsiCodes(this.rawText);
+		const source = this.transform ? this.transform(stripped) : stripped;
+		try {
+			return JSON.parse(source);
+		} catch {
+			const preview = source.slice(0, 200);
+			throw new Error(`stdout is not valid JSON: ${preview}`);
+		}
+	}
+};
+//#endregion
+//#region src/core/specification/shared/result/table.ts
+/**
+* Read-only accessor for a database table after a specification run.
+*
+* Assertions go through `expect()` (async — they query the database):
+*
+*     await expect(result.table('users', { database: 'db' })).toMatchRows({
+*         columns: ['name'],
+*         rows: [['Alice']],
+*     });
+*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
+*/
+var TableAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	db;
+	/** The table name this accessor reads. */
+	name;
+	constructor(name, db, captures) {
+		this.name = name;
+		this.db = db;
+		this.captures = captures ?? new CaptureScope();
+	}
+	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
+	query(columns) {
+		return this.db.query(this.name, columns);
+	}
+};
+//#endregion
+//#region src/integrations/docker/docker-lookup.ts
+/**
+* Thin synchronous wrappers around the `docker` CLI used by the docker() spec
+* mode. Sync is deliberate — the calls are fast, run only on the host, and
+* keep the dispose path straightforward (`Symbol.asyncDispose` can still be
+* async without needing these to be).
+*/
+const DEFAULT_TIMEOUT = 1e4;
+/** Return all container IDs (running or stopped) that carry `key=value`. */
+function findContainersByLabel(key, value) {
+	try {
+		return execSync(`docker ps -aq -f label=${key}=${value}`, {
+			encoding: "utf8",
+			timeout: DEFAULT_TIMEOUT
+		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+/** Return the raw `docker inspect` payload (object, not array) for a container. */
+function inspectContainer(id) {
+	const raw = execSync(`docker inspect ${id}`, {
+		encoding: "utf8",
+		timeout: DEFAULT_TIMEOUT
+	});
+	const parsed = JSON.parse(raw);
+	return Array.isArray(parsed) ? parsed[0] : parsed;
+}
+/** Force-remove the given container IDs in a single call. Errors are swallowed. */
+function removeContainers(ids) {
+	if (ids.length === 0) return;
+	try {
+		execSync(`docker rm -f ${ids.join(" ")}`, {
+			encoding: "utf8",
+			stdio: "pipe",
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch {}
+}
+//#endregion
+//#region src/core/specification/shared/result/result.ts
+/**
+* Base result - common accessors available after any action type.
+* Extended by HttpResult, CliResult, and used directly by job results.
+*
+* Every result carries a fresh {@link CaptureScope}: `match.ref()` captures
+* and `{{type#ref}}` placeholders are scoped to one spec execution.
+*/
+var BaseResult = class {
+	/** @internal Ref-capture scope shared by every assertion on this result. */
+	captures;
+	config;
+	testDir;
+	workDir;
+	constructor(options) {
+		this.config = options.config;
+		this.testDir = options.testDir;
+		this.workDir = options.workDir;
+		this.captures = new CaptureScope(options.workDir ? safeRealpath(options.workDir) : void 0);
+	}
+	/** Access a directory (relative to the working directory) for snapshot assertions. */
+	directory(path = ".") {
+		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir, this.captures);
+	}
+	/** Access a single file (relative to the working directory) for content assertions. */
+	file(path) {
+		const resolvedPath = resolve(this.workDir ?? this.testDir, path);
+		const exists = existsSync(resolvedPath);
+		const { captures, testDir } = this;
+		return {
+			get content() {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return readFileSync(resolvedPath, "utf8");
+			},
+			exists,
+			grep(pattern) {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return new TextAccessor(readFileSync(resolvedPath, "utf8"), path, testDir, { captures }).grep(pattern);
+			}
+		};
+	}
+	/** Access a database table for row-level assertions via expect() matchers. */
+	table(tableName, options) {
+		validateDatabaseOption("table", this.config, options?.database);
+		const db = this.resolveDatabase(options?.database);
+		if (!db) throw new Error(options?.database ? `table("${tableName}") requires database "${options.database}" but it was not found` : `table("${tableName}") requires a database adapter`);
+		return new TableAccessor(tableName, db, this.captures);
+	}
+	resolveDatabase(databaseKey) {
+		if (databaseKey && this.config.databases) return this.config.databases.get(databaseKey);
+		return this.config.database;
+	}
+};
+/**
+* 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).
+*
+* @internal
+*/
+function validateDatabaseOption(method, config, database) {
+	const keys = config.databaseKeys;
+	if (!keys) return;
+	if (keys.length >= 2 && !database) throw new Error(`${method}(): ${keys.length} databases are declared (${keys.map((k) => `"${k}"`).join(", ")}) — pass { database: <key> } to target one of them.`);
+	if (keys.length === 1 && database) throw new Error(`${method}(): redundant database option — "${keys[0]}" is the only declared database.`);
+}
+//#endregion
+//#region src/core/specification/cli/result.ts
+/**
+* Result from a command action (`.exec()`).
+*
+* When the runner was configured with a `docker` option, the result also
+* exposes container accessors and participates in `Symbol.asyncDispose`
+* cleanup. The Docker shell-outs are **lazy**: a test that never calls
+* `.container(...)` never queries the Docker daemon, so command-only tests
+* pay zero Docker cost even when the runner is Docker-aware.
+*
+* Dispose always runs one final label-filtered `docker ps` to catch
+* containers that were spawned during `.exec` but never asserted on —
+* tests still get leak-free cleanup even if they forget to reach into
+* a container.
+*/
+var CliResult = class extends BaseResult {
+	commandOutput;
+	containersCache = null;
+	dockerConfig;
+	testRunId;
+	transform;
+	constructor(options) {
+		super(options);
+		this.commandOutput = options.commandOutput;
+		this.dockerConfig = options.dockerConfig;
+		this.testRunId = options.testRunId;
+		this.transform = options.transform;
+	}
+	/** The process exit code. */
+	get exitCode() {
+		return this.commandOutput.exitCode;
+	}
+	/** Accessor for the captured standard output with file-based assertions. */
+	get stdout() {
+		return new TextAccessor(this.commandOutput.stdout, "stdout", this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	/** Accessor for the captured standard error with file-based assertions. */
+	get stderr() {
+		return new TextAccessor(this.commandOutput.stderr, "stderr", this.testDir, {
+			captures: this.captures,
+			transform: this.transform
+		});
+	}
+	/** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+	get json() {
+		return new JsonAccessor(this.commandOutput.stdout, this.testDir, this.transform, this.captures);
+	}
+	/** Accessor for the temporary working directory the command ran in. */
+	get filesystem() {
+		if (!this.workDir) throw new Error("CliResult.filesystem requires a working directory");
+		return new FilesystemAccessor(this.workDir, this.testDir, this.captures);
+	}
+	/**
+	* Look up a container the command spawned during this run by the value of
+	* its name-label (as declared in the `docker.nameLabel` of the
+	* `specification.cli()` options).
+	* First access triggers a one-shot `docker ps` + `docker inspect`
+	* query and caches the result for the rest of the result's lifetime.
+	* Tests that don't call this never touch Docker.
+	*
+	* Returns an accessor with `.exists === false` when no container
+	* carries that name — callers can still assert absence without a try.
+	*/
+	container(name) {
+		this.ensureDockerAware("container");
+		this.loadContainers();
+		const captured = this.containersCache.get(name);
+		if (!captured) return new ContainerAccessor(null, null, this.testDir, this.transform);
+		return new ContainerAccessor(captured.id, captured.inspect, this.testDir, this.transform);
+	}
+	/** All captured container IDs. Triggers the same lazy query as `container()`. */
+	get containerIds() {
+		this.ensureDockerAware("containerIds");
+		this.loadContainers();
+		return [...this.containersCache.values()].map((c) => c.id);
+	}
+	async [Symbol.asyncDispose]() {
+		if (!this.dockerConfig || !this.testRunId) return;
+		removeContainers(this.containersCache !== null ? [...this.containersCache.values()].map((c) => c.id) : findContainersByLabel(this.dockerConfig.testRunLabel, this.testRunId));
+	}
+	ensureDockerAware(member) {
+		if (!this.dockerConfig || !this.testRunId) throw new Error(`CliResult.${member}: runner was not configured with a docker option. Pass \`docker: { envVar, nameLabel, testRunLabel }\` in the specification.cli() options.`);
+	}
+	loadContainers() {
+		if (this.containersCache !== null) return;
+		const ids = findContainersByLabel(this.dockerConfig.testRunLabel, this.testRunId);
+		const map = /* @__PURE__ */ new Map();
+		for (const id of ids) {
+			let inspect;
+			try {
+				inspect = inspectContainer(id);
+			} catch {
+				continue;
+			}
+			const nameValue = (inspect?.Config?.Labels ?? inspect?.config?.labels ?? {})[this.dockerConfig.nameLabel];
+			const key = typeof nameValue === "string" && nameValue.length > 0 ? nameValue : id;
+			map.set(key, {
+				id,
+				inspect
+			});
+		}
+		this.containersCache = map;
+	}
+};
+//#endregion
+//#region src/integrations/docker/container-accessor.ts
+const EXEC_TIMEOUT = 1e4;
+function readInspectState(inspect) {
+	const state = inspect?.State ?? inspect?.state;
+	if (!state) return {
+		running: false,
+		status: "unknown"
+	};
+	return {
+		running: Boolean(state.Running ?? state.running ?? false),
+		status: String(state.Status ?? state.status ?? "unknown")
+	};
+}
+/**
+* Assertion accessor for a single Docker container captured by the docker()
+* spec mode. Mirrors the shape of {@link CliResult} so tests use the same
+* vocabulary (`stdout.toContain`, `file(...).content`, etc.) regardless
+* of where output came from.
+*
+* Sync state (`exists`, `running`, `status`) is derived from the `docker
+* inspect` payload captured at result-construction time. Logs are fetched
+* lazily on first access to `stdout`/`stderr`.
+*/
+var ContainerAccessor = class {
+	cachedLogs = null;
+	containerId;
+	exists;
+	inspectData;
+	running;
+	status;
+	testDir;
+	transform;
+	/**
+	* Underlying Docker container ID, or `null` if no container was captured
+	* for this name. Useful when a follow-up CLI command needs to reference
+	* the container by id (e.g. `spwn world inspect <id>`). Prefer the other
+	* accessors for common reads — pulling the raw id is the escape hatch.
+	*/
+	get id() {
+		return this.containerId;
+	}
+	constructor(containerId, inspectData, testDir, transform) {
+		this.containerId = containerId;
+		this.inspectData = inspectData;
+		this.testDir = testDir;
+		this.transform = transform;
+		this.exists = containerId !== null;
+		if (this.exists) {
+			const state = readInspectState(inspectData);
+			this.running = state.running;
+			this.status = state.status;
+		} else {
+			this.running = false;
+			this.status = "absent";
+		}
+	}
+	/**
+	* Raw `docker inspect` object for this container. Throws if the container
+	* was not captured (i.e. `.exists === false`).
+	*/
+	get inspect() {
+		this.requireExists("inspect");
+		return new JsonAccessor(JSON.stringify(this.inspectData), this.testDir, this.transform);
+	}
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stdout() {
+		this.requireExists("stdout");
+		return new TextAccessor(this.loadLogs(), "stdout", this.testDir, { transform: this.transform });
+	}
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stderr() {
+		this.requireExists("stderr");
+		return new TextAccessor(this.loadLogs(), "stderr", this.testDir, { transform: this.transform });
+	}
+	/**
+	* Read a file from inside the container via `docker exec cat`. The
+	* returned object satisfies the same {@link FileAccessor} shape used by
+	* the host filesystem accessor, so tests do not need to learn a new API.
+	*/
+	file(path) {
+		this.requireExists("file");
+		const id = this.containerId;
+		const exists = this.containerExec(id, [
+			"test",
+			"-e",
+			path
+		]).exitCode === 0;
+		const { testDir } = this;
+		const readContent = () => {
+			if (!exists) throw new Error(`File not found in container: ${path}`);
+			return execSync(`docker exec ${id} cat ${JSON.stringify(path)}`, {
+				encoding: "utf8",
+				timeout: EXEC_TIMEOUT
+			});
+		};
+		return {
+			get content() {
+				return readContent();
+			},
+			exists,
+			grep(pattern) {
+				return new TextAccessor(readContent(), path, testDir).grep(pattern);
+			}
+		};
+	}
+	/**
+	* Run a shell command inside the container and get back the same
+	* {@link CliResult} used for host-side executions.
+	*/
+	async exec(cmd) {
+		this.requireExists("exec");
+		return new CliResult({
+			commandOutput: this.containerExec(this.containerId, [
+				"sh",
+				"-c",
+				cmd
+			]),
+			config: {},
+			testDir: this.testDir,
+			transform: this.transform,
+			workDir: this.testDir
+		});
+	}
+	requireExists(member) {
+		if (!this.exists) throw new Error(`ContainerAccessor.${member}: container does not exist (check .exists first)`);
+	}
+	loadLogs() {
+		if (this.cachedLogs !== null) return this.cachedLogs;
+		try {
+			const out = execSync(`docker logs ${this.containerId}`, {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				timeout: EXEC_TIMEOUT
+			});
+			this.cachedLogs = out;
+		} catch (error) {
+			this.cachedLogs = typeof error?.stdout === "string" ? error.stdout : String(error?.stderr ?? "");
+		}
+		return this.cachedLogs ?? "";
+	}
+	containerExec(id, argv) {
+		try {
+			return {
+				exitCode: 0,
+				stderr: "",
+				stdout: execSync(`docker exec ${id} ${argv.map((a) => JSON.stringify(a)).join(" ")}`, {
+					encoding: "utf8",
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					],
+					timeout: EXEC_TIMEOUT
+				})
+			};
+		} catch (error) {
+			return {
+				exitCode: typeof error?.status === "number" ? error.status : 1,
+				stderr: typeof error?.stderr === "string" ? error.stderr : String(error?.message ?? ""),
+				stdout: typeof error?.stdout === "string" ? error.stdout : ""
+			};
+		}
+	}
+};
+//#endregion
+//#region src/vitest/update.ts
+/**
+* Snapshot update-mode detection. `TEST_UPDATE=1` (framework convention, see
+* CONVENTIONS E1) or vitest's `-u` / `--update` flag turn fixture mismatches
+* into fixture rewrites.
+*/
+function shouldUpdateSnapshots() {
+	if (process.env.TEST_UPDATE === "1") return true;
+	return process.argv.includes("-u") || process.argv.includes("--update");
+}
+/** Standard hint appended to missing-fixture errors. */
+const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
+//#endregion
+//#region src/core/specification/website/serve.adapter.ts
+/** Grace period between SIGTERM and the SIGKILL escalation. */
+const KILL_GRACE_MS = 2e3;
+const DEFAULT_READY_TIMEOUT = 3e4;
+const READY_POLL_INTERVAL_MS = 250;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Ask the OS for a free TCP port. */
+function findFreePort() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.listen(0, () => {
+			const address = server.address();
+			if (address === null || typeof address === "string") {
+				server.close();
+				reject(/* @__PURE__ */ new Error("could not determine a free port"));
+				return;
+			}
+			const { port } = address;
+			server.close(() => resolve(port));
+		});
+		server.on("error", reject);
+	});
+}
+/**
+* Starts the site under test as a child process and waits until it answers
+* HTTP. Any HTTP status counts as ready — a 404 on the ready path is still a
+* listening server; only connection failures keep the poll going.
+*
+* The child runs through the shell in its own process group (POSIX) so
+* `stop()` can terminate the whole tree — a `next start` grandchild must not
+* outlive the spec run (same escalation as the cli exec adapter: SIGTERM,
+* then SIGKILL after a 2 s grace).
+*/
+var ServeAdapter = class {
+	/** The port the server ended up on — known only after {@link start}. */
+	port = null;
+	child = null;
+	/** Extra environment injected into the child (e.g. the stub backend URL). */
+	extraEnv;
+	/** The constructor named in error messages — `website`, or `mobile` (appium server). */
+	facet;
+	options;
+	output = "";
+	root;
+	constructor(options, root, facet = "website", extraEnv = {}) {
+		this.extraEnv = extraEnv;
+		this.facet = facet;
+		this.options = options;
+		this.root = root;
+	}
+	/** Start the server and resolve with its base URL once it is ready. */
+	async start() {
+		const banner = this.options.ready instanceof RegExp ? this.options.ready : null;
+		const port = banner ? null : this.options.port ?? await findFreePort();
+		const timeout = this.options.timeout ?? DEFAULT_READY_TIMEOUT;
+		this.child = spawn(this.options.command, [], {
+			cwd: this.root,
+			detached: process.platform !== "win32",
+			env: {
+				...process.env,
+				...this.extraEnv,
+				...port === null ? {} : { PORT: String(port) }
+			},
+			shell: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child.stdout?.on("data", (data) => {
+			this.output += data.toString();
+		});
+		this.child.stderr?.on("data", (data) => {
+			this.output += data.toString();
+		});
+		let exited = false;
+		this.child.on("exit", () => {
+			exited = true;
+		});
+		const deadline = Date.now() + timeout;
+		const died = () => {
+			throw new Error(`specification.${this.facet}(): server command exited before it was ready.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+		};
+		if (banner) for (;;) {
+			banner.lastIndex = 0;
+			const found = banner.exec(this.output);
+			if (found) {
+				const captured = Number(found[1]);
+				if (!Number.isInteger(captured)) {
+					await this.stop();
+					throw new Error(`specification.${this.facet}(): the ready pattern ${String(banner)} matched but its capture group is not a port ("${found[1]}").\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+				}
+				this.port = captured;
+				return `http://127.0.0.1:${captured}`;
+			}
+			if (exited) died();
+			if (Date.now() >= deadline) {
+				await this.stop();
+				throw new Error(`specification.${this.facet}(): server did not print ${String(banner)} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+			}
+			await delay(READY_POLL_INTERVAL_MS);
+		}
+		const baseUrl = `http://127.0.0.1:${port}`;
+		const readyUrl = `${baseUrl}${this.options.ready ?? "/"}`;
+		for (;;) {
+			if (exited) died();
+			try {
+				await fetch(readyUrl, { redirect: "manual" });
+				this.port = port;
+				return baseUrl;
+			} catch {
+				if (Date.now() >= deadline) {
+					await this.stop();
+					throw new Error(`specification.${this.facet}(): server did not answer on ${readyUrl} within ${timeout}ms.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
+				}
+				await delay(READY_POLL_INTERVAL_MS);
+			}
+		}
+	}
+	/** Terminate the server process group (idempotent). */
+	async stop() {
+		const child = this.child;
+		if (!child) return;
+		this.child = null;
+		await new Promise((resolve) => {
+			let exited = false;
+			child.on("exit", () => {
+				exited = true;
+				resolve();
+			});
+			if (child.exitCode !== null || child.signalCode !== null) {
+				resolve();
+				return;
+			}
+			this.kill(child, "SIGTERM");
+			setTimeout(() => {
+				if (!exited) {
+					this.kill(child, "SIGKILL");
+					resolve();
+				}
+			}, KILL_GRACE_MS).unref?.();
+		});
+	}
+	/** Group-aware kill: signal the process group, fall back to the child. */
+	kill(child, signal) {
+		if (child.pid !== void 0 && process.platform !== "win32") try {
+			process.kill(-child.pid, signal);
+			return;
+		} catch {}
+		child.kill(signal);
+	}
+};
+//#endregion
+//#region src/core/specification/cli/literate.ts
+/**
+* The form a stream is compared in: ANSI stripped (rule D6) and the runner's
+* `transform` applied. Nothing else — a block scalar states its own final
+* newline (`|` keeps it, `|-` drops it), so the comparison is byte-exact and
+* has no normalisation to hide behind.
+*/
+function comparable(raw, transform) {
+	const stripped = stripAnsiCodes(raw);
+	return transform ? transform(stripped) : stripped;
+}
+/**
+* Line equality AS THE COMPARISON JUDGED IT — a `{{url}}` line that matched is
+* equal, whatever port the run picked. Each line is judged on its own fresh
+* scope: this is a rendering, and a ref captured by an earlier line must not
+* decide how a later one is displayed.
+*/
+function tokenAwareEquals(scope) {
+	return (expected, actual) => textEquals(expected, actual, new CaptureScope(scope.workdir));
+}
+/** A path under the working directory, refusing anything that would escape it. */
+function resolveUnderWorkDir(path, workDir, context) {
+	const target = resolve(workDir, path);
+	const inside = relative(workDir, target);
+	if (isAbsolute(path) || inside.startsWith("..") || isAbsolute(inside)) throw new Error(`${context.displayPath}: files: "${path}" leaves the working directory — a files: key is a relative path under the cwd`);
+	return target;
+}
+/** A one-line preview of a file's content for the failure rendering. */
+function preview(text) {
+	return JSON.stringify(text.length > 160 ? `${text.slice(0, 160)}…` : text);
+}
+function readIfPresent(path) {
+	try {
+		return statSync(path).isFile() ? readFileSync(path, "utf8") : null;
+	} catch {
+		return null;
+	}
+}
+/** Check one `files:` entry and render its failure, or `null` when it holds. */
+function checkFile(assertion, workDir, context, scope) {
+	const target = resolveUnderWorkDir(assertion.path, workDir, context);
+	let exists;
+	try {
+		exists = statSync(target) !== void 0;
+	} catch {
+		exists = false;
+	}
+	if (assertion.kind === "absent") return exists ? `${assertion.path}: expected absent, got a file` : null;
+	if (!exists) return `${assertion.path}: expected to exist, got nothing at that path`;
+	if (assertion.kind === "exists") return null;
+	const content = readIfPresent(target);
+	if (content === null) return `${assertion.path}: expected a readable file, got a directory`;
+	for (const needle of assertion.contains) if (!textContains(needle.text, content, scope)) return `${assertion.path}: expected to contain ${preview(needle.text)}, got ${preview(content)}`;
+	if (assertion.equals !== null && !textEquals(assertion.equals.text, content, scope)) return `${assertion.path}: expected ${preview(assertion.equals.text)}, got ${preview(content)}`;
+	return null;
+}
+/**
+* The failure a mismatching run throws: the description, the command that ran,
+* every detail the comparison rejected, and where to open the document. The
+* update hint names exactly what a rewrite touches, so it cannot be read as
+* "this will re-generate my `files:`".
+*
+* The stack is REPLACED by the run's own line. Left alone it would carry the
+* engine's frames and end inside the module the plugin generates — pointing the
+* reader at a line of a file they never wrote. One frame, on the `command:` key,
+* is the whole truth here.
+*/
+function failure(document, run, context, details) {
+	return atLine(new Error([
+		"Spec mismatch",
+		"",
+		document.description,
+		"",
+		`$ ${run.command}`,
+		"",
+		details.join("\n\n"),
+		"",
+		`${context.displayPath}:${run.commandLine}`,
+		"Run with TEST_UPDATE=1 to rewrite the runs — the exit code and the streams, and nothing else."
+	].join("\n")), context.filePath, run.commandLine);
+}
+/**
+* Point an error's stack at one frame: the line of the `.spec.yaml` that owns
+* the failure. The framework's own frames carry nothing a reader of a spec
+* document can act on, and the generated module's frame actively misleads.
+*/
+function atLine(error, filePath, line) {
+	error.stack = `${error.name}: ${error.message}\n    at ${filePath}:${line}:1`;
+	return error;
+}
+/** Compare one run against what the command actually did. */
+function assertRun(document, outcome, context, workDir, scope) {
+	const { actual, run } = outcome;
+	if (actual.exitCode !== run.exitCode) throw failure(document, run, context, [[
+		"exit code mismatch",
+		`  expected: ${run.exitCode}`,
+		`  received: ${actual.exitCode}`,
+		...outcome.stderr.length > 0 ? [
+			"",
+			"stderr was:",
+			outcome.stderr.replace(/\n$/, "")
+		] : []
+	].join("\n")]);
+	const equals = tokenAwareEquals(scope);
+	const details = [];
+	for (const [name, expected, received] of [[
+		"stdout",
+		run.stdout?.text ?? "",
+		outcome.stdout
+	], [
+		"stderr",
+		run.stderr?.text ?? "",
+		outcome.stderr
+	]]) if (!textEquals(expected, received, scope)) details.push(formatStdoutDiff(name, expected, received, { equals }));
+	const fileFailures = run.files.map((assertion) => checkFile(assertion, workDir, context, scope)).filter((line) => line !== null);
+	if (fileFailures.length > 0) details.push([
+		"files mismatch",
+		"",
+		...fileFailures.map((line) => `  ${line}`)
+	].join("\n"));
+	if (details.length > 0) throw failure(document, run, context, details);
+}
+/**
+* The rewritten runs: exit codes and streams from the run, placeholders of the
+* previous golden preserved by pattern (rule D5). A stream that ends up empty
+* loses its key, so a rewritten document passes the next run.
+*/
+function updates(outcomes, scope) {
+	return outcomes.map(({ actual, run, stderr, stdout }) => ({
+		exitCode: actual.exitCode,
+		stderr: mergeTextPreservingPlaceholders(run.stderr?.text ?? null, stderr, scope),
+		stdout: mergeTextPreservingPlaceholders(run.stdout?.text ?? null, stdout, scope)
+	}));
+}
+/**
+* Start every server the document names, in declaration order, before the first
+* run. They all stay live for the whole file and are stopped together — one
+* document is one scenario, and its servers are part of its ground.
+*/
+async function startServers(document, config, displayPath) {
+	const registry = config.serveRegistry ?? {};
+	const started = [];
+	const env = {};
+	const stop = async () => {
+		for (const adapter of started.toReversed()) await adapter.stop();
+	};
+	for (const entry of document.serve) {
+		const registration = registry[entry.name];
+		if (!registration) {
+			await stop();
+			const known = Object.keys(registry);
+			throw new Error(`${displayPath}:${entry.line}: serve: "${entry.name}" is not registered — ${known.length === 0 ? "specification.cli() declares no `serve` option." : `registered servers: ${known.join(", ")}.`}`);
+		}
+		const adapter = new ServeAdapter({
+			command: registration.command,
+			ready: registration.ready
+		}, config.root ?? process.cwd(), "cli", entry.env);
+		started.push(adapter);
+		try {
+			await adapter.start();
+		} catch (error) {
+			await stop();
+			throw error;
+		}
+		env[registration.env] = registration.url(adapter.port);
+	}
+	return {
+		env,
+		stop
+	};
+}
+/** Resolve the document's `env:` entries against the registered sets. `$WORKDIR` expands. */
+function documentEnv(document, config, displayPath) {
+	const sets = config.envSets ?? {};
+	const env = {};
+	for (const token of document.env) {
+		if (token.kind === "set") {
+			const declared = sets[token.name];
+			if (!declared) {
+				const known = Object.keys(sets);
+				throw new Error(`${displayPath}:${token.line}: env: "${token.name}" is not a registered env set — ${known.length === 0 ? "specification.cli() declares no `env` option." : `registered sets: ${known.join(", ")}.`}`);
+			}
+			Object.assign(env, declared);
+			continue;
+		}
+		env[token.key] = token.value;
+	}
+	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
+* grep) after `cli.run('<case>.spec.yaml')`.
+*
+* Under `TEST_UPDATE=1` nothing is asserted: every run executes, and each one's
+* exit code and streams are rewritten from the actual output with the previous
+* golden's placeholders preserved.
+*/
+async function runSpecDocument(options) {
+	const { config, displayPath, filePath, testDir, workDir } = options;
+	if (!config.command) throw new Error(".run(): spec documents require a command adapter (use specification.cli())");
+	let file;
+	try {
+		file = readSpecFile(readFileSync(filePath, "utf8"), displayPath);
+	} catch (error) {
+		throw error instanceof SpecSyntaxError ? atLine(error, filePath, error.line) : error;
+	}
+	const document = file.document;
+	const fileDir = filePath.replace(/[/\\][^/\\]*$/, "");
+	for (const fixture of document.fixtures) {
+		const { dest, src } = copyPlan(fixture.path, fileDir, workDir);
+		cpSync(src, dest, { recursive: true });
+	}
+	const servers = await startServers(document, config, displayPath);
+	const scope = new CaptureScope(safeRealpath(workDir));
+	const env = expandWorkdir({
+		...options.baseEnv,
+		...servers.env,
+		...documentEnv(document, config, displayPath)
+	}, workDir);
+	let outcomes;
+	try {
+		outcomes = [];
+		for (const run of document.runs) {
+			const actual = run.waitFor === null ? await config.command.exec(run.command, workDir, env, {
+				stdin: run.stdin ?? void 0,
+				timeout: run.timeout ?? void 0
+			}) : await config.command.watch(run.command, workDir, {
+				timeout: run.timeout ?? void 0,
+				waitFor: run.waitFor
+			}, env);
+			outcomes.push({
+				actual,
+				run,
+				stderr: comparable(actual.stderr, config.transform),
+				stdout: comparable(actual.stdout, config.transform)
+			});
+		}
+	} finally {
+		await servers.stop();
+	}
+	if (shouldUpdateSnapshots() && options.frozen !== true) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
+	else for (const outcome of outcomes) assertRun(document, outcome, {
+		displayPath,
+		filePath
+	}, workDir, scope);
+	return new CliResult({
+		commandOutput: outcomes.at(-1).actual,
+		config,
+		dockerConfig: config.dockerConfig,
+		testDir,
+		testRunId: config.dockerTestRunId,
+		transform: config.transform,
+		workDir
+	});
+}
+/** The title a transformed `.spec.yaml` module runs under — the `description:` line. */
+function specDescription(content, displayPath) {
+	return readSpecFile(content, displayPath).document.description;
+}
+//#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 };