@jterrazz/test 5.2.0 → 5.3.1

package/dist/index.cjs

@@ -21,197 +21,182 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-let mockdate = require("mockdate");
-mockdate = __toESM(mockdate);
-let vitest_mock_extended = require("vitest-mock-extended");
-let node_fs = require("node:fs");
-let node_path = require("node:path");
 let node_child_process = require("node:child_process");
-let yaml = require("yaml");
-let pg = require("pg");
+let node_fs = require("node:fs");
 let node_os = require("node:os");
+let node_path = require("node:path");
 let node_fs_promises = require("node:fs/promises");
-//#region src/mocking/mock-of-date.ts
-const mockOfDate = mockdate.default;
-//#endregion
-//#region src/mocking/mock-of.ts
-const mockOf = vitest_mock_extended.mockDeep;
-//#endregion
-//#region src/infrastructure/adapters/compose.adapter.ts
+let pg = require("pg");
+let yaml = require("yaml");
+let mockdate = require("mockdate");
+mockdate = __toESM(mockdate);
+let vitest_mock_extended = require("vitest-mock-extended");
+//#region src/adapters/exec.adapter.ts
 /**
-* Start the full compose stack and stop it all on cleanup.
+* Build a child-process env from the parent env plus user overrides.
+* `null` overrides delete keys (e.g. `INIT_CWD: null`).
 */
