@jterrazz/test 7.0.0 → 8.0.0

package/dist/index.d.cts

@@ -1,8 +1,150 @@
-import { a as PostgresOptions, c as IsolationStrategy, i as redis, l as DatabasePort, n as sqlite, o as postgres, r as RedisOptions, s as ServiceHandle, t as SqliteOptions } from "./sqlite.adapter.cjs";
+import { a as PostgresOptions, c as IsolationStrategy, i as redis, l as DatabasePort, n as sqlite, o as postgres, r as RedisOptions, s as ServiceHandle, t as SqliteOptions } from "./sqlite.cjs";
 import { n as InterceptResponse, r as InterceptTrigger } from "./types.cjs";
 import { i as mockOfDate, n as mockOf, r as MockDatePort, t as MockPort } from "./mock-of.cjs";
 
-//#region src/builder/cli/command.port.d.ts
+//#region src/infra/docker/docker.port.d.ts
+/** Abstract interface for interacting with a Docker container (exec, inspect, file I/O). */
+interface DockerContainerPort {
+  /** Execute a command inside the container, return stdout */
+  exec(cmd: string[]): Promise<string>;
+  /** Read a file from inside the container */
+  file(path: string): Promise<{
+    exists: boolean;
+    content: string;
+  }>;
+  /** Check if container is running */
+  isRunning(): Promise<boolean>;
+  /** Get container logs */
+  logs(tail?: number): Promise<string>;
+  /** Get full docker inspect JSON */
+  inspect(): Promise<DockerInspectResult>;
+  /** Check if a file/directory exists */
+  exists(path: string): Promise<boolean>;
+}
+/** Normalized subset of `docker inspect` output for assertion use. */
+interface DockerInspectResult {
+  id: string;
+  name: string;
+  state: {
+    running: boolean;
+    exitCode: number;
+    status: string;
+  };
+  config: {
+    image: string;
+    env: string[];
+  };
+  hostConfig: {
+    memory: number;
+    cpuQuota: number;
+    networkMode: string;
+    mounts: Array<{
+      source: string;
+      destination: string;
+      type: string;
+    }>;
+  };
+  networkSettings: {
+    networks: Record<string, {
+      gateway: string;
+      ipAddress: string;
+    }>;
+  };
+}
+//#endregion
+//#region src/infra/docker/docker-assertion.d.ts
+/**
+ * Fluent assertion builder for Docker containers.
+ * Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
+ */
+declare class DockerAssertion {
+  private container;
+  constructor(container: DockerContainerPort);
+  /** Assert the container is running */
+  toBeRunning(): Promise<this>;
+  /** Assert the container is NOT running / doesn't exist */
+  toNotExist(): Promise<this>;
+  /** Assert a file exists inside the container */
+  toHaveFile(path: string, opts?: {
+    containing?: string;
+  }): Promise<this>;
+  /** Assert a file does NOT exist */
+  toNotHaveFile(path: string): Promise<this>;
+  /** Assert a directory exists */
+  toHaveDirectory(path: string): Promise<this>;
+  /** Assert a mount exists */
+  toHaveMount(destination: string): Promise<this>;
+  /** Assert network mode */
+  toHaveNetwork(mode: string): Promise<this>;
+  /** Assert memory limit */
+  toHaveMemoryLimit(bytes: number): Promise<this>;
+  /** Assert CPU quota */
+  toHaveCpuQuota(quota: number): Promise<this>;
+  /** Execute a command and return output for custom assertions */
+  exec(cmd: string[]): Promise<string>;
+  /** Read a file for custom assertions */
+  readFile(path: string): Promise<string>;
+  /** Get logs for custom assertions */
+  getLogs(tail?: number): Promise<string>;
+}
+//#endregion
+//#region src/infra/orchestrator.d.ts
+interface OrchestratorOptions {
+  services: ServiceHandle[];
+  mode: 'e2e' | 'integration';
+  root?: string;
+  /** Compose project name — used for per-worker stack isolation. */
+  projectName?: string;
+}
+/**
+ * Orchestrator for test infrastructure.
+ * Integration: starts services via testcontainers.
+ * E2E: runs full docker compose up.
+ */
+declare class Orchestrator {
+  private services;
+  private mode;
+  private root;
+  private projectName;
+  private running;
+  private composeStack;
+  private composeHandles;
+  private started;
+  constructor(options: OrchestratorOptions);
+  /**
+   * 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).
+   */
+  start(): Promise<void>;
+  /**
+   * Stop testcontainers (integration mode).
+   */
+  stop(): Promise<void>;
+  /**
+   * Start full docker compose stack (e2e mode).
+   * Auto-detects infra services and creates handles for them.
+   */
+  startCompose(): Promise<void>;
+  /**
+   * Stop docker compose stack (e2e mode).
+   */
+  stopCompose(): Promise<void>;
+  /**
+   * Get a database service by compose name, or the first one if no name given.
+   */
+  getDatabase(serviceName?: string): DatabasePort | null;
+  /**
+   * Get all database services keyed by compose name.
+   */
+  getDatabases(): Map<string, DatabasePort>;
+  /**
+   * Get app URL from compose (e2e mode).
+   */
+  getAppUrl(): null | string;
+}
+//#endregion
+//#region src/spec/modes/cli/command.port.d.ts
 /**
  * Result of executing a CLI command, including exit code and captured output streams.
  */
