@jterrazz/test 12.0.2 → 12.2.0

package/dist/index.js

@@ -1,15 +1,13 @@
 import { i as match, n as Matcher, t as CaptureScope } from "./match.js";
-import { a as isContract, c as mergeTextPreservingPlaceholders, d as structuralSubset, f as textEquals, i as defineContracts, l as renderExpected, n as contractsOf, o as isContracts, r as defineContract, s as mergePreservingPlaceholders, t as ContractQueue, u as structuralEquals } from "./queue.js";
-import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { A as mergeTextPreservingPlaceholders, C as formatDirectoryDiff, D as formatTableDiff, E as formatStdoutDiff, F as textEquals, M as renderExpected, N as structuralEquals, P as structuralSubset, S as walkDirectory, T as formatStartupReport, _ as text, a as UPDATE_HINT, b as DirectoryAccessor, c as CliResult, d as findContainersByLabel, f as inspectContainer, g as TextAccessor, h as JsonAccessor, i as copyPlan, k as mergePreservingPlaceholders, l as BaseResult, m as TableAccessor, n as runLiterateSpec, o as shouldUpdateSnapshots, p as removeContainers, r as ServeAdapter, s as ContainerAccessor, u as validateDatabaseOption, v as getCallerDir, w as formatResponseDiff, x as diffDirectories, y as FilesystemAccessor } from "./literate.js";
+import { a as isContract, i as defineContracts, n as contractsOf, o as isContracts, r as defineContract, t as ContractQueue } from "./queue.js";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { Client } from "pg";
-import { readdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import { createServer } from "node:http";
-import { createServer as createServer$1 } from "node:net";
 import { promisify } from "node:util";
 import Database from "better-sqlite3";
 import { createHash } from "node:crypto";
@@ -522,497 +520,6 @@ function isJsonLike(text) {
 	}
 }
 //#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");