-var ComposeStackAdapter = class {
-	composeFile;
-	started = false;
-	constructor(composeFile) {
-		this.composeFile = composeFile;
-	}
-	run(command) {
-		try {
-			return (0, node_child_process.execSync)(command, {
-				cwd: (0, node_path.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 });
-		}
-	}
-	async start() {
-		if (this.started) return;
-		this.run(`docker compose -f ${this.composeFile} up -d --wait`);
-		this.started = true;
-	}
-	async stop() {
-		if (!this.started) return;
-		this.run(`docker compose -f ${this.composeFile} down -v`);
-		this.started = false;
-	}
-	getMappedPort(serviceName, containerPort) {
-		const port = this.run(`docker compose -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
-		return Number(port);
-	}
-	getHost() {
-		return "localhost";
-	}
-};
-//#endregion
-//#region src/infrastructure/adapters/testcontainers.adapter.ts
+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;
+}
 /**
-* Container adapter using testcontainers.
-* Wraps a GenericContainer for programmatic container lifecycle.
+* Executes CLI commands via execSync (blocking) or spawn (long-running).
+* Used by cli() for local command execution.
 */
-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;
-	}
-	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();
+var ExecAdapter = class {
+	command;
+	constructor(command) {
+		this.command = command;
 	}
-	async stop() {
-		if (this.container && !this.reuse) {
-			await this.container.stop();
-			this.container = null;
+	async exec(args, cwd, extraEnv) {
+		const env = buildEnv(extraEnv);
+		try {
+			return {
+				exitCode: 0,
+				stdout: (0, node_child_process.execSync)(`${this.command} ${args}`, {
+					cwd,
+					encoding: "utf8",
+					env,
+					stdio: [
+						"pipe",
+						"pipe",
+						"pipe"
+					]
+				}),
+				stderr: ""
+			};
+		} catch (error) {
+			return {
+				exitCode: error.status ?? 1,
+				stdout: error.stdout?.toString() ?? "",
+				stderr: error.stderr?.toString() ?? ""
+			};
 		}
 	}
-	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();
+	async spawn(args, cwd, options, extraEnv) {
+		const env = buildEnv(extraEnv);
 		return new Promise((resolve) => {
-			let output = "";
-			stream.on("data", (chunk) => {
-				output += chunk.toString();
+			let stdout = "";
+			let stderr = "";
+			let resolved = false;
+			const child = (0, node_child_process.spawn)(this.command, args.split(/\s+/).filter(Boolean), {
+				cwd,
+				env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
 			});
-			stream.on("end", () => {
-				resolve(output);
+			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();
 			});
-			setTimeout(() => {
-				resolve(output);
-			}, 1e3);
+			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);
 		});
 	}
 };
 //#endregion
-//#region src/infrastructure/compose-parser.ts
+//#region src/utilities/directory.ts
 /**
-* Detect the service type from the image name.
+* Default ignore patterns — paths that should never appear in a tracked snapshot.
+* Each entry is matched against any path segment OR a path prefix.
 */
-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";
-}
+const DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	".next",
+	"dist",
+	".turbo",
+	".cache"
+];
 /**
-* Find the compose file in the project.
-* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
+* Recursively walk a directory, returning sorted relative paths of files only.
+* Ignored entries (default + caller-supplied) are skipped.
 */
-function findComposeFile(projectRoot) {
-	const candidates = [
-		(0, node_path.resolve)(projectRoot, "docker/compose.test.yaml"),
-		(0, node_path.resolve)(projectRoot, "docker/compose.test.yml"),
-		(0, node_path.resolve)(projectRoot, "docker-compose.test.yaml"),
-		(0, node_path.resolve)(projectRoot, "docker-compose.test.yml")
-	];
-	for (const candidate of candidates) if ((0, node_fs.existsSync)(candidate)) return candidate;
-	return null;
+async function walkDirectory(root, options = {}) {
+	const ignores = new Set([...DEFAULT_IGNORES, ...options.ignore ?? []]);
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await (0, node_fs_promises.readdir)(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignores.has(entry)) continue;
+			const abs = (0, node_path.resolve)(current, entry);
+			const stat = (0, node_fs.statSync)(abs);
+			if (stat.isDirectory()) await walk(abs);
+			else if (stat.isFile()) out.push((0, node_path.relative)(root, abs).split(node_path.sep).join("/"));
+		}
+	}
+	await walk(root);
+	out.sort();
+	return out;
 }
 /**
-* Parse a docker-compose file and extract service definitions.
+* Compare two directory trees file-by-file.
+* Binary files are compared by byte equality but reported without inline diff.
 */
-function parseComposeFile(filePath) {
-	const doc = (0, yaml.parse)((0, node_fs.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
-		};
-	});
+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 = (0, node_fs.readFileSync)((0, node_path.resolve)(expectedRoot, file), "utf8");
+		const actual = (0, node_fs.readFileSync)((0, node_path.resolve)(actualRoot, file), "utf8");
+		if (expected !== actual) changed.push({
+			actual,
+			expected,
+			path: file
+		});
+	}
 	return {
-		services,
-		appService: services.find((s) => s.build !== void 0) ?? null,
-		infraServices: services.filter((s) => s.build === void 0)
+		added,
+		changed,
+		removed
 	};
 }
 //#endregion
-//#region src/infrastructure/reporter.ts
+//#region src/utilities/reporter.ts
 const GREEN = "\x1B[32m";
 const RED = "\x1B[31m";
 const DIM = "\x1B[2m";
@@ -347,915 +332,859 @@ 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();
 }
 //#endregion
-//#region src/infrastructure/services/postgres.ts
-var PostgresHandle = class {
-	type = "postgres";
-	composeName;
-	defaultPort = 5432;
-	defaultImage;
-	environment;
-	connectionString = "";
-	started = false;
-	client = null;
-	constructor(options = {}) {
-		this.composeName = options.compose ?? null;
-		this.defaultImage = options.image ?? "postgres:17";
-		this.environment = {
-			POSTGRES_DB: "test",
-			POSTGRES_PASSWORD: "test",
-			POSTGRES_USER: "test",
-			...options.env
-		};
-	}
-	buildConnectionString(host, port) {
-		return `postgresql://${this.environment.POSTGRES_USER ?? "test"}:${this.environment.POSTGRES_PASSWORD ?? "test"}@${host}:${port}/${this.environment.POSTGRES_DB ?? "test"}`;
-	}
-	createDatabaseAdapter() {
-		return this;
-	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("postgres: cannot healthcheck — no connection string");
-		try {
-			const client = new pg.Client({ connectionString: this.connectionString });
-			await client.connect();
-			await client.query("SELECT 1");
-			await client.end();
-		} catch (error) {
-			throw new Error(`postgres healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
-		}
+//#region src/builder/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
+*/
+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;
+}
+var DirectoryAccessor = class {
+	absPath;
+	testDir;
+	constructor(absPath, testDir) {
+		this.absPath = absPath;
+		this.testDir = testDir;
 	}
-	async initialize(composeDir) {
-		if (!this.composeName) return;
-		const initPaths = [(0, node_path.resolve)(composeDir, `${this.composeName}/init.sql`), (0, node_path.resolve)(composeDir, "postgres/init.sql")];
-		for (const initPath of initPaths) if ((0, node_fs.existsSync)(initPath)) {
-			const sql = (0, node_fs.readFileSync)(initPath, "utf8");
-			try {
-				await this.seed(sql);
-			} catch (error) {
-				throw new Error(`postgres init script failed (${initPath}):\n${error.message}`, { cause: error });
-			}
+	/**
+	* 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 = (0, node_path.resolve)(this.testDir, "expected", name);
+		if (options.update ?? shouldUpdateSnapshots()) {
+			(0, node_fs.rmSync)(fixtureDir, {
+				force: true,
+				recursive: true
+			});
+			(0, node_fs.mkdirSync)(fixtureDir, { recursive: true });
+			(0, node_fs.cpSync)(this.absPath, fixtureDir, { recursive: true });
 			return;
 		}
+		if (!(0, node_fs.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 getClient() {
-		if (this.client) return this.client;
-		const client = new pg.Client({ connectionString: this.connectionString });
-		client.on("error", () => {
-			this.client = null;
-		});
-		await client.connect();
-		this.client = client;
-		return client;
-	}
-	async seed(sql) {
-		await (await this.getClient()).query(sql);
-	}
-	async query(table, columns) {
-		const client = await this.getClient();
-		const columnList = columns.join(", ");
-		return (await client.query(`SELECT ${columnList} FROM "${table}" ORDER BY 1`)).rows.map((row) => columns.map((col) => row[col]));
-	}
-	async reset() {
-		const client = await this.getClient();
-		const result = await client.query(`
-            SELECT tablename FROM pg_tables
-            WHERE schemaname = 'public'
-            AND tablename NOT LIKE '_prisma%'
-        `);
-		for (const row of result.rows) await client.query(`TRUNCATE "${row.tablename}" CASCADE`);
+	/**
+	* 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);
 	}
 };
-/**
-* Create a PostgreSQL service handle.
-*
-* @example
-* const db = postgres({ compose: "db" });
-* // After start: db.connectionString is populated
-*/
-function postgres(options = {}) {
-	return new PostgresHandle(options);
-}
 //#endregion
-//#region src/infrastructure/services/redis.ts
-var RedisHandle = class {
-	type = "redis";
-	composeName;
-	defaultPort = 6379;
-	defaultImage;
-	environment = {};
-	connectionString = "";
-	started = false;
-	constructor(options = {}) {
-		this.composeName = options.compose ?? null;
-		this.defaultImage = options.image ?? "redis:7";
+//#region src/builder/response-accessor.ts
+var ResponseAccessor = class {
+	body;
+	testDir;
+	constructor(body, testDir) {
+		this.body = body;
+		this.testDir = testDir;
 	}
-	buildConnectionString(host, port) {
-		return `redis://${host}:${port}`;
+	toMatchFile(file) {
+		const expected = JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "responses", file), "utf8"));
+		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
 	}
-	createDatabaseAdapter() {
-		return null;
+};
+//#endregion
+//#region src/builder/table-assertion.ts
+var TableAssertion = class {
+	tableName;
+	db;
+	constructor(tableName, db) {
+		this.tableName = tableName;
+		this.db = db;
 	}
-	async healthcheck() {
-		if (!this.connectionString) throw new Error("redis: cannot healthcheck — no connection string");
-		try {
-			const { createClient } = await import("redis");
-			const client = createClient({ url: this.connectionString });
-			await client.connect();
-			await client.ping();
-			await client.disconnect();
-		} catch (error) {
-			throw new Error(`redis healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
-		}
+	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));
 	}
-	async initialize() {}
-	async reset() {
-		const { createClient } = await import("redis");
-		const client = createClient({ url: this.connectionString });
-		await client.connect();
-		try {
-			await client.flushAll();
-		} finally {
-			await client.disconnect();
-		}
+	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`);
 	}
 };
-/**
-* Create a Redis service handle.
-*
-* @example
-* const cache = redis({ compose: "cache" });
-* // After start: cache.connectionString is populated
-*/
-function redis(options = {}) {
-	return new RedisHandle(options);
-}
 //#endregion
-//#region src/infrastructure/orchestrator.ts
-/**
-* Orchestrator for test infrastructure.
-* Integration: starts services via testcontainers.
-* E2E: runs full docker compose up.
-*/
-var Orchestrator = class {
-	services;
-	mode;
-	root;
-	running = [];
-	composeStack = null;
-	composeHandles = [];
-	started = false;
-	constructor(options) {
-		this.services = options.services;
-		this.mode = options.mode;
-		this.root = options.root ?? process.cwd();
+//#region src/builder/specification-result.ts
+var SpecificationResult = class {
+	commandResult;
+	config;
+	requestInfo;
+	responseData;
+	testDir;
+	workDir;
+	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;
 	}
-	/**
-	* 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).
-	*/
-	async start() {
-		if (this.started) return;
-		const composePath = findComposeFile(this.root);
-		const composeDir = composePath ? (0, node_path.dirname)(composePath) : this.root;
-		const composeConfig = composePath ? parseComposeFile(composePath) : null;
-		const containerTasks = this.services.map((handle) => {
-			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);
-				}
-			}
-			return {
-				container: new TestcontainersAdapter({
-					image,
-					port: handle.defaultPort,
-					env
-				}),
-				handle
-			};
-		});
-		await Promise.all(containerTasks.map(({ container }) => container.start()));
-		const reports = [];
-		for (const { container, handle } of containerTasks) {
-			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);
+	get exitCode() {
+		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
+		return this.commandResult.exitCode;
 	}
-	/**
-	* Stop testcontainers (integration mode).
-	*/
-	async stop() {
-		for (const { container } of this.running) if (container) await container.stop();
-		this.running = [];
-		this.started = false;
+	get status() {
+		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
+		return this.responseData.status;
 	}
-	/**
-	* 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 = (0, node_path.dirname)(composePath);
-		const composeConfig = parseComposeFile(composePath);
-		this.composeStack = new ComposeStackAdapter(composePath);
-		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);
+	get stdout() {
+		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
+		return this.commandResult.stdout;
 	}
-	/**
-	* Stop docker compose stack (e2e mode).
-	*/
-	async stopCompose() {
-		if (this.composeStack) {
-			await this.composeStack.stop();
-			this.composeStack = null;
-		}
-		this.composeHandles = [];
+	get stderr() {
+		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
+		return this.commandResult.stderr;
 	}
-	/**
-	* 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;
+	get response() {
+		if (!this.responseData) throw new Error(".response requires an HTTP action (.get(), .post(), etc.)");
+		return new ResponseAccessor(this.responseData.body, this.testDir);
 	}
-	/**
-	* 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;
+	directory(path = ".") {
+		return new DirectoryAccessor((0, node_path.resolve)(this.workDir ?? this.testDir, path), this.testDir);
 	}
-	/**
-	* 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)}`;
+	file(path) {
+		const resolvedPath = (0, node_path.resolve)(this.workDir ?? this.testDir, path);
+		const exists = (0, node_fs.existsSync)(resolvedPath);
+		return {
+			get content() {
+				if (!exists) throw new Error(`File not found: ${path}`);
+				return (0, node_fs.readFileSync)(resolvedPath, "utf8");
+			},
+			exists
+		};
+	}
+	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);
+	}
+	resolveDatabase(serviceName) {
+		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
+		return this.config.database;
 	}
 };
 //#endregion
-//#region src/specification/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 execSync (blocking) or spawn (long-running).
-* Used by cli() for local command execution.
-*/
-var ExecAdapter = class {
-	command;
-	constructor(command) {
-		this.command = command;
+//#region src/builder/specification-builder.ts
+var SpecificationBuilder = class {
+	commandArgs = null;
+	commandEnv = {};
+	config;
+	fixtures = [];
+	label;
+	mocks = [];
+	projectName = null;
+	request = null;
+	seeds = [];
+	spawnConfig = null;
+	testDir;
+	constructor(config, testDir, label) {
+		this.config = config;
+		this.testDir = testDir;
+		this.label = label;
 	}
-	async exec(args, cwd, extraEnv) {
-		const env = buildEnv(extraEnv);
-		try {
-			return {
-				exitCode: 0,
-				stdout: (0, node_child_process.execSync)(`${this.command} ${args}`, {
-					cwd,
-					encoding: "utf8",
-					env,
-					stdio: [
-						"pipe",
-						"pipe",
-						"pipe"
-					]
-				}),
-				stderr: ""
-			};
-		} catch (error) {
-			return {
-				exitCode: error.status ?? 1,
-				stdout: error.stdout?.toString() ?? "",
-				stderr: error.stderr?.toString() ?? ""
-			};
-		}
-	}
-	async spawn(args, cwd, options, extraEnv) {
-		const env = buildEnv(extraEnv);
-		return new Promise((resolve) => {
-			let stdout = "";
-			let stderr = "";
-			let resolved = false;
-			const child = (0, node_child_process.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);
+	seed(file, options) {
+		this.seeds.push({
+			file,
+			service: options?.service
 		});
+		return this;
 	}
-};
-//#endregion
-//#region src/specification/adapters/fetch.adapter.ts
-/**
-* Server adapter for real HTTP — sends actual fetch requests.
-* Used by e2e() specification runner.
-*/
-var FetchAdapter = class {
-	baseUrl;
-	constructor(url) {
-		this.baseUrl = url.replace(/\/$/, "");
+	fixture(file) {
+		this.fixtures.push({ file });
+		return this;
 	}
-	async request(method, path, body) {
-		const init = {
-			method,
-			headers: { "Content-Type": "application/json" }
+	project(name) {
+		this.projectName = name;
+		return this;
+	}
+	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
 		};
-		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 headers = {};
-		response.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers
+		return this;
+	}
+	get(path) {
+		this.request = {
+			method: "GET",
+			path
+		};
+		return this;
+	}
+	post(path, bodyFile) {
+		this.request = {
+			bodyFile,
+			method: "POST",
+			path
 		};
+		return this;
 	}
-};
-//#endregion
-//#region src/specification/adapters/hono.adapter.ts
-/**
-* Server adapter for Hono — in-process requests, no real HTTP.
-* Used by integration() specification runner.
-*/
-var HonoAdapter = class {
-	app;
-	constructor(app) {
-		this.app = app;
+	put(path, bodyFile) {
+		this.request = {
+			bodyFile,
+			method: "PUT",
+			path
+		};
+		return this;
 	}
-	async request(method, path, body) {
-		const init = {
-			method,
-			headers: { "Content-Type": "application/json" }
+	delete(path) {
+		this.request = {
+			method: "DELETE",
+			path
 		};
-		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 headers = {};
-		response.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		return {
-			status: response.status,
-			body: responseBody,
-			headers
+		return this;
+	}
+	exec(args) {
+		this.commandArgs = args;
+		return this;
+	}
+	spawn(args, options) {
+		this.spawnConfig = {
+			args,
+			options
 		};
+		return this;
 	}
-};
-//#endregion
-//#region src/specification/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 (0, node_fs_promises.readdir)(current);
-		} catch {
-			return;
+	async run() {
+		const hasHttpAction = this.request !== null;
+		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
+		if (!hasHttpAction && !hasCliAction) throw new Error(`Specification "${this.label}": no action defined. Call .get(), .post(), .exec(), etc. before .run()`);
+		if (hasHttpAction && hasCliAction) throw new Error(`Specification "${this.label}": cannot mix HTTP (.get/.post) and CLI (.exec/.spawn) actions`);
+		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 = (0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "seeds", entry.file), "utf8");
+			await db.seed(sql);
 		}
-		for (const entry of entries) {
-			if (ignores.has(entry)) continue;
-			const abs = (0, node_path.resolve)(current, entry);
-			const stat = (0, node_fs.statSync)(abs);
-			if (stat.isDirectory()) await walk(abs);
-			else if (stat.isFile()) out.push((0, node_path.relative)(root, abs).split(node_path.sep).join("/"));
+		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) (0, node_fs.cpSync)((0, node_path.resolve)(this.testDir, "fixtures", entry.file), (0, node_path.resolve)(workDir, entry.file), { recursive: true });
+		for (const entry of this.mocks) JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "mock", entry.file), "utf8"));
+		if (hasHttpAction) return this.runHttpAction();
+		return this.runCliAction(workDir);
+	}
+	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;
 	}
-	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 = (0, node_fs.readFileSync)((0, node_path.resolve)(expectedRoot, file), "utf8");
-		const actual = (0, node_fs.readFileSync)((0, node_path.resolve)(actualRoot, file), "utf8");
-		if (expected !== actual) changed.push({
-			actual,
-			expected,
-			path: file
+	prepareWorkDir() {
+		const tempDir = (0, node_fs.mkdtempSync)((0, node_path.resolve)((0, node_os.tmpdir)(), "spec-cli-"));
+		if (this.projectName && this.config.fixturesRoot) {
+			const projectDir = (0, node_path.resolve)(this.config.fixturesRoot, this.projectName);
+			if (!(0, node_fs.existsSync)(projectDir)) throw new Error(`project("${this.projectName}"): fixture project not found at ${projectDir}`);
+			(0, node_fs.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((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "requests", this.request.bodyFile), "utf8"));
+		const response = await this.config.server.request(this.request.method, this.request.path, body);
+		return new SpecificationResult({
+			config: this.config,
+			requestInfo: {
+				body,
+				method: this.request.method,
+				path: this.request.path
+			},
+			response,
+			testDir: this.testDir
 		});
 	}
-	return {
-		added,
-		changed,
-		removed
+	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/runner/")) continue;
+		if (filePath.includes("/package-test/dist/") || filePath.includes("/package-test/src/")) continue;
+		return (0, node_path.resolve)(filePath, "..");
+	}
+	throw new Error("Cannot detect caller directory from stack trace");
+}
+function createSpecificationRunner(config) {
+	return (label) => {
+		return new SpecificationBuilder(config, getCallerDir(), label);
 	};
 }
 //#endregion
-//#region src/specification/specification.ts
-var TableAssertion = class {
-	tableName;
-	db;
-	constructor(tableName, db) {
-		this.tableName = tableName;
-		this.db = db;
-	}
-	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));
-	}
-	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`);
-	}
-};
+//#region src/adapters/compose.adapter.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
+* Start the full compose stack and stop it all on cleanup.
 */
-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;
-}
-var DirectoryAccessor = class {
-	absPath;
-	testDir;
-	constructor(absPath, testDir) {
-		this.absPath = absPath;
-		this.testDir = testDir;
+var ComposeStackAdapter = class {
+	composeFile;
+	started = false;
+	constructor(composeFile) {
+		this.composeFile = composeFile;
 	}
-	/**
-	* 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 = (0, node_path.resolve)(this.testDir, "expected", name);
-		if (options.update ?? shouldUpdateSnapshots()) {
-			(0, node_fs.rmSync)(fixtureDir, {
-				force: true,
-				recursive: true
-			});
-			(0, node_fs.mkdirSync)(fixtureDir, { recursive: true });
-			(0, node_fs.cpSync)(this.absPath, fixtureDir, { recursive: true });
-			return;
+	run(command) {
+		try {
+			return (0, node_child_process.execSync)(command, {
+				cwd: (0, node_path.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 (!(0, node_fs.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 -f ${this.composeFile} up -d --wait`);
+		this.started = true;
 	}
-};
-var ResponseAccessor = class {
-	body;
-	testDir;
-	constructor(body, testDir) {
-		this.body = body;
-		this.testDir = testDir;
+	async stop() {
+		if (!this.started) return;
+		this.run(`docker compose -f ${this.composeFile} down -v`);
+		this.started = false;
 	}
-	toMatchFile(file) {
-		const expected = JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "responses", file), "utf8"));
-		if (JSON.stringify(this.body) !== JSON.stringify(expected)) throw new Error(formatResponseDiff(file, expected, this.body));
+	getMappedPort(serviceName, containerPort) {
+		const port = this.run(`docker compose -f ${this.composeFile} port ${serviceName} ${containerPort}`).split(":").pop();
+		return Number(port);
 	}
-};
-var SpecificationResult = class {
-	commandResult;
-	config;
-	requestInfo;
-	responseData;
-	testDir;
-	workDir;
-	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;
+	getHost() {
+		return "localhost";
 	}
-	get exitCode() {
-		if (!this.commandResult) throw new Error(".exitCode requires a CLI action (.exec())");
-		return this.commandResult.exitCode;
+};
+//#endregion
+//#region src/adapters/postgres.adapter.ts
+var PostgresHandle = class {
+	type = "postgres";
+	composeName;
+	defaultPort = 5432;
+	defaultImage;
+	environment;
+	connectionString = "";
+	started = false;
+	client = null;
+	constructor(options = {}) {
+		this.composeName = options.compose ?? null;
+		this.defaultImage = options.image ?? "postgres:17";
+		this.environment = {
+			POSTGRES_DB: "test",
+			POSTGRES_PASSWORD: "test",
+			POSTGRES_USER: "test",
+			...options.env
+		};
 	}
-	get status() {
-		if (!this.responseData) throw new Error(".status requires an HTTP action (.get(), .post(), etc.)");
-		return this.responseData.status;
+	buildConnectionString(host, port) {
+		return `postgresql://${this.environment.POSTGRES_USER ?? "test"}:${this.environment.POSTGRES_PASSWORD ?? "test"}@${host}:${port}/${this.environment.POSTGRES_DB ?? "test"}`;
 	}
-	get stdout() {
-		if (!this.commandResult) throw new Error(".stdout requires a CLI action (.exec())");
-		return this.commandResult.stdout;
+	createDatabaseAdapter() {
+		return this;
 	}
-	get stderr() {
-		if (!this.commandResult) throw new Error(".stderr requires a CLI action (.exec())");
-		return this.commandResult.stderr;
+	async healthcheck() {
+		if (!this.connectionString) throw new Error("postgres: cannot healthcheck — no connection string");
+		try {
+			const client = new pg.Client({ connectionString: this.connectionString });
+			await client.connect();
+			await client.query("SELECT 1");
+			await client.end();
+		} catch (error) {
+			throw new Error(`postgres healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
+		}
 	}
-	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 initialize(composeDir) {
+		if (!this.composeName) return;
+		const initPaths = [(0, node_path.resolve)(composeDir, `${this.composeName}/init.sql`), (0, node_path.resolve)(composeDir, "postgres/init.sql")];
+		for (const initPath of initPaths) if ((0, node_fs.existsSync)(initPath)) {
+			const sql = (0, node_fs.readFileSync)(initPath, "utf8");
+			try {
+				await this.seed(sql);
+			} catch (error) {
+				throw new Error(`postgres init script failed (${initPath}):\n${error.message}`, { cause: error });
+			}
+			return;
+		}
 	}
-	directory(path = ".") {
-		return new DirectoryAccessor((0, node_path.resolve)(this.workDir ?? this.testDir, path), this.testDir);
+	async getClient() {
+		if (this.client) return this.client;
+		const client = new pg.Client({ connectionString: this.connectionString });
+		client.on("error", () => {
+			this.client = null;
+		});
+		await client.connect();
+		this.client = client;
+		return client;
 	}
-	file(path) {
-		const resolvedPath = (0, node_path.resolve)(this.workDir ?? this.testDir, path);
-		const exists = (0, node_fs.existsSync)(resolvedPath);
-		return {
-			get content() {
-				if (!exists) throw new Error(`File not found: ${path}`);
-				return (0, node_fs.readFileSync)(resolvedPath, "utf8");
-			},
-			exists
-		};
+	async seed(sql) {
+		await (await this.getClient()).query(sql);
 	}
-	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);
+	async query(table, columns) {
+		const client = await this.getClient();
+		const columnList = columns.join(", ");
+		return (await client.query(`SELECT ${columnList} FROM "${table}" ORDER BY 1`)).rows.map((row) => columns.map((col) => row[col]));
 	}
-	resolveDatabase(serviceName) {
-		if (serviceName && this.config.databases) return this.config.databases.get(serviceName);
-		return this.config.database;
+	async reset() {
+		const client = await this.getClient();
+		const result = await client.query(`
+            SELECT tablename FROM pg_tables
+            WHERE schemaname = 'public'
+            AND tablename NOT LIKE '_prisma%'
+        `);
+		for (const row of result.rows) await client.query(`TRUNCATE "${row.tablename}" CASCADE`);
 	}
 };
-var SpecificationBuilder = class {
-	commandArgs = null;
-	commandEnv = {};
-	config;
-	fixtures = [];
-	label;
-	mocks = [];
-	projectName = null;
-	request = null;
-	seeds = [];
-	spawnConfig = null;
-	testDir;
-	constructor(config, testDir, label) {
-		this.config = config;
-		this.testDir = testDir;
-		this.label = label;
+/**
+* Create a PostgreSQL service handle.
+*
+* @example
+* const db = postgres({ compose: "db" });
+* // After start: db.connectionString is populated
+*/
+function postgres(options = {}) {
+	return new PostgresHandle(options);
+}
+//#endregion
+//#region src/adapters/redis.adapter.ts
+var RedisHandle = class {
+	type = "redis";
+	composeName;
+	defaultPort = 6379;
+	defaultImage;
+	environment = {};
+	connectionString = "";
+	started = false;
+	constructor(options = {}) {
+		this.composeName = options.compose ?? null;
+		this.defaultImage = options.image ?? "redis:7";
 	}
-	seed(file, options) {
-		this.seeds.push({
-			file,
-			service: options?.service
-		});
-		return this;
+	buildConnectionString(host, port) {
+		return `redis://${host}:${port}`;
 	}
-	fixture(file) {
-		this.fixtures.push({ file });
-		return this;
+	createDatabaseAdapter() {
+		return null;
 	}
-	project(name) {
-		this.projectName = name;
-		return this;
+	async healthcheck() {
+		if (!this.connectionString) throw new Error("redis: cannot healthcheck — no connection string");
+		try {
+			const { createClient } = await import("redis");
+			const client = createClient({ url: this.connectionString });
+			await client.connect();
+			await client.ping();
+			await client.disconnect();
+		} catch (error) {
+			throw new Error(`redis healthcheck failed: ${error.message || error.code || String(error)}`, { cause: error });
+		}
 	}
-	mock(file) {
-		this.mocks.push({ file });
-		return this;
+	async initialize() {}
+	async reset() {
+		const { createClient } = await import("redis");
+		const client = createClient({ url: this.connectionString });
+		await client.connect();
+		try {
+			await client.flushAll();
+		} finally {
+			await client.disconnect();
+		}
 	}
-	/**
-	* 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;
+};
+/**
+* Create a Redis service handle.
+*
+* @example
+* const cache = redis({ compose: "cache" });
+* // After start: cache.connectionString is populated
+*/
+function redis(options = {}) {
+	return new RedisHandle(options);
+}
+//#endregion
+//#region src/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;
 	}
-	get(path) {
-		this.request = {
-			method: "GET",
-			path
-		};
-		return this;
+	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();
 	}
-	post(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "POST",
-			path
-		};
-		return this;
+	async stop() {
+		if (this.container && !this.reuse) {
+			await this.container.stop();
+			this.container = null;
+		}
 	}
-	put(path, bodyFile) {
-		this.request = {
-			bodyFile,
-			method: "PUT",
-			path
-		};
-		return this;
+	getMappedPort(containerPort) {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getMappedPort(containerPort);
 	}
-	delete(path) {
-		this.request = {
-			method: "DELETE",
-			path
-		};
-		return this;
+	getHost() {
+		if (!this.container) throw new Error("Container not started");
+		return this.container.getHost();
 	}
-	exec(args) {
-		this.commandArgs = args;
-		return this;
+	getConnectionString() {
+		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
 	}
-	spawn(args, options) {
-		this.spawnConfig = {
-			args,
-			options
+	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/orchestrator/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";
+}
+/**
+* Find the compose file in the project.
+* Looks for docker/compose.test.yaml or docker-compose.test.yaml.
+*/
+function findComposeFile(projectRoot) {
+	const candidates = [
+		(0, node_path.resolve)(projectRoot, "docker/compose.test.yaml"),
+		(0, node_path.resolve)(projectRoot, "docker/compose.test.yml"),
+		(0, node_path.resolve)(projectRoot, "docker-compose.test.yaml"),
+		(0, node_path.resolve)(projectRoot, "docker-compose.test.yml")
+	];
+	for (const candidate of candidates) if ((0, node_fs.existsSync)(candidate)) return candidate;
+	return null;
+}
+/**
+* Parse a docker-compose file and extract service definitions.
+*/
+function parseComposeFile(filePath) {
+	const doc = (0, yaml.parse)((0, node_fs.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 this;
+	});
+	return {
+		services,
+		appService: services.find((s) => s.build !== void 0) ?? null,
+		infraServices: services.filter((s) => s.build === void 0)
+	};
+}
+//#endregion
+//#region src/orchestrator/orchestrator.ts
+/**
+* Orchestrator for test infrastructure.
+* Integration: starts services via testcontainers.
+* E2E: runs full docker compose up.
+*/
+var Orchestrator = class {
+	services;
+	mode;
+	root;
+	running = [];
+	composeStack = null;
+	composeHandles = [];
+	started = false;
+	constructor(options) {
+		this.services = options.services;
+		this.mode = options.mode;
+		this.root = options.root ?? process.cwd();
 	}
-	async run() {
-		const hasHttpAction = this.request !== null;
-		const hasCliAction = this.commandArgs !== null || this.spawnConfig !== null;
-		if (!hasHttpAction && !hasCliAction) throw new Error(`Specification "${this.label}": no action defined. Call .get(), .post(), .exec(), etc. before .run()`);
-		if (hasHttpAction && hasCliAction) throw new Error(`Specification "${this.label}": cannot mix HTTP (.get/.post) and CLI (.exec/.spawn) actions`);
-		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 = (0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "seeds", entry.file), "utf8");
-			await db.seed(sql);
+	/**
+	* 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).
+	*/
+	async start() {
+		if (this.started) return;
+		const composePath = findComposeFile(this.root);
+		const composeDir = composePath ? (0, node_path.dirname)(composePath) : this.root;
+		const composeConfig = composePath ? parseComposeFile(composePath) : null;
+		const containerTasks = this.services.map((handle) => {
+			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);
+				}
+			}
+			return {
+				container: new TestcontainersAdapter({
+					image,
+					port: handle.defaultPort,
+					env
+				}),
+				handle
+			};
+		});
+		await Promise.all(containerTasks.map(({ container }) => container.start()));
+		const reports = [];
+		for (const { container, handle } of containerTasks) {
+			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;
+			}
 		}
-		if (this.fixtures.length > 0 && workDir) for (const entry of this.fixtures) (0, node_fs.cpSync)((0, node_path.resolve)(this.testDir, "fixtures", entry.file), (0, node_path.resolve)(workDir, entry.file), { recursive: true });
-		for (const entry of this.mocks) JSON.parse((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "mock", entry.file), "utf8"));
-		if (hasHttpAction) return this.runHttpAction();
-		return this.runCliAction(workDir);
+		this.started = true;
+		const output = formatStartupReport("integration", reports, { type: "in-process" });
+		console.log(output);
 	}
-	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;
+	/**
+	* Stop testcontainers (integration mode).
+	*/
+	async stop() {
+		for (const { container } of this.running) if (container) await container.stop();
+		this.running = [];
+		this.started = false;
+	}
+	/**
+	* 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 = (0, node_path.dirname)(composePath);
+		const composeConfig = parseComposeFile(composePath);
+		this.composeStack = new ComposeStackAdapter(composePath);
+		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);
+	}
+	/**
+	* Stop docker compose stack (e2e mode).
+	*/
+	async stopCompose() {
+		if (this.composeStack) {
+			await this.composeStack.stop();
+			this.composeStack = null;
+		}
+		this.composeHandles = [];
+	}
+	/**
+	* 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 resolved;
+		return null;
 	}
-	prepareWorkDir() {
-		const tempDir = (0, node_fs.mkdtempSync)((0, node_path.resolve)((0, node_os.tmpdir)(), "spec-cli-"));
-		if (this.projectName && this.config.fixturesRoot) {
-			const projectDir = (0, node_path.resolve)(this.config.fixturesRoot, this.projectName);
-			if (!(0, node_fs.existsSync)(projectDir)) throw new Error(`project("${this.projectName}"): fixture project not found at ${projectDir}`);
-			(0, node_fs.cpSync)(projectDir, tempDir, { recursive: true });
+	/**
+	* 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 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((0, node_fs.readFileSync)((0, node_path.resolve)(this.testDir, "requests", this.request.bodyFile), "utf8"));
-		const response = await this.config.server.request(this.request.method, this.request.path, body);
-		return new SpecificationResult({
-			config: this.config,
-			requestInfo: {
-				body,
-				method: this.request.method,
-				path: this.request.path
-			},
-			response,
-			testDir: this.testDir
-		});
+		return map;
 	}
-	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
-		});
+	/**
+	* 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)}`;
 	}
 };
-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/specification/")) continue;
-		return (0, node_path.resolve)(filePath, "..");
-	}
-	throw new Error("Cannot detect caller directory from stack trace");
-}
-function createSpecificationRunner(config) {
-	return (label) => {
-		return new SpecificationBuilder(config, getCallerDir(), label);
-	};
-}
-//#endregion
-//#region src/specification/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/specification/index.ts
+//#region src/runner/resolve.ts
 /**
 * Resolve root — if relative, resolves from the caller's directory.
 */
@@ -1269,7 +1198,8 @@ function resolveProjectRoot(root) {
 			const match = line.match(/at\s+(?:.*?\()?(?:file:\/\/)?([^:)]+):\d+:\d+/);
 			if (!match) continue;
 			const filePath = match[1];
-			if (filePath.includes("node_modules") || filePath.includes("/specification/")) continue;
+			if (filePath.includes("node_modules")) continue;
+			if (filePath.includes("/src/runner/") || filePath.includes("/dist/")) continue;
 			return (0, node_path.resolve)(filePath, "..", root);
 		}
 	}
@@ -1286,29 +1216,73 @@ function resolveCommand(command, root) {
 	if ((0, node_fs.existsSync)(cwdBinPath)) return cwdBinPath;
 	return command;
 }
+//#endregion
+//#region src/runner/cli.ts
 /**
-* Create an integration specification runner.
-* Starts infra containers via testcontainers, app runs in-process.
+* Create a CLI specification runner.
+* Runs CLI commands against fixture projects. Optionally starts infrastructure.
 */
-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();
+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: databases.size > 0 ? databases : void 0,
-		server: new HonoAdapter(app)
+		databases,
+		fixturesRoot: root
 	});
-	runner.cleanup = () => orchestrator.stop();
+	runner.cleanup = async () => {
+		if (orchestrator) await orchestrator.stop();
+	};
 	runner.orchestrator = orchestrator;
 	return runner;
 }
+//#endregion
+//#region src/adapters/fetch.adapter.ts
+/**
+* Server adapter for real HTTP — sends actual fetch requests.
+* Used by e2e() specification runner.
+*/
+var FetchAdapter = class {
+	baseUrl;
+	constructor(url) {
+		this.baseUrl = url.replace(/\/$/, "");
+	}
+	async request(method, path, body) {
+		const init = {
+			method,
+			headers: { "Content-Type": "application/json" }
+		};
+		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 headers = {};
+		response.headers.forEach((value, key) => {
+			headers[key] = value;
+		});
+		return {
+			status: response.status,
+			body: responseBody,
+			headers
+		};
+	}
+};
+//#endregion
+//#region src/runner/e2e.ts
 /**
 * Create an E2E specification runner.
 * Starts full docker compose stack. App URL and database auto-detected.
@@ -1333,47 +1307,63 @@ async function e2e(options = {}) {
 	runner.orchestrator = orchestrator;
 	return runner;
 }
+//#endregion
+//#region src/adapters/hono.adapter.ts
 /**
-* Create a CLI specification runner.
-* Runs CLI commands against fixture projects. Optionally starts infrastructure.
-*
-* @example
-* export const spec = await cli({
-*     command: resolve(import.meta.dirname, "../../bin/my-cli.sh"),
-*     root: "../fixtures",
-* });
+* Server adapter for Hono — in-process requests, no real HTTP.
+* Used by integration() specification runner.
 */
-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
+var HonoAdapter = class {
+	app;
+	constructor(app) {
+		this.app = app;
+	}
+	async request(method, path, body) {
+		const init = {
+			method,
+			headers: { "Content-Type": "application/json" }
+		};
+		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 headers = {};
+		response.headers.forEach((value, key) => {
+			headers[key] = value;
 		});
-		await orchestrator.start();
-		database = orchestrator.getDatabase() ?? void 0;
-		const dbMap = orchestrator.getDatabases();
-		databases = dbMap.size > 0 ? dbMap : void 0;
+		return {
+			status: response.status,
+			body: responseBody,
+			headers
+		};
 	}
+};
+//#endregion
+//#region src/runner/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({
-		command: new ExecAdapter(command),
 		database,
-		databases,
-		fixturesRoot: root
+		databases: databases.size > 0 ? databases : void 0,
+		server: new HonoAdapter(app)
 	});
-	runner.cleanup = async () => {
-		if (orchestrator) await orchestrator.stop();
-	};
+	runner.cleanup = () => orchestrator.stop();
 	runner.orchestrator = orchestrator;
 	return runner;
 }
 //#endregion
-//#region src/infrastructure/docker/docker-adapter.ts
+//#region src/docker/docker-adapter.ts
 var DockerAdapter = class {
 	containerId;
 	constructor(containerId) {
@@ -1466,7 +1456,7 @@ function dockerContainer(containerId) {
 	return new DockerAdapter(containerId);
 }
 //#endregion
-//#region src/infrastructure/docker/docker-assertion.ts
+//#region src/docker/docker-assertion.ts
 /** Fluent assertion builder for Docker containers */
 var DockerAssertion = class {
 	container;
@@ -1543,12 +1533,38 @@ var DockerAssertion = class {
 	}
 };
 //#endregion
+//#region src/utilities/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/mocking/mock-of-date.ts
+const mockOfDate = mockdate.default;
+//#endregion
+//#region src/mocking/mock-of.ts
+const mockOf = vitest_mock_extended.mockDeep;
+//#endregion
+exports.DirectoryAccessor = DirectoryAccessor;
 exports.DockerAssertion = DockerAssertion;
 exports.ExecAdapter = ExecAdapter;
 exports.FetchAdapter = FetchAdapter;
 exports.HonoAdapter = HonoAdapter;
 exports.Orchestrator = Orchestrator;
+exports.ResponseAccessor = ResponseAccessor;
+exports.SpecificationBuilder = SpecificationBuilder;
+exports.SpecificationResult = SpecificationResult;
+exports.TableAssertion = TableAssertion;
 exports.cli = cli;
+exports.createSpecificationRunner = createSpecificationRunner;
 exports.dockerContainer = dockerContainer;
 exports.e2e = e2e;
 exports.grep = grep;