@@ -39,76 +181,87 @@ interface CommandPort {
   spawn(args: string, cwd: string, options: SpawnOptions, env?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
-//#region src/builder/http/server.port.d.ts
-/**
- * HTTP response returned by a server port, with parsed JSON body.
- */
-interface ServerResponse {
-  /** HTTP status code. */
-  status: number;
-  /** Parsed JSON response body, or null if parsing failed. */
-  body: unknown;
-  /** Response headers as a flat key-value map. */
-  headers: Record<string, string>;
-}
-/**
- * Abstract server interface for specification runners.
- * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
- */
-interface ServerPort {
-  /** Send an HTTP request and return the parsed response. */
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
-}
-//#endregion
-//#region src/builder/common/directory-accessor.d.ts
+//#region src/spec/result/directory.d.ts
 interface DirectorySnapshotOptions {
-  /** Extra path segments to ignore (in addition to default: .git, node_modules, etc.). */
   ignore?: string[];
-  /**
-   * Force update mode regardless of vitest flags / env vars.
-   * `true` writes the fixture, `false` always asserts. Defaults to auto-detect.
-   */
   update?: boolean;
 }
-/**
- * Handle to a directory produced by a specification run.
- * Supports snapshot-based assertions via {@link toMatchFixture} and file listing via {@link files}.
- */
 declare class DirectoryAccessor {
   private absPath;
   private testDir;
   constructor(absPath: string, testDir: string);
-  /**
-   * 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.
-   */
   toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
-  /**
-   * List all files in the directory (recursive, sorted, ignoring defaults).
-   * Useful for ad-hoc assertions when you don't want a full snapshot.
-   */
   files(options?: {
     ignore?: string[];
   }): Promise<string[]>;
 }
 //#endregion
-//#region src/builder/common/response-accessor.d.ts
-/** Accessor for an HTTP response body with file-based assertion support. */
-declare class ResponseAccessor {
-  readonly body: unknown;
-  private testDir;
-  constructor(body: unknown, testDir: string);
+//#region src/spec/result/filesystem.d.ts
+/**
+ * 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>/`.
+ */
+declare class FilesystemAccessor {
+  /** The absolute path of the temporary working directory. */
+  readonly cwd: string;
+  private readonly testDir;
+  constructor(cwd: string, testDir: string);
+  /** List all files (recursively) under the working directory, sorted. */
+  files(options?: {
+    ignore?: string[];
+  }): Promise<string[]>;
   /**
-   * Assert that the response body matches the JSON in `responses/{file}`.
+   * Assert the working directory matches a convention-based fixture tree:
+   * `<test-file-dir>/expected/filesystem/<name>/`.
+   */
+  toMatch(name: string, options?: DirectorySnapshotOptions): Promise<void>;
+}
+//#endregion
+//#region src/spec/result/json.d.ts
+interface JsonSnapshotOptions {
+  update?: boolean;
+}
+/**
+ * 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.
+ */
+declare class JsonAccessor {
+  private readonly rawText;
+  private readonly testDir;
+  private readonly transform?;
+  constructor(rawText: string, testDir: string, transform?: (text: string) => string);
+  /** The parsed JSON value. Throws if the text is not valid JSON. */
+  get value(): unknown;
+  /**
+   * Assert the parsed JSON deep-equals the JSON in the given file on disk.
    *
-   * @example
-   *   result.response.toMatchFile("expected-items.json");
+   * 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(file: string): void;
+  toMatchFile(path: string, options?: JsonSnapshotOptions): void;
+  /**
+   * 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: string, options?: JsonSnapshotOptions): void;
+  private parse;
 }
 //#endregion
-//#region src/builder/common/table-assertion.d.ts
+//#region src/spec/result/table.d.ts
 /** Assertion helper for verifying database table contents after a specification run. */
 declare class TableAssertion {
   private tableName;
@@ -131,79 +284,323 @@ declare class TableAssertion {
   toBeEmpty(): Promise<void>;
 }
 //#endregion
-//#region src/builder/common/result.d.ts
-/** Read-only handle to a single file produced by a CLI action. */
+//#region src/spec/result/result.d.ts
+/** Read-only handle to a single file produced by a spec action. */
 interface FileAccessor {
   /** The UTF-8 text content. Throws if the file does not exist. */
   readonly content: string;
   readonly exists: boolean;
 }
+interface BaseResultOptions {
+  config: SpecificationConfig;
+  testDir: string;
+  workDir?: string;
+}
 /**
- * The outcome of a single specification run.
- * Provides accessors for CLI output, HTTP responses, files, directories, and database tables.
+ * Base result - common accessors available after any action type.
+ * Extended by HttpResult, CliResult, and used directly by JobResult.
  */
-declare class SpecificationResult {
-  private commandResult?;
-  private config;
-  private requestInfo?;
-  private responseData?;
-  private testDir;
-  private workDir?;
+declare class BaseResult {
+  protected config: SpecificationConfig;
+  protected testDir: string;
+  protected workDir?: string;
+  constructor(options: BaseResultOptions);
+  /** Access a directory (relative to the working directory) for snapshot assertions. */
+  directory(path?: string): DirectoryAccessor;
+  /** Access a single file (relative to the working directory) for content assertions. */
+  file(path: string): FileAccessor;
+  /** Access a database table for row-level assertions. */
+  table(tableName: string, options?: {
+    service?: string;
+  }): TableAssertion;
+  private resolveDatabase;
+}
+//#endregion
+//#region src/spec/result/stream.d.ts
+interface StreamSnapshotOptions {
+  update?: boolean;
+}
+/**
+ * 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.
+ */
+declare class StreamAccessor {
+  private readonly streamName;
+  private readonly testDir;
+  private readonly transform?;
+  readonly text: string;
+  constructor(text: string, streamName: string, testDir: string, transform?: (text: string) => string);
+  /**
+   * 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: string, options?: StreamSnapshotOptions): void;
+  /**
+   * 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: string, options?: StreamSnapshotOptions): void;
+  /**
+   * 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: string): void;
+  toString(): string;
+  valueOf(): string;
+}
+//#endregion
+//#region src/spec/modes/cli/container-accessor.d.ts
+/**
+ * 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`.
+ */
+declare class ContainerAccessor {
+  private cachedLogs;
+  private readonly containerId;
+  readonly exists: boolean;
+  private readonly inspectData;
+  readonly running: boolean;
+  readonly status: string;
+  private readonly testDir;
+  private readonly 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(): null | string;
+  constructor(containerId: null | string, inspectData: unknown, testDir: string, transform?: (text: string) => string);
+  /**
+   * Raw `docker inspect` object for this container. Throws if the container
+   * was not captured (i.e. `.exists === false`).
+   */
+  get inspect(): JsonAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stdout(): StreamAccessor;
+  /** Captured logs (stdout+stderr combined for v1). */
+  get stderr(): StreamAccessor;
+  /**
+   * 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: string): FileAccessor;
+  /**
+   * Run a shell command inside the container and get back the same
+   * {@link CliResult} used for host-side executions.
+   */
+  exec(cmd: string): Promise<CliResult>;
+  private requireExists;
+  private loadLogs;
+  private containerExec;
+}
+//#endregion
+//#region src/spec/modes/cli/result.d.ts
+/**
+ * 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.
+ */
+declare class CliResult extends BaseResult {
+  private readonly commandResult;
+  private containersCache;
+  private readonly dockerConfig?;
+  private readonly testRunId?;
+  private readonly transform?;
   constructor(options: {
-    commandResult?: CommandResult;
+    commandResult: CommandResult;
     config: SpecificationConfig;
-    requestInfo?: {
-      body?: unknown;
-      method: string;
-      path: string;
-    };
-    response?: ServerResponse;
+    dockerConfig?: DockerSpecConfig;
     testDir: string;
-    workDir?: string;
+    testRunId?: string;
+    transform?: (text: string) => string;
+    workDir: string;
   });
-  /** The process exit code. Only available after a CLI action. */
+  /** The process exit code. */
   get exitCode(): number;
-  /** The HTTP response status code. Only available after an HTTP action. */
-  get status(): number;
-  /** The captured standard output. Only available after a CLI action. */
-  get stdout(): string;
-  /** The captured standard error. Only available after a CLI action. */
-  get stderr(): string;
+  /** Accessor for the captured standard output with file-based assertions. */
+  get stdout(): StreamAccessor;
+  /** Accessor for the captured standard error with file-based assertions. */
+  get stderr(): StreamAccessor;
+  /** Accessor for parsing stdout as JSON and asserting against JSON fixtures. */
+  get json(): JsonAccessor;
+  /** Accessor for the temporary working directory the command ran in. */
+  get filesystem(): FilesystemAccessor;
+  /**
+   * 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.
+   */
+  container(name: string): ContainerAccessor;
+  /** All captured container IDs. Triggers the same lazy query as `container()`. */
+  get containerIds(): string[];
+  [Symbol.asyncDispose](): Promise<void>;
   /**
    * 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: string): string;
-  /** Access the HTTP response body for assertions. Only available after an HTTP action. */
+  private ensureDockerAware;
+  private loadContainers;
+}
+//#endregion
+//#region src/spec/result/response.d.ts
+/** Accessor for an HTTP response body with file-based assertion support. */
+declare class ResponseAccessor {
+  readonly body: unknown;
+  private testDir;
+  constructor(body: unknown, testDir: string);
+  /**
+   * Assert that the response body matches the JSON in `responses/{file}`.
+   *
+   * @example
+   *   result.response.toMatchFile("expected-items.json");
+   */
+  toMatchFile(file: string): void;
+}
+//#endregion
+//#region src/spec/modes/http/server.port.d.ts
+/**
+ * HTTP response returned by a server port, with parsed JSON body.
+ */
+interface ServerResponse {
+  /** HTTP status code. */
+  status: number;
+  /** Parsed JSON response body, or null if parsing failed. */
+  body: unknown;
+  /** Response headers as a flat key-value map. */
+  headers: Record<string, string>;
+}
+/**
+ * Abstract server interface for specification runners.
+ * Integration mode uses an in-process Hono app; E2E mode uses real HTTP via fetch.
+ */
+interface ServerPort {
+  /** Send an HTTP request and return the parsed response. */
+  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
+}
+//#endregion
+//#region src/spec/modes/http/result.d.ts
+/** Result from an HTTP action (.get(), .post(), .put(), .delete()). */
+declare class HttpResult extends BaseResult {
+  private responseData;
+  constructor(options: {
+    config: SpecificationConfig;
+    response: ServerResponse;
+    testDir: string;
+  });
+  /** The HTTP response status code. */
+  get status(): number;
+  /** Access the HTTP response body for assertions. */
   get response(): ResponseAccessor;
-  /** Access a directory (relative to the working directory) for snapshot assertions. */
-  directory(path?: string): DirectoryAccessor;
-  /** Access a single file (relative to the working directory) for content assertions. */
-  file(path: string): FileAccessor;
-  /** Access a database table for row-level assertions. */
-  table(tableName: string, options?: {
-    service?: string;
-  }): TableAssertion;
-  private resolveDatabase;
 }
 //#endregion
-//#region src/builder/specification-builder.d.ts
+//#region src/spec/builder.d.ts
 /** A named job that can be triggered via .job(). */
 interface JobHandle$1 {
   name: string;
   execute: () => Promise<void>;
 }
+/**
+ * Context passed to a {@link SeedHandler} when a non-SQL seed is dispatched.
+ */
+interface SeedHandlerContext {
+  /** Absolute path of the temporary working directory for the current spec. */
+  cwd: string;
+  /** Absolute path of the test file directory (where `seeds/` lives). */
+  testDir: string;
+}
+/**
+ * Handler invoked for a non-SQL seed entry. The first path segment of the
+ * seed file selects the handler; the handler is given the absolute path of
+ * the source fragment (file or directory) and the working directory to mutate.
+ */
+type SeedHandler = (ctx: SeedHandlerContext, fragmentPath: string) => Promise<void> | void;
+/**
+ * Configuration for the docker() spec mode. When set on
+ * {@link SpecificationConfig}, the CLI runner generates a test-run id, injects
+ * it into the child env under `envVar`, then queries Docker for every
+ * container carrying `testRunLabel=<id>` after the command exits.
+ */
+interface DockerSpecConfig {
+  envVar: string;
+  nameLabel: string;
+  testRunLabel: string;
+}
 /** Adapter configuration passed to the specification runner at setup time. */
 interface SpecificationConfig {
   command?: CommandPort;
   database?: DatabasePort;
   databases?: Map<string, DatabasePort>;
+  dockerConfig?: DockerSpecConfig;
+  /**
+   * Unique id shared by every `.run()` from this runner instance.
+   * Stable for the runner's lifetime so multi-step tests (spawn in
+   * one run, inspect in another) see the same container scope. The
+   * public `createSpecificationRunner` auto-populates this when
+   * `dockerConfig` is present — callers should leave it unset.
+   */
+  dockerTestRunId?: string;
   fixturesRoot?: string;
   jobs?: JobHandle$1[];
+  /**
+   * Pluggable seed handlers for CLI-mode tests. Keys are leading path
+   * segments (e.g. `"spwn.yaml/"`, `"agent/"`). When `.seed(relPath)` is
+   * called with a path whose first segment matches, the handler is invoked
+   * with the full absolute path of the seed fragment under
+   * `<test-file-dir>/seeds/<relPath>`.
+   */
+  seedHandlers?: Record<string, SeedHandler>;
   server?: ServerPort;
+  /**
+   * Optional normaliser applied to CLI stdout/stderr before every
+   * .toMatch / .toMatchFile comparison. Does not mutate the raw
+   * `.text` accessor.
+   */
+  transform?: (text: string) => string;
 }
 /**
  * Fluent builder for declaring a single test specification.
@@ -327,7 +724,8 @@ declare class SpecificationBuilder {
    *   const result = await spec("test").exec("status").run();
    *   expect(result.exitCode).toBe(0);
    */
-  run(): Promise<SpecificationResult>;
+  run(): Promise<BaseResult | CliResult | HttpResult>;
+  private resolveSeedHandler;
   private resolveEnv;
   private prepareWorkDir;
   private runHttpAction;
@@ -342,151 +740,9 @@ type SpecificationRunner = (label: string) => SpecificationBuilder;
  */
 declare function createSpecificationRunner(config: SpecificationConfig): SpecificationRunner;
 //#endregion
-//#region src/docker/docker-port.d.ts
-/** Abstract interface for interacting with a Docker container (exec, inspect, file I/O). */
-interface DockerContainerPort {
-  /** Execute a command inside the container, return stdout */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file from inside the container */
-  file(path: string): Promise<{
-    exists: boolean;
-    content: string;
-  }>;
-  /** Check if container is running */
-  isRunning(): Promise<boolean>;
-  /** Get container logs */
-  logs(tail?: number): Promise<string>;
-  /** Get full docker inspect JSON */
-  inspect(): Promise<DockerInspectResult>;
-  /** Check if a file/directory exists */
-  exists(path: string): Promise<boolean>;
-}
-/** Normalized subset of `docker inspect` output for assertion use. */
-interface DockerInspectResult {
-  id: string;
-  name: string;
-  state: {
-    running: boolean;
-    exitCode: number;
-    status: string;
-  };
-  config: {
-    image: string;
-    env: string[];
-  };
-  hostConfig: {
-    memory: number;
-    cpuQuota: number;
-    networkMode: string;
-    mounts: Array<{
-      source: string;
-      destination: string;
-      type: string;
-    }>;
-  };
-  networkSettings: {
-    networks: Record<string, {
-      gateway: string;
-      ipAddress: string;
-    }>;
-  };
-}
-//#endregion
-//#region src/docker/docker-assertion.d.ts
-/**
- * Fluent assertion builder for Docker containers.
- * Chain async assertions like `toBeRunning()`, `toHaveFile()`, `toHaveMount()`.
- */
-declare class DockerAssertion {
-  private container;
-  constructor(container: DockerContainerPort);
-  /** Assert the container is running */
-  toBeRunning(): Promise<this>;
-  /** Assert the container is NOT running / doesn't exist */
-  toNotExist(): Promise<this>;
-  /** Assert a file exists inside the container */
-  toHaveFile(path: string, opts?: {
-    containing?: string;
-  }): Promise<this>;
-  /** Assert a file does NOT exist */
-  toNotHaveFile(path: string): Promise<this>;
-  /** Assert a directory exists */
-  toHaveDirectory(path: string): Promise<this>;
-  /** Assert a mount exists */
-  toHaveMount(destination: string): Promise<this>;
-  /** Assert network mode */
-  toHaveNetwork(mode: string): Promise<this>;
-  /** Assert memory limit */
-  toHaveMemoryLimit(bytes: number): Promise<this>;
-  /** Assert CPU quota */
-  toHaveCpuQuota(quota: number): Promise<this>;
-  /** Execute a command and return output for custom assertions */
-  exec(cmd: string[]): Promise<string>;
-  /** Read a file for custom assertions */
-  readFile(path: string): Promise<string>;
-  /** Get logs for custom assertions */
-  getLogs(tail?: number): Promise<string>;
-}
-//#endregion
-//#region src/infra/orchestrator.d.ts
-interface OrchestratorOptions {
-  services: ServiceHandle[];
-  mode: 'e2e' | 'integration';
-  root?: string;
-  /** Compose project name — used for per-worker stack isolation. */
-  projectName?: string;
-}
-/**
- * Orchestrator for test infrastructure.
- * Integration: starts services via testcontainers.
- * E2E: runs full docker compose up.
- */
-declare class Orchestrator {
-  private services;
-  private mode;
-  private root;
-  private projectName;
-  private running;
-  private composeStack;
-  private composeHandles;
-  private started;
-  constructor(options: OrchestratorOptions);
-  /**
-   * 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).
-   */
-  start(): Promise<void>;
-  /**
-   * Stop testcontainers (integration mode).
-   */
-  stop(): Promise<void>;
-  /**
-   * Start full docker compose stack (e2e mode).
-   * Auto-detects infra services and creates handles for them.
-   */
-  startCompose(): Promise<void>;
-  /**
-   * Stop docker compose stack (e2e mode).
-   */
-  stopCompose(): Promise<void>;
-  /**
-   * Get a database service by compose name, or the first one if no name given.
-   */
-  getDatabase(serviceName?: string): DatabasePort | null;
-  /**
-   * Get all database services keyed by compose name.
-   */
-  getDatabases(): Map<string, DatabasePort>;
-  /**
-   * Get app URL from compose (e2e mode).
-   */
-  getAppUrl(): null | string;
-}
-//#endregion
 //#region src/spec/targets.d.ts
 /** Any object with a request method compatible with Hono's app.request(). */
-type HonoApp$1 = {
+type HonoApp = {
   request: (path: string, init?: RequestInit) => Promise<Response> | Response;
 };
 /** A named job that can be triggered via .job(). */
@@ -500,8 +756,8 @@ type AppServices = Record<string, ServiceHandle>;
  * Return value from the app() factory. Either a bare server (backward compat)
  * or an object with server + jobs for job-based testing.
  */
-type AppFactoryResult = HonoApp$1 | {
-  server: HonoApp$1;
+type AppFactoryResult = HonoApp | {
+  server: HonoApp;
   jobs: JobHandle[];
 };
 /** In-process Hono app target. Created by {@link app}. */
@@ -536,7 +792,7 @@ type SpecTarget = AppTarget | CommandTarget | StackTarget;
  *       { services: [db] },
  *   );
  */
-declare function app(factory: (services: AppServices) => HonoApp$1): AppTarget;
+declare function app(factory: (services: AppServices) => HonoApp): AppTarget;
 /**
  * Test against a full docker compose stack. The stack is started with
  * `docker compose up` and real HTTP requests are sent to the app service.
@@ -550,20 +806,67 @@ declare function stack(root: string): StackTarget;
 /**
  * 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',
+ *       },
+ *   });
  */
 declare function command(bin: string): CommandTarget;
 //#endregion
 //#region src/spec/spec.d.ts
 /** Shared options for all spec targets. */
 interface SpecOptions {
+  /**
+   * Opt-in Docker awareness for CLI-mode runners. When set, every
+   * `.run()` generates a unique test-run id, injects it into the
+   * child process env under `envVar`, and exposes `.container(name)`
+   * accessors on the result that lazily query Docker. A test that
+   * never calls `.container(...)` never touches the Docker daemon —
+   * CLI-only and container-asserting tests share one runner.
+   *
+   * Always wrap calls that may spawn containers with `await using`
+   * so leaked containers get force-removed at scope exit (the
+   * runner cleans up by label filter).
+   */
+  docker?: DockerSpecConfig;
   /** Project root for fixture lookup and compose detection (relative paths supported). */
   root?: string;
+  /**
+   * Pluggable seed handlers for CLI-mode tests. Keys are leading path
+   * segments (e.g. `"spwn.yaml/"`); values receive the seed context and the
+   * absolute path of the source fragment under `<test-file-dir>/seeds/`.
+   */
+  seedHandlers?: Record<string, SeedHandler>;
   /** Infrastructure services to start via testcontainers. */
   services?: ServiceHandle[];
+  /**
+   * Optional normaliser applied to result.stdout.text and
+   * result.stderr.text before every .toMatch / .toMatchFile
+   * comparison. Useful for stripping ANSI codes, masking
+   * machine-specific paths, scrubbing timestamps, etc.
+   *
+   * The transform does NOT mutate the raw `.text` accessor —
+   * callers can still inspect the pristine output.
+   */
+  transform?: (text: string) => string;
 }
 /** A specification runner with teardown support and orchestrator access. */
 interface SpecRunner {
@@ -599,7 +902,15 @@ interface SpecRunner {
  */
 declare function spec(target: SpecTarget, options?: SpecOptions): Promise<SpecRunner>;
 //#endregion
-//#region src/infra/ports/container.port.d.ts
+//#region src/spec/modes/cli/docker-lookup.d.ts
+/** Return all container IDs (running or stopped) that carry `key=value`. */
+declare function findContainersByLabel(key: string, value: string): string[];
+/** Return the raw `docker inspect` payload (object, not array) for a container. */
+declare function inspectContainer(id: string): unknown;
+/** Force-remove the given container IDs in a single call. Errors are swallowed. */
+declare function removeContainers(ids: string[]): void;
+//#endregion
+//#region src/infra/containers/container.port.d.ts
 /**
  * Abstract container interface.
  * Represents a running service (database, cache, etc.)
@@ -619,11 +930,16 @@ interface ContainerPort {
   getLogs(): Promise<string>;
 }
 //#endregion
-//#region src/builder/cli/adapters/exec.adapter.d.ts
+//#region src/spec/modes/cli/adapters/exec.adapter.d.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.
+ * 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.
  */
 declare class ExecAdapter implements CommandPort {
   private command;
@@ -632,7 +948,7 @@ declare class ExecAdapter implements CommandPort {
   spawn(args: string, cwd: string, options: SpawnOptions, extraEnv?: CommandEnv): Promise<CommandResult>;
 }
 //#endregion
-//#region src/builder/http/adapters/fetch.adapter.d.ts
+//#region src/spec/modes/http/adapters/fetch.adapter.d.ts
 /**
  * Server adapter that sends real HTTP requests via the Fetch API.
  * Used by the `e2e()` specification runner to hit a live server.
@@ -643,7 +959,7 @@ declare class FetchAdapter implements ServerPort {
   request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
 }
 //#endregion
-//#region src/builder/http/adapters/hono.adapter.d.ts
+//#region src/spec/modes/http/adapters/hono.adapter.d.ts
 /**
  * Server adapter that dispatches requests in-process through a Hono app instance.
  * Used by the `integration()` specification runner -- no network overhead.
@@ -656,79 +972,9 @@ declare class HonoAdapter implements ServerPort {
   request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
 }
 //#endregion
-//#region src/spec/legacy-integration.d.ts
-type HonoApp = {
-  fetch: (...args: any[]) => any;
-  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-};
-interface IntegrationOptions {
-  /** Factory that returns a Hono app — called after services start. */
-  app: () => HonoApp;
-  /** Project root for compose detection (relative paths supported). */
-  root?: string;
-  /** Declared services — started via testcontainers. */
-  services: ServiceHandle[];
-}
-/** A specification runner that also exposes teardown and the underlying orchestrator. */
-interface SpecificationRunnerWithCleanup extends SpecificationRunner {
-  /** Stop all infrastructure containers started by this runner. */
-  cleanup: () => Promise<void>;
-  /** The orchestrator managing the test infrastructure lifecycle. */
-  orchestrator: Orchestrator;
-}
-/**
- * Create an integration specification runner.
- * Starts infra containers via testcontainers, app runs in-process.
- */
-declare function integration(options: IntegrationOptions): Promise<SpecificationRunnerWithCleanup>;
-//#endregion
-//#region src/spec/legacy-cli.d.ts
-interface CliOptions {
-  /** CLI command to run (resolved from node_modules/.bin or PATH). */
-  command: string;
-  /** Project root — base dir for .project() fixture lookup (relative paths supported). */
-  root?: string;
-  /** Optional infrastructure services (started via testcontainers). */
-  services?: ServiceHandle[];
-}
-/**
- * Create a CLI specification runner.
- * Runs CLI commands against fixture projects. Optionally starts infrastructure.
- */
-declare function cli(options: CliOptions): Promise<SpecificationRunnerWithCleanup>;
-//#endregion
-//#region src/spec/legacy-e2e.d.ts
-interface E2eOptions {
-  /** Project root — must contain docker/compose.test.yaml. */
-  root?: string;
-}
-/**
- * Create an E2E specification runner.
- * Starts full docker compose stack. App URL and database auto-detected.
- */
-declare function e2e(options?: E2eOptions): Promise<SpecificationRunnerWithCleanup>;
-//#endregion
-//#region src/builder/common/grep.d.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")
- */
-declare function grep(output: string, pattern: string): string;
-//#endregion
-//#region src/builder/common/reporter.d.ts
-/** Strip ANSI escape codes from a string. */
-declare function stripAnsi(str: string): string;
-/** Strip ANSI codes and replace volatile tokens (ports, durations) with placeholders. */
-declare function normalizeOutput(str: string): string;
-//#endregion
-//#region src/docker/docker-adapter.d.ts
+//#region src/infra/docker/docker.d.ts
 /** Create a {@link DockerContainerPort} bound to an existing container by ID. */
 declare function dockerContainer(containerId: string): DockerContainerPort;
 //#endregion
-export { type AppFactoryResult, type AppServices, type AppTarget, type CliOptions, type CommandEnv, type CommandPort, type CommandResult, type CommandTarget, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type E2eOptions, ExecAdapter, FetchAdapter, type FileAccessor, HonoAdapter, type HttpTarget, type IntegrationOptions, type IsolationStrategy, type JobHandle, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, type SpecOptions, type SpecRunner, type SpecTarget, SpecificationBuilder, type SpecificationConfig, SpecificationResult, type SpecificationRunner, type SpecificationRunnerWithCleanup, type SqliteOptions, type StackTarget, TableAssertion, app, cli, command, createSpecificationRunner, dockerContainer, e2e, grep, integration, mockOf, mockOfDate, normalizeOutput, postgres, redis, spec, sqlite, stack, stripAnsi };
+export { type AppFactoryResult, type AppServices, type AppTarget, BaseResult, CliResult, type CommandEnv, type CommandPort, type CommandResult, type CommandTarget, ContainerAccessor, type ContainerPort, type DatabasePort, DirectoryAccessor, type DirectorySnapshotOptions, DockerAssertion, type DockerContainerPort, type DockerInspectResult, type DockerSpecConfig, ExecAdapter, FetchAdapter, type FileAccessor, FilesystemAccessor, HonoAdapter, HttpResult, type HttpTarget, type IsolationStrategy, type JobHandle, JsonAccessor, type JsonSnapshotOptions, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type SeedHandler, type SeedHandlerContext, type ServerPort, type ServerResponse, type ServiceHandle, type SpawnOptions, type SpecOptions, type SpecRunner, type SpecTarget, SpecificationBuilder, type SpecificationConfig, type SpecificationRunner, type SqliteOptions, type StackTarget, StreamAccessor, type StreamSnapshotOptions, TableAssertion, app, command, createSpecificationRunner, dockerContainer, findContainersByLabel, inspectContainer, mockOf, mockOfDate, postgres, redis, removeContainers, spec, sqlite, stack };
 //# sourceMappingURL=index.d.cts.map