-}
-function formatStdoutDiff(file, expected, actual) {
-	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 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");
-}
-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/response.ts
 /**
 * Read-only accessor for an HTTP response.
@@ -1042,440 +549,6 @@ var ResponseAccessor = class {
 	}
 };
 //#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;
-	}
-};
-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/vitest/matchers.ts
 /**
 * Vitest custom matchers for `@jterrazz/test` accessors.
@@ -1515,7 +588,7 @@ function matchStreamFile(accessor, name, frozen) {
 	if (!existsSync(filePath)) return FAIL(`${accessor.streamName} fixture "${name}" does not exist at ${filePath}.\n${UPDATE_HINT}`);
 	const expected = readFileSync(filePath, "utf8");
 	if (textEquals(expected, actual, accessor.captures)) return PASS(`expected ${accessor.streamName} not to match expected/${name}`);
-	return FAIL(formatStdoutDiff(name, expected, actual));
+	return FAIL(formatStdoutDiff(name, expected, actual, { equals: (expectedLine, actualLine) => textEquals(expectedLine, actualLine, new CaptureScope(accessor.captures.workdir)) }));
 }
 function matchJsonFile(accessor, name, frozen) {
 	requireExtension(name, "json");
@@ -1955,77 +1028,6 @@ function resolveComposeBinding(key, explicitComposeName, serviceNames) {
 	return key;
 }
 //#endregion
-//#region src/core/specification/shared/fixtures.ts
-/**
-* Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
-*
-* A fixture path is one of two shapes:
-*
-*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/fixtures/<rest>`,
-*    where `<specs-root>` is the nearest ancestor directory named `specs`.
-*  - `<path>` (no marker) — feature-local, at `<test-dir>/fixtures/<path>`.
-*
-* Any other `$`-prefixed marker is a usage error (listed against the known
-* markers). Copy semantics mirror rsync's trailing-slash rule (see
-* {@link copyPlan}).
-*/
-/**
-* Markers understood in a `.fixture()` path. Extend here + in
-* {@link resolveFixtureSource}. Exported so the lint layer (rule
-* `jterrazz/b2-known-fixture-marker`) validates literals against the same list.
-*/
-const KNOWN_FIXTURE_MARKERS = ["$FIXTURES"];
-/**
-* Walk up from `startDir` to the nearest ancestor directory named `specs`.
-* Throws with guidance if none is found up to the filesystem root — the
-* `$FIXTURES` marker is meaningless without a specs root.
-*/
-function discoverSpecsRoot(startDir) {
-	let dir = startDir;
-	for (;;) {
-		if (basename(dir) === "specs") return dir;
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/fixtures, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local fixtures/ path (no $FIXTURES marker).`);
-}
-/**
-* Resolve the absolute source path of a fixture, applying marker resolution.
-* The trailing slash (spread semantics) is preserved by callers via
-* {@link copyPlan} — it is irrelevant to source resolution.
-*/
-function resolveFixtureSource(path, testDir) {
-	const clean = path.replace(/\/+$/, "");
-	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
-		const rest = clean.slice(9).replace(/^\/+/, "");
-		return resolve(discoverSpecsRoot(testDir), "fixtures", rest);
-	}
-	if (path.startsWith("$")) {
-		const marker = clean.split("/")[0];
-		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/fixtures/).`);
-	}
-	return resolve(testDir, "fixtures", clean);
-}
-/**
-* Compute the source + destination for copying a fixture into the working
-* directory. Copy semantics follow rsync's trailing-slash rule:
-*
-*  - `dir/` (trailing slash) — the CONTENTS are spread into the cwd.
-*  - `dir`  (no slash, a directory) — the directory is copied as `<cwd>/<basename>`.
-*  - `file` — copied as `<cwd>/<basename>`.
-*
-* Chained `.fixture()` calls layer in order: a later fixture overwrites files
-* written by an earlier one.
-*/
-function copyPlan(path, testDir, workDir) {
-	const src = resolveFixtureSource(path, testDir);
-	return {
-		dest: /\/+$/.test(path) ? workDir : resolve(workDir, basename(src)),
-		src
-	};
-}
-//#endregion
 //#region src/core/specification/shared/builder.ts
 /**
 * Fluent builder for declaring a single test specification.
@@ -2220,6 +1222,25 @@ var SpecificationBuilder = class {
 		});
 	}
 	/**
+	* Run a literate `<case>.cli` spec and resolve with the LAST block's
+	* result. The whole file runs in ONE working directory with ONE set of
+	* servers, and every block is asserted — unlike `.exec([...])`, a non-zero
+	* exit does not stop the sequence, because here each exit code is part of
+	* what the file states.
+	*
+	* Setup chained BEFORE the call layers underneath the file's own header: a
+	* chained `.fixture()` is copied first, the header's `fixture:` lines over
+	* it, and the header's `env:` wins over a chained `.env()`.
+	*
+	* @example
+	*   const result = await cli.run('no-estate.cli');
+	*   await expect(result.directory('out')).toMatch('scaffold');
+	*/
+	run(file, options) {
+		const workDir = this.prepareWorkDir();
+		return this.executeSetup(workDir, () => this.runLiterateAction(workDir, file, options));
+	}
+	/**
 	* Perform one raw HTTP GET against the website under test and resolve
 	* with the exchange. Redirects are never followed — a 308 IS the result,
 	* with its `location` readable on the result. The scalpel for wire-level
@@ -2450,20 +1471,42 @@ var SpecificationBuilder = class {
 		if (redisHandles.length === 1) env.REDIS_URL = redisHandles[0].connectionString;
 		return env;
 	}
-	async runCommandAction(workDir, action) {
-		if (!this.config.command) throw new Error("Command actions require a command adapter");
-		const dockerConfig = this.config.dockerConfig;
-		const testRunId = this.config.dockerTestRunId;
+	/**
+	* The environment every child of this chain starts with. Merge order:
+	* injected service URLs (CONVENTIONS B6), then the docker run-id var, then
+	* the chain's own `.env()` — which always wins, `null` unsetting.
+	*/
+	childEnv(workDir) {
 		let env = this.serviceEnv();
-		if (dockerConfig && testRunId) env = {
+		const dockerConfig = this.config.dockerConfig;
+		if (dockerConfig && this.config.dockerTestRunId) env = {
 			...env,
-			[dockerConfig.envVar]: testRunId
+			[dockerConfig.envVar]: this.config.dockerTestRunId
 		};
 		const userEnv = this.resolveEnv(workDir);
 		if (userEnv) env = {
 			...env,
 			...userEnv
 		};
+		return env;
+	}
+	runLiterateAction(workDir, file, options) {
+		const filePath = resolve(this.testDir, file);
+		return runLiterateSpec({
+			baseEnv: this.childEnv(workDir),
+			frozen: options?.frozen,
+			config: this.config,
+			displayPath: relative(process.cwd(), filePath) || file,
+			filePath,
+			testDir: this.testDir,
+			workDir
+		});
+	}
+	async runCommandAction(workDir, action) {
+		if (!this.config.command) throw new Error("Command actions require a command adapter");
+		const dockerConfig = this.config.dockerConfig;
+		const testRunId = this.config.dockerTestRunId;
+		const env = this.childEnv(workDir);
 		let commandOutput;
 		if (action.options) commandOutput = await this.config.command.watch(action.args, workDir, action.options, env);
 		else if (Array.isArray(action.args)) {
@@ -2563,6 +1606,7 @@ function createCliFacet(config) {
 		env: (env) => start().env(env),
 		exec: (args, options) => start().exec(args, options),
 		fixture: (path) => start().fixture(path),
+		run: (file, options) => start().run(file, options),
 		seed: (file, options) => start().seed(file, options)
 	};
 }
@@ -2958,7 +2002,7 @@ 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$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const delay = (ms) => 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.
@@ -2999,7 +2043,7 @@ var FetchAdapter = class {
 			return await fetch(url, init);
 		} catch (error) {
 			if (attempt >= MAX_ATTEMPTS || !isTransientConnectionError(error)) throw error;
-			await delay$1(BASE_BACKOFF_MS * 2 ** (attempt - 1));
+			await delay(BASE_BACKOFF_MS * 2 ** (attempt - 1));
 		}
 	}
 };
