@jterrazz/test 16.1.0 → 17.0.0

package/dist/shared-index.services.d.ts

@@ -0,0 +1,346 @@
+import { t as ContainerOptions } from "./shared-container.port.js";
+//#region src/chain/config.d.ts
+type ChainConfig = {
+  root?: string | undefined;
+};
+//#endregion
+//#region src/chain/context/with.capability.d.ts
+/** Merged over `process.env`; a `null` value unsets the variable. */
+type EnvRecord = Record<string, null | string>;
+/** What a file shares on every chain it starts: settings, never state. */
+type ChainContext = {
+  /** The instant every chain pins; a chain's own `.clock()` wins. */
+  clock?: string;
+  /** The environment every command runs with; a chain's own `.env()` merges over it. */
+  env?: EnvRecord;
+  /** The headers every request carries; a chain's own `.headers()` merges over them. */
+  headers?: Record<string, string>;
+};
+//#endregion
+//#region src/chain/capability.d.ts
+type MatrixGroup = 'Constructor option' | 'Result accessor' | 'Route option' | 'Setup' | 'Target' | 'Terminal action' | 'Verb';
+/** `probe` is a call in `lint/self/corpus/matrix-calls.ts`'s grammar, or a literal. */
+type MatrixRow = {
+  readonly group: MatrixGroup;
+  readonly member?: string;
+  readonly name: string;
+  readonly probe: string;
+};
+type ContextKey = keyof ChainContext;
+type Intersect<Union> = (Union extends unknown ? (member: Union) => void : never) extends ((all: infer All) => void) ? All : never;
+type SpecificationParams = {
+  readonly databaseKey: string;
+  readonly services: Record<string, unknown>;
+};
+/** Each definition extends this, naming its methods over `this['self']` and `this['params']`; `ChainOf` fills both in. */
+interface ChainSignature {
+  readonly chain: object;
+  readonly params: SpecificationParams;
+  readonly self: unknown;
+}
+type Armed = {
+  /** Released in reverse arm order; an adapter may defer it to the test's end. */
+  readonly release?: () => void;
+  /** Preferred over the action's own error. */
+  readonly violation?: () => Error | null;
+};
+type Run<Config extends ChainConfig = ChainConfig> = {
+  readonly config: Config;
+  readonly testDir: string;
+  readonly workDir: null | string;
+};
+type SetupContext<Needs, Config extends ChainConfig = ChainConfig> = {
+  readonly config: Config;
+  readonly adapters: Needs;
+};
+type Capability<Name extends string, Slice, Args extends readonly unknown[], Signature extends ChainSignature = ChainSignature, Needs extends object = Record<never, never>, Context extends ContextKey = never, Config extends ChainConfig = ChainConfig> = {
+  readonly context?: Context;
+  readonly initial: Slice;
+  readonly kind: 'setup';
+  readonly name: Name;
+  /** Arm order across the setups of a chain: a lower phase arms first, and each setup states its own. */
+  readonly phase: number;
+  readonly row: MatrixRow;
+  /** A type alone, never set at runtime: `ChainOf` reads it. */
+  readonly signature?: Signature;
+  /** Absent when the action reads the slice instead. */
+  arm?(slice: Slice, adapters: Needs, run: Run<Config>): Armed | Promise<Armed | undefined> | undefined;
+  reduce(slice: Slice, args: Args, setup: SetupContext<Needs, Config>): Slice;
+};
+type AnyCapability = Capability<string, unknown, readonly unknown[], ChainSignature, object, ContextKey>;
+type ActionOption<Name extends string> = {
+  readonly kind: 'option';
+  readonly name: Name;
+  readonly row: MatrixRow;
+};
+type Sharing = {
+  readonly kind: 'context';
+  readonly name: 'with';
+  readonly row: MatrixRow;
+};
+//#endregion
+//#region src/services/database.port.d.ts
+/** Database port for specification runners; implement it to plug in your stack. */
+type DatabasePort = {
+  /** Execute raw SQL (for seeding test data). */
+  seed: (sql: string) => Promise<void>;
+  /** Query a table and return rows as arrays of values. */
+  query: (table: string, columns: string[]) => Promise<unknown[][]>;
+  /** The table's columns, in the order the table declares them: what a whole-table comparison reads. */
+  columns: (table: string) => Promise<string[]>;
+  /** Reset database to clean state between tests. */
+  reset: () => Promise<void>;
+};
+//#endregion
+//#region src/services/isolation.port.d.ts
+/** Isolates service state across parallel workers: `acquire()` per worker, `reset()` per run, `release()` at shutdown. */
+type IsolationStrategy = {
+  /** Create this worker's isolated namespace, once at worker start. */
+  acquire: (workerId: string) => Promise<void>;
+  /** Fast reset within the namespace between runs. */
+  reset: () => Promise<void>;
+  /** Tear down the namespace, once at worker shutdown. */
+  release: () => Promise<void>;
+};
+//#endregion
+//#region src/services/service.port.d.ts
+/** A service handle, as `postgres()` or `redis()` return it; `connectionString` fills in once started. */
+type ServiceHandle = {
+  readonly type: string;
+  /** The kebab-case record key, assigned at start: `{ analyticsDb: postgres() }` reads `docker/analytics-db/`. */
+  serviceName: null | string;
+  /** Default container port for this service type. */
+  readonly defaultPort: number;
+  /** Default Docker image for this service type. */
+  readonly defaultImage: string;
+  /** Environment variables to pass to the container. */
+  readonly environment: Record<string, string>;
+  /** How the container runs beyond its image, port and environment; none when absent. */
+  readonly containerOptions?: ContainerOptions;
+  /** Connection string, populated after start. */
+  connectionString: string;
+  /** Build the connection string from host and port. */
+  buildConnectionString: (host: string, port: number) => string;
+  /** Create a DatabasePort adapter (if this is a database). Returns null otherwise. */
+  createDatabaseAdapter: () => DatabasePort | null;
+  /** Verify the service is ready and accepting connections. Throws with context if not. */
+  healthcheck: () => Promise<void>;
+  /** Run the init scripts from `<root>/docker/<name>/`; a cache goes under `<root>/.artifacts/`, never a machine-global directory. */
+  initialize: (dockerDir: string, root: string) => Promise<void>;
+  /** Reset state between tests (truncate tables, flush cache, etc.) */
+  reset: () => Promise<void>;
+  isolation: () => IsolationStrategy;
+};
+//#endregion
+//#region src/services/services.d.ts
+/** Services declared as a named record: the keys are the spec's database vocabulary. */
+type ServiceRecord = Record<string, ServiceHandle>;
+/** Keys of a services record whose handles are databases. */
+type DatabaseKeys<Services extends ServiceRecord> = { [K in keyof Services]: Services[K] extends DatabasePort ? K & string : never; }[keyof Services];
+type ServicesConfig = ChainConfig & {
+  database?: DatabasePort | undefined;
+  /** Drives `database-named-only-when-several-at-runtime`: with 2+ databases `database` is required on `.seed()` / `.table()`, with one it is refused. */
+  databaseKeys?: string[] | undefined;
+  databases?: Map<string, DatabasePort> | undefined;
+  /** In cli mode, drives the `<KEY>_URL` injection (`service-urls-injected`), plus `DATABASE_URL` / `REDIS_URL` when unambiguous. */
+  services?: Record<string, ServiceHandle> | undefined;
+};
+//#endregion
+//#region src/disk/spec-path.d.ts
+/** A path relative to the spec file; `Extension` narrows its tail. */
+type RelativePath<Extension extends string = string> = `../${string}${Extension}` | `./${string}${Extension}`;
+declare const DISK: unique symbol;
+/** A file the spec names, at `Path`. */
+type FileAt<Path extends string> = {
+  readonly [DISK]: 'file';
+  readonly path: Path;
+};
+/** A file whose path ends in `Extension`: what a verb that reads one file accepts. */
+type DiskFile<Extension extends string = string> = FileAt<RelativePath<Extension>>;
+/** A directory the spec names; its path ends in `/`. */
+type DiskDirectory = {
+  readonly [DISK]: 'directory';
+  readonly path: RelativePath<'/'>;
+};
+/** Either of the two: what a verb that takes a file or a directory accepts. */
+type DiskTarget = DiskDirectory | DiskFile;
+/** Name one file, by its path from the spec file. */
+declare function file<const Path extends RelativePath>(path: Path extends `${string}/` ? never : Path): FileAt<Path>;
+/** Name one directory, by its path from the spec file, ending in `/`. */
+declare function directory<const Path extends RelativePath<'/'>>(path: Path): DiskDirectory & {
+  readonly path: Path;
+};
+//#endregion
+//#region src/services/postgres/postgres.adapter.d.ts
+type PostgresOptions = {
+  /** Override image. */
+  image?: string;
+  /** Override environment variables. */
+  env?: Record<string, string>;
+};
+declare class PostgresHandle implements DatabasePort, ServiceHandle {
+  readonly type = "postgres";
+  serviceName: null | string;
+  readonly defaultPort = 5432;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  readonly containerOptions: ContainerOptions;
+  connectionString: string;
+  private client;
+  private template;
+  private clone;
+  constructor(options?: PostgresOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  initialize(dockerDir: string): Promise<void>;
+  private getClient;
+  seed(sql: string): Promise<void>;
+  reset(): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  columns(table: string): Promise<string[]>;
+  isolation(): IsolationStrategy;
+  private closeClient;
+}
+/** Create a PostgreSQL service handle; its record key names the init script folder (`docker/<key>/init.sql`). */
+declare function postgres(options?: PostgresOptions): PostgresHandle;
+//#endregion
+//#region src/services/redis/redis.adapter.d.ts
+type RedisOptions = {
+  /** Override image. */
+  image?: string;
+};
+declare class RedisHandle implements ServiceHandle {
+  readonly type = "redis";
+  serviceName: null | string;
+  readonly defaultPort = 6379;
+  readonly defaultImage: string;
+  readonly environment: Record<string, string>;
+  readonly containerOptions: ContainerOptions;
+  connectionString: string;
+  private dbIndex;
+  /** What this handle holds: its slot's release, and the container's own string it extended. */
+  private pair;
+  constructor(options?: RedisOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+  private letGo;
+}
+/** Create a Redis service handle, reported under its record key. */
+declare function redis(options?: RedisOptions): RedisHandle;
+//#endregion
+//#region src/services/sqlite/sqlite-template.d.ts
+type SqliteOptions = {
+  /** Path to a SQL file initializing the schema; exclusive with `prismaSchema`. */
+  init?: string;
+  /** Path to a Prisma schema, resolved against the cwd and handed to `prisma db push --schema`; exclusive with `init`. */
+  prismaSchema?: string;
+};
+//#endregion
+//#region src/services/sqlite/sqlite.adapter.d.ts
+declare class SqliteHandle implements DatabasePort, ServiceHandle {
+  readonly type = "sqlite";
+  serviceName: null | string;
+  readonly defaultPort = 0;
+  readonly defaultImage = "";
+  readonly environment: Record<string, string>;
+  connectionString: string;
+  private db;
+  private templatePath;
+  private workerDbPath;
+  private readonly initSql;
+  private readonly prismaSchema;
+  private readonly options;
+  constructor(options?: SqliteOptions);
+  buildConnectionString(): string;
+  createDatabaseAdapter(): DatabasePort;
+  healthcheck(): Promise<void>;
+  /** One worker builds under an exclusive lock, the others wait: two concurrent `prisma db push` on one file is `database is locked`. */
+  initialize(_dockerDir?: string, root?: string): Promise<void>;
+  /** Built on a private path, then renamed into place: `prisma db push` writes the header long before the tables exist. */
+  private buildTemplate;
+  private writeTemplate;
+  private getDb;
+  private closeDb;
+  seed(sql: string): Promise<void>;
+  query(table: string, columns: string[]): Promise<unknown[][]>;
+  columns(table: string): Promise<string[]>;
+  reset(): Promise<void>;
+  isolation(): IsolationStrategy;
+}
+/** Create a SQLite service handle, isolated per test by file copy. */
+declare function sqlite(options?: SqliteOptions): SqliteHandle;
+//#endregion
+//#region src/services/process/process.adapter.d.ts
+/** The one shape an external process takes: `website({ server })`, `services: { api: process(...) }`, `serve:`. */
+type ProcessOptions = {
+  /** A one-shot command run once per specification before the spawn, which must exit 0. */
+  before?: string;
+  /** Shell command that starts the process. Receives the chosen port as `PORT`. */
+  command: string;
+  /** Working directory, relative to the project root. Default: the root itself. A function is called when the process starts, once per file: a spec that lays a fresh project for each file returns the path it laid. */
+  cwd?: (() => string) | string;
+  /** Environment on top of the runner's; a function receives the services already started. */
+  env?: ((services: Record<string, {
+    connectionString: string;
+  }>) => Record<string, string>) | Record<string, string>;
+  /** Fixed port. Default: an OS-assigned free port, injected as `PORT`. */
+  port?: number;
+  /** Readiness: a path polled until any HTTP status answers (`PORT` injected), or a regex over the output whose one group captures the port. */
+  ready?: RegExp | string;
+  /** Readiness budget in milliseconds. Default 30 000. */
+  timeout?: number;
+};
+declare class ProcessHandle implements ServiceHandle {
+  /** Embedded: nothing to pull, nothing to run in a container. */
+  readonly defaultImage = "";
+  readonly defaultPort = 0;
+  readonly environment: Record<string, string>;
+  readonly type = "process";
+  serviceName: null | string;
+  connectionString: string;
+  started: boolean;
+  private served;
+  private readonly options;
+  constructor(options: ProcessOptions);
+  buildConnectionString(host: string, port: number): string;
+  createDatabaseAdapter(): DatabasePort | null;
+  healthcheck(): Promise<void>;
+  initialize(): Promise<void>;
+  /** Isolation is the run's: one child per evaluation of the specification module, told apart by the minted id. */
+  isolation(): IsolationStrategy;
+  reset(): Promise<void>;
+  /** Spawn it and wait until it answers; `services` is every sibling, already started. */
+  spawnWith(root: string, services: Record<string, {
+    connectionString: string;
+  }>, runId: string): Promise<void>;
+  /** Terminate the process group. Idempotent. */
+  shutdown(): Promise<void>;
+  /** What it was declared as: what a specification reads to start it in a slot of its own. */
+  get spec(): ProcessOptions;
+  /** The base URL it came up on, known only once it is started. */
+  get url(): string;
+}
+/** Declare an external process the framework owns for the life of the specification. */
+declare function processService(options: ProcessOptions): ProcessHandle;
+//#endregion
+//#region src/services/seed/seed.capability.d.ts
+/** What `.seed()` takes: a `.sql` file, never the statements themselves: SQL is not written in a test. */
+type SeedSource = DiskFile<'.sql'>;
+type SeedMethod<Self, DatabaseKey extends string> = (source: SeedSource, options?: {
+  database?: DatabaseKey;
+}) => Self;
+type SeedChain<Self, DatabaseKey extends string> = {
+  /** Queue a SQL seed (`file('./__seeds__/<name>.sql')`) to run before the action. */
+  seed: SeedMethod<Self, DatabaseKey>;
+};
+interface SeedSignature extends ChainSignature {
+  readonly chain: SeedChain<this['self'], this['params']['databaseKey']>;
+}
+//#endregion
+export { Intersect as A, IsolationStrategy as C, Armed as D, AnyCapability as E, ChainContext as F, EnvRecord as I, ChainConfig as L, Run as M, Sharing as N, Capability as O, SpecificationParams as P, ServiceHandle as S, ActionOption as T, directory as _, processService as a, ServiceRecord as b, RedisOptions as c, postgres as d, DiskDirectory as f, RelativePath as g, FileAt as h, ProcessOptions as i, MatrixRow as j, ChainSignature as k, redis as l, DiskTarget as m, SeedSource as n, sqlite as o, DiskFile as p, ProcessHandle as r, SqliteOptions as s, SeedSignature as t, PostgresOptions as u, file as v, DatabasePort as w, ServicesConfig as x, DatabaseKeys as y };
+//# sourceMappingURL=shared-index.services.d.ts.map

package/dist/shared-index.stubs.d.ts

@@ -0,0 +1,287 @@
+//#region src/stubs/exchange.d.ts
+/** An observed outgoing request, reduced to what stub matchers inspect. */
+type MatchableRequest = {
+  /** Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent. */
+  body: unknown;
+  /** Request headers, keyed by lowercased header name. */
+  headers: Record<string, string>;
+  /** Uppercased HTTP method of the observed request. */
+  method: string;
+  /** The request URL: fully-qualified, or origin-relative for the stub backend. */
+  url: string;
+};
+/** The request half of a stub: an absolute URL, or a path form (`/articles/{{uuid}}`) matching any origin. */
+type StubRequest = {
+  /** Adapter name: `http` | `openai` | `anthropic`. */
+  adapter: string;
+  /** HTTP method to match. `*` matches any method. */
+  method: string;
+  /** Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`). */
+  url: RegExp | string;
+  /** Optional request matcher; the stub only fires if this returns true. */
+  match?: ((request: MatchableRequest) => boolean) | undefined;
+  /** Header names, case-insensitive, whose presence keeps the stub from firing; `http.*` writes them from `without.headers`. */
+  absentHeaders?: readonly string[] | undefined;
+  /** Transform raw data into a provider-specific response envelope. */
+  wrap: (data: unknown) => StubResponse;
+};
+/** The response half of a stub. */
+type StubResponse = {
+  /** HTTP status code (default: 200). */
+  status?: number;
+  /** Response body: an object is JSON, a string text, `null` empty, a `StreamBody` arrives in pieces. */
+  body: unknown;
+  headers?: Record<string, string> | undefined;
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number | undefined;
+  /** A transport failure instead of a reply: `fetch` rejects, as no status code can express. */
+  transport?: 'network-error' | undefined;
+};
+/** Each adapter serialises an object as JSON, so a stream declared as a plain value would arrive as `{}`: the tag tells them apart. */
+declare const STREAM_BODY = "@jterrazz/test:stream";
+/** A body that arrives in pieces, as `http.stream()` and `http.sse()` build it. */
+type StreamBody = {
+  /** The pieces, written in order. */
+  chunks: readonly string[];
+  /** The `content-type` the stream is served under. */
+  contentType: string;
+  /** Milliseconds between two chunks. Default 0: everything at once. */
+  delayBetweenChunks: number;
+  kind: typeof STREAM_BODY;
+};
+/** A response computed from the observed request at serve time. */
+type StubResponder = (request: MatchableRequest) => StubResponse;
+/** A fixed `StubResponse`, or a `StubResponder` evaluated per served request. */
+type StubResponseValue = StubResponder | StubResponse;
+//#endregion
+//#region src/stubs/stub.d.ts
+/** A declared external interaction: what to match and what to reply. */
+type Stub = {
+  /** Which outgoing call this stub speaks for. */
+  request: StubRequest;
+  /** A fixed reply, or a function of the observed request. */
+  response: StubResponseValue;
+  /** How many times it may serve; omitted is unlimited. `0` with `required` is a never stub: docs/reference/stubs.md#never-a-call-that-must-not-happen. */
+  times?: number;
+  /** Fail the chain unless it was requested: exactly `times` times when set, so `times: 0` fails it once requested. */
+  required?: boolean;
+};
+/** A composite of stubs; `.with()` derives a variant without touching the original. */
+type Stubs = {
+  /** The flattened stubs, in selection order. */
+  readonly stubs: readonly Stub[];
+  /** Overrides replace base stubs of the same route and are prepended, so a more specific override wins first match. */
+  with: (...overrides: (Stub | Stub[] | Stubs)[]) => Stubs;
+};
+/** Any accepted stub input: one, a list, or a composite. */
+type StubInput = Stub | Stub[] | Stubs;
+declare function defineStub(stub: Stub): Stub;
+/** Compose stubs, lists and composites, order preserved; `.with()` derives a scenario. */
+declare function defineStubs(...items: StubInput[]): Stubs;
+//#endregion
+//#region lint/kit/project/tokens.d.ts
+declare const TOKEN_KINDS: readonly ["any", "base64", "date", "duration", "email", "float", "hex", "int", "ip", "iso8601", "number", "path", "port", "semver", "sha", "string", "time", "ulid", "url", "uuid", "workdir"];
+type TokenKind = (typeof TOKEN_KINDS)[number];
+//#endregion
+//#region src/expectations/tokens/match.d.ts
+/** The frozen token vocabulary (rule `no-unknown-token`) plus the code-only kinds. */
+type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+/** A dynamic-value matcher, created through the `match` factories. */
+declare class Matcher {
+  /** For kind 'includes': the substring the actual value must contain. */
+  readonly includes?: string | undefined;
+  readonly kind: MatcherKind;
+  /** For kind 'ref': the capture to assert inequality against. */
+  readonly notRef?: string | undefined;
+  /** For kind 'ref': the capture name. */
+  readonly refName?: string | undefined;
+  /** For kind 'regex': the pattern the actual value must match. */
+  readonly regex?: RegExp | undefined;
+  constructor(kind: MatcherKind, options?: {
+    includes?: string | undefined;
+    notRef?: string | undefined;
+    refName?: string | undefined;
+    regex?: RegExp | undefined;
+  });
+  /** Placeholder-style rendering used in failure diffs and serialization. */
+  toString(): string;
+  toJSON(): string;
+}
+type TypedMatcher = () => Matcher;
+/** Dynamic-value matchers, the code-side mirror of the `{{token}}` grammar (`no-unknown-token`). */
+type MatchFactories = Record<TokenKind, TypedMatcher> & {
+  includes: (substring: string) => Matcher;
+  ref: (name: string, options?: {
+    not?: string;
+  }) => Matcher;
+  regex: (regex: RegExp) => Matcher;
+};
+declare const match: MatchFactories;
+//#endregion
+//#region src/stubs/kinds/text-filter.d.ts
+/** A text filter on a provider request builder: a string is exact, a `RegExp` or `match.*` loosens it. */
+type TextFilter = Matcher | RegExp | string;
+//#endregion
+//#region src/stubs/kinds/anthropic.d.ts
+type AnthropicMessagesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+/** Init options for a streamed Anthropic reply. */
+type AnthropicStreamInit = {
+  /** Milliseconds between two events. Default 0: every event at once. */
+  delay?: number;
+};
+/** Anthropic API stub helpers. */
+declare const anthropic: {
+  /** Match Messages API calls, optionally through a gateway URL; a string filter is exact equality. */
+  messages(filter?: AnthropicMessagesFilter, url?: string): StubRequest;
+  /** A stub the chain fails on if the subject reaches this endpoint: `http.never()`. */
+  never(request: StubRequest): Stub;
+  /** Response: data wrapped in the Messages format. */
+  reply(data: unknown): StubResponse;
+  /** Response: the text streamed as server-sent events, one `text_delta` per piece. */
+  stream(pieces: readonly string[], init?: AnthropicStreamInit): StubResponse;
+  /** Response: return an Anthropic error. */
+  error(status: number, message?: string): StubResponse;
+  /** Response: simulate a timeout. */
+  timeout(): StubResponse;
+};
+//#endregion
+//#region src/stubs/kinds/http-filter.d.ts
+/** Request filters; a request matches when every provided field matches. */
+type HttpStubFilter = {
+  /** An object is a deep subset match (leaves may be `match.*`); a string is containment, a RegExp `test()`s the raw body. */
+  body?: object | RegExp | string;
+  /** Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`. */
+  headers?: Record<string, RegExp | string>;
+  /** Query-param subset. string = exact value, RegExp = `test()`. */
+  query?: Record<string, RegExp | string>;
+  /** Headers the request must not carry; a name present with any value keeps the stub from firing. */
+  without?: {
+    headers?: readonly string[];
+  };
+};
+//#endregion
+//#region src/stubs/kinds/http.d.ts
+/** Init options for a streamed reply. */
+type HttpStreamInit = {
+  /** The `content-type` the stream is served under. Default `application/octet-stream`. */
+  contentType?: string;
+  /** Milliseconds between two chunks. Default 0: every chunk at once. */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. Default 200. */
+  status?: number;
+};
+/** One server-sent event, as `http.sse()` frames it. */
+type SseEvent = {
+  /** The `data:` payload. An object is serialised as JSON; a string is sent as-is. */
+  data: unknown;
+  /** The `event:` name. Omitted for an unnamed (default `message`) event. */
+  event?: string;
+  /** The `id:` the client echoes as `Last-Event-ID` when it reconnects. */
+  id?: string;
+  /** The `retry:` hint, in milliseconds. */
+  retry?: number;
+};
+/** Init options shared by the response builders. */
+type HttpResponseInit = {
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. */
+  status?: number;
+};
+/** Generic HTTP stub helpers: an absolute URL, or a path form (`/articles/{{uuid}}`) matching any origin. */
+declare const http: {
+  any(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  delete(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  get(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  patch(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  post(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  put(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  /** A stub the chain fails on if the subject reaches its route: `required` with `times: 0`. */
+  never(request: StubRequest): Stub;
+  /** Response: a body-less reply (204 by default). */
+  empty(status?: number): StubResponse;
+  /** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+  error(status: number, body?: unknown): StubResponse;
+  /** Response: a JSON body (200 by default). */
+  json(body: unknown, init?: HttpResponseInit): StubResponse;
+  /** Response: no response at all; `fetch` rejects, as when no server is running. */
+  unreachable(): StubResponse;
+  /** Response: a body that arrives in pieces, written in order. */
+  stream(chunks: readonly string[], init?: HttpStreamInit): StubResponse;
+  /** Response: a server-sent event stream, served as `text/event-stream`. */
+  sse(events: readonly SseEvent[], init?: Omit<HttpStreamInit, "contentType">): StubResponse;
+  /** Response: a text body, served as `text/plain` (200 by default). */
+  text(body: string, init?: HttpResponseInit): StubResponse;
+};
+//#endregion
+//#region src/stubs/kinds/openai.d.ts
+type OpenAIChatFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+  temperature?: number;
+};
+type OpenAIResponsesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+type OpenAIStreamInit = {
+  /** The API whose stream is served: Chat Completions (default) or Responses. */
+  api?: 'chat' | 'responses';
+  /** Milliseconds between two events. Default 0: every event at once. */
+  delay?: number;
+  /** The tokens the stream reports it spent: a Chat Completions stream ends on a usage chunk, as `stream_options.include_usage` asks, and a Responses stream carries them in its completed response. Default 10 and 10. */
+  usage?: {
+    completionTokens: number;
+    promptTokens: number;
+  };
+};
+/** OpenAI API stub helpers. */
+declare const openai: {
+  /** Match Chat Completions calls, at `url` where the client reaches another host; a string filter is exact equality, a RegExp or `match.includes` loosens it. */
+  chat(filter?: OpenAIChatFilter, url?: string): StubRequest;
+  /** Match Responses API calls; a JSON file is wrapped in the Responses envelope. */
+  responses(filter?: OpenAIResponsesFilter, url?: string): StubRequest;
+  /** A stub the chain fails on if the subject reaches this endpoint: `http.never()`. */
+  never(request: StubRequest): Stub;
+  /** Response: data wrapped in the Chat Completions format. */
+  reply(data: unknown): StubResponse;
+  /** Response: the text streamed as server-sent events; `api` picks Chat Completions (default) or Responses. */
+  stream(pieces: readonly string[], init?: OpenAIStreamInit): StubResponse;
+  /** Response: return an OpenAI error. */
+  error(status: number, message?: string): StubResponse;
+  /** Response: return malformed content. */
+  malformed(content: string): StubResponse;
+  /** Response: simulate a timeout. */
+  timeout(): StubResponse;
+};
+//#endregion
+//#region src/stubs/intercept/intercept.d.ts
+/** Disposed at the end of the declaring scope: handlers dropped, an unmatched request thrown. */
+type InterceptScope = AsyncDisposable;
+/** What a scope may state about the network it declares. */
+type InterceptOptions = {
+  /** The base a relative request resolves against for the life of the scope; under node `fetch('/api/posts')` cannot parse. */
+  origin?: string;
+};
+/** The module-scope network double; awaited, so the network double listens before the subject runs. */
+type Intercept = ((stubs: StubInput, options?: InterceptOptions) => Promise<InterceptScope>) & ((request: StubRequest, response: StubResponder | StubResponse, options?: InterceptOptions) => Promise<InterceptScope>);
+//#endregion
+//#region src/stubs/delivery/same-process/intercept.d.ts
+/** The module-scope network double, on msw's node server. */
+declare const intercept: Intercept;
+//#endregion
+export { StubRequest as C, StubResponseValue as E, StreamBody as S, StubResponse as T, StubInput as _, openai as a, defineStubs as b, SseEvent as c, anthropic as d, TextFilter as f, Stub as g, match as h, InterceptScope as i, http as l, MatcherKind as m, Intercept as n, HttpResponseInit as o, Matcher as p, InterceptOptions as r, HttpStreamInit as s, intercept as t, HttpStubFilter as u, Stubs as v, StubResponder as w, MatchableRequest as x, defineStub as y };
+//# sourceMappingURL=shared-index.stubs.d.ts.map

package/dist/shared-json-shape.js

@@ -0,0 +1,17 @@
+//#region lint/kit/project/json-shape.ts
+/** `JSON.parse` answers `any`: these read a parsed value field by field, and a field of another shape reads as absent. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** What a text that is no JSON stands for is the caller's to say. */
+function parsedJson(text, otherwise) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return otherwise;
+	}
+}
+//#endregion
+export { parsedJson as n, isRecord as t };
+
+//# sourceMappingURL=shared-json-shape.js.map