@jterrazz/test 8.0.0 → 9.0.0

package/dist/index.d.cts

@@ -1,980 +0,0 @@
-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/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.
- */
-interface CommandResult {
-  /** Process exit code (0 = success). */
-  exitCode: number;
-  /** Captured standard output. */
-  stdout: string;
-  /** Captured standard error. */
-  stderr: string;
-}
-/**
- * Options for spawning a long-running process.
- */
-interface SpawnOptions {
-  /** Resolve when stdout/stderr contains this string. */
-  waitFor: string;
-  /** Kill the process after this many milliseconds. */
-  timeout: number;
-}
-/**
- * Extra environment variables to set for the child process.
- * Values are merged on top of process.env. A `null` value unsets the variable.
- */
-type CommandEnv = Record<string, null | string>;
-/**
- * Abstract CLI interface for specification runners.
- * Implement this to plug in your command execution strategy.
- */
-interface CommandPort {
-  /** Execute a CLI command with the given arguments in the given working directory. */
-  exec(args: string, cwd: string, env?: CommandEnv): Promise<CommandResult>;
-  /** Spawn a long-running process and wait for a pattern or timeout. */
-  spawn(args: string, cwd: string, options: SpawnOptions, env?: CommandEnv): Promise<CommandResult>;
-}
-//#endregion
-//#region src/spec/result/directory.d.ts
-interface DirectorySnapshotOptions {
-  ignore?: string[];
-  update?: boolean;
-}
-declare class DirectoryAccessor {
-  private absPath;
-  private testDir;
-  constructor(absPath: string, testDir: string);
-  toMatchFixture(name: string, options?: DirectorySnapshotOptions): Promise<void>;
-  files(options?: {
-    ignore?: string[];
-  }): Promise<string[]>;
-}
-//#endregion
-//#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 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.
-   *
-   * Path is resolved relative to the test file directory unless absolute.
-   * If `JTERRAZZ_TEST_UPDATE=1` (or vitest `-u`), the file is (re)written
-   * with the pretty-printed parsed value.
-   */
-  toMatchFile(path: 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/spec/result/table.d.ts
-/** Assertion helper for verifying database table contents after a specification run. */
-declare class TableAssertion {
-  private tableName;
-  private db;
-  constructor(tableName: string, db: DatabasePort);
-  /**
-   * Assert that the table contains exactly the expected rows for the given columns.
-   *
-   * @example
-   *   await result.table("users").toMatch({
-   *     columns: ["name", "email"],
-   *     rows: [["Alice", "alice@example.com"]],
-   *   });
-   */
-  toMatch(expected: {
-    columns: string[];
-    rows: unknown[][];
-  }): Promise<void>;
-  /** Assert that the table has zero rows. */
-  toBeEmpty(): Promise<void>;
-}
-//#endregion
-//#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;
-}
-/**
- * Base result - common accessors available after any action type.
- * Extended by HttpResult, CliResult, and used directly by JobResult.
- */
-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;
-    config: SpecificationConfig;
-    dockerConfig?: DockerSpecConfig;
-    testDir: string;
-    testRunId?: string;
-    transform?: (text: string) => string;
-    workDir: string;
-  });
-  /** The process exit code. */
-  get exitCode(): number;
-  /** 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.
-   *
-   * @example
-   *   expect(result.grep('error.ts')).toContain('no-unused-vars');
-   */
-  grep(pattern: string): string;
-  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;
-}
-//#endregion
-//#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.
- *
- * Chain setup methods ({@link seed}, {@link fixture}, {@link env}), an action
- * ({@link get}, {@link post}, {@link exec}), then call {@link run} to execute
- * and receive a {@link SpecificationResult} for assertions.
- */
-declare class SpecificationBuilder {
-  private commandArgs;
-  private commandEnv;
-  private config;
-  private fixtures;
-  private intercepts;
-  private jobName;
-  private label;
-  private mocks;
-  private projectName;
-  private request;
-  private requestHeaders;
-  private seeds;
-  private spawnConfig;
-  private testDir;
-  constructor(config: SpecificationConfig, testDir: string, label: string);
-  /**
-   * Queue a SQL seed file to run before the action.
-   *
-   * @example
-   *   spec("creates user").seed("users.sql").exec("list-users").run();
-   */
-  seed(file: string, options?: {
-    service?: string;
-  }): this;
-  /** Copy a file or directory from `fixtures/` into the working directory before execution. */
-  fixture(file: string): this;
-  /** Copy an entire project fixture from `fixturesRoot` into the working directory. */
-  project(name: string): this;
-  /** Register an MSW mock definition file from `mock/` to intercept HTTP calls. */
-  mock(file: string): 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: CommandEnv): this;
-  /**
-   * Set HTTP headers for the request. Multiple calls merge.
-   *
-   * @example
-   *   spec("french").headers({ 'Accept-Language': 'fr' }).get("/articles").run();
-   */
-  headers(headers: Record<string, string>): this;
-  /**
-   * Intercept an outgoing HTTP request and return a controlled response.
-   * Uses MSW under the hood. Intercepts are queued — multiple calls with the
-   * same trigger fire sequentially (first match consumed first).
-   *
-   * @param trigger - What to match (use openai.agent(), http.get(), etc.)
-   * @param response - What to return: an InterceptResponse object, or a filename
-   *   from `intercepts/` (JSON loaded and auto-wrapped by the trigger).
-   *
-   * @example
-   *   // With inline response
-   *   .intercept(openai.agent({...}), openai.reply({ categories: ['TECH'] }))
-   *
-   *   // With JSON fixture file (loaded from intercepts/ directory)
-   *   .intercept(openai.agent({...}), 'ingest-tech.json')
-   *   .intercept(http.get(url), 'world-news-tech.json')
-   */
-  intercept(trigger: InterceptTrigger, response: InterceptResponse | string): this;
-  /**
-   * Send a GET request to the server adapter.
-   *
-   * @example
-   *   spec("list items").get("/api/items").run();
-   */
-  get(path: string): this;
-  /**
-   * Send a POST request to the server adapter.
-   *
-   * @param bodyFile - Optional JSON file from `requests/` to use as the request body.
-   * @example
-   *   spec("create item").post("/api/items", "new-item.json").run();
-   */
-  post(path: string, bodyFile?: string): this;
-  /** Send a PUT request to the server adapter. */
-  put(path: string, bodyFile?: string): this;
-  /** Send a DELETE request to the server adapter. */
-  delete(path: string): this;
-  /**
-   * Execute a CLI command (or a sequence of commands) in an isolated working directory.
-   * When an array is passed, commands run sequentially and stop on the first non-zero exit code.
-   *
-   * @example
-   *   spec("init project").exec("init --name demo").run();
-   *   spec("multi-step").exec(["init", "build"]).run();
-   */
-  exec(args: string | string[]): this;
-  /** Spawn a long-running CLI process with custom spawn options (e.g. timeout, signal). */
-  spawn(args: string, options: SpawnOptions): this;
-  /**
-   * Execute a named job registered via the app() factory.
-   *
-   * @param name - The job name to trigger (must match a registered JobHandle.name).
-   *
-   * @example
-   *   spec('pipeline').intercept(openai.chat(), openai.response({...})).job('report-refresh').run();
-   */
-  job(name: string): this;
-  /**
-   * Execute the specification: run seeds, copy fixtures, then perform the
-   * configured action (HTTP or CLI).
-   *
-   * @returns The result object used for assertions.
-   * @example
-   *   const result = await spec("test").exec("status").run();
-   *   expect(result.exitCode).toBe(0);
-   */
-  run(): Promise<BaseResult | CliResult | HttpResult>;
-  private resolveSeedHandler;
-  private resolveEnv;
-  private prepareWorkDir;
-  private runHttpAction;
-  private runJobAction;
-  private runCliAction;
-}
-/** Factory function returned by `cli()`, `integration()`, or `e2e()` that starts a new spec. */
-type SpecificationRunner = (label: string) => SpecificationBuilder;
-/**
- * Create a {@link SpecificationRunner} bound to the given adapter configuration.
- * The test file directory is auto-detected from the call stack.
- */
-declare function createSpecificationRunner(config: SpecificationConfig): SpecificationRunner;
-//#endregion
-//#region src/spec/targets.d.ts
-/** Any object with a request method compatible with Hono's app.request(). */
-type HonoApp = {
-  request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-};
-/** A named job that can be triggered via .job(). */
-interface JobHandle {
-  name: string;
-  execute: () => Promise<void>;
-}
-/** Services map passed to the app factory after infrastructure starts. */
-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 | {
-  server: HonoApp;
-  jobs: JobHandle[];
-};
-/** In-process Hono app target. Created by {@link app}. */
-interface AppTarget {
-  readonly kind: 'app';
-  readonly factory: (services: AppServices) => AppFactoryResult;
-}
-/** Docker compose stack target. Created by {@link stack}. */
-interface StackTarget {
-  readonly kind: 'stack';
-  readonly root: string;
-}
-/** CLI command target. Created by {@link command}. */
-interface CommandTarget {
-  readonly kind: 'command';
-  readonly bin: string;
-}
-/** Any target that produces an HTTP interface (app or stack). */
-type HttpTarget = AppTarget | StackTarget;
-/** Any valid spec target. */
-type SpecTarget = AppTarget | CommandTarget | StackTarget;
-/**
- * Test against an in-process Hono app. The factory receives started services
- * so you can wire connection strings into your app/DI container.
- *
- * @param factory - Function that receives services and returns a Hono app instance.
- *
- * @example
- *   const db = postgres({ compose: 'db' });
- *   await spec(
- *       app((services) => createApp({ databaseUrl: services.db.connectionString })),
- *       { services: [db] },
- *   );
- */
-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.
- *
- * @param root - Project root containing `docker/compose.test.yaml`.
- *
- * @example
- *   await spec(stack('../../'));
- */
-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 {
-  /** The function to create individual specs: `runner('label').get('/path').run()`. */
-  (label: string): SpecificationBuilder;
-  /** Stop all infrastructure started by this runner. */
-  cleanup: () => Promise<void>;
-  /**
-   * Get a Docker assertion builder for a running container.
-   *
-   * @example
-   *   await runner.docker('my-container').toBeRunning();
-   */
-  docker: (containerId: string) => DockerAssertion;
-  /** The orchestrator managing the test infrastructure lifecycle. */
-  orchestrator: Orchestrator;
-}
-/**
- * Create a specification runner for the given target.
- *
- * @param target - What to test against: {@link app}, {@link stack}, or {@link command}.
- * @param options - Shared options: root directory, infrastructure services.
- *
- * @example
- *   // HTTP — in-process app with testcontainers
- *   const s = await spec(app(() => createApp(db)), { services: [db] });
- *
- *   // HTTP — full docker compose stack
- *   const s = await spec(stack('../../'));
- *
- *   // CLI — command binary
- *   const s = await spec(command('my-cli'), { root: '../fixtures' });
- */
-declare function spec(target: SpecTarget, options?: SpecOptions): Promise<SpecRunner>;
-//#endregion
-//#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.)
- */
-interface ContainerPort {
-  /** Start the container and wait until ready. */
-  start(): Promise<void>;
-  /** Stop and remove the container. */
-  stop(): Promise<void>;
-  /** Get the mapped host port for a container port. */
-  getMappedPort(containerPort: number): number;
-  /** Get the host to connect to. */
-  getHost(): string;
-  /** Get a full connection string for this service. */
-  getConnectionString(): string;
-  /** Get container logs (stdout + stderr). */
-  getLogs(): Promise<string>;
-}
-//#endregion
-//#region src/spec/modes/cli/adapters/exec.adapter.d.ts
-/**
- * Executes CLI commands via Node.js child_process.
- * Uses `spawnSync` for one-shot commands and `spawn` for long-running processes.
- * Used by the command() specification runner.
- *
- * `spawnSync` is used (over the simpler `execSync`) so stdout AND stderr are
- * captured regardless of exit code. Many CLIs follow the Unix convention of
- * writing status banners to stderr on success — `execSync` would silently
- * discard them, leaving snapshot tests with no output to assert on.
- */
-declare class ExecAdapter implements CommandPort {
-  private command;
-  constructor(command: string);
-  exec(args: string, cwd: string, extraEnv?: CommandEnv): Promise<CommandResult>;
-  spawn(args: string, cwd: string, options: SpawnOptions, extraEnv?: CommandEnv): Promise<CommandResult>;
-}
-//#endregion
-//#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.
- */
-declare class FetchAdapter implements ServerPort {
-  private baseUrl;
-  constructor(url: string);
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
-}
-//#endregion
-//#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.
- */
-declare class HonoAdapter implements ServerPort {
-  private app;
-  constructor(app: {
-    request: (path: string, init?: RequestInit) => Promise<Response> | Response;
-  });
-  request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<ServerResponse>;
-}
-//#endregion
-//#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, 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