@@ -3062,7 +2106,7 @@ async function startApi(options) {
 //#region src/core/specification/cli/exec.adapter.ts
 const DEFAULT_WATCH_TIMEOUT = 1e4;
 /** Grace period between SIGTERM and the SIGKILL escalation. */
-const KILL_GRACE_MS$1 = 2e3;
+const KILL_GRACE_MS = 2e3;
 /**
 * Build a child-process env from the parent env plus user overrides.
 * `null` overrides delete keys (e.g. `INIT_CWD: null`).
@@ -3105,7 +2149,7 @@ function observeProcess(child, options) {
 			child.kill("SIGTERM");
 			killTimer = setTimeout(() => {
 				if (!exited) child.kill("SIGKILL");
-			}, KILL_GRACE_MS$1);
+			}, KILL_GRACE_MS);
 		};
 		const finish = (exitCode) => {
 			if (resolved) return;
@@ -3231,6 +2275,9 @@ async function startCli(bin, options = {}) {
 			databaseKeys,
 			databases: started?.databases,
 			dockerConfig: options.docker,
+			envSets: options.env,
+			root,
+			serveRegistry: options.serve,
 			services: Object.keys(services).length > 0 ? services : void 0,
 			transform: options.transform
 		}),
@@ -3436,134 +2483,6 @@ async function readBody(request) {
 	}
 }
 //#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$1();
-		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 {
-	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 answers HTTP. */
-	async start() {
-		const port = this.options.port ?? await findFreePort();
-		const baseUrl = `http://127.0.0.1:${port}`;
-		const readyUrl = `${baseUrl}${this.options.ready ?? "/"}`;
-		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: 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;
-		for (;;) {
-			if (exited) throw new Error(`specification.${this.facet}(): server command exited before answering HTTP.\nCommand: ${this.options.command}\nOutput:\n${this.output}`);
-			try {
-				await fetch(readyUrl, { redirect: "manual" });
-				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/mobile/appium-server.ts
 const APPIUM_READY_TIMEOUT_MS = 6e4;
 /**