@jterrazz/test 7.1.0 → 8.0.0

package/dist/index.js

@@ -1,244 +1,189 @@
-import { n as redis, r as postgres, t as sqlite } from "./sqlite.adapter.js";
+import { n as redis, r as postgres, t as sqlite } from "./sqlite.js";
 import { n as mockOfDate, t as mockOf } from "./mock-of.js";
-import { execSync, spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { execSync, spawn, spawnSync } from "node:child_process";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { readdir } from "node:fs/promises";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { parse } from "yaml";
-//#region src/builder/cli/adapters/exec.adapter.ts
+import { tmpdir } from "node:os";
+import { readdir } from "node:fs/promises";
+//#region src/infra/docker/docker-assertion.ts
 /**
-* Build a child-process env from the parent env plus user overrides.
-* `null` overrides delete keys (e.g. `INIT_CWD: null`).
+* Fluent assertion builder for Docker containers.
+* Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
 */
-function buildEnv(extra) {
-	const env = {
-		...process.env,
-		INIT_CWD: void 0
-	};
-	if (extra) for (const [key, value] of Object.entries(extra)) if (value === null) delete env[key];
-	else env[key] = value;
-	return env;
-}
+var DockerAssertion = class {
+	container;
+	constructor(container) {
+		this.container = container;
+	}
+	/** Assert the container is running */
+	async toBeRunning() {
+		if (!await this.container.isRunning()) throw new Error("Expected container to be running");
+		return this;
+	}
+	/** Assert the container is NOT running / doesn't exist */
+	async toNotExist() {
+		if (await this.container.isRunning()) throw new Error("Expected container to not exist or not be running");
+		return this;
+	}
+	/** Assert a file exists inside the container */
+	async toHaveFile(path, opts) {
+		const file = await this.container.file(path);
+		if (!file.exists) throw new Error(`Expected file ${path} to exist in container`);
+		if (opts?.containing && !file.content.includes(opts.containing)) throw new Error(`Expected file ${path} to contain "${opts.containing}", got: ${file.content.slice(0, 200)}`);
+		return this;
+	}
+	/** Assert a file does NOT exist */
+	async toNotHaveFile(path) {
+		if (await this.container.exists(path)) throw new Error(`Expected ${path} to not exist in container`);
+		return this;
+	}
+	/** Assert a directory exists */
+	async toHaveDirectory(path) {
+		if (!await this.container.exists(path)) throw new Error(`Expected directory ${path} to exist in container`);
+		return this;
+	}
+	/** Assert a mount exists */
+	async toHaveMount(destination) {
+		const info = await this.container.inspect();
+		if (!info.hostConfig.mounts.find((m) => m.destination === destination)) {
+			const available = info.hostConfig.mounts.map((m) => m.destination).join(", ");
+			throw new Error(`Expected mount at ${destination}, found: [${available}]`);
+		}
+		return this;
+	}
+	/** Assert network mode */
+	async toHaveNetwork(mode) {
+		const info = await this.container.inspect();
+		if (!info.hostConfig.networkMode.includes(mode)) throw new Error(`Expected network mode "${mode}", got "${info.hostConfig.networkMode}"`);
+		return this;
+	}
+	/** Assert memory limit */
+	async toHaveMemoryLimit(bytes) {
+		const info = await this.container.inspect();
+		if (info.hostConfig.memory !== bytes) throw new Error(`Expected memory limit ${bytes}, got ${info.hostConfig.memory}`);
+		return this;
+	}
+	/** Assert CPU quota */
+	async toHaveCpuQuota(quota) {
+		const info = await this.container.inspect();
+		if (info.hostConfig.cpuQuota !== quota) throw new Error(`Expected CPU quota ${quota}, got ${info.hostConfig.cpuQuota}`);
+		return this;
+	}
+	/** Execute a command and return output for custom assertions */
+	async exec(cmd) {
+		return this.container.exec(cmd);
+	}
+	/** Read a file for custom assertions */
+	async readFile(path) {
+		const file = await this.container.file(path);
+		if (!file.exists) throw new Error(`File ${path} does not exist`);
+		return file.content;
+	}
+	/** Get logs for custom assertions */
+	async getLogs(tail) {
+		return this.container.logs(tail);
+	}
+};
+//#endregion
+//#region src/infra/docker/docker.ts
 /**
-* Executes CLI commands via Node.js child_process.
-* Uses `execSync` for one-shot commands and `spawn` for long-running processes.
-* Used by the `cli()` specification runner.
+* Implements {@link DockerContainerPort} by shelling out to the Docker CLI.
+* Each instance is bound to a single container ID.
 */
-var ExecAdapter = class {
-	command;
-	constructor(command) {
-		this.command = command;
+var DockerAdapter = class {
+	containerId;
+	constructor(containerId) {
+		this.containerId = containerId;
 	}
-	async exec(args, cwd, extraEnv) {
-		const env = buildEnv(extraEnv);
+	async exec(cmd) {
+		return execSync(`docker exec ${this.containerId} ${cmd.map((c) => `'${c}'`).join(" ")}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		}).trim();
+	}
+	async file(path) {
 		try {
 			return {
-				exitCode: 0,
-				stdout: execSync(`${this.command} ${args}`, {
-					cwd,
-					encoding: "utf8",
-					env,
-					stdio: [
-						"pipe",
-						"pipe",
-						"pipe"
-					]
-				}),
-				stderr: ""
+				exists: true,
+				content: await this.exec(["cat", path])
 			};
-		} catch (error) {
+		} catch {
 			return {
-				exitCode: error.status ?? 1,
-				stdout: error.stdout?.toString() ?? "",
-				stderr: error.stderr?.toString() ?? ""
+				exists: false,
+				content: ""
 			};
 		}
 	}
-	async spawn(args, cwd, options, extraEnv) {
-		const env = buildEnv(extraEnv);
-		return new Promise((resolve) => {
-			let stdout = "";
-			let stderr = "";
-			let resolved = false;
-			const child = spawn(this.command, args.split(/\s+/).filter(Boolean), {
-				cwd,
-				env,
-				stdio: [
-					"pipe",
-					"pipe",
-					"pipe"
-				]
-			});
-			const finish = (exitCode) => {
-				if (resolved) return;
-				resolved = true;
-				child.kill("SIGTERM");
-				resolve({
-					exitCode,
-					stdout,
-					stderr
-				});
-			};
-			let patternMatched = false;
-			const checkPattern = () => {
-				if (!patternMatched && (stdout.includes(options.waitFor) || stderr.includes(options.waitFor))) {
-					patternMatched = true;
-					finish(0);
-				}
-			};
-			child.stdout?.on("data", (data) => {
-				stdout += data.toString();
-				checkPattern();
-			});
-			child.stderr?.on("data", (data) => {
-				stderr += data.toString();
-				checkPattern();
-			});
-			child.on("exit", (code) => {
-				if (!patternMatched) finish(code === 0 ? 1 : code ?? 1);
-			});
-			setTimeout(() => finish(124), options.timeout);
-		});
+	async isRunning() {
+		try {
+			return execSync(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
+				encoding: "utf8",
+				timeout: 5e3
+			}).trim() === "true";
+		} catch {
+			return false;
+		}
 	}
-};
-//#endregion
-//#region src/builder/http/adapters/fetch.adapter.ts
-/**
-* Server adapter that sends real HTTP requests via the Fetch API.
-* Used by the `e2e()` specification runner to hit a live server.
-*/
-var FetchAdapter = class {
-	baseUrl;
-	constructor(url) {
-		this.baseUrl = url.replace(/\/$/, "");
+	async logs(tail) {
+		return execSync(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 1e4
+		});
 	}
-	async request(method, path, body, headers) {
-		const init = {
-			method,
-			headers: {
-				"Content-Type": "application/json",
-				...headers
-			}
-		};
-		if (body !== void 0) init.body = JSON.stringify(body);
-		const response = await fetch(`${this.baseUrl}${path}`, init);
-		const responseBody = await response.json().catch(() => null);
-		const responseHeaders = {};
-		response.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
+	async inspect() {
+		const raw = execSync(`docker inspect ${this.containerId}`, {
+			encoding: "utf8",
+			timeout: 5e3
 		});
+		const data = JSON.parse(raw)[0];
 		return {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
+			id: data.Id,
+			name: data.Name,
+			state: {
+				running: data.State.Running,
+				exitCode: data.State.ExitCode,
+				status: data.State.Status
+			},
+			config: {
+				image: data.Config.Image,
+				env: data.Config.Env || []
+			},
+			hostConfig: {
+				memory: data.HostConfig.Memory || 0,
+				cpuQuota: data.HostConfig.CpuQuota || 0,
+				networkMode: data.HostConfig.NetworkMode || "",
+				mounts: (data.Mounts || []).map((m) => ({
+					source: m.Source,
+					destination: m.Destination,
+					type: m.Type
+				}))
+			},
+			networkSettings: { networks: Object.fromEntries(Object.entries(data.NetworkSettings.Networks || {}).map(([name, net]) => [name, {
+				gateway: net.Gateway,
+				ipAddress: net.IPAddress
+			}])) }
 		};
 	}
+	async exists(path) {
+		try {
+			await this.exec([
+				"test",
+				"-e",
+				path
+			]);
+			return true;
+		} catch {
+			return false;
+		}
+	}
 };
+/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
+function dockerContainer(containerId) {
+	return new DockerAdapter(containerId);
+}
 //#endregion
-//#region src/builder/http/adapters/hono.adapter.ts
-/**
-* Server adapter that dispatches requests in-process through a Hono app instance.
-* Used by the `integration()` specification runner -- no network overhead.
-*/
-var HonoAdapter = class {
-	app;
-	constructor(app) {
-		this.app = app;
-	}
-	async request(method, path, body, headers) {
-		const init = {
-			method,
-			headers: {
-				"Content-Type": "application/json",
-				...headers
-			}
-		};
-		if (body !== void 0) init.body = JSON.stringify(body);
-		const response = await this.app.request(path, init);
-		const responseBody = await response.json().catch(() => null);
-		const responseHeaders = {};
-		response.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers: responseHeaders
-		};
-	}
-};
-//#endregion
-//#region src/builder/common/directory.ts
-/**
-* Default ignore patterns — paths that should never appear in a tracked snapshot.
-* Each entry is matched against any path segment OR a path prefix.
-*/
-const DEFAULT_IGNORES = [
-	".git",
-	".DS_Store",
-	"node_modules",
-	".next",
-	"dist",
-	".turbo",
-	".cache"
-];
-/**
-* Recursively walk a directory, returning sorted relative paths of files only.
-* Ignored entries (default + caller-supplied) are skipped.
-*/
-async function walkDirectory(root, options = {}) {
-	const ignores = 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.
-* Binary files are compared by byte equality but reported without inline diff.
-*/
-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 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 (expected !== actual) changed.push({
-			actual,
-			expected,
-			path: file
-		});
-	}
-	return {
-		added,
-		changed,
-		removed
-	};
-}
-//#endregion
-//#region src/builder/common/reporter.ts
+//#region src/spec/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
 const DIM = "\x1B[2m";
@@ -320,6 +265,27 @@ function formatResponseDiff(file, expected, actual) {
 	}
 	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;
@@ -367,1123 +333,1669 @@ function rowLabel(n) {
 function formatRow(row) {
 	return row.map((v) => String(v ?? "null")).join("  |  ");
 }
-/** Strip ANSI escape codes from a string. */
-function stripAnsi(str) {
-	return str.replace(/\x1b\[[0-9;]*m/g, "");
+//#endregion
+//#region src/infra/containers/compose-parser.ts
+/**
+* Detect the service type from the image name.
+*/
+function detectServiceType(image) {
+	if (!image) return "app";
+	const lower = image.toLowerCase();
+	if (lower.startsWith("postgres")) return "postgres";
+	if (lower.startsWith("redis")) return "redis";
+	return "unknown";
 }
-/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
-function normalizeOutput(str) {
-	return stripAnsi(str).replace(/localhost:\d+/g, "localhost:PORT").replace(/\d+ms/g, "Xms").replace(/\d+\.\d+s/g, "X.Xs").trim();
+/**
+* Find the compose file in the project.
+* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
+*/
+function findComposeFile(projectRoot) {
+	const candidates = [
+		resolve(projectRoot, "docker/compose.test.yaml"),
+		resolve(projectRoot, "docker/compose.test.yml"),
+		resolve(projectRoot, "docker-compose.test.yaml"),
+		resolve(projectRoot, "docker-compose.test.yml")
+	];
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+	return null;
 }
-//#endregion
-//#region src/builder/common/directory-accessor.ts
 /**
-* Detect whether the user wants to update snapshots — `true` for any of:
-*   - vitest run with `-u` / `--update`
-*   - JTERRAZZ_TEST_UPDATE=1
-*   - UPDATE_SNAPSHOTS=1
+* Parse a docker-compose file and extract service definitions.
 */
-function shouldUpdateSnapshots() {
-	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
-	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
-	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
-	return false;
+function parseComposeFile(filePath) {
+	const doc = parse(readFileSync(filePath, "utf8"));
+	if (!doc?.services) return {
+		services: [],
+		appService: null,
+		infraServices: []
+	};
+	const services = Object.entries(doc.services).map(([name, def]) => {
+		const ports = [];
+		if (def.ports) for (const port of def.ports) {
+			const str = String(port);
+			if (str.includes(":")) {
+				const [host, container] = str.split(":");
+				ports.push({
+					container: Number(container),
+					host: Number(host)
+				});
+			} else ports.push({ container: Number(str) });
+		}
+		const environment = {};
+		if (def.environment) if (Array.isArray(def.environment)) for (const env of def.environment) {
+			const [key, ...rest] = String(env).split("=");
+			environment[key] = rest.join("=");
+		}
+		else Object.assign(environment, def.environment);
+		const volumes = def.volumes ? def.volumes.map((v) => String(v)) : [];
+		let dependsOn = [];
+		if (def.depends_on) dependsOn = Array.isArray(def.depends_on) ? def.depends_on : Object.keys(def.depends_on);
+		return {
+			name,
+			image: def.image,
+			build: def.build,
+			ports,
+			environment,
+			volumes,
+			dependsOn
+		};
+	});
+	return {
+		services,
+		appService: services.find((s) => s.build !== void 0) ?? null,
+		infraServices: services.filter((s) => s.build === void 0)
+	};
 }
+//#endregion
+//#region src/infra/containers/compose.ts
 /**
-* Handle to a directory produced by a specification run.
-* Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
+* Start the full compose stack and stop it all on cleanup.
+* Supports per-worker project names for parallel execution.
 */
-var DirectoryAccessor = class {
-	absPath;
-	testDir;
-	constructor(absPath, testDir) {
-		this.absPath = absPath;
-		this.testDir = testDir;
+var ComposeStackAdapter = class {
+	composeFile;
+	projectName;
+	started = false;
+	constructor(composeFile, projectName) {
+		this.composeFile = composeFile;
+		this.projectName = projectName ?? null;
 	}
-	/**
-	* Compare the directory tree against `expected/{name}/` (relative to the test file).
-	* On mismatch, throws with a structured diff. With update mode enabled, the
-	* fixture is overwritten with the current contents instead.
-	*/
-	async toMatchFixture(name, options = {}) {
-		const fixtureDir = resolve(this.testDir, "expected", name);
-		if (options.update ?? shouldUpdateSnapshots()) {
-			rmSync(fixtureDir, {
-				force: true,
-				recursive: true
-			});
-			mkdirSync(fixtureDir, { recursive: true });
-			cpSync(this.absPath, fixtureDir, { recursive: true });
-			return;
+	get projectFlag() {
+		return this.projectName ? `-p ${this.projectName}` : "";
+	}
+	run(command) {
+		try {
+			return execSync(command, {
+				cwd: dirname(this.composeFile),
+				encoding: "utf8",
+				timeout: 12e4
+			}).trim();
+		} catch (error) {
+			const stderr = error.stderr?.toString().trim() ?? error.message;
+			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
 		}
-		if (!existsSync(fixtureDir)) throw new Error(`Directory fixture "${name}" does not exist at ${fixtureDir}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
-		const diff = await diffDirectories(fixtureDir, this.absPath, { ignore: options.ignore });
-		if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return;
-		throw new Error(formatDirectoryDiff(name, diff, "Run with JTERRAZZ_TEST_UPDATE=1 to update the fixture."));
 	}
-	/**
-	* List all files in the directory (recursive, sorted, ignoring defaults).
-	* Useful for ad-hoc assertions when you don't want a full snapshot.
-	*/
-	async files(options = {}) {
-		return walkDirectory(this.absPath, options);
+	async start() {
+		if (this.started) return;
+		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} up -d --wait`);
+		this.started = true;
+	}
+	async stop() {
+		if (!this.started) return;
+		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} down -v`);
+		this.started = false;
+	}
+	getMappedPort(serviceName, containerPort) {
+		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
+		return Number(port);
+	}
+	getHost() {
+		return "localhost";
 	}
 };
 //#endregion
-//#region src/builder/common/grep.ts
+//#region src/infra/containers/testcontainers.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/builder/common/response-accessor.ts
-/** Accessor for an HTTP response body with file-based assertion support. */
-var ResponseAccessor = class {
-	body;
-	testDir;
-	constructor(body, testDir) {
-		this.body = body;
-		this.testDir = testDir;
-	}
-	/**
-	* Assert that the response body matches the JSON in `responses/{file}`.
-	*
-	* @example
-	*   result.response.toMatchFile("expected-items.json");
-	*/
-	toMatchFile(file) {
-		const expected = JSON.parse(readFileSync(resolve(this.testDir, "responses", file), "utf8"));
-		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
-	}
-};
-//#endregion
-//#region src/builder/common/table-assertion.ts
-/** Assertion helper for verifying database table contents after a specification run. */
-var TableAssertion = class {
-	tableName;
-	db;
-	constructor(tableName, db) {
-		this.tableName = tableName;
-		this.db = db;
-	}
-	/**
-	* Assert that the table contains exactly the expected rows for the given columns.
-	*
-	* @example
-	*   await result.table("users").toMatch({
-	*     columns: ["name", "email"],
-	*     rows: [["Alice", "alice@example.com"]],
-	*   });
-	*/
-	async toMatch(expected) {
-		const actual = await this.db.query(this.tableName, expected.columns);
-		if (JSON.stringify(actual) !== JSON.stringify(expected.rows)) throw new Error(formatTableDiff(this.tableName, expected.columns, expected.rows, actual));
-	}
-	/** Assert that the table has zero rows. */
-	async toBeEmpty() {
-		const actual = await this.db.query(this.tableName, ["*"]);
-		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
-	}
-};
-//#endregion
-//#region src/builder/common/result.ts
-/**
-* The outcome of a single specification run.
-* Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+* Container adapter using testcontainers.
+* Wraps a GenericContainer for programmatic container lifecycle.
 */
-var SpecificationResult = class {
-	commandResult;
-	config;
-	requestInfo;
-	responseData;
-	testDir;
-	workDir;
+var TestcontainersAdapter = class {
+	image;
+	containerPort;
+	env;
+	reuse;
+	container = null;
 	constructor(options) {
-		this.responseData = options.response;
-		this.commandResult = options.commandResult;
-		this.config = options.config;
-		this.testDir = options.testDir;
-		this.requestInfo = options.requestInfo;
-		this.workDir = options.workDir;
-	}
-	/** The process exit code. Only available after a CLI action. */
-	get exitCode() {
-		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
-		return this.commandResult.exitCode;
-	}
-	/** The HTTP response status code. Only available after an HTTP action. */
-	get status() {
-		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
-		return this.responseData.status;
-	}
-	/** The captured standard output. Only available after a CLI action. */
-	get stdout() {
-		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
-		return this.commandResult.stdout;
-	}
-	/** The captured standard error. Only available after a CLI action. */
-	get stderr() {
-		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
-		return this.commandResult.stderr;
+		this.image = options.image;
+		this.containerPort = options.port;
+		this.env = options.env ?? {};
+		this.reuse = options.reuse ?? false;
 	}
-	/**
-	* Extract text blocks from stdout that contain a pattern.
-	* Useful for parsing structured CLI output (linters, compilers).
-	*
-	* @example
-	*   expect(result.grep('error.ts')).toContain('no-unused-vars');
-	*/
-	grep(pattern) {
-		return grep(this.stdout, pattern);
+	async start() {
+		const { GenericContainer, Wait } = await import("testcontainers");
+		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort);
+		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
+		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/, 2));
+		if (this.reuse) builder = builder.withReuse();
+		this.container = await builder.start();
 	}
-	/** Access the HTTP response body for assertions. Only available after an HTTP action. */
-	get response() {
-		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
-		return new ResponseAccessor(this.responseData.body, this.testDir);
+	async stop() {
+		if (this.container && !this.reuse) {
+			await this.container.stop();
+			this.container = null;
+		}
 	}
-	/** Access a directory (relative to the working directory) for snapshot assertions. */
-	directory(path = ".") {
-		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir);
+	getMappedPort(containerPort) {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getMappedPort(containerPort);
 	}
-	/** 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);
-		return {
-			get content() {
-				if (!exists) throw new Error(`File not found: ${path}`);
-				return readFileSync(resolvedPath, "utf8");
-			},
-			exists
-		};
+	getHost() {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getHost();
 	}
-	/** Access a database table for row-level assertions. */
-	table(tableName, options) {
-		const db = this.resolveDatabase(options?.service);
-		if (!db) throw new Error(options?.service ? `table("${tableName}") requires database "${options.service}" but it was not found` : `table("${tableName}") requires a database adapter`);
-		return new TableAssertion(tableName, db);
+	getConnectionString() {
+		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
 	}
-	resolveDatabase(serviceName) {
-		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
-		return this.config.database;
+	async getLogs() {
+		if (!this.container) return "";
+		const stream = await this.container.logs();
+		return new Promise((resolve) => {
+			let output = "";
+			stream.on("data", (chunk) => {
+				output += chunk.toString();
+			});
+			stream.on("end", () => {
+				resolve(output);
+			});
+			setTimeout(() => {
+				resolve(output);
+			}, 1e3);
+		});
 	}
 };
 //#endregion
-//#region src/builder/specification-builder.ts
+//#region src/infra/orchestrator.ts
 /**
-* Fluent builder for declaring a single test specification.
-*
-* Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
-* ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
-* and receive a {@link SpecificationResult} for assertions.
+* Orchestrator for test infrastructure.
+* Integration: starts services via testcontainers.
+* E2E: runs full docker compose up.
 */
-var SpecificationBuilder = class {
-	commandArgs = null;
-	commandEnv = {};
-	config;
-	fixtures = [];
-	intercepts = [];
-	jobName = null;
-	label;
-	mocks = [];
-	projectName = null;
-	request = null;
-	requestHeaders = {};
-	seeds = [];
-	spawnConfig = null;
-	testDir;
-	constructor(config, testDir, label) {
-		this.config = config;
-		this.testDir = testDir;
-		this.label = label;
-	}
-	/**
-	* Queue a SQL seed file to run before the action.
-	*
-	* @example
-	*   spec("creates user").seed("users.sql").exec("list-users").run();
-	*/
-	seed(file, options) {
-		this.seeds.push({
-			file,
-			service: options?.service
-		});
-		return this;
-	}
-	/** Copy a file or directory from `fixtures/` into the working directory before execution. */
-	fixture(file) {
-		this.fixtures.push({ file });
-		return this;
-	}
-	/** Copy an entire project fixture from `fixturesRoot` into the working directory. */
-	project(name) {
-		this.projectName = name;
-		return this;
-	}
-	/** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
-	mock(file) {
-		this.mocks.push({ file });
-		return this;
-	}
-	/**
-	* Set environment variables for the CLI process. Merged on top of process.env.
-	* Use `null` to unset a variable. Multiple calls merge.
-	*
-	* The token `$WORKDIR` (in any value) is replaced with the actual working
-	* directory at run-time — useful for tests that need a fully isolated `HOME`.
-	*
-	* @example
-	*   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
-	*/
-	env(env) {
-		this.commandEnv = {
-			...this.commandEnv,
-			...env
-		};
-		return this;
+var Orchestrator = class {
+	services;
+	mode;
+	root;
+	projectName;
+	running = [];
+	composeStack = null;
+	composeHandles = [];
+	started = false;
+	constructor(options) {
+		this.services = options.services;
+		this.mode = options.mode;
+		this.root = options.root ?? process.cwd();
+		this.projectName = options.projectName;
 	}
 	/**
-	* Set HTTP headers for the request. Multiple calls merge.
-	*
-	* @example
-	*   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+	* Start declared services via testcontainers (integration mode).
+	* Phase 1: start all containers in parallel (the slow part).
+	* Phase 2: wire connections, healthcheck, and init sequentially (fast).
 	*/
-	headers(headers) {
-		this.requestHeaders = {
-			...this.requestHeaders,
-			...headers
-		};
-		return this;
-	}
-	/**
-	* Intercept an outgoing HTTP request and return a controlled response.
-	* Uses MSW under the hood. Intercepts are queued — multiple calls with the
-	* same trigger fire sequentially (first match consumed first).
-	*
-	* @param trigger - What to match (use openai.agent(), http.get(), etc.)
-	* @param response - What to return: an InterceptResponse object, or a filename
-	*   from `intercepts/` (JSON loaded and auto-wrapped by the trigger).
-	*
-	* @example
-	*   // With inline response
-	*   .intercept(openai.agent({...}), openai.reply({ categories: ['TECH'] }))
-	*
-	*   // With JSON fixture file (loaded from intercepts/ directory)
-	*   .intercept(openai.agent({...}), 'ingest-tech.json')
-	*   .intercept(http.get(url), 'world-news-tech.json')
-	*/
-	intercept(trigger, response) {
-		if (typeof response === "string") {
-			const slashIndex = response.indexOf("/");
-			if (slashIndex === -1) throw new Error(`.intercept(): file path must be 'adapter/filename.json' (e.g. 'openai/ingest-tech.json'), got '${response}'`);
-			const adapterName = response.slice(0, slashIndex);
-			if (adapterName !== trigger.adapter) throw new Error(`.intercept(): adapter mismatch - trigger uses '${trigger.adapter}' but file path starts with '${adapterName}/'`);
-			const filePath = resolve(this.testDir, "intercepts", response);
-			const data = JSON.parse(readFileSync(filePath, "utf8"));
-			const resolved = trigger.wrap(data);
-			this.intercepts.push({
-				trigger,
-				response: resolved
+	async start() {
+		if (this.started) return;
+		const composePath = findComposeFile(this.root);
+		const composeDir = composePath ? dirname(composePath) : this.root;
+		const composeConfig = composePath ? parseComposeFile(composePath) : null;
+		const containerServices = [];
+		const embeddedServices = [];
+		for (const handle of this.services) {
+			if (handle.defaultPort === 0) {
+				embeddedServices.push(handle);
+				continue;
+			}
+			let image = handle.defaultImage;
+			let env = { ...handle.environment };
+			if (handle.composeName && composeConfig) {
+				const composeService = composeConfig.services.find((s) => s.name === handle.composeName);
+				if (composeService) {
+					image = composeService.image ?? image;
+					env = {
+						...env,
+						...composeService.environment
+					};
+					Object.assign(handle.environment, composeService.environment);
+				}
+			}
+			const container = new TestcontainersAdapter({
+				image,
+				port: handle.defaultPort,
+				env
 			});
-		} else this.intercepts.push({
-			trigger,
-			response
-		});
-		return this;
+			containerServices.push({
+				container,
+				handle
+			});
+		}
+		await Promise.all([...containerServices.map(({ container }) => container.start()), ...embeddedServices.map(async (handle) => {
+			await handle.initialize(composeDir);
+			handle.started = true;
+			this.running.push({
+				handle,
+				container: null
+			});
+		})]);
+		const reports = [];
+		for (const { container, handle } of containerServices) {
+			const serviceStartTime = Date.now();
+			try {
+				const host = container.getHost();
+				const port = container.getMappedPort(handle.defaultPort);
+				handle.connectionString = handle.buildConnectionString(host, port);
+				await handle.healthcheck();
+				await handle.initialize(composeDir);
+				handle.started = true;
+				reports.push({
+					name: handle.composeName ?? handle.type,
+					type: handle.type,
+					connectionString: handle.connectionString,
+					durationMs: Date.now() - serviceStartTime
+				});
+				this.running.push({
+					handle,
+					container
+				});
+			} catch (error) {
+				let logs = "";
+				try {
+					logs = await container.getLogs();
+				} catch {}
+				try {
+					await container.stop();
+				} catch {}
+				reports.push({
+					name: handle.composeName ?? handle.type,
+					type: handle.type,
+					durationMs: Date.now() - serviceStartTime,
+					error: error.message,
+					logs
+				});
+				const output = formatStartupReport("integration", reports, { type: "in-process" });
+				console.error(output);
+				throw error;
+			}
+		}
+		this.started = true;
+		const output = formatStartupReport("integration", reports, { type: "in-process" });
+		console.log(output);
 	}
 	/**
-	* Send a GET request to the server adapter.
-	*
-	* @example
-	*   spec("list items").get("/api/items").run();
+	* Stop testcontainers (integration mode).
 	*/
-	get(path) {
-		this.request = {
-			method: "GET",
-			path
-		};
-		return this;
+	async stop() {
+		for (const { container } of this.running) if (container) await container.stop();
+		this.running = [];
+		this.started = false;
 	}
 	/**
-	* Send a POST request to the server adapter.
-	*
-	* @param bodyFile - Optional JSON file from `requests/` to use as the request body.
-	* @example
-	*   spec("create item").post("/api/items", "new-item.json").run();
+	* Start full docker compose stack (e2e mode).
+	* Auto-detects infra services and creates handles for them.
 	*/
-	post(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "POST",
-			path
-		};
-		return this;
-	}
-	/** Send a PUT request to the server adapter. */
-	put(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "PUT",
-			path
-		};
-		return this;
-	}
-	/** Send a DELETE request to the server adapter. */
-	delete(path) {
-		this.request = {
-			method: "DELETE",
-			path
-		};
-		return this;
+	async startCompose() {
+		const composePath = findComposeFile(this.root);
+		if (!composePath) throw new Error(`E2E: no compose file found in ${this.root}`);
+		const startTime = Date.now();
+		const composeDir = dirname(composePath);
+		const composeConfig = parseComposeFile(composePath);
+		this.composeStack = new ComposeStackAdapter(composePath, this.projectName);
+		await this.composeStack.start();
+		for (const service of composeConfig.infraServices) {
+			const type = detectServiceType(service.image);
+			if (type === "postgres") {
+				const handle = postgres({
+					compose: service.name,
+					env: service.environment
+				});
+				const port = this.composeStack.getMappedPort(service.name, 5432);
+				handle.connectionString = handle.buildConnectionString("localhost", port);
+				await handle.initialize(composeDir);
+				handle.started = true;
+				this.composeHandles.push(handle);
+			} else if (type === "redis") {
+				const handle = redis({ compose: service.name });
+				const port = this.composeStack.getMappedPort(service.name, 6379);
+				handle.connectionString = handle.buildConnectionString("localhost", port);
+				handle.started = true;
+				this.composeHandles.push(handle);
+			}
+		}
+		const durationMs = Date.now() - startTime;
+		const output = formatStartupReport("e2e", this.composeHandles.map((h) => ({
+			name: h.composeName ?? h.type,
+			type: h.type,
+			connectionString: h.connectionString,
+			durationMs
+		})), {
+			type: "http",
+			url: this.getAppUrl() ?? void 0
+		});
+		console.log(output);
 	}
 	/**
-	* Execute a CLI command (or a sequence of commands) in an isolated working directory.
-	* When an array is passed, commands run sequentially and stop on the first non-zero exit code.
-	*
-	* @example
-	*   spec("init project").exec("init --name demo").run();
-	*   spec("multi-step").exec(["init", "build"]).run();
+	* Stop docker compose stack (e2e mode).
 	*/
-	exec(args) {
-		this.commandArgs = args;
-		return this;
-	}
-	/** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
-	spawn(args, options) {
-		this.spawnConfig = {
-			args,
-			options
-		};
-		return this;
+	async stopCompose() {
+		if (this.composeStack) {
+			await this.composeStack.stop();
+			this.composeStack = null;
+		}
+		this.composeHandles = [];
 	}
 	/**
-	* Execute a named job registered via the app() factory.
-	*
-	* @param name - The job name to trigger (must match a registered JobHandle.name).
-	*
-	* @example
-	*   spec('pipeline').intercept(openai.chat(), openai.response({...})).job('report-refresh').run();
+	* Get a database service by compose name, or the first one if no name given.
 	*/
-	job(name) {
-		this.jobName = name;
-		return this;
+	getDatabase(serviceName) {
+		for (const handle of [...this.services, ...this.composeHandles]) {
+			if (serviceName && handle.composeName !== serviceName) continue;
+			const adapter = handle.createDatabaseAdapter();
+			if (adapter) return adapter;
+		}
+		return null;
 	}
 	/**
-	* Execute the specification: run seeds, copy fixtures, then perform the
-	* configured action (HTTP or CLI).
-	*
-	* @returns The result object used for assertions.
-	* @example
-	*   const result = await spec("test").exec("status").run();
-	*   expect(result.exitCode).toBe(0);
+	* Get all database services keyed by compose name.
 	*/
-	async run() {
-		const hasHttpAction = this.request !== null;
-		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
-		const hasJobAction = this.jobName !== null;
-		const actionCount = [
-			hasHttpAction,
-			hasCliAction,
-			hasJobAction
-		].filter(Boolean).length;
-		if (actionCount === 0) throw new Error(`Specification "${this.label}": no action defined. Call .get(), .post(), .exec(), .job(), etc. before .run()`);
-		if (actionCount > 1) throw new Error(`Specification "${this.label}": cannot mix action types (.get/.post, .exec/.spawn, .job)`);
-		let workDir = null;
-		if (hasCliAction) workDir = this.prepareWorkDir();
-		if (this.config.databases) for (const db of this.config.databases.values()) await db.reset();
-		else if (this.config.database) await this.config.database.reset();
-		for (const entry of this.seeds) {
-			let db;
-			if (entry.service && this.config.databases) {
-				db = this.config.databases.get(entry.service);
-				if (!db) throw new Error(`seed() targets database "${entry.service}" but it was not found. Available: ${[...this.config.databases.keys()].join(", ")}`);
-			} else db = this.config.database;
-			if (!db) throw new Error("seed() requires a database adapter");
-			const sql = readFileSync(resolve(this.testDir, "seeds", entry.file), "utf8");
-			await db.seed(sql);
-		}
-		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) cpSync(resolve(this.testDir, "fixtures", entry.file), resolve(workDir, entry.file), { recursive: true });
-		let cleanupIntercepts = null;
-		if (this.intercepts.length > 0) {
-			const { registerIntercepts } = await import("./intercept2.js");
-			cleanupIntercepts = await registerIntercepts(this.intercepts);
-		}
-		try {
-			if (hasHttpAction) return await this.runHttpAction();
-			if (hasJobAction) return await this.runJobAction();
-			return await this.runCliAction(workDir);
-		} finally {
-			if (cleanupIntercepts) cleanupIntercepts();
+	getDatabases() {
+		const map = /* @__PURE__ */ new Map();
+		for (const handle of [...this.services, ...this.composeHandles]) {
+			const adapter = handle.createDatabaseAdapter();
+			if (adapter && handle.composeName) map.set(handle.composeName, adapter);
 		}
+		return map;
 	}
-	resolveEnv(workDir) {
-		const keys = Object.keys(this.commandEnv);
-		if (keys.length === 0) return;
-		const resolved = {};
-		for (const key of keys) {
-			const value = this.commandEnv[key];
-			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
-		}
-		return resolved;
+	/**
+	* Get app URL from compose (e2e mode).
+	*/
+	getAppUrl() {
+		const composePath = findComposeFile(this.root);
+		if (!composePath || !this.composeStack) return null;
+		const appService = parseComposeFile(composePath).appService;
+		if (!appService || appService.ports.length === 0) return null;
+		return `http://localhost:${this.composeStack.getMappedPort(appService.name, appService.ports[0].container)}`;
 	}
-	prepareWorkDir() {
-		const tempDir = mkdtempSync(resolve(tmpdir(), "spec-cli-"));
-		if (this.projectName && this.config.fixturesRoot) {
-			const projectDir = resolve(this.config.fixturesRoot, this.projectName);
-			if (!existsSync(projectDir)) throw new Error(`project("${this.projectName}"): fixture project not found at ${projectDir}`);
-			cpSync(projectDir, tempDir, { recursive: true });
+};
+//#endregion
+//#region src/spec/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 = new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current);
+		} catch {
+			return;
 		}
-		return tempDir;
-	}
-	async runHttpAction() {
-		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use integration() or e2e())");
-		let body;
-		if (this.request.bodyFile) body = JSON.parse(readFileSync(resolve(this.testDir, "requests", this.request.bodyFile), "utf8"));
-		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
-		const response = await this.config.server.request(this.request.method, this.request.path, body, headers);
-		return new SpecificationResult({
-			config: this.config,
-			requestInfo: {
-				body,
-				method: this.request.method,
-				path: this.request.path
-			},
-			response,
-			testDir: this.testDir
-		});
-	}
-	async runJobAction() {
-		if (!this.config.jobs?.length) throw new Error("Job actions require jobs registered via app(() => ({ server, jobs }))");
-		const job = this.config.jobs.find((j) => j.name === this.jobName);
-		if (!job) {
-			const available = this.config.jobs.map((j) => j.name).join(", ");
-			throw new Error(`job("${this.jobName}"): not found. Available: ${available}`);
+		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 job.execute();
-		return new SpecificationResult({
-			config: this.config,
-			testDir: this.testDir
-		});
-	}
-	async runCliAction(workDir) {
-		if (!this.config.command) throw new Error("CLI actions require a command adapter (use cli())");
-		const env = this.resolveEnv(workDir);
-		let commandResult;
-		if (this.spawnConfig) commandResult = await this.config.command.spawn(this.spawnConfig.args, workDir, this.spawnConfig.options, env);
-		else if (Array.isArray(this.commandArgs)) {
-			commandResult = {
-				exitCode: 0,
-				stderr: "",
-				stdout: ""
-			};
-			for (const args of this.commandArgs) {
-				commandResult = await this.config.command.exec(args, workDir, env);
-				if (commandResult.exitCode !== 0) break;
-			}
-		} else commandResult = await this.config.command.exec(this.commandArgs, workDir, env);
-		return new SpecificationResult({
-			commandResult,
-			config: this.config,
-			testDir: this.testDir,
-			workDir
-		});
-	}
-};
-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:\/\/)?([^:)]+):\d+:\d+/);
-		if (!match) continue;
-		const filePath = match[1];
-		if (filePath.includes("node_modules")) continue;
-		if (filePath.includes("/src/builder/") || filePath.includes("/src/spec/")) continue;
-		return resolve(filePath, "..");
 	}
-	throw new Error("Cannot detect caller directory from stack trace");
+	await walk(root);
+	out.sort();
+	return out;
 }
 /**
-* Create a {@link SpecificationRunner} bound to the given adapter configuration.
-* The test file directory is auto-detected from the call stack.
+* Compare two directory trees file-by-file.
 */
-function createSpecificationRunner(config) {
-	return (label) => {
-		return new SpecificationBuilder(config, getCallerDir(), label);
+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 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 (expected !== actual) changed.push({
+			actual,
+			expected,
+			path: file
+		});
+	}
+	return {
+		added,
+		changed,
+		removed
 	};
 }
+function shouldUpdateSnapshots$3() {
+	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
+	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
+	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
+	return false;
+}
+var DirectoryAccessor = class {
+	absPath;
+	testDir;
+	constructor(absPath, testDir) {
+		this.absPath = absPath;
+		this.testDir = testDir;
+	}
+	async toMatchFixture(name, options = {}) {
+		const fixtureDir = resolve(this.testDir, "expected", name);
+		if (options.update ?? shouldUpdateSnapshots$3()) {
+			rmSync(fixtureDir, {
+				force: true,
+				recursive: true
+			});
+			mkdirSync(fixtureDir, { recursive: true });
+			cpSync(this.absPath, fixtureDir, { recursive: true });
+			return;
+		}
+		if (!existsSync(fixtureDir)) throw new Error(`Directory fixture "${name}" does not exist at ${fixtureDir}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
+		const diff = await diffDirectories(fixtureDir, this.absPath, { ignore: options.ignore });
+		if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return;
+		throw new Error(formatDirectoryDiff(name, diff, "Run with JTERRAZZ_TEST_UPDATE=1 to update the fixture."));
+	}
+	async files(options = {}) {
+		return walkDirectory(this.absPath, options);
+	}
+};
 //#endregion
-//#region src/docker/docker-adapter.ts
+//#region src/spec/result/filesystem.ts
+function shouldUpdateSnapshots$2() {
+	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
+	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
+	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
+	return false;
+}
 /**
-* Implements {@link DockerContainerPort} by shelling out to the Docker CLI.
-* Each instance is bound to a single container ID.
+* Accessor for the whole temporary working directory used by a CLI spec.
+*
+* Generalization of {@link DirectoryAccessor} that snapshots the entire CLI
+* working directory into `<test-file-dir>/expected/filesystem/<name>/`.
 */
-var DockerAdapter = class {
-	containerId;
-	constructor(containerId) {
-		this.containerId = containerId;
+var FilesystemAccessor = class {
+	/** The absolute path of the temporary working directory. */
+	cwd;
+	testDir;
+	constructor(cwd, testDir) {
+		this.cwd = cwd;
+		this.testDir = testDir;
 	}
-	async exec(cmd) {
-		return execSync(`docker exec ${this.containerId} ${cmd.map((c) => `'${c}'`).join(" ")}`, {
-			encoding: "utf8",
-			timeout: 1e4
-		}).trim();
+	/** List all files (recursively) under the working directory, sorted. */
+	async files(options = {}) {
+		return walkDirectory(this.cwd, options);
 	}
-	async file(path) {
-		try {
-			return {
-				exists: true,
-				content: await this.exec(["cat", path])
-			};
-		} catch {
-			return {
-				exists: false,
-				content: ""
-			};
+	/**
+	* Assert the working directory matches a convention-based fixture tree:
+	* `<test-file-dir>/expected/filesystem/<name>/`.
+	*/
+	async toMatch(name, options = {}) {
+		const fixtureDir = resolve(this.testDir, "expected", "filesystem", name);
+		if (options.update ?? shouldUpdateSnapshots$2()) {
+			rmSync(fixtureDir, {
+				force: true,
+				recursive: true
+			});
+			mkdirSync(fixtureDir, { recursive: true });
+			cpSync(this.cwd, fixtureDir, { recursive: true });
+			return;
 		}
+		if (!existsSync(fixtureDir)) throw new Error(`Filesystem fixture "${name}" does not exist at ${fixtureDir}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
+		const diff = await diffDirectories(fixtureDir, this.cwd, { ignore: options.ignore });
+		if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) return;
+		throw new Error(formatDirectoryDiff(`filesystem/${name}`, diff, "Run with JTERRAZZ_TEST_UPDATE=1 to update the fixture."));
 	}
-	async isRunning() {
-		try {
-			return execSync(`docker inspect --format='{{.State.Running}}' ${this.containerId}`, {
-				encoding: "utf8",
-				timeout: 5e3
-			}).trim() === "true";
-		} catch {
-			return false;
-		}
+};
+//#endregion
+//#region src/spec/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/spec/result/json.ts
+function shouldUpdateSnapshots$1() {
+	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
+	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
+	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
+	return false;
+}
+function formatJson(value) {
+	return `${JSON.stringify(value, null, 4)}\n`;
+}
+/**
+* Accessor for a JSON payload parsed from a text stream (stdout).
+*
+* Lazily parses the JSON on first use; parse errors are deferred until an
+* assertion is performed so that callers can still read the raw stream text
+* without triggering a throw.
+*
+* When a `transform` is configured on the spec runner, it is applied to the
+* raw stdout text BEFORE `JSON.parse`. This lets consumers strip ANSI codes,
+* scrub machine-specific paths, etc. before structural comparison.
+*/
+var JsonAccessor = class {
+	rawText;
+	testDir;
+	transform;
+	constructor(rawText, testDir, transform) {
+		this.rawText = rawText;
+		this.testDir = testDir;
+		this.transform = transform;
 	}
-	async logs(tail) {
-		return execSync(`docker logs ${tail ? `--tail ${tail}` : ""} ${this.containerId}`, {
-			encoding: "utf8",
-			timeout: 1e4
-		});
+	/** The parsed JSON value. Throws if the text is not valid JSON. */
+	get value() {
+		return this.parse();
 	}
-	async inspect() {
-		const raw = execSync(`docker inspect ${this.containerId}`, {
-			encoding: "utf8",
-			timeout: 5e3
-		});
-		const data = JSON.parse(raw)[0];
-		return {
-			id: data.Id,
-			name: data.Name,
-			state: {
-				running: data.State.Running,
-				exitCode: data.State.ExitCode,
-				status: data.State.Status
-			},
-			config: {
-				image: data.Config.Image,
-				env: data.Config.Env || []
-			},
-			hostConfig: {
-				memory: data.HostConfig.Memory || 0,
-				cpuQuota: data.HostConfig.CpuQuota || 0,
-				networkMode: data.HostConfig.NetworkMode || "",
-				mounts: (data.Mounts || []).map((m) => ({
-					source: m.Source,
-					destination: m.Destination,
-					type: m.Type
-				}))
-			},
-			networkSettings: { networks: Object.fromEntries(Object.entries(data.NetworkSettings.Networks || {}).map(([name, net]) => [name, {
-				gateway: net.Gateway,
-				ipAddress: net.IPAddress
-			}])) }
-		};
+	/**
+	* Assert the parsed JSON deep-equals the JSON in the given file on disk.
+	*
+	* Path is resolved relative to the test file directory unless absolute.
+	* If `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`), the file is (re)written
+	* with the pretty-printed parsed value.
+	*/
+	toMatchFile(path, options = {}) {
+		const absPath = isAbsolute(path) ? path : resolve(this.testDir, path);
+		const update = options.update ?? shouldUpdateSnapshots$1();
+		const actual = this.parse();
+		if (update) {
+			mkdirSync(dirname(absPath), { recursive: true });
+			writeFileSync(absPath, formatJson(actual));
+			return;
+		}
+		if (!existsSync(absPath)) throw new Error(`JSON fixture "${path}" does not exist at ${absPath}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
+		const expected = JSON.parse(readFileSync(absPath, "utf8"));
+		if (JSON.stringify(expected) !== JSON.stringify(actual)) throw new Error(formatResponseDiff(path, expected, actual));
 	}
-	async exists(path) {
+	/**
+	* Assert the parsed JSON matches a convention-based fixture:
+	* `<test-file-dir>/expected/json/<name>`.
+	*
+	* The extension is part of the name and must be included by the caller —
+	* e.g. `toMatch('error.json')`, not `toMatch('error')`. Explicit extensions
+	* are clearer at the call site and remove magic from the resolution.
+	*/
+	toMatch(name, options = {}) {
+		const absPath = resolve(this.testDir, "expected", "json", name);
+		this.toMatchFile(absPath, options);
+	}
+	parse() {
+		const source = this.transform ? this.transform(this.rawText) : this.rawText;
 		try {
-			await this.exec([
-				"test",
-				"-e",
-				path
-			]);
-			return true;
+			return JSON.parse(source);
 		} catch {
-			return false;
+			const preview = source.slice(0, 200);
+			throw new Error(`stdout is not valid JSON: ${preview}`);
 		}
 	}
 };
-/** Create a {@link DockerContainerPort} bound to an existing container by ID. */
-function dockerContainer(containerId) {
-	return new DockerAdapter(containerId);
-}
 //#endregion
-//#region src/docker/docker-assertion.ts
+//#region src/spec/result/table.ts
+/** Assertion helper for verifying database table contents after a specification run. */
+var TableAssertion = class {
+	tableName;
+	db;
+	constructor(tableName, db) {
+		this.tableName = tableName;
+		this.db = db;
+	}
+	/**
+	* Assert that the table contains exactly the expected rows for the given columns.
+	*
+	* @example
+	*   await result.table("users").toMatch({
+	*     columns: ["name", "email"],
+	*     rows: [["Alice", "alice@example.com"]],
+	*   });
+	*/
+	async toMatch(expected) {
+		const actual = await this.db.query(this.tableName, expected.columns);
+		if (JSON.stringify(actual) !== JSON.stringify(expected.rows)) throw new Error(formatTableDiff(this.tableName, expected.columns, expected.rows, actual));
+	}
+	/** Assert that the table has zero rows. */
+	async toBeEmpty() {
+		const actual = await this.db.query(this.tableName, ["*"]);
+		if (actual.length !== 0) throw new Error(`Expected table "${this.tableName}" to be empty, but it has ${actual.length} rows`);
+	}
+};
+//#endregion
+//#region src/spec/result/result.ts
 /**
-* Fluent assertion builder for Docker containers.
-* Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
+* Base result - common accessors available after any action type.
+* Extended by HttpResult, CliResult, and used directly by JobResult.
 */
-var DockerAssertion = class {
-	container;
-	constructor(container) {
-		this.container = container;
+var BaseResult = class {
+	config;
+	testDir;
+	workDir;
+	constructor(options) {
+		this.config = options.config;
+		this.testDir = options.testDir;
+		this.workDir = options.workDir;
 	}
-	/** Assert the container is running */
-	async toBeRunning() {
-		if (!await this.container.isRunning()) throw new Error("Expected container to be running");
-		return this;
+	/** Access a directory (relative to the working directory) for snapshot assertions. */
+	directory(path = ".") {
+		return new DirectoryAccessor(resolve(this.workDir ?? this.testDir, path), this.testDir);
 	}
-	/** Assert the container is NOT running / doesn't exist */
-	async toNotExist() {
-		if (await this.container.isRunning()) throw new Error("Expected container to not exist or not be running");
-		return this;
+	/** 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);
+		return {
+			get content() {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return readFileSync(resolvedPath, "utf8");
+			},
+			exists
+		};
 	}
-	/** Assert a file exists inside the container */
-	async toHaveFile(path, opts) {
-		const file = await this.container.file(path);
-		if (!file.exists) throw new Error(`Expected file ${path} to exist in container`);
-		if (opts?.containing && !file.content.includes(opts.containing)) throw new Error(`Expected file ${path} to contain "${opts.containing}", got: ${file.content.slice(0, 200)}`);
-		return this;
+	/** Access a database table for row-level assertions. */
+	table(tableName, options) {
+		const db = this.resolveDatabase(options?.service);
+		if (!db) throw new Error(options?.service ? `table("${tableName}") requires database "${options.service}" but it was not found` : `table("${tableName}") requires a database adapter`);
+		return new TableAssertion(tableName, db);
 	}
-	/** Assert a file does NOT exist */
-	async toNotHaveFile(path) {
-		if (await this.container.exists(path)) throw new Error(`Expected ${path} to not exist in container`);
-		return this;
+	resolveDatabase(serviceName) {
+		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
+		return this.config.database;
 	}
-	/** Assert a directory exists */
-	async toHaveDirectory(path) {
-		if (!await this.container.exists(path)) throw new Error(`Expected directory ${path} to exist in container`);
-		return this;
+};
+//#endregion
+//#region src/spec/result/stream.ts
+function shouldUpdateSnapshots() {
+	if (process.env.JTERRAZZ_TEST_UPDATE === "1") return true;
+	if (process.env.UPDATE_SNAPSHOTS === "1") return true;
+	if (process.argv.includes("-u") || process.argv.includes("--update")) return true;
+	return false;
+}
+/**
+* Accessor for a captured text stream (stdout/stderr) with file-based
+* assertion support.
+*
+* 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.
+*/
+var StreamAccessor = class {
+	streamName;
+	testDir;
+	transform;
+	text;
+	constructor(text, streamName, testDir, transform) {
+		this.text = text;
+		this.streamName = streamName;
+		this.testDir = testDir;
+		this.transform = transform;
 	}
-	/** Assert a mount exists */
-	async toHaveMount(destination) {
-		const info = await this.container.inspect();
-		if (!info.hostConfig.mounts.find((m) => m.destination === destination)) {
-			const available = info.hostConfig.mounts.map((m) => m.destination).join(", ");
-			throw new Error(`Expected mount at ${destination}, found: [${available}]`);
+	/**
+	* Assert the captured text matches the given file on disk.
+	*
+	* Path is resolved relative to the test file directory unless absolute.
+	* If `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`), the file is (re)written
+	* with the actual text.
+	*
+	* When a `transform` is configured on the spec runner, it is applied to
+	* the actual text before comparison (and before writing in update mode).
+	* The fixture file is treated as authoritative and is NOT transformed.
+	*/
+	toMatchFile(path, options = {}) {
+		const absPath = isAbsolute(path) ? path : resolve(this.testDir, path);
+		const update = options.update ?? shouldUpdateSnapshots();
+		const actual = this.transform ? this.transform(this.text) : this.text;
+		if (update) {
+			mkdirSync(dirname(absPath), { recursive: true });
+			writeFileSync(absPath, actual);
+			return;
 		}
-		return this;
-	}
-	/** Assert network mode */
-	async toHaveNetwork(mode) {
-		const info = await this.container.inspect();
-		if (!info.hostConfig.networkMode.includes(mode)) throw new Error(`Expected network mode "${mode}", got "${info.hostConfig.networkMode}"`);
-		return this;
-	}
-	/** Assert memory limit */
-	async toHaveMemoryLimit(bytes) {
-		const info = await this.container.inspect();
-		if (info.hostConfig.memory !== bytes) throw new Error(`Expected memory limit ${bytes}, got ${info.hostConfig.memory}`);
-		return this;
+		if (!existsSync(absPath)) throw new Error(`${this.streamName} fixture "${path}" does not exist at ${absPath}.\nRun with JTERRAZZ_TEST_UPDATE=1 (or vitest -u) to create it.`);
+		const expected = readFileSync(absPath, "utf8");
+		if (expected !== actual) throw new Error(formatStdoutDiff(path, expected, actual));
 	}
-	/** Assert CPU quota */
-	async toHaveCpuQuota(quota) {
-		const info = await this.container.inspect();
-		if (info.hostConfig.cpuQuota !== quota) throw new Error(`Expected CPU quota ${quota}, got ${info.hostConfig.cpuQuota}`);
-		return this;
+	/**
+	* Assert the captured text matches a convention-based fixture:
+	* `<test-file-dir>/expected/<stream>/<name>`.
+	*
+	* The extension is part of the name and must be included by the caller —
+	* e.g. `toMatch('valid.txt')`, not `toMatch('valid')`. Explicit extensions
+	* are clearer at the call site and remove magic from the resolution.
+	*/
+	toMatch(name, options = {}) {
+		const absPath = resolve(this.testDir, "expected", this.streamName, name);
+		this.toMatchFile(absPath, options);
 	}
-	/** Execute a command and return output for custom assertions */
-	async exec(cmd) {
-		return this.container.exec(cmd);
+	/**
+	* Assert the captured text contains the given substring. The runner's
+	* `transform` (if any) is applied before the check so callers can rely
+	* on the same normalised view as {@link toMatch}.
+	*
+	* Throws with a tight diff-style error on miss so tests read uniformly
+	* with the other accessor assertions (no reaching through `.text` into
+	* `expect(...).toContain(...)`).
+	*/
+	toContain(substring) {
+		const actual = this.transform ? this.transform(this.text) : this.text;
+		if (actual.includes(substring)) return;
+		throw new Error(`${this.streamName} does not contain expected substring.\n  expected to contain: ${JSON.stringify(substring)}\n  actual: ${JSON.stringify(actual.length > 500 ? `${actual.slice(0, 500)}…` : actual)}`);
 	}
-	/** Read a file for custom assertions */
-	async readFile(path) {
-		const file = await this.container.file(path);
-		if (!file.exists) throw new Error(`File ${path} does not exist`);
-		return file.content;
+	toString() {
+		return this.text;
 	}
-	/** Get logs for custom assertions */
-	async getLogs(tail) {
-		return this.container.logs(tail);
+	valueOf() {
+		return this.text;
 	}
 };
 //#endregion
-//#region src/infra/adapters/compose.adapter.ts
+//#region src/spec/modes/cli/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")
+	};
+}
 /**
-* Start the full compose stack and stop it all on cleanup.
-* Supports per-worker project names for parallel execution.
+* 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 ComposeStackAdapter = class {
-	composeFile;
-	projectName;
-	started = false;
-	constructor(composeFile, projectName) {
-		this.composeFile = composeFile;
-		this.projectName = projectName ?? null;
-	}
-	get projectFlag() {
-		return this.projectName ? `-p ${this.projectName}` : "";
+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;
 	}
-	run(command) {
-		try {
-			return execSync(command, {
-				cwd: dirname(this.composeFile),
-				encoding: "utf8",
-				timeout: 12e4
-			}).trim();
-		} catch (error) {
-			const stderr = error.stderr?.toString().trim() ?? error.message;
-			throw new Error(`docker compose failed: ${stderr}`, { cause: error });
+	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";
 		}
 	}
-	async start() {
-		if (this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} up -d --wait`);
-		this.started = true;
+	/**
+	* 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);
 	}
-	async stop() {
-		if (!this.started) return;
-		this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} down -v`);
-		this.started = false;
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stdout() {
+		this.requireExists("stdout");
+		return new StreamAccessor(this.loadLogs(), "stdout", this.testDir, this.transform);
 	}
-	getMappedPort(serviceName, containerPort) {
-		const port = this.run(`docker compose ${this.projectFlag} -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
-		return Number(port);
+	/** Captured logs (stdout+stderr combined for v1). */
+	get stderr() {
+		this.requireExists("stderr");
+		return new StreamAccessor(this.loadLogs(), "stderr", this.testDir, this.transform);
 	}
-	getHost() {
-		return "localhost";
+	/**
+	* 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;
+		return {
+			get content() {
+				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
+				});
+			},
+			exists
+		};
 	}
-};
-//#endregion
-//#region src/infra/adapters/testcontainers.adapter.ts
-/**
-* Container adapter using testcontainers.
-* Wraps a GenericContainer for programmatic container lifecycle.
-*/
-var TestcontainersAdapter = class {
-	image;
-	containerPort;
-	env;
-	reuse;
-	container = null;
-	constructor(options) {
-		this.image = options.image;
-		this.containerPort = options.port;
-		this.env = options.env ?? {};
-		this.reuse = options.reuse ?? false;
+	/**
+	* 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({
+			commandResult: this.containerExec(this.containerId, [
+				"sh",
+				"-c",
+				cmd
+			]),
+			config: {},
+			testDir: this.testDir,
+			transform: this.transform,
+			workDir: this.testDir
+		});
 	}
-	async start() {
-		const { GenericContainer, Wait } = await import("testcontainers");
-		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort);
-		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
-		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/, 2));
-		if (this.reuse) builder = builder.withReuse();
-		this.container = await builder.start();
+	requireExists(member) {
+		if (!this.exists) throw new Error(`ContainerAccessor.${member}: container does not exist (check .exists first)`);
 	}
-	async stop() {
-		if (this.container && !this.reuse) {
-			await this.container.stop();
-			this.container = null;
+	loadLogs() {
+		if (this.cachedLogs !== null) return this.cachedLogs;
+		try {
+			this.cachedLogs = execSync(`docker logs ${this.containerId}`, {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				timeout: EXEC_TIMEOUT
+			});
+		} catch (error) {
+			this.cachedLogs = typeof error?.stdout === "string" ? error.stdout : String(error?.stderr ?? "");
 		}
+		return this.cachedLogs ?? "";
 	}
-	getMappedPort(containerPort) {
-		if (!this.container) throw new Error("Container not started");
-		return this.container.getMappedPort(containerPort);
-	}
-	getHost() {
-		if (!this.container) throw new Error("Container not started");
-		return this.container.getHost();
-	}
-	getConnectionString() {
-		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
-	}
-	async getLogs() {
-		if (!this.container) return "";
-		const stream = await this.container.logs();
-		return new Promise((resolve) => {
-			let output = "";
-			stream.on("data", (chunk) => {
-				output += chunk.toString();
-			});
-			stream.on("end", () => {
-				resolve(output);
-			});
-			setTimeout(() => {
-				resolve(output);
-			}, 1e3);
-		});
+	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/infra/compose-parser.ts
-/**
-* Detect the service type from the image name.
-*/
-function detectServiceType(image) {
-	if (!image) return "app";
-	const lower = image.toLowerCase();
-	if (lower.startsWith("postgres")) return "postgres";
-	if (lower.startsWith("redis")) return "redis";
-	return "unknown";
-}
+//#region src/spec/modes/cli/docker-lookup.ts
 /**
-* Find the compose file in the project.
-* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
+* 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).
 */
-function findComposeFile(projectRoot) {
-	const candidates = [
-		resolve(projectRoot, "docker/compose.test.yaml"),
-		resolve(projectRoot, "docker/compose.test.yml"),
-		resolve(projectRoot, "docker-compose.test.yaml"),
-		resolve(projectRoot, "docker-compose.test.yml")
-	];
-	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
-	return null;
+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 [];
+	}
 }
-/**
-* Parse a docker-compose file and extract service definitions.
-*/
-function parseComposeFile(filePath) {
-	const doc = parse(readFileSync(filePath, "utf8"));
-	if (!doc?.services) return {
-		services: [],
-		appService: null,
-		infraServices: []
-	};
-	const services = Object.entries(doc.services).map(([name, def]) => {
-		const ports = [];
-		if (def.ports) for (const port of def.ports) {
-			const str = String(port);
-			if (str.includes(":")) {
-				const [host, container] = str.split(":");
-				ports.push({
-					container: Number(container),
-					host: Number(host)
-				});
-			} else ports.push({ container: Number(str) });
-		}
-		const environment = {};
-		if (def.environment) if (Array.isArray(def.environment)) for (const env of def.environment) {
-			const [key, ...rest] = String(env).split("=");
-			environment[key] = rest.join("=");
-		}
-		else Object.assign(environment, def.environment);
-		const volumes = def.volumes ? def.volumes.map((v) => String(v)) : [];
-		let dependsOn = [];
-		if (def.depends_on) dependsOn = Array.isArray(def.depends_on) ? def.depends_on : Object.keys(def.depends_on);
-		return {
-			name,
-			image: def.image,
-			build: def.build,
-			ports,
-			environment,
-			volumes,
-			dependsOn
-		};
+/** 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
 	});
-	return {
-		services,
-		appService: services.find((s) => s.build !== void 0) ?? null,
-		infraServices: services.filter((s) => s.build === void 0)
-	};
+	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/infra/orchestrator.ts
+//#region src/spec/modes/cli/result.ts
 /**
-* Orchestrator for test infrastructure.
-* Integration: starts services via testcontainers.
-* E2E: runs full docker compose up.
+* Result from a CLI action (.exec(), .spawn()).
+*
+* 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 CLI-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 Orchestrator = class {
-	services;
-	mode;
-	root;
-	projectName;
-	running = [];
-	composeStack = null;
-	composeHandles = [];
-	started = false;
+var CliResult = class extends BaseResult {
+	commandResult;
+	containersCache = null;
+	dockerConfig;
+	testRunId;
+	transform;
 	constructor(options) {
-		this.services = options.services;
-		this.mode = options.mode;
-		this.root = options.root ?? process.cwd();
-		this.projectName = options.projectName;
+		super(options);
+		this.commandResult = options.commandResult;
+		this.dockerConfig = options.dockerConfig;
+		this.testRunId = options.testRunId;
+		this.transform = options.transform;
+	}
+	/** The process exit code. */
+	get exitCode() {
+		return this.commandResult.exitCode;
+	}
+	/** Accessor for the captured standard output with file-based assertions. */
+	get stdout() {
+		return new StreamAccessor(this.commandResult.stdout, "stdout", this.testDir, this.transform);
+	}
+	/** Accessor for the captured standard error with file-based assertions. */
+	get stderr() {
+		return new StreamAccessor(this.commandResult.stderr, "stderr", this.testDir, this.transform);
+	}
+	/** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+	get json() {
+		return new JsonAccessor(this.commandResult.stdout, this.testDir, this.transform);
+	}
+	/** 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);
 	}
 	/**
-	* Start declared services via testcontainers (integration mode).
-	* Phase 1: start all containers in parallel (the slow part).
-	* Phase 2: wire connections, healthcheck, and init sequentially (fast).
+	* Look up a container the CLI spawned during this run by the value of
+	* its name-label (as declared in `SpecOptions.docker.nameLabel`).
+	* 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.
 	*/
-	async start() {
-		if (this.started) return;
-		const composePath = findComposeFile(this.root);
-		const composeDir = composePath ? dirname(composePath) : this.root;
-		const composeConfig = composePath ? parseComposeFile(composePath) : null;
-		const containerServices = [];
-		const embeddedServices = [];
-		for (const handle of this.services) {
-			if (handle.defaultPort === 0) {
-				embeddedServices.push(handle);
+	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));
+	}
+	/**
+	* Extract text blocks from stdout that contain a pattern.
+	*
+	* @example
+	*   expect(result.grep('error.ts')).toContain('no-unused-vars');
+	*/
+	grep(pattern) {
+		return grep(this.commandResult.stdout, pattern);
+	}
+	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 SpecOptions.`);
+	}
+	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;
 			}
-			let image = handle.defaultImage;
-			let env = { ...handle.environment };
-			if (handle.composeName && composeConfig) {
-				const composeService = composeConfig.services.find((s) => s.name === handle.composeName);
-				if (composeService) {
-					image = composeService.image ?? image;
-					env = {
-						...env,
-						...composeService.environment
-					};
-					Object.assign(handle.environment, composeService.environment);
-				}
-			}
-			const container = new TestcontainersAdapter({
-				image,
-				port: handle.defaultPort,
-				env
-			});
-			containerServices.push({
-				container,
-				handle
+			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
 			});
 		}
-		await Promise.all([...containerServices.map(({ container }) => container.start()), ...embeddedServices.map(async (handle) => {
-			await handle.initialize(composeDir);
-			handle.started = true;
-			this.running.push({
-				handle,
-				container: null
+		this.containersCache = map;
+	}
+};
+//#endregion
+//#region src/spec/result/response.ts
+/** Accessor for an HTTP response body with file-based assertion support. */
+var ResponseAccessor = class {
+	body;
+	testDir;
+	constructor(body, testDir) {
+		this.body = body;
+		this.testDir = testDir;
+	}
+	/**
+	* Assert that the response body matches the JSON in `responses/{file}`.
+	*
+	* @example
+	*   result.response.toMatchFile("expected-items.json");
+	*/
+	toMatchFile(file) {
+		const expected = JSON.parse(readFileSync(resolve(this.testDir, "responses", file), "utf8"));
+		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
+	}
+};
+//#endregion
+//#region src/spec/modes/http/result.ts
+/** Result from an HTTP action (.get(), .post(), .put(), .delete()). */
+var HttpResult = class extends BaseResult {
+	responseData;
+	constructor(options) {
+		super(options);
+		this.responseData = options.response;
+	}
+	/** The HTTP response status code. */
+	get status() {
+		return this.responseData.status;
+	}
+	/** Access the HTTP response body for assertions. */
+	get response() {
+		return new ResponseAccessor(this.responseData.body, this.testDir);
+	}
+};
+//#endregion
+//#region src/spec/builder.ts
+/**
+* Fluent builder for declaring a single test specification.
+*
+* Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
+* ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
+* and receive a {@link SpecificationResult} for assertions.
+*/
+var SpecificationBuilder = class {
+	commandArgs = null;
+	commandEnv = {};
+	config;
+	fixtures = [];
+	intercepts = [];
+	jobName = null;
+	label;
+	mocks = [];
+	projectName = null;
+	request = null;
+	requestHeaders = {};
+	seeds = [];
+	spawnConfig = null;
+	testDir;
+	constructor(config, testDir, label) {
+		this.config = config;
+		this.testDir = testDir;
+		this.label = label;
+	}
+	/**
+	* Queue a SQL seed file to run before the action.
+	*
+	* @example
+	*   spec("creates user").seed("users.sql").exec("list-users").run();
+	*/
+	seed(file, options) {
+		this.seeds.push({
+			file,
+			service: options?.service
+		});
+		return this;
+	}
+	/** Copy a file or directory from `fixtures/` into the working directory before execution. */
+	fixture(file) {
+		this.fixtures.push({ file });
+		return this;
+	}
+	/** Copy an entire project fixture from `fixturesRoot` into the working directory. */
+	project(name) {
+		this.projectName = name;
+		return this;
+	}
+	/** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
+	mock(file) {
+		this.mocks.push({ file });
+		return this;
+	}
+	/**
+	* Set environment variables for the CLI process. Merged on top of process.env.
+	* Use `null` to unset a variable. Multiple calls merge.
+	*
+	* The token `$WORKDIR` (in any value) is replaced with the actual working
+	* directory at run-time — useful for tests that need a fully isolated `HOME`.
+	*
+	* @example
+	*   spec("...").env({ HOME: "$WORKDIR", TZ: "UTC" }).exec("status").run();
+	*/
+	env(env) {
+		this.commandEnv = {
+			...this.commandEnv,
+			...env
+		};
+		return this;
+	}
+	/**
+	* Set HTTP headers for the request. Multiple calls merge.
+	*
+	* @example
+	*   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
+	*/
+	headers(headers) {
+		this.requestHeaders = {
+			...this.requestHeaders,
+			...headers
+		};
+		return this;
+	}
+	/**
+	* Intercept an outgoing HTTP request and return a controlled response.
+	* Uses MSW under the hood. Intercepts are queued — multiple calls with the
+	* same trigger fire sequentially (first match consumed first).
+	*
+	* @param trigger - What to match (use openai.agent(), http.get(), etc.)
+	* @param response - What to return: an InterceptResponse object, or a filename
+	*   from `intercepts/` (JSON loaded and auto-wrapped by the trigger).
+	*
+	* @example
+	*   // With inline response
+	*   .intercept(openai.agent({...}), openai.reply({ categories: ['TECH'] }))
+	*
+	*   // With JSON fixture file (loaded from intercepts/ directory)
+	*   .intercept(openai.agent({...}), 'ingest-tech.json')
+	*   .intercept(http.get(url), 'world-news-tech.json')
+	*/
+	intercept(trigger, response) {
+		if (typeof response === "string") {
+			const slashIndex = response.indexOf("/");
+			if (slashIndex === -1) throw new Error(`.intercept(): file path must be 'adapter/filename.json' (e.g. 'openai/ingest-tech.json'), got '${response}'`);
+			const adapterName = response.slice(0, slashIndex);
+			if (adapterName !== trigger.adapter) throw new Error(`.intercept(): adapter mismatch - trigger uses '${trigger.adapter}' but file path starts with '${adapterName}/'`);
+			const filePath = resolve(this.testDir, "intercepts", response);
+			const data = JSON.parse(readFileSync(filePath, "utf8"));
+			const resolved = trigger.wrap(data);
+			this.intercepts.push({
+				trigger,
+				response: resolved
 			});
-		})]);
-		const reports = [];
-		for (const { container, handle } of containerServices) {
-			const serviceStartTime = Date.now();
-			try {
-				const host = container.getHost();
-				const port = container.getMappedPort(handle.defaultPort);
-				handle.connectionString = handle.buildConnectionString(host, port);
-				await handle.healthcheck();
-				await handle.initialize(composeDir);
-				handle.started = true;
-				reports.push({
-					name: handle.composeName ?? handle.type,
-					type: handle.type,
-					connectionString: handle.connectionString,
-					durationMs: Date.now() - serviceStartTime
-				});
-				this.running.push({
-					handle,
-					container
-				});
-			} catch (error) {
-				let logs = "";
-				try {
-					logs = await container.getLogs();
-				} catch {}
-				try {
-					await container.stop();
-				} catch {}
-				reports.push({
-					name: handle.composeName ?? handle.type,
-					type: handle.type,
-					durationMs: Date.now() - serviceStartTime,
-					error: error.message,
-					logs
-				});
-				const output = formatStartupReport("integration", reports, { type: "in-process" });
-				console.error(output);
-				throw error;
-			}
-		}
-		this.started = true;
-		const output = formatStartupReport("integration", reports, { type: "in-process" });
-		console.log(output);
+		} else this.intercepts.push({
+			trigger,
+			response
+		});
+		return this;
 	}
 	/**
-	* Stop testcontainers (integration mode).
+	* Send a GET request to the server adapter.
+	*
+	* @example
+	*   spec("list items").get("/api/items").run();
 	*/
-	async stop() {
-		for (const { container } of this.running) if (container) await container.stop();
-		this.running = [];
-		this.started = false;
+	get(path) {
+		this.request = {
+			method: "GET",
+			path
+		};
+		return this;
+	}
+	/**
+	* Send a POST request to the server adapter.
+	*
+	* @param bodyFile - Optional JSON file from `requests/` to use as the request body.
+	* @example
+	*   spec("create item").post("/api/items", "new-item.json").run();
+	*/
+	post(path, bodyFile) {
+		this.request = {
+			bodyFile,
+			method: "POST",
+			path
+		};
+		return this;
+	}
+	/** Send a PUT request to the server adapter. */
+	put(path, bodyFile) {
+		this.request = {
+			bodyFile,
+			method: "PUT",
+			path
+		};
+		return this;
+	}
+	/** Send a DELETE request to the server adapter. */
+	delete(path) {
+		this.request = {
+			method: "DELETE",
+			path
+		};
+		return this;
+	}
+	/**
+	* Execute a CLI command (or a sequence of commands) in an isolated working directory.
+	* When an array is passed, commands run sequentially and stop on the first non-zero exit code.
+	*
+	* @example
+	*   spec("init project").exec("init --name demo").run();
+	*   spec("multi-step").exec(["init", "build"]).run();
+	*/
+	exec(args) {
+		this.commandArgs = args;
+		return this;
+	}
+	/** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
+	spawn(args, options) {
+		this.spawnConfig = {
+			args,
+			options
+		};
+		return this;
+	}
+	/**
+	* Execute a named job registered via the app() factory.
+	*
+	* @param name - The job name to trigger (must match a registered JobHandle.name).
+	*
+	* @example
+	*   spec('pipeline').intercept(openai.chat(), openai.response({...})).job('report-refresh').run();
+	*/
+	job(name) {
+		this.jobName = name;
+		return this;
+	}
+	/**
+	* Execute the specification: run seeds, copy fixtures, then perform the
+	* configured action (HTTP or CLI).
+	*
+	* @returns The result object used for assertions.
+	* @example
+	*   const result = await spec("test").exec("status").run();
+	*   expect(result.exitCode).toBe(0);
+	*/
+	async run() {
+		const hasHttpAction = this.request !== null;
+		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
+		const hasJobAction = this.jobName !== null;
+		const actionCount = [
+			hasHttpAction,
+			hasCliAction,
+			hasJobAction
+		].filter(Boolean).length;
+		if (actionCount === 0) throw new Error(`Specification "${this.label}": no action defined. Call .get(), .post(), .exec(), .job(), etc. before .run()`);
+		if (actionCount > 1) throw new Error(`Specification "${this.label}": cannot mix action types (.get/.post, .exec/.spawn, .job)`);
+		let workDir = null;
+		if (hasCliAction) workDir = this.prepareWorkDir();
+		if (this.config.databases) for (const db of this.config.databases.values()) await db.reset();
+		else if (this.config.database) await this.config.database.reset();
+		for (const entry of this.seeds) {
+			const handler = this.resolveSeedHandler(entry.file);
+			if (handler) {
+				if (!workDir) throw new Error(`seed("${entry.file}"): pluggable seed handlers require a CLI working directory`);
+				const fragmentPath = resolve(this.testDir, "seeds", entry.file);
+				await handler({
+					cwd: workDir,
+					testDir: this.testDir
+				}, fragmentPath);
+				continue;
+			}
+			let db;
+			if (entry.service && this.config.databases) {
+				db = this.config.databases.get(entry.service);
+				if (!db) throw new Error(`seed() targets database "${entry.service}" but it was not found. Available: ${[...this.config.databases.keys()].join(", ")}`);
+			} else db = this.config.database;
+			if (!db) throw new Error("seed() requires a database adapter");
+			const sql = readFileSync(resolve(this.testDir, "seeds", entry.file), "utf8");
+			await db.seed(sql);
+		}
+		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) cpSync(resolve(this.testDir, "fixtures", entry.file), resolve(workDir, entry.file), { recursive: true });
+		let cleanupIntercepts = null;
+		if (this.intercepts.length > 0) {
+			const { registerIntercepts } = await import("./intercept2.js");
+			cleanupIntercepts = await registerIntercepts(this.intercepts);
+		}
+		try {
+			if (hasHttpAction) return await this.runHttpAction();
+			if (hasJobAction) return await this.runJobAction();
+			return await this.runCliAction(workDir);
+		} finally {
+			if (cleanupIntercepts) cleanupIntercepts();
+		}
+	}
+	resolveSeedHandler(file) {
+		const handlers = this.config.seedHandlers;
+		if (!handlers) return;
+		const normalized = file.replaceAll("\\", "/");
+		let bestKey;
+		for (const key of Object.keys(handlers)) {
+			const prefix = key.endsWith("/") ? key : `${key}/`;
+			if (normalized === key || normalized.startsWith(prefix)) {
+				if (!bestKey || key.length > bestKey.length) bestKey = key;
+			}
+		}
+		return bestKey ? handlers[bestKey] : void 0;
+	}
+	resolveEnv(workDir) {
+		const keys = Object.keys(this.commandEnv);
+		if (keys.length === 0) return;
+		const resolved = {};
+		for (const key of keys) {
+			const value = this.commandEnv[key];
+			resolved[key] = typeof value === "string" ? value.replace(/\$WORKDIR/g, workDir) : value;
+		}
+		return resolved;
+	}
+	prepareWorkDir() {
+		const tempDir = mkdtempSync(resolve(tmpdir(), "spec-cli-"));
+		if (this.projectName && this.config.fixturesRoot) {
+			const projectDir = resolve(this.config.fixturesRoot, this.projectName);
+			if (!existsSync(projectDir)) throw new Error(`project("${this.projectName}"): fixture project not found at ${projectDir}`);
+			cpSync(projectDir, tempDir, { recursive: true });
+		}
+		return tempDir;
+	}
+	async runHttpAction() {
+		if (!this.config.server) throw new Error("HTTP actions require a server adapter (use integration() or e2e())");
+		let body;
+		if (this.request.bodyFile) body = JSON.parse(readFileSync(resolve(this.testDir, "requests", this.request.bodyFile), "utf8"));
+		const headers = Object.keys(this.requestHeaders).length > 0 ? this.requestHeaders : void 0;
+		const response = await this.config.server.request(this.request.method, this.request.path, body, headers);
+		return new HttpResult({
+			config: this.config,
+			response,
+			testDir: this.testDir
+		});
+	}
+	async runJobAction() {
+		if (!this.config.jobs?.length) throw new Error("Job actions require jobs registered via app(() => ({ server, jobs }))");
+		const job = this.config.jobs.find((j) => j.name === this.jobName);
+		if (!job) {
+			const available = this.config.jobs.map((j) => j.name).join(", ");
+			throw new Error(`job("${this.jobName}"): not found. Available: ${available}`);
+		}
+		await job.execute();
+		return new BaseResult({
+			config: this.config,
+			testDir: this.testDir
+		});
+	}
+	async runCliAction(workDir) {
+		if (!this.config.command) throw new Error("CLI actions require a command adapter (use cli())");
+		const dockerConfig = this.config.dockerConfig;
+		const testRunId = this.config.dockerTestRunId;
+		let env = this.resolveEnv(workDir);
+		if (dockerConfig && testRunId) env = {
+			[dockerConfig.envVar]: testRunId,
+			...env
+		};
+		let commandResult;
+		if (this.spawnConfig) commandResult = await this.config.command.spawn(this.spawnConfig.args, workDir, this.spawnConfig.options, env);
+		else if (Array.isArray(this.commandArgs)) {
+			commandResult = {
+				exitCode: 0,
+				stderr: "",
+				stdout: ""
+			};
+			for (const args of this.commandArgs) {
+				commandResult = await this.config.command.exec(args, workDir, env);
+				if (commandResult.exitCode !== 0) break;
+			}
+		} else commandResult = await this.config.command.exec(this.commandArgs, workDir, env);
+		return new CliResult({
+			commandResult,
+			config: this.config,
+			dockerConfig: dockerConfig ?? void 0,
+			testDir: this.testDir,
+			testRunId: testRunId ?? void 0,
+			transform: this.config.transform,
+			workDir
+		});
+	}
+};
+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:\/\/)?([^:)]+):\d+:\d+/);
+		if (!match) continue;
+		const filePath = match[1];
+		if (filePath.includes("node_modules")) continue;
+		if (filePath.includes("/src/builder/") || filePath.includes("/src/spec/")) continue;
+		return resolve(filePath, "..");
+	}
+	throw new Error("Cannot detect caller directory from stack trace");
+}
+/**
+* Create a {@link SpecificationRunner} bound to the given adapter configuration.
+* The test file directory is auto-detected from the call stack.
+*/
+function createSpecificationRunner(config) {
+	const resolved = config.dockerConfig && !config.dockerTestRunId ? {
+		...config,
+		dockerTestRunId: `t-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`
+	} : config;
+	return (label) => {
+		return new SpecificationBuilder(resolved, getCallerDir(), label);
+	};
+}
+//#endregion
+//#region src/spec/modes/cli/adapters/exec.adapter.ts
+/**
+* Build a child-process env from the parent env plus user overrides.
+* `null` overrides delete keys (e.g. `INIT_CWD: null`).
+*/
+function buildEnv(extra) {
+	const env = {
+		...process.env,
+		INIT_CWD: void 0
+	};
+	if (extra) for (const [key, value] of Object.entries(extra)) if (value === null) delete env[key];
+	else env[key] = value;
+	return env;
+}
+/**
+* Executes CLI commands via Node.js child_process.
+* Uses `spawnSync` for one-shot commands and `spawn` for long-running processes.
+* Used by the command() specification runner.
+*
+* `spawnSync` is used (over the simpler `execSync`) so stdout AND stderr are
+* captured regardless of exit code. Many CLIs follow the Unix convention of
+* writing status banners to stderr on success — `execSync` would silently
+* discard them, leaving snapshot tests with no output to assert on.
+*/
+var ExecAdapter = class {
+	command;
+	constructor(command) {
+		this.command = command;
 	}
-	/**
-	* Start full docker compose stack (e2e mode).
-	* Auto-detects infra services and creates handles for them.
-	*/
-	async startCompose() {
-		const composePath = findComposeFile(this.root);
-		if (!composePath) throw new Error(`E2E: no compose file found in ${this.root}`);
-		const startTime = Date.now();
-		const composeDir = dirname(composePath);
-		const composeConfig = parseComposeFile(composePath);
-		this.composeStack = new ComposeStackAdapter(composePath, this.projectName);
-		await this.composeStack.start();
-		for (const service of composeConfig.infraServices) {
-			const type = detectServiceType(service.image);
-			if (type === "postgres") {
-				const handle = postgres({
-					compose: service.name,
-					env: service.environment
+	async exec(args, cwd, extraEnv) {
+		const env = buildEnv(extraEnv);
+		const result = spawnSync(`${this.command} ${args}`, [], {
+			cwd,
+			encoding: "utf8",
+			env,
+			shell: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		return {
+			exitCode: result.status ?? 1,
+			stdout: result.stdout ?? "",
+			stderr: result.stderr ?? ""
+		};
+	}
+	async spawn(args, cwd, options, extraEnv) {
+		const env = buildEnv(extraEnv);
+		return new Promise((resolve) => {
+			let stdout = "";
+			let stderr = "";
+			let resolved = false;
+			const child = spawn(this.command, args.split(/\s+/).filter(Boolean), {
+				cwd,
+				env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+			const finish = (exitCode) => {
+				if (resolved) return;
+				resolved = true;
+				child.kill("SIGTERM");
+				resolve({
+					exitCode,
+					stdout,
+					stderr
 				});
-				const port = this.composeStack.getMappedPort(service.name, 5432);
-				handle.connectionString = handle.buildConnectionString("localhost", port);
-				await handle.initialize(composeDir);
-				handle.started = true;
-				this.composeHandles.push(handle);
-			} else if (type === "redis") {
-				const handle = redis({ compose: service.name });
-				const port = this.composeStack.getMappedPort(service.name, 6379);
-				handle.connectionString = handle.buildConnectionString("localhost", port);
-				handle.started = true;
-				this.composeHandles.push(handle);
-			}
-		}
-		const durationMs = Date.now() - startTime;
-		const output = formatStartupReport("e2e", this.composeHandles.map((h) => ({
-			name: h.composeName ?? h.type,
-			type: h.type,
-			connectionString: h.connectionString,
-			durationMs
-		})), {
-			type: "http",
-			url: this.getAppUrl() ?? void 0
+			};
+			let patternMatched = false;
+			const checkPattern = () => {
+				if (!patternMatched && (stdout.includes(options.waitFor) || stderr.includes(options.waitFor))) {
+					patternMatched = true;
+					finish(0);
+				}
+			};
+			child.stdout?.on("data", (data) => {
+				stdout += data.toString();
+				checkPattern();
+			});
+			child.stderr?.on("data", (data) => {
+				stderr += data.toString();
+				checkPattern();
+			});
+			child.on("exit", (code) => {
+				if (!patternMatched) finish(code === 0 ? 1 : code ?? 1);
+			});
+			setTimeout(() => finish(124), options.timeout);
 		});
-		console.log(output);
 	}
-	/**
-	* Stop docker compose stack (e2e mode).
-	*/
-	async stopCompose() {
-		if (this.composeStack) {
-			await this.composeStack.stop();
-			this.composeStack = null;
-		}
-		this.composeHandles = [];
+};
+//#endregion
+//#region src/spec/modes/http/adapters/fetch.adapter.ts
+/**
+* Server adapter that sends real HTTP requests via the Fetch API.
+* Used by the `e2e()` specification runner to hit a live server.
+*/
+var FetchAdapter = class {
+	baseUrl;
+	constructor(url) {
+		this.baseUrl = url.replace(/\/$/, "");
 	}
-	/**
-	* Get a database service by compose name, or the first one if no name given.
-	*/
-	getDatabase(serviceName) {
-		for (const handle of [...this.services, ...this.composeHandles]) {
-			if (serviceName && handle.composeName !== serviceName) continue;
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter) return adapter;
-		}
-		return null;
+	async request(method, path, body, headers) {
+		const init = {
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
+		};
+		if (body !== void 0) init.body = JSON.stringify(body);
+		const response = await fetch(`${this.baseUrl}${path}`, init);
+		const responseBody = await response.json().catch(() => null);
+		const responseHeaders = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers: responseHeaders
+		};
 	}
-	/**
-	* Get all database services keyed by compose name.
-	*/
-	getDatabases() {
-		const map = /* @__PURE__ */ new Map();
-		for (const handle of [...this.services, ...this.composeHandles]) {
-			const adapter = handle.createDatabaseAdapter();
-			if (adapter && handle.composeName) map.set(handle.composeName, adapter);
-		}
-		return map;
+};
+//#endregion
+//#region src/spec/modes/http/adapters/hono.adapter.ts
+/**
+* Server adapter that dispatches requests in-process through a Hono app instance.
+* Used by the `integration()` specification runner -- no network overhead.
+*/
+var HonoAdapter = class {
+	app;
+	constructor(app) {
+		this.app = app;
 	}
-	/**
-	* Get app URL from compose (e2e mode).
-	*/
-	getAppUrl() {
-		const composePath = findComposeFile(this.root);
-		if (!composePath || !this.composeStack) return null;
-		const appService = parseComposeFile(composePath).appService;
-		if (!appService || appService.ports.length === 0) return null;
-		return `http://localhost:${this.composeStack.getMappedPort(appService.name, appService.ports[0].container)}`;
+	async request(method, path, body, headers) {
+		const init = {
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				...headers
+			}
+		};
+		if (body !== void 0) init.body = JSON.stringify(body);
+		const response = await this.app.request(path, init);
+		const responseBody = await response.json().catch(() => null);
+		const responseHeaders = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers: responseHeaders
+		};
 	}
 };
 //#endregion
@@ -1634,7 +2146,10 @@ async function startCommand(target, options) {
 		command: new ExecAdapter(bin),
 		database,
 		databases,
-		fixturesRoot: root
+		dockerConfig: options.docker,
+		fixturesRoot: root,
+		seedHandlers: options.seedHandlers,
+		transform: options.transform
 	});
 	runner.cleanup = async () => {
 		await releaseIsolation(services);
@@ -1683,10 +2198,28 @@ function stack(root) {
 /**
 * Test a CLI binary. Each spec runs in a fresh temp directory.
 *
+* Pass a `docker: { envVar, nameLabel, testRunLabel }` option on
+* {@link SpecOptions} to make the runner Docker-aware — the runner
+* stamps a unique test-run id into `envVar`, and results expose
+* `.container(name)` accessors that lazily query Docker. Tests that
+* never call `.container(...)` pay zero Docker cost.
+*
 * @param bin - Path to the CLI binary or command name (resolved from node_modules/.bin or PATH).
 *
 * @example
+*   // CLI-only
 *   await spec(command('my-cli'), { root: '../fixtures' });
+*
+*   // CLI binary that also spawns containers — same runner, just
+*   // opt into container accessors via the docker option:
+*   await spec(command('my-cli'), {
+*       root: '../fixtures',
+*       docker: {
+*           envVar: 'MYCLI_TEST_LABEL',
+*           nameLabel: 'com.mycli.world.name',
+*           testRunLabel: 'com.mycli.test.run',
+*       },
+*   });
 */
 function command(bin) {
 	return {
@@ -1695,92 +2228,6 @@ function command(bin) {
 	};
 }
 //#endregion
-//#region src/spec/legacy-cli.ts
-/**
-* Create a CLI specification runner.
-* Runs CLI commands against fixture projects. Optionally starts infrastructure.
-*/
-async function cli(options) {
-	const root = resolveProjectRoot(options.root);
-	const command = resolveCommand(options.command, root);
-	let orchestrator = null;
-	let database;
-	let databases;
-	if (options.services?.length) {
-		orchestrator = new Orchestrator({
-			mode: "integration",
-			root,
-			services: options.services
-		});
-		await orchestrator.start();
-		database = orchestrator.getDatabase() ?? void 0;
-		const dbMap = orchestrator.getDatabases();
-		databases = dbMap.size > 0 ? dbMap : void 0;
-	}
-	const runner = createSpecificationRunner({
-		command: new ExecAdapter(command),
-		database,
-		databases,
-		fixturesRoot: root
-	});
-	runner.cleanup = async () => {
-		if (orchestrator) await orchestrator.stop();
-	};
-	runner.orchestrator = orchestrator;
-	return runner;
-}
-//#endregion
-//#region src/spec/legacy-e2e.ts
-/**
-* Create an E2E specification runner.
-* Starts full docker compose stack. App URL and database auto-detected.
-*/
-async function e2e(options = {}) {
-	const orchestrator = new Orchestrator({
-		mode: "e2e",
-		root: resolveProjectRoot(options.root),
-		services: []
-	});
-	await orchestrator.startCompose();
-	const appUrl = orchestrator.getAppUrl();
-	if (!appUrl) throw new Error("E2E: could not detect app URL from compose. Ensure an app service with ports is defined.");
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		server: new FetchAdapter(appUrl)
-	});
-	runner.cleanup = () => orchestrator.stopCompose();
-	runner.orchestrator = orchestrator;
-	return runner;
-}
-//#endregion
-//#region src/spec/legacy-integration.ts
-/**
-* Create an integration specification runner.
-* Starts infra containers via testcontainers, app runs in-process.
-*/
-async function integration(options) {
-	const orchestrator = new Orchestrator({
-		mode: "integration",
-		root: resolveProjectRoot(options.root),
-		services: options.services
-	});
-	await orchestrator.start();
-	const app = options.app();
-	const database = orchestrator.getDatabase() ?? void 0;
-	const databases = orchestrator.getDatabases();
-	const runner = createSpecificationRunner({
-		database,
-		databases: databases.size > 0 ? databases : void 0,
-		server: new HonoAdapter(app)
-	});
-	runner.cleanup = () => orchestrator.stop();
-	runner.orchestrator = orchestrator;
-	return runner;
-}
-//#endregion
-export { DirectoryAccessor, DockerAssertion, ExecAdapter, FetchAdapter, HonoAdapter, Orchestrator, ResponseAccessor, SpecificationBuilder, SpecificationResult, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, sqlite, stack, stripAnsi };
+export { BaseResult, CliResult, ContainerAccessor, DirectoryAccessor, DockerAssertion, ExecAdapter, FetchAdapter, FilesystemAccessor, HonoAdapter, HttpResult, JsonAccessor, Orchestrator, ResponseAccessor, SpecificationBuilder, StreamAccessor, TableAssertion, app, command, createSpecificationRunner, dockerContainer, findContainersByLabel, inspectContainer, mockOf, mockOfDate, postgres, redis, removeContainers, spec, sqlite, stack };
 
 //# sourceMappingURL=index.js.map